spexcode 0.6.1 → 0.6.5

package/node_modules/@spexcode/spec-cli/dist/gateway-auth.d.ts

@@ -0,0 +1,56 @@
+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';
+};
+export declare function authStorePath(): string;
+export declare function loadAuthStore(): AuthStore;
+export declare function makeVerifier(password: string): Verifier;
+export declare function verifyPassword(v: Verifier | undefined, password: string): boolean;
+export declare function setAdminPassword(password: string): AuthStore;
+export declare function clearAdminPassword(): AuthStore;
+export declare function setProjectPassword(projectId: string, password: string): AuthStore;
+export declare function clearProjectPassword(projectId: string): AuthStore;
+export declare function mintToken(store: AuthStore, scope: Scope, nowMs?: number): string;
+export declare function verifyToken(store: AuthStore, token: string, nowMs?: number): Claims | null;
+export declare function adminCookieName(port: number): string;
+export declare function projectCookieName(port: number, projectId: string): string;
+export declare function cookieOf(header: string | undefined, name: string): string | null;
+export declare function isLoopback(addr: string | null | undefined): boolean;
+export type Route = {
+    kind: 'admin';
+} | {
+    kind: 'project';
+    projectId: string;
+};
+export declare function authorize(store: AuthStore, route: Route, cookieHeader: string | undefined, remoteAddr: string | null | undefined, port: number): Decision;

package/node_modules/@spexcode/spec-cli/dist/gateway-auth.js

