@omnituum/pqc-shared 0.4.1 → 0.6.0

package/dist/fs/index.js

@@ -1,17 +1,28 @@
 import { argon2id } from 'hash-wasm';
 import { sha256 as sha256$1 } from '@noble/hashes/sha2.js';
 import { hmac } from '@noble/hashes/hmac.js';
-import nacl2 from 'tweetnacl';
+import nacl3 from 'tweetnacl';
 import { ml_kem1024 } from '@noble/post-quantum/ml-kem.js';
 
 // 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 OQE_FORMAT_VERSION = OQE_FORMAT_VERSION_V2;
+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,
@@ -29,7 +40,9 @@ var MIN_ARGON2ID_PARAMS = {
   hashLength: 32,
   saltLength: 32
 };
-var OQE_HEADER_SIZE = 30;
+var OQE_HEADER_SIZE_V1 = 30;
+var OQE_HEADER_SIZE_V2 = 42;
+var OQE_HEADER_SIZE = OQE_HEADER_SIZE_V1;
 var OQEError = class extends Error {
   constructor(code, message) {
     super(message);
@@ -115,6 +128,7 @@ function hkdfSha256(ikm, opts) {
   }
   return out;
 }
+var b64 = toB64;
 var ub64 = fromB64;
 var u8 = (s) => typeof s === "string" ? textEncoder.encode(s) : s;
 
@@ -344,6 +358,9 @@ async function aesDecryptStreaming(encrypted, key, onProgress) {
 }
 
 // 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);
@@ -361,7 +378,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;
@@ -374,11 +392,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);
@@ -387,14 +412,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);
@@ -402,13 +432,16 @@ 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) {
@@ -459,6 +492,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);
@@ -500,7 +565,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);
@@ -535,8 +600,11 @@ function isOQEFile(filenameOrData) {
 }
 var OQE_MIME_TYPE = "application/x-omnituum-encrypted";
 function getAlgorithmName(suiteId) {
+  if (suiteId === ALGORITHM_SUITES.HYBRID_X25519_MLKEM1024_AES256GCM) {
+    return "Hybrid (X25519 + ML-KEM-1024 + AES-256-GCM)";
+  }
   if (suiteId === ALGORITHM_SUITES.HYBRID_X25519_KYBER768_AES256GCM) {
-    return "Hybrid (X25519 + Kyber768 + AES-256-GCM)";
+    return "Hybrid legacy (X25519 + Kyber + AES-256-GCM, either-key)";
   }
   if (suiteId === ALGORITHM_SUITES.PASSWORD_ARGON2ID_AES256GCM) {
     return "Password (Argon2id + AES-256-GCM)";
@@ -561,61 +629,81 @@ async function kyberDecapsulate(kemCiphertextB64, secretKeyB64) {
 }
 
 // src/fs/encrypt.ts
-function hkdfFlex(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 = nacl2.box.keyPair();
-  const recipientX25519Pk = fromHex(options.recipientPublicKeys.x25519PubHex);
-  const x25519Shared = nacl2.scalarMult(x25519EphKp.secretKey, recipientX25519Pk);
-  const x25519Kek = hkdfFlex(x25519Shared, "omnituum/fs/x25519", "wrap-content-key");
-  const x25519Nonce = rand24();
-  const x25519WrappedKey = nacl2.secretbox(contentKey, x25519Nonce, x25519Kek);
-  const kyberResult = await kyberEncapsulate(options.recipientPublicKeys.kyberPubB64);
-  const kyberKek = hkdfFlex(kyberResult.sharedSecret, "omnituum/fs/kyber", "wrap-content-key");
-  const kyberNonce = rand24();
-  const kyberWrappedKey = nacl2.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 = nacl3.box.keyPair();
+    const recipientX25519Pk = fromHex(options.recipientPublicKeys.x25519PubHex);
+    const x25519Shared = nacl3.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 = nacl3.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()) {
@@ -627,37 +715,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);
@@ -698,17 +793,56 @@ async function encryptFileWithPassword(input, password) {
     password
   });
 }
