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 status
Section titled “Review status”- 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.
v1 and v2 side by side
Section titled “v1 and v2 side by side”| Area | Protocol v1 (1.0.0-alpha.21) | Protocol v2 (2.0.0-beta.2) |
|---|---|---|
| Signatures | Hybrid Ed25519 and ML-DSA-65 over canonical bytes | Same algorithms. Both sign a domain-separated message carrying the object type code, and ML-DSA uses a fixed context per object type |
| Key IDs | 128-bit v1 ID | Full 256-bit key_id_v2; trust is pinned by complete key, never by ID alone |
| Numbers | Floats allowed in some constraints | Integers only; amounts in micro-units (max_amount_micros) |
| Decision | Verify returns a status | A committed outcome, actionable only after release: receipt verified, checkpoint acknowledged, deadlines current |
| Revocation | Provider callback, which may be unsigned or boolean | Signed lists and pushes under a separate status key, applied through an anchored journal. An allow requires current status |
| Audit | Optional receipts and audit hook | A signed receipt for every terminal result, in a hash-chained log acknowledged by an independent checkpoint |
| Replay | Optional challenge store | A stored challenge and an atomic claim are required for a live decision |
| Custom scopes | custom: accepted as a required scope | One exact custom: scope, listed by every certificate in the chain; custom:* is invalid |
| Constraints | Built-in types including geo and speed, plus a local evaluator hook | A closed registry of five types plus registered evaluator profiles whose digests are signed into the receipt |
| Geo and speed | Supported | Planned for 2.1 |
| Session fast path | SessionToken | Planned for 2.1 |
| Agent-to-agent mutual presentation | Documented pattern | Planned for 2.1 |
| HTTP and registry bindings | Specified | Planned for 2.1 |
| Expiry | No-expiry sentinel allowed | Finite expiry, at most ten years |
| Limits | Depth and identifier limits | Per-object byte limits checked before parsing |
| Deployment profiles | Middleware custody | Single-device offline, dual-root composition, middleware custody |
| Errors | Status strings | A closed table of 49 error classes, spelled the same in every SDK |
| Packages | Go module root, npm 1.x, ratify-protocol on PyPI, crate 1.x, ratify-c | Go /v2 module, npm 2.x, ratify-protocol 2.x with the protocol-v2 extra on PyPI, crate 2.x, ratify-c 2.x ABI |
What’s new in this beta
Section titled “What’s new in this beta”- Verify, then release.
VerifyProofBundleV2returns a committed outcome that exposes no decision.ReleaseV2Decisionchecks the signed receipt, the checkpoint acknowledgement, and the deadlines, and returns the only value an application may act on. Applications gate each side effect onAllowed(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 givesindeterminate. 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 exactcustom:<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/v1andcom.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_amountin micro-units,max_rate,resource_path, andratify.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.
Known limits
Section titled “Known limits”- 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.
What is not in v2.0
Section titled “What is not in v2.0”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.
