@adtl/gateway 0.5.1 → 0.6.0

package/playground/server.mjs

@@ -0,0 +1,290 @@
+// `adtl-gateway playground`: a local web playground for ADTL. It runs the real
+// gateway in this process, in front of fake GitHub and fake memory servers,
+// and shows every call: the label on its result, the session label, the
+// policy decision, the audit log and what actually reached GitHub. "Ask"
+// decisions come up in the page with Allow / Deny buttons (a notifier that
+// answers like ntfy does).
+//
+// Listens on 127.0.0.1 only. Everything it writes (ledger, audit log, posted
+// comments) goes to a temporary folder that is removed on reset and exit.
+
+import { createServer } from "node:http";
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport, getDefaultEnvironment } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { parseConfigText } from "@adtl/interceptors";
+import {
+  AdtlGateway,
+  ApprovalBroker,
+  GATEWAY_DECISION_KEY,
+  InterceptorInvoker,
+  JsonlAuditLog,
+  bundledInterceptorsCli,
+  connectUpstream,
+  loadGatewayConfig,
+} from "../dist/index.js";
+
+const here = fileURLToPath(new URL(".", import.meta.url));
+const FAKE_GITHUB = join(here, "fake-github.mjs");
+const FAKE_MEMORY = join(here, "fake-memory.mjs");
+export const DEFAULT_CONFIG = readFileSync(join(here, "playground.yaml"), "utf8");
+export const DEFAULT_PORT = 4317;
+const TRUST_KEY = "io.modelcontextprotocol/trust-annotations";
+
+/** Answers "ask" decisions from the page, the way the ntfy notifier answers them from a phone. */
+class PageNotifier {
+  name = "playground";
+  pending = new Map();
+
+  listen(request, answer, signal) {
+    this.pending.set(request.id, { request, answer });
+    return new Promise((resolve) => signal.addEventListener("abort", () => {
+      this.pending.delete(request.id);
+      resolve();
+    }));
+  }
+
+  async notify(event) {
+    if (event.kind === "pending") {
+      const p = this.pending.get(event.request.id);
+      if (p) p.tokens = event.tokens;
+    }
+  }
+
+  answer(id, decision) {
+    const p = this.pending.get(id);
+    return !!p?.tokens && p.answer(p.tokens[decision], "you, in the playground");
+  }
+
+  list() {
+    return [...this.pending.values()].filter((p) => p.tokens).map(({ request: r }) => ({
+      id: r.id, tool: `${r.server}__${r.tool}`, reason: r.reason, matched: r.matched, sessionLabel: r.sessionLabel,
+    }));
+  }
+}
+
+async function stdio(script, env = {}) {
+  const client = new Client({ name: "playground-agent", version: "0.0.0" });
+  await client.connect(new StdioClientTransport({ command: process.execPath, args: [script], env: { ...getDefaultEnvironment(), ...env }, stderr: "ignore" }));
+  return client;
+}
+
+function readJsonl(path) {
+  return existsSync(path) ? readFileSync(path, "utf8").split("\n").filter(Boolean).map((l) => JSON.parse(l)) : [];
+}
+
+async function close(s) {
+  if (!s) return;
+  await Promise.allSettled(s.closers.map((c) => c.close()));
+  rmSync(s.work, { recursive: true, force: true });
+}
+
+/** Fresh servers, ledger, audit log and session. Throws without side effects if the config is invalid. */
+async function build({ adtl, config }) {
+  if (adtl) parseConfigText(config); // a broken adtl.yaml fails here, before anything starts
+  const work = mkdtempSync(join(tmpdir(), "adtl-playground-"));
+  const posted = join(work, "posted.jsonl");
+  const s = { adtl, config, work, posted, audit: join(work, "audit.jsonl"), timeline: [], sessionNo: 1, closers: [], auditSeen: 0 };
+  try {
+    if (adtl) {
+      const path = join(work, "adtl.yaml");
+      writeFileSync(
+        path,
+        config.replace(/^(ledger|gateway):[\s\S]*$/m, "") +
+          `\nledger:\n  path: ${JSON.stringify(join(work, "ledger.db"))}\n` +
+          `gateway:\n  audit: ${JSON.stringify(s.audit)}\n  upstreams:\n` +
+          `    github:\n      command: ${JSON.stringify(process.execPath)}\n      args: [${JSON.stringify(FAKE_GITHUB)}]\n` +
+          `      env: { FAKE_GITHUB_POSTED: ${JSON.stringify(posted)} }\n` +
+          `    memory:\n      command: ${JSON.stringify(process.execPath)}\n      args: [${JSON.stringify(FAKE_MEMORY)}]\n`,
+      );
+      const loaded = await loadGatewayConfig(path);
+      const interceptors = await connectUpstream("interceptors", {
+        command: process.execPath, args: [bundledInterceptorsCli(), "--config", path], env: {},
+      }, work);
+      s.closers.push(interceptors);
+      s.invoker = new InterceptorInvoker(await InterceptorInvoker.discover(interceptors), loaded.gateway.interceptorTimeoutMs);
+      s.upstreams = new Map();
+      for (const [id, u] of Object.entries(loaded.gateway.upstreams)) {
+        const c = await connectUpstream(id, u, work);
+        s.closers.push(c);
+        s.upstreams.set(id, c);
+      }
+      s.notifier = new PageNotifier();
+      s.approvals = new ApprovalBroker({ notifiers: [s.notifier], timeoutMs: 120_000 });
+      s.auditLog = new JsonlAuditLog(s.audit);
+    } else {
+      s.upstreams = new Map([
+        ["github", await stdio(FAKE_GITHUB, { FAKE_GITHUB_POSTED: posted })],
+        ["memory", await stdio(FAKE_MEMORY)],
+      ]);
+      s.closers.push(...s.upstreams.values());
+    }
+  } catch (err) {
+    await close(s);
+    throw err;
+  }
+  return s;
+}
+
+/**
+ * Start the playground. Resolves once it is listening, with its URL and a
+ * `close()` that stops the server and every child process. Port 0 picks a free port.
+ */
+export async function startPlayground({ port = DEFAULT_PORT, host = "127.0.0.1", warn = (m) => console.error(`[adtl] ${m}`) } = {}) {
+  let state;
+
+  function newSession(bump = true) {
+    const s = state;
+    if (bump) s.sessionNo++;
+    s.sessionId = `session-${s.sessionNo}`;
+    s.sessionLabel = undefined;
+    if (s.adtl) {
+      s.gateway = new AdtlGateway({
+        sessionId: s.sessionId, upstreams: s.upstreams, invoker: s.invoker, audit: s.auditLog, approvals: s.approvals,
+        logger: { info: () => {}, warn },
+      });
+    }
+    s.timeline.push({ kind: "session", session: s.sessionId });
+  }
+
+  /** Start over. If the new setup fails (e.g. a broken adtl.yaml), the old one keeps running. */
+  async function reset({ adtl = true, config = state?.config ?? DEFAULT_CONFIG } = {}) {
+    const next = await build({ adtl, config });
+    const old = state;
+    state = next;
+    newSession(false);
+    await close(old);
+  }
+
+  async function tools() {
+    const s = state;
+    if (s.adtl) return (await s.gateway.listTools()).map((t) => ({ name: t.name, description: t.description, inputSchema: t.inputSchema }));
+    const out = [];
+    for (const [id, c] of s.upstreams) {
+      for (const t of (await c.listTools()).tools) out.push({ name: `${id}__${t.name}`, description: t.description, inputSchema: t.inputSchema });
+    }
+    return out;
+  }
+
+  async function call(name, args) {
+    const s = state;
+    const entry = { kind: "call", session: s.sessionId, tool: name, args, pending: true };
+    s.timeline.push(entry);
+    try {
+      let r;
+      if (s.adtl) {
+        r = await s.gateway.callTool(name, args);
+      } else {
+        const [id, tool] = name.split("__");
+        r = await s.upstreams.get(id).callTool({ name: tool, arguments: args });
+      }
+      entry.text = r.content?.map((c) => c.text ?? "").join("") ?? "";
+      entry.isError = !!r.isError;
+      entry.label = r._meta?.[TRUST_KEY];
+      entry.decision = r._meta?.[GATEWAY_DECISION_KEY];
+    } catch (err) {
+      entry.text = err.message;
+      entry.isError = true;
+    }
+    if (s.adtl) {
+      const audit = readJsonl(s.audit);
+      const mine = audit.slice(s.auditSeen).filter((e) => e.sessionId === s.sessionId).at(-1);
+      s.auditSeen = audit.length;
+      if (mine) {
+        entry.audit = mine;
+        if (mine.sessionLabel) s.sessionLabel = mine.sessionLabel;
+      }
+    }
+    entry.pending = false;
+    return entry;
+  }
+
+  function snapshot() {
+    const s = state;
+    return {
+      adtl: s.adtl,
+      config: s.config,
+      session: s.sessionId,
+      sessionLabel: s.sessionLabel,
+      timeline: s.timeline,
+      audit: s.adtl ? readJsonl(s.audit) : [],
+      posted: readJsonl(s.posted),
+      approvals: s.notifier?.list() ?? [],
+    };
+  }
+
+  const page = () => readFileSync(join(here, "index.html"));
+
+  async function body(req) {
+    let raw = "";
+    for await (const chunk of req) raw += chunk;
+    return raw ? JSON.parse(raw) : {};
+  }
+
+  // One action at a time, except approvals: an "ask" holds its call open until the page answers.
+  let queue = Promise.resolve();
+  const serial = (fn) => (queue = queue.then(fn, fn));
+
+  const routes = {
+    "GET /": async (_req, res) => res.writeHead(200, { "content-type": "text/html; charset=utf-8" }).end(page()),
+    "GET /api/state": async () => snapshot(),
+    // Not queued: listing tools must not wait behind a call that is waiting for approval.
+    "GET /api/tools": async () => tools(),
+    "POST /api/reset": async (req) => {
+      const b = await body(req);
+      return serial(async () => {
+        await reset({ adtl: b.adtl ?? state.adtl, config: b.config ?? (b.defaults ? DEFAULT_CONFIG : state.config) });
+        return snapshot();
+      });
+    },
+    "POST /api/session": async () => serial(async () => (newSession(), snapshot())),
+    "POST /api/call": async (req) => {
+      const b = await body(req);
+      return serial(() => call(b.name, b.args ?? {}));
+    },
+    "POST /api/approve": async (req) => {
+      const b = await body(req);
+      return { ok: state.notifier?.answer(b.id, b.decision === "allow" ? "allow" : "deny") ?? false };
+    },
+  };
+
+  await reset();
+
+  const server = createServer(async (req, res) => {
+    const route = routes[`${req.method} ${req.url.split("?")[0]}`];
+    if (!route) return res.writeHead(404).end("not found");
+    try {
+      const out = await route(req, res);
+      if (!res.headersSent) res.writeHead(200, { "content-type": "application/json" }).end(JSON.stringify(out ?? {}));
+    } catch (err) {
+      if (!res.headersSent) res.writeHead(400, { "content-type": "application/json" }).end(JSON.stringify({ error: err.message }));
+    }
+  });
+
+  try {
+    await new Promise((resolve, reject) => {
+      server.once("error", reject);
+      server.listen(port, host, resolve);
+    });
+  } catch (err) {
+    await close(state);
+    if (err.code === "EADDRINUSE") {
+      throw new Error(`Port ${port} is in use (another playground running?). Try --port ${port + 1}`);
+    }
+    throw err;
+  }
+  const actual = server.address().port;
+  return {
+    url: `http://localhost:${actual}`,
+    port: actual,
+    async close() {
+      const closed = new Promise((resolve) => server.close(() => resolve()));
+      server.closeAllConnections?.();
+      await closed;
+      await close(state);
+    },
+  };
+}

