@cldmv/gh-broker 0.0.0-stage → 0.7.0

package/src/paths.ts

@@ -0,0 +1,60 @@
+/**
+ *
+ *	@Project: @cldmv/gh-broker
+ *	@Filename: /src/paths.ts
+ *	@Date: 2026-09-06T10:05:35-07:00 (1788714335)
+ *	@Author: Nate Corcoran <CLDMV>
+ *	@Email: <Shinrai@users.noreply.github.com>
+ *	-----
+ *	@Last modified by: Nate Corcoran <CLDMV> (Shinrai@users.noreply.github.com)
+ *	@Last modified time: 2026-10-02T11:30:58-07:00 (1790965858)
+ *	-----
+ *	@Copyright: Copyright (c) 2013-2026 Catalyzed Motivation Inc. All rights reserved.
+ *
+ */
+
+import { platform, env } from "node:process";
+import { join } from "node:path";
+
+/**
+ * Platform-neutral path resolution for the config and secrets files.
+ *
+ * Nothing is hardcoded to /etc. Both files resolve through the same order:
+ *   1. an explicit path (a `--config` flag, or GH_BROKER_CONFIG / GH_BROKER_SECRETS),
+ *   2. the platform's system config dir (below),
+ *   3. the packaged default under that dir.
+ *
+ * Only the Linux defaults are exercised today; the macOS/Windows entries are
+ * wired so a later port is a table entry, not surgery. See docs/deploy-architecture.md.
+ */
+
+/** The system-wide config directory for the current platform (env-overridable). */
+export function configDir(): string {
+	const override = env.GH_BROKER_CONFIG_DIR;
+	if (override) return override;
+	switch (platform) {
+		case "darwin":
+			return "/Library/Application Support/gh-broker";
+		case "win32":
+			return join(env.ProgramData ?? "C:\\ProgramData", "gh-broker");
+		default: // linux and other unixes
+			return "/etc/gh-broker";
+	}
+}
+
+/**
+ * Resolve the config file path: an explicit argument (from `--config`) wins,
+ * then GH_BROKER_CONFIG, then `<configDir>/config.json`.
+ */
+export function resolveConfigPath(explicit?: string): string {
+	if (explicit) return explicit;
+	if (env.GH_BROKER_CONFIG) return env.GH_BROKER_CONFIG;
+	return join(configDir(), "config.json");
+}
+
+/** Resolve the secrets file path: an explicit argument wins, then GH_BROKER_SECRETS, then `<configDir>/secrets.json`. */
+export function resolveSecretsPath(explicit?: string): string {
+	if (explicit) return explicit;
+	if (env.GH_BROKER_SECRETS) return env.GH_BROKER_SECRETS;
+	return join(configDir(), "secrets.json");
+}

package/src/router.ts

