strikethroo 4.0.0 → 4.1.1

package/dist/serve/server.js

@@ -14,6 +14,23 @@
  *     external self-review binary for a validated in-workspace plan path;
  *   - platform-aware browser auto-open on startup.
  *
+ * The server binds loopback unless the caller passes another IP address in
+ * `host`, and every request — static, API, and the `apiHandlers` extension
+ * point — passes through {@link guardRequest} (Host authority, request-target
+ * parsing) and a single
+ * exception boundary before any route runs. Routes are matched by path first
+ * and method second, so a wrong method answers `405` and a mutation path never
+ * reaches a read handler. Body-bearing mutations require `application/json`.
+ *
+ * Mutations are additionally gated on a per-start capability: a random token
+ * minted in {@link startServer}, handed out only by `GET /api/session` to a
+ * same-origin request, and required in {@link CAPABILITY_HEADER}. Together with
+ * the Origin/fetch-metadata check this closes CSRF and DNS-rebinding paths from
+ * a browser. It is a browser/request safeguard only: it does not isolate the
+ * server from another local process that can already read the user's files
+ * (and so the token). No cookies, no accounts, no CORS — the token lives in
+ * the page's memory and is never persisted, logged, or placed in a URL.
+ *
  * The SSE change stream (`GET /api/events`) is added by a separate module that
  * hooks into the `apiHandlers` extension point below, so this module stays free
  * of file-watching concerns. Node built-ins only — no runtime dependency, no
@@ -53,10 +70,12 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.startServer = exports.defaultAssetsDir = void 0;
+exports.startServer = exports.hostAddressesFor = exports.isLoopbackAddress = exports.CONTENT_SECURITY_POLICY = exports.guardRequest = exports.defaultAssetsDir = exports.CAPABILITY_HEADER = void 0;
 const http = __importStar(require("http"));
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
+const crypto = __importStar(require("crypto"));
+const os = __importStar(require("os"));
 const child_process_1 = require("child_process");
 const url_1 = require("url");
 const workspace_model_1 = require("./workspace-model");
@@ -64,6 +83,8 @@ const events_1 = require("./events");
 const self_review_1 = require("./self-review");
 const archive_1 = require("./archive");
 const config_write_1 = require("./config-write");
