fee/aesstream: range decryption API (FIL-472)

[Peeja]

This will support range requests for objects. A higher layer will translate an object range request into plaintext segment (piece/shard) range requests, and those into ciphertext blob range requests which can go to Piri. This PR provides everything that layer needs to convert from a plaintext range to a ciphertext range (CiphertextRange()), and then turn the ciphertext result of those range requests into the plaintext we're after (SpanReader).

---

Implements FIL-472 — the range-decryption API for the FilOne File Encryption Envelope (FEE).

Pure STREAM mechanics on top of the existing body cipher — no new crypto, just chunk-index arithmetic and a single contiguous fetch of the chunks overlapping a request.

Design: sequential, one request per segment

A range read turns a plaintext range into one contiguous ciphertext fetch, then streams the result through the decryptor — so the read path is one request per segment with O(chunkSize) memory, no per-chunk fetching.

• CiphertextRange(ciphertextSize, chunkSize, off, length) (start, n, err) — the single contiguous ciphertext byte span covering a plaintext range. Because the chunks overlapping a range are adjacent, the bytes needed are one span; the consumer (FIL-487) fetches it in one range request. Offsets are stream-relative (add any envelope-header length). Chunk-aligned, so the edge over-read is <2·chunkSize (GCM authenticates whole chunks).
• SpanReader (io.Reader) / OpenSpan — decrypt that span, delivered as a sequential io.Reader (e.g. a range-request body), into exactly the requested plaintext. The total ciphertext length pins each chunk's index, final-chunk flag and length up front, so there's no last-chunk retry; the first/last chunks are trimmed to the range. OpenSpan guards its int64→int buffer with math.MaxInt (steers huge ranges to the streaming reader instead of panicking in make on 32-bit builds).
• DecryptedSize — inverse of EncryptedSize; derives and validates the plaintext length from a ciphertext length without fetching any ciphertext.

Semantics

HTTP-range-like: a length past the end clamps to the bytes available from the offset; a negative offset/length or an offset past the end is ErrRange. A structurally invalid declared ciphertext length is ErrCiphertextSize; a tampered/reordered/misframed chunk is ErrCorrupted; a span shorter than the geometry requires is ErrTruncated.

What the tests cover (testify require)

• TestSpanReader/Ranges — a table of hand-computed literal expectations (span start/length and decrypted length): an independent oracle that pins the exact span CiphertextRange reports, that OpenSpan/SpanReader reproduce the right plaintext from exactly that span, and that the span is consumed in full and no further.
• TestSpanReader/RoundTrip — reads each sealed object back in full through adjacent range windows of varying widths (chunk-aligned and not), via both OpenSpan and SpanReader, and confirms the reassembly equals the original plaintext (length recovered through DecryptedSize).
• Tamper detection, short-span truncation, wrong-declared-size detection, range/size validation, default 256 KiB chunks, CiphertextRange input validation, the internal chunkLayout geometry + MaxChunks guard, and EncryptedSize↔DecryptedSize inversion.

go test (incl. -race), go vet, gofmt clean.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds a range-decryption API to fee/aesstream so consumers can read arbitrary plaintext byte ranges from a chunked AES-256-GCM STREAM ciphertext using only the overlapping ciphertext chunks.

Changes:

• Introduces RangeReader, OpenRange, and DecryptedSize plus shared chunk-geometry math (chunkLayout).
• Adds comprehensive tests covering correctness, chunk-selective fetch behavior, tamper detection, and size/range validation.
• Promotes github.com/stretchr/testify to a direct dependency to support the new test suites.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

File	Description
go.mod	Promotes testify to a direct dependency for new tests.
fee/aesstream/rangereader.go	Implements range decryption reader + size/geometry helpers.
fee/aesstream/rangereader_test.go	Black-box tests for range correctness, selective fetch, and tamper/validation behavior.
fee/aesstream/rangereader_internal_test.go	Internal tests pinning chunkLayout boundary math and MaxChunks guard.

---

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

[Copilot]

Pull request overview

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