Modelo de Evidencia del Grabador y Arquitectura de Integridad

Audience: Engineers implementing envelope ingestion, hashing, signing, Audiencia: Ingenieros que implementan la ingestión de sobres, hashing, firma y verificación de integridad.

Tabla de Contenidos

Resumen Ejecutivo
Identidad y Primitivas de Esquema
Modelo de Sobre y Segmento
Codificación y Hashing Canónicos
Integridad del Archivo Adjunto
Modelo de Firma
Resultado de Verificación Álgebra
Referencia Cruzada Archivo por Archivo

Resumen Ejecutivo

La integridad del grabador se basa en bytes canónicos más enlace criptográfico:

hashes de contenido del sobre sobre vistas hashables canónicas de 11 campos,
hashes de cadena que vinculan cada sobre al estado anterior,
vinculación de la génesis del segmento y la cadena de predecesores.
firmas de sobre opcionales sobre los bytes del hash de contenido.

F:crates/recorder-envelope/src/envelope.rs L46-L92 F:crates/recorder-envelope/src/encoding.rs L252-L296 F:crates/recorder-envelope/src/segment.rs L39-L66

Identidad y Primitivas de Esquema

IDs respaldados por UUIDv7: EnvelopeId, SegmentId, BundleId.
IDs de cadena con validación: EventType, ActorId, EnvironmentId, etc.
String-backed IDs fail closed on empty, whitespace-only, and Los IDs respaldados por cadenas fallan en cerrar cuando la entrada está vacía, contiene solo espacios en blanco o caracteres de control.
String-backed IDs enforce explicit max-length bounds (256 for Los IDs respaldados por cadenas imponen límites máximos de longitud explícitos (256 para trace/session/actor/environment, 128 para event/adapter IDs).
String-backed ID serde paths are constructor-validated so hostile JSON cannot Las rutas de serde de ID respaldadas por cadenas son validadas por el constructor, por lo que un JSON hostil no puede eludir las invariantes.
KeyId is strict canonical lowercase hex(SHA-256(public_key_bytes)) KeyId es estrictamente canónico en minúsculas hex(SHA-256(public_key_bytes)) (64 caracteres).
SchemaVersion es explícito y actualmente está fijado en 1 (CURRENT_SCHEMA_VERSION).

F:crates/recorder-core/src/identity.rs L31-L55 F:crates/recorder-core/src/identity.rs L205-L647 F:crates/recorder-core/src/schema.rs L24-L49

Modelo de Sobre y Segmento

Estados del sobre

UnsealedEnvelope: campos hashables proporcionados por el adaptador.
Envelope: recorder-sealed record with content_hash, chain_hash, Sobre: registro sellado por el grabador con content_hash, chain_hash, sequence, segment_id y firma opcional.

F:crates/recorder-envelope/src/envelope.rs L98-L131 F:crates/recorder-envelope/src/envelope.rs L46-L92

Invariantes del constructor

EnvelopeBuilder impone campos requeridos, tiempo reclamado en UTC y un orden de adjuntos determinista antes de producir un UnsealedEnvelope. F:crates/recorder-envelope/src/envelope.rs L284-L328

Estructura del segmento

SegmentGenesis es metadatos estructurales (no un sobre) y ancla el cálculo de primera cadena; los campos predecesores deben estar establecidos conjuntamente o ausentes. recorder_id está limitado por la misma longitud máxima que ActorId y las rutas de deserialización son validadas por el constructor. F:crates/recorder-envelope/src/segment.rs L39-L109

SealRecord captura el estado final del segmento y la taxonomía de SealReason. F:crates/recorder-envelope/src/segment.rs L116-L170

Codificación y Hashing Canónicos

El grabador utiliza JCS (serde_jcs) sobre estructuras de vista hashables privadas. Invariantes importantes:

None se serializa como null en la salida canónica.
las marcas de tiempo utilizan un formato UTC fijo de 9 dígitos en nanosegundos.
las referencias de los archivos adjuntos están ordenadas por hash hexadecimal en vistas canónicas.

F:crates/recorder-envelope/src/encoding.rs L19-L31 F:crates/recorder-envelope/src/encoding.rs L48-L77 F:crates/recorder-envelope/src/encoding.rs L148-L162

Hash model:

content_hash = H(canonical_bytes)
chain_hash = H(prev_chain_hash || content_hash)
el primer sobre en el segmento utiliza H(segment_genesis_hash || content_hash)

F:crates/recorder-envelope/src/encoding.rs L239-L246 F:crates/recorder-envelope/src/encoding.rs L262-L273 F:crates/recorder-envelope/src/encoding.rs L285-L296

Las funciones hash son identificadas por algoritmos y se pueden conectar a través de HashFunction. El valor predeterminado actual es Sha256HashFunction. F:crates/recorder-core/src/hash.rs L200-L274

Integridad del archivo adjunto

Dos representaciones de adjuntos:

AttachmentData: bytes en línea enviados durante la ingestión.
AttachmentRef: metadatos dirigidos por contenido incrustados en sobres.

AttachmentRef y AttachmentData rechazan valores de content_type vacíos, que solo contengan espacios en blanco y que contengan caracteres de control, imponen una longitud máxima (255), y deserializan AttachmentRef a través de la validación del constructor. AttachmentData también requiere bytes no vacíos. F:crates/recorder-envelope/src/attachment.rs L35-L85 F:crates/recorder-envelope/src/attachment.rs L99-L133

Modelo de Firma

Contrato principal:

EnvelopeSigner firma los bytes de content_hash.
SignatureVerifier verifica los bytes del mensaje bajo claves específicas del algoritmo.
TrustRoot and TrustPolicy define trusted key material and signature TrustRoot y TrustPolicy definen el material de clave confiable y la política de aceptación de firmas (AnyTrustedKey, AllMustSign, Threshold).

F:crates/recorder-core/src/signature.rs L131-L270 F:crates/recorder-core/src/signature.rs L301-L337

Implementación actual:

Ed25519Signer derives key ID as hex(SHA-256(public_key_bytes)) and signs content_hash. F:crates/recorder-envelope/src/signer.rs L68-L113
Ed25519SignatureVerifier uses strict verification. F:crates/recorder-envelope/src/signature.rs L32-L95
Verifier phase 6 uses trust-root lookup + algorithm dispatch and applies policy checks after per-envelope signature validation. F:crates/recorder/src/verifier.rs L509-L651

Resultado de Verificación Álgebra

recorder-envelope define tipos de datos de verificación, mientras que la verificación algorítmica se ejecuta en recorder.

Estructuras clave:

VerificationManifest y ManifestSegmentEntry
VerificationVerdict y VerdictStatus
CheckResult, CheckType y verificaciones especializadas de cadena/cruzadas/firmas
VerificationWarning para hallazgos no fatales

F:crates/recorder-envelope/src/verification.rs L39-L79 F:crates/recorder-envelope/src/verification.rs L85-L132 F:crates/recorder-envelope/src/verification.rs L189-L266

Referencia Cruzada Archivo por Archivo

Área	Archivo	Notas
Contratos de identidad	`crates/recorder-core/src/identity.rs`	Validación de ID y nuevos tipos de serialización-estables.
Contratos de hash	`crates/recorder-core/src/hash.rs`	Tipos de hash, igualdad en tiempo constante, registro de algoritmos.
Contratos de firma	`crates/recorder-core/src/signature.rs`	Rasgos de firmante/verificador y forma de firma de sobre.
Modelo de sobre	`crates/recorder-envelope/src/envelope.rs`	Formas selladas/no selladas e invariantes del constructor.
Codificación canónica	`crates/recorder-envelope/src/encoding.rs`	Bytes canónicos JCS y fórmulas de cadena.
Modelo de segmento	`crates/recorder-envelope/src/segment.rs`	Metadatos de génesis y sello.
Adjuntos	`crates/recorder-envelope/src/attachment.rs`	Referencias de adjuntos dirigidos por contenido.
Modelo de verificación	`crates/recorder-envelope/src/verification.rs`	Álgebra de veredicto y resultado de verificación.
Verificación Ed25519	`crates/recorder-envelope/src/signature.rs`	Implementación estricta de verificación de firma.
Firma Ed25519	`crates/recorder-envelope/src/signer.rs`	Implementación de firma de sobre.