@objectstack/runtime 15.0.0 → 15.1.1

package/dist/index.d.cts

@@ -683,16 +683,19 @@ interface DispatcherPluginConfig {
      */
     enforceProjectMembership?: boolean;
     /**
-     * Reject anonymous requests to `auth: true` service routes (AI, etc.) with
-     * HTTP 401, mirroring the REST API's `requireAuth` gate. Must match the
-     * REST plugin's `api.requireAuth` so `/ai` and `/meta` stay in lockstep
-     * with `/data` — otherwise the AI routes' declared `auth: true` contract is
-     * never enforced and anonymous callers reach adapter/model status routes.
+     * Reject anonymous requests to `auth: true` service routes (AI, etc.), the
+     * `/graphql` endpoint and the `/meta` catch-all with HTTP 401, mirroring the
+     * REST API's `requireAuth` gate. Must match the REST plugin's
+     * `api.requireAuth` so `/ai`, `/graphql` and `/meta` stay in lockstep with
+     * `/data` — otherwise the AI routes' declared `auth: true` contract is never
+     * enforced and anonymous callers reach adapter/model status routes or read
+     * object data over GraphQL that `/data/*` 401s (#2567).
      *
-     * Defaults to `false` (backward-compatible: previously nothing enforced
-     * `RouteDefinition.auth` here). Hosts pass their `api.requireAuth` through —
-     * the framework `serve` command and the cloud apps do so from the same
-     * stack `api` config the REST plugin reads.
+     * Defaults to `true` — secure-by-default, matching the REST plugin's
+     * `api.requireAuth` default (ADR-0056 D2). Hosts pass their `api.requireAuth`
+     * through (the framework `serve` command and the cloud apps do so from the
+     * same stack `api` config the REST plugin reads); a deployment that serves
+     * these surfaces publicly sets `requireAuth: false` explicitly.
      */
     requireAuth?: boolean;
     /**
@@ -1128,6 +1131,19 @@ declare class HttpDispatcher {
      * route and the MCP `run_action` bridge enforce the SAME declaration.
      */
     private actionPermissionError;
+    /**
+     * [#2849 / ADR-0011] AI-exposure gate for the MCP action surface. Returns a
+     * human-readable error string unless the action's author explicitly opted it
+     * into the AI surface with `ai.exposed: true`, or `null` when exposed.
+     *
+     * This gate is the REAL agent-facing boundary for actions: script/body
+     * handlers execute as TRUSTED application code (the engine facade carries no
+     * ExecutionContext — see {@link buildActionEngineFacade}), so once invoked, a
+     * body's reads/writes are NOT bounded by the caller's RLS/FLS or an agent's
+     * data ceiling (ADR-0090 D10). The author's explicit opt-in — not a data-layer
+     * backstop — therefore decides what AI may trigger. Fail-closed by default.
+     */
+    private actionAiExposureError;
     /**
      * Whether an action has a headless invocation path (so MCP can run it).
      * Mirrors the supported-type set of the (now cloud-side) action-tools
@@ -1144,15 +1160,34 @@ declare class HttpDispatcher {
     private jsonTypeOf;
     /** Resolve an action's params into LLM-facing summaries (field-backed types resolved). */
     private summarizeActionParams;
-    /** Slim engine facade matching the ActionContext.engine shape handlers expect. */
+    /**
+     * Slim engine facade matching the ActionContext.engine shape handlers expect.
+     *
+     * ⚠️ TRUSTED (SECURITY-DEFINER-like) BY DESIGN (#2849): these calls carry NO
+     * ExecutionContext, so the data engine's security middleware skips RLS / FLS /
+     * CRUD / tenant scoping entirely. Action bodies are the app author's own code
+     * and legitimately perform cross-object writes the invoking user could not
+     * (convert-lead, cascade-close). The boundary is therefore enforced at INVOKE
+     * time (`ai.exposed` + ADR-0066 D4 capability gate), and every dispatch is
+     * audit-logged. Longer-term direction: an action-level `runAs: 'user'|'system'`
+     * mirroring flows (ADR-0049) — tracked in #2849.
+     */
     private buildActionEngineFacade;
     /**
      * Resolve + invoke a business action by its declarative name for the MCP
-     * `run_action` tool. Enforces the ADR-0066 D4 capability gate and RLS as the
-     * caller, loads the subject record under RLS for row-context actions, and
-     * dispatches through the framework's `engine.executeAction` (script/body) or
-     * automation flow runner (flow). Throws on denial / not-found / handler
-     * failure so the tool surfaces a clean tool-error. No service-ai dependency.
+     * `run_action` tool. Enforces the AI-exposure gate (`ai.exposed`, #2849), the
+     * ADR-0066 D4 capability gate, loads the subject record under the caller's
+     * RLS for row-context actions, and dispatches through the framework's
+     * `engine.executeAction` (script/body) or automation flow runner (flow).
+     * Throws on denial / not-found / handler failure so the tool surfaces a
+     * clean tool-error. No service-ai dependency.
+     *
+     * SECURITY MODEL (#2849): all gating happens at INVOKE time. A script/body
+     * handler then runs as trusted code — its engine facade performs
+     * context-less reads/writes that bypass RLS/FLS (SECURITY-DEFINER-like), so
+     * the caller's permissions and an agent's ADR-0090 D10 data ceiling do NOT
+     * bound what the body does internally. Flow actions differ: the flow engine
+     * receives the caller's identity below and honours `runAs` (ADR-0049).
      */
     private invokeBusinessAction;
     /**
@@ -1162,6 +1197,34 @@ declare class HttpDispatcher {
      * and no `objectName` was supplied (so `run_action` can ask for one).
      */
     private resolveActionByName;
+    /**
+     * The MCP surface's single declaration source: every action declaration the
+     * bridge may list or invoke, as `{ action, objectName, obj }` rows.
+     *
+     * Two shapes feed it (#3010):
+     *  1. `object.actions` — bundle/artifact objects and authored object rows.
+     *  2. Standalone `action` metadata items — Studio-authored rows that the
+     *     engine executes since #2608 (`resyncAuthoredActions`) but that never
+     *     appear inside any object definition. Their owning object follows the
+     *     same convention as the engine registration key (`objectName` field,
+     *     legacy `object` field, else the `'global'` wildcard).
+     *
+     * On a key clash (`objectName:name`) the object-embedded declaration wins,
+     * mirroring the execution layer's artifact-wins rule — `resyncAuthoredActions`
+     * refuses to clobber an artifact-registered handler, so the embedded
+     * declaration is the one that matches what actually runs. All MCP gating
+     * (`ai.exposed`, ADR-0066 D4, headless-invokability) applies downstream of
+     * this collection, unchanged.
+     */
+    private collectActionDeclarations;
+    /**
+     * Owning object of a standalone `action` item — must stay in lockstep with
+     * the ObjectQL plugin's `actionObjectKey` (the engine registration key), so
+     * the declaration the MCP surface resolves is the one whose handler
+     * `executeAction` will find: spec `objectName`, bundle-collector `object`,
+     * else the `'global'` wildcard.
+     */
+    private standaloneActionObjectName;
     /**
      * Generate a `sys_api_key` and return the raw secret EXACTLY ONCE
      * (`POST /keys`). This is the only mint path — the raw key is never stored
@@ -1255,7 +1318,7 @@ declare class HttpDispatcher {
             analytics: string | undefined;
             automation: string | undefined;
             workflow: string | undefined;
-            realtime: string | undefined;
+            realtime: undefined;
             notifications: string | undefined;
             ai: string | undefined;
             i18n: string | undefined;
@@ -1272,7 +1335,7 @@ declare class HttpDispatcher {
             analytics: string | undefined;
             automation: string | undefined;
             workflow: string | undefined;
-            realtime: string | undefined;
+            realtime: undefined;
             notifications: string | undefined;
             ai: string | undefined;
             i18n: string | undefined;
@@ -1299,18 +1362,34 @@ declare class HttpDispatcher {
                 message: string;
             };
             data: {
+                enabled: boolean;
+                status: "degraded" | "stub";
+                handlerReady: boolean;
+                route: string | undefined;
+                provider: string | undefined;
+                message: string | undefined;
+            } | {
                 enabled: boolean;
                 status: "available";
                 handlerReady: boolean;
                 route: string | undefined;
                 provider: string | undefined;
+                message?: undefined;
             };
             auth: {
+                enabled: boolean;
+                status: "degraded" | "stub";
+                handlerReady: boolean;
+                route: string | undefined;
+                provider: string | undefined;
+                message: string | undefined;
+            } | {
                 enabled: boolean;
                 status: "available";
                 handlerReady: boolean;
                 route: string | undefined;
                 provider: string | undefined;
+                message?: undefined;
             } | {
                 enabled: boolean;
                 status: "unavailable";
@@ -1318,11 +1397,19 @@ declare class HttpDispatcher {
                 message: string;
             };
             automation: {
+                enabled: boolean;
+                status: "degraded" | "stub";
+                handlerReady: boolean;
+                route: string | undefined;
+                provider: string | undefined;
+                message: string | undefined;
+            } | {
                 enabled: boolean;
                 status: "available";
                 handlerReady: boolean;
                 route: string | undefined;
                 provider: string | undefined;
+                message?: undefined;
             } | {
                 enabled: boolean;
                 status: "unavailable";
@@ -1330,11 +1417,19 @@ declare class HttpDispatcher {
                 message: string;
             };
             analytics: {
+                enabled: boolean;
+                status: "degraded" | "stub";
+                handlerReady: boolean;
+                route: string | undefined;
+                provider: string | undefined;
+                message: string | undefined;
+            } | {
                 enabled: boolean;
                 status: "available";
                 handlerReady: boolean;
                 route: string | undefined;
                 provider: string | undefined;
+                message?: undefined;
             } | {
                 enabled: boolean;
                 status: "unavailable";
@@ -1342,11 +1437,19 @@ declare class HttpDispatcher {
                 message: string;
             };
             cache: {
+                enabled: boolean;
+                status: "degraded" | "stub";
+                handlerReady: boolean;
+                route: string | undefined;
+                provider: string | undefined;
+                message: string | undefined;
+            } | {
                 enabled: boolean;
                 status: "available";
                 handlerReady: boolean;
                 route: string | undefined;
                 provider: string | undefined;
+                message?: undefined;
             } | {
                 enabled: boolean;
                 status: "unavailable";
@@ -1354,11 +1457,19 @@ declare class HttpDispatcher {
                 message: string;
             };
             queue: {
+                enabled: boolean;
+                status: "degraded" | "stub";
+                handlerReady: boolean;
+                route: string | undefined;
+                provider: string | undefined;
+                message: string | undefined;
+            } | {
                 enabled: boolean;
                 status: "available";
                 handlerReady: boolean;
                 route: string | undefined;
                 provider: string | undefined;
+                message?: undefined;
             } | {
                 enabled: boolean;
                 status: "unavailable";
@@ -1366,11 +1477,19 @@ declare class HttpDispatcher {
                 message: string;
             };
             job: {
+                enabled: boolean;
+                status: "degraded" | "stub";
+                handlerReady: boolean;
+                route: string | undefined;
+                provider: string | undefined;
+                message: string | undefined;
+            } | {
                 enabled: boolean;
                 status: "available";
                 handlerReady: boolean;
                 route: string | undefined;
                 provider: string | undefined;
+                message?: undefined;
             } | {
                 enabled: boolean;
                 status: "unavailable";
@@ -1378,11 +1497,19 @@ declare class HttpDispatcher {
                 message: string;
             };
             ui: {
+                enabled: boolean;
+                status: "degraded" | "stub";
+                handlerReady: boolean;
+                route: string | undefined;
+                provider: string | undefined;
+                message: string | undefined;
+            } | {
                 enabled: boolean;
                 status: "available";
                 handlerReady: boolean;
                 route: string | undefined;
                 provider: string | undefined;
+                message?: undefined;
             } | {
                 enabled: boolean;
                 status: "unavailable";
@@ -1390,11 +1517,19 @@ declare class HttpDispatcher {
                 message: string;
             };
             workflow: {
+                enabled: boolean;
+                status: "degraded" | "stub";
+                handlerReady: boolean;
+                route: string | undefined;
+                provider: string | undefined;
+                message: string | undefined;
+            } | {
                 enabled: boolean;
                 status: "available";
                 handlerReady: boolean;
                 route: string | undefined;
                 provider: string | undefined;
+                message?: undefined;
             } | {
                 enabled: boolean;
                 status: "unavailable";
@@ -1403,22 +1538,29 @@ declare class HttpDispatcher {
             };
             realtime: {
                 enabled: boolean;
-                status: "available";
+                status: "unavailable";
                 handlerReady: boolean;
-                route: string | undefined;
-                provider: string | undefined;
+                message: string;
             } | {
                 enabled: boolean;
-                status: "unavailable";
+                status: "degraded" | "stub";
                 handlerReady: boolean;
                 message: string;
             };
             notification: {
+                enabled: boolean;
+                status: "degraded" | "stub";
+                handlerReady: boolean;
+                route: string | undefined;
+                provider: string | undefined;
+                message: string | undefined;
+            } | {
                 enabled: boolean;
                 status: "available";
                 handlerReady: boolean;
                 route: string | undefined;
                 provider: string | undefined;
+                message?: undefined;
             } | {
                 enabled: boolean;
                 status: "unavailable";
@@ -1426,11 +1568,19 @@ declare class HttpDispatcher {
                 message: string;
             };
             ai: {
+                enabled: boolean;
+                status: "degraded" | "stub";
+                handlerReady: boolean;
+                route: string | undefined;
+                provider: string | undefined;
+                message: string | undefined;
+            } | {
                 enabled: boolean;
                 status: "available";
                 handlerReady: boolean;
                 route: string | undefined;
                 provider: string | undefined;
+                message?: undefined;
             } | {
                 enabled: boolean;
                 status: "unavailable";
@@ -1438,11 +1588,19 @@ declare class HttpDispatcher {
                 message: string;
             };
             i18n: {
+                enabled: boolean;
+                status: "degraded" | "stub";
+                handlerReady: boolean;
+                route: string | undefined;
+                provider: string | undefined;
+                message: string | undefined;
+            } | {
                 enabled: boolean;
                 status: "available";
                 handlerReady: boolean;
                 route: string | undefined;
                 provider: string | undefined;
+                message?: undefined;
             } | {
                 enabled: boolean;
                 status: "unavailable";
@@ -1450,11 +1608,19 @@ declare class HttpDispatcher {
                 message: string;
             };
             graphql: {
+                enabled: boolean;
+                status: "degraded" | "stub";
+                handlerReady: boolean;
+                route: string | undefined;
+                provider: string | undefined;
+                message: string | undefined;
+            } | {
                 enabled: boolean;
                 status: "available";
                 handlerReady: boolean;
                 route: string | undefined;
                 provider: string | undefined;
+                message?: undefined;
             } | {
                 enabled: boolean;
                 status: "unavailable";
@@ -1462,11 +1628,19 @@ declare class HttpDispatcher {
                 message: string;
             };
             'file-storage': {
+                enabled: boolean;
+                status: "degraded" | "stub";
+                handlerReady: boolean;
+                route: string | undefined;
+                provider: string | undefined;
+                message: string | undefined;
+            } | {
                 enabled: boolean;
                 status: "available";
                 handlerReady: boolean;
                 route: string | undefined;
                 provider: string | undefined;
+                message?: undefined;
             } | {
                 enabled: boolean;
                 status: "unavailable";
@@ -1474,11 +1648,19 @@ declare class HttpDispatcher {
                 message: string;
             };
             search: {
+                enabled: boolean;
+                status: "degraded" | "stub";
+                handlerReady: boolean;
+                route: string | undefined;
+                provider: string | undefined;
+                message: string | undefined;
+            } | {
                 enabled: boolean;
                 status: "available";
                 handlerReady: boolean;
                 route: string | undefined;
                 provider: string | undefined;
+                message?: undefined;
             } | {
                 enabled: boolean;
                 status: "unavailable";
@@ -1499,6 +1681,18 @@ declare class HttpDispatcher {
         query: string;
         variables?: any;
     }, context: HttpProtocolContext): Promise<any>;
+    /**
+     * Resolve the RBAC/RLS execution context for a request that did NOT flow
+     * through {@link dispatch} (which resolves and caches it on
+     * `context.executionContext`). The dispatcher-plugin's direct `/graphql`
+     * route is the current caller. Mirrors the identity resolution `dispatch()`
+     * performs so an anonymous-deny gate can tell an authenticated caller from
+     * an anonymous one, and so the caller's identity can be THREADED to the
+     * engine (#2992 / ADR-0096 D1) instead of dropped. Best-effort: returns
+     * `undefined` on failure (treated as anonymous, i.e. denied under
+     * `requireAuth`).
+     */
+    private resolveRequestExecutionContext;
     /**
      * Handles Auth requests
      * path: sub-path after /auth/