@makerstufferupper/flypi 0.0.0-stage → 0.1.2

package/src/secrets/crypto.ts

@@ -0,0 +1,180 @@
+/**
+ * The vault's crypto and its key seam (docs/secrets.md Phase 5.5).
+ *
+ * AES-256-GCM through `node:crypto` — no native module, so `npm install` still works everywhere flypi
+ * runs. Every row gets a fresh 96-bit nonce and its own auth tag, which is what makes a tampered or
+ * swapped row fail loudly instead of decrypting to garbage. That is the whole reason this file is a choke
+ * point: a seal that silently returns the wrong plaintext would put a wrong secret into a config file, and
+ * nothing downstream could tell.
+ *
+ * The key is behind `KeyProvider` so a macOS Keychain or a pinentry prompt can appear later without
+ * touching the table. The default reads a key file — see `keyfileProvider`.
+ */
+import { createCipheriv, createDecipheriv, createHash, randomBytes } from "node:crypto";
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { parse } from "yaml";
+
+export const KEY_BYTES = 32;
+export const NONCE_BYTES = 12;
+
+/**
+ * A secret kind is a label with consequences: it decides what a list line may show (see `mask`) and what a
+ * value has to be before it is stored (see `validate`).
+ *
+ * One `password` kind covers an api key, a token and a password: they are the same shape to the code — one line
+ * of characters, injected as-is — and which of the three it was was never information the vault could use. A
+ * person reading the list learns it from the name and the notes, and the agent from those and from whether the
+ * config wants `secret_env` or `secret_file`. (They used to be three kinds. Nothing read the difference, and the
+ * dropdown made people choose wrong.) v8 collapses any stored `api_key`/`token` row to `password`.
+ */
+export const SECRET_KINDS = ["password", "ssh_private_key", "ssh_public_key", "yaml", "generic"] as const;
+export type SecretKind = (typeof SECRET_KINDS)[number];
+
+/** One sealed row: the three pieces GCM produces, kept apart because SQLite stores each as its own BLOB. */
+export interface Sealed {
+	valueCipher: Uint8Array;
+	valueNonce: Uint8Array;
+	valueTag: Uint8Array;
+}
+
+/** The key is 32 bytes and the plaintext is UTF-8; nothing else is encoded, so a row round-trips exactly. */
+export function seal(plaintext: string, key: Uint8Array): Sealed {
+	const nonce = randomBytes(NONCE_BYTES);
+	const cipher = createCipheriv("aes-256-gcm", key, nonce);
+	const valueCipher = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
+	return { valueCipher, valueNonce: nonce, valueTag: cipher.getAuthTag() };
+}
+
+/**
+ * Throws when the key is not the one that sealed the row, or when any byte of the row moved. The caller
+ * adds the name — that is the only way a user finds out which secret a key rotation left behind.
+ */
+export function open(sealed: Sealed, key: Uint8Array): string {
+	const decipher = createDecipheriv("aes-256-gcm", key, asBuffer(sealed.valueNonce));
+	decipher.setAuthTag(asBuffer(sealed.valueTag));
+	try {
+		return Buffer.concat([decipher.update(asBuffer(sealed.valueCipher)), decipher.final()]).toString("utf8");
+	} catch {
+		throw new Error("the vault could not open this row: the key version is gone, or the ciphertext changed");
+	}
+}
+
+/** sha256 hex. `put` checks this before storing anything, so a repeat write does not need to decrypt. */
+export function fingerprint(plaintext: string): string {
+	return createHash("sha256").update(plaintext, "utf8").digest("hex");
+}
+
+/**
+ * What a list, a tool result or the UI shows instead of the value.
+ *
+ * A key's last four characters are how a user recognises which one they mean — the reason the plan keeps a
+ * little of it — and a fingerprint is how two SSH keys are told apart (what `ssh-keygen -lf` prints, so it
+ * reads the same). A short value gets no characters at all: showing four of a six-character password would
+ * show most of it. Note this fingerprints the bytes stored, not the public half of a private key, which is
+ * enough to tell two stored keys apart and is not the string to compare against `ssh-keygen`.
+ */
+export function mask(value: string, kind: SecretKind): string {
+	if (kind === "ssh_private_key" || kind === "ssh_public_key") {
+		return `SHA256:${createHash("sha256").update(value, "utf8").digest("base64").replace(/=+$/, "")}`;
+	}
+	// A mask is one line in a list, whatever was stored — a yaml blob or a key pasted with a trailing newline.
+	const flat = value.replace(/\s+/g, " ").trim();
+	if (flat.length <= 8) return "•••••";
+	return `${flat.slice(0, 3)}…${flat.slice(-4)}`;
+}
+
+/**
+ * Does this value match the kind it is being stored as? Answers with the sentence to show, or null.
+ *
+ * Only `yaml` has anything to say. A kubeconfig or an MCP config blob that does not parse is worthless the
+ * moment `secret_file` hands it to a command, and the vault is the last place that can name the line that
+ * broke. Any other kind is a string: rejecting a typo in a password would be a guess about what the user
+ * meant, which is not this function's call to make.
+ */
+export function validate(value: string, kind: SecretKind): string | null {
+	if (kind !== "yaml") return null;
+	try {
+		parse(value);
+	} catch (cause) {
+		// A YAMLParseError's first line names the line and column; the rest is a code frame the panel has no room for.
+		return `is not valid YAML: ${(cause as Error).message.split("\n")[0]}`;
+	}
+	return null;
+}
+
+/**
+ * A key provider holds versioned keys. `currentVersion` seals new rows; `key(version)` returns an older key
+ * while rows still need it and `undefined` once it is gone, which is how "rotate, then re-encrypt, then
+ * forget the old key" reaches a real error rather than a wrong plaintext.
+ */
+export interface KeyProvider {
+	readonly name: string;
+	currentVersion(): number;
+	key(version: number): Uint8Array | undefined;
+	/** Generate a new key, make it current, and return its version. */
+	rotate(): number;
+	/** Drop the versions no row needs any more. */
+	retain(versions: readonly number[]): void;
+}
+
+/**
+ * The default provider: a key file, mode 0600, created on first use. It is a JSON map of versions because
+ * rotation must keep the old key readable until every row has been re-sealed under the new one.
+ *
+ * Written by hand rather than with a temp file and a rename: the file already exists by then (created 0600
+ * on first use), and the only thing that can happen mid-write is a crash with an unreadable vault, which
+ * every other flypi JSON file behaves the same way about.
+ */
+export function keyfileProvider(file: string): KeyProvider {
+	const read = (): { current: number; keys: Record<string, string> } => {
+		if (!existsSync(file)) return write({ current: 1, keys: { 1: randomBytes(KEY_BYTES).toString("base64") } });
+		try {
+			const raw = JSON.parse(readFileSync(file, "utf8")) as unknown;
+			if (isObject(raw) && typeof raw.current === "number" && isObject(raw.keys)) return raw as { current: number; keys: Record<string, string> };
+		} catch {
+			// Fall through: a vault that cannot be read must not be replaced by a fresh key, because that
+			// would strand every row in the database. Say so instead.
+		}
+		throw new Error(`${file} is not a key file flypi can read (it holds the keys every encrypted row needs)`);
+	};
+	const write = (state: { current: number; keys: Record<string, string> }) => {
+		mkdirSync(dirname(file), { recursive: true });
+		writeFileSync(file, `${JSON.stringify(state, null, "\t")}\n`, { mode: 0o600 });
+		// `mode` only applies when the file is created; a umask, or a file that already existed, can leave it
+		// wider than that. Ask for it explicitly.
+		chmodSync(file, 0o600);
+		return state;
+	};
+
+	return {
+		name: "keyfile",
+		currentVersion: () => read().current,
+		key: (version) => {
+			const encoded = read().keys[String(version)];
+			return encoded === undefined ? undefined : Buffer.from(encoded, "base64");
+	 },
+		rotate: () => {
+			const state = read();
+			const current = state.current + 1;
+			write({ current, keys: { ...state.keys, [current]: randomBytes(KEY_BYTES).toString("base64") } });
+			return current;
+		},
+		retain: (versions) => {
+			const state = read();
+			const keep = new Set([state.current, ...versions]);
+			const keys: Record<string, string> = {};
+			for (const [version, encoded] of Object.entries(state.keys)) if (keep.has(Number(version))) keys[version] = encoded;
+			write({ current: state.current, keys });
+		},
+	};
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function asBuffer(value: Uint8Array): Buffer {
+	// node:sqlite hands back a plain Uint8Array for a BLOB; the crypto API wants a Buffer.
+	return Buffer.from(value);
+}

package/src/secrets/extension.ts

@@ -0,0 +1,253 @@
+/**
+ * The vault's agent surface (docs/secrets.md Phase 5.5): the `secret_*` tools and the two redaction hooks,
+ * registered as one extension like the memory one is.
+ *
+ * Two rules shape this file:
+ *
+ * - A tool result is where a credential is most likely to appear, so every result passes through the
+ *   redactor — the model sees `[secret:github_token]` instead of the token — except `secret_get`, which is
+ *   the one call whose whole point is to hand the plaintext over, and which the permission gate holds until
+ *   the user agrees.
+ * - The value must not become a durable artifact. So the assistant message is redacted at `message_end`,
+ *   before it is written to the session file: the value is in the model's context for the turn that asked
+ *   for it, and nothing after that keeps it.
+ *
+ * The vault itself is opened by the process that owns the memory database (the daemon, `npm run memory`, the
+ * CLI). A process with no vault registers nothing, which is how `npm run serve` stays out of it.
+ */
+import { spawn } from "node:child_process";
+import { chmodSync, mkdirSync, writeFileSync } from "node:fs";
+import type { ExtensionFactory } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import type { FlypiPaths } from "../agent/paths.ts";
+import { blockedToolCall } from "../agent/permission-gate.ts";
+import { secretFilePath, secretsConfig } from "./config.ts";
+import { placeholder, redactSecrets } from "./redact.ts";
+import { SECRET_KINDS, type SecretKind, type SecretStore } from "./vault.ts";
+
+/** The one tool whose result is plaintext, and the name the permission gate holds by default. */
+export const SECRET_GET = "secret_get";
+
+/** A command may print a lot; a credential does not need the last megabyte of it. */
+const COMMAND_BYTES = 64_000;
+const COMMAND_MS = 30_000;
+
+const NameParam = Type.String({ description: "The secret's name, as it appears in the vault" });
+const ValueParam = Type.String({ description: "The secret's value. It is encrypted before it is stored." });
+const KindParam = Type.Optional(
+	Type.String({
+		description: `What kind of secret: ${SECRET_KINDS.join(", ")}. "password" is any credential a service hands you — an api key, a token or a password, stored the same way; "yaml" is parsed before it is stored.`,
+	}),
+);
+
+export interface SecretsExtensionOptions {
+	/** Whose doing every audit row records. */
+	actor?: string;
+	paths: FlypiPaths;
+}
+
+export function createSecretsExtension(vault: SecretStore, options: SecretsExtensionOptions): ExtensionFactory {
+	const actor = options.actor ?? "agent";
+	return (pi) => {
+		/**
+		 * The gate Phase 5 built, applied to the one tool here whose result is a credential. Read from the
+		 * settings on every call like `createPermissionGateExtension` does, so the user turning it off takes
+		 * effect on the next call and not at the next restart. Being asked is the default: a model that wants a
+		 * value has to ask a person for it.
+		 */
+		pi.on("tool_call", (event) => {
+			if (event.toolName !== SECRET_GET) return;
+			if (!secretsConfig(options.paths).askBeforeUse) return;
+			return blockedToolCall(
+				`flypi did not run "${SECRET_GET}": reading a secret back as plaintext is the user's decision. ` +
+					`Ask them whether this call may run; to stop being asked, they set "secrets": { "askBeforeUse": false } ` +
+					`in .flypi/agent/settings.json. Until then use secret_env or secret_file, which hand the value to a command instead of to you.`,
+			);
+		});
+
+		pi.registerTool({
+			name: "secret_list",
+			label: "List secrets",
+			description: "List the flypi secret vault: names, kinds, masks and metadata. Never the values.",
+			parameters: Type.Object({ query: Type.Optional(Type.String({ description: "Filter by name or metadata" })) }),
+			execute: async (_id, { query }) => json(vault.list(typeof query === "string" ? query : "")),
+		});
+
+		pi.registerTool({
+			name: "secret_env",
+			label: "Run a command with a secret",
+			description:
+				"Run a shell command with the secret in FLYPI_SECRET and FLYPI_SECRET_<NAME>, and return its output with the secret replaced. Use this rather than putting the value in the command: it never reaches the transcript, the session file or the model's arguments.",
+			parameters: Type.Object({ name: NameParam, command: Type.String({ description: "The command to run" }) }),
+			execute: async (_id, { name, command }) => {
+				const value = vault.value(name, { actor, action: "used" });
+				if (value === undefined) return error(`no secret named "${name}" in the vault`);
+				const ran = await run(command, { FLYPI_SECRET: value, [`FLYPI_SECRET_${name.replace(/[^A-Za-z0-9]/g, "_").toUpperCase()}`]: value });
+				// Both guards: `redactSecrets` for any *other* secret the command printed, and this one for the
+				// value just handed over, which is redacted whatever its length. A failed command's output is
+				// redacted on the way out too — a stack trace quotes the header it was trying to send.
+				const text = redactSecrets(ran.text).replaceAll(value, placeholder(name));
+				if (!ran.ok) return error(text);
+				return ran.text.trim() === "" ? json({ ran: true, output: "", note: "the command printed nothing" }) : { content: [{ type: "text" as const, text }], details: { name, ran: true } };
+			},
+		});
+
+		pi.registerTool({
+			name: "secret_file",
+			label: "Write a secret to a file",
+			description:
+				"Write the secret to a mode-0400 file under .flypi/secrets/ and return its path. For the commands that only take a path — ssh, gpg. It is not the agent's environment, so the value is not inherited by every child process.",
+			parameters: Type.Object({ name: NameParam }),
+			execute: async (_id, { name }) => {
+				const value = vault.value(name, { actor, action: "used" });
+				if (value === undefined) return error(`no secret named "${name}" in the vault`);
+				mkdirSync(options.paths.secretsDir, { recursive: true });
+				// `secret_file_path` refuses a name that would not be a safe file name.
+				const file = secretFilePath(options.paths, name);
+				writeFileSync(file, value, { mode: 0o400 });
+				// `mode` only applies on create; ask for it, so re-writing a secret never leaves it world-readable.
+				chmodSync(file, 0o400);
+				return json({ path: file, mode: "0400", note: "the file holds the plaintext — delete it when the command is done" });
+			},
+		});
+
+		pi.registerTool({
+			name: SECRET_GET,
+			label: "Read a secret's value",
+			description:
+				"The plaintext value of one secret. It is held until the user approves each call: this is the one tool whose result is a credential, and the value will not be kept in the conversation afterwards.",
+			parameters: Type.Object({ name: NameParam }),
+			execute: async (_id, { name }) => {
+				const value = vault.value(name, { actor, action: "revealed" });
+				// No redaction on this result — that is the whole exception. If the value turns up again in a
+				// later tool result or in the answer, it is redacted there.
+				return value === undefined ? error(`no secret named "${name}" in the vault`) : { content: [{ type: "text" as const, text: value }], details: { name } };
+			},
+		});
+
+		pi.registerTool({
+			name: "secret_put",
+			label: "Store a secret",
+			description: "Store a value in the vault. Give it a name and a kind; the value is encrypted and only a mask is ever listed back.",
+			parameters: Type.Object({ name: NameParam, value: ValueParam, kind: KindParam, meta: Type.Optional(Type.Record(Type.String(), Type.String())) }),
+			execute: async (_id, params) => json(vault.put({ name: params.name, value: params.value, kind: params.kind as SecretKind, meta: params.meta, actor })),
+		});
+
+		pi.registerTool({
+			name: "secret_rotate",
+			label: "Replace a secret's value",
+			description: "Replace the value of an existing secret. The value it replaced is kept as a mask in the audit history; nothing auto-expires a secret.",
+			parameters: Type.Object({ name: NameParam, value: ValueParam, kind: KindParam }),
+			execute: async (_id, params) => json(vault.rotate({ name: params.name, value: params.value, kind: params.kind as SecretKind, actor })),
+		});
+
+		pi.registerTool({
+			name: "secret_delete",
+			label: "Delete a secret",
+			description: "Delete a secret from the vault. It leaves a tombstone and its history, like a forgotten memory.",
+			parameters: Type.Object({ name: NameParam }),
+			execute: async (_id, { name }) => json(vault.remove(name, { actor })),
+		});
+
+		/**
+		 * Every tool result, redacted — including `structuredContent`, which a handler that replaces only
+		 * `content` silently drops (docs/extensions.md). An MCP server's structured result is exactly where a
+		 * token tends to be echoed back.
+		 */
+		pi.on("tool_result", (event) => {
+			if (event.toolName === SECRET_GET) return;
+			let changed = false;
+			const content = event.content.map((block) => {
+				if (block.type !== "text") return block;
+				const text = redactSecrets(block.text);
+				if (text === block.text) return block;
+				changed = true;
+				return { ...block, text };
+			}) as typeof event.content;
+			const structured = event.structuredContent === undefined ? undefined : redactValue(event.structuredContent as Json);
+			if (!changed && structured === undefined) return;
+			return {
+				content,
+				...(structured === undefined ? {} : { structuredContent: structured }),
+				...(event.isError ? { isError: true } : {}),
+			};
+		});
+
+		/**
+		 * The assistant's own words, on the way into the session file. A model that repeats a token it was
+		 * shown writes it into the transcript, the context of every later turn, the HTML export and any memory
+		 * captured from it — this is the seam that stops that.
+		 */
+		pi.on("message_end", (event) => {
+			const message = event.message as { role?: string; content?: unknown };
+			if (message.role !== "assistant" || !Array.isArray(message.content)) return;
+			let changed = false;
+			const content = message.content.map((block) => {
+				if (typeof block !== "object" || block === null) return block;
+				const part = block as { type?: string; text?: string };
+				if (part.type !== "text" || typeof part.text !== "string") return block;
+				const text = redactSecrets(part.text);
+				if (text === part.text) return block;
+				changed = true;
+				return { ...part, text };
+			});
+			if (!changed) return;
+			return { message: { ...(event.message as object), content } as never };
+		});
+	};
+}
+
+function json(value: unknown): { content: { type: "text"; text: string }[]; details: unknown } {
+	const text = JSON.stringify(value, null, 2);
+	return { content: [{ type: "text", text }], details: value };
+}
+
+function error(text: string): { content: { type: "text"; text: string }[]; details: unknown; isError: true } {
+	return { content: [{ type: "text", text }], details: { error: text }, isError: true };
+}
+
+/**
+ * Recursive, because `structuredContent` is JSON: a token can be nested in it. Declared here rather than
+ * imported — pi's own `JsonValue` lives in `@earendil-works/pi-ai`, which is a dev dependency here.
+ */
+type Json = string | number | boolean | null | Json[] | { [key: string]: Json };
+
+function redactValue(value: Json): Json {
+	if (typeof value === "string") return redactSecrets(value);
+	if (Array.isArray(value)) return value.map((item) => redactValue(item));
+	if (typeof value === "object" && value !== null) {
+		return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, redactValue(item)]));
+	}
+	return value;
+}
+
+/**
+ * The command's own environment plus the secret — never the other way round, so nothing can name a variable
+ * over an existing one. Output is capped and the command is killed if it hangs; a command that fails is
+ * reported with its output, because "ssh refused it" is the answer the model needs.
+ */
+/** `{ ok: false }` covers both a non-zero exit and a command that never started; the text says which. */
+function run(command: string, env: Record<string, string>): Promise<{ text: string; ok: boolean }> {
+	return new Promise((resolve) => {
+		const child = spawn(command, { shell: true, env: { ...process.env, ...env } });
+		const chunks: Buffer[] = [];
+		let bytes = 0;
+		const collect = (buffer: Buffer) => {
+			if (bytes >= COMMAND_BYTES) return;
+			bytes += buffer.length;
+			chunks.push(buffer);
+		};
+		child.stdout.on("data", collect);
+		child.stderr.on("data", collect);
+		const timer = setTimeout(() => child.kill("SIGKILL"), COMMAND_MS);
+		child.on("close", (code) => {
+			clearTimeout(timer);
+			const output = Buffer.concat(chunks).toString("utf8");
+			resolve(code === 0 ? { text: output, ok: true } : { text: `the command exited with ${code}\n${output}`, ok: false });
+		});
+		child.on("error", (cause) => {
+			clearTimeout(timer);
+			resolve({ text: `the command could not run: ${(cause as Error).message}`, ok: false });
+		});
+	});
+}

