@elevasis/core 0.29.0 → 0.31.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/business/acquisition/api-schemas.test.ts

@@ -1,9 +1,73 @@
 import { describe, expect, it } from 'vitest'
-import {
-  LEAD_GEN_PIPELINE_DEFINITIONS,
-  type CrmPriorityRuleConfig,
-  type StatefulPipelineDefinition
-} from '../../organization-model/domains/sales'
+import { type CrmPriorityRuleConfig, type StatefulPipelineDefinition } from '../../organization-model/domains/sales'
+
+// Inline fixture for lead-gen pipeline stage/state validation tests.
+// The canonical constants live in @repo/elevasis-core; @repo/core cannot depend on it.
+const LEAD_GEN_PIPELINE_DEFINITIONS: Record<string, StatefulPipelineDefinition[]> = {
+  'acq.list-member': [
+    {
+      pipelineKey: 'lead-gen',
+      label: 'Lead Generation',
+      entityKey: 'acq.list-member',
+      stages: [
+        {
+          stageKey: 'outreach',
+          label: 'Outreach',
+          states: [
+            { stateKey: 'pending', label: 'Pending' },
+            { stateKey: 'personalized', label: 'Personalized' },
+            { stateKey: 'uploaded', label: 'Uploaded' },
+            { stateKey: 'interested', label: 'Interested' }
+          ]
+        },
+        {
+          stageKey: 'prospecting',
+          label: 'Prospecting',
+          states: [
+            { stateKey: 'pending', label: 'Pending' },
+            { stateKey: 'discovered', label: 'Discovered' },
+            { stateKey: 'verified', label: 'Verified' }
+          ]
+        },
+        { stageKey: 'qualification', label: 'Qualification', states: [{ stateKey: 'pending', label: 'Pending' }] }
+      ]
+    }
+  ],
+  'acq.list-company': [
+    {
+      pipelineKey: 'lead-gen',
+      label: 'Lead Generation',
+      entityKey: 'acq.list-company',
+      stages: [
+        {
+          stageKey: 'outreach',
+          label: 'Outreach',
+          states: [
+            { stateKey: 'pending', label: 'Pending' },
+            { stateKey: 'uploaded', label: 'Uploaded' }
+          ]
+        },
+        {
+          stageKey: 'prospecting',
+          label: 'Prospecting',
+          states: [
+            { stateKey: 'pending', label: 'Pending' },
+            { stateKey: 'populated', label: 'Populated' },
+            { stateKey: 'extracted', label: 'Extracted' }
+          ]
+        },
+        {
+          stageKey: 'qualification',
+          label: 'Qualification',
+          states: [
+            { stateKey: 'pending', label: 'Pending' },
+            { stateKey: 'qualified', label: 'Qualified' }
+          ]
+        }
+      ]
+    }
+  ]
+}
 import { DEFAULT_ORGANIZATION_MODEL } from '../../organization-model/defaults'
 import type { OrganizationModel } from '../../organization-model/types'
 import { CrmPriorityOverrideSchema, evaluateCrmDealPriority, resolveCrmPriorityRuleConfig } from './crm-priority'

package/src/business/acquisition/crm-state-actions.test.ts

@@ -1,8 +1,5 @@
 import { describe, expect, it } from 'vitest'
-import {
-  LEAD_GEN_PIPELINE_DEFINITIONS,
-  type StatefulPipelineDefinition
-} from '../../organization-model/domains/sales'
+import { type StatefulPipelineDefinition } from '../../organization-model/domains/sales'
 import { ActivityEventSchema } from './activity-events'
 import { DealStageSchema, TransitionItemRequestSchema } from './api-schemas'
 import { deriveActions } from './derive-actions'
@@ -188,8 +185,29 @@ describe('CRM stage and transition vocabulary contracts', () => {
     }
   })
 
-  it('accepts canonical lead-gen stage/state pairs in transition requests', () => {
-    for (const pipelineDefinitions of Object.values(LEAD_GEN_PIPELINE_DEFINITIONS)) {
+  it('accepts caller-supplied lead-gen stage/state pairs in transition requests', () => {
+    const leadGenPipelines: Record<string, StatefulPipelineDefinition[]> = {
+      'acq.list-member': [
+        {
+          pipelineKey: 'lead-gen',
+          label: 'Lead Gen',
+          entityKey: 'leadgen.contact',
+          stages: [
+            {
+              stageKey: 'outreach',
+              label: 'Outreach',
+              color: 'blue',
+              states: [
+                { stateKey: 'personalized', label: 'Personalized' },
+                { stateKey: 'contacted', label: 'Contacted' }
+              ]
+            }
+          ]
+        }
+      ]
+    }
+
+    for (const pipelineDefinitions of Object.values(leadGenPipelines)) {
       for (const pipeline of pipelineDefinitions) {
         for (const stage of pipeline.stages) {
           for (const state of stage.states) {