leviathan-crypto 2.0.0 → 2.1.0

package/dist/kyber/kem.js

@@ -33,6 +33,20 @@ import { wipe } from '../utils.js';
 export function kemKeypairDerand(kx, sx, params, d, z) {
     // indcpaKeypairDerand handles its own sigma wipe
     const { ekCpa, skCpa } = indcpaKeypairDerand(kx, sx, params, d);
+    // Wipe kyber WASM scratch regions that held the CPA secret key and the
+    // keygen noise. After kemKeypairDerand returns, no secret or secret-
+    // derived data persists in kyber linear memory until the next kyber op
+    // or MlKem.dispose(). SK_OFFSET holds skCpa packed via polyvec_tobytes
+    // — same severity class as the decap-side SK_OFFSET residual (R-028):
+    // long-lived key material whose disclosure compromises every ciphertext
+    // under the corresponding ek. POLYVEC_SLOT_1/2 hold ŝ and ê in NTT
+    // domain. XOF_PRF_OFFSET holds the last PRF output block. POLYVEC_SLOT_3
+    // (t̂) and POLYVEC_SLOT_0 (Â rows) are public and intentionally skipped.
+    const kyberMem = new Uint8Array(kx.memory.buffer);
+    kyberMem.fill(0, kx.getSkOffset(), kx.getSkOffset() + params.skCpaBytes);
+    kyberMem.fill(0, kx.getPolyvecSlot1(), kx.getPolyvecSlot1() + 2048);
+    kyberMem.fill(0, kx.getPolyvecSlot2(), kx.getPolyvecSlot2() + 2048);
+    kyberMem.fill(0, kx.getXofPrfOffset(), kx.getXofPrfOffset() + 1024);
     const h = sha3_256Hash(sx, ekCpa);
     try {
         const dk = new Uint8Array(params.dkBytes);
@@ -40,6 +54,7 @@ export function kemKeypairDerand(kx, sx, params, d, z) {
         dk.set(ekCpa, params.skCpaBytes);
         dk.set(h, params.skCpaBytes + params.ekBytes);
         dk.set(z, params.skCpaBytes + params.ekBytes + 32);
+        sx.wipeBuffers();
         return {
             encapsulationKey: ekCpa,
             decapsulationKey: dk,
@@ -68,6 +83,27 @@ export function kemEncapsulateDerand(kx, sx, params, ek, m) {
         const K = gOut.slice(0, 32);
         r = gOut.slice(32, 64);
         const c = indcpaEncrypt(kx, sx, params, ek, m, r);
+        // Wipe kyber WASM scratch regions that held m / r / e₁ / e₂ / u / v /
+        // m-poly / PRF output. After kemEncapsulateDerand returns, no secret
+        // or secret-derived data persists in kyber linear memory until the
+        // next kyber op or MlKem.dispose(). MSG_OFFSET holds raw m —
+        // reproducing the shared secret K = G(m ‖ H(ek))[0..32] only needs m
+        // plus the public ek, so this is the highest-severity encap residual.
+        // POLYVEC_SLOT_1/2/3 hold r, e₁, and uncompressed u (u compression is
+        // lossy for du ∈ {10,11} — uncompressed u reveals low-order bits the
+        // public ciphertext hides). POLY_SLOT_1/2/3 hold e₂ (full 512B), v,
+        // and the m-polynomial. XOF_PRF_OFFSET holds the last PRF block.
+        // PK_OFFSET, CT_OFFSET, POLYVEC_SLOT_0/4 are public — skipped.
+        const kyberMem = new Uint8Array(kx.memory.buffer);
+        kyberMem.fill(0, kx.getMsgOffset(), kx.getMsgOffset() + 32);
+        kyberMem.fill(0, kx.getPolyvecSlot1(), kx.getPolyvecSlot1() + 2048);
+        kyberMem.fill(0, kx.getPolyvecSlot2(), kx.getPolyvecSlot2() + 2048);
+        kyberMem.fill(0, kx.getPolyvecSlot3(), kx.getPolyvecSlot3() + 2048);
+        kyberMem.fill(0, kx.getPolySlot1(), kx.getPolySlot1() + 512);
+        kyberMem.fill(0, kx.getPolySlot2(), kx.getPolySlot2() + 512);
+        kyberMem.fill(0, kx.getPolySlot3(), kx.getPolySlot3() + 512);
+        kyberMem.fill(0, kx.getXofPrfOffset(), kx.getXofPrfOffset() + 1024);
+        sx.wipeBuffers();
         return { ciphertext: c, sharedSecret: K };
     }
     finally {
@@ -133,7 +169,26 @@ export function kemDecapsulate(kx, sx, params, dk, c) {
         const fail = kx.ct_verify(ctOff, ctPrimeOff, ctBytes);
         // If fail != 0 (mismatch): K' ← K̄
         kx.ct_cmov(kPrimeOff, kBarOff, 32, fail);
-        return kyberMem.slice(kPrimeOff, kPrimeOff + 32);
+        const sharedSecret = kyberMem.slice(kPrimeOff, kPrimeOff + 32);
+        // Wipe kyber WASM scratch regions that held the CPA secret key (skCpa),
+        // m' / K' / K̄ / e₂ / r / e₁ / u, and the PRF output buffer. Without
+        // this, residual secret and secret-derived bytes persist in linear
+        // memory until the next kyber op or MlKem.dispose() — a window during
+        // which any other code with a handle to the kyber exports could read
+        // them. skCpa is the highest-severity residual: it compromises every
+        // ciphertext under the corresponding ek, not just this message.
+        kyberMem.fill(0, kx.getMsgOffset(), kx.getMsgOffset() + 32); // m' (bytes)
+        kyberMem.fill(0, kPrimeOff, kPrimeOff + 32); // K' (final shared secret)
+        kyberMem.fill(0, kBarOff, kBarOff + 512); // K̄ (first 32B) + e₂ poly tail
+        kyberMem.fill(0, kx.getPolySlot2(), kx.getPolySlot2() + 512); // m'-poly / v residual
+        kyberMem.fill(0, kx.getPolySlot3(), kx.getPolySlot3() + 512); // indcpa message poly
+        kyberMem.fill(0, kx.getPolyvecSlot1(), kx.getPolyvecSlot1() + 2048); // r (NTT-domain noise polyvec)
+        kyberMem.fill(0, kx.getPolyvecSlot2(), kx.getPolyvecSlot2() + 2048); // e₁ (noise polyvec for u)
+        kyberMem.fill(0, kx.getPolyvecSlot3(), kx.getPolyvecSlot3() + 2048); // uncompressed u polyvec from FO re-encryption
+        kyberMem.fill(0, kx.getXofPrfOffset(), kx.getXofPrfOffset() + 1024); // last PRF output block
+        kyberMem.fill(0, kx.getSkOffset(), kx.getSkOffset() + skCpaBytes); // CPA secret key (long-lived — highest severity residual)
+        sx.wipeBuffers();
+        return sharedSecret;
     }
     finally {
         if (mPrime)

package/dist/kyber/suite.d.ts

@@ -1,7 +1,7 @@
 import type { CipherSuite } from '../stream/types.js';
 import type { KyberKeyPair, KyberEncapsulation } from './types.js';
 import type { KyberParams } from './params.js';
-interface MlKemLike {
+export interface MlKemLike {
     readonly params: KyberParams;
     encapsulate(ek: Uint8Array): KyberEncapsulation;
     decapsulate(dk: Uint8Array, c: Uint8Array): Uint8Array;
@@ -10,4 +10,3 @@ interface MlKemLike {
 export declare function KyberSuite(kem: MlKemLike, inner: CipherSuite): CipherSuite & {
     keygen(): KyberKeyPair;
 };
-export {};

package/dist/kyber/suite.js

@@ -52,6 +52,7 @@ export function KyberSuite(kem, inner) {
         kemCtSize: p.ctBytes,
         tagSize: inner.tagSize,
         padded: inner.padded,
+        wasmChunkSize: inner.wasmChunkSize,
         wasmModules: [...inner.wasmModules, 'kyber', 'sha3'],
         deriveKeys(key, nonce, kemCt) {
             let sharedSecret;

package/dist/kyber/types.d.ts

@@ -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;

package/dist/kyber/validate.d.ts

@@ -3,10 +3,14 @@ import type { KyberParams } from './params.js';
 /**
  * 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 declare function checkEncapsulationKey(kx: KyberExports, params: KyberParams, ek: Uint8Array): boolean;
 /**

package/dist/kyber/validate.js

@@ -27,10 +27,14 @@ import { constantTimeEqual } from '../utils.js';
 /**
  * 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)
@@ -38,15 +42,10 @@ export function checkEncapsulationKey(kx, params, ek) {
     const { k } = params;
     const kyberMem = 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);
     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).
@@ -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/loader.d.ts

@@ -8,12 +8,17 @@ export declare function decodeWasm(b64: string): Promise<Uint8Array>;
 /**
  * Compile a WASM source to a Module without instantiating.
  * Used by pool infrastructure to send compiled modules to workers.
+ *
+ * Thenable sources (Promise<Response>, Promise<ArrayBuffer>, etc.) are
+ * resolved and then re-dispatched by the runtime type of the resolved value.
+ * Depth is capped at `MAX_THENABLE_DEPTH` to prevent runaway recursion.
  */
-export declare function compileWasm(source: WasmSource): Promise<WebAssembly.Module>;
+export declare function compileWasm(source: WasmSource, _depth?: number): Promise<WebAssembly.Module>;
 /**
  * Load a WASM module from any accepted source type.
  * The loading strategy is inferred from the argument type — no mode string.
  *
- * Throws `TypeError` for null, numeric, or unrecognised inputs.
+ * Throws `TypeError` for null, numeric, or unrecognised inputs, or if a
+ * thenable source nests deeper than `MAX_THENABLE_DEPTH`.
  */
 export declare function loadWasm(source: WasmSource): Promise<WebAssembly.Instance>;

package/dist/loader.js

@@ -1,8 +1,4 @@
 import { base64ToBytes as _b64 } from './utils.js';
-// Each WASM module gets its own fresh Memory — never shared between instances.
-function makeImports() {
-    return { env: { memory: new WebAssembly.Memory({ initial: 3, maximum: 3 }) } };
-}
 // TS 5.9 generified Uint8Array<TArrayBuffer> with default ArrayBufferLike, which
 // no longer satisfies BufferSource = ArrayBufferView<ArrayBuffer> | ArrayBuffer.
 // Convert Uint8Array to a proper ArrayBuffer before calling WebAssembly APIs.
@@ -22,9 +18,8 @@ export async function decodeWasm(b64) {
     if (typeof DecompressionStream === 'undefined')
         throw new Error('leviathan-crypto: DecompressionStream not available — '
             + 'use a URL, ArrayBuffer, or WebAssembly.Module source in this runtime');
+    // _b64 throws RangeError on invalid base64 — no nullish check required.
     const compressed = _b64(b64);
-    if (!compressed)
-        throw new Error('leviathan-crypto: corrupt embedded WASM — base64 decode failed');
     const ds = new DecompressionStream('gzip');
     const writer = ds.writable.getWriter();
     const reader = ds.readable.getReader();
@@ -44,11 +39,22 @@ export async function decodeWasm(b64) {
     }
     return out;
 }
+// Max thenable nesting depth. A caller can pass `Promise<Response>` or even
+// `Promise<Promise<Response>>` (e.g. deferred fetch wrapped in another async
+// layer), but arbitrary `Promise<Promise<Promise<...>>>` chains would indicate
+// a caller bug — cap at 3 levels and throw a clear error beyond that.
+const MAX_THENABLE_DEPTH = 3;
 /**
  * Compile a WASM source to a Module without instantiating.
  * Used by pool infrastructure to send compiled modules to workers.
+ *
+ * Thenable sources (Promise<Response>, Promise<ArrayBuffer>, etc.) are
+ * resolved and then re-dispatched by the runtime type of the resolved value.
+ * Depth is capped at `MAX_THENABLE_DEPTH` to prevent runaway recursion.
  */
-export async function compileWasm(source) {
+export async function compileWasm(source, _depth = 0) {
+    if (_depth > MAX_THENABLE_DEPTH)
+        throw new TypeError(`leviathan-crypto: thenable nesting too deep (max ${MAX_THENABLE_DEPTH})`);
     if (typeof source === 'string') {
         if (source.length === 0)
             throw new TypeError('leviathan-crypto: invalid WasmSource — empty string');
@@ -64,33 +70,24 @@ export async function compileWasm(source) {
         return source;
     if (typeof Response !== 'undefined' && source instanceof Response)
         return WebAssembly.compileStreaming(source);
-    if (source != null && typeof source.then === 'function')
-        return WebAssembly.compileStreaming(source);
+    if (source != null && typeof source.then === 'function') {
+        const resolved = await source;
+        return compileWasm(resolved, _depth + 1);
+    }
     throw new TypeError(`leviathan-crypto: invalid WasmSource — got ${source === null ? 'null' : typeof source}`);
 }
 /**
  * Load a WASM module from any accepted source type.
  * The loading strategy is inferred from the argument type — no mode string.
  *
- * Throws `TypeError` for null, numeric, or unrecognised inputs.
+ * Throws `TypeError` for null, numeric, or unrecognised inputs, or if a
+ * thenable source nests deeper than `MAX_THENABLE_DEPTH`.
  */
 export async function loadWasm(source) {
-    if (typeof source === 'string') {
-        if (source.length === 0)
-            throw new TypeError('leviathan-crypto: invalid WasmSource — empty string');
-        return (await WebAssembly.instantiate(toArrayBuffer(await decodeWasm(source)), makeImports())).instance;
-    }
-    if (source instanceof URL)
-        return (await WebAssembly.instantiateStreaming(fetch(source.href), makeImports())).instance;
-    if (source instanceof ArrayBuffer)
-        return (await WebAssembly.instantiate(source, makeImports())).instance;
-    if (source instanceof Uint8Array)
-        return (await WebAssembly.instantiate(toArrayBuffer(source), makeImports())).instance;
-    if (source instanceof WebAssembly.Module)
-        return WebAssembly.instantiate(source, makeImports());
-    if (typeof Response !== 'undefined' && source instanceof Response)
-        return (await WebAssembly.instantiateStreaming(source, makeImports())).instance;
-    if (source != null && typeof source.then === 'function')
-        return (await WebAssembly.instantiateStreaming(source, makeImports())).instance;
-    throw new TypeError(`leviathan-crypto: invalid WasmSource — got ${source === null ? 'null' : typeof source}`);
+    // All leviathan-crypto WASM modules export their own memory and import
+    // nothing from the host. If a future module needs imports, they would be
+    // computed and passed here.
+    // compileWasm already handles thenable resolution + depth capping.
+    const mod = await compileWasm(source);
+    return WebAssembly.instantiate(mod);
 }

package/dist/ratchet/index.d.ts

@@ -0,0 +1,6 @@
+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';
+export declare function ratchetReady(): boolean;

package/dist/ratchet/index.js

@@ -0,0 +1,37 @@
+//                  ▄▄▄▄▄▄▄▄▄▄
+//           ▄████████████████████▄▄          ▒  ▄▀▀ ▒ ▒ █ ▄▀▄ ▀█▀ █ ▒ ▄▀▄ █▀▄
+//        ▄██████████████████████ ▀████▄      ▓  ▓▀  ▓ ▓ ▓ ▓▄▓  ▓  ▓▀▓ ▓▄▓ ▓ ▓
+//      ▄█████████▀▀▀     ▀███████▄▄███████▌  ▀▄ ▀▄▄ ▀▄▀ ▒ ▒ ▒  ▒  ▒ █ ▒ ▒ ▒ █
+//     ▐████████▀   ▄▄▄▄     ▀████████▀██▀█▌
+//     ████████      ███▀▀     ████▀  █▀ █▀       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 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;