@omnituum/pqc-shared 0.4.0 → 0.6.0

package/src/fs/format.ts

@@ -8,17 +8,26 @@
 import { textEncoder, textDecoder } from '../crypto/primitives';
 import {
   OQE_MAGIC,
-  OQE_FORMAT_VERSION,
-  OQE_HEADER_SIZE,
+  OQE_FORMAT_VERSION_V1,
+  OQE_FORMAT_VERSION_V2,
+  OQE_HEADER_SIZE_V1,
+  OQE_HEADER_SIZE_V2,
+  SUPPORTED_OQE_VERSIONS,
   ALGORITHM_SUITES,
   AlgorithmSuiteId,
   OQEHeader,
   OQEMetadata,
   HybridKeyMaterial,
+  HybridKeyMaterialV2,
   PasswordKeyMaterial,
   OQEError,
 } from './types';
 
+/** Byte length of a section's fixed header for the given format version. */
+export function oqeHeaderSize(version: number): number {
+  return version === OQE_FORMAT_VERSION_V2 ? OQE_HEADER_SIZE_V2 : OQE_HEADER_SIZE_V1;
+}
+
 // ═══════════════════════════════════════════════════════════════════════════
 // BINARY UTILITIES
 // ═══════════════════════════════════════════════════════════════════════════
