@cldmv/gh-broker 0.7.0 → 0.9.0

package/src/secrets.ts

@@ -1,137 +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-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

@@ -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,104 +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-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;
-}

package/src/upstream.ts

@@ -1,85 +0,0 @@
-/**
- *
- *	@Project: @cldmv/gh-broker
- *	@Filename: /src/upstream.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 { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
-import type { CallToolResult, Tool } from "@modelcontextprotocol/sdk/types.js";
-import type { Config } from "./types.ts";
-import type { Upstream } from "./router.ts";
-
-const CLIENT_INFO = { name: "cldmv-gh-broker", version: "0.1.0" };
-
-/**
- * Pool of MCP client connections to the hosted GitHub MCP — one per bearer token,
- * so each org's PAT drives its own upstream session. Connections are created lazily
- * and reused; the PAT is only ever set as an `Authorization: Bearer` header and is
- * never logged.
- */
-export class UpstreamPool implements Upstream {
-	private readonly url: URL;
-	private readonly clients = new Map<string, Promise<Client>>();
-
-	constructor(config: Config) {
-		this.url = new URL(config.upstream);
-	}
-
-	private connect(token: string): Promise<Client> {
-		const existing = this.clients.get(token);
-		if (existing) return existing;
-		const pending = (async (): Promise<Client> => {
-			const client = new Client(CLIENT_INFO);
-			const transport = new StreamableHTTPClientTransport(this.url, {
-				requestInit: { headers: { Authorization: `Bearer ${token}` } }
-			});
-			await client.connect(transport);
-			return client;
-		})();
-		// Don't cache a failed connect — let the next call retry.
-		pending.catch(() => this.clients.delete(token));
-		this.clients.set(token, pending);
-		return pending;
-	}
-
-	async forward(tool: string, args: Record<string, unknown>, token: string): Promise<CallToolResult> {
-		return this.withReconnect(token, (client) => client.callTool({ name: tool, arguments: args }) as Promise<CallToolResult>);
-	}
-
-	/** Fetch upstream tool schemas (owner-independent) to build the advertised catalog. */
-	async listToolsFor(token: string): Promise<Tool[]> {
-		return this.withReconnect(token, async (client) => (await client.listTools()).tools);
-	}
-
-	/**
-	 * Run an upstream op with a single transparent reconnect. The hosted MCP's
-	 * streamable-HTTP session can die server-side (idle-session expiry, upstream
-	 * restart) even though our cached client still looks connected — the next call
-	 * then fails with "invalid session". Rather than surface that first failure to
-	 * the agent (and leave it stuck until the whole broker restarts), evict the dead
-	 * client and retry ONCE with a fresh connection. A genuinely broken call (bad
-	 * token, real upstream error) fails the retry too and propagates.
-	 */
-	private async withReconnect<T>(token: string, op: (client: Client) => Promise<T>): Promise<T> {
-		for (let attempt = 0; ; attempt++) {
-			const client = await this.connect(token);
-			try {
-				return await op(client);
-			} catch (err) {
-				// Evict the (possibly stale) session so this retry / the next call reconnects.
-				this.clients.delete(token);
-				if (attempt >= 1) throw err;
-			}
-		}
-	}
-}