# validator

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->

## Purpose

Declares the `ChunkValidator` strategy interface and provides the
`NoopChunkValidator` default. Validation is the second stage of the
chunk pipeline (between ingestion and decryption). The strategy
interface lets callers plug in any verification primitive — Ed25519
signature checks, HMAC tags, custom integrity schemes — without the
core queue needing to know the cryptographic details.

## Features

- `ChunkValidator` interface with a single async `validate` method.
- `NoopChunkValidator` default that passes every chunk through
  unchanged.
- `noopChunkValidator` singleton shorthand for callers that don't want
  to instantiate.
- Adapters live in sibling modules (`chunk-verifier-validator.ts`).

## Usage: Basic

```ts
import { noopChunkValidator } from "@suaveplan/streams-chunk-queue";

const queue = new StreamingChunkQueue({
    fileId: 1n,
    totalChunks: 5n,
    validator: noopChunkValidator,
});
```

## Usage: Advanced

```ts
import type { ChunkValidator } from "@suaveplan/streams-chunk-queue";

class HmacValidator implements ChunkValidator {
    constructor(private readonly key: Uint8Array) {}
    async validate(chunkId: bigint, data: Uint8Array) {
        const tagLen = 32;
        const tag = data.slice(0, tagLen);
        const body = data.slice(tagLen);
        if (!(await hmacVerify(this.key, body, tag))) {
            throw new Error(`HMAC failed for chunk ${chunkId}`);
        }
        return { data: body };
    }
}
```

## API Reference

### `ChunkValidator`

```ts
interface ChunkValidator {
    validate(chunkId: bigint, data: Uint8Array): Promise<ValidationOutcome>;
}
```

Implementations MUST throw on failure. The thrown error is wrapped by
the queue into `StreamsChunkQueueError(VALIDATION_FAILED)`.

### `ValidationOutcome`

`{ data: Uint8Array }`. The returned bytes supersede the inline
ciphertext — useful when validation strips a header or signature.

### `NoopChunkValidator`

Concrete class implementing `ChunkValidator` as a pass-through.

### `noopChunkValidator`

Singleton instance of `NoopChunkValidator`.

## Implementation Notes

The interface is async even for synchronous validators because all
real-world validators end up wanting WebCrypto / native crypto, which
is async. Forcing the contract to be uniformly async means the queue
can `await` without per-implementation branches. The `data` return
value is intentionally writable — adapters may strip a signature
header before passing bytes downstream, so the queue stores the
adapter-returned bytes (not the original wire frame) in its in-memory
map. A noop validator is included so the queue can call
`validator.validate` unconditionally without checking for a
configured strategy.