Saltar a contenido

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;
  • merchant está dentro del scope;
  • category está 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
  • amount y remaining son enteros en la unidad mínima de la moneda del mandato. Los argumentos inválidos (amount <= 0, remaining < 0, valores no enteros, now sin zona horaria) son errores de programación y lanzan una excepción.
  • hitl_threshold no lo aplica verify: pedir aprobación humana es una decisión de política del gateway.

Pendientes

Temas abiertos, todavía sin decisión:

  • Formato exacto de iss para pymes argentinas sin DID (¿did:web del gateway + CUIT?).
  • Correspondencia de ritta:scope.categories con los códigos MCC de tarjetas.
  • typ: el borrador actual de SD-JWT VC usa dc+sd-jwt (antes vc+sd-jwt) y exige el claim vct. 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 uno open.
  • Vinculación del agente (holder binding, claim cnf + Key Binding JWT): no implementada.