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

@@ -1338,6 +1338,36 @@
], ],
"type": "object" "type": "object"
}, },
"cabana.Envelope-cabana_MCPConsentDecisionView": {
"properties": {
"data": {
"$ref": "#/components/schemas/cabana.MCPConsentDecisionView"
},
"meta": {
"$ref": "#/components/schemas/cabana.SuccessMeta"
}
},
"required": [
"data",
"meta"
],
"type": "object"
},
"cabana.Envelope-cabana_MCPConsentView": {
"properties": {
"data": {
"$ref": "#/components/schemas/cabana.MCPConsentView"
},
"meta": {
"$ref": "#/components/schemas/cabana.SuccessMeta"
}
},
"required": [
"data",
"meta"
],
"type": "object"
},
"cabana.Envelope-cabana_PartialView": { "cabana.Envelope-cabana_PartialView": {
"properties": { "properties": {
"data": { "data": {
@@ -2586,6 +2616,123 @@
], ],
"type": "object" "type": "object"
}, },
"cabana.MCPConsentAdminView": {
"properties": {
"email": {
"type": "string"
},
"login": {
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"email",
"login",
"name"
],
"type": "object"
},
"cabana.MCPConsentClientView": {
"properties": {
"id": {
"type": "string"
},
"logo_url": {
"type": "string"
},
"name": {
"type": "string"
},
"redirect_host": {
"type": "string"
}
},
"required": [
"id",
"logo_url",
"name",
"redirect_host"
],
"type": "object"
},
"cabana.MCPConsentDecisionRequest": {
"properties": {
"decision": {
"enum": [
"allow",
"deny"
],
"type": "string"
},
"offline_access": {
"type": "boolean"
},
"scopes": {
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"decision",
"offline_access",
"scopes"
],
"type": "object"
},
"cabana.MCPConsentDecisionView": {
"properties": {
"redirect_uri": {
"type": "string"
}
},
"required": [
"redirect_uri"
],
"type": "object"
},
"cabana.MCPConsentView": {
"properties": {
"admin": {
"$ref": "#/components/schemas/cabana.MCPConsentAdminView"
},
"client": {
"$ref": "#/components/schemas/cabana.MCPConsentClientView"
},
"consent_required": {
"type": "boolean"
},
"expires_at": {
"type": "string"
},
"offline_access": {
"type": "boolean"
},
"request_id": {
"type": "string"
},
"scopes": {
"items": {
"$ref": "#/components/schemas/cabana.AdminAPITokenScope"
},
"type": "array"
}
},
"required": [
"admin",
"client",
"consent_required",
"expires_at",
"offline_access",
"request_id",
"scopes"
],
"type": "object"
},
"cabana.MarketplaceMeta": { "cabana.MarketplaceMeta": {
"properties": { "properties": {
"categories": { "categories": {
@@ -4960,6 +5107,169 @@
] ]
} }
}, },
"/mcp/consent/{request}": {
"get": {
"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).",
"parameters": [
{
"description": "Pending request id",
"in": "path",
"name": "request",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/cabana.Envelope-cabana_MCPConsentView"
}
}
},
"description": "OK"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/cabana.ErrorEnvelope"
}
}
},
"description": "Unauthorized"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/cabana.ErrorEnvelope"
}
}
},
"description": "Forbidden"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/cabana.ErrorEnvelope"
}
}
},
"description": "Not Found"
}
},
"security": [
{
"BackendBearer": []
}
],
"summary": "Show an MCP consent request",
"tags": [
"admin"
]
},
"post": {
"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).",
"parameters": [
{
"description": "Pending request id",
"in": "path",
"name": "request",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/cabana.MCPConsentDecisionRequest"
}
}
},
"description": "Decision",
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/cabana.Envelope-cabana_MCPConsentDecisionView"
}
}
},
"description": "OK"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/cabana.ErrorEnvelope"
}
}
},
"description": "Bad Request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/cabana.ErrorEnvelope"
}
}
},
"description": "Unauthorized"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/cabana.ErrorEnvelope"
}
}
},
"description": "Forbidden"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/cabana.ErrorEnvelope"
}
}
},
"description": "Not Found"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/cabana.ErrorEnvelope"
}
}
},
"description": "Unprocessable Entity"
}
},
"security": [
{
"BackendBearer": []
}
],
"summary": "Allow or deny an MCP consent request",
"tags": [
"admin"
]
}
},
"/navigation": { "/navigation": {
"get": { "get": {
"responses": { "responses": {

View File

@@ -1559,6 +1559,151 @@ export interface paths {
patch?: never; patch?: never;
trace?: never; trace?: never;
}; };
"/mcp/consent/{request}": {
parameters: {
query?: never;
header?: never;
path?: never;
cookie?: never;
};
/**
* 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).
*/
get: {
parameters: {
query?: never;
header?: never;
path: {
/** @description Pending request id */
request: string;
};
cookie?: never;
};
requestBody?: never;
responses: {
/** @description OK */
200: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["cabana.Envelope-cabana_MCPConsentView"];
};
};
/** @description Unauthorized */
401: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["cabana.ErrorEnvelope"];
};
};
/** @description Forbidden */
403: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["cabana.ErrorEnvelope"];
};
};
/** @description Not Found */
404: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["cabana.ErrorEnvelope"];
};
};
};
};
put?: never;
/**
* 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).
*/
post: {
parameters: {
query?: never;
header?: never;
path: {
/** @description Pending request id */
request: string;
};
cookie?: never;
};
/** @description Decision */
requestBody: {
content: {
"application/json": components["schemas"]["cabana.MCPConsentDecisionRequest"];
};
};
responses: {
/** @description OK */
200: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["cabana.Envelope-cabana_MCPConsentDecisionView"];
};
};
/** @description Bad Request */
400: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["cabana.ErrorEnvelope"];
};
};
/** @description Unauthorized */
401: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["cabana.ErrorEnvelope"];
};
};
/** @description Forbidden */
403: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["cabana.ErrorEnvelope"];
};
};
/** @description Not Found */
404: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["cabana.ErrorEnvelope"];
};
};
/** @description Unprocessable Entity */
422: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["cabana.ErrorEnvelope"];
};
};
};
};
delete?: never;
options?: never;
head?: never;
patch?: never;
trace?: never;
};
"/navigation": { "/navigation": {
parameters: { parameters: {
query?: never; query?: never;
@@ -6429,6 +6574,14 @@ export interface components {
data: components["schemas"]["cabana.ListSchema"]; data: components["schemas"]["cabana.ListSchema"];
meta: components["schemas"]["cabana.SuccessMeta"]; meta: components["schemas"]["cabana.SuccessMeta"];
}; };
"cabana.Envelope-cabana_MCPConsentDecisionView": {
data: components["schemas"]["cabana.MCPConsentDecisionView"];
meta: components["schemas"]["cabana.SuccessMeta"];
};
"cabana.Envelope-cabana_MCPConsentView": {
data: components["schemas"]["cabana.MCPConsentView"];
meta: components["schemas"]["cabana.SuccessMeta"];
};
"cabana.Envelope-cabana_PartialView": { "cabana.Envelope-cabana_PartialView": {
data: components["schemas"]["cabana.PartialView"]; data: components["schemas"]["cabana.PartialView"];
meta: components["schemas"]["cabana.SuccessMeta"]; meta: components["schemas"]["cabana.SuccessMeta"];
@@ -6911,6 +7064,35 @@ export interface components {
column: string; column: string;
direction: string; direction: string;
}; };
"cabana.MCPConsentAdminView": {
email: string;
login: string;
name: string;
};
"cabana.MCPConsentClientView": {
id: string;
logo_url: string;
name: string;
redirect_host: string;
};
"cabana.MCPConsentDecisionRequest": {
/** @enum {string} */
decision: "allow" | "deny";
offline_access: boolean;
scopes: string[];
};
"cabana.MCPConsentDecisionView": {
redirect_uri: string;
};
"cabana.MCPConsentView": {
admin: components["schemas"]["cabana.MCPConsentAdminView"];
client: components["schemas"]["cabana.MCPConsentClientView"];
consent_required: boolean;
expires_at: string;
offline_access: boolean;
request_id: string;
scopes: components["schemas"]["cabana.AdminAPITokenScope"][];
};
"cabana.MarketplaceMeta": { "cabana.MarketplaceMeta": {
categories: string[]; categories: string[];
registry: components["schemas"]["cabana.RegistryState"]; registry: components["schemas"]["cabana.RegistryState"];

View File

@@ -118,6 +118,8 @@ The authorization endpoint sends the browser to `<issuer>/connect?request=<id>`,
An OAuth server plugin that signs administrators in instead of frontend users answers its verifier's grants with `pact.MCPGrant.Subject` set to `pact.MCPGrantSubjectBackend`, `UserID` 0 and the administrator in `pact.MCPGrant.BackendUserID`. The MCP endpoint then acts as that administrator only, scope-limited like a `g15_` token with the granted scopes (see [MCP](mcp.md)). An OAuth server plugin that signs administrators in instead of frontend users answers its verifier's grants with `pact.MCPGrant.Subject` set to `pact.MCPGrantSubjectBackend`, `UserID` 0 and the administrator in `pact.MCPGrant.BackendUserID`. The MCP endpoint then acts as that administrator only, scope-limited like a `g15_` token with the granted scopes (see [MCP](mcp.md)).
The consent page of such grants is the admin's own: the plugin sets `wristband.Options.ConsentPath` to a page under the admin prefix and publishes a `pact.MCPAdminConsent`. cabana serves `GET` and `POST {admin api}/mcp/consent/{request}` for the signed-in administrator (cookie session only, the POST with `X-Requested-With`) and delegates to that provider: `pact.MCPAdminConsent.MCPAdminConsentShow` describes the pending request as a `pact.MCPAdminConsentRequest`, `pact.MCPAdminConsent.MCPAdminConsentDecide` issues the code or the denial for a `pact.MCPAdminConsentDecision` and answers the redirect URI. cabana owns the scope policy, the same as for `g15_` personal tokens: the scopes are the token-scope catalog (`cabana.TokenScopeNames`, labels through `cabana.TokenScopeLabels`), the screen shows only requested scopes the administrator can grant, and an allow drops anything else before Decide runs (`*` collapses as on token creation). A missing provider or request is 404 `request_not_found` (`pact.ErrMCPConsentNotFound`), and nothing left to grant is 422 `no_grantable_scopes` (`pact.ErrMCPConsentNoScopes`).
## Clients created outside registration ## Clients created outside registration
Operator tooling that creates clients directly uses the same rules as registration. `wristband.RejectRedirectURI` accepts `https://` URIs and loopback `http://` URIs only: Operator tooling that creates clients directly uses the same rules as registration. `wristband.RejectRedirectURI` accepts `https://` URIs and loopback `http://` URIs only:

View File

@@ -92,6 +92,8 @@ Guarded routes run surf's `locale.from-principal` after the backend guard: an in
| DELETE `/account/tokens/{id}` | Soft-revoke one of the caller's own active tokens (`cabana.AdminAPIToken`); 404 otherwise. Interactive session only. | | DELETE `/account/tokens/{id}` | Soft-revoke one of the caller's own active tokens (`cabana.AdminAPIToken`); 404 otherwise. Interactive session only. |
| GET `/account/tokens/scopes` | Scopes the caller may assign (`cabana.AdminAPITokenScope`), including `*`, `admin:read` and overlapping plugin scopes. Interactive session only. | | GET `/account/tokens/scopes` | Scopes the caller may assign (`cabana.AdminAPITokenScope`), including `*`, `admin:read` and overlapping plugin scopes. Interactive session only. |
| GET `/account/contributions` | The sections plugins contribute to My account (`cabana.AccountContributionView`): translated label, description and status for the signed-in administrator, and the actions (`cabana.AccountContributionActionView`) they hold the permissions for and whose `Applies` reports true. A section whose status or one of whose actions' `Applies` failed carries `error: true`. An empty list when no plugin contributes. Interactive session only. | | GET `/account/contributions` | The sections plugins contribute to My account (`cabana.AccountContributionView`): translated label, description and status for the signed-in administrator, and the actions (`cabana.AccountContributionActionView`) they hold the permissions for and whose `Applies` reports true. A section whose status or one of whose actions' `Applies` failed carries `error: true`. An empty list when no plugin contributes. Interactive session only. |
| GET `/mcp/consent/{request}` | A pending MCP authorization request of an administrator-only grant (`cabana.MCPConsentView`), resolved by the published `pact.MCPAdminConsent` for the signed-in administrator: the client (`cabana.MCPConsentClientView`, with the redirect URI's host), the administrator (`cabana.MCPConsentAdminView`: login, name, email), the requested scopes the administrator can grant in catalog order (`cabana.AdminAPITokenScope`; scopes outside the catalog or without an owned permission are hidden, as in the token picker), `offline_access` (requested), `consent_required` and `expires_at`. 404 `request_not_found` when no provider is published or the request is unknown. Interactive session only. |
| POST `/mcp/consent/{request}` | Allow or deny that request (`cabana.MCPConsentDecisionRequest`: `decision` `allow` or `deny`, `scopes`, `offline_access`; at most 16 KiB, unknown fields 400). An allow keeps the submitted scopes that were requested and can be granted (others are dropped), normalises them like token creation (`*` collapses to `["*"]`), answers 422 `no_grantable_scopes` when nothing is left and grants offline access only when it was requested and asked for; the answer is `cabana.MCPConsentDecisionView` (`redirect_uri`). cabana opens no transaction: the provider owns it. Interactive session only, AJAX header required. |
| POST `/account/contributions/{name}/actions/{action}` | Run one contributed action for the signed-in administrator: 404 for an unknown section or action, 403 without the action's permissions, 409 when it no longer applies; `Run` gets the administrator's id inside a transaction and answers `cabana.AccountActionResultView` (translated `message`, optional `url`, only an `http`/`https` or same-origin URL). Interactive session only, AJAX header required. | | POST `/account/contributions/{name}/actions/{action}` | Run one contributed action for the signed-in administrator: 404 for an unknown section or action, 403 without the action's permissions, 409 when it no longer applies; `Run` gets the administrator's id inside a transaction and answers `cabana.AccountActionResultView` (translated `message`, optional `url`, only an `http`/`https` or same-origin URL). Interactive session only, AJAX header required. |
| GET `/navigation`, GET `/settings` | Navigation and settings entries the administrator may open and, for a navigation entry with a `Visible` func, that it answers true for the request; a settings entry's `controller` names the admin controller a link entry opens and is empty for a singleton form, and `path` (only on the admin's own Plugins entry) names the SPA route it opens. | | GET `/navigation`, GET `/settings` | Navigation and settings entries the administrator may open and, for a navigation entry with a `Visible` func, that it answers true for the request; a settings entry's `controller` names the admin controller a link entry opens and is empty for a singleton form, and `path` (only on the admin's own Plugins entry) names the SPA route it opens. |
| GET `/plugins` | The Plugins screen (`cabana.PluginsOverview`): the framework version the application was built with, the registry state (`cabana.RegistryState`: `enabled`, `status` ok, disabled or unavailable) and every activated plugin in summer.yaml order (`cabana.InstalledPlugin`) with, for a plugin the registry lists, `latest`, `updateAvailable`, `updateCommand` and `latestFramework`. 403 without `cabana.PermissionViewPlugins`. | | GET `/plugins` | The Plugins screen (`cabana.PluginsOverview`): the framework version the application was built with, the registry state (`cabana.RegistryState`: `enabled`, `status` ok, disabled or unavailable) and every activated plugin in summer.yaml order (`cabana.InstalledPlugin`) with, for a plugin the registry lists, `latest`, `updateAvailable`, `updateCommand` and `latestFramework`. 403 without `cabana.PermissionViewPlugins`. |
@@ -279,6 +281,9 @@ func (p *BlogPlugin) AdminFS() fs.FS { return os.DirFS("testdata/docs") }
| `cabana.ErrUnauthenticated` / `cabana.ErrTokenScope` | Sentinel errors from `cabana.ResolveBackend`. | | `cabana.ErrUnauthenticated` / `cabana.ErrTokenScope` | Sentinel errors from `cabana.ResolveBackend`. |
| `cabana.ResolveBackendToken` | Resolves a `g15_` token outside any request (same hash lookup, usability window, admin load and `last_used_at` stamp as the guard) without the request-method scope filter; returns the principal, the token row and the stored scope names. For an in-process dispatcher that opens a session with a personal token. Each attempt is logged as `admin.auth` with the client address the caller put on the context (`towel.ClientIP`). | | `cabana.ResolveBackendToken` | Resolves a `g15_` token outside any request (same hash lookup, usability window, admin load and `last_used_at` stamp as the guard) without the request-method scope filter; returns the principal, the token row and the stored scope names. For an in-process dispatcher that opens a session with a personal token. Each attempt is logged as `admin.auth` with the client address the caller put on the context (`towel.ClientIP`). |
| `cabana.ScopeLimitFor` | Filters stored scope names by one HTTP method into the `bouncer.ScopeLimit` the guard would set for a request with that method, with the known and method-allowed counts. | | `cabana.ScopeLimitFor` | Filters stored scope names by one HTTP method into the `bouncer.ScopeLimit` the guard would set for a request with that method, with the known and method-allowed counts. |
| `cabana.TokenScopeNames` | The personal-token scope catalog names in catalog order (`*`, `admin:read`, then the plugins' `TokenScopes`), compiled from the activated plugins, so it works at plugin Boot before `cabana.Activate`. |
| `cabana.TokenScopeLabels` | The translated label of each catalog scope name, the name itself for an unknown one, in input order. |
| `cabana.MCPConsentView` / `cabana.MCPConsentClientView` / `cabana.MCPConsentAdminView` / `cabana.MCPConsentDecisionRequest` / `cabana.MCPConsentDecisionView` | JSON shapes of the MCP consent routes. `cabana.AdminMCPConsentShow` and `cabana.AdminMCPConsentDecide` carry their swag annotations. |
| `cabana.BackendPrincipal` | Loads an admin principal by id through the backend users provider (grants, superuser flag, backend kind set); nil, nil for a missing or deactivated admin. | | `cabana.BackendPrincipal` | Loads an admin principal by id through the backend users provider (grants, superuser flag, backend kind set); nil, nil for a missing or deactivated admin. |
| `cabana.AdminAPIToken` / `cabana.AdminAPITokenScope` / `cabana.AdminAPITokenCreated` / `cabana.AdminAPITokenRequest` | JSON shapes of the account token API. | | `cabana.AdminAPIToken` / `cabana.AdminAPITokenScope` / `cabana.AdminAPITokenCreated` / `cabana.AdminAPITokenRequest` | JSON shapes of the account token API. |
| `cabana.AccountContributionView` / `cabana.AccountContributionActionView` / `cabana.AccountActionResultView` | JSON shapes of the My account contribution routes: a contributed section with its status and offered actions, one action, and an action's answer (message and optional URL). | | `cabana.AccountContributionView` / `cabana.AccountContributionActionView` / `cabana.AccountActionResultView` | JSON shapes of the My account contribution routes: a contributed section with its status and offered actions, one action, and an action's answer (message and optional URL). |
@@ -455,6 +460,8 @@ The Phase 18.1 pieces (the taglist field and the flat reorder) are covered by Do
`ClearOnChange` is covered by `clear_on_change_field_test.go` (TestClearOnChangeFieldBoot, Docker-free, and TestClearOnChangeBelongsTo on Postgres: a changed, emptied, kept or co-submitted belongsTo key) and `clear_on_change_test.go` (TestClearOnChangeRelationBoot and, on Postgres, TestClearOnChangeHasMany: link, unlink and a deferred link committed by the parent's first save). `ClearOnChange` is covered by `clear_on_change_field_test.go` (TestClearOnChangeFieldBoot, Docker-free, and TestClearOnChangeBelongsTo on Postgres: a changed, emptied, kept or co-submitted belongsTo key) and `clear_on_change_test.go` (TestClearOnChangeRelationBoot and, on Postgres, TestClearOnChangeHasMany: link, unlink and a deferred link committed by the parent's first save).
The MCP consent routes are covered by the Postgres test TestMCPAdminConsentSmoke in `mcp_consent_smoke_test.go`, over a fake `pact.MCPAdminConsent`: hidden scopes, a dropped `*` that was not requested, a requested `*` collapsing the grant, offline access, deny, 400 for a bad body, 401 anonymous, 403 `interactive_only` for a `g15_` token and 404 without a provider or for an unknown request. TestTokenScopeNamesAndLabels covers the exported catalog names and labels.
The toolbar and widget action run log is covered by the Postgres test TestAdminActionRunLog in `action_run_log_test.go`: who ran the action, its kind, the field and record id of a widget run, no posted or returned content, and no line for refused, invalid or failed runs. The toolbar and widget action run log is covered by the Postgres test TestAdminActionRunLog in `action_run_log_test.go`: who ran the action, its kind, the field and record id of a widget run, no posted or returned content, and no line for refused, invalid or failed runs.
A Detached bulk action (`pact.AdminBulkAction.Detached`) is covered by the Postgres test TestDetachedBulkAction in `bulk_detached_test.go`, on the roster fixture with two test-only actions: Run sees no transaction (`TxFromContext`) and holds no row lock (another connection's `SELECT ... FOR UPDATE NOWAIT` succeeds during Run); the empty, absent and partial-selection rules match the locked path; a `ValidationError` from Run is 422 and the rows written before it stay written; the same action without Detached still runs in the transaction holding the row locks. `scripts/check-phase18.1.sh` requires it in its postgres stage. A Detached bulk action (`pact.AdminBulkAction.Detached`) is covered by the Postgres test TestDetachedBulkAction in `bulk_detached_test.go`, on the roster fixture with two test-only actions: Run sees no transaction (`TxFromContext`) and holds no row lock (another connection's `SELECT ... FOR UPDATE NOWAIT` succeeds during Run); the empty, absent and partial-selection rules match the locked path; a `ValidationError` from Run is 422 and the rows written before it stay written; the same action without Detached still runs in the transaction holding the row locks. `scripts/check-phase18.1.sh` requires it in its postgres stage.

View File

@@ -396,6 +396,88 @@ func AdminAccountContributions() {}
// @Router /account/contributions/{name}/actions/{action} [post] // @Router /account/contributions/{name}/actions/{action} [post]
func AdminAccountContributionAction() {} 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. // AdminAccountTokenScopes documents GET /account/tokens/scopes.
// //
// @Summary List available API token scopes // @Summary List available API token scopes

View File

@@ -348,6 +348,10 @@ func (s *service) mount(r pact.Router) {
// Sections plugins contribute to My account (pact.HasAccountContributions). // Sections plugins contribute to My account (pact.HasAccountContributions).
g.Get("/account/contributions", interactiveOnly(s.accountContributionsList)) g.Get("/account/contributions", interactiveOnly(s.accountContributionsList))
g.Post("/account/contributions/{name}/actions/{action}", interactiveOnly(requireAjax(s.accountContributionAction))) g.Post("/account/contributions/{name}/actions/{action}", interactiveOnly(requireAjax(s.accountContributionAction)))
// Consent of administrator-only MCP grants, served for the
// published pact.MCPAdminConsent (404 when none is published).
g.Get("/mcp/consent/{request}", interactiveOnly(s.mcpConsentShow))
g.Post("/mcp/consent/{request}", interactiveOnly(requireAjax(s.mcpConsentDecide)))
g.Get("/navigation", s.navigation) g.Get("/navigation", s.navigation)
// Plugin field types (pact.HasFormFieldTypes): the SPA loads their // Plugin field types (pact.HasFormFieldTypes): the SPA loads their
// scripts and styles once after sign-in. // scripts and styles once after sign-in.

View File

@@ -0,0 +1,233 @@
package cabana
import (
"encoding/json"
"errors"
"io"
"net/http"
"net/url"
"strings"
"time"
"git.golem15.com/golem15/summercms/modules/bouncer"
"git.golem15.com/golem15/summercms/modules/pact"
)
// maxMCPConsentBody caps the POST /mcp/consent/{request} body.
const maxMCPConsentBody = 16 << 10
// Messages of the consent endpoints (phrase keys under backend::lang).
const (
mcpConsentNotFoundKey = "mcp_connect.request_not_found"
mcpConsentNotFoundFallback = "This connection request has expired or does not exist."
mcpConsentNoScopesKey = "mcp_connect.no_grantable_scopes"
mcpConsentNoScopesFallback = "Choose at least one scope you can use."
)
// mcpConsentProvider answers the published pact.MCPAdminConsent, nil when
// no plugin publishes one.
func (s *service) mcpConsentProvider() pact.MCPAdminConsent {
if s == nil || s.app == nil {
return nil
}
provider, ok := s.app.Lookup[pact.MCPAdminConsent]()
if !ok || provider == nil {
return nil
}
return provider
}
func (s *service) writeMCPConsentNotFound(w http.ResponseWriter, r *http.Request) {
WriteError(w, http.StatusNotFound, "request_not_found", backendMessage(r.Context(), s.translator(), mcpConsentNotFoundKey, mcpConsentNotFoundFallback))
}
func (s *service) writeMCPConsentNoScopes(w http.ResponseWriter, r *http.Request) {
WriteError(w, http.StatusUnprocessableEntity, "no_grantable_scopes", backendMessage(r.Context(), s.translator(), mcpConsentNoScopesKey, mcpConsentNoScopesFallback))
}
// grantableConsentScopes answers, in catalog order, the requested scope
// names that are in the token-scope catalog and that the administrator can
// grant (scopeOverlaps, the personal-token picker rule). Everything else is
// hidden from the consent screen and dropped from a decision (D-11).
func (s *service) grantableConsentScopes(principal *bouncer.Principal, requested []string) []*compiledTokenScope {
if s.reg == nil || s.reg.tokenScopes == nil || principal == nil {
return nil
}
want := make(map[string]bool, len(requested))
for _, name := range requested {
want[strings.TrimSpace(name)] = true
}
var out []*compiledTokenScope
for _, scope := range s.reg.tokenScopes.ordered {
if want[scope.Name] && scopeOverlaps(s.reg, principal, scope.Name) {
out = append(out, scope)
}
}
return out
}
// mcpConsentRedirectHost is what the consent screen shows as the place the
// browser returns to: the redirect URI's host (with its port), or, for a
// URI without a host (a custom scheme), the URI without query and fragment.
func mcpConsentRedirectHost(raw string) string {
u, err := url.Parse(raw)
if err != nil {
return ""
}
if u.Host != "" {
return u.Host
}
u.RawQuery, u.Fragment, u.RawFragment = "", "", ""
return u.String()
}
// mcpConsentShow serves GET /mcp/consent/{request}: the pending MCP
// authorization request of an administrator-only grant, as the published
// pact.MCPAdminConsent resolves it for the signed-in administrator, with
// only the requested scopes this administrator can grant.
func (s *service) mcpConsentShow(w http.ResponseWriter, r *http.Request) {
principal := accountPrincipal(w, r)
if principal == nil {
return
}
provider := s.mcpConsentProvider()
if provider == nil {
s.writeMCPConsentNotFound(w, r)
return
}
ctx := r.Context()
req, err := provider.MCPAdminConsentShow(ctx, principal.ID, r.PathValue("request"))
if errors.Is(err, pact.ErrMCPConsentNotFound) {
s.writeMCPConsentNotFound(w, r)
return
}
if err != nil {
moduleLog.ErrorContext(ctx, "cabana: mcp consent show failed", "admin_id", principal.ID, "error", err)
WriteError(w, http.StatusInternalServerError, "error", msgServerError)
return
}
db, err := s.db()
if err != nil {
moduleLog.ErrorContext(ctx, "cabana: mcp consent show without a database", "error", err)
WriteError(w, http.StatusInternalServerError, "error", msgServerError)
return
}
var admin BackendUser
if err := db.WithContext(ctx).Select("id", "login", "first_name", "last_name", "email").Where("id = ?", principal.ID).Take(&admin).Error; err != nil {
moduleLog.ErrorContext(ctx, "cabana: mcp consent show could not load the administrator", "admin_id", principal.ID, "error", err)
WriteError(w, http.StatusInternalServerError, "error", msgServerError)
return
}
tr := s.translator()
scopes := []AdminAPITokenScope{}
for _, scope := range s.grantableConsentScopes(principal, req.Scopes) {
scopes = append(scopes, mapCompiledScope(ctx, tr, scope))
}
expires := ""
if !req.ExpiresAt.IsZero() {
expires = req.ExpiresAt.UTC().Format(time.RFC3339)
}
WriteData(w, http.StatusOK, MCPConsentView{
RequestID: req.RequestID,
Client: MCPConsentClientView{
ID: req.ClientID,
Name: req.ClientName,
RedirectHost: mcpConsentRedirectHost(req.RedirectURI),
LogoURL: req.LogoURL,
},
Admin: MCPConsentAdminView{
Login: admin.Login,
Name: strings.TrimSpace(admin.FirstName + " " + admin.LastName),
Email: admin.Email,
},
Scopes: scopes,
OfflineAccess: req.OfflineAccess,
ConsentRequired: req.ConsentRequired,
ExpiresAt: expires,
}, nil)
}
// mcpConsentDecide serves POST /mcp/consent/{request}: the administrator's
// allow or deny. An allow keeps the submitted scopes that were requested
// and that the administrator can grant (others are dropped, not refused),
// normalises them as personal-token creation does (* collapses to ["*"])
// and answers 422 no_grantable_scopes when nothing is left; offline access
// is granted only when it was requested and the body asks for it. The
// provider owns the transaction and the lock of the pending request.
func (s *service) mcpConsentDecide(w http.ResponseWriter, r *http.Request) {
principal := accountPrincipal(w, r)
if principal == nil {
return
}
provider := s.mcpConsentProvider()
if provider == nil {
s.writeMCPConsentNotFound(w, r)
return
}
var body MCPConsentDecisionRequest
dec := json.NewDecoder(http.MaxBytesReader(w, r.Body, maxMCPConsentBody))
dec.DisallowUnknownFields()
if err := dec.Decode(&body); err != nil || dec.Decode(&struct{}{}) != io.EOF {
WriteError(w, http.StatusBadRequest, "invalid_request", "Invalid request")
return
}
ctx := r.Context()
requestID := r.PathValue("request")
var decision pact.MCPAdminConsentDecision
switch body.Decision {
case "deny":
case "allow":
req, err := provider.MCPAdminConsentShow(ctx, principal.ID, requestID)
if errors.Is(err, pact.ErrMCPConsentNotFound) {
s.writeMCPConsentNotFound(w, r)
return
}
if err != nil {
moduleLog.ErrorContext(ctx, "cabana: mcp consent decide could not load the request", "admin_id", principal.ID, "error", err)
WriteError(w, http.StatusInternalServerError, "error", msgServerError)
return
}
grantable := map[string]bool{}
for _, scope := range s.grantableConsentScopes(principal, req.Scopes) {
grantable[scope.Name] = true
}
kept := make([]string, 0, len(body.Scopes))
for _, name := range body.Scopes {
if name = strings.TrimSpace(name); grantable[name] {
kept = append(kept, name)
}
}
if len(kept) == 0 {
s.writeMCPConsentNoScopes(w, r)
return
}
scopes, details := validateTokenScopes(s.reg, principal, kept)
if details != nil || len(scopes) == 0 {
s.writeMCPConsentNoScopes(w, r)
return
}
decision = pact.MCPAdminConsentDecision{
Allow: true,
Scopes: scopes,
OfflineAccess: req.OfflineAccess && body.OfflineAccess,
}
default:
WriteError(w, http.StatusBadRequest, "invalid_request", "Invalid request")
return
}
redirect, err := provider.MCPAdminConsentDecide(ctx, principal.ID, requestID, decision)
switch {
case errors.Is(err, pact.ErrMCPConsentNotFound):
s.writeMCPConsentNotFound(w, r)
return
case errors.Is(err, pact.ErrMCPConsentNoScopes):
s.writeMCPConsentNoScopes(w, r)
return
case err != nil:
moduleLog.ErrorContext(ctx, "cabana: mcp consent decide failed", "admin_id", principal.ID, "allow", decision.Allow, "error", err)
WriteError(w, http.StatusInternalServerError, "error", msgServerError)
return
}
moduleLog.InfoContext(ctx, "cabana: mcp consent decided", "admin_id", principal.ID, "allow", decision.Allow, "scopes", decision.Scopes)
WriteData(w, http.StatusOK, MCPConsentDecisionView{RedirectURI: redirect}, nil)
}

View File

@@ -0,0 +1,302 @@
package cabana
import (
"context"
"database/sql"
"encoding/json"
"net/http"
"net/http/httptest"
"slices"
"strings"
"sync"
"testing"
"time"
"git.golem15.com/golem15/summercms/modules/backpack"
"git.golem15.com/golem15/summercms/modules/bouncer"
"git.golem15.com/golem15/summercms/modules/lagoon"
"git.golem15.com/golem15/summercms/modules/pact"
"git.golem15.com/golem15/summercms/modules/party"
_ "github.com/jackc/pgx/v5/stdlib"
tcpostgres "github.com/testcontainers/testcontainers-go/modules/postgres"
"gorm.io/gorm"
)
var (
consentPGOnce sync.Once
consentPGDB *gorm.DB
consentPGErr error
)
// consentGorm starts one Postgres for the admin smoke tests of this file
// set and migrates the framework tables (backend_users and friends).
func consentGorm(t *testing.T) *gorm.DB {
t.Helper()
if testing.Short() {
t.Skip("requires testcontainers postgres")
}
consentPGOnce.Do(func() {
ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
defer cancel()
ctr, err := tcpostgres.Run(ctx, "postgres:16-alpine",
tcpostgres.WithDatabase("cabana"),
tcpostgres.WithUsername("cabana"),
tcpostgres.WithPassword("cabana"),
tcpostgres.BasicWaitStrategies(),
)
if err != nil {
consentPGErr = err
return
}
dsn, err := ctr.ConnectionString(ctx, "sslmode=disable")
if err != nil {
consentPGErr = err
return
}
db, err := sql.Open("pgx", dsn)
if err != nil {
consentPGErr = err
return
}
gdb, err := lagoon.Use(ctx, db)
if err != nil {
consentPGErr = err
return
}
if err := lagoon.Migrate(gdb, nil); err != nil {
consentPGErr = err
return
}
consentPGDB = gdb
})
if consentPGErr != nil {
t.Fatalf("postgres: %v", consentPGErr)
}
return consentPGDB
}
// consentScopesPlugin declares a read and a write permission and one plugin
// token scope behind the write permission.
type consentScopesPlugin struct{}
func (consentScopesPlugin) ID() string { return "acme.items" }
func (consentScopesPlugin) Requires() []string { return nil }
func (consentScopesPlugin) Register(*backpack.App) error { return nil }
func (consentScopesPlugin) Boot(*backpack.App) error { return nil }
func (consentScopesPlugin) Permissions() []pact.Permission {
return []pact.Permission{
{Code: "acme.items.read", Tab: "Items", Label: "Read items"},
{Code: "acme.items.write", Tab: "Items", Label: "Write items"},
}
}
func (consentScopesPlugin) TokenScopes() []pact.TokenScope {
return []pact.TokenScope{{Name: "acme:write", Label: "Write items", Description: "Create and change items.", Permissions: []string{"acme.items.write"}, Methods: []string{"GET", "POST"}}}
}
// fakeAdminConsent is the published pact.MCPAdminConsent of the test: one
// pending request "req1" for any administrator.
type fakeAdminConsent struct {
mu sync.Mutex
requested []string
decided []pact.MCPAdminConsentDecision
admins []uint
}
func (f *fakeAdminConsent) MCPAdminConsentShow(_ context.Context, adminID uint, requestID string) (pact.MCPAdminConsentRequest, error) {
if requestID != "req1" {
return pact.MCPAdminConsentRequest{}, pact.ErrMCPConsentNotFound
}
f.mu.Lock()
defer f.mu.Unlock()
return pact.MCPAdminConsentRequest{
RequestID: "req1", ClientID: "oas_client", ClientName: "Agent", LogoURL: "https://agent.example.com/logo.png",
RedirectURI: "https://agent.example.com:8443/callback?x=1", Scopes: append([]string(nil), f.requested...),
OfflineAccess: true, ConsentRequired: true, ExpiresAt: time.Date(2026, 11, 21, 10, 0, 0, 0, time.UTC),
}, nil
}
func (f *fakeAdminConsent) MCPAdminConsentDecide(_ context.Context, adminID uint, requestID string, decision pact.MCPAdminConsentDecision) (string, error) {
if requestID != "req1" {
return "", pact.ErrMCPConsentNotFound
}
f.mu.Lock()
defer f.mu.Unlock()
f.decided = append(f.decided, decision)
f.admins = append(f.admins, adminID)
if !decision.Allow {
return "https://agent.example.com:8443/callback?error=access_denied", nil
}
return "https://agent.example.com:8443/callback?code=c1", nil
}
// TestMCPAdminConsentSmoke covers the admin consent endpoints over a fake
// provider: Show lists only requested catalog scopes the administrator can
// grant (a write scope they lack and an unknown name are hidden), Allow
// drops submitted scopes outside that set and calls Decide with the rest,
// offline access needs both the request and the body, Deny passes through,
// and the endpoint answers 401 anonymous, 403 interactive_only for a g15_
// token, 404 without a provider or for an unknown request, 422 when nothing
// grantable is submitted and 400 for an unknown body field.
func TestMCPAdminConsentSmoke(t *testing.T) {
gdb := consentGorm(t)
var admin BackendUser
admin = BackendUser{FirstName: "Ada", LastName: "Reader", Login: "consent-reader", Email: "reader@acme.test", Password: "x", Permissions: `{"acme.items.read":1}`, IsActivated: true}
if err := gdb.Create(&admin).Error; err != nil {
t.Fatal(err)
}
reg, err := compileTokenCatalog([]party.Plugin{consentScopesPlugin{}})
if err != nil {
t.Fatal(err)
}
app := backpack.New(nil)
if err := app.Publish(gdb); err != nil {
t.Fatal(err)
}
provider := &fakeAdminConsent{requested: []string{"acme:write", "admin:read", "ghost"}}
svc := &service{app: app, reg: reg}
principal := &bouncer.Principal{ID: admin.ID, Backend: true, PermissionGrants: map[string]bool{"acme.items.read": true}}
request := func(method, id, body string, p *bouncer.Principal) *http.Request {
req := httptest.NewRequest(method, "/mcp/consent/"+id, strings.NewReader(body))
req.Header.Set("X-Requested-With", "XMLHttpRequest")
req.SetPathValue("request", id)
if p != nil {
req = req.WithContext(bouncer.WithUser(req.Context(), p))
}
return req
}
show := func(s *service, id string, p *bouncer.Principal) *httptest.ResponseRecorder {
rec := httptest.NewRecorder()
interactiveOnly(s.mcpConsentShow)(rec, request(http.MethodGet, id, "", p))
return rec
}
decide := func(s *service, id, body string, p *bouncer.Principal) *httptest.ResponseRecorder {
rec := httptest.NewRecorder()
interactiveOnly(requireAjax(s.mcpConsentDecide))(rec, request(http.MethodPost, id, body, p))
return rec
}
// No provider published: 404 request_not_found for both.
if rec := show(svc, "req1", principal); rec.Code != http.StatusNotFound || !strings.Contains(rec.Body.String(), `"request_not_found"`) {
t.Fatalf("show without provider = %d %s", rec.Code, rec.Body.String())
}
if rec := decide(svc, "req1", `{"decision":"deny"}`, principal); rec.Code != http.StatusNotFound {
t.Fatalf("decide without provider = %d %s", rec.Code, rec.Body.String())
}
if err := app.Publish[pact.MCPAdminConsent](provider); err != nil {
t.Fatal(err)
}
rec := show(svc, "req1", principal)
if rec.Code != http.StatusOK {
t.Fatalf("show = %d %s", rec.Code, rec.Body.String())
}
var shown struct {
Data MCPConsentView `json:"data"`
}
if err := json.Unmarshal(rec.Body.Bytes(), &shown); err != nil {
t.Fatal(err)
}
var names []string
for _, sc := range shown.Data.Scopes {
names = append(names, sc.Name)
}
if !slices.Equal(names, []string{"admin:read"}) {
t.Fatalf("shown scopes = %v, want [admin:read]", names)
}
d := shown.Data
if d.RequestID != "req1" || d.Client.ID != "oas_client" || d.Client.Name != "Agent" || d.Client.RedirectHost != "agent.example.com:8443" ||
d.Admin.Login != "consent-reader" || d.Admin.Name != "Ada Reader" || d.Admin.Email != "reader@acme.test" ||
!d.OfflineAccess || !d.ConsentRequired || d.ExpiresAt != "2026-11-21T10:00:00Z" || !shown.Data.Scopes[0].ReadOnly {
t.Fatalf("view = %+v", d)
}
if rec := show(svc, "nope", principal); rec.Code != http.StatusNotFound || !strings.Contains(rec.Body.String(), `"request_not_found"`) {
t.Fatalf("unknown request = %d %s", rec.Code, rec.Body.String())
}
// Allow: * was not requested and acme:write is not grantable, so both
// are dropped; offline access is requested and asked for.
rec = decide(svc, "req1", `{"decision":"allow","scopes":["*","admin:read","acme:write"],"offline_access":true}`, principal)
if rec.Code != http.StatusOK || !strings.Contains(rec.Body.String(), `"redirect_uri":"https://agent.example.com:8443/callback?code=c1"`) {
t.Fatalf("allow = %d %s", rec.Code, rec.Body.String())
}
if last := provider.decided[len(provider.decided)-1]; !last.Allow || !slices.Equal(last.Scopes, []string{"admin:read"}) || !last.OfflineAccess || provider.admins[len(provider.admins)-1] != admin.ID {
t.Fatalf("decide called with %+v", last)
}
// Only hidden scopes submitted: 422, Decide not called.
calls := len(provider.decided)
if rec := decide(svc, "req1", `{"decision":"allow","scopes":["acme:write","ghost"]}`, principal); rec.Code != http.StatusUnprocessableEntity || !strings.Contains(rec.Body.String(), `"no_grantable_scopes"`) || len(provider.decided) != calls {
t.Fatalf("nothing grantable = %d %s", rec.Code, rec.Body.String())
}
// A requested * is offered, as on personal-token creation, and
// collapses the grant to ["*"].
provider.mu.Lock()
provider.requested = []string{"*", "admin:read"}
provider.mu.Unlock()
if rec := decide(svc, "req1", `{"decision":"allow","scopes":["admin:read","*"],"offline_access":false}`, principal); rec.Code != http.StatusOK {
t.Fatalf("allow * = %d %s", rec.Code, rec.Body.String())
}
if last := provider.decided[len(provider.decided)-1]; !slices.Equal(last.Scopes, []string{"*"}) || last.OfflineAccess {
t.Fatalf("decide * called with %+v", last)
}
// Deny passes through without scopes.
if rec := decide(svc, "req1", `{"decision":"deny"}`, principal); rec.Code != http.StatusOK || !strings.Contains(rec.Body.String(), "access_denied") {
t.Fatalf("deny = %d %s", rec.Code, rec.Body.String())
}
if last := provider.decided[len(provider.decided)-1]; last.Allow || len(last.Scopes) != 0 {
t.Fatalf("deny called with %+v", last)
}
// Malformed bodies: an unknown field and an unknown decision.
for _, body := range []string{`{"decision":"allow","scopes":["admin:read"],"extra":1}`, `{"decision":"maybe"}`, `not json`} {
if rec := decide(svc, "req1", body, principal); rec.Code != http.StatusBadRequest {
t.Fatalf("body %s = %d %s", body, rec.Code, rec.Body.String())
}
}
if rec := decide(svc, "nope", `{"decision":"allow","scopes":["admin:read"]}`, principal); rec.Code != http.StatusNotFound {
t.Fatalf("decide unknown request = %d %s", rec.Code, rec.Body.String())
}
// Anonymous: 401. A g15_ token: 403 interactive_only, for GET and POST.
if rec := show(svc, "req1", nil); rec.Code != http.StatusUnauthorized {
t.Fatalf("anonymous = %d %s", rec.Code, rec.Body.String())
}
tokenReq := request(http.MethodGet, "req1", "", principal)
tokenReq = tokenReq.WithContext(bouncer.WithCredential(tokenReq.Context(), &BackendAPIToken{ID: 3}))
rec = httptest.NewRecorder()
interactiveOnly(svc.mcpConsentShow)(rec, tokenReq)
if rec.Code != http.StatusForbidden || !strings.Contains(rec.Body.String(), "interactive_only") {
t.Fatalf("token credential = %d %s", rec.Code, rec.Body.String())
}
bearer := request(http.MethodPost, "req1", `{"decision":"deny"}`, principal)
bearer.Header.Set("Authorization", "Bearer "+APITokenPrefix+strings.Repeat("0", 40))
rec = httptest.NewRecorder()
interactiveOnly(requireAjax(svc.mcpConsentDecide))(rec, bearer)
if rec.Code != http.StatusForbidden || !strings.Contains(rec.Body.String(), "interactive_only") {
t.Fatalf("raw g15_ bearer = %d %s", rec.Code, rec.Body.String())
}
// The POST needs X-Requested-With.
plain := request(http.MethodPost, "req1", `{"decision":"deny"}`, principal)
plain.Header.Del("X-Requested-With")
rec = httptest.NewRecorder()
interactiveOnly(requireAjax(svc.mcpConsentDecide))(rec, plain)
if rec.Code != http.StatusForbidden {
t.Fatalf("POST without X-Requested-With = %d", rec.Code)
}
}
// TestTokenScopeNamesAndLabels: the exported catalog answers names in
// catalog order before activation, and labels fall back to the name.
func TestTokenScopeNamesAndLabels(t *testing.T) {
app := backpack.New(nil)
if err := app.Publish(party.Activated([]party.Plugin{consentScopesPlugin{}})); err != nil {
t.Fatal(err)
}
names, err := TokenScopeNames(app)
if err != nil || !slices.Equal(names, []string{"*", "admin:read", "acme:write"}) {
t.Fatalf("names = %v, %v", names, err)
}
labels := TokenScopeLabels(context.Background(), app, []string{"acme:write", "ghost"})
if !slices.Equal(labels, []string{"Write items", "ghost"}) {
t.Fatalf("labels = %v", labels)
}
}

View File

@@ -836,6 +836,12 @@ func conformCases() []conformCase {
{"POST /account/contributions/{name}/actions/{action}", 200, "cabana.Envelope-cabana_AccountActionResultView", func(t *testing.T, e *conformEnv) *httptest.ResponseRecorder { {"POST /account/contributions/{name}/actions/{action}", 200, "cabana.Envelope-cabana_AccountActionResultView", func(t *testing.T, e *conformEnv) *httptest.ResponseRecorder {
return e.send(t, http.MethodPost, "/account/contributions/conform_link/actions/open", nil, true) return e.send(t, http.MethodPost, "/account/contributions/conform_link/actions/open", nil, true)
}, into[cabana.Envelope[cabana.AccountActionResultView]](), nil}, }, into[cabana.Envelope[cabana.AccountActionResultView]](), nil},
{"GET /mcp/consent/{request}", 200, "cabana.Envelope-cabana_MCPConsentView", func(t *testing.T, e *conformEnv) *httptest.ResponseRecorder {
return e.send(t, http.MethodGet, "/mcp/consent/conform-request", nil, true)
}, into[cabana.Envelope[cabana.MCPConsentView]](), nil},
{"POST /mcp/consent/{request}", 200, "cabana.Envelope-cabana_MCPConsentDecisionView", func(t *testing.T, e *conformEnv) *httptest.ResponseRecorder {
return e.send(t, http.MethodPost, "/mcp/consent/conform-request", map[string]any{"decision": "allow", "scopes": []string{"admin:read"}, "offline_access": true}, true)
}, into[cabana.Envelope[cabana.MCPConsentDecisionView]](), nil},
{"POST /auth/logout", 200, "cabana.Envelope-cabana_AdminLogoutData", func(t *testing.T, e *conformEnv) *httptest.ResponseRecorder { {"POST /auth/logout", 200, "cabana.Envelope-cabana_AdminLogoutData", func(t *testing.T, e *conformEnv) *httptest.ResponseRecorder {
return e.send(t, http.MethodPost, "/auth/logout", nil, true) return e.send(t, http.MethodPost, "/auth/logout", nil, true)
}, into[cabana.Envelope[cabana.AdminLogoutData]](), nil}, }, into[cabana.Envelope[cabana.AdminLogoutData]](), nil},
@@ -1134,6 +1140,10 @@ func newConformEnv(t *testing.T) *conformEnv {
if err := app.Publish[postcard.Mailer](mailer); err != nil { if err := app.Publish[postcard.Mailer](mailer); err != nil {
t.Fatal(err) t.Fatal(err)
} }
// The MCP consent routes serve a fake administrator-only consent provider.
if err := app.Publish[pact.MCPAdminConsent](conformConsent{}); err != nil {
t.Fatal(err)
}
// The acme.companions fixture serves the Phase 17 routes (dependent // The acme.companions fixture serves the Phase 17 routes (dependent
// options) next to the gadgets. // options) next to the gadgets.
plugins := []party.Plugin{conformPlugin{stamp: stamp}, companionsPlugin{app: app}} plugins := []party.Plugin{conformPlugin{stamp: stamp}, companionsPlugin{app: app}}
@@ -1238,6 +1248,30 @@ func (conformSettings) TableName() string { return "cabana_conform_settin
func (conformSettings) Fillable() []string { return []string{"enabled", "api_key"} } func (conformSettings) Fillable() []string { return []string{"enabled", "api_key"} }
func (conformSettings) Rules() map[string]string { return map[string]string{} } func (conformSettings) Rules() map[string]string { return map[string]string{} }
// conformConsent is the fake pact.MCPAdminConsent of the conformance
// suite: one pending request asking for admin:read and offline access.
type conformConsent struct{}
func (conformConsent) MCPAdminConsentShow(_ context.Context, _ uint, requestID string) (pact.MCPAdminConsentRequest, error) {
if requestID != "conform-request" {
return pact.MCPAdminConsentRequest{}, pact.ErrMCPConsentNotFound
}
return pact.MCPAdminConsentRequest{
RequestID: requestID, ClientID: "oas_conform", ClientName: "Conform agent", RedirectURI: "https://agent.example.test/callback",
Scopes: []string{"admin:read"}, OfflineAccess: true, ConsentRequired: true, ExpiresAt: time.Now().Add(10 * time.Minute),
}, nil
}
func (conformConsent) MCPAdminConsentDecide(_ context.Context, _ uint, requestID string, decision pact.MCPAdminConsentDecision) (string, error) {
if requestID != "conform-request" {
return "", pact.ErrMCPConsentNotFound
}
if len(decision.Scopes) == 0 && decision.Allow {
return "", pact.ErrMCPConsentNoScopes
}
return "https://agent.example.test/callback?code=conform", nil
}
type conformPlugin struct{ stamp string } type conformPlugin struct{ stamp string }
func (conformPlugin) ID() string { return "acme.conform" } func (conformPlugin) ID() string { return "acme.conform" }

View File

@@ -103,6 +103,7 @@ func TestPhase10Coverage(t *testing.T) {
"POST /mail/preview", "POST /mail/preview",
"POST /mail/test-send", "POST /mail/test-send",
"POST /markdown/preview", "POST /markdown/preview",
"POST /mcp/consent/{request}",
"POST /{vendor}/{plugin}/{controller}", "POST /{vendor}/{plugin}/{controller}",
"POST /{vendor}/{plugin}/{controller}/bulk-delete", "POST /{vendor}/{plugin}/{controller}/bulk-delete",
"POST /{vendor}/{plugin}/{controller}/bulk/{action}", "POST /{vendor}/{plugin}/{controller}/bulk/{action}",

View File

@@ -73,9 +73,9 @@ func TestPhase10CSRF(t *testing.T) {
// caption, file remove, relation child create, update and delete, pivot // caption, file remove, relation child create, update and delete, pivot
// update, child file upload, reorder, caption and remove, plugin field // update, child file upload, reorder, caption and remove, plugin field
// type upload, tree reorder save, account contribution action, // type upload, tree reorder save, account contribution action,
// mail image upload, mail preview, mail test-send // mail image upload, mail preview, mail test-send, MCP consent decision
if unsafe != 38 { if unsafe != 39 {
t.Fatalf("walked %d state-changing routes, want 38: %v", unsafe, router.order) t.Fatalf("walked %d state-changing routes, want 39: %v", unsafe, router.order)
} }
loginHandler := router.handlers[login] loginHandler := router.handlers[login]

View File

@@ -50,6 +50,8 @@ var phase09Routes = []adminRoute{
{key: "DELETE /account/tokens/{id}"}, {key: "DELETE /account/tokens/{id}"},
{key: "GET /account/contributions"}, {key: "GET /account/contributions"},
{key: "POST /account/contributions/{name}/actions/{action}"}, {key: "POST /account/contributions/{name}/actions/{action}"},
{key: "GET /mcp/consent/{request}"},
{key: "POST /mcp/consent/{request}"},
{key: "GET /navigation"}, {key: "GET /navigation"},
{key: "GET /field-types"}, {key: "GET /field-types"},
{key: "GET /settings"}, {key: "GET /settings"},

View File

@@ -45,6 +45,8 @@ var tokenRouteClasses = map[string]tokenRouteClass{
"DELETE /account/tokens/{id}": classInteractive, "DELETE /account/tokens/{id}": classInteractive,
"GET /account/contributions": classInteractive, "GET /account/contributions": classInteractive,
"POST /account/contributions/{name}/actions/{action}": classInteractive, "POST /account/contributions/{name}/actions/{action}": classInteractive,
"GET /mcp/consent/{request}": classInteractive,
"POST /mcp/consent/{request}": classInteractive,
"GET /navigation": classAllowsNav, "GET /navigation": classAllowsNav,
"GET /field-types": classExplicitGate, "GET /field-types": classExplicitGate,

View File

@@ -0,0 +1,63 @@
package cabana
import (
"context"
"strings"
"git.golem15.com/golem15/summercms/modules/backpack"
"git.golem15.com/golem15/summercms/modules/phrasebook"
)
// TokenScopeNames answers the names of the personal API token scope catalog
// in catalog order: *, admin:read, then every plugin's TokenScopes in
// activation order. It compiles the catalog from the activated plugins
// (party.Activated), so it works at plugin Boot, before cabana.Activate. A
// plugin that advertises the same scopes elsewhere (an OAuth server whose
// grants act as administrators, for example) reads them here. The error is
// the catalog's compile error (an invalid or duplicate plugin scope).
func TokenScopeNames(app *backpack.App) ([]string, error) {
reg, err := tokenCatalogForApp(app)
if err != nil {
return nil, err
}
if reg == nil || reg.tokenScopes == nil {
return []string{}, nil
}
out := make([]string, 0, len(reg.tokenScopes.ordered))
for _, scope := range reg.tokenScopes.ordered {
out = append(out, scope.Name)
}
return out, nil
}
// TokenScopeLabels answers the translated label of each name, in input
// order: the label the token screens show for a catalog scope, and the name
// itself for a name the catalog does not know (or when the catalog fails to
// compile). The locale is the one ctx carries.
func TokenScopeLabels(ctx context.Context, app *backpack.App, names []string) []string {
if ctx == nil {
ctx = context.Background()
}
var tr *phrasebook.Translator
if app != nil {
tr, _ = app.Lookup[*phrasebook.Translator]()
}
reg, err := tokenCatalogForApp(app)
out := make([]string, 0, len(names))
for _, name := range names {
label := name
if err == nil && reg != nil && reg.tokenScopes != nil {
if scope, ok := reg.tokenScopes.byName[name]; ok {
label = scope.Label
if strings.Contains(label, "::") {
label = resolveScopePhrase(ctx, tr, label, label)
}
if strings.TrimSpace(label) == "" {
label = name
}
}
}
out = append(out, label)
}
return out
}

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.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.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.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.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.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. | | `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) 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 // MCPLinkedBackendResolver answers the verified backend account linked to a
// frontend user, published by the plugin that owns the link. The boolean is // frontend user, published by the plugin that owns the link. The boolean is
// false when the user has no link. // false when the user has no link.

View File

@@ -348,6 +348,9 @@ api_tokens:
unknown_scope: ':name (unknown)' unknown_scope: ':name (unknown)'
unknown_scope_hint: This scope is no longer registered and grants nothing. unknown_scope_hint: This scope is no longer registered and grants nothing.
hint: Token ending in :last4 hint: Token ending in :last4
mcp_connect:
request_not_found: This connection request has expired or does not exist.
no_grantable_scopes: Choose at least one scope you can use.
myaccount: myaccount:
menu_label: My account menu_label: My account
menu_description: Edit your name, email, subtitle and password, and manage your API tokens. menu_description: Edit your name, email, subtitle and password, and manage your API tokens.

View File

@@ -370,6 +370,9 @@ api_tokens:
unknown_scope: ':name (nieznany)' unknown_scope: ':name (nieznany)'
unknown_scope_hint: Ten zakres nie jest już zarejestrowany i nic nie przyznaje. unknown_scope_hint: Ten zakres nie jest już zarejestrowany i nic nie przyznaje.
hint: Token kończący się na :last4 hint: Token kończący się na :last4
mcp_connect:
request_not_found: To żądanie połączenia wygasło albo nie istnieje.
no_grantable_scopes: Wybierz co najmniej jeden zakres, którego możesz użyć.
myaccount: myaccount:
menu_label: Moje konto menu_label: Moje konto
menu_description: Zmień imię, nazwisko, e-mail, podtytuł i hasło oraz zarządzaj tokenami API. menu_description: Zmień imię, nazwisko, e-mail, podtytuł i hasło oraz zarządzaj tokenami API.