@adtl/gateway 0.7.0 → 0.8.1

package/src/invoker.ts

@@ -11,8 +11,11 @@
  * 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).
+ * The invoker may override execution policy, as SEP-2624 allows: every
+ * interceptor's `mode` at once (e.g. audit in staging, active in production),
+ * and per interceptor its `failOpen`, `priorityHint`, `mode`, `timeoutMs` and
+ * `hooks` (narrowed only, never widened). A global mode wins over a
+ * per-interceptor one, so `--audit` always stops nothing.
  */
 import type { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import {
@@ -21,6 +24,7 @@ import {
   LIST_METHOD,
   type ConfirmationRequest,
   type InterceptorDefinition,
+  type InterceptorHook,
   type InterceptorResult,
   type InvocationContext,
   type MutationResult,
@@ -34,17 +38,49 @@ const AnyResult = z.object({}).passthrough();
 
 type Loose = Record<string, unknown>;
 
-/** Untyped request: interceptor methods are extension methods the SDK does not type. */
+/**
+ * Untyped request: interceptor methods are extension methods the SDK does not type.
+ * The timeout is enforced here too, so a client that ignores it can't hang a phase.
+ */
 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 });
+  const controller = new AbortController();
+  let timer: NodeJS.Timeout | undefined;
+  const expired = new Promise<never>((_, reject) => {
+    timer = setTimeout(() => {
+      controller.abort();
+      reject(new Error(`timed out after ${timeout} ms`));
+    }, timeout);
+  });
+  return Promise.race([r.call(client, { method, params }, AnyResult, { timeout, signal: controller.signal }), expired]).finally(() =>
+    clearTimeout(timer),
+  );
 }
 
 export type InterceptorMode = NonNullable<InterceptorDefinition["mode"]>;
 
