ritta 0.2.0__tar.gz

ritta-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,12 @@
+name: ci
+on: [push, pull_request]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v3
+      - run: uv sync
+      - run: uv run ruff check .
+      - run: uv run mypy --strict src
+      - run: uv run pytest -q

ritta-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,44 @@
+name: publish
+
+# Publishes to PyPI when a GitHub release is published from a v* tag.
+# Uses PyPI trusted publishing (OIDC): no API tokens are stored in secrets.
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    if: startsWith(github.event.release.tag_name, 'v')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v3
+      - name: Check tag matches project version
+        run: |
+          version=$(grep -m1 '^version = ' pyproject.toml | cut -d '"' -f2)
+          test "v${version}" = "${{ github.event.release.tag_name }}" \
+            || { echo "Tag ${{ github.event.release.tag_name }} != v${version}"; exit 1; }
+      - run: uv sync
+      - run: uv run ruff check .
+      - run: uv run mypy --strict src
+      - run: uv run pytest -q
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/ritta
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

ritta-0.2.0/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.hypothesis/
+.env
+.env.*
+*.pem
+*.key

ritta-0.2.0/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+## Unreleased
+
+## 0.2.0
+
+- Renamed to Ritta: the PyPI distribution and the import package are now `ritta` (was `agentmandates`).
+- Claim prefix changed from `agentmandates:` to `ritta:` (e.g. `ritta:limits.total`). Tokens with the old prefix are rejected as `malformed`; see the compatibility note in the spec.
+- No functional changes.
+
+## 0.1.0
+
+- `Mandate`, `Limits` and `Scope` models (pydantic v2) with every claim required by the spec; integer amounts only.
+- Ed25519 key generation and PEM import/export (`generate_keypair`, `*_to_pem`, `load_*_pem`).
+- Mandates signed as SD-JWT (`typ: vc+sd-jwt`, `alg: EdDSA`), no selective disclosure yet.
+- Pure `verify()` returning `VerificationResult(ok, reason)`.
+- Spec: defined wire format, check order, empty `categories` means "any", verify does not enforce `hitl_threshold`.
+- READMEs in Spanish, English and Portuguese. Package ships `py.typed`.
+- Project scaffold.

ritta-0.2.0/CLAUDE.md

