fee: top-level package composing encrypt/decrypt over existing primitives (FIL-569)

[Peeja]

tl;dr: Provides the outer fee package interface that ties the primitives together.

---

Stacked on #32 (FIL-473). This PR targets claude/fil-473-s7pjf9, not main, so its diff is only the composer on top of #32. Review/merge #32 first; GitHub will retarget this to main automatically when #32 lands.

What

Adds github.com/fil-forge/ingot/fee — a standalone FEE (FilOne File Encryption Envelope) library that composes the four primitives (fee/cose, fee/aesstream, fee/ecdhkw, fee/aeskw) into a small public API for whole-object encrypt/decrypt, so callers no longer sequence COSE encode/decode, STREAM encrypt/decrypt and recipient wrap/unwrap by hand. No app vocabulary at this layer — it's publishable as an independent FEE package.

func Encrypt(plaintext io.Reader, recipients []Recipient, opts ...EncryptOption) (io.ReadCloser, error)
func EncryptWithCEK(plaintext io.Reader, cek []byte, recipients []Recipient, opts ...EncryptOption) (io.ReadCloser, error)
func Decrypt(src io.Reader, unwrap RecipientUnwrapper) (io.Reader, error)
func DecryptWithCEK(src io.Reader, cek []byte) (io.Reader, error)

func NewECDHESRecipient(kid []byte, pub *ecdh.PublicKey) Recipient   // ECDH-ES+A256KW (X25519)
func NewA256KWRecipient(kid, kek []byte) Recipient                   // A256KW (32-byte KEK)
func NewECDHESUnwrapper(kid []byte, priv *ecdh.PrivateKey) RecipientUnwrapper
func NewA256KWUnwrapper(kid, kek []byte) RecipientUnwrapper
func WithChunkSize(n int) EncryptOption
func WithContentLength(n int64) EncryptOption

Two orthogonal concerns

1. Wrap algorithm — how the CEK is wrapped into an in-envelope COSE_Recipient. Both may be mixed in one envelope; on decrypt the caller never selects the algorithm, the recipient's COSE header does:

• ECDH-ES+A256KW to an X25519 public key (NewECDHESRecipient / NewECDHESUnwrapper).
• A256KW under a symmetric KEK (NewA256KWRecipient / NewA256KWUnwrapper).

kid is an opaque, caller-supplied key id for both kinds (a DID verification method ID in the consuming app); the library never derives or interprets it.

2. CEK delivery — decoupled from the algorithm:

• In-envelope: Encrypt wraps a fresh CEK to the recipients (a COSE_Encrypt, tag 96); Decrypt recovers it by matching a RecipientUnwrapper's kid and unwrapping.
• Externally-provided: EncryptWithCEK seals under a caller-held CEK; with recipients it emits a tag-96 envelope, and with no recipients it emits a recipient-less COSE_Encrypt0 (tag 16). DecryptWithCEK decrypts with a CEK obtained out of band (e.g. unwrapped by a custody service), accepting either form and ignoring recipients. Decrypt on a recipient-less envelope returns ErrNoRecipientsInEnvelope.

Naming tracks the exact COSE algorithms because the arguments are pinned to them (X25519-only key agreement; 32-byte A256KW KEK; 32-byte AES-256 CEK), not general ECDH/AES-KW.

Streaming (both directions, O(chunk) memory)

Neither direction buffers the whole object, so a multi-GB body can be piped straight to/from storage.

• Decrypt/DecryptWithCEK are pull-based: cose.DecodeReader reads only the header, then aesstream.NewReader streams the ciphertext — no goroutine.
• Encrypt/EncryptWithCEK return an io.ReadCloser: the STREAM body cipher is push-based (finalizes on Close, like gzip/age), so a reader-returning API bridges push→pull with an internal io.Pipe + goroutine. Read to EOF or Close() — Close aborts the goroutine; an encryption error surfaces as a non-EOF Read error. The pipe is created only after all fallible header work succeeds, so no error path can orphan it.

cose.DecodeReader (sub-package addition)

