@adtl/gateway 0.1.0 → 0.2.0

package/src/gateway.ts

@@ -7,8 +7,15 @@
  *               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.
+ * `isError: true` explaining why, so the model can tell the user.
+ *
+ * An "ask" decision holds the call and asks a human through the approval
+ * broker (e.g. a phone notification). Approved calls run; denied, unanswered
+ * or undeliverable ones are stopped. Without an approval channel, "ask" blocks.
+ *
+ * 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";
@@ -20,11 +27,12 @@ import {
   type Tool,
 } from "@modelcontextprotocol/sdk/types.js";
 import type { InvocationContext } from "@adtl/interceptors";
+import type { ApprovalBroker, ApprovalResult } from "./approvals.js";
 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.0";
+export const GATEWAY_VERSION = "0.2.0";
 
 /** `_meta` key on gateway-generated error results describing why a call was stopped. */
 export const GATEWAY_DECISION_KEY = "adtl/gateway";
@@ -52,8 +60,18 @@ export interface AdtlGatewayOptions {
   sessionId?: string;
   audit?: AuditSink;
   logger?: GatewayLogger;
+  /** Asks humans about "ask" decisions and sends notices. */
+  approvals?: ApprovalBroker;
+}
+
+export interface CallOptions {
+  /** Report progress to the client while a call waits for approval. */
+  progress?: (progress: number, message: string) => Promise<void>;
 }
 
+/** How often a waiting call reports progress, so clients that reset their timeout on progress keep waiting. */
+const PROGRESS_INTERVAL_MS = 10_000;
+
 function textError(text: string, meta: Record<string, unknown>): CallToolResult {
   return { content: [{ type: "text", text }], isError: true, _meta: { [GATEWAY_DECISION_KEY]: meta } };
 }
@@ -62,12 +80,24 @@ 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.`
+      `No approval channel is configured, 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 approvalMessage(b: Blocked, a: ApprovalResult): string {
+  const why = `ADTL asked a human to approve this call because: ${b.reason}.`;
+  switch (a.outcome) {
+    case "denied":
+      return `${why} The request was denied, so the call was not run. Do not retry it; tell the user what you were trying to do.`;
+    case "timeout":
+      return `${why} Nobody answered in time, so the call was not run. Tell the user, who can approve it if you try again.`;
+    default:
+      return `${why} ADTL could not reach anyone to approve it, so the call was not run. Tell the user what you were trying to do.`;
+  }
+}
+
 function infoOf(outcome: ChainOutcome, interceptor: string): Record<string, unknown> {
   return outcome.results.find((r) => r.interceptor === interceptor)?.info ?? {};
 }
@@ -78,6 +108,7 @@ export class AdtlGateway {
   private readonly invoker: InterceptorInvoker;
   private readonly audit: AuditSink | undefined;
   private readonly log: GatewayLogger;
+  private readonly approvals: ApprovalBroker | undefined;
   private routes = new Map<string, Route>();
 
   constructor(opts: AdtlGatewayOptions) {
@@ -86,6 +117,7 @@ export class AdtlGateway {
     this.sessionId = opts.sessionId ?? randomUUID();
     this.audit = opts.audit;
     this.log = opts.logger ?? stderrLogger;
+    this.approvals = opts.approvals;
   }
 
   /** The downstream MCP server the agent connects to. */
@@ -100,7 +132,15 @@ export class AdtlGateway {
       },
     );
     server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: await this.listTools() }));
-    server.setRequestHandler(CallToolRequestSchema, async (req) => this.callTool(req.params.name, req.params.arguments ?? {}));
+    server.setRequestHandler(CallToolRequestSchema, async (req, extra) => {
+      const progressToken = req.params._meta?.progressToken;
+      const progress =
+        progressToken === undefined
+          ? undefined
+          : (progress: number, message: string) =>
+              extra.sendNotification({ method: "notifications/progress", params: { progressToken, progress, message } });
+      return this.callTool(req.params.name, req.params.arguments ?? {}, progress ? { progress } : {});
+    });
     return server;
   }
 
@@ -127,7 +167,7 @@ export class AdtlGateway {
     return tools;
   }
 
