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

@@ -137,6 +137,14 @@ type MCPSubject struct {
Scopes []string
ClientID string
TokenID uint
// ScopeLimited, when true, makes the backend guard cap the subject with
// the same scope limit a personal token with these Scopes gets, so the
// subject can do no more than its scopes allow even where its account
// could. The MCP endpoint sets it on the backend subject of an
// administrator-only OAuth grant (MCPGrantSubjectBackend). False keeps
// today's rule: only a personal-token subject (TokenID set, no
// ClientID) is scope-limited.
ScopeLimited bool
}
// mcpCallKey is the unexported context key of an MCPCall. A plain HTTP
@@ -274,23 +282,41 @@ type MemberTokenScopeCatalog interface {
MemberTokenScopes() []FrontendTokenScope
}
// MCPGrant is a verified OAuth access token: the frontend user, the client,
// the token row, the granted scopes, the expiry and, for a grant carrying
// the backend scope, the backend account the user consented to.
// MCPGrant is a verified OAuth access token: the client, the token row, the
// granted scopes, the expiry and the subject the token acts as. With Subject
// empty that is the frontend user in UserID and, for a grant carrying the
// backend scope, the backend account the user consented to. With Subject
// MCPGrantSubjectBackend it is the administrator in BackendUserID alone.
type MCPGrant struct {
UserID uint
ClientID string
TokenID uint
Scopes []string
ExpiresAt time.Time
// BackendUserID is the backend account the consent page showed when
// the user granted the backend scope. The MCP endpoint gives the grant
// a backend subject only while the user's current link names this
// BackendUserID is the backend account of the grant. With Subject
// empty it is the account the consent page showed when the user
// granted the backend scope: the MCP endpoint gives the grant a
// backend subject only while the user's current link names this
// account, so a grant never acts as an administrator its consent did
// not show; zero (none recorded) gives no backend subject.
// not show, and zero (none recorded) gives no backend subject. With
// Subject MCPGrantSubjectBackend it is the administrator who signed in
// and consented, and the grant's only subject.
BackendUserID uint
// 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.
Subject string
}
// MCPGrantSubjectBackend is the MCPGrant.Subject of an administrator-only
// grant: the subject is the backend account in BackendUserID, UserID is 0
// and no frontend user is involved. The MCP endpoint gives such a grant a
// backend subject straight from BackendUserID (no link lookup), keys its
// sessions on oauth:backend:<client>:<admin> and scope-limits it like a
// personal token with the same scopes (MCPSubject.ScopeLimited).
const MCPGrantSubjectBackend = "backend"
// ErrMCPTokenInvalid is what an MCPTokenVerifier answers for a token it does
// not accept.
var ErrMCPTokenInvalid = errors.New("pact: mcp token invalid")