Empezar¶
Esta guía recorre el ejemplo completo de la librería ritta: crear claves, armar un mandato, firmarlo y verificar un pago contra él. Necesitás Python 3.12 o más nuevo.
Instalar¶
pip install ritta
El ejemplo completo¶
from ritta import Limits, Mandate, Scope, generate_keypair, sign, verify
private_key, public_key = generate_keypair()
mandate = Mandate(
issuer="did:web:farmacia-central.com.ar",
subject="agent:compras-01",
limits=Limits(total=15_000_000, per_operation=5_000_000, currency="ARS"), # centavos
scope=Scope(merchants=["MP-123456"], categories=["pharmacy"]),
hitl_threshold=1_000_000, # desde $10.000 se pide aprobación humana (lo aplica el gateway)
state="open",
expires_in_days=30,
)
token = sign(mandate, private_key) # SD-JWT firmado con Ed25519
result = verify(
token,
public_key,
amount=120_000, # en centavos; sale del catálogo del comercio, nunca del modelo
merchant="MP-123456",
category="pharmacy",
remaining=15_000_000, # saldo sin gastar, lo aporta el ledger del gateway
)
assert result.ok
A continuación, paso por paso.
1. Crear las claves¶
private_key, public_key = generate_keypair()
generate_keypair() crea un par de claves Ed25519. La clave privada la guarda quien autoriza el gasto (la persona o la empresa) y sirve para firmar mandatos. La clave pública se comparte con quien tiene que verificar los pagos.
2. Armar el mandato¶
mandate = Mandate(
issuer="did:web:farmacia-central.com.ar",
subject="agent:compras-01",
limits=Limits(total=15_000_000, per_operation=5_000_000, currency="ARS"),
scope=Scope(merchants=["MP-123456"], categories=["pharmacy"]),
hitl_threshold=1_000_000,
state="open",
expires_in_days=30,
)
El mandato es el permiso: "este agente puede gastar hasta X, en Y, en nombre de Z".
issuer: quién autoriza. Un DID (did:...) o una URLhttps://....subject: el agente autorizado.limits: cuánto puede gastar en total y como máximo por operación, y en qué moneda. Los montos van siempre en enteros y en la unidad mínima de la moneda (centavos):15_000_000son $150.000.scope: en qué comercios y en qué categorías puede gastar.hitl_threshold: a partir de qué monto se pide aprobación de una persona. En este ejemplo, desde $10.000. Esta regla no la aplica la librería, sino el gateway.state:openes un presupuesto abierto;closedes un mandato atado a una compra concreta.expires_in_days: cuántos días dura el mandato.
3. Firmar¶
token = sign(mandate, private_key)
sign devuelve el mandato firmado como texto: un SD-JWT con firma Ed25519. Ese texto es lo que viaja con el agente. Si alguien cambia un solo carácter, la firma deja de ser válida.
4. Verificar un pago¶
result = verify(
token,
public_key,
amount=120_000,
merchant="MP-123456",
category="pharmacy",
remaining=15_000_000,
)
assert result.ok
Antes de cada pago, verify controla que la firma sea válida, que el mandato no esté vencido, que el monto no supere el tope por operación ni el saldo disponible, y que el comercio y la categoría estén permitidos.
amount: el monto del pago, en centavos. Tiene que salir del catálogo del comercio, nunca de lo que diga el modelo de lenguaje.remaining: el saldo que todavía no se gastó de ese mandato. Lo aporta el libro contable (ledger) del gateway; la librería solo recibe el valor.
5. Cuando el pago no está autorizado¶
Si el pago no está autorizado, result.ok es False y result.reason dice por qué. Por ejemplo, un pago de $60.000 supera el tope por operación de $50.000:
result = verify(
token,
public_key,
amount=6_000_000,
merchant="MP-123456",
category="pharmacy",
remaining=15_000_000,
)
assert not result.ok
assert result.reason == "amount_over_per_operation"
Las razones posibles son:
| Razón | Qué significa |
|---|---|
malformed |
El token no tiene el formato esperado o le faltan datos obligatorios. |
invalid_signature |
La firma no corresponde a la clave pública o el token fue modificado. |
expired |
El mandato está vencido. |
amount_over_per_operation |
El monto supera el tope por operación. |
amount_over_remaining |
El monto supera el saldo disponible. |
merchant_not_allowed |
El comercio no está entre los permitidos. |
category_not_allowed |
La categoría no está entre las permitidas. |
Si hay más de un problema, se informa el primero en ese orden. El detalle está en la especificación.
Una verificación sin sorpresas¶
verify es pura: no usa la red ni guarda estado. Con la misma entrada da siempre la misma salida. Para fijar el reloj (por ejemplo, en tests), pasá now= con una fecha y hora con zona horaria.
Guardar las claves¶
Las claves se exportan e importan en formato PEM con ritta.mandates.private_key_to_pem, public_key_to_pem, load_private_key_pem y load_public_key_pem.
Cuidá la clave privada
Nunca guardes una clave privada en el repositorio. Quien tenga esa clave puede firmar mandatos en tu nombre.