spine-framework 0.4.3 → 0.5.0-rc.4

package/.framework/functions/pipeline-runner-background.ts

@@ -0,0 +1,120 @@
+// CIL[BEGIN stable_id="~/.framework/functions/pipeline-runner-background.ts:module_header:module_header" type="module_header" identity="module_header" parent="~/.framework/functions/pipeline-runner-background.ts"]
+// CIL[DOC-MACRO purpose="Background entry point for event-triggered pipeline executions — receives dispatched payloads from checkAndFireTriggers and runs the pipeline in an isolated process with its own connection budget"]
+// CIL[DOC-RESPONSIBILITY responsibility="Authenticate internal dispatch calls via INTERNAL_INVOKE_SECRET, reconstruct a machine RequestContext, and invoke runPipeline with the pre-created execution_id so the queued row transitions to running/completed rather than being duplicated"]
+// CIL[DOC-CONTEXT module="pipeline-runner-background" layer="functions" related_files=".framework/functions/_shared/trigger-engine.ts,.framework/functions/_shared/pipeline-runner.ts,.framework/functions/_shared/principal.ts,.framework/functions/_shared/middleware.ts"]
+// CIL[DOC-CONTRACT inputs="POST body { pipeline_id, trigger_data, account_id, execution_id, trigger_id } with X-Internal-Secret header" outputs="{ ok: true, execution_id } | { error }" errors="403 on missing/wrong secret, 400 on missing pipeline_id, 500 on pipeline failure" side_effects="Runs the named pipeline; updates pipeline_executions row from queued→running→terminal"]
+// CIL[DOC-MICRO logic_summary="Validates the shared internal secret (timing-safe, same as principal.isInternalInvokeAuthorized), builds a SYSTEM_PRINCIPAL RequestContext carrying the original account scope, then calls runPipeline with the caller's pre-created execution_id. Status 'queued' → 'running' is handled inside runPipeline via the new opts.executionId parameter." notable_decisions="Does NOT use createHandler — it would resolve the secret to anonymous and 401 before reaching the handler. Auth is checked inline and SYSTEM_PRINCIPAL provides the machine context directly."]
+// CIL[DOC-CONFIDENCE pass="first" score="0.9" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-AUDIENCE audience="framework"]
+
+import { createHash, timingSafeEqual } from 'node:crypto'
+import { runPipeline, sweepStaleExecutions } from './_shared/pipeline-runner'
+import { SYSTEM_PRINCIPAL } from './_shared/principal'
+import { adminDb } from './_shared/db'
+// CIL[END stable_id="~/.framework/functions/pipeline-runner-background.ts:module_header:module_header"]
+
+
+// CIL[BEGIN stable_id="~/.framework/functions/pipeline-runner-background.ts:isdispatchauthorized:function" type="function" identity="isDispatchAuthorized" parent="~/.framework/functions/pipeline-runner-background.ts"]
+// CIL[DOC-MACRO purpose="Verify the X-Internal-Secret header using timing-safe comparison (mirrors principal.isInternalInvokeAuthorized)"]
+// CIL[DOC-RESPONSIBILITY responsibility="Return true only when the request carries a valid INTERNAL_INVOKE_SECRET"]
+// CIL[DOC-CONTEXT module="pipeline-runner-background" layer="functions" related_files=".framework/functions/_shared/principal.ts"]
+// CIL[DOC-CONTRACT inputs="event headers" outputs="boolean" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="SHA-256 both sides before timingSafeEqual so early-exit on length mismatch cannot leak the expected secret length via response timing — identical pattern to principal.isInternalInvokeAuthorized" notable_decisions="duplicated here rather than imported because isInternalInvokeAuthorized is unexported from principal.ts"]
+// CIL[DOC-CONFIDENCE pass="first" score="0.9" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+function isDispatchAuthorized(event: any): boolean {
+  const expected = (globalThis as any).process?.env?.INTERNAL_INVOKE_SECRET
+  if (!expected) return false
+
+  const provided = event.headers?.['x-internal-secret'] || event.headers?.['X-Internal-Secret']
+  if (!provided || typeof provided !== 'string') return false
+
+  const expectedHash = createHash('sha256').update(expected).digest()
+  const providedHash = createHash('sha256').update(provided).digest()
+
+  try {
+    return timingSafeEqual(expectedHash, providedHash)
+  } catch {
+    return false
+  }
+}
+// CIL[END stable_id="~/.framework/functions/pipeline-runner-background.ts:isdispatchauthorized:function"]
+
+
+// CIL[BEGIN stable_id="~/.framework/functions/pipeline-runner-background.ts:handler:constant" type="constant" identity="handler" parent="~/.framework/functions/pipeline-runner-background.ts"]
+// CIL[DOC-MACRO purpose="Netlify function handler for dispatched pipeline executions"]
+// CIL[DOC-RESPONSIBILITY responsibility="Authenticate, sweep stale executions, then runPipeline with the caller's pre-created execution_id"]
+// CIL[DOC-CONTEXT module="pipeline-runner-background" layer="functions" related_files=".framework/functions/_shared/pipeline-runner.ts"]
+// CIL[DOC-CONTRACT inputs="POST body { pipeline_id, trigger_data, account_id, execution_id, trigger_id }" outputs="{ ok, execution_id, status } | { error }" errors="403 unauthorized, 400 missing pipeline_id" side_effects="Pipeline runs; pipeline_executions transitions queued→running→terminal"]
+// CIL[DOC-MICRO logic_summary="Reject without INTERNAL_INVOKE_SECRET; build SYSTEM_PRINCIPAL ctx scoped to the dispatching account; runPipeline with opts.executionId so the pre-created row is claimed rather than duplicated; return the final ExecutionResult" notable_decisions="sweepStaleExecutions is called opportunistically on entry — same fire-and-forget pattern as runPipeline itself, but on a fresh process it costs nothing"]
+// CIL[DOC-CONFIDENCE pass="first" score="0.9" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+export const handler = async (event: any, _context: any) => {
+  const requestId = crypto.randomUUID()
+
+  if (!isDispatchAuthorized(event)) {
+    return {
+      statusCode: 403,
+      body: JSON.stringify({ error: 'Forbidden — invalid internal secret' }),
+    }
+  }
+
+  let body: any = {}
+  try {
+    body = typeof event.body === 'string' ? JSON.parse(event.body || '{}') : (event.body || {})
+  } catch {
+    return { statusCode: 400, body: JSON.stringify({ error: 'Invalid JSON body' }) }
+  }
+
+  const { pipeline_id, trigger_data, account_id, execution_id, trigger_id } = body
+
+  if (!pipeline_id) {
+    return { statusCode: 400, body: JSON.stringify({ error: 'pipeline_id is required' }) }
+  }
+
+  // Opportunistic sweep — picks up any executions orphaned by a prior dead
+  // invocation before this one starts its own work.
+  void sweepStaleExecutions().catch(() => {})
+
+  const ctx = {
+    requestId,
+    principal: {
+      ...SYSTEM_PRINCIPAL,
+      provenance: {
+        ...SYSTEM_PRINCIPAL.provenance,
+        sourceType: 'trigger' as const,
+        invokedAt: new Date().toISOString(),
+        triggerId: trigger_id || null,
+      },
+    },
+    db: adminDb,
+    accountId: account_id || null,
+    appId: null,
+    query: {},
+    requestPath: '/.netlify/functions/pipeline-runner-background',
+    headers: event.headers || {},
+  }
+
+  try {
+    const result = await runPipeline(pipeline_id, trigger_data || {}, ctx as any, {
+      executionId: execution_id,
+    })
+
+    return {
+      statusCode: 200,
+      body: JSON.stringify({
+        ok: result.status === 'completed',
+        execution_id: result.executionId,
+        status: result.status,
+      }),
+    }
+  } catch (err: any) {
+    console.error(`[${requestId}] pipeline-runner-background failed for pipeline ${pipeline_id}:`, err)
+    return {
+      statusCode: 500,
+      body: JSON.stringify({ error: err.message || 'Pipeline execution failed', execution_id }),
+    }
+  }
+}
+// CIL[END stable_id="~/.framework/functions/pipeline-runner-background.ts:handler:constant"]