@@ -0,0 +1,258 @@
+/**
+ *
+ *	@Project: @cldmv/gh-broker
+ *	@Filename: /src/router.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:03-07:00 (1792196223)
+ *	-----
+ *	@Copyright: Copyright (c) 2013-2026 Catalyzed Motivation Inc. All rights reserved.
+ *
+ */
+
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import type { Config, SecretStore, ToolRule } from "./types.ts";
+import type { AppAuth } from "./appauth.ts";
+import { Octokit } from "@octokit/core";
+import { indexTools } from "./config.ts";
+import { audit } from "./audit.ts";
+// DEFERRED: link_issue is App-token-only and not wired in — see docs.
+// import { linkIssue, type LinkIssueInput } from "./verbs/link_issue.ts";
+import {
+	resolveReviewThread,
+	replyReviewThread,
+	type ResolveReviewThreadInput,
+	type ReplyReviewThreadInput
+} from "./verbs/review_thread.ts";
+import { reportUnlabeled, type ReportUnlabeledInput } from "./verbs/report_unlabeled.ts";
+import { reportSecurityAlerts, type ReportSecurityAlertsInput } from "./verbs/report_security_alerts.ts";
+import { reportReleasePrs, type ReportReleasePrsInput } from "./verbs/report_release_prs.ts";
+import { issueLabels, type IssueLabelsInput } from "./verbs/issue_labels.ts";
+import { reportCiStatus, ciStatusForHeadSha, type ReportCiStatusInput, type FailedJobLogsFetcher } from "./verbs/report_ci_status.ts";
+
+/** What the router needs from the upstream (hosted-MCP) client pool. */
+export interface Upstream {
+	forward(tool: string, args: Record<string, unknown>, token: string): Promise<CallToolResult>;
+}
+
+/**
+ * Enforces the default-deny allowlist, resolves the (owner, mode) → PAT, and either
+ * forwards to the hosted MCP or dispatches a custom verb. The token never leaves here.
+ */
+export class Router {
+	private readonly config: Config;
+	private readonly secrets: SecretStore;
+	private readonly upstream: Upstream;
+	private readonly appAuth?: AppAuth;
+	private readonly rules: Map<string, ToolRule>;
+
+	constructor(config: Config, secrets: SecretStore, upstream: Upstream, appAuth?: AppAuth) {
+		this.config = config;
+		this.secrets = secrets;
+		this.upstream = upstream;
+		this.appAuth = appAuth;
+		this.rules = indexTools(config.tools);
+	}
+
+	/** Tools advertised to the agent (used to build tools/list). */
+	advertisedTools(): ToolRule[] {
+		return this.config.tools;
+	}
+
+	async call(tool: string, args: Record<string, unknown>): Promise<CallToolResult> {
+		const rule = this.rules.get(tool);
+		if (!rule) {
+			audit({ tool, decision: "deny", detail: "not in allowlist" });
+			throw new Error(`tool "${tool}" is not allowed`);
+		}
+		// Owner-less reads (global advisory DB, get_me, notifications) fall back to
+		// the configured defaultOwner's READ PAT. Writes never fall back — a write
+		// must always name the owner it targets.
+		let owner = extractOwner(args);
+		if (!owner && rule.mode === "read" && this.config.defaultOwner && this.config.owners[this.config.defaultOwner]) {
+			owner = this.config.defaultOwner.toLowerCase();
+		}
+		if (!owner) {
+			audit({ tool, decision: "error", detail: "no owner in args" });
+			throw new Error(`tool "${tool}": could not determine repo owner from arguments`);
+		}
+		const creds = this.config.owners[owner];
+		if (!creds) {
+			audit({ tool, owner, decision: "error", detail: "no creds for owner" });
+			throw new Error(`no credentials configured for owner "${owner}" — add it to config.owners + creds`);
+		}
+		const token = this.secrets.resolve(rule.mode === "write" ? creds.write : creds.read);
+		const repo = typeof args.repo === "string" ? `${owner}/${args.repo}` : owner;
+
+		const decision = rule.custom ? "custom" : rule.augment ? "augment" : "forward";
+		try {
+			const out = rule.custom
+				? await this.dispatchCustom(tool, args, owner, token)
+				: rule.augment
+					? await this.dispatchAugmented(tool, args, owner, token)
+					: await this.upstream.forward(tool, args, token);
+			audit({ tool, owner, mode: rule.mode, repo, decision, ok: true });
+			return out;
+		} catch (err) {
+			audit({ tool, owner, mode: rule.mode, repo, decision, ok: false, detail: (err as Error).message });
+			throw err;
+		}
+	}
+
+	private async dispatchCustom(
+		tool: string,
+		args: Record<string, unknown>,
+		owner: string,
+		token: string
+	): Promise<CallToolResult> {
+		switch (tool) {
+			// DEFERRED: link_issue (App-token-only addClosingIssueReference) is not wired in — see docs.
+			// Re-enable by restoring this case + the import above + the catalog block, adding a
+			// link_issue allowlist entry to config, and configuring config.app + owner installationId.
+			// case "link_issue": {
+			// 	const octokit = this.appAuth?.octokitFor(owner);
+			// 	if (!octokit) {
+			// 		throw new Error(`link_issue needs a GitHub App for "${owner}": set config.app + owners.${owner}.installationId + the app key cred (addClosingIssueReference is App-token-only — not available to fine-grained PATs)`);
+			// 	}
+			// 	const out = await linkIssue(octokit, args as unknown as LinkIssueInput);
+			// 	return { content: [{ type: "text", text: `linked: PR ${out.pullRequestId} → issue ${out.issueId}` }] };
+			// }
+			case "resolve_review_thread": {
+				// PAT-usable (Pull requests: write) — run on the resolved write PAT, not the App token.
+				const octokit = new Octokit({ auth: token });
+				const out = await resolveReviewThread(octokit, args as unknown as ResolveReviewThreadInput);
+				return { content: [{ type: "text", text: `thread ${out.threadId}: isResolved=${out.isResolved}` }] };
+			}
+			case "reply_review_thread": {
+				const octokit = new Octokit({ auth: token });
+				const out = await replyReviewThread(octokit, args as unknown as ReplyReviewThreadInput);
+				return { content: [{ type: "text", text: `replied: ${out.url}` }] };
+			}
+			case "issue_labels": {
+				// Per-label REST endpoints (Issues: write) on the resolved write PAT.
+				const octokit = new Octokit({ auth: token });
+				const out = await issueLabels(octokit, args as unknown as IssueLabelsInput);
+				return { content: [{ type: "text", text: JSON.stringify(out) }] };
+			}
+			case "report_unlabeled": {
+				const octokit = new Octokit({ auth: token });
+				const out = await reportUnlabeled(octokit, args as unknown as ReportUnlabeledInput);
+				return { content: [{ type: "text", text: JSON.stringify(out) }] };
+			}
+			case "report_security_alerts": {
+				const octokit = new Octokit({ auth: token });
+				const out = await reportSecurityAlerts(octokit, args as unknown as ReportSecurityAlertsInput);
+				return { content: [{ type: "text", text: JSON.stringify(out) }] };
+			}
+			case "report_release_prs": {
+				const octokit = new Octokit({ auth: token });
+				const out = await reportReleasePrs(octokit, args as unknown as ReportReleasePrsInput);
+				return { content: [{ type: "text", text: JSON.stringify(out) }] };
+			}
+			case "report_ci_status": {
+				const octokit = new Octokit({ auth: token });
+				const reportArgs = args as unknown as ReportCiStatusInput;
+				const out = await reportCiStatus(octokit, reportArgs, this.makeJobLogsFetcher(owner, reportArgs.repo, token));
+				return { content: [{ type: "text", text: JSON.stringify(out) }] };
+			}
+			default:
+				throw new Error(`custom verb "${tool}" not implemented`);
+		}
+	}
+
+	/**
+	 * A failing-run's job logs, via the hosted MCP's own `get_job_logs` tool
+	 * (`failed_only: true` fetches every failing job in the run in one call) rather
+	 * than a hand-rolled REST call — see report_ci_status.ts's FailedJobLogsFetcher
+	 * doc comment for why. Best-effort: any failure here (bad shape, upstream error)
+	 * just yields an empty map — report_ci_status treats a lookup miss as "no
+	 * logTail for this job", never a hard failure of the whole report.
+	 */
+	private makeJobLogsFetcher(owner: string, repo: string, token: string): FailedJobLogsFetcher {
+		return async (runId, tailLines) => {
+			const map = new Map<number, string>();
+			try {
+				const result = await this.upstream.forward("get_job_logs", { owner, repo, run_id: runId, failed_only: true, return_content: true, tail_lines: tailLines }, token);
+				const textBlock = result.content?.find((c) => (c as { type?: string }).type === "text") as { text?: string } | undefined;
+				if (!textBlock?.text) return map;
+				const parsed = JSON.parse(textBlock.text) as { logs?: Array<{ job_id?: unknown; logs_content?: unknown }> };
+				for (const entry of parsed.logs ?? []) {
+					if (typeof entry.job_id === "number" && typeof entry.logs_content === "string") map.set(entry.job_id, entry.logs_content);
+				}
+			} catch {
+				/* best-effort — see doc comment */
+			}
+			return map;
+		};
+	}
+
+	/**
+	 * Forwards to the hosted MCP like a plain proxy, then post-processes the result.
+	 * gh-broker presents its own MCP contract — a proxied tool's response is not
+	 * required to match the hosted MCP's shape verbatim (see [[broker-owns-its-mcp-contract]]
+	 * in project memory). `ciVerbosity`/`logLines` are gh-broker's own extension
+	 * params, stripped before forwarding since the upstream schema doesn't know them.
+	 *
+	 * Opt-in only: with no `ciVerbosity`, this is byte-identical to a plain forward —
+	 * augmenting every `pull_request_read` call by default would add an unrequested
+	 * API call (and cost) to every ordinary PR read.
+	 *
+	 * Best-effort: if the upstream response isn't the JSON-text shape expected (a
+	 * format this broker doesn't control), the original result is returned unmodified
+	 * rather than thrown — a shape mismatch should degrade to "no CI data added," not
+	 * break an otherwise-successful PR read.
+	 */
+	private async dispatchAugmented(tool: string, args: Record<string, unknown>, owner: string, token: string): Promise<CallToolResult> {
+		switch (tool) {
+			case "pull_request_read": {
+				const { ciVerbosity, logLines, ...upstreamArgs } = args as Record<string, unknown> & { ciVerbosity?: number; logLines?: number };
+				const result = await this.upstream.forward(tool, upstreamArgs, token);
+				if (ciVerbosity === undefined) return result;
+				if ((upstreamArgs.method ?? "get") !== "get") return result; // only the single-PR "get" shape is augmentable
+
+				const textBlock = result.content?.find((c) => (c as { type?: string }).type === "text") as { text?: string } | undefined;
+				if (!textBlock?.text) return result;
+				let pr: unknown;
+				try {
+					pr = JSON.parse(textBlock.text);
+				} catch {
+					return result;
+				}
+				const p = pr as { number?: unknown; head?: { sha?: unknown } };
+				if (typeof p.number !== "number" || typeof p.head?.sha !== "string") return result;
+
+				const repo = String(upstreamArgs.repo ?? "");
+				const octokit = new Octokit({ auth: token });
+				const ci = await ciStatusForHeadSha(octokit, owner, repo, p.number, p.head.sha, {
+					verbosity: Number(ciVerbosity),
+					logLines: logLines !== undefined ? Number(logLines) : undefined,
+					fetchFailedJobLogs: this.makeJobLogsFetcher(owner, repo, token)
+				});
+				textBlock.text = JSON.stringify({ ...(pr as object), ci });
+				return result;
+			}
+			default:
+				return this.upstream.forward(tool, args, token);
+		}
+	}
+}
+
+/** Derive the repo owner from a tool call's arguments, so we pick the right PAT. */
+export function extractOwner(args: Record<string, unknown>): string | undefined {
+	if (typeof args.owner === "string" && args.owner) return args.owner.toLowerCase();
+	// Many org-scoped tools (list_org_repository_security_advisories, get_team_members, …)
+	// name the org as `org` rather than `owner`; for routing, org === owner.
+	if (typeof args.org === "string" && args.org) return args.org.toLowerCase();
+	if (typeof args.query === "string") {
+		const m = args.query.match(/\brepo:([^/\s]+)\/[^\s]+|\b(?:org|user):([^\s]+)/i);
+		const hit = m?.[1] ?? m?.[2];
+		if (hit) return hit.toLowerCase();
+	}
+	if (typeof args.repository === "string" && args.repository.includes("/")) {
+		return args.repository.split("/")[0]?.toLowerCase();
+	}
+	return undefined;
+}

