feat(mcp): /mcp/issue signs in with Forgejo and files as the person #5

Merged
claude merged 11 commits from feat/forgejo-signin into main 2026-11-15 15:16:30 -05:00
Collaborator

/mcp/issue now signs people in with their account on git.magicbean.dev, not Discord, and files the report with their own login, as if they had used the web form. This is the design in docs/architecture/index.md, built, plus one change to it: the AI never holds a forge token.

Stacked on #4 (docs/explanation): merging this brings #4's docs in.

The gate

  • A second authorization server. It is at /oauth/forgejo: issuer <gate>/oauth/forgejo, metadata at /.well-known/oauth-authorization-server/oauth/forgejo, endpoints /oauth/forgejo/{register,authorize,callback,token,revoke}. A route's resource metadata names its rule's server, so a client discovers which one to sign in with.

  • Policy. A rule gets "login": "forgejo", which gives the forge role. The new mode identity-and-token hands the service the identity token and, in X-Forge-Token, the person's forge token. The identity token holds that token's digest (cred), so a service takes the forge token only with the identity it was checked for. Validation refuses Discord roles on a Forgejo rule, the forge role on a Discord rule, and a Discord token handed on.

  • Sessions, not forge tokens. The client may be a public AI, run by its provider. The gate keeps the forge's tokens and answers the login with a random session token of its own:

    • It is good only at the gate.
    • It lasts FORGEJO_SESSION_SECONDS at most (default 3600), less if the forge's token expires first.
    • It comes with no refresh token.
    • It ends through RFC 7009 revocation (/oauth/forgejo/revoke), with the session token or the forge token.

    A forge token a client sends itself is refused.

  • Settings: FORGEJO_URL, FORGEJO_CLIENT_ID, FORGEJO_CLIENT_SECRET, FORGEJO_SCOPES (default read:user read:repository write:issue). The gate refuses to start when the policy uses Forgejo and the app isn't set.

  • Unchanged: the Discord sign-in, /mcp/grafana and every existing gate test.

mcp-issue

  • Files with the person's token, through a forgejo.Client without a token of its own (forgejo.WithToken). Forgejo's own permissions, bans and blocks apply.
  • Refusals: a 401/403 from the forge is now issues.ErrForbidden, and the AI gets it back as a refusal it can act on, not "the forge could not be reached".
  • Labels: Forgejo drops a non-writer's labels, so the crash bot sets the form's labels (LABEL_BOT_TOKEN, through the new issues.Labeler). A labelling failure is logged; the issue stays open.
  • The session ends with the report. After create_issue or comment_on_issue, mcp-issue revokes the session at the gate (REVOKE_URL), so the token the AI holds is dead. The tool's answer and the instructions tell the AI: one report per sign-in.
  • ISSUE_BOT_TOKEN is gone. The credit line under a report no longer names a Discord user; the forge shows the author.

⚠️ What clients see changes

  • /mcp/issue: it was never deployed, but its contract changes. It takes the forge role, not member, and needs X-Forge-Token.
  • Report text: "Reported by X (Discord)" becomes "Sent through Longshot's issue assistant…". The compatibility tests are updated to match (report, mcp-issue, e2e).

