@cldmv/gh-broker 0.7.0 → 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/secret-store.mjs

@@ -7,7 +7,7 @@
  *	@Email: <Shinrai@users.noreply.github.com>
  *	-----
  *	@Last modified by: Nate Corcoran <CLDMV> (Shinrai@users.noreply.github.com)
- *	@Last modified time: 2026-10-02T11:30:58-07:00 (1790965858)
+ *	@Last modified time: 2026-10-31T12:12:11-07:00 (1793473931)
  *	-----
  *	@Copyright: Copyright (c) 2013-2026 Catalyzed Motivation Inc. All rights reserved.
  *
@@ -77,7 +77,7 @@ export function assertSafeCredName(name) {
 }
 
 /**
- * The distinct cred names a config's owners + app reference (strips the "cred:"
+ * 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.
  */
@@ -91,9 +91,27 @@ export function referencedCredNames(config) {
 		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

package/deploy/lib/system.mjs

@@ -7,14 +7,14 @@
  *	@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-31T23:26:29-07:00 (1793514389)
  *	-----
  *	@Copyright: Copyright (c) 2013-2026 Catalyzed Motivation Inc. All rights reserved.
  *
  */
 
 import { spawnSync } from "node:child_process";
-import { existsSync, mkdirSync, chmodSync, chownSync, writeFileSync, cpSync, rmSync, symlinkSync, realpathSync } from "node:fs";
+import { existsSync, mkdirSync, chmodSync, chownSync, lstatSync, writeFileSync, cpSync, rmSync, symlinkSync, realpathSync } from "node:fs";
 import { join, dirname } from "node:path";
 
 /** spawnSync wrapper: throws on non-zero unless opts.allowFail. Returns the result. */
@@ -171,9 +171,33 @@ export function currentNodeBin() {
 function mkdirp(path, mode, uid, gid) {
 	if (!existsSync(path)) mkdirSync(path, { recursive: true, mode });
 	chmodSync(path, mode);
+	// Every caller passes a resolved uid and gid (requireUid/requireGid throw otherwise), so the skipped-chown branch is unreachable.
+	/* v8 ignore else */
 	if (uid !== undefined && gid !== undefined) chownSync(path, uid, gid);
 }
 
+/**
+ * Create the GHCR drop directory: `2750 <agentUser>:<svcGroup>`. The agent (owner) writes
+ * archives there; the setgid bit gives every new file the service group, so the broker can
+ * read a group-readable archive while other users can't see in. A missing parent is created
+ * `0755 root:root`; an existing parent is never chmod-ed. Refuses a symlink at the path.
+ */
+export function ensureDropDir(path, agentUser, svcGroup) {
+	const parent = dirname(path);
+	if (!existsSync(parent)) mkdirSync(parent, { recursive: true, mode: 0o755 });
+	let st;
+	try {
+		st = lstatSync(path); // lstat: a symlink (even a dangling one) is seen as itself
+	} catch {
+		st = undefined;
+	}
+	if (!st) mkdirSync(path, { mode: 0o750 });
+	else if (st.isSymbolicLink()) throw new Error(`gh-broker install: ${path} is a symlink — refusing to use it as the GHCR drop dir`);
+	else if (!st.isDirectory()) throw new Error(`gh-broker install: ${path} exists and is not a directory`);
+	chownSync(path, requireUid(agentUser), requireGid(svcGroup));
+	chmodSync(path, 0o2750); // after chown: chown clears the setgid bit
+}
+
 /** Create /etc/gh-broker (0750 root:group) and /opt/gh-broker (0755 svcUser:group). */
 export function ensureDirs(configDir, appDir, svcUser, svcGroup) {
 	const gid = requireGid(svcGroup);