@cldmv/gh-broker 0.9.0 → 0.10.0

package/deploy/lib/config-merge.mjs

@@ -7,7 +7,7 @@
  *	@Email: <Shinrai@users.noreply.github.com>
  *	-----
  *	@Last modified by: Nate Corcoran <CLDMV> (Shinrai@users.noreply.github.com)
- *	@Last modified time: 2026-11-01T00:40:44-07:00 (1793518844)
+ *	@Last modified time: 2026-11-02T21:30:45-08:00 (1793683845)
  *	-----
  *	@Copyright: Copyright (c) 2013-2026 Catalyzed Motivation Inc. All rights reserved.
  *
@@ -24,9 +24,11 @@
  * Field-level rules, because the layers have different owners:
  *   - `tools` (the allowlist) is a SECURITY control and is always taken from the example, so a
  *     removal or tightening in an update applies and neither the deployed copy, a --config
- *     file nor a flag can widen it. A --config file that contains `tools` is refused.
+ *     file nor a flag can widen it. A --config file that contains `tools` is refused. The one
+ *     exception is each deployed tool's boolean `otp` and `enabled`, which carry onto the same
+ *     tool in the new list (they never add a tool).
  *   - Everything else is operator data and the deployed copy wins over the example: `listen`,
- *     `upstream`, `defaultOwner`, `owners`, `ghcr`, `app`, `secrets`, `npm`. The example ships
+ *     `upstream`, `defaultOwner`, `owners`, `ghcr`, `app`, `secrets`, `npm`, `otp`. The example ships
  *     none of the owner-specific ones, so a fresh install has no owners until the operator
  *     supplies one (--owner, --config, or the interactive prompt).
  *   - Layers 3 and 4 are merged on top of what is deployed rather than replacing it: scalars are
@@ -37,9 +39,11 @@
  * The result is validated by the real loader (`--check`) before anything is deployed, and a
  * --config file may hold only `cred:` references, never token values.
  */
+import { DEFAULT_LISTEN } from "./agents.mjs";
+
 export const DEFAULT_GHCR_DROP_DIR = "/srv/gh-broker/ghcr-drop";
 
-const OPERATOR_KEYS = ["listen", "upstream", "defaultOwner", "owners", "app", "secrets", "npm", "ghcr"];
+const OPERATOR_KEYS = ["listen", "upstream", "defaultOwner", "owners", "app", "secrets", "npm", "ghcr", "otp"];
 const isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
 /** Shapes of live GitHub / npm tokens (classic, fine-grained, app, npm granular). */
 const TOKEN_SHAPE = /\b(?:gh[pousr]_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,}|npm_[A-Za-z0-9]{30,})\b/;
@@ -51,11 +55,20 @@ export function mergeConfig(example, current) {
 
 	const out = structuredClone(example);
 
-	// tools: always authoritative from the example (already copied into out).
+	// tools: the allowlist is authoritative from the example (already copied into out). The per-tool
+	// settings the operator owns are `otp` (gate a tool or ungate it, #143) and `enabled` (turn a
+	// shipped tool on or off, #146), so a boolean one on a deployed tool is carried onto the same
+	// tool in the new list. It never adds a tool.
+	const deployed = (Array.isArray(current.tools) ? current.tools : []).filter(isObject);
+	for (const key of ["otp", "enabled"]) {
+		const kept = new Map(deployed.filter((t) => typeof t[key] === "boolean").map((t) => [t.name, t[key]]));
+		for (const t of out.tools ?? []) if (kept.has(t.name)) t[key] = kept.get(t.name);
+	}
 
-	// scalars: current wins when defined.
+	// scalars: current wins when defined. An old `unix:` listen is the shared-socket form the
+	// per-agent sockets replaced, so it is not carried over (buildConfig sets the new default).
 	for (const k of ["listen", "upstream", "defaultOwner"]) {
-		if (current[k] !== undefined) out[k] = current[k];
+		if (current[k] !== undefined && !(k === "listen" && String(current[k]).startsWith("unix:"))) out[k] = current[k];
 	}
 
 	// owners: operator data. Current entries win per owner; any the example ships are kept.
@@ -66,6 +79,10 @@ export function mergeConfig(example, current) {
 		if (current[k] !== undefined) out[k] = structuredClone(current[k]);
 	}
 
+	// otp: the example ships the default seed ref; the deployed block wins per field, so a
+	// user's own limits or state path survive an upgrade and new default fields still arrive.
+	if (current.otp !== undefined) out.otp = { ...(example.otp ?? {}), ...structuredClone(current.otp) };
+
 	return out;
 }
 
