@adtl/gateway 0.1.1 → 0.3.0

package/src/init/suggest.ts

@@ -0,0 +1,127 @@
+/**
+ * Draft ADTL rules for an upstream's tools, and merge them into adtl.yaml.
+ *
+ * Without a preset, rules come from the MCP tool annotations. Those are the
+ * server's own claims, so they only decide egress; integrity is always
+ * untrusted and confidentiality private until the owner says otherwise.
+ * Missing hints take the MCP spec defaults (readOnlyHint false, openWorldHint true).
+ *
+ * Merging never changes an entry that is already in the file: the owner's
+ * choices win, and `init` can be re-run to pick up new tools.
+ */
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import type { ToolRule } from "@adtl/labels";
+import { isMap, isScalar, type Document, type YAMLMap } from "yaml";
+import { choosePreset, PRESETS, type Preset } from "./presets.js";
+
+export interface ServerScan {
+  /** Upstream id in gateway.upstreams. */
+  id: string;
+  /** `serverInfo.name` the server reported. */
+  serverName?: string;
+  tools: Pick<Tool, "name" | "annotations">[];
+}
+
+export interface ToolSuggestion {
+  name: string;
+  rule: ToolRule;
+  /** Short reason, written as a comment next to the rule. */
+  why: string;
+}
+
+export interface ServerSuggestion {
+  id: string;
+  preset?: Preset;
+  defaults: ToolRule;
+  tools: ToolSuggestion[];
+}
+
+const UNKNOWN_DEFAULTS: ToolRule = { integrity: "untrusted", confidentiality: "private" };
+
+/** A rule from the tool's MCP annotations alone. */
+export function ruleFromHints(annotations: Tool["annotations"]): Omit<ToolSuggestion, "name"> {
+  const readOnly = annotations?.readOnlyHint === true;
+  const openWorld = annotations?.openWorldHint !== false;
+  const egress = readOnly ? (openWorld ? "external" : "none") : openWorld ? "public" : "internal";
+  const why = `hints: ${readOnly ? "read-only" : "writes"}, ${openWorld ? "open world" : "closed world"} (review)`;
+  return { rule: { integrity: "untrusted", confidentiality: "private", egress }, why };
+}
+
+export function suggest(scan: ServerScan, presets = PRESETS): ServerSuggestion {
+  const preset = choosePreset(scan.id, scan.serverName, presets);
+  const tools = scan.tools.map(({ name, annotations }): ToolSuggestion => {
+    if (!preset) return { name, ...ruleFromHints(annotations) };
+    const override = preset.tools?.[name];
+    if (override) return { name, rule: override, why: `preset ${preset.id}` };
+    const read = annotations?.readOnlyHint === true;
+    return { name, rule: read ? preset.read : preset.write, why: `preset ${preset.id}: ${read ? "read" : "write"}` };
+  });
+  return { id: scan.id, ...(preset ? { preset } : {}), defaults: preset?.defaults ?? UNKNOWN_DEFAULTS, tools };
+}
+
+export interface MergeReport {
+  id: string;
+  preset?: string;
+  added: string[];
+  /** Tools already configured; left as they were. */
+  kept: string[];
+  /** Configured tools the server no longer offers. Left in place, reported only. */
+  stale: string[];
+  addedDefaults: boolean;
+}
+
+function mapAt(doc: Document, parent: YAMLMap, key: string, commentBefore?: string): YAMLMap {
+  const existing = parent.get(key, true);
+  if (isMap(existing)) return existing;
+  const map = doc.createNode({}) as YAMLMap;
+  const k = doc.createNode(key);
+  if (commentBefore && isScalar(k)) k.commentBefore = ` ${commentBefore}`;
+  parent.add(doc.createPair(k, map));
+  return map;
+}
+
+/** Add the suggestions to the document's `servers:` section, keeping every existing entry. */
+export function mergeIntoDocument(doc: Document, suggestions: ServerSuggestion[]): MergeReport[] {
+  let servers = doc.get("servers", true);
+  if (!isMap(servers)) {
+    servers = doc.createNode({}) as YAMLMap;
+    // Put servers: first, ahead of policy: and gateway:.
+    const root = doc.contents;
+    if (isMap(root)) root.items.unshift(doc.createPair("servers", servers));
+    else doc.contents = doc.createNode({ servers }) as never;
+  }
+  const serversMap = servers as YAMLMap;
+
+  return suggestions.map((s) => {
+    const report: MergeReport = { id: s.id, added: [], kept: [], stale: [], addedDefaults: false };
+    if (s.preset) report.preset = s.preset.id;
+    const isNew = !serversMap.has(s.id);
+    const server = mapAt(doc, serversMap, s.id, isNew ? (s.preset?.note ?? "from MCP tool hints: review every line") : undefined);
+
+    if (!server.has("defaults")) {
+      const d = doc.createNode(s.defaults, { flow: true });
+      d.comment = " resources, prompts, and tools not listed below";
+      server.items.unshift(doc.createPair("defaults", d));
+      report.addedDefaults = true;
+    }
+
+    const tools = mapAt(doc, server, "tools");
+    tools.flow = false;
+    const offered = new Set(s.tools.map((t) => t.name));
+    for (const t of s.tools) {
+      if (tools.has(t.name)) {
+        report.kept.push(t.name);
+        continue;
+      }
+      const v = doc.createNode(t.rule, { flow: true });
+      v.comment = ` ${t.why}`;
+      tools.set(t.name, v);
+      report.added.push(t.name);
+    }
+    for (const item of tools.items) {
+      const name = isScalar(item.key) ? String(item.key.value) : String(item.key);
+      if (!offered.has(name)) report.stale.push(name);
+    }
+    return report;
+  });
+}

package/src/invoker.ts

@@ -174,10 +174,11 @@ export class InterceptorInvoker {
       const r = s.value as ValidationResult;
       out.results.push(r);
       if (r.valid || r.severity !== "error" || this.isAudit(i)) return;
-      if (!out.blocked) {
+      // 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) {
@@ -84,7 +88,7 @@ function stdioTransport(u: StdioUpstream, baseDir: string): StdioClientTransport
   });
 }
 
-async function connect(id: string, u: Upstream, baseDir: string): Promise<Client> {
+export async function connectUpstream(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 } })
@@ -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>;
@@ -113,7 +137,7 @@ export async function startGateway(
     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);
+    const interceptors = await connectUpstream("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`);
@@ -134,7 +158,7 @@ export async function startGateway(
     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)),
+      ids.map((id) => connectUpstream(id, expandUpstream(id, loaded.gateway.upstreams[id]!, env), baseDir)),
     );
     settled.forEach((s, i) => {
       const id = ids[i]!;
@@ -152,7 +176,14 @@ export async function startGateway(
     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 });
+    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();