Mandate specification¶
Status
Draft v0, implemented in version 0.2.0 of the library. The source is docs/spec-mandate.md in the repository (in Spanish).
A mandate is a verifiable credential (SD-JWT) that authorizes an agent to spend within limits. It maps to AP2 v0.2; whatever AP2 does not cover goes into claims prefixed with ritta:.
Required claims¶
Names are literal and flat: ritta:limits.total is a single claim, not a nested object.
| Claim | Type | Meaning |
|---|---|---|
iss |
DID or URL | Who authorizes (person or company). Currently did:<method>:... or https://... is accepted |
sub |
string | Identifier of the authorized agent |
ritta:limits.total |
int | Total authorized amount, in the smallest unit (> 0) |
ritta:limits.per_operation |
int | Per-operation cap (> 0 and ≤ total) |
ritta:limits.currency |
string | ISO 4217 (ARS, BRL) or token (USDC). Syntax: ^[A-Z][A-Z0-9]{2,9}$ |
ritta:scope.merchants |
list | Allowed merchant IDs (empty = any, discouraged) |
ritta:scope.categories |
list | Allowed categories (empty = any, discouraged) |
ritta:hitl_threshold |
int | Amount from which human approval is required (≥ 0) |
exp |
timestamp | Expiration (NumericDate, UTC seconds) |
jti |
string | Unique nonce (anti-replay) |
ritta:state |
open / closed |
Open (budget) or closed (tied to a checkout) |
Amounts are JSON integers. A number with decimals (even 100.0) or a string makes the mandate malformed.
Compatibility
Version 0.1.0 used a different prefix. Since 0.2.0 the prefix is ritta:, and a 0.2.0 verifier does not accept mandates with the old prefix: it rejects them as malformed because the required claims are missing. No migration is offered because 0.1.0 had no external users.
Format (SD-JWT)¶
The signed mandate is an SD-JWT in compact form:
<JWT signed by the issuer>~
- Header:
{"alg": "EdDSA", "typ": "vc+sd-jwt"}. Ed25519 signature. - Payload:
"_sd_alg": "sha-256"plus the claims in the table. - The trailing
~is the SD-JWT separator, with zero disclosures and no Key Binding JWT.
The current version has no selective disclosure: every claim is visible. The format is already valid SD-JWT, so adding disclosures later does not break the envelope. Meanwhile, the verifier rejects as malformed any token with disclosures, a Key Binding JWT, _sd digests, a header with crit, duplicate JSON members or non-canonical base64url.
Verification¶
verify(token, public_key, *, amount, merchant, category, remaining, now=None)
Returns ok only if all of these hold:
- the signature is valid;
now < exp;amount <= per_operation;amount <= remaining;merchantis in scope;categoryis in scope.
It is pure: no network calls. The remaining balance is supplied by the gateway (ledger); the library receives the value.
Order of rejection reasons¶
On failure, it returns the first reason in this order:
| Order | Reason |
|---|---|
| 1 | malformed / invalid_signature |
| 2 | expired |
| 3 | amount_over_per_operation |
| 4 | amount_over_remaining |
| 5 | merchant_not_allowed |
| 6 | category_not_allowed |
amountandremainingare integers in the smallest unit of the mandate currency. Invalid arguments (amount <= 0,remaining < 0, non-integers, a timezone-naivenow) are programming errors and raise an exception.verifydoes not enforcehitl_threshold: asking for human approval is a gateway policy decision.
Open questions¶
Not yet decided:
- Exact
issformat for Argentine small businesses without a DID (gatewaydid:web+ CUIT?). - Mapping of
ritta:scope.categoriesto card MCC codes. typ: the current SD-JWT VC draft usesdc+sd-jwt(formerlyvc+sd-jwt) and requires thevctclaim. Still to confirm what AP2 v0.2 verifiers expect.closedmandate: which claim ties it to the checkout (AP2 CartMandate). Today it is verified the same as anopenone.- Agent binding (holder binding,
cnfclaim + Key Binding JWT): not implemented.