@psavelis/enterprise-blockchain 0.1.0 → 1.1.1

package/dist/mpc/field.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Finite field arithmetic for Shamir Secret Sharing.
+ *
+ * Two field sizes are supported:
+ * - **Demo mode**: 2^31 - 1 (Mersenne prime, fast, fits in JS Number)
+ * - **Production mode** (default): 2^256 - 2^32 - 977 (secp256k1 order, cryptographically secure)
+ *
+ * WARNING: Demo mode is NOT secure for production use.
+ * The small field allows brute-force enumeration in seconds.
+ * Demo mode is only allowed when NODE_ENV is "development" or "test".
+ *
+ * @see skills/mpc-secret-sharing.md for security guidance
+ * @see docs/adr/ADR-0004-field-arithmetic-for-mpc.md for design rationale
+ */
+/**
+ * Demo field: Mersenne prime 2^31 - 1.
+ * Fast arithmetic, fits in JS safe integer range.
+ * NOT SECURE for production - enumerable in ~seconds on modern hardware.
+ */
+export declare const DEMO_PRIME = 2147483647n;
+/**
+ * Production field: secp256k1 curve order.
+ * 256-bit prime providing 128+ bits of security against enumeration.
+ * Used by Bitcoin, Ethereum, and most production secret sharing implementations.
+ */
+export declare const PRODUCTION_PRIME = 115792089237316195423570985008687907852837564279074904382605163141518161494337n;
+/**
+ * Alternative production field: 2^255 - 19 (Curve25519 prime).
+ * Slightly faster modular reduction due to special form.
+ */
+export declare const CURVE25519_PRIME = 57896044618658097711785492504343953926634992332820282019728792003956564819949n;
+export type FieldMode = "demo" | "production";
+export interface FieldConfig {
+    mode: FieldMode;
+    prime: bigint;
+}
+/**
+ * Get field configuration from environment or explicit parameter.
+ *
+ * Environment variable: MPC_FIELD_MODE ("demo" | "production")
+ * Default: "production" (secure by default)
+ *
+ * Demo mode requires NODE_ENV to be "development" or "test".
+ * This prevents accidental deployment with insecure field size.
+ *
+ * @param mode - Explicit mode override (optional)
+ * @returns Field configuration with prime and mode
+ * @throws Error if demo mode is requested outside dev/test environment
+ */
+export declare function getFieldConfig(mode?: FieldMode): FieldConfig;
+/**
+ * Field arithmetic operations for a given prime.
+ */
+export declare class FieldArithmetic {
+    readonly prime: bigint;
+    readonly mode: FieldMode;
+    constructor(config?: FieldConfig);
+    /**
+     * Modular reduction: ensures result is in [0, prime).
+     */
+    mod(a: bigint): bigint;
+    /**
+     * Modular addition: (a + b) mod prime.
+     */
+    add(a: bigint, b: bigint): bigint;
+    /**
+     * Modular subtraction: (a - b) mod prime.
+     */
+    sub(a: bigint, b: bigint): bigint;
+    /**
+     * Modular multiplication: (a * b) mod prime.
+     */
+    mul(a: bigint, b: bigint): bigint;
+    /**
+     * Modular exponentiation: base^exp mod prime.
+     * Uses square-and-multiply for O(log exp) complexity.
+     */
+    pow(base: bigint, exp: bigint): bigint;
+    /**
+     * Modular multiplicative inverse: a^(-1) mod prime.
+     * Uses Fermat's little theorem: a^(-1) = a^(p-2) mod p.
+     */
+    inverse(a: bigint): bigint;
+    /**
+     * Modular division: a / b mod prime = a * b^(-1) mod prime.
+     */
+    div(a: bigint, b: bigint): bigint;
+    /**
+     * Generate a random field element in [1, prime).
+     * Uses cryptographically secure random bytes.
+     */
+    random(): bigint;
+    /**
+     * Convert a number to a field element.
+     * Throws if the number is outside the valid range.
+     */
+    fromNumber(n: number): bigint;
+    /**
+     * Convert a field element to a number.
+     * Throws if the value exceeds JS safe integer range.
+     */
+    toNumber(value: bigint): number;
+    /**
+     * Check if this is a production-grade field.
+     */
+    isProductionSecure(): boolean;
+    /**
+     * Get the security level in bits.
+     * Demo mode: ~31 bits (insecure)
+     * Production mode: ~128 bits (secure)
+     */
+    getSecurityBits(): number;
+}
+/**
+ * Production field singleton for common use cases.
+ * This is the recommended default for all production code.
+ */
+export declare const productionField: FieldArithmetic;
+/**
+ * Demo field singleton - INTERNAL USE ONLY.
+ * Not exported to prevent accidental use in production code.
+ * Use `new FieldArithmetic({ mode: "demo", prime: DEMO_PRIME })` explicitly
+ * in development/test contexts only.
+ */
+declare const _demoField: FieldArithmetic;
+export { _demoField as demoField };
+//# sourceMappingURL=field.d.ts.map

