@elevasis/core 0.11.0 → 0.11.2

package/src/auth/multi-tenancy/memberships/api-schemas.ts

@@ -1,126 +1,142 @@
-/**
- * Memberships Domain - Zod Validation Schemas
- *
- * Validation schemas for membership management endpoints.
- * Includes request bodies, query params, and path params.
- *
- * Security:
- * - All schemas use .strict() to prevent mass assignment attacks
- * - UUID validation prevents invalid references
- * - Role enum validation prevents privilege escalation
- * - organizationId never accepted in body (from JWT when needed)
- */
-
-import { z } from 'zod'
-
-// ============================================================================
-// Shared Schemas
-// ============================================================================
-
-/**
- * Membership role validation
- * Restricts to valid role slugs only
- *
- * Security: Prevents privilege escalation by limiting role values
- */
-export const MembershipRoleSchema = z.enum(['admin', 'member'])
-
-/**
- * Membership status validation
- * Note: Database constraint only allows 'active' | 'inactive'
- */
-export const MembershipStatusSchema = z.enum(['active', 'inactive'])
-
-// ============================================================================
-// Path Parameters
-// ============================================================================
-
-/**
- * Validate membership ID in URL path
- * Used by: GET/PUT/DELETE /memberships/:id
- */
-export const MembershipIdParamSchema = z
-  .object({
-    id: z.string().min(1) // WorkOS membership IDs can be various formats
-  })
-  .strict()
-
-// ============================================================================
-// Request Bodies
-// ============================================================================
-
-/**
- * Create new membership
- * POST /memberships
- *
- * Security:
- * - userId must be valid (string format for WorkOS)
- * - organizationId must be valid (string format for WorkOS)
- * - roleSlug enum prevents privilege escalation
- * - Strict mode prevents injection
- */
-export const CreateMembershipSchema = z
-  .object({
-    userId: z.string().min(1),
-    organizationId: z.string().min(1),
-    roleSlug: MembershipRoleSchema.default('member')
-  })
-  .strict()
-
-/**
- * Update membership role
- * PUT /memberships/:id
- *
- * Security:
- * - Only roleSlug can be updated
- * - Enum validation prevents privilege escalation
- */
-export const UpdateMembershipSchema = z
-  .object({
-    roleSlug: MembershipRoleSchema
-  })
-  .strict()
-
-// ============================================================================
-// Query Parameters
-// ============================================================================
-
-/**
- * List memberships with filters
- * GET /memberships
- *
- * Filters:
- * - userId: Filter by user
- * - organizationId: Filter by organization
- *
- * Security:
- * - Requires at least one filter parameter
- * - String IDs validated for WorkOS format
- */
-export const ListMembershipsQuerySchema = z
-  .object({
-    userId: z.string().optional(),
-    organizationId: z.string().optional(),
-    limit: z.coerce.number().int().min(1).max(100).optional(),
-    before: z.string().optional(), // WorkOS pagination cursor
-    after: z.string().optional()   // WorkOS pagination cursor
-  })
-  .strict()
-  .refine(
-    (data) => data.userId || data.organizationId,
-    {
-      message: 'Either userId or organizationId must be provided'
-    }
-  )
-
-// ============================================================================
-// TypeScript Type Exports
-// ============================================================================
-
-// Export inferred types for use in route handlers
-export type CreateMembershipInput = z.infer<typeof CreateMembershipSchema>
-export type UpdateMembershipInput = z.infer<typeof UpdateMembershipSchema>
-export type ListMembershipsQuery = z.infer<typeof ListMembershipsQuerySchema>
-export type MembershipIdParam = z.infer<typeof MembershipIdParamSchema>
-export type MembershipRole = z.infer<typeof MembershipRoleSchema>
-export type MembershipStatus = z.infer<typeof MembershipStatusSchema>
+/**
+ * Memberships Domain - Zod Validation Schemas
+ *
+ * Validation schemas for membership management endpoints.
+ * Includes request bodies, query params, and path params.
+ *
+ * Security:
+ * - All schemas use .strict() to prevent mass assignment attacks
+ * - UUID validation prevents invalid references
+ * - Role enum validation prevents privilege escalation
+ * - organizationId never accepted in body (from JWT when needed)
+ */
+
+import { z } from 'zod'
+
+// ============================================================================
+// Shared Schemas
+// ============================================================================
+
+/**
+ * Membership role validation
+ * Restricts to valid role slugs only
+ *
+ * Security: Prevents privilege escalation by limiting role values
+ */
+export const MembershipRoleSchema = z.enum(['admin', 'member'])
+
+/**
+ * Membership status validation
+ * Note: Database constraint only allows 'active' | 'inactive'
+ */
+export const MembershipStatusSchema = z.enum(['active', 'inactive'])
+
+// ============================================================================
+// Path Parameters
+// ============================================================================
+
+/**
+ * Validate membership ID in URL path
+ * Used by: GET/PUT/DELETE /memberships/:id
+ */
+export const MembershipIdParamSchema = z
+  .object({
+    id: z.string().min(1) // WorkOS membership IDs can be various formats
+  })
+  .strict()
+
+/**
+ * Validate organization ID (Supabase UUID) in URL path
+ * Used by: GET /memberships/my-permissions/:orgId
+ */
+export const OrgIdParamSchema = z
+  .object({
+    orgId: z.string().uuid()
+  })
+  .strict()
+
+/**
+ * Response shape for GET /memberships/my-permissions/:orgId
+ */
+export const MyOrgPermissionsResponseSchema = z.object({
+  permissions: z.array(z.string())
+})
+
+// ============================================================================
+// Request Bodies
+// ============================================================================
+
+/**
+ * Create new membership
+ * POST /memberships
+ *
+ * Security:
+ * - userId must be valid (string format for WorkOS)
+ * - organizationId must be valid (string format for WorkOS)
+ * - roleSlug enum prevents privilege escalation
+ * - Strict mode prevents injection
+ */
+export const CreateMembershipSchema = z
+  .object({
+    userId: z.string().min(1),
+    organizationId: z.string().min(1),
+    roleSlug: MembershipRoleSchema.default('member')
+  })
+  .strict()
+
+/**
+ * Update membership role
+ * PUT /memberships/:id
+ *
+ * Security:
+ * - Only roleSlug can be updated
+ * - Enum validation prevents privilege escalation
+ */
+export const UpdateMembershipSchema = z
+  .object({
+    roleSlug: MembershipRoleSchema
+  })
+  .strict()
+
+// ============================================================================
+// Query Parameters
+// ============================================================================
+
+/**
+ * List memberships with filters
+ * GET /memberships
+ *
+ * Filters:
+ * - userId: Filter by user
+ * - organizationId: Filter by organization
+ *
+ * Security:
+ * - Requires at least one filter parameter
+ * - String IDs validated for WorkOS format
+ */
+export const ListMembershipsQuerySchema = z
+  .object({
+    userId: z.string().optional(),
+    organizationId: z.string().optional(),
+    limit: z.coerce.number().int().min(1).max(100).optional(),
+    before: z.string().optional(), // WorkOS pagination cursor
+    after: z.string().optional() // WorkOS pagination cursor
+  })
+  .strict()
+  .refine((data) => data.userId || data.organizationId, {
+    message: 'Either userId or organizationId must be provided'
+  })
+
+// ============================================================================
+// TypeScript Type Exports
+// ============================================================================
+
+// Export inferred types for use in route handlers
+export type CreateMembershipInput = z.infer<typeof CreateMembershipSchema>
+export type UpdateMembershipInput = z.infer<typeof UpdateMembershipSchema>
+export type ListMembershipsQuery = z.infer<typeof ListMembershipsQuerySchema>
+export type MembershipIdParam = z.infer<typeof MembershipIdParamSchema>
+export type MembershipRole = z.infer<typeof MembershipRoleSchema>
+export type MembershipStatus = z.infer<typeof MembershipStatusSchema>
+export type OrgIdParam = z.infer<typeof OrgIdParamSchema>
+export type MyOrgPermissionsResponse = z.infer<typeof MyOrgPermissionsResponseSchema>

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

