@objectstack/runtime 12.6.0 → 14.3.0

package/dist/index.d.cts

@@ -122,15 +122,15 @@ interface StandaloneStackResult {
      * App-declared RBAC metadata, surfaced so the CLI (`serve`/`dev`/`start`)
      * can wire it without a host `objectstack.config.ts`. In particular the
      * `serve` command reads `permissions[]` to honour an app-declared default
-     * profile (ADR-0056 D7 — `appDefaultProfileName` → SecurityPlugin
-     * `fallbackPermissionSet`) and reads both `roles[]` and `permissions[]` to
+     * profile (ADR-0056 D7 — `appDefaultPermissionSetName` → SecurityPlugin
+     * `fallbackPermissionSet`) and reads both `positions[]` and `permissions[]` to
      * register application org roles with Better-Auth. Without these the
      * artifact-serve path silently fell back to the built-in `member_default`
      * (owner-only), so an `isDefault` profile declared purely in app metadata
      * was ignored under `objectstack dev`.
      */
     permissions?: any[];
-    roles?: any[];
+    positions?: any[];
 }
 declare function createStandaloneStack(config?: StandaloneStackConfig): Promise<StandaloneStackResult>;
 
@@ -1038,9 +1038,10 @@ declare class HttpDispatcher {
      * Handle an MCP request over the Streamable HTTP transport (`/mcp`).
      *
      * Gating + auth (fail-closed):
-     *  - **opt-in**: only served when `OS_MCP_SERVER_ENABLED=true` (single-env
-     *    runtime). Multi-tenant cloud overrides this gate per env. When off we
-     *    return 404 so the surface isn't advertised.
+     *  - **default-on**: served unless `OS_MCP_SERVER_ENABLED=false` (single-env
+     *    runtime; MCP is a core platform capability). Multi-tenant cloud
+     *    overrides this gate per env. When opted out we return 404 so the
+     *    surface isn't advertised.
      *  - **auth**: requires a principal already resolved by
      *    `resolveExecutionContext` (the `sys_api_key` Bearer/header path or a
      *    session). Anonymous → 401.
@@ -1051,8 +1052,31 @@ declare class HttpDispatcher {
      * uses. An external agent can never exceed the key's authority.
      */
     handleMcp(body: any, context: HttpProtocolContext): Promise<HttpDispatcherResult>;
-    /** Whether the MCP HTTP surface is opted in for this single-env runtime. */
+    /**
+     * Whether the MCP HTTP surface is on for this single-env runtime.
+     * Default-on core capability; `OS_MCP_SERVER_ENABLED=false` opts out
+     * (single decision point: `isMcpServerEnabled` in `@objectstack/types`).
+     */
     private static isMcpEnabled;
+    /**
+     * Absolute URL of the RFC 9728 protected-resource metadata for the MCP
+     * endpoint, advertised via `WWW-Authenticate` (#2698). `null` when the
+     * OAuth track is off — the auth service owns the decision (AS enabled +
+     * OAuth 2.1 TLS rule), the dispatcher only relays it. Never throws.
+     */
+    private getMcpResourceMetadataUrl;
+    /**
+     * `GET /mcp/skill` — the environment-customized portable Agent Skill
+     * (`SKILL.md`), rendered by the MCP service (ADR-0036 Amendment C: ONE
+     * generic skill; only the connection URL is environment-specific).
+     *
+     * Served PUBLIC like `/discovery`: the content is generic agent
+     * instructions plus a URL the caller already knows — no schema, no
+     * tenant data. Gated on the same default-on switch as the `/mcp` route
+     * (404 when opted out, so the surface isn't advertised) and 501 when the
+     * MCP plugin isn't loaded, mirroring `handleMcp`.
+     */
+    handleMcpSkill(method: string, context: HttpProtocolContext): Promise<HttpDispatcherResult>;
     /**
      * Normalise the inbound request into a Web-standard `Request` for the MCP
      * transport. Accepts an already-Web `Request`, or a node/Hono-style req
@@ -1489,6 +1513,21 @@ declare class HttpDispatcher {
      *   POST /read/all   → markAllRead
      */
     handleNotification(path: string, method: string, body: any, query: any, context: HttpProtocolContext): Promise<HttpDispatcherResult>;
+    /**
+     * Handle the security admin surface (`/security/...`) — ADR-0090 D5/D9
+     * suggested audience bindings. A package's `isDefault: true` permission
+     * set is an install-time SUGGESTION to bind it to the `everyone` position;
+     * these routes let an admin see and resolve those suggestions. The
+     * `security` service does the real gating (tenant-admin pre-check, and the
+     * confirm write runs under the audience-anchor + delegated-admin gates
+     * with the caller's execution context — never auto-bound, never system).
+     *
+     * Routes:
+     *   GET  /security/suggested-bindings?status=&packageId=   → list (reconciles first)
+     *   POST /security/suggested-bindings/:id/confirm          → create the anchor binding
+     *   POST /security/suggested-bindings/:id/dismiss          → decline the suggestion
+     */
+    handleSecurity(path: string, method: string, _body: any, query: any, context: HttpProtocolContext): Promise<HttpDispatcherResult>;
     /**
      * Handles i18n requests
      * path: sub-path after /i18n/

package/dist/index.d.ts

@@ -122,15 +122,15 @@ interface StandaloneStackResult {
      * App-declared RBAC metadata, surfaced so the CLI (`serve`/`dev`/`start`)
      * can wire it without a host `objectstack.config.ts`. In particular the
      * `serve` command reads `permissions[]` to honour an app-declared default
-     * profile (ADR-0056 D7 — `appDefaultProfileName` → SecurityPlugin
-     * `fallbackPermissionSet`) and reads both `roles[]` and `permissions[]` to
+     * profile (ADR-0056 D7 — `appDefaultPermissionSetName` → SecurityPlugin
+     * `fallbackPermissionSet`) and reads both `positions[]` and `permissions[]` to
      * register application org roles with Better-Auth. Without these the
      * artifact-serve path silently fell back to the built-in `member_default`
      * (owner-only), so an `isDefault` profile declared purely in app metadata
      * was ignored under `objectstack dev`.
      */
     permissions?: any[];
-    roles?: any[];
+    positions?: any[];
 }
 declare function createStandaloneStack(config?: StandaloneStackConfig): Promise<StandaloneStackResult>;
 
@@ -1038,9 +1038,10 @@ declare class HttpDispatcher {
      * Handle an MCP request over the Streamable HTTP transport (`/mcp`).
      *
      * Gating + auth (fail-closed):
-     *  - **opt-in**: only served when `OS_MCP_SERVER_ENABLED=true` (single-env
-     *    runtime). Multi-tenant cloud overrides this gate per env. When off we
-     *    return 404 so the surface isn't advertised.
+     *  - **default-on**: served unless `OS_MCP_SERVER_ENABLED=false` (single-env
+     *    runtime; MCP is a core platform capability). Multi-tenant cloud
+     *    overrides this gate per env. When opted out we return 404 so the
+     *    surface isn't advertised.
      *  - **auth**: requires a principal already resolved by
      *    `resolveExecutionContext` (the `sys_api_key` Bearer/header path or a
      *    session). Anonymous → 401.
@@ -1051,8 +1052,31 @@ declare class HttpDispatcher {
      * uses. An external agent can never exceed the key's authority.
      */
     handleMcp(body: any, context: HttpProtocolContext): Promise<HttpDispatcherResult>;
-    /** Whether the MCP HTTP surface is opted in for this single-env runtime. */
+    /**
+     * Whether the MCP HTTP surface is on for this single-env runtime.
+     * Default-on core capability; `OS_MCP_SERVER_ENABLED=false` opts out
+     * (single decision point: `isMcpServerEnabled` in `@objectstack/types`).
+     */
     private static isMcpEnabled;
+    /**
+     * Absolute URL of the RFC 9728 protected-resource metadata for the MCP
+     * endpoint, advertised via `WWW-Authenticate` (#2698). `null` when the
+     * OAuth track is off — the auth service owns the decision (AS enabled +
+     * OAuth 2.1 TLS rule), the dispatcher only relays it. Never throws.
+     */
+    private getMcpResourceMetadataUrl;
+    /**
+     * `GET /mcp/skill` — the environment-customized portable Agent Skill
+     * (`SKILL.md`), rendered by the MCP service (ADR-0036 Amendment C: ONE
+     * generic skill; only the connection URL is environment-specific).
+     *
+     * Served PUBLIC like `/discovery`: the content is generic agent
+     * instructions plus a URL the caller already knows — no schema, no
+     * tenant data. Gated on the same default-on switch as the `/mcp` route
+     * (404 when opted out, so the surface isn't advertised) and 501 when the
+     * MCP plugin isn't loaded, mirroring `handleMcp`.
+     */
+    handleMcpSkill(method: string, context: HttpProtocolContext): Promise<HttpDispatcherResult>;
     /**
      * Normalise the inbound request into a Web-standard `Request` for the MCP
      * transport. Accepts an already-Web `Request`, or a node/Hono-style req
@@ -1489,6 +1513,21 @@ declare class HttpDispatcher {
      *   POST /read/all   → markAllRead
      */
     handleNotification(path: string, method: string, body: any, query: any, context: HttpProtocolContext): Promise<HttpDispatcherResult>;
+    /**
+     * Handle the security admin surface (`/security/...`) — ADR-0090 D5/D9
+     * suggested audience bindings. A package's `isDefault: true` permission
+     * set is an install-time SUGGESTION to bind it to the `everyone` position;
+     * these routes let an admin see and resolve those suggestions. The
+     * `security` service does the real gating (tenant-admin pre-check, and the
+     * confirm write runs under the audience-anchor + delegated-admin gates
+     * with the caller's execution context — never auto-bound, never system).
+     *
+     * Routes:
+     *   GET  /security/suggested-bindings?status=&packageId=   → list (reconciles first)
+     *   POST /security/suggested-bindings/:id/confirm          → create the anchor binding
+     *   POST /security/suggested-bindings/:id/dismiss          → decline the suggestion
+     */
+    handleSecurity(path: string, method: string, _body: any, query: any, context: HttpProtocolContext): Promise<HttpDispatcherResult>;
     /**
      * Handles i18n requests
      * path: sub-path after /i18n/

package/dist/index.js

@@ -1030,7 +1030,7 @@ var init_app_plugin = __esm({
             if (typeof metadata?.registerInMemory === "function") {
               const securityBundle = this.bundle.manifest ? { ...this.bundle.manifest, ...this.bundle } : this.bundle;
               const SECURITY_FIELDS = [
-                ["roles", "role"],
+                ["positions", "position"],
                 ["permissions", "permission"],
                 ["sharingRules", "sharing_rule"],
                 ["policies", "policy"]
@@ -1396,8 +1396,7 @@ var init_app_plugin = __esm({
             "skills",
             "actions",
             "permissions",
-            "roles",
-            "profiles",
+            "positions",
             "translations",
             "sharingRules",
             "ragPipelines",
@@ -1757,7 +1756,7 @@ async function createStandaloneStack(config) {
   const objects = Array.isArray(artifactBundle?.objects) ? artifactBundle.objects : void 0;
   const manifest = artifactBundle?.manifest;
   const permissions = Array.isArray(artifactBundle?.permissions) ? artifactBundle.permissions : void 0;
-  const roles = Array.isArray(artifactBundle?.roles) ? artifactBundle.roles : void 0;
+  const positions = Array.isArray(artifactBundle?.positions) ? artifactBundle.positions : void 0;
   return {
     plugins,
     api: {
@@ -1768,7 +1767,7 @@ async function createStandaloneStack(config) {
     ...objects ? { objects } : {},
     ...manifest ? { manifest } : {},
     ...permissions ? { permissions } : {},
-    ...roles ? { roles } : {}
+    ...positions ? { positions } : {}
   };
 }
 var StandaloneStackConfigSchema;
@@ -2085,7 +2084,9 @@ function safeGet(ctx, name) {
 // src/http-dispatcher.ts
 init_package_state_store();
 import { getEnv, resolveLocale, evaluateAuthGate, isAuthGateAllowlisted } from "@objectstack/core";
+import { isMcpServerEnabled } from "@objectstack/types";
 import { CoreServiceName } from "@objectstack/spec/system";
+import { MCP_OAUTH_SCOPES } from "@objectstack/spec/ai";
 import { pluralToSingular, PLURAL_TO_SINGULAR } from "@objectstack/spec/shared";
 
 // src/api-exposure.ts
@@ -2122,6 +2123,12 @@ import {
   resolveAuthzContext,
   resolveLocalizationContext
 } from "@objectstack/core";
+function extractJwtBearer(headers) {
+  const auth = headers.get("authorization");
+  const bearer = auth?.match(/^Bearer\s+(\S+)$/i)?.[1];
+  if (!bearer || bearer.startsWith("osk_")) return void 0;
+  return bearer.split(".").length === 3 ? bearer : void 0;
+}
 function toHeaders(input) {
   if (!input) return new Headers();
   if (typeof Headers !== "undefined" && input instanceof Headers) return input;
@@ -2140,6 +2147,22 @@ function toHeaders(input) {
 async function resolveExecutionContext(opts) {
   const headers = toHeaders(opts.request?.headers);
   const ql = await opts.getQl();
+  let oauthPrincipal;
+  let oauthBearerPresented = false;
+  if (opts.acceptOAuthAccessToken) {
+    const jwtBearer = extractJwtBearer(headers);
+    if (jwtBearer) {
+      oauthBearerPresented = true;
+      try {
+        const authService = await opts.getService("auth");
+        const verified = await authService?.verifyMcpAccessToken?.(jwtBearer);
+        if (verified?.userId && Array.isArray(verified.scopes)) {
+          oauthPrincipal = verified;
+        }
+      } catch {
+      }
+    }
+  }
   const getSession = async (h) => {
     try {
       const authService = await opts.getService("auth");
@@ -2150,19 +2173,29 @@ async function resolveExecutionContext(opts) {
       return void 0;
     }
   };
-  const authz = await resolveAuthzContext({ ql, headers, getSession });
+  const getSessionForProvenance = oauthPrincipal ? async () => ({ user: { id: oauthPrincipal.userId } }) : oauthBearerPresented ? async () => void 0 : getSession;
+  const authz = await resolveAuthzContext({ ql, headers, getSession: getSessionForProvenance });
   const ctx = {
-    roles: authz.roles,
+    positions: authz.positions,
     permissions: authz.permissions,
     systemPermissions: authz.systemPermissions,
     isSystem: false
   };
+  if (authz.userId) {
+    ctx.principalKind = "human";
+  } else {
+    ctx.principalKind = "guest";
+    ctx.positions = ["guest"];
+  }
   if (authz.userId) ctx.userId = authz.userId;
   if (authz.tenantId) ctx.tenantId = authz.tenantId;
   if (authz.email) ctx.email = authz.email;
   if (authz.accessToken) ctx.accessToken = authz.accessToken;
   if (authz.tabPermissions) ctx.tabPermissions = authz.tabPermissions;
   ctx.org_user_ids = authz.org_user_ids;
+  if (oauthPrincipal && ctx.userId === oauthPrincipal.userId) {
+    ctx.oauthScopes = oauthPrincipal.scopes;
+  }
   if (authz.userId) {
     const settings = await Promise.resolve(opts.getService("settings")).catch(() => void 0);
     const localization = await resolveLocalizationContext({
@@ -2414,9 +2447,10 @@ var _HttpDispatcher = class _HttpDispatcher {
    * Handle an MCP request over the Streamable HTTP transport (`/mcp`).
    *
    * Gating + auth (fail-closed):
-   *  - **opt-in**: only served when `OS_MCP_SERVER_ENABLED=true` (single-env
-   *    runtime). Multi-tenant cloud overrides this gate per env. When off we
-   *    return 404 so the surface isn't advertised.
+   *  - **default-on**: served unless `OS_MCP_SERVER_ENABLED=false` (single-env
+   *    runtime; MCP is a core platform capability). Multi-tenant cloud
+   *    overrides this gate per env. When opted out we return 404 so the
+   *    surface isn't advertised.
    *  - **auth**: requires a principal already resolved by
    *    `resolveExecutionContext` (the `sys_api_key` Bearer/header path or a
    *    session). Anonymous → 401.
@@ -2436,7 +2470,29 @@ var _HttpDispatcher = class _HttpDispatcher {
     }
     const ec = context.executionContext;
     if (!ec || !ec.userId && !ec.isSystem) {
-      return { handled: true, response: this.error("Unauthorized: a valid API key is required", 401) };
+      const resourceMetadataUrl = await this.getMcpResourceMetadataUrl(context);
+      const response = this.error(
+        resourceMetadataUrl ? "Unauthorized: a valid OAuth access token or API key is required" : "Unauthorized: a valid API key is required",
+        401
+      );
+      if (resourceMetadataUrl) {
+        response.headers = {
+          "WWW-Authenticate": `Bearer realm="ObjectStack MCP", resource_metadata="${resourceMetadataUrl}"`
+        };
+      }
+      return { handled: true, response };
+    }
+    const grantedScopes = Array.isArray(ec.oauthScopes) ? ec.oauthScopes : void 0;
+    if (grantedScopes && !grantedScopes.some((s) => MCP_OAUTH_SCOPES.includes(s))) {
+      const resourceMetadataUrl = await this.getMcpResourceMetadataUrl(context);
+      const response = this.error(
+        `Forbidden: the access token grants none of the MCP scopes (${MCP_OAUTH_SCOPES.join(", ")})`,
+        403
+      );
+      response.headers = {
+        "WWW-Authenticate": `Bearer error="insufficient_scope", scope="${MCP_OAUTH_SCOPES.join(" ")}"` + (resourceMetadataUrl ? `, resource_metadata="${resourceMetadataUrl}"` : "")
+      };
+      return { handled: true, response };
     }
     const webRequest = this.toMcpWebRequest(context.request, body);
     if (!webRequest) {
@@ -2445,7 +2501,13 @@ var _HttpDispatcher = class _HttpDispatcher {
     const bridge = this.buildMcpBridge(context);
     let webRes;
     try {
-      webRes = await mcp.handleHttpRequest(webRequest, { bridge, parsedBody: body });
+      webRes = await mcp.handleHttpRequest(webRequest, {
+        bridge,
+        parsedBody: body,
+        // undefined = not scope-limited (API key / session); an array
+        // narrows the registered tool families inside the MCP runtime.
+        ...grantedScopes ? { toolOptions: { grantedScopes } } : {}
+      });
     } catch (err) {
       return { handled: true, response: this.error(err?.message ?? "MCP request failed", 500) };
     }
@@ -2472,9 +2534,95 @@ var _HttpDispatcher = class _HttpDispatcher {
     }
     return { handled: true, response: { status: webRes.status, headers, body: responseBody } };
   }
-  /** Whether the MCP HTTP surface is opted in for this single-env runtime. */
+  /**
+   * Whether the MCP HTTP surface is on for this single-env runtime.
+   * Default-on core capability; `OS_MCP_SERVER_ENABLED=false` opts out
+   * (single decision point: `isMcpServerEnabled` in `@objectstack/types`).
+   */
   static isMcpEnabled() {
-    return typeof process !== "undefined" && process.env?.OS_MCP_SERVER_ENABLED === "true";
+    return isMcpServerEnabled();
+  }
+  /**
+   * Absolute URL of the RFC 9728 protected-resource metadata for the MCP
+   * endpoint, advertised via `WWW-Authenticate` (#2698). `null` when the
+   * OAuth track is off — the auth service owns the decision (AS enabled +
+   * OAuth 2.1 TLS rule), the dispatcher only relays it. Never throws.
+   */
+  async getMcpResourceMetadataUrl(context) {
+    try {
+      const authService = await this.resolveService("auth", context.environmentId);
+      const url = authService?.getMcpResourceMetadataUrl?.();
+      return typeof url === "string" && url ? url : null;
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * `GET /mcp/skill` — the environment-customized portable Agent Skill
+   * (`SKILL.md`), rendered by the MCP service (ADR-0036 Amendment C: ONE
+   * generic skill; only the connection URL is environment-specific).
+   *
+   * Served PUBLIC like `/discovery`: the content is generic agent
+   * instructions plus a URL the caller already knows — no schema, no
+   * tenant data. Gated on the same default-on switch as the `/mcp` route
+   * (404 when opted out, so the surface isn't advertised) and 501 when the
+   * MCP plugin isn't loaded, mirroring `handleMcp`.
+   */
+  async handleMcpSkill(method, context) {
+    if (!_HttpDispatcher.isMcpEnabled()) {
+      return { handled: true, response: this.error("MCP server is not enabled for this environment", 404) };
+    }
+    if (method !== "GET") {
+      return {
+        handled: true,
+        response: {
+          status: 405,
+          headers: { Allow: "GET" },
+          body: { success: false, error: { message: "Method not allowed \u2014 use GET", code: 405 } }
+        }
+      };
+    }
+    const mcp = await this.resolveService("mcp", context.environmentId);
+    if (!mcp || typeof mcp.renderSkill !== "function") {
+      return { handled: true, response: this.error("MCP server is not available", 501) };
+    }
+    let mcpUrl;
+    try {
+      const authService = await this.resolveService("auth", context.environmentId);
+      const url = authService?.getMcpResourceUrl?.();
+      if (typeof url === "string" && url) mcpUrl = url;
+    } catch {
+    }
+    if (!mcpUrl) {
+      try {
+        const webReq = this.toMcpWebRequest(context.request, void 0);
+        const host = webReq?.headers.get("host");
+        if (host) {
+          const proto = webReq?.headers.get("x-forwarded-proto") || "http";
+          mcpUrl = `${proto}://${host}/api/v1/mcp`;
+        }
+      } catch {
+      }
+    }
+    const markdown = mcp.renderSkill({ mcpUrl });
+    return {
+      handled: true,
+      result: {
+        type: "stream",
+        status: 200,
+        contentType: "text/markdown; charset=utf-8",
+        headers: {
+          "content-type": "text/markdown; charset=utf-8",
+          "content-disposition": 'inline; filename="SKILL.md"',
+          // Same reasoning as /discovery (cloud#152): reflects mutable
+          // runtime config (base URL), must never be edge-cached stale.
+          "cache-control": "no-store"
+        },
+        events: (async function* () {
+          yield markdown;
+        })()
+      }
+    };
   }
   /**
    * Normalise the inbound request into a Web-standard `Request` for the MCP
@@ -3132,9 +3280,9 @@ var _HttpDispatcher = class _HttpDispatcher {
       notifications: hasNotification ? `${prefix}/notifications` : void 0,
       ai: hasAi ? `${prefix}/ai` : void 0,
       i18n: hasI18n ? `${prefix}/i18n` : void 0,
-      // MCP (Streamable HTTP) is opt-in per env — only advertised
-      // when OS_MCP_SERVER_ENABLED=true so the surface isn't exposed
-      // by default. The objectui Integrations page reads this.
+      // MCP (Streamable HTTP) is a default-on core capability —
+      // advertised unless OS_MCP_SERVER_ENABLED=false opts the env
+      // out. The objectui Integrations page reads this.
       mcp: _HttpDispatcher.isMcpEnabled() ? `${prefix}/mcp` : void 0
     };
     const svcAvailable = (route, provider) => ({
@@ -3641,6 +3789,56 @@ var _HttpDispatcher = class _HttpDispatcher {
     }
     return { handled: false };
   }
+  /**
+   * Handle the security admin surface (`/security/...`) — ADR-0090 D5/D9
+   * suggested audience bindings. A package's `isDefault: true` permission
+   * set is an install-time SUGGESTION to bind it to the `everyone` position;
+   * these routes let an admin see and resolve those suggestions. The
+   * `security` service does the real gating (tenant-admin pre-check, and the
+   * confirm write runs under the audience-anchor + delegated-admin gates
+   * with the caller's execution context — never auto-bound, never system).
+   *
+   * Routes:
+   *   GET  /security/suggested-bindings?status=&packageId=   → list (reconciles first)
+   *   POST /security/suggested-bindings/:id/confirm          → create the anchor binding
+   *   POST /security/suggested-bindings/:id/dismiss          → decline the suggestion
+   */
+  async handleSecurity(path, method, _body, query, context) {
+    const service = await this.resolveService("security", context.environmentId);
+    if (!service || typeof service.listAudienceBindingSuggestions !== "function") {
+      return { handled: true, response: this.error("Security service not available", 503) };
+    }
+    const ec = context.executionContext;
+    if (!ec?.userId && !ec?.isSystem) {
+      return { handled: true, response: this.error("Authentication required", 401) };
+    }
+    const m = method.toUpperCase();
+    const parts = path.split("/").filter(Boolean);
+    if (parts[0] !== "suggested-bindings") return { handled: false };
+    try {
+      if (parts.length === 1 && m === "GET") {
+        const status = query?.status ? String(query.status) : void 0;
+        const packageId = query?.packageId ? String(query.packageId) : void 0;
+        const result = await service.listAudienceBindingSuggestions(ec, { status, packageId });
+        return { handled: true, response: this.success(result) };
+      }
+      if (parts.length === 3 && m === "POST") {
+        const id = decodeURIComponent(parts[1]);
+        if (parts[2] === "confirm") {
+          const result = await service.confirmAudienceBindingSuggestion(ec, id);
+          return { handled: true, response: this.success(result) };
+        }
+        if (parts[2] === "dismiss") {
+          const result = await service.dismissAudienceBindingSuggestion(ec, id);
+          return { handled: true, response: this.success(result) };
+        }
+      }
+      return { handled: false };
+    } catch (err) {
+      const status = typeof err?.statusCode === "number" ? err.statusCode : 500;
+      return { handled: true, response: this.error(err?.message ?? "Security operation failed", status) };
+    }
+  }
   /**
    * Handles i18n requests
    * path: sub-path after /i18n/
@@ -4424,7 +4622,7 @@ var _HttpDispatcher = class _HttpDispatcher {
           const ec = context?.executionContext;
           const userIdFromAuth = context?.user?.id ?? context?.userId ?? ec?.userId;
           if (userIdFromAuth) automationContext.userId = userIdFromAuth;
-          if (Array.isArray(ec?.roles) && ec.roles.length) automationContext.roles = ec.roles;
+          if (Array.isArray(ec?.positions) && ec.positions.length) automationContext.positions = ec.positions;
           if (Array.isArray(ec?.permissions) && ec.permissions.length) automationContext.permissions = ec.permissions;
           if (ec?.tenantId) automationContext.tenantId = ec.tenantId;
           const result = await automationService.execute(name, automationContext);
@@ -4646,8 +4844,16 @@ var _HttpDispatcher = class _HttpDispatcher {
         return Array.isArray(rows) ? rows : rows?.value ?? [];
       }
     };
-    const userIdFromAuth = _context?.user?.id ?? _context?.userId ?? "system";
-    const userFromAuth = _context?.user ?? { id: userIdFromAuth, name: userIdFromAuth };
+    const ec = _context?.executionContext;
+    const userFromAuth = ec?.userId ? {
+      id: ec.userId,
+      name: ec.userId,
+      email: ec.email,
+      roles: Array.isArray(ec.positions) ? ec.positions : [],
+      positions: Array.isArray(ec.positions) ? ec.positions : [],
+      permissions: Array.isArray(ec.permissions) ? ec.permissions : [],
+      tenantId: ec.tenantId
+    } : { id: "system", name: "system", roles: [], positions: [], permissions: [] };
     const actionContext = {
       record,
       user: userFromAuth,
@@ -4732,7 +4938,7 @@ var _HttpDispatcher = class _HttpDispatcher {
         id: ec.userId,
         displayName: ec.userDisplayName ?? ec.userName ?? ec.userId,
         email: ec.userEmail,
-        roles: Array.isArray(ec.roles) ? ec.roles : [],
+        roles: Array.isArray(ec.positions) ? ec.positions : [],
         permissions: Array.isArray(ec.permissions) ? ec.permissions : [],
         organizationId: ec.tenantId
       } : void 0;
@@ -4796,7 +5002,7 @@ var _HttpDispatcher = class _HttpDispatcher {
     if (!svc) {
       return { handled: true, response: this.error("Sharing is not configured for this environment", 501) };
     }
-    const SYSTEM_CTX = { isSystem: true, roles: [], permissions: [] };
+    const SYSTEM_CTX = { isSystem: true, positions: [], permissions: [] };
     const m = method.toUpperCase();
     const parts = subPath.replace(/^\/+/, "").split("/").filter(Boolean);
     const ec = context.executionContext;
@@ -4975,7 +5181,13 @@ var _HttpDispatcher = class _HttpDispatcher {
           }
           return this.getObjectQLService(context.environmentId);
         },
-        request: context.request
+        request: context.request,
+        // OAuth 2.1 access tokens are honoured ONLY on the MCP
+        // surface (#2698): their coarse tool-family scopes are
+        // enforced at MCP tool dispatch, which other routes don't do.
+        // Matches the plain and `/projects/:id`-scoped route forms
+        // (the scoped prefix is stripped only later, below).
+        acceptOAuthAccessToken: /^(?:\/projects\/[^/]+)?\/mcp(?:[/?]|$)/.test(cleanPath)
       });
     } catch {
     }
@@ -5023,6 +5235,9 @@ var _HttpDispatcher = class _HttpDispatcher {
       if (cleanPath.startsWith("/data")) {
         return this.handleData(cleanPath.substring(5), method, body, query, context);
       }
+      if (cleanPath === "/mcp/skill" || cleanPath.startsWith("/mcp/skill?")) {
+        return this.handleMcpSkill(method, context);
+      }
       if (cleanPath === "/mcp" || cleanPath.startsWith("/mcp/") || cleanPath.startsWith("/mcp?")) {
         return this.handleMcp(body, context);
       }
@@ -5050,6 +5265,9 @@ var _HttpDispatcher = class _HttpDispatcher {
       if (cleanPath.startsWith("/notifications")) {
         return this.handleNotification(cleanPath.substring(14), method, body, query, context);
       }
+      if (cleanPath === "/security" || cleanPath.startsWith("/security/")) {
+        return this.handleSecurity(cleanPath.substring(9), method, body, query, context);
+      }
       if (cleanPath.startsWith("/packages")) {
         return this.handlePackages(cleanPath.substring(9), method, body, query, context);
       }
@@ -5768,6 +5986,14 @@ function createDispatcherPlugin(config = {}) {
       mountMcp("POST");
       mountMcp("GET");
       mountMcp("DELETE");
+      server.get(`${prefix}/mcp/skill`, async (req, res) => {
+        try {
+          const result = await dispatcher.dispatch("GET", "/mcp/skill", req.body, req.query, { request: req });
+          sendResult(result, res);
+        } catch (err) {
+          errorResponse(err, res);
+        }
+      });
       server.post(`${prefix}/keys`, async (req, res) => {
         try {
           const result = await dispatcher.dispatch("POST", "/keys", req.body, req.query, { request: req });
@@ -6072,9 +6298,7 @@ function createDispatcherPlugin(config = {}) {
       const registerActionRoutes = (base) => {
         server.post(`${base}/actions/:object/:action`, async (req, res) => {
           try {
-            const ctx2 = { request: req };
-            if (req.params?.environmentId) ctx2.environmentId = req.params.environmentId;
-            const result = await dispatcher.handleActions(`/${req.params.object}/${req.params.action}`, "POST", req.body, ctx2);
+            const result = await dispatcher.dispatch("POST", `/actions/${req.params.object}/${req.params.action}`, req.body, req.query, { request: req });
             sendResult(result, res);
           } catch (err) {
             errorResponse(err, res);
@@ -6082,9 +6306,7 @@ function createDispatcherPlugin(config = {}) {
         });
         server.post(`${base}/actions/:object/:action/:recordId`, async (req, res) => {
           try {
-            const ctx2 = { request: req };
-            if (req.params?.environmentId) ctx2.environmentId = req.params.environmentId;
-            const result = await dispatcher.handleActions(`/${req.params.object}/${req.params.action}/${req.params.recordId}`, "POST", req.body, ctx2);
+            const result = await dispatcher.dispatch("POST", `/actions/${req.params.object}/${req.params.action}/${req.params.recordId}`, req.body, req.query, { request: req });
             sendResult(result, res);
           } catch (err) {
             errorResponse(err, res);
@@ -6126,7 +6348,7 @@ function createDispatcherPlugin(config = {}) {
             id: userId,
             displayName: sessionData?.user?.name ?? sessionData?.user?.email ?? userId,
             email: sessionData?.user?.email,
-            roles: [],
+            positions: [],
             permissions: [],
             organizationId: sessionData?.session?.activeOrganizationId
           };