@@ -0,0 +1,61 @@
+# CLAUDE.md — mandates
+
+Este archivo es la memoria de trabajo de Claude Code en este repo. Leelo entero antes de tocar código.
+
+## Qué es el proyecto (en una oración)
+
+> Nombre: **Ritta** (ritta.io, docs en ritta.dev). Repo: https://github.com/ritta-io/mandates. Paquete en PyPI: `ritta`. Publicar en PyPI solo desde un tag `v*` (release de GitHub → `.github/workflows/publish.yml`), nunca a mano ni desde una rama.
+
+El producto le pone límites a la inteligencia artificial cuando gasta plata: el dueño define hasta cuánto puede pagar un agente y en qué, cada pago se verifica contra esa regla antes de ejecutarse, y todo queda registrado de forma auditable. La plata nunca pasa por nosotros: pasa por Mercado Pago, Pix o una wallet del cliente.
+
+## Qué es ESTE repo
+
+`mandates` es la **librería open source (Apache 2.0)** del formato de mandato y su verificación, más el SDK de cliente en Python. Es la capa de adquisición: lo que un desarrollador instala con `pip install ritta` para que su agente pueda pedir permiso de gasto de forma estándar.
+
+Lo que vive acá:
+- `ritta.mandates`: modelo de mandato, firma, verificación, serialización. Compatible con **AP2 v0.2** (Agent Payments Protocol, hoy en la FIDO Alliance): el mandato es una credencial verificable **SD-JWT**, con estados `open` (presupuesto + restricciones) y `closed` (monto atado a un checkout concreto).
+- `ritta.client`: cliente HTTP y herramientas MCP para hablar con un el gateway (`create_mandate`, `quote`, `request_payment`, `get_receipt`).
+- `docs/`: spec del mandato en español, inglés y portugués.
+
+Lo que NO vive acá (vive en `gateway`, repo privado): el motor de políticas, los rieles de pago (Mercado Pago, x402, Pix), el ledger, el audit log, el panel, la facturación.
+
+## Stack y convenciones
+
+- Python 3.12. Gestor: `uv`. Empaquetado con `pyproject.toml` (hatchling). Nombre del paquete en PyPI: `ritta`.
+- Tipado estricto: `mypy --strict` pasa siempre. Modelos con `pydantic` v2.
+- Firma y verificación: `cryptography` (Ed25519 por defecto) y SD-JWT según el borrador IETF `draft-ietf-oauth-selective-disclosure-jwt`. No inventar criptografía: usar primitivas estándar.
+- Tests con `pytest` + `hypothesis` para propiedades (un mandato nunca se verifica con firma inválida, vencido, o con monto mayor al restante).
+- Lint y formato: `ruff`. Commits en inglés, estilo Conventional Commits (`feat:`, `fix:`, `docs:`). Código, nombres y comentarios en inglés; documentación de usuario en español, inglés y portugués.
+- Sin dependencias pesadas. Nada de frameworks web en este repo.
+
+## Reglas no negociables
+
+1. **El modelo de lenguaje nunca decide monto, moneda ni destinatario.** Esos datos salen del mandato firmado y del catálogo del comercio. El agente solo elige un `product_id` o una intención. Cualquier API que acepte un monto libre proveniente del agente está mal diseñada y no se mergea.
+2. **Nada de secretos en el código ni en los tests.** Claves de prueba se generan en el test. Nunca commitear `.env`, tokens de Mercado Pago, claves privadas.
+3. **Un mandato tiene siempre:** emisor (quién autoriza), sujeto (qué agente), límites (monto total, monto por operación, moneda), alcance (comercios o categorías permitidas), vencimiento, nonce, y firma. Si falta uno, el constructor falla.
+4. **Verificación es pura y determinista:** misma entrada, misma salida, sin red. La verificación de un mandato no llama a ningún servicio externo.
+5. **Compatibilidad AP2 primero.** Si hay que elegir entre un diseño propio y uno que mapea limpio a AP2/Verifiable Credentials, se elige AP2. Lo que no cubre AP2 va en extensiones con prefijo `ritta:`.
+6. **Idempotencia:** toda operación que pueda repetirse lleva `idempotency_key`.
+7. **Montos en enteros** (centavos/unidad mínima) con moneda ISO 4217 o identificador de token. Nunca `float`.
+
+## Cómo trabajamos con Claude Code
+
+- Antes de implementar algo, leé `docs/spec-mandate.md` y los tests existentes. Si la spec no cubre el caso, primero se actualiza la spec, después el código.
+- Trabajá en ramas `feat/...` o `fix/...`. Un PR por cambio. Los PR llevan descripción en inglés y, si cambia la spec, una línea en `CHANGELOG.md`.
+- Definición de terminado: `uv run pytest` verde, `uv run mypy --strict src` sin errores, `uv run ruff check .` limpio, docs actualizadas en los tres idiomas si cambió la API pública.
+- Cuando no estés seguro de una decisión de diseño que afecte la compatibilidad con AP2, Mercado Pago o x402: no asumas, dejá un comentario `# DECISION NEEDED:` y pará.
+- No agregues funcionalidad que no esté en la etapa actual del roadmap (ver `docs/roadmap.md`). Menos es más.
+
+## Comandos
+
+```bash
+uv sync                      # instalar dependencias
+uv run pytest -q             # tests
+uv run mypy --strict src     # tipos
+uv run ruff check . && uv run ruff format .   # lint y formato
+uv build                     # construir el paquete
+```
+
+## Estado actual
+
+Etapa 1 del roadmap. Objetivo de la etapa: esquema de mandato compatible con AP2 v0.2 (SD-JWT), firma y verificación en Python, README en tres idiomas, tests de propiedades. Ver `docs/roadmap.md`.

ritta-0.2.0/LICENSE

@@ -0,0 +1,17 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   Copyright 2026 Ramiro Ritta
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

ritta-0.2.0/PKG-INFO

