palaryn 0.1.0 → 0.3.2

package/src/server/app.ts

@@ -0,0 +1,985 @@
+import express from 'express';
+import path from 'path';
+import fs from 'fs';
+import cors from 'cors';
+import helmet from 'helmet';
+import cookieParser from 'cookie-parser';
+import { Gateway } from './gateway';
+import { streamProxy } from './stream-proxy';
+import { NoopExecutor } from '../executor/noop-executor';
+import { createForwardProxy, ForwardProxyServer } from '../proxy';
+import { GatewayConfig } from '../types/config';
+import { createAuthMiddleware, createRBACMiddleware } from '../middleware/auth';
+import { createSessionMiddleware, SessionMiddlewareDeps } from '../middleware/session';
+import { normalizeToolCall, validateToolCall } from '../middleware/validate';
+import { GatewayMetrics } from '../metrics';
+import { GatewayTracer } from '../tracing';
+import { createAdminRouter } from '../admin';
+import { sendError, ErrorCode } from './errors';
+import { createAuthRouter, AuthRouteDeps } from '../auth/routes';
+import { createSaaSRouter, SaaSRouteDeps } from '../saas/routes';
+import { createMCPHttpHandler } from '../mcp/http-transport';
+import { mcpAuthRouter } from '@modelcontextprotocol/sdk/server/auth/router.js';
+import { requireBearerAuth } from '@modelcontextprotocol/sdk/server/auth/middleware/bearerAuth.js';
+import { getOAuthProtectedResourceMetadataUrl } from '@modelcontextprotocol/sdk/server/auth/router.js';
+import { OAuthClientsStore, AuthCodeStore, OAuthTokenStore } from '../mcp/oauth-stores';
+import { PostgresOAuthClientsStore, PostgresOAuthTokenStore } from '../mcp/oauth-postgres-stores';
+import { PalarynOAuthProvider } from '../mcp/oauth-provider';
+import { HybridTokenVerifier } from '../mcp/auth-verifier';
+import { SESSION_COOKIE_NAME } from '../auth/session';
+import { ToolCall } from '../types/tool-call';
+import {
+  UserStore, OAuthAccountStore, WorkspaceStore,
+  WorkspaceMemberStore, SessionStore, UserApiKeyStore,
+  SubscriptionStore, PolicyStore, RateLimitConfigStore, BudgetConfigStore,
+} from '../storage/interfaces';
+import {
+  InMemoryUserStore, InMemoryOAuthAccountStore, InMemoryWorkspaceStore,
+  InMemoryWorkspaceMemberStore, InMemorySessionStore, InMemoryUserApiKeyStore,
+  InMemorySubscriptionStore,
+} from '../storage/memory';
+import { StripeClient, WebhookHandler, createWebhookRouter, createBillingRouter, PlanEnforcer } from '../billing';
+import { createPlanEnforcerMiddleware } from '../billing/plan-enforcer';
+import { FilePersistedStores } from '../storage/file-persistence';
+import { hashPassword } from '../auth/password';
+import { log as devLog } from './logger';
+
+const MAX_TRACKED_IPS = 10000;
+
+/**
+ * Simple IP-based rate limiter for unauthenticated endpoints.
+ * Uses a sliding window with per-IP tracking.
+ */
+function createIPRateLimiter(maxPerWindow: number, windowMs: number) {
+  const hits = new Map<string, number[]>();
+
+  // Periodic cleanup to prevent memory leaks
+  setInterval(() => {
+    const now = Date.now();
+    for (const [ip, timestamps] of hits) {
+      const valid = timestamps.filter(t => now - t < windowMs);
+      if (valid.length === 0) {
+        hits.delete(ip);
+      } else {
+        hits.set(ip, valid);
+      }
+    }
+  }, windowMs).unref();
+
+  return (req: express.Request, res: express.Response, next: express.NextFunction): void => {
+    const ip = req.ip || req.socket.remoteAddress || 'unknown';
+    const now = Date.now();
+    const timestamps = hits.get(ip) || [];
+    const windowStart = now - windowMs;
+    const valid = timestamps.filter(t => t > windowStart);
+
+    if (valid.length >= maxPerWindow) {
+      sendError(res, 429, ErrorCode.RATE_LIMIT_EXCEEDED, 'Too many requests', {
+        details: { retry_after_ms: windowMs - (now - valid[0]) },
+        hint: 'Retry after the reset time or increase rate_limit config',
+      });
+      return;
+    }
+
+    // Reject new IPs when the map is at capacity to prevent unbounded growth
+    if (!hits.has(ip) && hits.size >= MAX_TRACKED_IPS) {
+      sendError(res, 429, ErrorCode.RATE_LIMIT_EXCEEDED, 'Too many requests', {
+        details: { retry_after_ms: windowMs },
+        hint: 'Retry after the reset time or increase rate_limit config',
+      });
+      return;
+    }
+
+    valid.push(now);
+    hits.set(ip, valid);
+    next();
+  };
+}
+
+export interface HealthCheck {
+  name: string;
+  check: () => Promise<{ status: 'ok' | 'degraded' | 'unhealthy'; message?: string }>;
+}
+
+export interface HealthCheckResult {
+  status: 'ok' | 'degraded' | 'unhealthy';
+  message?: string;
+}
+
+export interface SaaSStores {
+  userStore: UserStore;
+  oauthAccountStore: OAuthAccountStore;
+  workspaceStore: WorkspaceStore;
+  workspaceMemberStore: WorkspaceMemberStore;
+  sessionStore: SessionStore;
+  userApiKeyStore: UserApiKeyStore;
+  subscriptionStore: SubscriptionStore;
+  mcpOAuthClientsStore?: PostgresOAuthClientsStore;
+  mcpOAuthTokenStore?: PostgresOAuthTokenStore;
+  policyStore?: PolicyStore;
+  rateLimitConfigStore?: RateLimitConfigStore;
+  budgetConfigStore?: BudgetConfigStore;
+}
+
+export interface CreateAppResult {
+  app: express.Application;
+  gateway: Gateway;
+  metrics: GatewayMetrics;
+  tracer?: GatewayTracer;
+  healthChecks: HealthCheck[];
+  saasStores: SaaSStores;
+  proxyServer?: ForwardProxyServer;
+}
+
+export function createApp(config: GatewayConfig, externalSaaSStores?: Partial<SaaSStores>): CreateAppResult {
+  const app = express();
+  const metrics = new GatewayMetrics();
+  const startTime = Date.now();
+  const healthChecks: HealthCheck[] = [];
+
+  // Initialize SaaS stores (use provided, file-persisted, or default to in-memory)
+  let saasStores: SaaSStores;
+  let filePersistence: FilePersistedStores | undefined;
+
+  if (externalSaaSStores?.userStore) {
+    // External stores provided (e.g., PostgreSQL)
+    saasStores = {
+      userStore: externalSaaSStores.userStore,
+      oauthAccountStore: externalSaaSStores.oauthAccountStore || new InMemoryOAuthAccountStore(),
+      workspaceStore: externalSaaSStores.workspaceStore || new InMemoryWorkspaceStore(),
+      workspaceMemberStore: externalSaaSStores.workspaceMemberStore || new InMemoryWorkspaceMemberStore(),
+      sessionStore: externalSaaSStores.sessionStore || new InMemorySessionStore(),
+      userApiKeyStore: externalSaaSStores.userApiKeyStore || new InMemoryUserApiKeyStore(),
+      subscriptionStore: externalSaaSStores.subscriptionStore || new InMemorySubscriptionStore(),
+      policyStore: externalSaaSStores.policyStore,
+      rateLimitConfigStore: externalSaaSStores.rateLimitConfigStore,
+      budgetConfigStore: externalSaaSStores.budgetConfigStore,
+    };
+  } else {
+    // File-persisted in-memory stores (survives server restarts)
+    const dataDir = process.env.PALARYN_DATA_DIR || './data';
+    filePersistence = new FilePersistedStores(dataDir);
+    saasStores = {
+      userStore: filePersistence.userStore,
+      oauthAccountStore: filePersistence.oauthAccountStore,
+      workspaceStore: filePersistence.workspaceStore,
+      workspaceMemberStore: filePersistence.workspaceMemberStore,
+      sessionStore: filePersistence.sessionStore,
+      userApiKeyStore: filePersistence.userApiKeyStore,
+      subscriptionStore: new InMemorySubscriptionStore(),
+      policyStore: filePersistence.policyStore,
+    };
+  }
+
+  // Default OAuth config for session/auth routes (email+password always works)
+  const oauthConfig = config.oauth || {
+    enabled: false,
+    session_secret: 'palaryn-dev-session-secret',
+    session_ttl_seconds: 604800,
+  };
+
+  // Seed test account in non-production (async due to hashPassword)
+  if (process.env.NODE_ENV !== 'production') {
+    (async () => {
+      const existing = saasStores.userStore.getByEmail('test@palaryn.dev');
+      if (!existing) {
+        const now = new Date().toISOString();
+        saasStores.userStore.create({
+          id: 'usr_test_000',
+          email: 'test@palaryn.dev',
+          display_name: 'Test User',
+          password_hash: await hashPassword('test1234'),
+          status: 'active',
+          onboarding_completed: false,
+          created_at: now,
+          updated_at: now,
+        });
+      }
+    })();
+  }
+
+  // Seed admin account from env vars (for production with in-memory storage)
+  if (process.env.SEED_ADMIN_EMAIL && process.env.SEED_ADMIN_PASSWORD) {
+    (async () => {
+      const existing = saasStores.userStore.getByEmail(process.env.SEED_ADMIN_EMAIL!);
+      if (!existing) {
+        const now = new Date().toISOString();
+        const userId = 'usr_admin_001';
+        const workspaceId = process.env.SEED_ADMIN_WORKSPACE || 'ws_default';
+        saasStores.userStore.create({
+          id: userId,
+          email: process.env.SEED_ADMIN_EMAIL!,
+          display_name: process.env.SEED_ADMIN_NAME || 'Admin',
+          avatar_url: process.env.SEED_ADMIN_AVATAR_URL,
+          password_hash: await hashPassword(process.env.SEED_ADMIN_PASSWORD!),
+          status: 'active',
+          onboarding_completed: true,
+          created_at: now,
+          updated_at: now,
+        });
+        // Create workspace if store supports it
+        if (saasStores.workspaceStore && typeof saasStores.workspaceStore.create === 'function') {
+          const existingWs = saasStores.workspaceStore.getById(workspaceId);
+          if (!existingWs) {
+            saasStores.workspaceStore.create({
+              id: workspaceId,
+              name: process.env.SEED_ADMIN_WORKSPACE_NAME || 'Default',
+              slug: 'default',
+              owner_user_id: userId,
+              plan: 'pro',
+              settings: {},
+              created_at: now,
+              updated_at: now,
+            });
+          }
+        }
+        // Add user as workspace owner
+        if (saasStores.workspaceMemberStore && typeof saasStores.workspaceMemberStore.create === 'function') {
+          saasStores.workspaceMemberStore.create({
+            id: `wm_${userId}_${workspaceId}`,
+            workspace_id: workspaceId,
+            user_id: userId,
+            role: 'owner',
+            joined_at: now,
+          });
+        }
+      }
+    })();
+  }
+
+  // Initialize OpenTelemetry tracer if tracing is configured
+  let tracer: GatewayTracer | undefined;
+  if (config.tracing?.enabled) {
+    tracer = new GatewayTracer(config.tracing);
+    tracer.setup();
+  }
+
+  const gateway = new Gateway(config, metrics, tracer);
+
+  // Inject workspace-level policy store so per-workspace policies are evaluated
+  if (saasStores.policyStore) {
+    gateway.setStores({ policyStore: saasStores.policyStore });
+  }
+
+  // Register noop executors for non-HTTP tools (e.g. pre-flight validation from Android)
+  gateway.registerExecutor('web_search', new NoopExecutor({ body: { validated: true, tool: 'web_search' } }));
+  gateway.registerExecutor('chat.completion', new NoopExecutor({ body: { validated: true, tool: 'chat.completion' } }));
+
+  // Rate limiter for unauthenticated endpoints (60 requests per minute per IP)
+  const publicLimitConfig = config.public_rate_limit || { max_per_window: 60, window_ms: 60000 };
+  const publicRateLimiter = createIPRateLimiter(publicLimitConfig.max_per_window, publicLimitConfig.window_ms);
+
+  // Middleware
+  const isProduction = process.env.NODE_ENV === 'production';
+  app.use(helmet({
+    contentSecurityPolicy: {
+      directives: {
+        defaultSrc: ["'self'"],
+        scriptSrc: ["'self'", "'unsafe-inline'"],
+        styleSrc: ["'self'", "'unsafe-inline'", "https://fonts.googleapis.com"],
+        fontSrc: ["'self'", "https://fonts.gstatic.com", "data:"],
+        imgSrc: ["'self'", "data:", "https:"],
+        connectSrc: ["'self'"],
+        frameAncestors: ["'none'"],
+        upgradeInsecureRequests: isProduction ? [] : null,
+      },
+    },
+    hsts: isProduction ? { maxAge: 31536000, includeSubDomains: true } : false,
+    xFrameOptions: { action: 'deny' },
+  }));
+  app.use(cors(
+    config.cors_origins
+      ? { origin: config.cors_origins, credentials: true }
+      : isProduction
+        ? { origin: false } // Block all cross-origin in production when not configured
+        : { origin: ['http://localhost:3000', 'http://localhost:3001', 'http://localhost:5173', 'http://127.0.0.1:3000', 'http://127.0.0.1:5173'], credentials: true }
+  ));
+  // Stripe webhook route (must be before express.json() for raw body signature verification)
+  if (config.stripe?.secret_key && config.stripe?.webhook_secret) {
+    const stripeClient = new StripeClient(config.stripe);
+    const webhookHandler = new WebhookHandler(saasStores.subscriptionStore, saasStores.workspaceStore, config.stripe);
+    app.use(createWebhookRouter(stripeClient, webhookHandler));
+  }
+
+  app.use(express.json({ limit: '10mb' }));
+  app.use(cookieParser());
+
+  // Server-side request timeout (30 seconds default, prevents hung connections)
+  app.use((req, res, next) => {
+    const timeoutMs = 30000;
+    res.setTimeout(timeoutMs, () => {
+      if (!res.headersSent) {
+        sendError(res, 408, ErrorCode.REQUEST_TIMEOUT, 'Request timeout', {
+          hint: 'The server did not complete the request within 30 seconds',
+        });
+      }
+    });
+    next();
+  });
+
+  // Dev request/response logging middleware
+  app.use((req, res, next) => {
+    const reqStart = Date.now();
+    // Skip noisy health/metrics polling
+    if (req.path === '/health' || req.path === '/ready' || req.path === '/metrics') {
+      return next();
+    }
+    devLog.request(req.method, req.path, req.ip || req.socket.remoteAddress || 'unknown', req.body);
+
+    const origJson = res.json.bind(res);
+    res.json = (body: unknown) => {
+      devLog.response(res.statusCode, Date.now() - reqStart, body as Record<string, unknown>);
+      return origJson(body);
+    };
+
+    const origSend = res.send.bind(res);
+    res.send = (body?: any) => {
+      // Log HTML responses (from admin routes) without the full body
+      if (typeof body === 'string' && body.startsWith('<!DOCTYPE html>')) {
+        devLog.response(res.statusCode, Date.now() - reqStart, { html: true, length: body.length });
+      }
+      return origSend(body);
+    };
+    next();
+  });
+
+  // Health check (no auth) - minimal response to avoid information disclosure
+  app.get('/health', publicRateLimiter, async (req, res) => {
+    // Internal dependency checks
+    const checks: { name: string; status: string }[] = [];
+    let overall: 'ok' | 'degraded' | 'unhealthy' = 'ok';
+
+    for (const hc of healthChecks) {
+      try {
+        const result = await hc.check();
+        checks.push({ name: hc.name, status: result.status });
+        if (result.status === 'unhealthy') overall = 'unhealthy';
+        else if (result.status === 'degraded' && overall !== 'unhealthy') overall = 'degraded';
+      } catch {
+        checks.push({ name: hc.name, status: 'unhealthy' });
+        overall = 'unhealthy';
+      }
+    }
+
+    // Return 503 when any critical dependency is unhealthy
+    const httpStatus = overall === 'unhealthy' ? 503 : 200;
+
+    // Unauthenticated: minimal response (no version, uptime, or internal component names)
+    const authCtx = (req as any).auth;
+    if (authCtx && authCtx.auth_method !== 'none') {
+      const uptimeSeconds = Math.floor((Date.now() - startTime) / 1000);
+      res.status(httpStatus).json({
+        status: overall,
+        version: '0.1.0',
+        timestamp: new Date().toISOString(),
+        uptime_seconds: uptimeSeconds,
+        checks,
+      });
+    } else {
+      res.status(httpStatus).json({ status: overall });
+    }
+  });
+
+  // Readiness probe (no auth) - for K8s readiness checks
+  // Unlike /health which always returns 200, /ready returns 503 when unhealthy
+  app.get('/ready', publicRateLimiter, async (req, res) => {
+    const checks: { name: string; status: string; message?: string }[] = [];
+    let ready = true;
+
+    // Check if gateway is shutting down
+    if (gateway.isShuttingDown) {
+      checks.push({ name: 'gateway', status: 'unhealthy', message: 'shutting down' });
+      ready = false;
+    } else {
+      checks.push({ name: 'gateway', status: 'ok' });
+    }
+
+    // Check registered external dependencies (Redis, Postgres, etc.)
+    for (const hc of healthChecks) {
+      try {
+        const result = await hc.check();
+        checks.push({ name: hc.name, status: result.status, message: result.message });
+        if (result.status === 'unhealthy') {
+          ready = false;
+        }
+      } catch (err) {
+        checks.push({ name: hc.name, status: 'unhealthy', message: err instanceof Error ? err.message : 'check failed' });
+        ready = false;
+      }
+    }
+
+    // Always check core components
+    checks.push({ name: 'policy_engine', status: 'ok' });
+
+    if (ready) {
+      res.json({ ready: true, checks });
+    } else {
+      res.status(503).json({ ready: false, checks });
+    }
+  });
+
+  // Prometheus metrics endpoint (auth required in production, open in dev for scraping)
+  app.get('/metrics', publicRateLimiter, async (req, res) => {
+    // In production, require auth to prevent information disclosure
+    if (isProduction && config.auth.enabled) {
+      const apiKey = req.headers['x-api-key'] as string | undefined;
+      const bearer = (req.headers['authorization'] as string | undefined)?.startsWith('Bearer ') ? (req.headers['authorization'] as string).slice(7) : undefined;
+      if (!apiKey && !bearer) {
+        sendError(res, 401, ErrorCode.AUTH_REQUIRED, 'Authentication required for /metrics in production');
+        return;
+      }
+    }
+    try {
+      const metricsOutput = await metrics.getMetrics();
+      res.set('Content-Type', metrics.getContentType());
+      res.end(metricsOutput);
+    } catch (err) {
+      res.status(500).end();
+    }
+  });
+
+  // Serve install script: curl -fsSL https://app.palaryn.com/install.sh | sh
+  app.get('/install.sh', publicRateLimiter, (req, res) => {
+    // __dirname is dist/src/server — go up 3 levels to repo root
+    const scriptPath = path.resolve(__dirname, '..', '..', '..', 'install.sh');
+    if (fs.existsSync(scriptPath)) {
+      res.set('Content-Type', 'text/plain; charset=utf-8');
+      res.send(fs.readFileSync(scriptPath, 'utf-8'));
+    } else {
+      res.status(404).send('# install.sh not found\n');
+    }
+  });
+
+  // Rate limiter for auth endpoints (10 requests per minute per IP — tighter than public)
+  const authRateLimiter = createIPRateLimiter(10, 60000);
+
+  // Stricter rate limiter for registration (3 per 15 minutes per IP)
+  const registerRateLimiter = createIPRateLimiter(3, 15 * 60 * 1000);
+
+  // Session middleware + auth routes (always mounted for email/password auth)
+  const sessionMiddleware = createSessionMiddleware({
+    oauthConfig: oauthConfig,
+    authConfig: config.auth,
+    sessionStore: saasStores.sessionStore,
+    userStore: saasStores.userStore,
+    workspaceMemberStore: saasStores.workspaceMemberStore,
+  });
+  app.use(sessionMiddleware);
+
+  const authRouter = createAuthRouter({
+    config: oauthConfig,
+    userStore: saasStores.userStore,
+    oauthAccountStore: saasStores.oauthAccountStore,
+    sessionStore: saasStores.sessionStore,
+    workspaceStore: saasStores.workspaceStore,
+    workspaceMemberStore: saasStores.workspaceMemberStore,
+    userApiKeyStore: saasStores.userApiKeyStore,
+  });
+  app.use('/auth/register', registerRateLimiter);
+  // Rate limit sensitive auth endpoints (login, OAuth) but not /auth/me (called on every page load)
+  app.use('/auth/login', authRateLimiter);
+  app.use('/auth/google', authRateLimiter);
+  app.use('/auth/github', authRateLimiter);
+  app.use('/auth', authRouter);
+
+  // Auth middleware for API routes (bridges config keys + SaaS-generated keys)
+  const authMiddleware = createAuthMiddleware(config.auth, saasStores.userApiKeyStore);
+
+  // RBAC middleware factories
+  const rbacToolExecute = createRBACMiddleware(config.auth, 'tool:execute');
+  const rbacApprovalManage = createRBACMiddleware(config.auth, 'approval:manage');
+  const rbacTraceRead = createRBACMiddleware(config.auth, 'trace:read');
+  const rbacPolicyRead = createRBACMiddleware(config.auth, 'policy:read');
+  const rbacPolicyWrite = createRBACMiddleware(config.auth, 'policy:write');
+
+  // Admin routes (require auth + admin:full permission)
+  // Auth + RBAC middleware mounted directly with the router to prevent route decoupling
+  const adminRouter = createAdminRouter(gateway, config);
+  const rbacAdmin = createRBACMiddleware(config.auth, 'admin:full');
+  app.use('/admin', authMiddleware, rbacAdmin, adminRouter);
+
+  // Plan enforcer middleware — blocks calls when workspace exceeds plan limits
+  const planEnforcerMiddleware = createPlanEnforcerMiddleware({
+    workspaceStore: saasStores.workspaceStore,
+    getMonthlyCallCount: (workspaceId: string) => {
+      const now = new Date();
+      const monthStart = new Date(now.getFullYear(), now.getMonth(), 1).toISOString();
+      const events = gateway.getAuditLogger().getAllEvents();
+      return events.filter(
+        e => e.workspace_id === workspaceId
+          && e.event_type === 'TOOL_CALL_RECEIVED'
+          && e.timestamp >= monthStart
+      ).length;
+    },
+  });
+
+  // POST /v1/tool/execute - Execute a tool call through the gateway
+  app.post('/v1/tool/execute', authMiddleware, rbacToolExecute, planEnforcerMiddleware, normalizeToolCall, validateToolCall, async (req, res) => {
+    try {
+      // Capability-specific RBAC check
+      const capability = req.body.tool?.capability;
+      if (capability && config.auth.rbac?.enabled) {
+        const authCtx = (req as any).auth;
+        if (authCtx && authCtx.auth_method !== 'none') {
+          const { hasPermission } = require('../middleware/auth');
+          const capPerm = `tool:execute:${capability}`;
+          // Only enforce capability check if user does NOT have the broad tool:execute permission
+          // and does NOT have admin:full
+          if (!hasPermission(authCtx.permissions, capPerm)) {
+            sendError(res, 403, ErrorCode.AUTH_INSUFFICIENT_PERMS, `Insufficient permissions. Required: ${capPerm}`, {
+              details: { required_permission: capPerm, roles: authCtx.roles },
+              hint: 'Assign a role with the required permission or use an admin key',
+            });
+            return;
+          }
+        }
+      }
+
+      const toolCall = {
+        ...req.body,
+        workspace_id: (req as any).auth?.workspace_id || req.body.workspace_id || (req as any).workspace_id,
+      };
+      // Merge API key tags into context.labels
+      const apiKeyTags: string[] | undefined = (req as any).auth?.api_key_tags;
+      if (apiKeyTags && apiKeyTags.length > 0) {
+        if (!toolCall.context) toolCall.context = {};
+        const existing: string[] = toolCall.context.labels || [];
+        toolCall.context.labels = [...new Set([...existing, ...apiKeyTags])];
+      }
+      const requestingApiKeyId = (req as any).auth?.api_key_id;
+      const result = await gateway.execute(toolCall, requestingApiKeyId);
+      // Use 429 for rate limit blocks, 403 for policy blocks
+      let httpStatus: number;
+      if (result.status === 'ok') {
+        httpStatus = 200;
+      } else if (result.status === 'blocked') {
+        httpStatus = result.policy?.rule_id === 'rate_limit' ? 429 : 403;
+      } else if (result.status === 'needs_approval') {
+        httpStatus = 202;
+      } else {
+        httpStatus = 500;
+      }
+      // S3: Never leak raw error messages to clients (may contain internal paths, IPs, secrets)
+      if (result.error) {
+        console.error('[tool-execute] Gateway error:', result.error);
+        result.error = 'Tool execution failed';
+      }
+      res.status(httpStatus).json(result);
+    } catch (err) {
+      const errorMessage = err instanceof Error ? err.message : 'Unknown error';
+      console.error('[tool-execute] Execution error:', errorMessage);
+      sendError(res, 500, ErrorCode.TOOL_EXECUTION_ERROR, 'Tool execution failed');
+    }
+  });
+
+  // POST /v1/proxy/stream - SSE streaming proxy (dormant, feature-flagged)
+  // Kept for future use when gateway controls the upstream directly.
+  // Enable with PROXY_STREAM_ENABLED=true environment variable.
+  if (process.env.PROXY_STREAM_ENABLED === 'true') {
+    app.post('/v1/proxy/stream', authMiddleware, rbacToolExecute, async (req, res) => {
+      try {
+        const { tool_call_id, task_id, actor, source, tool, target, context, constraints } = req.body;
+
+        if (!tool_call_id || !task_id || !actor || !tool || !target?.url) {
+          sendError(res, 400, ErrorCode.VALIDATION_FAILED, 'Missing required fields: tool_call_id, task_id, actor, tool, target.url', {
+            hint: 'Check the stream proxy request schema',
+          });
+          return;
+        }
+
+        const toolCall: ToolCall = {
+          tool_call_id,
+          task_id,
+          workspace_id: (req as any).auth?.workspace_id || req.body.workspace_id || 'unknown',
+          actor: { type: actor.type || 'agent', id: actor.id, display: actor.display },
+          source: { platform: source?.platform || 'unknown', session_id: source?.session_id },
+          tool: { name: tool.name, version: tool.version, capability: tool.capability || 'write' },
+          args: {
+            method: target.method || 'POST',
+            url: target.url,
+            headers: target.headers,
+            body: target.body,
+          },
+          constraints,
+          context,
+        };
+
+        const pre = await gateway.preExecute(toolCall);
+        if (!pre.allowed) {
+          const httpStatus = pre.result!.status === 'blocked' ? 403 : pre.result!.status === 'needs_approval' ? 202 : 500;
+          res.status(httpStatus).json(pre.result);
+          return;
+        }
+
+        res.setTimeout(0);
+
+        const proxyResult = await streamProxy({
+          url: target.url,
+          method: target.method || 'POST',
+          headers: target.headers || {},
+          body: target.body,
+          timeoutMs: constraints?.timeout_ms || 120000,
+        }, res);
+
+        try {
+          await gateway.postExecute(toolCall, {
+            http_status: proxyResult.httpStatus,
+            body: proxyResult.accumulatedBody,
+            headers: proxyResult.headers,
+          }, pre);
+        } catch (postErr) {
+          console.error('[post-execute] Failed:', postErr instanceof Error ? postErr.message : postErr);
+          // Don't fail the response — it's already sent for streaming
+        }
+
+      } catch (err) {
+        const errorMessage = err instanceof Error ? err.message : 'Unknown error';
+        console.error('[stream-proxy] Execution error:', errorMessage);
+        if (!res.headersSent) {
+          sendError(res, 502, ErrorCode.TOOL_EXECUTION_ERROR, 'Stream proxy failed');
+        } else {
+          try {
+            res.write(`event: error\ndata: ${JSON.stringify({ error: 'Stream proxy failed' })}\n\n`);
+            res.end();
+          } catch {
+            // Client already disconnected
+          }
+        }
+      }
+    });
+  }
+
+  // POST /v1/tool/approve - Approve or deny a pending action
+  app.post('/v1/tool/approve', authMiddleware, rbacApprovalManage, async (req, res) => {
+    try {
+      const { approval_token, approved, approver_id, reason } = req.body;
+      if (!approval_token) {
+        sendError(res, 400, ErrorCode.VALIDATION_FAILED, 'approval_token is required', {
+          hint: 'Include the approval_token from the needs_approval response',
+        });
+        return;
+      }
+      // Use auth context for approver identity (not user-supplied approver_id)
+      const authCtx = (req as any).auth;
+      const approverApiKeyId = authCtx?.api_key_id;
+      const effectiveApproverId = authCtx?.actor_id || approver_id || 'unknown';
+      const result = await gateway.processApproval(
+        approval_token,
+        effectiveApproverId,
+        approved !== false,
+        reason,
+        approverApiKeyId,
+      );
+      if (result.success) {
+        res.json({ status: 'ok', ...result });
+      } else {
+        sendError(res, 400, ErrorCode.VALIDATION_FAILED, result.error || 'Approval processing failed');
+      }
+    } catch (err) {
+      const errorMessage = err instanceof Error ? err.message : 'Unknown error';
+      console.error('[tool-approve] Error:', errorMessage);
+      sendError(res, 500, ErrorCode.INTERNAL_ERROR, 'Approval processing failed');
+    }
+  });
+
+  // GET /v1/tasks/:task_id/trace - Get full trace for a task
+  // Workspace isolation: non-admin callers only see events for their own workspace
+  app.get('/v1/tasks/:task_id/trace', authMiddleware, rbacTraceRead, (req, res) => {
+    const taskId = Array.isArray(req.params.task_id) ? req.params.task_id[0] : req.params.task_id;
+    const authCtx = (req as any).auth;
+    let events = gateway.getTaskTrace(taskId);
+
+    // Scope to workspace unless caller has admin:full permission
+    if (authCtx?.workspace_id && authCtx.auth_method !== 'none') {
+      const { hasPermission } = require('../middleware/auth');
+      if (!hasPermission(authCtx.permissions, 'admin:full')) {
+        events = events.filter(e => !e.workspace_id || e.workspace_id === authCtx.workspace_id);
+      }
+    }
+    res.json({ task_id: taskId, events });
+  });
+
+  // GET /v1/policies/current - Get active policy configuration
+  app.get('/v1/policies/current', authMiddleware, rbacPolicyRead, (req, res) => {
+    res.json(gateway.getCurrentPolicy());
+  });
+
+  // POST /v1/policies/validate - Validate a policy configuration
+  app.post('/v1/policies/validate', authMiddleware, rbacPolicyWrite, (req, res) => {
+    const result = gateway.validatePolicy(req.body);
+    res.json(result);
+  });
+
+  // POST /v1/policies/reload - Hot-reload policy from disk
+  app.post('/v1/policies/reload', authMiddleware, rbacPolicyWrite, (req, res) => {
+    const result = gateway.reloadPolicy();
+    if (result.success) {
+      res.json({ status: 'ok', rule_count: result.ruleCount });
+    } else {
+      sendError(res, 500, ErrorCode.INTERNAL_ERROR, result.error || 'Policy reload failed');
+    }
+  });
+
+  // POST /v1/usage/report - Report actual usage/cost from clients
+  app.post('/v1/usage/report', authMiddleware, rbacToolExecute, (req, res) => {
+    try {
+      const { tool_call_id, task_id, actual_cost_usd, usage, workspace_id, actor_id } = req.body;
+
+      if (!tool_call_id || !task_id) {
+        sendError(res, 400, ErrorCode.VALIDATION_FAILED, 'tool_call_id and task_id are required', {
+          hint: 'Both tool_call_id and task_id must be provided in the request body',
+        });
+        return;
+      }
+
+      gateway.reportUsage({
+        tool_call_id,
+        task_id,
+        workspace_id: workspace_id || (req as any).workspace_id,
+        actor_id: actor_id || (req as any).auth?.actor_id,
+        actual_cost_usd,
+        usage,
+      });
+
+      res.json({ status: 'ok' });
+    } catch (err) {
+      const errorMessage = err instanceof Error ? err.message : 'Unknown error';
+      console.error('[usage-report] Error:', errorMessage);
+      sendError(res, 500, ErrorCode.INTERNAL_ERROR, 'Usage reporting failed');
+    }
+  });
+
+  // GET /v1/approvals/pending - List pending approvals
+  // Workspace isolation: non-admin callers are forced to their own workspace
+  app.get('/v1/approvals/pending', authMiddleware, rbacApprovalManage, (req, res) => {
+    const authCtx = (req as any).auth;
+    let workspaceId = typeof req.query.workspace_id === 'string' ? req.query.workspace_id : undefined;
+
+    // Enforce workspace scope for non-admin callers
+    if (authCtx?.workspace_id && authCtx.auth_method !== 'none') {
+      const { hasPermission } = require('../middleware/auth');
+      if (!hasPermission(authCtx.permissions, 'admin:full')) {
+        workspaceId = authCtx.workspace_id;
+      }
+    }
+
+    const approvals = gateway.getPendingApprovals(workspaceId);
+    res.json({ approvals });
+  });
+
+  // GET /v1/config/active - View active configuration (admin-only, secrets redacted)
+  app.get('/v1/config/active', authMiddleware, rbacAdmin, (req, res) => {
+    const redacted = JSON.parse(JSON.stringify(config));
+
+    // Deep redaction: recursively redact any key containing 'secret', 'password', or 'token'
+    function deepRedact(obj: any): void {
+      if (!obj || typeof obj !== 'object') return;
+      for (const key of Object.keys(obj)) {
+        const lowerKey = key.toLowerCase();
+        if (lowerKey.includes('secret') || lowerKey.includes('password') || lowerKey.includes('token')) {
+          obj[key] = '[REDACTED]';
+        } else if (lowerKey === 'last_used_at' || lowerKey === 'created_at') {
+          obj[key] = null;
+        } else if (typeof obj[key] === 'object' && obj[key] !== null) {
+          deepRedact(obj[key]);
+        }
+      }
+    }
+    deepRedact(redacted);
+
+    // Redact API key values (show only key prefix, strip metadata timestamps)
+    if (redacted.auth?.api_keys) {
+      const redactedKeys: Record<string, unknown> = {};
+      for (const key of Object.keys(redacted.auth.api_keys)) {
+        const entry = redacted.auth.api_keys[key];
+        if (typeof entry === 'object' && entry !== null) {
+          delete entry.last_used_at;
+          delete entry.created_at;
+        }
+        redactedKeys[key.slice(0, 8) + '...'] = entry;
+      }
+      redacted.auth.api_keys = redactedKeys;
+    }
+    res.json(redacted);
+  });
+
+  // Inject per-workspace config stores into gateway if provided externally
+  if (saasStores.rateLimitConfigStore || saasStores.budgetConfigStore) {
+    gateway.setStores({
+      rateLimitConfigStore: saasStores.rateLimitConfigStore,
+      budgetConfigStore: saasStores.budgetConfigStore,
+    });
+  }
+
+  // SaaS API routes (require session auth)
+  const saasRouter = createSaaSRouter({
+    config,
+    userStore: saasStores.userStore,
+    workspaceStore: saasStores.workspaceStore,
+    workspaceMemberStore: saasStores.workspaceMemberStore,
+    userApiKeyStore: saasStores.userApiKeyStore,
+    sessionStore: saasStores.sessionStore,
+    gateway,
+    policyStore: saasStores.policyStore,
+    rateLimitConfigStore: saasStores.rateLimitConfigStore,
+    budgetConfigStore: saasStores.budgetConfigStore,
+  });
+  app.use('/api/v1', authMiddleware, saasRouter);
+
+  // Billing API routes (require session auth, only when Stripe is configured)
+  if (config.stripe?.secret_key) {
+    const billingStripeClient = new StripeClient(config.stripe);
+    const billingRouter = createBillingRouter({
+      stripeClient: billingStripeClient,
+      stripeConfig: config.stripe,
+      subscriptionStore: saasStores.subscriptionStore,
+      workspaceStore: saasStores.workspaceStore,
+      workspaceMemberStore: saasStores.workspaceMemberStore,
+      gateway,
+    });
+    app.use('/api/v1', billingRouter);
+  }
+
+  // MCP HTTP transport with OAuth 2.0 support.
+  // When mcp_oauth is enabled, uses the MCP SDK's OAuth router + bearer auth.
+  // When disabled, falls back to existing auth middleware + RBAC.
+  const mcpBaseUrl = config.mcp_oauth?.base_url
+    || (isProduction ? 'https://app.palaryn.com' : `http://localhost:${config.port}`);
+  const mcpHandler = createMCPHttpHandler(gateway, {
+    gateway_base_url: config.mcp_oauth?.enabled ? mcpBaseUrl : undefined,
+  });
+
+  if (config.mcp_oauth?.enabled) {
+    // Create OAuth stores — prefer Postgres-backed stores when available
+    const oauthClientsStore = saasStores.mcpOAuthClientsStore
+      || filePersistence?.oauthClientsStore
+      || new OAuthClientsStore();
+    const authCodeStore = new AuthCodeStore();
+    const tokenStore = saasStores.mcpOAuthTokenStore
+      || new OAuthTokenStore(
+        config.mcp_oauth.access_token_ttl || 3600,
+        config.mcp_oauth.refresh_token_ttl || 30 * 24 * 3600,
+      );
+
+    // Create OAuth provider
+    const oauthProvider = new PalarynOAuthProvider({
+      clientsStore: oauthClientsStore,
+      authCodeStore,
+      tokenStore,
+      userStore: saasStores.userStore,
+      workspaceStore: saasStores.workspaceStore,
+      workspaceMemberStore: saasStores.workspaceMemberStore,
+      sessionStore: saasStores.sessionStore,
+      rbacConfig: config.auth.rbac,
+    });
+
+    // Determine base URL for OAuth metadata
+    const baseUrl = config.mcp_oauth.base_url
+      || (isProduction ? 'https://app.palaryn.com' : `http://localhost:${config.port}`);
+    const issuerUrl = new URL(baseUrl);
+    const resourceServerUrl = new URL('/mcp', baseUrl);
+    const resourceMetadataUrl = getOAuthProtectedResourceMetadataUrl(resourceServerUrl);
+
+    // Mount OAuth routes at app root (/.well-known/*, /authorize, /token, /register, /revoke)
+    app.use(mcpAuthRouter({
+      provider: oauthProvider,
+      issuerUrl,
+      resourceServerUrl,
+      scopesSupported: ['mcp:tools'],
+    }));
+
+    // Consent decision endpoint (POST /authorize/decision from the consent form)
+    app.post('/authorize/decision', express.urlencoded({ extended: false }), async (req, res) => {
+      // Verify the user is logged in via session cookie
+      const sessionId = req.cookies?.[SESSION_COOKIE_NAME];
+      if (!sessionId) {
+        res.status(401).send('Not authenticated');
+        return;
+      }
+      const session = saasStores.sessionStore.getById(sessionId);
+      if (!session) {
+        res.status(401).send('Session expired');
+        return;
+      }
+
+      const result = await oauthProvider.handleConsentDecision(req.body, session.user_id);
+      if ('error' in result) {
+        res.status(result.status).send(result.error);
+        return;
+      }
+      res.redirect(result.redirectUrl);
+    });
+
+    // Create hybrid verifier (OAuth + API keys)
+    const hybridVerifier = new HybridTokenVerifier({
+      oauthProvider,
+      authConfig: config.auth,
+      userApiKeyStore: saasStores.userApiKeyStore,
+    });
+
+    // MCP with SDK's bearer auth (returns proper WWW-Authenticate on 401)
+    app.use('/mcp', requireBearerAuth({
+      verifier: hybridVerifier,
+      resourceMetadataUrl,
+    }), mcpHandler.router);
+  } else {
+    // Legacy: use existing auth middleware + RBAC
+    app.use('/mcp', authMiddleware, rbacToolExecute, mcpHandler.router);
+  }
+
+  // Frontend SPA serving (must be last, serves index.html for all unmatched routes)
+  if (config.frontend?.enabled) {
+    const frontendPath = path.resolve(config.frontend.build_path);
+    app.use(express.static(frontendPath));
+    app.get('/{*splat}', (req, res) => {
+      // Don't serve SPA for API routes or known backend routes
+      if (req.path.startsWith('/v1/') || req.path.startsWith('/api/') ||
+          req.path.startsWith('/auth/') || req.path.startsWith('/admin/') ||
+          req.path === '/health' || req.path === '/metrics') {
+        sendError(res, 404, ErrorCode.NOT_FOUND, 'Not found');
+        return;
+      }
+      res.sendFile(path.join(frontendPath, 'index.html'));
+    });
+  }
+
+  // Global error handler — catches JSON parse errors and other unhandled errors
+  // Must be registered after all routes (Express identifies error handlers by 4 params)
+  app.use((err: any, req: express.Request, res: express.Response, next: express.NextFunction) => {
+    // JSON parse errors from body-parser
+    if (err.type === 'entity.parse.failed' || (err instanceof SyntaxError && 'body' in err)) {
+      sendError(res, 400, ErrorCode.VALIDATION_FAILED, 'Invalid JSON in request body', {
+        hint: 'Ensure the request body is valid JSON',
+      });
+      return;
+    }
+    // Payload too large
+    if (err.type === 'entity.too.large') {
+      sendError(res, 413, ErrorCode.VALIDATION_FAILED, 'Request body too large', {
+        hint: 'Maximum request body size is 10MB',
+      });
+      return;
+    }
+    // All other errors — never expose stack traces
+    const message = isProduction ? 'Internal server error' : (err.message || 'Internal server error');
+    sendError(res, err.status || 500, ErrorCode.INTERNAL_ERROR, message);
+  });
+
+  // Session cleanup job: purge expired sessions every 5 minutes
+  const sessionCleanupInterval = setInterval(() => {
+    try {
+      saasStores.sessionStore.deleteExpired();
+    } catch {
+      // Ignore cleanup errors
+    }
+  }, 300_000);
+  sessionCleanupInterval.unref();
+
+  // Forward proxy server (optional, started alongside Express)
+  let proxyServer: ForwardProxyServer | undefined;
+  if (config.proxy?.enabled) {
+    proxyServer = createForwardProxy(gateway, config);
+  }
+
+  return { app, gateway, metrics, tracer, healthChecks, saasStores, proxyServer };
+}