spexcode 0.4.1 → 0.4.3

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' }
+}

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

@@ -0,0 +1,360 @@
+// @@@ gateway hub - the multi-project face of [[public-mode]]: ONE gateway fronting every project backend
+// this user runs. The backends stay loopback internal services (each `spex serve` records its endpoint in
+// ~/.spexcode/projects/<enc>/backend.json — that record IS the hub's registry); the hub terminates the
+// outside world, decides authorization ([[gateway-auth]] — the single mechanism, two signed scopes), and
+// reverse-proxies into the matching loopback backend with the gateway's own cookies STRIPPED, so a backend
+// never sees a credential.
+//
+// The route contract:
+//   /login /logout                      admin session (the designed login page)
+//   GET /projects                       admin: list the registry (+ gating state); with a host shell
+//                                       mounted, an explicit text/html GET gets the Projects UI instead
+//   PUT|DELETE /projects/admin-password admin: set/clear the admin password
+//   PUT|DELETE /projects/:id/password   admin: set/clear one project's password
+//   /p/:projectId/login|logout          project session for that project
+//   ANY /p/:projectId/*  (+ WS upgrade) authorized → proxied, prefix-stripped, to that project's backend
+// Authorization never trusts the cookie's name or Path — the token's projectId claim is validated against
+// the :projectId in the URL on every request (see gateway-auth.ts).
+import http from 'node:http'
+import https from 'node:https'
+import net from 'node:net'
+import { readdirSync } from 'node:fs'
+import { join } from 'node:path'
+import {
+  adminCookieName, authorize, clearAdminPassword, clearProjectPassword, loadAuthStore, mintToken,
+  projectCookieName, setAdminPassword, setProjectPassword, verifyPassword, type AuthStore,
+} from './gateway-auth.js'
+import { loginPage } from './login-page.js'
+import { listenOrExit } from './listen.js'
+import { installConnectionReaper } from './reaper.js'
+import { spexcodeHome, encodeProject } from './layout.js'
+import { readEndpointRecord } from './host.js'
+import { readGatewayIdentity, type ResolvedIdentity } from './project-identity.js'
+
+export type HubProject = { id: string; identity: ResolvedIdentity; url: string; port: number; gated: boolean }
+// @@@ extension seam - the hub stays the ONE routing+authorization server; a host-level caller
+// ([[host-gateway]]'s `spex dashboard`) plugs richer behavior in here instead of running a second
+// gateway beside it. All three hooks are optional; bare startHubGateway behavior is unchanged.
+export type HubExtensions = {
+  // enriched GET /projects rows (reconciled online/offline entries + the durable catalog); the hub
+  // still owns the envelope ({adminGated, projects}) and the admin gate in front of it.
+  listProjects?: (store: AuthStore) => Promise<object[]> | object[]
+  // extra ADMIN-scope routes under /projects/* (stream, registration, project operations) — called only
+  // AFTER admin authorization, for /projects paths the hub itself doesn't handle. True = handled.
+  adminRoute?: (req: http.IncomingMessage, res: http.ServerResponse, path: string) => Promise<boolean> | boolean
+  // paths the hub would 404 (everything outside /projects, /p, /login) — the dashboard SPA shell +
+  // assets. Unauthorized by design: the shell is code, not data; every data call it makes re-enters
+  // the authorized routes.
+  fallback?: (req: http.IncomingMessage, res: http.ServerResponse, path: string) => void
+}
+export type HubOpts = { port: number; host?: string; tls?: { cert: string; key: string } | null; label?: string; onBindFail?: () => void; extensions?: HubExtensions }
+
+// ---- registry ---------------------------------------------------------------------------------------
+// A project = a live backend record under ~/.spexcode/projects/<enc>/backend.json (written by supervise.ts
+// at bind time). The <enc> dir name is the projectId. ONE record-read seam ([[host-gateway]]'s
+// readEndpointRecord — the identity-carrying shape): a legacy or torn record is not routable, and a record
+// sitting in a slot its own root does not encode to is not trusted. Only LOOPBACK upstream urls are
+// honored — the hub proxies into this machine's trust boundary, never out to an arbitrary host a crafted
+// record names.
+
+function upstreamOf(id: string): { url: string; port: number; identity: ResolvedIdentity } | null {
+  const rec = readEndpointRecord(join(spexcodeHome(), 'projects', id, 'backend.json'))
+  if (!rec || encodeProject(rec.root) !== id) return null
+  let u: URL
+  try { u = new URL(rec.url) } catch { return null }
+  if (u.protocol !== 'http:' || (u.hostname !== '127.0.0.1' && u.hostname !== 'localhost')) {
+    console.error(`[hub] ignoring project '${id}': backend url ${rec.url} is not a loopback http endpoint`)
+    return null
+  }
+  const port = Number(u.port || 80)
+  if (!Number.isInteger(port) || port <= 0) return null
+  return { url: rec.url, port, identity: rec.identity }
+}
+
+// a projectId arrives as ONE url path segment; reject anything that could re-shape the registry path.
+function validProjectId(id: string): boolean {
+  return id.length > 0 && id.length <= 256 && id !== '.' && id !== '..' &&
+    !id.includes('/') && !id.includes('\\') && !id.includes('\0')
+}
+
+export function listHubProjects(store: AuthStore): HubProject[] {
+  const dir = join(spexcodeHome(), 'projects')
+  let entries: string[] = []
+  try { entries = readdirSync(dir) } catch { /* no projects yet */ }
+  const out: HubProject[] = []
+  for (const id of entries) {
+    const up = upstreamOf(id)
+    if (!up) continue
+    out.push({ id, identity: up.identity, url: up.url, port: up.port, gated: !!store.projects[id] })
+  }
+  return out.sort((a, b) => a.id.localeCompare(b.id))
+}
+
+// ---- helpers ----------------------------------------------------------------------------------------
+
+function sendJson(res: http.ServerResponse, status: number, body: unknown): void {
+  res.writeHead(status, { 'Content-Type': 'application/json' })
+  res.end(JSON.stringify(body))
+}
+function sendHtml(res: http.ServerResponse, status: number, html: string): void {
+  res.writeHead(status, { 'Content-Type': 'text/html; charset=utf-8' })
+  res.end(html)
+}
+function redirect(res: http.ServerResponse, location: string, setCookie?: string): void {
+  res.writeHead(302, { Location: location, ...(setCookie ? { 'Set-Cookie': setCookie } : {}) })
+  res.end()
+}
+
+function readBody(req: http.IncomingMessage, limit = 4096): Promise<string> {
+  return new Promise((resolve) => {
+    let body = ''
+    req.on('data', (d) => { body += d; if (body.length > limit) { req.destroy(); resolve('') } })
+    req.on('end', () => resolve(body))
+    req.on('error', () => resolve(''))
+  })
+}
+
+// the login POST accepts the designed page's form encoding or JSON (the future admin UI)
+function passwordOf(req: http.IncomingMessage, body: string): string {
+  try {
+    return req.headers['content-type']?.includes('application/json')
+      ? String(JSON.parse(body).password ?? '')
+      : new URLSearchParams(body).get('password') ?? ''
+  } catch { return '' }
+}
+
+// the gateway's own cookies never cross into a backend — a backend knows nothing about visitors, and a
+// leaked gateway token in some backend log would be a credential spill. Everything else passes through.
+function stripGatewayCookies(header: string | undefined): string {
+  return (header ?? '').split(';').map((s) => s.trim())
+    .filter((p) => p && !/^spex_(admin|proj|auth)_/i.test(p.slice(0, Math.max(p.indexOf('='), 0))))
+    .join('; ')
+}
+
+function cookieAttrs(secure: boolean): string {
+  return `; HttpOnly; Path=/; SameSite=Lax; Max-Age=2592000${secure ? '; Secure' : ''}`
+}
+
+// ---- the hub ----------------------------------------------------------------------------------------
+
+export function startHubGateway(opts: HubOpts): http.Server {
+  const secure = !!opts.tls
+  const port = opts.port
+  const ext = opts.extensions ?? {}
+  const attrs = cookieAttrs(secure)
+  const clearCookie = (name: string) => `${name}=; HttpOnly; Path=/; Max-Age=0`
+
+  const handler = async (req: http.IncomingMessage, res: http.ServerResponse) => {
+    // the store is re-read per request: a password set/clear (this process or another) is live at once,
+    // and there is no in-memory session state to invalidate.
+    const store = loadAuthStore()
+    const rawUrl = req.url || '/'
+    const q = rawUrl.indexOf('?')
+    const path = q >= 0 ? rawUrl.slice(0, q) : rawUrl
+    const query = q >= 0 ? rawUrl.slice(q) : ''
+    const remote = req.socket.remoteAddress
+    const cookies = req.headers.cookie
+    const adminz = () => authorize(store, { kind: 'admin' }, cookies, remote, port)
+
+    // ---- admin surface ----
+    if (path === '/') return redirect(res, '/projects')
+    if (path === '/login') {
+      if (!store.admin) return req.method === 'POST'
+        ? sendJson(res, 403, { error: 'no admin password is configured — /projects is manageable from loopback only' })
+        : redirect(res, '/projects')
+      if (req.method === 'POST') {
+        const pw = passwordOf(req, await readBody(req))
+        if (verifyPassword(store.admin, pw)) return redirect(res, '/projects', `${adminCookieName(port)}=${mintToken(store, { s: 'admin' })}${attrs}`)
+        return sendHtml(res, 401, loginPage(true))
+      }
+      return sendHtml(res, 200, loginPage(false))
+    }
+    if (path === '/logout') return redirect(res, '/login', clearCookie(adminCookieName(port)))
+
+    if (path === '/projects' || path.startsWith('/projects/')) {
+      // browser navigation (the `/` redirect lands here with Accept: text/html) wants the Projects UI,
+      // not the catalog envelope. With a host shell mounted, an explicit text/html GET is served the SPA
+      // shell — code, not data, same unauthorized-by-design posture as the fallback seam: every data call
+      // the shell makes re-enters the JSON route below with its auth gate intact. API fetches
+      // (application/json, */*, no Accept) keep the JSON catalog unchanged, as does the bare hub.
+      if (path === '/projects' && req.method === 'GET' && ext.fallback && (req.headers.accept ?? '').includes('text/html')) {
+        return ext.fallback(req, res, path)
+      }
+      const d = adminz()
+      if (!d.ok) {
+        return d.reason === 'locked'
+          ? sendJson(res, 403, { error: 'admin surface is locked: no admin password is configured and this is not a loopback connection' })
+          : sendJson(res, 401, { error: 'authentication required', login: '/login' })
+      }
+      if (path === '/projects' && req.method === 'GET') {
+        const gateway = readGatewayIdentity()
+        return sendJson(res, 200, {
+          adminGated: !!store.admin,
+          gateway: { ...gateway.identity, revision: gateway.revision },
+          projects: await (ext.listProjects ? ext.listProjects(store) : listHubProjects(store)),
+        })
+      }
+      if (path === '/projects/admin-password') {
+        if (req.method === 'PUT') {
+          const pw = passwordOf(req, await readBody(req))
+          if (!pw) return sendJson(res, 400, { error: 'body must be JSON {"password": "<non-empty>"}' })
+          const next = setAdminPassword(pw)
+          // the setter stays authenticated: implicit-loopback access ends the moment the password exists,
+          // so hand them a session minted under the new verifier in the same response.
+          res.setHeader('Set-Cookie', `${adminCookieName(port)}=${mintToken(next, { s: 'admin' })}${attrs}`)
+          return sendJson(res, 200, { ok: true })
+        }
+        if (req.method === 'DELETE') {
+          clearAdminPassword()
+          res.setHeader('Set-Cookie', clearCookie(adminCookieName(port)))
+          return sendJson(res, 200, { ok: true })
+        }
+        return sendJson(res, 405, { error: 'PUT or DELETE' })
+      }
+      const m = path.match(/^\/projects\/([^/]+)\/password$/)
+      if (m) {
+        const id = decodeURIComponent(m[1])
+        if (!validProjectId(id)) return sendJson(res, 404, { error: 'unknown project' })
+        if (req.method === 'PUT') {
+          if (!upstreamOf(id)) return sendJson(res, 404, { error: 'unknown project' })
+          const pw = passwordOf(req, await readBody(req))
+          if (!pw) return sendJson(res, 400, { error: 'body must be JSON {"password": "<non-empty>"}' })
+          setProjectPassword(id, pw)
+          return sendJson(res, 200, { ok: true })
+        }
+        if (req.method === 'DELETE') { // clearing works even for a retired registry entry — the cleanup path
+          clearProjectPassword(id)
+          return sendJson(res, 200, { ok: true })
+        }
+        return sendJson(res, 405, { error: 'PUT or DELETE' })
+      }
+      // host-level admin routes ([[host-gateway]]: /projects/stream, registration, project operations)
+      // ride the SAME admin gate — the extension only ever sees an authorized request.
+      if (ext.adminRoute && await ext.adminRoute(req, res, path)) return
+      return sendJson(res, 404, { error: 'not found' })
+    }
+
+    // ---- project surface ----
+    const pm = path.match(/^\/p\/([^/]+)(\/.*)?$/)
+    if (pm) {
+      const id = decodeURIComponent(pm[1])
+      if (!validProjectId(id)) return sendJson(res, 404, { error: 'unknown project' })
+      const up = upstreamOf(id)
+      if (!up) return sendJson(res, 404, { error: 'unknown project' })
+      const sub = pm[2] || '/'
+      const base = `/p/${encodeURIComponent(id)}`
+      const gated = !!store.projects[id]
+      if (sub === '/login') {
+        if (!gated) return redirect(res, `${base}/`)
+        if (req.method === 'POST') {
+          const pw = passwordOf(req, await readBody(req))
+          if (verifyPassword(store.projects[id], pw)) {
+            return redirect(res, `${base}/`, `${projectCookieName(port, id)}=${mintToken(store, { s: 'project', p: id })}${attrs}`)
+          }
+          return sendHtml(res, 401, loginPage(true, { action: `${base}/login`, heading: 'Project access', sub: `Enter the password for this project.` }))
+        }
+        return sendHtml(res, 200, loginPage(false, { action: `${base}/login`, heading: 'Project access', sub: `Enter the password for this project.` }))
+      }
+      if (sub === '/logout') return redirect(res, `${base}/login`, clearCookie(projectCookieName(port, id)))
+      // browser navigation into the scoped page (`/p/<id>/`, any non-api sub) is content-negotiated
+      // exactly like GET /projects, and — like the fallback it rides — PRE-authorization: the shell is
+      // code, not data ([[projects-hub]]'s one credential card renders in-app off the scoped api's 401,
+      // and a direct guest must reach that card, not a dead-end redirect). With a host fallback mounted,
+      // an explicit text/html GET serves the SPA shell (its root-absolute assets resolve outside /p onto
+      // the same fallback); every api/SSE/health fetch (json, */*, event-stream) and the WS upgrade keep
+      // the auth gate and proxy to the backend untouched.
+      if (req.method === 'GET' && !sub.startsWith('/api') && ext.fallback && (req.headers.accept ?? '').includes('text/html')) {
+        return ext.fallback(req, res, '/')
+      }
+      const d = authorize(store, { kind: 'project', projectId: id }, cookies, remote, port)
+      if (!d.ok) {
+        if (sub.startsWith('/api')) return sendJson(res, 401, { error: 'authentication required', login: `${base}/login` })
+        return redirect(res, `${base}/login`)
+      }
+      return proxyTo(req, res, up.port, sub + query)
+    }
+
+    // outside /projects and /p/: the dashboard shell + assets when a host extension serves them, 404 bare.
+    if (ext.fallback) return ext.fallback(req, res, path)
+    return sendJson(res, 404, { error: 'not found' })
+  }
+
+  // a handler throw answers 500 and never becomes an unhandled rejection — the hub owns a public port
+  // and must keep serving (same posture as the supervisor's process guards).
+  const safe = (req: http.IncomingMessage, res: http.ServerResponse) =>
+    void handler(req, res).catch((e) => {
+      console.error(`[hub] request failed: ${(e as Error).message}`)
+      if (!res.headersSent) res.writeHead(500, { 'Content-Type': 'application/json' })
+      res.end('{"error":"internal error"}')
+    })
+  const server = secure
+    ? https.createServer({ cert: opts.tls!.cert, key: opts.tls!.key }, safe)
+    : http.createServer(safe)
+  installConnectionReaper(server)
+
+  // the terminal WebSocket rides an HTTP upgrade on a /p/:id path: same authorization, then a raw byte
+  // pipe to that project's backend with the prefix stripped and the gateway cookies filtered out.
+  server.on('upgrade', (req, socket, head) => {
+    const store = loadAuthStore()
+    const rawUrl = req.url || '/'
+    const q = rawUrl.indexOf('?')
+    const path = q >= 0 ? rawUrl.slice(0, q) : rawUrl
+    const pm = path.match(/^\/p\/([^/]+)(\/.*)?$/)
+    if (!pm) return socket.destroy()
+    const id = decodeURIComponent(pm[1])
+    if (!validProjectId(id)) return socket.destroy()
+    const up = upstreamOf(id)
+    if (!up) return socket.destroy()
+    const d = authorize(store, { kind: 'project', projectId: id }, req.headers.cookie, req.socket.remoteAddress, port)
+    if (!d.ok) return socket.destroy()
+    const sub = (pm[2] || '/') + (q >= 0 ? rawUrl.slice(q) : '')
+    const upstream = net.connect(up.port, '127.0.0.1', () => {
+      upstream.write(`${req.method} ${sub} HTTP/1.1\r\n` + filteredRawHeaders(req))
+      if (head && head.length) upstream.write(head)
+      socket.pipe(upstream); upstream.pipe(socket)
+    })
+    const bail = () => { socket.destroy(); upstream.destroy() }
+    socket.on('error', bail); upstream.on('error', bail)
+    // pair the halves fully (the supervisor's rule): an http server's sockets are allowHalfOpen, so a bare
+    // client FIN ('end') would otherwise leave a zombie socket the server can never close — an upgraded
+    // stream never half-closes legitimately, so either half's FIN or close tears down both.
+    socket.on('end', bail); upstream.on('end', bail)
+    socket.once('close', () => upstream.destroy())
+    upstream.once('close', () => socket.destroy())
+  })
+
+  const onListen = () => {
+    const scheme = secure ? 'https' : 'http'
+    console.log(`[hub] multi-project gateway on ${scheme}://${opts.host ?? '0.0.0.0'}:${port} — /projects + /p/:projectId/*`)
+  }
+  listenOrExit(server, port, { host: opts.host, label: opts.label ?? 'hub gateway', cleanup: opts.onBindFail, onListen })
+  return server
+}
+
+// replay an upgrade's headers with the Cookie header rewritten to exclude the gateway's own cookies.
+function filteredRawHeaders(req: http.IncomingMessage): string {
+  let s = ''
+  for (let i = 0; i < req.rawHeaders.length; i += 2) {
+    const name = req.rawHeaders[i]
+    if (name.toLowerCase() === 'cookie') {
+      const kept = stripGatewayCookies(req.rawHeaders[i + 1])
+      if (kept) s += `Cookie: ${kept}\r\n`
+      continue
+    }
+    s += `${name}: ${req.rawHeaders[i + 1]}\r\n`
+  }
+  return s + '\r\n'
+}
+
+// reverse-proxy one authorized request to a project's loopback backend, prefix already stripped.
+function proxyTo(req: http.IncomingMessage, res: http.ServerResponse, upstreamPort: number, path: string): void {
+  const headers: http.OutgoingHttpHeaders = { ...req.headers }
+  const kept = stripGatewayCookies(req.headers.cookie)
+  if (kept) headers.cookie = kept; else delete headers.cookie
+  const up = http.request({ host: '127.0.0.1', port: upstreamPort, path, method: req.method, headers }, (upRes) => {
+    res.writeHead(upRes.statusCode || 502, upRes.headers)
+    upRes.pipe(res)
+  })
+  up.on('error', () => { if (!res.headersSent) res.writeHead(502, { 'Content-Type': 'text/plain' }); res.end('project backend unreachable') })
+  req.pipe(up)
+}

