leviathan-crypto 2.0.1 → 3.0.0

package/dist/sha3/index.js

@@ -22,23 +22,15 @@
 // src/ts/sha3/index.ts
 //
 // Public API classes for the SHA-3 WASM module.
-// Uses the init() module cache — call sha3Init(source) before constructing.
-import { getInstance, initModule } from '../init.js';
+// Uses the init() module cache, call sha3Init(source) before constructing.
+import { getInstance, initModule, _acquireModule, _releaseModule, _assertNotOwned } from '../init.js';
 export async function sha3Init(source) {
     return initModule('sha3', source);
 }
+export { isInitialized } from '../init.js';
 function getExports() {
     return getInstance('sha3').exports;
 }
-export function _sha3Ready() {
-    try {
-        getInstance('sha3');
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
 // Write msg into INPUT_OFFSET in chunks of 168 bytes (max rate)
 function absorb(x, msg) {
     const mem = new Uint8Array(x.memory.buffer);
@@ -58,6 +50,7 @@ export class SHA3_256 {
         this.x = getExports();
     }
     hash(msg) {
+        _assertNotOwned('sha3');
         this.x.sha3_256Init();
         absorb(this.x, msg);
         this.x.sha3_256Final();
@@ -65,6 +58,7 @@ export class SHA3_256 {
         return mem.slice(this.x.getOutOffset(), this.x.getOutOffset() + 32);
     }
     dispose() {
+        _assertNotOwned('sha3');
         this.x.wipeBuffers();
     }
 }
@@ -75,6 +69,7 @@ export class SHA3_512 {
         this.x = getExports();
     }
     hash(msg) {
+        _assertNotOwned('sha3');
         this.x.sha3_512Init();
         absorb(this.x, msg);
         this.x.sha3_512Final();
@@ -82,6 +77,7 @@ export class SHA3_512 {
         return mem.slice(this.x.getOutOffset(), this.x.getOutOffset() + 64);
     }
     dispose() {
+        _assertNotOwned('sha3');
         this.x.wipeBuffers();
     }
 }
@@ -92,6 +88,7 @@ export class SHA3_384 {
         this.x = getExports();
     }
     hash(msg) {
+        _assertNotOwned('sha3');
         this.x.sha3_384Init();
         absorb(this.x, msg);
         this.x.sha3_384Final();
@@ -99,6 +96,7 @@ export class SHA3_384 {
         return mem.slice(this.x.getOutOffset(), this.x.getOutOffset() + 48);
     }
     dispose() {
+        _assertNotOwned('sha3');
         this.x.wipeBuffers();
     }
 }
@@ -109,6 +107,7 @@ export class SHA3_224 {
         this.x = getExports();
     }
     hash(msg) {
+        _assertNotOwned('sha3');
         this.x.sha3_224Init();
         absorb(this.x, msg);
         this.x.sha3_224Final();
@@ -116,22 +115,40 @@ export class SHA3_224 {
         return mem.slice(this.x.getOutOffset(), this.x.getOutOffset() + 28);
     }
     dispose() {
+        _assertNotOwned('sha3');
         this.x.wipeBuffers();
     }
 }
 // ── SHAKE128 ────────────────────────────────────────────────────────────────
-/** SHAKE128 XOF — extendable output, multi-squeeze capable. */
+/**
+ * SHAKE128 XOF, extendable output, multi-squeeze capable.
+ *
+ * Holds exclusive access to the `sha3` WASM module from construction until
+ * `dispose()`. Constructing a second SHAKE128/SHAKE256 or any other sha3
+ * user while this instance is live throws. Call `dispose()` when done.
+ */
 export class SHAKE128 {
     x;
     _rate = 168;
     _squeezing = false;
     _block = new Uint8Array(168);
     _blockPos = 168;
+    _tok;
     constructor() {
         this.x = getExports();
-        this.x.shake128Init();
+        this._tok = _acquireModule('sha3');
+        try {
+            this.x.shake128Init();
+        }
+        catch (e) {
+            _releaseModule('sha3', this._tok);
+            this._tok = undefined;
+            throw e;
+        }
     }
     reset() {
+        if (this._tok === undefined)
+            throw new Error('SHAKE128: instance has been disposed');
         this.x.shake128Init();
         this._squeezing = false;
         this._block.fill(0);
@@ -139,12 +156,16 @@ export class SHAKE128 {
         return this;
     }
     absorb(msg) {
+        if (this._tok === undefined)
+            throw new Error('SHAKE128: instance has been disposed');
         if (this._squeezing)
-            throw new Error('SHAKE128: cannot absorb after squeeze — call reset() first');
+            throw new Error('SHAKE128: cannot absorb after squeeze, call reset() first');
         absorb(this.x, msg);
         return this;
     }
     squeeze(n) {
+        if (this._tok === undefined)
+            throw new Error('SHAKE128: instance has been disposed');
         if (n < 1)
             throw new RangeError(`squeeze length must be >= 1 (got ${n})`);
         if (!this._squeezing) {
@@ -170,6 +191,8 @@ export class SHAKE128 {
         return out;
     }
     hash(msg, outputLength) {
+        if (this._tok === undefined)
+            throw new Error('SHAKE128: instance has been disposed');
         if (outputLength < 1)
             throw new RangeError(`outputLength must be >= 1 (got ${outputLength})`);
         this.reset();
@@ -177,23 +200,48 @@ export class SHAKE128 {
         return this.squeeze(outputLength);
     }
     dispose() {
+        if (this._tok === undefined)
+            return;
         this._block.fill(0);
-        this.x.wipeBuffers();
+        try {
+            this.x.wipeBuffers();
+        }
+        finally {
+            _releaseModule('sha3', this._tok);
+            this._tok = undefined;
+        }
     }
 }
 // ── SHAKE256 ────────────────────────────────────────────────────────────────
-/** SHAKE256 XOF — extendable output, multi-squeeze capable. */
+/**
+ * SHAKE256 XOF, extendable output, multi-squeeze capable.
+ *
+ * Holds exclusive access to the `sha3` WASM module from construction until
+ * `dispose()`. Constructing a second SHAKE128/SHAKE256 or any other sha3
+ * user while this instance is live throws. Call `dispose()` when done.
+ */
 export class SHAKE256 {
     x;
     _rate = 136;
     _squeezing = false;
     _block = new Uint8Array(136);
     _blockPos = 136;
+    _tok;
     constructor() {
         this.x = getExports();
-        this.x.shake256Init();
+        this._tok = _acquireModule('sha3');
+        try {
+            this.x.shake256Init();
+        }
+        catch (e) {
+            _releaseModule('sha3', this._tok);
+            this._tok = undefined;
+            throw e;
+        }
     }
     reset() {
+        if (this._tok === undefined)
+            throw new Error('SHAKE256: instance has been disposed');
         this.x.shake256Init();
         this._squeezing = false;
         this._block.fill(0);
@@ -201,12 +249,16 @@ export class SHAKE256 {
         return this;
     }
     absorb(msg) {
+        if (this._tok === undefined)
+            throw new Error('SHAKE256: instance has been disposed');
         if (this._squeezing)
-            throw new Error('SHAKE256: cannot absorb after squeeze — call reset() first');
+            throw new Error('SHAKE256: cannot absorb after squeeze, call reset() first');
         absorb(this.x, msg);
         return this;
     }
     squeeze(n) {
+        if (this._tok === undefined)
+            throw new Error('SHAKE256: instance has been disposed');
         if (n < 1)
             throw new RangeError(`squeeze length must be >= 1 (got ${n})`);
         if (!this._squeezing) {
@@ -232,6 +284,8 @@ export class SHAKE256 {
         return out;
     }
     hash(msg, outputLength) {
+        if (this._tok === undefined)
+            throw new Error('SHAKE256: instance has been disposed');
         if (outputLength < 1)
             throw new RangeError(`outputLength must be >= 1 (got ${outputLength})`);
         this.reset();
@@ -239,7 +293,251 @@ export class SHAKE256 {
         return this.squeeze(outputLength);
     }
     dispose() {
+        if (this._tok === undefined)
+            return;
         this._block.fill(0);
-        this.x.wipeBuffers();
+        try {
+            this.x.wipeBuffers();
+        }
+        finally {
+            _releaseModule('sha3', this._tok);
+            this._tok = undefined;
+        }
+    }
+}
+// ── SHA3_256Stream ──────────────────────────────────────────────────────────
+/**
+ * Incremental SHA3-256. Construct, `update()` chunks (any size), `finalize()`
+ * to get the 32-byte digest. Finalize disposes the instance.
+ *
+ * Holds exclusive access to the `sha3` WASM module from construction until
+ * `dispose()` or `finalize()`. Mirrors SHAKE128 lifecycle.
+ */
+export class SHA3_256Stream {
+    x;
+    _tok;
+    constructor() {
+        this.x = getExports();
+        this._tok = _acquireModule('sha3');
+        try {
+            this.x.sha3_256Init();
+        }
+        catch (e) {
+            _releaseModule('sha3', this._tok);
+            this._tok = undefined;
+            throw e;
+        }
+    }
+    update(chunk) {
+        if (this._tok === undefined)
+            throw new Error('SHA3_256Stream: instance has been disposed');
+        absorb(this.x, chunk);
+        return this;
+    }
+    finalize() {
+        if (this._tok === undefined)
+            throw new Error('SHA3_256Stream: instance has been disposed');
+        this.x.sha3_256Final();
+        const mem = new Uint8Array(this.x.memory.buffer);
+        const off = this.x.getOutOffset();
+        const out = mem.slice(off, off + 32);
+        this.dispose();
+        return out;
+    }
+    dispose() {
+        if (this._tok === undefined)
+            return;
+        try {
+            this.x.wipeBuffers();
+        }
+        finally {
+            _releaseModule('sha3', this._tok);
+            this._tok = undefined;
+        }
+    }
+}
+// ── SHA3_512Stream ──────────────────────────────────────────────────────────
+/**
+ * Incremental SHA3-512. Construct, `update()` chunks (any size), `finalize()`
+ * to get the 64-byte digest. Finalize disposes the instance.
+ *
+ * Holds exclusive access to the `sha3` WASM module from construction until
+ * `dispose()` or `finalize()`. Mirrors SHAKE128 lifecycle.
+ */
+export class SHA3_512Stream {
+    x;
+    _tok;
+    constructor() {
+        this.x = getExports();
+        this._tok = _acquireModule('sha3');
+        try {
+            this.x.sha3_512Init();
+        }
+        catch (e) {
+            _releaseModule('sha3', this._tok);
+            this._tok = undefined;
+            throw e;
+        }
+    }
+    update(chunk) {
+        if (this._tok === undefined)
+            throw new Error('SHA3_512Stream: instance has been disposed');
+        absorb(this.x, chunk);
+        return this;
+    }
+    finalize() {
+        if (this._tok === undefined)
+            throw new Error('SHA3_512Stream: instance has been disposed');
+        this.x.sha3_512Final();
+        const mem = new Uint8Array(this.x.memory.buffer);
+        const off = this.x.getOutOffset();
+        const out = mem.slice(off, off + 64);
+        this.dispose();
+        return out;
+    }
+    dispose() {
+        if (this._tok === undefined)
+            return;
+        try {
+            this.x.wipeBuffers();
+        }
+        finally {
+            _releaseModule('sha3', this._tok);
+            this._tok = undefined;
+        }
+    }
+}
+// ── SHAKE128Stream ──────────────────────────────────────────────────────────
+/**
+ * Single-shot streaming SHAKE128. `outputLen` is bound at construction;
+ * `update()` absorbs chunks of any size, `finalize()` pads and squeezes
+ * exactly `outputLen` bytes, then disposes the instance.
+ *
+ * Used by `createRunningHash` in the sign layer: each StreamableSignatureSuite
+ * with `prehashAlgorithm: 'shake-128'` declares its `prehashSize` and that
+ * value is passed in here at construction time. The multi-squeeze
+ * `SHAKE128` class above remains for the XOF surface; this class is the
+ * fixed-output cousin that matches the RunningHash contract.
+ *
+ * Holds exclusive access to the `sha3` WASM module from construction until
+ * `dispose()` or `finalize()`. Mirrors `SHA3_256Stream` lifecycle.
+ */
+export class SHAKE128Stream {
+    x;
+    _rate = 168;
+    outputLen;
+    _tok;
+    constructor(outputLen) {
+        if (outputLen < 1)
+            throw new RangeError(`outputLen must be >= 1 (got ${outputLen})`);
+        this.outputLen = outputLen;
+        this.x = getExports();
+        this._tok = _acquireModule('sha3');
+        try {
+            this.x.shake128Init();
+        }
+        catch (e) {
+            _releaseModule('sha3', this._tok);
+            this._tok = undefined;
+            throw e;
+        }
+    }
+    update(chunk) {
+        if (this._tok === undefined)
+            throw new Error('SHAKE128Stream: instance has been disposed');
+        absorb(this.x, chunk);
+        return this;
+    }
+    finalize() {
+        if (this._tok === undefined)
+            throw new Error('SHAKE128Stream: instance has been disposed');
+        this.x.shakePad();
+        const out = new Uint8Array(this.outputLen);
+        const mem = new Uint8Array(this.x.memory.buffer);
+        const off = this.x.getOutOffset();
+        let pos = 0;
+        while (pos < this.outputLen) {
+            this.x.shakeSqueezeBlock();
+            const take = Math.min(this.outputLen - pos, this._rate);
+            out.set(mem.subarray(off, off + take), pos);
+            pos += take;
+        }
+        this.dispose();
+        return out;
+    }
+    dispose() {
+        if (this._tok === undefined)
+            return;
+        try {
+            this.x.wipeBuffers();
+        }
+        finally {
+            _releaseModule('sha3', this._tok);
+            this._tok = undefined;
+        }
+    }
+}
+// ── SHAKE256Stream ──────────────────────────────────────────────────────────
+/**
+ * Single-shot streaming SHAKE256. `outputLen` is bound at construction;
+ * mirrors `SHAKE128Stream`. See that class for usage notes.
+ */
+export class SHAKE256Stream {
+    x;
+    _rate = 136;
+    outputLen;
+    _tok;
+    constructor(outputLen) {
+        if (outputLen < 1)
+            throw new RangeError(`outputLen must be >= 1 (got ${outputLen})`);
+        this.outputLen = outputLen;
+        this.x = getExports();
+        this._tok = _acquireModule('sha3');
+        try {
+            this.x.shake256Init();
+        }
+        catch (e) {
+            _releaseModule('sha3', this._tok);
+            this._tok = undefined;
+            throw e;
+        }
+    }
+    update(chunk) {
+        if (this._tok === undefined)
+            throw new Error('SHAKE256Stream: instance has been disposed');
+        absorb(this.x, chunk);
+        return this;
+    }
+    finalize() {
+        if (this._tok === undefined)
+            throw new Error('SHAKE256Stream: instance has been disposed');
+        this.x.shakePad();
+        const out = new Uint8Array(this.outputLen);
+        const mem = new Uint8Array(this.x.memory.buffer);
+        const off = this.x.getOutOffset();
+        let pos = 0;
+        while (pos < this.outputLen) {
+            this.x.shakeSqueezeBlock();
+            const take = Math.min(this.outputLen - pos, this._rate);
+            out.set(mem.subarray(off, off + take), pos);
+            pos += take;
+        }
+        this.dispose();
+        return out;
+    }
+    dispose() {
+        if (this._tok === undefined)
+            return;
+        try {
+            this.x.wipeBuffers();
+        }
+        finally {
+            _releaseModule('sha3', this._tok);
+            this._tok = undefined;
+        }
     }
 }
+// ── SHA3_256Hash ────────────────────────────────────────────────────────────
+export { SHA3_256Hash } from './hash.js';
+// ── cSHAKE / KMAC (SP 800-185) ──────────────────────────────────────────────
+export { CSHAKE128, CSHAKE256, KMAC128, KMAC256, KMACXOF128, KMACXOF256 } from './kmac.js';

package/dist/sha3/kmac.d.ts

@@ -0,0 +1,121 @@
+/**
+ * cSHAKE128, customizable SHAKE128 (SP 800-185 §3).
+ *
+ * Holds exclusive access to the `sha3` WASM module from construction until
+ * `dispose()`. Constructing any other sha3 user (SHAKE128/256, SHA3_*,
+ * KMAC*, CSHAKE*) while this instance is live throws.
+ */
+export declare class CSHAKE128 {
+    private readonly x;
+    private readonly _rate;
+    private readonly _prefix;
+    private _squeezing;
+    private _block;
+    private _blockPos;
+    private _tok;
+    constructor(customization: Uint8Array);
+    reset(): this;
+    absorb(msg: Uint8Array): this;
+    squeeze(n: number): Uint8Array;
+    hash(msg: Uint8Array, outputLength: number): Uint8Array;
+    dispose(): void;
+}
+/**
+ * cSHAKE256, customizable SHAKE256 (SP 800-185 §3).
+ *
+ * Holds exclusive access to the `sha3` WASM module from construction until
+ * `dispose()`.
+ */
+export declare class CSHAKE256 {
+    private readonly x;
+    private readonly _rate;
+    private readonly _prefix;
+    private _squeezing;
+    private _block;
+    private _blockPos;
+    private _tok;
+    constructor(customization: Uint8Array);
+    reset(): this;
+    absorb(msg: Uint8Array): this;
+    squeeze(n: number): Uint8Array;
+    hash(msg: Uint8Array, outputLength: number): Uint8Array;
+    dispose(): void;
+}
+/**
+ * KMAC128, keyed Keccak MAC, fixed-output (SP 800-185 §4).
+ *
+ * Bound to a specific output length at construction (the spec's right_encode(L)
+ * suffix is a function of L). Use `KMACXOF128` for arbitrary-length output.
+ *
+ * Holds exclusive access to the `sha3` WASM module from construction until
+ * `dispose()`.
+ */
+export declare class KMAC128 {
+    private readonly x;
+    private readonly _rate;
+    private readonly _outLen;
+    private _finalized;
+    private _tok;
+    constructor(key: Uint8Array, outLen: number, customization: Uint8Array);
+    update(chunk: Uint8Array): this;
+    finalize(): Uint8Array;
+    mac(msg: Uint8Array): Uint8Array;
+    dispose(): void;
+    /**
+     * Constant-time tag verification. Throws `AuthenticationError('kmac128')`
+     * on mismatch (matches the lib's AEAD pattern). Returns `true` on success.
+     *
+     * Atomic, does not hold the sha3 module beyond the internal compute.
+     */
+    static verify(tag: Uint8Array, key: Uint8Array, msg: Uint8Array, customization: Uint8Array): true;
+}
+/**
+ * KMAC256, 256-bit-strength keyed Keccak MAC, fixed-output (SP 800-185 §4).
+ */
+export declare class KMAC256 {
+    private readonly x;
+    private readonly _rate;
+    private readonly _outLen;
+    private _finalized;
+    private _tok;
+    constructor(key: Uint8Array, outLen: number, customization: Uint8Array);
+    update(chunk: Uint8Array): this;
+    finalize(): Uint8Array;
+    mac(msg: Uint8Array): Uint8Array;
+    dispose(): void;
+    static verify(tag: Uint8Array, key: Uint8Array, msg: Uint8Array, customization: Uint8Array): true;
+}
+/**
+ * KMACXOF128, XOF variant of KMAC128 (SP 800-185 §4.3.1). Output length
+ * is caller-chosen per squeeze; the spec's right_encode(0) suffix marks the
+ * XOF mode.
+ */
+export declare class KMACXOF128 {
+    private readonly x;
+    private readonly _rate;
+    private _squeezing;
+    private _block;
+    private _blockPos;
+    private _tok;
+    constructor(key: Uint8Array, customization: Uint8Array);
+    update(chunk: Uint8Array): this;
+    squeeze(n: number): Uint8Array;
+    mac(msg: Uint8Array, outLen: number): Uint8Array;
+    dispose(): void;
+}
+/**
+ * KMACXOF256, XOF variant of KMAC256 (SP 800-185 §4.3.1).
+ */
+export declare class KMACXOF256 {
+    private readonly x;
+    private readonly _rate;
+    private _squeezing;
+    private _block;
+    private _blockPos;
+    private _tok;
+    constructor(key: Uint8Array, customization: Uint8Array);
+    update(chunk: Uint8Array): this;
+    squeeze(n: number): Uint8Array;
+    mac(msg: Uint8Array, outLen: number): Uint8Array;
+    dispose(): void;
+}