package/src/secrets.ts

@@ -0,0 +1,137 @@
+/**
+ *
+ *	@Project: @cldmv/gh-broker
+ *	@Filename: /src/secrets.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 { join } from "node:path";
+import type { Config, SecretStore } from "./types.ts";
+import { resolveSecretsPath } from "./paths.ts";
+
+const CRED_PREFIX = "cred:";
+
+/**
+ * Loads PATs from the configured secret store and returns a resolver mapping
+ * "cred:<name>" refs to token values. Never writes or logs a token.
+ *
+ * Provider seam (chosen at install time, recorded in config.secrets.provider):
+ *   - "systemd-creds" (default) — tokens are systemd-encrypted, host/TPM-bound
+ *     `.cred` files delivered via LoadCredentialEncrypted into $CREDENTIALS_DIRECTORY
+ *     (memory-only, service-user-readable). Encrypted at rest; not portable.
+ *   - "file" — a JSON `{ "<name>": "<token>" }` map at an agent-unreadable path.
+ *     Plaintext at rest (perms only); portable and platform-neutral.
+ *
+ * Both keep tokens off any agent-readable path — the agent boundary is filesystem
+ * perms either way. See docs/deploy-architecture.md.
+ */
+export function loadSecretStore(config: Config): SecretStore {
+	const provider = config.secrets?.provider ?? "systemd-creds";
+	switch (provider) {
+		case "systemd-creds":
+			return systemdCredsStore(config);
+		case "file":
+			return fileStore(config);
+		default:
+			throw new Error(`secrets: unknown provider "${provider}" (expected "systemd-creds" or "file")`);
+	}
+}
+
+const SAFE_CRED_NAME = /^[A-Za-z0-9._-]+$/;
+
+/**
+ * Credential names become filesystem path components (`join(dir, name)`) and are
+ * interpolated into systemd drop-in lines, so constrain them to a safe charset —
+ * no path separators, "..", colons, or control characters — to prevent reads
+ * outside $CREDENTIALS_DIRECTORY and malformed drop-ins.
+ */
+function assertSafeName(name: string): string {
+	if (name === "." || name === ".." || !SAFE_CRED_NAME.test(name)) {
+		throw new Error(`secrets: unsafe credential name "${name}" (allowed: letters, digits, ".", "_", "-")`);
+	}
+	return name;
+}
+
+function credName(ref: string): string {
+	if (!ref.startsWith(CRED_PREFIX)) throw new Error(`secrets: bad credential ref "${ref}"`);
+	return assertSafeName(ref.slice(CRED_PREFIX.length));
+}
+
+/** Eagerly read every referenced credential so a missing token fails at startup, not on first request. */
+function validateRefs(config: Config, read: (name: string) => string): void {
+	for (const [owner, creds] of Object.entries(config.owners)) {
+		for (const ref of [creds.read, creds.write]) {
+			if (!ref.startsWith(CRED_PREFIX)) throw new Error(`secrets: owner "${owner}" ref must be "cred:<name>", got "${ref}"`);
+			read(assertSafeName(ref.slice(CRED_PREFIX.length)));
+		}
+	}
+	if (config.app) {
+		// The App key is a secret too — it must be a cred: ref, never inlined in the
+		// token-free config. Reject a non-cred ref rather than silently accepting it.
+		if (!config.app.privateKey.startsWith(CRED_PREFIX)) {
+			throw new Error(`secrets: config.app.privateKey must be a "cred:<name>" ref, got "${config.app.privateKey}"`);
+		}
+		read(assertSafeName(config.app.privateKey.slice(CRED_PREFIX.length)));
+	}
+}
+
+/** systemd-creds provider: read decrypted creds from $CREDENTIALS_DIRECTORY. */
+function systemdCredsStore(config: Config): SecretStore {
+	const dir = process.env.CREDENTIALS_DIRECTORY;
+	if (!dir) {
+		throw new Error("secrets: $CREDENTIALS_DIRECTORY unset — the systemd-creds provider needs LoadCredentialEncrypted= (run under systemd)");
+	}
+	const cache = new Map<string, string>();
+	const read = (name: string): string => {
+		const cached = cache.get(name);
+		if (cached !== undefined) return cached;
+		let val: string;
+		try {
+			val = readFileSync(join(dir, name), "utf8").replace(/\r?\n$/, "");
+		} catch (err) {
+			throw new Error(`secrets: credential "${name}" not available: ${(err as Error).message}`);
+		}
+		if (!val) throw new Error(`secrets: credential "${name}" is empty`);
+		cache.set(name, val);
+		return val;
+	};
+	validateRefs(config, read);
+	return { resolve: (ref) => read(credName(ref)) };
+}
+
+/** file provider: read tokens from a JSON `{ "<name>": "<token>" }` map. */
+function fileStore(config: Config): SecretStore {
+	const path = resolveSecretsPath(config.secrets?.path);
+	let raw: unknown;
+	try {
+		raw = JSON.parse(readFileSync(path, "utf8"));
+	} catch (err) {
+		throw new Error(`secrets: cannot read/parse secrets file ${path}: ${(err as Error).message}`);
+	}
+	if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+		throw new Error(`secrets: ${path} must be a JSON object of { "<name>": "<token>" }`);
+	}
+	const map = raw as Record<string, unknown>; // read once into memory; never re-read or write
+
+	const read = (name: string): string => {
+		const val = map[name];
+		if (typeof val !== "string") throw new Error(`secrets: credential "${name}" missing or empty in ${path}`);
+		// Normalize like the systemd-creds provider: strip a single trailing newline
+		// (common when a token is copy/pasted into the JSON) so it isn't silently
+		// mismatched at auth time. A value that is only a newline then reads as empty.
+		const token = val.replace(/\r?\n$/, "");
+		if (token.length === 0) throw new Error(`secrets: credential "${name}" missing or empty in ${path}`);
+		return token;
+	};
+	validateRefs(config, read);
+	return { resolve: (ref) => read(credName(ref)) };
+}

