@objectstack/core 10.3.0 → 11.1.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import { Logger, IServiceRegistry } from '@objectstack/spec/contracts';
-export { DriverInterface, IDataDriver, IDataEngine, IHttpRequest, IHttpResponse, IHttpServer, Logger, Middleware, RouteHandler } from '@objectstack/spec/contracts';
+export { IDataDriver, IDataEngine, IHttpRequest, IHttpResponse, IHttpServer, Logger, Middleware, RouteHandler } from '@objectstack/spec/contracts';
 import { z } from 'zod';
 import { LoggerConfig } from '@objectstack/spec/system';
 import { ObjectLogger } from './logger.cjs';
@@ -1693,9 +1693,15 @@ interface GeneratedApiKey {
  */
 declare function generateApiKey(prefix?: string): GeneratedApiKey;
 /**
- * Extract an API key from request headers. Accepts `X-API-Key: <token>` or
- * `Authorization: ApiKey <token>` (case-insensitive scheme). Bearer tokens are
- * deliberately NOT treated as API keys — those flow through the session path.
+ * Extract an API key from request headers. Accepts, in order:
+ *  - `X-API-Key: <token>`
+ *  - `Authorization: ApiKey <token>` (case-insensitive scheme)
+ *  - `Authorization: Bearer <token>` ONLY when `<token>` carries the ObjectStack
+ *    api-key prefix (`osk_`). Remote MCP clients (Claude Desktop / Cursor /
+ *    Claude Code) authenticate to `/api/v1/mcp` with the key as a Bearer per the
+ *    MCP spec, so rejecting Bearer outright made every standard MCP client fail.
+ *    A better-auth *session* token never starts with `osk_`, so a session Bearer
+ *    still falls through to the session path — this can't shadow it.
  */
 declare function extractApiKey(headers: any): string | undefined;
 /** Parse a `scopes` value that may be a JSON-string textarea or a real array. */
@@ -1721,6 +1727,87 @@ interface ApiKeyPrincipal {
  */
 declare function resolveApiKeyPrincipal(ql: any, headers: any, nowMs?: number): Promise<ApiKeyPrincipal | undefined>;
 
+/** The transport-agnostic authorization envelope produced from a request. */
+interface ResolvedAuthzContext {
+    userId?: string;
+    tenantId?: string;
+    email?: string;
+    accessToken?: string;
+    roles: string[];
+    permissions: string[];
+    systemPermissions: string[];
+    tabPermissions?: Record<string, 'visible' | 'hidden' | 'default_on' | 'default_off'>;
+    /** Fellow-org user IDs for RLS scoping of identity tables (`id IN (...)`). */
+    org_user_ids: string[];
+}
+interface ResolveAuthzInput {
+    /** Data engine (ObjectQL) exposing `find(object, { where, limit, context })`. */
+    ql: any;
+    /** Inbound request headers (Web `Headers` or a plain record). */
+    headers: any;
+    /**
+     * Resolve a better-auth session from `headers`, returning `{ user?, session? }`
+     * (or undefined). Optional — when omitted or throwing, only the API-key path
+     * runs and anonymous requests resolve to an empty context.
+     */
+    getSession?: (headers: any) => Promise<any> | any;
+    /** Clock injection for API-key expiry (tests). */
+    nowMs?: number;
+}
+/**
+ * Resolve the authorization context for an inbound request. Always resolves —
+ * never throws. Anonymous requests yield `{ roles: [], permissions: [], ... }`.
+ */
+declare function resolveAuthzContext(input: ResolveAuthzInput): Promise<ResolvedAuthzContext>;
+interface ResolveLocalizationInput {
+    ql: any;
+    /** Settings service exposing `get(namespace, key, { tenantId, userId })`. */
+    settings?: any;
+    tenantId?: string;
+    userId?: string;
+}
+/**
+ * Resolve workspace localization defaults (reference `timezone` / `locale` /
+ * `currency`). Canonical path is the `localization` SettingsManifest (cascade:
+ * platform default → global → tenant); falls back to direct tenant-scoped
+ * `sys_setting` rows, then the built-ins `UTC` / `en-US`. Never throws.
+ */
+declare function resolveLocalizationContext(input: ResolveLocalizationInput): Promise<{
+    timezone: string;
+    locale: string;
+    currency?: string;
+}>;
+
+/**
+ * ADR-0069 — authentication-policy session gate.
+ *
+ * Some auth policies (password expiry, enforced MFA) must block an
+ * authenticated user from PROTECTED RESOURCES until they remediate, while
+ * still letting them reach the auth endpoints (change-password, two-factor
+ * enrollment, sign-out) and a few UI-bootstrap reads.
+ *
+ * The posture is computed ONCE, in the auth `customSession` enrichment, and
+ * attached to the session user as `user.authGate = { code, message }`. The
+ * transport seams (REST middleware, dispatcher) then call
+ * {@link evaluateAuthGate} to decide whether THIS request is blocked. Keeping
+ * the allow-list + decision in one pure function means the seams can never
+ * drift on what is blocked.
+ */
+interface AuthGate {
+    /** Stable machine code, e.g. `PASSWORD_EXPIRED` / `MFA_REQUIRED`. */
+    code: string;
+    /** Human-facing message. */
+    message: string;
+}
+/** True when `path` is exempt from the auth gate (auth + remediation + health). */
+declare function isAuthGateAllowlisted(rawPath: string | undefined | null): boolean;
+/**
+ * Returns the active gate when `sessionUser` carries an `authGate` AND `path`
+ * is not allow-listed; otherwise null. Anonymous users (no `authGate`) and
+ * allow-listed paths always pass.
+ */
+declare function evaluateAuthGate(sessionUser: any, path: string): AuthGate | null;
+
 /**
  * Environment utilities for universal (Node/Browser) compatibility.
  */
@@ -2168,4 +2255,4 @@ declare class NamespaceResolver {
     private suggestAlternative;
 }
 
-export { API_KEY_PREFIX, type ApiKeyPrincipal, ApiRegistry, type ApiRegistryPluginConfig, CORE_FALLBACK_FACTORIES, type CalendarParts, DependencyResolver, type GeneratedApiKey, HotReloadManager, type KernelState, type KeyInput, LiteKernel, type NamespaceCheckResult, type NamespaceConflict, type NamespaceEntry, NamespaceResolver, ObjectKernel, ObjectKernelBase, type ObjectKernelConfig, ObjectLogger, type ParsedSignature, type PermissionCheckResult$1 as PermissionCheckResult, type PermissionGrant, type Plugin, type PluginArtifactVerifyResult, PluginConfigValidator, type PluginContext, PluginHealthMonitor, type PluginHealthStatus, type PluginLoadResult, PluginLoader, type PluginMetadata, type PermissionCheckResult as PluginPermissionCheckResult, PluginPermissionEnforcer, PluginPermissionManager, type PluginPermissions, PluginSandboxRuntime, PluginSecurityScanner, type PluginSignatureConfig, PluginSignatureVerifier, type PluginStartupResult, type PublisherVerifyResult, index as QA, type ResourceUsage, SIGNATURE_ALG, type SandboxContext, type ScanTarget, SecurePluginContext, type SecurityIssue, SemanticVersionManager, type ServiceFactory, ServiceLifecycle, type ServiceRegistration, type SignatureVerificationResult, type VersionCompatibility, buildPermissionsFromGrants, calendarPartsInTz, calendarPartsInTzOrUtc, counterSignPayload, createApiRegistryPlugin, createMemoryCache, createMemoryI18n, createMemoryJob, createMemoryMetadata, createMemoryQueue, createPluginConfigValidator, createPluginPermissionEnforcer, extractApiKey, generateApiKey, generateEd25519KeyPair, getEnv, getMemoryUsage, hashApiKey, isExpired, isNode, parseScopes, parseSignature, resolveApiKeyPrincipal, resolveLocale, safeExit, signPayload, verifyPayload, verifyPlatformSignature, verifyPluginArtifact, verifyPublisherSignature };
+export { API_KEY_PREFIX, type ApiKeyPrincipal, ApiRegistry, type ApiRegistryPluginConfig, type AuthGate, CORE_FALLBACK_FACTORIES, type CalendarParts, DependencyResolver, type GeneratedApiKey, HotReloadManager, type KernelState, type KeyInput, LiteKernel, type NamespaceCheckResult, type NamespaceConflict, type NamespaceEntry, NamespaceResolver, ObjectKernel, ObjectKernelBase, type ObjectKernelConfig, ObjectLogger, type ParsedSignature, type PermissionCheckResult$1 as PermissionCheckResult, type PermissionGrant, type Plugin, type PluginArtifactVerifyResult, PluginConfigValidator, type PluginContext, PluginHealthMonitor, type PluginHealthStatus, type PluginLoadResult, PluginLoader, type PluginMetadata, type PermissionCheckResult as PluginPermissionCheckResult, PluginPermissionEnforcer, PluginPermissionManager, type PluginPermissions, PluginSandboxRuntime, PluginSecurityScanner, type PluginSignatureConfig, PluginSignatureVerifier, type PluginStartupResult, type PublisherVerifyResult, index as QA, type ResolveAuthzInput, type ResolveLocalizationInput, type ResolvedAuthzContext, type ResourceUsage, SIGNATURE_ALG, type SandboxContext, type ScanTarget, SecurePluginContext, type SecurityIssue, SemanticVersionManager, type ServiceFactory, ServiceLifecycle, type ServiceRegistration, type SignatureVerificationResult, type VersionCompatibility, buildPermissionsFromGrants, calendarPartsInTz, calendarPartsInTzOrUtc, counterSignPayload, createApiRegistryPlugin, createMemoryCache, createMemoryI18n, createMemoryJob, createMemoryMetadata, createMemoryQueue, createPluginConfigValidator, createPluginPermissionEnforcer, evaluateAuthGate, extractApiKey, generateApiKey, generateEd25519KeyPair, getEnv, getMemoryUsage, hashApiKey, isAuthGateAllowlisted, isExpired, isNode, parseScopes, parseSignature, resolveApiKeyPrincipal, resolveAuthzContext, resolveLocale, resolveLocalizationContext, safeExit, signPayload, verifyPayload, verifyPlatformSignature, verifyPluginArtifact, verifyPublisherSignature };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { Logger, IServiceRegistry } from '@objectstack/spec/contracts';
-export { DriverInterface, IDataDriver, IDataEngine, IHttpRequest, IHttpResponse, IHttpServer, Logger, Middleware, RouteHandler } from '@objectstack/spec/contracts';
+export { IDataDriver, IDataEngine, IHttpRequest, IHttpResponse, IHttpServer, Logger, Middleware, RouteHandler } from '@objectstack/spec/contracts';
 import { z } from 'zod';
 import { LoggerConfig } from '@objectstack/spec/system';
 import { ObjectLogger } from './logger.js';
@@ -1693,9 +1693,15 @@ interface GeneratedApiKey {
  */
 declare function generateApiKey(prefix?: string): GeneratedApiKey;
 /**
- * Extract an API key from request headers. Accepts `X-API-Key: <token>` or
- * `Authorization: ApiKey <token>` (case-insensitive scheme). Bearer tokens are
- * deliberately NOT treated as API keys — those flow through the session path.
+ * Extract an API key from request headers. Accepts, in order:
+ *  - `X-API-Key: <token>`
+ *  - `Authorization: ApiKey <token>` (case-insensitive scheme)
+ *  - `Authorization: Bearer <token>` ONLY when `<token>` carries the ObjectStack
+ *    api-key prefix (`osk_`). Remote MCP clients (Claude Desktop / Cursor /
+ *    Claude Code) authenticate to `/api/v1/mcp` with the key as a Bearer per the
+ *    MCP spec, so rejecting Bearer outright made every standard MCP client fail.
+ *    A better-auth *session* token never starts with `osk_`, so a session Bearer
+ *    still falls through to the session path — this can't shadow it.
  */
 declare function extractApiKey(headers: any): string | undefined;
 /** Parse a `scopes` value that may be a JSON-string textarea or a real array. */
@@ -1721,6 +1727,87 @@ interface ApiKeyPrincipal {
  */
 declare function resolveApiKeyPrincipal(ql: any, headers: any, nowMs?: number): Promise<ApiKeyPrincipal | undefined>;
 
+/** The transport-agnostic authorization envelope produced from a request. */
+interface ResolvedAuthzContext {
+    userId?: string;
+    tenantId?: string;
+    email?: string;
+    accessToken?: string;
+    roles: string[];
+    permissions: string[];
+    systemPermissions: string[];
+    tabPermissions?: Record<string, 'visible' | 'hidden' | 'default_on' | 'default_off'>;
+    /** Fellow-org user IDs for RLS scoping of identity tables (`id IN (...)`). */
+    org_user_ids: string[];
+}
+interface ResolveAuthzInput {
+    /** Data engine (ObjectQL) exposing `find(object, { where, limit, context })`. */
+    ql: any;
+    /** Inbound request headers (Web `Headers` or a plain record). */
+    headers: any;
+    /**
+     * Resolve a better-auth session from `headers`, returning `{ user?, session? }`
+     * (or undefined). Optional — when omitted or throwing, only the API-key path
+     * runs and anonymous requests resolve to an empty context.
+     */
+    getSession?: (headers: any) => Promise<any> | any;
+    /** Clock injection for API-key expiry (tests). */
+    nowMs?: number;
+}
+/**
+ * Resolve the authorization context for an inbound request. Always resolves —
+ * never throws. Anonymous requests yield `{ roles: [], permissions: [], ... }`.
+ */
+declare function resolveAuthzContext(input: ResolveAuthzInput): Promise<ResolvedAuthzContext>;
+interface ResolveLocalizationInput {
+    ql: any;
+    /** Settings service exposing `get(namespace, key, { tenantId, userId })`. */
+    settings?: any;
+    tenantId?: string;
+    userId?: string;
+}
+/**
+ * Resolve workspace localization defaults (reference `timezone` / `locale` /
+ * `currency`). Canonical path is the `localization` SettingsManifest (cascade:
+ * platform default → global → tenant); falls back to direct tenant-scoped
+ * `sys_setting` rows, then the built-ins `UTC` / `en-US`. Never throws.
+ */
+declare function resolveLocalizationContext(input: ResolveLocalizationInput): Promise<{
+    timezone: string;
+    locale: string;
+    currency?: string;
+}>;
+
+/**
+ * ADR-0069 — authentication-policy session gate.
+ *
+ * Some auth policies (password expiry, enforced MFA) must block an
+ * authenticated user from PROTECTED RESOURCES until they remediate, while
+ * still letting them reach the auth endpoints (change-password, two-factor
+ * enrollment, sign-out) and a few UI-bootstrap reads.
+ *
+ * The posture is computed ONCE, in the auth `customSession` enrichment, and
+ * attached to the session user as `user.authGate = { code, message }`. The
+ * transport seams (REST middleware, dispatcher) then call
+ * {@link evaluateAuthGate} to decide whether THIS request is blocked. Keeping
+ * the allow-list + decision in one pure function means the seams can never
+ * drift on what is blocked.
+ */
+interface AuthGate {
+    /** Stable machine code, e.g. `PASSWORD_EXPIRED` / `MFA_REQUIRED`. */
+    code: string;
+    /** Human-facing message. */
+    message: string;
+}
+/** True when `path` is exempt from the auth gate (auth + remediation + health). */
+declare function isAuthGateAllowlisted(rawPath: string | undefined | null): boolean;
+/**
+ * Returns the active gate when `sessionUser` carries an `authGate` AND `path`
+ * is not allow-listed; otherwise null. Anonymous users (no `authGate`) and
+ * allow-listed paths always pass.
+ */
+declare function evaluateAuthGate(sessionUser: any, path: string): AuthGate | null;
+
 /**
  * Environment utilities for universal (Node/Browser) compatibility.
  */
@@ -2168,4 +2255,4 @@ declare class NamespaceResolver {
     private suggestAlternative;
 }
 
-export { API_KEY_PREFIX, type ApiKeyPrincipal, ApiRegistry, type ApiRegistryPluginConfig, CORE_FALLBACK_FACTORIES, type CalendarParts, DependencyResolver, type GeneratedApiKey, HotReloadManager, type KernelState, type KeyInput, LiteKernel, type NamespaceCheckResult, type NamespaceConflict, type NamespaceEntry, NamespaceResolver, ObjectKernel, ObjectKernelBase, type ObjectKernelConfig, ObjectLogger, type ParsedSignature, type PermissionCheckResult$1 as PermissionCheckResult, type PermissionGrant, type Plugin, type PluginArtifactVerifyResult, PluginConfigValidator, type PluginContext, PluginHealthMonitor, type PluginHealthStatus, type PluginLoadResult, PluginLoader, type PluginMetadata, type PermissionCheckResult as PluginPermissionCheckResult, PluginPermissionEnforcer, PluginPermissionManager, type PluginPermissions, PluginSandboxRuntime, PluginSecurityScanner, type PluginSignatureConfig, PluginSignatureVerifier, type PluginStartupResult, type PublisherVerifyResult, index as QA, type ResourceUsage, SIGNATURE_ALG, type SandboxContext, type ScanTarget, SecurePluginContext, type SecurityIssue, SemanticVersionManager, type ServiceFactory, ServiceLifecycle, type ServiceRegistration, type SignatureVerificationResult, type VersionCompatibility, buildPermissionsFromGrants, calendarPartsInTz, calendarPartsInTzOrUtc, counterSignPayload, createApiRegistryPlugin, createMemoryCache, createMemoryI18n, createMemoryJob, createMemoryMetadata, createMemoryQueue, createPluginConfigValidator, createPluginPermissionEnforcer, extractApiKey, generateApiKey, generateEd25519KeyPair, getEnv, getMemoryUsage, hashApiKey, isExpired, isNode, parseScopes, parseSignature, resolveApiKeyPrincipal, resolveLocale, safeExit, signPayload, verifyPayload, verifyPlatformSignature, verifyPluginArtifact, verifyPublisherSignature };
+export { API_KEY_PREFIX, type ApiKeyPrincipal, ApiRegistry, type ApiRegistryPluginConfig, type AuthGate, CORE_FALLBACK_FACTORIES, type CalendarParts, DependencyResolver, type GeneratedApiKey, HotReloadManager, type KernelState, type KeyInput, LiteKernel, type NamespaceCheckResult, type NamespaceConflict, type NamespaceEntry, NamespaceResolver, ObjectKernel, ObjectKernelBase, type ObjectKernelConfig, ObjectLogger, type ParsedSignature, type PermissionCheckResult$1 as PermissionCheckResult, type PermissionGrant, type Plugin, type PluginArtifactVerifyResult, PluginConfigValidator, type PluginContext, PluginHealthMonitor, type PluginHealthStatus, type PluginLoadResult, PluginLoader, type PluginMetadata, type PermissionCheckResult as PluginPermissionCheckResult, PluginPermissionEnforcer, PluginPermissionManager, type PluginPermissions, PluginSandboxRuntime, PluginSecurityScanner, type PluginSignatureConfig, PluginSignatureVerifier, type PluginStartupResult, type PublisherVerifyResult, index as QA, type ResolveAuthzInput, type ResolveLocalizationInput, type ResolvedAuthzContext, type ResourceUsage, SIGNATURE_ALG, type SandboxContext, type ScanTarget, SecurePluginContext, type SecurityIssue, SemanticVersionManager, type ServiceFactory, ServiceLifecycle, type ServiceRegistration, type SignatureVerificationResult, type VersionCompatibility, buildPermissionsFromGrants, calendarPartsInTz, calendarPartsInTzOrUtc, counterSignPayload, createApiRegistryPlugin, createMemoryCache, createMemoryI18n, createMemoryJob, createMemoryMetadata, createMemoryQueue, createPluginConfigValidator, createPluginPermissionEnforcer, evaluateAuthGate, extractApiKey, generateApiKey, generateEd25519KeyPair, getEnv, getMemoryUsage, hashApiKey, isAuthGateAllowlisted, isExpired, isNode, parseScopes, parseSignature, resolveApiKeyPrincipal, resolveAuthzContext, resolveLocale, resolveLocalizationContext, safeExit, signPayload, verifyPayload, verifyPlatformSignature, verifyPluginArtifact, verifyPublisherSignature };

package/dist/index.js

@@ -3919,9 +3919,11 @@ function extractApiKey(headers) {
   if (x && x.trim()) return x.trim();
   const auth = readHeader(headers, "authorization");
   if (!auth) return void 0;
-  const m = auth.match(/^ApiKey\s+(.+)$/i);
-  const token = m?.[1]?.trim();
-  return token || void 0;
+  const apiKeyScheme = auth.match(/^ApiKey\s+(\S.*)$/i);
+  if (apiKeyScheme?.[1]?.trim()) return apiKeyScheme[1].trim();
+  const bearer = auth.match(/^Bearer\s+(\S.*)$/i)?.[1]?.trim();
+  if (bearer && bearer.startsWith(API_KEY_PREFIX)) return bearer;
+  return void 0;
 }
 function parseScopes(value) {
   if (Array.isArray(value)) {
@@ -4000,6 +4002,238 @@ function safeJsonParse(s, fallback) {
   }
 }
 
+// src/security/resolve-authz-context.ts
+import {
+  mapMembershipRole,
+  BUILTIN_ROLE_PLATFORM_ADMIN,
+  ADMIN_FULL_ACCESS
+} from "@objectstack/spec";
+function safeJsonParse2(s, fallback) {
+  try {
+    return JSON.parse(s);
+  } catch {
+    return fallback;
+  }
+}
+async function tryFind(ql, object, where, limit = 100) {
+  if (!ql || typeof ql.find !== "function") return [];
+  try {
+    let rows = await ql.find(object, { where, limit, context: { isSystem: true } });
+    if (rows && rows.value) rows = rows.value;
+    return Array.isArray(rows) ? rows : [];
+  } catch {
+    return [];
+  }
+}
+async function resolveAuthzContext(input) {
+  const { ql, headers } = input;
+  const ctx = {
+    roles: [],
+    permissions: [],
+    systemPermissions: [],
+    org_user_ids: []
+  };
+  let userId;
+  let tenantId;
+  const keyPrincipal = await resolveApiKeyPrincipal(ql, headers, input.nowMs);
+  if (keyPrincipal) {
+    userId = keyPrincipal.userId;
+    tenantId = keyPrincipal.tenantId;
+    for (const scope of keyPrincipal.scopes) {
+      if (!ctx.permissions.includes(scope)) ctx.permissions.push(scope);
+    }
+  }
+  if (!userId && typeof input.getSession === "function") {
+    try {
+      const sessionData = await input.getSession(headers);
+      userId = sessionData?.user?.id ?? sessionData?.session?.userId;
+      tenantId = tenantId ?? sessionData?.session?.activeOrganizationId;
+      ctx.accessToken = sessionData?.session?.token ?? ctx.accessToken;
+      if (sessionData?.user?.email) ctx.email = String(sessionData.user.email);
+    } catch {
+    }
+  }
+  if (!userId) return ctx;
+  ctx.userId = userId;
+  if (tenantId) ctx.tenantId = tenantId;
+  if (!ql || typeof ql.find !== "function") return ctx;
+  let userRowLoaded = false;
+  let userRow;
+  const getUserRow = async () => {
+    if (!userRowLoaded) {
+      userRowLoaded = true;
+      const rows = await tryFind(ql, "sys_user", { id: userId }, 1);
+      userRow = rows[0];
+    }
+    return userRow;
+  };
+  if (!ctx.email) {
+    const u = await getUserRow();
+    if (u?.email) ctx.email = String(u.email);
+  }
+  const memberWhere = tenantId ? { user_id: userId, organization_id: tenantId } : { user_id: userId };
+  const members = await tryFind(ql, "sys_member", memberWhere, 50);
+  for (const m of members) {
+    if (m.role && typeof m.role === "string") {
+      for (const raw of m.role.split(",").map((s) => s.trim()).filter(Boolean)) {
+        const r = mapMembershipRole(raw);
+        if (!ctx.roles.includes(r)) ctx.roles.push(r);
+      }
+    }
+  }
+  const userRoleRows = await tryFind(ql, "sys_user_role", { user_id: userId }, 200);
+  for (const ur of userRoleRows) {
+    const org = ur.organization_id ?? null;
+    if (org && tenantId && org !== tenantId) continue;
+    const r = ur.role;
+    if (typeof r === "string" && r && !ctx.roles.includes(r)) ctx.roles.push(r);
+  }
+  if (tenantId) {
+    const orgMembers = await tryFind(ql, "sys_member", { organization_id: tenantId }, 1e3);
+    const ids = new Set(
+      orgMembers.map((m) => m.user_id ?? m.userId).filter((v) => typeof v === "string" && v.length > 0)
+    );
+    ids.add(userId);
+    ctx.org_user_ids = Array.from(ids);
+  } else {
+    ctx.org_user_ids = [userId];
+  }
+  const upsRows = await tryFind(ql, "sys_user_permission_set", { user_id: userId }, 100);
+  const psIds = new Set(
+    upsRows.filter((r) => {
+      const org = r.organization_id ?? r.organizationId ?? null;
+      return !(org && tenantId && org !== tenantId);
+    }).map((r) => r.permission_set_id ?? r.permissionSetId).filter(Boolean)
+  );
+  const unscopedUserPsIds = new Set(
+    upsRows.filter((r) => (r.organization_id ?? r.organizationId ?? null) === null).map((r) => r.permission_set_id ?? r.permissionSetId).filter(Boolean)
+  );
+  let hasPlatformAdminGrant = false;
+  if (ctx.roles.length > 0) {
+    const roleRows = await tryFind(ql, "sys_role", { name: { $in: ctx.roles } }, 100);
+    const roleIds = roleRows.map((r) => r.id).filter(Boolean);
+    if (roleIds.length > 0) {
+      const rpsRows = await tryFind(ql, "sys_role_permission_set", { role_id: { $in: roleIds } }, 500);
+      for (const r of rpsRows) {
+        const id = r.permission_set_id ?? r.permissionSetId;
+        if (id) psIds.add(id);
+      }
+    }
+  }
+  if (psIds.size > 0) {
+    const psRows = await tryFind(ql, "sys_permission_set", { id: { $in: Array.from(psIds) } }, 500);
+    const tabRank = { hidden: 0, default_off: 1, default_on: 2, visible: 3 };
+    const mergedTabs = {};
+    for (const ps of psRows) {
+      if (ps.name && !ctx.permissions.includes(ps.name)) ctx.permissions.push(ps.name);
+      if (ps.name === ADMIN_FULL_ACCESS && unscopedUserPsIds.has(ps.id)) hasPlatformAdminGrant = true;
+      const sysPerms = typeof ps.system_permissions === "string" ? safeJsonParse2(ps.system_permissions, []) : ps.system_permissions ?? ps.systemPermissions;
+      if (Array.isArray(sysPerms)) {
+        for (const p of sysPerms) {
+          if (typeof p === "string" && !ctx.systemPermissions.includes(p)) ctx.systemPermissions.push(p);
+        }
+      }
+      const tabs = typeof ps.tab_permissions === "string" ? safeJsonParse2(ps.tab_permissions, {}) : ps.tab_permissions ?? ps.tabPermissions;
+      if (tabs && typeof tabs === "object") {
+        for (const [app, val] of Object.entries(tabs)) {
+          if (typeof val !== "string" || !(val in tabRank)) continue;
+          const cur = mergedTabs[app];
+          if (!cur || tabRank[val] > tabRank[cur]) {
+            mergedTabs[app] = val;
+          }
+        }
+      }
+    }
+    if (Object.keys(mergedTabs).length > 0) ctx.tabPermissions = mergedTabs;
+  }
+  if (hasPlatformAdminGrant && !ctx.roles.includes(BUILTIN_ROLE_PLATFORM_ADMIN)) {
+    ctx.roles.unshift(BUILTIN_ROLE_PLATFORM_ADMIN);
+  }
+  if (!ctx.permissions.includes("ai_seat")) {
+    const aiAccess = (await getUserRow())?.ai_access;
+    if (aiAccess === true || aiAccess === 1 || aiAccess === "1") ctx.permissions.push("ai_seat");
+  }
+  return ctx;
+}
+function isValidTimeZone(tz) {
+  try {
+    new Intl.DateTimeFormat("en-US", { timeZone: tz });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function coerceTimeZone(value) {
+  const s = typeof value === "string" ? value.trim() : value != null ? String(value).trim() : "";
+  return s && isValidTimeZone(s) ? s : void 0;
+}
+function coerceLocale(value) {
+  const s = typeof value === "string" ? value.trim() : value != null ? String(value).trim() : "";
+  return s || void 0;
+}
+function coerceCurrency(value) {
+  const s = typeof value === "string" ? value.trim().toUpperCase() : "";
+  return /^[A-Z]{3}$/.test(s) ? s : void 0;
+}
+async function resolveLocalizationContext(input) {
+  const { ql, settings, tenantId, userId } = input;
+  try {
+    if (settings && typeof settings.get === "function") {
+      const sctx = { tenantId, userId };
+      const [tzRes, localeRes, currencyRes] = await Promise.all([
+        settings.get("localization", "timezone", sctx).catch(() => void 0),
+        settings.get("localization", "locale", sctx).catch(() => void 0),
+        settings.get("localization", "currency", sctx).catch(() => void 0)
+      ]);
+      const tz = coerceTimeZone(tzRes?.value);
+      const locale = coerceLocale(localeRes?.value);
+      const currency = coerceCurrency(currencyRes?.value);
+      if (tz || locale || currency) return { timezone: tz ?? "UTC", locale: locale ?? "en-US", currency };
+    }
+  } catch {
+  }
+  const rows = await tryFind(
+    ql,
+    "sys_setting",
+    { namespace: "localization", key: { $in: ["timezone", "locale", "currency"] }, scope: "tenant" },
+    10
+  );
+  const valueOf = (k) => rows.find((r) => r.key === k)?.value;
+  return {
+    timezone: coerceTimeZone(valueOf("timezone")) ?? "UTC",
+    locale: coerceLocale(valueOf("locale")) ?? "en-US",
+    currency: coerceCurrency(valueOf("currency"))
+  };
+}
+
+// src/security/auth-gate.ts
+var ALLOW_PREFIXES = ["/api/v1/auth/", "/api/auth/", "/auth/"];
+var ALLOW_SUFFIXES = ["/health", "/ready", "/discovery", "/me/apps", "/me/localization"];
+function isAuthGateAllowlisted(rawPath) {
+  if (!rawPath) return true;
+  let path = rawPath.split("?")[0] || "/";
+  let end = path.length;
+  while (end > 1 && path.charCodeAt(end - 1) === 47) end--;
+  path = path.slice(0, end) || "/";
+  if (path.includes("/auth/")) return true;
+  for (const p of ALLOW_PREFIXES) {
+    if (path.startsWith(p) || path === p.replace(/\/$/, "")) return true;
+  }
+  for (const s of ALLOW_SUFFIXES) {
+    if (path.endsWith(s)) return true;
+  }
+  return false;
+}
+function evaluateAuthGate(sessionUser, path) {
+  const gate = sessionUser?.authGate;
+  if (!gate || typeof gate.code !== "string") return null;
+  if (isAuthGateAllowlisted(path)) return null;
+  return {
+    code: gate.code,
+    message: typeof gate.message === "string" && gate.message ? gate.message : "Access is blocked by an authentication policy."
+  };
+}
+
 // src/utils/datetime.ts
 function calendarPartsInTz(d, tz) {
   const parts = new Intl.DateTimeFormat("en-US", {
@@ -4975,18 +5209,22 @@ export {
   createMemoryQueue,
   createPluginConfigValidator,
   createPluginPermissionEnforcer,
+  evaluateAuthGate,
   extractApiKey,
   generateApiKey,
   generateEd25519KeyPair,
   getEnv,
   getMemoryUsage,
   hashApiKey,
+  isAuthGateAllowlisted,
   isExpired,
   isNode,
   parseScopes,
   parseSignature,
   resolveApiKeyPrincipal,
+  resolveAuthzContext,
   resolveLocale,
+  resolveLocalizationContext,
   safeExit,
   signPayload,
   verifyPayload,