DecodeReader(io.Reader) (*cose.Envelope, io.Reader, error) decodes the COSE header from a stream — dispatching on the tag (96 COSE_Encrypt / 16 COSE_Encrypt0) — and returns the detached ciphertext as a reader (the decoder's Buffered() remainder + the source). It shares the strict decodeEnvelope validation core with the byte-based cose.Decode and produces a byte-identical EncStructure (AAD), so an envelope decrypts the same read either way.

Note: #32 unified cose.Encrypt/cose.Encrypt0 into a single cose.Envelope{Headers, Recipients} whose form — COSE_Encrypt (tag 96) vs COSE_Encrypt0 (tag 16), the array shape, and the Enc_structure context — is derived from recipient presence rather than stored. This PR's DecodeReader returns that type, and the composer builds one Envelope for both the AAD and the encoded header.

Wire format

Detached-payload convention: the COSE envelope followed by the STREAM ciphertext. Reconciled to the foc-encryption reference and the FIL-473 cross-implementation vectors:

• Body protected header: FEE typ (application/vnd.foc-envelope+cose) and the body alg (-65793, private-use chunked AES-256-GCM-STREAM), both authenticated via the Enc_structure AAD.
• Body unprotected header: base nonce in iv (label 5), chunk size (-65790), and — only when the plaintext length is known via WithContentLength — the advisory chunk count (-65791). The chunk count is metadata for range/seek planning and is not required to decrypt; when omitted, range decryption derives the geometry from the ciphertext length instead.
• Recipient entries: wrap alg (-31 ECDH-ES+A256KW / -5 A256KW), the kid, and — for ECDH-ES — the ephemeral key as a self-describing COSE_Key (kty=OKP, crv=X25519, x=public-key bytes), decoded and validated on unwrap.
• Body AAD is the envelope's own Enc_structure, whose context ("Encrypt"/"Encrypt0") tracks recipient presence.

Acceptance criteria

• ✅ Mixed ECDH-ES + A256KW recipients in one Encrypt, opened by either — TestRoundTripMixedRecipients.
• ✅ Recover plaintext from the appropriate key/KEK, or a directly-provided CEK (with recipients and recipient-less) — round-trip + TestExternalCEK + TestExternalCEKNoRecipients.
• ✅ A kid matching no recipient → ErrNoMatchingRecipient (no panic/silent failure) — TestDecryptKidMismatch.
• ✅ Sub-package behavior unchanged; their tests pass (only doc comments de-worded).

Design notes

• Chunk size stored in the envelope (unprotected), default 256 KiB, overridable via WithChunkSize; present-but-non-integer is rejected as malformed.
• A256KW KEK / external CEK are required to be 32 bytes; ECDH-ES requires an X25519 key. Invalid recipients (nil key, empty kid, wrong KEK length) are rejected before any plaintext is read.
• WithContentLength declares the plaintext length so the chunk count can be recorded; the returned reader then fails with ErrContentLengthMismatch if the actual length differs (and the already-written count can't be trusted).
• ECDH ephemeral is a COSE_Key, not raw bytes — a malformed ephemeral key (wrong kty/crv, missing/short x, or not a map) is rejected as ErrMalformedEnvelope before any ECDH is attempted.

Testing

GOWORK=off go test -race ./fee/... -count=1 — green (incl. the goroutine-backed streaming Encrypt under the race detector). go build ./..., go vet ./fee/..., gofmt clean. Coverage: round-trips across sizes for ECDH-ES / A256KW / mixed; external-CEK round trip (with recipients + recipient-less) + in-envelope cross-check + wrong-CEK + invalid length; content-length chunk-count present/omitted + mismatch; pure reader→reader streaming; fragmented (one-byte-at-a-time) decrypt; Encrypt reader Close; kid mismatch (both kinds); wrong ECDH key and wrong A256KW KEK (both fail before decryption); recipient alg mismatch; corrupted header (→ cose.ErrMalformed); tampered ciphertext (→ aesstream.ErrCorrupted); malformed COSE_Key ephemeral (→ ErrMalformedEnvelope); wrong envelope typ; no/nil/invalid recipients; nil src/unwrapper; out-of-range & malformed chunk size; self-describing chunk size; and cose.DecodeReader (streaming + fragmented + empty + both forms + cose.Decode-equivalence).

Closes FIL-569.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds a new top-level fee package that composes the existing FEE primitives (fee/cose, fee/aesstream, fee/ecdhkw, fee/aeskw) into a small public API for whole-object encrypt/decrypt via a detached COSE_Encrypt envelope (envelope || ciphertext).

Changes:

• Introduces fee.Encrypt / fee.Decrypt, including envelope typing, body alg pinning, and self-describing chunk size handling.
• Adds sealed Recipient / RecipientUnwrapper implementations for tenant (X25519 ECDH-ES+A256KW) and region (A256KW) recipients.
• Adds comprehensive round-trip and tamper/mismatch tests for mixed recipients and error paths.

Reviewed changes

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

File	Description
fee/fee.go	Implements the top-level Encrypt/Decrypt orchestration and envelope conventions.
fee/recipient.go	Defines sealed recipient wrappers for tenant/region key wrapping into COSE_Recipient entries.
fee/unwrapper.go	Defines sealed unwrappers for recovering the CEK for tenant/region recipients during decrypt.
fee/fee_test.go	Adds API-level tests for round trips, wire conventions, and failure modes.

---

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

[Copilot]

Pull request overview

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

[bajtos]

Review comments written by Claude (requested by @miroslav): five suggestions from a review pass, all non-blocking. The most substantive is documenting a CEK-uniqueness requirement on EncryptWithCEK; the rest are ordering/naming/doc nits.

---

Generated by Claude Code