@wrongstack/plugins 0.307.1 → 0.308.0

package/dist/runtime/redos-guard.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Redos guard — run a regex inside a `node:worker_threads` worker so
+ * the host can actually terminate it on a wall-clock budget.
+ *
+ * Why a worker thread?
+ *   A `setTimeout`-based watchdog cannot interrupt a synchronous
+ *   CPU-bound regex in Node.js's single-threaded event loop. The
+ *   `setImmediate`/`setTimeout` race fires whichever wins the next
+ *   event-loop tick; if the regex blocks the loop synchronously for
+ *   7 seconds, the timer has long since fired and the regex still
+ *   returns a result — only after the loop is unblocked does the
+ *   `setImmediate` callback resume and resolve `{ timedOut: false }`.
+ *
+ *   The only honest fix is to run the regex in a separate thread that
+ *   the host can `worker.terminate()`. `node:worker_threads` gives us
+ *   that, and the per-thread cost is amortized by the runtime helper
+ *   itself (the host doesn't pay for the thread except when it
+ *   invokes `withReDoSGuard`).
+ *
+ * Why is this here, not inside each plugin?
+ *   Three plugins (`secret-scanner`, `prompt-firewall`, `path-guard`)
+ *   need the same contract. Three copies would drift; one copy is
+ *   auditable and testable.
+ *
+ * Contract:
+ *   `withReDoSGuard(re, input, ms)` returns:
+ *     { timedOut: false, match: RegExpExecArray | null }   on normal completion
+ *     { timedOut: true,  match: null }                     on timeout
+ */
+export interface ReDoSResult {
+    /** True when the regex did not complete within the wall-clock budget. */
+    timedOut: boolean;
+    /** The match result (groups, indices) when `timedOut === false`; null otherwise. */
+    match: RegExpExecArray | null;
+}
+export interface ReDoSOptions {
+    /** Wall-clock budget in ms. Default 50. */
+    budgetMs?: number;
+    /**
+     * Optional hook invoked exactly once when the budget is exceeded.
+     * Called synchronously after the regex is terminated. Default: no-op.
+     */
+    onTimeout?: (info: {
+        regex: RegExp;
+        input: string;
+        budgetMs: number;
+        elapsedMs: number;
+    }) => void;
+}
+/**
+ * Run `re.exec(input)` inside a worker thread with a wall-clock
+ * watchdog. The worker is terminated when the budget elapses; the
+ * regex cannot keep running.
+ *
+ * Returns a Promise; resolved with `{ timedOut, match }`.
+ */
+export declare function withReDoSGuard(re: RegExp, input: string, budgetMs?: number, options?: ReDoSOptions): Promise<ReDoSResult>;
+/**
+ * Convenience: build a guarded matcher.
+ *
+ * ```ts
+ * const matchCredential = guardedMatcher(/AKIA[0-9A-Z]{16}/g, 25);
+ * const r = await matchCredential(line);
+ * if (r.timedOut) counters.redosTimeouts++;
+ * else if (r.match) report(r.match);
+ * ```
+ */
+export declare function guardedMatcher(re: RegExp, budgetMs?: number, onTimeout?: ReDoSOptions['onTimeout']): (input: string) => Promise<ReDoSResult>;
+//# sourceMappingURL=redos-guard.d.ts.map

