@omnituum/pqc-shared 0.2.6

package/src/crypto/x25519.ts

@@ -0,0 +1,134 @@
+/**
+ * Omnituum PQC Shared - X25519 Key Exchange
+ *
+ * Browser-compatible X25519 operations using tweetnacl.
+ * Provides key generation, ECDH, and NaCl box operations.
+ */
+
+import nacl from 'tweetnacl';
+import { rand24, assertLen, toHex, fromHex, b64, ub64, sha256, hkdfSha256, u8 } from './primitives';
+
+// ═══════════════════════════════════════════════════════════════════════════
+// TYPES
+// ═══════════════════════════════════════════════════════════════════════════
+
+export interface X25519Keypair {
+  publicKey: Uint8Array;
+  secretKey: Uint8Array;
+}
+
+export interface X25519KeypairHex {
+  publicHex: string;
+  secretHex: string;
+  publicBytes: Uint8Array;
+  secretBytes: Uint8Array;
+}
+
+export interface ClassicalWrap {
+  ephPubKey: string;
+  nonce: string;
+  boxed: string;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// KEY GENERATION
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Generate a new random X25519 keypair.
+ */
+export function generateX25519Keypair(): X25519KeypairHex {
+  const kp = nacl.box.keyPair();
+  return {
+    publicHex: '0x' + toHex(kp.publicKey),
+    secretHex: '0x' + toHex(kp.secretKey),
+    publicBytes: kp.publicKey,
+    secretBytes: kp.secretKey,
+  };
+}
+
+/**
+ * Generate a deterministic X25519 keypair from a 32-byte seed.
+ */
+export function generateX25519KeypairFromSeed(seed: Uint8Array): X25519Keypair {
+  if (seed.length !== 32) {
+    throw new Error('X25519 seed must be 32 bytes');
+  }
+
+  // Hash seed for uniformity
+  const uniformSeed = sha256(seed);
+
+  // Generate keypair from secret key
+  const kp = nacl.box.keyPair.fromSecretKey(uniformSeed);
+
+  return {
+    publicKey: kp.publicKey,
+    secretKey: uniformSeed,
+  };
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// KEY WRAPPING
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Wrap a symmetric key for a recipient using X25519 ECDH.
+ * Creates an ephemeral keypair and encrypts the key using NaCl box.
+ */
+export function boxWrapWithX25519(symKey32: Uint8Array, recipientPubKeyHex: string): ClassicalWrap {
+  assertLen('sym key', symKey32, 32);
+  const pk = fromHex(recipientPubKeyHex);
+  assertLen('recipient pubKey', pk, 32);
+
+  // Generate ephemeral keypair
+  const eph = nacl.box.keyPair();
+  const nonce = rand24();
+
+  // Encrypt the symmetric key
+  const boxed = nacl.box(symKey32, nonce, pk, eph.secretKey);
+
+  return {
+    ephPubKey: toHex(eph.publicKey),
+    nonce: b64(nonce),
+    boxed: b64(boxed),
+  };
+}
+
+/**
+ * Unwrap a symmetric key using X25519 ECDH.
+ */
+export function boxUnwrapWithX25519(
+  wrap: ClassicalWrap,
+  recipientSecretKey32: Uint8Array
+): Uint8Array | null {
+  assertLen('recipient secretKey', recipientSecretKey32, 32);
+  const ephPk = fromHex(wrap.ephPubKey);
+  assertLen('ephemeral pubKey', ephPk, 32);
+
+  return nacl.box.open(
+    ub64(wrap.boxed),
+    ub64(wrap.nonce),
+    ephPk,
+    recipientSecretKey32
+  ) || null;
+}
+
+/**
+ * Perform raw X25519 ECDH to derive a shared secret.
+ */
+export function x25519SharedSecret(
+  ourSecretKey: Uint8Array,
+  theirPublicKey: Uint8Array
+): Uint8Array {
+  assertLen('secret key', ourSecretKey, 32);
+  assertLen('public key', theirPublicKey, 32);
+  return nacl.scalarMult(ourSecretKey, theirPublicKey);
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// HKDF KEY DERIVATION HELPER
+// ═══════════════════════════════════════════════════════════════════════════
+
+export function deriveKeyFromShared(shared: Uint8Array, salt: string, info: string): Uint8Array {
+  return hkdfSha256(shared, { salt: u8(salt), info: u8(info), length: 32 });
+}

package/src/fs/aes.ts

@@ -0,0 +1,343 @@
+/**
+ * Omnituum FS - AES-256-GCM Encryption
+ *
+ * File encryption using AES-256-GCM via Web Crypto API.
+ * Provides authenticated encryption with associated data (AEAD).
+ */
+
+import { rand12 } from '../crypto/primitives';
+
+// Helper to safely extract ArrayBuffer from Uint8Array (handles SharedArrayBuffer)
+function toArrayBuffer(arr: Uint8Array): ArrayBuffer {
+  // If buffer is SharedArrayBuffer or view is offset, copy to new ArrayBuffer
+  if (arr.buffer instanceof SharedArrayBuffer || arr.byteOffset !== 0 || arr.byteLength !== arr.buffer.byteLength) {
+    const copy = new ArrayBuffer(arr.byteLength);
+    new Uint8Array(copy).set(arr);
+    return copy;
+  }
+  return arr.buffer as ArrayBuffer;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// CONSTANTS
+// ═══════════════════════════════════════════════════════════════════════════
+
+/** AES-256 key size in bytes */
+export const AES_KEY_SIZE = 32;
+
+/** AES-GCM IV size in bytes (96 bits recommended by NIST) */
+export const AES_GCM_IV_SIZE = 12;
+
+/** AES-GCM auth tag size in bytes (128 bits) */
+export const AES_GCM_TAG_SIZE = 16;
+
+// ═══════════════════════════════════════════════════════════════════════════
+// KEY IMPORT
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Import a raw 256-bit key for AES-GCM operations.
+ *
+ * @param keyBytes - 32-byte raw key material
+ * @returns CryptoKey suitable for AES-GCM encryption/decryption
+ */
+export async function importAesKey(keyBytes: Uint8Array): Promise<CryptoKey> {
+  if (keyBytes.length !== AES_KEY_SIZE) {
+    throw new Error(`AES key must be ${AES_KEY_SIZE} bytes, got ${keyBytes.length}`);
+  }
+
+  return globalThis.crypto.subtle.importKey(
+    'raw',
+    toArrayBuffer(keyBytes),
+    { name: 'AES-GCM', length: 256 },
+    false, // not extractable
+    ['encrypt', 'decrypt']
+  );
+}
+
+/**
+ * Generate a random 256-bit AES key.
+ *
+ * @returns CryptoKey for AES-GCM
+ */
+export async function generateAesKey(): Promise<CryptoKey> {
+  return globalThis.crypto.subtle.generateKey(
+    { name: 'AES-GCM', length: 256 },
+    true, // extractable for wrapping
+    ['encrypt', 'decrypt']
+  );
+}
+
+/**
+ * Export a CryptoKey to raw bytes.
+ *
+ * @param key - CryptoKey to export
+ * @returns 32-byte raw key
+ */
+export async function exportAesKey(key: CryptoKey): Promise<Uint8Array> {
+  const exported = await globalThis.crypto.subtle.exportKey('raw', key);
+  return new Uint8Array(exported);
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// ENCRYPTION
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Encrypt data using AES-256-GCM.
+ *
+ * @param plaintext - Data to encrypt
+ * @param key - AES-256 key (CryptoKey or 32-byte Uint8Array)
+ * @param iv - Optional 12-byte IV (generated if not provided)
+ * @param additionalData - Optional additional authenticated data (AAD)
+ * @returns Object containing IV and ciphertext (with auth tag appended)
+ */
+export async function aesEncrypt(
+  plaintext: Uint8Array,
+  key: CryptoKey | Uint8Array,
+  iv?: Uint8Array,
+  additionalData?: Uint8Array
+): Promise<{ iv: Uint8Array; ciphertext: Uint8Array }> {
+  // Import key if raw bytes provided
+  const cryptoKey = key instanceof CryptoKey ? key : await importAesKey(key);
+
+  // Generate IV if not provided
+  const ivBytes = iv ?? rand12();
+
+  if (ivBytes.length !== AES_GCM_IV_SIZE) {
+    throw new Error(`IV must be ${AES_GCM_IV_SIZE} bytes, got ${ivBytes.length}`);
+  }
+
+  // Encrypt with AES-GCM (convert Uint8Arrays to ArrayBuffer for Web Crypto compatibility)
+  const encrypted = await globalThis.crypto.subtle.encrypt(
+    {
+      name: 'AES-GCM',
+      iv: toArrayBuffer(ivBytes),
+      additionalData: additionalData ? toArrayBuffer(additionalData) : undefined,
+      tagLength: 128, // 16 bytes
+    },
+    cryptoKey,
+    toArrayBuffer(plaintext)
+  );
+
+  return {
+    iv: ivBytes,
+    ciphertext: new Uint8Array(encrypted), // Includes auth tag
+  };
+}
+
+/**
+ * Encrypt data and return combined IV + ciphertext.
+ * Convenience method for simple encryption.
+ *
+ * @param plaintext - Data to encrypt
+ * @param key - AES-256 key
+ * @param additionalData - Optional AAD
+ * @returns Combined bytes: [IV (12 bytes)] [ciphertext + tag]
+ */
+export async function aesEncryptCombined(
+  plaintext: Uint8Array,
+  key: CryptoKey | Uint8Array,
+  additionalData?: Uint8Array
+): Promise<Uint8Array> {
+  const { iv, ciphertext } = await aesEncrypt(plaintext, key, undefined, additionalData);
+
+  // Combine IV + ciphertext
+  const combined = new Uint8Array(iv.length + ciphertext.length);
+  combined.set(iv, 0);
+  combined.set(ciphertext, iv.length);
+
+  return combined;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// DECRYPTION
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Decrypt data using AES-256-GCM.
+ *
+ * @param ciphertext - Encrypted data (with auth tag appended)
+ * @param key - AES-256 key (CryptoKey or 32-byte Uint8Array)
+ * @param iv - 12-byte IV used for encryption
+ * @param additionalData - Optional additional authenticated data (must match encryption)
+ * @returns Decrypted plaintext
+ * @throws Error if authentication fails (wrong key or tampered data)
+ */
+export async function aesDecrypt(
+  ciphertext: Uint8Array,
+  key: CryptoKey | Uint8Array,
+  iv: Uint8Array,
+  additionalData?: Uint8Array
+): Promise<Uint8Array> {
+  // Import key if raw bytes provided
+  const cryptoKey = key instanceof CryptoKey ? key : await importAesKey(key);
+
+  if (iv.length !== AES_GCM_IV_SIZE) {
+    throw new Error(`IV must be ${AES_GCM_IV_SIZE} bytes, got ${iv.length}`);
+  }
+
+  try {
+    // Convert Uint8Arrays to ArrayBuffer for Web Crypto compatibility
+    const decrypted = await globalThis.crypto.subtle.decrypt(
+      {
+        name: 'AES-GCM',
+        iv: toArrayBuffer(iv),
+        additionalData: additionalData ? toArrayBuffer(additionalData) : undefined,
+        tagLength: 128,
+      },
+      cryptoKey,
+      toArrayBuffer(ciphertext)
+    );
+
+    return new Uint8Array(decrypted);
+  } catch (error) {
+    // Web Crypto throws a generic error for auth failures
+    throw new Error('Decryption failed: authentication tag mismatch (wrong key or corrupted data)');
+  }
+}
+
+/**
+ * Decrypt combined IV + ciphertext.
+ * Convenience method for simple decryption.
+ *
+ * @param combined - Combined bytes: [IV (12 bytes)] [ciphertext + tag]
+ * @param key - AES-256 key
+ * @param additionalData - Optional AAD
+ * @returns Decrypted plaintext
+ */
+export async function aesDecryptCombined(
+  combined: Uint8Array,
+  key: CryptoKey | Uint8Array,
+  additionalData?: Uint8Array
+): Promise<Uint8Array> {
+  if (combined.length < AES_GCM_IV_SIZE + AES_GCM_TAG_SIZE) {
+    throw new Error(`Combined data too short: need at least ${AES_GCM_IV_SIZE + AES_GCM_TAG_SIZE} bytes`);
+  }
+
+  const iv = combined.slice(0, AES_GCM_IV_SIZE);
+  const ciphertext = combined.slice(AES_GCM_IV_SIZE);
+
+  return aesDecrypt(ciphertext, key, iv, additionalData);
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// STREAMING ENCRYPTION (for large files)
+// ═══════════════════════════════════════════════════════════════════════════
+
+/** Chunk size for streaming operations (1 MB) */
+export const STREAM_CHUNK_SIZE = 1024 * 1024;
+
+/**
+ * Encrypt large data in chunks.
+ * Each chunk is encrypted with a unique IV derived from base IV + counter.
+ *
+ * Note: For files < 100MB, use regular aesEncrypt for simplicity.
+ * This is primarily for very large files where memory is a concern.
+ *
+ * @param plaintext - Data to encrypt
+ * @param key - AES-256 key
+ * @param onProgress - Optional progress callback
+ * @returns Encrypted data with format: [chunk count (4 bytes)] [IV] [chunks...]
+ */
+export async function aesEncryptStreaming(
+  plaintext: Uint8Array,
+  key: CryptoKey | Uint8Array,
+  onProgress?: (percent: number) => void
+): Promise<Uint8Array> {
+  const cryptoKey = key instanceof CryptoKey ? key : await importAesKey(key);
+
+  const chunks: Uint8Array[] = [];
+  const totalChunks = Math.ceil(plaintext.length / STREAM_CHUNK_SIZE);
+
+  // Store chunk count (4 bytes, big-endian)
+  const header = new Uint8Array(4);
+  new DataView(header.buffer).setUint32(0, totalChunks, false);
+  chunks.push(header);
+
+  for (let i = 0; i < totalChunks; i++) {
+    const start = i * STREAM_CHUNK_SIZE;
+    const end = Math.min(start + STREAM_CHUNK_SIZE, plaintext.length);
+    const chunk = plaintext.slice(start, end);
+
+    // Encrypt chunk (IV is generated fresh for each chunk)
+    const { iv, ciphertext } = await aesEncrypt(chunk, cryptoKey);
+
+    // Store: [IV (12 bytes)] [ciphertext length (4 bytes)] [ciphertext]
+    const chunkData = new Uint8Array(12 + 4 + ciphertext.length);
+    chunkData.set(iv, 0);
+    new DataView(chunkData.buffer).setUint32(12, ciphertext.length, false);
+    chunkData.set(ciphertext, 16);
+    chunks.push(chunkData);
+
+    if (onProgress) {
+      onProgress(Math.round(((i + 1) / totalChunks) * 100));
+    }
+  }
+
+  // Combine all chunks
+  const totalLength = chunks.reduce((sum, c) => sum + c.length, 0);
+  const result = new Uint8Array(totalLength);
+  let offset = 0;
+  for (const chunk of chunks) {
+    result.set(chunk, offset);
+    offset += chunk.length;
+  }
+
+  return result;
+}
+
+/**
+ * Decrypt large data encrypted with aesEncryptStreaming.
+ *
+ * @param encrypted - Encrypted data from aesEncryptStreaming
+ * @param key - AES-256 key
+ * @param onProgress - Optional progress callback
+ * @returns Decrypted plaintext
+ */
+export async function aesDecryptStreaming(
+  encrypted: Uint8Array,
+  key: CryptoKey | Uint8Array,
+  onProgress?: (percent: number) => void
+): Promise<Uint8Array> {
+  const cryptoKey = key instanceof CryptoKey ? key : await importAesKey(key);
+
+  // Read chunk count
+  const totalChunks = new DataView(encrypted.buffer, encrypted.byteOffset).getUint32(0, false);
+  const chunks: Uint8Array[] = [];
+
+  let offset = 4; // Skip header
+
+  for (let i = 0; i < totalChunks; i++) {
+    // Read IV
+    const iv = encrypted.slice(offset, offset + 12);
+    offset += 12;
+
+    // Read ciphertext length
+    const ctLength = new DataView(encrypted.buffer, encrypted.byteOffset + offset).getUint32(0, false);
+    offset += 4;
+
+    // Read ciphertext
+    const ciphertext = encrypted.slice(offset, offset + ctLength);
+    offset += ctLength;
+
+    // Decrypt chunk
+    const plaintext = await aesDecrypt(ciphertext, cryptoKey, iv);
+    chunks.push(plaintext);
+
+    if (onProgress) {
+      onProgress(Math.round(((i + 1) / totalChunks) * 100));
+    }
+  }
+
+  // Combine all chunks
+  const totalLength = chunks.reduce((sum, c) => sum + c.length, 0);
+  const result = new Uint8Array(totalLength);
+  let resultOffset = 0;
+  for (const chunk of chunks) {
+    result.set(chunk, resultOffset);
+    resultOffset += chunk.length;
+  }
+
+  return result;
+}

package/src/fs/argon2.ts

@@ -0,0 +1,184 @@
+/**
+ * Omnituum FS - Argon2id Key Derivation
+ *
+ * Memory-hard password hashing using Argon2id (winner of PHC).
+ * Uses hash-wasm for browser-compatible WASM implementation.
+ *
+ * Security: OWASP 2024 recommended parameters.
+ */
+
+import { argon2id } from 'hash-wasm';
+import { randN } from '../crypto/primitives';
+import {
+  Argon2idParams,
+  DEFAULT_ARGON2ID_PARAMS,
+  MIN_ARGON2ID_PARAMS,
+} from './types';
+
+// ═══════════════════════════════════════════════════════════════════════════
+// ARGON2ID KEY DERIVATION
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Derive an encryption key from a password using Argon2id.
+ *
+ * @param password - User password
+ * @param salt - 32-byte random salt (generate with generateArgon2Salt())
+ * @param params - Argon2id parameters (uses OWASP defaults if not specified)
+ * @returns 32-byte derived key suitable for AES-256
+ */
+export async function deriveKeyFromPassword(
+  password: string,
+  salt: Uint8Array,
+  params: Argon2idParams = DEFAULT_ARGON2ID_PARAMS
+): Promise<Uint8Array> {
+  if (salt.length !== params.saltLength) {
+    throw new Error(`Salt must be ${params.saltLength} bytes, got ${salt.length}`);
+  }
+
+  const hash = await argon2id({
+    password,
+    salt,
+    parallelism: params.parallelism,
+    iterations: params.timeCost,
+    memorySize: params.memoryCost,
+    hashLength: params.hashLength,
+    outputType: 'binary',
+  });
+
+  return new Uint8Array(hash);
+}
+
+/**
+ * Generate a random salt for Argon2id.
+ *
+ * @param length - Salt length in bytes (default: 32)
+ * @returns Random salt
+ */
+export function generateArgon2Salt(length: number = 32): Uint8Array {
+  return randN(length);
+}
+
+/**
+ * Verify a password against a stored hash.
+ * Useful for vault unlocking or file password verification.
+ *
+ * @param password - Password to verify
+ * @param salt - Original salt used
+ * @param expectedKey - Expected derived key
+ * @param params - Argon2id parameters
+ * @returns true if password is correct
+ */
+export async function verifyPassword(
+  password: string,
+  salt: Uint8Array,
+  expectedKey: Uint8Array,
+  params: Argon2idParams = DEFAULT_ARGON2ID_PARAMS
+): Promise<boolean> {
+  const derivedKey = await deriveKeyFromPassword(password, salt, params);
+
+  // Constant-time comparison to prevent timing attacks
+  if (derivedKey.length !== expectedKey.length) {
+    return false;
+  }
+
+  let result = 0;
+  for (let i = 0; i < derivedKey.length; i++) {
+    result |= derivedKey[i] ^ expectedKey[i];
+  }
+
+  return result === 0;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// PARAMETER ESTIMATION
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Estimate Argon2id parameters based on available memory and target time.
+ * Useful for adapting to low-memory environments.
+ *
+ * @param targetTimeMs - Target key derivation time in milliseconds
+ * @param availableMemoryMB - Available memory in megabytes
+ * @returns Estimated Argon2id parameters
+ */
+export function estimateArgon2Params(
+  targetTimeMs: number = 1000,
+  availableMemoryMB: number = 64
+): Argon2idParams {
+  // Start with minimum parameters
+  const params = { ...MIN_ARGON2ID_PARAMS };
+
+  // Scale memory based on availability (cap at 64MB for browser compatibility)
+  const maxMemoryKB = Math.min(availableMemoryMB * 1024, 65536);
+  params.memoryCost = Math.max(MIN_ARGON2ID_PARAMS.memoryCost, maxMemoryKB);
+
+  // Use 4 parallelism for modern multi-core CPUs
+  params.parallelism = Math.min(4, navigator.hardwareConcurrency || 1);
+
+  // Estimate time cost (rough heuristic: 1 iteration ≈ 300ms at 64MB)
+  const estimatedIterations = Math.max(2, Math.floor(targetTimeMs / 300));
+  params.timeCost = Math.min(estimatedIterations, 10); // Cap at 10 iterations
+
+  return params;
+}
+
+/**
+ * Benchmark Argon2id on current device.
+ * Returns the time in milliseconds for one derivation.
+ *
+ * @param params - Parameters to benchmark
+ * @returns Time in milliseconds
+ */
+export async function benchmarkArgon2(
+  params: Argon2idParams = DEFAULT_ARGON2ID_PARAMS
+): Promise<number> {
+  const testPassword = 'benchmark-test-password';
+  const testSalt = generateArgon2Salt(params.saltLength);
+
+  const start = performance.now();
+  await deriveKeyFromPassword(testPassword, testSalt, params);
+  const end = performance.now();
+
+  return end - start;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// AVAILABILITY CHECK
+// ═══════════════════════════════════════════════════════════════════════════
+
+let _argon2Available: boolean | null = null;
+
+/**
+ * Check if Argon2id is available in current environment.
+ * Caches result after first check.
+ */
+export async function isArgon2Available(): Promise<boolean> {
+  if (_argon2Available !== null) {
+    return _argon2Available;
+  }
+
+  try {
+    // Quick test with minimal parameters
+    await argon2id({
+      password: 'test',
+      salt: new Uint8Array(16),
+      parallelism: 1,
+      iterations: 1,
+      memorySize: 1024, // 1 MB
+      hashLength: 32,
+      outputType: 'binary',
+    });
+    _argon2Available = true;
+  } catch {
+    _argon2Available = false;
+  }
+
+  return _argon2Available;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// EXPORTS
+// ═══════════════════════════════════════════════════════════════════════════
+
+export { DEFAULT_ARGON2ID_PARAMS, MIN_ARGON2ID_PARAMS };