@jskit-ai/workspaces-web 0.1.13 → 0.1.15

package/src/client/lib/bootstrap.js

@@ -0,0 +1,59 @@
+import { normalizeLowerText, normalizeText } from "@jskit-ai/kernel/shared/actions/textNormalization";
+import { normalizeRecordId } from "@jskit-ai/kernel/shared/support/normalize";
+
+function normalizeWorkspaceSlug(value = "") {
+  return normalizeLowerText(value);
+}
+
+function normalizeWorkspaceEntry(entry = null) {
+  if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+    return null;
+  }
+
+  const id = normalizeRecordId(entry.id, { fallback: "" });
+  const slug = normalizeWorkspaceSlug(entry.slug);
+  const name = normalizeText(entry.name);
+  if (!id || !slug || !name) {
+    return null;
+  }
+
+  return Object.freeze({
+    id,
+    slug,
+    name,
+    avatarUrl: normalizeText(entry.avatarUrl),
+    roleSid: normalizeLowerText(entry.roleSid || "member") || "member",
+    isAccessible: entry.isAccessible !== false
+  });
+}
+
+function normalizeWorkspaceList(entries = []) {
+  if (!Array.isArray(entries)) {
+    return [];
+  }
+
+  return entries.map((entry) => normalizeWorkspaceEntry(entry)).filter(Boolean);
+}
+
+function findWorkspaceBySlug(entries = [], workspaceSlug = "") {
+  const normalizedWorkspaceSlug = normalizeWorkspaceSlug(workspaceSlug);
+  if (!normalizedWorkspaceSlug) {
+    return null;
+  }
+
+  return normalizeWorkspaceList(entries).find((entry) => entry.slug === normalizedWorkspaceSlug) || null;
+}
+
+function buildBootstrapApiPath(workspaceSlug = "") {
+  const normalizedWorkspaceSlug = normalizeWorkspaceSlug(workspaceSlug);
+  if (!normalizedWorkspaceSlug) {
+    return "/api/bootstrap";
+  }
+
+  const params = new URLSearchParams({
+    workspaceSlug: normalizedWorkspaceSlug
+  });
+  return `/api/bootstrap?${params.toString()}`;
+}
+
+export { buildBootstrapApiPath, findWorkspaceBySlug, normalizeWorkspaceEntry, normalizeWorkspaceList };

package/src/client/lib/httpClient.js

@@ -0,0 +1,10 @@
+import { createTransientRetryHttpClient } from "@jskit-ai/http-runtime/client";
+
+const workspacesWebHttpClient = createTransientRetryHttpClient({
+  credentials: "include",
+  csrf: {
+    sessionPath: "/api/session"
+  }
+});
+
+export { workspacesWebHttpClient };

package/src/client/lib/permissions.js

