Everything that is in the Vouch Protocol repo, in plain English.

Vouch is a digital signature layer for AI agents. When your agent does something on your behalf (sends an email, transfers money, files a claim, queries a database), Vouch lets it cryptographically sign that action so anyone, anywhere, can later prove who did what and with whose permission.

Think of it as a tamper-proof receipt for every move an autonomous AI makes. The receipt is human-readable, cryptographically signed, and works across whatever framework you use to build agents (LangChain, CrewAI, MCP, anything).

AI agents are doing real work now: they submit insurance claims, place trades, file regulatory reports, access patient records. When something goes wrong (and eventually something will), you need to know exactly which agent took which action, who authorized it, and whether the agent had permission.

The tools we built for humans (API keys, login sessions, OAuth tokens) were not designed for this. They prove someone has access. They don't prove what the agent intended to do, who delegated the action down to it, or whether the agent is still behaving correctly.

Vouch fixes this by turning every agent action into a signed receipt. Identity, intent, target, and the chain of permissions are all cryptographically bound together. If your CFO asks "did our agent really wire that money?", you can prove it in seconds, with math, not log files.

Three big differences:

1. The agent owns its identity. With API keys, someone hands the agent a string. With Vouch, the agent generates its own cryptographic identity. Nobody, including the issuer, can impersonate it or take it away from afar.

2. Every action carries its intent. An API key just says "I'm allowed in." A Vouch credential says "I am Agent A, I want to submit *this specific claim* to *this specific URL*, at *this specific time*, and here is the chain of humans who approved it." Replaying the credential against any other resource literally cannot work.

3. Trust expires fast and renews continuously. A bearer token is good until someone remembers to revoke it. Vouch flips this: agents are untrusted by default and must renew their credentials on a heartbeat. If an agent goes silent (crashed, compromised, network split), its permissions expire on their own. No manual cleanup.

Yes, for what most teams need. Signing your agent's actions, verifying them anywhere, building permission chains between multiple agents, revoking compromised credentials, and being post-quantum ready: all shipped, all tested across Python, TypeScript, and Go, all have published test vectors. Build on it today.

The "continuous trust scoring" layer now ships in the Python SDK. That's the part where the credential's trust value decays over time, multiple validators can agree on whether your agent is behaving correctly while it's running, and a missed heartbeat is cryptographically detectable. The six new modules (trust entropy decay, behavioral attestation digest, canary commit/reveal chain, Merkle trees, heartbeat orchestration, validator quorum) animate the SessionVoucher format end-to-end. TypeScript and Go ports of these runtime pieces are not yet shipped; the data formats are already cross-language.

Vouch Shield, our optional runtime middleware that checks every tool call against your permission rules, is also production-ready (TypeScript library).

Vouch is a personal open-source project from Ramprasad Gaddam, an AI engineering director with 20+ years in regulated industries (healthcare, banking, manufacturing), 20 patents in cryptography and AI, and active membership in The Linux Foundation, C2PA, the Content Authenticity Initiative, DIF, and IEEE.

It is not affiliated with or endorsed by any employer.

To vouch for someone is to publicly stand behind them and take responsibility if they let you down. A Vouch credential does the same thing in code: an agent stands behind its own action, and the chain of people who delegated to it stands behind the agent.

Yes, fully free and open-source. Apache 2.0 for all code and the specification. CC0 (public domain) for the 55 design disclosures we've published. Use it in commercial products, fork it, sell things built on top of it. We just ask that you don't try to patent the ideas back at us.

Most people never need to. The FAQ and Guides cover everything you'll use day to day. But if you want the formal version, an executive summary is available here.

A DID (Decentralized Identifier) is a username your agent gives itself, backed by a cryptographic key only your agent holds. No registrar, no central authority can take it away.

Think of it like a passport you issue to yourself, where the passport's authenticity is proven by math, not by a government stamp. Vouch uses two flavours:

- did:web looks like did:web:agent.example.com and points to a small JSON file on your domain. Use this when you own a domain. - did:key looks like did:key:z6Mk... and the public key is baked into the identifier itself. Use this for quick experiments or self-contained agents that don't need a website.

A Verifiable Credential is a small piece of signed JSON that says "the holder of this DID claims X." For Vouch, X is something like "I, Agent A, am about to submit claim HC-001 to the insurance system at this URL."

The credential is signed by whoever issues it (the agent itself, a human delegator, or a validator). Anyone with the issuer's public key can verify the signature later. Tamper with even one character and the signature breaks.

A Vouch credential is just a Verifiable Credential with an intent field that pins down what the agent is doing and to what.

It is the cryptographic signature glued to the side of a Verifiable Credential. Vouch uses the Data Integrity mechanism, which keeps the credential as plain readable JSON and attaches the proof as a separate object next to it. You can open a Vouch credential in any text editor and read it.

By default Vouch uses Ed25519 (fast, well-known elliptic-curve signatures). If you need post-quantum protection, switch to the hybrid cryptosuite that signs with both Ed25519 *and* ML-DSA-44 (a NIST-approved post-quantum algorithm).

It is a fancy name for "write this JSON the exact same way every time." JCS (RFC 8785) gives every implementation the same recipe: sort keys alphabetically, format numbers the same way, no random whitespace. Same JSON in, same bytes out.

This matters because signatures are over bytes, not over abstract JSON. If your Python signs the credential but the bytes look different when TypeScript serializes the same data, the signature breaks. JCS makes that impossible. It is the reason a Vouch credential signed in Python can be verified in TypeScript or Go without any conversion.

It is a deployment trick that keeps your agent's private signing key away from the language model.

Here is the problem: your LLM-driven agent has tools, and a prompt-injection attack could trick it into leaking anything in its context window. If the private key is in that context, the attacker now controls your agent's identity.

