@adtl/gateway 0.1.1 → 0.3.0

package/dist/startup.js

@@ -11,10 +11,13 @@ import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/
 import { INTERCEPTORS_EXTENSION, LABEL_INTERCEPTOR, POLICY_INTERCEPTOR, parseConfigText } from "@adtl/interceptors";
 import { parse as parseYaml } from "yaml";
 import { ZodError } from "zod";
+import { ApprovalBroker } from "./approvals.js";
 import { JsonlAuditLog } from "./audit.js";
-import { GatewayConfigSchema, expandUpstream, isHttpUpstream, } from "./config.js";
+import { GatewayConfigSchema, expandApprovals, expandUpstream, isHttpUpstream, } from "./config.js";
+import { EmailNotifier } from "./email.js";
 import { AdtlGateway, GATEWAY_VERSION } from "./gateway.js";
 import { InterceptorInvoker } from "./invoker.js";
+import { NtfyNotifier } from "./ntfy.js";
 export class GatewayConfigError extends Error {
     constructor(message) {
         super(message);
@@ -68,7 +71,7 @@ function stdioTransport(u, baseDir) {
         stderr: "inherit",
     });
 }
-async function connect(id, u, baseDir) {
+export async function connectUpstream(id, u, baseDir) {
     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 } })
@@ -76,6 +79,28 @@ async function connect(id, u, baseDir) {
     await client.connect(transport);
     return client;
 }
