docs(32.2): create phase plan
Five plans in four waves: framework seams, admin SPA consent route and plugin backend mode in parallel, app wiring with a local proof, then unit tests and the release checkpoint. Research open questions marked resolved.
This commit is contained in:
@@ -1722,7 +1722,18 @@ Plans:
|
|||||||
5. Module READMEs, `docs/` pages and the app's DEPLOY.md are updated; the new code has unit tests in the phase's last plan; the framework and `sm-oauthserver-plugin` get patch tags.
|
5. Module READMEs, `docs/` pages and the app's DEPLOY.md are updated; the new code has unit tests in the phase's last plan; the framework and `sm-oauthserver-plugin` get patch tags.
|
||||||
|
|
||||||
Plans:
|
Plans:
|
||||||
- [ ] TBD (run /msd-plan-phase 32.2 to break down)
|
**Wave 1**
|
||||||
|
- [ ] 32.2-01-PLAN.md — Framework seams: pact backend grant and consent provider, wristband handoff, pier scope limit, cabana consent endpoint, revoke event, account items
|
||||||
|
|
||||||
|
**Wave 2** *(blocked on Wave 1 completion)*
|
||||||
|
- [ ] 32.2-02-PLAN.md — Admin SPA consent route, switch account, account items, openapi and dist
|
||||||
|
- [ ] 32.2-03-PLAN.md — sm-oauthserver-plugin backend mode: config, migration, store, verifier, consent provider, revocation, My account, connections screen
|
||||||
|
|
||||||
|
**Wave 3** *(blocked on Wave 2 completion)*
|
||||||
|
- [ ] 32.2-04-PLAN.md — sm-grzybyfunkcjonalne-app wiring, local MCP OAuth proof, DEPLOY.md
|
||||||
|
|
||||||
|
**Wave 4** *(blocked on Wave 3 completion)*
|
||||||
|
- [ ] 32.2-05-PLAN.md — Unit tests, regressions and release checkpoint
|
||||||
|
|
||||||
### Phase 32.1: MCP OAuth for plugin apps: declared scopes, MCP subject on context, per-client MCP consent (INSERTED)
|
### Phase 32.1: MCP OAuth for plugin apps: declared scopes, MCP subject on context, per-client MCP consent (INSERTED)
|
||||||
|
|
||||||
|
|||||||
@@ -0,0 +1,401 @@
|
|||||||
|
---
|
||||||
|
phase: 32.2
|
||||||
|
plan: 01
|
||||||
|
type: execute
|
||||||
|
wave: 1
|
||||||
|
depends_on: []
|
||||||
|
files_modified:
|
||||||
|
- modules/pact/mcp.go
|
||||||
|
- modules/pact/capabilities.go
|
||||||
|
- modules/pact/README.md
|
||||||
|
- modules/wristband/server.go
|
||||||
|
- modules/wristband/authorize.go
|
||||||
|
- modules/wristband/consent_path_smoke_test.go
|
||||||
|
- modules/wristband/README.md
|
||||||
|
- modules/pier/identity.go
|
||||||
|
- modules/pier/backend_guard.go
|
||||||
|
- modules/pier/backend_subject_smoke_test.go
|
||||||
|
- modules/pier/README.md
|
||||||
|
- modules/cabana/token_scopes_export.go
|
||||||
|
- modules/cabana/mcp_consent.go
|
||||||
|
- modules/cabana/mcp_consent_smoke_test.go
|
||||||
|
- modules/cabana/account_contributions.go
|
||||||
|
- modules/cabana/account_items_smoke_test.go
|
||||||
|
- modules/cabana/admin_events.go
|
||||||
|
- modules/cabana/backend_access_revoked_smoke_test.go
|
||||||
|
- modules/cabana/backend_users_admin.go
|
||||||
|
- modules/cabana/backend_roles_admin.go
|
||||||
|
- modules/cabana/account.go
|
||||||
|
- modules/cabana/commands.go
|
||||||
|
- modules/cabana/http.go
|
||||||
|
- modules/cabana/admin_openapi.go
|
||||||
|
- modules/cabana/README.md
|
||||||
|
- modules/phrasebook/backend/lang/en/lang.yaml
|
||||||
|
- modules/phrasebook/backend/lang/pl/lang.yaml
|
||||||
|
- docs/services/mcp.md
|
||||||
|
- docs/services/oauth-server.md
|
||||||
|
- docs/services/events.md
|
||||||
|
- docs/backend/users-and-permissions.md
|
||||||
|
- docs/plugins/registration.md
|
||||||
|
autonomous: true
|
||||||
|
requirements: [SC-1, SC-2, SC-3, SC-5]
|
||||||
|
estimate:
|
||||||
|
tokens: 120000
|
||||||
|
raw_tokens: 120000
|
||||||
|
tasks: 4
|
||||||
|
confidence: low
|
||||||
|
must_haves:
|
||||||
|
truths:
|
||||||
|
- "SC-1, D-04: wristband Options.ConsentPath and Options.DefaultScopes are new. Empty ConsentPath keeps the authorize handoff byte-identical to today ({issuer}/connect?request=<id>); a set path is appended to the issuer instead. Empty DefaultScopes keeps the PHP fallback read; a set list (filtered to the resolved allowed set) is what an authorize request with no data scope gets. DefaultOptions is unchanged."
|
||||||
|
- "SC-2, D-01, D-09: pact.MCPGrant has Subject (pact.MCPGrantSubjectBackend = backend) and pact.MCPSubject has ScopeLimited. pier resolves a grant with Subject backend, UserID 0 and BackendUserID set straight to a backend subject: no frontend subject, no MCPLinkedBackendResolver lookup, binding oauth:backend:<client>:<admin>, read/write ceiling off, ScopeLimited true."
|
||||||
|
- "SC-2, D-09: the backend guard applies cabana.ScopeLimitFor to a subject with ScopeLimited true exactly as to a g15_ personal-token subject; a linked user-mode grant (ScopeLimited false, ClientID set) still gets no scope limit, and a grant with Subject empty and UserID 0 is still refused."
|
||||||
|
- "SC-1, D-03, D-11: cabana serves GET and POST {admin api}/mcp/consent/{request} inside the backend-guarded admin group, interactive-only (a g15_ token gets 403 interactive_only) and X-Requested-With on POST. It delegates to a published pact.MCPAdminConsent and answers 404 request_not_found when none is published or the provider answers pact.ErrMCPConsentNotFound. Show lists only requested ∩ catalog ∩ scopes the administrator can use; Decide drops submitted scopes outside that set, collapses * like token creation, and answers 422 no_grantable_scopes when nothing is left."
|
||||||
|
- "D-09: cabana.TokenScopeNames(app) answers the token-scope catalog names in catalog order (*, admin:read, then plugin TokenScopes) before cabana.Activate, and cabana.TokenScopeLabels translates catalog names to their labels."
|
||||||
|
- "SC-3, D-12: pact.AccountContribution gains Items, ItemActions and ItemsEmpty. A section with nil Items serialises items as null and renders as today; a section with Items always sends an array. POST /account/contributions/{name}/items/{item}/actions/{action} answers 404 for an item the administrator's own Items did not list or when Run answers pact.ErrAccountItemNotFound, 403 for missing permissions, and runs Run inside a transaction."
|
||||||
|
- "SC-3, D-13: cabana.BackendAccessRevokedEvent is fired synchronously inside the save's transaction on admin delete, deactivate, password set by another admin, own password change, admin:reset-password, the administrator's role/own permissions/superuser flag change, and a role's permission change (for every holder). A listener error rolls the save back. The existing after-commit MCPSubjectChanged emissions are unchanged. Sign out everywhere is not offered by cabana; the docs say so."
|
||||||
|
- "SC-5: module READMEs (pact, wristband, pier, cabana) and docs/services/mcp.md, oauth-server.md, events.md, docs/backend/users-and-permissions.md and docs/plugins/registration.md describe every identifier this plan adds, in the commit that adds it; framework docs and code never name a consuming application; docs:build --check passes."
|
||||||
|
artifacts:
|
||||||
|
- path: modules/pact/mcp.go
|
||||||
|
provides: "MCPGrant.Subject, MCPGrantSubjectBackend, MCPSubject.ScopeLimited, MCPAdminConsent, MCPAdminConsentRequest, MCPAdminConsentDecision, ErrMCPConsentNotFound, ErrMCPConsentNoScopes"
|
||||||
|
contains: "MCPGrantSubjectBackend"
|
||||||
|
- path: modules/pact/capabilities.go
|
||||||
|
provides: "AccountContribution.Items/ItemActions/ItemsEmpty, AccountItem, AccountItemAction, AccountItemActionInput, ErrAccountItemNotFound"
|
||||||
|
contains: "AccountItemAction"
|
||||||
|
- path: modules/wristband/server.go
|
||||||
|
provides: "Options.ConsentPath, Options.DefaultScopes"
|
||||||
|
contains: "ConsentPath"
|
||||||
|
- path: modules/pier/identity.go
|
||||||
|
provides: "backend-only grant branch of resolveOAuth"
|
||||||
|
contains: "MCPGrantSubjectBackend"
|
||||||
|
- path: modules/cabana/mcp_consent.go
|
||||||
|
provides: "GET/POST {api}/mcp/consent/{request} handlers"
|
||||||
|
contains: "MCPAdminConsent"
|
||||||
|
- path: modules/cabana/token_scopes_export.go
|
||||||
|
provides: "TokenScopeNames, TokenScopeLabels"
|
||||||
|
contains: "func TokenScopeNames"
|
||||||
|
- path: modules/cabana/admin_events.go
|
||||||
|
provides: "BackendAccessRevokedEvent and reason constants, fireBackendAccessRevoked"
|
||||||
|
contains: "BackendAccessRevokedEvent"
|
||||||
|
key_links:
|
||||||
|
- from: modules/wristband/authorize.go
|
||||||
|
to: Options.ConsentPath
|
||||||
|
via: "handoff URL built from issuer + consent path (default /connect)"
|
||||||
|
pattern: "ConsentPath"
|
||||||
|
- from: modules/pier/identity.go resolveOAuth
|
||||||
|
to: modules/pier/backend_guard.go principal
|
||||||
|
via: "MCPSubject.ScopeLimited set by the backend branch, read by the scope-limit condition"
|
||||||
|
pattern: "ScopeLimited"
|
||||||
|
- from: modules/cabana/mcp_consent.go
|
||||||
|
to: pact.MCPAdminConsent
|
||||||
|
via: "app.Lookup at request time"
|
||||||
|
pattern: "Lookup\\[pact.MCPAdminConsent\\]"
|
||||||
|
- from: modules/cabana/backend_users_admin.go, account.go, commands.go, backend_roles_admin.go
|
||||||
|
to: modules/cabana/admin_events.go
|
||||||
|
via: "fireBackendAccessRevoked with the save's transaction"
|
||||||
|
pattern: "fireBackendAccessRevoked"
|
||||||
|
---
|
||||||
|
|
||||||
|
<objective>
|
||||||
|
User story (phase goal, ROADMAP 32.2): **As an** editor of a blog-only application whose MCP tools are backend-guarded (Journal) and which has no frontend users, **I want to** add the site's `/mcp` as a connector and sign in once as my administrator account over OAuth, **so that** agents no longer need a hand-copied `g15_` personal token.
|
||||||
|
|
||||||
|
Slice in this plan (the thin end-to-end path the tracer proves): an MCP client holding an administrator-only grant calls tools/list on `/mcp` and sees only the backend tools that the administrator's cabana permissions and granted scopes allow. That is the same cap a `g15_` token with those scopes gets. The tracer sends a real HTTP request through pier, the backend guard and cabana.ScopeLimitFor to a Postgres-backed backend tool (TestBackendSubjectSmoke), and proves that wristband hands authorize off to a configured consent path (TestConsentPathSmoke). The token comes from a fake verifier because issuing it is plan 03's job.
|
||||||
|
|
||||||
|
Lean-split exception (accepted; recorded for the MVP check): the phase's plans follow repository and surface boundaries (01 framework, 02 admin SPA, 03 sm-oauthserver-plugin, 04 the first consumer app, 05 tests and release), not user-visible slices. The user confirmed this 5-plan split under the project's lean-planning rule (CLAUDE.md, "few, large plans per phase"). The boundaries also match the release order, because the plugin can only require a framework version that has been tagged. Each plan still leads with a tracer through every layer it touches. The first real-token path is plan 03's tracer (authorize, cabana consent, token, verifier). The first path a person can run end to end (discovery, registration, admin sign-in, consent, Journal tool call) is plan 04's tracer. On its own, plan 01's only observable result is the tracer's tools/list response.
|
||||||
|
|
||||||
|
Framework seams for SC-1, SC-2, SC-3 and the framework half of SC-5 (D-01, D-03, D-04, D-09, D-11, D-12, D-13): the pieces of summercms.go that an administrator-subject mode of the OAuth server plugin needs, all additive and off unless a plugin uses them.
|
||||||
|
|
||||||
|
Purpose: plans 02 (admin SPA) and 03 (sm-oauthserver-plugin backend mode) build against these contracts. Every zero value means today's behaviour, so applications on the frontend-user MCP flow are unchanged.
|
||||||
|
Output: pact, wristband, pier and cabana API, the cabana consent endpoint and account-item route with swag annotations, the in-transaction revocation event at every D-13 site, smoke tests, and the READMEs and docs pages in the same commits. The broad unit-test pass is plan 05. The openapi document and the SPA types are regenerated in plan 02, not here.
|
||||||
|
|
||||||
|
⚠ spec-less probe fallback skipped: phase has no requirement IDs to probe (visible skip). SC-1..SC-5 from the ROADMAP stand in as requirements.
|
||||||
|
|
||||||
|
Discretion recorded here (CONTEXT "Claude's Discretion"):
|
||||||
|
- pier representation: pact.MCPGrant.Subject with the constant pact.MCPGrantSubjectBackend; UserID stays 0 and BackendUserID carries the administrator.
|
||||||
|
- Consent JSON lives in cabana under the admin API and delegates to a published pact.MCPAdminConsent provider, because plugin routes cannot read the admin cookie (cabana.ResolveBackend never reads it) and the SPA cannot load plugin code. cabana owns the scope policy (catalog, scopeOverlaps, validateTokenScopes); the provider only resolves and issues.
|
||||||
|
- D-13 uses a new in-transaction cabana event mirroring sm-user-plugin's AccessRevokedEvent. Sign out everywhere: cabana has no such action; documented as not offered.
|
||||||
|
- Reversibility: D-04 and the new pact types are costly (published contracts other apps will adopt), recorded on the tasks; no one-way door, so no checkpoint.
|
||||||
|
</objective>
|
||||||
|
|
||||||
|
<execution_context>
|
||||||
|
@~/.claude/msd-core/workflows/execute-plan.md
|
||||||
|
@~/.claude/msd-core/templates/summary.md
|
||||||
|
</execution_context>
|
||||||
|
|
||||||
|
<context>
|
||||||
|
@.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-CONTEXT.md
|
||||||
|
@.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-RESEARCH.md
|
||||||
|
@.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-PATTERNS.md
|
||||||
|
@.planning/notes/2026-11-20-mcp-oauth-backend-subject.md
|
||||||
|
@.planning/notes/oauth2-wristband-direct-port.md
|
||||||
|
@modules/pact/mcp.go
|
||||||
|
@modules/pact/capabilities.go
|
||||||
|
@modules/wristband/server.go
|
||||||
|
@modules/wristband/authorize.go
|
||||||
|
@modules/wristband/consent.go
|
||||||
|
@modules/pier/identity.go
|
||||||
|
@modules/pier/backend_guard.go
|
||||||
|
@modules/pier/events.go
|
||||||
|
@modules/cabana/token_scopes.go
|
||||||
|
@modules/cabana/token_commands.go
|
||||||
|
@modules/cabana/token_resolver.go
|
||||||
|
@modules/cabana/api_tokens.go
|
||||||
|
@modules/cabana/account_tokens.go
|
||||||
|
@modules/cabana/account_contributions.go
|
||||||
|
@modules/cabana/subject_events.go
|
||||||
|
@modules/cabana/http.go
|
||||||
|
@modules/cabana/admin_openapi.go
|
||||||
|
|
||||||
|
<interfaces>
|
||||||
|
Existing (read this session):
|
||||||
|
- pact.MCPGrant{UserID uint; ClientID string; TokenID uint; Scopes []string; ExpiresAt time.Time; BackendUserID uint}
|
||||||
|
- pact.MCPSubject{Guard string; UserID uint; Scopes []string; ClientID string; TokenID uint}
|
||||||
|
- pact.MCPSubjectChanged{Guard, UserID, Kind, TokenID, ClientID}; kinds MCPSubjectPermissions, MCPSubjectLink, MCPSubjectRevoked, MCPSubjectDeleted
|
||||||
|
- pact.AccountContribution{Name, Label, Description string; Status func(ctx, adminID uint) (string, error) `json:"-"`; Actions []AccountAction}
|
||||||
|
- pact.AccountAction{Name, Label, Confirm string; Danger bool; Permissions []string; Applies func(ctx, adminID uint) (bool, error); Run func(ctx, AccountActionInput) (AccountActionResult, error)}
|
||||||
|
- pact.AccountActionResult{Message, URL string}
|
||||||
|
- wristband: authorize.go line 187 builds the handoff as s.opts.Issuer + "/connect?request=" + rfc3986Escape(requestID); parseAuthorizeScopes falls back to []string{"read"} at line 250
|
||||||
|
- wristband: (s *Server) PendingRequest(ctx, requestID, userID) (PendingRequestView, error); IssueCode(ctx, requestID, userID, grantedScopes, collectionIDs) (string, error); DenyPending(ctx, requestID, userID) (string, error); ErrPendingNotFound, ErrNoGrantableScopes
|
||||||
|
- pier: resolveOAuth refuses grant.UserID == 0; Identity has unexported ceiling and consentedBackend; writes() = !ceiling || Scopes contains write; fingerprint() writes each subject's Guard:UserID:ClientID:sorted scopes
|
||||||
|
- pier backend_guard.go principal: scope limit only when subject.ClientID == "" && subject.TokenID != 0, through cabana.ScopeLimitFor(g.app, subject.Scopes, method), known == 0 → errScopeUnavailable
|
||||||
|
- cabana: scopeAll "*", scopeAdminRead "admin:read"; tokenCatalogForApp(app) (*Registry, error) compiles the catalog from party.Activated; scopeOverlaps(reg, owner, name) bool; validateTokenScopes(reg, owner, scopes) ([]string, map[string]any); mapCompiledScope(ctx, tr, scope) AdminAPITokenScope{Name, Label, Description, ReadOnly, Known}
|
||||||
|
- cabana: accountPrincipal(w, r) *bouncer.Principal; interactiveOnly(h); requireAjax(h); WriteData; WriteError; WriteErrorDetails; backendMessage(ctx, tr, key, fallback); TxFromContext(ctx) (*gorm.DB, bool); lagoon.AfterCommit
|
||||||
|
- cabana: fireSubjectChanged(ctx, app, kind, adminIDs...) fires MCPSubjectChanged after commit; revocationCutoff()
|
||||||
|
- cabana http.go line 335: r.GroupRaw(api, []string{"backend", "locale.from-principal"}, ...) holds /account* routes, e.g. g.Post("/account/contributions/{name}/actions/{action}", interactiveOnly(requireAjax(s.accountContributionAction)))
|
||||||
|
- cabana admin_openapi.go: AccountContributionView, AccountContributionActionView, AccountActionResultView and swag doc funcs AdminAccountContributions / AdminAccountContributionAction
|
||||||
|
- D-13 sites: backend_users_admin.go FormAfterDelete (tx from TxFromContext), the deactivate lifecycle action (Updates is_activated false + tokens_valid_after), FormBeforeUpdate (storePassword changed → cutoff), FormAfterUpdate (role/permissions/superuser change → MCPSubjectPermissions); backend_roles_admin.go FormAfterUpdate (holders); account.go accountUpdate changePassword inside its transaction closure (variable tx); commands.go admin:reset-password inside gdb.Transaction(func(tx *gorm.DB) error)
|
||||||
|
- sm-user-plugin classes/events.go AccessRevokedEvent{UserIDs []uint; Before time.Time; Reason string; Tx *gorm.DB} is the shape to mirror
|
||||||
|
</interfaces>
|
||||||
|
</context>
|
||||||
|
|
||||||
|
<tasks>
|
||||||
|
|
||||||
|
<task type="tracer">
|
||||||
|
<name>Tracer: an administrator-only grant reaches a backend tool through pier, scope-limited, and wristband hands off to a configured consent path</name>
|
||||||
|
<reversibility rating="costly">D-04 makes the handoff path a public wristband option, and MCPGrant.Subject / MCPSubject.ScopeLimited become a grant shape other plugins will produce and read.</reversibility>
|
||||||
|
<precondition>docker info exits 0 (the pier backend-guard smoke uses a testcontainers Postgres like modules/pier/backend_scope_unavailable_test.go).</precondition>
|
||||||
|
<files>modules/pact/mcp.go, modules/wristband/server.go, modules/wristband/authorize.go, modules/wristband/consent_path_smoke_test.go, modules/pier/identity.go, modules/pier/backend_guard.go, modules/pier/backend_subject_smoke_test.go, modules/pact/README.md, modules/wristband/README.md, modules/pier/README.md, docs/services/mcp.md, docs/services/oauth-server.md</files>
|
||||||
|
<read_first>
|
||||||
|
modules/pact/mcp.go (MCPSubject at line 134, MCPGrant at line 280, MCPLinkedBackendResolver)
|
||||||
|
modules/wristband/server.go (Options; ScopesSupported doc comment is the empty-means-default pattern; DefaultOptions)
|
||||||
|
modules/wristband/authorize.go (line 187 handoff, line 43 comment, parseAuthorizeScopes fallback at line 250, allowedAuthorizeScopes)
|
||||||
|
modules/wristband/mcp_scopes_smoke_test.go (smoke test shape to copy)
|
||||||
|
modules/pier/identity.go (resolveOAuth, consentedBackendSubject, writes, fingerprint)
|
||||||
|
modules/pier/backend_guard.go (principal)
|
||||||
|
modules/pier/events.go (revokedMatch and refreshBackend; read only, no change expected)
|
||||||
|
modules/pier/backend_scope_unavailable_test.go (Docker harness for cabana-backed backend tools to copy)
|
||||||
|
modules/pier/helpers_test.go (fake verifier acmeVerifier)
|
||||||
|
.planning/notes/oauth2-wristband-direct-port.md (default bytes must stay PHP-identical)
|
||||||
|
</read_first>
|
||||||
|
<action>
|
||||||
|
pact (modules/pact/mcp.go), per D-01 and D-09: add Subject string to MCPGrant, documented as the kind of subject the grant names; empty means the frontend user in UserID (today's meaning). Add exported const MCPGrantSubjectBackend = "backend": the grant's subject is the backend account in BackendUserID, UserID is 0 and no frontend user is involved. Add ScopeLimited bool to MCPSubject: when true, the guard caps the subject with the same scope limit a personal token with those scopes gets. Zero values keep every existing producer and reader unchanged. Update the MCPGrant and BackendUserID doc comments so they describe both meanings.
|
||||||
|
|
||||||
|
wristband (D-04): add Options.ConsentPath string, appended to Issuer for the MCP authorize handoff; empty means "/connect". Add Options.DefaultScopes []string: the scopes an MCP authorize request gets when it names no data scope (absent, empty or identity-only scope value); empty means the PHP default read. Leave DefaultOptions unchanged. In authorize.go build the handoff from Issuer + resolved consent path + "?request=" + rfc3986Escape(requestID), so the default bytes are identical to today. Thread the default-scope list into the empty-scope fallback of parseAuthorizeScopes (resolved per server: DefaultScopes filtered to the server's allowed set; if empty after filtering, read). Do not change client lookup, redirect matching, PKCE, resource validation or the order of checks. Update the line 43 comment and the Options doc comments. OIDC flavour is unaffected.
|
||||||
|
|
||||||
|
pier (D-01, D-09): in resolveOAuth, after MCPVerifyToken succeeds, branch when grant.Subject == pact.MCPGrantSubjectBackend: refuse with ErrUnauthorized unless grant.UserID == 0 and grant.BackendUserID != 0; otherwise build Identity with Scopes cloned, Binding "oauth:backend:" + ClientID + ":" + BackendUserID, ExpiresAt, TokenKind TokenKindOAuth, ceiling false, no Frontend subject even when a frontend guard is registered, and Backend = &pact.MCPSubject{Guard: BackendGuard, UserID: BackendUserID, Scopes, ClientID, TokenID, ScopeLimited: true}. Do not call linkedBackend or consentedBackendSubject on that path. The existing path below stays byte-for-byte the same, including the grant.UserID == 0 refusal for grants without the backend subject. In backend_guard.go principal change the scope-limit condition to apply when (subject.ClientID == "" and subject.TokenID != 0) or subject.ScopeLimited; user-mode linked grants never set ScopeLimited, so they stay unlimited (D-09 says that must not change). Add ScopeLimited to the per-subject part of fingerprint() so a change re-filters a cached server. Do not edit filter.go.
|
||||||
|
|
||||||
|
Smoke tests, same commit. modules/wristband/consent_path_smoke_test.go TestConsentPathSmoke: a server with default options redirects a valid authorize request to {issuer}/connect?request=..., a server with ConsentPath "/admin/connect" redirects to {issuer}/admin/connect?request=..., and a server with DefaultScopes ["acme"] and acme in ScopesSupported stores acme for a request with no scope (read via PendingRequest). modules/pier/backend_subject_smoke_test.go TestBackendSubjectSmoke (Docker, package pier_test, copy the backend_scope_unavailable_test.go harness): a fake verifier answers a grant with Subject backend, UserID 0, BackendUserID = a seeded administrator and Scopes [admin:read]; tools/list over /mcp lists a read-only backend tool and hides a write backend tool of the fixture controller; the same verifier answering Subject "" and UserID 0 gets 401. Skip under testing.Short(), with flag.Parse() handled the way the existing pier Docker tests do.
|
||||||
|
|
||||||
|
Docs in the same commit (D-04, D-09, SC-5): modules/pact/README.md (MCPGrant.Subject, MCPGrantSubjectBackend, MCPSubject.ScopeLimited), modules/wristband/README.md (ConsentPath, DefaultScopes, defaults unchanged), modules/pier/README.md (administrator-only grants: backend subject straight from the grant, no link lookup, distinct binding, ceiling off, scope limit like a personal token; linked grants unchanged), docs/services/mcp.md and docs/services/oauth-server.md (the same rules in prose). Prose only, no new Go code block unless it is a src= reference into compiled test code refreshed with summer docs:sync. Never name a consuming application in framework code or docs. Stage only the files of this task by path; do not git add -A; leave other sessions' uncommitted files alone.
|
||||||
|
</action>
|
||||||
|
<verify>
|
||||||
|
<automated>go test -count=1 -run 'TestBackendSubjectSmoke|TestConsentPathSmoke|TestMCPScopesSmoke|TestMCPSeam|TestDiscoveryFields|TestBackendScopeUnavailable' ./modules/pier ./modules/wristband</automated>
|
||||||
|
<fails_when>non-zero exit, or a line contains FAIL, or the output contains `[no tests to run]`, or `--- SKIP: TestBackendSubjectSmoke` appears, or TestBackendSubjectSmoke or TestConsentPathSmoke has no `--- PASS` line (run with -v if needed)</fails_when>
|
||||||
|
<automated>go vet ./modules/pact ./modules/pier ./modules/wristband && go test -short -count=1 ./modules/pact ./modules/pier ./modules/wristband && go test ./cmd/summer -run TestDocsTree -count=1 && go run ./cmd/summer docs:build --check</automated>
|
||||||
|
<fails_when>non-zero exit, or a line contains FAIL, or docs:build prints a problem line</fails_when>
|
||||||
|
</verify>
|
||||||
|
<acceptance_criteria>
|
||||||
|
- modules/pact/mcp.go contains `MCPGrantSubjectBackend = "backend"`, a `Subject string` field on MCPGrant and a `ScopeLimited bool` field on MCPSubject.
|
||||||
|
- modules/wristband/server.go contains `ConsentPath string` and `DefaultScopes []string` on Options; DefaultOptions has no ConsentPath or DefaultScopes entry.
|
||||||
|
- TestConsentPathSmoke passes, proving the default handoff is exactly {issuer}/connect?request=<id>.
|
||||||
|
- `grep -n 'subject.ScopeLimited' modules/pier/backend_guard.go` finds the scope-limit condition; `grep -n '"oauth:backend:"' modules/pier/identity.go` finds the backend binding.
|
||||||
|
- TestBackendSubjectSmoke passes (not skipped): admin:read grant lists the read-only backend tool and not the write tool; a grant with empty Subject and UserID 0 gets 401.
|
||||||
|
- modules/pier/filter.go has no diff in this commit.
|
||||||
|
- TestDocsTree and docs:build --check pass; `git grep -n -i 'grzyby' -- modules/pact modules/wristband modules/pier modules/cabana docs` prints nothing.
|
||||||
|
</acceptance_criteria>
|
||||||
|
<done>An administrator-only grant resolves to a scope-limited backend subject end to end through pier, and wristband can hand authorize off to a configured consent path with unchanged defaults. One commit with only this task's files.</done>
|
||||||
|
</task>
|
||||||
|
|
||||||
|
<task type="auto">
|
||||||
|
<name>Cabana admin consent endpoint backed by a published pact.MCPAdminConsent, with the token-scope catalog exported</name>
|
||||||
|
<reversibility rating="costly">The pact.MCPAdminConsent interface and the {api}/mcp/consent JSON contract are consumed by the admin SPA and by the OAuth server plugin; renaming them needs coordinated releases.</reversibility>
|
||||||
|
<precondition>docker info exits 0 (cabana admin smoke tests use Postgres).</precondition>
|
||||||
|
<files>modules/pact/mcp.go, modules/cabana/token_scopes_export.go, modules/cabana/mcp_consent.go, modules/cabana/mcp_consent_smoke_test.go, modules/cabana/http.go, modules/cabana/admin_openapi.go, modules/phrasebook/backend/lang/en/lang.yaml, modules/phrasebook/backend/lang/pl/lang.yaml, modules/pact/README.md, modules/cabana/README.md, docs/services/oauth-server.md</files>
|
||||||
|
<read_first>
|
||||||
|
modules/pact/mcp.go (MCPLinkedBackendResolver + LinkedBackendUser: provider interface and plain view struct pattern)
|
||||||
|
modules/cabana/token_commands.go (tokenCatalogForApp at line 101)
|
||||||
|
modules/cabana/token_scopes.go (catalog, scopeOverlaps at line 333)
|
||||||
|
modules/cabana/api_tokens.go (validateTokenScopes at line 133: * collapse and refusal rules)
|
||||||
|
modules/cabana/account_tokens.go (accountTokenScopes and mapCompiledScope: filtering by scopeOverlaps and label mapping)
|
||||||
|
modules/cabana/account_contributions.go (handler style: accountPrincipal, WriteData, WriteError, moduleLog)
|
||||||
|
modules/cabana/account.go (accountPrincipal, backendMessage)
|
||||||
|
modules/cabana/http.go (line 335 group, interactiveOnly/requireAjax wrapping)
|
||||||
|
modules/cabana/admin_openapi.go (lines 336-395: view structs and swag annotation style)
|
||||||
|
modules/cabana/account_contributions_smoke_test.go (Docker admin harness to copy)
|
||||||
|
../sm-oauthserver-plugin/controllers/mcp_consent_api.go (user-mode body shapes the admin view mirrors: mcpConsentClient, mcpScopeDetail, mcpConsentShowBody)
|
||||||
|
modules/phrasebook/backend/lang/en/lang.yaml and pl/lang.yaml (group layout)
|
||||||
|
</read_first>
|
||||||
|
<action>
|
||||||
|
pact (D-03): add the provider interface MCPAdminConsent with MCPAdminConsentShow(ctx context.Context, adminID uint, requestID string) (MCPAdminConsentRequest, error) and MCPAdminConsentDecide(ctx context.Context, adminID uint, requestID string, decision MCPAdminConsentDecision) (string, error), the second answering the client redirect URI. Add MCPAdminConsentRequest{RequestID, ClientID, ClientName, LogoURL, RedirectURI string; Scopes []string (requested data scopes, offline_access excluded); OfflineAccess bool (requested); ConsentRequired bool; ExpiresAt time.Time} and MCPAdminConsentDecision{Allow bool; Scopes []string; OfflineAccess bool}. Add sentinels ErrMCPConsentNotFound and ErrMCPConsentNoScopes. Doc: one provider per application, published through app.Publish by the plugin that owns the MCP authorization server; the framework applies the scope policy before calling Decide.
|
||||||
|
|
||||||
|
cabana catalog export (D-09), new file modules/cabana/token_scopes_export.go: TokenScopeNames(app *backpack.App) ([]string, error) answers the catalog names in catalog order (*, admin:read, then plugin TokenScopes) built on tokenCatalogForApp, so it works at plugin Boot before cabana.Activate. TokenScopeLabels(ctx context.Context, app *backpack.App, names []string) []string answers the translated label of each catalog name, the name itself for an unknown one, in input order. Neither changes the catalog.
|
||||||
|
|
||||||
|
cabana endpoint (D-03, D-09, D-11), new file modules/cabana/mcp_consent.go, mounted in the line 335 backend group of http.go as g.Get("/mcp/consent/{request}", interactiveOnly(s.mcpConsentShow)) and g.Post("/mcp/consent/{request}", interactiveOnly(requireAjax(s.mcpConsentDecide))). Both: accountPrincipal, then app.Lookup[pact.MCPAdminConsent](); none published → 404 code request_not_found. Show: call MCPAdminConsentShow(ctx, principal.ID, request); ErrMCPConsentNotFound → 404 request_not_found; other errors → 500 logged with moduleLog.ErrorContext (never log the request id together with a code). Answer MCPConsentView{request_id, client{id, name, redirect_host, logo_url}, admin{login, name, email}, scopes []AdminAPITokenScope, offline_access, consent_required, expires_at RFC 3339}. scopes = requested names in catalog order that are in the catalog and pass scopeOverlaps for the principal (D-11 hides the rest), mapped with mapCompiledScope. redirect_host = the host of RedirectURI, or its scheme-and-origin when the host is empty. admin = the administrator's login, "first last" name and email loaded from backend_users. Decide: decode MCPConsentDecisionRequest{decision "allow"|"deny", scopes []string, offline_access bool} under a 16 KiB http.MaxBytesReader with unknown fields refused (400). decision deny → MCPAdminConsentDecide with Allow false. decision allow → load the request through MCPAdminConsentShow again, keep submitted names that are requested and grantable (others dropped, not errors), normalise with validateTokenScopes (* collapses to ["*"]), empty → 422 no_grantable_scopes; OfflineAccess = requested && body offline_access; call Decide with Allow true. ErrMCPConsentNotFound → 404, ErrMCPConsentNoScopes → 422 no_grantable_scopes. Success → 200 MCPConsentDecisionView{redirect_uri}. cabana opens no transaction; the provider owns its lock and transaction. Messages through backendMessage with new keys mcp_connect.request_not_found and mcp_connect.no_grantable_scopes added to both en and pl phrasebook files (English: "This connection request has expired or does not exist." / "Choose at least one scope you can use."; Polish equivalents).
|
||||||
|
|
||||||
|
Swag (admin_openapi.go): exported view structs MCPConsentView, MCPConsentClientView, MCPConsentAdminView, MCPConsentDecisionRequest, MCPConsentDecisionView and doc funcs AdminMCPConsentShow (GET /mcp/consent/{request}: 200, 401, 403, 404) and AdminMCPConsentDecide (POST: 200, 400, 401, 403, 404, 422) in the style of lines 368-395. Do not run scripts/check-admin-openapi.sh here; plan 02 regenerates admin/openapi/admin.json and admin/src/api/schema.d.ts.
|
||||||
|
|
||||||
|
Smoke test modules/cabana/mcp_consent_smoke_test.go TestMCPAdminConsentSmoke (Docker, copy the account contributions smoke harness): a fake provider published for the test; an administrator holding only the read permissions behind admin:read sees admin:read and not * in Show; allow with scopes [*, admin:read] from that admin yields Decide called with [admin:read]; an anonymous request gets 401; a g15_ token gets 403 with reason interactive_only; no provider → 404. Docs same commit: pact README (MCPAdminConsent and its types), cabana README API reference (TokenScopeNames, TokenScopeLabels, the endpoint and its rules), docs/services/oauth-server.md (admin consent contract). Stage by path, no git add -A.
|
||||||
|
</action>
|
||||||
|
<verify>
|
||||||
|
<automated>go test -count=1 -run 'TestMCPAdminConsentSmoke|TestAccountContributionsSmoke|TestPhase09ContractInventory|TestScopeLimitForMethods' ./modules/cabana</automated>
|
||||||
|
<fails_when>non-zero exit, or a line contains FAIL, or `[no tests to run]`, or `--- SKIP: TestMCPAdminConsentSmoke` appears</fails_when>
|
||||||
|
<automated>go vet ./modules/pact ./modules/cabana && go test -short -count=1 ./modules/pact ./modules/cabana ./modules/phrasebook && go test ./cmd/summer -run TestDocsTree -count=1 && go run ./cmd/summer docs:build --check</automated>
|
||||||
|
<fails_when>non-zero exit, or a line contains FAIL, or docs:build prints a problem line</fails_when>
|
||||||
|
</verify>
|
||||||
|
<acceptance_criteria>
|
||||||
|
- `grep -n 'type MCPAdminConsent interface' modules/pact/mcp.go` matches; ErrMCPConsentNotFound and ErrMCPConsentNoScopes exist.
|
||||||
|
- `grep -n 'func TokenScopeNames(app \*backpack.App) (\[\]string, error)' modules/cabana/token_scopes_export.go` matches.
|
||||||
|
- http.go mounts `/mcp/consent/{request}` GET wrapped in interactiveOnly and POST wrapped in interactiveOnly(requireAjax(...)) inside the backend group.
|
||||||
|
- admin_openapi.go has `@Router /mcp/consent/{request} [get]` and `@Router /mcp/consent/{request} [post]`.
|
||||||
|
- TestMCPAdminConsentSmoke passes, not skipped, covering hidden scopes, the dropped `*`, 401, 403 interactive_only and 404 without provider.
|
||||||
|
- Both phrasebook files have mcp_connect.request_not_found and mcp_connect.no_grantable_scopes.
|
||||||
|
</acceptance_criteria>
|
||||||
|
<done>The admin SPA has a same-origin, cookie-authenticated consent API whose scope policy is the g15_ token policy, and a plugin can serve consent data by publishing one interface.</done>
|
||||||
|
</task>
|
||||||
|
|
||||||
|
<task type="auto">
|
||||||
|
<name>Per-item rows and item actions on My account contributions</name>
|
||||||
|
<reversibility rating="costly">AccountContribution.Items/ItemActions and the item action route are part of the pact plugin contract and the admin API.</reversibility>
|
||||||
|
<precondition>docker info exits 0.</precondition>
|
||||||
|
<files>modules/pact/capabilities.go, modules/cabana/account_contributions.go, modules/cabana/account_items_smoke_test.go, modules/cabana/http.go, modules/cabana/admin_openapi.go, modules/pact/README.md, modules/cabana/README.md, docs/plugins/registration.md, docs/backend/users-and-permissions.md</files>
|
||||||
|
<read_first>
|
||||||
|
modules/pact/capabilities.go (HasAccountContributions, AccountContribution, AccountAction, AccountActionInput, AccountActionResult at lines 596-650)
|
||||||
|
modules/cabana/account_contributions.go (compileAccountContributions at line 38, accountContributionsList at line 98, accountContributionAction at line 160)
|
||||||
|
modules/cabana/admin_openapi.go (AccountContributionView at line 336, AccountContributionActionView, annotations at lines 368-395)
|
||||||
|
modules/cabana/http.go (line 349-350 contribution routes)
|
||||||
|
modules/cabana/account_contributions_smoke_test.go and account_contributions_hardening_test.go (behaviour that must not change)
|
||||||
|
../sm-user-plugin/account_contributions.go (an existing contributor that must keep working unchanged)
|
||||||
|
.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-UI-SPEC.md section C3
|
||||||
|
</read_first>
|
||||||
|
<action>
|
||||||
|
pact (D-12): add to AccountContribution Items func(ctx context.Context, adminID uint) ([]AccountItem, error) with json:"-", ItemActions []AccountItemAction and ItemsEmpty string (phrase key or text; empty means the framework's own empty line). Add AccountItem{ID, Title, Subtitle string; Meta []string}, AccountItemAction{Name, Label, Confirm string; Danger bool; Permissions []string; Run func(ctx context.Context, in AccountItemActionInput) (AccountActionResult, error) json:"-"} and AccountItemActionInput{AdminID uint; ItemID string}. Add sentinel ErrAccountItemNotFound (Run answers it when the item is gone). Document that Confirm may contain :title, which the admin fills with the item's Title, and that Items must be a pure read scoped to the signed-in administrator. Nil Items keeps a section exactly as today.
|
||||||
|
|
||||||
|
cabana compile: in compileAccountContributions refuse at boot ItemActions without Items, an item action whose Name is not an identifier or repeats within the section, a nil Run and an empty Label, with the same error style as section actions.
|
||||||
|
|
||||||
|
cabana list: in accountContributionsList add to AccountContributionView Items []AccountItemView json:"items" (nil, serialised null, when the section has no Items func; a non-nil, possibly empty slice otherwise), ItemActions []AccountContributionActionView json:"item_actions" (only actions whose Permissions the administrator holds, via the same Allows check section actions use), and ItemsEmpty string json:"items_empty" (translated; empty when unset). A failing Items sets view.Error true, leaves items null, logs, and never hides other sections. Labels and Confirm texts are translated like section actions. New exported AccountItemView{ID, Title, Subtitle string; Meta []string}.
|
||||||
|
|
||||||
|
cabana route: g.Post("/account/contributions/{name}/items/{item}/actions/{action}", interactiveOnly(requireAjax(s.accountContributionItemAction))) next to the section action route. Handler: unknown section or action → 404; missing permissions → 403 like section actions; then call the section's Items for the signed-in administrator and answer 404 when {item} is not among the returned IDs (an administrator can never act on an item their own Items did not list); then run Run inside a transaction carried by the context exactly like accountContributionAction; ErrAccountItemNotFound from Run → 404; other errors → the existing action error mapping. 200 answers AccountActionResultView with the localized message.
|
||||||
|
|
||||||
|
Swag: AccountItemView, the new AccountContributionView fields, and doc func AdminAccountContributionItemAction for POST /account/contributions/{name}/items/{item}/actions/{action} (200, 401, 403, 404, 422).
|
||||||
|
|
||||||
|
Smoke test modules/cabana/account_items_smoke_test.go TestAccountItemsSmoke (Docker): a section without Items still answers items null; a section with Items for admin A lists two rows; the item action on a listed ID runs with AdminID and ItemID; the same ID posted by admin B (whose Items list is empty) gets 404 and Run is not called; Run answering ErrAccountItemNotFound gives 404; a boot with ItemActions and no Items fails. Docs same commit: pact README, cabana README, docs/plugins/registration.md and docs/backend/users-and-permissions.md (items, item actions, ItemsEmpty, :title). Stage by path.
|
||||||
|
</action>
|
||||||
|
<verify>
|
||||||
|
<automated>go test -count=1 -run 'TestAccountItemsSmoke|TestAccountContributionsSmoke|TestAccountContributions$|TestAccountContributionURL|TestAccountContributionsIsolation|TestAccountContributionsAppliesFailureFlagsSection' ./modules/cabana</automated>
|
||||||
|
<fails_when>non-zero exit, or a line contains FAIL, or `[no tests to run]`, or `--- SKIP: TestAccountItemsSmoke` appears</fails_when>
|
||||||
|
<automated>go vet ./modules/pact ./modules/cabana && go test -short -count=1 ./modules/pact ./modules/cabana && go test ./cmd/summer -run TestDocsTree -count=1 && go run ./cmd/summer docs:build --check</automated>
|
||||||
|
<fails_when>non-zero exit, or a line contains FAIL, or docs:build prints a problem line</fails_when>
|
||||||
|
</verify>
|
||||||
|
<acceptance_criteria>
|
||||||
|
- `grep -n 'type AccountItemAction struct' modules/pact/capabilities.go` and `grep -n 'ErrAccountItemNotFound' modules/pact/capabilities.go` match.
|
||||||
|
- http.go has the route `/account/contributions/{name}/items/{item}/actions/{action}` wrapped in interactiveOnly(requireAjax(...)).
|
||||||
|
- TestAccountItemsSmoke passes (not skipped), including the cross-admin 404 with Run not called.
|
||||||
|
- The existing account contribution tests named in the verify command still pass unchanged.
|
||||||
|
- admin_openapi.go has `@Router /account/contributions/{name}/items/{item}/actions/{action} [post]`.
|
||||||
|
</acceptance_criteria>
|
||||||
|
<done>A plugin can contribute a My account section with a list of rows and per-row actions; existing contributors render exactly as before.</done>
|
||||||
|
</task>
|
||||||
|
|
||||||
|
<task type="auto">
|
||||||
|
<name>In-transaction BackendAccessRevokedEvent at every D-13 site</name>
|
||||||
|
<reversibility rating="costly">BackendAccessRevokedEvent and its reason values become an event contract plugins listen to; a listener error now rolls back the admin save.</reversibility>
|
||||||
|
<precondition>docker info exits 0.</precondition>
|
||||||
|
<files>modules/cabana/admin_events.go, modules/cabana/backend_users_admin.go, modules/cabana/backend_roles_admin.go, modules/cabana/account.go, modules/cabana/commands.go, modules/cabana/backend_access_revoked_smoke_test.go, modules/cabana/README.md, docs/services/events.md, docs/backend/users-and-permissions.md</files>
|
||||||
|
<read_first>
|
||||||
|
modules/cabana/subject_events.go (fireSubjectChanged, fireTokenRevoked; keep them unchanged)
|
||||||
|
modules/cabana/backend_users_admin.go (FormAfterDelete line 219, deactivate action lines 276-292, FormBeforeUpdate around line 815, FormAfterUpdate line 830-845, the prior* fields on the model)
|
||||||
|
modules/cabana/backend_roles_admin.go (FormAfterUpdate lines 178-199; check for a role delete path that changes holders' permissions)
|
||||||
|
modules/cabana/account.go (accountUpdate changePassword inside the transaction closure, lines 370-398)
|
||||||
|
modules/cabana/commands.go (admin:reset-password transaction, lines 141-165)
|
||||||
|
modules/cabana/tx_context.go (TxFromContext)
|
||||||
|
modules/cabana/subject_events_test.go (listener test style)
|
||||||
|
../sm-user-plugin/classes/events.go (AccessRevokedEvent lines 112-130: synchronous fire with Tx, listener error aborts)
|
||||||
|
</read_first>
|
||||||
|
<action>
|
||||||
|
New file modules/cabana/admin_events.go (D-13): exported BackendAccessRevokedEvent{AdminIDs []uint; Reason string; Tx *gorm.DB} with reason constants BackendAccessDeleted = "deleted", BackendAccessDeactivated = "deactivated", BackendAccessPasswordChanged = "password_changed" (own change on My account), BackendAccessPasswordSet = "password_set" (set by another administrator), BackendAccessPasswordReset = "password_reset" (admin:reset-password), BackendAccessPermissions = "permissions" (role, own permissions, superuser flag, or a role's permissions). Doc: fired synchronously through app.Events.Fire inside the transaction of the save, before commit; a listener's error is returned and rolls the save back; listeners revoke grants keyed on the administrators and must not open their own transaction when Tx is set. Unexported fireBackendAccessRevoked(ctx context.Context, app *backpack.App, tx *gorm.DB, reason string, adminIDs ...uint) error: no-op answering nil when app or bus is nil or no non-zero id remains; otherwise fires one event with the de-duplicated non-zero ids and returns the listener error.
|
||||||
|
|
||||||
|
Call sites, each next to the existing fireSubjectChanged call (which stays as is) and each returning the error so the save rolls back: usersAdmin.FormAfterDelete (deleted, its tx); the deactivate lifecycle action (deactivated, the db/tx the action updates through); usersAdmin.FormBeforeUpdate records on the model an unexported flag when storePassword changed the password and the editor is another administrator, and FormAfterUpdate fires password_set when the flag is set; usersAdmin.FormAfterUpdate fires permissions when role, own permissions or superuser flag changed (D-13: revoke, not only re-list); rolesAdmin.FormAfterUpdate fires permissions for the holders it already plucks, through the save's transaction; account.go accountUpdate fires password_changed inside the transaction closure when changePassword is set, with the closure's tx; commands.go admin:reset-password fires password_reset inside its transaction with tx. If backend_roles_admin.go allows deleting a role that still has holders, fire permissions for those holders there too; if deletion is refused while holders exist, add nothing and say so in the SUMMARY. cabana offers no sign out everywhere action: add none, and document that.
|
||||||
|
|
||||||
|
Smoke test modules/cabana/backend_access_revoked_smoke_test.go TestBackendAccessRevokedSmoke (Docker, admin harness): a listener records events; deleting an administrator, deactivating one, an administrator setting another's password, an own password change on PUT /account, a role change, and a role permission change each record one event with the matching reason, the affected id and a non-nil Tx; a listener that returns an error makes the password change answer non-2xx and leaves the stored password hash unchanged. admin:reset-password is covered in plan 05. Docs same commit: cabana README (event, reasons, rollback rule, sign out everywhere not offered), docs/services/events.md (event table), docs/backend/users-and-permissions.md (what ends an administrator's OAuth grants). Stage by path.
|
||||||
|
</action>
|
||||||
|
<verify>
|
||||||
|
<automated>go test -count=1 -run 'TestBackendAccessRevokedSmoke|TestFireSubjectChangedReachesPointerListener|TestFireSubjectChangedWaitsForCommit' ./modules/cabana</automated>
|
||||||
|
<fails_when>non-zero exit, or a line contains FAIL, or `[no tests to run]`, or `--- SKIP: TestBackendAccessRevokedSmoke` appears</fails_when>
|
||||||
|
<automated>go vet ./... && go test -short -count=1 ./... && go test ./cmd/summer -run TestDocsTree -count=1 && go run ./cmd/summer docs:build --check</automated>
|
||||||
|
<fails_when>non-zero exit, or a line contains FAIL, or docs:build prints a problem line</fails_when>
|
||||||
|
</verify>
|
||||||
|
<acceptance_criteria>
|
||||||
|
- `grep -n 'type BackendAccessRevokedEvent struct' modules/cabana/admin_events.go` matches and the six reason constants exist.
|
||||||
|
- `grep -c 'fireBackendAccessRevoked(' modules/cabana/backend_users_admin.go` is at least 4; backend_roles_admin.go, account.go and commands.go each contain at least one call.
|
||||||
|
- The existing fireSubjectChanged calls remain at each site (`grep -c 'fireSubjectChanged(' modules/cabana/backend_users_admin.go` is still 3, as before the task).
|
||||||
|
- TestBackendAccessRevokedSmoke passes, not skipped, including the rolled-back password change.
|
||||||
|
- go vet ./... and go test -short ./... pass for the whole framework module.
|
||||||
|
</acceptance_criteria>
|
||||||
|
<done>Every administrator change D-13 names fires an in-transaction event a plugin can revoke grants on atomically; nothing changes for applications that do not listen.</done>
|
||||||
|
</task>
|
||||||
|
|
||||||
|
</tasks>
|
||||||
|
|
||||||
|
<threat_model>
|
||||||
|
## Trust Boundaries
|
||||||
|
|
||||||
|
| Boundary | Description |
|
||||||
|
|----------|-------------|
|
||||||
|
| MCP client → wristband authorize | Untrusted scope, redirect and request values; this plan only changes where the browser is handed off and the empty-scope default |
|
||||||
|
| Browser (admin SPA) → cabana consent API | Cookie-authenticated, same-origin; decides which scopes an agent gets |
|
||||||
|
| MCP bearer → pier backend guard | A verified grant becomes a backend subject acting as an administrator |
|
||||||
|
| cabana admin saves → plugin listeners | In-transaction event; a listener can veto the save |
|
||||||
|
|
||||||
|
## STRIDE Threat Register
|
||||||
|
|
||||||
|
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|
||||||
|
|-----------|----------|-----------|----------|-------------|-----------------|
|
||||||
|
| T-32.2-01 | Elevation of privilege | pier resolveOAuth backend branch | high | mitigate | Branch only on Subject backend with UserID 0 and BackendUserID non-zero; every other grant takes the unchanged path, which still refuses UserID 0; ScopeLimited true so ScopeLimitFor caps the subject; no link lookup |
|
||||||
|
| T-32.2-02 | Information disclosure | pier session binding | high | mitigate | Binding oauth:backend:<client>:<admin>, never oauth:<client>:0, so two administrators of one client never share a session |
|
||||||
|
| T-32.2-03 | Elevation of privilege | pier linked user-mode grants | medium | mitigate | Scope-limit condition widened only by ScopeLimited, which only the backend branch sets; filter.go untouched; smoke proves the empty-Subject UserID-0 grant is refused |
|
||||||
|
| T-32.2-04 | Tampering (CSRF) | cabana POST /mcp/consent/{request} | high | mitigate | requireAjax (X-Requested-With), SameSite=Strict cookie, interactiveOnly; 16 KiB body cap; unknown fields refused |
|
||||||
|
| T-32.2-05 | Elevation of privilege | consent scope selection | high | mitigate | Granted = submitted ∩ requested ∩ scopeOverlaps(admin) then validateTokenScopes; never trust the provider or the SPA to filter (D-11) |
|
||||||
|
| T-32.2-06 | Spoofing | wristband handoff | medium | mitigate | ConsentPath is appended to the issuer only (same origin); client lookup, exact redirect match and PKCE run before the handoff unchanged |
|
||||||
|
| T-32.2-07 | Elevation of privilege | account item action | high | mitigate | cabana answers 404 for an item id not listed by the administrator's own Items before Run; permissions checked first; Run inside a transaction |
|
||||||
|
| T-32.2-08 | Repudiation / Elevation | D-13 revocation | high | mitigate | BackendAccessRevokedEvent fired in the save's transaction at every site; listener error rolls back; existing after-commit MCPSubjectChanged kept |
|
||||||
|
| T-32.2-SC | Tampering | npm/pip/cargo/go module installs | low | accept | No dependency is added in this plan; the Package Legitimacy Audit lists none |
|
||||||
|
</threat_model>
|
||||||
|
|
||||||
|
<verification>
|
||||||
|
Each task's verify passes on its own commit. After task 4: go vet ./... and go test -short ./... green for the framework module; the four Docker smokes pass; TestDocsTree and docs:build --check pass; `git grep -n -i 'grzyby' -- modules/pact modules/wristband modules/pier modules/cabana docs` is empty.
|
||||||
|
</verification>
|
||||||
|
|
||||||
|
<success_criteria>
|
||||||
|
- SC-1 framework half: configurable handoff and default scopes (D-04), cabana consent endpoint with the token scope policy (D-03, D-09, D-11).
|
||||||
|
- SC-2 framework half: pier backend-only grants with the personal-token scope limit (D-01, D-09); linked grants unchanged.
|
||||||
|
- SC-3 framework half: My account items (D-12) and the in-transaction revocation event at every D-13 site.
|
||||||
|
- SC-5 framework docs in the same commits.
|
||||||
|
</success_criteria>
|
||||||
|
|
||||||
|
<output>
|
||||||
|
Create `.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-01-SUMMARY.md` when done.
|
||||||
|
</output>
|
||||||
|
|
||||||
|
## Artifacts this phase produces
|
||||||
|
|
||||||
|
Plan 01 (framework seams):
|
||||||
|
- pact: MCPGrant.Subject, const MCPGrantSubjectBackend, MCPSubject.ScopeLimited
|
||||||
|
- pact: interface MCPAdminConsent (MCPAdminConsentShow, MCPAdminConsentDecide), structs MCPAdminConsentRequest, MCPAdminConsentDecision, errors ErrMCPConsentNotFound, ErrMCPConsentNoScopes
|
||||||
|
- pact: AccountContribution.Items, AccountContribution.ItemActions, AccountContribution.ItemsEmpty, structs AccountItem, AccountItemAction, AccountItemActionInput, error ErrAccountItemNotFound
|
||||||
|
- wristband: Options.ConsentPath, Options.DefaultScopes
|
||||||
|
- pier: backend-only branch in resolveOAuth (binding format oauth:backend:<client>:<admin>), ScopeLimited in the backend guard condition and in fingerprint
|
||||||
|
- cabana: TokenScopeNames, TokenScopeLabels (new file modules/cabana/token_scopes_export.go)
|
||||||
|
- cabana: routes GET/POST {api}/mcp/consent/{request} (new file modules/cabana/mcp_consent.go), POST {api}/account/contributions/{name}/items/{item}/actions/{action}
|
||||||
|
- cabana: view structs MCPConsentView, MCPConsentClientView, MCPConsentAdminView, MCPConsentDecisionRequest, MCPConsentDecisionView, AccountItemView; AccountContributionView.Items/ItemActions/ItemsEmpty; swag doc funcs AdminMCPConsentShow, AdminMCPConsentDecide, AdminAccountContributionItemAction
|
||||||
|
- cabana: BackendAccessRevokedEvent, BackendAccessDeleted, BackendAccessDeactivated, BackendAccessPasswordChanged, BackendAccessPasswordSet, BackendAccessPasswordReset, BackendAccessPermissions, fireBackendAccessRevoked (new file modules/cabana/admin_events.go)
|
||||||
|
- phrasebook keys: backend::lang.mcp_connect.request_not_found, backend::lang.mcp_connect.no_grantable_scopes
|
||||||
|
- smoke tests: TestConsentPathSmoke, TestBackendSubjectSmoke, TestMCPAdminConsentSmoke, TestAccountItemsSmoke, TestBackendAccessRevokedSmoke
|
||||||
@@ -0,0 +1,303 @@
|
|||||||
|
---
|
||||||
|
phase: 32.2
|
||||||
|
plan: 02
|
||||||
|
type: execute
|
||||||
|
wave: 2
|
||||||
|
depends_on: [32.2-01]
|
||||||
|
files_modified:
|
||||||
|
- admin/openapi/admin.json
|
||||||
|
- admin/src/api/schema.d.ts
|
||||||
|
- admin/src/api/types.ts
|
||||||
|
- admin/src/views/ConnectView.vue
|
||||||
|
- admin/src/app/router.ts
|
||||||
|
- admin/src/app/pageTitle.ts
|
||||||
|
- admin/src/views/LoginView.vue
|
||||||
|
- admin/src/components/account/AccountContributions.vue
|
||||||
|
- admin/tests/smoke/connect.smoke.test.ts
|
||||||
|
- admin/tests/smoke/account-items.smoke.test.ts
|
||||||
|
- modules/phrasebook/backend/lang/en/lang.yaml
|
||||||
|
- modules/phrasebook/backend/lang/pl/lang.yaml
|
||||||
|
- modules/cabana/admin_openapi.go
|
||||||
|
- docs/backend/admin-spa.md
|
||||||
|
- modules/boardwalk/dist
|
||||||
|
autonomous: true
|
||||||
|
requirements: [SC-1, SC-3, SC-5]
|
||||||
|
estimate:
|
||||||
|
tokens: 85000
|
||||||
|
raw_tokens: 85000
|
||||||
|
tasks: 3
|
||||||
|
confidence: low
|
||||||
|
must_haves:
|
||||||
|
truths:
|
||||||
|
- "SC-1, D-03: the admin SPA has a route { path: '/connect', name: 'connect', component: ConnectView } with no meta.shell and no meta.public, so an anonymous visitor of /<admin prefix>/connect?request=<id> is sent to login with redirect=/connect?request=<id> and comes back after any 2FA or Turnstile step; safeRedirect is unchanged."
|
||||||
|
- "SC-1, D-05: ConnectView is a standalone full-screen card copied from LoginView (navy gradient, wordmark, white card, light-literal palette, no sidebar or top bar) showing the client mark, the heading with the client name, the subline, a fact box with 'Signed in as' and 'Returns to' (the redirect host, always shown), the scope checkboxes, the Stay connected row, and Deny (left) and Allow (right)."
|
||||||
|
- "D-06: 'Use another account' calls logout() without the router argument, then router.replace({ name: 'login', query: { redirect: route.fullPath } }); it is disabled while a decision is in flight; a sign-out failure shows the inline alert (decide_failed copy), keeps the card and re-enables the button."
|
||||||
|
- "D-09, D-11: the scope rows are exactly the scopes GET /mcp/consent/{request} returned, in catalog order (*, admin:read, plugin scopes); the SPA never re-adds a hidden scope. Every shown scope starts ticked except *, which starts unticked unless it is the only scope; ticking * clears and disables the others and shows the scope_all_includes note; the submitted scopes are ['*'] when * is ticked, else the ticked names in catalog order. Read-only scopes carry the Read-only pill."
|
||||||
|
- "D-10: the Stay connected checkbox is shown only when offline_access was requested, is ticked by default and posts offline_access true|false; when offline_access was not requested the row is not rendered and offline_access false is posted."
|
||||||
|
- "No auto-allow: nothing is posted on mount even when consent_required is false (the previously allowed note is shown instead); Allow and Deny POST {decision, scopes, offline_access} and, on 200, switch to the Returning state and call window.location.assign(redirect_uri), never the router and never safeRedirect; a redirect_uri whose scheme is javascript:, data: or vbscript: is treated as a submit failure with no navigation; no native form POST (admin CSP form-action 'self')."
|
||||||
|
- "UI loading — consent card: the Loading state is a skeleton card with aria-busy=true and no buttons, so nothing can be submitted before the request is known."
|
||||||
|
- "UI loading — decision in flight: a disabled fieldset wraps the checkboxes, both buttons are disabled, the clicked button shows LoaderCircle (Allow shows mcp_connect.allowing), then the Returning state stays until the browser leaves."
|
||||||
|
- "UI loading — My account items arrive with the existing GET /account/contributions; nothing renders until it answers, so there is no item-level loading UI."
|
||||||
|
- "UI empty — no grantable scope (D-11): when the API returns zero scopes, the none_grantable alert replaces the scope group, no offline row is shown, and only Deny is offered, full width."
|
||||||
|
- "UI empty — request missing: a missing or empty ?request goes straight to the Expired state without a network call."
|
||||||
|
- "UI empty — nothing ticked: Allow is disabled while the submitted scope set would be empty; Deny stays available."
|
||||||
|
- "UI empty — My account items: a section whose items array is empty renders the dashed empty block (data-account-items-empty) with ItemsEmpty, or myaccount.items_empty when ItemsEmpty is unset; the status line stays above it."
|
||||||
|
- "UI error — consent load 5xx or network: the Load error state shows load_failed in the alert block and a full-width Try again button that re-runs the load."
|
||||||
|
- "UI error — 404 on load or submit: the Expired state (Clock icon, expired_heading, expired_body, a RouterLink to / with open_admin)."
|
||||||
|
- "UI error — 401 at any point: expireSession sends the browser to login with redirect = the current /connect?request=… path; no copy on the card."
|
||||||
|
- "UI error — submit 422 shows api_tokens.scopes_required under the scopes; 5xx, network or 400 shows decide_failed above the buttons; in both the ticks are kept and both buttons are enabled again."
|
||||||
|
- "UI error — forbidden redirect scheme: treated as a submit failure (decide_failed); no navigation."
|
||||||
|
- "UI error — My account item revoke: 404 shows myaccount.item_gone as a danger toast and reloads; 409 shows myaccount.action_stale and reloads; 403 shows the server message or list.action_forbidden; other failures show extension.action_failed."
|
||||||
|
- "UI error — a section whose items func failed renders the existing section_error line in place of both the list and the empty block."
|
||||||
|
- "UI populated — consent scopes follow catalog order with the initial ticks and Read-only pill above, and the offline row is ticked when requested."
|
||||||
|
- "UI populated — My account items: one role=listitem row per item (data-account-item=<id>) with title, subtitle, meta joined with ' · ' (tabular-nums) and one Button size=sm per item action (variant danger with the Ban icon when Danger, else outline), aria-label myaccount.item_action_named with the item title."
|
||||||
|
- "UI partial — no logo shows the Bot icon in a 48px circle (a logo is shown only for a same-origin path or an https: URL); no email shows the name alone; no name shows the login; when the API omits admin the card falls back to currentUser."
|
||||||
|
- "UI zero-one-many — My account items: zero renders the empty block, one or many render the same row list with dividers (first:border-t-0), no pagination."
|
||||||
|
- "UI overflow — the consent card grows with the page and the page scrolls (min-h-screen main, not fixed height); rows wrap and nothing scrolls inside the card."
|
||||||
|
- "UI long-text — client name, admin email, redirect host, scope descriptions and item titles/subtitles/meta use [overflow-wrap:anywhere]; nothing on the consent card truncates; My account rows stack under max-sm:flex-col."
|
||||||
|
- "UI loading/error — the consent scope list never renders on its own; it inherits the card's Loading, Load error and Expired states."
|
||||||
|
- "SC-3, D-12: AccountContributions.vue renders items additively: a section JSON without items (null) renders exactly as today (status line and buttons); an item action with Confirm or Danger runs through confirm.ask({ message with :title filled from the item Title, confirmLabel, danger }, run) using the confirm AccountView passes in; while one runs every action button is disabled; after a 2xx the section reloads and focus returns to the section heading (tabindex=-1)."
|
||||||
|
- "C2: LoginView shows one Meta line mcp_connect.login_hint under its heading only when safeRedirect(route.query.redirect) resolves to pathname /connect; nothing else in LoginView changes."
|
||||||
|
- "SC-5: admin/openapi/admin.json and admin/src/api/schema.d.ts are regenerated by scripts/check-admin-openapi.sh and pass --check; modules/boardwalk/dist is rebuilt and committed and scripts/check-admin-dist.sh passes; docs/backend/admin-spa.md documents the /connect route and account items; framework copy never names a consuming application."
|
||||||
|
artifacts:
|
||||||
|
- path: admin/src/views/ConnectView.vue
|
||||||
|
provides: "Standalone consent card with every state of UI-SPEC C1"
|
||||||
|
contains: "window.location.assign"
|
||||||
|
- path: admin/src/app/router.ts
|
||||||
|
provides: "connect route without shell and without public"
|
||||||
|
contains: "name: 'connect'"
|
||||||
|
- path: admin/src/components/account/AccountContributions.vue
|
||||||
|
provides: "item rows, empty block and item actions"
|
||||||
|
contains: "data-account-item"
|
||||||
|
- path: admin/src/api/schema.d.ts
|
||||||
|
provides: "typed /mcp/consent/{request} and item action routes"
|
||||||
|
contains: "/mcp/consent/{request}"
|
||||||
|
- path: modules/boardwalk/dist
|
||||||
|
provides: "rebuilt embedded SPA"
|
||||||
|
key_links:
|
||||||
|
- from: admin/src/views/ConnectView.vue
|
||||||
|
to: "cabana GET/POST /mcp/consent/{request} (plan 01)"
|
||||||
|
via: "api client (openapi-fetch) typed by schema.d.ts"
|
||||||
|
pattern: "/mcp/consent/\\{request\\}"
|
||||||
|
- from: admin/src/views/LoginView.vue
|
||||||
|
to: admin/src/app/router.ts safeRedirect
|
||||||
|
via: "login round trip back to /connect?request="
|
||||||
|
pattern: "safeRedirect"
|
||||||
|
- from: admin/src/components/account/AccountContributions.vue
|
||||||
|
to: "cabana POST /account/contributions/{name}/items/{item}/actions/{action}"
|
||||||
|
via: "api client"
|
||||||
|
pattern: "/items/"
|
||||||
|
---
|
||||||
|
|
||||||
|
<objective>
|
||||||
|
User story (phase goal, ROADMAP 32.2): **As an** editor of a blog-only application whose MCP tools are backend-guarded (Journal) and which has no frontend users, **I want to** add the site's `/mcp` as a connector and sign in once as my administrator account over OAuth, **so that** agents no longer need a hand-copied `g15_` personal token.
|
||||||
|
|
||||||
|
Slice in this plan (the "sign in once as my administrator" step): an administrator who opens `/<admin prefix>/connect?request=…` goes through the normal admin login if needed, sees the consent card, ticks scopes and clicks Allow, and the browser leaves for the client's redirect. The tracer proves this against plan 01's JSON contract (connect.smoke.test.ts, router.test.ts). The provider behind that contract is plan 03, and the run against a live stack is plan 04.
|
||||||
|
|
||||||
|
The admin SPA half of SC-1 and SC-3 (D-03, D-05, D-06, D-09, D-10, D-11, D-12): a consent route inside the admin SPA that an anonymous browser reaches through the normal admin login, and per-item rows with actions in My account contributions. All copy, layout and states follow 32.2-UI-SPEC.md (C1, C2, C3).
|
||||||
|
|
||||||
|
Purpose: the admin cookie is Path=<admin prefix> and SameSite=Strict, so only same-origin SPA fetches carry it; the consent screen must be framework code against plan 01's JSON contract, because the SPA cannot load plugin Vue code.
|
||||||
|
Output: ConnectView, the route, the login hint, item rendering, regenerated openapi and types, the rebuilt committed boardwalk dist, and docs. Smoke tests only; ConnectView.test.ts and the extended unit tests are plan 05.
|
||||||
|
|
||||||
|
⚠ spec-less probe fallback skipped: phase has no requirement IDs to probe (visible skip).
|
||||||
|
|
||||||
|
Discretion recorded (UI-SPEC already decided): plain checkboxes with the token-dialog `*` rule, no presets; the scope-picker logic is copied into ConnectView rather than extracted, so ApiTokenCreateDialog.vue is not touched. UI-SPEC "UI Considerations" rows marked covered are must_haves truths here (admin-wide list rows are in plan 03); the five backstop rows are in plan 05; the dismissed login-hint overflow row needs nothing.
|
||||||
|
</objective>
|
||||||
|
|
||||||
|
<execution_context>
|
||||||
|
@~/.claude/msd-core/workflows/execute-plan.md
|
||||||
|
@~/.claude/msd-core/templates/summary.md
|
||||||
|
</execution_context>
|
||||||
|
|
||||||
|
<context>
|
||||||
|
@.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-CONTEXT.md
|
||||||
|
@.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-UI-SPEC.md
|
||||||
|
@.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-RESEARCH.md
|
||||||
|
@.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-01-SUMMARY.md
|
||||||
|
@admin/src/views/LoginView.vue
|
||||||
|
@admin/src/app/router.ts
|
||||||
|
@admin/src/components/account/AccountContributions.vue
|
||||||
|
@admin/src/components/account/ApiTokenCreateDialog.vue
|
||||||
|
@admin/src/components/account/ApiTokensPanel.vue
|
||||||
|
@admin/src/state/useAuth.ts
|
||||||
|
@admin/src/api/types.ts
|
||||||
|
@scripts/check-admin-openapi.sh
|
||||||
|
@scripts/check-admin-dist.sh
|
||||||
|
|
||||||
|
<interfaces>
|
||||||
|
From plan 01 (cabana, admin API base {prefix}/api/v1; check 32.2-01-SUMMARY.md for any rename):
|
||||||
|
- GET /mcp/consent/{request} → 200 data MCPConsentView{request_id, client{id, name, redirect_host, logo_url}, admin{login, name, email}, scopes[AdminAPITokenScope{name, label, description, read_only, known}], offline_access, consent_required, expires_at}; 401; 403 interactive_only; 404 request_not_found
|
||||||
|
- POST /mcp/consent/{request} body MCPConsentDecisionRequest{decision 'allow'|'deny', scopes[], offline_access} with X-Requested-With → 200 data MCPConsentDecisionView{redirect_uri}; 400; 404; 422 no_grantable_scopes
|
||||||
|
- GET /account/contributions → AccountContributionView gains items (AccountItemView{id, title, subtitle, meta[]} array, or null when the section has none), item_actions (AccountContributionActionView[]), items_empty (string)
|
||||||
|
- POST /account/contributions/{name}/items/{item}/actions/{action} → 200 AccountActionResultView{message, url}; 403; 404; 409; 422
|
||||||
|
Existing SPA:
|
||||||
|
- router.ts: safeRedirect(value) accepts a single-leading-slash path; beforeEach sends an anonymous visitor to { name: 'login', query: { redirect: to.fullPath } }; '/login' route has meta.public, '/account' has meta.shell
|
||||||
|
- useAuth.ts: currentUser (readonly), expireSession(router), logout(router?) — call logout() with no router argument for the switch
|
||||||
|
- types.ts: aliases like AccountContribution = Schemas['cabana.AccountContributionView']
|
||||||
|
- LoginView.vue line 34: router.replace(safeRedirect(route.query.redirect) ?? '/')
|
||||||
|
</interfaces>
|
||||||
|
</context>
|
||||||
|
|
||||||
|
<tasks>
|
||||||
|
|
||||||
|
<task type="tracer">
|
||||||
|
<name>Tracer: a signed-in administrator opens /connect?request=…, ticks scopes and Allow sends the browser to the client's redirect</name>
|
||||||
|
<reversibility rating="reversible">An SPA route and a view behind the plan 01 contract; replaceable without touching the API.</reversibility>
|
||||||
|
<precondition>32.2-01-SUMMARY.md exists and `grep -n '@Router /mcp/consent/{request} \[get\]' modules/cabana/admin_openapi.go` matches; admin/node_modules exists or `npm --prefix admin ci` succeeds.</precondition>
|
||||||
|
<files>admin/openapi/admin.json, admin/src/api/schema.d.ts, admin/src/api/types.ts, admin/src/views/ConnectView.vue, admin/src/app/router.ts, admin/src/app/pageTitle.ts, modules/phrasebook/backend/lang/en/lang.yaml, modules/phrasebook/backend/lang/pl/lang.yaml, admin/tests/smoke/connect.smoke.test.ts, modules/cabana/admin_openapi.go</files>
|
||||||
|
<read_first>
|
||||||
|
admin/src/views/LoginView.vue (whole file: shell markup, busy/failed refs, double-submit guard, alert block classes)
|
||||||
|
admin/src/components/account/ApiTokenCreateDialog.vue (scope rows, toggleScope, scopeDisabled, starChecked at lines 64 and 149-177, skeleton rows)
|
||||||
|
admin/src/app/router.ts (routes at lines 60-80, beforeEach at line 92, safeRedirect at line 31)
|
||||||
|
admin/src/app/pageTitle.ts (login and account branches)
|
||||||
|
admin/src/api/client.ts and admin/src/api/types.ts (openapi-fetch usage and schema aliases)
|
||||||
|
admin/tests/smoke/tracer.smoke.test.ts (smoke test harness and fetch mocking to copy)
|
||||||
|
scripts/check-admin-openapi.sh
|
||||||
|
modules/phrasebook/backend/lang/en/lang.yaml (api_tokens and myaccount groups for reused keys)
|
||||||
|
.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-UI-SPEC.md (Copywriting Contract, C1 Layout, Ready state, Interaction)
|
||||||
|
</read_first>
|
||||||
|
<action>
|
||||||
|
First run scripts/check-admin-openapi.sh (no argument) so admin/openapi/admin.json and admin/src/api/schema.d.ts include plan 01's /mcp/consent/{request} routes, the account item action route and the new view fields. If swag refuses one of plan 01's annotations, fix only that annotation in modules/cabana/admin_openapi.go and note it in the SUMMARY. Add aliases in admin/src/api/types.ts: MCPConsent = Schemas['cabana.MCPConsentView'], MCPConsentDecision = Schemas['cabana.MCPConsentDecisionView'], AccountItem = Schemas['cabana.AccountItemView'].
|
||||||
|
|
||||||
|
Route (D-03): add { path: '/connect', name: 'connect', component: ConnectView } to router.ts next to the other fixed paths, before the /:vendor/:plugin/:controller entries, with no meta.shell and no meta.public; do not change safeRedirect or beforeEach. pageTitle.ts: a connect branch returning t('backend::lang.mcp_connect.page_title').
|
||||||
|
|
||||||
|
ConnectView.vue (D-05, D-09, D-10, D-11), new, script setup lang ts, copying LoginView's main, wordmark and card markup verbatim and using only light-literal hex classes inside the card (no Button.vue, no token utilities, no dark: variants), per UI-SPEC Color. This task builds the Ready state only: on mount and when route.query.request changes, GET /mcp/consent/{request}; render the client mark (logo only for a same-origin path or an https: URL, else the Bot icon circle), h1 mcp_connect.heading with :client, the subline, the fact box (signed_in_as with admin_with_email, returns_to with redirect_host in font-mono), the scope group (role=group labelled by api_tokens.scopes) with the copied row markup, the initial ticks and the * rule from the UI-SPEC, the offline row when offline_access was requested (ticked by default, D-10), and Deny then Allow. Allow is disabled while no scope is ticked or while busy. Allow POSTs {decision: 'allow', scopes, offline_access}; Deny POSTs {decision: 'deny'}; on 200 call window.location.assign(redirect_uri) after refusing javascript:, data: and vbscript: schemes. The redirect URI never goes through the router or the login-redirect sanitizer (it is absolute and server-issued); never use a native form submit. No auto-allow on mount, no initial focus on Allow or Deny, no Allow hotkey. All copy through t(); no literal UI strings.
|
||||||
|
|
||||||
|
Phrasebook: add the whole backend::lang.mcp_connect group of the UI-SPEC Copywriting Contract to en and pl (page_title, heading, subline, signed_in_as, admin_with_email, switch_account, returns_to, offline, offline_description, previously_allowed, allow, allowing, deny, returning, continue, login_hint, none_grantable, expired_heading, expired_body, open_admin, load_failed, retry, decide_failed), keeping plan 01's request_not_found and no_grantable_scopes. Reuse api_tokens.scopes, scope_all_includes, read_only and scopes_required; do not duplicate them.
|
||||||
|
|
||||||
|
Smoke test admin/tests/smoke/connect.smoke.test.ts: mount the router at /connect?request=req1 signed in, mock GET to answer two scopes and offline_access true; the card shows both scopes ticked and Stay connected ticked; clicking Allow POSTs scopes and offline_access true and calls a stubbed window.location.assign with the mocked redirect_uri, and the router's push and replace are not called with that URI. Commit source and test (not the dist) by path; do not git add -A.
|
||||||
|
</action>
|
||||||
|
<verify>
|
||||||
|
<automated>npm --prefix admin run typecheck && npm --prefix admin run test -- tests/smoke/connect.smoke.test.ts tests/app/router.test.ts tests/app/pageTitle.test.ts tests/app/i18n.test.ts</automated>
|
||||||
|
<fails_when>non-zero exit, or the vitest summary shows a failed test, or `No test files found`, or connect.smoke.test.ts is absent from the run output</fails_when>
|
||||||
|
<automated>scripts/check-admin-openapi.sh --check && go test -count=1 -run 'TestPhase09ContractInventory|TestPhase10OpenAPIConformance' ./modules/cabana</automated>
|
||||||
|
<fails_when>non-zero exit, or check-admin-openapi reports a differing file, or a line contains FAIL, or `[no tests to run]`</fails_when>
|
||||||
|
</verify>
|
||||||
|
<acceptance_criteria>
|
||||||
|
- `grep -n "name: 'connect'" admin/src/app/router.ts` matches and that route object has neither `shell` nor `public` in its meta.
|
||||||
|
- `grep -n '/mcp/consent/{request}' admin/src/api/schema.d.ts` matches.
|
||||||
|
- ConnectView.vue contains `window.location.assign`; connect.smoke.test.ts asserts the router's push and replace were not called with the redirect_uri.
|
||||||
|
- Both phrasebook files contain `mcp_connect:` with page_title, heading, allow and deny.
|
||||||
|
- connect.smoke.test.ts passes and asserts window.location.assign was called with the mocked redirect_uri.
|
||||||
|
- check-admin-openapi.sh --check exits 0.
|
||||||
|
</acceptance_criteria>
|
||||||
|
<done>An administrator can finish a consent from the SPA and the browser leaves for the client redirect; the API contract is typed.</done>
|
||||||
|
</task>
|
||||||
|
|
||||||
|
<task type="auto">
|
||||||
|
<name>Every consent state, the account switch and the login hint</name>
|
||||||
|
<reversibility rating="reversible">View states and copy; no contract change.</reversibility>
|
||||||
|
<files>admin/src/views/ConnectView.vue, admin/src/views/LoginView.vue, admin/tests/smoke/connect.smoke.test.ts</files>
|
||||||
|
<read_first>
|
||||||
|
admin/src/views/ConnectView.vue (from task 1)
|
||||||
|
admin/src/views/LoginView.vue
|
||||||
|
admin/src/state/useAuth.ts (logout without router, expireSession, currentUser)
|
||||||
|
.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-UI-SPEC.md (C1 Other states, Interaction, C2, UI Considerations)
|
||||||
|
</read_first>
|
||||||
|
<action>
|
||||||
|
In ConnectView add the UI-SPEC C1 states: Loading (aria-busy true, sr-only h1 with page_title, the 48px skeleton circle, two skeleton bars and three skeleton scope rows, no buttons); Expired (404 on load or submit, or a missing/empty request; no network call in the missing case; Clock icon circle, expired_heading, expired_body, RouterLink to / with open_admin styled like Deny); Load error (5xx or network; page_title h1, alert block with load_failed, full-width Try again that reloads); No grantable scope (zero scopes: client mark, h1, subline and fact box, the none_grantable alert instead of the scope group, no offline row, only Deny, full width); Returning (client mark, h1 returning with :host, an inline LoaderCircle, and for http: or https: URIs a continue link with href = the URI). Inline alerts: 422 shows api_tokens.scopes_required under the scopes; 5xx, network or 400 shows decide_failed above the buttons; ticks kept and buttons re-enabled. 401 anywhere calls expireSession(router) so the browser returns to login with redirect = route.fullPath. Busy treatment: a disabled fieldset around the checkboxes, both buttons disabled, a spinner on the clicked one (Allow label becomes mcp_connect.allowing). Previously allowed note under the subline when consent_required is false (no auto-allow). After every state change past the first render, focus the state's h1 (or the alert block for inline errors). Admin value: admin.name with (email) when both present, the name alone without email, the login when the name is empty; when the API omits admin, fall back to currentUser.
|
||||||
|
|
||||||
|
Use another account (D-06): a type=button text button under the signed-in value; await logout() with no router argument, then router.replace({ name: 'login', query: { redirect: route.fullPath } }); disabled while a decision is in flight; when logout throws, show the decide_failed inline alert, keep the card and re-enable the button.
|
||||||
|
|
||||||
|
LoginView (C2): when safeRedirect(route.query.redirect) resolves to a path whose pathname is /connect, render one Meta line with mcp_connect.login_hint under the h1. Nothing else in LoginView changes; 2FA, Turnstile and redirect behaviour stay as they are (D-03).
|
||||||
|
|
||||||
|
Extend admin/tests/smoke/connect.smoke.test.ts with two smoke cases: a 404 on load renders expired_heading; Use another account calls POST /auth/logout and replaces to login with the redirect query. Commit by path.
|
||||||
|
</action>
|
||||||
|
<verify>
|
||||||
|
<automated>npm --prefix admin run typecheck && npm --prefix admin run test -- tests/smoke/connect.smoke.test.ts tests/views/LoginView.test.ts</automated>
|
||||||
|
<fails_when>non-zero exit, or the vitest summary shows a failed test, or `No test files found`</fails_when>
|
||||||
|
</verify>
|
||||||
|
<acceptance_criteria>
|
||||||
|
- ConnectView.vue contains `aria-busy`, `expired_heading`, `load_failed`, `none_grantable`, `returning` and `switch_account` keys.
|
||||||
|
- `grep -n 'logout()' admin/src/views/ConnectView.vue` matches (no router argument passed to logout).
|
||||||
|
- LoginView.vue references `mcp_connect.login_hint` and the existing LoginView.test.ts still passes.
|
||||||
|
- The extended smoke cases pass.
|
||||||
|
</acceptance_criteria>
|
||||||
|
<done>The consent card handles loading, expiry, failures, no-grantable-scope, returning and account switching as the UI-SPEC defines, and the login screen says why the administrator is signing in.</done>
|
||||||
|
</task>
|
||||||
|
|
||||||
|
<task type="auto">
|
||||||
|
<name>Account contribution items, docs and the rebuilt embedded dist</name>
|
||||||
|
<reversibility rating="reversible">Additive rendering of a field older sections never send; the dist is regenerated output.</reversibility>
|
||||||
|
<files>admin/src/components/account/AccountContributions.vue, admin/tests/smoke/account-items.smoke.test.ts, modules/phrasebook/backend/lang/en/lang.yaml, modules/phrasebook/backend/lang/pl/lang.yaml, docs/backend/admin-spa.md, modules/boardwalk/dist</files>
|
||||||
|
<read_first>
|
||||||
|
admin/src/components/account/AccountContributions.vue (whole file: sections, actions, running guard, confirm usage)
|
||||||
|
admin/src/components/account/ApiTokensPanel.vue (list container and row classes)
|
||||||
|
admin/src/views/AccountView.vue (the confirm it passes down)
|
||||||
|
admin/tests/account/AccountContributions.test.ts (existing behaviour that must keep passing)
|
||||||
|
docs/backend/admin-spa.md
|
||||||
|
scripts/check-admin-dist.sh
|
||||||
|
.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-UI-SPEC.md (C3)
|
||||||
|
</read_first>
|
||||||
|
<action>
|
||||||
|
AccountContributions.vue (D-12, UI-SPEC C3), inside each section card after the status line and before the section buttons: when the section's items is null or absent render nothing new (the section looks exactly as today). When items is an array with entries, render a role=list container with the ApiTokensPanel row classes and one role=listitem row per item with data-account-item set to the item id: title, subtitle (omitted when empty), meta joined with ' · ' in tabular-nums (omitted when empty), and one Button size=sm per item_actions entry with data-account-item-action set to its name, variant danger plus the Ban icon when danger, else outline, aria-label t('backend::lang.myaccount.item_action_named', { action, title }). When items is an empty array render the dashed empty block (data-account-items-empty) with items_empty or myaccount.items_empty. A section with error true keeps the existing section_error line in place of both. Running an item action: Confirm or Danger → confirm.ask({ message: the confirm text with :title replaced by the item title as text, confirmLabel: action label, danger }, run); otherwise run directly. run POSTs /account/contributions/{name}/items/{encodeURIComponent(item)}/actions/{action}. The existing running guard disables every action button. 2xx: toast the answer message or form.action_done, then reload. 404: danger toast myaccount.item_gone, then reload. 409, 403 and other failures: exactly as section actions today. After a reload that follows an item action, focus the section heading (give it tabindex=-1).
|
||||||
|
|
||||||
|
Phrasebook en and pl: add myaccount.items_empty, myaccount.item_gone and myaccount.item_action_named with the UI-SPEC copy.
|
||||||
|
|
||||||
|
Smoke test admin/tests/smoke/account-items.smoke.test.ts: a section without items renders no list and no empty block; a section with items [] renders the empty block; a Danger item action asks the confirm with :title replaced and POSTs the item route.
|
||||||
|
|
||||||
|
docs/backend/admin-spa.md: document the /connect consent route (standalone, reached through the login redirect, framework screen over the cabana consent API) and the My account item rows and actions. Never name a consuming application.
|
||||||
|
|
||||||
|
Last: npm --prefix admin run build, then commit modules/boardwalk/dist as its own commit (stage modules/boardwalk/dist by path), after committing the component, test, phrasebook and docs changes by path. Do not git add -A.
|
||||||
|
</action>
|
||||||
|
<verify>
|
||||||
|
<automated>npm --prefix admin run typecheck && npm --prefix admin run test && npm --prefix admin run test:browser</automated>
|
||||||
|
<fails_when>non-zero exit, or the vitest summary shows a failed test, or `No test files found`</fails_when>
|
||||||
|
<automated>scripts/check-admin-dist.sh && scripts/check-admin-openapi.sh --check && go test ./cmd/summer -run TestDocsTree -count=1 && go run ./cmd/summer docs:build --check && go test -short -count=1 ./modules/boardwalk ./modules/phrasebook ./modules/cabana</automated>
|
||||||
|
<fails_when>non-zero exit, or check-admin-dist prints `modules/boardwalk/dist is stale`, or a line contains FAIL, or docs:build prints a problem line</fails_when>
|
||||||
|
</verify>
|
||||||
|
<acceptance_criteria>
|
||||||
|
- AccountContributions.vue contains `data-account-item`, `data-account-items-empty` and `data-account-item-action`.
|
||||||
|
- The whole admin vitest suite passes, including the unchanged tests/account/AccountContributions.test.ts.
|
||||||
|
- check-admin-dist.sh exits 0 after the dist commit; `git status --porcelain -- modules/boardwalk/dist` is empty.
|
||||||
|
- docs/backend/admin-spa.md mentions the /connect route; `git grep -n -i 'grzyby' -- admin/src docs/backend/admin-spa.md modules/phrasebook` prints nothing.
|
||||||
|
</acceptance_criteria>
|
||||||
|
<done>My account shows plugin-supplied rows with per-row actions, and the embedded admin the Go binary serves includes the consent route.</done>
|
||||||
|
</task>
|
||||||
|
|
||||||
|
</tasks>
|
||||||
|
|
||||||
|
<threat_model>
|
||||||
|
## Trust Boundaries
|
||||||
|
|
||||||
|
| Boundary | Description |
|
||||||
|
|----------|-------------|
|
||||||
|
| Server-issued redirect_uri → browser navigation | The SPA navigates cross-origin to a URI wristband validated against the client's registered list |
|
||||||
|
| Server data → DOM | Client name, admin name/email, scope labels and item titles are untrusted text |
|
||||||
|
|
||||||
|
## STRIDE Threat Register
|
||||||
|
|
||||||
|
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|
||||||
|
|-----------|----------|-----------|----------|-------------|-----------------|
|
||||||
|
| T-32.2-09 | Spoofing (open redirect) | ConnectView navigation | high | mitigate | Navigate only to the redirect_uri of a 200 decision answer; refuse javascript:, data:, vbscript:; never accept a URI from the query string; the login round trip uses the unchanged safeRedirect |
|
||||||
|
| T-32.2-10 | Spoofing (phishing) | ConnectView fact box | medium | mitigate | Returns to (redirect host) is always shown and never truncated, as the MCP spec requires; client logo only from a same-origin path or https |
|
||||||
|
| T-32.2-11 | Tampering (XSS) | ConnectView, AccountContributions | high | mitigate | Every server string renders as text through Vue interpolation; no v-html; :title is substituted as text |
|
||||||
|
| T-32.2-12 | Elevation of privilege (click-through consent) | ConnectView | medium | mitigate | No auto-allow, no initial focus on Allow, no Allow hotkey; `*` is never pre-ticked unless it is the only scope |
|
||||||
|
| T-32.2-SC | Tampering | npm installs | low | accept | No new npm dependency; npm ci installs the committed lockfile |
|
||||||
|
</threat_model>
|
||||||
|
|
||||||
|
<verification>
|
||||||
|
Typecheck, the whole vitest suite and the browser suite pass; check-admin-openapi.sh --check and check-admin-dist.sh pass; docs:build --check passes; go test -short passes for boardwalk, phrasebook and cabana.
|
||||||
|
</verification>
|
||||||
|
|
||||||
|
<success_criteria>
|
||||||
|
- SC-1 SPA half: the consent card under the admin prefix, reached through the unchanged login (D-03, D-05, D-06, D-09, D-10, D-11).
|
||||||
|
- SC-3 SPA half: My account rows with Revoke-style item actions (D-12).
|
||||||
|
- SC-5: regenerated typed contract, rebuilt committed dist, admin-spa docs.
|
||||||
|
</success_criteria>
|
||||||
|
|
||||||
|
<output>
|
||||||
|
Create `.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-02-SUMMARY.md` when done.
|
||||||
|
</output>
|
||||||
|
|
||||||
|
## Artifacts this phase produces
|
||||||
|
|
||||||
|
Plan 02 (admin SPA):
|
||||||
|
- New file admin/src/views/ConnectView.vue (states: loading, ready, expired, load error, no grantable scope, returning)
|
||||||
|
- Route { path: '/connect', name: 'connect' } in admin/src/app/router.ts; connect branch in admin/src/app/pageTitle.ts
|
||||||
|
- Type aliases MCPConsent, MCPConsentDecision, AccountItem in admin/src/api/types.ts
|
||||||
|
- LoginView login hint (mcp_connect.login_hint)
|
||||||
|
- AccountContributions.vue item rows: data-account-item, data-account-item-action, data-account-items-empty
|
||||||
|
- Phrasebook keys: backend::lang.mcp_connect.* (page_title, heading, subline, signed_in_as, admin_with_email, switch_account, returns_to, offline, offline_description, previously_allowed, allow, allowing, deny, returning, continue, login_hint, none_grantable, expired_heading, expired_body, open_admin, load_failed, retry, decide_failed), backend::lang.myaccount.items_empty, item_gone, item_action_named
|
||||||
|
- Regenerated admin/openapi/admin.json and admin/src/api/schema.d.ts; rebuilt modules/boardwalk/dist
|
||||||
|
- Smoke tests: admin/tests/smoke/connect.smoke.test.ts, admin/tests/smoke/account-items.smoke.test.ts
|
||||||
@@ -0,0 +1,364 @@
|
|||||||
|
---
|
||||||
|
phase: 32.2
|
||||||
|
plan: 03
|
||||||
|
type: execute
|
||||||
|
wave: 2
|
||||||
|
depends_on: [32.2-01]
|
||||||
|
files_modified:
|
||||||
|
- ../sm-oauthserver-plugin/config/config.yaml
|
||||||
|
- ../sm-oauthserver-plugin/servers.go
|
||||||
|
- ../sm-oauthserver-plugin/routes.go
|
||||||
|
- ../sm-oauthserver-plugin/plugin.go
|
||||||
|
- ../sm-oauthserver-plugin/updates/202611200001_add_golem15_oauthserver_backend_subjects.go
|
||||||
|
- ../sm-oauthserver-plugin/models/consent.go
|
||||||
|
- ../sm-oauthserver-plugin/models/mcp_connection.go
|
||||||
|
- ../sm-oauthserver-plugin/models/mcpconnection/columns.yaml
|
||||||
|
- ../sm-oauthserver-plugin/classes/mcp_backend_subject.go
|
||||||
|
- ../sm-oauthserver-plugin/classes/mcp_store.go
|
||||||
|
- ../sm-oauthserver-plugin/classes/mcp_verifier.go
|
||||||
|
- ../sm-oauthserver-plugin/classes/backend_cascade.go
|
||||||
|
- ../sm-oauthserver-plugin/controllers/mcp_admin_consent.go
|
||||||
|
- ../sm-oauthserver-plugin/controllers/mcp_connections.go
|
||||||
|
- ../sm-oauthserver-plugin/controllers/mcpconnections/config_list.yaml
|
||||||
|
- ../sm-oauthserver-plugin/controllers/admin_registry.go
|
||||||
|
- ../sm-oauthserver-plugin/account.go
|
||||||
|
- ../sm-oauthserver-plugin/admin.go
|
||||||
|
- ../sm-oauthserver-plugin/admin_permissions.go
|
||||||
|
- ../sm-oauthserver-plugin/admin_navigation.go
|
||||||
|
- ../sm-oauthserver-plugin/lang/en/lang.yaml
|
||||||
|
- ../sm-oauthserver-plugin/lang/pl/lang.yaml
|
||||||
|
- ../sm-oauthserver-plugin/harness_test.go
|
||||||
|
- ../sm-oauthserver-plugin/backend_mode_smoke_test.go
|
||||||
|
- ../sm-oauthserver-plugin/backend_revocation_smoke_test.go
|
||||||
|
- ../sm-oauthserver-plugin/backend_account_smoke_test.go
|
||||||
|
- ../sm-oauthserver-plugin/README.md
|
||||||
|
- ../sm-oauthserver-plugin/plugin.yaml
|
||||||
|
autonomous: true
|
||||||
|
requirements: [SC-1, SC-2, SC-3, SC-5]
|
||||||
|
estimate:
|
||||||
|
tokens: 130000
|
||||||
|
raw_tokens: 130000
|
||||||
|
tasks: 3
|
||||||
|
confidence: low
|
||||||
|
must_haves:
|
||||||
|
truths:
|
||||||
|
- "SC-1, D-02, D-07: golem15.oauthserver has a new config key mcp.subject with values user (the default) and backend; mcp.consent_path (empty: <backend.uri>/connect in backend mode, /connect in user mode) and oidc.enabled (default true) are new too. An unknown subject, backend with mcp.enabled false, and backend together with mcp_scopes fail boot with a clear message. With the defaults, every route, scope list, store write and existing test behaves exactly as before."
|
||||||
|
- "D-08: Requires() still answers [golem15.user] in both modes."
|
||||||
|
- "SC-1, D-01, D-03, D-04: in backend mode /oauth/mcp/authorize hands the browser to {issuer}<backend.uri>/connect?request=<id>; the plugin publishes pact.MCPAdminConsent, and an allow through cabana's {api}/mcp/consent/{request} issues a code under the backend grants lock whose mcp_codes, access_tokens, refresh_tokens and consents rows have user_id NULL and backend_user_id = the administrator; no frontend user is involved."
|
||||||
|
- "SC-1 (Pitfall 4, Pitfall 6): in backend mode the user-mode consent routes /oauth/mcp/requests/{request} are not mounted (404); with oidc.enabled false the OIDC discovery, JWKS, /oauth/authorize*, /oauth/token and /oauth/userinfo routes are not mounted, and the frontend authorized-apps routes are mounted only when oidc.enabled is true or the subject is user."
|
||||||
|
- "SC-2, D-09: in backend mode wristband metadata scopes_supported, the authorize allow-list and the verifier's MCPScopesSupported (so pier's protected-resource metadata) are cabana.TokenScopeNames plus offline_access, and Options.DefaultScopes is the catalog names, so a client sending no scope does not fall back to read."
|
||||||
|
- "SC-2, D-01: the verifier answers a backend row (user_id NULL, backend_user_id set) as pact.MCPGrant{UserID: 0, BackendUserID: admin, Subject: pact.MCPGrantSubjectBackend, ClientID, TokenID, Scopes, ExpiresAt}, refusing it when cabana.BackendPrincipal answers nil (deleted or deactivated) or the token was issued before the administrator's tokens_valid_after; user rows take the unchanged path."
|
||||||
|
- "D-10: offline_access granted on the admin consent yields a refresh token; refresh rotation of a backend row keeps user_id NULL and backend_user_id, and refuses a deleted, deactivated or re-passworded administrator."
|
||||||
|
- "SC-3, D-13: a listener on cabana.BackendAccessRevokedEvent (registered only in backend mode) revokes, inside the save's transaction and under the backend grants lock, every backend access and refresh token of the administrators, deletes their unused backend codes and backend consents, and after commit fires pact.MCPSubjectChanged{Guard: backend, UserID, Kind: revoked, ClientID} once per touched client. User rows and user-mode linked grants are not touched."
|
||||||
|
- "SC-3, D-12: in backend mode the plugin contributes a My account section mcp_connections (only then; user-mode apps' My account is unchanged) listing the signed-in administrator's backend consents (ID client_id, Title client name falling back to client_id, Subtitle scope labels without offline_access, Meta connected / last used or never used) ordered by last_used_at DESC NULLS LAST then created_at DESC, with one item action revoke (Danger, Confirm with :title) that revokes that one client's grant and ends its sessions."
|
||||||
|
- "SC-3, D-12: in backend mode a side-menu entry mcp_connections (icon network, after OAuth clients) opens the admin-wide list golem15.oauthserver.mcpconnections, gated by the new permission golem15.oauthserver.manage_mcp_connections (no default role; superusers pass), with columns administrator, email, client, scopes, created_at, last_used_at, no toolbar buttons, no recordUrl, recordsPerPage 20 and a bulk action revoke."
|
||||||
|
- "UI loading — the admin-wide MCP connections list uses the existing ListView skeleton rows."
|
||||||
|
- "UI empty — the admin-wide list shows mcp_connections.list_empty; an empty search uses the existing empty-search message."
|
||||||
|
- "UI error — the admin-wide list relies on the existing ListView error handling and bulk-action failure toast; nothing new."
|
||||||
|
- "UI long-text — administrator, email, client and scopes cells wrap with the existing ListView cell wrapping."
|
||||||
|
- "UI overflow — on a small screen the admin-wide list uses the existing ListView horizontal scroll container."
|
||||||
|
- "UI zero-one-many — the admin-wide list pages 20 rows with the existing pager; zero rows show mcp_connections.list_empty."
|
||||||
|
- "UI partial — the administrator column falls back to the login when the administrator has no name."
|
||||||
|
- "UI partial — a My account item whose client has no name uses the client_id as its Title."
|
||||||
|
- "SC-5: the plugin README documents backend mode (keys, routes, scopes, storage, migration and rollback, revocation, My account section, MCP connections screen and permission, exclusive per application for now) in the commits that add each piece; the migration is additive and its rollback is documented as deleting backend grants."
|
||||||
|
artifacts:
|
||||||
|
- path: ../sm-oauthserver-plugin/updates/202611200001_add_golem15_oauthserver_backend_subjects.go
|
||||||
|
provides: "nullable user_id on access/refresh/consents, consents.backend_user_id, partial unique and lookup indexes, NOT VALID subject checks"
|
||||||
|
contains: "oas_consents_backend_client_unique"
|
||||||
|
- path: ../sm-oauthserver-plugin/classes/mcp_backend_subject.go
|
||||||
|
provides: "WithBackendSubject, backend grants advisory locks, RevokeBackendGrants"
|
||||||
|
contains: "WithinBackendGrantsLock"
|
||||||
|
- path: ../sm-oauthserver-plugin/classes/mcp_verifier.go
|
||||||
|
provides: "backend branch returning MCPGrantSubjectBackend"
|
||||||
|
contains: "MCPGrantSubjectBackend"
|
||||||
|
- path: ../sm-oauthserver-plugin/controllers/mcp_admin_consent.go
|
||||||
|
provides: "pact.MCPAdminConsent implementation"
|
||||||
|
contains: "MCPAdminConsentDecide"
|
||||||
|
- path: ../sm-oauthserver-plugin/classes/backend_cascade.go
|
||||||
|
provides: "listener for cabana.BackendAccessRevokedEvent"
|
||||||
|
contains: "BackendAccessRevokedEvent"
|
||||||
|
- path: ../sm-oauthserver-plugin/account.go
|
||||||
|
provides: "HasAccountContributions mcp_connections section"
|
||||||
|
contains: "AccountContributions"
|
||||||
|
key_links:
|
||||||
|
- from: ../sm-oauthserver-plugin/servers.go
|
||||||
|
to: "cabana.TokenScopeNames / wristband Options.ConsentPath + DefaultScopes (plan 01)"
|
||||||
|
via: "backend-mode NewServers"
|
||||||
|
pattern: "TokenScopeNames"
|
||||||
|
- from: ../sm-oauthserver-plugin/plugin.go Boot
|
||||||
|
to: pact.MCPAdminConsent
|
||||||
|
via: "app.Publish in backend mode; cabana's consent endpoint looks it up"
|
||||||
|
pattern: "MCPAdminConsent"
|
||||||
|
- from: ../sm-oauthserver-plugin/classes/mcp_store.go
|
||||||
|
to: ../sm-oauthserver-plugin/classes/mcp_backend_subject.go
|
||||||
|
via: "backendSubjectFrom(ctx) on writes, backend row detection on reads"
|
||||||
|
pattern: "backendSubject"
|
||||||
|
- from: ../sm-oauthserver-plugin/classes/backend_cascade.go
|
||||||
|
to: "pier session teardown"
|
||||||
|
via: "MCPSubjectChanged revoked with ClientID after commit"
|
||||||
|
pattern: "MCPSubjectRevoked"
|
||||||
|
---
|
||||||
|
|
||||||
|
<objective>
|
||||||
|
User story (phase goal, ROADMAP 32.2): **As an** editor of a blog-only application whose MCP tools are backend-guarded (Journal) and which has no frontend users, **I want to** add the site's `/mcp` as a connector and sign in once as my administrator account over OAuth, **so that** agents no longer need a hand-copied `g15_` personal token.
|
||||||
|
|
||||||
|
Slice in this plan (the OAuth server issues the administrator's grant): in backend mode, an MCP client's authorize request is handed to the admin consent route, and an Allow through cabana's consent API issues a code. The exchanged token verifies as an administrator-only grant whose rows name the administrator and no frontend user (TestBackendModeSmoke, the first real-token path of the phase). Administrators also list and revoke their own connections on My account.
|
||||||
|
|
||||||
|
The plugin half of SC-1, SC-2 and SC-3 (D-01, D-02, D-03, D-04, D-07, D-08, D-09, D-10, D-12, D-13): an additive, off-by-default backend-subject mode of sm-oauthserver-plugin, where the MCP OAuth sign-in authenticates an administrator and the grant names that administrator.
|
||||||
|
|
||||||
|
Purpose: an application whose MCP tools are backend-guarded and which has no frontend users can accept MCP OAuth sign-in as an administrator. The plugin is shared by several applications, so every change is additive and the user mode (the default) behaves exactly as before.
|
||||||
|
Output: config keys, one additive migration, per-row subject storage in the existing tables, backend advisory locks, verifier and refresh branches, the published consent provider, the cabana-event revocation listener, the My account section, the admin-wide MCP connections screen with its permission, and README, all in ../sm-oauthserver-plugin. Smoke tests only; the broad tests are plan 05.
|
||||||
|
|
||||||
|
⚠ spec-less probe fallback skipped: phase has no requirement IDs to probe (visible skip).
|
||||||
|
|
||||||
|
Discretion recorded (CONTEXT "Claude's Discretion"):
|
||||||
|
- Storage: nullable user_id on access tokens, refresh tokens and consents, plus consents.backend_user_id with a partial unique index (backend_user_id, client_id) WHERE user_id IS NULL, in one additive migration. Every user-mode query filters on user_id, so NULL rows are invisible to it. Model field types stay as they are (UserID uint scans NULL as 0); Consent gains BackendUserID *uint.
|
||||||
|
- Permission: golem15.oauthserver.manage_mcp_connections, no default role.
|
||||||
|
- Admin-wide list model: a read-only models.MCPConnection whose list query is a derived table aliased to the model's table name, joining consents to backend_users and clients so administrator (full name falling back to login), email and client are real searchable columns. If cabana's list query cannot take the derived table, fall back to relation columns (relation admin select login, relation admin select email, relation client select name over references:ClientID) and record the full-name deviation in the SUMMARY.
|
||||||
|
- The backend-mode admin controller, permission, navigation entry and My account section are returned only in backend mode, so controllers.AdminControllers(nil) and every user-mode surface stay as they are. cabana compiles these at Activate, which runs after Boot, so the booted config is known; if a test shows otherwise, record it and declare them unconditionally.
|
||||||
|
- Reversibility: D-02 and D-07 make the mode and its keys a public contract (costly, recorded on the tasks); the migration is costly (its rollback drops backend grants); nothing is one-way, so no checkpoint.
|
||||||
|
</objective>
|
||||||
|
|
||||||
|
<execution_context>
|
||||||
|
@~/.claude/msd-core/workflows/execute-plan.md
|
||||||
|
@~/.claude/msd-core/templates/summary.md
|
||||||
|
</execution_context>
|
||||||
|
|
||||||
|
<context>
|
||||||
|
@.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-CONTEXT.md
|
||||||
|
@.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-RESEARCH.md
|
||||||
|
@.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-PATTERNS.md
|
||||||
|
@.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-UI-SPEC.md
|
||||||
|
@.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-01-SUMMARY.md
|
||||||
|
@../sm-oauthserver-plugin/README.md
|
||||||
|
@../sm-oauthserver-plugin/plugin.go
|
||||||
|
@../sm-oauthserver-plugin/servers.go
|
||||||
|
@../sm-oauthserver-plugin/routes.go
|
||||||
|
@../sm-oauthserver-plugin/config/config.yaml
|
||||||
|
@../sm-oauthserver-plugin/classes/mcp_store.go
|
||||||
|
@../sm-oauthserver-plugin/classes/mcp_verifier.go
|
||||||
|
@../sm-oauthserver-plugin/classes/mcp_backend_binding.go
|
||||||
|
@../sm-oauthserver-plugin/classes/cascade.go
|
||||||
|
@../sm-oauthserver-plugin/controllers/mcp_consent_api.go
|
||||||
|
@../sm-oauthserver-plugin/harness_test.go
|
||||||
|
|
||||||
|
<interfaces>
|
||||||
|
From plan 01 (summercms.go working tree; the plugin's go.mod replaces the framework with ../summercms.go; check 32.2-01-SUMMARY.md for any rename):
|
||||||
|
- pact.MCPGrant.Subject string; const pact.MCPGrantSubjectBackend = "backend"; pact.MCPSubject.ScopeLimited bool
|
||||||
|
- pact.MCPAdminConsent interface { MCPAdminConsentShow(ctx, adminID uint, requestID string) (pact.MCPAdminConsentRequest, error); MCPAdminConsentDecide(ctx, adminID uint, requestID string, d pact.MCPAdminConsentDecision) (string, error) }
|
||||||
|
- pact.MCPAdminConsentRequest{RequestID, ClientID, ClientName, LogoURL, RedirectURI string; Scopes []string; OfflineAccess, ConsentRequired bool; ExpiresAt time.Time}; pact.MCPAdminConsentDecision{Allow bool; Scopes []string; OfflineAccess bool}; pact.ErrMCPConsentNotFound, pact.ErrMCPConsentNoScopes
|
||||||
|
- pact.AccountContribution.Items func(ctx, adminID uint) ([]pact.AccountItem, error); ItemActions []pact.AccountItemAction; ItemsEmpty string; pact.AccountItem{ID, Title, Subtitle string; Meta []string}; pact.AccountItemAction{Name, Label, Confirm string; Danger bool; Permissions []string; Run func(ctx, pact.AccountItemActionInput) (pact.AccountActionResult, error)}; pact.AccountItemActionInput{AdminID uint; ItemID string}; pact.ErrAccountItemNotFound
|
||||||
|
- wristband.Options.ConsentPath string; wristband.Options.DefaultScopes []string
|
||||||
|
- cabana.TokenScopeNames(app) ([]string, error); cabana.TokenScopeLabels(ctx, app, names) []string; cabana.AdminPrefix(app) (string, error); cabana.BackendPrincipal(ctx, app, id) (*bouncer.Principal, error) — nil for deleted/deactivated, Principal.TokensValidAfter time.Time
|
||||||
|
- cabana.BackendAccessRevokedEvent{AdminIDs []uint; Reason string; Tx *gorm.DB}
|
||||||
|
Existing plugin (read this session):
|
||||||
|
- Config{..., MCPEnabled bool; MCPResource string}; LoadConfig reads golem15.oauthserver.*; NewServers builds mcpOpts from DefaultOptions with ScopesSupported = classes.AdvertisedMCPScopes(app) and the verifier with the same slice
|
||||||
|
- Boot publishes servers.KeyRing, pact.MCPTokenVerifier (when MCPEnabled) and registers Cascade listeners on userclasses events
|
||||||
|
- routes.go: OIDC groups at lines 40-68, MCP group at lines 70-82 (metadata, authorize, register, token; user consent /oauth/mcp/requests/{request} behind jwt.auth)
|
||||||
|
- classes/mcp_backend_binding.go: consentedBackendKey/WithConsentedBackend, WithGrantedOfflineAccess, backendBinding(scopes, id) (nil unless the backend scope), userGrantsLockKey "golem15_oauthserver_user_grants:<id>", lockUserGrantsShared, LockUserGrants, grantsTxKey, WithinUserGrantsLock
|
||||||
|
- classes/mcp_store.go: mcpTx methods MarkIssued (column map), ByCodeHashForUpdate, Create (refresh), ByTokenHashForUpdate, refreshUserUsable, refreshRecord, Mint, consentedBackend
|
||||||
|
- classes/mcp_verifier.go: MCPVerifyToken, stamp, issuedBeforeCutoff(createdAt *time.Time, cutoff time.Time) bool
|
||||||
|
- classes/subject_events.go: FireSubjectChanged, FireSubjectChangedAfterCommit(ctx, app, tx, guard, userID, kind)
|
||||||
|
- controllers/mcp_consent_api.go: mcpRequestedScopes, mcpPendingClientID, replaceMCPConsent, clipRunes, maxMCPClientName, mcpScopeText
|
||||||
|
- models: AccessToken.UserID uint, AccessToken.BackendUserID *uint, RefreshToken.UserID uint/BackendUserID *uint, MCPCode.UserID *uint/BackendUserID *uint, Consent{ID, UserID uint, ClientID, Scopes Strings, LastUsedAt, CreatedAt, UpdatedAt}
|
||||||
|
- controllers.AdminControllers(func() *backpack.App) answers exactly the clients and branding controllers (admin_surface_test.go pins that)
|
||||||
|
- harness_test.go: bootOAuthWith(t, extra []string, overrides ...string) with SUMMER_* overrides; env.admin(t, permissions...) answers an admin bearer; adminCall uses cabana.DefaultAdminPrefix + "/api/v1"
|
||||||
|
</interfaces>
|
||||||
|
</context>
|
||||||
|
|
||||||
|
<tasks>
|
||||||
|
|
||||||
|
<task type="tracer">
|
||||||
|
<name>Tracer: in backend mode an administrator consents through cabana and the issued token verifies as an administrator-only grant</name>
|
||||||
|
<reversibility rating="costly">D-02 and D-07 publish mcp.subject (values user and backend), mcp.consent_path and oidc.enabled as the plugin's config contract, and the migration changes three columns other code reads; its rollback deletes backend grants.</reversibility>
|
||||||
|
<precondition>docker info exits 0; `grep -n 'MCPGrantSubjectBackend' /media/nvme/dev/golem15/summercms.io/summercms/summercms.go/modules/pact/mcp.go` and `grep -n 'type MCPAdminConsent interface' /media/nvme/dev/golem15/summercms.io/summercms/summercms.go/modules/pact/mcp.go` match (plan 01 landed).</precondition>
|
||||||
|
<files>../sm-oauthserver-plugin/config/config.yaml, ../sm-oauthserver-plugin/servers.go, ../sm-oauthserver-plugin/routes.go, ../sm-oauthserver-plugin/plugin.go, ../sm-oauthserver-plugin/updates/202611200001_add_golem15_oauthserver_backend_subjects.go, ../sm-oauthserver-plugin/models/consent.go, ../sm-oauthserver-plugin/classes/mcp_backend_subject.go, ../sm-oauthserver-plugin/classes/mcp_store.go, ../sm-oauthserver-plugin/classes/mcp_verifier.go, ../sm-oauthserver-plugin/controllers/mcp_admin_consent.go, ../sm-oauthserver-plugin/harness_test.go, ../sm-oauthserver-plugin/backend_mode_smoke_test.go, ../sm-oauthserver-plugin/README.md</files>
|
||||||
|
<read_first>
|
||||||
|
../sm-oauthserver-plugin/config/config.yaml (comment style, mcp block, mcp_scopes)
|
||||||
|
../sm-oauthserver-plugin/servers.go (Config, LoadConfig, NewServers)
|
||||||
|
../sm-oauthserver-plugin/routes.go (every GroupRaw block)
|
||||||
|
../sm-oauthserver-plugin/plugin.go (Requires, Boot)
|
||||||
|
../sm-oauthserver-plugin/updates/202610230001_add_backend_user_id.go (migration file shape, run helper, Register in init)
|
||||||
|
../sm-oauthserver-plugin/updates/202610190001_create_golem15_oauthserver_tables.go (current columns and constraints)
|
||||||
|
../sm-oauthserver-plugin/classes/mcp_backend_binding.go (context keys, lock keys, WithinUserGrantsLock join-the-tx trick)
|
||||||
|
../sm-oauthserver-plugin/classes/mcp_store.go (MarkIssued, ByCodeHashForUpdate, mcpCodeRecord, Mint, Create)
|
||||||
|
../sm-oauthserver-plugin/classes/mcp_verifier.go (MCPVerifyToken, issuedBeforeCutoff)
|
||||||
|
../sm-oauthserver-plugin/controllers/mcp_consent_api.go (MCPConsentShow, MCPConsentDecide, replaceMCPConsent, IssueCode usage)
|
||||||
|
../sm-oauthserver-plugin/harness_test.go and admin_smoke_test.go (bootOAuthWith, env.admin, adminCall)
|
||||||
|
../sm-oauthserver-plugin/mcp_consent_smoke_test.go (PKCE + DCR + authorize + token test flow to copy)
|
||||||
|
/media/nvme/dev/golem15/summercms.io/summercms/summercms.go/modules/cabana/mcp_consent.go (the endpoint this provider serves; from plan 01)
|
||||||
|
</read_first>
|
||||||
|
<action>
|
||||||
|
Config (D-07, D-04, D-14 prerequisite): in config/config.yaml add under mcp, with the file's comment style and "(new)" markers, subject: user (user or backend; backend authenticates an administrator and needs mcp.enabled; one subject per application for now) and consent_path: "" (empty: <backend.uri>/connect in backend mode, /connect in user mode), and a new top-level oidc block with enabled: true (false mounts no OIDC provider routes). Name the env vars SUMMER_GOLEM15__OAUTHSERVER__MCP__SUBJECT, ..._MCP__CONSENT_PATH and ..._OIDC__ENABLED in the comments. In servers.go add Config.MCPSubjectMode (exported constants SubjectModeUser = "user" and SubjectModeBackend = "backend" in package classes), Config.MCPConsentPath and Config.OIDCEnabled, read in LoadConfig; empty subject is user; any other value fails boot ("%s: mcp.subject %q must be user or backend"); backend with mcp.enabled false fails boot; backend while golem15.oauthserver.mcp_scopes is set fails boot (the member-scope filter has no meaning there).
|
||||||
|
|
||||||
|
Migration (storage discretion), new updates/202611200001_add_golem15_oauthserver_backend_subjects.go with ID 202611200001_add_golem15_oauthserver_backend_subjects, raw SQL through run like 202610230001: ALTER COLUMN user_id DROP NOT NULL on golem15_oauthserver_access_tokens, _refresh_tokens and _consents; ADD COLUMN backend_user_id INTEGER NULL on _consents (no FK: backend users are only soft-deleted); CREATE UNIQUE INDEX oas_consents_backend_client_unique ON _consents (backend_user_id, client_id) WHERE user_id IS NULL; CREATE INDEX oas_tokens_backend_client_idx and oas_refresh_backend_client_idx on (backend_user_id, client_id) WHERE user_id IS NULL; ADD CONSTRAINT oas_tokens_subject_check CHECK ((user_id IS NOT NULL AND user_id > 0) OR backend_user_id IS NOT NULL) NOT VALID, oas_refresh_subject_check and oas_consents_subject_check CHECK (user_id IS NOT NULL OR backend_user_id IS NOT NULL) NOT VALID. Rollback: DELETE the user_id IS NULL rows of the three tables (comment: backend grants cannot survive a down migration), drop the constraints, indexes and column, SET NOT NULL. Do not touch auth_codes (OIDC) or mcp_codes (already nullable). Add BackendUserID *uint (column backend_user_id) to models.Consent; do not change any existing field type.
|
||||||
|
|
||||||
|
Subject and locks, new classes/mcp_backend_subject.go: WithBackendSubject(ctx) context.Context and unexported backendSubjectFrom(ctx) bool; backendGrantsLockKey(id) = "golem15_oauthserver_backend_grants:" + id (a namespace separate from users, so administrator 7 and user 7 never contend); lockBackendGrantsShared, LockBackendGrants(ctx, db, adminIDs) and WithinBackendGrantsLock(ctx, db, adminIDs, fn) reusing grantsTxKey exactly like WithinUserGrantsLock so MCPStore.WithinTx joins the locked transaction.
|
||||||
|
|
||||||
|
Store, authorization-code path (classes/mcp_store.go): MarkIssued with backendSubjectFrom(ctx) writes user_id nil and backend_user_id = the id wristband passes (regardless of the backend scope; never reuse backendBinding for it); ByCodeHashForUpdate also selects backend_user_id, and a row with user_id NULL and backend_user_id set takes lockBackendGrantsShared, fills the record's UserID from backend_user_id and marks the mcpTx as a backend-subject transaction; Mint and Create (refresh) in a backend-subject transaction write no user_id (column map or Omit, never a zero) and backend_user_id = the id. User-mode writes are unchanged.
|
||||||
|
|
||||||
|
Verifier (D-01, D-09): in MCPVerifyToken, after the existing token and client checks and before the user principal lookup, a row with UserID 0 and BackendUserID set loads cabana.BackendPrincipal; nil, an error, or issuedBeforeCutoff(token.CreatedAt, principal.TokensValidAfter) answers pact.ErrMCPTokenInvalid; otherwise stamp and answer pact.MCPGrant{UserID: 0, BackendUserID, Subject: pact.MCPGrantSubjectBackend, ClientID, TokenID, Scopes, ExpiresAt}. The user path is unchanged.
|
||||||
|
|
||||||
|
Consent provider (D-03), new controllers/mcp_admin_consent.go: exported type MCPAdminConsent{App *backpack.App; Server *wristband.Server} with NewMCPAdminConsent(app, srv) implementing pact.MCPAdminConsent. Show: srv.PendingRequest(ctx, requestID, adminID) (wristband.ErrPendingNotFound → pact.ErrMCPConsentNotFound), the client name clipped like the user-mode API, the logo URL, the pending redirect URI, requested data scopes without offline_access, OfflineAccess, ConsentRequired (false when the administrator's backend consent for the client already covers the request), ExpiresAt. Decide: deny → srv.DenyPending; allow → WithinBackendGrantsLock for the administrator, then IssueCode with ctx carrying WithBackendSubject and WithGrantedOfflineAccess(d.OfflineAccess), then replace the backend consent row (user_id NULL, backend_user_id, client_id, the granted scopes plus offline_access when granted; INSERT … ON CONFLICT on the partial unique index; never merge with older scopes); wristband.ErrNoGrantableScopes → pact.ErrMCPConsentNoScopes. Answer the redirect target IssueCode or DenyPending returns. Do not log codes or bearer tokens.
|
||||||
|
|
||||||
|
Servers and routes (D-04, D-09, Pitfalls 3, 4, 6): in NewServers, backend mode sets mcpOpts.ScopesSupported = cabana.TokenScopeNames(app) plus offline_access (same slice on the verifier, so pier's protected-resource metadata advertises it), mcpOpts.DefaultScopes = the catalog names, and mcpOpts.ConsentPath = cfg.MCPConsentPath or cabana.AdminPrefix(app) + "/connect" (an AdminPrefix error fails boot). User mode keeps classes.AdvertisedMCPScopes and leaves ConsentPath and DefaultScopes empty. In routes.go mount the OIDC groups only when OIDCEnabled; the frontend authorized-apps routes only when OIDCEnabled or the subject is user; the /oauth/mcp/requests/{request} consent routes only in user mode. Boot publishes pact.MCPAdminConsent (controllers.NewMCPAdminConsent(app, servers.MCP)) in backend mode only. Requires() stays [golem15.user] (D-08).
|
||||||
|
|
||||||
|
Harness and smoke: add bootBackendMode(t, overrides...) in harness_test.go (mcp.enabled true, mcp.subject backend, oidc.enabled false, a resource). New backend_mode_smoke_test.go TestBackendModeSmoke (Docker): register a client by DCR, authorize with PKCE and no scope → 302 to issuer + cabana.DefaultAdminPrefix + "/connect?request=…"; an administrator holding admin:read's permissions GETs {prefix}/api/v1/mcp/consent/{request} (scopes include admin:read) and POSTs allow with [admin:read] and offline_access true → redirect_uri with code; exchanging the code answers an access token and a refresh token; the published pact.MCPTokenVerifier answers Subject backend, UserID 0, BackendUserID = the administrator; the access_tokens, refresh_tokens and consents rows have user_id NULL and backend_user_id set; GET /oauth/mcp/requests/{request} and /.well-known/openid-configuration answer 404; metadata scopes_supported contains *, admin:read and offline_access; a boot with mcp.subject frontend fails. README: a "Backend-subject mode" section with the keys, routes and storage added here. Commit in ../sm-oauthserver-plugin only, staging these files by path; never stage go.work (another session's edit).
|
||||||
|
</action>
|
||||||
|
<verify>
|
||||||
|
<automated>go -C /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin test -count=1 -timeout 600s -run 'TestBackendModeSmoke|TestMCPConsentSmoke|TestMCPStoreSmoke|TestMCPTokenVerifierSmoke|TestMCPTokenVerifier$' .</automated>
|
||||||
|
<fails_when>non-zero exit, or a line contains FAIL, or `[no tests to run]`, or `--- SKIP: TestBackendModeSmoke` appears, or TestBackendModeSmoke has no `--- PASS` line (run with -v if needed)</fails_when>
|
||||||
|
<automated>go -C /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin vet ./... && go -C /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin test -short -count=1 ./...</automated>
|
||||||
|
<fails_when>non-zero exit, or a line contains FAIL</fails_when>
|
||||||
|
</verify>
|
||||||
|
<acceptance_criteria>
|
||||||
|
- config/config.yaml contains `subject: user`, `consent_path: ""` and an `oidc:` block with `enabled: true`.
|
||||||
|
- `grep -n 'oas_consents_backend_client_unique' ../sm-oauthserver-plugin/updates/202611200001_add_golem15_oauthserver_backend_subjects.go` matches and the file has a Rollback.
|
||||||
|
- `grep -n '"golem15_oauthserver_backend_grants:"' ../sm-oauthserver-plugin/classes/mcp_backend_subject.go` matches.
|
||||||
|
- `grep -n 'MCPGrantSubjectBackend' ../sm-oauthserver-plugin/classes/mcp_verifier.go` matches.
|
||||||
|
- plugin.go Requires() still returns exactly golem15.user.
|
||||||
|
- TestBackendModeSmoke passes (not skipped) with every assertion listed in the action.
|
||||||
|
- The plugin's `go test -short ./...` passes, so user-mode unit tests are unchanged.
|
||||||
|
</acceptance_criteria>
|
||||||
|
<done>In backend mode an MCP client's authorization request ends in an administrator-only grant whose rows name the administrator and no frontend user; user mode is untouched.</done>
|
||||||
|
</task>
|
||||||
|
|
||||||
|
<task type="auto">
|
||||||
|
<name>Refresh rotation and in-transaction revocation for administrator grants</name>
|
||||||
|
<reversibility rating="reversible">Internal store branches and a listener behind the plan 01 event; no new public contract.</reversibility>
|
||||||
|
<precondition>docker info exits 0; `grep -n 'type BackendAccessRevokedEvent struct' /media/nvme/dev/golem15/summercms.io/summercms/summercms.go/modules/cabana/admin_events.go` matches.</precondition>
|
||||||
|
<files>../sm-oauthserver-plugin/classes/mcp_store.go, ../sm-oauthserver-plugin/classes/mcp_backend_subject.go, ../sm-oauthserver-plugin/classes/backend_cascade.go, ../sm-oauthserver-plugin/plugin.go, ../sm-oauthserver-plugin/backend_revocation_smoke_test.go, ../sm-oauthserver-plugin/README.md</files>
|
||||||
|
<read_first>
|
||||||
|
../sm-oauthserver-plugin/classes/mcp_store.go (ByTokenHashForUpdate, refreshUserUsable, refreshRow, refreshRecord)
|
||||||
|
../sm-oauthserver-plugin/classes/cascade.go (Cascade, revokeUserGrants, grantRef, txOf; the revoke shape to mirror)
|
||||||
|
../sm-oauthserver-plugin/classes/subject_events.go (FireSubjectChangedAfterCommit)
|
||||||
|
../sm-oauthserver-plugin/controllers/authorizations.go (revoke: per-client revoke and its after-commit event)
|
||||||
|
../sm-oauthserver-plugin/mcp_revocation_smoke_test.go (revocation test shape)
|
||||||
|
/media/nvme/dev/golem15/summercms.io/summercms/summercms.go/modules/cabana/admin_events.go (event and reasons, plan 01)
|
||||||
|
</read_first>
|
||||||
|
<action>
|
||||||
|
Refresh (D-10): ByTokenHashForUpdate treats a row with user_id NULL and backend_user_id set as a backend-subject row: lockBackendGrantsShared, mark the mcpTx as backend-subject so the rotated refresh and the new access token (Create, Mint) keep user_id NULL and backend_user_id; refreshUserUsable for such a row loads cabana.BackendPrincipal and answers unusable when it is nil, errors, or the row's created_at is before principal.TokensValidAfter (issuedBeforeCutoff); refreshRecord fills UserID from BackendUserID for such a row. User rows are unchanged, ban checks included.
|
||||||
|
|
||||||
|
Revocation (D-13): in classes/mcp_backend_subject.go add exported BackendGrantRef{AdminID uint; ClientID string} and RevokeBackendGrants(ctx, tx *gorm.DB, adminIDs []uint, clientID string) ([]BackendGrantRef, error): for rows with user_id NULL and backend_user_id IN adminIDs (and client_id = clientID when non-empty) revoke the access tokens and refresh tokens the way revokeUserGrants revokes user rows, delete unused mcp_codes and the consents, and answer the distinct (admin, client) pairs touched. Add FireBackendRevokedAfterCommit(ctx, app, tx, refs) firing pact.MCPSubjectChanged{Guard: "backend", UserID: AdminID, Kind: pact.MCPSubjectRevoked, ClientID} per ref through lagoon.AfterCommit (a listener error only logs).
|
||||||
|
|
||||||
|
Listener, new classes/backend_cascade.go: BackendCascade{App *backpack.App} with OnBackendAccessRevoked(ctx, ev *cabana.BackendAccessRevokedEvent) error: nil-safe on ev and empty AdminIDs; uses ev.Tx (falls back to the app database outside a transaction, like Cascade.txOf); takes LockBackendGrants for the ids; RevokeBackendGrants with clientID ""; FireBackendRevokedAfterCommit; returns any error so the administrator save rolls back. Boot registers it with app.Events.Listen[*cabana.BackendAccessRevokedEvent](PluginID, …) only in backend mode. User rows, user-mode linked grants (rows with a user_id) and the existing userclasses listeners are not touched.
|
||||||
|
|
||||||
|
Smoke, new backend_revocation_smoke_test.go TestBackendRevocationSmoke (Docker, bootBackendMode): one administrator connects two clients with offline_access; a refresh rotation answers a new access token whose row keeps user_id NULL and backend_user_id; the administrator's own password change through PUT {prefix}/api/v1/account (current password supplied) leaves both clients' access and refresh tokens refused by the verifier and the token endpoint, deletes both backend consents, and records two MCPSubjectChanged revoked events (one per ClientID) after commit through a recording listener; deactivating a second administrator through the admin users screen revokes their grant the same way. README: refresh and revocation rules, and which administrator changes end grants (from plan 01's event). Commit by path in ../sm-oauthserver-plugin.
|
||||||
|
</action>
|
||||||
|
<verify>
|
||||||
|
<automated>go -C /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin test -count=1 -timeout 600s -run 'TestBackendRevocationSmoke|TestBackendModeSmoke|TestMCPRevocationSmoke|TestUserDeleteCascade' .</automated>
|
||||||
|
<fails_when>non-zero exit, or a line contains FAIL, or `[no tests to run]`, or `--- SKIP: TestBackendRevocationSmoke` appears</fails_when>
|
||||||
|
<automated>go -C /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin vet ./... && go -C /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin test -short -count=1 ./...</automated>
|
||||||
|
<fails_when>non-zero exit, or a line contains FAIL</fails_when>
|
||||||
|
</verify>
|
||||||
|
<acceptance_criteria>
|
||||||
|
- `grep -n 'func RevokeBackendGrants' ../sm-oauthserver-plugin/classes/mcp_backend_subject.go` and `grep -n 'OnBackendAccessRevoked' ../sm-oauthserver-plugin/classes/backend_cascade.go` match.
|
||||||
|
- plugin.go registers the BackendAccessRevokedEvent listener inside a backend-mode condition.
|
||||||
|
- TestBackendRevocationSmoke passes (not skipped), including the two per-client revoked events and the rotated backend-shaped refresh.
|
||||||
|
- Existing TestUserDeleteCascade and TestMCPRevocationSmoke still pass.
|
||||||
|
</acceptance_criteria>
|
||||||
|
<done>An administrator's agent can stay connected through refresh, and every D-13 change ends its tokens and sessions atomically with the save.</done>
|
||||||
|
</task>
|
||||||
|
|
||||||
|
<task type="auto">
|
||||||
|
<name>My account MCP connections section and the admin-wide MCP connections screen</name>
|
||||||
|
<reversibility rating="costly">The permission code golem15.oauthserver.manage_mcp_connections is stored in roles once administrators grant it; renaming it later needs a data fix.</reversibility>
|
||||||
|
<precondition>docker info exits 0; `grep -n 'type AccountItemAction struct' /media/nvme/dev/golem15/summercms.io/summercms/summercms.go/modules/pact/capabilities.go` matches.</precondition>
|
||||||
|
<files>../sm-oauthserver-plugin/account.go, ../sm-oauthserver-plugin/models/mcp_connection.go, ../sm-oauthserver-plugin/models/mcpconnection/columns.yaml, ../sm-oauthserver-plugin/controllers/mcp_connections.go, ../sm-oauthserver-plugin/controllers/mcpconnections/config_list.yaml, ../sm-oauthserver-plugin/controllers/admin_registry.go, ../sm-oauthserver-plugin/admin.go, ../sm-oauthserver-plugin/admin_permissions.go, ../sm-oauthserver-plugin/admin_navigation.go, ../sm-oauthserver-plugin/lang/en/lang.yaml, ../sm-oauthserver-plugin/lang/pl/lang.yaml, ../sm-oauthserver-plugin/backend_account_smoke_test.go, ../sm-oauthserver-plugin/README.md, ../sm-oauthserver-plugin/plugin.yaml</files>
|
||||||
|
<read_first>
|
||||||
|
/media/nvme/dev/golem15/summercms.io/summercms/sm-user-plugin/account_contributions.go (HasAccountContributions example: phrase prefix, Status, Danger + Confirm)
|
||||||
|
../sm-oauthserver-plugin/controllers/clients.go and controllers/clients/config_list.yaml, models/client/columns.yaml (admin controller, ListExtendQuery, YAML)
|
||||||
|
../sm-oauthserver-plugin/controllers/admin_registry.go (AdminControllers)
|
||||||
|
../sm-oauthserver-plugin/admin.go (embed list), admin_permissions.go, admin_navigation.go
|
||||||
|
../sm-oauthserver-plugin/admin_surface_test.go (must keep passing unchanged in user mode)
|
||||||
|
../sm-oauthserver-plugin/lang/en/lang.yaml and lang/pl/lang.yaml
|
||||||
|
/media/nvme/dev/golem15/summercms.io/summercms/summercms.go/modules/cabana/list_schema.go and query.go (relation/select columns, relationSubquery)
|
||||||
|
/media/nvme/dev/golem15/summercms.io/summercms/summercms.go/modules/pact/capabilities.go (AdminBulkAction, HasAdminBulkActions, ListExtendQuery)
|
||||||
|
.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-UI-SPEC.md (C4, C5 and the plugin copy tables)
|
||||||
|
</read_first>
|
||||||
|
<action>
|
||||||
|
My account (D-12, UI-SPEC C4), new account.go: var _ pact.HasAccountContributions = (*Plugin)(nil); AccountContributions() answers nothing in user mode and, in backend mode, one section Name mcp_connections, Label account.section, Description account.description, Status account.status with :url = the configured mcp.resource, ItemsEmpty account.empty (all golem15.oauthserver::lang.*). Items: the administrator's backend consents (user_id IS NULL AND backend_user_id = adminID) joined to clients, ordered last_used_at DESC NULLS LAST then created_at DESC; ID client_id, Title the client name or the client_id when the name is empty, Subtitle cabana.TokenScopeLabels of the granted scopes without offline_access joined with ", ", Meta [account.connected with :date YYYY-MM-DD, account.last_used with :date or account.never_used], translated with the request locale. One item action revoke: Label account.revoke, Confirm account.revoke_confirm (contains :title), Danger true; Run takes LockBackendGrants for in.AdminID on cabana.TxFromContext's transaction, RevokeBackendGrants(ctx, tx, [in.AdminID], in.ItemID), answers pact.ErrAccountItemNotFound when nothing was revoked, FireBackendRevokedAfterCommit, and answers Message account.revoked.
|
||||||
|
|
||||||
|
Admin-wide list (D-12, UI-SPEC C5): new models/mcp_connection.go, a read-only MCPConnection with TableName golem15_oauthserver_mcp_connections and fields id, backend_user_id, client_id, administrator, email, client, scopes_text, created_at, last_used_at (not added to models.Register, because it has no table of its own). New controllers/mcp_connections.go with exported MCPConnectionsControllerID = "golem15.oauthserver.mcpconnections" and PermissionManageMCPConnections = "golem15.oauthserver.manage_mcp_connections": ConfigDir controllers/mcpconnections, RequiredPermissions [PermissionManageMCPConnections], NewRecord &models.MCPConnection{}, ListExtendQuery replacing the FROM with a derived table aliased golem15_oauthserver_mcp_connections over consents with user_id IS NULL AND backend_user_id IS NOT NULL joined to backend_users (administrator = trimmed first and last name, else login; email) and LEFT JOIN clients (client = name, else client_id), scopes_text = the granted names without offline_access joined with ", ". If cabana's list cannot take the derived table, use the relation-column fallback recorded in the objective. Bulk action revoke (Label mcp_connections.revoke, Confirm mcp_connections.revoke_confirm, empty result Message so the framework's list.bulk_done shows) revokes each selected (administrator, client) pair through RevokeBackendGrants and FireBackendRevokedAfterCommit inside the action's transaction. controllers/mcpconnections/config_list.yaml per C5 (title, noRecordsMessage, recordsPerPage 20, showCheckboxes, showSetup, showSorting, defaultSort created_at desc, bulkActions [revoke], toolbar search prompt backend::lang.list.search_prompt, no toolbar buttons, no recordUrl); models/mcpconnection/columns.yaml with id (invisible), administrator, email, client (text, searchable), scopes (text), created_at and last_used_at (datetime). Add a BackendModeAdminControllers accessor in controllers and have Plugin.AdminControllers append it only in backend mode, so controllers.AdminControllers(nil) still answers exactly two controllers. Add the YAML files to admin.go's embed list.
|
||||||
|
|
||||||
|
Permission and navigation: Permissions() adds {Code: PermissionManageMCPConnections, Tab: golem15.oauthserver::lang.plugin.tab, Label: golem15.oauthserver::lang.permissions.manage_mcp_connections} in backend mode, no default role. Navigation() adds, in backend mode, a side-menu entry after clients: Code mcp_connections, Label mcp_connections.menu_label, Icon network, Permissions [PermissionManageMCPConnections], Controller MCPConnectionsControllerID. The main item keeps its label and golem15.oauthserver.* permission.
|
||||||
|
|
||||||
|
Lang en and pl: the account.* and mcp_connections.* groups and permissions.manage_mcp_connections exactly as the UI-SPEC copy tables give them. README: My account section, MCP connections screen, permission and the bulk revoke. If TestPluginManifest fails because the README summary or capabilities changed, regenerate plugin.yaml with `go -C /media/nvme/dev/golem15/summercms.io/summercms/summercms.go run ./cmd/summer plugin:manifest` run against this plugin directory (check the command's usage) and commit it.
|
||||||
|
|
||||||
|
Smoke, new backend_account_smoke_test.go TestBackendAccountSmoke (Docker, bootBackendMode): GET {prefix}/api/v1/account/contributions lists mcp_connections with one item per connected client; POST …/items/{client_id}/actions/revoke revokes only that client (the other client's token still verifies) and records one revoked event with that ClientID; a second administrator posting the first one's client_id gets 404; the mcpconnections list answers 403 without the permission and lists both administrators' connections with it, searchable by administrator; bulk revoke removes the selected rows; in user mode (bootOAuth) the contributions list has no mcp_connections section and TestAdminSurfaceHidesCredentials still passes. Commit by path.
|
||||||
|
</action>
|
||||||
|
<verify>
|
||||||
|
<automated>go -C /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin test -count=1 -timeout 600s -run 'TestBackendAccountSmoke|TestAdminSurfaceHidesCredentials|TestClientsAdminSmoke|TestBrandingAdminSmoke|TestPluginManifest' .</automated>
|
||||||
|
<fails_when>non-zero exit, or a line contains FAIL, or `[no tests to run]`, or `--- SKIP: TestBackendAccountSmoke` appears</fails_when>
|
||||||
|
<automated>go -C /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin vet ./... && go -C /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin test -count=1 -timeout 900s ./...</automated>
|
||||||
|
<fails_when>non-zero exit, or a line contains FAIL</fails_when>
|
||||||
|
</verify>
|
||||||
|
<acceptance_criteria>
|
||||||
|
- `grep -n '"golem15.oauthserver.manage_mcp_connections"' ../sm-oauthserver-plugin/controllers/mcp_connections.go` matches.
|
||||||
|
- account.go declares `var _ pact.HasAccountContributions = (*Plugin)(nil)` and answers no section in user mode.
|
||||||
|
- controllers/mcpconnections/config_list.yaml has `recordsPerPage: 20` and `bulkActions`, and no `recordUrl` key.
|
||||||
|
- Both lang files contain account.section, account.revoke_confirm, mcp_connections.list_title and permissions.manage_mcp_connections.
|
||||||
|
- TestBackendAccountSmoke passes (not skipped); TestAdminSurfaceHidesCredentials passes unchanged.
|
||||||
|
- The full plugin suite (`go test ./...` with Docker) passes.
|
||||||
|
</acceptance_criteria>
|
||||||
|
<done>Administrators see and revoke their own agents on My account, and a superuser or a holder of the new permission sees and revokes everyone's; user-mode applications see no new section, screen or permission.</done>
|
||||||
|
</task>
|
||||||
|
|
||||||
|
</tasks>
|
||||||
|
|
||||||
|
<threat_model>
|
||||||
|
## Trust Boundaries
|
||||||
|
|
||||||
|
| Boundary | Description |
|
||||||
|
|----------|-------------|
|
||||||
|
| cabana consent endpoint → plugin provider | The administrator id comes from cabana's authenticated principal, never from the request body |
|
||||||
|
| MCP token endpoint → store | Code and refresh lookups decide whose subject a token names |
|
||||||
|
| oas_at_ bearer → verifier | A token becomes an administrator grant |
|
||||||
|
| cabana admin saves → revocation listener | In-transaction revocation; a failure rolls the save back |
|
||||||
|
| Admin list and My account → revoke | Revoking another administrator's agent |
|
||||||
|
|
||||||
|
## STRIDE Threat Register
|
||||||
|
|
||||||
|
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|
||||||
|
|-----------|----------|-----------|----------|-------------|-----------------|
|
||||||
|
| T-32.2-13 | Elevation of privilege | store MarkIssued/Mint/Create | critical | mitigate | Backend writes leave user_id NULL (never 0 or an admin id in a users-FK column); CHECK constraints refuse a row naming no subject or user_id 0 |
|
||||||
|
| T-32.2-14 | Elevation of privilege | user consent routes in backend mode | high | mitigate | /oauth/mcp/requests/* not mounted in backend mode, so a frontend user cannot finish an administrator's pending request (Pitfall 4); smoke asserts 404 |
|
||||||
|
| T-32.2-15 | Elevation of privilege | verifier backend branch | high | mitigate | cabana.BackendPrincipal (nil for deleted/deactivated) and the tokens_valid_after cutoff on every verification and refresh; pier re-verifies every request |
|
||||||
|
| T-32.2-16 | Tampering (race) | consent allow vs revoke | medium | mitigate | Issue and revoke both run under the per-administrator backend grants advisory lock, in a namespace separate from users |
|
||||||
|
| T-32.2-17 | Repudiation / Elevation | D-13 revocation | high | mitigate | Listener revokes in the save's transaction and returns its error; MCPSubjectChanged revoked per client after commit ends sessions |
|
||||||
|
| T-32.2-18 | Elevation of privilege | My account revoke | medium | mitigate | Run scopes RevokeBackendGrants to in.AdminID; cabana already refuses unlisted items; smoke asserts the cross-admin 404 |
|
||||||
|
| T-32.2-19 | Elevation of privilege | admin-wide list and bulk revoke | medium | mitigate | RequiredPermissions manage_mcp_connections, no default role; list query restricted to backend rows |
|
||||||
|
| T-32.2-20 | Information disclosure | logs | medium | mitigate | No code, bearer, refresh token or request id in log lines; tests assert status codes and ids |
|
||||||
|
| T-32.2-21 | Denial of service | migration on existing installs | low | accept | DROP NOT NULL and NOT VALID constraints avoid table rewrites and scans; indexes are partial over backend rows, empty on user-mode installs |
|
||||||
|
| T-32.2-SC | Tampering | go module installs | low | accept | No dependency added; cabana is already a framework import of the plugin |
|
||||||
|
</threat_model>
|
||||||
|
|
||||||
|
<verification>
|
||||||
|
The three Docker smokes pass; the plugin's go vet, go test -short ./... and the full go test ./... pass; plugin.yaml matches the manifest; no go.work is staged.
|
||||||
|
</verification>
|
||||||
|
|
||||||
|
<success_criteria>
|
||||||
|
- SC-1 plugin half: backend-mode authorize → admin SPA consent → administrator-only grant; user mode unchanged (D-01, D-02, D-03, D-04, D-07, D-08).
|
||||||
|
- SC-2 plugin half: the verifier answers backend grants pier scope-limits; scopes are the cabana catalog (D-09).
|
||||||
|
- SC-3 plugin half: revocation on every D-13 change, My account revoke and the admin-wide screen (D-12, D-13).
|
||||||
|
- SC-5: plugin README.
|
||||||
|
</success_criteria>
|
||||||
|
|
||||||
|
<output>
|
||||||
|
Create `.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-03-SUMMARY.md` when done.
|
||||||
|
</output>
|
||||||
|
|
||||||
|
## Artifacts this phase produces
|
||||||
|
|
||||||
|
Plan 03 (sm-oauthserver-plugin):
|
||||||
|
- Config keys: golem15.oauthserver.mcp.subject (user|backend), golem15.oauthserver.mcp.consent_path, golem15.oauthserver.oidc.enabled; Config.MCPSubjectMode, Config.MCPConsentPath, Config.OIDCEnabled; classes.SubjectModeUser, classes.SubjectModeBackend
|
||||||
|
- Migration 202611200001_add_golem15_oauthserver_backend_subjects (new file updates/202611200001_add_golem15_oauthserver_backend_subjects.go): nullable user_id on access_tokens, refresh_tokens, consents; consents.backend_user_id; indexes oas_consents_backend_client_unique, oas_tokens_backend_client_idx, oas_refresh_backend_client_idx; constraints oas_tokens_subject_check, oas_refresh_subject_check, oas_consents_subject_check
|
||||||
|
- models.Consent.BackendUserID; new read model models.MCPConnection (models/mcp_connection.go) with models/mcpconnection/columns.yaml
|
||||||
|
- New file classes/mcp_backend_subject.go: WithBackendSubject, backendSubjectFrom, backendGrantsLockKey, lockBackendGrantsShared, LockBackendGrants, WithinBackendGrantsLock, BackendGrantRef, RevokeBackendGrants, FireBackendRevokedAfterCommit
|
||||||
|
- New file classes/backend_cascade.go: BackendCascade, OnBackendAccessRevoked
|
||||||
|
- New file controllers/mcp_admin_consent.go: MCPAdminConsent, NewMCPAdminConsent (implements pact.MCPAdminConsent)
|
||||||
|
- New file controllers/mcp_connections.go: MCPConnectionsControllerID, PermissionManageMCPConnections, BackendModeAdminControllers, bulk action revoke; controllers/mcpconnections/config_list.yaml
|
||||||
|
- New file account.go: AccountContributions (section mcp_connections, item action revoke)
|
||||||
|
- Permission golem15.oauthserver.manage_mcp_connections; navigation side-menu entry mcp_connections
|
||||||
|
- Lang keys golem15.oauthserver::lang.account.*, mcp_connections.*, permissions.manage_mcp_connections
|
||||||
|
- Test helper bootBackendMode; smoke tests TestBackendModeSmoke, TestBackendRevocationSmoke, TestBackendAccountSmoke
|
||||||
@@ -0,0 +1,228 @@
|
|||||||
|
---
|
||||||
|
phase: 32.2
|
||||||
|
plan: 04
|
||||||
|
type: execute
|
||||||
|
wave: 3
|
||||||
|
depends_on: [32.2-02, 32.2-03]
|
||||||
|
files_modified:
|
||||||
|
- ../sm-grzybyfunkcjonalne-app/.gitmodules
|
||||||
|
- ../sm-grzybyfunkcjonalne-app/plugins/golem15/oauthserver
|
||||||
|
- ../sm-grzybyfunkcjonalne-app/go.work
|
||||||
|
- ../sm-grzybyfunkcjonalne-app/go.mod
|
||||||
|
- ../sm-grzybyfunkcjonalne-app/go.sum
|
||||||
|
- ../sm-grzybyfunkcjonalne-app/summer.yaml
|
||||||
|
- ../sm-grzybyfunkcjonalne-app/main.go
|
||||||
|
- ../sm-grzybyfunkcjonalne-app/plugins.gen.go
|
||||||
|
- ../sm-grzybyfunkcjonalne-app/scripts/build.sh
|
||||||
|
- ../sm-grzybyfunkcjonalne-app/config/golem15.oauthserver.yaml
|
||||||
|
- ../sm-grzybyfunkcjonalne-app/config/mcp.yaml
|
||||||
|
- ../sm-grzybyfunkcjonalne-app/boot_test.go
|
||||||
|
- ../sm-grzybyfunkcjonalne-app/scripts/smoke-mcp-oauth.sh
|
||||||
|
- ../sm-grzybyfunkcjonalne-app/deploy/nginx/grzybyfunkcjonalne-staging.conf
|
||||||
|
- ../sm-grzybyfunkcjonalne-app/deploy/nginx/grzybyfunkcjonalne-production.conf
|
||||||
|
- ../sm-grzybyfunkcjonalne-app/scripts/check-deploy.sh
|
||||||
|
- ../sm-grzybyfunkcjonalne-app/deploy/env.example
|
||||||
|
- ../sm-grzybyfunkcjonalne-app/DEPLOY.md
|
||||||
|
- ../sm-grzybyfunkcjonalne-app/README.md
|
||||||
|
autonomous: true
|
||||||
|
requirements: [SC-4, SC-5]
|
||||||
|
estimate:
|
||||||
|
tokens: 70000
|
||||||
|
raw_tokens: 70000
|
||||||
|
tasks: 2
|
||||||
|
confidence: low
|
||||||
|
must_haves:
|
||||||
|
truths:
|
||||||
|
- "SC-4, D-14: sm-grzybyfunkcjonalne-app mounts golem15.oauthserver (submodule plugins/golem15/oauthserver, summer.yaml, go.work use, go.mod require + replace) with config/golem15.oauthserver.yaml setting mcp.enabled true, mcp.subject backend, oidc.enabled false and a local mcp.resource equal to the /mcp resource of config/mcp.yaml; config/mcp.yaml keeps allow_personal_tokens true."
|
||||||
|
- "SC-4, D-14: on a local stack, scripts/smoke-mcp-oauth.sh completes, with no browser and no Nuxt: POST /mcp without a bearer answers 401 with resource_metadata; the protected-resource metadata lists journal and offline_access; the authorization-server metadata lists the MCP endpoints and /.well-known/openid-configuration answers 404; dynamic registration; PKCE authorize answers 302 to /gfadmin/connect?request=…; admin sign-in through POST /gfadmin/api/v1/auth/login with a cookie jar; GET and POST /gfadmin/api/v1/mcp/consent/{request}; code exchange; MCP initialize, notifications/initialized, tools/list containing journal_list_posts and tools/call journal_list_posts without isError; the same tools/list and call with a g15_ personal token; and after the administrator changes their password, the OAuth bearer answers 401."
|
||||||
|
- "SC-4, D-14: both nginx vhosts route exactly /.well-known/oauth-authorization-server (GET, HEAD) and ^~ /oauth/mcp/ (GET, POST) to the Go binary with auth_basic off and no add_header, next to the existing /mcp and protected-resource locations; scripts/check-deploy.sh requires them and the backend-mode config."
|
||||||
|
- "SC-5, D-14: DEPLOY.md's MCP section describes OAuth sign-in as an administrator (connector address, admin sign-in and consent, My account revoke, the oauthserver env keys, rollback) next to g15_ tokens, states the minimum sm-oauthserver-plugin version, and says the production deploy and the live Claude connector check happen separately on the user's go-ahead."
|
||||||
|
- "UI backstop (recorded, verified later): the SameSite=Strict admin cookie on a real cross-site connector redirect chain (D-03, RESEARCH assumption A2) cannot be proven on a localhost stack; DEPLOY.md lists the live check (add the connector in Claude, sign in, the consent card shows signed in rather than the login screen) for the deferred deploy. The phase VERIFICATION.md must list this check under human verification with status unverified (not passed, not failed), pointing at the DEPLOY.md note and the VALIDATION.md manual-only row; the local smoke passing does not close it."
|
||||||
|
artifacts:
|
||||||
|
- path: ../sm-grzybyfunkcjonalne-app/config/golem15.oauthserver.yaml
|
||||||
|
provides: "backend-mode, OIDC-off MCP authorization server config"
|
||||||
|
contains: "subject: backend"
|
||||||
|
- path: ../sm-grzybyfunkcjonalne-app/scripts/smoke-mcp-oauth.sh
|
||||||
|
provides: "local end-to-end OAuth proof"
|
||||||
|
contains: "mcp/consent"
|
||||||
|
- path: ../sm-grzybyfunkcjonalne-app/deploy/nginx/grzybyfunkcjonalne-production.conf
|
||||||
|
provides: "OAuth locations"
|
||||||
|
contains: "location ^~ /oauth/mcp/"
|
||||||
|
key_links:
|
||||||
|
- from: ../sm-grzybyfunkcjonalne-app/config/golem15.oauthserver.yaml mcp.resource
|
||||||
|
to: ../sm-grzybyfunkcjonalne-app/config/mcp.yaml (pier resource from app.url)
|
||||||
|
via: "equal resource string; production via SUMMER_GOLEM15__OAUTHSERVER__MCP__RESOURCE"
|
||||||
|
pattern: "resource"
|
||||||
|
- from: ../sm-grzybyfunkcjonalne-app/go.work
|
||||||
|
to: ../sm-grzybyfunkcjonalne-app/plugins/golem15/oauthserver
|
||||||
|
via: "use ./plugins/golem15/oauthserver and go.mod replace"
|
||||||
|
pattern: "plugins/golem15/oauthserver"
|
||||||
|
---
|
||||||
|
|
||||||
|
<objective>
|
||||||
|
User story (phase goal, ROADMAP 32.2): **As an** editor of a blog-only application whose MCP tools are backend-guarded (Journal) and which has no frontend users, **I want to** add the site's `/mcp` as a connector and sign in once as my administrator account over OAuth, **so that** agents no longer need a hand-copied `g15_` personal token.
|
||||||
|
|
||||||
|
Slice in this plan (the whole story on the first consumer's local stack): a scripted MCP client runs discovery, dynamic registration, admin sign-in, consent and a Journal tool call over OAuth, and a `g15_` token keeps working (scripts/smoke-mcp-oauth.sh). The real Claude connector on a cross-site redirect is the deferred live check (see the UI backstop truth).
|
||||||
|
|
||||||
|
SC-4 and the app half of SC-5 (D-14): the first consumer, sm-grzybyfunkcjonalne-app, mounts golem15.oauthserver in backend mode with only the MCP authorization server, routes the OAuth paths to Go, proves the whole flow on a local stack and documents it.
|
||||||
|
|
||||||
|
Purpose: editors of this blog-only site sign their agent in once as their administrator instead of pasting a g15_ token; g15_ tokens keep working.
|
||||||
|
Output: submodule and module wiring, the regenerated main.go and plugins.gen.go, the oauthserver config, a local proof script, nginx locations, the extended check-deploy.sh, env example and DEPLOY.md. The production deploy and a live Claude connector run are not part of this phase (CONTEXT Deferred).
|
||||||
|
|
||||||
|
⚠ spec-less probe fallback skipped: phase has no requirement IDs to probe (visible skip).
|
||||||
|
|
||||||
|
Submodule rule (CLAUDE.md, memory): the app may only point at plugin commits that are pushed, and the pointer bump to the release is its own commit after the plugin push (plan 05). So this plan adds the submodule at the commit origin/master already has, commits the wiring with that gitlink, and then moves only the submodule's working tree to the local plan 03 commits (fetched from the sibling checkout) for the proof, leaving that gitlink change uncommitted for plan 05. The SC-4 "Claude connector" wording is met by a scripted MCP client locally; the connector itself is the deferred live check.
|
||||||
|
</objective>
|
||||||
|
|
||||||
|
<execution_context>
|
||||||
|
@~/.claude/msd-core/workflows/execute-plan.md
|
||||||
|
@~/.claude/msd-core/templates/summary.md
|
||||||
|
</execution_context>
|
||||||
|
|
||||||
|
<context>
|
||||||
|
@.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-CONTEXT.md
|
||||||
|
@.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-RESEARCH.md
|
||||||
|
@.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-03-SUMMARY.md
|
||||||
|
@../sm-grzybyfunkcjonalne-app/summer.yaml
|
||||||
|
@../sm-grzybyfunkcjonalne-app/go.work
|
||||||
|
@../sm-grzybyfunkcjonalne-app/config/mcp.yaml
|
||||||
|
@../sm-grzybyfunkcjonalne-app/config/backend.yaml
|
||||||
|
@../sm-grzybyfunkcjonalne-app/scripts/build.sh
|
||||||
|
@../sm-grzybyfunkcjonalne-app/scripts/smoke.sh
|
||||||
|
@../sm-grzybyfunkcjonalne-app/scripts/check-deploy.sh
|
||||||
|
@../sm-grzybyfunkcjonalne-app/DEPLOY.md
|
||||||
|
@../sm-bm-app/config/golem15.oauthserver.yaml
|
||||||
|
|
||||||
|
<interfaces>
|
||||||
|
- golem15.oauthserver keys from plan 03: mcp.enabled, mcp.resource, mcp.subject (user|backend), mcp.consent_path (empty: <backend.uri>/connect in backend mode), oidc.enabled (default true); env SUMMER_GOLEM15__OAUTHSERVER__MCP__RESOURCE etc.
|
||||||
|
- Backend-mode routes: GET /.well-known/oauth-authorization-server, GET /oauth/mcp/authorize, POST /oauth/mcp/register, POST /oauth/mcp/token; pier: /mcp, /.well-known/oauth-protected-resource[/mcp]; cabana: {/gfadmin}/api/v1/auth/login (cookie set only with X-Requested-With), {/gfadmin}/api/v1/mcp/consent/{request} GET/POST, PUT {/gfadmin}/api/v1/account (password change)
|
||||||
|
- Journal token scopes: journal, journal:read; cabana scopes *, admin:read
|
||||||
|
- grzyby today: config/backend.yaml uri /gfadmin; config/mcp.yaml enabled, path /mcp, allow_personal_tokens true; summer.yaml build.tags [summercms_mcp, nodynamic]; nginx upstream 127.0.0.1:8096; a location ~ /\. dotfile rule answers 404 for unlisted /.well-known paths; scripts/check-deploy.sh fails on any add_header inside a location
|
||||||
|
- scripts/smoke.sh: throwaway database from SMOKE_ADMIN_DSN or a postgres:15 container, run migrate and admin:create (password on stdin), SUMMER_APP__URL=http://127.0.0.1:$GO_PORT
|
||||||
|
</interfaces>
|
||||||
|
</context>
|
||||||
|
|
||||||
|
<tasks>
|
||||||
|
|
||||||
|
<task type="tracer">
|
||||||
|
<name>Tracer: mount the OAuth server in backend mode and prove discovery → registration → admin sign-in → consent → Journal tool call locally</name>
|
||||||
|
<reversibility rating="reversible">App wiring and config; turning SUMMER_GOLEM15__OAUTHSERVER__MCP__ENABLED off or removing the plugin entry restores today's g15_-only MCP.</reversibility>
|
||||||
|
<precondition>docker info exits 0 (or SMOKE_ADMIN_DSN is set); 32.2-02-SUMMARY.md and 32.2-03-SUMMARY.md exist; `git -C /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin log --oneline -1` is a plan 03 commit; `git -C /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin status -sb` shows master tracking origin/master.</precondition>
|
||||||
|
<files>../sm-grzybyfunkcjonalne-app/.gitmodules, ../sm-grzybyfunkcjonalne-app/plugins/golem15/oauthserver, ../sm-grzybyfunkcjonalne-app/go.work, ../sm-grzybyfunkcjonalne-app/go.mod, ../sm-grzybyfunkcjonalne-app/go.sum, ../sm-grzybyfunkcjonalne-app/summer.yaml, ../sm-grzybyfunkcjonalne-app/main.go, ../sm-grzybyfunkcjonalne-app/plugins.gen.go, ../sm-grzybyfunkcjonalne-app/scripts/build.sh, ../sm-grzybyfunkcjonalne-app/config/golem15.oauthserver.yaml, ../sm-grzybyfunkcjonalne-app/config/mcp.yaml, ../sm-grzybyfunkcjonalne-app/boot_test.go, ../sm-grzybyfunkcjonalne-app/scripts/smoke-mcp-oauth.sh, ../sm-grzybyfunkcjonalne-app/README.md</files>
|
||||||
|
<read_first>
|
||||||
|
../sm-grzybyfunkcjonalne-app/.gitmodules (entry style: path, url git@git.golem15.com:golem15/<repo>.git, branch)
|
||||||
|
../sm-grzybyfunkcjonalne-app/go.work and go.mod (use list, require block, replace lines 192-206)
|
||||||
|
../sm-grzybyfunkcjonalne-app/summer.yaml (plugins list)
|
||||||
|
../sm-grzybyfunkcjonalne-app/scripts/build.sh (PLUGINS array; summer build drift check)
|
||||||
|
../sm-grzybyfunkcjonalne-app/scripts/smoke.sh (database setup lines 97-120 and 239-300, admin:create, serve and fail helpers)
|
||||||
|
../sm-grzybyfunkcjonalne-app/boot_test.go (TestBootUserTranslateJournal plugin lists at lines 38-66)
|
||||||
|
../sm-grzybyfunkcjonalne-app/config/mcp.yaml and config/backend.yaml
|
||||||
|
../sm-bm-app/config/golem15.oauthserver.yaml (header comment style)
|
||||||
|
../sm-oauthserver-plugin/README.md (backend-mode section from plan 03)
|
||||||
|
../sm-grzybyfunkcjonalne-app/README.md (plugin table)
|
||||||
|
</read_first>
|
||||||
|
<action>
|
||||||
|
Wiring (D-14): from ../sm-grzybyfunkcjonalne-app, git submodule add -b master git@git.golem15.com:golem15/sm-oauthserver-plugin.git plugins/golem15/oauthserver (it checks out the commit origin/master already has; do not push anything). Add ./plugins/golem15/oauthserver to go.work use; add git.golem15.com/golem15/sm-oauthserver-plugin to go.mod's require at the latest pushed tag and a replace to ./plugins/golem15/oauthserver next to the other plugin replaces; go mod tidy so go.sum is complete. Add - id: golem15.oauthserver with module git.golem15.com/golem15/sm-oauthserver-plugin to summer.yaml and the submodule path to the PLUGINS array of scripts/build.sh. Regenerate main.go and plugins.gen.go with summer build (install the CLI with GOBIN=<scratch dir> go -C /media/nvme/dev/golem15/summercms.io/summercms/summercms.go install ./cmd/summer, then run that binary's build from the app root). Add golem15.oauthserver to both plugin lists of boot_test.go. README.md: the plugin table names the oauthserver submodule and what it serves.
|
||||||
|
|
||||||
|
Config: new config/golem15.oauthserver.yaml with a header comment in the style of sm-bm-app's (what it serves, env overrides SUMMER_GOLEM15__OAUTHSERVER__<KEY>, no secret here, signing keys generated in the database), oidc.enabled false, mcp.enabled true, mcp.subject backend, consent_path left unset (defaults to /gfadmin/connect from backend.uri), and mcp.resource http://127.0.0.1:8096/mcp as the local default with a comment that production sets SUMMER_GOLEM15__OAUTHSERVER__MCP__RESOURCE and that it must equal the pier resource (<app.url>/mcp). config/mcp.yaml: change only its comments (OAuth sign-in as an administrator now exists next to personal tokens); keep the three lines enabled: true, path: /mcp and allow_personal_tokens: true exactly as they are (check-deploy.sh matches them).
|
||||||
|
|
||||||
|
Commit, in ../sm-grzybyfunkcjonalne-app only, staging these paths explicitly (.gitmodules, the plugins/golem15/oauthserver gitlink at the pushed commit, go.work, go.mod, go.sum, summer.yaml, main.go, plugins.gen.go, scripts/build.sh, config/golem15.oauthserver.yaml, config/mcp.yaml, boot_test.go, README.md). Then move only the submodule's working tree to the local plan 03 commits: git -C plugins/golem15/oauthserver fetch /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin master and check out FETCH_HEAD detached. Do not commit that gitlink change; plan 05 commits the release pointer after the plugin push. Leave the untracked .agents/, .gsd/, docs/ and sm-grzybyfunkcjonalne-app entries alone.
|
||||||
|
|
||||||
|
Proof script, new executable scripts/smoke-mcp-oauth.sh (bash, set -euo pipefail, curl, jq, openssl, psql; no new dependency), header comment in the style of scripts/smoke.sh: build the Go binary into a temp dir with go build -tags summercms_mcp,nodynamic (no Nuxt), create a throwaway database exactly like smoke.sh (SMOKE_ADMIN_DSN or a postgres:15 container, dropped on exit), run migrate, create a superuser administrator with a random password on stdin and a g15_ token with scope journal (the binary's admin:token:create command), serve on SMOKE_GO_PORT (default 18097) with SUMMER_APP__URL and SUMMER_GOLEM15__OAUTHSERVER__MCP__RESOURCE set to that port. Then, failing with a clear message at each step: 1) POST /mcp without bearer → 401 and a resource_metadata parameter; 2) GET /.well-known/oauth-protected-resource/mcp → authorization_servers and scopes_supported containing journal and offline_access; 3) GET /.well-known/oauth-authorization-server → authorization, registration and token endpoints under /oauth/mcp/, and GET /.well-known/openid-configuration → 404; 4) POST /oauth/mcp/register with redirect http://127.0.0.1:<port>/cb and token_endpoint_auth_method none; 5) PKCE verifier and S256 challenge with openssl; 6) GET /oauth/mcp/authorize with scope "journal offline_access" and resource → 302 whose Location is <app.url>/gfadmin/connect?request=<id>; 7) POST /gfadmin/api/v1/auth/login with X-Requested-With: XMLHttpRequest and a curl cookie jar; 8) GET /gfadmin/api/v1/mcp/consent/<id> (jar, X-Requested-With) shows journal; POST allow with scopes [journal] and offline_access true → redirect_uri with code and iss; 9) POST /oauth/mcp/token (code, verifier, redirect_uri, client_id, resource) → an access token and a refresh token; 10) MCP initialize, notifications/initialized, tools/list containing journal_list_posts, tools/call journal_list_posts with isError false; 11) the same tools/list and call with the g15_ token; 12) PUT /gfadmin/api/v1/account changing the administrator's password (jar, X-Requested-With) → a following tools/list with the OAuth bearer answers 401. Never echo tokens, codes or the password; print step names and status codes only. Commit the script by path.
|
||||||
|
</action>
|
||||||
|
<verify>
|
||||||
|
<automated>bash /media/nvme/dev/golem15/summercms.io/summercms/sm-grzybyfunkcjonalne-app/scripts/smoke-mcp-oauth.sh</automated>
|
||||||
|
<fails_when>non-zero exit, or the output lacks the final step-12 success line, or any step line reports an unexpected status code</fails_when>
|
||||||
|
<automated>go -C /media/nvme/dev/golem15/summercms.io/summercms/sm-grzybyfunkcjonalne-app vet -tags summercms_mcp,nodynamic ./... && go -C /media/nvme/dev/golem15/summercms.io/summercms/sm-grzybyfunkcjonalne-app test -count=1 -tags summercms_mcp,nodynamic ./...</automated>
|
||||||
|
<fails_when>non-zero exit, or a line contains FAIL</fails_when>
|
||||||
|
</verify>
|
||||||
|
<acceptance_criteria>
|
||||||
|
- .gitmodules has a plugins/golem15/oauthserver entry with url git@git.golem15.com:golem15/sm-oauthserver-plugin.git; the committed gitlink equals a commit that `git -C ../sm-oauthserver-plugin branch -r --contains <gitlink>` lists on origin/master.
|
||||||
|
- summer.yaml lists golem15.oauthserver; go.work uses ./plugins/golem15/oauthserver; go.mod has the replace.
|
||||||
|
- config/golem15.oauthserver.yaml contains `subject: backend` and an oidc block with `enabled: false`; config/mcp.yaml still contains the exact lines `enabled: true`, `path: /mcp`, `allow_personal_tokens: true`.
|
||||||
|
- `git -C ../sm-grzybyfunkcjonalne-app status --porcelain -- main.go plugins.gen.go` is empty after summer build.
|
||||||
|
- scripts/smoke-mcp-oauth.sh exits 0 with all twelve steps passing; piping its output through `grep -E 'oas_at_[A-Za-z0-9]|g15_[A-Za-z0-9]{8,}|code=[A-Za-z0-9]'` prints nothing.
|
||||||
|
- The app's vet and tagged tests pass (boot test includes golem15.oauthserver).
|
||||||
|
</acceptance_criteria>
|
||||||
|
<done>The site's MCP endpoint accepts an OAuth agent signed in as an administrator, locally, end to end, and g15_ tokens still work.</done>
|
||||||
|
</task>
|
||||||
|
|
||||||
|
<task type="auto">
|
||||||
|
<name>Proxy the OAuth paths to Go, guard them in check-deploy.sh, and document the deploy</name>
|
||||||
|
<reversibility rating="reversible">nginx locations and docs; removing the two locations sends the paths back to the dotfile rule and Nuxt.</reversibility>
|
||||||
|
<files>../sm-grzybyfunkcjonalne-app/deploy/nginx/grzybyfunkcjonalne-staging.conf, ../sm-grzybyfunkcjonalne-app/deploy/nginx/grzybyfunkcjonalne-production.conf, ../sm-grzybyfunkcjonalne-app/scripts/check-deploy.sh, ../sm-grzybyfunkcjonalne-app/deploy/env.example, ../sm-grzybyfunkcjonalne-app/DEPLOY.md</files>
|
||||||
|
<read_first>
|
||||||
|
../sm-grzybyfunkcjonalne-app/deploy/nginx/grzybyfunkcjonalne-staging.conf (lines 82-130 server headers and /gfadmin, 170-225 /mcp and protected-resource locations, 250-260 dotfile rule)
|
||||||
|
../sm-grzybyfunkcjonalne-app/deploy/nginx/grzybyfunkcjonalne-production.conf (same locations; keep in step)
|
||||||
|
../sm-grzybyfunkcjonalne-app/scripts/check-deploy.sh (header list, location checks at lines 230-320, config checks at lines 350-370)
|
||||||
|
../sm-grzybyfunkcjonalne-app/deploy/env.example
|
||||||
|
../sm-grzybyfunkcjonalne-app/DEPLOY.md (MCP section at line 411, Security headers at line 229, Release at line 249, Rollback)
|
||||||
|
../sm-bm-app/deploy/nginx/bm.jakubzych.com.conf (lines 97-110, an OAuth-enabled vhost)
|
||||||
|
</read_first>
|
||||||
|
<action>
|
||||||
|
nginx (D-14), both vhosts, next to the existing /mcp and protected-resource locations and with the same proxy headers they use: location = /.well-known/oauth-authorization-server (auth_basic off on staging, limit_except GET HEAD { deny all; }, proxy_pass http://127.0.0.1:8096) and location ^~ /oauth/mcp/ (auth_basic off on staging, limit_except GET POST { deny all; }, client_max_body_size 64k, proxy_pass http://127.0.0.1:8096). Exact and prefix locations keep the dotfile rule and Nuxt away from them. No add_header inside either (server-level security headers keep applying). Comment each with why (the connector fetches metadata, registers and exchanges tokens server-to-server; the browser leg of /oauth/mcp/authorize hands off to /gfadmin/connect, which /gfadmin already proxies). Do not add /.well-known/openid-configuration (OIDC is off; the dotfile rule answers 404).
|
||||||
|
|
||||||
|
check-deploy.sh: extend the header comment and the checks so each vhost must have both new locations with the method limits above and no add_header, config/golem15.oauthserver.yaml must contain subject: backend and the oidc enabled: false block, and summer.yaml must list golem15.oauthserver. Keep every existing check.
|
||||||
|
|
||||||
|
deploy/env.example: add SUMMER_GOLEM15__OAUTHSERVER__MCP__RESOURCE=https://<host>/mcp with a comment that it must equal <SUMMER_APP__URL>/mcp.
|
||||||
|
|
||||||
|
DEPLOY.md (SC-5): rewrite the MCP section's Auth paragraph: agents connect over OAuth as an administrator (connector address <site>/mcp; the browser signs in at /gfadmin with the usual login gates and shows the consent card; scopes are the g15_ token scopes; Stay connected gives a refresh token; each administrator revokes agents on My account and a superuser or a holder of golem15.oauthserver.manage_mcp_connections on the OAuth server's MCP connections screen; deleting, deactivating or re-passwording an administrator, or changing their role or permissions, ends their agents), and g15_ personal tokens keep working. Add the oauthserver env key, the nginx locations, the migration note (migrate creates the golem15_oauthserver_* tables on the first run), the minimum sm-oauthserver-plugin version (the release plan 05 tags; write it as "the plugin release that adds mcp.subject"), scripts/smoke-mcp-oauth.sh as the local check, and rollback (SUMMER_GOLEM15__OAUTHSERVER__MCP__ENABLED=false and a Go restart; g15_ tokens keep working). Add a "Live connector check (deferred)" note: after the production deploy, on the user's go-ahead, add the connector in Claude and sign in; the consent card must show the signed-in administrator, not the login screen, after the cross-site redirect (SameSite=Strict cookie; not provable on localhost). Commit these files by path in the app repo.
|
||||||
|
</action>
|
||||||
|
<verify>
|
||||||
|
<automated>bash /media/nvme/dev/golem15/summercms.io/summercms/sm-grzybyfunkcjonalne-app/scripts/check-deploy.sh</automated>
|
||||||
|
<fails_when>non-zero exit, or a line starting with `check-deploy:` reports a failure, or nginx -t output contains `emerg`</fails_when>
|
||||||
|
</verify>
|
||||||
|
<acceptance_criteria>
|
||||||
|
- `grep -c 'location = /.well-known/oauth-authorization-server' ../sm-grzybyfunkcjonalne-app/deploy/nginx/grzybyfunkcjonalne-staging.conf` and the same for the production vhost are 1; `grep -c 'location ^~ /oauth/mcp/'` is 1 in each.
|
||||||
|
- check-deploy.sh passes and names the new locations in its header comment.
|
||||||
|
- DEPLOY.md's MCP section mentions /gfadmin/connect, My account, golem15.oauthserver.manage_mcp_connections, SUMMER_GOLEM15__OAUTHSERVER__MCP__RESOURCE, scripts/smoke-mcp-oauth.sh and the deferred live connector check.
|
||||||
|
- deploy/env.example contains SUMMER_GOLEM15__OAUTHSERVER__MCP__RESOURCE.
|
||||||
|
</acceptance_criteria>
|
||||||
|
<done>The deployed site will route the OAuth paths to Go, the deploy checker guards them, and DEPLOY.md tells the operator how to run, check and roll back administrator OAuth.</done>
|
||||||
|
</task>
|
||||||
|
|
||||||
|
</tasks>
|
||||||
|
|
||||||
|
<threat_model>
|
||||||
|
## Trust Boundaries
|
||||||
|
|
||||||
|
| Boundary | Description |
|
||||||
|
|----------|-------------|
|
||||||
|
| Internet → nginx → Go | New public OAuth endpoints on a site that had none |
|
||||||
|
| Local proof script → logs | Tokens, codes and a password exist during the run |
|
||||||
|
|
||||||
|
## STRIDE Threat Register
|
||||||
|
|
||||||
|
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|
||||||
|
|-----------|----------|-----------|----------|-------------|-----------------|
|
||||||
|
| T-32.2-22 | Elevation of privilege | OIDC provider surface | medium | mitigate | oidc.enabled false in config/golem15.oauthserver.yaml and no nginx location for OIDC paths; the smoke asserts /.well-known/openid-configuration is 404 |
|
||||||
|
| T-32.2-23 | Denial of service | /oauth/mcp/register and /token | medium | mitigate | Plugin throttles (BucketMCPRegister, BucketMCPToken) and the DCR client cap stay on; nginx limits methods and body size (64k) |
|
||||||
|
| T-32.2-24 | Information disclosure | smoke-mcp-oauth.sh output | medium | mitigate | Print step names and status codes only; acceptance checks the output for oas_at_, g15_ and code= values |
|
||||||
|
| T-32.2-25 | Tampering | security headers | low | mitigate | No add_header in the new locations, so server-level headers apply; check-deploy.sh enforces it |
|
||||||
|
| T-32.2-SC | Tampering | go module installs | low | accept | Only the first-party sm-oauthserver-plugin is added, as a submodule of the organisation's repository |
|
||||||
|
</threat_model>
|
||||||
|
|
||||||
|
<verification>
|
||||||
|
scripts/smoke-mcp-oauth.sh passes all twelve steps; the app's go vet and tagged go test pass; scripts/check-deploy.sh passes; summer build leaves main.go and plugins.gen.go unchanged.
|
||||||
|
|
||||||
|
Human verification, open after this phase (unverified, not a failure): the D-03 SameSite=Strict cookie on a real cross-site connector redirect chain (RESEARCH A2). The local stack is same-site, so the smoke cannot prove it. It stays open until the live connector check in DEPLOY.md runs after the deferred production deploy, and VERIFICATION.md lists it as such.
|
||||||
|
</verification>
|
||||||
|
|
||||||
|
<success_criteria>
|
||||||
|
- SC-4: local proof of discovery, registration, administrator sign-in, consent and a Journal tool call over OAuth, with g15_ tokens still working (D-14).
|
||||||
|
- SC-5: DEPLOY.md, env example and check-deploy updated; production deploy explicitly deferred.
|
||||||
|
</success_criteria>
|
||||||
|
|
||||||
|
<output>
|
||||||
|
Create `.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-04-SUMMARY.md` when done.
|
||||||
|
</output>
|
||||||
|
|
||||||
|
## Artifacts this phase produces
|
||||||
|
|
||||||
|
Plan 04 (sm-grzybyfunkcjonalne-app):
|
||||||
|
- Submodule plugins/golem15/oauthserver (.gitmodules entry, gitlink at the pushed origin/master commit; working tree at the local plan 03 commits, uncommitted)
|
||||||
|
- summer.yaml plugin entry golem15.oauthserver; go.work use ./plugins/golem15/oauthserver; go.mod require + replace git.golem15.com/golem15/sm-oauthserver-plugin => ./plugins/golem15/oauthserver; regenerated main.go and plugins.gen.go; scripts/build.sh PLUGINS entry
|
||||||
|
- New file config/golem15.oauthserver.yaml (oidc.enabled false, mcp.enabled true, mcp.subject backend, mcp.resource local default)
|
||||||
|
- New file scripts/smoke-mcp-oauth.sh (twelve-step local OAuth proof, env SMOKE_ADMIN_DSN, SMOKE_GO_PORT)
|
||||||
|
- nginx locations `= /.well-known/oauth-authorization-server` and `^~ /oauth/mcp/` in both vhosts; check-deploy.sh checks for them and for the backend-mode config
|
||||||
|
- deploy/env.example key SUMMER_GOLEM15__OAUTHSERVER__MCP__RESOURCE; DEPLOY.md MCP section with the deferred live connector check
|
||||||
@@ -0,0 +1,350 @@
|
|||||||
|
---
|
||||||
|
phase: 32.2
|
||||||
|
plan: 05
|
||||||
|
type: execute
|
||||||
|
wave: 4
|
||||||
|
depends_on: [32.2-01, 32.2-02, 32.2-03, 32.2-04]
|
||||||
|
files_modified:
|
||||||
|
- modules/wristband/consent_path_test.go
|
||||||
|
- modules/pier/backend_only_grant_test.go
|
||||||
|
- modules/cabana/token_scope_names_test.go
|
||||||
|
- modules/cabana/mcp_admin_consent_test.go
|
||||||
|
- modules/cabana/account_items_test.go
|
||||||
|
- modules/cabana/backend_access_revoked_test.go
|
||||||
|
- admin/tests/views/ConnectView.test.ts
|
||||||
|
- admin/tests/app/router.test.ts
|
||||||
|
- admin/tests/views/LoginView.test.ts
|
||||||
|
- admin/tests/account/AccountContributions.test.ts
|
||||||
|
- ../sm-oauthserver-plugin/backend_tools_test.go
|
||||||
|
- ../sm-oauthserver-plugin/backend_mode_test.go
|
||||||
|
- ../sm-oauthserver-plugin/backend_consent_test.go
|
||||||
|
- ../sm-oauthserver-plugin/backend_subject_migration_test.go
|
||||||
|
- ../sm-oauthserver-plugin/backend_grant_rows_test.go
|
||||||
|
- ../sm-oauthserver-plugin/backend_revoke_test.go
|
||||||
|
- ../sm-oauthserver-plugin/go.mod
|
||||||
|
- ../sm-oauthserver-plugin/go.sum
|
||||||
|
- ../sm-oauthserver-plugin/plugin.yaml
|
||||||
|
- ../sm-grzybyfunkcjonalne-app/plugins/golem15/oauthserver
|
||||||
|
- ../sm-grzybyfunkcjonalne-app/go.mod
|
||||||
|
- ../sm-grzybyfunkcjonalne-app/go.sum
|
||||||
|
- .planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-05-release-decision.txt
|
||||||
|
- .planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-05-changelog-framework.md
|
||||||
|
- .planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-05-changelog-plugin.md
|
||||||
|
- .planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-05-changelog-published.txt
|
||||||
|
autonomous: false
|
||||||
|
requirements: [SC-1, SC-2, SC-3, SC-4, SC-5]
|
||||||
|
estimate:
|
||||||
|
tokens: 115000
|
||||||
|
raw_tokens: 115000
|
||||||
|
tasks: 5
|
||||||
|
confidence: low
|
||||||
|
must_haves:
|
||||||
|
truths:
|
||||||
|
- "SC-1, SC-2 (D-01, D-09): TestBackendGrantToolsMatchPersonalToken proves end to end in the plugin harness (Docker, summercms_mcp tag) that an administrator who consents over OAuth with a plugin scope's read variant lists only read-only tools, with the full scope lists write tools, and in both cases sees exactly the tool set a g15_ token with the same scopes sees, and that a tool call succeeds."
|
||||||
|
- "SC-1 (D-04): TestAuthorizeConsentPath and TestAuthorizeDefaultScopes lock the default handoff {issuer}/connect?request= and the read fallback, and the set values."
|
||||||
|
- "SC-2 (D-01, D-09): TestBackendOnlyGrant proves no frontend subject, no linked-backend lookup, distinct bindings for two administrators of one client, ceiling off, ScopeLimited true, refusal of malformed backend grants and a fingerprint change on ScopeLimited; TestLinkedGrantNoScopeLimit proves a user-mode linked grant still gets no scope limit."
|
||||||
|
- "SC-1 (D-03, D-09, D-11): TestMCPAdminConsent covers 401, 403 interactive_only, missing X-Requested-With, 404 without provider and for ErrMCPConsentNotFound, hidden scopes, dropped unknown and ungrantable scopes, the * collapse, 422 no_grantable_scopes, deny, offline_access only when requested, unknown body fields and the body cap; TestTokenScopeNames locks catalog order and labels."
|
||||||
|
- "SC-3 (D-12, D-13): TestAccountContributionItems covers null versus empty items, permission-filtered item actions, the items error flag, 403, both 404 paths and compile refusals; TestBackendAccessRevokedEvent covers all seven D-13 sites including admin:reset-password and role permission changes for holders, de-duplicated ids, rollback on listener error, no event for unrelated edits, and the unchanged after-commit MCPSubjectChanged."
|
||||||
|
- "SC-1, SC-3 (D-02, D-07, D-08, D-10, D-12, D-13): the plugin tests TestBackendMode, TestBackendConsent, TestBackendSubjectMigration, TestBackendGrantRows, TestBackendRevokeFromAccount and TestBackendCascade pass in Docker; the full plugin suite, the framework suite, the admin suites, the grzyby smoke and check-deploy, and sm-bm-app's tests against the new plugin through a scratch go.work all pass with user mode unchanged."
|
||||||
|
- "SC-5: tags, pushes and changelog posts happen only after the blocking release checkpoint records tag-and-publish: the framework gets the next free v0.6 patch on master containing every earlier tag, the plugin gets v0.1.8 after its go.mod requires that framework tag, the plugin is pushed before the app's pointer bump, which is its own commit, and each tag gets its changelog post the same day; no deploy."
|
||||||
|
- { statement: "UI backstop — the consent * rule: ticking * disables and clears the other scopes and shows the scope_all_includes note, the POST body is ['*'], and unticking re-enables them (ConnectView.test.ts)", verification: backstop }
|
||||||
|
- { statement: "UI backstop — no auto-allow and the decision navigation: 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 (ConnectView.test.ts)", verification: backstop }
|
||||||
|
- { statement: "UI backstop — the switch account round trip: 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 (ConnectView.test.ts, router.test.ts)", verification: backstop }
|
||||||
|
- { statement: "UI backstop — account contribution items back-compat: a section without items renders exactly as before, items [] renders the empty block, and an item action runs the confirm with :title filled (AccountContributions.test.ts)", verification: backstop }
|
||||||
|
- { statement: "UI backstop — the D-03 SameSite=Strict cookie on a real cross-site connector redirect chain (RESEARCH A2) is not provable on localhost; it is routed to the live connector check DEPLOY.md lists for the deferred production deploy. VERIFICATION.md lists it under human verification with status unverified (not passed), and no test in this plan claims to cover it", verification: backstop }
|
||||||
|
artifacts:
|
||||||
|
- path: ../sm-oauthserver-plugin/backend_tools_test.go
|
||||||
|
provides: "OAuth administrator grant tools equal a g15_ token's tools"
|
||||||
|
contains: "TestBackendGrantToolsMatchPersonalToken"
|
||||||
|
- path: modules/pier/backend_only_grant_test.go
|
||||||
|
provides: "pier backend-only grant and linked-grant regression"
|
||||||
|
contains: "TestBackendOnlyGrant"
|
||||||
|
- path: modules/cabana/backend_access_revoked_test.go
|
||||||
|
provides: "all D-13 sites"
|
||||||
|
contains: "TestBackendAccessRevokedEvent"
|
||||||
|
- path: admin/tests/views/ConnectView.test.ts
|
||||||
|
provides: "consent screen unit tests and UI backstops"
|
||||||
|
contains: "window.location.assign"
|
||||||
|
- path: .planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-05-release-decision.txt
|
||||||
|
provides: "checkpoint record read by the release verify"
|
||||||
|
key_links:
|
||||||
|
- from: ../sm-oauthserver-plugin/backend_tools_test.go
|
||||||
|
to: "pier tools/list through the published verifier"
|
||||||
|
via: "real authorize, admin consent, token exchange and /mcp calls"
|
||||||
|
pattern: "tools/list"
|
||||||
|
- from: release task
|
||||||
|
to: 32.2-05-release-decision.txt
|
||||||
|
via: "first line hold or tag-and-publish, then base tags"
|
||||||
|
pattern: "tag-and-publish"
|
||||||
|
---
|
||||||
|
|
||||||
|
<objective>
|
||||||
|
User story (phase goal, ROADMAP 32.2): **As an** editor of a blog-only application whose MCP tools are backend-guarded (Journal) and which has no frontend users, **I want to** add the site's `/mcp` as a connector and sign in once as my administrator account over OAuth, **so that** agents no longer need a hand-copied `g15_` personal token.
|
||||||
|
|
||||||
|
Slice in this plan (the "so that" part of the story): an OAuth agent and a `g15_` token with equal scopes see and call the same tools (TestBackendGrantToolsMatchPersonalToken). The rest of the plan is the unit tests, the regression runs that show user mode is unchanged, and the gated release.
|
||||||
|
|
||||||
|
Last plan of the phase (project rule: unit tests are the last plan): the Validation Architecture tests for SC-1 to SC-4 across summercms.go, the admin SPA and sm-oauthserver-plugin, regression runs proving user mode is unchanged (framework, plugin, grzyby, sm-bm-app through a scratch go.work), then a blocking human checkpoint before any tag, push or changelog post (SC-5).
|
||||||
|
|
||||||
|
Purpose: plans 01 to 04 carry smoke tests only; this plan proves every behaviour, including the five UI backstops, and keeps releasing behind the user's go-ahead.
|
||||||
|
Output: test files in three repos, recorded regression runs, and, only if the checkpoint says so, the framework patch tag, sm-oauthserver-plugin v0.1.8, the grzyby pointer bump commit and the two changelog posts.
|
||||||
|
|
||||||
|
⚠ spec-less probe fallback skipped: phase has no requirement IDs to probe (visible skip).
|
||||||
|
|
||||||
|
Do not deploy anything. Do not hardcode the framework version: compute it from tags at release time (memory: next free patch, never a minor bump without the user's word; tags only on master; each tag contains all earlier tags).
|
||||||
|
</objective>
|
||||||
|
|
||||||
|
<execution_context>
|
||||||
|
@~/.claude/msd-core/workflows/execute-plan.md
|
||||||
|
@~/.claude/msd-core/templates/summary.md
|
||||||
|
</execution_context>
|
||||||
|
|
||||||
|
<context>
|
||||||
|
@.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-CONTEXT.md
|
||||||
|
@.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-VALIDATION.md
|
||||||
|
@.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-UI-SPEC.md
|
||||||
|
@.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-01-SUMMARY.md
|
||||||
|
@.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-02-SUMMARY.md
|
||||||
|
@.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-03-SUMMARY.md
|
||||||
|
@.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-04-SUMMARY.md
|
||||||
|
@modules/pier/backend_subject_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
|
||||||
|
@admin/tests/smoke/connect.smoke.test.ts
|
||||||
|
@../sm-oauthserver-plugin/harness_test.go
|
||||||
|
@../sm-oauthserver-plugin/backend_mode_smoke_test.go
|
||||||
|
@../sm-oauthserver-plugin/testmain_test.go
|
||||||
|
</context>
|
||||||
|
|
||||||
|
<tasks>
|
||||||
|
|
||||||
|
<task type="tracer">
|
||||||
|
<name>Tracer: an OAuth administrator grant and a g15_ token with equal scopes see and call the same tools</name>
|
||||||
|
<reversibility rating="reversible">Tests only.</reversibility>
|
||||||
|
<precondition>docker info exits 0; plans 01-04 SUMMARY files exist.</precondition>
|
||||||
|
<files>../sm-oauthserver-plugin/backend_tools_test.go</files>
|
||||||
|
<read_first>
|
||||||
|
../sm-oauthserver-plugin/harness_test.go (bootBackendMode, env.admin, adminCall)
|
||||||
|
../sm-oauthserver-plugin/backend_mode_smoke_test.go (authorize → admin consent → token flow)
|
||||||
|
../sm-oauthserver-plugin/testmain_test.go (Docker skip under testing.Short with flag.Parse)
|
||||||
|
/media/nvme/dev/golem15/summercms.io/summercms/summercms.go/modules/pier/backend_subject_smoke_test.go (MCP initialize/tools/list helpers)
|
||||||
|
/media/nvme/dev/golem15/summercms.io/summercms/summercms.go/modules/surf/pier_on.go (pier is linked only with -tags summercms_mcp)
|
||||||
|
</read_first>
|
||||||
|
<action>
|
||||||
|
New ../sm-oauthserver-plugin/backend_tools_test.go with build constraint //go:build summercms_mcp, TestBackendGrantToolsMatchPersonalToken (Docker; skip under testing.Short()). Boot backend mode with pier enabled (mcp.enabled, allow_personal_tokens true) and a test fixture plugin declaring TokenScopes acme and acme:read and backend-guarded admin routes exposed as MCP tools: one read-only, one write (copy the fixture style of the framework's pier Docker tests; do not depend on any app plugin). For an administrator holding the fixture permissions: connect over OAuth (DCR, PKCE authorize, cabana consent with [acme:read], token exchange) and list tools: only the read-only tool; call it: success. Connect a second client with [acme]: both tools listed, the write call succeeds. Create g15_ tokens with [acme:read] and [acme] through cabana and assert their tools/list results equal the OAuth ones name for name (D-09: an OAuth agent and a g15_ token with equal scopes see the same tools). Revoke one OAuth client from My account and assert its next call answers 401 while the other client still works. Never print tokens or codes. Commit in the plugin repo by path.
|
||||||
|
</action>
|
||||||
|
<verify>
|
||||||
|
<automated>go -C /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin test -count=1 -timeout 600s -tags summercms_mcp -run 'TestBackendGrantToolsMatchPersonalToken' -v .</automated>
|
||||||
|
<fails_when>non-zero exit, or a line contains FAIL, or `[no tests to run]`, or `--- SKIP: TestBackendGrantToolsMatchPersonalToken`, or no `--- PASS: TestBackendGrantToolsMatchPersonalToken` line</fails_when>
|
||||||
|
</verify>
|
||||||
|
<acceptance_criteria>
|
||||||
|
- backend_tools_test.go starts with `//go:build summercms_mcp`.
|
||||||
|
- TestBackendGrantToolsMatchPersonalToken has a PASS line and asserts OAuth and g15_ tool lists are equal for both scope sets.
|
||||||
|
- No production file is in this commit.
|
||||||
|
</acceptance_criteria>
|
||||||
|
<done>SC-1 and SC-2 are proven end to end through the real authorization server, the admin consent API and pier.</done>
|
||||||
|
</task>
|
||||||
|
|
||||||
|
<task type="auto">
|
||||||
|
<name>Framework and admin SPA unit tests</name>
|
||||||
|
<reversibility rating="reversible">Tests only.</reversibility>
|
||||||
|
<precondition>docker info exits 0; admin/node_modules exists.</precondition>
|
||||||
|
<files>modules/wristband/consent_path_test.go, modules/pier/backend_only_grant_test.go, modules/cabana/token_scope_names_test.go, modules/cabana/mcp_admin_consent_test.go, modules/cabana/account_items_test.go, modules/cabana/backend_access_revoked_test.go, admin/tests/views/ConnectView.test.ts, admin/tests/app/router.test.ts, admin/tests/views/LoginView.test.ts, admin/tests/account/AccountContributions.test.ts</files>
|
||||||
|
<read_first>
|
||||||
|
modules/wristband/consent_path_smoke_test.go, modules/pier/backend_subject_smoke_test.go, modules/pier/export_test.go, modules/pier/helpers_test.go
|
||||||
|
modules/cabana/mcp_consent_smoke_test.go, account_items_smoke_test.go, backend_access_revoked_smoke_test.go, scope_limit_for_test.go
|
||||||
|
admin/tests/smoke/connect.smoke.test.ts, admin/tests/smoke/account-items.smoke.test.ts, admin/tests/app/router.test.ts, admin/tests/views/LoginView.test.ts, admin/tests/account/AccountContributions.test.ts
|
||||||
|
.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-UI-SPEC.md (C1-C3, UI Considerations backstop rows)
|
||||||
|
</read_first>
|
||||||
|
<action>
|
||||||
|
Go (summercms.go), extending the plan 01 smokes, never weakening them:
|
||||||
|
modules/wristband/consent_path_test.go: TestAuthorizeConsentPath (empty path byte-identical {issuer}/connect?request=<escaped id>; a set path; an issuer with a path segment) and TestAuthorizeDefaultScopes (absent, empty and identity-only scope values fall back to DefaultScopes; DefaultScopes entries outside the allowed set are dropped; empty DefaultScopes keeps read; an explicit scope is not replaced).
|
||||||
|
modules/pier/backend_only_grant_test.go (package pier for the unexported fields): TestBackendOnlyGrant (frontend guard registered but Frontend nil; a fake MCPLinkedBackendResolver records zero calls; bindings oauth:backend:c1:7 and oauth:backend:c1:8 differ; writes() true; ScopeLimited true; Subject backend with UserID non-zero, and with BackendUserID 0, answer ErrUnauthorized; fingerprint differs when only ScopeLimited differs) and TestLinkedGrantNoScopeLimit (Docker: a user-mode grant with the backend scope and a matching consented link reaches the backend guard with principal.Scope nil, as before).
|
||||||
|
modules/cabana/token_scope_names_test.go: TestTokenScopeNames (order *, admin:read, plugin scopes in plugin order; works before Activate; TokenScopeLabels translates and passes unknown names through).
|
||||||
|
modules/cabana/mcp_admin_consent_test.go: TestMCPAdminConsent (Docker) with the cases of the SC-1 truth above, a 16 KiB+ body refused and a fake provider asserting the exact Decide arguments.
|
||||||
|
modules/cabana/account_items_test.go: TestAccountContributionItems (Docker) with the cases of the SC-3 truth above; Run sees a transaction through TxFromContext.
|
||||||
|
modules/cabana/backend_access_revoked_test.go: TestBackendAccessRevokedEvent (Docker): each of the seven sites (delete, deactivate, password set by another admin, own password change, admin:reset-password through the command, role/own permissions/superuser change, a role's permission change firing once with every holder) records the right reason and ids with a non-nil Tx; a listener error rolls back the delete and the role save; a name-only edit fires nothing; the after-commit MCPSubjectChanged emissions still happen.
|
||||||
|
|
||||||
|
Admin vitest: admin/tests/views/ConnectView.test.ts covering every C1 state, the * rule, no auto-allow, Allow and Deny bodies, window.location.assign with the server URI and never the router, forbidden schemes as submit failures, Use another account (logout then login with redirect), 401 → expireSession, 404 on submit → Expired, focus moving to the state heading, and the currentUser fallback; extend router.test.ts (anonymous /connect?request=x → login with redirect=/connect?request=x; safeRedirect accepts it), LoginView.test.ts (the hint only for a /connect redirect) and AccountContributions.test.ts (null items unchanged, [] empty block, item rows and action buttons, confirm with :title, 404 item_gone toast plus reload, 409 action_stale). Commit Go tests and admin tests by path in the framework repo; no production file changes unless a test exposes a bug, in which case fix it in its own commit and say so in the SUMMARY.
|
||||||
|
</action>
|
||||||
|
<verify>
|
||||||
|
<automated>go test -count=1 -run 'TestAuthorizeConsentPath|TestAuthorizeDefaultScopes|TestBackendOnlyGrant|TestLinkedGrantNoScopeLimit|TestTokenScopeNames|TestMCPAdminConsent$|TestAccountContributionItems|TestBackendAccessRevokedEvent' -v ./modules/wristband ./modules/pier ./modules/cabana</automated>
|
||||||
|
<fails_when>non-zero exit, or any `--- FAIL` or `--- SKIP` line, or `[no tests to run]`, or fewer than eight distinct top-level `--- PASS: Test` lines for the eight names</fails_when>
|
||||||
|
<automated>npm --prefix admin run typecheck && npm --prefix admin run test -- tests/views/ConnectView.test.ts tests/app/router.test.ts tests/views/LoginView.test.ts tests/account/AccountContributions.test.ts</automated>
|
||||||
|
<fails_when>non-zero exit, or the vitest summary shows a failed test, or `No test files found`, or ConnectView.test.ts is absent from the run output</fails_when>
|
||||||
|
</verify>
|
||||||
|
<acceptance_criteria>
|
||||||
|
- All eight Go test names have a PASS line and none is skipped.
|
||||||
|
- ConnectView.test.ts exists and contains tests for the * rule, no auto-allow, the switch round trip and forbidden schemes (the four ConnectView/router backstops).
|
||||||
|
- AccountContributions.test.ts contains the back-compat case (null items render exactly as before) and the :title confirm case.
|
||||||
|
- The four admin test files pass under vitest.
|
||||||
|
</acceptance_criteria>
|
||||||
|
<done>SC-1, SC-2 and SC-3 framework and SPA behaviour is locked by unit tests, including the UI backstops.</done>
|
||||||
|
</task>
|
||||||
|
|
||||||
|
<task type="auto">
|
||||||
|
<name>Plugin unit tests and the cross-repo regression runs</name>
|
||||||
|
<reversibility rating="reversible">Tests and read-only regression runs; the scratch go.work lives in a temp dir.</reversibility>
|
||||||
|
<precondition>docker info exits 0; /media/nvme/dev/golem15/summercms.io/summercms/sm-bm-app/go.work exists.</precondition>
|
||||||
|
<files>../sm-oauthserver-plugin/backend_mode_test.go, ../sm-oauthserver-plugin/backend_consent_test.go, ../sm-oauthserver-plugin/backend_subject_migration_test.go, ../sm-oauthserver-plugin/backend_grant_rows_test.go, ../sm-oauthserver-plugin/backend_revoke_test.go</files>
|
||||||
|
<read_first>
|
||||||
|
../sm-oauthserver-plugin/backend_mode_smoke_test.go, backend_revocation_smoke_test.go, backend_account_smoke_test.go (plan 03 smokes)
|
||||||
|
../sm-oauthserver-plugin/mcp_backfill_test.go (migration test pattern: migrate twice, rollback)
|
||||||
|
../sm-oauthserver-plugin/mcp_revocation_test.go and cascade_test.go (revocation assertions)
|
||||||
|
/media/nvme/dev/golem15/summercms.io/summercms/sm-bm-app/go.work (use list for the scratch copy)
|
||||||
|
</read_first>
|
||||||
|
<action>
|
||||||
|
Plugin tests (Docker, not -short), in ../sm-oauthserver-plugin: backend_mode_test.go TestBackendMode (boot refusals: unknown mcp.subject, backend with mcp.enabled false, backend with mcp_scopes; backend mode: /oauth/mcp/requests/{request} 404, OIDC routes 404 with oidc.enabled false and present with oidc.enabled true, the authorized-apps rule, mcp.consent_path override, metadata scopes_supported = catalog plus offline_access, a no-scope request yields the catalog names; user mode: handoff still {issuer}/connect and scopes unchanged). backend_consent_test.go TestBackendConsent (allow and deny through cabana's endpoint; the consent row is replaced, never merged; consent_required false once covered; another administrator's issued request answers 404; a frontend user's JWT cannot reach the admin consent). backend_subject_migration_test.go TestBackendSubjectMigration (columns nullable and the partial unique index exist after migrate; the CHECK refuses an access token row with user_id 0 and no backend_user_id; rollback deletes backend rows and restores NOT NULL; migrate again succeeds). backend_grant_rows_test.go TestBackendGrantRows (code, access, refresh and consent rows have user_id NULL and backend_user_id; refresh rotation keeps the shape; replaying a rotated backend refresh token revokes the family; a user-mode grant in a user-mode boot is byte-for-byte as before). backend_revoke_test.go TestBackendRevokeFromAccount (only the chosen client revoked, one revoked event with that ClientID, cross-admin 404) and TestBackendCascade (each D-13 trigger revokes and fires one event per client; with the listener disabled the verifier still refuses a token issued before tokens_valid_after, sleeping past the two-second cutoff window of RESEARCH Pitfall 8; user rows and user-mode linked grants untouched). Commit by path in the plugin repo.
|
||||||
|
|
||||||
|
Regression runs, recorded in the SUMMARY with pass counts: the framework suite and MCP-tagged pier/surf; the full plugin suite with and without -tags summercms_mcp; admin typecheck, test and test:browser plus check-admin-openapi.sh --check and check-admin-dist.sh; docs; in ../sm-grzybyfunkcjonalne-app scripts/smoke-mcp-oauth.sh, scripts/check-deploy.sh and the tagged go test; sm-bm-app against the new plugin through a scratch go.work: copy sm-bm-app/go.work to a mktemp -d directory with every use path made absolute under /media/nvme/dev/golem15/summercms.io/summercms/sm-bm-app except plugins/golem15/oauthserver, which points at /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin, and an absolute summercms replace; run with GOWORK set to it. Do not edit sm-bm-app or sm-demo-app.
|
||||||
|
</action>
|
||||||
|
<verify>
|
||||||
|
<automated>go -C /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin test -count=1 -timeout 900s -run 'TestBackendMode$|TestBackendConsent|TestBackendSubjectMigration|TestBackendGrantRows|TestBackendRevokeFromAccount|TestBackendCascade' -v .</automated>
|
||||||
|
<fails_when>non-zero exit, or any `--- FAIL` or `--- SKIP` line, or `[no tests to run]`, or fewer than six top-level `--- PASS: TestBackend` lines</fails_when>
|
||||||
|
<automated>go vet ./... && go test -count=1 ./... && go test -count=1 -tags summercms_mcp ./modules/pier ./modules/surf && go -C /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin test -count=1 -timeout 900s ./... && go -C /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin test -count=1 -timeout 900s -tags summercms_mcp ./...</automated>
|
||||||
|
<fails_when>non-zero exit, or a line contains FAIL</fails_when>
|
||||||
|
<automated>npm --prefix admin run typecheck && npm --prefix admin run test && npm --prefix admin run test:browser && scripts/check-admin-openapi.sh --check && scripts/check-admin-dist.sh && go test ./cmd/summer -run TestDocsTree -count=1 && go run ./cmd/summer docs:build --check</automated>
|
||||||
|
<fails_when>non-zero exit, or a vitest summary shows a failed test, or check-admin-dist prints `stale`, or docs:build prints a problem line</fails_when>
|
||||||
|
<automated>bash /media/nvme/dev/golem15/summercms.io/summercms/sm-grzybyfunkcjonalne-app/scripts/smoke-mcp-oauth.sh && bash /media/nvme/dev/golem15/summercms.io/summercms/sm-grzybyfunkcjonalne-app/scripts/check-deploy.sh && go -C /media/nvme/dev/golem15/summercms.io/summercms/sm-grzybyfunkcjonalne-app test -count=1 -tags summercms_mcp,nodynamic ./...</automated>
|
||||||
|
<fails_when>non-zero exit, or a line contains FAIL, or the smoke output lacks its final step line</fails_when>
|
||||||
|
<automated>W="$(mktemp -d)" && B=/media/nvme/dev/golem15/summercms.io/summercms/sm-bm-app && sed -e "s#^\t\.\$#\t$B#" -e "s#^\t\./plugins/golem15/oauthserver\$#\t/media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin#" -e "s#^\t\./#\t$B/#" -e "s#=> \.\./summercms.go#=> /media/nvme/dev/golem15/summercms.io/summercms/summercms.go#" "$B/go.work" > "$W/go.work" && grep -q sm-oauthserver-plugin "$W/go.work" && GOWORK="$W/go.work" go -C "$B" vet -tags summercms_mcp ./... && GOWORK="$W/go.work" go -C "$B" test -count=1 -tags summercms_mcp ./...</automated>
|
||||||
|
<fails_when>non-zero exit, or a line contains FAIL, or the grep finds no sm-oauthserver-plugin line in the scratch go.work</fails_when>
|
||||||
|
</verify>
|
||||||
|
<acceptance_criteria>
|
||||||
|
- The six plugin test names have PASS lines, none skipped.
|
||||||
|
- Framework, plugin (both tag settings), admin, docs, grzyby and sm-bm-app runs all exit 0; the SUMMARY records each command and its result.
|
||||||
|
- No file in sm-bm-app or sm-demo-app changed (`git -C ../sm-bm-app status --porcelain` shows nothing new from this task).
|
||||||
|
</acceptance_criteria>
|
||||||
|
<done>Backend mode is proven in the plugin, and every existing consumer path (user mode, sm-bm-app, g15_ tokens) is shown unchanged.</done>
|
||||||
|
</task>
|
||||||
|
|
||||||
|
<task type="checkpoint:decision" gate="blocking">
|
||||||
|
<name>Whether to tag, push and post the changelog</name>
|
||||||
|
<reversibility rating="costly">A pushed framework tag and plugin v0.1.8 are what other applications will require; a mistake is fixed by a further patch, never a rewritten tag.</reversibility>
|
||||||
|
<decision>Tag the framework's next free v0.6 patch and sm-oauthserver-plugin v0.1.8, push both, commit and push the grzyby pointer bump, and publish both changelog posts now?</decision>
|
||||||
|
<context>SC-5 asks for patch tags. Memory rules: tag only at phase completion after full verification and validation; default to the next patch (never a minor bump without the user's word); tags only on master; each tag must contain every earlier tag. If the user wants /msd-verify-work first, choose hold and run the release later. No deploy of any application happens either way (CONTEXT Deferred: production deploy of the first consumer and the live Claude connector check). There is no auto-select: an unattended run must stop here. On resume, before any later task changes a ref, write .planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-05-release-decision.txt with three lines: the accepted option id (hold or tag-and-publish), `framework-base <highest v0.6.* tag in summercms.go now>`, `plugin-base <highest v0.1.* tag in sm-oauthserver-plugin now>`, read with git tag --list --sort=-v:refname. Create no tag, push nothing and publish nothing in this task.</context>
|
||||||
|
<options>
|
||||||
|
<option id="tag-and-publish">
|
||||||
|
<name>Tag, push and post the changelog</name>
|
||||||
|
<pros>The first consumer can require released versions; SC-5 is met the same day with its changelog posts.</pros>
|
||||||
|
<cons>The tags are public before /msd-verify-work has run.</cons>
|
||||||
|
</option>
|
||||||
|
<option id="hold">
|
||||||
|
<name>Do not tag or push yet</name>
|
||||||
|
<pros>Verification and validation can run first, as the release memory recommends.</pros>
|
||||||
|
<cons>SC-5's tags and the grzyby pointer bump wait for a later go-ahead.</cons>
|
||||||
|
</option>
|
||||||
|
</options>
|
||||||
|
<resume-signal>Select tag-and-publish or hold</resume-signal>
|
||||||
|
<read_first>
|
||||||
|
.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-RESEARCH.md (Release mechanics)
|
||||||
|
CLAUDE.md (Commits and concurrency: changelog posts, plugin push before pointer bump)
|
||||||
|
</read_first>
|
||||||
|
<acceptance_criteria>
|
||||||
|
- No git tag, git push or changelog publish runs before this checkpoint returns.
|
||||||
|
- 32.2-05-release-decision.txt exists before the next task changes any ref, and its first line is the accepted option id.
|
||||||
|
</acceptance_criteria>
|
||||||
|
</task>
|
||||||
|
|
||||||
|
<task type="auto">
|
||||||
|
<name>Release only if the checkpoint accepted it</name>
|
||||||
|
<reversibility rating="costly">Pushed tags, the pointer bump and the changelog posts are the release; hold does none of it.</reversibility>
|
||||||
|
<files>../sm-oauthserver-plugin/go.mod, ../sm-oauthserver-plugin/go.sum, ../sm-oauthserver-plugin/plugin.yaml, ../sm-grzybyfunkcjonalne-app/plugins/golem15/oauthserver, ../sm-grzybyfunkcjonalne-app/go.mod, ../sm-grzybyfunkcjonalne-app/go.sum, .planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-05-release-decision.txt, .planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-05-changelog-framework.md, .planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-05-changelog-plugin.md, .planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-05-changelog-published.txt</files>
|
||||||
|
<read_first>
|
||||||
|
.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-05-release-decision.txt
|
||||||
|
../sm-oauthserver-plugin/go.mod (require summercms, replace line) and plugin.yaml (generated by summer plugin:manifest)
|
||||||
|
../sm-grzybyfunkcjonalne-app/go.mod (require lines for summercms and sm-oauthserver-plugin)
|
||||||
|
../sm-summercmsio-app/DEPLOY.md section "Posting to the changelog"
|
||||||
|
CLAUDE.md changelog rules
|
||||||
|
</read_first>
|
||||||
|
<action>
|
||||||
|
Read the decision record; never rewrite it after a ref changes (if resuming without it, write it as the checkpoint describes before changing anything). If the first line is hold: create no tag, push nothing, run no changelog script, say so in the SUMMARY and stop.
|
||||||
|
|
||||||
|
tag-and-publish, in this order. 1) Framework: on master with a clean index for the files of this phase, the new tag is framework-base's patch plus one (next free v0.6 patch; if that tag already exists locally or on origin, stop and ask). Check that HEAD contains every existing v0.* tag (git merge-base --is-ancestor for each), create an annotated tag whose message summarises the phase in user terms, push master, then push the tag. 2) Plugin: set the summercms require in ../sm-oauthserver-plugin/go.mod to the new framework tag (keep the replace line), refresh go.sum, regenerate plugin.yaml with the framework's summer plugin:manifest so TestPluginManifest passes, run the plugin's go test -short ./..., commit go.mod, go.sum and plugin.yaml by path (never go.work), tag v0.1.8 (stop and ask if it exists or if plugin-base is not v0.1.7), push master, then push the tag. 3) App pointer bump, its own commit, only after step 2's push: in ../sm-grzybyfunkcjonalne-app check out v0.1.8 in plugins/golem15/oauthserver, set the go.mod requires of sm-oauthserver-plugin to v0.1.8 and of summercms to the new framework tag, go mod tidy, run scripts/smoke-mcp-oauth.sh and the tagged go test, commit the gitlink, go.mod and go.sum by path, push master. No deploy. 4) Changelog, from ../sm-summercmsio-app: scripts/changelog-post.py source <framework tag> and write .planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-05-changelog-framework.md (user-facing markdown with ## Highlights, ## Added, ## Changed, ## Fixed; no H1, no planning IDs, no quick codes), then publish it with an --excerpt; write 32.2-05-changelog-plugin.md the same way for v0.1.8 and publish it with --repo ../sm-oauthserver-plugin. Append each published post URL the script prints to 32.2-05-changelog-published.txt, one per line. The script reads the g15_ token from ~/.config/summercms/journal-token: never print, copy or mint it; if the file is missing or the token is refused, stop and ask. Never force-push. Do not git add -A anywhere.
|
||||||
|
</action>
|
||||||
|
<verify>
|
||||||
|
<automated>python3 -I -c 'import pathlib,subprocess,sys
|
||||||
|
d=pathlib.Path("/media/nvme/dev/golem15/summercms.io/summercms/summercms.go/.planning/phases/32.2-mcp-oauth-with-administrator-subjects")
|
||||||
|
fw=pathlib.Path("/media/nvme/dev/golem15/summercms.io/summercms/summercms.go"); pl=pathlib.Path("/media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin"); app=pathlib.Path("/media/nvme/dev/golem15/summercms.io/summercms/sm-grzybyfunkcjonalne-app")
|
||||||
|
rec=d/"32.2-05-release-decision.txt"
|
||||||
|
rec.is_file() or sys.exit("decision record absent")
|
||||||
|
L=[x.strip() for x in rec.read_text().splitlines() if x.strip()]
|
||||||
|
len(L)>=3 or sys.exit("decision record incomplete")
|
||||||
|
opt=L[0]; fb=L[1].split()[-1]; pb=L[2].split()[-1]
|
||||||
|
opt in ("hold","tag-and-publish") or sys.exit("bad option")
|
||||||
|
def g(r,*a):
|
||||||
|
p=subprocess.run(["git","-C",str(r),*a],capture_output=True,text=True)
|
||||||
|
p.returncode==0 or sys.exit("git failed in "+r.name)
|
||||||
|
return p.stdout
|
||||||
|
def tags(r,pat): return [t for t in g(r,"tag","--list",pat).split() if t]
|
||||||
|
nxt="v0.6."+str(int(fb.split(".")[2])+1)
|
||||||
|
if opt=="hold":
|
||||||
|
nxt not in tags(fw,"v0.6.*") or sys.exit("hold but framework tagged")
|
||||||
|
"v0.1.8" not in tags(pl,"v0.1.*") or sys.exit("hold but plugin tagged")
|
||||||
|
sys.exit(0)
|
||||||
|
nxt in tags(fw,"v0.6.*") or sys.exit("framework tag missing")
|
||||||
|
"refs/tags/"+nxt in g(fw,"ls-remote","--tags","origin") or sys.exit("framework tag not pushed")
|
||||||
|
"refs/tags/v0.1.8" in g(pl,"ls-remote","--tags","origin") or sys.exit("plugin tag not pushed")
|
||||||
|
"summercms "+nxt in (pl/"go.mod").read_text() or sys.exit("plugin go.mod not on framework tag")
|
||||||
|
c=g(pl,"rev-list","-n","1","v0.1.8").strip()
|
||||||
|
c in g(app,"ls-tree","HEAD","plugins/golem15/oauthserver") or sys.exit("app pointer not at v0.1.8")
|
||||||
|
"sm-oauthserver-plugin v0.1.8" in (app/"go.mod").read_text() or sys.exit("app go.mod not on v0.1.8")
|
||||||
|
for n in ("32.2-05-changelog-framework.md","32.2-05-changelog-plugin.md"):
|
||||||
|
t=(d/n).read_text() if (d/n).is_file() else sys.exit(n+" missing")
|
||||||
|
(not t.lstrip().startswith("# ")) or sys.exit(n+" starts with an H1")
|
||||||
|
all(h in t for h in ("## Highlights","## Added","## Changed","## Fixed")) or sys.exit(n+" missing heading")
|
||||||
|
pub=d/"32.2-05-changelog-published.txt"
|
||||||
|
urls=[x for x in pub.read_text().split() if x.startswith("https://summercms.io/changelog")] if pub.is_file() else []
|
||||||
|
len(urls)>=2 or sys.exit("changelog posts not recorded")'</automated>
|
||||||
|
<fails_when>non-zero exit, including decision record absent, decision record incomplete, bad option, git failed, hold but framework tagged, hold but plugin tagged, framework tag missing, framework tag not pushed, plugin tag not pushed, plugin go.mod not on framework tag, app pointer not at v0.1.8, app go.mod not on v0.1.8, a changelog file missing or starting with an H1 or missing a heading, or changelog posts not recorded</fails_when>
|
||||||
|
</verify>
|
||||||
|
<acceptance_criteria>
|
||||||
|
- hold: no new v0.6 tag in summercms.go, no v0.1.8 in sm-oauthserver-plugin, no changelog script run.
|
||||||
|
- tag-and-publish: the framework tag is the next v0.6 patch on master and on origin; sm-oauthserver-plugin v0.1.8 is on origin and its go.mod requires that framework tag; the grzyby commit moving plugins/golem15/oauthserver to v0.1.8 comes after the plugin push and is its own commit; two changelog posts are recorded; nothing was deployed.
|
||||||
|
</acceptance_criteria>
|
||||||
|
<done>SC-5's patch releases either shipped with their changelog posts and the app pointer bump, or stayed local because the checkpoint said hold.</done>
|
||||||
|
</task>
|
||||||
|
|
||||||
|
</tasks>
|
||||||
|
|
||||||
|
<threat_model>
|
||||||
|
## Trust Boundaries
|
||||||
|
|
||||||
|
| Boundary | Description |
|
||||||
|
|----------|-------------|
|
||||||
|
| Test output and changelog notes | Tokens, codes and the journal token must not reach logs or the public post |
|
||||||
|
| git push of release tags | What other repositories will require |
|
||||||
|
|
||||||
|
## STRIDE Threat Register
|
||||||
|
|
||||||
|
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|
||||||
|
|-----------|----------|-----------|----------|-------------|-----------------|
|
||||||
|
| T-32.2-26 | Information disclosure | tests, smoke output, changelog-post.py | medium | mitigate | Tests assert status codes and ids, never print bearer tokens or codes; the journal token is read by the script only, never printed, copied or minted; stop if it is missing |
|
||||||
|
| T-32.2-27 | Tampering | release tags | medium | mitigate | Blocking checkpoint; tag only on master containing every earlier tag; next patch computed from tags; no force-push; plugin pushed before the app pointer bump |
|
||||||
|
| T-32.2-28 | Spoofing | sm-bm-app regression scratch workspace | low | accept | The scratch go.work lives in a temp dir and only redirects the plugin to the sibling checkout; sm-bm-app files are not changed |
|
||||||
|
| T-32.2-SC | Tampering | go/npm installs | low | accept | No dependency added; npm ci uses the committed lockfile |
|
||||||
|
</threat_model>
|
||||||
|
|
||||||
|
<verification>
|
||||||
|
All named tests pass (none skipped); every regression run in task 3 exits 0; the checkpoint record exists and the release verify agrees with it.
|
||||||
|
|
||||||
|
Carried as unverified human verification (not a failure, and not closed by any test here): the D-03 cross-site SameSite=Strict cookie check (RESEARCH A2, VALIDATION.md manual-only row, DEPLOY.md "Live connector check (deferred)"). VERIFICATION.md must list it as open.
|
||||||
|
</verification>
|
||||||
|
|
||||||
|
<success_criteria>
|
||||||
|
- SC-1 to SC-4 have automated proofs beyond the plan 01-04 smokes, including the five UI backstops (four in vitest, one routed to the deferred live check).
|
||||||
|
- SC-5: tags, pushes, pointer bump and changelog posts happen only through the checkpoint.
|
||||||
|
</success_criteria>
|
||||||
|
|
||||||
|
<output>
|
||||||
|
Create `.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-05-SUMMARY.md` when done.
|
||||||
|
</output>
|
||||||
|
|
||||||
|
## Artifacts this phase produces
|
||||||
|
|
||||||
|
Plan 05 (tests and release):
|
||||||
|
- Framework tests: TestAuthorizeConsentPath, TestAuthorizeDefaultScopes (modules/wristband/consent_path_test.go); TestBackendOnlyGrant, TestLinkedGrantNoScopeLimit (modules/pier/backend_only_grant_test.go); TestTokenScopeNames, TestMCPAdminConsent, TestAccountContributionItems, TestBackendAccessRevokedEvent (modules/cabana/*_test.go)
|
||||||
|
- Admin tests: admin/tests/views/ConnectView.test.ts (new); extended router.test.ts, LoginView.test.ts, AccountContributions.test.ts
|
||||||
|
- Plugin tests: TestBackendGrantToolsMatchPersonalToken (build tag summercms_mcp), TestBackendMode, TestBackendConsent, TestBackendSubjectMigration, TestBackendGrantRows, TestBackendRevokeFromAccount, TestBackendCascade
|
||||||
|
- Release records: 32.2-05-release-decision.txt, 32.2-05-changelog-framework.md, 32.2-05-changelog-plugin.md, 32.2-05-changelog-published.txt
|
||||||
|
- Only after tag-and-publish: next framework v0.6 patch tag, sm-oauthserver-plugin v0.1.8 (go.mod on that framework tag, regenerated plugin.yaml), the grzyby pointer bump commit to v0.1.8, two changelog posts
|
||||||
@@ -0,0 +1,239 @@
|
|||||||
|
# Phase 32.2: MCP OAuth with administrator subjects - Pattern Map
|
||||||
|
|
||||||
|
**Mapped:** 2026-11-20
|
||||||
|
**Files analyzed:** 30 (file list from 32.2-RESEARCH.md "Recommended file layout")
|
||||||
|
**Analogs found:** 28 / 30
|
||||||
|
|
||||||
|
Repos: `F` = summercms.go, `P` = ../sm-oauthserver-plugin, `U` = ../sm-user-plugin, `G` = ../sm-grzybyfunkcjonalne-app, `B` = ../sm-bm-app. All analog paths are git-tracked source (no `.msd/` mirrors).
|
||||||
|
|
||||||
|
## File Classification
|
||||||
|
|
||||||
|
| New/Modified File | Role | Data Flow | Closest Analog | Match |
|
||||||
|
|---|---|---|---|---|
|
||||||
|
| F `modules/pact/mcp.go` (MCPGrant.Subject, MCPSubject.ScopeLimited, MCPAdminConsent) | model/contract | request-response | same file: `MCPGrant` (l.280-292), `MCPLinkedBackendResolver` (l.314-323) | exact |
|
||||||
|
| F `modules/pact/capabilities.go` (AccountContribution.Items/ItemActions) | contract | CRUD | same file `AccountContribution`/`AccountAction` (l.614-640) | exact |
|
||||||
|
| F `modules/wristband/server.go` (Options.ConsentPath, DefaultScopes) | config | - | same file `Options` (l.26-60), `ScopesSupported` empty→default doc (l.36-40) | exact |
|
||||||
|
| F `modules/wristband/authorize.go` | controller | request-response | same file l.187 handoff | exact |
|
||||||
|
| F `modules/pier/identity.go` | service | request-response | same file `resolveOAuth` (l.204-238), `consentedBackendSubject` (l.240) | exact |
|
||||||
|
| F `modules/pier/backend_guard.go` | middleware/guard | request-response | same file `principal` (l.105-122) | exact |
|
||||||
|
| F `modules/cabana/mcp_consent.go` (new) | controller | request-response | `modules/cabana/account_contributions.go` (l.98-233) + P `controllers/mcp_consent_api.go` (body shapes) | role-match |
|
||||||
|
| F `modules/cabana/token_scopes_export.go` (new) | utility | transform | `modules/cabana/token_scopes.go` (`ownerHas` l.237, `scopeOverlaps` l.333, `methodFilterScopes` l.365) | exact |
|
||||||
|
| F `modules/cabana/admin_events.go` (new BackendAccessRevokedEvent) | event | event-driven | U `classes/events.go` `AccessRevokedEvent` (l.112-130); F `modules/cabana/subject_events.go` (l.25-60) | exact |
|
||||||
|
| F `modules/cabana/account_contributions.go` | controller | CRUD | same file | exact |
|
||||||
|
| F `modules/cabana/admin_openapi.go` | config (docs) | - | same file l.370-395 (account contributions annotations) | exact |
|
||||||
|
| F `admin/src/views/ConnectView.vue` (new) | component | request-response | `admin/src/views/LoginView.vue` (101 lines) | exact (standalone card) |
|
||||||
|
| F `admin/src/app/router.ts` | route | - | same file l.62 (`/login`), l.74 (`/account`), guard l.90-101 | exact |
|
||||||
|
| F `admin/src/components/account/AccountContributions.vue` | component | CRUD | same file (160 lines); `ApiTokensPanel.vue` for per-row revoke list | exact |
|
||||||
|
| F `admin/openapi/admin.json`, `admin/src/api/schema.d.ts` | generated | - | `scripts/check-admin-openapi.sh` | generated |
|
||||||
|
| F `modules/boardwalk/dist` | generated | - | `scripts/check-admin-dist.sh` | generated |
|
||||||
|
| P `updates/2026112xxxxx_add_golem15_oauthserver_backend_subjects.go` | migration | batch | P `updates/202610230001_add_backend_user_id.go` | exact |
|
||||||
|
| P `classes/mcp_store.go` | store | CRUD | same file `MarkIssued` (l.262-287), `ByCodeHashForUpdate` (l.192), `Create` (l.300), `ByTokenHashForUpdate`/`refreshUserUsable` (l.334-377) | exact |
|
||||||
|
| P `classes/mcp_backend_subject.go` (new) | utility | request-response | P `classes/mcp_backend_binding.go` (ctx keys l.11-62, locks l.73-110) | exact |
|
||||||
|
| P `classes/mcp_verifier.go` | service | request-response | same file `MCPVerifyToken` (l.83-145) | exact |
|
||||||
|
| P `classes/backend_cascade.go` (new) | listener | event-driven | P `classes/cascade.go` (l.1-80) + `classes/subject_events.go` (`FireSubjectChangedAfterCommit` l.25) | exact |
|
||||||
|
| P `controllers/mcp_admin_consent.go` (new) | controller/provider | request-response | P `controllers/mcp_consent_api.go` | exact |
|
||||||
|
| P `controllers/mcp_connections.go` (new admin list screen) | controller | CRUD | P `controllers/clients.go` + `controllers/clients/` YAML; U `backend_links_admin.go` | role-match |
|
||||||
|
| P `account.go` (new HasAccountContributions) | provider | CRUD | U `account_contributions.go` (l.1-80) | exact |
|
||||||
|
| P `admin_permissions.go` / `admin_navigation.go` | config | - | same files (`Permissions()` l.10-23) | exact |
|
||||||
|
| P `servers.go` / `routes.go` / `config/config.yaml` | config/route | - | same files; `routes.go` `GroupRaw` blocks (l.32-85); `config.yaml` comment style (l.1-36) | exact |
|
||||||
|
| G `summer.yaml`, `.gitmodules`, `go.mod`, `go.work` | config | - | G `summer.yaml` plugins (l.8-24) ; B for oauthserver entry | exact |
|
||||||
|
| G `config/golem15.oauthserver.yaml` | config | - | B `config/golem15.oauthserver.yaml` | exact |
|
||||||
|
| G `deploy/nginx/*.conf` | config | - | B `deploy/nginx/bm.jakubzych.com.conf` (l.1-10, 97-110) | exact |
|
||||||
|
| G `scripts/smoke-mcp-oauth.sh`, `DEPLOY.md` | test/docs | - | none tracked for full OAuth dance (see No Analog) | partial |
|
||||||
|
|
||||||
|
## Pattern Assignments
|
||||||
|
|
||||||
|
### F `modules/pact/mcp.go`
|
||||||
|
**Analog:** same file, `MCPGrant` l.280-292. Add fields additively with doc comments in the same voice; zero value must mean today's behaviour.
|
||||||
|
```go
|
||||||
|
type MCPGrant struct {
|
||||||
|
UserID uint
|
||||||
|
ClientID string
|
||||||
|
TokenID uint
|
||||||
|
Scopes []string
|
||||||
|
ExpiresAt time.Time
|
||||||
|
// BackendUserID is the backend account the consent page showed ...
|
||||||
|
BackendUserID uint
|
||||||
|
}
|
||||||
|
```
|
||||||
|
`MCPSubject` (l.134-140) is `{Guard, UserID, Scopes, ClientID, TokenID}`; add `ScopeLimited bool` there. A new provider interface (`MCPAdminConsent`) follows `MCPLinkedBackendResolver` (l.314-323): single-method-ish interface published through `app.Lookup[...]`, plus a plain view struct like `LinkedBackendUser`. Subject-changed kinds: reuse `MCPSubjectRevoked`/`MCPSubjectDeleted`/`MCPSubjectPermissions` (l.347-353), do not add kinds unless needed.
|
||||||
|
|
||||||
|
### F `modules/pact/capabilities.go`
|
||||||
|
**Analog:** `AccountContribution` l.614-620 and `AccountAction` l.629-640:
|
||||||
|
```go
|
||||||
|
type AccountContribution struct {
|
||||||
|
Name string
|
||||||
|
Label string
|
||||||
|
Description string
|
||||||
|
Status func(ctx context.Context, adminID uint) (string, error) `json:"-"`
|
||||||
|
Actions []AccountAction
|
||||||
|
}
|
||||||
|
```
|
||||||
|
Add `Items func(ctx, adminID uint) ([]AccountItem, error) \`json:"-"\`` and `ItemActions []AccountAction` (or a sibling item-action type with `Run(ctx, adminID, itemID)`). Nil keeps existing plugins (U) unchanged.
|
||||||
|
|
||||||
|
### F `modules/wristband/server.go` + `authorize.go`
|
||||||
|
**Analog:** `Options.ScopesSupported` doc (l.36-40): "empty or nil resolves to PHP default". Use the same rule for `ConsentPath` (empty → `/connect`). Change only l.187:
|
||||||
|
```go
|
||||||
|
spa := s.opts.Issuer + "/connect?request=" + rfc3986Escape(requestID)
|
||||||
|
```
|
||||||
|
→ `s.opts.Issuer + consentPath + "?request=" + ...`. Default bytes must stay identical (PHP parity, `.planning/notes/oauth2-wristband-direct-port.md`); also update l.43 comment.
|
||||||
|
|
||||||
|
### F `modules/pier/identity.go`
|
||||||
|
**Analog:** `resolveOAuth` l.204-238 builds `Identity` and calls `consentedBackendSubject(ctx, grant.UserID, grant.ClientID, grant.TokenID, scopes, grant.BackendUserID)` (l.231). Add an early branch: when `grant.Subject == pact.MCPGrantSubjectBackend` (or `UserID==0 && BackendUserID!=0`), set only `id.Backend = &pact.MCPSubject{Guard: backend, UserID: grant.BackendUserID, Scopes, ClientID, TokenID, ScopeLimited: true}`; no frontend subject, no `linkedBackend` (l.309-325) lookup.
|
||||||
|
|
||||||
|
### F `modules/pier/backend_guard.go`
|
||||||
|
**Analog:** `principal` l.105-122:
|
||||||
|
```go
|
||||||
|
if subject.ClientID == "" && subject.TokenID != 0 {
|
||||||
|
limit, known, _ := cabana.ScopeLimitFor(g.app, subject.Scopes, method)
|
||||||
|
if known == 0 {
|
||||||
|
return nil, errScopeUnavailable
|
||||||
|
}
|
||||||
|
if limit == nil {
|
||||||
|
limit = &bouncer.ScopeLimit{}
|
||||||
|
}
|
||||||
|
principal.Scope = limit
|
||||||
|
}
|
||||||
|
```
|
||||||
|
Extend the condition to `(subject.ClientID == "" && subject.TokenID != 0) || subject.ScopeLimited`; user-mode linked grants (ScopeLimited false) unchanged (D-09).
|
||||||
|
|
||||||
|
### F `modules/cabana/mcp_consent.go` (new)
|
||||||
|
**Analog:** `modules/cabana/account_contributions.go` handlers l.98-233.
|
||||||
|
- Auth: `principal := accountPrincipal(w, r); if principal == nil { return }`
|
||||||
|
- Lookup provider: `app.Lookup[pact.MCPAdminConsent]()`; absent → `WriteError(w, http.StatusNotFound, "not_found", msgNotFound)`.
|
||||||
|
- Response: `WriteData(w, http.StatusOK, view, map[string]any{})`; errors via `WriteError(w, status, code, msg)`; log with `moduleLog.ErrorContext(ctx, "cabana: ...", ...)`.
|
||||||
|
- Translation: `translateKey(ctx, s.translator(), key)`.
|
||||||
|
- Transaction for the decision POST: same as `accountContributionAction` (Run inside a tx carried by context, `TxFromContext`).
|
||||||
|
- Route path `r.PathValue("request")`. Body shapes for client/scope lists copy P `controllers/mcp_consent_api.go` `mcpConsentClient`, `mcpScopeDetail`, `mcpConsentShowBody` (l.35-60) so the SPA mirrors 32.1's `/connect` shape.
|
||||||
|
|
||||||
|
### F `modules/cabana/token_scopes_export.go` (new)
|
||||||
|
**Analog:** `modules/cabana/token_scopes.go`: catalog `tokenScopeCatalog` (l.32), `ownerHas(p, code)` (l.237), `scopeOverlaps(reg, owner, name)` (l.333). Export `TokenScopeNames(app)` and a grantable-for-principal view; D-11 hide = filter with `scopeOverlaps`. Exported funcs taking `*backpack.App` follow `ScopeLimitFor(app, scopes, method)` (tested in `scope_limit_for_test.go`). Docs checker: add to cabana README API reference.
|
||||||
|
|
||||||
|
### F `modules/cabana/admin_events.go` (new)
|
||||||
|
**Analog:** U `classes/events.go` l.112-117:
|
||||||
|
```go
|
||||||
|
type AccessRevokedEvent struct {
|
||||||
|
UserIDs []uint
|
||||||
|
Before time.Time
|
||||||
|
Reason string
|
||||||
|
Tx *gorm.DB
|
||||||
|
}
|
||||||
|
```
|
||||||
|
Model `BackendAccessRevokedEvent{AdminIDs []uint; Reason string; Tx *gorm.DB}` with Reason constants (deleted, deactivated, password, permissions, sign_out_everywhere). Fire synchronously inside the save tx (listener failure rolls back, like U); the `MCPSubjectChanged` after-commit fan-out copies `fireSubjectChanged` (`subject_events.go` l.25-48: `lagoon.AfterCommit(ctx, tx, func(...){ app.Events.Fire(ctx, &pact.MCPSubjectChanged{Guard: backendSubjectGuard, ...}) })`). Call sites: the places that already call `fireSubjectChanged` (grep `fireSubjectChanged(` in cabana: backend users admin, account, commands).
|
||||||
|
|
||||||
|
### F `modules/cabana/account_contributions.go`
|
||||||
|
**Analog:** same file. Items list goes in the per-section loop of `accountContributionsList` (l.105-150), same error policy: a failing `Items` sets `view.Error = true` and logs, never hides other sections. Item action route copies `accountContributionAction` (l.160-233): 404 unknown, 403 `!Allows(principal, action.Permissions)`, 409 no longer applies, run in tx. Compile-time validation in `compileAccountContributions` (l.38).
|
||||||
|
|
||||||
|
### F `modules/cabana/admin_openapi.go`
|
||||||
|
**Analog:** l.370-395 (`@Summary List My account contributions` / `@Router /account/contributions [get]`). Add annotations for `/mcp/consent/{request} [get]`, `[post]`, item action route; then `scripts/check-admin-openapi.sh`.
|
||||||
|
|
||||||
|
### F `admin/src/views/ConnectView.vue` (new)
|
||||||
|
**Analog:** `admin/src/views/LoginView.vue` (whole file, 101 lines): `<script setup lang="ts">`, imports `t` from `../app/i18n`, `safeRedirect` from `../app/router`, `useAuth` state, lucide icons, `busy`/`failed` refs, guard against double submit:
|
||||||
|
```ts
|
||||||
|
async function submit(): Promise<void> {
|
||||||
|
if (busy.value) { return }
|
||||||
|
busy.value = true
|
||||||
|
failed.value = false
|
||||||
|
try { ... } finally { busy.value = false }
|
||||||
|
}
|
||||||
|
```
|
||||||
|
Template: same standalone card markup as LoginView (no shell). "Use another account" = logout from `state/useAuth` then `router.replace({ name: 'login', query: { redirect: route.fullPath } })`. Final Allow/Deny answer is a `window.location.assign(redirect_url)` (cross-origin client redirect). Follow 32.2-UI-SPEC.md for copy and states.
|
||||||
|
|
||||||
|
### F `admin/src/app/router.ts`
|
||||||
|
**Analog:** l.62 and guard l.90-101:
|
||||||
|
```ts
|
||||||
|
{ path: '/login', name: 'login', component: LoginView, meta: { public: true } },
|
||||||
|
...
|
||||||
|
return { name: 'login', query: { redirect: to.fullPath } }
|
||||||
|
```
|
||||||
|
New: `{ path: '/connect', name: 'connect', component: ConnectView }` — no `meta.shell`, no `meta.public` (anonymous → login with redirect via existing guard). Verify `safeRedirect` (l.28-50) accepts `/connect?request=...`.
|
||||||
|
|
||||||
|
### F `admin/src/components/account/AccountContributions.vue`
|
||||||
|
**Analog:** same file (sections + actions + confirm dialog); per-item row list with revoke button copies `ApiTokensPanel.vue` (312 lines) list/revoke layout.
|
||||||
|
|
||||||
|
### P migration `updates/2026112xxxxx_add_golem15_oauthserver_backend_subjects.go`
|
||||||
|
**Analog:** `updates/202610230001_add_backend_user_id.go` (whole file):
|
||||||
|
```go
|
||||||
|
var addBackendUserID = []*gormigrate.Migration{
|
||||||
|
{
|
||||||
|
ID: "202610230001_add_golem15_oauthserver_backend_user_id",
|
||||||
|
Migrate: func(tx *gorm.DB) error {
|
||||||
|
return run(tx, []string{ `ALTER TABLE ... ADD COLUMN backend_user_id INTEGER NULL`, ... })
|
||||||
|
},
|
||||||
|
Rollback: func(tx *gorm.DB) error { return run(tx, []string{ ... }) },
|
||||||
|
},
|
||||||
|
}
|
||||||
|
func init() { Register(addBackendUserID...) }
|
||||||
|
```
|
||||||
|
SQL body: RESEARCH.md Pattern 1 (l.212-227). Doc comment explains rollback deletes backend rows.
|
||||||
|
|
||||||
|
### P `classes/mcp_backend_subject.go` (new)
|
||||||
|
**Analog:** `classes/mcp_backend_binding.go`: context key pattern l.11-62
|
||||||
|
```go
|
||||||
|
type consentedBackendKey struct{}
|
||||||
|
func WithConsentedBackend(ctx context.Context, backendUserID uint) context.Context {
|
||||||
|
return context.WithValue(ctx, consentedBackendKey{}, backendUserID)
|
||||||
|
}
|
||||||
|
func consentedBackendFrom(ctx context.Context) uint {
|
||||||
|
id, _ := ctx.Value(consentedBackendKey{}).(uint)
|
||||||
|
...
|
||||||
|
```
|
||||||
|
→ `WithBackendSubject(ctx)` / `backendSubjectFrom(ctx)`. Advisory locks copy `userGrantsLockKey`, `lockUserGrantsShared`, `LockUserGrants` (l.73-110) with a distinct key namespace for admins.
|
||||||
|
|
||||||
|
### P `classes/mcp_store.go`
|
||||||
|
**Analog:** `MarkIssued` l.262-287 column map:
|
||||||
|
```go
|
||||||
|
cols := map[string]any{
|
||||||
|
"request_id": nil, "code_hash": codeHash, "user_id": userID, ...
|
||||||
|
"backend_user_id": backendBinding(scopes, consentedBackendFrom(ctx)),
|
||||||
|
}
|
||||||
|
```
|
||||||
|
Backend ctx: `"user_id": nil, "backend_user_id": userID`. Same branching for `Create` (l.300), `ByCodeHashForUpdate` (l.192), `refreshUserUsable` (l.363), `refreshRecord`. Reader table: RESEARCH.md l.229-240.
|
||||||
|
|
||||||
|
### P `classes/mcp_verifier.go`
|
||||||
|
**Analog:** `MCPVerifyToken` l.83-145. Keep token/client checks (l.92-115); branch before `userclasses.PrincipalByID(ctx, db, token.UserID)` (l.117): when `token.UserID == nil/0 && token.BackendUserID != nil` → `cabana.BackendPrincipal(ctx, app, id)`, `issuedBeforeCutoff(token.CreatedAt, principal.TokensValidAfter)`, skip `ThrottleStates`, return grant with `Subject: backend, BackendUserID: id`. Note `models.AccessToken.UserID` must become a pointer/nullable (check model file).
|
||||||
|
|
||||||
|
### P `classes/backend_cascade.go` (new)
|
||||||
|
**Analog:** `classes/cascade.go`: `Cascade{App *backpack.App}`, handler signature `func (c Cascade) OnUserDeleting(ctx context.Context, ev *userclasses.DeletingEvent) error` with nil guards and `tx == nil → lookupDB(c.App)` fallback (l.31-60). Fire sessions-ended with `FireSubjectChangedAfterCommit(ctx, app, tx, guard, id, kind)` (`classes/subject_events.go` l.25). Register listener where `Cascade` is registered in `plugin.go`.
|
||||||
|
|
||||||
|
### P `controllers/mcp_admin_consent.go` (new)
|
||||||
|
**Analog:** `controllers/mcp_consent_api.go` (imports l.3-21, constants `mcpBackendScope`, `mcpOfflineAccessScope`, `maxMCPClientName`, view structs l.35-60, IssueCode with `classes.WithGrantedOfflineAccess`). Implements `pact.MCPAdminConsent`; issues with `classes.WithBackendSubject(ctx)` and the admin ID.
|
||||||
|
|
||||||
|
### P `controllers/mcp_connections.go` (new admin screen)
|
||||||
|
**Analog:** `controllers/clients.go` + `controllers/clients/` YAML (columns.yaml/config_list.yaml) and `controllers/admin_registry.go`; permission gating as in `admin_permissions.go`. Revoke action copies the per-client revoke from 32.1 (`controllers/authorizations.go`).
|
||||||
|
|
||||||
|
### P `account.go` (new)
|
||||||
|
**Analog:** U `account_contributions.go` l.15-55: `var _ pact.HasAccountContributions = (*Plugin)(nil)`, phrase-key prefix const, one contribution with `Status`, `Actions` gated by `Applies`; Danger+Confirm on revoke. Only offered when `mcp.subject == backend`.
|
||||||
|
|
||||||
|
### P `admin_permissions.go` / `admin_navigation.go`
|
||||||
|
**Analog:** `admin_permissions.go` l.10-23 — append `{Code: controllers.PermissionManageMCPConnections, Tab: "golem15.oauthserver::lang.plugin.tab", Label: "golem15.oauthserver::lang.permissions.manage_mcp_connections"}`; no default role.
|
||||||
|
|
||||||
|
### P `config/config.yaml`, `servers.go`, `routes.go`
|
||||||
|
**Analog:** config.yaml comment style l.1-36 (each key documented, PHP name or "(new)"). New keys `mcp.subject: user`, `mcp.consent_path: ""`, `oidc.enabled: true`. `routes.go` `GroupRaw` blocks l.32-85: gate OIDC groups behind `oidc.enabled`.
|
||||||
|
|
||||||
|
### G app wiring
|
||||||
|
- `summer.yaml` plugins list l.8-24: add `- id: golem15.oauthserver\n module: git.golem15.com/golem15/sm-oauthserver-plugin`.
|
||||||
|
- `config/golem15.oauthserver.yaml`: copy B's file header and `mcp.enabled/resource` block; add `mcp.subject: backend`, `mcp.consent_path: /<admin prefix>/connect`, `oidc.enabled: false`.
|
||||||
|
- nginx: G confs already proxy; copy B `bm.jakubzych.com.conf` l.97-110 comment and `location = /mcp`, and ensure `/oauth/` and `/.well-known/oauth-*` reach the Go binary.
|
||||||
|
- `.gitmodules`/`go.mod replace`/`go.work use`: copy existing `plugins/golem15/*` entries in G.
|
||||||
|
|
||||||
|
## Shared Patterns
|
||||||
|
|
||||||
|
- **Admin API auth/response (cabana):** `accountPrincipal(w, r)`, `Allows(principal, perms)`, `WriteData`, `WriteError`, `moduleLog.*Context` — `modules/cabana/account_contributions.go` l.98-233.
|
||||||
|
- **After-commit MCP session end:** cabana `fireSubjectChanged` (`subject_events.go` l.25-48); plugin `FireSubjectChangedAfterCommit` (P `classes/subject_events.go` l.25).
|
||||||
|
- **Event in transaction, listener failure rolls back:** U `classes/events.go` `AccessRevokedEvent` + P `classes/cascade.go`.
|
||||||
|
- **Context-carried flags into wristband store:** P `classes/mcp_backend_binding.go` l.11-62.
|
||||||
|
- **Migrations:** raw SQL slice through `run(tx, ...)` + `Register(...)` in `init()` (P `updates/`).
|
||||||
|
- **Additivity:** zero values = current behaviour in every new pact field / wristband option / config key (core plugins are shared).
|
||||||
|
|
||||||
|
## No Analog Found
|
||||||
|
|
||||||
|
| File | Role | Reason |
|
||||||
|
|---|---|---|
|
||||||
|
| G `scripts/smoke-mcp-oauth.sh` | test | No tracked script drives discovery + DCR + login + consent + tool call end to end; use RESEARCH.md flow and P `mcp_consent_smoke_test.go` harness for Go-side pieces |
|
||||||
|
| Admin-scoped scope-limited OAuth grant in pier | service | New concept; RESEARCH.md Code Examples define it |
|
||||||
|
|
||||||
|
## Metadata
|
||||||
|
|
||||||
|
**Analog search scope:** summercms.go `modules/{pact,wristband,pier,cabana}`, `admin/src`; sm-oauthserver-plugin (root, classes, controllers, updates, config); sm-user-plugin (classes/events.go, account_contributions.go); sm-grzybyfunkcjonalne-app and sm-bm-app (summer.yaml, config, deploy/nginx).
|
||||||
|
**Files scanned:** ~35
|
||||||
@@ -536,12 +536,16 @@ A Claude connector run is part of the deferred deploy check.
|
|||||||
| A5 | Firing a new cabana event synchronously inside admin saves has no ordering conflict with existing FormAfterUpdate hooks | D-13 map | minor rework of hook placement |
|
| A5 | Firing a new cabana event synchronously inside admin saves has no ordering conflict with existing FormAfterUpdate hooks | D-13 map | minor rework of hook placement |
|
||||||
| A6 | No other app relies on `Options` zero values producing `/connect` other than through `DefaultOptions` | Pattern 3 | none if empty-means-default is kept |
|
| A6 | No other app relies on `Options` zero values producing `/connect` other than through `DefaultOptions` | Pattern 3 | none if empty-means-default is kept |
|
||||||
|
|
||||||
## Open Questions
|
## Open Questions (RESOLVED)
|
||||||
|
|
||||||
1. **Show consent when already consented?** The user-mode contract has `consent_required`; vue-oauth-layer omits scopes when consent is stored. Recommendation: always show the card for admins (one click), keep the field for parity.
|
1. **Show consent when already consented?** The user-mode contract has `consent_required`; vue-oauth-layer omits scopes when consent is stored. Recommendation: always show the card for admins (one click), keep the field for parity.
|
||||||
|
**RESOLVED** (32.2-01, 32.2-02): adopted. 32.2-01 task 2 keeps `consent_required` in the cabana `MCPConsentView`; 32.2-02 always renders the card, posts nothing on mount even when `consent_required` is false, and shows the "previously allowed" note instead (no auto-allow).
|
||||||
2. **Keep `oidc.enabled` as a new key or tie OIDC off to `mcp.subject: backend`?** Recommendation: separate key (default true); coupling would block the deferred coexistence.
|
2. **Keep `oidc.enabled` as a new key or tie OIDC off to `mcp.subject: backend`?** Recommendation: separate key (default true); coupling would block the deferred coexistence.
|
||||||
|
**RESOLVED** (32.2-03): adopted. 32.2-03 task 1 adds `oidc.enabled` as its own key, default true; with it false, the OIDC discovery, JWKS, `/oauth/authorize*`, `/oauth/token` and `/oauth/userinfo` routes are not mounted. It is not derived from `mcp.subject`.
|
||||||
3. **`mcp_scopes` in backend mode:** ignore or fail boot? Recommendation: fail boot with a clear message when set together with `subject: backend`.
|
3. **`mcp_scopes` in backend mode:** ignore or fail boot? Recommendation: fail boot with a clear message when set together with `subject: backend`.
|
||||||
|
**RESOLVED** (32.2-03): adopted. 32.2-03 task 1 fails boot when `golem15.oauthserver.mcp_scopes` is set together with `mcp.subject: backend`. The same task also fails boot on an unknown subject and on backend with `mcp.enabled: false`.
|
||||||
4. **"Sign out everywhere":** cabana offers none today. Recommendation: document; if added later it fires the new event with its own reason.
|
4. **"Sign out everywhere":** cabana offers none today. Recommendation: document; if added later it fires the new event with its own reason.
|
||||||
|
**RESOLVED** (32.2-01): adopted. 32.2-01 task 4 adds no such action and documents that cabana does not offer one (cabana README, `docs/backend/users-and-permissions.md`). D-13 covers it "where cabana offers it", so nothing is left out. A later sign-out-everywhere action would fire `cabana.BackendAccessRevokedEvent` with its own reason.
|
||||||
|
|
||||||
## Environment Availability
|
## Environment Availability
|
||||||
|
|
||||||
|
|||||||
@@ -0,0 +1 @@
|
|||||||
|
No external API integration: this phase implements its own OAuth 2.1 authorization server mode (wristband + sm-oauthserver-plugin) and MCP resource (pier) and the admin consent API they expose; it consumes no third-party API, and the only external client (the Claude connector) is a caller of these endpoints whose live check is deferred to the post-phase deploy.
|
||||||
Reference in New Issue
Block a user