strikethroo 4.0.0 → 4.1.0

package/dist/serve/self-review.js

@@ -15,6 +15,12 @@
  * Untrusted input (the path string) is never passed to the shell: `spawn` is
  * invoked with an argv array, and the path is rejected before spawning unless it
  * resolves to an existing file under `plans/` or `archive/`. Node built-ins only.
+ *
+ * Launches are bounded: a {@link LaunchRegistry} tracks the plans whose child is
+ * still running, refusing a duplicate for the same plan and anything past
+ * {@link MAX_CONCURRENT_SELF_REVIEWS}. The registry is in-memory and per server
+ * instance: a restart resets the accounting, and the detached children — which
+ * the viewer never waits on — can outlive it. It is not a job manager.
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
@@ -50,12 +56,17 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.launchSelfReview = exports.resolveReviewPath = exports.isSelfReviewAvailable = exports.SELF_REVIEW_URL = exports.SELF_REVIEW_BINARY = void 0;
+exports.launchSelfReview = exports.resolveReviewPath = exports.createLaunchRegistry = exports.isSelfReviewAvailable = exports.SELF_REVIEW_URL = exports.MAX_CONCURRENT_SELF_REVIEWS = exports.SELF_REVIEW_BINARY = void 0;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const child_process_1 = require("child_process");
+const safe_fs_1 = require("../skill-scripts/shared/safe-fs");
 /** The binary name looked up on PATH and spawned. */
 exports.SELF_REVIEW_BINARY = 'self-review';
+/** Upper bound on self-review children running at once per server instance. */
+exports.MAX_CONCURRENT_SELF_REVIEWS = 2;
+/** Seconds a client should wait before retrying a `429` launch. */
+const BUSY_RETRY_AFTER_SECONDS = 30;
 /** Where to obtain self-review; surfaced by the SPA when it is not installed. */
 exports.SELF_REVIEW_URL = 'https://github.com/e0ipso/self-review';
 /** Cache key derived from the environment inputs that affect the PATH scan. */
@@ -104,13 +115,21 @@ const isSelfReviewAvailable = (env = process.env) => {
     return result;
 };
 exports.isSelfReviewAvailable = isSelfReviewAvailable;
