first commit

docs/networking/drive/drive-plugin-chunks/src/pipeline/verify-chunk.md

@@ -0,0 +1,52 @@
+# verify-chunk
+
+## Purpose
+
+Verifies a chunk's Ed25519 signature against the server's public key as the gate that runs on receipt of every chunk — before persistence, before decryption, before reassembly. A mismatched or corrupted signature surfaces as `ChunksError(CHUNKS.SIG_INVALID)` so callers can drop bad chunks without ever exposing them to the rest of the pipeline.
+
+## Features
+
+- `verifyChunkSig(raw, pubKey): void` — reads the embedded signature out of the raw bytes, recomputes the signed payload, and verifies in constant-time via `@noble/curves/ed25519`.
+- Single-pass — runs over the original raw buffer without re-encoding.
+- Throws on failure rather than returning `false`, matching the rest of the pipeline's error contract.
+
+## Usage: Basic Example
+
+```ts
+import { verifyChunkSig } from "@suaveplan/drive-plugin-chunks";
+
+verifyChunkSig(rawChunk, serverPubKey);
+// throws ChunksError(CHUNKS.SIG_INVALID) on mismatch
+```
+
+## Usage: Advanced Example
+
+```ts
+import {
+    CHUNKS_CODES,
+    ChunksError,
+    parseChunk,
+    verifyChunkSig,
+} from "@suaveplan/drive-plugin-chunks";
+
+async function ingestPeerChunk(raw: Uint8Array) {
+    try {
+        verifyChunkSig(raw, expectedServerPub);
+    } catch (err) {
+        if (err instanceof ChunksError && err.code === CHUNKS_CODES.SIG_INVALID) {
+            return reportPeerCorruption(raw);
+        }
+        throw err;
+    }
+    const parsed = parseChunk(raw);
+    return persist(parsed);
+}
+```
+
+## API Reference
+
+- `verifyChunkSig(raw: Uint8Array, pubKey: Uint8Array): void` — validates that `raw` carries a correct signature for its embedded metadata + ciphertext under `pubKey`. Throws `ChunksError(CHUNKS.SIG_INVALID)` on any failure (including under-length buffers, since `parseHeader` runs first).
+
+## Implementation Notes
+
+The function rebuilds the signed payload as `metadata || ciphertext` rather than treating the raw bytes as already-signed because the signature occupies a fixed offset between metadata and ciphertext — re-encoding metadata after parsing keeps verification independent of any future header padding changes. suaveplan pins to `@noble/curves` for both signing and verification, which is constant-time and audited.