diff --git a/.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-04-SUMMARY.md b/.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-04-SUMMARY.md new file mode 100644 index 00000000..a7e4856c --- /dev/null +++ b/.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-04-SUMMARY.md @@ -0,0 +1,265 @@ +--- +phase: 32.2-mcp-oauth-with-administrator-subjects +plan: 04 +subsystem: auth +tags: [mcp, oauth, sm-oauthserver-plugin, sm-grzybyfunkcjonalne-app, nginx, deploy, smoke] + +requires: + - phase: 32.2-01 + provides: pact.MCPAdminConsent, cabana GET/POST {api}/mcp/consent/{request}, BackendAccessRevokedEvent on password change + - phase: 32.2-02 + provides: admin SPA /connect screen and My account item rows + - phase: 32.2-03 + provides: sm-oauthserver-plugin mcp.subject backend, mcp.consent_path, oidc.enabled (local commits 6996ffe, 9b97466, 4c209c1) +provides: + - sm-grzybyfunkcjonalne-app mounts golem15.oauthserver (submodule plugins/golem15/oauthserver, go.work use, go.mod require v0.1.7 + replace, summer.yaml, build.sh) + - config/golem15.oauthserver.yaml in backend mode with oidc off and a local mcp.resource + - scripts/smoke-mcp-oauth.sh, a twelve-step local proof of administrator OAuth sign-in with no browser and no Nuxt + - nginx locations = /.well-known/oauth-authorization-server and ^~ /oauth/mcp/ in both vhosts, guarded by check-deploy.sh + - DEPLOY.md MCP section for administrator OAuth, env.example key, deferred live connector check +affects: [32.2-05 plugin release and app pointer bump, phase 32.2 VERIFICATION human-verification list] + +actuals: + tokens: 11079 + tasks: 2 + commits: 3 +plan_head_before: c06a2d8cd92e49318f83ee97d6aa2d2f7ecbdde4 +plan_head_after: df554d5e3df8348d92f3e50487b2c5567424209c + +tech-stack: + added: [] + patterns: + - "Scripted MCP OAuth client in bash (curl, jq, openssl): secrets travel in header files and @file form fields, output is step names and status codes only" + - "Committed gitlink at the pushed plugin commit, working tree on unpushed local commits for the proof; the pointer bump is a later commit" + +key-files: + created: + - ../sm-grzybyfunkcjonalne-app/config/golem15.oauthserver.yaml + - ../sm-grzybyfunkcjonalne-app/scripts/smoke-mcp-oauth.sh + - ../sm-grzybyfunkcjonalne-app/plugins/golem15/oauthserver (submodule) + modified: + - ../sm-grzybyfunkcjonalne-app/.gitmodules + - ../sm-grzybyfunkcjonalne-app/go.work + - ../sm-grzybyfunkcjonalne-app/go.mod + - ../sm-grzybyfunkcjonalne-app/go.sum + - ../sm-grzybyfunkcjonalne-app/summer.yaml + - ../sm-grzybyfunkcjonalne-app/plugins.gen.go + - ../sm-grzybyfunkcjonalne-app/scripts/build.sh + - ../sm-grzybyfunkcjonalne-app/config/mcp.yaml + - ../sm-grzybyfunkcjonalne-app/boot_test.go + - ../sm-grzybyfunkcjonalne-app/README.md + - ../sm-grzybyfunkcjonalne-app/deploy/nginx/grzybyfunkcjonalne-staging.conf + - ../sm-grzybyfunkcjonalne-app/deploy/nginx/grzybyfunkcjonalne-production.conf + - ../sm-grzybyfunkcjonalne-app/scripts/check-deploy.sh + - ../sm-grzybyfunkcjonalne-app/deploy/env.example + - ../sm-grzybyfunkcjonalne-app/DEPLOY.md + +key-decisions: + - "Rollback of the OAuth sign-in sets both SUMMER_GOLEM15__OAUTHSERVER__MCP__ENABLED=false and SUMMER_GOLEM15__OAUTHSERVER__MCP__SUBJECT=user: the plan's single key fails boot (mcp.subject backend needs mcp.enabled), verified with route:list" + - "go.mod requires sm-oauthserver-plugin v0.1.7 (the latest pushed tag, equal to the committed gitlink); plan 05 bumps require, gitlink and plugins.gen.go to the new release together" + - "The boot test asserts the backend-mode route set (MCP OAuth routes mounted; /.well-known/openid-configuration, /oauth/jwks, /oauth/authorize, /oauth/token and /oauth/mcp/requests/* absent) and sets golem15.oauthserver.mcp.resource to /mcp like pier's" + - "env.example carries the concrete UAT value of SUMMER_GOLEM15__OAUTHSERVER__MCP__RESOURCE and the production value in its production block, in the file's existing style, instead of a placeholder" + +patterns-established: + - "check-deploy.sh parses config/golem15.oauthserver.yaml by top-level block and refuses any OpenID Connect nginx location" + +requirements-completed: [SC-4, SC-5] + +coverage: + - id: D1 + description: "sm-grzybyfunkcjonalne-app mounts golem15.oauthserver in backend mode with oidc off: submodule, go.work, go.mod require + replace, summer.yaml, build.sh, regenerated plugins.gen.go; config/mcp.yaml keeps enabled, path and allow_personal_tokens; the boot test activates nine plugins, checks the gitlink and the backend-mode route set" + requirement: SC-4 + verification: + - kind: integration + ref: "go -C ../sm-grzybyfunkcjonalne-app test -count=1 -tags summercms_mcp,nodynamic ./... (TestBootUserTranslateJournal, TestCompanionsHost with Docker)" + status: pass + - kind: other + ref: "summer build at the committed gitlink 7b9899f leaves main.go and plugins.gen.go unchanged" + status: pass + human_judgment: false + - id: D2 + description: "Local end-to-end proof: 401 with resource_metadata, protected-resource and authorization-server metadata, openid-configuration 404, dynamic registration, PKCE authorize 302 to /gfadmin/connect?request=, admin cookie sign-in, consent GET/POST, code exchange with refresh token, MCP initialize, notifications/initialized, tools/list and tools/call journal_list_posts over OAuth and with a g15_ token, and 401 for the OAuth bearer after a password change" + requirement: SC-4 + verification: + - kind: e2e + ref: "bash ../sm-grzybyfunkcjonalne-app/scripts/smoke-mcp-oauth.sh (ends 'smoke-mcp-oauth: ok (12 steps)'; output has no oas_at_, g15_ or code= values)" + status: pass + human_judgment: false + - id: D3 + description: "Both nginx vhosts route exactly /.well-known/oauth-authorization-server (GET, HEAD) and ^~ /oauth/mcp/ (GET, POST, 64k) to Go with auth_basic off on staging and no add_header; check-deploy.sh requires them, the backend-mode config and the summer.yaml entry, and refuses an OpenID Connect location" + requirement: SC-4 + verification: + - kind: automated_ui + ref: "bash ../sm-grzybyfunkcjonalne-app/scripts/check-deploy.sh (nginx -t both vhosts; 'check-deploy: ok') plus seven mutants on a scratch copy, all caught" + status: pass + human_judgment: false + - id: D4 + description: "DEPLOY.md MCP section: OAuth sign-in as an administrator next to g15_ tokens (connector address, /gfadmin/connect sign-in and consent, Stay connected, My account revoke, manage_mcp_connections screen, what ends an administrator's agents), config and env key, minimum plugin release, migration, nginx, local smoke, rollback, and the deferred live connector check; env.example key" + requirement: SC-5 + verification: + - kind: other + ref: "grep of DEPLOY.md for /gfadmin/connect, My account, golem15.oauthserver.manage_mcp_connections, SUMMER_GOLEM15__OAUTHSERVER__MCP__RESOURCE, scripts/smoke-mcp-oauth.sh, Live connector check (deferred); env.example contains the key" + status: pass + human_judgment: false + - id: D5 + description: "Live connector check: on a real cross-site redirect from Claude the SameSite=Strict admin cookie still reaches /gfadmin/connect, so the consent card shows the signed-in administrator rather than the login screen (D-03, RESEARCH A2)" + requirement: SC-4 + verification: [] + human_judgment: true + rationale: "A localhost stack is same-site and cannot reproduce the cross-site redirect chain; it needs the deferred production deploy on the user's go-ahead (DEPLOY.md 'Live connector check (deferred)', VALIDATION.md manual-only row). Status unverified, not passed and not failed." + +duration: 20min +completed: 2026-11-21 +status: complete +--- + +# Phase 32.2 Plan 04: first consumer mounts administrator MCP OAuth Summary + +**sm-grzybyfunkcjonalne-app now mounts sm-oauthserver-plugin as a backend-mode, OIDC-off MCP authorization server. A scripted MCP client proves the whole administrator sign-in locally in twelve steps: discovery, registration, PKCE, /gfadmin/connect consent, code exchange and a Journal tool call. `g15_` tokens keep working, and a password change ends the OAuth grant. Both vhosts route the two OAuth paths to Go, check-deploy guards them, and DEPLOY.md documents operation, rollback and the deferred live connector check.** + +## Performance + +- **Duration:** about 20 min +- **Started:** 2026-11-21T00:18Z +- **Completed:** 2026-11-21T00:39Z +- **Tasks:** 2 of 2 +- **Files modified:** 18 in ../sm-grzybyfunkcjonalne-app (752 insertions, 49 deletions) + +## Accomplishments + +- **Wiring (task 1).** + - `git submodule add -b master` created `plugins/golem15/oauthserver`. Its committed gitlink is `7b9899f`, which is v0.1.7 and equals `origin/master` (`git branch -r --contains 7b9899f` lists `origin/master`). + - Added `use ./plugins/golem15/oauthserver` to go.work. go.mod requires `v0.1.7` and has a `replace` to the submodule. `go mod tidy` filled go.sum. + - summer.yaml lists `golem15.oauthserver` (after `golem15.faq`), and the build.sh `PLUGINS` array has the submodule. + - `summer build` regenerated plugins.gen.go. main.go is unchanged. +- **Config.** + - New `config/golem15.oauthserver.yaml` sets `oidc.enabled: false`, `mcp.enabled: true`, `mcp.subject: backend` and `mcp.resource: http://127.0.0.1:8096/mcp`. Comments cover the env override and the equality with `/mcp`. `consent_path` is unset. + - In config/mcp.yaml only the comments changed. The three lines check-deploy matches are untouched. +- **Boot test.** + - Nine plugins, with golem15.oauthserver in both lists and a gitlink check. + - A new `assertMCPOAuthRoutes` checks that the four MCP OAuth routes are mounted and the OIDC and user-mode consent routes are not. + - The test sets the oauthserver resource to `/mcp`, so pier's resource-mismatch warning is gone. +- **Proof (task 1).** `scripts/smoke-mcp-oauth.sh` runs as follows: + - It builds with `-tags summercms_mcp,nodynamic`, creates a throwaway database (`SMOKE_ADMIN_DSN` or a postgres:15 container, dropped on exit) and migrates it. + - It creates a superuser with a random password on stdin and a `g15_` token (scope `journal`), then serves on `SMOKE_GO_PORT` (default 18097). + - It passes all twelve steps. Access, refresh and personal tokens, the code and the passwords never reach a command line or the output. +- **Proxy (task 2).** + - Both vhosts now have `location = /.well-known/oauth-authorization-server` (`limit_except GET HEAD`) and `location ^~ /oauth/mcp/` (`limit_except GET POST`, `client_max_body_size 64k`). Each sends the same proxy headers as the `/mcp` locations, and staging adds `auth_basic off`. There is no `add_header` and no OIDC location. + - The `/mcp` comments now name OAuth access tokens next to `g15_` tokens. +- **check-deploy.sh.** + - New header bullet. + - Both new locations are required, with exact method limits, the body cap and the staging gate-off. + - Any OpenID Connect location is refused. + - The oauthserver config must have `mcp.enabled: true`, `mcp.subject: backend` and `oidc.enabled: false`, and summer.yaml must list the plugin. + - Every existing check is kept. +- **Docs.** + - `deploy/env.example` gained `SUMMER_GOLEM15__OAUTHSERVER__MCP__RESOURCE`, with the UAT value and the production value. + - The DEPLOY.md MCP section was rewritten. Auth now covers both ways, then come OAuth server config, plugin version and migration, nginx, Check (with the local smoke), the deferred live connector check, and the corrected rollback. + - README.md has the plugin in the overview, a layout row for the submodule, and the new script. + +## Task Commits + +All in `../sm-grzybyfunkcjonalne-app` (branch master, not pushed): + +1. **Task 1 (tracer): mount golem15.oauthserver as the MCP authorization server for administrators** - `2953bf8` (feat) +2. **Task 1 (tracer): local end-to-end proof of administrator OAuth sign-in** - `f2dc85d` (test) +3. **Task 2: route the MCP OAuth paths to Go and document administrator sign-in** - `df554d5` (deploy) + +Tracer gate: auto mode is off. human_verify_mode is end-of-phase (the default) and `` is automated-only. The smoke and the tagged app tests ran again and passed before task 2, so expansion continued. + +## Files Created/Modified + +- `.gitmodules`, `plugins/golem15/oauthserver`: the submodule entry (url `git@git.golem15.com:golem15/sm-oauthserver-plugin.git`, branch master) and the gitlink at 7b9899f +- `go.work`, `go.mod`, `go.sum`: the workspace use, the require and replace, and the tidied sums +- `summer.yaml`, `plugins.gen.go`, `scripts/build.sh`: the plugin entry, the generated registration, and the plugin dir for the build check +- `config/golem15.oauthserver.yaml`: the backend-mode config (new) +- `config/mcp.yaml`: comments only +- `boot_test.go`: the plugin lists, the gitlink check, `assertMCPOAuthRoutes` and the resource alignment +- `scripts/smoke-mcp-oauth.sh`: the twelve-step proof (new, executable) +- `deploy/nginx/grzybyfunkcjonalne-{staging,production}.conf`: the two locations and the `/mcp` comment +- `scripts/check-deploy.sh`: the new checks +- `deploy/env.example`, `DEPLOY.md`, `README.md`: the docs + +## Decisions Made + +See key-decisions in the frontmatter. In addition: +- Regenerating plugins.gen.go also refreshed two stale values: golem15.user `v0.1.19` became `v0.1.21` (the previous commit bumped the user pointer without regenerating), and `FrameworkVersion` `v0.6.1` became `v0.6.6`, the framework checkout's base tag. Without the regeneration, build.sh's drift check would fail. +- The smoke script's steps 8 and 12 send `X-Requested-With: XMLHttpRequest` with the cookie jar, the same as the SPA. The account PUT sends the email as well, because cabana requires it. Step 12 calls `tools/list` without a session id, so the 401 comes from the bearer check and not from session handling. + +## Deviations from Plan + +### Auto-fixed Issues + +**1. [Rule 1 - Bug] The documented rollback would not boot** +- **Found during:** Task 2 (DEPLOY.md rollback) +- **Issue:** The plan's rollback, `SUMMER_GOLEM15__OAUTHSERVER__MCP__ENABLED=false` alone, fails boot with `golem15.oauthserver: mcp.subject backend needs mcp.enabled`. This was checked with `route:list` on the built binary. +- **Fix:** DEPLOY.md also sets `SUMMER_GOLEM15__OAUTHSERVER__MCP__SUBJECT=user`. That boots with no MCP OAuth routes. The only plugin routes left are the user-mode `/oauth/authorizations` ones, which have no nginx location. +- **Files modified:** `DEPLOY.md` +- **Commit:** `df554d5` + +**2. [Rule 2 - Missing check] Boot test asserts the backend-mode route set** +- **Found during:** Task 1 +- **Issue:** The plan only added the plugin to the boot test's lists. Nothing in the Go tests would notice the plugin booting in user mode or with OIDC on. +- **Fix:** Added `assertMCPOAuthRoutes`, and aligned `golem15.oauthserver.mcp.resource` with the test's `app.url`. +- **Files modified:** `boot_test.go` +- **Commit:** `2953bf8` + +**3. [Rule 3 - Blocking] Smoke token expiry** +- **Found during:** Task 1 (first smoke run) +- **Issue:** `admin:token:create --expires 1d` is refused (`api_tokens.expires_invalid`). +- **Fix:** The script uses `30d`, the value scripts/smoke.sh uses. The token dies with the throwaway database anyway. +- **Commit:** `f2dc85d` + +### Notes on the plan text + +- The acceptance check `grep -c 'location ^~ /oauth/mcp/'` prints 0 for any file, because GNU grep reads `^` as an anchor there. With `grep -cF` each vhost has exactly 1, and check-deploy.sh matches the location with `grep -qF`. +- The committed state is intermediate by design, following the submodule rule. On a fresh `git submodule update`, the gitlink 7b9899f (v0.1.7) predates backend mode, so `TestBootUserTranslateJournal` fails at commits 2953bf8 to df554d5 until plan 05 commits the release pointer. With the working tree on the plan 03 commits, as left now, vet and every app test pass. + +--- + +**Total deviations:** 3 auto-fixed. **Impact:** no scope creep. The rollback fix keeps the documented rollback from failing boot. + +## Issues Encountered + +None beyond the deviations. + +## Known Stubs + +None. + +## Threat Flags + +None beyond the plan's threat model: +- T-32.2-22: OIDC off. The smoke asserts the 404, check-deploy refuses an OIDC location, and the boot test asserts the routes are absent. +- T-32.2-23: the plugin throttles stay on. nginx limits methods and the body size (64k). +- T-32.2-24: the output check printed nothing. +- T-32.2-25: no `add_header` in the new locations, and check-deploy enforces it. + +## Verification + +- `bash scripts/smoke-mcp-oauth.sh`: all twelve steps pass and the run ends `smoke-mcp-oauth: ok (12 steps)`. `grep -E 'oas_at_[A-Za-z0-9]|g15_[A-Za-z0-9]{8,}|code=[A-Za-z0-9]'` over the output prints nothing. +- `go vet -tags summercms_mcp,nodynamic ./...` and `go test -count=1 -tags summercms_mcp,nodynamic ./...` in the app: ok (Docker suite included). Untagged `go test -short ./...`: ok. +- `bash scripts/check-deploy.sh`: `check-deploy: ok` (nginx -t on both vhosts). The seven mutants were an add_header, a widened method limit, `subject: user`, `oidc` on, a missing summer.yaml entry, an added openid-configuration location, and the staging gate left on. Each one fails the check. +- `summer build` at the committed gitlink leaves `main.go` and `plugins.gen.go` unchanged. With the working tree on 4c209c1, only the oauthserver row changes (`v0.1.7-3-g4c209c1` and the newer plugin.yaml description), and plan 05 regenerates that with the release pointer. The file was restored to the committed copy. +- `go mod tidy -diff` is clean with the plan 03 plugin tree. + +**Human verification, still open after this phase (unverified, not a failure):** the D-03 `SameSite=Strict` admin cookie on a real cross-site connector redirect chain (RESEARCH A2). It stays open until the "Live connector check (deferred)" in DEPLOY.md runs after the deferred production deploy. The phase VERIFICATION.md must list it under human verification with status unverified, pointing at that DEPLOY.md note and the VALIDATION.md manual-only row. + +## User Setup Required + +None for the local proof. The production deploy, the server's `go/.env` key (`SUMMER_GOLEM15__OAUTHSERVER__MCP__RESOURCE=https://grzybyfunkcjonalne.pl/mcp`), the vhost install and the live Claude connector check wait for the user's go-ahead. + +## Next Phase Readiness + +- **Plan 05**, after pushing and tagging sm-oauthserver-plugin, makes one app commit with these changes: + - the gitlink `plugins/golem15/oauthserver` moves to the release (it is uncommitted now; the working tree sits at local 4c209c1); + - the go.mod require goes from `v0.1.7` to the new tag; + - `summer build` regenerates plugins.gen.go (new version and description); + - then run `scripts/smoke-mcp-oauth.sh` and `scripts/check-deploy.sh` again. +- DEPLOY.md calls the minimum version "the sm-oauthserver-plugin release that adds `mcp.subject`". Plan 05 can name the tag there. +- Nothing was pushed, tagged or deployed in any repo. STATE.md and ROADMAP.md were not touched. + +## Self-Check: PASSED + +- Files exist: `config/golem15.oauthserver.yaml`, `scripts/smoke-mcp-oauth.sh` (executable), `plugins/golem15/oauthserver/plugin.go`. +- Commits 2953bf8, f2dc85d and df554d5 are in the app's `git log`. The gitlink 7b9899f is on the plugin's `origin/master`.