package/src/secrets/redact.ts

@@ -0,0 +1,132 @@
+/**
+ * The redaction boundary (docs/secrets.md Phase 5.5).
+ *
+ * A secret's value is not stored anywhere except in a row of the vault, but it passes through a conversation
+ * as often as a user or a tool mentions it: memory bodies, turn rows, tool output, the HTML export, and the
+ * context of every later turn. So every durable write in flypi calls `redactSecrets` — `src/memory/store.ts`
+ * for turns and memory bodies, `src/daemon/jobs.ts` for job details, and the session extension in
+ * `src/secrets/extension.ts` for tool results and what the model says back.
+ *
+ * Which values count as secrets is *read from the vault*, not pushed at it: `setSecretSource` names where to
+ * ask, and the list is rebuilt when it is older than `DEFAULT_MAX_AGE_MS`. That is deliberate. The process
+ * that redacts is usually not the process that edits the vault — `flypi secret put` is its own process, and
+ * the memory server is another — and a pull with a short TTL needs no signalling between them. A process that
+ * changes the vault invalidates the cache itself, so it never redacts with a stale list.
+ *
+ * What is not here: the vault, or anything that decrypts. This module is given plaintext and turns text into
+ * text; `redactSecrets` is called on the hot path of every turn and must stay that cheap to reason about.
+ */
+
+/** A placeholder must not survive a second pass as someone else's secret. */
+export const placeholder = (name: string): string => `[secret:${name}]`;
+
+/**
+ * Below this, a value is not treated as a secret when redacting text. `hunter2` is a password; redacting
+ * every occurrence of `token` inside a memory about tokens would shred the memory. The vault refuses a name
+ * of its own below four characters, and anything shorter than this is reported by the status surface rather
+ * than redacted.
+ */
+export const MIN_SECRET_CHARS = 6;
+
+/**
+ * How long a redactor may answer from the list it already read. Short enough that a secret stored in another
+ * process is protected within a turn or two; long enough that storing one does not mean a decrypt of the
+ * whole vault before every memory write.
+ */
+export const DEFAULT_MAX_AGE_MS = 5_000;
+
+export interface ActiveSecret {
+	name: string;
+	value: string;
+}
+
+let source: (() => ActiveSecret[]) | undefined;
+let maxAgeMs = DEFAULT_MAX_AGE_MS;
+let cached: ActiveSecret[] | undefined;
+let cachedAt = 0;
+let sorted: string[] = [];
+/** Each value → the placeholders it maps to. A value stored under two names redacts to both, so the text says which. */
+let placeholders = new Map<string, string>();
+
+/**
+ * Where this process asks for the current secrets — usually `() => vault.activeValues()`. The list is
+ * decrypted on demand, once per `DEFAULT_MAX_AGE_MS`, and `invalidateSecrets()` ends that window the moment
+ * this process changes the vault.
+ */
+export function setSecretSource(next: () => ActiveSecret[], options: { maxAgeMs?: number } = {}): void {
+	source = next;
+	maxAgeMs = options.maxAgeMs ?? DEFAULT_MAX_AGE_MS;
+	invalidateSecrets();
+}
+
+/**
+ * This process is finished with the vault it was reading (a CLI that opened one and closed it, or a daemon
+ * shutting down). Redaction goes back to matching nothing: a source pointing at a closed database would
+ * otherwise turn an unrelated write into an error three frames away from the cause.
+ */
+export function closeSecretSource(): void {
+	source = undefined;
+	invalidateSecrets();
+	buildIndex([]);
+}
+
+/** Drop what this process has read, so the next redaction asks again. */
+export function invalidateSecrets(): void {
+	cached = undefined;
+	cachedAt = 0;
+}
+
+function currentSecrets(): ActiveSecret[] {
+	// The cache is the whole point — a memory write must not decrypt the vault — and its expiry is the whole
+	// point of the cache being allowed at all: a secret stored by another process still gets redacted.
+	if (cached !== undefined && Date.now() - cachedAt < maxAgeMs) return cached;
+	const list = source === undefined ? [] : source();
+	cached = list;
+	cachedAt = Date.now();
+	buildIndex(list);
+	return list;
+}
+
+/** The active values, longest first, so `sk-very-long` wins over `sk` inside the same string. */
+function buildIndex(list: ActiveSecret[]): void {
+	sorted = list.map((secret) => secret.value).filter((value) => value.length >= MIN_SECRET_CHARS).sort((a, b) => b.length - a.length);
+	placeholders = new Map<string, string>();
+	for (const { name, value } of list) {
+		const mark = placeholders.get(value) ?? "";
+		placeholders.set(value, mark === "" ? placeholder(name) : `${mark}${placeholder(name)}`);
+	}
+}
+
+/** The names of the active values too short to redact — the gap in this boundary, made visible. */
+export function shortSecrets(): string[] {
+	return currentSecrets()
+		.filter((secret) => secret.value.length < MIN_SECRET_CHARS)
+		.map((secret) => secret.name)
+		.sort();
+}
+
+function escapeRegExp(value: string): string {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function pattern(): RegExp | undefined {
+	// Reads the source first (and only re-reads it when the cached list has aged out), then matches. Kept in
+	// one place so `redactSecrets` and `containsSecret` cannot disagree about what the current secrets are.
+	currentSecrets();
+	if (sorted.length === 0) return undefined;
+	return new RegExp(sorted.map(escapeRegExp).join("|"), "g");
+}
+
+/** Replace every active secret value in `text` with a named placeholder. Idempotent: a placeholder never matches. */
+export function redactSecrets(text: string): string {
+	const regex = pattern();
+	if (regex === undefined) return text;
+	// Every match came out of `pattern()`, which is built from these same keys, so the lookup cannot miss.
+	return text.replace(regex, (value) => placeholders.get(value) as string);
+}
+
+/** Does this text contain an active secret? Used to refuse a memory rather than rewrite it. */
+export function containsSecret(text: string): boolean {
+	const regex = pattern();
+	return regex !== undefined && regex.test(text);
+}