header

Purpose

Encodes and parses the 100-byte metadata portion of a v1 chunk on its own (without sig or ciphertext). Every chunk on the wire begins with this exact byte layout; receivers parse the header first, validate structural invariants, and only then proceed to signature verification and AEAD decryption. The parser enforces every PACKER-CHUNK-* requirement that can be checked from the header alone — version pin, reserved-flags zero, payloadLen non-final/final invariants, in-range chunkId, sane chunkSize.

Features

encodeHeader(meta) writes a fresh 100-byte big-endian buffer at the locked field offsets.
parseHeader(buf) reads the first 100 bytes and validates structural invariants.
Returns metadata fields as zero-copy Uint8Array.subarray views into the input buffer.
Throws PackerError with stable codes on every failure mode (INVALID_FORMAT, VERSION_UNSUPPORTED, FLAGS_RESERVED_NONZERO, PAYLOAD_LEN_INVALID).

Usage: Basic Example

import { encodeHeader, parseHeader, CHUNK_VERSION_V1 } from "@suaveplan/packer/chunked";

const meta = {
    version: CHUNK_VERSION_V1,
    fileId: new Uint8Array(32),
    chunkId: 0,
    totalChunks: 4,
    fileSize: 4_000_000n,
    chunkSize: 1_048_576,
    payloadLen: 1_048_576 - 164,
    flags: 0,
    nonce: new Uint8Array(24),
    aeadTag: new Uint8Array(16),
};
const bytes = encodeHeader(meta);
const round = parseHeader(bytes);

Usage: Advanced Example

import { parseHeader, PackerError, PACKER_CODES } from "@suaveplan/packer/chunked";

function safeParse(buf: Uint8Array) {
    try { return { ok: true as const, meta: parseHeader(buf) }; }
    catch (err) {
        if (err instanceof PackerError) return { ok: false as const, code: err.code };
        throw err;
    }
}

// Reject v2 chunks early without engaging the verify path:
const result = safeParse(receivedBytes);
if (!result.ok && result.code === PACKER_CODES.VERSION_UNSUPPORTED) {
    metrics.versionRejects.inc();
}

API Reference

encodeHeader(meta: ChunkV1Metadata): Uint8Array — writes 100 bytes at locked offsets. Throws PackerError(PACKER.INVALID_FORMAT) on fileId.byteLength !== 32, nonce.byteLength !== 24, or aeadTag.byteLength !== 16.
parseHeader(buf: Uint8Array): ChunkV1Metadata — validates length >= 100, version === 0x0001, flags === 0x0000, totalChunks >= 1, chunkId < totalChunks, chunkSize > 164, and the non-final / final payloadLen invariants. Returns metadata; field byte ranges are zero-copy subarrays of buf.

Implementation Notes

DataView is used for all multi-byte numeric reads/writes with littleEndian: false to enforce big-endian wire format. Uint8Array.subarray (not slice) is used for byte-range fields so the parser is zero-allocation in the happy path. The payloadLen invariant uses BigInt arithmetic for the final-chunk derivation because fileSize is u64 and may exceed Number.MAX_SAFE_INTEGER. The non-final case stays in number arithmetic (chunkSize is u32).

3.0 KiB Raw Blame History