docs(spec): state what the action requiredPermissions server gate does NOT cover (#3923)

`ActionSchema.requiredPermissions` documented itself as a dual-surface gate
whose server half is "the source of truth". An app author reasonably reads that
as "any action I declare this on is enforced somewhere", and it isn't.

Server enforcement lives on the platform action route — POST
/api/v1/actions/<object>/<action> and the MCP/AI path — which is where
`type: 'script' | 'flow' | 'modal'` actions execute. A `type: 'api'` action
pointed at a self-authored endpoint is fetched by the browser directly; that
request never reaches the platform, so nothing checks the declaration
server-side and the endpoint must re-check the capability itself. The doc
comment, the `describe()` string (what surfaces in generated schema docs and
editor tooltips) and ADR-0066 D4 now say so.

Behaviour is unchanged. The UI half's gaps were separate and are fixed in
objectui.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: 2 people

.changeset/action-required-permissions-server-scope-docs.md

@@ -0,0 +1,22 @@
+---
+"@objectstack/spec": patch
+---
+
+docs(spec): state what the action `requiredPermissions` server gate does NOT cover (#3923)
+
+`ActionSchema.requiredPermissions` documented itself as a dual-surface gate whose
+server half is "the source of truth": declare once, get a 403 on the server and a
+hidden button in the UI. An app author reasonably read that as "any action I
+declare this on is enforced somewhere", and it isn't.
+
+Server enforcement lives on the PLATFORM ACTION ROUTE — `POST
+/api/v1/actions/<object>/<action>` and the MCP/AI path — which is where `type:
+'script' | 'flow' | 'modal'` actions execute. A `type: 'api'` action pointed at a
+self-authored endpoint is fetched by the browser directly; that request never
+reaches the platform, so nothing checks the declaration server-side and the
+endpoint has to re-check the capability itself. The doc comment, the `describe()`
+string (which is what surfaces in generated schema docs and editor tooltips), and
+ADR-0066 D4 now say so.
+
+Behaviour is unchanged — this is the contract being honest about its edges. The
+UI half's gaps were separate and are fixed in objectui.

docs/adr/0066-unified-authorization-model.md

@@ -57,6 +57,8 @@ Extend `requiredPermissions` (today only on `App`/nav, **[existing]**) to **Obje
 ### D4 — Dual-surface action gates [new]
 An action declaring `requiredPermissions` is enforced in **one place, two surfaces**: the ActionRunner hides/disables it in the UI **and** the server rejects the call when the caller lacks the capability. Removes the "UI-gated but server-open" footgun (and the inverse). Server enforcement is the source of truth; UI gating is derived from the same declaration.
 
+**Scope of the server half (clarified 2026-07, framework#3923).** "The server rejects the call" means the PLATFORM ACTION ROUTE — `POST /api/v1/actions/<object>/<action>` and the MCP/AI path, i.e. where `type: 'script' | 'flow' | 'modal'` actions execute. A `type: 'api'` action whose `target` is a self-authored endpoint is fetched by the browser directly and never passes through that route, so the declaration has no server-side consumer there; that endpoint must re-check the capability itself. The UI half is correspondingly *every* action surface, not just the engine: `record_header`/`record_more` (`page:header`) and `list_item` (the grid row menu) filter their own action lists and were fixed to apply the same gate (objectui), alongside `ActionEngine.getActionsForLocation`. All of them fail OPEN when the client does not know the caller's capabilities — unknown is not denied.
+
 ### D5 — Package-seeded, admin-maintainable policies [existing mechanism, fill the gap]
 A package may seed permission-set policies (incl. per-object grants for **its own** objects) via `stack.permissions` **[existing]**; these land as `sys_permission_set` records **admins can edit in Setup** **[existing]**. The gap to close: make a package's per-object secure default (D2 + an admin-only grant) expressible + seedable so a sensitive package object is locked on install and tunable thereafter.
 

packages/spec/src/ui/action.zod.ts

@@ -580,13 +580,22 @@ export const ActionSchema = lazySchema(() => z.object({
 
   /**
    * [ADR-0066 D4] System capabilities required to INVOKE this action — a
-   * dual-surface gate from ONE declaration: the server (action route) rejects
+   * dual-surface gate from ONE declaration: the PLATFORM ACTION ROUTE rejects
    * the call with 403 when the caller's systemPermissions don't cover these (the
-   * source of truth), and the objectui ActionRunner hides/disables the button
-   * using the same requirement. Independent of `visible` (CEL): this is the RBAC
+   * source of truth), and the objectui action surfaces hide the button using the
+   * same requirement. Independent of `visible` (CEL): this is the RBAC
    * capability contract, mirroring `App.requiredPermissions`.
+   *
+   * **Server enforcement covers the platform's own invocation paths only** —
+   * `POST /api/v1/actions/<object>/<action>` (and the MCP/AI path), which is
+   * where `type: 'script' | 'flow' | 'modal'` actions land. A `type: 'api'`
+   * action whose `target` is a self-authored endpoint is called by the browser
+   * DIRECTLY: the platform never sees the request, so nothing checks this
+   * declaration server-side. Such an endpoint MUST re-check the capability
+   * itself (framework#3923) — treat the UI gate there as a courtesy, not a
+   * boundary.
    */
-  requiredPermissions: z.array(z.string()).optional().describe('[ADR-0066 D4] Capabilities required to invoke this action (server-enforced 403 + UI hide/disable).'),
+  requiredPermissions: z.array(z.string()).optional().describe('[ADR-0066 D4] Capabilities required to invoke this action. Enforced with 403 on the platform action route (script/flow/modal + MCP) and mirrored as a UI hide; a `type: api` action pointed at a custom endpoint must re-check it there.'),
 
   /** Keyboard Shortcut */
   shortcut: z.string().optional().describe('Keyboard shortcut to trigger this action (e.g., "Ctrl+S")'),