package/dist/mpc/field.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"field.d.ts","sourceRoot":"","sources":["../../src/mpc/field.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH;;;;GAIG;AACH,eAAO,MAAM,UAAU,cAAiB,CAAC;AAEzC;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,kFACwC,CAAC;AAEtE;;;GAGG;AACH,eAAO,MAAM,gBAAgB,iFACwC,CAAC;AAEtE,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,YAAY,CAAC;AAE9C,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,IAAI,CAAC,EAAE,SAAS,GAAG,WAAW,CA+B5D;AAED;;GAEG;AACH,qBAAa,eAAe;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;gBAEb,MAAM,GAAE,WAA8B;IAKlD;;OAEG;IACH,GAAG,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM;IAItB;;OAEG;IACH,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM;IAIjC;;OAEG;IACH,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM;IAIjC;;OAEG;IACH,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM;IAIjC;;;OAGG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM;IAetC;;;OAGG;IACH,OAAO,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM;IAO1B;;OAEG;IACH,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM;IAIjC;;;OAGG;IACH,MAAM,IAAI,MAAM;IAchB;;;OAGG;IACH,UAAU,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM;IAa7B;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAU/B;;OAEG;IACH,kBAAkB,IAAI,OAAO;IAI7B;;;;OAIG;IACH,eAAe,IAAI,MAAM;CAG1B;AAED;;;GAGG;AACH,eAAO,MAAM,eAAe,iBAG1B,CAAC;AAEH;;;;;GAKG;AACH,QAAA,MAAM,UAAU,iBAGd,CAAC;AAGH,OAAO,EAAE,UAAU,IAAI,SAAS,EAAE,CAAC"}

package/dist/mpc/field.js

