@adtl/gateway 0.4.0 → 0.5.0

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.4.0";
+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, ...(label.ledger ? { ledger: label.ledger } : {}), 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;
@@ -494,6 +571,7 @@ export class AdtlGateway {
       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

@@ -24,7 +24,7 @@
  *
  * 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,
@@ -62,7 +62,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 };
+  protect?: { configPath?: string; sessionsDir?: string; ledgerPath?: string; auditPath?: string };
 }
 
 /** What the hook process prints and exits with. */
@@ -128,6 +128,10 @@ function protectedTarget(input: HookInput, route: { server: string; tool: string
     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)) {
@@ -139,6 +143,9 @@ function protectedTarget(input: HookInput, route: { server: string; tool: string
     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;
 }

package/src/hooks/run.ts

@@ -39,14 +39,15 @@ export async function runHook(opts: RunHookOptions): Promise<HookOutcome> {
     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, ledgerPath },
+      ...(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";
@@ -9,3 +10,4 @@ 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;
     });

package/src/ledgerCli.ts

@@ -3,11 +3,14 @@
  *
  *   adtl-gateway ledger stats                 [-c adtl.yaml]
  *   adtl-gateway ledger verify                [-c adtl.yaml]
- *   adtl-gateway ledger declassify <file>...  [-c adtl.yaml] [--reason <text>]
+ *   adtl-gateway ledger declassify <file>...  [-c adtl.yaml] --reason <text>
+ *   adtl-gateway ledger declassified          [-c adtl.yaml] [--limit <n>]
  *
  * `declassify` clears the label of each file's current content, after you've
  * checked it. It is meant to be run by a person; the Claude Code hook asks
- * before letting the agent run it.
+ * before letting the agent run it. The reason is required: declassifying is
+ * where taint tracking erodes, and the reason is what a later review reads.
+ * `declassified` lists recent declassifications for that review.
  */
 import { readFile } from "node:fs/promises";
 import { userInfo } from "node:os";
@@ -17,7 +20,8 @@ import { Ledger, chunkHashes, defaultLedgerPath } from "@adtl/ledger";
 
 export const LEDGER_USAGE = `Usage: adtl-gateway ledger stats [-c <adtl.yaml>]
        adtl-gateway ledger verify [-c <adtl.yaml>]
-       adtl-gateway ledger declassify <file>... [-c <adtl.yaml>] [--reason <text>]
+       adtl-gateway ledger declassify <file>... [-c <adtl.yaml>] --reason <text>
+       adtl-gateway ledger declassified [-c <adtl.yaml>] [--limit <n>]
 
 The ledger remembers content written by sessions that had read untrusted or
 private data, and re-labels it when it is read back. It lives in
@@ -26,7 +30,9 @@ ledger.path from the config, else ADTL_LEDGER, else ~/.adtl/ledger.db.
   stats       Count entries.
   verify      Check that no entry was changed or removed (exit 1 if one was).
   declassify  Clear the label of each file's current content. Check the
-              files first: after this, ADTL treats that content as clean.`;
+              files first: after this, ADTL treats that content as clean.
+              --reason is required and kept in the ledger.
+  declassified  List recent declassifications: when, who, what and why.`;
 
 export interface LedgerCommandResult {
   stdout: string;
@@ -37,17 +43,21 @@ export async function runLedgerCommand(argv: string[], env: NodeJS.ProcessEnv =
   const [cmd, ...rest] = argv;
   let config: string | undefined;
   let reason: string | undefined;
+  let limit: number | undefined;
   const files: string[] = [];
   for (let i = 0; i < rest.length; i++) {
     const a = rest[i]!;
     if (a === "-c" || a === "--config") config = rest[++i];
     else if (a === "--reason") reason = rest[++i];
+    else if (a === "--limit") limit = Number(rest[++i]);
     else if (a.startsWith("-")) throw new Error(`Unknown argument: ${a}\n\n${LEDGER_USAGE}`);
     else files.push(a);
   }
   if (cmd === undefined || cmd === "-h" || cmd === "--help") return { stdout: LEDGER_USAGE, exitCode: 0 };
-  if (!["stats", "verify", "declassify"].includes(cmd)) throw new Error(`Unknown ledger command: ${cmd}\n\n${LEDGER_USAGE}`);
+  if (!["stats", "verify", "declassify", "declassified"].includes(cmd)) throw new Error(`Unknown ledger command: ${cmd}\n\n${LEDGER_USAGE}`);
   if (cmd === "declassify" && files.length === 0) throw new Error(`declassify needs at least one file\n\n${LEDGER_USAGE}`);
+  if (cmd === "declassify" && !reason?.trim()) throw new Error(`declassify needs --reason: say why this content is safe\n\n${LEDGER_USAGE}`);
+  if (limit !== undefined && !(Number.isInteger(limit) && limit > 0)) throw new Error(`--limit must be a positive whole number\n\n${LEDGER_USAGE}`);
   if (cmd !== "declassify" && files.length > 0) throw new Error(`Unexpected argument: ${files[0]}\n\n${LEDGER_USAGE}`);
 
   let path = defaultLedgerPath(env);
@@ -70,10 +80,16 @@ export async function runLedgerCommand(argv: string[], env: NodeJS.ProcessEnv =
         ? { stdout: `${path}: ${v.entries} entries, chain intact`, exitCode: 0 }
         : { stdout: `${path}: TAMPERED: ${v.problem}`, exitCode: 1 };
     }
+    if (cmd === "declassified") {
+      const list = ledger.declassifications(limit);
+      if (list.length === 0) return { stdout: `${path}: nothing declassified`, exitCode: 0 };
+      const rows = list.map((d) => `${d.ts}  ${d.by}  ${d.subject ?? "-"}  ${d.chunks} chunk${d.chunks === 1 ? "" : "s"}  ${d.reason ?? "(no reason given)"}`);
+      return { stdout: rows.join("\n"), exitCode: 0 };
+    }
     const by = `user:${userInfo().username}`;
     const lines: string[] = [];
     for (const f of files) {
-      const n = ledger.declassify(chunkHashes(await readFile(resolve(f), "utf8")), by, reason);
+      const n = ledger.declassify(chunkHashes(await readFile(resolve(f), "utf8")), by, reason!.trim(), f);
       lines.push(n ? `${f}: cleared ${n} labeled chunk${n === 1 ? "" : "s"}` : `${f}: nothing labeled`);
     }
     return { stdout: lines.join("\n"), exitCode: 0 };