first commit

docs/networking/drive/drive-plugin-chunks/src/codec/header.md

@@ -0,0 +1,67 @@
+# 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
+
+```ts
+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
+
+```ts
+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.