@@ -0,0 +1,209 @@
+/**
+ * Finite field arithmetic for Shamir Secret Sharing.
+ *
+ * Two field sizes are supported:
+ * - **Demo mode**: 2^31 - 1 (Mersenne prime, fast, fits in JS Number)
+ * - **Production mode** (default): 2^256 - 2^32 - 977 (secp256k1 order, cryptographically secure)
+ *
+ * WARNING: Demo mode is NOT secure for production use.
+ * The small field allows brute-force enumeration in seconds.
+ * Demo mode is only allowed when NODE_ENV is "development" or "test".
+ *
+ * @see skills/mpc-secret-sharing.md for security guidance
+ * @see docs/adr/ADR-0004-field-arithmetic-for-mpc.md for design rationale
+ */
+import { randomBytes } from "node:crypto";
+/**
+ * Demo field: Mersenne prime 2^31 - 1.
+ * Fast arithmetic, fits in JS safe integer range.
+ * NOT SECURE for production - enumerable in ~seconds on modern hardware.
+ */
+export const DEMO_PRIME = 2147483647n;
+/**
+ * Production field: secp256k1 curve order.
+ * 256-bit prime providing 128+ bits of security against enumeration.
+ * Used by Bitcoin, Ethereum, and most production secret sharing implementations.
+ */
+export const PRODUCTION_PRIME = 0xfffffffffffffffffffffffffffffffebaaedce6af48a03bbfd25e8cd0364141n;
+/**
+ * Alternative production field: 2^255 - 19 (Curve25519 prime).
+ * Slightly faster modular reduction due to special form.
+ */
+export const CURVE25519_PRIME = 0x7fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffedn;
+/**
+ * Get field configuration from environment or explicit parameter.
+ *
+ * Environment variable: MPC_FIELD_MODE ("demo" | "production")
+ * Default: "production" (secure by default)
+ *
+ * Demo mode requires NODE_ENV to be "development" or "test".
+ * This prevents accidental deployment with insecure field size.
+ *
+ * @param mode - Explicit mode override (optional)
+ * @returns Field configuration with prime and mode
+ * @throws Error if demo mode is requested outside dev/test environment
+ */
+export function getFieldConfig(mode) {
+    const envMode = process.env.MPC_FIELD_MODE;
+    const rawMode = mode ?? envMode ?? "production";
+    // Validate the mode is one of the allowed values
+    if (rawMode !== "demo" && rawMode !== "production") {
+        throw new Error(`Invalid MPC_FIELD_MODE: "${rawMode}". Use "demo" or "production".`);
+    }
+    const effectiveMode = rawMode;
+    const nodeEnv = process.env.NODE_ENV;
+    const isDevelopment = nodeEnv === "development" || nodeEnv === "test";
+    // SECURITY: Demo mode is ONLY allowed when NODE_ENV is explicitly
+    // set to "development" or "test". No bypass or override is permitted.
+    // This prevents accidental deployment with insecure field size.
+    if (effectiveMode === "demo" && !isDevelopment) {
+        throw new Error("SECURITY ERROR: Demo field mode is only allowed when NODE_ENV is " +
+            "'development' or 'test'. Set NODE_ENV appropriately for local " +
+            "development, or set MPC_FIELD_MODE=production for cryptographic security.");
+    }
+    return {
+        mode: effectiveMode,
+        prime: effectiveMode === "production" ? PRODUCTION_PRIME : DEMO_PRIME,
+    };
+}
+/**
+ * Field arithmetic operations for a given prime.
+ */
+export class FieldArithmetic {
+    prime;
+    mode;
+    constructor(config = getFieldConfig()) {
+        this.prime = config.prime;
+        this.mode = config.mode;
+    }
+    /**
+     * Modular reduction: ensures result is in [0, prime).
+     */
+    mod(a) {
+        return ((a % this.prime) + this.prime) % this.prime;
+    }
+    /**
+     * Modular addition: (a + b) mod prime.
+     */
+    add(a, b) {
+        return this.mod(a + b);
+    }
+    /**
+     * Modular subtraction: (a - b) mod prime.
+     */
+    sub(a, b) {
+        return this.mod(a - b);
+    }
+    /**
+     * Modular multiplication: (a * b) mod prime.
+     */
+    mul(a, b) {
+        return this.mod(a * b);
+    }
+    /**
+     * Modular exponentiation: base^exp mod prime.
+     * Uses square-and-multiply for O(log exp) complexity.
+     */
+    pow(base, exp) {
+        let result = 1n;
+        base = this.mod(base);
+        while (exp > 0n) {
+            if (exp & 1n) {
+                result = this.mod(result * base);
+            }
+            exp >>= 1n;
+            base = this.mod(base * base);
+        }
+        return result;
+    }
+    /**
+     * Modular multiplicative inverse: a^(-1) mod prime.
+     * Uses Fermat's little theorem: a^(-1) = a^(p-2) mod p.
+     */
+    inverse(a) {
+        if (this.mod(a) === 0n) {
+            throw new Error("Cannot compute inverse of zero");
+        }
+        return this.pow(a, this.prime - 2n);
+    }
+    /**
+     * Modular division: a / b mod prime = a * b^(-1) mod prime.
+     */
+    div(a, b) {
+        return this.mul(a, this.inverse(b));
+    }
+    /**
+     * Generate a random field element in [1, prime).
+     * Uses cryptographically secure random bytes.
+     */
+    random() {
+        // Generate enough bytes to cover the prime
+        const byteLength = Math.ceil(this.prime.toString(2).length / 8);
+        let value;
+        // Rejection sampling to ensure uniform distribution
+        do {
+            const bytes = randomBytes(byteLength);
+            value = BigInt("0x" + bytes.toString("hex"));
+        } while (value >= this.prime || value === 0n);
+        return value;
+    }
+    /**
+     * Convert a number to a field element.
+     * Throws if the number is outside the valid range.
+     */
+    fromNumber(n) {
+        if (!Number.isInteger(n) || n < 0) {
+            throw new Error("Field element must be a non-negative integer");
+        }
+        const value = BigInt(n);
+        if (value >= this.prime) {
+            throw new Error(`Value ${n} exceeds field prime ${this.prime}`);
+        }
+        return value;
+    }
+    /**
+     * Convert a field element to a number.
+     * Throws if the value exceeds JS safe integer range.
+     */
+    toNumber(value) {
+        if (value > BigInt(Number.MAX_SAFE_INTEGER)) {
+            throw new Error(`Field element ${value} exceeds JS safe integer range. ` +
+                `Use bigint operations directly for production field.`);
+        }
+        return Number(value);
+    }
+    /**
+     * Check if this is a production-grade field.
+     */
+    isProductionSecure() {
+        return this.mode === "production";
+    }
+    /**
+     * Get the security level in bits.
+     * Demo mode: ~31 bits (insecure)
+     * Production mode: ~128 bits (secure)
+     */
+    getSecurityBits() {
+        return this.mode === "production" ? 128 : 31;
+    }
+}
+/**
+ * Production field singleton for common use cases.
+ * This is the recommended default for all production code.
+ */
+export const productionField = new FieldArithmetic({
+    mode: "production",
+    prime: PRODUCTION_PRIME,
+});
+/**
+ * Demo field singleton - INTERNAL USE ONLY.
+ * Not exported to prevent accidental use in production code.
+ * Use `new FieldArithmetic({ mode: "demo", prime: DEMO_PRIME })` explicitly
+ * in development/test contexts only.
+ */
+const _demoField = new FieldArithmetic({
+    mode: "demo",
+    prime: DEMO_PRIME,
+});
+// Export for internal test usage only (not re-exported from index.ts)
+export { _demoField as demoField };

