spexcode 0.4.1 → 0.5.0

package/spec-cli/src/doctor.ts

@@ -1,19 +1,17 @@
-// @@@ spex doctor - the DIAGNOSIS surface ([[doctor]]; command renamed from `self`, which misread as the
-// tool itself / the global install). When a user launches their OWN claude/codex with no SpexCode process
-// in the launch, the workflow reaches that agent only through the files materialize() writes (the manifest
-// in the global store; the in-tree contract blocks + hook shims + codex trust). Bare `spex doctor` answers
-// "is this agent actually governed, or silently running free?" — diagnosing that materialized contract per
-// LAYER, looping the same HARNESSES adapter materialize delivers through (so claude AND codex are covered
-// with no hardcoded paths). It catches the SILENT failure: a shim whose handler is missing, a PATH that
-// can't resolve `spex`, a contract that never landed. Read-only today: the bare report, `contract` (print
-// the surface:system text any agent reads), `conflicts`. install/uninstall are STAGED (noteStaged).
+// @@@ spex doctor - the opt-in, read-only project DIAGNOSIS surface ([[doctor]]). Bare doctor composes
+// spec-health findings with the delivery audit: when a user launches their OWN agent with no SpexCode
+// process in the launch, the workflow reaches it only through the files materialize() writes. The audit
+// loops the same HARNESSES adapter materialize uses and catches missing delivery or duplicate discovery.
+// `--contract` and `--conflicts` remain focused representations of that same diagnosis.
 import { existsSync, readFileSync, readdirSync, accessSync, constants } from 'node:fs'
 import { join, dirname, basename } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { execFileSync } from 'node:child_process'
 import { homedir } from 'node:os'
-import { loadSystemConfig, loadSkillConfig } from './specs.js'
-import { runtimeRoot, treeSlotDir, envSessionId, readAliasedRawRecord, mainCheckout } from './layout.js'
+import { loadSystemConfig, loadSkillConfig, loadSpecs } from './specs.js'
+import { runtimeRoot, treeSlotDir, envSessionId, readAliasedRawRecord, mainCheckout, readJsonConfig } from './layout.js'
+import { loadConfig } from './lint.js'
+import { trackedSourceFiles } from './source-files.js'
 
 // this file lives at <pkgRoot>/src/self.ts, so `..` is the package root — the same derivation init.ts/
 // materialize.ts use (never a hardcoded repo path), so the git-hook template lookup survives a relocated install.
@@ -31,6 +29,156 @@ function commonHooksDir(dir: string): string | null {
 }
 const read = (f: string): string => { try { return readFileSync(f, 'utf8') } catch { return '' } }
 
