hammer/docs/09-trust-model.md

SDD 09 — Modelo de confianza

La premisa de compartir en hammer es "verificar, no confiar": nunca ejecutas un binario ajeno; reproduces una receta sobre código fuente público y compruebas que obtienes el mismo resultado. Esto sólo funciona si el build es determinista y si el intercambio está firmado y, opcionalmente, anclado a un log de transparencia.

1. La cadena de confianza

   código fuente público (repo@commit fijado)
        │  +  patch declarado en el .swm
        ▼
   build determinista en TU laboratorio local
        │  →  artifact_hash reproducible
        ▼
   ¿coincide con el expected_hash del autor?
        ├─ sí  → obtuviste exactamente su binario, sin descargarlo. Confianza derivada del código, no del autor.
        └─ no  → algo difiere (pin, patch, toolchain). hammer te dice qué. No promueves.

El binario del autor nunca viaja. Viaja la receta. La confianza no está en "el binario de sergio es bueno", sino en "el código fuente público + esta transformación produce esto, y lo verifiqué yo mismo".

2. Determinismo como cimiento

Todo esto descansa en que dos máquinas con la misma entrada produzcan el mismo artifact_hash (SDD 02). Requisitos prácticos de reproducibilidad:

• Toolchain fijado. El zig/compilador y su versión forman parte del hash de entrada.
• Commits fijados. Nada de HEAD (ADR 0006).
• Sandbox hermético. Sin red durante el build, sin fugas del host (SDD 02 §3).
• Eliminación de no-determinismo. Timestamps embebidos, rutas absolutas, orden de archivos, paralelismo no determinista → se normalizan (p. ej. SOURCE_DATE_EPOCH, orden estable).

Cuando un build no reproduce, es un bug a corregir, no una excepción a tolerar. La reproducibilidad bit-a-bit es objetivo, no aspiración.

3. Firma del .swm

Un .swm puede ir firmado (Ed25519). La firma cubre el contenido del manifiesto (base + mutations). Sirve para:

• Autoría: saber quién publicó la receta.
• Integridad: que no se alteró en tránsito.

La firma no sustituye la verificación reproducible — un autor firmado podría declarar un expected_hash que no corresponde a su patch; por eso hammer apply siempre reproduce y compara, firme o no.

4. Log de transparencia (visión, opt-in)

Para compartir en comunidad sin un repositorio central de binarios de confianza, los .swm publicados pueden anclarse a un log de transparencia append-only (estilo Sigstore/Rekor):

• cada .swm publicado deja una entrada inmutable (hash del manifiesto + firma + timestamp),
• cualquiera puede auditar la historia: qué se publicó, por quién, cuándo,
• detecta sustituciones silenciosas y "split-view".

Esto es opt-in y de fase posterior; el modelo base (reproducir + firmar) ya da la garantía fuerte: no ejecutas binarios ajenos.

5. TrustStore local

Claves públicas en las que el usuario confía para autoría (no para ejecución):

/var/lib/hammer/trust/
    sergio.ed25519.pub
    comunidad-foo.ed25519.pub

hammer apply reporta el estado de firma (trusted / unknown-key / bad-sig / unsigned) pero la decisión de promover sigue dependiendo de la verificación reproducible + el commit humano.

6. Resumen de garantías

Amenaza	Mitigación
Ejecutar binario ajeno malicioso	No se ejecutan binarios ajenos; se reproduce desde fuente
Receta alterada en tránsito	Firma Ed25519 del .swm
Build no reproducible / backdoor en toolchain	Toolchain fijado en el hash + determinismo verificado
Sustitución silenciosa en la comunidad	Log de transparencia (opt-in)
Promoción accidental de algo malo	Overlay + commit humano explícito

7. Interfaz

// hammer-core
pub fn sign_swm(swm: &Swm, key: &Ed25519PrivateKey) -> Signature;
pub fn verify_swm(swm: &Swm, trust: &TrustStore) -> SigStatus;
pub fn reproduce_and_compare(swm: &Swm, store: &Store) -> Result<Vec<HashMatch>>;