Cryptographic Immutability Architecture

This document specifies the technical design, threat mitigations, and implementation structure for append-only DocTypes and outbox sealing in Framework M.

---

1. Architectural Strategy

Framework M implements a 4-layer defense-in-depth model for data integrity:

1. Layer 1: Application Layer (TamperManager[T])
   • Intercepts save() and delete() operations on models with tamper_proof = True.
   • Raises TamperProofMutationError on update or delete attempts.
2. Layer 2: Database Triggers (SchemaMapper)
   • Native SQL triggers (prevent_{table_name}_mutation() on PostgreSQL, BEFORE triggers on SQLite).
   • Aborts direct SQL UPDATE and DELETE queries executed outside the ORM.
3. Layer 3: Mathematical Chaining (JCS RFC 8785 + SHA-256)
   • Every row stores prev_hash and hash = sha256(prev_hash : canonical_json).
   • Any manual table modification breaks hash continuity and is flagged during audits.
4. Layer 4: Origin Envelope Attestation (CryptoOutboxSealer & Ingress)
   • Outbox messages are sealed with Ed25519 node and operator digital signatures.
   • IngressVerificationService validates signatures, sequence numbers, and replay windows before accepting records.

---

2. Component Structure & Code Mapping

Component	Responsibility	Code File
TamperProofMixin	Defines prev_hash and hash fields on DocType models	libs/framework-m-core/src/framework_m_core/domain/mixins.py
CryptoSignMixin	Defines outbox envelope signing fields (payload_hash, node_signature, etc.)	libs/framework-m-core/src/framework_m_core/domain/mixins.py
TamperManager	Manages hash calculation and mutation checks for GenericRepository	libs/framework-m-standard/src/framework_m_standard/adapters/db/tamper_manager.py
SchemaMapper	Generates SQL triggers preventing UPDATE / DELETE	libs/framework-m-standard/src/framework_m_standard/adapters/db/schema_mapper.py
CryptoOutboxSealer	Assigns sequence numbers, hash chains, and Ed25519 signatures	libs/framework-m-standard/src/framework_m_standard/adapters/crypto/outbox_sealer.py
prune_outbox_entries	Deletes acknowledged outbox entries and records _outbox_checkpoints	libs/framework-m-standard/src/framework_m_standard/adapters/db/outbox_pruner.py
IngressVerificationService	Central ingress gate checking signatures, sequence gaps, and replays	libs/framework-m-standard/src/framework_m_standard/services/ingress_verification_service.py
IntegrityAuditor	Continuous chain verification and Prometheus gauge export	libs/framework-m-standard/src/framework_m_standard/adapters/jobs/integrity_auditor.py

---

3. Threat Model & Safeguards

Threat Vector	DBA / Attacker Action	System Mitigation	Outcome
Direct SQL Row Mutation	Runs UPDATE or DELETE in a SQL client	SQL triggers reject the statement with TAMPER REJECTED	Transaction aborts; no data changes
Trigger Bypass Modification	Runs ALTER TABLE ... DISABLE TRIGGER, alters rows, re-enables triggers	Hash chaining breaks: hash != sha256(prev_hash : JCS(payload))	Detected by IntegrityAuditor and m audit forensic-trace
Network Replay Attack	Captures and re-transmits valid signed outbox envelope	SequenceTracker checks sequence_no <= last_sequence	Ingress rejects with DUPLICATE_REPLAY
Sequence Gap Injection	Drops packets or injects out-of-order sequence numbers	SequenceTracker checks sequence_no > expected_sequence	Ingress rejects with SEQUENCE_GAP_DETECTED and routes to quarantine
Forged Record Insertion	Injects synthetic outbox rows into transit	Node signature verification fails against KeyRegistryRepository	Ingress rejects with INVALID_NODE_SIGNATURE

---

4. Scope Boundaries

What is In-Scope

1. SQL Immutability: Enforcing append-only restrictions in PostgreSQL and SQLite.
2. Deterministic Serialization: RFC 8785 JSON canonicalization without whitespace discrepancies.
3. Partitioned Sequencing: Chaining hashes and sequence numbers independently per (node_id, stream_id).
4. Key Providers & Signatures: Software Ed25519 node keys (SoftwareKeyProvider) and WebAuthn / FIDO2 operator credentials (OperatorTokenService).
5. Continuous Auditing: Background verification jobs and CLI diagnostic tools.

What is Out-of-Scope

1. Raw Storage Destruction: Dropping database tables or deleting disk files directly (rm -rf) cannot be prevented by application software. Mitigated by replica backups.
2. Business Ledger Accounting: Verifying that debits equal credits in double-entry bookkeeping is the domain responsibility of downstream accounting applications.
3. External Event Store Clients: The ProjectionRehydrationProtocol defines the interface; concrete cluster drivers (Kafka, external ledger services) are implemented by external packages.