@@ -48,13 +57,19 @@ function readUint16BE(data: Uint8Array, offset: number): number {
 // ═══════════════════════════════════════════════════════════════════════════
 
 /**
- * Write an OQE file header.
+ * Write an OQE file header. Layout depends on `header.version`: v2 appends a
+ * second 12-byte IV (the content IV) after the metadata IV.
+ *
+ * The returned bytes are also used verbatim as the AES-GCM associated data for
+ * both sections (v2), so every field here — version, suite, flags, lengths and
+ * both IVs — is authenticated and cannot be tampered with undetected.
  *
  * @param header - Header data
- * @returns 30-byte header buffer
+ * @returns Header buffer (30 bytes for v1, 42 bytes for v2)
  */
 export function writeOQEHeader(header: OQEHeader): Uint8Array {
-  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;
 
   // Magic bytes (4 bytes)
@@ -79,23 +94,32 @@ export function writeOQEHeader(header: OQEHeader): Uint8Array {
   buffer.set(writeUint32BE(header.keyMaterialLength), offset);
   offset += 4;
 
-  // IV (12 bytes)
+  // Metadata IV (12 bytes)
   buffer.set(header.iv, offset);
-  // offset += 12;
+  offset += 12;
+
+  // Content IV (12 bytes, v2 only)
+  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);
+    // offset += 12;
+  }
 
   return buffer;
 }
 
 /**
- * Parse an OQE file header.
+ * Parse an OQE file header (v1 or v2).
  *
- * @param data - File data (at least 30 bytes)
+ * @param data - File data
  * @returns Parsed header
  * @throws OQEError if header is invalid
  */
 export function parseOQEHeader(data: Uint8Array): OQEHeader {
-  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;
@@ -109,7 +133,7 @@ export function parseOQEHeader(data: Uint8Array): OQEHeader {
 
   // Version
   const version = data[offset++];
-  if (version !== OQE_FORMAT_VERSION) {
+  if (!SUPPORTED_OQE_VERSIONS.includes(version as typeof SUPPORTED_OQE_VERSIONS[number])) {
     throw new OQEError('UNSUPPORTED_VERSION', `Unsupported OQE version: ${version}`);
   }
 
@@ -117,12 +141,19 @@ export function parseOQEHeader(data: Uint8Array): OQEHeader {
   const algorithmSuiteRaw = data[offset++];
   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 as AlgorithmSuiteId;
 
+  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}`);
+  }
+
   // Flags
   const flags = readUint32BE(data, offset);
   offset += 4;
@@ -135,8 +166,12 @@ export function parseOQEHeader(data: Uint8Array): OQEHeader {
   const keyMaterialLength = readUint32BE(data, offset);
   offset += 4;
 
-  // IV
+  // Metadata IV
   const iv = data.slice(offset, offset + 12);
+  offset += 12;
+
+  // Content IV (v2 only)
+  const contentIv = isV2 ? data.slice(offset, offset + 12) : undefined;
 
   return {
     version,
@@ -145,6 +180,7 @@ export function parseOQEHeader(data: Uint8Array): OQEHeader {
     metadataLength,
     keyMaterialLength,
     iv,
+    contentIv,
   };
 }
 
@@ -247,6 +283,62 @@ export function parseHybridKeyMaterial(data: Uint8Array): HybridKeyMaterial {
   };
 }
 
+/**
+ * Serialize v2 hybrid key material (single AND-combined wrap).
+ *
+ * Format:
+ * - X25519 ephemeral PK (32 bytes)
+ * - Kyber ciphertext length (2 bytes) + Kyber ciphertext (variable)
+ * - Content-key wrap nonce (24 bytes)
+ * - Wrapped content key length (2 bytes) + wrapped content key (variable)
+ */
+export function serializeHybridKeyMaterialV2(km: HybridKeyMaterialV2): Uint8Array {
+  const parts: Uint8Array[] = [];
+
+  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;
+}
+
+/**
+ * Parse v2 hybrid key material (single AND-combined wrap).
+ */
+export function parseHybridKeyMaterialV2(data: Uint8Array): HybridKeyMaterialV2 {
+  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 };
+}
+
 /**
  * Serialize password mode key material.
  *
@@ -343,7 +435,7 @@ export function assembleOQEFile(components: OQEFileComponents): Uint8Array {
 export function parseOQEFile(data: Uint8Array): OQEFileComponents {
   const header = parseOQEHeader(data);
 
-  let offset = OQE_HEADER_SIZE;
+  let offset = oqeHeaderSize(header.version);
 
   // Key material
   const keyMaterial = data.slice(offset, offset + header.keyMaterialLength);
@@ -415,8 +507,11 @@ export const OQE_MIME_TYPE = 'application/x-omnituum-encrypted';
  * Get a display-friendly algorithm name from suite ID.
  */
 export function getAlgorithmName(suiteId: AlgorithmSuiteId): string {
+  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)';

package/src/fs/index.ts

@@ -62,8 +62,11 @@ export {
 export {
   writeOQEHeader,
   parseOQEHeader,
+  oqeHeaderSize,
   serializeHybridKeyMaterial,
   parseHybridKeyMaterial,
+  serializeHybridKeyMaterialV2,
+  parseHybridKeyMaterialV2,
   serializePasswordKeyMaterial,
   parsePasswordKeyMaterial,
   serializeMetadata,
@@ -83,6 +86,7 @@ export {
   encryptFile,
   encryptFileForSelf,
   encryptFileWithPassword,
+  combinedFileKekV2,
 } from './encrypt';
 
 // Main decryption API

package/src/fs/types.ts

@@ -14,18 +14,47 @@
 /** Magic bytes: "OQEF" (Omnituum Quantum Encrypted File) */
 export const OQE_MAGIC = new Uint8Array([0x4f, 0x51, 0x45, 0x46]);
 
-/** Current format version */
-export 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.
+ */
+export const OQE_FORMAT_VERSION_V1 = 1;
+export const OQE_FORMAT_VERSION_V2 = 2;
+
+/** Current (write) format version. */
+export const OQE_FORMAT_VERSION = OQE_FORMAT_VERSION_V2;
+
+/** Format versions this library can read. */
+export const SUPPORTED_OQE_VERSIONS = [OQE_FORMAT_VERSION_V1, OQE_FORMAT_VERSION_V2] as const;
 
 /** Supported encryption modes */
 export type OQEMode = 'hybrid' | 'password';
 
 /** Algorithm suite identifiers */
 export 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.
+   */
   HYBRID_X25519_KYBER768_AES256GCM: 0x01,
   /** Password: Argon2id + AES-256-GCM */
   PASSWORD_ARGON2ID_AES256GCM: 0x02,
+  /**
+   * 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: 0x03,
 } as const;
 
 export type AlgorithmSuiteId = typeof ALGORITHM_SUITES[keyof typeof ALGORITHM_SUITES];
@@ -117,12 +146,29 @@ export 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) */
-export const OQE_HEADER_SIZE = 30;
+/** Fixed v1 header size in bytes (before variable-length sections). */
+export const OQE_HEADER_SIZE_V1 = 30;
+
+/** Fixed v2 header size: v1 layout plus a 12-byte content IV. */
+export const OQE_HEADER_SIZE_V2 = 42;
+
+/**
+ * @deprecated Use OQE_HEADER_SIZE_V1 / OQE_HEADER_SIZE_V2. Retained as the v1
+ * size for source compatibility.
+ */
+export const OQE_HEADER_SIZE = OQE_HEADER_SIZE_V1;
 
 // ═══════════════════════════════════════════════════════════════════════════
 // KEY MATERIAL (Mode-Specific)
@@ -152,6 +198,31 @@ export interface HybridKeyMaterial {
   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)
+ */
+export 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)

package/src/index.ts

@@ -51,6 +51,8 @@ export type {
   HybridPublicKeys,
   HybridSecretKeys,
   HybridEnvelope,
+  HybridEnvelopeV1,
+  HybridEnvelopeV2,
 } from './crypto/hybrid';
 
 // ═══════════════════════════════════════════════════════════════════════════
@@ -69,6 +71,11 @@ export {
   kyberWrapKey,
   kyberUnwrapKey,
   KYBER_SUITE,
+  KYBER_PUBLIC_KEY_SIZE,
+  KYBER_SECRET_KEY_SIZE,
+  KYBER_CIPHERTEXT_SIZE,
+  KYBER_SHARED_SECRET_SIZE,
+  KYBER_SEED_SIZE,
 } from './crypto/kyber';
 
 export type {
@@ -365,7 +372,9 @@ export {
   VAULT_ENCRYPTED_VERSION,
   VAULT_ENCRYPTED_VERSION_V2,
   ENVELOPE_VERSION,
+  ENVELOPE_VERSION_V2,
   ENVELOPE_SUITE,
+  ENVELOPE_SUITE_V2,
   ENVELOPE_AEAD,
   VAULT_KDF,
   VAULT_KDF_V2,

package/src/utils/integrity.ts

@@ -1,22 +1,29 @@
 /**
  * Omnituum PQC Shared - Integrity Verification
  *
- * SHA-256 based integrity checking for vault contents.
+ * SHA-256 checksum over a vault's public identity records.
+ *
+ * SCOPE: this is an UNKEYED integrity checksum — it detects accidental
+ * corruption or field mix-ups, not malicious tampering. An attacker who edits
+ * the decrypted vault can simply recompute this value. Tamper *resistance* for
+ * a stored vault comes from the AES-256-GCM authentication tag on the encrypted
+ * file (see vault/encrypt.ts), not from this hash. Do not treat a matching
+ * integrity hash as authentication.
  */
 
 import type { HybridIdentityRecord } from '../vault/types';
-import { toHex } from '../crypto/primitives';
+import { sha256, toHex, textEncoder } from '../crypto/primitives';
 
 // ═══════════════════════════════════════════════════════════════════════════
 // INTEGRITY HASH
 // ═══════════════════════════════════════════════════════════════════════════
 
 /**
- * Compute SHA-256 integrity hash for a list of identities.
- * Uses only the public keys and metadata to create a deterministic hash.
+ * Compute a SHA-256 checksum for a list of identities.
+ * Uses only the public keys and metadata (never secret keys). Deterministic:
+ * the canonical objects carry a fixed key order, which JSON.stringify preserves.
  */
 export function computeIntegrityHash(identities: HybridIdentityRecord[]): string {
-  // Create a deterministic representation (exclude secret keys from hash input)
   const canonical = identities.map(i => ({
     id: i.id,
     name: i.name,
@@ -26,22 +33,16 @@ export function computeIntegrityHash(identities: HybridIdentityRecord[]): string
     rotationCount: i.rotationCount,
   }));
 
-  const serialized = JSON.stringify(canonical, Object.keys(canonical[0] || {}).sort());
+  const serialized = JSON.stringify(canonical);
   return computeStringHash(serialized);
 }
 
 /**
- * Compute SHA-256 hash of a string (synchronous fallback).
+ * Real SHA-256 of a UTF-8 string, returned as lowercase hex. Synchronous via
+ * @noble/hashes (no Web Crypto async dependency).
  */
 function computeStringHash(str: string): string {
-  // Simple hash for sync operation - actual implementation uses Web Crypto
-  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)));
 }
 
 /**

package/src/vault/manager.ts

@@ -55,7 +55,7 @@ export async function createIdentity(name: string): Promise<HybridIdentityRecord
   // Generate Kyber keypair
   const kyber = await generateKyberKeypair();
   if (!kyber) {
-    console.error('Kyber key generation failed');
+    // Backend unavailable; caller handles the null return.
     return null;
   }
 

package/src/version.ts

@@ -18,9 +18,16 @@ import {
 // VERSION CONSTANTS (FROZEN)
 // ═══════════════════════════════════════════════════════════════════════════
 
-/** HybridEnvelope version - hybrid encryption format (from registry) */
+/** HybridEnvelope v1 - independent X25519/Kyber wraps (read-only legacy; see v2) */
 export const ENVELOPE_VERSION = OMNI_VERSIONS.HYBRID_V1;
 
+/**
+ * HybridEnvelope v2 - AND-combined KEK (single wrap under
+ * HKDF(ss_mlkem || ss_x25519) with transcript binding). The version new
+ * envelopes are written in.
+ */
+export const ENVELOPE_VERSION_V2 = OMNI_VERSIONS.HYBRID_V2;
+
 /** Legacy envelope version for backwards compatibility (from registry) */
 export const ENVELOPE_VERSION_LEGACY = DEPRECATED_VERSIONS.PQC_DEMO_HYBRID_V1;
 
@@ -33,9 +40,12 @@ export const VAULT_ENCRYPTED_VERSION = 'omnituum.vault.enc.v1' as const;
 /** EncryptedVaultFile v2 - encrypted vault format (Argon2id) */
 export const VAULT_ENCRYPTED_VERSION_V2 = 'omnituum.vault.enc.v2' as const;
 
-/** Algorithm suite for hybrid encryption */
+/** Algorithm suite for hybrid encryption (v1 label — kept for wire compat) */
 export const ENVELOPE_SUITE = 'x25519+kyber768' as const;
 
+/** Algorithm suite for hybrid v2 (matches the actual ML-KEM-1024 backend) */
+export const ENVELOPE_SUITE_V2 = 'x25519+mlkem1024' as const;
+
 /** AEAD algorithm for envelope content */
 export const ENVELOPE_AEAD = 'xsalsa20poly1305' as const;
 
@@ -55,6 +65,7 @@ export const VAULT_ALGORITHM = 'AES-256-GCM' as const;
 /** Envelope versions we can read */
 export const SUPPORTED_ENVELOPE_VERSIONS = [
   ENVELOPE_VERSION,
+  ENVELOPE_VERSION_V2,
   ENVELOPE_VERSION_LEGACY,
 ] as const;
 
@@ -147,8 +158,16 @@ export function isVaultEncryptedVersionSupported(version: string): boolean {
 // ENVELOPE VALIDATION
 // ═══════════════════════════════════════════════════════════════════════════
 
+/** v1-shaped required fields: independent per-primitive wraps. */
+const ENVELOPE_V1_FIELDS = ['x25519Epk', 'x25519Wrap', 'kyberKemCt', 'kyberWrap', 'contentNonce', 'ciphertext', 'meta'];
+
+/** v2-shaped required fields: single wrap under the AND-combined KEK. */
+const ENVELOPE_V2_FIELDS = ['x25519Epk', 'kyberKemCt', 'ckWrap', 'contentNonce', 'ciphertext', 'meta'];
+
 /**
- * Validate envelope structure and version.
+ * Validate envelope structure and version. Dispatches per-version since v1
+ * and v2 have different wire shapes (independent dual wraps vs. a single
+ * AND-combined wrap) — see hybrid.ts for the security rationale.
  * Returns detailed validation result.
  */
 export function validateEnvelope(envelope: unknown): {
@@ -171,9 +190,13 @@ export function validateEnvelope(envelope: unknown): {
     errors.push(`Unsupported envelope version: ${env.v}`);
   }
 
+  const isV2 = env.v === ENVELOPE_VERSION_V2;
+  const expectedSuite = isV2 ? ENVELOPE_SUITE_V2 : ENVELOPE_SUITE;
+  const requiredFields = isV2 ? ENVELOPE_V2_FIELDS : ENVELOPE_V1_FIELDS;
+
   // Suite check
-  if (env.suite !== ENVELOPE_SUITE) {
-    errors.push(`Invalid suite: expected "${ENVELOPE_SUITE}", got "${env.suite}"`);
+  if (env.suite !== expectedSuite) {
+    errors.push(`Invalid suite: expected "${expectedSuite}", got "${env.suite}"`);
   }
 
   // AEAD check
@@ -182,8 +205,7 @@ export function validateEnvelope(envelope: unknown): {
   }
 
   // Required fields
-  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}`);
     }