feat(crypto): add per-page HPKE encryption for LTX v4

[corylanou]

Summary

Adds per-page encryption to the LTX file format (v4) using HPKE (RFC 9180) with DHKEM(X25519) + HKDF-SHA256 + ChaCha20-Poly1305.

• Each file gets a random 32-byte CEK wrapped per-recipient via HPKE, with HKDF-derived keys for page encryption and index authentication
• Duplicate recipient block at start and end of file enables both streaming decryption and efficient VFS random-access reads
• Multi-recipient support from day one for key rotation scenarios
• New CLI commands: keygen (generate X25519 keypair), rekey (re-encrypt with new recipients)
• Encryption flags on existing commands: -key for decryption, -encrypt-to for encryption
• Backward compatible: v3 files still decode correctly with v4 code

Fixes #77

Changes since the original review

Rebased onto main (twice — once for #80, once after #89, #90, #91 and #92 merged) and audited end to end. Four things came out of that:

Unencrypted output stays at v3. encode-db and the compactor were emitting the new LTX4 magic for every file, encrypted or not, which every existing reader rejects — including litestream. An unencrypted v4 header is byte-identical to a v3 header, since the new fields occupy v3 reserved space and are zero, so this broke readers without changing the file. The encoder now emits the lowest version that represents the requested features, and LTX4 in practice means encrypted. TestEncoder_FormatVersionSelection pins both directions.

Integrity is now verifiable without a key. Encrypted files hash their ciphertext into the file checksum specifically so a holder of the file can detect corruption without holding a decryption key, but DecodeHeader rejected any encrypted file when no key was supplied, making the capability unreachable. Decoding without a key now verifies structure and the file checksum, skipping decryption, the index auth tag, and the plaintext post-apply comparison. DecodePage still refuses, so nothing can mistake an unread buffer for page contents, and ltx verify reports the narrower guarantee instead of a bare ok.

Key derivation moved to crypto/hkdf. The module already requires Go 1.26 for crypto/hpke, so the x/crypto import was redundant. Verified byte-identical output for both derivation labels before switching, so existing encrypted files still decrypt. chacha20poly1305 has no stdlib equivalent and stays.

Two crypto invariants are now documented. AuthenticateIndex uses a fixed nonce and EncryptPage uses random 96-bit nonces. Both are safe only because a CEK is generated fresh per file and never reused; reusing one across files would leak the Poly1305 key and permit index forgery. Nothing recorded that previously.

Also: the format documentation rewritten in #92 states that LTX carries no on-disk version field and that a reader cannot determine the version from the file. v4 changes the magic, so both became wrong here — the README now covers the LTX1/LTX4 split, the v4 header fields, the recipient block, encrypted frame layout and AAD binding, the index auth tag, and the ciphertext checksum domain.

Compatibility note for reviewers

This branch raises the Go floor to 1.26, because crypto/hpke does not exist before it. go.mod, the Dockerfile and both workflows move from 1.24 to 1.26. That is a larger consumer-facing change than the encryption feature itself, and it conflicts with #64, which adds a CI matrix covering Go 1.22–1.24. Those two cannot both land unchanged.

Test Plan

• Crypto primitive tests: key generation, CEK seal/open (single/multi-recipient/wrong key), page encrypt/decrypt (round-trip/tampered/wrong AAD), index auth (round-trip/tampered), key derivation
• Keyless decoding: integrity verification succeeds, page access refused, bit-flipped ciphertext still detected
• Format version selection: unencrypted emits LTX1/v3, encrypted emits LTX4/v4
• Encoder/decoder round-trip with encryption; multi-recipient decryption
• Compactor: encrypted→encrypted, encrypted→unencrypted, unencrypted→encrypted
• All existing v3 tests continue to pass
• New E2E CLI suite (11 groups): keygen, single and multi-recipient, rekey, sequential encrypted apply, backward compatibility, tamper detection, error paths, truncation at six offsets, page sizes 512B–64KB. Previously an uncommitted script run by hand on macOS; now committed and run on linux in CI.
• go build ./..., go vet ./..., go test ./..., go test -race ./... all pass

[corylanou]

LTX HPKE E2E Encryption Test Report

• Date: 2026-02-25T19:21:33Z
• Git commit: 5f0c59d
• Go version: go version go1.26.0 darwin/arm64
• LTX version: ltx development build
• Platform: Darwin/arm64

Results

Test	Result	Duration
Test 1: Docker Build	PASS	4.539s
Test 2: Key Generation	PASS	58ms
Test 3: Single-Key Encryption Workflow	PASS	76ms
Test 4: Multi-Recipient	PASS	118ms
Test 5: Key Rotation (Rekey)	PASS	110ms
Test 6: Sequential Encrypted Apply	PASS	52ms
Test 7: Backward Compatibility	PASS	75ms
Test 8: Tamper Detection	PASS	70ms
Test 9: Error Paths	PASS	64ms
Test 10: Truncation Simulation	PASS	96ms
Test 11: Page Sizes (512B–64KB)	PASS	459ms

Summary

• Total: 11
• Passed: 11
• Failed: 0

[corylanou]

Data on the Go 1.26 floor, since that's the thing gating this.

Downstream state today:

Consumer	Go	Pinned ltx
litestream	1.25.0	v0.5.1
LiteFS	1.21	v0.3.14

litestream is the consumer that actually tracks this repo — one minor behind on Go, one patch behind on ltx. Its workflows all use go-version-file: go.mod, so bumping its go.mod moves CI with it; there's no version pinned in the workflow files to chase. Moving it 1.25 → 1.26 is a one-line change.

LiteFS is a different story. It's on Go 1.21 and pinned to ltx v0.3.14, five minor versions back. It is not currently tracking this repo at all, so the 1.26 floor doesn't block anything for it today — but whenever it does upgrade, it inherits a 1.21 → 1.26 jump on top of a five-version ltx jump.

Two useful consequences.

First, the floor is cheap for the consumer that's actually current and irrelevant to the one that isn't. That's a much weaker objection than it looked before checking.

Second, and worth noting for #84: LiteFS pinning v0.3.14 means it does not yet have the lock-page fix from #89. I checked, and v0.3.14 does contain both ChecksumPages and ChecksumReader (they landed in 2c8411b, which v0.3.14 includes), so LiteFS is genuinely a consumer of the changed functions — it just hasn't picked up the change. Since LiteFS already zeroes the lock-page slot on its own side, it stays correct either way, and gets the fix when it upgrades.

On #64. It adds a CI matrix for Go 1.22–1.24, which cannot coexist with a 1.26 floor. Separately, #64 has gone badly stale — see my note there. If this PR lands, #64's matrix needs rewriting regardless of what happens to the rest of it.