feat(fee): compose FEE encrypt/decrypt over the pinned foc wire format (FIL-569)

Add a top-level `fee` package that sequences the four FEE primitives
(cose, aesstream, ecdhkw, aeskw) into a small streaming API:

  - Encrypt(plaintext, recipients) -> io.ReadCloser over envelope||ciphertext
  - Decrypt(src, unwrap) -> io.Reader over the recovered plaintext
  - EncryptWithCEK / DecryptWithCEK for an externally-managed CEK

Both directions stream with O(chunk size) memory: Encrypt seals through an
io.Pipe fed by a background goroutine; Decrypt reads only the envelope header
up front (via the new cose.DecodeReader) and streams the detached ciphertext.

Recipients are domain-agnostic and selected on decrypt by an opaque,
caller-supplied kid (a DID verification method ID): ECDH-ES+A256KW to an X25519
public key, or A256KW under a symmetric KEK. Both kinds may be mixed in one
envelope; a kid that matches no recipient yields ErrNoMatchingRecipient. With
no recipients, EncryptWithCEK emits a recipient-less COSE_Encrypt0 (tag 16).

The wire format matches the foc-encryption reference and the FIL-473
cross-implementation vectors: typ application/vnd.foc-envelope+cose, the
chunked AES-256-GCM-STREAM body alg in the protected header, and the base
nonce / chunk size (and, when the content length is known via WithContentLength,
the advisory chunk count) in the unprotected header. The ECDH-ES ephemeral key
is a self-describing COSE_Key (kty=OKP, crv=X25519), decoded and validated on
unwrap. The body AAD is the envelope's own Enc_structure, so its context tracks
the tag.

Also add cose.DecodeReader: a streaming, tag-16/96-dispatching decoder that
returns the decoded header plus a reader over the trailing detached ciphertext,
producing the same AAD and trailing bytes as the byte-based Decode. De-word the
aeskw/ecdhkw package docs (drop the app-specific "tenant"/"region" vocabulary)
so the primitives read as a standalone FEE library.

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; a direct A256KW recipient takes a KEK straight from a key provider.
 // Both paths call Wrap and Unwrap identically.
 package aeskw
 

fee/cose/decode.go

@@ -3,6 +3,7 @@ package cose
 import (
 	"bytes"
 	"fmt"
+	"io"
 
 	"github.com/fxamacker/cbor/v2"
 )
@@ -181,6 +182,116 @@ func PeekTag(data []byte) (uint64, error) {
 	return tag.Number, nil
 }
 
