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

@@ -36,10 +36,12 @@ var ErrUnauthorized = errors.New("pier: unauthorized")
// Identity is who one MCP request acts as: the frontend subject (the OAuth
// grant's user or a frontend personal token), the backend subject (the
// linked admin when the grant carries the backend scope, or an admin
// personal token), the scopes of the credential, the session binding key
// (D-35: oauth:<client_id>:<user_id>, pat:user:<token_id> or
// pat:backend:<token_id>), the credential's expiry and its kind. Every
// linked admin when the grant carries the backend scope, the administrator
// of an administrator-only grant, or an admin personal token), the scopes
// of the credential, the session binding key (D-35:
// oauth:<client_id>:<user_id>, oauth:backend:<client_id>:<admin_id>,
// pat:user:<token_id> or pat:backend:<token_id>), the credential's expiry
// and its kind. Every
// request resolves its own Identity from its bearer; a session never
// replaces it.
type Identity struct {
@@ -82,8 +84,9 @@ func (id Identity) writes() bool {
}
// fingerprint encodes the authorization-relevant parts of the identity
// (P-26): the sorted scopes, both subjects (guard, user, client and their
// sorted scopes), the ceiling and the token kind. Two requests of one
// (P-26): the sorted scopes, both subjects (guard, user, client, their
// sorted scopes and whether they are scope-limited), the ceiling and the
// token kind. Two requests of one
// binding with different fingerprints may see different tools, so a cached
// server is re-filtered when it changes (A-WR-04). Token ids are left out:
// a guard decides on scopes, subjects and the ceiling, not on which token
@@ -108,6 +111,8 @@ func (id Identity) fingerprint() string {
b.WriteString(s.ClientID)
b.WriteByte(':')
b.WriteString(sorted(s.Scopes))
b.WriteByte(':')
b.WriteString(strconv.FormatBool(s.ScopeLimited))
b.WriteByte('|')
}
b.WriteString(sorted(id.Scopes))
@@ -207,7 +212,13 @@ func (r *identityResolver) resolveOAuth(ctx context.Context, raw string) (Identi
return Identity{}, ErrUnauthorized
}
grant, err := verifier.MCPVerifyToken(ctx, raw)
if err != nil || grant.UserID == 0 {
if err != nil {
return Identity{}, ErrUnauthorized
}
if grant.Subject == pact.MCPGrantSubjectBackend {
return resolveBackendGrant(grant)
}
if grant.UserID == 0 {
return Identity{}, ErrUnauthorized
}
scopes := append([]string(nil), grant.Scopes...)
@@ -232,6 +243,36 @@ func (r *identityResolver) resolveOAuth(ctx context.Context, raw string) (Identi
return id, nil
}
// resolveBackendGrant is the Identity of an administrator-only OAuth grant
// (pact.MCPGrantSubjectBackend): the backend subject is the administrator
// in BackendUserID, taken straight from the grant without a link lookup,
// and there is no frontend subject even when a frontend guard is
// registered. The binding oauth:backend:<client>:<admin> never collides
// with a user grant's oauth:<client>:<user>. The read/write ceiling is off
// and the subject is ScopeLimited, so the backend guard caps it with the
// scope limit a personal token with the same scopes gets. A grant that
// names a frontend user or no administrator is refused.
func resolveBackendGrant(grant pact.MCPGrant) (Identity, error) {
if grant.UserID != 0 || grant.BackendUserID == 0 {
return Identity{}, ErrUnauthorized
}
scopes := append([]string(nil), grant.Scopes...)
return Identity{
Scopes: scopes,
Binding: "oauth:backend:" + grant.ClientID + ":" + strconv.FormatUint(uint64(grant.BackendUserID), 10),
ExpiresAt: grant.ExpiresAt,
TokenKind: TokenKindOAuth,
Backend: &pact.MCPSubject{
Guard: BackendGuard,
UserID: grant.BackendUserID,
Scopes: append([]string(nil), scopes...),
ClientID: grant.ClientID,
TokenID: grant.TokenID,
ScopeLimited: true,
},
}, nil
}
// consentedBackendSubject is the backend subject of an OAuth grant of
// userID: the linked administrator, when the grant carries the backend
// scope and the link names consented, the account the grant was consented