fee: make the API domain-agnostic; add external-CEK paths (FIL-569)

The composition layer named recipients by app role ("tenant"/"region"). This
package should be a standalone FEE library, so name by mechanism instead and
separate the two orthogonal concerns: the wrap algorithm, and how the CEK
reaches the decryptor.

Recipients / unwrappers (rename; kid is now an explicit, opaque caller-supplied
key id — a DID verification method ID in the consuming app — for both kinds):
- NewTenantRecipient  -> NewECDHESRecipient(kid, pub)   ECDH-ES+A256KW (X25519)
- NewRegionRecipient  -> NewA256KWRecipient(kid, kek)   A256KW (32-byte KEK)
- NewTenantUnwrapper  -> NewECDHESUnwrapper(kid, priv)
- NewRegionUnwrapper  -> NewA256KWUnwrapper(kid, kek)

Names track the exact COSE algorithms because the arguments are pinned to them
(X25519-only key agreement; 32-byte A256KW KEK) rather than general ECDH/AES-KW.

Externally-provided CEK (new, decoupled from the wrap algorithm):
- EncryptWithCEK(plaintext, cek, recipients, opts): seal under a caller-provided
  CEK instead of a generated one.
- DecryptWithCEK(src, cek): decrypt with a CEK obtained out of band (e.g.
  unwrapped by a custody service), ignoring the envelope's recipients.
Encrypt/Decrypt and EncryptWithCEK/DecryptWithCEK share seal/open cores; a
32-byte CEK is required (ErrInvalidCEK).

Also de-worded the fee/aeskw and fee/ecdhkw package doc comments (comments only;
no behavior change) so the whole tree is free of app vocabulary.

Tests: renamed throughout; added external-CEK round trip + cross-check + invalid
length, a proper ECDH-ES wrong-key unwrap test (now possible with an explicit
kid), and empty-kid recipient validation.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Fyx4RZx2j88mTQyeavbs79

Author: claude

fee/aeskw/aeskw.go

@@ -30,9 +30,9 @@
 // default IV. This package contributes the input validation, the ErrIntegrity
 // sentinel, and a stable API over it.
 //
-// This is a shared primitive. The tenant-recipient wrap (ECDH-ES+A256KW, in
-// the sibling fee/ecdhkw package) derives its KEK ephemerally per message and
-// feeds it here; the region wrap takes a KEK straight from a key provider.
+// This is a shared primitive. The ECDH-ES+A256KW wrap (in the sibling
+// fee/ecdhkw package) derives its KEK ephemerally per message and feeds it
+// here; the A256KW recipient wrap takes a KEK straight from a key provider.
 // Both paths call Wrap and Unwrap identically.
 package aeskw
 

fee/ecdhkw/ecdhkw.go

@@ -2,8 +2,8 @@
 // encrypts a content-encryption key (CEK) to a recipient's X25519 public key so
 // that only the holder of the matching private key can recover it.
 //
-// This is the tenant-recipient wrap of the FilOne encryption design. A fresh
-// ephemeral X25519 key pair is generated for every Wrap; an ECDH against the
+// This is the key-agreement recipient wrap of the FilOne encryption design. A
+// fresh ephemeral X25519 key pair is generated for every Wrap; an ECDH against the
 // recipient's static public key yields a shared secret, the COSE Concat-KDF
 // (RFC 9053 §5.1, see kdf.go) turns that secret into a 256-bit key-encryption
 // key, and AES Key Wrap (RFC 3394, the sibling fee/aeskw package) wraps the CEK

fee/fee.go

@@ -10,33 +10,39 @@
 //   - fee/aesstream — the chunked AES-256-GCM-STREAM body cipher: it seals the
 //     plaintext under a per-object content-encryption key (CEK) and a random
 //     base nonce.
-//   - fee/ecdhkw    — the tenant recipient wrap (ECDH-ES+A256KW over X25519):
-//     it encrypts the CEK to a tenant's X25519 public key.
-//   - fee/aeskw     — RFC 3394 AES Key Wrap, used for the region recipient wrap
-//     (A256KW) directly under a key-encryption key (KEK).
+//   - fee/ecdhkw    — the ECDH-ES+A256KW key wrap over X25519: it encrypts the
+//     CEK to a recipient's X25519 public key.
+//   - fee/aeskw     — RFC 3394 AES Key Wrap (A256KW): it wraps the CEK directly
+//     under a symmetric key-encryption key (KEK).
 //
 // This package sequences them so callers do not have to. [Encrypt] generates a
 // fresh CEK, seals the plaintext with the STREAM body cipher, wraps the CEK to
 // each [Recipient], and encodes the COSE_Encrypt envelope; [Decrypt] reverses
 // the process, locating the recipient that a [RecipientUnwrapper] holds the key
 // for, recovering the CEK, and streaming out the plaintext.
 //
