@adtl/gateway 0.5.1 → 0.6.0

package/dist/playgroundCli.js

@@ -0,0 +1,57 @@
+/**
+ * `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.`;
+export function parsePlaygroundArgs(argv) {
+    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) {
+    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) {
+    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));
+    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"]) {
+        process.once(sig, () => void pg.close().finally(() => process.exit(0)));
+    }
+}
+//# sourceMappingURL=playgroundCli.js.map

package/dist/playgroundCli.js.map

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

package/dist/receipt.d.ts

@@ -0,0 +1,62 @@
+import { type Signer } from "@adtl/labels";
+import { type AuditEntry } from "./audit.js";
+export declare 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;
+}
+/** Sessions in the audit log, with their number of calls and last activity. */
+export declare function listSessions(logPath: string): {
+    sessionId: string;
+    calls: number;
+    last: string;
+}[];
+/** Build and sign the receipt for `sessionId` from a verified audit log. */
+export declare function buildReceipt(logPath: string, sessionId: string, signer: Signer, now?: Date): Receipt;
+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 declare function verifyReceipt(receipt: Receipt, opts?: {
+    logPath?: string;
+    trustedKey?: string;
+}): ReceiptCheck;
+//# sourceMappingURL=receipt.d.ts.map

package/dist/receipt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"receipt.d.ts","sourceRoot":"","sources":["../src/receipt.ts"],"names":[],"mappings":"AAeA,OAAO,EAAkC,KAAK,MAAM,EAAE,MAAM,cAAc,CAAC;AAC3E,OAAO,EAAkB,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7D,eAAO,MAAM,YAAY,oBAAoB,CAAC;AAE9C,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,UAAU,CAAC,OAAO,CAAC,CAAC;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,UAAU,CAAC,SAAS,CAAC,CAAC;IAC/B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mDAAmD;IACnD,KAAK,CAAC,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,eAAe,EAAE,MAAM,CAAA;KAAE,CAAC;IACvD,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,OAAO,YAAY,CAAC;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,cAAc,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IACvI,KAAK,EAAE,WAAW,EAAE,CAAC;IACrB,8CAA8C;IAC9C,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;CACnB;AAcD,+EAA+E;AAC/E,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EAAE,CASlG;AAsBD,4EAA4E;AAC5E,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,GAAE,IAAiB,GAAG,OAAO,CAqBhH;AAED,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,OAAO,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,GAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,YAAY,CAqBlH"}

package/dist/receipt.js

