spine-framework 0.3.124 → 0.3.126

package/.framework/functions/api-keys.ts

@@ -1,59 +1,69 @@
-/**
- * @module api-keys
- * @audience core-contributor
- * @layer api-handler
- * @stability stable
- *
- * Management and validation API for the `api_keys` table. API keys are
- * issued per-integration and optionally scoped to specific permissions.
- * Key material is generated and stored by the `create_api_key` Postgres
- * RPC, which handles hashing internally. Validation also delegates to the
- * `validate_api_key` RPC.
- *
- * **Routed by:** `GET/POST /.netlify/functions/api-keys`
- *
- * **Actions:**
- * | method | ?action    | handler       |
- * |--------|------------|---------------|
- * | POST   | validate   | validate      |
- * | POST   | revoke     | revoke        |
- * | GET    | usage-logs | listUsageLogs |
- * | GET    | ?id        | get           |
- * | GET    | (default)  | list          |
- * | POST   | —          | create        |
- *
- * **Authorization:** All operations use `ctx.db` (RLS-scoped). Account context
- * required for creates. No PATCH/DELETE — use `revoke` for deactivation.
- *
- * INVARIANT: Raw key material is never stored. Only the hash is persisted.
- *   `create` returns the plaintext key once via RPC response.
- * INVARIANT: `revoke` soft-deactivates by setting `is_active = false`.
- *
- * @seeAlso integrations.ts (integration_id FK on api_keys)
- * @seeAlso audit.ts (emitLog for api_key.* events)
- */
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ 
+
+
+
+
+
+
+
+// CIL[BEGIN chunk_id="api-keys_moduleheader_1783969696" type="module_header" identity="imports" parent="none"]
+// CIL[DOC-MACRO purpose="Import dependencies for API keys module"]
+// CIL[DOC-RESPONSIBILITY responsibility="Import middleware, audit, and permissions utilities"]
+// CIL[DOC-CONTEXT module="api-keys" layer="backend_functions" related_files="[\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/migrations/015_simplify_apps_table.sql\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/functions/_shared/principal.ts\",\".framework/functions/_shared/schema-utils.ts\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="imported_modules" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Imports required dependencies for API key management functions" 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: backend_functions. Direct callers: 0. Direct calls: 0. Related files: custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/migrations/015_simplify_apps_table.sql, .framework/src/pages/admin/TypeDetailPage.tsx, .framework/functions/_shared/principal.ts, .framework/functions/_shared/schema-utils.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"]
 
 import { createHandler } from './_shared/middleware'
+import { adminDb } from './_shared/db'
 import { emitLog } from './_shared/audit'
+import { isSystemAdmin } from './_shared/principal'
 import { sanitizeRecordData } from './_shared/permissions'
-
-// ─── HANDLERS ─────────────────────────────────────────────────────────────────
-
-// ─── CHUNK_START: API_KEYS_LIST ──────────────────────────────────────────────
-/**
- * @chunk-id    API_KEYS_LIST_1_0_0
- * @version     1.0.0
- * @hash        f825d8f4bbabe21071b61fe41e5e4e1b87482d501bf4078fab70906b7a5f5e78
- * @macro       API Keys List Handler
- * @micro       Lists API keys with filtering, pagination, and joins
- * @inputs      ctx: CoreContext — Request context with principal and database
- * @inputs      _body: any — Request body (unused for GET)
- * @outputs     Array of sanitized API key records with integration joins
- * @depends-on  [createHandler, sanitizeRecordData]
- * @depended-by [Netlify function routing]
- * @side-effects [DB queries, permission sanitization]
- * @tags        api-keys, list, crud, pagination
- */
+import { hashApiKey } from './_shared/hash-api-key'
+// CIL[END chunk_id="api-keys_moduleheader_1783969696"]
+// CIL[BEGIN chunk_id="api-keys_list_1783969696" type="function" identity="list" parent="none"]
+// CIL[DOC-MACRO purpose="List API keys with filtering"]
+// CIL[DOC-RESPONSIBILITY responsibility="Retrieve and filter API keys by various criteria"]
+// CIL[DOC-CONTEXT module="api-keys" layer="backend_functions" related_files="[\".framework/functions/_shared/schema-utils.ts\",\".framework/src/components/ui/dialog.tsx\",\".framework/functions/_shared/principal.ts\",\".framework/src/components/ui/table-primitives.tsx\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="sanitized_api_keys" errors="auth_errors,db_errors" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Query API keys with filters, sanitize data, return paginated results" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: backend_functions. Direct callers: 3. Direct calls: 0. Related files: .framework/functions/_shared/schema-utils.ts, .framework/src/components/ui/dialog.tsx, .framework/functions/_shared/principal.ts, .framework/src/components/ui/table-primitives.tsx, .framework/src/pages/admin/TypeDetailPage.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 3. Total affected: 3."]
+// 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 { integration_id, key_type, is_active, expires_before, expires_after, limit = 100, offset = 0 } = ctx.query || {}
 
