@crewhaus/tool-secure 0.7.0

package/dist/lib/entropy.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Shannon entropy over the symbols a string actually contains.
+ *
+ * ## What this measures
+ *
+ * `H = -Σ p(c) · log2 p(c)`, where `p(c)` is the frequency of character `c`
+ * in THIS string. Units are bits per character. It is a property of the
+ * string's own symbol distribution and nothing else — it has no model of
+ * English, of base64, or of what a key looks like.
+ *
+ * ## What it does not measure
+ *
+ * Not randomness, and not secrecy. `"abcdefgh"` scores a perfect 3.0 bits
+ * per character over its own alphabet while being entirely predictable, and
+ * a genuine 128-bit key rendered as 32 hex characters cannot exceed 4.0
+ * because hex has only 16 symbols. Short strings score low by construction:
+ * a 6-character string cannot exceed log2(6) ≈ 2.58.
+ *
+ * That is why every entropy threshold in this package is paired with a
+ * minimum length and a charset check, and why the threshold is reported
+ * alongside the finding rather than hidden inside it.
+ */
+/** Entropy in bits per character, plus the observed alphabet size. */
+export declare function shannonEntropy(value: string): {
+    bits: number;
+    alphabet: number;
+};
+/**
+ * Round to 4 decimal places so the same input serializes to the same bytes.
+ *
+ * The convention is HALF-UP TOWARDS POSITIVE INFINITY — `Math.round`'s rule,
+ * so 0.00005 rounds to 0.0001 and -0.00005 rounds to -0. Entropy is never
+ * negative, so the asymmetry is unreachable here, but the rule is named
+ * because an unstated rounding mode is how two hosts disagree about a value
+ * they both computed correctly.
+ */
+export declare function roundBits(bits: number): number;
+export type Charset = "hex" | "base64" | "base64url" | "alphanumeric" | "printable" | "mixed";
+/**
+ * Classify the alphabet a string is drawn from. The order matters: the
+ * narrowest matching class wins, because the narrower the alphabet the lower
+ * the entropy ceiling, and thresholds are per-class for exactly that reason.
+ */
+export declare function classifyCharset(value: string): Charset;
+/**
+ * The bits-per-character floor above which a string of this charset is worth
+ * a look. Derived from each alphabet's ceiling (log2 of its size) with room
+ * left for the uneven symbol distribution of a real 32-character sample:
+ * hex tops out at 4.0, base64 at 6.0.
+ *
+ * These are heuristics, stated here so a caller can see and override them.
+ */
+export declare const DEFAULT_ENTROPY_THRESHOLDS: Readonly<Record<Charset, number>>;
+/** The shortest run that the high-entropy rule will consider at all. */
+export declare const MIN_HIGH_ENTROPY_LENGTH = 20;
+/**
+ * Is this string a plausible opaque credential? Length, charset and entropy
+ * together — any one of the three alone is a false-positive machine.
+ */
+export declare function looksHighEntropy(value: string, override?: number): {
+    high: boolean;
+    bits: number;
+    charset: Charset;
+    threshold: number;
+};

package/dist/lib/entropy.js

