Delegation and constraints
Delegation certificates
Section titled “Delegation certificates”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:delegatefrom 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.
Exact custom: scopes
Section titled “Exact custom: scopes”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 prefixcustom:, and an empty string are never valid required scopes.- Whether a custom action is sensitive is relying-party policy, not a Protocol property.
The constraint registry
Section titled “The constraint registry”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.
Extension evaluator profiles
Section titled “Extension evaluator profiles”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 formname/vN. Its descriptor digest is signed into every receipt for the claim, in the receipt memberconstraint_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
paramsand the authenticated request context. It returnspass(optionally with a horizon),denied, orunverifiable. An error, panic, timeout, or anything else counts asconstraint_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.