The fix: run a small separate process (the "sidecar") that owns the key. When the agent wants to sign something, it asks the sidecar over a local connection. The sidecar signs, returns the credential, and never exposes the key to the LLM. Vouch ships a small Go binary you can run as the sidecar.

It is a dead-man's-switch for long-running agents. Every few minutes (you pick the interval) the agent has to actively renew its credentials. If it crashes, gets disconnected, or is taken over, the renewals stop and its permissions expire on their own. No human has to remember to revoke anything.

The credential format for these renewals ships today (it is called SessionVoucher). The runtime that actually drives the heartbeats and coordinates with multiple validators is on the roadmap, not built yet.

A chain of permission slips that tracks "who let whom do what." Imagine you tell your assistant "please book my flight." Your assistant tells an AI travel agent "please find flights." The travel agent tells a payment agent "please charge this card." Three steps, three permission grants.

A Vouch delegation chain captures all three steps cryptographically. Each step narrows the permission (the travel agent can find flights but not, say, sell your house). At the end, anyone looking at the action can walk the chain backward to the human who started it. "The AI did it" becomes "Person X delegated to assistant Y who delegated to agent Z, and here is each signed step." Real accountability.

One canonical Rust core does the cryptography once, and every language is a thin wrapper over it, so a credential signed on any platform verifies on every other, byte for byte (JCS canonicalization):

- Python: pip install vouch-protocol (the most complete: signer, verifier, async verifier, KMS, reputation, revocation, cache, rate-limit, metrics, CLI) - TypeScript and Go: the reference SDKs for Node and for the Identity Sidecar - Browser and Node.js (WebAssembly): npm install @vouch-protocol-official/core-wasm - .NET: dotnet add package VouchProtocol.Core - Swift (iOS and macOS), JVM (Java and Kotlin), and C/C++: native wrappers over the same core - HTTP API clients for the Bridge service: npm install @vouch-protocol-official/api-client or pip install vouch-api-client

Every implementation passes the same cross-language test vectors at test-vectors/.

Three lines after imports:

from vouch import Signer, build_vouch_credential

signer = Signer.from_did("did:web:agent.example.com")
credential = build_vouch_credential(
  subject_did="did:web:agent.example.com",
  intent={"action": "submit_claim", "target": "claim:HC-001",
      "resource": "https://insurance.example.com/claims/HC-001"},
  valid_seconds=300,
)
signed = signer.sign_credential(credential)

The signed dict has a proof object with a proofValue (z-base58 encoded Ed25519 signature) and verification metadata.

Use sign_credential_hybrid() instead of sign_credential(). The required pqcrypto library is bundled with vouch-protocol by default (since v1.6.0), so nothing else to install:

pip install vouch-protocol

Then:

from vouch import Signer, build_vouch_credential

signer = Signer.from_did_with_hybrid("did:web:agent.example.com")
signed = signer.sign_credential_hybrid(credential)

The resulting credential's proof field is an array of two Data Integrity proofs: one with cryptosuite: "eddsa-jcs-2022" (the classical Ed25519 proof) and one with cryptosuite: "mldsa44-jcs-2026" (the post-quantum ML-DSA-44 proof). Both proofs cover the same JCS-canonicalized credential bytes. Verifiers iterate the array and apply their local policy (validate either, validate both).

(The earlier v1.6.x reference implementation emits a single composite proof with cryptosuite: "hybrid-eddsa-mldsa44-jcs-2026" and a concatenated proofValue. That format is retained as a transitional alias; new implementations SHOULD emit dual proofs.)

You don't need to do anything special. JCS canonicalization guarantees byte-identical signed payloads across languages, so a credential signed in Python verifies correctly in TypeScript or Go (and vice versa).

from vouch import Verifier
verifier = Verifier()
result = await verifier.verify_credential(signed) # accepts credentials from any SDK

The published test vectors at test-vectors/hybrid-eddsa-mldsa44/ include a Python-generated signature that is exercised by both the TypeScript and Go test suites.

Only if you want the Identity Sidecar pattern, which is the recommended deployment for LLM-driven agents because it keeps the private key out of the LLM context window. If your code never exposes the key to the model (for example, a Python service signing on behalf of an agent), you can sign directly from the Python or TypeScript SDK.

The Go sidecar is also useful for polyglot stacks: it exposes POST /sign over HTTP, so any language can ask it to sign without having a Vouch SDK installed.

Pass the chain (list of credentials, principal first, agent last) to the verifier:

from vouch import Verifier
verifier = Verifier()
result = await verifier.verify_delegation_chain([principal_vc, agent_vc, sub_agent_vc])

The verifier walks every link, validates signatures, and confirms resource subset narrowing. If any link fails, the whole chain fails with a structured reason.

Attach a status entry when you issue it. That way, if you ever need to revoke it, you just flip a bit on a published list. Two steps: allocate an index from your status list, then pass a status entry to build_vouch_credential:

from vouch import (
  StatusList, build_status_list_entry, build_vouch_credential, Signer,
)

# Issuer maintains a single StatusList per status purpose (revocation or suspension).
status_list = StatusList(status_list_id="https://issuer.example/status/1")
index = status_list.allocate_index()

# Attach the status entry at issuance time.
status_entry = build_status_list_entry(
  status_list_credential="https://issuer.example/status/1",
  status_list_index=index,
)

credential = build_vouch_credential(
  issuer_did="did:web:issuer.example",
  intent={"action": "submit_claim", "target": "claim:HC-001",
      "resource": "https://insurance.example/claims/HC-001"},
  credential_status=status_entry,
)

signed = Signer.from_did("did:web:issuer.example").sign_credential(credential)

