strikethroo 4.0.0 → 4.1.1

package/dist/serve/server.d.ts

@@ -13,13 +13,32 @@
  *     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
  * Vite/React/Tailwind imports.
  */
 import * as http from 'http';
+import * as os from 'os';
 import { EventsHub } from './events';
+import { LaunchDeps } from './self-review';
 /** Options for {@link startServer}. */
 export interface ServeOptions {
     /** Absolute path of the `.ai/strikethroo` workspace directory to serve. */
@@ -41,6 +60,17 @@ export interface ServeOptions {
      * module's default; exposed mainly so tests can tighten it.
      */
     debounceMs?: number;
+    /**
+     * IP address to bind. Defaults to `127.0.0.1`, falling back to `::1` when the
+     * platform has no IPv4 loopback. A non-loopback address exposes the viewer to
+     * every peer that can reach it; see {@link ServeHandle.exposed}.
+     */
+    host?: string;
+    /**
+     * Seams for the self-review launcher (availability probe and spawn).
+     * Test-only: lets a suite prove a rejected request launched nothing.
+     */
+    selfReviewDeps?: LaunchDeps;
 }
 /** A pluggable `/api/*` handler. Returns `true` if it handled the request. */
 export type ApiHandler = (req: http.IncomingMessage, res: http.ServerResponse, ctx: {
@@ -52,9 +82,25 @@ export interface ServeHandle {
     url: string;
     server: http.Server;
     port: number;
+    /**
+     * True when the bound address is not loopback. The capability guards against
+     * other web origins, not network peers: any peer that reaches the port can
+     * bootstrap it, so the caller must warn.
+     */
+    exposed: boolean;
+    /** URLs a browser can use, one per accepted IP authority. */
+    reachableUrls: string[];
     /** The SSE change-stream hub backing `GET /api/events`. */
     events: EventsHub;
+    /**
+     * This instance's mutation capability. Test-only: production callers (the
+     * CLI) must never print, log, or persist it; the SPA obtains it from
+     * `GET /api/session`.
+     */
+    capability?: string;
 }
+/** Request header carrying the mutation capability. */
+export declare const CAPABILITY_HEADER = "X-Strikethroo-Capability";
 /**
  * Resolves the default prebuilt SPA assets directory relative to the installed
  * package. The compiled server lives at `<pkg>/dist/serve/server.js`, so the
@@ -62,6 +108,67 @@ export interface ServeHandle {
  * Plan 94 finalizes the shipped asset path; this is the local-dev default.
  */
 export declare const defaultAssetsDir: () => string;
+/** What the request handler knows about the running server; fixed after `listen`. */
+export interface GuardContext {
+    /** Lower-case `host[:port]` authorities this server answers for. */
+    allowedHosts: ReadonlySet<string>;
+    /** The per-start mutation capability (see the module comment). */
+    capability: string;
+}
+/**
+ * Outcome of {@link guardRequest} and the per-route guards: the parsed path to
+ * route, or a complete rejection the caller writes verbatim.
+ */
+export type GuardResult = {
+    ok: true;
+    pathname: string;
+} | {
+    ok: false;
+    status: number;
+    body: unknown;
+    headers?: Record<string, string>;
+};
+/**
+ * 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.
+ */
+export declare const guardRequest: (req: http.IncomingMessage, ctx: GuardContext) => GuardResult;
+/**
+ * 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>`.
+ */
+export declare const CONTENT_SECURITY_POLICY: string;
+export declare const isLoopbackAddress: (address: string) => boolean;
+/**
+ * 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.
+ */
+export declare const hostAddressesFor: (bound: string, interfaces?: ReturnType<typeof os.networkInterfaces>) => string[];
 /**
  * Creates and starts the HTTP server, resolving with the bound URL once it is
  * listening. Rejects only on a genuine listen/bind error.

package/dist/serve/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/serve/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAM7B,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAKrC,uCAAuC;AACvC,MAAM,WAAW,YAAY;IAC3B,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAC;IACb,wEAAwE;IACxE,IAAI,EAAE,MAAM,CAAC;IACb,wDAAwD;IACxD,IAAI,EAAE,OAAO,CAAC;IACd,0DAA0D;IAC1D,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,WAAW,CAAC,EAAE,UAAU,EAAE,CAAC;IAC3B;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,8EAA8E;AAC9E,MAAM,MAAM,UAAU,GAAG,CACvB,GAAG,EAAE,IAAI,CAAC,eAAe,EACzB,GAAG,EAAE,IAAI,CAAC,cAAc,EACxB,GAAG,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,KACpC,OAAO,CAAC;AAEb,uDAAuD;AACvD,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,2DAA2D;IAC3D,MAAM,EAAE,SAAS,CAAC;CACnB;AA0CD;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,QAAO,MAAyD,CAAC;AA0U9F;;;GAGG;AACH,eAAO,MAAM,WAAW,GAAI,MAAM,YAAY,KAAG,OAAO,CAAC,WAAW,CAgDnE,CAAC"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/serve/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAI7B,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AAIzB,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACrC,OAAO,EAIL,UAAU,EACX,MAAM,eAAe,CAAC;AAIvB,uCAAuC;AACvC,MAAM,WAAW,YAAY;IAC3B,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAC;IACb,wEAAwE;IACxE,IAAI,EAAE,MAAM,CAAC;IACb,wDAAwD;IACxD,IAAI,EAAE,OAAO,CAAC;IACd,0DAA0D;IAC1D,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,WAAW,CAAC,EAAE,UAAU,EAAE,CAAC;IAC3B;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,cAAc,CAAC,EAAE,UAAU,CAAC;CAC7B;AAED,8EAA8E;AAC9E,MAAM,MAAM,UAAU,GAAG,CACvB,GAAG,EAAE,IAAI,CAAC,eAAe,EACzB,GAAG,EAAE,IAAI,CAAC,cAAc,EACxB,GAAG,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,KACpC,OAAO,CAAC;AAEb,uDAAuD;AACvD,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,OAAO,EAAE,OAAO,CAAC;IACjB,6DAA6D;IAC7D,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,2DAA2D;IAC3D,MAAM,EAAE,SAAS,CAAC;IAClB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,uDAAuD;AACvD,eAAO,MAAM,iBAAiB,6BAA6B,CAAC;AA0C5D;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,QAAO,MAAyD,CAAC;AAiC9F,qFAAqF;AACrF,MAAM,WAAW,YAAY;IAC3B,oEAAoE;IACpE,YAAY,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAClC,kEAAkE;IAClE,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,MAAM,MAAM,WAAW,GACnB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAC9B;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,CAAC;AAYnF;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,GAAI,KAAK,IAAI,CAAC,eAAe,EAAE,KAAK,YAAY,KAAG,WAsB3E,CAAC;AA4bF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,uBAAuB,QAG2B,CAAC;AAkGhE,eAAO,MAAM,iBAAiB,GAAI,SAAS,MAAM,KAAG,OAC0C,CAAC;AAE/F;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,GAC3B,OAAO,MAAM,EACb,aAAY,UAAU,CAAC,OAAO,EAAE,CAAC,iBAAiB,CAA0B,KAC3E,MAAM,EAYR,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,WAAW,GAAU,MAAM,YAAY,KAAG,OAAO,CAAC,WAAW,CAwHzE,CAAC"}