@omnituum/pqc-shared 0.2.6

package/src/kdf/index.ts

@@ -0,0 +1,311 @@
+/**
+ * Omnituum PQC Shared - Unified Key Derivation
+ *
+ * Single source of truth for password-based key derivation.
+ * Supports both legacy PBKDF2 (for backwards compatibility) and
+ * Argon2id (recommended for new implementations).
+ *
+ * Security Levels:
+ * - PBKDF2-SHA256: 600K iterations (OWASP 2023)
+ * - Argon2id: 64MB memory, 3 iterations, 4 parallelism (OWASP 2024)
+ */
+
+import { argon2id } from 'hash-wasm';
+import { randN } from '../crypto/primitives';
+
+// ═══════════════════════════════════════════════════════════════════════════
+// KDF TYPES
+// ═══════════════════════════════════════════════════════════════════════════
+
+export type KDFAlgorithm = 'PBKDF2-SHA256' | 'Argon2id';
+
+export interface KDFConfig {
+  algorithm: KDFAlgorithm;
+  // PBKDF2 params
+  pbkdf2Iterations?: number;
+  // Argon2id params
+  argon2MemoryCost?: number; // KiB
+  argon2TimeCost?: number;
+  argon2Parallelism?: number;
+  // Common
+  saltLength: number;
+  hashLength: number;
+}
+
+export interface KDFResult {
+  key: Uint8Array;
+  salt: Uint8Array;
+  algorithm: KDFAlgorithm;
+  params: Record<string, number>;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// DEFAULT CONFIGURATIONS
+// ═══════════════════════════════════════════════════════════════════════════
+
+/** Legacy PBKDF2 config (for existing vaults) */
+export const KDF_CONFIG_PBKDF2: KDFConfig = {
+  algorithm: 'PBKDF2-SHA256',
+  pbkdf2Iterations: 600000, // OWASP 2023
+  saltLength: 32,
+  hashLength: 32,
+};
+
+/** Modern Argon2id config (recommended for new vaults) */
+export const KDF_CONFIG_ARGON2ID: KDFConfig = {
+  algorithm: 'Argon2id',
+  argon2MemoryCost: 65536, // 64 MB
+  argon2TimeCost: 3,
+  argon2Parallelism: 4,
+  saltLength: 32,
+  hashLength: 32,
+};
+
+/** Low-memory Argon2id config (for constrained environments) */
+export const KDF_CONFIG_ARGON2ID_LOW_MEMORY: KDFConfig = {
+  algorithm: 'Argon2id',
+  argon2MemoryCost: 19456, // 19 MB
+  argon2TimeCost: 2,
+  argon2Parallelism: 1,
+  saltLength: 32,
+  hashLength: 32,
+};
+
+/** Current default - can be changed for migration */
+export const KDF_CONFIG_DEFAULT = KDF_CONFIG_PBKDF2;
+
+// ═══════════════════════════════════════════════════════════════════════════
+// PBKDF2 IMPLEMENTATION
+// ═══════════════════════════════════════════════════════════════════════════
+
+const textEncoder = new TextEncoder();
+
+async function derivePBKDF2(
+  password: string,
+  salt: Uint8Array,
+  iterations: number,
+  hashLength: number
+): Promise<Uint8Array> {
+  const passwordKey = await globalThis.crypto.subtle.importKey(
+    'raw',
+    textEncoder.encode(password),
+    'PBKDF2',
+    false,
+    ['deriveBits']
+  );
+
+  const saltBuffer = new ArrayBuffer(salt.length);
+  new Uint8Array(saltBuffer).set(salt);
+
+  const bits = await globalThis.crypto.subtle.deriveBits(
+    {
+      name: 'PBKDF2',
+      salt: saltBuffer,
+      iterations,
+      hash: 'SHA-256',
+    },
+    passwordKey,
+    hashLength * 8
+  );
+
+  return new Uint8Array(bits);
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// ARGON2ID IMPLEMENTATION
+// ═══════════════════════════════════════════════════════════════════════════
+
+async function deriveArgon2id(
+  password: string,
+  salt: Uint8Array,
+  memoryCost: number,
+  timeCost: number,
+  parallelism: number,
+  hashLength: number
+): Promise<Uint8Array> {
+  const hash = await argon2id({
+    password,
+    salt,
+    parallelism,
+    iterations: timeCost,
+    memorySize: memoryCost,
+    hashLength,
+    outputType: 'binary',
+  });
+
+  return new Uint8Array(hash);
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// UNIFIED API
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Generate a cryptographically secure salt.
+ */
+export function generateSalt(length: number = 32): Uint8Array {
+  return randN(length);
+}
+
+/**
+ * Derive a key from a password using the specified KDF configuration.
+ *
+ * @param password - User password
+ * @param salt - Random salt (use generateSalt())
+ * @param config - KDF configuration
+ * @returns Derived key as Uint8Array
+ */
+export async function kdfDeriveKey(
+  password: string,
+  salt: Uint8Array,
+  config: KDFConfig = KDF_CONFIG_DEFAULT
+): Promise<Uint8Array> {
+  if (salt.length !== config.saltLength) {
+    throw new Error(`Salt must be ${config.saltLength} bytes, got ${salt.length}`);
+  }
+
+  if (config.algorithm === 'PBKDF2-SHA256') {
+    return derivePBKDF2(
+      password,
+      salt,
+      config.pbkdf2Iterations ?? 600000,
+      config.hashLength
+    );
+  } else if (config.algorithm === 'Argon2id') {
+    return deriveArgon2id(
+      password,
+      salt,
+      config.argon2MemoryCost ?? 65536,
+      config.argon2TimeCost ?? 3,
+      config.argon2Parallelism ?? 4,
+      config.hashLength
+    );
+  } else {
+    throw new Error(`Unsupported KDF algorithm: ${config.algorithm}`);
+  }
+}
+
+/**
+ * Derive a key and return full result with params.
+ * Useful for storing KDF metadata alongside encrypted data.
+ */
+export async function kdfDeriveKeyWithParams(
+  password: string,
+  config: KDFConfig = KDF_CONFIG_DEFAULT
+): Promise<KDFResult> {
+  const salt = generateSalt(config.saltLength);
+  const key = await kdfDeriveKey(password, salt, config);
+
+  const params: Record<string, number> = {};
+
+  if (config.algorithm === 'PBKDF2-SHA256') {
+    params.iterations = config.pbkdf2Iterations ?? 600000;
+  } else if (config.algorithm === 'Argon2id') {
+    params.memoryCost = config.argon2MemoryCost ?? 65536;
+    params.timeCost = config.argon2TimeCost ?? 3;
+    params.parallelism = config.argon2Parallelism ?? 4;
+  }
+
+  return {
+    key,
+    salt,
+    algorithm: config.algorithm,
+    params,
+  };
+}
+
+/**
+ * Reconstruct KDF config from stored parameters.
+ */
+export function configFromParams(
+  algorithm: KDFAlgorithm,
+  params: Record<string, number>
+): KDFConfig {
+  if (algorithm === 'PBKDF2-SHA256') {
+    return {
+      algorithm,
+      pbkdf2Iterations: params.iterations,
+      saltLength: 32,
+      hashLength: 32,
+    };
+  } else if (algorithm === 'Argon2id') {
+    return {
+      algorithm,
+      argon2MemoryCost: params.memoryCost,
+      argon2TimeCost: params.timeCost,
+      argon2Parallelism: params.parallelism,
+      saltLength: 32,
+      hashLength: 32,
+    };
+  } else {
+    throw new Error(`Unsupported KDF algorithm: ${algorithm}`);
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// AVAILABILITY CHECKS
+// ═══════════════════════════════════════════════════════════════════════════
+
+let _argon2Available: boolean | null = null;
+
+/**
+ * Check if Argon2id is available in current environment.
+ */
+export async function isArgon2idAvailable(): Promise<boolean> {
+  if (_argon2Available !== null) {
+    return _argon2Available;
+  }
+
+  try {
+    await argon2id({
+      password: 'test',
+      salt: new Uint8Array(16),
+      parallelism: 1,
+      iterations: 1,
+      memorySize: 1024,
+      hashLength: 32,
+      outputType: 'binary',
+    });
+    _argon2Available = true;
+  } catch {
+    _argon2Available = false;
+  }
+
+  return _argon2Available;
+}
+
+/**
+ * Check if PBKDF2 is available (always true in Web Crypto environments).
+ */
+export function isPBKDF2Available(): boolean {
+  return typeof globalThis.crypto !== 'undefined' && typeof globalThis.crypto.subtle !== 'undefined';
+}
+
+/**
+ * Get the recommended KDF config based on environment capabilities.
+ */
+export async function getRecommendedConfig(): Promise<KDFConfig> {
+  if (await isArgon2idAvailable()) {
+    return KDF_CONFIG_ARGON2ID;
+  }
+  return KDF_CONFIG_PBKDF2;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// BENCHMARKING
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Benchmark a KDF configuration.
+ * @returns Time in milliseconds
+ */
+export async function benchmarkKDF(config: KDFConfig = KDF_CONFIG_DEFAULT): Promise<number> {
+  const salt = generateSalt(config.saltLength);
+  const testPassword = 'benchmark-test-password';
+
+  const start = performance.now();
+  await kdfDeriveKey(testPassword, salt, config);
+  const end = performance.now();
+
+  return end - start;
+}

package/src/runtime/crypto.ts

@@ -0,0 +1,16 @@
+// src/runtime/crypto.ts
+// Ensure globalThis.crypto exists across Node + browsers.
+// Uses dynamic import so bundlers don't try to resolve Node built-ins.
+
+export async function ensureCrypto(): Promise<void> {
+  if (typeof globalThis.crypto !== 'undefined') return;
+
+  // Node: attach WebCrypto at runtime
+  const mod: any = await import('node:crypto');
+  const webcrypto = mod.webcrypto ?? mod.default?.webcrypto;
+  if (!webcrypto) throw new Error('WebCrypto not available in this Node runtime');
+  (globalThis as any).crypto = webcrypto as unknown as Crypto;
+}
+
+// fire-and-forget (works for your library init pattern)
+void ensureCrypto();

package/src/security/index.ts

@@ -0,0 +1,345 @@
+/**
+ * Omnituum PQC Shared - Security Utilities
+ *
+ * Memory hygiene, secure comparison, and session management utilities.
+ * These are critical for enterprise credibility and threat model legitimacy.
+ */
+
+// ═══════════════════════════════════════════════════════════════════════════
+// MEMORY ZEROING
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Securely zero out a Uint8Array to prevent sensitive data from lingering in memory.
+ *
+ * Note: JavaScript garbage collection may still leave copies. This is a best-effort
+ * approach for browser environments. For maximum security, use Web Assembly or
+ * native code.
+ *
+ * @param arr - Array to zero
+ */
+export function zeroMemory(arr: Uint8Array): void {
+  if (!arr || arr.length === 0) return;
+
+  // Fill with zeros
+  arr.fill(0);
+
+  // Try to prevent optimizer from removing the fill
+  // This is a best-effort approach
+  if (arr[0] !== 0) {
+    throw new Error('Memory zeroing failed');
+  }
+}
+
+/**
+ * Zero multiple arrays at once.
+ *
+ * @param arrays - Arrays to zero
+ */
+export function zeroAll(...arrays: (Uint8Array | null | undefined)[]): void {
+  for (const arr of arrays) {
+    if (arr) {
+      zeroMemory(arr);
+    }
+  }
+}
+
+/**
+ * Execute a function and zero the result after a callback processes it.
+ * Ensures sensitive data is cleared even if callback throws.
+ *
+ * @param getData - Function that returns sensitive data
+ * @param process - Function to process the data
+ * @returns Result of process function
+ */
+export async function withSecureData<T, R>(
+  getData: () => Promise<Uint8Array>,
+  process: (data: Uint8Array) => Promise<R>
+): Promise<R> {
+  let data: Uint8Array | null = null;
+  try {
+    data = await getData();
+    return await process(data);
+  } finally {
+    if (data) {
+      zeroMemory(data);
+    }
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// CONSTANT-TIME COMPARISON
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Compare two byte arrays in constant time to prevent timing attacks.
+ *
+ * @param a - First array
+ * @param b - Second array
+ * @returns true if arrays are equal
+ */
+export function constantTimeEqual(a: Uint8Array, b: Uint8Array): boolean {
+  if (a.length !== b.length) {
+    return false;
+  }
+
+  let result = 0;
+  for (let i = 0; i < a.length; i++) {
+    result |= a[i] ^ b[i];
+  }
+
+  return result === 0;
+}
+
+/**
+ * Compare two strings in constant time.
+ *
+ * @param a - First string
+ * @param b - Second string
+ * @returns true if strings are equal
+ */
+export function constantTimeStringEqual(a: string, b: string): boolean {
+  const encoder = new TextEncoder();
+  return constantTimeEqual(encoder.encode(a), encoder.encode(b));
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// SESSION MANAGEMENT
+// ═══════════════════════════════════════════════════════════════════════════
+
+export type UnlockReason =
+  | 'password'        // User entered password
+  | 'biometric'       // Biometric authentication (future)
+  | 'hardware_key'    // Hardware security key (future)
+  | 'session_restore' // Restored from saved session
+  | 'api_token'       // API token authentication
+  | 'unknown';
+
+export interface SecureSession {
+  /** Session is currently unlocked */
+  unlocked: boolean;
+
+  /** Timestamp when session was unlocked (ms since epoch) */
+  unlockedAt: number | null;
+
+  /** Session timeout in milliseconds (0 = never) */
+  timeoutMs: number;
+
+  /** How the session was unlocked */
+  unlockReason: UnlockReason | null;
+
+  /** Optional session identifier */
+  sessionId: string | null;
+
+  /** Last activity timestamp (ms since epoch) */
+  lastActivityAt: number | null;
+
+  /** Number of failed unlock attempts */
+  failedAttempts: number;
+
+  /** Lockout until timestamp (ms since epoch) if too many failed attempts */
+  lockedOutUntil: number | null;
+}
+
+/**
+ * Create a new locked session.
+ */
+export function createSession(timeoutMs: number = 15 * 60 * 1000): SecureSession {
+  return {
+    unlocked: false,
+    unlockedAt: null,
+    timeoutMs,
+    unlockReason: null,
+    sessionId: null,
+    lastActivityAt: null,
+    failedAttempts: 0,
+    lockedOutUntil: null,
+  };
+}
+
+/**
+ * Unlock a secure session.
+ */
+export function unlockSecureSession(
+  session: SecureSession,
+  reason: UnlockReason = 'password'
+): SecureSession {
+  const now = Date.now();
+  return {
+    ...session,
+    unlocked: true,
+    unlockedAt: now,
+    unlockReason: reason,
+    sessionId: generateSessionId(),
+    lastActivityAt: now,
+    failedAttempts: 0,
+    lockedOutUntil: null,
+  };
+}
+
+/**
+ * Lock a secure session and clear sensitive state.
+ */
+export function lockSecureSession(session: SecureSession): SecureSession {
+  return {
+    ...session,
+    unlocked: false,
+    unlockedAt: null,
+    unlockReason: null,
+    sessionId: null,
+    lastActivityAt: null,
+  };
+}
+
+/**
+ * Record session activity (resets timeout).
+ */
+export function touchSession(session: SecureSession): SecureSession {
+  if (!session.unlocked) {
+    return session;
+  }
+  return {
+    ...session,
+    lastActivityAt: Date.now(),
+  };
+}
+
+/**
+ * Check if session has timed out.
+ */
+export function isSessionTimedOut(session: SecureSession): boolean {
+  if (!session.unlocked || session.timeoutMs === 0) {
+    return false;
+  }
+
+  const lastActivity = session.lastActivityAt ?? session.unlockedAt ?? 0;
+  return Date.now() - lastActivity > session.timeoutMs;
+}
+
+/**
+ * Check if session should be auto-locked.
+ */
+export function shouldAutoLock(session: SecureSession): boolean {
+  return session.unlocked && isSessionTimedOut(session);
+}
+
+/**
+ * Record a failed unlock attempt.
+ */
+export function recordFailedAttempt(
+  session: SecureSession,
+  lockoutThreshold: number = 5,
+  lockoutDurationMs: number = 5 * 60 * 1000
+): SecureSession {
+  const newAttempts = session.failedAttempts + 1;
+  const isLockedOut = newAttempts >= lockoutThreshold;
+
+  return {
+    ...session,
+    failedAttempts: newAttempts,
+    lockedOutUntil: isLockedOut ? Date.now() + lockoutDurationMs : null,
+  };
+}
+
+/**
+ * Check if session is in lockout state.
+ */
+export function isLockedOut(session: SecureSession): boolean {
+  if (!session.lockedOutUntil) {
+    return false;
+  }
+  return Date.now() < session.lockedOutUntil;
+}
+
+/**
+ * Get remaining lockout time in milliseconds.
+ */
+export function getLockoutRemaining(session: SecureSession): number {
+  if (!session.lockedOutUntil) {
+    return 0;
+  }
+  return Math.max(0, session.lockedOutUntil - Date.now());
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// HELPERS
+// ═══════════════════════════════════════════════════════════════════════════
+
+function generateSessionId(): string {
+  const bytes = globalThis.crypto.getRandomValues(new Uint8Array(16));
+  return Array.from(bytes)
+    .map(b => b.toString(16).padStart(2, '0'))
+    .join('');
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// SENSITIVE DATA WRAPPER
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Wrapper for sensitive data that auto-zeros on disposal.
+ */
+export class SecureBuffer {
+  private _data: Uint8Array;
+  private _disposed: boolean = false;
+
+  constructor(data: Uint8Array) {
+    // Copy data to prevent external references
+    this._data = new Uint8Array(data.length);
+    this._data.set(data);
+  }
+
+  /**
+   * Get a copy of the data (original stays protected).
+   */
+  get data(): Uint8Array {
+    if (this._disposed) {
+      throw new Error('SecureBuffer has been disposed');
+    }
+    const copy = new Uint8Array(this._data.length);
+    copy.set(this._data);
+    return copy;
+  }
+
+  /**
+   * Get data length without exposing contents.
+   */
+  get length(): number {
+    return this._data.length;
+  }
+
+  /**
+   * Check if buffer has been disposed.
+   */
+  get isDisposed(): boolean {
+    return this._disposed;
+  }
+
+  /**
+   * Zero and dispose the buffer.
+   */
+  dispose(): void {
+    if (!this._disposed) {
+      zeroMemory(this._data);
+      this._disposed = true;
+    }
+  }
+
+  /**
+   * Execute a function with the data, then dispose.
+   */
+  async useAndDispose<T>(fn: (data: Uint8Array) => Promise<T>): Promise<T> {
+    try {
+      return await fn(this._data);
+    } finally {
+      this.dispose();
+    }
+  }
+}
+
+/**
+ * Create a SecureBuffer from data.
+ */
+export function secureBuffer(data: Uint8Array): SecureBuffer {
+  return new SecureBuffer(data);
+}

package/src/tunnel/index.ts

@@ -0,0 +1,39 @@
+/**
+ * Omnituum Tunnel v1
+ *
+ * Post-handshake encrypted tunnel abstraction.
+ * Handshake-agnostic: any key agreement protocol can feed into this.
+ *
+ * @example
+ * ```ts
+ * import { createTunnelSession, TunnelKeyMaterial } from '@omnituum/pqc-shared';
+ *
+ * // From Noise handshake
+ * const keys: TunnelKeyMaterial = toTunnelKeyMaterial(noiseState);
+ * const tunnel = createTunnelSession(keys);
+ *
+ * // Encrypt
+ * const ciphertext = tunnel.encrypt(plaintext);
+ *
+ * // Decrypt
+ * const plaintext = tunnel.decrypt(ciphertext);
+ *
+ * // Clean up
+ * tunnel.close();
+ * ```
+ *
+ * @see pqc-docs/specs/tunnel.v1.md
+ */
+
+// Types
+export type { TunnelKeyMaterial, PQCTunnelSession } from './types';
+
+export {
+  TUNNEL_VERSION,
+  TUNNEL_KEY_SIZE,
+  TUNNEL_NONCE_SIZE,
+  TUNNEL_TAG_SIZE,
+} from './types';
+
+// Session factory
+export { createTunnelSession, createTestKeyMaterial } from './session';