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	Plain-object form of CborValue. Defined as an interface because TypeScript does not allow this recursive type through Record<string, CborValue>.
DecodedEnvelope	-
DecodedProtectedHeader	A decoded protected header with its original encoded bytes. Use bytes verbatim when building the Enc_structure.
DecodedRecipient	A decoded COSE_recipient. No key unwrapping happens at this layer.
EncodeEnvelopeInput	-
ProtectedHeaderFields	Logical protected-header fields, independent of their CBOR encoding.
RecipientInput	Input for one COSE_recipient. This layer shapes it; it never wraps a key.

Type Aliases

Type Alias	Description
Alg	One of the two content-encryption schemes supported by this package.
CborValue	CBOR values supported by this profile.
EnvelopeTag	Which of the two COSE containers this is — and so which context string the AAD carries.
UnprotectedHeaderMap	Content unprotected header map.

Variables

Variable	Description
ALG_A256KW	AES key wrap, RFC 9053 §6.2.1. The only wrap this version supports.
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	typ header value identifying this envelope format.
HEADER_ALG	alg, RFC 9052 §3.1. Selects the encryption scheme, see the ALG_* constants.
HEADER_APP_METADATA	app_metadata, private use. Opaque, string-keyed map carried and authenticated but never interpreted.
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	content_type, RFC 9052 §3.1. Media type of the plaintext. Optional.
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	iv, RFC 9052 §3.1: a 12-byte nonce (scheme 1) or a 7-byte base nonce (chunked).
HEADER_KID	kid, RFC 9052 §3.1. Recipients only; a byte string. Never a content header in this profile.
HEADER_PARTIAL_IV	Partial IV, RFC 9052 §3.1. Forbidden in both content buckets.
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	typ, RFC 9052 §3.1. Must equal ENVELOPE_TYPE.
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	Ceiling on the encoded envelope alone, not the detached ciphertext after it.
TAG_ENCRYPT	COSE_Encrypt, RFC 9052 §5.1. Carries a recipients array for key wrapping.
TAG_ENCRYPT0	COSE_Encrypt0, RFC 9052 §5.2. No recipients array; used when the CEK is out of band.

Functions

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