-/** Spawns the binary detached and unref'd so it outlives the request. */
-const spawnDetached = (command, args) => {
-    const child = (0, child_process_1.spawn)(command, args, { stdio: 'ignore', detached: true });
-    child.on('error', () => {
-        /* a failed launch must not crash the server */
-    });
-    child.unref();
+/** Creates an empty {@link LaunchRegistry}. */
+const createLaunchRegistry = () => new Set();
+exports.createLaunchRegistry = createLaunchRegistry;
+/** Fallback registry for callers that do not own one (tests pass their own). */
+const defaultRegistry = (0, exports.createLaunchRegistry)();
+/** Spawns the binary detached with no stdio so it can outlive the request. */
+const spawnDetached = (command, args) => (0, child_process_1.spawn)(command, args, { stdio: 'ignore', detached: true });
+/** Resolves once the child reports `spawn`; rejects on a launch `error`. */
+const awaitSpawn = (child) => new Promise((resolve, reject) => {
+    child.once('spawn', () => resolve());
+    child.once('error', (err) => reject(err));
+});
+const LAUNCH_FAILED = {
+    status: 500,
+    body: { ok: false, error: 'Failed to launch self-review.' },
 };
 /**
  * Resolves a client-supplied plan path to an absolute path, requiring it to be
@@ -120,40 +139,56 @@ const spawnDetached = (command, args) => {
  * `root` is the absolute `.ai/strikethroo` directory; client paths are the
  * workspace-relative form the SPA shows (e.g. `.ai/strikethroo/plans/NN--s/…`),
  * so they are resolved against the project root (`root/../..`). Absolute client
- * paths are accepted too — the containment check is what enforces safety.
+ * paths are accepted too — the containment check is what enforces safety: the
+ * lexical check below picks the subtree, and the shared helper walks the real
+ * components so a symlinked plan file or directory is refused rather than
+ * followed out of the workspace.
  */
 const resolveReviewPath = (root, clientPath) => {
     if (typeof clientPath !== 'string' || clientPath.trim() === '') {
         return { error: 'A plan path is required.', status: 400 };
     }
-    const projectRoot = path.resolve(root, '..', '..');
+    const absRoot = path.resolve(root);
+    const projectRoot = path.resolve(absRoot, '..', '..');
     const resolved = path.resolve(projectRoot, clientPath);
-    const plansDir = path.join(root, 'plans');
-    const archiveDir = path.join(root, 'archive');
-    const within = (dir) => resolved === dir || resolved.startsWith(dir + path.sep);
-    if (!within(plansDir) && !within(archiveDir)) {
-        return {
-            error: 'Plan path must be inside the workspace plans/ or archive/ directory.',
-            status: 400,
-        };
+    const rel = path.relative(absRoot, resolved);
+    const first = rel.split(path.sep)[0];
+    const outside = {
+        error: 'Plan path must be inside the workspace plans/ or archive/ directory.',
+        status: 400,
+    };
+    if (path.isAbsolute(rel) || first === '..' || (first !== 'plans' && first !== 'archive')) {
+        return outside;
     }
-    try {
-        if (!fs.statSync(resolved).isFile()) {
-            return { error: 'Plan path does not point to a file.', status: 404 };
+    const contained = (0, safe_fs_1.resolveContained)(absRoot, rel);
+    if ('error' in contained) {
+        switch (contained.error) {
+            case 'not-found':
+                return { error: 'Plan file not found.', status: 404 };
+            case 'not-a-file':
+            case 'not-a-directory':
+                return { error: 'Plan path does not point to a file.', status: 404 };
+            case 'fs-error':
+                return { error: 'Plan path could not be inspected.', status: 500 };
+            default:
+                // invalid-path, outside-root, symlink: the path does not denote a plain
+                // file inside the workspace.
+                return outside;
         }
     }
-    catch {
-        return { error: 'Plan file not found.', status: 404 };
-    }
     return { absPath: resolved };
 };
 exports.resolveReviewPath = resolveReviewPath;
 /**
- * Validates `clientPath` and, if the binary is available, launches
- * `self-review <absolutePath>` detached. Pure of HTTP concerns: returns the
- * status/body the endpoint should send so it stays unit-testable.
+ * Validates `clientPath` and, if the binary is available and a slot is free,
+ * launches `self-review <absolutePath>` detached. Resolves `200` only after the
+ * child's `spawn` event; a launch `error` (e.g. `ENOENT`) is a fixed `500`. The
+ * plan's slot is taken synchronously before the spawn, so two simultaneous
+ * requests for one plan cannot both launch, and is released — idempotently —
+ * when the child exits, errors, or fails to launch. Pure of HTTP concerns:
+ * returns the status/body the endpoint should send so it stays unit-testable.
  */
-const launchSelfReview = (root, clientPath, deps = {}) => {
+const launchSelfReview = async (root, clientPath, deps = {}) => {
     const available = deps.available ?? exports.isSelfReviewAvailable;
     if (!available()) {
         return {
@@ -165,15 +200,40 @@ const launchSelfReview = (root, clientPath, deps = {}) => {
     if ('error' in resolved) {
         return { status: resolved.status, body: { ok: false, error: resolved.error } };
     }
-    try {
-        (deps.spawnDetached ?? spawnDetached)(exports.SELF_REVIEW_BINARY, [resolved.absPath]);
+    const registry = deps.registry ?? defaultRegistry;
+    const key = resolved.absPath;
+    if (registry.has(key)) {
+        return {
+            status: 409,
+            body: { ok: false, error: 'A self-review is already running for this plan.' },
+        };
     }
-    catch (err) {
+    if (registry.size >= exports.MAX_CONCURRENT_SELF_REVIEWS) {
         return {
-            status: 500,
-            body: { ok: false, error: `Failed to launch self-review: ${err.message}` },
+            status: 429,
+            body: {
+                ok: false,
+                error: `Too many self-reviews are running (limit ${exports.MAX_CONCURRENT_SELF_REVIEWS}). Try again when one finishes.`,
+            },
+            headers: { 'Retry-After': String(BUSY_RETRY_AFTER_SECONDS) },
         };
     }
+    registry.add(key);
+    const release = () => {
+        registry.delete(key);
+    };
+    let child;
+    try {
+        child = (deps.spawn ?? spawnDetached)(exports.SELF_REVIEW_BINARY, [key]);
+        await awaitSpawn(child);
+    }
+    catch {
+        release();
+        return LAUNCH_FAILED;
+    }
+    child.once('exit', release);
+    child.once('error', release);
+    child.unref();
     return { status: 200, body: { ok: true } };
 };
 exports.launchSelfReview = launchSelfReview;

package/dist/serve/self-review.js.map

@@ -1 +1 @@
-{"version":3,"file":"self-review.js","sourceRoot":"","sources":["../../src/serve/self-review.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"self-review.js","sourceRoot":"","sources":["../../src/serve/self-review.ts"],"names":[],"mappings":"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"}

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"}