@adtl/gateway 0.0.0-stage → 0.1.1

package/src/gateway.ts

@@ -0,0 +1,213 @@
+/**
+ * The gateway: one MCP server facing the agent, many MCP clients facing the
+ * upstream servers, and an interceptor chain in between.
+ *
+ * tools/list  → every upstream's tools, renamed <upstream>__<tool>
+ * tools/call  → request interceptors (adtl.policy) → upstream → response
+ *               interceptors (adtl.label) → agent
+ *
+ * When a call is stopped, the agent receives a normal tool result with
+ * `isError: true` explaining why, so the model can tell the user. In v0.1 an
+ * "ask" decision is treated as a block; approvals arrive in v0.2.
+ *
+ * In audit mode (the invoker runs every interceptor with `mode: "audit"`)
+ * nothing is stopped or changed: calls the policy would stop are forwarded,
+ * and the audit log records what would have happened.
+ */
+import { randomUUID } from "node:crypto";
+import type { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  type CallToolResult,
+  type Tool,
+} from "@modelcontextprotocol/sdk/types.js";
+import type { InvocationContext } from "@adtl/interceptors";
+import type { AuditEntry, AuditSink } from "./audit.js";
+import { TOOL_SEPARATOR } from "./config.js";
+import type { Blocked, ChainOutcome, InterceptorInvoker } from "./invoker.js";
+
+export const GATEWAY_VERSION = "0.1.1";
+
+/** `_meta` key on gateway-generated error results describing why a call was stopped. */
+export const GATEWAY_DECISION_KEY = "adtl/gateway";
+
+interface Route {
+  upstream: string;
+  tool: string;
+  annotations?: Tool["annotations"];
+}
+
+export interface GatewayLogger {
+  info(msg: string): void;
+  warn(msg: string): void;
+}
+
+const stderrLogger: GatewayLogger = {
+  info: (m) => console.error(`[adtl-gateway] ${m}`),
+  warn: (m) => console.error(`[adtl-gateway] warning: ${m}`),
+};
+
+export interface AdtlGatewayOptions {
+  upstreams: Map<string, Client>;
+  invoker: InterceptorInvoker;
+  /** One gateway process serves one agent session over stdio. */
+  sessionId?: string;
+  audit?: AuditSink;
+  logger?: GatewayLogger;
+}
+
+function textError(text: string, meta: Record<string, unknown>): CallToolResult {
+  return { content: [{ type: "text", text }], isError: true, _meta: { [GATEWAY_DECISION_KEY]: meta } };
+}
+
+function blockedMessage(b: Blocked): string {
+  if (b.decision === "ask") {
+    return (
+      `ADTL stopped this call because it needs a human's approval: ${b.reason}. ` +
+      `This version of ADTL cannot ask for approval yet, so the call was not run. Tell the user what you were trying to do.`
+    );
+  }
+  return `ADTL blocked this call: ${b.reason}. The call was not run.`;
+}
+
+function infoOf(outcome: ChainOutcome, interceptor: string): Record<string, unknown> {
+  return outcome.results.find((r) => r.interceptor === interceptor)?.info ?? {};
+}
+
+export class AdtlGateway {
+  readonly sessionId: string;
+  private readonly upstreams: Map<string, Client>;
+  private readonly invoker: InterceptorInvoker;
+  private readonly audit: AuditSink | undefined;
+  private readonly log: GatewayLogger;
+  private routes = new Map<string, Route>();
+
+  constructor(opts: AdtlGatewayOptions) {
+    this.upstreams = opts.upstreams;
+    this.invoker = opts.invoker;
+    this.sessionId = opts.sessionId ?? randomUUID();
+    this.audit = opts.audit;
+    this.log = opts.logger ?? stderrLogger;
+  }
+
+  /** The downstream MCP server the agent connects to. */
+  createServer(): Server {
+    const server = new Server(
+      { name: "adtl-gateway", version: GATEWAY_VERSION },
+      {
+        capabilities: { tools: {} },
+        instructions:
+          "Tools from several MCP servers, named <server>__<tool>. ADTL checks each call against trust labels; " +
+          "if a call is stopped, the result explains why.",
+      },
+    );
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: await this.listTools() }));
+    server.setRequestHandler(CallToolRequestSchema, async (req) => this.callTool(req.params.name, req.params.arguments ?? {}));
+    return server;
+  }
+
+  async listTools(): Promise<Tool[]> {
+    const routes = new Map<string, Route>();
+    const tools: Tool[] = [];
+    for (const [upstream, client] of this.upstreams) {
+      let cursor: string | undefined;
+      try {
+        do {
+          const page = await client.listTools(cursor ? { cursor } : {});
+          for (const t of page.tools) {
+            const name = `${upstream}${TOOL_SEPARATOR}${t.name}`;
+            routes.set(name, { upstream, tool: t.name, ...(t.annotations ? { annotations: t.annotations } : {}) });
+            tools.push({ ...t, name });
+          }
+          cursor = page.nextCursor;
+        } while (cursor);
+      } catch (err) {
+        this.log.warn(`tools/list failed for ${upstream}: ${(err as Error).message}`);
+      }
+    }
+    this.routes = routes;
+    return tools;
+  }
+
+  async callTool(name: string, args: Record<string, unknown>): Promise<CallToolResult> {
+    const started = performance.now();
+    let route = this.routes.get(name);
+    if (!route) {
+      await this.listTools();
+      route = this.routes.get(name);
+    }
+    if (!route) return textError(`Unknown tool: ${name}`, { reason: "unknown_tool" });
+
+    const client = this.upstreams.get(route.upstream)!;
+    const context: InvocationContext = {
+      sessionId: this.sessionId,
+      timestamp: new Date().toISOString(),
+      principal: { type: "anonymous" },
+    };
+    const config: Record<string, unknown> = {
+      server: route.upstream,
+      ...(route.annotations ? { toolAnnotations: route.annotations } : {}),
+    };
+    const base = { sessionId: this.sessionId, event: "tools/call" as const, server: route.upstream, tool: route.tool };
+    const finish = (entry: Omit<AuditEntry, keyof typeof base | "ts" | "durationMs">) =>
+      this.audit?.write({ ts: context.timestamp!, ...base, ...entry, durationMs: Math.round(performance.now() - started) });
+
+    // 1. Request phase: adtl.policy decides whether the call may run.
+    const requestPayload = { method: "tools/call", params: { name: route.tool, arguments: args } };
+    const req = await this.invoker.runRequest({ event: "tools/call", payload: requestPayload, config, context });
+    const policy = infoOf(req, "adtl.policy");
+    if (req.blocked) {
+      finish({ outcome: "blocked", decision: req.blocked.decision, reason: req.blocked.reason, matched: policy.matched, callHash: policy.callHash, sessionLabel: policy.sessionLabel, warnings: req.warnings });
+      this.log.info(`${req.blocked.decision} ${name}: ${req.blocked.reason}`);
+      return textError(blockedMessage(req.blocked), { ...req.blocked, callHash: policy.callHash });
+    }
+    const forwarded = (req.payload as typeof requestPayload).params;
+    const decision = policy["adtl/decision"] as string | undefined;
+    const audit = this.invoker.modeOverride === "audit";
+    // Only set in audit mode, for calls the policy would have stopped.
+    const wouldStop =
+      audit && decision !== undefined && decision !== "allow"
+        ? { reason: policy.reason as string | undefined, matched: policy.matched }
+        : undefined;
+    if (wouldStop) this.log.info(`audit: would ${decision} ${name}: ${wouldStop.reason}`);
+
+    // 2. Forward to the upstream server.
+    let result: CallToolResult;
+    try {
+      result = (await client.callTool({ name: forwarded.name, arguments: forwarded.arguments })) as CallToolResult;
+    } catch (err) {
+      const reason = (err as Error).message;
+      finish({ outcome: "upstream_error", ...(decision ? { decision } : {}), reason, callHash: policy.callHash, ...(audit ? { mode: "audit" as const } : {}), warnings: req.warnings });
+      return textError(`The ${route.upstream} server returned an error: ${reason}`, { reason: "upstream_error" });
+    }
+
+    // 3. Response phase: adtl.label labels the result and records it in the session.
+    const res = await this.invoker.runResponse({
+      event: "tools/call",
+      payload: { method: "tools/call", params: forwarded, result },
+      config,
+      context,
+    });
+    if (res.blocked) {
+      // Fail closed: an unlabeled result must not reach the agent.
+      finish({ outcome: "blocked", decision: res.blocked.decision, reason: res.blocked.reason, callHash: policy.callHash, warnings: [...req.warnings, ...res.warnings] });
+      this.log.warn(`result of ${name} withheld: ${res.blocked.reason}`);
+      return textError(`ADTL could not label the result of this call, so it was withheld: ${res.blocked.reason}`, { ...res.blocked });
+    }
+    const label = infoOf(res, "adtl.label");
+    finish({
+      outcome: "forwarded",
+      // Missing only if adtl.policy failed and was allowed to (audit mode); see warnings.
+      ...(decision ? { decision } : {}),
+      ...(wouldStop ?? {}),
+      ...(audit ? { mode: "audit" as const } : {}),
+      callHash: policy.callHash,
+      label: label.label,
+      sessionLabel: label.sessionLabel,
+      warnings: [...req.warnings, ...res.warnings],
+    });
+    return (res.payload as { result: CallToolResult }).result;
+  }
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from "./config.js";
+export * from "./invoker.js";
+export * from "./audit.js";
+export * from "./gateway.js";
+export * from "./startup.js";

