spine-framework 0.3.124 → 0.3.126

package/.framework/functions/_shared/principal.ts

@@ -1,44 +1,81 @@
-/**
- * @module principal
- * @audience both
- * @layer shared-core
- * @stability stable
- *
- * Unified identity abstraction for all actors in Spine v2. Every request —
- * whether from a human via JWT, an integration via API key, a scheduled cron
- * job, or an internal trigger — resolves to a single `Principal` object before
- * any permission check or DB query occurs.
- *
- * Resolution order in `resolvePrincipal`:
- *   1. `x-api-key` header  → machine principal (external integration)
- *   2. `x-cron-id` header  → machine principal (scheduled job)
- *   3. `x-trigger-id` header → machine principal (event trigger)
- *   4. `Authorization: Bearer <jwt>` → human principal
- *   5. (none)              → ANONYMOUS_PRINCIPAL (rejected by createHandler)
- *
- * INVARIANT: `resolvePrincipal` always returns a Principal, never null.
- *   ANONYMOUS_PRINCIPAL is the sentinel for unauthenticated requests and is
- *   rejected by `createHandler` before the handler runs.
- * INVARIANT: `adminDb` is used for all principal resolution lookups to avoid
- *   circular dependencies with RLS (which itself depends on the resolved principal).
- * INVARIANT: never store `authContext.jwt` or `authContext.apiKey` in logs.
- *   Use `formatPrincipalForAudit` which strips these fields.
- *
- * @seeAlso db.ts (adminDb, getUserDb — used for resolution and client selection)
- * @seeAlso middleware.ts (createHandler calls resolvePrincipal, getPrincipalDb)
- * @seeAlso permissions.ts (PermissionEngine.isSystemAdmin, canPrincipalAccessRecord)
- * @seeAlso audit.ts (formatPrincipalForAudit — safe audit serialization)
- */
 
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+// CIL[BEGIN chunk_id="principal_imports_1784020784" type="module_header" identity="imports" parent="none"]
+// CIL[DOC-MACRO purpose="Import database, auth client, and WebSocket dependencies"]
+// CIL[DOC-RESPONSIBILITY responsibility="Import required modules for principal resolution"]
+// CIL[DOC-CONTEXT module="principal" layer="shared" related_files="[\"custom/apps/portal/pages/ContentPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/pages/admin/RolesPage.tsx\",\".framework/src/components/ui/dialog.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="database, auth client, WebSocket" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Import database connections, Supabase client, and WebSocket" 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: shared. Direct callers: 0. Direct calls: 0. Related files: custom/apps/portal/pages/ContentPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/pages/admin/RolesPage.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"]
 import { getUserDb, adminDb } from './db'
 import { createClient } from '@supabase/supabase-js'
 import WebSocket from 'ws'
+import { timingSafeEqual } from 'crypto'
+// CIL[END chunk_id="principal_imports_1784020784"]
+// CIL[BEGIN chunk_id="principal_internalsecret_1784020785" type="function" identity="isInternalInvokeAuthorized" parent="none"]
+// CIL[DOC-MACRO purpose="Gate internal-only principal headers behind a shared secret"]
+// CIL[DOC-RESPONSIBILITY responsibility="Prevent x-cron-id/x-trigger-id header spoofing on public endpoints"]
+// CIL[DOC-CONTEXT module="principal" layer="shared" related_files="[\".framework/functions/system-cron.ts\"]"]
+// CIL[DOC-CONTRACT inputs="event" outputs="boolean" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Compares x-internal-secret header against INTERNAL_INVOKE_SECRET env var using a timing-safe comparison; returns false (deny) if the secret is unset or missing/mismatched" notable_decisions="[\"Without this gate, any caller could set x-cron-id/x-trigger-id and impersonate the associated machine principal by guessing or reusing a leaked schedule/trigger id.\"]"]
+// CIL[DOC-CONFIDENCE pass="first" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-AUDIENCE audience="developer"]
+// CIL[DOC-NOTE type="caution" content="INTERNAL_INVOKE_SECRET must be set wherever the framework itself issues x-cron-id/x-trigger-id headers (currently no code path does), or those callers will silently fall back to ANONYMOUS_PRINCIPAL."]
+function isInternalInvokeAuthorized(event: any): boolean {
+  const expected = (globalThis as any).process?.env?.INTERNAL_INVOKE_SECRET
+  if (!expected) return false
+
+  const provided = event.headers?.['x-internal-secret'] || event.headers?.['X-Internal-Secret']
+  if (!provided || typeof provided !== 'string') return false
 
-// ─── AUTH CLIENT ─────────────────────────────────────────────────────────────
+  const expectedBuf = Buffer.from(expected)
+  const providedBuf = Buffer.from(provided)
+  if (expectedBuf.length !== providedBuf.length) return false
 
-// Supabase anon client used only for JWT validation (supabase.auth.getUser).
-// A separate client is used here to avoid importing the RLS-scoped client
-// before the principal is resolved.
+  try {
+    return timingSafeEqual(expectedBuf, providedBuf)
+  } catch {
+    return false
+  }
+}
+// CIL[END chunk_id="principal_internalsecret_1784020785"]
+// CIL[BEGIN chunk_id="principal_authclient_1784020784" type="variable" identity="supabase" parent="none"]
+// CIL[DOC-MACRO purpose="Create Supabase auth client for JWT validation"]
+// CIL[DOC-RESPONSIBILITY responsibility="Initialize auth client with environment configuration"]
+// CIL[DOC-CONTEXT module="principal" layer="shared" related_files="[\".framework/functions/_shared/schema-utils.ts\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/components/layout/Sidebar.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="supabase client" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Configures Supabase client with auth and realtime settings" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: shared. Direct callers: 0. Direct calls: 0. Related files: .framework/functions/_shared/schema-utils.ts, .framework/src/pages/admin/TypeDetailPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/components/layout/Sidebar.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"]
 const env = (globalThis as any).process?.env || {}
 const supabase = createClient(
   env.SUPABASE_URL || 'https://placeholder.supabase.co',
@@ -48,117 +85,64 @@ const supabase = createClient(
     realtime: { transport: WebSocket as any }
   }
 )