-// # Recipients
+// # Recipients and content-encryption keys
 //
-// A single envelope can carry several recipients, each holding the same CEK
-// wrapped under a different key, named by a key id (kid). A caller mixes
-// recipient kinds freely and never has to know which wrap algorithm a given
-// envelope entry uses — the kid and the recipient's COSE algorithm header
-// determine that:
+// The body is sealed under a single content-encryption key (CEK). Two concerns
+// are independent: which algorithm wraps the CEK, and how the CEK reaches the
+// decryptor.
 //
-//   - A tenant recipient ([NewTenantRecipient] / [NewTenantUnwrapper]) wraps the
-//     CEK to an X25519 public key with ECDH-ES+A256KW. Its kid is the raw
-//     X25519 public-key bytes, so recovery needs only the matching private key.
-//   - A region recipient ([NewRegionRecipient] / [NewRegionUnwrapper]) wraps the
-//     CEK under a symmetric KEK with A256KW. Its kid is supplied by the caller
-//     and names the KEK (and, by convention, its version). The KEK custody and
-//     versioning layer is a separate concern (see FIL-547) that plugs in behind
-//     the same Recipient/RecipientUnwrapper seam without changing this API.
+// A CEK can be carried in the envelope as one or more COSE_Recipient entries,
+// each keyed by a caller-supplied key id (kid — opaque to this package, e.g. a
+// DID verification method ID). Two wrap algorithms are available and may be mixed
+// in one envelope; the caller never selects the algorithm on decrypt, the
+// recipient's COSE header does:
+//
+//   - ECDH-ES+A256KW to an X25519 public key: [NewECDHESRecipient] /
+//     [NewECDHESUnwrapper].
+//   - A256KW under a symmetric KEK: [NewA256KWRecipient] / [NewA256KWUnwrapper].
+//
+// Alternatively the CEK can be managed out of band — generated or unwrapped by a
+// custody service and handed to this package directly. [EncryptWithCEK] seals
+// under a caller-provided CEK and [DecryptWithCEK] decrypts with one, ignoring
+// the envelope's recipients. The two axes are orthogonal: either wrap algorithm
+// can be used for an in-envelope recipient, and the external-CEK path is
+// independent of both.
 //
 // # Wire format
 //
