evidence.v1 · ed25519
El recibo, explicado
Cada cambio gobernado produce un recibo firmado: evidence.v1. Esta página es el detalle completo: qué contiene, por qué se firma como se firma, y cómo cualquiera lo verifica sin confiar en nosotros.
El recibo, anotado
// evidence.v1: un recibo real de nuestro propio repo, abreviado.
{
"schemaVersion": "rootblocks.evidence/v1",
"evidenceId": "observed-pr-57-d1aea6afcbf1",
"operationType": "code.merge",
"status": "passed",
"assurance": "observed",
"actor": { "type": "tool", "id": "rootblocks-scan" },
"checks": [
{ "id": "review-gap", "status": "failed", "severity": "error" }
],
"provenance": {
"pullRequest": "Rootblocks/rootblocks-cloud#57",
"review": { "decision": "merged", "reviewer": "anrasi" }
},
"redaction": { "status": "not-needed", "rules": [] }
}
// + una firma ed25519 desacoplada { keyId, value }
Verificá un recibo sin conexión, solo con la clave pública:
$ npx rootblocks-verify rootblocks-receipt.json --key rootblocks.pub
✓ signature valid · schema evidence.v1 · not tampered
Sí: este recibo registra un check fallido, un PR escrito por un agente que se mergeó solo, sin revisión, en nuestro propio repo. El escaneo completó (status: passed) y registró el hueco con honestidad. Ese hueco es exactamente lo que RootBlocks existe para exponer.
Entregá este archivo a cualquiera. No nos necesita para verificarlo.
Apache-2.0 El formato de recibo es una especificación abierta, publicada en standards.rootblocks.com, y el verificador también: lo corrés con npx, sin cuenta y sin registro. Leelo, forkealo, o escribí el tuyo a partir del esquema. Si mañana desapareciéramos, cada recibo que ya tenés sigue verificando. La evidencia que depende de que su proveedor siga vivo no es evidencia.
- operationType el evento gobernado: un merge, una ejecución, un release.
- provenance.agent qué agente produjo el cambio, y con qué modelo corrió. Distinto del actor de la operación.
- decisionRefs la decisión humana que autorizó este cambio, referenciada por id. El ancla de la traza.
- assurance el sello: qué tan fuerte es el respaldo del recibo. observed, proven, traced, enforced.
- checks los gates y el alcance de rutas aplicado, tal como corrieron.
- redaction qué se omitió del recibo, declarado, para que la ausencia también sea auditable.
- signature desacoplada: ed25519 sobre los bytes canónicos, más el id de la clave de firma.
Por qué ed25519
Las firmas se hacen sobre los bytes canónicos del recibo, así que cualquier cambio en cualquier campo rompe la firma. No hay lugar para un recibo que diga una cosa y pruebe otra.
ed25519 es un esquema de firma moderno y ampliamente auditado: claves chicas, firmas chicas, firma determinística, y sin necesidad de una autoridad certificante. La verificación es una sola operación de clave pública que corre en cualquier lado, incluso en máquinas aisladas de la red.
La clave privada se genera por instalación y nunca sale del host del daemon. Cada recibo lleva su keyId, así que la rotación y la revocación son parte del formato de evidencia, no una idea tardía.
Por qué importa la verificación sin conexión
Un auditor, un cliente o un regulador no debería tener que confiar en RootBlocks para revisar tu evidencia. rootblocks verify toma un recibo y la clave pública, y responde con matemática, no con nuestra palabra.
Esa es la diferencia entre un log y evidencia. Un log vive dentro de un sistema que puede editarlo. Un recibo se firma en un ledger de solo anexado y se verifica en cualquier lado, en cualquier máquina, sin cuenta y sin red.
Una política, completa
policy: payments-tier
scope:
allow: ["src/payments/**", "test/payments/**"]
deny: ["**/secrets/**", "infra/**"]
gates: [ typecheck, test, lint ] # all required
allowedTools: [ Edit, Read, "Bash(npm *)" ]
limits: { maxFiles: 40, maxRuntime: "20m" }
onGateFail: block # no commit, no receipt
Modos de falla
Daemon caído configurable por política: fail-closed (los agentes no pueden mergear sin prueba) o fail-open (corre, marca observed, reconcilia después).
Plano de control caído los recibos se escriben primero localmente, en el ledger de solo anexado, que es lo que corre hoy. La sincronización con la nube (llegando con los design partners) se reanuda al reconectar.
Falla un gate sin commit, sin recibo. El intento en sí queda registrado como evidencia.
Qué sale de tu infraestructura
Sale
Nunca sale
hashes de contenido
código fuente
firmas ed25519
diffs
metadatos de checks (pasa/falla)
prompts del agente
IDs de decisión y de PR
contenido de archivos
Claves, y qué prueba la firma
Generada por instalación, en la primera corrida. La clave privada nunca sale del host del daemon.
Rotación cada recibo lleva su keyId, así que la rotación y la revocación están integradas en el formato de evidencia. El procedimiento de re-anclaje llega con el programa enterprise.
Nosotros probamos que esta ejecución, bajo esta política, quedó atada a esta decisión humana ratificada. No certificamos el razonamiento interno del agente, que es exactamente por qué anclamos la evidencia en la decisión humana, no en la narrativa del modelo.
checks.* + decisionRefs mapea a ISO 42001 cláusula 8 (control operacional) y SOC 2 CC8.1 (gestión de cambios).