-
-// ─── PRINCIPAL INTERFACE ─────────────────────────────────────────────────────
-
-/**
- * Unified identity abstraction for all actors in Spine.
- *
- * Every request resolves to a `Principal` before any permission or DB access.
- * The `type` field gates which optional fields are populated:
- *   - `'human'` → `roles`, `displayName`, `email`, `authContext.jwt`
- *   - `'machine'` → `scopes`, `machineType`, `isInternal`, `authContext.apiKey`
- *
- * The `provenance` object is always populated and is the primary audit trail
- * field. It must not be modified after resolution.
- *
- * @inputSpec none — this is a pure type definition
- * @calledBy middleware.ts (RequestContext.principal), permissions.ts (all methods),
- *   audit.ts (formatPrincipalForAudit), tests/integration/helpers.ts (makeTestCtx)
- */
+// CIL[END chunk_id="principal_authclient_1784020784"]
+// CIL[BEGIN chunk_id="principal_interface_1784020784" type="interface" identity="Principal" parent="none"]
+// CIL[DOC-MACRO purpose="Define principal interface for authentication and authorization"]
+// CIL[DOC-RESPONSIBILITY responsibility="Provide comprehensive principal structure with provenance"]
+// CIL[DOC-CONTEXT module="principal" layer="shared" related_files="[\".framework/functions/_shared/schema-utils.ts\",\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/src/components/layout/Sidebar.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Principal interface" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Interface with identity, permissions, provenance, and auth context" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: shared. Direct callers: 0. Direct calls: 0. Related files: .framework/functions/_shared/schema-utils.ts, custom/apps/portal/pages/ContentPage.tsx, .framework/src/components/layout/Sidebar.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.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 interface Principal {
-  /** Unique identifier — person UUID (human) or machine principal UUID (machine) */
   id: string
-  
-  /** Actor type — gates which optional fields are populated */
   type: 'human' | 'machine'
-  
-  /** Primary account context; null for internal system principals */
   accountId: string | null
-  
-  // ─ Human-specific (only populated when type === 'human') ─────────────────
-  /** Role slugs from people.role_id → roles.slug; used by PermissionEngine */
   roles?: string[]
-  
-  /** Display name from people.display_name or people.email */
   displayName?: string
-  
-  /** Email address from people.email or Supabase auth user */
   email?: string
-  
-  // ─ Machine-specific (only populated when type === 'machine') ─────────────
-  /** Explicit permission grants (e.g., ['items:read', 'people:write', '*:*']) */
   scopes?: string[]
-  
-  /** Machine classification — determines UI visibility and default scopes */
   machineType?: 'integration' | 'service_account' | 'internal' | 'timer'
-  
-  /** Internal machines (cron, trigger, pipeline) are hidden from the UI */
   isInternal?: boolean
-  
-  // ─ Universal provenance — always populated, never modified after resolution
   provenance: {
-    /** How this principal was authenticated */
     sourceType: 'jwt' | 'api_key' | 'cron' | 'trigger' | 'manual' | 'webhook' | 'timer'
-    
-    /** Person who authorized this principal (may be self for humans) */
     createdBy: string | null
-    
-    /** Chain ID for trigger/pipeline sequences */
     parentExecutionId?: string
-    
-    /** When this principal context was created */
     invokedAt: string
-    
-    // Source-specific context
-    /** API key ID (for api_key source) */
     apiKeyId?: string
-    
-    /** Schedule ID (for cron source) */
     cronId?: string
-    
-    /** Trigger ID (for trigger source) */
     triggerId?: string
-    
-    /** Timer ID (for timer source) */
     timerId?: string
-    
-    /** Event ID that triggered this execution */
     eventId?: string
-    
-    /** IP address of the requester */
     ipAddress?: string
-    
-    /** User agent string */
     userAgent?: string
   }
-  
-  // ============================================
-  // Authentication context (for RLS client selection)
-  // ============================================
   authContext?: {
-    /** JWT token for human-scoped DB client */
     jwt?: string
-    
-    /** API key value for machine verification */
     apiKey?: string
   }
 }
-
-// ─── PRINCIPAL CONSTANTS ─────────────────────────────────────────────────────
-
-/**
- * Sentinel principal for unauthenticated requests.
- *
- * Returned by `resolvePrincipal` when no auth header is present. `createHandler`
- * checks for `principal.id === 'anonymous'` and rejects the request with 401.
- * Never use this principal for any DB access — it has no scopes or accountId.
- *
- * @stability stable
- * @calledBy resolvePrincipal (returned when no auth header is present)
- * @calledBy middleware.ts, requireUserContext, requireSystemContextWithAudit (checked against)
- * @calledBy permissions.ts (all surface methods check for 'anonymous' and deny)
- */
+// CIL[END chunk_id="principal_interface_1784020784"]
+// CIL[BEGIN chunk_id="principal_anonymous_1784020784" type="constant" identity="ANONYMOUS_PRINCIPAL" parent="none"]
+// CIL[DOC-MACRO purpose="Define anonymous principal for unauthenticated access"]
+// CIL[DOC-RESPONSIBILITY responsibility="Provide fallback principal when no authentication present"]
+// CIL[DOC-CONTEXT module="principal" layer="shared" related_files="[\".framework/src/components/layout/Sidebar.tsx\",\".framework/functions/_shared/schema-utils.ts\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/src/pages/admin/IntegrationsPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="ANONYMOUS_PRINCIPAL constant" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Machine principal with no permissions and manual provenance" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: shared. Direct callers: 0. Direct calls: 0. Related files: .framework/src/components/layout/Sidebar.tsx, .framework/functions/_shared/schema-utils.ts, .framework/src/pages/admin/TypeDetailPage.tsx, .framework/src/pages/admin/IntegrationsPage.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 ANONYMOUS_PRINCIPAL: Principal = {
   id: 'anonymous',
   type: 'machine',