package/.framework/functions/pipelines.ts

@@ -176,7 +176,8 @@ export const create = createHandler(async (ctx, body) => {
     throw new Error('User context (person and account) required')
   }
 
-  const { data, error: err } = await ctx.db
+  const db = isSystemAdmin(ctx.principal) ? adminDb : ctx.db
+  const { data, error: err } = await db
     .from('pipelines')
     .insert({
       app_id: app_id || null,
@@ -187,7 +188,7 @@ export const create = createHandler(async (ctx, body) => {
       config: config || {},
       stages,
       metadata: metadata || {},
-      created_by: ctx.principal.id
+      created_by: ctx.principal.type === 'human' ? ctx.principal.id : null
     })
     .select()
     .single()
@@ -228,7 +229,8 @@ export const update = createHandler(async (ctx, body) => {
     throw new Error('User context (person and account) required')
   }
 
-  const { data: current } = await ctx.db
+  const db = isSystemAdmin(ctx.principal) ? adminDb : ctx.db
+  const { data: current } = await db
     .from('pipelines')
     .select('*')
     .eq('id', id)
@@ -248,7 +250,7 @@ export const update = createHandler(async (ctx, body) => {
   if (is_active !== undefined) updateData.is_active = is_active
   if (app_id !== undefined) updateData.app_id = app_id
 
-  const { data, error: err } = await ctx.db
+  const { data, error: err } = await db
     .from('pipelines')
     .update(updateData)
     .eq('id', id)
@@ -290,7 +292,8 @@ export const toggle = createHandler(async (ctx, body) => {
     throw new Error('User context (person and account) required')
   }
 
-  const { data: current } = await ctx.db
+  const db = isSystemAdmin(ctx.principal) ? adminDb : ctx.db
+  const { data: current } = await db
     .from('pipelines')
     .select('*')
     .eq('id', id)
@@ -300,7 +303,7 @@ export const toggle = createHandler(async (ctx, body) => {
     throw new Error('Pipeline not found')
   }
 
-  const { data, error: err } = await ctx.db
+  const { data, error: err } = await db
     .from('pipelines')
     .update({ is_active, updated_at: new Date().toISOString() })
     .eq('id', id)
@@ -338,7 +341,8 @@ export const getExecutions = createHandler(async (ctx, _body) => {
     throw new Error('Pipeline ID is required')
   }
 
-  const { data, error: err } = await ctx.db
+  const db = isSystemAdmin(ctx.principal) ? adminDb : ctx.db
+  const { data, error: err } = await db
     .from('pipeline_executions')
     .select('*')
     .eq('pipeline_id', pipeline_id)
@@ -374,7 +378,8 @@ export const remove = createHandler(async (ctx, _body) => {
     throw new Error('Pipeline ID is required')
   }
 
-  const { data: current } = await ctx.db
+  const db = isSystemAdmin(ctx.principal) ? adminDb : ctx.db
+  const { data: current } = await db
     .from('pipelines')
     .select('id, name')
     .eq('id', id)
@@ -382,7 +387,7 @@ export const remove = createHandler(async (ctx, _body) => {
 
   if (!current) throw new Error('Pipeline not found')
 
-  const { error: err } = await ctx.db
+  const { error: err } = await db
     .from('pipelines')
     .delete()
     .eq('id', id)

package/.framework/functions/prompt-configs.ts

@@ -131,7 +131,8 @@ export const create = createHandler(async (ctx, body) => {
     throw new Error('Account context required')
   }
 
-  const { data, error: err } = await ctx.db
+  const db = isSystemAdmin(ctx.principal) ? adminDb : ctx.db
+  const { data, error: err } = await db
     .from('prompt_configs')
     .insert({
       app_id: app_id || null,
@@ -201,7 +202,8 @@ export const update = createHandler(async (ctx, body) => {
     if (updates[key] !== undefined) updateData[key] = updates[key]
   }
 
-  const { data, error: err } = await ctx.db
+  const db = isSystemAdmin(ctx.principal) ? adminDb : ctx.db
+  const { data, error: err } = await db
     .from('prompt_configs')
     .update(updateData)
     .eq('id', id)
@@ -239,7 +241,8 @@ export const remove = createHandler(async (ctx, _body) => {
     throw new Error('Config ID is required')
   }
 
-  const { data: current } = await ctx.db
+  const db = isSystemAdmin(ctx.principal) ? adminDb : ctx.db
+  const { data: current } = await db
     .from('prompt_configs')
     .select('id, name, slug')
     .eq('id', id)
@@ -247,7 +250,7 @@ export const remove = createHandler(async (ctx, _body) => {
 
   if (!current) throw new Error('Prompt config not found')
 
-  const { error: err } = await ctx.db
+  const { error: err } = await db
     .from('prompt_configs')
     .delete()
     .eq('id', id)

package/.framework/functions/roles.ts

@@ -188,7 +188,8 @@ export const create = createHandler(async (ctx, body) => {
     throw new Error('Role slug already exists for this app')
   }
 
-  const { data, error: err } = await ctx.db
+  const db = permissions.isSystemAdmin(ctx) ? adminDb : ctx.db
+  const { data, error: err } = await db
     .from('roles')
     .insert({
       app_id,
@@ -234,7 +235,8 @@ export const update = createHandler(async (ctx, body) => {
     throw new Error('User context (person and account) required')
   }
 
-  const { data: current, error: fetchErr } = await ctx.db
+  const db = permissions.isSystemAdmin(ctx) ? adminDb : ctx.db
+  const { data: current, error: fetchErr } = await db
     .from('roles')
     .select('*')
     .eq('id', id)
@@ -255,7 +257,7 @@ export const update = createHandler(async (ctx, body) => {
     throw new Error(fieldValidation.error)
   }
 
-  const { data, error: err } = await ctx.db
+  const { data, error: err } = await db
     .from('roles')
     .update({
       ...updates,
@@ -297,7 +299,8 @@ export const remove = createHandler(async (ctx, body) => {
     throw new Error('User context (person and account) required')
   }
 
-  const { data: current, error: fetchErr } = await ctx.db
+  const db = permissions.isSystemAdmin(ctx) ? adminDb : ctx.db
+  const { data: current, error: fetchErr } = await db
     .from('roles')
     .select('*')
     .eq('id', id)
@@ -307,7 +310,7 @@ export const remove = createHandler(async (ctx, body) => {
     throw new Error('Role not found or access denied')
   }
 
-  const { data, error: err } = await ctx.db
+  const { data, error: err } = await db
     .from('roles')
     .update({
       is_active: false,

package/.framework/functions/security.ts

@@ -1,3 +1,4 @@
+// CIL[BEGIN stable_id="~/.framework/functions/security.ts:module_header:module_header" type="module_header" identity="module_header" parent="~/.framework/functions/security.ts"]
 /**
  * @module   security
  * @audience internal
@@ -15,7 +16,6 @@
  *
  * @cil-generated
  */
-// CIL[BEGIN stable_id="~/.framework/functions/security.ts:module_header:module_header" type="module_header" identity="module_header" parent="~/.framework/functions/security.ts"]
 // CIL[DOC-MACRO purpose="System-admin security operations: flagged-actor report, ban/unban, blocklist CRUD, Netlify edge sync"]
 // CIL[DOC-RESPONSIBILITY responsibility="Aggregate security.* audit events into a flagged-accounts report; apply three-layer bans (security_blocklist + auth.admin ban_duration + Netlify firewall rule); expose blocklist list/add/revoke"]
 // CIL[DOC-CONTEXT module="functions" layer="security" related_files=".framework/functions/_shared/security.ts,.framework/migrations/049_security_blocklist.sql,.framework/src/pages/admin/SecurityPage.tsx"]
@@ -29,15 +29,19 @@ import { adminDb } from './_shared/db'
 import { emitAudit } from './_shared/audit'
 // CIL[END stable_id="~/.framework/functions/security.ts:module_header:module_header"]
 
-// CIL[BEGIN stable_id="~/.framework/functions/security.ts:netlifyedgesync:comment" type="comment" identity="netlifyEdgeSync" parent="~/.framework/functions/security.ts"]
 // CIL[DOC-MACRO purpose="Netlify Firewall Traffic Rules sync for banned IPs"]
 // CIL[DOC-RESPONSIBILITY responsibility="Keep a single managed ip-deny rule (description spine-security:blocklist) whose data.addresses mirrors active ip blocklist entries"]
 // CIL[DOC-CONTRACT inputs="ips to add/remove" outputs="{ synced: boolean, skipped?: boolean, error?: string }" errors="never throws — returns error field" side_effects="Netlify API GET/PUT of full ruleset"]
 // CIL[DOC-MICRO logic_summary="GET firewall_rule_set → mutate managed rule's addresses (or create rule) → PUT whole published ruleset back; user-managed rules are preserved verbatim" notable_decisions="PUT replaces the entire ruleset, so the full published rule list is round-tripped; concurrent edits could still race — acceptable at admin-action frequency"]
 // CIL[DOC-STABILITY stability="experimental"]
+// CIL[BEGIN stable_id="~/.framework/functions/security.ts:MANAGED_RULE_DESC:constant" type="constant" identity="MANAGED_RULE_DESC" parent="~/.framework/functions/security.ts"]
 const MANAGED_RULE_DESC = 'spine-security:blocklist'
+// CIL[END stable_id="~/.framework/functions/security.ts:MANAGED_RULE_DESC:constant"]
+// CIL[BEGIN stable_id="~/.framework/functions/security.ts:NETLIFY_API:constant" type="constant" identity="NETLIFY_API" parent="~/.framework/functions/security.ts"]
 const NETLIFY_API = 'https://api.netlify.com'
+// CIL[END stable_id="~/.framework/functions/security.ts:NETLIFY_API:constant"]
 
+// CIL[BEGIN stable_id="~/.framework/functions/security.ts:netlifyEdgeSync:function" type="function" identity="netlifyEdgeSync" parent="~/.framework/functions/security.ts"]
 async function netlifyEdgeSync(ipsToAdd: string[], ipsToRemove: string[] = []): Promise<{ synced: boolean; skipped?: boolean; error?: string }> {
   const token = process.env.NETLIFY_ACCESS_TOKEN
   const siteId = process.env.NETLIFY_SITE_ID
@@ -90,25 +94,29 @@ async function netlifyEdgeSync(ipsToAdd: string[], ipsToRemove: string[] = []):
     return { synced: false, error: err?.message || 'Netlify sync failed' }
   }
 }
-// CIL[END stable_id="~/.framework/functions/security.ts:netlifyedgesync:comment"]
+// CIL[END stable_id="~/.framework/functions/security.ts:netlifyEdgeSync:function"]
 
-// CIL[BEGIN stable_id="~/.framework/functions/security.ts:flaggedaccounts:function" type="function" identity="flaggedAccounts" parent="~/.framework/functions/security.ts"]
 // CIL[DOC-MACRO purpose="Aggregate security.* audit events into a flagged-actors report"]
 // CIL[DOC-RESPONSIBILITY responsibility="Group recent security.rate_limit_exceeded / injection_detected / registration_blocked log rows by acting person or account, enrich with people + account + blocklist state"]
 // CIL[DOC-CONTRACT inputs="ctx" outputs="{ rows: FlaggedRow[] }" errors="returns empty rows on missing tables" side_effects="logs + people + accounts + security_blocklist reads"]
-// CIL[DOC-MICRO logic_summary="Fetch last 500 security.* events → bucket by person id (fallback account id) → count signals + collect kinds/patterns/ips → join people(email, geo, status), accounts(display_name), active blocklist entries → sort by signal count desc" notable_decisions="IP shown comes from the person's registration_ip/last_ip (trusted edge capture), not spoofable request data"]
+// CIL[DOC-MICRO logic_summary="Fetch last 500 security.* events within 30 days → bucket by person id (fallback account id) → count signals + collect kinds/patterns/ips → join people(email, geo, status), accounts(display_name), active blocklist entries → sort by signal count desc" notable_decisions="IP shown comes from the person's registration_ip/last_ip (trusted edge capture), not spoofable request data; started_at lower bound keeps the span_name scan index-bounded (no span_name index, and zero-signal scans would otherwise walk the whole logs table)"]
 // CIL[DOC-STABILITY stability="experimental"]
+// CIL[BEGIN stable_id="~/.framework/functions/security.ts:SECURITY_SIGNALS:constant" type="constant" identity="SECURITY_SIGNALS" parent="~/.framework/functions/security.ts"]
 const SECURITY_SIGNALS = [
   'security.rate_limit_exceeded',
   'security.injection_detected',
   'security.registration_blocked',
 ]
+// CIL[END stable_id="~/.framework/functions/security.ts:SECURITY_SIGNALS:constant"]
 
+// CIL[BEGIN stable_id="~/.framework/functions/security.ts:flaggedAccounts:function" type="function" identity="flaggedAccounts" parent="~/.framework/functions/security.ts"]
 async function flaggedAccounts(ctx: RequestContext) {
+  const since = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000).toISOString()
   const { data: events, error } = await adminDb
     .from('logs')
     .select('account_id, started_at, metadata')
     .in('span_name', SECURITY_SIGNALS)
+    .gte('started_at', since)
     .order('started_at', { ascending: false })
     .limit(500)
   if (error) {
@@ -194,14 +202,14 @@ async function flaggedAccounts(ctx: RequestContext) {
   rows.sort((a, b) => b.signals - a.signals)
   return { rows }
 }
-// CIL[END stable_id="~/.framework/functions/security.ts:flaggedaccounts:function"]
+// CIL[END stable_id="~/.framework/functions/security.ts:flaggedAccounts:function"]
 
-// CIL[BEGIN stable_id="~/.framework/functions/security.ts:addblockrows:function" type="function" identity="addBlockRows" parent="~/.framework/functions/security.ts"]
 // CIL[DOC-MACRO purpose="Upsert active hard-block rows into security_blocklist"]
 // CIL[DOC-RESPONSIBILITY responsibility="Insert rows with revoked_at cleared on (type,value) conflict so a re-ban re-activates a revoked row"]
 // CIL[DOC-CONTRACT inputs="rows[], bannedBy, reason" outputs="void" errors="throws on DB error" side_effects="security_blocklist upsert"]
 // CIL[DOC-MICRO logic_summary="map rows → upsert onConflict type,value with revoked_at:null" notable_decisions="[]"]
 // CIL[DOC-STABILITY stability="stable"]
+// CIL[BEGIN stable_id="~/.framework/functions/security.ts:addBlockRows:function" type="function" identity="addBlockRows" parent="~/.framework/functions/security.ts"]
 async function addBlockRows(
   rows: Array<{ type: string; value: string }>,
   bannedBy: string | undefined,
@@ -225,14 +233,14 @@ async function addBlockRows(
     )
   if (error) throw new Error('security_blocklist upsert failed: ' + error.message)
 }
-// CIL[END stable_id="~/.framework/functions/security.ts:addblockrows:function"]
+// CIL[END stable_id="~/.framework/functions/security.ts:addBlockRows:function"]
 
-// CIL[BEGIN stable_id="~/.framework/functions/security.ts:banuser:function" type="function" identity="banUser" parent="~/.framework/functions/security.ts"]
 // CIL[DOC-MACRO purpose="Three-layer ban: internal blocklist + Supabase Auth ban + Netlify edge deny"]
 // CIL[DOC-RESPONSIBILITY responsibility="Given a person_id (or bare email/ip), persist blocklist rows for person+email+account+IP, ban the auth user, and push the IP into the managed Netlify deny rule"]
 // CIL[DOC-CONTRACT inputs="ctx, body {person_id?|email?|ip?, reason?, block_ip?, block_email?}" outputs="{ ok, person_id, layers }" errors="400 missing target; 404 person not found; 500 blocklist write failure" side_effects="security_blocklist upserts, auth.admin.updateUserById, Netlify ruleset PUT, audit events"]
 // CIL[DOC-MICRO logic_summary="Resolve person → write blocklist rows (fail = abort) → auth ban via ban_duration 876600h → edge sync for last/registration IP → audit security.user_banned with per-layer results" notable_decisions="Internal blocklist is authoritative and must succeed; auth/edge failures are recorded in the audit event and returned, not thrown — a ban must never half-apply silently"]
 // CIL[DOC-STABILITY stability="experimental"]
+// CIL[BEGIN stable_id="~/.framework/functions/security.ts:banUser:function" type="function" identity="banUser" parent="~/.framework/functions/security.ts"]
 async function banUser(ctx: RequestContext, body: any) {
   const { person_id, email: rawEmail, ip: rawIp, reason, block_ip = true, block_email = true } = body || {}
   if (!person_id && !rawEmail && !rawIp) {
@@ -295,14 +303,14 @@ async function banUser(ctx: RequestContext, body: any) {
 
   return { ok: true, person_id: person?.id || null, email, ip, layers }
 }
-// CIL[END stable_id="~/.framework/functions/security.ts:banuser:function"]
+// CIL[END stable_id="~/.framework/functions/security.ts:banUser:function"]
 
-// CIL[BEGIN stable_id="~/.framework/functions/security.ts:unbanuser:function" type="function" identity="unbanUser" parent="~/.framework/functions/security.ts"]
 // CIL[DOC-MACRO purpose="Reverse a ban: revoke blocklist rows, lift auth ban, remove edge IP"]
 // CIL[DOC-RESPONSIBILITY responsibility="Revoke active security_blocklist rows for the person's identifiers, lift the Supabase ban, and pull the IP out of the managed Netlify rule"]
 // CIL[DOC-CONTRACT inputs="ctx, body {person_id}" outputs="{ ok, revoked, layers }" errors="404 person not found" side_effects="blocklist updates, auth admin call, Netlify PUT, audit"]
 // CIL[DOC-MICRO logic_summary="Load person → revoke matching (type,value) rows → ban_duration 'none' → edge remove → audit security.user_unbanned" notable_decisions="account_id rows are intentionally left alone on unban — an org-level block is a separate decision"]
 // CIL[DOC-STABILITY stability="experimental"]
+// CIL[BEGIN stable_id="~/.framework/functions/security.ts:unbanUser:function" type="function" identity="unbanUser" parent="~/.framework/functions/security.ts"]
 async function unbanUser(ctx: RequestContext, body: any) {
   const { person_id } = body || {}
   if (!person_id) throw new Error('person_id is required')
@@ -353,13 +361,13 @@ async function unbanUser(ctx: RequestContext, body: any) {
 
   return { ok: true, person_id: person.id, layers }
 }
-// CIL[END stable_id="~/.framework/functions/security.ts:unbanuser:function"]
+// CIL[END stable_id="~/.framework/functions/security.ts:unbanUser:function"]
 
-// CIL[BEGIN stable_id="~/.framework/functions/security.ts:blocklistcrud:comment" type="comment" identity="blocklistCrud" parent="~/.framework/functions/security.ts"]
 // CIL[DOC-MACRO purpose="Blocklist list/add/revoke for the admin UI"]
 // CIL[DOC-RESPONSIBILITY responsibility="Expose the security_blocklist table to system admins; ip entries sync to the Netlify edge on add/revoke"]
 // CIL[DOC-MICRO logic_summary="list returns active+recent rows; add upserts (type,value,severity,reason,expires_at); revoke stamps revoked_at. Both edge-sync ip values" notable_decisions="[]"]
 // CIL[DOC-STABILITY stability="experimental"]
+// CIL[BEGIN stable_id="~/.framework/functions/security.ts:listBlocklist:function" type="function" identity="listBlocklist" parent="~/.framework/functions/security.ts"]
 async function listBlocklist() {
   const { data, error } = await adminDb
     .from('security_blocklist')
@@ -369,7 +377,9 @@ async function listBlocklist() {
   if (error) throw new Error('blocklist read failed: ' + error.message)
   return { rows: data || [] }
 }
+// CIL[END stable_id="~/.framework/functions/security.ts:listBlocklist:function"]
 
+// CIL[BEGIN stable_id="~/.framework/functions/security.ts:blocklistAdd:function" type="function" identity="blocklistAdd" parent="~/.framework/functions/security.ts"]
 async function blocklistAdd(ctx: RequestContext, body: any) {
   const { type, value, severity = 'hard', reason, expires_at } = body || {}
   if (!type || !value) throw new Error('type and value are required')
@@ -395,7 +405,9 @@ async function blocklistAdd(ctx: RequestContext, body: any) {
   })
   return { ok: true }
 }
+// CIL[END stable_id="~/.framework/functions/security.ts:blocklistAdd:function"]
 
+// CIL[BEGIN stable_id="~/.framework/functions/security.ts:blocklistRevoke:function" type="function" identity="blocklistRevoke" parent="~/.framework/functions/security.ts"]
 async function blocklistRevoke(ctx: RequestContext, body: any) {
   const { id, type, value } = body || {}
   if (!id && !(type && value)) throw new Error('id or (type, value) is required')
@@ -417,17 +429,18 @@ async function blocklistRevoke(ctx: RequestContext, body: any) {
   })
   return { ok: true, revoked: revoked?.length || 0 }
 }
-// CIL[END stable_id="~/.framework/functions/security.ts:blocklistcrud:comment"]
+// CIL[END stable_id="~/.framework/functions/security.ts:blocklistRevoke:function"]
 
-// CIL[BEGIN stable_id="~/.framework/functions/security.ts:handler:constant" type="constant" identity="handler" parent="~/.framework/functions/security.ts"]
 // CIL[DOC-MACRO purpose="Action dispatcher — system-admin only"]
 // CIL[DOC-RESPONSIBILITY responsibility="Route ?action= to the security operations; every action is gated by requireSystemContextWithAudit"]
 // CIL[DOC-CONTRACT inputs="ctx, body" outputs="action result JSON" errors="401/403 unauthenticated/non-admin; 400 unknown action" side_effects="delegated"]
 // CIL[DOC-MICRO logic_summary="Gate once, then switch on ctx.query.action || body.action" notable_decisions="[]"]
 // CIL[DOC-STABILITY stability="experimental"]
+// CIL[BEGIN stable_id="~/.framework/functions/security.ts:handler:constant" type="constant" identity="handler" parent="~/.framework/functions/security.ts"]
 export const handler = createHandler(async (ctx, body) => {
-  const deny = requireSystemContextWithAudit(ctx, 'security_admin')
-  if (deny) return deny
+  // Throws a statusCode-carrying error on denial; createHandler maps it to a
+  // real HTTP 401/403 (F-051).
+  requireSystemContextWithAudit(ctx, 'security_admin')
 
   const action = (ctx.query?.action as string) || (body?.action as string) || ''
   switch (action) {