@@ -1,22 +1,26 @@
-/**
- * Membership types - browser-safe exports only
- * For WorkOS types and transforms, use @repo/core/server
- */
-export * from './membership'
-export * from './supabase'
-
-// Validation schemas
-export {
-  CreateMembershipSchema,
-  UpdateMembershipSchema,
-  ListMembershipsQuerySchema,
-  MembershipIdParamSchema,
-  MembershipRoleSchema,
-  MembershipStatusSchema,
-  type CreateMembershipInput,
-  type UpdateMembershipInput,
-  type ListMembershipsQuery,
-  type MembershipIdParam,
-  type MembershipRole,
-  type MembershipStatus
-} from './api-schemas'
+/**
+ * Membership types - browser-safe exports only
+ * For WorkOS types and transforms, use @repo/core/server
+ */
+export * from './membership'
+export * from './supabase'
+
+// Validation schemas
+export {
+  CreateMembershipSchema,
+  UpdateMembershipSchema,
+  ListMembershipsQuerySchema,
+  MembershipIdParamSchema,
+  MembershipRoleSchema,
+  MembershipStatusSchema,
+  OrgIdParamSchema,
+  MyOrgPermissionsResponseSchema,
+  type CreateMembershipInput,
+  type UpdateMembershipInput,
+  type ListMembershipsQuery,
+  type MembershipIdParam,
+  type MembershipRole,
+  type MembershipStatus,
+  type OrgIdParam,
+  type MyOrgPermissionsResponse
+} from './api-schemas'

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

