@jskit-ai/workspaces-core 0.1.138-oldline.1 → 0.1.139

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@jskit-ai/workspaces-core",
-  "version": "0.1.138-oldline.1",
+  "version": "0.1.139",
   "type": "module",
   "scripts": {
     "test": "node --test"
   },
   "exports": {
-    "./server/WorkspacesCoreServiceProvider": "./src/server/WorkspacesCoreServiceProvider.js",
+    "./server/WorkspacesFeature": "./src/server/WorkspacesFeature.js",
+    "./server/WorkspacesIntegrationsProvider": "./src/server/WorkspacesIntegrationsProvider.js",
     "./server/validators/routeParamsValidator": "./src/server/common/validators/routeParamsValidator.js",
     "./server/support/workspaceRouteInput": "./src/server/support/workspaceRouteInput.js",
     "./shared/jsonApiTransports": "./src/shared/jsonApiTransports.js",
@@ -17,14 +18,157 @@
     "./shared/resources/workspaceSettingsResource": "./src/shared/resources/workspaceSettingsResource.js"
   },
   "dependencies": {
-    "@jskit-ai/auth-core": "0.1.146",
-    "@jskit-ai/database-runtime": "0.1.147",
-    "@jskit-ai/http-runtime": "0.1.146",
-    "@jskit-ai/json-rest-api-core": "0.1.92",
-    "@jskit-ai/kernel": "0.1.147",
-    "@jskit-ai/resource-crud-core": "0.1.90",
-    "@jskit-ai/resource-core": "0.1.90",
-    "@jskit-ai/users-core": "0.1.161",
+    "@jskit-ai/auth-core": "0.1.159",
+    "@jskit-ai/database-runtime": "0.1.161",
+    "@jskit-ai/http-runtime": "0.1.159",
+    "@jskit-ai/json-rest-api-core": "0.1.105",
+    "@jskit-ai/kernel": "0.1.161",
+    "@jskit-ai/resource-core": "0.1.103",
+    "@jskit-ai/resource-crud-core": "0.1.103",
+    "@jskit-ai/users-core": "0.1.174",
     "json-rest-schema": "^1.0.17"
+  },
+  "description": "Workspace tenancy runtime plus HTTP routes, role catalog, and workspace config scaffolding.",
+  "jskit": {
+    "kind": "runtime",
+    "capabilities": {
+      "provides": [
+        "workspaces.core"
+      ],
+      "requires": [
+        "auth.extensions",
+        "runtime.actions",
+        "runtime.bootstrap",
+        "runtime.config",
+        "runtime.database",
+        "runtime.env",
+        "runtime.http",
+        "runtime.json-rest-api",
+        "users.core",
+        "users.extensions"
+      ]
+    },
+    "runtime": {
+      "server": {
+        "providers": [
+          {
+            "entrypoint": "src/server/WorkspacesFeature.js",
+            "export": "WorkspacesFeature"
+          },
+          {
+            "entrypoint": "src/server/WorkspacesIntegrationsProvider.js",
+            "export": "WorkspacesIntegrationsProvider"
+          }
+        ]
+      },
+      "client": {
+        "providers": []
+      }
+    },
+    "metadata": {
+      "jskit": {
+        "tableOwnership": {
+          "tables": [
+            {
+              "tableName": "workspaces"
+            },
+            {
+              "tableName": "workspace_memberships"
+            },
+            {
+              "tableName": "workspace_settings"
+            },
+            {
+              "tableName": "workspace_invites"
+            }
+          ]
+        }
+      },
+      "apiSummary": {
+        "surfaces": [
+          {
+            "subpath": "./server",
+            "summary": "Exports the explicit workspace feature, integrations, services, repositories, actions, and routes."
+          }
+        ],
+        "capabilities": [
+          "workspaces.core"
+        ]
+      },
+      "server": {
+        "routes": [
+          {
+            "method": "POST",
+            "path": "/api/workspaces",
+            "summary": "Create a workspace for the authenticated user."
+          },
+          {
+            "method": "GET",
+            "path": "/api/workspaces",
+            "summary": "List workspaces visible to authenticated user."
+          },
+          {
+            "method": "GET",
+            "path": "/api/workspace/invitations/resolve",
+            "summary": "Resolve safe public workspace invitation metadata."
+          },
+          {
+            "method": "GET",
+            "path": "/api/workspace/invitations/pending",
+            "summary": "List pending workspace invitations for authenticated user."
+          },
+          {
+            "method": "POST",
+            "path": "/api/workspace/invitations/redeem",
+            "summary": "Accept or refuse a workspace invitation using an invite token."
+          },
+          {
+            "method": "GET",
+            "path": "/api/w/:workspaceSlug/settings",
+            "summary": "Get workspace settings and role catalog by workspace slug."
+          },
+          {
+            "method": "PATCH",
+            "path": "/api/w/:workspaceSlug/settings",
+            "summary": "Update workspace settings by workspace slug."
+          },
+          {
+            "method": "GET",
+            "path": "/api/w/:workspaceSlug/roles",
+            "summary": "Get role catalog by workspace slug."
+          },
+          {
+            "method": "GET",
+            "path": "/api/w/:workspaceSlug/members",
+            "summary": "List members by workspace slug."
+          },
+          {
+            "method": "PATCH",
+            "path": "/api/w/:workspaceSlug/members/:memberUserId/role",
+            "summary": "Update workspace member role by workspace slug."
+          },
+          {
+            "method": "GET",
+            "path": "/api/w/:workspaceSlug/invites",
+            "summary": "List workspace invites by workspace slug."
+          },
+          {
+            "method": "POST",
+            "path": "/api/w/:workspaceSlug/invites",
+            "summary": "Create workspace invite by workspace slug."
+          },
+          {
+            "method": "DELETE",
+            "path": "/api/w/:workspaceSlug/invites/:inviteId",
+            "summary": "Revoke workspace invite by workspace slug."
+          }
+        ]
+      }
+    },
+    "migrations": {
+      "directories": [
+        "migrations"
+      ]
+    }
   }
 }

