@objectstack/runtime 12.5.0 → 13.0.0

package/dist/index.cjs

@@ -265,8 +265,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);
@@ -276,7 +288,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();
@@ -286,7 +298,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();
@@ -1042,7 +1054,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"]
@@ -1408,8 +1420,7 @@ var init_app_plugin = __esm({
             "skills",
             "actions",
             "permissions",
-            "roles",
-            "profiles",
+            "positions",
             "translations",
             "sharingRules",
             "ragPipelines",
@@ -1764,7 +1775,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: {
@@ -1775,7 +1786,7 @@ async function createStandaloneStack(config) {
     ...objects ? { objects } : {},
     ...manifest ? { manifest } : {},
     ...permissions ? { permissions } : {},
-    ...roles ? { roles } : {}
+    ...positions ? { positions } : {}
   };
 }
 var import_node_path3, import_node_fs2, import_node_os, import_zod, import_types2, StandaloneStackConfigSchema;
@@ -1846,7 +1857,7 @@ __export(index_exports, {
   SandboxError: () => SandboxError,
   SeedLoaderService: () => import_objectql.SeedLoaderService,
   UnimplementedScriptRunner: () => UnimplementedScriptRunner,
-  _resetEnvDeprecationWarnings: () => import_types3._resetEnvDeprecationWarnings,
+  _resetEnvDeprecationWarnings: () => import_types4._resetEnvDeprecationWarnings,
   actionBodyRunnerFactory: () => actionBodyRunnerFactory,
   buildSecurityHeaders: () => buildSecurityHeaders,
   collectBundleActions: () => collectBundleActions,
@@ -1867,7 +1878,7 @@ __export(index_exports, {
   mergeRuntimeModule: () => mergeRuntimeModule,
   parseTraceparent: () => parseTraceparent,
   readArtifactSource: () => readArtifactSource,
-  readEnvWithDeprecation: () => import_types3.readEnvWithDeprecation,
+  readEnvWithDeprecation: () => import_types4.readEnvWithDeprecation,
   resolveDefaultArtifactPath: () => resolveDefaultArtifactPath,
   resolveErrorReporter: () => resolveErrorReporter,
   resolveMetrics: () => resolveMetrics,
@@ -2148,7 +2159,9 @@ function safeGet(ctx, name) {
 
 // src/http-dispatcher.ts
 var import_core5 = require("@objectstack/core");
+var import_types3 = require("@objectstack/types");
 var import_system = require("@objectstack/spec/system");
+var import_ai = require("@objectstack/spec/ai");
 var import_shared2 = require("@objectstack/spec/shared");
 init_package_state_store();
 
@@ -2183,6 +2196,12 @@ function checkApiExposure(def, action) {
 
 // src/security/resolve-execution-context.ts
 var import_core3 = require("@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;
@@ -2201,6 +2220,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");
@@ -2211,19 +2246,29 @@ async function resolveExecutionContext(opts) {
       return void 0;
     }
   };
-  const authz = await (0, import_core3.resolveAuthzContext)({ ql, headers, getSession });
+  const getSessionForProvenance = oauthPrincipal ? async () => ({ user: { id: oauthPrincipal.userId } }) : oauthBearerPresented ? async () => void 0 : getSession;
+  const authz = await (0, import_core3.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 (0, import_core3.resolveLocalizationContext)({
@@ -2467,9 +2512,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.
@@ -2489,7 +2535,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) => import_ai.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 (${import_ai.MCP_OAUTH_SCOPES.join(", ")})`,
+        403
+      );
+      response.headers = {
+        "WWW-Authenticate": `Bearer error="insufficient_scope", scope="${import_ai.MCP_OAUTH_SCOPES.join(" ")}"` + (resourceMetadataUrl ? `, resource_metadata="${resourceMetadataUrl}"` : "")
+      };
+      return { handled: true, response };
     }
     const webRequest = this.toMcpWebRequest(context.request, body);
     if (!webRequest) {
@@ -2498,7 +2566,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) };
     }
@@ -2525,9 +2599,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 (0, import_types3.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
@@ -3185,9 +3278,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) => ({
@@ -4477,7 +4570,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);
@@ -4785,7 +4878,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;
@@ -4849,7 +4942,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;
@@ -5028,7 +5121,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 {
     }
@@ -6169,7 +6268,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
           };
@@ -6543,7 +6642,7 @@ init_body_runner();
 // src/index.ts
 var import_rest = require("@objectstack/rest");
 __reExport(index_exports, require("@objectstack/core"), module.exports);
-var import_types3 = require("@objectstack/types");
+var import_types4 = require("@objectstack/types");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AppPlugin,