@omnituum/pqc-shared 0.4.0 → 0.6.0

package/dist/index.cjs

@@ -155,6 +155,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;
 }
@@ -202,17 +207,20 @@ function kyberUnwrapKey(sharedSecret, nonceB64, wrappedB64) {
   return nacl4__default.default.secretbox.open(wrapped, nonce, kek) || null;
 }
 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 VAULT_VERSION = "omnituum.vault.v1";
 var VAULT_ENCRYPTED_VERSION = "omnituum.vault.enc.v1";
 var VAULT_ENCRYPTED_VERSION_V2 = "omnituum.vault.enc.v2";
 var ENVELOPE_SUITE = "x25519+kyber768";
+var ENVELOPE_SUITE_V2 = "x25519+mlkem1024";
 var ENVELOPE_AEAD = "xsalsa20poly1305";
 var VAULT_KDF = "PBKDF2-SHA256";
 var VAULT_KDF_V2 = "Argon2id";
 var VAULT_ALGORITHM = "AES-256-GCM";
 var SUPPORTED_ENVELOPE_VERSIONS = [
   ENVELOPE_VERSION,
+  ENVELOPE_VERSION_V2,
   ENVELOPE_VERSION_LEGACY
 ];
 var SUPPORTED_VAULT_VERSIONS = [
@@ -257,6 +265,8 @@ function isVaultVersionSupported(version) {
 function isVaultEncryptedVersionSupported(version) {
   return SUPPORTED_VAULT_ENCRYPTED_VERSIONS.includes(version);
 }
+var ENVELOPE_V1_FIELDS = ["x25519Epk", "x25519Wrap", "kyberKemCt", "kyberWrap", "contentNonce", "ciphertext", "meta"];
+var ENVELOPE_V2_FIELDS = ["x25519Epk", "kyberKemCt", "ckWrap", "contentNonce", "ciphertext", "meta"];
 function validateEnvelope(envelope) {
   const errors = [];
   if (!envelope || typeof envelope !== "object") {
@@ -268,14 +278,16 @@ function validateEnvelope(envelope) {
   } else if (!isEnvelopeVersionSupported(env.v)) {
     errors.push(`Unsupported envelope version: ${env.v}`);
   }
-  if (env.suite !== ENVELOPE_SUITE) {
-    errors.push(`Invalid suite: expected "${ENVELOPE_SUITE}", got "${env.suite}"`);
+  const isV2 = env.v === ENVELOPE_VERSION_V2;
+  const expectedSuite = isV2 ? ENVELOPE_SUITE_V2 : ENVELOPE_SUITE;
+  const requiredFields = isV2 ? ENVELOPE_V2_FIELDS : ENVELOPE_V1_FIELDS;
+  if (env.suite !== expectedSuite) {
+    errors.push(`Invalid suite: expected "${expectedSuite}", got "${env.suite}"`);
   }
   if (env.aead !== ENVELOPE_AEAD) {
     errors.push(`Invalid aead: expected "${ENVELOPE_AEAD}", got "${env.aead}"`);
   }
-  const required = ["x25519Epk", "x25519Wrap", "kyberKemCt", "kyberWrap", "contentNonce", "ciphertext", "meta"];
-  for (const field of required) {
+  for (const field of requiredFields) {
     if (!(field in env)) {
       errors.push(`Missing required field: ${field}`);
     }
@@ -370,7 +382,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 {
@@ -396,49 +407,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 = nacl4__default.default.secretbox(pt, contentNonce, CK);
-  const x25519EphKp = nacl4__default.default.box.keyPair();
-  const recipientX25519Pk = fromHex(recipientPublicKeys.x25519PubHex);
-  const x25519Shared = nacl4__default.default.scalarMult(x25519EphKp.secretKey, recipientX25519Pk);
-  const x25519Kek = hkdfFlex(x25519Shared, "omnituum/x25519", "wrap-ck");
-  const x25519WrapNonce = rand24();
-  const x25519Wrapped = nacl4__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 = nacl4__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 = nacl4__default.default.secretbox(pt, contentNonce, CK);
+    const x25519EphKp = nacl4__default.default.box.keyPair();
+    const recipientX25519Pk = fromHex(recipientPublicKeys.x25519PubHex);
+    const x25519Shared = nacl4__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 = nacl4__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 = nacl4__default.default.scalarMult(sk, ephPk);
+  const kek = combinedKekV2(kyberShared, x25519Shared, envelope.x25519Epk, envelope.kyberKemCt);
+  kyberShared.fill(0);
+  x25519Shared.fill(0);
+  const CK = nacl4__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");
@@ -447,11 +483,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 {
@@ -464,21 +496,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 = nacl4__default.default.secretbox.open(
     ub64(envelope.ciphertext),
     ub64(envelope.contentNonce),
     CK
   );
+  CK.fill(0);
   if (!pt) {
     throw new Error("Content authentication failed");
   }
@@ -497,8 +536,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;
   }
 }
@@ -516,8 +554,7 @@ async function generateDilithiumKeypair() {
       publicB64: toB64(kp.publicKey),
       secretB64: toB64(kp.secretKey)
     };
-  } catch (e) {
-    console.warn("[Dilithium] Key generation failed:", e);
+  } catch {
     return null;
   }
 }
@@ -856,17 +893,11 @@ function computeIntegrityHash(identities) {
     createdAt: i.createdAt,
     rotationCount: i.rotationCount
   }));
-  const serialized = JSON.stringify(canonical, Object.keys(canonical[0] || {}).sort());
+  const serialized = JSON.stringify(canonical);
   return computeStringHash(serialized);
 }
 function computeStringHash(str) {
-  let hash = 0;
-  for (let i = 0; i < str.length; i++) {
-    const char = str.charCodeAt(i);
-    hash = (hash << 5) - hash + char;
-    hash = hash & hash;
-  }
-  return Math.abs(hash).toString(16).padStart(16, "0");
+  return toHex(sha256(textEncoder.encode(str)));
 }
 async function computeHashAsync(data) {
   const encoder = new TextEncoder();
@@ -1117,7 +1148,6 @@ async function createIdentity(name) {
   const x25519 = generateX25519Keypair();
   const kyber = await generateKyberKeypair();
   if (!kyber) {
-    console.error("Kyber key generation failed");
     return null;
   }
   const now = (/* @__PURE__ */ new Date()).toISOString();
@@ -1340,12 +1370,22 @@ async function migrateEncryptedVault(options) {
 
 // src/fs/types.ts
 var OQE_MAGIC = new Uint8Array([79, 81, 69, 70]);
-var OQE_FORMAT_VERSION = 1;
+var OQE_FORMAT_VERSION_V1 = 1;
+var OQE_FORMAT_VERSION_V2 = 2;
+var SUPPORTED_OQE_VERSIONS = [OQE_FORMAT_VERSION_V1, OQE_FORMAT_VERSION_V2];
 var ALGORITHM_SUITES = {
-  /** Hybrid: X25519 ECDH + Kyber768 KEM + AES-256-GCM */
+  /**
+   * LEGACY (read-only): Hybrid X25519 + Kyber with independent per-primitive
+   * wraps (either secret unwraps). Only appears in v1 files. Never written.
+   */
   HYBRID_X25519_KYBER768_AES256GCM: 1,
   /** Password: Argon2id + AES-256-GCM */
-  PASSWORD_ARGON2ID_AES256GCM: 2
+  PASSWORD_ARGON2ID_AES256GCM: 2,
+  /**
+   * Hybrid X25519 + ML-KEM-1024 with a single AND-combined KEK wrap
+   * (HKDF(ss_mlkem || ss_x25519), transcript-bound). Written by v2.
+   */
+  HYBRID_X25519_MLKEM1024_AES256GCM: 3
 };
 var DEFAULT_ARGON2ID_PARAMS = {
   memoryCost: 65536,
@@ -1355,7 +1395,8 @@ var DEFAULT_ARGON2ID_PARAMS = {
   hashLength: 32,
   saltLength: 32
 };
-var OQE_HEADER_SIZE = 30;
+var OQE_HEADER_SIZE_V1 = 30;
+var OQE_HEADER_SIZE_V2 = 42;
 var OQEError = class extends Error {
   constructor(code, message) {
     super(message);
@@ -1425,6 +1466,7 @@ function toArrayBuffer(arr) {
 }
 var AES_KEY_SIZE = 32;
 var AES_GCM_IV_SIZE = 12;
+var AES_GCM_TAG_SIZE = 16;
 async function importAesKey(keyBytes) {
   if (keyBytes.length !== AES_KEY_SIZE) {
     throw new Error(`AES key must be ${AES_KEY_SIZE} bytes, got ${keyBytes.length}`);
@@ -1448,7 +1490,7 @@ async function aesEncrypt(plaintext, key, iv, additionalData) {
     {
       name: "AES-GCM",
       iv: toArrayBuffer(ivBytes),
-      additionalData: void 0,
+      additionalData: additionalData ? toArrayBuffer(additionalData) : void 0,
       tagLength: 128
       // 16 bytes
     },
@@ -1484,6 +1526,9 @@ async function aesDecrypt(ciphertext, key, iv, additionalData) {
 }
 
 // src/fs/format.ts
+function oqeHeaderSize(version) {
+  return version === OQE_FORMAT_VERSION_V2 ? OQE_HEADER_SIZE_V2 : OQE_HEADER_SIZE_V1;
+}
 function writeUint32BE(value) {
   const buffer = new ArrayBuffer(4);
   new DataView(buffer).setUint32(0, value, false);
@@ -1501,7 +1546,8 @@ function readUint16BE(data, offset) {
   return new DataView(data.buffer, data.byteOffset + offset).getUint16(0, false);
 }
 function writeOQEHeader(header) {
-  const buffer = new Uint8Array(OQE_HEADER_SIZE);
+  const isV2 = header.version === OQE_FORMAT_VERSION_V2;
+  const buffer = new Uint8Array(oqeHeaderSize(header.version));
   let offset = 0;
   buffer.set(OQE_MAGIC, offset);
   offset += 4;
@@ -1514,11 +1560,18 @@ function writeOQEHeader(header) {
   buffer.set(writeUint32BE(header.keyMaterialLength), offset);
   offset += 4;
   buffer.set(header.iv, offset);
+  offset += 12;
+  if (isV2) {
+    if (!header.contentIv || header.contentIv.length !== 12) {
+      throw new OQEError("INVALID_HEADER", "v2 header requires a 12-byte contentIv");
+    }
+    buffer.set(header.contentIv, offset);
+  }
   return buffer;
 }
 function parseOQEHeader(data) {
-  if (data.length < OQE_HEADER_SIZE) {
-    throw new OQEError("INVALID_HEADER", `File too small: need ${OQE_HEADER_SIZE} bytes, got ${data.length}`);
+  if (data.length < OQE_HEADER_SIZE_V1) {
+    throw new OQEError("INVALID_HEADER", `File too small: need at least ${OQE_HEADER_SIZE_V1} bytes, got ${data.length}`);
   }
   let offset = 0;
   const magic = data.slice(0, 4);
@@ -1527,14 +1580,19 @@ function parseOQEHeader(data) {
   }
   offset += 4;
   const version = data[offset++];
-  if (version !== OQE_FORMAT_VERSION) {
+  if (!SUPPORTED_OQE_VERSIONS.includes(version)) {
     throw new OQEError("UNSUPPORTED_VERSION", `Unsupported OQE version: ${version}`);
   }
   const algorithmSuiteRaw = data[offset++];
-  if (algorithmSuiteRaw !== ALGORITHM_SUITES.HYBRID_X25519_KYBER768_AES256GCM && algorithmSuiteRaw !== ALGORITHM_SUITES.PASSWORD_ARGON2ID_AES256GCM) {
+  if (algorithmSuiteRaw !== ALGORITHM_SUITES.HYBRID_X25519_KYBER768_AES256GCM && algorithmSuiteRaw !== ALGORITHM_SUITES.HYBRID_X25519_MLKEM1024_AES256GCM && algorithmSuiteRaw !== ALGORITHM_SUITES.PASSWORD_ARGON2ID_AES256GCM) {
     throw new OQEError("UNSUPPORTED_ALGORITHM", `Unsupported algorithm suite: 0x${algorithmSuiteRaw.toString(16)}`);
   }
   const algorithmSuite = algorithmSuiteRaw;
+  const isV2 = version === OQE_FORMAT_VERSION_V2;
+  const headerSize = oqeHeaderSize(version);
+  if (data.length < headerSize) {
+    throw new OQEError("INVALID_HEADER", `Truncated v${version} header: need ${headerSize} bytes, got ${data.length}`);
+  }
   const flags = readUint32BE(data, offset);
   offset += 4;
   const metadataLength = readUint32BE(data, offset);
@@ -1542,35 +1600,18 @@ function parseOQEHeader(data) {
   const keyMaterialLength = readUint32BE(data, offset);
   offset += 4;
   const iv = data.slice(offset, offset + 12);
+  offset += 12;
+  const contentIv = isV2 ? data.slice(offset, offset + 12) : void 0;
   return {
     version,
     algorithmSuite,
     flags,
     metadataLength,
     keyMaterialLength,
-    iv
+    iv,
+    contentIv
   };
 }
-function serializeHybridKeyMaterial(km) {
-  const parts = [];
-  parts.push(km.x25519EphemeralPk);
-  parts.push(km.x25519Nonce);
-  parts.push(writeUint16BE(km.x25519WrappedKey.length));
-  parts.push(km.x25519WrappedKey);
-  parts.push(writeUint16BE(km.kyberCiphertext.length));
-  parts.push(km.kyberCiphertext);
-  parts.push(km.kyberNonce);
-  parts.push(writeUint16BE(km.kyberWrappedKey.length));
-  parts.push(km.kyberWrappedKey);
-  const totalLength = parts.reduce((sum, p) => sum + p.length, 0);
-  const result = new Uint8Array(totalLength);
-  let offset = 0;
-  for (const part of parts) {
-    result.set(part, offset);
-    offset += part.length;
-  }
-  return result;
-}
 function parseHybridKeyMaterial(data) {
   let offset = 0;
   const x25519EphemeralPk = data.slice(offset, offset + 32);
@@ -1599,6 +1640,38 @@ function parseHybridKeyMaterial(data) {
     kyberWrappedKey
   };
 }
+function serializeHybridKeyMaterialV2(km) {
+  const parts = [];
+  parts.push(km.x25519EphemeralPk);
+  parts.push(writeUint16BE(km.kyberCiphertext.length));
+  parts.push(km.kyberCiphertext);
+  parts.push(km.ckWrapNonce);
+  parts.push(writeUint16BE(km.ckWrapped.length));
+  parts.push(km.ckWrapped);
+  const totalLength = parts.reduce((sum, p) => sum + p.length, 0);
+  const result = new Uint8Array(totalLength);
+  let offset = 0;
+  for (const part of parts) {
+    result.set(part, offset);
+    offset += part.length;
+  }
+  return result;
+}
+function parseHybridKeyMaterialV2(data) {
+  let offset = 0;
+  const x25519EphemeralPk = data.slice(offset, offset + 32);
+  offset += 32;
+  const kyberCtLen = readUint16BE(data, offset);
+  offset += 2;
+  const kyberCiphertext = data.slice(offset, offset + kyberCtLen);
+  offset += kyberCtLen;
+  const ckWrapNonce = data.slice(offset, offset + 24);
+  offset += 24;
+  const ckWrappedLen = readUint16BE(data, offset);
+  offset += 2;
+  const ckWrapped = data.slice(offset, offset + ckWrappedLen);
+  return { x25519EphemeralPk, kyberCiphertext, ckWrapNonce, ckWrapped };
+}
 function serializePasswordKeyMaterial(km) {
   const result = new Uint8Array(32 + 4 + 4 + 4);
   result.set(km.salt, 0);
@@ -1640,7 +1713,7 @@ function assembleOQEFile(components) {
 }
 function parseOQEFile(data) {
   const header = parseOQEHeader(data);
-  let offset = OQE_HEADER_SIZE;
+  let offset = oqeHeaderSize(header.version);
   const keyMaterial = data.slice(offset, offset + header.keyMaterialLength);
   offset += header.keyMaterialLength;
   const encryptedMetadata = data.slice(offset, offset + header.metadataLength);
@@ -1660,61 +1733,81 @@ function addOQEExtension(filename) {
   }
   return `${filename}${OQE_EXTENSION}`;
 }
-function hkdfFlex2(ikm, salt, info) {
-  return hkdfSha256(ikm, { salt: u8(salt), info: u8(info), length: 32 });
-}
+var AES_GCM_TAG_LEN = AES_GCM_TAG_SIZE;
 function computeIdentityHash(publicKeyHex) {
   const hash = sha256(fromHex(publicKeyHex));
   return toHex(hash).slice(0, 16);
 }
+function combinedFileKekV2(kyberShared, x25519Shared, x25519EpkHex, kyberKemCtB64) {
+  const ikm = new Uint8Array(kyberShared.length + x25519Shared.length);
+  ikm.set(kyberShared, 0);
+  ikm.set(x25519Shared, kyberShared.length);
+  try {
+    return hkdfSha256(ikm, {
+      salt: u8("omnituum/fs/hybrid-v2"),
+      info: u8(`wrap-content-key|${x25519EpkHex}|${kyberKemCtB64}`),
+      length: 32
+    });
+  } finally {
+    ikm.fill(0);
+  }
+}
 async function encryptHybrid(plaintext, metadata, options) {
   if (!await isKyberAvailable()) {
     throw new OQEError("KYBER_UNAVAILABLE", "Kyber library not available in this environment");
   }
   const contentKey = rand32();
-  const iv = rand12();
-  const x25519EphKp = nacl4__default.default.box.keyPair();
-  const recipientX25519Pk = fromHex(options.recipientPublicKeys.x25519PubHex);
-  const x25519Shared = nacl4__default.default.scalarMult(x25519EphKp.secretKey, recipientX25519Pk);
-  const x25519Kek = hkdfFlex2(x25519Shared, "omnituum/fs/x25519", "wrap-content-key");
-  const x25519Nonce = rand24();
-  const x25519WrappedKey = nacl4__default.default.secretbox(contentKey, x25519Nonce, x25519Kek);
-  const kyberResult = await kyberEncapsulate(options.recipientPublicKeys.kyberPubB64);
-  const kyberKek = hkdfFlex2(kyberResult.sharedSecret, "omnituum/fs/kyber", "wrap-content-key");
-  const kyberNonce = rand24();
-  const kyberWrappedKey = nacl4__default.default.secretbox(contentKey, kyberNonce, kyberKek);
-  const keyMaterial = {
-    x25519EphemeralPk: x25519EphKp.publicKey,
-    x25519Nonce,
-    x25519WrappedKey,
-    kyberCiphertext: kyberResult.ciphertext,
-    kyberNonce,
-    kyberWrappedKey
-  };
-  const keyMaterialBytes = serializeHybridKeyMaterial(keyMaterial);
-  const metadataBytes = serializeMetadata(metadata);
-  const { ciphertext: encryptedMetadata } = await aesEncrypt(metadataBytes, contentKey, iv);
-  const { ciphertext: encryptedContent } = await aesEncrypt(plaintext, contentKey, iv);
-  const header = {
-    version: OQE_FORMAT_VERSION,
-    algorithmSuite: ALGORITHM_SUITES.HYBRID_X25519_KYBER768_AES256GCM,
-    flags: 0,
-    metadataLength: encryptedMetadata.length,
-    keyMaterialLength: keyMaterialBytes.length,
-    iv
-  };
-  const fileData = assembleOQEFile({
-    header,
-    keyMaterial: keyMaterialBytes,
-    encryptedMetadata,
-    encryptedContent
-  });
-  return {
-    data: fileData,
-    filename: addOQEExtension(metadata.filename),
-    metadata,
-    mode: "hybrid"
-  };
+  try {
+    const metadataIv = rand12();
+    const contentIv = rand12();
+    const x25519EphKp = nacl4__default.default.box.keyPair();
+    const recipientX25519Pk = fromHex(options.recipientPublicKeys.x25519PubHex);
+    const x25519Shared = nacl4__default.default.scalarMult(x25519EphKp.secretKey, recipientX25519Pk);
+    const x25519EpkHex = toHex(x25519EphKp.publicKey);
+    const kyberResult = await kyberEncapsulate(options.recipientPublicKeys.kyberPubB64);
+    const kyberKemCtB64 = b64(kyberResult.ciphertext);
+    const kek = combinedFileKekV2(kyberResult.sharedSecret, x25519Shared, x25519EpkHex, kyberKemCtB64);
+    const ckWrapNonce = rand24();
+    const ckWrapped = nacl4__default.default.secretbox(contentKey, ckWrapNonce, kek);
+    kek.fill(0);
+    x25519Shared.fill(0);
+    kyberResult.sharedSecret.fill(0);
+    x25519EphKp.secretKey.fill(0);
+    const keyMaterial = {
+      x25519EphemeralPk: x25519EphKp.publicKey,
+      kyberCiphertext: kyberResult.ciphertext,
+      ckWrapNonce,
+      ckWrapped
+    };
+    const keyMaterialBytes = serializeHybridKeyMaterialV2(keyMaterial);
+    const metadataBytes = serializeMetadata(metadata);
+    const header = {
+      version: OQE_FORMAT_VERSION_V2,
+      algorithmSuite: ALGORITHM_SUITES.HYBRID_X25519_MLKEM1024_AES256GCM,
+      flags: 0,
+      metadataLength: metadataBytes.length + AES_GCM_TAG_LEN,
+      keyMaterialLength: keyMaterialBytes.length,
+      iv: metadataIv,
+      contentIv
+    };
+    const aad = writeOQEHeader(header);
+    const { ciphertext: encryptedMetadata } = await aesEncrypt(metadataBytes, contentKey, metadataIv, aad);
+    const { ciphertext: encryptedContent } = await aesEncrypt(plaintext, contentKey, contentIv, aad);
+    const fileData = assembleOQEFile({
+      header,
+      keyMaterial: keyMaterialBytes,
+      encryptedMetadata,
+      encryptedContent
+    });
+    return {
+      data: fileData,
+      filename: addOQEExtension(metadata.filename),
+      metadata,
+      mode: "hybrid"
+    };
+  } finally {
+    contentKey.fill(0);
+  }
 }
 async function encryptPassword(plaintext, metadata, options) {
   if (!await isArgon2Available()) {
@@ -1726,37 +1819,44 @@ async function encryptPassword(plaintext, metadata, options) {
   };
   const salt = generateArgon2Salt(params.saltLength);
   const contentKey = await deriveKeyFromPassword(options.password, salt, params);
-  const iv = rand12();
-  const keyMaterial = {
-    salt,
-    memoryCost: params.memoryCost,
-    timeCost: params.timeCost,
-    parallelism: params.parallelism
-  };
-  const keyMaterialBytes = serializePasswordKeyMaterial(keyMaterial);
-  const metadataBytes = serializeMetadata(metadata);
-  const { ciphertext: encryptedMetadata } = await aesEncrypt(metadataBytes, contentKey, iv);
-  const { ciphertext: encryptedContent } = await aesEncrypt(plaintext, contentKey, iv);
-  const header = {
-    version: OQE_FORMAT_VERSION,
-    algorithmSuite: ALGORITHM_SUITES.PASSWORD_ARGON2ID_AES256GCM,
-    flags: 0,
-    metadataLength: encryptedMetadata.length,
-    keyMaterialLength: keyMaterialBytes.length,
-    iv
-  };
-  const fileData = assembleOQEFile({
-    header,
-    keyMaterial: keyMaterialBytes,
-    encryptedMetadata,
-    encryptedContent
-  });
-  return {
-    data: fileData,
-    filename: addOQEExtension(metadata.filename),
-    metadata,
-    mode: "password"
-  };
+  try {
+    const metadataIv = rand12();
+    const contentIv = rand12();
+    const keyMaterial = {
+      salt,
+      memoryCost: params.memoryCost,
+      timeCost: params.timeCost,
+      parallelism: params.parallelism
+    };
+    const keyMaterialBytes = serializePasswordKeyMaterial(keyMaterial);
+    const metadataBytes = serializeMetadata(metadata);
+    const header = {
+      version: OQE_FORMAT_VERSION_V2,
+      algorithmSuite: ALGORITHM_SUITES.PASSWORD_ARGON2ID_AES256GCM,
+      flags: 0,
+      metadataLength: metadataBytes.length + AES_GCM_TAG_LEN,
+      keyMaterialLength: keyMaterialBytes.length,
+      iv: metadataIv,
+      contentIv
+    };
+    const aad = writeOQEHeader(header);
+    const { ciphertext: encryptedMetadata } = await aesEncrypt(metadataBytes, contentKey, metadataIv, aad);
+    const { ciphertext: encryptedContent } = await aesEncrypt(plaintext, contentKey, contentIv, aad);
+    const fileData = assembleOQEFile({
+      header,
+      keyMaterial: keyMaterialBytes,
+      encryptedMetadata,
+      encryptedContent
+    });
+    return {
+      data: fileData,
+      filename: addOQEExtension(metadata.filename),
+      metadata,
+      mode: "password"
+    };
+  } finally {
+    contentKey.fill(0);
+  }
 }
 async function encryptFile(input, options) {
   const plaintext = await toUint8Array(input.data);
@@ -1784,17 +1884,56 @@ async function encryptFileWithPassword(input, password) {
     password
   });
 }
-function hkdfFlex3(ikm, salt, info) {
+function hkdfFlex2(ikm, salt, info) {
   return hkdfSha256(ikm, { salt: u8(salt), info: u8(info), length: 32 });
 }
+function headerAad(header) {
+  return writeOQEHeader(header);
+}
 async function decryptHybrid(encryptedData, options) {
-  const { header, keyMaterial, encryptedMetadata, encryptedContent } = parseOQEFile(encryptedData);
-  if (header.algorithmSuite !== ALGORITHM_SUITES.HYBRID_X25519_KYBER768_AES256GCM) {
-    throw new OQEError(
-      "UNSUPPORTED_ALGORITHM",
-      "This file was not encrypted with hybrid mode. Use password decryption."
-    );
+  const parsed = parseOQEFile(encryptedData);
+  const { header } = parsed;
+  if (header.algorithmSuite === ALGORITHM_SUITES.HYBRID_X25519_MLKEM1024_AES256GCM) {
+    return decryptHybridV2(parsed, options);
+  }
+  if (header.algorithmSuite === ALGORITHM_SUITES.HYBRID_X25519_KYBER768_AES256GCM) {
+    return decryptHybridV1Legacy(parsed, options);
   }
+  throw new OQEError(
+    "UNSUPPORTED_ALGORITHM",
+    "This file was not encrypted with hybrid mode. Use password decryption."
+  );
+}
+async function decryptHybridV2(parsed, options) {
+  const { header, keyMaterial, encryptedMetadata, encryptedContent } = parsed;
+  if (header.version !== OQE_FORMAT_VERSION_V2 || !header.contentIv) {
+    throw new OQEError("INVALID_HEADER", "v2 hybrid file missing content IV");
+  }
+  const km = parseHybridKeyMaterialV2(keyMaterial);
+  const x25519EpkHex = toHex(km.x25519EphemeralPk);
+  const kyberKemCtB64 = b64(km.kyberCiphertext);
+  const kyberShared = await kyberDecapsulate(kyberKemCtB64, options.recipientSecretKeys.kyberSecB64);
+  const sk = fromHex(options.recipientSecretKeys.x25519SecHex);
+  const x25519Shared = nacl4__default.default.scalarMult(sk, km.x25519EphemeralPk);
+  const kek = combinedFileKekV2(kyberShared, x25519Shared, x25519EpkHex, kyberKemCtB64);
+  kyberShared.fill(0);
+  x25519Shared.fill(0);
+  const contentKey = nacl4__default.default.secretbox.open(km.ckWrapped, km.ckWrapNonce, kek);
+  kek.fill(0);
+  if (!contentKey) {
+    throw new OQEError("KEY_UNWRAP_FAILED", "Could not unwrap content key \u2014 combined-KEK authentication failed");
+  }
+  const aad = headerAad(header);
+  try {
+    const metadata = await decryptSection(encryptedMetadata, contentKey, header.iv, aad, "metadata");
+    const plaintext = await aesDecrypt(encryptedContent, contentKey, header.contentIv, aad);
+    return buildResult(plaintext, metadata, "hybrid");
+  } finally {
+    contentKey.fill(0);
+  }
+}
+async function decryptHybridV1Legacy(parsed, options) {
+  const { header, keyMaterial, encryptedMetadata, encryptedContent } = parsed;
   const km = parseHybridKeyMaterial(keyMaterial);
   let contentKey = null;
   if (await isKyberAvailable()) {
@@ -1803,54 +1942,47 @@ async function decryptHybrid(encryptedData, options) {
         toB64(km.kyberCiphertext),
         options.recipientSecretKeys.kyberSecB64
       );
-      const kyberKek = hkdfFlex3(kyberShared, "omnituum/fs/kyber", "wrap-content-key");
-      const unwrapped = nacl4__default.default.secretbox.open(km.kyberWrappedKey, km.kyberNonce, kyberKek);
-      if (unwrapped) {
-        contentKey = unwrapped;
-        console.log("[OQE] Decrypted content key via Kyber (post-quantum secure)");
-      }
-    } catch (e) {
-      console.warn("[OQE] Kyber decapsulation failed, trying X25519:", e);
+      const kyberKek = hkdfFlex2(kyberShared, "omnituum/fs/kyber", "wrap-content-key");
+      contentKey = nacl4__default.default.secretbox.open(km.kyberWrappedKey, km.kyberNonce, kyberKek);
+    } catch {
     }
   }
   if (!contentKey) {
     try {
-      const ephPk = km.x25519EphemeralPk;
       const sk = fromHex(options.recipientSecretKeys.x25519SecHex);
-      const x25519Shared = nacl4__default.default.scalarMult(sk, ephPk);
-      const x25519Kek = hkdfFlex3(x25519Shared, "omnituum/fs/x25519", "wrap-content-key");
-      const unwrapped = nacl4__default.default.secretbox.open(km.x25519WrappedKey, km.x25519Nonce, x25519Kek);
-      if (unwrapped) {
-        contentKey = unwrapped;
-        console.log("[OQE] Decrypted content key via X25519 (classical)");
-      }
-    } catch (e) {
-      console.warn("[OQE] X25519 decryption failed:", e);
+      const x25519Shared = nacl4__default.default.scalarMult(sk, km.x25519EphemeralPk);
+      const x25519Kek = hkdfFlex2(x25519Shared, "omnituum/fs/x25519", "wrap-content-key");
+      contentKey = nacl4__default.default.secretbox.open(km.x25519WrappedKey, km.x25519Nonce, x25519Kek);
+    } catch {
     }
   }
   if (!contentKey) {
     throw new OQEError("KEY_UNWRAP_FAILED", "Could not unwrap content key with provided keys");
   }
-  let metadata;
   try {
-    const metadataBytes = await aesDecrypt(encryptedMetadata, contentKey, header.iv);
-    metadata = parseMetadata(metadataBytes);
-  } catch (e) {
-    throw new OQEError("DECRYPTION_FAILED", "Failed to decrypt file metadata");
+    const metadata = await decryptSection(encryptedMetadata, contentKey, header.iv, void 0, "metadata");
+    const plaintext = await aesDecrypt(encryptedContent, contentKey, header.iv);
+    return buildResult(plaintext, metadata, "hybrid");
+  } finally {
+    contentKey.fill(0);
   }
-  let plaintext;
+}
+async function decryptSection(ciphertext, key, iv, aad, what) {
   try {
-    plaintext = await aesDecrypt(encryptedContent, contentKey, header.iv);
-  } catch (e) {
-    throw new OQEError("DECRYPTION_FAILED", "Failed to decrypt file content");
+    const bytes = await aesDecrypt(ciphertext, key, iv, aad);
+    return parseMetadata(bytes);
+  } catch {
+    throw new OQEError("DECRYPTION_FAILED", `Failed to decrypt file ${what}`);
   }
+}
+function buildResult(plaintext, metadata, mode) {
   return {
     data: plaintext,
     filename: metadata.filename,
     mimeType: metadata.mimeType,
     originalSize: metadata.originalSize,
     metadata,
-    mode: "hybrid"
+    mode
   };
 }
 async function decryptPassword(encryptedData, options) {
@@ -1872,27 +2004,27 @@ async function decryptPassword(encryptedData, options) {
     hashLength: 32,
     saltLength: km.salt.length
   });
-  let metadata;
+  const isV2 = header.version === OQE_FORMAT_VERSION_V2;
+  const aad = isV2 ? headerAad(header) : void 0;
+  const contentIv = isV2 && header.contentIv ? header.contentIv : header.iv;
   try {
-    const metadataBytes = await aesDecrypt(encryptedMetadata, contentKey, header.iv);
-    metadata = parseMetadata(metadataBytes);
-  } catch (e) {
-    throw new OQEError("PASSWORD_WRONG", "Incorrect password or corrupted file");
-  }
-  let plaintext;
-  try {
-    plaintext = await aesDecrypt(encryptedContent, contentKey, header.iv);
-  } catch (e) {
-    throw new OQEError("DECRYPTION_FAILED", "Failed to decrypt file content");
+    let metadata;
+    try {
+      const metadataBytes = await aesDecrypt(encryptedMetadata, contentKey, header.iv, aad);
+      metadata = parseMetadata(metadataBytes);
+    } catch {
+      throw new OQEError("PASSWORD_WRONG", "Incorrect password or corrupted file");
+    }
+    let plaintext;
+    try {
+      plaintext = await aesDecrypt(encryptedContent, contentKey, contentIv, aad);
+    } catch {
+      throw new OQEError("DECRYPTION_FAILED", "Failed to decrypt file content");
+    }
+    return buildResult(plaintext, metadata, "password");
+  } finally {
+    contentKey.fill(0);
   }
-  return {
-    data: plaintext,
-    filename: metadata.filename,
-    mimeType: metadata.mimeType,
-    originalSize: metadata.originalSize,
-    metadata,
-    mode: "password"
-  };
 }
 async function decryptFile(encryptedData, options) {
   const data = await toUint8Array(encryptedData);
@@ -1999,9 +2131,16 @@ exports.DILITHIUM_SECRET_KEY_SIZE = DILITHIUM_SECRET_KEY_SIZE;
 exports.DILITHIUM_SIGNATURE_SIZE = DILITHIUM_SIGNATURE_SIZE;
 exports.ENVELOPE_AEAD = ENVELOPE_AEAD;
 exports.ENVELOPE_SUITE = ENVELOPE_SUITE;
+exports.ENVELOPE_SUITE_V2 = ENVELOPE_SUITE_V2;
 exports.ENVELOPE_VERSION = ENVELOPE_VERSION;
+exports.ENVELOPE_VERSION_V2 = ENVELOPE_VERSION_V2;
 exports.KDF_CONFIG_ARGON2ID = KDF_CONFIG_ARGON2ID;
 exports.KDF_CONFIG_PBKDF2 = KDF_CONFIG_PBKDF2;
+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;