package/patterns/workspace-server/PATTERN.md

@@ -0,0 +1,60 @@
+---
+id: workspaces/workspace-server
+title: Workspace tenancy server composition
+summary: Configure roles, workspace access policy, invitations, and app-owned invitation email rendering around JSKIT workspace runtime APIs.
+keywords: access, invite, membership, multitenancy, policy, role, tenancy, workspace
+requires: @jskit-ai/workspaces-core, @jskit-ai/users-core
+---
+
+# Workspace tenancy server composition
+
+## Use when
+
+Use this pattern when records, routes, or navigation belong to a selected
+workspace and membership or role affects access.
+
+## Do not use when
+
+Do not use workspace tenancy for a genuinely single-owner product or as a
+substitute for a simpler domain ownership column.
+
+## Product decisions
+
+Choose workspace creation policy, roles, invitation policy, expiry, email copy,
+member permissions, personal-workspace behavior, and surface access rules.
+
+## Framework APIs
+
+Use workspace routes, resources, scope helpers, tenancy profiles, and settings
+contracts exported by `@jskit-ai/workspaces-core`.
+
+## Invariants
+
+- Workspace membership and role are checked before scoped application actions.
+- Role ids are stable product vocabulary shared by server and client config.
+- Invitation tokens remain secret; emails receive only the intended link.
+- Workspace scope reaches repository queries, not just route parsing.
+- Package-owned migrations run directly from the installed package graph.
+
+## Example files
+
+`example/config/roles.js` is a concrete role catalogue.
+`example/packages/main/src/server/email/workspaceInviteEmail.js` demonstrates an
+app-owned invitation renderer. Compose both through normal application config.
+
+## Variation points
+
+Change roles, invitation policy and copy, defaults, access policies, surface
+ids, and product-specific workspace settings.
+
+## Verification
+
+Test create/list/select, member and non-member access, each role boundary,
+invitation expiry/redemption, cross-workspace isolation, and email output.
+
+## Avoid
+
+- synthetic membership workarounds
+- authorizing from client navigation state
+- embedding invitation templates or secrets in package metadata
+- source-appending install commands

package/src/server/WorkspacesFeature.js

