@elevasis/core 0.29.0 → 0.30.0

package/src/auth/__tests__/access-key-coverage.test.ts

@@ -0,0 +1,42 @@
+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'
+
+const INTENTIONALLY_UNCONSUMED_ACCESS_KEYS = new Set([
+  'secretsManage',
+  'operationsManage',
+  'acquisitionManage',
+  'projectsManage',
+  'clientsManage',
+  'operationsRecentExecutions'
+])
+
+describe('access key coverage', () => {
+  it('keeps every runtime consumer key present in the catalog', () => {
+    const catalog = deriveAccessKeyCatalog(accessTestOrganizationModel)
+    const usages = scanAccessKeyUsages()
+    const consumerKeys = [
+      ...usages.stringLiterals.map((usage) => ({ file: usage.file, key: normalizeAccessKey(usage.key) })),
+      ...usages.accessKeySymbols.map((usage) => ({
+        file: usage.file,
+        key: AccessKeys[usage.symbol as keyof typeof AccessKeys]
+      }))
+    ]
+
+    const missingCatalogEntries = consumerKeys
+      .filter((usage) => findAccessCatalogEntry(catalog, usage.key) === undefined)
+      .map((usage) => `${usage.file}: ${usage.key.systemPath}:${usage.key.action}`)
+
+    expect(missingCatalogEntries).toEqual([])
+  })
+
+  it('keeps exported static AccessKeys either consumed or explicitly reserved', () => {
+    const usages = scanAccessKeyUsages()
+    const consumedSymbols = new Set(usages.accessKeySymbols.map((usage) => usage.symbol))
+    const unconsumedSymbols = Object.keys(AccessKeys).filter((symbol) => !consumedSymbols.has(symbol))
+
+    expect(unconsumedSymbols).toEqual([...INTENTIONALLY_UNCONSUMED_ACCESS_KEYS])
+  })
+})

package/src/auth/__tests__/access-key-scan.ts

@@ -0,0 +1,117 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { dirname, join, relative } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import type { AccessKeyInput } from '../access-keys'
+
+export interface AccessKeyUsage {
+  file: string
+  key: AccessKeyInput
+}
+
+export interface AccessKeySymbolUsage {
+  file: string
+  symbol: string
+}
+
+const repoRoot = findRepoRoot(dirname(fileURLToPath(import.meta.url)))
+
+const RUNTIME_SOURCE_ROOTS = [
+  join(repoRoot, 'apps', 'command-center', 'src'),
+  join(repoRoot, 'packages', 'ui', 'src'),
+  join(repoRoot, 'apps', 'api', 'src'),
+  join(repoRoot, 'external', '_template', 'ui', 'src')
+]
+
+const STRING_LITERAL_PATTERNS = [
+  /<AccessGuard\b[\s\S]*?\baccessKey\s*=\s*["']([^"']+)["']/g,
+  /<AccessGuard\b[\s\S]*?\baccessKey\s*=\s*\{\s*["']([^"']+)["']\s*\}/g,
+  /\buseAccess\(\s*["']([^"']+)["']\s*\)/g,
+  /\brequireAccess\(\s*["']([^"']+)["']\s*[,)]/g
+]
+
+const ACCESS_KEYS_PATTERN = /\bAccessKeys\.([A-Za-z_$][A-Za-z0-9_$]*)\b/g
+
+function findRepoRoot(startDirectory: string): string {
+  let current = startDirectory
+
+  while (current !== dirname(current)) {
+    if (existsSync(join(current, 'pnpm-workspace.yaml'))) return current
+    current = dirname(current)
+  }
+
+  throw new Error('Could not find monorepo root from access-key scan test')
+}
+
+function isRuntimeSourceFile(file: string): boolean {
+  if (!/\.(ts|tsx)$/.test(file)) return false
+  if (file.includes(`${join('', '__tests__').slice(1)}`)) return false
+  if (file.includes('__tests__')) return false
+  if (/\.(test|spec)\.(ts|tsx)$/.test(file)) return false
+  return !file.endsWith('routeTree.gen.ts')
+}
+
+function listRuntimeSourceFiles(directory: string): string[] {
+  if (!existsSync(directory)) return []
+
+  const entries = readdirSync(directory, { withFileTypes: true })
+  const files: string[] = []
+
+  for (const entry of entries) {
+    const entryPath = join(directory, entry.name)
+
+    if (entry.isDirectory()) {
+      if (['node_modules', 'dist', '.next', 'coverage'].includes(entry.name)) continue
+      files.push(...listRuntimeSourceFiles(entryPath))
+      continue
+    }
+
+    if (isRuntimeSourceFile(entryPath)) files.push(entryPath)
+  }
+
+  return files
+}
+
+function relativePath(file: string): string {
+  return relative(repoRoot, file).replaceAll('\\', '/')
+}
+
+function collectMatches<T>(
+  content: string,
+  pattern: RegExp,
+  build: (match: RegExpExecArray) => T
+): T[] {
+  const matches: T[] = []
+  pattern.lastIndex = 0
+
+  for (let match = pattern.exec(content); match !== null; match = pattern.exec(content)) {
+    matches.push(build(match))
+  }
+
+  return matches
+}
+
+export function scanAccessKeyUsages(): {
+  stringLiterals: AccessKeyUsage[]
+  accessKeySymbols: AccessKeySymbolUsage[]
+} {
+  const stringLiterals: AccessKeyUsage[] = []
+  const accessKeySymbols: AccessKeySymbolUsage[] = []
+
+  for (const sourceRoot of RUNTIME_SOURCE_ROOTS) {
+    for (const file of listRuntimeSourceFiles(sourceRoot)) {
+      const content = readFileSync(file, 'utf8')
+      const path = relativePath(file)
+
+      for (const pattern of STRING_LITERAL_PATTERNS) {
+        stringLiterals.push(...collectMatches(content, pattern, (match) => ({ file: path, key: match[1] })))
+      }
+
+      accessKeySymbols.push(
+        ...collectMatches(content, ACCESS_KEYS_PATTERN, (match) => ({ file: path, symbol: match[1] }))
+      )
+    }
+  }
+
+  return { stringLiterals, accessKeySymbols }
+}

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