@@ -0,0 +1,99 @@
+/**
+ * Shannon entropy over the symbols a string actually contains.
+ *
+ * ## What this measures
+ *
+ * `H = -Σ p(c) · log2 p(c)`, where `p(c)` is the frequency of character `c`
+ * in THIS string. Units are bits per character. It is a property of the
+ * string's own symbol distribution and nothing else — it has no model of
+ * English, of base64, or of what a key looks like.
+ *
+ * ## What it does not measure
+ *
+ * Not randomness, and not secrecy. `"abcdefgh"` scores a perfect 3.0 bits
+ * per character over its own alphabet while being entirely predictable, and
+ * a genuine 128-bit key rendered as 32 hex characters cannot exceed 4.0
+ * because hex has only 16 symbols. Short strings score low by construction:
+ * a 6-character string cannot exceed log2(6) ≈ 2.58.
+ *
+ * That is why every entropy threshold in this package is paired with a
+ * minimum length and a charset check, and why the threshold is reported
+ * alongside the finding rather than hidden inside it.
+ */
+/** Entropy in bits per character, plus the observed alphabet size. */
+export function shannonEntropy(value) {
+    if (value.length === 0)
+        return { bits: 0, alphabet: 0 };
+    const counts = new Map();
+    for (const ch of value)
+        counts.set(ch, (counts.get(ch) ?? 0) + 1);
+    const n = [...value].length;
+    let bits = 0;
+    for (const count of counts.values()) {
+        const p = count / n;
+        bits -= p * Math.log2(p);
+    }
+    // Clamp the -0 that a single-symbol string produces.
+    return { bits: bits === 0 ? 0 : bits, alphabet: counts.size };
+}
+/**
+ * Round to 4 decimal places so the same input serializes to the same bytes.
+ *
+ * The convention is HALF-UP TOWARDS POSITIVE INFINITY — `Math.round`'s rule,
+ * so 0.00005 rounds to 0.0001 and -0.00005 rounds to -0. Entropy is never
+ * negative, so the asymmetry is unreachable here, but the rule is named
+ * because an unstated rounding mode is how two hosts disagree about a value
+ * they both computed correctly.
+ */
+export function roundBits(bits) {
+    return Math.round(bits * 10_000) / 10_000;
+}
+/**
+ * Classify the alphabet a string is drawn from. The order matters: the
+ * narrowest matching class wins, because the narrower the alphabet the lower
+ * the entropy ceiling, and thresholds are per-class for exactly that reason.
+ */
+export function classifyCharset(value) {
+    if (value.length === 0)
+        return "mixed";
+    if (/^[0-9a-fA-F]+$/.test(value))
+        return "hex";
+    if (/^[A-Za-z0-9+/]+={0,2}$/.test(value))
+        return "base64";
+    if (/^[A-Za-z0-9_-]+$/.test(value))
+        return "base64url";
+    if (/^[A-Za-z0-9]+$/.test(value))
+        return "alphanumeric";
+    if (/^[\x20-\x7e]+$/.test(value))
+        return "printable";
+    return "mixed";
+}
+/**
+ * The bits-per-character floor above which a string of this charset is worth
+ * a look. Derived from each alphabet's ceiling (log2 of its size) with room
+ * left for the uneven symbol distribution of a real 32-character sample:
+ * hex tops out at 4.0, base64 at 6.0.
+ *
+ * These are heuristics, stated here so a caller can see and override them.
+ */
+export const DEFAULT_ENTROPY_THRESHOLDS = {
+    hex: 3.2,
+    base64: 4.2,
+    base64url: 4.2,
+    alphanumeric: 4.0,
+    printable: 4.0,
+    mixed: 4.0,
+};
+/** The shortest run that the high-entropy rule will consider at all. */
+export const MIN_HIGH_ENTROPY_LENGTH = 20;
+/**
+ * Is this string a plausible opaque credential? Length, charset and entropy
+ * together — any one of the three alone is a false-positive machine.
+ */
+export function looksHighEntropy(value, override) {
+    const charset = classifyCharset(value);
+    const threshold = override ?? DEFAULT_ENTROPY_THRESHOLDS[charset];
+    const { bits } = shannonEntropy(value);
+    const high = value.length >= MIN_HIGH_ENTROPY_LENGTH && bits >= threshold;
+    return { high, bits: roundBits(bits), charset, threshold };
+}

package/dist/lib/evidence.d.ts

