olemd/forgejo-mcp-broker
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
forgejo-mcp-broker/.beads/issues.jsonl

27 lines
34 KiB
Text
Raw Normal View History

sec(oauth): phase-2 attack-path review (forgejo-mcp-broker-wgo) Structured review of every OAuth/auth handler against the standard attack catalog. Findings table added to design.md §8.2. Two real issues found and fixed: - Refresh-token replay race: tokenRefreshGrant read the row, validated it, then minted a new pair before unconditionally revoking the old refresh. Two concurrent /token requests with the same refresh would both pass validation and both mint a fresh pair — token-quota duplication and a hint to a stolen-refresh attacker. Fixed with the same atomic UPDATE rows-affected pattern already used for auth-code single-use. New TestToken_Refresh_ConcurrentReplay_OnlyOneSucceeds races two goroutines and verifies exactly one wins. - Permissive redirect_uri schemes: validateRedirectURI accepted any non-empty scheme, including javascript: and data:. Tightened to require https, http for loopback only, or a reverse-DNS private-use scheme per RFC 8252 §7.1. TestValidateRedirectURI updated to cover each variant including the rejected javascript:/data: cases. Items deferred to backlog (already filed): - Rate limits on /oauth/register and /oauth/token (-ttl) - --token-fd to close the /proc/<pid>/environ window (-1n2) - AES-GCM at-rest encryption of Forgejo tokens (-sd4) Closes forgejo-mcp-broker-wgo. Phase 2 complete. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-27 17:37:00 +02:00
{"id":"forgejo-mcp-broker-q4x","title":"Phase 5c: idle reaper + Forgejo token rotation + child respawn","description":"Reaper (30s tick) applies idle timeout. Rotation (1-min tick) refreshes Forgejo tokens expiring \u003c2min, SIGTERMs child, respawns on next request (design.md §6). Token revocation tears down sessions.","acceptance_criteria":"Clock-injected tests: idle kill, rotation triggers respawn, revocation tears down sessions. Smoke test: 20 concurrent sessions for 10min with mid-test rotations.","status":"closed","priority":1,"issue_type":"task","assignee":"Ole-Morten Duesund","owner":"olemd@glemt.net","created_at":"2026-04-24T15:45:18Z","created_by":"Ole-Morten Duesund","updated_at":"2026-04-27T15:32:44Z","started_at":"2026-04-27T15:27:46Z","closed_at":"2026-04-27T15:32:44Z","close_reason":"StartReaper shipped: idle eviction + Forgejo token rotation with atomic backend swap. Caught and fixed two -race issues (Done-watcher post-rotation; fakeSpawner test helper). 89.7% session coverage. Phase 5 complete.","dependencies":[{"issue_id":"forgejo-mcp-broker-q4x","depends_on_id":"forgejo-mcp-broker-pur","type":"blocks","created_at":"2026-04-24T17:45:31Z","created_by":"Ole-Morten Duesund","metadata":"{}"},{"issue_id":"forgejo-mcp-broker-q4x","depends_on_id":"forgejo-mcp-broker-t81","type":"blocks","created_at":"2026-04-24T17:45:31Z","created_by":"Ole-Morten Duesund","metadata":"{}"}],"dependency_count":2,"dependent_count":1,"comment_count":0}
feat(session): MCP session registry + spawn-on-initialize (forgejo-mcp-broker-t81) Adds internal/session.Registry, the MCP session glue that maps Mcp-Session-Id to a running forgejo-mcp child + bridge. Lifecycle: - First /mcp POST without Mcp-Session-Id: SpawnFunc creates a backend (in production: supervisor.Start + bridge.New); registry mints a 192-bit hex session id, attaches it to the response header, and dispatches the request to the new backend. - Subsequent POSTs with the header dispatch to the existing backend. - Unknown sids → 410 Gone (per MCP guidance, so clients re-initialise instead of retrying forever). - Sids are bound to the OAuth token that minted them: a different bearer probing a stolen sid gets 403, distinct from "your token is bad" (401) and "sid unknown" (410). Cleanup: - When backend.Done closes (child exited on its own — crash, OOM, user-driven shutdown), a goroutine reaps the entry. - Stop tears every session down on broker shutdown. The 30s idle reaper and Forgejo token rotation come in 5c. The Registry is decoupled from supervisor and bridge via SpawnFunc, so tests don't need to fork real processes — they hand the registry a fake that returns a controllable Backend. Also added oauth.ContextWithSession so the session tests can inject an oauth.Session into request contexts without standing up the full bearer-middleware chain. Tests: 83.3% coverage. Cover spawn-on-initialize, sid reuse, unknown sid, max-session cap with Retry-After, no-auth-context guard, sid hijack defense (token mismatch → 403), Done-channel reaping, and graceful Stop. Closes forgejo-mcp-broker-t81. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-27 17:24:25 +02:00
{"id":"forgejo-mcp-broker-ytw","title":"Phase 5b: bearer-token middleware on /mcp","description":"Middleware reads Authorization: Bearer \u003cmcp_token\u003e, resolves via store, attaches Forgejo access token to request context. 401 for missing/expired/revoked.","acceptance_criteria":"Table-driven tests: missing header, malformed, unknown token, expired, revoked, valid. Valid-token path puts Forgejo token on ctx via typed key.","status":"closed","priority":1,"issue_type":"task","assignee":"Ole-Morten Duesund","owner":"olemd@glemt.net","created_at":"2026-04-24T15:45:18Z","created_by":"Ole-Morten Duesund","updated_at":"2026-04-27T15:10:28Z","started_at":"2026-04-27T15:08:52Z","closed_at":"2026-04-27T15:10:28Z","close_reason":"Bearer middleware shipped: RequireBearer wraps protected handlers, looks up access_tokens by hash, rejects expired/revoked/unknown with RFC 6750 WWW-Authenticate. Session attached to ctx for downstream MCP endpoint use.","dependencies":[{"issue_id":"forgejo-mcp-broker-ytw","depends_on_id":"forgejo-mcp-broker-pur","type":"blocks","created_at":"2026-04-24T17:45:30Z","created_by":"Ole-Morten Duesund","metadata":"{}"}],"dependency_count":1,"dependent_count":1,"comment_count":0}
chore: bd export after closing -t81
2026-04-27 17:27:43 +02:00
{"id":"forgejo-mcp-broker-t81","title":"Phase 5a: session registry + spawn-on-initialize","description":"Map Mcp-Session-Id -\u003e supervisor.Child + user metadata. On first initialize for unknown sid, spawn forgejo-mcp with user's Forgejo token in env, bind to bridge. LastActive bumped per request.","acceptance_criteria":"Tests with fake supervisor + fake bridge cover: spawn-on-initialize, reuse for subsequent messages, unknown-sid returns 410, max-sessions cap enforced.","status":"closed","priority":1,"issue_type":"task","assignee":"Ole-Morten Duesund","owner":"olemd@glemt.net","created_at":"2026-04-24T15:45:17Z","created_by":"Ole-Morten Duesund","updated_at":"2026-04-27T15:24:32Z","started_at":"2026-04-27T15:11:43Z","closed_at":"2026-04-27T15:24:32Z","close_reason":"Session registry shipped: Mcp-Session-Id minting on initialize, sid reuse for follow-ups, 410 for unknown, 403 for sid-hijack, max-sessions cap with Retry-After, Done-channel reaping, graceful Stop. Decoupled from supervisor/bridge via SpawnFunc. 83.3% coverage.","dependencies":[{"issue_id":"forgejo-mcp-broker-t81","depends_on_id":"forgejo-mcp-broker-am1","type":"blocks","created_at":"2026-04-24T17:45:29Z","created_by":"Ole-Morten Duesund","metadata":"{}"},{"issue_id":"forgejo-mcp-broker-t81","depends_on_id":"forgejo-mcp-broker-pur","type":"blocks","created_at":"2026-04-24T17:45:30Z","created_by":"Ole-Morten Duesund","metadata":"{}"},{"issue_id":"forgejo-mcp-broker-t81","depends_on_id":"forgejo-mcp-broker-zuq","type":"blocks","created_at":"2026-04-24T17:45:28Z","created_by":"Ole-Morten Duesund","metadata":"{}"}],"dependency_count":3,"dependent_count":2,"comment_count":0}
feat(oauth): authorization-server endpoints (forgejo-mcp-broker-pur) Implements internal/oauth, the broker's OAuth 2.1 AS surface that Claude.ai (and other MCP clients) talk to. User authentication is delegated to upstream Forgejo via internal/forgejo. Endpoints: POST /oauth/register — RFC 7591 dynamic client registration GET /oauth/authorize — RFC 6749 + 7636 PKCE (S256 only) GET /oauth/callback — Forgejo redirects back here after consent POST /oauth/token — authorization_code + refresh_token grants POST /oauth/revoke — RFC 7009 Security model: - PKCE required, S256 only — plain method rejected per OAuth 2.1 - Every broker-issued access/refresh token stored as hex(sha256(plain)); plaintext leaves the broker exactly once in the /token response body - Refresh-token rotation: each refresh issues a new token pair and revokes the old refresh (RFC 6749 §10.4) - Auth-code single-use enforced atomically via UPDATE...WHERE used_at IS NULL with rows-affected check, blocking the concurrent-replay race - Issuer URL sourced from cfg.Issuer at construction time, never from inbound headers — prevents host-header injection on /.well-known metadata that ships in 2d - redirect_uri must match a registered URI exactly (no prefix/wildcard) Pending-authorization state (between /authorize and /callback) lives in an in-memory sync.Map with a 1-minute reaper goroutine. A broker restart drops them, forcing the user to re-authorize — acceptable trade-off versus introducing a fifth table. Tests: 81.0% coverage with ~20 cases across happy paths, every required- field error, PKCE failure, code-replay, refresh expiry/revocation, client-id and redirect-uri mismatches, Forgejo-side errors, and the reaper logic itself (internal test). Closes forgejo-mcp-broker-pur. The OAuth keystone is in place; phase 2c unblocks discovery (2d) and security review (2e), and combined with the existing supervisor + bridge it unblocks the session glue work in phase 5. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-27 17:04:34 +02:00
{"id":"forgejo-mcp-broker-xot","title":"Phase 4b: bridge integration test against real forgejo-mcp","description":"Drive the bridge with initialize -\u003e tools/list -\u003e tools/call get_forgejo_mcp_server_version against a real forgejo-mcp subprocess. Validates the opaque-pipe assumption.","acceptance_criteria":"Full handshake, tools/list returns expected set, tools/call returns a version string. Tagged as integration test if runtime exceeds 2s.","status":"closed","priority":1,"issue_type":"task","assignee":"Ole-Morten Duesund","owner":"olemd@glemt.net","created_at":"2026-04-24T15:45:16Z","created_by":"Ole-Morten Duesund","updated_at":"2026-04-27T14:28:39Z","started_at":"2026-04-27T14:10:04Z","closed_at":"2026-04-27T14:28:39Z","close_reason":"Bridge integration test passes against real forgejo-mcp 2.2.0: MCP handshake (initialize → notifications/initialized → tools/list → tools/call) round-trips through bridge cleanly. Fake Forgejo covers /api/v1/version and /api/v1/user probes. Phase 4 complete.","dependencies":[{"issue_id":"forgejo-mcp-broker-xot","depends_on_id":"forgejo-mcp-broker-am1","type":"blocks","created_at":"2026-04-24T17:45:28Z","created_by":"Ole-Morten Duesund","metadata":"{}"}],"dependency_count":1,"dependent_count":0,"comment_count":0}
test(bridge): integration test against real forgejo-mcp (forgejo-mcp-broker-xot) Spawns a real forgejo-mcp --transport stdio subprocess, runs the canonical MCP handshake (initialize → notifications/initialized → tools/list → tools/call get_forgejo_mcp_server_version) through the bridge, and verifies each step. Validates that the opaque-pipe assumption holds end-to-end: every JSON-RPC message round-trips correctly with no hand-rolled framing surprises. Binary discovery (skipped if none found): 1. $FORGEJO_MCP_BIN 2. ../../../forgejo-mcp/forgejo-mcp (sibling-repo built binary) 3. go build of ../../../forgejo-mcp into a temp dir Fake Forgejo (httptest.Server) covers the two probes the SDK and forgejo-mcp's testConnection do at startup: - GET /api/v1/version → returns 11.0.0 (>=1.11.0 satisfies SDK gate) - GET /api/v1/user → returns a minimal authenticated user blob Skipped under -short. Catch-all 404 handler logs unexpected probes so new SDK or forgejo-mcp behaviour surfaces clearly in test output. Closes forgejo-mcp-broker-xot. Phase 4 complete. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-27 16:28:32 +02:00
{"id":"forgejo-mcp-broker-31t","title":"Phase 3b: supervisor stress tests (FD/goroutine/zombie leak detection)","description":"1000 spawn/stop cycles under -race. Verify no FD leak, no goroutine leak (go.uber.org/goleak), no zombies (wait4 returns ECHILD when idle).","acceptance_criteria":"Cycle test passes under -race. FD count stable within a small constant. goleak detects no extra goroutines after test.","status":"closed","priority":1,"issue_type":"task","assignee":"Ole-Morten Duesund","owner":"olemd@glemt.net","created_at":"2026-04-24T15:45:15Z","created_by":"Ole-Morten Duesund","updated_at":"2026-04-27T14:04:42Z","started_at":"2026-04-27T12:00:32Z","closed_at":"2026-04-27T14:04:42Z","close_reason":"Stress tests in place: 1000-cycle spawn/reap and 200-cycle Stop both clean under -race; FD/goroutine/zombie deltas all single-digit. Driver: /bin/true and /bin/cat (helper-process recursion at scale exposed an unrelated Go pidfd interaction). Supervisor now defensively closes pipe handles post-Wait.","dependencies":[{"issue_id":"forgejo-mcp-broker-31t","depends_on_id":"forgejo-mcp-broker-zuq","type":"blocks","created_at":"2026-04-24T17:45:26Z","created_by":"Ole-Morten Duesund","metadata":"{}"}],"dependency_count":1,"dependent_count":0,"comment_count":0}
test(supervisor): stress tests for FD/goroutine/zombie leaks (forgejo-mcp-broker-31t) Adds two stress tests: TestStress_NoLeaksAcross1000Cycles — spawns and reaps 1000 children in sequence, asserts FD count, goroutine count, and zombie status are all stable. TestStress_StopMidLifecycle — 200 cycles that exercise the Stop path (SIGTERM via Close+Signal) rather than relying on natural exit. Bypassed by -short for the unit-test inner loop. Notable findings: * Using the helper-process pattern at this scale was a dead end. Each spawn re-execs the test binary, which inherits the parent's open FDs and runs Go's `testing` package init. Past a few hundred cycles the inner test binaries drag delivery of EOF on their inherited stderr pipe ends, leaving drainStderr goroutines blocked in bufio.ReadString even after Wait returned. Replacing the helper with /bin/true (for quick-exit) and /bin/cat (for echo-loop) sidesteps the recursion and is closer to the production case anyway: the broker spawns forgejo-mcp, not itself. * Defensively close stdout/stderr handles in supervisor's reap goroutine after cmd.Wait returns. cmd.StderrPipe is supposed to be closed by Wait, but under load the kernel doesn't always deliver EOF promptly through Go 1.26's pidfd-based wait path; an explicit Close ensures drainStderr exits and FDs aren't held longer than needed. Tests pass under -race with FD/goroutine deltas in single digits across 1000+200 cycles, and Wait4(-1) confirms no zombie children. Closes forgejo-mcp-broker-31t. Phase 3 complete. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-27 16:04:34 +02:00
{"id":"forgejo-mcp-broker-am1","title":"Phase 4a: internal/bridge JSON-RPC pipe + SSE writer","description":"Given a supervisor.Child: inbound HTTP JSON -\u003e newline-framed stdin; stdout lines -\u003e SSE frames. Handle client disconnect without killing the child.","acceptance_criteria":"Unit tests with mock Child that echoes: request/response round trip, multiple concurrent requests with correct id routing, client disconnect mid-stream.","status":"closed","priority":1,"issue_type":"task","assignee":"Ole-Morten Duesund","owner":"olemd@glemt.net","created_at":"2026-04-24T15:45:15Z","created_by":"Ole-Morten Duesund","updated_at":"2026-04-27T11:59:35Z","started_at":"2026-04-27T11:56:15Z","closed_at":"2026-04-27T11:59:35Z","close_reason":"Bridge shipped: per-id routing, SSE responses for request/reply messages, 204 for notifications, structured 4xx/5xx for malformed input. Decoupled from supervisor (takes pipes directly) for clean testing via io.Pipe. 90.0% coverage.","dependencies":[{"issue_id":"forgejo-mcp-broker-am1","depends_on_id":"forgejo-mcp-broker-zuq","type":"blocks","created_at":"2026-04-24T17:45:27Z","created_by":"Ole-Morten Duesund","metadata":"{}"}],"dependency_count":1,"dependent_count":2,"comment_count":0}
feat(deploy): rootless podman + Quadlet deployment (forgejo-mcp-broker-8yd) Adds a multi-stage Containerfile, Quadlet unit, and operator walkthrough for a production deploy. The broker spawns forgejo-mcp per session, so the image bundles both binaries — broker built from this repo, forgejo-mcp pinned via FORGEJO_MCP_VERSION build-arg (default 2.18.0). Image stages: 1. golang:alpine compiles the broker with ldflags-stamped buildinfo 2. golang:alpine clones forgejo-mcp at the pinned tag and compiles it 3. distroless static-nonroot copies both binaries; uid 65532 Persistent state via the named volume `fjmcp-state` mounted at /data. SQLite WAL + SHM sidecars live alongside broker.db on the same volume, so a container swap or image upgrade preserves all OAuth clients, issued tokens, and refresh-token history. Verified end-to-end: podman run --rm -d -v fjmcp-test-state:/data ... fjmcp-broker:test curl /healthz # store: ok, broker.db created podman stop fjmcp-test podman run --rm -d -v fjmcp-test-state:/data ... fjmcp-broker:test curl /healthz # store: ok, same broker.db ls volume → broker.db, broker.db-shm, broker.db-wal all present Quadlet unit (deploy/podman/fjmcp-broker.container) drops into ~/.config/containers/systemd/, reads secrets from a 0600 env file outside the unit, publishes :8080 on loopback for Caddy to front. Makefile gains `image` and `image-run` targets. README links to the new docs/deploy-podman.md walkthrough. Closes forgejo-mcp-broker-8yd. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-27 17:42:09 +02:00
{"id":"forgejo-mcp-broker-wgo","title":"Phase 2e: OAuth security review + attack-path tests","description":"Phase 2 exit gate. Review every handler for classic OAuth vulns (open redirect, code replay, mix-up, token leak in logs, host spoofing). Add at least one test per attack class. Update design.md §8 with findings.","acceptance_criteria":"Review checklist documented. Tests added for: PKCE mismatch, stale code, token absent from log attributes, bad redirect_uri, mismatched state, replay of used code.","status":"closed","priority":1,"issue_type":"task","assignee":"Ole-Morten Duesund","owner":"olemd@glemt.net","created_at":"2026-04-24T15:45:14Z","created_by":"Ole-Morten Duesund","updated_at":"2026-04-27T15:37:10Z","started_at":"2026-04-27T15:33:21Z","closed_at":"2026-04-27T15:37:10Z","close_reason":"Phase-2 attack-path review complete. Found and fixed 2 real issues: refresh-token replay race (atomic UPDATE rows-affected, new concurrent-replay test) and permissive redirect_uri schemes (now requires https | http-loopback | reverse-DNS RFC 8252). Findings table in design.md §8.2 cross-references each defence to its test. Phase 2 complete.","dependencies":[{"issue_id":"forgejo-mcp-broker-wgo","depends_on_id":"forgejo-mcp-broker-b2o","type":"blocks","created_at":"2026-04-24T17:45:26Z","created_by":"Ole-Morten Duesund","metadata":"{}"},{"issue_id":"forgejo-mcp-broker-wgo","depends_on_id":"forgejo-mcp-broker-pur","type":"blocks","created_at":"2026-04-24T17:45:25Z","created_by":"Ole-Morten Duesund","metadata":"{}"}],"dependency_count":2,"dependent_count":0,"comment_count":0}
feat(bridge): JSON-RPC pipe + SSE writer (forgejo-mcp-broker-am1) Adds internal/bridge: connects HTTP-side MCP clients to a stdio-side child via JSON-RPC framing. Decoupled from internal/supervisor — takes io.Writer + *bufio.Reader + done channel directly so it tests cleanly with io.Pipe pairs and could later wrap something other than a child process. Routing model: one reader goroutine consumes child stdout line-by-line. Each line is parsed only enough to extract the JSON-RPC `id` field (string/number/null kept as raw JSON, so `1` and `"1"` don't collide). HTTP requests register a per-id waiter channel before forwarding their body to the child; the reader delivers the response to whichever waiter matches. Concurrent in-flight requests are safe; a duplicate id while the first is still pending returns 409. HandleSSE response shapes: - request with id + child reply → 200 text/event-stream, one `event: message` SSE event carrying the JSON-RPC response - request without id (notification) → 204 No Content (no waiter needed; MCP notifications are fire-and-forget) - empty body → 400 - duplicate in-flight id → 409 - send-to-child fails → 502 - client disconnect mid-wait → bridge cleans up its waiter; child keeps running, other in-flight requests unaffected - child exits before reply → SSE `error` event with reason=child_exited Tests cover all of the above plus stale unsolicited replies, malformed lines from the child, and reader robustness across both. 90.0% coverage. The remaining gap is splitLines' empty-data branch (only reachable if the child sends a literal `\n` line). Closes forgejo-mcp-broker-am1. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-27 13:59:28 +02:00
{"id":"forgejo-mcp-broker-zuq","title":"Phase 3a: internal/supervisor managed stdio subprocess","description":"Child type: Start, Stop(ctx) with SIGTERM -\u003e grace -\u003e SIGKILL, Wait+reap goroutine (no zombies), stderr drainer with prefix. Protocol-agnostic.","acceptance_criteria":"Unit tests against an echo-loop helper: round trip, graceful stop, kill-after-grace, child-exits-on-own detection, stderr capture. Manual spawn of real forgejo-mcp --transport stdio works.","status":"closed","priority":1,"issue_type":"task","assignee":"Ole-Morten Duesund","owner":"olemd@glemt.net","created_at":"2026-04-24T15:45:14Z","created_by":"Ole-Morten Duesund","updated_at":"2026-04-27T11:41:07Z","started_at":"2026-04-27T11:32:54Z","closed_at":"2026-04-27T11:41:07Z","close_reason":"internal/supervisor shipped: Start/Stop/Done/ExitErr/Pid, SIGTERM-\u003egrace-\u003eSIGKILL escalation, mandatory wait-and-reap. Test uses TestMain helper-process pattern; coverage 89.6% on the testable surface.","dependency_count":0,"dependent_count":3,"comment_count":0}
feat(oauth): bearer-token middleware (forgejo-mcp-broker-ytw) Adds Authenticator.RequireBearer — http middleware that gates downstream handlers on a valid broker access token. Lookup path: 1. Read Authorization: Bearer <token> header. 2. SHA-256 the token, query access_tokens by token_hash. 3. Reject expired or revoked rows. 4. Build a Session (client_id, forgejo user info, upstream token, scopes) and attach to r.Context() under a typed key. Downstream handlers (the MCP endpoint shipping in 5a) read the upstream Forgejo token via SessionFromContext to spawn forgejo-mcp subprocesses scoped to the right user. Failures emit 401 with an RFC 6750 §3 WWW-Authenticate header carrying distinct error codes (invalid_request for missing/malformed headers, invalid_token with reason=expired/revoked/unknown for token problems). The body stays empty so a confused browser doesn't render auth errors; all detail rides in the header where compliant clients look for it. Tests: 90.9% on RequireBearer, 91.7% on lookupSession. Covers valid token, missing/wrong-scheme/empty Authorization, unknown token, expired token (clock-advanced past AccessTokenTTL), revoked token (via the public /oauth/revoke endpoint). Closes forgejo-mcp-broker-ytw. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-27 17:10:21 +02:00
{"id":"forgejo-mcp-broker-b2o","title":"Phase 2d: OAuth discovery endpoints (/.well-known/*)","description":"GET /.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server. Issuer URLs MUST derive from cfg.PublicURL, never inbound headers (host-header attack defense per design.md §8).","acceptance_criteria":"Responses validate against RFC 8414/9728 shapes. Issuer URL sourced from config only. supported_scopes matches cfg.ForgejoOAuthScopes.","status":"closed","priority":1,"issue_type":"task","assignee":"Ole-Morten Duesund","owner":"olemd@glemt.net","created_at":"2026-04-24T15:45:13Z","created_by":"Ole-Morten Duesund","updated_at":"2026-04-27T15:08:19Z","started_at":"2026-04-27T15:06:24Z","closed_at":"2026-04-27T15:08:19Z","close_reason":"Discovery endpoints shipped: /.well-known/oauth-authorization-server (RFC 8414) and /.well-known/oauth-protected-resource (RFC 9728). All URLs derived from cfg.Issuer; explicit Host-header-spoofing test verifies attacker-supplied hosts don't leak into metadata.","dependencies":[{"issue_id":"forgejo-mcp-broker-b2o","depends_on_id":"forgejo-mcp-broker-pur","type":"blocks","created_at":"2026-04-24T17:45:25Z","created_by":"Ole-Morten Duesund","metadata":"{}"}],"dependency_count":1,"dependent_count":1,"comment_count":0}
feat(supervisor): managed stdio subprocess (forgejo-mcp-broker-zuq) Adds internal/supervisor: a thin wrapper around os/exec that handles the zombie/leak/escalation concerns once, so phase-4 (bridge) and phase-5 (session glue) don't each have to re-derive them. Lifecycle (Stop): 1. Close stdin — well-behaved stdio servers exit on EOF 2. Send SIGTERM 3. Wait up to StopGrace (default 5s) for exit 4. SIGKILL if still alive Reaping is mandatory: a goroutine calls cmd.Wait so the kernel actually collects the child. Without it you accumulate zombies under N concurrent sessions. Tests exercise this via the helper-process pattern (TestMain re-execs the test binary in helper mode) — no shell or external binary dependency. Tests cover: empty Cmd validation, missing-binary error, echo round trip via stdin/stdout, stderr drainer collecting lines, SIGTERM-friendly graceful stop, SIGTERM-ignoring child escalating to SIGKILL (with a ready-on-stdout sync barrier so the test isn't racing the helper's signal.Notify), idempotent Stop, clean exit detection, non-zero exit detection, env override propagation. 89.6% coverage; remaining gap is unreachable-from-public-API defensive branches (pipe-creation failures under FD exhaustion, post-release Pid). Manual smoke test against a real `forgejo-mcp --transport stdio` is deferred to phase 4b's integration test (where it adds the most value). Closes forgejo-mcp-broker-zuq. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-27 13:41:00 +02:00
{"id":"forgejo-mcp-broker-b9i","title":"Phase 2b: internal/forgejo OAuth client","description":"Broker-side OAuth client for upstream Forgejo: authorize URL builder, code-to-token exchange, refresh_token grant, userinfo fetch, revoke. Used by AS callback and refresh machinery. Stateless; caller owns persistence.","acceptance_criteria":"Unit tests with httptest.Server fake Forgejo cover each grant plus error paths (wrong code, expired refresh, revoked token). No state persisted in this package.","status":"closed","priority":1,"issue_type":"task","assignee":"Ole-Morten Duesund","owner":"olemd@glemt.net","created_at":"2026-04-24T15:45:12Z","created_by":"Ole-Morten Duesund","updated_at":"2026-04-27T11:31:27Z","started_at":"2026-04-27T11:29:17Z","closed_at":"2026-04-27T11:31:27Z","close_reason":"internal/forgejo shipped: AuthorizeURL, ExchangeCode, Refresh, FetchUserInfo. Structured *forgejo.Error for OAuth failures (errors.As-friendly). 95.1% coverage. Stateless — caller owns persistence. Revocation deferred since upstream Forgejo lacks the endpoint.","dependency_count":0,"dependent_count":1,"comment_count":0}
feat(oauth): /.well-known discovery endpoints (forgejo-mcp-broker-b2o) Adds RFC 8414 (oauth-authorization-server) and RFC 9728 (oauth- protected-resource) metadata documents. Both URLs are derived from cfg.Issuer at construction time, never from inbound request headers. Test TestDiscovery_IssuerIgnoresHostHeader explicitly probes this — a malicious Host: evil.example.com value must not leak into the published metadata. Defense against the OAuth metadata-spoofing class starts at the discovery layer. Capabilities published reflect the actual OAuth surface: - response_types_supported = ["code"] - grant_types_supported = ["authorization_code", "refresh_token"] - code_challenge_methods_supported = ["S256"] (PKCE only, no plain) - token_endpoint_auth_methods_supported = ["none"] (PKCE-only public clients) Protected-resource metadata advertises /mcp as the resource; phase 5 will mount the gated MCP endpoint there. Closes forgejo-mcp-broker-b2o. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-27 17:08:12 +02:00
{"id":"forgejo-mcp-broker-pur","title":"Phase 2c: internal/oauth AS endpoints (register, authorize, callback, token, revoke)","description":"Five OAuth handlers per design.md §4.1. RFC 7591 DCR with ephemeral client IDs, authorize -\u003e Forgejo delegation, callback minting broker auth codes, token exchange with SHA-256 hashing at rest, revoke. PKCE S256 required.","acceptance_criteria":"End-to-end curl walkthrough from plan.md phase 2 passes. All tokens hashed at rest. Auth codes single-use, 10-min TTL. Rejects missing PKCE, non-S256, wrong verifier, expired codes/tokens. Handler coverage \u003e=80%.","status":"closed","priority":1,"issue_type":"task","assignee":"Ole-Morten Duesund","owner":"olemd@glemt.net","created_at":"2026-04-24T15:45:12Z","created_by":"Ole-Morten Duesund","updated_at":"2026-04-27T15:04:43Z","started_at":"2026-04-27T14:30:02Z","closed_at":"2026-04-27T15:04:43Z","close_reason":"OAuth AS shipped: register, authorize, callback, token (auth_code + refresh grants), revoke. PKCE S256 enforced. Tokens hashed at rest. Refresh rotation with old-token revocation. Auth-code single-use via atomic UPDATE rows-affected. 81% coverage. ~1700 LOC. Unblocks 2d, 2e, and is a key dep for 5a.","dependencies":[{"issue_id":"forgejo-mcp-broker-pur","depends_on_id":"forgejo-mcp-broker-b9i","type":"blocks","created_at":"2026-04-24T17:45:24Z","created_by":"Ole-Morten Duesund","metadata":"{}"},{"issue_id":"forgejo-mcp-broker-pur","depends_on_id":"forgejo-mcp-broker-cpb","type":"blocks","created_at":"2026-04-24T17:45:24Z","created_by":"Ole-Morten Duesund","metadata":"{}"}],"dependency_count":2,"dependent_count":5,"comment_count":0}
feat(forgejo): upstream OAuth client (forgejo-mcp-broker-b9i) Adds internal/forgejo: a stateless OAuth 2.1 client for upstream Forgejo. Covers what the broker AS needs: - AuthorizeURL: builds the user-agent redirect to /login/oauth/authorize - ExchangeCode: code → access+refresh tokens (PKCE verifier included) - Refresh: refresh_token grant (Forgejo rotates the refresh token) - FetchUserInfo: OIDC userinfo claims (sub, preferred_username, etc.) OAuth errors come back as a structured *forgejo.Error so the AS can distinguish "user must re-authenticate" (invalid_grant) from "transient network problem" via errors.As. Forgejo doesn't currently expose a token revocation endpoint, so revocation lives in the broker's own store — upstream tokens expire naturally. Defaults: - 30s HTTP timeout (Forgejo OAuth is sub-second when healthy) - User-Agent "fjmcp-broker" if not overridden - 64 KiB cap on response bodies (these endpoints return ~kilobytes) Tests: 95.1% coverage. httptest.Server fake Forgejo exercises every public method, every error shape (OAuth-formatted, plain {"message":...}, malformed JSON, missing required fields, network failure), and verifies form params hit the wire as expected. Closes forgejo-mcp-broker-b9i. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-27 13:31:19 +02:00
{"id":"forgejo-mcp-broker-cpb","title":"Phase 2a: OAuth tables migration","description":"Add migrations/0002_oauth_tables.sql creating clients, auth_codes, access_tokens, refresh_tokens per design.md §4.2. Broker tokens stored as SHA-256 hashes; Forgejo tokens cleartext (subprocess spawning requires them). See plan.md phase 2.","acceptance_criteria":"Migration applies on a fresh DB and is idempotent on reopen. Schema matches design.md §4.2. Tests verify every table and key column exists.","status":"closed","priority":1,"issue_type":"task","assignee":"Ole-Morten Duesund","owner":"olemd@glemt.net","created_at":"2026-04-24T15:45:04Z","created_by":"Ole-Morten Duesund","updated_at":"2026-04-27T11:28:20Z","started_at":"2026-04-27T11:26:17Z","closed_at":"2026-04-27T11:28:20Z","close_reason":"0002_oauth_tables.sql shipped: clients/auth_codes/access_tokens/refresh_tokens with cascading FKs, indexes on hot-path columns, and an oauth_schema_version marker. PRAGMA-driven tests verify columns; FK cascade tested in both directions.","dependency_count":0,"dependent_count":1,"comment_count":0}
feat(cmd/broker): wire config → log → store → httpserver (forgejo-mcp-broker-t37) Final phase-1 step: the broker now starts. run() parses config, opens the store, builds the httpserver, and blocks on signal.NotifyContext until SIGTERM/SIGINT fires, at which point it drains through httpserver.Run's graceful-shutdown path and closes the store. --version is handled before config.Load so operators can inspect a binary without providing the rest of the config. flag.ErrHelp is passed through so -h exits 0. Config failure exits 2; runtime failure exits 1. Integration tests build the binary once in TestMain and exercise three acceptance scenarios against it: - --version: prints build info, exits 0 - no config: exits nonzero with stderr listing every missing field - full startup: /healthz returns 200 with correct JSON; SIGTERM triggers clean exit within 2s Closes forgejo-mcp-broker-t37. Phase 1 complete. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-24 17:29:37 +02:00
{"id":"forgejo-mcp-broker-8ei","title":"Phase 1: internal/httpserver with /healthz and graceful shutdown","description":"Implement internal/httpserver: constructs a *http.Server bound to cfg.Listen, mounts GET /healthz (returns 200 with JSON build-info from the build-info package, including version, git revision, build date, and current store status), handles SIGTERM/SIGINT by initiating graceful shutdown with a configurable deadline (default 10s). Uses log/slog for structured JSON logs. Exposes a Run(ctx) error method that blocks until shutdown completes.","acceptance_criteria":"go test ./internal/httpserver passes; GET /healthz returns expected JSON; sending SIGTERM causes Run to return nil within 2 seconds after in-flight requests complete; slow in-flight request is allowed to finish within the deadline, then forcibly closed.","status":"closed","priority":1,"issue_type":"task","assignee":"Ole-Morten Duesund","owner":"olemd@glemt.net","created_at":"2026-04-24T14:46:20Z","created_by":"Ole-Morten Duesund","updated_at":"2026-04-24T15:26:43Z","started_at":"2026-04-24T15:24:09Z","closed_at":"2026-04-24T15:26:43Z","close_reason":"httpserver shipped: /healthz with store probe, graceful shutdown with force-close fallback, ExtraHandler extension point. 97.9% coverage. internal/log also implemented in the same commit (100% coverage).","dependencies":[{"issue_id":"forgejo-mcp-broker-8ei","depends_on_id":"forgejo-mcp-broker-n84","type":"blocks","created_at":"2026-04-24T16:46:19Z","created_by":"Ole-Morten Duesund","metadata":"{}"}],"dependency_count":1,"dependent_count":1,"comment_count":0}
chore: update beads export after creating -8yd (podman deployment)
2026-04-24 17:31:02 +02:00
{"id":"forgejo-mcp-broker-t37","title":"Phase 1: wire cmd/broker/main.go and integration test","description":"Final phase 1 task: wire config → log → store → httpserver in cmd/broker/main.go. Parse config, init slog, open store, start httpserver, wait for shutdown signal, close store, exit. Add an integration test under cmd/broker/ that builds the binary, runs it with a valid env + temp store path, curls /healthz, sends SIGTERM, verifies clean exit within 2s. This is the acceptance gate for phase 1.","acceptance_criteria":"make build; make test (incl. integration) pass; running the binary with missing config fails with a clear error; running with valid config serves /healthz; SIGTERM shuts down cleanly within 2s; /healthz JSON includes version, git revision, build date, and store OK status.","status":"closed","priority":1,"issue_type":"task","assignee":"Ole-Morten Duesund","owner":"olemd@glemt.net","created_at":"2026-04-24T14:46:20Z","created_by":"Ole-Morten Duesund","updated_at":"2026-04-24T15:29:44Z","started_at":"2026-04-24T15:27:58Z","closed_at":"2026-04-24T15:29:44Z","close_reason":"Main wired, signal.NotifyContext triggers shutdown cascade, integration tests green. Phase 1 complete: binary starts with valid config, serves /healthz JSON, shuts down cleanly on SIGTERM within 2s.","dependencies":[{"issue_id":"forgejo-mcp-broker-t37","depends_on_id":"forgejo-mcp-broker-8ei","type":"blocks","created_at":"2026-04-24T16:48:29Z","created_by":"Ole-Morten Duesund","metadata":"{}"},{"issue_id":"forgejo-mcp-broker-t37","depends_on_id":"forgejo-mcp-broker-9jh","type":"blocks","created_at":"2026-04-24T16:48:29Z","created_by":"Ole-Morten Duesund","metadata":"{}"},{"issue_id":"forgejo-mcp-broker-t37","depends_on_id":"forgejo-mcp-broker-9nq","type":"blocks","created_at":"2026-04-24T16:48:28Z","created_by":"Ole-Morten Duesund","metadata":"{}"},{"issue_id":"forgejo-mcp-broker-t37","depends_on_id":"forgejo-mcp-broker-n84","type":"blocks","created_at":"2026-04-24T16:48:28Z","created_by":"Ole-Morten Duesund","metadata":"{}"}],"dependency_count":4,"dependent_count":0,"comment_count":0}
feat(httpserver,log): /healthz, graceful shutdown, slog constructor Implements internal/httpserver and internal/log. httpserver (forgejo-mcp-broker-8ei): - Server struct owns the HTTP lifecycle; Run(ctx) blocks, Handler() returns the composed handler for unit tests - GET /healthz returns JSON with status, version, git_revision, build_date, and store probe result. Returns 503 when the store reports unhealthy - Signal handling delegated to the caller via ctx cancellation — main wires signal.NotifyContext, httpserver just responds to Done() - Graceful shutdown with a configurable deadline (default 10s). When the deadline expires, falls back to http.Server.Close() so lingering connections are forcibly terminated — http.Server.Shutdown alone never interrupts active connections - ExtraHandler extension point for the OAuth + MCP routes that land in phase 2 and phase 5, so the server doesn't need to be re-plumbed later log: - Small slog wrapper: New(w, debug) returns a JSON logger that stamps every record with service/version/git_rev for correlation across deployments - Discard() helper for tests Tests: 97.9% coverage on httpserver (all health states, wrong-method, ExtraHandler dispatch, ctx-cancel shutdown, shutdown-deadline force-close of hanging requests, missing-field errors), 100% on log. Closes forgejo-mcp-broker-8ei. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-24 17:26:32 +02:00
{"id":"forgejo-mcp-broker-9jh","title":"Phase 1: internal/store with SQLite open and embedded schema migrations","description":"Implement internal/store: wraps a modernc.org/sqlite connection, applies embedded schema migrations in order via a schema_migrations table, exposes a *sql.DB and a Close method. Phase 1 schema is just the migrations table itself plus a health_check row — real tables (clients, auth_codes, access_tokens, refresh_tokens) ship in phase 2. Store_path from config; creates parent dirs if missing; fails fast on unwritable path. Migrations embedded via embed.FS under internal/store/migrations/.","acceptance_criteria":"go test ./internal/store passes; opening a fresh db file applies migrations; re-opening is idempotent (no re-application, no errors); corrupt/locked files yield a clear error; Close() leaves no file handles open.","status":"closed","priority":1,"issue_type":"task","assignee":"Ole-Morten Duesund","owner":"olemd@glemt.net","created_at":"2026-04-24T14:46:19Z","created_by":"Ole-Morten Duesund","updated_at":"2026-04-24T15:22:53Z","started_at":"2026-04-24T15:11:36Z","closed_at":"2026-04-24T15:22:53Z","close_reason":"Store package shipped: modernc.org/sqlite, embed.FS migrations, WAL + FK pragmas, idempotent reopen, 90.1% coverage including bad-SQL rollback and record-step PK conflict.","dependencies":[{"issue_id":"forgejo-mcp-broker-9jh","depends_on_id":"forgejo-mcp-broker-n84","type":"blocks","created_at":"2026-04-24T16:46:19Z","created_by":"Ole-Morten Duesund","metadata":"{}"}],"dependency_count":1,"dependent_count":1,"comment_count":0}
feat(store): SQLite with embedded migrations (forgejo-mcp-broker-9jh) Implements internal/store on top of modernc.org/sqlite (pure-Go, no CGO). Open applies any pending migrations, Close releases the handle, Ping underpins /healthz. Migration design: - Files embedded via embed.FS under migrations/NNNN_name.sql - schema_migrations table tracks applied versions; re-open is a no-op - Each migration runs in its own transaction: no partial commits - loadMigrations takes an fs.FS so tests can inject synthetic migration sets to exercise rollback and conflict paths Connection pragmas (set via DSN so they apply to every pooled conn): - journal_mode=WAL — better reader/writer concurrency - foreign_keys=ON — off by default in SQLite, we always want them - busy_timeout=5000 — absorb brief contention without surfacing SQLITE_BUSY - synchronous=NORMAL — standard WAL pairing Phase 1 schema (0001_initial.sql) is minimal: a broker_meta table with a schema_version row. Real OAuth tables ship in phase 2. Tests: 90.1% coverage across public API and internal migration runner, including bad SQL rollback, PK-conflict record-step failure, and scan errors on malformed schema_migrations rows. Closes forgejo-mcp-broker-9jh. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-24 17:22:47 +02:00
{"id":"forgejo-mcp-broker-9nq","title":"Phase 1: internal/config package with flag + env parsing and validation","description":"Implement internal/config: a Config struct populated from CLI flags and environment variables (flags win), with validation at startup. Parse public-url, listen addr, forgejo-url, forgejo-oauth-client-id/secret/scopes, forgejo-mcp-binary, store-path, max-sessions, session-idle-timeout, debug. Validation: required fields present and non-empty; public-url parses as an https URL; store-path writable; idle-timeout positive; max-sessions positive. Unit tests cover happy path + every validation error branch.","acceptance_criteria":"go test ./internal/config passes with \u003e=90% coverage; missing required env produces a clear error message listing all missing fields; flag values override env; --help prints all config options.","status":"closed","priority":1,"issue_type":"task","assignee":"Ole-Morten Duesund","owner":"olemd@glemt.net","created_at":"2026-04-24T14:46:19Z","created_by":"Ole-Morten Duesund","updated_at":"2026-04-24T15:10:26Z","started_at":"2026-04-24T15:05:57Z","closed_at":"2026-04-24T15:10:26Z","close_reason":"Config package shipped with 94.1% coverage, handles all required-vs-optional fields, env/flag precedence, URL validation with loopback-http exception, and store-path writability. Full test suite green.","dependencies":[{"issue_id":"forgejo-mcp-broker-9nq","depends_on_id":"forgejo-mcp-broker-n84","type":"blocks","created_at":"2026-04-24T16:46:18Z","created_by":"Ole-Morten Duesund","metadata":"{}"}],"dependency_count":1,"dependent_count":1,"comment_count":0}
chore: update beads export after closing n84
2026-04-24 16:57:29 +02:00
{"id":"forgejo-mcp-broker-n84","title":"Phase 1: bootstrap Go project layout","description":"Set up the Go project skeleton so all subsequent phase 1 packages have somewhere to live. Initialize go.mod with module path kode.naiv.no/olemd/forgejo-mcp-broker, create the directory layout (cmd/broker, internal/config, internal/log, internal/store, internal/httpserver), add a Makefile with build/test/lint targets, and wire build-info injection (version, git revision, build date) via -ldflags.","acceptance_criteria":"go.mod present with correct module path; make build produces ./fjmcp-broker binary; make test and make lint targets exist and pass against an empty codebase; binary prints --version with injected build info.","status":"closed","priority":1,"issue_type":"task","assignee":"Ole-Morten Duesund","owner":"olemd@glemt.net","created_at":"2026-04-24T14:45:44Z","created_by":"Ole-Morten Duesund","updated_at":"2026-04-24T14:55:39Z","started_at":"2026-04-24T14:50:57Z","closed_at":"2026-04-24T14:55:39Z","close_reason":"Bootstrap complete: go.mod, Makefile, directory layout, ldflags-injected build info, --version flag all working. make build/test/lint pass.","dependency_count":0,"dependent_count":4,"comment_count":0}
chore: bd export after filing phase 2-7 + backlog issues (21 new)
2026-04-24 17:46:05 +02:00
{"id":"forgejo-mcp-broker-q6n","title":"Phase 7a: Claude.ai end-to-end validation on staging","description":"Stand up staging Forgejo + broker on a public hostname with real TLS. Register as a Claude.ai MCP connector. Walk through OAuth, tool discovery, tool invocation, session timeout, reconnect, Forgejo token refresh mid-session. Capture findings.","acceptance_criteria":"Claude.ai completes OAuth and lists tools. All forgejo-mcp tools invocable. 30-min idle session reconnects. Token refresh during active session invisible to user. docs/phase7-findings.md written.","status":"open","priority":2,"issue_type":"task","owner":"olemd@glemt.net","created_at":"2026-04-24T15:45:19Z","created_by":"Ole-Morten Duesund","updated_at":"2026-04-24T15:45:19Z","dependencies":[{"issue_id":"forgejo-mcp-broker-q6n","depends_on_id":"forgejo-mcp-broker-8yd","type":"blocks","created_at":"2026-04-24T17:45:34Z","created_by":"Ole-Morten Duesund","metadata":"{}"},{"issue_id":"forgejo-mcp-broker-q6n","depends_on_id":"forgejo-mcp-broker-q4x","type":"blocks","created_at":"2026-04-24T17:45:34Z","created_by":"Ole-Morten Duesund","metadata":"{}"},{"issue_id":"forgejo-mcp-broker-q6n","depends_on_id":"forgejo-mcp-broker-r2c","type":"blocks","created_at":"2026-04-24T17:45:35Z","created_by":"Ole-Morten Duesund","metadata":"{}"},{"issue_id":"forgejo-mcp-broker-q6n","depends_on_id":"forgejo-mcp-broker-t81","type":"blocks","created_at":"2026-04-24T17:45:33Z","created_by":"Ole-Morten Duesund","metadata":"{}"},{"issue_id":"forgejo-mcp-broker-q6n","depends_on_id":"forgejo-mcp-broker-ytw","type":"blocks","created_at":"2026-04-24T17:45:33Z","created_by":"Ole-Morten Duesund","metadata":"{}"}],"dependency_count":5,"dependent_count":0,"comment_count":0}
docs(deploy): Caddy front-end example + walkthrough (forgejo-mcp-broker-r2c) Adds deploy/caddy/Caddyfile and docs/deploy-caddy.md, the front-end half of the production deployment that pairs with deploy-podman.md. Caddyfile: - reverse_proxy with flush_interval -1 (mandatory for /mcp SSE) - structured JSON access log to a separate file - validated with `caddy validate` and formatted with `caddy fmt` - omits explicit X-Forwarded-{For,Proto,Host} since Caddy forwards them by default (caddy validate flags them as redundant) deploy-caddy.md walks operators through: - why a reverse proxy at all (TLS, SSE, future rate limits) - the host-header trap and why FJMCP_BROKER_PUBLIC_URL is the trusted source of issuer URLs (cross-references the existing TestDiscovery_IssuerIgnoresHostHeader regression) - SSE buffering as the most common deployment foot-gun - optional rate-limit recipe via caddy-ratelimit (defers to backlog issue -ttl) - troubleshooting for the four failure modes the broker has actually seen during dev: wrong issuer, buffered SSE, unreachable upstream, TLS conflict README updated to link both deploy guides and the deploy/ subtree. Closes forgejo-mcp-broker-r2c. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-27 17:49:25 +02:00
{"id":"forgejo-mcp-broker-r2c","title":"Phase 6a: Caddy front-end example + docs/deploy-caddy.md","description":"deploy/caddy/Caddyfile example and docs/deploy-caddy.md: TLS via Let's Encrypt, flush_interval -1 for SSE, X-Forwarded-* config (issuer URL still from broker config, never inbound headers).","acceptance_criteria":"Caddyfile works against a local broker (curl --resolve test). docs/deploy-caddy.md linked from README and deploy-podman.md. Explains host-header attack defense.","status":"in_progress","priority":2,"issue_type":"task","assignee":"Ole-Morten Duesund","owner":"olemd@glemt.net","created_at":"2026-04-24T15:45:19Z","created_by":"Ole-Morten Duesund","updated_at":"2026-04-27T15:42:37Z","started_at":"2026-04-27T15:42:37Z","dependencies":[{"issue_id":"forgejo-mcp-broker-r2c","depends_on_id":"forgejo-mcp-broker-8yd","type":"blocks","created_at":"2026-04-24T17:45:32Z","created_by":"Ole-Morten Duesund","metadata":"{}"}],"dependency_count":1,"dependent_count":1,"comment_count":0}
{"id":"forgejo-mcp-broker-8yd","title":"Deploy via rootless podman with persistent state","description":"Operators will deploy fjmcp-broker via rootless podman (user's stated preference over docker). The broker needs: (1) a working Containerfile that bundles both fjmcp-broker and a pinned forgejo-mcp binary so the broker can spawn subprocesses; (2) deployment artefacts that use a named podman volume for /data so the SQLite store persists across container restarts and image updates; (3) documentation an operator can follow end-to-end. Container must run as non-root, carry OCI labels (org.opencontainers.image.created, .revision) and /etc/build-info per the user's global container standards. Note: full usefulness depends on OAuth (phase 2) being implemented, but writing the Containerfile + deploy docs early forces runtime concerns (volumes, env vars, non-root) to surface before they become harder to fix.","design":"Container: multi-stage build. Stage 1 compiles fjmcp-broker with -trimpath and ldflags for build info. Stage 2 fetches forgejo-mcp at a pinned version (pinning matters — the broker subprocess contract depends on flags/env). Final stage uses distroless/static or alpine-nonroot, copies both binaries, USER 65532, EXPOSE 8080, ENTRYPOINT ['/usr/local/bin/fjmcp-broker']. Volume strategy: /data is a podman named volume ('fjmcp-state') mounted with the right uid. SQLite WAL files live inside it and survive restarts. Env vars for secrets via --env-file pointing to a 0600-permissioned file outside the repo. Build args: BUILD_DATE and GIT_REVISION, wired into labels and /etc/build-info. Quadlet unit: use Podman Quadlet (not the deprecated podman generate systemd) — drop fjmcp-broker.container under ~/.config/containers/systemd/, daemon-reload, start.","acceptance_criteria":"make image builds locally under rootless podman; podman run -p 8080:8080 -v fjmcp-state:/data --env-file .env fjmcp-broker:latest starts the broker and /healthz returns 200 with store=ok; stopping the container and starting a new one against the same fjmcp-state volume preserves schema_migrations rows; pulling a newer image and recreating the container preserves state; a Quadlet .container unit example brings the broker up under systemd --user; docs/deploy-podman.md walks a fresh operator through build → run → persistent state → secret injection → image upgrade → troubleshooting.","notes":"Related to plan.md Phase 6 (packaging). If we build a compose example later for non-podman users, it can piggyback off the same Containerfile. Caddy sits in front of this container — include a brief note about Caddy+flush_interval requirements for SSE, referencing design.md §7.2.","status":"closed","priority":2,"issue_type":"task","assignee":"Ole-Morten Duesund","owner":"olemd@glemt.net","created_at":"2026-04-24T15:30:50Z","created_by":"Ole-Morten Duesund","updated_at":"2026-04-27T15:42:17Z","started_at":"2026-04-27T15:37:37Z","closed_at":"2026-04-27T15:42:17Z","close_reason":"Containerfile + Quadlet unit + docs/deploy-podman.md shipped. Image builds under rootless podman; verified end-to-end that fjmcp-state volume preserves broker.db + WAL + SHM across container swap and that /healthz returns store: ok on the new container. Unblocks 6a (Caddy front-end docs).","dependency_count":0,"dependent_count":2,"comment_count":0}
chore: bd export after filing phase 2-7 + backlog issues (21 new)
2026-04-24 17:46:05 +02:00
{"id":"forgejo-mcp-broker-0sq","title":"Backlog: Forgejo Actions CI workflow","description":".forgejo/workflows/ci.yml running go vet, go test -race, go build, and golangci-lint on PRs and pushes to main. Block merge on failure.","acceptance_criteria":"CI green on main. PR failures block merge. Badge/status referenced in README.","status":"open","priority":3,"issue_type":"task","owner":"olemd@glemt.net","created_at":"2026-04-24T15:45:24Z","created_by":"Ole-Morten Duesund","updated_at":"2026-04-24T15:45:24Z","dependency_count":0,"dependent_count":0,"comment_count":0}
{"id":"forgejo-mcp-broker-ttl","title":"Backlog: rate limits on /oauth/register and /oauth/token","description":"design.md §8: Start with Caddy-level rate limits in the example Caddyfile (coarse but free). Add broker-side middleware only if operator experience shows Caddy is too coarse.","acceptance_criteria":"Caddy example extended with rate_limit directive. If broker-side added: unit tests cover quota exhaustion and reset windows.","status":"open","priority":3,"issue_type":"task","owner":"olemd@glemt.net","created_at":"2026-04-24T15:45:23Z","created_by":"Ole-Morten Duesund","updated_at":"2026-04-24T15:45:23Z","dependency_count":0,"dependent_count":0,"comment_count":0}
{"id":"forgejo-mcp-broker-1n2","title":"Backlog: upstream forgejo-mcp --token-fd flag","description":"Contribute --token-fd to upstream forgejo-mcp so broker passes token via inherited FD instead of env, closing /proc/\u003cpid\u003e/environ leak (design.md §11). Tracked in a sibling repo; this issue tracks our consumption side.","acceptance_criteria":"Upstream PR merged and broker switches to --token-fd, OR design.md §11 records that we accept the env exposure for now.","status":"open","priority":3,"issue_type":"task","owner":"olemd@glemt.net","created_at":"2026-04-24T15:45:22Z","created_by":"Ole-Morten Duesund","updated_at":"2026-04-24T15:45:22Z","dependency_count":0,"dependent_count":0,"comment_count":0}
{"id":"forgejo-mcp-broker-7fn","title":"Backlog: Prometheus /metrics endpoint","description":"design.md §10 item 5: session count, spawn/reap rates, OAuth endpoint latencies, Forgejo refresh success rate. Prometheus textfile format.","acceptance_criteria":"/metrics endpoint serves standard exposition. Optional auth/allow-list gate. Example Grafana dashboard JSON committed.","status":"open","priority":3,"issue_type":"task","owner":"olemd@glemt.net","created_at":"2026-04-24T15:45:22Z","created_by":"Ole-Morten Duesund","updated_at":"2026-04-24T15:45:22Z","dependency_count":0,"dependent_count":0,"comment_count":0}
{"id":"forgejo-mcp-broker-sd4","title":"Backlog: optional AES-GCM encryption of Forgejo tokens at rest","description":"design.md §4.2 notes Forgejo tokens are cleartext in SQLite. Evaluate application-layer AES-GCM with a key from env vs. rely on volume encryption only. Make a decision and record it.","acceptance_criteria":"If implemented: transparent encrypt/decrypt in store, key rotation path. If rejected: design.md §4.2 decision recorded with rationale.","status":"open","priority":3,"issue_type":"task","owner":"olemd@glemt.net","created_at":"2026-04-24T15:45:21Z","created_by":"Ole-Morten Duesund","updated_at":"2026-04-24T15:45:21Z","dependency_count":0,"dependent_count":0,"comment_count":0}
{"id":"forgejo-mcp-broker-5l2","title":"Backlog: dependency justification log (docs/deps.md)","description":"plan.md conventions: every Go dep gets an entry in docs/deps.md. Backfill modernc.org/sqlite (and transitive deps). Add a PR-template hook so future additions land with a justification.","acceptance_criteria":"docs/deps.md exists with entry for modernc.org/sqlite. Contributors guided to update when adding deps.","status":"open","priority":3,"issue_type":"task","owner":"olemd@glemt.net","created_at":"2026-04-24T15:45:20Z","created_by":"Ole-Morten Duesund","updated_at":"2026-04-24T15:45:20Z","dependency_count":0,"dependent_count":0,"comment_count":0}
{"id":"forgejo-mcp-broker-ca1","title":"Backlog: .golangci.yml config committed","description":"Commit a pragmatic golangci-lint config (errcheck, gosec, govet, ineffassign, staticcheck, unparam, etc). Aligns make lint output across machines.","acceptance_criteria":".golangci.yml in repo. make lint picks it up when golangci-lint installed. Ruleset documented in CONTRIBUTING or README.","status":"open","priority":3,"issue_type":"task","owner":"olemd@glemt.net","created_at":"2026-04-24T15:45:20Z","created_by":"Ole-Morten Duesund","updated_at":"2026-04-24T15:45:20Z","dependency_count":0,"dependent_count":0,"comment_count":0}
Reference in a new issue Copy permalink