docs(32.2-01): complete framework seams plan
This commit is contained in:
@@ -0,0 +1,252 @@
|
|||||||
|
---
|
||||||
|
phase: 32.2-mcp-oauth-with-administrator-subjects
|
||||||
|
plan: 01
|
||||||
|
subsystem: auth
|
||||||
|
tags: [mcp, oauth, pier, wristband, cabana, pact, postgres, swag]
|
||||||
|
|
||||||
|
requires:
|
||||||
|
- phase: 32.1-mcp-oauth-for-plugin-apps-declared-scopes-mcp-subject-on-con
|
||||||
|
provides: MCPGrant.BackendUserID, configurable MCP scopes, user-mode consent flow
|
||||||
|
provides:
|
||||||
|
- pact MCPGrant.Subject + MCPGrantSubjectBackend, MCPSubject.ScopeLimited
|
||||||
|
- pact MCPAdminConsent provider interface with MCPAdminConsentRequest/Decision and ErrMCPConsentNotFound/ErrMCPConsentNoScopes
|
||||||
|
- pact AccountContribution.Items/ItemActions/ItemsEmpty, AccountItem, AccountItemAction, AccountItemActionInput, ErrAccountItemNotFound
|
||||||
|
- wristband Options.ConsentPath and Options.DefaultScopes (defaults byte-identical to PHP)
|
||||||
|
- pier backend-only grant branch (binding oauth:backend:<client>:<admin>, ceiling off, scope-limited like g15_ tokens)
|
||||||
|
- cabana GET/POST {api}/mcp/consent/{request} with the personal-token scope policy
|
||||||
|
- cabana POST {api}/account/contribution-items/{name}/{item}/actions/{action}
|
||||||
|
- cabana TokenScopeNames, TokenScopeLabels
|
||||||
|
- cabana BackendAccessRevokedEvent fired in-transaction at every D-13 site
|
||||||
|
affects: [32.2-02 admin SPA, 32.2-03 sm-oauthserver-plugin backend mode, 32.2-04 first consumer app, 32.2-05 tests and release]
|
||||||
|
|
||||||
|
actuals:
|
||||||
|
tokens: 37974
|
||||||
|
tasks: 4
|
||||||
|
commits: 4
|
||||||
|
plan_head_before: 45eb34e5c4e86cd94ab3467be1e93ae7d688f3b2
|
||||||
|
plan_head_after: fcc7bbde25a270a6211aace6b1cc40589b2295b4
|
||||||
|
|
||||||
|
tech-stack:
|
||||||
|
added: []
|
||||||
|
patterns:
|
||||||
|
- "Zero value means today's behaviour for every new pact field and wristband option"
|
||||||
|
- "Framework owns the scope policy; a published provider (pact.MCPAdminConsent) only resolves and issues"
|
||||||
|
- "In-transaction veto event (BackendAccessRevokedEvent) next to the unchanged after-commit MCPSubjectChanged"
|
||||||
|
|
||||||
|
key-files:
|
||||||
|
created:
|
||||||
|
- modules/cabana/mcp_consent.go
|
||||||
|
- modules/cabana/token_scopes_export.go
|
||||||
|
- modules/cabana/admin_events.go
|
||||||
|
- modules/pier/backend_subject_smoke_test.go
|
||||||
|
- modules/wristband/consent_path_smoke_test.go
|
||||||
|
- modules/cabana/mcp_consent_smoke_test.go
|
||||||
|
- modules/cabana/account_items_smoke_test.go
|
||||||
|
- modules/cabana/backend_access_revoked_smoke_test.go
|
||||||
|
modified:
|
||||||
|
- modules/pact/mcp.go
|
||||||
|
- modules/pact/capabilities.go
|
||||||
|
- modules/wristband/server.go
|
||||||
|
- modules/wristband/authorize.go
|
||||||
|
- modules/pier/identity.go
|
||||||
|
- modules/pier/backend_guard.go
|
||||||
|
- modules/cabana/account_contributions.go
|
||||||
|
- modules/cabana/admin_openapi.go
|
||||||
|
- modules/cabana/http.go
|
||||||
|
- modules/cabana/backend_users_admin.go
|
||||||
|
- modules/cabana/backend_roles_admin.go
|
||||||
|
- modules/cabana/account.go
|
||||||
|
- modules/cabana/commands.go
|
||||||
|
- modules/cabana/contracts.go
|
||||||
|
- admin/openapi/admin.json
|
||||||
|
- admin/src/api/schema.d.ts
|
||||||
|
|
||||||
|
key-decisions:
|
||||||
|
- "The account item action route is POST {api}/account/contribution-items/{name}/{item}/actions/{action}, not /account/contributions/{name}/items/{item}/actions/{action}: the planned nine-segment POST overlaps the controller routes ({vendor}/{plugin}/{controller}/{id}/relations/{name}/records) and surf refuses the boot"
|
||||||
|
- "admin/openapi/admin.json and admin/src/api/schema.d.ts are regenerated in plan 01 (not 02), because the contract and conformance inventory tests fail go test ./... without them"
|
||||||
|
- "A requested * is offered on admin consent, exactly as on g15_ token creation (scopeOverlaps always offers *); D-11 hides only catalog scopes the admin cannot use and names outside the catalog"
|
||||||
|
- "Role delete fires no BackendAccessRevokedEvent: FormBeforeDelete refuses deleting a role that any administrator holds"
|
||||||
|
|
||||||
|
patterns-established:
|
||||||
|
- "Administrator-only grant: Subject backend, UserID 0, BackendUserID set; resolveOAuth branches before the UserID==0 refusal"
|
||||||
|
- "Consent JSON lives in cabana under the admin API and delegates to app.Lookup[pact.MCPAdminConsent] at request time"
|
||||||
|
|
||||||
|
requirements-completed: [SC-1, SC-2, SC-3, SC-5]
|
||||||
|
|
||||||
|
coverage:
|
||||||
|
- id: D1
|
||||||
|
description: "Administrator-only grant lists only the backend tools its scopes allow over a real /mcp request; empty-subject UserID-0 grant gets 401"
|
||||||
|
requirement: SC-2
|
||||||
|
verification:
|
||||||
|
- kind: integration
|
||||||
|
ref: "modules/pier/backend_subject_smoke_test.go#TestBackendSubjectSmoke"
|
||||||
|
status: pass
|
||||||
|
human_judgment: false
|
||||||
|
- id: D2
|
||||||
|
description: "wristband hands authorize off to {issuer}/connect by default and to Options.ConsentPath when set; DefaultScopes fill an empty-scope request"
|
||||||
|
requirement: SC-1
|
||||||
|
verification:
|
||||||
|
- kind: unit
|
||||||
|
ref: "modules/wristband/consent_path_smoke_test.go#TestConsentPathSmoke"
|
||||||
|
status: pass
|
||||||
|
human_judgment: false
|
||||||
|
- id: D3
|
||||||
|
description: "cabana admin consent endpoint: hidden scopes, dropped unrequested *, 401, 403 interactive_only, 404 without provider, 422 no_grantable_scopes, 400 bad body"
|
||||||
|
requirement: SC-1
|
||||||
|
verification:
|
||||||
|
- kind: integration
|
||||||
|
ref: "modules/cabana/mcp_consent_smoke_test.go#TestMCPAdminConsentSmoke"
|
||||||
|
status: pass
|
||||||
|
- kind: integration
|
||||||
|
ref: "modules/cabana/openapi_conformance_test.go#TestPhase10OpenAPIConformance"
|
||||||
|
status: pass
|
||||||
|
human_judgment: false
|
||||||
|
- id: D4
|
||||||
|
description: "My account items and item actions: items null without Items, cross-admin 404 without Run, ErrAccountItemNotFound 404, boot refusals"
|
||||||
|
requirement: SC-3
|
||||||
|
verification:
|
||||||
|
- kind: integration
|
||||||
|
ref: "modules/cabana/account_items_smoke_test.go#TestAccountItemsSmoke"
|
||||||
|
status: pass
|
||||||
|
human_judgment: false
|
||||||
|
- id: D5
|
||||||
|
description: "BackendAccessRevokedEvent fires in the save's transaction at delete, deactivate, password set, own password change, role change and role permission change; a listener error rolls back"
|
||||||
|
requirement: SC-3
|
||||||
|
verification:
|
||||||
|
- kind: integration
|
||||||
|
ref: "modules/cabana/backend_access_revoked_smoke_test.go#TestBackendAccessRevokedSmoke"
|
||||||
|
status: pass
|
||||||
|
human_judgment: false
|
||||||
|
- id: D6
|
||||||
|
description: "READMEs and docs describe every new identifier; docs checker passes; no consuming application named"
|
||||||
|
requirement: SC-5
|
||||||
|
verification:
|
||||||
|
- kind: other
|
||||||
|
ref: "go run ./cmd/summer docs:build --check; go test ./cmd/summer -run TestDocsTree"
|
||||||
|
status: pass
|
||||||
|
human_judgment: false
|
||||||
|
|
||||||
|
duration: 40min
|
||||||
|
completed: 2026-11-21
|
||||||
|
status: complete
|
||||||
|
---
|
||||||
|
|
||||||
|
# Phase 32.2 Plan 01: Framework seams for administrator-subject MCP OAuth Summary
|
||||||
|
|
||||||
|
**Administrator-only MCP grants that pier resolves straight to a scope-limited backend subject, a cabana admin consent API over a published pact.MCPAdminConsent, per-row My account items, and an in-transaction BackendAccessRevokedEvent at every admin access change**
|
||||||
|
|
||||||
|
## Performance
|
||||||
|
|
||||||
|
- **Duration:** about 40 min
|
||||||
|
- **Started:** 2026-11-20T22:52Z
|
||||||
|
- **Completed:** 2026-11-20T23:33Z
|
||||||
|
- **Tasks:** 4 of 4
|
||||||
|
- **Files modified:** 40 (including the regenerated admin.json and schema.d.ts)
|
||||||
|
|
||||||
|
## Accomplishments
|
||||||
|
|
||||||
|
- Tracer: a fake verifier's `Subject: backend` grant with `admin:read` lists the read-only backend tool and hides the write tool of a superuser over a real `/mcp` request through pier, the backend guard and `cabana.ScopeLimitFor` on Postgres. Removing `|| subject.ScopeLimited` makes the test fail, so it checks the scope limit. Linked user-mode grants are still not scope-limited, and `filter.go` is untouched.
|
||||||
|
- wristband `Options.ConsentPath` and `Options.DefaultScopes`. With both empty the handoff is byte-identical to the PHP server (`{issuer}/connect?request=<id>`), and `DefaultOptions` is unchanged.
|
||||||
|
- cabana `GET/POST {api}/mcp/consent/{request}` (interactive only; the POST needs X-Requested-With, is capped at 16 KiB and refuses unknown fields). Show lists the requested scopes that are in the catalog and that the administrator holds. Decide drops the rest, collapses `*`, and answers 422 when nothing is left. `TokenScopeNames` and `TokenScopeLabels` export the catalog for plugin Boot.
|
||||||
|
- My account sections can list rows with per-row actions. A row action runs only for an item the administrator's own `Items` listed, inside a transaction. Existing contributors are unchanged: a section without `Items` sends `items: null`.
|
||||||
|
- `cabana.BackendAccessRevokedEvent` (six reasons) fires synchronously inside the save's transaction at every D-13 site, and a listener error rolls the save back. The existing after-commit `MCPSubjectChanged` emissions stay as they were (3 calls in backend_users_admin.go).
|
||||||
|
|
||||||
|
## Task Commits
|
||||||
|
|
||||||
|
1. **Task 1 (tracer): administrator-only grants and configurable consent handoff** - `c63bfa3e` (feat)
|
||||||
|
2. **Task 2: cabana admin consent endpoint and exported token-scope catalog** - `97d7ee05` (feat)
|
||||||
|
3. **Task 3: per-item rows and item actions on My account** - `3f7ce602` (feat)
|
||||||
|
4. **Task 4: in-transaction BackendAccessRevokedEvent** - `fcc7bbde` (feat)
|
||||||
|
|
||||||
|
Tracer gate: auto mode is off and human_verify_mode is end-of-phase with an automated-only `<verify>`. The verify ran again end to end and passed (TestBackendSubjectSmoke PASS, not skipped), so expansion continued.
|
||||||
|
|
||||||
|
## Files Created/Modified
|
||||||
|
|
||||||
|
- `modules/pact/mcp.go`: MCPGrant.Subject, MCPGrantSubjectBackend, MCPSubject.ScopeLimited, MCPAdminConsent and its types and sentinels
|
||||||
|
- `modules/pact/capabilities.go`: AccountContribution.Items/ItemActions/ItemsEmpty, AccountItem, AccountItemAction, AccountItemActionInput, ErrAccountItemNotFound
|
||||||
|
- `modules/wristband/server.go`, `authorize.go`: ConsentPath and DefaultScopes, `consentPath()` and `defaultAuthorizeScopes()`
|
||||||
|
- `modules/pier/identity.go`: `resolveBackendGrant`, ScopeLimited in `fingerprint()`
|
||||||
|
- `modules/pier/backend_guard.go`: scope-limit condition widened by `subject.ScopeLimited`
|
||||||
|
- `modules/cabana/mcp_consent.go`: consent show and decide handlers
|
||||||
|
- `modules/cabana/token_scopes_export.go`: TokenScopeNames, TokenScopeLabels
|
||||||
|
- `modules/cabana/account_contributions.go`: item compile checks, list fields, `accountContributionItemAction`
|
||||||
|
- `modules/cabana/admin_events.go`: BackendAccessRevokedEvent, reasons, `fireBackendAccessRevoked`
|
||||||
|
- `modules/cabana/backend_users_admin.go`, `backend_roles_admin.go`, `account.go`, `commands.go`, `contracts.go`: D-13 call sites and the `passwordSetByOther` flag
|
||||||
|
- `modules/cabana/admin_openapi.go`: MCPConsent* and AccountItemView views, three swag doc funcs
|
||||||
|
- `modules/cabana/http.go`: three new routes in the backend group
|
||||||
|
- `modules/phrasebook/backend/lang/{en,pl}/lang.yaml`: `mcp_connect.request_not_found`, `mcp_connect.no_grantable_scopes`
|
||||||
|
- `admin/openapi/admin.json`, `admin/src/api/schema.d.ts`: regenerated by `scripts/check-admin-openapi.sh` (additions only; `npm --prefix admin run typecheck` passes)
|
||||||
|
- Route inventory tests updated: `security_coverage_test.go`, `phase10_coverage_test.go`, `phase10_csrf_test.go` (40 unsafe routes), `token_routes_test.go`, `openapi_conformance_test.go` (new cases and a fake consent provider)
|
||||||
|
- Docs: pact, wristband, pier and cabana READMEs; `docs/services/mcp.md`, `oauth-server.md`, `events.md` (new framework event table); `docs/backend/users-and-permissions.md`; `docs/plugins/registration.md`
|
||||||
|
|
||||||
|
## Decisions Made
|
||||||
|
|
||||||
|
- The pier backend branch runs before the `grant.UserID == 0` refusal. Every other grant goes down the unchanged path, so a grant with an empty Subject and UserID 0 still gets 401 (tested).
|
||||||
|
- `defaultAuthorizeScopes` drops identity scopes and duplicates as well as names outside the allowed set. It falls back to `read` when nothing is left.
|
||||||
|
- The consent view's `redirect_host` is `url.Host`, port included. For a URI without a host it is the URI with the query and fragment removed.
|
||||||
|
- Show loads the administrator (login, "first last", email) from backend_users. A database failure answers 500 instead of leaving `admin` out.
|
||||||
|
- Swag `enums:"allow,deny"` is set on `MCPConsentDecisionRequest.Decision`. The `items`/`item_actions` fields are not marked nullable, matching the repo's existing convention for pointer and nil fields.
|
||||||
|
|
||||||
|
## Deviations from Plan
|
||||||
|
|
||||||
|
### Auto-fixed Issues
|
||||||
|
|
||||||
|
**1. [Rule 3 - Blocking] Item action route path changed**
|
||||||
|
- **Found during:** Task 3
|
||||||
|
- **Issue:** surf refused to boot with `POST /account/contributions/{name}/items/{item}/actions/{action}`. That nine-segment POST overlaps the controller routes (`{vendor}/{plugin}/{controller}/{id}/relations/{name}/records` and others). The overlap family surf then generates conflicts with the SPA catch-all `GET /backend/{path...}`.
|
||||||
|
- **Fix:** The route is now `POST {api}/account/contribution-items/{name}/{item}/actions/{action}`. It is strictly more specific than the record action route `{vendor}/{plugin}/{controller}/{id}/actions/{action}`, so no overlap is possible. The semantics are unchanged.
|
||||||
|
- **Impact for plan 02:** the SPA must call `/account/contribution-items/{name}/{item}/actions/{action}`, which the regenerated schema.d.ts already types. The UI-SPEC text naming the old path is out of date.
|
||||||
|
- **Committed in:** `3f7ce602`
|
||||||
|
|
||||||
|
**2. [Rule 3 - Blocking] admin.json and schema.d.ts regenerated in plan 01**
|
||||||
|
- **Found during:** Task 2
|
||||||
|
- **Issue:** The plan said not to run `scripts/check-admin-openapi.sh` here. But `TestPhase09ContractInventory` and `TestPhase10ConformanceInventory`/`TestPhase10OpenAPIConformance` fail `go test -short ./...` when a route is not in admin.json or has no conformance case. CLAUDE.md requires `go test ./...` to be green at every commit.
|
||||||
|
- **Fix:** Regenerated both files in tasks 2 and 3 (additions only), and added conformance cases plus a fake `pact.MCPAdminConsent` and an `Items` section to the conformance fixture. Updated the route inventories (CSRF count 38 to 40, token route classes, permission matrix). Plan 02's regeneration step will now find them up to date, and `check-admin-openapi.sh --check` passes.
|
||||||
|
- **Committed in:** `97d7ee05`, `3f7ce602`
|
||||||
|
|
||||||
|
**3. [Rule 1 - Interpretation] `*` on admin consent**
|
||||||
|
- **Found during:** Task 2
|
||||||
|
- **Issue:** The plan's smoke text says an admin with only read permissions "sees admin:read and not *". Under the g15_ token policy (D-09, `scopeOverlaps`), however, `*` is always offered.
|
||||||
|
- **Fix:** I kept the token policy. The smoke covers it through the request: the provider does not request `*`, so it is hidden and dropped from `[*, admin:read]`, and Decide gets `[admin:read]`. A second case shows that a requested `*` is offered and collapses the grant to `["*"]`. Plans 02 and 03 should expect `*` to appear when the client requests it.
|
||||||
|
- **Committed in:** `97d7ee05`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Total deviations:** 3 (2 blocking fixes, 1 interpretation). **Impact:** no scope creep. The route path change is the only contract difference that plan 02 has to pick up.
|
||||||
|
|
||||||
|
## Issues Encountered
|
||||||
|
|
||||||
|
- `cabana.Activate` registers the `backend` middleware itself, so the pier fixture plugin must not declare one (the first test run failed with a duplicate middleware error).
|
||||||
|
- Plugin token scopes need a description (boot check), so the consent fixture now has one.
|
||||||
|
|
||||||
|
## Notes for later plans
|
||||||
|
|
||||||
|
- D-13 role delete: `rolesAdmin.FormBeforeDelete` refuses deleting a role that any administrator holds (deleted administrators included), so no event is added there.
|
||||||
|
- No "sign out everywhere" action exists in cabana. None was added, and the docs say so.
|
||||||
|
- `admin:reset-password` fires `password_reset` inside its transaction. Its smoke coverage is left to plan 05, as the plan says.
|
||||||
|
- The ScopeLimited mutation check (removing the condition makes TestBackendSubjectSmoke fail) was run by hand and is not committed.
|
||||||
|
|
||||||
|
## Verification
|
||||||
|
|
||||||
|
- Task verifies all passed: `TestBackendSubjectSmoke`, `TestConsentPathSmoke`, `TestMCPScopesSmoke`, `TestMCPSeam`, `TestDiscoveryFields`, `TestBackendScopeUnavailable`, `TestMCPAdminConsentSmoke`, `TestAccountContributionsSmoke`, `TestPhase09ContractInventory`, `TestScopeLimitForMethods`, `TestAccountItemsSmoke`, the existing account contribution tests, `TestBackendAccessRevokedSmoke`, `TestFireSubjectChanged*`. Each passed and none was skipped.
|
||||||
|
- `go vet ./...` and `go test -short -count=1 ./...` pass for the whole framework module. The full Docker runs of `./modules/cabana`, `./modules/pier`, `./modules/wristband` and `./modules/pact` pass.
|
||||||
|
- `go test ./cmd/summer -run TestDocsTree` and `summer docs:build --check` pass. `scripts/check-admin-openapi.sh --check` passes, and so does `npm --prefix admin run typecheck`.
|
||||||
|
- `git grep -n -i 'grzyby' -- modules/pact modules/wristband modules/pier modules/cabana docs` finds nothing.
|
||||||
|
|
||||||
|
## User Setup Required
|
||||||
|
|
||||||
|
None.
|
||||||
|
|
||||||
|
## Next Phase Readiness
|
||||||
|
|
||||||
|
- Plan 02 can build ConnectView and the item rows against the typed schema. It must use the `/account/contribution-items/...` path.
|
||||||
|
- Plan 03 implements `pact.MCPAdminConsent`, sets `wristband.Options.ConsentPath`/`DefaultScopes`, answers `Subject: backend` grants and listens for `cabana.BackendAccessRevokedEvent`.
|
||||||
|
|
||||||
|
## Self-Check: PASSED
|
||||||
|
|
||||||
|
- All 8 created files exist on disk.
|
||||||
|
- Commits c63bfa3e, 97d7ee05, 3f7ce602 and fcc7bbde are in `git log`.
|
||||||
|
|
||||||
|
---
|
||||||
|
*Phase: 32.2-mcp-oauth-with-administrator-subjects*
|
||||||
|
*Completed: 2026-11-21*
|
||||||
Reference in New Issue
Block a user