@michaelthielemann/kestrel 3.0.1 → 4.0.1

package/scripts/port-graph.mjs

@@ -0,0 +1,350 @@
+#!/usr/bin/env node
+// Port-graph extraction (experiment): for every exported function in packages/kestrel-core/src whose
+// return type resolves to `Effect.Effect<A, E, R>`, the R (requirements) channel becomes that function's
+// port list. Every `Layer.succeed`/`Layer.effect`/`Layer.scoped` call becomes an adapter binding from the
+// layer's containing function to the port it provides. Nodes reuse graphify-out/graph.json's id scheme so
+// the two graphs join; a node not already present there is synthesized with the same scheme and flagged.
+//
+// The R channel alone cannot answer "does persist always follow validate" — this codebase passes the
+// database as a plain function parameter, not a Context.Tag requirement, so R is `never` on every step.
+// To make that invariant askable as a graph query at all, this script also extracts each `definePipeline`
+// call's literal `steps: [...]` array (resolving each step-factory call to the runtime step name registered
+// via `syncStep(name, ...)`) into an ordered step chain, and exposes `stepOrderRespectsInvariant` for
+// querying it.
+import ts from 'typescript'
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs'
+import { dirname, join, relative } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+
+const root = join(dirname(fileURLToPath(import.meta.url)), '..')
+const corePkg = join(root, 'packages/kestrel-core')
+const graphOutDir = join(root, 'graphify-out')
+
+// --- graph id scheme (mirrors graphify's own slugging, see graphify-out/graph.json) ---
+
+function slugFile(relFile) {
+  return relFile.replace(/\.[^/.]+$/, '').replace(/[^A-Za-z0-9]+/g, '_').toLowerCase()
+}
+
+function slugSymbol(name) {
+  return name.replace(/\(\)$/, '').toLowerCase().replace(/[^a-z0-9]/g, '')
+}
+
+function loadExistingGraph() {
+  const graphPath = join(graphOutDir, 'graph.json')
+  if (!existsSync(graphPath)) return { nodes: [], byFileAndLabel: new Map() }
+  const graph = JSON.parse(readFileSync(graphPath, 'utf8'))
+  const byFileAndLabel = new Map()
+  for (const n of graph.nodes) byFileAndLabel.set(`${n.source_file}::${n.label}`, n)
+  return { nodes: graph.nodes, byFileAndLabel }
+}
+
+/** Reuses the existing graph's node id for (relFile, name) when present; otherwise synthesizes one with
+ *  the same scheme and marks it so a future graphify run can be checked against it. */
+function nodeIdFor(existing, relFile, name) {
+  const found = existing.byFileAndLabel.get(`${relFile}::${name}()`)
+  if (found) return { id: found.id, synthesized: false }
+  return { id: `${slugFile(relFile)}_${slugSymbol(name)}`, synthesized: true }
+}
+
+function loadProgram() {
+  const tsconfigPath = join(corePkg, 'tsconfig.json')
+  const configFile = ts.readConfigFile(tsconfigPath, ts.sys.readFile)
+  const parsed = ts.parseJsonConfigFileContent(configFile.config, ts.sys, corePkg)
+  const fileNames = parsed.fileNames.filter((f) => !/\.test\.ts$/.test(f) && !f.includes(`${corePkg}/test/`))
+  const program = ts.createProgram(fileNames, { ...parsed.options, noEmit: true })
+  return { program, fileNames }
+}
+
+function hasExportModifier(node) {
+  return (ts.getCombinedModifierFlags(node) & ts.ModifierFlags.Export) !== 0
+}
+
+function isEffectReturnType(type) {
+  const target = type.aliasSymbol ?? type.target?.symbol ?? type.symbol
+  return target?.name === 'Effect' && !!(type).typeArguments
+}
+
+/** Flattens a union of `Context.Tag`-shaped types (or a bare one) into distinct display names, dropping
+ *  `never` (the honest "no requirements" answer, not an omission). */
+function portNamesFromRType(checker, rType) {
+  if (!rType) return []
+  const parts = rType.isUnion?.() ? rType.types : [rType]
+  const names = new Set()
+  for (const t of parts) {
+    const text = checker.typeToString(t)
+    if (text === 'never' || text === 'unknown') continue
+    names.add(text)
+  }
+  return [...names]
+}
+
+/** Visits every exported function-like declaration (function declarations and `export const f = (...) =>`)
+ *  in a source file, at the top level and one level of nesting (namespaces are not used in this codebase). */
+function* exportedFunctions(sf) {
+  for (const stmt of sf.statements) {
+    if (ts.isFunctionDeclaration(stmt) && hasExportModifier(stmt) && stmt.name) {
+      yield { name: stmt.name.text, decl: stmt }
+    } else if (ts.isVariableStatement(stmt) && hasExportModifier(stmt)) {
+      for (const d of stmt.declarationList.declarations) {
+        if (ts.isIdentifier(d.name) && d.initializer && (ts.isArrowFunction(d.initializer) || ts.isFunctionExpression(d.initializer))) {
+          yield { name: d.name.text, decl: d.initializer }
+        }
+      }
+    }
+  }
+}
+
+function extractFunctionPorts(program, existing) {
+  const checker = program.getTypeChecker()
+  const functions = []
+  let scanned = 0
+  for (const sf of program.getSourceFiles()) {
+    if (!sf.fileName.startsWith(corePkg) || sf.fileName.includes('/node_modules/')) continue
+    const relFile = relative(root, sf.fileName)
+    for (const { name, decl } of exportedFunctions(sf)) {
+      scanned++
+      const sig = checker.getSignatureFromDeclaration(decl)
+      if (!sig) continue
+      const returnType = checker.getReturnTypeOfSignature(sig)
+      if (!isEffectReturnType(returnType)) continue
+      const typeArgs = checker.getTypeArguments(returnType)
+      const rType = typeArgs[2]
+      const ports = portNamesFromRType(checker, rType)
+      const { id, synthesized } = nodeIdFor(existing, relFile, name)
+      functions.push({ id, name, file: relFile, ports, synthesized })
+    }
+  }
+  return { functions, scanned }
+}
+
+function containingFunctionName(node) {
+  let cur = node.parent
+  while (cur) {
+    if ((ts.isFunctionDeclaration(cur) || ts.isFunctionExpression(cur) || ts.isArrowFunction(cur)) ) {
+      if (ts.isFunctionDeclaration(cur) && cur.name) return cur.name.text
+      if (ts.isVariableDeclaration(cur.parent) && ts.isIdentifier(cur.parent.name)) return cur.parent.name.text
+    }
+    cur = cur.parent
+  }
+  return null
+}
+
+/** Resolves a `Context.GenericTag<X>(...)` (or `Context.Tag<X, ...>`) expression, following one level of
+ *  identifier indirection, to the service type name `X`. */
+function resolveTagTypeName(checker, expr) {
+  let target = expr
+  if (ts.isIdentifier(expr)) {
+    const sym = checker.getSymbolAtLocation(expr)
+    const decl = sym?.valueDeclaration
+    if (decl && ts.isVariableDeclaration(decl) && decl.initializer) target = decl.initializer
+  }
+  if (ts.isCallExpression(target) && target.typeArguments?.length) {
+    return target.typeArguments[0].getText()
+  }
+  return null
+}
+
+const LAYER_CONSTRUCTORS = new Set(['succeed', 'effect', 'scoped', 'sync'])
+
+function extractLayerBindings(program, existing) {
+  const checker = program.getTypeChecker()
+  const bindings = []
+  for (const sf of program.getSourceFiles()) {
+    if (!sf.fileName.startsWith(corePkg) || sf.fileName.includes('/node_modules/')) continue
+    const relFile = relative(root, sf.fileName)
+    const visit = (node) => {
+      if (
+        ts.isCallExpression(node)
+        && ts.isPropertyAccessExpression(node.expression)
+        && ts.isIdentifier(node.expression.expression)
+        && node.expression.expression.text === 'Layer'
+        && LAYER_CONSTRUCTORS.has(node.expression.name.text)
+        && node.arguments.length > 0
+      ) {
+        const tagName = resolveTagTypeName(checker, node.arguments[0])
+        if (tagName) {
+          const fnName = containingFunctionName(node) ?? '<module scope>'
+          const { id, synthesized } = nodeIdFor(existing, relFile, fnName)
+          bindings.push({
+            layerFnId: id,
+            layerFnName: fnName,
+            file: relFile,
+            line: sf.getLineAndCharacterOfPosition(node.getStart()).line + 1,
+            constructor: node.expression.name.text,
+            port: tagName,
+            synthesized,
+          })
+        }
+      }
+      ts.forEachChild(node, visit)
+    }
+    visit(sf)
+  }
+  return bindings
+}
+
+// --- Pipeline step-order extraction (makes the validate-before-persist invariant askable as a graph query) ---
+
+/** Maps every step-factory function name (e.g. `validateCreateStep`) to the runtime step name it registers
+ *  via `syncStep('<name>', ...)` / `asyncStep('<name>', ...)`. A factory with more than one such call inside
+ *  keeps only the first — every factory in this codebase registers exactly one step. */
+function buildStepNameMap(program) {
+  const map = new Map()
+  for (const sf of program.getSourceFiles()) {
+    if (!sf.fileName.includes('/pipeline/steps/') || sf.fileName.includes('/node_modules/')) continue
+    for (const { name, decl } of exportedFunctions(sf)) {
+      let stepName = null
+      const visit = (node) => {
+        if (stepName) return
+        if (
+          ts.isCallExpression(node)
+          && ts.isIdentifier(node.expression)
+          && (node.expression.text === 'syncStep' || node.expression.text === 'asyncStep')
+          && node.arguments[0] && ts.isStringLiteral(node.arguments[0])
+        ) {
+          stepName = node.arguments[0].text
+          return
+        }
+        ts.forEachChild(node, visit)
+      }
+      visit(decl)
+      if (stepName) map.set(name, stepName)
+    }
+  }
+  return map
+}
+
+function extractPipelineStepChains(program) {
+  const stepNameMap = buildStepNameMap(program)
+  const pipelines = []
+  for (const sf of program.getSourceFiles()) {
+    if (!sf.fileName.startsWith(corePkg) || sf.fileName.includes('/node_modules/')) continue
+    const relFile = relative(root, sf.fileName)
+    const visit = (node) => {
+      if (
+        ts.isCallExpression(node)
+        && ts.isIdentifier(node.expression)
+        && node.expression.text === 'definePipeline'
+        && node.arguments[0] && ts.isObjectLiteralExpression(node.arguments[0])
+      ) {
+        const obj = node.arguments[0]
+        const nameProp = obj.properties.find((p) => ts.isPropertyAssignment(p) && ts.isIdentifier(p.name) && p.name.text === 'name')
+        const stepsProp = obj.properties.find((p) => ts.isPropertyAssignment(p) && ts.isIdentifier(p.name) && p.name.text === 'steps')
+        if (nameProp && ts.isStringLiteral(nameProp.initializer) && stepsProp && ts.isArrayLiteralExpression(stepsProp.initializer)) {
+          const steps = []
+          for (const el of stepsProp.initializer.elements) {
+            // `steps: deleteSteps` (an identifier referring to a separately declared array) is skipped —
+            // rollback/duplicate/delete are not in VALIDATING_WRITE_OPS, so the invariant query never needs it.
+            if (ts.isCallExpression(el) && ts.isIdentifier(el.expression)) {
+              const factoryName = el.expression.text
+              steps.push(stepNameMap.get(factoryName) ?? factoryName)
+            } else if (ts.isCallExpression(el) && ts.isPropertyAccessExpression(el.expression)) {
+              steps.push(el.expression.name.text)
+            }
+          }
+          pipelines.push({ name: nameProp.initializer.text, file: relFile, line: sf.getLineAndCharacterOfPosition(node.getStart()).line + 1, steps })
+        }
+      }
+      ts.forEachChild(node, visit)
+    }
+    visit(sf)
+  }
+  return pipelines
+}
+
+/** The validate-before-persist invariant, as a pure query over an ordered step-name chain: `validate` must occur, `persist`
+ *  must occur, and `validate` must precede `persist`. Mirrors test/architecture/pipeline-invariants.test.ts'
+ *  registry-based check, but over the statically extracted `definePipeline` step array instead of a
+ *  runtime-composed `PipelineDescriptor`. */
+export function stepOrderRespectsInvariant(stepNames) {
+  const validateAt = stepNames.indexOf('validate')
+  const persistAt = stepNames.indexOf('persist')
+  if (validateAt < 0 || persistAt < 0) return false
+  return validateAt < persistAt
+}
+
+export const VALIDATING_WRITE_OPS = new Set(['createOne', 'createMany', 'updateOne', 'updateMany'])
+
+export function extractPortGraph() {
+  const { program } = loadProgram()
+  const existing = loadExistingGraph()
+  const { functions, scanned } = extractFunctionPorts(program, existing)
+  const bindings = extractLayerBindings(program, existing)
+  const pipelines = extractPipelineStepChains(program)
+  return { functions, scanned, bindings, pipelines }
+}
+
+function buildEmittedGraph({ functions, bindings, pipelines }) {
+  const nodes = []
+  const links = []
+  const seenNodes = new Set()
+  const addNode = (node) => {
+    if (seenNodes.has(node.id)) return
+    seenNodes.add(node.id)
+    nodes.push(node)
+  }
+
+  for (const fn of functions) {
+    addNode({ id: fn.id, label: `${fn.name}()`, kind: 'function', source_file: fn.file, synthesized: fn.synthesized })
+    for (const port of fn.ports) {
+      const portId = `port_${slugSymbol(port)}`
+      addNode({ id: portId, label: port, kind: 'port' })
+      links.push({ relation: 'requires', source: fn.id, target: portId, source_file: fn.file })
+    }
+  }
+
+  for (const b of bindings) {
+    addNode({ id: b.layerFnId, label: `${b.layerFnName}()`, kind: 'function', source_file: b.file, synthesized: b.synthesized })
+    const portId = `port_${slugSymbol(b.port)}`
+    addNode({ id: portId, label: b.port, kind: 'port' })
+    links.push({ relation: 'provides', source: b.layerFnId, target: portId, source_file: b.file, source_location: `L${b.line}`, layer_constructor: b.constructor })
+  }
+
+  for (const [i, p] of pipelines.entries()) {
+    const pipelineId = `pipeline_${slugFile(p.file)}_${slugSymbol(p.name)}_${i}`
+    addNode({ id: pipelineId, label: `${p.name} (pipeline)`, kind: 'pipeline', source_file: p.file, source_location: `L${p.line}` })
+    p.steps.forEach((stepName, order) => {
+      const stepId = `pipeline_step_${slugSymbol(stepName)}`
+      addNode({ id: stepId, label: stepName, kind: 'pipeline_step' })
+      links.push({ relation: 'pipeline_step', source: pipelineId, target: stepId, order, source_file: p.file })
+    })
+  }
+
+  return { nodes, links }
+}
+
+function main() {
+  const { functions, scanned, bindings, pipelines } = extractPortGraph()
+  const nonEmpty = functions.filter((f) => f.ports.length > 0)
+  const totalPorts = new Set(functions.flatMap((f) => f.ports)).size
+
+  const emitted = buildEmittedGraph({ functions, bindings, pipelines })
+  const reportDir = join(root, 'reports/graph')
+  mkdirSync(reportDir, { recursive: true })
+  const outPath = join(reportDir, 'port-graph.json')
+  writeFileSync(outPath, JSON.stringify({ generated_at: new Date().toISOString(), nodes: emitted.nodes, links: emitted.links }, null, 2))
+
+  console.log(`port-graph: scanned ${scanned} exported functions in packages/kestrel-core/src`)
+  console.log(`port-graph: ${functions.length} have an Effect.Effect<A, E, R> return type`)
+  console.log(`port-graph: ${nonEmpty.length} have a non-empty (non-never) R channel; ${totalPorts} distinct ports found`)
+  console.log(`port-graph: ${bindings.length} Layer composition(s) -> adapter binding(s) found`)
+  console.log(`port-graph: ${pipelines.length} definePipeline() call(s) with a literal steps array extracted`)
+  console.log(`port-graph: wrote ${emitted.nodes.length} nodes, ${emitted.links.length} links to ${relative(root, outPath)}`)
+
+  if (nonEmpty.length === 0) {
+    console.log('port-graph: honest finding — every scanned function has R = never (DB/services are plain')
+    console.log('port-graph: parameters here, not Context.Tag requirements), so the R-channel port list is')
+    console.log('port-graph: empty by construction. The pipeline_step chains above make the validate-before-persist')
+    console.log('port-graph: invariant askable as a graph query at all; see test/architecture/port-graph-cross-check.test.ts.')
+  }
+
+  for (const p of pipelines) {
+    if (!VALIDATING_WRITE_OPS.has(p.name)) continue
+    const ok = stepOrderRespectsInvariant(p.steps)
+    console.log(`port-graph: pipeline "${p.name}" (${p.file}:L${p.line}) validate-before-persist = ${ok}`)
+  }
+}
+
+const isMain = process.argv[1] && pathToFileURL(process.argv[1]).href === import.meta.url
+if (isMain) main()