@@ -0,0 +1,117 @@
+/**
+ * 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 } from "@adtl/labels";
+import { verifyAuditLog } from "./audit.js";
+export const RECEIPT_TYPE = "adtl.receipt.v1";
+function chainedEntries(logPath) {
+    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))
+        .filter((e) => 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) {
+    const out = new Map();
+    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) {
+    const label = e.label;
+    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, sessionId, signer, now = new Date()) {
+    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) => entries.filter(f).length;
+    const unsigned = {
+        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) };
+}
+/**
+ * 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, opts = {}) {
+    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;
+    try {
+        entries = chainedEntries(opts.logPath);
+    }
+    catch (err) {
+        return { ok: false, problem: err.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 };
+}
+//# sourceMappingURL=receipt.js.map

package/dist/receipt.js.map

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

package/dist/receiptCli.d.ts

@@ -0,0 +1,8 @@
+export declare const RECEIPT_USAGE = "Usage: adtl-gateway receipt list [<log>] [-c <adtl.yaml>]\n       adtl-gateway receipt <session> [<log>] [-c <adtl.yaml>] [-o <receipt.json>]\n       adtl-gateway receipt verify <receipt.json> [--log <log>] [--key <ed25519:...>]\n       adtl-gateway key\n\nA receipt is a signed summary of every call one session made through the\ngateway and the Claude Code hooks: tool, outcome, decision, approver, call\nhash, result label and the hash of each audit log line. It is built from the\nhash-chained audit log (gateway.audit) and signed with this machine's key\n(ADTL_SIGNING_KEY, or ~/.adtl/signing-key.pem).\n\n  list     Sessions in the log, newest first.\n  verify   Check the signature; with --log, also that the receipt lists every\n           line the session wrote; with --key, who signed it (exit 1 if not).\n  key      Print this machine's public key, to give to whoever checks receipts.";
+export interface ReceiptCommandResult {
+    stdout: string;
+    exitCode: number;
+}
+export declare function runKeyCommand(env?: NodeJS.ProcessEnv): Promise<ReceiptCommandResult>;
+export declare function runReceiptCommand(argv: string[], env?: NodeJS.ProcessEnv): Promise<ReceiptCommandResult>;
+//# sourceMappingURL=receiptCli.d.ts.map

package/dist/receiptCli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"receiptCli.d.ts","sourceRoot":"","sources":["../src/receiptCli.ts"],"names":[],"mappings":"AAaA,eAAO,MAAM,aAAa,o4BAcsD,CAAC;AAEjF,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,wBAAsB,aAAa,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAIvG;AAED,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CA4C3H"}

package/dist/receiptCli.js

@@ -0,0 +1,87 @@
+/**
+ * `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 } 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 async function runKeyCommand(env = process.env) {
+    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, env = process.env) {
+    const [cmd, ...rest] = argv;
+    if (cmd === undefined || cmd === "-h" || cmd === "--help")
+        return { stdout: RECEIPT_USAGE, exitCode: 0 };
+    let config;
+    let out;
+    let log;
+    let key;
+    const args = [];
+    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"));
+        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 };
+}
+//# sourceMappingURL=receiptCli.js.map

package/dist/receiptCli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"receiptCli.js","sourceRoot":"","sources":["../src/receiptCli.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,EAAE,qBAAqB,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AACzE,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,aAAa,EAAgB,MAAM,cAAc,CAAC;AAEvF,MAAM,CAAC,MAAM,aAAa,GAAG;;;;;;;;;;;;;;gFAcmD,CAAC;AAOjF,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,MAAyB,OAAO,CAAC,GAAG;IACtE,MAAM,IAAI,GAAG,qBAAqB,CAAC,GAAG,CAAC,CAAC;IACxC,MAAM,MAAM,GAAG,kBAAkB,CAAC,IAAI,CAAC,CAAC;IACxC,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC,SAAS,aAAa,MAAM,CAAC,KAAK,WAAW,IAAI,EAAE,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC;AAChG,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,IAAc,EAAE,MAAyB,OAAO,CAAC,GAAG;IAC1F,MAAM,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC;IAC5B,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,IAAI,IAAI,GAAG,KAAK,QAAQ;QAAE,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC;IACzG,IAAI,MAA0B,CAAC;IAC/B,IAAI,GAAuB,CAAC;IAC5B,IAAI,GAAuB,CAAC;IAC5B,IAAI,GAAuB,CAAC;IAC5B,MAAM,IAAI,GAAa,EAAE,CAAC;IAC1B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC,CAAE,CAAC;QACnB,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,UAAU;YAAE,MAAM,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;aAClD,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,OAAO;YAAE,GAAG,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;aACjD,IAAI,CAAC,KAAK,OAAO;YAAE,GAAG,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;aACnC,IAAI,CAAC,KAAK,OAAO;YAAE,GAAG,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;aACnC,IAAI,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,qBAAqB,CAAC,OAAO,aAAa,EAAE,CAAC,CAAC;;YACrF,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACpB,CAAC;IAED,IAAI,GAAG,KAAK,QAAQ,EAAE,CAAC;QACrB,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,4CAA4C,aAAa,EAAE,CAAC,CAAC;QACpG,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAE,EAAE,MAAM,CAAC,CAAY,CAAC;QACxE,MAAM,CAAC,GAAG,aAAa,CAAC,OAAO,EAAE,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;QAC5G,IAAI,CAAC,CAAC,CAAC,EAAE;YAAE,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,OAAO,EAAE,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC;QAC/E,MAAM,OAAO,GAAG,CAAC,aAAa,OAAO,CAAC,MAAM,EAAE,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QAC3H,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC,YAAY,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,OAAO,CAAC,MAAM,CAAC,KAAK,qBAAqB,OAAO,CAAC,SAAS,EAAE,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC;IAC7I,CAAC;IAED,IAAI,GAAG,KAAK,MAAM,EAAE,CAAC;QACnB,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,wBAAwB,IAAI,CAAC,CAAC,CAAC,OAAO,aAAa,EAAE,CAAC,CAAC;QAC5F,MAAM,IAAI,GAAG,MAAM,gBAAgB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,aAAa,CAAC,CAAC;QACpE,MAAM,QAAQ,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;QACpC,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,eAAe,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC;QAClF,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,SAAS,KAAK,CAAC,CAAC,KAAK,QAAQ,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC;IAC1I,CAAC;IAED,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,wBAAwB,IAAI,CAAC,CAAC,CAAC,OAAO,aAAa,EAAE,CAAC,CAAC;IAC5F,MAAM,IAAI,GAAG,MAAM,gBAAgB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,aAAa,CAAC,CAAC;IACpE,MAAM,OAAO,GAAG,YAAY,CAAC,IAAI,EAAE,GAAG,EAAE,kBAAkB,CAAC,qBAAqB,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IACxF,MAAM,IAAI,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC;IACrD,IAAI,GAAG,EAAE,CAAC;QACR,MAAM,SAAS,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QAC3B,OAAO,EAAE,MAAM,EAAE,GAAG,GAAG,iBAAiB,OAAO,CAAC,MAAM,CAAC,KAAK,qBAAqB,GAAG,EAAE,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC;IACxG,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,OAAO,EAAE,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC;AACjD,CAAC"}

package/dist/roles.d.ts

@@ -0,0 +1,9 @@
+import type { AuthorizationDecision, AuthorizationRequest, Authorizer } from "./authorizer.js";
+import type { RoleConfig } from "./config.js";
+export declare class RoleAuthorizer implements Authorizer {
+    readonly name = "roles";
+    private readonly roles;
+    constructor(roles: Record<string, RoleConfig>);
+    check(req: AuthorizationRequest): AuthorizationDecision;
+}
+//# sourceMappingURL=roles.d.ts.map

package/dist/roles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"roles.d.ts","sourceRoot":"","sources":["../src/roles.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC/F,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAU9C,qBAAa,cAAe,YAAW,UAAU;IAC/C,QAAQ,CAAC,IAAI,WAAW;IACxB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiB;gBAE3B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC;IAU7C,KAAK,CAAC,GAAG,EAAE,oBAAoB,GAAG,qBAAqB;CAgBxD"}

package/dist/roles.js

@@ -0,0 +1,41 @@
+/**
+ * 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";
+export class RoleAuthorizer {
+    name = "roles";
+    roles;
+    constructor(roles) {
+        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) {
+        const id = req.principal.id;
+        const [kind, what] = req.event === "tools/call"
+            ? ["tools", `${req.server}.${req.tool}`]
+            : req.event === "prompts/get"
+                ? ["prompts", `${req.server}.${req.prompt}`]
+                : ["resources", req.resource ?? ""];
+        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}` };
+    }
+}
+//# sourceMappingURL=roles.js.map

package/dist/roles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"roles.js","sourceRoot":"","sources":["../src/roles.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAY5C,MAAM,OAAO,cAAc;IAChB,IAAI,GAAG,OAAO,CAAC;IACP,KAAK,CAAiB;IAEvC,YAAY,KAAiC;QAC3C,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YACrD,IAAI;YACJ,OAAO,EAAE,IAAI,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC;YAC3B,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,YAAY,CAAC;YAChC,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC;YACpC,SAAS,EAAE,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,YAAY,CAAC;SACzC,CAAC,CAAC,CAAC;IACN,CAAC;IAED,KAAK,CAAC,GAAyB;QAC7B,MAAM,EAAE,GAAG,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;QAC5B,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,GAChB,GAAG,CAAC,KAAK,KAAK,YAAY;YACxB,CAAC,CAAE,CAAC,OAAO,EAAE,GAAG,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,IAAI,EAAE,CAAW;YACnD,CAAC,CAAC,GAAG,CAAC,KAAK,KAAK,aAAa;gBAC3B,CAAC,CAAE,CAAC,SAAS,EAAE,GAAG,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,MAAM,EAAE,CAAW;gBACvD,CAAC,CAAE,CAAC,WAAW,EAAE,GAAG,CAAC,QAAQ,IAAI,EAAE,CAAW,CAAC;QACrD,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAC7B,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,KAAK,SAAS,IAAI,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAC5G,CAAC;QACF,IAAI,OAAO;YAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;QACpC,MAAM,GAAG,GAAG,EAAE,IAAI,qBAAqB,CAAC;QACxC,MAAM,IAAI,GAAG,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC;QACpF,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,gBAAgB,GAAG,YAAY,IAAI,IAAI,IAAI,EAAE,EAAE,CAAC;IACjF,CAAC;CACF"}

package/dist/startup.d.ts

@@ -1,6 +1,7 @@
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { type AdtlConfig } from "@adtl/labels";
 import { ApprovalBroker } from "./approvals.js";
+import type { Principal } from "./authorizer.js";
 import { type GatewayConfig, type Upstream } from "./config.js";
 import { AdtlGateway, type GatewayLogger } from "./gateway.js";
 export declare class GatewayConfigError extends Error {
@@ -19,6 +20,14 @@ export declare function bundledInterceptorsCli(): string;
 export declare function connectUpstream(id: string, u: Upstream, baseDir: string): Promise<Client>;
 /** Build the approval broker from `gateway.approvals`, or undefined if not configured. */
 export declare function createApprovals(cfg: GatewayConfig, env: NodeJS.ProcessEnv, log: GatewayLogger): ApprovalBroker | undefined;
