@elevasis/core 0.10.0 → 0.11.1

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