@cldmv/gh-broker 0.0.0-stage → 0.8.0

package/deploy/lib/credentials.mjs

@@ -0,0 +1,143 @@
+/**
+ *
+ *	@Project: @cldmv/gh-broker
+ *	@Filename: /deploy/lib/credentials.mjs
+ *	@Date: 2026-10-31T12:53:32-07:00 (1793476412)
+ *	@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-31T12:58:15-07:00 (1793476695)
+ *	-----
+ *	@Copyright: Copyright (c) 2013-2026 Catalyzed Motivation Inc. All rights reserved.
+ *
+ */
+
+/**
+ * Where each credential's value comes from, and what gets stored, for the installer's
+ * secrets step. Kept out of install.mjs (which needs root and a systemd host) so the
+ * decisions are testable; the filesystem and systemd operations are passed in.
+ *
+ * Precedence for a value: explicit (--secret, then --secrets-file, then env
+ * GH_BROKER_SECRET_<NAME>) → a newly created npm token (when this run creates one) → the
+ * plaintext secrets file → decrypting an existing .cred → an interactive prompt. An explicit
+ * value, or a newly created token, replaces a stored one (rotation); otherwise a stored value
+ * is kept. Optional credentials (their tools are hidden without them) can be skipped and never
+ * fail the install. Every problem throws; install.mjs reports it and exits.
+ */
+
+import { envSecretKey } from "./install-args.mjs";
+
+/**
+ * @param {object} o
+ * @param {string[]} o.needed                   every cred name the config references
+ * @param {Set<string>} o.optional              the ones that may be missing
+ * @param {Record<string, string>} o.cliSecrets --secret values
+ * @param {Record<string, unknown>} o.imported  --secrets-file contents ({} when none)
+ * @param {Record<string, string | undefined>} o.env
+ * @param {Record<string, string>} o.existingFile current plaintext secrets file ({} when none)
+ * @param {(name: string) => string | undefined} o.decrypt  an existing .cred's value, if any
+ * @param {(name: string) => boolean} o.mints   whether this run creates `name` (the npm token)
+ * @param {(name: string) => Promise<string>} o.mint
+ * @param {string | undefined} o.appKeyName     the App private key (multi-line; can't be prompted)
+ * @param {boolean} o.nonInteractive
+ * @param {(q: string) => Promise<string>} o.promptHidden
+ * @param {(m: string) => void} o.log
+ */
+export function credentialPlan(o) {
+	const unknown = Object.keys(o.cliSecrets).filter((n) => !o.needed.includes(n));
+	if (unknown.length) throw new Error(`--secret names no credential this config uses: ${unknown.join(", ")} (it uses: ${o.needed.join(", ")})`);
+
+	const explicit = (name) => {
+		for (const v of [o.cliSecrets[name], o.imported?.[name], o.env[envSecretKey(name)]]) {
+			if (typeof v === "string" && v) return v;
+		}
+		return undefined;
+	};
+	const minting = (name) => o.mints(name) && explicit(name) === undefined;
+	/** A new value is supplied for this run, so a stored one is replaced. */
+	const replaces = (name) => explicit(name) !== undefined || minting(name);
+
+	/** The value for `name`, or undefined for a skipped optional credential. */
+	const resolve = async (name) => {
+		const given = explicit(name);
+		if (given) return given;
+		if (minting(name)) {
+			if (o.nonInteractive) throw new Error(`creating the npm token needs a browser login and prompts — run interactively, or supply an existing token via --secret, --secrets-file or env ${envSecretKey(name)}`);
+			return o.mint(name);
+		}
+		const fromFile = o.existingFile[name];
+		if (typeof fromFile === "string" && fromFile) return fromFile;
+		const dec = o.decrypt(name);
+		if (dec) {
+			o.log(`  ${name}: migrated from systemd-creds`);
+			return dec;
+		}
+		if (o.optional.has(name)) {
+			if (o.nonInteractive) return undefined;
+			return (await o.promptHidden(`  ${name} (input hidden; Enter to skip — its tools stay hidden): `)) || undefined;
+		}
+		if (o.nonInteractive) throw new Error(`missing credential "${name}" — provide via --secret, --secrets-file or env ${envSecretKey(name)}`);
+		if (name === o.appKeyName) {
+			throw new Error(`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 o.promptHidden(`  ${name} (input hidden): `);
+		if (!entered) throw new Error(`empty value for "${name}"`);
+		return entered;
+	};
+
+	const skipped = (name) => o.log(`  ${name}: not stored — its tools stay hidden until it is (re-run the installer to add it)`);
+	const replacedNote = (name) => {
+		if (minting(name)) o.log(`  note: the previous ${name} is still valid until it expires — revoke it in your npm account's Access Tokens settings`);
+	};
+
+	/**
+	 * systemd-creds backend. Returns the names that end up stored: only those go into the
+	 * LoadCredentialEncrypted= drop-in, since a line for a missing file stops the unit.
+	 * @param {{ exists: (name: string) => boolean, encrypt: (name: string, value: string) => void }} io
+	 */
+	const storeSystemd = async (io) => {
+		const stored = [];
+		for (const name of o.needed) {
+			const existed = io.exists(name);
+			// A plaintext entry (file → creds migration) or a new value re-encrypts; otherwise keep.
+			if (existed && !o.existingFile[name] && !replaces(name)) {
+				o.log(`  ${name}: existing systemd-creds kept`);
+				stored.push(name);
+				continue;
+			}
+			// Only a missing optional cred can resolve to nothing here: a re-encrypt always has a
+			// value (the explicit one, the new npm token, or the plaintext entry).
+			const value = await resolve(name);
+			if (value === undefined) {
+				skipped(name);
+				continue;
+			}
+			io.encrypt(name, value);
+			stored.push(name);
+			o.log(`  ${name}: ${existed ? "rotated" : "encrypted"} (systemd-creds)`);
+			if (existed) replacedNote(name);
+		}
+		return stored;
+	};
+
+	/** file backend: the token map to write. */
+	const storeFile = async () => {
+		const tokens = { ...o.existingFile };
+		for (const name of o.needed) {
+			if (tokens[name] && !replaces(name)) continue;
+			const had = Boolean(tokens[name]);
+			// As above, only a missing optional cred can resolve to nothing.
+			const value = await resolve(name);
+			if (value === undefined) {
+				skipped(name);
+				continue;
+			}
+			tokens[name] = value;
+			if (had) replacedNote(name);
+		}
+		return tokens;
+	};
+
+	return { explicit, replaces, resolve, storeSystemd, storeFile };
+}

package/deploy/lib/install-args.mjs

@@ -0,0 +1,144 @@
+/**
+ *
+ *	@Project: @cldmv/gh-broker
+ *	@Filename: /deploy/lib/install-args.mjs
+ *	@Date: 2026-10-31T12:31:29-07:00 (1793475089)
+ *	@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-01T00:40:47-07:00 (1793518847)
+ *	-----
+ *	@Copyright: Copyright (c) 2013-2026 Catalyzed Motivation Inc. All rights reserved.
+ *
+ */
+
+/**
+ * The installer's command-line parsing, kept apart from install.mjs (which needs root and
+ * a systemd host) so it can be tested. Every problem throws; install.mjs turns that into
+ * its usual fatal message.
+ */
+
+import { assertSafeCredName } from "./secret-store.mjs";
+
+export const NPM_SCOPE = /^@[a-z0-9][a-z0-9._~-]*$/;
+export const NPM_ORG = /^[a-z0-9][a-z0-9._~-]*$/;
+/** A GitHub owner (user or org) name, lowercase, as config.owners keys must be. */
+export const GH_OWNER = /^[a-z0-9](?:[a-z0-9-]{0,38})$/;
+const GH_LOGIN = /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})$/;
+const IMAGE_GLOB = /^[a-z0-9*](?:[a-z0-9._*-]*[a-z0-9*])?(?:\/[a-z0-9*](?:[a-z0-9._*-]*[a-z0-9*])?)*$/;
+
+/** env var that supplies the token for cred `name`: GH_BROKER_SECRET_<NAME>. */
+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: {} };
+	// 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("-")) throw new Error(`${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 === "--secret") {
+			const pair = value(++i, a);
+			const eq = pair.indexOf("=");
+			if (eq <= 0 || eq === pair.length - 1) throw new Error("--secret takes <cred-name>=<token> (see --help)");
+			o.cliSecrets[assertSafeCredName(pair.slice(0, eq))] = pair.slice(eq + 1);
+		} else if (a === "--npm") o.npm = true;
+		else if (a === "--npm-scope") {
+			const s = value(++i, a);
+			if (!NPM_SCOPE.test(s)) throw new Error(`--npm-scope must be a lowercase npm scope like "@cldmv", got "${s}"`);
+			o.npmScopes.push(s);
+		} else if (a === "--npm-org") {
+			const org = value(++i, a);
+			if (!NPM_ORG.test(org)) throw new Error(`--npm-org must be a lowercase npm org name like "cldmv", got "${org}"`);
+			o.npmOrgs.push(org);
+		} else if (a === "--npm-token-days") {
+			const days = value(++i, a);
+			if (!/^[1-9][0-9]{0,2}$/.test(days)) throw new Error("--npm-token-days must be a whole number of days");
+			o.npmTokenDays = Number(days);
+		} else if (a === "--config") o.configFile = value(++i, a);
+		else if (a === "--owner") {
+			const org = value(++i, a);
+			if (!GH_OWNER.test(org)) throw new Error(`--owner must be a lowercase GitHub owner name like "acme", got "${org}"`);
+			(o.owners ??= []).push(org);
+		} else if (a === "--installation-id") {
+			const pair = value(++i, a);
+			const eq = pair.indexOf("=");
+			const org = pair.slice(0, eq);
+			const id = pair.slice(eq + 1);
+			if (eq <= 0 || !GH_OWNER.test(org) || !/^[1-9][0-9]{0,14}$/.test(id)) throw new Error("--installation-id takes <owner>=<numeric id> (see --help)");
+			(o.installationIds ??= {})[org] = Number(id);
+		} else if (a === "--default-owner") {
+			const org = value(++i, a);
+			if (!GH_OWNER.test(org)) throw new Error(`--default-owner must be a lowercase GitHub owner name like "acme", got "${org}"`);
+			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}"`);
+			o.listen = addr;
+		} else if (a === "--upstream") {
+			const url = value(++i, a);
+			if (!/^https?:\/\/\S+$/.test(url)) throw new Error(`--upstream must be an http(s) URL, got "${url}"`);
+			o.upstream = url;
+		} else if (a === "--app-id") {
+			const id = value(++i, a);
+			if (!/^[1-9][0-9]{0,14}$/.test(id)) throw new Error("--app-id must be the numeric GitHub App id");
+			o.appId = Number(id);
+		} else if (a === "--app-private-key") o.appPrivateKey = assertSafeCredName(value(++i, a).replace(/^cred:/, ""));
+		else if (a === "--secrets-path") {
+			const path = value(++i, a);
+			if (!path.startsWith("/")) throw new Error(`--secrets-path must be an absolute path, got "${path}"`);
+			o.secretsPath = path;
+		} else if (a === "--npm-registry") {
+			const url = value(++i, a);
+			if (!/^https:\/\/\S+$/.test(url)) throw new Error(`--npm-registry must be an https URL, got "${url}"`);
+			o.npmRegistry = url;
+		} else if (a === "--ghcr-owner") {
+			const org = value(++i, a);
+			if (!GH_OWNER.test(org)) throw new Error(`--ghcr-owner must be a lowercase GitHub owner name like "acme", got "${org}"`);
+			o.ghcrOwner = org;
+		} else if (a === "--ghcr-username") {
+			const login = value(++i, a);
+			if (!GH_LOGIN.test(login)) throw new Error(`--ghcr-username must be a GitHub login, got "${login}"`);
+			o.ghcrUsername = login;
+		} else if (a === "--ghcr-image") {
+			const img = value(++i, a);
+			if (img.length > 255 || !IMAGE_GLOB.test(img)) throw new Error(`--ghcr-image must be a lowercase image name or glob like "app" or "app-*", got "${img}"`);
+			(o.ghcrImages ??= []).push(img);
+		} else if (a === "--ghcr-drop-dir") {
+			const dir = value(++i, a);
+			if (!dir.startsWith("/")) throw new Error(`--ghcr-drop-dir must be an absolute path, got "${dir}"`);
+			o.ghcrDropDir = dir;
+		} else if (a === "--ghcr-max-archive-bytes") {
+			const n = value(++i, a);
+			if (!/^[1-9][0-9]{0,15}$/.test(n) || !Number.isSafeInteger(Number(n))) throw new Error("--ghcr-max-archive-bytes must be a positive whole number of bytes");
+			o.ghcrMaxArchiveBytes = Number(n);
+		} else if (a === "--protect-release-tags") o.protectReleaseTags = true;
+		else if (a === "--no-protect-release-tags") o.protectReleaseTags = false;
+		else if (a.startsWith("-")) throw new Error(`unknown flag: ${a} (see --help)`);
+		else o.positional.push(a);
+	}
+	if (o.provider !== undefined && o.provider !== "systemd-creds" && o.provider !== "file") {
+		throw new Error(`--secrets-provider must be "systemd-creds" or "file"`);
+	}
+	if (o.npmRegistry !== undefined && !o.npm) throw new Error("--npm-registry only applies together with --npm");
+	if (o.appPrivateKey !== undefined && o.appId === undefined) throw new Error("--app-private-key needs --app-id");
+	if (o.ghcrOwner !== undefined && (o.ghcrUsername === undefined || !o.ghcrImages)) {
+		throw new Error("--ghcr-owner needs --ghcr-username and at least one --ghcr-image");
+	}
+	if (o.ghcrOwner === undefined && (o.ghcrUsername !== undefined || o.ghcrImages)) {
+		throw new Error("--ghcr-username and --ghcr-image need --ghcr-owner (several GHCR owners go in a --config file)");
+	}
+	return o;
+}