+// DecodedEnvelope is a decoded detached COSE envelope header returned by
+// [DecodeReader]: either a COSE_Encrypt (tag 96, carrying Recipients) or a
+// COSE_Encrypt0 (tag 16, no recipients), distinguished by Tag.
+type DecodedEnvelope struct {
+	// Tag is [TagCOSEEncrypt] (96) or [TagCOSEEncrypt0] (16).
+	Tag uint64
+	// Headers is the body protected/unprotected header pair.
+	Headers Headers
+	// Recipients are the per-recipient wrapped-key entries; nil for a
+	// COSE_Encrypt0 (tag 16).
+	Recipients []*Recipient
+}
+
+// EncStructure returns the body AAD Enc_structure for this envelope, using the
+// context that matches its tag: "Encrypt" for a COSE_Encrypt (tag 96),
+// "Encrypt0" for a COSE_Encrypt0 (tag 16). See [Encrypt.EncStructure].
+func (e *DecodedEnvelope) EncStructure(externalAAD []byte) ([]byte, error) {
+	ctx := contextEncrypt
+	if e.Tag == TagCOSEEncrypt0 {
+		ctx = contextEncrypt0
+	}
+	prot, err := e.Headers.protectedBytes()
+	if err != nil {
+		return nil, fmt.Errorf("cose: building Enc_structure: %w", err)
+	}
+	return encStructureBytes(ctx, prot, externalAAD)
+}
+
+// DecodeReader reads one detached COSE_Encrypt (tag 96) or COSE_Encrypt0 (tag
+// 16) from the front of r and returns the decoded envelope header together with
+// rest: a reader over the bytes that follow the self-delimited envelope item —
+// the detached ciphertext. rest draws first from whatever the decoder buffered
+// past the envelope, then from r, so only the (small) header is held in memory
+// and an arbitrarily large ciphertext can be streamed.
+//
+// It is the streaming, tag-dispatching counterpart to [Decode] and
+// [DecodeEncrypt0], and is as strict as they are: a byte-string protected
+// header, map headers without duplicate labels, a null detached body, and — for
+// tag 96 — at least one well-formed 3-element recipient. Any deviation returns
+// an error (wrapping a package sentinel) and a nil envelope.
+func DecodeReader(r io.Reader, opts ...DecodeOption) (env *DecodedEnvelope, rest io.Reader, err error) {
+	var cfg decodeConfig
+	for _, o := range opts {
+		o(&cfg)
+	}
+
+	// Read exactly one CBOR item. Whatever the decoder buffered past that item,
+	// followed by the unread remainder of r, is the detached payload.
+	dec := decMode.NewDecoder(r)
+	var first cbor.RawMessage
+	if err := dec.Decode(&first); err != nil {
+		return nil, nil, fmt.Errorf("%w: %v", ErrMalformed, err)
+	}
+	rest = io.MultiReader(dec.Buffered(), r)
+
+	var tag cbor.RawTag
+	if err := decMode.Unmarshal(first, &tag); err != nil {
+		return nil, nil, fmt.Errorf("%w: %v", ErrNotEncrypt, err)
+	}
+	if tag.Number != TagCOSEEncrypt && tag.Number != TagCOSEEncrypt0 {
+		return nil, nil, fmt.Errorf("%w: got tag %d", ErrNotEncrypt, tag.Number)
+	}
+
+	if cborMajor(tag.Content) != majorArray {
+		return nil, nil, fmt.Errorf("%w: tag content is not an array", ErrMalformed)
+	}
+	var arr []cbor.RawMessage
+	if err := decMode.Unmarshal(tag.Content, &arr); err != nil {
+		return nil, nil, fmt.Errorf("%w: %v", ErrMalformed, err)
+	}
+
+	// A COSE_Encrypt is a 4-element array (with recipients); a COSE_Encrypt0 is
+	// a 3-element array (no recipients).
+	wantLen := 3
+	if tag.Number == TagCOSEEncrypt {
+		wantLen = 4
+	}
+	if len(arr) != wantLen {
+		return nil, nil, fmt.Errorf("%w: array has %d elements, want %d", ErrMalformed, len(arr), wantLen)
+	}
+
+	headers, err := decodeHeaders(arr[0], arr[1])
+	if err != nil {
+		return nil, nil, err
+	}
+
+	// Detached payload: the body ciphertext must be null.
+	if !isNull(arr[2]) {
+		return nil, nil, ErrDetachedPayload
+	}
+
+	env = &DecodedEnvelope{Tag: tag.Number, Headers: headers}
+	if tag.Number == TagCOSEEncrypt {
+		recipients, err := decodeRecipients(arr[3])
+		if err != nil {
+			return nil, nil, err
+		}
+		env.Recipients = recipients
+	}
+
+	if cfg.checkType {
+		got, ok := env.Headers.Protected.Text(HeaderLabelType)
+		if !ok || got != cfg.expectedType {
+			return nil, nil, fmt.Errorf("%w: got %q, want %q", ErrUnexpectedType, got, cfg.expectedType)
+		}
+	}
+
+	return env, rest, nil
+}
+
 // decodeHeaders decodes a [protected, unprotected] pair. The protected element
 // is a byte string whose content (when non-empty) is itself a CBOR map; its
 // raw bytes are preserved on RawProtected for AAD stability.

fee/cose/decode_reader_test.go

