@absol-labs/agent 0.1.0

package/src/mcp/http.ts

@@ -0,0 +1,620 @@
+import { createHash, randomUUID, timingSafeEqual } from "node:crypto";
+import {
+  createServer,
+  type IncomingMessage,
+  type Server,
+  type ServerResponse,
+} from "node:http";
+import type { AddressInfo } from "node:net";
+
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
+import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
+
+import {
+  createVerifiedStreamMcpServer,
+  createVerifiedStreamMcpServerOptionsFromEnv,
+  type VerifiedStreamMcpServerOptions,
+  type VerifiedStreamMcpServerRuntime,
+} from "./server.js";
+
+/**
+ * Hosted, multi-tenant MCP transport over Streamable HTTP.
+ *
+ * This serves the SAME Metrik agent MCP tool set as the stdio transport
+ * (`mcp/stdio.ts`) over the MCP SDK's `StreamableHTTPServerTransport`, so the
+ * agent lane can be hosted as a remote endpoint.
+ *
+ * Security model (fail-closed):
+ * - Every request MUST carry `Authorization: Bearer <token>`. Requests without
+ *   a valid bearer token are rejected with 401 BEFORE any MCP session is
+ *   created or any tool executes.
+ * - Tokens are compared in constant time (SHA-256 + `timingSafeEqual`) and are
+ *   never logged.
+ * - Each authenticated caller maps to its OWN tenant context — its own
+ *   wallet-backed agent client and stream registry — so one caller can never
+ *   drive another caller's funds or observe another caller's streams.
+ * - A caller may only use MCP sessions bound to its own tenant; presenting
+ *   another tenant's session id is rejected (403).
+ * - If zero tenants (tokens) are configured, the transport refuses to start.
+ */
+
+/** Maximum accepted request body size (bytes) — bounds memory per request. */
+const MAX_BODY_BYTES = 4 * 1024 * 1024;
+/** Header carrying the Streamable HTTP session id (per the MCP spec). */
+const SESSION_ID_HEADER = "mcp-session-id";
+
+/**
+ * A single authenticated tenant: a bearer token plus the wallet/mandate-scoped
+ * MCP server options used to build that tenant's server instances.
+ */
+export interface HostedMcpTenant {
+  /** Stable, human-readable tenant identifier (used only for routing/logging). */
+  readonly id: string;
+  /** The tenant's secret bearer token. Never logged. */
+  readonly token: string;
+  /**
+   * The tenant's isolated MCP server options (its own agent client + registry).
+   * A fresh `McpServer` is built from these for each of the tenant's sessions.
+   */
+  readonly options: VerifiedStreamMcpServerOptions;
+}
+
+/** Resolves a presented bearer token to a tenant, or `null` when invalid. */
+export interface TenantResolver {
+  authenticate(token: string): HostedMcpTenant | null;
+}
+
+function sha256(value: string): Buffer {
+  return createHash("sha256").update(value, "utf8").digest();
+}
+
+/**
+ * Constant-time, env-backed tenant resolver.
+ *
+ * Tokens are pre-hashed with SHA-256 (fixed 32-byte width) so every comparison
+ * uses `timingSafeEqual` on equal-length buffers, and the loop always visits
+ * every tenant with no early exit — neither the presented token's length nor
+ * which tenant matched is observable via timing.
+ */
+export class StaticTenantResolver implements TenantResolver {
+  private readonly entries: readonly {
+    readonly tenant: HostedMcpTenant;
+    readonly tokenHash: Buffer;
+  }[];
+
+  constructor(tenants: readonly HostedMcpTenant[]) {
+    if (tenants.length === 0) {
+      throw new Error(
+        "hosted MCP: no tenants configured — refusing to start (fail-closed)",
+      );
+    }
+    const seenIds = new Set<string>();
+    const seenTokens = new Set<string>();
+    for (const tenant of tenants) {
+      if (tenant.token.length === 0) {
+        throw new Error(
+          `hosted MCP: tenant "${tenant.id}" has an empty token (fail-closed)`,
+        );
+      }
+      if (seenIds.has(tenant.id)) {
+        throw new Error(`hosted MCP: duplicate tenant id "${tenant.id}"`);
+      }
+      if (seenTokens.has(tenant.token)) {
+        throw new Error(
+          `hosted MCP: duplicate token for tenant "${tenant.id}"`,
+        );
+      }
+      seenIds.add(tenant.id);
+      seenTokens.add(tenant.token);
+    }
+    this.entries = tenants.map((tenant) => ({
+      tenant,
+      tokenHash: sha256(tenant.token),
+    }));
+  }
+
+  authenticate(token: string): HostedMcpTenant | null {
+    const presented = sha256(token);
+    let match: HostedMcpTenant | null = null;
+    for (const entry of this.entries) {
+      // timingSafeEqual on equal-length buffers; visit all entries so timing
+      // does not reveal which (if any) tenant matched.
+      if (timingSafeEqual(presented, entry.tokenHash)) {
+        match = entry.tenant;
+      }
+    }
+    return match;
+  }
+}
+
+export interface HostedMcpHttpServerOptions {
+  readonly resolver: TenantResolver;
+  /** HTTP path the MCP endpoint is served on. Default `/mcp`. */
+  readonly path?: string;
+  /**
+   * Allowed CORS origins. `["*"]` allows any origin. When omitted, no
+   * cross-origin `Access-Control-Allow-Origin` header is emitted (same-origin
+   * / non-browser clients only).
+   */
+  readonly allowedOrigins?: readonly string[];
+  /** Session id generator. Default: cryptographically-random UUID v4. */
+  readonly generateSessionId?: () => string;
+}
+
+interface HostedSession {
+  readonly transport: StreamableHTTPServerTransport;
+  readonly runtime: VerifiedStreamMcpServerRuntime;
+  readonly tenantId: string;
+}
+
+export interface HostedMcpHttpServer {
+  readonly httpServer: Server;
+  /** Bind and start listening. Resolves with the actual bound address. */
+  listen(port: number, host?: string): Promise<{ port: number; host: string }>;
+  /** Stop accepting requests and tear down all live sessions. */
+  close(): Promise<void>;
+}
+
+/**
+ * Creates (but does not start) a hosted multi-tenant MCP HTTP server.
+ *
+ * Use {@link HostedMcpHttpServer.listen} to bind it. The returned server is
+ * suitable for tests (bind to port 0 for an ephemeral port) and for
+ * deployment (bind to `0.0.0.0`/`PORT`).
+ */
+export function createHostedMcpHttpServer(
+  options: HostedMcpHttpServerOptions,
+): HostedMcpHttpServer {
+  const path = options.path ?? "/mcp";
+  const allowedOrigins = options.allowedOrigins;
+  const generateSessionId = options.generateSessionId ?? (() => randomUUID());
+  const sessions = new Map<string, HostedSession>();
+
+  const httpServer = createServer((req, res) => {
+    handleHttpRequest(req, res, {
+      path,
+      allowedOrigins,
+      generateSessionId,
+      resolver: options.resolver,
+      sessions,
+    }).catch((error) => {
+      // Never leak internal error detail to the client.
+      logError("unhandled request error", error);
+      if (!res.headersSent) {
+        writeJsonRpcError(res, 500, -32603, "internal error");
+      } else {
+        res.end();
+      }
+    });
+  });
+
+  return {
+    httpServer,
+    listen: (port, host = "0.0.0.0") =>
+      new Promise((resolve, reject) => {
+        const onError = (error: Error) => reject(error);
+        httpServer.once("error", onError);
+        httpServer.listen(port, host, () => {
+          httpServer.removeListener("error", onError);
+          const address = httpServer.address() as AddressInfo;
+          resolve({ port: address.port, host });
+        });
+      }),
+    close: async () => {
+      // Closing the runtime cascades to its transport via the SDK lifecycle
+      // linkage; the transport's onclose then drops it from the map.
+      await Promise.all(
+        Array.from(sessions.values()).map((session) =>
+          session.runtime.close().catch(() => undefined),
+        ),
+      );
+      sessions.clear();
+      await new Promise<void>((resolve, reject) => {
+        httpServer.close((error) => (error ? reject(error) : resolve()));
+      });
+    },
+  };
+}
+
+interface RequestContext {
+  readonly path: string;
+  readonly allowedOrigins: readonly string[] | undefined;
+  readonly generateSessionId: () => string;
+  readonly resolver: TenantResolver;
+  readonly sessions: Map<string, HostedSession>;
+}
+
+async function handleHttpRequest(
+  req: IncomingMessage,
+  res: ServerResponse,
+  ctx: RequestContext,
+): Promise<void> {
+  applyCorsHeaders(req, res, ctx.allowedOrigins);
+
+  // CORS preflight — no auth, no side effects.
+  if (req.method === "OPTIONS") {
+    res.writeHead(204).end();
+    return;
+  }
+
+  const requestUrl = new URL(req.url ?? "/", "http://localhost");
+  if (requestUrl.pathname !== ctx.path) {
+    writeJsonRpcError(res, 404, -32601, "not found");
+    return;
+  }
+
+  const method = req.method ?? "";
+  if (method !== "POST" && method !== "GET" && method !== "DELETE") {
+    res.setHeader("Allow", "POST, GET, DELETE, OPTIONS");
+    writeJsonRpcError(res, 405, -32601, "method not allowed");
+    return;
+  }
+
+  // ── Authentication gate (runs before ANY MCP session / tool executes) ──
+  const tenant = authenticateRequest(req, ctx.resolver);
+  if (tenant === null) {
+    res.setHeader("WWW-Authenticate", 'Bearer realm="metrik-agent-mcp"');
+    writeJsonRpcError(res, 401, -32001, "unauthorized");
+    return;
+  }
+
+  if (method === "POST") {
+    await handlePost(req, res, ctx, tenant);
+    return;
+  }
+
+  // GET (SSE stream) and DELETE (end session) both require an existing session.
+  const session = resolveSessionForTenant(req, res, ctx, tenant);
+  if (session === null) {
+    return;
+  }
+  await session.transport.handleRequest(req, res);
+}
+
+async function handlePost(
+  req: IncomingMessage,
+  res: ServerResponse,
+  ctx: RequestContext,
+  tenant: HostedMcpTenant,
+): Promise<void> {
+  let body: unknown;
+  try {
+    body = await readJsonBody(req);
+  } catch (error) {
+    const status = error instanceof BodyTooLargeError ? 413 : 400;
+    writeJsonRpcError(res, status, -32700, "invalid request body");
+    return;
+  }
+
+  const sessionId = headerValue(req, SESSION_ID_HEADER);
+
+  if (sessionId !== undefined) {
+    const session = resolveSessionForTenant(req, res, ctx, tenant);
+    if (session === null) {
+      return;
+    }
+    await session.transport.handleRequest(req, res, body);
+    return;
+  }
+
+  // No session id: only an `initialize` request may open a new session.
+  if (!isInitializeRequest(body)) {
+    writeJsonRpcError(
+      res,
+      400,
+      -32000,
+      "missing session id (only initialize may open a session)",
+    );
+    return;
+  }
+
+  const runtime = createVerifiedStreamMcpServer(tenant.options);
+  const transport = new StreamableHTTPServerTransport({
+    sessionIdGenerator: ctx.generateSessionId,
+    onsessioninitialized: (id) => {
+      ctx.sessions.set(id, { transport, runtime, tenantId: tenant.id });
+    },
+    onsessionclosed: (id) => {
+      ctx.sessions.delete(id);
+    },
+  });
+  // Only drop the session from the map on close. Do NOT call runtime.close()
+  // here: `mcpServer.connect` links server<->transport lifecycle, so closing
+  // the runtime already closes the transport (and vice versa). Closing one from
+  // the other's close handler would recurse infinitely.
+  transport.onclose = () => {
+    const id = transport.sessionId;
+    if (id !== undefined) {
+      ctx.sessions.delete(id);
+    }
+  };
+
+  // The SDK's StreamableHTTPServerTransport exposes onclose/onerror as
+  // getter/setter pairs typed `(() => void) | undefined`, which does not satisfy
+  // the `onclose?: () => void` optional-property shape under
+  // exactOptionalPropertyTypes. The runtime shape is fully compatible.
+  await runtime.mcpServer.connect(transport as unknown as Transport);
+  await transport.handleRequest(req, res, body);
+}
+
+/**
+ * Looks up the session named by the request's `mcp-session-id` header and
+ * enforces tenant ownership. Writes the appropriate error response and returns
+ * `null` when the session is missing (404) or owned by another tenant (403).
+ */
+function resolveSessionForTenant(
+  req: IncomingMessage,
+  res: ServerResponse,
+  ctx: RequestContext,
+  tenant: HostedMcpTenant,
+): HostedSession | null {
+  const sessionId = headerValue(req, SESSION_ID_HEADER);
+  if (sessionId === undefined) {
+    writeJsonRpcError(res, 400, -32000, "missing session id");
+    return null;
+  }
+  const session = ctx.sessions.get(sessionId);
+  if (session === undefined) {
+    writeJsonRpcError(res, 404, -32001, "unknown session");
+    return null;
+  }
+  if (session.tenantId !== tenant.id) {
+    // Tenant isolation: a caller may never touch another tenant's session.
+    writeJsonRpcError(res, 403, -32001, "forbidden");
+    return null;
+  }
+  return session;
+}
+
+function authenticateRequest(
+  req: IncomingMessage,
+  resolver: TenantResolver,
+): HostedMcpTenant | null {
+  const header = headerValue(req, "authorization");
+  if (header === undefined) {
+    return null;
+  }
+  const match = /^Bearer[ ]+(.+)$/i.exec(header.trim());
+  if (match === null) {
+    return null;
+  }
+  const token = match[1]!.trim();
+  if (token.length === 0) {
+    return null;
+  }
+  return resolver.authenticate(token);
+}
+
+function applyCorsHeaders(
+  req: IncomingMessage,
+  res: ServerResponse,
+  allowedOrigins: readonly string[] | undefined,
+): void {
+  if (allowedOrigins === undefined || allowedOrigins.length === 0) {
+    return;
+  }
+  const origin = headerValue(req, "origin");
+  const allowAny = allowedOrigins.includes("*");
+  if (allowAny) {
+    res.setHeader("Access-Control-Allow-Origin", "*");
+  } else if (origin !== undefined && allowedOrigins.includes(origin)) {
+    res.setHeader("Access-Control-Allow-Origin", origin);
+    res.setHeader("Vary", "Origin");
+  } else {
+    // Origin not allowed — emit no ACAO header (browser will block).
+    return;
+  }
+  res.setHeader("Access-Control-Allow-Methods", "POST, GET, DELETE, OPTIONS");
+  res.setHeader(
+    "Access-Control-Allow-Headers",
+    "Authorization, Content-Type, Mcp-Session-Id, Last-Event-ID, Mcp-Protocol-Version",
+  );
+  res.setHeader("Access-Control-Expose-Headers", "Mcp-Session-Id");
+  res.setHeader("Access-Control-Max-Age", "600");
+}
+
+class BodyTooLargeError extends Error {}
+
+async function readJsonBody(req: IncomingMessage): Promise<unknown> {
+  const chunks: Buffer[] = [];
+  let size = 0;
+  for await (const chunk of req) {
+    const buffer = chunk as Buffer;
+    size += buffer.length;
+    if (size > MAX_BODY_BYTES) {
+      throw new BodyTooLargeError("request body too large");
+    }
+    chunks.push(buffer);
+  }
+  const raw = Buffer.concat(chunks).toString("utf8");
+  if (raw.trim().length === 0) {
+    return undefined;
+  }
+  return JSON.parse(raw);
+}
+
+function headerValue(req: IncomingMessage, name: string): string | undefined {
+  const value = req.headers[name];
+  if (value === undefined) {
+    return undefined;
+  }
+  return Array.isArray(value) ? value[0] : value;
+}
+
+function writeJsonRpcError(
+  res: ServerResponse,
+  status: number,
+  code: number,
+  message: string,
+): void {
+  if (res.headersSent) {
+    res.end();
+    return;
+  }
+  const payload = JSON.stringify({
+    jsonrpc: "2.0",
+    error: { code, message },
+    id: null,
+  });
+  res.writeHead(status, { "Content-Type": "application/json" }).end(payload);
+}
+
+function logError(context: string, error: unknown): void {
+  // Only the message — never headers/tokens/bodies.
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(`[metrik-agent-mcp-http] ${context}: ${message}`);
+}
+
+// ── Environment configuration ────────────────────────────────────────────────
+
+/**
+ * Per-tenant configuration parsed from the hosted server environment.
+ *
+ * Each tenant carries the environment slice (`METRIK_AGENT_*`, wallet vars,
+ * optional Reclaim vars) that builds its OWN wallet-backed agent client, so
+ * tenants are fully fund-isolated from one another.
+ */
+export interface HostedMcpTenantConfig {
+  readonly id: string;
+  readonly token: string;
+  readonly env: Readonly<Record<string, string>>;
+}
+
+export interface HostedMcpServerConfig {
+  readonly host: string;
+  readonly port: number;
+  readonly path: string;
+  readonly allowedOrigins: readonly string[];
+  readonly tenants: readonly HostedMcpTenantConfig[];
+}
+
+/**
+ * Parses the hosted MCP server configuration from environment variables.
+ *
+ * Env contract:
+ * - `PORT` / `METRIK_MCP_PORT` — listen port (default 8080).
+ * - `METRIK_MCP_HOST` — bind host (default `0.0.0.0`).
+ * - `METRIK_MCP_PATH` — MCP endpoint path (default `/mcp`).
+ * - `METRIK_MCP_ALLOWED_ORIGINS` — comma-separated CORS origins, or `*`.
+ * - `METRIK_MCP_TENANTS` — JSON array of
+ *   `{ "id": string, "token": string, "env"?: Record<string,string> }`.
+ *   Each tenant's `env` is layered over the process environment and used to
+ *   build that tenant's isolated, wallet-backed agent client.
+ *
+ * Throws (fail-closed) when no tenants/tokens are configured.
+ */
+export function parseHostedMcpServerConfig(
+  env: NodeJS.ProcessEnv = process.env,
+): HostedMcpServerConfig {
+  const portRaw = env.METRIK_MCP_PORT ?? env.PORT ?? "8080";
+  const port = Number(portRaw);
+  if (!Number.isInteger(port) || port < 0 || port > 65535) {
+    throw new Error(`invalid port: ${portRaw}`);
+  }
+
+  const host = env.METRIK_MCP_HOST ?? "0.0.0.0";
+  const path = env.METRIK_MCP_PATH ?? "/mcp";
+  const allowedOrigins = (env.METRIK_MCP_ALLOWED_ORIGINS ?? "")
+    .split(",")
+    .map((value) => value.trim())
+    .filter((value) => value.length > 0);
+
+  const tenantsRaw = env.METRIK_MCP_TENANTS;
+  if (tenantsRaw === undefined || tenantsRaw.trim().length === 0) {
+    throw new Error(
+      "METRIK_MCP_TENANTS is required (fail-closed: refusing to run an open, unauthenticated MCP endpoint)",
+    );
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(tenantsRaw);
+  } catch {
+    throw new Error("METRIK_MCP_TENANTS must be valid JSON");
+  }
+  if (!Array.isArray(parsed) || parsed.length === 0) {
+    throw new Error("METRIK_MCP_TENANTS must be a non-empty JSON array");
+  }
+
+  const tenants = parsed.map((entry, index) => {
+    if (typeof entry !== "object" || entry === null) {
+      throw new Error(`METRIK_MCP_TENANTS[${index}] must be an object`);
+    }
+    const record = entry as Record<string, unknown>;
+    const id = record.id;
+    const token = record.token;
+    if (typeof id !== "string" || id.length === 0) {
+      throw new Error(
+        `METRIK_MCP_TENANTS[${index}].id must be a non-empty string`,
+      );
+    }
+    if (typeof token !== "string" || token.length === 0) {
+      throw new Error(
+        `METRIK_MCP_TENANTS[${index}].token must be a non-empty string`,
+      );
+    }
+    const tenantEnv: Record<string, string> = {};
+    if (record.env !== undefined) {
+      if (typeof record.env !== "object" || record.env === null) {
+        throw new Error(`METRIK_MCP_TENANTS[${index}].env must be an object`);
+      }
+      for (const [key, value] of Object.entries(
+        record.env as Record<string, unknown>,
+      )) {
+        if (typeof value !== "string") {
+          throw new Error(
+            `METRIK_MCP_TENANTS[${index}].env.${key} must be a string`,
+          );
+        }
+        tenantEnv[key] = value;
+      }
+    }
+    return { id, token, env: tenantEnv } satisfies HostedMcpTenantConfig;
+  });
+
+  return { host, port, path, allowedOrigins, tenants };
+}
+
+/**
+ * Builds fully-isolated {@link HostedMcpTenant}s from parsed config, resolving
+ * each tenant's wallet-backed agent client from its own environment slice.
+ */
+export async function createHostedMcpTenants(
+  config: HostedMcpServerConfig,
+  baseEnv: NodeJS.ProcessEnv = process.env,
+): Promise<HostedMcpTenant[]> {
+  const tenants: HostedMcpTenant[] = [];
+  for (const tenantConfig of config.tenants) {
+    const options = await createVerifiedStreamMcpServerOptionsFromEnv({
+      ...baseEnv,
+      ...tenantConfig.env,
+    });
+    tenants.push({
+      id: tenantConfig.id,
+      token: tenantConfig.token,
+      options,
+    });
+  }
+  return tenants;
+}
+
+/**
+ * Builds and starts a hosted MCP HTTP server entirely from the environment.
+ *
+ * Fail-closed: throws before binding if no tenants/tokens are configured.
+ */
+export async function startHostedMcpHttpServerFromEnv(
+  env: NodeJS.ProcessEnv = process.env,
+): Promise<HostedMcpHttpServer & { readonly boundPort: number }> {
+  const config = parseHostedMcpServerConfig(env);
+  const tenants = await createHostedMcpTenants(config, env);
+  const resolver = new StaticTenantResolver(tenants);
+  const server = createHostedMcpHttpServer({
+    resolver,
+    path: config.path,
+    allowedOrigins: config.allowedOrigins,
+  });
+  const { port } = await server.listen(config.port, config.host);
+  return Object.assign(server, { boundPort: port });
+}