+/** Invoker-side execution policy for one interceptor (SEP-2624 "Invoker Overrides"). */
+export interface InterceptorOverrides {
+  failOpen?: boolean;
+  /** Ignored for validators. */
+  priorityHint?: InterceptorDefinition["priorityHint"];
+  mode?: InterceptorMode;
+  timeoutMs?: number;
+  /** Must be a subset of the interceptor's declared hooks. */
+  hooks?: InterceptorHook[];
+}
+
 export interface BoundInterceptor {
   client: Client;
   definition: InterceptorDefinition;
+  /** Id of the interceptor server that advertised it, for messages. */
+  server?: string;
+  /**
+   * Whether the gateway's per-call `config` (ADTL's server, tool and
+   * annotations) is sent. Other servers' interceptors get none, so their
+   * own defaults apply. Default: true.
+   */
+  sendConfig?: boolean;
 }
 
 export interface Blocked {
@@ -68,6 +104,7 @@ export interface InterceptorRun {
   modeFrom: "override" | "default";
   failOpen: boolean;
   failOpenFrom: "override" | "default";
+  timeoutMs: number;
   /** Set when the invocation errored or timed out. */
   failed?: true;
 }
@@ -89,15 +126,77 @@ export interface InvokeOptions {
   context: InvocationContext;
 }
 
-function priority(def: InterceptorDefinition, phase: Phase): number {
-  const p = def.priorityHint;
+/** SEP-2624 `resolvePriority`: the override's hint, else the interceptor's. */
+export function resolvePriority(def: InterceptorDefinition, overrides: InterceptorOverrides | undefined, phase: Phase): number {
+  const p = overrides?.priorityHint ?? 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("*")));
+function matches(hooks: InterceptorHook[], event: string, phase: Phase): boolean {
+  return hooks.some((h) => h.phase === phase && (h.events.includes(event) || h.events.includes("*")));
+}
+
+/**
+ * Problems with `overrides` for these interceptors: an unknown name, or hooks
+ * that widen what the interceptor declares (which SEP-2624 says to reject).
+ */
+export function checkOverrides(defs: InterceptorDefinition[], overrides: Record<string, InterceptorOverrides>): string[] {
+  const problems: string[] = [];
+  for (const [name, o] of Object.entries(overrides)) {
+    const def = defs.find((d) => d.name === name);
+    if (!def) {
+      problems.push(`${name}: no such interceptor (offered: ${defs.map((d) => d.name).join(", ")})`);
+      continue;
+    }
+    for (const h of o.hooks ?? []) {
+      for (const event of h.events) {
+        const declared = def.hooks.some((d) => d.phase === h.phase && (d.events.includes("*") || (event !== "*" && d.events.includes(event))));
+        if (!declared) problems.push(`${name}: hooks may only narrow the declared hooks, and ${event} (${h.phase}) is not declared`);
+      }
+    }
+  }
+  return problems;
+}
+
+/** Interceptors of a type this invoker doesn't run (e.g. the proposed `sink`). They are never invoked. */
+export function unsupportedInterceptors(bound: BoundInterceptor[]): string[] {
+  return bound
+    .filter((b) => b.definition.type !== "validation" && b.definition.type !== "mutation")
+    .map((b) => `${b.definition.name} (${String(b.definition.type)})`);
+}
+
+/** Interceptor names offered by more than one server: each must be invoked on its own server, so names must be unique. */
+export function duplicateInterceptors(bound: BoundInterceptor[]): string[] {
+  const servers = new Map<string, string[]>();
+  for (const b of bound) servers.set(b.definition.name, [...(servers.get(b.definition.name) ?? []), b.server ?? "?"]);
+  return [...servers].filter(([, s]) => s.length > 1).map(([name, s]) => `${name} (offered by ${s.join(", ")})`);
+}
+
+/**
+ * Mutators that would run after `name` on a phase both hook, so they see (and
+ * could change or drop) what it wrote. Used to warn when another server's
+ * mutator runs after adtl.label.
+ */
+export function mutatorsAfter(bound: BoundInterceptor[], name: string, overrides: Record<string, InterceptorOverrides> = {}): string[] {
+  const target = bound.find((b) => b.definition.name === name);
+  if (!target) return [];
+  const hooksOf = (b: BoundInterceptor) => overrides[b.definition.name]?.hooks ?? b.definition.hooks;
+  const shares = (b: BoundInterceptor, phase: Phase) =>
+    hooksOf(b).some((h) => h.phase === phase && hooksOf(target).some((t) => t.phase === phase && (h.events.includes("*") || t.events.includes("*") || h.events.some((e) => t.events.includes(e)))));
+  const after: string[] = [];
+  for (const b of bound) {
+    if (b === target || b.definition.type !== "mutation") continue;
+    const late = (["request", "response"] as const).some((phase) => {
+      if (!shares(b, phase)) return false;
+      const p = resolvePriority(b.definition, overrides[b.definition.name], phase);
+      const t = resolvePriority(target.definition, overrides[name], phase);
+      return p > t || (p === t && b.definition.name.localeCompare(name) > 0);
+    });
+    if (late) after.push(b.definition.name);
+  }
+  return after;
 }
 
 export class InterceptorInvoker {
@@ -106,13 +205,15 @@ export class InterceptorInvoker {
     private readonly timeoutMs = 5000,
     /** Overrides the mode every interceptor declares. */
     readonly modeOverride?: InterceptorMode,
+    /** Per-interceptor overrides, by name. Check them with `checkOverrides` first. */
+    private readonly overrides: Record<string, InterceptorOverrides> = {},
   ) {}
 
   /** Discover the interceptors an interceptor server offers. */
-  static async discover(client: Client): Promise<BoundInterceptor[]> {
+  static async discover(client: Client, opts: { server?: string; sendConfig?: boolean } = {}): Promise<BoundInterceptor[]> {
     const res = await request(client, LIST_METHOD, {}, 10_000);
     const defs = (res.interceptors ?? []) as InterceptorDefinition[];
-    return defs.map((definition) => ({ client, definition }));
+    return defs.map((definition) => ({ client, definition, ...opts }));
   }
 
   get definitions(): InterceptorDefinition[] {
@@ -133,34 +234,63 @@ export class InterceptorInvoker {
     return out;
   }
 
+  private override(i: BoundInterceptor): InterceptorOverrides | undefined {
+    return this.overrides[i.definition.name];
+  }
+
+  private mode(i: BoundInterceptor): InterceptorMode {
+    return this.modeOverride ?? this.override(i)?.mode ?? i.definition.mode ?? "active";
+  }
+
   private isAudit(i: BoundInterceptor): boolean {
-    return (this.modeOverride ?? i.definition.mode) === "audit";
+    return this.mode(i) === "audit";
+  }
+
+  private failOpen(i: BoundInterceptor): boolean {
+    return (this.override(i)?.failOpen ?? i.definition.failOpen) === true;
   }
 
-  /** Record that `i` runs in `phase`, with its resolved policy. The gateway has no failOpen overrides. */
+  private timeout(i: BoundInterceptor): number {
+    return this.override(i)?.timeoutMs ?? this.timeoutMs;
+  }
+
+  /** Record that `i` runs in `phase`, with its resolved policy. */
   private run(i: BoundInterceptor, phase: Phase, out: PhaseOutcome): InterceptorRun {
+    const o = this.override(i);
     const r: InterceptorRun = {
       name: i.definition.name,
       phase,
-      mode: this.modeOverride ?? i.definition.mode ?? "active",
-      modeFrom: this.modeOverride ? "override" : "default",
-      failOpen: i.definition.failOpen === true,
-      failOpenFrom: "default",
+      mode: this.mode(i),
+      modeFrom: this.modeOverride || o?.mode ? "override" : "default",
+      failOpen: this.failOpen(i),
+      failOpenFrom: o?.failOpen !== undefined ? "override" : "default",
+      timeoutMs: this.timeout(i),
     };
     out.ran.push(r);
     return r;
   }
 
   private select(type: InterceptorDefinition["type"], event: string, phase: Phase): BoundInterceptor[] {
-    return this.interceptors.filter((i) => i.definition.type === type && hooks(i.definition, event, phase));
+    return this.interceptors.filter(
+      (i) => i.definition.type === type && matches(this.override(i)?.hooks ?? i.definition.hooks, event, phase),
+    );
   }
 
   private async invoke(i: BoundInterceptor, phase: Phase, opts: InvokeOptions, payload: unknown): Promise<InterceptorResult> {
+    const timeoutMs = this.timeout(i);
     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,
+      {
+        name: i.definition.name,
+        event: opts.event,
+        phase,
+        payload,
+        ...(i.sendConfig === false ? {} : { config: opts.config }),
+        timeoutMs,
+        context: opts.context,
+      },
+      timeoutMs,
     );
     return res as unknown as InterceptorResult;
   }
@@ -168,7 +298,7 @@ export class InterceptorInvoker {
   /** Handle an interceptor failure. Returns false if the phase must stop. */
   private failed(i: BoundInterceptor, err: unknown, out: PhaseOutcome): boolean {
     const msg = `${i.definition.name} failed: ${err instanceof Error ? err.message : String(err)}`;
-    if (this.isAudit(i) || i.definition.failOpen === true) {
+    if (this.isAudit(i) || this.failOpen(i)) {
       out.warnings.push(msg);
       return true;
     }
@@ -179,7 +309,9 @@ export class InterceptorInvoker {
   /** Sequential mutations, atomic: on failure the original payload is kept. */
   private async mutate(phase: Phase, opts: InvokeOptions, out: PhaseOutcome): Promise<boolean> {
     const selected = this.select("mutation", opts.event, phase).sort(
-      (a, b) => priority(a.definition, phase) - priority(b.definition, phase) || a.definition.name.localeCompare(b.definition.name),
+      (a, b) =>
+        resolvePriority(a.definition, this.override(a), phase) - resolvePriority(b.definition, this.override(b), phase) ||
+        a.definition.name.localeCompare(b.definition.name),
     );
     let payload = out.payload;
     for (const i of selected) {

package/src/openfga.ts

@@ -0,0 +1,101 @@
+/**
+ * Relationship-based authorization with OpenFGA (`gateway.openfga`):
+ *
+ *   openfga:
+ *     url: http://localhost:8080
+ *     storeId: "${FGA_STORE_ID}"
+ *     modelId: "${FGA_MODEL_ID}"     # optional: pin an authorization model
+ *     token: "${FGA_TOKEN}"          # optional: bearer token
+ *     relation: can_use              # optional: the default relation
+ *     timeoutMs: 2000                # optional
+ *     tools:                         # optional: per-resource rules, from the call's arguments
+ *       github.add_issue_comment: { relation: can_comment, object: "repo:{owner}/{repo}" }
+ *
+ * Every call becomes one OpenFGA check:
+ *
+ *   user      user:<id>, service:<id>, or user:anonymous without an id
+ *   relation  the tool's rule, else `relation`
+ *   object    the tool's rule, else tool:<server>.<tool>, prompt:<server>.<name> or resource:<uri>
+ *
+ * Ids are percent-encoded, because OpenFGA ids can't hold `:`, `#`, `@` or
+ * spaces; ids too long for OpenFGA are replaced by their SHA-256. A rule's
+ * `{argument}` must be a string or number, or the call is denied. Tool lists
+ * have no arguments, so tools whose object needs them stay listed and are
+ * checked when called. An unreachable server or an error denies the call.
+ *
+ * Works with Auth0 FGA too, by pointing `url` at its API and passing a token.
+ */
+import { createHash } from "node:crypto";
+import type { AuthorizationDecision, AuthorizationRequest, Authorizer } from "./authorizer.js";
+import type { OpenFgaConfig } from "./config.js";
+
+/** OpenFGA's limit on the id part of an object or user. */
+const MAX_ID = 254;
+
+function fgaId(value: string): string {
+  const id = encodeURIComponent(value);
+  return id.length <= MAX_ID ? id : `sha256-${createHash("sha256").update(value).digest("hex")}`;
+}
+
+const PLACEHOLDER = /\{([A-Za-z0-9_.-]+)\}/g;
+
+export class OpenFgaAuthorizer implements Authorizer {
+  readonly name = "openfga";
+
+  constructor(
+    private readonly cfg: OpenFgaConfig,
+    private readonly fetchFn: typeof fetch = fetch,
+  ) {}
+
+  private user(req: AuthorizationRequest): string {
+    const p = req.principal;
+    if (p.type === "anonymous" || !p.id) return "user:anonymous";
+    return `${p.type === "service" ? "service" : "user"}:${fgaId(p.id)}`;
+  }
+
+  /** The object of this call, or a reason it can't be built. "listing" means: decide when called. */
+  private object(req: AuthorizationRequest, template?: string): { object: string } | { missing: string } | "listing" {
+    if (template !== undefined) {
+      if (req.arguments === undefined && template.search(PLACEHOLDER) !== -1) return "listing";
+      const colon = template.indexOf(":");
+      const type = template.slice(0, colon + 1);
+      let missing: string | undefined;
+      const id = template.slice(colon + 1).replace(PLACEHOLDER, (_, name: string) => {
+        const v = req.arguments?.[name];
+        if (typeof v !== "string" && typeof v !== "number") {
+          missing ??= name;
+          return "";
+        }
+        return String(v);
+      });
+      return missing !== undefined ? { missing } : { object: `${type}${fgaId(id)}` };
+    }
+    if (req.tool !== undefined) return { object: `tool:${fgaId(`${req.server}.${req.tool}`)}` };
+    if (req.prompt !== undefined) return { object: `prompt:${fgaId(`${req.server}.${req.prompt}`)}` };
+    return { object: `resource:${fgaId(req.resource ?? "")}` };
+  }
+
+  async check(req: AuthorizationRequest): Promise<AuthorizationDecision> {
+    const rule = req.tool !== undefined ? this.cfg.tools[`${req.server}.${req.tool}`] : undefined;
+    const target = this.object(req, rule?.object);
+    if (target === "listing") return { allow: true };
+    const what = req.tool ?? req.prompt ?? req.resource;
+    if ("missing" in target) return { allow: false, reason: `openfga: ${what} has no usable argument "${target.missing}"` };
+
+    const user = this.user(req);
+    const relation = rule?.relation ?? this.cfg.relation;
+    const res = await this.fetchFn(`${this.cfg.url.replace(/\/+$/, "")}/stores/${encodeURIComponent(this.cfg.storeId)}/check`, {
+      method: "POST",
+      headers: { "content-type": "application/json", ...(this.cfg.token ? { authorization: `Bearer ${this.cfg.token}` } : {}) },
+      body: JSON.stringify({
+        tuple_key: { user, relation, object: target.object },
+        ...(this.cfg.modelId ? { authorization_model_id: this.cfg.modelId } : {}),
+      }),
+      signal: AbortSignal.timeout(this.cfg.timeoutMs),
+    });
+    if (!res.ok) throw new Error(`OpenFGA answered ${res.status}`);
+    const body = (await res.json()) as { allowed?: unknown };
+    if (body.allowed === true) return { allow: true };
+    return { allow: false, reason: `OpenFGA: ${user} has no ${relation} on ${target.object}` };
+  }
+}

package/src/startup.ts

@@ -28,7 +28,9 @@ import {
 } from "./config.js";
 import { EmailNotifier } from "./email.js";
 import { AdtlGateway, GATEWAY_VERSION, type GatewayLogger } from "./gateway.js";
-import { InterceptorInvoker } from "./invoker.js";
+import { InterceptorInvoker, checkOverrides, duplicateInterceptors, mutatorsAfter, unsupportedInterceptors } from "./invoker.js";
+import { OpenFgaAuthorizer } from "./openfga.js";
+import { loadTotpVerifier } from "./totp.js";
 import { NtfyNotifier } from "./ntfy.js";
 import { RoleAuthorizer } from "./roles.js";
 
@@ -124,12 +126,13 @@ export function createApprovals(cfg: GatewayConfig, env: NodeJS.ProcessEnv, log:
   const approverChannels = new Map<string, Notifier[]>(
     Object.entries(a.approvers ?? {}).map(([id, c]) => [id, [new NtfyNotifier({ ...c.ntfy, name: `ntfy:${id}` })]]),
   );
-  if (notifiers.length === 0 && approverChannels.size === 0 && !a.elicitation) return undefined;
-  if (!notifiers.some((n) => n.listen) && approverChannels.size === 0 && !a.elicitation) {
+  if (notifiers.length === 0 && approverChannels.size === 0 && !a.elicitation && !a.totp) return undefined;
+  if (!notifiers.some((n) => n.listen) && approverChannels.size === 0 && !a.elicitation && !a.totp) {
     log.warn('no approval channel can carry answers (configure gateway.approvals.ntfy); "ask" still blocks');
   }
   const approvers = approverChannels.size ? `; approvers: ${[...approverChannels.keys()].join(", ")}` : "";
-  const shared = [...notifiers.map((n) => n.name), ...(a.elicitation ? ["elicitation (if the client supports it)"] : [])];
+  const inClient = a.totp ? ["authenticator code (if the client supports elicitation)"] : a.elicitation ? ["elicitation (if the client supports it)"] : [];
+  const shared = [...notifiers.map((n) => n.name), ...inClient];
   log.info(`approvals: ${shared.join(", ") || "none shared"}${approvers} (timeout ${a.timeoutSeconds}s)`);
   return new ApprovalBroker({ notifiers, approverChannels, timeoutMs: a.timeoutSeconds * 1000, log });
 }
@@ -175,7 +178,7 @@ export function gatewayPrincipal(cfg: GatewayConfig, env: NodeJS.ProcessEnv): Pr
  * The configured authorizers, in the order they are asked: roles, then cedar.
  * Cedar files are read and parsed here, so a bad policy fails startup.
  */
-export async function gatewayAuthorizers(cfg: GatewayConfig, baseDir: string): Promise<Authorizer[]> {
+export async function gatewayAuthorizers(cfg: GatewayConfig, baseDir: string, env: NodeJS.ProcessEnv = process.env): Promise<Authorizer[]> {
   const out: Authorizer[] = [];
   if (cfg.roles) out.push(new RoleAuthorizer(cfg.roles));
   if (cfg.cedar) {
@@ -185,6 +188,19 @@ export async function gatewayAuthorizers(cfg: GatewayConfig, baseDir: string): P
       throw new GatewayConfigError((err as Error).message);
     }
   }
+  if (cfg.openfga) {
+    const f = cfg.openfga;
+    const expand = (v: string, key: string) => expandEnv(v, env, `gateway.openfga.${key}`);
+    out.push(
+      new OpenFgaAuthorizer({
+        ...f,
+        url: expand(f.url, "url"),
+        storeId: expand(f.storeId, "storeId"),
+        ...(f.modelId !== undefined ? { modelId: expand(f.modelId, "modelId") } : {}),
+        ...(f.token !== undefined ? { token: expand(f.token, "token") } : {}),
+      }),
+    );
+  }
   return out;
 }
 
@@ -192,12 +208,23 @@ export async function gatewayAuthorizers(cfg: GatewayConfig, baseDir: string): P
  * Under Claude Code, which passes `CLAUDE_CODE_SESSION_ID` to stdio MCP
  * servers, the gateway uses that id and keeps session labels in files, so the
  * Claude Code hooks (`adtl-gateway hook`) add to the same session label.
+ *
+ * `ADTL_SESSION_ID` does the same for any agent framework, and wins over
+ * Claude Code's: a sub-agent's gateway started with its parent's session id
+ * starts from the parent's label, and what it reads taints the parent too.
  */
 export function sharedSession(env: NodeJS.ProcessEnv): { sessionId: string; dir: string } | undefined {
-  const sessionId = env.CLAUDE_CODE_SESSION_ID?.trim();
+  const sessionId = env.ADTL_SESSION_ID?.trim() || env.CLAUDE_CODE_SESSION_ID?.trim();
   return sessionId ? { sessionId, dir: defaultSessionsDir(env) } : undefined;
 }
 
+/** `ADTL_AGENT_ID` (and `ADTL_AGENT_TYPE`): which agent this gateway serves, for the audit log. */
+export function gatewayAgent(env: NodeJS.ProcessEnv): { id: string; type?: string } | undefined {
+  const id = env.ADTL_AGENT_ID?.trim();
+  const type = env.ADTL_AGENT_TYPE?.trim();
+  return id ? { id, ...(type ? { type } : {}) } : undefined;
+}
+
 export interface StartedGateway {
   gateway: AdtlGateway;
   close(): Promise<void>;
@@ -211,7 +238,7 @@ export async function startGateway(
   // Config problems that need no process: fail before starting any.
   const approverMembers = approverRoles(loaded.labels, loaded.gateway);
   const baseDir = dirname(loaded.path);
-  const authorizers = await gatewayAuthorizers(loaded.gateway, baseDir);
+  const authorizers = await gatewayAuthorizers(loaded.gateway, baseDir, env);
   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);
@@ -237,15 +264,50 @@ export async function startGateway(
     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);
+    const own = await InterceptorInvoker.discover(interceptors, { server: "interceptors" });
+    const ownNames = own.map((b) => b.definition.name);
     for (const required of [POLICY_INTERCEPTOR, LABEL_INTERCEPTOR]) {
-      if (!names.includes(required)) {
+      if (!ownNames.includes(required)) {
         throw new GatewayConfigError(`The interceptor server does not offer ${required}; refusing to start without it`);
       }
     }
+    // More interceptor servers (SEP-2624: interceptors may come from N servers, each invoked where it was advertised).
+    // A server that can't be reached stops startup: the owner asked for its interceptors.
+    const bound = [...own];
+    for (const [id, server] of Object.entries(loaded.gateway.interceptorServers)) {
+      const where = `gateway.interceptorServers.${id}`;
+      let client: Client;
+      try {
+        client = await connectUpstream(`interceptors:${id}`, expandUpstream(id, server, env), baseDir);
+      } catch (err) {
+        throw new GatewayConfigError(`${where}: could not connect: ${err instanceof Error ? err.message : String(err)}`);
+      }
+      clients.push(client);
+      if (!client.getServerCapabilities()?.extensions?.[INTERCEPTORS_EXTENSION]) {
+        throw new GatewayConfigError(`${where} does not declare the ${INTERCEPTORS_EXTENSION} extension`);
+      }
+      bound.push(...(await InterceptorInvoker.discover(client, { server: id, sendConfig: false })));
+    }
+    const duplicates = duplicateInterceptors(bound);
+    if (duplicates.length) throw new GatewayConfigError(`Interceptor names must be unique across servers: ${duplicates.join("; ")}`);
+    const names = bound.map((b) => b.definition.name);
+    const overrides = loaded.gateway.interceptorOverrides;
+    const problems = checkOverrides(bound.map((b) => b.definition), overrides);
+    if (problems.length) throw new GatewayConfigError(`gateway.interceptorOverrides: ${problems.join("; ")}`);
+    const unsupported = unsupportedInterceptors(bound);
+    if (unsupported.length) log.warn(`not running interceptors of an unknown type: ${unsupported.join(", ")}`);
+    const late = mutatorsAfter(bound, LABEL_INTERCEPTOR, overrides);
+    if (late.length) {
+      log.warn(`${late.join(", ")} run after ${LABEL_INTERCEPTOR} and could change or drop its label; give them a lower priorityHint`);
+    }
+    for (const name of [POLICY_INTERCEPTOR, LABEL_INTERCEPTOR]) {
+      const o = overrides[name];
+      if (o?.mode === "audit" || o?.failOpen === true || o?.hooks) {
+        log.warn(`gateway.interceptorOverrides relaxes ${name} (${Object.keys(o).join(", ")}): calls it would stop may get through`);
+      }
+    }
     const audit = loaded.gateway.mode === "audit";
-    const invoker = new InterceptorInvoker(bound, loaded.gateway.interceptorTimeoutMs, audit ? "audit" : undefined);
+    const invoker = new InterceptorInvoker(bound, loaded.gateway.interceptorTimeoutMs, audit ? "audit" : undefined, overrides);
     log.info(`interceptors: ${names.join(", ")}`);
     if (shared) log.info(`sharing session labels with Claude Code hooks (${shared.dir})`);
     if (audit) log.warn("audit mode: calls are logged but never stopped or changed");
@@ -280,8 +342,14 @@ export async function startGateway(
       if (!principal) log.warn('roles are set but gateway.principal is not: only roles with members ["*"] apply');
     }
     for (const a of authorizers) if (a.name !== "roles") log.info(`authorizer: ${a.name}`);
+    const totp = loaded.gateway.approvals?.totp ? loadTotpVerifier(env) : undefined;
+    if (loaded.gateway.approvals?.totp && !totp) throw new GatewayConfigError("gateway.approvals.totp is on, but no secret is set up: run adtl-gateway totp setup");
+    const agent = gatewayAgent(env);
+    if (agent) log.info(`agent: ${agent.id}${agent.type ? ` (${agent.type})` : ""}`);
     const gateway = new AdtlGateway({
       ...(shared ? { sessionId: shared.sessionId } : {}),
+      ...(agent ? { agent } : {}),
+      ...(totp ? { totp } : {}),
       upstreams,
       invoker,
       ...(auditLog ? { audit: auditLog } : {}),