@@ -0,0 +1,55 @@
+/** Digest algorithms this package will use, and why each is here. */
+export declare const HASH_ALGORITHMS: readonly ["sha256", "sha384", "sha512", "sha1"];
+export type HashAlgorithm = (typeof HASH_ALGORITHMS)[number];
+export declare const SIGNATURE_ENCODINGS: readonly ["hex", "base64url"];
+export type SignatureEncoding = (typeof SIGNATURE_ENCODINGS)[number];
+/** Bounds a chain: verification is linear, but the result is not. */
+export declare const MAX_CHAIN_RECORDS = 50000;
+export declare class EvidenceError extends Error {
+    readonly name = "EvidenceError";
+}
+export type ChainRecord = {
+    readonly data: string;
+    readonly prevHash: string;
+    readonly hash: string;
+};
+export type ChainOptions = {
+    readonly algorithm?: HashAlgorithm;
+    readonly separator?: string;
+    readonly genesisPrevHash?: string;
+};
+export type ChainBreak = {
+    readonly index: number;
+    readonly kind: "link.mismatch" | "hash.mismatch";
+    readonly expected: string;
+    readonly actual: string;
+    readonly explanation: string;
+};
+export type ChainResult = {
+    readonly ok: boolean;
+    readonly length: number;
+    readonly algorithm: HashAlgorithm;
+    /** Records checked before stopping. Equals `length` for an intact chain. */
+    readonly verified: number;
+    readonly headHash?: string;
+    readonly firstBreak?: ChainBreak;
+};
+/** One link, by the convention documented above. */
+export declare function computeLink(prevHash: string, data: string, algorithm?: HashAlgorithm, separator?: string): string;
+/**
+ * Walk the chain and stop at the first break.
+ *
+ * Stopping is the point: after a break every later hash is computed over
+ * altered material, so continuing would report a cascade of failures that
+ * all have one cause. The index reported is where to look.
+ */
+export declare function verifyChain(records: ReadonlyArray<ChainRecord>, options?: ChainOptions): ChainResult;
+/** HMAC over a payload. The key never appears in the result. */
+export declare function signPayload(key: string, payload: string, algorithm?: HashAlgorithm, encoding?: SignatureEncoding): string;
+/**
+ * Constant-time verification via the double-HMAC comparison described above.
+ * A malformed signature is a `false`, not a throw.
+ */
+export declare function verifyPayload(key: string, payload: string, signature: string, algorithm?: HashAlgorithm, encoding?: SignatureEncoding): boolean;
+/** SHA-256 of a string, hex. Used for evidence records about a document. */
+export declare function sha256Hex(value: string): string;

package/dist/lib/evidence.js