+/** Request header carrying the mutation capability. */
+exports.CAPABILITY_HEADER = 'X-Strikethroo-Capability';
 const MIME_TYPES = {
     '.html': 'text/html; charset=utf-8',
     '.js': 'text/javascript; charset=utf-8',
@@ -108,14 +129,117 @@ const deriveProject = (root) => {
  */
 const defaultAssetsDir = () => path.resolve(__dirname, '..', '..', 'dist-web');
 exports.defaultAssetsDir = defaultAssetsDir;
-const sendJson = (res, status, body) => {
+const sendJson = (res, status, body, headers = {}) => {
     const payload = JSON.stringify(body);
     res.writeHead(status, {
         'Content-Type': 'application/json; charset=utf-8',
         'Content-Length': Buffer.byteLength(payload),
+        ...headers,
     });
     res.end(payload);
 };
+/**
+ * Sends an error response if one can still be sent. Once headers are out the
+ * only honest option is to drop the connection, never a half-written body.
+ */
+const sendError = (res, status, body) => {
+    if (res.headersSent) {
+        res.destroy();
+        return;
+    }
+    sendJson(res, status, body);
+};
+const reject = (status, error) => ({
+    ok: false,
+    status,
+    body: { error },
+});
+const BAD_REQUEST = reject(400, 'Bad request.');
+const MISDIRECTED = reject(421, 'Misdirected request.');
+const FORBIDDEN = reject(403, 'Forbidden.');
+/**
+ * Runs before routing, for every request. Refuses any `Host` that is not one
+ * of the server's own loopback authorities (DNS-rebinding defense), then parses
+ * the request target: origin-form (`/path`) or absolute-form naming an allowed
+ * authority; anything else, including a target whose path does not
+ * percent-decode, is a `400`. The returned `pathname` is the only thing routing
+ * consumes.
+ */
+const guardRequest = (req, ctx) => {
+    const host = (req.headers.host ?? '').toLowerCase();
+    if (!ctx.allowedHosts.has(host))
+        return MISDIRECTED;
+    const target = req.url ?? '';
+    let url;
+    try {
+        if (target.startsWith('/')) {
+            // `//authority/path` is scheme-relative, not origin-form; refuse it so the
+            // routed path is never taken from a smuggled authority.
+            if (target.startsWith('//'))
+                return BAD_REQUEST;
+            url = new url_1.URL(target, 'http://127.0.0.1');
+        }
+        else {
+            url = new url_1.URL(target);
+            if (url.protocol !== 'http:' && url.protocol !== 'https:')
+                return BAD_REQUEST;
+            if (!ctx.allowedHosts.has(url.host.toLowerCase()))
+                return MISDIRECTED;
+        }
+        decodeURIComponent(url.pathname);
+    }
+    catch {
+        return BAD_REQUEST;
+    }
+    return { ok: true, pathname: url.pathname };
+};
+exports.guardRequest = guardRequest;
+/**
+ * Same-origin policy for the session bootstrap and every mutation. The request
+ * must carry no cross-site fetch metadata (`Sec-Fetch-Site` absent, `same-origin`
+ * or `none` — a page we served, or a direct navigation) and any `Origin` present
+ * must be `http://<allowed authority>`. `same-site`, `cross-site`, `null`, and a
+ * foreign or https Origin are all refused. Both headers are forbidden request
+ * headers in browsers, so a page cannot forge them; non-browser callers are
+ * what the capability is for.
+ */
+const guardSameOrigin = (req, ctx) => {
+    const site = req.headers['sec-fetch-site'];
+    if (site !== undefined && site !== 'same-origin' && site !== 'none')
+        return FORBIDDEN;
+    const origin = req.headers.origin;
+    if (origin === undefined)
+        return null;
+    const lower = origin.toLowerCase();
+    for (const host of ctx.allowedHosts) {
+        if (lower === `http://${host}`)
+            return null;
+    }
+    return FORBIDDEN;
+};
+/** Constant-time check that {@link CAPABILITY_HEADER} carries this instance's token. */
+const guardCapability = (req, ctx) => {
+    const header = req.headers[exports.CAPABILITY_HEADER.toLowerCase()];
+    if (typeof header !== 'string')
+        return FORBIDDEN;
+    const presented = Buffer.from(header);
+    const expected = Buffer.from(ctx.capability);
+    if (presented.length !== expected.length || !crypto.timingSafeEqual(presented, expected)) {
+        return FORBIDDEN;
+    }
+    return null;
+};
+/** True when `Content-Type` is `application/json`, any case, parameters allowed. */
+const isJson = (req) => {
+    const header = req.headers['content-type'];
+    if (typeof header !== 'string')
+        return false;
+    const mediaType = header.split(';', 1)[0]?.trim().toLowerCase();
+    return mediaType === 'application/json';
+};
+// ---------------------------------------------------------------------------
+// Route handlers
+// ---------------------------------------------------------------------------
 /** The composite plan key grammar: `{id}--{slug}`, e.g. `28--plan-name`. */
 const COMPOSITE_KEY = /^[0-9]+--[a-z0-9-]+$/;
 /**
@@ -160,130 +284,162 @@ const parseArchivePlanId = (pathname) => {
         return null;
     return validateCompositeKey(match[1]);
 };
-/**
- * Handles `POST /api/plans/:id/archive`: delegates entirely to the {@link
- * archivePlan} operation and maps its discriminated result to status codes
- * without duplicating validation. Returns `true` once it owns the response.
- */
-const handleArchive = (res, root, pathname) => {
-    const key = parseArchivePlanId(pathname);
-    if (key === null) {
-        sendJson(res, 400, { error: 'Invalid plan id.' });
-        return true;
-    }
-    (0, archive_1.archivePlan)(root, key)
-        .then(result => {
-        if (result.ok) {
-            sendJson(res, 200, result.plan);
-            return;
-        }
-        switch (result.reason) {
-            case 'not-found':
-                sendJson(res, 404, { error: result.message });
-                return;
-            case 'not-done':
-            case 'already-archived':
-            case 'destination-exists':
-                sendJson(res, 409, { error: result.message });
-                return;
-            default:
-                // fs-error: a safe, fixed message — never leak internals.
-                sendJson(res, 500, { error: 'Failed to archive plan.' });
-        }
-    })
-        .catch(() => {
-        sendJson(res, 500, { error: 'Failed to archive plan.' });
-    });
-    return true;
-};
-/** Handles the built-in read-only API. Returns `true` when the request matched. */
-const handleApi = (res, root, pathname) => {
-    try {
-        if (pathname === '/api/plans' || pathname === '/api/plans/') {
-            sendJson(res, 200, (0, workspace_model_1.getWorkspaceModel)(root).plans);
-            return true;
-        }
-        if (pathname === '/api/config' || pathname === '/api/config/') {
-            sendJson(res, 200, (0, workspace_model_1.getConfig)(root));
-            return true;
-        }
-        if (pathname === '/api/capabilities' || pathname === '/api/capabilities/') {
-            sendJson(res, 200, { selfReview: (0, self_review_1.isSelfReviewAvailable)(), project: deriveProject(root) });
-            return true;
-        }
-        if (/^\/api\/plans\/[^/]+\/?$/.test(pathname)) {
-            const key = parsePlanId(pathname);
-            if (key === null) {
-                sendJson(res, 404, { error: 'Invalid plan id' });
-                return true;
-            }
-            const detail = (0, workspace_model_1.getPlanDetail)(root, key);
-            if (!detail) {
-                sendJson(res, 404, { error: `Plan ${key} not found` });
-                return true;
-            }
-            sendJson(res, 200, detail);
-            return true;
-        }
-        return false;
-    }
-    catch (err) {
-        // Malformed workspace data: concise message, never a raw stack trace.
-        sendJson(res, 500, {
-            error: `Failed to read workspace: ${err instanceof Error ? err.message : String(err)}`,
-        });
-        return true;
-    }
-};
 /**
  * Max accepted request-body size (bytes). The self-review body is tiny JSON,
  * but the config-write route carries whole markdown files, which can exceed
  * 64 KiB once edited — so the cap is 1 MiB.
  */
 const MAX_BODY_BYTES = 1024 * 1024;
-/** Reads and JSON-parses a request body, rejecting oversized or malformed input. */
+/** A body-reading failure that already knows its HTTP status. */
+class BodyError extends Error {
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
+/**
+ * Reads and JSON-parses a request body. Rejects with a {@link BodyError}: `413`
+ * when the declared or actual size exceeds {@link MAX_BODY_BYTES}, `400` when
+ * the body is empty or not JSON. An oversized body is answered, not reset, so
+ * the client sees the `413`; Node drains the remainder after the response.
+ */
 const readJsonBody = (req) => new Promise((resolve, reject) => {
+    const tooLarge = new BodyError(413, 'Request body too large');
+    const declared = Number(req.headers['content-length']);
+    if (Number.isFinite(declared) && declared > MAX_BODY_BYTES) {
+        reject(tooLarge);
+        return;
+    }
     let size = 0;
+    let failed = false;
     const chunks = [];
     req.on('data', (chunk) => {
+        if (failed)
+            return;
         size += chunk.length;
         if (size > MAX_BODY_BYTES) {
-            reject(new Error('Request body too large'));
-            req.destroy();
+            failed = true;
+            chunks.length = 0;
+            reject(tooLarge);
             return;
         }
         chunks.push(chunk);
     });
     req.on('end', () => {
+        if (failed)
+            return;
         const raw = Buffer.concat(chunks).toString('utf8').trim();
         if (raw === '') {
-            resolve({});
+            reject(new BodyError(400, 'Request body must be a JSON document'));
             return;
         }
         try {
             resolve(JSON.parse(raw));
         }
         catch {
-            reject(new Error('Invalid JSON body'));
+            reject(new BodyError(400, 'Invalid JSON body'));
         }
     });
     req.on('error', reject);
 });
+const bodyErrorStatus = (err) => (err instanceof BodyError ? err.status : 500);
+const READ_METHODS = ['GET', 'HEAD'];
+/** Malformed workspace data is a concise `500`, never a stack trace. */
+const sendReadFailure = (res, err) => {
+    sendJson(res, 500, {
+        error: `Failed to read workspace: ${err instanceof Error ? err.message : String(err)}`,
+    });
+};
+/** Wraps a synchronous workspace read as a `200` JSON route. */
+const readRoute = (read) => (_req, res, ctx) => {
+    let body;
+    try {
+        body = read(ctx);
+    }
+    catch (err) {
+        sendReadFailure(res, err);
+        return;
+    }
+    sendJson(res, 200, body);
+};
+const handlePlanDetail = (_req, res, ctx) => {
+    const key = parsePlanId(ctx.pathname);
+    if (key === null) {
+        sendJson(res, 404, { error: 'Invalid plan id' });
+        return;
+    }
+    let detail;
+    try {
+        detail = (0, workspace_model_1.getPlanDetail)(ctx.root, key);
+    }
+    catch (err) {
+        sendReadFailure(res, err);
+        return;
+    }
+    if (!detail) {
+        sendJson(res, 404, { error: `Plan ${key} not found` });
+        return;
+    }
+    sendJson(res, 200, detail);
+};
+/**
+ * Handles `POST /api/plans/:id/archive`: delegates entirely to the {@link
+ * archivePlan} operation and maps its discriminated result to status codes
+ * without duplicating validation. A JSON body is required; `{}` is enough.
+ */
+const handleArchive = (req, res, ctx) => {
+    const key = parseArchivePlanId(ctx.pathname);
+    if (key === null) {
+        sendJson(res, 400, { error: 'Invalid plan id.' });
+        return;
+    }
+    readJsonBody(req)
+        .then(() => (0, archive_1.archivePlan)(ctx.root, key))
+        .then(result => {
+        if (result.ok) {
+            sendJson(res, 200, result.plan);
+            return;
+        }
+        switch (result.reason) {
+            case 'not-found':
+                sendJson(res, 404, { error: result.message });
+                return;
+            case 'not-done':
+            case 'already-archived':
+            case 'destination-exists':
+                sendJson(res, 409, { error: result.message });
+                return;
+            default:
+                // fs-error: a safe, fixed message — never leak internals.
+                sendJson(res, 500, { error: 'Failed to archive plan.' });
+        }
+    })
+        .catch((err) => {
+        const status = bodyErrorStatus(err);
+        sendError(res, status, {
+            error: err instanceof BodyError ? err.message : 'Failed to archive plan.',
+        });
+    });
+};
 /**
  * Handles `POST /api/self-review`: launches the external self-review binary for
- * the requested plan path. Returns `true` once it has owned the response.
+ * the requested plan path.
  */
-const handleSelfReview = (req, res, root) => {
+const handleSelfReview = (req, res, ctx) => {
     readJsonBody(req)
         .then(body => {
         const clientPath = body.path;
-        const result = (0, self_review_1.launchSelfReview)(root, typeof clientPath === 'string' ? clientPath : '');
-        sendJson(res, result.status, result.body);
+        return (0, self_review_1.launchSelfReview)(ctx.root, typeof clientPath === 'string' ? clientPath : '', ctx.selfReviewDeps);
+    })
+        .then(result => {
+        sendJson(res, result.status, result.body, result.headers);
     })
         .catch((err) => {
-        sendJson(res, 400, { ok: false, error: err.message });
+        sendError(res, bodyErrorStatus(err), {
+            ok: false,
+            error: err instanceof Error ? err.message : 'Failed to launch self-review.',
+        });
     });
-    return true;
 };
 /** Parses `/api/config/:kind/:id` -> `{ kind, id }`, or `null` if malformed. */
 const parseConfigTarget = (pathname) => {
@@ -301,14 +457,13 @@ const parseConfigTarget = (pathname) => {
  * Handles `PUT /api/config/:kind/:id`: reads `{ content }` from the JSON body,
  * delegates to the {@link writeConfigFile} guard, and maps its discriminated
  * result to status codes. On success returns the refreshed config slice so the
- * client can update without a second fetch. Returns `true` once it owns the
- * response.
+ * client can update without a second fetch.
  */
-const handleConfigWrite = (req, res, root, pathname) => {
-    const target = parseConfigTarget(pathname);
+const handleConfigWrite = (req, res, ctx) => {
+    const target = parseConfigTarget(ctx.pathname);
     if (!target) {
         sendJson(res, 400, { error: 'Invalid config path.' });
-        return true;
+        return;
     }
     readJsonBody(req)
         .then(body => {
@@ -317,9 +472,9 @@ const handleConfigWrite = (req, res, root, pathname) => {
             sendJson(res, 400, { error: 'Request body must include string "content".' });
             return;
         }
-        return (0, config_write_1.writeConfigFile)(root, target.kind, target.id, content).then(result => {
+        return (0, config_write_1.writeConfigFile)(ctx.root, target.kind, target.id, content).then(result => {
             if (result.ok) {
-                sendJson(res, 200, (0, workspace_model_1.getConfig)(root));
+                sendJson(res, 200, (0, workspace_model_1.getConfig)(ctx.root));
                 return;
             }
             switch (result.reason) {
@@ -337,13 +492,135 @@ const handleConfigWrite = (req, res, root, pathname) => {
         });
     })
         .catch((err) => {
-        sendJson(res, 400, { error: err.message });
+        sendError(res, bodyErrorStatus(err), {
+            error: err instanceof BodyError ? err.message : 'Failed to write config file.',
+        });
     });
-    return true;
 };
-/** Streams a static file with an appropriate content type. */
+/**
+ * The built-in API, most specific paths first. A path is matched before its
+ * method is checked, so a known path with the wrong method is a `405` and a
+ * mutation path can never fall through to a read handler.
+ */
+const API_ROUTES = [
+    {
+        pattern: /^\/api\/plans\/?$/,
+        methods: READ_METHODS,
+        handle: readRoute(ctx => (0, workspace_model_1.getPlanSummaries)(ctx.root)),
+    },
+    {
+        pattern: /^\/api\/config\/?$/,
+        methods: READ_METHODS,
+        handle: readRoute(ctx => (0, workspace_model_1.getConfig)(ctx.root)),
+    },
+    {
+        pattern: /^\/api\/capabilities\/?$/,
+        methods: READ_METHODS,
+        handle: readRoute(ctx => ({
+            selfReview: (0, self_review_1.isSelfReviewAvailable)(),
+            project: deriveProject(ctx.root),
+        })),
+    },
+    {
+        pattern: /^\/api\/events\/?$/,
+        methods: ['GET'],
+        handle: (req, res, ctx) => {
+            ctx.events.apiHandler(req, res, { pathname: ctx.pathname });
+        },
+    },
+    {
+        // Capability bootstrap: the only response that ever carries the token. A
+        // cross-origin page cannot read it (no CORS headers), a cross-site fetch is
+        // refused outright, and the Host guard already stopped DNS rebinding.
+        pattern: /^\/api\/session\/?$/,
+        methods: ['GET'],
+        sameOrigin: true,
+        handle: (_req, res, ctx) => {
+            sendJson(res, 200, { token: ctx.guard.capability }, { 'Cache-Control': 'no-store' });
+        },
+    },
+    {
+        pattern: /^\/api\/plans\/[^/]+\/archive\/?$/,
+        methods: ['POST'],
+        mutation: true,
+        requiresJson: true,
+        handle: handleArchive,
+    },
+    {
+        pattern: /^\/api\/self-review\/?$/,
+        methods: ['POST'],
+        mutation: true,
+        requiresJson: true,
+        handle: handleSelfReview,
+    },
+    {
+        pattern: /^\/api\/config\/[^/]+\/[^/]+\/?$/,
+        methods: ['PUT'],
+        mutation: true,
+        requiresJson: true,
+        handle: handleConfigWrite,
+    },
+    { pattern: /^\/api\/plans\/[^/]+\/?$/, methods: READ_METHODS, handle: handlePlanDetail },
+];
+/**
+ * Routes a guarded `/api/*` request through {@link API_ROUTES}. Check order,
+ * after the Host guard that already ran: path, method, Origin and fetch
+ * metadata, capability, media type, then the handler — which is the first thing
+ * to read the body, touch a file, or launch a process.
+ */
+const routeApi = (req, res, ctx) => {
+    const route = API_ROUTES.find(candidate => candidate.pattern.test(ctx.pathname));
+    if (!route) {
+        sendJson(res, 404, { error: `Unknown API route: ${ctx.pathname}` });
+        return;
+    }
+    if (!route.methods.includes(req.method ?? '')) {
+        sendJson(res, 405, { error: 'Method not allowed.' }, { Allow: route.methods.join(', ') });
+        return;
+    }
+    const rejection = (route.sameOrigin || route.mutation ? guardSameOrigin(req, ctx.guard) : null) ??
+        (route.mutation ? guardCapability(req, ctx.guard) : null);
+    if (rejection && !rejection.ok) {
+        sendJson(res, rejection.status, rejection.body, rejection.headers);
+        return;
+    }
+    if (route.requiresJson && !isJson(req)) {
+        sendJson(res, 415, { error: 'Content-Type must be application/json.' });
+        return;
+    }
+    route.handle(req, res, ctx);
+};
+/**
+ * The Content Security Policy for the SPA, sent on every static response (the
+ * HTML document and its assets; a non-HTML asset ignores it, which is harmless).
+ * Everything the page loads is self-hosted from `dist-web/`, so the baseline is
+ * `'self'`. The exceptions, and why:
+ *
+ * - `style-src 'unsafe-inline'`: CodeMirror 6 injects its `<style>` elements at
+ *   runtime and Mermaid's rendered SVG embeds a `<style>` block, neither of
+ *   which can be hashed ahead of time. Scripts have no such exception: the
+ *   pre-paint theme guard is the self-hosted `/theme-guard.js`, not an inline
+ *   block, so `script-src` stays `'self'` with no hash and no `unsafe-eval`.
+ * - `img-src data:`: the markdown sanitizer admits bounded `data:image/*`
+ *   images; remote image sources are already stripped there.
+ * - `connect-src 'self'`: the `/api/*` fetches and the `/api/events`
+ *   EventSource are same-origin.
+ * - `object-src`, `base-uri`, `form-action`: `'none'` — the page embeds no
+ *   plugins, sets no base URL, and submits no forms (the sanitizer removes
+ *   authored `<form>`s; this makes a surviving one unable to post anywhere).
+ * - `frame-ancestors 'none'`: the viewer is never embedded. This directive only
+ *   works in the header form, which is why the policy is a header and not a
+ *   `<meta http-equiv>`.
+ */
+exports.CONTENT_SECURITY_POLICY = "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; " +
+    "img-src 'self' data:; font-src 'self'; connect-src 'self'; object-src 'none'; " +
+    "base-uri 'none'; form-action 'none'; frame-ancestors 'none'";
+/** Streams a static file with an appropriate content type and the CSP. */
 const sendFile = (res, filePath) => {
-    res.writeHead(200, { 'Content-Type': mimeFor(filePath) });
+    res.writeHead(200, {
+        'Content-Type': mimeFor(filePath),
+        'Content-Security-Policy': exports.CONTENT_SECURITY_POLICY,
+    });
     const stream = fs.createReadStream(filePath);
     stream.on('error', () => {
         if (!res.headersSent)
@@ -356,7 +633,8 @@ const ASSETS_MISSING_MESSAGE = 'Web assets not found. Build the web app first (e
 /** Serves the SPA: a real file under the assets root, else the index fallback. */
 const handleStatic = (res, assetsDir, pathname) => {
     const indexFile = path.join(assetsDir, 'index.html');
-    // Resolve the request path under assetsDir and guard against traversal.
+    // Resolve the request path under assetsDir and guard against traversal. The
+    // guard already proved `pathname` decodes; a throw here is a 400 upstream.
     const relative = decodeURIComponent(pathname).replace(/^\/+/, '');
     const resolved = path.resolve(assetsDir, relative);
     const assetsRoot = path.resolve(assetsDir);
@@ -417,60 +695,149 @@ const openBrowser = (url) => {
         /* non-fatal */
     }
 };
+// ---------------------------------------------------------------------------
+// Server
+// ---------------------------------------------------------------------------
+const DEFAULT_HOST = '127.0.0.1';
+const IPV6_LOOPBACK = '::1';
+/** `host:port` as a browser writes it in `Host`, bracketing IPv6 literals. */
+const authorityOf = (address, port) => `${address.includes(':') ? `[${address}]` : address}:${port}`;
+const WILDCARD_ADDRESSES = new Set(['0.0.0.0', '::']);
+const isLoopbackAddress = (address) => address === IPV6_LOOPBACK || address.startsWith('127.') || address.startsWith('::ffff:127.');
+exports.isLoopbackAddress = isLoopbackAddress;
+/**
+ * IP addresses a browser may name in `Host` for a server bound to `bound`. A
+ * wildcard bind accepts the machine's interface addresses as read at startup
+ * (IPv4 only for `0.0.0.0`). Link-local IPv6 is skipped: a browser cannot put a
+ * zone id in `Host`. Only IP literals are accepted because they cannot be
+ * DNS-rebound; `localhost` is added by the caller.
+ */
+const hostAddressesFor = (bound, interfaces = os.networkInterfaces()) => {
+    if (!WILDCARD_ADDRESSES.has(bound))
+        return [bound];
+    const addresses = new Set();
+    for (const infos of Object.values(interfaces)) {
+        for (const info of infos ?? []) {
+            if (info.family === 'IPv6' && (bound === '0.0.0.0' || info.address.startsWith('fe80:'))) {
+                continue;
+            }
+            addresses.add(info.address);
+        }
+    }
+    return [...addresses];
+};
+exports.hostAddressesFor = hostAddressesFor;
 /**
  * Creates and starts the HTTP server, resolving with the bound URL once it is
  * listening. Rejects only on a genuine listen/bind error.
  */
-const startServer = (opts) => {
+const startServer = async (opts) => {
     const extraHandlers = opts.apiHandlers ?? [];
     const events = new events_1.EventsHub(opts.root, opts.debounceMs);
-    const server = http.createServer((req, res) => {
-        const pathname = new url_1.URL(req.url ?? '/', 'http://localhost').pathname;
+    // One capability per start; it lives in this closure and leaves the process
+    // only through `GET /api/session` (and the test-only handle field).
+    const capability = crypto.randomBytes(32).toString('base64url');
+    // `allowedHosts` is filled in once `listen` resolves (port 0 is ephemeral);
+    // empty until then, which refuses everything — no request can arrive before
+    // that anyway.
+    const guardContext = { allowedHosts: new Set(), capability };
+    // One launch registry per instance, so self-review admission is bounded for
+    // this server's lifetime; a test-supplied registry still wins.
+    const selfReviewDeps = { registry: (0, self_review_1.createLaunchRegistry)(), ...opts.selfReviewDeps };
+    const handleRequest = (req, res) => {
+        const guard = (0, exports.guardRequest)(req, guardContext);
+        if (!guard.ok) {
+            sendJson(res, guard.status, guard.body, guard.headers);
+            return;
+        }
+        const { pathname } = guard;
         if (pathname.startsWith('/api/')) {
             for (const handler of extraHandlers) {
                 if (handler(req, res, { root: opts.root, pathname }))
                     return;
             }
-            // The one sanctioned workspace mutation: archive a done plan.
-            if (req.method === 'POST' && /^\/api\/plans\/[^/]+\/archive\/?$/.test(pathname)) {
-                if (handleArchive(res, opts.root, pathname))
-                    return;
-            }
-            // The one write-ish endpoint: launch the external self-review binary.
-            if (req.method === 'POST' && /^\/api\/self-review\/?$/.test(pathname)) {
-                if (handleSelfReview(req, res, opts.root))
-                    return;
-            }
-            // The second sanctioned workspace mutation: overwrite a config file.
-            if (req.method === 'PUT' && /^\/api\/config\/[^/]+\/[^/]+\/?$/.test(pathname)) {
-                if (handleConfigWrite(req, res, opts.root, pathname))
-                    return;
-            }
-            // Built-in SSE change stream.
-            if (events.apiHandler(req, res, { pathname }))
-                return;
-            if (handleApi(res, opts.root, pathname))
-                return;
-            sendJson(res, 404, { error: `Unknown API route: ${pathname}` });
+            routeApi(req, res, {
+                root: opts.root,
+                pathname,
+                events,
+                guard: guardContext,
+                selfReviewDeps,
+            });
+            return;
+        }
+        if (!READ_METHODS.includes(req.method)) {
+            sendJson(res, 405, { error: 'Method not allowed.' }, { Allow: READ_METHODS.join(', ') });
             return;
         }
         handleStatic(res, opts.assetsDir, pathname);
+    };
+    // The one exception boundary: a throw anywhere in the synchronous path is a
+    // bounded error response, never a dead process. Async handlers own their own
+    // `.catch`, each of which ends in `sendError`.
+    const server = http.createServer((req, res) => {
+        try {
+            handleRequest(req, res);
+        }
+        catch (err) {
+            sendError(res, err instanceof URIError ? 400 : 500, {
+                error: err instanceof URIError ? 'Bad request.' : 'Internal server error.',
+            });
+        }
+    });
+    // Requests the HTTP parser itself rejects get a minimal 400 and a closed socket.
+    server.on('clientError', (err, socket) => {
+        if (err.code === 'ECONNRESET' || !socket.writable) {
+            socket.destroy();
+            return;
+        }
+        socket.end('HTTP/1.1 400 Bad Request\r\nConnection: close\r\n\r\n');
     });
     // Tear the watcher and open client streams down with the server.
     server.on('close', () => events.close());
-    return new Promise((resolve, reject) => {
-        server.once('error', reject);
-        server.listen(opts.port, () => {
-            server.removeListener('error', reject);
-            const address = server.address();
-            const boundPort = typeof address === 'object' && address ? address.port : opts.port;
-            const url = `http://localhost:${boundPort}`;
-            events.start();
-            if (opts.open)
-                openBrowser(url);
-            resolve({ url, server, port: boundPort, events });
+    const listenOn = (host) => new Promise((resolve, reject) => {
+        const onError = (err) => reject(err);
+        server.once('error', onError);
+        server.listen(opts.port, host, () => {
+            server.removeListener('error', onError);
+            resolve();
         });
     });
+    const preferred = opts.host ?? DEFAULT_HOST;
+    try {
+        await listenOn(preferred);
+    }
+    catch (err) {
+        const code = err.code;
+        if (preferred !== DEFAULT_HOST || code !== 'EADDRNOTAVAIL')
+            throw err;
+        await listenOn(IPV6_LOOPBACK);
+    }
+    const address = server.address();
+    if (!address || typeof address === 'string') {
+        server.close();
+        throw new Error('Server did not bind a TCP address.');
+    }
+    const boundPort = address.port;
+    const authorities = (0, exports.hostAddressesFor)(address.address).map(a => authorityOf(a, boundPort));
+    // `127.0.0.1` and `localhost` are always allowed; IPv6 and non-loopback
+    // authorities only where the server listens. Lower-cased to match the guard.
+    guardContext.allowedHosts = new Set([...authorities, `${DEFAULT_HOST}:${boundPort}`, `localhost:${boundPort}`].map(a => a.toLowerCase()));
+    // A wildcard bind is opened locally through IPv4 loopback.
+    const url = WILDCARD_ADDRESSES.has(address.address)
+        ? `http://${authorityOf(DEFAULT_HOST, boundPort)}`
+        : `http://${authorityOf(address.address, boundPort)}`;
+    events.start();
+    if (opts.open)
+        openBrowser(url);
+    return {
+        url,
+        server,
+        port: boundPort,
+        exposed: !(0, exports.isLoopbackAddress)(address.address),
+        reachableUrls: authorities.map(a => `http://${a}`),
+        events,
+        capability,
+    };
 };
 exports.startServer = startServer;
 //# sourceMappingURL=server.js.map