ratify-protocol (Rust)
Rust reference SDK of the Ratify Protocol: delegated-authority proofs for human-agent and agent-agent interactions.
Hybrid signatures: every signature is Ed25519 plus ML-DSA-65 (NIST FIPS 204), and both must verify, so a forger has to break both algorithms.
Byte-identical interoperability with the Go, TypeScript, Python, and C/C++ reference implementations. Validated against the 79 canonical test vectors (Protocol v1) on every CI run. This package also implements Protocol v2 (version 2.0.0-beta.2, a prerelease) and runs every file in the shared testvectors/v2 corpus and the cross-SDK fixtures of every other SDK.
What is Ratify Protocol?
Ratify is an open cryptographic protocol that answers the question: "Is this AI agent authorized to act, by whom, for what, and under what constraints?"
A human issues a signed delegation cert to an agent. The agent presents a proof bundle when acting. Any third party can verify the proof without calling back to whoever issued it. In Protocol v2 the verifier then releases the decision: it is actionable only after the verifier's signed receipt has been acknowledged by an independent checkpoint.
For Protocol v1, beyond the one-shot delegate → present → verify round trip, this SDK implements the full v1.1 feature set for continuous and multi-party interactions: session-bound challenges and stream sequence numbers (replay and reorder detection across a multi-turn conversation), single-use challenge acceptance through a pluggable challenge store (SPEC §10), the SessionToken fast path (one hybrid signature verification per turn instead of N+1) with scope, single-use, and binding enforcement on the streamed path, canonical operation- and session-context binding for middleware custody deployments (SPEC §6.4.9, §15.2.1), push-based revocation, multi-party transaction receipts, witness append-only logs, and key rotation statements. All normative in the spec. Protocol v2 has its own session and stream binding, signed status, receipts, witness entries and key rotation; the SessionToken fast path, A2A mutual presentation, the HTTP and registry bindings, and the geo and speed constraints remain v1-only until Protocol 2.1.
- Protocol v1 spec: SPEC.md
- Protocol v2 spec: SPEC-v2.md, upgrade guide: docs/PROTOCOL_V2_MIGRATION.md
- Runnable v2 examples in every SDK language: examples/v2
- Explainer (how it works, threat model): docs/EXPLAINED.md
- Developer docs: docs.ratifyprotocol.com
Install
[]
= "2.0.0-beta.2"
Version 2.0.0-beta.2 is a Protocol v2 prerelease. The v2 API is the
ratify_protocol::v2 module; the v1 API stays at the crate root. To keep the
exact v1 release next to it, rename it:
ratify_v1 = { package = "ratify-protocol", version = "=1.0.0-alpha.20" }.
Protocol v2 quickstart
Runnable Rust programs live in
examples/v2/rust
(cargo run --release --bin quickstart from that directory): a quickstart
(keys, delegation, challenge from the issuance helper, proof, verify, receipt,
checkpoint, release, allowed), signed status with a revocation, an exact
custom: scope with the max_count/v1 evaluator profile, and an external
signer. Each prints the same output as the other SDKs' programs, and CI checks
it. They use the in-memory reference stores in ratify_protocol::v2::reference
and are development-only. Upgrading from v1 is covered in
docs/PROTOCOL_V2_MIGRATION.md.
Quickstart (Protocol v1 API)
use ;
use ;
Key custody
The protocol supports three key-custody modes with different trust tradeoffs. See SPEC.md §15.2 for the full model.
Self-custody (strongest)
The user generates and holds their own keypair. No third party can sign on their behalf.
use ;
// User generates keypair on their own device; the private key never leaves
let = generate_human_root;
// User signs delegations locally
issue_delegation;
// Only root.id and root.public_key are shared with registries
Custodial
A registry operator generates and stores the keypair server-side (envelope-encrypted with KMS). The user never touches keys directly. The operator calls the same SDK functions on the user's behalf.
Self-custody upgrade
A user who started in custodial mode can migrate to self-custody at any time using KeyRotationStatement:
use ;
// User generates a NEW keypair on their device
let = generate_human_root;
// Rotation statement signed by BOTH old (custodial) and new (device) keys
let mut stmt = KeyRotationStatement ;
issue_key_rotation_statement;
// From now on, only the user's device key can sign delegations.
// Auditors verify continuity via the rotation statement.
Scope vocabulary
Ratify v1 ships 54 canonical scopes plus 14 wildcards and a custom: extension pattern for application-specific scopes. See SPEC.md §9 for the full table including sensitivity flags and wildcard expansions.
For app-specific needs not covered by the canonical vocabulary, use the custom: prefix:
use validate_scopes;
assert!;
Custom scopes pass through expand_scopes unchanged and are non-sensitive by default.
Running the conformance tests
The suite loads every fixture from the canonical test vectors and runs it through the Rust implementation. All 79 must pass; any failure means this SDK has drifted from the Go reference.
v1 API added in alpha.16
The following surface first shipped in the v1 alpha.16 release and is available in every later v1 release.
- Resource-bound verification. The
resource_pathconstraint (the 8th constraint type, SPEC §5.7.3) binds authority to a named resource via aConstraint'sresource_idand optionalpath_prefix. At verify time the application suppliesrequested_resource_idandrequested_pathonVerifierContext(SPEC §5.16);verify_bundle(&bundle, &VerifyOptions { context, ..Default::default() })evaluates them. Helpers:normalize_resource_path,resource_path_matches,validate_resource_constraints. - Operation / session verifier context.
OperationContextandSessionContextInputs, withoperation_context_bytes,operation_context_hash,session_context_bytes, andbuild_session_context;verifier_context_hashproduces the canonical hash bound into aVerificationReceipt. - VerificationReceipt wire codecs.
encode_verification_receipt;decode_verification_receiptrequires thestdfeature. - Streamed-turn verify options.
StreamedTurnandStreamedVerifyOptions, withverify_streamed_turn_with_options(the options-object streamed fast path, SPEC §5.13). - Extension-constraint params. A
Constraint'sparams(typedParamsValue) carries parameters for non-canonical constraint types (SPEC §5.7.1), validated byvalidate_params_valueandvalidate_constraint_params;is_canonical_constraint_typeguards which types may carry them. - Deeper delegation chains.
MAX_DELEGATION_CHAIN_DEPTHis raised from 3 to 8 (SPEC §5.1). - Input bounds constants.
MAX_PROOF_BUNDLE_BYTES,MAX_SCOPES_PER_CERT,MAX_CONSTRAINTS_PER_CERT,MAX_SCOPE_LENGTH_BYTES,MAX_IDENTIFIER_LENGTH_BYTES,MAX_AGENT_NAME_LENGTH_BYTES,MAX_JSON_NESTING_DEPTH.
Protocol v2 API
Version 2.0.0-beta.2 is a prerelease on the separate v2 line. The v2 API lives
in the ratify_protocol::v2 module next to the unchanged v1 API. Review so far
is the project's own pre-release security review; external independent review is a gate for
2.0.0, and v2 carries no production security claim yet. It covers:
- strict decoding and canonical encoding of every v2 signed object, full 256-bit v2 key IDs, and typed signers for every object, each with an external-signer form (direct or external-mu mode) whose returned signatures are verified before use;
- the challenge issuance helper (persist before expose) and the live verifier
verify_proof_bundle_v2, which returns a committed outcome with no decision, and the release step that returns the only actionable decision; - signed status: the status publisher under a separate status key and the
anchored
SecurityJournalV2; - the closed constraint registry and extension evaluator profiles, including
the standard
max_count/v1andallowed_values/v1; - witness and verification-receipt logs, key rotation, transaction receipts,
archival verification, and the Part B traits, with in-memory reference
implementations in
ratify_protocol::v2::referencefor tests only.
cargo test runs every file in testvectors/v2, including the verifier
ordering, lifecycle, status, log, and rotation sequences, and verifies the
cross-SDK fixtures of every other SDK. The per-SDK record against the gates in
SPEC-v2 §8 is in
docs/V2_REFERENCE_COMPATIBILITY.md.
A deployment supplies durable Part B stores and an independent checkpoint.
License
Apache-2.0. See the project-level LICENSE.