auramaxx 0.0.1

package/server/lib/dont-ask-again-policy.ts

@@ -0,0 +1,41 @@
+const DEFAULT_ON_ALLOWLIST = new Set([
+  'password',
+  'cvv',
+  'refresh_token',
+]);
+
+const HARD_DENYLIST = new Set([
+  'privatekey',
+  'private_key',
+  'seedphrase',
+  'seed_phrase',
+  'mnemonic',
+  'recovery_phrase',
+]);
+
+function norm(field: string): string {
+  return field.trim().toLowerCase().replace(/[^a-z0-9_]/g, '');
+}
+
+export interface DontAskAgainDecision {
+  defaultOn: boolean;
+  reason: 'ALLOWLIST_EXCLUDED_FIELD' | 'DENYLIST_SENSITIVE_FIELD' | 'MIXED_OR_UNKNOWN';
+}
+
+export function resolveDontAskAgainDefault(excludedFields: string[]): DontAskAgainDecision {
+  const normalized = excludedFields.map(norm).filter(Boolean);
+  if (!normalized.length) {
+    return { defaultOn: false, reason: 'MIXED_OR_UNKNOWN' };
+  }
+
+  if (normalized.some((f) => HARD_DENYLIST.has(f))) {
+    return { defaultOn: false, reason: 'DENYLIST_SENSITIVE_FIELD' };
+  }
+
+  const allAllowlisted = normalized.every((f) => DEFAULT_ON_ALLOWLIST.has(f));
+  if (allAllowlisted) {
+    return { defaultOn: true, reason: 'ALLOWLIST_EXCLUDED_FIELD' };
+  }
+
+  return { defaultOn: false, reason: 'MIXED_OR_UNKNOWN' };
+}

package/server/lib/e2e-agent/artifacts.ts

@@ -0,0 +1,36 @@
+import fs from 'fs';
+import path from 'path';
+import { RunFingerprint } from './contracts';
+
+export interface SummaryArtifact {
+  runId: string;
+  status: 'passed' | 'failed';
+  scenarioId: string;
+  runFingerprint: RunFingerprint;
+}
+
+export interface ReplayManifest {
+  runId: string;
+  scenarioId: string;
+  runFingerprint: RunFingerprint;
+  replayCommand: string;
+}
+
+export function writeArtifacts(baseDir: string, summary: SummaryArtifact): { summaryPath: string; manifestPath: string } {
+  fs.mkdirSync(baseDir, { recursive: true });
+
+  const summaryPath = path.join(baseDir, 'summary.json');
+  fs.writeFileSync(summaryPath, JSON.stringify(summary, null, 2));
+
+  const manifest: ReplayManifest = {
+    runId: summary.runId,
+    scenarioId: summary.scenarioId,
+    runFingerprint: summary.runFingerprint,
+    replayCommand: `npx tsx server/tests/e2e-agent/runner.ts replay --run ${summary.runId}`,
+  };
+
+  const manifestPath = path.join(baseDir, 'replay.manifest.json');
+  fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+
+  return { summaryPath, manifestPath };
+}

package/server/lib/e2e-agent/contracts.ts

