leviathan-crypto 2.0.1 → 3.0.0

package/dist/{kyber → mlkem}/suite.js

@@ -19,9 +19,9 @@
 //   ▀██████▀             ▀████▄▄▄████▀       for its {ab,mis,}use.
 //                           ▀█████▀▀
 //
-// src/ts/kyber/suite.ts
+// src/ts/mlkem/suite.ts
 //
-// KyberSuite — wraps a MlKemBase + inner CipherSuite into a unified CipherSuite.
+// MlKemSuite, wraps a MlKemBase + inner CipherSuite into a unified CipherSuite.
 // Provides hybrid KEM + symmetric AEAD for use with SealStream / OpenStream / Seal.
 import { concat } from '../utils.js';
 import { HKDF_SHA256 } from '../sha2/index.js';
@@ -36,7 +36,7 @@ const KEM_LABEL = {
     3: 'mlkem768',
     4: 'mlkem1024',
 };
-export function KyberSuite(kem, inner) {
+export function MlKemSuite(kem, inner) {
     const p = kem.params;
     const kemNibble = KEM_NIBBLE[p.k];
     if (!kemNibble)
@@ -50,23 +50,24 @@ export function KyberSuite(kem, inner) {
         keySize: p.ekBytes,
         decKeySize: p.dkBytes,
         kemCtSize: p.ctBytes,
+        commitmentSize: inner.commitmentSize,
         tagSize: inner.tagSize,
         padded: inner.padded,
         wasmChunkSize: inner.wasmChunkSize,
-        wasmModules: [...inner.wasmModules, 'kyber', 'sha3'],
-        deriveKeys(key, nonce, kemCt) {
+        wasmModules: [...inner.wasmModules, 'mlkem', 'sha3'],
+        deriveKeys(key, nonce, kemCt, header) {
             let sharedSecret;
             let outKemCt;
             let ctForInfo;
             if (kemCt === undefined) {
-                // encrypt path: key = ek — encapsulate to produce shared secret + ct
+                // encrypt path: key = ek, encapsulate to produce shared secret + ct
                 const result = kem.encapsulate(key);
                 sharedSecret = result.sharedSecret;
                 outKemCt = result.ciphertext;
                 ctForInfo = outKemCt;
             }
             else {
-                // decrypt path: key = dk — decapsulate to recover shared secret
+                // decrypt path: key = dk, decapsulate to recover shared secret
                 sharedSecret = kem.decapsulate(key, kemCt);
                 ctForInfo = kemCt;
             }
@@ -76,12 +77,16 @@ export function KyberSuite(kem, inner) {
             const derived = hkdf.derive(sharedSecret, nonce, info, inner.keySize);
             hkdf.dispose();
             sharedSecret.fill(0);
-            // Delegate actual per-cipher key derivation to the inner suite
-            const innerKeys = inner.deriveKeys(derived, nonce);
+            // Delegate actual per-cipher key derivation to the inner suite.
+            // Header is forwarded so XChaCha20's deriveKeys can bind it into
+            // HKDF info; SerpentCipher accepts and ignores it.
+            const innerKeys = inner.deriveKeys(derived, nonce, undefined, header);
             derived.fill(0);
-            return outKemCt
-                ? { bytes: innerKeys.bytes, kemCiphertext: outKemCt }
-                : innerKeys;
+            if (!outKemCt)
+                return innerKeys;
+            return innerKeys.commitment
+                ? { bytes: innerKeys.bytes, kemCiphertext: outKemCt, commitment: innerKeys.commitment }
+                : { bytes: innerKeys.bytes, kemCiphertext: outKemCt };
         },
         sealChunk: inner.sealChunk.bind(inner),
         openChunk: inner.openChunk.bind(inner),

package/dist/{kyber → mlkem}/types.d.ts

@@ -1,4 +1,4 @@
-export interface KyberExports {
+export interface MlKemExports {
     memory: WebAssembly.Memory;
     getModuleId: () => number;
     getMemoryPages: () => number;
@@ -63,6 +63,7 @@ export interface KyberExports {
     polyvec_reduce: (pvOffset: number, k: number) => void;
     polyvec_add: (rOffset: number, aOffset: number, bOffset: number, k: number) => void;
     polyvec_basemul_acc_montgomery: (rOffset: number, aOffset: number, bOffset: number, k: number) => void;
+    polyvec_modulus_check: (pvOffset: number, k: number) => number;
     rej_uniform: (polyOffset: number, ctrStart: number, bufOffset: number, buflen: number) => number;
     ct_verify: (aOffset: number, bOffset: number, len: number) => number;
     ct_cmov: (rOffset: number, xOffset: number, len: number, b: number) => void;
@@ -88,11 +89,11 @@ export interface Sha3Exports {
     shakeSqueezeBlock: () => void;
     wipeBuffers: () => void;
 }
-export interface KyberKeyPair {
+export interface MlKemKeyPair {
     encapsulationKey: Uint8Array;
     decapsulationKey: Uint8Array;
 }
-export interface KyberEncapsulation {
+export interface MlKemEncapsulation {
     ciphertext: Uint8Array;
     sharedSecret: Uint8Array;
 }

package/dist/{kyber → mlkem}/types.js

@@ -19,7 +19,7 @@
 //   ▀██████▀             ▀████▄▄▄████▀       for its {ab,mis,}use.
 //                           ▀█████▀▀
 //
-// src/ts/kyber/types.ts
+// src/ts/mlkem/types.ts
 //
 // ML-KEM type definitions: WASM export interfaces and KEM API types.
 export {};

package/dist/mlkem/validate.d.ts

@@ -0,0 +1,23 @@
+import type { MlKemExports, Sha3Exports } from './types.js';
+import type { MlKemParams } from './params.js';
+/**
+ * Encapsulation key check, FIPS 203 §7.2 (EncapsulationKeyCheck).
+ *
+ * 1. Length gate: ek.length must equal params.ekBytes.
+ * 2. Decode the polyvec portion via ByteDecode₁₂ (polyvec_frombytes). The
+ *    decoded coefficients are raw 12-bit values in [0, 4095], frombytes
+ *    does not reduce mod q.
+ * 3. Modulus scan: every coefficient must satisfy c < Q = 3329.
+ *
+ * Returns true iff both gates pass. The seed ρ (final 32 bytes of ek) is
+ * not checked; any 32-byte value is a valid ρ per FIPS 203.
+ */
+export declare function checkEncapsulationKey(kx: MlKemExports, params: MlKemParams, ek: Uint8Array): boolean;
+/**
+ * Decapsulation key check, FIPS 203 §7.3 (DecapsulationKeyCheck).
+ *
+ * 1. Length check: dk.length == params.dkBytes
+ * 2. Extract embedded ek and H(ek), verify SHA3-256(ek) matches stored H
+ * 3. Also run checkEncapsulationKey on the embedded ek
+ */
+export declare function checkDecapsulationKey(kx: MlKemExports, sx: Sha3Exports, params: MlKemParams, dk: Uint8Array): boolean;

package/dist/{kyber → mlkem}/validate.js

@@ -19,37 +19,36 @@
 //   ▀██████▀             ▀████▄▄▄████▀       for its {ab,mis,}use.
 //                           ▀█████▀▀
 //
-// src/ts/kyber/validate.ts
+// src/ts/mlkem/validate.ts
 //
-// ML-KEM key validation — FIPS 203 §7.2 and §7.3.
+// ML-KEM key validation, FIPS 203 §7.2 and §7.3.
 import { sha3_256Hash } from './indcpa.js';
 import { constantTimeEqual } from '../utils.js';
 /**
- * Encapsulation key check — FIPS 203 §7.2 (EncapsulationKeyCheck).
+ * Encapsulation key check, FIPS 203 §7.2 (EncapsulationKeyCheck).
  *
- * 1. Length check: ek.length == params.ekBytes
- * 2. ByteDecode₁₂ → ByteEncode₁₂ round-trip check on the polyvec portion.
- *    Any coefficient ≥ q stored modulo 2^12 survives frombytes, but tobytes
- *    re-encodes it differently — so the round-trip fails iff any coeff was ≥ q.
+ * 1. Length gate: ek.length must equal params.ekBytes.
+ * 2. Decode the polyvec portion via ByteDecode₁₂ (polyvec_frombytes). The
+ *    decoded coefficients are raw 12-bit values in [0, 4095], frombytes
+ *    does not reduce mod q.
+ * 3. Modulus scan: every coefficient must satisfy c < Q = 3329.
+ *
+ * Returns true iff both gates pass. The seed ρ (final 32 bytes of ek) is
+ * not checked; any 32-byte value is a valid ρ per FIPS 203.
  */
 export function checkEncapsulationKey(kx, params, ek) {
     if (ek.length !== params.ekBytes)
         return false;
     const { k } = params;
-    const kyberMem = new Uint8Array(kx.memory.buffer);
+    const mlkemMem = new Uint8Array(kx.memory.buffer);
     const pkOff = kx.getPkOffset();
-    const skOff = kx.getSkOffset();
     const pvecOff = kx.getPolyvecSlot0();
-    // Write the polyvec portion of ek into PK buffer, decode, re-encode
-    kyberMem.set(ek.subarray(0, k * 384), pkOff);
+    mlkemMem.set(ek.subarray(0, k * 384), pkOff);
     kx.polyvec_frombytes(pvecOff, pkOff, k);
-    kx.polyvec_tobytes(skOff, pvecOff, k);
-    // orig is at pkOff (written above); reEnc is at skOff (polyvec_tobytes output)
-    const mismatch = kx.ct_verify(pkOff, skOff, k * 384);
-    return mismatch === 0;
+    return kx.polyvec_modulus_check(pvecOff, k) === 0;
 }
 /**
- * Decapsulation key check — FIPS 203 §7.3 (DecapsulationKeyCheck).
+ * Decapsulation key check, FIPS 203 §7.3 (DecapsulationKeyCheck).
  *
  * 1. Length check: dk.length == params.dkBytes
  * 2. Extract embedded ek and H(ek), verify SHA3-256(ek) matches stored H
@@ -61,8 +60,13 @@ export function checkDecapsulationKey(kx, sx, params, dk) {
     const { skCpaBytes, ekBytes } = params;
     const ek = dk.slice(skCpaBytes, skCpaBytes + ekBytes);
     const h = dk.slice(skCpaBytes + ekBytes, skCpaBytes + ekBytes + 32);
-    const hComputed = sha3_256Hash(sx, ek);
-    if (!constantTimeEqual(hComputed, h))
-        return false;
-    return checkEncapsulationKey(kx, params, ek);
+    try {
+        const hComputed = sha3_256Hash(sx, ek);
+        if (!constantTimeEqual(hComputed, h))
+            return false;
+        return checkEncapsulationKey(kx, params, ek);
+    }
+    finally {
+        sx.wipeBuffers();
+    }
 }

package/dist/ratchet/index.d.ts

@@ -0,0 +1,8 @@
+export { KDFChain } from './kdf-chain.js';
+export { ratchetInit, kemRatchetEncap, kemRatchetDecap } from './root-kdf.js';
+export { SkippedKeyStore } from './skipped-key-store.js';
+export { RatchetKeypair } from './ratchet-keypair.js';
+export type { RatchetInitResult, KemEncapResult, KemDecapResult, MlKemLike, RatchetMessageHeader, ResolveHandle, SkippedKeyStoreOpts, } from './types.js';
+import { isInitialized } from '../init.js';
+export { isInitialized };
+export declare function ratchetReady(): boolean;

package/dist/ratchet/index.js

@@ -0,0 +1,38 @@
+//                  ▄▄▄▄▄▄▄▄▄▄
+//           ▄████████████████████▄▄          ▒  ▄▀▀ ▒ ▒ █ ▄▀▄ ▀█▀ █ ▒ ▄▀▄ █▀▄
+//        ▄██████████████████████ ▀████▄      ▓  ▓▀  ▓ ▓ ▓ ▓▄▓  ▓  ▓▀▓ ▓▄▓ ▓ ▓
+//      ▄█████████▀▀▀     ▀███████▄▄███████▌  ▀▄ ▀▄▄ ▀▄▀ ▒ ▒ ▒  ▒  ▒ █ ▒ ▒ ▒ █
+//     ▐████████▀   ▄▄▄▄     ▀████████▀██▀█▌
+//     ████████      ███▀▀     ████▀  █▀ █▀       Leviathan Crypto Library
+//     ███████▌    ▀██▀         ███
+//      ███████   ▀███           ▀██ ▀█▄      Repository & Mirror:
+//       ▀██████   ▄▄██            ▀▀  ██▄    github.com/xero/leviathan-crypto
+//         ▀█████▄   ▄██▄             ▄▀▄▀    unpkg.com/leviathan-crypto
+//            ▀████▄   ▄██▄
+//              ▐████   ▐███                  Author: xero (https://x-e.ro)
+//       ▄▄██████████    ▐███         ▄▄      License: MIT
+//    ▄██▀▀▀▀▀▀▀▀▀▀     ▄████      ▄██▀
+//  ▄▀  ▄▄█████████▄▄  ▀▀▀▀▀     ▄███         This file is provided completely
+//   ▄██████▀▀▀▀▀▀██████▄ ▀▄▄▄▄████▀          free, "as is", and without
+//  ████▀    ▄▄▄▄▄▄▄ ▀████▄ ▀█████▀  ▄▄▄▄     warranty of any kind. The author
+//  █████▄▄█████▀▀▀▀▀▀▄ ▀███▄      ▄████      assumes absolutely no liability
+//   ▀██████▀             ▀████▄▄▄████▀       for its {ab,mis,}use.
+//                           ▀█████▀▀
+//
+// src/ts/ratchet/index.ts
+//
+// Public barrel for the ratchet module.
+export { KDFChain } from './kdf-chain.js';
+export { ratchetInit, kemRatchetEncap, kemRatchetDecap } from './root-kdf.js';
+export { SkippedKeyStore } from './skipped-key-store.js';
+export { RatchetKeypair } from './ratchet-keypair.js';
+import { isInitialized } from '../init.js';
+export { isInitialized };
+export function ratchetReady() {
+    try {
+        return isInitialized('sha2');
+    }
+    catch {
+        return false;
+    }
+}

package/dist/ratchet/kdf-chain.d.ts

@@ -0,0 +1,13 @@
+export declare class KDFChain {
+    private _ck;
+    private _n;
+    private _disposed;
+    constructor(ck: Uint8Array);
+    step(): Uint8Array;
+    stepWithCounter(): {
+        key: Uint8Array;
+        counter: number;
+    };
+    get n(): number;
+    dispose(): void;
+}

package/dist/ratchet/kdf-chain.js

@@ -0,0 +1,85 @@
+//                  ▄▄▄▄▄▄▄▄▄▄
+//           ▄████████████████████▄▄          ▒  ▄▀▀ ▒ ▒ █ ▄▀▄ ▀█▀ █ ▒ ▄▀▄ █▀▄
+//        ▄██████████████████████ ▀████▄      ▓  ▓▀  ▓ ▓ ▓ ▓▄▓  ▓  ▓▀▓ ▓▄▓ ▓ ▓
+//      ▄█████████▀▀▀     ▀███████▄▄███████▌  ▀▄ ▀▄▄ ▀▄▀ ▒ ▒ ▒  ▒  ▒ █ ▒ ▒ ▒ █
+//     ▐████████▀   ▄▄▄▄     ▀████████▀██▀█▌
+//     ████████      ███▀▀     ████▀  █▀ █▀       Leviathan Crypto Library
+//     ███████▌    ▀██▀         ███
+//      ███████   ▀███           ▀██ ▀█▄      Repository & Mirror:
+//       ▀██████   ▄▄██            ▀▀  ██▄    github.com/xero/leviathan-crypto
+//         ▀█████▄   ▄██▄             ▄▀▄▀    unpkg.com/leviathan-crypto
+//            ▀████▄   ▄██▄
+//              ▐████   ▐███                  Author: xero (https://x-e.ro)
+//       ▄▄██████████    ▐███         ▄▄      License: MIT
+//    ▄██▀▀▀▀▀▀▀▀▀▀     ▄████      ▄██▀
+//  ▄▀  ▄▄█████████▄▄  ▀▀▀▀▀     ▄███         This file is provided completely
+//   ▄██████▀▀▀▀▀▀██████▄ ▀▄▄▄▄████▀          free, "as is", and without
+//  ████▀    ▄▄▄▄▄▄▄ ▀████▄ ▀█████▀  ▄▄▄▄     warranty of any kind. The author
+//  █████▄▄█████▀▀▀▀▀▀▄ ▀███▄      ▄████      assumes absolutely no liability
+//   ▀██████▀             ▀████▄▄▄████▀       for its {ab,mis,}use.
+//                           ▀█████▀▀
+//
+// src/ts/ratchet/kdf-chain.ts
+//
+// KDFChain, stateful symmetric ratchet chain step (spec §5.2, KDF_SCKA_CK).
+// Each step derives a message key and advances the chain key via HKDF-SHA-256.
+import { HKDF_SHA256 } from '../sha2/index.js';
+import { isInitialized } from '../init.js';
+import { wipe, concat, utf8ToBytes } from '../utils.js';
+// Signal Double Ratchet §7.2, chain step info string
+const INFO_CHAIN_BYTES = utf8ToBytes('leviathan-ratchet-v1 Chain Step');
+const ZERO_SALT = new Uint8Array(32);
+export class KDFChain {
+    _ck;
+    _n;
+    _disposed;
+    constructor(ck) {
+        if (!isInitialized('sha2'))
+            throw new Error('leviathan-crypto: call init({ sha2: ... }) before using KDFChain');
+        if (ck.length !== 32)
+            throw new RangeError('KDFChain: ck must be 32 bytes');
+        this._ck = ck.slice();
+        this._n = 0;
+        this._disposed = false;
+    }
+    step() {
+        if (this._disposed)
+            throw new Error('KDFChain: instance has been disposed');
+        if (this._n >= Number.MAX_SAFE_INTEGER)
+            throw new RangeError('KDFChain: counter exceeds maximum safe integer');
+        const nextN = this._n + 1;
+        // Encode counter as big-endian uint64, two u32 calls, no BigInt
+        const ctrBuf = new Uint8Array(8);
+        const dv = new DataView(ctrBuf.buffer);
+        dv.setUint32(0, Math.floor(nextN / 0x100000000), false);
+        dv.setUint32(4, nextN >>> 0, false);
+        const info = concat(INFO_CHAIN_BYTES, ctrBuf);
+        const h = new HKDF_SHA256();
+        try {
+            const okm = h.derive(this._ck, ZERO_SALT, info, 64);
+            const nextCk = okm.slice(0, 32);
+            const msgKey = okm.slice(32, 64);
+            wipe(this._ck);
+            this._ck = nextCk;
+            this._n = nextN;
+            wipe(okm);
+            return msgKey;
+        }
+        finally {
+            h.dispose();
+        }
+    }
+    // Returns both the message key and the post-step counter atomically.
+    // Eliminates the two-step step() + .n read pattern and the off-by-one risk.
+    stepWithCounter() {
+        const key = this.step();
+        return { key, counter: this._n };
+    }
+    get n() {
+        return this._n;
+    }
+    dispose() {
+        wipe(this._ck);
+        this._disposed = true;
+    }
+}

package/dist/ratchet/ratchet-keypair.d.ts

@@ -0,0 +1,9 @@
+import type { MlKemLike, KemDecapResult } from './types.js';
+export declare class RatchetKeypair {
+    readonly ek: Uint8Array;
+    private _dk;
+    private _used;
+    constructor(kem: MlKemLike);
+    decap(kem: MlKemLike, rk: Uint8Array, kemCt: Uint8Array, context?: Uint8Array): KemDecapResult;
+    dispose(): void;
+}

package/dist/ratchet/ratchet-keypair.js

@@ -0,0 +1,61 @@
+//                  ▄▄▄▄▄▄▄▄▄▄
+//           ▄████████████████████▄▄          ▒  ▄▀▀ ▒ ▒ █ ▄▀▄ ▀█▀ █ ▒ ▄▀▄ █▀▄
+//        ▄██████████████████████ ▀████▄      ▓  ▓▀  ▓ ▓ ▓ ▓▄▓  ▓  ▓▀▓ ▓▄▓ ▓ ▓
+//      ▄█████████▀▀▀     ▀███████▄▄███████▌  ▀▄ ▀▄▄ ▀▄▀ ▒ ▒ ▒  ▒  ▒ █ ▒ ▒ ▒ █
+//     ▐████████▀   ▄▄▄▄     ▀████████▀██▀█▌
+//     ████████      ███▀▀     ████▀  █▀ █▀       Leviathan Crypto Library
+//     ███████▌    ▀██▀         ███
+//      ███████   ▀███           ▀██ ▀█▄      Repository & Mirror:
+//       ▀██████   ▄▄██            ▀▀  ██▄    github.com/xero/leviathan-crypto
+//         ▀█████▄   ▄██▄             ▄▀▄▀    unpkg.com/leviathan-crypto
+//            ▀████▄   ▄██▄
+//              ▐████   ▐███                  Author: xero (https://x-e.ro)
+//       ▄▄██████████    ▐███         ▄▄      License: MIT
+//    ▄██▀▀▀▀▀▀▀▀▀▀     ▄████      ▄██▀
+//  ▄▀  ▄▄█████████▄▄  ▀▀▀▀▀     ▄███         This file is provided completely
+//   ▄██████▀▀▀▀▀▀██████▄ ▀▄▄▄▄████▀          free, "as is", and without
+//  ████▀    ▄▄▄▄▄▄▄ ▀████▄ ▀█████▀  ▄▄▄▄     warranty of any kind. The author
+//  █████▄▄█████▀▀▀▀▀▀▄ ▀███▄      ▄████      assumes absolutely no liability
+//   ▀██████▀             ▀████▄▄▄████▀       for its {ab,mis,}use.
+//                           ▀█████▀▀
+//
+// src/ts/ratchet/ratchet-keypair.ts
+//
+// RatchetKeypair, single-use ek/dk lifecycle for one KEM ratchet step.
+// Enforces the DR spec requirement that both parties rotate encapsulation
+// keys after each KEM ratchet step.
+import { wipe } from '../utils.js';
+import { kemRatchetDecap } from './root-kdf.js';
+export class RatchetKeypair {
+    ek;
+    _dk;
+    _used;
+    constructor(kem) {
+        const { encapsulationKey, decapsulationKey } = kem.keygen();
+        this.ek = encapsulationKey;
+        this._dk = decapsulationKey;
+        this._used = false;
+    }
+    // Decapsulate using the stored dk. May only be called once per instance.
+    // Wipes the dk immediately after decap, the dk never leaves this class.
+    // The stored ek is passed as `ownEk` so both sides bind the identical
+    // (peerEk, kemCt) pair into the HKDF info string.
+    decap(kem, rk, kemCt, context) {
+        if (this._used)
+            throw new Error('RatchetKeypair: already consumed or disposed. generate a new keypair for the next ratchet step');
+        this._used = true;
+        try {
+            return kemRatchetDecap(kem, rk, this._dk, kemCt, this.ek, context);
+        }
+        finally {
+            wipe(this._dk);
+        }
+    }
+    // Wipe the dk if not already wiped by decap. Idempotent.
+    dispose() {
+        if (!this._used) {
+            wipe(this._dk);
+            this._used = true;
+        }
+    }
+}

package/dist/ratchet/root-kdf.d.ts

@@ -0,0 +1,4 @@
+import type { MlKemLike, RatchetInitResult, KemEncapResult, KemDecapResult } from './types.js';
+export declare function ratchetInit(sk: Uint8Array, context?: Uint8Array): RatchetInitResult;
+export declare function kemRatchetEncap(kem: MlKemLike, rk: Uint8Array, peerEk: Uint8Array, context?: Uint8Array): KemEncapResult;
+export declare function kemRatchetDecap(kem: MlKemLike, rk: Uint8Array, dk: Uint8Array, kemCt: Uint8Array, ownEk: Uint8Array, context?: Uint8Array): KemDecapResult;

package/dist/ratchet/root-kdf.js

@@ -0,0 +1,124 @@
+//                  ▄▄▄▄▄▄▄▄▄▄
+//           ▄████████████████████▄▄          ▒  ▄▀▀ ▒ ▒ █ ▄▀▄ ▀█▀ █ ▒ ▄▀▄ █▀▄
+//        ▄██████████████████████ ▀████▄      ▓  ▓▀  ▓ ▓ ▓ ▓▄▓  ▓  ▓▀▓ ▓▄▓ ▓ ▓
+//      ▄█████████▀▀▀     ▀███████▄▄███████▌  ▀▄ ▀▄▄ ▀▄▀ ▒ ▒ ▒  ▒  ▒ █ ▒ ▒ ▒ █
+//     ▐████████▀   ▄▄▄▄     ▀████████▀██▀█▌
+//     ████████      ███▀▀     ████▀  █▀ █▀       Leviathan Crypto Library
+//     ███████▌    ▀██▀         ███
+//      ███████   ▀███           ▀██ ▀█▄      Repository & Mirror:
+//       ▀██████   ▄▄██            ▀▀  ██▄    github.com/xero/leviathan-crypto
+//         ▀█████▄   ▄██▄             ▄▀▄▀    unpkg.com/leviathan-crypto
+//            ▀████▄   ▄██▄
+//              ▐████   ▐███                  Author: xero (https://x-e.ro)
+//       ▄▄██████████    ▐███         ▄▄      License: MIT
+//    ▄██▀▀▀▀▀▀▀▀▀▀     ▄████      ▄██▀
+//  ▄▀  ▄▄█████████▄▄  ▀▀▀▀▀     ▄███         This file is provided completely
+//   ▄██████▀▀▀▀▀▀██████▄ ▀▄▄▄▄████▀          free, "as is", and without
+//  ████▀    ▄▄▄▄▄▄▄ ▀████▄ ▀█████▀  ▄▄▄▄     warranty of any kind. The author
+//  █████▄▄█████▀▀▀▀▀▀▄ ▀███▄      ▄████      assumes absolutely no liability
+//   ▀██████▀             ▀████▄▄▄████▀       for its {ab,mis,}use.
+//                           ▀█████▀▀
+//
+// src/ts/ratchet/root-kdf.ts
+//
+// Root KDF functions for the Sparse Post-Quantum Ratchet (spec §7.2).
+// Implements KDF_SCKA_INIT (ratchetInit) and KDF_SCKA_RK (kemRatchetEncap/Decap).
+import { HKDF_SHA256 } from '../sha2/index.js';
+import { isInitialized } from '../init.js';
+import { wipe, concat, utf8ToBytes } from '../utils.js';
+// Signal Double Ratchet §7.2, info strings
+const INFO_INIT = utf8ToBytes('leviathan-ratchet-v1 Chain Start');
+const INFO_ROOT = utf8ToBytes('leviathan-ratchet-v1 Chain Add Epoch');
+// INFO_CHAIN ('leviathan-ratchet-v1 Chain Step') is used in kdf-chain.ts
+const ZERO_SALT = new Uint8Array(32);
+// HKDF-SHA-256 root step (KDF_SCKA_INIT and KDF_SCKA_RK share this shape).
+// ikm    = 32-byte secret (shared secret or sk)
+// salt   = 32-byte salt (zero bytes for init, rk for KEM ratchet)
+// info   = protocol info bytes
+// length = 96
+// → { nextRootKey: [0:32], sendChainKey: [32:64], recvChainKey: [64:96] }
+// Wipes okm after slicing.
+function kdfRoot(secret, salt, info) {
+    const h = new HKDF_SHA256();
+    try {
+        const okm = h.derive(secret, salt, info, 96);
+        const nextRootKey = okm.slice(0, 32);
+        const sendChainKey = okm.slice(32, 64);
+        const recvChainKey = okm.slice(64, 96);
+        wipe(okm);
+        return { nextRootKey, sendChainKey, recvChainKey };
+    }
+    finally {
+        h.dispose();
+    }
+}
+// u32 big-endian length prefix, same convention as serpent/cipher-suite.ts AAD encoding.
+function u32be(n) {
+    if (!Number.isInteger(n) || n < 0 || n > 0xFFFFFFFF)
+        throw new RangeError(`u32be: n must be an integer in [0, 0xFFFFFFFF] (got ${n})`);
+    const b = new Uint8Array(4);
+    new DataView(b.buffer).setUint32(0, n, false);
+    return b;
+}
+// KEM ratchet info, binds peerEk, kemCt, and context with u32be length prefixes.
+// Defense-in-depth: the HKDF output is tied to the exact (peerEk, kemCt, context)
+// tuple used, not just the KEM shared secret. An attacker who substitutes any of
+// these inputs derives a different chain key trio, regardless of the KEM transcript.
+function buildRootInfo(peerEk, kemCt, context) {
+    const ctxBytes = context ?? new Uint8Array(0);
+    return concat(INFO_ROOT, u32be(peerEk.length), peerEk, u32be(kemCt.length), kemCt, u32be(ctxBytes.length), ctxBytes);
+}
+// KDF_SCKA_INIT, spec §7.2
+// Derives initial root key, send chain key, and receive chain key from a
+// shared secret sk. Optional context bytes are appended to the info string.
+export function ratchetInit(sk, context) {
+    if (!isInitialized('sha2'))
+        throw new Error('leviathan-crypto: call init({ sha2: ... }) before using ratchetInit');
+    if (sk.length !== 32)
+        throw new RangeError('ratchetInit: sk must be 32 bytes');
+    const info = context != null && context.length > 0 ? concat(INFO_INIT, context) : INFO_INIT;
+    const { nextRootKey, sendChainKey, recvChainKey } = kdfRoot(sk, ZERO_SALT, info);
+    return { nextRootKey, sendChainKey, recvChainKey };
+}
+// KDF_SCKA_RK, encapsulation side (spec §7.2)
+// Generates a fresh KEM ciphertext, derives next epoch keys from the shared secret.
+// `peerEk` and `kemCt` are bound into the HKDF info string (defense-in-depth).
+export function kemRatchetEncap(kem, rk, peerEk, context) {
+    if (!isInitialized('sha2'))
+        throw new Error('leviathan-crypto: call init({ sha2: ... }) before using kemRatchetEncap');
+    if (rk.length !== 32)
+        throw new RangeError('kemRatchetEncap: rk must be 32 bytes');
+    const { ciphertext: kemCt, sharedSecret } = kem.encapsulate(peerEk);
+    const info = buildRootInfo(peerEk, kemCt, context);
+    try {
+        const { nextRootKey, sendChainKey, recvChainKey } = kdfRoot(sharedSecret, rk, info);
+        return { nextRootKey, sendChainKey, recvChainKey, kemCt };
+    }
+    finally {
+        wipe(sharedSecret);
+    }
+}
+// KDF_SCKA_RK, decapsulation side (spec §7.2)
+// Recovers the shared secret from the KEM ciphertext, derives next epoch keys.
+// The chain key slots are swapped relative to the encap side: what the KDF
+// labels 'sendChainKey' (A→B direction) becomes the decap side's recvChainKey,
+// and vice versa, Alice's send IS Bob's receive.
+//
+// `ownEk` is the local party's encapsulation key (the same public key the
+// encap side targeted as `peerEk`). It must be passed explicitly so both
+// sides bind the identical (peerEk, kemCt) pair into the HKDF info string.
+export function kemRatchetDecap(kem, rk, dk, kemCt, ownEk, context) {
+    if (!isInitialized('sha2'))
+        throw new Error('leviathan-crypto: call init({ sha2: ... }) before using kemRatchetDecap');
+    if (rk.length !== 32)
+        throw new RangeError('kemRatchetDecap: rk must be 32 bytes');
+    const sharedSecret = kem.decapsulate(dk, kemCt);
+    const info = buildRootInfo(ownEk, kemCt, context);
+    try {
+        const { nextRootKey, sendChainKey: recvChainKey, recvChainKey: sendChainKey } = kdfRoot(sharedSecret, rk, info);
+        return { nextRootKey, sendChainKey, recvChainKey };
+    }
+    finally {
+        wipe(sharedSecret);
+    }
+}

package/dist/ratchet/skipped-key-store.d.ts

@@ -0,0 +1,14 @@
+import { KDFChain } from './kdf-chain.js';
+import type { ResolveHandle, SkippedKeyStoreOpts } from './types.js';
+export declare class SkippedKeyStore {
+    private _store;
+    private _maxCacheSize;
+    private _maxSkipPerResolve;
+    constructor(opts?: SkippedKeyStoreOpts);
+    private _evictOldest;
+    resolve(chain: KDFChain, counter: number): ResolveHandle;
+    private _makeHandle;
+    advanceToBoundary(chain: KDFChain, pn: number): void;
+    get size(): number;
+    wipeAll(): void;
+}