# @filoz/filecoin-encryption-envelope

Filecoin Encryption Envelope (FIP-1253).

## Classes

| Class | Description |
| ------ | ------ |
| [ChunkCountExceededError](/reference/filoz/filecoin-encryption-envelope/classes/chunkcountexceedederror/) | The derived or declared chunk count exceeds `MAX_CHUNK_COUNT`. |
| [EnvelopeError](/reference/filoz/filecoin-encryption-envelope/classes/envelopeerror/) | Base class for every error raised by this package. |
| [InvalidChunkSizeError](/reference/filoz/filecoin-encryption-envelope/classes/invalidchunksizeerror/) | `chunkSize` is not an integer within `[MIN_CHUNK_SIZE, MAX_CHUNK_SIZE]`. |
| [InvalidCiphertextSizeError](/reference/filoz/filecoin-encryption-envelope/classes/invalidciphertextsizeerror/) | `ciphertextSize` is not a valid ciphertext length for the given chunk size — negative, not a safe integer, or too short to hold a final chunk's authentication tag. |
| [InvalidNonceError](/reference/filoz/filecoin-encryption-envelope/classes/invalidnonceerror/) | A base nonce or chunk index is not valid for per-chunk nonce derivation. |

## Interfaces

| Interface | Description |
| ------ | ------ |
| [ChunkLayout](/reference/filoz/filecoin-encryption-envelope/interfaces/chunklayout/) | - |

## Variables

| Variable | Description |
| ------ | ------ |
| [ALG\_A256KW](/reference/filoz/filecoin-encryption-envelope/variables/alg_a256kw/) | AES key wrap, RFC 9053 §6.2.1. |
| [ALG\_AES\_256\_GCM](/reference/filoz/filecoin-encryption-envelope/variables/alg_aes_256_gcm/) | Whole-object AES-256-GCM, one AEAD operation over the entire plaintext. Not seekable. |
| [ALG\_CHUNKED\_AES\_256\_GCM\_STREAM](/reference/filoz/filecoin-encryption-envelope/variables/alg_chunked_aes_256_gcm_stream/) | Chunked AES-256-GCM with STREAM (per-chunk nonce, positional AAD binding). Seekable. |
| [ALG\_ECDH\_ES\_A256KW](/reference/filoz/filecoin-encryption-envelope/variables/alg_ecdh_es_a256kw/) | ECDH-ES + AES key wrap, HKDF-SHA-256, RFC 9053 §6.3.1. |
| [BASE\_NONCE\_SIZE](/reference/filoz/filecoin-encryption-envelope/variables/base_nonce_size/) | Random, per-object portion of the chunked scheme's nonce. |
| [DEFAULT\_CHUNK\_SIZE](/reference/filoz/filecoin-encryption-envelope/variables/default_chunk_size/) | Default chunk size when the caller does not specify one. |
| [ENVELOPE\_TYPE](/reference/filoz/filecoin-encryption-envelope/variables/envelope_type/) | `typ` header value identifying this envelope format. |
| [HEADER\_ALG](/reference/filoz/filecoin-encryption-envelope/variables/header_alg/) | `alg`, RFC 9052 §3.1. Selects the encryption scheme, see the ALG_* constants. |
| [HEADER\_APP\_METADATA](/reference/filoz/filecoin-encryption-envelope/variables/header_app_metadata/) | `app_metadata`, private use. Opaque, string-keyed map carried and authenticated but never interpreted. |
| [HEADER\_CHUNK\_COUNT](/reference/filoz/filecoin-encryption-envelope/variables/header_chunk_count/) | `chunk_count`, private use (RFC 9052 §3.1). Present only when the content length was known at encryption time. See docs/tech-spec.md, "chunk_count and truncation" — this label lives in the *protected* header so an attacker cannot edit it to mask a truncated object without failing every chunk's AEAD tag. |
| [HEADER\_CHUNK\_SIZE](/reference/filoz/filecoin-encryption-envelope/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](/reference/filoz/filecoin-encryption-envelope/variables/alg_aes_256_gcm/) (3) — whole-object AEAD has no chunk layout. |
| [HEADER\_CONTENT\_TYPE](/reference/filoz/filecoin-encryption-envelope/variables/header_content_type/) | `content_type`, RFC 9052 §3.1. Media type of the plaintext. Optional. |
| [HEADER\_IV](/reference/filoz/filecoin-encryption-envelope/variables/header_iv/) | `iv`, RFC 9052 §3.1. Unprotected: 12-byte nonce (scheme 1) or 7-byte base nonce (chunked). |
| [HEADER\_KID](/reference/filoz/filecoin-encryption-envelope/variables/header_kid/) | `kid`, RFC 9052 §3.1. Not used at the top level in this profile; kept for recipients. |
| [HEADER\_TYP](/reference/filoz/filecoin-encryption-envelope/variables/header_typ/) | `typ`, RFC 9052 §3.1. Must equal [ENVELOPE\_TYPE](/reference/filoz/filecoin-encryption-envelope/variables/envelope_type/). |
| [KEY\_SIZE](/reference/filoz/filecoin-encryption-envelope/variables/key_size/) | Content encryption key size (AES-256). |
| [MAX\_CHUNK\_COUNT](/reference/filoz/filecoin-encryption-envelope/variables/max_chunk_count/) | Largest permitted chunk count. |
| [MAX\_CHUNK\_SIZE](/reference/filoz/filecoin-encryption-envelope/variables/max_chunk_size/) | Largest permitted chunk size. |
| [MIN\_CHUNK\_SIZE](/reference/filoz/filecoin-encryption-envelope/variables/min_chunk_size/) | Smallest permitted chunk size. |
| [NONCE\_SIZE](/reference/filoz/filecoin-encryption-envelope/variables/nonce_size/) | Full AEAD nonce size (GCM standard). |
| [TAG\_ENCRYPT](/reference/filoz/filecoin-encryption-envelope/variables/tag_encrypt/) | `COSE_Encrypt`, RFC 9052 §5.1. Carries a recipients array for key wrapping. |
| [TAG\_ENCRYPT0](/reference/filoz/filecoin-encryption-envelope/variables/tag_encrypt0/) | `COSE_Encrypt0`, RFC 9052 §5.2. No recipients array; used when the CEK is out of band. |
| [TAG\_SIZE](/reference/filoz/filecoin-encryption-envelope/variables/tag_size/) | GCM authentication tag size. |