@@ -0,0 +1,168 @@
+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 '@spexcode/spec-core';
+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 };
+// ---- the private per-user store --------------------------------------------------------------------
+export function authStorePath() {
+    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() {
+    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 = { v: 1, secret: randomBytes(32).toString('base64url'), projects: {} };
+    saveAuthStore(fresh);
+    return fresh;
+}
+function saveAuthStore(store) {
+    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) {
+    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, password) {
+    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, b) {
+    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) {
+    const store = loadAuthStore();
+    store.admin = makeVerifier(password);
+    saveAuthStore(store);
+    return store;
+}
+export function clearAdminPassword() {
+    const store = loadAuthStore();
+    delete store.admin;
+    saveAuthStore(store);
+    return store;
+}
+export function setProjectPassword(projectId, password) {
+    const store = loadAuthStore();
+    store.projects[projectId] = makeVerifier(password);
+    saveAuthStore(store);
+    return store;
+}
+export function clearProjectPassword(projectId) {
+    const store = loadAuthStore();
+    delete store.projects[projectId];
+    saveAuthStore(store);
+    return store;
+}
+// ---- signed session tokens --------------------------------------------------------------------------
+function sign(secret, payload) {
+    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, scope, nowMs = Date.now()) {
+    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 = { 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, token, nowMs = Date.now()) {
+    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;
+    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) { return `spex_admin_${port}`; }
+export function projectCookieName(port, projectId) {
+    return `spex_proj_${port}_${createHash('sha256').update(projectId).digest('hex').slice(0, 12)}`;
+}
+export function cookieOf(header, name) {
+    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) {
+    if (!addr)
+        return false;
+    const a = addr.startsWith('::ffff:') ? addr.slice(7) : addr;
+    return a === '::1' || /^127(\.\d{1,3}){3}$/.test(a);
+}
+export function authorize(store, route, cookieHeader, remoteAddr, port) {
+    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/node_modules/@spexcode/spec-cli/dist/gateway-hub.d.ts

@@ -0,0 +1,28 @@
+import http from 'node:http';
+import { type AuthStore } from './gateway-auth.js';
+import { type ResolvedIdentity } from '@spexcode/spec-core';
+export type HubProject = {
+    id: string;
+    identity: ResolvedIdentity;
+    url: string;
+    port: number;
+    gated: boolean;
+};
+export type HubExtensions = {
+    listProjects?: (store: AuthStore) => Promise<object[]> | object[];
+    adminRoute?: (req: http.IncomingMessage, res: http.ServerResponse, path: string) => Promise<boolean> | boolean;
+    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;
+};
+export declare function listHubProjects(store: AuthStore): HubProject[];
+export declare function startHubGateway(opts: HubOpts): http.Server;

package/node_modules/@spexcode/spec-cli/dist/gateway-hub.js

@@ -0,0 +1,361 @@
+// @@@ 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, } from './gateway-auth.js';
+import { loginPage } from './login-page.js';
+import { listenOrExit } from './listen.js';
+import { installConnectionReaper } from './reaper.js';
+import { spexcodeHome, encodeProject } from '@spexcode/spec-core';
+import { readEndpointRecord } from './host.js';
+import { readGatewayIdentity } from '@spexcode/spec-core';
+import { proxyHttp, proxySessionWeb, proxySessionWebUpgrade } from './gateway.js';
+// ---- 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) {
+    const rec = readEndpointRecord(join(spexcodeHome(), 'projects', id, 'backend.json'));
+    if (!rec || encodeProject(rec.root) !== id)
+        return null;
+    let u;
+    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, root: rec.root, identity: rec.identity };
+}
+// a projectId arrives as ONE url path segment; reject anything that could re-shape the registry path.
+function validProjectId(id) {
+    return id.length > 0 && id.length <= 256 && id !== '.' && id !== '..' &&
+        !id.includes('/') && !id.includes('\\') && !id.includes('\0');
+}
+export function listHubProjects(store) {
+    const dir = join(spexcodeHome(), 'projects');
+    let entries = [];
+    try {
+        entries = readdirSync(dir);
+    }
+    catch { /* no projects yet */ }
+    const out = [];
+    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, status, body) {
+    res.writeHead(status, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify(body));
+}
+function sendHtml(res, status, html) {
+    res.writeHead(status, { 'Content-Type': 'text/html; charset=utf-8' });
+    res.end(html);
+}
+function redirect(res, location, setCookie) {
+    res.writeHead(302, { Location: location, ...(setCookie ? { 'Set-Cookie': setCookie } : {}) });
+    res.end();
+}
+function readBody(req, limit = 4096) {
+    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, body) {
+    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) {
+    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) {
+    return `; HttpOnly; Path=/; SameSite=Lax; Max-Age=2592000${secure ? '; Secure' : ''}`;
+}
+// ---- the hub ----------------------------------------------------------------------------------------
+export function startHubGateway(opts) {
+    const secure = !!opts.tls;
+    const port = opts.port;
+    const ext = opts.extensions ?? {};
+    const attrs = cookieAttrs(secure);
+    const clearCookie = (name) => `${name}=; HttpOnly; Path=/; Max-Age=0`;
+    const handler = async (req, res) => {
+        // 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/non-web 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 outside /api and /web serves the SPA shell (its root-absolute assets
+            // resolve outside /p onto the same fallback); API/SSE/health fetches, posted-web frames, and WS
+            // upgrades keep the auth gate and proxy to their backend untouched.
+            if (req.method === 'GET' && !sub.startsWith('/api') && !sub.startsWith('/web/') && 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`);
+            }
+            if (proxySessionWeb(req, res, sub + query, up.root))
+                return;
+            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, res) => void handler(req, res).catch((e) => {
+        console.error(`[hub] request failed: ${e.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) : '');
+        if (proxySessionWebUpgrade(req, socket, head, sub, up.root))
+            return;
+        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) {
+    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, res, upstreamPort, path) {
+    const headers = { ...req.headers };
+    const kept = stripGatewayCookies(req.headers.cookie);
+    if (kept)
+        headers.cookie = kept;
+    else
+        delete headers.cookie;
+    proxyHttp(req, res, upstreamPort, path, headers);
+}

package/node_modules/@spexcode/spec-cli/dist/gateway.d.ts

@@ -0,0 +1,37 @@
+import http from 'node:http';
+import type { Duplex } from 'node:stream';
+export type PublicConfig = {
+    password: string;
+    tls: {
+        cert: string;
+        key: string;
+    } | null;
+};
+export declare function resolvePublicConfig(repoRoot: string): PublicConfig | null;
+export declare function resolveDistDir(): string;
+export type GatewayOpts = {
+    publicPort: number;
+    upstreamPort: number;
+    password: string;
+    tls: {
+        cert: string;
+        key: string;
+    } | null;
+    distDir: string;
+    host?: string;
+    label?: string;
+    onBindFail?: () => void;
+    projectRoot?: string;
+};
+export declare function startGateway(opts: GatewayOpts): void;
+export declare function rawHeaders(req: http.IncomingMessage): string;
+export declare function proxyHttp(req: http.IncomingMessage, res: http.ServerResponse, upstreamPort: number, path?: string, headers?: http.OutgoingHttpHeaders, unavailableMessage?: string, upstreamHost?: string): void;
+export declare function proxySessionWeb(req: http.IncomingMessage, res: http.ServerResponse, raw?: string, projectRoot?: string): boolean;
+export declare function proxySessionWebUpgrade(req: http.IncomingMessage, socket: Duplex, head: Buffer, raw?: string, projectRoot?: string): boolean;
+export declare function serveStatic(req: http.IncomingMessage, res: http.ServerResponse, distDir: string, urlPath: string): http.ServerResponse<http.IncomingMessage> | undefined;
+export declare function serveDashboardLocal(opts: {
+    port: number;
+    apiPort: number;
+    host?: string;
+    projectRoot?: string;
+}): void;