auramaxx 0.0.1

package/server/lib/passkey.ts

@@ -0,0 +1,68 @@
+/**
+ * Passkey challenge store and helpers for WebAuthn biometric unlock.
+ * Challenges are in-memory, single-use, with 60s TTL.
+ */
+
+const CHALLENGE_TTL_MS = 60_000;
+
+interface PendingChallenge {
+  type: 'register' | 'authenticate';
+  expiresAt: number;
+}
+
+const challenges = new Map<string, PendingChallenge>();
+
+// Cleanup expired challenges periodically
+let cleanupTimer: ReturnType<typeof setInterval> | null = null;
+
+function ensureCleanup() {
+  if (cleanupTimer) return;
+  cleanupTimer = setInterval(() => {
+    const now = Date.now();
+    for (const [key, val] of challenges) {
+      if (val.expiresAt <= now) challenges.delete(key);
+    }
+    if (challenges.size === 0 && cleanupTimer) {
+      clearInterval(cleanupTimer);
+      cleanupTimer = null;
+    }
+  }, 30_000);
+  // Don't keep process alive for cleanup
+  if (cleanupTimer && typeof cleanupTimer === 'object' && 'unref' in cleanupTimer) {
+    cleanupTimer.unref();
+  }
+}
+
+/**
+ * Store a challenge for later verification.
+ */
+export function storeChallenge(challenge: string, type: 'register' | 'authenticate'): void {
+  challenges.set(challenge, { type, expiresAt: Date.now() + CHALLENGE_TTL_MS });
+  ensureCleanup();
+}
+
+/**
+ * Consume a challenge (single-use). Returns true if valid and not expired.
+ */
+export function consumeChallenge(challenge: string, type: 'register' | 'authenticate'): boolean {
+  const entry = challenges.get(challenge);
+  if (!entry) return false;
+  challenges.delete(challenge);
+  if (entry.type !== type) return false;
+  if (entry.expiresAt <= Date.now()) return false;
+  return true;
+}
+
+/**
+ * Convert base64url string to Uint8Array.
+ */
+export function base64urlToUint8Array(base64url: string): Uint8Array {
+  return Buffer.from(base64url, 'base64url');
+}
+
+/**
+ * Convert Uint8Array (or Buffer) to base64url string.
+ */
+export function uint8ArrayToBase64url(bytes: Uint8Array | Buffer): string {
+  return Buffer.from(bytes).toString('base64url');
+}

package/server/lib/permissions.ts

