@adtl/gateway 0.5.1 → 0.7.0

package/src/hooks/claudeCode.ts

@@ -49,6 +49,9 @@ export interface HookInput {
   /** PostToolUseFailure: the error the tool returned. */
   error?: unknown;
   cwd?: string;
+  /** Set when the hook fires inside a subagent (or an in-process teammate). */
+  agent_id?: string;
+  agent_type?: string;
 }
 
 export interface HookOptions {
@@ -62,7 +65,7 @@ export interface HookOptions {
   /** Label ledger shared with the gateway. */
   ledger?: Ledger;
   /** Files the agent must not change: the ADTL config, the session directory and the ledger. */
-  protect?: { configPath?: string; sessionsDir?: string; ledgerPath?: string; auditPath?: string };
+  protect?: { configPath?: string; sessionsDir?: string; ledgerPath?: string; auditPath?: string; signingKeyPath?: string };
 }
 
 /** What the hook process prints and exits with. */
@@ -132,6 +135,9 @@ function protectedTarget(input: HookInput, route: { server: string; tool: string
     if (protect.auditPath && abs.startsWith(resolve(protect.auditPath))) {
       return { decision: "block", reason: "The agent may not change the ADTL audit log" };
     }
+    if (protect.signingKeyPath && abs === resolve(protect.signingKeyPath)) {
+      return { decision: "block", reason: "The agent may not touch the ADTL signing key" };
+    }
   }
   const command = typeof args.command === "string" ? args.command : undefined;
   if (command !== undefined && ["Bash", "Monitor"].includes(route.tool)) {
@@ -146,6 +152,9 @@ function protectedTarget(input: HookInput, route: { server: string; tool: string
     if (protect.auditPath && command.includes(basename(protect.auditPath))) {
       return { decision: "ask", reason: "This command touches the ADTL audit log" };
     }
+    if (protect.signingKeyPath && command.includes(basename(protect.signingKeyPath))) {
+      return { decision: "ask", reason: "This command touches the ADTL signing key" };
+    }
   }
   return undefined;
 }
@@ -173,7 +182,9 @@ export function handleHook(input: HookInput, opts: HookOptions): HookOutcome {
   if (!route) return NOTHING;
   const config = withClaudeCodePreset(opts.config);
   const ts = new Date().toISOString();
-  const base = { ts, sessionId: input.session_id, event: "tools/call" as const, ...route, via: "claude-code-hook" as const };
+  const agent =
+    typeof input.agent_id === "string" ? { agent: { id: input.agent_id, ...(typeof input.agent_type === "string" ? { type: input.agent_type } : {}) } } : {};
+  const base = { ts, sessionId: input.session_id, event: "tools/call" as const, ...route, via: "claude-code-hook" as const, ...agent };
 
   if (event !== "PreToolUse") {
     const output = input.tool_response ?? input.error ?? null;

package/src/hooks/run.ts

@@ -8,7 +8,7 @@
  */
 import { readFile } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
-import { FileSessionStore, defaultSessionsDir } from "@adtl/labels";
+import { FileSessionStore, defaultSessionsDir, defaultSigningKeyPath, trySigner } from "@adtl/labels";
 import { Ledger, defaultLedgerPath } from "@adtl/ledger";
 import { parseConfigText } from "@adtl/interceptors";
 import { parse as parseYaml } from "yaml";
@@ -38,7 +38,10 @@ export async function runHook(opts: RunHookOptions): Promise<HookOutcome> {
     const env = opts.env ?? process.env;
     const sessionsDir = defaultSessionsDir(env);
     const ledgerPath = config.ledger.path ? resolve(dirname(path), config.ledger.path) : defaultLedgerPath(env);
-    const ledger = config.ledger.enabled ? new Ledger(ledgerPath, { retentionDays: config.ledger.retentionDays }) : undefined;
+    const signer = config.ledger.enabled ? trySigner(defaultSigningKeyPath(env)) : undefined;
+    const ledger = config.ledger.enabled
+      ? new Ledger(ledgerPath, { retentionDays: config.ledger.retentionDays, ...(signer ? { signer } : {}) })
+      : undefined;
     const auditPath = typeof gw.audit === "string" ? resolve(dirname(path), gw.audit) : undefined;
     return handleHook(input, {
       config,
@@ -47,7 +50,7 @@ export async function runHook(opts: RunHookOptions): Promise<HookOutcome> {
       ...(opts.gatewayServer ? { gatewayServer: opts.gatewayServer } : {}),
       mode: gw.mode === "audit" ? "audit" : "active",
       ...(auditPath ? { audit: new JsonlAuditLog(auditPath) } : {}),
-      protect: { configPath: path, sessionsDir, ledgerPath, ...(auditPath ? { auditPath } : {}) },
+      protect: { configPath: path, sessionsDir, ledgerPath, ...(auditPath ? { auditPath } : {}), signingKeyPath: defaultSigningKeyPath(env) },
     });
   } catch (err) {
     return failure(input.hook_event_name, (err as Error).message);

package/src/index.ts

@@ -11,3 +11,9 @@ export * from "./init/index.js";
 export * from "./hooks/index.js";
 export * from "./ledgerCli.js";
 export * from "./auditCli.js";
+export * from "./roles.js";
+export * from "./cedar.js";
+export * from "./elicitation.js";
+export * from "./receipt.js";
+export * from "./receiptCli.js";
+export * from "./playgroundCli.js";

package/src/init/presets.ts

@@ -53,6 +53,60 @@ export const PRESETS: Preset[] = [
     write: { integrity: "untrusted", confidentiality: "public", egress: "external" },
     note: "preset fetch: web pages are untrusted; a fetched URL can carry data out, so fetch is external egress",
   },
+  {
+    id: "slack",
+    // Both popular servers report this name: @modelcontextprotocol/server-slack (no tool hints, so its
+    // tools are listed below) and korotovsky/slack-mcp-server (marks reads with readOnlyHint).
+    serverNames: ["Slack MCP Server"],
+    // Anyone in the workspace, or a shared channel, can write messages and profiles.
+    defaults: { integrity: "untrusted", confidentiality: "private", egress: "external" },
+    read: { integrity: "untrusted", confidentiality: "private", egress: "internal" },
+    write: { egress: "external" },
+    tools: {
+      slack_list_channels: { integrity: "untrusted", confidentiality: "private", egress: "internal" },
+      slack_get_channel_history: { integrity: "untrusted", confidentiality: "private", egress: "internal" },
+      slack_get_thread_replies: { integrity: "untrusted", confidentiality: "private", egress: "internal" },
+      slack_get_users: { integrity: "untrusted", confidentiality: "private", egress: "internal" },
+      slack_get_user_profile: { integrity: "untrusted", confidentiality: "private", egress: "internal" },
+      slack_post_message: { integrity: "trusted", confidentiality: "public", egress: "external" },
+      slack_reply_to_thread: { integrity: "trusted", confidentiality: "public", egress: "external" },
+      slack_add_reaction: { integrity: "trusted", confidentiality: "public", egress: "external" },
+    },
+    note: "preset slack: messages are untrusted (anyone in the workspace can write them) and private; posting is external egress (set public for channels with outside guests)",
+  },
+  {
+    id: "gmail",
+    // @gongrzhe/server-gmail-autoauth-mcp, the most used Gmail server. It sets no tool hints.
+    serverNames: ["gmail"],
+    // Anyone can send you email.
+    defaults: { integrity: "untrusted", confidentiality: "private", egress: "internal" },
+    read: { integrity: "untrusted", confidentiality: "private", egress: "internal" },
+    write: { egress: "internal" },
+    tools: {
+      read_email: { integrity: "untrusted", confidentiality: "private", egress: "internal" },
+      search_emails: { integrity: "untrusted", confidentiality: "private", egress: "internal" },
+      list_email_labels: { integrity: "untrusted", confidentiality: "private", egress: "none" },
+      list_filters: { integrity: "trusted", confidentiality: "private", egress: "none" },
+      get_filter: { integrity: "trusted", confidentiality: "private", egress: "none" },
+      // Saves the attachment to a local folder.
+      download_attachment: { integrity: "untrusted", confidentiality: "private", egress: "internal" },
+      send_email: { integrity: "trusted", confidentiality: "public", egress: "external" },
+      draft_email: { integrity: "trusted", confidentiality: "public", egress: "internal" },
+      modify_email: { integrity: "trusted", confidentiality: "public", egress: "internal" },
+      delete_email: { integrity: "trusted", confidentiality: "public", egress: "internal" },
+      batch_modify_emails: { integrity: "trusted", confidentiality: "public", egress: "internal" },
+      batch_delete_emails: { integrity: "trusted", confidentiality: "public", egress: "internal" },
+      create_label: { integrity: "trusted", confidentiality: "public", egress: "internal" },
+      update_label: { integrity: "trusted", confidentiality: "public", egress: "internal" },
+      delete_label: { integrity: "trusted", confidentiality: "public", egress: "internal" },
+      get_or_create_label: { integrity: "trusted", confidentiality: "public", egress: "internal" },
+      delete_filter: { integrity: "trusted", confidentiality: "public", egress: "internal" },
+      // Filters can forward matching mail to any address.
+      create_filter: { integrity: "trusted", confidentiality: "public", egress: "external" },
+      create_filter_from_template: { integrity: "trusted", confidentiality: "public", egress: "external" },
+    },
+    note: "preset gmail: email is untrusted (anyone can send it) and private; sending, and filters that can forward mail, are external egress",
+  },
 ];
 
 /** The preset for an upstream: by the name the server reports, then by the upstream id. */

package/src/invoker.ts

@@ -55,12 +55,31 @@ export interface Blocked {
   confirmation?: ConfirmationRequest;
 }
 
+/**
+ * One interceptor invocation, with the execution policy it ran under. SEP-2624
+ * (Security Best Practice 3) asks invokers to log the resolved `mode` and
+ * `failOpen`, and whether each came from an invoker override or the
+ * interceptor's declared default.
+ */
+export interface InterceptorRun {
+  name: string;
+  phase: Phase;
+  mode: InterceptorMode;
+  modeFrom: "override" | "default";
+  failOpen: boolean;
+  failOpenFrom: "override" | "default";
+  /** Set when the invocation errored or timed out. */
+  failed?: true;
+}
+
 export interface PhaseOutcome {
   payload: unknown;
   blocked?: Blocked;
   results: InterceptorResult[];
   /** Interceptors that failed but were allowed to (failOpen or audit mode). */
   warnings: string[];
+  /** Every interceptor invoked in this phase. */
+  ran: InterceptorRun[];
 }
 
 export interface InvokeOptions {
@@ -101,14 +120,14 @@ export class InterceptorInvoker {
   }
 
   async runRequest(opts: InvokeOptions): Promise<PhaseOutcome> {
-    const out: PhaseOutcome = { payload: opts.payload, results: [], warnings: [] };
+    const out: PhaseOutcome = { payload: opts.payload, results: [], warnings: [], ran: [] };
     if (!(await this.mutate("request", opts, out))) return out;
     await this.validate("request", opts, out);
     return out;
   }
 
   async runResponse(opts: InvokeOptions): Promise<PhaseOutcome> {
-    const out: PhaseOutcome = { payload: opts.payload, results: [], warnings: [] };
+    const out: PhaseOutcome = { payload: opts.payload, results: [], warnings: [], ran: [] };
     if (!(await this.validate("response", opts, out))) return out;
     await this.mutate("response", opts, out);
     return out;
@@ -118,6 +137,20 @@ export class InterceptorInvoker {
     return (this.modeOverride ?? i.definition.mode) === "audit";
   }
 
+  /** Record that `i` runs in `phase`, with its resolved policy. The gateway has no failOpen overrides. */
+  private run(i: BoundInterceptor, phase: Phase, out: PhaseOutcome): InterceptorRun {
+    const r: InterceptorRun = {
+      name: i.definition.name,
+      phase,
+      mode: this.modeOverride ?? i.definition.mode ?? "active",
+      modeFrom: this.modeOverride ? "override" : "default",
+      failOpen: i.definition.failOpen === true,
+      failOpenFrom: "default",
+    };
+    out.ran.push(r);
+    return r;
+  }
+
   private select(type: InterceptorDefinition["type"], event: string, phase: Phase): BoundInterceptor[] {
     return this.interceptors.filter((i) => i.definition.type === type && hooks(i.definition, event, phase));
   }
@@ -150,10 +183,12 @@ export class InterceptorInvoker {
     );
     let payload = out.payload;
     for (const i of selected) {
+      const ran = this.run(i, phase, out);
       let r: MutationResult;
       try {
         r = (await this.invoke(i, phase, opts, payload)) as MutationResult;
       } catch (err) {
+        ran.failed = true;
         if (!this.failed(i, err, out)) return false;
         continue;
       }
@@ -167,11 +202,13 @@ export class InterceptorInvoker {
   /** Parallel validations. Only severity "error" blocks. */
   private async validate(phase: Phase, opts: InvokeOptions, out: PhaseOutcome): Promise<boolean> {
     const selected = this.select("validation", opts.event, phase);
+    const runs = selected.map((i) => this.run(i, phase, out));
     const settled = await Promise.allSettled(selected.map((i) => this.invoke(i, phase, opts, out.payload)));
     let ok = true;
     settled.forEach((s, idx) => {
       const i = selected[idx]!;
       if (s.status === "rejected") {
+        runs[idx]!.failed = true;
         if (!this.failed(i, s.reason, out)) ok = false;
         return;
       }

package/src/ledgerCli.ts

@@ -17,6 +17,7 @@ import { userInfo } from "node:os";
 import { dirname, resolve } from "node:path";
 import { parseConfigText } from "@adtl/interceptors";
 import { Ledger, chunkHashes, defaultLedgerPath } from "@adtl/ledger";
+import { defaultSigningKeyPath, loadSigner, trySigner } from "@adtl/labels";
 
 export const LEDGER_USAGE = `Usage: adtl-gateway ledger stats [-c <adtl.yaml>]
        adtl-gateway ledger verify [-c <adtl.yaml>]
@@ -28,7 +29,8 @@ private data, and re-labels it when it is read back. It lives in
 ledger.path from the config, else ADTL_LEDGER, else ~/.adtl/ledger.db.
 
   stats       Count entries.
-  verify      Check that no entry was changed or removed (exit 1 if one was).
+  verify      Check that no entry was changed or removed, and that signed
+              entries are signed by this machine's key (exit 1 if not).
   declassify  Clear the label of each file's current content. Check the
               files first: after this, ADTL treats that content as clean.
               --reason is required and kept in the ledger.
@@ -68,7 +70,10 @@ export async function runLedgerCommand(argv: string[], env: NodeJS.ProcessEnv =
     if (parsed.ledger.path) path = resolve(dirname(abs), parsed.ledger.path);
     retentionDays = parsed.ledger.retentionDays;
   }
-  const ledger = new Ledger(path, retentionDays ? { retentionDays } : {});
+  // Declassifying signs its entries; verifying only reads the key, to know whose signatures to trust.
+  const keyPath = defaultSigningKeyPath(env);
+  const signer = cmd === "declassify" ? trySigner(keyPath) : loadSigner(keyPath);
+  const ledger = new Ledger(path, { ...(retentionDays ? { retentionDays } : {}), ...(signer ? { signer } : {}) });
   try {
     if (cmd === "stats") {
       const s = ledger.stats();
@@ -76,8 +81,9 @@ export async function runLedgerCommand(argv: string[], env: NodeJS.ProcessEnv =
     }
     if (cmd === "verify") {
       const v = ledger.verify();
+      const sigs = v.signed ? `, ${v.signed} signed${v.unsigned ? `, ${v.unsigned} from before signing` : ""}` : "";
       return v.ok
-        ? { stdout: `${path}: ${v.entries} entries, chain intact`, exitCode: 0 }
+        ? { stdout: `${path}: ${v.entries} entries${sigs}, chain intact`, exitCode: 0 }
         : { stdout: `${path}: TAMPERED: ${v.problem}`, exitCode: 1 };
     }
     if (cmd === "declassified") {

package/src/ntfy.ts

@@ -12,6 +12,8 @@
 import type { AnswerFn, ApprovalEvent, ApprovalRequest, Notifier } from "./approvals.js";
 
 export interface NtfyOptions {
+  /** Channel name in approval results and logs. Default: "ntfy". */
+  name?: string;
   /** Server base URL, e.g. https://ntfy.sh */
   server: string;
   topic: string;
@@ -32,7 +34,7 @@ function describe(request: ApprovalRequest): string {
 }
 
 export class NtfyNotifier implements Notifier {
-  readonly name = "ntfy";
+  readonly name: string;
   private readonly server: string;
   private readonly topic: string;
   private readonly replyTopic: string;
@@ -42,6 +44,7 @@ export class NtfyNotifier implements Notifier {
   private readonly publishAttempts: number;
 
   constructor(opts: NtfyOptions) {
+    this.name = opts.name ?? "ntfy";
     this.server = opts.server.replace(/\/+$/, "");
     this.topic = opts.topic;
     this.replyTopic = opts.replyTopic ?? `${opts.topic}-reply`;

package/src/playgroundCli.ts

@@ -0,0 +1,60 @@
+/**
+ * `adtl-gateway playground [--port 4317] [--no-open]`: the web playground, with
+ * the real gateway in front of fake GitHub and memory servers. Listens on
+ * 127.0.0.1 only and opens the browser unless --no-open is given.
+ */
+import { spawn } from "node:child_process";
+
+export const PLAYGROUND_USAGE = `Usage: adtl-gateway playground [--port <n>] [--no-open]
+
+Runs the ADTL gateway in front of fake GitHub and memory servers, with a
+browser UI: three test cases, every call's label and decision, the session
+label, approvals, the config and the audit log. Nothing leaves your machine.
+
+  --port <n>   Port on 127.0.0.1 (default 4317; 0 picks a free one).
+  --no-open    Don't open the browser.`;
+
+interface Playground {
+  url: string;
+  close(): Promise<void>;
+}
+
+export function parsePlaygroundArgs(argv: string[]): { port: number; open: boolean; help: boolean } {
+  let port = 4317;
+  let open = true;
+  let help = false;
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]!;
+    if (a === "--port") port = Number(argv[++i]);
+    else if (a === "--no-open") open = false;
+    else if (a === "-h" || a === "--help") help = true;
+    else throw new Error(`Unknown argument: ${a}\n\n${PLAYGROUND_USAGE}`);
+  }
+  if (!Number.isInteger(port) || port < 0 || port > 65535) throw new Error(`--port must be a number from 0 to 65535\n\n${PLAYGROUND_USAGE}`);
+  return { port, open, help };
+}
+
+function openBrowser(url: string): void {
+  const [cmd, args] =
+    process.platform === "darwin" ? ["open", [url]] : process.platform === "win32" ? ["cmd", ["/c", "start", "", url]] : ["xdg-open", [url]];
+  try {
+    spawn(cmd, args, { stdio: "ignore", detached: true }).on("error", () => {}).unref();
+  } catch {
+    // No browser to open: the URL is printed anyway.
+  }
+}
+
+export async function runPlayground(argv: string[]): Promise<void> {
+  const opts = parsePlaygroundArgs(argv);
+  if (opts.help) return void console.log(PLAYGROUND_USAGE);
+  // Plain JavaScript shipped next to dist/, not compiled.
+  const mod = (await import(new URL("../playground/server.mjs", import.meta.url).href)) as {
+    startPlayground(o: { port: number }): Promise<Playground>;
+  };
+  const pg = await mod.startPlayground({ port: opts.port });
+  console.log(`ADTL playground: ${pg.url}  (Ctrl-C to stop)`);
+  if (opts.open) openBrowser(pg.url);
+  for (const sig of ["SIGINT", "SIGTERM"] as const) {
+    process.once(sig, () => void pg.close().finally(() => process.exit(0)));
+  }
+}

package/src/receipt.ts

@@ -0,0 +1,148 @@
+/**
+ * Session receipts: a signed summary of every call a session made through
+ * the gateway and the Claude Code hooks, built from the hash-chained audit log.
+ *
+ * Agents can misreport what they did; the audit log is written outside the
+ * model. A receipt names the session, lists each call (tool, outcome,
+ * decision, approver, call hash, result label, and the hash of its audit log
+ * line) with counts, and is signed with the machine's Ed25519 key. Anyone with
+ * the public key can check it, and with the log at hand, that it lists every
+ * line the session wrote between its first and last call.
+ *
+ * Receipts cover what crossed the gateway and the hooks, not everything the
+ * agent did. Arguments and results are never included.
+ */
+import { readFileSync } from "node:fs";
+import { verifyCanonical, signCanonical, type Signer } from "@adtl/labels";
+import { verifyAuditLog, type AuditEntry } from "./audit.js";
+
+export const RECEIPT_TYPE = "adtl.receipt.v1";
+
+export interface ReceiptCall {
+  ts: string;
+  event: AuditEntry["event"];
+  server: string;
+  tool?: string;
+  resource?: string;
+  prompt?: string;
+  outcome: AuditEntry["outcome"];
+  decision?: string;
+  approver?: string;
+  callHash?: string;
+  /** Integrity and confidentiality of the result. */
+  label?: { integrity: string; confidentiality: string };
+  /** Hash of this call's audit log line. */
+  line: string;
+}
+
+export interface Receipt {
+  type: typeof RECEIPT_TYPE;
+  sessionId: string;
+  createdAt: string;
+  counts: { calls: number; forwarded: number; blocked: number; asked: number; upstreamErrors: number; approved: number; denied: number };
+  calls: ReceiptCall[];
+  /** Public key that signed it, `ed25519:…`. */
+  signer: string;
+  signature: string;
+}
+
+type ChainedEntry = AuditEntry & { hash: string };
+
+function chainedEntries(logPath: string): ChainedEntry[] {
+  const v = verifyAuditLog(logPath);
+  if (!v.ok) throw new Error(`${logPath}: the audit log was tampered with (${v.problem}); refusing to issue a receipt`);
+  return readFileSync(logPath, "utf8")
+    .split("\n")
+    .filter((l) => l.trim())
+    .map((l) => JSON.parse(l) as Partial<ChainedEntry>)
+    .filter((e): e is ChainedEntry => typeof e.hash === "string" && typeof e.sessionId === "string");
+}
+
+/** Sessions in the audit log, with their number of calls and last activity. */
+export function listSessions(logPath: string): { sessionId: string; calls: number; last: string }[] {
+  const out = new Map<string, { sessionId: string; calls: number; last: string }>();
+  for (const e of chainedEntries(logPath)) {
+    const s = out.get(e.sessionId) ?? { sessionId: e.sessionId, calls: 0, last: e.ts };
+    s.calls++;
+    if (e.ts > s.last) s.last = e.ts;
+    out.set(e.sessionId, s);
+  }
+  return [...out.values()].sort((a, b) => b.last.localeCompare(a.last));
+}
+
+function receiptCall(e: ChainedEntry): ReceiptCall {
+  const label = e.label as { integrity?: unknown; confidentiality?: unknown } | undefined;
+  return {
+    ts: e.ts,
+    event: e.event,
+    server: e.server,
+    ...(e.tool !== undefined ? { tool: e.tool } : {}),
+    ...(e.resource !== undefined ? { resource: e.resource } : {}),
+    ...(e.prompt !== undefined ? { prompt: e.prompt } : {}),
+    outcome: e.outcome,
+    ...(e.decision !== undefined ? { decision: e.decision } : {}),
+    ...(e.approval?.approver !== undefined ? { approver: e.approval.approver } : {}),
+    ...(typeof e.callHash === "string" ? { callHash: e.callHash } : {}),
+    ...(typeof label?.integrity === "string" && typeof label.confidentiality === "string"
+      ? { label: { integrity: label.integrity, confidentiality: label.confidentiality } }
+      : {}),
+    line: e.hash,
+  };
+}
+
+/** Build and sign the receipt for `sessionId` from a verified audit log. */
+export function buildReceipt(logPath: string, sessionId: string, signer: Signer, now: Date = new Date()): Receipt {
+  const entries = chainedEntries(logPath).filter((e) => e.sessionId === sessionId);
+  if (entries.length === 0) throw new Error(`${logPath} has no entries for session ${sessionId}`);
+  const count = (f: (e: ChainedEntry) => boolean) => entries.filter(f).length;
+  const unsigned: Omit<Receipt, "signature"> = {
+    type: RECEIPT_TYPE,
+    sessionId,
+    createdAt: now.toISOString(),
+    counts: {
+      calls: entries.length,
+      forwarded: count((e) => e.outcome === "forwarded"),
+      blocked: count((e) => e.outcome === "blocked"),
+      asked: count((e) => e.outcome === "asked"),
+      upstreamErrors: count((e) => e.outcome === "upstream_error"),
+      approved: count((e) => e.approval?.outcome === "approved"),
+      denied: count((e) => e.approval?.outcome === "denied"),
+    },
+    calls: entries.map(receiptCall),
+    signer: signer.publicKey,
+  };
+  return { ...unsigned, signature: signCanonical(signer, unsigned) };
+}
+
+export interface ReceiptCheck {
+  ok: boolean;
+  problem?: string;
+}
+
+/**
+ * Check a receipt's signature, that it is signed by `trustedKey` if given,
+ * and, with `logPath`, that the log is intact and the receipt lists exactly
+ * the session's lines from its first call to its last.
+ */
+export function verifyReceipt(receipt: Receipt, opts: { logPath?: string; trustedKey?: string } = {}): ReceiptCheck {
+  const { signature, ...unsigned } = receipt;
+  if (receipt.type !== RECEIPT_TYPE) return { ok: false, problem: `not an ADTL receipt (type ${String(receipt.type)})` };
+  if (!verifyCanonical(receipt.signer, unsigned, signature)) return { ok: false, problem: "the signature doesn't match: the receipt was changed or forged" };
+  if (opts.trustedKey && receipt.signer !== opts.trustedKey) return { ok: false, problem: `signed by ${receipt.signer}, not the expected key` };
+  if (!opts.logPath) return { ok: true };
+  let entries: ChainedEntry[];
+  try {
+    entries = chainedEntries(opts.logPath);
+  } catch (err) {
+    return { ok: false, problem: (err as Error).message };
+  }
+  const lines = receipt.calls.map((c) => c.line);
+  const first = entries.findIndex((e) => e.hash === lines[0]);
+  const last = entries.findIndex((e) => e.hash === lines.at(-1));
+  if (first < 0 || last < 0) return { ok: false, problem: "the log doesn't contain the receipt's calls" };
+  const logged = entries.slice(first, last + 1).filter((e) => e.sessionId === receipt.sessionId);
+  if (logged.length !== lines.length || logged.some((e, i) => e.hash !== lines[i])) {
+    return { ok: false, problem: "the receipt doesn't list exactly the session's calls in the log" };
+  }
+  return { ok: true };
+}

package/src/receiptCli.ts

@@ -0,0 +1,85 @@
+/**
+ * `adtl-gateway receipt` and `adtl-gateway key`.
+ *
+ *   adtl-gateway receipt list [<log>] [-c adtl.yaml]
+ *   adtl-gateway receipt <session> [<log>] [-c adtl.yaml] [-o receipt.json]
+ *   adtl-gateway receipt verify <receipt.json> [--log <log>] [--key ed25519:…]
+ *   adtl-gateway key
+ */
+import { readFile, writeFile } from "node:fs/promises";
+import { defaultSigningKeyPath, loadOrCreateSigner } from "@adtl/labels";
+import { resolveAuditPath } from "./auditCli.js";
+import { buildReceipt, listSessions, verifyReceipt, type Receipt } from "./receipt.js";
+
+export const RECEIPT_USAGE = `Usage: adtl-gateway receipt list [<log>] [-c <adtl.yaml>]
+       adtl-gateway receipt <session> [<log>] [-c <adtl.yaml>] [-o <receipt.json>]
+       adtl-gateway receipt verify <receipt.json> [--log <log>] [--key <ed25519:...>]
+       adtl-gateway key
+
+A receipt is a signed summary of every call one session made through the
+gateway and the Claude Code hooks: tool, outcome, decision, approver, call
+hash, result label and the hash of each audit log line. It is built from the
+hash-chained audit log (gateway.audit) and signed with this machine's key
+(ADTL_SIGNING_KEY, or ~/.adtl/signing-key.pem).
+
+  list     Sessions in the log, newest first.
+  verify   Check the signature; with --log, also that the receipt lists every
+           line the session wrote; with --key, who signed it (exit 1 if not).
+  key      Print this machine's public key, to give to whoever checks receipts.`;
+
+export interface ReceiptCommandResult {
+  stdout: string;
+  exitCode: number;
+}
+
+export async function runKeyCommand(env: NodeJS.ProcessEnv = process.env): Promise<ReceiptCommandResult> {
+  const path = defaultSigningKeyPath(env);
+  const signer = loadOrCreateSigner(path);
+  return { stdout: `${signer.publicKey}\nkey id: ${signer.keyId}\nfile: ${path}`, exitCode: 0 };
+}
+
+export async function runReceiptCommand(argv: string[], env: NodeJS.ProcessEnv = process.env): Promise<ReceiptCommandResult> {
+  const [cmd, ...rest] = argv;
+  if (cmd === undefined || cmd === "-h" || cmd === "--help") return { stdout: RECEIPT_USAGE, exitCode: 0 };
+  let config: string | undefined;
+  let out: string | undefined;
+  let log: string | undefined;
+  let key: string | undefined;
+  const args: string[] = [];
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i]!;
+    if (a === "-c" || a === "--config") config = rest[++i];
+    else if (a === "-o" || a === "--out") out = rest[++i];
+    else if (a === "--log") log = rest[++i];
+    else if (a === "--key") key = rest[++i];
+    else if (a.startsWith("-")) throw new Error(`Unknown argument: ${a}\n\n${RECEIPT_USAGE}`);
+    else args.push(a);
+  }
+
+  if (cmd === "verify") {
+    if (args.length !== 1) throw new Error(`receipt verify needs one receipt file\n\n${RECEIPT_USAGE}`);
+    const receipt = JSON.parse(await readFile(args[0]!, "utf8")) as Receipt;
+    const r = verifyReceipt(receipt, { ...(log ? { logPath: log } : {}), ...(key ? { trustedKey: key } : {}) });
+    if (!r.ok) return { stdout: `${args[0]}: INVALID: ${r.problem}`, exitCode: 1 };
+    const checked = [`signed by ${receipt.signer}`, ...(key ? ["the expected key"] : []), ...(log ? ["matches the log"] : [])];
+    return { stdout: `${args[0]}: valid (${checked.join(", ")}): ${receipt.counts.calls} calls in session ${receipt.sessionId}`, exitCode: 0 };
+  }
+
+  if (cmd === "list") {
+    if (args.length > 1) throw new Error(`Unexpected argument: ${args[1]}\n\n${RECEIPT_USAGE}`);
+    const path = await resolveAuditPath(args[0], config, RECEIPT_USAGE);
+    const sessions = listSessions(path);
+    if (sessions.length === 0) return { stdout: `${path}: no sessions`, exitCode: 0 };
+    return { stdout: sessions.map((s) => `${s.last}  ${s.sessionId}  ${s.calls} call${s.calls === 1 ? "" : "s"}`).join("\n"), exitCode: 0 };
+  }
+
+  if (args.length > 1) throw new Error(`Unexpected argument: ${args[1]}\n\n${RECEIPT_USAGE}`);
+  const path = await resolveAuditPath(args[0], config, RECEIPT_USAGE);
+  const receipt = buildReceipt(path, cmd, loadOrCreateSigner(defaultSigningKeyPath(env)));
+  const json = `${JSON.stringify(receipt, null, 2)}\n`;
+  if (out) {
+    await writeFile(out, json);
+    return { stdout: `${out}: receipt for ${receipt.counts.calls} calls in session ${cmd}`, exitCode: 0 };
+  }
+  return { stdout: json.trimEnd(), exitCode: 0 };
+}

package/src/roles.ts

@@ -0,0 +1,55 @@
+/**
+ * Role-based authorization from the config (`gateway.roles`):
+ *
+ *   roles:
+ *     maintainers: { members: [alice, bob], tools: ["github.*"] }
+ *     readers:     { members: ["*"],        tools: ["github.read_*", "github.get_*"] }
+ *
+ * A call is allowed if a role the caller belongs to grants it: `tools` and
+ * `prompts` are `server.name` patterns (the same `*` wildcards as policy
+ * rules), `resources` are URI patterns. Everything else is denied. Members
+ * are principal ids; "*" means everyone, including an anonymous caller.
+ */
+import { globToRegExp } from "@adtl/labels";
+import type { AuthorizationDecision, AuthorizationRequest, Authorizer } from "./authorizer.js";
+import type { RoleConfig } from "./config.js";
+
+interface CompiledRole {
+  name: string;
+  members: Set<string>;
+  tools: RegExp[];
+  prompts: RegExp[];
+  resources: RegExp[];
+}
+
+export class RoleAuthorizer implements Authorizer {
+  readonly name = "roles";
+  private readonly roles: CompiledRole[];
+
+  constructor(roles: Record<string, RoleConfig>) {
+    this.roles = Object.entries(roles).map(([name, r]) => ({
+      name,
+      members: new Set(r.members),
+      tools: r.tools.map(globToRegExp),
+      prompts: r.prompts.map(globToRegExp),
+      resources: r.resources.map(globToRegExp),
+    }));
+  }
+
+  check(req: AuthorizationRequest): AuthorizationDecision {
+    const id = req.principal.id;
+    const [kind, what] =
+      req.event === "tools/call"
+        ? (["tools", `${req.server}.${req.tool}`] as const)
+        : req.event === "prompts/get"
+          ? (["prompts", `${req.server}.${req.prompt}`] as const)
+          : (["resources", req.resource ?? ""] as const);
+    const granted = this.roles.some(
+      (r) => (r.members.has("*") || (id !== undefined && r.members.has(id))) && r[kind].some((p) => p.test(what)),
+    );
+    if (granted) return { allow: true };
+    const who = id ?? "an anonymous caller";
+    const noun = kind === "tools" ? "tool" : kind === "prompts" ? "prompt" : "resource";
+    return { allow: false, reason: `No role lets ${who} use the ${noun} ${what}` };
+  }
+}