@@ -170,37 +154,26 @@ export const ANONYMOUS_PRINCIPAL: Principal = {
     invokedAt: new Date().toISOString()
   }
 }
-
-/**
- * System principal for internal Spine operations (cron, pipeline runner, trigger engine).
- *
- * Has `'*:*'` scope (all resources, all actions) and `isInternal: true`. When
- * a `CoreContext` is constructed for a system operation (e.g. in v2-custom/ or
- * the CLI), use `SYSTEM_PRINCIPAL` as the principal and `adminDb` as the db.
- *
- * Never expose this principal in an HTTP response or log the `authContext` field.
- *
- * @stability stable
- * @calledBy tests/integration/helpers.ts (makeTestCtx)
- * @calledBy CLI context construction
- * @calledBy v2-custom/ system-level import callers
- *
- * @example Import usage (v2-custom/)
- * ```ts
- * import { CoreContext, SYSTEM_PRINCIPAL, adminDb } from '../_shared/index'
- * const ctx: CoreContext = {
- *   principal: SYSTEM_PRINCIPAL,
- *   accountId: MY_ACCOUNT_ID,
- *   db: adminDb,
- *   requestId: crypto.randomUUID()
- * }
- * ```
- */
+// CIL[END chunk_id="principal_anonymous_1784020784"]
+// CIL[BEGIN chunk_id="principal_system_1784020784" type="constant" identity="SYSTEM_PRINCIPAL" parent="none"]
+// CIL[DOC-MACRO purpose="Define system principal for internal operations"]
+// CIL[DOC-RESPONSIBILITY responsibility="Provide unrestricted internal principal for system tasks"]
+// CIL[DOC-CONTEXT module="principal" layer="shared" related_files="[\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/components/layout/Sidebar.tsx\",\".framework/functions/_shared/schema-utils.ts\",\".framework/src/pages/admin/TypeDetailPage.tsx\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="SYSTEM_PRINCIPAL constant" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Internal machine principal with full permissions" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: shared. Direct callers: 0. Direct calls: 0. Related files: custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/components/layout/Sidebar.tsx, .framework/functions/_shared/schema-utils.ts, .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 SYSTEM_PRINCIPAL: Principal = {
   id: 'system',
   type: 'machine',
   accountId: null,
-  scopes: ['*:*'],  // All scopes
+  scopes: ['*:*'],
   machineType: 'internal',
   isInternal: true,
   provenance: {
@@ -209,107 +182,125 @@ export const SYSTEM_PRINCIPAL: Principal = {
     invokedAt: new Date().toISOString()
   }
 }
-
-// ─── RESOLUTION FUNCTIONS ────────────────────────────────────────────────────
-
-/**
- * Main entry point for principal resolution. Called by `createHandler` on every
- * HTTP request before the handler runs.
- *
- * Examines request headers in priority order and delegates to the appropriate
- * resolver. Always returns a `Principal` — never throws for missing auth
- * (returns `ANONYMOUS_PRINCIPAL` instead). Throws only on invalid/expired
- * credentials (invalid API key, expired JWT, etc.).
- *
- * Resolution order:
- *   1. `x-api-key` / `X-Api-Key` header → `resolveMachinePrincipal`
- *   2. `x-cron-id` / `X-Cron-Id` header → `resolveCronPrincipal`
- *   3. `x-trigger-id` / `X-Trigger-Id` header → `resolveTriggerPrincipal`
- *   4. `Authorization: Bearer <jwt>` → `resolveHumanPrincipal`
- *   5. (none matched) → `ANONYMOUS_PRINCIPAL`
- *
- * @param event - Raw Netlify event object with `headers` and optional `body`
- * @returns Promise<Principal> — always resolves; throws on invalid credentials
- * @throws Error — on invalid API key, invalid JWT, or missing DB records
- * @inputSpec event.headers: Record<string, string> — HTTP request headers
- * @outputSpec Principal — fully resolved principal with provenance populated
- * @sideEffects DB reads: api_keys, schedules, triggers, people tables via sub-resolvers
- * @calledBy middleware.ts (createHandler) — once per HTTP request
- * @calls resolveMachinePrincipal | resolveCronPrincipal | resolveTriggerPrincipal |
- *   resolveHumanPrincipal
- * @testUnit tests/unit/principal.test.ts — 'resolvePrincipal' describe block
- * @testIntegration tests/integration/auth.test.ts
- */
+// CIL[END chunk_id="principal_system_1784020784"]
+// CIL[BEGIN chunk_id="principal_resolve_1784020784" type="function" identity="resolvePrincipal" parent="none"]
+// CIL[DOC-MACRO purpose="Resolve principal from event headers and authentication"]
+// CIL[DOC-RESPONSIBILITY responsibility="Determine caller identity from various auth methods"]
+// CIL[DOC-CONTEXT module="principal" layer="shared" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Principal" errors="authentication failures" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Checks API key, then (only if isInternalInvokeAuthorized) cron/trigger, then JWT auth in priority order" notable_decisions="[\"cron/trigger headers require INTERNAL_INVOKE_SECRET to be honored, closing a header-spoofing auth bypass\"]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: shared. 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="Requires INTERNAL_INVOKE_SECRET env var for cron/trigger principal resolution."]
+// 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 async function resolvePrincipal(event: any): Promise<Principal> {
-  // Check for API key (external machine)
   const apiKey = event.headers?.['x-api-key'] || event.headers?.['X-Api-Key']
   if (apiKey) {
     return resolveMachinePrincipal(apiKey, event)
   }
