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).

EstadoSignificado
activefirma las versiones nuevas
retiredya no firma; las versiones anteriores se siguen verificando
revokedlas 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.

Shell
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

Shell
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.