@wrongstack/plugins 0.307.1 → 0.308.1

package/dist/prompt-firewall.js

@@ -1,3 +1,6 @@
+// src/prompt-firewall/index.ts
+import { performance } from "node:perf_hooks";
+
 // src/runtime/credential-patterns.ts
 var CREDENTIAL_PATTERNS = [
   // LLM provider keys
@@ -130,6 +133,83 @@ function cloneCredentialPatterns() {
   }));
 }
 
+// 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((resolve) => {
+    let settled = false;
+    const onMessage = (msg) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      worker.terminate().catch(() => {
+      });
+      if (!msg.ok) {
+        resolve({ timedOut: true, match: null });
+        return;
+      }
+      resolve({ timedOut: false, match: msg.match });
+    };
+    const onError = () => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      worker.terminate().catch(() => {
+      });
+      resolve({ 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 {
+      }
+      resolve({ 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) });
+}
+`;
+}
+
 // src/prompt-firewall/index.ts
 var KIND_ALIASES = {
   aws_access_key: "aws-access-key",
@@ -169,32 +249,161 @@ var PATTERNS = [
   })),
   ...EXTRA_PATTERNS
 ];
-function detectSecrets(text, allow) {
-  const counts = /* @__PURE__ */ new Map();
-  for (const p of PATTERNS) {
-    p.re.lastIndex = 0;
-    let m = p.re.exec(text);
+var PATTERN_BUDGET_MS = 250;
+var GUARD_PROBE_LENGTH = 1e5;
+var GUARD_PROBE_OVERLAP = 4096;
+var SCAN_PASS_BUDGET_MS = 250;
+function createScanDeadline() {
+  return { deadline: performance.now() + SCAN_PASS_BUDGET_MS, tripped: /* @__PURE__ */ new Set() };
+}
+var SCAN_WINDOW_STRIDE = GUARD_PROBE_LENGTH - GUARD_PROBE_OVERLAP;
+var SCAN_WINDOW_TAIL = 65536;
+var SCAN_WINDOW_LIMIT = GUARD_PROBE_LENGTH + SCAN_WINDOW_TAIL;
+var SCAN_MAX_GROWTH = 16;
+function growMatch(re, p, text, absStart, deadline) {
+  let size = GUARD_PROBE_LENGTH;
+  for (let grown = 0; grown < SCAN_MAX_GROWTH; grown++) {
+    if (deadline && performance.now() > deadline.deadline) {
+      deadline.tripped.add(p.kind);
+      return null;
+    }
+    const extEnd = Math.min(text.length, absStart + size);
+    const ext = text.slice(absStart, extEnd);
+    re.lastIndex = 0;
+    const em = re.exec(ext);
+    if (!em || em.index !== 0 || em[0].length === 0) return null;
+    const end = absStart + em[0].length;
+    if (end < extEnd || extEnd === text.length) {
+      return { start: absStart, end, matched: em[0] };
+    }
+    size *= 2;
+  }
+  return null;
+}
+function* execWindowed(p, text, deadline) {
+  const re = new RegExp(p.re.source, p.re.flags);
+  let acceptLo = 0;
+  let highWater = 0;
+  for (let window = 0; acceptLo < text.length; window++) {
+    const sliceStart = window === 0 ? 0 : acceptLo - GUARD_PROBE_OVERLAP;
+    const sliceEnd = Math.min(text.length, sliceStart + SCAN_WINDOW_LIMIT);
+    const slice = text.slice(sliceStart, sliceEnd);
+    const acceptHi = Math.min(acceptLo + SCAN_WINDOW_STRIDE, text.length);
+    re.lastIndex = 0;
+    let m = re.exec(slice);
     while (m !== null) {
+      if (deadline && performance.now() > deadline.deadline) {
+        deadline.tripped.add(p.kind);
+        return;
+      }
       const matched = m[0];
-      if (!allow.some((a) => a.test(matched))) {
-        counts.set(p.kind, (counts.get(p.kind) ?? 0) + 1);
+      if (matched.length === 0) {
+        re.lastIndex += 1;
+        m = re.exec(slice);
+        continue;
+      }
+      const absStart = sliceStart + m.index;
+      const absEnd = absStart + matched.length;
+      if (absStart >= acceptLo && absStart < acceptHi) {
+        let final = { start: absStart, end: absEnd, matched };
+        if (absEnd === sliceEnd && sliceEnd < text.length) {
+          final = growMatch(re, p, text, absStart, deadline) ?? final;
+          re.lastIndex = m.index + final.matched.length;
+        }
+        if (final.start >= highWater) {
+          highWater = Math.max(highWater, final.end);
+          yield final;
+        }
       }
-      m = p.re.exec(text);
+      m = re.exec(slice);
     }
+    acceptLo += SCAN_WINDOW_STRIDE;
   }
+}
+function countMatches(p, text, allow, counts, deadline) {
+  if (deadline && performance.now() > deadline.deadline) {
+    deadline.tripped.add(p.kind);
+    return;
+  }
+  for (const m of execWindowed(p, text, deadline)) {
+    if (!allow.some((a) => a.test(m.matched))) {
+      counts.set(p.kind, (counts.get(p.kind) ?? 0) + 1);
+    }
+  }
+}
+function replacePattern(p, text, allow, redactions, deadline) {
+  if (deadline && performance.now() > deadline.deadline) {
+    deadline.tripped.add(p.kind);
+    return text;
+  }
+  let out = "";
+  let copied = 0;
+  for (const m of execWindowed(p, text, deadline)) {
+    out += text.slice(copied, m.start);
+    if (allow.some((a) => a.test(m.matched))) {
+      out += m.matched;
+    } else {
+      redactions.n += 1;
+      out += `[REDACTED:${p.kind}]`;
+    }
+    copied = m.end;
+  }
+  return out + text.slice(copied);
+}
+function detectSecrets(text, allow) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const p of PATTERNS) countMatches(p, text, allow, counts);
   return [...counts.entries()].map(([kind, count]) => ({ kind, count }));
 }
-function redactSecrets(text, allow) {
+function redactSecrets(text, allow, deadline) {
+  const redactions = { n: 0 };
   let out = text;
-  let redactions = 0;
-  for (const p of PATTERNS) {
-    out = out.replace(new RegExp(p.re.source, p.re.flags), (match) => {
-      if (allow.some((a) => a.test(match))) return match;
-      redactions += 1;
-      return `[REDACTED:${p.kind}]`;
+  for (const p of PATTERNS) out = replacePattern(p, out, allow, redactions, deadline);
+  return { text: out, redactions: redactions.n };
+}
+var DISTINCT_PATTERN_KINDS = new Set(PATTERNS.map((p) => p.kind)).size;
+async function probeTimedOutPatterns(text) {
+  const timedOut = /* @__PURE__ */ new Set();
+  if (text.length === 0) return timedOut;
+  const probeWindow = (offset) => {
+    const window = text.slice(offset, offset + GUARD_PROBE_LENGTH);
+    const combined = new RegExp(PATTERNS.map((p) => `(${p.re.source})`).join("|"), "gi");
+    return withReDoSGuard(combined, window, PATTERN_BUDGET_MS).then(async (combinedResult) => {
+      if (!combinedResult.timedOut) return;
+      for (const p of PATTERNS) {
+        if (timedOut.has(p.kind)) continue;
+        const result = await withReDoSGuard(p.re, window, PATTERN_BUDGET_MS);
+        if (result.timedOut) timedOut.add(p.kind);
+      }
     });
+  };
+  const stride = GUARD_PROBE_LENGTH - GUARD_PROBE_OVERLAP;
+  for (let offset = 0; offset < text.length; offset += stride) {
+    if (timedOut.size >= DISTINCT_PATTERN_KINDS) break;
+    await probeWindow(offset);
   }
-  return { text: out, redactions };
+  return timedOut;
+}
+async function detectSecretsGuarded(text, allow) {
+  const timedOut = await probeTimedOutPatterns(text);
+  const deadline = createScanDeadline();
+  const counts = /* @__PURE__ */ new Map();
+  for (const p of PATTERNS) {
+    if (!timedOut.has(p.kind)) countMatches(p, text, allow, counts, deadline);
+  }
+  const allSkipped = /* @__PURE__ */ new Set([...timedOut, ...deadline.tripped]);
+  return {
+    detections: [...counts.entries()].map(([kind, count]) => ({ kind, count })),
+    skipped: [...allSkipped].sort().map((kind) => ({ kind, reason: "redos-timeout" }))
+  };
+}
+function redactSecretsGuarded(text, allow, skip, deadline) {
+  const redactions = { n: 0 };
+  let out = text;
+  for (const p of PATTERNS) {
+    if (!skip.has(p.kind)) out = replacePattern(p, out, allow, redactions, deadline);
+  }
+  return { text: out, redactions: redactions.n };
 }
 function collectText(request) {
   const parts = [];
@@ -208,17 +417,27 @@ function collectText(request) {
   walk(request["messages"]);
   return parts.join("\n");
 }
-function redactDeep(value, allow, counter) {
+var RESPONSE_SCAN_BUDGET = 1e6;
+function redactDeep(value, allow, counter, skip, budget, deadline) {
   if (typeof value === "string") {
-    const { text, redactions } = redactSecrets(value, allow);
+    if (budget) {
+      if (value.length > budget.remaining) {
+        budget.remaining = 0;
+        budget.truncated = true;
+        return value;
+      }
+      budget.remaining -= value.length;
+    }
+    const { text, redactions } = skip ? redactSecretsGuarded(value, allow, skip, deadline) : redactSecrets(value, allow, deadline);
     counter.n += redactions;
     return text;
   }
-  if (Array.isArray(value)) return value.map((v) => redactDeep(v, allow, counter));
+  if (Array.isArray(value))
+    return value.map((v) => redactDeep(v, allow, counter, skip, budget, deadline));
   if (value && typeof value === "object") {
     const out = {};
     for (const [k, v] of Object.entries(value)) {
-      out[k] = redactDeep(v, allow, counter);
+      out[k] = redactDeep(v, allow, counter, skip, budget, deadline);
     }
     return out;
   }
@@ -253,16 +472,34 @@ var state = {
   requestRedactions: 0,
   responseRedactions: 0,
   blocked: 0,
+  timeoutCount: 0,
+  skippedPatterns: [],
+  responseTruncated: false,
   byKind: /* @__PURE__ */ new Map(),
   lastDetection: null,
   extensionUnregister: null
 };
+function surfaceScanTrips(api, tripped) {
+  for (const kind of tripped) {
+    if (!state.skippedPatterns.includes(kind)) state.skippedPatterns.push(kind);
+  }
+  state.timeoutCount += 1;
+  api.metrics.counter("redos_skips", 1);
+  api.log.warn("prompt-firewall: scan-pass budget exceeded \u2014 patterns skipped mid-pass (issue #370)", {
+    skipped: [...tripped]
+  });
+}
 var plugin = {
   name: "prompt-firewall",
   version: "0.1.0",
   description: "Scans the provider wire for credential leaks before context reaches the LLM API (wrapProviderRunner); redact/warn/block. Opt-in; redact by default.",
   apiVersion: "^0.1.10",
   capabilities: { tools: true },
+  // Wrap-stack contract (issue #362): ExtensionRegistry composes wrappers
+  // first-registered = outermost. The manifest lists this plugin before
+  // llm-cache, and llm-cache declares this plugin in optionalDeps, so the
+  // firewall is the outer wrap: every request is scanned/redacted before
+  // llm-cache can fingerprint or cache it.
   defaultConfig: { enabled: false, mode: "redact", scanResponse: true, allow: [] },
   configSchema: {
     type: "object",
@@ -297,6 +534,9 @@ var plugin = {
     state.requestRedactions = 0;
     state.responseRedactions = 0;
     state.blocked = 0;
+    state.timeoutCount = 0;
+    state.skippedPatterns = [];
+    state.responseTruncated = false;
     state.byKind.clear();
     state.lastDetection = null;
     if (state.extensionUnregister) {
@@ -319,7 +559,17 @@ var plugin = {
         async wrapProviderRunner(_ctx, request, inner) {
           const req = request ?? {};
           state.invocations += 1;
-          const detections = detectSecrets(collectText(req), cfg.allow);
+          const requestText = collectText(req);
+          const { detections, skipped } = await detectSecretsGuarded(requestText, cfg.allow);
+          state.skippedPatterns = skipped.map((s) => s.kind);
+          if (skipped.length > 0) {
+            state.timeoutCount += 1;
+            api.log.warn("prompt-firewall: ReDoS budget exceeded, patterns skipped", {
+              skipped: state.skippedPatterns
+            });
+            api.metrics.counter("redos_skips", 1);
+          }
+          const skipSet = new Set(state.skippedPatterns);
           if (detections.length > 0) {
             state.requestsWithSecrets += 1;
             for (const d of detections) {
@@ -338,27 +588,39 @@ var plugin = {
             }
             if (cfg.mode === "redact") {
               const counter = { n: 0 };
-              const redactedReq = redactDeep(req, cfg.allow, counter);
+              const deadline = createScanDeadline();
+              const redactedReq = redactDeep(req, cfg.allow, counter, skipSet, void 0, deadline);
               state.requestRedactions += counter.n;
               api.metrics.counter("request_redactions", counter.n);
+              if (deadline.tripped.size > 0) surfaceScanTrips(api, deadline.tripped);
               const response2 = await inner(_ctx, redactedReq);
-              return cfg.scanResponse ? redactResponse(response2, cfg.allow) : response2;
+              return cfg.scanResponse ? redactResponse(response2, cfg.allow, skipSet) : response2;
             }
           }
           const response = await inner(_ctx, request);
           if (cfg.mode === "redact" && cfg.scanResponse) {
-            return redactResponse(response, cfg.allow);
+            return redactResponse(response, cfg.allow, skipSet);
           }
           return response;
         }
       });
     }
-    function redactResponse(response, allow) {
+    function redactResponse(response, allow, skip) {
       if (!response || typeof response !== "object") return response;
       const counter = { n: 0 };
       const content = response.content;
       if (content === void 0) return response;
-      const redacted = redactDeep(content, allow, counter);
+      const budget = { remaining: RESPONSE_SCAN_BUDGET, truncated: false };
+      const deadline = createScanDeadline();
+      const redacted = redactDeep(content, allow, counter, skip, budget, deadline);
+      if (deadline.tripped.size > 0) surfaceScanTrips(api, deadline.tripped);
+      if (budget.truncated) {
+        state.responseTruncated = true;
+        api.log.warn(
+          "prompt-firewall: response scan budget exhausted \u2014 part of the response was returned unredacted"
+        );
+        api.metrics.counter("response_scan_truncated", 1);
+      }
       if (counter.n > 0) {
         state.responseRedactions += counter.n;
         api.metrics.counter("response_redactions", counter.n);
@@ -384,12 +646,15 @@ var plugin = {
           mode: cfg.mode,
           scanResponse: cfg.scanResponse,
           patterns: PATTERNS.map((p) => p.kind),
+          skippedPatterns: state.skippedPatterns,
+          responseTruncated: state.responseTruncated,
           counters: {
             invocations: state.invocations,
             requestsWithSecrets: state.requestsWithSecrets,
             requestRedactions: state.requestRedactions,
             responseRedactions: state.responseRedactions,
-            blocked: state.blocked
+            blocked: state.blocked,
+            timeoutCount: state.timeoutCount
           },
           byKind: Object.fromEntries(state.byKind),
           lastDetection: state.lastDetection
@@ -416,13 +681,17 @@ var plugin = {
       requestsWithSecrets: state.requestsWithSecrets,
       requestRedactions: state.requestRedactions,
       responseRedactions: state.responseRedactions,
-      blocked: state.blocked
+      blocked: state.blocked,
+      timeoutCount: state.timeoutCount
     };
     state.invocations = 0;
     state.requestsWithSecrets = 0;
     state.requestRedactions = 0;
     state.responseRedactions = 0;
     state.blocked = 0;
+    state.timeoutCount = 0;
+    state.skippedPatterns = [];
+    state.responseTruncated = false;
     state.byKind.clear();
     state.lastDetection = null;
     api.log.info("prompt-firewall: teardown complete", { final });
@@ -443,8 +712,12 @@ var plugin = {
 };
 var prompt_firewall_default = plugin;
 export {
+  KIND_ALIASES,
+  SCAN_WINDOW_LIMIT,
   prompt_firewall_default as default,
   detectSecrets,
+  detectSecretsGuarded,
   readConfig,
-  redactSecrets
+  redactSecrets,
+  redactSecretsGuarded
 };

package/dist/runtime/h1-state.d.ts

@@ -0,0 +1,62 @@
+/**
+ * H1 idempotent state — single-slot plugin state with a registry of
+ * releasable handles that survives `setup()` reload cycles.
+ *
+ * The "H1 audit pattern" (per SAGE memory T-03) is documented across
+ * the plugin suite: a plugin's module-scope `state` object holds
+ * counters plus a `hookUnregister` (or `extensionUnregister`) slot;
+ * on reload, the slot MUST be released before a new one is stored.
+ * Every plugin implements this inline with subtle variations:
+ *
+ *   - some use `releaseHandle(state.hookUnregister)` (`accessibility-auditor`)
+ *   - some use `try { state.hookUnregister(); } catch {}` (`config-validator`)
+ *   - some use a single inline `if (state.hookUnregister) { … }` block
+ *
+ * The drift cost: in 4 plugins the prior handle was leaked on reload
+ * because the inline `if` check raced with the new registration.
+ * This helper centralises the contract.
+ *
+ * Contract:
+ *   `createH1State<T>(initial)` returns
+ *     {
+ *       state:    T,                    // the user's mutable state
+ *       register: (key, unregister) => void,
+ *       release:  (key) => void,
+ *       releaseAll: () => void,
+ *     }
+ *
+ * - `register(key, unregister)` releases any prior handle at `key`
+ *   before storing the new one.
+ * - `release(key)` is a no-op if no handle is registered.
+ * - `releaseAll()` releases every registered handle and clears the map.
+ * - A throwing unregister function is swallowed (best-effort), matching
+ *   the existing `releaseHandle` semantics at `runtime/handles.ts`.
+ *
+ * The state object itself is NOT reset by `releaseAll` — counter
+ * reset is the plugin's responsibility (it knows the semantics of its
+ * counters). This helper owns the handle lifecycle only.
+ */
+export type Unregister = () => void;
+export interface H1State<T> {
+    /** The plugin's mutable state. Owned by the caller; never reset by this helper. */
+    state: T;
+    /**
+     * Register an unregister function under `key`. Any prior handle at
+     * `key` is released first. Throwing unregister functions are
+     * swallowed.
+     */
+    register: (key: string, unregister: Unregister | null | undefined) => void;
+    /**
+     * Release the handle at `key` (if any). Idempotent. Throwing
+     * unregister functions are swallowed.
+     */
+    release: (key: string) => void;
+    /** Release every registered handle. Idempotent. */
+    releaseAll: () => void;
+    /** Number of currently registered handles. Observability for health()/status tools. */
+    size: () => number;
+    /** List the registered keys. Order is insertion order; useful for diagnostics. */
+    keys: () => string[];
+}
+export declare function createH1State<T>(initial: T): H1State<T>;
+//# sourceMappingURL=h1-state.d.ts.map

package/dist/runtime/index.d.ts

@@ -32,6 +32,9 @@ export { parseLlmJsonObject, runOptionalPluginCouncil, runOptionalPluginLlm, str
 export { BoundedMap, BoundedSet, type BoundedMapOptions } from './bounded-map.js';
 export { UNSERIALIZABLE, safeJsonStringify } from './safe-json.js';
 export { releaseHandle, releaseHandles, type Unregister } from './handles.js';
+export { withReDoSGuard, guardedMatcher, type ReDoSResult, type ReDoSOptions, } from './redos-guard.js';
+export { safePath, isInsideProject, type SafePathOptions, } from './sandbox.js';
+export { createH1State, type H1State, } from './h1-state.js';
 export { clearLocalBinCache, findOnPath, resolveExecInvocation, resolveFirstNodeBin, resolveNodeBin, resolveWin32Command, type ExecInvocation, type ResolvedNodeBin, } from './local-bin.js';
 export type LanguageId = 'typescript' | 'javascript' | 'python' | 'go' | 'rust' | 'shell' | 'ruby' | 'java' | 'kotlin' | 'dotnet' | 'generic';
 export type PackageManagerId = 'npm' | 'pnpm' | 'yarn' | 'bun' | 'pip' | 'poetry' | 'go' | 'cargo' | 'gem' | 'maven' | 'gradle' | 'dotnet' | 'none';

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