@adtl/gateway 0.3.1 → 0.4.0

package/src/hooks/claudeCode.ts

@@ -17,6 +17,11 @@
  * 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";
@@ -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 };
 }
 
 /** What the hook process prints and exits with. */
@@ -115,6 +124,10 @@ 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" };
+    }
   }
   const command = typeof args.command === "string" ? args.command : undefined;
   if (command !== undefined && ["Bash", "Monitor"].includes(route.tool)) {
@@ -122,10 +135,27 @@ 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" };
+    }
   }
   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 +169,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,18 @@ 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;
     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 },
+      protect: { configPath: path, sessionsDir, ledgerPath },
     });
   } catch (err) {
     return failure(input.hook_event_name, (err as Error).message);

package/src/index.ts

@@ -8,3 +8,4 @@ export * from "./gateway.js";
 export * from "./startup.js";
 export * from "./init/index.js";
 export * from "./hooks/index.js";
+export * from "./ledgerCli.js";

package/src/init/fromMcpJson.ts

@@ -0,0 +1,165 @@
+/**
+ * `adtl-gateway init --from .mcp.json`: import an MCP client's server list
+ * (Claude Code's .mcp.json, or any file with `mcpServers`, such as Claude
+ * Desktop's config) into `gateway.upstreams`, and point the client at the
+ * gateway instead.
+ *
+ * - stdio servers keep their command, args and env; HTTP servers their url
+ *   and headers. `${VAR}` and `${VAR:-default}` work the same in adtl.yaml.
+ * - SSE servers are left in the client config: the gateway speaks Streamable HTTP only.
+ * - An entry that already runs the gateway is recognized and kept.
+ * - Upstreams already in adtl.yaml are never changed.
+ *
+ * The new client config has the imported servers replaced by one entry that
+ * runs the gateway; everything else in the file is kept.
+ */
+import { dirname, relative, resolve } from "node:path";
+import { isMap, type Document } from "yaml";
+import type { Upstream } from "../config.js";
+import { GATEWAY_VERSION } from "../gateway.js";
+
+export const DEFAULT_GATEWAY_NAME = "adtl";
+
+export interface McpImport {
+  /** Servers moved into gateway.upstreams: name in the client config → upstream id. */
+  imported: { name: string; id: string }[];
+  /** Servers already in adtl.yaml under the same id; left as they are. */
+  kept: { name: string; id: string }[];
+  /** Servers left in the client config, with why. */
+  skipped: { name: string; reason: string }[];
+  /** The client config as it should be once the gateway replaces the imported servers. */
+  text: string;
+  changed: boolean;
+}
+
+type Entry = Record<string, unknown>;
+
+function isRecord(v: unknown): v is Entry {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+function strings(v: unknown): string[] | undefined {
+  return Array.isArray(v) && v.every((x) => typeof x === "string") ? (v as string[]) : undefined;
+}
+
+function stringRecord(v: unknown): Record<string, string> | undefined {
+  if (!isRecord(v)) return undefined;
+  return Object.values(v).every((x) => typeof x === "string") ? (v as Record<string, string>) : undefined;
+}
+
+/** True if this client entry already runs adtl-gateway. */
+export function isGatewayEntry(entry: Entry): boolean {
+  const words = [entry.command, ...(strings(entry.args) ?? [])].filter((w): w is string => typeof w === "string");
+  return words.some((w) => /(^|[/\\@])adtl-gateway$|@adtl\/gateway(@[^/\s]*)?$|packages[/\\]gateway[/\\]dist[/\\]cli\.js$/.test(w));
+}
+
+/** A valid upstream id (letters, digits, '-') for a client server name, unique among `taken`. */
+export function upstreamId(name: string, taken: Set<string>): string {
+  const base = name.replace(/[^A-Za-z0-9-]+/g, "-").replace(/^-+|-+$/g, "") || "server";
+  let id = base;
+  for (let n = 2; taken.has(id); n++) id = `${base}-${n}`;
+  taken.add(id);
+  return id;
+}
+
+/** The upstream for one client entry, or why it can't be one. */
+export function toUpstream(entry: Entry, mcpDir: string, configDir: string): Upstream | { skip: string } {
+  const type = typeof entry.type === "string" ? entry.type : undefined;
+  if (type === "sse") return { skip: "the gateway doesn't support SSE servers; it speaks Streamable HTTP" };
+  if (type === "http" || (type === undefined && typeof entry.url === "string")) {
+    if (typeof entry.url !== "string") return { skip: "HTTP server without a url" };
+    const headers = stringRecord(entry.headers);
+    return { url: entry.url, headers: headers ?? {} };
+  }
+  if (type !== undefined && type !== "stdio") return { skip: `unknown server type "${type}"` };
+  if (typeof entry.command !== "string" || entry.command === "") return { skip: "no command or url" };
+  // Clients start stdio servers in the project directory; the gateway resolves cwd against adtl.yaml's.
+  const cwd = relative(configDir, mcpDir);
+  const args = strings(entry.args) ?? [];
+  const env = stringRecord(entry.env) ?? {};
+  return {
+    command: entry.command,
+    args,
+    env,
+    ...(cwd !== "" ? { cwd } : {}),
+  };
+}
+
+/** What runs the gateway from the client config, with adtl.yaml given relative to the client config's directory. */
+export function gatewayEntry(configPath: string, mcpDir: string): Entry {
+  return { command: "npx", args: ["-y", `@adtl/gateway@${GATEWAY_VERSION}`, "--config", relative(mcpDir, configPath) || configPath] };
+}
+
+/**
+ * Add the client's servers to `doc` (adtl.yaml) under gateway.upstreams, and
+ * return the client config rewritten to use the gateway.
+ */
+export function importMcpServers(
+  mcpText: string,
+  mcpPath: string,
+  doc: Document,
+  configPath: string,
+  gatewayName = DEFAULT_GATEWAY_NAME,
+): McpImport {
+  let json: unknown;
+  try {
+    json = JSON.parse(mcpText);
+  } catch (err) {
+    throw new Error(`${mcpPath}: not valid JSON: ${(err as Error).message}`);
+  }
+  if (!isRecord(json) || !isRecord(json.mcpServers)) throw new Error(`${mcpPath}: no "mcpServers" object`);
+
+  const mcpDir = dirname(resolve(mcpPath));
+  const configDir = dirname(resolve(configPath));
+  const existing = doc.getIn(["gateway", "upstreams"]);
+  const taken = new Set<string>(isMap(existing) ? existing.items.map((p) => String((p.key as { value?: unknown })?.value ?? p.key)) : []);
+  const alreadyThere = new Set(taken);
+
+  const result: McpImport = { imported: [], kept: [], skipped: [], text: mcpText, changed: false };
+  const servers: Record<string, unknown> = {};
+  let gatewayKey: string | undefined;
+
+  for (const [name, entry] of Object.entries(json.mcpServers)) {
+    if (!isRecord(entry)) {
+      result.skipped.push({ name, reason: "not an object" });
+      servers[name] = entry;
+      continue;
+    }
+    if (isGatewayEntry(entry)) {
+      gatewayKey ??= name;
+      servers[name] = entry;
+      continue;
+    }
+    const upstream = toUpstream(entry, mcpDir, configDir);
+    if ("skip" in upstream) {
+      result.skipped.push({ name, reason: upstream.skip });
+      servers[name] = entry;
+      continue;
+    }
+    const plain = name.replace(/[^A-Za-z0-9-]+/g, "-").replace(/^-+|-+$/g, "");
+    if (alreadyThere.has(plain)) {
+      result.kept.push({ name, id: plain });
+      continue;
+    }
+    const id = upstreamId(name, taken);
+    // Leave out empty fields; the gateway fills them in.
+    const written = Object.fromEntries(
+      Object.entries(upstream).filter(([, v]) => !(Array.isArray(v) ? v.length === 0 : isRecord(v) && Object.keys(v).length === 0)),
+    );
+    doc.setIn(["gateway", "upstreams", id], doc.createNode(written));
+    result.imported.push({ name, id });
+  }
+  // Block style, so long paths and secrets references stay readable (a new config starts with `upstreams: {}`).
+  const upstreams = doc.getIn(["gateway", "upstreams"]);
+  if (isMap(upstreams) && result.imported.length) upstreams.flow = false;
+
+  if (result.imported.length === 0 && result.kept.length === 0) return result;
+  if (gatewayKey === undefined) {
+    let key = gatewayName;
+    for (let n = 2; key in servers; n++) key = `${gatewayName}-${n}`;
+    servers[key] = gatewayEntry(resolve(configPath), mcpDir);
+  }
+  result.text = `${JSON.stringify({ ...json, mcpServers: servers }, null, 2)}\n`;
+  result.changed = result.text !== mcpText;
+  return result;
+}

package/src/init/index.ts

@@ -1,3 +1,5 @@
 export { PRESETS, choosePreset, type Preset } from "./presets.js";
 export { mergeIntoDocument, ruleFromHints, suggest, type MergeReport, type ServerScan, type ServerSuggestion, type ToolSuggestion } from "./suggest.js";
 export { runInit, type InitOptions, type InitResult } from "./run.js";
+export { DEFAULT_GATEWAY_NAME, gatewayEntry, importMcpServers, isGatewayEntry, toUpstream, upstreamId, type McpImport } from "./fromMcpJson.js";
+export { NEW_CONFIG } from "./run.js";

package/src/init/run.ts

@@ -2,31 +2,79 @@
  * `adtl-gateway init`: connect to every upstream in adtl.yaml, list its
  * tools, and draft a labeling rule for each tool not configured yet.
  *
+ * With `from` (e.g. `.mcp.json`), the client's MCP servers are first imported
+ * into gateway.upstreams (see fromMcpJson.ts), and adtl.yaml is created if it
+ * doesn't exist yet.
+ *
  * Without `write`, the updated file is only returned (the CLI prints it).
  * With `write`, the original is kept as `<file>.bak` and the file is updated
- * in place. Existing entries and comments are never changed.
+ * in place; with `from`, the client config is rewritten to use the gateway,
+ * also keeping a `.bak`. Existing entries and comments are never changed.
  */
 import { readFile, writeFile } from "node:fs/promises";
-import { dirname } from "node:path";
+import { dirname, resolve } from "node:path";
 import type { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import type { Tool } from "@modelcontextprotocol/sdk/types.js";
 import { parseDocument } from "yaml";
 import { expandUpstream } from "../config.js";
-import { connectUpstream, loadGatewayConfig } from "../startup.js";
+import { GatewayConfigError, connectUpstream, parseGatewayConfigText } from "../startup.js";
+import { importMcpServers, type McpImport } from "./fromMcpJson.js";
 import { mergeIntoDocument, suggest, type MergeReport, type ServerScan } from "./suggest.js";
 
 export interface InitOptions {
   path: string;
   write?: boolean;
   env?: NodeJS.ProcessEnv;
+  /** An MCP client config with `mcpServers` (e.g. Claude Code's .mcp.json) to import upstreams from. */
+  from?: string;
+  /** Name for the gateway's entry in that client config. Default `adtl`. */
+  gatewayName?: string;
 }
 
+/** Don't fold long values (paths, commands) across lines. */
+const YAML_OPTIONS = { lineWidth: 0 } as const;
+
+/** Starting point when `--from` creates adtl.yaml. */
+export const NEW_CONFIG = `# ADTL config, drafted by \`adtl-gateway init --from\`. Review every rule marked "review".
+#
+# For every tool, say what its result is (integrity, confidentiality) and where
+# calling it can send data (egress). Anything left out gets the defaults below.
+
+defaults:
+  integrity: untrusted
+  confidentiality: private
+
+policy:
+  default: allow
+  rules:
+    - name: no-public-write-after-untrusted
+      when:
+        session.integrity: untrusted
+        tool.egress: [public, external, unknown]
+      then: ask
+      reason: Session has read untrusted content; confirm before sending data out
+
+    - name: private-stays-private
+      when:
+        session.confidentiality: [private, secret]
+        tool.egress: public
+      then: block
+      reason: Private data must not reach a public tool
+
+gateway:
+  upstreams: {}
+`;
+
 export interface InitResult {
   /** The updated adtl.yaml. */
   text: string;
   reports: MergeReport[];
   /** Upstreams that could not be scanned; left untouched in the file. */
   failed: { id: string; error: string }[];
+  /** With `from`: what was imported, and the rewritten client config. */
+  mcp?: McpImport & { path: string };
+  /** True if adtl.yaml didn't exist and was drafted from scratch. */
+  created?: boolean;
 }
 
 async function listAllTools(client: Client): Promise<Tool[]> {
@@ -53,10 +101,35 @@ async function scan(id: string, connect: () => Promise<Client>): Promise<ServerS
 
 export async function runInit(opts: InitOptions): Promise<InitResult> {
   const env = opts.env ?? process.env;
-  const loaded = await loadGatewayConfig(opts.path);
-  const baseDir = dirname(loaded.path);
-  const original = await readFile(loaded.path, "utf8");
+  const path = resolve(opts.path);
+  let original: string | undefined;
+  try {
+    original = await readFile(path, "utf8");
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code !== "ENOENT" || !opts.from) {
+      throw new GatewayConfigError(`Cannot read config file ${path}: ${(err as Error).message}`);
+    }
+  }
+  const doc = parseDocument(original ?? NEW_CONFIG);
 
+  let mcp: InitResult["mcp"];
+  if (opts.from) {
+    const mcpPath = resolve(opts.from);
+    let mcpText: string;
+    try {
+      mcpText = await readFile(mcpPath, "utf8");
+    } catch (err) {
+      throw new GatewayConfigError(`Cannot read ${mcpPath}: ${(err as Error).message}`);
+    }
+    try {
+      mcp = { path: mcpPath, ...importMcpServers(mcpText, mcpPath, doc, path, opts.gatewayName) };
+    } catch (err) {
+      throw new GatewayConfigError((err as Error).message);
+    }
+  }
+
+  const loaded = parseGatewayConfigText(doc.toString(YAML_OPTIONS), path);
+  const baseDir = dirname(loaded.path);
   const ids = Object.keys(loaded.gateway.upstreams);
   const settled = await Promise.allSettled(
     ids.map((id) => scan(id, () => connectUpstream(id, expandUpstream(id, loaded.gateway.upstreams[id]!, env), baseDir))),
@@ -68,12 +141,18 @@ export async function runInit(opts: InitOptions): Promise<InitResult> {
     else failed.push({ id: ids[i]!, error: (s.reason as Error).message });
   });
 
-  const doc = parseDocument(original);
   const reports = mergeIntoDocument(doc, scans.map((s) => suggest(s)));
-  const text = doc.toString();
-  if (opts.write && text !== original) {
-    await writeFile(`${loaded.path}.bak`, original, "utf8");
-    await writeFile(loaded.path, text, "utf8");
+  const text = doc.toString(YAML_OPTIONS);
+  if (opts.write) {
+    if (original === undefined) await writeFile(path, text, "utf8");
+    else if (text !== original) {
+      await writeFile(`${path}.bak`, original, "utf8");
+      await writeFile(path, text, "utf8");
+    }
+    if (mcp?.changed) {
+      await writeFile(`${mcp.path}.bak`, await readFile(mcp.path, "utf8"), "utf8");
+      await writeFile(mcp.path, mcp.text, "utf8");
+    }
   }
-  return { text, reports, failed };
+  return { text, reports, failed, ...(mcp ? { mcp } : {}), ...(original === undefined ? { created: true } : {}) };
 }

package/src/ledgerCli.ts

@@ -0,0 +1,83 @@
+/**
+ * `adtl-gateway ledger`: look after the label ledger by hand.
+ *
+ *   adtl-gateway ledger stats                 [-c adtl.yaml]
+ *   adtl-gateway ledger verify                [-c adtl.yaml]
+ *   adtl-gateway ledger declassify <file>...  [-c adtl.yaml] [--reason <text>]
+ *
+ * `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.
+ */
+import { readFile } from "node:fs/promises";
+import { userInfo } from "node:os";
+import { dirname, resolve } from "node:path";
+import { parseConfigText } from "@adtl/interceptors";
+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>]
+
+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
+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.`;
+
+export interface LedgerCommandResult {
+  stdout: string;
+  exitCode: number;
+}
+
+export async function runLedgerCommand(argv: string[], env: NodeJS.ProcessEnv = process.env): Promise<LedgerCommandResult> {
+  const [cmd, ...rest] = argv;
+  let config: string | undefined;
+  let reason: string | 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.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 (cmd === "declassify" && files.length === 0) throw new Error(`declassify needs at least one file\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);
+  let retentionDays: number | undefined;
+  if (config) {
+    const abs = resolve(config);
+    const parsed = parseConfigText(await readFile(abs, "utf8"), abs);
+    if (parsed.ledger.path) path = resolve(dirname(abs), parsed.ledger.path);
+    retentionDays = parsed.ledger.retentionDays;
+  }
+  const ledger = new Ledger(path, retentionDays ? { retentionDays } : {});
+  try {
+    if (cmd === "stats") {
+      const s = ledger.stats();
+      return { stdout: `${path}\n${s.records} records from ${s.writers} sessions, ${s.clears} declassified chunks (${s.entries} entries)`, exitCode: 0 };
+    }
+    if (cmd === "verify") {
+      const v = ledger.verify();
+      return v.ok
+        ? { stdout: `${path}: ${v.entries} entries, chain intact`, exitCode: 0 }
+        : { stdout: `${path}: TAMPERED: ${v.problem}`, exitCode: 1 };
+    }
+    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);
+      lines.push(n ? `${f}: cleared ${n} labeled chunk${n === 1 ? "" : "s"}` : `${f}: nothing labeled`);
+    }
+    return { stdout: lines.join("\n"), exitCode: 0 };
+  } finally {
+    ledger.close();
+  }
+}

