# 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.