package/deploy/lib/npm-setup.mjs

@@ -0,0 +1,164 @@
+/**
+ *
+ *	@Project: @cldmv/gh-broker
+ *	@Filename: /deploy/lib/npm-setup.mjs
+ *	@Date: 2026-10-31T10:58:54-07:00 (1793469534)
+ *	@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-31T12:58:17-07:00 (1793476697)
+ *	-----
+ *	@Copyright: Copyright (c) 2013-2026 Catalyzed Motivation Inc. All rights reserved.
+ *
+ */
+
+/**
+ * Creates the npm granular access token npm_scaffold uses, the way the npm CLI would, so the
+ * installer can drive it end to end:
+ *
+ *   1. web login     POST /-/v1/login → show the login URL, poll the done URL until approved
+ *                    (what `npm login --auth-type=web` does). Yields a short-lived session.
+ *   2. token create  POST /-/npm/v1/tokens with the account password and an OTP, both
+ *                    prompted for and held only for that request (what `npm token create`
+ *                    does). Scope read-write, an expiry, and NO 2FA bypass, so the token
+ *                    cannot write anything without a fresh OTP.
+ *   3. cleanup       DELETE /-/user/token/<session>, on every path (what `npm logout` does).
+ *
+ * Nothing here logs or returns the password, the OTP or the session token; the new token is
+ * returned to the caller, which stores it in the secret backend.
+ */
+
+export const DEFAULT_NPM_REGISTRY = "https://registry.npmjs.org";
+export const DEFAULT_TOKEN_DAYS = 90;
+const MAX_ATTEMPTS = 3;
+
+const isHttpsUrl = (u) => {
+	try {
+		return new URL(u).protocol === "https:";
+	} catch {
+		return false;
+	}
+};
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+async function readJson(res) {
+	const text = await res.text();
+	try {
+		return JSON.parse(text);
+	} catch {
+		return { _raw: text.slice(0, 300) };
+	}
+}
+
+const detail = (body) => {
+	const msg = [body?.error, body?.message, body?.reason, body?._raw].find((v) => typeof v === "string" && v);
+	return msg ? `: ${msg.slice(0, 300)}` : "";
+};
+
+/** npm's own signal for "this request needs a (valid) OTP": a 401 naming otp. */
+export function wantsOtp(res, body) {
+	if (res.status !== 401) return false;
+	const auth = (res.headers.get("www-authenticate") ?? "").toLowerCase();
+	return auth.includes("otp") || /one-time pass/i.test(JSON.stringify(body ?? ""));
+}
+
+/**
+ * @param {object} o
+ * @param {string} [o.registry]
+ * @param {string[]} o.scopes                  e.g. ["@cldmv"]
+ * @param {string[]} [o.orgs]                  npm orgs to also grant read-write on (org permission)
+ * @param {string} o.tokenName                 shown in the npm token list
+ * @param {number} [o.days]                    token lifetime
+ * @param {(q: string) => Promise<string>} o.promptHidden
+ * @param {(m: string) => void} o.log
+ * @param {typeof fetch} [o.fetch]
+ * @param {number} [o.pollTimeoutMs]           how long to wait for the browser approval
+ * @returns {Promise<{ token: string, expires?: string }>}
+ */
+export async function createNpmToken(o) {
+	const registry = (o.registry ?? DEFAULT_NPM_REGISTRY).replace(/\/+$/, "");
+	const doFetch = o.fetch ?? globalThis.fetch;
+	const days = o.days ?? DEFAULT_TOKEN_DAYS;
+	const session = await webLogin(registry, doFetch, o);
+	try {
+		return await createToken(registry, doFetch, session, { ...o, days });
+	} finally {
+		try {
+			const res = await doFetch(`${registry}/-/user/token/${encodeURIComponent(session)}`, {
+				method: "DELETE",
+				headers: { authorization: `Bearer ${session}`, "npm-command": "logout" }
+			});
+			o.log(res.status >= 200 && res.status < 300 ? "  npm login session revoked" : `  note: could not revoke the npm login session (HTTP ${res.status}); it expires on its own`);
+		} catch (err) {
+			o.log(`  note: could not revoke the npm login session (${err.message}); it expires on its own`);
+		}
+	}
+}
+
+async function webLogin(registry, doFetch, o) {
+	const res = await doFetch(`${registry}/-/v1/login`, {
+		method: "POST",
+		headers: { "content-type": "application/json", accept: "application/json", "npm-auth-type": "web", "npm-command": "login" },
+		body: "{}"
+	});
+	const body = await readJson(res);
+	if (res.status < 200 || res.status >= 300 || !isHttpsUrl(body.loginUrl) || !isHttpsUrl(body.doneUrl)) {
+		throw new Error(`npm web login could not start (HTTP ${res.status})${detail(body)}`);
+	}
+	o.log(`  Log in to npm in a browser (as the account that owns ${o.scopes.join(", ")}):\n\n    ${body.loginUrl}\n\n  Waiting for the login to be approved…`);
+	const deadline = Date.now() + (o.pollTimeoutMs ?? 10 * 60_000);
+	for (;;) {
+		const poll = await doFetch(body.doneUrl, { method: "GET", headers: { accept: "application/json", "npm-command": "login" } });
+		const content = await readJson(poll);
+		if (poll.status === 200) {
+			if (typeof content.token !== "string" || !content.token) throw new Error("npm web login finished without a session");
+			o.log("  npm login approved");
+			return content.token;
+		}
+		if (poll.status !== 202) throw new Error(`npm web login failed (HTTP ${poll.status})${detail(content)}`);
+		if (Date.now() > deadline) throw new Error("npm web login timed out waiting for approval");
+		const retry = Number(poll.headers.get("retry-after"));
+		await sleep(Number.isFinite(retry) && retry > 0 ? retry * 1000 : 1000);
+	}
+}
+
+async function createToken(registry, doFetch, session, o) {
+	let password = await o.promptHidden("  npm account password (input hidden, used once, not stored): ");
+	let otp = await o.promptHidden("  npm one-time password (input hidden): ");
+	const request = {
+		name: o.tokenName,
+		scopes: o.scopes,
+		packages_and_scopes_permission: "read-write",
+		...(o.orgs?.length ? { orgs: o.orgs, orgs_permission: "read-write" } : {}),
+		expires: o.days
+	};
+	for (let attempt = 1; ; attempt++) {
+		const res = await doFetch(`${registry}/-/npm/v1/tokens`, {
+			method: "POST",
+			headers: {
+				authorization: `Bearer ${session}`,
+				"content-type": "application/json",
+				accept: "application/json",
+				"npm-command": "token",
+				...(otp ? { "npm-otp": otp } : {})
+			},
+			body: JSON.stringify({ ...request, password })
+		});
+		const body = await readJson(res);
+		if (res.status >= 200 && res.status < 300) {
+			if (typeof body.token !== "string" || !body.token) throw new Error("npm created a token but did not return it");
+			return { token: body.token, ...(typeof body.expires === "string" ? { expires: body.expires } : {}) };
+		}
+		if (attempt >= MAX_ATTEMPTS) throw new Error(`npm token creation failed (HTTP ${res.status})${detail(body)}`);
+		if (wantsOtp(res, body)) {
+			otp = await o.promptHidden("  npm rejected the one-time password (expired?). New one-time password (input hidden): ");
+		} else if (res.status === 401 || res.status === 403) {
+			password = await o.promptHidden("  npm rejected the password. npm account password (input hidden): ");
+			otp = await o.promptHidden("  npm one-time password (input hidden): ");
+		} else {
+			throw new Error(`npm token creation failed (HTTP ${res.status})${detail(body)}`);
+		}
+	}
+}

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,132 @@
+/**
+ *
+ *	@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-31T12:12:11-07:00 (1793473931)
+ *	-----
+ *	@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 and ghcr owners 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);
+	if (config.npm) add(config.npm.token);
+	for (const owner of Object.values(config.ghcr?.owners ?? {})) add(owner.credential);
+	return [...names];
+}
+
+/**
+ * The referenced cred names that are OPTIONAL: the broker hides the tools that need them
+ * when they aren't stored (src/availability.ts) instead of refusing to start, so the
+ * installer may skip them: the npm token and the GHCR credentials. The owners' PATs and
+ * the App key stay required.
+ */
+export function optionalCredNames(config) {
+	const names = [];
+	const add = (ref) => {
+		if (typeof ref === "string" && ref.startsWith("cred:")) names.push(assertSafeCredName(ref.slice("cred:".length)));
+	};
+	add(config.npm?.token);
+	for (const owner of Object.values(config.ghcr?.owners ?? {})) add(owner.credential);
+	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;
+}