auramaxx 1.0.0-alpha.4

package/server/lib/encrypt.ts

@@ -0,0 +1,128 @@
+import CryptoJS from 'crypto-js';
+import { randomBytes, scryptSync, createCipheriv, createDecipheriv } from 'crypto';
+import { EncryptedData } from '../types';
+
+const ALGORITHM = 'aes-256-ctr';
+const SCRYPT_COST = 16384; // 2^14
+const SCRYPT_BLOCK_SIZE = 8;
+const SCRYPT_PARALLELIZATION = 1;
+const DKLEN = 32;
+
+export function encryptPrivateKey(privateKey: string, password: string): EncryptedData {
+  const salt = randomBytes(32);
+  const iv = randomBytes(16);
+
+  const derivedKey = scryptSync(password, salt, DKLEN, {
+    cost: SCRYPT_COST,
+    blockSize: SCRYPT_BLOCK_SIZE,
+    parallelization: SCRYPT_PARALLELIZATION
+  });
+
+  const cipher = createCipheriv(ALGORITHM, derivedKey, iv);
+  const ciphertext = Buffer.concat([
+    cipher.update(privateKey, 'utf8'),
+    cipher.final()
+  ]);
+
+  const mac = CryptoJS.HmacSHA256(
+    ciphertext.toString('hex') + iv.toString('hex'),
+    derivedKey.toString('hex')
+  ).toString();
+
+  return {
+    ciphertext: ciphertext.toString('hex'),
+    iv: iv.toString('hex'),
+    salt: salt.toString('hex'),
+    mac
+  };
+}
+
+export function decryptPrivateKey(encrypted: EncryptedData, password: string): string {
+  const salt = Buffer.from(encrypted.salt, 'hex');
+  const iv = Buffer.from(encrypted.iv, 'hex');
+  const ciphertext = Buffer.from(encrypted.ciphertext, 'hex');
+
+  const derivedKey = scryptSync(password, salt, DKLEN, {
+    cost: SCRYPT_COST,
+    blockSize: SCRYPT_BLOCK_SIZE,
+    parallelization: SCRYPT_PARALLELIZATION
+  });
+
+  const expectedMac = CryptoJS.HmacSHA256(
+    encrypted.ciphertext + encrypted.iv,
+    derivedKey.toString('hex')
+  ).toString();
+
+  if (expectedMac !== encrypted.mac) {
+    throw new Error('Invalid password or corrupted data');
+  }
+
+  const decipher = createDecipheriv(ALGORITHM, derivedKey, iv);
+  const decrypted = Buffer.concat([
+    decipher.update(ciphertext),
+    decipher.final()
+  ]);
+
+  return decrypted.toString('utf8');
+}
+
+/**
+ * Encrypt data using a seed phrase (mnemonic) as the key.
+ * Uses faster key derivation since mnemonic has high entropy.
+ */
+export function encryptWithSeed(data: string, seed: string): EncryptedData {
+  const iv = randomBytes(16);
+  // Use SHA-256 of seed as key (mnemonic has enough entropy, no need for slow scrypt)
+  const derivedKey = Buffer.from(
+    CryptoJS.SHA256(seed).toString(CryptoJS.enc.Hex),
+    'hex'
+  );
+
+  const cipher = createCipheriv(ALGORITHM, derivedKey, iv);
+  const ciphertext = Buffer.concat([
+    cipher.update(data, 'utf8'),
+    cipher.final()
+  ]);
+
+  const mac = CryptoJS.HmacSHA256(
+    ciphertext.toString('hex') + iv.toString('hex'),
+    derivedKey.toString('hex')
+  ).toString();
+
+  return {
+    ciphertext: ciphertext.toString('hex'),
+    iv: iv.toString('hex'),
+    salt: '', // Not needed for seed-based encryption
+    mac
+  };
+}
+
+/**
+ * Decrypt data using a seed phrase (mnemonic) as the key.
+ */
+export function decryptWithSeed(encrypted: EncryptedData, seed: string): string {
+  const iv = Buffer.from(encrypted.iv, 'hex');
+  const ciphertext = Buffer.from(encrypted.ciphertext, 'hex');
+
+  const derivedKey = Buffer.from(
+    CryptoJS.SHA256(seed).toString(CryptoJS.enc.Hex),
+    'hex'
+  );
+
+  const expectedMac = CryptoJS.HmacSHA256(
+    encrypted.ciphertext + encrypted.iv,
+    derivedKey.toString('hex')
+  ).toString();
+
+  if (expectedMac !== encrypted.mac) {
+    throw new Error('Invalid seed or corrupted data');
+  }
+
+  const decipher = createDecipheriv(ALGORITHM, derivedKey, iv);
+  const decrypted = Buffer.concat([
+    decipher.update(ciphertext),
+    decipher.final()
+  ]);
+
+  return decrypted.toString('utf8');
+}

