diff --git a/.planning/notes/2026-11-20-mcp-oauth-backend-subject.md b/.planning/notes/2026-11-20-mcp-oauth-backend-subject.md new file mode 100644 index 00000000..009c395c --- /dev/null +++ b/.planning/notes/2026-11-20-mcp-oauth-backend-subject.md @@ -0,0 +1,31 @@ +--- +title: MCP OAuth with administrator subjects (backend-subject mode of sm-oauthserver-plugin) +date: 2026-11-20 +context: /msd-explore session. sm-bm-app's MCP accepts OAuth sign-in because it mounts golem15.oauthserver and its Nuxt site has a login page and the /connect consent page. sm-grzybyfunkcjonalne-app's MCP only accepts admin g15_ personal tokens; its tools are the Journal's backend-guarded blog tools, and the site has no frontend users at all. +--- + +# MCP OAuth with administrator subjects + +## Starting point + +- An MCP OAuth grant's subject is always a frontend user (`pact.MCPGrant.UserID`). Backend-guarded tools appear only when the grant carries the `backend` scope and that frontend user has a verified link to an administrator (`sm-user-plugin` `BackendLinks`, confirmed on `/link-admin` with a fresh sign-in; `pier/identity.go` `consentedBackendSubject`). That is decisions 5 and 6 of `2026-10-17-generic-mcp-module.md`, and it is built. +- sm-grzybyfunkcjonalne-app has none of what that path needs: `golem15.oauthserver` is not mounted (`config/mcp.yaml`: "no OAuth server on this site"), and the Nuxt site extends only the journal, menu, faq and seo layers. It has no login, no `/connect` and no `/link-admin` page. Its only real users are a few editors, and they are administrators. +- The cabana admin session is an HttpOnly cookie on the same origin (`admin/src/api/client.ts`). `sm-oauthserver-plugin` already renders its own consent and error pages in Go (`views/consent.html.tmpl`, `error.html.tmpl`) with branding. + +## Decisions + +1. **On grzyby, the OAuth sign-in authenticates an administrator.** There are no frontend users there. Giving editors frontend accounts plus a link only to reach their own admin tools would add a public login surface to a blog for no gain. +2. **It is an additive mode of `sm-oauthserver-plugin`, not a new framework module.** One authorization server keeps one implementation of code stores, PKCE, refresh rotation, replay-family revocation, the Clients and Branding screens, and pruning. The mode is off by default, so sm-bm-app, sm-demo-app and every other consumer stay unchanged (core plugin, no breaking changes). + +## Shape of the change (to be settled in discuss-phase) + +- **sm-oauthserver-plugin:** a config key (working name `mcp.subject: backend`, default `user`). In backend mode, `/oauth/mcp/authorize` recognises a signed-in administrator from the cabana cookie and sends an anonymous browser to the admin login with a return URL. Consent is a server-rendered Go page (reuse `consent.html.tmpl` and branding), not the Nuxt `/connect`. The grant records `BackendUserID` with no `UserID`. That needs an additive migration if `user_id` is NOT NULL, revocation when the administrator is deleted, deactivated or changes password, and a "Connected apps" list with revoke on cabana My account. The `Requires()` on `golem15.user` is a question for this mode only. grzyby mounts golem15.user anyway. +- **summercms.go `pier`:** a grant with only `BackendUserID` resolves straight to the backend subject (guard `backend`), with no link lookup. Tools are capped by the administrator's cabana permissions and the granted scopes, as for a `g15_` token with a scope limit. An administrator change or revocation fires `pact.MCPSubjectChanged`, so open sessions re-list or end. +- **sm-grzybyfunkcjonalne-app:** add `golem15.oauthserver` to `summer.yaml`. Add `config/golem15.oauthserver.yaml` with the backend mode, `mcp.enabled` and `mcp.resource`, which must equal `mcp.resource` in `config/mcp.yaml`. Add proxy rules so `/.well-known/oauth-authorization-server`, `/.well-known/oauth-protected-resource` and `/oauth/mcp/*` reach the Go binary and not Nuxt. `allow_personal_tokens: true` stays, so existing `g15_` agents keep working. Update DEPLOY.md. + +## Open questions + +- Can one application run both subject modes at once (for example the demo: frontend users and admins as separate MCP subjects), or is it one mode per application? +- Does consent let the administrator narrow the scopes (read only, no write), like the 32.1 `/connect` checkboxes? +- Do the Claude and ChatGPT connectors complete dynamic client registration and discovery unchanged against the backend-mode server? Not checked in this session. +- Admin-login brute-force and the Turnstile/2FA gates: does the authorize redirect reuse the cabana login unchanged, including the device or second-factor steps?