@elevasis/core 0.29.0 → 0.30.0

package/src/auth/access-keys.ts

@@ -0,0 +1,173 @@
+import { z } from 'zod'
+import { listAllSystems } from '../organization-model/helpers'
+import type { OrganizationModel } from '../organization-model/types'
+import { PERMISSIONS, type PermissionKey } from './multi-tenancy/permissions'
+
+export const DEFAULT_ACCESS_ACTION = 'view' as const
+export const PLATFORM_ADMIN_ACCESS_KEY = 'platform.admin' as const
+export const PLATFORM_ADMIN_ACCESS_KEY_SHORTHAND = 'platformAdmin' as const
+
+export const AccessActionSchema = z.enum(['view', 'manage'])
+
+export const AccessKeyObjectSchema = z
+  .object({
+    systemPath: z.string().trim().min(1),
+    action: AccessActionSchema.default(DEFAULT_ACCESS_ACTION)
+  })
+  .strict()
+
+export const AccessKeyInputSchema = z.union([z.string().trim().min(1), AccessKeyObjectSchema])
+export const NormalizedAccessKeySchema = AccessKeyObjectSchema
+export const AccessKeySchema = AccessKeyInputSchema
+
+export type AccessAction = z.infer<typeof AccessActionSchema>
+export type AccessKeyObject = z.infer<typeof AccessKeyObjectSchema>
+export type AccessKeyInput = z.input<typeof AccessKeyInputSchema>
+export type NormalizedAccessKey = z.infer<typeof NormalizedAccessKeySchema>
+export type AccessKey = NormalizedAccessKey
+
+export type AccessCatalogEntrySource = 'om-system' | 'diagnostic' | 'platform' | 'permission'
+
+export interface AccessCatalogEntry {
+  key: NormalizedAccessKey
+  source: AccessCatalogEntrySource
+  rolePermission?: string
+}
+
+export interface AccessKeyCatalog {
+  bySystemPath: ReadonlyMap<string, readonly AccessCatalogEntry[]>
+  entries: readonly AccessCatalogEntry[]
+}
+
+export const DIAGNOSTIC_VIEW_ACCESS_KEYS = [
+  'diagnostic.operations.overview',
+  'diagnostic.operations.recent-executions',
+  'diagnostic.monitoring.execution-logs',
+  'diagnostic.monitoring.notifications'
+] as const
+
+export const AccessKeys = {
+  platformAdmin: { systemPath: PLATFORM_ADMIN_ACCESS_KEY, action: DEFAULT_ACCESS_ACTION },
+  organizationManage: { systemPath: 'permission.org', action: 'manage' },
+  membersManage: { systemPath: 'permission.members', action: 'manage' },
+  rolesManage: { systemPath: 'permission.roles', action: 'manage' },
+  secretsManage: { systemPath: 'permission.secrets', action: 'manage' },
+  operationsRead: { systemPath: 'permission.operations', action: DEFAULT_ACCESS_ACTION },
+  operationsManage: { systemPath: 'permission.operations', action: 'manage' },
+  acquisitionManage: { systemPath: 'permission.acquisition', action: 'manage' },
+  projectsManage: { systemPath: 'permission.projects', action: 'manage' },
+  clientsManage: { systemPath: 'permission.clients', action: 'manage' },
+  operationsOverview: { systemPath: 'diagnostic.operations.overview', action: DEFAULT_ACCESS_ACTION },
+  operationsRecentExecutions: { systemPath: 'diagnostic.operations.recent-executions', action: DEFAULT_ACCESS_ACTION },
+  monitoringExecutionLogs: { systemPath: 'diagnostic.monitoring.execution-logs', action: DEFAULT_ACCESS_ACTION },
+  monitoringNotifications: { systemPath: 'diagnostic.monitoring.notifications', action: DEFAULT_ACCESS_ACTION }
+} as const satisfies Record<string, NormalizedAccessKey>
+
+const PERMISSION_ACCESS_KEY_DEFINITIONS: readonly {
+  key: NormalizedAccessKey
+  rolePermission: PermissionKey
+}[] = [
+  { key: AccessKeys.organizationManage, rolePermission: PERMISSIONS.ORG_MANAGE },
+  { key: AccessKeys.membersManage, rolePermission: PERMISSIONS.MEMBERS_MANAGE },
+  { key: AccessKeys.rolesManage, rolePermission: PERMISSIONS.ROLES_MANAGE },
+  { key: AccessKeys.secretsManage, rolePermission: PERMISSIONS.SECRETS_MANAGE },
+  { key: AccessKeys.operationsRead, rolePermission: PERMISSIONS.OPERATIONS_READ },
+  { key: AccessKeys.operationsManage, rolePermission: PERMISSIONS.OPERATIONS_MANAGE },
+  { key: AccessKeys.acquisitionManage, rolePermission: PERMISSIONS.ACQUISITION_MANAGE },
+  { key: AccessKeys.projectsManage, rolePermission: PERMISSIONS.PROJECTS_MANAGE },
+  { key: AccessKeys.clientsManage, rolePermission: PERMISSIONS.CLIENTS_MANAGE }
+]
+
+export function normalizeAccessKey(input: AccessKeyInput): NormalizedAccessKey {
+  const parsed = AccessKeyInputSchema.parse(input)
+  const normalized =
+    typeof parsed === 'string'
+      ? {
+          systemPath: parsed === PLATFORM_ADMIN_ACCESS_KEY_SHORTHAND ? PLATFORM_ADMIN_ACCESS_KEY : parsed,
+          action: DEFAULT_ACCESS_ACTION
+        }
+      : parsed
+
+  return NormalizedAccessKeySchema.parse(normalized)
+}
+
+export function accessKeyToString(input: AccessKeyInput): string {
+  const key = normalizeAccessKey(input)
+  return `${key.systemPath}:${key.action}`
+}
+
+export function rolePermissionForAccessKey(key: NormalizedAccessKey): string | undefined {
+  if (key.action === DEFAULT_ACCESS_ACTION) return undefined
+  return `${key.systemPath}.${key.action}`
+}
+
+export interface DeriveAccessKeyCatalogOptions {
+  diagnosticKeys?: readonly string[]
+  includeManageActions?: boolean
+}
+
+function groupCatalogEntries(entries: readonly AccessCatalogEntry[]): ReadonlyMap<string, readonly AccessCatalogEntry[]> {
+  const grouped = new Map<string, AccessCatalogEntry[]>()
+
+  for (const entry of entries) {
+    const existing = grouped.get(entry.key.systemPath) ?? []
+    existing.push(entry)
+    grouped.set(entry.key.systemPath, existing)
+  }
+
+  return grouped
+}
+
+function buildCatalogEntry(systemPath: string, action: AccessAction, source: AccessCatalogEntrySource): AccessCatalogEntry {
+  const key = normalizeAccessKey({ systemPath, action })
+  return {
+    key,
+    source,
+    rolePermission: rolePermissionForAccessKey(key)
+  }
+}
+
+export function deriveAccessKeyCatalog(
+  organizationModel: OrganizationModel,
+  options: DeriveAccessKeyCatalogOptions = {}
+): AccessKeyCatalog {
+  const { diagnosticKeys = DIAGNOSTIC_VIEW_ACCESS_KEYS, includeManageActions = true } = options
+  const entries: AccessCatalogEntry[] = [
+    buildCatalogEntry(PLATFORM_ADMIN_ACCESS_KEY, DEFAULT_ACCESS_ACTION, 'platform')
+  ]
+
+  for (const { path } of listAllSystems(organizationModel)) {
+    entries.push(buildCatalogEntry(path, DEFAULT_ACCESS_ACTION, 'om-system'))
+    if (includeManageActions) {
+      entries.push(buildCatalogEntry(path, 'manage', 'om-system'))
+    }
+  }
+
+  for (const { key, rolePermission } of PERMISSION_ACCESS_KEY_DEFINITIONS) {
+    entries.push({
+      key,
+      source: 'permission',
+      rolePermission
+    })
+  }
+
+  for (const systemPath of diagnosticKeys) {
+    entries.push(buildCatalogEntry(systemPath, DEFAULT_ACCESS_ACTION, 'diagnostic'))
+  }
+
+  return {
+    bySystemPath: groupCatalogEntries(entries),
+    entries
+  }
+}
+
+export function findAccessCatalogEntry(
+  catalog: AccessKeyCatalog,
+  key: NormalizedAccessKey
+): AccessCatalogEntry | undefined {
+  return catalog.bySystemPath.get(key.systemPath)?.find((entry) => entry.key.action === key.action)
+}
+
+export function listAccessKeys(catalog: AccessKeyCatalog): NormalizedAccessKey[] {
+  return catalog.entries.map((entry) => entry.key)
+}

