refactor: rename body material to descriptor

Use descriptor terminology for the cached, non-secret envelope\nmetadata returned by Encrypt and consumed by range decryption.\nThis matches the review feedback and avoids implying that the\nvalue carries key material.\n\nAssisted-by: GPT-5.4:gpt-5.4

Author: bajtos

README.md

@@ -46,7 +46,7 @@ import (
 
 | Package | Purpose |
 |---|---|
-| [`fee`](.) (root) | Composes the primitives below into a small API: whole-object `Encrypt`/`Decrypt`, byte-range `DecryptRange`, and the cacheable envelope parameters (`BodyMaterial`) that let a range read skip the header. Adds no cryptography of its own. |
+| [`fee`](.) (root) | Composes the primitives below into a small API: whole-object `Encrypt`/`Decrypt`, byte-range `DecryptRange`, and the cacheable envelope parameters (`BodyDescriptor`) that let a range read skip the header. Adds no cryptography of its own. |
 | [`aesstream`](./aesstream) | The chunked AES-256-GCM STREAM body cipher: streaming `Writer`/`Reader` plus the range primitives (`CiphertextRange`, `SpanReader`, `OpenSpan`) that `fee.DecryptRange` is built on. |
 | [`cose`](./cose) | Just enough of COSE (RFC 9052): `COSE_Encrypt` (tag 96) / `COSE_Encrypt0` (tag 16) with a detached payload, and the `Enc_structure` AAD. |
 | [`ecdhkw`](./ecdhkw) | ECDH-ES+A256KW key wrap over X25519 (COSE algorithm −31). |
@@ -327,13 +327,13 @@ They are complete before any plaintext is read, so a writer can store them while
 the upload is still streaming:
 
 ```go
-// m goes alongside the blob's location and size.
-r, m, err := fee.Encrypt(plaintext, recipients)
+// d goes alongside the blob's location and size.
+r, d, err := fee.Encrypt(plaintext, recipients)
 ```
 
-`fee.DecryptRangeWithMaterial(blob, blobSize, m, cek, off, length)` then serves a
+`fee.DecryptRangeWithDescriptor(blob, blobSize, d, cek, off, length)` then serves a
 range with no envelope round trip at all: the only bytes fetched are the
-ciphertext chunks the range overlaps. `m.PlaintextSize(blobSize)` answers a `HEAD`
+ciphertext chunks the range overlaps. `d.PlaintextSize(blobSize)` answers a `HEAD`
 or resolves a suffix range from the stored record alone, reading nothing.
 
 Every field is non-secret — all four are already in the clear at the front of the

material.go descriptor.gomaterial.go renamed to descriptor.go

@@ -8,14 +8,14 @@ import (
 	"github.com/filecoin-project/go-fee/aesstream"
 )
 
-// ErrIncompleteMaterial means a [BodyMaterial] is missing a field, or carries one
-// that cannot describe a FEE body — a value that could not decrypt anything.
-var ErrIncompleteMaterial = errors.New("fee: incomplete body material")
+// ErrIncompleteDescriptor means a [BodyDescriptor] is missing a field, or carries
+// one that cannot describe a FEE body — a value that could not decrypt anything.
+var ErrIncompleteDescriptor = errors.New("fee: incomplete body descriptor")
 
-// BodyMaterial is everything a range decrypt needs from a FEE envelope, so a
+// BodyDescriptor is everything a range decrypt needs from a FEE envelope, so a
 // caller that cached it can serve a byte range without fetching or decoding the
 // envelope header at all. It is returned by [Encrypt] / [EncryptWithCEK] at
-// encryption time and consumed by [DecryptRangeWithMaterial].
+// encryption time and consumed by [DecryptRangeWithDescriptor].
 //
 // It exists for stores that keep their own metadata alongside the blob: the
 // envelope is a fixed prefix of every stored object, so re-reading it on each
@@ -35,8 +35,8 @@ var ErrIncompleteMaterial = errors.New("fee: incomplete body material")
 // plausible-looking plaintext. The worst case is an unreadable object, not an
 // incorrect one.
 //
-// The zero value is not usable; see [BodyMaterial.Validate].
-type BodyMaterial struct {
+// The zero value is not usable; see [BodyDescriptor.Validate].
+type BodyDescriptor struct {
 	// HeaderLen is the encoded length of the envelope, and so the offset within
 	// the blob at which the detached ciphertext begins.
 	HeaderLen int64
@@ -53,7 +53,7 @@ type BodyMaterial struct {
 	// protected header because the Enc_structure's context string differs
 	// between a COSE_Encrypt and a recipient-less COSE_Encrypt0, a distinction
 	// this value has no other way to record. Caching the finished bytes keeps
-	// BodyMaterial identical for both envelope forms. The protected header
+	// BodyDescriptor identical for both envelope forms. The protected header
 	// remains recoverable from it: it is the structure's second element.
 	AAD []byte
 }
@@ -63,22 +63,22 @@ type BodyMaterial struct {
 // material — a partially populated record would produce a row that no later
 // range read could use.
 //
-// [DecryptRangeWithMaterial] calls it, so a bad value fails there with
-// [ErrIncompleteMaterial] rather than as an authentication error further down.
-func (m BodyMaterial) Validate() error {
+// [DecryptRangeWithDescriptor] calls it, so a bad value fails there with
+// [ErrIncompleteDescriptor] rather than as an authentication error further down.
+func (m BodyDescriptor) Validate() error {
 	if m.HeaderLen <= 0 {
-		return fmt.Errorf("%w: header length %d is not positive", ErrIncompleteMaterial, m.HeaderLen)
+		return fmt.Errorf("%w: header length %d is not positive", ErrIncompleteDescriptor, m.HeaderLen)
 	}
 	if len(m.BaseNonce) != aesstream.BaseNonceSize {
 		return fmt.Errorf("%w: base nonce is %d bytes, want %d",
-			ErrIncompleteMaterial, len(m.BaseNonce), aesstream.BaseNonceSize)
+			ErrIncompleteDescriptor, len(m.BaseNonce), aesstream.BaseNonceSize)
 	}
 	if m.ChunkSize < aesstream.MinChunkSize || m.ChunkSize > aesstream.MaxChunkSize {
 		return fmt.Errorf("%w: chunk size %d out of range [%d, %d]",
-			ErrIncompleteMaterial, m.ChunkSize, aesstream.MinChunkSize, aesstream.MaxChunkSize)
+			ErrIncompleteDescriptor, m.ChunkSize, aesstream.MinChunkSize, aesstream.MaxChunkSize)
 	}
 	if len(m.AAD) == 0 {
-		return fmt.Errorf("%w: missing AAD", ErrIncompleteMaterial)
+		return fmt.Errorf("%w: missing AAD", ErrIncompleteDescriptor)
 	}
 	return nil
 }
@@ -89,10 +89,10 @@ func (m BodyMaterial) Validate() error {
 // suffix range ("bytes=-N" is off = size-N) from cached metadata alone.
 //
 // blobSize is the whole stored object, envelope included, exactly as passed to
-// [DecryptRangeWithMaterial]. It reports [ErrIncompleteMaterial] for an unusable
+// [DecryptRangeWithDescriptor]. It reports [ErrIncompleteDescriptor] for an unusable
 // m, and [aesstream.ErrCiphertextSize] if blobSize cannot describe a FEE blob at
 // this header length and chunk size.
-func (m BodyMaterial) PlaintextSize(blobSize int64) (int64, error) {
+func (m BodyDescriptor) PlaintextSize(blobSize int64) (int64, error) {
 	if err := m.Validate(); err != nil {
 		return 0, err
 	}
@@ -103,7 +103,7 @@ func (m BodyMaterial) PlaintextSize(blobSize int64) (int64, error) {
 // whose envelope occupies headerLen bytes and whose STREAM chunks carry chunkSize
 // plaintext bytes each.
 //
-// It is shared by [BodyMaterial.PlaintextSize] and the envelope-backed paths (via
+// It is shared by [BodyDescriptor.PlaintextSize] and the envelope-backed paths (via
 // envelopePlaintextSize), so a blob size that cannot describe a FEE body is reported
 // the same way whether the parameters came from a cache or from the envelope.
 func plaintextSizeFrom(blobSize, headerLen int64, chunkSize int) (int64, error) {
@@ -122,14 +122,14 @@ func plaintextSizeFrom(blobSize, headerLen int64, chunkSize int) (int64, error)
 // body returns the envelope body parameters m describes, for the range wiring it
 // shares with the envelope-backed paths. HeaderLen is not among them: it says
 // where the ciphertext starts, not how to decrypt it.
-func (m BodyMaterial) body() bodyParams {
+func (m BodyDescriptor) body() bodyParams {
 	return bodyParams{baseNonce: m.BaseNonce, chunkSize: m.ChunkSize, aad: m.AAD}
 }
 
-// clone returns a deep copy, so a BodyMaterial handed to a caller shares no
+// clone returns a deep copy, so a BodyDescriptor handed to a caller shares no
 // backing array with the envelope it came from (and one handed back to us cannot
 // be mutated underneath a live reader).
-func (m BodyMaterial) clone() BodyMaterial {
+func (m BodyDescriptor) clone() BodyDescriptor {
 	m.BaseNonce = bytes.Clone(m.BaseNonce)
 	m.AAD = bytes.Clone(m.AAD)
 	return m