@adtl/gateway 0.6.0 → 0.8.0

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,70 @@ 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;
+}
+
+/** 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 +198,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 +227,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 +291,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 +302,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/startup.ts

@@ -14,7 +14,8 @@ import { parse as parseYaml } from "yaml";
 import { ZodError } from "zod";
 import { ApprovalBroker, type Notifier } from "./approvals.js";
 import { JsonlAuditLog } from "./audit.js";
-import type { Principal } from "./authorizer.js";
+import type { Authorizer, Principal } from "./authorizer.js";
+import { CedarAuthorizer } from "./cedar.js";
 import {
   GatewayConfigSchema,
   expandApprovals,
@@ -27,7 +28,7 @@ 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 } from "./invoker.js";
 import { NtfyNotifier } from "./ntfy.js";
 import { RoleAuthorizer } from "./roles.js";
 
@@ -170,16 +171,44 @@ export function gatewayPrincipal(cfg: GatewayConfig, env: NodeJS.ProcessEnv): Pr
   return { type: p.type, id, ...(p.claims ? { claims: p.claims } : {}) };
 }
 
+/**
+ * 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[]> {
+  const out: Authorizer[] = [];
+  if (cfg.roles) out.push(new RoleAuthorizer(cfg.roles));
+  if (cfg.cedar) {
+    try {
+      out.push(await CedarAuthorizer.load(cfg.cedar, (p) => resolve(baseDir, p)));
+    } catch (err) {
+      throw new GatewayConfigError((err as Error).message);
+    }
+  }
+  return out;
+}
+
 /**
  * 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>;
@@ -193,6 +222,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 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);
@@ -218,15 +248,48 @@ 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 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");
@@ -260,13 +323,17 @@ export async function startGateway(
       log.info(`roles: ${Object.keys(roles).join(", ")} (caller: ${principal?.id ?? "anonymous"})`);
       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 agent = gatewayAgent(env);
+    if (agent) log.info(`agent: ${agent.id}${agent.type ? ` (${agent.type})` : ""}`);
     const gateway = new AdtlGateway({
       ...(shared ? { sessionId: shared.sessionId } : {}),
+      ...(agent ? { agent } : {}),
       upstreams,
       invoker,
       ...(auditLog ? { audit: auditLog } : {}),
       ...(approvals ? { approvals } : {}),
-      ...(roles ? { authorizer: new RoleAuthorizer(roles) } : {}),
+      ...(authorizers.length ? { authorizer: authorizers } : {}),
       ...(principal ? { principal } : {}),
       ...(approverMembers.size ? { approverRoles: approverMembers } : {}),
       ...(loaded.gateway.approvals?.elicitation ? { elicitApprovals: true } : {}),