@@ -0,0 +1,226 @@
+import { toDatabaseDateTimeUtc } from "@jskit-ai/database-runtime/shared";
+import {
+  addResourceIfMissing,
+  createJsonRestResourceScopeOptions
+} from "@jskit-ai/json-rest-api-core/server/jsonRestApiHost";
+import { defineFeature } from "@jskit-ai/kernel/server/features";
+import { workspaceInvitesResource } from "../shared/resources/workspaceInvitesResource.js";
+import { workspaceMembershipsResource } from "../shared/resources/workspaceMembershipsResource.js";
+import { workspaceResource } from "../shared/resources/workspaceResource.js";
+import { workspaceSettingsResource } from "../shared/resources/workspaceSettingsResource.js";
+import { createWorkspaceRoleCatalog } from "../shared/roles.js";
+import { resolveTenancyProfile } from "../shared/tenancyProfile.js";
+import { createRepository as createWorkspaceInvitesRepository } from "./common/repositories/workspaceInvitesRepository.js";
+import { createRepository as createWorkspaceMembershipsRepository } from "./common/repositories/workspaceMembershipsRepository.js";
+import { createRepository as createWorkspacesRepository } from "./common/repositories/workspacesRepository.js";
+import { createService as createWorkspaceService } from "./common/services/workspaceContextService.js";
+import { createWorkspaceBootstrapContributor } from "./workspaceBootstrapContributor.js";
+import { registerWorkspaceDirectoryRoutes } from "./workspaceDirectory/bootWorkspaceDirectoryRoutes.js";
+import { buildWorkspaceDirectoryActions } from "./workspaceDirectory/workspaceDirectoryActions.js";
+import { renderDefaultWorkspaceInviteEmail } from "./workspaceMembers/defaultWorkspaceInviteEmail.js";
+import { registerWorkspaceMembersRoutes } from "./workspaceMembers/bootWorkspaceMembers.js";
+import { buildWorkspaceMembersActions } from "./workspaceMembers/workspaceMembersActions.js";
+import { createWorkspaceInviteUrlBuilder } from "./workspaceMembers/workspaceInviteUrls.js";
+import { createService as createWorkspaceMembersService } from "./workspaceMembers/workspaceMembersService.js";
+import { registerWorkspacePendingInvitationsRoutes } from "./workspacePendingInvitations/bootWorkspacePendingInvitations.js";
+import { buildWorkspacePendingInvitationsActions } from "./workspacePendingInvitations/workspacePendingInvitationsActions.js";
+import { createService as createWorkspacePendingInvitationsService } from "./workspacePendingInvitations/workspacePendingInvitationsService.js";
+import { registerWorkspaceSettingsRoutes } from "./workspaceSettings/bootWorkspaceSettings.js";
+import { createRepository as createWorkspaceSettingsRepository } from "./workspaceSettings/workspaceSettingsRepository.js";
+import { buildWorkspaceSettingsActions } from "./workspaceSettings/workspaceSettingsActions.js";
+import { createService as createWorkspaceSettingsService } from "./workspaceSettings/workspaceSettingsService.js";
+import { resolveWorkspaceInvitationsPolicy } from "./support/workspaceInvitationsPolicy.js";
+import { workspaceSlugParamsValidator } from "./common/validators/routeParamsValidator.js";
+import { buildWorkspaceInputFromRouteParams } from "./support/workspaceRouteInput.js";
+import { resolveWorkspace } from "./support/resolveWorkspace.js";
+
+function requirePositiveInteger(value, label) {
+  const normalized = Number(value);
+  if (!Number.isInteger(normalized) || normalized < 1) {
+    throw new TypeError(`${label} must be a positive integer.`);
+  }
+  return normalized;
+}
+
+function requireBoolean(value, label) {
+  if (typeof value !== "boolean") {
+    throw new TypeError(`${label} must be boolean.`);
+  }
+  return value;
+}
+
+function resolveInviteEmailTemplate(config) {
+  const template =
+    config.workspaceInviteEmailTemplate ||
+    config.workspaceInviteEmailRenderer ||
+    config.workspaceInvitations?.emailTemplate ||
+    config.workspaceInvitations?.emailRenderer;
+  return typeof template === "function" ? template : renderDefaultWorkspaceInviteEmail;
+}
+
+async function installWorkspaceResources(jsonRestApi) {
+  const scopeOptions = { writeSerializers: { "datetime-utc": toDatabaseDateTimeUtc } };
+  await addResourceIfMissing(
+    jsonRestApi,
+    "workspaces",
+    createJsonRestResourceScopeOptions(workspaceResource, scopeOptions)
+  );
+  await addResourceIfMissing(
+    jsonRestApi,
+    "workspaceMemberships",
+    createJsonRestResourceScopeOptions(workspaceMembershipsResource, scopeOptions)
+  );
+  await addResourceIfMissing(
+    jsonRestApi,
+    "workspaceInvites",
+    createJsonRestResourceScopeOptions(workspaceInvitesResource, scopeOptions)
+  );
+  await addResourceIfMissing(
+    jsonRestApi,
+    "workspaceSettings",
+    createJsonRestResourceScopeOptions(workspaceSettingsResource, scopeOptions)
+  );
+}
+
+function createWorkspacesRuntime({ config, database, env, jsonRestApi } = {}) {
+  const tenancyProfile = resolveTenancyProfile(config);
+  const invitationsPolicy = resolveWorkspaceInvitationsPolicy({ config, appConfig: config, tenancyProfile });
+  const invitationsEnabled = invitationsPolicy.enabled === true;
+  const roleCatalog = createWorkspaceRoleCatalog(config);
+  const workspaceSettingsRepository = createWorkspaceSettingsRepository({
+    api: jsonRestApi,
+    knex: database.knex,
+    defaultInvitesEnabled: requireBoolean(
+      config?.workspaceSettings?.defaults?.invitesEnabled,
+      "runtime.config.workspaceSettings.defaults.invitesEnabled"
+    )
+  });
+  const workspacesRepository = createWorkspacesRepository({ api: jsonRestApi, knex: database.knex });
+  const workspaceMembershipsRepository = createWorkspaceMembershipsRepository({
+    api: jsonRestApi,
+    knex: database.knex
+  });
+  const workspaceInvitesRepository = createWorkspaceInvitesRepository({
+    api: jsonRestApi,
+    knex: database.knex
+  });
+  const workspaceService = createWorkspaceService({
+    appConfig: config,
+    workspacesRepository,
+    workspaceMembershipsRepository,
+    workspaceSettingsRepository
+  });
+  const workspacePendingInvitationsService = createWorkspacePendingInvitationsService({
+    workspaceInvitesRepository,
+    workspaceMembershipsRepository
+  });
+  const workspaceMembersService = createWorkspaceMembersService({
+    workspaceMembershipsRepository,
+    workspaceInvitesRepository,
+    inviteExpiresInMs: requirePositiveInteger(
+      config?.workspaceMembers?.defaults?.inviteExpiresInMs,
+      "runtime.config.workspaceMembers.defaults.inviteExpiresInMs"
+    ),
+    roleCatalog,
+    workspaceInvitationsEnabled: invitationsEnabled,
+    inviteUrlBuilder: createWorkspaceInviteUrlBuilder({ appConfig: config, env }),
+    workspaceInviteMailer: config?.workspaceInviteMailer || null,
+    workspaceInviteEmailTemplate: resolveInviteEmailTemplate(config)
+  });
+  const workspaceSettingsService = createWorkspaceSettingsService({
+    workspaceSettingsRepository,
+    workspaceInvitationsEnabled: invitationsEnabled,
+    roleCatalog
+  });
+
+  return Object.freeze({
+    config,
+    enabled: tenancyProfile.workspace.enabled === true,
+    invitationsEnabled,
+    selfCreateEnabled: tenancyProfile.workspace.allowSelfCreate === true,
+    scope: Object.freeze({
+      params: workspaceSlugParamsValidator,
+      buildInputFromRouteParams: buildWorkspaceInputFromRouteParams,
+      resolveWorkspace
+    }),
+    tenancyProfile,
+    repositories: Object.freeze({
+      workspaceInvites: workspaceInvitesRepository,
+      workspaceMemberships: workspaceMembershipsRepository,
+      workspaceSettings: workspaceSettingsRepository,
+      workspaces: workspacesRepository
+    }),
+    services: Object.freeze({
+      directory: workspaceService,
+      members: workspaceMembersService,
+      pendingInvitations: workspacePendingInvitationsService,
+      settings: workspaceSettingsService
+    })
+  });
+}
+
+const WorkspacesFeature = defineFeature({
+  id: "workspaces.core",
+  domain: "workspace",
+  requires: {
+    bootstrap: "runtime.bootstrap",
+    config: "runtime.config",
+    database: "runtime.database",
+    env: "runtime.env",
+    http: "runtime.http",
+    jsonRestApi: "runtime.json-rest-api",
+    users: "users.core"
+  },
+  provides: {
+    workspaces: "workspaces.core"
+  },
+  async setup({ bootstrap, config, database, env, http, jsonRestApi, users }) {
+    await installWorkspaceResources(jsonRestApi);
+    const workspaces = createWorkspacesRuntime({ config, database, env, jsonRestApi });
+
+    bootstrap.register({
+      id: "workspaces.bootstrap",
+      order: 200,
+      contribute: createWorkspaceBootstrapContributor({
+        appConfig: config,
+        tenancyProfile: workspaces.tenancyProfile,
+        userProfilesRepository: users.repositories.userProfiles,
+        workspaceInvitationsEnabled: workspaces.invitationsEnabled,
+        workspacePendingInvitationsService: workspaces.services.pendingInvitations,
+        workspaceService: workspaces.services.directory
+      }).contribute
+    });
+
+    if (workspaces.enabled) {
+      registerWorkspaceDirectoryRoutes(http.router, {
+        config,
+        workspaceSelfCreateEnabled: workspaces.selfCreateEnabled
+      });
+      registerWorkspaceSettingsRoutes(http.router, { config });
+      registerWorkspaceMembersRoutes(http.router, {
+        config,
+        workspaceInvitationsEnabled: workspaces.invitationsEnabled
+      });
+      if (workspaces.invitationsEnabled) {
+        registerWorkspacePendingInvitationsRoutes(http.router);
+      }
+    }
+
+    return { workspaces };
+  },
+  actions({ workspaces }) {
+    if (!workspaces.enabled) return [];
+    return [
+      ...buildWorkspaceDirectoryActions({ workspaceService: workspaces.services.directory }),
+      ...buildWorkspaceSettingsActions({ workspaceSettingsService: workspaces.services.settings }),
+      ...buildWorkspaceMembersActions({ workspaceMembersService: workspaces.services.members }),
+      ...(workspaces.invitationsEnabled
+        ? buildWorkspacePendingInvitationsActions({
+            workspacePendingInvitationsService: workspaces.services.pendingInvitations
+          })
+        : [])
+    ];
+  }
+});
+
+export { WorkspacesFeature, createWorkspacesRuntime, installWorkspaceResources };

