Skip to content
You are reading the Ratify Protocol v2 beta documentation. Protocol v1 remains available at the site root.

What's new in v2

2.0.0-beta.2 is the current beta of Ratify Protocol v2, a separately versioned protocol line for portable authority proofs. The first beta froze the v2 wire format and SDK API in Go, TypeScript, Python, Rust, and C. The current beta adds Swift for iOS and macOS and Kotlin for Android. Protocol v1 is unchanged and remains available.

v1 left freshness, status, and audit to local hooks, so a mutable local result could stand in for the Protocol result. v2 fixes the Protocol result and its signed receipt first. Application policy runs after release and can only narrow it.

  • Review so far is the project’s own pre-release security review of the specification, the shared vectors, and every SDK.
  • External independent review has not happened yet. It is a 2.0.0 gate, together with interoperability with at least one implementation outside the protocol repository and a recorded soak.
  • The beta carries no production security claim. The wire format and API are frozen, so code written against the beta carries to 2.0.0 without import changes.

Full notes, including the test evidence: release notes and changelog.

AreaProtocol v1 (1.0.0-alpha.21)Protocol v2 (2.0.0-beta.2)
SignaturesHybrid Ed25519 and ML-DSA-65 over canonical bytesSame algorithms. Both sign a domain-separated message carrying the object type code, and ML-DSA uses a fixed context per object type
Key IDs128-bit v1 IDFull 256-bit key_id_v2; trust is pinned by complete key, never by ID alone
NumbersFloats allowed in some constraintsIntegers only; amounts in micro-units (max_amount_micros)
DecisionVerify returns a statusA committed outcome, actionable only after release: receipt verified, checkpoint acknowledged, deadlines current
RevocationProvider callback, which may be unsigned or booleanSigned lists and pushes under a separate status key, applied through an anchored journal. An allow requires current status
AuditOptional receipts and audit hookA signed receipt for every terminal result, in a hash-chained log acknowledged by an independent checkpoint
ReplayOptional challenge storeA stored challenge and an atomic claim are required for a live decision
Custom scopescustom: accepted as a required scopeOne exact custom: scope, listed by every certificate in the chain; custom:* is invalid
ConstraintsBuilt-in types including geo and speed, plus a local evaluator hookA closed registry of five types plus registered evaluator profiles whose digests are signed into the receipt
Geo and speedSupportedPlanned for 2.1
Session fast pathSessionTokenPlanned for 2.1
Agent-to-agent mutual presentationDocumented patternPlanned for 2.1
HTTP and registry bindingsSpecifiedPlanned for 2.1
ExpiryNo-expiry sentinel allowedFinite expiry, at most ten years
LimitsDepth and identifier limitsPer-object byte limits checked before parsing
Deployment profilesMiddleware custodySingle-device offline, dual-root composition, middleware custody
ErrorsStatus stringsA closed table of 49 error classes, spelled the same in every SDK
PackagesGo module root, npm 1.x, ratify-protocol on PyPI, crate 1.x, ratify-cGo /v2 module, npm 2.x, ratify-protocol 2.x with the protocol-v2 extra on PyPI, crate 2.x, ratify-c 2.x ABI
  • Verify, then release. VerifyProofBundleV2 returns a committed outcome that exposes no decision. ReleaseV2Decision checks the signed receipt, the checkpoint acknowledgement, and the deadlines, and returns the only value an application may act on. Applications gate each side effect on Allowed(clock). See Committed vs. released.
  • Signed status under a separate status key. Revocation lists and pushes are signed by a status key separate from every issuer and root key, and applied through an anchored SecurityJournalV2. An allow always requires current status for every certificate in the chain; a gap, fork, or stale list gives indeterminate. Every SDK ships a minimal status publisher. See Status from signed evidence.
  • Stored challenges. The issuance helper persists each challenge before it returns it, and the verifier claims it atomically, so a replay is never evaluated. See One-time challenges and claims.
  • Receipts for every terminal result, in a hash-chained log with checkpoint acknowledgements. See Receipts and logs.
  • Exact custom: scopes. A required scope may be one exact custom:<name> that every certificate in the chain lists. custom:* is invalid.
  • Extension evaluator profiles registered by the verifier, with the standard com.ratifyprotocol.max_count/v1 and com.ratifyprotocol.allowed_values/v1. The profile digests a decision used are signed into its receipt. See Delegation and constraints.
  • A closed constraint registry with integer-only numbers: time_window (pinned IANA tzdata), max_amount in micro-units, max_rate, resource_path, and ratify.receiver_audience.
  • Typed and external signers. No SDK signs caller-chosen bytes. An external provider can hold the private key, and the SDK verifies every returned signature before use. No claim is made about any particular KMS or HSM. See Typed signing and key IDs.
  • Deployment profiles for a single offline device, dual-root approval, and middleware custody. See Deployment profiles.
  • Wire limits checked before parsing, a closed table of 49 error classes, and finite delegation lifetimes.
  • Runnable examples in all five languages, with identical output checked in the protocol repository’s CI. They are the code shown on these pages.
  • The SDKs’ in-memory reference stores are for tests and examples only. Production needs durable Part B stores and an independent checkpoint in a separate failure domain.
  • Embedded v2 targets other than armv7 Linux are untested.
  • No reference integration is described as v2-compatible until its own gate passes on v2 with recorded versions; see the compatibility ledger and the published-package results from 31 October 2026.
  • Ratify Verify is not yet publicly available. It is being built to use Protocol v2 by default when it launches.

Session grants, agent-to-agent mutual presentation, HTTP and registry bindings, and geo, speed, and activation constraints are planned for 2.1. Until then they remain v1 capabilities. See v1-only until 2.1.

The normative mapping of every v1 concept is in the upgrade guide.