@cldmv/gh-broker 0.0.0-stage → 0.7.0

package/deploy/install.mjs

@@ -0,0 +1,344 @@
+#!/usr/bin/env node
+/**
+ *
+ *	@Project: @cldmv/gh-broker
+ *	@Filename: /deploy/install.mjs
+ *	@Date: 2026-09-06T10:05:35-07:00 (1788714335)
+ *	@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-10-02T11:30:58-07:00 (1790965858)
+ *	-----
+ *	@Copyright: Copyright (c) 2013-2026 Catalyzed Motivation Inc. All rights reserved.
+ *
+ */
+
+/**
+ * gh-broker installer — one command for first install AND upgrade.
+ *
+ *   sudo node deploy/install.mjs [agent-user] [flags]
+ *
+ * Prerequisite: node >= 20. Idempotent: re-run to upgrade (config regenerated by
+ * merge, existing secrets kept). Interactive by default; pass flags plus
+ * --non-interactive for a single unattended command. See --help and
+ * docs/deploy-architecture.md.
+ */
+import { readFileSync, readdirSync, existsSync, statSync, rmSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import {
+	run, has, isRoot, userExists, requireGid,
+	ensureServiceUser, createAgentUser, addUserToGroup,
+	pointNodeSymlinks, currentNodeBin, ensureDirs, installUnit,
+	enableService, restartService, serviceActive, deployDist, writeConfigFile,
+	trySystemdCredDecrypt, systemdCredsEncrypt, ensureCredsDir, writeCredsDropin, removeCredsDropin
+} from "./lib/system.mjs";
+import { promptLine, promptHidden, confirm, choose } from "./lib/prompt.mjs";
+import { mergeConfig } from "./lib/config-merge.mjs";
+import { writeSecretsFile, readSecretsFile, removeSecretsFile, referencedCredNames, detectSecretsProvider } from "./lib/secret-store.mjs";
+import { smokeTest } from "./lib/smoke.mjs";
+
+const REPO = dirname(dirname(fileURLToPath(import.meta.url)));
+const SVC_USER = "gh-broker";
+const SVC_GROUP = "gh-broker";
+const CLIENTS_GROUP = "gh-broker-clients";
+const APP_DIR = "/opt/gh-broker";
+const DIST = join(REPO, "dist");
+const DIST_ENTRY = join(DIST, "index.mjs");
+
+const log = (m) => console.log(m);
+const step = (m) => console.log(`\n==> ${m}`);
+const die = (m) => {
+	console.error(`gh-broker install: ${m}`);
+	process.exit(1);
+};
+
+function readJson(path) {
+	try {
+		return JSON.parse(readFileSync(path, "utf8"));
+	} catch {
+		return null;
+	}
+}
+
+const HELP = `gh-broker installer — install and upgrade in one command.
+
+Usage: sudo node deploy/install.mjs [agent-user] [flags]
+
+Flags:
+  --agent-user <name>     the unprivileged user the agent runs as
+                          (also positional; defaults to $SUDO_USER)
+  --secrets-provider <p>  systemd-creds | file   (skips the prompt)
+  --secrets-file <path>   JSON { "<cred-name>": "<token>" } to import tokens from
+  --create-agent-user     create the agent user if missing (no confirm)
+  -y, --non-interactive   never prompt; fail if a value/decision is missing
+  -h, --help              this help
+
+Non-interactive credentials: for each not already stored, the token is taken from
+--secrets-file, then env GH_BROKER_SECRET_<NAME> (NAME upper-cased, non-alnum -> _).
+Example (unattended):
+  sudo GH_BROKER_SECRET_CLDMV_READ=… GH_BROKER_SECRET_CLDMV_WRITE=… \\
+    /usr/local/bin/node deploy/install.mjs --agent-user repo \\
+    --secrets-provider systemd-creds --non-interactive`;
+
+function parseArgs(argv) {
+	const o = { positional: [], nonInteractive: false, createAgentUser: false };
+	// 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.
+	const value = (i, flag) => {
+		const v = argv[i];
+		if (v === undefined || v.startsWith("-")) die(`${flag} requires a value (see --help)`);
+		return v;
+	};
+	for (let i = 0; i < argv.length; i++) {
+		const a = argv[i];
+		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 === "--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);
+		else if (a.startsWith("-")) die(`unknown flag: ${a} (see --help)`);
+		else o.positional.push(a);
+	}
+	return o;
+}
+
+const envSecretKey = (name) => "GH_BROKER_SECRET_" + name.toUpperCase().replace(/[^A-Z0-9]/g, "_");
+
+async function main() {
+	const opts = parseArgs(process.argv.slice(2));
+	if (opts.help) {
+		log(HELP);
+		return;
+	}
+	if (opts.provider && opts.provider !== "systemd-creds" && opts.provider !== "file") {
+		die(`--secrets-provider must be "systemd-creds" or "file"`);
+	}
+	const importTokens = opts.secretsFile ? readJson(opts.secretsFile) : {};
+	// Must be a plain JSON object of { "<name>": "<token>" } — an array parses as an
+	// "object" but yields no tokens, so reject it explicitly rather than importing nothing.
+	if (opts.secretsFile && (!importTokens || typeof importTokens !== "object" || Array.isArray(importTokens))) {
+		die(`--secrets-file: ${opts.secretsFile} must be a JSON object of { "<name>": "<token>" }`);
+	}
+
+	if (!isRoot()) die("must run as root: sudo node deploy/install.mjs [agent-user] [flags]");
+	if (process.platform !== "linux") {
+		die(`only Linux is implemented today (platform: ${process.platform}). The path/secret/service seams are ready; the impls are not.`);
+	}
+
+	step("prerequisites");
+	for (const cmd of ["systemctl", "useradd", "getent", "sudo"]) if (!has(cmd)) die(`missing required command: ${cmd}`);
+	for (const cmd of ["socat", "rsync"]) if (!has(cmd)) log(`  note: '${cmd}' not found — ${cmd === "socat" ? "the agent socket bridge needs it" : "will fall back to a plain copy"}`);
+
+	// --- agent user ---
+	step("agent user");
+	let agentUser = opts.agentUser || opts.positional[0] || process.env.SUDO_USER || "";
+	if (!agentUser) {
+		if (opts.nonInteractive) die("no agent user — pass --agent-user <name>");
+		agentUser = await promptLine("Which unprivileged user does the agent run as? ");
+	}
+	if (!agentUser) die("no agent user given");
+	if (!userExists(agentUser)) {
+		const create = opts.createAgentUser || (!opts.nonInteractive && (await confirm(`User "${agentUser}" does not exist. Create it (plain, no sudo)?`)));
+		if (!create) die(`agent user "${agentUser}" missing — create it first or pass --create-agent-user`);
+		createAgentUser(agentUser);
+		log(`  created "${agentUser}"`);
+	} else {
+		log(`  "${agentUser}" exists`);
+	}
+
+	// --- build if needed ---
+	// This installer requires root, but dist/ and node_modules/ are generated INSIDE
+	// the repo checkout itself — not the deploy target (/opt/gh-broker, a directory
+	// the installer owns outright and correctly chowns to the gh-broker service user
+	// via deployDist() below). The checkout already has an owner: whoever owns this
+	// very script file. Build AS that owner via `sudo -u '#<uid>'` — sudo resolves
+	// that uid's home directory, primary group, AND full supplementary groups itself
+	// (exactly like a real login), so generated files are correct from the moment
+	// they're created — never chown, which is neither cross-platform nor necessary
+	// once nothing is ever created with the wrong owner to begin with.
+	const nodeModulesDir = join(REPO, "node_modules");
+	const buildUid = statSync(fileURLToPath(import.meta.url)).uid;
+	const asBuildOwner = (cmd, args) => run("sudo", ["-u", `#${buildUid}`, cmd, ...args], { cwd: REPO, stdio: "inherit" });
+
+	// A prior root-run build (an older version of this script, or a manual `sudo npm
+	// run build`) can leave dist/ or node_modules/ owned by root instead. Detect that
+	// and rebuild rather than reuse it — root can always remove a root-owned
+	// directory (regular DAC checks don't apply to it), where the build subprocess
+	// (running as the checkout owner) could not. This makes re-running the installer
+	// self-healing with no separate manual fix ever required.
+	const distStale = existsSync(DIST_ENTRY) && statSync(DIST_ENTRY).uid !== buildUid;
+	const modulesStale = existsSync(nodeModulesDir) && statSync(nodeModulesDir).uid !== buildUid;
+	if (!existsSync(DIST_ENTRY) || distStale || modulesStale) {
+		step(distStale || modulesStale ? "build (owned by a different user — rebuilding)" : "build (dist not found)");
+		if (!has("npm")) die(`dist/ is missing and 'npm' is not installed — build the bundle first (npm run build) or install npm, then re-run`);
+		if (distStale) rmSync(DIST, { recursive: true, force: true });
+		if (modulesStale) rmSync(nodeModulesDir, { recursive: true, force: true });
+		if (!existsSync(nodeModulesDir)) asBuildOwner("npm", ["ci"]);
+		asBuildOwner("npm", ["run", "build"]);
+	}
+
+	// --- resolve deployed paths from the daemon itself (one resolver, no drift) ---
+	const paths = JSON.parse(run(currentNodeBin(), [DIST_ENTRY, "--print-paths"]).stdout);
+	const configDir = dirname(paths.config);
+	log(`  config:  ${paths.config}`);
+	log(`  secrets: ${paths.secrets}`);
+
+	// --- users, groups, dirs, node symlink ---
+	step("service user, groups, directories");
+	ensureServiceUser(SVC_USER, SVC_GROUP, CLIENTS_GROUP);
+	addUserToGroup(agentUser, CLIENTS_GROUP);
+	ensureDirs(configDir, APP_DIR, SVC_USER, SVC_GROUP);
+	const linked = pointNodeSymlinks(currentNodeBin());
+	log(`  node symlink -> ${currentNodeBin()} (${linked.join(", ")})`);
+
+	// --- config: merge(example, current) ---
+	step("config (merge example + current)");
+	const example = readJson(join(REPO, "config.example.json"));
+	if (!example) die("config.example.json missing or invalid");
+	const current = readJson(paths.config); // null on first install
+	const merged = mergeConfig(example, current);
+
+	// --- secrets: operator chooses the backend, then tokens are stored in it ---
+	step("secrets");
+	const needed = referencedCredNames(merged);
+	const existingFile = readSecretsFile(paths.secrets); // {} if none
+	const credsDir = join(configDir, "creds"); // systemd-creds location
+	const priorProvider = merged.secrets?.provider ?? "systemd-creds";
+	let provider = opts.provider;
+	if (!provider) {
+		// An existing install already has a backend — keep it rather than asking again. Only a
+		// first install (or an ambiguous one) falls through to the prompt.
+		let credNames = [];
+		try {
+			credNames = readdirSync(credsDir).filter((f) => f.endsWith(".cred")).map((f) => f.slice(0, -".cred".length));
+		} catch {
+			// no creds dir yet — nothing encrypted on disk
+		}
+		const detected = detectSecretsProvider({ configured: current?.secrets?.provider, credNames, fileTokenNames: Object.keys(existingFile) });
+		if (detected) {
+			provider = detected;
+			log(`  keeping existing backend: ${provider} (change it with --secrets-provider)`);
+		}
+	}
+	if (!provider) {
+		provider = opts.nonInteractive
+			? priorProvider
+			: await choose(
+					"How should the PAT credentials be stored at rest?",
+					[
+						{ key: "systemd-creds", label: "systemd-creds — encrypted, host-bound (recommended; Linux/systemd)" },
+						{ key: "file", label: "file — plaintext JSON 0640 root:gh-broker (portable, platform-neutral)" }
+					],
+					priorProvider === "file" ? 2 : 1
+				);
+	}
+	log(`  backend: ${provider}`);
+	merged.secrets = { provider, ...(merged.secrets?.path ? { path: merged.secrets.path } : {}) };
+
+	// The App private key (if config.app is ever set) is a multi-line PEM the
+	// single-line prompt can't accept — it must be supplied out-of-band.
+	const appKeyName = merged.app?.privateKey?.startsWith("cred:") ? merged.app.privateKey.slice("cred:".length) : undefined;
+
+	// A token the operator EXPLICITLY supplied for this run — --secrets-file, then
+	// env GH_BROKER_SECRET_<NAME>. Its presence is what makes a re-run ROTATE an
+	// existing credential rather than keep it. Only non-empty strings count.
+	const explicitToken = (name) => {
+		const fromImport = importTokens && importTokens[name];
+		if (typeof fromImport === "string" && fromImport) return fromImport;
+		const fromEnv = process.env[envSecretKey(name)];
+		if (typeof fromEnv === "string" && fromEnv) return fromEnv;
+		return undefined;
+	};
+
+	// Resolve a token's plaintext, only when needed. Precedence:
+	//   plaintext secrets file (file → creds migration) → explicit --secrets-file/env
+	//   (a new value = rotation) → decrypt an existing legacy .cred (migration/keep) →
+	//   prompt (interactive only). Explicit MUST beat decrypt, or a rotation would
+	//   just re-encrypt the old decrypted value. Every source yields a non-empty STRING.
+	const resolveToken = async (name) => {
+		const fromFile = existingFile[name];
+		if (typeof fromFile === "string" && fromFile) return fromFile;
+		const explicit = explicitToken(name);
+		if (explicit) return explicit;
+		const dec = trySystemdCredDecrypt(name, join(credsDir, `${name}.cred`));
+		if (dec) {
+			log(`  ${name}: migrated from systemd-creds`);
+			return dec;
+		}
+		if (opts.nonInteractive) die(`missing credential "${name}" — provide via --secrets-file or env ${envSecretKey(name)}`);
+		if (name === appKeyName) {
+			die(`credential "${name}" is a GitHub App private key (multi-line PEM); the single-line prompt can't accept it — supply it via --secrets-file or env ${envSecretKey(name)}`);
+		}
+		const entered = await promptHidden(`  ${name} (input hidden): `);
+		if (!entered) die(`empty value for "${name}"`);
+		return entered;
+	};
+
+	if (provider === "systemd-creds") {
+		ensureCredsDir(configDir, SVC_GROUP);
+		for (const name of needed) {
+			const credFile = join(credsDir, `${name}.cred`);
+			const existed = existsSync(credFile);
+			// Re-encrypt (rotate) only when the operator supplies a new value — a
+			// plaintext entry (file → creds migration) or an explicit --secrets-file/env
+			// token. On a plain re-run with no new value, keep the existing cred as-is.
+			const rotate = Boolean(existingFile[name]) || explicitToken(name) !== undefined;
+			if (existed && !rotate) {
+				log(`  ${name}: existing systemd-creds kept`);
+				continue;
+			}
+			systemdCredsEncrypt(name, await resolveToken(name), credFile);
+			log(`  ${name}: ${existed ? "rotated" : "encrypted"} (systemd-creds)`);
+		}
+		writeCredsDropin(needed, credsDir);
+		// Now that creds are encrypted, a plaintext secrets file from a previous
+		// `file` install must not linger — it would defeat "encrypted at rest".
+		if (existsSync(paths.secrets)) {
+			removeSecretsFile(paths.secrets);
+			log(`  removed plaintext secrets file (now using systemd-creds)`);
+		}
+	} else {
+		const tokens = { ...existingFile };
+		for (const name of needed) {
+			if (!tokens[name]) tokens[name] = await resolveToken(name);
+		}
+		writeSecretsFile(paths.secrets, tokens, { gid: requireGid(SVC_GROUP) });
+		removeCredsDropin(); // no systemd-creds delivery under the file provider
+	}
+	writeConfigFile(paths.config, merged, SVC_GROUP);
+
+	// --- validate with the real loader before deploying ---
+	step("validate config");
+	run(currentNodeBin(), [DIST_ENTRY, "--check", "--config", paths.config], {
+		env: { ...process.env, GH_BROKER_SECRETS: paths.secrets },
+		stdio: "inherit"
+	});
+
+	// --- deploy unit + dist, restart ---
+	step("deploy");
+	installUnit(join(REPO, "deploy", "gh-broker.service"));
+	enableService();
+	deployDist(DIST, APP_DIR, SVC_USER, SVC_GROUP);
+	restartService();
+	log(`  service: ${serviceActive()}`);
+
+	// --- smoke test ---
+	step("smoke test");
+	const sock = merged.listen.replace(/^unix:/, "");
+	try {
+		const r = await smokeTest(sock);
+		log(`  ✅ broker answered — ${r.tools.length} tools advertised${r.roundTrip ? `; ${r.roundTrip}` : ""}`);
+	} catch (e) {
+		die(`smoke test failed: ${e.message}\n  check: journalctl -u gh-broker -n 30 --no-pager`);
+	}
+
+	log(`\n✅ gh-broker installed. Point the agent's MCP client at the socket:`);
+	log(`   "github": { "type": "stdio", "command": "socat", "args": ["STDIO", "UNIX-CONNECT:${sock}"] }`);
+	log(`   (re-login as "${agentUser}" so its ${CLIENTS_GROUP} membership is active)`);
+}
+
+main().catch((e) => die(e.message));

package/deploy/install.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+#
+# OPTIONAL Linux convenience bootstrap. The real installer is the Node one:
+#   sudo node deploy/install.mjs [agent-user]
+# with node >= 20 as the only prerequisite. This script just gets a system-wide
+# node onto the box first (via nvm) for a truly zero-prerequisite run, then hands
+# off. Not needed if node is already installed. See docs/deploy-architecture.md.
+set -euo pipefail
+[[ $EUID -eq 0 ]] || { echo "run as root: sudo $0 [agent-user]" >&2; exit 1; }
+HERE="$(cd "$(dirname "$0")" && pwd)"
+
+node_ok() { command -v node >/dev/null 2>&1 && node -e 'process.exit(+process.versions.node.split(".")[0] >= 20 ? 0 : 1)' 2>/dev/null; }
+
+if ! node_ok; then
+	echo "==> node >=20 not found — installing system-wide nvm + node"
+	export NVM_DIR=/usr/local/nvm
+	if [[ ! -s "$NVM_DIR/nvm.sh" ]]; then
+		command -v git >/dev/null 2>&1 || { echo "git not found — needed to fetch nvm; install git, or install node>=20 yourself then run: sudo node $HERE/install.mjs [agent-user]" >&2; exit 1; }
+		git clone --depth 1 https://github.com/nvm-sh/nvm.git "$NVM_DIR"
+	fi
+	# shellcheck source=/dev/null
+	. "$NVM_DIR/nvm.sh"
+	nvm install --lts >/dev/null
+	nvm alias default node >/dev/null
+	ver="$(nvm version default)"
+	for b in node npm npx; do ln -sfn "/usr/local/nvm/versions/node/$ver/bin/$b" "/usr/local/bin/$b"; done
+fi
+
+exec "$(command -v node)" "$HERE/install.mjs" "$@"

package/deploy/lib/config-merge.mjs

@@ -0,0 +1,56 @@
+/**
+ *
+ *	@Project: @cldmv/gh-broker
+ *	@Filename: /deploy/lib/config-merge.mjs
+ *	@Date: 2026-09-06T10:05:35-07:00 (1788714335)
+ *	@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-10-02T11:30:58-07:00 (1790965858)
+ *	-----
+ *	@Copyright: Copyright (c) 2013-2026 Catalyzed Motivation Inc. All rights reserved.
+ *
+ */
+
+/**
+ * Regenerate the deployed config by merging shipped defaults with what's already
+ * deployed — never a blind overwrite. See docs/deploy-architecture.md.
+ *
+ *   new_config = mergeConfig(example_defaults, current_config)
+ *
+ * Field-level precedence, because the two halves have different owners:
+ *   - `tools` (the allowlist) is a SECURITY control → taken from the example, so a
+ *     removal/tightening in an update always applies (a "current wins" merge would
+ *     silently keep a tool the repo dropped).
+ *   - `owners` → current entries win and are preserved; example owners not present
+ *     in current are added (a newly-onboarded org in the repo shows up on upgrade).
+ *   - `listen` / `upstream` / `defaultOwner` / `app` / `secrets` → current wins if
+ *     set, else the example's value.
+ *
+ * On a first install (no current), the example is used as-is.
+ */
+export function mergeConfig(example, current) {
+	if (!example || typeof example !== "object" || Array.isArray(example)) throw new Error("mergeConfig: example config must be an object");
+	if (!current) return structuredClone(example);
+	if (typeof current !== "object" || Array.isArray(current)) throw new Error("mergeConfig: current config must be an object");
+
+	const out = structuredClone(example);
+
+	// tools: always authoritative from the example (already copied into out).
+
+	// scalars: current wins when defined.
+	for (const k of ["listen", "upstream", "defaultOwner"]) {
+		if (current[k] !== undefined) out[k] = current[k];
+	}
+
+	// owners: current entries win per-owner; example owners not in current are kept.
+	out.owners = { ...(example.owners ?? {}), ...(current.owners ?? {}) };
+
+	// optional blocks: current wins if present.
+	for (const k of ["app", "secrets"]) {
+		if (current[k] !== undefined) out[k] = current[k];
+	}
+
+	return out;
+}

package/deploy/lib/prompt.mjs

@@ -0,0 +1,98 @@
+/**
+ *
+ *	@Project: @cldmv/gh-broker
+ *	@Filename: /deploy/lib/prompt.mjs
+ *	@Date: 2026-09-06T10:05:35-07:00 (1788714335)
+ *	@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-10-02T11:30:58-07:00 (1790965858)
+ *	-----
+ *	@Copyright: Copyright (c) 2013-2026 Catalyzed Motivation Inc. All rights reserved.
+ *
+ */
+
+import { stdin, stdout } from "node:process";
+
+// Control codes, by number, so no literal control characters live in this file.
+const LF = 10; // Enter
+const CR = 13; // Enter
+const EOT = 4; // Ctrl-D
+const ETX = 3; // Ctrl-C
+const DEL = 127; // Backspace
+const BS = 8; // Backspace
+
+/**
+ * Raw-mode line reader. `echo` controls whether typed characters are shown:
+ * visible prompts echo them, secret prompts don't. Handles Enter, Ctrl-C (abort),
+ * Ctrl-D, and Backspace. Falls back to non-raw when stdin isn't a TTY.
+ */
+function readLine(question, echo) {
+	return new Promise((resolve, reject) => {
+		stdout.write(question);
+		let input = "";
+		const onData = (chunk) => {
+			const s = chunk.toString("utf8");
+			for (const ch of s) {
+				const code = ch.charCodeAt(0);
+				if (code === LF || code === CR || code === EOT) {
+					cleanup();
+					stdout.write("\n");
+					return resolve(input.trim());
+				}
+				if (code === ETX) {
+					cleanup();
+					stdout.write("\n");
+					return reject(new Error("aborted"));
+				}
+				if (code === DEL || code === BS) {
+					if (input.length > 0) {
+						input = input.slice(0, -1);
+						if (echo) stdout.write("\b \b");
+					}
+					continue;
+				}
+				input += ch;
+				if (echo) stdout.write(ch);
+			}
+		};
+		const cleanup = () => {
+			stdin.removeListener("data", onData);
+			if (stdin.isTTY) stdin.setRawMode(false);
+			stdin.pause();
+		};
+		if (stdin.isTTY) stdin.setRawMode(true);
+		stdin.resume();
+		stdin.on("data", onData);
+	});
+}
+
+/** Ask a visible question; typed characters are echoed. Returns the trimmed answer. */
+export function promptLine(question) {
+	return readLine(question, true);
+}
+
+/** Ask for a secret; typed characters are NOT echoed. Never prints the value. */
+export function promptHidden(question) {
+	return readLine(question, false);
+}
+
+/** Yes/no confirmation. Defaults to no unless the answer starts with y/Y. */
+export async function confirm(question) {
+	const a = await promptLine(`${question} [y/N] `);
+	return /^y(es)?$/i.test(a);
+}
+
+/**
+ * Present numbered options ({ key, label }) and return the chosen key.
+ * Empty input picks the 1-based default `def`.
+ */
+export async function choose(question, options, def = 1) {
+	stdout.write(`${question}\n`);
+	options.forEach((o, i) => stdout.write(`  ${i + 1}) ${o.label}\n`));
+	const a = await promptLine(`Choose [${def}]: `);
+	const n = a === "" ? def : parseInt(a, 10);
+	const idx = Number.isInteger(n) && n >= 1 && n <= options.length ? n - 1 : def - 1;
+	return options[idx].key;
+}

package/deploy/lib/secret-store.mjs

@@ -0,0 +1,114 @@
+/**
+ *
+ *	@Project: @cldmv/gh-broker
+ *	@Filename: /deploy/lib/secret-store.mjs
+ *	@Date: 2026-09-06T10:05:35-07:00 (1788714335)
+ *	@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-10-02T11:30:58-07:00 (1790965858)
+ *	-----
+ *	@Copyright: Copyright (c) 2013-2026 Catalyzed Motivation Inc. All rights reserved.
+ *
+ */
+
+import { writeFileSync, chmodSync, chownSync, readFileSync, existsSync, statSync, rmSync } from "node:fs";
+
+/**
+ * Write the secrets map ({ "<name>": "<token>" }) to `path` as JSON, mode 0640,
+ * owned by uid:gid (root:<service-group>) so the service user reads it and the
+ * agent user (not in that group, dir 0750) cannot. The file provider counterpart
+ * to src/secrets.ts. Never logs a value.
+ */
+export function writeSecretsFile(path, secrets, { uid = 0, gid, mode = 0o640 } = {}) {
+	const json = JSON.stringify(secrets, null, "\t") + "\n";
+	writeFileSync(path, json, { mode });
+	chmodSync(path, mode);
+	if (gid !== undefined) chownSync(path, uid, gid);
+}
+
+/**
+ * Read an existing secrets file so an upgrade preserves tokens the operator isn't
+ * re-entering. Returns {} if the file is absent or unreadable.
+ */
+export function readSecretsFile(path) {
+	if (!existsSync(path)) return {};
+	try {
+		const v = JSON.parse(readFileSync(path, "utf8"));
+		if (!v || typeof v !== "object" || Array.isArray(v)) return {};
+		// Keep only non-empty string values — a non-string (number/object) must never
+		// be treated as a token (it would crash encryption or be written back invalid).
+		const out = {};
+		for (const [name, val] of Object.entries(v)) if (typeof val === "string" && val.length > 0) out[name] = val;
+		return out;
+	} catch {
+		return {};
+	}
+}
+
+/**
+ * Remove a plaintext secrets file — used when the operator switches to the
+ * systemd-creds provider, so the tokens don't linger on disk and defeat
+ * "encrypted at rest". Best-effort zero-overwrite before unlink. No-op if absent.
+ */
+export function removeSecretsFile(path) {
+	if (!existsSync(path)) return;
+	try {
+		writeFileSync(path, Buffer.alloc(statSync(path).size, 0));
+	} catch {
+		// overwrite is best-effort; unlink still happens below
+	}
+	rmSync(path, { force: true });
+}
+
+const SAFE_CRED_NAME = /^[A-Za-z0-9._-]+$/;
+
+/**
+ * Constrain a credential name to a safe charset — it becomes a `.cred` filename
+ * and is interpolated into a systemd drop-in line written as root, so a name with
+ * path separators, "..", colons, or control characters must be rejected.
+ */
+export function assertSafeCredName(name) {
+	if (name === "." || name === ".." || !SAFE_CRED_NAME.test(name)) {
+		throw new Error(`gh-broker: unsafe credential name "${name}" (allowed: letters, digits, ".", "_", "-")`);
+	}
+	return name;
+}
+
+/**
+ * The distinct cred names a config's owners + app reference (strips the "cred:"
+ * prefix). Validates each name — this is the single source feeding the encrypted
+ * `.cred` filenames and the systemd drop-in, so hardening here covers both.
+ */
+export function referencedCredNames(config) {
+	const names = new Set();
+	const add = (ref) => {
+		if (typeof ref === "string" && ref.startsWith("cred:")) names.add(assertSafeCredName(ref.slice("cred:".length)));
+	};
+	for (const owner of Object.values(config.owners ?? {})) {
+		add(owner.read);
+		add(owner.write);
+	}
+	if (config.app) add(config.app.privateKey);
+	return [...names];
+}
+
+/**
+ * Works out which secrets backend an EXISTING install already uses, so a re-run keeps it
+ * instead of asking again. Precedence: the provider recorded in the deployed config, then
+ * what is actually on disk (encrypted `.cred` files → systemd-creds; tokens in the secrets
+ * file → file). Returns undefined when it is a first install, or when both backends have
+ * credentials and nothing is recorded (ambiguous — the caller should ask).
+ *
+ * @param {{ configured?: unknown, credNames?: string[], fileTokenNames?: string[] }} found
+ * @returns {"systemd-creds" | "file" | undefined}
+ */
+export function detectSecretsProvider({ configured, credNames = [], fileTokenNames = [] } = {}) {
+	if (configured === "systemd-creds" || configured === "file") return configured;
+	const hasCreds = credNames.length > 0;
+	const hasFile = fileTokenNames.length > 0;
+	if (hasCreds && !hasFile) return "systemd-creds";
+	if (hasFile && !hasCreds) return "file";
+	return undefined;
+}