-  
-  // Check for internal cron header
-  const cronId = event.headers?.['x-cron-id'] || event.headers?.['X-Cron-Id']
-  if (cronId) {
-    return resolveCronPrincipal(cronId)
-  }
-  
-  // Check for internal trigger header
-  const triggerId = event.headers?.['x-trigger-id'] || event.headers?.['X-Trigger-Id']
-  if (triggerId) {
-    return resolveTriggerPrincipal(triggerId, event)
+
+  // x-cron-id / x-trigger-id let the caller assume a privileged machine
+  // principal by ID alone. They must never be honored unless the request
+  // also proves it came from a trusted internal caller via a shared
+  // secret (see isInternalInvokeAuthorized) — otherwise anyone who learns
+  // a valid schedule/trigger id (e.g. from the admin UI or an audit log)
+  // could impersonate that principal on any endpoint.
+  if (isInternalInvokeAuthorized(event)) {
+    const cronId = event.headers?.['x-cron-id'] || event.headers?.['X-Cron-Id']
+    if (cronId) {
+      return resolveCronPrincipal(cronId)
+    }
+
+    const triggerId = event.headers?.['x-trigger-id'] || event.headers?.['X-Trigger-Id']
+    if (triggerId) {
+      return resolveTriggerPrincipal(triggerId, event)
+    }
   }
-  
-  // Check for JWT Bearer (human)
+
   const authHeader = event.headers?.authorization || event.headers?.Authorization
   if (authHeader?.startsWith('Bearer ')) {
     return resolveHumanPrincipal(authHeader.replace('Bearer ', ''), event)
   }
   
-  // No authentication - return anonymous
   return ANONYMOUS_PRINCIPAL
 }
