@crewhaus/tool-secure 0.7.0

package/dist/lib/url.js

@@ -0,0 +1,363 @@
+/**
+ * Structural analysis of a URL, and allow-list matching.
+ *
+ * ## Nothing here fetches anything
+ *
+ * Every check reads the string. No DNS, no HTTP, no reputation service — so
+ * this says nothing about whether a host is malicious, only whether the URL
+ * is SHAPED like the ones used to mislead: credentials in the authority, an
+ * IP where a name should be, a punycode label, another URL smuggled through
+ * a redirect parameter, a `javascript:` payload.
+ *
+ * A URL with no findings is a URL that is structurally unremarkable. That is
+ * all. Plenty of ordinary-looking URLs are hostile and plenty of odd-looking
+ * ones are fine.
+ *
+ * ## Allow-list grammar
+ *
+ * A rule is matched, never guessed at. Exactly these forms:
+ *
+ * | kind | rule | matches |
+ * |---|---|---|
+ * | `url` | `example.com` | that host only, any http(s) URL |
+ * | `url` | `*.example.com` | any subdomain, NOT the bare host |
+ * | `url` | `https://example.com/api/` | host plus a path prefix, scheme pinned |
+ * | `emailDomain` | `example.com` | that domain only, case-insensitive |
+ * | `emailDomain` | `*.example.com` | any subdomain of it |
+ * | `path` | `src/` | that workspace-relative directory and everything under it |
+ *
+ * Deny by default: an empty allow-list allows nothing, and a rule that does
+ * not parse is an error rather than a rule that silently matches nothing.
+ */
+import { compareStrings } from "./text";
+import { mixedScriptRuns } from "./unicode";
+/** Schemes a link in a document is normally allowed to use. */
+const BENIGN_SCHEMES = new Set(["http", "https", "mailto"]);
+/** Schemes that execute or inline content rather than locate it. */
+const ACTIVE_SCHEMES = new Set(["javascript", "data", "vbscript", "blob", "file"]);
+/** Ports that are a service, not a website. */
+const SENSITIVE_PORTS = new Set([
+    22, 23, 25, 110, 135, 139, 445, 1433, 1521, 3306, 3389, 5432, 5900, 6379, 9200, 11211, 27017,
+]);
+const REDIRECT_PARAMS = new Set([
+    "callback",
+    "continue",
+    "dest",
+    "destination",
+    "forward",
+    "goto",
+    "image_url",
+    "link",
+    "next",
+    "out",
+    "path",
+    "r",
+    "redir",
+    "redirect",
+    "redirect_uri",
+    "redirect_url",
+    "return",
+    "returnto",
+    "return_to",
+    "rurl",
+    "target",
+    "to",
+    "u",
+    "uri",
+    "url",
+    "window",
+]);
+/**
+ * Every rule id `analyzeUrl` can emit, so `checked` and `issues[].rule` are
+ * the same vocabulary — a caller can line an empty `issues` list up against
+ * this one and see exactly what "no findings" covered. Naming a category here
+ * that no issue ever reports under (`scheme` when the issue says
+ * `scheme.active`) makes the two lists un-joinable, which is the whole point
+ * of publishing the second one.
+ */
+export const URL_CHECKS = [
+    "parse",
+    "raw.whitespace-or-control",
+    "length",
+    "scheme.active",
+    "scheme.unexpected",
+    "authority.credentials",
+    "host.numeric",
+    "host.ip-literal",
+    "host.punycode",
+    "host.non-ascii",
+    "host.mixed-script",
+    "host.label-count",
+    "port.service",
+    "port.non-standard",
+    "query.redirect-parameter",
+    "query.embedded-url",
+    "encoding.double",
+];
+const IPV4_HOST = /^\d{1,3}(?:\.\d{1,3}){3}$/;
+const ALL_DIGITS = /^\d+$/;
+const HEX_HOST = /^0x[0-9a-f]+$/i;
+/** Whitespace or an ASCII control character anywhere in the string. */
+function hasWhitespaceOrControl(value) {
+    for (let i = 0; i < value.length; i++) {
+        const code = value.charCodeAt(i);
+        if (code <= 0x20 || code === 0x7f)
+            return true;
+    }
+    return false;
+}
+/** True when every code unit is ASCII. */
+function isAscii(value) {
+    for (let i = 0; i < value.length; i++) {
+        if (value.charCodeAt(i) > 0x7f)
+            return false;
+    }
+    return true;
+}
+/** Analyse one URL string. Never throws for a caller mistake. */
+export function analyzeUrl(raw) {
+    const issues = [];
+    if (hasWhitespaceOrControl(raw)) {
+        issues.push({
+            rule: "raw.whitespace-or-control",
+            severity: "medium",
+            detail: "the URL contains whitespace or control characters, which parsers disagree about",
+        });
+    }
+    if (raw.length > 2000) {
+        issues.push({
+            rule: "length",
+            severity: "low",
+            detail: `the URL is ${raw.length} characters; unusually long URLs hide their tail in a status bar`,
+        });
+    }
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        return {
+            parsed: false,
+            issues: [
+                ...issues,
+                {
+                    rule: "parse",
+                    severity: "medium",
+                    detail: "not an absolute URL; a relative reference resolves against a base this tool cannot see",
+                },
+            ],
+            checked: URL_CHECKS,
+        };
+    }
+    const scheme = url.protocol.replace(/:$/, "").toLowerCase();
+    if (ACTIVE_SCHEMES.has(scheme)) {
+        issues.push({
+            rule: "scheme.active",
+            severity: "high",
+            detail: `the "${scheme}:" scheme carries or executes content rather than locating it`,
+        });
+    }
+    else if (!BENIGN_SCHEMES.has(scheme)) {
+        issues.push({
+            rule: "scheme.unexpected",
+            severity: "low",
+            detail: `scheme "${scheme}:" is neither http, https nor mailto`,
+        });
+    }
+    if (url.username !== "" || url.password !== "") {
+        issues.push({
+            rule: "authority.credentials",
+            severity: "high",
+            detail: url.password === ""
+                ? "the authority carries a username, which pushes the real host past where a reader stops looking"
+                : "the authority carries a username and password",
+        });
+    }
+    // The authority exactly as written. `url.hostname` is already normalized —
+    // for an http URL the parser turns `2130706433` into `127.0.0.1` — so the
+    // obfuscated form is only visible here.
+    const rawAuthority = raw.replace(/^[a-z][a-z0-9+.-]*:\/\//i, "").split(/[/?#]/)[0] ?? "";
+    const rawHost = rawAuthority
+        .slice(rawAuthority.lastIndexOf("@") + 1)
+        .replace(/:\d*$/, "")
+        .toLowerCase();
+    const host = url.hostname.toLowerCase();
+    if (ALL_DIGITS.test(rawHost) || HEX_HOST.test(rawHost)) {
+        issues.push({
+            rule: "host.numeric",
+            severity: "high",
+            detail: `the host is written as a bare number ("${rawHost}"), a decimal or hex encoding of the IP address ${host} that hides it from a reader`,
+        });
+    }
+    else if (IPV4_HOST.test(host)) {
+        issues.push({
+            rule: "host.ip-literal",
+            severity: "medium",
+            detail: "the host is an IPv4 literal, so there is no name to check and no certificate name to match",
+        });
+    }
+    else if (host.startsWith("[")) {
+        issues.push({
+            rule: "host.ip-literal",
+            severity: "medium",
+            detail: "the host is an IPv6 literal",
+        });
+    }
+    const labels = host.split(".");
+    for (const label of labels) {
+        if (label.startsWith("xn--")) {
+            issues.push({
+                rule: "host.punycode",
+                severity: "medium",
+                detail: `label "${label}" is punycode, so the host displays as non-ASCII characters that may imitate another name`,
+            });
+            break;
+        }
+    }
+    // Compare against the raw input, because URL parsing already applied IDNA.
+    if (!isAscii(rawAuthority)) {
+        issues.push({
+            rule: "host.non-ascii",
+            severity: "medium",
+            detail: "the host as written contains non-ASCII characters",
+        });
+        const mixed = mixedScriptRuns(rawAuthority);
+        if (mixed.length > 0) {
+            issues.push({
+                rule: "host.mixed-script",
+                severity: "high",
+                detail: `the host mixes scripts (${mixed[0]?.scripts.join(" + ")}), the shape of a homograph imitation`,
+            });
+        }
+    }
+    if (labels.length > 5) {
+        issues.push({
+            rule: "host.label-count",
+            severity: "low",
+            detail: `${labels.length} labels: a long prefix can make a hostile registrable domain read as a path`,
+        });
+    }
+    if (url.port !== "") {
+        const port = Number(url.port);
+        if (SENSITIVE_PORTS.has(port)) {
+            issues.push({
+                rule: "port.service",
+                severity: "medium",
+                detail: `port ${port} is an administrative or database service, not a web server`,
+            });
+        }
+        else if (port !== 80 && port !== 443) {
+            issues.push({
+                rule: "port.non-standard",
+                severity: "low",
+                detail: `explicit port ${port}`,
+            });
+        }
+    }
+    for (const [key, value] of [...url.searchParams].sort((a, b) => compareStrings(a[0], b[0]) || compareStrings(a[1], b[1]))) {
+        const decoded = safeDecode(value);
+        const carriesUrl = /^(?:\/\/|[a-z][a-z0-9+.-]*:\/\/)/i.test(decoded);
+        if (!carriesUrl)
+            continue;
+        const named = REDIRECT_PARAMS.has(key.toLowerCase());
+        issues.push({
+            rule: named ? "query.redirect-parameter" : "query.embedded-url",
+            severity: named ? "high" : "medium",
+            detail: `parameter "${key}" carries another URL (${truncate(decoded, 80)})`,
+        });
+    }
+    if (/%25[0-9a-f]{2}/i.test(raw)) {
+        issues.push({
+            rule: "encoding.double",
+            severity: "medium",
+            detail: "double percent-encoding: what one layer decodes may differ from what the next one sees",
+        });
+    }
+    return {
+        parsed: true,
+        scheme,
+        host,
+        port: url.port === "" ? undefined : url.port,
+        issues: issues.sort((a, b) => compareStrings(a.rule, b.rule) || compareStrings(a.detail, b.detail)),
+        checked: URL_CHECKS,
+    };
+}
+function safeDecode(value) {
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        return value;
+    }
+}
+function truncate(value, max) {
+    return value.length <= max ? value : `${value.slice(0, max)}...`;
+}
+// ---------------------------------------------------------------------------
+// allow-lists
+// ---------------------------------------------------------------------------
+export class AllowRuleError extends Error {
+    name = "AllowRuleError";
+}
+/** A host matches a host rule exactly, or as a subdomain under `*.`. */
+export function hostMatches(host, rule) {
+    const h = host.toLowerCase().replace(/\.$/, "");
+    const r = rule.toLowerCase().replace(/\.$/, "");
+    if (r.startsWith("*.")) {
+        const base = r.slice(2);
+        return h.endsWith(`.${base}`) && h.length > base.length + 1;
+    }
+    return h === r;
+}
+/** True when `pathname` is `prefix` or lives under it. */
+function underPrefix(pathname, prefix) {
+    if (prefix === "/" || prefix === "")
+        return true;
+    const normalized = prefix.endsWith("/") ? prefix : `${prefix}/`;
+    return pathname === prefix || pathname.startsWith(normalized);
+}
+/** Does this URL satisfy this allow-list rule? */
+export function urlMatchesRule(value, rule) {
+    const trimmed = rule.trim();
+    if (trimmed === "")
+        throw new AllowRuleError("an allow-list rule may not be empty");
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        return false;
+    }
+    if (/^[a-z][a-z0-9+.-]*:\/\//i.test(trimmed)) {
+        let ruleUrl;
+        try {
+            ruleUrl = new URL(trimmed);
+        }
+        catch {
+            throw new AllowRuleError(`allow-list rule "${rule}" starts with a scheme but is not a valid URL`);
+        }
+        if (ruleUrl.protocol !== url.protocol)
+            return false;
+        if (!hostMatches(url.hostname, ruleUrl.hostname))
+            return false;
+        if (ruleUrl.port !== "" && ruleUrl.port !== url.port)
+            return false;
+        return underPrefix(url.pathname, ruleUrl.pathname);
+    }
+    const [hostPart = "", ...pathParts] = trimmed.split("/");
+    if (hostPart.includes(":")) {
+        throw new AllowRuleError(`allow-list rule "${rule}" has a port or scheme but no "://" — write it as https://host[:port][/prefix]`);
+    }
+    if (!hostMatches(url.hostname, hostPart))
+        return false;
+    const prefix = pathParts.join("/");
+    return prefix === "" ? true : underPrefix(url.pathname, `/${prefix}`);
+}
+/** The domain of an email address, lower-cased, or undefined if there is none. */
+export function emailDomain(address) {
+    const at = address.lastIndexOf("@");
+    if (at < 0 || at === address.length - 1)
+        return undefined;
+    const domain = address.slice(at + 1).toLowerCase();
+    return domain.includes(" ") ? undefined : domain;
+}

