ratify-protocol 2.0.0-beta.2

Delegated-authority proofs for human-agent and agent-agent interactions — Rust reference SDK for the Ratify Protocol.
Documentation

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.

Install

[dependencies]
ratify-protocol = "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 ratify_protocol::{
    generate_human_root, generate_agent,
    DelegationCert, HybridSignature, ProofBundle, VerifyOptions,
    PROTOCOL_VERSION, SCOPE_MEETING_ATTEND,
    issue_delegation, sign_challenge, generate_challenge,
    verify_bundle,
};
use std::time::{SystemTime, UNIX_EPOCH};

fn main() {
    // 1. DELEGATE
    let (root, root_priv) = generate_human_root();
    let (agent, agent_priv) =
        generate_agent("Alice's Assistant", "voice_agent").expect("agent generation");

    let now = SystemTime::now().duration_since(UNIX_EPOCH).unwrap().as_secs() as i64;
    let mut cert = DelegationCert {
        cert_id: "cert-1".into(),
        version: PROTOCOL_VERSION,
        issuer_id: root.id.clone(),
        issuer_pub_key: root.public_key.clone(),
        subject_id: agent.id.clone(),
        subject_pub_key: agent.public_key.clone(),
        scope: vec![SCOPE_MEETING_ATTEND.into()],
        constraints: Vec::new(),
        issued_at: now,
        expires_at: now + 7 * 24 * 3600,
        signature: HybridSignature { ed25519: vec![], ml_dsa_65: vec![] },
    };
    issue_delegation(&mut cert, &root_priv).expect("delegation issuance");

    // 2. PRESENT
    let challenge = generate_challenge();
    let challenge_at = now;
    let bundle = ProofBundle {
        agent_id: agent.id.clone(),
        agent_pub_key: agent.public_key.clone(),
        delegations: vec![cert],
        challenge: challenge.clone(),
        challenge_at,
        challenge_sig: sign_challenge(&challenge, challenge_at, &agent_priv),
        session_context: Vec::new(),
        stream_id: Vec::new(),
        stream_seq: 0,
    };

    // 3. VERIFY
    let opts = VerifyOptions {
        required_scope: SCOPE_MEETING_ATTEND.into(),
        ..Default::default()
    };
    let result = verify_bundle(&bundle, &opts);
    if result.valid {
        println!("✅ Authorized agent {} for {}", result.agent_id, result.human_id);
    } else {
        println!("❌ {:?}: {}", result.identity_status, result.error_reason);
    }
}

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 ratify_protocol::{generate_human_root, issue_delegation};

// User generates keypair on their own device; the private key never leaves
let (root, private_key) = generate_human_root();

// User signs delegations locally
issue_delegation(&mut cert, &private_key);

// 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 ratify_protocol::{
    generate_human_root, issue_key_rotation_statement, KeyRotationStatement,
};

// User generates a NEW keypair on their device
let (new_root, new_private_key) = generate_human_root();

// Rotation statement signed by BOTH old (custodial) and new (device) keys
let mut stmt = KeyRotationStatement {
    version: 1,
    old_id: old_root.id.clone(),
    old_pub_key: old_root.public_key.clone(),
    new_id: new_root.id.clone(),
    new_pub_key: new_root.public_key.clone(),
    rotated_at: 1_700_000_000, // current unix seconds
    reason: "routine".into(),
    signature_old: HybridSignature { ed25519: vec![], ml_dsa_65: vec![] },
    signature_new: HybridSignature { ed25519: vec![], ml_dsa_65: vec![] },
};
issue_key_rotation_statement(&mut stmt, &old_custodial_key, &new_private_key);

// 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 ratify_protocol::validate_scopes;

assert!(validate_scopes(&["custom:acme:inventory:read".into()]).is_none());

Custom scopes pass through expand_scopes unchanged and are non-sensitive by default.

Running the conformance tests

cargo test

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_path constraint (the 8th constraint type, SPEC §5.7.3) binds authority to a named resource via a Constraint's resource_id and optional path_prefix. At verify time the application supplies requested_resource_id and requested_path on VerifierContext (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. OperationContext and SessionContextInputs, with operation_context_bytes, operation_context_hash, session_context_bytes, and build_session_context; verifier_context_hash produces the canonical hash bound into a VerificationReceipt.
  • VerificationReceipt wire codecs. encode_verification_receipt; decode_verification_receipt requires the std feature.
  • Streamed-turn verify options. StreamedTurn and StreamedVerifyOptions, with verify_streamed_turn_with_options (the options-object streamed fast path, SPEC §5.13).
  • Extension-constraint params. A Constraint's params (typed ParamsValue) carries parameters for non-canonical constraint types (SPEC §5.7.1), validated by validate_params_value and validate_constraint_params; is_canonical_constraint_type guards which types may carry them.
  • Deeper delegation chains. MAX_DELEGATION_CHAIN_DEPTH is 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/v1 and allowed_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::reference for 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.