-
-/**
- * Resolves a machine principal by validating an API key against the DB.
- *
- * Calls the `validate_machine_principal` RPC which checks the key hash,
- * expiry, and active status in one query. Throws on any validation failure —
- * invalid keys are not silently demoted to anonymous.
- *
- * @param apiKey - Raw API key string from `x-api-key` header
- * @param event - Raw Netlify event (used for IP/user-agent provenance)
- * @returns Promise<Principal> — machine principal with scopes from the DB record
- * @throws Error — on invalid, expired, or inactive API key
- * @inputSpec apiKey: string — raw key value; hashed by the RPC for comparison
- * @outputSpec Principal with type='machine', scopes from DB, provenance.sourceType='api_key'
- * @sideEffects DB read: validate_machine_principal RPC (api_keys table)
- * @calledBy resolvePrincipal (api_key branch)
- * @calls adminDb.rpc('validate_machine_principal')
- */
+// CIL[END chunk_id="principal_resolve_1784020784"]
+// CIL[BEGIN chunk_id="principal_resolvemachine_1784020784" type="function" identity="resolveMachinePrincipal" parent="none"]
+// CIL[DOC-MACRO purpose="Resolve machine principal from API key"]
+// CIL[DOC-RESPONSIBILITY responsibility="Validate API key and return machine principal"]
+// CIL[DOC-CONTEXT module="principal" layer="shared" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Principal" errors="invalid API key" side_effects="database query"]
+// CIL[DOC-MICRO logic_summary="Validates machine principal via RPC and builds principal object" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: shared. 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"]
 async function resolveMachinePrincipal(apiKey: string, event: any): Promise<Principal> {
-  // Validate the API key using the database function
-  const { data: rows, error } = await adminDb.rpc('validate_machine_principal', {
-    p_key_value: apiKey,
-    p_required_scope: null  // No specific scope required for resolution
-  })
-  const machine = Array.isArray(rows) ? rows[0] : rows
-  
-  if (error || !machine || !machine.is_valid) {
-    throw new Error(machine?.error_message || 'Invalid or inactive machine principal')
+  const keyPrefix = apiKey.slice(0, 8)
+
+  const { data: rows, error } = await adminDb
+    .from('api_keys')
+    .select('*')
+    .eq('key_prefix', keyPrefix)
+    .eq('is_active', true)
+    .or(`expires_at.is.null,expires_at.gte.${new Date().toISOString()}`)
+    .limit(1)
+
+  if (error || !rows || rows.length === 0) {
+    throw new Error('Invalid or inactive machine principal')
   }
-  
+
+  const key = rows[0]
+  const { verifyApiKey } = await import('./hash-api-key')
+  if (!verifyApiKey(apiKey, key.key_hash)) {
+    throw new Error('Invalid or inactive machine principal')
+  }
+
+  const rateWindowSeconds = (key.config?.rate_limit_window_seconds as number) || 60
+  const rateLimit = key.rate_limit || 100
+  const windowStart = new Date(Date.now() - rateWindowSeconds * 1000).toISOString()
+
+  const { count, error: countError } = await adminDb
+    .from('api_key_usage_logs')
+    .select('*', { count: 'exact', head: true })
+    .eq('api_key_id', key.id)
+    .gte('created_at', windowStart)
+
+  if (!countError && count !== null && count >= rateLimit) {
+    throw new Error('Rate limit exceeded for this API key')
+  }
+
+  await adminDb.from('api_key_usage_logs').insert({
+    api_key_id: key.id,
+    account_id: key.account_id,
+    request_method: event.httpMethod,
+    request_path: event.path,
+    request_ip: getClientIp(event),
+    user_agent: event.headers?.['user-agent'] || event.headers?.['User-Agent'],
+    success: true,
+    metadata: { source: 'resolve_machine_principal' }
+  })
+
   return {
-    id: machine.machine_id,
+    id: key.id,
     type: 'machine',
-    accountId: machine.account_id,
-    scopes: machine.scopes || [],
-    machineType: machine.machine_type as any,
-    isInternal: machine.is_internal,
+    accountId: key.account_id,
+    scopes: key.scopes || [],
+    machineType: (key.machine_type as any) || 'integration',
+    isInternal: key.is_internal,
     provenance: {
       sourceType: 'api_key',
-      createdBy: machine.created_by,
+      createdBy: key.created_by,
       invokedAt: new Date().toISOString(),
-      apiKeyId: machine.machine_id,
+      apiKeyId: key.id,
       ipAddress: getClientIp(event),
       userAgent: event.headers?.['user-agent'] || event.headers?.['User-Agent']
     },
@@ -317,25 +308,23 @@ async function resolveMachinePrincipal(apiKey: string, event: any): Promise<Prin
   }
 }
 
-/**
- * Resolves a machine principal for a scheduled cron job execution.
- *
- * Loads the schedule record (with its linked machine principal) and validates
- * that the schedule creator is still active via `validate_schedule_creator` RPC.
- * Uses the schedule's `delegated_scopes` if set, falling back to the machine's
- * own scopes. This allows scopes to be narrowed per-schedule for least-privilege.
- *
- * @param scheduleId - UUID of the schedule from `x-cron-id` header
- * @returns Promise<Principal> — machine principal with delegated or own scopes
- * @throws Error — on invalid/inactive schedule, missing machine, or validation failure
- * @inputSpec scheduleId: string — valid UUID in the schedules table
- * @outputSpec Principal with type='machine', provenance.sourceType='cron', cronId set
- * @sideEffects DB reads: schedules table, validate_schedule_creator RPC
- * @calledBy resolvePrincipal (cron branch)
- * @calls adminDb.from('schedules'), adminDb.rpc('validate_schedule_creator')
- */
+
+// CIL[END chunk_id="principal_resolvemachine_1784020784"]
+// CIL[BEGIN chunk_id="principal_resolvecron_1784020784" type="function" identity="resolveCronPrincipal" parent="none"]
+// CIL[DOC-MACRO purpose="Resolve machine principal for scheduled execution"]
+// CIL[DOC-RESPONSIBILITY responsibility="Validate schedule and return associated machine principal"]
+// CIL[DOC-CONTEXT module="principal" layer="shared" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Principal" errors="invalid schedule" side_effects="database query"]
+// CIL[DOC-MICRO logic_summary="Validates schedule and creator, returns machine principal" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: shared. 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"]
 async function resolveCronPrincipal(scheduleId: string): Promise<Principal> {
-  // Load the schedule with its machine principal
   const { data: schedule, error: scheduleError } = await adminDb
     .from('schedules')
     .select(`
@@ -349,7 +338,6 @@ async function resolveCronPrincipal(scheduleId: string): Promise<Principal> {
     throw new Error('Invalid or inactive schedule: ' + scheduleId)
   }
   
-  // Validate the schedule creator is still active
   const { data: validation, error: validationError } = await adminDb.rpc('validate_schedule_creator', {
     p_schedule_id: scheduleId
   })
@@ -375,26 +363,22 @@ async function resolveCronPrincipal(scheduleId: string): Promise<Principal> {
     }
   }
 }
-
-/**
- * Resolves a machine principal for an event trigger execution.
- *
- * Loads the trigger record and its associated action. The action must have a
- * `default_machine_principal_id` configured — this is the API key record that
- * provides identity and scopes for the trigger's execution context.
- *
- * @param triggerId - UUID of the trigger from `x-trigger-id` header
- * @param event - Raw Netlify event (used for eventId and provenance)
- * @returns Promise<Principal> — machine principal from the trigger's action config
- * @throws Error — on invalid trigger, missing action config, or missing machine
- * @inputSpec triggerId: string — valid UUID in the triggers table
- * @outputSpec Principal with type='machine', provenance.sourceType='trigger', triggerId set
- * @sideEffects DB reads: triggers table, api_keys table
- * @calledBy resolvePrincipal (trigger branch)
- * @calls adminDb.from('triggers'), adminDb.from('api_keys')
- */
+// CIL[END chunk_id="principal_resolvecron_1784020784"]
+// CIL[BEGIN chunk_id="principal_resolvetrigger_1784020784" type="function" identity="resolveTriggerPrincipal" parent="none"]
+// CIL[DOC-MACRO purpose="Resolve machine principal for trigger execution"]
+// CIL[DOC-RESPONSIBILITY responsibility="Validate trigger and return configured machine principal"]
+// CIL[DOC-CONTEXT module="principal" layer="shared" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Principal" errors="invalid trigger" side_effects="database query"]
+// CIL[DOC-MICRO logic_summary="Validates trigger, finds action's machine principal, returns principal" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: shared. 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"]
 async function resolveTriggerPrincipal(triggerId: string, event: any): Promise<Principal> {
-  // Load the trigger
   const { data: trigger, error: triggerError } = await adminDb
     .from('triggers')
     .select(`
@@ -408,7 +392,6 @@ async function resolveTriggerPrincipal(triggerId: string, event: any): Promise<P
     throw new Error('Invalid trigger: ' + triggerId)
   }
   
-  // Get the action's default machine principal
   const action = trigger.action
   if (!action?.default_machine_principal_id) {
     throw new Error('Trigger action has no machine principal configured')
@@ -440,47 +423,36 @@ async function resolveTriggerPrincipal(triggerId: string, event: any): Promise<P
     }
   }
 }