package/src/auth/access-model.ts

@@ -0,0 +1,185 @@
+import {
+  DEFAULT_ACCESS_ACTION,
+  PLATFORM_ADMIN_ACCESS_KEY,
+  deriveAccessKeyCatalog,
+  findAccessCatalogEntry,
+  normalizeAccessKey,
+  type AccessKeyCatalog,
+  type AccessKeyInput,
+  type NormalizedAccessKey
+} from './access-keys'
+import { getSystem } from '../organization-model/helpers'
+import type { OrganizationModel, OrganizationModelSystemLifecycle } from '../organization-model/types'
+
+export type AccessRestrictedBy =
+  | 'catalog'
+  | 'membership'
+  | 'system-lifecycle'
+  | 'role-permission'
+  | 'diagnostic-allowlist'
+  | null
+
+export type AccessReason =
+  | 'allowed'
+  | 'platform-admin-bypass'
+  | 'invalid-access-key'
+  | 'unknown-access-key'
+  | 'organization-mismatch'
+  | 'missing-membership'
+  | 'system-not-active'
+  | 'role-permission-denied'
+  | 'diagnostic-key-not-allowed'
+
+export interface AccessAnswer {
+  allowed: boolean
+  restrictedBy: AccessRestrictedBy
+  reason: AccessReason
+}
+
+export interface AccessContextMembership {
+  id?: string
+  organizationId: string
+  role?: string | null
+  effectivePermissions?: readonly string[] | null
+}
+
+export interface AccessContextProfile {
+  id?: string
+  isPlatformAdmin?: boolean | null
+  is_platform_admin?: boolean | null
+}
+
+export interface AccessContext {
+  organizationId: string
+  organizationModel: OrganizationModel
+  membership?: AccessContextMembership | null
+  profile?: AccessContextProfile | null
+  permissions?: readonly string[] | null
+  diagnosticAllowlist?: ReadonlySet<string> | readonly string[]
+  accessCatalog?: AccessKeyCatalog
+  betaAccessEnabled?: boolean
+  isDevelopment?: boolean
+}
+
+export interface AccessModel {
+  catalog: AccessKeyCatalog
+  checkAccess: (key: AccessKeyInput, ctx: Omit<AccessContext, 'accessCatalog'>) => AccessAnswer
+}
+
+const ALLOWED: AccessAnswer = { allowed: true, restrictedBy: null, reason: 'allowed' }
+const PLATFORM_ADMIN_BYPASS: AccessAnswer = {
+  allowed: true,
+  restrictedBy: null,
+  reason: 'platform-admin-bypass'
+}
+
+function deny(restrictedBy: Exclude<AccessRestrictedBy, null>, reason: Exclude<AccessReason, 'allowed'>): AccessAnswer {
+  return { allowed: false, restrictedBy, reason }
+}
+
+function isPlatformAdmin(profile: AccessContextProfile | null | undefined): boolean {
+  return profile?.isPlatformAdmin === true || profile?.is_platform_admin === true
+}
+
+function diagnosticAllowlistHas(
+  allowlist: AccessContext['diagnosticAllowlist'],
+  systemPath: string
+): boolean {
+  if (allowlist === undefined) return false
+  return 'has' in allowlist ? allowlist.has(systemPath) : allowlist.includes(systemPath)
+}
+
+function lifecycleAllowsAccess(
+  lifecycle: OrganizationModelSystemLifecycle | undefined,
+  ctx: Pick<AccessContext, 'betaAccessEnabled' | 'isDevelopment'>
+): boolean {
+  if (lifecycle === 'active') return true
+  if (lifecycle === 'beta') return ctx.betaAccessEnabled === true || ctx.isDevelopment === true
+  return false
+}
+
+function getPermissionSource(ctx: AccessContext): readonly string[] | null | undefined {
+  return ctx.permissions ?? ctx.membership?.effectivePermissions
+}
+
+function hasRequiredPermission(key: NormalizedAccessKey, rolePermission: string | undefined, ctx: AccessContext): boolean {
+  const permissionSource = getPermissionSource(ctx)
+  if (permissionSource === undefined || permissionSource === null) return true
+
+  const requiredPermission = rolePermission ?? `${key.systemPath}.${key.action}`
+  return permissionSource.includes(requiredPermission)
+}
+
+function hasExplicitRequiredPermission(rolePermission: string | undefined, ctx: AccessContext): boolean {
+  const permissionSource = getPermissionSource(ctx)
+  return rolePermission !== undefined && permissionSource !== undefined && permissionSource !== null
+    ? permissionSource.includes(rolePermission)
+    : false
+}
+
+export function checkAccess(input: AccessKeyInput, ctx: AccessContext): AccessAnswer {
+  if (isPlatformAdmin(ctx.profile)) return PLATFORM_ADMIN_BYPASS
+
+  const parsed = (() => {
+    try {
+      return normalizeAccessKey(input)
+    } catch {
+      return null
+    }
+  })()
+
+  if (parsed === null) return deny('catalog', 'invalid-access-key')
+
+  const catalog = ctx.accessCatalog ?? deriveAccessKeyCatalog(ctx.organizationModel)
+  const catalogEntry = findAccessCatalogEntry(catalog, parsed)
+
+  if (catalogEntry === undefined) return deny('catalog', 'unknown-access-key')
+
+  const membership = ctx.membership
+  if (membership === undefined || membership === null) return deny('membership', 'missing-membership')
+  if (membership.organizationId !== ctx.organizationId) return deny('membership', 'organization-mismatch')
+
+  if (parsed.systemPath === PLATFORM_ADMIN_ACCESS_KEY) {
+    return deny('role-permission', 'role-permission-denied')
+  }
+
+  if (catalogEntry.source === 'diagnostic') {
+    if (!diagnosticAllowlistHas(ctx.diagnosticAllowlist, parsed.systemPath)) {
+      return deny('diagnostic-allowlist', 'diagnostic-key-not-allowed')
+    }
+
+    if (parsed.action !== DEFAULT_ACCESS_ACTION && !hasRequiredPermission(parsed, catalogEntry.rolePermission, ctx)) {
+      return deny('role-permission', 'role-permission-denied')
+    }
+
+    return ALLOWED
+  }
+
+  if (catalogEntry.source === 'permission') {
+    if (!hasExplicitRequiredPermission(catalogEntry.rolePermission, ctx)) {
+      return deny('role-permission', 'role-permission-denied')
+    }
+
+    return ALLOWED
+  }
+
+  const system = getSystem(ctx.organizationModel, parsed.systemPath)
+  if (system === undefined || !lifecycleAllowsAccess(system.lifecycle, ctx)) {
+    return deny('system-lifecycle', 'system-not-active')
+  }
+
+  if (parsed.action !== DEFAULT_ACCESS_ACTION && !hasRequiredPermission(parsed, catalogEntry.rolePermission, ctx)) {
+    return deny('role-permission', 'role-permission-denied')
+  }
+
+  return ALLOWED
+}
+
+export function createAccessModel(organizationModel: OrganizationModel): AccessModel {
+  const catalog = deriveAccessKeyCatalog(organizationModel)
+
+  return {
+    catalog,
+    checkAccess: (key, ctx) => checkAccess(key, { ...ctx, organizationModel, accessCatalog: catalog })
+  }
+}

