spine-framework 0.3.124 → 0.3.126

package/.framework/functions/roles.ts

@@ -1,31 +1,3 @@
-/**
- * @module roles
- * @audience core-contributor
- * @layer api-handler
- * @stability stable
- *
- * CRUD API for the `roles` table. Roles define permission sets (`permissions`
- * JSONB) that are assigned to people within an account.
- *
- * **Routed by:** `GET/POST/PATCH/DELETE /.netlify/functions/roles`
- *
- * **Authorization model:**
- * - All reads use `ctx.db` (RLS-scoped). System admins see raw records;
- *   others get field-level sanitization via `sanitizeRecordData`.
- * - `create`: requires system admin OR first-surface `canCreate` permission.
- *   Creating a role with `slug === 'system_admin'` is system-admin-only.
- * - `update` / `remove`: require authenticated principal. RLS controls row
- *   access; field-level permissions validated via `validateUpdatePermissions`.
- * - Slug uniqueness is enforced per-app: checked against `adminDb`.
- *
- * INVARIANT: `system_admin` role slug can only be created by system admins.
- * INVARIANT: soft delete only — roles are set to `is_active = false`.
- *
- * @seeAlso middleware.ts (createHandler)
- * @seeAlso permissions.ts (PermissionEngine, sanitizeRecordData)
- * @seeAlso audit.ts (emitLog for role.created / role.updated / role.deleted)
- */
-
 import { createHandler } from './_shared/middleware'
 import { adminDb } from './_shared/db'
 import { emitLog } from './_shared/audit'
@@ -33,27 +5,30 @@ import { PermissionEngine, sanitizeRecordData } from './_shared/permissions'
 
 const permissions = PermissionEngine as any
 
-// ─── HANDLERS ─────────────────────────────────────────────────────────────────
-
-// ─── CHUNK_START: ROLES_LIST ──────────────────────────────────────────────
-/**
- * @chunk-id    ROLES_LIST_1_0_0
- * @version     1.0.0
- * @hash        b643852233c87c20abd7d62b3f51be9ba7f0f2a4ff02154be239ceef6184811b
- * @macro       Roles List Handler
- * @micro       Lists active roles with filtering and permission-based sanitization
- * @inputs      ctx: CoreContext — Request context with principal and database
- * @inputs      _body: any — Request body (unused for GET)
- * @outputs     Array of role records with app join, sanitized for non-admins
- * @depends-on  [createHandler, PermissionEngine, sanitizeRecordData]
- * @depended-by [Netlify function routing]
- * @side-effects [DB queries, permission sanitization]
- * @tags        roles, list, crud, pagination, permissions
- */
+
+
+
+
+
+
+// CIL[BEGIN chunk_id="roles_module_header_1783932909" type="module_header" identity="module_header" parent="none"]
+// CIL[DOC-MACRO purpose="Lists roles with filtering and permission-based sanitization"]
+// CIL[DOC-RESPONSIBILITY responsibility="Handle role listing with app and system filters"]
+// CIL[DOC-CONTEXT module="roles" layer="api-handler" related_files="[\".framework/src/pages/admin/RolesPage.tsx\",\"custom/apps/portal/pages/ContentPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/components/ui/dialog.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="ctx, _body" outputs="Array of role records" errors="Throws on DB errors" side_effects="Database queries, permission checks"]
+// CIL[DOC-MICRO logic_summary="Filters roles, applies permission sanitization for non-admins" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-AUDIENCE audience="developer"]
+// CIL[DOC-VECTOR type="context" content="Layer: api-handler. Direct callers: 0. Direct calls: 0. Related files: .framework/src/pages/admin/RolesPage.tsx, custom/apps/portal/pages/ContentPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/components/ui/dialog.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export const list = createHandler(async (ctx, _body) => {
   const { app_id, is_system, limit = '50', offset = '0' } = ctx.query || {}
 
