auramaxx 1.0.0-alpha.4

package/server/lib/passkey-credential.ts

@@ -0,0 +1,360 @@
+/**
+ * Passkey Credential Operations — Software WebAuthn Authenticator
+ * ===============================================================
+ *
+ * Generates ECDSA P-256 keypairs, builds WebAuthn attestation/assertion objects,
+ * and stores passkey credentials in the encrypted vault.
+ */
+
+import crypto from 'crypto';
+import { encode as cborEncode } from 'cbor-x';
+import {
+  createCredential,
+  listCredentials,
+  getCredential,
+  readCredentialSecrets,
+  updateCredential,
+} from './credentials';
+import { CredentialField } from '../types';
+
+// Our software authenticator AAGUID (random, unique to Aura)
+const AURA_AAGUID = Buffer.from('a0a1a2a3a4a5a6a7a8a9aaabacadaeaf', 'hex');
+
+const PASSKEY_CHALLENGE_TTL_MS = 120_000;
+const usedChallenges = new Map<string, number>();
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+export class PasskeyCredentialValidationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'PasskeyCredentialValidationError';
+  }
+}
+
+function base64urlEncode(buf: Buffer | Uint8Array): string {
+  return Buffer.from(buf).toString('base64url');
+}
+
+function base64urlDecode(str: string): Buffer {
+  return Buffer.from(str, 'base64url');
+}
+
+function sha256(data: Buffer | string): Buffer {
+  return crypto.createHash('sha256').update(data).digest();
+}
+
+function cleanupUsedChallenges(now = Date.now()): void {
+  for (const [challenge, expiresAt] of usedChallenges.entries()) {
+    if (expiresAt <= now) {
+      usedChallenges.delete(challenge);
+    }
+  }
+}
+
+function consumeFreshChallenge(challenge: string): void {
+  const now = Date.now();
+  cleanupUsedChallenges(now);
+
+  const key = challenge.trim();
+  if (!key) {
+    throw new PasskeyCredentialValidationError('challenge is required');
+  }
+
+  if (usedChallenges.has(key)) {
+    throw new PasskeyCredentialValidationError('challenge replay detected');
+  }
+
+  usedChallenges.set(key, now + PASSKEY_CHALLENGE_TTL_MS);
+}
+
+export function _resetPasskeyCredentialChallengeStoreForTests(): void {
+  usedChallenges.clear();
+}
+
+function validateOriginPolicy(origin: string, rpId: string): void {
+  let parsed: URL;
+  try {
+    parsed = new URL(origin);
+  } catch {
+    throw new PasskeyCredentialValidationError('clientDataJSON.origin must be a valid URL');
+  }
+
+  const host = parsed.hostname.toLowerCase();
+  const normalizedRpId = rpId.toLowerCase();
+  const isRpMatch = host === normalizedRpId || host.endsWith(`.${normalizedRpId}`);
+  if (!isRpMatch) {
+    throw new PasskeyCredentialValidationError('clientDataJSON.origin does not match rpId');
+  }
+
+  const isLocalhost = host === 'localhost' || host.endsWith('.localhost');
+  const allowedHttp = parsed.protocol === 'http:' && isLocalhost;
+  if (parsed.protocol !== 'https:' && !allowedHttp) {
+    throw new PasskeyCredentialValidationError('clientDataJSON.origin must be https (except localhost)');
+  }
+}
+
+function parseAndValidateClientDataJSON(params: {
+  clientDataJSON: string;
+  expectedType: 'webauthn.create' | 'webauthn.get';
+  expectedChallenge: string;
+  rpId: string;
+  expectedOrigin?: string;
+}): { challenge: string; origin: string } {
+  let parsed: Record<string, unknown>;
+
+  try {
+    const raw = base64urlDecode(params.clientDataJSON).toString('utf8');
+    parsed = JSON.parse(raw) as Record<string, unknown>;
+  } catch {
+    throw new PasskeyCredentialValidationError('clientDataJSON must be valid base64url-encoded JSON');
+  }
+
+  const type = parsed.type;
+  const challenge = parsed.challenge;
+  const origin = parsed.origin;
+
+  if (type !== params.expectedType) {
+    throw new PasskeyCredentialValidationError(`clientDataJSON.type must be ${params.expectedType}`);
+  }
+
+  if (typeof challenge !== 'string' || challenge !== params.expectedChallenge) {
+    throw new PasskeyCredentialValidationError('clientDataJSON.challenge mismatch');
+  }
+
+  if (typeof origin !== 'string' || !origin.trim()) {
+    throw new PasskeyCredentialValidationError('clientDataJSON.origin is required');
+  }
+
+  validateOriginPolicy(origin, params.rpId);
+
+  if (params.expectedOrigin && origin !== params.expectedOrigin) {
+    throw new PasskeyCredentialValidationError('clientDataJSON.origin mismatch');
+  }
+
+  return { challenge, origin };
+}
+
+/**
+ * Encode an EC public key in COSE_Key format (ECDSA P-256).
+ * See RFC 8152 Section 13.1.1
+ */
+function encodeCosePublicKey(publicKeyDer: Buffer): Buffer {
+  const raw = crypto.createPublicKey({ key: publicKeyDer, format: 'der', type: 'spki' })
+    .export({ format: 'jwk' });
+
+  const x = base64urlDecode(raw.x!);
+  const y = base64urlDecode(raw.y!);
+
+  const coseKey = new Map<number, number | Buffer>();
+  coseKey.set(1, 2);      // kty: EC2
+  coseKey.set(3, -7);     // alg: ES256
+  coseKey.set(-1, 1);     // crv: P-256
+  coseKey.set(-2, x);     // x coordinate
+  coseKey.set(-3, y);     // y coordinate
+
+  return Buffer.from(cborEncode(coseKey));
+}
+
+// ---------------------------------------------------------------------------
+// Registration (navigator.credentials.create)
+// ---------------------------------------------------------------------------
+
+export interface PasskeyRegisterOptions {
+  vaultId: string;
+  rpId: string;
+  rpName?: string;
+  userName?: string;
+  displayName?: string;
+  userHandle: string; // base64url
+  challenge: string;  // base64url — from clientDataJSON
+  origin: string;
+  clientDataJSON: string; // base64url — raw from browser
+}
+
+export interface PasskeyRegisterResult {
+  credentialId: string;    // base64url
+  attestationObject: string; // base64url
+  clientDataJSON: string;    // base64url (pass-through)
+  publicKey: string;         // base64url (SPKI DER)
+  publicKeyCose: string;     // base64url (COSE)
+  transports: string[];
+  auraCredentialId: string;  // internal cred-xxx id
+}
+
+export function registerPasskey(opts: PasskeyRegisterOptions): PasskeyRegisterResult {
+  parseAndValidateClientDataJSON({
+    clientDataJSON: opts.clientDataJSON,
+    expectedType: 'webauthn.create',
+    expectedChallenge: opts.challenge,
+    rpId: opts.rpId,
+    expectedOrigin: opts.origin,
+  });
+  consumeFreshChallenge(opts.challenge);
+
+  const { publicKey, privateKey } = crypto.generateKeyPairSync('ec', {
+    namedCurve: 'prime256v1',
+    publicKeyEncoding: { type: 'spki', format: 'der' },
+    privateKeyEncoding: { type: 'pkcs8', format: 'der' },
+  });
+
+  const credentialIdBuf = crypto.randomBytes(32);
+  const credentialId = base64urlEncode(credentialIdBuf);
+
+  const cosePublicKey = encodeCosePublicKey(publicKey as Buffer);
+
+  const rpIdHash = sha256(opts.rpId);
+  const flags = Buffer.from([0x45]); // UP + UV + AT
+  const signCount = Buffer.alloc(4);
+
+  const credIdLenBuf = Buffer.alloc(2);
+  credIdLenBuf.writeUInt16BE(credentialIdBuf.length);
+
+  const authData = Buffer.concat([
+    rpIdHash,
+    flags,
+    signCount,
+    AURA_AAGUID,
+    credIdLenBuf,
+    credentialIdBuf,
+    cosePublicKey,
+  ]);
+
+  const attestationObject = cborEncode({
+    fmt: 'none',
+    attStmt: {},
+    authData,
+  });
+
+  const sensitiveFields: CredentialField[] = [
+    { key: 'privateKey', value: base64urlEncode(privateKey as Buffer), type: 'secret', sensitive: true },
+  ];
+
+  const meta: Record<string, unknown> = {
+    rpId: opts.rpId,
+    rpName: opts.rpName || opts.rpId,
+    credentialId,
+    publicKey: base64urlEncode(publicKey as Buffer),
+    publicKeyCose: base64urlEncode(cosePublicKey),
+    userHandle: opts.userHandle,
+    userName: opts.userName || '',
+    displayName: opts.displayName || '',
+    signCount: 0,
+    transports: ['internal'],
+    discoverable: true,
+  };
+
+  const name = `${opts.rpId} — ${opts.displayName || opts.userName || 'passkey'}`;
+  const cred = createCredential(opts.vaultId, 'passkey', name, meta, sensitiveFields);
+
+  return {
+    credentialId,
+    attestationObject: base64urlEncode(Buffer.from(attestationObject)),
+    clientDataJSON: opts.clientDataJSON,
+    publicKey: base64urlEncode(publicKey as Buffer),
+    publicKeyCose: base64urlEncode(cosePublicKey),
+    transports: ['internal'],
+    auraCredentialId: cred.id,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Authentication (navigator.credentials.get)
+// ---------------------------------------------------------------------------
+
+export interface PasskeyAuthOptions {
+  auraCredentialId: string; // internal cred-xxx id
+  rpId: string;
+  challenge: string;
+  origin?: string;
+  clientDataJSON: string;   // base64url — raw from browser
+}
+
+export interface PasskeyAuthResult {
+  credentialId: string;       // base64url
+  authenticatorData: string;  // base64url
+  signature: string;          // base64url
+  userHandle: string;         // base64url
+}
+
+export function authenticatePasskey(opts: PasskeyAuthOptions): PasskeyAuthResult {
+  parseAndValidateClientDataJSON({
+    clientDataJSON: opts.clientDataJSON,
+    expectedType: 'webauthn.get',
+    expectedChallenge: opts.challenge,
+    rpId: opts.rpId,
+    expectedOrigin: opts.origin,
+  });
+  consumeFreshChallenge(opts.challenge);
+
+  const cred = getCredential(opts.auraCredentialId);
+  if (!cred || cred.type !== 'passkey') {
+    throw new Error('Passkey credential not found');
+  }
+
+  if (cred.meta.rpId !== opts.rpId) {
+    throw new Error('rpId mismatch');
+  }
+
+  const secrets = readCredentialSecrets(opts.auraCredentialId);
+  const privateKeyField = secrets.find(f => f.key === 'privateKey');
+  if (!privateKeyField) {
+    throw new Error('Private key not found in credential');
+  }
+
+  const privateKeyDer = base64urlDecode(privateKeyField.value);
+  const privateKey = crypto.createPrivateKey({ key: privateKeyDer, format: 'der', type: 'pkcs8' });
+
+  const currentCount = (cred.meta.signCount as number) || 0;
+  const newCount = currentCount + 1;
+
+  const rpIdHash = sha256(opts.rpId);
+  const flags = Buffer.from([0x05]); // UP + UV
+  const signCountBuf = Buffer.alloc(4);
+  signCountBuf.writeUInt32BE(newCount);
+
+  const authenticatorData = Buffer.concat([rpIdHash, flags, signCountBuf]);
+
+  const clientDataHash = sha256(base64urlDecode(opts.clientDataJSON));
+  const signedData = Buffer.concat([authenticatorData, clientDataHash]);
+  const signature = crypto.sign('sha256', signedData, privateKey);
+
+  updateCredential(opts.auraCredentialId, {
+    meta: { ...cred.meta, signCount: newCount },
+  });
+
+  return {
+    credentialId: cred.meta.credentialId as string,
+    authenticatorData: base64urlEncode(authenticatorData),
+    signature: base64urlEncode(signature),
+    userHandle: (cred.meta.userHandle as string) || '',
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Match — find passkeys for an rpId
+// ---------------------------------------------------------------------------
+
+export interface PasskeyMatch {
+  auraCredentialId: string;
+  credentialId: string;
+  rpId: string;
+  userName: string;
+  displayName: string;
+}
+
+export function matchPasskeys(rpId: string, vaultId?: string): PasskeyMatch[] {
+  const creds = listCredentials({ type: 'passkey', vaultId });
+  return creds
+    .filter(c => c.meta.rpId === rpId)
+    .map(c => ({
+      auraCredentialId: c.id,
+      credentialId: c.meta.credentialId as string,
+      rpId: c.meta.rpId as string,
+      userName: (c.meta.userName as string) || '',
+      displayName: (c.meta.displayName as string) || '',
+    }))
+    .sort((a, b) => a.auraCredentialId.localeCompare(b.auraCredentialId));
+}

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,248 @@
+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[]> = {
+  '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)) {
+      res.status(403).json({
+        error: 'Insufficient permissions',
+        required: permissions,
+        have: req.auth.token.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)) {
+    res.status(403).json({ error: 'Admin access required' });
+    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';
+}

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',
+          },
+        },
+      }
+    : {}),
+});