@cldmv/gh-broker 0.8.0 → 0.9.0

package/src/router.ts

@@ -1,299 +0,0 @@
-/**
- *
- *	@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-31T12:12:11-07:00 (1793473931)
- *	-----
- *	@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";
-import { unavailableReason } from "./availability.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";
-import { npmScaffold } from "./verbs/npm_scaffold.ts";
-import { NpmRegistry } from "./verbs/npm-registry.ts";
-import { GhcrService } from "./verbs/ghcr_push.ts";
-
-const GHCR_TOOLS = new Set(["ghcr_push", "ghcr_push_status", "ghcr_tags"]);
-
-/** 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>;
-	/** GHCR verbs run on config.ghcr's own credential, not the owner's GitHub PAT (created on first use). */
-	private ghcr?: GhcrService;
-
-	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.filter((rule) => !unavailableReason(rule, this.config, this.secrets));
-	}
-
-	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`);
-		}
-		// An optional integration that isn't set up hides its tools: refuse them the same way.
-		const unavailable = unavailableReason(rule, this.config, this.secrets);
-		if (unavailable) {
-			audit({ tool, decision: "deny", detail: `unavailable: ${unavailable}` });
-			throw new Error(`tool "${tool}" is not available on this broker: ${unavailable}`);
-		}
-		// The GHCR verbs authenticate with config.ghcr's own credential, never an owner's GitHub
-		// PAT, so they don't need (or touch) a config.owners entry.
-		if (GHCR_TOOLS.has(tool)) return this.callGhcr(tool, args, rule);
-		// 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;
-		}
-	}
-
-	/** GHCR verbs: config.ghcr checks the owner and image itself; no GitHub PAT is resolved. */
-	private async callGhcr(tool: string, args: Record<string, unknown>, rule: ToolRule): Promise<CallToolResult> {
-		const owner = extractOwner(args) ?? "";
-		const repo = typeof args.image === "string" ? `${owner}/${args.image}` : owner;
-		try {
-			this.ghcr ??= new GhcrService(this.config.ghcr, this.secrets);
-			const out = tool === "ghcr_push" ? await this.ghcr.push(args) : tool === "ghcr_tags" ? await this.ghcr.tags(args) : this.ghcr.status(args);
-			audit({ tool, owner, mode: rule.mode, repo, decision: "custom", ok: true });
-			return { content: [{ type: "text", text: JSON.stringify(out) }] };
-		} catch (err) {
-			audit({ tool, owner, mode: rule.mode, repo, decision: "custom", 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) }] };
-			}
-			case "npm_scaffold": {
-				const npm = this.config.npm!; // availability already required it
-				// The GitHub side only reads (repo metadata, package.json, workflow file), so it
-				// runs on the read PAT even though the verb is a write.
-				const octokit = new Octokit({ auth: this.secrets.resolve(this.config.owners[owner]!.read) });
-				const registry = new NpmRegistry({ token: this.secrets.resolve(npm.token), ...(npm.registry ? { registry: npm.registry } : {}) });
-				const out = await npmScaffold(args, { octokit, registry, scopes: npm.scopes });
-				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

@@ -1,167 +0,0 @@
-/**
- *
- *	@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-31T12:12:11-07:00 (1793473931)
- *	-----
- *	@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";
-import { ghcrCredRefs } from "./verbs/ghcr/config.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._-]+$/;
-
-/** A store over a reader that throws for a missing/empty credential. */
-function storeFrom(read: (name: string) => string): SecretStore {
-	return {
-		resolve: (ref) => read(credName(ref)),
-		has: (ref) => {
-			const name = credName(ref);
-			try {
-				read(name);
-				return true;
-			} catch {
-				return false;
-			}
-		}
-	};
-}
-
-/**
- * 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 REQUIRED credential (the owners' PATs, the App key) so a missing token
- * fails at startup, not on first request. Optional credentials (the npm token, the GHCR
- * credentials) are only
- * format-checked here: when one isn't stored, the tools that need it are hidden instead
- * (see availability.ts), and the rest of the broker runs normally.
- */
-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)));
-	}
-	if (config.npm) {
-		if (!config.npm.token.startsWith(CRED_PREFIX)) throw new Error(`secrets: config.npm.token must be a "cred:<name>" ref, got "${config.npm.token}"`);
-		assertSafeName(config.npm.token.slice(CRED_PREFIX.length));
-	}
-	// GHCR credentials are optional too: format-checked here, and the ghcr_* tools are hidden
-	// while none is stored (availability.ts).
-	for (const ref of ghcrCredRefs(config.ghcr)) credName(ref);
-}
-
-/** 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 storeFrom(read);
-}
-
-/** 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 storeFrom(read);
-}

package/src/server.ts

@@ -1,91 +0,0 @@
-/**
- *
- *	@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

@@ -1,128 +0,0 @@
-/**
- *
- *	@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-31T12:12:12-07:00 (1793473932)
- *	-----
- *	@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.
- */
-
-import type { GhcrConfig } from "./verbs/ghcr/config.ts";
-
-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;
-}
-
-/**
- * npm integration for `npm_scaffold`. Optional: without it the verb refuses. The token is a
- * granular access token created by the installer without 2FA bypass, so every write it makes
- * still needs a user-supplied one-time password.
- */
-export interface NpmConfig {
-	/** Credential reference (e.g. "cred:npm-token") for the granular access token. */
-	token: string;
-	/** Scopes the verb may create packages in, e.g. ["@cldmv"]. */
-	scopes: string[];
-	/** Registry base URL. Defaults to https://registry.npmjs.org. */
-	registry?: string;
-	/** Installer only: npm orgs the token is also granted org read-write on when it is created. */
-	tokenOrgs?: 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;
-	/** Optional npm integration (`npm_scaffold`). */
-	npm?: NpmConfig;
-	/** Optional GHCR push policy + credentials for the ghcr_* verbs (src/verbs/ghcr/config.ts). */
-	ghcr?: GhcrConfig;
-}
-
-/** Resolves a "cred:<name>" reference to a token, never logging it. */
-export interface SecretStore {
-	resolve(ref: string): string;
-	/** Whether an optional credential is stored (non-empty). Never throws for a missing one. */
-	has(ref: string): boolean;
-}