@elevasis/core 0.28.0 → 0.30.0

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

@@ -44,6 +44,7 @@ import {
   ListReadQuerySchema,
   ListRecordsQuerySchema,
   ListStatusSchema,
+  PipelineConfigSchema,
   PipelineStageSchema,
   ScrapingConfigSchema,
   TransitionDealStateRequestSchema,
@@ -54,7 +55,7 @@ import {
   UpdateListRequestSchema,
   UpdateListStatusRequestSchema
 } from './api-schemas'
-import { createBuildPlanSnapshotFromTemplateId } from './build-templates'
+import { createBuildPlanSnapshotFromTemplate } from './build-templates'
 import {
   compileBusinessOntologyValidationIndex,
   CRM_PIPELINE_CATALOG_ONTOLOGY_ID,
@@ -1168,17 +1169,32 @@ describe('PipelineStageSchema', () => {
 // ---------------------------------------------------------------------------
 
 describe('BuildPlanSnapshotSchema', () => {
-  const validSnapshot = createBuildPlanSnapshotFromTemplateId('dtc-subscription-apollo-clickup')
+  const validSnapshot = createBuildPlanSnapshotFromTemplate({
+    id: 'tenant-template',
+    label: 'Tenant Template',
+    steps: [
+      {
+        id: 'source-companies',
+        label: 'Companies found',
+        primaryEntity: 'company',
+        outputs: ['company'],
+        stageKey: 'populated',
+        dependencyMode: 'per-record-eligibility',
+        actionKey: 'lead-gen.company.source',
+        defaultBatchSize: 100,
+        maxBatchSize: 250
+      }
+    ]
+  })
 
   it('accepts a snapshot generated from a prospecting build template', () => {
-    expect(validSnapshot).not.toBeNull()
     expect(BuildPlanSnapshotSchema.safeParse(validSnapshot).success).toBe(true)
   })
 
   it('accepts custom non-empty step stage keys at the transport boundary', () => {
     const result = BuildPlanSnapshotSchema.safeParse({
       ...validSnapshot,
-      steps: [{ ...validSnapshot!.steps[0], stageKey: 'made-up-stage' }]
+      steps: [{ ...validSnapshot.steps[0], stageKey: 'made-up-stage' }]
     })
 
     expect(result.success).toBe(true)
@@ -1187,7 +1203,7 @@ describe('BuildPlanSnapshotSchema', () => {
   it('accepts custom non-empty action keys at the transport boundary', () => {
     const result = BuildPlanSnapshotSchema.safeParse({
       ...validSnapshot,
-      steps: [{ ...validSnapshot!.steps[0], actionKey: 'lead-gen.missing.action' }]
+      steps: [{ ...validSnapshot.steps[0], actionKey: 'lead-gen.missing.action' }]
     })
 
     expect(result.success).toBe(true)
@@ -1293,8 +1309,8 @@ describe('CreateListRequestSchema', () => {
     expect(result.success).toBe(true)
   })
 
-  it('rejects an unknown prospecting build template id', () => {
-    expect(CreateListRequestSchema.safeParse({ name: 'X', buildTemplateId: 'not-a-template' }).success).toBe(false)
+  it('accepts tenant-owned build template ids for API-layer membership validation', () => {
+    expect(CreateListRequestSchema.safeParse({ name: 'X', buildTemplateId: 'not-a-template' }).success).toBe(true)
   })
 
   it('rejects an invalid status', () => {
@@ -1311,10 +1327,20 @@ describe('CreateListRequestSchema', () => {
         name: 'SaaS List',
         scrapingConfig: { vertical: 'SaaS' },
         icp: { minReviewCount: 5 },
-        pipelineConfig: { stages: [] }
+        pipelineConfig: { stages: [], dataMode: 'mock' }
       }).success
     ).toBe(true)
   })
+
+  it('accepts create-time list-wide pipeline dataMode', () => {
+    const result = CreateListRequestSchema.safeParse({
+      name: 'DTC Demo',
+      pipelineConfig: { dataMode: 'mock' }
+    })
+
+    expect(result.success).toBe(true)
+    if (result.success) expect(result.data.pipelineConfig?.dataMode).toBe('mock')
+  })
 })
 
 // ---------------------------------------------------------------------------
@@ -1404,11 +1430,36 @@ describe('UpdateListConfigRequestSchema', () => {
     expect(UpdateListConfigRequestSchema.safeParse({ pipelineConfig: { stages: [] } }).success).toBe(true)
   })
 
+  it('accepts a data-mode-only pipelineConfig patch', () => {
+    const result = UpdateListConfigRequestSchema.safeParse({ pipelineConfig: { dataMode: 'live' } })
+
+    expect(result.success).toBe(true)
+    if (result.success) expect(result.data.pipelineConfig?.dataMode).toBe('live')
+  })
+
+  it('rejects invalid pipelineConfig dataMode values', () => {
+    expect(UpdateListConfigRequestSchema.safeParse({ pipelineConfig: { dataMode: 'demo' } }).success).toBe(false)
+  })
+
   it('rejects unknown fields (strict mode)', () => {
     expect(UpdateListConfigRequestSchema.safeParse({ scrapingConfig: {}, bogus: true }).success).toBe(false)
   })
 })
 
+// ---------------------------------------------------------------------------
+// PipelineConfigSchema
+// ---------------------------------------------------------------------------
+
+describe('PipelineConfigSchema', () => {
+  it.each(['mock', 'live'])('accepts list-wide dataMode "%s"', (dataMode) => {
+    expect(PipelineConfigSchema.safeParse({ dataMode }).success).toBe(true)
+  })
+
+  it('keeps dataMode optional for legacy stored configs', () => {
+    expect(PipelineConfigSchema.safeParse({ stages: [{ key: 'populated' }] }).success).toBe(true)
+  })
+})
+
 // ---------------------------------------------------------------------------
 // AddCompaniesToListRequestSchema / AddContactsToListRequestSchema
 // ---------------------------------------------------------------------------

package/src/business/acquisition/api-schemas.ts

@@ -1,7 +1,6 @@
 import { z } from 'zod'
 import { UuidSchema, NonEmptyStringSchema } from '../../platform/utils/validation'
 import { CredentialRequirementSchema, RecordColumnConfigSchema } from '../../organization-model/domains/prospecting'
-import { isProspectingBuildTemplateId } from './build-templates'
 export { CrmPriorityBucketKeySchema, CrmPriorityBucketOverrideSchema, CrmPriorityOverrideSchema } from './crm-priority'
 export type { CrmPriorityBucketOverride, CrmPriorityOverride, ResolvedCrmPriorityRuleConfig } from './crm-priority'
 
@@ -508,12 +507,15 @@ export const PipelineStageSchema = z.object({
   order: z.number().int().optional()
 })
 
+export const DataModeSchema = z.enum(['mock', 'live'])
+
 /**
  * Pipeline presentation contract stored in `acq_lists.pipeline_config` jsonb.
  * `stages[].key` validates against the catalog; the rest is presentation only.
  */
 export const PipelineConfigSchema = z.object({
-  stages: z.array(PipelineStageSchema).optional()
+  stages: z.array(PipelineStageSchema).optional(),
+  dataMode: DataModeSchema.optional()
 })
 
 export const BuildPlanSnapshotStepSchema = z
@@ -584,9 +586,10 @@ export const AcqListMetadataSchema = z
   })
   .catchall(z.unknown())
 
-export const ProspectingBuildTemplateIdSchema = z.string().trim().min(1).max(100).refine(isProspectingBuildTemplateId, {
-  message: 'buildTemplateId must match a known prospecting build template'
-})
+// Build-template IDs are tenant-owned OM catalog entries. Published core only
+// validates the transport shape; API/services validate membership against the
+// tenant's resolved Organization Model before creating or changing snapshots.
+export const ProspectingBuildTemplateIdSchema = z.string().trim().min(1).max(100)
 
 // ---------------------------------------------------------------------------
 // List telemetry / progress schemas
@@ -1360,6 +1363,7 @@ export const AcqListSchemas = {
   ScrapingConfig: ScrapingConfigSchema,
   IcpRubric: IcpRubricSchema,
   PipelineConfig: PipelineConfigSchema,
+  DataMode: DataModeSchema,
   PipelineStage: PipelineStageSchema,
   BuildPlanSnapshot: BuildPlanSnapshotSchema,
   BuildPlanSnapshotStep: BuildPlanSnapshotStepSchema,
@@ -1459,6 +1463,7 @@ export type ListStatus = z.infer<typeof ListStatusSchema>
 export type ScrapingConfig = z.infer<typeof ScrapingConfigSchema>
 export type IcpRubric = z.infer<typeof IcpRubricSchema>
 export type PipelineStage = z.infer<typeof PipelineStageSchema>
+export type DataMode = z.infer<typeof DataModeSchema>
 export type PipelineConfig = z.infer<typeof PipelineConfigSchema>
 export type BuildPlanSnapshotStep = z.infer<typeof BuildPlanSnapshotStepSchema>
 export type BuildPlanSnapshot = z.infer<typeof BuildPlanSnapshotSchema>