@elevasis/core 0.28.0 → 0.30.0

package/src/auth/__tests__/access-model.test.ts

@@ -0,0 +1,257 @@
+import { describe, expect, it } from 'vitest'
+import { AccessKeys, deriveAccessKeyCatalog } from '../access-keys'
+import { checkAccess } from '../access-model'
+import type { AccessContext } from '../access-model'
+import type { OrganizationModel } from '../../organization-model/types'
+
+const organizationModel = {
+  systems: {
+    sales: {
+      id: 'sales',
+      label: 'Sales',
+      lifecycle: 'active',
+      order: 10,
+      systems: {
+        crm: {
+          id: 'crm',
+          label: 'CRM',
+          lifecycle: 'active',
+          order: 10
+        }
+      }
+    },
+    operations: {
+      id: 'operations',
+      label: 'Operations',
+      lifecycle: 'beta',
+      order: 20
+    },
+    drafts: {
+      id: 'drafts',
+      label: 'Drafts',
+      lifecycle: 'draft',
+      order: 30
+    },
+    retired: {
+      id: 'retired',
+      label: 'Retired',
+      lifecycle: 'deprecated',
+      order: 40
+    },
+    missingLifecycle: {
+      id: 'missingLifecycle',
+      label: 'Missing Lifecycle',
+      order: 50
+    }
+  }
+} as OrganizationModel
+
+const baseContext: AccessContext = {
+  organizationId: 'org-1',
+  organizationModel,
+  membership: {
+    id: 'membership-1',
+    organizationId: 'org-1',
+    effectivePermissions: ['sales.crm.manage']
+  },
+  profile: {
+    id: 'user-1',
+    isPlatformAdmin: false
+  }
+}
+
+function context(overrides: Partial<AccessContext> = {}): AccessContext {
+  return { ...baseContext, ...overrides }
+}
+
+describe('checkAccess', () => {
+  it('allows active system view access by lifecycle alone', () => {
+    expect(checkAccess('sales.crm', context())).toEqual({
+      allowed: true,
+      restrictedBy: null,
+      reason: 'allowed'
+    })
+  })
+
+  it('denies unknown keys through catalog validation', () => {
+    expect(checkAccess('unknown.system', context())).toEqual({
+      allowed: false,
+      restrictedBy: 'catalog',
+      reason: 'unknown-access-key'
+    })
+  })
+
+  it('denies missing membership before evaluating lifecycle or permissions', () => {
+    expect(checkAccess('sales.crm', context({ membership: null }))).toEqual({
+      allowed: false,
+      restrictedBy: 'membership',
+      reason: 'missing-membership'
+    })
+  })
+
+  it('denies organization mismatches', () => {
+    expect(
+      checkAccess(
+        'sales.crm',
+        context({
+          membership: { id: 'membership-2', organizationId: 'org-2', effectivePermissions: ['sales.crm.manage'] }
+        })
+      )
+    ).toEqual({
+      allowed: false,
+      restrictedBy: 'membership',
+      reason: 'organization-mismatch'
+    })
+  })
+
+  it('denies draft, deprecated, archived, and missing lifecycle systems', () => {
+    const archivedModel = {
+      systems: {
+        archived: {
+          id: 'archived',
+          label: 'Archived',
+          lifecycle: 'archived',
+          order: 10
+        }
+      }
+    } as OrganizationModel
+
+    expect(checkAccess('drafts', context())).toMatchObject({
+      allowed: false,
+      restrictedBy: 'system-lifecycle',
+      reason: 'system-not-active'
+    })
+    expect(checkAccess('retired', context())).toMatchObject({
+      allowed: false,
+      restrictedBy: 'system-lifecycle',
+      reason: 'system-not-active'
+    })
+    expect(checkAccess('missingLifecycle', context())).toMatchObject({
+      allowed: false,
+      restrictedBy: 'system-lifecycle',
+      reason: 'system-not-active'
+    })
+    expect(checkAccess('archived', context({ organizationModel: archivedModel }))).toMatchObject({
+      allowed: false,
+      restrictedBy: 'system-lifecycle',
+      reason: 'system-not-active'
+    })
+  })
+
+  it('allows beta systems only when beta access or development mode is enabled', () => {
+    expect(checkAccess('operations', context())).toEqual({
+      allowed: false,
+      restrictedBy: 'system-lifecycle',
+      reason: 'system-not-active'
+    })
+
+    expect(checkAccess('operations', context({ betaAccessEnabled: true }))).toEqual({
+      allowed: true,
+      restrictedBy: null,
+      reason: 'allowed'
+    })
+
+    expect(checkAccess('operations', context({ isDevelopment: true }))).toEqual({
+      allowed: true,
+      restrictedBy: null,
+      reason: 'allowed'
+    })
+  })
+
+  it('requires matching role permission for manage when permissions are supplied', () => {
+    expect(checkAccess({ systemPath: 'sales.crm', action: 'manage' }, context())).toEqual({
+      allowed: true,
+      restrictedBy: null,
+      reason: 'allowed'
+    })
+
+    expect(
+      checkAccess(
+        { systemPath: 'sales.crm', action: 'manage' },
+        context({
+          membership: { id: 'membership-1', organizationId: 'org-1', effectivePermissions: [] }
+        })
+      )
+    ).toEqual({
+      allowed: false,
+      restrictedBy: 'role-permission',
+      reason: 'role-permission-denied'
+    })
+  })
+
+  it('requires explicit role permissions for permission-only access keys', () => {
+    expect(
+      checkAccess(
+        AccessKeys.organizationManage,
+        context({
+          membership: { id: 'membership-1', organizationId: 'org-1', effectivePermissions: ['org.manage'] }
+        })
+      )
+    ).toEqual({
+      allowed: true,
+      restrictedBy: null,
+      reason: 'allowed'
+    })
+
+    expect(checkAccess(AccessKeys.organizationManage, context())).toEqual({
+      allowed: false,
+      restrictedBy: 'role-permission',
+      reason: 'role-permission-denied'
+    })
+  })
+
+  it('checks diagnostic keys against the runtime diagnostic allowlist', () => {
+    expect(checkAccess(AccessKeys.operationsOverview, context())).toEqual({
+      allowed: false,
+      restrictedBy: 'diagnostic-allowlist',
+      reason: 'diagnostic-key-not-allowed'
+    })
+
+    expect(
+      checkAccess(
+        AccessKeys.operationsOverview,
+        context({ diagnosticAllowlist: [AccessKeys.operationsOverview.systemPath] })
+      )
+    ).toEqual({
+      allowed: true,
+      restrictedBy: null,
+      reason: 'allowed'
+    })
+  })
+
+  it('keeps diagnostic catalog validation separate from runtime diagnostic allowlist', () => {
+    const accessCatalog = deriveAccessKeyCatalog(organizationModel, { diagnosticKeys: ['diagnostic.custom'] })
+
+    expect(
+      checkAccess('diagnostic.custom', context({ accessCatalog, diagnosticAllowlist: ['diagnostic.custom'] }))
+    ).toEqual({
+      allowed: true,
+      restrictedBy: null,
+      reason: 'allowed'
+    })
+
+    expect(checkAccess('diagnostic.not-cataloged', context({ diagnosticAllowlist: ['diagnostic.not-cataloged'] }))).toEqual({
+      allowed: false,
+      restrictedBy: 'catalog',
+      reason: 'unknown-access-key'
+    })
+  })
+
+  it('centralizes platform-admin bypass with the platform-admin-bypass reason', () => {
+    expect(
+      checkAccess('unknown.system', context({ profile: { id: 'admin', isPlatformAdmin: true }, membership: null }))
+    ).toEqual({
+      allowed: true,
+      restrictedBy: null,
+      reason: 'platform-admin-bypass'
+    })
+  })
+
+  it('denies platformAdmin special-case for non-platform admins', () => {
+    expect(checkAccess('platformAdmin', context())).toEqual({
+      allowed: false,
+      restrictedBy: 'role-permission',
+      reason: 'role-permission-denied'
+    })
+  })
+})

