doc.go

// Package vectors holds the FEE (Filecoin Encryption Envelope)
// cross-implementation test vectors: fixed fixture blobs that must decrypt
// identically under this Go implementation (fee/cose, fee/aesstream,
// fee/ecdhkw, fee/aeskw) and under the TypeScript reference implementation,
// foc-encryption (github.com/Kubuxu/foc-encryption-demo, packages/
// foc-encryption), pinned in pull-foc-encryption.sh.
//
// The reference is the source of truth for the wire format. It is pinned (see
// pull-foc-encryption.sh) to a fixed commit on foc-encryption-demo master — the
// merged fix (upstream PR #2) that makes the body AAD context follow the
// envelope structure per RFC 9052 §5.3. Commits before that fix seal tag-96
// bodies under "Encrypt0" and are not comparable with these vectors. The shape,
// verified against the pinned commit, is:
//
//	blob        = envelope || ciphertext          (detached payload)
//	envelope    = 16([protected, unprotected, null])                for no recipients
//	            | 96([protected, unprotected, null, recipients])    with recipients
//	protected   = {1: alg, 16: "application/vnd.foc-envelope+cose"}
//	unprotected = {5: baseNonce, -65790: chunkSize, -65791: chunkCount}
//	alg         = -65793  (chunked AES-256-GCM-STREAM)
//	body AAD    = [ context, protected, "" ]      context per RFC 9052 §5.3:
//	              "Encrypt" for a tag-96 envelope, "Encrypt0" for tag-16
//	chunk nonce = baseNonce[7] || chunkIndex[4 BE] || lastFlag[1]
//
// A recipient entry is [ {1: alg}, {4: kid, ...}, wrappedKey ]. The reference
// carries wrappedKey opaquely and never unwraps it — decryption takes the CEK
// directly — so cross-implementation coverage of the recipient layer proves the
// reference parses our recipient descriptors and decrypts the body from the
// shared CEK; the actual CEK unwrap (ECDH-ES+A256KW over X25519, and A256KW) is
// asserted on the Go side in vectors_test.go.
//
// Fixtures live under testdata/<name>/ as blob.bin, plaintext.bin and
// meta.json. TestVectors reads and verifies every fixture. The Go-produced
// fixtures are (re)generated by TestGenerate (guarded by FEE_VECTORS_REGEN=1);
// the TS-produced ones by pull-foc-encryption.sh, which also confirms the real
// foc-encryption decrypts the Go-produced fixtures. See README.md.
package vectors