ratify-protocol (Rust)
Rust reference SDK of the Ratify Protocol v1 — delegated-authority proofs for human-agent and agent-agent interactions.
Quantum-safe by design: every signature is hybrid Ed25519 + ML-DSA-65 (NIST FIPS 204). Both must verify.
Byte-identical interoperability with the Go, TypeScript, Python, and C/C++ reference implementations. Validated against the 79 canonical test vectors on every CI run.
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 — offline, without contacting a server — and get a cryptographically certain answer.
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 — practical for live voice and video) 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.
- Full protocol spec: SPEC.md
- Explainer (how it works, threat model): docs/EXPLAINED.md
- Developer docs: docs.identities.ai
Install
[]
= "1.0.0-alpha.20"
Quickstart
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 — 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.
API added on main (ships in alpha.16, release unpublished)
The following surface is merged to main and ships in alpha.16. The tag is not yet published; depend on main (git) to use it ahead of the 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.
License
Apache-2.0. See the project-level LICENSE.