first commit

docs/foundation/flow/streams-chunk-queue/src/validator/validator.md

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