@@ -0,0 +1,90 @@
+Metadata-Version: 2.5
+Name: ritta
+Version: 0.2.0
+Summary: Signed spend mandates for AI agents: create, sign and verify what an agent may pay, on whose behalf, and within which limits.
+Project-URL: Homepage, https://ritta.io
+Project-URL: Documentation, https://ritta.dev
+Project-URL: Repository, https://github.com/ritta-io/mandates
+Author: Ramiro Ritta
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: agentic-commerce,ai-agents,ap2,mandates,mcp,mercadopago,payments,x402
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Security :: Cryptography
+Requires-Python: >=3.12
+Requires-Dist: cryptography>=42
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.7
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.2; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# Ritta · mandates
+
+**Español** · [English](docs/README_en.md) · [Português](docs/README_pt.md)
+
+[Ritta](https://ritta.io) le pone límites a la inteligencia artificial cuando gasta tu plata: vos decís hasta cuánto puede pagar un agente y en qué, cada pago se verifica contra esa regla antes de ejecutarse, y todo queda registrado. La plata nunca pasa por Ritta.
+
+Este repo es la librería open source (Apache 2.0) del **mandato**: el permiso firmado que dice "este agente puede gastar hasta X, en Y, en nombre de Z". Es compatible con [AP2](https://fidoalliance.org/) (Agent Payments Protocol) y se usa con el gateway para pagar con Mercado Pago, Pix y USDC.
+
+```bash
+pip install ritta
+```
+
+```python
+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
+```
+
+Si el pago no está autorizado, `result.ok` es `False` y `result.reason` dice por qué: `invalid_signature`, `expired`, `amount_over_per_operation`, `amount_over_remaining`, `merchant_not_allowed`, `category_not_allowed` o `malformed`.
+
+`verify` es pura: no usa red ni guarda estado. Misma entrada, misma salida (pasá `now=` para fijar el reloj).
+
+Las claves se exportan e importan en PEM con `ritta.mandates.private_key_to_pem`, `public_key_to_pem`, `load_private_key_pem` y `load_public_key_pem`. Nunca guardes una clave privada en el repositorio.
+
+Documentación: [ritta.dev](https://ritta.dev). La especificación del formato está en [`docs/spec-mandate.md`](docs/spec-mandate.md).
+
+## Estado
+
+Pre-alpha (0.2.0). Etapa 1 del roadmap: ver [`docs/roadmap.md`](docs/roadmap.md).
+
+## Publicación (mantenedores)
+
+Las versiones se publican en PyPI como `ritta` solo desde un release de GitHub con tag `v*` (por ejemplo `v0.2.0`, que tiene que coincidir con `version` en `pyproject.toml`). Lo hace `.github/workflows/publish.yml` con *trusted publishing*: no hay tokens de PyPI en los secretos del repo.
+
+Configuración, una sola vez:
+
+1. En pypi.org, con la cuenta dueña del proyecto: *Your account → Publishing → Add a new pending publisher* (o, si el proyecto ya existe, *Manage → Publishing*).
+2. Completar: PyPI project name `ritta`, owner `ritta-io`, repository `mandates`, workflow name `publish.yml`, environment name `pypi`.
+3. En GitHub, *Settings → Environments* del repo `ritta-io/mandates`: crear el environment `pypi` (conviene agregar *required reviewers* para aprobar cada publicación).
+4. Publicar: actualizar `version` y `CHANGELOG.md`, mergear a `main`, y crear el release con tag `vX.Y.Z` desde la pestaña *Releases*.
+
+## Licencia
+
+Apache 2.0.

ritta-0.2.0/README.md

@@ -0,0 +1,65 @@
+# Ritta · mandates
+
+**Español** · [English](docs/README_en.md) · [Português](docs/README_pt.md)
+
+[Ritta](https://ritta.io) le pone límites a la inteligencia artificial cuando gasta tu plata: vos decís hasta cuánto puede pagar un agente y en qué, cada pago se verifica contra esa regla antes de ejecutarse, y todo queda registrado. La plata nunca pasa por Ritta.
+
+Este repo es la librería open source (Apache 2.0) del **mandato**: el permiso firmado que dice "este agente puede gastar hasta X, en Y, en nombre de Z". Es compatible con [AP2](https://fidoalliance.org/) (Agent Payments Protocol) y se usa con el gateway para pagar con Mercado Pago, Pix y USDC.
+
+```bash
+pip install ritta
+```
+
+```python
+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
+```
+
+Si el pago no está autorizado, `result.ok` es `False` y `result.reason` dice por qué: `invalid_signature`, `expired`, `amount_over_per_operation`, `amount_over_remaining`, `merchant_not_allowed`, `category_not_allowed` o `malformed`.
+
+`verify` es pura: no usa red ni guarda estado. Misma entrada, misma salida (pasá `now=` para fijar el reloj).
+
+Las claves se exportan e importan en PEM con `ritta.mandates.private_key_to_pem`, `public_key_to_pem`, `load_private_key_pem` y `load_public_key_pem`. Nunca guardes una clave privada en el repositorio.
+
+Documentación: [ritta.dev](https://ritta.dev). La especificación del formato está en [`docs/spec-mandate.md`](docs/spec-mandate.md).
+
+## Estado
+
+Pre-alpha (0.2.0). Etapa 1 del roadmap: ver [`docs/roadmap.md`](docs/roadmap.md).
+
+## Publicación (mantenedores)
+
+Las versiones se publican en PyPI como `ritta` solo desde un release de GitHub con tag `v*` (por ejemplo `v0.2.0`, que tiene que coincidir con `version` en `pyproject.toml`). Lo hace `.github/workflows/publish.yml` con *trusted publishing*: no hay tokens de PyPI en los secretos del repo.
+
+Configuración, una sola vez:
+
+1. En pypi.org, con la cuenta dueña del proyecto: *Your account → Publishing → Add a new pending publisher* (o, si el proyecto ya existe, *Manage → Publishing*).
+2. Completar: PyPI project name `ritta`, owner `ritta-io`, repository `mandates`, workflow name `publish.yml`, environment name `pypi`.
+3. En GitHub, *Settings → Environments* del repo `ritta-io/mandates`: crear el environment `pypi` (conviene agregar *required reviewers* para aprobar cada publicación).
+4. Publicar: actualizar `version` y `CHANGELOG.md`, mergear a `main`, y crear el release con tag `vX.Y.Z` desde la pestaña *Releases*.
+
+## Licencia
+
+Apache 2.0.

ritta-0.2.0/docs/README_en.md

@@ -0,0 +1,54 @@
+# Ritta · mandates
+
+[Español](../README.md) · **English** · [Português](README_pt.md)
+
+[Ritta](https://ritta.io) puts limits on AI when it spends your money: you decide how much an agent may pay and on what, every payment is checked against that rule before it runs, and everything is recorded. The money never goes through Ritta.
+
+This repo is the open source (Apache 2.0) library for the **mandate**: the signed permission that says "this agent may spend up to X, on Y, on behalf of Z". It is compatible with [AP2](https://fidoalliance.org/) (Agent Payments Protocol) and is used with the gateway to pay with Mercado Pago, Pix and USDC.
+
+```bash
+pip install ritta
+```
+
+```python
+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"),  # cents
+    scope=Scope(merchants=["MP-123456"], categories=["pharmacy"]),
+    hitl_threshold=1_000_000,  # from $10,000 a human must approve (enforced by the gateway)
+    state="open",
+    expires_in_days=30,
+)
+token = sign(mandate, private_key)  # SD-JWT signed with Ed25519
+
+result = verify(
+    token,
+    public_key,
+    amount=120_000,          # in cents; comes from the merchant catalog, never from the model
+    merchant="MP-123456",
+    category="pharmacy",
+    remaining=15_000_000,    # unspent balance, supplied by the gateway ledger
+)
+assert result.ok
+```
+
+If the payment is not authorized, `result.ok` is `False` and `result.reason` says why: `invalid_signature`, `expired`, `amount_over_per_operation`, `amount_over_remaining`, `merchant_not_allowed`, `category_not_allowed` or `malformed`.
+
+`verify` is pure: no network, no state. Same input, same output (pass `now=` to pin the clock).
+
+Keys are exported and imported as PEM with `ritta.mandates.private_key_to_pem`, `public_key_to_pem`, `load_private_key_pem` and `load_public_key_pem`. Never store a private key in the repository.
+
+Documentation: [ritta.dev](https://ritta.dev). The format specification is in [`spec-mandate.md`](spec-mandate.md) (Spanish).
+
+## Status
+
+Pre-alpha (0.2.0). Stage 1 of the roadmap: see [`roadmap.md`](roadmap.md).
+
+## License
+
+Apache 2.0.

ritta-0.2.0/docs/README_pt.md

@@ -0,0 +1,54 @@
+# Ritta · mandates
+
+[Español](../README.md) · [English](README_en.md) · **Português**
+
+A [Ritta](https://ritta.io) coloca limites na inteligência artificial quando ela gasta o seu dinheiro: você decide quanto um agente pode pagar e em quê, cada pagamento é verificado contra essa regra antes de ser executado, e tudo fica registrado. O dinheiro nunca passa pela Ritta.
+
+Este repositório é a biblioteca open source (Apache 2.0) do **mandato**: a permissão assinada que diz "este agente pode gastar até X, em Y, em nome de Z". É compatível com o [AP2](https://fidoalliance.org/) (Agent Payments Protocol) e é usada com o gateway para pagar com Mercado Pago, Pix e USDC.
+
+```bash
+pip install ritta
+```
+
+```python
+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,  # a partir de $10.000 exige aprovação humana (aplicada pelo gateway)
+    state="open",
+    expires_in_days=30,
+)
+token = sign(mandate, private_key)  # SD-JWT assinado com Ed25519
+
+result = verify(
+    token,
+    public_key,
+    amount=120_000,          # em centavos; vem do catálogo do comerciante, nunca do modelo
+    merchant="MP-123456",
+    category="pharmacy",
+    remaining=15_000_000,    # saldo não gasto, fornecido pelo ledger do gateway
+)
+assert result.ok
+```
+
+Se o pagamento não for autorizado, `result.ok` é `False` e `result.reason` diz o motivo: `invalid_signature`, `expired`, `amount_over_per_operation`, `amount_over_remaining`, `merchant_not_allowed`, `category_not_allowed` ou `malformed`.
+
+`verify` é pura: não usa rede nem guarda estado. Mesma entrada, mesma saída (passe `now=` para fixar o relógio).
+
+As chaves são exportadas e importadas em PEM com `ritta.mandates.private_key_to_pem`, `public_key_to_pem`, `load_private_key_pem` e `load_public_key_pem`. Nunca guarde uma chave privada no repositório.
+
+Documentação: [ritta.dev](https://ritta.dev). A especificação do formato está em [`spec-mandate.md`](spec-mandate.md) (em espanhol).
+
+## Status
+
+Pré-alfa (0.2.0). Etapa 1 do roadmap: veja [`roadmap.md`](roadmap.md).
+
+## Licença
+
+Apache 2.0.

ritta-0.2.0/docs/roadmap.md

@@ -0,0 +1,17 @@
+# Roadmap público
+
+| Etapa | Entregable |
+|---|---|
+| 1 | Esquema de mandato AP2 v0.2 (SD-JWT), firma/verificación Ed25519, README en es/en/pt, tests de propiedades |
+| 2 | (gateway) Modelo de datos Postgres: tenants, agents, mandates, ledger doble entrada, audit log hash-chain |
+| 3 | (gateway) Mercado Pago sandbox con `mercadopago-commerce-agents-checkout`: Order, webhook, conciliación |
+| 4 | Servidor MCP (OAuth 2.1) con `create_mandate`, `quote`, `request_payment`, `get_receipt`. Demo en video |
+| 5 | (gateway) Policy engine: límites agente/sesión/comercio/día + kill switch. Suite de 20 ataques de prompt injection |
+| 6 | Hito 1: primer pago real en producción de Mercado Pago (ARS 100) |
+| 7 | x402 en Base Sepolia → mainnet: primer servicio cobrando por llamada |
+| 8 | Segundo y tercer servicio de nicho. Publicación en Bazaar y Agent.market |
+| 9 | Registros de MCP. Opinión legal PSP. Términos y privacidad |
+| 10 | Dataset de fallas v0: 10 categorías, 50 casos anonimizados |
+| 11 | Plan Builder con cobro. Panel mínimo |
+| 12 | Hito 3: 3+ usuarios externos, 3 servicios cobrando, primer cliente pago |
+| 13 | Retro pública: seguir, pivotar o parar |

ritta-0.2.0/docs/spec-mandate.md

@@ -0,0 +1,52 @@
+# Especificación del mandato Ritta (borrador v0, implementado en 0.2.0)
+
+Un **mandato** es una credencial verificable (SD-JWT) que autoriza a un agente a gastar dentro de límites. Mapea a AP2 v0.2; lo que AP2 no cubre va en claims con prefijo `ritta:`.
+
+## Claims obligatorios
+
+Los nombres son literales y planos: `ritta:limits.total` es un único claim, no un objeto anidado.
+
+> **Compatibilidad.** La versión 0.1.0 usaba el prefijo `agentmandates:`. 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.
+
+| 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 (anti-replay) |
+| `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`.
+
+## 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 disclosures y sin Key Binding JWT.
+
+En 0.1.0 no hay divulgación selectiva: todos los claims son visibles. El formato ya es SD-JWT válido, así que agregar disclosures después no rompe el sobre. Mientras tanto, un verificador 0.1.0 rechaza como `malformed` cualquier token con disclosures, 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: la firma es válida, `now < exp`, `amount <= per_operation`, `amount <= remaining`, `merchant` y `category` están dentro del scope. Es pura: no consulta red. El saldo `remaining` lo aporta el gateway (ledger); la librería recibe el valor.
+
+Si falla, devuelve la primera razón en este orden: `malformed` / `invalid_signature`, `expired`, `amount_over_per_operation`, `amount_over_remaining`, `merchant_not_allowed`, `category_not_allowed`.
+
+- `amount` y `remaining` son enteros en la unidad mínima de la moneda del mandato. Argumentos inválidos (`amount <= 0`, `remaining < 0`, no enteros, `now` sin zona horaria) son errores de programación y lanzan excepción.
+- `hitl_threshold` no lo aplica `verify`: pedir aprobación humana es una decisión de política del gateway.
+
+## Pendientes (DECISION NEEDED)
+
+- Formato exacto de `iss` para pymes argentinas sin DID (¿`did:web` del gateway + CUIT?).
+- Mapeo de `ritta:scope.categories` a MCC de tarjetas.
+- `typ`: el borrador actual de SD-JWT VC usa `dc+sd-jwt` (antes `vc+sd-jwt`) y exige el claim `vct`. 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.

ritta-0.2.0/pyproject.toml

@@ -0,0 +1,60 @@
+[project]
+name = "ritta"
+version = "0.2.0"
+description = "Signed spend mandates for AI agents: create, sign and verify what an agent may pay, on whose behalf, and within which limits."
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.12"
+authors = [{ name = "Ramiro Ritta" }]
+keywords = ["ai-agents", "payments", "mandates", "ap2", "mcp", "mercadopago", "x402", "agentic-commerce"]
+classifiers = [
+  "Development Status :: 2 - Pre-Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: Apache Software License",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Office/Business :: Financial",
+  "Topic :: Security :: Cryptography",
+]
+dependencies = [
+  "pydantic>=2.7",
+  "cryptography>=42",
+  "httpx>=0.27",
+]
+
+[project.optional-dependencies]
+mcp = ["mcp>=1.2"]
+
+[project.urls]
+Homepage = "https://ritta.io"
+Documentation = "https://ritta.dev"
+Repository = "https://github.com/ritta-io/mandates"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ritta"]
+
+[dependency-groups]
+dev = [
+  "pytest>=8",
+  "hypothesis>=6",
+  "mypy>=1.10",
+  "ruff>=0.5",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "S"]
+ignore = ["S101"]
+
+[tool.mypy]
+strict = true
+python_version = "3.12"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

ritta-0.2.0/src/ritta/__init__.py

@@ -0,0 +1,24 @@
+"""Ritta: signed spend mandates for AI agents."""
+
+from ritta.mandates import (
+    Limits,
+    Mandate,
+    Scope,
+    VerificationResult,
+    generate_keypair,
+    sign,
+    verify,
+)
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "Limits",
+    "Mandate",
+    "Scope",
+    "VerificationResult",
+    "__version__",
+    "generate_keypair",
+    "sign",
+    "verify",
+]

ritta-0.2.0/src/ritta/mandates/__init__.py

@@ -0,0 +1,27 @@
+"""Mandate model, signing (SD-JWT, Ed25519) and pure verification."""
+
+from ritta.mandates.keys import (
+    generate_keypair,
+    load_private_key_pem,
+    load_public_key_pem,
+    private_key_to_pem,
+    public_key_to_pem,
+)
+from ritta.mandates.model import Limits, Mandate, Scope
+from ritta.mandates.sdjwt import sign
+from ritta.mandates.verify import RejectionReason, VerificationResult, verify
+
+__all__ = [
+    "Limits",
+    "Mandate",
+    "RejectionReason",
+    "Scope",
+    "VerificationResult",
+    "generate_keypair",
+    "load_private_key_pem",
+    "load_public_key_pem",
+    "private_key_to_pem",
+    "public_key_to_pem",
+    "sign",
+    "verify",
+]