-  async callTool(name: string, args: Record<string, unknown>): Promise<CallToolResult> {
+  async callTool(name: string, args: Record<string, unknown>, opts: CallOptions = {}): Promise<CallToolResult> {
     const started = performance.now();
     let route = this.routes.get(name);
     if (!route) {
@@ -154,12 +194,46 @@ export class AdtlGateway {
     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");
+    let approval: ApprovalResult | undefined;
     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 b = req.blocked;
+      const stopped = { decision: b.decision, reason: b.reason, matched: policy.matched, callHash: policy.callHash, sessionLabel: policy.sessionLabel };
+      const matched = Array.isArray(policy.matched) ? (policy.matched as string[]) : [];
+      if (b.decision === "ask" && this.approvals?.canApprove && typeof policy.callHash === "string") {
+        this.log.info(`ask ${name}: waiting for approval (${b.reason})`);
+        approval = await this.waitForApproval(opts, () =>
+          this.approvals!.request({
+            sessionId: this.sessionId,
+            server: route.upstream,
+            tool: route.tool,
+            callHash: policy.callHash as string,
+            reason: b.reason,
+            matched,
+            ...(policy.sessionLabel !== undefined ? { sessionLabel: policy.sessionLabel } : {}),
+          }),
+        );
+        this.log.info(`ask ${name}: ${approval.outcome}`);
+        if (approval.outcome !== "approved") {
+          finish({ outcome: "blocked", ...stopped, approval, warnings: req.warnings });
+          return textError(approvalMessage(b, approval), { ...b, callHash: policy.callHash, approval });
+        }
+      } else {
+        finish({ outcome: "blocked", ...stopped, warnings: req.warnings });
+        this.log.info(`${b.decision} ${name}: ${b.reason}`);
+        this.approvals?.blocked({ sessionId: this.sessionId, server: route.upstream, tool: route.tool, reason: b.reason, matched });
+        return textError(blockedMessage(b), { ...b, callHash: policy.callHash });
+      }
     }
     const forwarded = (req.payload as typeof requestPayload).params;
+    const decision = policy["adtl/decision"] as string | undefined;
+    const approved = approval ? { approval } : {};
+    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;
@@ -167,7 +241,7 @@ export class AdtlGateway {
       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: "allow", reason, callHash: policy.callHash, warnings: req.warnings });
+      finish({ outcome: "upstream_error", ...(decision ? { decision } : {}), ...approved, 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" });
     }
 
@@ -187,7 +261,11 @@ export class AdtlGateway {
     const label = infoOf(res, "adtl.label");
     finish({
       outcome: "forwarded",
-      decision: (policy["adtl/decision"] as string | undefined) ?? "allow",
+      // Missing only if adtl.policy failed and was allowed to (audit mode); see warnings.
+      ...(decision ? { decision } : {}),
+      ...(wouldStop ?? {}),
+      ...approved,
+      ...(audit ? { mode: "audit" as const } : {}),
       callHash: policy.callHash,
       label: label.label,
       sessionLabel: label.sessionLabel,
@@ -195,4 +273,18 @@ export class AdtlGateway {
     });
     return (res.payload as { result: CallToolResult }).result;
   }
+
+  /** Run an approval request, reporting progress to the client while it waits. */
+  private async waitForApproval(opts: CallOptions, ask: () => Promise<ApprovalResult>): Promise<ApprovalResult> {
+    if (!opts.progress) return ask();
+    let n = 0;
+    const report = () => void opts.progress!(++n, "Waiting for a human to approve this call").catch(() => undefined);
+    report();
+    const timer = setInterval(report, PROGRESS_INTERVAL_MS);
+    try {
+      return await ask();
+    } finally {
+      clearInterval(timer);
+    }
+  }
 }

package/src/index.ts

@@ -1,5 +1,8 @@
 export * from "./config.js";
 export * from "./invoker.js";
 export * from "./audit.js";
+export * from "./approvals.js";
+export * from "./ntfy.js";
+export * from "./email.js";
 export * from "./gateway.js";
 export * from "./startup.js";

package/src/invoker.ts

@@ -9,6 +9,9 @@
  * 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 {
@@ -35,6 +38,8 @@ function request(client: Client, method: string, params: unknown, timeout: numbe
   return r.call(client, { method, params }, AnyResult, { timeout });
 }
 
+export type InterceptorMode = NonNullable<InterceptorDefinition["mode"]>;
+
 export interface BoundInterceptor {
   client: Client;
   definition: InterceptorDefinition;
@@ -76,6 +81,8 @@ 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. */
@@ -103,6 +110,10 @@ export class InterceptorInvoker {
     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));
   }
@@ -120,7 +131,7 @@ export class InterceptorInvoker {
   /** 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 (i.definition.mode === "audit" || i.definition.failOpen === true) {
+    if (this.isAudit(i) || i.definition.failOpen === true) {
       out.warnings.push(msg);
       return true;
     }
@@ -143,7 +154,7 @@ export class InterceptorInvoker {
         continue;
       }
       out.results.push(r);
-      if (i.definition.mode !== "audit" && r.modified) payload = r.payload;
+      if (!this.isAudit(i) && r.modified) payload = r.payload;
     }
     out.payload = payload;
     return true;
@@ -162,11 +173,12 @@ export class InterceptorInvoker {
       }
       const r = s.value as ValidationResult;
       out.results.push(r);
-      if (r.valid || r.severity !== "error" || i.definition.mode === "audit") return;
-      if (!out.blocked) {
+      if (r.valid || r.severity !== "error" || this.isAudit(i)) return;
+      // Keep the strictest rejection, so an "ask" never hides another validator's "block".
+      if (!out.blocked || out.blocked.decision === "ask") {
         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 };
+        if (!out.blocked || decision === "block") out.blocked = { interceptor: i.definition.name, decision, reason };
       }
       ok = false;
     });

package/src/ntfy.ts

@@ -0,0 +1,154 @@
+/**
+ * ntfy (https://ntfy.sh) push notifications with Allow / Deny buttons.
+ *
+ * The buttons make the phone POST a signed answer token to a reply topic on
+ * the same ntfy server, and the gateway subscribes to that topic. So answers
+ * reach the gateway without it ever accepting inbound connections.
+ *
+ * Messages name the tool, server and reason, never arguments or results.
+ * Anyone who can read the topic can press the buttons, so use a long random
+ * topic name or an access-controlled topic on your own server.
+ */
+import type { AnswerFn, ApprovalEvent, ApprovalRequest, Notifier } from "./approvals.js";
+
+export interface NtfyOptions {
+  /** Server base URL, e.g. https://ntfy.sh */
+  server: string;
+  topic: string;
+  /** Topic answers are posted to. Default: `<topic>-reply`. */
+  replyTopic?: string;
+  /** Access token for protected topics. */
+  token?: string;
+  fetch?: typeof fetch;
+  /** Delay before re-subscribing after the stream drops, and the base delay between publish retries. */
+  reconnectMs?: number;
+  /** Publish attempts before giving up (network errors, 429 and 5xx are retried). */
+  publishAttempts?: number;
+}
+
+function describe(request: ApprovalRequest): string {
+  const secs = Math.max(0, Math.round((request.expiresAt.getTime() - request.createdAt.getTime()) / 1000));
+  return `${request.reason}\n\nRule: ${request.matched.join(", ") || "default"}\nExpires in ${secs}s; no answer means deny.`;
+}
+
+export class NtfyNotifier implements Notifier {
+  readonly name = "ntfy";
+  private readonly server: string;
+  private readonly topic: string;
+  private readonly replyTopic: string;
+  private readonly token: string | undefined;
+  private readonly fetch: typeof fetch;
+  private readonly reconnectMs: number;
+  private readonly publishAttempts: number;
+
+  constructor(opts: NtfyOptions) {
+    this.server = opts.server.replace(/\/+$/, "");
+    this.topic = opts.topic;
+    this.replyTopic = opts.replyTopic ?? `${opts.topic}-reply`;
+    this.token = opts.token;
+    this.fetch = opts.fetch ?? globalThis.fetch;
+    this.reconnectMs = opts.reconnectMs ?? 1000;
+    this.publishAttempts = opts.publishAttempts ?? 3;
+  }
+
+  private get auth(): Record<string, string> {
+    return this.token ? { Authorization: `Bearer ${this.token}` } : {};
+  }
+
+  async notify(event: ApprovalEvent): Promise<void> {
+    if (event.kind === "blocked") return; // push is for decisions; email covers blocked notices
+    const { request } = event;
+    const subject = `${request.server}.${request.tool}`;
+    let message: Record<string, unknown>;
+    if (event.kind === "pending") {
+      const reply = `${this.server}/${encodeURIComponent(this.replyTopic)}`;
+      const button = (label: string, body: string) => ({
+        action: "http",
+        label,
+        url: reply,
+        method: "POST",
+        body,
+        clear: true,
+        ...(this.token ? { headers: this.auth } : {}),
+      });
+      message = {
+        title: `ADTL: allow ${subject}?`,
+        message: describe(request),
+        priority: 4,
+        tags: ["warning"],
+        actions: [button("Allow", event.tokens.allow), button("Deny", event.tokens.deny)],
+      };
+    } else {
+      message = {
+        title: `ADTL: ${subject} ${event.result.outcome}`,
+        message: `Approval ${event.result.outcome} after ${Math.round(event.result.waitedMs / 1000)}s.`,
+        priority: 2,
+        tags: [event.result.outcome === "approved" ? "white_check_mark" : "x"],
+      };
+    }
+    await this.publish(JSON.stringify({ topic: this.topic, ...message }));
+  }
+
+  /** POST with retries: flaky networks should not turn an approval request into a denial. */
+  private async publish(body: string): Promise<void> {
+    for (let attempt = 1; ; attempt++) {
+      let res: Response | undefined;
+      try {
+        res = await this.fetch(this.server, { method: "POST", headers: { "Content-Type": "application/json", ...this.auth }, body });
+      } catch (err) {
+        if (attempt >= this.publishAttempts) throw err;
+      }
+      if (res?.ok) return;
+      if (res && ((res.status !== 429 && res.status < 500) || attempt >= this.publishAttempts)) {
+        throw new Error(`ntfy publish failed: HTTP ${res.status}`);
+      }
+      await new Promise((r) => setTimeout(r, this.reconnectMs * attempt));
+    }
+  }
+
+  async listen(request: ApprovalRequest, answer: AnswerFn, signal: AbortSignal): Promise<void> {
+    // `since` replays anything posted after the request was created, so a fast
+    // answer is not lost while (re)connecting.
+    const since = Math.floor(request.createdAt.getTime() / 1000) - 1;
+    const url = `${this.server}/${encodeURIComponent(this.replyTopic)}/json?since=${since}`;
+    while (!signal.aborted) {
+      try {
+        const res = await this.fetch(url, { headers: this.auth, signal });
+        if (!res.ok || !res.body) throw new Error(`ntfy subscribe failed: HTTP ${res.status}`);
+        await this.read(res.body, answer, signal);
+      } catch (err) {
+        if (signal.aborted) return;
+        if ((err as Error).message.includes("HTTP 401") || (err as Error).message.includes("HTTP 403")) throw err;
+      }
+      if (!signal.aborted) await sleep(this.reconnectMs, signal);
+    }
+  }
+
+  private async read(body: ReadableStream<Uint8Array>, answer: AnswerFn, signal: AbortSignal): Promise<void> {
+    const decoder = new TextDecoder();
+    let buf = "";
+    for await (const chunk of body as unknown as AsyncIterable<Uint8Array>) {
+      if (signal.aborted) return;
+      buf += decoder.decode(chunk, { stream: true });
+      let nl: number;
+      while ((nl = buf.indexOf("\n")) >= 0) {
+        const line = buf.slice(0, nl).trim();
+        buf = buf.slice(nl + 1);
+        if (!line) continue;
+        try {
+          const msg = JSON.parse(line) as { event?: string; message?: string };
+          if (msg.event === "message" && typeof msg.message === "string") answer(msg.message);
+        } catch {
+          // Not JSON: ignore.
+        }
+      }
+    }
+  }
+}
+
+function sleep(ms: number, signal: AbortSignal): Promise<void> {
+  return new Promise((resolve) => {
+    const t = setTimeout(resolve, ms);
+    signal.addEventListener("abort", () => (clearTimeout(t), resolve()), { once: true });
+  });
+}

package/src/startup.ts

@@ -12,17 +12,21 @@ import { INTERCEPTORS_EXTENSION, LABEL_INTERCEPTOR, POLICY_INTERCEPTOR, parseCon
 import type { AdtlConfig } from "@adtl/labels";
 import { parse as parseYaml } from "yaml";
 import { ZodError } from "zod";
+import { ApprovalBroker, type Notifier } from "./approvals.js";
 import { JsonlAuditLog } from "./audit.js";
 import {
   GatewayConfigSchema,
+  expandApprovals,
   expandUpstream,
   isHttpUpstream,
   type GatewayConfig,
   type StdioUpstream,
   type Upstream,
 } from "./config.js";
+import { EmailNotifier } from "./email.js";
 import { AdtlGateway, GATEWAY_VERSION, type GatewayLogger } from "./gateway.js";
 import { InterceptorInvoker } from "./invoker.js";
+import { NtfyNotifier } from "./ntfy.js";
 
 export class GatewayConfigError extends Error {
   constructor(message: string) {
@@ -93,6 +97,26 @@ async function connect(id: string, u: Upstream, baseDir: string): Promise<Client
   return client;
 }
 
+/** Build the approval broker from `gateway.approvals`, or undefined if not configured. */
+export function createApprovals(cfg: GatewayConfig, env: NodeJS.ProcessEnv, log: GatewayLogger): ApprovalBroker | undefined {
+  if (!cfg.approvals) return undefined;
+  const a = expandApprovals(cfg.approvals, env);
+  const notifiers: Notifier[] = [];
+  if (a.ntfy) {
+    if (/^https:\/\/ntfy\.sh\/?$/.test(a.ntfy.server) && a.ntfy.topic.length < 20 && !a.ntfy.token) {
+      log.warn("gateway.approvals.ntfy.topic is short and on the public ntfy.sh server: anyone who guesses it can approve calls. Use a long random topic.");
+    }
+    notifiers.push(new NtfyNotifier(a.ntfy));
+  }
+  if (a.email) {
+    notifiers.push(new EmailNotifier({ smtp: a.email.smtp, from: a.email.from, to: [a.email.to].flat(), on: a.email.on }));
+  }
+  if (notifiers.length === 0) return undefined;
+  if (!notifiers.some((n) => n.listen)) log.warn('no approval channel can carry answers (configure gateway.approvals.ntfy); "ask" still blocks');
+  log.info(`approvals: ${notifiers.map((n) => n.name).join(", ")} (timeout ${a.timeoutSeconds}s)`);
+  return new ApprovalBroker({ notifiers, timeoutMs: a.timeoutSeconds * 1000, log });
+}
+
 export interface StartedGateway {
   gateway: AdtlGateway;
   close(): Promise<void>;
@@ -125,8 +149,10 @@ export async function startGateway(
         throw new GatewayConfigError(`The interceptor server does not offer ${required}; refusing to start without it`);
       }
     }
-    const invoker = new InterceptorInvoker(bound, loaded.gateway.interceptorTimeoutMs);
+    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>();
@@ -149,8 +175,15 @@ export async function startGateway(
     if (upstreams.size === 0) throw new GatewayConfigError("No upstream server could be connected");
     log.info(`upstreams: ${[...upstreams.keys()].join(", ")}`);
 
-    const audit = loaded.gateway.audit ? new JsonlAuditLog(resolve(baseDir, loaded.gateway.audit)) : undefined;
-    const gateway = new AdtlGateway({ upstreams, invoker, ...(audit ? { audit } : {}), logger: log });
+    const auditLog = loaded.gateway.audit ? new JsonlAuditLog(resolve(baseDir, loaded.gateway.audit)) : undefined;
+    const approvals = createApprovals(loaded.gateway, env, log);
+    const gateway = new AdtlGateway({
+      upstreams,
+      invoker,
+      ...(auditLog ? { audit: auditLog } : {}),
+      ...(approvals ? { approvals } : {}),
+      logger: log,
+    });
     return { gateway, close: closeAll };
   } catch (err) {
     await closeAll();