@adtl/gateway 0.1.1 → 0.2.0

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) {
@@ -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>;
@@ -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();