@adtl/gateway 0.3.2 → 0.5.0

package/src/authorizer.ts

@@ -0,0 +1,60 @@
+/**
+ * Authorization: may this caller use this tool, resource or prompt at all?
+ *
+ * Labels and the policy answer "may this call run, given what the session has
+ * seen?". An Authorizer answers the question before it, from who is calling.
+ * The gateway asks it on every tools/call, resources/read and prompts/get,
+ * before the request interceptors run, and the stricter answer wins: a denial
+ * stops the call whatever the policy would say, and an allow still leaves the
+ * call to the policy.
+ *
+ * The caller is the SEP-2624 `context.principal` the gateway passes to the
+ * interceptors. Over stdio that is whoever started the gateway (anonymous
+ * unless configured); authenticated transports can fill it in per request.
+ *
+ * An authorizer that throws denies the call (fails closed). In audit mode
+ * denials are logged and not enforced, like policy decisions.
+ */
+import type { InvocationContext } from "@adtl/interceptors";
+
+export type Principal = NonNullable<InvocationContext["principal"]>;
+
+export interface AuthorizationRequest {
+  principal: Principal;
+  event: "tools/call" | "resources/read" | "prompts/get";
+  /** Upstream server id, as named in the config. */
+  server: string;
+  /** Exactly one of tool, resource or prompt is set, matching `event`. */
+  tool?: string;
+  resource?: string;
+  prompt?: string;
+  /** Tool or prompt arguments, for authorizers that decide on them. */
+  arguments?: Record<string, unknown>;
+}
+
+export type AuthorizationDecision = { allow: true } | { allow: false; reason: string };
+
+export interface Authorizer {
+  /** Shown in audit entries and error messages, e.g. "rbac". */
+  readonly name: string;
+  check(request: AuthorizationRequest): AuthorizationDecision | Promise<AuthorizationDecision>;
+}
+
+/** A denial: which authorizer said no, and why. */
+export interface Denial {
+  by: string;
+  reason: string;
+}
+
+/** Ask `authorizer`, failing closed. Returns the denial, or undefined if allowed. */
+export async function authorize(authorizer: Authorizer, request: AuthorizationRequest): Promise<Denial | undefined> {
+  let d: AuthorizationDecision;
+  try {
+    d = await authorizer.check(request);
+  } catch (err) {
+    return { by: authorizer.name, reason: `${authorizer.name} failed: ${err instanceof Error ? err.message : String(err)}` };
+  }
+  if (d?.allow === true) return undefined;
+  const reason = d && "reason" in d && typeof d.reason === "string" && d.reason ? d.reason : `${authorizer.name} denied the call`;
+  return { by: authorizer.name, reason };
+}

package/src/cli.ts

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

package/src/gateway.ts

@@ -1,6 +1,6 @@
 /**
  * The gateway: one MCP server facing the agent, many MCP clients facing the
- * upstream servers, and an interceptor chain in between.
+ * upstream servers, and the interceptors in between.
  *
  * tools/list  → every upstream's tools, renamed <upstream>__<tool>
  * tools/call  → request interceptors (adtl.policy) → upstream → response
@@ -15,8 +15,14 @@
  * `isError: true` explaining why, so the model can tell the user.
  *
  * An "ask" decision holds the call and asks a human through the approval
- * broker (e.g. a phone notification). Approved calls run; denied, unanswered
- * or undeliverable ones are stopped. Without an approval channel, "ask" blocks.
+ * broker (e.g. a phone notification). Once approved, the gateway checks the
+ * call again with the confirmation in `context.confirmations` (SEP-2624
+ * draft) and runs it only if every validator then allows it. Denied,
+ * unanswered or undeliverable calls are stopped. Without an approval channel,
+ * "ask" blocks.
+ *
+ * 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.
  *
  * In audit mode (the invoker runs every interceptor with `mode: "audit"`)
  * nothing is stopped or changed: calls the policy would stop are forwarded,
@@ -46,12 +52,14 @@ import {
   type Tool,
 } from "@modelcontextprotocol/sdk/types.js";
 import type { InvocationContext } from "@adtl/interceptors";
+import { callBindingHash } from "@adtl/labels";
 import type { ApprovalBroker, ApprovalResult } from "./approvals.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, ChainOutcome, InterceptorInvoker } from "./invoker.js";
+import type { Blocked, PhaseOutcome, InterceptorInvoker } from "./invoker.js";
 
-export const GATEWAY_VERSION = "0.3.2";
+export const GATEWAY_VERSION = "0.5.0";
 
 /** `_meta` key on gateway-generated error results describing why a call was stopped. */
 export const GATEWAY_DECISION_KEY = "adtl/gateway";
