fee: adapt composer + DecodeReader to unified cose.Envelope (FIL-569)

FIL-473 collapsed cose.Encrypt/Encrypt0 into a single cose.Envelope (tag and
Enc_structure context computed from recipient presence) and replaced the two
byte decoders with one tag-dispatching cose.Decode. Adapt this PR's additions
to match:

  - cose.DecodeReader now returns *cose.Envelope, sharing the decodeEnvelope
    validation core with cose.Decode; the redundant DecodedEnvelope type is gone.
  - encryptStream builds one cose.Envelope and uses it for both the AAD
    (EncStructure) and the encoded header (Encode), instead of a DecodedEnvelope
    for the AAD plus a separate Encrypt/Encrypt0 for the header. The envelopeTag
    helper is dropped — recipient presence is the form.
  - Decrypt discriminates the recipient-less envelope with len(Recipients)==0
    rather than a Tag comparison; openStream takes *cose.Envelope.
  - Tests updated: DecodeReader equivalence now checks against cose.Decode, and
    fee tests build cose.Envelope / call cose.Decode.

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

Author: claude

fee/cose/decode.go

@@ -14,7 +14,7 @@ type decodeConfig struct {
 	expectedType string
 }
 
-// DecodeOption configures [Decode].
+// DecodeOption configures [Decode] and [DecodeReader].
 type DecodeOption func(*decodeConfig)
 
 // WithExpectedType requires the decoded protected header to carry a "typ"
@@ -149,52 +149,19 @@ 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.
+// 16) from the front of r and returns the decoded [Envelope] 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 [DecodeEncrypt] 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)
-	}
-
+// It is the streaming counterpart to [Decode], dispatching on the same tags and
+// as strict — both share the decodeEnvelope validation core: 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 *Envelope, rest io.Reader, err error) {
 	// 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)
@@ -208,10 +175,6 @@ func DecodeReader(r io.Reader, opts ...DecodeOption) (env *DecodedEnvelope, rest
 	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)
 	}
@@ -220,42 +183,13 @@ func DecodeReader(r io.Reader, opts ...DecodeOption) (env *DecodedEnvelope, rest
 		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])
+	env, err = decodeEnvelope(tag.Number, arr)
 	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)
-		}
+	if err := newDecodeConfig(opts).checkTyp(env.Headers.Protected); err != nil {
+		return nil, nil, err
 	}
-
 	return env, rest, nil
 }
 

fee/cose/decode_reader_test.go