@@ -0,0 +1,81 @@
+import { describe, expect, it } from 'vitest'
+import {
+  AccessKeys,
+  DIAGNOSTIC_VIEW_ACCESS_KEYS,
+  PLATFORM_ADMIN_ACCESS_KEY,
+  deriveAccessKeyCatalog,
+  findAccessCatalogEntry,
+  listAccessKeys,
+  normalizeAccessKey
+} from '../access-keys'
+import type { OrganizationModel } from '../../organization-model/types'
+
+const model = {
+  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: 'active',
+      order: 20
+    }
+  }
+} as OrganizationModel
+
+describe('access keys', () => {
+  it('normalizes string shorthand to view access keys', () => {
+    expect(normalizeAccessKey('sales.crm')).toEqual({ systemPath: 'sales.crm', action: 'view' })
+    expect(normalizeAccessKey({ systemPath: 'sales.crm' })).toEqual({ systemPath: 'sales.crm', action: 'view' })
+  })
+
+  it('normalizes platformAdmin string shorthand to the platform special-case key', () => {
+    expect(normalizeAccessKey('platformAdmin')).toEqual(AccessKeys.platformAdmin)
+    expect(normalizeAccessKey('platformAdmin').systemPath).toBe(PLATFORM_ADMIN_ACCESS_KEY)
+  })
+
+  it('derives view and manage access keys from nested Organization Model systems', () => {
+    const catalog = deriveAccessKeyCatalog(model)
+    const keys = listAccessKeys(catalog)
+
+    expect(keys).toContainEqual({ systemPath: 'sales', action: 'view' })
+    expect(keys).toContainEqual({ systemPath: 'sales.crm', action: 'view' })
+    expect(keys).toContainEqual({ systemPath: 'sales.crm', action: 'manage' })
+    expect(keys).toContainEqual({ systemPath: 'operations', action: 'manage' })
+  })
+
+  it('includes diagnostic allowlist keys and platformAdmin in the catalog', () => {
+    const catalog = deriveAccessKeyCatalog(model)
+
+    for (const systemPath of DIAGNOSTIC_VIEW_ACCESS_KEYS) {
+      expect(findAccessCatalogEntry(catalog, { systemPath, action: 'view' })?.source).toBe('diagnostic')
+    }
+
+    expect(findAccessCatalogEntry(catalog, AccessKeys.platformAdmin)?.source).toBe('platform')
+  })
+
+  it('includes permission-only access keys with their legacy role-permission mapping', () => {
+    const catalog = deriveAccessKeyCatalog(model)
+
+    expect(findAccessCatalogEntry(catalog, AccessKeys.organizationManage)).toMatchObject({
+      source: 'permission',
+      rolePermission: 'org.manage'
+    })
+    expect(findAccessCatalogEntry(catalog, AccessKeys.membersManage)).toMatchObject({
+      source: 'permission',
+      rolePermission: 'members.manage'
+    })
+  })
+})

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