diff --git a/.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-02-SUMMARY.md b/.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-02-SUMMARY.md new file mode 100644 index 00000000..723c08b0 --- /dev/null +++ b/.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-02-SUMMARY.md @@ -0,0 +1,238 @@ +--- +phase: 32.2-mcp-oauth-with-administrator-subjects +plan: 02 +subsystem: admin-spa +tags: [mcp, oauth, consent, admin-spa, vue, boardwalk, phrasebook, my-account] + +requires: + - phase: 32.2-01 + provides: cabana GET/POST {api}/mcp/consent/{request}, POST {api}/account/contribution-items/{name}/{item}/actions/{action}, AccountContributionView items/item_actions/items_empty, regenerated admin.json and schema.d.ts +provides: + - admin SPA route /connect (name connect, no shell, not public) with ConnectView + - ConnectView states loading, ready, no grantable scope, expired, load error, returning, inline 422/decide failures + - LoginView login hint when the redirect is /connect + - AccountContributions item rows, empty block and item actions + - type aliases MCPConsent, MCPConsentDecision, AccountItem + - backend::lang.mcp_connect.* consent copy, myaccount.items_empty/item_gone/item_action_named (en, pl) + - rebuilt modules/boardwalk/dist + - docs/backend/admin-spa.md "Connect screen" section and My account item rows +affects: [32.2-03 sm-oauthserver-plugin backend mode (sets ConsentPath to {admin prefix}/connect, contributes the items section), 32.2-04 live run, 32.2-05 ConnectView.test.ts and extended unit tests] + +actuals: + tokens: 11200 + tasks: 3 + commits: 4 +plan_head_before: 1d3e6df6ecc1dcc2bfdd0872353261231e7874f9 +plan_head_after: ee754b6b5d0669f3872ce2cd8362bb9cf775ae75 + +tech-stack: + added: [] + patterns: + - "Server-issued cross-origin redirect leaves through window.location.assign after a scheme deny-list, never through the router or safeRedirect" + - "Consent card copies LoginView's light-literal palette (no Button.vue, no tokens, no dark: variants)" + - "Additive per-item rendering: items null keeps a section exactly as before" + +key-files: + created: + - admin/src/views/ConnectView.vue + - admin/tests/smoke/connect.smoke.test.ts + - admin/tests/smoke/account-items.smoke.test.ts + modified: + - admin/src/app/router.ts + - admin/src/app/pageTitle.ts + - admin/src/api/types.ts + - admin/src/views/LoginView.vue + - admin/src/components/account/AccountContributions.vue + - modules/phrasebook/backend/lang/en/lang.yaml + - modules/phrasebook/backend/lang/pl/lang.yaml + - docs/backend/admin-spa.md + - modules/boardwalk/dist + +key-decisions: + - "Deny posts {decision: 'deny', scopes: [], offline_access: false}: the generated MCPConsentDecisionRequest type marks all three fields required (swag --requiredByDefault), and cabana ignores scopes on deny" + - "Item ids are passed raw to openapi-fetch, which already applies encodeURIComponent to path parameters; the plan's explicit encodeURIComponent would double-encode (smoke test pins client:1 -> client%3A1)" + - "Focus follows the state heading only after the first settled render, so the initial load never moves focus; inline errors focus their alert block" + - "A 422 on Deny (not expected from cabana) shows decide_failed, not scopes_required" + - "While Use another account runs, Allow and Deny are disabled as well (locked = deciding or switching)" + +patterns-established: + - "ConnectView talks only to cabana's admin API; plugins supply the consent through pact.MCPAdminConsent, never Vue code" + +requirements-completed: [SC-1, SC-3, SC-5] + +coverage: + - id: D1 + description: "Signed-in admin at /connect?request= sees both scopes and Stay connected ticked; Allow POSTs {allow, scopes, offline_access true} with X-Requested-With and window.location.assign gets redirect_uri; router push/replace never see it; nothing posts before the click" + requirement: SC-1 + verification: + - kind: unit + ref: "admin/tests/smoke/connect.smoke.test.ts#Allow posts the ticked scopes and Stay connected, then leaves for redirect_uri without the router" + status: pass + human_judgment: false + - id: D2 + description: "404 on load renders the Expired state with a link to /; Use another account POSTs /auth/logout and lands on login with redirect=/connect?request=req1 and the login hint" + requirement: SC-1 + verification: + - kind: unit + ref: "admin/tests/smoke/connect.smoke.test.ts#shows the Expired state when the request is unknown (404 on load)" + status: pass + - kind: unit + ref: "admin/tests/smoke/connect.smoke.test.ts#Use another account signs out and returns through login to the same request" + status: pass + human_judgment: false + - id: D3 + description: "My account: section without items unchanged; items [] renders the empty block; danger item action confirms with :title filled, posts the encoded item route, reloads and focuses the section heading" + requirement: SC-3 + verification: + - kind: unit + ref: "admin/tests/smoke/account-items.smoke.test.ts" + status: pass + - kind: unit + ref: "admin/tests/account/AccountContributions.test.ts (unchanged, 16 tests)" + status: pass + human_judgment: false + - id: D4 + description: "Typed contract regenerated and unchanged, dist rebuilt and committed, docs checker clean, SPA phrase keys resolve in en and pl" + requirement: SC-5 + verification: + - kind: other + ref: "scripts/check-admin-openapi.sh --check; scripts/check-admin-dist.sh; summer docs:build --check; go test ./cmd/summer -run TestDocsTree; modules/phrasebook TestPhase10SPAKeysResolve" + status: pass + human_judgment: false + - id: D5 + description: "Cross-site cookie on the real connector flow shows the signed-in card, not login, after the cross-site redirect (UI-SPEC backstop, RESEARCH Pitfall 7)" + requirement: SC-1 + verification: + - kind: manual + ref: "deferred to the live connector check (plan 04 / deploy)" + status: pending + human_judgment: true + +duration: 20min +completed: 2026-11-21 +status: complete +--- + +# Phase 32.2 Plan 02: Admin consent screen and My account item rows Summary + +**A standalone `/connect` consent card in the admin SPA that an administrator reaches through the normal login, which posts Allow/Deny to cabana's consent API and sends the browser to the server-issued `redirect_uri` with `window.location.assign`. Plus per-item rows with Revoke-style actions on My account, and the rebuilt embedded dist.** + +## Performance + +- **Duration:** about 20 min +- **Started:** 2026-11-20T23:36Z +- **Completed:** 2026-11-20T23:56Z +- **Tasks:** 3 of 3 +- **Files modified:** 12 source/doc files plus the regenerated `modules/boardwalk/dist` + +## Accomplishments + +- **Tracer.** At `/connect?request=req1` a signed-in administrator sees the scopes the API returned, in catalog order, together with Stay connected. Allow sends `{decision, scopes, offline_access}` through openapi-fetch (with X-Requested-With and the same-origin cookie), and the browser leaves through `window.location.assign`. The router never sees the URI. The smoke test proves this against plan 01's JSON contract. +- **Every C1 state:** + - Loading: skeleton card with `aria-busy` and no buttons. + - Expired: a 404 on load or submit, or no `request` parameter (in which case no network call is made). + - Load error: shows Try again. + - No grantable scope: only Deny, full width. + - Returning: an inline spinner, plus a continue link for http(s) URIs. + - Inline errors: a 422 shows `scopes_required` and the ticks are kept. A 5xx, a network failure, a 400, or a `javascript:`/`data:`/`vbscript:` URI shows `decide_failed`. + - 401: handled by `expireSession`. +- **Scope picker.** Uses the token-dialog `*` rule (ticking `*` clears and disables the others and shows the note). `*` starts unticked unless it is the only scope. The Read-only pill and the logo rule (a same-origin path or `https:`, else the Bot circle) are in place. There is no auto-allow, no initial focus on Allow or Deny, and no hotkey. +- **Use another account.** Calls `logout()` without a router, then `router.replace({ name: 'login', query: { redirect: route.fullPath } })`. LoginView shows `mcp_connect.login_hint` when `safeRedirect(redirect)` points to `/connect`. +- **My account items.** + - A section with `items` shows one `role=listitem` row per item (title, subtitle, and meta joined with ` · `) and one `Button size=sm` per item action. Danger actions get the Ban icon and the `item_action_named` aria-label. + - An empty `items` array shows the dashed empty block. + - A section with `items: null` renders exactly as before, and the existing 16 AccountContributions tests are unchanged and pass. + - Item actions confirm with `:title` filled in as text, post the item route, reload, and focus the section heading. A 404 shows the `item_gone` toast and reloads. +- **Docs and dist.** `docs/backend/admin-spa.md` has a new "Connect screen" section and a paragraph on My account item rows. `modules/boardwalk/dist` is rebuilt and committed, and `check-admin-dist.sh` passes. + +## Task Commits + +1. **Task 1 (tracer): consent card at /connect, decision POST, leave for redirect_uri** - `f46c90f7` (feat) +2. **Task 2: every consent state, account switch and login hint** - `6900bd1a` (feat) +3. **Task 3: My account item rows, docs** - `27089826` (feat); **rebuilt dist** - `ee754b6b` (chore) + +Tracer gate: auto mode is off, and human_verify_mode is end-of-phase with an automated-only ``. The verify ran again (typecheck, the connect, router, pageTitle and i18n vitest files, `check-admin-openapi.sh --check`, and the contract and conformance Go tests) and passed, so expansion continued. + +## Files Created/Modified + +- `admin/src/views/ConnectView.vue`: the consent card with all of its states +- `admin/src/app/router.ts`: `{ path: '/connect', name: 'connect', component: ConnectView }`, without `meta.shell` or `meta.public`. `safeRedirect` and `beforeEach` are unchanged +- `admin/src/app/pageTitle.ts`: connect branch → `mcp_connect.page_title` +- `admin/src/api/types.ts`: `MCPConsent`, `MCPConsentDecision`, `AccountItem` +- `admin/src/views/LoginView.vue`: the login hint line, and nothing else +- `admin/src/components/account/AccountContributions.vue`: item rows, the empty block, item actions, and a focusable section heading +- `modules/phrasebook/backend/lang/{en,pl}/lang.yaml`: the 23 `mcp_connect` keys and 3 `myaccount` keys +- `docs/backend/admin-spa.md`: the Connect screen and My account item rows +- `admin/tests/smoke/connect.smoke.test.ts` (3 cases), `admin/tests/smoke/account-items.smoke.test.ts` (3 cases) +- `modules/boardwalk/dist`: rebuilt + +## Decisions Made + +- Deny sends `scopes: []` and `offline_access: false` along with `decision: 'deny'`. The generated request type requires all three fields, and cabana ignores them on a deny. +- Path parameters are not encoded by hand, because openapi-fetch's `defaultPathSerializer` already applies `encodeURIComponent`. +- Focus moves only after the first settled render, so the initial load does not move focus. Later state changes focus the state's `h1`, and inline errors focus their alert. +- `locked` covers both a decision in flight and an account switch in progress, so Allow, Deny and Use another account cannot overlap. + +## Deviations from Plan + +### Auto-fixed Issues + +**1. [Rule 1 - Bug] No double-encoding of the item id** +- **Found during:** Task 3 +- **Issue:** The plan says to POST `.../{encodeURIComponent(item)}/...`. openapi-fetch already encodes path parameters, so a second `encodeURIComponent` would turn `client:1` into `client%253A1`, and the item would never be found (404). +- **Fix:** The raw `item.id` is passed in `params.path`. The smoke test checks that the request goes to `.../contribution-items/agents/client%3A1/actions/revoke`. +- **Files modified:** admin/src/components/account/AccountContributions.vue, admin/tests/smoke/account-items.smoke.test.ts +- **Commit:** 27089826 + +**2. [Prior-wave pickup] Item action path** +- The SPA uses plan 01's `/account/contribution-items/{name}/{item}/actions/{action}`, not the plan's `/account/contributions/{name}/items/...`. The plan's key_link pattern `/items/` therefore does not match. The route is typed in `schema.d.ts`. + +**3. [Rule 3 - Interpretation] Deny body** +- The plan says "Deny POSTs {decision: 'deny'}". The typed body needs `scopes` and `offline_access`, so they are sent empty and false. The server accepts this (DisallowUnknownFields only refuses extra keys). + +**Other notes:** +- `scripts/check-admin-openapi.sh` produced no diff, as expected after plan 01. `--check` passes. +- `modules/cabana/admin_openapi.go` is untouched, because swag accepted every annotation from plan 01. + +**Total deviations:** 1 bug fix, 1 contract pickup, 1 interpretation. No scope creep. + +## Issues Encountered + +- `rm` is aliased to an interactive prompt in this shell. A throwaway scratch test (it exercised the `*` rule, no grantable scope, 422, a `javascript:` URI, a 5xx followed by retry, a missing request and the anonymous redirect, and all passed) was removed with `command rm -f`, and nothing from it was committed. + +## Known Stubs + +None. + +## Threat Flags + +None. The consent screen adds no new server surface. It uses only the plan 01 routes covered by T-32.2-09..12: +- `redirect_uri` comes only from the 200 decision answer, with the scheme deny-list applied. +- The redirect host is always shown and never truncated. +- Every server string is rendered by interpolation and `v-html` is never used. `:title` is filled in as text. +- There is no auto-allow, and `*` is never pre-ticked unless it is the only scope. + +## Verification + +- `npm --prefix admin run typecheck`: pass. +- `npm --prefix admin run test`: 116 files and 1685 tests pass. `npm --prefix admin run test:browser`: 4 files and 13 tests pass. +- `scripts/check-admin-openapi.sh --check`, `scripts/check-admin-dist.sh` (after the dist commit), `go test ./cmd/summer -run TestDocsTree` and `summer docs:build --check` ("no problems found"): pass. +- `go test -short` passes for `./modules/boardwalk`, `./modules/phrasebook` (including TestPhase10SPAKeysResolve, so every new key resolves in en and pl) and `./modules/cabana`. `TestPhase09ContractInventory` and `TestPhase10OpenAPIConformance` pass and were not skipped. +- `go vet ./...` and `go test -short -count=1 ./...` pass for the whole module. +- `git grep -n -i 'grzyby' -- admin/src docs/backend/admin-spa.md modules/phrasebook` finds nothing. +- `git status --porcelain -- modules/boardwalk/dist` is empty. + +## User Setup Required + +None. + +## Next Phase Readiness + +- Plan 03: set `wristband.Options.ConsentPath` to `/connect` (the SPA reads `?request=`), and contribute the `mcp_connections` section with `Items`/`ItemActions` (`revoke`, `Danger: true`, a `Confirm` with `:title`). +- Plan 05: write `ConnectView.test.ts` covering the `*` rule, no auto-allow, the switch round trip and the back-compat backstops against the `data-*` hooks used here (`data-connect-state`, `data-scope`, `data-connect-offline`, `data-action="allow|deny|switch-account|retry|open-admin"`, `data-connect-error`, `data-connect-none-grantable`, `data-previously-allowed`, `data-scope-all-note`, `data-connect-continue`, `data-login-hint`). +- Human verification is still needed for the cross-site cookie on a real connector (D5). + +## Self-Check: PASSED + +- All 3 created files exist on disk. +- Commits f46c90f7, 6900bd1a, 27089826 and ee754b6b are in `git log`.