+/**
+ * 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 declare function approverRoles(labels: AdtlConfig, cfg: GatewayConfig): Map<string, string[]>;
+/** `gateway.principal`, with `${VAR}` in its id expanded. */
+export declare function gatewayPrincipal(cfg: GatewayConfig, env: NodeJS.ProcessEnv): Principal | undefined;
 /**
  * Under Claude Code, which passes `CLAUDE_CODE_SESSION_ID` to stdio MCP
  * servers, the gateway uses that id and keeps session labels in files, so the

package/dist/startup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"startup.d.ts","sourceRoot":"","sources":["../src/startup.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAInE,OAAO,EAAsB,KAAK,UAAU,EAAE,MAAM,cAAc,CAAC;AAGnE,OAAO,EAAE,cAAc,EAAiB,MAAM,gBAAgB,CAAC;AAE/D,OAAO,EAKL,KAAK,aAAa,EAElB,KAAK,QAAQ,EACd,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,WAAW,EAAmB,KAAK,aAAa,EAAE,MAAM,cAAc,CAAC;AAIhF,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,OAAO,EAAE,MAAM;CAI5B;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,UAAU,CAAC;IACnB,OAAO,EAAE,aAAa,CAAC;CACxB;AAED,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAS3E;AAED,8GAA8G;AAC9G,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,YAAY,CAqB/E;AAED,iDAAiD;AACjD,wBAAgB,sBAAsB,IAAI,MAAM,CAI/C;AAaD,wBAAsB,eAAe,CAAC,EAAE,EAAE,MAAM,EAAE,CAAC,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAO/F;AAED,0FAA0F;AAC1F,wBAAgB,eAAe,CAAC,GAAG,EAAE,aAAa,EAAE,GAAG,EAAE,MAAM,CAAC,UAAU,EAAE,GAAG,EAAE,aAAa,GAAG,cAAc,GAAG,SAAS,CAiB1H;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAGpG;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,WAAW,CAAC;IACrB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,wBAAsB,YAAY,CAChC,MAAM,EAAE,YAAY,EACpB,IAAI,GAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IAAC,MAAM,CAAC,EAAE,aAAa,CAAA;CAAO,GAC7D,OAAO,CAAC,cAAc,CAAC,CA0EzB"}
+{"version":3,"file":"startup.d.ts","sourceRoot":"","sources":["../src/startup.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAInE,OAAO,EAAuC,KAAK,UAAU,EAAE,MAAM,cAAc,CAAC;AAGpF,OAAO,EAAE,cAAc,EAAiB,MAAM,gBAAgB,CAAC;AAE/D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,EAML,KAAK,aAAa,EAElB,KAAK,QAAQ,EACd,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,WAAW,EAAmB,KAAK,aAAa,EAAE,MAAM,cAAc,CAAC;AAKhF,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,OAAO,EAAE,MAAM;CAI5B;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,UAAU,CAAC;IACnB,OAAO,EAAE,aAAa,CAAC;CACxB;AAED,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAS3E;AAED,8GAA8G;AAC9G,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,YAAY,CAqB/E;AAED,iDAAiD;AACjD,wBAAgB,sBAAsB,IAAI,MAAM,CAI/C;AAaD,wBAAsB,eAAe,CAAC,EAAE,EAAE,MAAM,EAAE,CAAC,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAO/F;AAED,0FAA0F;AAC1F,wBAAgB,eAAe,CAAC,GAAG,EAAE,aAAa,EAAE,GAAG,EAAE,MAAM,CAAC,UAAU,EAAE,GAAG,EAAE,aAAa,GAAG,cAAc,GAAG,SAAS,CAwB1H;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,UAAU,EAAE,GAAG,EAAE,aAAa,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAqB3F;AAED,6DAA6D;AAC7D,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,aAAa,EAAE,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,SAAS,GAAG,SAAS,CAMlG;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAGpG;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,WAAW,CAAC;IACrB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,wBAAsB,YAAY,CAChC,MAAM,EAAE,YAAY,EACpB,IAAI,GAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IAAC,MAAM,CAAC,EAAE,aAAa,CAAA;CAAO,GAC7D,OAAO,CAAC,cAAc,CAAC,CAyFzB"}

package/dist/startup.js

@@ -9,16 +9,17 @@ 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 } from "@adtl/labels";
+import { SIGNING_KEY_ENV, defaultSessionsDir } from "@adtl/labels";
 import { parse as parseYaml } from "yaml";
 import { ZodError } from "zod";
 import { ApprovalBroker } from "./approvals.js";
 import { JsonlAuditLog } from "./audit.js";
-import { GatewayConfigSchema, expandApprovals, expandUpstream, isHttpUpstream, } from "./config.js";
+import { GatewayConfigSchema, expandApprovals, expandEnv, 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";
+import { RoleAuthorizer } from "./roles.js";
 export class GatewayConfigError extends Error {
     constructor(message) {
         super(message);
@@ -100,12 +101,57 @@ export function createApprovals(cfg, env, 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)
+    const approverChannels = new Map(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))
+    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');
-    log.info(`approvals: ${notifiers.map((n) => n.name).join(", ")} (timeout ${a.timeoutSeconds}s)`);
-    return new ApprovalBroker({ notifiers, timeoutMs: a.timeoutSeconds * 1000, log });
+    }
+    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, cfg) {
+    const out = new Map();
+    const problems = [];
+    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, env) {
+    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 } : {}) };
 }
 /**
  * Under Claude Code, which passes `CLAUDE_CODE_SESSION_ID` to stdio MCP
@@ -118,6 +164,8 @@ export function sharedSession(env) {
 }
 export async function startGateway(loaded, opts = {}) {
     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) => console.error(`[adtl-gateway] ${m}`), warn: (m) => console.error(`[adtl-gateway] warning: ${m}`) };
     const clients = [];
@@ -127,7 +175,10 @@ export async function startGateway(loaded, opts = {}) {
         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 = env.ADTL_LEDGER ? { ADTL_LEDGER: env.ADTL_LEDGER } : {};
+        const ledgerEnv = {
+            ...(env.ADTL_LEDGER ? { ADTL_LEDGER: env.ADTL_LEDGER } : {}),
+            ...(env[SIGNING_KEY_ENV] ? { [SIGNING_KEY_ENV]: env[SIGNING_KEY_ENV] } : {}),
+        };
         const icfg = custom
             ? { ...custom, env: { ...ledgerEnv, ...custom.env, ...(shared ? { ADTL_SESSIONS_DIR: shared.dir } : {}) } }
             : {
@@ -176,12 +227,23 @@ export async function startGateway(loaded, opts = {}) {
         log.info(`upstreams: ${[...upstreams.keys()].join(", ")}`);
         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 };