@@ -0,0 +1,134 @@
+/**
+ * Evidence that a record was not altered: hash chains and HMAC signatures.
+ *
+ * ## The hash-chain convention, stated exactly
+ *
+ * A record is `{ data, prevHash, hash }`, all strings, and the link is
+ *
+ *     hash = hex( H( prevHash + separator + data ) )
+ *
+ * with `separator` defaulting to `"\n"`, `H` defaulting to SHA-256, and the
+ * first record's `prevHash` defaulting to the empty string. Every part is an
+ * input because chains in the wild differ on all of them, and a verifier
+ * that guesses is a verifier that returns a confidently wrong "valid".
+ *
+ * `data` must be a string the producer already canonicalized. This module
+ * deliberately does not serialize objects for you: two JSON encoders
+ * disagree about key order and number formatting, and a chain that verifies
+ * under one and not the other is worse than no chain at all.
+ *
+ * ## What a valid chain proves
+ *
+ * That these records are internally consistent — nobody edited one without
+ * recomputing every hash after it. It does NOT prove who wrote them or when,
+ * and an attacker who can rewrite the whole sequence can produce a perfectly
+ * valid chain. For that you need a signature over the head, which is what
+ * `SignPayload` is for, or an external anchor.
+ *
+ * ## Signature comparison
+ *
+ * Verification compares `HMAC(key, expectedSignature)` with
+ * `HMAC(key, providedSignature)` rather than the signatures themselves. The
+ * two HMACs are always the same length, so `timingSafeEqual` can be used
+ * even when the caller supplies a signature of the wrong length, and an
+ * attacker cannot learn the expected bytes from how long the comparison
+ * took.
+ */
+import { createHash, createHmac, timingSafeEqual } from "node:crypto";
+/** Digest algorithms this package will use, and why each is here. */
+export const HASH_ALGORITHMS = ["sha256", "sha384", "sha512", "sha1"];
+export const SIGNATURE_ENCODINGS = ["hex", "base64url"];
+/** Bounds a chain: verification is linear, but the result is not. */
+export const MAX_CHAIN_RECORDS = 50_000;
+export class EvidenceError extends Error {
+    name = "EvidenceError";
+}
+/** One link, by the convention documented above. */
+export function computeLink(prevHash, data, algorithm = "sha256", separator = "\n") {
+    return createHash(algorithm).update(`${prevHash}${separator}${data}`, "utf8").digest("hex");
+}
+/**
+ * Walk the chain and stop at the first break.
+ *
+ * Stopping is the point: after a break every later hash is computed over
+ * altered material, so continuing would report a cascade of failures that
+ * all have one cause. The index reported is where to look.
+ */
+export function verifyChain(records, options = {}) {
+    if (records.length > MAX_CHAIN_RECORDS) {
+        throw new EvidenceError(`${records.length} records, over the ${MAX_CHAIN_RECORDS} limit — verify the chain in segments`);
+    }
+    const algorithm = options.algorithm ?? "sha256";
+    const separator = options.separator ?? "\n";
+    const genesis = options.genesisPrevHash ?? "";
+    let previousHash = genesis;
+    for (let i = 0; i < records.length; i++) {
+        const record = records[i];
+        if (!record)
+            continue;
+        if (record.prevHash !== previousHash) {
+            return {
+                ok: false,
+                length: records.length,
+                algorithm,
+                verified: i,
+                firstBreak: {
+                    index: i,
+                    kind: "link.mismatch",
+                    expected: previousHash,
+                    actual: record.prevHash,
+                    explanation: i === 0
+                        ? "the first record's prevHash is not the genesis value — pass genesisPrevHash if this chain starts somewhere else"
+                        : "this record does not point at the previous record's hash: a record was inserted, removed or reordered",
+                },
+            };
+        }
+        const expected = computeLink(record.prevHash, record.data, algorithm, separator);
+        if (expected !== record.hash) {
+            return {
+                ok: false,
+                length: records.length,
+                algorithm,
+                verified: i,
+                firstBreak: {
+                    index: i,
+                    kind: "hash.mismatch",
+                    expected,
+                    actual: record.hash,
+                    explanation: "the stored hash does not match this record's own data: the data was altered, or it was hashed under a different algorithm or separator",
+                },
+            };
+        }
+        previousHash = record.hash;
+    }
+    return {
+        ok: true,
+        length: records.length,
+        algorithm,
+        verified: records.length,
+        ...(records.length > 0 ? { headHash: previousHash } : {}),
+    };
+}
+/** Encode a digest in the requested form. */
+function encode(buffer, encoding) {
+    return encoding === "hex" ? buffer.toString("hex") : buffer.toString("base64url");
+}
+/** HMAC over a payload. The key never appears in the result. */
+export function signPayload(key, payload, algorithm = "sha256", encoding = "hex") {
+    return encode(createHmac(algorithm, key).update(payload, "utf8").digest(), encoding);
+}
+/**
+ * Constant-time verification via the double-HMAC comparison described above.
+ * A malformed signature is a `false`, not a throw.
+ */
+export function verifyPayload(key, payload, signature, algorithm = "sha256", encoding = "hex") {
+    const expected = signPayload(key, payload, algorithm, encoding);
+    const blind = (value) => createHmac(algorithm, key).update(value, "utf8").digest();
+    const a = blind(expected);
+    const b = blind(signature);
+    return a.length === b.length && timingSafeEqual(a, b);
+}
+/** SHA-256 of a string, hex. Used for evidence records about a document. */
+export function sha256Hex(value) {
+    return createHash("sha256").update(value, "utf8").digest("hex");
+}