-function hkdfFlex2(ikm, salt, info) {
+function hkdfFlex(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 = nacl3.scalarMult(sk, km.x25519EphemeralPk);
+  const kek = combinedFileKekV2(kyberShared, x25519Shared, x25519EpkHex, kyberKemCtB64);
+  kyberShared.fill(0);
+  x25519Shared.fill(0);
+  const contentKey = nacl3.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()) {
@@ -717,54 +851,47 @@ async function decryptHybrid(encryptedData, options) {
         toB64(km.kyberCiphertext),
         options.recipientSecretKeys.kyberSecB64
       );
-      const kyberKek = hkdfFlex2(kyberShared, "omnituum/fs/kyber", "wrap-content-key");
-      const unwrapped = nacl2.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 = hkdfFlex(kyberShared, "omnituum/fs/kyber", "wrap-content-key");
+      contentKey = nacl3.secretbox.open(km.kyberWrappedKey, km.kyberNonce, kyberKek);
+    } catch {
     }
   }
   if (!contentKey) {
     try {
-      const ephPk = km.x25519EphemeralPk;
       const sk = fromHex(options.recipientSecretKeys.x25519SecHex);
-      const x25519Shared = nacl2.scalarMult(sk, ephPk);
-      const x25519Kek = hkdfFlex2(x25519Shared, "omnituum/fs/x25519", "wrap-content-key");
-      const unwrapped = nacl2.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 = nacl3.scalarMult(sk, km.x25519EphemeralPk);
+      const x25519Kek = hkdfFlex(x25519Shared, "omnituum/fs/x25519", "wrap-content-key");
+      contentKey = nacl3.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) {
@@ -786,27 +913,27 @@ async function decryptPassword(encryptedData, options) {
     hashLength: 32,
     saltLength: km.salt.length
   });
-  let metadata;
-  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;
+  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 {
-    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);
@@ -836,9 +963,12 @@ async function inspectOQEFile(data) {
   const { header } = parseOQEFile(bytes);
   let mode;
   let algorithm;
-  if (header.algorithmSuite === ALGORITHM_SUITES.HYBRID_X25519_KYBER768_AES256GCM) {
+  if (header.algorithmSuite === ALGORITHM_SUITES.HYBRID_X25519_MLKEM1024_AES256GCM) {
+    mode = "hybrid";
+    algorithm = "X25519 + ML-KEM-1024 + AES-256-GCM (AND-combined)";
+  } else if (header.algorithmSuite === ALGORITHM_SUITES.HYBRID_X25519_KYBER768_AES256GCM) {
     mode = "hybrid";
-    algorithm = "X25519 + Kyber768 + AES-256-GCM";
+    algorithm = "X25519 + Kyber + AES-256-GCM (legacy, either-key)";
   } else {
     mode = "password";
     algorithm = "Argon2id + AES-256-GCM";
@@ -1060,4 +1190,4 @@ function isDragDropSupported() {
   return "draggable" in div || "ondragstart" in div && "ondrop" in div;
 }
 
-export { AES_GCM_IV_SIZE, AES_GCM_TAG_SIZE, AES_KEY_SIZE, ALGORITHM_SUITES, DEFAULT_ARGON2ID_PARAMS, MIN_ARGON2ID_PARAMS, OQEError, OQE_EXTENSION, OQE_FORMAT_VERSION, OQE_HEADER_SIZE, OQE_MAGIC, OQE_MIME_TYPE, STREAM_CHUNK_SIZE, addOQEExtension, aesDecrypt, aesDecryptCombined, aesDecryptStreaming, aesEncrypt, aesEncryptCombined, aesEncryptStreaming, assembleOQEFile, benchmarkArgon2, bytesToDataURL, copyToClipboard, createDropZone, createObjectURL, decryptFile, decryptFileForSelf, decryptFileWithPassword, decryptResultToBlob, deriveKeyFromPassword, downloadBlob, downloadBytes, downloadDecryptedFile, downloadEncryptedFile, encryptFile, encryptFileForSelf, encryptFileWithPassword, encryptResultToBlob, estimateArgon2Params, exportAesKey, formatFileSize, generateAesKey, generateArgon2Salt, getAlgorithmName, getFileInfo, importAesKey, inspectOQEFile, isArgon2Available, isBrowser, isDragDropSupported, isFileAPIAvailable, isOQEFile, isWebCryptoAvailable, openFilePicker, openFileToEncrypt, openOQEFilePicker, parseHybridKeyMaterial, parseMetadata, parseOQEFile, parseOQEHeader, parsePasswordKeyMaterial, readFile, readFileAsDataURL, readFileAsText, removeOQEExtension, serializeHybridKeyMaterial, serializeMetadata, serializePasswordKeyMaterial, toUint8Array, verifyPassword, writeOQEHeader };
+export { AES_GCM_IV_SIZE, AES_GCM_TAG_SIZE, AES_KEY_SIZE, ALGORITHM_SUITES, DEFAULT_ARGON2ID_PARAMS, MIN_ARGON2ID_PARAMS, OQEError, OQE_EXTENSION, OQE_FORMAT_VERSION, OQE_FORMAT_VERSION_V1, OQE_FORMAT_VERSION_V2, OQE_HEADER_SIZE, OQE_HEADER_SIZE_V1, OQE_HEADER_SIZE_V2, OQE_MAGIC, OQE_MIME_TYPE, STREAM_CHUNK_SIZE, SUPPORTED_OQE_VERSIONS, addOQEExtension, aesDecrypt, aesDecryptCombined, aesDecryptStreaming, aesEncrypt, aesEncryptCombined, aesEncryptStreaming, assembleOQEFile, benchmarkArgon2, bytesToDataURL, combinedFileKekV2, copyToClipboard, createDropZone, createObjectURL, decryptFile, decryptFileForSelf, decryptFileWithPassword, decryptResultToBlob, deriveKeyFromPassword, downloadBlob, downloadBytes, downloadDecryptedFile, downloadEncryptedFile, encryptFile, encryptFileForSelf, encryptFileWithPassword, encryptResultToBlob, estimateArgon2Params, exportAesKey, formatFileSize, generateAesKey, generateArgon2Salt, getAlgorithmName, getFileInfo, importAesKey, inspectOQEFile, isArgon2Available, isBrowser, isDragDropSupported, isFileAPIAvailable, isOQEFile, isWebCryptoAvailable, openFilePicker, openFileToEncrypt, openOQEFilePicker, oqeHeaderSize, parseHybridKeyMaterial, parseHybridKeyMaterialV2, parseMetadata, parseOQEFile, parseOQEHeader, parsePasswordKeyMaterial, readFile, readFileAsDataURL, readFileAsText, removeOQEExtension, serializeHybridKeyMaterial, serializeHybridKeyMaterialV2, serializeMetadata, serializePasswordKeyMaterial, toUint8Array, verifyPassword, writeOQEHeader };