package/spec-cli/src/gateway.ts

@@ -151,16 +151,14 @@ export function startGateway(opts: GatewayOpts): void {
   }
 
   // server-side connection reaping ([[spec-cli]] / [[public-mode]]) - the internet-facing gateway is the
-  // public server in public mode, so it carries the SAME reaping as the child. The `reap` HTTP timeouts are
-  // kept (harmless) but are NOT the mechanism — MEASURED (eval server-reaps-abandoned-connections), Node's
-  // headersTimeout/requestTimeout don't reap an INCOMPLETE request; the real reaper is the socket-level
-  // `installConnectionReaper` (reaper.ts), applied below at every http server the serving path creates.
-  // Idle keep-alive / slow-loris / never-completing request only; the gated WS upgrade (handled below) is an
-  // active stream and exempt for its lifetime.
-  const reap = { keepAliveTimeout: 10000, headersTimeout: 20000, requestTimeout: 60000, connectionsCheckingInterval: 10000 }
+  // public server in public mode, so it carries the SAME reaping as the child: the socket-level
+  // `installConnectionReaper` (reaper.ts), the single owner of the header/idle deadlines — it disables
+  // Node's own overlapping HTTP timeouts, which were measured to race and shadow it (issue #65), so no
+  // timeout options are passed here. Idle keep-alive / slow-loris / never-completing request only; the
+  // gated WS upgrade (handled below) is an active stream and exempt for its lifetime.
   const server = secure