package/dist/mpc/hybrid-kem.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Hybrid KEM — X25519 + ML-KEM-768
+ *
+ * Why hybrid instead of ML-KEM alone?
+ *
+ * We are in a cryptographic transition period.  CRQCs capable of running
+ * Shor's algorithm at scale do not yet exist, but quantum-safe algorithms are
+ * newer and have had less time for public cryptanalysis than well-established
+ * classical schemes.
+ *
+ * A hybrid KEM addresses both risks simultaneously:
+ *   1. Classical channel (X25519) — secure against all known classical attacks
+ *   2. Post-quantum channel (ML-KEM-768) — secure against quantum adversaries
+ *
+ * Both shared secrets are fed into HKDF together, so breaking the combined
+ * key requires breaking *both* channels.  This matches how Chrome, Firefox, and
+ * Cloudflare deployed post-quantum TLS during the 2023–2024 transition
+ * (Google's X25519Kyber768 experiment: https://blog.chromium.org/2023/08/protecting-chrome-traffic-with-hybrid.html).
+ *
+ * The construction used here follows the approach described in:
+ * IETF draft-ietf-tls-hybrid-design — https://datatracker.ietf.org/doc/draft-ietf-tls-hybrid-design/
+ *
+ * Standard for the PQ half: NIST FIPS 203 — https://csrc.nist.gov/pubs/fips/203/final
+ */
+import type { KeyObject } from "node:crypto";
+import type { KyberKeyPair } from "./kyber.js";
+export interface HybridKeyPairs {
+    /** Ephemeral X25519 key pair (classical channel). */
+    x25519: {
+        publicKey: KeyObject;
+        privateKey: KeyObject;
+    };
+    /** ML-KEM-768 key pair (post-quantum channel). */
+    kyber: KyberKeyPair;
+}
+export interface HybridEncapsulation {
+    /**
+     * X25519 ephemeral public key in DER format.
+     * The recipient uses this together with their X25519 private key to
+     * reproduce the classical shared secret.
+     */
+    x25519EphemeralPublicKeyDer: Buffer;
+    /** ML-KEM-768 ciphertext (post-quantum channel). */
+    kyberCiphertext: Uint8Array;
+    /**
+     * The combined symmetric key derived from both channels.
+     * 32 bytes — ready for use as an AES-256-GCM key.
+     * Do not transmit; derive it independently on each side.
+     */
+    combinedKey: Buffer;
+    /**
+     * SHA-256 of the concatenated hex encodings for auditing.
+     *
+     * Computed as: sha256hex(ephemeralPubDer.toString("hex") + kyberCiphertext.toString("hex"))
+     *
+     * This hashes the hex-encoded string concatenation, not the raw bytes.
+     * Suitable for on-chain commitments or audit logs.
+     */
+    auditCommitment: string;
+}
+export interface HybridDecapsulation {
+    combinedKey: Buffer;
+}
+export declare class HybridKem {
+    #private;
+    /**
+     * Generate a fresh set of long-term recipient key pairs (one per channel).
+     *
+     * In production the X25519 and ML-KEM keys would live in separate HSM slots
+     * and be rotated on independent schedules.  Here we generate both for
+     * demonstration purposes.
+     */
+    generateKeyPairs(): HybridKeyPairs;
+    /**
+     * Sender-side encapsulation.
+     *
+     * 1. Generate an ephemeral X25519 keypair and perform DH with the
+     *    recipient's X25519 public key to get the classical shared secret.
+     * 2. Encapsulate a fresh shared secret under the recipient's ML-KEM-768
+     *    public key.
+     * 3. Feed both shared secrets into HKDF together to produce one combined
+     *    symmetric key.
+     *
+     * Only `x25519EphemeralPublicKeyDer` and `kyberCiphertext` are transmitted.
+     * The `combinedKey` stays local and is used for encryption.
+     */
+    encapsulate(recipientX25519PublicKey: KeyObject, recipientKyberPublicKey: Uint8Array): HybridEncapsulation;
+    /**
+     * Receiver-side decapsulation.
+     *
+     * Reproduces the same `combinedKey` as the sender using the two received
+     * ciphertexts and the recipient's secret keys.
+     */
+    decapsulate(recipientX25519PrivateKey: KeyObject, recipientKyberSecretKey: Uint8Array, x25519EphemeralPublicKeyDer: Buffer, kyberCiphertext: Uint8Array): HybridDecapsulation;
+}
+//# sourceMappingURL=hybrid-kem.d.ts.map

package/dist/mpc/hybrid-kem.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hybrid-kem.d.ts","sourceRoot":"","sources":["../../src/mpc/hybrid-kem.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AASH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAK7C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAM/C,MAAM,WAAW,cAAc;IAC7B,qDAAqD;IACrD,MAAM,EAAE;QACN,SAAS,EAAE,SAAS,CAAC;QACrB,UAAU,EAAE,SAAS,CAAC;KACvB,CAAC;IACF,kDAAkD;IAClD,KAAK,EAAE,YAAY,CAAC;CACrB;AAED,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,2BAA2B,EAAE,MAAM,CAAC;IACpC,oDAAoD;IACpD,eAAe,EAAE,UAAU,CAAC;IAC5B;;;;OAIG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;;;OAOG;IACH,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,MAAM,CAAC;CACrB;AAMD,qBAAa,SAAS;;IACpB;;;;;;OAMG;IACH,gBAAgB,IAAI,cAAc;IASlC;;;;;;;;;;;;OAYG;IACH,WAAW,CACT,wBAAwB,EAAE,SAAS,EACnC,uBAAuB,EAAE,UAAU,GAClC,mBAAmB;IAuCtB;;;;;OAKG;IACH,WAAW,CACT,yBAAyB,EAAE,SAAS,EACpC,uBAAuB,EAAE,UAAU,EACnC,2BAA2B,EAAE,MAAM,EACnC,eAAe,EAAE,UAAU,GAC1B,mBAAmB;CAqDvB"}

package/dist/mpc/hybrid-kem.js

@@ -0,0 +1,136 @@
+/**
+ * Hybrid KEM — X25519 + ML-KEM-768
+ *
+ * Why hybrid instead of ML-KEM alone?
+ *
+ * We are in a cryptographic transition period.  CRQCs capable of running
+ * Shor's algorithm at scale do not yet exist, but quantum-safe algorithms are
+ * newer and have had less time for public cryptanalysis than well-established
+ * classical schemes.
+ *
+ * A hybrid KEM addresses both risks simultaneously:
+ *   1. Classical channel (X25519) — secure against all known classical attacks
+ *   2. Post-quantum channel (ML-KEM-768) — secure against quantum adversaries
+ *
+ * Both shared secrets are fed into HKDF together, so breaking the combined
+ * key requires breaking *both* channels.  This matches how Chrome, Firefox, and
+ * Cloudflare deployed post-quantum TLS during the 2023–2024 transition
+ * (Google's X25519Kyber768 experiment: https://blog.chromium.org/2023/08/protecting-chrome-traffic-with-hybrid.html).
+ *
+ * The construction used here follows the approach described in:
+ * IETF draft-ietf-tls-hybrid-design — https://datatracker.ietf.org/doc/draft-ietf-tls-hybrid-design/
+ *
+ * Standard for the PQ half: NIST FIPS 203 — https://csrc.nist.gov/pubs/fips/203/final
+ */
+var _a;
+import { createPublicKey, diffieHellman, generateKeyPairSync, hkdfSync, createHash, } from "node:crypto";
+import { ml_kem768 } from "@noble/post-quantum/ml-kem.js";
+import { sha256hex } from "./crypto.js";
+// ---------------------------------------------------------------------------
+// HybridKem class
+// ---------------------------------------------------------------------------
+export class HybridKem {
+    /**
+     * Generate a fresh set of long-term recipient key pairs (one per channel).
+     *
+     * In production the X25519 and ML-KEM keys would live in separate HSM slots
+     * and be rotated on independent schedules.  Here we generate both for
+     * demonstration purposes.
+     */
+    generateKeyPairs() {
+        const { publicKey, privateKey } = generateKeyPairSync("x25519");
+        const { publicKey: kyberPub, secretKey: kyberSec } = ml_kem768.keygen();
+        return {
+            x25519: { publicKey, privateKey },
+            kyber: { publicKey: kyberPub, secretKey: kyberSec, params: "ml-kem-768" },
+        };
+    }
+    /**
+     * Sender-side encapsulation.
+     *
+     * 1. Generate an ephemeral X25519 keypair and perform DH with the
+     *    recipient's X25519 public key to get the classical shared secret.
+     * 2. Encapsulate a fresh shared secret under the recipient's ML-KEM-768
+     *    public key.
+     * 3. Feed both shared secrets into HKDF together to produce one combined
+     *    symmetric key.
+     *
+     * Only `x25519EphemeralPublicKeyDer` and `kyberCiphertext` are transmitted.
+     * The `combinedKey` stays local and is used for encryption.
+     */
+    encapsulate(recipientX25519PublicKey, recipientKyberPublicKey) {
+        // --- Classical channel ---
+        const { privateKey: ephemeralPriv, publicKey: ephemeralPub } = generateKeyPairSync("x25519");
+        const x25519SharedSecret = diffieHellman({
+            privateKey: ephemeralPriv,
+            publicKey: recipientX25519PublicKey,
+        });
+        // --- Post-quantum channel ---
+        const { cipherText: kyberCiphertext, sharedSecret: kyberSharedSecret } = ml_kem768.encapsulate(recipientKyberPublicKey);
+        // --- Combine both secrets via HKDF ---
+        // Concatenating before HKDF means neither secret dominates — both must be
+        // known to derive the output.  The domain-separator label prevents the
+        // same key material being reused in a different context.
+        const combinedKey = this.#combineSecrets(x25519SharedSecret, kyberSharedSecret);
+        const ephemeralPubDer = Buffer.from(ephemeralPub.export({ type: "spki", format: "der" }));
+        const auditCommitment = sha256hex(ephemeralPubDer.toString("hex") +
+            Buffer.from(kyberCiphertext).toString("hex"));
+        return {
+            x25519EphemeralPublicKeyDer: ephemeralPubDer,
+            kyberCiphertext,
+            combinedKey,
+            auditCommitment,
+        };
+    }
+    /**
+     * Receiver-side decapsulation.
+     *
+     * Reproduces the same `combinedKey` as the sender using the two received
+     * ciphertexts and the recipient's secret keys.
+     */
+    decapsulate(recipientX25519PrivateKey, recipientKyberSecretKey, x25519EphemeralPublicKeyDer, kyberCiphertext) {
+        // --- Classical channel ---
+        // Re-import the sender's ephemeral public key from the wire format
+        const ephemeralPub = createPublicKeyFromDer(x25519EphemeralPublicKeyDer);
+        const x25519SharedSecret = diffieHellman({
+            privateKey: recipientX25519PrivateKey,
+            publicKey: ephemeralPub,
+        });
+        // --- Post-quantum channel ---
+        const kyberSharedSecret = ml_kem768.decapsulate(kyberCiphertext, recipientKyberSecretKey);
+        // --- Combine both secrets (same steps as sender) ---
+        const combinedKey = this.#combineSecrets(x25519SharedSecret, kyberSharedSecret);
+        return { combinedKey };
+    }
+    // ---------------------------------------------------------------------------
+    // Helpers
+    // ---------------------------------------------------------------------------
+    /**
+     * Domain-specific salt for HKDF key derivation.
+     * Per RFC 5869, salt provides additional entropy for the extraction step.
+     * Using SHA-256 of domain string ensures cryptographic binding to this context.
+     */
+    static #HKDF_SALT = createHash("sha256")
+        .update("enterprise-blockchain:hybrid-kem-v1:salt")
+        .digest();
+    /**
+     * Derive a single 32-byte key from two independent shared secrets using
+     * HKDF-SHA256.  The label "hybrid-kem-v1" acts as a domain separator.
+     */
+    #combineSecrets(x25519Secret, kyberSecret) {
+        const ikm = Buffer.concat([x25519Secret, Buffer.from(kyberSecret)]);
+        return Buffer.from(hkdfSync("sha256", ikm, _a.#HKDF_SALT, Buffer.from("hybrid-kem-v1", "utf8"), 32));
+    }
+}
+_a = HybridKem;
+// ---------------------------------------------------------------------------
+// Internal utility
+// ---------------------------------------------------------------------------
+/**
+ * Reconstruct an X25519 public key from a SPKI DER buffer received over the
+ * wire.  Node.js's `createPublicKey` accepts the `der` + `type: 'spki'`
+ * combination for all standard curve families including X25519.
+ */
+function createPublicKeyFromDer(der) {
+    return createPublicKey({ key: der, format: "der", type: "spki" });
+}