@cldmv/gh-broker 0.0.0-stage → 0.7.0

package/README.md

@@ -1,3 +1,186 @@
-# Temporary Holding Version
+# @cldmv/gh-broker
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A local **credential-routing MCP proxy** for GitHub. It lets an autonomous agent read and write GitHub issues/PRs across multiple orgs **without ever possessing a token** — the agent gets to *act*, never to *hold* the credential.
+
+## Why
+
+The hosted GitHub MCP authenticates with one token per server, so multi-org means many servers (tool-list bloat) and the token sits in an agent-readable config file. A classic PAT spans orgs but is coarse; a GitHub App gives bot attribution and can't drive the MCP. `gh` and raw PATs are readable by the agent (`gh auth token`, `cat ~/.claude.json`). None satisfy: **user identity + least-privilege + multi-org + one server + the agent cannot exfiltrate the secret.**
+
+## How
+
+A small daemon (this package) runs as a dedicated **`gh-broker` system user** and:
+
+- holds per-org **read-scoped** and **write-scoped** fine-grained PATs, read from an agent-unreadable secret store — `systemd-creds` (encrypted at rest, default) or a plaintext file, chosen at install — via `cred:` references in a token-free config, into memory only;
+- routes the right PAT by **repo owner + read/write mode** on each call;
+- exposes a **config-driven, default-deny** toolset — mostly **proxied** to GitHub's hosted MCP (which already does labels, type, issue fields, dedup), plus **custom verbs** for gaps the hosted MCP has no tool for, and **augmented** tools that extend a proxied tool's response in place. See [Key Features](#-key-features) and [docs/TOOLS.md](docs/TOOLS.md) for the full set;
+- talks to the agent over a **Unix socket** (bytes only; no token crosses).
+
+The agent (uid 1003, rootless docker, no passwordless sudo — verified) cannot read another user's mode-0400 secrets, so the boundary is real. The **agent-as-separate-user** model — the users, the bridge group, and the permissions that make the boundary real, as a reproducible example setup — is documented in [`docs/agent-user-model.md`](docs/agent-user-model.md).
+
+Full design + threat model: `~/.claude/designs/github-mcp-broker.md`.
+
+---
+
+## 🚀 Key Features
+
+### 🔒 **Use ≠ Possession**
+
+The agent can trigger a GitHub read/write; it can never hold the token that performs it. A separate system user owns the secret store and the daemon; the agent reaches it only over a permissioned Unix socket carrying MCP frames, never credential material.
+
+🔒 **For the full isolation model — users, groups, filesystem permissions, verified against this host — see [docs/agent-user-model.md](docs/agent-user-model.md)**
+
+### 🎯 **Default-Deny, Config-Driven Toolset**
+
+A tool not listed in `config.tools` is neither advertised nor executable. Adding an org is a config entry plus two credentials — no new server, no new agent-visible tool-list bloat. Each entry is `mode: "read"` or `"write"`, optionally `custom` (handled entirely locally) or `augment` (proxied, then enriched) — see below.
+
+### 📊 **CI Visibility Without Per-Call Log Fetches**
+
+`report_ci_status` answers "does this PR have failing checks" at whatever detail level you ask for — counts only by default, escalating to which job failed, which step failed, and a tail of the failing job's actual log — paying for that detail only on runs that are genuinely failing. The same status can ride inline on a normal `pull_request_read` via an opt-in `ciVerbosity` parameter.
+
+```json
+{ "owner": "cldmv", "repo": "droidsock", "pull": 35, "verbosity": 2 }
+```
+
+📊 **For every tier, the classification rules, and real verified examples, see [docs/TOOLS.md](docs/TOOLS.md#report_ci_status)**
+
+### 🏷️ **Cross-Repo Label Auditing**
+
+`report_unlabeled` finds every issue/PR with no labels — in one repo, or every repo an owner has — bounded by fan-out safety caps and a rate-limit floor that reads the token's own real limit rather than assuming one.
+
+🏷️ **Full parameter reference: [docs/TOOLS.md](docs/TOOLS.md#report_unlabeled)**
+
+### 🏷️ **Label Edits That Leave Other Labels Alone**
+
+The hosted MCP's `issue_write` takes `labels` as a full replacement, so changing one status label that way drops every other label on the issue. `issue_labels` edits labels one at a time instead: `add` and `remove` (one or several, combinable), `swap` (drop every `status: ` label and add `status: verified` in one call), and an explicit `set`. A misspelled label is refused rather than created, and the call returns the resulting set.
+
+```json
+{ "owner": "cldmv", "repo": "gh-broker", "issue_number": 117, "swap": { "prefix": "status: ", "to": "status: implemented" } }
+```
+
+🏷️ **Full parameter reference: [docs/TOOLS.md](docs/TOOLS.md#issue_labels)**
+
+### 🛡️ **Org-Wide Security Alerts**
+
+`report_security_alerts` lists every open Dependabot, CodeQL and secret-scanning alert — for one repo or across everything an owner has — using the org-level endpoints where the token can read them and a per-repo sweep where it can't. Secret values are never returned.
+
+🛡️ **Full parameter reference: [docs/TOOLS.md](docs/TOOLS.md#report_security_alerts)**
+
+### 🚢 **Release PR Discovery**
+
+`report_release_prs` finds every open release PR across an owner's repos and says which ones still lack their per-version changelog file — the list an agent needs during a mass update.
+
+🚢 **Full parameter reference: [docs/TOOLS.md](docs/TOOLS.md#report_release_prs)**
+
+### 🔧 **Extensible By Design**
+
+The broker presents its **own** MCP contract to the agent — a proxied tool's schema and response are not required to match the hosted MCP's exactly. Adding a custom verb or extending a proxied tool with new parameters follows a documented pattern, not a one-off hack.
+
+🔧 **How to add one: [docs/TOOLS.md § Extending this](docs/TOOLS.md#extending-this-adding-a-new-custom-verb-or-augmented-tool)**
+
+### 📦 **One-Command Install & Upgrade**
+
+`sudo node deploy/install.mjs` handles first install and every upgrade: builds under the checkout's own owner (no `chown`, ever), merges shipped config defaults over the deployed config, lets you choose how PATs are stored at rest, and runs a post-deploy smoke test.
+
+📦 **Full prerequisites, PAT scopes, and flags: [deploy/README.md](deploy/README.md)**
+
+---
+
+## ✨ What's New
+
+### Latest: v0.7.0 (October 2026)
+
+- **`issue_labels`: edit labels without replacing the set.** The new write verb adds, removes or swaps individual labels on an issue or PR (`swap { prefix: "status: ", to: "status: verified" }` moves a status in one call), so the priority, area and type labels next to it are never dropped the way they are by `issue_write`'s whole-set `labels`. Unknown label names are refused unless `create_missing` is set, and the call returns the resulting set.
+- **`issue_write` warns about the replacement.** Its advertised description now says that `labels` replaces the whole set and points at `issue_labels`.
+- **Dependencies.** MCP SDK 1.32.1 and a patched `proxy-addr` (CVE-2026-90711) at runtime; `@cldmv/configs` 1.3.0 and other dev-tooling bumps.
+- [View full v0.7.0 Changelog](https://github.com/CLDMV/gh-broker/blob/master/docs/changelog/v0/v0.7.0.md)
+
+### Recent Releases
+
+- **v0.6.1** (October 2026) — MCP SDK 1.32.0 (same-origin redirects only) and a refreshed vitest toolchain; no broker source changes ([Changelog](https://github.com/CLDMV/gh-broker/blob/master/docs/changelog/v0/v0.6.1.md))
+- **v0.6.0** (October 2026) — Compact per-repo roll-up, filters and flow tier for `report_security_alerts`, and release-readiness analysis for `report_release_prs` ([Changelog](https://github.com/CLDMV/gh-broker/blob/master/docs/changelog/v0/v0.6.0.md))
+- **v0.5.1** (October 2026) — The installer keeps the existing secrets backend instead of prompting on every upgrade ([Changelog](https://github.com/CLDMV/gh-broker/blob/master/docs/changelog/v0/v0.5.1.md))
+- **v0.5.0** (October 2026) — New `report_security_alerts` and `report_release_prs` verbs, and a permission 403 is no longer mistaken for a rate limit ([Changelog](https://github.com/CLDMV/gh-broker/blob/master/docs/changelog/v0/v0.5.0.md))
+
+📚 For the complete version history, see the [docs/changelog/](https://github.com/CLDMV/gh-broker/tree/master/docs/changelog/) folder.
+
+---
+
+## Calling a tool
+
+The agent's MCP client sees an ordinary `tools/call`; the broker resolves the credential, routes it, and (for custom/augmented tools) does the extra work in between:
+
+```json
+// tools/call
+{ "name": "report_ci_status", "arguments": { "owner": "cldmv", "repo": "droidsock", "pull": 35, "verbosity": 1 } }
+```
+
+```json
+// result
+{ "pull": 35, "summary": { "passed": 6, "failed": 1, "pending": 0 }, "failures": [{ "workflow": "🧪 CI Tests & Build", "job": "Build & Test (22.12)", "runId": 34787050719, "runUrl": "https://github.com/CLDMV/droidsock/actions/runs/34787050719", "conclusion": "failure" }] }
+```
+
+No token ever appears in the request, the response, or anywhere the agent can read. See [docs/TOOLS.md](docs/TOOLS.md) for every custom and augmented tool, with full parameter tables and real verified examples.
+
+---
+
+## Layout
+
+```
+src/
+  index.ts          entry — resolve paths, load config + secrets, start server
+  paths.ts          platform-neutral config/secrets path resolution
+  config.ts         load + validate the token-free config
+  secrets.ts        resolve cred refs from the secrets file (provider seam)
+  router.ts         allowlist (default-deny) + owner/mode → PAT + dispatch (custom/augment/forward)
+  upstream.ts       pool of MCP clients to the hosted GitHub MCP (per-token, Bearer)
+  catalog.ts        build the advertised tool list (real upstream schemas + custom + augmented)
+  server.ts         Unix-socket MCP server toward the agent (StdioServerTransport)
+  audit.ts          structured audit log (never tokens)
+  verbs/
+    report_unlabeled.ts  issues/PRs with no labels, one repo or org-wide
+    report_security_alerts.ts  open Dependabot/CodeQL/secret alerts, one repo or org-wide
+    report_release_prs.ts  open release PRs + whether each has its changelog file
+    report_ci_status.ts  tiered CI status for a PR or every open PR in a repo
+    rest-client.ts       shared rate-limit-floor + call-budget REST helpers
+    issue_labels.ts      add/remove/swap/set labels on an issue or PR (write PAT)
+    review_thread.ts     resolve/reply PR review threads (write PAT)
+    link_issue.ts         addClosingIssueReference (App token) — DEFERRED, not wired in
+deploy/
+  install.mjs       interactive installer — first install AND upgrade (sudo node)
+  install.sh        optional Linux bootstrap — set up node, then hand off to install.mjs
+  lib/              installer pieces (config merge, secret store, system ops, smoke test)
+  gh-broker.service systemd unit (hardened)
+  README.md         prerequisites + PAT scopes + install/upgrade/wiring
+docs/
+  TOOLS.md                reference for every custom/augmented tool, with real examples
+  deploy-architecture.md  config merge, secret store, node handling, installer flow
+  agent-user-model.md     the agent-as-separate-user isolation model (example setup)
+  changelog/              per-version release notes
+config.example.json  shipped defaults (token-free); merged into the deployed config
+```
+
+## 📚 Documentation
+
+- **[Tools Reference](docs/TOOLS.md)** — every custom and augmented tool: `report_unlabeled`, `report_security_alerts`, `report_release_prs`, `report_ci_status`, the `pull_request_read` `ciVerbosity` extension, `issue_labels`, `resolve_review_thread`/`reply_review_thread`, and how to add a new one
+- **[Agent-as-Separate-User Model](docs/agent-user-model.md)** — the isolation model behind "use ≠ possession": users, groups, filesystem permissions, verified against a real host
+- **[Deploy Architecture](docs/deploy-architecture.md)** — config merge, secret store backends, node handling, the installer's full flow
+- **[Install Guide](deploy/README.md)** — prerequisites, PAT scopes, install/upgrade command, flags
+- **[Changelog](docs/changelog/)** — per-version release notes
+
+## Status
+
+**Deployed and in production** — running under systemd, brokering live GitHub reads and writes across the configured org. The Unix-socket MCP server, the default-deny allowlist, owner/mode→PAT routing, and every custom/augmented tool in [docs/TOOLS.md](docs/TOOLS.md) are exercised in normal use — `report_ci_status` and the `pull_request_read` augmentation have both been verified against real failing CI data, not just mocked tests. `link_issue` (App-token-only) is implemented but deferred — see [`deploy/README.md`](deploy/README.md#enabling-link_issue-github-app--deferred). Install/upgrade with `sudo node deploy/install.mjs` (see [`deploy/README.md`](deploy/README.md)).
+
+## Install / build
+
+```sh
+npm ci
+npm run typecheck
+npm run build
+```
+
+## License
+
+Apache-2.0 © Shinrai / CLDMV
+
+Published on npm as [`@cldmv/gh-broker`](https://www.npmjs.com/package/@cldmv/gh-broker). It's a systemd daemon, not a typical CLI tool — install it with [`deploy/install.mjs`](deploy/README.md), not `npm install -g`.

package/config.example.json

@@ -0,0 +1,281 @@
+{
+	"listen": "unix:/run/gh-broker/gh-broker.sock",
+	"upstream": "https://api.githubcopilot.com/mcp/x/all",
+	"tools": [
+		{
+			"name": "list_issues",
+			"mode": "read"
+		},
+		{
+			"name": "issue_read",
+			"mode": "read"
+		},
+		{
+			"name": "search_issues",
+			"mode": "read"
+		},
+		{
+			"name": "list_issue_types",
+			"mode": "read"
+		},
+		{
+			"name": "list_issue_fields",
+			"mode": "read"
+		},
+		{
+			"name": "list_label",
+			"mode": "read"
+		},
+		{
+			"name": "list_pull_requests",
+			"mode": "read"
+		},
+		{
+			"name": "pull_request_read",
+			"mode": "read",
+			"augment": true
+		},
+		{
+			"name": "search_pull_requests",
+			"mode": "read"
+		},
+		{
+			"name": "search_repositories",
+			"mode": "read"
+		},
+		{
+			"name": "search_code",
+			"mode": "read"
+		},
+		{
+			"name": "actions_list",
+			"mode": "read"
+		},
+		{
+			"name": "actions_get",
+			"mode": "read"
+		},
+		{
+			"name": "get_job_logs",
+			"mode": "read"
+		},
+		{
+			"name": "list_code_scanning_alerts",
+			"mode": "read"
+		},
+		{
+			"name": "get_code_scanning_alert",
+			"mode": "read"
+		},
+		{
+			"name": "list_dependabot_alerts",
+			"mode": "read"
+		},
+		{
+			"name": "get_dependabot_alert",
+			"mode": "read"
+		},
+		{
+			"name": "list_secret_scanning_alerts",
+			"mode": "read"
+		},
+		{
+			"name": "get_secret_scanning_alert",
+			"mode": "read"
+		},
+		{
+			"name": "get_file_contents",
+			"mode": "read"
+		},
+		{
+			"name": "get_commit",
+			"mode": "read"
+		},
+		{
+			"name": "list_commits",
+			"mode": "read"
+		},
+		{
+			"name": "list_branches",
+			"mode": "read"
+		},
+		{
+			"name": "list_tags",
+			"mode": "read"
+		},
+		{
+			"name": "get_repository_tree",
+			"mode": "read"
+		},
+		{
+			"name": "list_releases",
+			"mode": "read"
+		},
+		{
+			"name": "get_latest_release",
+			"mode": "read"
+		},
+		{
+			"name": "check_dependency_vulnerabilities",
+			"mode": "read"
+		},
+		{
+			"name": "get_code_quality_finding",
+			"mode": "read"
+		},
+		{
+			"name": "get_discussion",
+			"mode": "read"
+		},
+		{
+			"name": "get_discussion_comments",
+			"mode": "read"
+		},
+		{
+			"name": "get_global_security_advisory",
+			"mode": "read"
+		},
+		{
+			"name": "get_label",
+			"mode": "read"
+		},
+		{
+			"name": "get_me",
+			"mode": "read"
+		},
+		{
+			"name": "get_notification_details",
+			"mode": "read"
+		},
+		{
+			"name": "get_release_by_tag",
+			"mode": "read"
+		},
+		{
+			"name": "get_tag",
+			"mode": "read"
+		},
+		{
+			"name": "get_team_members",
+			"mode": "read"
+		},
+		{
+			"name": "get_teams",
+			"mode": "read"
+		},
+		{
+			"name": "list_discussion_categories",
+			"mode": "read"
+		},
+		{
+			"name": "list_discussions",
+			"mode": "read"
+		},
+		{
+			"name": "list_global_security_advisories",
+			"mode": "read"
+		},
+		{
+			"name": "list_notifications",
+			"mode": "read"
+		},
+		{
+			"name": "list_org_repository_security_advisories",
+			"mode": "read"
+		},
+		{
+			"name": "list_repository_collaborators",
+			"mode": "read"
+		},
+		{
+			"name": "list_repository_security_advisories",
+			"mode": "read"
+		},
+		{
+			"name": "projects_get",
+			"mode": "read"
+		},
+		{
+			"name": "projects_list",
+			"mode": "read"
+		},
+		{
+			"name": "search_commits",
+			"mode": "read"
+		},
+		{
+			"name": "search_orgs",
+			"mode": "read"
+		},
+		{
+			"name": "search_users",
+			"mode": "read"
+		},
+		{
+			"name": "semantic_issue_similarity_search",
+			"mode": "read"
+		},
+		{
+			"name": "issue_write",
+			"mode": "write"
+		},
+		{
+			"name": "add_issue_comment",
+			"mode": "write"
+		},
+		{
+			"name": "sub_issue_write",
+			"mode": "write"
+		},
+		{
+			"name": "create_pull_request",
+			"mode": "write"
+		},
+		{
+			"name": "update_pull_request",
+			"mode": "write"
+		},
+		{
+			"name": "issue_labels",
+			"mode": "write",
+			"custom": true
+		},
+		{
+			"name": "resolve_review_thread",
+			"mode": "write",
+			"custom": true
+		},
+		{
+			"name": "reply_review_thread",
+			"mode": "write",
+			"custom": true
+		},
+		{
+			"name": "report_unlabeled",
+			"mode": "read",
+			"custom": true
+		},
+		{
+			"name": "report_security_alerts",
+			"mode": "read",
+			"custom": true
+		},
+		{
+			"name": "report_release_prs",
+			"mode": "read",
+			"custom": true
+		},
+		{
+			"name": "report_ci_status",
+			"mode": "read",
+			"custom": true
+		}
+	],
+	"owners": {
+		"cldmv": {
+			"read": "cred:cldmv-read",
+			"write": "cred:cldmv-write"
+		}
+	},
+	"defaultOwner": "cldmv"
+}

package/deploy/README.md

@@ -0,0 +1,92 @@
+# Deploying gh-broker
+
+One interactive installer does first-install and upgrade. Design and rationale: [`../docs/deploy-architecture.md`](../docs/deploy-architecture.md). The broker runs as a dedicated `gh-broker` service user, separate from the unprivileged user the agent runs as — that two-user split is the security boundary; see [`../docs/agent-user-model.md`](../docs/agent-user-model.md).
+
+## 0. Host prerequisites
+
+- **Node ≥ 20** — the only real prerequisite; the installer runs under it (`sudo node deploy/install.mjs`). If node isn't installed yet, the optional Linux bootstrap `sudo ./deploy/install.sh` sets up a system-wide nvm + node + the `/usr/local/bin/node` symlink, then hands off to the Node installer.
+- **`socat`** — the agent's stdio↔socket bridge. **`rsync`** — used to sync the build (falls back to a plain copy if absent). **`systemd`** with `systemctl`. **`sudo`** — used internally to build as the checkout's own owner (see step 5 below), not just to invoke the installer itself. Install what's missing (`apt install socat rsync sudo` etc.).
+
+The installer maintains `/usr/local/bin/node` as the single node indirection (CLI and service resolve the same link). Bumping node is re-pointing that symlink — which the installer does on every run.
+
+## 1. Mint the two CLDMV fine-grained PATs
+
+GitHub → Settings → Developer settings → **Fine-grained tokens** → Generate new token, **twice**. Resource owner: **CLDMV**. Repository access: **All repositories**.
+
+**`cldmv-read`** — Issues: Read, Pull requests: Read, Contents: Read, Metadata: Read (auto).
+**`cldmv-write`** — Issues: R/W, Pull requests: R/W, Contents: R/W, Metadata: Read (auto).
+
+No organization or admin permissions. If the org requires approval for fine-grained PATs, approve them in Org → Settings → Personal access tokens. The two-PAT split (read vs write) is a deliberate least-privilege control — see the design doc.
+
+## 2. Install (first install AND upgrade — same command)
+
+```sh
+sudo node deploy/install.mjs [agent-user]
+```
+
+`agent-user` defaults to `$SUDO_USER` (the account you ran `sudo` from). The installer walks the whole thing and is idempotent:
+
+1. checks prerequisites,
+2. **creates or confirms the agent user** (stops if it can't — no silent half-install),
+3. creates the `gh-broker` service user + `gh-broker-clients` bridge group, adds the agent user to it,
+4. points `/usr/local/bin/node` at the running node,
+5. builds `dist/` if it isn't already built, or rebuilds it if a prior run left it (or `node_modules/`) owned by someone other than the checkout's owner — the build itself runs via `sudo -u '#<uid>'` as whoever owns `deploy/install.mjs`, not as root, so the installer never leaves root-owned files behind in your checkout,
+6. regenerates the config by **merging** `config.example.json` with whatever is deployed (your data is preserved; new keys/allowlist changes from the repo arrive),
+7. **asks how to store the credentials** — `systemd-creds` (encrypted at rest, host-bound; recommended) or a plaintext `file` (`0640 root:gh-broker`; portable) — then stores the tokens in the chosen backend: it keeps existing creds, decrypts a legacy `systemd-creds` token when you switch to `file`, and **prompts only for what it can't find** (input hidden),
+8. validates the config with the real loader (`--check`),
+9. installs the unit, deploys `dist/`, restarts, and
+10. runs a **smoke test** (MCP handshake + a real read over the socket) → ✅/❌.
+
+### Unattended (single non-interactive command)
+
+Pass flags plus `--non-interactive` (`-y`) to skip every prompt: `--agent-user <name>`, `--secrets-provider systemd-creds|file`, `--create-agent-user`, and supply tokens via `--secrets-file <json>` (`{ "<cred-name>": "<token>" }`) or env `GH_BROKER_SECRET_<NAME>` (NAME upper-cased, non-alnum → `_`). Example:
+
+```sh
+sudo GH_BROKER_SECRET_CLDMV_READ=… GH_BROKER_SECRET_CLDMV_WRITE=… \
+  /usr/local/bin/node deploy/install.mjs --agent-user repo \
+  --secrets-provider systemd-creds --non-interactive
+```
+
+Migrating an existing `systemd-creds` install needs **no tokens** — `--secrets-provider systemd-creds --non-interactive` keeps the existing `.cred` files (nothing to prompt). `--help` lists every flag.
+
+**Upgrade** is just re-running it: config merged (edits kept), your previously-chosen storage backend pre-selected, existing tokens kept. You can **switch backends** on any run — pick `file` and it decrypts the existing `systemd-creds` tokens into the file (no re-entry); pick `systemd-creds` and it encrypts the tokens into `.cred` files. `launch.sh` is no longer used — remove it after a successful run: `sudo rm -f /opt/gh-broker/launch.sh` (and `sudo rm -rf /etc/gh-broker/creds` only if you've moved fully to the `file` backend).
+
+## Credential storage — your choice
+
+The installer asks which backend holds the tokens at rest:
+
+- **`systemd-creds`** (recommended, Linux): tokens are encrypted with a host/TPM-bound key (`.cred` files delivered via a unit drop-in into memory-only `$CREDENTIALS_DIRECTORY`). Encrypted at rest and resistant to backup/disk theft; not portable to another machine.
+- **`file`**: tokens in a plaintext JSON file, `0640 root:gh-broker`. Portable and platform-neutral; at-rest protection is filesystem permissions only.
+
+Either way the **agent user cannot read the tokens** (that's filesystem perms, not encryption) and the **config stays token-free**. The choice only affects at-rest protection vs portability. See [`../docs/deploy-architecture.md`](../docs/deploy-architecture.md).
+
+## 3. Point Claude at the broker
+
+The installer prints this; add it to the agent user's `~/.claude.json` `mcpServers`:
+
+```json
+"github": {
+	"type": "stdio",
+	"command": "socat",
+	"args": ["STDIO", "UNIX-CONNECT:/run/gh-broker/gh-broker.sock"]
+}
+```
+
+Re-login as the agent user first, so its `gh-broker-clients` membership is active.
+
+## Adding an org later
+
+Add an `owners` entry to `config.example.json` (name + `cred:<org>-read` / `cred:<org>-write` refs), then re-run the installer — the merge brings the new owner through, and it prompts for the new credentials. No code change.
+
+## Enabling `link_issue` (GitHub App) — DEFERRED
+
+> **Status: deferred / not wired in.** `link_issue` is implemented in `src/verbs/link_issue.ts` but its catalog (advertise) and router (dispatch) hooks are **commented out**, and it has no entry in `config.example.json`'s allowlist — so it is neither advertised nor callable. To turn it on: uncomment the `link_issue` blocks in `src/catalog.ts` and `src/router.ts` (and their imports), add `{ "name": "link_issue", "mode": "write", "custom": true }` to the tools allowlist, and configure a GitHub App.
+
+`link_issue` creates an explicit PR→issue closing reference via `addClosingIssueReference` — a mutation **not available to fine-grained PATs** (only App/classic tokens). It runs on a **GitHub App** installation token (`@octokit/auth-app`, from `config.app` = `{ appId, privateKey: "cred:gh-app-key" }` plus the owner's `installationId`). Store the App key like any other credential — as `gh-app-key` in the secrets file.
+
+## Verify no secret leaks
+
+- The agent user cannot read `/etc/gh-broker/` — the dir is `0750 root:gh-broker`; the config (`0640`) and, whichever backend is used, the tokens (systemd-creds `.cred` files `0400 root`, or the `file` backend's `secrets.json` `0640 root:gh-broker`) are unreadable to a non-member.
+- The config file holds **no tokens** — only `cred:` references; the tokens live in the separate secret store.
+- The socket carries MCP frames only.
+- `journalctl -u gh-broker` shows the audit log (tool, owner, mode, repo, result) — never tokens.

package/deploy/gh-broker.service

@@ -0,0 +1,57 @@
+[Unit]
+Description=CLDMV gh-broker — GitHub MCP credential-routing proxy
+Documentation=https://github.com/CLDMV/gh-broker
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=gh-broker
+Group=gh-broker
+
+# Secrets: the daemon resolves the config's cred: refs via the provider chosen at
+# install — systemd-creds (a unit drop-in adds LoadCredentialEncrypted, delivering
+# creds into $CREDENTIALS_DIRECTORY) or an agent-unreadable file (0640 root:gh-broker).
+# See secrets.ts / docs/deploy-architecture.md.
+
+# Socket dir /run/gh-broker (traversable), owned by the service user; the daemon
+# creates the socket there and sets it 0660 group=gh-broker-clients so the agent
+# user (a member of that group) can connect, while the token stays server-side.
+RuntimeDirectory=gh-broker
+RuntimeDirectoryMode=0755
+
+# Node comes from the maintained /usr/local/bin/node symlink (the installer points
+# it at the chosen node and re-points it on a bump), so no node version is pinned
+# here and there is no nvm resolution at start. The symlink is the single source of
+# truth, so CLI node == service node by construction. See docs/deploy-architecture.md.
+ExecStart=/usr/local/bin/node /opt/gh-broker/dist/index.mjs --config /etc/gh-broker/config.json
+Restart=on-failure
+RestartSec=2
+
+# ---- hardening (least privilege for a credential holder) ----
+NoNewPrivileges=true
+ProtectSystem=strict
+ProtectHome=true
+PrivateTmp=true
+PrivateDevices=true
+ProtectKernelTunables=true
+ProtectKernelModules=true
+ProtectControlGroups=true
+RestrictNamespaces=true
+RestrictSUIDSGID=true
+RestrictRealtime=true
+LockPersonality=true
+# NOTE: MemoryDenyWriteExecute is intentionally OMITTED — V8's JIT requires
+# writable→executable memory, and enabling it crashes Node at startup with
+# "Fatal OOM ... during deserialization".
+SystemCallArchitectures=native
+SystemCallFilter=@system-service
+SystemCallErrorNumber=EPERM
+ReadWritePaths=/run/gh-broker
+UMask=0077
+# Optional egress lockdown once GitHub ranges are pinned:
+# IPAddressDeny=any
+# IPAddressAllow=<github api ranges>
+
+[Install]
+WantedBy=multi-user.target