first commit

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

@@ -0,0 +1,51 @@
+# 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.