@adtl/gateway 0.5.1 → 0.6.0

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}` };
+  }
+}

package/src/startup.ts

@@ -9,14 +9,16 @@ import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StdioClientTransport, getDefaultEnvironment } from "@modelcontextprotocol/sdk/client/stdio.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import { INTERCEPTORS_EXTENSION, LABEL_INTERCEPTOR, POLICY_INTERCEPTOR, parseConfigText } from "@adtl/interceptors";
-import { defaultSessionsDir, type AdtlConfig } from "@adtl/labels";
+import { SIGNING_KEY_ENV, defaultSessionsDir, 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 type { Principal } from "./authorizer.js";
 import {
   GatewayConfigSchema,
   expandApprovals,
+  expandEnv,
   expandUpstream,
   isHttpUpstream,
   type GatewayConfig,
@@ -27,6 +29,7 @@ import { EmailNotifier } from "./email.js";
 import { AdtlGateway, GATEWAY_VERSION, type GatewayLogger } from "./gateway.js";
 import { InterceptorInvoker } from "./invoker.js";
 import { NtfyNotifier } from "./ntfy.js";
+import { RoleAuthorizer } from "./roles.js";
 
 export class GatewayConfigError extends Error {
   constructor(message: string) {
@@ -117,10 +120,54 @@ export function createApprovals(cfg: GatewayConfig, env: NodeJS.ProcessEnv, log:
   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 });
+  const approverChannels = new Map<string, Notifier[]>(
+    Object.entries(a.approvers ?? {}).map(([id, c]) => [id, [new NtfyNotifier({ ...c.ntfy, name: `ntfy:${id}` })]]),
+  );
+  if (notifiers.length === 0 && approverChannels.size === 0 && !a.elicitation) return undefined;
+  if (!notifiers.some((n) => n.listen) && approverChannels.size === 0 && !a.elicitation) {
+    log.warn('no approval channel can carry answers (configure gateway.approvals.ntfy); "ask" still blocks');
+  }
+  const approvers = approverChannels.size ? `; approvers: ${[...approverChannels.keys()].join(", ")}` : "";
+  const shared = [...notifiers.map((n) => n.name), ...(a.elicitation ? ["elicitation (if the client supports it)"] : [])];
+  log.info(`approvals: ${shared.join(", ") || "none shared"}${approvers} (timeout ${a.timeoutSeconds}s)`);
+  return new ApprovalBroker({ notifiers, approverChannels, timeoutMs: a.timeoutSeconds * 1000, log });
+}
+
+/**
+ * Check that every role a policy rule names under `approvers:` exists, has
+ * named members, and that each member has a channel in
+ * `gateway.approvals.approvers`. Returns each such role's members.
+ */
+export function approverRoles(labels: AdtlConfig, cfg: GatewayConfig): Map<string, string[]> {
+  const out = new Map<string, string[]>();
+  const problems: string[] = [];
+  for (const rule of labels.policy.rules) {
+    for (const role of rule.approvers ?? []) {
+      if (out.has(role)) continue;
+      const r = cfg.roles?.[role];
+      if (!r) {
+        problems.push(`policy rule "${rule.name}" names approver role "${role}", which is not under gateway.roles`);
+        continue;
+      }
+      const members = [...r.members];
+      if (members.includes("*")) problems.push(`approver role "${role}" has member "*": approvers must be named, so the answer says who approved`);
+      for (const m of members.filter((x) => x !== "*")) {
+        if (!cfg.approvals?.approvers?.[m]) problems.push(`approver "${m}" (role "${role}") has no channel under gateway.approvals.approvers`);
+      }
+      out.set(role, members);
+    }
+  }
+  if (problems.length) throw new GatewayConfigError(`approvers:\n${problems.map((p) => `  - ${p}`).join("\n")}`);
+  return out;
+}
+
+/** `gateway.principal`, with `${VAR}` in its id expanded. */
+export function gatewayPrincipal(cfg: GatewayConfig, env: NodeJS.ProcessEnv): Principal | undefined {
+  const p = cfg.principal;
+  if (!p) return undefined;
+  const id = expandEnv(p.id, env, "gateway.principal.id").trim();
+  if (!id) throw new GatewayConfigError("gateway.principal.id is empty after expanding environment variables");
+  return { type: p.type, id, ...(p.claims ? { claims: p.claims } : {}) };
 }
 
 /**
@@ -143,6 +190,8 @@ export async function startGateway(
   opts: { env?: NodeJS.ProcessEnv; logger?: GatewayLogger } = {},
 ): Promise<StartedGateway> {
   const env = opts.env ?? process.env;
+  // Config problems that need no process: fail before starting any.
+  const approverMembers = approverRoles(loaded.labels, loaded.gateway);
   const baseDir = dirname(loaded.path);
   const log = opts.logger ?? { info: (m: string) => console.error(`[adtl-gateway] ${m}`), warn: (m: string) => console.error(`[adtl-gateway] warning: ${m}`) };
   const clients: Client[] = [];
@@ -153,7 +202,10 @@ export async function startGateway(
     const shared = sharedSession(env);
     const custom = loaded.gateway.interceptors && expandUpstream("interceptors", loaded.gateway.interceptors, env);
     // The interceptor process starts with a minimal environment; pass on where the ledger lives.
-    const ledgerEnv: Record<string, string> = env.ADTL_LEDGER ? { ADTL_LEDGER: env.ADTL_LEDGER } : {};
+    const ledgerEnv: Record<string, string> = {
+      ...(env.ADTL_LEDGER ? { ADTL_LEDGER: env.ADTL_LEDGER } : {}),
+      ...(env[SIGNING_KEY_ENV] ? { [SIGNING_KEY_ENV]: env[SIGNING_KEY_ENV]! } : {}),
+    };
     const icfg: StdioUpstream = custom
       ? { ...custom, env: { ...ledgerEnv, ...custom.env, ...(shared ? { ADTL_SESSIONS_DIR: shared.dir } : {}) } }
       : {
@@ -202,12 +254,22 @@ export async function startGateway(
 
     const auditLog = loaded.gateway.audit ? new JsonlAuditLog(resolve(baseDir, loaded.gateway.audit)) : undefined;
     const approvals = createApprovals(loaded.gateway, env, log);
+    const principal = gatewayPrincipal(loaded.gateway, env);
+    const roles = loaded.gateway.roles;
+    if (roles) {
+      log.info(`roles: ${Object.keys(roles).join(", ")} (caller: ${principal?.id ?? "anonymous"})`);
+      if (!principal) log.warn('roles are set but gateway.principal is not: only roles with members ["*"] apply');
+    }
     const gateway = new AdtlGateway({
       ...(shared ? { sessionId: shared.sessionId } : {}),
       upstreams,
       invoker,
       ...(auditLog ? { audit: auditLog } : {}),
       ...(approvals ? { approvals } : {}),
+      ...(roles ? { authorizer: new RoleAuthorizer(roles) } : {}),
+      ...(principal ? { principal } : {}),
+      ...(approverMembers.size ? { approverRoles: approverMembers } : {}),
+      ...(loaded.gateway.approvals?.elicitation ? { elicitApprovals: true } : {}),
       logger: log,
     });
     return { gateway, close: closeAll };