fee/aesstream: chunked AES-256-GCM STREAM encrypt/decrypt (FIL-470)

[Peeja]

This is the stream encryption. The FEE FIP specifies two algorithms for encryption: AES-256-GCM, which is well-known and IANA-registered, and Chunked AES-256-GCM with STREAM construction, which is defined in the FIP in terms of AES-256-GCM over a chunking scheme, to allow for random access. We're using the latter, which isn't implemented in any off-the-shelf package yet. Luckily, the chunking is pretty straightforward, and AES-256-GCM itself is supported by Go's crypto/cipher.

Unfortunately, being a bespoke configuration, even over standard AES, there are no published fixtures to test against, but the tests are pretty thorough, with lots of round-tripping.

---

Implements FIL-470 — the raw chunked AES-256-GCM STREAM body cipher for the FilOne File Encryption Envelope (FEE), in fee/aesstream/. The parent fee package (COSE envelope, key-wrapping) will build on this.

Wire format

Per the FilOne encryption RFC (fil-one/RFC#9) and FIP #1253:

• AES-256-GCM, 32-byte CEK, 16-byte tag
• Default 256 KiB chunks (configurable 4 KiB – 16 MiB)
• Nonce: baseNonce[7] ‖ chunkIndex[4, big-endian] ‖ lastFlag[1]
• AAD is constant per stream (the COSE Enc_structure); chunks are differentiated by the counter, not per-chunk AAD
• Empty plaintext → one empty final chunk (16-byte tag), so the ciphertext is never zero-length
• The 4-byte counter caps a stream at 2³² chunks rather than silently wrapping a nonce

Scope

Raw body cipher only — Config{Key, BaseNonce, AAD, ChunkSize} in, ciphertext stream out. The COSE_Encrypt envelope (FIL-469), IV generation, and CEK key-wrapping (FIL-471/547) live in the parent fee package.

API

• Writer / Reader — streaming io.WriteCloser / io.Reader, O(chunk-size) memory
• Seal / Open — one-shot convenience helpers
• Config (+ validation), NewBaseNonce, EncryptedSize

Acceptance criteria

• ✅ Round-trips arbitrary-size streams; chunk size defaults to 256 KiB
• ✅ Truncation → error rather than partial plaintext (callers trust only a clean io.EOF)
• ✅ Reordered chunks → error
• ✅ Bit flip anywhere in a chunk → error
• ✅ Encrypt larger than memory without OOM — heap stays O(chunk size), not O(stream size)

Testing

Black-box + white-box suites: round-trips across chunk boundaries (empty, ±1 chunk, exact multiples, odd remainders), truncation / reorder / tamper / trailing-data detection, the full-size-last-chunk retry path, the exact nonce wire format, the counter-overflow guard, a 128 MiB bounded-memory stream, and zero-allocation steady state. -race clean, 93.4% statement coverage (remainder is unreachable defensive code).

A design seam for FIL-472 (range decryption) is intentionally left in place: the nonce/chunk math is isolated so range reads can determine the last-chunk flag from the envelope's byte length rather than the streaming reader's retry path.

🤖 Generated with Claude Code

https://claude.ai/code/session_014EgQ1SYk7fMEtwoEdppPqL

---

Generated by Claude Code

[Copilot]

Pull request overview

Adds the fee/aesstream package implementing FilOne’s chunked AES-256-GCM STREAM body cipher (Writer/Reader + one-shot helpers) as the foundation for the higher-level FEE envelope work.

Changes:

• Introduces core streaming encryption/decryption types (Writer, Reader) and the shared Config/nonce construction.
• Adds convenience helpers (Seal, Open, EncryptedSize, NewBaseNonce) for one-shot usage and sizing.
• Adds comprehensive black-box and internal white-box tests covering boundary cases, tampering/truncation, and allocation/memory behavior.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
fee/aesstream/aesstream.go	Defines the AES-GCM STREAM format, config/validation, nonce layout, helpers (Seal/Open/EncryptedSize/NewBaseNonce), and exported errors/constants.
fee/aesstream/writer.go	Implements chunked streaming encryption and ciphertext writing.
fee/aesstream/reader.go	Implements chunked streaming decryption with truncation/tamper/trailing-data detection.
fee/aesstream/aesstream_test.go	Black-box tests for round-trips, boundary conditions, tamper/truncation/reorder, sizing, and bounded-memory streaming.
fee/aesstream/internal_test.go	Internal tests pinning nonce wire format, chunk-count guards, and per-chunk allocation behavior.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 4 comments.

[frrist]

I'm going to sound like a broken record across all these crypto PRs; I lack the depth of knowledge to determine is this is "correct", though it looks good to me:

Approving so this isn't blocked. But flagging, as a follow-up rather than an objection: this is hand-rolled cryptography, and the blast radius if any of it is subtly wrong is large.