@@ -0,0 +1,112 @@
+import { z } from 'zod';
+
+export const E2E_AGENT_ERROR_CODES = {
+  schemaAssertion: 'E_SCHEMA_ASSERTION',
+  egressPolicy: 'E_EGRESS_POLICY',
+  clockDrift: 'E_CLOCK_DRIFT',
+  budgetDuration: 'E_BUDGET_DURATION',
+  budgetSteps: 'E_BUDGET_STEPS',
+  budgetToolCalls: 'E_BUDGET_TOOL_CALLS',
+  budgetTokens: 'E_BUDGET_TOKENS',
+} as const;
+
+const assertionBaseSchema = z.object({
+  id: z.string().min(1),
+  type: z.enum(['ui', 'api', 'db']),
+  op: z.enum(['equals', 'contains', 'exists', 'not_exists', 'gt', 'gte', 'lt', 'lte']),
+});
+
+const uiAssertionSchema = assertionBaseSchema.extend({
+  type: z.literal('ui'),
+  selector: z.string().min(1),
+  expected: z.union([z.string(), z.number(), z.boolean()]).optional(),
+});
+
+const apiAssertionSchema = assertionBaseSchema.extend({
+  type: z.literal('api'),
+  endpoint: z.string().min(1),
+  path: z.string().min(1),
+  expected: z.union([z.string(), z.number(), z.boolean()]).optional(),
+});
+
+const dbAssertionSchema = assertionBaseSchema.extend({
+  type: z.literal('db'),
+  query: z.string().min(1),
+  expected: z.union([z.string(), z.number(), z.boolean()]).optional(),
+});
+
+export const assertionSchema = z.discriminatedUnion('type', [
+  uiAssertionSchema,
+  apiAssertionSchema,
+  dbAssertionSchema,
+]);
+
+export const budgetSchema = z.object({
+  maxDurationSec: z.number().int().positive(),
+  maxSteps: z.number().int().positive(),
+  maxToolCalls: z.number().int().positive(),
+  maxTokens: z.number().int().positive(),
+});
+
+export const scenarioSchema = z.object({
+  id: z.string().min(1),
+  title: z.string().min(1),
+  mode: z.enum(['agent-hybrid', 'scripted']),
+  clock: z.object({
+    baseTimeIso: z.string().datetime(),
+  }),
+  budget: budgetSchema.partial().optional(),
+  assertions: z.array(assertionSchema).min(1),
+});
+
+export type Assertion = z.infer<typeof assertionSchema>;
+export type Budget = z.infer<typeof budgetSchema>;
+export type Scenario = z.infer<typeof scenarioSchema>;
+
+export type Lane = 'pr-smoke' | 'nightly';
+
+export interface LaneBudgetCaps {
+  maxDurationSec: number;
+  maxSteps: number;
+  maxToolCalls: number;
+  maxTokens: number;
+}
+
+export const REPO_DEFAULT_BUDGET: Budget = {
+  maxDurationSec: 90,
+  maxSteps: 15,
+  maxToolCalls: 12,
+  maxTokens: 12000,
+};
+
+export const LANE_BUDGET_CAPS: Record<Lane, LaneBudgetCaps> = {
+  'pr-smoke': {
+    maxDurationSec: 120,
+    maxSteps: 20,
+    maxToolCalls: 16,
+    maxTokens: 16000,
+  },
+  nightly: {
+    maxDurationSec: 240,
+    maxSteps: 40,
+    maxToolCalls: 30,
+    maxTokens: 40000,
+  },
+};
+
+export interface ClockProbe {
+  runnerMs: number;
+  serverMs: number;
+  browserMs: number;
+  fixtureMs: number;
+}
+
+export interface RunFingerprint {
+  scenarioId: string;
+  lane: Lane;
+  mode: Scenario['mode'];
+  clockBaseTimeIso: string;
+  schemaVersion: string;
+  runnerVersion: string;
+  gitCommit: string;
+}

package/server/lib/e2e-agent/validation.ts