package/server/lib/error.ts

@@ -0,0 +1,20 @@
+/**
+ * Shared error helpers used across routes and lib modules.
+ */
+
+/**
+ * Extract a human-readable message from an unknown catch value.
+ */
+export function getErrorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : 'Unknown error';
+}
+
+/**
+ * An error with an HTTP status code, thrown by validation helpers
+ * so callers can respond with the correct status.
+ */
+export class HttpError extends Error {
+  constructor(public status: number, message: string) {
+    super(message);
+  }
+}

package/server/lib/events.ts

@@ -0,0 +1,205 @@
+/**
+ * Webhook emitter for notifying Next.js of wallet events
+ * Posts events to Next.js API which broadcasts to WebSocket clients
+ * Also stores all events in database for debugging/audit trail
+ */
+
+import { prisma } from './db';
+import { log } from './pino';
+
+// Event types (mirrored from src/lib/events.ts)
+export const WALLET_EVENTS = {
+  TOKEN_CREATED: 'token:created',
+  TOKEN_REVOKED: 'token:revoked',
+  TOKEN_SPENT: 'token:spent',
+  WALLET_CREATED: 'wallet:created',
+  WALLET_CHANGED: 'wallet:changed',
+  ASSET_CHANGED: 'asset:changed',
+  TX_CREATED: 'tx:created',
+  ACTION_CREATED: 'action:created',
+  ACTION_RESOLVED: 'action:resolved',
+  VAULT_UNLOCKED: 'vault:unlocked',
+  CREDENTIAL_CHANGED: 'credential:changed',
+  CREDENTIAL_ACCESSED: 'credential:accessed',
+} as const;
+
+export type WalletEventType = (typeof WALLET_EVENTS)[keyof typeof WALLET_EVENTS];
+
+interface WalletEvent<T = unknown> {
+  type: WalletEventType | string;
+  timestamp: number;
+  source: 'express' | 'nextjs';
+  data: T;
+}
+
+// WebSocket server broadcast endpoint (runs on port 4748)
+const WS_BROADCAST_URL = process.env.WS_BROADCAST_URL ?? 'http://localhost:4748/broadcast';
+
+/**
+ * Store event in database (non-blocking)
+ * Automatically stores all events for debugging and audit purposes
+ */
+function storeEvent<T>(event: WalletEvent<T>): void {
+  prisma.event.create({
+    data: {
+      type: event.type,
+      source: event.source,
+      data: JSON.stringify(event.data),
+      timestamp: new Date(event.timestamp),
+    },
+  })
+    .then(() => {
+      // Stored successfully
+    })
+    .catch((err) => {
+      log.error({ err: err.message }, 'failed to store event in DB');
+    });
+}
+
+/**
+ * Emit a wallet event to Next.js webhook
+ * Non-blocking - failures are logged but don't affect the calling code
+ * Events are automatically stored in the database
+ */
+export function emitWalletEvent<T>(type: WalletEventType | string, data: T): void {
+  const event: WalletEvent<T> = {
+    type,
+    timestamp: Date.now(),
+    source: 'express',
+    data,
+  };
+
+  // Store in database (non-blocking)
+  storeEvent(event);
+
+  // Fire and forget broadcast to WebSocket server - don't block the request
+  // Skip when WS_BROADCAST_URL is empty (e.g. in tests)
+  if (!WS_BROADCAST_URL) return;
+
+  fetch(WS_BROADCAST_URL, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(event),
+  })
+    .then((res) => {
+      if (!res.ok) {
+        log.warn({ status: res.status, type }, 'WebSocket broadcast failed');
+      }
+    })
+    .catch((err) => {
+      // Log but don't throw - this is non-critical
+      log.warn({ err: err.message, type }, 'failed to broadcast to WebSocket');
+    });
+}
+
+// Type-safe event emitters for each event type
+export const events = {
+  tokenCreated: (data: {
+    tokenHash: string;
+    agentId: string;
+    limit: number;
+    permissions: string[];
+    expiresAt: number;
+  }) => emitWalletEvent(WALLET_EVENTS.TOKEN_CREATED, data),
+
+  tokenRevoked: (data: { tokenHash: string }) =>
+    emitWalletEvent(WALLET_EVENTS.TOKEN_REVOKED, data),
+
+  tokenSpent: (data: {
+    tokenHash: string;
+    amount: number;
+    newSpent: number;
+    remaining: number;
+    limitType?: 'fund' | 'send' | 'swap';
+  }) => emitWalletEvent(WALLET_EVENTS.TOKEN_SPENT, data),
+
+  walletCreated: (data: {
+    address: string;
+    tier: 'hot' | 'temp';
+    chain: string;
+    name?: string;
+    tokenHash?: string;
+  }) => emitWalletEvent(WALLET_EVENTS.WALLET_CREATED, data),
+
+  walletChanged: (data: {
+    address: string;
+    reason: 'created' | 'updated';
+  }) => emitWalletEvent(WALLET_EVENTS.WALLET_CHANGED, data),
+
+  assetChanged: (data: {
+    walletAddress: string;
+    tokenAddress: string;
+    symbol?: string;
+    name?: string;
+    poolAddress?: string;
+    poolVersion?: string;
+    icon?: string;
+    removed?: boolean;
+  }) => emitWalletEvent(WALLET_EVENTS.ASSET_CHANGED, data),
+
+  txCreated: (data: {
+    walletAddress: string;
+    id: string;
+    type: string;
+    txHash?: string;
+    amount?: string;
+    tokenAddress?: string;
+    tokenAmount?: string;
+    description?: string;
+  }) => emitWalletEvent(WALLET_EVENTS.TX_CREATED, data),
+
+  actionCreated: (data: {
+    id: string;
+    type: string;
+    source: string;
+    summary: string;
+    expiresAt: number | null;
+    metadata?: Record<string, unknown>;
+  }) => emitWalletEvent(WALLET_EVENTS.ACTION_CREATED, data),
+
+  actionResolved: (data: {
+    id: string;
+    type: string;
+    approved: boolean;
+    resolvedBy: string;
+  }) => emitWalletEvent(WALLET_EVENTS.ACTION_RESOLVED, data),
+
+  vaultUnlocked: (data: { address: string; vaultId: string }) =>
+    emitWalletEvent(WALLET_EVENTS.VAULT_UNLOCKED, data),
+
+  credentialChanged: (data: {
+    credentialId: string;
+    vaultId: string;
+    change:
+      | 'created'
+      | 'updated'
+      | 'archived'
+      | 'moved_to_recently_deleted'
+      | 'restored_to_active'
+      | 'restored_to_archive'
+      | 'purged';
+    actorType: 'admin' | 'agent';
+    agentId?: string;
+    tokenHash?: string;
+    fromLocation?: 'active' | 'archive' | 'recently_deleted';
+    toLocation?: 'active' | 'archive' | 'recently_deleted';
+  }) => emitWalletEvent(WALLET_EVENTS.CREDENTIAL_CHANGED, data),
+
+  credentialAccessed: (data: {
+    credentialId: string;
+    vaultId: string;
+    action: 'credentials.read' | 'credentials.totp';
+    allowed: boolean;
+    reasonCode: string;
+    httpStatus: number;
+    actorType: 'admin' | 'agent';
+    agentId?: string;
+    tokenHash?: string;
+  }) => emitWalletEvent(WALLET_EVENTS.CREDENTIAL_ACCESSED, data),
+
+  /**
+   * Generic event emitter for custom/new event types
+   * Events are automatically stored in the database
+   */
+  custom: <T>(type: string, data: T) => emitWalletEvent(type, data),
+};

