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

One-time challenges and claims

A live v2 decision needs a challenge that the verifier issued, stored, and then claims exactly once. A challenge the presenter picked can only be checked as an archival proof, which is labelled freshness_unverified and never authorizes an action.

Every SDK provides a challenge issuer over a durable issuance store. To issue, it:

  1. validates the request (namespace, replay epoch, verifier ID, a lifetime from 1 to 300 seconds, and optional expected agent, receiver, and session context);
  2. reads the authoritative clock for issued_at and sets expires_at;
  3. draws 32 random bytes;
  4. durably stores the complete expected challenge;
  5. only then returns the challenge bytes.

A record is never overwritten. Every binding comes from the issuer’s authenticated state, never from the party that will present the proof. Deadlines are exclusive: a challenge is fresh only while now < expires_at and now < issued_at + max_age.

The agent signs a presentation over the verifier ID, its own key, the delegation chain digest, the challenge, and an optional session context. Before claiming anything, the verifier checks structure, key IDs, chain linkage, every signature, challenge binding and freshness, expected agent and session context, and receiver audience. A failure here consumes nothing and creates no receipt.

After preflight, the claim store atomically records the claim under (verifier namespace, replay epoch, challenge digest) and seals the bundle hash and the evaluation inputs. It rechecks freshness at its own authoritative time inside the same transaction.

  • A different proof for an already claimed challenge is claim_replay. It does not see the first result and creates no second receipt.
  • An exact retry of the same proof can only retrieve the result after it is released.
  • A stream (stream_id, stream_seq) advances in the same transaction and accepts only the next sequence number.

session_context binds a proof to the verifier, workspace, agent, session, invocation, and a hash of the exact operation (scope, operation, resource, path, payload digest). The verifier recomputes it from authenticated request state and compares before claim, so a valid proof cannot be moved to another action or verifier.

Details: SPEC-v2 §5.3, §7.3, §7.4, §6.10.