## Functions

| Function | Description |
| ------ | ------ |
| [chunkCountForPlaintext](/reference/filoz/filecoin-encryption-envelope/functions/chunkcountforplaintext/) | Chunk count an *encoder* writes into the `chunk_count` header for a plaintext of the given length. This is deliberately not the inverse of [chunkLayout](/reference/filoz/filecoin-encryption-envelope/functions/chunklayout/): a plaintext that is an exact multiple of the chunk size can be sealed validly as either `k` chunks (last one full) or `k+1` (last one empty, carrying only its tag), and both decrypt to identical bytes. We always WRITE the `k` form here, but a decoder must ACCEPT both — so the header this function produces is checked against `chunkLayout(ciphertextSize, chunkSize).chunkCount`, never against `chunkCountForPlaintext` run in reverse on the plaintext size. |
| [chunkLayout](/reference/filoz/filecoin-encryption-envelope/functions/chunklayout/) | Derive the chunk layout of a stored blob from its ciphertext size and chunk size — never the reverse. A declared `chunk_count` header must be checked against `chunkLayout(...).chunkCount`, not the other way around, or a truncated object would go undetected (docs/tech-spec.md, "Three rules make the check correct"). |
| [deriveChunkNonce](/reference/filoz/filecoin-encryption-envelope/functions/derivechunknonce/) | Derive the 12-byte AEAD nonce for one chunk: `baseNonce (7) ‖ chunkIndex (4, big-endian) ‖ last_flag (1)`. |