feat(32.2-01): admin consent endpoint for administrator-only MCP grants

- pact: MCPAdminConsent provider interface, MCPAdminConsentRequest,
  MCPAdminConsentDecision, ErrMCPConsentNotFound, ErrMCPConsentNoScopes
- cabana: GET/POST {api}/mcp/consent/{request}, interactive-only, scope
  policy of personal tokens (requested, catalog, owned; * collapses)
- cabana: TokenScopeNames and TokenScopeLabels export the token-scope catalog
- swag views and annotations; admin.json and schema.d.ts regenerated so the
  contract and conformance inventories stay green
- phrasebook keys mcp_connect.request_not_found and no_grantable_scopes
This commit is contained in:
Jakub Zych
2026-11-21 00:14:43 +01:00
parent c63bfa3ef2
commit 97d7ee0586
18 changed files with 1296 additions and 3 deletions

View File

@@ -162,6 +162,10 @@ func (p *BlogPlugin) Schedule() []pact.ScheduledCommand {
| `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.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. |
| `pact.MCPAdminConsentRequest` | A pending request as the administrator's consent screen shows it: request and client ids, client name, logo URL, redirect URI, requested data scopes (`offline_access` excluded), whether `offline_access` was requested, whether consent must be asked and the expiry. |
| `pact.MCPAdminConsentDecision` | The administrator's answer: `Allow`, the scopes to grant (already filtered by the framework) and `OfflineAccess`. |
| `pact.ErrMCPConsentNotFound` / `pact.ErrMCPConsentNoScopes` | What a `pact.MCPAdminConsent` answers for a missing, expired, used or foreign request, and for an allow that leaves nothing to grant. |
| `pact.MCPLinkedBackendResolver` | Published by the plugin that owns the frontend-to-backend account link: the `pact.LinkedBackendUser` (id, login, display name) of a frontend user, false when unlinked. |
| `pact.MCPSubjectChanged` | Event fired on the festival bus when a subject's permissions, link, grants or existence change (`Kind` is `pact.MCPSubjectPermissions`, `pact.MCPSubjectLink`, `pact.MCPSubjectRevoked` or `pact.MCPSubjectDeleted`), so the MCP endpoint re-lists tools or ends sessions. `TokenID` and `ClientID` narrow a revoked event: a token id ends only the sessions that personal token opened (subject with that `TokenID` and no `ClientID`), a client id only that OAuth client's sessions, neither every session of the subject; other kinds ignore them. |
| `pact.FrontendPermission` | One frontend permission code a plugin declares: `Code`, `Label`, `Tab` and `Comment`, offered in the user plugin's permission editors next to the seeded codes. |

View File

@@ -334,6 +334,65 @@ type MCPPersonalTokenResolver interface {
MCPResolvePersonalToken(ctx context.Context, raw string) (MCPSubject, bool, error)
}
// MCPAdminConsent serves the consent screen of administrator-only MCP
// grants (MCPGrantSubjectBackend) to the framework's admin API. One
// provider per application, published through app.Publish by the plugin
// that owns the MCP authorization server. The framework serves the
// cookie-authenticated consent endpoints for the signed-in administrator
// and owns the scope policy: it shows only requested scopes the
// administrator can grant and filters a decision the same way before it
// calls MCPAdminConsentDecide, so the provider only resolves and issues.
//
// MCPAdminConsentShow answers the pending request requestID for the
// administrator adminID; a missing, expired, used or foreign request is
// ErrMCPConsentNotFound. MCPAdminConsentDecide allows or denies it and
// answers the client redirect URI to send the browser to (carrying the
// code, or the access_denied error); ErrMCPConsentNotFound as for Show,
// ErrMCPConsentNoScopes when an allow decision leaves nothing to grant.
type MCPAdminConsent interface {
MCPAdminConsentShow(ctx context.Context, adminID uint, requestID string) (MCPAdminConsentRequest, error)
MCPAdminConsentDecide(ctx context.Context, adminID uint, requestID string, decision MCPAdminConsentDecision) (string, error)
}
// MCPAdminConsentRequest is one pending MCP authorization request as the
// administrator's consent screen shows it: the request id, the client (id,
// name, logo and the redirect URI the browser returns to), the requested
// data scopes (offline_access excluded), whether offline_access was
// requested, whether consent must be asked (false when this client was
// allowed before) and the request's expiry.
type MCPAdminConsentRequest struct {
RequestID string
ClientID string
ClientName string
LogoURL string
RedirectURI string
Scopes []string
OfflineAccess bool
ConsentRequired bool
ExpiresAt time.Time
}
// MCPAdminConsentDecision is the administrator's answer to a consent
// request: Allow, the scopes to grant (already filtered by the framework to
// requested scopes the administrator can grant, with * collapsed as for
// personal tokens) and OfflineAccess (a refresh token; only when it was
// requested). A deny carries no scopes.
type MCPAdminConsentDecision struct {
Allow bool
Scopes []string
OfflineAccess bool
}
// ErrMCPConsentNotFound is what an MCPAdminConsent answers for a consent
// request that does not exist, expired, was used or belongs to someone
// else; the admin API answers 404 request_not_found.
var ErrMCPConsentNotFound = errors.New("pact: mcp consent request not found")
// ErrMCPConsentNoScopes is what MCPAdminConsentDecide answers when an allow
// decision leaves no scope to grant; the admin API answers 422
// no_grantable_scopes.
var ErrMCPConsentNoScopes = errors.New("pact: mcp consent has no grantable scopes")
// MCPLinkedBackendResolver answers the verified backend account linked to a
// frontend user, published by the plugin that owns the link. The boolean is
// false when the user has no link.