Firma y confianza
Un documento que un agente sigue se parece más a un artefacto de despliegue que a una página de wiki, así que recibe el mismo trato: quién lo escribió, si ha cambiado y si sigue estando aprobado.
Qué se firma
Publicar produce una atestación de autor (author attestation): una firma sobre los bytes tal como se escribieron, que nombra el documento, la versión, el digest y el techo de capacidades que el editor respalda. Una lectura que resuelve el documento —sus bases, inclusiones y parámetros— puede llevar además una atestación de entrega (delivery attestation), para un solo lector: una firma sobre el texto tal como se envió y sobre el manifiesto de la resolución (el digest del documento, cada dependencia con la que se resolvió y el digest del resultado resuelto), que incorpora la firma de autor. Un consumidor verifica la entrega, extrae de ella la firma de autor y la verifica también.
Claves
Las claves públicas de una organización están en instruction://pub/<owner>/keys.json, y los
consumidores las descubren a partir de la propia lectura. Cada clave está en uno de tres estados: active (activa),
retired (retirada) o revoked (revocada).
| Estado | Significado |
|---|---|
| active | firma las versiones nuevas |
| retired | ya no firma; las versiones anteriores se siguen verificando |
| revoked | las versiones firmadas con ella cuentan como no firmadas; los consumidores que exigen firmas se quedan con la versión que tenían |
Rota las claves con instruction keys rotate --org acme. Revoca solo en caso de compromiso de la clave: es un paso deliberado y no es reversible.
Firmar con tu propia clave
La mitad privada nunca sale de tu máquina; el registro solo ve la JWK pública.
instruction keygen --out acme-key.json --kid laptop
instruction keys add acme-key.json --org acme --label "Alice's laptop"
instruction publish <id> --sign-with acme-key.json --message "signed by hand" Verificar como consumidor
instruction watch instruction://acme/runbook@stable \
--require-signature --publisher https://instruction.md/pub/acme Fijar el editor es la mitad importante. Sin ello, verificas que alguien firmó el documento; con ello, verificas que lo firmó el editor que esperabas. Un editor sin fijar es un rechazo, no un nivel de confianza más débil.
Retirar una versión
instruction revoke <id> <version> retira una versión publicada. Antes, las referencias
(refs) deben haber dejado de apuntar a ella. Sigue siendo legible cuando se fija, de modo que una auditoría puede
seguir viendo qué ocurrió, y queda marcada, de modo que los consumidores se quedan con la versión que tenían en
lugar de aplicarla.
Lo que una firma no promete
Que el documento sea seguro. Una firma es procedencia, no un juicio: demuestra quién publicó estos bytes, y nada sobre si seguirlos es buena idea. Los controles que importan para eso están del lado del consumidor: los techos de capacidades, la revisión antes de que una referencia se mueva y una persona que decide qué se le permite seguir a un agente.