spexcode 0.6.2 → 0.6.5

package/spec-cli/src/execution-trace.ts

@@ -1,444 +0,0 @@
-import { execFileSync } from 'node:child_process'
-import { closeSync, openSync, readFileSync, readSync, readdirSync, statSync } from 'node:fs'
-import { homedir } from 'node:os'
-import { join } from 'node:path'
-
-export type ExecutionTurn = Readonly<{
-  token: string
-  acceptedAt: string
-}>
-export type ExecutionStepKind = 'command' | 'read' | 'write' | 'search' | 'tool'
-export type ExecutionStep = Readonly<{
-  id: string
-  kind: ExecutionStepKind
-  label: string
-  detail?: string
-  state: 'running' | 'done'
-}>
-export type ExecutionTrace = Readonly<{
-  revision: string
-  turnId: string | null
-  workingNote: string | null
-  steps: readonly ExecutionStep[]
-}>
-
-type TraceEvent =
-  | Readonly<{ type: 'boundary'; ids: readonly string[]; at: number | null }>
-  | Readonly<{ type: 'note'; text: string }>
-  | Readonly<{ type: 'call'; step: ExecutionStep }>
-  | Readonly<{ type: 'done'; id: string }>
-type CachedTrace = { size: number; remainder: Buffer; events: TraceEvent[] }
-type ApplyEvent = (value: unknown, ordinal: number) => readonly TraceEvent[]
-type ExportLoader = (threadId: string) => string
-
-const cache = new Map<string, CachedTrace>()
-const sessionJsonlPaths = new Map<string, string>()
-const localStoreCache = new Map<string, { revision: string; events: TraceEvent[] }>()
-
-const emptyTrace = (turn: ExecutionTurn | null, revision = '0'): ExecutionTrace => ({
-  revision: `${turn?.token ?? '0'}:${revision}`,
-  turnId: turn?.token ?? null,
-  workingNote: null,
-  steps: [],
-})
-
-const object = (value: unknown): Record<string, unknown> | null =>
-  value && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : null
-const items = (value: unknown): readonly unknown[] => Array.isArray(value) ? value : []
-const text = (value: unknown): string | null => typeof value === 'string' && value.trim() ? value.trim() : null
-const field = (value: Record<string, unknown>, ...names: string[]): string | null => {
-  for (const name of names) {
-    const found = text(value[name])
-    if (found) return found
-  }
-  return null
-}
-const children = (dir: string): string[] => { try { return readdirSync(dir).sort().reverse() } catch { return [] } }
-
-const sensitive = /(token|secret|password|authorization|bearer|cookie|credential|api[_-]?key|private[ _-]?key)/i
-const detailFields = [
-  ['cmd', 'cmd'], ['command', 'command'], ['path', 'path'], ['file_path', 'path'],
-  ['query', 'query'], ['pattern', 'pattern'], ['url', 'url'], ['workdir', 'in'],
-] as const
-
-function toolKind(name: string): ExecutionStepKind {
-  const normalized = name.toLowerCase()
-  if (/(search|browse|web)/.test(normalized)) return 'search'
-  if (/(read|list|find|grep|glob|stat)/.test(normalized)) return 'read'
-  if (/(write|edit|patch|create|delete|move|rename)/.test(normalized)) return 'write'
-  if (/(exec|shell|command|terminal|bash|npm|git)/.test(normalized)) return 'command'
-  return 'tool'
-}
-
-function toolLabel(name: string, kind: ExecutionStepKind): string {
-  const labels: Record<ExecutionStepKind, string> = {
-    command: 'Run command', read: 'Read files', write: 'Update files', search: 'Search', tool: 'Use tool',
-  }
-  return name.trim() || labels[kind]
-}
-
-function recordInput(value: unknown): Record<string, unknown> | null {
-  if (value && typeof value === 'object' && !Array.isArray(value)) return value as Record<string, unknown>
-  if (typeof value !== 'string') return null
-  try {
-    const parsed = JSON.parse(value)
-    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed as Record<string, unknown> : null
-  } catch { return null }
-}
-
-function sensitiveInput(value: unknown): boolean {
-  if (typeof value === 'string') return sensitive.test(value)
-  if (Array.isArray(value)) return value.some(sensitiveInput)
-  if (value && typeof value === 'object') return Object.entries(value as Record<string, unknown>)
-    .some(([key, entry]) => sensitive.test(key) || sensitiveInput(entry))
-  return false
-}
-
-function compactValue(key: string, value: string | number | boolean): string {
-  const compact = String(value).trim().replace(/\s+/g, ' ')
-  if (key === 'path' || key === 'file_path' || key === 'workdir') {
-    const parts = compact.replace(/\\/g, '/').split('/').filter(Boolean)
-    return parts.slice(-2).join('/') || compact
-  }
-  return compact.length > 96 ? `${compact.slice(0, 95)}...` : compact
-}
-
-function detailFromInput(value: unknown): string | undefined {
-  const input = recordInput(value)
-  if (!input || sensitiveInput(input)) return undefined
-  const details: string[] = []
-  for (const [key, title] of detailFields) {
-    const value = input[key]
-    if (typeof value !== 'string' && typeof value !== 'number' && typeof value !== 'boolean') continue
-    details.push(`${title}: ${compactValue(key, value)}`)
-    if (details.length === 2) break
-  }
-  const lineStart = input.line_start
-  const lineEnd = input.line_end
-  if (details.length < 2 && (typeof lineStart === 'number' || typeof lineEnd === 'number')) {
-    details.push(`lines: ${typeof lineStart === 'number' ? lineStart : 1}-${typeof lineEnd === 'number' ? lineEnd : lineStart}`)
-  }
-  return details.length ? details.join(' · ') : undefined
-}
-
-function displayableNote(value: unknown): string | null {
-  const note = text(value)?.replace(/\s+/g, ' ')
-  return note ? (note.length > 240 ? `${note.slice(0, 239)}...` : note) : null
-}
-
-function stepFromInput(id: string, name: string, input: unknown, state: ExecutionStep['state']): ExecutionStep {
-  const kind = toolKind(name)
-  const detail = detailFromInput(input)
-  return { id, kind, label: toolLabel(name, kind), ...(detail ? { detail } : {}), state }
-}
-
-function timestamp(value: unknown): number | null {
-  if (typeof value === 'number' && Number.isFinite(value)) return value
-  if (typeof value !== 'string' || !value.trim()) return null
-  const number = Number(value)
-  if (Number.isFinite(number)) return number
-  const parsed = Date.parse(value)
-  return Number.isFinite(parsed) ? parsed : null
-}
-
-function identities(...values: Array<Record<string, unknown> | null>): string[] {
-  const result = new Set<string>()
-  for (const value of values) for (const key of ['id', 'uuid', 'message_id', 'messageId', 'client_id', 'clientId', 'client_user_message_id', 'clientUserMessageId', 'promptId']) {
-    const id = field(value || {}, key)
-    if (id) result.add(id)
-  }
-  return [...result]
-}
-
-function at(value: Record<string, unknown>): number | null {
-  for (const key of ['timestamp', 'created_at', 'createdAt', 'created', 'time']) {
-    const found = timestamp(value[key])
-    if (found !== null) return found
-  }
-  return null
-}
-
-function isPrompt(content: unknown): boolean {
-  if (typeof content === 'string') return !!content.trim()
-  const blocks = items(content)
-  return blocks.some((block) => object(block)?.type !== 'tool_result')
-}
-
-function project(events: readonly TraceEvent[], sourceRevision: string, turn: ExecutionTurn | null): ExecutionTrace {
-  let start = -1
-  if (!turn) {
-    for (const [index, event] of events.entries()) if (event.type === 'boundary') start = index
-  } else {
-    const acceptedAt = timestamp(turn.acceptedAt)
-    const exact = events.flatMap((event, index) => event.type === 'boundary' && event.ids.includes(turn.token) ? [index] : [])
-    start = exact.length === 1 ? exact[0] : -1
-    if (start < 0 && exact.length === 0 && acceptedAt !== null) {
-      const candidates = events.flatMap((event, index) => event.type === 'boundary' && event.at !== null && event.at >= acceptedAt
-        ? [{ index, at: event.at }] : [])
-      const earliest = candidates.reduce<number | null>((value, candidate) => value === null || candidate.at < value ? candidate.at : value, null)
-      const matches = earliest === null ? [] : candidates.filter((candidate) => candidate.at === earliest)
-      if (matches.length === 1) start = matches[0].index
-    }
-  }
-  if (turn && start < 0) return emptyTrace(turn, sourceRevision)
-
-  let note: string | null = null
-  let steps: ExecutionStep[] = []
-  for (let index = start + 1; index < events.length; index++) {
-    const event = events[index]
-    if (event.type === 'boundary') return emptyTrace(turn, sourceRevision)
-    if (event.type === 'note') { note = event.text; steps = []; continue }
-    if (event.type === 'call') {
-      if (note) steps.push(event.step)
-      continue
-    }
-    const step = steps.find((value) => value.id === event.id)
-    if (step) steps[steps.indexOf(step)] = { ...step, state: 'done' }
-  }
-  return note
-    ? { revision: `${turn?.token ?? '0'}:${sourceRevision}`, turnId: turn?.token ?? null, workingNote: note, steps }
-    : emptyTrace(turn, sourceRevision)
-}
-
-function applyRolloutEvent(value: unknown, ordinal: number): readonly TraceEvent[] {
-  const event = object(value)
-  const payload = object(event?.payload)
-  if (!event || !payload) return []
-  const result: TraceEvent[] = []
-  const type = field(payload, 'type')
-  if ((event.type === 'event_msg' && type === 'user_message')
-    || (event.type === 'response_item' && (type === 'message' || type === 'input_message') && payload.role === 'user')) {
-    result.push({ type: 'boundary', ids: identities(payload, event), at: at(payload) ?? at(event) })
-  }
-  if (event.type === 'event_msg' && type === 'agent_message' && payload.phase === 'commentary') {
-    const note = displayableNote(payload.message ?? payload.text)
-    if (note) result.push({ type: 'note', text: note })
-  }
-  if (event.type === 'response_item' && (type === 'custom_tool_call' || type === 'function_call')) {
-    const name = field(payload, 'name', 'tool_name') || 'tool'
-    const id = field(payload, 'call_id', 'id') || `tool-${ordinal}`
-    result.push({ type: 'call', step: stepFromInput(id, name, payload.input ?? payload.arguments ?? payload.args, 'running') })
-  }
-  if (event.type === 'response_item' && (type === 'custom_tool_call_output' || type === 'function_call_output')) {
-    const id = field(payload, 'call_id', 'id')
-    if (id) result.push({ type: 'done', id })
-  }
-  if (event.type === 'event_msg' && type === 'web_search_end') {
-    result.push({ type: 'call', step: stepFromInput(field(payload, 'id', 'call_id') || `search-${ordinal}`, 'Search', payload, 'done') })
-  }
-  return result
-}
-
-function applyProjectJsonlEvent(value: unknown, ordinal: number): readonly TraceEvent[] {
-  const entry = object(value)
-  const message = object(entry?.message)
-  if (!entry || !message) return []
-  const result: TraceEvent[] = []
-  if (entry.type === 'user' && message.role === 'user' && isPrompt(message.content))
-    result.push({ type: 'boundary', ids: identities(entry, message), at: at(entry) ?? at(message) })
-  if (entry.type === 'assistant' && message.role === 'assistant') for (const blockValue of items(message.content)) {
-    const block = object(blockValue)
-    if (block?.type === 'text') {
-      const note = displayableNote(block.text)
-      if (note) result.push({ type: 'note', text: note })
-    }
-    if (block?.type === 'tool_use') {
-      const id = field(block, 'id') || `tool-${ordinal}`
-      result.push({ type: 'call', step: stepFromInput(id, field(block, 'name') || 'tool', block.input, 'running') })
-    }
-  }
-  if (entry.type === 'user' && message.role === 'user') for (const blockValue of items(message.content)) {
-    const block = object(blockValue)
-    if (block?.type === 'tool_result') {
-      const id = field(block, 'tool_use_id')
-      if (id) result.push({ type: 'done', id })
-    }
-  }
-  return result
-}
-
-function applySessionJsonlEvent(value: unknown, ordinal: number): readonly TraceEvent[] {
-  const entry = object(value)
-  const message = object(entry?.message)
-  if (!entry || entry.type !== 'message' || !message) return []
-  const result: TraceEvent[] = []
-  if (message.role === 'user' && isPrompt(message.content))
-    result.push({ type: 'boundary', ids: identities(entry, message), at: at(entry) ?? at(message) })
-  if (message.role === 'assistant') for (const blockValue of items(message.content)) {
-    const block = object(blockValue)
-    if (block?.type === 'text') {
-      const note = displayableNote(block.text)
-      if (note) result.push({ type: 'note', text: note })
-    }
-    if (block?.type === 'toolCall') {
-      const id = field(block, 'id') || `tool-${ordinal}`
-      result.push({ type: 'call', step: stepFromInput(id, field(block, 'name') || 'tool', block.arguments, 'running') })
-    }
-  }
-  if (message.role === 'toolResult') {
-    const id = field(message, 'toolCallId')
-    if (id) result.push({ type: 'done', id })
-  }
-  return result
-}
-
-function completeLines(buffer: Buffer): { lines: Buffer[]; remainder: Buffer } {
-  const lines: Buffer[] = []
-  let start = 0
-  for (let index = 0; index < buffer.length; index++) {
-    if (buffer[index] !== 10) continue
-    if (index > start) lines.push(buffer.subarray(start, index))
-    start = index + 1
-  }
-  return { lines, remainder: buffer.subarray(start) }
-}
-
-function readFrom(path: string, start: number): Buffer | null {
-  let fd: number | null = null
-  try {
-    const size = statSync(path).size
-    if (size <= start) return Buffer.alloc(0)
-    const chunk = Buffer.allocUnsafe(size - start)
-    fd = openSync(path, 'r')
-    readSync(fd, chunk, 0, chunk.length, start)
-    return chunk
-  } catch { return null }
-  finally { if (fd !== null) closeSync(fd) }
-}
-
-function readIncremental(path: string | null, apply: ApplyEvent, turn: ExecutionTurn | null): ExecutionTrace {
-  if (!path) return emptyTrace(turn)
-  let size: number
-  try { size = statSync(path).size } catch { return emptyTrace(turn) }
-  const prior = cache.get(path)
-  const trace = prior && prior.size <= size
-    ? { ...prior, events: [...prior.events] }
-    : { size: 0, remainder: Buffer.alloc(0), events: [] as TraceEvent[] }
-  const appended = readFrom(path, trace.size)
-  if (appended === null) return emptyTrace(turn)
-  const { lines, remainder } = completeLines(Buffer.concat([trace.remainder, appended]))
-  for (const [index, line] of lines.entries()) {
-    try { trace.events.push(...apply(JSON.parse(line.toString('utf8')), trace.size + index)) } catch { /* malformed native data is ignored */ }
-  }
-  trace.size = size
-  trace.remainder = remainder
-  cache.set(path, trace)
-  return project(trace.events, String(size), turn)
-}
-
-const codexSessionsDir = () => join(process.env.CODEX_HOME || join(homedir(), '.codex'), 'sessions')
-
-export function codexRolloutPath(threadId: string, root = codexSessionsDir()): string | null {
-  for (const year of children(root)) for (const month of children(join(root, year))) for (const day of children(join(root, year, month))) {
-    const dir = join(root, year, month, day)
-    const file = children(dir).find((name) => name.includes(threadId))
-    if (file) return join(dir, file)
-  }
-  return null
-}
-
-export function readCodexExecutionTrace(threadId: string, turn: ExecutionTurn | null, root = codexSessionsDir()): ExecutionTrace {
-  return readIncremental(codexRolloutPath(threadId, root), applyRolloutEvent, turn)
-}
-
-const projectTranscriptRoot = () => join(process.env.CLAUDE_CONFIG_DIR || join(homedir(), '.claude'), 'projects')
-
-function projectJsonlPath(threadId: string, root = projectTranscriptRoot()): string | null {
-  for (const project of children(root)) {
-    const path = join(root, project, `${threadId}.jsonl`)
-    try { if (statSync(path).isFile()) return path } catch { /* try next */ }
-  }
-  return null
-}
-
-export function readProjectJsonlExecutionTrace(threadId: string, turn: ExecutionTurn | null, root = projectTranscriptRoot()): ExecutionTrace {
-  return readIncremental(projectJsonlPath(threadId, root), applyProjectJsonlEvent, turn)
-}
-
-const sessionJsonlRoot = () => join(process.env.SPEXCODE_PI_AGENT_DIR || join(homedir(), '.pi', 'agent'), 'sessions')
-
-function sessionJsonlPath(threadId: string, root = sessionJsonlRoot()): string | null {
-  const key = `${root}:${threadId}`
-  const cached = sessionJsonlPaths.get(key)
-  if (cached) {
-    try { if (statSync(cached).isFile()) return cached } catch { sessionJsonlPaths.delete(key) }
-  }
-  for (const directory of children(root)) for (const file of children(join(root, directory))) {
-    if (!file.endsWith('.jsonl')) continue
-    const path = join(root, directory, file)
-    try {
-      const header = object(JSON.parse(readFileSync(path, 'utf8').split('\n', 1)[0]))
-      if (header?.type === 'session' && header.id === threadId) {
-        sessionJsonlPaths.set(key, path)
-        return path
-      }
-    } catch { /* unreadable entries are not a match */ }
-  }
-  return null
-}
-
-export function readSessionJsonlExecutionTrace(threadId: string, turn: ExecutionTurn | null, root = sessionJsonlRoot()): ExecutionTrace {
-  return readIncremental(sessionJsonlPath(threadId, root), applySessionJsonlEvent, turn)
-}
-
-const localStoreRoot = () => process.env.SPEXCODE_OPENCODE_DATA_DIR
-  || join(process.env.XDG_DATA_HOME || join(homedir(), '.local', 'share'), 'opencode')
-
-function readLocalExport(threadId: string): string {
-  return execFileSync(process.env.SPEXCODE_OPENCODE_CMD || 'opencode', ['export', threadId, '--sanitize'], {
-    encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
-  })
-}
-
-function localStoreRevision(root: string): string | null {
-  try {
-    const database = statSync(join(root, 'opencode.db'))
-    let writeAheadLog = '0:0'
-    try {
-      const stat = statSync(join(root, 'opencode.db-wal'))
-      writeAheadLog = `${stat.size}:${Math.floor(stat.mtimeMs)}`
-    } catch { /* a checkpointed database has no separate write-ahead log */ }
-    return `${database.size}:${Math.floor(database.mtimeMs)}:${writeAheadLog}`
-  } catch { return null }
-}
-
-function localStoreEvents(value: unknown): TraceEvent[] {
-  const events: TraceEvent[] = []
-  for (const messageValue of items(object(value)?.messages)) {
-    const message = object(messageValue)
-    const info = object(message?.info)
-    if (!message || !info) continue
-    if (info.role === 'user') events.push({ type: 'boundary', ids: identities(info, message), at: at(object(info.time) || info) })
-    if (info.role !== 'assistant') continue
-    for (const partValue of items(message.parts)) {
-      const part = object(partValue)
-      if (part?.type === 'text') {
-        const note = displayableNote(part.text)
-        if (note) events.push({ type: 'note', text: note })
-      }
-      if (part?.type === 'tool') {
-        const state = object(part.state)
-        const status = field(state || {}, 'status')?.toLowerCase() || ''
-        const id = field(part, 'callID', 'id') || `tool-${events.length}`
-        events.push({ type: 'call', step: stepFromInput(id, field(part, 'tool') || 'tool', state?.input, /completed|error|cancelled/.test(status) ? 'done' : 'running') })
-      }
-    }
-  }
-  return events
-}
-
-export function readLocalStoreExecutionTrace(threadId: string, turn: ExecutionTurn | null, root = localStoreRoot(), load: ExportLoader = readLocalExport): ExecutionTrace {
-  const revision = localStoreRevision(root)
-  if (!revision) return emptyTrace(turn)
-  const key = `${root}:${threadId}`
-  let cached = localStoreCache.get(key)
-  if (!cached || cached.revision !== revision) {
-    try {
-      cached = { revision, events: localStoreEvents(JSON.parse(load(threadId))) }
-      localStoreCache.set(key, cached)
-    } catch { return emptyTrace(turn, revision) }
-  }
-  return project(cached.events, revision, turn)
-}
-
-export const noExecutionTrace = (_threadId: string, _turn: ExecutionTurn | null): ExecutionTrace | null => null

package/spec-cli/src/file-write.ts

@@ -1,22 +0,0 @@
-import { copyFileSync, readFileSync, writeFileSync } from 'node:fs'
-
-export function writeFileIfChanged(path: string, content: string | Uint8Array): boolean {
-  const next = Buffer.from(content)
-  try {
-    if (readFileSync(path).equals(next)) return false
-  } catch (error: any) {
-    if (error?.code !== 'ENOENT') throw error
-  }
-  writeFileSync(path, content)
-  return true
-}
-
-export function copyFileIfChanged(source: string, target: string): boolean {
-  try {
-    if (readFileSync(target).equals(readFileSync(source))) return false
-  } catch (error: any) {
-    if (error?.code !== 'ENOENT') throw error
-  }
-  copyFileSync(source, target)
-  return true
-}

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

@@ -1,181 +0,0 @@
-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' }
-}