mcp.ts

/**
 * Vercel Serverless Function for Terminal49 MCP Server
 * Uses StreamableHTTPServerTransport for MCP protocol
 *
 * Endpoint: POST /api/mcp
 */

import '../packages/mcp/src/instrument.js';
import type { IncomingMessage, ServerResponse } from 'node:http';
import { randomUUID, timingSafeEqual } from 'node:crypto';
import {
  createMcpHandler,
  type McpHttpHandler,
} from '@modelcontextprotocol/server';
import { toNodeHandler } from '@modelcontextprotocol/node';
import * as Sentry from '@sentry/node';
import { createTerminal49McpServer } from '../packages/mcp/src/server.js';
import { CALL_BUDGET_MS } from '../packages/mcp/src/tools/record-writes.js';
import { flushPostHogEvents } from '../packages/mcp/src/posthog.js';
import { captureMcpException } from '../packages/mcp/src/sentry.js';
import { protectedResourceMetadataUrl } from '../packages/mcp/src/resource.js';
import { logMcpEvent } from '../packages/mcp/src/logging.js';
import type { McpCredentialType } from '../packages/mcp/src/tools/context.js';
import type { ToolSelection } from '../packages/mcp/src/tools/registry.js';
import {
  READ_ONLY_HEADER,
  resolveToolSelection,
  ToolSelectionRequestError,
  TOOLSETS_HEADER,
} from '../packages/mcp/src/toolsets.js';

type RequestLike = {
  method?: string;
  headers: IncomingMessage['headers'];
  body?: unknown;
} & IncomingMessage;

type JsonResponse = {
  error: string | { code: number; message: string };
  message?: string;
  jsonrpc?: string;
  id?: string | number | null;
};

type ResponseLike = {
  headersSent: boolean;
  status(code: number): ResponseLike;
  json(payload: JsonResponse): void;
  setHeader(name: string, value: string): void;
  end(): void;
  on(event: 'close' | 'finish', listener: () => void): void;
} & ServerResponse;

const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;

function setCorsHeaders(res: ResponseLike): void {
  res.setHeader('Access-Control-Allow-Origin', '*');
  res.setHeader('Access-Control-Allow-Methods', 'POST, OPTIONS');
  res.setHeader(
    'Access-Control-Allow-Headers',
    `Content-Type, Authorization, X-Account-ID, X-T49-Credential-Type, ${TOOLSETS_HEADER}, ${READ_ONLY_HEADER}, MCP-Protocol-Version, Mcp-Method, Mcp-Name, Mcp-Session-Id`,
  );
}

function getHeaderValue(
  value: string | string[] | undefined,
): string | undefined {
  if (Array.isArray(value)) {
    return value[0];
  }

  return value;
}

type AuthorizationToken = {
  scheme?: 'Bearer' | 'Token';
  token?: string;
  source?: 'authorization';
};

function extractAuthorizationToken(
  authorizationHeader: string | undefined,
): AuthorizationToken {
  if (authorizationHeader?.trim()) {
    const trimmed = authorizationHeader.trim();
    const authMatch = trimmed.match(/^(bearer|token)\s+(.+)$/i);
    if (authMatch?.[2]) {
      const token = authMatch[2].trim();
      if (token.length > 0) {
        const scheme =
          authMatch[1].toLowerCase() === 'bearer' ? 'Bearer' : 'Token';
        return { scheme, token, source: 'authorization' };
      }
    }
  }

  return {};
}

type ResolvedTerminal49Auth = {
  apiToken: string;
  accountId?: string;
  authSource: 'authorization' | 'environment' | 'workos_mcp';
  credentialType: McpCredentialType;
};

type ConnectedClientResolutionResponse = {
  data?: {
    attributes?: {
      access_token?: string;
      account_id?: string;
    };
  };
  error?: string;
};

type UnauthorizedReason = 'missing_credentials' | 'invalid_token';

function oauthConfigured(): boolean {
  return Boolean(
    process.env.WORKOS_AUTHORIZATION_SERVER_URL?.trim() ||
    process.env.WORKOS_ISSUER?.trim(),
  );
}