The TypeScript and Go SDKs expose the same API (buildStatusListEntry / BuildStatusListEntry) and accept credentialStatus / CredentialStatus on their credential builders.

Flip the bit at that credential's index in your status list, re-sign the BitstringStatusListCredential, and republish it:

status_list.revoke(index) # set the bit

status_credential = build_status_list_credential(
  issuer_did="did:web:issuer.example",
  status_list=status_list,
)
signed_status_credential = signer.sign_credential(status_credential)

# Publish signed_status_credential at the URL referenced by issued credentials.

Verifiers fetch the updated status credential, decode the bitstring, and observe that the bit is now set. The credential itself doesn't change; only the status list does.

Fetch the status list credential, then call verify_status with the credential's credentialStatus entry and the fetched list:

from vouch import StatusListFetcher, verify_status

fetcher = StatusListFetcher() # in-memory TTL cache, conditional GETs

status_credential = fetcher.get(
  signed["credentialStatus"]["statusListCredential"]
)

is_revoked = verify_status(
  credential_status=signed["credentialStatus"],
  status_list_credential=status_credential,
)

The fetcher caches by URL with a 5-minute default TTL and issues conditional GETs (If-None-Match, If-Modified-Since) so re-validation is cheap when the issuer hasn't updated the list. Set force_refresh=True on verification failure to handle stale-cache scenarios. TypeScript and Go callers can compose the equivalent with fetch() and net/http.Get() respectively.

Use the persistence API. to_state_dict() returns a JSON-serializable dict containing the encoded bitstring and the allocation cursor (next_index), which is NOT recoverable from the encoded list alone:

from vouch import FilesystemStatusListStore

store = FilesystemStatusListStore("/var/lib/vouch/status-1.json")

# After every allocate / revoke, persist.
store.save(status_list)

# On startup:
status_list = store.load()

FilesystemStatusListStore is a reference implementation with atomic temp-file + rename writes. Production deployments substitute Redis, Postgres, or S3 using the same state-dict API. Without persistence of next_index, an issuer restart would re-allocate already-used indices, silently overwriting prior revocations.

Python integrations live under vouch/integrations/:

- LangChain - tool wrapper that signs tool inputs before execution - CrewAI - tool wrapper for crew-style multi-agent flows - AutoGPT - command integration - AutoGen - tool wrapper - Streamlit - media-sealing UI helper - Vertex AI - Google Vertex AI tool - Google ADK - Agent Development Kit integration - Google APIs - generic Sheets/Docs/Drive integration - n8n - workflow automation node - Hasura - GraphQL webhook - MCP - Model Context Protocol server

Examples for each are in examples/05_integrations/.

TypeScript currently has the Amnesia bridge in packages/sdk-ts/src/integrations/.

Yes. pip install vouch-protocol installs the vouch command:

vouch init [--domain DOMAIN] [--env]  Generate keypair + DID, store securely
vouch credential sign [--hybrid]    Sign a Verifiable Credential
vouch credential verify         Verify a Verifiable Credential
vouch git init             One-command Git workflow setup
vouch git status            Show current Git config
vouch reputation get [--did DID]    Fetch reputation score
vouch revocation check [--did DID]   Check revocation status

The CLI source is at vouch/cli.py.

Source at browser-extension/. Manifest v3, Chrome / Edge / Brave compatible. Adds a "Sign with Vouch" context menu on selected text, a popup for identity selection and verification, and shortlink resolution via vch.sh.

Build artifacts (.crx, .zip) are produced by the GitHub Actions workflow at .github/workflows/build-extensions.yml.

Yes. mobile/expo-app/ is a React Native + Expo app supporting iOS and Android. It uses device-level Secure Enclave (iOS) and Android Keystore. Capture-time photo signing with EXIF preservation and a chain of trust linking to organizational credentials.

vouch/kms.py (16 KB) supports:

- Memory - in-process key storage (development only) - AWS KMS - via boto3 - GCP KMS - via google-cloud-kms - Azure Key Vault - via azure-keyvault - Local File - encrypted file storage with optional passphrase

The RotatingKeyProvider class handles automatic rotation by time or by validity period. KeyConfig is the dataclass that holds JWK, DID, key ID, and validity window.

vouch/revocation.py (449 lines) supports Memory and Redis backends out of the box, with an abstract RevocationStoreInterface for custom backends (HTTP remote registries, distributed key-value stores, etc.).

This is DID-level revocation (revoke a DID, all credentials under it become invalid). For credential-level revocation (revoke a single credential by index in a status bitstring), Vouch ships a BitstringStatusList implementation across all three SDKs (vouch.status_list in Python, packages/sdk-ts/src/status-list.ts in TypeScript, go-sidecar/signer/status_list.go in Go). The two mechanisms compose: BitstringStatusList for granular per-credential status, DID-level registry for "revoke everything from this compromised identity" scenarios.

vouch/reputation.py (711 lines) supports four backends:

- MemoryReputationStore - in-process dict - RedisReputationStore - via redis-py - KafkaReputationStore - event-sourced via Kafka topics - HTTP - remote reputation API

The engine implements exponential decay toward a baseline (default rate 0.1/day, kicks in after 7 days of inactivity), action deltas (success +1, failure -2, slash/boost configurable), and five-tier classification (untrusted < cautionary < neutral < trusted < exceptional).

Note: the Specification scope statement says reputation *algorithms* are not normative; the shipped engine is a reference implementation.

vouch/cache.py (9.4 KB) ships three cache backends: Memory (LRU), Redis (distributed), and Tiered (Memory + Redis fallback). The caches are used by the verifier to cache DID Document resolutions, public key lookups, and credential-status responses.