package/src/auth/__tests__/access-test-fixtures.ts

@@ -0,0 +1,50 @@
+import type { OrganizationModel } from '../../organization-model/types'
+
+export const accessTestOrganizationModel = {
+  systems: {
+    platform: {
+      id: 'platform',
+      label: 'Platform',
+      lifecycle: 'active',
+      order: 10
+    },
+    sales: {
+      id: 'sales',
+      label: 'Sales',
+      lifecycle: 'active',
+      order: 20,
+      systems: {
+        crm: {
+          id: 'crm',
+          label: 'CRM',
+          lifecycle: 'active',
+          order: 10
+        },
+        'lead-gen': {
+          id: 'lead-gen',
+          label: 'Lead Gen',
+          lifecycle: 'active',
+          order: 20
+        }
+      }
+    },
+    projects: {
+      id: 'projects',
+      label: 'Projects',
+      lifecycle: 'active',
+      order: 30
+    },
+    clients: {
+      id: 'clients',
+      label: 'Clients',
+      lifecycle: 'active',
+      order: 40
+    },
+    seo: {
+      id: 'seo',
+      label: 'SEO',
+      lifecycle: 'active',
+      order: 50
+    }
+  }
+} as unknown as OrganizationModel

package/src/auth/__tests__/key-catalog-drift.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from 'vitest'
+
+import { AccessKeys, deriveAccessKeyCatalog, findAccessCatalogEntry, normalizeAccessKey } from '../access-keys'
+import { accessTestOrganizationModel } from './access-test-fixtures'
+import { scanAccessKeyUsages } from './access-key-scan'
+
+describe('access key catalog drift', () => {
+  it('keeps runtime literal access keys in the derived catalog', () => {
+    const catalog = deriveAccessKeyCatalog(accessTestOrganizationModel)
+    const usages = scanAccessKeyUsages()
+
+    const unknownLiterals = usages.stringLiterals
+      .map((usage) => {
+        const key = normalizeAccessKey(usage.key)
+        return findAccessCatalogEntry(catalog, key) === undefined
+          ? `${usage.file}: ${JSON.stringify(usage.key)}`
+          : null
+      })
+      .filter((usage): usage is string => usage !== null)
+
+    expect(unknownLiterals).toEqual([])
+  })
+
+  it('keeps runtime AccessKeys references backed by exported symbols', () => {
+    const usages = scanAccessKeyUsages()
+    const exportedSymbols = new Set(Object.keys(AccessKeys))
+    const unknownSymbols = usages.accessKeySymbols
+      .filter((usage) => !exportedSymbols.has(usage.symbol))
+      .map((usage) => `${usage.file}: AccessKeys.${usage.symbol}`)
+
+    expect(unknownSymbols).toEqual([])
+  })
+})