+type AltitudeConfig = {
+  lineBudget: number
+  charBudget: number
+  sizeable: number
+  dense: number
+  steps: number
+  identifierExtensions: string[]
+}
+
+type BreadthConfig = {
+  maxChildren: number
+}
+
+export type HealthFinding = {
+  check: string
+  spec: string
+  summary: string
+  evidence: string[]
+  repair: string
+}
+
+const DEFAULT_ALTITUDE: AltitudeConfig = {
+  lineBudget: 50,
+  charBudget: 4200,
+  sizeable: 35,
+  dense: 1.3,
+  steps: 3,
+  identifierExtensions: [],
+}
+
+const DEFAULT_BREADTH: BreadthConfig = {
+  maxChildren: 8,
+}
+
+function loadAltitudeConfig(root: string): AltitudeConfig {
+  const configured = readJsonConfig(join(root, 'spexcode.json'))?.doctor?.altitude ?? {}
+  const merged = { ...DEFAULT_ALTITUDE, ...configured }
+  return {
+    ...merged,
+    identifierExtensions: (merged.identifierExtensions ?? []).map((ext: string) => ext.replace(/^\.+/, '')),
+  }
+}
+
+function loadBreadthConfig(root: string): BreadthConfig {
+  const configured = readJsonConfig(join(root, 'spexcode.json'))?.doctor?.breadth ?? {}
+  return { ...DEFAULT_BREADTH, ...configured }
+}
+
+// Filename rows are lint coverage's exact tracked candidates. Compatibility extensions lower to wildcard
+// rows before the one identifier matcher is compiled.
+function identifierFilenameCandidates(sourceFiles: string[], compatibilityExtensions: string[]): string[] {
+  return [...new Set([
+    ...sourceFiles.map((path) => basename(path)),
+    ...compatibilityExtensions.map((ext) => `*.${ext}`),
+  ])]
+}
+
+function identRe(filenameCandidates: string[]): RegExp {
+  const escape = (value: string) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  const filenames = filenameCandidates
+    .map((candidate) => candidate.startsWith('*.')
+      ? `[\\w-]+\\.${escape(candidate.slice(2))}`
+      : escape(candidate))
+    .sort((a, b) => b.length - a.length)
+  const signals = [
+    '[a-z][A-Za-z0-9]*[A-Z][A-Za-z0-9]*',
+    '\\b[a-z]+_[a-z0-9_]+\\b',
+    '\\b\\w+\\(',
+    '`[^`]+`',
+    '\\/[\\w./-]+\\.\\w+',
+  ]
+  if (filenames.length) signals.push(`(?<![\\w./-])(?:${filenames.join('|')})(?![\\w.-])`)
+  return new RegExp(signals.join('|'), 'g')
+}
+
+const STEP_LINE = /^\s*(\d+[.)]\s|[-*]\s*(first|then|next|finally)\b)|(^|[,;]\s*)(first|then|next|finally),/i
+
+function altitudeEvidence(body: string, cfg: AltitudeConfig, ident: RegExp): string[] {
+  const lines = body.split('\n')
+  const nonBlank = lines.filter((line) => line.trim()).length
+  let inFence = false
+  let signals = 0
+  let steps = 0
+  for (const line of lines) {
+    if (/^\s*```/.test(line)) { inFence = !inFence; continue }
+    if (inFence || !line.trim()) continue
+    signals += line.match(ident)?.length ?? 0
+    if (STEP_LINE.test(line)) steps++
+  }
+  const density = signals / Math.max(1, nonBlank)
+  const evidence: string[] = []
+  if (nonBlank > cfg.lineBudget || body.length > cfg.charBudget)
+    evidence.push(`${nonBlank} non-blank lines / ${body.length} chars over budget (${cfg.lineBudget}/${cfg.charBudget})`)
+  if (nonBlank > cfg.sizeable && density > cfg.dense)
+    evidence.push(`code-identifier density ${density.toFixed(2)}/line over ${cfg.dense}`)
+  if (nonBlank > cfg.sizeable && steps >= cfg.steps)
+    evidence.push(`${steps} step-by-step how-to lines`)
+  return evidence
+}
+
+export async function specHealthDiagnosis(root: string): Promise<HealthFinding[]> {
+  const lint = loadConfig(root)
+  const altitude = loadAltitudeConfig(root)
+  const breadth = loadBreadthConfig(root)
+  const governed = trackedSourceFiles(root, lint.governedRoots, lint)
+  const ident = identRe(identifierFilenameCandidates(governed, altitude.identifierExtensions))
+  const specs = await loadSpecs(root)
+  const childCount = new Map<string, number>()
+  for (const spec of specs) if (spec.parent) childCount.set(spec.parent, (childCount.get(spec.parent) ?? 0) + 1)
+  const findings: HealthFinding[] = []
+  for (const spec of specs) {
+    const evidence = altitudeEvidence(spec.body, altitude, ident)
+    if (evidence.length) findings.push({
+      check: 'altitude',
+      spec: spec.id,
+      summary: 'body reads like mechanics rather than a contract',
+      evidence,
+      repair: `rewrite '${spec.id}' around observable intent and invariants; the tidy workflow can perform the semantic review`,
+    })
+    const children = childCount.get(spec.id) ?? 0
+    if (children >= breadth.maxChildren) findings.push({
+      check: 'breadth',
+      spec: spec.id,
+      summary: 'tree fan-out may be missing a natural grouping layer',
+      evidence: [`${children} direct child nodes (>= ${breadth.maxChildren})`],
+      repair: `review '${spec.id}' with the regroup workflow; group only along a real seam and leave genuine peers flat`,
+    })
+  }
+  return findings
+}
+
+function healthReport(findings: HealthFinding[], adopted: boolean): string[] {
+  const lines = ['Spec health diagnosis (opt-in advisory; never part of spex spec lint)']
+  if (!adopted) {
+    lines.push('  status          : unavailable — adopt the repository with `spex init`')
+    return lines
+  }
+  const checks = ['altitude', 'breadth', ...new Set(findings.map((finding) => finding.check).filter((check) => check !== 'altitude' && check !== 'breadth'))]
+  for (const check of checks) {
+    const rows = findings.filter((finding) => finding.check === check)
+    lines.push(`  ${check.padEnd(16)}: ${rows.length ? `${rows.length} finding(s)` : 'healthy'}`)
+    for (const finding of rows) {
+      lines.push(`    ${finding.spec.padEnd(16)}: ${finding.summary}`)
+      for (const evidence of finding.evidence) lines.push(`      evidence      : ${evidence}`)
+      lines.push(`      repair        : ${finding.repair}`)
+    }
+  }
+  return lines
+}
+
 // @@@ contractText - the layer-2 payload: the composed `surface:system` bodies, the SAME join materialize()
 // folds into each harness's contract file — so a BYOA agent reads byte-identical guidance.
 function contractText(): { names: string[]; body: string } {
@@ -170,9 +318,9 @@ async function doubleDeliveryReport(base: string): Promise<{ lines: string[]; co
   if (conflict) {
     L.push('Repair — SpexCode is reaching this agent through MORE THAN ONE discovery channel. Keep exactly one:')
     L.push('  • remove the independently-installed plugin bundle (delete its dir, or `claude plugin uninstall spexcode`); or')
-    L.push('  • if you WANT the plugin, stop the native delivery: set spexcode.json "harnesses" to a plugin target')
-    L.push('    (e.g. ["plugin",{"plugin":".claude"}] → {"plugin":".claude"}) so `spex materialize` prunes the loose shim/contract/skills; or')
-    L.push('  • remove the loose copy directly (`spex doctor uninstall` [staged] / `spex uninstall`).')
+    L.push('  • if you WANT the plugin, stop the native delivery: set spexcode.json to')
+    L.push('    `"harnesses": [{"plugin":".claude"}]`, then run `spex materialize` to prune the loose shim/contract/skills; or')
+    L.push('  • remove SpexCode\'s generated delivery with `spex uninstall`.')
   } else {
     L.push('No double-delivery: each harness is reached by at most one spexcode-stamped channel.')
   }
@@ -233,8 +381,14 @@ async function doctor(): Promise<number> {
     })
     line('issues workflow', `${issuesEnabled() ? 'ON' : 'OFF'} (spexcode.json issues.enabled)`)
     if (legacy.length) line('  LEGACY key', `\`proposals\` found in ${legacy.map((f) => join(cfgHome, f)).join(', ')} — no longer read; rename it to "issues": { "enabled": … }`)
+    const projectConfig = readJsonConfig(join(base, 'spexcode.json'))
+    if (Object.prototype.hasOwnProperty.call(projectConfig.lint ?? {}, 'maxChildren'))
+      line('RETIRED key', '`lint.maxChildren` is no longer read — move the value to `doctor.breadth.maxChildren`')
   }
 
+  const health = adopted ? await specHealthDiagnosis(base) : []
+  L.push('\n' + healthReport(health, adopted).join('\n'))
+
   // --- preconditions: nothing downstream fires without these ---
   L.push('\nPreconditions (without these nothing downstream fires)')
   for (const bin of ['spex', 'claude', 'codex']) {
@@ -347,37 +501,23 @@ async function conflicts(): Promise<number> {
   return conflict ? 1 : 0
 }
 
-
-// install/uninstall are STAGED: wiring layer-3 hooks into a standalone repo is only SAFE once the hooks
-// detect a missing managed session and degrade. So the diagnosis ships first; the installer lands behind it.
-function noteStaged(verb: string): number {
-  console.error(`spex doctor ${verb} is not available yet — it is staged behind the hook-degradation prerequisite
-(the live hooks must detect a missing managed session and degrade before they can be safely wired into your
-own agent's config). Meanwhile: \`spex doctor\` reports your coverage, and \`spex doctor --contract\` prints
-the workflow text you can hand any agent.`)
+function migrationRemoved(): number {
+  console.error('spex: `spex doctor --migrate` was removed in v0.4.0 — migrate this tree with a 0.3.x SpexCode release, then reinstall the current release. Nothing was changed.')
   return 2
 }
 
 function usage(): number {
-  console.error(`spex doctor — diagnose how the SpexCode workflow reaches your agent
-  (bare)         per-layer report: preconditions · git-hook floor · contract · hooks(+handlers) · backend · footprint
+  console.error(`spex doctor — diagnose spec health and how the SpexCode workflow reaches your agent
+  (bare)         spec-health findings + delivery report: preconditions · git-hook floor · contract · hooks(+handlers) · backend · footprint
   --contract     print the surface:system contract text (hand it to any agent)
-  --conflicts    detect double-delivery — the same agent reached via loose native delivery AND a plugin bundle (exits non-zero on conflict)
-  --migrate      one-shot 0.2.x → 0.3.0 vocabulary migration for an adopter repo (renames + hook-asset
-                 upgrade + body rewrites; refuses on a dirty tree / undrained sessions / an already-migrated
-                 tree; stages everything, commits nothing; removed in 0.4.0)
-  install        [staged] wire the materialized contract + hooks into your agent  (--agent claude, --minimal)
-  uninstall      [staged] reverse exactly what install wrote`)
+  --conflicts    detect double-delivery — the same agent reached via loose native delivery AND a plugin bundle (exits non-zero on conflict)`)
   return 0
 }
 
 export async function runDoctor(args: string[]): Promise<number> {
   // contract/conflicts are FLAGS, not subcommands ([[cli-surface]] §4: another representation of the same
   // diagnosis read, not a distinct action). The old positional spellings signpost — report, never run.
-  // --migrate is the one MUTATING flag: the term-limited 0.2.x→0.3.0 adopter migrator ([[migrate]],
-  // ships with 0.3.0, deleted in 0.4.0) — dispatched first so its refusal/summary is never diluted
-  // by the diagnosis report.
-  if (args.includes('--migrate')) return await (await import('./migrate.js')).runMigrate()
+  if (args.includes('--migrate')) return migrationRemoved()
   if (args.includes('--contract')) return contract()
   if (args.includes('--conflicts')) return await conflicts()
   switch (args[0]) {
@@ -385,8 +525,6 @@ export async function runDoctor(args: string[]): Promise<number> {
     case 'contract': case 'conflicts':
       console.error(`spex: \`spex doctor ${args[0]}\` was removed in v0.3.0 — use: spex doctor --${args[0]}`)
       return 2
-    case 'install': return noteStaged('install')
-    case 'uninstall': return noteStaged('uninstall')
     case 'help': case '--help': case '-h': return usage()
     default: console.error(`spex doctor: unknown subcommand "${args[0]}"`); usage(); return 2
   }

package/spec-cli/src/gateway-auth.ts

@@ -0,0 +1,194 @@
+// @@@ gateway auth - the ONE authorization mechanism of the multi-project gateway ([[gateway-hub]]).
+// Everything about passwords and visitors lives HERE, at the gateway: the project backends stay loopback
+// internal services that never see a credential, a cookie, or a visitor identity. Two signed scopes only:
+// an ADMIN session grants /projects (management) plus every /p/:projectId route; a PROJECT session grants
+// exactly its own /p/:projectId route. A project with no configured password is open; with no admin
+// password, loopback may manage implicitly while non-loopback /projects stays locked.
+//
+// Secrets discipline: password VERIFIERS (scrypt, salted) live only in the per-user private store
+// (~/.spexcode/gateway/auth.json, 0600) — never in a repo, never in a backend record, never plaintext.
+// Session tokens are HMAC-signed claims under a random per-user secret, so they survive a gateway restart
+// with no server-side session table, verified in constant time. Each verifier carries a random `gen` that
+// rotates on every set/clear and is embedded in the tokens it authenticates — changing or clearing a
+// password instantly invalidates every session it minted.
+import { createHmac, createHash, randomBytes, scryptSync, timingSafeEqual } from 'node:crypto'
+import { chmodSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { spexcodeHome } from './layout.js'
+
+export type Verifier = { algo: 'scrypt'; N: number; r: number; p: number; salt: string; hash: string; gen: string }
+export type AuthStore = { v: 1; secret: string; admin?: Verifier; projects: Record<string, Verifier> }
+export type Scope = { s: 'admin' } | { s: 'project'; p: string }
+export type Claims = { v: 1; s: 'admin' | 'project'; p?: string; g: string; t: number }
+export type Decision =
+  | { ok: true; via: 'admin' | 'project' | 'open' | 'loopback' }
+  | { ok: false; reason: 'admin-login' | 'locked' | 'project-login' }
+
+const TOKEN_TTL_MS = 30 * 24 * 3600 * 1000 // matches the single-project gateway's 30-day cookie
+const SCRYPT = { N: 16384, r: 8, p: 1 } as const
+
+// ---- the private per-user store --------------------------------------------------------------------
+
+export function authStorePath(): string {
+  return join(spexcodeHome(), 'gateway', 'auth.json')
+}
+
+// first load creates the store (and its random signing secret) so sessions survive restarts; the file is
+// 0600 in a 0700 dir — this is a per-USER secret store, no other principal has business reading it.
+export function loadAuthStore(): AuthStore {
+  try {
+    const raw = JSON.parse(readFileSync(authStorePath(), 'utf8'))
+    if (raw?.v === 1 && typeof raw.secret === 'string' && raw.secret) return { v: 1, secret: raw.secret, admin: raw.admin, projects: raw.projects ?? {} }
+  } catch { /* absent or unreadable → fresh below; malformed secrets must not be half-trusted */ }
+  const fresh: AuthStore = { v: 1, secret: randomBytes(32).toString('base64url'), projects: {} }
+  saveAuthStore(fresh)
+  return fresh
+}
+
+function saveAuthStore(store: AuthStore): void {
+  const file = authStorePath()
+  mkdirSync(dirname(file), { recursive: true, mode: 0o700 })
+  const tmp = `${file}.tmp`
+  writeFileSync(tmp, JSON.stringify(store, null, 2) + '\n', { mode: 0o600 })
+  renameSync(tmp, file)
+  chmodSync(file, 0o600) // rename preserves the tmp mode, but never let a pre-existing looser file win
+}
+
+// ---- password verifiers (scrypt, salted, constant-time) --------------------------------------------
+
+export function makeVerifier(password: string): Verifier {
+  const salt = randomBytes(16)
+  const hash = scryptSync(password, salt, 32, SCRYPT)
+  return { algo: 'scrypt', ...SCRYPT, salt: salt.toString('base64url'), hash: hash.toString('base64url'), gen: randomBytes(8).toString('base64url') }
+}
+
+export function verifyPassword(v: Verifier | undefined, password: string): boolean {
+  if (!v || v.algo !== 'scrypt' || typeof password !== 'string') return false
+  const got = scryptSync(password, Buffer.from(v.salt, 'base64url'), 32, { N: v.N, r: v.r, p: v.p })
+  return constEq(got, Buffer.from(v.hash, 'base64url'))
+}
+
+function constEq(a: Buffer | string, b: Buffer | string): boolean {
+  const ab = Buffer.isBuffer(a) ? a : Buffer.from(a)
+  const bb = Buffer.isBuffer(b) ? b : Buffer.from(b)
+  return ab.length === bb.length && timingSafeEqual(ab, bb)
+}
+
+// ---- verifier management (the gateway admin APIs write through these) ------------------------------
+
+export function setAdminPassword(password: string): AuthStore {
+  const store = loadAuthStore()
+  store.admin = makeVerifier(password)
+  saveAuthStore(store)
+  return store
+}
+export function clearAdminPassword(): AuthStore {
+  const store = loadAuthStore()
+  delete store.admin
+  saveAuthStore(store)
+  return store
+}
+export function setProjectPassword(projectId: string, password: string): AuthStore {
+  const store = loadAuthStore()
+  store.projects[projectId] = makeVerifier(password)
+  saveAuthStore(store)
+  return store
+}
+export function clearProjectPassword(projectId: string): AuthStore {
+  const store = loadAuthStore()
+  delete store.projects[projectId]
+  saveAuthStore(store)
+  return store
+}
+
+// ---- signed session tokens --------------------------------------------------------------------------
+
+function sign(secret: string, payload: string): string {
+  return createHmac('sha256', Buffer.from(secret, 'base64url')).update(payload).digest('base64url')
+}
+
+// a token exists only for a scope that has a verifier — its `g` claim is that verifier's current gen.
+export function mintToken(store: AuthStore, scope: Scope, nowMs = Date.now()): string {
+  const v = scope.s === 'admin' ? store.admin : store.projects[scope.p]
+  if (!v) throw new Error(`gateway-auth: cannot mint a ${scope.s} token with no verifier configured`)
+  const claims: Claims = { v: 1, s: scope.s, ...(scope.s === 'project' ? { p: scope.p } : {}), g: v.gen, t: nowMs }
+  const payload = Buffer.from(JSON.stringify(claims)).toString('base64url')
+  return `${payload}.${sign(store.secret, payload)}`
+}
+
+// full validity lives here: signature (constant-time), shape, expiry, and the gen check against the
+// CURRENT verifier — a cleared or re-set password leaves no valid tokens behind.
+export function verifyToken(store: AuthStore, token: string, nowMs = Date.now()): Claims | null {
+  const dot = token.indexOf('.')
+  if (dot <= 0) return null
+  const payload = token.slice(0, dot), sig = token.slice(dot + 1)
+  if (!constEq(sig, sign(store.secret, payload))) return null
+  let claims: Claims
+  try { claims = JSON.parse(Buffer.from(payload, 'base64url').toString('utf8')) } catch { return null }
+  if (claims?.v !== 1 || typeof claims.t !== 'number' || typeof claims.g !== 'string') return null
+  if (nowMs > claims.t + TOKEN_TTL_MS || claims.t > nowMs + 60_000) return null
+  if (claims.s === 'admin') return store.admin && constEq(claims.g, store.admin.gen) ? claims : null
+  if (claims.s === 'project' && typeof claims.p === 'string') {
+    const v = store.projects[claims.p]
+    return v && constEq(claims.g, v.gen) ? claims : null
+  }
+  return null
+}
+
+// ---- cookies ----------------------------------------------------------------------------------------
+// Cookie names are keyed by the gateway's public port (cookies are host-scoped; the port is the
+// discriminator — same rationale as the single-project gateway) and, for project scopes, by a hash of the
+// projectId (ids are path-derived and may hold non-token chars). The NAME is only a mailbox: authorization
+// always re-validates the token's own projectId claim against the requested route — never the cookie's
+// name, and never its Path attribute, both of which are client-controlled.
+
+export function adminCookieName(port: number): string { return `spex_admin_${port}` }
+export function projectCookieName(port: number, projectId: string): string {
+  return `spex_proj_${port}_${createHash('sha256').update(projectId).digest('hex').slice(0, 12)}`
+}
+
+export function cookieOf(header: string | undefined, name: string): string | null {
+  for (const part of (header ?? '').split(';')) {
+    const eq = part.indexOf('=')
+    if (eq > 0 && part.slice(0, eq).trim() === name) return decodeURIComponent(part.slice(eq + 1).trim())
+  }
+  return null
+}
+
+// ---- loopback ---------------------------------------------------------------------------------------
+// The implicit-admin decision reads the SOCKET's remote address only. Never a header (X-Forwarded-For,
+// X-Real-IP): headers are attacker-controlled, and this gateway is designed to face the internet directly,
+// not to sit behind a trusted proxy.
+export function isLoopback(addr: string | null | undefined): boolean {
+  if (!addr) return false
+  const a = addr.startsWith('::ffff:') ? addr.slice(7) : addr
+  return a === '::1' || /^127(\.\d{1,3}){3}$/.test(a)
+}
+
+// ---- the decision -----------------------------------------------------------------------------------
+
+export type Route = { kind: 'admin' } | { kind: 'project'; projectId: string }
+
+export function authorize(store: AuthStore, route: Route, cookieHeader: string | undefined, remoteAddr: string | null | undefined, port: number): Decision {
+  const adminTok = cookieOf(cookieHeader, adminCookieName(port))
+  const adminClaims = adminTok ? verifyToken(store, adminTok) : null
+  const adminOk = adminClaims?.s === 'admin'
+
+  if (route.kind === 'admin') {
+    if (adminOk) return { ok: true, via: 'admin' }
+    // no admin verifier configured: loopback manages implicitly (the bootstrap path — set the first
+    // password from the machine itself); anyone else finds /projects locked, not open.
+    if (!store.admin) return isLoopback(remoteAddr) ? { ok: true, via: 'loopback' } : { ok: false, reason: 'locked' }
+    return { ok: false, reason: 'admin-login' }
+  }
+
+  // project route — admin reaches every project; then the project's own gate decides.
+  if (adminOk) return { ok: true, via: 'admin' }
+  if (!store.projects[route.projectId]) return { ok: true, via: 'open' }
+  const tok = cookieOf(cookieHeader, projectCookieName(port, route.projectId))
+  const claims = tok ? verifyToken(store, tok) : null
+  // the projectId CLAIM must match the route — presenting project A's token under project B's cookie
+  // name (or any Path trick) authorizes nothing.
+  if (claims?.s === 'project' && claims.p === route.projectId) return { ok: true, via: 'project' }
+  return { ok: false, reason: 'project-login' }
+}