@adtl/gateway 0.5.1 → 0.6.0

package/src/config.ts

@@ -12,15 +12,21 @@
  *       docs:
  *         url: https://example.com/mcp
  *         headers: { Authorization: "Bearer ${DOCS_TOKEN}" }
+ *     principal: { id: "${USER}" }       # optional: who runs this gateway (default: anonymous)
+ *     roles:                             # optional: who may use which tools (deny by default)
+ *       maintainers: { members: [alice], tools: ["github.*"] }
+ *       readers:     { members: ["*"],   tools: ["github.read_*", "github.get_*"] }
  *     approvals:                         # optional: make "ask" really ask
  *       timeoutSeconds: 50
  *       ntfy: { topic: "${ADTL_NTFY_TOPIC}" }
+ *       approvers:                       # optional: each approver's own channel (policy rule `approvers:`)
+ *         alice: { ntfy: { topic: "${ALICE_NTFY_TOPIC}" } }
  *       email:
  *         smtp: { host: smtp.example.com, port: 465, user: "${SMTP_USER}", pass: "${SMTP_PASS}" }
  *         from: adtl@example.com
  *         to: you@example.com
  *
- * `${VAR}` in command, args, env, cwd, url, headers and approval settings is
+ * `${VAR}` in command, args, env, cwd, url, headers, approval settings and principal.id is
  * replaced from the gateway's environment. A missing variable is a config error,
  * unless a default is given: `${VAR:-default}`.
  */
@@ -88,10 +94,50 @@ export const ApprovalsConfigSchema = z
     timeoutSeconds: z.number().int().positive().max(3600).default(50),
     ntfy: NtfyConfigSchema.optional(),
     email: EmailConfigSchema.optional(),
+    /**
+     * Also ask in the MCP client (elicitation), when it supports it. Off by
+     * default: a client that accepts elicitations by itself would approve calls.
+     */
+    elicitation: z.boolean().default(false),
+    /**
+     * Each approver's own channel, by principal id. Policy rules with
+     * `approvers: [role]` ask only these people, so the answer names who approved.
+     */
+    approvers: z.record(z.object({ ntfy: NtfyConfigSchema }).strict()).optional(),
   })
   .strict();
 export type ApprovalsConfig = z.infer<typeof ApprovalsConfigSchema>;
 
+/** `server.tool` (or `server.prompt`), with `*` wildcards, as in policy rules. */
+const QualifiedPattern = z
+  .string()
+  .min(1)
+  .refine((p) => /^[^.]+\..+$/.test(p), { message: 'Use "server.name" with optional * wildcards, e.g. "github.read_*" or "github.*"' });
+
+export const PrincipalConfigSchema = z
+  .object({
+    type: z.enum(["user", "service"]).default("user"),
+    id: z.string().min(1),
+    claims: z.record(z.unknown()).optional(),
+  })
+  .strict();
+export type PrincipalConfig = z.infer<typeof PrincipalConfigSchema>;
+
+export const RoleSchema = z
+  .object({
+    /** Principal ids; "*" means everyone, including an anonymous caller. */
+    members: z.array(z.string().min(1)).nonempty("A role needs at least one member (\"*\" for everyone)"),
+    tools: z.array(QualifiedPattern).default([]),
+    prompts: z.array(QualifiedPattern).default([]),
+    /** Resource URI patterns, e.g. "github://acme/*". */
+    resources: z.array(z.string().min(1)).default([]),
+  })
+  .strict()
+  .refine((r) => r.tools.length + r.prompts.length + r.resources.length > 0, {
+    message: "A role must grant at least one of tools, prompts or resources",
+  });
+export type RoleConfig = z.infer<typeof RoleSchema>;
+
 export const GatewayConfigSchema = z
   .object({
     upstreams: z
@@ -113,6 +159,13 @@ export const GatewayConfigSchema = z
     approvals: ApprovalsConfigSchema.optional(),
     /** Timeout for each interceptor invocation, in milliseconds. */
     interceptorTimeoutMs: z.number().int().positive().default(5000),
+    /** Who runs this gateway. Passed to the authorizer and the interceptors. Default: anonymous. */
+    principal: PrincipalConfigSchema.optional(),
+    /** Role-based authorization: when present, a call no role grants is denied. */
+    roles: z
+      .record(RoleSchema)
+      .refine((r) => Object.keys(r).length > 0, "roles: needs at least one role (remove it to allow everyone)")
+      .optional(),
   })
   .strict();
 export type GatewayConfig = z.infer<typeof GatewayConfigSchema>;