package/src/auth/__tests__/platform-admin-bypass-parity.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, it } from 'vitest'
+
+import { AccessKeys } from '../access-keys'
+import { checkAccess, createAccessModel, type AccessContext } from '../access-model'
+import { accessTestOrganizationModel } from './access-test-fixtures'
+
+const bypassAnswer = {
+  allowed: true,
+  restrictedBy: null,
+  reason: 'platform-admin-bypass'
+} as const
+
+const baseContext: AccessContext = {
+  organizationId: 'org-1',
+  organizationModel: accessTestOrganizationModel,
+  membership: {
+    id: 'membership-1',
+    organizationId: 'org-1',
+    effectivePermissions: []
+  },
+  profile: {
+    id: 'user-1',
+    isPlatformAdmin: false
+  }
+}
+
+describe('platform admin bypass parity', () => {
+  it('short-circuits unknown keys before catalog and membership checks', () => {
+    expect(
+      checkAccess('unknown.system', {
+        ...baseContext,
+        membership: null,
+        profile: { id: 'admin', isPlatformAdmin: true }
+      })
+    ).toEqual(bypassAnswer)
+  })
+
+  it('supports both camelCase and database-shaped platform-admin profile flags', () => {
+    expect(
+      checkAccess('unknown.system', {
+        ...baseContext,
+        membership: null,
+        profile: { id: 'admin', is_platform_admin: true }
+      })
+    ).toEqual(bypassAnswer)
+  })
+
+  it('returns the same bypass answer through createAccessModel', () => {
+    const accessModel = createAccessModel(accessTestOrganizationModel)
+
+    expect(
+      accessModel.checkAccess('unknown.system', {
+        ...baseContext,
+        membership: null,
+        profile: { id: 'admin', isPlatformAdmin: true }
+      })
+    ).toEqual(bypassAnswer)
+  })
+
+  it('does not grant platformAdmin access to non-platform admins', () => {
+    expect(checkAccess(AccessKeys.platformAdmin, baseContext)).toEqual({
+      allowed: false,
+      restrictedBy: 'role-permission',
+      reason: 'role-permission-denied'
+    })
+  })
+})

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)
+}