diff --git a/.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-CONTEXT.md b/.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-CONTEXT.md new file mode 100644 index 00000000..cf062dcd --- /dev/null +++ b/.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-CONTEXT.md @@ -0,0 +1,124 @@ +# Phase 32.2: MCP OAuth with administrator subjects - Context + +**Gathered:** 2026-11-20 +**Status:** Ready for planning + + +## Phase Boundary + +An application whose MCP tools are backend-guarded and which has no frontend users (first consumer: sm-grzybyfunkcjonalne-app, Journal tools only) can accept MCP OAuth sign-in as an **administrator**. The work is an additive, off-by-default backend-subject mode of `sm-oauthserver-plugin`, the `summercms.go` pieces it needs (pier resolution of administrator-only grants, a configurable consent handoff in wristband, an admin SPA consent route), and the grzyby wiring. The existing frontend-user MCP OAuth flow (sm-bm-app, sm-demo-app: Nuxt `/connect`, verified account link for backend tools) behaves exactly as before. + +Ends at a local-stack proof, patch tags, an app pointer bump and DEPLOY.md. The production deploy of grzybyfunkcjonalne.pl happens separately, on the user's go-ahead. + + + + +## Implementation Decisions + +### Framing (from the /msd-explore session, `.planning/notes/2026-11-20-mcp-oauth-backend-subject.md`) +- **D-01:** On a backend-mode application, the OAuth sign-in authenticates an administrator (`backend_users`). No frontend user and no account link is involved; the grant subject is the administrator. +- **D-02:** It is a mode of `sm-oauthserver-plugin`, not a new framework module. Code stores, PKCE, refresh rotation, replay-family revocation, the Clients and Branding screens and pruning are reused. Every change to the plugin is additive. `sm-oauthserver-plugin`, `sm-user-plugin`, `sm-journal-plugin` and the framework are shared by many apps, so no breaking changes. — **Reversibility:** costly — the mode becomes a public config key and a grant shape other apps may adopt. + +### Consent surface +- **D-03:** Consent lives in the **admin SPA** (boardwalk, `admin/`) as a route under the admin prefix (working shape `//connect?request=…`), not as a Go-rendered page and not in Nuxt. Reason: the admin cookie `summer_admin` is `Path=`, `SameSite=Strict` (`modules/cabana/auth.go` `sessionCookie`). It never reaches `/oauth/mcp/authorize` at the root, and it isn't sent on the cross-site navigation from the MCP client. A route inside the SPA gets it on its same-origin API fetches, and the SPA router already sends an anonymous visitor to login with `?redirect=` and back (`admin/src/app/router.ts` `safeRedirect`). Login gates (2FA, Turnstile) therefore apply unchanged. +- **D-04:** wristband's MCP authorize handoff, currently hard-wired to `{issuer}/connect?request=` (`modules/wristband/authorize.go`), becomes configurable so backend mode can point it at the admin SPA route. The default stays `/connect`. — **Reversibility:** costly — wristband option and oauthserver config key are public API. +- **D-05:** The consent screen is a **standalone full-screen card** like `LoginView` (no sidebar or top bar). It shows the client name, the redirect host, the scope checkboxes and the refresh choice, with Allow and Deny. +- **D-06:** The consent screen shows the signed-in administrator ("Signed in as ()") with a **"use another account"** action. That action signs out and goes back to login with the same redirect, like the 19.4 OIDC switch-account flow. + +### Mode per application +- **D-07:** The mode is **exclusive per application for now**: a config key on `golem15.oauthserver` (working name `mcp.subject`, values `user` (default) and `backend`). One issuer, one `/mcp` resource, one consent surface per app. Pick a config shape that doesn't block coexisting modes later (see Deferred). — **Reversibility:** costly — config key name and values become part of the plugin's contract. +- **D-08:** `sm-oauthserver-plugin` keeps `Requires() = ["golem15.user"]` in backend mode. grzyby mounts golem15.user anyway, and the core plugin's dependency graph stays untouched. + +### Consent choices +- **D-09:** The scopes on consent are the **cabana token-scope catalog**, the same as `g15_` personal-token creation (`modules/cabana/token_scopes.go`: `*`, `admin:read` and the plugin-declared `TokenScopes()` such as the Journal's). A backend-mode grant gets the same `bouncer.ScopeLimit` a personal token with those scopes would (`cabana.ScopeLimitFor`). An OAuth agent and a `g15_` token with equal scopes therefore see and can call the same tools. This differs from today's linked-admin grants, which carry no scope limit (`modules/pier/backend_guard.go` `principal` applies the limit only when `ClientID == ""`). That existing behaviour must not change for user-mode grants. In backend mode the advertised `scopes_supported` (wristband metadata and pier's protected-resource metadata) come from this catalog. +- **D-10:** `offline_access` appears as a **"Stay connected" checkbox, ticked by default**, as in 32.1's `/connect`. Unticked, the agent gets no refresh token and re-consents when the access token expires. +- **D-11:** Scopes the administrator can't use (they lack the scope's permissions) are **hidden** from the consent screen. A request that asked for them gets only what is ticked and granted. + +### Revocation and visibility +- **D-12:** Each administrator lists and revokes their own MCP connections in a **My account section** (`pact.HasAccountContributions`). A superuser, or an administrator holding a new oauthserver permission, can see and revoke any administrator's connections on the existing oauthserver admin screens. +- **D-13:** An administrator's MCP grants (access and refresh tokens) are revoked, and their open MCP sessions ended (`pact.MCPSubjectChanged`), on: **delete, deactivate, password change, role or permission change** (including the role's own permissions changing) and **"sign out everywhere"** where cabana offers it. Role and permission changes revoke the grants rather than only re-listing tools. + +### Rollout +- **D-14:** sm-grzybyfunkcjonalne-app mounts `golem15.oauthserver` in backend mode with only the MCP authorization server enabled (no OIDC provider surface), keeps `allow_personal_tokens: true`, routes `/.well-known/oauth-authorization-server`, `/.well-known/oauth-protected-resource` and `/oauth/mcp/*` to the Go binary, and documents it in DEPLOY.md. Proof: on a local stack, an MCP client completes discovery, dynamic registration, admin sign-in, consent and a Journal tool call. The production deploy is not part of this phase. + +### Claude's Discretion +- How backend-mode grants are stored. The current tables have `user_id INTEGER NOT NULL REFERENCES users(id)` on access tokens, auth codes and consents (`updates/202610190001_create_golem15_oauthserver_tables.go`). Options: nullable `user_id` via an additive migration with the readers that assume it hardened, or companion rows keyed on `backend_user_id`. Constraints: additive only, user-mode rows and queries unchanged, and the per-user advisory lock and revocation cascade keep working. +- How pier represents an administrator-only grant (for example `pact.MCPGrant` with `UserID` 0 and `BackendUserID` set, resolved straight to the `backend` subject, with no `MCPLinkedBackendResolver` lookup). Additive to `pact`. +- Where the consent JSON API lives (oauthserver routes under the admin API, authenticated by the cabana guard) and how the framework SPA route renders a consent screen whose data a plugin serves. The admin SPA can't load plugin Vue code, so the screen is framework code against a JSON contract. +- The name of the new "manage any administrator's MCP connections" permission and its default role (none, like `golem15.users.manage_backend_links`). +- Whether `*` and `admin:read` are shown as plain scope checkboxes or as "full access" / "read only" presets above the plugin scopes. + + + + +## Canonical References + +**Downstream agents MUST read these before planning or implementing.** + +### Decisions behind this phase +- `.planning/notes/2026-11-20-mcp-oauth-backend-subject.md`: why administrator subjects, why an oauthserver mode, first change list and open questions. D-03 refines its "server-rendered Go consent page": consent moves to the admin SPA because of the cookie scope. +- `.planning/notes/2026-10-17-generic-mcp-module.md`: the original MCP shape (one connector per person, verified account link, Journal stays on `backend_users`). Backend mode is the second path next to it, not a replacement. +- `.planning/notes/oauth2-wristband-direct-port.md`: wristband's design constraints (RFC behaviours that must stay byte-exact). +- `.planning/ROADMAP.md` Phase 32.2: goal and success criteria. Phases 32.1, 19.7 and 19.4 for the prior MCP OAuth, MCP module and OIDC decisions. + +### Prior phase context +- `.planning/phases/32.1-mcp-oauth-for-plugin-apps-declared-scopes-mcp-subject-on-con/`: declared scopes, MCP consent records, per-client revoke, the `/connect` checkboxes. +- `.planning/phases/19.4-*/`: wristband OIDC flavour, switch-account flow, consent store, sm-oauthserver-plugin creation. + +### Module and plugin docs +- `modules/wristband/README.md`, `modules/pier/README.md`, `modules/cabana/README.md`, `modules/boardwalk/README.md` +- `../sm-oauthserver-plugin/README.md` +- `../sm-user-plugin/README.md` §"Frontend account link for administrators" and §"MCP guard": how user-mode backend grants work today (must stay unchanged). +- `../sm-journal-plugin/mcp.go`: the backend-guarded tools grzyby exposes. +- `../sm-grzybyfunkcjonalne-app/config/mcp.yaml`, `summer.yaml`, `DEPLOY.md`; `../sm-bm-app/config/golem15.oauthserver.yaml` (a user-mode configuration example). + + + + +## Existing Code Insights + +### Reusable Assets +- `wristband.Server.Authorize` / MCP code, token, register handlers: the whole OAuth protocol side; only the handoff URL and subject binding change. +- `sm-oauthserver-plugin/classes/mcp_backend_binding.go` (`WithConsentedBackend`, `backendBinding`): already carries `BackendUserID` from consent onto codes and tokens; backend mode sets it without the `backend` scope or a user. +- `sm-oauthserver-plugin/controllers/mcp_consent_api.go` (`MCPConsentShow`, `MCPConsentDecide`): the consent JSON the Nuxt `/connect` uses; the admin-side counterpart mirrors it under the cabana guard. +- `cabana.ScopeLimitFor`, the token-scope catalog and `cabana.BackendPrincipal`: scope limits and principal loading for D-09. +- `admin/src/views/LoginView.vue`, `admin/src/app/router.ts` (`safeRedirect`, login redirect): standalone screen pattern and sign-in round trip for D-03, D-05, D-06. +- `pact.HasAccountContributions` / `modules/cabana/account_contributions.go`: My account section for D-12 (sm-user-plugin's `frontend_account` section is the example). + +### Established Patterns +- `pier/identity.go`: `identityResolver` builds the backend subject; `consentedBackendSubject` is the user-mode path that must stay as is. `LinkCacheTTL` and the `MCPSubjectChanged` events show how changes propagate. +- `pier/backend_guard.go`: the scope limit applies only to personal-token subjects today. Backend-mode OAuth subjects need it too (D-09) without changing user-mode linked grants. +- Off-by-default modes keep every existing test green (32.1 and 19.4 releases: patch tags for the framework and the plugin). + +### Integration Points +- `golem15.oauthserver` config: new subject mode key, consent handoff path. +- cabana events for D-13 (delete, deactivate, password change, role and permission saves, sign out everywhere). Some may need new additive hooks in cabana. +- grzyby proxy (nginx/Caddy in `deploy/`) for the OAuth paths. Today Nuxt answers everything except the Go API prefixes. + + + + +## Specific Ideas + +- The consent screen should look like an authorization step, not an admin page: same card style as the admin login. +- OAuth agents and `g15_` tokens with equal scopes must behave identically. That's the mental model for administrators. +- Revocation is strict: any role or permission change ends the grants instead of quietly re-listing tools. + + + + +## Deferred Ideas + +- **Both subject modes on one application** (for example the demo offering member and administrator connectors, through two resources or a choice at authorize). Exclusive per app for now (D-07); the config shape should leave room for it. +- **Production deploy of grzybyfunkcjonalne.pl with OAuth on** and a live check with the Claude connector: after the phase, on the user's go-ahead. +- **Backend mode without golem15.user** for apps that mount no user plugin (D-08 keeps the dependency). + +### Reviewed Todos (not folded) +- "Benchmark Płytarium on WinterCMS vs SummerCMS", "Record PHP OIDC parity against WavePath" (belongs to Phase 31-08), "Earlier phase gate scripts still name consuming applications", "Translate Messages as a Nuxt i18n JSON editor": keyword matches only, unrelated to this phase. + + + +--- + +*Phase: 32.2-mcp-oauth-with-administrator-subjects* +*Context gathered: 2026-11-20* diff --git a/.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-DISCUSSION-LOG.md b/.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-DISCUSSION-LOG.md new file mode 100644 index 00000000..aefb1c9c --- /dev/null +++ b/.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-DISCUSSION-LOG.md @@ -0,0 +1,95 @@ +# Phase 32.2: MCP OAuth with administrator subjects - Discussion Log + +> **Audit trail only.** Do not use as input to planning, research, or execution agents. +> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered. + +**Date:** 2026-11-20 +**Phase:** 32.2-mcp-oauth-with-administrator-subjects +**Areas discussed:** Consent surface, Mode per app, Consent choices, Revocation & visibility, Rollout + +Scout finding presented first: `summer_admin` is `Path=`, `SameSite=Strict`, so a root-level authorize or a cross-site navigation never sees it. That ruled out the exploration note's "authorize reads the cookie, Go renders consent". + +--- + +## Consent surface + +| Option | Description | Selected | +|--------|-------------|----------| +| Admin SPA route | /smbackend/connect in boardwalk; reuses login redirect and same-origin cookie fetch; wristband handoff configurable | ✓ | +| Go page under prefix | Server-rendered at /smbackend/oauth/connect, JS same-origin fetch to learn the admin | | +| You decide | Planner picks | | + +| Option | Description | Selected | +|--------|-------------|----------| +| Standalone screen | Full-screen card like LoginView | ✓ | +| Inside admin chrome | Normal admin page | | + +| Option | Description | Selected | +|--------|-------------|----------| +| Show + switch | Signed-in admin plus "use another account" | ✓ | +| Show only | Account shown, no switch | | + +## Mode per app + +| Option | Description | Selected | +|--------|-------------|----------| +| Exclusive per app | mcp.subject user / backend | | +| Both coexist | One app accepts both | | +| Exclusive now, coexist later | Ship exclusive, defer coexistence, keep config shape open | ✓ | + +| Option | Description | Selected | +|--------|-------------|----------| +| Keep requiring golem15.user | No Requires() change | ✓ | +| Make it optional | Backend mode without the user plugin | | + +## Consent choices + +| Option | Description | Selected | +|--------|-------------|----------| +| Cabana token scopes | Same catalog and ScopeLimit as g15_ tokens | ✓ | +| All-or-nothing | Full admin permissions | | +| Read vs read+write | admin:read vs * | | + +| Option | Description | Selected | +|--------|-------------|----------| +| Checkbox, on by default | "Stay connected" offline_access | ✓ | +| Always | Always refreshable | | +| Never | Re-authorize on expiry | | + +| Option | Description | Selected | +|--------|-------------|----------| +| Show disabled + explain | Greyed out with reason | | +| Hide them | Only usable scopes listed | ✓ | +| You decide | Planner chooses | | + +## Revocation & visibility + +| Option | Description | Selected | +|--------|-------------|----------| +| My account + superuser screen | Own list on My account; superuser/permission sees all | ✓ | +| My account only | No global view | | +| Admin screens only | Behind a permission | | + +Kill triggers (multi-select): Delete / deactivate ✓, Password change ✓, Role / permission change ✓, Sign out everywhere ✓. + +## Rollout + +| Option | Description | Selected | +|--------|-------------|----------| +| Local proof, deploy separately | Tags, pointer bump, DEPLOY.md; deploy on go-ahead | ✓ | +| Include prod deploy | Deploy checkpoint and live connector check | | +| Explore more gray areas | Keep discussing | | + +## Claude's Discretion + +- Storage of administrator-only grants (nullable user_id vs companion rows), additive only. +- pact/pier representation of an administrator-only grant. +- Location of the consent JSON API and the SPA ↔ plugin contract. +- Name and default role of the "manage any administrator's MCP connections" permission. +- Presentation of `*` / `admin:read` (plain checkboxes or presets). + +## Deferred Ideas + +- Both subject modes on one application. +- Production deploy of grzybyfunkcjonalne.pl with OAuth. +- Backend mode without golem15.user.