package/src/server.ts

@@ -0,0 +1,91 @@
+/**
+ *
+ *	@Project: @cldmv/gh-broker
+ *	@Filename: /src/server.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 { createServer, type Socket } from "node:net";
+import { chmodSync, chownSync, existsSync, readFileSync, unlinkSync } from "node:fs";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, type Tool } from "@modelcontextprotocol/sdk/types.js";
+import type { Config } from "./types.ts";
+import type { Router } from "./router.ts";
+
+const SERVER_INFO = { name: "gh-broker", version: "0.1.0" };
+
+function socketPath(listen: string): string {
+	if (!listen.startsWith("unix:")) throw new Error(`server: unsupported listen "${listen}"`);
+	return listen.slice("unix:".length);
+}
+
+/** Resolve a group name → gid via /etc/group (no native Node API for this). */
+function groupGid(name: string): number | undefined {
+	try {
+		for (const line of readFileSync("/etc/group", "utf8").split("\n")) {
+			const parts = line.split(":");
+			if (parts[0] === name && parts[2]) return Number(parts[2]);
+		}
+	} catch {
+		/* ignore — fall back to RuntimeDirectory perms */
+	}
+	return undefined;
+}
+
+/**
+ * Each agent connection (a socat stdio bridge to our Unix socket) gets its own MCP
+ * Server over a StdioServerTransport bound to that socket. `tools/list` returns the
+ * pre-built catalog; `tools/call` delegates to the router (allowlist + owner/mode →
+ * PAT + forward/dispatch). The token never crosses to this side.
+ */
+function handleConnection(socket: Socket, router: Router, catalog: Tool[]): void {
+	const server = new Server(SERVER_INFO, { capabilities: { tools: {} } });
+
+	server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: catalog }));
+	server.setRequestHandler(CallToolRequestSchema, async (req) => {
+		const args = (req.params.arguments ?? {}) as Record<string, unknown>;
+		return router.call(req.params.name, args);
+	});
+
+	const transport = new StdioServerTransport(socket, socket);
+	server.connect(transport).catch((err: unknown) => {
+		console.error(`gh-broker: connection error: ${(err as Error).message}`);
+		socket.destroy();
+	});
+	socket.on("close", () => void server.close().catch(() => {}));
+	socket.on("error", () => {
+		/* client hangup — ignore */
+	});
+}
+
+export function startServer(config: Config, router: Router, catalog: Tool[]): Promise<void> {
+	const path = socketPath(config.listen);
+	if (existsSync(path)) unlinkSync(path); // clear a stale socket from a prior run
+
+	return new Promise((resolve, reject) => {
+		const server = createServer((sock: Socket) => handleConnection(sock, router, catalog));
+		server.on("error", reject);
+		server.listen(path, () => {
+			// Restrict the socket to the agent-clients group: chgrp to gh-broker-clients,
+			// mode 0660 (owner+group rw). The agent user is a member of that group.
+			const group = process.env.GH_BROKER_SOCKET_GROUP ?? "gh-broker-clients";
+			const gid = groupGid(group);
+			try {
+				if (gid !== undefined) chownSync(path, process.getuid?.() ?? -1, gid);
+				chmodSync(path, 0o660);
+			} catch {
+				/* best-effort; RuntimeDirectory perms already restrict access */
+			}
+			resolve();
+		});
+	});
+}

