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