package/src/invoker.ts

@@ -0,0 +1,186 @@
+/**
+ * Runs interceptors in the order SEP-2624 requires:
+ *
+ * - Sending (request phase, gateway → upstream): Mutate (sequential, by
+ *   priorityHint then name) → Validate (parallel).
+ * - Receiving (response phase, upstream → gateway): Validate (parallel) →
+ *   Mutate (sequential).
+ *
+ * Only `severity: "error"` blocks. Audit-mode interceptors never block, and
+ * their mutations are not applied. An interceptor that fails (error or
+ * timeout) blocks the message unless it declares `failOpen: true`.
+ *
+ * The invoker may override every interceptor's `mode`, as SEP-2624 allows
+ * (e.g. audit in staging, active in production).
+ */
+import type { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import {
+  DECISION_INFO_KEY,
+  INVOKE_METHOD,
+  LIST_METHOD,
+  type InterceptorDefinition,
+  type InterceptorResult,
+  type InvocationContext,
+  type MutationResult,
+  type Phase,
+  type ValidationResult,
+} from "@adtl/interceptors";
+import type { Decision } from "@adtl/labels";
+import { z } from "zod";
+
+const AnyResult = z.object({}).passthrough();
+
+type Loose = Record<string, unknown>;
+
+/** Untyped request: interceptor methods are extension methods the SDK does not type. */
+function request(client: Client, method: string, params: unknown, timeout: number): Promise<Loose> {
+  const r = client.request as unknown as (req: unknown, schema: unknown, opts: unknown) => Promise<Loose>;
+  return r.call(client, { method, params }, AnyResult, { timeout });
+}
+
+export type InterceptorMode = NonNullable<InterceptorDefinition["mode"]>;
+
+export interface BoundInterceptor {
+  client: Client;
+  definition: InterceptorDefinition;
+}
+
+export interface Blocked {
+  interceptor: string;
+  decision: Decision;
+  reason: string;
+}
+
+export interface ChainOutcome {
+  payload: unknown;
+  blocked?: Blocked;
+  results: InterceptorResult[];
+  /** Interceptors that failed but were allowed to (failOpen or audit mode). */
+  warnings: string[];
+}
+
+export interface InvokeOptions {
+  event: string;
+  payload: unknown;
+  config: Record<string, unknown>;
+  context: InvocationContext;
+}
+
+function priority(def: InterceptorDefinition, phase: Phase): number {
+  const p = def.priorityHint;
+  if (p === undefined) return 0;
+  if (typeof p === "number") return p;
+  return p[phase] ?? 0;
+}
+
+function hooks(def: InterceptorDefinition, event: string, phase: Phase): boolean {
+  return def.hooks.some((h) => h.phase === phase && (h.events.includes(event) || h.events.includes("*")));
+}
+
+export class InterceptorInvoker {
+  constructor(
+    private readonly interceptors: BoundInterceptor[],
+    private readonly timeoutMs = 5000,
+    /** Overrides the mode every interceptor declares. */
+    readonly modeOverride?: InterceptorMode,
+  ) {}
+
+  /** Discover the interceptors an interceptor server offers. */
+  static async discover(client: Client): Promise<BoundInterceptor[]> {
+    const res = await request(client, LIST_METHOD, {}, 10_000);
+    const defs = (res.interceptors ?? []) as InterceptorDefinition[];
+    return defs.map((definition) => ({ client, definition }));
+  }
+
+  get definitions(): InterceptorDefinition[] {
+    return this.interceptors.map((i) => i.definition);
+  }
+
+  async runRequest(opts: InvokeOptions): Promise<ChainOutcome> {
+    const out: ChainOutcome = { payload: opts.payload, results: [], warnings: [] };
+    if (!(await this.mutate("request", opts, out))) return out;
+    await this.validate("request", opts, out);
+    return out;
+  }
+
+  async runResponse(opts: InvokeOptions): Promise<ChainOutcome> {
+    const out: ChainOutcome = { payload: opts.payload, results: [], warnings: [] };
+    if (!(await this.validate("response", opts, out))) return out;
+    await this.mutate("response", opts, out);
+    return out;
+  }
+
+  private isAudit(i: BoundInterceptor): boolean {
+    return (this.modeOverride ?? i.definition.mode) === "audit";
+  }
+
+  private select(type: InterceptorDefinition["type"], event: string, phase: Phase): BoundInterceptor[] {
+    return this.interceptors.filter((i) => i.definition.type === type && hooks(i.definition, event, phase));
+  }
+
+  private async invoke(i: BoundInterceptor, phase: Phase, opts: InvokeOptions, payload: unknown): Promise<InterceptorResult> {
+    const res = await request(
+      i.client,
+      INVOKE_METHOD,
+      { name: i.definition.name, event: opts.event, phase, payload, config: opts.config, timeoutMs: this.timeoutMs, context: opts.context },
+      this.timeoutMs,
+    );
+    return res as unknown as InterceptorResult;
+  }
+
+  /** Handle an interceptor failure. Returns false if the chain must stop. */
+  private failed(i: BoundInterceptor, err: unknown, out: ChainOutcome): boolean {
+    const msg = `${i.definition.name} failed: ${err instanceof Error ? err.message : String(err)}`;
+    if (this.isAudit(i) || i.definition.failOpen === true) {
+      out.warnings.push(msg);
+      return true;
+    }
+    out.blocked = { interceptor: i.definition.name, decision: "block", reason: msg };
+    return false;
+  }
+
+  /** Sequential mutations, atomic: on failure the original payload is kept. */
+  private async mutate(phase: Phase, opts: InvokeOptions, out: ChainOutcome): Promise<boolean> {
+    const chain = this.select("mutation", opts.event, phase).sort(
+      (a, b) => priority(a.definition, phase) - priority(b.definition, phase) || a.definition.name.localeCompare(b.definition.name),
+    );
+    let payload = out.payload;
+    for (const i of chain) {
+      let r: MutationResult;
+      try {
+        r = (await this.invoke(i, phase, opts, payload)) as MutationResult;
+      } catch (err) {
+        if (!this.failed(i, err, out)) return false;
+        continue;
+      }
+      out.results.push(r);
+      if (!this.isAudit(i) && r.modified) payload = r.payload;
+    }
+    out.payload = payload;
+    return true;
+  }
+
+  /** Parallel validations. Only severity "error" blocks. */
+  private async validate(phase: Phase, opts: InvokeOptions, out: ChainOutcome): Promise<boolean> {
+    const chain = this.select("validation", opts.event, phase);
+    const settled = await Promise.allSettled(chain.map((i) => this.invoke(i, phase, opts, out.payload)));
+    let ok = true;
+    settled.forEach((s, idx) => {
+      const i = chain[idx]!;
+      if (s.status === "rejected") {
+        if (!this.failed(i, s.reason, out)) ok = false;
+        return;
+      }
+      const r = s.value as ValidationResult;
+      out.results.push(r);
+      if (r.valid || r.severity !== "error" || this.isAudit(i)) return;
+      if (!out.blocked) {
+        const decision = (r.info?.[DECISION_INFO_KEY] as Decision | undefined) ?? "block";
+        const reason = r.messages?.map((m) => m.message).join("; ") || `${i.definition.name} rejected the call`;
+        out.blocked = { interceptor: i.definition.name, decision, reason };
+      }
+      ok = false;
+    });
+    return ok;
+  }
+}

package/src/startup.ts

@@ -0,0 +1,161 @@
+/**
+ * Build a running gateway from an adtl.yaml file: start the interceptor
+ * server, connect every upstream, and check that ADTL's interceptors are there.
+ */
+import { readFile } from "node:fs/promises";
+import { dirname, isAbsolute, resolve } from "node:path";
+import { createRequire } from "node:module";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport, getDefaultEnvironment } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { INTERCEPTORS_EXTENSION, LABEL_INTERCEPTOR, POLICY_INTERCEPTOR, parseConfigText } from "@adtl/interceptors";
+import type { AdtlConfig } from "@adtl/labels";
+import { parse as parseYaml } from "yaml";
+import { ZodError } from "zod";
+import { JsonlAuditLog } from "./audit.js";
+import {
+  GatewayConfigSchema,
+  expandUpstream,
+  isHttpUpstream,
+  type GatewayConfig,
+  type StdioUpstream,
+  type Upstream,
+} from "./config.js";
+import { AdtlGateway, GATEWAY_VERSION, type GatewayLogger } from "./gateway.js";
+import { InterceptorInvoker } from "./invoker.js";
+
+export class GatewayConfigError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "GatewayConfigError";
+  }
+}
+
+export interface LoadedConfig {
+  path: string;
+  labels: AdtlConfig;
+  gateway: GatewayConfig;
+}
+
+export async function loadGatewayConfig(path: string): Promise<LoadedConfig> {
+  const abs = resolve(path);
+  let text: string;
+  try {
+    text = await readFile(abs, "utf8");
+  } catch (err) {
+    throw new GatewayConfigError(`Cannot read config file ${abs}: ${(err as Error).message}`);
+  }
+  let labels: AdtlConfig;
+  try {
+    labels = parseConfigText(text, abs);
+  } catch (err) {
+    throw new GatewayConfigError((err as Error).message);
+  }
+  const raw = (parseYaml(text) ?? {}) as { gateway?: unknown };
+  if (raw.gateway === undefined) {
+    throw new GatewayConfigError(`${abs}: missing "gateway:" section (at least one upstream under gateway.upstreams)`);
+  }
+  try {
+    return { path: abs, labels, gateway: GatewayConfigSchema.parse(raw.gateway) };
+  } catch (err) {
+    if (err instanceof ZodError) {
+      const problems = err.issues.map((i) => `  - gateway.${i.path.join(".")}: ${i.message}`).join("\n");
+      throw new GatewayConfigError(`${abs}: invalid gateway config\n${problems}`);
+    }
+    throw err;
+  }
+}
+
+/** Path of the bundled adtl-interceptors CLI. */
+export function bundledInterceptorsCli(): string {
+  // Resolve via package.json: works in plain Node and under tools that lack import.meta.resolve.
+  const pkg = createRequire(import.meta.url).resolve("@adtl/interceptors/package.json");
+  return resolve(dirname(pkg), "dist", "cli.js");
+}
+
+function stdioTransport(u: StdioUpstream, baseDir: string): StdioClientTransport {
+  return new StdioClientTransport({
+    command: u.command,
+    args: u.args,
+    // The SDK passes only `env` when given, which would drop PATH; start from its safe defaults.
+    env: { ...getDefaultEnvironment(), ...u.env },
+    ...(u.cwd !== undefined ? { cwd: isAbsolute(u.cwd) ? u.cwd : resolve(baseDir, u.cwd) } : {}),
+    stderr: "inherit",
+  });
+}
+
+async function connect(id: string, u: Upstream, baseDir: string): Promise<Client> {
+  const client = new Client({ name: `adtl-gateway→${id}`, version: GATEWAY_VERSION });
+  const transport = isHttpUpstream(u)
+    ? new StreamableHTTPClientTransport(new URL(u.url), { requestInit: { headers: u.headers } })
+    : stdioTransport(u, baseDir);
+  await client.connect(transport);
+  return client;
+}
+
+export interface StartedGateway {
+  gateway: AdtlGateway;
+  close(): Promise<void>;
+}
+
+export async function startGateway(
+  loaded: LoadedConfig,
+  opts: { env?: NodeJS.ProcessEnv; logger?: GatewayLogger } = {},
+): Promise<StartedGateway> {
+  const env = opts.env ?? process.env;
+  const baseDir = dirname(loaded.path);
+  const log = opts.logger ?? { info: (m: string) => console.error(`[adtl-gateway] ${m}`), warn: (m: string) => console.error(`[adtl-gateway] warning: ${m}`) };
+  const clients: Client[] = [];
+  const closeAll = () => Promise.allSettled(clients.map((c) => c.close())).then(() => undefined);
+
+  try {
+    // 1. Interceptor server (out of process, per the Interceptors WG).
+    const icfg: StdioUpstream = loaded.gateway.interceptors
+      ? expandUpstream("interceptors", loaded.gateway.interceptors, env)
+      : { command: process.execPath, args: [bundledInterceptorsCli(), "--config", loaded.path], env: {} };
+    const interceptors = await connect("interceptors", icfg, baseDir);
+    clients.push(interceptors);
+    if (!interceptors.getServerCapabilities()?.extensions?.[INTERCEPTORS_EXTENSION]) {
+      throw new GatewayConfigError(`The interceptor server does not declare the ${INTERCEPTORS_EXTENSION} extension`);
+    }
+    const bound = await InterceptorInvoker.discover(interceptors);
+    const names = bound.map((b) => b.definition.name);
+    for (const required of [POLICY_INTERCEPTOR, LABEL_INTERCEPTOR]) {
+      if (!names.includes(required)) {
+        throw new GatewayConfigError(`The interceptor server does not offer ${required}; refusing to start without it`);
+      }
+    }
+    const audit = loaded.gateway.mode === "audit";
+    const invoker = new InterceptorInvoker(bound, loaded.gateway.interceptorTimeoutMs, audit ? "audit" : undefined);
+    log.info(`interceptors: ${names.join(", ")}`);
+    if (audit) log.warn("audit mode: calls are logged but never stopped or changed");
+
+    // 2. Upstream servers. One failing upstream does not stop the others.
+    const upstreams = new Map<string, Client>();
+    const ids = Object.keys(loaded.gateway.upstreams);
+    const settled = await Promise.allSettled(
+      ids.map((id) => connect(id, expandUpstream(id, loaded.gateway.upstreams[id]!, env), baseDir)),
+    );
+    settled.forEach((s, i) => {
+      const id = ids[i]!;
+      if (s.status === "fulfilled") {
+        clients.push(s.value);
+        upstreams.set(id, s.value);
+        if (!loaded.labels.servers[id]) {
+          log.warn(`upstream "${id}" has no entry under servers: in the label config; its results get the default label`);
+        }
+      } else {
+        log.warn(`could not connect to upstream "${id}": ${(s.reason as Error).message}`);
+      }
+    });
+    if (upstreams.size === 0) throw new GatewayConfigError("No upstream server could be connected");
+    log.info(`upstreams: ${[...upstreams.keys()].join(", ")}`);
+
+    const auditLog = loaded.gateway.audit ? new JsonlAuditLog(resolve(baseDir, loaded.gateway.audit)) : undefined;
+    const gateway = new AdtlGateway({ upstreams, invoker, ...(auditLog ? { audit: auditLog } : {}), logger: log });
+    return { gateway, close: closeAll };
+  } catch (err) {
+    await closeAll();
+    throw err;
+  }
+}