# cose

COSE wire-format layer (FIP-1253): typed structures ↔ bytes for the
envelope's protected/unprotected headers, `Enc_structure` (AAD), and the
tagged CBOR envelope itself. See docs/tech-spec.md, "Wire profile" and
"CDDL". No AEAD, no key wrap, no chunk framing — those live above this.

## Interfaces

| Interface | Description |
| ------ | ------ |
| [CborValueObject](/reference/filoz/filecoin-encryption-envelope/namespaces/cose/interfaces/cborvalueobject/) | Plain-object form of [CborValue](/reference/filoz/filecoin-encryption-envelope/namespaces/cose/type-aliases/cborvalue/). Defined as an interface because TypeScript does not allow this recursive type through `Record<string, CborValue>`. |
| [DecodedEnvelope](/reference/filoz/filecoin-encryption-envelope/namespaces/cose/interfaces/decodedenvelope/) | - |
| [DecodedProtectedHeader](/reference/filoz/filecoin-encryption-envelope/namespaces/cose/interfaces/decodedprotectedheader/) | A decoded protected header with its original encoded bytes. Use `bytes` verbatim when building the Enc_structure. |
| [DecodedRecipient](/reference/filoz/filecoin-encryption-envelope/namespaces/cose/interfaces/decodedrecipient/) | A decoded `COSE_recipient`. No key unwrapping happens at this layer. |
| [EncodeEnvelopeInput](/reference/filoz/filecoin-encryption-envelope/namespaces/cose/interfaces/encodeenvelopeinput/) | - |
| [ProtectedHeaderFields](/reference/filoz/filecoin-encryption-envelope/namespaces/cose/interfaces/protectedheaderfields/) | Logical protected-header fields, independent of their CBOR encoding. |
| [RecipientInput](/reference/filoz/filecoin-encryption-envelope/namespaces/cose/interfaces/recipientinput/) | Input for one `COSE_recipient`. This layer shapes it; it never wraps a key. |

## Type Aliases

| Type Alias | Description |
| ------ | ------ |
| [Alg](/reference/filoz/filecoin-encryption-envelope/namespaces/cose/type-aliases/alg/) | One of the two content-encryption schemes supported by this package. |
| [CborValue](/reference/filoz/filecoin-encryption-envelope/namespaces/cose/type-aliases/cborvalue/) | CBOR values supported by this profile. |
| [EnvelopeTag](/reference/filoz/filecoin-encryption-envelope/namespaces/cose/type-aliases/envelopetag/) | Which of the two COSE containers this is — and so which context string the AAD carries. |
| [UnprotectedHeaderMap](/reference/filoz/filecoin-encryption-envelope/namespaces/cose/type-aliases/unprotectedheadermap/) | Content unprotected header map. |

## Variables

