@filoz/filecoin-encryption-envelope

Filecoin Encryption Envelope (FIP-1253).

Classes

Class	Description
ChunkCountExceededError	The derived or declared chunk count exceeds MAX_CHUNK_COUNT.
EnvelopeError	Base class for every error raised by this package.
InvalidChunkSizeError	chunkSize is not an integer within [MIN_CHUNK_SIZE, MAX_CHUNK_SIZE].
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	A base nonce or chunk index is not valid for per-chunk nonce derivation.

Interfaces

Interface	Description
ChunkLayout	-

Variables

Variable	Description
ALG_A256KW	AES key wrap, RFC 9053 §6.2.1.
ALG_AES_256_GCM	Whole-object AES-256-GCM, one AEAD operation over the entire plaintext. Not seekable.
ALG_CHUNKED_AES_256_GCM_STREAM	Chunked AES-256-GCM with STREAM (per-chunk nonce, positional AAD binding). Seekable.
ALG_ECDH_ES_A256KW	ECDH-ES + AES key wrap, HKDF-SHA-256, RFC 9053 §6.3.1.
BASE_NONCE_SIZE	Random, per-object portion of the chunked scheme’s nonce.
DEFAULT_CHUNK_SIZE	Default chunk size when the caller does not specify one.
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_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	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_IV	iv, RFC 9052 §3.1. Unprotected: 12-byte nonce (scheme 1) or 7-byte base nonce (chunked).
HEADER_KID	kid, RFC 9052 §3.1. Not used at the top level in this profile; kept for recipients.
HEADER_TYP	typ, RFC 9052 §3.1. Must equal ENVELOPE_TYPE.
KEY_SIZE	Content encryption key size (AES-256).
MAX_CHUNK_COUNT	Largest permitted chunk count.
MAX_CHUNK_SIZE	Largest permitted chunk size.
MIN_CHUNK_SIZE	Smallest permitted chunk size.
NONCE_SIZE	Full AEAD nonce size (GCM standard).
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.
TAG_SIZE	GCM authentication tag size.

Functions

Function	Description
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: 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	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	Derive the 12-byte AEAD nonce for one chunk: baseNonce (7) ‖ chunkIndex (4, big-endian) ‖ last_flag (1).