-
-/**
- * Resolves a human principal from a Supabase JWT Bearer token.
- *
- * Validates the token with `supabase.auth.getUser`, resolves the internal
- * person UUID from the auth user, then loads the person's role via `role_id` FK.
- * Role slugs are the source of truth for `PermissionEngine.isSystemAdmin` checks.
- *
- * If the person's `auth_uid` is not yet set, it is backfilled on first login
- * (side effect on the people table).
- *
- * @param token - Raw JWT string extracted from `Authorization: Bearer <token>`
- * @param event - Raw Netlify event (used for IP/user-agent provenance)
- * @returns Promise<Principal> — human principal with roles from the DB
- * @throws Error('Invalid authentication token') — on expired or invalid JWT
- * @throws Error('Person not found') — if people record doesn't exist for this auth user
- * @inputSpec token: string — valid non-expired Supabase JWT
- * @outputSpec Principal with type='human', roles from people.role_id → roles.slug
- * @sideEffects DB reads: supabase.auth.getUser, people table (with role join)
- * @sideEffects DB write (conditional): people.auth_uid backfill on first login
- * @calledBy resolvePrincipal (jwt branch)
- * @calls supabase.auth.getUser, resolveInternalPersonId, adminDb.from('people')
- * @testIntegration tests/integration/auth.test.ts
- */
+// CIL[END chunk_id="principal_resolvetrigger_1784020784"]
+// CIL[BEGIN chunk_id="principal_resolvehuman_1784020784" type="function" identity="resolveHumanPrincipal" parent="none"]
+// CIL[DOC-MACRO purpose="Resolve human principal from JWT token"]
+// CIL[DOC-RESPONSIBILITY responsibility="Validate JWT and return human principal with roles"]
+// CIL[DOC-CONTEXT module="principal" layer="shared" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Principal" errors="invalid token" side_effects="database query"]
+// CIL[DOC-MICRO logic_summary="Validates JWT, finds person record, builds principal with 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: shared. 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"]
 async function resolveHumanPrincipal(token: string, event: any): Promise<Principal> {
-  // Validate JWT with Supabase
   const { data: { user }, error } = await supabase.auth.getUser(token)
   
   if (error || !user) {
     return ANONYMOUS_PRINCIPAL
   }
   
-  // Resolve internal person ID from auth user
   const personId = await resolveInternalPersonId(user.id, user.email)
+  const userDb = getUserDb(token)
   
-  // Load person details
-  const { data: person, error: personError } = await adminDb
+  const { data: person, error: personError } = await userDb
     .from('people')
-    .select('*, role:roles!role_id(slug, name, is_system, is_protected)')
+    .select('*, role:roles(id, slug, name, is_system, permissions)')
     .eq('id', personId)
-    .maybeSingle()
+    .single()
   
   if (personError) {
     throw new Error('Person lookup error: ' + personError.message + ' (id: ' + personId + ')')
@@ -489,8 +461,8 @@ async function resolveHumanPrincipal(token: string, event: any): Promise<Princip
     throw new Error('Person not found: ' + personId)
   }
   
-  // Resolve role from role_id
-  const roleSlugs = person.role?.slug ? [person.role.slug] : []
+  const role = Array.isArray(person.role) ? person.role[0] : person.role
+  const roleSlugs = role?.slug ? [role.slug] : []
   
   return {
     id: personId,
@@ -501,7 +473,7 @@ async function resolveHumanPrincipal(token: string, event: any): Promise<Princip
     email: person.email,
     provenance: {
       sourceType: 'jwt',
-      createdBy: personId,  // Self-created through auth
+      createdBy: personId,
       invokedAt: new Date().toISOString(),
       ipAddress: getClientIp(event),
       userAgent: event.headers?.['user-agent'] || event.headers?.['User-Agent']
@@ -509,32 +481,22 @@ async function resolveHumanPrincipal(token: string, event: any): Promise<Princip
     authContext: { jwt: token }
   }
 }
-
-/**
- * Resolves the internal people table UUID from a Supabase auth user ID.
- *
- * Lookup strategy (in order):
- *   1. Match by `email` — most reliable; also backfills `auth_uid` if missing
- *   2. Fallback: match by `auth_uid` directly
- *   3. Last resort: return `authUserId` as-is (person not yet in people table)
- *
- * The email-first strategy handles the case where a person was created manually
- * in the people table before the user completed Supabase Auth registration.
- *
- * @param authUserId - UUID from Supabase auth.users (supabase.auth.getUser result)
- * @param email - Email address from the Supabase auth user (optional but preferred)
- * @returns Promise<string> — internal person UUID, or authUserId as fallback
- * @throws never — graceful fallback to authUserId on any lookup failure
- * @inputSpec authUserId: string — valid Supabase auth user UUID
- * @inputSpec email: string | undefined — used for primary lookup
- * @outputSpec string — internal people.id UUID
- * @sideEffects DB reads: people table (by email, then by auth_uid)
- * @sideEffects DB write (conditional): people.auth_uid backfill when found by email
- * @calledBy resolveHumanPrincipal
- * @calls adminDb.from('people')
- */
+// CIL[END chunk_id="principal_resolvehuman_1784020784"]
+// CIL[BEGIN chunk_id="principal_resolveinternal_1784020784" type="function" identity="resolveInternalPersonId" parent="none"]
+// CIL[DOC-MACRO purpose="Resolve internal person ID from auth user ID and email"]
+// CIL[DOC-RESPONSIBILITY responsibility="Map external auth ID to internal person record"]
+// CIL[DOC-CONTEXT module="principal" layer="shared" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="internal person ID" errors="none" side_effects="database update"]
+// CIL[DOC-MICRO logic_summary="Looks up by email first, then auth ID, updates auth_uid if missing" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: shared. 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"]
 async function resolveInternalPersonId(authUserId: string, email?: string): Promise<string> {
-  // Try to find by email first (more reliable)
   if (email) {
     const { data: byEmail } = await adminDb
       .from('people')
@@ -543,7 +505,6 @@ async function resolveInternalPersonId(authUserId: string, email?: string): Prom
       .maybeSingle()
     
     if (byEmail) {
-      // Update auth_uid if not set
       if (!byEmail.auth_uid) {
         await adminDb
           .from('people')
@@ -554,7 +515,6 @@ async function resolveInternalPersonId(authUserId: string, email?: string): Prom
     }
   }
   
-  // Fallback: try by auth_uid
   const { data: byAuthId } = await adminDb
     .from('people')
     .select('id')
@@ -563,28 +523,23 @@ async function resolveInternalPersonId(authUserId: string, email?: string): Prom
   
   if (byAuthId) return byAuthId.id
   
-  // Not found - return the auth ID as fallback
   return authUserId
 }
-
-// ─── HELPER FUNCTIONS ────────────────────────────────────────────────────────
-
-/**
- * Extracts the client IP address from event headers.
- *
- * Checks headers in priority order: `x-forwarded-for` (load balancer),
- * `x-real-ip` (proxy), then `requestContext.identity.sourceIp` (API Gateway).
- * Returns `undefined` if none are present.
- *
- * @param event - Raw Netlify event object
- * @returns string | undefined — first non-empty IP found
- * @throws never
- * @inputSpec event.headers: Record<string, string> | undefined
- * @outputSpec string — IPv4 or IPv6 address; may contain comma-separated list
- *   from x-forwarded-for (take first value if parsing is needed)
- * @sideEffects none
- * @calledBy resolveMachinePrincipal, resolveHumanPrincipal (for provenance)
- */
+// CIL[END chunk_id="principal_resolveinternal_1784020784"]
+// CIL[BEGIN chunk_id="principal_getclientip_1784020784" type="function" identity="getClientIp" parent="none"]
+// CIL[DOC-MACRO purpose="Extract client IP address from event headers"]
+// CIL[DOC-RESPONSIBILITY responsibility="Parse various IP header formats for provenance"]
+// CIL[DOC-CONTEXT module="principal" layer="shared" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="IP string or undefined" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Checks common IP headers in priority order" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: shared. 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"]
 function getClientIp(event: any): string | undefined {
   return event.headers?.['x-forwarded-for'] ||
          event.headers?.['X-Forwarded-For'] ||
@@ -592,157 +547,109 @@ function getClientIp(event: any): string | undefined {
          event.headers?.['X-Real-Ip'] ||
          event.requestContext?.identity?.sourceIp
 }
-
-/**
- * Checks whether a machine principal has been granted a specific scope.
- *
- * Scope matching supports three patterns:
- *   1. Exact: `'items:read'` matches only `'items:read'`
- *   2. Wildcard action: `'items:*'` matches `'items:read'`, `'items:write'`, etc.
- *   3. Global wildcard: `'*:*'` matches any scope
- *
- * Returns `false` for non-machine principals — role-based checks use `humanHasRole`.
- *
- * @param principal - The principal to check
- * @param scope - The required scope string in `'resource:action'` format
- * @returns boolean — true if any of the principal's scopes grant the required scope
- * @throws never
- * @inputSpec principal.type: 'machine' — returns false for human principals
- * @inputSpec scope: string — must be in 'resource:action' format
- * @inputSpec principal.scopes: string[] — list of granted scope strings
- * @outputSpec boolean
- * @sideEffects none
- * @calledBy permissions.ts (checkMachineScope), any custom code doing scope checks
- * @testUnit tests/unit/principal.test.ts — 'machineHasScope' describe block
- *
- * @example
- * ```ts
- * import { machineHasScope } from '../_shared/index'
- * if (!machineHasScope(principal, 'items:write')) {
- *   return { error: 'Insufficient scope' }
- * }
- * ```
- */
+// CIL[END chunk_id="principal_getclientip_1784020784"]
+// CIL[BEGIN chunk_id="principal_machinescope_1784020784" type="function" identity="machineHasScope" parent="none"]
+// CIL[DOC-MACRO purpose="Check if machine principal has required scope"]
+// CIL[DOC-RESPONSIBILITY responsibility="Validate machine principal permissions"]
+// CIL[DOC-CONTEXT module="principal" layer="shared" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="boolean" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Checks exact scope, resource wildcard, or global wildcard" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: shared. 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 function machineHasScope(principal: Principal, scope: string): boolean {
   if (principal.type !== 'machine') return false
   
   const scopes = principal.scopes || []
   const [resource, action] = scope.split(':')
   
-  // Exact match
   if (scopes.includes(scope)) return true
   
-  // Wildcard resource
   if (scopes.includes(`${resource}:*`)) return true
   
-  // Global wildcard
   if (scopes.includes('*:*')) return true
   
   return false
 }
-
-/**
- * Checks whether a human principal has been assigned a specific role.
- *
- * Returns `false` for non-human (machine) principals — scope checks use
- * `machineHasScope`. Role slugs come from `people.role_id → roles.slug`
- * and are loaded at resolution time in `resolveHumanPrincipal`.
- *
- * @param principal - The principal to check
- * @param roleSlug - The role slug to look for (e.g. 'system_admin', 'agent')
- * @returns boolean — true if principal.roles includes the given slug
- * @throws never
- * @inputSpec principal.type: 'human' — returns false for machine principals
- * @inputSpec roleSlug: string — must match exactly (case-sensitive)
- * @inputSpec principal.roles: string[] | undefined
- * @outputSpec boolean
- * @sideEffects none
- * @calledBy isSystemAdmin, permissions.ts (PermissionEngine.isSystemAdmin)
- * @testUnit tests/unit/principal.test.ts — 'humanHasRole' describe block
- */
+// CIL[END chunk_id="principal_machinescope_1784020784"]
+// CIL[BEGIN chunk_id="principal_humanrole_1784020784" type="function" identity="humanHasRole" parent="none"]
+// CIL[DOC-MACRO purpose="Check if human principal has required role"]
+// CIL[DOC-RESPONSIBILITY responsibility="Validate human principal role membership"]
+// CIL[DOC-CONTEXT module="principal" layer="shared" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="boolean" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Checks if principal type is human and role is in roles array" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: shared. 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 function humanHasRole(principal: Principal, roleSlug: string): boolean {
   if (principal.type !== 'human') return false
   return principal.roles?.includes(roleSlug) || false
 }
-
-/**
- * Returns true if the principal holds the `system_admin` role.
- *
- * This is the canonical system admin check used by `middleware.ts`
- * (`requireSystemContextWithAudit`) and re-exported from `permissions.ts`
- * (`PermissionEngine.isSystemAdmin`). system_admin bypasses all three
- * permission surfaces.
- *
- * @param principal - The principal to check
- * @returns boolean — true only if type='human' and roles includes 'system_admin'
- * @throws never
- * @inputSpec principal: Principal — any resolved principal
- * @outputSpec boolean — false for machine principals, anonymous, or missing roles
- * @sideEffects none
- * @calledBy middleware.ts (requireSystemContextWithAudit), permissions.ts (PermissionEngine),
- *   any handler doing system-admin-only checks
- * @calls humanHasRole
- * @testUnit tests/unit/principal.test.ts — 'isSystemAdmin' describe block
- */
+// CIL[END chunk_id="principal_humanrole_1784020784"]
+// CIL[BEGIN chunk_id="principal_systemadmin_1784020784" type="function" identity="isSystemAdmin" parent="none"]
+// CIL[DOC-MACRO purpose="Check if principal is system administrator"]
+// CIL[DOC-RESPONSIBILITY responsibility="Validate system admin role for privileged operations"]
+// CIL[DOC-CONTEXT module="principal" layer="shared" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="boolean" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Checks if human principal has system_admin 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: shared. 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 function isSystemAdmin(principal: Principal): boolean {
   return humanHasRole(principal, 'system_admin')
 }