@@ -117,8 +123,8 @@ var (
 	ErrUnsupportedBodyAlg = errors.New("fee: unsupported body algorithm")
 
 	// ErrUnsupportedRecipientAlg means a matched recipient's key-wrap algorithm
-	// header does not match the unwrapper that was asked to recover it (e.g. a
-	// tenant unwrapper matched against an A256KW recipient).
+	// header does not match the unwrapper that was asked to recover it (e.g. an
+	// ECDH-ES unwrapper matched against an A256KW recipient).
 	ErrUnsupportedRecipientAlg = errors.New("fee: unsupported recipient key-wrap algorithm")
 
 	// ErrMalformedEnvelope means a required body header was missing or had the
@@ -127,6 +133,10 @@ var (
 
 	// ErrNilUnwrapper means Decrypt was given a nil RecipientUnwrapper.
 	ErrNilUnwrapper = errors.New("fee: nil recipient unwrapper")
+
+	// ErrInvalidCEK means a caller-provided content-encryption key (see
+	// EncryptWithCEK / DecryptWithCEK) was not the required AES-256 key length.
+	ErrInvalidCEK = errors.New("fee: content-encryption key must be 32 bytes")
 )
 
 // encryptConfig holds the resolved, optional Encrypt parameters.
@@ -162,16 +172,49 @@ func WithChunkSize(n int) EncryptOption {
 // caller MUST either read it to EOF or Close it: Close aborts the goroutine and
 // releases its resources. An encryption failure (reading plaintext, or
 // finalizing a chunk) surfaces as a non-EOF error from the reader's Read.
+//
+// To seal under a CEK you already hold (rather than a freshly generated one),
+// use [EncryptWithCEK].
 func Encrypt(plaintext io.Reader, recipients []Recipient, opts ...EncryptOption) (io.ReadCloser, error) {
+	cek := make([]byte, aesstream.KeySize)
+	if _, err := rand.Read(cek); err != nil {
+		return nil, fmt.Errorf("fee: generating content-encryption key: %w", err)
+	}
+	// encryptStream copies the CEK into the body cipher and wraps it to the
+	// recipients (all synchronously, before it returns), so our generated copy
+	// can be wiped once it returns — on every path.
+	defer zero(cek)
+	return encryptStream(plaintext, cek, recipients, opts...)
+}
+
+// EncryptWithCEK is [Encrypt] with a caller-provided content-encryption key
+// instead of a freshly generated one — for when the CEK is managed out of band
+// (e.g. derived deterministically, or issued by a custody service). cek must be
+// 32 bytes (AES-256). The envelope still carries whatever recipients are given;
+// pair it with [DecryptWithCEK] to recover without an in-envelope unwrap.
+//
+// The caller retains ownership of cek: it is copied into the body cipher and
+// wrapped to the recipients, but neither retained nor wiped by this call.
+func EncryptWithCEK(plaintext io.Reader, cek []byte, recipients []Recipient, opts ...EncryptOption) (io.ReadCloser, error) {
+	if len(cek) != aesstream.KeySize {
+		return nil, fmt.Errorf("%w, got %d", ErrInvalidCEK, len(cek))
+	}
+	return encryptStream(plaintext, cek, recipients, opts...)
+}
+
+// encryptStream is the shared core of Encrypt and EncryptWithCEK: it seals
+// plaintext under cek and returns a streaming reader over envelope||ciphertext.
+// It does not retain, modify, or wipe cek — the caller owns that decision.
+func encryptStream(plaintext io.Reader, cek []byte, recipients []Recipient, opts ...EncryptOption) (io.ReadCloser, error) {
 	if plaintext == nil {
 		return nil, errors.New("fee: nil plaintext reader")
 	}
 	if len(recipients) == 0 {
 		return nil, ErrNoRecipients
 	}
 	// Validate recipients before doing any encryption work, so a malformed
-	// recipient (a nil entry, or invalid contents such as a nil tenant key or a
-	// wrong-length region KEK) fails fast rather than after streaming has begun.
+	// recipient (a nil entry, or invalid contents such as a nil key or a
+	// wrong-length KEK) fails fast rather than after streaming has begun.
 	for i, r := range recipients {
 		if r == nil {
 			return nil, fmt.Errorf("fee: recipient %d is nil", i)
@@ -193,16 +236,8 @@ func Encrypt(plaintext io.Reader, recipients []Recipient, opts ...EncryptOption)
 			ErrMalformedEnvelope, cfg.chunkSize, aesstream.MinChunkSize, aesstream.MaxChunkSize)
 	}
 
-	// Fresh per-object content-encryption key and STREAM base nonce. The CEK is
-	// wiped once it has been copied into the body cipher and wrapped to every
-	// recipient; the wrapped copies, not this one, travel in the envelope.
-	cek := make([]byte, aesstream.KeySize)
-	if _, err := rand.Read(cek); err != nil {
-		return nil, fmt.Errorf("fee: generating content-encryption key: %w", err)
-	}
 	baseNonce, err := aesstream.NewBaseNonce()
 	if err != nil {
-		zero(cek)
 		return nil, fmt.Errorf("fee: generating base nonce: %w", err)
 	}
 
@@ -225,7 +260,6 @@ func Encrypt(plaintext io.Reader, recipients []Recipient, opts ...EncryptOption)
 	// be derived before the CEK is wrapped.
 	aad, err := env.EncStructure(nil)
 	if err != nil {
-		zero(cek)
 		return nil, fmt.Errorf("fee: building envelope AAD: %w", err)
 	}
 
@@ -239,7 +273,6 @@ func Encrypt(plaintext io.Reader, recipients []Recipient, opts ...EncryptOption)
 		ChunkSize: cfg.chunkSize,
 	})
 	if err != nil {
-		zero(cek)
 		return nil, fmt.Errorf("fee: initializing body cipher: %w", err)
 	}
 
@@ -248,21 +281,15 @@ func Encrypt(plaintext io.Reader, recipients []Recipient, opts ...EncryptOption)
 	for i, r := range recipients {
 		entry, werr := r.wrap(cek)
 		if werr != nil {
-			zero(cek)
 			return nil, werr
 		}
 		env.Recipients[i] = entry
 	}
 	header, err := env.Encode()
 	if err != nil {
-		zero(cek)
 		return nil, fmt.Errorf("fee: encoding envelope: %w", err)
 	}
 
-	// The CEK is now in the body cipher's key schedule and wrapped to every
-	// recipient; wipe our copy before streaming begins.
-	zero(cek)
-
 	go func() {
 		_, cerr := io.Copy(w, plaintext)
 		if cerr == nil {
@@ -305,9 +332,10 @@ func (e *encryptReader) Close() error { return e.pr.Close() }
 // fee/aesstream) means the plaintext is incomplete and must be discarded.
 //
 // If no recipient kid matches unwrap, Decrypt returns [ErrNoMatchingRecipient]
-// without attempting an unwrap. If the matched recipient's wrapped CEK cannot
-// be recovered (e.g. the wrong key), the unwrap error is returned and no
-// plaintext reader is produced.
+// without attempting an unwrap. If the matched recipient's wrapped CEK cannot be
+// recovered (e.g. the wrong key), the unwrap error is returned and no plaintext
+// reader is produced. To decrypt with a CEK obtained out of band, use
+// [DecryptWithCEK].
 func Decrypt(src io.Reader, unwrap RecipientUnwrapper) (io.Reader, error) {
 	if src == nil {
 		return nil, errors.New("fee: nil envelope reader")
@@ -321,25 +349,55 @@ func Decrypt(src io.Reader, unwrap RecipientUnwrapper) (io.Reader, error) {
 		return nil, fmt.Errorf("fee: decoding envelope: %w", err)
 	}
 
-	alg, ok := env.Headers.Protected.Int(cose.HeaderLabelAlg)
-	if !ok {
-		return nil, fmt.Errorf("%w: body algorithm header missing or not an integer", ErrUnsupportedBodyAlg)
-	}
-	if alg != algChunkedAES256GCMStream {
-		return nil, fmt.Errorf("%w: body algorithm %d is not chunked AES-256-GCM-STREAM", ErrUnsupportedBodyAlg, alg)
-	}
-
 	match, err := matchRecipient(env.Recipients, unwrap.keyID())
 	if err != nil {
 		return nil, err
 	}
-
 	cek, err := unwrap.unwrap(match)
 	if err != nil {
 		return nil, err
 	}
+	// The recovered CEK is ours; wipe it once openStream has copied it into the
+	// body cipher (synchronously, before it returns).
 	defer zero(cek)
 
+	return openStream(env, ciphertext, cek)
+}
+
+// DecryptWithCEK is [Decrypt] with a caller-provided content-encryption key
+// instead of one recovered from an in-envelope recipient — for when the CEK was
+// obtained out of band (e.g. unwrapped by a custody service). The envelope's
+// recipients are ignored. cek must be 32 bytes (AES-256).
+//
+// The caller retains ownership of cek: it is copied into the body cipher but
+// neither retained nor wiped by this call.
+func DecryptWithCEK(src io.Reader, cek []byte) (io.Reader, error) {
+	if src == nil {
+		return nil, errors.New("fee: nil envelope reader")
+	}
+	if len(cek) != aesstream.KeySize {
+		return nil, fmt.Errorf("%w, got %d", ErrInvalidCEK, len(cek))
+	}
+	env, ciphertext, err := cose.DecodeReader(src, cose.WithExpectedType(EnvelopeType))
+	if err != nil {
+		return nil, fmt.Errorf("fee: decoding envelope: %w", err)
+	}
+	return openStream(env, ciphertext, cek)
+}
+
+// openStream is the shared core of Decrypt and DecryptWithCEK: given a decoded
+// envelope, its detached ciphertext stream, and the content-encryption key, it
+// validates the body parameters and returns the streaming plaintext reader. It
+// copies cek into the body cipher and does not retain it.
+func openStream(env *cose.Encrypt, ciphertext io.Reader, cek []byte) (io.Reader, error) {
+	alg, ok := env.Headers.Protected.Int(cose.HeaderLabelAlg)
+	if !ok {
+		return nil, fmt.Errorf("%w: body algorithm header missing or not an integer", ErrUnsupportedBodyAlg)
+	}
+	if alg != algChunkedAES256GCMStream {
+		return nil, fmt.Errorf("%w: body algorithm %d is not chunked AES-256-GCM-STREAM", ErrUnsupportedBodyAlg, alg)
+	}
+
 	baseNonce, ok := env.Headers.Unprotected.Bytes(cose.HeaderLabelIV)
 	if !ok {
 		return nil, fmt.Errorf("%w: missing iv (base nonce)", ErrMalformedEnvelope)