@omnituum/pqc-shared 0.4.0 → 0.6.0

package/dist/crypto/index.cjs

@@ -201,6 +201,11 @@ function deriveKeyFromShared(shared, salt, info) {
   return hkdfSha256(shared, { salt: u8(salt), info: u8(info), length: 32 });
 }
 var KYBER_SUITE = "ML-KEM-1024-FIPS203";
+var KYBER_PUBLIC_KEY_SIZE = 1568;
+var KYBER_SECRET_KEY_SIZE = 3168;
+var KYBER_CIPHERTEXT_SIZE = 1568;
+var KYBER_SHARED_SECRET_SIZE = 32;
+var KYBER_SEED_SIZE = 64;
 async function isKyberAvailable() {
   return true;
 }
@@ -256,8 +261,7 @@ async function loadDilithium() {
     const { ml_dsa65 } = await import('@noble/post-quantum/ml-dsa.js');
     dilithiumModule = ml_dsa65;
     return dilithiumModule;
-  } catch (e) {
-    console.warn("[Dilithium] Failed to load @noble/post-quantum:", e);
+  } catch {
     return null;
   }
 }
@@ -275,8 +279,7 @@ async function generateDilithiumKeypair() {
       publicB64: toB64(kp.publicKey),
       secretB64: toB64(kp.secretKey)
     };
-  } catch (e) {
-    console.warn("[Dilithium] Key generation failed:", e);
+  } catch {
     return null;
   }
 }
@@ -345,11 +348,13 @@ var DILITHIUM_SECRET_KEY_SIZE = 4032;
 var DILITHIUM_SIGNATURE_SIZE = 3309;
 var DILITHIUM_ALGORITHM = "ML-DSA-65";
 var ENVELOPE_VERSION = envelopeRegistry.OMNI_VERSIONS.HYBRID_V1;
+var ENVELOPE_VERSION_V2 = envelopeRegistry.OMNI_VERSIONS.HYBRID_V2;
 var ENVELOPE_VERSION_LEGACY = envelopeRegistry.DEPRECATED_VERSIONS.PQC_DEMO_HYBRID_V1;