package/src/server/WorkspacesIntegrationsProvider.js

@@ -0,0 +1,74 @@
+import { defineProvider } from "@jskit-ai/kernel/shared/capabilities";
+import { createWorkspaceActionContextContributor } from "./common/contributors/workspaceActionContextContributor.js";
+import { createWorkspaceAuthPolicyContextResolver } from "./common/contributors/workspaceAuthPolicyContextResolver.js";
+import { createWorkspaceRouteVisibilityResolver } from "./common/contributors/workspaceRouteVisibilityResolver.js";
+import {
+  resolveWorkspaceMembershipOptionalSurfaceIdsFromAppConfig,
+  resolveWorkspaceSurfaceIdsFromAppConfig
+} from "./support/workspaceActionSurfaces.js";
+
+const WorkspacesIntegrationsProvider = defineProvider({
+  id: "workspaces.integrations",
+  requires: {
+    actions: "runtime.actions",
+    authExtensions: "auth.extensions",
+    config: "runtime.config",
+    http: "runtime.http",
+    usersExtensions: "users.extensions",
+    workspaces: "workspaces.core"
+  },
+  setup({ actions, authExtensions, config, http, usersExtensions, workspaces }) {
+    const workspaceService = workspaces.services.directory;
+    const membershipOptionalSurfaceIds = resolveWorkspaceMembershipOptionalSurfaceIdsFromAppConfig(config);
+    const workspaceSurfaceIds = resolveWorkspaceSurfaceIdsFromAppConfig(config);
+
+    const actionContext = createWorkspaceActionContextContributor({
+      workspaceMembershipOptionalSurfaceIds: membershipOptionalSurfaceIds,
+      workspaceService,
+      workspaceSurfaceIds
+    });
+    actions.registerContextContributor({
+      id: actionContext.contributorId,
+      contribute: actionContext.contribute
+    });
+
+    const authPolicyResolver = createWorkspaceAuthPolicyContextResolver({
+      workspaceMembershipOptionalSurfaceIds: membershipOptionalSurfaceIds,
+      workspaceService
+    });
+    authExtensions.registerPolicyContextResolver({
+      resolverId: "workspaces.policy",
+      resolveAuthPolicyContext: authPolicyResolver
+    });
+
+    const visibility = createWorkspaceRouteVisibilityResolver({
+      workspaceMembershipOptionalSurfaceIds: membershipOptionalSurfaceIds,
+      workspaceService
+    });
+    http.registerVisibilityResolver({
+      id: visibility.resolverId,
+      resolve: visibility.resolve
+    });
+
+    usersExtensions.registerProfileSyncLifecycleContributor({
+      contributorId: "workspaces.provisioning",
+      order: 100,
+      async afterIdentityProfileSynced({ profile, options } = {}) {
+        await workspaceService.ensureProvisionedWorkspaceForAuthenticatedUser(profile, options);
+      }
+    });
+
+    if (workspaces.invitationsEnabled) {
+      authExtensions.registerInvitationContextResolver({
+        resolverId: "workspaces.invitation",
+        resolveInvitationContext(invitation, options = {}) {
+          return workspaces.services.pendingInvitations.resolveInviteContextForAuth(invitation, options);
+        }
+      });
+    }
+
+    return {};
+  }
+});
+
+export { WorkspacesIntegrationsProvider };