@@ -0,0 +1,299 @@
+import { Request, Response, NextFunction } from 'express';
+import { AgentTokenPayload } from '../types';
+
+/**
+ * PERMISSION SYSTEM
+ * =================
+ *
+ * Permission strings control access to specific routes and operations.
+ * Admin tokens bypass all permission checks.
+ */
+
+// All valid permission strings
+export type Permission =
+  // Wallet operations
+  | 'wallet:list'           // List/view wallets
+  | 'wallet:create:hot'     // Create hot wallets
+  | 'wallet:create:temp'    // Create temp wallets
+  | 'wallet:rename'         // Rename wallets
+  | 'wallet:export'         // Export private keys
+  | 'wallet:tx:add'         // Manually add transactions to wallet history
+  | 'wallet:asset:add'      // Add assets to track for a wallet
+  | 'wallet:asset:remove'   // Remove tracked assets from a wallet
+
+  // Transaction operations
+  | 'send:hot'              // Send from hot wallets
+  | 'send:temp'             // Send from temp wallets
+  | 'swap'                  // Execute swaps
+  | 'fund'                  // Cold→hot transfers
+  | 'launch'                // Execute token launches
+
+  // API Key operations
+  | 'apikey:get'            // Read API keys
+  | 'apikey:set'            // Create/update/delete API keys
+
+  // Workspace/UI operations
+  | 'workspace:modify'      // Add/update/remove apps, modify workspaces
+
+  // Strategy operations
+  | 'strategy:read'         // View strategies and their state
+  | 'strategy:manage'       // Enable/disable strategies, update config
+
+  // App operations
+  | 'app:storage'        // Read/write own app's storage via Express API
+  | 'app:storage:all'    // Read/write ANY app's storage via Express API
+  | 'app:accesskey'      // Read API keys from app storage
+
+  // Action operations
+  | 'action:create'          // Create human action requests (propose actions for approval)
+  | 'action:read'            // Read/list pending actions
+  | 'action:resolve'         // Approve or reject pending actions
+
+  // Adapter operations
+  | 'adapter:manage'         // Configure and restart approval adapters (Telegram, webhooks)
+
+  // Address book & bookmark operations
+  | 'addressbook:write'      // Create/update/delete address labels
+  | 'bookmark:write'         // Create/delete token bookmarks
+
+  // Credential vault operations
+  | 'secret:read'            // Read credentials from the vault
+  | 'secret:write'           // Create/update/delete credentials in the vault
+  | 'totp:read'              // Generate TOTP codes from credential secrets
+
+  // Compound permissions (expand to multiple permissions)
+  | 'trade:all'             // All trading permissions + apikey:get + strategy:read
+  | 'wallet:write'          // All wallet write operations
+  | 'extension:*'           // Browser extension permissions
+
+  // Admin (UI only)
+  | 'admin:*';              // All permissions, bypass limits
+
+/**
+ * Compound permission mappings
+ * These permissions expand to multiple underlying permissions
+ */
+const COMPOUND_PERMISSIONS: Record<string, Permission[]> = {
+  'admin:*': [
+    'swap', 'send:hot', 'send:temp', 'fund', 'launch',
+    'wallet:create:hot', 'wallet:create:temp', 'wallet:export', 'wallet:list', 'wallet:rename',
+    'wallet:tx:add', 'wallet:asset:add', 'wallet:asset:remove',
+    'secret:read', 'secret:write', 'totp:read',
+    'action:create', 'action:read', 'action:resolve',
+    'apikey:get', 'apikey:set',
+    'workspace:modify',
+    'strategy:read', 'strategy:manage',
+    'app:storage', 'app:storage:all', 'app:accesskey',
+    'adapter:manage',
+    'addressbook:write', 'bookmark:write',
+  ],
+  'trade:all': [
+    'wallet:list',
+    'wallet:create:hot',
+    'wallet:create:temp',
+    'send:hot',
+    'send:temp',
+    'swap',
+    'fund',
+    'launch',
+    'apikey:get',
+    'strategy:read'
+  ],
+  'extension:*': [
+    'wallet:list',
+    'secret:read',
+    'action:read',
+    'action:resolve'
+  ],
+  'wallet:write': [
+    'wallet:create:hot',
+    'wallet:create:temp',
+    'wallet:rename',
+    'wallet:tx:add',
+    'wallet:asset:add',
+    'wallet:asset:remove'
+  ]
+};
+
+/**
+ * Expand and normalize permissions array
+ * - Expands compound permissions (e.g., 'trade:all' → multiple permissions)
+ * - Deduplicates the result
+ */
+export function expandPermissions(permissions: string[]): Permission[] {
+  const expanded = new Set<Permission>();
+
+  for (const perm of permissions) {
+    // Check if this is a compound permission
+    if (COMPOUND_PERMISSIONS[perm]) {
+      for (const subPerm of COMPOUND_PERMISSIONS[perm]) {
+        expanded.add(subPerm);
+      }
+    }
+    // Always add the original permission too
+    expanded.add(perm as Permission);
+  }
+
+  return Array.from(expanded);
+}
+
+/**
+ * Get the list of compound permissions and what they expand to
+ */
+export function getCompoundPermissions(): Record<string, Permission[]> {
+  return { ...COMPOUND_PERMISSIONS };
+}
+
+/**
+ * Check if token has ANY of the required permissions
+ * Automatically expands compound permissions before checking
+ */
+export function hasAnyPermission(
+  tokenPermissions: string[],
+  requiredPermissions: string[]
+): boolean {
+  // Admin bypass
+  if (tokenPermissions.includes('admin:*')) {
+    return true;
+  }
+
+  // Expand compound permissions
+  const expanded = expandPermissions(tokenPermissions);
+
+  for (const required of requiredPermissions) {
+    if (expanded.includes(required as Permission)) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Check if token has ALL of the required permissions
+ * Automatically expands compound permissions before checking
+ */
+export function hasAllPermissions(
+  tokenPermissions: string[],
+  requiredPermissions: string[]
+): boolean {
+  // Admin bypass
+  if (tokenPermissions.includes('admin:*')) {
+    return true;
+  }
+
+  // Expand compound permissions
+  const expanded = expandPermissions(tokenPermissions);
+
+  for (const required of requiredPermissions) {
+    if (!expanded.includes(required as Permission)) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+/**
+ * Check if a token is an admin token (has admin:* permission)
+ */
+export function isAdmin(auth: { token: { permissions: string[] } }): boolean {
+  return auth.token.permissions.includes('admin:*');
+}
+
+/**
+ * Middleware factory that requires specific permissions
+ *
+ * Usage:
+ *   router.post('/create', requireWalletAuth, requirePermission('wallet:create:hot'), handler)
+ *   router.post('/send', requireWalletAuth, requirePermission('send:hot', 'send:temp'), handler)
+ */
+export function requirePermission(...permissions: string[]) {
+  return (req: Request, res: Response, next: NextFunction): void => {
+    if (!req.auth) {
+      res.status(401).json({ error: 'Authentication required' });
+      return;
+    }
+
+    // Check if token has any of the required permissions (admin:* bypasses via hasAnyPermission)
+    if (!hasAnyPermission(req.auth.token.permissions, permissions)) {
+      const dashboardBase = `http://localhost:${process.env.DASHBOARD_PORT || '4747'}`;
+      res.status(403).json({
+        error: 'Insufficient permissions',
+        required: permissions,
+        have: req.auth.token.permissions,
+        escalation: {
+          via: 'auth',
+          permissions,
+          dashboard: dashboardBase,
+          note: 'Request a new token via POST /auth with a profile that includes the required permissions.',
+        },
+      });
+      return;
+    }
+
+    next();
+  };
+}
+
+/**
+ * Middleware that requires admin permission specifically
+ */
+export function requireAdmin(req: Request, res: Response, next: NextFunction): void {
+  if (!req.auth) {
+    res.status(401).json({ error: 'Authentication required' });
+    return;
+  }
+
+  if (!isAdmin(req.auth)) {
+    const dashboardBase = `http://localhost:${process.env.DASHBOARD_PORT || '4747'}`;
+    res.status(403).json({
+      error: 'Admin access required',
+      required: ['admin:*'],
+      have: req.auth.token.permissions,
+      escalation: {
+        via: 'auth',
+        permissions: ['admin:*'],
+        dashboard: dashboardBase,
+        note: 'Request a new token via POST /auth with profile "admin".',
+      },
+    });
+    return;
+  }
+
+  next();
+}
+
+/**
+ * Get the permission required for a wallet tier operation
+ */
+export function getWalletCreatePermission(tier: 'hot' | 'temp'): Permission {
+  return tier === 'hot' ? 'wallet:create:hot' : 'wallet:create:temp';
+}
+
+/**
+ * Get the permission required for sending from a wallet tier
+ */
+export function getSendPermission(tier: 'hot' | 'temp'): Permission {
+  return tier === 'hot' ? 'send:hot' : 'send:temp';
+}
+
+/**
+ * Build a 403 response body with escalation info.
+ * Use this instead of bare `{ error: '...' }` for permission denials
+ * so that agents (MCP, CLI, SDK) know how to self-escalate.
+ */
+export function buildPermissionDenied(error: string, required: string[], have?: string[]): Record<string, unknown> {
+  const dashboardBase = `http://localhost:${process.env.DASHBOARD_PORT || '4747'}`;
+  return {
+    error,
+    required,
+    ...(have ? { have } : {}),
+    escalation: {
+      via: 'auth',
+      permissions: required,
+      dashboard: dashboardBase,
+      note: 'Request a new token via POST /auth with a profile that includes the required permissions.',
+    },
+  };
+}

package/server/lib/pino.ts

@@ -0,0 +1,24 @@
+/**
+ * Shared Pino logger instance for the Express server (port 4242)
+ */
+
+import pino from 'pino';
+
+const isDev = process.env.NODE_ENV !== 'production';
+const isTest = process.env.NODE_ENV === 'test' || process.env.VITEST === 'true';
+
+export const log = pino({
+  level: isTest ? 'silent' : (process.env.LOG_LEVEL || 'debug'),
+  ...(isDev && !isTest
+    ? {
+        transport: {
+          target: 'pino-pretty',
+          options: {
+            colorize: true,
+            translateTime: 'HH:MM:ss.l',
+            ignore: 'pid,hostname',
+          },
+        },
+      }
+    : {}),
+});

package/server/lib/policy-preview.ts

@@ -0,0 +1,138 @@
+import type { ResolveProfileInput, ResolvedProfilePolicy } from './agent-profiles';
+
+export type DenyCode =
+  | 'DENY_PERMISSION_MISSING'
+  | 'DENY_CREDENTIAL_READ_SCOPE'
+  | 'DENY_CREDENTIAL_WRITE_SCOPE'
+  | 'DENY_EXCLUDED_FIELD'
+  | 'DENY_MAX_READS_EXCEEDED'
+  | 'DENY_RATE_LIMIT';
+
+export interface PolicyPreviewV1 {
+  version: 'v1';
+  request: {
+    profile: string;
+    profileVersion: string;
+    overrides?: ResolveProfileInput['overrides'];
+  };
+  effectivePolicy: {
+    permissions: string[];
+    credentialAccess: {
+      read: string[];
+      write: string[];
+      excludeFields: string[];
+      maxReads: number | null;
+    };
+    ttlSeconds: number;
+    maxReads: number | null;
+    rateBudget: {
+      state: 'none' | 'inherited' | 'explicit';
+      requests: number | null;
+      windowSeconds: number | null;
+      source: 'none' | 'profile' | 'override';
+    };
+  };
+  effectivePolicyHash: string;
+  overrideDelta: string[];
+  warnings: string[];
+  denyExamples: Array<{ code: DenyCode; message: string }>;
+}
+
+export function canonicalizeEffectivePolicy(policy: ResolvedProfilePolicy): PolicyPreviewV1['effectivePolicy'] {
+  return {
+    permissions: Array.from(new Set(policy.permissions)).sort(),
+    credentialAccess: {
+      read: Array.from(new Set(policy.credentialAccess.read || [])).sort(),
+      write: Array.from(new Set(policy.credentialAccess.write || [])).sort(),
+      excludeFields: Array.from(new Set(policy.credentialAccess.excludeFields || [])).sort(),
+      maxReads: typeof policy.credentialAccess.maxReads === 'number' ? policy.credentialAccess.maxReads : null,
+    },
+    ttlSeconds: policy.ttlSeconds,
+    maxReads: typeof policy.credentialAccess.maxReads === 'number' ? policy.credentialAccess.maxReads : null,
+    rateBudget: {
+      state: 'none',
+      requests: null,
+      windowSeconds: null,
+      source: 'none',
+    },
+  };
+}
+
+const DENY_ORDER: DenyCode[] = [
+  'DENY_PERMISSION_MISSING',
+  'DENY_CREDENTIAL_READ_SCOPE',
+  'DENY_CREDENTIAL_WRITE_SCOPE',
+  'DENY_EXCLUDED_FIELD',
+  'DENY_MAX_READS_EXCEEDED',
+  'DENY_RATE_LIMIT',
+];
+
+const DENY_MESSAGES: Record<DenyCode, string> = {
+  DENY_PERMISSION_MISSING: 'Operation denied: required permission is not granted by this policy.',
+  DENY_CREDENTIAL_READ_SCOPE: 'Credential read denied: target credential is outside allowed read scopes.',
+  DENY_CREDENTIAL_WRITE_SCOPE: 'Credential write denied: target credential is outside allowed write scopes.',
+  DENY_EXCLUDED_FIELD: 'Field access denied: requested field is explicitly excluded by policy.',
+  DENY_MAX_READS_EXCEEDED: 'Read denied: token maxReads budget would be exceeded.',
+  DENY_RATE_LIMIT: 'Rate limit denied: request would exceed configured token rate budget.',
+};
+
+export function buildDenyExamples(): Array<{ code: DenyCode; message: string }> {
+  return DENY_ORDER.map((code) => ({ code, message: DENY_MESSAGES[code] }));
+}
+
+export function buildPolicyPreviewV1(
+  input: ResolveProfileInput,
+  resolved: ResolvedProfilePolicy,
+): PolicyPreviewV1 {
+  const profileVersion = input.profileVersion || resolved.profile.version;
+  return {
+    version: 'v1',
+    request: {
+      profile: input.profileId,
+      profileVersion,
+      ...(input.overrides ? { overrides: input.overrides } : {}),
+    },
+    effectivePolicy: canonicalizeEffectivePolicy(resolved),
+    effectivePolicyHash: resolved.effectivePolicyHash,
+    overrideDelta: [...resolved.overrideDelta],
+    warnings: [...resolved.warnings],
+    denyExamples: buildDenyExamples(),
+  };
+}
+
+export interface PreviewErrorV1 {
+  version: 'v1';
+  code:
+    | 'ERR_UNAUTHORIZED'
+    | 'ERR_FORBIDDEN'
+    | 'ERR_PROFILE_NOT_FOUND'
+    | 'ERR_PROFILE_VERSION_UNSUPPORTED'
+    | 'ERR_OVERRIDE_INVALID'
+    | 'ERR_RESOLUTION_FAILED';
+  error: string;
+}
+
+export function mapPreviewError(code: string): { status: number; error: PreviewErrorV1 } {
+  if (code === 'AGENT_PROFILE_NOT_FOUND') {
+    return {
+      status: 404,
+      error: { version: 'v1', code: 'ERR_PROFILE_NOT_FOUND', error: 'Requested profile does not exist.' },
+    };
+  }
+  if (code === 'AGENT_PROFILE_VERSION_UNSUPPORTED') {
+    return {
+      status: 409,
+      error: { version: 'v1', code: 'ERR_PROFILE_VERSION_UNSUPPORTED', error: 'Requested profile version is unsupported.' },
+    };
+  }
+  if (code.startsWith('AGENT_PROFILE_')) {
+    return {
+      status: 422,
+      error: { version: 'v1', code: 'ERR_OVERRIDE_INVALID', error: 'Profile overrides are invalid for the selected profile.' },
+    };
+  }
+  return {
+    status: 500,
+    error: { version: 'v1', code: 'ERR_RESOLUTION_FAILED', error: 'Failed to resolve policy preview.' },
+  };
+}