fix(32.2): WR-03 refuse an unknown MCPGrant.Subject instead of treating it as a user grant

pier now resolves only the empty subject (frontend user grant) and pact.MCPGrantSubjectBackend; any other value is ErrUnauthorized and never reaches the linked-administrator lookup.
This commit is contained in:
Jakub Zych
2026-11-21 09:11:46 +01:00
parent 1dcc2ed06d
commit 19bb3f9485
6 changed files with 18 additions and 6 deletions

View File

@@ -163,7 +163,7 @@ func (p *BlogPlugin) Schedule() []pact.ScheduledCommand {
| `pact.WithMCPCall` | Stores a `pact.MCPCall` on a context. A nil context is returned as nil. |
| `pact.MCPCallFrom` | Returns the `pact.MCPCall` on a context. The boolean is false when the context is nil or carries none, including a plain HTTP request. |
| `pact.MCPDispatch` | A guard provider's answer for one call: the principal (as `any`), an optional credential and the bouncer guard names that honour the dispatch marker. |
| `pact.MCPTokenVerifier` | Published by the OAuth server plugin: verifies an access token at the MCP endpoint into a `pact.MCPGrant` (user, client, token, scopes, expiry and, for a `backend` grant, `BackendUserID`, the backend account the consent showed) and names its resource. `pact.MCPGrant.Subject` says what the grant acts as: empty is the frontend user in `UserID` (the meaning every grant had before), `pact.MCPGrantSubjectBackend` is the administrator in `pact.MCPGrant.BackendUserID` alone, with `UserID` 0 and no frontend user. A refused token is `pact.ErrMCPTokenInvalid`. The interface is only `MCPVerifyToken` and `MCPResource`. |
| `pact.MCPTokenVerifier` | Published by the OAuth server plugin: verifies an access token at the MCP endpoint into a `pact.MCPGrant` (user, client, token, scopes, expiry and, for a `backend` grant, `BackendUserID`, the backend account the consent showed) and names its resource. `pact.MCPGrant.Subject` says what the grant acts as: empty is the frontend user in `UserID` (the meaning every grant had before), `pact.MCPGrantSubjectBackend` is the administrator in `pact.MCPGrant.BackendUserID` alone, with `UserID` 0 and no frontend user; the MCP endpoint refuses any other value. A refused token is `pact.ErrMCPTokenInvalid`. The interface is only `MCPVerifyToken` and `MCPResource`. |
| `pact.MCPAdvertisedScopes` | Optional second interface on that verifier. `pact.MCPAdvertisedScopes.MCPScopesSupported` is the MCP scope list pier copies into protected-resource metadata when the slice is non-empty. |
| `pact.MCPPersonalTokenResolver` | Published by the one plugin whose personal tokens may open an MCP session (one resolver per application): resolves a raw token into a `pact.MCPSubject` whose `TokenID` identifies the token row (it keys the session binding; a subject without one is refused); false when the prefix is not its own, which the endpoint answers as unauthorized. |
| `pact.MCPAdminConsent` | Published (`app.Publish`) by the plugin that owns the MCP authorization server, one per application: `pact.MCPAdminConsent.MCPAdminConsentShow` answers a pending request for the signed-in administrator as a `pact.MCPAdminConsentRequest`, `pact.MCPAdminConsent.MCPAdminConsentDecide` applies a `pact.MCPAdminConsentDecision` and answers the client redirect URI. The framework serves the consent endpoints of the admin API over it and applies the scope policy before calling Decide; the provider only resolves and issues. |

View File

@@ -305,7 +305,8 @@ type MCPGrant struct {
// Subject is the kind of subject the grant names. Empty means the
// frontend user in UserID, the meaning every grant had before Subject
// existed. MCPGrantSubjectBackend means the backend account in
// BackendUserID, with UserID 0 and no frontend user involved.
// BackendUserID, with UserID 0 and no frontend user involved. The MCP
// endpoint refuses a grant with any other value.
Subject string
}

View File

@@ -10,7 +10,7 @@ Opt-in MCP endpoint that lists the tools and prompts plugins declare per caller
pier mounts a streamable HTTP MCP endpoint (POST, GET and DELETE at `mcp.path`, default `/mcp`) inside the application binary, on the official Go SDK. A plugin takes part by implementing `pact.HasMCP`: each `pact.MCPTool` names one of the plugin's own routes by method and path, an input struct whose tags say which fields fill the path, the query string and the body, and the guard the tool runs as. At boot pier compiles every declaration against the route table (an unknown route, a duplicate or invalid name, a route that is not token-guarded, a non-object input, a `path:` field the schema does not require, an embedded struct on a `GET` or `DELETE` tool all fail boot naming the plugin and the tool), reflects the input schema from the struct and prefixes the exposed name with the plugin's short code (`acme.blog` declaring `create_post` exposes `blog_create_post`).
Every request to the endpoint is authorized afresh from its bearer: an OAuth access token through the `pact.MCPTokenVerifier` the OAuth server plugin publishes, or, behind `mcp.allow_personal_tokens`, a personal API token (an admin `g15_` token through cabana, a frontend token through the published `pact.MCPPersonalTokenResolver`). The resulting `pier.Identity` names a frontend subject and, when the grant carries the `backend` scope and the published `pact.MCPLinkedBackendResolver` confirms a link, a backend subject, but only while that link names the administrator the grant was consented for (`pact.MCPGrant.BackendUserID`): a link changed to anyone else, or a grant that records no consented administrator, gets no backend subject. An administrator-only grant (`pact.MCPGrant.Subject` is `pact.MCPGrantSubjectBackend`, `UserID` 0, `pact.MCPGrant.BackendUserID` set) instead gets a backend subject straight from the grant: no frontend subject even when a frontend guard is registered, no link lookup, its own binding `oauth:backend:<client_id>:<admin_id>`, no read/write ceiling, and `pact.MCPSubject.ScopeLimited` set, so the backend guard caps the administrator with `cabana.ScopeLimitFor` exactly like a `g15_` token with the same scopes. A grant with neither a frontend user nor that subject kind is refused; linked user grants are unchanged and stay uncapped by a scope limit. `tools/list` is computed for that identity: a tool needs a subject under its guard, a grant without `write` sees only read-only tools, and the guard provider's own check (the same logic its route middleware enforces) decides the rest. A `tools/call` runs the bound route's compiled middleware chain in-process with the `bouncer.Dispatch` marker carrying the principal the guard provider resolved, and, immediately before that marker, a `pact.MCPCall` stored with `pact.WithMCPCall`. `pact.MCPCall.Subject` is the subject resolved for the 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 and never the audit word used when a stateful call has no session. A route reads the call with `pact.MCPCallFrom`; a context pier did not dispatch answers false. `pact.MCPSubject.TokenID` is a member personal-token id only when `pact.MCPSubject.ClientID` is empty, and the OAuth access-token row otherwise. `pact.MCPSubject.Scopes` is the grant, not an implied expansion. The read/write ceiling is unchanged: a grant without `write` still sees only read-only tools. The inner request never carries an `Authorization` or `Cookie` header. A 2xx answer becomes text plus structured content, anything else a tool error carrying the route's own body.
Every request to the endpoint is authorized afresh from its bearer: an OAuth access token through the `pact.MCPTokenVerifier` the OAuth server plugin publishes, or, behind `mcp.allow_personal_tokens`, a personal API token (an admin `g15_` token through cabana, a frontend token through the published `pact.MCPPersonalTokenResolver`). The resulting `pier.Identity` names a frontend subject and, when the grant carries the `backend` scope and the published `pact.MCPLinkedBackendResolver` confirms a link, a backend subject, but only while that link names the administrator the grant was consented for (`pact.MCPGrant.BackendUserID`): a link changed to anyone else, or a grant that records no consented administrator, gets no backend subject. An administrator-only grant (`pact.MCPGrant.Subject` is `pact.MCPGrantSubjectBackend`, `UserID` 0, `pact.MCPGrant.BackendUserID` set) instead gets a backend subject straight from the grant: no frontend subject even when a frontend guard is registered, no link lookup, its own binding `oauth:backend:<client_id>:<admin_id>`, no read/write ceiling, and `pact.MCPSubject.ScopeLimited` set, so the backend guard caps the administrator with `cabana.ScopeLimitFor` exactly like a `g15_` token with the same scopes. A grant with neither a frontend user nor that subject kind is refused, and so is one whose `pact.MCPGrant.Subject` is any other non-empty value (never read as a frontend user grant); linked user grants are unchanged and stay uncapped by a scope limit. `tools/list` is computed for that identity: a tool needs a subject under its guard, a grant without `write` sees only read-only tools, and the guard provider's own check (the same logic its route middleware enforces) decides the rest. A `tools/call` runs the bound route's compiled middleware chain in-process with the `bouncer.Dispatch` marker carrying the principal the guard provider resolved, and, immediately before that marker, a `pact.MCPCall` stored with `pact.WithMCPCall`. `pact.MCPCall.Subject` is the subject resolved for the 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 and never the audit word used when a stateful call has no session. A route reads the call with `pact.MCPCallFrom`; a context pier did not dispatch answers false. `pact.MCPSubject.TokenID` is a member personal-token id only when `pact.MCPSubject.ClientID` is empty, and the OAuth access-token row otherwise. `pact.MCPSubject.Scopes` is the grant, not an implied expansion. The read/write ceiling is unchanged: a grant without `write` still sees only read-only tools. The inner request never carries an `Authorization` or `Cookie` header. A 2xx answer becomes text plus structured content, anything else a tool error carrying the route's own body.
Sessions (`Mcp-Session-Id`) are bound to the identity that opened them (client and user, or the personal token), live in a store with a sliding idle TTL, and are served by a per-session SDK server on whichever instance receives the request, rehydrated from the stored session state when it is not local. The memory store serves one instance; the Redis store shares sessions across instances and fans subject events out to every instance, so a permission or link change pushes `notifications/tools/list_changed` to the sessions it concerns and a revocation ends them everywhere. Clients of protocol 2026-07-28 and later, which have no sessions, are served statelessly from the same path by the SDK's stateless handler over per-identity servers, sharing identity, dispatch and filtering with the stateful path.

View File

@@ -82,6 +82,10 @@ func TestBackendOnlyGrant(t *testing.T) {
"oas_at_no_admin": {Subject: pact.MCPGrantSubjectBackend, ClientID: "c1", TokenID: 5, Scopes: []string{"admin:read"}, ExpiresAt: exp},
"oas_at_linked_user": {UserID: 7, BackendUserID: 42, ClientID: "c1", TokenID: 6, Scopes: []string{"read", "backend"}, ExpiresAt: exp},
"oas_at_no_subject_0": {BackendUserID: 7, ClientID: "c1", TokenID: 7, Scopes: []string{"admin:read"}, ExpiresAt: exp},
// An unknown subject kind is refused even when it names a frontend
// user (and a linked administrator), never read as a user grant.
"oas_at_member": {Subject: "member", UserID: 7, BackendUserID: 42, ClientID: "c1", TokenID: 8, Scopes: []string{"read", "backend"}, ExpiresAt: exp},
"oas_at_backend_": {Subject: "Backend", UserID: 7, BackendUserID: 42, ClientID: "c1", TokenID: 9, Scopes: []string{"read"}, ExpiresAt: exp},
}
links := &countingLinks{admin: 42}
r := newIdentityResolver(grantApp(t, verifier, links), Config{}, "user")
@@ -129,7 +133,7 @@ func TestBackendOnlyGrant(t *testing.T) {
t.Fatalf("the linked-backend resolver was called %d times", n)
}
for _, raw := range []string{"oas_at_user_too", "oas_at_no_admin", "oas_at_no_subject_0", "oas_at_unknown"} {
for _, raw := range []string{"oas_at_user_too", "oas_at_no_admin", "oas_at_no_subject_0", "oas_at_member", "oas_at_backend_", "oas_at_unknown"} {
if _, err := r.resolve(ctx, raw); !errors.Is(err, ErrUnauthorized) {
t.Fatalf("%s: err = %v, want ErrUnauthorized", raw, err)
}

View File

@@ -215,8 +215,15 @@ func (r *identityResolver) resolveOAuth(ctx context.Context, raw string) (Identi
if err != nil {
return Identity{}, ErrUnauthorized
}
if grant.Subject == pact.MCPGrantSubjectBackend {
switch grant.Subject {
case pact.MCPGrantSubjectBackend:
return resolveBackendGrant(grant)
case "":
// The frontend user grant, below.
default:
// An unknown subject kind (a newer plugin, a typo) is refused, never
// reinterpreted as a frontend user grant.
return Identity{}, ErrUnauthorized
}
if grant.UserID == 0 {
return Identity{}, ErrUnauthorized