package/dist/lib/files.d.ts

@@ -0,0 +1,71 @@
+import { type SafePath } from "../paths";
+/** Default per-file ceiling. Generous for source, refuses a database dump. */
+export declare const DEFAULT_MAX_FILE_BYTES: number;
+/** Hard ceiling a caller cannot raise past. */
+export declare const MAX_FILE_BYTES_LIMIT: number;
+/** Directories skipped unless the caller names them explicitly. */
+export declare const DEFAULT_SKIP_DIRS: ReadonlyArray<string>;
+/**
+ * Why a path in the tree was not scanned.
+ *
+ * The first three are read failures. The last three are DELIBERATE
+ * exclusions, and they are listed for the same reason the others are: a
+ * secret scanner whose walk quietly drops `.env`, `node_modules/` and every
+ * symlink, and then returns `skipped: []`, is telling the caller it covered
+ * a tree it did not open.
+ */
+export type SkipReason = "too-large" | "binary" | "unreadable" | "symlink" | "hidden" | "excluded-directory";
+export type ScannedFile = {
+    /** Slash-separated, relative to the scan root. */
+    readonly rel: string;
+    readonly abs: string;
+    readonly bytes: number;
+    readonly text: string;
+};
+export type SkippedFile = {
+    readonly rel: string;
+    readonly reason: SkipReason;
+    readonly detail: string;
+};
+export type WalkLimits = {
+    readonly maxFiles: number;
+    readonly maxDepth: number;
+    readonly maxFileBytes: number;
+    readonly includeHidden: boolean;
+    readonly skipDirs: ReadonlyArray<string>;
+};
+export declare const DEFAULT_WALK_LIMITS: WalkLimits;
+export type ReadOutcome = {
+    readonly ok: true;
+    readonly text: string;
+    readonly bytes: number;
+} | {
+    readonly ok: false;
+    readonly reason: SkipReason;
+    readonly detail: string;
+};
+/**
+ * Read a file as UTF-8, refusing it when it is too large or not text.
+ *
+ * The size check happens against the open descriptor before a single byte is
+ * buffered, which is what makes the limit a memory bound rather than a
+ * post-hoc complaint.
+ */
+export declare function readTextBounded(toolName: string, abs: string, maxBytes: number): ReadOutcome;
+export type WalkOutcome = {
+    readonly files: ReadonlyArray<ScannedFile>;
+    readonly skipped: ReadonlyArray<SkippedFile>;
+    /** True when the entry cap or the depth cap cut the walk short. */
+    readonly truncated: boolean;
+    readonly depthLimited: boolean;
+};
+/**
+ * Collect the readable text files under `root`, depth-first in sorted order.
+ *
+ * Symlinks are named in `skipped` but never followed, for containment and to
+ * make cycles impossible rather than merely unlikely. So are dot-entries and
+ * the default-excluded directories: what was not opened is always said.
+ */
+export declare function walkTextFiles(toolName: string, root: SafePath, limits?: WalkLimits): WalkOutcome;
+/** Relative, slash-separated label for a path inside the workspace. */
+export declare function relLabel(safe: SafePath): string;

package/dist/lib/files.js

