leviathan-crypto 2.0.1 → 3.0.0

package/dist/blake3/index.d.ts

@@ -0,0 +1,143 @@
+import { isInitialized } from '../init.js';
+import type { WasmSource } from '../wasm-source.js';
+import type { HashFn } from '../types.js';
+import type { Blake3Exports } from './types.js';
+export type { WasmSource };
+export type { Blake3Exports };
+export { isInitialized };
+export declare function blake3Init(source: WasmSource): Promise<void>;
+/**
+ * BLAKE3 default-mode hash (BLAKE3 §2.3 Modes — `hash`).
+ *
+ * One-shot: `hash(msg, outLen?)` runs the full chunk / tree / root
+ * pipeline and returns `outLen` (default 32) bytes of XOF output.
+ * Module exclusivity is acquired and released per call.
+ */
+export declare class BLAKE3 {
+    private readonly x;
+    constructor();
+    hash(msg: Uint8Array, outLen?: number): Uint8Array;
+    dispose(): void;
+}
+/**
+ * BLAKE3 keyed_hash (BLAKE3 §2.3 Modes — `keyed_hash`).
+ *
+ * The 32-byte key seeds the chunk machine in place of the BLAKE3 IV and
+ * every compress carries the KEYED_HASH flag. Use cases include MACs and
+ * keyed-pseudorandom generation; the construction is a PRF when the key
+ * is uniform and secret.
+ */
+export declare class BLAKE3KeyedHash {
+    private readonly x;
+    constructor();
+    hash(key: Uint8Array, msg: Uint8Array, outLen?: number): Uint8Array;
+    dispose(): void;
+}
+/**
+ * BLAKE3 derive_key (BLAKE3 §2.3 Modes — `derive_key`).
+ *
+ * Two-pass KDF: pass 1 hashes the context string with the
+ * DERIVE_KEY_CONTEXT flag, pass 2 hashes the key material with the
+ * DERIVE_KEY_MATERIAL flag using the pass-1 output as its starting CV.
+ * Context strings are conventionally hardcoded UTF-8 application
+ * constants; empty contexts are rejected by `validateContext`.
+ */
+export declare class BLAKE3DeriveKey {
+    private readonly x;
+    constructor();
+    derive(context: string | Uint8Array, material: Uint8Array, outLen?: number): Uint8Array;
+    dispose(): void;
+}
+/**
+ * Streaming BLAKE3 default-mode hash (BLAKE3 §2.3 Modes — `hash`).
+ *
+ * `update()` accepts chunks of any size; `finalize()` returns the
+ * `outLen`-byte (default 32) digest and disposes the instance. Holds
+ * exclusive access to the `blake3` WASM module from construction until
+ * `dispose()` or `finalize()` / `finalizeXof()`.
+ */
+export declare class BLAKE3Stream {
+    private readonly x;
+    private _tok;
+    private readonly _state;
+    constructor();
+    update(chunk: Uint8Array): this;
+    finalize(outLen?: number): Uint8Array;
+    finalizeXof(): BLAKE3OutputReader;
+    dispose(): void;
+    private _checkLive;
+}
+/**
+ * Streaming BLAKE3 keyed_hash (BLAKE3 §2.3 Modes). Key is bound at construction
+ * time. Same lifecycle as `BLAKE3Stream`.
+ */
+export declare class BLAKE3KeyedHashStream {
+    private readonly x;
+    private _tok;
+    private readonly _state;
+    private readonly _key;
+    constructor(key: Uint8Array);
+    update(chunk: Uint8Array): this;
+    finalize(outLen?: number): Uint8Array;
+    finalizeXof(): BLAKE3OutputReader;
+    dispose(): void;
+    private _checkLive;
+}
+/**
+ * Streaming BLAKE3 derive_key (BLAKE3 §2.3 Modes). Context is bound at
+ * construction time; updates stream the material; finalize derives.
+ * Same lifecycle as `BLAKE3Stream`.
+ */
+export declare class BLAKE3DeriveKeyStream {
+    private readonly x;
+    private _tok;
+    private readonly _state;
+    private readonly _ctxBytes;
+    constructor(context: string | Uint8Array);
+    update(chunk: Uint8Array): this;
+    finalize(outLen?: number): Uint8Array;
+    finalizeXof(): BLAKE3OutputReader;
+    dispose(): void;
+    private _checkLive;
+}
+/**
+ * BLAKE3 XOF reader (BLAKE3 §2.6 Extendable Output).
+ *
+ * Sequential `read(nBytes)` calls squeeze the next bytes of XOF output.
+ * Constructed via `finalizeXof()` on a streaming class. Holds module
+ * exclusivity until `dispose()`.
+ *
+ * Implementation: the first `read()` runs the underlying hash entry once
+ * to populate the WASM-side root-compress snapshot (ROOT_STATE_*), then
+ * caches the first 64-byte XOF block. Subsequent reads pump
+ * `squeezeXofBlock` on the WASM module with an incrementing counter to
+ * lift additional 64-byte blocks off the snapshot. The reader's lifetime
+ * coincides with its hold on the module token, so `ROOT_STATE_*` stays
+ * intact between read calls (no other consumer can fire a hash that
+ * would clobber it).
+ */
+export declare class BLAKE3OutputReader {
+    private readonly x;
+    private _tok;
+    private readonly _mode;
+    private readonly _input;
+    private readonly _key;
+    private readonly _ctx;
+    private readonly _blockBuf;
+    private _blockPos;
+    private _nextCounter;
+    private _populated;
+    read(nBytes: number): Uint8Array;
+    dispose(): void;
+    private _populate;
+    private _squeezeNextBlock;
+}
+/**
+ * Stateless BLAKE3-256 HashFn. Shape mirrors `SHA256Hash` in
+ * `src/ts/sha2/hash.ts`: 32-byte output, single WASM module dependency,
+ * `digest(msg)` runs a one-shot hash with default `outLen`.
+ *
+ * Usable as a Fortuna accumulator / reseed hash when paired with a
+ * matching 32-byte-key Generator.
+ */
+export declare const BLAKE3Hash: HashFn;