package/src/auth/index.ts

@@ -4,5 +4,9 @@
  * Identity and multi-tenancy types
  */
 
-// Multi-tenancy types (browser-safe only)
-export * from './multi-tenancy/index'
+// Multi-tenancy types (browser-safe only)
+export * from './multi-tenancy/index'
+
+// Unified access model primitives (browser-safe only)
+export * from './access-keys'
+export * from './access-model'

package/src/auth/multi-tenancy/memberships/membership.ts

@@ -1,5 +1,4 @@
-import type { MembershipFeatureConfig } from '../types'
-import { type MembershipStatus } from './api-schemas.js'
+import { type MembershipStatus } from './api-schemas.js'
 
 export type { MembershipStatus }
 
@@ -75,8 +74,7 @@ export interface MembershipWithDetails extends OrganizationMembership {
     metadata?: Record<string, unknown>
     config?: Record<string, unknown>
   }
-  config?: MembershipFeatureConfig
-}
+}
 
 /**
  * UI-specific membership table row data

package/src/auth/multi-tenancy/permissions.ts

@@ -4,7 +4,7 @@
  * Source of truth for the permission keys used by:
  *   - RLS policies in Supabase (via has_org_permission(org_id, key))
  *   - API middleware (via requireOrganizationPermission(key))
- *   - UI hooks (via useOrganizationPermissions().hasPermission(key))
+ *   - UI access checks (via useAccess() permission-backed AccessKeys)
  *
  * The DB table `org_rol_permissions` mirrors this constant. There is no
  * runtime reconciler; parity is enforced two ways:

package/src/auth/multi-tenancy/types.ts

@@ -3,23 +3,14 @@
  *
  * Config is stored in dedicated `config` columns (NOT nested in metadata):
  * - organizations.config: Org-level config (no feature toggles -- all features available by default)
- * - org_memberships.config: Per-user-per-org feature overrides
+ * - org_memberships.config: Reserved for non-access membership configuration
  * - users.config: User-global config
  */
 
 import type { ThemePresetName } from './theme-presets'
 