package/src/elicitation.ts

@@ -0,0 +1,69 @@
+/**
+ * Approvals inside the MCP client, through `elicitation/create`: the person
+ * using the client (for example Claude Code) sees the request and answers
+ * Allow or Deny there, no phone needed.
+ *
+ * The answer is turned into the same signed token a push button would send,
+ * so it answers only the one pending call it was asked about. Declining or
+ * dismissing the prompt counts as Deny. The gateway uses this channel only
+ * when `gateway.approvals.elicitation` is on and the client declares the
+ * elicitation capability, and never for rules with named approvers: the
+ * client can't say who answered.
+ */
+import type { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { ElicitResultSchema } from "@modelcontextprotocol/sdk/types.js";
+import type { AnswerFn, ApprovalEvent, ApprovalRequest, Notifier } from "./approvals.js";
+
+interface Listening {
+  answer: AnswerFn;
+  signal: AbortSignal;
+}
+
+/** True if the connected client can answer elicitation requests. */
+export function supportsElicitation(server: Server): boolean {
+  return server.getClientCapabilities()?.elicitation !== undefined;
+}
+
+function message(request: ApprovalRequest): string {
+  const rule = request.matched.join(", ") || "default";
+  return `ADTL: allow ${request.server}.${request.tool}?\n\n${request.reason}\n\nRule: ${rule}. Allow runs this one call; Deny or no answer stops it.`;
+}
+
+export class ElicitationChannel implements Notifier {
+  readonly name = "elicitation";
+  private readonly listening = new Map<string, Listening>();
+
+  constructor(private readonly server: Server) {}
+
+  async listen(request: ApprovalRequest, answer: AnswerFn, signal: AbortSignal): Promise<void> {
+    this.listening.set(request.id, { answer, signal });
+    await new Promise<void>((resolve) => signal.addEventListener("abort", () => resolve(), { once: true }));
+    this.listening.delete(request.id);
+  }
+
+  async notify(event: ApprovalEvent): Promise<void> {
+    if (event.kind !== "pending") return; // the client sees the call's result; no other notices
+    const l = this.listening.get(event.request.id);
+    if (!l) throw new Error("not listening for this request");
+    // A plain request, not Server.elicitInput(): clients that declare only `elicitation: {}` support forms too.
+    const result = await this.server.request(
+      {
+        method: "elicitation/create",
+        params: {
+          message: message(event.request),
+          requestedSchema: {
+            type: "object",
+            properties: {
+              decision: { type: "string", title: "Decision", enum: ["allow", "deny"], description: "allow runs this one call; deny stops it" },
+            },
+            required: ["decision"],
+          },
+        },
+      },
+      ElicitResultSchema,
+      { signal: l.signal, timeout: Math.max(1, event.request.expiresAt.getTime() - Date.now()) },
+    );
+    const allow = result.action === "accept" && result.content?.decision === "allow";
+    l.answer(allow ? event.tokens.allow : event.tokens.deny);
+  }
+}

package/src/gateway.ts

@@ -23,6 +23,8 @@
  *
  * An optional Authorizer decides first whether the caller may use the tool,
  * resource or prompt at all; a denial stops the call before the policy runs.
+ * The lists the agent sees leave out what the authorizer would deny, so the
+ * agent doesn't try it; hiding is a convenience, and every call is still checked.
  *
  * In audit mode (the invoker runs every interceptor with `mode: "audit"`)
  * nothing is stopped or changed: calls the policy would stop are forwarded,
@@ -54,12 +56,13 @@ import {
 import type { InvocationContext } from "@adtl/interceptors";
 import { callBindingHash } from "@adtl/labels";
 import type { ApprovalBroker, ApprovalResult } from "./approvals.js";
+import { ElicitationChannel, supportsElicitation } from "./elicitation.js";
 import type { AuditEntry, AuditSink } from "./audit.js";
 import { authorize, type AuthorizationRequest, type Authorizer, type Denial, type Principal } from "./authorizer.js";
 import { TOOL_SEPARATOR } from "./config.js";
-import type { Blocked, PhaseOutcome, InterceptorInvoker } from "./invoker.js";
+import type { Blocked, InterceptorInvoker, InterceptorRun, PhaseOutcome } from "./invoker.js";
 
-export const GATEWAY_VERSION = "0.5.1";
+export const GATEWAY_VERSION = "0.6.0";
 
 /** `_meta` key on gateway-generated error results describing why a call was stopped. */
 export const GATEWAY_DECISION_KEY = "adtl/gateway";
@@ -108,6 +111,20 @@ export interface AdtlGatewayOptions {
   authorizer?: Authorizer;
   /** The caller, passed to the authorizer and the interceptors. Default: anonymous. */
   principal?: Principal;
+  /** Members of each role that policy rules name as `approvers:`. */
+  approverRoles?: Map<string, string[]>;
+  /** Also ask for approval in the MCP client, when it supports elicitation. */
+  elicitApprovals?: boolean;
+}
+
+/**
+ * Who may answer an "ask" whose rules name approver roles: someone in one of
+ * the roles of every list. Sorted, for stable notifications and tests.
+ */
+export function eligibleApprovers(lists: string[][], roles: Map<string, string[]>): string[] {
+  const sets = lists.map((list) => new Set(list.flatMap((role) => roles.get(role) ?? [])));
+  const [first, ...rest] = sets;
+  return [...(first ?? [])].filter((id) => id !== "*" && rest.every((s) => s.has(id))).sort();
 }
 
 export interface CallOptions {
@@ -157,6 +174,10 @@ export class AdtlGateway {
   private readonly approvals: ApprovalBroker | undefined;
   private readonly authorizer: Authorizer | undefined;
   private readonly principal: Principal;
+  private readonly approverRoles: Map<string, string[]>;
+  private readonly elicitApprovals: boolean;
+  /** The server the agent is connected to, for elicitation. */
+  private server: Server | undefined;
   private routes = new Map<string, Route>();
   private promptRoutes = new Map<string, PromptRoute>();
   /** Resource URI → the upstreams that list it. */
@@ -172,6 +193,8 @@ export class AdtlGateway {
     this.approvals = opts.approvals;
     this.authorizer = opts.authorizer;
     this.principal = opts.principal ?? { type: "anonymous" };
+    this.approverRoles = opts.approverRoles ?? new Map();
+    this.elicitApprovals = opts.elicitApprovals === true;
   }
 
   /** Ask the authorizer, if any. Returns the denial; in audit mode the caller logs it and carries on. */
@@ -195,7 +218,7 @@ export class AdtlGateway {
           "if a call is stopped, the result explains why.",
       },
     );
-    server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: await this.listTools() }));
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: await this.visibleTools() }));
     server.setRequestHandler(CallToolRequestSchema, async (req, extra) => {
       const progressToken = req.params._meta?.progressToken;
       const progress =
@@ -206,16 +229,17 @@ export class AdtlGateway {
       return this.callTool(req.params.name, req.params.arguments ?? {}, progress ? { progress } : {});
     });
     if (capabilities.resources) {
-      server.setRequestHandler(ListResourcesRequestSchema, async () => ({ resources: await this.listResources() }));
+      server.setRequestHandler(ListResourcesRequestSchema, async () => ({ resources: await this.visibleResources() }));
       server.setRequestHandler(ListResourceTemplatesRequestSchema, async () => ({
         resourceTemplates: await this.listResourceTemplates(),
       }));
       server.setRequestHandler(ReadResourceRequestSchema, async (req) => this.readResource(req.params.uri));
     }
     if (capabilities.prompts) {
-      server.setRequestHandler(ListPromptsRequestSchema, async () => ({ prompts: await this.listPrompts() }));
+      server.setRequestHandler(ListPromptsRequestSchema, async () => ({ prompts: await this.visiblePrompts() }));
       server.setRequestHandler(GetPromptRequestSchema, async (req) => this.getPrompt(req.params.name, req.params.arguments));
     }
+    this.server = server;
     return server;
   }
 
