auramaxx 1.0.0-alpha.4

package/server/lib/cold.ts

@@ -0,0 +1,874 @@
+import fs from 'fs';
+import path from 'path';
+import { ethers } from 'ethers';
+import { Keypair, Transaction, VersionedTransaction } from '@solana/web3.js';
+import { WalletInfo, EncryptedData } from '../types';
+import { encryptPrivateKey, decryptPrivateKey } from './encrypt';
+import { DATA_PATHS } from './config';
+import { deriveSolanaColdKeypair } from './solana/wallet';
+import { unlockCredentialVault, lockCredentialVault, lockAllCredentialVaults } from './credential-vault';
+import { ensureOurSecretForVault } from './oursecret';
+
+// Cold wallet derivation path: m/44'/60'/0'/0/0
+const COLD_PATH = "m/44'/60'/0'/0/0";
+const COLD_FILE = 'cold.json';
+const VAULT_PREFIX = 'vault-';
+const PRIMARY_VAULT_ID = 'primary';
+const AGENT_VAULT_NAME = 'agent';
+
+export type VaultMode = 'primary' | 'linked' | 'independent';
+
+// ---------------------------------------------------------------------------
+// Vault session stored in memory while a vault is unlocked
+// ---------------------------------------------------------------------------
+interface VaultSession {
+  id: string;
+  mnemonic: string;
+  address: string;           // EVM
+  solanaKeypair: Keypair;    // Solana
+}
+
+// In-memory storage - survives as long as process runs
+const vaultSessions = new Map<string, VaultSession>();
+let primaryVaultId: string | null = null;
+let primaryVaultPassword: string | null = null; // stored while primary is unlocked
+
+// ---------------------------------------------------------------------------
+// Vault file on disk
+// ---------------------------------------------------------------------------
+interface VaultFile {
+  address: string;
+  solanaAddress?: string;
+  encrypted: EncryptedData;
+  createdAt: string;
+  name?: string;
+  mode?: VaultMode;
+  linkedTo?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Public vault info (safe to expose)
+// ---------------------------------------------------------------------------
+export interface VaultInfo {
+  id: string;
+  name?: string;
+  address: string;
+  solanaAddress?: string;
+  mode: VaultMode;
+  linkedTo?: string;
+  isUnlocked: boolean;
+  isPrimary: boolean;
+  createdAt: string;
+}
+
+export interface CreateVaultResult {
+  id: string;
+  address: string;
+  solanaAddress: string;
+  mnemonic: string;
+  name?: string;
+  mode: VaultMode;
+  linkedTo?: string;
+}
+
+export interface CreateVaultOptions {
+  mode?: Exclude<VaultMode, 'primary'>;
+  linkedTo?: string;
+  seedOnboardingSecret?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// File path helpers
+// ---------------------------------------------------------------------------
+function getVaultFilePath(id: string): string {
+  return path.join(DATA_PATHS.wallets, `${VAULT_PREFIX}${id}.json`);
+}
+
+function getLegacyColdFilePath(): string {
+  return path.join(DATA_PATHS.wallets, COLD_FILE);
+}
+
+/**
+ * Auto-migrate cold.json → vault-primary.json if needed.
+ * Called on first access that needs to list vaults.
+ */
+let migrationDone = false;
+function ensureMigration(): void {
+  if (migrationDone) return;
+  migrationDone = true;
+
+  const legacyPath = getLegacyColdFilePath();
+  const primaryPath = getVaultFilePath(PRIMARY_VAULT_ID);
+
+  if (fs.existsSync(legacyPath) && !fs.existsSync(primaryPath)) {
+    // Migrate: copy cold.json content into vault-primary.json
+    const raw = fs.readFileSync(legacyPath, 'utf-8');
+    fs.writeFileSync(primaryPath, raw);
+    // Remove old file
+    fs.unlinkSync(legacyPath);
+  }
+
+  // If primary vault file exists, ensure primaryVaultId is set
+  if (fs.existsSync(primaryPath) && !primaryVaultId) {
+    primaryVaultId = PRIMARY_VAULT_ID;
+  }
+}
+
+function isVaultMode(value: unknown): value is VaultMode {
+  return value === 'primary' || value === 'linked' || value === 'independent';
+}
+
+function readVaultFile(id: string): VaultFile {
+  const filePath = getVaultFilePath(id);
+  return JSON.parse(fs.readFileSync(filePath, 'utf-8')) as VaultFile;
+}
+
+function writeVaultFile(id: string, data: VaultFile): void {
+  const filePath = getVaultFilePath(id);
+  fs.writeFileSync(filePath, JSON.stringify(data, null, 2));
+}
+
+function resolveVaultMode(id: string, data: VaultFile): VaultMode {
+  if (id === PRIMARY_VAULT_ID || id === primaryVaultId) return 'primary';
+  if (isVaultMode(data.mode) && data.mode !== 'primary') return data.mode;
+  return 'independent';
+}
+
+function resolveLinkedTo(id: string, data: VaultFile, mode: VaultMode): string | undefined {
+  if (mode !== 'linked') return undefined;
+  if (typeof data.linkedTo === 'string' && data.linkedTo.trim()) return data.linkedTo;
+  // Default linked target is primary when omitted.
+  return primaryVaultId || PRIMARY_VAULT_ID;
+}
+
+// ---------------------------------------------------------------------------
+// Vault CRUD
+// ---------------------------------------------------------------------------
+
+/**
+ * List all vault files on disk. Returns VaultInfo for each.
+ */
+export function listVaults(): VaultInfo[] {
+  ensureMigration();
+
+  const walletsDir = DATA_PATHS.wallets;
+  if (!fs.existsSync(walletsDir)) return [];
+
+  const files = fs.readdirSync(walletsDir);
+  const vaults: VaultInfo[] = [];
+
+  for (const file of files) {
+    if (!file.startsWith(VAULT_PREFIX) || !file.endsWith('.json')) continue;
+    const id = file.slice(VAULT_PREFIX.length, -5); // strip prefix and .json
+
+    try {
+      const raw = fs.readFileSync(path.join(walletsDir, file), 'utf-8');
+      const data: VaultFile = JSON.parse(raw);
+      const mode = resolveVaultMode(id, data);
+      const linkedTo = resolveLinkedTo(id, data, mode);
+      vaults.push({
+        id,
+        name: data.name,
+        address: data.address,
+        solanaAddress: data.solanaAddress,
+        mode,
+        linkedTo,
+        isUnlocked: vaultSessions.has(id),
+        isPrimary: id === primaryVaultId || id === PRIMARY_VAULT_ID,
+        createdAt: data.createdAt,
+      });
+    } catch {
+      // skip corrupt files
+    }
+  }
+
+  // Sort: primary first, linked next, then independent by createdAt
+  vaults.sort((a, b) => {
+    if (a.isPrimary) return -1;
+    if (b.isPrimary) return 1;
+    if (a.mode === 'linked' && b.mode !== 'linked') return -1;
+    if (b.mode === 'linked' && a.mode !== 'linked') return 1;
+    return new Date(a.createdAt).getTime() - new Date(b.createdAt).getTime();
+  });
+
+  return vaults;
+}
+
+/**
+ * Create a new vault with a fresh mnemonic.
+ */
+export function createVault(password: string, name?: string, options: CreateVaultOptions = {}): CreateVaultResult {
+  ensureMigration();
+
+  const id = generateVaultId();
+  const filePath = getVaultFilePath(id);
+
+  if (fs.existsSync(filePath)) {
+    throw new Error(`Vault file already exists: ${id}`);
+  }
+
+  const mnemonic = ethers.Mnemonic.entropyToPhrase(ethers.randomBytes(16));
+  const hdNode = ethers.HDNodeWallet.fromPhrase(mnemonic, undefined, COLD_PATH);
+  const solanaKeypair = deriveSolanaColdKeypair(mnemonic);
+  const solanaAddress = solanaKeypair.publicKey.toBase58();
+
+  const mode: Exclude<VaultMode, 'primary'> = options.mode || 'independent';
+  const linkedTo = mode === 'linked'
+    ? (options.linkedTo || primaryVaultId || PRIMARY_VAULT_ID)
+    : undefined;
+  if (mode === 'linked') {
+    if (!linkedTo) throw new Error('linked vault requires a linkedTo target');
+    if (!fs.existsSync(getVaultFilePath(linkedTo))) {
+      throw new Error(`linkedTo vault not found: ${linkedTo}`);
+    }
+  }
+
+  const encrypted = encryptPrivateKey(mnemonic, password);
+
+  const vaultFile: VaultFile = {
+    address: hdNode.address,
+    solanaAddress,
+    encrypted,
+    createdAt: new Date().toISOString(),
+    name,
+    mode,
+    linkedTo,
+  };
+
+  fs.writeFileSync(filePath, JSON.stringify(vaultFile, null, 2));
+
+  // Auto-unlock
+  vaultSessions.set(id, {
+    id,
+    mnemonic,
+    address: hdNode.address,
+    solanaKeypair,
+  });
+  unlockCredentialVault(id);
+
+  if (options.seedOnboardingSecret !== false) {
+    try {
+      ensureOurSecretForVault(id);
+    } catch (err) {
+      console.warn('[cold] Failed to seed OURSECRET onboarding note:', err);
+    }
+  }
+
+  return {
+    id,
+    address: hdNode.address,
+    solanaAddress,
+    mnemonic,
+    name,
+    mode,
+    linkedTo,
+  };
+}
+
+/**
+ * Import a vault from an existing mnemonic.
+ */
+export function importVault(mnemonic: string, password: string, name?: string, options: CreateVaultOptions = {}): VaultInfo {
+  ensureMigration();
+
+  // Normalize
+  const normalizedMnemonic = mnemonic.trim().toLowerCase().split(/\s+/).join(' ');
+  if (!ethers.Mnemonic.isValidMnemonic(normalizedMnemonic)) {
+    throw new Error('Invalid seed phrase');
+  }
+
+  const id = generateVaultId();
+  const filePath = getVaultFilePath(id);
+
+  const hdNode = ethers.HDNodeWallet.fromPhrase(normalizedMnemonic, undefined, COLD_PATH);
+  const solanaKeypair = deriveSolanaColdKeypair(normalizedMnemonic);
+  const solanaAddress = solanaKeypair.publicKey.toBase58();
+
+  const mode: Exclude<VaultMode, 'primary'> = options.mode || 'independent';
+  const linkedTo = mode === 'linked'
+    ? (options.linkedTo || primaryVaultId || PRIMARY_VAULT_ID)
+    : undefined;
+  if (mode === 'linked') {
+    if (!linkedTo) throw new Error('linked vault requires a linkedTo target');
+    if (!fs.existsSync(getVaultFilePath(linkedTo))) {
+      throw new Error(`linkedTo vault not found: ${linkedTo}`);
+    }
+  }
+
+  const encrypted = encryptPrivateKey(normalizedMnemonic, password);
+
+  const vaultFile: VaultFile = {
+    address: hdNode.address,
+    solanaAddress,
+    encrypted,
+    createdAt: new Date().toISOString(),
+    name,
+    mode,
+    linkedTo,
+  };
+
+  fs.writeFileSync(filePath, JSON.stringify(vaultFile, null, 2));
+
+  // Auto-unlock
+  vaultSessions.set(id, {
+    id,
+    mnemonic: normalizedMnemonic,
+    address: hdNode.address,
+    solanaKeypair,
+  });
+  unlockCredentialVault(id);
+
+  if (options.seedOnboardingSecret !== false) {
+    try {
+      ensureOurSecretForVault(id);
+    } catch (err) {
+      console.warn('[cold] Failed to seed OURSECRET onboarding note:', err);
+    }
+  }
+
+  return {
+    id,
+    name,
+    address: hdNode.address,
+    solanaAddress,
+    mode,
+    linkedTo,
+    isUnlocked: true,
+    isPrimary: false,
+    createdAt: vaultFile.createdAt,
+  };
+}
+
+/**
+ * Unlock a specific vault.
+ */
+export function unlockVault(id: string, password: string): boolean {
+  ensureMigration();
+
+  const filePath = getVaultFilePath(id);
+  if (!fs.existsSync(filePath)) {
+    throw new Error(`Vault not found: ${id}`);
+  }
+
+  const data: VaultFile = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+
+  try {
+    const mnemonic = decryptPrivateKey(data.encrypted, password);
+    const solanaKeypair = deriveSolanaColdKeypair(mnemonic);
+
+    vaultSessions.set(id, {
+      id,
+      mnemonic,
+      address: data.address,
+      solanaKeypair,
+    });
+    unlockCredentialVault(id);
+
+    // Cache primary password while unlocked so linked vaults can auto-unlock.
+    if (id === primaryVaultId || id === PRIMARY_VAULT_ID) {
+      primaryVaultPassword = password;
+    }
+
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Lock a specific vault.
+ */
+export function lockVault(id: string): void {
+  vaultSessions.delete(id);
+  lockCredentialVault(id);
+}
+
+/**
+ * Lock ALL vaults.
+ */
+export function lockAllVaults(): void {
+  vaultSessions.clear();
+  primaryVaultPassword = null;
+  lockAllCredentialVaults();
+}
+
+/**
+ * Get the mnemonic for a specific vault (must be unlocked).
+ */
+export function getVaultMnemonic(id: string): string | null {
+  return vaultSessions.get(id)?.mnemonic ?? null;
+}
+
+/**
+ * Check if a specific vault is unlocked.
+ */
+export function isVaultUnlocked(id: string): boolean {
+  return vaultSessions.has(id);
+}
+
+/**
+ * Get a vault's EVM address (from file, doesn't need unlock).
+ */
+export function getVaultAddress(id: string): string | null {
+  const session = vaultSessions.get(id);
+  if (session) return session.address;
+
+  const filePath = getVaultFilePath(id);
+  if (!fs.existsSync(filePath)) return null;
+
+  const data: VaultFile = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+  return data.address;
+}
+
+/**
+ * Get a vault's Solana address (from file, doesn't need unlock).
+ */
+export function getVaultSolanaAddress(id: string): string | null {
+  const session = vaultSessions.get(id);
+  if (session) return session.solanaKeypair.publicKey.toBase58();
+
+  const filePath = getVaultFilePath(id);
+  if (!fs.existsSync(filePath)) return null;
+
+  const data: VaultFile = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+  return data.solanaAddress || null;
+}
+
+/**
+ * Get a vault's Solana keypair (requires unlock).
+ */
+export function getVaultSolanaKeypair(id: string): Keypair | null {
+  return vaultSessions.get(id)?.solanaKeypair ?? null;
+}
+
+/**
+ * Delete a vault file and lock it.
+ */
+export function deleteVault(id: string): void {
+  lockVault(id);
+
+  const filePath = getVaultFilePath(id);
+  if (fs.existsSync(filePath)) {
+    fs.unlinkSync(filePath);
+  }
+
+  if (primaryVaultId === id) {
+    primaryVaultId = null;
+  }
+}
+
+/**
+ * Export seed for a specific vault (must be unlocked).
+ */
+export function exportVaultSeed(id: string): string | null {
+  return getVaultMnemonic(id);
+}
+
+/**
+ * Sign an EVM transaction with a specific vault.
+ */
+export async function signWithVault(
+  vaultId: string,
+  transaction: ethers.TransactionRequest,
+  provider: ethers.Provider
+): Promise<string> {
+  const session = vaultSessions.get(vaultId);
+  if (!session) {
+    throw new Error(`Vault ${vaultId} is locked. Unlock it first.`);
+  }
+
+  const hdNode = ethers.HDNodeWallet.fromPhrase(session.mnemonic, undefined, COLD_PATH);
+  const wallet = hdNode.connect(provider);
+  const tx = await wallet.sendTransaction(transaction);
+  return tx.hash;
+}
+
+/**
+ * Sign a Solana transaction with a specific vault's keypair.
+ */
+export function signSolanaVaultTransaction(vaultId: string, tx: Transaction): void {
+  const session = vaultSessions.get(vaultId);
+  if (!session) {
+    throw new Error(`Vault ${vaultId} is locked. Unlock it first.`);
+  }
+  tx.partialSign(session.solanaKeypair);
+}
+
+// ---------------------------------------------------------------------------
+// Generate short vault ID
+// ---------------------------------------------------------------------------
+function generateVaultId(): string {
+  const chars = 'abcdefghijklmnopqrstuvwxyz0123456789';
+  let id = '';
+  const bytes = ethers.randomBytes(6);
+  for (let i = 0; i < 6; i++) {
+    id += chars[bytes[i] % chars.length];
+  }
+  return id;
+}
+
+/**
+ * Get the cached primary vault password (available while primary is unlocked).
+ */
+export function getPrimaryVaultPassword(): string | null {
+  return primaryVaultPassword;
+}
+
+/**
+ * Ensure the default "agent" vault exists as a LINKED vault.
+ * This is only called during primary creation/import, not on every unlock/startup.
+ */
+export function ensureDefaultLinkedAgentVault(): { created: boolean; vaultId: string | null } {
+  ensureMigration();
+  if (!primaryVaultId || !primaryVaultPassword) {
+    return { created: false, vaultId: null };
+  }
+
+  const existing = listVaults().find(v => (v.name || '').trim().toLowerCase() === AGENT_VAULT_NAME);
+  if (existing) {
+    return { created: false, vaultId: existing.id };
+  }
+
+  const created = createVault(primaryVaultPassword, AGENT_VAULT_NAME, {
+    mode: 'linked',
+    linkedTo: primaryVaultId,
+    seedOnboardingSecret: false,
+  });
+  return { created: true, vaultId: created.id };
+}
+
+/**
+ * Auto-unlock linked vaults when primary is unlocked.
+ * Independent vaults remain locked until explicitly unlocked with their own password.
+ */
+export function autoUnlockLinkedVaults(): number {
+  if (!primaryVaultPassword) return 0;
+
+  const vaults = listVaults();
+  let unlocked = 0;
+  for (const v of vaults) {
+    if (v.isPrimary || v.isUnlocked || v.mode !== 'linked') continue;
+    try {
+      if (unlockVault(v.id, primaryVaultPassword)) unlocked++;
+    } catch (err) {
+      console.warn(
+        `[cold] Linked vault unlock failed for "${v.id}"${v.name ? ` (${v.name})` : ''}: ${String(err)}`
+      );
+    }
+  }
+  return unlocked;
+}
+
+/**
+ * Resolve the linked vault group for UI filtering.
+ * - Selecting primary or a linked vault returns root + all linked siblings.
+ * - Selecting independent vault returns only itself.
+ */
+export function getLinkedVaultGroup(vaultId: string): string[] {
+  const vaults = listVaults();
+  const selected = vaults.find(v => v.id === vaultId);
+  if (!selected) return [vaultId];
+  if (selected.mode === 'independent') return [selected.id];
+
+  const rootId = selected.mode === 'linked'
+    ? (selected.linkedTo || selected.id)
+    : selected.id;
+
+  const group = vaults
+    .filter(v => v.id === rootId || (v.mode === 'linked' && v.linkedTo === rootId))
+    .map(v => v.id);
+
+  return group.length > 0 ? group : [vaultId];
+}
+
+// ---------------------------------------------------------------------------
+// Reset for testing (clears all module state)
+// ---------------------------------------------------------------------------
+export function _resetForTesting(): void {
+  vaultSessions.clear();
+  primaryVaultId = null;
+  primaryVaultPassword = null;
+  migrationDone = false;
+}
+
+// ===========================================================================
+// BACKWARD COMPATIBILITY — all original exports still work via primary vault
+// ===========================================================================
+
+/**
+ * Get the primary vault ID (or null if none exists).
+ */
+export function getPrimaryVaultId(): string | null {
+  ensureMigration();
+  return primaryVaultId;
+}
+
+export function hasColdWallet(): boolean {
+  ensureMigration();
+  if (primaryVaultId && fs.existsSync(getVaultFilePath(primaryVaultId))) {
+    return true;
+  }
+  // Also check legacy path as fallback
+  return fs.existsSync(getLegacyColdFilePath());
+}
+
+export function isUnlocked(): boolean {
+  // Returns true if ANY vault is unlocked (backward compat)
+  return vaultSessions.size > 0;
+}
+
+export interface CreateWalletResult extends WalletInfo {
+  mnemonic: string;
+}
+
+export function createColdWallet(password: string): CreateWalletResult {
+  ensureMigration();
+
+  if (hasColdWallet()) {
+    throw new Error('Cold wallet already exists. Delete it first if you want to recreate.');
+  }
+
+  // Create as the primary vault
+  const result = createVault(password, undefined, { seedOnboardingSecret: false });
+
+  // Set as primary
+  primaryVaultId = result.id;
+
+  // Rename to vault-primary.json
+  const currentPath = getVaultFilePath(result.id);
+  const primaryPath = getVaultFilePath(PRIMARY_VAULT_ID);
+  fs.renameSync(currentPath, primaryPath);
+
+  // Update session key
+  const session = vaultSessions.get(result.id)!;
+  vaultSessions.delete(result.id);
+  vaultSessions.set(PRIMARY_VAULT_ID, { ...session, id: PRIMARY_VAULT_ID });
+  primaryVaultId = PRIMARY_VAULT_ID;
+  primaryVaultPassword = password;
+  unlockCredentialVault(PRIMARY_VAULT_ID);
+
+  // Persist primary mode metadata after rename.
+  try {
+    const primaryFile = readVaultFile(PRIMARY_VAULT_ID);
+    primaryFile.mode = 'primary';
+    delete primaryFile.linkedTo;
+    writeVaultFile(PRIMARY_VAULT_ID, primaryFile);
+  } catch (err) {
+    console.warn('[cold] Failed to persist primary vault mode metadata:', err);
+  }
+
+  // Seed primary onboarding secret after final vault ID is stable.
+  try {
+    ensureOurSecretForVault(PRIMARY_VAULT_ID);
+  } catch (err) {
+    console.warn('[cold] Failed to seed primary OURSECRET onboarding note:', err);
+  }
+
+  // Create default linked agent vault once at setup time.
+  try {
+    ensureDefaultLinkedAgentVault();
+  } catch (err) {
+    console.warn('[cold] Failed to create default linked agent vault:', err);
+  }
+
+  return {
+    address: result.address,
+    tier: 'cold',
+    chain: 'all',
+    createdAt: new Date().toISOString(),
+    mnemonic: result.mnemonic,
+  };
+}
+
+export function exportSeed(): string | null {
+  if (!primaryVaultId) return null;
+  return getVaultMnemonic(primaryVaultId);
+}
+
+export function unlock(password: string): boolean {
+  ensureMigration();
+
+  if (!primaryVaultId) {
+    throw new Error('No cold wallet found');
+  }
+
+  return unlockVault(primaryVaultId, password);
+}
+
+/**
+ * Rotate the primary vault password by re-encrypting the stored mnemonic wrapper.
+ * Returns false when the current password is invalid.
+ */
+export function rotatePrimaryVaultPassword(currentPassword: string, newPassword: string): boolean {
+  ensureMigration();
+
+  const vaultId = primaryVaultId || PRIMARY_VAULT_ID;
+  const filePath = getVaultFilePath(vaultId);
+  if (!fs.existsSync(filePath)) {
+    throw new Error('No cold wallet found');
+  }
+  if (newPassword.length < 8) {
+    throw new Error('Password must be at least 8 characters');
+  }
+
+  const vaultFile = readVaultFile(vaultId);
+  let mnemonic: string;
+  try {
+    mnemonic = decryptPrivateKey(vaultFile.encrypted, currentPassword);
+  } catch {
+    return false;
+  }
+
+  vaultFile.encrypted = encryptPrivateKey(mnemonic, newPassword);
+  writeVaultFile(vaultId, vaultFile);
+
+  if (primaryVaultPassword === currentPassword) {
+    primaryVaultPassword = newPassword;
+  }
+
+  return true;
+}
+
+export function lock(): void {
+  lockAllVaults();
+}
+
+export function getColdWalletAddress(): string | null {
+  if (!primaryVaultId) {
+    ensureMigration();
+    if (!primaryVaultId) return null;
+  }
+  return getVaultAddress(primaryVaultId);
+}
+
+export function getMnemonic(): string | null {
+  if (!primaryVaultId) return null;
+  return getVaultMnemonic(primaryVaultId);
+}
+
+export async function signWithColdWallet(
+  transaction: ethers.TransactionRequest,
+  provider: ethers.Provider
+): Promise<string> {
+  if (!primaryVaultId) {
+    throw new Error('No primary vault configured');
+  }
+  return signWithVault(primaryVaultId, transaction, provider);
+}
+
+export function getColdWalletInfo(): WalletInfo | null {
+  ensureMigration();
+  if (!primaryVaultId) return null;
+
+  const filePath = getVaultFilePath(primaryVaultId);
+  if (!fs.existsSync(filePath)) return null;
+
+  const data: VaultFile = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+
+  return {
+    address: data.address,
+    tier: 'cold',
+    chain: 'all',
+    createdAt: data.createdAt,
+  };
+}
+
+export function getSolanaColdAddress(): string | null {
+  if (!primaryVaultId) {
+    ensureMigration();
+    if (!primaryVaultId) return null;
+  }
+  return getVaultSolanaAddress(primaryVaultId);
+}
+
+export function getSolanaColdKeypair(): Keypair | null {
+  if (!primaryVaultId) return null;
+  return getVaultSolanaKeypair(primaryVaultId);
+}
+
+export function signSolanaColdTransaction(tx: Transaction): void {
+  if (!primaryVaultId) {
+    throw new Error('No primary vault configured');
+  }
+  signSolanaVaultTransaction(primaryVaultId, tx);
+}
+
+export function deleteColdWallet(): void {
+  if (primaryVaultId) {
+    deleteVault(primaryVaultId);
+  }
+  // Also remove legacy file if it exists
+  const legacyPath = getLegacyColdFilePath();
+  if (fs.existsSync(legacyPath)) {
+    fs.unlinkSync(legacyPath);
+  }
+}
+
+export function importColdWallet(mnemonic: string, password: string): WalletInfo {
+  ensureMigration();
+
+  if (hasColdWallet()) {
+    throw new Error('Cold wallet already exists. Delete it first if you want to import.');
+  }
+
+  const info = importVault(mnemonic, password, undefined, { seedOnboardingSecret: false });
+
+  // Make it the primary vault
+  const currentPath = getVaultFilePath(info.id);
+  const primaryPath = getVaultFilePath(PRIMARY_VAULT_ID);
+  fs.renameSync(currentPath, primaryPath);
+
+  // Update session key
+  const session = vaultSessions.get(info.id)!;
+  vaultSessions.delete(info.id);
+  vaultSessions.set(PRIMARY_VAULT_ID, { ...session, id: PRIMARY_VAULT_ID });
+  primaryVaultId = PRIMARY_VAULT_ID;
+  primaryVaultPassword = password;
+  unlockCredentialVault(PRIMARY_VAULT_ID);
+
+  // Persist primary mode metadata after rename.
+  try {
+    const primaryFile = readVaultFile(PRIMARY_VAULT_ID);
+    primaryFile.mode = 'primary';
+    delete primaryFile.linkedTo;
+    writeVaultFile(PRIMARY_VAULT_ID, primaryFile);
+  } catch (err) {
+    console.warn('[cold] Failed to persist primary vault mode metadata:', err);
+  }
+
+  // Seed primary onboarding secret after final vault ID is stable.
+  try {
+    ensureOurSecretForVault(PRIMARY_VAULT_ID);
+  } catch (err) {
+    console.warn('[cold] Failed to seed primary OURSECRET onboarding note:', err);
+  }
+
+  // Create default linked agent vault once at import time.
+  try {
+    ensureDefaultLinkedAgentVault();
+  } catch (err) {
+    console.warn('[cold] Failed to create default linked agent vault:', err);
+  }
+
+  return {
+    address: info.address,
+    tier: 'cold',
+    chain: 'all',
+    createdAt: info.createdAt,
+  };
+}
+
+// Derive a hot wallet at a specific index
+// Hot wallets use path: m/44'/60'/1'/0/N
+export function deriveHotWallet(index: number): ethers.HDNodeWallet {
+  if (!primaryVaultId) {
+    throw new Error('No primary vault configured');
+  }
+  const mnemonic = getVaultMnemonic(primaryVaultId);
+  if (!mnemonic) {
+    throw new Error('Primary vault is locked. Unlock it first.');
+  }
+
+  const hotPath = `m/44'/60'/1'/0/${index}`;
+  return ethers.HDNodeWallet.fromPhrase(mnemonic, undefined, hotPath);
+}