-    ? https.createServer({ cert: opts.tls!.cert, key: opts.tls!.key, ...reap }, handler)
-    : http.createServer(reap, handler)
+    ? https.createServer({ cert: opts.tls!.cert, key: opts.tls!.key }, handler)
+    : http.createServer(handler)
   installConnectionReaper(server)
 
   // @@@ WS gate - the terminal socket rides an HTTP upgrade. Gate it by the SAME cookie (the browser sends
@@ -175,6 +173,12 @@ export function startGateway(opts: GatewayOpts): void {
     })
     const bail = () => { socket.destroy(); up.destroy() }
     socket.on('error', bail); up.on('error', bail)
+    // pair the halves fully (the supervisor's rule): an http server's sockets are allowHalfOpen, so a bare
+    // client FIN ('end') would otherwise leave this side open forever — an upgraded stream never
+    // half-closes legitimately, so either half's FIN or close tears down both.
+    socket.on('end', bail); up.on('end', bail)
+    socket.once('close', () => up.destroy())
+    up.once('close', () => socket.destroy())
   })
 
   // `spex serve ui` passes an explicit host (loopback by default, --host to widen); `--public` passes
@@ -194,7 +198,9 @@ export function startGateway(opts: GatewayOpts): void {
   listenOrExit(server, opts.publicPort, { host: opts.host, label: opts.label ?? 'gateway', cleanup: opts.onBindFail, onListen })
 }
 
