# chunk

## Purpose

Wraps the chunk wire format above the bare header: takes raw chunk bytes (header + signature + ciphertext) and parses them into the structured `Chunk` and `EncodedChunk` shapes that the rest of the plugin consumes. This is the inverse of `encrypt-stream`'s output and the input to `verify-chunk` / `decrypt-chunk`.

## Features

- `parseChunk(raw): Chunk` — splits raw bytes into `metadata`, `sig`, and `ciphertext` slices using `HEADER_SIZE` as the boundary.
- Length validation — rejects anything shorter than `HEADER_SIZE + payloadLen`.
- Allocation-light — uses `Uint8Array.subarray` views where safe and `slice` only where ownership matters.
- Round-trip stable when paired with `encodeHeader` and the encrypt-stream output.

## Usage: Basic Example

```ts
import { parseChunk } from "@suaveplan/drive-plugin-chunks";

const raw: Uint8Array = await chunks.getChunk(fileId, 0).then((b) => b!);
const chunk = parseChunk(raw);
console.log(chunk.metadata.chunkId, chunk.ciphertext.length);
```

## Usage: Advanced Example

```ts
import {
    decryptChunk,
    parseChunk,
    verifyChunkSig,
} from "@suaveplan/drive-plugin-chunks";

async function readVerifiedChunk(fileId: Uint8Array, idx: number) {
    const raw = await chunks.getChunk(fileId, idx);
    if (!raw) throw new Error("missing chunk");
    const chunk = parseChunk(raw);
    verifyChunkSig(raw, serverPubKey);
    const plaintext = decryptChunk(chunk.metadata, chunk.ciphertext, fileKey);
    return plaintext.slice(0, chunk.metadata.payloadLen);
}
```

## API Reference

- `parseChunk(raw: Uint8Array): Chunk` — returns `{ metadata, sig, ciphertext }`. `metadata` flows through `parseHeader`; `sig` is the 64-byte Ed25519 signature slice; `ciphertext` is the trailing `payloadLen` bytes.
- Throws `ChunksError(CHUNKS.METADATA_INVALID)` for under-length buffers (delegated to `parseHeader`).
- Throws `ChunksError(CHUNKS.PAYLOAD_LEN_INVALID)` when the trailing payload is shorter than `metadata.payloadLen`.

## Implementation Notes

`parseChunk` does not verify the signature or decrypt — those are independent stages so peers can short-circuit on metadata-only inspection (manifest checks, availability gossip). The ciphertext is sliced rather than viewed when its length differs from the underlying buffer to avoid pinning the larger raw allocation in caches.