@@ -96,6 +104,10 @@ export interface AdtlGatewayOptions {
   logger?: GatewayLogger;
   /** Asks humans about "ask" decisions and sends notices. */
   approvals?: ApprovalBroker;
+  /** Decides whether the caller may use a tool, resource or prompt at all, before the policy. */
+  authorizer?: Authorizer;
+  /** The caller, passed to the authorizer and the interceptors. Default: anonymous. */
+  principal?: Principal;
 }
 
 export interface CallOptions {
@@ -132,7 +144,7 @@ function approvalMessage(b: Blocked, a: ApprovalResult): string {
   }
 }
 
-function infoOf(outcome: ChainOutcome, interceptor: string): Record<string, unknown> {
+function infoOf(outcome: PhaseOutcome, interceptor: string): Record<string, unknown> {
   return outcome.results.find((r) => r.interceptor === interceptor)?.info ?? {};
 }
 
@@ -143,6 +155,8 @@ export class AdtlGateway {
   private readonly audit: AuditSink | undefined;
   private readonly log: GatewayLogger;
   private readonly approvals: ApprovalBroker | undefined;
+  private readonly authorizer: Authorizer | undefined;
+  private readonly principal: Principal;
   private routes = new Map<string, Route>();
   private promptRoutes = new Map<string, PromptRoute>();
   /** Resource URI → the upstreams that list it. */
@@ -156,6 +170,13 @@ export class AdtlGateway {
     this.audit = opts.audit;
     this.log = opts.logger ?? stderrLogger;
     this.approvals = opts.approvals;
+    this.authorizer = opts.authorizer;
+    this.principal = opts.principal ?? { type: "anonymous" };
+  }
+
+  /** Ask the authorizer, if any. Returns the denial; in audit mode the caller logs it and carries on. */
+  private async authorize(request: Omit<AuthorizationRequest, "principal">): Promise<Denial | undefined> {
+    return this.authorizer ? authorize(this.authorizer, { principal: this.principal, ...request }) : undefined;
   }
 
   /** The downstream MCP server the agent connects to. */
@@ -331,8 +352,8 @@ export class AdtlGateway {
   }
 
   /**
-   * Forward a resources/read or prompts/get request through the interceptor
-   * chain: request interceptors → upstream → response interceptors (adtl.label).
+   * Forward a resources/read or prompts/get request through the interceptors:
+   * request interceptors → upstream → response interceptors (adtl.label).
    * These requests have no tool result to carry an error, so a stopped request
    * becomes a JSON-RPC error.
    */
@@ -347,10 +368,12 @@ export class AdtlGateway {
     const context: InvocationContext = {
       sessionId: this.sessionId,
       timestamp: new Date().toISOString(),
-      principal: { type: "anonymous" },
+      principal: this.principal,
+      target: upstream,
     };
     const config = { server: upstream };
     const audit = this.invoker.modeOverride === "audit" ? { mode: "audit" as const } : {};
+    let denied: Denial | undefined;
     const finish = (entry: Pick<AuditEntry, "outcome"> & Partial<AuditEntry>) =>
       this.audit?.write({
         ts: context.timestamp!,
@@ -358,11 +381,25 @@ export class AdtlGateway {
         event,
         server: upstream,
         ...target,
+        ...(denied ? { denied } : {}),
         ...entry,
         durationMs: Math.round(performance.now() - started),
       });
     const what = "resource" in target ? `resource ${target.resource}` : `prompt ${upstream}${TOOL_SEPARATOR}${target.prompt}`;
 
+    denied = await this.authorize({
+      event,
+      server: upstream,
+      ...target,
+      ...(params.arguments ? { arguments: params.arguments as Record<string, unknown> } : {}),
+    });
+    if (denied && !("mode" in audit)) {
+      finish({ outcome: "blocked", decision: "block", reason: denied.reason });
+      this.log.info(`denied ${what}: ${denied.reason}`);
+      throw new McpError(ErrorCode.InvalidRequest, `ADTL blocked this request: ${denied.reason}`);
+    }
+    if (denied) this.log.info(`audit: would deny ${what}: ${denied.reason}`);
+
     const req = await this.invoker.runRequest({ event, payload: { method: event, params }, config, context });
     if (req.blocked) {
       finish({ outcome: "blocked", decision: req.blocked.decision, reason: req.blocked.reason, warnings: req.warnings });
@@ -388,7 +425,8 @@ export class AdtlGateway {
       throw new McpError(ErrorCode.InternalError, `ADTL could not label this content, so it was withheld: ${res.blocked.reason}`);
     }
     const label = infoOf(res, "adtl.label");
-    finish({ outcome: "forwarded", ...audit, label: label.label, sessionLabel: label.sessionLabel, warnings });
+    finish({ outcome: "forwarded", ...audit, label: label.label, ...(label.ledger ? { ledger: label.ledger } : {}),
+      ...(label.records ? { records: label.records } : {}), sessionLabel: label.sessionLabel, warnings });
     return (res.payload as { result: R }).result;
   }
 
@@ -405,33 +443,52 @@ export class AdtlGateway {
     const context: InvocationContext = {
       sessionId: this.sessionId,
       timestamp: new Date().toISOString(),
-      principal: { type: "anonymous" },
+      principal: this.principal,
+      target: route.upstream,
     };
     const config: Record<string, unknown> = {
       server: route.upstream,
       ...(route.annotations ? { toolAnnotations: route.annotations } : {}),
     };
     const base = { sessionId: this.sessionId, event: "tools/call" as const, server: route.upstream, tool: route.tool };
+    let denied: Denial | undefined;
     const finish = (entry: Omit<AuditEntry, keyof typeof base | "ts" | "durationMs">) =>
-      this.audit?.write({ ts: context.timestamp!, ...base, ...entry, durationMs: Math.round(performance.now() - started) });
+      this.audit?.write({ ts: context.timestamp!, ...base, ...(denied ? { denied } : {}), ...entry, 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 });
+    if (denied && this.invoker.modeOverride !== "audit") {
+      finish({ outcome: "blocked", decision: "block", reason: denied.reason });
+      this.log.info(`denied ${name}: ${denied.reason}`);
+      this.approvals?.blocked({ sessionId: this.sessionId, server: route.upstream, tool: route.tool, reason: denied.reason, matched: [`authorizer:${denied.by}`] });
+      return textError(`ADTL blocked this call: ${denied.reason}. You are not allowed to use this tool, so the call was not run.`, {
+        decision: "block",
+        reason: denied.reason,
+        authorizer: denied.by,
+      });
+    }
+    if (denied) this.log.info(`audit: would deny ${name}: ${denied.reason}`);
 
     // 1. Request phase: adtl.policy decides whether the call may run.
     const requestPayload = { method: "tools/call", params: { name: route.tool, arguments: args } };
-    const req = await this.invoker.runRequest({ event: "tools/call", payload: requestPayload, config, context });
+    let req = await this.invoker.runRequest({ event: "tools/call", payload: requestPayload, config, context });
     const policy = infoOf(req, "adtl.policy");
     let approval: ApprovalResult | undefined;
     if (req.blocked) {
       const b = req.blocked;
+      // What the agent sees; the confirmation token stays inside the gateway.
+      const shown = { interceptor: b.interceptor, decision: b.decision, reason: b.reason };
       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[]) : [];
-      if (b.decision === "ask" && this.approvals?.canApprove && typeof policy.callHash === "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})`);
         approval = await this.waitForApproval(opts, () =>
           this.approvals!.request({
             sessionId: this.sessionId,
             server: route.upstream,
             tool: route.tool,
-            callHash: policy.callHash as string,
+            callHash: hash,
             reason: b.reason,
             matched,
             ...(policy.sessionLabel !== undefined ? { sessionLabel: policy.sessionLabel } : {}),
@@ -440,13 +497,33 @@ export class AdtlGateway {
         this.log.info(`ask ${name}: ${approval.outcome}`);
         if (approval.outcome !== "approved") {
           finish({ outcome: "blocked", ...stopped, approval, warnings: req.warnings });
-          return textError(approvalMessage(b, approval), { ...b, callHash: policy.callHash, approval });
+          return textError(approvalMessage(b, approval), { ...shown, callHash: policy.callHash, approval });
+        }
+        if (b.confirmation) {
+          // Check the call again with the confirmation; it runs only if every validator now allows it.
+          const c = b.confirmation;
+          const confirmations = [{
+            interceptor: b.interceptor,
+            id: c.id,
+            callHash: c.callHash,
+            ...(c.token !== undefined ? { token: c.token } : {}),
+            decidedAt: new Date().toISOString(),
+            ...(approval.approver ? { principal: { type: "user" as const, id: approval.approver } } : {}),
+          }];
+          req = await this.invoker.runRequest({ event: "tools/call", payload: requestPayload, config, context: { ...context, confirmations } });
+          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) {
+            finish({ outcome: "blocked", ...stopped, approval, reason: recheck, warnings: req.warnings });
+            this.log.info(`ask ${name}: approved but blocked on recheck (${recheck})`);
+            return textError(`ADTL blocked this call after it was approved: ${recheck}. The call was not run.`, { ...shown, callHash: policy.callHash, approval, reason: recheck });
+          }
         }
       } else {
         finish({ outcome: "blocked", ...stopped, warnings: req.warnings });
         this.log.info(`${b.decision} ${name}: ${b.reason}`);
         this.approvals?.blocked({ sessionId: this.sessionId, server: route.upstream, tool: route.tool, reason: b.reason, matched });
-        return textError(blockedMessage(b), { ...b, callHash: policy.callHash });
+        return textError(blockedMessage(b), { ...shown, callHash: policy.callHash });
       }
     }
     const forwarded = (req.payload as typeof requestPayload).params;
@@ -493,6 +570,8 @@ export class AdtlGateway {
       ...(audit ? { mode: "audit" as const } : {}),
       callHash: policy.callHash,
       label: label.label,
+      ...(label.ledger ? { ledger: label.ledger } : {}),
+      ...(label.records ? { records: label.records } : {}),
       sessionLabel: label.sessionLabel,
       warnings: [...req.warnings, ...res.warnings],
     });

package/src/hooks/claudeCode.ts

@@ -17,9 +17,14 @@
  * by Claude Code's session id, which the gateway reads from
  * `CLAUDE_CODE_SESSION_ID`.
  *
+ * With a ledger, PostToolUse also re-labels output that contains content a
+ * tainted session wrote earlier, and, when this session is tainted, records
+ * what the tool was given (file contents, edits, prompts) and the lines a
+ * shell command added to files.
+ *
  * Errors fail closed: a PreToolUse hook that can't decide denies the call.
  */
-import { isAbsolute, relative, resolve, sep } from "node:path";
+import { basename, isAbsolute, relative, resolve, sep } from "node:path";
 import {
   callHash,
   evaluatePolicy,
@@ -29,7 +34,9 @@ import {
   type Decision,
   type PolicyDecision,
   type SessionStore,
+  join,
 } from "@adtl/labels";
+import { chunkHashes, valueHashes, type Ledger } from "@adtl/ledger";
 import type { AuditEntry, AuditSink } from "../audit.js";
 import { CLAUDE_CODE_PRESET, CLAUDE_CODE_SERVER } from "./preset.js";
 
@@ -52,8 +59,10 @@ export interface HookOptions {
   /** `audit`: decide and log, but never deny or ask. */
   mode?: "active" | "audit";
   audit?: AuditSink;
-  /** Files the agent must not change: the ADTL config and the session directory. */
-  protect?: { configPath?: string; sessionsDir?: string };
+  /** 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 };
 }
 
 /** What the hook process prints and exits with. */
@@ -115,6 +124,14 @@ function protectedTarget(input: HookInput, route: { server: string; tool: string
     if (protect.sessionsDir && inside(abs, resolve(protect.sessionsDir))) {
       return { decision: "block", reason: "The agent may not change ADTL session labels" };
     }
+    // Prefix match also covers SQLite's -wal and -shm files.
+    if (protect.ledgerPath && abs.startsWith(resolve(protect.ledgerPath))) {
+      return { decision: "block", reason: "The agent may not change the ADTL ledger" };
+    }
+    // Prefix match also covers the .lock file.
+    if (protect.auditPath && abs.startsWith(resolve(protect.auditPath))) {
+      return { decision: "block", reason: "The agent may not change the ADTL audit log" };
+    }
   }
   const command = typeof args.command === "string" ? args.command : undefined;
   if (command !== undefined && ["Bash", "Monitor"].includes(route.tool)) {
@@ -122,10 +139,30 @@ function protectedTarget(input: HookInput, route: { server: string; tool: string
     if (marks.some((m) => command.includes(m))) {
       return { decision: "ask", reason: "This command touches ADTL session labels" };
     }
+    const ledgerMarks = ["ledger.db", "ledger declassify", protect.ledgerPath].filter((m): m is string => !!m);
+    if (ledgerMarks.some((m) => command.includes(m))) {
+      return { decision: "ask", reason: "This command touches the ADTL ledger" };
+    }
+    if (protect.auditPath && command.includes(basename(protect.auditPath))) {
+      return { decision: "ask", reason: "This command touches the ADTL audit log" };
+    }
   }
   return undefined;
 }
 
+/** Text a shell command added to files, from Claude Code's `bashEditDiff` (one string per file). */
+export function addedLines(output: unknown): string[] {
+  const files = isRecord(output) && isRecord(output.bashEditDiff) && Array.isArray(output.bashEditDiff.files) ? output.bashEditDiff.files : [];
+  const out: string[] = [];
+  for (const f of files) {
+    const hunks = isRecord(f) && Array.isArray(f.hunks) ? f.hunks : [];
+    const lines = hunks.flatMap((h) => (isRecord(h) && Array.isArray(h.lines) ? h.lines : []));
+    const added = lines.filter((l): l is string => typeof l === "string" && l.startsWith("+")).map((l) => l.slice(1));
+    if (added.length) out.push(added.join("\n"));
+  }
+  return out;
+}
+
 export function handleHook(input: HookInput, opts: HookOptions): HookOutcome {
   const event = input.hook_event_name;
   if (event !== "PreToolUse" && event !== "PostToolUse" && event !== "PostToolUseFailure") return NOTHING;
@@ -139,9 +176,22 @@ export function handleHook(input: HookInput, opts: HookOptions): HookOutcome {
   const base = { ts, sessionId: input.session_id, event: "tools/call" as const, ...route, via: "claude-code-hook" as const };
 
   if (event !== "PreToolUse") {
-    const label = labelResult({ ...route, result: input.tool_response ?? input.error ?? null }, config);
+    const output = input.tool_response ?? input.error ?? null;
+    let label = labelResult({ ...route, result: output }, config);
+    let ledger: { chunks: number; writers: string[] } | undefined;
+    if (opts.ledger) {
+      const match = opts.ledger.lookup(valueHashes(output));
+      if (match) {
+        label = join(label, match.label);
+        ledger = { chunks: match.chunks, writers: match.writers };
+      }
+      // What the tool was given came from the session as it was before this output.
+      const before = opts.sessions.get(input.session_id);
+      const written = [...valueHashes(input.tool_input ?? {}), ...addedLines(output).flatMap(chunkHashes)];
+      opts.ledger.record(written, before, input.session_id, route);
+    }
     const sessionLabel = opts.sessions.observe(input.session_id, label);
-    opts.audit?.write({ ...base, outcome: "forwarded", label, sessionLabel, durationMs: 0 });
+    opts.audit?.write({ ...base, outcome: "forwarded", label, ...(ledger ? { ledger } : {}), sessionLabel, durationMs: 0 });
     return NOTHING;
   }
 

package/src/hooks/run.ts

@@ -9,6 +9,7 @@
 import { readFile } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
 import { FileSessionStore, defaultSessionsDir } from "@adtl/labels";
+import { Ledger, defaultLedgerPath } from "@adtl/ledger";
 import { parseConfigText } from "@adtl/interceptors";
 import { parse as parseYaml } from "yaml";
 import { JsonlAuditLog } from "../audit.js";
@@ -34,14 +35,19 @@ export async function runHook(opts: RunHookOptions): Promise<HookOutcome> {
     const text = await readFile(path, "utf8");
     const config = parseConfigText(text, path);
     const gw = ((parseYaml(text) ?? {}) as { gateway?: { audit?: unknown; mode?: unknown } }).gateway ?? {};
-    const sessionsDir = defaultSessionsDir(opts.env ?? process.env);
+    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 auditPath = typeof gw.audit === "string" ? resolve(dirname(path), gw.audit) : undefined;
     return handleHook(input, {
       config,
       sessions: new FileSessionStore(sessionsDir),
+      ...(ledger ? { ledger } : {}),
       ...(opts.gatewayServer ? { gatewayServer: opts.gatewayServer } : {}),
       mode: gw.mode === "audit" ? "audit" : "active",
-      ...(typeof gw.audit === "string" ? { audit: new JsonlAuditLog(resolve(dirname(path), gw.audit)) } : {}),
-      protect: { configPath: path, sessionsDir },
+      ...(auditPath ? { audit: new JsonlAuditLog(auditPath) } : {}),
+      protect: { configPath: path, sessionsDir, ledgerPath, ...(auditPath ? { auditPath } : {}) },
     });
   } catch (err) {
     return failure(input.hook_event_name, (err as Error).message);

package/src/index.ts

@@ -1,6 +1,7 @@
 export * from "./config.js";
 export * from "./invoker.js";
 export * from "./audit.js";
+export * from "./authorizer.js";
 export * from "./approvals.js";
 export * from "./ntfy.js";
 export * from "./email.js";
@@ -8,3 +9,5 @@ export * from "./gateway.js";
 export * from "./startup.js";
 export * from "./init/index.js";
 export * from "./hooks/index.js";
+export * from "./ledgerCli.js";
+export * from "./auditCli.js";

package/src/invoker.ts

@@ -6,7 +6,8 @@
  * - Receiving (response phase, upstream → gateway): Validate (parallel) →
  *   Mutate (sequential).
  *
- * Only `severity: "error"` blocks. Audit-mode interceptors never block, and
+ * Only `severity: "error"` blocks. A blocking result with a `confirmation`
+ * request is an "ask"; the gateway may ask a human and re-validate. Audit-mode interceptors never block, and
  * their mutations are not applied. An interceptor that fails (error or
  * timeout) blocks the message unless it declares `failOpen: true`.
  *
@@ -18,6 +19,7 @@ import {
   DECISION_INFO_KEY,
   INVOKE_METHOD,
   LIST_METHOD,
+  type ConfirmationRequest,
   type InterceptorDefinition,
   type InterceptorResult,
   type InvocationContext,
@@ -49,9 +51,11 @@ export interface Blocked {
   interceptor: string;
   decision: Decision;
   reason: string;
+  /** Set when the validator would accept a human confirmation. */
+  confirmation?: ConfirmationRequest;
 }
 
-export interface ChainOutcome {
+export interface PhaseOutcome {
   payload: unknown;
   blocked?: Blocked;
   results: InterceptorResult[];
@@ -96,15 +100,15 @@ export class InterceptorInvoker {
     return this.interceptors.map((i) => i.definition);
   }
 
-  async runRequest(opts: InvokeOptions): Promise<ChainOutcome> {
-    const out: ChainOutcome = { payload: opts.payload, results: [], warnings: [] };
+  async runRequest(opts: InvokeOptions): Promise<PhaseOutcome> {
+    const out: PhaseOutcome = { payload: opts.payload, results: [], warnings: [] };
     if (!(await this.mutate("request", opts, out))) return out;
     await this.validate("request", opts, out);
     return out;
   }
 
-  async runResponse(opts: InvokeOptions): Promise<ChainOutcome> {
-    const out: ChainOutcome = { payload: opts.payload, results: [], warnings: [] };
+  async runResponse(opts: InvokeOptions): Promise<PhaseOutcome> {
+    const out: PhaseOutcome = { payload: opts.payload, results: [], warnings: [] };
     if (!(await this.validate("response", opts, out))) return out;
     await this.mutate("response", opts, out);
     return out;
@@ -128,8 +132,8 @@ export class InterceptorInvoker {
     return res as unknown as InterceptorResult;
   }
 
-  /** Handle an interceptor failure. Returns false if the chain must stop. */
-  private failed(i: BoundInterceptor, err: unknown, out: ChainOutcome): boolean {
+  /** Handle an interceptor failure. Returns false if the phase must stop. */
+  private failed(i: BoundInterceptor, err: unknown, out: PhaseOutcome): boolean {
     const msg = `${i.definition.name} failed: ${err instanceof Error ? err.message : String(err)}`;
     if (this.isAudit(i) || i.definition.failOpen === true) {
       out.warnings.push(msg);
@@ -140,12 +144,12 @@ export class InterceptorInvoker {
   }
 
   /** Sequential mutations, atomic: on failure the original payload is kept. */
-  private async mutate(phase: Phase, opts: InvokeOptions, out: ChainOutcome): Promise<boolean> {
-    const chain = this.select("mutation", opts.event, phase).sort(
+  private async mutate(phase: Phase, opts: InvokeOptions, out: PhaseOutcome): Promise<boolean> {
+    const selected = this.select("mutation", opts.event, phase).sort(
       (a, b) => priority(a.definition, phase) - priority(b.definition, phase) || a.definition.name.localeCompare(b.definition.name),
     );
     let payload = out.payload;
-    for (const i of chain) {
+    for (const i of selected) {
       let r: MutationResult;
       try {
         r = (await this.invoke(i, phase, opts, payload)) as MutationResult;
@@ -161,12 +165,12 @@ export class InterceptorInvoker {
   }
 
   /** Parallel validations. Only severity "error" blocks. */
-  private async validate(phase: Phase, opts: InvokeOptions, out: ChainOutcome): Promise<boolean> {
-    const chain = this.select("validation", opts.event, phase);
-    const settled = await Promise.allSettled(chain.map((i) => this.invoke(i, phase, opts, out.payload)));
+  private async validate(phase: Phase, opts: InvokeOptions, out: PhaseOutcome): Promise<boolean> {
+    const selected = this.select("validation", opts.event, phase);
+    const settled = await Promise.allSettled(selected.map((i) => this.invoke(i, phase, opts, out.payload)));
     let ok = true;
     settled.forEach((s, idx) => {
-      const i = chain[idx]!;
+      const i = selected[idx]!;
       if (s.status === "rejected") {
         if (!this.failed(i, s.reason, out)) ok = false;
         return;
@@ -176,9 +180,12 @@ export class InterceptorInvoker {
       if (r.valid || r.severity !== "error" || this.isAudit(i)) return;
       // Keep the strictest rejection, so an "ask" never hides another validator's "block".
       if (!out.blocked || out.blocked.decision === "ask") {
-        const decision = (r.info?.[DECISION_INFO_KEY] as Decision | undefined) ?? "block";
+        // Older ADTL interceptor servers carry "ask" only in info.
+        const decision = r.confirmation ? "ask" : ((r.info?.[DECISION_INFO_KEY] as Decision | undefined) ?? "block");
         const reason = r.messages?.map((m) => m.message).join("; ") || `${i.definition.name} rejected the call`;
-        if (!out.blocked || decision === "block") out.blocked = { interceptor: i.definition.name, decision, reason };
+        if (!out.blocked || decision === "block") {
+          out.blocked = { interceptor: i.definition.name, decision, reason, ...(r.confirmation ? { confirmation: r.confirmation } : {}) };
+        }
       }
       ok = false;
     });