package/server/lib/hot.ts

@@ -0,0 +1,357 @@
+import { ethers } from 'ethers';
+import { WalletInfo, EncryptedData } from '../types';
+import { getMnemonic, isUnlocked, getVaultMnemonic, isVaultUnlocked, getPrimaryVaultId } from './cold';
+import { encryptWithSeed, decryptWithSeed } from './encrypt';
+import { prisma } from './db';
+import { normalizeAddress, isSolanaChain } from './address';
+import { createSolanaHotWallet, getSolanaKeypair, signSolanaTransaction } from './solana/wallet';
+
+export interface HotWalletInfo extends WalletInfo {
+  name?: string;
+  color?: string;
+  description?: string;
+  emoji?: string;
+  hidden?: boolean;
+  tokenHash: string;
+}
+
+export interface CreateHotWalletOptions {
+  tokenHash: string;
+  chain?: string;
+  name?: string;
+  color?: string;
+  description?: string;
+  emoji?: string;
+  hidden?: boolean;
+  coldWalletId?: string;  // Which vault to encrypt with (null = primary)
+}
+
+/**
+ * Create a new hot wallet with random keypair, encrypted with the seed phrase.
+ * The wallet is owned by the token that creates it.
+ */
+export async function createHotWallet(options: CreateHotWalletOptions): Promise<HotWalletInfo> {
+  const { chain = 'base', coldWalletId } = options;
+
+  // Delegate to Solana wallet creation if Solana chain
+  if (isSolanaChain(chain)) {
+    return createSolanaHotWallet(options);
+  }
+
+  // Get mnemonic from specific vault or primary
+  const mnemonic = coldWalletId ? getVaultMnemonic(coldWalletId) : getMnemonic();
+  if (!mnemonic) {
+    const target = coldWalletId ? `Vault ${coldWalletId}` : 'Cold wallet';
+    throw new Error(`${target} must be unlocked to create hot wallets`);
+  }
+
+  const { tokenHash, name, color, description, emoji, hidden = false } = options;
+
+  // Generate random wallet
+  const wallet = ethers.Wallet.createRandom();
+
+  // Encrypt private key with seed phrase
+  const encrypted = encryptWithSeed(wallet.privateKey, mnemonic);
+
+  // Store in DB (with coldWalletId reference)
+  const hotWallet = await prisma.hotWallet.create({
+    data: {
+      address: normalizeAddress(wallet.address, chain),
+      encryptedPrivateKey: JSON.stringify(encrypted),
+      tokenHash,
+      coldWalletId: coldWalletId || null,
+      name,
+      color,
+      description,
+      emoji,
+      hidden,
+      chain,
+    },
+  });
+
+  return {
+    address: hotWallet.address,
+    tier: 'hot',
+    chain: hotWallet.chain,
+    createdAt: hotWallet.createdAt.toISOString(),
+    name: hotWallet.name || undefined,
+    color: hotWallet.color || undefined,
+    description: hotWallet.description || undefined,
+    emoji: hotWallet.emoji || undefined,
+    hidden: hotWallet.hidden,
+    tokenHash: hotWallet.tokenHash,
+  };
+}
+
+/**
+ * List hot wallets. If tokenHash is provided, filter to only wallets owned by that token.
+ * If not provided (human access), return all wallets.
+ * If includeHidden is false (default), hidden wallets are excluded.
+ */
+export async function listHotWallets(tokenHash?: string, includeHidden: boolean = false): Promise<HotWalletInfo[]> {
+  const where: { tokenHash?: string; hidden?: boolean } = {};
+  if (tokenHash) where.tokenHash = tokenHash;
+  if (!includeHidden) where.hidden = false;
+
+  const wallets = await prisma.hotWallet.findMany({
+    where,
+    orderBy: { createdAt: 'desc' },
+  });
+
+  return wallets.map((w) => ({
+    address: w.address,
+    tier: 'hot' as const,
+    chain: w.chain,
+    createdAt: w.createdAt.toISOString(),
+    name: w.name || undefined,
+    color: w.color || undefined,
+    description: w.description || undefined,
+    emoji: w.emoji || undefined,
+    hidden: w.hidden,
+    tokenHash: w.tokenHash,
+  }));
+}
+
+/**
+ * Get a hot wallet by address.
+ */
+export async function getHotWallet(address: string) {
+  // Try lowercase first (EVM), then exact match (Solana)
+  let wallet = await prisma.hotWallet.findUnique({
+    where: { address: address.toLowerCase() },
+  });
+  if (!wallet && address !== address.toLowerCase()) {
+    wallet = await prisma.hotWallet.findUnique({
+      where: { address },
+    });
+  }
+
+  if (!wallet) return null;
+
+  return {
+    address: wallet.address,
+    tokenHash: wallet.tokenHash,
+    coldWalletId: wallet.coldWalletId,
+    metadata: {
+      name: wallet.name,
+      color: wallet.color,
+      description: wallet.description,
+      emoji: wallet.emoji,
+      hidden: wallet.hidden,
+      chain: wallet.chain,
+      createdAt: wallet.createdAt.toISOString(),
+    },
+  };
+}
+
+/**
+ * Sign and send a transaction from a hot wallet.
+ * Requires the cold wallet to be unlocked to decrypt the private key.
+ */
+export async function signWithHotWallet(
+  address: string,
+  transaction: ethers.TransactionRequest,
+  provider: ethers.Provider
+): Promise<{ hash: string }> {
+  // Try lowercase first (EVM), then exact match (Solana)
+  let wallet = await prisma.hotWallet.findUnique({
+    where: { address: address.toLowerCase() },
+  });
+  if (!wallet && address !== address.toLowerCase()) {
+    wallet = await prisma.hotWallet.findUnique({
+      where: { address },
+    });
+  }
+
+  if (!wallet) {
+    throw new Error(`Hot wallet not found: ${address}`);
+  }
+
+  // Get mnemonic from the vault this hot wallet belongs to
+  const mnemonic = wallet.coldWalletId
+    ? getVaultMnemonic(wallet.coldWalletId)
+    : getMnemonic();
+  if (!mnemonic) {
+    const target = wallet.coldWalletId ? `Vault ${wallet.coldWalletId}` : 'Cold wallet';
+    throw new Error(`${target} must be unlocked to sign from hot wallet`);
+  }
+
+  // Decrypt the private key
+  const encrypted: EncryptedData = JSON.parse(wallet.encryptedPrivateKey);
+  const privateKey = decryptWithSeed(encrypted, mnemonic);
+
+  // Create signer and send transaction
+  const signer = new ethers.Wallet(privateKey, provider);
+  const tx = await signer.sendTransaction(transaction);
+
+  return { hash: tx.hash };
+}
+
+/**
+ * Export a hot wallet's private key.
+ * Requires the cold wallet to be unlocked.
+ */
+export async function exportHotWallet(address: string): Promise<{ address: string; privateKey: string }> {
+  // Try lowercase first (EVM), then exact match (Solana)
+  let wallet = await prisma.hotWallet.findUnique({
+    where: { address: address.toLowerCase() },
+  });
+  if (!wallet && address !== address.toLowerCase()) {
+    wallet = await prisma.hotWallet.findUnique({
+      where: { address },
+    });
+  }
+
+  if (!wallet) {
+    throw new Error(`Hot wallet not found: ${address}`);
+  }
+
+  // Get mnemonic from the vault this hot wallet belongs to
+  const mnemonic = wallet.coldWalletId
+    ? getVaultMnemonic(wallet.coldWalletId)
+    : getMnemonic();
+  if (!mnemonic) {
+    const target = wallet.coldWalletId ? `Vault ${wallet.coldWalletId}` : 'Cold wallet';
+    throw new Error(`${target} must be unlocked to export hot wallet`);
+  }
+
+  // Decrypt the private key
+  const encrypted: EncryptedData = JSON.parse(wallet.encryptedPrivateKey);
+  const privateKey = decryptWithSeed(encrypted, mnemonic);
+
+  return {
+    address: wallet.address,
+    privateKey,
+  };
+}
+
+/**
+ * Delete a hot wallet.
+ */
+export async function deleteHotWallet(address: string): Promise<void> {
+  // Try lowercase first (EVM), then exact (Solana)
+  try {
+    await prisma.hotWallet.delete({ where: { address: address.toLowerCase() } });
+  } catch {
+    if (address !== address.toLowerCase()) {
+      await prisma.hotWallet.delete({ where: { address } }).catch(() => {});
+    }
+  }
+}
+
+/**
+ * Update hot wallet metadata.
+ */
+export async function updateHotWallet(
+  address: string,
+  updates: { name?: string; color?: string; description?: string; emoji?: string; hidden?: boolean }
+): Promise<boolean> {
+  try {
+    await prisma.hotWallet.update({
+      where: { address: address.toLowerCase() },
+      data: updates,
+    });
+    return true;
+  } catch {
+    // Try exact match (Solana addresses are case-sensitive)
+    if (address !== address.toLowerCase()) {
+      try {
+        await prisma.hotWallet.update({
+          where: { address },
+          data: updates,
+        });
+        return true;
+      } catch {
+        return false;
+      }
+    }
+    return false;
+  }
+}
+
+/**
+ * Search hot wallets by name, address, or description.
+ * If tokenHash is provided, filter to only wallets owned by that token.
+ * Always includes hidden wallets in search results.
+ */
+export async function searchHotWallets(query: string, tokenHash?: string): Promise<HotWalletInfo[]> {
+  const lowerQuery = query.toLowerCase();
+
+  const where: { tokenHash?: string; OR: Array<{ name?: { contains: string }; address?: { contains: string }; description?: { contains: string } }> } = {
+    OR: [
+      { name: { contains: lowerQuery } },
+      { address: { contains: lowerQuery } },
+      { description: { contains: lowerQuery } },
+    ],
+  };
+  if (tokenHash) where.tokenHash = tokenHash;
+
+  const wallets = await prisma.hotWallet.findMany({
+    where,
+    orderBy: { createdAt: 'desc' },
+  });
+
+  return wallets.map((w) => ({
+    address: w.address,
+    tier: 'hot' as const,
+    chain: w.chain,
+    createdAt: w.createdAt.toISOString(),
+    name: w.name || undefined,
+    color: w.color || undefined,
+    description: w.description || undefined,
+    emoji: w.emoji || undefined,
+    hidden: w.hidden,
+    tokenHash: w.tokenHash,
+  }));
+}
+
+/**
+ * Check if a token owns a specific hot wallet.
+ */
+export async function tokenOwnsWallet(tokenHash: string, address: string): Promise<boolean> {
+  // Try lowercase first (EVM), then exact match (Solana)
+  let wallet = await prisma.hotWallet.findUnique({
+    where: { address: address.toLowerCase() },
+    select: { tokenHash: true },
+  });
+  if (!wallet && address !== address.toLowerCase()) {
+    wallet = await prisma.hotWallet.findUnique({
+      where: { address },
+      select: { tokenHash: true },
+    });
+  }
+
+  return wallet?.tokenHash === tokenHash;
+}
+
+/**
+ * Check if a token can access a specific wallet.
+ * A token can access a wallet if:
+ *   1. The token created the wallet (tokenHash match), OR
+ *   2. The wallet address is in the token's walletAccess array
+ *
+ * @param tokenHash - Hash of the token making the request
+ * @param walletAccess - Array of wallet addresses the token has been granted access to
+ * @param address - The wallet address to check access for
+ * @returns true if the token can access the wallet
+ */
+export async function tokenCanAccessWallet(
+  tokenHash: string,
+  walletAccess: string[] | undefined,
+  address: string,
+  chain?: string
+): Promise<boolean> {
+  const normalized = normalizeAddress(address, chain);
+
+  // Check if wallet address is in the walletAccess grants
+  if (walletAccess && walletAccess.includes(normalized)) {
+    return true;
+  }
+  // Also check original address (for Solana addresses that may be stored as-is)
+  if (walletAccess && walletAccess.includes(address)) {
+    return true;
+  }
+
+  // Fall back to checking ownership
+  return tokenOwnsWallet(tokenHash, address);
+}