header

Purpose

Encodes and parses the fixed-width 100-byte metadata header that prefixes every chunk in the @suaveplan/drive-plugin-chunks wire format. Big-endian throughout, no trailing version bytes, layout pinned by constants so receivers can locate each field without consulting the manifest.

Features

encodeHeader(metadata): Uint8Array — packs ChunkMetadata into a 100-byte buffer using big-endian byte order.
parseHeader(buf): ChunkMetadata — reverses the encoding and rejects under-length buffers with CHUNKS.METADATA_INVALID.
METADATA_SIZE (100) — header length excluding signature.
SIG_SIZE (64) — signature length.
HEADER_SIZE (164) — METADATA_SIZE + SIG_SIZE, used by encrypt-stream and the layout helpers.

Usage: Basic Example

import { encodeHeader, parseHeader } from "@suaveplan/drive-plugin-chunks";

const metadata = {
    version: 1, fileId: new Uint8Array(32), chunkId: 0, totalChunks: 1,
    fileSize: 8n, chunkSize: 1024, payloadLen: 8, flags: 0,
    nonce: new Uint8Array(24), aeadTag: new Uint8Array(16),
};
const header = encodeHeader(metadata);
const back = parseHeader(header);

Usage: Advanced Example

import { HEADER_SIZE, METADATA_SIZE, SIG_SIZE, parseHeader } from "@suaveplan/drive-plugin-chunks";

function decodeChunk(raw: Uint8Array) {
    const metadata = parseHeader(raw.subarray(0, METADATA_SIZE));
    const sig = raw.subarray(METADATA_SIZE, HEADER_SIZE);
    const ciphertext = raw.subarray(HEADER_SIZE, HEADER_SIZE + metadata.payloadLen);
    return { metadata, sig, ciphertext };
}

API Reference

METADATA_SIZE: 100 — bytes reserved for metadata.
SIG_SIZE: 64 — bytes reserved for the Ed25519 signature.
HEADER_SIZE: 164 — METADATA_SIZE + SIG_SIZE.
encodeHeader(metadata: ChunkMetadata): Uint8Array — returns a freshly-allocated 100-byte buffer.
parseHeader(buf: Uint8Array): ChunkMetadata — throws ChunksError(CHUNKS.METADATA_INVALID) if buf.length < METADATA_SIZE. Slices fileId, nonce, and aeadTag so callers can mutate the input safely.

Implementation Notes

Layout (big-endian):

Offset	Length	Field
0	2	version
2	32	fileId
34	4	chunkId
38	4	totalChunks
42	8	fileSize (u64)
50	4	chunkSize
54	4	payloadLen
58	2	flags
60	24	nonce
84	16	aeadTag

The header pads to exactly 100 bytes so encrypt-stream can compute payload offsets without recomputing field sums.

2.6 KiB Raw Blame History