package/src/server/common/contributors/workspaceActionContextContributor.js

@@ -45,21 +45,20 @@ function createWorkspaceActionContextContributor({
 
   return Object.freeze({
     contributorId,
-    async contribute({ definition = null, input, context, request, surface = "" } = {}) {
+    async contribute({ definition = null, input, context } = {}) {
       const payload = normalizeObject(input);
       if (!Object.hasOwn(payload, "workspaceSlug")) {
         return {};
       }
 
+      const request = context?.requestMeta?.request || null;
       const actionSurfaces = Array.isArray(definition?.surfaces) ? definition.surfaces : [];
       const hasWorkspaceActionSurface = actionSurfaces.some((surfaceId) => workspaceSurfaceIdSet.has(surfaceId));
       const routeSurfaceId = normalizeSurfaceId(request?.routeOptions?.config?.surface);
-      const activeSurfaceId = routeSurfaceId || normalizeSurfaceId(surface || context?.surface);
+      const activeSurfaceId = routeSurfaceId || normalizeSurfaceId(context?.surface);
       const hasWorkspaceSurface = workspaceSurfaceIdSet.has(routeSurfaceId);
       const routeVisibilityInput =
-        request && request.routeOptions && request.routeOptions.config
-          ? request.routeOptions.config.visibility
-          : ROUTE_VISIBILITY_PUBLIC;
+        context?.routeVisibility ?? request?.routeOptions?.config?.visibility ?? ROUTE_VISIBILITY_PUBLIC;
       const routeVisibility = checkRouteVisibility(routeVisibilityInput);
       const hasWorkspaceRouteVisibility = WORKSPACE_VISIBILITY_ACTION_CONTEXT_SET.has(routeVisibility);
       if (!hasWorkspaceActionSurface && !hasWorkspaceRouteVisibility && !hasWorkspaceSurface) {
@@ -67,10 +66,7 @@ function createWorkspaceActionContextContributor({
       }
 
       const resolveOptions = { request };
-      if (
-        !hasWorkspaceRouteVisibility &&
-        workspaceMembershipOptionalSurfaceIdSet.has(activeSurfaceId)
-      ) {
+      if (workspaceMembershipOptionalSurfaceIdSet.has(activeSurfaceId)) {
         resolveOptions.requireMembership = false;
       }
 

package/src/server/common/contributors/workspaceAuthPolicyContextResolver.js

@@ -1,12 +1,22 @@
 import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
+import { normalizeSurfaceId } from "@jskit-ai/kernel/shared/surface/registry";
 
-function createWorkspaceAuthPolicyContextResolver({ workspaceService } = {}) {
+function createWorkspaceAuthPolicyContextResolver({
+  workspaceService,
+  workspaceMembershipOptionalSurfaceIds = []
+} = {}) {
   if (!workspaceService || typeof workspaceService.resolveWorkspaceContextForUserBySlug !== "function") {
     throw new Error(
       "workspace auth policy context resolver requires workspaceService.resolveWorkspaceContextForUserBySlug()."
     );
   }
 
+  const membershipOptionalSurfaceIds = new Set(
+    (Array.isArray(workspaceMembershipOptionalSurfaceIds) ? workspaceMembershipOptionalSurfaceIds : [])
+      .map((entry) => normalizeSurfaceId(entry))
+      .filter(Boolean)
+  );
+
   return async function resolveWorkspaceAuthPolicyContext({ request, actor, meta } = {}) {
     const contextPolicy = normalizeText(meta?.contextPolicy || "none").toLowerCase() || "none";
     const permission = normalizeText(meta?.permission);
@@ -20,7 +30,11 @@ function createWorkspaceAuthPolicyContextResolver({ workspaceService } = {}) {
     }
 
     const resolveOptions = { request };
-    if (contextPolicy === "optional" && !permission) {
+    const activeSurfaceId = normalizeSurfaceId(request?.routeOptions?.config?.surface);
+    if (
+      (contextPolicy === "optional" && !permission) ||
+      membershipOptionalSurfaceIds.has(activeSurfaceId)
+    ) {
       resolveOptions.requireMembership = false;
     }
 

package/src/server/common/contributors/workspaceRouteVisibilityResolver.js

@@ -1,4 +1,5 @@
 import { normalizeOpaqueId, normalizeRecordId, normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
+import { normalizeSurfaceId } from "@jskit-ai/kernel/shared/surface/registry";
 
 function buildVisibilityContribution({ visibility, scopeOwnerId = null, userId = null } = {}) {
   const requiresActorScope = visibility === "workspace_user";
@@ -17,11 +18,20 @@ function buildVisibilityContribution({ visibility, scopeOwnerId = null, userId =
   return contribution;
 }
 
-function createWorkspaceRouteVisibilityResolver({ workspaceService } = {}) {
+function createWorkspaceRouteVisibilityResolver({
+  workspaceService,
+  workspaceMembershipOptionalSurfaceIds = []
+} = {}) {
   if (!workspaceService || typeof workspaceService.resolveWorkspaceContextForUserBySlug !== "function") {
     throw new Error("workspace route visibility resolver requires workspaceService.resolveWorkspaceContextForUserBySlug().");
   }
 
+  const membershipOptionalSurfaceIds = new Set(
+    (Array.isArray(workspaceMembershipOptionalSurfaceIds) ? workspaceMembershipOptionalSurfaceIds : [])
+      .map((entry) => normalizeSurfaceId(entry))
+      .filter(Boolean)
+  );
+
   return Object.freeze({
     resolverId: "workspaces.visibility",
     async resolve({ visibility, context, request, input } = {}) {
@@ -46,9 +56,17 @@ function createWorkspaceRouteVisibilityResolver({ workspaceService } = {}) {
             : {};
         }
 
-        const resolvedWorkspaceContext = await workspaceService.resolveWorkspaceContextForUserBySlug(actor, workspaceSlug, {
-          request
-        });
+        const activeSurfaceId = normalizeSurfaceId(
+          request?.routeOptions?.config?.surface || context?.surface
+        );
+        const resolvedWorkspaceContext = await workspaceService.resolveWorkspaceContextForUserBySlug(
+          actor,
+          workspaceSlug,
+          {
+            request,
+            ...(membershipOptionalSurfaceIds.has(activeSurfaceId) ? { requireMembership: false } : {})
+          }
+        );
         const resolvedWorkspaceOwnerId = normalizeRecordId(resolvedWorkspaceContext?.workspace?.id, { fallback: null });
         if (!resolvedWorkspaceOwnerId) {
           return visibility === "workspace_user"