@omnituum/pqc-shared 0.2.6

package/src/vault/manager.ts

@@ -0,0 +1,327 @@
+/**
+ * Omnituum PQC Shared - Vault Manager
+ *
+ * High-level operations for managing the PQC identity vault.
+ * Handles identity creation, rotation, import/export, and session management.
+ */
+
+import type {
+  OmnituumVault,
+  HybridIdentityRecord,
+  VaultSettings,
+  VaultSession,
+} from './types';
+import { encryptVaultToBlob } from './encrypt';
+import { decryptVaultFromFile } from './decrypt';
+import { computeIntegrityHash } from '../utils/integrity';
+import { generateId } from '../utils/entropy';
+import { generateX25519Keypair, generateKyberKeypair, toHex } from '../crypto';
+import { VAULT_VERSION } from '../version';
+
+// ═══════════════════════════════════════════════════════════════════════════
+// VAULT CREATION
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Create a new empty vault.
+ */
+export function createEmptyVault(): OmnituumVault {
+  const now = new Date().toISOString();
+  return {
+    version: VAULT_VERSION,
+    identities: [],
+    settings: {
+      autoUnlock: false,
+      lockTimeout: 15,
+      showFingerprints: true,
+    },
+    integrityHash: computeIntegrityHash([]),
+    createdAt: now,
+    modifiedAt: now,
+  };
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// IDENTITY MANAGEMENT
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Create a new hybrid identity.
+ */
+export async function createIdentity(name: string): Promise<HybridIdentityRecord | null> {
+  // Generate X25519 keypair
+  const x25519 = generateX25519Keypair();
+
+  // Generate Kyber keypair
+  const kyber = await generateKyberKeypair();
+  if (!kyber) {
+    console.error('Kyber key generation failed');
+    return null;
+  }
+
+  const now = new Date().toISOString();
+  const deviceFingerprint = await getDeviceFingerprint();
+
+  return {
+    id: generateId(),
+    name,
+    x25519PubHex: x25519.publicHex,
+    x25519SecHex: x25519.secretHex,
+    kyberPubB64: kyber.publicB64,
+    kyberSecB64: kyber.secretB64,
+    createdAt: now,
+    rotationCount: 0,
+    deviceFingerprint,
+  };
+}
+
+/**
+ * Add an identity to the vault.
+ */
+export function addIdentity(vault: OmnituumVault, identity: HybridIdentityRecord): OmnituumVault {
+  const identities = [...vault.identities, identity];
+  return {
+    ...vault,
+    identities,
+    integrityHash: computeIntegrityHash(identities),
+    modifiedAt: new Date().toISOString(),
+  };
+}
+
+/**
+ * Remove an identity from the vault.
+ */
+export function removeIdentity(vault: OmnituumVault, identityId: string): OmnituumVault {
+  const identities = vault.identities.filter(i => i.id !== identityId);
+  return {
+    ...vault,
+    identities,
+    integrityHash: computeIntegrityHash(identities),
+    modifiedAt: new Date().toISOString(),
+    settings: {
+      ...vault.settings,
+      lastUsedIdentity: vault.settings.lastUsedIdentity === identityId
+        ? undefined
+        : vault.settings.lastUsedIdentity,
+    },
+  };
+}
+
+/**
+ * Rotate keys for an identity (regenerate Kyber + X25519).
+ */
+export async function rotateIdentityKeys(
+  vault: OmnituumVault,
+  identityId: string
+): Promise<OmnituumVault | null> {
+  const index = vault.identities.findIndex(i => i.id === identityId);
+  if (index === -1) return null;
+
+  const existing = vault.identities[index];
+
+  // Generate new X25519 keypair
+  const x25519 = generateX25519Keypair();
+
+  // Generate new Kyber keypair
+  const kyber = await generateKyberKeypair();
+  if (!kyber) return null;
+
+  const now = new Date().toISOString();
+
+  const updated: HybridIdentityRecord = {
+    ...existing,
+    x25519PubHex: x25519.publicHex,
+    x25519SecHex: x25519.secretHex,
+    kyberPubB64: kyber.publicB64,
+    kyberSecB64: kyber.secretB64,
+    lastRotatedAt: now,
+    rotationCount: existing.rotationCount + 1,
+  };
+
+  const identities = [...vault.identities];
+  identities[index] = updated;
+
+  return {
+    ...vault,
+    identities,
+    integrityHash: computeIntegrityHash(identities),
+    modifiedAt: now,
+  };
+}
+
+/**
+ * Update identity metadata.
+ */
+export function updateIdentityMetadata(
+  vault: OmnituumVault,
+  identityId: string,
+  updates: Partial<Pick<HybridIdentityRecord, 'name' | 'metadata'>>
+): OmnituumVault {
+  const identities = vault.identities.map(i =>
+    i.id === identityId ? { ...i, ...updates } : i
+  );
+  return {
+    ...vault,
+    identities,
+    integrityHash: computeIntegrityHash(identities),
+    modifiedAt: new Date().toISOString(),
+  };
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// VAULT SETTINGS
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Update vault settings.
+ */
+export function updateSettings(
+  vault: OmnituumVault,
+  settings: Partial<VaultSettings>
+): OmnituumVault {
+  return {
+    ...vault,
+    settings: { ...vault.settings, ...settings },
+    modifiedAt: new Date().toISOString(),
+  };
+}
+
+/**
+ * Set the active identity.
+ */
+export function setActiveIdentity(vault: OmnituumVault, identityId: string): OmnituumVault {
+  return updateSettings(vault, { lastUsedIdentity: identityId });
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// IMPORT / EXPORT
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Export vault to encrypted file.
+ */
+export async function exportVault(vault: OmnituumVault, password: string): Promise<Blob> {
+  return encryptVaultToBlob(vault, password);
+}
+
+/**
+ * Import vault from encrypted file.
+ */
+export async function importVault(file: File, password: string): Promise<OmnituumVault> {
+  return decryptVaultFromFile(file, password);
+}
+
+/**
+ * Trigger download of encrypted vault.
+ */
+export async function downloadVault(vault: OmnituumVault, password: string): Promise<void> {
+  const blob = await exportVault(vault, password);
+  const url = URL.createObjectURL(blob);
+  const a = document.createElement('a');
+  a.href = url;
+  a.download = `omnituum_vault_${new Date().toISOString().split('T')[0]}.enc`;
+  document.body.appendChild(a);
+  a.click();
+  document.body.removeChild(a);
+  URL.revokeObjectURL(url);
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// SESSION MANAGEMENT
+// ═══════════════════════════════════════════════════════════════════════════
+
+let currentSession: VaultSession = {
+  unlocked: false,
+  sessionKey: null,
+  unlockedAt: null,
+  activeIdentityId: null,
+};
+
+/**
+ * Get current session state.
+ */
+export function getSession(): VaultSession {
+  return { ...currentSession };
+}
+
+/**
+ * Unlock vault and store session key in memory.
+ */
+export async function unlockSession(password: string, vault: OmnituumVault): Promise<boolean> {
+  try {
+    // Verify password by attempting to encrypt/decrypt
+    const salt = globalThis.crypto.getRandomValues(new Uint8Array(32));
+    const passwordKey = await globalThis.crypto.subtle.importKey(
+      'raw',
+      new TextEncoder().encode(password),
+      'PBKDF2',
+      false,
+      ['deriveBits', 'deriveKey']
+    );
+
+    const sessionKey = await globalThis.crypto.subtle.deriveKey(
+      {
+        name: 'PBKDF2',
+        salt,
+        iterations: 100000, // Faster for session key
+        hash: 'SHA-256',
+      },
+      passwordKey,
+      { name: 'AES-GCM', length: 256 },
+      false,
+      ['encrypt', 'decrypt']
+    );
+
+    currentSession = {
+      unlocked: true,
+      sessionKey,
+      unlockedAt: Date.now(),
+      activeIdentityId: vault.settings.lastUsedIdentity || vault.identities[0]?.id || null,
+    };
+
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Lock the session.
+ */
+export function lockSession(): void {
+  currentSession = {
+    unlocked: false,
+    sessionKey: null,
+    unlockedAt: null,
+    activeIdentityId: null,
+  };
+}
+
+/**
+ * Set active identity in session.
+ */
+export function setSessionActiveIdentity(identityId: string): void {
+  if (currentSession.unlocked) {
+    currentSession.activeIdentityId = identityId;
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// DEVICE FINGERPRINT
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Generate a device fingerprint for identity tracking.
+ */
+async function getDeviceFingerprint(): Promise<string> {
+  const data = [
+    navigator.userAgent,
+    navigator.language,
+    screen.width,
+    screen.height,
+    new Date().getTimezoneOffset(),
+  ].join('|');
+
+  const hash = await globalThis.crypto.subtle.digest('SHA-256', new TextEncoder().encode(data));
+  return toHex(new Uint8Array(hash)).slice(0, 16);
+}

package/src/vault/migrate.ts

@@ -0,0 +1,190 @@
+/**
+ * Omnituum PQC Shared - Vault Migration
+ *
+ * One-way migration from v1 (PBKDF2) to v2 (Argon2id) encrypted vaults.
+ * Includes memory hygiene for sensitive data.
+ */
+
+import type {
+  OmnituumVault,
+  EncryptedVaultFile,
+  EncryptedVaultFileV1,
+  EncryptedVaultFileV2,
+} from './types';
+import { decryptVault } from './decrypt';
+import { encryptVaultV2 } from './encrypt';
+import { zeroMemory } from '../security';
+import {
+  VAULT_ENCRYPTED_VERSION,
+  VAULT_ENCRYPTED_VERSION_V2,
+} from '../version';
+
+// ═══════════════════════════════════════════════════════════════════════════
+// MIGRATION TYPES
+// ═══════════════════════════════════════════════════════════════════════════
+
+export interface MigrationOptions {
+  /** Source encrypted vault */
+  encryptedVault: EncryptedVaultFile;
+  /** Vault password */
+  password: string;
+  /** Keep backup of original vault data (default: false) */
+  keepBackup?: boolean;
+}
+
+export interface MigrationResult {
+  /** New v2 encrypted vault */
+  encryptedVault: EncryptedVaultFileV2;
+  /** Original vault (only if keepBackup was true) */
+  backup?: EncryptedVaultFile;
+  /** Source version */
+  sourceVersion: string;
+  /** Target version */
+  targetVersion: string;
+  /** Migration timestamp */
+  migratedAt: string;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// VERSION DETECTION
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Check if vault needs migration (is v1 format).
+ */
+export function needsMigration(encryptedVault: EncryptedVaultFile): boolean {
+  return encryptedVault.version === VAULT_ENCRYPTED_VERSION;
+}
+
+/**
+ * Check if vault is already v2 format.
+ */
+export function isV2Vault(encryptedVault: EncryptedVaultFile): boolean {
+  return encryptedVault.version === VAULT_ENCRYPTED_VERSION_V2;
+}
+
+/**
+ * Get vault KDF info for display.
+ */
+export function getVaultKdfInfo(encryptedVault: EncryptedVaultFile): {
+  kdf: string;
+  version: string;
+  isSecure: boolean;
+  recommendation?: string;
+} {
+  if (encryptedVault.version === VAULT_ENCRYPTED_VERSION_V2) {
+    const v2 = encryptedVault as EncryptedVaultFileV2;
+    return {
+      kdf: `Argon2id (${v2.memoryCost / 1024}MB, ${v2.timeCost} iterations)`,
+      version: 'v2',
+      isSecure: true,
+    };
+  } else {
+    const v1 = encryptedVault as EncryptedVaultFileV1;
+    return {
+      kdf: `PBKDF2-SHA256 (${v1.iterations.toLocaleString()} iterations)`,
+      version: 'v1',
+      isSecure: true, // Still secure, just not as modern
+      recommendation: 'Consider upgrading to Argon2id for stronger protection',
+    };
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// MIGRATION
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Migrate an encrypted vault from v1 (PBKDF2) to v2 (Argon2id).
+ *
+ * This is a ONE-WAY migration. The original vault remains unchanged,
+ * but a new v2 encrypted vault is returned.
+ *
+ * Memory hygiene: Sensitive data (decrypted vault) is zeroed after use.
+ *
+ * @param options - Migration options
+ * @returns Migration result with new v2 vault
+ * @throws Error if decryption fails or vault is already v2
+ */
+export async function migrateEncryptedVault(
+  options: MigrationOptions
+): Promise<MigrationResult> {
+  const { encryptedVault, password, keepBackup = false } = options;
+
+  // Check if already v2
+  if (isV2Vault(encryptedVault)) {
+    throw new Error('Vault is already v2 format, no migration needed');
+  }
+
+  // Track sensitive data for cleanup
+  let decryptedVaultJson: Uint8Array | null = null;
+
+  try {
+    // Decrypt the vault
+    const vault = await decryptVault(encryptedVault, password);
+
+    // Serialize for memory tracking (so we can zero it)
+    const vaultJson = JSON.stringify(vault);
+    decryptedVaultJson = new TextEncoder().encode(vaultJson);
+
+    // Re-encrypt with v2 (Argon2id)
+    const newEncryptedVault = await encryptVaultV2(vault, password);
+
+    return {
+      encryptedVault: newEncryptedVault,
+      backup: keepBackup ? encryptedVault : undefined,
+      sourceVersion: encryptedVault.version,
+      targetVersion: VAULT_ENCRYPTED_VERSION_V2,
+      migratedAt: new Date().toISOString(),
+    };
+  } finally {
+    // Zero sensitive data
+    if (decryptedVaultJson) {
+      zeroMemory(decryptedVaultJson);
+    }
+  }
+}
+
+/**
+ * Validate migration by decrypting both versions and comparing.
+ * Used for testing migration integrity.
+ *
+ * @param original - Original encrypted vault
+ * @param migrated - Migrated encrypted vault
+ * @param password - Vault password
+ * @returns true if vaults contain identical data
+ */
+export async function validateMigration(
+  original: EncryptedVaultFile,
+  migrated: EncryptedVaultFileV2,
+  password: string
+): Promise<boolean> {
+  let originalVaultJson: Uint8Array | null = null;
+  let migratedVaultJson: Uint8Array | null = null;
+
+  try {
+    const originalVault = await decryptVault(original, password);
+    const migratedVault = await decryptVault(migrated, password);
+
+    // Serialize for comparison
+    originalVaultJson = new TextEncoder().encode(JSON.stringify(originalVault));
+    migratedVaultJson = new TextEncoder().encode(JSON.stringify(migratedVault));
+
+    // Compare serialized JSON
+    if (originalVaultJson.length !== migratedVaultJson.length) {
+      return false;
+    }
+
+    for (let i = 0; i < originalVaultJson.length; i++) {
+      if (originalVaultJson[i] !== migratedVaultJson[i]) {
+        return false;
+      }
+    }
+
+    return true;
+  } finally {
+    // Zero sensitive data
+    if (originalVaultJson) zeroMemory(originalVaultJson);
+    if (migratedVaultJson) zeroMemory(migratedVaultJson);
+  }
+}

package/src/vault/types.ts

@@ -0,0 +1,177 @@
+/**
+ * Omnituum PQC Shared - Vault Types
+ *
+ * Type definitions for the PQC identity vault.
+ * FROZEN CONTRACTS - see pqc-docs/specs/vault.v1.md
+ */
+
+import type {
+  VAULT_VERSION,
+  VAULT_ENCRYPTED_VERSION,
+  VAULT_ENCRYPTED_VERSION_V2,
+  VAULT_KDF,
+  VAULT_KDF_V2,
+  VAULT_ALGORITHM,
+} from '../version';
+
+// ═══════════════════════════════════════════════════════════════════════════
+// IDENTITY TYPES
+// ═══════════════════════════════════════════════════════════════════════════
+
+export interface HybridIdentityRecord {
+  /** Unique identity ID */
+  id: string;
+  /** Display name */
+  name: string;
+  /** X25519 public key (hex) */
+  x25519PubHex: string;
+  /** X25519 secret key (hex) - encrypted in vault */
+  x25519SecHex: string;
+  /** Kyber public key (base64) */
+  kyberPubB64: string;
+  /** Kyber secret key (base64) - encrypted in vault */
+  kyberSecB64: string;
+  /** Creation timestamp */
+  createdAt: string;
+  /** Last rotation timestamp */
+  lastRotatedAt?: string;
+  /** Device fingerprint */
+  deviceFingerprint?: string;
+  /** Key rotation count */
+  rotationCount: number;
+  /** Identity metadata */
+  metadata?: {
+    label?: string;
+    notes?: string;
+    tags?: string[];
+  };
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// VAULT TYPES
+// ═══════════════════════════════════════════════════════════════════════════
+
+export interface VaultSettings {
+  /** Auto-unlock on return (session memory) */
+  autoUnlock: boolean;
+  /** Last used identity ID */
+  lastUsedIdentity?: string;
+  /** Lock timeout in minutes (0 = never auto-lock) */
+  lockTimeout: number;
+  /** Show key fingerprints in UI */
+  showFingerprints: boolean;
+}
+
+export interface OmnituumVault {
+  /** Vault format version (FROZEN - see pqc-docs/specs/vault.v1.md) */
+  version: typeof VAULT_VERSION;
+  /** Stored identities */
+  identities: HybridIdentityRecord[];
+  /** Vault settings */
+  settings: VaultSettings;
+  /** SHA-256 hash of serialized identities (integrity check) */
+  integrityHash: string;
+  /** Vault creation timestamp */
+  createdAt: string;
+  /** Last modified timestamp */
+  modifiedAt: string;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// ENCRYPTED VAULT TYPES
+// ═══════════════════════════════════════════════════════════════════════════
+
+/** V1 encrypted vault (PBKDF2) */
+export interface EncryptedVaultFileV1 {
+  /** File format version (FROZEN - see pqc-docs/specs/vault.v1.md) */
+  version: typeof VAULT_ENCRYPTED_VERSION;
+  /** Key derivation function */
+  kdf: typeof VAULT_KDF;
+  /** PBKDF2 iterations */
+  iterations: number;
+  /** Salt (base64) */
+  salt: string;
+  /** AES-GCM IV (base64) */
+  iv: string;
+  /** Encrypted vault (base64) */
+  ciphertext: string;
+  /** Auth tag included in ciphertext (AES-GCM) */
+  algorithm: typeof VAULT_ALGORITHM;
+}
+
+/** V2 encrypted vault (Argon2id) */
+export interface EncryptedVaultFileV2 {
+  /** File format version */
+  version: typeof VAULT_ENCRYPTED_VERSION_V2;
+  /** Key derivation function */
+  kdf: typeof VAULT_KDF_V2;
+  /** Argon2id memory cost (KiB) */
+  memoryCost: number;
+  /** Argon2id time cost (iterations) */
+  timeCost: number;
+  /** Argon2id parallelism */
+  parallelism: number;
+  /** Salt (base64) */
+  salt: string;
+  /** AES-GCM IV (base64) */
+  iv: string;
+  /** Encrypted vault (base64) */
+  ciphertext: string;
+  /** Auth tag included in ciphertext (AES-GCM) */
+  algorithm: typeof VAULT_ALGORITHM;
+}
+
+/** Union type for any encrypted vault version */
+export type EncryptedVaultFile = EncryptedVaultFileV1 | EncryptedVaultFileV2;
+
+// ═══════════════════════════════════════════════════════════════════════════
+// HEALTH CHECK TYPES
+// ═══════════════════════════════════════════════════════════════════════════
+
+export type HealthStatus = 'healthy' | 'needs-rotation' | 'warning' | 'error';
+
+export interface IdentityHealth {
+  /** Overall health status */
+  status: HealthStatus;
+  /** Entropy score (0-100) */
+  entropyScore: number;
+  /** Integrity verified */
+  integrityValid: boolean;
+  /** SHA-256 fingerprint */
+  fingerprint: string;
+  /** Days since last rotation */
+  daysSinceRotation: number;
+  /** Kyber key valid */
+  kyberValid: boolean;
+  /** X25519 key valid */
+  x25519Valid: boolean;
+  /** Recommendations */
+  recommendations: string[];
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// SESSION TYPES
+// ═══════════════════════════════════════════════════════════════════════════
+
+export interface VaultSession {
+  /** Session active */
+  unlocked: boolean;
+  /** Derived encryption key (in memory only) */
+  sessionKey: CryptoKey | null;
+  /** Unlock timestamp */
+  unlockedAt: number | null;
+  /** Active identity ID */
+  activeIdentityId: string | null;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// DEFAULT VALUES
+// ═══════════════════════════════════════════════════════════════════════════
+
+export const DEFAULT_VAULT_SETTINGS: VaultSettings = {
+  autoUnlock: false,
+  lockTimeout: 15,
+  showFingerprints: true,
+};
+
+export const PBKDF2_ITERATIONS = 600000; // OWASP 2023 recommendation