vouch/ratelimit.py (9.5 KB) implements token-bucket rate limiting backed by Redis (distributed) or Memory (local). Per-DID, per-IP, or per-tool buckets. Configurable burst capacity and refill rate.

For more aggressive primitives, PAD-047 describes a Verifiable Delay Function (VDF) approach where minimum elapsed wall-clock time is cryptographically self-evident without trust in any clock authority.

vouch/nonce.py (7 KB) tracks recently-seen credential nonces and rejects duplicates. Memory or Redis backed, with configurable TTL (default 300 seconds). The verifier consults the nonce store on every verification.

vouch/metrics.py (8.8 KB) emits Prometheus-compatible metrics:

vouch_signatures_total      counter
vouch_verifications_total     counter
vouch_verification_success_rate  gauge
vouch_verification_latency_seconds histogram
vouch_cache_hits         counter
vouch_cache_misses        counter
vouch_credential_issuances    counter
vouch_reputation_lookups     counter
vouch_revocation_checks      counter

OpenTelemetry exporters are optional via the [otel] extra.

The reputation engine's three-tier storage architecture is sized for 10K-50K RPS deployments per the CHANGELOG. Signing and verification throughput depends on the chosen cryptosuite (ed25519 is fast, hybrid PQ adds ML-DSA-44's ~3ms sign cost per operation on M-series hardware). For high-throughput verifier paths, use async_verifier (vouch/async_verifier.py, 16 KB) which supports concurrent verification with caching.

Build and run:

cd go-sidecar
go build ./cmd/vouch-sidecar
./vouch-sidecar --did did:web:agent.example.com --port 8877

The -s / --sensitive flag wraps the response in a JWE so the credential is encrypted in flight. The endpoint is POST /sign accepting a credential JSON body and returning the signed credential.

For containerized deployment, the Dockerfile is straightforward Go static binary in a scratch image.

Yes. Vouch Gatekeeper (github-app/, FastAPI, ~1000 lines) enforces cryptographic identity and organizational policy on every PR. Listens for pull_request.opened and pull_request.synchronize. Verifies commit signatures with GitHub SSH/GPG first, falls back to the Vouch Registry. Zero-config policy is "org member with signed commit = allow." Custom policy via .github/vouch-policy.yml. Shields.io badge endpoint at /api/badge/{owner}/{repo}. Auto-opens a PR to add the protection badge on installation.

Yes. cloudflare-worker/ provides signature storage and shortlink redirection. Shortlinks at vch.sh/{id} redirect to vouch-protocol.com/v/{id}. Free tier (1-year expiry) and Pro tier (no expiry). Cloudflare KV bindings for storage.

Vouch leaves media provenance to C2PA and works alongside it rather than reimplementing it. The c2pa-ca/ directory contains an active Certificate Authority that issues Ed25519-signed C2PA certificates and embeds CBOR manifests in image metadata. The audio path (vouch/audio.py, 38 KB) implements multi-layer Hamming(7,4) watermarks with psychoacoustic masking for audio signing.

Three operational pieces:

1. Issuer-side storage: Replace FilesystemStatusListStore (development) with a shared store so multiple issuer instances can coordinate. The state-dict API is backend-agnostic; common choices are Redis (SET status:1 <state-json>), Postgres (single row with UPDATE under SELECT FOR UPDATE), or S3 (with optimistic concurrency via ETags).

2. Status list publishing: Sign the BitstringStatusListCredential and serve it at a stable HTTPS URL, ideally with Cache-Control: max-age=... and ETag headers. The StatusListFetcher honors both. CDN-cacheable; the credential is public.

3. Verifier-side caching: The reference StatusListFetcher uses an in-memory cache, fine for single-process verifiers. For multi-instance verifier fleets, wrap it with a shared cache (Redis) so a revocation is visible across the fleet within one TTL window. On verification failure, set force_refresh=True to bypass the cache and pick up the latest list.

The protocol minimum is 131,072 bits (16 KiB uncompressed; ~50 bytes compressed when empty). That's enough for 131,072 credentials per status list. For larger issuers, allocate a new status list when you approach exhaustion; each credential's credentialStatus.statusListCredential URL identifies which list it belongs to.

Practical operational sizing: 131,072 credentials at a 5-minute validity (typical short-lived agent credentials) means a single list covers roughly one year at 0.4 credentials/minute, or one day at ~91/minute. Plan list rotation accordingly.

Vouch is not a HIPAA control by itself, no specification is. But Vouch provides the cryptographic primitives that map directly onto multiple HIPAA Technical Safeguards (45 CFR 164.312):

- Audit Controls (§164.312(b)) - every agent action is a non-repudiable signed credential - Integrity (§164.312(c)) - Data Integrity proofs detect any post-hoc modification - Person or Entity Authentication (§164.312(d)) - DIDs prove agent identity cryptographically - Transmission Security (§164.312(e)) - delegation chains plus optional JWE wrapping in the sidecar

For 21 CFR Part 11 (electronic records / electronic signatures), the same proofs satisfy the integrity and authenticity requirements.

SR 11-7 (Federal Reserve guidance on model risk management) and FFIEC AI guidance require a verifiable audit trail of model-driven decisions, the ability to attribute actions to specific model versions, and continuous monitoring of model behavior post-deployment.

Vouch addresses these through (a) intent-bound credentials with model-version metadata in the credential subject, (b) the Heartbeat Protocol for continuous post-deployment monitoring, and (c) reputation tracking and slashing for misbehavior detection. The docs/THREAT_MODEL.md maps Vouch primitives to SR 11-7 categories.

The EU AI Act (applicable from 2025) imposes auditability and human-oversight obligations on high-risk AI systems. Vouch's delegation chains provide a verifiable principal-to-agent-to-sub-agent audit trail. The intent attestation in every credential satisfies the "human-interpretable record of the model's decision" requirement for high-risk systems. The Heartbeat Protocol provides the continuous monitoring required under Article 14.

