@cldmv/gh-broker 0.0.0-stage → 0.7.0

package/docs/deploy-architecture.md

@@ -0,0 +1,82 @@
+# Deploy architecture
+
+How gh-broker is installed, configured, and upgraded. The guiding goals are **portability** (copy the repo to another machine, run one installer, it works), a **clean upgrade path** (updates never lose operator-set data), and **platform-neutrality** (Linux today, with seams so macOS/Windows are additive later — not a rewrite).
+
+## Config: one portable, token-free file, regenerated by merge
+
+There is a single config file. It is **portable** and **contains no secrets** — only the tool allowlist, owner names, and credential *references* (`"read": "cred:cldmv-read"`). Keeping tokens out of it is what makes it safe to copy, commit, and carry between machines; a file designed to be copied must never hold live credentials.
+
+On install *and* upgrade the deployed config is **regenerated by merging**, not overwritten:
+
+```
+new_config = merge(example_defaults, current_config)
+```
+
+- `example_defaults` — `config.example.json`, shipped with the code. Updated freely on upgrade; this is where new keys and allowlist changes arrive.
+- `current_config` — whatever is already deployed on this machine (absent on a first install).
+
+The merge is **field-level**, because the two halves have different owners:
+
+| Field | Source of truth | Why |
+|---|---|---|
+| `tools` (the allowlist) | **example** (repo) | It is a security control. A removal or tightening in an update must apply; a naive "current wins" would silently keep a tool the repo dropped. |
+| `owners`, `app`, `listen`, `upstream`, `defaultOwner` | **current** (deployed), falling back to example | Deployment data the operator set. Preserved across upgrades; new owners from the example are added, existing ones kept as-is. |
+
+So an upgrade brings new defaults and allowlist changes through the example, while everything the operator configured survives. Nothing is blindly clobbered.
+
+## Secrets: separate, agent-unreadable, and the storage backend is the operator's choice
+
+Secrets never live in the config — the config carries only `cred:<name>` references. The tokens live in a separate store the agent user cannot read, behind a **provider seam** (`config.secrets.provider`) the installer sets from a prompt. Two providers ship:
+
+- **`systemd-creds`** (default, recommended on Linux): tokens are encrypted with a host/TPM-bound key as `.cred` files, delivered by a unit drop-in (`LoadCredentialEncrypted`) into a memory-only `$CREDENTIALS_DIRECTORY` at start. **Encrypted at rest** and resistant to backups/disk theft (the key isn't beside the ciphertext); not portable to another machine.
+- **`file`**: a JSON `{ "<name>": "<token>" }` map at `0640 root:gh-broker` inside the `0750` config dir. **Portable and platform-neutral**; at-rest protection is filesystem permissions only (plaintext on disk).
+
+The **agent-read boundary is identical either way** — it's filesystem permissions (the agent isn't in the `gh-broker` group), not encryption. The choice trades *at-rest protection* (systemd-creds) against *portability* (file); it does not weaken the agent boundary. This is a genuine trade because the daemon must auto-start, so any decryption key must be available without a human at boot — which only a host/TPM-bound key (systemd-creds) achieves without leaving the key beside the ciphertext.
+
+The installer moves tokens between backends without re-entry where it can: switching to `file` decrypts the existing host-bound `.cred` files (as root, same host) into the JSON; switching to `systemd-creds` encrypts the tokens into `.cred` files. It prompts only for tokens it can't find. Further providers (OS keychain, DPAPI, encrypted vault) slot into the same seam without touching the daemon's call sites.
+
+## Paths: resolved, not hardcoded
+
+Neither the config nor the secrets path is hardcoded to `/etc`. Both resolve through the same order:
+
+1. explicit `--config` flag / `GH_BROKER_CONFIG` (and `GH_BROKER_SECRETS`) — highest,
+2. the platform's system config dir — Linux `/etc/gh-broker`, macOS `/Library/Application Support/gh-broker`, Windows `%ProgramData%\gh-broker`,
+3. the packaged default.
+
+Only the Linux defaults are exercised today; the others are wired so a later platform port is a table entry, not surgery.
+
+## Node runtime: a maintained symlink, no runtime resolution
+
+The service runs jailed (`ProtectHome`), so it cannot use a `/home` nvm, and there is no login shell at start. Rather than have the unit *resolve* node at runtime, the installer maintains a **stable symlink** — `/usr/local/bin/node` → the chosen node — and the unit simply runs it:
+
+```
+ExecStart=/usr/local/bin/node /opt/gh-broker/dist/index.mjs --config <resolved>
+```
+
+The symlink is the single indirection: the CLI (via `PATH`) and the service resolve the *same* link, so "CLI node == service node" holds by construction. Bumping node is re-pointing the symlink — which is exactly the node step the installer runs on setup and on update, so it is not a special case. This removes `launch.sh` (a runtime nvm resolver that duplicated the symlink) and keeps the hardened unit free of a `bash`/`nvm` startup dependency.
+
+## Tooling: Node, with one optional shell bootstrap
+
+All install/deploy *logic* is Node (`deploy/install.mjs` + `deploy/lib/*.mjs`): config merge and validation (validation reuses the daemon's own loader via `node dist/index.mjs --check`), the interactive prompts, the privileged system operations (shelled out to `useradd` / `systemctl` / `rsync`), building `dist/`/`node_modules/` as the checkout's own owner via `sudo -u '#<uid>'` rather than leaving them root-owned, and the smoke test (a real MCP client over the socket). One language, testable with the repo's vitest suite.
+
+The only thing that can't be Node is bootstrapping node itself. So the entrypoint is **`sudo node deploy/install.mjs`** with node ≥20 as the one prerequisite — which runs on any platform node runs on. For zero-prerequisite convenience on Linux, an **optional** `deploy/install.sh` (~20 lines) sets up nvm + node + the symlink if node is absent, then `exec`s the Node installer. It is a convenience, not the real installer.
+
+## The installer flow (install and upgrade are the same command)
+
+`sudo node deploy/install.mjs` is idempotent — first install and later upgrade are one command:
+
+1. detect platform + check prerequisites (`socat`, `rsync`, `systemctl`, `sudo`),
+2. **create or confirm the agent user** — hard stop if it can't (no silent warn-and-continue),
+3. ensure node on a stable path + the `/usr/local/bin/node` symlink,
+4. **regenerate the config** via `merge(example, current)`,
+5. **choose the secret backend and store the PATs** — keep existing, migrate a legacy `systemd-creds` token, or take it from `--secrets-file` / env / a prompt (see the Secrets section),
+6. validate the config with the real loader (`node dist/index.mjs --check`),
+7. build + deploy (unit → `/usr/local/bin/node`, `dist/`, config, secrets),
+8. **smoke test** — MCP `initialize` + one real read over the socket → ✅/❌.
+
+The same flow runs **fully unattended** via flags — `--agent-user`, `--secrets-provider`, `--secrets-file` / `GH_BROKER_SECRET_<NAME>`, `--create-agent-user`, `--non-interactive`; prompts are the default when flags are omitted. See [`../deploy/README.md`](../deploy/README.md) and `--help`.
+
+## What is deliberately deferred
+
+- Non-Linux secret providers and path defaults (the seams exist; the implementations are additive).
+- `link_issue` (App-token-only) stays deferred — implemented but not advertised or wired; see [`../deploy/README.md`](../deploy/README.md).

package/package.json

@@ -1,6 +1,72 @@
 {
-  "name": "@cldmv/gh-broker",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@cldmv/gh-broker",
+	"version": "0.7.0",
+	"description": "Local credential-routing MCP proxy: holds per-org GitHub PATs out of the agent's reach, routes by repo owner, exposes a config-driven default-deny toolset in front of GitHub's hosted MCP.",
+	"type": "module",
+	"license": "Apache-2.0",
+	"bin": {
+		"gh-broker": "./dist/index.mjs"
+	},
+	"main": "./dist/index.mjs",
+	"engines": {
+		"node": ">=22.12.0"
+	},
+	"scripts": {
+		"typecheck": "tsc -p tsconfig.json --noEmit",
+		"build": "npm run typecheck && rm -rf dist && esbuild src/index.ts --bundle --platform=node --format=esm --target=node20 --outfile=dist/index.mjs --sourcemap",
+		"start": "node dist/index.mjs",
+		"dev": "node --experimental-strip-types --watch src/index.ts",
+		"build:ci": "npm run build",
+		"test:types": "npm run typecheck",
+		"test": "node tests/run-vitest.mjs",
+		"test:watch": "vitest --config .configs/vitest.config.mjs",
+		"coverage": "node tests/run-vitest.mjs --coverage-quiet",
+		"ci:coverage": "npm run coverage",
+		"fix:headers": "fix-headers --config .configs/fix-headers.json"
+	},
+	"author": {
+		"name": "Shinrai",
+		"company": "CLDMV",
+		"email": "git+npm@cldmv.net",
+		"url": "https://cldmv.net"
+	},
+	"contributors": [
+		{
+			"name": "CLDMV",
+			"url": "https://github.com/CLDMV"
+		}
+	],
+	"funding": {
+		"type": "github",
+		"url": "https://github.com/sponsors/shinrai"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/CLDMV/gh-broker.git"
+	},
+	"bugs": {
+		"url": "https://github.com/CLDMV/gh-broker/issues"
+	},
+	"homepage": "https://github.com/CLDMV/gh-broker#readme",
+	"devDependencies": {
+		"@cldmv/configs": "^1.3.0",
+		"@cldmv/fix-headers": "^2.2.1",
+		"@cldmv/vitest-runner": "^1.5.4",
+		"@types/node": "^26.6.5",
+		"@vitest/coverage-v8": "^5.0.2",
+		"esbuild": "^0.28.2",
+		"typescript": "^6.0.3",
+		"vitest": "^5.0.3"
+	},
+	"dependencies": {
+		"@modelcontextprotocol/sdk": "^1.32.1",
+		"@octokit/auth-app": "^8.3.1",
+		"@octokit/core": "^7.0.8"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"allowScripts": {
+		"esbuild": true
+	}
+}

package/src/appauth.ts

@@ -0,0 +1,56 @@
+/**
+ *
+ *	@Project: @cldmv/gh-broker
+ *	@Filename: /src/appauth.ts
+ *	@Date: 2026-07-07T18:39:48-07:00 (1783474788)
+ *	@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 { Octokit } from "@octokit/core";
+import { createAppAuth } from "@octokit/auth-app";
+import type { Config, SecretStore } from "./types.ts";
+
+/**
+ * Provides per-owner GitHub App–authenticated Octokit clients for the operations
+ * that fine-grained PATs can't do (`link_issue` → addClosingIssueReference, which
+ * is not in the fine-grained-PAT GraphQL schema — only App/classic tokens see it).
+ *
+ * `@octokit/auth-app` handles the JWT signing + installation-token minting/refresh
+ * internally, so there's no hand-rolled token machinery here. The App private key
+ * lives only in the broker (systemd-creds), never in the agent.
+ */
+export class AppAuth {
+	private readonly config: Config;
+	private readonly appId: number;
+	private readonly privateKey: string;
+	private readonly cache = new Map<number, Octokit>();
+
+	constructor(config: Config, secrets: SecretStore) {
+		if (!config.app) throw new Error("AppAuth: no app config");
+		this.config = config;
+		this.appId = config.app.appId;
+		this.privateKey = secrets.resolve(config.app.privateKey);
+	}
+
+	/** App-authed Octokit for this owner's installation, or null if none configured. */
+	octokitFor(owner: string): Octokit | null {
+		const installationId = this.config.owners[owner]?.installationId;
+		if (installationId === undefined) return null;
+		let ok = this.cache.get(installationId);
+		if (!ok) {
+			ok = new Octokit({
+				authStrategy: createAppAuth,
+				auth: { appId: this.appId, privateKey: this.privateKey, installationId }
+			});
+			this.cache.set(installationId, ok);
+		}
+		return ok;
+	}
+}

package/src/audit.ts

@@ -0,0 +1,34 @@
+/**
+ *
+ *	@Project: @cldmv/gh-broker
+ *	@Filename: /src/audit.ts
+ *	@Date: 2026-07-07T00:24:51-07:00 (1783409091)
+ *	@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.
+ *
+ */
+
+/**
+ * Structured audit log. One JSON line per decision/call to stdout (journald
+ * captures it). NEVER include token values — only tool, owner, mode, repo, result.
+ */
+
+export interface AuditEntry {
+	tool: string;
+	owner?: string;
+	mode?: "read" | "write";
+	repo?: string;
+	decision: "forward" | "custom" | "augment" | "deny" | "error";
+	ok?: boolean;
+	detail?: string;
+}
+
+export function audit(entry: AuditEntry): void {
+	// eslint-disable-next-line no-console -- journald is the sink
+	console.log(JSON.stringify({ ts: new Date().toISOString(), ...entry }));
+}

package/src/catalog.ts

@@ -0,0 +1,165 @@
+/**
+ *
+ *	@Project: @cldmv/gh-broker
+ *	@Filename: /src/catalog.ts
+ *	@Date: 2026-07-07T00:24:51-07:00 (1783409091)
+ *	@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-16T17:17:02-07:00 (1792196222)
+ *	-----
+ *	@Copyright: Copyright (c) 2013-2026 Catalyzed Motivation Inc. All rights reserved.
+ *
+ */
+
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import type { Config, SecretStore } from "./types.ts";
+import type { UpstreamPool } from "./upstream.ts";
+// DEFERRED: link_issue (addClosingIssueReference) is App-token-only and not wired in — see docs.
+// import { LINK_ISSUE_SCHEMA } from "./verbs/link_issue.ts";
+import { RESOLVE_REVIEW_THREAD_SCHEMA, REPLY_REVIEW_THREAD_SCHEMA } from "./verbs/review_thread.ts";
+import { REPORT_UNLABELED_SCHEMA } from "./verbs/report_unlabeled.ts";
+import { REPORT_SECURITY_ALERTS_SCHEMA } from "./verbs/report_security_alerts.ts";
+import { REPORT_RELEASE_PRS_SCHEMA } from "./verbs/report_release_prs.ts";
+import { ISSUE_LABELS_SCHEMA } from "./verbs/issue_labels.ts";
+import { REPORT_CI_STATUS_SCHEMA } from "./verbs/report_ci_status.ts";
+
+/**
+ * Build the advertised tool list ONCE at startup. Proxied tools carry their real
+ * schemas fetched from the hosted MCP (tool schemas are owner-independent, so any
+ * valid read token works — we use the first configured owner's read PAT). Custom
+ * verbs carry local schemas. Only allowlisted tools appear; nothing else is
+ * advertised (and, per the router, nothing else is executable either).
+ *
+ * If the upstream fetch fails (network/token), we advertise minimal schemas rather
+ * than fail startup — the daemon still serves and calls still route correctly.
+ */
+export async function buildCatalog(config: Config, secrets: SecretStore, upstream: UpstreamPool): Promise<Tool[]> {
+	const upstreamByName = new Map<string, Tool>();
+	// Whether the upstream tool list was actually fetched. If it wasn't (network/token), we must NOT drop
+	// allowlisted tools — we fall back to minimal schemas so the daemon still serves + routes. But if the
+	// fetch DID succeed, a tool missing from it genuinely isn't served by this upstream (wrong toolset /
+	// renamed), so advertising a minimal-schema stub only defers the failure to call time (the confusing
+	// "could not determine repo owner" → "unknown tool" pair) — better to skip it and say why at startup.
+	let upstreamFetched = false;
+	const firstOwner = Object.values(config.owners)[0];
+	if (firstOwner) {
+		try {
+			const token = secrets.resolve(firstOwner.read);
+			// Never let a slow/unreachable upstream hang startup — fall back to minimal schemas.
+			const timeoutMs = Number(process.env.GH_BROKER_CATALOG_TIMEOUT_MS ?? 10000);
+			const tools = await Promise.race([
+				upstream.listToolsFor(token),
+				new Promise<never>((_, rej) => setTimeout(() => rej(new Error(`timed out after ${timeoutMs}ms`)), timeoutMs).unref())
+			]);
+			for (const t of tools) upstreamByName.set(t.name, t);
+			upstreamFetched = true;
+		} catch (err) {
+			console.error(`catalog: could not fetch upstream tool schemas (${(err as Error).message}) — advertising minimal schemas`);
+		}
+	}
+
+	const tools: Tool[] = [];
+	for (const rule of config.tools) {
+		if (rule.custom) {
+			// DEFERRED: link_issue (App-token-only addClosingIssueReference) is not wired in — see docs.
+			// Intentionally not advertised even if an allowlist entry is added; re-enable by restoring
+			// this branch + the import above + the router dispatch case, then config.app + installationId.
+			if (rule.name === "resolve_review_thread") {
+				tools.push({
+					name: "resolve_review_thread",
+					description:
+						"Resolve (or unresolve) a pull-request review thread — e.g. mark a Copilot review comment resolved once addressed. Takes the thread node id from pull_request_read get_review_comments. Runs on the write PAT (Pull requests: write).",
+					inputSchema: RESOLVE_REVIEW_THREAD_SCHEMA
+				});
+			} else if (rule.name === "reply_review_thread") {
+				tools.push({
+					name: "reply_review_thread",
+					description:
+						"Post a reply inside a pull-request review thread — e.g. respond to a Copilot review comment. Takes the thread node id from pull_request_read get_review_comments. Runs on the write PAT (Pull requests: write).",
+					inputSchema: REPLY_REVIEW_THREAD_SCHEMA
+				});
+			} else if (rule.name === "issue_labels") {
+				tools.push({
+					name: "issue_labels",
+					description:
+						'Edit the labels on one issue or PR without touching any other label on it. add / remove take one label or several (combinable in one call); swap { prefix, to } removes every label starting with prefix and adds to (e.g. prefix "status: ", to "status: verified"); set replaces the whole set and only as an explicit choice. Labels already present (add) or absent (remove) are no-ops. A label name to add that does not exist in the repo refuses the call and changes nothing, unless create_missing is true. Returns the resulting label set plus what was added, removed and created. Runs on the write PAT (Issues: write).',
+					inputSchema: ISSUE_LABELS_SCHEMA
+				});
+			} else if (rule.name === "report_unlabeled") {
+				tools.push({
+					name: "report_unlabeled",
+					description:
+						"Report issues and/or PRs with no labels, for one repo or every non-archived repo an owner has. Bounded by maxRepos/perRepoLimit/maxApiCalls; returns truncated:true (with a reason) instead of failing outright if a cap or GitHub's rate limit is hit mid-scan. Runs on the read PAT.",
+					inputSchema: REPORT_UNLABELED_SCHEMA
+				});
+			} else if (rule.name === "report_security_alerts") {
+				tools.push({
+					name: "report_security_alerts",
+					description:
+						"Report every open Dependabot, code-scanning (CodeQL) and secret-scanning alert, for one repo or across every repo an owner has. Reads the org-level endpoints in a handful of calls and falls back to a per-repo sweep for any alert type the token can't read org-wide. Alert state tracks the default branch. Secret values are never returned. Bounded by maxRepos/alertLimit/maxApiCalls; returns truncated:true (with a reason) instead of failing outright if a cap or GitHub's rate limit is hit. Runs on the read PAT.",
+					inputSchema: REPORT_SECURITY_ALERTS_SCHEMA
+				});
+			} else if (rule.name === "report_release_prs") {
+				tools.push({
+					name: "report_release_prs",
+					description:
+						"Report every open release PR (label `release`: next→master and hotfixes→master) for one repo or across every repo an owner has, and whether each one's per-version changelog file (docs/changelog[s]/v<major>/vX.Y.Z.md) is already on the release branch. Status per PR: ready, needs-changelog, or unknown-version (title has no `release: vX.Y.Z`). Use during mass updates to find which repos need a changelog. One search call plus two calls per release PR found; returns truncated:true with a reason if a cap or GitHub's rate limit is hit. Runs on the read PAT.",
+					inputSchema: REPORT_RELEASE_PRS_SCHEMA
+				});
+			} else if (rule.name === "report_ci_status") {
+				tools.push({
+					name: "report_ci_status",
+					description:
+						"Report CI health for a PR, or every open PR in a repo, at a chosen verbosity: 0 counts only, 1 adds which run/job failed, 2 adds which step failed, 3 adds a tail of the failing job's log. Detail beyond tier 0 is only fetched for runs that are actually failing. Runs on the read PAT.",
+					inputSchema: REPORT_CI_STATUS_SCHEMA
+				});
+			}
+			continue;
+		}
+		const up = upstreamByName.get(rule.name);
+		if (!up && upstreamFetched) {
+			// Reachable upstream that doesn't expose this tool → it would 32602 at call time. Skip + warn.
+			console.error(`catalog: allowlisted tool "${rule.name}" is NOT exposed by the upstream (${config.upstream}) — skipping it. Check the tool name or the upstream toolset (e.g. use /mcp/x/all for non-default toolsets like labels).`);
+			continue;
+		}
+		const base = up ?? { name: rule.name, description: `(${rule.mode}) proxied to the GitHub MCP`, inputSchema: { type: "object" } };
+		if (rule.augment && rule.name === "pull_request_read") {
+			// Layer gh-broker's own extension params onto the real upstream schema — the
+			// forwarded call still needs pull_request_read's actual params (method,
+			// pullNumber, ...); this ADDS to that, it doesn't replace it. See router.ts's
+			// dispatchAugmented for why gh-broker can extend a proxied tool's contract.
+			const baseSchema = base.inputSchema as { properties?: Record<string, unknown>; [k: string]: unknown };
+			tools.push({
+				...base,
+				description: `${base.description} gh-broker extension: with method "get", pass "ciVerbosity" (0-3) to also compute CI status for the PR's current head — 0 counts only, 1 adds which run/job failed, 2 adds which step failed, 3 adds a tail of the failing job's log; "logLines" tunes tier 3's tail length.`,
+				inputSchema: {
+					...baseSchema,
+					type: "object",
+					properties: {
+						...(baseSchema.properties ?? {}),
+						ciVerbosity: { type: "number", enum: [0, 1, 2, 3], description: 'gh-broker extension: also compute CI status at this verbosity (method "get" only)' },
+						logLines: { type: "number", description: "gh-broker extension: tier-3 log tail length" }
+					}
+				}
+			});
+			continue;
+		}
+		if (rule.name === "issue_write") {
+			// issue_write's `labels` REPLACES the issue's whole label set — the trap behind
+			// CLDMV/gh-broker#117. Say so where the agent reads the tool, and point at the verb
+			// that edits labels one at a time when it is allowlisted.
+			const pointer = config.tools.some((t) => t.name === "issue_labels" && t.custom)
+				? " To add, remove or swap individual labels, use issue_labels instead."
+				: " Read the current labels first and pass the full set you want to keep.";
+			tools.push({
+				...base,
+				description: `${base.description ?? ""} WARNING (gh-broker): "labels" REPLACES the issue's whole label set — every label not listed is removed.${pointer}`.trim()
+			});
+			continue;
+		}
+		tools.push(base);
+	}
+	return tools;
+}

package/src/config.ts

@@ -0,0 +1,130 @@
+/**
+ *
+ *	@Project: @cldmv/gh-broker
+ *	@Filename: /src/config.ts
+ *	@Date: 2026-07-07T00:24:51-07:00 (1783409091)
+ *	@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 { readFileSync } from "node:fs";
+import type { Config, Mode, ToolRule } from "./types.ts";
+
+const MODES: readonly Mode[] = ["read", "write"];
+
+/** Load and validate the JSON config. Throws with a precise message on any problem. */
+export function loadConfig(path: string): Config {
+	let raw: unknown;
+	try {
+		raw = JSON.parse(readFileSync(path, "utf8"));
+	} catch (err) {
+		throw new Error(`config: cannot read/parse ${path}: ${(err as Error).message}`);
+	}
+	if (typeof raw !== "object" || raw === null) throw new Error("config: root must be an object");
+	const c = raw as Record<string, unknown>;
+
+	if (typeof c.listen !== "string" || !c.listen.startsWith("unix:")) {
+		throw new Error('config.listen: must be a "unix:<path>" string');
+	}
+	if (typeof c.upstream !== "string" || !/^https?:\/\//.test(c.upstream)) {
+		throw new Error("config.upstream: must be an http(s) URL");
+	}
+	if (!Array.isArray(c.tools) || c.tools.length === 0) {
+		throw new Error("config.tools: must be a non-empty array");
+	}
+
+	const seen = new Set<string>();
+	const tools: ToolRule[] = c.tools.map((t, i) => {
+		const o = t as Record<string, unknown>;
+		if (typeof o.name !== "string" || !o.name) throw new Error(`config.tools[${i}].name: required`);
+		if (!MODES.includes(o.mode as Mode)) throw new Error(`config.tools[${i}].mode: must be read|write`);
+		if (seen.has(o.name)) throw new Error(`config.tools: duplicate tool "${o.name}"`);
+		seen.add(o.name);
+		const custom = o.custom === true;
+		const augment = o.augment === true;
+		if (custom && augment) throw new Error(`config.tools[${i}] ("${o.name}"): custom and augment are mutually exclusive`);
+		return { name: o.name, mode: o.mode as Mode, custom, augment };
+	});
+
+	if (typeof c.owners !== "object" || c.owners === null) throw new Error("config.owners: must be an object");
+	const owners: Config["owners"] = {};
+	for (const [owner, v] of Object.entries(c.owners as Record<string, unknown>)) {
+		const o = v as Record<string, unknown>;
+		if (typeof o.read !== "string" || typeof o.write !== "string") {
+			throw new Error(`config.owners.${owner}: needs "read" and "write" credential refs`);
+		}
+		if (o.installationId !== undefined && typeof o.installationId !== "number") {
+			throw new Error(`config.owners.${owner}.installationId: must be a number`);
+		}
+		owners[owner.toLowerCase()] = {
+			read: o.read,
+			write: o.write,
+			...(typeof o.installationId === "number" ? { installationId: o.installationId } : {})
+		};
+	}
+	if (Object.keys(owners).length === 0) throw new Error("config.owners: at least one owner required");
+
+	let defaultOwner: string | undefined;
+	if (c.defaultOwner !== undefined) {
+		if (typeof c.defaultOwner !== "string" || !c.defaultOwner) {
+			throw new Error("config.defaultOwner: must be a non-empty string naming a configured owner");
+		}
+		defaultOwner = c.defaultOwner.toLowerCase();
+		if (!owners[defaultOwner]) {
+			throw new Error(`config.defaultOwner "${c.defaultOwner}" is not a key of config.owners`);
+		}
+	}
+
+	let app: Config["app"];
+	if (c.app !== undefined) {
+		const a = c.app as Record<string, unknown>;
+		if (typeof a.appId !== "number") throw new Error("config.app.appId: must be a number");
+		if (typeof a.privateKey !== "string") throw new Error('config.app.privateKey: must be a "cred:<name>" ref');
+		app = { appId: a.appId, privateKey: a.privateKey };
+	}
+
+	let secrets: Config["secrets"];
+	if (c.secrets !== undefined) {
+		if (typeof c.secrets !== "object" || c.secrets === null || Array.isArray(c.secrets)) throw new Error("config.secrets: must be an object");
+		const s = c.secrets as Record<string, unknown>;
+		if (s.provider !== undefined && s.provider !== "file" && s.provider !== "systemd-creds") {
+			throw new Error('config.secrets.provider: must be "systemd-creds" or "file"');
+		}
+		// Reject an empty path: resolveSecretsPath treats a falsy explicit path as
+		// "not provided" and falls back to env/default, so "" would be silently ignored.
+		if (s.path !== undefined && (typeof s.path !== "string" || s.path.length === 0)) {
+			throw new Error("config.secrets.path: must be a non-empty string");
+		}
+		// path only means anything to the file provider; the systemd-creds provider
+		// (the default) reads $CREDENTIALS_DIRECTORY and would silently ignore it.
+		// Reject the combination so an operator can't think a file path is in effect.
+		if (s.path !== undefined && (s.provider ?? "systemd-creds") !== "file") {
+			throw new Error('config.secrets.path is only used by the "file" provider — set provider to "file" or remove path');
+		}
+		secrets = {
+			...(s.provider === "file" || s.provider === "systemd-creds" ? { provider: s.provider } : {}),
+			...(typeof s.path === "string" ? { path: s.path } : {})
+		};
+	}
+
+	return {
+		listen: c.listen,
+		upstream: c.upstream,
+		tools,
+		owners,
+		...(app ? { app } : {}),
+		...(secrets ? { secrets } : {}),
+		...(defaultOwner ? { defaultOwner } : {})
+	};
+}
+
+/** Build a name→rule index for O(1) allowlist checks. */
+export function indexTools(tools: ToolRule[]): Map<string, ToolRule> {
+	return new Map(tools.map((t) => [t.name, t]));
+}

package/src/index.ts

@@ -0,0 +1,107 @@
+/**
+ *
+ *	@Project: @cldmv/gh-broker
+ *	@Filename: /src/index.ts
+ *	@Date: 2026-07-07T00:24:51-07:00 (1783409091)
+ *	@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 { loadConfig } from "./config.ts";
+import { loadSecretStore } from "./secrets.ts";
+import { UpstreamPool } from "./upstream.ts";
+import { Router } from "./router.ts";
+import { AppAuth } from "./appauth.ts";
+import { buildCatalog } from "./catalog.ts";
+import { startServer } from "./server.ts";
+import { resolveConfigPath } from "./paths.ts";
+
+function argConfig(): string {
+	const i = process.argv.indexOf("--config");
+	if (i >= 0) {
+		// Fail fast on `--config` with no value (or a flag as the "value") rather than
+		// silently falling back to env/default and hiding the operator's mistake.
+		const explicit = process.argv[i + 1];
+		if (!explicit || explicit.startsWith("-")) throw new Error("--config requires a path argument");
+		return resolveConfigPath(explicit);
+	}
+	return resolveConfigPath(undefined);
+}
+
+async function main(): Promise<void> {
+	const configPath = argConfig();
+
+	// --print-paths: emit the resolved config + secrets paths and exit. The
+	// installer uses this so there is one path resolver (src/paths.ts), no drift.
+	// Honor a deployed config's secrets.path override when the config already exists
+	// (upgrades); fall back to the default when it doesn't (first install) or is
+	// unparseable — this must not require a valid config to run.
+	if (process.argv.includes("--print-paths")) {
+		const { resolveSecretsPath } = await import("./paths.ts");
+		let secretsOverride: string | undefined;
+		try {
+			secretsOverride = loadConfig(configPath).secrets?.path;
+		} catch {
+			secretsOverride = undefined;
+		}
+		console.log(JSON.stringify({ config: configPath, secrets: resolveSecretsPath(secretsOverride) }));
+		return;
+	}
+
+	const config = loadConfig(configPath);
+
+	// --check: validate the config parses (and, where possible, that credentials
+	// resolve), then exit WITHOUT starting the server. The installer runs this to
+	// fail an install/upgrade early. The file provider validates here; the
+	// systemd-creds provider can only resolve under systemd (needs
+	// $CREDENTIALS_DIRECTORY), so it's checked at service start / by the smoke test.
+	if (process.argv.includes("--check")) {
+		const provider = config.secrets?.provider ?? "systemd-creds";
+		// Truthy, not just "defined": the systemd-creds store treats an empty
+		// $CREDENTIALS_DIRECTORY as unset (if (!dir)), so --check must too — otherwise
+		// it would attempt secret resolution and fail where it should report unchecked.
+		const secretsChecked = provider === "file" || Boolean(process.env.CREDENTIALS_DIRECTORY);
+		if (secretsChecked) loadSecretStore(config);
+		console.log(JSON.stringify({ event: "config-ok", config: configPath, provider, secretsChecked, owners: Object.keys(config.owners), tools: config.tools.length }));
+		return;
+	}
+
+	const secrets = loadSecretStore(config); // eagerly validates every referenced credential
+	const upstream = new UpstreamPool(config);
+
+	// Optional GitHub App (for link_issue). Non-fatal: a misconfigured App disables
+	// link_issue but never takes down the read/write path.
+	let appAuth: AppAuth | undefined;
+	if (config.app) {
+		try {
+			appAuth = new AppAuth(config, secrets);
+		} catch (err) {
+			console.error(`gh-broker: app-auth disabled (link_issue unavailable): ${(err as Error).message}`);
+		}
+	}
+
+	const router = new Router(config, secrets, upstream, appAuth);
+	const catalog = await buildCatalog(config, secrets, upstream);
+	await startServer(config, router, catalog);
+	console.log(
+		JSON.stringify({
+			ts: new Date().toISOString(),
+			event: "listening",
+			listen: config.listen,
+			owners: Object.keys(config.owners),
+			app: appAuth ? "enabled" : "none",
+			tools: catalog.map((t) => t.name)
+		})
+	);
+}
+
+main().catch((err: unknown) => {
+	console.error(`gh-broker: fatal: ${(err as Error).message}`);
+	process.exit(1);
+});