-  // RLS automatically filters to accessible roles
   let query = ctx.db
     .from('roles')
     .select(`
@@ -79,12 +54,10 @@ export const list = createHandler(async (ctx, _body) => {
 
   if (err) throw err
 
-  // System admin sees everything without additional filtering
   if (permissions.isSystemAdmin(ctx)) {
     return data
   }
 
-  // Filter each role based on field-level permissions
   const filteredData = []
   for (const role of data || []) {
     const roleWithType = { ...role, type: 'role' }
@@ -94,23 +67,21 @@ export const list = createHandler(async (ctx, _body) => {
 
   return filteredData
 })
-// ─── CHUNK_END: ROLES_LIST ────────────────────────────────────────────────
-
-// ─── CHUNK_START: ROLES_GET ──────────────────────────────────────────────
-/**
- * @chunk-id    ROLES_GET_1_0_0
- * @version     1.0.0
- * @hash        94607bad8b9ff929233ce1b29b6563062d439365ed0413726c5a8d8d0f58474b
- * @macro       Role Get Handler
- * @micro       Returns single role record with joins and permission sanitization
- * @inputs      ctx: CoreContext — Request context with principal and database
- * @inputs      _body: any — Request body (unused for GET)
- * @outputs     Sanitized role record with app join
- * @depends-on  [createHandler, sanitizeRecordData]
- * @depended-by [Netlify function routing]
- * @side-effects [DB single row query, permission sanitization]
- * @tags        roles, get, crud, single-record, permissions
- */
+// CIL[END chunk_id="roles_module_header_1783932909"]
+// CIL[BEGIN chunk_id="roles_get_1783932909" type="function" identity="get" parent="none"]
+// CIL[DOC-MACRO purpose="Retrieves single role by ID with sanitization"]
+// CIL[DOC-RESPONSIBILITY responsibility="Handle individual role retrieval"]
+// CIL[DOC-CONTEXT module="roles" layer="api-handler" related_files="[\".framework/functions/_shared/schema-utils.ts\",\".framework/src/pages/admin/RolesPage.tsx\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Single role record" errors="Throws if ID missing or DB error" side_effects="Database query, permission sanitization"]
+// CIL[DOC-MICRO logic_summary="Fetches role by ID, applies permission sanitization" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: api-handler. Direct callers: 0. Direct calls: 0. Related files: .framework/functions/_shared/schema-utils.ts, .framework/src/pages/admin/RolesPage.tsx, .framework/src/pages/admin/TypeDetailPage.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export const get = createHandler(async (ctx, _body) => {
   const { id } = ctx.query || {}
   
@@ -118,7 +89,6 @@ export const get = createHandler(async (ctx, _body) => {
     throw new Error('Role ID is required')
   }
 
-  // RLS ensures user can only access roles in their accessible accounts
   const { data, error: err } = await ctx.db
     .from('roles')
     .select(`
@@ -131,27 +101,24 @@ export const get = createHandler(async (ctx, _body) => {
 
   if (err) throw err
 
-  // Return sanitized data based on field-level permissions
   const roleWithType = { ...data, type: 'role' }
   return await sanitizeRecordData(ctx, roleWithType, 'role')
 })
-// ─── CHUNK_END: ROLES_GET ────────────────────────────────────────────────
-
-// ─── CHUNK_START: ROLES_CREATE ──────────────────────────────────────────────
-/**
- * @chunk-id    ROLES_CREATE_1_0_0
- * @version     1.0.0
- * @hash        7f6646fee88ed72d997eb710feb3778aad114f3a96819390166c8ecbc6eeaa0e
- * @macro       Role Create Handler
- * @micro       Creates role with permission validation and audit logging
- * @inputs      ctx: CoreContext — Request context with principal and database
- * @inputs      body: object — Role data including slug, name, and optional fields
- * @outputs     Inserted role record
- * @depends-on  [createHandler, PermissionEngine, adminDb, emitLog]
- * @depended-by [Netlify function routing]
- * @side-effects [DB insert, permission validation, audit logging]
- * @tags        roles, create, crud, permissions, audit
- */
+// CIL[END chunk_id="roles_get_1783932909"]
+// CIL[BEGIN chunk_id="roles_create_1783932909" type="function" identity="create" parent="none"]
+// CIL[DOC-MACRO purpose="Creates new role with permission validation"]
+// CIL[DOC-RESPONSIBILITY responsibility="Handle role creation with security checks"]
+// CIL[DOC-CONTEXT module="roles" layer="api-handler" related_files="[\".framework/functions/_shared/schema-utils.ts\",\".framework/src/pages/admin/RolesPage.tsx\",\".framework/src/components/ui/dialog.tsx\",\".framework/functions/_shared/principal.ts\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Created role record" errors="Throws on validation, permission, or DB errors" side_effects="Database insert, audit logging"]
+// CIL[DOC-MICRO logic_summary="Validates permissions, checks uniqueness, creates role" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: api-handler. Direct callers: 0. Direct calls: 0. Related files: .framework/functions/_shared/schema-utils.ts, .framework/src/pages/admin/RolesPage.tsx, .framework/src/components/ui/dialog.tsx, .framework/functions/_shared/principal.ts, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export const create = createHandler(async (ctx, body) => {
   const { app_id, slug, name, description, permissions: rolePermissions, is_system } = body
 
@@ -163,12 +130,10 @@ export const create = createHandler(async (ctx, body) => {
     throw new Error('User context (person and account) required')
   }
 
-  // Guard: system_admin role can only be created by system admins
   if (slug === 'system_admin' && !permissions.isSystemAdmin(ctx)) {
     throw new Error('system_admin role can only be created by system administrators')
   }
 
-  // Check create permissions using PermissionEngine
   if (!permissions.isSystemAdmin(ctx)) {
     const perms = await permissions.resolveFirstSurfacePermissions(
       ctx.principal.id,
@@ -182,7 +147,6 @@ export const create = createHandler(async (ctx, body) => {
     }
   }
 
-  // Check if slug is unique within app using service role (validating uniqueness is a system concern)
   let query = adminDb
     .from('roles')
     .select('id')
@@ -200,7 +164,6 @@ export const create = createHandler(async (ctx, body) => {
     throw new Error('Role slug already exists for this app')
   }
 
-  // Insert with RLS enforcement
   const { data, error: err } = await ctx.db
     .from('roles')
     .insert({
@@ -221,23 +184,21 @@ export const create = createHandler(async (ctx, body) => {
 
   return data
 })
-// ─── CHUNK_END: ROLES_CREATE ────────────────────────────────────────────────
-
-// ─── CHUNK_START: ROLES_UPDATE ──────────────────────────────────────────────
-/**
- * @chunk-id    ROLES_UPDATE_1_0_0
- * @version     1.0.0
- * @hash        19803de116b38af5e27bf542ca642228f4661bbf428a4846ed565d0667767580
- * @macro       Role Update Handler
- * @micro       Updates role with field-level permission validation and audit logging
- * @inputs      ctx: CoreContext — Request context with principal and database
- * @inputs      body: object — Role updates including id and updatable fields
- * @outputs     Updated role record
- * @depends-on  [createHandler, PermissionEngine, emitLog]
- * @depended-by [Netlify function routing]
- * @side-effects [DB update, permission validation, audit logging]
- * @tags        roles, update, crud, permissions, audit
- */
+// CIL[END chunk_id="roles_create_1783932909"]
+// CIL[BEGIN chunk_id="roles_update_1783932909" type="function" identity="update" parent="none"]
+// CIL[DOC-MACRO purpose="Updates role with field-level permission validation"]
+// CIL[DOC-RESPONSIBILITY responsibility="Handle role updates with security validation"]
+// CIL[DOC-CONTEXT module="roles" layer="api-handler" related_files="[\".framework/functions/_shared/schema-utils.ts\",\".framework/src/pages/admin/RolesPage.tsx\",\".framework/functions/_shared/principal.ts\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Updated role record" errors="Throws on validation, permission, or DB errors" side_effects="Database update, audit logging"]
+// CIL[DOC-MICRO logic_summary="Validates update permissions, applies changes with audit trail" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: api-handler. Direct callers: 0. Direct calls: 0. Related files: .framework/functions/_shared/schema-utils.ts, .framework/src/pages/admin/RolesPage.tsx, .framework/functions/_shared/principal.ts, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export const update = createHandler(async (ctx, body) => {
   const { id, ...updates } = body
 
@@ -249,7 +210,6 @@ export const update = createHandler(async (ctx, body) => {
     throw new Error('User context (person and account) required')
   }
 
-  // Get current state for audit via RLS
   const { data: current, error: fetchErr } = await ctx.db
     .from('roles')
     .select('*')
@@ -260,7 +220,6 @@ export const update = createHandler(async (ctx, body) => {
     throw new Error('Role not found or access denied')
   }
 
-  // Validate field-level permissions
   const fieldValidation = await permissions.validateUpdatePermissions(
     ctx,
     updates,
@@ -272,7 +231,6 @@ export const update = createHandler(async (ctx, body) => {
     throw new Error(fieldValidation.error)
   }
 
-  // Update via RLS
   const { data, error: err } = await ctx.db
     .from('roles')
     .update({
@@ -289,23 +247,21 @@ export const update = createHandler(async (ctx, body) => {
 
   return data
 })
-// ─── CHUNK_END: ROLES_UPDATE ────────────────────────────────────────────────
-
-// ─── CHUNK_START: ROLES_REMOVE ──────────────────────────────────────────────
-/**
- * @chunk-id    ROLES_REMOVE_1_0_0
- * @version     1.0.0
- * @hash        9194c78a60e7d12b7acf6981bbc56afdfbe9e922c52739394240fca5adcfa069
- * @macro       Role Remove Handler
- * @micro       Soft-deletes role with audit logging
- * @inputs      ctx: CoreContext — Request context with principal and database
- * @inputs      body: object — Role id for deletion
- * @outputs     Updated role record with is_active: false
- * @depends-on  [createHandler, emitLog]
- * @depended-by [Netlify function routing]
- * @side-effects [DB soft delete, audit logging]
- * @tags        roles, remove, soft-delete, audit
- */
+// CIL[END chunk_id="roles_update_1783932909"]
+// CIL[BEGIN chunk_id="roles_remove_1783932909" type="function" identity="remove" parent="none"]
+// CIL[DOC-MACRO purpose="Soft deletes role by setting is_active to false"]
+// CIL[DOC-RESPONSIBILITY responsibility="Handle role deletion with audit trail"]
+// CIL[DOC-CONTEXT module="roles" layer="api-handler" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Deactivated role record" errors="Throws on validation or DB errors" side_effects="Database update, audit logging"]
+// CIL[DOC-MICRO logic_summary="Soft deletes role, maintains audit trail" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: api-handler. Direct callers: 0. Direct calls: 0. Related files: none."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export const remove = createHandler(async (ctx, body) => {
   const { id } = body
 
@@ -317,7 +273,6 @@ export const remove = createHandler(async (ctx, body) => {
     throw new Error('User context (person and account) required')
   }
 
-  // Verify access via RLS fetch
   const { data: current, error: fetchErr } = await ctx.db
     .from('roles')
     .select('*')
@@ -328,7 +283,6 @@ export const remove = createHandler(async (ctx, body) => {
     throw new Error('Role not found or access denied')
   }
 
-  // Soft delete via RLS
   const { data, error: err } = await ctx.db
     .from('roles')
     .update({
@@ -345,25 +299,21 @@ export const remove = createHandler(async (ctx, body) => {
 
   return data
 })
-// ─── CHUNK_END: ROLES_REMOVE ────────────────────────────────────────────────
-
-// ─── MAIN HANDLER ────────────────────────────────────────────────────────────
-
-// ─── CHUNK_START: ROLES_HANDLER ──────────────────────────────────────────────
-/**
- * @chunk-id    ROLES_HANDLER_1_0_0
- * @version     1.0.0
- * @hash        14c00f276a22287ed65c019efe327cbb513f860a408191e299864b05c641833c
- * @macro       Roles Router
- * @micro       Routes HTTP methods to appropriate role handlers
- * @inputs      ctx: CoreContext — Request context with principal and database
- * @inputs      body: any — Request body for POST/PATCH/DELETE operations
- * @outputs     Varies — Depends on routed handler (list/get/create/update/remove)
- * @depends-on  [createHandler, list, get, create, update, remove]
- * @depended-by [Netlify function routing]
- * @side-effects [Delegates to appropriate handler]
- * @tags        roles, router, crud, netlify-function
- */
+// CIL[END chunk_id="roles_remove_1783932909"]
+// CIL[BEGIN chunk_id="roles_handler_1783932909" type="function" identity="handler" parent="none"]
+// CIL[DOC-MACRO purpose="Routes HTTP methods to appropriate role handlers"]
+// CIL[DOC-RESPONSIBILITY responsibility="Handle request routing for role CRUD operations"]
+// CIL[DOC-CONTEXT module="roles" layer="api-handler" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Varies by handler" errors="Throws on unsupported methods" side_effects="Delegates to appropriate handler"]
+// CIL[DOC-MICRO logic_summary="Routes based on HTTP method, delegates to CRUD handlers" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: api-handler. Direct callers: 0. Direct calls: 0. Related files: none."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export const handler = createHandler(async (ctx, body) => {
   const method = ctx.query?.method || 'GET'
 
@@ -384,4 +334,4 @@ export const handler = createHandler(async (ctx, body) => {
       throw new Error(`Unsupported method: ${method}`)
   }
 })
-// ─── CHUNK_END: ROLES_HANDLER ────────────────────────────────────────────────
+// CIL[END chunk_id="roles_handler_1783932909"]