docs(32.2-02): complete admin consent screen and account items plan
This commit is contained in:
@@ -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 `<verify>`. 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 `<admin prefix>/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`.
|
||||
Reference in New Issue
Block a user