function wwwAuthenticateHeader(
  req: RequestLike,
  reason: UnauthorizedReason,
): string {
  const parts = ['Bearer realm="mcp"'];

  // RFC 6750 §3.1: include an error code only when a token was actually
  // presented and rejected; omit it when the client sent no credentials.
  if (reason === 'invalid_token') {
    parts.push('error="invalid_token"');
    parts.push('error_description="The access token is invalid or expired"');
  }

  // Only advertise OAuth discovery when the WorkOS resolver path is actually
  // active: AuthKit enabled AND the authorization server configured. If AuthKit
  // is off, a Bearer token isn't resolved (it's treated as a passthrough key), so
  // an OAuth-aware client would complete the WorkOS flow and then loop with a
  // token the handler won't honor. The PRM endpoint also 500s without WORKOS_*.
  if (authKitMcpEnabled() && oauthConfigured()) {
    parts.push(`resource_metadata="${protectedResourceMetadataUrl(req)}"`);
  }

  return parts.join(', ');
}

function setUnauthorizedChallenge(
  res: ResponseLike,
  req: RequestLike,
  reason: UnauthorizedReason,
): void {
  res.setHeader('WWW-Authenticate', wwwAuthenticateHeader(req, reason));
}

function authKitMcpEnabled(): boolean {
  return process.env.T49_MCP_AUTHKIT_ENABLED === 'true';
}

function resolveEndpointUrl(): string {
  const apiBaseUrl =
    process.env.T49_API_BASE_URL?.trim() || 'https://api.terminal49.com/v2';
  return `${apiBaseUrl.replace(/\/+$/, '')}/connected-clients/resolve`;
}

type ResolveFailureKind = 'config' | 'invalid_token' | 'forbidden' | 'upstream';

class ConnectedClientResolveError extends Error {
  readonly kind: ResolveFailureKind;
  readonly upstreamStatus?: number;

  constructor(
    message: string,
    kind: ResolveFailureKind,
    upstreamStatus?: number,
  ) {
    super(message);
    this.name = 'ConnectedClientResolveError';
    this.kind = kind;
    this.upstreamStatus = upstreamStatus;
  }
}

/** Rejects with an upstream error if `signal` aborts before `work` settles. */
function untilDeadline<T>(work: Promise<T>, signal: AbortSignal): Promise<T> {
  return new Promise<T>((resolve, reject) => {
    const onAbort = () =>
      reject(
        new ConnectedClientResolveError(
          'Terminal49 connected client resolve ran past the request deadline.',
          'upstream',
        ),
      );
    if (signal.aborted) {
      onAbort();
      return;
    }
    signal.addEventListener('abort', onAbort, { once: true });
    work
      .then(resolve, reject)
      .finally(() => signal.removeEventListener('abort', onAbort));
  });
}