@@ -9,16 +9,16 @@ import (
 	"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.
+// TestDecodeReader exercises the streaming decoder: it decodes both envelope
+// forms 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, 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{
+	t.Run("with recipients (COSE_Encrypt, tag 96)", func(t *testing.T) {
+		enc := &Envelope{
 			Headers: Headers{
 				Protected: Header{}.
 					Set(HeaderLabelType, exampleType).
@@ -39,15 +39,14 @@ func TestDecodeReader(t *testing.T) {
 
 		env, rest, err := DecodeReader(bytes.NewReader(blob))
 		require.NoError(t, err)
-		require.Equal(t, TagCOSEEncrypt, env.Tag)
-		require.Len(t, env.Recipients, 1)
+		require.Len(t, env.Recipients, 1, "recipient presence marks the tag-96 form")
 		gotRest, err := io.ReadAll(rest)
 		require.NoError(t, err)
 		require.Equal(t, ciphertext, gotRest)
 
-		// The streaming decode agrees with the byte-based DecodeEncrypt on both
-		// the trailing ciphertext and the AAD (context "Encrypt").
-		byteEnv, byteRest, err := DecodeEncrypt(blob)
+		// 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)
@@ -57,8 +56,8 @@ func TestDecodeReader(t *testing.T) {
 		require.Equal(t, want, got)
 	})
 
-	t.Run("tag 16 COSE_Encrypt0", func(t *testing.T) {
-		enc0 := &Encrypt0{
+	t.Run("recipient-less (COSE_Encrypt0, tag 16)", func(t *testing.T) {
+		enc0 := &Envelope{
 			Headers: Headers{
 				Protected: Header{}.
 					Set(HeaderLabelType, exampleType).
@@ -72,14 +71,13 @@ func TestDecodeReader(t *testing.T) {
 
 		env, rest, err := DecodeReader(bytes.NewReader(blob))
 		require.NoError(t, err)
-		require.Equal(t, TagCOSEEncrypt0, env.Tag)
-		require.Nil(t, env.Recipients)
+		require.Empty(t, env.Recipients, "recipient absence marks the tag-16 form")
 		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)
+		// Agrees with the byte-based Decode (context "Encrypt0").
+		byteEnv, byteRest, err := Decode(blob)
 		require.NoError(t, err)
 		require.Equal(t, ciphertext, byteRest)
 		want, err := byteEnv.EncStructure(nil)
@@ -90,7 +88,7 @@ func TestDecodeReader(t *testing.T) {
 	})
 
 	t.Run("ciphertext split across the decoder buffer and the reader", func(t *testing.T) {
-		enc0 := &Encrypt0{
+		enc0 := &Envelope{
 			Headers: Headers{Protected: Header{}.Set(HeaderLabelType, exampleType)},
 		}
 		header, err := enc0.Encode()
@@ -101,14 +99,14 @@ func TestDecodeReader(t *testing.T) {
 		// 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)
+		require.Empty(t, env.Recipients)
 		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{
+		enc0 := &Envelope{
 			Headers: Headers{Protected: Header{}.Set(HeaderLabelType, "application/other")},
 		}
 		header, err := enc0.Encode()

fee/fee.go

@@ -279,33 +279,30 @@ func encryptStream(plaintext io.Reader, cek []byte, recipients []Recipient, opts
 		Unprotected: unprotected,
 	}
 
-	// The AAD binds the protected header into every STREAM chunk via the
-	// Enc_structure whose context matches the envelope tag ("Encrypt0" for a
-	// recipient-less envelope, "Encrypt" otherwise). It depends only on the
-	// (now-fixed) protected header, so it can be derived before the CEK is wrapped.
-	aad, err := (&cose.DecodedEnvelope{Tag: envelopeTag(len(recipients)), Headers: headers}).EncStructure(nil)
-	if err != nil {
-		return nil, fmt.Errorf("fee: building envelope AAD: %w", err)
+	// Wrap the CEK to each recipient (none → a recipient-less envelope). All the
+	// fallible header work happens here, before the pipe is created, so an error
+	// returns before the pipe exists and can never orphan a PipeReader/PipeWriter
+	// pair.
+	entries := make([]*cose.Recipient, len(recipients))
+	for i, r := range recipients {
+		entry, werr := r.wrap(cek)
+		if werr != nil {
+			return nil, werr
+		}
+		entries[i] = entry
 	}
 
-	// Encode the envelope header before creating the pipe: a COSE_Encrypt0 (no
-	// recipients) or a COSE_Encrypt whose recipients each wrap the CEK. All the
-	// fallible header work happens up front, so an error here returns before the
-	// pipe exists and can never orphan a PipeReader/PipeWriter pair.
-	var header []byte
-	if len(recipients) == 0 {
-		header, err = (&cose.Encrypt0{Headers: headers}).Encode()
-	} else {
-		entries := make([]*cose.Recipient, len(recipients))
-		for i, r := range recipients {
-			entry, werr := r.wrap(cek)
-			if werr != nil {
-				return nil, werr
-			}
-			entries[i] = entry
-		}
-		header, err = (&cose.Encrypt{Headers: headers, Recipients: entries}).Encode()
+	// One envelope drives both the AAD and the encoded header. Recipient presence
+	// alone selects the form — a COSE_Encrypt (tag 96) when present, a
+	// recipient-less COSE_Encrypt0 (tag 16) when not — and the Enc_structure
+	// context tracks it. The AAD binds the protected header into every STREAM
+	// chunk.
+	env := &cose.Envelope{Headers: headers, Recipients: entries}
+	aad, err := env.EncStructure(nil)
+	if err != nil {
+		return nil, fmt.Errorf("fee: building envelope AAD: %w", err)
 	}
+	header, err := env.Encode()
 	if err != nil {
 		return nil, fmt.Errorf("fee: encoding envelope: %w", err)
 	}
@@ -347,15 +344,6 @@ func encryptStream(plaintext io.Reader, cek []byte, recipients []Recipient, opts
 	}, nil
 }
 
-// envelopeTag reports the COSE tag for an envelope with the given recipient
-// count: tag 16 (COSE_Encrypt0) for none, tag 96 (COSE_Encrypt) otherwise.
-func envelopeTag(nRecipients int) uint64 {
-	if nRecipients == 0 {
-		return cose.TagCOSEEncrypt0
-	}
-	return cose.TagCOSEEncrypt
-}
-
 // chunkCountFor reports how many STREAM chunks a plaintext of nPlain bytes
 // produces at the given chunk size. Empty input is one (empty) final chunk.
 func chunkCountFor(nPlain, chunkSize int64) int64 {
@@ -406,7 +394,7 @@ func Decrypt(src io.Reader, unwrap RecipientUnwrapper) (io.Reader, error) {
 	if err != nil {
 		return nil, fmt.Errorf("fee: decoding envelope: %w", err)
 	}
-	if env.Tag != cose.TagCOSEEncrypt {
+	if len(env.Recipients) == 0 {
 		return nil, ErrNoRecipientsInEnvelope
 	}
 
@@ -451,7 +439,7 @@ func DecryptWithCEK(src io.Reader, cek []byte) (io.Reader, error) {
 // 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.DecodedEnvelope, ciphertext io.Reader, cek []byte) (io.Reader, error) {
+func openStream(env *cose.Envelope, 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)

fee/fee_test.go

@@ -436,7 +436,7 @@ func TestDecryptCorruptedProtectedHeader(t *testing.T) {
 
 	// Locate the protected-header bytes via a clean decode, then flip the first
 	// byte (the CBOR map head) so the protected bytes are no longer a map.
-	env, _, err := cose.DecodeEncrypt(blob, cose.WithExpectedType(fee.EnvelopeType))
+	env, _, err := cose.Decode(blob, cose.WithExpectedType(fee.EnvelopeType))
 	require.NoError(t, err)
 	require.NotEmpty(t, env.Headers.RawProtected)
 	off := bytes.Index(blob, env.Headers.RawProtected)
@@ -477,7 +477,7 @@ func TestDecryptTamperedCiphertext(t *testing.T) {
 // COSE typ) is refused before any key material is used.
 func TestDecryptWrongEnvelopeType(t *testing.T) {
 	// A well-formed COSE_Encrypt with a non-FEE typ and a single recipient.
-	other := &cose.Encrypt{
+	other := &cose.Envelope{
 		Headers: cose.Headers{
 			Protected: cose.Header{}.Set(cose.HeaderLabelType, "application/not-fee"),
 		},
@@ -550,7 +550,7 @@ func TestEnvelopeWireConventions(t *testing.T) {
 	)
 	require.NoError(t, err)
 
-	env, ciphertext, err := cose.DecodeEncrypt(blob, cose.WithExpectedType(fee.EnvelopeType))
+	env, ciphertext, err := cose.Decode(blob, cose.WithExpectedType(fee.EnvelopeType))
 	require.NoError(t, err)
 
 	// Protected header: typ and body algorithm are authenticated via the AAD.
@@ -610,7 +610,7 @@ func TestContentLengthChunkCount(t *testing.T) {
 		)
 		require.NoError(t, err)
 
-		env, _, err := cose.DecodeEncrypt(blob, cose.WithExpectedType(fee.EnvelopeType))
+		env, _, err := cose.Decode(blob, cose.WithExpectedType(fee.EnvelopeType))
 		require.NoError(t, err)
 		cc, ok := env.Headers.Unprotected.Int(labelChunkCount)
 		require.True(t, ok, "chunk count present when content length declared")
@@ -626,7 +626,7 @@ func TestContentLengthChunkCount(t *testing.T) {
 		)
 		require.NoError(t, err)
 
-		env, _, err := cose.DecodeEncrypt(blob, cose.WithExpectedType(fee.EnvelopeType))
+		env, _, err := cose.Decode(blob, cose.WithExpectedType(fee.EnvelopeType))
 		require.NoError(t, err)
 		require.False(t, env.Headers.Unprotected.Has(labelChunkCount),
 			"chunk count omitted when content length unknown")
@@ -737,7 +737,7 @@ func TestDecryptMalformedChunkSizeHeader(t *testing.T) {
 
 	// Hand-build an envelope whose chunk-size header (FEE private-use label, in
 	// the unprotected header) is present but holds a string instead of an integer.
-	env := &cose.Encrypt{
+	env := &cose.Envelope{
 		Headers: cose.Headers{
 			Protected: cose.Header{}.
 				Set(cose.HeaderLabelAlg, algChunkedStream).
@@ -785,7 +785,7 @@ func TestDecryptMalformedEphemeralKey(t *testing.T) {
 	for _, tc := range cases {
 		tc := tc
 		t.Run(tc.name, func(t *testing.T) {
-			env := &cose.Encrypt{
+			env := &cose.Envelope{
 				Headers: cose.Headers{
 					Protected: cose.Header{}.
 						Set(cose.HeaderLabelAlg, algChunkedStream).