package/src/types.ts

@@ -0,0 +1,104 @@
+/**
+ *
+ *	@Project: @cldmv/gh-broker
+ *	@Filename: /src/types.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.
+ *
+ */
+
+/**
+ * Config + internal types for gh-broker.
+ *
+ * The on-disk config holds no secrets — only the tool allowlist and, per owner,
+ * the *names* of the credentials to use. Actual PAT values are resolved at
+ * runtime from a separate, agent-unreadable secrets store (see secrets.ts and
+ * docs/deploy-architecture.md). Keeping the config token-free is what makes it
+ * safe to copy between machines.
+ */
+
+export type Mode = "read" | "write";
+
+/**
+ * One entry in the default-deny allowlist. `custom` verbs are handled locally, not
+ * proxied. `augment` tools ARE proxied (forwarded to the hosted MCP) but the router
+ * post-processes the response afterward — gh-broker's own MCP contract for a proxied
+ * tool is not required to match the hosted MCP's exact schema/response verbatim (see
+ * router.ts's dispatchAugmented). `custom` and `augment` are mutually exclusive.
+ */
+export interface ToolRule {
+	name: string;
+	mode: Mode;
+	custom?: boolean;
+	augment?: boolean;
+}
+
+/** Credential *references* (e.g. "cred:cldmv-read"), resolved via the SecretStore. */
+export interface OwnerCreds {
+	read: string;
+	write: string;
+	/**
+	 * GitHub App installation id for this owner. Required only for verbs that need
+	 * an App token (currently `link_issue` → addClosingIssueReference, which is not
+	 * available to fine-grained PATs). Omit if the owner has no App installed.
+	 */
+	installationId?: number;
+}
+
+/** GitHub App config — for App-token-only operations (`link_issue`). Optional. */
+export interface AppConfig {
+	appId: number;
+	/** Credential reference (e.g. "cred:gh-app-key") for the App's PEM private key. */
+	privateKey: string;
+}
+
+/**
+ * Where the actual token values live — chosen at install time. A provider seam:
+ *   - "systemd-creds" (default): encrypted, host-bound `.cred` files via
+ *     LoadCredentialEncrypted → $CREDENTIALS_DIRECTORY (encrypted at rest, not portable).
+ *   - "file": a JSON `{ "<name>": "<token>" }` map at an agent-unreadable path
+ *     (plaintext at rest, portable, platform-neutral).
+ * Further providers (OS keychain, DPAPI, encrypted vault) can be added here
+ * without touching call sites. Omit to use the systemd-creds provider.
+ */
+export interface SecretsConfig {
+	provider?: "systemd-creds" | "file";
+	/** For provider "file": path to the JSON secrets file. Defaults to <configDir>/secrets.json. */
+	path?: string;
+}
+
+export interface Config {
+	/** e.g. "unix:/run/gh-broker/gh-broker.sock" */
+	listen: string;
+	/** GitHub hosted MCP base URL, e.g. "https://api.githubcopilot.com/mcp/" */
+	upstream: string;
+	tools: ToolRule[];
+	owners: Record<string, OwnerCreds>;
+	/**
+	 * Owner whose READ PAT handles calls that carry no owner in their args —
+	 * the genuinely global/identity reads (global security-advisory DB, `get_me`,
+	 * `list_notifications`). Must be a key of `owners`. Applies to `mode: "read"`
+	 * only; write calls always require an explicit owner. Omit to reject every
+	 * owner-less call (the stricter original behaviour).
+	 */
+	defaultOwner?: string;
+	/**
+	 * Optional GitHub App, reserved for `link_issue` (an App-token-only mutation).
+	 * `link_issue` is currently deferred — it is neither advertised nor dispatched —
+	 * so providing this does not enable any verb today.
+	 */
+	app?: AppConfig;
+	/** Optional secret-store backend selection. Defaults to the systemd-creds provider. */
+	secrets?: SecretsConfig;
+}
+
+/** Resolves a "cred:<name>" reference to a token, never logging it. */
+export interface SecretStore {
+	resolve(ref: string): string;
+}