@@ -0,0 +1,42 @@
+import { describe, it, expect } from 'vitest'
+import { PERMISSIONS, PERMISSION_CATALOG, isPermissionKey } from './permissions'
+
+describe('permissions catalog', () => {
+  const permissionValues = Object.values(PERMISSIONS)
+  const catalogKeys = PERMISSION_CATALOG.map((p) => p.key)
+
+  it('every PERMISSIONS value appears as a key in PERMISSION_CATALOG', () => {
+    for (const value of permissionValues) {
+      expect(catalogKeys).toContain(value)
+    }
+  })
+
+  it('every PERMISSION_CATALOG key exists as a value in PERMISSIONS', () => {
+    for (const key of catalogKeys) {
+      expect(permissionValues).toContain(key)
+    }
+  })
+
+  it('every catalog entry has a non-empty description and a boolean isOrgGrantable', () => {
+    for (const entry of PERMISSION_CATALOG) {
+      expect(typeof entry.description).toBe('string')
+      expect(entry.description.trim().length).toBeGreaterThan(0)
+      expect(typeof entry.isOrgGrantable).toBe('boolean')
+    }
+  })
+
+  it('catalog has no duplicate keys', () => {
+    const seen = new Set<string>()
+    for (const key of catalogKeys) {
+      expect(seen.has(key), `duplicate catalog key: ${key}`).toBe(false)
+      seen.add(key)
+    }
+  })
+
+  it('isPermissionKey returns true for every catalog key and false for unknown strings', () => {
+    for (const key of catalogKeys) {
+      expect(isPermissionKey(key)).toBe(true)
+    }
+    expect(isPermissionKey('not.a.permission')).toBe(false)
+  })
+})

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