package/scripts/typecheck.mjs

@@ -44,6 +44,17 @@ pass('server (Nitro) project', 'tsc', ['--noEmit', '-p', gateConfig])
 // 3. App / `.vue` / modules / config — vue-tsc via `nuxt typecheck` (needs the committed root tsconfig.json).
 pass('app + .vue (vue-tsc)', 'nuxt', ['typecheck'])
 
+// 4. Standalone workspace packages have their own tsconfig, outside the playground project. Globbed by
+// pnpm's own filter (topological order, every current and future `@michaelthielemann/kestrel-*` package, `create-kestrel`
+// excluded by name) rather than a hand-written list per package — the class of drift a hand list invites
+// (a package silently missing from this one script) is the exact failure mode this rail exists to avoid.
+console.log('› typechecking packages (@michaelthielemann/kestrel-*)…')
+try {
+  execFileSync('pnpm', ['--filter', '@michaelthielemann/kestrel-*', '-r', 'typecheck'], { cwd: root, stdio: 'inherit', env })
+} catch {
+  failed.push('packages (@michaelthielemann/kestrel-*)')
+}
+
 if (failed.length) {
   console.error(`\n✗ typecheck failed: ${failed.join(', ')}`)
   process.exit(1)

package/templates/starter/app/blocks/Prose.vue

@@ -8,6 +8,6 @@ defineBlock({ label: { en: 'Prose' }, icon: 'file-text' })
 
 <template>
   <!-- richtext is sanitized server-side on write -->
-  <!-- eslint-disable-next-line vue/no-v-html -- sanitized via sanitizeRichtext (sanitize-html allowlist) in layers/fields/server/field-registry/index.ts -->
+  <!-- eslint-disable-next-line vue/no-v-html -- sanitized via sanitizeRichtext (sanitize-html allowlist) in packages/kestrel-fields/src/server/field-registry/index.ts -->
   <div class="block-prose" v-html="body" />
 </template>

package/layers/access/server/utils/csrf.ts

@@ -1,39 +0,0 @@
-export interface CsrfHeaders {
-  secFetchSite?: string | null
-  origin?: string | null
-  referer?: string | null
-  host?: string | null
-}
-
-function hostOf(url: string | null | undefined): string | null {
-  if (!url) return null
-  try {
-    return new URL(url).host
-  } catch {
-    return null
-  }
-}
-
-export function isCrossSiteWrite(h: CsrfHeaders): boolean {
-  if (h.secFetchSite) {
-    return !(h.secFetchSite === 'same-origin' || h.secFetchSite === 'none')
-  }
-  // hostOf() lowercases per the URL spec; the raw Host header does not, so normalize both
-  // sides — host comparison is case-insensitive (RFC 3986).
-  const host = (h.host ?? '').toLowerCase()
-  // The literal opaque origin `null` (a browser signal from a sandboxed iframe, a data: URL, or some
-  // redirect chains) is unparseable by new URL, so it must NOT fall through to the all-absent "allow"
-  // path — per spec it is cross-origin. Treat it as cross-site.
-  if (h.origin === 'null') return true
-  const originHost = hostOf(h.origin)
-  if (originHost !== null) return originHost !== host
-  const refererHost = hostOf(h.referer)
-  if (refererHost !== null) return refererHost !== host
-  // A write carrying NONE of Sec-Fetch-Site / Origin / Referer is treated as same-site (allowed). A
-  // browser ALWAYS attaches Origin and/or Sec-Fetch-Site to a cross-origin state-changing request, so
-  // the all-absent case can only come from a NON-browser client (the test harness, a server-to-server
-  // import, automation) — which carries no ambient cookies and therefore cannot mount CSRF. The real
-  // defenses are SameSite=Strict on the session cookie + the Origin/Referer checks above; failing closed
-  // here adds no protection and breaks legitimate authenticated API clients.
-  return false
-}

package/layers/access/server/utils/grant-registry.ts

@@ -1,36 +0,0 @@
-import type { Grant, Role } from './policy'
-
-// A process-singleton registry of EXTRA authorization grants, contributed by layers/extensions at boot
-// (server plugin) on top of the hardcoded `POLICY`. This is the seam that lets an opt-in layer deliberately
-// open a narrow hole in the default-deny guard — e.g. the proofing extension granting `anonymous → write →
-// proofing` for its public back-channel. Inert until something registers: with an empty registry the guard
-// behaves exactly as the hardcoded policy. The map is INJECTED into the (pure) guard, not read from inside
-// it (symmetric with `publicResources`), so the policy stays deterministically node-testable. Foundation
-// for a future configurable Users & Roles system.
-const registered: Partial<Record<Role, Grant[]>> = {}
-
-/** Add an extra grant for a role. Deliberate + explicit — it widens what that role may do. */
-export function registerAccessGrant(role: Role, grant: Grant): void {
-  // Defense-in-depth: the public (anonymous) must never be handed a wildcard or draft-read through this
-  // seam — a legitimate public back-channel always names ONE specific resource and reads published-only.
-  // CRUCIAL: the evaluator (`resolveAccess`) defaults an OMITTED read scope to 'all' via `(scope ?? 'all')`,
-  // so an unscoped anonymous read would silently resolve to draft-read. The validator must use the SAME
-  // default, or a "safe"-looking `{action:'read', resource:'x'}` grant leaks drafts to anonymous visitors.
-  // (Write grants carry no read scope — `resolveAccess` only upgrades readScope for read grants — so an
-  // omitted scope on a write is fine, e.g. the proofing back-channel's anonymous write.)
-  const anonymousDraftRead = role === 'anonymous' && grant.action === 'read' && (grant.scope ?? 'all') === 'all'
-  if (role === 'anonymous' && (grant.resource === '*' || anonymousDraftRead)) {
-    throw new Error(`refusing an over-broad anonymous grant (${grant.action} ${grant.resource}${grant.scope ? ` scope=${grant.scope}` : ''}): name a specific resource and grant read with an explicit scope: 'published' (never draft-read)`)
-  }
-  (registered[role] ??= []).push(grant)
-}
-
-/** The full role → extra-grants map, for the guard to consult alongside `POLICY`. */
-export function registeredGrants(): Readonly<Partial<Record<Role, Grant[]>>> {
-  return registered
-}
-
-/** Test helper: drop all registered grants (the registry is a module singleton). */
-export function clearAccessGrants(): void {
-  for (const role of Object.keys(registered) as Role[]) Reflect.deleteProperty(registered, role)
-}

package/layers/access/server/utils/guard.ts

@@ -1,44 +0,0 @@
-import { isCrossSiteWrite, type CsrfHeaders } from './csrf'
-import { verifySession } from '../../../auth/server/utils/session'
-import { resolveAccess, actionForMethod, resourceForPath, isBootstrapPath, isPublicRenderPath, type Principal, type Grant, type Role } from './policy'
-
-export interface AccessInput {
-  method: string
-  path: string
-  csrf: CsrfHeaders
-  cookie: string | undefined
-  secret: string
-  nowMs: number
-  isPrerender: boolean
-}
-
-export type AccessDecision =
-  | { allow: true; principal: Principal; readScope: 'published' | 'all' }
-  | { allow: false; status: number; message: string }
-
-export function derivePrincipal(input: AccessInput): Principal {
-  if (input.isPrerender) return { userId: 'renderer', role: 'renderer' }
-  if (verifySession(input.secret, input.cookie, input.nowMs).valid) return { userId: 'admin', role: 'admin' }
-  return { userId: null, role: 'anonymous' }
-}
-
-export function evaluateAccess(input: AccessInput, publicResources: readonly string[] = [], registeredGrants: Readonly<Partial<Record<Role, Grant[]>>> = {}): AccessDecision {
-  // CSRF first: every unsafe method (incl. login) must be same-site.
-  if (actionForMethod(input.method) === 'write' && isCrossSiteWrite(input.csrf)) {
-    return { allow: false, status: 403, message: 'Cross-origin write rejected' }
-  }
-  const principal = derivePrincipal(input)
-  // Auth bootstrap (login/session) is always permitted so the SPA can authenticate. Scope still follows
-  // the principal (mirrors isPublicRenderPath below) — an anonymous caller never gets draft-read scope.
-  if (isBootstrapPath(input.method, input.path)) {
-    return { allow: true, principal, readScope: principal.role === 'anonymous' ? 'published' : 'all' }
-  }
-  // The public render entry is readable by everyone; the scope follows the principal so an admin can
-  // preview drafts while anonymous (and the static render) stay published-only.
-  if (isPublicRenderPath(input.method, input.path)) {
-    return { allow: true, principal, readScope: principal.role === 'anonymous' ? 'published' : 'all' }
-  }
-  const { allowed, readScope } = resolveAccess(principal, actionForMethod(input.method), resourceForPath(input.path), publicResources, registeredGrants[principal.role] ?? [])
-  if (!allowed) return { allow: false, status: 401, message: 'Authentication required' }
-  return { allow: true, principal, readScope }
-}

package/layers/access/server/utils/ip-allowlist.ts

@@ -1,79 +0,0 @@
-export type AllowlistMode = 'enforce' | 'log' | 'off'
-
-/** A parsed IPv4 CIDR as `network base & mask`, both uint32. */
-export interface Cidr {
-  base: number
-  mask: number
-}
-
-/**
- * Resolve the gate mode from `KESTREL_IP_ALLOWLIST_MODE` given the raw list.
- *
- * An empty list means there is nothing to enforce → `off`. When a list IS present, an unset/unknown mode
- * defaults to `enforce`: a configured allow-list that silently let everyone through is the exact legacy
- * footgun we are replacing. `log` is the opt-in calibration mode (observe, never block) used to confirm the
- * resolved client IP + `KESTREL_TRUST_PROXY` depth before enforcing.
- */
-export function allowlistMode(modeRaw: string | undefined, listRaw: string | undefined): AllowlistMode {
-  if (!listRaw || !listRaw.trim()) return 'off'
-  const m = (modeRaw ?? '').trim().toLowerCase()
-  if (m === 'off' || m === 'disabled' || m === 'false') return 'off'
-  if (m === 'log' || m === 'log-only' || m === 'dry-run') return 'log'
-  return 'enforce'
-}
-
-/** `1.2.3.4` / `::ffff:1.2.3.4` → uint32; `null` for out-of-range, real IPv6, or non-IPv4 input. */
-export function ipv4ToInt(ip: string): number | null {
-  let s = ip.trim()
-  const mapped = /^::ffff:(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/i.exec(s)
-  if (mapped) s = mapped[1]!
-  const m = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(s)
-  if (!m) return null
-  let n = 0
-  for (let i = 1; i <= 4; i++) {
-    const octet = Number(m[i])
-    if (octet > 255) return null
-    n = n * 256 + octet
-  }
-  return n >>> 0
-}
-
-function parseCidr(token: string): Cidr | null {
-  const slash = token.indexOf('/')
-  const base = ipv4ToInt(slash === -1 ? token : token.slice(0, slash))
-  if (base === null) return null
-  // `Number()` alone would widen a malformed prefix into a mask: '' → 0 → 0.0.0.0/0, and '0x10'/'1e1' → 16/10.
-  const bitsRaw = slash === -1 ? '32' : token.slice(slash + 1).trim()
-  if (!/^\d+$/.test(bitsRaw)) return null
-  const bits = Number(bitsRaw)
-  if (!Number.isInteger(bits) || bits < 0 || bits > 32) return null
-  const mask = bits === 0 ? 0 : (0xffffffff << (32 - bits)) >>> 0
-  return { base: (base & mask) >>> 0, mask }
-}
-
-/**
- * Parse the allow-list env into CIDRs, tolerant of the legacy nginx block so it can be pasted verbatim:
- * newline/comma/semicolon separated, `# comments` and a leading `allow`/`set_real_ip_from` keyword stripped.
- * Invalid tokens are dropped, not thrown — one bad line must not disable the whole gate. `onReject`, when
- * given, is called with each dropped token (this parser is IPv4-only, so an IPv6 CIDR pasted into an
- * otherwise-valid list is silently a no-op unless the caller surfaces it).
- */
-export function parseAllowlist(raw: string | undefined, onReject?: (token: string) => void): Cidr[] {
-  if (!raw) return []
-  const out: Cidr[] = []
-  for (const part of raw.split(/[\n,;]+/)) {
-    const token = part.replace(/#.*$/, '').trim().replace(/^(?:allow|set_real_ip_from)\s+/i, '').trim()
-    if (!token) continue
-    const cidr = parseCidr(token)
-    if (cidr) out.push(cidr)
-    else onReject?.(token)
-  }
-  return out
-}
-
-/** True when `ip` falls in any CIDR. Fails closed: a non-IPv4 address or empty list never matches. */
-export function ipAllowed(ip: string, cidrs: Cidr[]): boolean {
-  const n = ipv4ToInt(ip)
-  if (n === null) return false
-  return cidrs.some((c) => ((n & c.mask) >>> 0) === c.base)
-}