@@ -0,0 +1,27 @@
+import { hasPermission, normalizePermissionList } from "@jskit-ai/kernel/shared/support";
+
+function toPermissionSet(values) {
+  const normalized = normalizePermissionList(values);
+  if (normalized.length < 1) {
+    return new Set();
+  }
+  return new Set(normalized);
+}
+
+function arePermissionListsEqual(left, right) {
+  const leftSet = toPermissionSet(left);
+  const rightSet = toPermissionSet(right);
+  if (leftSet.size !== rightSet.size) {
+    return false;
+  }
+
+  for (const permission of leftSet) {
+    if (!rightSet.has(permission)) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+export { normalizePermissionList, arePermissionListsEqual, hasPermission };

package/src/client/lib/profileSurfaceMenuLinks.js

@@ -0,0 +1,163 @@
+import {
+  resolveSurfaceIdFromPlacementPathname
+} from "@jskit-ai/shell-web/client/placement";
+import { resolveWorkspaceShellLinkPath } from "./workspaceLinkResolver.js";
+import { resolveSurfaceSwitchTargetsFromPlacementContext } from "./workspaceSurfaceContext.js";
+import { evaluateSurfaceAccess, hasWorkspaceMembership } from "./surfaceAccessPolicy.js";
+import {
+  resolveWorkspaceSurfaceIdFromPlacementPathname,
+  extractWorkspaceSlugFromSurfacePathname
+} from "./workspaceSurfacePaths.js";
+import {
+  mdiArrowRightCircleOutline,
+  mdiHomeVariantOutline,
+  mdiShieldCrownOutline,
+  mdiViewDashboardOutline
+} from "@mdi/js";
+
+const SURFACE_SWITCH_ICON_BY_ID = Object.freeze({
+  home: mdiHomeVariantOutline,
+  app: mdiViewDashboardOutline,
+  admin: mdiShieldCrownOutline
+});
+
+function resolveSurfaceSwitchIcon(surfaceId = "", explicitIcon = "") {
+  const resolvedExplicitIcon = String(explicitIcon || "").trim();
+  if (resolvedExplicitIcon) {
+    return resolvedExplicitIcon;
+  }
+
+  const normalizedSurfaceId = String(surfaceId || "").trim().toLowerCase();
+  return SURFACE_SWITCH_ICON_BY_ID[normalizedSurfaceId] || mdiArrowRightCircleOutline;
+}
+
+function resolveCurrentWorkspaceSlug(contextValue, surfaceId) {
+  const context = contextValue && typeof contextValue === "object" ? contextValue : {};
+  const workspaceSlugFromContext = String(context?.workspace?.slug || "").trim();
+  if (workspaceSlugFromContext) {
+    return workspaceSlugFromContext;
+  }
+
+  if (typeof window !== "object" || !window?.location?.pathname) {
+    return "";
+  }
+
+  const pathname = String(window.location.pathname || "").trim();
+  const currentSurfaceId =
+    resolveWorkspaceSurfaceIdFromPlacementPathname(context, pathname) ||
+    resolveSurfaceIdFromPlacementPathname(context, pathname) ||
+    surfaceId;
+  return String(extractWorkspaceSlugFromSurfacePathname(context, currentSurfaceId, pathname) || "").trim();
+}
+
+function shouldIncludeSurfaceSwitchTarget(surfaceDefinition = null) {
+  if (!surfaceDefinition || typeof surfaceDefinition !== "object") {
+    return false;
+  }
+
+  if (surfaceDefinition.enabled === false) {
+    return false;
+  }
+
+  if (surfaceDefinition.showInSurfaceSwitchMenu === true) {
+    return true;
+  }
+  if (surfaceDefinition.showInSurfaceSwitchMenu === false) {
+    return false;
+  }
+
+  return surfaceDefinition.requiresWorkspace === true || surfaceDefinition.requiresAuth === true;
+}
+
+function resolveSurfaceSwitchLinkLabel(surfaceDefinition = null, surfaceId = "") {
+  const normalizedSurfaceId = String(surfaceId || "").trim();
+  const configuredLabel = String(surfaceDefinition?.label || "").trim();
+  const label = configuredLabel || normalizedSurfaceId;
+  if (!label) {
+    return "Go to surface";
+  }
+  return `Go to ${label.toLowerCase()}`;
+}
+
+function resolveSurfaceSwitchLinks({ context, surface } = {}) {
+  const source = context && typeof context === "object" ? context : {};
+  const targets = resolveSurfaceSwitchTargetsFromPlacementContext(source, surface);
+  const currentSurfaceId = String(targets.currentSurfaceId || "").trim().toLowerCase();
+  const resolvedWorkspaceSlug = resolveCurrentWorkspaceSlug(source, currentSurfaceId || surface);
+  const workspaceSlug = hasWorkspaceMembership(source, resolvedWorkspaceSlug) ? resolvedWorkspaceSlug : "";
+  const enabledSurfaceIds = Array.isArray(targets?.surfaceConfig?.enabledSurfaceIds)
+    ? targets.surfaceConfig.enabledSurfaceIds
+    : [];
+  const links = [];
+
+  for (const targetSurfaceIdCandidate of enabledSurfaceIds) {
+    const targetSurfaceId = String(targetSurfaceIdCandidate || "").trim().toLowerCase();
+    if (!targetSurfaceId) {
+      continue;
+    }
+    if (targetSurfaceId === currentSurfaceId) {
+      continue;
+    }
+
+    const targetSurface = targets.surfaceConfig.surfacesById[targetSurfaceId] || null;
+    if (!shouldIncludeSurfaceSwitchTarget(targetSurface)) {
+      continue;
+    }
+
+    const targetWorkspaceSlug = targetSurface?.requiresWorkspace === true ? workspaceSlug : "";
+    if (targetSurface?.requiresWorkspace === true && !targetWorkspaceSlug) {
+      continue;
+    }
+
+    const accessDecision = evaluateSurfaceAccess({
+      context: source,
+      surfaceId: targetSurfaceId,
+      workspaceSlug: targetWorkspaceSlug
+    });
+    if (!accessDecision.allowed) {
+      continue;
+    }
+
+    links.push({
+      id: `surface-switch.${targetSurfaceId}`,
+      label: resolveSurfaceSwitchLinkLabel(targetSurface, targetSurfaceId),
+      icon: resolveSurfaceSwitchIcon(targetSurfaceId, targetSurface?.icon),
+      to: resolveWorkspaceShellLinkPath({
+        context: source,
+        surface: targetSurfaceId,
+        workspaceSlug: targetWorkspaceSlug,
+        mode: targetSurface?.requiresWorkspace === true ? "workspace" : "surface",
+        relativePath: "/"
+      })
+    });
+  }
+
+  return links;
+}
+
+function resolvePrimarySurfaceSwitchLink({ context, surface } = {}) {
+  const links = resolveSurfaceSwitchLinks({
+    context,
+    surface
+  });
+  return links[0] || null;
+}
+
+function resolveProfileSurfaceMenuLinks({ context, surface } = {}) {
+  const source = context && typeof context === "object" ? context : {};
+  const authenticated = Boolean(source?.auth?.authenticated);
+  if (!authenticated) {
+    return [];
+  }
+  return resolveSurfaceSwitchLinks({
+    context: source,
+    surface
+  });
+}
+
+export {
+  resolveProfileSurfaceMenuLinks,
+  resolvePrimarySurfaceSwitchLink,
+  resolveSurfaceSwitchLinks,
+  hasWorkspaceMembership
+};

package/src/client/lib/surfaceAccessPolicy.js

@@ -0,0 +1,350 @@
+import { resolveSurfaceDefinitionFromPlacementContext } from "@jskit-ai/shell-web/client/placement";
+import { normalizeSurfaceId } from "@jskit-ai/kernel/shared/surface/registry";
+import {
+  normalizeRecord,
+  normalizeWorkspaceBootstrapStatusValue
+} from "../support/runtimeNormalization.js";
+import { hasPermission, normalizePermissionList } from "./permissions.js";
+
+const WORKSPACE_BOOTSTRAP_STATUS_NOT_FOUND = "not_found";
+const WORKSPACE_BOOTSTRAP_STATUS_FORBIDDEN = "forbidden";
+const WORKSPACE_ACCESS_BLOCKING_STATUSES = new Set([
+  WORKSPACE_BOOTSTRAP_STATUS_NOT_FOUND,
+  WORKSPACE_BOOTSTRAP_STATUS_FORBIDDEN
+]);
+
+function normalizeSurfaceAccessPolicyId(value = "") {
+  return String(value || "")
+    .trim()
+    .toLowerCase();
+}
+
+function normalizeWorkspaceSlug(value = "") {
+  return String(value || "")
+    .trim()
+    .toLowerCase();
+}
+
+function normalizeAccessFlagName(value = "") {
+  return String(value || "")
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "");
+}
+
+function normalizeStringList(value) {
+  const source = Array.isArray(value) ? value : [value];
+  const output = [];
+  for (const entry of source) {
+    const normalizedEntry = normalizeAccessFlagName(entry);
+    if (!normalizedEntry || output.includes(normalizedEntry)) {
+      continue;
+    }
+    output.push(normalizedEntry);
+  }
+  return output;
+}
+
+function normalizeSurfaceAccessFlags(value = null) {
+  const source = normalizeRecord(value);
+  const flags = {};
+
+  for (const [candidateKey, candidateValue] of Object.entries(source)) {
+    const key = normalizeAccessFlagName(candidateKey);
+    if (!key) {
+      continue;
+    }
+    flags[key] = candidateValue === true;
+  }
+
+  return flags;
+}
+
+function hasPlacementValue(source, key) {
+  if (!source || typeof source !== "object") {
+    return false;
+  }
+  return Object.hasOwn(source, key);
+}
+
+function hasKnownWorkspaceMembershipContext(contextValue = null) {
+  return hasPlacementValue(contextValue, "workspaces");
+}
+
+function hasKnownPermissionsContext(contextValue = null) {
+  return hasPlacementValue(contextValue, "permissions");
+}
+
+function hasKnownSurfaceAccessContext(contextValue = null) {
+  return hasPlacementValue(contextValue, "surfaceAccess");
+}
+
+function hasWorkspaceMembership(contextValue = null, workspaceSlug = "") {
+  const normalizedWorkspaceSlug = normalizeWorkspaceSlug(workspaceSlug);
+  if (!normalizedWorkspaceSlug) {
+    return false;
+  }
+
+  const context = normalizeRecord(contextValue);
+  if (normalizeWorkspaceSlug(context?.workspace?.slug) === normalizedWorkspaceSlug) {
+    return true;
+  }
+
+  const workspaces = Array.isArray(context.workspaces) ? context.workspaces : [];
+  for (const workspace of workspaces) {
+    if (normalizeWorkspaceSlug(workspace?.slug) === normalizedWorkspaceSlug) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+function resolveSurfaceAccessPolicies(contextValue = null) {
+  const context = normalizeRecord(contextValue);
+  const configuredPolicies = normalizeRecord(context.surfaceAccessPolicies);
+  const policies = {};
+
+  for (const [candidatePolicyId, candidatePolicy] of Object.entries(configuredPolicies)) {
+    const policyId = normalizeSurfaceAccessPolicyId(candidatePolicyId);
+    if (!policyId) {
+      continue;
+    }
+    policies[policyId] = normalizeRecord(candidatePolicy);
+  }
+
+  return policies;
+}
+
+function resolveSurfaceAccessPolicy(contextValue = null, surfaceDefinition = null) {
+  const definition = normalizeRecord(surfaceDefinition);
+  const policyId = normalizeSurfaceAccessPolicyId(definition.accessPolicyId);
+  const configuredPolicies = resolveSurfaceAccessPolicies(contextValue);
+  const configuredPolicy = policyId ? normalizeRecord(configuredPolicies[policyId]) : {};
+
+  const requireAuth = Object.hasOwn(configuredPolicy, "requireAuth")
+    ? configuredPolicy.requireAuth === true
+    : definition.requiresAuth === true;
+  const requireWorkspaceMembership = Object.hasOwn(configuredPolicy, "requireWorkspaceMembership")
+    ? configuredPolicy.requireWorkspaceMembership === true
+    : definition.requiresWorkspace === true;
+  const requireAnyPermissions = normalizePermissionList(configuredPolicy.requireAnyPermissions);
+  const requireAllPermissions = normalizePermissionList(configuredPolicy.requireAllPermissions);
+  const requireFlagsAny = normalizeStringList(configuredPolicy.requireFlagsAny);
+  const requireFlagsAll = normalizeStringList(configuredPolicy.requireFlagsAll);
+
+  return Object.freeze({
+    policyId,
+    requireAuth,
+    requireWorkspaceMembership,
+    requireAnyPermissions: Object.freeze([...requireAnyPermissions]),
+    requireAllPermissions: Object.freeze([...requireAllPermissions]),
+    requireFlagsAny: Object.freeze([...requireFlagsAny]),
+    requireFlagsAll: Object.freeze([...requireFlagsAll])
+  });
+}
+
+function toAccessDecision({ allowed = false, pending = false, reason = "" } = {}) {
+  return Object.freeze({
+    allowed: allowed === true,
+    pending: pending === true,
+    reason: String(reason || "").trim()
+  });
+}
+
+function evaluatePermissionRequirements(policy, permissions = []) {
+  if (policy.requireAnyPermissions.length > 0) {
+    const hasAnyRequiredPermission = policy.requireAnyPermissions.some((permission) => hasPermission(permissions, permission));
+    if (!hasAnyRequiredPermission) {
+      return toAccessDecision({
+        allowed: false,
+        reason: "surface-access-missing-any-permission"
+      });
+    }
+  }
+
+  if (policy.requireAllPermissions.length > 0) {
+    for (const permission of policy.requireAllPermissions) {
+      if (hasPermission(permissions, permission)) {
+        continue;
+      }
+      return toAccessDecision({
+        allowed: false,
+        reason: "surface-access-missing-permission"
+      });
+    }
+  }
+
+  return toAccessDecision({
+    allowed: true
+  });
+}
+
+function evaluateFlagRequirements(policy, flags = {}) {
+  const normalizedFlags = normalizeSurfaceAccessFlags(flags);
+  if (policy.requireFlagsAll.length > 0) {
+    for (const flagName of policy.requireFlagsAll) {
+      if (normalizedFlags[flagName] === true) {
+        continue;
+      }
+      return toAccessDecision({
+        allowed: false,
+        reason: "surface-access-missing-flag"
+      });
+    }
+  }
+
+  if (policy.requireFlagsAny.length > 0) {
+    const hasAnyRequiredFlag = policy.requireFlagsAny.some((flagName) => normalizedFlags[flagName] === true);
+    if (!hasAnyRequiredFlag) {
+      return toAccessDecision({
+        allowed: false,
+        reason: "surface-access-missing-any-flag"
+      });
+    }
+  }
+
+  return toAccessDecision({
+    allowed: true
+  });
+}
+
+function evaluateSurfaceAccess({
+  context = null,
+  surfaceId = "",
+  workspaceSlug = "",
+  allowOnUnknown = false
+} = {}) {
+  const source = normalizeRecord(context);
+  const normalizedSurfaceId = normalizeSurfaceId(surfaceId);
+  if (!normalizedSurfaceId) {
+    return toAccessDecision({
+      allowed: false,
+      reason: "surface-access-invalid-surface"
+    });
+  }
+
+  const surfaceDefinition = resolveSurfaceDefinitionFromPlacementContext(source, normalizedSurfaceId);
+  if (!surfaceDefinition || surfaceDefinition.enabled === false) {
+    return toAccessDecision({
+      allowed: false,
+      reason: "surface-access-disabled"
+    });
+  }
+
+  const policy = resolveSurfaceAccessPolicy(source, surfaceDefinition);
+  if (policy.requireAuth && source?.auth?.authenticated !== true) {
+    return toAccessDecision({
+      allowed: false,
+      reason: "surface-access-auth-required"
+    });
+  }
+
+  const normalizedWorkspaceSlug = normalizeWorkspaceSlug(workspaceSlug);
+  if (policy.requireWorkspaceMembership) {
+    if (!normalizedWorkspaceSlug) {
+      return toAccessDecision({
+        allowed: false,
+        reason: "surface-access-workspace-required"
+      });
+    }
+
+    const workspaceBootstrapStatuses = normalizeRecord(source.workspaceBootstrapStatuses);
+    const workspaceStatus = normalizeWorkspaceBootstrapStatusValue(
+      workspaceBootstrapStatuses[normalizedWorkspaceSlug],
+      WORKSPACE_ACCESS_BLOCKING_STATUSES
+    );
+    if (workspaceStatus === WORKSPACE_BOOTSTRAP_STATUS_NOT_FOUND) {
+      return toAccessDecision({
+        allowed: false,
+        reason: "surface-access-workspace-not-found"
+      });
+    }
+    if (workspaceStatus === WORKSPACE_BOOTSTRAP_STATUS_FORBIDDEN) {
+      return toAccessDecision({
+        allowed: false,
+        reason: "surface-access-workspace-forbidden"
+      });
+    }
+
+    if (hasKnownWorkspaceMembershipContext(source)) {
+      if (!hasWorkspaceMembership(source, normalizedWorkspaceSlug)) {
+        if (allowOnUnknown && !workspaceStatus) {
+          return toAccessDecision({
+            allowed: true,
+            pending: true
+          });
+        }
+        return toAccessDecision({
+          allowed: false,
+          reason: "surface-access-workspace-membership-required"
+        });
+      }
+    } else if (allowOnUnknown) {
+      return toAccessDecision({
+        allowed: true,
+        pending: true
+      });
+    } else {
+      return toAccessDecision({
+        allowed: false,
+        pending: true,
+        reason: "surface-access-pending"
+      });
+    }
+  }
+
+  const placementPermissions = normalizePermissionList(source.permissions);
+  if (policy.requireAnyPermissions.length > 0 || policy.requireAllPermissions.length > 0) {
+    if (!hasKnownPermissionsContext(source)) {
+      if (allowOnUnknown) {
+        return toAccessDecision({
+          allowed: true,
+          pending: true
+        });
+      }
+      return toAccessDecision({
+        allowed: false,
+        pending: true,
+        reason: "surface-access-pending"
+      });
+    }
+
+    const permissionDecision = evaluatePermissionRequirements(policy, placementPermissions);
+    if (!permissionDecision.allowed) {
+      return permissionDecision;
+    }
+  }
+
+  if (policy.requireFlagsAny.length > 0 || policy.requireFlagsAll.length > 0) {
+    if (!hasKnownSurfaceAccessContext(source)) {
+      if (allowOnUnknown) {
+        return toAccessDecision({
+          allowed: true,
+          pending: true
+        });
+      }
+      return toAccessDecision({
+        allowed: false,
+        pending: true,
+        reason: "surface-access-pending"
+      });
+    }
+
+    const accessFlags = normalizeRecord(source.surfaceAccess);
+    const flagDecision = evaluateFlagRequirements(policy, accessFlags);
+    if (!flagDecision.allowed) {
+      return flagDecision;
+    }
+  }
+
+  return toAccessDecision({
+    allowed: true
+  });
+}
+
+export {
+  hasWorkspaceMembership,
+  resolveSurfaceAccessPolicy,
+  evaluateSurfaceAccess
+};