async function resolveConnectedClientToken(
  token: string,
  requestId: string,
  deadlineAt: number,
): Promise<{ apiToken: string; accountId: string }> {
  const resolveSecret =
    process.env.T49_CONNECTED_CLIENTS_RESOLVE_SECRET?.trim() ||
    process.env.T49_MCP_RESOLVE_SECRET?.trim();
  if (!resolveSecret) {
    throw new ConnectedClientResolveError(
      'T49_CONNECTED_CLIENTS_RESOLVE_SECRET must be set when AuthKit MCP auth is enabled.',
      'config',
    );
  }

  // Sign-in counts against the same deadline as the tool call, so a slow
  // resolver cannot push the request past the function limit.
  const deadline = new AbortController();
  const timer = setTimeout(
    () => deadline.abort(),
    Math.max(deadlineAt - Date.now(), 0),
  );
  let response: Response;
  let payload: ConnectedClientResolutionResponse = {};
  try {
    try {
      response = await untilDeadline(
        fetch(resolveEndpointUrl(), {
          method: 'POST',
          headers: {
            'Content-Type': 'application/json',
            'X-T49-Connected-Clients-Resolve-Secret': resolveSecret,
            'X-Request-Id': requestId,
          },
          body: JSON.stringify({ access_token: token }),
          signal: deadline.signal,
        }),
        deadline.signal,
      );
    } catch (error) {
      if (error instanceof ConnectedClientResolveError) throw error;
      const err = asError(error);
      throw new ConnectedClientResolveError(
        `Terminal49 connected client resolve request failed: ${err.message}`,
        'upstream',
      );
    }

    try {
      // SAFETY: The fields read below are optional and validated before use.
      payload = (await untilDeadline(
        response.json(),
        deadline.signal,
      )) as ConnectedClientResolutionResponse;
    } catch (error) {
      if (error instanceof ConnectedClientResolveError) throw error;
      payload = {};
    }
  } finally {
    clearTimeout(timer);
  }

  if (!response.ok) {
    // A 401 means the credential itself is invalid. A 403 means WorkOS auth
    // succeeded but Terminal49 denied account access (for example, a rollout
    // gate); converting that to 401 makes clients discard a valid grant and
    // loop through OAuth. Other failures are retryable upstream errors.
    const kind: ResolveFailureKind =
      response.status === 401
        ? 'invalid_token'
        : response.status === 403
          ? 'forbidden'
          : 'upstream';
    throw new ConnectedClientResolveError(
      payload.error ||
        `Terminal49 connected client resolve failed with ${response.status}`,
      kind,
      response.status,
    );
  }

  const accessToken = payload.data?.attributes?.access_token;
  const accountId = payload.data?.attributes?.account_id;
  if (!accessToken || !accountId) {
    throw new ConnectedClientResolveError(
      'Terminal49 connected client resolve response is missing access_token or account_id.',
      'upstream',
    );
  }

  return { apiToken: `Bearer ${accessToken}`, accountId };
}

function isMatchingClientSecret(
  providedToken: string,
  expectedSecret: string,
): boolean {
  const providedBuffer = Buffer.from(providedToken);
  const expectedBuffer = Buffer.from(expectedSecret);

  if (providedBuffer.length !== expectedBuffer.length) {
    return false;
  }

  return timingSafeEqual(providedBuffer, expectedBuffer);
}

function buildRequestId(): string {
  // Caller-controlled request IDs can contain tokens or customer identifiers.
  // Generate an internal correlation ID so the safe request_id log exemption
  // never forwards arbitrary header content.
  return randomUUID();
}

function asError(cause: unknown): Error {
  return cause instanceof Error ? cause : new Error(String(cause));
}

type LifecycleDetail = string | number | string[] | undefined;

function logLifecycle(
  event: string,
  requestId: string,
  details: Record<string, LifecycleDetail> = {},
): void {
  logMcpEvent({
    event,
    request_id: requestId,
    timestamp: new Date().toISOString(),
    ...details,
  });
}

function parseAllowList(value: string | undefined): Set<string> {
  if (!value) {
    return new Set();
  }

  return new Set(
    value
      .split(',')
      .map((item) => item.trim())
      .filter((item) => item.length > 0),
  );
}

function isAllowedHost(
  hostHeader: string | undefined,
  allowList: Set<string>,
): boolean {
  if (allowList.size === 0) {
    return true;
  }

  if (!hostHeader) {
    return false;
  }

  const hostname = hostHeader.split(':')[0];
  return allowList.has(hostHeader) || allowList.has(hostname);
}

function isAllowedOrigin(
  originHeader: string | undefined,
  hostHeader: string | undefined,
  allowList: Set<string>,
): boolean {
  if (!originHeader) {
    // Non-browser clients commonly omit Origin.
    return true;
  }

  let origin: URL;

  try {
    origin = new URL(originHeader);
  } catch {
    return false;
  }

  if (allowList.size > 0) {
    return allowList.has(origin.origin) || allowList.has(origin.hostname);
  }

  const localHosts = new Set(['localhost', '127.0.0.1', '::1']);
  if (localHosts.has(origin.hostname)) {
    return true;
  }

  if (!hostHeader) {
    return false;
  }

  const requestHost = hostHeader.split(':')[0];
  return origin.hostname === requestHost;
}