package/src/startup.ts

@@ -49,6 +49,12 @@ export async function loadGatewayConfig(path: string): Promise<LoadedConfig> {
   } catch (err) {
     throw new GatewayConfigError(`Cannot read config file ${abs}: ${(err as Error).message}`);
   }
+  return parseGatewayConfigText(text, abs);
+}
+
+/** Validate adtl.yaml text; `path` is where it lives (relative paths in it resolve against its directory). */
+export function parseGatewayConfigText(text: string, path: string): LoadedConfig {
+  const abs = resolve(path);
   let labels: AdtlConfig;
   try {
     labels = parseConfigText(text, abs);
@@ -146,12 +152,14 @@ export async function startGateway(
     // 1. Interceptor server (out of process, per the Interceptors WG).
     const shared = sharedSession(env);
     const custom = loaded.gateway.interceptors && expandUpstream("interceptors", loaded.gateway.interceptors, env);
+    // The interceptor process starts with a minimal environment; pass on where the ledger lives.
+    const ledgerEnv: Record<string, string> = env.ADTL_LEDGER ? { ADTL_LEDGER: env.ADTL_LEDGER } : {};
     const icfg: StdioUpstream = custom
-      ? { ...custom, env: { ...custom.env, ...(shared ? { ADTL_SESSIONS_DIR: shared.dir } : {}) } }
+      ? { ...custom, env: { ...ledgerEnv, ...custom.env, ...(shared ? { ADTL_SESSIONS_DIR: shared.dir } : {}) } }
       : {
           command: process.execPath,
           args: [bundledInterceptorsCli(), "--config", loaded.path, ...(shared ? ["--sessions-dir", shared.dir] : [])],
-          env: {},
+          env: ledgerEnv,
         };
     const interceptors = await connectUpstream("interceptors", icfg, baseDir);
     clients.push(interceptors);