@objectstack/runtime 12.5.0 → 13.0.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,19 @@ 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;
     /**
      * Normalise the inbound request into a Web-standard `Request` for the MCP
      * transport. Accepts an already-Web `Request`, or a node/Hono-style req

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,19 @@ 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;
     /**
      * Normalise the inbound request into a Web-standard `Request` for the MCP
      * transport. Accepts an already-Web `Request`, or a node/Hono-style req

package/dist/index.js

@@ -243,8 +243,20 @@ function installApiMethod(vm, parent, method, objectName, ctx, caps, required, o
   vm.setProp(parent, method, fn);
   fn.dispose();
 }
+function safeJsonStringify(v) {
+  const seen = /* @__PURE__ */ new WeakSet();
+  const json = JSON.stringify(v ?? null, function(_key, value) {
+    if (typeof value === "bigint") return value.toString();
+    if (typeof value === "object" && value !== null) {
+      if (seen.has(value)) return void 0;
+      seen.add(value);
+    }
+    return value;
+  });
+  return json ?? "null";
+}
 function jsonToHandle(vm, v) {
-  const json = JSON.stringify(v ?? null);
+  const json = safeJsonStringify(v);
   const r = vm.evalCode(`(${json})`);
   if (r.error) {
     const msg = vm.dump(r.error);
@@ -254,7 +266,7 @@ function jsonToHandle(vm, v) {
   return r.value;
 }
 function setGlobalJson(vm, name, v) {
-  const json = JSON.stringify(v ?? null);
+  const json = safeJsonStringify(v);
   const result = vm.evalCode(`(${json})`);
   if (result.error) {
     result.error.dispose();
@@ -264,7 +276,7 @@ function setGlobalJson(vm, name, v) {
   result.value.dispose();
 }
 function setObjectJson(vm, parent, key, v) {
-  const json = JSON.stringify(v ?? null);
+  const json = safeJsonStringify(v);
   const result = vm.evalCode(`(${json})`);
   if (result.error) {
     result.error.dispose();
@@ -1018,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"]
@@ -1384,8 +1396,7 @@ var init_app_plugin = __esm({
             "skills",
             "actions",
             "permissions",
-            "roles",
-            "profiles",
+            "positions",
             "translations",
             "sharingRules",
             "ragPipelines",
@@ -1745,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: {
@@ -1756,7 +1767,7 @@ async function createStandaloneStack(config) {
     ...objects ? { objects } : {},
     ...manifest ? { manifest } : {},
     ...permissions ? { permissions } : {},
-    ...roles ? { roles } : {}
+    ...positions ? { positions } : {}
   };
 }
 var StandaloneStackConfigSchema;
@@ -2073,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
@@ -2110,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;
@@ -2128,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");
@@ -2138,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({
@@ -2402,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.
@@ -2424,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) {
@@ -2433,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) };
     }
@@ -2460,9 +2534,28 @@ 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;
+    }
   }
   /**
    * Normalise the inbound request into a Web-standard `Request` for the MCP
@@ -3120,9 +3213,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) => ({
@@ -4412,7 +4505,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);
@@ -4720,7 +4813,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;
@@ -4784,7 +4877,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;
@@ -4963,7 +5056,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 {
     }
@@ -6114,7 +6213,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
           };