@@ -0,0 +1,104 @@
+/**
+ * Canonical permission catalog.
+ *
+ * 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))
+ *
+ * The DB table `org_rol_permissions` mirrors this constant. Reconciliation
+ * runs at API boot (insert-or-update only — never auto-delete; see the
+ * deletion runbook in the auth-role-system-redesign doc).
+ *
+ * Adding a permission:
+ *   1. Add an entry below.
+ *   2. Add a row to the migration / via reconcilePermissionCatalog at boot.
+ *   3. Reference it in RLS / middleware as needed.
+ *   4. Optionally grant it to one or more system roles in org_rol_grants.
+ *
+ * Removing a permission: follow the deletion runbook — never just delete
+ * the entry. Existing role grants and policy references must be cleared first.
+ */
+
+export const PERMISSIONS = {
+  ORG_READ: 'org.read',
+  ORG_MANAGE: 'org.manage',
+  ORG_DELETE: 'org.delete',
+  MEMBERS_MANAGE: 'members.manage',
+  ROLES_MANAGE: 'roles.manage',
+  SECRETS_MANAGE: 'secrets.manage',
+  OPERATIONS_READ: 'operations.read',
+  OPERATIONS_MANAGE: 'operations.manage',
+  WORK_MANAGE: 'work.manage'
+} as const
+
+export type PermissionKey = (typeof PERMISSIONS)[keyof typeof PERMISSIONS]
+
+/**
+ * Static metadata for each permission. Mirrored into org_rol_permissions on
+ * boot reconciliation. is_org_grantable=false means the permission is reserved
+ * to system roles only — custom roles cannot include it (privilege-escalation guard).
+ */
+export interface PermissionDescriptor {
+  key: PermissionKey
+  description: string
+  isOrgGrantable: boolean
+}
+
+export const PERMISSION_CATALOG: readonly PermissionDescriptor[] = [
+  {
+    key: 'org.read',
+    description: 'Read organization profile and listings',
+    isOrgGrantable: true
+  },
+  {
+    key: 'org.manage',
+    description: 'Update organization settings',
+    isOrgGrantable: false
+  },
+  {
+    key: 'org.delete',
+    description: 'Delete the organization (owner-only)',
+    isOrgGrantable: false
+  },
+  {
+    key: 'members.manage',
+    description: 'Invite, remove, and reassign roles for members',
+    isOrgGrantable: false
+  },
+  {
+    key: 'roles.manage',
+    description: 'Grant or revoke privileged system roles (owner, admin) within the organization',
+    isOrgGrantable: false
+  },
+  {
+    key: 'secrets.manage',
+    description: 'Create, update, and delete API keys and credentials',
+    isOrgGrantable: false
+  },
+  {
+    key: 'operations.read',
+    description: 'View executions, sessions, schedules, and command queue',
+    isOrgGrantable: true
+  },
+  {
+    key: 'operations.manage',
+    description: 'Run and modify executions, sessions, schedules, queue',
+    isOrgGrantable: true
+  },
+  {
+    key: 'work.manage',
+    description: 'Create and edit business-domain records (acq_*, prj_*)',
+    isOrgGrantable: true
+  }
+] as const
+
+const PERMISSION_KEY_SET: ReadonlySet<string> = new Set(PERMISSION_CATALOG.map((p) => p.key))
+
+/**
+ * Type guard. Use at trust boundaries (request input, third-party data) before
+ * passing a string to `has_org_permission` / `requireOrganizationPermission`.
+ */
+export function isPermissionKey(value: unknown): value is PermissionKey {
+  return typeof value === 'string' && PERMISSION_KEY_SET.has(value)
+}

package/src/organization-model/README.md