+/** Build the approval broker from `gateway.approvals`, or undefined if not configured. */
+export function createApprovals(cfg, env, log) {
+    if (!cfg.approvals)
+        return undefined;
+    const a = expandApprovals(cfg.approvals, env);
+    const notifiers = [];
+    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 async function startGateway(loaded, opts = {}) {
     const env = opts.env ?? process.env;
     const baseDir = dirname(loaded.path);
@@ -87,7 +112,7 @@ export async function startGateway(loaded, opts = {}) {
         const icfg = 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`);
@@ -107,7 +132,7 @@ export async function startGateway(loaded, opts = {}) {
         // 2. Upstream servers. One failing upstream does not stop the others.
         const upstreams = new Map();
         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)));
+        const settled = await Promise.allSettled(ids.map((id) => connectUpstream(id, expandUpstream(id, loaded.gateway.upstreams[id], env), baseDir)));
         settled.forEach((s, i) => {
             const id = ids[i];
             if (s.status === "fulfilled") {
@@ -125,7 +150,14 @@ export async function startGateway(loaded, opts = {}) {
             throw new GatewayConfigError("No upstream server could be connected");
         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) {

package/dist/startup.js.map

@@ -1 +1 @@
-{"version":3,"file":"startup.js","sourceRoot":"","sources":["../src/startup.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"startup.js","sourceRoot":"","sources":["../src/startup.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adtl/gateway",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "Experimental: MCP gateway that labels every tool result and blocks risky tool calls using ADTL trust labels",
   "keywords": [
     "mcp",
@@ -46,9 +46,10 @@
     "url": "https://github.com/probita-ai/adtl/issues"
   },
   "dependencies": {
-    "@adtl/interceptors": "0.1.1",
-    "@adtl/labels": "0.1.1",
+    "@adtl/interceptors": "0.3.0",
+    "@adtl/labels": "0.3.0",
     "@modelcontextprotocol/sdk": "1.31.0",
+    "nodemailer": "10.0.12",
     "yaml": "2.9.1",
     "zod": "3.25.76"
   },

package/src/approvals.ts

@@ -0,0 +1,219 @@
+/**
+ * Human approvals for "ask" decisions.
+ *
+ * When adtl.policy answers `ask`, the gateway holds the call and asks the
+ * broker. The broker sends the request to every notifier and waits for an
+ * answer from a notifier that can carry one (e.g. ntfy). No answer before the
+ * timeout means deny.
+ *
+ * Answers are signed tokens: HMAC over the approval id, the call's hash, the
+ * decision and an expiry. A token only ever answers the one pending call it
+ * was made for, and only once. Anyone who can read the push channel can still
+ * use the tokens sent on it, so that channel must stay private.
+ */
+import { createHmac, randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
+
+export type ApprovalDecision = "allow" | "deny";
+export type ApprovalOutcome = "approved" | "denied" | "timeout" | "undeliverable";
+
+export interface ApprovalRequest {
+  id: string;
+  sessionId: string;
+  server: string;
+  tool: string;
+  callHash: string;
+  reason: string;
+  matched: string[];
+  /** The session label that triggered the rule (no arguments or results). */
+  sessionLabel?: unknown;
+  createdAt: Date;
+  expiresAt: Date;
+}
+
+export interface ApprovalResult {
+  outcome: ApprovalOutcome;
+  /** Notifier that delivered the answer. */
+  channel?: string;
+  approver?: string;
+  waitedMs: number;
+}
+
+export type ApprovalEvent =
+  | { kind: "pending"; request: ApprovalRequest; tokens: Record<ApprovalDecision, string> }
+  | { kind: "resolved"; request: ApprovalRequest; result: ApprovalResult }
+  | { kind: "blocked"; sessionId: string; server: string; tool: string; reason: string; matched: string[] };
+
+/** Called by a notifier with every answer it receives. Returns true if the answer was accepted. */
+export type AnswerFn = (token: string, approver?: string) => boolean;
+
+export interface Notifier {
+  readonly name: string;
+  /** Deliver an event. Throwing marks the delivery as failed; it never stops the call by itself. */
+  notify(event: ApprovalEvent): Promise<void>;
+  /**
+   * Notifiers that can carry answers: pass every answer for `request` to
+   * `answer` until `signal` aborts. Called before the pending event is sent.
+   */
+  listen?(request: ApprovalRequest, answer: AnswerFn, signal: AbortSignal): Promise<void>;
+}
+
+const TOKEN_PREFIX = "adtl1";
+
+/** Error message plus its cause, e.g. "fetch failed (ECONNRESET)". */
+export function errorText(err: unknown): string {
+  if (!(err instanceof Error)) return String(err);
+  const cause = err.cause as { code?: string; message?: string } | undefined;
+  const detail = cause?.code ?? cause?.message;
+  return detail && !err.message.includes(detail) ? `${err.message} (${detail})` : err.message;
+}
+
+export class ApprovalTokens {
+  constructor(private readonly secret: Buffer = randomBytes(32)) {}
+
+  sign(request: Pick<ApprovalRequest, "id" | "callHash" | "expiresAt">, decision: ApprovalDecision): string {
+    const exp = Math.floor(request.expiresAt.getTime() / 1000);
+    return `${TOKEN_PREFIX}.${request.id}.${decision}.${exp}.${this.mac(request.id, request.callHash, decision, exp)}`;
+  }
+
+  /** Parse a token without verifying it. */
+  static parse(token: string): { id: string; decision: ApprovalDecision; exp: number; sig: string } | undefined {
+    const parts = token.trim().split(".");
+    if (parts.length !== 5 || parts[0] !== TOKEN_PREFIX) return undefined;
+    const [, id, decision, exp, sig] = parts as [string, string, string, string, string];
+    if (decision !== "allow" && decision !== "deny") return undefined;
+    if (!/^\d+$/.test(exp)) return undefined;
+    return { id, decision, exp: Number(exp), sig };
+  }
+
+  /** Verify a token against the pending request it claims to answer. */
+  verify(token: string, request: Pick<ApprovalRequest, "id" | "callHash">, now: Date): ApprovalDecision | undefined {
+    const t = ApprovalTokens.parse(token);
+    if (!t || t.id !== request.id) return undefined;
+    if (now.getTime() > t.exp * 1000) return undefined;
+    const expected = Buffer.from(this.mac(t.id, request.callHash, t.decision, t.exp));
+    const given = Buffer.from(t.sig);
+    if (given.length !== expected.length || !timingSafeEqual(given, expected)) return undefined;
+    return t.decision;
+  }
+
+  private mac(id: string, callHash: string, decision: ApprovalDecision, exp: number): string {
+    return createHmac("sha256", this.secret).update(`${id}\n${callHash}\n${decision}\n${exp}`).digest("base64url");
+  }
+}
+
+export interface ApprovalBrokerOptions {
+  notifiers: Notifier[];
+  timeoutMs: number;
+  tokens?: ApprovalTokens;
+  now?: () => Date;
+  log?: { warn(msg: string): void };
+}
+
+interface Pending {
+  request: ApprovalRequest;
+  settle(decision: ApprovalDecision, channel: string, approver?: string): void;
+}
+
+export class ApprovalBroker {
+  private readonly notifiers: Notifier[];
+  private readonly timeoutMs: number;
+  private readonly tokens: ApprovalTokens;
+  private readonly now: () => Date;
+  private readonly log: { warn(msg: string): void };
+  private readonly pending = new Map<string, Pending>();
+
+  constructor(opts: ApprovalBrokerOptions) {
+    this.notifiers = opts.notifiers;
+    this.timeoutMs = opts.timeoutMs;
+    this.tokens = opts.tokens ?? new ApprovalTokens();
+    this.now = opts.now ?? (() => new Date());
+    this.log = opts.log ?? { warn: () => {} };
+  }
+
+  /** True if at least one notifier can carry answers. Without one, "ask" stays a block. */
+  get canApprove(): boolean {
+    return this.notifiers.some((n) => n.listen);
+  }
+
+  /** Ask for approval and wait for the answer, the timeout, or a failure to reach anyone. */
+  async request(input: Omit<ApprovalRequest, "id" | "createdAt" | "expiresAt">): Promise<ApprovalResult> {
+    const createdAt = this.now();
+    const request: ApprovalRequest = {
+      ...input,
+      id: randomUUID(),
+      createdAt,
+      expiresAt: new Date(createdAt.getTime() + this.timeoutMs),
+    };
+    const started = performance.now();
+    const waited = () => Math.round(performance.now() - started);
+    const abort = new AbortController();
+
+    let finish!: (r: ApprovalResult) => void;
+    const result = new Promise<ApprovalResult>((resolve) => {
+      const timer = setTimeout(() => finish({ outcome: "timeout", waitedMs: waited() }), this.timeoutMs);
+      finish = (r) => {
+        if (!this.pending.delete(request.id)) return; // already settled
+        clearTimeout(timer);
+        abort.abort();
+        resolve(r);
+      };
+    });
+    this.pending.set(request.id, {
+      request,
+      settle: (decision, channel, approver) =>
+        finish({ outcome: decision === "allow" ? "approved" : "denied", channel, ...(approver ? { approver } : {}), waitedMs: waited() }),
+    });
+
+    // Start listening before anyone can answer, then send the request everywhere.
+    const listeners = this.notifiers.filter((n) => n.listen);
+    for (const n of listeners) {
+      n.listen!(request, (token, approver) => this.answer(token, n.name, approver), abort.signal).catch((err: unknown) =>
+        this.log.warn(`${n.name}: stopped listening for approvals: ${errorText(err)}`),
+      );
+    }
+    const tokens = { allow: this.tokens.sign(request, "allow"), deny: this.tokens.sign(request, "deny") };
+    const sent = this.notifiers.map((n) =>
+      n.notify({ kind: "pending", request, tokens }).then(
+        () => true,
+        (err: unknown) => {
+          this.log.warn(`${n.name}: could not send approval request: ${errorText(err)}`);
+          return false;
+        },
+      ),
+    );
+    // Nobody who could answer was reached: deny now rather than wait out the timeout.
+    // Notify-only channels (email) are not waited for.
+    void Promise.all(sent.filter((_, i) => this.notifiers[i]!.listen)).then((ok) => {
+      if (!ok.includes(true)) finish({ outcome: "undeliverable", waitedMs: waited() });
+    });
+
+    const r = await result;
+    this.broadcast({ kind: "resolved", request, result: r });
+    return r;
+  }
+
+  /** Handle an answer token from a channel. Returns true if it settled a pending approval. */
+  answer(token: string, channel: string, approver?: string): boolean {
+    const parsed = ApprovalTokens.parse(token);
+    const p = parsed && this.pending.get(parsed.id);
+    if (!p) return false; // not ours, already answered, or garbage
+    const decision = this.tokens.verify(token, p.request, this.now());
+    if (!decision) {
+      this.log.warn(`${channel}: ignored an approval answer with a bad or expired signature`);
+      return false;
+    }
+    p.settle(decision, channel, approver);
+    return true;
+  }
+
+  /** Tell notifiers a call was blocked. Fire and forget. */
+  blocked(event: Omit<Extract<ApprovalEvent, { kind: "blocked" }>, "kind">): void {
+    this.broadcast({ kind: "blocked", ...event });
+  }
+
+  private broadcast(event: ApprovalEvent): void {
+    for (const n of this.notifiers) {
+      n.notify(event).catch((err: unknown) => this.log.warn(`${n.name}: could not send ${event.kind} notice: ${errorText(err)}`));
+    }
+  }
+}

package/src/audit.ts

@@ -1,5 +1,5 @@
 /**
- * Append-only JSONL audit log. One line per tool call.
+ * Append-only JSONL audit log. One line per tool call, resource read or prompt get.
  *
  * Arguments and results are never written; the call is identified by its
  * hash, so the log can be shared without leaking the data it describes.
@@ -10,15 +10,20 @@ import { dirname } from "node:path";
 export interface AuditEntry {
   ts: string;
   sessionId: string;
-  event: "tools/call";
+  event: "tools/call" | "resources/read" | "prompts/get";
   server: string;
-  tool: string;
+  /** Exactly one of tool, resource or prompt is set, matching `event`. */
+  tool?: string;
+  resource?: string;
+  prompt?: string;
   /** Final outcome of the call. */
   outcome: "forwarded" | "blocked" | "upstream_error";
   /** The policy's decision. In audit mode a call can be forwarded with decision "ask" or "block". */
   decision?: string;
   /** Present when the gateway ran in audit mode: nothing was stopped or changed. */
   mode?: "audit";
+  /** Present when a human was asked: outcome, channel, approver (if known) and wait time. */
+  approval?: { outcome: string; channel?: string; approver?: string; waitedMs: number };
   reason?: string;
   matched?: unknown;
   callHash?: unknown;

package/src/cli.ts

@@ -4,6 +4,7 @@
  * servers through ADTL's interceptors.
  *
  *   adtl-gateway --config adtl.yaml [--audit]
+ *   adtl-gateway init --config adtl.yaml [--write]
  *
  * Point your MCP client (e.g. Claude Code's .mcp.json) at this command.
  * Logs go to stderr; stdout carries MCP JSON-RPC only.
@@ -11,9 +12,11 @@
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { EnvExpansionError } from "./config.js";
 import { GATEWAY_VERSION } from "./gateway.js";
+import { runInit, type InitResult } from "./init/run.js";
 import { GatewayConfigError, loadGatewayConfig, startGateway } from "./startup.js";
 
 const USAGE = `Usage: adtl-gateway --config <adtl.yaml> [--audit]
+       adtl-gateway init --config <adtl.yaml> [--write]
 
 Runs an MCP server over stdio that forwards tool calls to the upstream
 servers in the config, checking and labeling each call with ADTL.
@@ -23,9 +26,18 @@ Options:
       --audit          Log what would be stopped, but stop nothing
                        (same as gateway.mode: audit).
   -v, --version        Print the version and exit.
+
+init:
+  Connects to every upstream, lists its tools, and drafts a labeling rule
+  for each tool the config doesn't cover yet (presets for GitHub,
+  filesystem and fetch; MCP tool hints otherwise). Existing entries are
+  never changed. Prints the updated config; review it before using it.
+      --write          Update the config file in place (original kept as .bak).
   -h, --help           Show this help.`;
 
 interface Args {
+  init?: boolean;
+  write?: boolean;
   config?: string;
   audit?: boolean;
   help?: boolean;
@@ -36,11 +48,13 @@ function parseArgs(argv: string[]): Args {
   const out: Args = {};
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
-    if (a === "-h" || a === "--help") out.help = true;
+    if (i === 0 && a === "init") out.init = true;
+    else if (a === "-h" || a === "--help") out.help = true;
     else if (a === "-v" || a === "--version") out.version = true;
     else if (a === "-c" || a === "--config") out.config = argv[++i];
     else if (a?.startsWith("--config=")) out.config = a.slice("--config=".length);
     else if (a === "--audit") out.audit = true;
+    else if (a === "--write" && out.init) out.write = true;
     else throw new GatewayConfigError(`Unknown argument: ${a}\n\n${USAGE}`);
   }
   return out;
@@ -52,6 +66,7 @@ async function main(): Promise<void> {
   if (args.help) return void console.log(USAGE);
   if (args.version) return void console.log(GATEWAY_VERSION);
   if (!args.config) throw new GatewayConfigError(`Missing --config\n\n${USAGE}`);
+  if (args.init) return init(args.config, args.write === true);
 
   const loaded = await loadGatewayConfig(args.config);
   if (args.audit) loaded.gateway.mode = "audit";
@@ -77,6 +92,31 @@ async function main(): Promise<void> {
   console.error(`[adtl-gateway] ${GATEWAY_VERSION} ready (session ${started.gateway.sessionId})`);
 }
 
+function summarize(r: InitResult, path: string, write: boolean): string {
+  const lines = r.reports.map((s) => {
+    const parts = [`${s.added.length} tools added`];
+    if (s.kept.length) parts.push(`${s.kept.length} kept`);
+    if (s.addedDefaults) parts.push("defaults added");
+    if (s.stale.length) parts.push(`no longer offered: ${s.stale.join(", ")}`);
+    return `  ${s.id} (${s.preset ? `preset ${s.preset}` : "from tool hints, review"}): ${parts.join("; ")}`;
+  });
+  for (const f of r.failed) lines.push(`  ${f.id}: could not connect, skipped (${f.error})`);
+  const changed = r.reports.some((s) => s.added.length || s.addedDefaults);
+  const tail = !changed
+    ? "Nothing to add."
+    : write
+      ? `Updated ${path} (original saved as ${path}.bak). Review every line marked "review".`
+      : "Nothing written. Review the config above, then re-run with --write.";
+  return `${lines.join("\n")}\n${tail}`;
+}
+
+async function init(path: string, write: boolean): Promise<void> {
+  const result = await runInit({ path, write });
+  if (!write) process.stdout.write(result.text);
+  console.error(`[adtl-gateway] init\n${summarize(result, path, write)}`);
+  if (result.failed.length && !result.reports.length) process.exitCode = 1;
+}
+
 main().catch((err: unknown) => {
   const known = err instanceof GatewayConfigError || err instanceof EnvExpansionError;
   console.error(known ? `[adtl-gateway] ${(err as Error).message}` : err);

package/src/config.ts

@@ -12,11 +12,19 @@
  *       docs:
  *         url: https://example.com/mcp
  *         headers: { Authorization: "Bearer ${DOCS_TOKEN}" }
+ *     approvals:                         # optional: make "ask" really ask
+ *       timeoutSeconds: 50
+ *       ntfy: { topic: "${ADTL_NTFY_TOPIC}" }
+ *       email:
+ *         smtp: { host: smtp.example.com, port: 465, user: "${SMTP_USER}", pass: "${SMTP_PASS}" }
+ *         from: adtl@example.com
+ *         to: you@example.com
  *
- * `${VAR}` in command, args, env, cwd, url and headers is replaced from the
- * gateway's environment. A missing variable is a config error.
+ * `${VAR}` in command, args, env, cwd, url, headers and approval settings is
+ * replaced from the gateway's environment. A missing variable is a config error.
  */
 import { z } from "zod";
+import { EMAIL_EVENTS } from "./email.js";
 
 const UPSTREAM_ID = /^[A-Za-z0-9-]+$/;
 
@@ -41,6 +49,48 @@ export type StdioUpstream = z.infer<typeof StdioUpstreamSchema>;
 export type HttpUpstream = z.infer<typeof HttpUpstreamSchema>;
 export type Upstream = z.infer<typeof UpstreamSchema>;
 
+export const NtfyConfigSchema = z
+  .object({
+    server: z.string().min(1).default("https://ntfy.sh"),
+    /** Topic approval requests are sent to. Anyone who can read it can approve: keep it secret. */
+    topic: z.string().min(1),
+    /** Topic answers are posted to. Default: `<topic>-reply`. */
+    replyTopic: z.string().min(1).optional(),
+    token: z.string().min(1).optional(),
+  })
+  .strict();
+
+export const EmailConfigSchema = z
+  .object({
+    smtp: z
+      .object({
+        host: z.string().min(1),
+        port: z.number().int().positive().default(587),
+        /** TLS from the start. Default: true on port 465, otherwise STARTTLS. */
+        secure: z.boolean().optional(),
+        user: z.string().min(1).optional(),
+        pass: z.string().optional(),
+      })
+      .strict(),
+    from: z.string().min(1),
+    to: z.union([z.string().min(1), z.array(z.string().min(1)).nonempty()]),
+    on: z.array(z.enum(EMAIL_EVENTS)).nonempty().default(["pending", "blocked"]),
+  })
+  .strict();
+
+export const ApprovalsConfigSchema = z
+  .object({
+    /**
+     * How long a call waits for an answer; no answer means deny. Many MCP
+     * clients give up on a request after 60 seconds, hence the default.
+     */
+    timeoutSeconds: z.number().int().positive().max(3600).default(50),
+    ntfy: NtfyConfigSchema.optional(),
+    email: EmailConfigSchema.optional(),
+  })
+  .strict();
+export type ApprovalsConfig = z.infer<typeof ApprovalsConfigSchema>;
+
 export const GatewayConfigSchema = z
   .object({
     upstreams: z
@@ -58,6 +108,8 @@ export const GatewayConfigSchema = z
      * logs what would have been stopped: for trying a policy out safely.
      */
     mode: z.enum(["active", "audit"]).default("active"),
+    /** Human approvals for "ask" decisions. Without an answering channel, "ask" blocks. */
+    approvals: ApprovalsConfigSchema.optional(),
     /** Timeout for each interceptor invocation, in milliseconds. */
     interceptorTimeoutMs: z.number().int().positive().default(5000),
   })
@@ -101,6 +153,17 @@ export function expandUpstream<T extends Upstream>(id: string, u: T, env: NodeJS
   };
 }
 
+/** Expand `${VAR}` in every string of the approvals section. */
+export function expandApprovals(a: ApprovalsConfig, env: NodeJS.ProcessEnv): ApprovalsConfig {
+  const walk = (v: unknown, where: string): unknown => {
+    if (typeof v === "string") return expandEnv(v, env, where);
+    if (Array.isArray(v)) return v.map((x, i) => walk(x, `${where}[${i}]`));
+    if (v && typeof v === "object") return Object.fromEntries(Object.entries(v).map(([k, x]) => [k, walk(x, `${where}.${k}`)]));
+    return v;
+  };
+  return walk(a, "gateway.approvals") as ApprovalsConfig;
+}
+
 export function isHttpUpstream(u: Upstream): u is HttpUpstream {
   return "url" in u;
 }

package/src/email.ts

@@ -0,0 +1,79 @@
+/**
+ * Email notices over SMTP. Notify only, on purpose: emails never contain
+ * approve links, because mail security scanners open links automatically and
+ * would approve calls by themselves. Approving happens on the push channel.
+ *
+ * Emails name the tool, server and reason, never arguments or results.
+ */
+import nodemailer from "nodemailer";
+import type { ApprovalEvent, Notifier } from "./approvals.js";
+
+export const EMAIL_EVENTS = ["pending", "blocked", "approved", "denied", "timeout", "undeliverable"] as const;
+export type EmailEvent = (typeof EMAIL_EVENTS)[number];
+
+export interface MailSender {
+  sendMail(mail: { from: string; to: string[]; subject: string; text: string }): Promise<unknown>;
+}
+
+export interface EmailOptions {
+  from: string;
+  to: string[];
+  /** Which events send an email. */
+  on: EmailEvent[];
+  /** SMTP settings, used unless `sender` is given. */
+  smtp?: { host: string; port: number; secure?: boolean; user?: string; pass?: string };
+  sender?: MailSender;
+}
+
+export class EmailNotifier implements Notifier {
+  readonly name = "email";
+  private readonly sender: MailSender;
+
+  constructor(private readonly opts: EmailOptions) {
+    if (opts.sender) {
+      this.sender = opts.sender;
+    } else if (opts.smtp) {
+      const { host, port, secure, user, pass } = opts.smtp;
+      this.sender = nodemailer.createTransport({
+        host,
+        port,
+        secure: secure ?? port === 465,
+        ...(user !== undefined ? { auth: { user, pass } } : {}),
+      });
+    } else {
+      throw new Error("EmailNotifier needs smtp settings or a sender");
+    }
+  }
+
+  async notify(event: ApprovalEvent): Promise<void> {
+    const kind: EmailEvent = event.kind === "resolved" ? event.result.outcome : event.kind;
+    if (!this.opts.on.includes(kind)) return;
+    const { subject, text } = this.compose(event);
+    await this.sender.sendMail({ from: this.opts.from, to: this.opts.to, subject, text });
+  }
+
+  private compose(event: ApprovalEvent): { subject: string; text: string } {
+    const footer = "\n\n-- \nSent by ADTL (adtl-gateway). This email never contains approve links; approve on your push channel.";
+    if (event.kind === "blocked") {
+      return {
+        subject: `ADTL blocked ${event.server}.${event.tool}`,
+        text: `ADTL blocked a call to ${event.server}.${event.tool}.\n\nReason: ${event.reason}\nRule: ${event.matched.join(", ") || "default"}\nSession: ${event.sessionId}${footer}`,
+      };
+    }
+    const r = event.request;
+    const subject = `${r.server}.${r.tool}`;
+    if (event.kind === "pending") {
+      return {
+        subject: `ADTL: approval needed for ${subject}`,
+        text:
+          `An agent wants to call ${subject} and ADTL needs your approval.\n\nReason: ${r.reason}\nRule: ${r.matched.join(", ") || "default"}\n` +
+          `Session: ${r.sessionId}\nExpires: ${r.expiresAt.toISOString()} (no answer means deny)${footer}`,
+      };
+    }
+    const res = event.result;
+    return {
+      subject: `ADTL: ${subject} ${res.outcome}`,
+      text: `The approval request for ${subject} was ${res.outcome}${res.channel ? ` via ${res.channel}` : ""} after ${Math.round(res.waitedMs / 1000)}s.\n\nReason it was asked: ${r.reason}\nSession: ${r.sessionId}${footer}`,
+    };
+  }
+}