@crewhaus/tool-secure 0.7.0 → 0.8.1

package/dist/lib/text.js

@@ -79,6 +79,89 @@ export function maskValue(value, keep = 2) {
     const tail = value.slice(n - keep);
     return `${head}${"*".repeat(Math.min(n - 2 * keep, 12))}${tail}`;
 }
+/**
+ * Spans, asked one question: does `[start, end)` overlap any of them?
+ *
+ * Overlap is `start < k.end && k.start < end`, the test `dedupeOverlaps` and
+ * `secretFindings` make, answered for any numbers, empty spans included.
+ * Among the spans that start before `end`, one overlaps exactly when the
+ * largest of their ends is past `start`. So the index keeps that largest end
+ * in a Fenwick tree with one slot per distinct start, and a question or an
+ * addition visits O(log n) slots. Checking every span kept so far made
+ * those two passes quadratic in the findings, on text a model or a web page
+ * supplies.
+ *
+ * Every start a span will be added with is named up front, because the
+ * slots are the distinct starts in order. `steps` counts the slots and
+ * probes the calls visit, so a test can hold the index to its bound.
+ */
+export class SpanIndex {
+    /** Tree slots and binary-search probes visited so far. */
+    steps = 0;
+    /** The distinct starts, ascending. */
+    starts;
+    /** 1-based Fenwick tree of the largest end per prefix of `starts`. */
+    maxEnd;
+    constructor(starts) {
+        const sorted = new Float64Array(starts.length);
+        let n = 0;
+        // A NaN start never satisfies the test, so it never needs a slot.
+        for (let i = 0; i < starts.length; i++) {
+            const s = starts[i];
+            if (!Number.isNaN(s))
+                sorted[n++] = s;
+        }
+        sorted.subarray(0, n).sort();
+        let distinct = 0;
+        for (let i = 0; i < n; i++) {
+            const s = sorted[i];
+            if (distinct === 0 || s !== sorted[distinct - 1])
+                sorted[distinct++] = s;
+        }
+        this.starts = sorted.slice(0, distinct);
+        this.maxEnd = new Float64Array(distinct + 1).fill(Number.NEGATIVE_INFINITY);
+    }
+    /** How many distinct starts are below `bound`; none are below NaN. */
+    below(bound) {
+        let lo = 0;
+        let hi = this.starts.length;
+        while (lo < hi) {
+            this.steps++;
+            const mid = (lo + hi) >>> 1;
+            if (this.starts[mid] < bound)
+                lo = mid + 1;
+            else
+                hi = mid;
+        }
+        return lo;
+    }
+    /** Whether some span added so far has `k.start < end && start < k.end`. */
+    overlaps(start, end) {
+        let most = Number.NEGATIVE_INFINITY;
+        for (let i = this.below(end); i > 0; i -= i & -i) {
+            this.steps++;
+            const e = this.maxEnd[i];
+            if (e > most)
+                most = e;
+        }
+        return most > start;
+    }
+    /** Add `[start, end)`; `start` must be one the index was built with. */
+    add(start, end) {
+        // A NaN on either side never satisfies the test, so it is never found.
+        if (Number.isNaN(start) || Number.isNaN(end))
+            return;
+        const at = this.below(start);
+        if (at >= this.starts.length || this.starts[at] !== start) {
+            throw new Error(`SpanIndex: start ${start} was not named when the index was built`);
+        }
+        for (let i = at + 1; i < this.maxEnd.length; i += i & -i) {
+            this.steps++;
+            if (end > this.maxEnd[i])
+                this.maxEnd[i] = end;
+        }
+    }
+}
 /**
  * Drop findings swallowed by a stronger one.
  *
@@ -87,6 +170,10 @@ export function maskValue(value, keep = 2) {
  * survivor is chosen by confidence, then by length, then by earliest start,
  * then by rule name — a total order, so the same input always yields the
  * same set.
+ *
+ * Each candidate, in that order, is kept unless it overlaps one kept before
+ * it. A `SpanIndex` answers that, so the pass is O(k log k) in the findings
+ * rather than a check against every finding kept so far.
  */
 export function dedupeOverlaps(findings) {
     const ranked = [...findings].sort((a, b) => {
@@ -100,11 +187,13 @@ export function dedupeOverlaps(findings) {
             return a.start - b.start;
         return compareStrings(a.rule, b.rule);
     });
+    const index = new SpanIndex(ranked.map((f) => f.start));
     const kept = [];
     for (const candidate of ranked) {
-        const clashes = kept.some((k) => candidate.start < k.end && k.start < candidate.end);
-        if (!clashes)
-            kept.push(candidate);
+        if (index.overlaps(candidate.start, candidate.end))
+            continue;
+        kept.push(candidate);
+        index.add(candidate.start, candidate.end);
     }
     return sortFindings(kept);
 }
@@ -123,11 +212,54 @@ export function withPositions(text, raw) {
 /**
  * Replace each span with the string `replace` returns for it.
  *
- * Spans must not overlap (`dedupeOverlaps` guarantees that); they are
- * applied right to left so earlier offsets stay valid.
+ * Spans must not overlap (`dedupeOverlaps` guarantees that). `replace` is
+ * called right to left, as it always has been, and the output is the text
+ * between the spans joined with their replacements: one copy of the text.
+ * Rebuilding the whole string for every span was O(spans × text), and a
+ * redaction pass over megabytes of findings-dense text has hundreds of
+ * thousands of spans. Spans that overlap, sit out of order or outside the
+ * text, or have fractional offsets keep the old right-to-left rebuild, which
+ * gives the same result on spans that do none of those things.
  */
 export function applySpans(text, findings, replace) {
     const ordered = sortFindings(findings);
+    if (!disjointWithin(ordered, text.length))
+        return rebuildRightToLeft(text, ordered, replace);
+    const replacements = new Array(ordered.length);
+    for (let i = ordered.length - 1; i >= 0; i--) {
+        const f = ordered[i];
+        if (f)
+            replacements[i] = replace(f);
+    }
+    const parts = [];
+    let at = 0;
+    for (let i = 0; i < ordered.length; i++) {
+        const f = ordered[i];
+        if (!f)
+            continue;
+        parts.push(text.slice(at, f.start), replacements[i]);
+        at = f.end;
+    }
+    parts.push(text.slice(at));
+    return parts.join("");
+}
+/** Whether sorted spans are whole offsets, in order, apart, and inside the text. */
+function disjointWithin(ordered, length) {
+    let at = 0;
+    for (let i = 0; i < ordered.length; i++) {
+        const f = ordered[i];
+        if (!f)
+            continue;
+        if (!Number.isInteger(f.start) || !Number.isInteger(f.end))
+            return false;
+        if (f.start < at || f.end < f.start || f.end > length)
+            return false;
+        at = f.end;
+    }
+    return true;
+}
+/** The original rebuild, kept for spans `disjointWithin` refuses. */
+function rebuildRightToLeft(text, ordered, replace) {
     let out = text;
     for (let i = ordered.length - 1; i >= 0; i--) {
         const f = ordered[i];
@@ -173,6 +305,43 @@ export function* matchAll(text, pattern) {
             re.lastIndex += 1;
     }
 }
+/**
+ * `matchAll(text, pattern)`'s matches, in order, with the pattern tried
+ * (sticky) only where `canStart` says a match may begin, and, after a try
+ * that fails at `at`, not again before `failedTo(text, at)`.
+ *
+ * For a pattern that opens with an unbounded run (an email's local part, a
+ * word before a comma, the whitespace after a line start), a global search
+ * that fails at one start moves one character right and scans the same run
+ * again: quadratic in the run's length. Every later start inside such a run
+ * shares the run's end and reads the same text after it, so it fails too;
+ * `failedTo` names where that stops being true, and the matches are the
+ * global pattern's, start for start. After a match the next try is at its
+ * end (one further for an empty match), as `lastIndex` would be.
+ */
+export function* matchAllSkipping(text, pattern, canStart, failedTo) {
+    let flags = pattern.flags.replace("g", "");
+    if (!flags.includes("d"))
+        flags = `${flags}d`;
+    if (!flags.includes("y"))
+        flags = `${flags}y`;
+    const re = new RegExp(pattern.source, flags);
+    let at = 0;
+    while (at <= text.length) {
+        if (!canStart(text, at)) {
+            at++;
+            continue;
+        }
+        re.lastIndex = at;
+        const m = re.exec(text);
+        if (m !== null) {
+            yield { index: at, match: m };
+            at += Math.max(1, m[0].length);
+            continue;
+        }
+        at = Math.max(at + 1, failedTo(text, at));
+    }
+}
 /**
  * The absolute `[start, end)` of one capture group of a match produced by
  * `matchAll`, or `undefined` when the group did not participate.

package/dist/paths.d.ts

@@ -1,10 +1,29 @@
 import { CrewhausError } from "@crewhaus/errors";
-/** Raised when a caller-supplied path resolves outside the workspace root. */
+/**
+ * The longest path this resolves, in UTF-16 code units; a longer one is
+ * refused before it is walked. Nothing that long can be opened or created:
+ * PATH_MAX is 1,024 bytes on macOS and 4,096 on Linux, Windows stops at
+ * 32,767 UTF-16 units, and a path's UTF-8 form is never shorter than its
+ * UTF-16 one. The limit is twice that because the part of a path that exists
+ * is itself under PATH_MAX, so the part that does not is over PATH_MAX on its
+ * own: no spelling of the place reaches it, not even one through a symlink
+ * that shortens the part that exists.
+ */
+export declare const MAX_PATH_CHARS: number;
+/**
+ * Raised when a caller-supplied path resolves outside the workspace root, or
+ * is longer than any path can be.
+ */
 export declare class ToolPermissionError extends CrewhausError {
     readonly name = "ToolPermissionError";
     readonly toolName: string;
     readonly path: string;
-    constructor(toolName: string, attemptedPath: string);
+    /**
+     * Why, when it is not that the location escapes the workspace root: a path
+     * longer than any path can be. A caller that rewords the refusal says this.
+     */
+    readonly reason: string | undefined;
+    constructor(toolName: string, attemptedPath: string, reason?: string);
 }
 /**
  * A validated path, in both forms the tools need.

package/dist/paths.js

@@ -11,15 +11,45 @@
 import { lstatSync, readlinkSync, realpathSync } from "node:fs";
 import * as path from "node:path";
 import { CrewhausError } from "@crewhaus/errors";
-/** Raised when a caller-supplied path resolves outside the workspace root. */
+/**
+ * The longest path this resolves, in UTF-16 code units; a longer one is
+ * refused before it is walked. Nothing that long can be opened or created:
+ * PATH_MAX is 1,024 bytes on macOS and 4,096 on Linux, Windows stops at
+ * 32,767 UTF-16 units, and a path's UTF-8 form is never shorter than its
+ * UTF-16 one. The limit is twice that because the part of a path that exists
+ * is itself under PATH_MAX, so the part that does not is over PATH_MAX on its
+ * own: no spelling of the place reaches it, not even one through a symlink
+ * that shortens the part that exists.
+ */
+export const MAX_PATH_CHARS = 2 * (process.platform === "darwin" ? 1_024 : process.platform === "win32" ? 32_767 : 4_096);
+/** A path as a refusal quotes it: whole, unless it is past {@link MAX_PATH_CHARS}. */
+function shownPath(given) {
+    return given.length > MAX_PATH_CHARS ? `${given.slice(0, 64)}…` : given;
+}
+/** Why a path past {@link MAX_PATH_CHARS} is refused: its length and the limit. */
+function tooLong(abs) {
+    return `it is ${abs.length} characters once resolved, over the ${MAX_PATH_CHARS}-character limit: no path that long can be opened or created`;
+}
+/**
+ * Raised when a caller-supplied path resolves outside the workspace root, or
+ * is longer than any path can be.
+ */
 export class ToolPermissionError extends CrewhausError {
     name = "ToolPermissionError";
     toolName;
     path;
-    constructor(toolName, attemptedPath) {
-        super("tool", `tool "${toolName}" rejected path "${attemptedPath}": resolved location escapes the workspace root`);
+    /**
+     * Why, when it is not that the location escapes the workspace root: a path
+     * longer than any path can be. A caller that rewords the refusal says this.
+     */
+    reason;
+    constructor(toolName, attemptedPath, reason) {
+        super("tool", reason === undefined
+            ? `tool "${toolName}" rejected path "${attemptedPath}": resolved location escapes the workspace root`
+            : `tool "${toolName}" rejected path "${shownPath(attemptedPath)}": ${reason}`);
         this.toolName = toolName;
         this.path = attemptedPath;
+        this.reason = reason;
     }
 }
 /** The workspace root, resolved. Every path is contained within it. */
@@ -67,15 +97,7 @@ function nameExists(p) {
 function resolveLocation(target, depth = 0) {
     if (depth > 40)
         throw new Error(`symlink chain at "${target}" is too long to resolve`);
-    let probe = target;
-    const tail = [];
-    while (!nameExists(probe)) {
-        tail.unshift(path.basename(probe));
-        const parent = path.dirname(probe);
-        if (parent === probe)
-            break; // reached the filesystem root
-        probe = parent;
-    }
+    const { probe, tail } = deepestName(target);
     let probeReal;
     try {
         probeReal = realpathSync(probe);
@@ -97,7 +119,41 @@ function resolveLocation(target, depth = 0) {
         const base = realpathSync(path.dirname(probe));
         probeReal = resolveLocation(path.resolve(base, link), depth + 1);
     }
-    return tail.length > 0 ? path.join(probeReal, ...tail) : probeReal;
+    // One string, not one argument per name: Bun's `path.join` keeps only
+    // (argument count mod 65,536) of its arguments.
+    return tail.length > 0 ? path.join(probeReal, tail) : probeReal;
+}
+/**
+ * `target`, an absolute path, split where its deepest prefix that exists as
+ * a NAME ends: that prefix, and the names below it, which do not exist, as
+ * one string ("" when `target` itself exists). This is `path.dirname` and
+ * `path.basename` worked by index on `target` itself: handing them each
+ * shorter prefix in turn copied the rest of the path once per missing name,
+ * the square of a count the caller picks.
+ */
+function deepestName(target) {
+    const top = path.parse(target).root.length;
+    const isSep = (i) => target[i] === "/" || target[i] === path.sep;
+    let probe = target;
+    let start = target.length;
+    let stop = -1;
+    while (!nameExists(probe)) {
+        // `path.basename(probe)` is `target.slice(start, end)`, and
+        // `path.dirname(probe)` is `target.slice(0, up)`.
+        let end = probe.length;
+        while (end > top && isSep(end - 1))
+            end--;
+        if (stop < 0)
+            stop = end;
+        start = end;
+        while (start > top && !isSep(start - 1))
+            start--;
+        const up = start > top ? start - 1 : top;
+        if (up === probe.length)
+            break; // reached the filesystem root
+        probe = target.slice(0, up);
+    }
+    return { probe, tail: stop < 0 ? "" : target.slice(start, stop) };
 }
 export function resolveSafe(toolName, rel, root = workspaceRoot()) {
     const rootResolved = path.resolve(root);
@@ -107,6 +163,9 @@ export function resolveSafe(toolName, rel, root = workspaceRoot()) {
     if (abs !== rootResolved && !abs.startsWith(`${rootResolved}${path.sep}`)) {
         throw new ToolPermissionError(toolName, rel);
     }
+    // Longer than any path can be: refused before the walk below reads it.
+    if (abs.length > MAX_PATH_CHARS)
+        throw new ToolPermissionError(toolName, rel, tooLong(abs));
     let real;
     try {
         const rootReal = realpathSync(rootResolved);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crewhaus/tool-secure",
-  "version": "0.7.0",
+  "version": "0.8.1",
   "type": "module",
   "description": "Deterministic security tools: PII detection and redaction, secret scanning, prompt-injection heuristics, policy checks and evidence hashing",
   "main": "dist/index.js",
@@ -8,19 +8,22 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
     }
   },
   "scripts": {
     "test": "bun test src"
   },
   "dependencies": {
-    "@crewhaus/errors": "0.7.0",
-    "@crewhaus/tool-builder": "0.7.0",
-    "@crewhaus/tool-catalog": "0.7.0",
+    "@crewhaus/errors": "0.8.1",
+    "@crewhaus/tool-builder": "0.8.1",
+    "@crewhaus/tool-catalog": "0.8.1",
+    "@crewhaus/tool-safety": "0.8.1",
     "zod": "^3.23.8"
   },
   "devDependencies": {
+    "@crewhaus/tool-categories": "workspace:*",
     "@crewhaus/tool-executor": "workspace:*"
   },
   "license": "Apache-2.0",
@@ -41,5 +44,8 @@
   "publishConfig": {
     "access": "public"
   },
-  "files": ["dist", "README.md", "LICENSE", "NOTICE"]
+  "files": ["dist", "README.md", "LICENSE", "NOTICE"],
+  "engines": {
+    "bun": ">=1.3.14"
+  }
 }