@omnituum/pqc-shared 0.4.1 → 0.6.0

package/src/fs/decrypt.ts

@@ -7,13 +7,17 @@
 import nacl from 'tweetnacl';
 import {
   fromHex,
+  toHex,
   hkdfSha256,
   toB64,
+  b64,
   u8,
 } from '../crypto/primitives';
 import { kyberDecapsulate, isKyberAvailable } from '../crypto/kyber';
 import {
   ALGORITHM_SUITES,
+  OQE_FORMAT_VERSION_V2,
+  OQEHeader,
   OQEMetadata,
   HybridDecryptOptions,
   PasswordDecryptOptions,
@@ -23,13 +27,16 @@ import {
   FileInput,
   toUint8Array,
 } from './types';
+import { combinedFileKekV2 } from './encrypt';
 import { deriveKeyFromPassword, isArgon2Available } from './argon2';
 import { aesDecrypt } from './aes';
 import {
   parseOQEFile,
   parseHybridKeyMaterial,
+  parseHybridKeyMaterialV2,
   parsePasswordKeyMaterial,
   parseMetadata,
+  writeOQEHeader,
 } from './format';
 
 // ═══════════════════════════════════════════════════════════════════════════
@@ -40,69 +47,120 @@ function hkdfFlex(ikm: Uint8Array, salt: string, info: string): Uint8Array {
   return hkdfSha256(ikm, { salt: u8(salt), info: u8(info), length: 32 });
 }
 
+/**
+ * Reconstruct the AEAD associated data for a parsed v2 header. Re-serializing
+ * the parsed header yields the exact bytes bound at encryption time, so any
+ * mutation of version/suite/flags/lengths/IVs makes AES-GCM authentication fail.
+ */
+function headerAad(header: OQEHeader): Uint8Array {
+  return writeOQEHeader(header);
+}
+
 // ═══════════════════════════════════════════════════════════════════════════
 // HYBRID MODE DECRYPTION
 // ═══════════════════════════════════════════════════════════════════════════
 
 /**
- * Decrypt an OQE file using hybrid X25519 + Kyber768.
- * Tries Kyber first (post-quantum), falls back to X25519 (classical).
+ * Decrypt an OQE hybrid file. Dispatches by suite:
+ * - v2 (ML-KEM-1024, suite 0x03): single AND-combined KEK — both the X25519 and
+ *   ML-KEM secrets are required and there is no per-primitive fallback.
+ * - v1 legacy (Kyber, suite 0x01): read-only compatibility path where either
+ *   secret alone unwraps the content key (the weakness v2 exists to fix).
  */
 async function decryptHybrid(
   encryptedData: Uint8Array,
   options: HybridDecryptOptions
 ): Promise<OQEDecryptResult> {
-  // Parse file structure
-  const { header, keyMaterial, encryptedMetadata, encryptedContent } = parseOQEFile(encryptedData);
+  const parsed = parseOQEFile(encryptedData);
+  const { header } = parsed;
 
-  // Verify algorithm
-  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.'
-    );
+  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.'
+  );
+}
+
+type ParsedFile = ReturnType<typeof parseOQEFile>;
+
+/** v2 AND-combined hybrid decryption (both secrets required, header AAD-bound). */
+async function decryptHybridV2(
+  parsed: ParsedFile,
+  options: HybridDecryptOptions
+): Promise<OQEDecryptResult> {
+  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);
+  // Must match encryptHybrid's transcript exactly: plain hex, no "0x" prefix.
+  const x25519EpkHex = toHex(km.x25519EphemeralPk);
+  const kyberKemCtB64 = b64(km.kyberCiphertext);
+
+  // ML-KEM decapsulation (post-quantum half). No classical fallback in v2.
+  const kyberShared = await kyberDecapsulate(kyberKemCtB64, options.recipientSecretKeys.kyberSecB64);
+
+  // X25519 ECDH (classical half).
+  const sk = fromHex(options.recipientSecretKeys.x25519SecHex);
+  const x25519Shared = nacl.scalarMult(sk, km.x25519EphemeralPk);
+
+  const kek = combinedFileKekV2(kyberShared, x25519Shared, x25519EpkHex, kyberKemCtB64);
+  kyberShared.fill(0);
+  x25519Shared.fill(0);
+
+  const contentKey = nacl.secretbox.open(km.ckWrapped, km.ckWrapNonce, kek);
+  kek.fill(0);
+  if (!contentKey) {
+    throw new OQEError('KEY_UNWRAP_FAILED', 'Could not unwrap content key — 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);
   }
+}
 
