sh-mcp/packages/shared/src/http.ts

/**
 * Express host mounting both universal interfaces over one tool registry.
 *
 * Routes (build-plan §2.1, design.md §2.5):
 *   - `POST /mcp` (+ GET/DELETE) — MCP over Streamable HTTP. Authenticated.
 *   - `GET  /openapi.json`       — full OpenAPI 3.1 document. Unauthenticated.
 *   - `POST /tools/:name`        — one-shot tool call. Authenticated.
 *   - `GET  /healthz`            — liveness. Unauthenticated.
 *
 * Both `/mcp` and `/tools/:name` require a valid token — there is never an
 * unauthenticated tool path (design.md §2.5). Auth runs `authProvider.
 * authenticate(req)`; on `AuthError` → 401, otherwise the resolved `AuthContext`
 * flows into the SAME `executeTool` dispatch path for both interfaces.
 *
 * No listener is created here: `createApp` only builds. The server entrypoint
 * calls `.listen()` — keeping `@sh-mcp/shared` import-side-effect free
 * (build-plan §2.1, §7 "No I/O at import time").
 */

import express, { type Express, type Request, type Response, type NextFunction } from 'express';
import { rateLimit, type RateLimitRequestHandler } from 'express-rate-limit';
import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';

import { AuthError } from './cognito-auth.js';
import { ScopeError } from './auth.js';
import { RateLimitError } from './rate-limit.js';
import {
  executeTool,
  InputValidationError,
  UnknownToolError,
  type DispatchDeps,
} from './dispatch.js';
import { createMcpServer, type McpServerInfo } from './mcp.js';
import { buildOpenApiDocument, type BuildOpenApiOptions } from './openapi.js';
import { visibleTools } from './visibility.js';
import { ToolRegistry } from './registry.js';
import type { AuthProvider } from './auth.js';
import type { AuthContext } from './types.js';

export interface CreateAppOptions {
  registry: ToolRegistry;
  authProvider: AuthProvider;
  deps: DispatchDeps;
  /** MCP handshake identity + OpenAPI `info`/`servers`. */
  mcpInfo: McpServerInfo;
  openApi: BuildOpenApiOptions;
  /**
   * Per-IP edge rate limit for the authenticated routes (`/mcp`, `/tools/:name`).
   * This is a coarse abuse/DoS guard that runs BEFORE `authProvider.authenticate`
   * — so it throttles unauthenticated and invalid-token floods before the (more
   * expensive) JWT verification and dispatch. It complements, and does not
   * replace, the per-`sub` + per-tool limiter inside `executeTool` (design.md
   * §7.3). Defaults: 120 requests / 60s / IP. In production the API Gateway/WAF
   * is the first edge; this is defense-in-depth.
   */
  edgeRateLimit?: { windowMs: number; limit: number };
}

/** Express `Request` augmented with the authenticated context. */
interface AuthedRequest extends Request {
  authContext?: AuthContext;
}

/**
 * Build (but do not start) the Express app hosting MCP + OpenAPI for one server.
 */
export function createApp(options: CreateAppOptions): Express {
  const { registry, authProvider, deps, mcpInfo, openApi } = options;
  const app = express();
  app.use(express.json());

  // --- Per-IP edge rate limiter for the authenticated routes ---
  // Runs ahead of auth so request floods are throttled before JWT verification
  // and dispatch. Keyed by client IP (express-rate-limit default). Returns the
  // same 429 shape adapters use elsewhere; standard RateLimit headers, no legacy.
  const { windowMs = 60_000, limit = 120 } = options.edgeRateLimit ?? {};
  const edgeRateLimit: RateLimitRequestHandler = rateLimit({
    windowMs,
    limit,
    standardHeaders: 'draft-7',
    legacyHeaders: false,
    handler: (_req: Request, res: Response) => {
      res.status(429).json({ error: 'rate_limited' });
    },
  });

  // --- Unauthenticated liveness ---
  app.get('/healthz', (_req: Request, res: Response) => {
    res.status(200).json({ status: 'ok' });
  });

  // --- Unauthenticated full spec ---
  // The static document advertises ALL tools (it is the published contract);
  // per-call scope enforcement still gates execution server-side.
  app.get('/openapi.json', (_req: Request, res: Response) => {
    res.status(200).json(buildOpenApiDocument(registry, openApi));
  });

  // --- Auth middleware for tool paths + MCP ---
  const authenticate = async (
    req: AuthedRequest,
    res: Response,
    next: NextFunction,
  ): Promise<void> => {
    try {
      req.authContext = await authProvider.authenticate(req);
      next();
    } catch (err) {
      if (err instanceof AuthError) {
        res.status(401).json({ error: 'unauthorized', code: err.code });
        return;
      }
      // Unexpected auth failure — do not leak details.
      res.status(401).json({ error: 'unauthorized' });
    }
  };

  // --- MCP over Streamable HTTP ---
  const handleMcp = async (req: AuthedRequest, res: Response): Promise<void> => {
    const ctx = req.authContext!;
    // Stateless transport: a fresh server+transport per request (no session
    // store needed for this PR). sessionIdGenerator: undefined = stateless mode.
    const server = createMcpServer(registry, ctx, deps, mcpInfo);
    const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
    res.on('close', () => {
      void transport.close();
      void server.close();
    });
    await server.connect(transport);
    await transport.handleRequest(req, res, req.body);
  };
  app.post('/mcp', edgeRateLimit, authenticate, (req, res) => void handleMcp(req, res));
  app.get('/mcp', edgeRateLimit, authenticate, (req, res) => void handleMcp(req, res));
  app.delete('/mcp', edgeRateLimit, authenticate, (req, res) => void handleMcp(req, res));

  // --- One-shot OpenAPI tool call ---
  app.post('/tools/:name', edgeRateLimit, authenticate, (req: AuthedRequest, res: Response) => {
    const ctx = req.authContext!;
    const rawName = req.params['name'];
    const name = Array.isArray(rawName) ? (rawName[0] ?? '') : (rawName ?? '');
    void executeTool(registry, ctx, name, req.body ?? {}, deps)
      .then((output) => res.status(200).json(output))
      .catch((err: unknown) => sendToolError(res, err));
  });

  return app;
}

/** Translate dispatch errors to HTTP status codes (no stack traces / secrets). */
function sendToolError(res: Response, err: unknown): void {
  if (err instanceof UnknownToolError) {
    res.status(404).json({ error: 'unknown_tool', tool: err.tool });
    return;
  }
  if (err instanceof ScopeError) {
    res.status(403).json({ error: 'forbidden', requiredScope: err.requiredScope });
    return;
  }
  if (err instanceof InputValidationError) {
    res.status(400).json({ error: 'invalid_input', issues: err.issues });
    return;
  }
  if (err instanceof RateLimitError) {
    if (err.retryAfterMs != null) {
      res.setHeader('Retry-After', Math.ceil(err.retryAfterMs / 1000).toString());
    }
    res.status(429).json({ error: 'rate_limited' });
    return;
  }
  // Generic handler failure — never echo the underlying message.
  res.status(500).json({ error: 'internal_error' });
}

/** Re-export so server entrypoints can construct registries/visibility. */
export { ToolRegistry, visibleTools };