Yes, in two phases. The current revision ships an optional dual-proof post-quantum profile: pair the default eddsa-jcs-2022 Data Integrity proof with an additional mldsa44-jcs-2026 Data Integrity proof on the same credential, aligning with the NIST CNSA 2.0 phase-in. As CNSA 2.0 advances and regulator guidance matures, the dual-proof profile is expected to become RECOMMENDED for regulated sectors, then REQUIRED. Implementers operating in regulated sectors can adopt it today by passing --hybrid to the signer (the v1.6.x reference implementations still emit the transitional composite proof; the v1.7 rewrite emits dual proofs).

docs/THREAT_MODEL.md. It covers the trust boundaries (LLM context, sidecar, validator quorum, verifier), the attacker model (network adversary, compromised agent, compromised LLM, compromised key holder), and the mitigation each Vouch primitive provides.

Every action is a cryptographically signed credential whose signature can be verified by any third party with access to the agent's DID Document. The credential is human-readable JSON, so an auditor can inspect it directly without specialized tooling. Delegation chains preserve the audit trail from the human principal down to the executing agent.

If a dispute arises, the credential and its proof can be presented as evidence; the signature is independently verifiable without needing the issuer to cooperate.

Yes. 55 Prior Art Disclosures (PADs) published under CC0 1.0 Universal at docs/disclosures/. Each PAD documents an architectural pattern, threat model, or cryptographic primitive used in or adjacent to Vouch. The portfolio exists to establish prior art and prevent broad patents on Vouch's design decisions.

Vouch sits on top of well-known open specifications rather than inventing new cryptography:

- Verifiable Credentials 2.0, the JSON shape of a Vouch credential - Data Integrity proofs, how the cryptographic signature is attached - Decentralized Identifiers (DIDs), how agents identify themselves - Controlled Identifiers / Multikey, how public keys are encoded - BitstringStatusList, how individual credentials get revoked - RFC 8785 (JCS), the rule for serializing JSON the same way every time - NIST FIPS 204 (ML-DSA), the post-quantum signature algorithm - C2PA, Vouch acts as the identity layer for media provenance

Full mapping is documented in Appendix A of the Vouch Specification.

A Vouch credential is a Verifiable Credential. It uses the standard VC 2.0 JSON shape, the standard @context, the standard type, issuer, credentialSubject, and proof fields. The only Vouch-specific addition is an intent object inside credentialSubject that pins down the agent's action, target, and resource.

Any tool that knows how to read a VC can read a Vouch credential. It just will not know what to do with the intent field unless it has been taught.

Data Integrity is a way to attach a cryptographic signature to JSON in a readable form (instead of wrapping the whole credential in an opaque JWS blob).

Vouch uses two Data Integrity cryptosuites:

- eddsa-jcs-2022, the default classical Ed25519 cryptosuite - mldsa44-jcs-2026, the post-quantum ML-DSA-44 cryptosuite (provisional identifier, being aligned with Digital Bazaar's `mldsa44-rdfc-2024-cryptosuite` family's forthcoming JCS variant)

A credential can carry one proof (classical only) or two proofs (one of each cryptosuite, signing the same JCS-canonicalized bytes; this is the dual-proof post-quantum profile). The Data Integrity proof field is already specified as an array, so dual-signing is a natural use of existing primitives, no Vouch-specific composite cryptosuite required.

Every agent and every signer in Vouch has a Decentralized Identifier. Two DID methods are supported:

- did:web, resolves over HTTPS to a DID Document at your domain. Good for organizations that own a domain. - did:key, the public key is part of the identifier itself, no infrastructure needed. Good for ephemeral or fully decentralized agents.

Adding more DID methods (did:peer, did:dht, etc.) is straightforward when there is demand. Vouch is not opinionated about which method you use; it is opinionated that you use one.

Multikey is a format for encoding a public key with a small tag indicating which algorithm it belongs to. Vouch uses it because a single DID Document can then publish multiple keys side-by-side, one Ed25519 and one ML-DSA-44, for example, and verifiers pick whichever they support.

That is the trick behind the hybrid post-quantum profile: you can advertise both a classical key and a post-quantum key, sign credentials with both, and older verifiers (that only know Ed25519) still work fine. No flag day, no breakage.

BitstringStatusList is a mechanism for revoking individual credentials without invalidating everything an issuer ever signed. The idea: publish a compressed bitstring at a stable URL where each bit corresponds to one credential. To revoke a credential, flip its bit and republish. To check status, verifiers fetch the list and look at the right bit.

Vouch ships a reference implementation across Python, TypeScript, and Go, with a published cross-language test vector. Most issuers will pair this with the older "revoke an entire DID" model. BitstringStatusList is for granular per-credential status; the DID-level registry is for "this key was compromised, kill everything from this identity."

ZCAP-LD is another approach that tackles a similar problem: tracking who delegated which capability to whom. Vouch delegation chains share the same intent, but with different choices:

- Vouch uses JCS canonicalization (a deterministic byte-level recipe for serializing JSON); ZCAP-LD uses JSON-LD canonicalization. - Vouch requires every link in a chain to name a specific resource; ZCAP-LD is more open-ended about scope.

The two can interoperate; a future revision of the Vouch Specification may spell out the mapping in more detail.

JWS Compact Serialization wraps the entire credential in an opaque base64 blob. You cannot read it without decoding it first. Data Integrity keeps the credential as readable JSON and attaches the signature as a sibling object you can look at directly.

