Рыба проекта. Минимальная функциональность

2026-08-03 22:22:24 +03:00
commit 8c8631ac9c
80 changed files with 10618 additions and 0 deletions
@@ -0,0 +1,624 @@
+// Package composite implements the v2 .pqenc artifact format: a dual-KEM
+// (post-quantum + classical) hybrid AEAD with inherent downgrade resistance.
+//
+// Layout of an artifact (all multi-byte fields are big-endian):
+//
+//	[magic u32 = 0x47535051 "GSPQ"]              [0:4]
+//	[version u16 = 0x0002]                       [4:6]
+//	[flags u32 = 0x00000000 (reserved, must==0)]  [6:10]
+//	[nRecipients u8]                             [10]
+//
+//	for each recipient slot i (positional: slot 0 = PQ, slot 1 = classical):
+//	  [schemeID u16] [keyID 8B] [ctLen u32] [ciphertext ctLen bytes]
+//
+//	[wrapNonce 12B] [wrappedCEK 48B] [firstPayloadNonce 12B]
+//
+//	chunk records (until a chunk with flags&0x01==1 is seen):
+//	  [len u32 = ciphertext length incl. 16B tag] [flags u8] [ciphertext]
+//
+// The content key (CEK, 32B) is wrapped with kekFinal — the HKDF combiner
+// of the two KEM shared secrets — using AES-256-GCM (AAD = version u16 BE).
+// Payload is encrypted with AES-256-GCM under CEK in 64 KiB chunks; a
+// zero-length final marker chunk (flags&0x01==1) is ALWAYS emitted on EOF
+// regardless of the previous chunk's fullness, providing explicit AEAD
+// integrity for the logical end-of-stream.
+package composite
+
+import (
+	"bytes"
+	"crypto/aes"
+	"crypto/cipher"
+	"crypto/hkdf"
+	"crypto/sha256"
+	"encoding/binary"
+	"errors"
+	"io"
+
+	"git.tswf.io/infra/go-synapse-backupper/pkg/domain/crypto"
+)
+
+// Sentinel errors surfaced by the composite Encryptor/Decryptor.
+var (
+	// ErrMalformedHeader indicates the artifact header is structurally
+	// invalid (bad magic, reserved flags, out-of-range nRecipients, oversized
+	// recipient ciphertext length, or premature EOF while reading fixed
+	// metadata).
+	ErrMalformedHeader = errors.New("composite: malformed header")
+
+	// ErrUnsupportedVersion indicates the artifact's version field is not
+	// 0x0002. Decryption stops at the version check — no AES/GCM operations
+	// are attempted and no recipient state is allocated.
+	ErrUnsupportedVersion = errors.New("composite: unsupported artifact version")
+
+	// ErrWrongKeys indicates one of the supplied private keys does not match
+	// the recipient slot it was routed to (positional). Signal: the priv's
+	// KeyID() does not equal the slot's keyID, OR the KEM Decapsulate failed
+	// for the slot's ciphertext.
+	ErrWrongKeys = errors.New("composite: wrong recipient keys")
+
+	// ErrTamperingDetected indicates the wrappedCEK or a payload chunk failed
+	// AES-GCM authentication: the cancellation or modification of ciphertext
+	// bytes is cryptographically rejected.
+	ErrTamperingDetected = errors.New("composite: tampering detected")
+
+	// ErrNonceCounterWrapped indicates the per-chunk 64-bit counter
+	// (chunkNonce[4:12]) wrapped around to zero while encrypting or
+	// decrypting an additional chunk — the nonce sequence is exhausted.
+	ErrNonceCounterWrapped = errors.New("composite: nonce counter wrapped")
+
+	// ErrMalformedChunk indicates a chunk record failed structural
+	// validation: zero-length non-final chunk (infinite-loop DoS) or
+	// oversized ciphertext (over the 64 KiB+16 maximum).
+	ErrMalformedChunk = errors.New("composite: malformed chunk")
+
+	// ErrUnexpectedEOF indicates the chunk stream ended before any chunk
+	// with flags&0x01==1 (logical end-of-stream marker) was observed.
+	ErrUnexpectedEOF = errors.New("composite: unexpected end of stream")
+)
+
+// Format constants.
+const (
+	magic                     uint32 = 0x47535051 // "GSPQ"
+	version                   uint16 = 0x0002
+	flags                     uint32 = 0x00000000
+	maxRecipients             int    = 2
+	chunkSize                 int    = 64 * 1024
+	gcmTagLen                 int    = 16
+	maxRecipientCiphertextLen int    = 1 << 20 // MiB cap on a single recipient ciphertext
+	wrapNonceLen              int    = 12
+	wrappedCekLen             int    = 48 // 32-byte CEK + 16-byte GCM tag
+	firstPayloadNonceLen      int    = 12
+	kekLen                    int    = 32
+	infoPq                    string = "git.tswf.io/infra/go-synapse-backupper/v2/kek/pq"
+	infoComposite             string = "git.tswf.io/infra/go-synapse-backupper/v2/kek/composite"
+)
+
+// Chunk flag bits.
+const (
+	flagFinal byte = 0x01
+)
+
+// encryptor is the composite Encryptor implementation backed by a Registry
+// of KEM factories. Recipients are routed positionally: slot 0 = PQ, slot 1
+// = classical.
+type encryptor struct {
+	registry crypto.Registry
+}
+
+// NewEncryptor returns a composite Encryptor that resolves KEM schemes via
+// the provided Registry (Registry.Lookup(schemeID)).
+func NewEncryptor(
+	registry crypto.Registry,
+) crypto.Encryptor {
+	return &encryptor{
+		registry: registry,
+	}
+}
+
+// Encrypt encrypts plaintext to multiple recipients under the v2 artifact
+// format and streams the result to sink. Exactly two recipients must be
+// supplied — slot 0 (PQ) and slot 1 (classical).
+func (e *encryptor) Encrypt(
+	plaintext io.Reader,
+	recipients []crypto.RecipientPub,
+	sink io.Writer,
+	rand io.Reader,
+) error {
+	if len(recipients) != maxRecipients {
+		return ErrMalformedHeader
+	}
+	pqPub, classicalPub := recipients[0], recipients[1]
+
+	// Generate the per-message content key (32B for AES-256).
+	cek := make([]byte, kekLen)
+	if _, err := io.ReadFull(rand, cek); err != nil {
+		return err
+	}
+
+	// Bind KEM adapters through the registry — no direct adapter imports.
+	pqFactory, err := e.registry.Lookup(pqPub.SchemeID())
+	if err != nil {
+		return err
+	}
+	classicalFactory, err := e.registry.Lookup(classicalPub.SchemeID())
+	if err != nil {
+		return err
+	}
+	pqKem := pqFactory()
+	classicalKem := classicalFactory()
+
+	// Encapsulate to each recipient.
+	// ADAPTER CONTRACT (pinned verbatim): adapters return (ct, ss) —
+	// composite unpacks in that order at each call site.
+	pqCt, ssPq, err := pqKem.Encapsulate(pqPub, rand)
+	if err != nil {
+		return err
+	}
+	classicalCt, ssClassical, err := classicalKem.Encapsulate(classicalPub, rand)
+	if err != nil {
+		return err
+	}
+
+	// HKDF combiner (verbatim per plan Metis B1):
+	//   PRK1 = HKDF-Extract(ssPq, salt=nil)
+	//   kek1 = HKDF-Expand(prk1, infoPq, 32)
+	//   IKM  = kek1 || ssClassical     (with defensive copy of kek1)
+	//   PRK2 = HKDF-Extract(IKM, salt=nil)
+	//   kekFinal = HKDF-Expand(prk2, infoComposite, 32)
+	kekFinal, err := deriveCompositeKEK(ssPq, ssClassical)
+	if err != nil {
+		return err
+	}
+
+	// Wrap the CEK via AES-256-GCM with AAD = version u16 BE = {0x00, 0x02}.
+	wrapNonce := make([]byte, wrapNonceLen)
+	if _, err := io.ReadFull(rand, wrapNonce); err != nil {
+		return err
+	}
+	kekBlock, err := aes.NewCipher(kekFinal)
+	if err != nil {
+		return err
+	}
+	wrapGcm, err := cipher.NewGCM(kekBlock)
+	if err != nil {
+		return err
+	}
+	wrappedCek := wrapGcm.Seal(nil, wrapNonce, cek, []byte{0x00, 0x02})
+
+	// firstPayloadNonce seeds the per-chunk nonce stream.
+	firstPayloadNonce := make([]byte, firstPayloadNonceLen)
+	if _, err := io.ReadFull(rand, firstPayloadNonce); err != nil {
+		return err
+	}
+
+	// Emit the artifact header.
+	if err := writeHeader(
+		sink,
+		pqPub, classicalPub,
+		pqCt, classicalCt,
+		wrapNonce, wrappedCek, firstPayloadNonce,
+	); err != nil {
+		return err
+	}
+
+	// Encrypt the payload into chunks.
+	payloadBlock, err := aes.NewCipher(cek)
+	if err != nil {
+		return err
+	}
+	payloadGcm, err := cipher.NewGCM(payloadBlock)
+	if err != nil {
+		return err
+	}
+	return encryptChunks(plaintext, sink, payloadGcm, firstPayloadNonce)
+}
+
+// writeHeader serializes the v2 artifact header.
+//
+// Layout (see package doc):
+//
+//	magic(4) + version(2) + flags(4) + nRecipients(1)
+//	  + per-recipient: schemeID(2) + keyID(8) + ctLen(4) + ciphertext
+//	  + wrapNonce(12) + wrappedCEK(48) + firstPayloadNonce(12)
+func writeHeader(
+	w io.Writer,
+	pqPub, classicalPub crypto.RecipientPub,
+	pqCt, classicalCt,
+	wrapNonce, wrappedCek, firstPayloadNonce []byte,
+) error {
+	var buf bytes.Buffer
+	var b4 [4]byte
+
+	binary.BigEndian.PutUint32(b4[:], magic)
+	buf.Write(b4[:]) // [0:4] magic
+
+	binary.BigEndian.PutUint16(b4[:2], version)
+	buf.Write(b4[:2]) // [4:6] version
+
+	binary.BigEndian.PutUint32(b4[:], flags)
+	buf.Write(b4[:]) // [6:10] flags
+
+	// [10] nRecipients — composite v2 always carries exactly two slots.
+	buf.WriteByte(byte(maxRecipients))
+
+	// Slot 0 (PQ).
+	binary.BigEndian.PutUint16(b4[:2], pqPub.SchemeID())
+	buf.Write(b4[:2])
+	if len(pqPub.KeyID()) != 8 {
+		return ErrMalformedHeader
+	}
+	buf.Write(pqPub.KeyID())
+	binary.BigEndian.PutUint32(b4[:], uint32(len(pqCt)))
+	buf.Write(b4[:])
+	buf.Write(pqCt)
+
+	// Slot 1 (classical).
+	binary.BigEndian.PutUint16(b4[:2], classicalPub.SchemeID())
+	buf.Write(b4[:2])
+	if len(classicalPub.KeyID()) != 8 {
+		return ErrMalformedHeader
+	}
+	buf.Write(classicalPub.KeyID())
+	binary.BigEndian.PutUint32(b4[:], uint32(len(classicalCt)))
+	buf.Write(b4[:])
+	buf.Write(classicalCt)
+
+	// wrapNonce + wrappedCEK + firstPayloadNonce.
+	buf.Write(wrapNonce)
+	buf.Write(wrappedCek)
+	buf.Write(firstPayloadNonce)
+
+	_, err := w.Write(buf.Bytes())
+	return err
+}
+
+// encryptChunks encrypts plaintext into 64 KiB AES-256-GCM chunks under CEK
+// and streams them to w. A zero-length final marker chunk (flags&0x01==1)
+// is ALWAYS emitted on EOF regardless of the previous chunk's fullness.
+func encryptChunks(
+	plaintext io.Reader,
+	w io.Writer,
+	gcm cipher.AEAD,
+	firstPayloadNonce []byte,
+) error {
+	chunkNonce := make([]byte, gcm.NonceSize())
+	copy(chunkNonce, firstPayloadNonce)
+
+	buf := make([]byte, chunkSize)
+	var lenB [4]byte
+
+	for {
+		readN, readErr := io.ReadFull(plaintext, buf)
+		hasData := readN > 0
+		eof := readErr == io.EOF || readErr == io.ErrUnexpectedEOF
+
+		if hasData {
+			// Body chunk, flags = 0x00.
+			ciphertext := gcm.Seal(nil, chunkNonce, buf[:readN], nil)
+			binary.BigEndian.PutUint32(lenB[:], uint32(len(ciphertext)))
+			if _, err := w.Write(lenB[:]); err != nil {
+				return err
+			}
+			if _, err := w.Write([]byte{0x00}); err != nil {
+				return err
+			}
+			if _, err := w.Write(ciphertext); err != nil {
+				return err
+			}
+			// Increment counter for the next chunk; the top 4 bytes of the
+			// nonce ([0:4]) are untouched.
+			if err := incrementCounter(chunkNonce); err != nil {
+				return err
+			}
+		}
+
+		if eof {
+			// Final marker chunk — zero-length plaintext, flags = 0x01,
+			// ciphertext is just the 16-byte GCM tag. ALWAYS emitted.
+			ciphertext := gcm.Seal(nil, chunkNonce, nil, nil)
+			binary.BigEndian.PutUint32(lenB[:], uint32(len(ciphertext)))
+			if _, err := w.Write(lenB[:]); err != nil {
+				return err
+			}
+			if _, err := w.Write([]byte{flagFinal}); err != nil {
+				return err
+			}
+			if _, err := w.Write(ciphertext); err != nil {
+				return err
+			}
+			return nil
+		}
+		if readErr != nil {
+			return readErr
+		}
+	}
+}
+
+// incrementCounter mutates chunkNonce in place: reads the 64-bit big-endian
+// counter at chunkNonce[4:12], adds one, rejects wrap, writes back.
+// chunkNonce[0:4] (the random base) is preserved.
+func incrementCounter(chunkNonce []byte) error {
+	counter := binary.BigEndian.Uint64(chunkNonce[4:12])
+	newCounter := counter + 1
+	if newCounter <= counter {
+		return ErrNonceCounterWrapped
+	}
+	binary.BigEndian.PutUint64(chunkNonce[4:12], newCounter)
+	return nil
+}
+
+// decryptor is the composite Decryptor implementation. Slot routing is
+// positional; keyID equality is enforced as a fast wrong-key reject before
+// any AEAD operation.
+type decryptor struct {
+	registry crypto.Registry
+}
+
+// NewDecryptor returns a composite Decryptor that resolves KEM schemes via
+// the provided Registry.
+func NewDecryptor(
+	registry crypto.Registry,
+) crypto.Decryptor {
+	return &decryptor{
+		registry: registry,
+	}
+}
+
+// Decrypt parses the v2 artifact from src, decapsulates per slot using the
+// supplied private keys (positional: slot 0 ← privs[0], slot 1 ← privs[1]),
+// re-derives the composite KEK, unwraps the CEK, and streams decrypted
+// plaintext chunks to plaintext.
+func (d *decryptor) Decrypt(
+	src io.Reader,
+	privs []crypto.RecipientPriv,
+	plaintext io.Writer,
+) error {
+	// Prefix: magic(4) + version(2) + flags(4) + nRecipients(1) = 11 bytes.
+	const prefixLen = 11
+	var prefix [prefixLen]byte
+	if _, err := io.ReadFull(src, prefix[:]); err != nil {
+		return ErrMalformedHeader
+	}
+
+	if binary.BigEndian.Uint32(prefix[0:4]) != magic {
+		return ErrMalformedHeader
+	}
+
+	fileVersion := binary.BigEndian.Uint16(prefix[4:6])
+	if fileVersion != version {
+		// Stops BEFORE any flags/nRecipients validation, before any GCM
+		// work, before any recipient allocation.
+		return ErrUnsupportedVersion
+	}
+
+	if binary.BigEndian.Uint32(prefix[6:10]) != flags {
+		return ErrMalformedHeader
+	}
+
+	nRecipients := int(prefix[10])
+	if nRecipients < 1 || nRecipients > maxRecipients {
+		return ErrMalformedHeader
+	}
+	if nRecipients != maxRecipients {
+		// Composite v2 mandates exactly two slots.
+		return ErrMalformedHeader
+	}
+
+	// Per-recipient: each slot is `(meta 14B) (ciphertext ctLen B)` INLINE —
+	// slot0's ciphertext lives BETWEEN slot0's metadata and slot1's metadata
+	// (the inline-ct layout; see package doc). So parse strictly per-slot:
+	// read metadata → validate ctLen ≤ max → read ct → advance to next slot.
+	// The ctLen ≤ maxRecipientCiphertextLen check must fire BEFORE allocating/reading
+	// the per-slot ciphertext (test l: no OOM on malicious oversized value).
+	const perSlotMetaLen = 14
+	type slotMeta struct {
+		schemeID uint16
+		keyID    []byte
+		ctLen    uint32
+		ct       []byte
+	}
+	slots := make([]slotMeta, nRecipients)
+	for slotIndex := 0; slotIndex < nRecipients; slotIndex++ {
+		var meta [perSlotMetaLen]byte
+		if _, err := io.ReadFull(src, meta[:]); err != nil {
+			return ErrMalformedHeader
+		}
+		slot := &slots[slotIndex]
+		slot.schemeID = binary.BigEndian.Uint16(meta[0:2])
+		slot.keyID = append([]byte(nil), meta[2:10]...)
+		slot.ctLen = binary.BigEndian.Uint32(meta[10:14])
+		if int(slot.ctLen) > maxRecipientCiphertextLen {
+			return ErrMalformedHeader
+		}
+		slot.ct = make([]byte, slot.ctLen)
+		if slot.ctLen > 0 {
+			if _, err := io.ReadFull(src, slot.ct); err != nil {
+				return ErrMalformedHeader
+			}
+		}
+	}
+
+	// Trailing fixed region: wrapNonce(12) + wrappedCEK(48) + firstPayloadNonce(12) = 72B.
+	var tail [wrapNonceLen + wrappedCekLen + firstPayloadNonceLen]byte
+	if _, err := io.ReadFull(src, tail[:]); err != nil {
+		return ErrMalformedHeader
+	}
+	wrapNonce := tail[:wrapNonceLen]
+	wrappedCek := tail[wrapNonceLen : wrapNonceLen+wrappedCekLen]
+	firstPayloadNonce := tail[wrapNonceLen+wrappedCekLen:]
+
+	// Decapsulate per slot, routing privs positionally.
+	if len(privs) < nRecipients {
+		return ErrWrongKeys
+	}
+	sharedSecrets := make([][]byte, nRecipients)
+	for slotIndex := 0; slotIndex < nRecipients; slotIndex++ {
+		slot := slots[slotIndex]
+		priv := privs[slotIndex]
+		if priv == nil {
+			return ErrWrongKeys
+		}
+		if priv.SchemeID() != slot.schemeID {
+			return ErrWrongKeys
+		}
+		if !bytes.Equal(priv.KeyID(), slot.keyID) {
+			return ErrWrongKeys
+		}
+		factory, err := d.registry.Lookup(slot.schemeID)
+		if err != nil {
+			return ErrWrongKeys
+		}
+		kem := factory()
+		ss, err := kem.Decapsulate(priv, slot.ct)
+		if err != nil {
+			return ErrWrongKeys
+		}
+		sharedSecrets[slotIndex] = ss
+	}
+
+	kekFinal, err := deriveCompositeKEK(sharedSecrets[0], sharedSecrets[1])
+	if err != nil {
+		return err
+	}
+
+	// Unwrap CEK via AES-256-GCM. AAD = version u16 BE.
+	kekBlock, err := aes.NewCipher(kekFinal)
+	if err != nil {
+		return err
+	}
+	wrapGcm, err := cipher.NewGCM(kekBlock)
+	if err != nil {
+		return err
+	}
+	cek, err := wrapGcm.Open(nil, wrapNonce, wrappedCek, []byte{0x00, 0x02})
+	if err != nil {
+		return ErrTamperingDetected
+	}
+
+	// Setup payload AEAD under CEK.
+	payloadBlock, err := aes.NewCipher(cek)
+	if err != nil {
+		return err
+	}
+	payloadGcm, err := cipher.NewGCM(payloadBlock)
+	if err != nil {
+		return err
+	}
+
+	return decryptChunks(src, plaintext, payloadGcm, firstPayloadNonce)
+}
+
+// decryptChunks reads and decrypts chunk records until a final chunk
+// (flags & flagFinal != 0) is observed.
+func decryptChunks(
+	src io.Reader,
+	plaintext io.Writer,
+	gcm cipher.AEAD,
+	firstPayloadNonce []byte,
+) error {
+	chunkNonce := make([]byte, gcm.NonceSize())
+	copy(chunkNonce, firstPayloadNonce)
+
+	var lenB [4]byte
+	var flagB [1]byte
+
+	maxChunkCtLen := uint32(chunkSize + gcmTagLen)
+
+	for {
+		// Read chunk length u32 BE.
+		_, err := io.ReadFull(src, lenB[:])
+		if err == io.EOF || err == io.ErrUnexpectedEOF {
+			// No final marker chunk observed — premature end of stream.
+			return ErrUnexpectedEOF
+		}
+		if err != nil {
+			return err
+		}
+		length := binary.BigEndian.Uint32(lenB[:])
+
+		// Read flags u8.
+		_, err = io.ReadFull(src, flagB[:])
+		if err == io.EOF || err == io.ErrUnexpectedEOF {
+			return ErrUnexpectedEOF
+		}
+		if err != nil {
+			return err
+		}
+		flagsByte := flagB[0]
+		isFinal := flagsByte&flagFinal != 0
+
+		// Structural validation.
+		if length == 0 && !isFinal {
+			// Zero-length non-final chunk — infinite-loop DoS.
+			return ErrMalformedChunk
+		}
+		if length > maxChunkCtLen {
+			return ErrMalformedChunk
+		}
+
+		// Read ciphertext.
+		ciphertext := make([]byte, length)
+		if length > 0 {
+			if _, err := io.ReadFull(src, ciphertext); err != nil {
+				return ErrUnexpectedEOF
+			}
+		}
+
+		// AEAD open.
+		plaintextChunk, err := gcm.Open(nil, chunkNonce, ciphertext, nil)
+		if err != nil {
+			return ErrTamperingDetected
+		}
+
+		if len(plaintextChunk) > 0 {
+			if _, err := plaintext.Write(plaintextChunk); err != nil {
+				return err
+			}
+		}
+
+		if isFinal {
+			return nil
+		}
+
+		if err := incrementCounter(chunkNonce); err != nil {
+			return err
+		}
+	}
+}
+
+// deriveCompositeKEK applies the verbatim HKDF combiner from the plan:
+//
+//	PRK1      = HKDF-Extract(IKM=ss_pq, salt=nil)
+//	kek1      = HKDF-Expand(prk1, infoPq, 32)
+//	IKM       = kek1 || ss_classical     // defensive copy of kek1
+//	PRK2      = HKDF-Extract(IKM, salt=nil)
+//	kekFinal  = HKDF-Expand(prk2, infoComposite, 32)
+//
+// Go 1.26 stdlib crypto/hkdf returns ([]byte, error) directly from Extract
+// and Expand — no infinite io.Reader is involved, so neither io.ReadAll nor
+// io.ReadFull is needed; the spirit of the plan's "do not use io.ReadAll on
+// hkdf.Expand" guidance is preserved trivially.
+func deriveCompositeKEK(
+	ssPq, ssClassical []byte,
+) ([]byte, error) {
+	prk1, err := hkdf.Extract(sha256.New, ssPq, nil)
+	if err != nil {
+		return nil, err
+	}
+	kek1, err := hkdf.Expand(sha256.New, prk1, infoPq, kekLen)
+	if err != nil {
+		return nil, err
+	}
+	// Defensive copy of kek1 — append([]byte(nil), ...) avoids aliasing
+	// kek1's backing array when concatenating ssClassical (Metis B1).
+	ikmComposite := append(append([]byte(nil), kek1...), ssClassical...)
+	prk2, err := hkdf.Extract(sha256.New, ikmComposite, nil)
+	if err != nil {
+		return nil, err
+	}
+	kekFinal, err := hkdf.Expand(sha256.New, prk2, infoComposite, kekLen)
+	if err != nil {
+		return nil, err
+	}
+	return kekFinal, nil
+}
@@ -0,0 +1,949 @@
+package composite
+
+import (
+	"bytes"
+	"crypto/aes"
+	"crypto/cipher"
+	"crypto/rand"
+	"crypto/sha256"
+	"encoding/base64"
+	"encoding/binary"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"os"
+	"testing"
+
+	"git.tswf.io/infra/go-synapse-backupper/pkg/domain/crypto"
+)
+
+// ---------------------------------------------------------------------------
+// Test KEM harness
+//
+// The composite format pins slot 0 = PQ (schemeID 0x0006, ciphertext length
+// 1088) and slot 1 = classical (schemeID 0x0007, ciphertext length 32),
+// matching the real mlkem768 + x25519 adapter contracts. Adapters' priv types
+// are unexported and reject type-asserted impostors at Decapsulate, and the
+// composite todo's scope forbids touching adapter packages — so tests exercise
+// the composite with deterministic fake KEMs (registered under the SAME
+// schemeIDs as the real adapters). The committed golden fixture uses these
+// fakes; the composite production code is exercised end-to-end on the format,
+// the HKDF combiner, AES-256-GCM wrapping, and chunked AEAD.
+// ---------------------------------------------------------------------------
+
+const (
+	fakePqSchemeID        uint16 = 0x0006
+	fakeClassicalSchemeID uint16 = 0x0007
+	fakePqCtLen           int    = 1088 // matches crypto/mlkem EncapsulateKey768 ciphertext length
+	fakeClassicalCtLen    int    = 32   // matches X25519 ephemeral pubkey length
+	fakeSeedLen           int    = 32
+)
+
+// fakeKem derives a deterministic shared secret per pub/ct pair:
+//
+//	ss = SHA256(pub_raw_or_priv_raw || ct)
+//
+// where pub.raw and priv.raw are both the random seed; randomness lives only
+// in the ct (the call site's rand supplies ct bytes), so decapsulation with
+// the matching priv always recovers the encryption-time ss.
+type fakeKem struct {
+	schemeIDValue uint16
+	ctLenValue    int
+}
+
+func newFakePqKem() crypto.KEM {
+	return &fakeKem{schemeIDValue: fakePqSchemeID, ctLenValue: fakePqCtLen}
+}
+
+func newFakeClassicalKem() crypto.KEM {
+	return &fakeKem{schemeIDValue: fakeClassicalSchemeID, ctLenValue: fakeClassicalCtLen}
+}
+
+func (k *fakeKem) SchemeID() uint16 { return k.schemeIDValue }
+
+func (k *fakeKem) GenerateKeyPair(
+	rand io.Reader,
+) (
+	crypto.RecipientPub,
+	crypto.RecipientPriv,
+	error,
+) {
+	seed := make([]byte, fakeSeedLen)
+	if _, err := io.ReadFull(rand, seed); err != nil {
+		return nil, nil, err
+	}
+	return newFakePub(k.schemeIDValue, seed), newFakePriv(k.schemeIDValue, seed), nil
+}
+
+func (k *fakeKem) Encapsulate(
+	pub crypto.RecipientPub,
+	rand io.Reader,
+) (
+	ciphertext []byte,
+	sharedSecret []byte,
+	err error,
+) {
+	p, ok := pub.(*fakePub)
+	if !ok {
+		return nil, nil, errors.New("fakeKem: invalid pub type")
+	}
+	ciphertext = make([]byte, k.ctLenValue)
+	if _, err := io.ReadFull(rand, ciphertext); err != nil {
+		return nil, nil, err
+	}
+	return ciphertext, deriveFakeSS(p.raw, ciphertext), nil
+}
+
+func (k *fakeKem) Decapsulate(
+	priv crypto.RecipientPriv,
+	ciphertext []byte,
+) (
+	sharedSecret []byte,
+	err error,
+) {
+	p, ok := priv.(*fakePriv)
+	if !ok {
+		return nil, errors.New("fakeKem: invalid priv type")
+	}
+	if len(ciphertext) != k.ctLenValue {
+		return nil, errors.New("fakeKem: invalid ciphertext length")
+	}
+	return deriveFakeSS(p.raw, ciphertext), nil
+}
+
+func (k *fakeKem) LoadPriv(
+	raw []byte,
+) (
+	crypto.RecipientPriv,
+	error,
+) {
+	return newFakePriv(k.schemeIDValue, raw), nil
+}
+
+func deriveFakeSS(
+	raw, ciphertext []byte,
+) []byte {
+	h := sha256.New()
+	h.Write(raw)
+	h.Write(ciphertext)
+	return h.Sum(nil)
+}
+
+// fakePub / fakePriv — deterministic raw-bytes-backed recipients.
+type fakePub struct {
+	scheme uint16
+	raw    []byte
+	keyID  []byte
+}
+
+func newFakePub(
+	scheme uint16,
+	raw []byte,
+) *fakePub {
+	h := sha256.Sum256(raw)
+	return &fakePub{
+		scheme: scheme,
+		raw:    append([]byte(nil), raw...),
+		keyID:  h[:8],
+	}
+}
+
+func (f *fakePub) SchemeID() uint16 { return f.scheme }
+func (f *fakePub) KeyID() []byte    { return f.keyID }
+func (f *fakePub) Raw() []byte      { return f.raw }
+
+type fakePriv struct {
+	scheme uint16
+	raw    []byte
+	keyID  []byte
+}
+
+func newFakePriv(
+	scheme uint16,
+	raw []byte,
+) *fakePriv {
+	h := sha256.Sum256(raw)
+	return &fakePriv{
+		scheme: scheme,
+		raw:    append([]byte(nil), raw...),
+		keyID:  h[:8],
+	}
+}
+
+func (f *fakePriv) SchemeID() uint16 { return f.scheme }
+func (f *fakePriv) KeyID() []byte    { return f.keyID }
+func (f *fakePriv) Raw() []byte      { return f.raw }
+
+// fakeRegistry returns a Registry with the two fake KEMs registered under
+// the v2 slot schemeIDs.
+func fakeRegistry(
+	t *testing.T,
+) crypto.Registry {
+	t.Helper()
+	reg := crypto.NewRegistry()
+	if err := reg.Register(fakePqSchemeID, newFakePqKem); err != nil {
+		t.Fatalf("register pq fake: %v", err)
+	}
+	if err := reg.Register(fakeClassicalSchemeID, newFakeClassicalKem); err != nil {
+		t.Fatalf("register classical fake: %v", err)
+	}
+	return reg
+}
+
+// generateFakeKeyPair generates (pub, priv) for slot schemeID from rand.
+func generateFakeKeyPair(
+	t *testing.T,
+	reg crypto.Registry,
+	schemeID uint16,
+	rand io.Reader,
+) (
+	crypto.RecipientPub,
+	crypto.RecipientPriv,
+) {
+	t.Helper()
+	factory, err := reg.Lookup(schemeID)
+	if err != nil {
+		t.Fatalf("lookup 0x%04x: %v", schemeID, err)
+	}
+	pub, priv, err := factory().GenerateKeyPair(rand)
+	if err != nil {
+		t.Fatalf("generate 0x%04x: %v", schemeID, err)
+	}
+	return pub, priv
+}
+
+// standardHeaderLen returns the fixed artifact-header length given the two
+// slot ciphertext lengths: 11 (magic+version+flags+nRecipients) +
+// per-slot (14 + ctLen) + 72 (wrapNonce+wrappedCEK+firstPayloadNonce).
+func standardHeaderLen(
+	pqCtLen, classicalCtLen int,
+) int {
+	return 11 + (14 + pqCtLen) + (14 + classicalCtLen) + (12 + 48 + 12)
+}
+
+// countingReader wraps an io.Reader and counts how many bytes have been read
+// — used by the adversarial-parser tests to assert the parser does NOT
+// consume past the header before bailing out.
+type countingReader struct {
+	r io.Reader
+	n int64
+}
+
+func (c *countingReader) Read(
+	p []byte,
+) (int, error) {
+	readN, err := c.r.Read(p)
+	c.n += int64(readN)
+	return readN, err
+}
+
+// ---------------------------------------------------------------------------
+// Tests (a) through (p)
+// ---------------------------------------------------------------------------
+
+// (a) Golden format fixture.
+func TestGoldenFormat(
+	t *testing.T,
+) {
+	goldenBytes := mustReadFile(t, "testdata/golden-1byte.pqenc")
+
+	// Header byte offsets pinned verbatim — if any of these breaks, the
+	// on-disk format has drifted and old .pqenc files won't decrypt.
+	//   [0:4]    magic u32 BE      = 0x47535051
+	//   [4:6]    version u16 BE    = 0x0002
+	//   [6:10]   flags u32 BE      = 0x00000000
+	//   [10]     nRecipients u8    = 0x02
+	//   [11:13]  slot0 schemeID    = 0x0006
+	//   [13:21]  slot0 keyID 8B
+	//   [21:25]  slot0 ctLen u32   = 1088
+	//   [25:1113]  slot0 ciphertext (1088 bytes)
+	//   [1113:1115] slot1 schemeID = 0x0007
+	if binary.BigEndian.Uint32(goldenBytes[0:4]) != 0x47535051 {
+		t.Errorf("magic = 0x%08x, want 0x47535051", binary.BigEndian.Uint32(goldenBytes[0:4]))
+	}
+	if binary.BigEndian.Uint16(goldenBytes[4:6]) != 0x0002 {
+		t.Errorf("version = 0x%04x, want 0x0002", binary.BigEndian.Uint16(goldenBytes[4:6]))
+	}
+	if binary.BigEndian.Uint32(goldenBytes[6:10]) != 0x00000000 {
+		t.Errorf("flags = 0x%08x, want 0", binary.BigEndian.Uint32(goldenBytes[6:10]))
+	}
+	if goldenBytes[10] != 0x02 {
+		t.Errorf("nRecipients = 0x%02x, want 0x02", goldenBytes[10])
+	}
+	if binary.BigEndian.Uint16(goldenBytes[11:13]) != 0x0006 {
+		t.Errorf("slot0 schemeID = 0x%04x, want 0x0006", binary.BigEndian.Uint16(goldenBytes[11:13]))
+	}
+	if binary.BigEndian.Uint16(goldenBytes[1113:1115]) != 0x0007 {
+		t.Errorf("slot1 schemeID = 0x%04x, want 0x0007", binary.BigEndian.Uint16(goldenBytes[1113:1115]))
+	}
+
+	// Decrypt-equality: reconstruct privs from committed golden-keys.json
+	// and assert Decrypt yields the 0xAA plaintext committed via golden_generate.
+	pqPriv, classicalPriv := loadGoldenPrivs(t, "testdata/golden-keys.json")
+
+	dec := NewDecryptor(fakeRegistry(t))
+	out := &bytes.Buffer{}
+	if err := dec.Decrypt(
+		bytes.NewReader(goldenBytes),
+		[]crypto.RecipientPriv{pqPriv, classicalPriv},
+		out,
+	); err != nil {
+		t.Fatalf("Decrypt(golden) failed: %v", err)
+	}
+	if !bytes.Equal(out.Bytes(), []byte{0xAA}) {
+		t.Errorf("decrypted = %x, want [0xAA]", out.Bytes())
+	}
+}
+
+// (b) Round-trip on canonical input sizes.
+func TestRoundTrip(
+	t *testing.T,
+) {
+	sizes := []int{0, 1, 64*1024 - 1, 64 * 1024, 64*1024 + 1, 1 << 20}
+	for _, size := range sizes {
+		t.Run(fmt.Sprintf("size=%d", size), func(t *testing.T) {
+			plaintext := make([]byte, size)
+			for i := 0; i < size; i++ {
+				plaintext[i] = byte(i)
+			}
+
+			reg := fakeRegistry(t)
+			enc := NewEncryptor(reg)
+			dec := NewDecryptor(reg)
+
+			pqPub, pqPriv := generateFakeKeyPair(t, reg, fakePqSchemeID, rand.Reader)
+			classicalPub, classicalPriv := generateFakeKeyPair(t, reg, fakeClassicalSchemeID, rand.Reader)
+
+			var encrypted bytes.Buffer
+			if err := enc.Encrypt(
+				bytes.NewReader(plaintext),
+				[]crypto.RecipientPub{pqPub, classicalPub},
+				&encrypted,
+				rand.Reader,
+			); err != nil {
+				t.Fatalf("Encrypt: %v", err)
+			}
+
+			out := &bytes.Buffer{}
+			if err := dec.Decrypt(
+				bytes.NewReader(encrypted.Bytes()),
+				[]crypto.RecipientPriv{pqPriv, classicalPriv},
+				out,
+			); err != nil {
+				t.Fatalf("Decrypt: %v", err)
+			}
+			if !bytes.Equal(out.Bytes(), plaintext) {
+				t.Errorf("round-trip mismatch: got %d bytes, want %d", out.Len(), len(plaintext))
+			}
+		})
+	}
+}
+
+// (c) Empty plaintext produces exactly ONE chunk with flags=0x01 and a 16B
+// (tag-only) ciphertext.
+func TestEmptyPlaintextSingleFinalChunk(
+	t *testing.T,
+) {
+	reg := fakeRegistry(t)
+	enc := NewEncryptor(reg)
+
+	pqPub, _ := generateFakeKeyPair(t, reg, fakePqSchemeID, rand.Reader)
+	classicalPub, _ := generateFakeKeyPair(t, reg, fakeClassicalSchemeID, rand.Reader)
+
+	var encrypted bytes.Buffer
+	if err := enc.Encrypt(
+		bytes.NewReader(nil),
+		[]crypto.RecipientPub{pqPub, classicalPub},
+		&encrypted,
+		rand.Reader,
+	); err != nil {
+		t.Fatalf("Encrypt: %v", err)
+	}
+
+	headerLen := standardHeaderLen(fakePqCtLen, fakeClassicalCtLen)
+	chunks := encrypted.Bytes()[headerLen:]
+
+	// Expected record: [len=16 u32 (4B)][flags=0x01 (1B)][ciphertext (16B)].
+	if len(chunks) != 4+1+16 {
+		t.Fatalf("expected 21-byte chunk record, got %d bytes", len(chunks))
+	}
+	if ctLen := binary.BigEndian.Uint32(chunks[0:4]); ctLen != 16 {
+		t.Errorf("ctLen = %d, want 16 (tag-only)", ctLen)
+	}
+	if chunks[4] != 0x01 {
+		t.Errorf("flags = 0x%02x, want 0x01", chunks[4])
+	}
+	if len(chunks[5:]) != 16 {
+		t.Errorf("ciphertext = %d bytes, want 16 (tag-only)", len(chunks[5:]))
+	}
+}
+
+// (d) Exactly-64KiB input produces TWO chunks: full body (flags=0x00) and
+// zero-length final marker (flags=0x01).
+func TestExactly64KiBTwoChunks(
+	t *testing.T,
+) {
+	reg := fakeRegistry(t)
+	enc := NewEncryptor(reg)
+
+	pqPub, _ := generateFakeKeyPair(t, reg, fakePqSchemeID, rand.Reader)
+	classicalPub, _ := generateFakeKeyPair(t, reg, fakeClassicalSchemeID, rand.Reader)
+
+	plaintext := bytes.Repeat([]byte{0xCC}, 64*1024)
+	var encrypted bytes.Buffer
+	if err := enc.Encrypt(
+		bytes.NewReader(plaintext),
+		[]crypto.RecipientPub{pqPub, classicalPub},
+		&encrypted,
+		rand.Reader,
+	); err != nil {
+		t.Fatalf("Encrypt: %v", err)
+	}
+
+	headerLen := standardHeaderLen(fakePqCtLen, fakeClassicalCtLen)
+	chunks := encrypted.Bytes()[headerLen:]
+
+	// Chunk 1: full body. ct = 64 KiB plaintext + 16B tag.
+	const bodyCtLen = 64*1024 + 16
+	if ctLen := binary.BigEndian.Uint32(chunks[0:4]); ctLen != bodyCtLen {
+		t.Errorf("chunk1 ctLen = %d, want %d", ctLen, bodyCtLen)
+	}
+	if chunks[4] != 0x00 {
+		t.Errorf("chunk1 flags = 0x%02x, want 0x00", chunks[4])
+	}
+
+	// Chunk 2: zero-length final marker (ct = 16B tag), flags = 0x01.
+	chunk2Start := 4 + 1 + bodyCtLen
+	if chunk2Start+5 > len(chunks) {
+		t.Fatalf("file truncated before chunk 2: need offset %d, have %d", chunk2Start+5, len(chunks))
+	}
+	if ctLen := binary.BigEndian.Uint32(chunks[chunk2Start : chunk2Start+4]); ctLen != 16 {
+		t.Errorf("chunk2 ctLen = %d, want 16 (zero-length marker)", ctLen)
+	}
+	if chunks[chunk2Start+4] != 0x01 {
+		t.Errorf("chunk2 flags = 0x%02x, want 0x01", chunks[chunk2Start+4])
+	}
+
+	chunk3Start := chunk2Start + 4 + 1 + 16
+	if chunk3Start != len(chunks) {
+		t.Errorf("expected exactly 2 chunks; remaining = %d bytes after chunk 2", len(chunks)-chunk3Start)
+	}
+}
+
+// (e) Counter wrap-around: with chunkNonce[4:12]=0xFFFFFFFFFFFFFFFF, an
+// attempt to encrypt a SECOND body chunk fails on counter increment and
+// returns ErrNonceCounterWrapped.
+func TestCounterWraparound(
+	t *testing.T,
+) {
+	// firstPayloadNonce: slot 0..3 = arbitrary base; slot 4..11 = 0xFF*8.
+	firstPayloadNonce := make([]byte, 12)
+	firstPayloadNonce[0] = 0xde
+	firstPayloadNonce[1] = 0xad
+	firstPayloadNonce[2] = 0xbe
+	firstPayloadNonce[3] = 0xef
+	for i := 4; i < 12; i++ {
+		firstPayloadNonce[i] = 0xFF
+	}
+
+	cek := make([]byte, 32)
+	if _, err := io.ReadFull(rand.Reader, cek); err != nil {
+		t.Fatalf("rand: %v", err)
+	}
+	block, err := aes.NewCipher(cek)
+	if err != nil {
+		t.Fatalf("aes: %v", err)
+	}
+	gcm, err := cipher.NewGCM(block)
+	if err != nil {
+		t.Fatalf("gcm: %v", err)
+	}
+
+	// 64 KiB + 1 byte forces 2 body chunks; incrementing after chunk 1
+	// wraps to 0 and ErrNonceCounterWrapped (the second chunk's emission
+	// never happens).
+	input := make([]byte, chunkSize+1)
+	var out bytes.Buffer
+	err = encryptChunks(bytes.NewReader(input), &out, gcm, firstPayloadNonce)
+	if !errors.Is(err, ErrNonceCounterWrapped) {
+		t.Errorf("expected ErrNonceCounterWrapped, got %v", err)
+	}
+}
+
+// (f) Tamper 1 byte in payload → ErrTamperingDetected.
+func TestTamperPayload(
+	t *testing.T,
+) {
+	reg := fakeRegistry(t)
+	enc := NewEncryptor(reg)
+	dec := NewDecryptor(reg)
+
+	pqPub, pqPriv := generateFakeKeyPair(t, reg, fakePqSchemeID, rand.Reader)
+	classicalPub, classicalPriv := generateFakeKeyPair(t, reg, fakeClassicalSchemeID, rand.Reader)
+
+	plaintext := bytes.Repeat([]byte{0x88}, 64*1024+1) // enough to produce a body chunk + final
+	var encrypted bytes.Buffer
+	if err := enc.Encrypt(
+		bytes.NewReader(plaintext),
+		[]crypto.RecipientPub{pqPub, classicalPub},
+		&encrypted,
+		rand.Reader,
+	); err != nil {
+		t.Fatalf("Encrypt: %v", err)
+	}
+
+	buf := encrypted.Bytes()
+	headerLen := standardHeaderLen(fakePqCtLen, fakeClassicalCtLen)
+	tamperIdx := headerLen + 4 + 1 + 8 // into first chunk ciphertext, past len + flags
+	if tamperIdx >= len(buf) {
+		t.Fatalf("file too small to tamper: idx=%d len=%d", tamperIdx, len(buf))
+	}
+	buf[tamperIdx] ^= 0x01
+
+	out := &bytes.Buffer{}
+	err := dec.Decrypt(
+		bytes.NewReader(buf),
+		[]crypto.RecipientPriv{pqPriv, classicalPriv},
+		out,
+	)
+	if !errors.Is(err, ErrTamperingDetected) {
+		t.Errorf("expected ErrTamperingDetected, got %v", err)
+	}
+}
+
+// (g) Tamper 1 byte in wrappedCEK → ErrTamperingDetected.
+func TestTamperWrappedCEK(
+	t *testing.T,
+) {
+	reg := fakeRegistry(t)
+	enc := NewEncryptor(reg)
+	dec := NewDecryptor(reg)
+
+	pqPub, pqPriv := generateFakeKeyPair(t, reg, fakePqSchemeID, rand.Reader)
+	classicalPub, classicalPriv := generateFakeKeyPair(t, reg, fakeClassicalSchemeID, rand.Reader)
+
+	var encrypted bytes.Buffer
+	if err := enc.Encrypt(
+		bytes.NewReader([]byte{0xAA}),
+		[]crypto.RecipientPub{pqPub, classicalPub},
+		&encrypted,
+		rand.Reader,
+	); err != nil {
+		t.Fatalf("Encrypt: %v", err)
+	}
+
+	buf := encrypted.Bytes()
+
+	// wrappedCEK starts at: header-prefix (11) + slot0 (+ct) + slot1 (+ct) + wrapNonce (12).
+	wrapOffset := 11 + (14 + fakePqCtLen) + (14 + fakeClassicalCtLen) + 12
+	if wrapOffset+wrappedCekLen > len(buf) {
+		t.Fatalf("file too short for wrappedCEK")
+	}
+	buf[wrapOffset+5] ^= 0x01
+
+	out := &bytes.Buffer{}
+	err := dec.Decrypt(
+		bytes.NewReader(buf),
+		[]crypto.RecipientPriv{pqPriv, classicalPriv},
+		out,
+	)
+	if !errors.Is(err, ErrTamperingDetected) {
+		t.Errorf("expected ErrTamperingDetected, got %v", err)
+	}
+}
+
+// (h) Wrong priv key (swap pq.priv with another) → ErrWrongKeys.
+func TestWrongPrivKey(
+	t *testing.T,
+) {
+	reg := fakeRegistry(t)
+	enc := NewEncryptor(reg)
+	dec := NewDecryptor(reg)
+
+	pqPub, _ := generateFakeKeyPair(t, reg, fakePqSchemeID, rand.Reader)
+	classicalPub, classicalPriv := generateFakeKeyPair(t, reg, fakeClassicalSchemeID, rand.Reader)
+
+	// Different PQ priv — fresh seed, hence different KeyID.
+	_, wrongPqPriv := generateFakeKeyPair(t, reg, fakePqSchemeID, rand.Reader)
+	// Sanity: the wrong priv's keyID must not collide with the original
+	// pub's (otherwise this test would degrade into a keyID-collision case).
+	if bytes.Equal(wrongPqPriv.KeyID(), pqPub.KeyID()) {
+		t.Fatalf("wrongPqPriv keyID accidentally collides with pqPub keyID; reseed")
+	}
+
+	var encrypted bytes.Buffer
+	if err := enc.Encrypt(
+		bytes.NewReader([]byte{0x11, 0x22, 0x33}),
+		[]crypto.RecipientPub{pqPub, classicalPub},
+		&encrypted,
+		rand.Reader,
+	); err != nil {
+		t.Fatalf("Encrypt: %v", err)
+	}
+
+	out := &bytes.Buffer{}
+	err := dec.Decrypt(
+		bytes.NewReader(encrypted.Bytes()),
+		[]crypto.RecipientPriv{wrongPqPriv, classicalPriv},
+		out,
+	)
+	if !errors.Is(err, ErrWrongKeys) {
+		t.Errorf("expected ErrWrongKeys, got %v", err)
+	}
+}
+
+// (i) Format conformance: magic, version, nRecipients.
+func TestFormatConformance(
+	t *testing.T,
+) {
+	reg := fakeRegistry(t)
+	enc := NewEncryptor(reg)
+	pqPub, _ := generateFakeKeyPair(t, reg, fakePqSchemeID, rand.Reader)
+	classicalPub, _ := generateFakeKeyPair(t, reg, fakeClassicalSchemeID, rand.Reader)
+
+	var out bytes.Buffer
+	if err := enc.Encrypt(
+		bytes.NewReader([]byte{0x42}),
+		[]crypto.RecipientPub{pqPub, classicalPub},
+		&out,
+		rand.Reader,
+	); err != nil {
+		t.Fatalf("Encrypt: %v", err)
+	}
+
+	outBytes := out.Bytes()
+	if binary.BigEndian.Uint32(outBytes[0:4]) != 0x47535051 {
+		t.Errorf("magic = 0x%08x, want 0x47535051", binary.BigEndian.Uint32(outBytes[0:4]))
+	}
+	if binary.BigEndian.Uint16(outBytes[4:6]) != 0x0002 {
+		t.Errorf("version = 0x%04x, want 0x0002", binary.BigEndian.Uint16(outBytes[4:6]))
+	}
+	if outBytes[10] != 0x02 {
+		t.Errorf("nRecipients = 0x%02x, want 0x02", outBytes[10])
+	}
+}
+
+// (j) Adversarial parser: version==0x0001 → ErrUnsupportedVersion, with no
+// GCM operations attempted (proven by the post-validation byte counter
+// remaining at the prefix length — the parser does not consume past the
+// header before bailing).
+func TestUnsupportedVersionNoGCM(
+	t *testing.T,
+) {
+	reg := fakeRegistry(t)
+	dec := NewDecryptor(reg)
+
+	// File: magic + version=0x0001 + flags + nRecipients=0x02 + filler.
+	var buf bytes.Buffer
+	_ = binary.Write(&buf, binary.BigEndian, uint32(0x47535051)) // magic
+	_ = binary.Write(&buf, binary.BigEndian, uint16(0x0001))     // version (downgrade probe)
+	buf.Write(make([]byte, 200))                                 // filler
+
+	// Dummy privs — irrelevant because the parser bails at version check,
+	// but Decrypt accepts the slice shape.
+	_, pqPriv := generateFakeKeyPair(t, reg, fakePqSchemeID, rand.Reader)
+	_, classicalPriv := generateFakeKeyPair(t, reg, fakeClassicalSchemeID, rand.Reader)
+
+	reader := &countingReader{r: bytes.NewReader(buf.Bytes())}
+	out := &bytes.Buffer{}
+	err := dec.Decrypt(
+		reader,
+		[]crypto.RecipientPriv{pqPriv, classicalPriv},
+		out,
+	)
+	if !errors.Is(err, ErrUnsupportedVersion) {
+		t.Errorf("expected ErrUnsupportedVersion, got %v", err)
+	}
+
+	// The parser consumed only the 11-byte prefix — no further bytes read,
+	// hence no GCM operations attempted.
+	if reader.n != 11 {
+		t.Errorf("Decrypt consumed %d bytes post-validation; expected exactly 11 (the fixed prefix)", reader.n)
+	}
+}
+
+// (k) nRecipients==0 → ErrMalformedHeader.
+func TestZeroRecipients(
+	t *testing.T,
+) {
+	var buf bytes.Buffer
+	_ = binary.Write(&buf, binary.BigEndian, uint32(0x47535051)) // magic
+	_ = binary.Write(&buf, binary.BigEndian, uint16(0x0002))     // version
+	_ = binary.Write(&buf, binary.BigEndian, uint32(0))          // flags
+	buf.WriteByte(0x00)                                          // nRecipients = 0
+	buf.Write(make([]byte, 64))                                  // filler
+
+	dec := NewDecryptor(fakeRegistry(t))
+	err := dec.Decrypt(bytes.NewReader(buf.Bytes()), nil, &bytes.Buffer{})
+	if !errors.Is(err, ErrMalformedHeader) {
+		t.Errorf("expected ErrMalformedHeader, got %v", err)
+	}
+}
+
+// (l) nRecipients>2 OR ctLen > maxRecipientCiphertextLen →
+// ErrMalformedHeader BEFORE io.ReadFull attempts to allocate the
+// oversized ciphertext buffer.
+func TestMalformedHeaderCtLenOverflow(
+	t *testing.T,
+) {
+	t.Run("nRecipients_gt_2", func(t *testing.T) {
+		var buf bytes.Buffer
+		_ = binary.Write(&buf, binary.BigEndian, uint32(0x47535051)) // magic
+		_ = binary.Write(&buf, binary.BigEndian, uint16(0x0002))     // version
+		_ = binary.Write(&buf, binary.BigEndian, uint32(0))          // flags
+		buf.WriteByte(0x03)                                          // nRecipients = 3
+		buf.Write(make([]byte, 200))                                 // filler
+
+		dec := NewDecryptor(fakeRegistry(t))
+		err := dec.Decrypt(bytes.NewReader(buf.Bytes()), nil, &bytes.Buffer{})
+		if !errors.Is(err, ErrMalformedHeader) {
+			t.Errorf("expected ErrMalformedHeader, got %v", err)
+		}
+	})
+
+	t.Run("ctLen_overflow", func(t *testing.T) {
+		var buf bytes.Buffer
+		_ = binary.Write(&buf, binary.BigEndian, uint32(0x47535051)) // magic
+		_ = binary.Write(&buf, binary.BigEndian, uint16(0x0002))     // version
+		_ = binary.Write(&buf, binary.BigEndian, uint32(0))          // flags
+		buf.WriteByte(0x02)                                          // nRecipients = 2
+
+		// Slot 0 metadata only — schemeID, keyID, ctLen = 2 MiB (over the
+		// 1<<20 cap). The parser validates ctLen BEFORE allocating and
+		// reading per-slot ciphertext bytes, so it must reject at this
+		// point without attempting io.ReadFull of an oversized buffer.
+		_ = binary.Write(&buf, binary.BigEndian, uint16(0x0006))
+		buf.Write(make([]byte, 8))                                    // keyID
+		_ = binary.Write(&buf, binary.BigEndian, uint32(2*1024*1024)) // ctLen
+
+		reader := &countingReader{r: bytes.NewReader(buf.Bytes())}
+		dec := NewDecryptor(fakeRegistry(t))
+		_, pqPriv := generateFakeKeyPair(t, fakeRegistry(t), fakePqSchemeID, rand.Reader)
+		_, classicalPriv := generateFakeKeyPair(t, fakeRegistry(t), fakeClassicalSchemeID, rand.Reader)
+		err := dec.Decrypt(
+			reader,
+			[]crypto.RecipientPriv{pqPriv, classicalPriv},
+			&bytes.Buffer{},
+		)
+		if !errors.Is(err, ErrMalformedHeader) {
+			t.Errorf("expected ErrMalformedHeader, got %v", err)
+		}
+		// Consumed exactly prefix(11) + slot0 metadata(14) = 25 bytes — the
+		// ctLen validation fired before reading any slot1 metadata or any
+		// per-slot ciphertext.
+		if reader.n != 25 {
+			t.Errorf("Decrypt consumed %d bytes; expected 25 (no io.ReadFull of oversized ct)", reader.n)
+		}
+	})
+}
+
+// (m) Chunk record with length==0 AND flags&0x01==0 → ErrMalformedChunk
+// (prevents an infinite-loop DoS where the parser keeps scanning zero-size
+// non-final chunks).
+func TestZeroLengthNonFinalChunk(
+	t *testing.T,
+) {
+	reg := fakeRegistry(t)
+	enc := NewEncryptor(reg)
+	dec := NewDecryptor(reg)
+
+	pqPub, pqPriv := generateFakeKeyPair(t, reg, fakePqSchemeID, rand.Reader)
+	classicalPub, classicalPriv := generateFakeKeyPair(t, reg, fakeClassicalSchemeID, rand.Reader)
+
+	var encrypted bytes.Buffer
+	if err := enc.Encrypt(
+		bytes.NewReader([]byte{0xAA}),
+		[]crypto.RecipientPub{pqPub, classicalPub},
+		&encrypted,
+		rand.Reader,
+	); err != nil {
+		t.Fatalf("Encrypt: %v", err)
+	}
+
+	headerLen := standardHeaderLen(fakePqCtLen, fakeClassicalCtLen)
+	var corrupt bytes.Buffer
+	corrupt.Write(encrypted.Bytes()[:headerLen])
+	_ = binary.Write(&corrupt, binary.BigEndian, uint32(0)) // ctLen = 0
+	corrupt.WriteByte(0x00)                                 // flags = 0x00 (NOT final)
+
+	out := &bytes.Buffer{}
+	err := dec.Decrypt(
+		bytes.NewReader(corrupt.Bytes()),
+		[]crypto.RecipientPriv{pqPriv, classicalPriv},
+		out,
+	)
+	if !errors.Is(err, ErrMalformedChunk) {
+		t.Errorf("expected ErrMalformedChunk, got %v", err)
+	}
+}
+
+// (n) Chunk record with length > 64*1024+16 → ErrMalformedChunk.
+func TestOversizedChunk(
+	t *testing.T,
+) {
+	reg := fakeRegistry(t)
+	enc := NewEncryptor(reg)
+	dec := NewDecryptor(reg)
+
+	pqPub, pqPriv := generateFakeKeyPair(t, reg, fakePqSchemeID, rand.Reader)
+	classicalPub, classicalPriv := generateFakeKeyPair(t, reg, fakeClassicalSchemeID, rand.Reader)
+
+	var encrypted bytes.Buffer
+	if err := enc.Encrypt(
+		bytes.NewReader([]byte{0xAA}),
+		[]crypto.RecipientPub{pqPub, classicalPub},
+		&encrypted,
+		rand.Reader,
+	); err != nil {
+		t.Fatalf("Encrypt: %v", err)
+	}
+
+	headerLen := standardHeaderLen(fakePqCtLen, fakeClassicalCtLen)
+	var corrupt bytes.Buffer
+	corrupt.Write(encrypted.Bytes()[:headerLen])
+	_ = binary.Write(&corrupt, binary.BigEndian, uint32(chunkSize+gcmTagLen+1)) // oversized
+	corrupt.WriteByte(0x00)                                                     // flags = 0x00
+
+	out := &bytes.Buffer{}
+	err := dec.Decrypt(
+		bytes.NewReader(corrupt.Bytes()),
+		[]crypto.RecipientPriv{pqPriv, classicalPriv},
+		out,
+	)
+	if !errors.Is(err, ErrMalformedChunk) {
+		t.Errorf("expected ErrMalformedChunk, got %v", err)
+	}
+}
+
+// (o) End-of-stream reached BEFORE any chunk with flags&0x01==1
+// (truncated file after a body chunk with no final marker) →
+// ErrUnexpectedEOF.
+func TestPrematureEOF(
+	t *testing.T,
+) {
+	reg := fakeRegistry(t)
+	enc := NewEncryptor(reg)
+	dec := NewDecryptor(reg)
+
+	pqPub, pqPriv := generateFakeKeyPair(t, reg, fakePqSchemeID, rand.Reader)
+	classicalPub, classicalPriv := generateFakeKeyPair(t, reg, fakeClassicalSchemeID, rand.Reader)
+
+	plaintext := bytes.Repeat([]byte{0xAB}, 64*1024+1) // 2 body chunks + final marker
+	var encrypted bytes.Buffer
+	if err := enc.Encrypt(
+		bytes.NewReader(plaintext),
+		[]crypto.RecipientPub{pqPub, classicalPub},
+		&encrypted,
+		rand.Reader,
+	); err != nil {
+		t.Fatalf("Encrypt: %v", err)
+	}
+
+	headerLen := standardHeaderLen(fakePqCtLen, fakeClassicalCtLen)
+	bodyCtLen := 64*1024 + 1 + gcmTagLen
+	bodyChunkRecord := 4 + 1 + bodyCtLen
+	truncatedLen := headerLen + bodyChunkRecord
+
+	if truncatedLen >= len(encrypted.Bytes()) {
+		t.Fatalf("encrypted file shorter than expected: %d vs expected truncation at %d",
+			len(encrypted.Bytes()), truncatedLen)
+	}
+
+	out := &bytes.Buffer{}
+	err := dec.Decrypt(
+		bytes.NewReader(encrypted.Bytes()[:truncatedLen]),
+		[]crypto.RecipientPriv{pqPriv, classicalPriv},
+		out,
+	)
+	if !errors.Is(err, ErrUnexpectedEOF) {
+		t.Errorf("expected ErrUnexpectedEOF, got %v", err)
+	}
+}
+
+// (p) Truncated header → ErrMalformedHeader BEFORE any recipient allocation.
+func TestTruncatedHeader(
+	t *testing.T,
+) {
+	dec := NewDecryptor(fakeRegistry(t))
+
+	// File is shorter than the fixed 11-byte prefix + per-recipient metadata
+	// (2×14=28 = 39 bytes minimum): only 30 bytes total.
+	var buf bytes.Buffer
+	_ = binary.Write(&buf, binary.BigEndian, uint32(0x47535051)) // magic
+	_ = binary.Write(&buf, binary.BigEndian, uint16(0x0002))     // version
+	_ = binary.Write(&buf, binary.BigEndian, uint32(0))          // flags
+	buf.WriteByte(0x02)                                          // nRecipients = 2
+	buf.Write(make([]byte, 20))                                  // only 20 of the needed 28 metadata bytes
+
+	reader := &countingReader{r: bytes.NewReader(buf.Bytes())}
+	err := dec.Decrypt(reader, nil, &bytes.Buffer{})
+	if !errors.Is(err, ErrMalformedHeader) {
+		t.Errorf("expected ErrMalformedHeader, got %v", err)
+	}
+	// No recipient ct allocation happened — only the prefix (11) + partial
+	// metadata (20) = 31 bytes consumed; well shy of a full prefix+meta
+	// read that would precede any per-recipient ct allocation.
+	if reader.n > 39 {
+		t.Errorf("Decrypt consumed %d bytes; expected ≤ 39 — no recipient allocation occurred", reader.n)
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Shared test helpers
+// ---------------------------------------------------------------------------
+
+func mustReadFile(
+	t *testing.T,
+	path string,
+) []byte {
+	t.Helper()
+	data, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatalf("read %s: %v", path, err)
+	}
+	return data
+}
+
+func mustB64Decode(
+	t *testing.T,
+	s string,
+) []byte {
+	t.Helper()
+	b, err := base64.StdEncoding.DecodeString(s)
+	if err != nil {
+		t.Fatalf("base64 decode: %v", err)
+	}
+	return b
+}
+
+// loadGoldenPrivs reconstructs the two fake privs from the committed
+// golden-keys.json (the file produced by //go:build golden_generate).
+type goldenKeyFile struct {
+	Pq        string `json:"pq"`
+	Classical string `json:"classical"`
+}
+
+func loadGoldenPrivs(
+	t *testing.T,
+	path string,
+) (
+	*fakePriv,
+	*fakePriv,
+) {
+	t.Helper()
+	data := mustReadFile(t, path)
+	var keys goldenKeyFile
+	if err := json.Unmarshal(data, &keys); err != nil {
+		t.Fatalf("unmarshal golden keys: %v", err)
+	}
+	pqRaw := mustB64Decode(t, keys.Pq)
+	classicalRaw := mustB64Decode(t, keys.Classical)
+	if len(pqRaw) != fakeSeedLen {
+		t.Fatalf("pq raw len = %d, want %d", len(pqRaw), fakeSeedLen)
+	}
+	if len(classicalRaw) != fakeSeedLen {
+		t.Fatalf("classical raw len = %d, want %d", len(classicalRaw), fakeSeedLen)
+	}
+	return newFakePriv(fakePqSchemeID, pqRaw), newFakePriv(fakeClassicalSchemeID, classicalRaw)
+}
@@ -0,0 +1,120 @@
+//go:build golden_generate
+
+// The golden_generate build tag is intentionally separate so CI never
+// regenerates the committed fixture. Run ONCE locally to (re)commit:
+//
+//	~/sdk/go1.26.5/bin/go test -tags golden_generate                 \
+//	    -run TestGenerateGoldenFixture -v                             \
+//	    ./pkg/adapters/crypto/composite/...
+//
+// Then commit the produced testdata/golden-1byte.pqenc and
+// testdata/golden-keys.json. Non-`-update` runs of TestGoldenFormat load
+// the committed artifacts and verify decrypt-equality.
+package composite
+
+import (
+	"bytes"
+	"crypto/sha256"
+	"encoding/base64"
+	"encoding/binary"
+	"encoding/json"
+	"fmt"
+	"os"
+	"testing"
+
+	"git.tswf.io/infra/go-synapse-backupper/pkg/domain/crypto"
+)
+
+// deterministicRand implements io.Reader via a SHA-256 counter stream so the
+// golden fixture is byte-for-byte reproducible across machines and Go
+// toolchain versions.
+type deterministicRand struct {
+	seq uint64
+}
+
+func (d *deterministicRand) Read(
+	p []byte,
+) (int, error) {
+	for offset := 0; offset < len(p); {
+		var b [8]byte
+		binary.BigEndian.PutUint64(b[:], d.seq)
+		d.seq++
+		out := sha256.New()
+		out.Write(b[:])
+		hashed := out.Sum(nil)
+		n := copy(p[offset:], hashed)
+		offset += n
+	}
+	return len(p), nil
+}
+
+// Hard-coded priv seeds so the committed golden-keys.json stays stable across
+// builds — these are the test-only private "keys" the committed golden file
+// decrypts against.
+var (
+	goldenPqSeed = [32]byte{
+		0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08,
+		0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f, 0x10,
+		0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17, 0x18,
+		0x19, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f, 0x20,
+	}
+	goldenClassicalSeed = [32]byte{
+		0x21, 0x22, 0x23, 0x24, 0x25, 0x26, 0x27, 0x28,
+		0x29, 0x2a, 0x2b, 0x2c, 0x2d, 0x2e, 0x2f, 0x30,
+		0x31, 0x32, 0x33, 0x34, 0x35, 0x36, 0x37, 0x38,
+		0x39, 0x3a, 0x3b, 0x3c, 0x3d, 0x3e, 0x3f, 0x40,
+	}
+)
+
+func TestGenerateGoldenFixture(
+	t *testing.T,
+) {
+	pqPub := newFakePub(fakePqSchemeID, goldenPqSeed[:])
+	pqPriv := newFakePriv(fakePqSchemeID, goldenPqSeed[:])
+	classicalPub := newFakePub(fakeClassicalSchemeID, goldenClassicalSeed[:])
+	classicalPriv := newFakePriv(fakeClassicalSchemeID, goldenClassicalSeed[:])
+
+	reg := crypto.NewRegistry()
+	if err := reg.Register(fakePqSchemeID, newFakePqKem); err != nil {
+		t.Fatalf("register pq fake: %v", err)
+	}
+	if err := reg.Register(fakeClassicalSchemeID, newFakeClassicalKem); err != nil {
+		t.Fatalf("register classical fake: %v", err)
+	}
+
+	enc := NewEncryptor(reg)
+	rng := &deterministicRand{}
+
+	var encrypted bytes.Buffer
+	if err := enc.Encrypt(
+		bytes.NewReader([]byte{0xAA}),
+		[]crypto.RecipientPub{pqPub, classicalPub},
+		&encrypted,
+		rng,
+	); err != nil {
+		t.Fatalf("Encrypt: %v", err)
+	}
+
+	if err := os.MkdirAll("testdata", 0o755); err != nil {
+		t.Fatalf("mkdir testdata: %v", err)
+	}
+	if err := os.WriteFile("testdata/golden-1byte.pqenc", encrypted.Bytes(), 0o644); err != nil {
+		t.Fatalf("write golden file: %v", err)
+	}
+
+	keys := goldenKeyFile{
+		Pq:        base64.StdEncoding.EncodeToString(pqPriv.Raw()),
+		Classical: base64.StdEncoding.EncodeToString(classicalPriv.Raw()),
+	}
+	marshalled, err := json.MarshalIndent(keys, "", "  ")
+	if err != nil {
+		t.Fatalf("marshal keys: %v", err)
+	}
+	marshalled = append(marshalled, '\n')
+	if err := os.WriteFile("testdata/golden-keys.json", marshalled, 0o644); err != nil {
+		t.Fatalf("write keys json: %v", err)
+	}
+
+	fmt.Printf("Golden fixture written: testdata/golden-1byte.pqenc (%d bytes), "+
+		"testdata/golden-keys.json (%d bytes)\n", len(encrypted.Bytes()), len(marshalled))
+}
@@ -0,0 +1,4 @@
+{
+  "pq": "AQIDBAUGBwgJCgsMDQ4PEBESExQVFhcYGRobHB0eHyA=",
+  "classical": "ISIjJCUmJygpKissLS4vMDEyMzQ1Njc4OTo7PD0+P0A="
+}