function validateRequestSecurity(req: RequestLike, res: ResponseLike): boolean {
  const hostHeader = getHeaderValue(req.headers.host);
  const originHeader = getHeaderValue(req.headers.origin);
  const allowedHosts = parseAllowList(process.env.T49_MCP_ALLOWED_HOSTS);
  const allowedOrigins = parseAllowList(process.env.T49_MCP_ALLOWED_ORIGINS);

  if (!isAllowedHost(hostHeader, allowedHosts)) {
    setCorsHeaders(res);
    res.status(403).json({
      error: 'Forbidden',
      message: `Invalid Host header: ${hostHeader ?? '(missing)'}`,
    });
    return false;
  }

  if (!isAllowedOrigin(originHeader, hostHeader, allowedOrigins)) {
    setCorsHeaders(res);
    res.status(403).json({
      error: 'Forbidden',
      message: `Invalid Origin header: ${originHeader ?? '(missing)'}`,
    });
    return false;
  }

  return true;
}

/**
 * Main handler for Vercel serverless function
 */
export default async function handler(
  req: RequestLike,
  res: ResponseLike,
): Promise<void> {
  const requestId = buildRequestId();
  // vercel.json caps this function at 30s from the request, auth included.
  const deadlineAt = Date.now() + CALL_BUDGET_MS;
  setCorsHeaders(res);
  logLifecycle('mcp.request.start', requestId, {
    method: req.method ?? 'UNKNOWN',
  });

  if (!validateRequestSecurity(req, res)) {
    logLifecycle('mcp.request.rejected', requestId, {
      reason: 'request_security_validation_failed',
    });
    return;
  }

  // Handle CORS preflight
  if (req.method === 'OPTIONS') {
    res.status(200).end();
    logLifecycle('mcp.request.complete', requestId, { reason: 'preflight' });
    return;
  }

  // Only accept POST requests
  if (req.method !== 'POST') {
    setCorsHeaders(res);
    res.status(405).json({
      error: 'Method not allowed',
      message: 'Only POST requests are accepted',
    });
    logLifecycle('mcp.request.complete', requestId, {
      reason: 'method_not_allowed',
      method: req.method,
    });
    return;
  }

  let mcpHandler: McpHttpHandler | undefined;
  let cleanupPromise: Promise<void> | null = null;
  let shouldFlushSentry = false;

  const runCleanup = (reason: string): Promise<void> => {
    if (cleanupPromise) {
      return cleanupPromise;
    }

    cleanupPromise = (async () => {
      const cleanupErrors: string[] = [];
      logLifecycle('mcp.request.cleanup.start', requestId, { reason });

      if (mcpHandler) {
        try {
          await mcpHandler.close();
        } catch (error) {
          const err = asError(error);
          cleanupErrors.push(`handler.close: ${err.message}`);
        }
      }

      if (cleanupErrors.length > 0) {
        logLifecycle('mcp.request.cleanup.error', requestId, {
          reason,
          errors: cleanupErrors,
        });
        return;
      }

      logLifecycle('mcp.request.cleanup.complete', requestId, { reason });
    })();

    return cleanupPromise;
  };

  const scheduleCleanup = (reason: string): void => {
    void runCleanup(reason);
  };

  try {
    // Require caller Authorization; supports both `Bearer <token>` and `Token <token>`.
    // Use T49_API_TOKEN only as upstream credential, never as client-auth fallback.
    const authHeader = getHeaderValue(req.headers.authorization);
    const resolvedAuth = extractAuthorizationToken(authHeader);
    const callerToken = resolvedAuth.token;

    if (!callerToken) {
      setCorsHeaders(res);
      setUnauthorizedChallenge(res, req, 'missing_credentials');
      res.status(401).json({
        error: 'Unauthorized',
        message:
          'Missing valid Authorization header. Use `Authorization: Bearer <token>` or `Authorization: Token <token>`.',
      });
      logLifecycle('mcp.request.complete', requestId, {
        reason: 'missing_authorization',
      });
      return;
    }

    const requestedAccountId =
      resolvedAuth.scheme === 'Token'
        ? getHeaderValue(req.headers['x-account-id'])
        : undefined;
    const credentialType =
      resolvedAuth.scheme === 'Token'
        ? getHeaderValue(req.headers['x-t49-credential-type'])
        : undefined;
    if (credentialType && credentialType !== 'agent') {
      res.status(400).json({
        error: 'Bad Request',
        message: 'X-T49-Credential-Type is invalid.',
      });
      logLifecycle('mcp.request.complete', requestId, {
        reason: 'invalid_credential_type',
      });
      return;
    }
    if (requestedAccountId && !UUID.test(requestedAccountId)) {
      res.status(400).json({
        error: 'Bad Request',
        message: 'X-Account-ID must be a UUID.',
      });
      logLifecycle('mcp.request.complete', requestId, {
        reason: 'invalid_account_id',
      });
      return;
    }
    if (credentialType === 'agent' && !requestedAccountId) {
      res.status(400).json({
        error: 'Bad Request',
        message: 'X-Account-ID is required for a WorkOS agent credential.',
      });
      logLifecycle('mcp.request.complete', requestId, {
        reason: 'missing_account_id',
      });
      return;
    }

    const configuredApiToken = process.env.T49_API_TOKEN?.trim();
    const configuredClientSecret = process.env.T49_MCP_CLIENT_SECRET?.trim();
    let resolvedTerminal49Auth: ResolvedTerminal49Auth = {
      apiToken:
        credentialType === 'agent' ? `Bearer ${callerToken}` : callerToken,
      accountId: credentialType === 'agent' ? requestedAccountId : undefined,
      authSource: resolvedAuth.source ?? 'authorization',
      credentialType: credentialType === 'agent' ? 'agent' : 'api_key',
    };

    // Intentional: when AuthKit is enabled, `Bearer` is reserved for WorkOS OAuth
    // access tokens (resolved below). API keys authenticate with the `Token`
    // scheme (passthrough), which is what the docs instruct. Existing Bearer
    // API-key clients must migrate to `Token` before AuthKit is enabled — see
    // packages/mcp/WORKOS_MCP_SETUP.md (rollout note).
    if (authKitMcpEnabled() && resolvedAuth.scheme === 'Bearer') {
      try {
        const resolved = await resolveConnectedClientToken(
          callerToken,
          requestId,
          deadlineAt,
        );
        resolvedTerminal49Auth = {
          apiToken: resolved.apiToken,
          accountId: resolved.accountId,
          authSource: 'workos_mcp',
          credentialType: 'user',
        };
      } catch (error) {
        const err = asError(error);
        const kind: ResolveFailureKind =
          err instanceof ConnectedClientResolveError ? err.kind : 'upstream';
        const upstreamStatus =
          err instanceof ConnectedClientResolveError
            ? err.upstreamStatus
            : undefined;
        setCorsHeaders(res);
        // Keep the detailed reason in the server log (correlated by request_id);
        // return a generic, category-appropriate response so internals never leak.
        logLifecycle('mcp.request.complete', requestId, {
          reason: 'connected_client_resolve_failed',
          kind,
          upstream_status: upstreamStatus,
          message: err.message,
        });
        if (kind === 'invalid_token') {
          setUnauthorizedChallenge(res, req, 'invalid_token');
          res.status(401).json({
            error: 'Unauthorized',
            message: 'Invalid or expired token.',
          });
        } else if (kind === 'forbidden') {
          res.status(403).json({
            error: 'Forbidden',
            message: 'Terminal49 access is not enabled for this account.',
          });
        } else if (kind === 'config') {
          res.status(500).json({
            error: 'Server misconfiguration',
            message: 'Authorization is not configured correctly.',
          });
        } else {
          // Upstream/transient: do NOT send a 401 challenge — that tells clients
          // their token is bad and triggers re-auth loops. 502 invites a retry.
          res.status(502).json({
            error: 'Bad Gateway',
            message:
              'Authorization service is temporarily unavailable. Please retry.',
          });
        }
        return;
      }
    } else if (configuredApiToken) {
      if (!configuredClientSecret) {
        setCorsHeaders(res);
        res.status(500).json({
          error: 'Server misconfiguration',
          message:
            'T49_MCP_CLIENT_SECRET must be set when T49_API_TOKEN is configured.',
        });
        logLifecycle('mcp.request.complete', requestId, {
          reason: 'missing_client_secret',
        });
        return;
      }

      if (!isMatchingClientSecret(callerToken, configuredClientSecret)) {
        setCorsHeaders(res);
        setUnauthorizedChallenge(res, req, 'invalid_token');
        res.status(401).json({
          error: 'Unauthorized',
          message: 'Invalid client credentials.',
        });
        logLifecycle('mcp.request.complete', requestId, {
          reason: 'invalid_client_secret',
        });
        return;
      }

      resolvedTerminal49Auth = {
        apiToken: configuredApiToken,
        authSource: 'environment',
        credentialType: 'shared_token',
      };
    }

    let toolSelection: ToolSelection;
    try {
      toolSelection = resolveToolSelection({
        env: process.env,
        credentialType: resolvedTerminal49Auth.credentialType,
        toolsetsHeader: getHeaderValue(req.headers['x-t49-mcp-toolsets']),
        readOnlyHeader: getHeaderValue(req.headers['x-t49-mcp-read-only']),
      });
    } catch (error) {
      if (!(error instanceof ToolSelectionRequestError)) {
        throw error;
      }
      res.status(400).json({ error: 'Bad Request', message: error.message });
      logLifecycle('mcp.request.complete', requestId, {
        reason: 'invalid_tool_selection',
      });
      return;
    }

    logLifecycle('mcp.request.auth', requestId, {
      auth_source: resolvedTerminal49Auth.authSource,
      credential_type: resolvedTerminal49Auth.credentialType,
      toolsets: [...toolSelection.toolsets],
      read_only: String(toolSelection.readOnly),
    });

    setCorsHeaders(res);

    const observeMcpError = (error: Error): void => {
      captureMcpException(error);
      shouldFlushSentry = true;
      logLifecycle('mcp.request.error', requestId, {
        error: error.name,
        message: error.message,
      });
    };

    // The v2 HTTP entry serves the 2026-07-28 per-request protocol and keeps
    // the established stateless 2025-era path for older clients.
    mcpHandler = createMcpHandler(
      () =>
        createTerminal49McpServer(
          resolvedTerminal49Auth.apiToken,
          process.env.T49_API_BASE_URL,
          resolvedTerminal49Auth.accountId,
          {
            transport: 'http',
            authSource: resolvedTerminal49Auth.authSource,
            credentialType: resolvedTerminal49Auth.credentialType,
            toolsets: toolSelection.toolsets,
            readOnly: toolSelection.readOnly,
            writeDeadlineAt: deadlineAt,
          },
        ),
      {
        legacy: 'stateless',
        responseMode: 'json',
        onerror: observeMcpError,
      },
    );
    const nodeHandler = toNodeHandler(mcpHandler, {
      onerror: observeMcpError,
    });

    // Clean up on response lifecycle and also in finally to guarantee closure.
    res.on('close', () => {
      scheduleCleanup('response_close');
    });
    res.on('finish', () => {
      scheduleCleanup('response_finish');
    });

    await nodeHandler(req, res, req.body);
    logLifecycle('mcp.request.complete', requestId, { reason: 'handled' });
  } catch (error) {
    const err = asError(error);
    captureMcpException(err);
    shouldFlushSentry = true;
    logLifecycle('mcp.request.error', requestId, {
      error: err.name,
      message: err.message,
    });
    if (!res.headersSent) {
      setCorsHeaders(res);
      // The real error is logged above (correlated by request_id). Never echo
      // err.message to the client — it can carry upstream URLs, tokens, or
      // stack detail.
      res.status(500).json({
        jsonrpc: '2.0',
        error: {
          code: -32603,
          message: 'Internal server error',
        },
        id: null,
      });
    }
  } finally {
    await runCleanup('finally');
    if (shouldFlushSentry || Sentry.isInitialized()) {
      await Sentry.flush(2000).catch(() => undefined);
    }
    // Vercel freezes the function the moment the response is sent, so any batch
    // still queued in the PostHog client would be dropped (or leak into the next
    // invocation on a reused instance). Awaiting the flush here mirrors the
    // Sentry.flush() above: one batched request per invocation. Deliberately
    // preferred over `waitUntil`, which would add a @vercel/functions
    // dependency for the same guarantee. No-ops when PostHog is unconfigured.
    await flushPostHogEvents();
  }
}