@@ -242,6 +266,49 @@ export class AdtlGateway {
     return out;
   }
 
+  /** tools/list as the caller sees it: without the tools the authorizer would deny. */
+  async visibleTools(): Promise<Tool[]> {
+    const tools = await this.listTools();
+    return this.hideDenied(tools, (t) => {
+      const r = this.routes.get(t.name)!;
+      return { event: "tools/call", server: r.upstream, tool: r.tool };
+    });
+  }
+
+  /** prompts/list as the caller sees it. */
+  async visiblePrompts(): Promise<Prompt[]> {
+    const prompts = await this.listPrompts();
+    return this.hideDenied(prompts, (p) => {
+      const r = this.promptRoutes.get(p.name)!;
+      return { event: "prompts/get", server: r.upstream, prompt: r.prompt };
+    });
+  }
+
+  /** resources/list as the caller sees it. A URI several upstreams offer is listed as before (reading it is refused). */
+  async visibleResources(): Promise<Resource[]> {
+    const resources = await this.listResources();
+    return this.hideDenied(resources, (r) => {
+      const ups = this.resourceRoutes.get(r.uri);
+      return ups?.size === 1 ? { event: "resources/read", server: [...ups][0]!, resource: r.uri } : undefined;
+    });
+  }
+
+  /**
+   * Leave out items the authorizer would deny, asked without arguments. Not in
+   * audit mode, which changes nothing. Hiding only saves the agent a denied
+   * call: routes are kept, and a call to a hidden item is still authorized.
+   */
+  private async hideDenied<T>(items: T[], request: (item: T) => Omit<AuthorizationRequest, "principal"> | undefined): Promise<T[]> {
+    if (!this.authorizer || this.invoker.modeOverride === "audit") return items;
+    const shown = await Promise.all(
+      items.map(async (item) => {
+        const r = request(item);
+        return r === undefined || (await this.authorize(r)) === undefined;
+      }),
+    );
+    return items.filter((_, i) => shown[i]);
+  }
+
   async listTools(): Promise<Tool[]> {
     const all = await this.listAll("tools/list", "tools", async (c, cursor) => {
       const p = await c.listTools(cursor ? { cursor } : {});
@@ -374,6 +441,7 @@ export class AdtlGateway {
     const config = { server: upstream };
     const audit = this.invoker.modeOverride === "audit" ? { mode: "audit" as const } : {};
     let denied: Denial | undefined;
+    const ran: InterceptorRun[] = [];
     const finish = (entry: Pick<AuditEntry, "outcome"> & Partial<AuditEntry>) =>
       this.audit?.write({
         ts: context.timestamp!,
@@ -383,6 +451,7 @@ export class AdtlGateway {
         ...target,
         ...(denied ? { denied } : {}),
         ...entry,
+        ...(ran.length ? { interceptors: [...ran] } : {}),
         durationMs: Math.round(performance.now() - started),
       });
     const what = "resource" in target ? `resource ${target.resource}` : `prompt ${upstream}${TOOL_SEPARATOR}${target.prompt}`;
@@ -401,6 +470,7 @@ export class AdtlGateway {
     if (denied) this.log.info(`audit: would deny ${what}: ${denied.reason}`);
 
     const req = await this.invoker.runRequest({ event, payload: { method: event, params }, config, context });
+    ran.push(...req.ran);
     if (req.blocked) {
       finish({ outcome: "blocked", decision: req.blocked.decision, reason: req.blocked.reason, warnings: req.warnings });
       this.log.info(`${req.blocked.decision} ${what}: ${req.blocked.reason}`);
@@ -417,6 +487,7 @@ export class AdtlGateway {
     }
 
     const res = await this.invoker.runResponse({ event, payload: { method: event, params: forwarded, result }, config, context });
+    ran.push(...res.ran);
     const warnings = [...req.warnings, ...res.warnings];
     if (res.blocked) {
       // Fail closed: unlabeled content must not reach the agent.
@@ -452,8 +523,16 @@ export class AdtlGateway {
     };
     const base = { sessionId: this.sessionId, event: "tools/call" as const, server: route.upstream, tool: route.tool };
     let denied: Denial | undefined;
+    const ran: InterceptorRun[] = [];
     const finish = (entry: Omit<AuditEntry, keyof typeof base | "ts" | "durationMs">) =>
-      this.audit?.write({ ts: context.timestamp!, ...base, ...(denied ? { denied } : {}), ...entry, durationMs: Math.round(performance.now() - started) });
+      this.audit?.write({
+        ts: context.timestamp!,
+        ...base,
+        ...(denied ? { denied } : {}),
+        ...entry,
+        ...(ran.length ? { interceptors: [...ran] } : {}),
+        durationMs: Math.round(performance.now() - started),
+      });
 
     // 0. Authorization: may this caller use this tool at all? A denial wins over any policy decision.
     denied = await this.authorize({ event: "tools/call", server: route.upstream, tool: route.tool, arguments: args });
@@ -472,6 +551,7 @@ export class AdtlGateway {
     // 1. Request phase: adtl.policy decides whether the call may run.
     const requestPayload = { method: "tools/call", params: { name: route.tool, arguments: args } };
     let req = await this.invoker.runRequest({ event: "tools/call", payload: requestPayload, config, context });
+    ran.push(...req.ran);
     const policy = infoOf(req, "adtl.policy");
     let approval: ApprovalResult | undefined;
     if (req.blocked) {
@@ -481,8 +561,12 @@ export class AdtlGateway {
       const stopped = { decision: b.decision, reason: b.reason, matched: policy.matched, callHash: policy.callHash, sessionLabel: policy.sessionLabel };
       const matched = Array.isArray(policy.matched) ? (policy.matched as string[]) : [];
       const hash = b.confirmation?.callHash ?? policy.callHash;
-      if (b.decision === "ask" && this.approvals?.canApprove && typeof hash === "string") {
-        this.log.info(`ask ${name}: waiting for approval (${b.reason})`);
+      const lists = Array.isArray(policy.approvers) ? (policy.approvers as string[][]) : undefined;
+      const approvers = lists ? eligibleApprovers(lists, this.approverRoles) : undefined;
+      // The client's own prompt, if enabled and supported; never for named approvers (it can't say who answered).
+      const elicit = this.elicitApprovals && !approvers && this.server && supportsElicitation(this.server) ? [new ElicitationChannel(this.server)] : [];
+      if (b.decision === "ask" && this.approvals && (this.approvals.canApprove || elicit.length > 0) && typeof hash === "string") {
+        this.log.info(`ask ${name}: waiting for approval${approvers ? ` from ${approvers.join(", ") || "nobody"}` : ""} (${b.reason})`);
         approval = await this.waitForApproval(opts, () =>
           this.approvals!.request({
             sessionId: this.sessionId,
@@ -492,7 +576,8 @@ export class AdtlGateway {
             reason: b.reason,
             matched,
             ...(policy.sessionLabel !== undefined ? { sessionLabel: policy.sessionLabel } : {}),
-          }),
+            ...(approvers ? { approvers } : {}),
+          }, elicit),
         );
         this.log.info(`ask ${name}: ${approval.outcome}`);
         if (approval.outcome !== "approved") {
@@ -511,6 +596,7 @@ export class AdtlGateway {
             ...(approval.approver ? { principal: { type: "user" as const, id: approval.approver } } : {}),
           }];
           req = await this.invoker.runRequest({ event: "tools/call", payload: requestPayload, config, context: { ...context, confirmations } });
+          ran.push(...req.ran);
           const sent = callBindingHash({ event: "tools/call", phase: "request", target: route.upstream, payload: req.payload });
           const recheck = req.blocked?.reason ?? (sent !== c.callHash ? "the call changed after it was approved" : undefined);
           if (recheck !== undefined) {
@@ -554,6 +640,7 @@ export class AdtlGateway {
       config,
       context,
     });
+    ran.push(...res.ran);
     if (res.blocked) {
       // Fail closed: an unlabeled result must not reach the agent.
       finish({ outcome: "blocked", decision: res.blocked.decision, reason: res.blocked.reason, callHash: policy.callHash, warnings: [...req.warnings, ...res.warnings] });

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,8 @@ export * from "./init/index.js";
 export * from "./hooks/index.js";
 export * from "./ledgerCli.js";
 export * from "./auditCli.js";
+export * from "./roles.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;
       }