diff --git a/.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-UI-SPEC.md b/.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-UI-SPEC.md new file mode 100644 index 00000000..51757ab2 --- /dev/null +++ b/.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-UI-SPEC.md @@ -0,0 +1,370 @@ +--- +phase: "32.2" +slug: "mcp-oauth-with-administrator-subjects" +status: approved +reviewed_at: "2026-11-20" +shadcn_initialized: false +preset: none +created: "2026-11-20" +--- + +# Phase 32.2 — UI Design Contract + +> Visual and interaction contract for frontend phases. Generated by msd-ui-researcher, verified by msd-ui-checker. + +This phase adds three surfaces to the existing admin SPA (`admin/`, embedded by boardwalk). There is no new design system work. + +1. **Consent screen** `//connect?request=…` (`ConnectView.vue`, new). A standalone full-screen card built like `LoginView.vue`, with no sidebar or top bar (D-03, D-05). It shows the client name, the redirect host, "Signed in as" with "Use another account" (D-06), scope checkboxes from the cabana token-scope catalog with the scopes the administrator lacks hidden (D-09, D-11), a "Stay connected" checkbox ticked by default (D-10), and Allow / Deny. It also has loading, expired, load-error, submit-error, no-grantable-scope and "returning" states. +2. **My account: MCP connections** (D-12). A section that `sm-oauthserver-plugin` contributes through `pact.HasAccountContributions`. It is rendered by the framework's `AccountContributions.vue` through a new, additive per-item extension: one row per connected agent, each with a Revoke button. +3. **MCP connections list** on the oauthserver admin screens (D-12). It is driven by WinterCMS-style YAML (`config_list.yaml`, `columns.yaml`) and rendered by the existing `ListView.vue`. Its contract is columns, permission, navigation and copy, with no new Vue code. + +There is one small addition to `LoginView.vue`: a context line when the login redirect leads to `/connect`. + +Out of scope: wristband's own authorize-time error pages (unknown client, redirect mismatch). wristband renders them before the handoff, they are unchanged, and they never reach the SPA. The Nuxt `/connect` of user mode is also out of scope (unchanged, D-02). D-13 revocation has no UI. + +Sources: +- 32.2-CONTEXT.md D-03, D-05, D-06, D-09, D-10, D-11, D-12 (locked) and the Claude's Discretion items. +- 32.2-RESEARCH.md Patterns 4-6 (consent JSON contract, SPA route, account items) and Pitfall 7. +- The codebase scan: `admin/src/views/LoginView.vue`, `admin/src/components/account/{ApiTokenCreateDialog,ApiTokensPanel,AccountContributions}.vue`, `admin/src/components/ui/Button.vue`, `admin/src/app/{router,pageTitle,icons,i18n}.ts`, `admin/src/state/useAuth.ts`, `admin/src/styles/main.css`, `modules/phrasebook/backend/lang/{en,pl}/lang.yaml`, `modules/pact/capabilities.go`, `modules/cabana/{list_schema,navigation}.go`, `../sm-oauthserver-plugin/{admin*.go,controllers/clients/*.yaml,models/client/columns.yaml,lang/*/lang.yaml,models/consent.go}`, `../vue-oauth-layer/app/pages/connect.vue` (user-mode behaviour reference). +- House conventions from the approved 16.3 UI-SPEC (scope picker, token list rows, alert blocks, skeletons, copy) and the Direction C v2 design README (`.planning/phases/10-admin-vue-spa/design/README.md`). + +--- + +## Design System + +| Property | Value | +|----------|-------| +| Tool | none. There is no shadcn: this is a Vue 3 SPA with its own Direction C v2 system. The shadcn gate does not apply to a Vue codebase with an established system (same ruling as Phases 10.1, 12.1, 12.2, 16.3, 35) | +| Preset | not applicable | +| Component library | Reka UI 2.9.10 (headless primitives) plus the local components in `admin/src/components/` | +| Icon library | `@lucide/vue` 1.17.0, named imports only. Sizes: 20px in the wordmark and the 48px client circle (24px there), 18px in the login-style alert block, 16px in buttons and alert blocks, 14px in note lines. Navigation icons are registry names from `admin/src/app/icons.ts` | +| Font | DM Sans 400/600/700 (self-hosted `@fontsource/dm-sans`). DM Mono 400 (`font-mono`) for the redirect host and scope names. `tabular-nums` on every date | + +**This contract adds no new tokens, colours, fonts, radii, shadows or icons to the registry.** Every value below either reuses an existing token or copies a class string from `LoginView.vue`, `ApiTokenCreateDialog.vue`, `ApiTokensPanel.vue` or `AccountContributions.vue`. + +--- + +## Component Inventory + +Enumerated by `node --input-type=module -e "import * as r from 'reka-ui'; console.log(Object.keys(r).length)"` (run in `admin/`) — 478 exports — reka-ui@2.9.10 — 2026-11-20. +Local components enumerated by `find admin/src/components -name '*.vue' | wc -l` — 69 components — summercms-admin@unversioned (private workspace package with no `version` in `admin/package.json`; pinned by repo commit 28a07f6b) — 2026-11-20. + +Icon presence was verified by `node --input-type=module -e "import * as l from '@lucide/vue'; for (const n of [...]) console.log(n, n in l)"` (run in `admin/`) against @lucide/vue@1.17.0 on 2026-11-20. `Sun`, `Bot`, `CircleAlert`, `Info`, `LoaderCircle`, `Clock`, `Ban` and `Globe` are all exported. The navigation registry (`admin/src/app/icons.ts`) contains `network`, which is used for the new side-menu entry. `plug`/`bot` are **not** in the registry, so do not use them as navigation icon names. + +This table is a **non-exhaustive** list of known-good components for this phase, not a closed allowlist. Checking for another Reka export or local component is the expected path. + +| Component | Import path | Notes | +|-----------|-------------|-------| +| `LoginView.vue` shell markup | `admin/src/views/LoginView.vue` | The `
` gradient background, wordmark, card classes, alert block and primary button classes are copied verbatim into `ConnectView.vue` (D-05) | +| Scope picker markup | `admin/src/components/account/ApiTokenCreateDialog.vue` | Row markup, `toggleScope` / `scopeDisabled` / `starChecked` logic (`*` disables the rest) and the skeleton rows are copied, with the light-literal colours below. Extract a shared helper (for example `admin/src/app/scopePicker.ts`) if the planner prefers; the behaviour must stay identical | +| Token row markup | `admin/src/components/account/ApiTokensPanel.vue` | The list container and row classes, reused for My account item rows | +| `AccountContributions.vue` | `admin/src/components/account/AccountContributions.vue` | Extended to render `items` (C4). Existing sections without items render exactly as today | +| `Button` | `admin/src/components/ui/Button.vue` | My account item actions (`size="sm"`, `danger` / `outline`). **Not** used on the consent card, because its tokens flip in dark mode while the card stays light (see Color) | +| `ConfirmDialog` via `useConfirm` | `admin/src/components/ui/ConfirmDialog.vue`, `confirm.ts` | Item revoke confirmation. Reuse the `confirm` that `AccountView` passes in; do not mount a second one | +| `showToast` | `admin/src/state/useToasts.ts` | Item revoke success and failure toasts. The consent screen uses no toasts: every message is inline in the card | +| `logout`, `currentUser`, `expireSession` | `admin/src/state/useAuth.ts` | "Use another account" (call `logout()` **without** the router argument, then route to login with the redirect), the signed-in fallback, and the 401 handling | +| `safeRedirect` | `admin/src/app/router.ts` | Unchanged. Used only for the login round trip. **Never** pass the consent's `redirect_uri` through it | +| `t` | `admin/src/app/i18n.ts` | All copy. There are no literal UI strings in components | +| `api` (openapi-fetch) | `admin/src/api/client.ts` | `GET`/`POST /mcp/consent/{request}` and the account item action route, once `scripts/check-admin-openapi.sh` regenerates `schema.d.ts` | +| `ListView.vue` + cabana list YAML | `admin/src/views/ListView.vue`, `modules/cabana/list_schema.go` | The admin-wide MCP connections list. Column types are limited to `text`, `datetime`, `switch`, `date`, `time` and `money` (`listColumnTypes`) | + +New files this phase creates: `admin/src/views/ConnectView.vue`, and `admin/tests/views/ConnectView.test.ts` (in the last plan). The phase also changes `admin/src/app/router.ts`, `admin/src/app/pageTitle.ts`, `admin/src/views/LoginView.vue` and `admin/src/components/account/AccountContributions.vue`. Plugin side: `controllers/mcpconnections/config_list.yaml`, `models/consent/columns.yaml` (or a dedicated view model's columns), and lang keys. + +--- + +## Spacing Scale + +Declared values for new layout in this phase (multiples of 4): + +| Token | Value | Tailwind | Usage | +|-------|-------|----------|-------| +| xs | 4px | `gap-1` | Label to mono scope name in a scope row; dt to dd inside a fact row | +| sm | 8px | `gap-2` | Info-note icon gap; item meta line gap; the "returning" spinner to text | +| md | 16px | `gap-4`, `px-4` | Fact box and scope-row horizontal padding; item row column gap; My account items stack gap | +| lg | 24px | `gap-6`, `px-6` | Wordmark-to-card column gap (copied from LoginView); empty-state horizontal padding | +| xl | 32px | `p-8`, `py-8` | Consent card padding (copied from LoginView); empty-state vertical padding | +| 2xl | 48px | `size-12` | The client logo / icon circle (a size, not a gap) | +| 3xl | 64px | — | Not used | + +Exceptions (inherited from Direction C and copied verbatim from existing components; the same values 16.3 locked as system-level exceptions): +- Consent card stack gap 18px (`gap-[18px]`), copied from the LoginView card. +- Scope-row vertical padding 12px (`py-3`) and minimum row height 56px (`min-h-[56px]`); checkbox-to-text gap 12px (`gap-3`); 2px checkbox nudge (`mt-0.5`). All copied from the ApiTokenCreateDialog scope picker. +- Fact box vertical padding 12px (`py-3`), the same as a scope row, so the two boxes align. +- Footer button gap 10px (`gap-2.5`), copied from ApiTokenCreateDialog and ConfirmDialog. +- Item row vertical padding 14px (`py-3.5`), copied from ApiTokensPanel rows. +- Login-style alert block padding 12×14 (`px-3.5 py-3`), copied from LoginView. +- My account section card padding 28px (`p-7`), unchanged existing markup. + +Fixed component dimensions (sizes, not spacing): 44px consent buttons (`h-input`, as the login button); 38px item action buttons (`Button size="sm"`); 20px checkboxes (`size-5`); 48px client circle; 34px wordmark circle (copied); consent column max width 480px (`max-w-[480px]`, wider than the 400px login column because scope rows carry descriptions); 12px skeleton bars with `rounded-[6px]`. + +--- + +## Typography + +Exactly four sizes. All inherit DM Sans and the 14px/1.5 base from `html` in `main.css`. + +| Role | Size | Weight | Line Height | Used by | +|------|------|--------|-------------|---------| +| Body | 14px | 400 | 1.5 | Consent subline, signed-in value in the fact box, alert-block text, the expired and load-error bodies | +| Label | 14px | 600 | 1.5 | Scope label, "Stay connected" label, fact-row terms (`dt`), the "Use another account" text button, Allow / Deny button text, item row title, the Read-only pill (13px/600, as in 16.3) | +| Meta | 13px | 400 | 1.5 | Scope mono name and description, offline description, the `*` info note, redirect host (DM Mono), "previously allowed" note, login hint line, item meta line (`tabular-nums`), the items empty line, the "returning" fallback link | +| Heading | 22px | 700 | 1.2 (`tracking-[-0.02em]`) | Consent card `h1` (all states). The LoginView title class `text-[22px] font-bold tracking-[-0.02em]`, copied verbatim, so sign-in and consent read as one flow | + +Inherited, unchanged markup (not new text): the wordmark "Summer**CMS**" at 18px/700 (copied from LoginView) and the My account section heading at 18px/700 (existing `AccountContributions.vue`). + +Weights: new content uses 400 and 600 only. **700 is the inherited heading-only weight.** It appears on the consent `h1` and on the two inherited 18px elements, all copied verbatim. This is the system-level exception the user locked on 2026-10-11 (16.3 UI-SPEC, Typography) and that later phases re-applied. It is not a defect. DM Mono appears only on the redirect host and the scope names (`journal:read`, `*`). + +--- + +## Color + +**Consent card: light-literal palette.** `LoginView` draws a white card on the fixed navy gradient with literal hex values, so the card looks the same in light and dark mode (the theme preference is applied only after `me()`). `ConnectView` sits in the same flow, so it copies that treatment. Its card uses the **light** values of the existing tokens as literals (from `:root` in `main.css`), with no `dark:` variants, and does not use `Button.vue` or token utilities (`text-muted`, `bg-subtle` and so on) inside the card. Every literal below is an existing `:root` token value; no new colour is introduced. + +| Role | Value | Usage | +|------|-------|-------| +| Dominant (60%) | Gradient `radial-gradient(ellipse at 50% 35%, #2b3a5c 0%, #1d2740 60%)` (copied); card `#ffffff` (`bg-white`) | Page behind the card; the card itself; scope rows; the Deny button fill | +| Secondary (30%) | `#f3f5f8` (subtle) fact box and Read-only pill; `#e6e9ef` (border) row and box dividers; `#d2d8e2` (border-strong) Deny border and checkbox outline; `#566175` (muted) meta and description text; `#eceff4` (skel) skeleton bars; text `#141b2d` | Fact box, dividers, meta text, skeletons, body text | +| Accent (10%) | `#22304d` (primary, light value); the yellow `accent` `#fcd34d` / `accent-soft` (wordmark only, copied); focus ring `rgba(252,196,40,.55)` (base style) | See the reserved list | +| Destructive | `#c62828` (danger) / `#fdf0f0` (danger-soft) on the card; the `danger` / `danger-soft` tokens in My account | Consent alert blocks (load failure, submit failure, no grantable scopes); item Revoke buttons and their confirm button | + +**My account items and the admin-wide list use tokens** (`surface`, `border`, `muted`, `danger` …) and follow dark mode, like the rest of the shell. No hex literals appear there. + +Accent reserved for (exhaustive for this phase): +1. `#22304d` fill: the **Allow** button only. It is the single primary action on the consent card. +2. `#22304d` checkbox tint (`accent-[#22304d]`): checked scope checkboxes and the "Stay connected" checkbox. +3. Yellow `accent` / `accent-soft`: the wordmark sun circle and "CMS" (copied from LoginView), and nothing else. +4. Focus ring (3px): `:focus-visible` on every focusable element (base style), never removed. + +Accent is never used for: the Deny button (white fill, `#d2d8e2` border, `#141b2d` text, hover `#f1f3f7`), the "Use another account" text button (`#141b2d` text, underline on hover), the redirect host, scope names, links, or the My account item buttons. **Deny is not styled as destructive.** Refusing is a safe, neutral choice and must not look alarming. Danger colour is used only for errors and for Revoke. + +--- + +## Copywriting Contract + +Polish is the design language; English values follow. Placeholders use `:name` syntax (phrasebook). Copy lives in three places: +- **Framework (consent screen, login hint, generic item strings):** `modules/phrasebook/backend/lang/{en,pl}/lang.yaml`, in a new `mcp_connect:` group (`backend::lang.mcp_connect.*`) and additions to `myaccount:`. Framework copy never names an application. +- **Plugin (My account section, admin-wide list, permission):** `../sm-oauthserver-plugin/lang/{en,pl}/lang.yaml`, in new `account:` and `mcp_connections:` groups and `permissions.manage_mcp_connections`. +- **Server-delivered:** the client name, redirect host, admin name and email, and the scope labels and descriptions (from the cabana catalog, translated server-side; `*` and `admin:read` use the existing `api_tokens.scope_all*` and `scope_admin_read*` keys). These render as text, never as HTML. + +### Primary CTAs and key states (consent screen) + +| Element | Copy (EN / PL) | +|---------|----------------| +| Page title (`document.title` indicator) | `mcp_connect.page_title` "Connect an agent" / "Połącz agenta" | +| Heading (ready) | `mcp_connect.heading` "Allow :client to use the admin as you?" / "Pozwolić aplikacji :client korzystać z panelu w Twoim imieniu?" (the client name always follows a declined noun in Polish, so it stays in the nominative) | +| Subline | `mcp_connect.subline` "The agent gets your permissions, limited to the scopes you tick. It never gets more access than your own account." / "Agent otrzyma Twoje uprawnienia w granicach zaznaczonych zakresów. Nigdy nie dostanie szerszego dostępu niż Twoje konto." | +| Fact row: signed in (term) | `mcp_connect.signed_in_as` "Signed in as" / "Zalogowano jako" | +| Fact row: signed in (value) | `mcp_connect.admin_with_email` ":name (:email)" / ":name (:email)". With no email, the name alone. With no name, the login | +| Switch account | `mcp_connect.switch_account` "Use another account" / "Użyj innego konta" | +| Fact row: return address (term) | `mcp_connect.returns_to` "Returns to" / "Wrócisz do" (value: the redirect host in DM Mono) | +| Scopes group label | reuse `api_tokens.scopes` "Scopes" / "Zakresy" | +| `*` ticked note | reuse `api_tokens.scope_all_includes` "Full access already includes every other scope." / "Pełny dostęp obejmuje wszystkie pozostałe zakresy." | +| Read-only pill | reuse `api_tokens.read_only` "Read-only" / "Tylko odczyt" | +| Offline checkbox label | `mcp_connect.offline` "Stay connected" / "Pozostań połączony" | +| Offline description | `mcp_connect.offline_description` "The agent can renew its access without asking you again. Untick it and the agent has to be allowed again when its access expires." / "Agent może odnawiać dostęp bez ponownego pytania. Po odznaczeniu trzeba będzie ponownie wyrazić zgodę, gdy jego dostęp wygaśnie." | +| Previously allowed note (`consent_required: false`) | `mcp_connect.previously_allowed` "You have allowed :client before." / "Aplikacja :client ma już Twoją zgodę." | +| Primary CTA | `mcp_connect.allow` "Allow" / "Zezwól"; while busy `mcp_connect.allowing` "Allowing…" / "Zezwalanie…" | +| Secondary CTA | `mcp_connect.deny` "Deny" / "Odmów"; while busy the same label with a spinner | +| Returning state | `mcp_connect.returning` "Returning you to :host…" / "Wracasz do :host…" | +| Returning fallback link (http/https only) | `mcp_connect.continue` "Continue to :host" / "Przejdź do :host" | +| Login hint (LoginView, redirect to `/connect`) | `mcp_connect.login_hint` "Sign in to finish connecting your MCP agent." / "Zaloguj się, aby dokończyć łączenie agenta MCP." | + +### Empty, error and refusal states (consent screen) + +| Element | Copy (EN / PL) | +|---------|----------------| +| Empty: no grantable scope (every requested scope is hidden, D-11) | Alert block: `mcp_connect.none_grantable` "Your account has none of the permissions this agent asks for. Deny the request, or ask a superuser for the permissions and connect again." / "Twoje konto nie ma żadnego z uprawnień, o które prosi ten agent. Odmów albo poproś superużytkownika o uprawnienia i połącz się ponownie." Only Deny is offered | +| Expired / unknown / used request (404, or no `request` parameter) | Heading `mcp_connect.expired_heading` "This connection request has expired" / "Ta prośba o połączenie wygasła"; body `mcp_connect.expired_body` "Connection requests are valid for a few minutes and work only once. Go back to your agent and connect again." / "Prośba o połączenie jest ważna kilka minut i działa tylko raz. Wróć do agenta i połącz się ponownie."; link `mcp_connect.open_admin` "Go to the admin panel" / "Przejdź do panelu" | +| Error: load failed (5xx or network) | Alert block: `mcp_connect.load_failed` "The connection request could not be loaded. Check your connection and try again." / "Nie udało się wczytać prośby o połączenie. Sprawdź połączenie i spróbuj ponownie."; button `mcp_connect.retry` "Try again" / "Spróbuj ponownie" | +| Error: nothing ticked (client-side, Allow disabled) | Allow stays disabled; no message | +| Error: 422 `no_grantable_scopes` on Allow | Alert block under the scopes: reuse `api_tokens.scopes_required` "Choose at least one scope." / "Wybierz co najmniej jeden zakres." The ticks are kept | +| Error: submit failed (5xx, network, 400) | Alert block above the buttons: `mcp_connect.decide_failed` "Your answer could not be sent. Try again." / "Nie udało się wysłać odpowiedzi. Spróbuj ponownie." The ticks are kept and both buttons are enabled again | +| Error: 404 on submit | Switches to the expired state above | +| Error: 401 at any point | No copy on the card: `expireSession` sends the browser to login with `redirect` = this `/connect?request=…` path, and the existing `auth.session_expired` notice applies | + +### Destructive actions + +| Action | Confirmation approach | Copy (EN / PL) | +|--------|----------------------|----------------| +| Deny (consent) | **No confirmation.** Deny is reversible: the agent can simply ask again | `mcp_connect.deny` "Deny" / "Odmów" | +| Use another account (consent) | **No confirmation.** It only signs out of this browser session, and the request survives the round trip until it expires | `mcp_connect.switch_account` | +| Revoke one connection (My account item) | ConfirmDialog, `danger`, with the request run as the confirm action (`confirm.ask(request, run)`), so the confirm button shows the busy spinner | Button: `golem15.oauthserver::lang.account.revoke` "Revoke" / "Unieważnij"; aria-label `backend::lang.myaccount.item_action_named` ":action: :title" / ":action: :title". Confirm: `account.revoke_confirm` "Revoke the connection “:title”? The agent loses access at once and has to be connected again." / "Unieważnić połączenie „:title”? Agent natychmiast straci dostęp i trzeba będzie połączyć go ponownie." (the framework fills `:title` with the item title; C3). Confirm button: the action label. Success toast: `account.revoked` "Connection revoked" / "Unieważniono połączenie" | +| Revoke selected connections (admin-wide list, bulk) | Existing bulk confirm dialog with the action's `Confirm` text | Menu item: `mcp_connections.revoke` "Revoke connections" / "Unieważnij połączenia". Confirm: `mcp_connections.revoke_confirm` "Revoke the selected connections? Their agents lose access at once and have to be connected again." / "Unieważnić zaznaczone połączenia? Ich agenci natychmiast stracą dostęp i trzeba będzie połączyć ich ponownie." Result: empty `Message`, so the framework's `list.bulk_done` (CLDR plural with `:count`) shows | + +### My account section (plugin copy, `golem15.oauthserver::lang.account.*`) + +| Element | Copy (EN / PL) | +|---------|----------------| +| Section label | `account.section` "MCP connections" / "Połączenia MCP" | +| Section description | `account.description` "Agents you allowed to use the admin as you. Revoking a connection ends its access and its open sessions at once." / "Agenci, którym udzielono zgody na korzystanie z panelu w Twoim imieniu. Unieważnienie połączenia natychmiast odbiera dostęp i kończy otwarte sesje." | +| Status line (connector address) | `account.status` "Connector address: :url" / "Adres konektora: :url" (`:url` = the configured `mcp.resource`) | +| Empty state (no items) | `account.empty` "No agents are connected. Add the connector address in your agent and sign in to connect one." / "Brak połączonych agentów. Dodaj adres konektora w agencie i zaloguj się, aby go połączyć." | +| Item title | The client name (server data) | +| Item subtitle | The granted scope labels, joined with ", " (`*` → `api_tokens.scope_all`; `offline_access` is left out) | +| Item meta | `account.connected` "Connected :date" / "Połączono :date"; `account.last_used` "Last used :date" / "Ostatnio użyto :date" or `account.never_used` "Never used" / "Nieużywane". `:date` is `YYYY-MM-DD` | +| Item gone (404 on revoke) | framework `myaccount.item_gone` "This entry no longer exists. The section has been refreshed." / "Ten wpis już nie istnieje. Sekcja została odświeżona." (danger toast, then reload) | +| Revoke failed (other) | existing `extension.action_failed` (danger toast); 403 shows the server message or `list.action_forbidden`; 409 shows `myaccount.action_stale` and reloads (as for section actions today) | +| Framework fallback when `ItemsEmpty` is unset | `myaccount.items_empty` "Nothing here yet." / "Nic tu jeszcze nie ma." | + +### Admin-wide list (plugin copy, `golem15.oauthserver::lang.mcp_connections.*`) + +| Element | Copy (EN / PL) | +|---------|----------------| +| Side-menu label | `mcp_connections.menu_label` "MCP connections" / "Połączenia MCP" | +| List title | `mcp_connections.list_title` "Administrators' MCP connections" / "Połączenia MCP administratorów" | +| Empty list | `mcp_connections.list_empty` "No MCP connections in this view. Clear the search, or wait for an administrator to connect an agent." / "Brak połączeń MCP w tym widoku. Wyczyść wyszukiwanie albo poczekaj, aż administrator połączy agenta." | +| Columns | `mcp_connections.administrator` "Administrator" / "Administrator"; `mcp_connections.email` "Email" / "E-mail"; `mcp_connections.client` "Agent" / "Agent"; `mcp_connections.scopes` "Scopes" / "Zakresy"; `mcp_connections.created_at` "Connected" / "Połączono"; `mcp_connections.last_used_at` "Last used" / "Ostatnio użyto" | +| Search prompt | existing `backend::lang.list.search_prompt` | +| Permission label | `permissions.manage_mcp_connections` "See and revoke administrators' MCP connections" / "Podgląd i unieważnianie połączeń MCP administratorów" (tab `plugin.tab`, no default role) | + +--- + +## Component Contracts + +### C1. Consent screen — `admin/src/views/ConnectView.vue` (D-03, D-05, D-06, D-09, D-10, D-11) + +**Route.** `{ path: '/connect', name: 'connect', component: ConnectView }` in `router.ts`, with **no** `meta.shell` (standalone) and **no** `meta.public`. The existing `beforeEach` therefore sends an anonymous visitor to `{ name: 'login', query: { redirect: '/connect?request=…' } }`, and LoginView returns through `safeRedirect`. Place the route before the `/:vendor/:plugin/:controller` entries (a single segment never collides, but keep it with the other fixed paths). `pageTitle.ts` gains a `connect` branch returning `mcp_connect.page_title`. + +**Layout (copied from LoginView).** +- `
`. +- Column `flex w-full max-w-[480px] flex-col gap-6`: the wordmark block (verbatim), then the card. +- Card: `flex flex-col gap-[18px] rounded-card bg-white p-8 text-[#141b2d] shadow-login`. In the ready state it is a `
`. + +**Ready state, top to bottom.** +1. Client mark. When `client.logo_url` is a same-origin path or an `https:` URL, show a `size-12 rounded-inner object-contain` image with `alt=""` (the name is in the heading). Otherwise show a `size-12 rounded-full bg-[#f3f5f8]` circle holding `Bot` (24px, `text-[#566175]`). +2. `h1` (Heading role, `tabindex="-1"`) `mcp_connect.heading`, followed by the subline (Body, `text-[#566175]`). When `consent_required === false`, the "previously allowed" note (Meta, `Info` 14px) follows. +3. Fact box: a `
` with `flex flex-col gap-3 rounded-inner bg-[#f3f5f8] px-4 py-3`, two rows, each a `flex flex-col gap-1`: + - `dt` `mcp_connect.signed_in_as` (Label). `dd` holds the admin value (Body, `[overflow-wrap:anywhere]`), then on its own line the "Use another account" text button (`type="button"`, Label, `text-[#141b2d] underline-offset-2 hover:underline`, no fill). + - `dt` `mcp_connect.returns_to` (Label). `dd` holds `client.redirect_host` in `font-mono text-[13px]` with `[overflow-wrap:anywhere]`. **Always shown** (MCP spec: show the redirect host; anti-phishing). When the host is empty, show the full redirect origin the API returns. The row is never omitted. +4. Scope group: `role="group"` labelled by the "Scopes" label. Row markup is copied from ApiTokenCreateDialog: `overflow-hidden rounded-inner border border-[#e6e9ef]`, and each row is a `label` with `flex min-h-[56px] items-start gap-3 border-t border-[#e6e9ef] px-4 py-3 first:border-t-0`, a checkbox (`mt-0.5 size-5 shrink-0 rounded-[6px] accent-[#22304d]`), the label (Label), the mono name (Meta, `font-mono text-[#566175]`), the Read-only pill when `read_only` (`h-6 rounded-pill bg-[#f3f5f8] px-2.5 text-[13px] font-semibold text-[#566175]`) and the description (Meta, `text-[#566175] [overflow-wrap:anywhere]`). Rows appear in catalog order (`*`, `admin:read`, then plugin scopes). Only the scopes the API returns are shown; the API has already removed the ones the admin cannot use (D-11), and the SPA never re-adds them. + - **Initial ticks:** every shown scope is ticked **except `*`**, which starts unticked, unless `*` is the only scope shown, in which case it starts ticked. This keeps "full access" an explicit choice even when a client requests everything (RESEARCH Pattern 3, `DefaultScopes`). + - **`*` rule (discretion item, decided):** plain checkboxes, no presets. Ticking `*` clears and disables the others (`opacity-60 cursor-not-allowed`) and shows the `scope_all_includes` note (Meta, `Info` 14px); unticking re-enables them, with their previous ticks cleared. This matches `g15_` token creation exactly (D-09 mental model). Submitted scopes are `['*']` when `*` is ticked, else the ticked names in catalog order. +5. Offline row, shown only when `offline_access` was requested: a separate bordered box with the same row markup as a scope row (not inside the scope group). Checkbox **ticked by default** (D-10), label `mcp_connect.offline` (Label) and description `mcp_connect.offline_description` (Meta). Posted as `offline_access: true|false`. +6. Inline alert slot (submit failures, `role="alert"`). LoginView alert block classes: `flex items-center gap-2.5 rounded-control bg-[#fdf0f0] px-3.5 py-3 text-[#c62828]` with `CircleAlert` 18px. +7. Buttons: `flex gap-2.5`, both `flex-1 h-input rounded-control font-semibold`, **Deny on the left, Allow on the right** (the order of ApiTokenCreateDialog's cancel and submit). Allow is `type="submit"` with `bg-[#22304d] text-white hover:opacity-90 disabled:opacity-60`, disabled while no scope is ticked or while busy. Deny is `type="button"` with `border border-[#d2d8e2] bg-white text-[#141b2d] hover:bg-[#f1f3f7] disabled:opacity-60`. + +**Interaction.** +- Load on mount and when `route.query.request` changes: `GET {api}/mcp/consent/{request}`. A missing or empty `request` goes straight to the expired state without a request. +- **No auto-allow.** The card is shown even when `consent_required` is false (RESEARCH Open Question 1). Unlike the user-mode `/connect`, nothing is posted without a click. +- No initial focus on Allow or Deny, and no hotkey for Allow. Consent needs a deliberate click. After each state change past the first render, focus moves to the state's `h1` (or to the alert block for inline errors). +- Allow: `POST {api}/mcp/consent/{request}` with `{decision: 'allow', scopes, offline_access}`. While it runs, a `fieldset disabled` wraps the checkboxes, both buttons are disabled, and Allow shows `LoaderCircle` 16px `animate-spin` with `mcp_connect.allowing`. +- Deny: `POST` with `{decision: 'deny'}`, the same busy treatment on Deny (spinner, same label). +- On a `200 {redirect_uri}` for either decision, switch to the **returning** state and call `window.location.assign(redirect_uri)`. First refuse (and treat as a submit failure) a URI whose scheme is `javascript:`, `data:` or `vbscript:`. Never route the URI through `safeRedirect` or the router. Never use a native form POST: the admin CSP is `form-action 'self'`. +- "Use another account": `await logout()` (no router argument), then `router.replace({ name: 'login', query: { redirect: route.fullPath } })`. The button is disabled while a decision is in flight. +- Signed-in value: `admin.name` / `admin.email` / `admin.login` from the API. When the API omits `admin`, fall back to `currentUser` (first and last name, email, login). + +**Other states.** All use the same card shell; only the card contents change. +- **Loading:** `aria-busy="true"`. A 48px `bg-[#eceff4]` circle, two skeleton bars (`h-3 w-56`, `h-3 w-40`, `rounded-[6px] bg-[#eceff4]`), then three skeleton scope rows copied from the token dialog. No buttons. The `h1` is visually hidden (`sr-only`) and reads `mcp_connect.page_title`. +- **Expired** (404 on load or submit, or no `request`): `Clock` 24px in the 48px `bg-[#f3f5f8]` circle, the `h1` `expired_heading`, the body `expired_body` (`text-[#566175]`), and a full-width outline button-styled `RouterLink` to `/` with `open_admin` (Deny classes). +- **Load error:** `h1` `mcp_connect.page_title`, the alert block with `load_failed`, and a full-width "Try again" button (Deny classes) that re-runs the load. +- **No grantable scope** (ready, but the API returned zero scopes): the client mark, `h1`, subline and fact box as in ready; the `none_grantable` alert block in place of the scope group; no offline row; only **Deny**, full width. +- **Returning:** the client mark, `h1` `mcp_connect.returning` with `:host`, and a `LoaderCircle` 16px inline. When the URI is `http:` or `https:`, a Meta link `mcp_connect.continue` with `href` = the URI (`text-[#141b2d] underline`) follows, for browsers that block the navigation. No buttons. + +### C2. Login hint — `admin/src/views/LoginView.vue` (additive) + +When `safeRedirect(route.query.redirect)` resolves to a path whose pathname is `/connect`, render one Meta line (`text-[13px] text-[#566175]`) directly under the login `h1` with `mcp_connect.login_hint`. Nothing else in LoginView changes. Any 2FA or Turnstile step, error and redirect behaviour stays as it is (D-03). + +### C3. Account contribution items — `pact.AccountContribution` + `admin/src/components/account/AccountContributions.vue` (D-12, additive) + +The UI needs the RESEARCH Pattern 6 shape plus two small additions, all additive: +- `AccountContribution.Items` (func), `ItemActions []AccountItemAction`, and **`ItemsEmpty string`** (phrase key or text; empty means the framework's `myaccount.items_empty`). +- `AccountItem { ID, Title, Subtitle string; Meta []string }`. The framework interpolates **`:title`** in an item action's `Confirm` with the item's `Title` (as text). +- The JSON of a section **without** `Items` carries no `items` (or `null`), and that section renders exactly as today: status line and buttons only. Sections with `Items` always send an array, possibly empty. + +Rendering, inside the existing section card, after the status line and before the section buttons: +- **Items present:** `role="list"` container `flex flex-col overflow-hidden rounded-inner border border-border` (from ApiTokensPanel). Each `role="listitem"` row, with `data-account-item=""`, uses `flex items-start justify-between gap-4 border-t border-border px-4 py-3.5 first:border-t-0 max-sm:flex-col`. Left column `flex min-w-0 flex-1 flex-col gap-1`: title (Label, `[overflow-wrap:anywhere]`), subtitle (Meta, `text-muted [overflow-wrap:anywhere]`, omitted when empty), and the meta line (Meta, `text-muted tabular-nums`, entries joined with " · ", omitted when empty). Right: one `Button size="sm"` per item action, with `variant="danger"` and the `Ban` icon when `Danger`, else `variant="outline"` and no icon. `data-account-item-action=""`, aria-label `myaccount.item_action_named` with the item title, and `max-sm:self-start`. +- **Zero items:** `data-account-items-empty`, `rounded-inner border border-dashed border-border-strong px-6 py-8 text-center`, with one Meta line in `text-muted` holding `ItemsEmpty`. +- **Section error:** unchanged. The existing `section_error` line replaces both the list and the empty block. +- **Running an item action:** if the action has `Confirm` or `Danger`, `confirm.ask({ message, confirmLabel: action.label, danger }, run)`. Otherwise run directly. Run calls `POST /account/contributions/{name}/items/{item}/actions/{action}`. While it runs, every action button in every section is disabled (the existing `running` guard). On 2xx: toast with the answer message (or `form.action_done`), then reload. On 404: `item_gone` danger toast, then reload. On 409, 403 and other failures: as for section actions today. +- After a revoke reload, focus returns to the section heading (it gets `tabindex="-1"`), because the revoked row's button no longer exists. + +### C4. oauthserver My account section (D-12) — `sm-oauthserver-plugin/account.go` (new) + +- Contributed only when `mcp.subject: backend`. In user mode, `AccountContributions()` returns none, so other apps' My account pages are unchanged. +- `Name: "mcp_connections"`, `Label: account.section`, `Description: account.description`, `Status: account.status` with the resource URL, `ItemsEmpty: account.empty`. +- Items are the signed-in admin's backend consents (`user_id IS NULL AND backend_user_id = admin`), ordered by `last_used_at DESC NULLS LAST`, then `created_at DESC`. Item fields: `ID` = client_id, `Title` = client name, `Subtitle` = scope labels, `Meta` = [connected, last used or never used]. +- One item action: `Name: "revoke"`, `Label: account.revoke`, `Confirm: account.revoke_confirm`, `Danger: true`, result `Message: account.revoked`. +- No cap or pagination: an administrator has a handful of agents. Rows stack. + +### C5. Admin-wide MCP connections list (D-12) — YAML-driven, `sm-oauthserver-plugin` + +- **Controller** `golem15.oauthserver.mcpconnections` over the consent rows of backend subjects (`ListExtendQuery`: `user_id IS NULL AND backend_user_id IS NOT NULL`, joined to `backend_users` and `golem15_oauthserver_clients` for the text columns). `RequiredPermissions: [golem15.oauthserver.manage_mcp_connections]`; superusers pass as always. +- **Navigation:** a side-menu entry under the existing `oauthserver` main item, after "OAuth clients", with `Code: mcp_connections`, `Icon: network`, `Label: mcp_connections.menu_label`, the new permission, and `Visible` only when `mcp.subject: backend`. The main item keeps its label and permissions, and cabana's `openableTarget` already sends an admin who only holds the new permission to this entry. +- **`config_list.yaml`:** `title: mcp_connections.list_title`; `noRecordsMessage` / `messages.empty: mcp_connections.list_empty`; `recordsPerPage: 20`; `showCheckboxes: true`; `showSetup: true`; `showSorting: true`; `defaultSort: { column: created_at, direction: desc }`; `bulkActions: [revoke]`; `toolbar.search.prompt: backend::lang.list.search_prompt`; **no `toolbar.buttons`** (there is nothing to create); **no `recordUrl`** (a connection has nothing to edit, and every fact is in the columns). +- **`columns.yaml`** (in order): `id` (invisible); `administrator` (`text`, searchable: the full name, falling back to the login); `email` (`text`, searchable); `client` (`text`, searchable: the client name); `scopes` (`text`: the granted scope names joined with ", ", e.g. `journal, journal:read`, without `offline_access`); `created_at` (`datetime`); `last_used_at` (`datetime`, null shows the existing `list.empty_value` "—"). Cabana list relations may not join on the string `client_id` (RESEARCH A4). Use `select` expressions over the `ListExtendQuery` join, or a read-only view model, whichever the planner proves. The visible contract above is fixed either way. +- **Bulk action** `revoke` (copy in the Copywriting Contract, Destructive actions): it revokes each selected (admin, client) pair exactly like the My account item action, and fires the per-client `MCPSubjectChanged` after commit. Revoked rows disappear from the list (the consent row is deleted), so no row state is needed. + +--- + +## UI Considerations + +Applicable state considerations resolved: 38 probe checks in 38 rows (32 covered, 5 backstop, 1 dismissed, 0 unresolved). The elements are the consent card (form, interactive controls, static content), its scope list (list-collection), the login hint (static content), the My account items (list-collection, interactive control) and the admin-wide list (list-collection, existing ListView). The empty and error copy lives in the Copywriting Contract. + +| Category | Element(s) | Status | Resolution / Reason | +|----------|------------|--------|---------------------| +| loading | Consent card | ✅ covered | Skeleton card (C1 Loading) with `aria-busy="true"` and no buttons, so nothing can be submitted before the request is known | +| loading | Consent decision in flight | ✅ covered | Fieldset disabled, both buttons disabled, a spinner on the clicked button, then the Returning state until the browser leaves | +| loading | My account items | ✅ covered | Items arrive with the existing `GET /account/contributions`; nothing renders until it answers (existing behaviour), so no item-level loading UI | +| loading | Admin-wide list | ✅ covered | Existing ListView skeleton rows | +| empty | Consent scopes (none grantable) | ✅ covered | C1 No grantable scope: the `none_grantable` alert replaces the scope group, and only Deny is offered | +| empty | Consent request missing (`?request` absent) | ✅ covered | The Expired state, without a network call | +| empty | Consent form (nothing ticked) | ✅ covered | Allow is disabled while the submitted scope set would be empty; Deny stays available | +| empty | My account items | ✅ covered | The dashed empty block with `account.empty`; the status line with the connector address stays above it, so the next step is visible | +| empty | Admin-wide list | ✅ covered | `mcp_connections.list_empty`; an empty search uses the existing empty-search message | +| error | Consent load (5xx/network) | ✅ covered | Load error state with Try again | +| error | Consent load/submit 404 | ✅ covered | Expired state with a link to the admin | +| error | Consent 401 (session ended mid-flow) | ✅ covered | `expireSession` → login with the redirect back to the same `/connect?request=…` | +| error | Consent submit 422 / 5xx | ✅ covered | Inline alert, ticks kept, buttons enabled again | +| error | Consent `redirect_uri` with a forbidden scheme | ✅ covered | Treated as a submit failure (`decide_failed`); no navigation | +| error | My account item revoke 404 / 409 / 403 / other | ✅ covered | Toasts as in C3, with a reload on 404 and 409 | +| error | My account section items func failing | ✅ covered | The existing `section_error` line replaces the list | +| populated | Consent scopes | ✅ covered | Catalog order. Every shown scope ticked except `*` (unless `*` is alone). Read-only pill on read-only scopes. Offline row ticked when requested | +| populated | My account items | ✅ covered | One row per client: name, scope labels, "Connected · Last used" meta, Revoke | +| partial | Consent with `offline_access` not requested | ✅ covered | The offline row is not rendered; `offline_access: false` is posted | +| partial | Consent with no logo, no email or no name | ✅ covered | Bot circle; name without parentheses; login when the name is empty | +| zero-one-many | My account items | ✅ covered | Zero: the empty block. One or many: the same row list with dividers (`first:border-t-0`). No pagination (C4) | +| overflow | Consent scope list on a small screen | ✅ covered | The card grows with the page; the page scrolls (the `min-h-screen` main is not fixed height). Rows wrap; nothing scrolls inside the card | +| long-text | Client name, admin email, redirect host, scope descriptions, item titles | ✅ covered | `[overflow-wrap:anywhere]` on each. The heading wraps; nothing truncates on the consent card, because the redirect host must be read in full | +| populated | Consent `*` rule | 🧪 backstop | Vitest (`ConnectView.test.ts`): ticking `*` disables and clears the others and shows the note, the POST body is `['*']`, and unticking re-enables them | +| populated | No auto-allow and the decision navigation | 🧪 backstop | Vitest: with `consent_required: false` nothing is POSTed on mount; Allow and Deny POST the documented bodies and call `window.location.assign` with the server URI, never the router | +| populated | Switch account round trip | 🧪 backstop | Vitest: "Use another account" calls `POST /auth/logout`, then replaces to `login` with `redirect` = the current `/connect?request=…`; the router test covers anonymous `/connect` → login → back | +| populated | Account contribution items back-compat | 🧪 backstop | Vitest: a section without `items` renders exactly as before (status + buttons); a section with `items: []` renders the empty block; an item action runs the confirm with `:title` filled | +| populated | Cross-site cookie on the real connector flow (RESEARCH Pitfall 7, A2) | 🧪 backstop | Not provable on a localhost (same-site) stack: a live Claude-connector check at the deferred deploy step must show the signed-in card, not the login screen, after the cross-site redirect. Route to human verification | +| error | Admin-wide list (load, bulk revoke failure) | ✅ covered | Existing ListView error handling and bulk-action failure toast; nothing new | +| long-text | Admin-wide list cells (administrator, email, client, scopes) | ✅ covered | Existing ListView cell wrapping | +| overflow | Admin-wide list on a small screen | ✅ covered | Existing ListView horizontal scroll container | +| zero-one-many | Admin-wide list | ✅ covered | `recordsPerPage: 20` with the existing pager; zero rows show `mcp_connections.list_empty` | +| partial | Admin-wide list row (administrator without a name) | ✅ covered | The `administrator` column falls back to the login | +| error | "Use another account" sign-out failure | ✅ covered | The inline alert (`role="alert"`, `decide_failed` copy) shows and the card stays; the button is re-enabled | +| partial | My account item (client without a name) | ✅ covered | `Title` falls back to the client_id | +| overflow / long-text | My account items | ✅ covered | Titles, subtitles and meta wrap with `[overflow-wrap:anywhere]`; rows stack under `max-sm:flex-col` | +| loading / error | Consent scope list | ✅ covered | Inherited from the consent card's Loading, Load error and Expired states; the list never renders on its own | +| overflow / long-text | Login hint | ⛔ dismissed | One static, short translated line under the heading; it wraps with the heading's container and carries no user data | + +Open, prose-owned considerations (domain probes): +- **Accessibility:** the scope group is `role="group"` with a label. Every checkbox is inside its `label`. Alerts use `role="alert"`. Focus moves to the state heading on state changes. The 3px focus ring is never removed. Danger is never conveyed by colour alone (a text label is always present). +- **i18n:** Polish and English keys ship together. The Polish heading avoids inflecting the client name. Dates are `YYYY-MM-DD`, and the list datetimes use the existing admin formatting. + +--- + +## Registry Safety + +| Registry | Blocks Used | Safety Gate | +|----------|-------------|-------------| +| shadcn official | none (shadcn not used) | not applicable | +| third-party registries | none | not applicable | +| npm (new admin SPA deps) | none: only existing `reka-ui`, `@lucide/vue`, `vue`, `vue-router` and `openapi-fetch` | not applicable. The release gates still apply: `scripts/check-admin-openapi.sh --check` after the swag annotations, and a rebuilt, committed `modules/boardwalk/dist` passing `scripts/check-admin-dist.sh` | + +--- + +## Checker Sign-Off + +- [x] Dimension 1 Copywriting: FLAG (non-blocking) +- [x] Dimension 2 Visuals: PASS +- [x] Dimension 3 Color: PASS +- [x] Dimension 4 Typography: FLAG (non-blocking) +- [x] Dimension 5 Spacing: FLAG (non-blocking) +- [x] Dimension 6 Registry Safety: PASS +- [x] Dimension 7 Inventory Provenance: PASS + +**Approval:** approved 2026-11-20 (msd-ui-checker)