@@ -66,6 +66,7 @@ features: [
 ```
 
 Containers omit `path`; leaves provide `path`. `uiPosition`, `requiresAdmin`, and `devOnly` inherit from ancestors.
+Development-only features remain in the contract with `enabled: true` and `devOnly: true`; shell consumers hide them and guard their paths outside development mode.
 
 ## Graph IDs
 

package/src/organization-model/__tests__/defaults.test.ts

@@ -69,12 +69,25 @@ describe('organization-model defaults', () => {
       expect(() => OrganizationModelSchema.parse(result)).not.toThrow()
     })
 
-    it('resolveOrganizationModel with no override equals resolveOrganizationModel with DEFAULT_ORGANIZATION_MODEL', () => {
-      const fromUndefined = resolveOrganizationModel(undefined)
-      const fromDefault = resolveOrganizationModel(DEFAULT_ORGANIZATION_MODEL)
-      expect(fromDefault).toEqual(fromUndefined)
-    })
-  })
+    it('resolveOrganizationModel with no override equals resolveOrganizationModel with DEFAULT_ORGANIZATION_MODEL', () => {
+      const fromUndefined = resolveOrganizationModel(undefined)
+      const fromDefault = resolveOrganizationModel(DEFAULT_ORGANIZATION_MODEL)
+      expect(fromDefault).toEqual(fromUndefined)
+    })
+
+    it('keeps Command View enabled but development-only in the default Operations navigation', () => {
+      const result = resolveOrganizationModel(undefined)
+      const commandViewFeature = result.features.find((feature) => feature.id === 'operations.command-view')
+      const commandViewSurface = DEFAULT_ORGANIZATION_MODEL_NAVIGATION.surfaces.find(
+        (surface) => surface.id === 'operations.command-view'
+      )
+
+      expect(commandViewFeature?.enabled).toBe(true)
+      expect(commandViewFeature?.devOnly).toBe(true)
+      expect(commandViewSurface?.enabled).toBe(true)
+      expect(commandViewSurface?.devOnly).toBe(true)
+    })
+  })
 
   describe.each(domainCases)('$name (domain sub-constant)', ({ name: _name, constant, schema }) => {
     it('passes its domain schema parse without throwing', () => {

package/src/organization-model/contracts.ts

@@ -9,6 +9,6 @@ export const MONITORING_FEATURE_ID = 'monitoring' as const
 export const SETTINGS_FEATURE_ID = 'settings' as const
 export const SEO_FEATURE_ID = 'seo' as const
 
-export const SALES_PIPELINE_SURFACE_ID = 'crm.pipeline' as const
-export const PROSPECTING_LISTS_SURFACE_ID = 'lead-gen.lists' as const
-export const OPERATIONS_ORGANIZATION_GRAPH_SURFACE_ID = 'operations.organization-graph' as const
+export const SALES_PIPELINE_SURFACE_ID = 'crm.pipeline' as const
+export const PROSPECTING_LISTS_SURFACE_ID = 'lead-gen.lists' as const
+export const OPERATIONS_COMMAND_VIEW_SURFACE_ID = 'operations.command-view' as const

package/src/organization-model/defaults.ts

@@ -68,17 +68,12 @@ export const DEFAULT_ORGANIZATION_MODEL: OrganizationModel = {
       icon: 'operations',
       uiPosition: 'sidebar-primary'
     },
-    {
-      id: 'operations.graph',
-      label: 'Organization Graph',
-      enabled: true,
-      path: '/operations/organization-graph'
-    },
     {
       id: 'operations.command-view',
       label: 'Command View',
-      enabled: false,
-      path: '/operations/command-view'
+      enabled: true,
+      path: '/operations/command-view',
+      devOnly: true
     },
     {
       id: 'operations.overview',

package/src/organization-model/domains/navigation.ts

@@ -1,5 +1,10 @@
 import { z } from 'zod'
-import { PROJECTS_VIEW_CAPABILITY_ID, PROJECTS_FEATURE_ID, PROJECTS_INDEX_SURFACE_ID } from '../contracts'
+import {
+  OPERATIONS_COMMAND_VIEW_SURFACE_ID,
+  PROJECTS_VIEW_CAPABILITY_ID,
+  PROJECTS_FEATURE_ID,
+  PROJECTS_INDEX_SURFACE_ID
+} from '../contracts'
 import { DescriptionSchema, IconNameSchema, LabelSchema, ModelIdSchema, PathSchema, ReferenceIdsSchema } from './shared'
 
 export const SurfaceTypeSchema = z.enum(['page', 'dashboard', 'graph', 'detail', 'list', 'settings'])
@@ -9,9 +14,10 @@ export const SurfaceDefinitionSchema = z.object({
   label: LabelSchema,
   path: PathSchema,
   surfaceType: SurfaceTypeSchema,
-  description: DescriptionSchema.optional(),
-  enabled: z.boolean().default(true),
-  icon: IconNameSchema.optional(),
+  description: DescriptionSchema.optional(),
+  enabled: z.boolean().default(true),
+  devOnly: z.boolean().optional(),
+  icon: IconNameSchema.optional(),
   featureId: ModelIdSchema.optional(),
   featureIds: ReferenceIdsSchema,
   entityIds: ReferenceIdsSchema,
@@ -85,27 +91,16 @@ export const DEFAULT_ORGANIZATION_MODEL_NAVIGATION: z.infer<typeof OrganizationM
       resourceIds: [],
       capabilityIds: [PROJECTS_VIEW_CAPABILITY_ID]
     },
-    {
-      id: 'operations.organization-graph',
-      label: 'Organization Graph',
-      path: '/operations/organization-graph',
-      surfaceType: 'graph',
-      enabled: true,
-      featureId: 'operations',
-      featureIds: ['operations'],
-      entityIds: [],
-      resourceIds: [],
-      capabilityIds: ['operations.organization-graph']
-    },
-    {
-      id: 'operations.command-view',
-      label: 'Command View',
-      path: '/operations/command-view',
-      surfaceType: 'graph',
-      enabled: false,
-      featureId: 'operations',
-      featureIds: ['operations'],
-      entityIds: [],
+    {
+      id: OPERATIONS_COMMAND_VIEW_SURFACE_ID,
+      label: 'Command View',
+      path: '/operations/command-view',
+      surfaceType: 'graph',
+      enabled: true,
+      devOnly: true,
+      featureId: 'operations',
+      featureIds: ['operations'],
+      entityIds: [],
       resourceIds: [],
       capabilityIds: ['operations.command-view']
     },
@@ -347,13 +342,12 @@ export const DEFAULT_ORGANIZATION_MODEL_NAVIGATION: z.infer<typeof OrganizationM
     },
     {
       id: 'primary-operations',
-      label: 'Operations',
-      placement: 'primary',
-      surfaceIds: [
-        'operations.organization-graph',
-        'operations.command-view',
-        'operations.overview',
-        'operations.resources',
+      label: 'Operations',
+      placement: 'primary',
+      surfaceIds: [
+        OPERATIONS_COMMAND_VIEW_SURFACE_ID,
+        'operations.overview',
+        'operations.resources',
         'operations.command-queue',
         'operations.sessions',
         'operations.task-scheduler'

package/src/organization-model/foundation.ts

@@ -44,14 +44,13 @@ export function createFoundationOrganizationModel(override: DeepPartial<Organiza
     return feature
   }
 
-  const operationsGraphFeature = requireCoreFeature('operations.graph')
+  const operationsFeature = requireCoreFeature('operations')
   const projectsFeature = requireCoreFeature('projects')
   const leadGenFeature = requireCoreFeature('sales.lead-gen')
   const crmFeature = requireCoreFeature('sales.crm')
 
   const navigationSurfaces: FoundationNavigationSurface[] = [
-    { ...operationsGraphFeature, id: 'operations', path: '/operations', icon: 'operations', surfaceType: 'graph' },
-    { ...operationsGraphFeature, path: '/operations', icon: 'operations', surfaceType: 'graph' },
+    { ...operationsFeature, id: 'operations', path: '/operations', icon: 'operations', surfaceType: 'dashboard' },
     { ...projectsFeature, icon: 'projects', surfaceType: 'list' },
     { ...leadGenFeature, id: 'lead-gen', icon: 'lead-gen', surfaceType: 'list' },
     { ...crmFeature, id: 'crm', icon: 'crm', surfaceType: 'graph' },

package/src/organization-model/organization-model.mdx

@@ -67,6 +67,9 @@ Authored fields:
 - `devOnly`
 
 Containers omit `path`; leaves provide `path`. `uiPosition`, `requiresAdmin`, and `devOnly` inherit from ancestors.
+Development-only features remain defined and enabled with `devOnly: true`; shell consumers hide those entries and route paths outside development mode while preserving the semantic contract.
+
+Navigation surfaces may also carry `devOnly` for compatibility with the legacy/domain navigation model. `operations.command-view` is intentionally development-only while its graph visualization modes continue to mature.
 
 ## Graph IDs and Resource Links