package/dist/paths.d.ts

@@ -0,0 +1,42 @@
+import { CrewhausError } from "@crewhaus/errors";
+/** Raised when a caller-supplied path resolves outside the workspace root. */
+export declare class ToolPermissionError extends CrewhausError {
+    readonly name = "ToolPermissionError";
+    readonly toolName: string;
+    readonly path: string;
+    constructor(toolName: string, attemptedPath: string);
+}
+/**
+ * A validated path, in both forms the tools need.
+ *
+ * `real` has every in-workspace symlink already resolved and is what I/O
+ * should use — operating on it closes most of the check-to-use window.
+ * `abs` is the lexical resolution, which is what a tool must use when the
+ * question is about the link ITSELF (`Stat` reporting a symlink target,
+ * `RemovePath` deleting a link rather than its destination).
+ */
+export type SafePath = {
+    readonly abs: string;
+    readonly real: string;
+    /** The path as the caller wrote it, for echoing back in results. */
+    readonly given: string;
+    /** Slash-separated path relative to the workspace root. */
+    readonly rel: string;
+};
+/** The workspace root, resolved. Every path is contained within it. */
+export declare function workspaceRoot(): string;
+export declare function resolveSafe(toolName: string, rel: string, root?: string): SafePath;
+/** A path relative to the workspace root, with `/` separators on every OS. */
+export declare function toPosix(p: string): string;
+/**
+ * True when `candidate` is `parent` or lives underneath it. Both must already
+ * be absolute. Used to keep an archive entry, or a symlink inside an
+ * extracted tree, from reaching outside its destination.
+ */
+export declare function isInside(parent: string, candidate: string): boolean;
+/**
+ * Reject an archive member name that would escape its destination: an
+ * absolute path, a Windows drive prefix, or any `..` segment. Checked on the
+ * NAME, before extraction, because after extraction the damage is done.
+ */
+export declare function archiveEntryEscapes(name: string): boolean;

