feat(32.2-01): administrator-only MCP grants and a configurable consent handoff

- pact: MCPGrant.Subject with MCPGrantSubjectBackend, MCPSubject.ScopeLimited
- pier: a backend-subject grant resolves straight to a scope-limited backend
  subject bound to oauth:backend:<client>:<admin>, no link lookup, no ceiling
- pier: the backend guard scope-limits ScopeLimited subjects like g15_ tokens
- wristband: Options.ConsentPath and Options.DefaultScopes; defaults unchanged
- smoke tests TestBackendSubjectSmoke (Postgres) and TestConsentPathSmoke
This commit is contained in:
Jakub Zych
2026-11-21 00:06:19 +01:00
parent 45eb34e5c4
commit c63bfa3ef2
12 changed files with 506 additions and 33 deletions

View File

@@ -128,6 +128,8 @@ What pier does with it at boot:
Every request is authorized afresh from its bearer; a session never replaces the bearer. An OAuth access token of the application's authorization server (`oas_at_…`) is verified through the `pact.MCPTokenVerifier` the OAuth server plugin publishes: the grant's user is the frontend subject, the grant's scopes are the ceiling. With the `backend` scope and a link the published `pact.MCPLinkedBackendResolver` confirms, the linked administrator is the backend subject, resolved on every request (cached for at most five seconds on one instance and dropped at once by a link event), so unlinking takes effect on the next call with no token surgery. The verifier also reports which administrator the user consented to (`pact.MCPGrant.BackendUserID`); while the link names anyone else, or when the grant records none, the grant has no backend subject, so a link that changes after the consent never re-targets it. The backend principal keeps the administrator's real permissions, superuser included, under the grant's ceiling.
An application without frontend users can sign administrators in directly. The OAuth server plugin then issues administrator-only grants: the verifier answers `pact.MCPGrant.Subject` as `pact.MCPGrantSubjectBackend`, `UserID` 0 and the administrator in `pact.MCPGrant.BackendUserID`. Such a grant has only a backend subject, taken straight from the grant with no link lookup, and its sessions are bound to `oauth:backend:<client_id>:<admin_id>`, so two administrators of one client never share a session. The read/write ceiling does not apply; instead the subject is `pact.MCPSubject.ScopeLimited`, and the backend guard caps it with the same scope limit an administrator's `g15_` token with those scopes gets: a grant of `admin:read` lists and runs only the routes that limit allows for `GET`. A grant that names neither a frontend user nor an administrator is refused. Grants of linked frontend users are unchanged.
The `read` and `write` scopes are a ceiling, and that ceiling is unchanged: a grant with only `read` sees tools whose read-only hint is true, `write` unlocks the rest, and permissions always filter on top. The `ai` and `offline_access` scopes play no part in it. `pact.MCPSubject.Scopes` on a call is the grant, not an implied expansion of `pact.FrontendTokenScope.Implies`.
Every tool call stores a `pact.MCPCall` with `pact.WithMCPCall` immediately before the dispatch marker. A route reads it with `pact.MCPCallFrom`; a request pier did not dispatch has none. `pact.MCPCall.Subject` is the subject resolved for that tool's guard, `pact.MCPCall.Tool` is the exposed tool name and `pact.MCPCall.SessionID` is the MCP session id, empty on the stateless path. `pact.MCPSubject.TokenID` is a member personal-token id only when `pact.MCPSubject.ClientID` is empty, and the OAuth access-token row otherwise.