@omnituum/pqc-shared 0.4.1 → 0.6.0

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 };