@@ -61,13 +71,11 @@ export const list = createHandler(async (ctx, _body) => {
     throw new Error('Account context required')
   }
 
-  let query = ctx.db
+  const db = isSystemAdmin(ctx.principal) ? adminDb : ctx.db
+
+  let query = db
     .from('api_keys')
-    .select(`
-      *,
-      integration:integrations(id, name, provider, integration_type),
-      created_by_person:people(id, full_name, email)
-    `)
+    .select('*')
     .order('created_at', { ascending: false })
 
   if (integration_id) {
@@ -100,23 +108,21 @@ export const list = createHandler(async (ctx, _body) => {
 
   return sanitized
 })
-// ─── CHUNK_END: API_KEYS_LIST ────────────────────────────────────────────────
-
-// ─── CHUNK_START: API_KEYS_GET ──────────────────────────────────────────────
-/**
- * @chunk-id    API_KEYS_GET_1_0_0
- * @version     1.0.0
- * @hash        357f926aeb833ad0ca755e48350534771f491890645134a1b43d2f2a8e4be037
- * @macro       API Key Get Handler
- * @micro       Returns a single API key record with joins (no raw key material)
- * @inputs      ctx: CoreContext — Request context with principal and database
- * @inputs      _body: any — Request body (unused for GET)
- * @outputs     Sanitized API key record with integration and createdBy joins
- * @depends-on  [createHandler, sanitizeRecordData]
- * @depended-by [Netlify function routing]
- * @side-effects [DB single row query, permission sanitization]
- * @tags        api-keys, get, crud, single-record
- */
+// CIL[END chunk_id="api-keys_list_1783969696"]
+// CIL[BEGIN chunk_id="api-keys_get_1783969696" type="function" identity="get" parent="none"]
+// CIL[DOC-MACRO purpose="Get single API key by ID"]
+// CIL[DOC-RESPONSIBILITY responsibility="Retrieve individual API key record with related data"]
+// CIL[DOC-CONTEXT module="api-keys" layer="backend_functions" 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="sanitized_api_key" errors="not_found,db_errors" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Query API key by ID with integration and creator details, sanitize" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: backend_functions. 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 || {}
 
@@ -124,13 +130,11 @@ export const get = createHandler(async (ctx, _body) => {
     throw new Error('API key ID is required')
   }
 
-  const { data, error: err } = await ctx.db
+  const db = isSystemAdmin(ctx.principal) ? adminDb : ctx.db
+
+  const { data, error: err } = await db
     .from('api_keys')
-    .select(`
-      *,
-      integration:integrations(id, name, provider, integration_type),
-      created_by_person:people(id, full_name, email)
-    `)
+    .select('*')
     .eq('id', id)
     .single()
 
@@ -138,25 +142,35 @@ export const get = createHandler(async (ctx, _body) => {
 
   return await sanitizeRecordData(ctx, data, 'api_key')
 })
-// ─── CHUNK_END: API_KEYS_GET ────────────────────────────────────────────────
-
-// ─── CHUNK_START: API_KEYS_CREATE ──────────────────────────────────────────────
-/**
- * @chunk-id    API_KEYS_CREATE_1_0_0
- * @version     1.0.0
- * @hash        8d00c97111cddebc2b3821a1fee3e6cf4c6b7c55fc20cd19d70865d728c3387c
- * @macro       API Key Create Handler
- * @micro       Creates new API key via RPC with validation and audit logging
- * @inputs      ctx: CoreContext — Request context with principal and database
- * @inputs      body: object — API key configuration data
- * @outputs     RPC result containing api_key_id and plaintext key_value
- * @depends-on  [createHandler, emitLog]
- * @depended-by [Netlify function routing]
- * @side-effects [RPC call, audit logging]
- * @tags        api-keys, create, crud, rpc, audit
- */
+// CIL[END chunk_id="api-keys_get_1783969696"]
+// CIL[BEGIN chunk_id="api-keys_create_1783969696" type="function" identity="create" parent="none"]
+// CIL[DOC-MACRO purpose="Create new API key with validation"]
+// CIL[DOC-RESPONSIBILITY responsibility="Generate API key with permissions and audit logging"]
+// CIL[DOC-CONTEXT module="api-keys" layer="backend_functions" related_files="[\".framework/functions/_shared/schema-utils.ts\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/src/pages/admin/RolesPage.tsx\",\".framework/src/components/ui/dialog.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="created_api_key" errors="validation_errors,db_errors" side_effects="db_write,audit_log"]
+// CIL[DOC-MICRO logic_summary="Call stored procedure to create key, log creation event" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="external_symbols_unknown"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: backend_functions. Direct callers: 4. Direct calls: 0. Related files: .framework/functions/_shared/schema-utils.ts, .framework/src/pages/admin/TypeDetailPage.tsx, .framework/src/pages/admin/RolesPage.tsx, .framework/src/components/ui/dialog.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 4. Total affected: 5."]
+// 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 { integration_id, name, key_type, key_prefix, permissions, rate_limit, expires_at, metadata } = body
+  const {
+    integration_id,
+    app_id,
+    name,
+    key_type,
+    permissions,
+    scopes,
+    rate_limit,
+    expires_at,
+    metadata,
+    machine_type,
+    is_internal
+  } = body
 
   if (!name) {
     throw new Error('name is required')
@@ -166,46 +180,65 @@ export const create = createHandler(async (ctx, body) => {
     throw new Error('Account context required')
   }
 
+  const slug = body.slug || name.toLowerCase().replace(/\s+/g, '-').replace(/[^a-z0-9-]/g, '')
+
+  const rawKey = `sk_${crypto.randomUUID().replace(/-/g, '')}`
+  const { key_prefix, key_hash } = hashApiKey(rawKey)
+
+  const insertData = {
+    integration_id: integration_id || null,
+    app_id: app_id || ctx.appId || null,
+    account_id: ctx.accountId,
+    slug,
+    name,
+    key_prefix,
+    key_hash,
+    key_type: key_type || 'inbound',
+    permissions: permissions || [],
+    scopes: scopes || [],
+    rate_limit: rate_limit || 100,
+    expires_at: expires_at || null,
+    metadata: metadata || {},
+    machine_type: machine_type || 'integration',
+    is_internal: is_internal || false,
+    is_active: true,
+    created_by: ctx.principal?.id || null
+  }
+
   const { data, error: err } = await ctx.db
-    .rpc('create_api_key', {
-      integration_id,
-      name,
-      key_type: key_type || 'private',
-      key_prefix: key_prefix || 'sk_',
-      permissions: permissions || {},
-      rate_limit: rate_limit || 1000,
-      expires_at,
-      metadata: metadata || {},
-      created_by: ctx.principal?.id,
-      account_id: ctx.accountId
-    })
+    .from('api_keys')
+    .insert(insertData)
+    .select('id, name, key_type, rate_limit, expires_at, is_active, created_at')
+    .single()
 
   if (err) throw err
 
-  await emitLog(ctx, 'api_key.created', 
-    { type: 'api_key', id: data[0]?.api_key_id }, 
-    { after: { name, key_type, rate_limit } }
+  await emitLog(ctx, 'api_key.created',
+    { type: 'api_key', id: data.id },
+    { after: { name, key_type, rate_limit, integration_id } }
   )
 
-  return data
+  return {
+    ...data,
+    raw_key: rawKey,
+    warning: 'Store this key now. It will not be shown again.'
+  }
 })
-// ─── CHUNK_END: API_KEYS_CREATE ────────────────────────────────────────────────
-
-// ─── CHUNK_START: API_KEYS_VALIDATE ──────────────────────────────────────────────
-/**
- * @chunk-id    API_KEYS_VALIDATE_1_0_0
- * @version     1.0.0
- * @hash        05791f9b2c23bfebed01dffaa1430e896b89d311c5a51409704d731200eb621a
- * @macro       API Key Validation Handler
- * @micro       Validates API key and checks permissions via RPC
- * @inputs      ctx: CoreContext — Request context with principal and database
- * @inputs      body: object — key_value and optional required_permissions
- * @outputs     RPC validation result with is_valid, account_id, permissions
- * @depends-on  [createHandler]
- * @depended-by [Netlify function routing, middleware]
- * @side-effects [RPC validation call]
- * @tags        api-keys, validate, rpc, authentication
- */
+// CIL[END chunk_id="api-keys_create_1783969696"]
+// CIL[BEGIN chunk_id="api-keys_validate_1783969696" type="function" identity="validate" parent="none"]
+// CIL[DOC-MACRO purpose="Validate API key and permissions"]
+// CIL[DOC-RESPONSIBILITY responsibility="Check API key validity and required permissions"]
+// CIL[DOC-CONTEXT module="api-keys" layer="backend_functions" related_files="[\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/src/pages/admin/RolesPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/functions/_shared/principal.ts\",\".framework/src/components/ui/dialog.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="validation_result" errors="validation_errors,db_errors" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Call stored procedure to validate key against permissions" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="external_symbols_unknown"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: backend_functions. Direct callers: 1. Direct calls: 0. Related files: custom/apps/portal/pages/ContentPage.tsx, .framework/src/pages/admin/RolesPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/functions/_shared/principal.ts, .framework/src/components/ui/dialog.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 1. Total affected: 1."]
+// 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 validate = createHandler(async (ctx, body) => {
   const { key_value, required_permissions } = body
 
@@ -213,33 +246,64 @@ export const validate = createHandler(async (ctx, body) => {
     throw new Error('key_value is required')
   }
 
-  const { data, error: err } = await ctx.db
-    .rpc('validate_api_key', {
-      key_value,
-      required_permissions: required_permissions || {}
-    })
+  const keyPrefix = key_value.slice(0, 8)
+
+  const { data: rows, error: err } = await ctx.db
+    .from('api_keys')
+    .select('*')
+    .eq('key_prefix', keyPrefix)
+    .eq('is_active', true)
+    .or('expires_at.is.null,expires_at.gte.now()')
 
   if (err) throw err
+  if (!rows || rows.length === 0) {
+    return { is_valid: false, error: 'Invalid or inactive API key' }
+  }
 
-  return data
+  const { verifyApiKey } = await import('./_shared/hash-api-key')
+
+  for (const key of rows) {
+    if (verifyApiKey(key_value, key.key_hash)) {
+      const hasPermissions = !required_permissions || required_permissions.length === 0 ||
+        (key.permissions || []).some((p: string) => required_permissions.includes(p))
+
+      if (!hasPermissions) {
+        return {
+          is_valid: false,
+          error: 'Insufficient permissions',
+          api_key_id: key.id
+        }
+      }
+
+      return {
+        is_valid: true,
+        api_key_id: key.id,
+        integration_id: key.integration_id,
+        app_id: key.app_id,
+        account_id: key.account_id,
+        scopes: key.scopes,
+        permissions: key.permissions
+      }
+    }
+  }
+
+  return { is_valid: false, error: 'Invalid or inactive API key' }
 })
-// ─── CHUNK_END: API_KEYS_VALIDATE ────────────────────────────────────────────────
-
-// ─── CHUNK_START: API_KEYS_REVOKE ──────────────────────────────────────────────
-/**
- * @chunk-id    API_KEYS_REVOKE_1_0_0
- * @version     1.0.0
- * @hash        3302286a12c1315616470fcfbd3cbdc8dcf63dd00211a71159f3325bab95607a
- * @macro       API Key Revoke Handler
- * @micro       Soft-deactivates API key with validation and audit logging
- * @inputs      ctx: CoreContext — Request context with principal and database
- * @inputs      body: object — API key ID to revoke
- * @outputs     Updated API key record with is_active: false
- * @depends-on  [createHandler, emitLog]
- * @depended-by [Netlify function routing]
- * @side-effects [DB update, audit logging]
- * @tags        api-keys, revoke, crud, audit
- */
+// CIL[END chunk_id="api-keys_validate_1783969696"]
+// CIL[BEGIN chunk_id="api-keys_revoke_1783969696" type="function" identity="revoke" parent="none"]
+// CIL[DOC-MACRO purpose="Revoke API key by deactivating"]
+// CIL[DOC-RESPONSIBILITY responsibility="Deactivate API key with audit logging"]
+// CIL[DOC-CONTEXT module="api-keys" layer="backend_functions" related_files="[\".framework/src/pages/admin/RolesPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="revoked_api_key" errors="not_found,db_errors" side_effects="db_write,audit_log"]
+// CIL[DOC-MICRO logic_summary="Set is_active=false, log revocation event" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: backend_functions. Direct callers: 1. Direct calls: 0. Related files: .framework/src/pages/admin/RolesPage.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 1. Total affected: 1."]
+// 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 revoke = createHandler(async (ctx, body) => {
   const { id } = body
 
@@ -263,23 +327,21 @@ export const revoke = createHandler(async (ctx, body) => {
 
   return data
 })
-// ─── CHUNK_END: API_KEYS_REVOKE ────────────────────────────────────────────────
-
-// ─── CHUNK_START: API_KEYS_LIST_USAGE_LOGS ──────────────────────────────────────────────
-/**
- * @chunk-id    API_KEYS_LIST_USAGE_LOGS_1_0_0
- * @version     1.0.0
- * @hash        f21e004490dd983c8f20dc1d1f4db33e158334d19e38a4ace5e99389a8a96ded
- * @macro       API Key Usage Logs Handler
- * @micro       Lists paginated API key usage logs with filtering and joins
- * @inputs      ctx: CoreContext — Request context with principal and database
- * @inputs      _body: any — Request body (unused for GET)
- * @outputs     Array of usage log records with api_key joins
- * @depends-on  [createHandler]
- * @depended-by [Netlify function routing]
- * @side-effects [DB queries with filtering]
- * @tags        api-keys, usage-logs, pagination, monitoring
- */
+// CIL[END chunk_id="api-keys_revoke_1783969696"]
+// CIL[BEGIN chunk_id="api-keys_listusagelogs_1783969696" type="function" identity="listUsageLogs" parent="none"]
+// CIL[DOC-MACRO purpose="List API key usage logs"]
+// CIL[DOC-RESPONSIBILITY responsibility="Retrieve API key usage history with filtering"]
+// CIL[DOC-CONTEXT module="api-keys" layer="backend_functions" related_files="[\".framework/src/pages/admin/RolesPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="usage_logs" errors="auth_errors,db_errors" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Query usage logs with filters, return paginated results" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: backend_functions. Direct callers: 1. Direct calls: 0. Related files: .framework/src/pages/admin/RolesPage.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 1. Total affected: 1."]
+// 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 listUsageLogs = createHandler(async (ctx, _body) => {
   const { api_key_id, response_status, success, date_from, date_to, limit = 100, offset = 0 } = ctx.query || {}
 
@@ -320,25 +382,21 @@ export const listUsageLogs = createHandler(async (ctx, _body) => {
 
   return data
 })
-// ─── CHUNK_END: API_KEYS_LIST_USAGE_LOGS ────────────────────────────────────────────────
-
-// ─── MAIN HANDLER ────────────────────────────────────────────────────────────
-
-// ─── CHUNK_START: API_KEYS_HANDLER ──────────────────────────────────────────────
-/**
- * @chunk-id    API_KEYS_HANDLER_1_0_0
- * @version     1.0.0
- * @hash        6c2da419bea6f12b0fe654e2aad6c5ebac3d5993c2547a47d239f44197d90a68
- * @macro       API Keys Router
- * @micro       Routes HTTP methods and actions to appropriate handlers
- * @inputs      ctx: CoreContext — Request context with principal and database
- * @inputs      body: any — Request body for POST operations
- * @outputs     Varies — Depends on routed handler (list/get/create/validate/revoke/usage-logs)
- * @depends-on  [createHandler, list, get, create, validate, revoke, listUsageLogs]
- * @depended-by [Netlify function routing]
- * @side-effects [Delegates to appropriate handler]
- * @tags        api-keys, router, crud, netlify-function
- */
+// CIL[END chunk_id="api-keys_listusagelogs_1783969696"]
+// CIL[BEGIN chunk_id="api-keys_handler_1783969696" type="function" identity="handler" parent="none"]
+// CIL[DOC-MACRO purpose="Route API key HTTP methods"]
+// CIL[DOC-RESPONSIBILITY responsibility="Dispatch requests to API key operations"]
+// CIL[DOC-CONTEXT module="api-keys" layer="backend_functions" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="function_responses" errors="method_errors" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Route based on action and method to specific API key functions" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: backend_functions. 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 { action } = ctx.query || {}
   const method = ctx.query?.method || 'GET'
@@ -373,4 +431,4 @@ export const handler = createHandler(async (ctx, body) => {
 
   throw new Error('Invalid action or method')
 })
-// ─── CHUNK_END: API_KEYS_HANDLER ────────────────────────────────────────────────
+// CIL[END chunk_id="api-keys_handler_1783969696"]