package/dist/runtime/sandbox.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Sandbox — canonical project-path validation with symlink resolution.
+ *
+ * Why a new helper when `runtime/index.ts` already exports
+ * `withinProject` and `sanitizeRunnerPath`?
+ *
+ *  - `withinProject` does NOT resolve symlinks: a path like
+ *    `project/link-to-/etc/passwd` reports as inside the project
+ *    even though the resolved target is outside.
+ *  - `sanitizeRunnerPath` is for runner argv (linter binaries),
+ *    not user-supplied tool input. The two paths share the
+ *    leading-dash + length checks but `sanitizeRunnerPath`
+ *    rejects a `cwd` for which it cannot resolve; user-input
+ *    sandbox needs canonicalization instead.
+ *
+ * The previous design (per SAGE memory T-03) relied on three
+ * duplicate `withinProject` copies in `runtime/index.ts`,
+ * `file-watcher/index.ts`, and `path-guard/glob.ts`. They drifted
+ * on edge cases. This helper is the single replacement.
+ *
+ * Contract:
+ *   `safePath(input, projectRoot?)` returns the canonical absolute
+ *   path inside the project on success, or `null` on rejection.
+ *
+ * Rejection cases:
+ *   - empty string
+ *   - length > 4096 bytes (matches `runtime.withinProject`)
+ *   - leading-dash (option smuggling)
+ *   - cannot be resolved (path doesn't exist or EPERM)
+ *   - resolved path escapes the project root
+ *   - symlink target is outside the project
+ */
+export interface SafePathOptions {
+    /**
+     * Project root for the sandbox. Defaults to `process.cwd()`. Pass
+     * the session cwd from the plugin host when available so that
+     * tools running in a subdirectory are scoped to that directory.
+     */
+    projectRoot?: string;
+    /**
+     * If true (default), follow symlinks via `realpathSync`. Set false
+     * for plugins that need to record the literal path the user wrote
+     * (e.g. checkpoint capture, git diff).
+     */
+    followSymlinks?: boolean;
+}
+/**
+ * Resolve `input` to an absolute path inside the project root.
+ *
+ * Returns `null` for empty/oversized/leading-dash inputs and for
+ * paths whose real target escapes the project.
+ */
+export declare function safePath(input: string, options?: SafePathOptions): string | null;
+/**
+ * Boolean convenience for callers that don't need the canonical path.
+ * Equivalent to `safePath(input, options) !== null`.
+ */
+export declare function isInsideProject(input: string, options?: SafePathOptions): boolean;
+//# sourceMappingURL=sandbox.d.ts.map

package/dist/runtime.js

@@ -1,7 +1,7 @@
 // src/runtime/index.ts
 import { execFile } from "node:child_process";
 import { existsSync, readdirSync, statSync } from "node:fs";
-import { basename, extname as extname2, isAbsolute as isAbsolute2, relative as relative2, resolve as resolve2 } from "node:path";
+import { basename, extname as extname2, isAbsolute as isAbsolute3, relative as relative3, resolve as resolve3 } from "node:path";
 
 // src/runtime/llm.ts
 function stripOuterMarkdownFence(text) {
@@ -347,6 +347,162 @@ function releaseHandles(state, keys) {
   }
 }
 
+// src/runtime/redos-guard.ts
+import { Worker } from "node:worker_threads";
+function withReDoSGuard(re, input, budgetMs = 50, options = {}) {
+  const opts = { budgetMs, ...options };
+  const start = Date.now();
+  const workerSource = buildWorkerSource(re.source, input, re.flags);
+  const worker = new Worker(workerSource, {
+    eval: true,
+    name: `redos-guard:${re.source.slice(0, 32)}`
+  });
+  return new Promise((resolve4) => {
+    let settled = false;
+    const onMessage = (msg) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      worker.terminate().catch(() => {
+      });
+      if (!msg.ok) {
+        resolve4({ timedOut: true, match: null });
+        return;
+      }
+      resolve4({ timedOut: false, match: msg.match });
+    };
+    const onError = () => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      worker.terminate().catch(() => {
+      });
+      resolve4({ timedOut: true, match: null });
+    };
+    const timer = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      const elapsedMs = Date.now() - start;
+      worker.terminate().catch(() => {
+      });
+      try {
+        opts.onTimeout?.({
+          regex: re,
+          input,
+          budgetMs: opts.budgetMs,
+          elapsedMs
+        });
+      } catch {
+      }
+      resolve4({ timedOut: true, match: null });
+    }, opts.budgetMs);
+    timer.unref?.();
+    worker.on("message", onMessage);
+    worker.on("error", onError);
+  });
+}
+function buildWorkerSource(source, input, flags) {
+  const S = JSON.stringify(source);
+  const I = JSON.stringify(input);
+  const F = JSON.stringify(flags);
+  return `
+const { parentPort } = require('node:worker_threads');
+const source = ${S};
+const input = ${I};
+const flags = ${F};
+try {
+  const re = new RegExp(source, flags);
+  const match = re.exec(input);
+  // parentPort.postMessage, NOT bare postMessage: with eval:true
+  // workers this Node version does not expose the bare postMessage
+  // global \u2014 the worker throws ReferenceError at startup and the
+  // host misreads it as a timeout (positive-path regression).
+  parentPort.postMessage({ ok: true, match });
+} catch (err) {
+  parentPort.postMessage({ ok: false, error: err && err.message ? err.message : String(err) });
+}
+`;
+}
+function guardedMatcher(re, budgetMs = 50, onTimeout) {
+  return (input) => withReDoSGuard(re, input, budgetMs, onTimeout ? { onTimeout } : {});
+}
+
+// src/runtime/sandbox.ts
+import { realpathSync } from "node:fs";
+import { isAbsolute as isAbsolute2, relative as relative2, resolve as resolve2 } from "node:path";
+var MAX_PATH_BYTES = 4096;
+function safePath(input, options = {}) {
+  if (typeof input !== "string") return null;
+  if (input.length === 0 || input.length > MAX_PATH_BYTES) return null;
+  if (input.startsWith("-")) return null;
+  const projectRoot = resolve2(options.projectRoot ?? process.cwd());
+  const lexical = isAbsolute2(input) ? resolve2(input) : resolve2(projectRoot, input);
+  if (!withinLexical(projectRoot, lexical)) return null;
+  if (options.followSymlinks !== false) {
+    let real;
+    try {
+      real = realpathSync(lexical);
+    } catch {
+      return null;
+    }
+    if (!withinLexical(projectRoot, real)) return null;
+    return real;
+  }
+  return lexical;
+}
+function withinLexical(projectRoot, candidate) {
+  const rel = relative2(projectRoot, candidate);
+  if (rel === "" || rel === ".") return true;
+  if (rel.startsWith("..")) return false;
+  if (isAbsolute2(rel)) return false;
+  return true;
+}
+function isInsideProject(input, options = {}) {
+  return safePath(input, options) !== null;
+}
+
+// src/runtime/h1-state.ts
+function createH1State(initial) {
+  const handles = /* @__PURE__ */ new Map();
+  const safeRelease = (unregister) => {
+    try {
+      unregister();
+    } catch {
+    }
+  };
+  return {
+    state: initial,
+    register(key, unregister) {
+      const prior = handles.get(key);
+      if (prior) {
+        safeRelease(prior);
+        handles.delete(key);
+      }
+      if (unregister) {
+        handles.set(key, unregister);
+      }
+    },
+    release(key) {
+      const prior = handles.get(key);
+      if (!prior) return;
+      handles.delete(key);
+      safeRelease(prior);
+    },
+    releaseAll() {
+      for (const unregister of handles.values()) {
+        safeRelease(unregister);
+      }
+      handles.clear();
+    },
+    size() {
+      return handles.size;
+    },
+    keys() {
+      return [...handles.keys()];
+    }
+  };
+}
+
 // src/runtime/index.ts
 var META_CHARS = /["'`;&|<>\r\n]/;
 var MAX_BUFFER_BYTES = 16 * 1024 * 1024;
@@ -361,9 +517,9 @@ function safeSplit(command) {
 function withinProjectPath(projectRoot, candidate) {
   if (candidate.length === 0 || candidate.length > 4096) return false;
   if (hasLeadingDash(candidate)) return false;
-  const resolved = isAbsolute2(candidate) ? resolve2(candidate) : resolve2(projectRoot, candidate);
-  const rel = relative2(projectRoot, resolved);
-  return rel === "" || !rel.startsWith("..") && !isAbsolute2(rel);
+  const resolved = isAbsolute3(candidate) ? resolve3(candidate) : resolve3(projectRoot, candidate);
+  const rel = relative3(projectRoot, resolved);
+  return rel === "" || !rel.startsWith("..") && !isAbsolute3(rel);
 }
 function everyFlagAllowed(allowed, args) {
   for (const arg of args) {
@@ -375,14 +531,14 @@ function everyFlagAllowed(allowed, args) {
 }
 function sanitizeRunnerPath(value, options = {}) {
   if (!value || hasLeadingDash(value)) return null;
-  const projectRoot = resolve2(options.projectRoot ?? process.cwd());
+  const projectRoot = resolve3(options.projectRoot ?? process.cwd());
   if (!withinProjectPath(projectRoot, value)) return null;
-  return isAbsolute2(value) ? resolve2(value) : resolve2(projectRoot, value);
+  return isAbsolute3(value) ? resolve3(value) : resolve3(projectRoot, value);
 }
 function resolveRunnerCommand(runtime, command, options = {}) {
   const tokens = safeSplit(command);
   if (!tokens || tokens.length === 0) return null;
-  const projectRoot = resolve2(options.projectRoot ?? process.cwd());
+  const projectRoot = resolve3(options.projectRoot ?? process.cwd());
   const launcher = runtime.packageManager;
   const [head, second, ...rest] = tokens;
   if (!head) return null;
@@ -413,7 +569,7 @@ function resolveRunnerCommand(runtime, command, options = {}) {
       return { cmd: head, args: [second, exe, ...tail], display };
     }
   }
-  if (isAbsolute2(head)) {
+  if (isAbsolute3(head)) {
     if (!withinProjectPath(projectRoot, head)) return null;
     const base = basename(head);
     if (base !== runtime.executable && base !== launcher) return null;
@@ -434,7 +590,7 @@ function runRunnerCommand(argv, options) {
     });
   }
   return new Promise((resolvePromise) => {
-    const projectRoot = resolve2(options.projectRoot ?? process.cwd());
+    const projectRoot = resolve3(options.projectRoot ?? process.cwd());
     const trimmedCwd = options.cwd.trim();
     if (!withinProjectPath(projectRoot, trimmedCwd)) {
       resolvePromise({
@@ -448,6 +604,7 @@ function runRunnerCommand(argv, options) {
     }
     let timedOut = false;
     let spawnErrored = false;
+    const start = Date.now();
     const stdoutChunks = [];
     const stderrChunks = [];
     let stdoutBytes = 0;
@@ -477,6 +634,15 @@ function runRunnerCommand(argv, options) {
         timeout: options.timeoutMs,
         signal: options.signal,
         maxBuffer: MAX_BUFFER_BYTES,
+        // execFile defaults `encoding` to 'utf8', which makes the
+        // stdout/stderr `data` events emit *strings*. The chunk arrays
+        // below are typed Buffer[] and every consumer runs them through
+        // Buffer.concat(...).toString('utf8'), which throws
+        // ERR_INVALID_ARG_TYPE on any non-empty string output. Pin the
+        // streams to buffers so the declared contract holds (regression:
+        // runRunnerCommand crashed on any child that actually wrote
+        // output; only the maxBuffer fixture exercised this path).
+        encoding: "buffer",
         windowsHide: true,
         shell: false,
         ...invocation.windowsVerbatimArguments ? { windowsVerbatimArguments: true } : {}
@@ -505,11 +671,31 @@ function runRunnerCommand(argv, options) {
         }
         if (err) {
           const anyErr = err;
+          if ((anyErr.killed === true || anyErr.signal === "SIGTERM") && // maxBuffer overflow must NOT be misreported as a timeout
+          // — it's a real failure (the child wrote too much) and
+          // downstream callers (type-gate/index.ts:227) return
+          // null on timedOut=true, which would silently swallow
+          // maxBuffer overflow into a confusing empty-output
+          // result. Skip the timeout resolve when the err shape
+          // names maxBuffer explicitly.
+          !/maxBuffer length exceeded/i.test(anyErr.message ?? "") && // And only count it as a timeout if the wall clock has
+          // actually elapsed past the budget. External SIGTERMs and
+          // races against the exit handler don't satisfy this.
+          Date.now() - start >= options.timeoutMs) {
+            resolvePromise({
+              code: null,
+              stdout: Buffer.concat(stdoutChunks).toString("utf-8"),
+              stderr: Buffer.concat(stderrChunks).toString("utf-8"),
+              timedOut: true,
+              spawnError: false
+            });
+            return;
+          }
           const code = typeof anyErr.code === "number" ? anyErr.code : 1;
           resolvePromise({
             code,
-            stdout: Buffer.concat(stdoutChunks).toString("utf8"),
-            stderr: Buffer.concat(stderrChunks).toString("utf8"),
+            stdout: Buffer.concat(stdoutChunks).toString("utf-8"),
+            stderr: Buffer.concat(stderrChunks).toString("utf-8"),
             timedOut: false,
             spawnError: false
           });
@@ -525,7 +711,7 @@ function runRunnerCommand(argv, options) {
       }
     );
     child.on("exit", (_code, signal) => {
-      if (signal !== null) {
+      if (signal !== null && Date.now() - start >= options.timeoutMs) {
         timedOut = true;
       }
     });
@@ -555,14 +741,14 @@ async function probeRunner(runtime, probeArg = "--version", options) {
 }
 function withinProject(p) {
   const cwd = process.cwd();
-  return withinProjectPath(cwd, p) || relative2(cwd, p) === ".";
+  return withinProjectPath(cwd, p) || relative3(cwd, p) === ".";
 }
 function locateRunnerEntry(runtime, projectRoot) {
-  const root = resolve2(projectRoot);
+  const root = resolve3(projectRoot);
   const candidates = [
-    resolve2(root, "node_modules", ".bin", runtime.executable),
-    resolve2(root, "node_modules", ".bin", `${runtime.executable}.cmd`),
-    resolve2(root, "node_modules", ".bin", `${runtime.executable}.ps1`)
+    resolve3(root, "node_modules", ".bin", runtime.executable),
+    resolve3(root, "node_modules", ".bin", `${runtime.executable}.cmd`),
+    resolve3(root, "node_modules", ".bin", `${runtime.executable}.ps1`)
   ];
   for (const c of candidates) {
     if (existsSync(c)) return c;
@@ -592,7 +778,7 @@ function collectSourceFiles(root, opts) {
     entries.sort();
     for (const entry of entries) {
       if (excludeSet.has(entry)) continue;
-      const full = resolve2(dir, entry);
+      const full = resolve3(dir, entry);
       let st;
       try {
         st = statSync(full);
@@ -635,7 +821,7 @@ async function collectSourceFilesAsync(root, opts) {
     entries.sort((a, b) => a.name.localeCompare(b.name));
     for (const entry of entries) {
       if (excludeSet.has(entry.name)) continue;
-      const full = resolve2(dir, entry.name);
+      const full = resolve3(dir, entry.name);
       if (entry.isDirectory()) {
         await walk(full, depth + 1);
       } else if (entry.isFile() && matchesExtension(full, opts.extensions)) {
@@ -656,7 +842,10 @@ export {
   clearLocalBinCache,
   collectSourceFiles,
   collectSourceFilesAsync,
+  createH1State,
   findOnPath,
+  guardedMatcher,
+  isInsideProject,
   locateRunnerEntry,
   matchesExtension,
   parseLlmJsonObject,
@@ -672,7 +861,9 @@ export {
   runOptionalPluginLlm,
   runRunnerCommand,
   safeJsonStringify,
+  safePath,
   sanitizeRunnerPath,
   stripOuterMarkdownFence,
+  withReDoSGuard,
   withinProject
 };

package/dist/secret-scanner.js

@@ -188,6 +188,7 @@ function createState() {
     allowCount: 0,
     /** PostToolUse: secrets detected in tool output. */
     leakCount: 0,
+    timeoutCount: 0,
     /** Most recent PreToolUse block — surfaced by `secret_scanner_status`. */
     lastBlock: null,
     /** Most recent PostToolUse leak — surfaced by `secret_scanner_status`. */
@@ -356,7 +357,19 @@ function buildHook(cfg, log, runtime) {
     const { state } = runtime;
     if (!cfg.enabled) return;
     const toolName = input.toolName ?? "unknown";
-    const matched = scanInput(input.toolInput);
+    let matched;
+    try {
+      matched = scanInput(input.toolInput);
+    } catch (err) {
+      if (String(err).includes("ReDoS")) {
+        state.timeoutCount += 1;
+        return {
+          decision: "block",
+          reason: "secret-scanner: ReDoS timeout \u2014 regex scan exceeded the wall-clock budget. Fail-closed: treated as a block."
+        };
+      }
+      throw err;
+    }
     if (!matched) return;
     const summary = matched.join(", ");
     const when = (/* @__PURE__ */ new Date()).toISOString();
@@ -534,7 +547,8 @@ var plugin = {
             block: state.blockCount,
             redact: state.redactCount,
             allow: state.allowCount,
-            leak: state.leakCount
+            leak: state.leakCount,
+            timeoutCount: state.timeoutCount
           },
           lastBlock: state.lastBlock,
           lastLeak: state.lastLeak

package/dist/type-gate.js

@@ -177,6 +177,7 @@ function runRunnerCommand(argv, options) {
     }
     let timedOut = false;
     let spawnErrored = false;
+    const start = Date.now();
     const stdoutChunks = [];
     const stderrChunks = [];
     let stdoutBytes = 0;
@@ -206,6 +207,15 @@ function runRunnerCommand(argv, options) {
         timeout: options.timeoutMs,
         signal: options.signal,
         maxBuffer: MAX_BUFFER_BYTES,
+        // execFile defaults `encoding` to 'utf8', which makes the
+        // stdout/stderr `data` events emit *strings*. The chunk arrays
+        // below are typed Buffer[] and every consumer runs them through
+        // Buffer.concat(...).toString('utf8'), which throws
+        // ERR_INVALID_ARG_TYPE on any non-empty string output. Pin the
+        // streams to buffers so the declared contract holds (regression:
+        // runRunnerCommand crashed on any child that actually wrote
+        // output; only the maxBuffer fixture exercised this path).
+        encoding: "buffer",
         windowsHide: true,
         shell: false,
         ...invocation.windowsVerbatimArguments ? { windowsVerbatimArguments: true } : {}
@@ -234,11 +244,31 @@ function runRunnerCommand(argv, options) {
         }
         if (err) {
           const anyErr = err;
+          if ((anyErr.killed === true || anyErr.signal === "SIGTERM") && // maxBuffer overflow must NOT be misreported as a timeout
+          // — it's a real failure (the child wrote too much) and
+          // downstream callers (type-gate/index.ts:227) return
+          // null on timedOut=true, which would silently swallow
+          // maxBuffer overflow into a confusing empty-output
+          // result. Skip the timeout resolve when the err shape
+          // names maxBuffer explicitly.
+          !/maxBuffer length exceeded/i.test(anyErr.message ?? "") && // And only count it as a timeout if the wall clock has
+          // actually elapsed past the budget. External SIGTERMs and
+          // races against the exit handler don't satisfy this.
+          Date.now() - start >= options.timeoutMs) {
+            resolvePromise({
+              code: null,
+              stdout: Buffer.concat(stdoutChunks).toString("utf-8"),
+              stderr: Buffer.concat(stderrChunks).toString("utf-8"),
+              timedOut: true,
+              spawnError: false
+            });
+            return;
+          }
           const code = typeof anyErr.code === "number" ? anyErr.code : 1;
           resolvePromise({
             code,
-            stdout: Buffer.concat(stdoutChunks).toString("utf8"),
-            stderr: Buffer.concat(stderrChunks).toString("utf8"),
+            stdout: Buffer.concat(stdoutChunks).toString("utf-8"),
+            stderr: Buffer.concat(stderrChunks).toString("utf-8"),
             timedOut: false,
             spawnError: false
           });
@@ -254,7 +284,7 @@ function runRunnerCommand(argv, options) {
       }
     );
     child.on("exit", (_code, signal) => {
-      if (signal !== null) {
+      if (signal !== null && Date.now() - start >= options.timeoutMs) {
         timedOut = true;
       }
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wrongstack/plugins",
-  "version": "0.307.1",
+  "version": "0.308.0",
   "description": "Official WrongStack collection of focused plugins for code quality, security, observability, planning, and agent coordination",
   "license": "MIT",
   "author": "ECOSTACK TECHNOLOGY OÜ",
@@ -303,8 +303,8 @@
     "vitest": "^4.1.10"
   },
   "dependencies": {
-    "@wrongstack/tools": "0.307.1",
-    "@wrongstack/core": "0.307.1"
+    "@wrongstack/tools": "0.308.0",
+    "@wrongstack/core": "0.308.0"
   },
   "scripts": {
     "build": "node ../../scripts/build-package.mjs",