-  // Parse key material
+/** LEGACY read-only: v1 either-key hybrid. Single IV, no AAD. */
+async function decryptHybridV1Legacy(
+  parsed: ParsedFile,
+  options: HybridDecryptOptions
+): Promise<OQEDecryptResult> {
+  const { header, keyMaterial, encryptedMetadata, encryptedContent } = parsed;
   const km = parseHybridKeyMaterial(keyMaterial);
 
   let contentKey: Uint8Array | null = null;
 
-  // Try Kyber first (post-quantum path)
   if (await isKyberAvailable()) {
     try {
-      // Kyber decapsulate expects base64 ciphertext
       const kyberShared = await kyberDecapsulate(
         toB64(km.kyberCiphertext),
         options.recipientSecretKeys.kyberSecB64
       );
       const kyberKek = hkdfFlex(kyberShared, 'omnituum/fs/kyber', 'wrap-content-key');
-      const unwrapped = nacl.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);
+      contentKey = nacl.secretbox.open(km.kyberWrappedKey, km.kyberNonce, kyberKek);
+    } catch {
+      // Fall through to the classical wrap.
     }
   }
 
-  // Fall back to X25519 (classical path)
   if (!contentKey) {
     try {
-      const ephPk = km.x25519EphemeralPk;
       const sk = fromHex(options.recipientSecretKeys.x25519SecHex);
-      const x25519Shared = nacl.scalarMult(sk, ephPk);
+      const x25519Shared = nacl.scalarMult(sk, km.x25519EphemeralPk);
       const x25519Kek = hkdfFlex(x25519Shared, 'omnituum/fs/x25519', 'wrap-content-key');
-      const unwrapped = nacl.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);
+      contentKey = nacl.secretbox.open(km.x25519WrappedKey, km.x25519Nonce, x25519Kek);
+    } catch {
+      // Handled below.
     }
   }
 
@@ -110,30 +168,43 @@ async function decryptHybrid(
     throw new OQEError('KEY_UNWRAP_FAILED', 'Could not unwrap content key with provided keys');
   }
 
-  // Decrypt metadata
-  let metadata: OQEMetadata;
   try {
-    const metadataBytes = await aesDecrypt(encryptedMetadata, contentKey, header.iv);
-    metadata = parseMetadata(metadataBytes);
-  } catch (e) {
-    throw new OQEError('DECRYPTION_FAILED', 'Failed to decrypt file metadata');
+    // v1 reused header.iv for both sections; preserved for read compatibility.
+    const metadata = await decryptSection(encryptedMetadata, contentKey, header.iv, undefined, 'metadata');
+    const plaintext = await aesDecrypt(encryptedContent, contentKey, header.iv);
+    return buildResult(plaintext, metadata, 'hybrid');
+  } finally {
+    contentKey.fill(0);
   }
+}
 
-  // Decrypt file content
-  let plaintext: Uint8Array;
+async function decryptSection(
+  ciphertext: Uint8Array,
+  key: Uint8Array,
+  iv: Uint8Array,
+  aad: Uint8Array | undefined,
+  what: 'metadata'
+): Promise<OQEMetadata> {
   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: Uint8Array,
+  metadata: OQEMetadata,
+  mode: 'hybrid' | 'password'
+): OQEDecryptResult {
   return {
     data: plaintext,
     filename: metadata.filename,
     mimeType: metadata.mimeType,
     originalSize: metadata.originalSize,
     metadata,
-    mode: 'hybrid',
+    mode,
   };
 }
 
@@ -176,31 +247,34 @@ async function decryptPassword(
     saltLength: km.salt.length,
   });
 
-  // Decrypt metadata (also verifies password)
-  let metadata: OQEMetadata;
-  try {
-    const metadataBytes = await aesDecrypt(encryptedMetadata, contentKey, header.iv);
-    metadata = parseMetadata(metadataBytes);
-  } catch (e) {
-    throw new OQEError('PASSWORD_WRONG', 'Incorrect password or corrupted file');
-  }
+  // v2 binds the header as AAD and uses a distinct content IV; v1 reused
+  // header.iv for both sections and had no AAD.
+  const isV2 = header.version === OQE_FORMAT_VERSION_V2;
+  const aad = isV2 ? headerAad(header) : undefined;
+  const contentIv = isV2 && header.contentIv ? header.contentIv : header.iv;
 