@@ -0,0 +1,135 @@
+import { parse as parseYaml } from 'yaml';
+import {
+  Budget,
+  ClockProbe,
+  E2E_AGENT_ERROR_CODES,
+  LANE_BUDGET_CAPS,
+  Lane,
+  REPO_DEFAULT_BUDGET,
+  Scenario,
+  scenarioSchema,
+} from './contracts';
+
+export class E2EAgentValidationError extends Error {
+  constructor(public readonly code: string, message: string) {
+    super(message);
+    this.name = 'E2EAgentValidationError';
+  }
+}
+
+export function parseScenarioDocument(input: string): unknown {
+  try {
+    return JSON.parse(input);
+  } catch {
+    return parseYaml(input);
+  }
+}
+
+export function validateScenario(raw: unknown): Scenario {
+  const parsed = scenarioSchema.safeParse(raw);
+  if (!parsed.success) {
+    throw new E2EAgentValidationError(
+      E2E_AGENT_ERROR_CODES.schemaAssertion,
+      parsed.error.issues.map((issue) => issue.message).join('; ')
+    );
+  }
+
+  return parsed.data;
+}
+
+export function applyBudgetPolicy(scenarioBudget: Partial<Budget> | undefined, lane: Lane): Budget {
+  const merged: Budget = {
+    ...REPO_DEFAULT_BUDGET,
+    ...(scenarioBudget ?? {}),
+  };
+
+  const laneCaps = LANE_BUDGET_CAPS[lane];
+
+  if (merged.maxDurationSec > laneCaps.maxDurationSec) {
+    throw new E2EAgentValidationError(
+      E2E_AGENT_ERROR_CODES.budgetDuration,
+      `maxDurationSec (${merged.maxDurationSec}) exceeds lane cap (${laneCaps.maxDurationSec})`
+    );
+  }
+
+  if (merged.maxSteps > laneCaps.maxSteps) {
+    throw new E2EAgentValidationError(
+      E2E_AGENT_ERROR_CODES.budgetSteps,
+      `maxSteps (${merged.maxSteps}) exceeds lane cap (${laneCaps.maxSteps})`
+    );
+  }
+
+  if (merged.maxToolCalls > laneCaps.maxToolCalls) {
+    throw new E2EAgentValidationError(
+      E2E_AGENT_ERROR_CODES.budgetToolCalls,
+      `maxToolCalls (${merged.maxToolCalls}) exceeds lane cap (${laneCaps.maxToolCalls})`
+    );
+  }
+
+  if (merged.maxTokens > laneCaps.maxTokens) {
+    throw new E2EAgentValidationError(
+      E2E_AGENT_ERROR_CODES.budgetTokens,
+      `maxTokens (${merged.maxTokens}) exceeds lane cap (${laneCaps.maxTokens})`
+    );
+  }
+
+  return merged;
+}
+
+export function enforceClockDrift(probe: ClockProbe): void {
+  const values = [probe.runnerMs, probe.serverMs, probe.browserMs, probe.fixtureMs];
+  const drift = Math.max(...values) - Math.min(...values);
+
+  if (drift > 50) {
+    throw new E2EAgentValidationError(
+      E2E_AGENT_ERROR_CODES.clockDrift,
+      `Clock drift ${drift}ms exceeded tolerance`
+    );
+  }
+}
+
+export function enforceEgressPolicy(hostname: string, allowedHosts: readonly string[]): void {
+  if (!allowedHosts.includes(hostname)) {
+    throw new E2EAgentValidationError(
+      E2E_AGENT_ERROR_CODES.egressPolicy,
+      `Blocked outbound host: ${hostname}`
+    );
+  }
+}
+
+export interface RuntimeUsage {
+  durationSec: number;
+  steps: number;
+  toolCalls: number;
+  tokens: number;
+}
+
+export function enforceRuntimeBudget(usage: RuntimeUsage, budget: Budget): void {
+  if (usage.durationSec > budget.maxDurationSec) {
+    throw new E2EAgentValidationError(
+      E2E_AGENT_ERROR_CODES.budgetDuration,
+      `durationSec ${usage.durationSec} exceeded ${budget.maxDurationSec}`
+    );
+  }
+
+  if (usage.steps > budget.maxSteps) {
+    throw new E2EAgentValidationError(
+      E2E_AGENT_ERROR_CODES.budgetSteps,
+      `steps ${usage.steps} exceeded ${budget.maxSteps}`
+    );
+  }
+
+  if (usage.toolCalls > budget.maxToolCalls) {
+    throw new E2EAgentValidationError(
+      E2E_AGENT_ERROR_CODES.budgetToolCalls,
+      `toolCalls ${usage.toolCalls} exceeded ${budget.maxToolCalls}`
+    );
+  }
+
+  if (usage.tokens > budget.maxTokens) {
+    throw new E2EAgentValidationError(
+      E2E_AGENT_ERROR_CODES.budgetTokens,
+      `tokens ${usage.tokens} exceeded ${budget.maxTokens}`
+    );
+  }
+}

