# SAM Protocol **The Signed Envelope for Agent-Ready Merchants** [](docs/SAM_Protocol_WhitePaper_v2_2_EN.md) [](docs/SAM_Protocol_WhitePaper_v2_2_EN.md) [](docs/SAM_Protocol_Normative_OnePager.md) [](LICENSE) > *Publish one signed file. Reference everything else.* SAM is an **open standard** for a signed, time-bounded envelope that a merchant publishes at `https:///.well-known/sam.json`. The envelope declares the merchant's identity, references the agent-facing standards the merchant publishes (UCP, AP2, MCP, ACP, A2A), declares a merchant-issued policy mandate bounding autonomous action, and provides a structured human-escalation path. SAM does not replace UCP, AP2, MCP, ACP, or A2A. SAM is the **signed envelope** that makes any combination of them verifiable in one place. --- ## Why SAM exists The agentic commerce stack of 2026 is fragmented across roughly a dozen specifications, none of which signs the others, and none of which can serve as a single point of verifiable entry. Four concrete problems for agents: - **Which `.well-known/` URL is authoritative for this merchant?** - **Is the published configuration current?** Most standards have no freshness window. - **Is the configuration genuine?** TLS proves the channel, not the document. - **Within which bounds may the agent act, regardless of which protocol is used downstream?** A SAM-conformant merchant publishes one signed file. An agent reads it, verifies an `ed25519` signature over the entire envelope including its references (RFC 9421), and acts only within the merchant policy mandate declared inside. **One file. One signature. One grammar. One fallback.** --- ## How SAM composes | Layer | Standard | Question resolved | |---|---|---| | Signed entry | **SAM** | *Who is this merchant, what do they publish, is it current, is it genuine, within which bounds?* | | Capabilities | UCP | What can be browsed, quoted, ordered? | | User authorization | AP2 (FIDO) | Did the user authorize this purchase? | | Tool invocation | MCP | How does the agent call a specific function? | | Catalog feed | ACP | What is in stock, at what price? | | Agent-to-agent | A2A | How do two agents collaborate? | A merchant already on UCP adopts SAM in ten lines: a `sam:composes.ucp` entry, a signature, a freshness window. No rewrite. No duplication. No fork. --- ## Documents - **[White Paper v2.2 (current)](docs/SAM_Protocol_WhitePaper_v2_2_EN.md)** — The Signed Envelope for Agent-Ready Merchants. Composition thesis, normative core, security model, adoption roadmap. - **[Normative One-Pager v2.2](docs/SAM_Protocol_Normative_OnePager.md)** — RFC 2119 conformance requirements. What an implementer MUST, SHOULD, and MAY do. - **[Technical Appendix](docs/SAM_Protocol_Technical_Appendix.md)** — Python implementation snippets for manifest verification, mandate evaluation, RFC 9421 request signing, and operator key resolution. - **[W3C CG Submission](docs/SAM_W3C_CG_CallForParticipation.md)** — Proposal to incubate SAM at the W3C Agent Identity Registry Protocol Community Group. - *(Archived)* [White Paper v2.1](docs/SAM_Protocol_WhitePaper_v2_1_EN.md), [v1.0](docs/SAM_Protocol_WhitePaper_v1_0_EN.md). --- ## Schemas and test vectors - **[`schemas/sam.json.schema.json`](schemas/sam.json.schema.json)** — Normative JSON Schema (Draft 2020-12) for the SAM envelope, v2.2. - **[`examples/`](examples/)** — Valid and invalid test vectors. - `valid/composing-envelope.json` — UCP-equipped merchant, references UCP + AP2 + MCP under signature. - `valid/bootstrap-envelope.json` — Merchant without UCP, declaring local capabilities. - `valid/l0-starter.json` — Five-minute starter envelope. - `invalid/*.json` — Test vectors illustrating each structural and runtime failure mode. Validate with `jsonschema` (Python) or `ajv-cli` (Node). See `examples/README.md`. --- ## MCP Server A reference Model Context Protocol (MCP) server for SAM Protocol is published in [`mcp-server/`](mcp-server/). It exposes seven tools (verify, validate, evaluate, fetch composed, resolve operator, generate, sign) over stdio, with TypeScript + `ed25519` + Zod. Install via `cd mcp-server && npm install && npm run build`, then point any MCP client at `dist/index.js`. See [`mcp-server/README.md`](mcp-server/README.md). --- ## Conformance levels | Level | Required content | Claim | |---|---|---| | **L0** | `version`, `capabilities` or `composes`, `human` | merchant-ready | | **L1** | L0 + `identity`, `signature` | agent-ready | | **L2** | L1 + `mandate`, `agentAuth` | bounded autonomy | Conformant agents **MUST NOT** perform autonomous economic actions against a merchant below L2. --- ## Constitutional rules 1. No autonomy without proof. 2. No proof without signature. 3. No execution without bounds. 4. No bounds without local enforcement. 5. No signature is valid forever — only within its declared freshness window. --- ## Contributing See [CONTRIBUTING.md](CONTRIBUTING.md). The specification is incubated openly. Issues, pull requests, and challenges to the design are welcome. A formal submission to the **W3C Agent Identity Registry Protocol Community Group** (chartered April 2026) is described in [the CG submission note](docs/SAM_W3C_CG_CallForParticipation.md). ## License Apache License 2.0 — see [LICENSE](LICENSE).