For agent actions where humans (auditors, regulators, your CFO) will read the credentials, readability matters. Earlier Vouch drafts experimented with JWS and moved away from it deliberately. JWS is still a valid signature envelope for VCs; Vouch just chose differently.

C2PA is the right approach for "where did this photo, video, or audio come from?", provenance for media. Vouch is the right layer for "which AI agent signed this, and with whose permission?", identity for the signer.

The two complement each other. The Vouch repo ships a small Certificate Authority that issues Vouch-rooted C2PA certificates, so a C2PA manifest can be signed by a Vouch-identified agent and the whole chain checks out. The editor sits on C2PA technical committees and the Content Authenticity Initiative; this composition is intentional.

Vouch is framework-agnostic, so it works with MCP servers and clients without anything special. An MCP tool-call envelope can carry a Vouch credential alongside the tool arguments. The MCP server (or a Vouch Shield middleware in front of it) verifies the credential before letting the tool run.

There is a reference MCP server integration in the Python SDK to make this concrete.

Standards-speak: normative means "if you say you implement this spec, you have to do X." Informative means "here is a useful description, but it is not part of the contract."

The Vouch credential layer (signing, verification, delegation, hybrid post-quantum, revocation) is normative. If you call yourself Vouch-compatible, you must implement these the same way as everyone else, byte for byte.

The State Verifiability layer (Heartbeat Protocol, validator quorum, behavioral attestation) was originally documented as informative, "here is the idea, implementations may vary." With the runtime now shipped in the Python SDK and being ported to TypeScript and Go, parts of that layer will become normative in a future revision of the Vouch Specification.

Yes. test-vectors/ has canonical test vectors for the hybrid post-quantum profile and for BitstringStatusList. Each comes with a deterministic generator script (generate.py) so anyone can regenerate it and audit the result.

Python, TypeScript, and Go all verify the same vectors. For BitstringStatusList specifically, Python and TypeScript produce byte-identical encoded output; Go produces a slightly different DEFLATE stream that decompresses to the same bitstring (semantically equivalent, which is what the the specification actually requires).

Tracked at ROADMAP.md. Headline items:

- Promote the State Verifiability runtime to fully normative once TypeScript and Go ports of the Python implementation land. - Expand the post-quantum profile from "hybrid Ed25519 + ML-DSA-44" to "pure ML-DSA" as NIST's CNSA 2.0 migration progresses and confidence in ML-DSA matures. - Federate the credential trust state across multiple validator quorums for multi-tenant deployments. - Propose the formal standards-track transition once we have enough implementer experience. - Publish a systems whitepaper on arXiv that synthesizes the full architecture, Vouch's cryptographic identity layer, Amnesia's deterministic policy layer, and the bridge between them, with empirical evaluation from six to twelve months of real-world usage data.

Eventually, a sufficiently powerful quantum computer will be able to break today's elliptic-curve signatures (Ed25519 included). We don't know when, but governments are already publishing migration deadlines (NIST CNSA 2.0, U.S. NSM-10). Even more importantly, an attacker can harvest signed credentials now and decrypt them later. So even before quantum computers exist, the smart move is to start signing things with both an old and a new algorithm so old signatures stay valid forever.

