@cldmv/gh-broker 0.0.0-stage → 0.8.0

package/deploy/install.mjs

@@ -0,0 +1,409 @@
+#!/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-31T12:58:15-07:00 (1793476695)
+ *	-----
+ *	@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
+ * layering, 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, ensureDropDir
+} from "./lib/system.mjs";
+import { promptLine, promptHidden, confirm, choose } from "./lib/prompt.mjs";
+import { buildConfig, readOperatorConfig, secretsBlock } from "./lib/config-merge.mjs";
+import { writeSecretsFile, readSecretsFile, removeSecretsFile, referencedCredNames, optionalCredNames, detectSecretsProvider } from "./lib/secret-store.mjs";
+import { parseArgs, NPM_SCOPE } from "./lib/install-args.mjs";
+import { credentialPlan } from "./lib/credentials.mjs";
+import { smokeTest } from "./lib/smoke.mjs";
+import { createNpmToken } from "./lib/npm-setup.mjs";
+import { hostname } from "node:os";
+
+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
+  --secret <name>=<tok>   one token on the command line (repeatable). Visible in
+                          the process list and shell history: prefer the file or env
+  --create-agent-user     create the agent user if missing (no confirm)
+  --npm                   set up the npm integration (npm_scaffold), or rotate its
+                          token: walks through an npm web login and creates the token
+  --npm-scope <@scope>    scope npm_scaffold may create packages in (repeatable;
+                          default: the existing setting, else @<first owner>)
+  --npm-org <org>         also grant the new npm token org read-write on <org>
+                          (repeatable; default: the existing setting, else none)
+  --npm-token-days <n>    lifetime of a newly created npm token (default 90)
+  -y, --non-interactive   never prompt; fail if a value/decision is missing
+
+Config (layered, lowest to highest: shipped defaults, the deployed config, --config,
+these flags). An upgrade run with none of them keeps the deployed owners and ghcr as is.
+  --config <file>         JSON config file in the deployed config's shape, merged on top
+                          of the deployed one. Holds only "cred:" refs, never tokens;
+                          no "tools" (the allowlist ships with the code)
+  --owner <org>           GitHub owner (user or org) to serve; reads use cred:<org>-read,
+                          writes cred:<org>-write (repeatable). A first install with no
+                          owner asks for one, or fails under --non-interactive
+  --installation-id <org>=<id>
+                          GitHub App installation id for an owner (repeatable)
+  --default-owner <org>   owner whose read token serves calls that name no owner
+                          (a first install with a single owner defaults to it)
+  --listen <unix:path>    socket the broker listens on
+  --upstream <url>        GitHub hosted MCP base URL
+  --app-id <n>            GitHub App id (App-token-only verbs)
+  --app-private-key <cred-name>
+                          credential holding the App private key (default gh-app-key)
+  --secrets-path <path>   secrets file location for --secrets-provider file
+  --npm-registry <url>    npm registry for npm_scaffold (https; with --npm)
+  --ghcr-owner <org>      enable GHCR pushes for <org>; its classic PAT is cred:<org>-packages
+  --ghcr-username <login> GitHub login that owns that PAT (needs --ghcr-owner)
+  --ghcr-image <glob>     image name or glob the owner may push, e.g. app or app-* (repeatable)
+  --ghcr-drop-dir <path>  directory archives are read from (default /srv/gh-broker/ghcr-drop)
+  --ghcr-max-archive-bytes <n>
+                          largest archive accepted (default 16 GiB)
+  --protect-release-tags, --no-protect-release-tags
+                          refuse (or allow) overwriting 1.2.3 / v1.2.3 tags (default: refuse)
+  Several GHCR owners, or any other detail, go in a --config file.
+  -h, --help              this help
+
+Credentials: each token comes from, in order, --secret, --secrets-file, env
+GH_BROKER_SECRET_<NAME> (NAME upper-cased, non-alnum -> _), and otherwise an
+interactive prompt (input hidden). A token supplied by any of the first three
+replaces a stored one (rotation). Optional tokens (npm-token) can be skipped.
+Example (unattended):
+  sudo GH_BROKER_SECRET_ACME_READ=… GH_BROKER_SECRET_ACME_WRITE=… \\
+    /usr/local/bin/node deploy/install.mjs --agent-user repo --owner acme \\
+    --secrets-provider systemd-creds --non-interactive`;
+
+const NPM_TOKEN_REF = "cred:npm-token";
+
+/** parseArgs with installer-style failure (the parser itself throws). */
+function parseArgsOrDie(argv) {
+	try {
+		return parseArgs(argv);
+	} catch (err) {
+		die(err.message);
+	}
+}
+
+async function main() {
+	const opts = parseArgsOrDie(process.argv.slice(2));
+	if (opts.help) {
+		log(HELP);
+		return;
+	}
+	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>" }`);
+	}
+
+	let operatorFile;
+	if (opts.configFile) {
+		try {
+			operatorFile = readOperatorConfig(opts.configFile, (f) => readFileSync(f, "utf8"));
+		} catch (err) {
+			die(err.message);
+		}
+	}
+
+	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 (example + deployed + --config + flags)");
+	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
+	let merged;
+	try {
+		const built = await buildConfig({ example, current, file: operatorFile, opts, nonInteractive: opts.nonInteractive, ask: promptLine });
+		merged = built.config;
+		for (const n of built.notes) log(`  ${n}`);
+	} catch (err) {
+		die(err.message);
+	}
+	if (merged.ghcr?.dropDir) {
+		ensureDropDir(merged.ghcr.dropDir, agentUser, SVC_GROUP);
+		log(`  ghcr drop dir: ${merged.ghcr.dropDir} (2750 ${agentUser}:${SVC_GROUP})`);
+	}
+
+	// --- npm integration (npm_scaffold): opt-in ---
+	// Offered on a first interactive install; afterwards `--npm` enables it or, when it is
+	// already enabled, rotates the token. Either way a new token is created by driving the
+	// npm web login + token creation from here (see lib/npm-setup.mjs), unless the operator
+	// supplied one through --secrets-file/env.
+	step("npm integration");
+	let npmMint = false;
+	if (opts.npm || (!merged.npm && current === null && !opts.nonInteractive && (await confirm("Enable npm_scaffold (create new npm packages and their trusted publishers)?")))) {
+		let scopes = opts.npmScopes.length ? opts.npmScopes : merged.npm?.scopes;
+		if (!scopes?.length) {
+			const fallback = `@${Object.keys(merged.owners ?? {})[0] ?? ""}`.toLowerCase();
+			const answer = opts.nonInteractive ? fallback : (await promptLine(`  npm scope(s) to allow, comma-separated [${fallback}]: `)) || fallback;
+			scopes = answer.split(",").map((s) => s.trim()).filter(Boolean);
+		}
+		for (const s of scopes) if (!NPM_SCOPE.test(s)) die(`npm scope must be a lowercase npm scope like "@acme", got "${s}"`);
+		const tokenOrgs = opts.npmOrgs.length ? opts.npmOrgs : (merged.npm?.tokenOrgs ?? []);
+		merged.npm = { ...(merged.npm ?? {}), token: merged.npm?.token ?? NPM_TOKEN_REF, scopes, ...(opts.npmRegistry ? { registry: opts.npmRegistry } : {}) };
+		if (tokenOrgs.length) merged.npm.tokenOrgs = tokenOrgs;
+		else delete merged.npm.tokenOrgs;
+		npmMint = true;
+		log(`  ${current?.npm ? "rotating the npm token" : "enabling"} for ${scopes.join(", ")}${tokenOrgs.length ? ` (plus org read-write on ${tokenOrgs.join(", ")})` : ""}`);
+	} else {
+		log(merged.npm ? `  enabled for ${merged.npm.scopes.join(", ")} (rotate the token with --npm)` : "  not enabled (enable with --npm)");
+	}
+	const npmTokenName = merged.npm?.token?.startsWith("cred:") ? merged.npm.token.slice("cred:".length) : undefined;
+
+	// --- secrets: operator chooses the backend, then tokens are stored in it ---
+	step("secrets");
+	const needed = referencedCredNames(merged);
+	const optional = new Set(optionalCredNames(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}`);
+	try {
+		merged.secrets = secretsBlock(provider, merged.secrets);
+	} catch (err) {
+		die(err.message);
+	}
+
+	// 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;
+
+	let plan;
+	try {
+		plan = credentialPlan({
+			needed,
+			optional,
+			cliSecrets: opts.cliSecrets,
+			imported: importTokens ?? {},
+			env: process.env,
+			existingFile,
+			decrypt: (name) => trySystemdCredDecrypt(name, join(credsDir, `${name}.cred`)),
+			mints: (name) => name === npmTokenName && npmMint,
+			mint: async (name) => {
+				try {
+					const out = await createNpmToken({
+						...(merged.npm.registry ? { registry: merged.npm.registry } : {}),
+						scopes: merged.npm.scopes,
+						...(merged.npm.tokenOrgs?.length ? { orgs: merged.npm.tokenOrgs } : {}),
+						tokenName: `gh-broker ${hostname()} ${new Date().toISOString().slice(0, 10)}`,
+						...(opts.npmTokenDays ? { days: opts.npmTokenDays } : {}),
+						promptHidden,
+						log
+					});
+					log(`  ${name}: created${out.expires ? ` (expires ${out.expires.slice(0, 10)})` : ""}`);
+					return out.token;
+				} catch (err) {
+					throw new Error(`npm token setup failed: ${err.message}`);
+				}
+			},
+			appKeyName,
+			nonInteractive: opts.nonInteractive,
+			promptHidden,
+			log
+		});
+
+		if (provider === "systemd-creds") {
+			ensureCredsDir(configDir, SVC_GROUP);
+			const stored = await plan.storeSystemd({
+				exists: (name) => existsSync(join(credsDir, `${name}.cred`)),
+				encrypt: (name, value) => systemdCredsEncrypt(name, value, join(credsDir, `${name}.cred`))
+			});
+			writeCredsDropin(stored, 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 {
+			writeSecretsFile(paths.secrets, await plan.storeFile(), { gid: requireGid(SVC_GROUP) });
+			removeCredsDropin(); // no systemd-creds delivery under the file provider
+		}
+	} catch (err) {
+		die(err.message);
+	}
+	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,214 @@
+/**
+ *
+ *	@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-11-01T00:40:44-07:00 (1793518844)
+ *	-----
+ *	@Copyright: Copyright (c) 2013-2026 Catalyzed Motivation Inc. All rights reserved.
+ *
+ */
+
+/**
+ * Build the deployed config from four layers, lowest to highest precedence:
+ *
+ *   1. example defaults  — config.example.json: `listen`, `upstream` and the `tools` allowlist.
+ *   2. deployed config   — what is already on the host (the previous install's result).
+ *   3. --config file     — an operator config file, same shape as the deployed config.
+ *   4. CLI flags         — one flag per setting (--owner, --listen, --ghcr-owner, ...).
+ *
+ * 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.
+ *   - Everything else is operator data and the deployed copy wins over the example: `listen`,
+ *     `upstream`, `defaultOwner`, `owners`, `ghcr`, `app`, `secrets`, `npm`. 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
+ *     replaced, `owners` and `ghcr.owners` are merged per owner (and per field within an owner),
+ *     and the other blocks (`app`, `secrets`, `npm`, the `ghcr` scalars) are merged per field.
+ *     An upgrade run without flags therefore keeps the deployed owners and `ghcr` untouched.
+ *
+ * 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.
+ */
+export const DEFAULT_GHCR_DROP_DIR = "/srv/gh-broker/ghcr-drop";
+
+const OPERATOR_KEYS = ["listen", "upstream", "defaultOwner", "owners", "app", "secrets", "npm", "ghcr"];
+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/;
+
+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: operator data. Current entries win per owner; any the example ships are kept.
+	out.owners = { ...(example.owners ?? {}), ...(current.owners ?? {}) };
+
+	// optional blocks: current wins if present.
+	for (const k of ["app", "secrets", "npm", "ghcr"]) {
+		if (current[k] !== undefined) out[k] = structuredClone(current[k]);
+	}
+
+	return out;
+}
+
+/**
+ * Lay `overlay` (a --config file or the flags' config fragment) on top of `base`. `tools` in the
+ * overlay is ignored here (readOperatorConfig refuses it earlier). Returns a new object.
+ */
+export function layerConfig(base, overlay) {
+	const out = structuredClone(base);
+	for (const k of ["listen", "upstream", "defaultOwner"]) {
+		if (overlay[k] !== undefined) out[k] = overlay[k];
+	}
+	for (const k of ["app", "secrets", "npm"]) {
+		if (overlay[k] !== undefined) out[k] = { ...(out[k] ?? {}), ...structuredClone(overlay[k]) };
+	}
+	if (overlay.owners !== undefined) {
+		out.owners = { ...(out.owners ?? {}) };
+		for (const [name, creds] of Object.entries(overlay.owners)) out.owners[name] = { ...(out.owners[name] ?? {}), ...creds };
+	}
+	if (overlay.ghcr !== undefined) {
+		const { owners: ghcrOwners, ...scalars } = overlay.ghcr;
+		const merged = { ...(out.ghcr ?? {}), ...structuredClone(scalars) };
+		if (ghcrOwners !== undefined) {
+			merged.owners = { ...(merged.owners ?? {}) };
+			for (const [name, o] of Object.entries(ghcrOwners)) merged.owners[name] = { ...(merged.owners[name] ?? {}), ...structuredClone(o) };
+		}
+		out.ghcr = merged;
+	}
+	return out;
+}
+
+/** The config fragment the CLI flags describe (same shape as a config file), or {} when none were given. */
+export function overlayFromFlags(opts) {
+	const o = {};
+	if (opts.listen !== undefined) o.listen = opts.listen;
+	if (opts.upstream !== undefined) o.upstream = opts.upstream;
+	if (opts.defaultOwner !== undefined) o.defaultOwner = opts.defaultOwner;
+	for (const org of opts.owners ?? []) (o.owners ??= {})[org] = { read: `cred:${org}-read`, write: `cred:${org}-write` };
+	for (const [org, id] of Object.entries(opts.installationIds ?? {})) ((o.owners ??= {})[org] ??= {}).installationId = id;
+	if (opts.appId !== undefined) o.app = { appId: opts.appId, privateKey: `cred:${opts.appPrivateKey ?? "gh-app-key"}` };
+	if (opts.secretsPath !== undefined) o.secrets = { path: opts.secretsPath };
+	const g = {};
+	if (opts.ghcrDropDir !== undefined) g.dropDir = opts.ghcrDropDir;
+	if (opts.ghcrMaxArchiveBytes !== undefined) g.maxArchiveBytes = opts.ghcrMaxArchiveBytes;
+	if (opts.protectReleaseTags !== undefined) g.protectReleaseTags = opts.protectReleaseTags;
+	if (opts.ghcrOwner !== undefined) {
+		g.owners = { [opts.ghcrOwner]: { username: opts.ghcrUsername, credential: `cred:${opts.ghcrOwner}-packages`, images: [...opts.ghcrImages] } };
+	}
+	if (Object.keys(g).length) o.ghcr = g;
+	return o;
+}
+
+/**
+ * Parse an operator --config file. It must be a JSON object in the deployed config's shape, with
+ * no `tools` (the allowlist ships with the code), no unknown top-level keys and no token values.
+ * `read` is the file reader (injected so the check is testable). Throws on any problem.
+ */
+export function readOperatorConfig(path, read) {
+	let raw;
+	try {
+		raw = JSON.parse(read(path));
+	} catch (err) {
+		throw new Error(`--config: cannot read/parse ${path}: ${err.message}`);
+	}
+	if (!isObject(raw)) throw new Error(`--config: ${path} must be a JSON object`);
+	if (raw.tools !== undefined) throw new Error("--config: `tools` is the shipped allowlist and cannot be set from a config file");
+	const unknown = Object.keys(raw).filter((k) => !OPERATOR_KEYS.includes(k));
+	if (unknown.length) throw new Error(`--config: unknown key(s) ${unknown.join(", ")} (allowed: ${OPERATOR_KEYS.join(", ")})`);
+	const hit = findTokenShape(raw, "");
+	if (hit) throw new Error(`--config: ${hit} looks like a token. The config holds only "cred:<name>" references; pass the token with --secret, --secrets-file or env`);
+	return raw;
+}
+
+/** Path of the first string in `v` shaped like a token, or undefined. */
+function findTokenShape(v, where) {
+	if (typeof v === "string") return TOKEN_SHAPE.test(v) ? where : undefined;
+	if (Array.isArray(v)) {
+		for (let i = 0; i < v.length; i++) {
+			const hit = findTokenShape(v[i], `${where}[${i}]`);
+			if (hit) return hit;
+		}
+	} else if (isObject(v)) {
+		for (const [k, x] of Object.entries(v)) {
+			const hit = findTokenShape(x, where ? `${where}.${k}` : k);
+			if (hit) return hit;
+		}
+	}
+	return undefined;
+}
+
+/**
+ * The full pipeline: example -> deployed -> --config file -> flags, then the first-install
+ * fix-ups. Returns { config, notes }.
+ *
+ * @param {object} o
+ * @param {object} o.example           parsed config.example.json
+ * @param {object | null} o.current    the deployed config, or null on a first install
+ * @param {object | undefined} o.file  a parsed operator --config file (see readOperatorConfig)
+ * @param {object} o.opts              parsed installer flags
+ * @param {boolean} o.nonInteractive
+ * @param {(q: string) => Promise<string>} o.ask  visible prompt, used only when no owner exists
+ */
+export async function buildConfig({ example, current, file, opts, nonInteractive, ask }) {
+	const notes = [];
+	let config = mergeConfig(example, current);
+	if (file) config = layerConfig(config, file);
+	config = layerConfig(config, overlayFromFlags(opts));
+	config.owners ??= {};
+
+	if (Object.keys(config.owners).length === 0) {
+		if (nonInteractive) {
+			throw new Error("no GitHub owner configured — pass --owner <org> (repeatable) or --config <file> with an owners block");
+		}
+		const name = (await ask("GitHub owner (user or org) the broker serves, e.g. your-org: ")).trim().toLowerCase();
+		if (!/^[a-z0-9](?:[a-z0-9-]{0,38})$/.test(name)) throw new Error(`"${name}" is not a valid GitHub owner name — or pass --owner <org>`);
+		config.owners[name] = { read: `cred:${name}-read`, write: `cred:${name}-write` };
+	}
+	for (const [name, creds] of Object.entries(config.owners)) {
+		if (typeof creds.read !== "string" || typeof creds.write !== "string") {
+			throw new Error(`owner "${name}" has no credentials — add it with --owner ${name}, or give "read" and "write" cred refs in --config`);
+		}
+	}
+
+	const names = Object.keys(config.owners);
+	if (current === null && config.defaultOwner === undefined && names.length === 1) {
+		config.defaultOwner = names[0];
+		notes.push(`defaultOwner set to "${names[0]}" (the only owner); change it with --default-owner`);
+	}
+
+	if (config.ghcr && config.ghcr.dropDir === undefined) {
+		config.ghcr.dropDir = DEFAULT_GHCR_DROP_DIR;
+		notes.push(`ghcr.dropDir defaulted to ${DEFAULT_GHCR_DROP_DIR} (change it with --ghcr-drop-dir)`);
+	}
+	return { config, notes };
+}
+
+/**
+ * The `secrets` block for the chosen provider. A `path` only belongs to the "file" provider, and
+ * the loader refuses the combination, so refuse it here before any credential is written.
+ */
+export function secretsBlock(provider, existing) {
+	if (existing?.path && provider !== "file") {
+		throw new Error(`secrets.path (${existing.path}) is only used by the "file" provider — use --secrets-provider file, or drop the path`);
+	}
+	return { provider, ...(existing?.path ? { path: existing.path } : {}) };
+}