spine-framework 0.3.145 → 0.4.1

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

@@ -1,3 +1,4 @@
+// CIL[BEGIN stable_id="~/.framework/functions/api-keys.ts:module_header:module_header" type="module_header" identity="module_header" parent="~/.framework/functions/api-keys.ts"]
 
 
 
@@ -27,43 +28,36 @@
 
 
 
-// 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"]
 
+// CIL[DOC-AUDIENCE audience="function-developers,system-integrators"]
+// CIL[DOC-MACRO purpose="Netlify function module for API key lifecycle management"]
+// CIL[DOC-RESPONSIBILITY responsibility="Import shared middleware, DB, audit, principal, permissions and hash helpers"]
+// CIL[DOC-CONTEXT module="api-keys" layer="netlify-functions" related_files=".framework/functions/_shared/audit.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/hash-api-key.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/permissions.ts,.framework/functions/_shared/principal.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="none" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Sets up imports used by list/get/create/validate/revoke/usage-logs handlers" notable_decisions="Uses shared middleware and principal checks"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stable]
 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'
 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="context" content="purpose='Netlify function module for API key lifecycle management'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/audit.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/functions/api-keys.ts:module_header:module_header"]
+// CIL[BEGIN stable_id="~/.framework/functions/api-keys.ts:list:constant" type="constant" identity="list" parent="~/.framework/functions/api-keys.ts"]
+// CIL[DOC-MACRO purpose="List API keys for an account with optional filters"]
+// CIL[DOC-RESPONSIBILITY responsibility="Query api_keys table, apply filters, sanitize results, and return paginated list"]
+// CIL[DOC-CONTEXT module="api-keys" layer="netlify-functions" related_files=".framework/functions/_shared/audit.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/hash-api-key.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/permissions.ts,.framework/functions/_shared/principal.ts,.framework/functions/api-keys.ts"]
+// CIL[DOC-CONTRACT inputs="integration_id,key_type,is_active,expires_before,expires_after,limit,offset via ctx.query" outputs="Array of sanitized api_key records" errors="Account context required; DB query errors" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Builds a Supabase query with filters and range, then sanitizes each record" notable_decisions="Uses isSystemAdmin to choose adminDb vs ctx.db"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stable]
 export const list = createHandler(async (ctx, _body) => {
   const { integration_id, key_type, is_active, expires_before, expires_after, limit = 100, offset = 0 } = ctx.query || {}
 
@@ -108,21 +102,21 @@ export const list = createHandler(async (ctx, _body) => {
 
   return sanitized
 })
-// 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="context" content="purpose='List API keys for an account with optional filters'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/audit.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/functions/api-keys.ts:list:constant"]
+// CIL[BEGIN stable_id="~/.framework/functions/api-keys.ts:get:constant" type="constant" identity="get" parent="~/.framework/functions/api-keys.ts"]
+// CIL[DOC-MACRO purpose="Fetch a single API key by ID"]
+// CIL[DOC-RESPONSIBILITY responsibility="Retrieve one api_keys row by id and sanitize it"]
+// CIL[DOC-CONTEXT module="api-keys" layer="netlify-functions" related_files=".framework/functions/_shared/audit.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/hash-api-key.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/permissions.ts,.framework/functions/_shared/principal.ts,.framework/functions/api-keys.ts"]
+// CIL[DOC-CONTRACT inputs="id via ctx.query" outputs="Sanitized api_key record" errors="API key ID is required; DB errors" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Queries by id with .single(), then sanitizes" notable_decisions="Reuses principal/adminDb selection"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stable]
 export const get = createHandler(async (ctx, _body) => {
   const { id } = ctx.query || {}
 
@@ -142,21 +136,21 @@ export const get = createHandler(async (ctx, _body) => {
 
   return await sanitizeRecordData(ctx, data, 'api_key')
 })
-// 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="context" content="purpose='Fetch a single API key by ID'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/audit.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/functions/api-keys.ts:get:constant"]
+// CIL[BEGIN stable_id="~/.framework/functions/api-keys.ts:create:constant" type="constant" identity="create" parent="~/.framework/functions/api-keys.ts"]
+// CIL[DOC-MACRO purpose="Create a new API key"]
+// CIL[DOC-RESPONSIBILITY responsibility="Validate input, generate key hash, insert record, emit audit log, and return the raw key once"]
+// CIL[DOC-CONTEXT module="api-keys" layer="netlify-functions" related_files=".framework/functions/_shared/audit.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/hash-api-key.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/permissions.ts,.framework/functions/_shared/principal.ts,.framework/functions/api-keys.ts"]
+// CIL[DOC-CONTRACT inputs="integration_id,app_id,name,key_type,permissions,scopes,rate_limit,expires_at,metadata,machine_type,is_internal via body" outputs="Created api_key record plus raw_key and warning" errors="name is required; Account context required; DB insert errors" side_effects="Inserts into api_keys; emits api_key.created audit log"]
+// CIL[DOC-MICRO logic_summary="Generates slug and raw key, hashes it, inserts data, logs, and returns a one-time raw key" notable_decisions="Hashes the raw key before storage; returns raw key only on creation"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stable]
 export const create = createHandler(async (ctx, body) => {
   const {
     integration_id,
@@ -224,21 +218,21 @@ export const create = createHandler(async (ctx, body) => {
     warning: 'Store this key now. It will not be shown again.'
   }
 })
-// 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="context" content="purpose='Create a new API key'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/audit.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/functions/api-keys.ts:create:constant"]
+// CIL[BEGIN stable_id="~/.framework/functions/api-keys.ts:validate:constant" type="constant" identity="validate" parent="~/.framework/functions/api-keys.ts"]
+// CIL[DOC-MACRO purpose="Validate an API key value and optional permissions"]
+// CIL[DOC-RESPONSIBILITY responsibility="Look up active keys by prefix, verify hash, check permissions, and return validity and identity"]
+// CIL[DOC-CONTEXT module="api-keys" layer="netlify-functions" related_files=".framework/functions/_shared/audit.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/hash-api-key.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/permissions.ts,.framework/functions/_shared/principal.ts,.framework/functions/api-keys.ts"]
+// CIL[DOC-CONTRACT inputs="key_value,required_permissions via body" outputs="{ is_valid, api_key_id, integration_id, app_id, account_id, scopes, permissions } or { is_valid, error }" errors="key_value is required; DB errors" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Searches active or unexpired keys matching prefix, verifies hash against key_hash, and checks required permissions" notable_decisions="Dynamically imports verifyApiKey; returns first matched key"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stable]
 export const validate = createHandler(async (ctx, body) => {
   const { key_value, required_permissions } = body
 
@@ -289,21 +283,21 @@ export const validate = createHandler(async (ctx, body) => {
 
   return { is_valid: false, error: 'Invalid or inactive API key' }
 })
-// 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="context" content="purpose='Validate an API key value and optional permissions'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/audit.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/functions/api-keys.ts:validate:constant"]
+// CIL[BEGIN stable_id="~/.framework/functions/api-keys.ts:revoke:constant" type="constant" identity="revoke" parent="~/.framework/functions/api-keys.ts"]
+// CIL[DOC-MACRO purpose="Deactivate an API key by ID"]
+// CIL[DOC-RESPONSIBILITY responsibility="Update is_active to false and emit an audit log"]
+// CIL[DOC-CONTEXT module="api-keys" layer="netlify-functions" related_files=".framework/functions/_shared/audit.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/hash-api-key.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/permissions.ts,.framework/functions/_shared/principal.ts,.framework/functions/api-keys.ts"]
+// CIL[DOC-CONTRACT inputs="id via body" outputs="Updated api_key record" errors="API key ID is required; DB update errors" side_effects="Sets is_active=false on api_keys row; emits api_key.revoked audit log"]
+// CIL[DOC-MICRO logic_summary="Updates the row with is_active false and current timestamp, then logs" notable_decisions="Performs soft revocation via is_active flag"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stable]
 export const revoke = createHandler(async (ctx, body) => {
   const { id } = body
 
@@ -327,21 +321,21 @@ export const revoke = createHandler(async (ctx, body) => {
 
   return data
 })
-// 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="context" content="purpose='Deactivate an API key by ID'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/audit.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/functions/api-keys.ts:revoke:constant"]
+// CIL[BEGIN stable_id="~/.framework/functions/api-keys.ts:listUsageLogs:constant" type="constant" identity="listUsageLogs" parent="~/.framework/functions/api-keys.ts"]
+// CIL[DOC-MACRO purpose="List API key usage logs with filters"]
+// CIL[DOC-RESPONSIBILITY responsibility="Query api_key_usage_logs, join api_keys, apply filters, and return paginated results"]
+// CIL[DOC-CONTEXT module="api-keys" layer="netlify-functions" related_files=".framework/functions/_shared/audit.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/hash-api-key.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/permissions.ts,.framework/functions/_shared/principal.ts,.framework/functions/api-keys.ts"]
+// CIL[DOC-CONTRACT inputs="api_key_id,response_status,success,date_from,date_to,limit,offset via ctx.query" outputs="Array of usage log records with api_key details" errors="Account context required; DB query errors" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Builds a Supabase query with filters and range over usage logs" notable_decisions="Joins api_keys in select; normalizes success to boolean"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stable]
 export const listUsageLogs = createHandler(async (ctx, _body) => {
   const { api_key_id, response_status, success, date_from, date_to, limit = 100, offset = 0 } = ctx.query || {}
 
@@ -382,21 +376,21 @@ export const listUsageLogs = createHandler(async (ctx, _body) => {
 
   return data
 })
-// 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="context" content="purpose='List API key usage logs with filters'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/audit.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/functions/api-keys.ts:listUsageLogs:constant"]
+// CIL[BEGIN stable_id="~/.framework/functions/api-keys.ts:handler:constant" type="constant" identity="handler" parent="~/.framework/functions/api-keys.ts"]
+// CIL[DOC-MACRO purpose="Route incoming Netlify function requests to the appropriate action"]
+// CIL[DOC-RESPONSIBILITY responsibility="Dispatch GET/POST actions to list, get, create, validate, revoke, or listUsageLogs"]
+// CIL[DOC-CONTEXT module="api-keys" layer="netlify-functions" related_files=".framework/functions/_shared/audit.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/hash-api-key.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/permissions.ts,.framework/functions/_shared/principal.ts,.framework/functions/api-keys.ts"]
+// CIL[DOC-CONTRACT inputs="action,method,id via ctx.query; body" outputs="Result from delegated handler or error" errors="Invalid action or method" side_effects="Calls delegated handlers"]
+// CIL[DOC-MICRO logic_summary="Switch on action and HTTP method to call the correct sub-handler" notable_decisions="Default GET lists or gets; POST creates; validate/revoke/usage-logs are explicit"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stable]
 export const handler = createHandler(async (ctx, body) => {
   const { action } = ctx.query || {}
   const method = ctx.query?.method || 'GET'
@@ -431,4 +425,10 @@ export const handler = createHandler(async (ctx, body) => {
 
   throw new Error('Invalid action or method')
 })
-// CIL[END chunk_id="api-keys_handler_1783969696"]
+// CIL[DOC-VECTOR type="context" content="purpose='Route incoming Netlify function requests to the appropriate action'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/audit.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/functions/api-keys.ts:handler:constant"]