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

validator

(no submodules)

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

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

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

Usage: Advanced

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

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.