-var ENVELOPE_SUITE = "x25519+kyber768";
+var ENVELOPE_SUITE_V2 = "x25519+mlkem1024";
 var ENVELOPE_AEAD = "xsalsa20poly1305";
 var SUPPORTED_ENVELOPE_VERSIONS = [
   ENVELOPE_VERSION,
+  ENVELOPE_VERSION_V2,
   ENVELOPE_VERSION_LEGACY
 ];
 var VersionMismatchError = class extends Error {
@@ -381,7 +386,6 @@ async function generateHybridIdentity(name) {
   const x25519 = generateX25519Keypair();
   const kyber = await generateKyberKeypair();
   if (!kyber) {
-    console.error("Kyber key generation failed - library not available");
     return null;
   }
   return {
@@ -423,49 +427,74 @@ function getSecretKeys(identity) {
     kyberSecB64: identity.kyberSecB64
   };
 }
+function combinedKekV2(kyberShared, x25519Shared, x25519EpkHex, kyberKemCtB64) {
+  const ikm = new Uint8Array(kyberShared.length + x25519Shared.length);
+  ikm.set(kyberShared, 0);
+  ikm.set(x25519Shared, kyberShared.length);
+  try {
+    return hkdfFlex(ikm, "omnituum/hybrid-v2", `wrap-ck|${x25519EpkHex}|${kyberKemCtB64}`);
+  } finally {
+    ikm.fill(0);
+  }
+}
 async function hybridEncrypt(plaintext, recipientPublicKeys, sender) {
   const pt = typeof plaintext === "string" ? textEncoder.encode(plaintext) : plaintext;
   const CK = rand32();
-  const contentNonce = rand24();
-  const ciphertext = nacl__default.default.secretbox(pt, contentNonce, CK);
-  const x25519EphKp = nacl__default.default.box.keyPair();
-  const recipientX25519Pk = fromHex(recipientPublicKeys.x25519PubHex);
-  const x25519Shared = nacl__default.default.scalarMult(x25519EphKp.secretKey, recipientX25519Pk);
-  const x25519Kek = hkdfFlex(x25519Shared, "omnituum/x25519", "wrap-ck");
-  const x25519WrapNonce = rand24();
-  const x25519Wrapped = nacl__default.default.secretbox(CK, x25519WrapNonce, x25519Kek);
-  const kyberResult = await kyberEncapsulate(recipientPublicKeys.kyberPubB64);
-  const kyberKek = hkdfFlex(kyberResult.sharedSecret, "omnituum/kyber", "wrap-ck");
-  const kyberWrapNonce = rand24();
-  const kyberWrapped = nacl__default.default.secretbox(CK, kyberWrapNonce, kyberKek);
-  return {
-    v: ENVELOPE_VERSION,
-    suite: ENVELOPE_SUITE,
-    aead: ENVELOPE_AEAD,
-    x25519Epk: toHex(x25519EphKp.publicKey),
-    x25519Wrap: {
-      nonce: b64(x25519WrapNonce),
-      wrapped: b64(x25519Wrapped)
-    },
-    kyberKemCt: b64(kyberResult.ciphertext),
-    kyberWrap: {
-      nonce: b64(kyberWrapNonce),
-      wrapped: b64(kyberWrapped)
-    },
-    contentNonce: b64(contentNonce),
-    ciphertext: b64(ciphertext),
-    meta: {
-      createdAt: (/* @__PURE__ */ new Date()).toISOString(),
-      senderName: sender?.name,
-      senderId: sender?.id
-    }
-  };
+  try {
+    const contentNonce = rand24();
+    const ciphertext = nacl__default.default.secretbox(pt, contentNonce, CK);
+    const x25519EphKp = nacl__default.default.box.keyPair();
+    const recipientX25519Pk = fromHex(recipientPublicKeys.x25519PubHex);
+    const x25519Shared = nacl__default.default.scalarMult(x25519EphKp.secretKey, recipientX25519Pk);
+    const x25519EpkHex = toHex(x25519EphKp.publicKey);
+    const kyberResult = await kyberEncapsulate(recipientPublicKeys.kyberPubB64);
+    const kyberKemCtB64 = b64(kyberResult.ciphertext);
+    const kek = combinedKekV2(kyberResult.sharedSecret, x25519Shared, x25519EpkHex, kyberKemCtB64);
+    const ckWrapNonce = rand24();
+    const ckWrapped = nacl__default.default.secretbox(CK, ckWrapNonce, kek);
+    kek.fill(0);
+    x25519Shared.fill(0);
+    kyberResult.sharedSecret.fill(0);
+    x25519EphKp.secretKey.fill(0);
+    return {
+      v: ENVELOPE_VERSION_V2,
+      suite: ENVELOPE_SUITE_V2,
+      aead: ENVELOPE_AEAD,
+      x25519Epk: x25519EpkHex,
+      kyberKemCt: kyberKemCtB64,
+      ckWrap: {
+        nonce: b64(ckWrapNonce),
+        wrapped: b64(ckWrapped)
+      },
+      contentNonce: b64(contentNonce),
+      ciphertext: b64(ciphertext),
+      meta: {
+        createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+        senderName: sender?.name,
+        senderId: sender?.id
+      }
+    };
+  } finally {
+    CK.fill(0);
+  }
+}
+async function unwrapCkV2(envelope, secretKeys) {
+  const kyberShared = await kyberDecapsulate(envelope.kyberKemCt, secretKeys.kyberSecB64);
+  const ephPk = fromHex(envelope.x25519Epk);
+  const sk = fromHex(secretKeys.x25519SecHex);
+  const x25519Shared = nacl__default.default.scalarMult(sk, ephPk);
+  const kek = combinedKekV2(kyberShared, x25519Shared, envelope.x25519Epk, envelope.kyberKemCt);
+  kyberShared.fill(0);
+  x25519Shared.fill(0);
+  const CK = nacl__default.default.secretbox.open(ub64(envelope.ckWrap.wrapped), ub64(envelope.ckWrap.nonce), kek);
+  kek.fill(0);
+  if (!CK) {
+    throw new Error("Could not unwrap content key \u2014 combined-KEK authentication failed");
+  }
+  return CK;
 }
-async function hybridDecrypt(envelope, secretKeys) {
-  const version = envelope.v;
-  assertEnvelopeVersion(version);
+async function unwrapCkV1(envelope, secretKeys, saltPrefix) {
   let CK = null;
-  const saltPrefix = version === "pqc-demo.hybrid.v1" ? "pqc-demo" : "omnituum";
   try {
     const kyberShared = await kyberDecapsulate(envelope.kyberKemCt, secretKeys.kyberSecB64);
     const kyberKek = hkdfFlex(kyberShared, `${saltPrefix}/kyber`, "wrap-ck");
@@ -474,11 +503,7 @@ async function hybridDecrypt(envelope, secretKeys) {
       ub64(envelope.kyberWrap.nonce),
       kyberKek
     );
-    if (CK) {
-      console.log("[Hybrid] Decrypted using Kyber (post-quantum)");
-    }
-  } catch (e) {
-    console.warn("[Hybrid] Kyber decapsulation failed:", e);
+  } catch {
   }
   if (!CK) {
     try {
@@ -491,21 +516,28 @@ async function hybridDecrypt(envelope, secretKeys) {
         ub64(envelope.x25519Wrap.nonce),
         x25519Kek
       );
-      if (CK) {
-        console.log("[Hybrid] Decrypted using X25519 (classical)");
-      }
-    } catch (e) {
-      console.warn("[Hybrid] X25519 decryption failed:", e);
+    } catch {
     }
   }
   if (!CK) {
     throw new Error("Could not unwrap content key with either algorithm");
   }
+  return CK;
+}
+async function hybridDecrypt(envelope, secretKeys) {
+  const version = envelope.v;
+  assertEnvelopeVersion(version);
+  const CK = version === ENVELOPE_VERSION_V2 ? await unwrapCkV2(envelope, secretKeys) : await unwrapCkV1(
+    envelope,
+    secretKeys,
+    version === "pqc-demo.hybrid.v1" ? "pqc-demo" : "omnituum"
+  );
   const pt = nacl__default.default.secretbox.open(
     ub64(envelope.ciphertext),
     ub64(envelope.contentNonce),
     CK
   );
+  CK.fill(0);
   if (!pt) {
     throw new Error("Content authentication failed");
   }
@@ -689,6 +721,11 @@ exports.HKDF_SHA256_MAX_OUTPUT = HKDF_SHA256_MAX_OUTPUT;
 exports.HKDF_SHA256_OUTPUT_SIZE = HKDF_SHA256_OUTPUT_SIZE;
 exports.HKDF_SHA512_MAX_OUTPUT = HKDF_SHA512_MAX_OUTPUT;
 exports.HKDF_SHA512_OUTPUT_SIZE = HKDF_SHA512_OUTPUT_SIZE;
+exports.KYBER_CIPHERTEXT_SIZE = KYBER_CIPHERTEXT_SIZE;
+exports.KYBER_PUBLIC_KEY_SIZE = KYBER_PUBLIC_KEY_SIZE;
+exports.KYBER_SECRET_KEY_SIZE = KYBER_SECRET_KEY_SIZE;
+exports.KYBER_SEED_SIZE = KYBER_SEED_SIZE;
+exports.KYBER_SHARED_SECRET_SIZE = KYBER_SHARED_SECRET_SIZE;
 exports.KYBER_SUITE = KYBER_SUITE;
 exports.POLY1305_TAG_SIZE = POLY1305_TAG_SIZE;
 exports.SECRETBOX_KEY_SIZE = SECRETBOX_KEY_SIZE;

package/dist/crypto/index.d.cts

@@ -1,4 +1,4 @@
-import { OmniHybridV1 } from '@omnituum/envelope-registry';
+import { OmniHybridV2, OmniHybridV1 } from '@omnituum/envelope-registry';
 import * as _noble_ciphers_utils_js from '@noble/ciphers/utils.js';
 
 /**
@@ -35,6 +35,16 @@ interface KyberEncapsulation {
 /** Canonical suite identifier for new material produced by this package. */
 declare const KYBER_SUITE: "ML-KEM-1024-FIPS203";
 type KyberSuite = typeof KYBER_SUITE;
+/** ML-KEM-1024 public key size (bytes). */
+declare const KYBER_PUBLIC_KEY_SIZE = 1568;
+/** ML-KEM-1024 secret key size (bytes). */
+declare const KYBER_SECRET_KEY_SIZE = 3168;
+/** ML-KEM-1024 ciphertext size (bytes). */
+declare const KYBER_CIPHERTEXT_SIZE = 1568;
+/** ML-KEM-1024 shared-secret size (bytes). */
+declare const KYBER_SHARED_SECRET_SIZE = 32;
+/** Seed size accepted by `generateKyberKeypairFromSeed` (bytes). */
+declare const KYBER_SEED_SIZE = 64;
 /**
  * @deprecated Always returns true. Retained for API stability across the
  * 0.3.x → 0.4.x cut. The noble backend is statically imported and always
@@ -67,10 +77,16 @@ declare function kyberUnwrapKey(sharedSecret: Uint8Array, nonceB64: string, wrap
  *
  * Post-quantum secure hybrid encryption combining:
  * - X25519 ECDH (classical, proven security)
- * - Kyber ML-KEM-768 (post-quantum, NIST Level 3)
+ * - ML-KEM-1024 (post-quantum, FIPS 203, NIST Level 5)
  *
- * Both key exchanges must succeed for decryption, providing
- * security against both classical and quantum attacks.
+ * v2 (current write format): the content key is wrapped once, under a KEK
+ * derived from BOTH shared secrets (HKDF(ss_mlkem || ss_x25519) with
+ * transcript binding) — both key exchanges must succeed to decrypt, so
+ * breaking either primitive alone is insufficient.
+ *
+ * v1 (read-only legacy): wrapped the key independently under each
+ * primitive; either secret alone sufficed. Kept only for decrypting
+ * existing envelopes — see the 2026-07-05 security audit.
  */
 
 interface HybridIdentity {
@@ -106,12 +122,21 @@ interface HybridSecretKeys {
     kyberSecB64: string;
 }
 
-type HybridEnvelope = Omit<OmniHybridV1, 'meta'> & {
+type HybridEnvelopeV1 = Omit<OmniHybridV1, 'meta'> & {
     meta: OmniHybridV1['meta'] & {
         senderName?: string;
         senderId?: string;
     };
 };
+
+type HybridEnvelopeV2 = Omit<OmniHybridV2, 'meta'> & {
+    meta: OmniHybridV2['meta'] & {
+        senderName?: string;
+        senderId?: string;
+    };
+};
+/** Any hybrid envelope this module can decrypt. */
+type HybridEnvelope = HybridEnvelopeV1 | HybridEnvelopeV2;
 /**
  * Generate a new hybrid identity with both X25519 and Kyber keys.
  */
@@ -129,7 +154,12 @@ declare function getPublicKeys(identity: HybridIdentity): HybridPublicKeys;
  */
 declare function getSecretKeys(identity: HybridIdentity): HybridSecretKeys;
 /**
- * Encrypt a message using hybrid X25519 + Kyber encryption.
+ * Encrypt a message using hybrid X25519 + ML-KEM-1024 encryption (v2).
+ *
+ * The content key is wrapped exactly once, under a KEK derived from both
+ * shared secrets together — breaking either primitive alone is insufficient
+ * to unwrap. (v1 wrapped the key independently under each primitive, which
+ * reduced security to min(X25519, ML-KEM); v1 is now read-only legacy.)
  *
  * @param plaintext - Message to encrypt (string or bytes)
  * @param recipientPublicKeys - Recipient's public keys
@@ -138,12 +168,14 @@ declare function getSecretKeys(identity: HybridIdentity): HybridSecretKeys;
 declare function hybridEncrypt(plaintext: string | Uint8Array, recipientPublicKeys: HybridPublicKeys, sender?: {
     name?: string;
     id?: string;
-}): Promise<HybridEnvelope>;
+}): Promise<HybridEnvelopeV2>;
 /**
- * Decrypt a hybrid envelope.
+ * Decrypt a hybrid envelope (v2, v1, or legacy pqc-demo).
  *
- * Tries Kyber first (post-quantum), falls back to X25519 (classical).
- * Both must be valid for the envelope to be considered secure.
+ * v2: the content key is unwrapped from a single AND-combined KEK — both
+ * ML-KEM and X25519 secrets are required, and any failure is fatal.
+ * v1/legacy: read-only compatibility path (either secret suffices — the
+ * defect v2 exists to fix).
  *
  * @param envelope - Encrypted envelope
  * @param secretKeys - Recipient's secret keys
@@ -631,4 +663,4 @@ declare const BOX_KEY_SIZE: number;
 /** NaCl box nonce size (24 bytes) */
 declare const BOX_NONCE_SIZE: number;
 
-export { BLAKE3_BLOCK_SIZE, BLAKE3_KEY_LENGTH, BLAKE3_OUTPUT_LENGTH, BOX_KEY_SIZE, BOX_NONCE_SIZE, type Blake3Options, type BoxPayload, CHACHA20_KEY_SIZE, CHACHA20_NONCE_SIZE, type ChaChaPayload, type ClassicalWrap, DILITHIUM_ALGORITHM, DILITHIUM_PUBLIC_KEY_SIZE, DILITHIUM_SECRET_KEY_SIZE, DILITHIUM_SIGNATURE_SIZE, type DilithiumKeypair, type DilithiumKeypairB64, type DilithiumSignature, HKDF_SHA256_MAX_OUTPUT, HKDF_SHA256_OUTPUT_SIZE, HKDF_SHA512_MAX_OUTPUT, HKDF_SHA512_OUTPUT_SIZE, type HkdfHash, type HkdfOptions, type HybridEnvelope, type HybridIdentity, type HybridPublicKeys, type HybridSecretKeys, KYBER_SUITE, type KyberEncapsulation, type KyberKeypair, type KyberKeypairB64, type KyberSuite, POLY1305_TAG_SIZE, SECRETBOX_KEY_SIZE, SECRETBOX_NONCE_SIZE, SECRETBOX_OVERHEAD, type SecretboxPayload, type X25519Keypair, type X25519KeypairHex, XCHACHA20_NONCE_SIZE, assertLen, b64, blake3, blake3DeriveKey, blake3Hex, blake3Mac, boxDecrypt, boxEncrypt, boxUnwrapWithX25519, boxWrapWithX25519, chaCha20Poly1305Decrypt, chaCha20Poly1305Encrypt, createChaCha20Poly1305, createXChaCha20Poly1305, deriveKeyFromShared, dilithiumSign, dilithiumSignRaw, dilithiumVerify, dilithiumVerifyRaw, fromB64, fromHex, generateDilithiumKeypair, generateDilithiumKeypairFromSeed, generateHybridIdentity, generateKyberKeypair, generateKyberKeypairFromSeed, generateX25519Keypair, generateX25519KeypairFromSeed, getPublicKeys, getSecretKeys, hkdfDerive, hkdfExpand, hkdfExtract, hkdfSha256, hkdfSplitForNoise, hkdfTripleSplitForNoise, hybridDecrypt, hybridDecryptToString, hybridEncrypt, isDilithiumAvailable, isKyberAvailable, kyberDecapsulate, kyberEncapsulate, kyberUnwrapKey, kyberWrapKey, rand12, rand24, rand32, randN, rotateHybridIdentity, secretboxDecrypt, secretboxDecryptString, secretboxEncrypt, secretboxEncryptString, secretboxOpenRaw, secretboxRaw, sha256, sha256String, textDecoder, textEncoder, toB64, toHex, u8, ub64, x25519SharedSecret, xChaCha20Poly1305Decrypt, xChaCha20Poly1305Encrypt };
+export { BLAKE3_BLOCK_SIZE, BLAKE3_KEY_LENGTH, BLAKE3_OUTPUT_LENGTH, BOX_KEY_SIZE, BOX_NONCE_SIZE, type Blake3Options, type BoxPayload, CHACHA20_KEY_SIZE, CHACHA20_NONCE_SIZE, type ChaChaPayload, type ClassicalWrap, DILITHIUM_ALGORITHM, DILITHIUM_PUBLIC_KEY_SIZE, DILITHIUM_SECRET_KEY_SIZE, DILITHIUM_SIGNATURE_SIZE, type DilithiumKeypair, type DilithiumKeypairB64, type DilithiumSignature, HKDF_SHA256_MAX_OUTPUT, HKDF_SHA256_OUTPUT_SIZE, HKDF_SHA512_MAX_OUTPUT, HKDF_SHA512_OUTPUT_SIZE, type HkdfHash, type HkdfOptions, type HybridEnvelope, type HybridEnvelopeV1, type HybridEnvelopeV2, type HybridIdentity, type HybridPublicKeys, type HybridSecretKeys, KYBER_CIPHERTEXT_SIZE, KYBER_PUBLIC_KEY_SIZE, KYBER_SECRET_KEY_SIZE, KYBER_SEED_SIZE, KYBER_SHARED_SECRET_SIZE, KYBER_SUITE, type KyberEncapsulation, type KyberKeypair, type KyberKeypairB64, type KyberSuite, POLY1305_TAG_SIZE, SECRETBOX_KEY_SIZE, SECRETBOX_NONCE_SIZE, SECRETBOX_OVERHEAD, type SecretboxPayload, type X25519Keypair, type X25519KeypairHex, XCHACHA20_NONCE_SIZE, assertLen, b64, blake3, blake3DeriveKey, blake3Hex, blake3Mac, boxDecrypt, boxEncrypt, boxUnwrapWithX25519, boxWrapWithX25519, chaCha20Poly1305Decrypt, chaCha20Poly1305Encrypt, createChaCha20Poly1305, createXChaCha20Poly1305, deriveKeyFromShared, dilithiumSign, dilithiumSignRaw, dilithiumVerify, dilithiumVerifyRaw, fromB64, fromHex, generateDilithiumKeypair, generateDilithiumKeypairFromSeed, generateHybridIdentity, generateKyberKeypair, generateKyberKeypairFromSeed, generateX25519Keypair, generateX25519KeypairFromSeed, getPublicKeys, getSecretKeys, hkdfDerive, hkdfExpand, hkdfExtract, hkdfSha256, hkdfSplitForNoise, hkdfTripleSplitForNoise, hybridDecrypt, hybridDecryptToString, hybridEncrypt, isDilithiumAvailable, isKyberAvailable, kyberDecapsulate, kyberEncapsulate, kyberUnwrapKey, kyberWrapKey, rand12, rand24, rand32, randN, rotateHybridIdentity, secretboxDecrypt, secretboxDecryptString, secretboxEncrypt, secretboxEncryptString, secretboxOpenRaw, secretboxRaw, sha256, sha256String, textDecoder, textEncoder, toB64, toHex, u8, ub64, x25519SharedSecret, xChaCha20Poly1305Decrypt, xChaCha20Poly1305Encrypt };

package/dist/crypto/index.d.ts

@@ -1,4 +1,4 @@
-import { OmniHybridV1 } from '@omnituum/envelope-registry';
+import { OmniHybridV2, OmniHybridV1 } from '@omnituum/envelope-registry';
 import * as _noble_ciphers_utils_js from '@noble/ciphers/utils.js';
 
 /**
@@ -35,6 +35,16 @@ interface KyberEncapsulation {
 /** Canonical suite identifier for new material produced by this package. */
 declare const KYBER_SUITE: "ML-KEM-1024-FIPS203";
 type KyberSuite = typeof KYBER_SUITE;
+/** ML-KEM-1024 public key size (bytes). */
+declare const KYBER_PUBLIC_KEY_SIZE = 1568;
+/** ML-KEM-1024 secret key size (bytes). */
+declare const KYBER_SECRET_KEY_SIZE = 3168;
+/** ML-KEM-1024 ciphertext size (bytes). */
+declare const KYBER_CIPHERTEXT_SIZE = 1568;
+/** ML-KEM-1024 shared-secret size (bytes). */
+declare const KYBER_SHARED_SECRET_SIZE = 32;
+/** Seed size accepted by `generateKyberKeypairFromSeed` (bytes). */
+declare const KYBER_SEED_SIZE = 64;
 /**
  * @deprecated Always returns true. Retained for API stability across the
  * 0.3.x → 0.4.x cut. The noble backend is statically imported and always
@@ -67,10 +77,16 @@ declare function kyberUnwrapKey(sharedSecret: Uint8Array, nonceB64: string, wrap
  *
  * Post-quantum secure hybrid encryption combining:
  * - X25519 ECDH (classical, proven security)
- * - Kyber ML-KEM-768 (post-quantum, NIST Level 3)
+ * - ML-KEM-1024 (post-quantum, FIPS 203, NIST Level 5)
  *
- * Both key exchanges must succeed for decryption, providing
- * security against both classical and quantum attacks.
+ * v2 (current write format): the content key is wrapped once, under a KEK
+ * derived from BOTH shared secrets (HKDF(ss_mlkem || ss_x25519) with
+ * transcript binding) — both key exchanges must succeed to decrypt, so
+ * breaking either primitive alone is insufficient.
+ *
+ * v1 (read-only legacy): wrapped the key independently under each
+ * primitive; either secret alone sufficed. Kept only for decrypting
+ * existing envelopes — see the 2026-07-05 security audit.
  */
 
 interface HybridIdentity {
@@ -106,12 +122,21 @@ interface HybridSecretKeys {
     kyberSecB64: string;
 }
 
-type HybridEnvelope = Omit<OmniHybridV1, 'meta'> & {
+type HybridEnvelopeV1 = Omit<OmniHybridV1, 'meta'> & {
     meta: OmniHybridV1['meta'] & {
         senderName?: string;
         senderId?: string;
     };
 };
+
+type HybridEnvelopeV2 = Omit<OmniHybridV2, 'meta'> & {
+    meta: OmniHybridV2['meta'] & {
+        senderName?: string;
+        senderId?: string;
+    };
+};
+/** Any hybrid envelope this module can decrypt. */
+type HybridEnvelope = HybridEnvelopeV1 | HybridEnvelopeV2;
 /**
  * Generate a new hybrid identity with both X25519 and Kyber keys.
  */
@@ -129,7 +154,12 @@ declare function getPublicKeys(identity: HybridIdentity): HybridPublicKeys;
  */
 declare function getSecretKeys(identity: HybridIdentity): HybridSecretKeys;
 /**
- * Encrypt a message using hybrid X25519 + Kyber encryption.
+ * Encrypt a message using hybrid X25519 + ML-KEM-1024 encryption (v2).
+ *
+ * The content key is wrapped exactly once, under a KEK derived from both
+ * shared secrets together — breaking either primitive alone is insufficient
+ * to unwrap. (v1 wrapped the key independently under each primitive, which
+ * reduced security to min(X25519, ML-KEM); v1 is now read-only legacy.)
  *
  * @param plaintext - Message to encrypt (string or bytes)
  * @param recipientPublicKeys - Recipient's public keys
@@ -138,12 +168,14 @@ declare function getSecretKeys(identity: HybridIdentity): HybridSecretKeys;
 declare function hybridEncrypt(plaintext: string | Uint8Array, recipientPublicKeys: HybridPublicKeys, sender?: {
     name?: string;
     id?: string;
-}): Promise<HybridEnvelope>;
+}): Promise<HybridEnvelopeV2>;
 /**
- * Decrypt a hybrid envelope.
+ * Decrypt a hybrid envelope (v2, v1, or legacy pqc-demo).
  *
- * Tries Kyber first (post-quantum), falls back to X25519 (classical).
- * Both must be valid for the envelope to be considered secure.
+ * v2: the content key is unwrapped from a single AND-combined KEK — both
+ * ML-KEM and X25519 secrets are required, and any failure is fatal.
+ * v1/legacy: read-only compatibility path (either secret suffices — the
+ * defect v2 exists to fix).
  *
  * @param envelope - Encrypted envelope
  * @param secretKeys - Recipient's secret keys
@@ -631,4 +663,4 @@ declare const BOX_KEY_SIZE: number;
 /** NaCl box nonce size (24 bytes) */
 declare const BOX_NONCE_SIZE: number;
 
-export { BLAKE3_BLOCK_SIZE, BLAKE3_KEY_LENGTH, BLAKE3_OUTPUT_LENGTH, BOX_KEY_SIZE, BOX_NONCE_SIZE, type Blake3Options, type BoxPayload, CHACHA20_KEY_SIZE, CHACHA20_NONCE_SIZE, type ChaChaPayload, type ClassicalWrap, DILITHIUM_ALGORITHM, DILITHIUM_PUBLIC_KEY_SIZE, DILITHIUM_SECRET_KEY_SIZE, DILITHIUM_SIGNATURE_SIZE, type DilithiumKeypair, type DilithiumKeypairB64, type DilithiumSignature, HKDF_SHA256_MAX_OUTPUT, HKDF_SHA256_OUTPUT_SIZE, HKDF_SHA512_MAX_OUTPUT, HKDF_SHA512_OUTPUT_SIZE, type HkdfHash, type HkdfOptions, type HybridEnvelope, type HybridIdentity, type HybridPublicKeys, type HybridSecretKeys, KYBER_SUITE, type KyberEncapsulation, type KyberKeypair, type KyberKeypairB64, type KyberSuite, POLY1305_TAG_SIZE, SECRETBOX_KEY_SIZE, SECRETBOX_NONCE_SIZE, SECRETBOX_OVERHEAD, type SecretboxPayload, type X25519Keypair, type X25519KeypairHex, XCHACHA20_NONCE_SIZE, assertLen, b64, blake3, blake3DeriveKey, blake3Hex, blake3Mac, boxDecrypt, boxEncrypt, boxUnwrapWithX25519, boxWrapWithX25519, chaCha20Poly1305Decrypt, chaCha20Poly1305Encrypt, createChaCha20Poly1305, createXChaCha20Poly1305, deriveKeyFromShared, dilithiumSign, dilithiumSignRaw, dilithiumVerify, dilithiumVerifyRaw, fromB64, fromHex, generateDilithiumKeypair, generateDilithiumKeypairFromSeed, generateHybridIdentity, generateKyberKeypair, generateKyberKeypairFromSeed, generateX25519Keypair, generateX25519KeypairFromSeed, getPublicKeys, getSecretKeys, hkdfDerive, hkdfExpand, hkdfExtract, hkdfSha256, hkdfSplitForNoise, hkdfTripleSplitForNoise, hybridDecrypt, hybridDecryptToString, hybridEncrypt, isDilithiumAvailable, isKyberAvailable, kyberDecapsulate, kyberEncapsulate, kyberUnwrapKey, kyberWrapKey, rand12, rand24, rand32, randN, rotateHybridIdentity, secretboxDecrypt, secretboxDecryptString, secretboxEncrypt, secretboxEncryptString, secretboxOpenRaw, secretboxRaw, sha256, sha256String, textDecoder, textEncoder, toB64, toHex, u8, ub64, x25519SharedSecret, xChaCha20Poly1305Decrypt, xChaCha20Poly1305Encrypt };
+export { BLAKE3_BLOCK_SIZE, BLAKE3_KEY_LENGTH, BLAKE3_OUTPUT_LENGTH, BOX_KEY_SIZE, BOX_NONCE_SIZE, type Blake3Options, type BoxPayload, CHACHA20_KEY_SIZE, CHACHA20_NONCE_SIZE, type ChaChaPayload, type ClassicalWrap, DILITHIUM_ALGORITHM, DILITHIUM_PUBLIC_KEY_SIZE, DILITHIUM_SECRET_KEY_SIZE, DILITHIUM_SIGNATURE_SIZE, type DilithiumKeypair, type DilithiumKeypairB64, type DilithiumSignature, HKDF_SHA256_MAX_OUTPUT, HKDF_SHA256_OUTPUT_SIZE, HKDF_SHA512_MAX_OUTPUT, HKDF_SHA512_OUTPUT_SIZE, type HkdfHash, type HkdfOptions, type HybridEnvelope, type HybridEnvelopeV1, type HybridEnvelopeV2, type HybridIdentity, type HybridPublicKeys, type HybridSecretKeys, KYBER_CIPHERTEXT_SIZE, KYBER_PUBLIC_KEY_SIZE, KYBER_SECRET_KEY_SIZE, KYBER_SEED_SIZE, KYBER_SHARED_SECRET_SIZE, KYBER_SUITE, type KyberEncapsulation, type KyberKeypair, type KyberKeypairB64, type KyberSuite, POLY1305_TAG_SIZE, SECRETBOX_KEY_SIZE, SECRETBOX_NONCE_SIZE, SECRETBOX_OVERHEAD, type SecretboxPayload, type X25519Keypair, type X25519KeypairHex, XCHACHA20_NONCE_SIZE, assertLen, b64, blake3, blake3DeriveKey, blake3Hex, blake3Mac, boxDecrypt, boxEncrypt, boxUnwrapWithX25519, boxWrapWithX25519, chaCha20Poly1305Decrypt, chaCha20Poly1305Encrypt, createChaCha20Poly1305, createXChaCha20Poly1305, deriveKeyFromShared, dilithiumSign, dilithiumSignRaw, dilithiumVerify, dilithiumVerifyRaw, fromB64, fromHex, generateDilithiumKeypair, generateDilithiumKeypairFromSeed, generateHybridIdentity, generateKyberKeypair, generateKyberKeypairFromSeed, generateX25519Keypair, generateX25519KeypairFromSeed, getPublicKeys, getSecretKeys, hkdfDerive, hkdfExpand, hkdfExtract, hkdfSha256, hkdfSplitForNoise, hkdfTripleSplitForNoise, hybridDecrypt, hybridDecryptToString, hybridEncrypt, isDilithiumAvailable, isKyberAvailable, kyberDecapsulate, kyberEncapsulate, kyberUnwrapKey, kyberWrapKey, rand12, rand24, rand32, randN, rotateHybridIdentity, secretboxDecrypt, secretboxDecryptString, secretboxEncrypt, secretboxEncryptString, secretboxOpenRaw, secretboxRaw, sha256, sha256String, textDecoder, textEncoder, toB64, toHex, u8, ub64, x25519SharedSecret, xChaCha20Poly1305Decrypt, xChaCha20Poly1305Encrypt };