@omnituum/pqc-shared 0.4.0 → 0.6.0

package/dist/crypto/index.js

@@ -195,6 +195,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;
 }
@@ -250,8 +255,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;
   }
 }
@@ -269,8 +273,7 @@ async function generateDilithiumKeypair() {
       publicB64: toB64(kp.publicKey),
       secretB64: toB64(kp.secretKey)
     };
-  } catch (e) {
-    console.warn("[Dilithium] Key generation failed:", e);
+  } catch {
     return null;
   }
 }
@@ -339,11 +342,13 @@ var DILITHIUM_SECRET_KEY_SIZE = 4032;
 var DILITHIUM_SIGNATURE_SIZE = 3309;
 var DILITHIUM_ALGORITHM = "ML-DSA-65";
 var ENVELOPE_VERSION = OMNI_VERSIONS.HYBRID_V1;
+var ENVELOPE_VERSION_V2 = OMNI_VERSIONS.HYBRID_V2;
 var ENVELOPE_VERSION_LEGACY = 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 {
@@ -375,7 +380,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 {
@@ -417,49 +421,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.secretbox(pt, contentNonce, CK);
-  const x25519EphKp = nacl.box.keyPair();
-  const recipientX25519Pk = fromHex(recipientPublicKeys.x25519PubHex);
-  const x25519Shared = nacl.scalarMult(x25519EphKp.secretKey, recipientX25519Pk);
-  const x25519Kek = hkdfFlex(x25519Shared, "omnituum/x25519", "wrap-ck");
-  const x25519WrapNonce = rand24();
-  const x25519Wrapped = nacl.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.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.secretbox(pt, contentNonce, CK);
+    const x25519EphKp = nacl.box.keyPair();
+    const recipientX25519Pk = fromHex(recipientPublicKeys.x25519PubHex);
+    const x25519Shared = nacl.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.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.scalarMult(sk, ephPk);
+  const kek = combinedKekV2(kyberShared, x25519Shared, envelope.x25519Epk, envelope.kyberKemCt);
+  kyberShared.fill(0);
+  x25519Shared.fill(0);
+  const CK = nacl.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");
@@ -468,11 +497,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 {
@@ -485,21 +510,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.secretbox.open(
     ub64(envelope.ciphertext),
     ub64(envelope.contentNonce),
     CK
   );
+  CK.fill(0);
   if (!pt) {
     throw new Error("Content authentication failed");
   }
@@ -668,4 +700,4 @@ var HKDF_SHA512_OUTPUT_SIZE = 64;
 var HKDF_SHA256_MAX_OUTPUT = 255 * 32;
 var HKDF_SHA512_MAX_OUTPUT = 255 * 64;
 
-export { BLAKE3_BLOCK_SIZE, BLAKE3_KEY_LENGTH, BLAKE3_OUTPUT_LENGTH, BOX_KEY_SIZE, BOX_NONCE_SIZE, CHACHA20_KEY_SIZE, CHACHA20_NONCE_SIZE, DILITHIUM_ALGORITHM, DILITHIUM_PUBLIC_KEY_SIZE, DILITHIUM_SECRET_KEY_SIZE, DILITHIUM_SIGNATURE_SIZE, HKDF_SHA256_MAX_OUTPUT, HKDF_SHA256_OUTPUT_SIZE, HKDF_SHA512_MAX_OUTPUT, HKDF_SHA512_OUTPUT_SIZE, KYBER_SUITE, POLY1305_TAG_SIZE, SECRETBOX_KEY_SIZE, SECRETBOX_NONCE_SIZE, SECRETBOX_OVERHEAD, 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, CHACHA20_KEY_SIZE, CHACHA20_NONCE_SIZE, DILITHIUM_ALGORITHM, DILITHIUM_PUBLIC_KEY_SIZE, DILITHIUM_SECRET_KEY_SIZE, DILITHIUM_SIGNATURE_SIZE, HKDF_SHA256_MAX_OUTPUT, HKDF_SHA256_OUTPUT_SIZE, HKDF_SHA512_MAX_OUTPUT, HKDF_SHA512_OUTPUT_SIZE, KYBER_CIPHERTEXT_SIZE, KYBER_PUBLIC_KEY_SIZE, KYBER_SECRET_KEY_SIZE, KYBER_SEED_SIZE, KYBER_SHARED_SECRET_SIZE, KYBER_SUITE, POLY1305_TAG_SIZE, SECRETBOX_KEY_SIZE, SECRETBOX_NONCE_SIZE, SECRETBOX_OVERHEAD, 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/{decrypt-eSHlbh1j.d.cts → decrypt-O1iqFIDL.d.cts}

@@ -8,16 +8,43 @@
  */
 /** Magic bytes: "OQEF" (Omnituum Quantum Encrypted File) */
 declare const OQE_MAGIC: Uint8Array<ArrayBuffer>;
-/** Current format version */
-declare const OQE_FORMAT_VERSION = 1;
+/**
+ * OQE format versions.
+ *
+ * v1 (LEGACY, read-only): a single AES-GCM IV was reused for both the
+ * metadata section and the content section under the same content key —
+ * catastrophic GCM nonce reuse — and hybrid mode wrapped the content key
+ * independently under X25519 and Kyber (either secret alone unwrapped it).
+ * Kept only so pre-existing files remain decryptable.
+ *
+ * v2 (CURRENT, write format): distinct random IVs per AES-GCM section, the
+ * serialized header bound as AEAD associated data, and hybrid mode wraps the
+ * content key once under an AND-combined KEK (HKDF(ss_mlkem || ss_x25519)
+ * with transcript binding) — both primitives must be broken to unwrap.
+ * See the 2026-07-06 fs security fix.
+ */
+declare const OQE_FORMAT_VERSION_V1 = 1;
+declare const OQE_FORMAT_VERSION_V2 = 2;
+/** Current (write) format version. */
+declare const OQE_FORMAT_VERSION = 2;
+/** Format versions this library can read. */
+declare const SUPPORTED_OQE_VERSIONS: readonly [1, 2];
 /** Supported encryption modes */
 type OQEMode = 'hybrid' | 'password';
 /** Algorithm suite identifiers */
 declare const 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.
+     */
     readonly HYBRID_X25519_KYBER768_AES256GCM: 1;
     /** Password: Argon2id + AES-256-GCM */
     readonly 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.
+     */
+    readonly HYBRID_X25519_MLKEM1024_AES256GCM: 3;
 };
 type AlgorithmSuiteId = typeof ALGORITHM_SUITES[keyof typeof ALGORITHM_SUITES];
 interface Argon2idParams {
@@ -79,10 +106,25 @@ interface OQEHeader {
     metadataLength: number;
     /** Length of key material section */
     keyMaterialLength: number;
-    /** AES-GCM initialization vector */
+    /**
+     * AES-GCM IV for the metadata section. In v1 this same IV was (incorrectly)
+     * also used for the content section; v2 uses `contentIv` for content.
+     */
     iv: Uint8Array;
+    /**
+     * AES-GCM IV for the content section (v2 only). Distinct from `iv` so the
+     * two sections never share a (key, nonce) pair. Undefined for v1 files.
+     */
+    contentIv?: Uint8Array;
 }
-/** Fixed header size in bytes (before variable-length sections) */
+/** Fixed v1 header size in bytes (before variable-length sections). */
+declare const OQE_HEADER_SIZE_V1 = 30;
+/** Fixed v2 header size: v1 layout plus a 12-byte content IV. */
+declare const OQE_HEADER_SIZE_V2 = 42;
+/**
+ * @deprecated Use OQE_HEADER_SIZE_V1 / OQE_HEADER_SIZE_V2. Retained as the v1
+ * size for source compatibility.
+ */
 declare const OQE_HEADER_SIZE = 30;
 /**
  * Hybrid Mode Key Material:
@@ -107,6 +149,30 @@ interface HybridKeyMaterial {
     /** Kyber wrap nonce */
     kyberNonce: Uint8Array;
 }
+/**
+ * v2 Hybrid Mode Key Material — single AND-combined wrap.
+ *
+ * The content key is wrapped exactly once under a KEK derived from BOTH shared
+ * secrets: HKDF(ss_mlkem || ss_x25519) with the ephemeral X25519 key and the
+ * Kyber ciphertext bound into the info string. Both the X25519 and ML-KEM
+ * exchanges must succeed to unwrap — there is no per-primitive fallback.
+ *
+ * Serialized layout:
+ * - X25519 ephemeral public key (32 bytes)
+ * - Kyber KEM ciphertext (2-byte length prefix + data)
+ * - Content-key wrap nonce (24 bytes)
+ * - Wrapped content key (2-byte length prefix + data, 48 bytes)
+ */
+interface HybridKeyMaterialV2 {
+    /** X25519 ephemeral public key */
+    x25519EphemeralPk: Uint8Array;
+    /** Kyber KEM ciphertext */
+    kyberCiphertext: Uint8Array;
+    /** Wrap nonce for the single content-key wrap (NaCl secretbox) */
+    ckWrapNonce: Uint8Array;
+    /** Content key wrapped under the AND-combined KEK */
+    ckWrapped: Uint8Array;
+}
 /**
  * Password Mode Key Material:
  * - Argon2id salt (32 bytes)
@@ -209,6 +275,14 @@ declare function toUint8Array(input: FileInput): Promise<Uint8Array>;
  * Outputs .oqe (Omnituum Quantum Encrypted) files.
  */
 
+/**
+ * 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.
+ */
+declare function combinedFileKekV2(kyberShared: Uint8Array, x25519Shared: Uint8Array, x25519EpkHex: string, kyberKemCtB64: string): Uint8Array;
 interface EncryptFileInput {
     /** File data */
     data: FileInput;
@@ -318,4 +392,4 @@ interface OQEFileInfo {
  */
 declare function inspectOQEFile(data: FileInput): Promise<OQEFileInfo>;
 
-export { type Argon2idParams as A, type DecryptOptions as D, type EncryptOptions as E, type FileInput as F, type HybridKeyMaterial as H, MIN_ARGON2ID_PARAMS as M, type OQEEncryptResult as O, type PasswordKeyMaterial as P, encryptFileWithPassword as a, decryptFileWithPassword as b, type OQEDecryptResult as c, decryptFile as d, encryptFile as e, type OQEHeader as f, type OQEMetadata as g, type AlgorithmSuiteId as h, DEFAULT_ARGON2ID_PARAMS as i, encryptFileForSelf as j, decryptFileForSelf as k, inspectOQEFile as l, type OQEMode as m, type HybridEncryptOptions as n, type PasswordEncryptOptions as o, type HybridDecryptOptions as p, type PasswordDecryptOptions as q, type OQEErrorCode as r, type ProgressCallback as s, OQEError as t, OQE_MAGIC as u, OQE_FORMAT_VERSION as v, ALGORITHM_SUITES as w, OQE_HEADER_SIZE as x, toUint8Array as y };
+export { type Argon2idParams as A, ALGORITHM_SUITES as B, OQE_HEADER_SIZE_V1 as C, type DecryptOptions as D, type EncryptOptions as E, type FileInput as F, OQE_HEADER_SIZE_V2 as G, type HybridKeyMaterial as H, OQE_HEADER_SIZE as I, toUint8Array as J, MIN_ARGON2ID_PARAMS as M, type OQEEncryptResult as O, type PasswordKeyMaterial as P, SUPPORTED_OQE_VERSIONS as S, encryptFileWithPassword as a, decryptFileWithPassword as b, type OQEDecryptResult as c, decryptFile as d, encryptFile as e, type OQEHeader as f, type HybridKeyMaterialV2 as g, type OQEMetadata as h, type AlgorithmSuiteId as i, DEFAULT_ARGON2ID_PARAMS as j, encryptFileForSelf as k, combinedFileKekV2 as l, decryptFileForSelf as m, inspectOQEFile as n, type OQEMode as o, type HybridEncryptOptions as p, type PasswordEncryptOptions as q, type HybridDecryptOptions as r, type PasswordDecryptOptions as s, type OQEErrorCode as t, type ProgressCallback as u, OQEError as v, OQE_MAGIC as w, OQE_FORMAT_VERSION_V1 as x, OQE_FORMAT_VERSION_V2 as y, OQE_FORMAT_VERSION as z };

package/dist/{decrypt-eSHlbh1j.d.ts → decrypt-O1iqFIDL.d.ts}

@@ -8,16 +8,43 @@
  */
 /** Magic bytes: "OQEF" (Omnituum Quantum Encrypted File) */
 declare const OQE_MAGIC: Uint8Array<ArrayBuffer>;
-/** Current format version */
-declare const OQE_FORMAT_VERSION = 1;
+/**
+ * OQE format versions.
+ *
+ * v1 (LEGACY, read-only): a single AES-GCM IV was reused for both the
+ * metadata section and the content section under the same content key —
+ * catastrophic GCM nonce reuse — and hybrid mode wrapped the content key
+ * independently under X25519 and Kyber (either secret alone unwrapped it).
+ * Kept only so pre-existing files remain decryptable.
+ *
+ * v2 (CURRENT, write format): distinct random IVs per AES-GCM section, the
+ * serialized header bound as AEAD associated data, and hybrid mode wraps the
+ * content key once under an AND-combined KEK (HKDF(ss_mlkem || ss_x25519)
+ * with transcript binding) — both primitives must be broken to unwrap.
+ * See the 2026-07-06 fs security fix.
+ */
+declare const OQE_FORMAT_VERSION_V1 = 1;
+declare const OQE_FORMAT_VERSION_V2 = 2;
+/** Current (write) format version. */
+declare const OQE_FORMAT_VERSION = 2;
+/** Format versions this library can read. */
+declare const SUPPORTED_OQE_VERSIONS: readonly [1, 2];
 /** Supported encryption modes */
 type OQEMode = 'hybrid' | 'password';
 /** Algorithm suite identifiers */
 declare const 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.
+     */
     readonly HYBRID_X25519_KYBER768_AES256GCM: 1;
     /** Password: Argon2id + AES-256-GCM */
     readonly 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.
+     */
+    readonly HYBRID_X25519_MLKEM1024_AES256GCM: 3;
 };
 type AlgorithmSuiteId = typeof ALGORITHM_SUITES[keyof typeof ALGORITHM_SUITES];
 interface Argon2idParams {
@@ -79,10 +106,25 @@ interface OQEHeader {
     metadataLength: number;
     /** Length of key material section */
     keyMaterialLength: number;
-    /** AES-GCM initialization vector */
+    /**
+     * AES-GCM IV for the metadata section. In v1 this same IV was (incorrectly)
+     * also used for the content section; v2 uses `contentIv` for content.
+     */
     iv: Uint8Array;
+    /**
+     * AES-GCM IV for the content section (v2 only). Distinct from `iv` so the
+     * two sections never share a (key, nonce) pair. Undefined for v1 files.
+     */
+    contentIv?: Uint8Array;
 }
-/** Fixed header size in bytes (before variable-length sections) */
+/** Fixed v1 header size in bytes (before variable-length sections). */
+declare const OQE_HEADER_SIZE_V1 = 30;
+/** Fixed v2 header size: v1 layout plus a 12-byte content IV. */
+declare const OQE_HEADER_SIZE_V2 = 42;
+/**
+ * @deprecated Use OQE_HEADER_SIZE_V1 / OQE_HEADER_SIZE_V2. Retained as the v1
+ * size for source compatibility.
+ */
 declare const OQE_HEADER_SIZE = 30;
 /**
  * Hybrid Mode Key Material:
@@ -107,6 +149,30 @@ interface HybridKeyMaterial {
     /** Kyber wrap nonce */
     kyberNonce: Uint8Array;
 }
+/**
+ * v2 Hybrid Mode Key Material — single AND-combined wrap.
+ *
+ * The content key is wrapped exactly once under a KEK derived from BOTH shared
+ * secrets: HKDF(ss_mlkem || ss_x25519) with the ephemeral X25519 key and the
+ * Kyber ciphertext bound into the info string. Both the X25519 and ML-KEM
+ * exchanges must succeed to unwrap — there is no per-primitive fallback.
+ *
+ * Serialized layout:
+ * - X25519 ephemeral public key (32 bytes)
+ * - Kyber KEM ciphertext (2-byte length prefix + data)
+ * - Content-key wrap nonce (24 bytes)
+ * - Wrapped content key (2-byte length prefix + data, 48 bytes)
+ */
+interface HybridKeyMaterialV2 {
+    /** X25519 ephemeral public key */
+    x25519EphemeralPk: Uint8Array;
+    /** Kyber KEM ciphertext */
+    kyberCiphertext: Uint8Array;
+    /** Wrap nonce for the single content-key wrap (NaCl secretbox) */
+    ckWrapNonce: Uint8Array;
+    /** Content key wrapped under the AND-combined KEK */
+    ckWrapped: Uint8Array;
+}
 /**
  * Password Mode Key Material:
  * - Argon2id salt (32 bytes)
@@ -209,6 +275,14 @@ declare function toUint8Array(input: FileInput): Promise<Uint8Array>;
  * Outputs .oqe (Omnituum Quantum Encrypted) files.
  */
 
+/**
+ * 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.
+ */
+declare function combinedFileKekV2(kyberShared: Uint8Array, x25519Shared: Uint8Array, x25519EpkHex: string, kyberKemCtB64: string): Uint8Array;
 interface EncryptFileInput {
     /** File data */
     data: FileInput;
@@ -318,4 +392,4 @@ interface OQEFileInfo {
  */
 declare function inspectOQEFile(data: FileInput): Promise<OQEFileInfo>;
 
-export { type Argon2idParams as A, type DecryptOptions as D, type EncryptOptions as E, type FileInput as F, type HybridKeyMaterial as H, MIN_ARGON2ID_PARAMS as M, type OQEEncryptResult as O, type PasswordKeyMaterial as P, encryptFileWithPassword as a, decryptFileWithPassword as b, type OQEDecryptResult as c, decryptFile as d, encryptFile as e, type OQEHeader as f, type OQEMetadata as g, type AlgorithmSuiteId as h, DEFAULT_ARGON2ID_PARAMS as i, encryptFileForSelf as j, decryptFileForSelf as k, inspectOQEFile as l, type OQEMode as m, type HybridEncryptOptions as n, type PasswordEncryptOptions as o, type HybridDecryptOptions as p, type PasswordDecryptOptions as q, type OQEErrorCode as r, type ProgressCallback as s, OQEError as t, OQE_MAGIC as u, OQE_FORMAT_VERSION as v, ALGORITHM_SUITES as w, OQE_HEADER_SIZE as x, toUint8Array as y };
+export { type Argon2idParams as A, ALGORITHM_SUITES as B, OQE_HEADER_SIZE_V1 as C, type DecryptOptions as D, type EncryptOptions as E, type FileInput as F, OQE_HEADER_SIZE_V2 as G, type HybridKeyMaterial as H, OQE_HEADER_SIZE as I, toUint8Array as J, MIN_ARGON2ID_PARAMS as M, type OQEEncryptResult as O, type PasswordKeyMaterial as P, SUPPORTED_OQE_VERSIONS as S, encryptFileWithPassword as a, decryptFileWithPassword as b, type OQEDecryptResult as c, decryptFile as d, encryptFile as e, type OQEHeader as f, type HybridKeyMaterialV2 as g, type OQEMetadata as h, type AlgorithmSuiteId as i, DEFAULT_ARGON2ID_PARAMS as j, encryptFileForSelf as k, combinedFileKekV2 as l, decryptFileForSelf as m, inspectOQEFile as n, type OQEMode as o, type HybridEncryptOptions as p, type PasswordEncryptOptions as q, type HybridDecryptOptions as r, type PasswordDecryptOptions as s, type OQEErrorCode as t, type ProgressCallback as u, OQEError as v, OQE_MAGIC as w, OQE_FORMAT_VERSION_V1 as x, OQE_FORMAT_VERSION_V2 as y, OQE_FORMAT_VERSION as z };