| Variable | Description |
| ------ | ------ |
| [ALG\_A256KW](/reference/filoz/filecoin-encryption-envelope/namespaces/cose/variables/alg_a256kw/) | AES key wrap, RFC 9053 §6.2.1. The only wrap this version supports. |
| [ALG\_ECDH\_ES\_A256KW](/reference/filoz/filecoin-encryption-envelope/namespaces/cose/variables/alg_ecdh_es_a256kw/) | ECDH-ES + AES key wrap. Deferred — defined here so recipients using it can be recognised and skipped, not unwrapped. |
| [ENVELOPE\_TYPE](/reference/filoz/filecoin-encryption-envelope/namespaces/cose/variables/envelope_type/) | `typ` header value identifying this envelope format. |
| [HEADER\_ALG](/reference/filoz/filecoin-encryption-envelope/namespaces/cose/variables/header_alg/) | `alg`, RFC 9052 §3.1. Selects the encryption scheme, see the ALG_* constants. |
| [HEADER\_APP\_METADATA](/reference/filoz/filecoin-encryption-envelope/namespaces/cose/variables/header_app_metadata/) | `app_metadata`, private use. Opaque, string-keyed map carried and authenticated but never interpreted. |
| [HEADER\_CHUNK\_SIZE](/reference/filoz/filecoin-encryption-envelope/namespaces/cose/variables/header_chunk_size/) | `chunk_size`, algorithm-specific label per RFC 9052 §3.1. Required for the chunked scheme, must not appear when `alg` is ALG\_AES\_256\_GCM (3) — whole-object AEAD has no chunk layout. |
| [HEADER\_CONTENT\_TYPE](/reference/filoz/filecoin-encryption-envelope/namespaces/cose/variables/header_content_type/) | `content_type`, RFC 9052 §3.1. Media type of the plaintext. Optional. |
| [HEADER\_CRIT](/reference/filoz/filecoin-encryption-envelope/namespaces/cose/variables/header_crit/) | `crit`, RFC 9052 §3.1. Names header labels a processor must understand and act on. For the acceptance rule see CriticalHeaderError. |
| [HEADER\_IV](/reference/filoz/filecoin-encryption-envelope/namespaces/cose/variables/header_iv/) | `iv`, RFC 9052 §3.1: a 12-byte nonce (scheme 1) or a 7-byte base nonce (chunked). |
| [HEADER\_KID](/reference/filoz/filecoin-encryption-envelope/namespaces/cose/variables/header_kid/) | `kid`, RFC 9052 §3.1. Recipients only; a byte string. Never a content header in this profile. |
| [HEADER\_PARTIAL\_IV](/reference/filoz/filecoin-encryption-envelope/namespaces/cose/variables/header_partial_iv/) | `Partial IV`, RFC 9052 §3.1. Forbidden in both content buckets. |
| [HEADER\_PLAINTEXT\_LENGTH](/reference/filoz/filecoin-encryption-envelope/namespaces/cose/variables/header_plaintext_length/) | `plaintext_length`, private use (RFC 9052 §3.1). Optional; written only when the caller knew the content length before the envelope was emitted. |
| [HEADER\_TYP](/reference/filoz/filecoin-encryption-envelope/namespaces/cose/variables/header_typ/) | `typ`, RFC 9052 §3.1. Must equal [ENVELOPE\_TYPE](/reference/filoz/filecoin-encryption-envelope/namespaces/cose/variables/envelope_type/). |
| [MAX\_APP\_METADATA\_DEPTH](/reference/filoz/filecoin-encryption-envelope/namespaces/cose/variables/max_app_metadata_depth/) | How deep the allowlist walk in `headers.ts` will descend into an `app_metadata` value or a recipient's unprotected map, on encode and decode alike. |
| [MAX\_ENVELOPE\_SIZE](/reference/filoz/filecoin-encryption-envelope/namespaces/cose/variables/max_envelope_size/) | Ceiling on the encoded envelope alone, not the detached ciphertext after it. |
| [TAG\_ENCRYPT](/reference/filoz/filecoin-encryption-envelope/namespaces/cose/variables/tag_encrypt/) | `COSE_Encrypt`, RFC 9052 §5.1. Carries a recipients array for key wrapping. |
| [TAG\_ENCRYPT0](/reference/filoz/filecoin-encryption-envelope/namespaces/cose/variables/tag_encrypt0/) | `COSE_Encrypt0`, RFC 9052 §5.2. No recipients array; used when the CEK is out of band. |

## Functions

| Function | Description |
| ------ | ------ |
| [assertValidRecipientHeaders](/reference/filoz/filecoin-encryption-envelope/namespaces/cose/functions/assertvalidrecipientheaders/) | Validate the protected and unprotected headers of a `COSE_recipient` without unwrapping its key. |
| [decodeEnvelope](/reference/filoz/filecoin-encryption-envelope/namespaces/cose/functions/decodeenvelope/) | Decode the envelope at the start of `data`. Bytes after `envelopeLength` are untouched detached ciphertext. |
| [decodeProtectedHeader](/reference/filoz/filecoin-encryption-envelope/namespaces/cose/functions/decodeprotectedheader/) | Decode a protected header from its exact wire bytes and preserve those bytes in [DecodedProtectedHeader](/reference/filoz/filecoin-encryption-envelope/namespaces/cose/interfaces/decodedprotectedheader/). |
| [decodeUnprotectedHeader](/reference/filoz/filecoin-encryption-envelope/namespaces/cose/functions/decodeunprotectedheader/) | Validate and return the content unprotected header. |
| [describeCborType](/reference/filoz/filecoin-encryption-envelope/namespaces/cose/functions/describecbortype/) | Return a human-readable type name for validation errors. |
| [encodeEnvelope](/reference/filoz/filecoin-encryption-envelope/namespaces/cose/functions/encodeenvelope/) | Encode an envelope with detached ciphertext. The caller appends the ciphertext separately. See docs/tech-spec.md, "Blob layout". |
| [encodeProtectedHeader](/reference/filoz/filecoin-encryption-envelope/namespaces/cose/functions/encodeprotectedheader/) | Encode the protected header as a deterministically encoded CBOR map. |
| [encodeUnprotectedHeader](/reference/filoz/filecoin-encryption-envelope/namespaces/cose/functions/encodeunprotectedheader/) | Build the content unprotected header. This profile defines no unprotected content parameters, so the encoder always emits a new empty map. |
| [encStructure](/reference/filoz/filecoin-encryption-envelope/namespaces/cose/functions/encstructure/) | Build the `Enc_structure` bytes for an envelope: `[context, protected, external_aad]`, with `external_aad` always empty. |
| [ivLengthForAlg](/reference/filoz/filecoin-encryption-envelope/namespaces/cose/functions/ivlengthforalg/) | The IV length this profile requires for `alg`: 12 bytes (scheme 1) or 7 bytes (chunked base nonce). |