Saltar a contenido

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 URL https://....
  • 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_000 son $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: open es un presupuesto abierto; closed es 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.