@@ -0,0 +1,227 @@
+/**
+ * The only filesystem access in this package, kept in one place so the
+ * bounds are in one place too.
+ *
+ * Three properties hold for every read here:
+ *
+ *   1. CONTAINMENT. The caller's path has already been through
+ *      `resolveSafe`; directories are walked without following symlinks, so
+ *      a link inside the workspace cannot walk the scan out of it.
+ *   2. BOUNDED MEMORY. A file's size is taken from its open descriptor and
+ *      compared with the limit BEFORE any bytes are read. A limit applied
+ *      after buffering is not a limit.
+ *   3. BOUNDED WORK. The walk has an entry cap and a depth cap, and both are
+ *      reported when they bite, so a truncated scan never looks complete.
+ *   4. NO SILENT EXCLUSION. Everything the walk declines to open — a symlink,
+ *      a dot-file, an excluded directory, a binary, an oversized file — is
+ *      named in `skipped` with the reason. A scanner that drops `.env` and
+ *      `node_modules/` and then reports `skipped: []` is claiming coverage it
+ *      does not have, which is the only failure here that gets someone hurt.
+ *
+ * Determinism: entries are sorted with plain string comparison, so the same
+ * tree produces the same listing and the same truncation point on any host.
+ */
+import { closeSync, constants as fsConstants, fstatSync, openSync, readSync, readdirSync, } from "node:fs";
+import * as path from "node:path";
+import { ToolPermissionError, toPosix } from "../paths";
+import { compareStrings } from "./text";
+/** Default per-file ceiling. Generous for source, refuses a database dump. */
+export const DEFAULT_MAX_FILE_BYTES = 1024 * 1024;
+/** Hard ceiling a caller cannot raise past. */
+export const MAX_FILE_BYTES_LIMIT = 16 * 1024 * 1024;
+/** How much of a file is inspected for NUL bytes before calling it binary. */
+const BINARY_PROBE_BYTES = 8192;
+/** Directories skipped unless the caller names them explicitly. */
+export const DEFAULT_SKIP_DIRS = [
+    ".git",
+    ".hg",
+    ".svn",
+    "node_modules",
+    "dist",
+    "build",
+    "coverage",
+    ".next",
+    ".turbo",
+    ".venv",
+    "__pycache__",
+];
+export const DEFAULT_WALK_LIMITS = {
+    maxFiles: 2000,
+    maxDepth: 12,
+    maxFileBytes: DEFAULT_MAX_FILE_BYTES,
+    includeHidden: false,
+    skipDirs: DEFAULT_SKIP_DIRS,
+};
+/**
+ * Open without following a final symlink. `resolveSafe` proved containment,
+ * but the leaf could be swapped between the check and the open (CWE-367);
+ * refusing to follow it closes that window.
+ */
+function openNoFollow(toolName, abs) {
+    try {
+        return openSync(abs, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
+    }
+    catch (err) {
+        if (err.code === "ELOOP") {
+            throw new ToolPermissionError(toolName, abs);
+        }
+        throw err;
+    }
+}
+/**
+ * Read a file as UTF-8, refusing it when it is too large or not text.
+ *
+ * The size check happens against the open descriptor before a single byte is
+ * buffered, which is what makes the limit a memory bound rather than a
+ * post-hoc complaint.
+ */
+export function readTextBounded(toolName, abs, maxBytes) {
+    let fd;
+    try {
+        fd = openNoFollow(toolName, abs);
+    }
+    catch (err) {
+        if (err instanceof ToolPermissionError)
+            throw err;
+        return { ok: false, reason: "unreadable", detail: err.message };
+    }
+    try {
+        const stat = fstatSync(fd);
+        // A directory is not an oversized file, and the order of these two checks
+        // is load-bearing. A directory's st_size is 4096 on ext4 and a handful of
+        // bytes on APFS, so comparing it against the per-file cap first made
+        // `SecretScan({path: ".", maxFileBytes: 100})` walk the tree on macOS and
+        // refuse it outright on Linux — reported as a skipped oversized file
+        // rather than as a scan that covered nothing.
+        if (stat.isDirectory()) {
+            return { ok: false, reason: "unreadable", detail: "is a directory" };
+        }
+        const { size } = stat;
+        if (size > maxBytes) {
+            return {
+                ok: false,
+                reason: "too-large",
+                detail: `${size} bytes, over the ${maxBytes}-byte per-file limit`,
+            };
+        }
+        const probeLength = Math.min(size, BINARY_PROBE_BYTES);
+        const probe = Buffer.allocUnsafe(probeLength);
+        if (probeLength > 0)
+            readSync(fd, probe, 0, probeLength, 0);
+        if (probe.includes(0)) {
+            return { ok: false, reason: "binary", detail: "a NUL byte appears in the first 8 KiB" };
+        }
+        const buffer = Buffer.allocUnsafe(size);
+        let offset = 0;
+        while (offset < size) {
+            const read = readSync(fd, buffer, offset, size - offset, offset);
+            if (read <= 0)
+                break;
+            offset += read;
+        }
+        return { ok: true, text: buffer.subarray(0, offset).toString("utf8"), bytes: offset };
+    }
+    catch (err) {
+        return { ok: false, reason: "unreadable", detail: err.message };
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/**
+ * Collect the readable text files under `root`, depth-first in sorted order.
+ *
+ * Symlinks are named in `skipped` but never followed, for containment and to
+ * make cycles impossible rather than merely unlikely. So are dot-entries and
+ * the default-excluded directories: what was not opened is always said.
+ */
+export function walkTextFiles(toolName, root, limits = DEFAULT_WALK_LIMITS) {
+    const files = [];
+    const skipped = [];
+    let truncated = false;
+    let depthLimited = false;
+    const skipDirs = new Set(limits.skipDirs);
+    const visit = (dir, rel, depth) => {
+        if (files.length >= limits.maxFiles) {
+            truncated = true;
+            return;
+        }
+        if (depth > limits.maxDepth) {
+            depthLimited = true;
+            return;
+        }
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch (err) {
+            skipped.push({
+                rel: rel === "" ? "." : rel,
+                reason: "unreadable",
+                detail: err.message,
+            });
+            return;
+        }
+        entries.sort((a, b) => compareStrings(a.name, b.name));
+        for (const entry of entries) {
+            if (files.length >= limits.maxFiles) {
+                truncated = true;
+                return;
+            }
+            const childRel = rel === "" ? entry.name : `${rel}/${entry.name}`;
+            const childAbs = path.join(dir, entry.name);
+            if (!limits.includeHidden && entry.name.startsWith(".")) {
+                skipped.push({
+                    rel: childRel,
+                    reason: "hidden",
+                    detail: "a dot-file or dot-directory; pass includeHidden to scan it",
+                });
+                continue;
+            }
+            if (entry.isSymbolicLink()) {
+                // Never followed, for containment and to make cycles impossible —
+                // but named, so the caller knows this path went unread.
+                skipped.push({
+                    rel: childRel,
+                    reason: "symlink",
+                    detail: "a symbolic link; links are never followed, so its target was not scanned",
+                });
+                continue;
+            }
+            if (entry.isDirectory()) {
+                if (skipDirs.has(entry.name)) {
+                    skipped.push({
+                        rel: childRel,
+                        reason: "excluded-directory",
+                        detail: `"${entry.name}" is excluded by default; nothing under it was scanned`,
+                    });
+                    continue;
+                }
+                visit(childAbs, childRel, depth + 1);
+                continue;
+            }
+            if (!entry.isFile()) {
+                skipped.push({
+                    rel: childRel,
+                    reason: "unreadable",
+                    detail: "not a regular file (socket, fifo or device); nothing was read from it",
+                });
+                continue;
+            }
+            const outcome = readTextBounded(toolName, childAbs, limits.maxFileBytes);
+            if (!outcome.ok) {
+                skipped.push({ rel: childRel, reason: outcome.reason, detail: outcome.detail });
+                continue;
+            }
+            files.push({ rel: childRel, abs: childAbs, bytes: outcome.bytes, text: outcome.text });
+        }
+    };
+    visit(root.real, "", 1);
+    files.sort((a, b) => compareStrings(a.rel, b.rel));
+    skipped.sort((a, b) => compareStrings(a.rel, b.rel) || compareStrings(a.reason, b.reason));
+    return { files, skipped, truncated, depthLimited };
+}
+/** Relative, slash-separated label for a path inside the workspace. */
+export function relLabel(safe) {
+    return safe.rel === "" ? "." : toPosix(safe.rel);
+}