-  // Decrypt file content
-  let plaintext: Uint8Array;
   try {
-    plaintext = await aesDecrypt(encryptedContent, contentKey, header.iv);
-  } catch (e) {
-    throw new OQEError('DECRYPTION_FAILED', 'Failed to decrypt file content');
-  }
+    // Decrypt metadata (also verifies password).
+    let metadata: OQEMetadata;
+    try {
+      const metadataBytes = await aesDecrypt(encryptedMetadata, contentKey, header.iv, aad);
+      metadata = parseMetadata(metadataBytes);
+    } catch {
+      throw new OQEError('PASSWORD_WRONG', 'Incorrect password or corrupted file');
+    }
 
-  return {
-    data: plaintext,
-    filename: metadata.filename,
-    mimeType: metadata.mimeType,
-    originalSize: metadata.originalSize,
-    metadata,
-    mode: 'password',
-  };
+    // Decrypt file content.
+    let plaintext: Uint8Array;
+    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);
+  }
 }
 
 // ═══════════════════════════════════════════════════════════════════════════
@@ -302,9 +376,12 @@ export async function inspectOQEFile(data: FileInput): Promise<OQEFileInfo> {
   let mode: 'hybrid' | 'password';
   let algorithm: string;
 
-  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';

package/src/fs/encrypt.ts

@@ -12,17 +12,18 @@ import {
   rand12,
   toHex,
   fromHex,
+  b64,
   hkdfSha256,
   sha256,
   u8,
 } from '../crypto/primitives';
 import { kyberEncapsulate, isKyberAvailable } from '../crypto/kyber';
 import {
-  OQE_FORMAT_VERSION,
+  OQE_FORMAT_VERSION_V2,
   ALGORITHM_SUITES,
   OQEMetadata,
   OQEHeader,
-  HybridKeyMaterial,
+  HybridKeyMaterialV2,
   PasswordKeyMaterial,
   HybridEncryptOptions,
   PasswordEncryptOptions,
@@ -34,35 +35,69 @@ import {
   DEFAULT_ARGON2ID_PARAMS,
 } from './types';
 import { deriveKeyFromPassword, generateArgon2Salt, isArgon2Available } from './argon2';
-import { aesEncrypt } from './aes';
+import { aesEncrypt, AES_GCM_TAG_SIZE } from './aes';
 import {
-  serializeHybridKeyMaterial,
+  serializeHybridKeyMaterialV2,
   serializePasswordKeyMaterial,
   serializeMetadata,
+  writeOQEHeader,
   assembleOQEFile,
   addOQEExtension,
 } from './format';
 
+// AES-GCM tag length is fixed at 16 bytes, so GCM ciphertext length is known
+// before encryption. This lets us build (and thus AAD-bind) the full header,
+// including metadataLength, prior to the actual encrypt calls.
+const AES_GCM_TAG_LEN = AES_GCM_TAG_SIZE;
+
 // ═══════════════════════════════════════════════════════════════════════════
 // HELPERS
 // ═══════════════════════════════════════════════════════════════════════════
 
-function hkdfFlex(ikm: Uint8Array, salt: string, info: string): Uint8Array {
-  return hkdfSha256(ikm, { salt: u8(salt), info: u8(info), length: 32 });
-}
-
 function computeIdentityHash(publicKeyHex: string): string {
   const hash = sha256(fromHex(publicKeyHex));
   return toHex(hash).slice(0, 16); // First 8 bytes = 16 hex chars
 }
 
+/**
+ * Derive the v2 AND-combined KEK for file encryption. Requires BOTH shared
+ * secrets; the envelope's own KEM values are bound into the HKDF info so a
+ * spliced ephemeral key or Kyber ciphertext derives a different KEK and the
+ * wrap fails authentication (X-Wing-style transcript binding). Domain-separated
+ * from the message-envelope KEK via the "omnituum/fs/hybrid-v2" salt.
+ */
+export function combinedFileKekV2(
+  kyberShared: Uint8Array,
+  x25519Shared: Uint8Array,
+  x25519EpkHex: string,
+  kyberKemCtB64: string
+): Uint8Array {
+  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);
+  }
+}
+
 // ═══════════════════════════════════════════════════════════════════════════
 // HYBRID MODE ENCRYPTION
 // ═══════════════════════════════════════════════════════════════════════════
 
 /**
- * Encrypt a file using hybrid X25519 + Kyber768 encryption.
- * Provides post-quantum security through dual-algorithm key wrapping.
+ * Encrypt a file using hybrid X25519 + ML-KEM-1024 encryption (OQE v2).
+ *
+ * The content key is wrapped exactly once, under a KEK derived from BOTH shared
+ * secrets together (AND-combined) — breaking either primitive alone is
+ * insufficient to unwrap. Metadata and content are encrypted under separate
+ * AES-GCM IVs, and the full serialized header (version, suite, flags, lengths,
+ * both IVs) is bound as AEAD associated data.
  */
 async function encryptHybrid(
   plaintext: Uint8Array,
@@ -77,65 +112,74 @@ async function encryptHybrid(
   // 1. Generate random content key (32 bytes for AES-256)
   const contentKey = rand32();
 
-  // 2. Generate IV for AES-GCM
-  const iv = rand12();
-
-  // 3. Wrap content key with X25519 ECDH
-  const x25519EphKp = nacl.box.keyPair();
-  const recipientX25519Pk = fromHex(options.recipientPublicKeys.x25519PubHex);
-  const x25519Shared = nacl.scalarMult(x25519EphKp.secretKey, recipientX25519Pk);
-  const x25519Kek = hkdfFlex(x25519Shared, 'omnituum/fs/x25519', 'wrap-content-key');
-  const x25519Nonce = rand24();
-  const x25519WrappedKey = nacl.secretbox(contentKey, x25519Nonce, x25519Kek);
-
-  // 4. Wrap content key with Kyber KEM
-  const kyberResult = await kyberEncapsulate(options.recipientPublicKeys.kyberPubB64);
-  const kyberKek = hkdfFlex(kyberResult.sharedSecret, 'omnituum/fs/kyber', 'wrap-content-key');
-  const kyberNonce = rand24();
-  const kyberWrappedKey = nacl.secretbox(contentKey, kyberNonce, kyberKek);
-
-  // 5. Serialize key material
-  const keyMaterial: HybridKeyMaterial = {
-    x25519EphemeralPk: x25519EphKp.publicKey,
-    x25519Nonce,
-    x25519WrappedKey,
-    kyberCiphertext: kyberResult.ciphertext,
-    kyberNonce,
-    kyberWrappedKey,
-  };
-  const keyMaterialBytes = serializeHybridKeyMaterial(keyMaterial);
-
-  // 6. Encrypt metadata
-  const metadataBytes = serializeMetadata(metadata);
-  const { ciphertext: encryptedMetadata } = await aesEncrypt(metadataBytes, contentKey, iv);
-
-  // 7. Encrypt file content
-  const { ciphertext: encryptedContent } = await aesEncrypt(plaintext, contentKey, iv);
-
-  // 8. Build header
-  const header: OQEHeader = {
-    version: OQE_FORMAT_VERSION,
-    algorithmSuite: ALGORITHM_SUITES.HYBRID_X25519_KYBER768_AES256GCM,
-    flags: 0,
-    metadataLength: encryptedMetadata.length,
-    keyMaterialLength: keyMaterialBytes.length,
-    iv,
-  };
-
-  // 9. Assemble complete file
-  const fileData = assembleOQEFile({
-    header,
-    keyMaterial: keyMaterialBytes,
-    encryptedMetadata,
-    encryptedContent,
-  });
-
-  return {
-    data: fileData,
-    filename: addOQEExtension(metadata.filename),
-    metadata,
-    mode: 'hybrid',
-  };
+  try {
+    // 2. Separate IVs for metadata and content — never reuse a (key, nonce) pair.
+    const metadataIv = rand12();
+    const contentIv = rand12();
+
+    // 3. X25519 ECDH shared secret (ephemeral)
+    const x25519EphKp = nacl.box.keyPair();
+    const recipientX25519Pk = fromHex(options.recipientPublicKeys.x25519PubHex);
+    const x25519Shared = nacl.scalarMult(x25519EphKp.secretKey, recipientX25519Pk);
+    const x25519EpkHex = toHex(x25519EphKp.publicKey);
+
+    // 4. ML-KEM-1024 shared secret
+    const kyberResult = await kyberEncapsulate(options.recipientPublicKeys.kyberPubB64);
+    const kyberKemCtB64 = b64(kyberResult.ciphertext);
+
+    // 5. Single wrap under the AND-combined, transcript-bound KEK.
+    const kek = combinedFileKekV2(kyberResult.sharedSecret, x25519Shared, x25519EpkHex, kyberKemCtB64);
+    const ckWrapNonce = rand24();
+    const ckWrapped = nacl.secretbox(contentKey, ckWrapNonce, kek);
+    kek.fill(0);
+    x25519Shared.fill(0);
+    kyberResult.sharedSecret.fill(0);
+    x25519EphKp.secretKey.fill(0);
+
+    // 6. Serialize key material
+    const keyMaterial: HybridKeyMaterialV2 = {
+      x25519EphemeralPk: x25519EphKp.publicKey,
+      kyberCiphertext: kyberResult.ciphertext,
+      ckWrapNonce,
+      ckWrapped,
+    };
+    const keyMaterialBytes = serializeHybridKeyMaterialV2(keyMaterial);
+
+    // 7. Build header up-front so it can be used as AAD. GCM ciphertext length
+    //    is plaintext length + tag, so metadataLength is known before encrypting.
+    const metadataBytes = serializeMetadata(metadata);
+    const header: OQEHeader = {
+      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);
+
+    // 8. Encrypt metadata and content under distinct IVs, header bound as AAD.
+    const { ciphertext: encryptedMetadata } = await aesEncrypt(metadataBytes, contentKey, metadataIv, aad);
+    const { ciphertext: encryptedContent } = await aesEncrypt(plaintext, contentKey, contentIv, aad);
+
+    // 9. Assemble complete file
+    const fileData = assembleOQEFile({
+      header,
+      keyMaterial: keyMaterialBytes,
+      encryptedMetadata,
+      encryptedContent,
+    });
+
+    return {
+      data: fileData,
+      filename: addOQEExtension(metadata.filename),
+      metadata,
+      mode: 'hybrid',
+    };
+  } finally {
+    contentKey.fill(0);
+  }
 }
 
 // ═══════════════════════════════════════════════════════════════════════════
@@ -168,49 +212,54 @@ async function encryptPassword(
   // 2. Derive content key from password
   const contentKey = await deriveKeyFromPassword(options.password, salt, params);
 
-  // 3. Generate IV for AES-GCM
-  const iv = rand12();
-
-  // 4. Serialize key material (Argon2 params + salt)
-  const keyMaterial: PasswordKeyMaterial = {
-    salt,
-    memoryCost: params.memoryCost,
-    timeCost: params.timeCost,
-    parallelism: params.parallelism,
-  };
-  const keyMaterialBytes = serializePasswordKeyMaterial(keyMaterial);
-
-  // 5. Encrypt metadata
-  const metadataBytes = serializeMetadata(metadata);
-  const { ciphertext: encryptedMetadata } = await aesEncrypt(metadataBytes, contentKey, iv);
-
-  // 6. Encrypt file content
-  const { ciphertext: encryptedContent } = await aesEncrypt(plaintext, contentKey, iv);
-
-  // 7. Build header
-  const header: OQEHeader = {
-    version: OQE_FORMAT_VERSION,
-    algorithmSuite: ALGORITHM_SUITES.PASSWORD_ARGON2ID_AES256GCM,
-    flags: 0,
-    metadataLength: encryptedMetadata.length,
-    keyMaterialLength: keyMaterialBytes.length,
-    iv,
-  };
-
-  // 8. Assemble complete file
-  const fileData = assembleOQEFile({
-    header,
-    keyMaterial: keyMaterialBytes,
-    encryptedMetadata,
-    encryptedContent,
-  });
-
-  return {
-    data: fileData,
-    filename: addOQEExtension(metadata.filename),
-    metadata,
-    mode: 'password',
-  };
+  try {
+    // 3. Separate IVs for metadata and content — never reuse a (key, nonce) pair.
+    const metadataIv = rand12();
+    const contentIv = rand12();
+
+    // 4. Serialize key material (Argon2 params + salt)
+    const keyMaterial: PasswordKeyMaterial = {
+      salt,
+      memoryCost: params.memoryCost,
+      timeCost: params.timeCost,
+      parallelism: params.parallelism,
+    };
+    const keyMaterialBytes = serializePasswordKeyMaterial(keyMaterial);
+
+    // 5. Build header up-front for AAD binding.
+    const metadataBytes = serializeMetadata(metadata);
+    const header: OQEHeader = {
+      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);
+
+    // 6. Encrypt metadata and content under distinct IVs, header bound as AAD.
+    const { ciphertext: encryptedMetadata } = await aesEncrypt(metadataBytes, contentKey, metadataIv, aad);
+    const { ciphertext: encryptedContent } = await aesEncrypt(plaintext, contentKey, contentIv, aad);
+
+    // 7. Assemble complete file
+    const fileData = assembleOQEFile({
+      header,
+      keyMaterial: keyMaterialBytes,
+      encryptedMetadata,
+      encryptedContent,
+    });
+
+    return {
+      data: fileData,
+      filename: addOQEExtension(metadata.filename),
+      metadata,
+      mode: 'password',
+    };
+  } finally {
+    contentKey.fill(0);
+  }
 }
 
 // ═══════════════════════════════════════════════════════════════════════════