diff --git a/.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-05-SUMMARY.md b/.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-05-SUMMARY.md new file mode 100644 index 00000000..4b0caedd --- /dev/null +++ b/.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-05-SUMMARY.md @@ -0,0 +1,302 @@ +--- +phase: 32.2-mcp-oauth-with-administrator-subjects +plan: 05 +subsystem: testing +tags: [mcp, oauth, wristband, pier, cabana, admin-spa, sm-oauthserver-plugin, regression, release-gate] + +requires: + - phase: 32.2-01 + provides: wristband consent_path and DefaultScopes, pier backend-only grants, cabana MCP admin consent, account items, BackendAccessRevokedEvent + - phase: 32.2-02 + provides: admin SPA /connect screen, login hint, My account item rows + - phase: 32.2-03 + provides: sm-oauthserver-plugin mcp.subject backend (local commits 6996ffe, 9b97466, 4c209c1) + - phase: 32.2-04 + provides: sm-grzybyfunkcjonalne-app mounts the plugin in backend mode, smoke-mcp-oauth.sh, check-deploy.sh guards +provides: + - TestBackendGrantToolsMatchPersonalToken - an OAuth administrator grant and a g15_ token with equal scopes list and call the same tools + - framework unit tests for SC-1 to SC-3 in wristband, pier and cabana + - admin SPA tests for the consent screen, the login hint and the My account item rows (four of the five UI backstops) + - plugin unit tests for backend-subject mode, consent, migration, grant rows, revocation and the D-13 cascade + - recorded regression runs across framework, admin, plugin, grzyby and sm-bm-app (all exit 0) + - admin:reset-password now runs in a lagoon transaction, so BackendAccessRevokedEvent listeners' after-commit work fires + - 32.2-05-release-decision.txt recording hold (framework-base v0.6.6, plugin-base v0.1.7) +affects: [32.2 VERIFICATION, the release of the next v0.6 patch and sm-oauthserver-plugin v0.1.8, grzyby pointer bump] + +actuals: + tokens: 46063 + tasks: 5 + commits: 4 +plan_head_before: d450a6819e9b6d6da8879e9bb6933a365394d156 +plan_head_after: fc90a5470ce87acbbe199c4d0d0e64059315acee + +tech-stack: + added: [] + patterns: + - "Throttle-aware Docker tests: a cascade test rotates fresh OAuth clients instead of relaxing the plugin's register/token throttles" + - "Test-only hooks through export_test.go (cabana.FireBackendAccessRevokedForTest), never exported from the package" + +key-files: + created: + - modules/wristband/consent_path_test.go + - modules/pier/backend_only_grant_test.go + - modules/cabana/token_scope_names_test.go + - modules/cabana/mcp_admin_consent_test.go + - modules/cabana/account_items_test.go + - modules/cabana/backend_access_revoked_test.go + - admin/tests/views/ConnectView.test.ts + - ../sm-oauthserver-plugin/backend_tools_test.go + - ../sm-oauthserver-plugin/backend_mode_test.go + - ../sm-oauthserver-plugin/backend_consent_test.go + - ../sm-oauthserver-plugin/backend_subject_migration_test.go + - ../sm-oauthserver-plugin/backend_grant_rows_test.go + - ../sm-oauthserver-plugin/backend_revoke_test.go + - ../sm-oauthserver-plugin/jwt_only_test.go + - .planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-05-release-decision.txt + modified: + - modules/cabana/commands.go + - modules/cabana/export_test.go + - admin/tests/app/router.test.ts + - admin/tests/views/LoginView.test.ts + - admin/tests/account/AccountContributions.test.ts + - ../sm-oauthserver-plugin/testdata/php_methods.txt + - ../sm-oauthserver-plugin/testdata/PHP_METHOD_MAP.md + - .planning/phases/32.2-mcp-oauth-with-administrator-subjects/deferred-items.md + +key-decisions: + - "Release checkpoint answered hold: no tag, no push, no changelog post; the release (next v0.6 patch above v0.6.6, sm-oauthserver-plugin v0.1.8, grzyby pointer bump, two changelog posts) is pending the user's go-ahead after /msd-verify-work" + - "admin:reset-password runs in lagoon.Transaction instead of a plain GORM transaction, so lagoon.AfterCommit callbacks registered by BackendAccessRevokedEvent listeners run (Rule 1)" + - "TestPHPMethodMap: the five AuthorizeResolveUserJwtOnlyTest methods are mapped, three ported as adapted subtests and two marked not applicable (the Go plugin resolves users from the session JWT only)" + - "offline_access-only authorize requests storing no data scope is pre-existing (user mode behaves the same) and was logged to deferred-items.md, not changed" + +patterns-established: + - "Plugin v0.1.8 must require a framework tag that contains b1b96d85" + +requirements-completed: [SC-1, SC-2, SC-3, SC-4] + +coverage: + - id: D1 + description: "An administrator who consents over OAuth with acme:read lists and calls only the read-only tool, with acme lists and calls the write tool, and both tool lists equal a g15_ token's tools/list with the same scopes; revoking one connection from My account answers 401 for it and leaves the other working" + requirement: SC-2 + verification: + - kind: integration + ref: "go -C ../sm-oauthserver-plugin test -count=1 -tags summercms_mcp -run TestBackendGrantToolsMatchPersonalToken . (backend_tools_test.go, Docker)" + status: pass + human_judgment: false + - id: D2 + description: "Framework unit tests: consent handoff path and default scopes (wristband), backend-only grants and the user-mode linked-grant regression (pier), token scope names, MCP admin consent API, account contribution items and BackendAccessRevokedEvent at all seven D-13 sites (cabana)" + requirement: SC-1 + verification: + - kind: unit + ref: "go test -count=1 -run 'TestAuthorizeConsentPath|TestAuthorizeDefaultScopes|TestBackendOnlyGrant|TestLinkedGrantNoScopeLimit|TestTokenScopeNames|TestMCPAdminConsent$|TestAccountContributionItems|TestBackendAccessRevokedEvent' ./modules/wristband ./modules/pier ./modules/cabana" + status: pass + human_judgment: false + - id: D3 + description: "Admin SPA tests and four UI backstops: the * consent rule, no auto-allow with Allow/Deny through window.location.assign, the switch-account round trip, and account item rows back-compat" + requirement: SC-1 + verification: + - kind: automated_ui + ref: "npm --prefix admin run test -- tests/views/ConnectView.test.ts tests/app/router.test.ts tests/views/LoginView.test.ts tests/account/AccountContributions.test.ts" + status: pass + human_judgment: false + - id: D4 + description: "Plugin backend-mode unit tests: TestBackendMode, TestBackendConsent, TestBackendSubjectMigration, TestBackendGrantRows, TestBackendRevokeFromAccount, TestBackendCascade" + requirement: SC-3 + verification: + - kind: integration + ref: "go -C ../sm-oauthserver-plugin test -count=1 -run 'TestBackendMode$|TestBackendConsent|TestBackendSubjectMigration|TestBackendGrantRows|TestBackendRevokeFromAccount|TestBackendCascade' . (Docker)" + status: pass + human_judgment: false + - id: D5 + description: "User mode unchanged: full regression runs in framework, admin, plugin (both tag sets), grzyby (smoke, check-deploy, tagged tests) and sm-bm-app through a scratch go.work" + requirement: SC-4 + verification: + - kind: integration + ref: "task 3 regression commands (see Verification below), every exit code 0" + status: pass + human_judgment: false + - id: D6 + description: "Live connector check: on a real cross-site redirect from Claude the SameSite=Strict admin cookie still reaches the admin /connect screen, so the consent card shows the signed-in administrator rather than the login screen (D-03, RESEARCH A2, fifth UI backstop)" + requirement: SC-1 + verification: [] + human_judgment: true + rationale: "A localhost stack is same-site and cannot reproduce the cross-site redirect chain. It is routed to sm-grzybyfunkcjonalne-app DEPLOY.md 'Live connector check (deferred)', which runs after the deferred production deploy on the user's go-ahead. Status UNVERIFIED, not passed and not failed; no test in this plan claims to cover it." + - id: D7 + description: "SC-5 release: next v0.6 patch tag, sm-oauthserver-plugin v0.1.8, grzyby pointer bump, two changelog posts" + requirement: SC-5 + verification: + - kind: other + ref: "task 5 automated verify on the hold branch (no v0.6.7 in summercms.go, no v0.1.8 in sm-oauthserver-plugin): exit 0" + status: pass + human_judgment: true + rationale: "The checkpoint answer was hold. The release is pending the user's go-ahead after verification; SC-5 is not met yet." + +duration: 48min +completed: 2026-11-21 +status: complete +--- + +# Phase 32.2 Plan 05: tests, regression runs and release gate Summary + +**An OAuth administrator grant and a `g15_` token with equal scopes now provably see and call the same MCP tools. Unit tests cover SC-1 to SC-3 in wristband, pier, cabana, the admin SPA and sm-oauthserver-plugin. Regression runs in five repos show user mode is unchanged. One real bug came out of the tests: `admin:reset-password` never ran its listeners' after-commit work, and it is now fixed. The release checkpoint answered hold, so nothing was tagged, pushed or posted.** + +## Performance + +- **Duration:** about 48 min +- **Started:** 2026-11-21T00:41:38Z +- **Completed:** 2026-11-21T01:29Z +- **Tasks:** 5 of 5 (task 4 was the checkpoint, task 5 ran its hold branch) +- **Files modified:** 13 in summercms.go (tests, commands.go, deferred items, decision record), 8 in ../sm-oauthserver-plugin + +## Accomplishments + +- **Tracer (task 1), sm-oauthserver-plugin `bae8222`.** `TestBackendGrantToolsMatchPersonalToken` (`summercms_mcp`, Docker) runs the real flow: authorize, admin consent, token exchange and `/mcp` calls. + - `acme:read` lists and calls only the read-only backend tool. + - `acme` lists and calls the write tool. + - In both cases the tool list matches a `g15_` token with the same scopes, name for name. + - Revoking one connection from My account makes that bearer get 401, and the other client keeps working. +- **Framework unit tests (task 2), `7ecfa608`.** + - wristband: `TestAuthorizeConsentPath`, `TestAuthorizeDefaultScopes`. + - pier (Docker): `TestBackendOnlyGrant`, `TestLinkedGrantNoScopeLimit`. + - cabana: `TestTokenScopeNames`, `TestMCPAdminConsent`, `TestAccountContributionItems`, `TestBackendAccessRevokedEvent` (Docker, all seven D-13 sites). +- **Admin SPA tests (task 2), `1e00ed3d`.** + - New `ConnectView.test.ts` covers every C1 state, the `*` rule, no auto-allow, the Allow and Deny bodies through `window.location.assign`, forbidden schemes, switch account, 401/404 handling, focus and the profile fallback. + - router, LoginView and AccountContributions tests are extended: anonymous `/connect` goes to login and back, the login hint, `items` null versus `[]`, the `:title` confirm, 404 `item_gone` and 409 `action_stale`. +- **Plugin backend-mode tests (task 3), sm-oauthserver-plugin `793eadd`.** `TestBackendMode`, `TestBackendConsent`, `TestBackendSubjectMigration`, `TestBackendGrantRows`, `TestBackendRevokeFromAccount`, `TestBackendCascade`. +- **Regression runs (task 3).** Every command in task 3's verify exits 0 (see Verification). +- **Release gate (tasks 4 and 5).** The user answered **hold**. + - `32.2-05-release-decision.txt` records `hold`, `framework-base v0.6.6` and `plugin-base v0.1.7`. + - Task 5's automated verify passes on the hold branch (exit 0). + - No tag was created and nothing was pushed in any repo. No changelog script ran and nothing was deployed. + +## Task Commits + +| Task | Name | Repo | Commit | +|---|---|---|---| +| 1 | Tracer: OAuth administrator grant tools equal a `g15_` token's tools | sm-oauthserver-plugin | `bae8222` (test) | +| 2 | Framework unit tests (wristband, pier, cabana) | summercms.go | `7ecfa608` (test) | +| 2 | Admin SPA tests | summercms.go | `1e00ed3d` (test) | +| 3 | Plugin backend-mode unit tests | sm-oauthserver-plugin | `793eadd` (test) | +| 3 | Rule 1 fix: admin:reset-password in a lagoon transaction | summercms.go | `b1b96d85` (fix) | +| 3 | TestPHPMethodMap: map AuthorizeResolveUserJwtOnlyTest | sm-oauthserver-plugin | `1124fd1` (test) | +| 3 | Deferred items after the plugin tests | summercms.go | `fc90a547` (docs) | +| 4 | Checkpoint: whether to tag, push and post the changelog | - | answered hold | +| 5 | Release only if the checkpoint accepted it | summercms.go | decision record, in the plan metadata commit | + +`commits: 4` in the frontmatter is measured with the framework ledger (`d450a681..fc90a547`). The three plugin commits are local to `../sm-oauthserver-plugin`, which is now 6 commits ahead of `origin/master` (plans 03 and 05). Nothing was pushed. + +Tracer gate: auto mode is off, human_verify_mode is end-of-phase and task 1's `` is automated-only. The verify ran again and passed, so the plan continued to task 2. + +## Files Created/Modified + +- `modules/wristband/consent_path_test.go`: consent handoff path and default scopes +- `modules/pier/backend_only_grant_test.go`: backend-only grants and the linked-grant regression +- `modules/cabana/{token_scope_names,mcp_admin_consent,account_items,backend_access_revoked}_test.go`: the SC-1 and SC-3 cabana tests +- `modules/cabana/export_test.go`: `FireBackendAccessRevokedForTest`, used by the de-duplication case +- `modules/cabana/commands.go`: `admin:reset-password` in `lagoon.Transaction` +- `admin/tests/views/ConnectView.test.ts` (new), `admin/tests/app/router.test.ts`, `admin/tests/views/LoginView.test.ts`, `admin/tests/account/AccountContributions.test.ts` +- `../sm-oauthserver-plugin/backend_{tools,mode,consent,subject_migration,grant_rows,revoke}_test.go`, `jwt_only_test.go`, `testdata/php_methods.txt`, `testdata/PHP_METHOD_MAP.md` +- `.planning/phases/32.2-mcp-oauth-with-administrator-subjects/deferred-items.md`, `32.2-05-release-decision.txt` + +## Decisions Made + +See key-decisions in the frontmatter. + +**Release decision: hold. The release is pending the user's go-ahead after verification.** When the user says go, task 5's tag-and-publish branch runs in this order: +1. Tag the framework's next free v0.6 patch (v0.6.7 if still free) on master. It must contain every earlier tag and `b1b96d85`. +2. Point sm-oauthserver-plugin's go.mod at that framework tag, regenerate plugin.yaml, then tag v0.1.8 and push it. +3. Commit the grzyby pointer and go.mod bump to v0.1.8 as a separate commit, after the plugin push. +4. Publish the two changelog posts the same day. + +The decision record is not rewritten if the bases move. Recompute the bases at release time. + +## Deviations from Plan + +### Auto-fixed Issues + +**1. [Rule 1 - Bug] admin:reset-password skipped its listeners' after-commit work** +- **Found during:** Task 3 (regression runs, D-13 site coverage) +- **Issue:** The reset fired `BackendAccessRevokedEvent` inside a plain GORM transaction, and `lagoon.AfterCommit` refuses to run there. As a result the plugin's revoked `MCPSubjectChanged` events, which end MCP sessions, never ran for this D-13 site. +- **Fix:** The command now runs in `lagoon.Transaction`. `TestBackendAccessRevokedEvent` asserts that the after-commit callback runs once for a committed reset and does not run for a vetoed one. +- **Files modified:** `modules/cabana/commands.go`, `modules/cabana/backend_access_revoked_test.go` +- **Committed in:** `b1b96d85` + +**2. [Rule 3 - Blocking] TestPHPMethodMap failure (pre-existing, logged by plan 03)** +- **Found during:** Task 3 (full plugin suite) +- **Issue:** The PHP reference tree gained `AuthorizeResolveUserJwtOnlyTest`, and its five methods were unmapped, so the plugin's full `go test ./...` could not pass. +- **Fix:** Three methods are ported as adapted subtests of `TestAuthorizeResolveUserJwtOnly`. Two are marked not applicable, because the Go plugin resolves users from the session JWT only. +- **Committed in:** sm-oauthserver-plugin `1124fd1`; deferred-items.md updated in `fc90a547` + +**3. [Rule 3 - Blocking] TestBackendCascade hit the plugin's register and token throttles** +- **Found during:** Task 3 +- **Fix:** The test rotates six fresh OAuth clients instead of reusing one. The throttles are not relaxed. +- **Committed in:** sm-oauthserver-plugin `793eadd` + +**4. [Rule 3 - Blocking] De-duplication case needed an internal hook** +- **Fix:** `cabana.FireBackendAccessRevokedForTest` lives in `export_test.go`, so the package's exported API is unchanged. +- **Committed in:** `7ecfa608` + +--- + +**Total deviations:** 4 (1 Rule 1, 3 Rule 3). **Impact:** the Rule 1 fix closes a real gap in session termination after a password reset. The other three are test plumbing only, with no scope creep. + +## Issues Encountered + +- The first `npm --prefix admin run test:browser` run hit a Vite dynamic-import flake under load in the code editor test files. The rerun passed (4 files, 13 tests) with no code change. +- A pre-existing behaviour was logged to deferred-items.md and not changed: an authorize request whose only scope is `offline_access` stores no data scope. User mode behaves the same way. + +## Verification + +Regression exit codes (task 3; logs in the session scratchpad, `r1-*.log` to `r5-bm.log`): + +| Run | Exit | +|---|---| +| framework `go vet ./...` | 0 | +| framework `go test -count=1 ./...` (47 packages, Docker) | 0 | +| framework `go test -count=1 -tags summercms_mcp ./modules/pier ./modules/surf` | 0 | +| plugin `go vet` (both tag sets) | 0 | +| plugin `go test -count=1 ./...` | 0 | +| plugin `go test -count=1 -tags summercms_mcp ./...` | 0 | +| admin `typecheck` | 0 | +| admin `test` (117 files, 1729 tests) | 0 | +| admin `test:browser` (rerun, 4 files, 13 tests) | 0 | +| `scripts/check-admin-openapi.sh --check` | 0 | +| `scripts/check-admin-dist.sh` | 0 | +| `go test ./cmd/summer -run TestDocsTree` | 0 | +| `go run ./cmd/summer docs:build --check` | 0 | +| grzyby `scripts/smoke-mcp-oauth.sh` (`ok (12 steps)`) | 0 | +| grzyby `scripts/check-deploy.sh` | 0 | +| grzyby `go test -count=1 -tags summercms_mcp,nodynamic ./...` | 0 | +| sm-bm-app via scratch go.work: `vet -tags summercms_mcp` / `test -tags summercms_mcp` | 0 / 0 | +| task 5 verify (hold branch) | 0 | + +The grzyby runs used the plugin working tree at local `4c209c1` and later. The grzyby gitlink is still uncommitted (` M plugins/golem15/oauthserver`) until the release. + +**Human verification, open (UNVERIFIED, not a failure):** the D-03 `SameSite=Strict` admin cookie on a real cross-site connector redirect chain (RESEARCH A2, the fifth UI backstop, the VALIDATION.md manual-only row). It is routed to `../sm-grzybyfunkcjonalne-app/DEPLOY.md`, "Live connector check (deferred)", and runs after the deferred production deploy on the user's go-ahead. The phase VERIFICATION.md must list it under human verification with status unverified. No test in this plan claims to cover it. + +## Known Stubs + +None. + +## Threat Flags + +None beyond the plan's threat model: +- T-32.2-26: the tests assert status codes and ids, and the smoke output carries no tokens or codes. No changelog script ran, so the journal token was never read. +- T-32.2-27: the blocking checkpoint held. No tag and no push. + +## User Setup Required + +None. + +## Next Phase Readiness + +- Phase 32.2 is ready for `/msd-verify-work`. +- The release waits for the user's go-ahead, following the task 5 order above. +- Still not done: the plugin's 6 local commits are unpushed, the grzyby gitlink is uncommitted, and the DEPLOY.md minimum-version wording can name v0.1.8 once it exists. +- STATE.md and ROADMAP.md were not touched by this plan, as the orchestrator instructed. + +## Self-Check: PASSED + +- Files exist: the wristband, pier and cabana test files, `admin/tests/views/ConnectView.test.ts`, `../sm-oauthserver-plugin/backend_tools_test.go`, `../sm-oauthserver-plugin/backend_revoke_test.go` and `32.2-05-release-decision.txt`. +- Framework commits `7ecfa608`, `1e00ed3d`, `b1b96d85` and `fc90a547` exist, as do plugin commits `bae8222`, `793eadd` and `1124fd1`. +- There is no `v0.6.7` tag in summercms.go and no `v0.1.8` tag in sm-oauthserver-plugin. diff --git a/.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-05-release-decision.txt b/.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-05-release-decision.txt new file mode 100644 index 00000000..69bb86e9 --- /dev/null +++ b/.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-05-release-decision.txt @@ -0,0 +1,3 @@ +hold +framework-base v0.6.6 +plugin-base v0.1.7