@@ -78,7 +95,7 @@ export function layerConfig(base, overlay) {
 	for (const k of ["listen", "upstream", "defaultOwner"]) {
 		if (overlay[k] !== undefined) out[k] = overlay[k];
 	}
-	for (const k of ["app", "secrets", "npm"]) {
+	for (const k of ["app", "secrets", "npm", "otp"]) {
 		if (overlay[k] !== undefined) out[k] = { ...(out[k] ?? {}), ...structuredClone(overlay[k]) };
 	}
 	if (overlay.owners !== undefined) {
@@ -174,6 +191,10 @@ export async function buildConfig({ example, current, file, opts, nonInteractive
 	if (file) config = layerConfig(config, file);
 	config = layerConfig(config, overlayFromFlags(opts));
 	config.owners ??= {};
+	if (typeof config.listen !== "string" || config.listen.startsWith("unix:")) {
+		config.listen = DEFAULT_LISTEN;
+		notes.push(`listen set to ${DEFAULT_LISTEN} (one socket per agent; the shared unix: socket is gone)`);
+	}
 
 	if (Object.keys(config.owners).length === 0) {
 		if (nonInteractive) {

package/deploy/lib/install-args.mjs

@@ -32,7 +32,7 @@ const IMAGE_GLOB = /^[a-z0-9*](?:[a-z0-9._*-]*[a-z0-9*])?(?:\/[a-z0-9*](?:[a-z0-
 export const envSecretKey = (name) => "GH_BROKER_SECRET_" + name.toUpperCase().replace(/[^A-Z0-9]/g, "_");
 
 export function parseArgs(argv) {
-	const o = { positional: [], nonInteractive: false, createAgentUser: false, npm: false, npmScopes: [], npmOrgs: [], cliSecrets: {} };
+	const o = { positional: [], nonInteractive: false, createAgentUser: false, noMcpConfig: false, npm: false, npmScopes: [], npmOrgs: [], cliSecrets: {} };
 	// Consume the value after a value-taking flag, failing if it's missing or is
 	// itself a flag — so `--agent-user --secrets-provider file` can't silently take
 	// "--secrets-provider" as the username and proceed with an unintended user.
@@ -46,6 +46,7 @@ export function parseArgs(argv) {
 		if (a === "-h" || a === "--help") o.help = true;
 		else if (a === "-y" || a === "--non-interactive") o.nonInteractive = true;
 		else if (a === "--create-agent-user") o.createAgentUser = true;
+		else if (a === "--no-mcp-config") o.noMcpConfig = true;
 		else if (a === "--agent-user") o.agentUser = value(++i, a);
 		else if (a === "--secrets-provider") o.provider = value(++i, a);
 		else if (a === "--secrets-file") o.secretsFile = value(++i, a);
@@ -85,7 +86,7 @@ export function parseArgs(argv) {
 			o.defaultOwner = org;
 		} else if (a === "--listen") {
 			const addr = value(++i, a);
-			if (!/^unix:\/.+/.test(addr)) throw new Error(`--listen must be a "unix:<absolute path>" address, got "${addr}"`);
+			if (!/^agents:\/.+/.test(addr)) throw new Error(`--listen must be an "agents:<absolute directory>" address, got "${addr}"`);
 			o.listen = addr;
 		} else if (a === "--upstream") {
 			const url = value(++i, a);

package/deploy/lib/mcp-config.mjs

@@ -0,0 +1,211 @@
+/**
+ *
+ *	@Project: @cldmv/gh-broker
+ *	@Filename: /deploy/lib/mcp-config.mjs
+ *	@Date: 2026-11-02T09:12:00-08:00 (1793639520)
+ *	@Author: Nate Corcoran <CLDMV>
+ *	@Email: <Shinrai@users.noreply.github.com>
+ *	-----
+ *	@Last modified by: Nate Corcoran <CLDMV> (Shinrai@users.noreply.github.com)
+ *	@Last modified time: 2026-11-02T09:12:00-08:00 (1793639520)
+ *	-----
+ *	@Copyright: Copyright (c) 2013-2026 Catalyzed Motivation Inc. All rights reserved.
+ *
+ */
+
+/**
+ * Writing an agent user's Claude Code MCP config (#143, contract v2). The broker's entry goes in
+ * the top-level `mcpServers` of `<home>/.claude.json`; nothing else in that file is touched. The
+ * pure functions build the entry, pick its key and edit the JSON text; `applyMcpConfig` and
+ * `removeMcpConfig` do the file work (backup, atomic write that keeps the owner and mode, and a
+ * read-back check) with every filesystem effect injected. Root does that work in a directory the
+ * agent user owns, so `readOwnedFile` refuses anything but the user's own plain file.
+ */
+import { closeSync, constants, fstatSync, openSync, readSync } from "node:fs";
+import { agentGroup, socketPath } from "./agents.mjs";
+
+export const MCP_FILE = ".claude.json";
+export const MCP_BACKUP = ".claude.json.gh-broker.bak";
+const BROKER_PATH = "/run/gh-broker/";
+
+/** Largest ~/.claude.json root will read (Claude Code's own file is far smaller). */
+export const MAX_CONFIG_BYTES = 16 * 1024 * 1024;
+
+/** A file root must not read or replace: a symlink, not a regular file, not the user's, hard-linked, or oversized. */
+export class UnsafeFile extends Error {}
+
+/**
+ * Read `path` as root on behalf of the user `uid`, without following a symlink: the file must be
+ * a regular file owned by `uid` with a single link, and no larger than MAX_CONFIG_BYTES. Opened with O_NOFOLLOW (and O_NONBLOCK, so a
+ * FIFO can't hang the read), then checked and read through the same descriptor, so it can't be
+ * swapped between the check and the read.
+ * @returns {{ text: string, stat: { uid: number, gid: number, mode: number } } | undefined} undefined when there is no file
+ */
+export function readOwnedFile(path, uid) {
+	let fd;
+	try {
+		fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+	} catch (err) {
+		if (err.code === "ENOENT") return undefined;
+		if (err.code === "ELOOP") throw new UnsafeFile(`${path} is a symlink`);
+		throw err;
+	}
+	try {
+		const st = fstatSync(fd);
+		if (!st.isFile()) throw new UnsafeFile(`${path} is not a regular file`);
+		if (st.uid !== uid) throw new UnsafeFile(`${path} is owned by uid ${st.uid}, not the agent user (uid ${uid})`);
+		if (st.nlink !== 1) throw new UnsafeFile(`${path} has ${st.nlink} hard links`);
+		// Read at most one byte past the limit ourselves: the owner can grow the file after fstat.
+		const buf = Buffer.alloc(MAX_CONFIG_BYTES + 1);
+		let length = 0;
+		for (let n; length < buf.length && (n = readSync(fd, buf, length, buf.length - length, null)) > 0; ) length += n;
+		if (length > MAX_CONFIG_BYTES) throw new UnsafeFile(`${path} is over the ${MAX_CONFIG_BYTES}-byte limit`);
+		return { text: buf.toString("utf8", 0, length), stat: { uid: st.uid, gid: st.gid, mode: st.mode } };
+	} finally {
+		closeSync(fd);
+	}
+}
+
+/** `io.read`, with an unsafe file turned into `{ unsafe: reason }`. */
+function load(io, path, uid) {
+	try {
+		return io.read(path, uid);
+	} catch (err) {
+		if (err instanceof UnsafeFile) return { unsafe: err.message };
+		throw err;
+	}
+}
+
+/** The entry for `user`. `sg` makes the new group effective without a re-login. */
+export function mcpEntry(user, dir) {
+	return { type: "stdio", command: "sg", args: [agentGroup(user), "-c", `exec socat STDIO UNIX-CONNECT:${socketPath(dir, user)}`] };
+}
+
+/** Whether an entry points at a broker socket: the standard /run/gh-broker/ tree, or the configured agents directory. */
+const mentionsBroker = (entry, dir) => {
+	const text = JSON.stringify(entry ?? null);
+	return text.includes(BROKER_PATH) || (dir !== undefined && text.includes(`${dir}/`));
+};
+const isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+
+/** Keys of the entries that point at the broker (any /run/gh-broker/ socket, old or new, or one in `dir`). */
+export function brokerKeys(servers, dir) {
+	return Object.keys(servers).filter((k) => mentionsBroker(servers[k], dir));
+}
+
+/** The key to write: the existing broker entry's, else `github`, `gh-broker`, then `gh-broker-<user>` (first free). */
+export function chooseKey(servers, user, dir) {
+	const existing = brokerKeys(servers, dir);
+	if (existing.length) return existing[0];
+	return ["github", "gh-broker", `gh-broker-${user}`].find((k) => !(k in servers)) ?? `gh-broker-${user}`;
+}
+
+const sameEntry = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+
+/** Indentation of the file as written (tab or n spaces), so the edit doesn't reformat it. */
+function indentOf(text) {
+	const m = /^\{\r?\n([ \t]+)\S/.exec(text);
+	return m ? m[1] : "  ";
+}
+
+/** Parse the file; `undefined` text (no file) is an empty config. Returns undefined when it isn't a JSON object. */
+function parse(text) {
+	if (text === undefined) return {};
+	try {
+		const v = JSON.parse(text);
+		return isObject(v) ? v : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+/** Whether the file's broker entry for `user` is "ok", "missing", "points elsewhere" or "unreadable". */
+export function mcpStatus(text, user, dir) {
+	const cfg = parse(text);
+	if (cfg === undefined) return "unreadable";
+	const servers = isObject(cfg.mcpServers) ? cfg.mcpServers : {};
+	const keys = brokerKeys(servers, dir);
+	if (keys.length === 0) return "missing";
+	return keys.some((k) => sameEntry(servers[k], mcpEntry(user, dir))) ? "ok" : "points elsewhere";
+}
+
+/**
+ * The file text with `user`'s entry set. Only the chosen key changes.
+ * @returns {{ status: "unreadable" } | { status: "unchanged" | "changed", key: string, text: string }}
+ */
+export function mergeEntry(text, user, dir) {
+	const cfg = parse(text);
+	if (cfg === undefined) return { status: "unreadable" };
+	const servers = isObject(cfg.mcpServers) ? cfg.mcpServers : {};
+	const key = chooseKey(servers, user, dir);
+	const entry = mcpEntry(user, dir);
+	if (text !== undefined && sameEntry(servers[key], entry)) return { status: "unchanged", key, text };
+	const next = { ...cfg, mcpServers: { ...servers, [key]: entry } };
+	return { status: "changed", key, text: JSON.stringify(next, null, text === undefined ? "  " : indentOf(text)) + "\n" };
+}
+
+/**
+ * The file text with every broker entry removed (an empty `mcpServers` is left in place).
+ * @returns {{ status: "unreadable" | "absent" } | { status: "removed", keys: string[], text: string }}
+ */
+export function dropEntries(text, dir) {
+	const cfg = parse(text);
+	if (cfg === undefined) return { status: "unreadable" };
+	const servers = isObject(cfg.mcpServers) ? cfg.mcpServers : {};
+	const keys = brokerKeys(servers, dir);
+	if (keys.length === 0) return { status: "absent" };
+	const rest = Object.fromEntries(Object.entries(servers).filter(([k]) => !keys.includes(k)));
+	return { status: "removed", keys, text: JSON.stringify({ ...cfg, mcpServers: rest }, null, indentOf(text)) + "\n" };
+}
+
+/**
+ * Set `user`'s entry in their `.claude.json`.
+ * @param {object} o
+ * @param {string} o.home  the agent user's home directory
+ * @param {string} o.user
+ * @param {string} o.dir   the agents' socket directory
+ * @param {{ uid: number, gid: number }} o.owner  the agent user; owner for a file that has to be created
+ * @param {object} io      { read(path, uid) -> { text, stat: { uid, gid, mode } } | undefined (see readOwnedFile), write(path, text, { uid, gid, mode }) }
+ * @returns {{ status: "created" | "written" | "unchanged" | "unreadable" | "unsafe", key?: string, reason?: string, entry: object, path: string }}
+ */
+export function applyMcpConfig({ home, user, dir, owner }, io) {
+	const path = `${home}/${MCP_FILE}`;
+	const entry = mcpEntry(user, dir);
+	const before = load(io, path, owner.uid);
+	if (before?.unsafe) return { status: "unsafe", reason: before.unsafe, entry, path };
+	const merged = mergeEntry(before?.text, user, dir);
+	if (merged.status === "unreadable") return { status: "unreadable", entry, path };
+	if (merged.status === "unchanged") return { status: "unchanged", key: merged.key, entry, path };
+	let target = { ...owner, mode: 0o600 };
+	if (before !== undefined) {
+		target = { uid: before.stat.uid, gid: before.stat.gid, mode: before.stat.mode & 0o777 };
+		io.write(`${home}/${MCP_BACKUP}`, before.text, target);
+	}
+	io.write(path, merged.text, target);
+	const after = load(io, path, owner.uid);
+	if (after?.unsafe || mcpStatus(after?.text, user, dir) !== "ok") throw new Error(`${path}: the broker entry is not there after writing; restore ${MCP_BACKUP} if the file looks wrong`);
+	return { status: before === undefined ? "created" : "written", key: merged.key, entry, path };
+}
+
+/**
+ * Remove the broker entry from `user`'s `.claude.json`, backing the file up first.
+ * @returns {{ status: "removed" | "absent" | "no-file" | "unreadable" | "unsafe", keys?: string[], reason?: string, path: string }}
+ */
+export function removeMcpConfig({ home, dir, uid }, io) {
+	const path = `${home}/${MCP_FILE}`;
+	const before = load(io, path, uid);
+	if (before === undefined) return { status: "no-file", path };
+	if (before.unsafe) return { status: "unsafe", reason: before.unsafe, path };
+	const dropped = dropEntries(before.text, dir);
+	if (dropped.status !== "removed") return { status: dropped.status, path };
+	const target = { uid: before.stat.uid, gid: before.stat.gid, mode: before.stat.mode & 0o777 };
+	io.write(`${home}/${MCP_BACKUP}`, before.text, target);
+	io.write(path, dropped.text, target);
+	return { status: "removed", keys: dropped.keys, path };
+}
+
+/** The MCP status of `user`'s file for `agent list`: mcpStatus, or "unsafe (<reason>)". */
+export function mcpFileStatus({ home, user, dir, uid }, io) {
+	const got = load(io, `${home}/${MCP_FILE}`, uid);
+	return got?.unsafe ? `unsafe (${got.unsafe})` : mcpStatus(got?.text, user, dir);
+}

package/deploy/lib/otp-cli.mjs

@@ -0,0 +1,136 @@
+/**
+ *
+ *	@Project: @cldmv/gh-broker
+ *	@Filename: /deploy/lib/otp-cli.mjs
+ *	@Date: 2026-11-02T09:12:00-08:00 (1793639520)
+ *	@Author: Nate Corcoran <CLDMV>
+ *	@Email: <Shinrai@users.noreply.github.com>
+ *	-----
+ *	@Last modified by: Nate Corcoran <CLDMV> (Shinrai@users.noreply.github.com)
+ *	@Last modified time: 2026-11-02T09:12:00-08:00 (1793639520)
+ *	-----
+ *	@Copyright: Copyright (c) 2013-2026 Catalyzed Motivation Inc. All rights reserved.
+ *
+ */
+
+/**
+ * `gh-broker otp unlock | status | list | rotate` (#143, contract v2): the root-side half of the OTP gate.
+ * Lock state is per agent user, in the state file the daemon writes. Every effect is injected (see
+ * deploy/cli.mjs for the real wiring), so the commands are testable without root.
+ */
+import { DEFAULT_STATE_PATH, DEFAULT_MAX_FAILURES, DEFAULT_MAX_LOCKOUTS, describeUsers, emptyState, formatStatus, generateSeed, secondsUntilFreshCode, seedCredName, showSeed, spendRecentCodes, userOf, withoutUser, withoutUsers } from "./otp.mjs";
+import { assertAgentName, registeredAgents, versionWarning } from "./agents.mjs";
+
+export const statePathOf = (config) => config.otp?.statePath ?? DEFAULT_STATE_PATH;
+export const limitsOf = (config) => ({ maxFailures: config.otp?.maxFailures ?? DEFAULT_MAX_FAILURES, maxLockouts: config.otp?.maxLockouts ?? DEFAULT_MAX_LOCKOUTS });
+
+/** Run one `otp` subcommand. Returns the exit code; throws on a failure the dispatcher reports. */
+export async function otpCommand(command, rest, config, d) {
+	if (command === "status") return status(config, rest, d);
+	if (command === "unlock") return unlock(config, rest, d);
+	if (command === "list") return list(config, rest, d);
+	return rotate(config, d);
+}
+
+function status(config, rest, d) {
+	const only = rest.find((a) => !a.startsWith("-"));
+	const statePath = statePathOf(config);
+	const read = d.readState(statePath);
+	const known = registeredAgents(d.groups()).map((a) => a.user);
+	const users = describeUsers(read, only ? [only] : known, limitsOf(config), d.now()).filter((u) => !only || u.user === only);
+	const configured = seedCredName(config) !== undefined;
+	const warn = versionWarning(d.versions().pkg, d.versions().deployed);
+	if (rest.includes("--json")) {
+		d.log(JSON.stringify({ configured, statePath, fileStatus: read.status, users, unlockCommand: "sudo gh-broker otp unlock <user>" }, null, "\t"));
+	} else {
+		for (const line of formatStatus(users, { statePath, fileStatus: read.status, configured })) d.log(line);
+	}
+	if (warn) d.error(warn);
+	return 0;
+}
+
+/** Who is locked out right now (short lockout or hard lock), with the command that clears each. */
+function list(config, rest, d) {
+	const statePath = statePathOf(config);
+	const read = d.readState(statePath);
+	const known = registeredAgents(d.groups()).map((a) => a.user);
+	const locked = describeUsers(read, known, limitsOf(config), d.now())
+		.filter((u) => u.locked)
+		.map((u) => ({ user: u.user, corrupt: Boolean(u.corrupt), hardLock: u.hardLock, lockedUntil: u.lockedUntil, unlockCommand: u.corrupt ? "sudo gh-broker otp unlock --all" : `sudo gh-broker otp unlock ${u.user}` }));
+	if (rest.includes("--json")) {
+		d.log(JSON.stringify({ statePath, fileStatus: read.status, locked }, null, "\t"));
+		return 0;
+	}
+	if (locked.length === 0) d.log("nobody is locked out");
+	for (const u of locked) {
+		const why = u.corrupt ? `locked: ${statePath} is corrupt` : u.hardLock ? `hard-locked since ${u.hardLock.since} after ${u.hardLock.lockouts} lockouts` : `locked until ${u.lockedUntil}`;
+		d.log(`${u.user}  ${why}  unlock: ${u.unlockCommand}`);
+	}
+	return 0;
+}
+
+/** Record an unlock in the journal next to the daemon's audit log (never fatal). */
+function auditUnlock(d, user, detail) {
+	try {
+		d.audit({ ts: new Date(d.now()).toISOString(), decision: "otp-unlock", user, by: d.sudoUser() ?? "root", ...(detail ? { detail } : {}) });
+	} catch (err) {
+		d.error(`warning: the unlock could not be written to the journal: ${err.message}`);
+	}
+}
+
+/** What to tell the operator after a write that spent the recent codes (a code that is refused counts as a bad one). */
+const afterUnlock = (now) => `The code the authenticator shows now won't work, nor the one after it: wait ${secondsUntilFreshCode(now)} s for a fresh code.`;
+
+function unlock(config, rest, d) {
+	const all = rest.includes("--all");
+	const user = rest.find((a) => !a.startsWith("-"));
+	if (all === Boolean(user)) throw new Error('name the agent to unlock ("sudo gh-broker otp unlock <user>") or pass --all');
+	if (user) assertAgentName(user);
+	const statePath = statePathOf(config);
+	const read = d.readState(statePath);
+	if (read.status === "missing") {
+		d.log(`nothing to unlock: no state file at ${statePath}`);
+		return 0;
+	}
+	const now = d.now();
+	if (read.status === "corrupt") {
+		if (!all) throw new Error(`${statePath} is corrupt, so every user is locked; run "sudo gh-broker otp unlock --all" to rewrite it clean`);
+		// The old lastAcceptedStep can't be read back, so spend everything up to now instead.
+		d.writeState(statePath, spendRecentCodes(emptyState(), now));
+		auditUnlock(d, "*", "rewrote a corrupt state file");
+		d.log(`rewrote the corrupt state file at ${statePath}; everyone is unlocked. ${afterUnlock(now)}`);
+		return 0;
+	}
+	if (all) {
+		d.writeState(statePath, spendRecentCodes(withoutUsers(read.state), now));
+		auditUnlock(d, "*");
+		d.log(`cleared the lock state of every user in ${statePath}. ${afterUnlock(now)}`);
+		return 0;
+	}
+	if (!Object.hasOwn(read.state.users, user)) {
+		d.log(`${user} has no lock state; nothing to clear`);
+		return 0;
+	}
+	const wasLocked = Boolean(userOf(read.state, user).hardLock);
+	d.writeState(statePath, spendRecentCodes(withoutUser(read.state, user), now));
+	auditUnlock(d, user);
+	d.log(`${wasLocked ? `unlocked ${user}` : `cleared ${user}'s counters (not hard-locked)`}. ${afterUnlock(now)}`);
+	return 0;
+}
+
+async function rotate(config, d) {
+	const name = seedCredName(config);
+	if (!name) throw new Error("OTP is not configured (no otp.seed in the config); re-run the installer first");
+	const seed = d.newSeed ? d.newSeed() : generateSeed();
+	// Shown before it is stored: storing replaces the old seed, so a failure after the store
+	// would otherwise leave a seed nobody has.
+	await showSeed({ seed, host: d.host(), log: d.log, ...(d.qr ? { qr: d.qr } : {}) });
+	try {
+		d.storeSeed(config, name, seed);
+	} catch (err) {
+		throw new Error(`storing the new seed failed (${err.message}); the key above is not in use and the old seed is still the stored one. Nothing was restarted; run "sudo gh-broker otp rotate" again`);
+	}
+	d.restart();
+	d.log("service restarted. The old authenticator entry no longer works; remove it from your app.");
+	return 0;
+}