-function rawHeaders(req: http.IncomingMessage): string {
+// re-serialize an upgrade request's headers for replay against the upstream (exported for the host
+// gateway's per-project WS pipe, which replays the same way).
+export function rawHeaders(req: http.IncomingMessage): string {
   let s = ''
   for (let i = 0; i < req.rawHeaders.length; i += 2) s += `${req.rawHeaders[i]}: ${req.rawHeaders[i + 1]}\r\n`
   return s + '\r\n'
@@ -221,8 +227,10 @@ const wantsGzip = (req: http.IncomingMessage) => /\bgzip\b/.test(String(req.head
 
 // reverse-proxy an /api request to the loopback supervisor (which forwards to the live child) —
 // stream-gzipping compressible bodies (measured: the board JSON rides down at under a third).
-function proxyHttp(req: http.IncomingMessage, res: http.ServerResponse, upstreamPort: number) {
-  const up = http.request({ host: '127.0.0.1', port: upstreamPort, path: req.url, method: req.method, headers: req.headers }, (upRes) => {
+// `path` overrides the upstream path (the host gateway strips its /p/:projectId prefix); default = as-is.
+// Exported: the host gateway ([[host-gateway]]) proxies per-project traffic through this same function.
+export function proxyHttp(req: http.IncomingMessage, res: http.ServerResponse, upstreamPort: number, path?: string) {
+  const up = http.request({ host: '127.0.0.1', port: upstreamPort, path: path ?? req.url, method: req.method, headers: req.headers }, (upRes) => {
     const type = String(upRes.headers['content-type'] || '')
     const skip = !wantsGzip(req) || upRes.headers['content-encoding'] || !COMPRESSIBLE.test(type) || type.startsWith('text/event-stream')
     if (skip) { res.writeHead(upRes.statusCode || 502, upRes.headers); upRes.pipe(res); return }
@@ -238,30 +246,30 @@ function proxyHttp(req: http.IncomingMessage, res: http.ServerResponse, upstream
 // serve the built dashboard (vite dist). Unknown non-file paths fall back to index.html (SPA). Path
 // traversal is blocked by normalising and confining to distDir. Compressible files ship gzipped, memoized
 // per (path, mtime) — a dist file is immutable per build, so each is compressed once, not per request.
+// Exported: the host gateway serves the same dist through the same function.
 const gzMemo = new Map<string, { mtime: number; gz: Buffer }>()
-function serveStatic(req: http.IncomingMessage, res: http.ServerResponse, distDir: string, urlPath: string) {
+export function serveStatic(req: http.IncomingMessage, res: http.ServerResponse, distDir: string, urlPath: string) {
   const rel = normalize(decodeURIComponent(urlPath)).replace(/^(\.\.[/\\])+/, '')
   let file = join(distDir, rel)
   if (!file.startsWith(distDir)) file = join(distDir, 'index.html')
   if (urlPath === '/' || !existsSync(file)) {
-    // @@@ missing-asset 404 - only extensionless SPA routes fall back to index.html. A missing FILE
-    // request (it has an extension) is a stale hashed chunk from a pre-rebuild page still open in some
-    // browser: answering it with HTML trips the strict module-MIME check and hides the miss from the
-    // client — 404 instead, so the shell's vite:preloadError recovery can see it and reload.
+    // @@@ missing-asset 404 - a missing extensioned path is a stale hashed chunk, not an SPA route: answer
+    // 404, not HTML (which trips the module-MIME check), so the shell's reload recovery sees it ([[public-mode]]).
     if (urlPath !== '/' && extname(file)) { res.writeHead(404, { 'Content-Type': 'text/plain' }); return res.end('not found') }
     file = join(distDir, 'index.html')
   }
   if (!existsSync(file)) { res.writeHead(503); return res.end('dashboard build missing') }
   const type = MIME[extname(file)] || 'application/octet-stream'
+  const cacheControl = /[\\/]assets[\\/]/.test(file) ? 'public, max-age=31536000, immutable' : 'no-cache'
   const raw = readFileSync(file)
   if (wantsGzip(req) && COMPRESSIBLE.test(type)) {
     const mtime = statSync(file).mtimeMs
     let hit = gzMemo.get(file)
     if (!hit || hit.mtime !== mtime) { hit = { mtime, gz: gzipSync(raw) }; gzMemo.set(file, hit) }
-    res.writeHead(200, { 'Content-Type': type, 'Content-Encoding': 'gzip', Vary: 'Accept-Encoding' })
+    res.writeHead(200, { 'Content-Type': type, 'Content-Encoding': 'gzip', Vary: 'Accept-Encoding', 'Cache-Control': cacheControl })
     return res.end(hit.gz)
   }
-  res.writeHead(200, { 'Content-Type': type })
+  res.writeHead(200, { 'Content-Type': type, 'Cache-Control': cacheControl })
   res.end(raw)
 }