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

@@ -396,6 +396,88 @@ func AdminAccountContributions() {}
// @Router /account/contributions/{name}/actions/{action} [post]
func AdminAccountContributionAction() {}
// MCPConsentView is a pending MCP authorization request of an
// administrator-only grant, for the signed-in administrator's consent
// screen: the client, the administrator the grant would act as, the
// requested scopes this administrator can grant (catalog order, others
// hidden), whether offline access was requested, whether consent must be
// asked (false when the client was allowed before) and the expiry (RFC 3339).
type MCPConsentView struct {
RequestID string `json:"request_id"`
Client MCPConsentClientView `json:"client"`
Admin MCPConsentAdminView `json:"admin"`
Scopes []AdminAPITokenScope `json:"scopes"`
OfflineAccess bool `json:"offline_access"`
ConsentRequired bool `json:"consent_required"`
ExpiresAt string `json:"expires_at"`
}
// MCPConsentClientView is the client of a consent request: its id, name,
// logo and redirect host (the host of the redirect URI, or the URI without
// query when it has no host).
type MCPConsentClientView struct {
ID string `json:"id"`
Name string `json:"name"`
RedirectHost string `json:"redirect_host"`
LogoURL string `json:"logo_url"`
}
// MCPConsentAdminView is the administrator a consent grants access as.
type MCPConsentAdminView struct {
Login string `json:"login"`
Name string `json:"name"`
Email string `json:"email"`
}
// MCPConsentDecisionRequest is the POST /mcp/consent/{request} body:
// decision allow or deny, the scopes to grant and whether to stay
// connected (offline access). Unknown fields are refused.
type MCPConsentDecisionRequest struct {
Decision string `json:"decision" enums:"allow,deny"`
Scopes []string `json:"scopes"`
OfflineAccess bool `json:"offline_access"`
}
// MCPConsentDecisionView is the answer to a decision: the client redirect
// URI to send the browser to.
type MCPConsentDecisionView struct {
RedirectURI string `json:"redirect_uri"`
}
// AdminMCPConsentShow documents GET /mcp/consent/{request}.
//
// @Summary Show an MCP consent request
// @Description Shows a pending MCP authorization request of an administrator-only grant to the signed-in admin, as the plugin that owns the MCP authorization server resolves it. Only requested scopes the admin can grant are listed. 404 request_not_found when the request is missing, expired or used, or no plugin serves admin consent. Personal API tokens are refused (403 interactive_only).
// @Tags admin
// @Produce json
// @Security BackendBearer
// @Param request path string true "Pending request id"
// @Success 200 {object} Envelope[MCPConsentView]
// @Failure 401 {object} ErrorEnvelope
// @Failure 403 {object} ErrorEnvelope
// @Failure 404 {object} ErrorEnvelope
// @Router /mcp/consent/{request} [get]
func AdminMCPConsentShow() {}
// AdminMCPConsentDecide documents POST /mcp/consent/{request}.
//
// @Summary Allow or deny an MCP consent request
// @Description Allows or denies a pending MCP authorization request for the signed-in admin and answers the client redirect URI. Submitted scopes that were not requested or that the admin cannot grant are dropped, * collapses as for personal tokens, and 422 no_grantable_scopes answers when nothing is left. Needs X-Requested-With; the body is capped at 16 KiB and unknown fields are refused (400). Personal API tokens are refused (403 interactive_only).
// @Tags admin
// @Accept json
// @Produce json
// @Security BackendBearer
// @Param request path string true "Pending request id"
// @Param body body MCPConsentDecisionRequest true "Decision"
// @Success 200 {object} Envelope[MCPConsentDecisionView]
// @Failure 400 {object} ErrorEnvelope
// @Failure 401 {object} ErrorEnvelope
// @Failure 403 {object} ErrorEnvelope
// @Failure 404 {object} ErrorEnvelope
// @Failure 422 {object} ErrorEnvelope
// @Router /mcp/consent/{request} [post]
func AdminMCPConsentDecide() {}
// AdminAccountTokenScopes documents GET /account/tokens/scopes.
//
// @Summary List available API token scopes