@@ -0,0 +1,136 @@
+package cose
+
+import (
+	"bytes"
+	"io"
+	"testing"
+	"testing/iotest"
+
+	"github.com/stretchr/testify/require"
+)
+
+// TestDecodeReader exercises the streaming, tag-dispatching decoder: it decodes
+// both envelope shapes off a reader, streams back the detached ciphertext that
+// follows the header, and — critically — produces the same Enc_structure (AAD)
+// and the same trailing bytes as the byte-based Decode / DecodeEncrypt0, so a
+// caller can decrypt an envelope read either way.
+func TestDecodeReader(t *testing.T) {
+	ciphertext := []byte("detached-stream-ciphertext-bytes-0123456789")
+
+	t.Run("tag 96 COSE_Encrypt", func(t *testing.T) {
+		enc := &Encrypt{
+			Headers: Headers{
+				Protected: Header{}.
+					Set(HeaderLabelType, exampleType).
+					Set(HeaderLabelAlg, int64(-65793)),
+				Unprotected: Header{}.Set(HeaderLabelIV, []byte("0123456789ab")),
+			},
+			Recipients: []*Recipient{{
+				Headers: Headers{
+					Protected:   Header{}.Set(HeaderLabelAlg, AlgA256KW),
+					Unprotected: Header{}.Set(HeaderLabelKID, []byte("kid-1")),
+				},
+				Ciphertext: []byte("wrapped-cek-0123456789abcdef"),
+			}},
+		}
+		header, err := enc.Encode()
+		require.NoError(t, err)
+		blob := append(append([]byte{}, header...), ciphertext...)
+
+		env, rest, err := DecodeReader(bytes.NewReader(blob))
+		require.NoError(t, err)
+		require.Equal(t, TagCOSEEncrypt, env.Tag)
+		require.Len(t, env.Recipients, 1)
+		gotRest, err := io.ReadAll(rest)
+		require.NoError(t, err)
+		require.Equal(t, ciphertext, gotRest)
+
+		// The streaming decode agrees with the byte-based Decode on both the
+		// trailing ciphertext and the AAD (context "Encrypt").
+		byteEnv, byteRest, err := Decode(blob)
+		require.NoError(t, err)
+		require.Equal(t, ciphertext, byteRest)
+		want, err := byteEnv.EncStructure(nil)
+		require.NoError(t, err)
+		got, err := env.EncStructure(nil)
+		require.NoError(t, err)
+		require.Equal(t, want, got)
+	})
+
+	t.Run("tag 16 COSE_Encrypt0", func(t *testing.T) {
+		enc0 := &Encrypt0{
+			Headers: Headers{
+				Protected: Header{}.
+					Set(HeaderLabelType, exampleType).
+					Set(HeaderLabelAlg, int64(-65793)),
+				Unprotected: Header{}.Set(HeaderLabelIV, []byte("0123456789ab")),
+			},
+		}
+		header, err := enc0.Encode()
+		require.NoError(t, err)
+		blob := append(append([]byte{}, header...), ciphertext...)
+
+		env, rest, err := DecodeReader(bytes.NewReader(blob))
+		require.NoError(t, err)
+		require.Equal(t, TagCOSEEncrypt0, env.Tag)
+		require.Nil(t, env.Recipients)
+		gotRest, err := io.ReadAll(rest)
+		require.NoError(t, err)
+		require.Equal(t, ciphertext, gotRest)
+
+		// Agrees with the byte-based DecodeEncrypt0 (context "Encrypt0").
+		byteEnv, byteRest, err := DecodeEncrypt0(blob)
+		require.NoError(t, err)
+		require.Equal(t, ciphertext, byteRest)
+		want, err := byteEnv.EncStructure(nil)
+		require.NoError(t, err)
+		got, err := env.EncStructure(nil)
+		require.NoError(t, err)
+		require.Equal(t, want, got)
+	})
+
+	t.Run("ciphertext split across the decoder buffer and the reader", func(t *testing.T) {
+		enc0 := &Encrypt0{
+			Headers: Headers{Protected: Header{}.Set(HeaderLabelType, exampleType)},
+		}
+		header, err := enc0.Encode()
+		require.NoError(t, err)
+		blob := append(append([]byte{}, header...), ciphertext...)
+
+		// One byte at a time forces the header to be reassembled from many reads
+		// and the ciphertext to straddle the decoder's read-ahead and the source.
+		env, rest, err := DecodeReader(iotest.OneByteReader(bytes.NewReader(blob)))
+		require.NoError(t, err)
+		require.Equal(t, TagCOSEEncrypt0, env.Tag)
+		gotRest, err := io.ReadAll(rest)
+		require.NoError(t, err)
+		require.Equal(t, ciphertext, gotRest)
+	})
+
+	t.Run("expected type mismatch", func(t *testing.T) {
+		enc0 := &Encrypt0{
+			Headers: Headers{Protected: Header{}.Set(HeaderLabelType, "application/other")},
+		}
+		header, err := enc0.Encode()
+		require.NoError(t, err)
+
+		env, rest, err := DecodeReader(bytes.NewReader(header), WithExpectedType(exampleType))
+		require.Nil(t, env)
+		require.Nil(t, rest)
+		require.ErrorIs(t, err, ErrUnexpectedType)
+	})
+
+	t.Run("not a COSE tag", func(t *testing.T) {
+		env, rest, err := DecodeReader(bytes.NewReader([]byte{0x01}))
+		require.Nil(t, env)
+		require.Nil(t, rest)
+		require.ErrorIs(t, err, ErrNotEncrypt)
+	})
+
+	t.Run("empty input", func(t *testing.T) {
+		env, rest, err := DecodeReader(bytes.NewReader(nil))
+		require.Nil(t, env)
+		require.Nil(t, rest)
+		require.ErrorIs(t, err, ErrMalformed)
+	})
+}

fee/ecdhkw/ecdhkw.go

@@ -2,7 +2,9 @@
 // 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
+// This is one of FEE's two CEK wraps: it delivers the CEK to a recipient
+// identified by an X25519 public key (the sibling fee/aeskw package is the
+// other, wrapping directly under a symmetric KEK). 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