Each credential gets two Data Integrity proofs attached: one with the eddsa-jcs-2022 cryptosuite (today's classical Ed25519 algorithm, fast) and one with the mldsa44-jcs-2026 cryptosuite (the NIST-approved ML-DSA-44 post-quantum algorithm). Both proofs cover the same JSON bytes, and they ride together inside the credential's proof array.

A verifier can choose what to check:

- Old verifier? Validate the eddsa-jcs-2022 proof. Ignore the rest. Works today. - Forward-looking verifier? Validate the mldsa44-jcs-2026 proof. - Belt-and-suspenders verifier? Validate every proof in the array; fail if any one is wrong.

You can issue dual-proof credentials right now and they remain valid whether your verifier has been upgraded or not. No flag day, no mass migration, and no Vouch-specific composite cryptosuite to register, the dual-proof pattern uses standard W3C Data Integrity primitives.

Yes, but barely. On a modern laptop, signing with Ed25519 takes about 50 microseconds; adding the ML-DSA-44 proof on top brings total signing time to around 3 milliseconds. Verification is similar. The bigger trade-off is size: a classical-only credential is ~700 bytes; a dual-proof credential is ~3.2 KB. You will want to send credentials in HTTP bodies rather than headers.

Just call the hybrid signer. The pqcrypto library is bundled with vouch-protocol by default (since v1.6.0), so a plain pip install vouch-protocol gives you everything needed:

signer = Signer.from_did_with_hybrid("did:web:agent.example.com")
signed = signer.sign_credential_hybrid(credential)

TypeScript and Go work the same way. There is a full how-to in the Guides with code in all three languages.

The v1.6.x reference implementations emit the transitional composite proof (hybrid-eddsa-mldsa44-jcs-2026). The v1.7 rewrite emits two separate Data Integrity proofs on the same credential. The CLI flag stays the same.

ML-DSA-44, the smallest parameter set of NIST FIPS 204 (the standard published in 2024). It gives roughly the same security level as Ed25519 but against quantum attacks. Larger ML-DSA parameter sets (ML-DSA-65, ML-DSA-87) aren't wired in yet but the format leaves room for them.

Vouch Shield is a small TypeScript library that sits between your AI agent and the tools it tries to call. Before any tool runs, Shield checks: is this call signed? Is the signer on my trust list? Does this DID have permission to call this specific tool? If anything is off, the call is blocked and logged. If everything checks out, the call runs.

npm install @vouch-protocol/shield. Source: vouch-protocol/vouch-shield.

Think of Vouch Protocol as the passport: it defines how an agent proves who it is and what it intends to do. Vouch Shield is the customs officer: it inspects passports at the door and decides who gets through.

You can use Vouch Protocol without Shield (just sign and verify credentials in your own code). Shield is a convenience layer for teams who want the gatekeeping done for them.

Right before any tool actually executes. If your agent uses LangChain, CrewAI, AutoGen, MCP, or anything similar, Shield slots between "the LLM decided to call tool X" and "tool X actually runs." If the call doesn't pass Shield's checks, the tool never fires.

Most likely cause: the JCS canonicalization is not byte-identical. Check:

1. Are both ends on the same VC @context version? Mixing VC 1.1 and VC 2.0 contexts changes the canonical bytes. 2. Are timestamps in the canonical RFC 3339 form? Some implementations append +00:00 instead of Z for UTC. 3. Are numbers serialized as JCS specifies? Trailing zeros, scientific notation, or non-canonical fractions break JCS.

Run the credential through the JCS reference test vectors at test-vectors/ to isolate the issue.

Two possibilities depending on which version produced the credential:

- v1.7+ dual-proof credentials: the proof field is an array. A naive verifier might be reading only the first proof or expecting a single proof object. Make sure the verifier iterates the proof array and accepts any matching cryptosuite it recognizes (eddsa-jcs-2022 is the classical one). - v1.6.x transitional composite credentials: the proof.proofValue is a base58 concatenation of the Ed25519 signature (first 64 bytes) and the ML-DSA-44 signature (remaining ~2,420 bytes). A naive verifier that tries to validate the whole concatenated blob as Ed25519 will fail. Either upgrade the verifier to understand the hybrid-eddsa-mldsa44-jcs-2026 composite, or have the issuer emit dual proofs (v1.7+) and treat one of them as the classical proof.

pqcrypto (bundled with vouch-protocol since v1.6.0) ships prebuilt wheels for Python 3.9-3.13 on Linux x86_64/arm64, macOS x86_64/arm64, and Windows x86_64. On any of those, no compiler is needed.

If you are on a rare platform with no wheel, pip will fall back to building from source and you need a C toolchain:

- macOS: xcode-select --install - Ubuntu/Debian: apt install build-essential - Windows: install the "C++ build tools" workload from Visual Studio Installer

After that, pip install vouch-protocol succeeds.

Special case: if you genuinely cannot install pqcrypto at all (e.g. an extremely locked-down build environment), open a GitHub issue. A pure-Python ML-DSA-44 verifier (without signing) is on the roadmap for read-only environments.

1. Is port 8877 (or your configured port) free? netstat -an | grep 8877 2. Is your DID resolvable? curl https://agent.example.com/.well-known/did.json should return your DID Document. 3. Is your private key correctly placed (env var, KMS config, or file)?

Run with --verbose for detailed startup logs.

Common causes:

1. DID resolution failed - the verifier could not fetch the DID Document. Check network, TLS, and the .well-known/did.json URL. 2. Key not in DID Document - the signing key's verification-method ID is not in the DID Document's verificationMethod array. 3. Credential expired - validUntil is in the past. 4. Nonce already seen - the nonce store has a record of this credential's nonce. 5. Revoked at the DID level - the issuing DID is in the revocation registry. 6. Revoked at the credential level - the credential's credentialStatus bit is set in the fetched BitstringStatusListCredential.

The verifier returns structured reasons, not just "invalid"; check the error code.

Almost always cache TTL. The StatusListFetcher caches the status list credential by URL for 5 minutes by default. A revocation made at the issuer becomes visible to verifiers only after the cache expires (or sooner if the verifier sets force_refresh=True).

Two operational adjustments:

1. Shorten the TTL if your latency-to-revocation requirement is tighter than 5 minutes (StatusListFetcher(cache_ttl_seconds=60)). 2. Set `force_refresh=True` on verification failure so a credential that suddenly fails for any reason triggers a fresh fetch of its status list. This is the recommended way to handle stale caches.

For coordinated revocations across a verifier fleet, share the cache (Redis) so an invalidation in one verifier becomes visible to all of them immediately.

Privately via the process documented in SECURITY.md. Do not open public GitHub issues for vulnerabilities.

Three channels:

- GitHub issues for specification or implementation questions - Discord for community discussion and quick questions

Four surfaces, one canonical knowledge base, pick whichever fits the tool you already use:

- Claude Skill — a drop-in skill for Claude Code (the CLI). Reads your local repo, edits files, runs commands. Best for hands-on integration work. - Vouch Assistant — the chat helper on this website and the mobile app. Streams answers in your browser. Signs real Vouch credentials live so you can see the protocol in action. - OpenAI Custom GPT — a configuration you paste into ChatGPT's GPT builder. Optional Actions integration lets the GPT call the hosted assistant to sign for you. - Gemini Gem — a configuration for Google Gemini. Pairs naturally with Google Workspace (Docs, Sheets, Gmail, Search).

All four route to the same documentation, so the answers are consistent. Pick the one that fits your daily tool.

Two steps inside WSL bash, macOS, or Linux:

mkdir -p ~/.claude/skills
cp -r ~/vouch-protocol/claude-skill ~/.claude/skills/vouch-protocol

Restart Claude Code and run /skills to confirm. You should see vouch-protocol in the list. Read the Guides section "Installing the Vouch Claude Skill" for screen-by-screen steps and triggers.

The configuration is published in the repo at openai-gpt/. Open https://chatgpt.com/gpts/editor, click Create, switch to Configure, and paste each field from the matching file (name.txt, description.txt, instructions.md, conversation-starters.md). Upload all files from openai-gpt/knowledge/ to the Knowledge section. Optionally add the Actions integration using actions.yaml and actions-auth.md.

We do not host a shared GPT because Custom GPTs are tied to one OpenAI account and cannot be forked. Every team builds and owns its own version.

Open https://gemini.google.com/gems/create. Click New Gem. Paste name.txt, description.txt, and instructions.md from gemini-gem/ in the repo. Upload all files from gemini-gem/knowledge/. Add the prompts in examples.md as Examples. Save.

The Gem can use Google Workspace tools (drafting Docs, summarizing Sheets, composing Gmail). It always asks for confirmation before any Workspace write.

The chat helper you can open from "Ask the assistant" in the nav or the floating tab in the bottom-right. It answers questions about the protocol grounded in the canonical docs, and signs real Vouch credentials when you ask it to do something with consequences. The signed credential appears in the chat as a card with the issuer DID, intent, cryptosuite, and a Show raw JSON toggle.

The assistant is open source under website-agent/ in the repo. You can self-host it; the README has the local-run steps.

The LLM portion is vulnerable, like any LLM. Vouch's defense is defense-in-depth: the signing key lives in a sidecar process that the LLM cannot reach. Even a fully prompt-injected LLM cannot leak a key it never had, and the sidecar refuses to sign anything outside a small allow-list of action types. So the assistant can be tricked into saying weird things in chat, but cannot mint arbitrary credentials.

On this website, no. We pay the inference cost. For embedded use in your own product, you run the open-source backend yourself and supply your own LLM API key (Anthropic, OpenAI, or Google Gemini). The signing side is free; only the LLM provider charges for inference.

The Claude Skill, OpenAI GPT, and Gemini Gem are the Bring-Your-Own-LLM route: they run inside your existing AI subscription, so we never see your queries and you never pay us for inference.

Anthropic Claude, OpenAI GPT, and Google Gemini. Configure with VOUCH_LLM_PROVIDER=anthropic|openai|gemini and the matching API key. The hosted instance on this website uses Gemini today.

Claude Skill: git pull inside ~/.claude/skills/vouch-protocol/ whenever the protocol ships a new cryptosuite or SDK shape. Restart Claude Code; no further action.

OpenAI Custom GPT: in the GPT editor, replace the knowledge files (the builder deduplicates by filename). Bump the version note in the Instructions if you forked them.

Gemini Gem: same pattern — re-upload the knowledge files in the Gem editor.

All three follow the protocol's release cadence. Subscribe to releases on https://github.com/vouch-protocol/vouch.

A separate process that holds the agent's signing key. The LLM-running process calls it over HTTP for signatures. Because the key lives in a different process from the LLM, prompt injection cannot exfiltrate what is not there.

They are tiered. Pick by use case, not by language preference:

| Tier | Language | Use case | |---|---|---| | Production | Go | Real deployments. Small static binary, KMS / HSM keys, FIPS path in Pro tier. | | Lightweight | Python | Self-hosted, non-regulated stacks already in Python. File or env keys. | | Lightweight | TypeScript | Self-hosted Node stacks. File or env keys. | | Dev | Python `dev_sidecar` | Local iteration with an ephemeral key. Never for production. |

Rule of thumb: if your auditor will ask about the sidecar, run the Go one. For everything else, pick the language your stack already uses.

The sidecar is security-critical, so smaller code surface is safer. Python and TS sidecars implement the bare minimum to be useful (sign intents with Ed25519, return the credential) and intentionally leave out hybrid post-quantum, KMS integration, sensitive-mode JWE wrapping, Heartbeat validation, and multi-tenancy. When you need those, switch to the Go sidecar. That switch is the design intent, not a workaround.

Pick whichever runtime your existing application uses. There is no protocol-level difference; both pass the same contract test suite and emit semantically equivalent credentials.

Credentials are semantically equivalent across all three (same VC shape, same eddsa-jcs-2022 cryptosuite, same JCS canonicalization). A cross-language contract test suite enforces this on every release. The bytes are identical when the inputs are identical.

Yes for the Go sidecar — it is a static binary and starts in milliseconds. The Python and TS sidecars work as serverless too but their cold-start latency makes them less suited to high-frequency signing. For typical agent workloads (one credential per minute), any of them is fine.

Click the sun (or moon) icon in the top navigation. It flips between Light and Dark on each click. Your choice is remembered across visits and pages.

The site defaults to Light mode. If you want Dark, click the sun once.

It is back. Open the Blog link in the top nav. The nine articles were briefly off-site after the website redesign; all are now restored with the same content and updated styling.

Every code block has a small burgundy clipboard icon in the top-right corner. Click it and the entire snippet is copied to your clipboard. The icon briefly turns into a green checkmark to confirm.

This works on the homepage, in every guide, in blog posts, and inside the Vouch Assistant's responses.

Three ways:

1. Click Ask the assistant in the top navigation. 2. Click the small bordered tab labeled "ASK THE ASSISTANT" at the bottom-right of the page. 3. On mobile, tap "Ask the assistant" in the menu.

All three open the same slide-in panel. Inside the panel, use the diagonal-arrows icon in the panel's header to toggle between side-panel and full-screen mode.

Three things help:

1. Verify the answer against the canonical docs — every answer carries a disclaimer with links to the guides, FAQ, and the source on GitHub. 2. Report the bad answer at https://github.com/vouch-protocol/vouch/issues. Paste the question and the response. We update the knowledge base. 3. For protocol questions, the source on GitHub is the ground truth. The assistant is grounded in the docs but is still an AI and can be wrong.

Because real actions go through a signing gate. The assistant signs a Vouch credential for every action it takes on your behalf, and shows you the credential before performing the action. You can see exactly what is being authorized. If anything looks wrong, refuse the confirmation and the action does not happen.

After you scroll a bit, a small upward-arrow button appears in the bottom-left corner. Click it. Smooth scroll back to the top.