package/dist/paths.js

@@ -0,0 +1,158 @@
+/**
+ * Path containment — the gate every caller-supplied path in this package
+ * passes through before any syscall touches it.
+ *
+ * The approach is the one `@crewhaus/tool-fs` uses, and for the same reasons:
+ * a lexical check alone is fooled by a symlink that lives inside the
+ * workspace and points outside it (CWE-59), so the real path is checked too.
+ * The workspace root is `process.cwd()`, matching tool-fs, so a harness that
+ * trusts one tool's boundary gets the same boundary here.
+ */
+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. */
+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`);
+        this.toolName = toolName;
+        this.path = attemptedPath;
+    }
+}
+/** The workspace root, resolved. Every path is contained within it. */
+export function workspaceRoot() {
+    return path.resolve(process.cwd());
+}
+/**
+ * Resolve `rel` inside the workspace, or throw `ToolPermissionError`.
+ *
+ * The leaf is allowed not to exist — every tool here that creates something
+ * needs to validate a destination before it is made — so the deepest
+ * EXISTING ancestor is realpath'd and the missing tail re-appended. Any
+ * failure other than that walk fails closed.
+ */
+/**
+ * True when the NAME exists, whether or not it leads anywhere.
+ *
+ * `existsSync` FOLLOWS symlinks, so it answers false for a link whose target
+ * is missing — and that is exactly the case that matters: a dangling link is
+ * still a door, because `open(…, "w")` through `evil -> /outside/x` CREATES
+ * `/outside/x`. Probing with `lstat` keeps the link's name in the part of the
+ * path that gets resolved, rather than in the "does not exist yet" tail that
+ * is re-appended to the root verbatim and so passes the containment check.
+ */
+function nameExists(p) {
+    try {
+        lstatSync(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Where `target` would actually land, with every symlink on the way already
+ * followed — including one whose own target does not exist yet.
+ *
+ * `realpathSync` gives up with ENOENT on a dangling link, which would leave
+ * that link unresolved and let it stand in for a plain missing file. So the
+ * deepest ancestor that exists as a NAME is resolved, a dangling one is
+ * followed a hop by hand, and the components that do not exist are appended.
+ * The result is the path an `open` would create, which is the only path worth
+ * checking containment against.
+ */
+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;
+    }
+    let probeReal;
+    try {
+        probeReal = realpathSync(probe);
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            throw err;
+        // The name is there but `realpath` cannot finish it: a symlink with a
+        // missing target. `readlinkSync` throws EINVAL on anything else, which
+        // fails closed.
+        const link = readlinkSync(probe);
+        // A RELATIVE target resolves against the directory that actually CONTAINS
+        // the link, which is not the link's lexical parent when that parent is
+        // itself reached through a symlink. `<root>/dirlink/x -> ../y` with
+        // `dirlink` pointing out of the root really lands at `<elsewhere>/y`, but
+        // measured from the lexical parent it reads as `<root>/y` — an in-root
+        // path the caller's path does not lead to. So the parent is made real
+        // first. An absolute target ignores the base.
+        const base = realpathSync(path.dirname(probe));
+        probeReal = resolveLocation(path.resolve(base, link), depth + 1);
+    }
+    return tail.length > 0 ? path.join(probeReal, ...tail) : probeReal;
+}
+export function resolveSafe(toolName, rel, root = workspaceRoot()) {
+    const rootResolved = path.resolve(root);
+    const abs = path.resolve(rootResolved, rel);
+    // 1) Lexical containment — rejects `..` and absolute escapes. The trailing
+    //    separator avoids the `/root` vs `/root-sibling` prefix pitfall.
+    if (abs !== rootResolved && !abs.startsWith(`${rootResolved}${path.sep}`)) {
+        throw new ToolPermissionError(toolName, rel);
+    }
+    let real;
+    try {
+        const rootReal = realpathSync(rootResolved);
+        real = resolveLocation(abs);
+        // 2) Symlink-aware containment. The real path must land inside the real
+        //    root, so an in-workspace symlink pointing at /etc is refused here.
+        if (real !== rootReal && !real.startsWith(`${rootReal}${path.sep}`)) {
+            throw new ToolPermissionError(toolName, rel);
+        }
+    }
+    catch (err) {
+        if (err instanceof ToolPermissionError)
+            throw err;
+        throw new ToolPermissionError(toolName, rel);
+    }
+    return {
+        abs,
+        real,
+        given: rel,
+        rel: toPosix(path.relative(rootResolved, abs)),
+    };
+}
+/** A path relative to the workspace root, with `/` separators on every OS. */
+export function toPosix(p) {
+    return path.sep === "/" ? p : p.split(path.sep).join("/");
+}
+/**
+ * True when `candidate` is `parent` or lives underneath it. Both must already
+ * be absolute. Used to keep an archive entry, or a symlink inside an
+ * extracted tree, from reaching outside its destination.
+ */
+export function isInside(parent, candidate) {
+    const p = path.resolve(parent);
+    const c = path.resolve(candidate);
+    return c === p || c.startsWith(`${p}${path.sep}`);
+}
+/**
+ * Reject an archive member name that would escape its destination: an
+ * absolute path, a Windows drive prefix, or any `..` segment. Checked on the
+ * NAME, before extraction, because after extraction the damage is done.
+ */
+export function archiveEntryEscapes(name) {
+    const normalized = name.replace(/\\/g, "/");
+    if (normalized.startsWith("/"))
+        return true;
+    if (/^[A-Za-z]:/.test(normalized))
+        return true;
+    return normalized.split("/").some((segment) => segment === "..");
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@crewhaus/tool-secure",
+  "version": "0.7.0",
+  "type": "module",
+  "description": "Deterministic security tools: PII detection and redaction, secret scanning, prompt-injection heuristics, policy checks and evidence hashing",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./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",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@crewhaus/tool-executor": "workspace:*"
+  },
+  "license": "Apache-2.0",
+  "author": {
+    "name": "Max Meier",
+    "email": "max@crewhaus.ai",
+    "url": "https://crewhaus.ai"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/crewhaus/factory.git",
+    "directory": "packages/tool-secure"
+  },
+  "homepage": "https://github.com/crewhaus/factory/tree/main/packages/tool-secure#readme",
+  "bugs": {
+    "url": "https://github.com/crewhaus/factory/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": ["dist", "README.md", "LICENSE", "NOTICE"]
+}