-
-/**
- * Selects the correct Supabase database client for the given principal.
- *
- * This is the only place in the codebase where the two-client selection
- * decision is made. The result is stored in `ctx.db` and used for all
- * subsequent DB queries in the request.
- *
- * Selection logic:
- *   - Human principal with JWT → `getUserDb(jwt)` — enforces RLS
- *   - Machine principal → `adminDb` — RLS policies check machine ID in policies
- *   - Anonymous → `adminDb` (but anonymous requests are rejected before DB access)
- *
- * @param principal - The resolved principal
- * @returns SupabaseClient — RLS-scoped for humans, admin for machines
- * @throws never
- * @inputSpec principal.type: 'human' | 'machine'
- * @inputSpec principal.authContext.jwt: string | undefined — required for human client
- * @outputSpec SupabaseClient — getUserDb result (human) or adminDb (machine)
- * @sideEffects none (client construction only)
- * @calledBy middleware.ts (createHandler — `const ctxDb = getPrincipalDb(principal)`)
- * @calls getUserDb (db.ts), adminDb (db.ts)
- * @testUnit tests/unit/principal.test.ts — 'getPrincipalDb' describe block
- */
+// CIL[END chunk_id="principal_systemadmin_1784020784"]
+// CIL[BEGIN chunk_id="principal_getdb_1784020784" type="function" identity="getPrincipalDb" parent="none"]
+// CIL[DOC-MACRO purpose="Get appropriate database connection for principal"]
+// CIL[DOC-RESPONSIBILITY responsibility="Return user DB for humans, admin DB for machines"]
+// CIL[DOC-CONTEXT module="principal" layer="shared" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="database connection" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Returns user DB for authenticated humans, admin DB otherwise" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: shared. 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 function getPrincipalDb(principal: Principal) {
   if (principal.type === 'human' && principal.authContext?.jwt) {
     return getUserDb(principal.authContext.jwt)
   }
   
