spine-framework 0.4.4 → 0.5.0-rc.4

package/.framework/cli/lib/project-files.ts

@@ -33,10 +33,31 @@ export interface ProjectProfile {
   config_files: string[]
   root_scripts: string[]
   bin: string[]
+  /**
+   * Agent-facing assets init copies into the customer repo. Unlike the
+   * categories above, these are NOT copied verbatim into a matching path —
+   * each entry names a package `source`, a project `dest`, and a `merge`
+   * mode handled by syncAgentFiles:
+   *   framework-block — render the template, substitute {{SPINE_VERSION}},
+   *     and merge only the marked framework block into dest (init writes the
+   *     whole file; upgrade replaces the block between the markers and
+   *     preserves everything else).
+   *   dir-replace — copy the source directory tree to dest; on every run,
+   *     `spine-*` subdirectories under dest are removed first, so framework
+   *     skills are replaced wholesale while customer-owned sibling dirs
+   *     (any name not starting with `spine-`) are left alone.
+   */
+  agent_files?: AgentFileEntry[]
   exclude_globs: string[]
   package_scripts: Record<string, string>
 }
 
+export interface AgentFileEntry {
+  source: string
+  dest: string
+  merge: 'framework-block' | 'dir-replace'
+}
+
 export interface CollectedFile {
   rel: string
   abs: string
@@ -280,7 +301,11 @@ export function mergePackageJson(opts: {
   }
   for (const [k, v] of Object.entries(opts.newDependencies)) dependencies[k] = v
   for (const [k, v] of Object.entries(opts.newDevDependencies)) devDependencies[k] = v
-  dependencies['spine-framework'] = opts.spineVersion
+  const existingSpec = dependencies['spine-framework']
+  dependencies['spine-framework'] =
+    existingSpec && /^(file:|link:|workspace:|portal:)/.test(existingSpec)
+      ? existingSpec
+      : opts.spineVersion
 
   const frameworkDeps = [
     ...Object.keys(opts.newDependencies),
@@ -322,6 +347,7 @@ export function writeFrozenManifest(opts: {
   projectRoot: string
   frameworkVersion: string
   frameworkDeps: string[]
+  agentFiles?: Record<string, string>
 }): { fileCount: number; treeDigest: string } {
   const { projectRoot } = opts
   const entries = collectProtectedFiles(projectRoot, ['bin'], new Set(['.spine-manifest.json']))
@@ -338,6 +364,9 @@ export function writeFrozenManifest(opts: {
     node: '>=22.13.0',
     npm: '>=10.0.0',
     files,
+    // Agent assets live outside `files` — see the agent-files block comment
+    // above for why sealing them would break verify and upgrade.
+    ...(opts.agentFiles ? { agent_files: opts.agentFiles } : {}),
   }
   fs.writeFileSync(
     path.join(projectRoot, '.spine-manifest.json'),
@@ -347,6 +376,217 @@ export function writeFrozenManifest(opts: {
 }
 // CIL[END stable_id="~/.framework/cli/lib/project-files.ts:manifest:block"]
 
+/*
+ * Agent asset sync — AGENTS.md framework block + .devin/skills/spine-*.
+ *
+ * Marker contract (upgrade.ts, doctor.ts, and tests depend on this format):
+ *
+ *   <!-- spine-framework:begin version=X.Y.Z -->
+ *   ...framework-owned lines...
+ *   <!-- spine-framework:end -->
+ *
+ * - The markers are HTML comments so they are inert in rendered markdown.
+ * - `version=` on the begin marker lets doctor/doctor-style checks read the
+ *   block's framework version without hashing.
+ * - {{SPINE_VERSION}} anywhere in the template (including inside the begin
+ *   marker) is substituted at copy time by renderAgentTemplate.
+ * - Everything outside the markers is customer-owned and never rewritten.
+ *
+ * Manifest semantics: agent files are hashed into the manifest's
+ * `agent_files` map — NOT `files`. Keeping them out of `files` matters:
+ * verify-manifest treats `files` entries as sealed and unions their top-level
+ * dirs into the protected trees, which would flag every customer file under
+ * .devin/ as EXTRA and every edit to AGENTS.md's user section as MODIFIED.
+ * `agent_files` records, per dest rel:
+ *   - framework-block dests: sha256 of the extracted block (LF-normalized),
+ *     so edits outside the markers do not count as drift.
+ *   - dir-replace dests: sha256 of each file under `spine-*` subdirs.
+ */
+
+/** Begin marker: `<!-- spine-framework:begin version=X.Y.Z -->` (version optional on read). */
+export const AGENTS_BEGIN_RE = /<!--\s*spine-framework:begin(?:\s+version=([^\s>]*))?\s*-->/
+/** End marker: `<!-- spine-framework:end -->`. */
+export const AGENTS_END_RE = /<!--\s*spine-framework:end\s*-->/
+
+/** Substitute {{SPINE_VERSION}} placeholders in an agent template. */
+export function renderAgentTemplate(template: string, version: string): string {
+  return template.replace(/\{\{SPINE_VERSION\}\}/g, version)
+}
+
+/**
+ * Locate the framework block inside newline-split lines.
+ * Returns inclusive line indices, or null when no begin marker exists.
+ * An unterminated begin marker spans only its own line — the orphan marker is
+ * consumed on merge while the stale body below degrades into user content
+ * (safe: user content is never deleted, only the framework block is managed).
+ */
+export function findAgentsBlock(lines: string[]): { begin: number; end: number } | null {
+  let begin = -1
+  for (let i = 0; i < lines.length; i++) {
+    if (AGENTS_BEGIN_RE.test(lines[i])) { begin = i; break }
+  }
+  if (begin === -1) return null
+  for (let i = begin + 1; i < lines.length; i++) {
+    if (AGENTS_END_RE.test(lines[i])) return { begin, end: i }
+  }
+  return { begin, end: begin }
+}
+
+/** The framework block's declared version, or null when absent. */
+export function agentsBlockVersion(text: string): string | null {
+  const m = text.match(AGENTS_BEGIN_RE)
+  return m ? (m[1] ?? null) : null
+}
+
+export interface AgentsMergeResult {
+  text: string
+  status: 'replaced' | 'prepended'
+}
+
+/**
+ * Merge the rendered template's framework block into existing AGENTS.md text.
+ * Replaces the marker-delimited span when markers exist (EOL preserved),
+ * otherwise prepends the block ahead of the user's content.
+ */
+export function mergeAgentsFile(existing: string, renderedTemplate: string): AgentsMergeResult {
+  const eol = existing.includes('\r\n') ? '\r\n' : '\n'
+  const tplLines = renderedTemplate.split(/\r?\n/)
+  const tplRange = findAgentsBlock(tplLines)
+  if (!tplRange) {
+    throw new Error('agent template is missing spine-framework begin/end markers')
+  }
+  const blockLines = tplLines.slice(tplRange.begin, tplRange.end + 1)
+
+  const lines = existing.split(/\r?\n/)
+  const range = findAgentsBlock(lines)
+  if (!range) {
+    const body = existing.replace(/^\s+/, '')
+    return { text: `${blockLines.join(eol)}${eol}${eol}${body}`, status: 'prepended' }
+  }
+  const next = [...lines.slice(0, range.begin), ...blockLines, ...lines.slice(range.end + 1)]
+  return { text: next.join(eol), status: 'replaced' }
+}
+
+export interface AgentSyncAction {
+  rel: string
+  action: 'written' | 'replaced' | 'prepended' | 'synced' | 'unchanged' | 'skipped'
+  detail?: string
+}
+
+function copyDirRecursive(srcAbs: string, destAbs: string): void {
+  fs.mkdirSync(destAbs, { recursive: true })
+  for (const dent of fs.readdirSync(srcAbs, { withFileTypes: true })) {
+    const src = path.join(srcAbs, dent.name)
+    const dest = path.join(destAbs, dent.name)
+    if (dent.isDirectory()) copyDirRecursive(src, dest)
+    else if (dent.isFile()) {
+      fs.copyFileSync(src, dest)
+      fs.chmodSync(dest, fs.statSync(src).mode)
+    }
+  }
+}
+
+/**
+ * Apply the profile's agent_files entries to a project tree.
+ * `framework-block` renders + merges the template; `dir-replace` removes
+ * `spine-*` subdirs under dest then copies the source tree in.
+ * dryRun reports the same actions without writing.
+ */
+export function syncAgentFiles(opts: {
+  pkgRoot: string
+  projectRoot: string
+  entries: AgentFileEntry[]
+  version: string
+  dryRun?: boolean
+}): AgentSyncAction[] {
+  const out: AgentSyncAction[] = []
+  for (const entry of opts.entries ?? []) {
+    const srcAbs = path.join(opts.pkgRoot, entry.source)
+    const destAbs = path.join(opts.projectRoot, entry.dest)
+
+    if (entry.merge === 'framework-block') {
+      if (!fs.existsSync(srcAbs)) {
+        out.push({ rel: entry.dest, action: 'skipped', detail: 'template absent from package' })
+        continue
+      }
+      const rendered = renderAgentTemplate(fs.readFileSync(srcAbs, 'utf8'), opts.version)
+      if (!fs.existsSync(destAbs)) {
+        if (!opts.dryRun) {
+          fs.mkdirSync(path.dirname(destAbs), { recursive: true })
+          fs.writeFileSync(destAbs, rendered)
+        }
+        out.push({ rel: entry.dest, action: 'written' })
+      } else {
+        const existing = fs.readFileSync(destAbs, 'utf8')
+        const merged = mergeAgentsFile(existing, rendered)
+        if (merged.text === existing) {
+          out.push({ rel: entry.dest, action: 'unchanged' })
+        } else {
+          if (!opts.dryRun) fs.writeFileSync(destAbs, merged.text)
+          out.push({ rel: entry.dest, action: merged.status })
+        }
+      }
+    } else if (entry.merge === 'dir-replace') {
+      if (!fs.existsSync(srcAbs) || !fs.statSync(srcAbs).isDirectory()) {
+        out.push({ rel: entry.dest, action: 'skipped', detail: 'source dir absent from package' })
+        continue
+      }
+      // Framework owns only the spine-* subdirs of dest — remove them, then
+      // copy the source tree in. Sibling dirs with any other name are
+      // customer-owned and untouched.
+      const removed = fs.existsSync(destAbs)
+        ? fs.readdirSync(destAbs, { withFileTypes: true })
+            .filter((d) => d.isDirectory() && d.name.startsWith('spine-'))
+            .map((d) => d.name)
+        : []
+      if (!opts.dryRun) {
+        for (const name of removed) {
+          fs.rmSync(path.join(destAbs, name), { recursive: true, force: true })
+        }
+        copyDirRecursive(srcAbs, destAbs)
+      }
+      const detail = removed.length ? `removed spine-* dirs: ${removed.join(', ')}` : undefined
+      out.push({ rel: entry.dest, action: 'synced', detail })
+    } else {
+      out.push({ rel: entry.dest, action: 'skipped', detail: `unknown merge mode '${entry.merge}'` })
+    }
+  }
+  return out
+}
+
+/**
+ * Hash the project's installed agent files for the manifest `agent_files` map.
+ * framework-block → hash of the extracted block (LF-normalized, so EOL style
+ * does not matter); dir-replace → one entry per file under `spine-*` subdirs.
+ */
+export function collectAgentFileHashes(
+  projectRoot: string,
+  entries: AgentFileEntry[],
+): Record<string, string> {
+  const hashes: Record<string, string> = {}
+  for (const entry of entries ?? []) {
+    const destAbs = path.join(projectRoot, entry.dest)
+    if (entry.merge === 'framework-block') {
+      if (!fs.existsSync(destAbs)) continue
+      const lines = fs.readFileSync(destAbs, 'utf8').split(/\r?\n/)
+      const range = findAgentsBlock(lines)
+      if (!range) continue
+      hashes[entry.dest] = sha256Text(lines.slice(range.begin, range.end + 1).join('\n') + '\n')
+    } else if (entry.merge === 'dir-replace') {
+      if (!fs.existsSync(destAbs)) continue
+      const managed = fs.readdirSync(destAbs, { withFileTypes: true })
+        .filter((d) => d.isDirectory() && d.name.startsWith('spine-'))
+      for (const dir of managed) {
+        const dirAbs = path.join(destAbs, dir.name)
+        for (const f of walkDir(dirAbs, projectRoot, [])) {
+          hashes[f.rel] = sha256File(f.abs)
+        }
+      }
+    }
+  }
+  return hashes
+}
+
 // CIL[BEGIN stable_id="~/.framework/cli/lib/project-files.ts:file_io:block" type="block" identity="file_io" parent="~/.framework/cli/lib/project-files.ts"]
 // CIL[DOC-MACRO purpose="Copy collected files (mode-preserving, symlink safety-checked), sanitize dir names to npm package names, compare semvers"]
 // CIL[DOC-CONTEXT module="cli" layer="lib" related_files=""]

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

@@ -1,81 +1,135 @@
 // CIL[BEGIN stable_id="~/.framework/functions/_shared/hash-api-key.ts:module_header:module_header" type="module_header" identity="module_header" parent="~/.framework/functions/_shared/hash-api-key.ts"]
-// CIL[DOC-MACRO purpose="Provides PBKDF2-based API key hashing and verification utilities"]
-// CIL[DOC-RESPONSIBILITY responsibility="Imports crypto primitives and exports hashApiKey and verifyApiKey"]
-// CIL[DOC-CONTEXT module="functions/_shared" layer="shared" related_files=".framework/functions/_shared/hash-api-key.ts"]
-// CIL[DOC-CONTRACT inputs="none" outputs="none" errors="none" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Imports crypto functions used by hashing and verification" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-AUDIENCE audience="developers"]
+/**
+ * @module   hash-api-key
+ * @audience both
+ * @layer    shared-core
+ * @stability stable
+ *
+ * This module provides utilities for securely hashing API keys using cryptographic functions. It plays a crucial role in ensuring the integrity and confidentiality of sensitive data within the application. INVARIANT: The API keys must always be hashed before storage to prevent unauthorized access.
+ *
+ * @seeAlso crypto (provides cryptographic functions for hashing).
+ *
+ * @cil-generated
+ */
+
+
+
+
+
+
+
+
+
 
 
 import { randomBytes, pbkdf2Sync, timingSafeEqual } from 'crypto'
-// CIL[DOC-VECTOR type="context" content="purpose='Provides PBKDF2-based API key hashing and verification utilities'; No verified external callers; imports: none"]
-// 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/_shared/hash-api-key.ts:module_header:module_header"]
 
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 // CIL[BEGIN stable_id="~/.framework/functions/_shared/hash-api-key.ts:ITERATIONS:constant" type="constant" identity="ITERATIONS" parent="~/.framework/functions/_shared/hash-api-key.ts"]
-// CIL[DOC-MACRO purpose="Defines the default PBKDF2 iteration count"]
-// CIL[DOC-RESPONSIBILITY responsibility="Stores the default number of PBKDF2 iterations for hashing"]
-// CIL[DOC-CONTEXT module="functions/_shared" layer="shared" related_files=".framework/functions/_shared/hash-api-key.ts"]
-// CIL[DOC-CONTRACT inputs="none" outputs="number" errors="none" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Constant default iteration count used by hashApiKey" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
+/**
+ * ITERATIONS defines the number of iterations used for hashing an API key, ensuring a high level of security. This constant is crucial for maintaining the strength of the hashing process.
+ *
+ * @sideEffects none
+ * @stability   internal
+ * @cil-generated
+ */
 const ITERATIONS = 100000
-// CIL[DOC-VECTOR type="context" content="purpose='Defines the default PBKDF2 iteration count'; No verified external callers; imports: none"]
-// 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/_shared/hash-api-key.ts:ITERATIONS:constant"]
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 // CIL[BEGIN stable_id="~/.framework/functions/_shared/hash-api-key.ts:KEY_LENGTH:constant" type="constant" identity="KEY_LENGTH" parent="~/.framework/functions/_shared/hash-api-key.ts"]
-// CIL[DOC-MACRO purpose="Defines the derived key length in bytes for PBKDF2"]
-// CIL[DOC-RESPONSIBILITY responsibility="Stores the PBKDF2 derived key length"]
-// CIL[DOC-CONTEXT module="functions/_shared" layer="shared" related_files=".framework/functions/_shared/hash-api-key.ts"]
-// CIL[DOC-CONTRACT inputs="none" outputs="number" errors="none" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Constant derived key length used by hashApiKey" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
+/**
+ * KEY_LENGTH defines the length of the API key used for hashing to ensure a consistent key size for security purposes.
+ *
+ * @sideEffects none
+ * @stability   internal
+ * @cil-generated
+ */
 const KEY_LENGTH = 32
-// CIL[DOC-VECTOR type="context" content="purpose='Defines the derived key length in bytes for PBKDF2'; No verified external callers; imports: none"]
-// 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/_shared/hash-api-key.ts:KEY_LENGTH:constant"]
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 // CIL[BEGIN stable_id="~/.framework/functions/_shared/hash-api-key.ts:DIGEST:constant" type="constant" identity="DIGEST" parent="~/.framework/functions/_shared/hash-api-key.ts"]
-// CIL[DOC-MACRO purpose="Defines the digest algorithm for PBKDF2"]
-// CIL[DOC-RESPONSIBILITY responsibility="Stores the PBKDF2 digest algorithm"]
-// CIL[DOC-CONTEXT module="functions/_shared" layer="shared" related_files=".framework/functions/_shared/hash-api-key.ts"]
-// CIL[DOC-CONTRACT inputs="none" outputs="string" errors="none" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Constant digest algorithm used by hashApiKey and verifyApiKey" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
+/**
+ * DIGEST defines the hashing algorithm used for API key generation, specifically SHA-256. It provides a consistent and secure method for hashing within the module.
+ *
+ * @sideEffects none
+ * @stability   internal
+ * @cil-generated
+ */
 const DIGEST = 'sha256'
-// CIL[DOC-VECTOR type="context" content="purpose='Defines the digest algorithm for PBKDF2'; No verified external callers; imports: none"]
-// 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/_shared/hash-api-key.ts:DIGEST:constant"]
 
 
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 // CIL[BEGIN stable_id="~/.framework/functions/_shared/hash-api-key.ts:hashApiKey:function" type="function" identity="hashApiKey" parent="~/.framework/functions/_shared/hash-api-key.ts"]
-// CIL[DOC-MACRO purpose="Hash a raw API key using PBKDF2 and return a storable key record"]
-// CIL[DOC-RESPONSIBILITY responsibility="Derive a salted PBKDF2 hash, prefix the raw key, and return a hash string"]
-// CIL[DOC-CONTEXT module="functions/_shared" layer="shared" related_files=".framework/functions/_shared/hash-api-key.ts"]
-// CIL[DOC-CONTRACT inputs="rawKey: string, iterations = ITERATIONS" outputs="{ key_prefix: string, key_hash: string, rawKey: string }" errors="none" side_effects="Uses crypto.randomBytes and pbkdf2Sync to generate salt and hash"]
-// CIL[DOC-MICRO logic_summary="Extracts an 8-character prefix, generates a random salt, derives a 32-byte PBKDF2 hash, and encodes the result as pbkdf2$iterations$salt$hash" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
+/**
+ * Hashes a raw API key using PBKDF2 to enhance security and returns the key prefix along with the hashed key. This function is essential for securely storing API keys.
+ *
+ * @inputSpec
+ *   - rawKey: string (required) — the raw API key to be hashed.
+ *   - iterations: number (optional) — the number of iterations for the PBKDF2 algorithm, defaults to ITERATIONS.
+ * @outputSpec  { key_prefix: string; key_hash: string; rawKey: string }
+ * @sideEffects none
+ * @stability   internal
+ * @calls       randomBytes, pbkdf2Sync
+ * @cil-generated
+ */
 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)
@@ -84,23 +138,37 @@ export function hashApiKey(rawKey: string, iterations = ITERATIONS): { key_prefi
 
   return { key_prefix, key_hash, rawKey }
 }
-// CIL[DOC-VECTOR type="context" content="purpose='Hash a raw API key using PBKDF2 and return a storable key record'; No verified external callers; imports: none"]
-// 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/_shared/hash-api-key.ts:hashApiKey:function"]
 
 
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 // CIL[BEGIN stable_id="~/.framework/functions/_shared/hash-api-key.ts:verifyApiKey:function" type="function" identity="verifyApiKey" parent="~/.framework/functions/_shared/hash-api-key.ts"]
-// CIL[DOC-MACRO purpose="Verify a raw API key against a stored PBKDF2 hash"]
-// CIL[DOC-RESPONSIBILITY responsibility="Parse the stored hash, re-derive the key, and compare hashes timing-safely"]
-// CIL[DOC-CONTEXT module="functions/_shared" layer="shared" related_files=".framework/functions/_shared/hash-api-key.ts"]
-// CIL[DOC-CONTRACT inputs="rawKey: string, keyHash: string" outputs="boolean" errors="Returns false for invalid format, missing parts, non-positive iterations, base64 decode errors, or mismatched lengths" side_effects="Uses crypto.pbkdf2Sync and timingSafeEqual"]
-// CIL[DOC-MICRO logic_summary="Validates the keyHash format, extracts iterations and salt, derives the hash with the stored length, and compares with timingSafeEqual" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
+/**
+ * Verifies an API key against a stored hash to ensure its validity. This function is essential for securing access to resources by validating the provided key.
+ *
+ * @inputSpec
+ *   - rawKey: string (required) — the API key to verify.
+ *   - keyHash: string (required) — the hashed representation of the API key.
+ * @outputSpec  boolean — returns true if the API key is valid, otherwise false.
+ * @sideEffects none
+ * @stability   internal
+ * @calls       pbkdf2Sync, timingSafeEqual
+ * @cil-generated
+ */
 export function verifyApiKey(rawKey: string, keyHash: string): boolean {
   if (!keyHash || !keyHash.startsWith('pbkdf2$')) {
     return false
@@ -131,10 +199,46 @@ export function verifyApiKey(rawKey: string, keyHash: string): boolean {
     return false
   }
 }
-// CIL[DOC-VECTOR type="context" content="purpose='Verify a raw API key against a stored PBKDF2 hash'; No verified external callers; imports: none"]
-// 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/_shared/hash-api-key.ts:verifyApiKey:function"]
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+// CIL[BEGIN stable_id="~/.framework/functions/_shared/hash-api-key.ts:omitSecretFields:function" type="function" identity="omitSecretFields" parent="~/.framework/functions/_shared/hash-api-key.ts"]
+/**
+ * The omitSecretFields function removes sensitive fields from an object to prevent exposure of secret information. It is designed to sanitize data before further processing or transmission.
+ *
+ * @inputSpec
+ *   row: Record<string, any> | null | undefined — the object from which secret fields will be omitted.
+ * @outputSpec  Record<string, any> | null | undefined — a new object without the omitted fields, or the original input if it was not an object.
+ * @sideEffects none
+ * @stability   internal
+ * @cil-generated
+ */
+export function omitSecretFields(row: Record<string, any> | null | undefined) {
+  if (!row || typeof row !== 'object') return row
+  const copy = { ...row }
+  delete copy.key_value
+  delete copy.key_hash
+  return copy
+}
+// CIL[END stable_id="~/.framework/functions/_shared/hash-api-key.ts:omitSecretFields:function"]
+
+
+
+
+
+
+