package/server/lib/encrypt.ts

@@ -0,0 +1,114 @@
+import { randomBytes, scryptSync, createCipheriv, createDecipheriv, createHash } from 'crypto';
+import { EncryptedData } from '../types';
+
+const ALGORITHM = 'aes-256-gcm';
+const SCRYPT_COST = 131072; // 2^17
+const SCRYPT_BLOCK_SIZE = 8;
+const SCRYPT_PARALLELIZATION = 1;
+const SCRYPT_MAXMEM = 512 * 1024 * 1024; // 512 MiB
+const DKLEN = 32;
+const GCM_IV_BYTES = 12;
+
+function derivePasswordKey(password: string, salt: Buffer): Buffer {
+  return scryptSync(password, salt, DKLEN, {
+    cost: SCRYPT_COST,
+    blockSize: SCRYPT_BLOCK_SIZE,
+    parallelization: SCRYPT_PARALLELIZATION,
+    maxmem: SCRYPT_MAXMEM,
+  });
+}
+
+function deriveSeedKey(seed: string): Buffer {
+  return createHash('sha256').update(seed, 'utf8').digest();
+}
+
+export function encryptPrivateKey(privateKey: string, password: string): EncryptedData {
+  const salt = randomBytes(32);
+  const iv = randomBytes(GCM_IV_BYTES);
+  const derivedKey = derivePasswordKey(password, salt);
+
+  const cipher = createCipheriv(ALGORITHM, derivedKey, iv);
+  const ciphertext = Buffer.concat([
+    cipher.update(privateKey, 'utf8'),
+    cipher.final()
+  ]);
+  const mac = cipher.getAuthTag().toString('hex');
+
+  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 mac = Buffer.from(encrypted.mac, 'hex');
+
+  const derivedKey = derivePasswordKey(password, salt);
+
+  const decipher = createDecipheriv(ALGORITHM, derivedKey, iv);
+  decipher.setAuthTag(mac);
+  let decrypted: Buffer;
+  try {
+    decrypted = Buffer.concat([
+      decipher.update(ciphertext),
+      decipher.final()
+    ]);
+  } catch {
+    throw new Error('Invalid password or corrupted data');
+  }
+
+  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(GCM_IV_BYTES);
+  // Use SHA-256 of seed as key (mnemonic has enough entropy, no need for slow scrypt)
+  const derivedKey = deriveSeedKey(seed);
+
+  const cipher = createCipheriv(ALGORITHM, derivedKey, iv);
+  const ciphertext = Buffer.concat([
+    cipher.update(data, 'utf8'),
+    cipher.final()
+  ]);
+  const mac = cipher.getAuthTag().toString('hex');
+
+  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 mac = Buffer.from(encrypted.mac, 'hex');
+  const derivedKey = deriveSeedKey(seed);
+
+  const decipher = createDecipheriv(ALGORITHM, derivedKey, iv);
+  decipher.setAuthTag(mac);
+  let decrypted: Buffer;
+  try {
+    decrypted = Buffer.concat([
+      decipher.update(ciphertext),
+      decipher.final()
+    ]);
+  } catch {
+    throw new Error('Invalid seed or corrupted data');
+  }
+
+  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,217 @@
+/**
+ * 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',
+  SECRET_ACCESSED: 'secret: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'
+      | 'duplicated';
+    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),
+
+  secretAccessed: (data: {
+    credentialId: string;
+    credentialName: string;
+    vaultId: string;
+    surface: 'inject_secret' | 'get_secret';
+    envVar?: string;
+    agentId?: string;
+    tokenHash?: string;
+  }) => emitWalletEvent(WALLET_EVENTS.SECRET_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),
+};