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

Delegation and constraints

A v2 delegation certificate names the issuer and subject by complete key and key ID, lists its scopes and constraints, and carries issued_at and a finite expires_at (at most 315360000 seconds, ten years, after issuance). Chains are ordered leaf to root, up to 8 certificates.

  • The effective scope of a chain is the intersection of every certificate’s expanded scope.
  • Every non-root issuer must have received identity:delegate from its parent. Scope intersection alone does not let an agent delegate further.
  • Sensitive scopes never ride a wildcard.
  • The scope vocabulary is the copy in Annex A, which is normative for v2.

A request names exactly one required scope: either one registered, non-wildcard canonical scope, or one exact custom: scope such as custom:ticket:refund.

  • A custom: scope is an opaque string matched by byte equality. It is never expanded, case-folded, or treated as a family, and no canonical scope or wildcard grants it.
  • Every certificate in the chain must list it.
  • custom:*, the bare prefix custom:, and an empty string are never valid required scopes.
  • Whether a custom action is sensitive is relying-party policy, not a Protocol property.

v2 has its own closed registry. No v1 constraint definition applies by reference, and every number is an integer.

Type Bounds Request context
time_window Local minute of day in an IANA zone, with wrap past midnight Authoritative evaluation time; the verifier’s pinned tzdb_version (IANA 2025c)
max_amount max_amount_micros in a three-letter currency requested_amount_micros, requested_currency
max_rate At most count allows in a rolling window_s The rate reservation store
resource_path Exact resource_id, optional segment-boundary path_prefix requested_resource_id, requested_path
ratify.receiver_audience Exact receiver IDs or trust-domain membership expected_receiver_id, authenticated membership evidence

A constraint that needs context the caller did not supply is constraint_unverifiable; it never passes by omission. An unregistered type is constraint_unknown. When one proof carries several constraints, any denial wins, then unknown, then unverifiable.

The names geo_circle, geo_polygon, geo_bbox, and max_speed_mps are reserved for 2.1. In v2.0 they evaluate as unregistered types and cannot authorize. See v1-only until 2.1.

An application constraint becomes an evaluator profile that the verifier registers in its own authenticated configuration. A certificate cannot select a profile or an implementation.

  • A profile has a reverse-domain type (for example com.example.max_seats) and an identifier of the form name/vN. Its descriptor digest is signed into every receipt for the claim, in the receipt member constraint_evaluators.
  • The profile set in use is sealed when the challenge is claimed, so recovery never re-runs an evaluator against a different registry.
  • An evaluator is a pure function of the signed params and the authenticated request context. It returns pass (optionally with a horizon), denied, or unverifiable. An error, panic, timeout, or anything else counts as constraint_unverifiable.
  • A profile identifier names one immutable definition. A matching digest records which identifier was bound; it is not evidence that two implementations behave the same. Interoperability needs published conformance vectors.

Two standard profiles are defined by the specification and its vectors (testvectors/v2/evaluator-profiles.json):

Profile Params Request input Outcome
com.ratifyprotocol.max_count/v1 counter, max extension_counts[counter] Deny when the quantity is above max
com.ratifyprotocol.allowed_values/v1 field, allowed (1 to 64 strings) extension_values[field] Pass only on an exact byte match

Each SDK reference page renders a custom-scope and evaluator example.

Details: SPEC-v2 §2.4, §5.1, §5.2.