spine-framework 0.3.124 → 0.3.126

package/.framework/functions/_shared/{cil-state.ts → cil.ts}

@@ -1,15 +1,30 @@
-/**
- * @module cil-state
- * @audience both
- * @layer shared-core
- * @stability experimental
- *
- * Shared state-machine helpers for the CIL ingestion pipeline.
- */
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 
 import { adminDb } from './db'
 
-export type FileStatus = 'discovered' | 'pass2_complete' | 'pass3_complete' | 'pass4_complete' | 'pass4b_complete' | 'pass5_complete'
+export type FileStatus =
+  | '0-discovered'
+  | '1-selected'
+  | '2-chunked'
+  | '3-first-pass-complete'
+  | '4-first-pass-embedded'
+  | '5-first-pass-mapped'
+  | '6-second-pass-complete'
+  | '7-second-pass-embedded'
+  | '8-second-pass-mapped'
 
 export interface FileTreeNode {
   id?: string | null
@@ -23,10 +38,20 @@ export interface FileTreeNode {
   selected?: boolean
 }
 
-/**
- * Check whether a file path is inside any of the selected paths.
- * A file is selected if its path equals a selected path, or starts with a selected directory path + '/'.
- */
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 export function isSelectedPath(filePath: string, selectedPaths: string[]): boolean {
   if (selectedPaths.length === 0) return true
   return selectedPaths.some(sp => {
@@ -36,32 +61,66 @@ export function isSelectedPath(filePath: string, selectedPaths: string[]): boole
   })
 }
 
-/**
- * Extract the file status from a cil_file item.
- */
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 export function getFileStatus(fileItem: any): FileStatus {
-  return fileItem.data?.status || 'discovered'
+  return fileItem.data?.status || '0-discovered'
 }
 
-/**
- * Update the status of a cil_file item.
- */
-export async function updateFileStatus(ctx: any, fileItem: any, status: FileStatus, extraData: Record<string, any> = {}): Promise<void> {
-  const { create, update } = await import('../admin-data')
-  const updateCtx = { ...ctx, query: { ...(ctx.query || {}), entity: 'items', id: fileItem.id } }
-  await update(updateCtx, {
-    data: {
-      ...fileItem.data,
-      ...extraData,
-      status,
-      last_status_at: new Date().toISOString(),
-    },
-  })
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+export async function updateFileStatus(_ctx: any, fileItem: any, status: FileStatus, extraData: Record<string, any> = {}): Promise<void> {
+  await adminDb
+    .from('items')
+    .update({
+      data: {
+        ...fileItem.data,
+        ...extraData,
+        status,
+        last_status_at: new Date().toISOString(),
+      },
+    })
+    .eq('id', fileItem.id)
 }
 
-/**
- * Build a nested file tree from a flat list of discovered files.
- */
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 export function buildFileTree(fileRecords: { file_path: string; id?: string; language: string; status?: FileStatus; extension: string }[]): FileTreeNode {
   const root: FileTreeNode = { name: 'root', path: '', type: 'directory', children: [] }
 
@@ -97,9 +156,20 @@ export function buildFileTree(fileRecords: { file_path: string; id?: string; lan
   return root
 }
 
-/**
- * Update the status of a file node in the persisted tree by its file item ID.
- */
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 export function updateTreeNodeStatus(tree: FileTreeNode, fileId: string, status: FileStatus): void {
   if (tree.id === fileId) {
     tree.status = status
@@ -112,10 +182,20 @@ export function updateTreeNodeStatus(tree: FileTreeNode, fileId: string, status:
   }
 }
 
-/**
- * Update a file node in the persisted tree by its file path.
- * Used when the tree is built before file records exist (Pass 1).
- */
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 export function updateTreeNodeByPath(tree: FileTreeNode, filePath: string, updates: { id?: string; status?: FileStatus }): void {
   if (tree.type === 'file' && tree.path === filePath) {
     if (updates.id !== undefined) tree.id = updates.id
@@ -129,20 +209,42 @@ export function updateTreeNodeByPath(tree: FileTreeNode, filePath: string, updat
   }
 }
 
-/**
- * Persist the updated tree back to the project item.
- */
-export async function saveProjectTree(ctx: any, projectId: string, tree: FileTreeNode, extraData: Record<string, any> = {}): Promise<void> {
-  const { update } = await import('../admin-data')
-  const { data: projItem } = await adminDb.from('items').select('id, data').eq('id', projectId).maybeSingle()
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+export async function saveProjectTree(
+  _ctx: any,
+  projectId: string,
+  tree: FileTreeNode,
+  extraData: Record<string, any> = {},
+  projectItem?: any
+): Promise<void> {
+  let projItem = projectItem
+  if (!projItem) {
+    const { data } = await adminDb.from('items').select('id, data').eq('id', projectId).maybeSingle()
+    projItem = data
+  }
   if (!projItem) return
-  const updateCtx = { ...ctx, query: { ...(ctx.query || {}), entity: 'items', id: projItem.id } }
-  await update(updateCtx, {
-    data: {
-      ...projItem.data,
-      file_tree: tree,
-      ...extraData,
-      last_tree_update: new Date().toISOString(),
-    },
-  })
+  await adminDb
+    .from('items')
+    .update({
+      data: {
+        ...projItem.data,
+        file_tree: tree,
+        ...extraData,
+        last_tree_update: new Date().toISOString(),
+      },
+    })
+    .eq('id', projItem.id)
 }

package/.framework/functions/_shared/db.ts

@@ -1,29 +1,28 @@
-/**
- * @module db
- * @audience both
- * @layer shared-core
- * @stability stable
- *
- * Supabase client factory and PostgREST join helpers. This module owns the
- * two-client pattern that is central to Spine's security model: `adminDb`
- * bypasses RLS for system operations; `getUserDb` enforces RLS for all
- * human-principal requests. Never use `adminDb` for user-scoped queries —
- * doing so silently bypasses account isolation.
- *
- * @seeAlso principal.ts (getPrincipalDb selects between these two clients)
- * @seeAlso middleware.ts (ctx.db is set from getPrincipalDb at request time)
- */
 
+
+
+
+
+// CIL[BEGIN chunk_id="db_moduleheader_1784066609" type="module_header" identity="module_header" parent="none"]
+// CIL[DOC-MACRO purpose="Database connection setup and configuration"]
+// CIL[DOC-RESPONSIBILITY responsibility="Configure Supabase clients and environment variables"]
+// CIL[DOC-CONTEXT module="_shared/db" layer="infrastructure" 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="url" outputs="configured clients and constants" errors="invalid URLs" side_effects="global configuration"]
+// CIL[DOC-MICRO logic_summary="Validates environment variables and sets up Supabase connection parameters" 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: infrastructure. 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 { createClient } from '@supabase/supabase-js'
 import WebSocket from 'ws'
 
-// ─── ENVIRONMENT RESOLUTION ──────────────────────────────────────────────────
-
 const _env = (globalThis as any).process?.env || {}
 
-// Use a known-valid placeholder URL so that createClient() doesn't throw at
-// module load time when env vars haven't been set yet (e.g. during CLI init).
-// All real requests validate credentials before hitting the DB.
 const PLACEHOLDER_URL = 'https://placeholder.supabase.co'
 const PLACEHOLDER_KEY = 'placeholder'
 
@@ -36,62 +35,40 @@ const supabaseUrl: string = rawUrl && isValidUrl(rawUrl) ? rawUrl : PLACEHOLDER_
 const supabaseServiceKey: string = _env.SUPABASE_SERVICE_ROLE_KEY || PLACEHOLDER_KEY
 const supabaseAnonKey: string = _env.SUPABASE_ANON_KEY || PLACEHOLDER_KEY
 const dbSchema: string = _env.DB_SCHEMA || 'public'
-
-// ─── CLIENTS ─────────────────────────────────────────────────────────────────
-
-/**
- * Service-role Supabase client. Bypasses Row Level Security.
- *
- * Use this ONLY for:
- * - System/cron operations that must cross account boundaries (`system-cron.ts`)
- * - Principal resolution lookups (`principal.ts` — resolving auth_uid to person)
- * - Machine principal validation RPCs
- * - Test helpers that need to seed/clean data across accounts
- *
- * Do NOT use this in request handlers for user-scoped data reads or writes.
- * Always prefer `ctx.db` (set by `getPrincipalDb` in middleware) for those.
- *
- * @inputSpec SUPABASE_URL: string — valid Supabase project URL, required
- * @inputSpec SUPABASE_SERVICE_ROLE_KEY: string — service role JWT, required
- * @outputSpec SupabaseClient — PostgREST client scoped to `dbSchema`, RLS disabled
- * @sideEffects none (client construction only)
- * @calledBy principal.ts, middleware.ts, system-cron.ts, permissions.ts,
- *   tests/integration/helpers.ts
- * @calls createClient (supabase-js)
- * @testUnit tests/unit/pipeline-runner.test.ts — mocked via vi.mock
- * @testIntegration tests/integration/helpers.ts — used directly as adminDb
- *
- * @example API handler (system operation)
- * ```ts
- * import { adminDb } from './_shared/db'
- * const { data } = await adminDb.from('types').select('*').eq('slug', 'item')
- * ```
- *
- * @example Import usage (v2-custom/ — system-level only)
- * ```ts
- * import { adminDb } from '../_shared/index'
- * // Only use adminDb if your custom code runs as a system/cron principal
- * ```
- */
+// CIL[END chunk_id="db_moduleheader_1784066609"]
+// CIL[BEGIN chunk_id="db_admindb_1784066609" type="variable" identity="adminDb" parent="none"]
+// CIL[DOC-MACRO purpose="Admin database client with full permissions"]
+// CIL[DOC-RESPONSIBILITY responsibility="Provide database access for admin operations"]
+// CIL[DOC-CONTEXT module="_shared/db" layer="infrastructure" related_files="[\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/src/pages/admin/IntegrationsPage.tsx\",\".framework/src/pages/admin/RolesPage.tsx\",\".framework/functions/_shared/principal.ts\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="admin Supabase client" errors="invalid credentials" side_effects="database connection"]
+// CIL[DOC-MICRO logic_summary="Creates Supabase client with service role key for admin access" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: infrastructure. Direct callers: 0. Direct calls: 0. Related files: .framework/src/pages/admin/TypeDetailPage.tsx, .framework/src/pages/admin/IntegrationsPage.tsx, .framework/src/pages/admin/RolesPage.tsx, .framework/functions/_shared/principal.ts, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export const adminDb = createClient(supabaseUrl, supabaseServiceKey, {
   db: { schema: dbSchema },
   realtime: { transport: WebSocket as any }
 })
-
-// ─── CHUNK_START: SHARED_DB_GET_USER_DB ──────────────────────────────────────────────
-/**
- * @chunk-id    SHARED_DB_GET_USER_DB_1_0_0
- * @version     1.0.0
- * @hash        af3c792634c60ced1c1c4184cfc6c20add90ab97eb62f7e46bdf40ae2899a0f8
- * @macro       User Database Client Factory
- * @micro       Creates RLS-enforced Supabase client for specific user JWT
- * @inputs      jwt: string — Valid Supabase JWT from Authorization header
- * @outputs     SupabaseClient — PostgREST client with RLS enforced
- * @depends-on  [createClient, supabaseUrl, supabaseAnonKey, dbSchema]
- * @depended-by [principal.ts, middleware.ts]
- * @side-effects [Client construction with Authorization header]
- * @tags        database, supabase, rls, authentication, user-scoped
- */
+// CIL[END chunk_id="db_admindb_1784066609"]
+// CIL[BEGIN chunk_id="db_getuserdb_1784066609" type="function" identity="getUserDb" parent="none"]
+// CIL[DOC-MACRO purpose="Create user-scoped database client"]
+// CIL[DOC-RESPONSIBILITY responsibility="Provide authenticated database access for users"]
+// CIL[DOC-CONTEXT module="_shared/db" layer="infrastructure" related_files="[\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/src/components/ui/dialog.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="user Supabase client" errors="invalid JWT" side_effects="database connection"]
+// CIL[DOC-MICRO logic_summary="Creates Supabase client with user JWT for row-level security" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: infrastructure. Direct callers: 0. Direct calls: 0. Related files: .framework/src/pages/admin/TypeDetailPage.tsx, .framework/src/components/ui/dialog.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export function getUserDb(jwt: string) {
   return createClient(supabaseUrl, supabaseAnonKey, {
     db: { schema: dbSchema },
@@ -99,64 +76,40 @@ export function getUserDb(jwt: string) {
     realtime: { transport: WebSocket as any }
   })
 }
-// ─── CHUNK_END: SHARED_DB_GET_USER_DB ────────────────────────────────────────────────
-
-// ─── TYPES ───────────────────────────────────────────────────────────────────
-
-/**
- * Standard shape returned by all Supabase PostgREST queries.
- *
- * Both `data` and `error` follow the Supabase JS client convention: on success,
- * `error` is null; on failure, `data` is null and `error` contains the Postgres
- * error details. Always check `error` before using `data`.
- *
- * @inputSpec T — the expected shape of a successful result row
- * @outputSpec data: T | null — the query result, null on error
- * @outputSpec error: any — null on success, Postgres/PostgREST error object on failure
- * @calledBy used as return type annotation across all functions/*.ts handlers
- *
- * @example
- * ```ts
- * const result: DbResult<Item> = await adminDb.from('items').select('*').single()
- * if (result.error) throw result.error
- * return result.data!
- * ```
- */
+// CIL[END chunk_id="db_getuserdb_1784066609"]
+// CIL[BEGIN chunk_id="db_dbresult_1784066609" type="type" identity="DbResult" parent="none"]
+// CIL[DOC-MACRO purpose="Database operation result type"]
+// CIL[DOC-RESPONSIBILITY responsibility="Define standard database response structure"]
+// CIL[DOC-CONTEXT module="_shared/db" layer="infrastructure" related_files="[\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\"custom/apps/cortex/functions/custom_cil-embeddings.ts\",\".framework/functions/_shared/schema-utils.ts\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="DbResult type" errors="none" side_effects="type definition"]
+// CIL[DOC-MICRO logic_summary="Generic type for database operations with data and error fields" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: infrastructure. Direct callers: 0. Direct calls: 0. Related files: custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/pages/admin/TypeDetailPage.tsx, custom/apps/cortex/functions/custom_cil-embeddings.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"]
 export type DbResult<T> = {
   data: T | null
   error: any
 }
-
-// ─── JOIN HELPERS ─────────────────────────────────────────────────────────────
-
-/**
- * PostgREST relationship hint strings for all foreign keys in the public schema.
- *
- * These strings are interpolated into `.select()` calls to eager-load related
- * records in a single query. They use explicit `!fk_column` hints to resolve
- * ambiguous relationships — required when a table has multiple FKs to the same
- * target table, or when the FK column name doesn't follow PostgREST's default
- * `tablename_id` inference convention (e.g. `created_by` → `people.id`).
- *
- * Only add a join here when it is used in two or more handlers. One-off joins
- * should be written inline.
- *
- * @inputSpec none — these are static string constants
- * @outputSpec string — valid PostgREST embed expression for use in .select()
- * @sideEffects none
- * @calledBy types.ts, apps.ts, pipelines.ts, triggers.ts, admin-data.ts, and others
- * @testUnit none — these are string constants; incorrect joins fail at runtime
- * @testIntegration tests/integration/admin-data-accounts.test.ts — exercises joins.type
- *
- * @example
- * ```ts
- * import { joins } from './_shared/db'
- * const { data } = await ctx.db
- *   .from('items')
- *   .select(`*, ${joins.type}, ${joins.app}`)
- * // Returns items with nested type and app objects
- * ```
- */
+// CIL[END chunk_id="db_dbresult_1784066609"]
+// CIL[BEGIN chunk_id="db_joins_1784066609" type="variable" identity="joins" parent="none"]
+// CIL[DOC-MACRO purpose="Database join configuration for common relationships"]
+// CIL[DOC-RESPONSIBILITY responsibility="Define standard foreign key join patterns"]
+// CIL[DOC-CONTEXT module="_shared/db" layer="infrastructure" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="join configuration object" errors="none" side_effects="query optimization"]
+// CIL[DOC-MICRO logic_summary="Predefined join strings for common table relationships" 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: infrastructure. 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 joins = {
   type:         'type:types!type_id(id, slug, name, icon, color, design_schema)',
   app:          'app:apps!app_id(id, slug, name)',
@@ -166,3 +119,4 @@ export const joins = {
   role:         'role:roles!role_id(id, slug, name)',
   pipeline:     'pipeline:pipelines!pipeline_id(id, name)',
 }
+// CIL[END chunk_id="db_joins_1784066609"]

package/.framework/functions/_shared/hash-api-key.ts

@@ -0,0 +1,63 @@
+// CIL[BEGIN chunk_id="hash_api_key_module_header_1784200005" type="module_header" identity="imports" parent="none"]
+// CIL[DOC-MACRO purpose="Hash and verify API keys using PBKDF2"]
+// CIL[DOC-RESPONSIBILITY responsibility="Generate secure, salted key hashes and verify raw keys"]
+// CIL[DOC-CONTEXT module="hash_api_key" layer="infrastructure" related_files="[".framework/functions/api-keys.ts",".framework/functions/integration-routes.ts"]"]
+// CIL[DOC-CONTRACT inputs="raw key" outputs="{ key_prefix, key_hash }" errors="hashing error" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Uses crypto.pbkdf2Sync to derive a 32-byte key from a random salt and the raw key. Stored format is pbkdf2$<iterations>$<salt base64>$<hash base64>." notable_decisions="["PBKDF2 is built into Node; no extra dependency.","Format is self-describing so iterations can be upgraded later.","key_prefix is the first 8 characters of the raw key for lookup."]"]
+// CIL[DOC-CONFIDENCE pass="first" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="experimental"]
+// CIL[DOC-AUDIENCE audience="developer"]
+// CIL[DOC-VECTOR type="context" content="Layer: infrastructure. Direct callers: 0. Direct calls: 0. Related files: .framework/functions/api-keys.ts, .framework/functions/integration-routes.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="Uses Node crypto only."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="Hash on key creation; verify on inbound webhook."]
+// CIL[DOC-VECTOR type="user_journey" content="Machine-principal credential lifecycle."]
+
+import { randomBytes, pbkdf2Sync, timingSafeEqual } from 'crypto'
+
+const ITERATIONS = 100000
+const KEY_LENGTH = 32
+const DIGEST = 'sha256'
+
+export function hashApiKey(rawKey: string, iterations = ITERATIONS): { key_prefix: string; key_hash: string; rawKey: string } {
+  const key_prefix = rawKey.slice(0, 8)
+  const salt = randomBytes(16)
+  const hash = pbkdf2Sync(rawKey, salt, iterations, KEY_LENGTH, DIGEST)
+  const key_hash = `pbkdf2$${iterations}$${salt.toString('base64url')}$${hash.toString('base64url')}`
+
+  return { key_prefix, key_hash, rawKey }
+}
+
+export function verifyApiKey(rawKey: string, keyHash: string): boolean {
+  if (!keyHash || !keyHash.startsWith('pbkdf2$')) {
+    return false
+  }
+
+  const parts = keyHash.split('$')
+  if (parts.length !== 4) return false
+
+  const [, iterStr, saltB64, hashB64] = parts
+  const iterations = parseInt(iterStr, 10)
+  if (Number.isNaN(iterations) || iterations <= 0) return false
+
+  let salt: Buffer
+  let storedHash: Buffer
+  try {
+    salt = Buffer.from(saltB64, 'base64url')
+    storedHash = Buffer.from(hashB64, 'base64url')
+  } catch {
+    return false
+  }
+
+  const derived = pbkdf2Sync(rawKey, salt, iterations, storedHash.length, DIGEST)
+  if (derived.length !== storedHash.length) return false
+
+  try {
+    return timingSafeEqual(derived, storedHash)
+  } catch {
+    return false
+  }
+}
+
+// CIL[END chunk_id="hash_api_key_module_header_1784200005"]