Tested

  • scripts/lint.sh: 0 issues.
  • scripts/docs.sh --check: current.
  • go test -race ./... passes, and coverage is at or above where it was in every package.
  • go test -race -tags e2e ./test/e2e/ passes. The real binaries run against a fake forge: discovery, the Forgejo login, a session (not the forge's tokens), /auth, the issue opened as the person, labelled by the bot, and the session over afterwards.
  • A local smoke run of the gate, mcp-issue and a forwardAuth stand-in: the 401 challenge, both metadata documents, and /authorize redirecting to the forge's sign-in.

To deploy (Bean-Ops, not in this PR)

  • An OAuth app on git.magicbean.dev, with redirect https://api.magicbean.gmatte.xyz/oauth/forgejo/callback. Its id and secret go in a SOPS secret for the gate.
  • The policy rule: {"prefix": "/mcp/issue", "login": "forgejo", "roles": ["forge"], "mode": "identity-and-token", "audience": "mcp-issue"}.
  • Traefik: X-Forge-Token in the /mcp/issue forwardAuth's authResponseHeaders, beside Authorization.
  • The crash bot: write on Longshot's issues, and its token in mcp-issue as LABEL_BOT_TOKEN.
  • deploy/mcp-issue.
  • To check against the real forge: whether git.magicbean.dev's Forgejo narrows OAuth tokens to the requested scopes.

🤖 Generated with Claude Code

`/mcp/issue` now signs people in with their account on git.magicbean.dev, not Discord, and files the report **with their own login**, as if they had used the web form. This is the design in `docs/architecture/index.md`, built, plus one change to it: **the AI never holds a forge token.** Stacked on #4 (`docs/explanation`): merging this brings #4's docs in. ## The gate - **A second authorization server.** It is at `/oauth/forgejo`: issuer `<gate>/oauth/forgejo`, metadata at `/.well-known/oauth-authorization-server/oauth/forgejo`, endpoints `/oauth/forgejo/{register,authorize,callback,token,revoke}`. A route's resource metadata names its rule's server, so a client discovers which one to sign in with. - **Policy.** A rule gets `"login": "forgejo"`, which gives the `forge` role. The new mode `identity-and-token` hands the service the identity token and, in `X-Forge-Token`, the person's forge token. The identity token holds that token's digest (`cred`), so a service takes the forge token only with the identity it was checked for. Validation refuses Discord roles on a Forgejo rule, the `forge` role on a Discord rule, and a Discord token handed on. - **Sessions, not forge tokens.** The client may be a public AI, run by its provider. The gate keeps the forge's tokens and answers the login with a random session token of its own: - It is good only at the gate. - It lasts `FORGEJO_SESSION_SECONDS` at most (default 3600), less if the forge's token expires first. - It comes with no refresh token. - It ends through RFC 7009 revocation (`/oauth/forgejo/revoke`), with the session token or the forge token. A forge token a client sends itself is refused. - **Settings:** `FORGEJO_URL`, `FORGEJO_CLIENT_ID`, `FORGEJO_CLIENT_SECRET`, `FORGEJO_SCOPES` (default `read:user read:repository write:issue`). The gate refuses to start when the policy uses Forgejo and the app isn't set. - **Unchanged:** the Discord sign-in, `/mcp/grafana` and every existing gate test. ## mcp-issue - **Files with the person's token**, through a `forgejo.Client` without a token of its own (`forgejo.WithToken`). Forgejo's own permissions, bans and blocks apply. - **Refusals:** a 401/403 from the forge is now `issues.ErrForbidden`, and the AI gets it back as a refusal it can act on, not "the forge could not be reached". - **Labels:** Forgejo drops a non-writer's labels, so the crash bot sets the form's labels (`LABEL_BOT_TOKEN`, through the new `issues.Labeler`). A labelling failure is logged; the issue stays open. - **The session ends with the report.** After `create_issue` or `comment_on_issue`, mcp-issue revokes the session at the gate (`REVOKE_URL`), so the token the AI holds is dead. The tool's answer and the instructions tell the AI: one report per sign-in. - **`ISSUE_BOT_TOKEN` is gone.** The credit line under a report no longer names a Discord user; the forge shows the author. ## ⚠️ What clients see changes - **`/mcp/issue`:** it was never deployed, but its contract changes. It takes the `forge` role, not `member`, and needs `X-Forge-Token`. - **Report text:** "Reported by `X` (Discord)" becomes "Sent through Longshot's issue assistant…". The compatibility tests are updated to match (report, mcp-issue, e2e). ## Tested - `scripts/lint.sh`: 0 issues. - `scripts/docs.sh --check`: current. - `go test -race ./...` passes, and coverage is at or above where it was in every package. - `go test -race -tags e2e ./test/e2e/` passes. The real binaries run against a fake forge: discovery, the Forgejo login, a session (not the forge's tokens), `/auth`, the issue opened as the person, labelled by the bot, and the session over afterwards. - A local smoke run of the gate, mcp-issue and a forwardAuth stand-in: the 401 challenge, both metadata documents, and `/authorize` redirecting to the forge's sign-in. ## To deploy (Bean-Ops, not in this PR) - **An OAuth app on git.magicbean.dev**, with redirect `https://api.magicbean.gmatte.xyz/oauth/forgejo/callback`. Its id and secret go in a SOPS secret for the gate. - **The policy rule:** `{"prefix": "/mcp/issue", "login": "forgejo", "roles": ["forge"], "mode": "identity-and-token", "audience": "mcp-issue"}`. - **Traefik:** `X-Forge-Token` in the `/mcp/issue` forwardAuth's `authResponseHeaders`, beside `Authorization`. - **The crash bot:** write on Longshot's issues, and its token in mcp-issue as `LABEL_BOT_TOKEN`. - **`deploy/mcp-issue`.** - **To check against the real forge:** whether git.magicbean.dev's Forgejo narrows OAuth tokens to the requested scopes. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
docs: explanation/, sequence diagrams of the crash reports, perf, the MCP sign-in and queries
All checks were successful
ci / lint (pull_request) Successful in 39s
ci / test (pull_request) Successful in 37s
ci / e2e (pull_request) Successful in 37s
ci / docs (pull_request) Successful in 31s
ci / image (pull_request) Successful in 9s
d4e6280fe4
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015KgSKp43znbyyPyDajp3Cm
docs(explanation): the crash flows as the current branches have them
All checks were successful
ci / lint (pull_request) Successful in 36s
ci / test (pull_request) Successful in 42s
ci / docs (pull_request) Successful in 24s
ci / e2e (pull_request) Successful in 39s
ci / image (pull_request) Successful in 9s
c622c854bf
Report manually (clipboard and the prefilled form) and Report automatically
(sent on the click) from the helper's crash window; always sending is the
earlier design's, marked not built.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015KgSKp43znbyyPyDajp3Cm
docs(explanation): the Python scripts are the player's side, the server is Go
All checks were successful
ci / test (pull_request) Successful in 29s
ci / lint (pull_request) Successful in 38s
ci / e2e (pull_request) Successful in 31s
ci / docs (pull_request) Successful in 33s
ci / image (pull_request) Successful in 11s
bf7c1c776f
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015KgSKp43znbyyPyDajp3Cm
docs(explanation): why one Go API: modularity, performance, robustness, adding a service
All checks were successful
ci / test (pull_request) Successful in 27s
ci / lint (pull_request) Successful in 36s
ci / e2e (pull_request) Successful in 30s
ci / docs (pull_request) Successful in 34s
ci / image (pull_request) Successful in 23s
2d76b23b06
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015KgSKp43znbyyPyDajp3Cm
docs(explanation): Traefik is the proxy, whichever it is
All checks were successful
ci / lint (pull_request) Successful in 31s
ci / test (pull_request) Successful in 35s
ci / e2e (pull_request) Successful in 32s
ci / docs (pull_request) Successful in 33s
ci / image (pull_request) Successful in 13s
b008bc1bfa
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015KgSKp43znbyyPyDajp3Cm
docs(explanation): Beanstalk, its integration points and ramifications
All checks were successful
ci / lint (pull_request) Successful in 37s
ci / test (pull_request) Successful in 37s
ci / e2e (pull_request) Successful in 42s
ci / docs (pull_request) Successful in 35s
ci / image (pull_request) Successful in 8s
c663325b60
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015KgSKp43znbyyPyDajp3Cm
docs(explanation): what's deployed, merged and counted, as of 15 Nov
All checks were successful
ci / lint (pull_request) Successful in 38s
ci / test (pull_request) Successful in 37s
ci / e2e (pull_request) Successful in 45s
ci / docs (pull_request) Successful in 35s
ci / image (pull_request) Successful in 11s
e86a7af3b8
Checked against Bean-Ops, Longshot, the launcher and Beanstalk:
- the relays went out across Bean-Ops 91e5f47 and db8d8e0, not 91e5f47 alone
- mcp-issue and the gate's policy file aren't deployed yet
- the performance statistics are on unmerged game and launcher branches
- Beanstalk's coordinator has 155 test functions

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
docs: /mcp/issue signs in with Forgejo, not Discord (planned)
All checks were successful
ci / lint (pull_request) Successful in 39s
ci / test (pull_request) Successful in 39s
ci / e2e (pull_request) Successful in 38s
ci / docs (pull_request) Successful in 30s
ci / image (pull_request) Successful in 6s
856b073faf
A player filing a bug already has an account on git.magicbean.dev, so
/mcp/issue's sign-in is planned to be the forge's: anyone with a forge
account gets in, no Discord server or role needed. The gate stays the
OAuth server MCP clients register with (Forgejo has no dynamic client
registration) and sends this route's sign-in to Forgejo, asking for
read:user only; mcp-issue still gets an identity token, and the bot
still opens the issue, "reported by @login". /mcp/grafana keeps the
Discord sign-in and the Big Bean role. Not built: the gate speaks
Discord only today.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
docs: /mcp/issue files with the person's own forge login (planned)
Some checks failed
ci / lint (pull_request) Successful in 38s
ci / test (pull_request) Successful in 56s
ci / e2e (pull_request) Has been cancelled
ci / docs (pull_request) Has been cancelled
ci / image (pull_request) Has been cancelled
739772d4d4
Once /mcp/issue signs in with Forgejo, the gate hands mcp-issue the
person's forge token beside the identity token, and the issue or comment
is opened as them: Forgejo's own permissions decide, and where they can't
write, they can't report. The crash bot sets the form's labels, which a
player can't, and the separate issue bot goes away. /mcp/grafana keeps
Discord, the Magic Bean server, the Big Bean role and the admins.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
docs(architecture): deployment.md, how Bean-Ops runs Longshot-api
All checks were successful
ci / lint (pull_request) Successful in 35s
ci / test (pull_request) Successful in 36s
ci / e2e (pull_request) Successful in 31s
ci / docs (pull_request) Successful in 31s
ci / image (pull_request) Successful in 9s
ff1c272731
From a commit to a running pod (CI on main, digests pinned in Bean-Ops,
SOPS decrypted by ArgoCD's sidecar), what runs in the magicbean namespace
and how Traefik reaches it, and who may use which MCP server: Discord and
the Big Bean role for /mcp/grafana, Forgejo and the person's own login
for /mcp/issue (planned). Linked from the architecture and the
explanation's index.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
feat(mcp): /mcp/issue signs in with Forgejo and files as the person
All checks were successful
ci / lint (pull_request) Successful in 50s
ci / test (pull_request) Successful in 1m3s
ci / e2e (pull_request) Successful in 41s
ci / docs (pull_request) Successful in 31s
ci / image (pull_request) Successful in 29s
ba7032c168
The gate gets a second authorization server, the forge's, at
/oauth/forgejo (metadata at /.well-known/oauth-authorization-server/
oauth/forgejo). A policy rule picks it with "login": "forgejo", gives the
forge role, and the identity-and-token mode hands the service the
person's forge token in X-Forge-Token, its digest bound into the
identity token.

The MCP client never holds the forge's tokens: the gate keeps them and
answers the login with a session of its own, an hour at most, no
refresh, ended through /oauth/forgejo/revoke once mcp-issue has filed a
report. A public AI's provider can't act as the person on the forge.

mcp-issue files with the person's token (ISSUE_BOT_TOKEN is gone): the
forge's own permissions apply, a 403 comes back as a refusal, and the
crash bot (LABEL_BOT_TOKEN) sets the form's labels. The Discord sign-in
and /mcp/grafana are unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
claude scheduled this pull request to auto merge when all checks succeed 2026-11-15 15:15:48 -05:00
claude merged commit 92a56667e8 into main 2026-11-15 15:16:30 -05:00
claude deleted branch feat/forgejo-signin 2026-11-15 15:16:30 -05:00
Sign in to join this conversation.
No reviewers
No labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
MagicBean-Mirror/Longshot-api!5
No description provided.