diff --git a/README.md b/README.md index 5a4b3be..ed6239f 100644 --- a/README.md +++ b/README.md @@ -375,9 +375,18 @@ If you're implementing a new language port, **start from the fixtures, not the s ## Where to go next +[`references/`](references/README.md) is the open-source home for executable +integrations with agent frameworks, transports, and runtimes. These profiles +prove interoperability and document the receiver-side trust boundary. They do +not replace **Ratify Verify**, the managed commercial surface for production +trust configuration, revocation, policy, audit, observability, availability, +and supported deployment adapters. Both use the same portable protocol and +verification semantics—there is no managed-only wire format. + | You want to… | Go to | |---|---| | **Run the demo and see the protocol work** | [`demos/README.md`](demos/README.md) | +| **See integrations with specific agent platforms** | [`references/README.md`](references/README.md) | | **See the measured performance numbers** | [`docs/BENCHMARKS.md`](docs/BENCHMARKS.md) | | **Understand the threat model** | [`docs/EXPLAINED.md`](docs/EXPLAINED.md) | | **Read the normative spec** | [`SPEC.md`](SPEC.md) | @@ -441,6 +450,8 @@ ratify-protocol/ │ ├── demos/ End-to-end narrative demos: go/ python/ typescript/ rust/ │ +├── references/ Platform-specific profiles, threat models, and executable gates +│ └── docs/ ├── EXPLAINED.md Architecture + threat model + real-time patterns ├── AGENT_TO_AGENT.md A2A patterns (mutual auth, sub-delegation, receipts) diff --git a/docs/EXPLAINED.md b/docs/EXPLAINED.md index 3ff17ce..66427ef 100644 --- a/docs/EXPLAINED.md +++ b/docs/EXPLAINED.md @@ -112,11 +112,19 @@ a runtime dependency. A bundle moves freely across all five SDKs. Where verifiers differ is in operational surface — latency, compliance posture, integration ergonomics — not in cryptography. -### Surface adapters (out of scope for this repository) - -The integration code that turns a `ProofBundle` into a "Zoom auth gate," "Twilio SIP attestation," "AWS API Gateway authorizer," etc. — the **surface adapters** — lives in separate repositories (`ratify/zoom-sdk`, `ratify/voice-sdk`, …). Those are the home of proprietary "last-mile" integration code and are not addressed by this specification. - -The protocol's contract stops at the `ProofBundle` wire format and the verifier algorithm. Anything above that — how a third-party platform's signaling layer is intercepted, how middleware is wired into a specific framework, how an incumbent product's auth model is mapped onto Ratify scopes — is integration work, not protocol work. Ratify Verify ships those adapters as commercial product; the specification does not prevent a third party from writing their own. +### Open references and managed surface adapters + +Open, executable profiles under [`references/`](../references/README.md) show how +Ratify composes with specific agent frameworks, transports, and runtimes. They +are interoperability references: inspectable patterns, deterministic gates, +and evidence—not hosted services or production support commitments. + +The protocol contract stops at the `ProofBundle` wire format and verifier +semantics. Production last-mile adapters—such as supported Zoom, Twilio, or API +gateway deployments—plus managed trust configuration, revocation, policy, +audit, observability, and availability belong to Ratify Verify's commercial +surface. Ratify Verify does not introduce a proprietary proof format, and the +specification does not prevent anyone from building or operating an adapter. --- diff --git a/references/README.md b/references/README.md new file mode 100644 index 0000000..97ff0a1 --- /dev/null +++ b/references/README.md @@ -0,0 +1,42 @@ +# Ratify reference profiles + +Reference profiles show how Ratify composes with a specific agent framework, +transport, runtime, or platform without changing the Ratify verifier contract. +They are larger and more platform-specific than the small examples in +[`demos/`](../demos/README.md). + +These are open-source interoperability references, not hosted services or +production support commitments. They make the integration pattern inspectable, +portable, and reproducible. **Ratify Verify** is the separate managed commercial +surface for operating the same protocol at scale: managed trust configuration, +revocation, policy, audit retention, observability, availability, and supported +deployment adapters. The proof bytes and verifier semantics remain portable; +customers choose whether to operate them themselves or use the managed service. + +Every accepted profile should contain: + +- an explicit trust boundary and layer-separation statement; +- exact tested dependency versions; +- a deterministic path that does not depend on model judgment; +- adversarial allow/deny cases with protected-handler invocation evidence; +- a one-command published-package gate; +- limitations and non-goals; +- evidence generated from executed tests, not projected results; and +- a disclosure of endorsement, partnership, and standardization status. + +## Registry + +| Profile | Status | Ratify version | Platform version | Gate | +|---|---|---|---|---| + +## Lifecycle + +Profiles begin as independent drafts on feature branches. Passing tests do not +make a profile official for the named platform. The registry entry must state +whether a platform reviewed, contributed to, or endorsed the work. + +A profile remains in this repository while Ratify owns its maintenance and it +shares the protocol release cadence. It may move to a dedicated or jointly +maintained repository when it needs independent releases, external maintainers, +or partner-owned governance. A move should leave a compatibility pointer at the +old path so public evidence links do not silently break.