-/**
- * Per-user-per-org config (stored in org_memberships.config)
- * Controls which features a specific member can access within their org.
- * Keys are feature IDs from the organization model (e.g. crm, lead-gen, projects, seo).
- */
-export interface MembershipFeatureConfig {
-  features?: Record<string, boolean>
-}
-
-/**
- * User-global config (stored in users.config)
+/**
+ * User-global config (stored in users.config)
  * Theme and onboarding are user-specific, NOT org-specific
  */
 export interface UserConfig {

package/src/reference/glossary.md

@@ -7,7 +7,9 @@ description: Terminology disambiguation for Organization OS concepts used in the
 
 ## Terms
 
-**AdminGuard** -- route-level admin wrapper from `@elevasis/ui/features/auth`. Must nest inside `ProtectedRoute`.
+**AccessGuard** -- route-level and section-level access wrapper from `@elevasis/ui/auth`. It consumes the unified Access Model and gates on an `accessKey`.
+
+**AccessKeys** -- exported access-key constants from `@elevasis/core/auth` / `@repo/core/auth` for platform-admin, diagnostic, and permission-backed gates.
 
 **Contract** -- the publishable boundary a consumer depends on: Zod schemas, TypeScript types, provider props, resource definitions, or workflow I/O schemas.
 
@@ -15,7 +17,7 @@ description: Terminology disambiguation for Organization OS concepts used in the
 
 **Feature** -- legacy or UI-package wording for a platform capability area. In the current Organization Model, use **System** for semantic ownership and **navigation surface** for shell placement. Keep "feature" only when referring to existing UI package folders, exported manifest names, or legacy compatibility recipes.
 
-**SystemGuard** -- route-level System gate from `@elevasis/ui/features/auth`.
+**SystemGuard** -- retired route-level System gate. Use **AccessGuard** with a System path or `AccessKeys` constant.
 
 **SystemModule** -- manifest contract a shell module provides to `ElevasisSystemsProvider`. Key fields are `key`, optional `systemId`, optional `routePrefixes`, optional `capabilityIds`, optional `icon`, optional `sidebar`, and optional `sidebarWidth`. Graph bridge metadata is compatibility-only; new semantic bindings belong in the Organization Model System, ontology, navigation, and Resource descriptors.
 
@@ -29,13 +31,13 @@ description: Terminology disambiguation for Organization OS concepts used in the
 
 **Manifest** -- a runtime declaration for a feature or resource collection.
 
-**MembershipFeatureConfig** -- legacy per-member feature override config. Current System visibility should be authored through Organization Model System lifecycle/access metadata and resolved through provider compatibility layers for older consumers.
+**MembershipFeatureConfig** -- retired per-member feature override config. The migration is complete: access is resolved through the unified Access Model using Organization Model System lifecycle, role permissions, diagnostic allowlists, membership scope, and platform-admin bypass.
 
 **OrganizationModel** -- top-level semantic contract for an organization. Current primary fields include `version`, `domainMetadata`, `branding`, `navigation`, `ontology`, `systems`, `resources`, `topology`, `identity`, `customers`, `offerings`, `roles`, `goals`, `policies`, `statuses`, and `knowledge`. Legacy domain keys such as `sales`, `prospecting`, `projects`, `actions`, and `entities` remain compatibility inputs while projects migrate to System-owned ontology/config/resource contracts.
 
 **OrganizationModelSystemEntry** -- System node in `OrganizationModel.systems`. Primary authoring fields include `id`, `label`, `description`, `parentSystemId`, `systems`, `lifecycle`, `ui`, `requiresAdmin`, `devOnly`, `responsibleRoleId`, `governedByKnowledge`, `drivesGoals`, `actions`, `policies`, `ontology`, `config`, and `order`. `subsystems` and `content` are retained compatibility inputs for older projects and should not be used for new recursive Systems, schemas, catalogs, or config.
 
-**Provider / ElevasisSystemsProvider** -- runtime that registers System modules, resolves System access against the org model, projects sidebar navigation, and exposes shell helpers through `useElevasisSystems()`.
+**Provider / ElevasisSystemsProvider** -- runtime that registers System modules, resolves System lifecycle against the org model, projects sidebar navigation, and exposes shell helpers through `useElevasisSystems()`.
 
 **Resource** -- governance-only descriptor in `OrganizationModel.resources` for a workflow, agent, integration, or script. Runtime code derives `resourceId` and kind from the descriptor, then attaches executable behavior in operations.
 
@@ -62,13 +64,13 @@ description: Terminology disambiguation for Organization OS concepts used in the
 - `OrganizationModel`, `OrganizationModelSystemEntry`
 - `SystemEntry`, `ResourceEntry`
 - `resolveOrganizationModel`, `defineOrganizationModel`, `DEFAULT_ORGANIZATION_MODEL`
-- `MembershipFeatureConfig`
+- `AccessKeys`, `checkAccess`, `createAccessModel`
 - `DeploymentSpec`, `ResourceLink`, `ResourceCategory`
 
 **`@elevasis/ui`**
 
 - `SystemModule`
-- `SystemGuard`, `AdminGuard`, `ProtectedRoute`
+- `AccessGuard`, `ProtectedRoute`
 - `ElevasisSystemsProvider`, `ElevasisCoreProvider`, `useElevasisSystems`
 
 **External project source**

package/src/supabase/database.types.ts

@@ -2965,6 +2965,10 @@ export type Database = {
         Returns: boolean
       }
       current_user_is_platform_admin: { Args: never; Returns: boolean }
+      current_user_shares_org_with: {
+        Args: { other_user_id: string }
+        Returns: boolean
+      }
       current_user_supabase_id: { Args: never; Returns: string }
       detect_stalled_executions: { Args: never; Returns: undefined }
       execute_session_turn: {
@@ -2985,6 +2989,12 @@ export type Database = {
       get_platform_credential_kek: { Args: never; Returns: string }
       get_storage_org_id: { Args: { file_path: string }; Returns: string }
       get_workos_user_id: { Args: never; Returns: string }
+      has_org_access:
+        | {
+            Args: { action?: string; org_id: string; system_path: string }
+            Returns: boolean
+          }
+        | { Args: { action?: string; system_path: string }; Returns: boolean }
       has_org_permission: {
         Args: { org_id: string; perm_key: string }
         Returns: boolean