Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

SAM-protocol/SAM-Protocol

Repository files navigation

# SAM Protocol **The Signed Envelope for Agent-Ready Merchants** [![Status: Draft](https://img.shields.io/badge/status-draft-orange.svg)](docs/SAM_Protocol_WhitePaper_v2_2_EN.md) [![Version: 2.2](https://img.shields.io/badge/version-2.2-blue.svg)](docs/SAM_Protocol_WhitePaper_v2_2_EN.md) [![Spec: draft-sam-protocol-v2.2](https://img.shields.io/badge/spec-draft--sam--protocol--v2.2-lightgrey.svg)](docs/SAM_Protocol_Normative_OnePager.md) [![License: Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-green.svg)](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).

About

The Trust and Mandate Layer for Agentic Commerce — open standard (draft-sam-protocol-01). Merchant-ready. Agent-ready. Bounded autonomy.

Topics

Resources

License

Contributing

Stars

Watchers

Forks

Packages

Contributors

AltStyle によって変換されたページ (->オリジナル) /