@objectstack/runtime 12.6.0 → 14.3.0

package/dist/index.cjs

@@ -1054,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"]
@@ -1420,8 +1420,7 @@ var init_app_plugin = __esm({
             "skills",
             "actions",
             "permissions",
-            "roles",
-            "profiles",
+            "positions",
             "translations",
             "sharingRules",
             "ragPipelines",
@@ -1776,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: {
@@ -1787,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;
@@ -1858,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,
@@ -1879,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,
@@ -2160,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();
 
@@ -2195,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;
@@ -2213,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");
@@ -2223,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)({
@@ -2479,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.
@@ -2501,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) {
@@ -2510,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) };
     }
@@ -2537,9 +2599,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 (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;
+    }
+  }
+  /**
+   * `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
@@ -3197,9 +3345,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) => ({
@@ -3706,6 +3854,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/
@@ -4489,7 +4687,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);
@@ -4711,8 +4909,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,
@@ -4797,7 +5003,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;
@@ -4861,7 +5067,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;
@@ -5040,7 +5246,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 {
     }
@@ -5088,6 +5300,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);
       }
@@ -5115,6 +5330,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);
       }
@@ -5823,6 +6041,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 });
@@ -6127,9 +6353,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);
@@ -6137,9 +6361,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);
@@ -6181,7 +6403,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
           };
@@ -6555,7 +6777,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,