-  // Machines use admin client - RLS policies check their ID
   return adminDb
 }
-
-/**
- * Serializes a principal into a safe, structured object for audit log entries.
- *
- * Strips `authContext` entirely (never log JWT or API key values). The returned
- * object is safe to store in the `metadata` JSONB column of the `logs` table.
- *
- * @param principal - Any resolved principal including ANONYMOUS_PRINCIPAL
- * @returns object — audit-safe principal summary
- * @throws never
- * @inputSpec principal: Principal — any resolved principal
- * @outputSpec { id, type, account_id } + role/scope fields depending on type
- * @outputSpec authContext is NEVER included in output
- * @sideEffects none
- * @calledBy audit.ts (emitAudit — in metadata.principal)
- * @testUnit tests/unit/principal.test.ts — 'formatPrincipalForAudit' describe block
- *
- * @example
- * ```ts
- * await emitAudit(ctx, 'items.delete', { type: 'item', id }, {
- *   principal_snapshot: formatPrincipalForAudit(ctx.principal)
- * })
- * ```
- */
+// CIL[END chunk_id="principal_getdb_1784020784"]
+// CIL[BEGIN chunk_id="principal_audit_1784020784" type="function" identity="formatPrincipalForAudit" parent="none"]
+// CIL[DOC-MACRO purpose="Format principal for audit logging"]
+// CIL[DOC-RESPONSIBILITY responsibility="Create audit-safe representation of principal"]
+// CIL[DOC-CONTEXT module="principal" layer="shared" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="audit object" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Returns principal fields formatted for audit logs" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: shared. 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 function formatPrincipalForAudit(principal: Principal): object {
   return {
     id: principal.id,
@@ -760,3 +667,4 @@ export function formatPrincipalForAudit(principal: Principal): object {
     provenance: principal.provenance
   }
 }
+// CIL[END chunk_id="principal_audit_1784020784"]