fee/cose: COSE_Encrypt envelope codec with detached payload (FIL-469)

[Peeja]

This piece is just an implementation of COSE (RFC 8152, RFC 9052). More specifically, it's just enough to implement FEE for our needs, which means just COSE_Encrypt. (COSE_Encrypt0, the version with no recipients in the envelope, is part of FEE too, but we're not going to use it, so we leave it alone.) It also means only detached payloads, where the payload value in the FEE envelope is nil and the ciphertext bytes are stored separately—in our case, they'll be immediately following the envelope.

---

Implements FIL-469. Adds fee/cose, the low-level COSE (RFC 9052) envelope layer beneath the forthcoming FEE package: it encodes/decodes a COSE_Encrypt structure (CBOR tag 96) with a detached payload and builds the Enc_structure that COSE feeds to an AEAD as additional authenticated data.

The package is FEE-agnostic and performs no cryptography — it carries opaque header parameters and wrapped content-encryption keys, leaving key agreement, key wrap (ECDH-ES+A256KW over X25519), and the content AEAD (AES-256-GCM / chunked STREAM) to the higher-level fee package.

What's here

• Encode — deterministic (RFC 8949 core) tag-96 envelope with a null body ciphertext (detached); an empty protected header serializes to h'' per COSE's empty_or_serialized_map rule.
• Decode — strict parsing that returns the trailing detached ciphertext alongside the envelope; rejects a wrong/missing tag, malformed CBOR, duplicate header labels, a non-null body ciphertext, and nested recipients — never yielding a partial structure. WithExpectedType pins the protected typ header so a profile such as FEE can enforce its envelope type.
• EncStructure — AAD built from the exact on-wire protected bytes (preserved as RawProtected on decode), so authentication is stable across an encode/decode round trip.
• Header — a label/value map with typed accessors and integer-label normalization; arbitrary/unknown parameters, including nested maps, round-trip losslessly.

Uses github.com/fxamacker/cbor/v2 for COSE-grade deterministic encoding and robust malformed-input handling.

Acceptance criteria

• Encode a COSE_Encrypt (tag 96) with a nil ciphertext and one or more recipients → valid CBOR.
• Decode recovers all protected fields, unprotected headers, and recipient entries intact.
• Build the Enc_structure and confirm it matches the expected AAD bytes.
• Decoding an envelope with a wrong or missing typ returns an error.
• Malformed CBOR returns an error rather than a partial structure.
• Multi-recipient round trip recovers each recipient's header fields and wrapped CEK bytes intact.

Tests

Round trips (single + multi-recipient), full-field preservation including nested maps, the detached-payload split, hand-verified golden AAD/envelope vectors, typ validation, a 21-case malformed-input table, and a runnable Example. go build ./..., go vet, gofmt, and go test -race all pass (~90% statement coverage).

Scope notes

Per the ticket, this implements COSE_Encrypt (tag 96) only. COSE_Encrypt0 (tag 16) and nested recipients are intentionally out of scope and easy to add later if the single-recipient/PSK path needs tag 16. The FEE-specific typ value and private-use alg/label numbers will live in the parent fee package, keeping fee/cose a generic COSE codec.

🤖 Generated with Claude Code

https://claude.ai/code/session_01GAH2CgLUJgzFsqTzfiNxKT

---

Generated by Claude Code

[Copilot]

Pull request overview

Adds a new low-level fee/cose package implementing a COSE_Encrypt (CBOR tag 96) envelope codec with a detached payload, plus AAD (Enc_structure) construction for downstream AEAD usage.

Changes:

• Introduces fee/cose with deterministic COSE_Encrypt encoding, strict decoding (incl. typ validation via WithExpectedType), and AAD construction.
• Adds a header map abstraction (Header) with label normalization and typed accessors.
• Adds extensive tests: round-trips, golden vectors, malformed-input table, and a runnable Example.

Reviewed changes

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

Show a summary per file

File	Description
go.mod	Adds github.com/fxamacker/cbor/v2 dependency (and indirect float16).
go.sum	Adds checksums for new CBOR dependency and transitive float16.
fee/cose/cose.go	Defines core types/constants, sentinel errors, and CBOR encode/decode modes.
fee/cose/encrypt.go	Implements deterministic encoding, EncStructure, and protected header byte handling.
fee/cose/decode.go	Implements strict decoding with detached payload split and optional typ enforcement.
fee/cose/header.go	Implements COSE header map normalization and typed accessors.
fee/cose/cose_test.go	End-to-end and property-style tests (determinism, round-trip, detached payload, AAD stability).
fee/cose/decode_test.go	Malformed input table tests + WithExpectedType behavior tests.
fee/cose/header_test.go	Unit tests for header normalization/accessors and encode-time invalid label handling.
fee/cose/vectors_test.go	Golden vectors for encoding/decoding and AAD construction cross-checking.
fee/cose/example_test.go	Example demonstrating envelope lifecycle and detached ciphertext handling.

---

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

[frrist]

I'm going to sound like a broken record across all these crypto PRs; I lack the depth of knowledge to determine is this is "correct", though it looks good to me:

Approving so this isn't blocked. But flagging, as a follow-up rather than an objection: this is hand-rolled cryptography, and the blast radius if any of it is subtly wrong is large.