@cldmv/gh-broker 0.7.0 → 0.9.0

package/deploy/install.mjs

@@ -8,7 +8,7 @@
  *	@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)
+ *	@Last modified time: 2026-10-31T12:58:15-07:00 (1793476695)
  *	-----
  *	@Copyright: Copyright (c) 2013-2026 Catalyzed Motivation Inc. All rights reserved.
  *
@@ -17,10 +17,11 @@
 /**
  * gh-broker installer — one command for first install AND upgrade.
  *
- *   sudo node deploy/install.mjs [agent-user] [flags]
+ *   sudo npx @cldmv/gh-broker [agent-user] [flags]   (from npm)
+ *   sudo node deploy/install.mjs [agent-user] [flags] (from a checkout)
  *
  * Prerequisite: node >= 20. Idempotent: re-run to upgrade (config regenerated by
- * merge, existing secrets kept). Interactive by default; pass flags plus
+ * layering, existing secrets kept). Interactive by default; pass flags plus
  * --non-interactive for a single unattended command. See --help and
  * docs/deploy-architecture.md.
  */
@@ -32,12 +33,16 @@ import {
 	ensureServiceUser, createAgentUser, addUserToGroup,
 	pointNodeSymlinks, currentNodeBin, ensureDirs, installUnit,
 	enableService, restartService, serviceActive, deployDist, writeConfigFile,
-	trySystemdCredDecrypt, systemdCredsEncrypt, ensureCredsDir, writeCredsDropin, removeCredsDropin
+	trySystemdCredDecrypt, systemdCredsEncrypt, ensureCredsDir, writeCredsDropin, removeCredsDropin, ensureDropDir
 } 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 { 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";
@@ -64,59 +69,82 @@ function readJson(path) {
 
 const HELP = `gh-broker installer — install and upgrade in one command.
 
-Usage: sudo node deploy/install.mjs [agent-user] [flags]
+Usage: sudo npx @cldmv/gh-broker [agent-user] [flags]     (from npm)
+       sudo node deploy/install.mjs [agent-user] [flags]   (from a checkout)
 
 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
 
-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 -> _).
+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_CLDMV_READ=… GH_BROKER_SECRET_CLDMV_WRITE=… \\
-    /usr/local/bin/node deploy/install.mjs --agent-user repo \\
+  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`;
 
-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);
+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);
 	}
-	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));
+	const opts = parseArgsOrDie(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.
@@ -124,7 +152,16 @@ async function main() {
 		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]");
+	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 npx @cldmv/gh-broker [agent-user] [flags], or sudo node deploy/install.mjs from a checkout");
 	if (process.platform !== "linux") {
 		die(`only Linux is implemented today (platform: ${process.platform}). The path/secret/service seams are ready; the impls are not.`);
 	}
@@ -196,15 +233,53 @@ async function main() {
 	log(`  node symlink -> ${currentNodeBin()} (${linked.join(", ")})`);
 
 	// --- config: merge(example, current) ---
-	step("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
-	const merged = mergeConfig(example, current);
+	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";
@@ -237,77 +312,69 @@ async function main() {
 				);
 	}
 	log(`  backend: ${provider}`);
-	merged.secrets = { provider, ...(merged.secrets?.path ? { path: merged.secrets.path } : {}) };
+	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;
 
-	// 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;
-	};
+	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);
-		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;
+		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)`);
 			}
-			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);
+		} else {
+			writeSecretsFile(paths.secrets, await plan.storeFile(), { gid: requireGid(SVC_GROUP) });
+			removeCredsDropin(); // no systemd-creds delivery under the file provider
 		}
-		writeSecretsFile(paths.secrets, tokens, { gid: requireGid(SVC_GROUP) });
-		removeCredsDropin(); // no systemd-creds delivery under the file provider
+	} catch (err) {
+		die(err.message);
 	}
 	writeConfigFile(paths.config, merged, SVC_GROUP);
 

package/deploy/lib/config-merge.mjs

@@ -7,29 +7,43 @@
  *	@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)
+ *	@Last modified time: 2026-11-01T00:40:44-07:00 (1793518844)
  *	-----
  *	@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.
+ * Build the deployed config from four layers, lowest to highest precedence:
  *
- *   new_config = mergeConfig(example_defaults, current_config)
+ *   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 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.
+ * 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.
  *
- * On a first install (no current), the example is used as-is.
+ * 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);
@@ -44,13 +58,157 @@ export function mergeConfig(example, current) {
 		if (current[k] !== undefined) out[k] = current[k];
 	}
 
-	// owners: current entries win per-owner; example owners not in current are kept.
+	// 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"]) {
-		if (current[k] !== undefined) out[k] = current[k];
+	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 } : {}) };
+}