package/src/approvals.ts

@@ -10,6 +10,11 @@
  * 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.
+ *
+ * A request can name its approvers (policy rule `approvers:`). It then goes
+ * only to those people's own channels, each with tokens signed for that
+ * person, and an answer counts only if it comes back on the same person's
+ * channel. So the result names who approved, and nobody else can.
  */
 import { createHmac, randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
 
@@ -26,6 +31,8 @@ export interface ApprovalRequest {
   matched: string[];
   /** The session label that triggered the rule (no arguments or results). */
   sessionLabel?: unknown;
+  /** People who may answer, reached on their own channels. Absent: the shared channels. */
+  approvers?: string[];
   createdAt: Date;
   expiresAt: Date;
 }
@@ -70,9 +77,10 @@ export function errorText(err: unknown): string {
 export class ApprovalTokens {
   constructor(private readonly secret: Buffer = randomBytes(32)) {}
 
-  sign(request: Pick<ApprovalRequest, "id" | "callHash" | "expiresAt">, decision: ApprovalDecision): string {
+  /** A token answering `request` with `decision`; with `approver`, valid only as that person's answer. */
+  sign(request: Pick<ApprovalRequest, "id" | "callHash" | "expiresAt">, decision: ApprovalDecision, approver?: string): string {
     const exp = Math.floor(request.expiresAt.getTime() / 1000);
-    return `${TOKEN_PREFIX}.${request.id}.${decision}.${exp}.${this.mac(request.id, request.callHash, decision, exp)}`;
+    return `${TOKEN_PREFIX}.${request.id}.${decision}.${exp}.${this.mac(request.id, request.callHash, decision, exp, approver)}`;
   }
 
   /** Parse a token without verifying it. */
@@ -86,23 +94,26 @@ export class ApprovalTokens {
   }
 
   /** Verify a token against the pending request it claims to answer. */
-  verify(token: string, request: Pick<ApprovalRequest, "id" | "callHash">, now: Date): ApprovalDecision | undefined {
+  verify(token: string, request: Pick<ApprovalRequest, "id" | "callHash">, now: Date, approver?: string): 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 expected = Buffer.from(this.mac(t.id, request.callHash, t.decision, t.exp, approver));
     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");
+  private mac(id: string, callHash: string, decision: ApprovalDecision, exp: number, approver?: string): string {
+    const signed = `${id}\n${callHash}\n${decision}\n${exp}${approver === undefined ? "" : `\napprover:${approver}`}`;
+    return createHmac("sha256", this.secret).update(signed).digest("base64url");
   }
 }
 
 export interface ApprovalBrokerOptions {
   notifiers: Notifier[];
+  /** Each approver's own channels, by principal id. */
+  approverChannels?: Map<string, Notifier[]>;
   timeoutMs: number;
   tokens?: ApprovalTokens;
   now?: () => Date;
@@ -114,8 +125,15 @@ interface Pending {
   settle(decision: ApprovalDecision, channel: string, approver?: string): void;
 }
 
+/** A channel a request goes to, and whose answers it accepts on it (undefined: a shared channel). */
+interface Target {
+  notifier: Notifier;
+  approver?: string;
+}
+
 export class ApprovalBroker {
   private readonly notifiers: Notifier[];
+  private readonly approverChannels: Map<string, Notifier[]>;
   private readonly timeoutMs: number;
   private readonly tokens: ApprovalTokens;
   private readonly now: () => Date;
@@ -124,19 +142,32 @@ export class ApprovalBroker {
 
   constructor(opts: ApprovalBrokerOptions) {
     this.notifiers = opts.notifiers;
+    this.approverChannels = opts.approverChannels ?? new Map();
     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. */
+  /** True if at least one channel can carry answers. Without one, "ask" stays a block. */
   get canApprove(): boolean {
-    return this.notifiers.some((n) => n.listen);
+    return this.notifiers.some((n) => n.listen) || [...this.approverChannels.values()].some((ns) => ns.some((n) => n.listen));
+  }
+
+  /**
+   * Where a request goes: the named approvers' own channels plus notice-only
+   * ones, or else every shared channel plus `extra` (channels for this request
+   * only, such as the client's elicitation).
+   */
+  private targets(request: ApprovalRequest, extra: Notifier[]): Target[] {
+    if (!request.approvers) return [...this.notifiers, ...extra].map((notifier) => ({ notifier }));
+    const own = request.approvers.flatMap((approver) => (this.approverChannels.get(approver) ?? []).map((notifier) => ({ notifier, approver })));
+    // Shared channels that can answer would let anyone who reads them approve; notice-only ones (email) are fine.
+    return [...own, ...this.notifiers.filter((n) => !n.listen).map((notifier) => ({ notifier }))];
   }
 
   /** 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> {
+  async request(input: Omit<ApprovalRequest, "id" | "createdAt" | "expiresAt">, extra: Notifier[] = []): Promise<ApprovalResult> {
     const createdAt = this.now();
     const request: ApprovalRequest = {
       ...input,
@@ -164,45 +195,51 @@ export class ApprovalBroker {
         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) =>
+    // Start listening before anyone can answer, then send the request to every target.
+    const targets = this.targets(request, extra);
+    for (const { notifier: n, approver } of targets.filter((t) => t.notifier.listen)) {
+      n.listen!(request, (token, reportedBy) => this.answer(token, n.name, approver, reportedBy), 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(
+    const sent = targets.map(({ notifier: n, approver }) => {
+      const tokens = { allow: this.tokens.sign(request, "allow", approver), deny: this.tokens.sign(request, "deny", approver) };
+      return 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) => {
+    void Promise.all(sent.filter((_, i) => targets[i]!.notifier.listen)).then((ok) => {
       if (!ok.includes(true)) finish({ outcome: "undeliverable", waitedMs: waited() });
     });
 
     const r = await result;
-    this.broadcast({ kind: "resolved", request, result: r });
+    this.broadcast({ kind: "resolved", request, result: r }, [...new Set(targets.map((t) => t.notifier))]);
     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 {
+  /**
+   * Handle an answer token from a channel; `approver` is whose own channel it
+   * came on, `reportedBy` who a shared channel says answered (recorded, not
+   * trusted for anything). Returns true if it settled a pending approval.
+   */
+  answer(token: string, channel: string, approver?: string, reportedBy?: 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());
+    // A request with approvers takes answers only on their own channels.
+    if (p.request.approvers && (approver === undefined || !p.request.approvers.includes(approver))) return false;
+    const decision = this.tokens.verify(token, p.request, this.now(), approver);
     if (!decision) {
       this.log.warn(`${channel}: ignored an approval answer with a bad or expired signature`);
       return false;
     }
-    p.settle(decision, channel, approver);
+    p.settle(decision, channel, approver ?? reportedBy);
     return true;
   }
 
@@ -211,8 +248,8 @@ export class ApprovalBroker {
     this.broadcast({ kind: "blocked", ...event });
   }
 
-  private broadcast(event: ApprovalEvent): void {
-    for (const n of this.notifiers) {
+  private broadcast(event: ApprovalEvent, notifiers: Notifier[] = this.notifiers): void {
+    for (const n of notifiers) {
       n.notify(event).catch((err: unknown) => this.log.warn(`${n.name}: could not send ${event.kind} notice: ${errorText(err)}`));
     }
   }

package/src/audit.ts

@@ -18,6 +18,7 @@
 import { closeSync, fstatSync, mkdirSync, openSync, readFileSync, readSync, statSync, unlinkSync, writeSync } from "node:fs";
 import { dirname } from "node:path";
 import { digest, sha256Hex } from "@adtl/labels";
+import type { InterceptorRun } from "./invoker.js";
 
 export interface AuditEntry {
   ts: string;
@@ -32,6 +33,8 @@ export interface AuditEntry {
   outcome: "forwarded" | "blocked" | "asked" | "upstream_error";
   /** Present when the entry was written by the Claude Code hook rather than the gateway. */
   via?: "claude-code-hook";
+  /** Present when a Claude Code subagent made the call: its id and type (e.g. "Explore"). */
+  agent?: { id: string; type?: string };
   /** 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. */
@@ -49,6 +52,8 @@ export interface AuditEntry {
   /** Present when the result carried record label stamps: how many, and which sessions wrote them. */
   records?: unknown;
   sessionLabel?: unknown;
+  /** Every interceptor invocation for this call, with its resolved mode and failOpen and where each came from (SEP-2624). */
+  interceptors?: InterceptorRun[];
   warnings?: string[];
   durationMs: number;
 }

package/src/auditCli.ts

@@ -23,6 +23,16 @@ export interface AuditCommandResult {
   exitCode: number;
 }
 
+/** The audit log: `file` if given, else `gateway.audit` from `config`. */
+export async function resolveAuditPath(file: string | undefined, config: string | undefined, usage: string): Promise<string> {
+  if (file) return resolve(file);
+  if (!config) throw new Error(`Give the audit log file, or -c <adtl.yaml> with gateway.audit set\n\n${usage}`);
+  const abs = resolve(config);
+  const gw = ((parseYaml(await readFile(abs, "utf8")) ?? {}) as { gateway?: { audit?: unknown } }).gateway ?? {};
+  if (typeof gw.audit !== "string") throw new Error(`${config} has no gateway.audit`);
+  return resolve(dirname(abs), gw.audit);
+}
+
 export async function runAuditCommand(argv: string[]): Promise<AuditCommandResult> {
   const [cmd, ...rest] = argv;
   let config: string | undefined;
@@ -37,14 +47,7 @@ export async function runAuditCommand(argv: string[]): Promise<AuditCommandResul
   if (cmd !== "verify") throw new Error(`Unknown audit command: ${cmd}\n\n${AUDIT_USAGE}`);
   if (files.length > 1) throw new Error(`Unexpected argument: ${files[1]}\n\n${AUDIT_USAGE}`);
 
-  let path = files[0] && resolve(files[0]);
-  if (!path) {
-    if (!config) throw new Error(`Give the audit log file, or -c <adtl.yaml> with gateway.audit set\n\n${AUDIT_USAGE}`);
-    const abs = resolve(config);
-    const gw = ((parseYaml(await readFile(abs, "utf8")) ?? {}) as { gateway?: { audit?: unknown } }).gateway ?? {};
-    if (typeof gw.audit !== "string") throw new Error(`${config} has no gateway.audit`);
-    path = resolve(dirname(abs), gw.audit);
-  }
+  const path = await resolveAuditPath(files[0], config, AUDIT_USAGE);
 
   const v = verifyAuditLog(path);
   if (!v.ok) return { stdout: `${path}: TAMPERED: ${v.problem}`, exitCode: 1 };

package/src/cli.ts

@@ -8,6 +8,9 @@
  *   adtl-gateway hook --config adtl.yaml [--gateway-server adtl]
  *   adtl-gateway ledger stats|verify|declassify|declassified
  *   adtl-gateway audit verify [<file>]
+ *   adtl-gateway receipt list|<session>|verify <file>
+ *   adtl-gateway key
+ *   adtl-gateway playground [--port 4317] [--no-open]
  *
  * Point your MCP client (e.g. Claude Code's .mcp.json) at this command.
  * Logs go to stderr; stdout carries MCP JSON-RPC only.
@@ -16,6 +19,8 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { EnvExpansionError } from "./config.js";
 import { GATEWAY_VERSION } from "./gateway.js";
 import { runAuditCommand } from "./auditCli.js";
+import { runKeyCommand, runReceiptCommand } from "./receiptCli.js";
+import { runPlayground } from "./playgroundCli.js";
 import { runHook } from "./hooks/run.js";
 import { runLedgerCommand } from "./ledgerCli.js";
 import { runInit, type InitResult } from "./init/run.js";
@@ -26,6 +31,9 @@ const USAGE = `Usage: adtl-gateway --config <adtl.yaml> [--audit]
        adtl-gateway hook --config <adtl.yaml> [--gateway-server <name>]
        adtl-gateway ledger stats|verify|declassify|declassified  (see: adtl-gateway ledger --help)
        adtl-gateway audit verify [<file>]  (see: adtl-gateway audit --help)
+       adtl-gateway receipt list|<session>|verify <file>  (see: adtl-gateway receipt --help)
+       adtl-gateway key
+       adtl-gateway playground [--port <n>] [--no-open]  (a local web UI with fake servers)
 
 Runs an MCP server over stdio that forwards tool calls to the upstream
 servers in the config, checking and labeling each call with ADTL.
@@ -104,6 +112,13 @@ async function main(): Promise<void> {
     process.exitCode = r.exitCode;
     return;
   }
+  if (process.argv[2] === "playground") return runPlayground(process.argv.slice(3));
+  if (process.argv[2] === "receipt" || process.argv[2] === "key") {
+    const r = process.argv[2] === "key" ? await runKeyCommand() : await runReceiptCommand(process.argv.slice(3));
+    console.log(r.stdout);
+    process.exitCode = r.exitCode;
+    return;
+  }
   const args = parseArgs(process.argv.slice(2));
   // --help and --version print to stdout and exit; MCP is never served in these modes.
   if (args.help) return void console.log(USAGE);
@@ -190,7 +205,7 @@ async function init(path: string, write: boolean, from?: string): Promise<void>
 }
 
 main().catch((err: unknown) => {
-  const known = err instanceof GatewayConfigError || err instanceof EnvExpansionError || ["ledger", "audit"].includes(process.argv[2] ?? "");
+  const known = err instanceof GatewayConfigError || err instanceof EnvExpansionError || ["ledger", "audit", "receipt", "key", "playground"].includes(process.argv[2] ?? "");
   console.error(known ? `[adtl-gateway] ${(err as Error).message}` : err);
   // For Claude Code hooks only exit code 2 stops the call; any other code lets it run.
   process.exit(process.argv[2] === "hook" ? 2 : 1);