spine-framework 0.4.3 → 0.5.0-rc.4

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

@@ -1,4 +1,20 @@
 // 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"]
+/**
+ * @module   api-keys
+ * @audience both
+ * @layer    shared-core
+ * @stability stable
+ *
+ * This module manages API key operations, including creation and validation, as part of the system's security framework. It serves as a middleware handler that interacts with the database and performs necessary logging and permission checks. INVARIANT: All API key operations require system admin privileges. Route patterns include /api/keys for key management operations.
+ *
+ * @seeAlso middleware.ts (provides request handling functionality).
+ * @seeAlso db.ts (interacts with the database for key storage).
+ * @seeAlso audit.ts (handles logging of operations).
+ * @seeAlso permissions.ts (ensures proper access control).
+ *
+ * @cil-generated
+ */
+
 
 
 
@@ -29,39 +45,65 @@
 
 
 
-// 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[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"]
+import { hashApiKey, omitSecretFields } from './_shared/hash-api-key'
+import { resolveAppUuid } from './_shared/logging'
 // CIL[END stable_id="~/.framework/functions/api-keys.ts:module_header:module_header"]
+
+
+// True only for platform-level principals: a system_admin role or an
+// internal machine principal with no account binding (SYSTEM_PRINCIPAL,
+// produced only by the INTERNAL_INVOKE_SECRET path). Machine principals
+// resolve to the service-role adminDb via getPrincipalDb, so account-bound
+// API keys must be scoped to their own account below.
+// CIL[BEGIN stable_id="~/.framework/functions/api-keys.ts:isSystemPrincipal:function" type="function" identity="isSystemPrincipal" parent="~/.framework/functions/api-keys.ts"]
+function isSystemPrincipal(ctx: any): boolean {
+  return isSystemAdmin(ctx.principal) || (ctx.principal?.isInternal === true && !ctx.accountId)
+}
+// CIL[END stable_id="~/.framework/functions/api-keys.ts:isSystemPrincipal:function"]
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 // 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]
+/**
+ * This function retrieves a list of API keys based on various query parameters and returns sanitized records. It ensures that only authorized users can access the data and applies filters based on the provided criteria.
+ *
+ * @throws      Error — Account context required.
+ * @sideEffects none
+ * @stability   internal
+ * @calls       adminDb.from('api_keys'), ctx.db.from('api_keys'), sanitizeRecordData
+ * @cil-generated
+ */
 export const list = createHandler(async (ctx, _body) => {
   const { integration_id, key_type, is_active, expires_before, expires_after, limit = 100, offset = 0 } = ctx.query || {}
 
-  if (!ctx.accountId) {
+  const isSystem = isSystemPrincipal(ctx)
+
+  if (!isSystem && !ctx.accountId) {
     throw new Error('Account context required')
   }
 
@@ -72,6 +114,12 @@ export const list = createHandler(async (ctx, _body) => {
     .select('*')
     .order('created_at', { ascending: false })
 
+  // Machine principals run on the service-role client — pin them to their
+  // own account so they cannot enumerate other tenants' keys.
+  if (!isSystem) {
+    query = query.eq('account_id', ctx.accountId)
+  }
+
   if (integration_id) {
     query = query.eq('integration_id', integration_id)
   }
@@ -97,26 +145,37 @@ export const list = createHandler(async (ctx, _body) => {
 
   const sanitized = []
   for (const key of data || []) {
-    sanitized.push(await sanitizeRecordData(ctx, key, 'api_key'))
+    sanitized.push(omitSecretFields(await sanitizeRecordData(ctx, key, 'api_key')))
   }
 
   return sanitized
 })
-// 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]
+/**
+ * Retrieves an API key from the database based on the provided ID in the query parameters. It ensures that the caller has the necessary permissions and sanitizes the returned data before sending it back.
+ *
+ * @throws      Error — API key ID is required, Error — if there is an error fetching the API key.
+ * @sideEffects none
+ * @stability   internal
+ * @calls       adminDb.from('api_keys'), ctx.db.from('api_keys'), sanitizeRecordData
+ * @cil-generated
+ */
 export const get = createHandler(async (ctx, _body) => {
   const { id } = ctx.query || {}
 
@@ -126,31 +185,50 @@ export const get = createHandler(async (ctx, _body) => {
 
   const db = isSystemAdmin(ctx.principal) ? adminDb : ctx.db
 
-  const { data, error: err } = await db
+  let query = db
     .from('api_keys')
     .select('*')
     .eq('id', id)
-    .single()
+
+  if (!isSystemPrincipal(ctx)) {
+    if (!ctx.accountId) {
+      throw new Error('Account context required')
+    }
+    query = query.eq('account_id', ctx.accountId)
+  }
+
+  const { data, error: err } = await query.single()
 
   if (err) throw err
 
-  return await sanitizeRecordData(ctx, data, 'api_key')
+  return omitSecretFields(await sanitizeRecordData(ctx, data, 'api_key'))
 })
-// 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]
+/**
+ * Creates a new API key for a specified integration and application, ensuring required fields are validated and generating a unique key. This function is essential for managing access to the API securely.
+ *
+ * @throws      Error — name is required, Error — Account context required, Error — database error
+ * @sideEffects Writes a new record to the 'api_keys' table in the database and emits a log event.
+ * @stability   internal
+ * @calls       ctx.db.from('api_keys'), emitLog, resolveAppUuid
+ * @cil-generated
+ */
 export const create = createHandler(async (ctx, body) => {
   const {
     integration_id,
@@ -174,6 +252,35 @@ export const create = createHandler(async (ctx, body) => {
     throw new Error('Account context required')
   }
 
+  // S-011: scopes and is_internal are privilege-bearing fields. A machine
+  // caller runs on the service-role client, so accepting them verbatim let
+  // any scoped key mint a *:* or is_internal key and escalate itself past
+  // the isInternal gates elsewhere. Only system principals may request a
+  // wildcard scope or an internal key — for everyone else those are hard
+  // denials, other requested scopes are clipped to the scopes the caller
+  // itself holds, and an omitted scopes list inherits the caller's own.
+  const isSystem = isSystemPrincipal(ctx)
+  let effectiveScopes: string[] = scopes || []
+  let effectiveIsInternal = is_internal || false
+
+  if (!isSystem) {
+    if (is_internal) {
+      const e: any = new Error('Insufficient permissions to create an internal API key')
+      e.statusCode = 403
+      throw e
+    }
+    if (Array.isArray(scopes) && scopes.includes('*:*')) {
+      const e: any = new Error('Insufficient permissions to create a wildcard-scoped API key')
+      e.statusCode = 403
+      throw e
+    }
+    const callerScopes = Array.isArray(ctx.principal?.scopes) ? ctx.principal.scopes : []
+    effectiveScopes = Array.isArray(scopes)
+      ? scopes.filter((s: string) => callerScopes.includes(s))
+      : callerScopes
+    effectiveIsInternal = false
+  }
+
   const slug = body.slug || name.toLowerCase().replace(/\s+/g, '-').replace(/[^a-z0-9-]/g, '')
 
   const rawKey = `sk_${crypto.randomUUID().replace(/-/g, '')}`
@@ -181,7 +288,7 @@ export const create = createHandler(async (ctx, body) => {
 
   const insertData = {
     integration_id: integration_id || null,
-    app_id: app_id || ctx.appId || null,
+    app_id: (await resolveAppUuid(app_id || ctx.appId)) || null,
     account_id: ctx.accountId,
     slug,
     name,
@@ -189,14 +296,14 @@ export const create = createHandler(async (ctx, body) => {
     key_hash,
     key_type: key_type || 'inbound',
     permissions: permissions || [],
-    scopes: scopes || [],
+    scopes: effectiveScopes,
     rate_limit: rate_limit || 100,
     expires_at: expires_at || null,
     metadata: metadata || {},
     machine_type: machine_type || 'integration',
-    is_internal: is_internal || false,
+    is_internal: effectiveIsInternal,
     is_active: true,
-    created_by: ctx.principal?.id || null
+    created_by: ctx.principal?.type === 'human' ? ctx.principal.id : null
   }
 
   const { data, error: err } = await ctx.db
@@ -218,21 +325,32 @@ export const create = createHandler(async (ctx, body) => {
     warning: 'Store this key now. It will not be shown again.'
   }
 })
-// 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]
+/**
+ * Validates an API key by checking its existence and permissions in the database. This function ensures that only active keys with the required permissions can be used.
+ *
+ * @throws      Error — key_value is required, Error — database error
+ * @sideEffects Database read operations.
+ * @stability   internal
+ * @calls       ctx.db.from('api_keys'), import('./_shared/hash-api-key')
+ * @cil-generated
+ */
 export const validate = createHandler(async (ctx, body) => {
   const { key_value, required_permissions } = body
 
@@ -240,15 +358,29 @@ export const validate = createHandler(async (ctx, body) => {
     throw new Error('key_value is required')
   }
 
+  const isSystem = isSystemPrincipal(ctx)
+  if (!isSystem && !ctx.accountId) {
+    throw new Error('Account context required')
+  }
+
   const keyPrefix = key_value.slice(0, 8)
 
-  const { data: rows, error: err } = await ctx.db
+  let query = ctx.db
     .from('api_keys')
     .select('*')
     .eq('key_prefix', keyPrefix)
     .eq('is_active', true)
     .or('expires_at.is.null,expires_at.gte.now()')
 
+  // Scoped callers may only validate keys belonging to their own account —
+  // ctx.db is service-role for machine principals, so without this filter a
+  // caller could probe another account's key material.
+  if (!isSystem) {
+    query = query.eq('account_id', ctx.accountId)
+  }
+
+  const { data: rows, error: err } = await query
+
   if (err) throw err
   if (!rows || rows.length === 0) {
     return { is_valid: false, error: 'Invalid or inactive API key' }
@@ -283,21 +415,32 @@ export const validate = createHandler(async (ctx, body) => {
 
   return { is_valid: false, error: 'Invalid or inactive API key' }
 })
-// 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]
+/**
+ * The 'revoke' constant defines a handler for deactivating an API key by its ID. It ensures that the API key ID is provided and logs the revocation action.
+ *
+ * @throws      Error — if the API key ID is missing or if a database error occurs.
+ * @sideEffects Updates the 'api_keys' table in the database and emits a log event.
+ * @stability   internal
+ * @calls       ctx.db.from('api_keys'), emitLog
+ * @cil-generated
+ */
 export const revoke = createHandler(async (ctx, body) => {
   const { id } = body
 
@@ -305,12 +448,19 @@ export const revoke = createHandler(async (ctx, body) => {
     throw new Error('API key ID is required')
   }
 
-  const { data, error: err } = await ctx.db
+  let query = ctx.db
     .from('api_keys')
     .update({ is_active: false, updated_at: new Date().toISOString() })
     .eq('id', id)
-    .select()
-    .single()
+
+  if (!isSystemPrincipal(ctx)) {
+    if (!ctx.accountId) {
+      throw new Error('Account context required')
+    }
+    query = query.eq('account_id', ctx.accountId)
+  }
+
+  const { data, error: err } = await query.select().single()
 
   if (err) throw err
 
@@ -319,27 +469,41 @@ export const revoke = createHandler(async (ctx, body) => {
     { after: { revoked_by: ctx.principal?.id } }
   )
 
-  return data
+  return omitSecretFields(data)
 })
-// 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]
+/**
+ * The listUsageLogs constant defines an asynchronous handler for retrieving API key usage logs based on various query parameters. It ensures that the account context is valid and constructs a query to fetch logs from the database.
+ *
+ * @throws      Error — Account context required.
+ * @sideEffects none
+ * @stability   internal
+ * @calls       ctx.db.from('api_key_usage_logs'), ctx.db.select, ctx.db.eq, ctx.db.gte, ctx.db.lte, ctx.db.range
+ * @errorHandling none
+ * @cil-generated
+ */
 export const listUsageLogs = createHandler(async (ctx, _body) => {
   const { api_key_id, response_status, success, date_from, date_to, limit = 100, offset = 0 } = ctx.query || {}
 
-  if (!ctx.accountId) {
+  const isSystem = isSystemPrincipal(ctx)
+
+  if (!isSystem && !ctx.accountId) {
     throw new Error('Account context required')
   }
 
@@ -351,6 +515,10 @@ export const listUsageLogs = createHandler(async (ctx, _body) => {
     `)
     .order('created_at', { ascending: false })
 
+  if (!isSystem) {
+    query = query.eq('account_id', ctx.accountId)
+  }
+
   if (api_key_id) {
     query = query.eq('api_key_id', api_key_id)
   }
@@ -376,21 +544,32 @@ export const listUsageLogs = createHandler(async (ctx, _body) => {
 
   return data
 })
-// 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]
+/**
+ * The handler processes API requests based on the action and method specified in the query parameters. It routes the request to the appropriate function for validation, revocation, usage logs, or general data handling.
+ *
+ * @throws      Error — Invalid action or method
+ * @sideEffects none
+ * @stability   internal
+ * @calls       validate, revoke, listUsageLogs, get, list, create
+ * @cil-generated
+ */
 export const handler = createHandler(async (ctx, body) => {
   const { action } = ctx.query || {}
   const method = ctx.query?.method || 'GET'
@@ -425,10 +604,10 @@ export const handler = createHandler(async (ctx, body) => {
 
   throw new Error('Invalid action or method')
 })
-// 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"]
+// CIL[END stable_id="~/.framework/functions/api-keys.ts:handler:constant"]
+
+
+
+
+
+