Especificación del mandato¶
Estado
Borrador v0, implementado en la versión 0.2.0 de la librería. La fuente es docs/spec-mandate.md en el repositorio.
Un mandato es una credencial verificable (SD-JWT) que autoriza a un agente a gastar dentro de límites. Se corresponde con AP2 v0.2; lo que AP2 no cubre va en claims con el prefijo ritta:.
Claims obligatorios¶
Los nombres son literales y planos: ritta:limits.total es un único claim, no un objeto anidado.
| Claim | Tipo | Significado |
|---|---|---|
iss |
DID o URL | Quién autoriza (persona o empresa). Hoy se acepta did:<método>:... o https://... |
sub |
string | Identificador del agente autorizado |
ritta:limits.total |
int | Monto total autorizado, en unidad mínima (> 0) |
ritta:limits.per_operation |
int | Tope por operación (> 0 y ≤ total) |
ritta:limits.currency |
string | ISO 4217 (ARS, BRL) o token (USDC). Sintaxis: ^[A-Z][A-Z0-9]{2,9}$ |
ritta:scope.merchants |
lista | IDs de comercio permitidos (vacío = cualquiera, desaconsejado) |
ritta:scope.categories |
lista | Categorías permitidas (vacío = cualquiera, desaconsejado) |
ritta:hitl_threshold |
int | Monto a partir del cual se exige aprobación humana (≥ 0) |
exp |
timestamp | Vencimiento (NumericDate, segundos UTC) |
jti |
string | Nonce único (contra la reutilización) |
ritta:state |
open / closed |
Abierto (presupuesto) o cerrado (atado a un checkout) |
Los montos son enteros JSON. Un número con decimales (aunque sea 100.0) o un string hace que el mandato sea malformed.
Compatibilidad
La versión 0.1.0 usaba otro prefijo. Desde 0.2.0 el prefijo es ritta: y un verificador 0.2.0 no acepta mandatos con el prefijo anterior: los rechaza como malformed porque les faltan los claims obligatorios. No se ofrece migración porque 0.1.0 no tuvo usuarios externos.
Formato (SD-JWT)¶
El mandato firmado es un SD-JWT en forma compacta:
<JWT firmado por el emisor>~
- Header:
{"alg": "EdDSA", "typ": "vc+sd-jwt"}. Firma Ed25519. - Payload:
"_sd_alg": "sha-256"más los claims de la tabla. - El
~final es el separador de SD-JWT, con cero divulgaciones (disclosures) y sin Key Binding JWT.
En la versión actual no hay divulgación selectiva: todos los claims son visibles. El formato ya es un SD-JWT válido, así que agregar divulgaciones más adelante no rompe el sobre. Mientras tanto, el verificador rechaza como malformed cualquier token con divulgaciones, Key Binding JWT, digests _sd, header con crit, miembros JSON duplicados o base64url no canónico.
Verificación¶
verify(token, public_key, *, amount, merchant, category, remaining, now=None)
Devuelve ok solo si se cumplen todas estas condiciones:
- la firma es válida;
now < exp;amount <= per_operation;amount <= remaining;merchantestá dentro del scope;categoryestá dentro del scope.
Es pura: no consulta la red. El saldo remaining lo aporta el gateway (ledger); la librería recibe el valor.
Orden de las razones de rechazo¶
Si falla, devuelve la primera razón en este orden:
| Orden | Razón |
|---|---|
| 1 | malformed / invalid_signature |
| 2 | expired |
| 3 | amount_over_per_operation |
| 4 | amount_over_remaining |
| 5 | merchant_not_allowed |
| 6 | category_not_allowed |
amountyremainingson enteros en la unidad mínima de la moneda del mandato. Los argumentos inválidos (amount <= 0,remaining < 0, valores no enteros,nowsin zona horaria) son errores de programación y lanzan una excepción.hitl_thresholdno lo aplicaverify: pedir aprobación humana es una decisión de política del gateway.
Pendientes¶
Temas abiertos, todavía sin decisión:
- Formato exacto de
isspara pymes argentinas sin DID (¿did:webdel gateway + CUIT?). - Correspondencia de
ritta:scope.categoriescon los códigos MCC de tarjetas. typ: el borrador actual de SD-JWT VC usadc+sd-jwt(antesvc+sd-jwt) y exige el claimvct. Falta confirmar qué esperan los verificadores AP2 v0.2.- Mandato
closed: qué claim lo ata al checkout (CartMandate de AP2). Hoy se verifica igual que unoopen. - Vinculación del agente (holder binding, claim
cnf+ Key Binding JWT): no implementada.