clinkx 0.3.0 → 1.0.0

package/clinkx-workflows/dist/contained-file.d.ts

@@ -0,0 +1,172 @@
+/**
+ * Containment-safe, no-follow file reads.
+ *
+ * Extracted from the private sidecar reader in `workflow-tools.ts` so the
+ * plan-review snapshot/contract paths reuse ONE audited implementation instead
+ * of hand-rolling a second realpath+O_NOFOLLOW dance.
+ *
+ * The invariant every caller depends on: a single file handle backs both the
+ * stat and the read, so there is no check/use window, and `O_NOFOLLOW` rejects
+ * a final-component symlink swapped in after the containment check.
+ */
+/**
+ * Structured discriminator for the subset of policy violations that callers must
+ * be able to branch on WITHOUT matching message wording.
+ *
+ * Deliberately NOT a taxonomy over every throw site: only the allowed-roots
+ * containment failure carries a reason today, because it is the only one a
+ * caller (plan-review's snapshot root hint) must distinguish. The other throw
+ * sites leave `reason` undefined rather than grow a speculative enum.
+ */
+export type ContainedFilePolicyReason = "outside_allowed_roots";
+export interface ContainedFileFingerprint {
+    readonly dev: bigint;
+    readonly ino: bigint;
+    readonly mtimeNs: bigint;
+    readonly ctimeNs: bigint;
+    readonly size: bigint;
+    readonly nlink: bigint;
+}
+export interface ContainedReadBeforeCloseContext {
+    readonly fingerprint: ContainedFileFingerprint;
+    /** Resolve the authoritative path for the still-open descriptor. */
+    readonly resolveRealPath: () => Promise<string | undefined>;
+}
+/**
+ * `expectedPath` is OPTIONAL so an injected one-argument verifier (every test
+ * seam in this repo) stays assignable. Callers that know the pathname they
+ * opened should always pass it: it selects the cheap darwin verification path
+ * described on {@link resolveOpenedDescriptorPath}.
+ */
+export type OpenedDescriptorPathVerifier = (fd: number, expectedPath?: string) => Promise<string | undefined>;
+/**
+ * A containment/policy violation (absolute where relative is required, escape
+ * outside the root, symlink, non-regular file). Distinct from a plain Error so
+ * callers can tell "you may not read this" from "it is not there right now".
+ */
+export declare class ContainedFilePolicyError extends Error {
+    readonly reason: ContainedFilePolicyReason | undefined;
+    constructor(message: string, reason?: ContainedFilePolicyReason);
+}
+export declare class ContainedFileChangedError extends ContainedFilePolicyError {
+    constructor(message: string);
+}
+export declare class ContainedFileTooLargeError extends ContainedFilePolicyError {
+    readonly size: number | undefined;
+    readonly fingerprint: ContainedFileFingerprint | undefined;
+    constructor(message: string, size?: number, fingerprint?: ContainedFileFingerprint);
+}
+export interface ContainedReadOptions {
+    /** Return the file body decoded as UTF-8. */
+    readonly wantContent?: boolean | undefined;
+    /** Return the raw file body. Mutually usable with `wantContent`. */
+    readonly wantBytes?: boolean | undefined;
+    /** Reject anything that is not a regular file (fstat on the open handle). */
+    readonly requireRegular?: boolean | undefined;
+    /**
+     * Wording for policy-violation messages, e.g. `"run directory"`. Callers with
+     * an established message contract pass their own noun so extracting this
+     * module did not silently reword their errors.
+     */
+    readonly containerLabel?: string | undefined;
+    /** Wording for the path itself, e.g. `"outputPath"`. */
+    readonly pathLabel?: string | undefined;
+    /** Reject larger files before allocating their body. */
+    readonly maxBytes?: number | undefined;
+    /** Deterministic race-injection seam used by containment regression tests. */
+    readonly beforeOpen?: (() => void) | undefined;
+    /** Deterministic seam after open but before descriptor-path resolution. */
+    readonly afterOpen?: (() => void) | undefined;
+    /** Verify caller-owned invariants while the admitted descriptor is still open. */
+    readonly beforeClose?: (context: ContainedReadBeforeCloseContext) => void | Promise<void>;
+    /** Injectable platform adapter for authoritative descriptor-path resolution. */
+    readonly descriptorPathVerifier?: OpenedDescriptorPathVerifier | undefined;
+    /**
+     * Require the opened descriptor to remain at the lexical canonical path
+     * requested under `rootDir`, rather than merely somewhere inside that root.
+     * Dashboard state/body reads opt in; shared callers retain containment-only
+     * behavior.
+     */
+    readonly requireExactRequestedPath?: boolean | undefined;
+}
+export interface ContainedReadResult {
+    readonly size: number;
+    readonly content?: string | undefined;
+    readonly bytes?: Buffer | undefined;
+    /** The canonical path actually opened. */
+    readonly realPath: string;
+    /** BigInt identity/content tuple captured from the same handle as the body. */
+    readonly fingerprint: ContainedFileFingerprint;
+}
+export declare function containedFileFingerprintsEqual(left: ContainedFileFingerprint, right: ContainedFileFingerprint): boolean;
+/**
+ * Resolve a verified path for an already-open descriptor. Authoritative on
+ * Linux; on darwin the check is probabilistic — see below. Unsupported
+ * platforms and helper failures fail closed (`undefined`).
+ *
+ * WITHOUT an `expectedPath`, Linux reads `/proc/self/fd/<fd>`, which the
+ * kernel answers from the descriptor itself. Darwin has no equivalent and
+ * falls through to the historical `lsof` helper.
+ *
+ * WITH an `expectedPath` (linux and darwin) this canonicalizes
+ * `P = realpath(expectedPath)`, then `lstat`s `P` and compares `(dev, ino)`
+ * against an `fstat` of the descriptor. That pair is NOT atomic: it is two
+ * independent walks of a mutable pathname, microseconds apart, and `lstat` is
+ * no-follow only on the FINAL component — every intermediate component is
+ * resolved again. An ancestor swapped between the two walks can steer the
+ * `lstat` onto the same out-of-root inode the descriptor holds, so the
+ * comparison passes while the returned string still reads as in-root; the
+ * caller's containment re-assert then succeeds on a path that no longer
+ * describes the opened bytes. `P` is returned for that re-assert, which is
+ * deliberately NOT done here (this helper holds no roots).
+ *
+ * Ancestor ABA restoration defeats the mitigation outright: restore the
+ * original ancestor before the caller's post-read re-verify and both the verify
+ * and the re-verify agree — the re-verify's string comparison against the first
+ * result then matches by construction.
+ *
+ * So the darwin guarantee RAISES THE COST of a race rather than eliminating it:
+ * three adjacent synchronous syscalls with no `await` between them, and callers
+ * verify twice, so the window must be won twice. It is meaningful only under a
+ * trusted-local-filesystem threat model — NOT against an adversary with
+ * concurrent write access to any ancestor directory.
+ *
+ * No stronger in-process guarantee exists to reach for: Node exposes no
+ * `openat`, no `AT_*` constants, and no dirfd-accepting API, so a
+ * descriptor-relative no-follow walk cannot be expressed at all, and darwin's
+ * `/dev/fd/<fd>` is not traversable. The residual is accepted deliberately, not
+ * overlooked; closing it would require a native addon.
+ *
+ * `lstatSync`, not `statSync`, on purpose: `realpathSync.native` has already
+ * resolved every symlink in `P`, so the final component can only be a symlink
+ * if one was swapped in AFTER that resolve. `lstat` fails closed on that swap;
+ * `stat` would follow it. Same syscall cost, strictly stronger.
+ *
+ * What it does NOT prove: that the descriptor has no OTHER name. An out-of-root
+ * hardlink alias to the same inode is not detected. `fcntl(F_GETPATH)` would not
+ * fix that either — it reads the same darwin vnode name cache, which holds one
+ * name per inode and is rewritten by the most recent lookup.
+ *
+ * WITHOUT an `expectedPath` the historical `lsof` implementation is retained
+ * verbatim, so an unmigrated caller keeps today's exact behavior instead of
+ * silently downgrading to a weaker check it never opted into.
+ */
+export declare function resolveOpenedDescriptorPath(fd: number, expectedPath?: string): Promise<string | undefined>;
+/**
+ * Read a run-relative sidecar. `relPath` MUST be relative to `rootDir`.
+ *
+ * Realpaths BOTH sides: on macOS `/tmp` (and mkdtemp dirs) is itself a symlink
+ * to `/private/tmp`, so realpathing only the target would false-reject a
+ * legitimate read.
+ */
+export declare function readContainedRelativeFile(rootDir: string, relPath: string, options?: ContainedReadOptions): Promise<ContainedReadResult>;
+/**
+ * Read an absolute path that must live inside at least one allowed root.
+ *
+ * Unlike {@link readContainedRelativeFile} this deliberately does NOT realpath
+ * the target before opening: resolving the final component would silently
+ * follow a symlink and defeat the "reject symlink" requirement. Only the
+ * PARENT is canonicalized for the containment check; `O_NOFOLLOW` then rejects
+ * a symlinked final component at open time.
+ */
+export declare function readContainedAbsoluteFile(allowedRoots: readonly string[], targetPath: string, options?: ContainedReadOptions): Promise<ContainedReadResult>;

package/clinkx-workflows/dist/contained-file.js

@@ -0,0 +1,483 @@
+/**
+ * Containment-safe, no-follow file reads.
+ *
+ * Extracted from the private sidecar reader in `workflow-tools.ts` so the
+ * plan-review snapshot/contract paths reuse ONE audited implementation instead
+ * of hand-rolling a second realpath+O_NOFOLLOW dance.
+ *
+ * The invariant every caller depends on: a single file handle backs both the
+ * stat and the read, so there is no check/use window, and `O_NOFOLLOW` rejects
+ * a final-component symlink swapped in after the containment check.
+ */
+import { spawn } from "node:child_process";
+import { constants as fsConstants, fstatSync, lstatSync, realpathSync, } from "node:fs";
+import { open } from "node:fs/promises";
+import { basename, isAbsolute, relative, resolve, sep } from "node:path";
+/**
+ * A containment/policy violation (absolute where relative is required, escape
+ * outside the root, symlink, non-regular file). Distinct from a plain Error so
+ * callers can tell "you may not read this" from "it is not there right now".
+ */
+export class ContainedFilePolicyError extends Error {
+    // Always assigned (never an optional property): this package enables
+    // `exactOptionalPropertyTypes`, under which an `reason?:` declaration would
+    // reject an explicit `undefined` assignment.
+    reason;
+    constructor(message, reason) {
+        super(message);
+        this.name = "ContainedFilePolicyError";
+        this.reason = reason;
+    }
+}
+export class ContainedFileChangedError extends ContainedFilePolicyError {
+    constructor(message) {
+        super(message);
+        this.name = "ContainedFileChangedError";
+    }
+}
+export class ContainedFileTooLargeError extends ContainedFilePolicyError {
+    size;
+    fingerprint;
+    constructor(message, size, fingerprint) {
+        super(message);
+        this.name = "ContainedFileTooLargeError";
+        this.size = size;
+        this.fingerprint = fingerprint;
+    }
+}
+function fingerprintFromStats(stats) {
+    return {
+        dev: stats.dev,
+        ino: stats.ino,
+        mtimeNs: stats.mtimeNs,
+        ctimeNs: stats.ctimeNs,
+        size: stats.size,
+        nlink: stats.nlink,
+    };
+}
+export function containedFileFingerprintsEqual(left, right) {
+    return left.dev === right.dev &&
+        left.ino === right.ino &&
+        left.mtimeNs === right.mtimeNs &&
+        left.ctimeNs === right.ctimeNs &&
+        left.size === right.size &&
+        left.nlink === right.nlink;
+}
+/**
+ * Open `realTarget` once with no-follow semantics and serve every requested
+ * projection (size / bytes / text) from that SAME handle.
+ */
+async function readOpenedContained(realTarget, realRoots, options, exactRequestedPath) {
+    // O_NOFOLLOW rejects a final-component symlink swapped in between the
+    // containment check and this open — closing the check/use TOCTOU window.
+    // When the caller requires a regular file, also admit the descriptor
+    // non-blockingly: a FIFO (or other special file) opened O_RDONLY alone blocks
+    // until a writer connects, which would hang the reader indefinitely BEFORE the
+    // requireRegular fstat can reject it. O_NONBLOCK makes that open return at
+    // once so the non-regular file is rejected promptly. It is a no-op for regular
+    // files (their reads never return EAGAIN), so gating it on requireRegular
+    // preserves byte-identical behavior for every shared caller that does not opt
+    // into the regular-file requirement.
+    const requireRegular = options.requireRegular === true;
+    const flags = fsConstants.O_RDONLY |
+        (fsConstants.O_NOFOLLOW ?? 0) |
+        (requireRegular ? (fsConstants.O_NONBLOCK ?? 0) : 0);
+    const verifyDescriptorPath = options.descriptorPathVerifier ??
+        resolveOpenedDescriptorPath;
+    options.beforeOpen?.();
+    const fh = await open(realTarget, flags);
+    try {
+        const stats = await fh.stat({ bigint: true });
+        const fingerprint = fingerprintFromStats(stats);
+        // Reject a non-regular file (FIFO, device, ...) right after the same-handle
+        // fstat, BEFORE descriptor-path resolution and reads. For a FIFO this is the
+        // case O_NONBLOCK admission exists to make reachable: without it the open
+        // above would still be blocked here. Moving the check ahead of the expensive
+        // descriptor-path lookup also avoids spawning lsof for a file that will be
+        // rejected anyway.
+        if (requireRegular && !stats.isFile()) {
+            throw new ContainedFilePolicyError(`Path is not a regular file: ${realTarget}`);
+        }
+        options.afterOpen?.();
+        const openedRealPath = await verifyDescriptorPath(fh.fd, realTarget);
+        if (openedRealPath === undefined) {
+            throw new ContainedFilePolicyError(`Opened file descriptor containment could not be verified: ${realTarget}`);
+        }
+        if (!realRoots.some((root) => containsPath(root, openedRealPath))) {
+            throw new ContainedFilePolicyError(`Opened file escaped its containing root: ${realTarget}`);
+        }
+        if (exactRequestedPath !== undefined &&
+            openedRealPath !== exactRequestedPath) {
+            throw new ContainedFilePolicyError(`Opened file did not match its requested path: ${realTarget}`);
+        }
+        const exceedsMaxBytes = options.maxBytes !== undefined &&
+            Number(stats.size) > options.maxBytes;
+        // Read into a buffer sized from the checked handle stat. Unlike readFile(),
+        // this cannot allocate past the admitted size if the file grows while the
+        // read is in progress. A one-byte probe detects growth without widening the
+        // allocation bound.
+        let bytes;
+        let extraByteRead = false;
+        if (!exceedsMaxBytes && (options.wantBytes === true || options.wantContent === true)) {
+            bytes = Buffer.allocUnsafe(Number(stats.size));
+            let offset = 0;
+            while (offset < bytes.length) {
+                const chunk = await fh.read(bytes, offset, bytes.length - offset, null);
+                if (chunk.bytesRead === 0)
+                    break;
+                offset += chunk.bytesRead;
+            }
+            const probe = Buffer.allocUnsafe(1);
+            extraByteRead = (await fh.read(probe, 0, 1, null)).bytesRead > 0;
+            if (BigInt(offset) !== stats.size) {
+                bytes = bytes.subarray(0, offset);
+            }
+        }
+        const afterStats = await fh.stat({ bigint: true });
+        if (bytes !== undefined &&
+            (afterStats.size !== stats.size ||
+                BigInt(bytes.byteLength) !== stats.size ||
+                extraByteRead)) {
+            throw new ContainedFileChangedError(`File changed while it was being read: ${realTarget}`);
+        }
+        const afterFingerprint = fingerprintFromStats(afterStats);
+        if (!containedFileFingerprintsEqual(fingerprint, afterFingerprint) ||
+            afterFingerprint.nlink === 0n) {
+            throw new ContainedFileChangedError(`File changed while it was being read: ${realTarget}`);
+        }
+        // `openedRealPath` was resolved from this exact live descriptor after open.
+        // The caller's before-close hook may need that authoritative admission path,
+        // but resolving it a second time is redundant: the unconditional final
+        // descriptor lookup below still detects any rename/unlink that occurs before
+        // commit. On Darwin this avoids one `lsof` subprocess per admitted file
+        // without weakening the final post-hook path check.
+        await options.beforeClose?.({
+            fingerprint: afterFingerprint,
+            resolveRealPath: async () => openedRealPath,
+        });
+        const finalStats = await fh.stat({ bigint: true });
+        const finalFingerprint = fingerprintFromStats(finalStats);
+        const finalRealPath = await verifyDescriptorPath(fh.fd, realTarget);
+        if (!containedFileFingerprintsEqual(fingerprint, finalFingerprint) ||
+            finalFingerprint.nlink === 0n ||
+            finalRealPath === undefined ||
+            finalRealPath !== openedRealPath ||
+            (exactRequestedPath !== undefined &&
+                finalRealPath !== exactRequestedPath) ||
+            !realRoots.some((root) => containsPath(root, finalRealPath))) {
+            throw new ContainedFileChangedError(`File changed while it was being read: ${realTarget}`);
+        }
+        if (exceedsMaxBytes) {
+            throw new ContainedFileTooLargeError(`File exceeds the ${String(options.maxBytes)} byte limit: ${realTarget}`, Number(finalStats.size), finalFingerprint);
+        }
+        const result = {
+            size: Number(finalStats.size),
+            realPath: finalRealPath,
+            ...(options.wantContent === true
+                ? { content: bytes.toString("utf-8") }
+                : {}),
+            ...(options.wantBytes === true ? { bytes } : {}),
+        };
+        // Preserve the historical whole-result JSON shape. BigInt cannot be encoded
+        // by JSON.stringify, while callers that need cache identity access the
+        // fingerprint explicitly through the typed interface.
+        Object.defineProperty(result, "fingerprint", {
+            configurable: false,
+            enumerable: false,
+            value: finalFingerprint,
+            writable: false,
+        });
+        return result;
+    }
+    finally {
+        await fh.close();
+    }
+}
+/**
+ * Proper-descendant containment: `realTarget` must sit strictly INSIDE
+ * `realRoot`, never be the root itself.
+ *
+ * Segment-aware on purpose. A bare `rel.startsWith("..")` test conflates the
+ * escape segment `..` with any legal in-root component whose NAME merely begins
+ * with two dots — `<root>/..plans` is an ordinary child directory, not an
+ * escape. Only `..` alone, or `..` followed by a separator, is an ascent; both
+ * `relative()` outputs are matched exactly here.
+ */
+function containsPathStrictly(realRoot, realTarget) {
+    const rel = relative(realRoot, realTarget);
+    return (rel !== "" &&
+        rel !== ".." &&
+        !rel.startsWith(`..${sep}`) &&
+        !isAbsolute(rel));
+}
+/** Containment that additionally accepts the root directory itself. */
+function containsPath(realRoot, realTarget) {
+    return relative(realRoot, realTarget) === "" ||
+        containsPathStrictly(realRoot, realTarget);
+}
+const DESCRIPTOR_PATH_TIMEOUT_MS = 2_000;
+const DESCRIPTOR_PATH_OUTPUT_LIMIT = 8_192;
+/**
+ * Resolve a verified path for an already-open descriptor. Authoritative on
+ * Linux; on darwin the check is probabilistic — see below. Unsupported
+ * platforms and helper failures fail closed (`undefined`).
+ *
+ * WITHOUT an `expectedPath`, Linux reads `/proc/self/fd/<fd>`, which the
+ * kernel answers from the descriptor itself. Darwin has no equivalent and
+ * falls through to the historical `lsof` helper.
+ *
+ * WITH an `expectedPath` (linux and darwin) this canonicalizes
+ * `P = realpath(expectedPath)`, then `lstat`s `P` and compares `(dev, ino)`
+ * against an `fstat` of the descriptor. That pair is NOT atomic: it is two
+ * independent walks of a mutable pathname, microseconds apart, and `lstat` is
+ * no-follow only on the FINAL component — every intermediate component is
+ * resolved again. An ancestor swapped between the two walks can steer the
+ * `lstat` onto the same out-of-root inode the descriptor holds, so the
+ * comparison passes while the returned string still reads as in-root; the
+ * caller's containment re-assert then succeeds on a path that no longer
+ * describes the opened bytes. `P` is returned for that re-assert, which is
+ * deliberately NOT done here (this helper holds no roots).
+ *
+ * Ancestor ABA restoration defeats the mitigation outright: restore the
+ * original ancestor before the caller's post-read re-verify and both the verify
+ * and the re-verify agree — the re-verify's string comparison against the first
+ * result then matches by construction.
+ *
+ * So the darwin guarantee RAISES THE COST of a race rather than eliminating it:
+ * three adjacent synchronous syscalls with no `await` between them, and callers
+ * verify twice, so the window must be won twice. It is meaningful only under a
+ * trusted-local-filesystem threat model — NOT against an adversary with
+ * concurrent write access to any ancestor directory.
+ *
+ * No stronger in-process guarantee exists to reach for: Node exposes no
+ * `openat`, no `AT_*` constants, and no dirfd-accepting API, so a
+ * descriptor-relative no-follow walk cannot be expressed at all, and darwin's
+ * `/dev/fd/<fd>` is not traversable. The residual is accepted deliberately, not
+ * overlooked; closing it would require a native addon.
+ *
+ * `lstatSync`, not `statSync`, on purpose: `realpathSync.native` has already
+ * resolved every symlink in `P`, so the final component can only be a symlink
+ * if one was swapped in AFTER that resolve. `lstat` fails closed on that swap;
+ * `stat` would follow it. Same syscall cost, strictly stronger.
+ *
+ * What it does NOT prove: that the descriptor has no OTHER name. An out-of-root
+ * hardlink alias to the same inode is not detected. `fcntl(F_GETPATH)` would not
+ * fix that either — it reads the same darwin vnode name cache, which holds one
+ * name per inode and is rewritten by the most recent lookup.
+ *
+ * WITHOUT an `expectedPath` the historical `lsof` implementation is retained
+ * verbatim, so an unmigrated caller keeps today's exact behavior instead of
+ * silently downgrading to a weaker check it never opted into.
+ */
+export async function resolveOpenedDescriptorPath(fd, expectedPath) {
+    if (expectedPath !== undefined) {
+        if (process.platform !== "linux" && process.platform !== "darwin") {
+            return undefined;
+        }
+        try {
+            const canonical = realpathSync.native(expectedPath);
+            const opened = fstatSync(fd, { bigint: true });
+            const named = lstatSync(canonical, { bigint: true });
+            if (opened.dev !== named.dev || opened.ino !== named.ino)
+                return undefined;
+            return canonical;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    if (process.platform === "linux") {
+        try {
+            const path = realpathSync(`/proc/self/fd/${String(fd)}`);
+            return path.includes(" (deleted)") ? undefined : path;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    if (process.platform !== "darwin")
+        return undefined;
+    return await new Promise((resolvePath) => {
+        let child;
+        try {
+            child = spawn("/usr/sbin/lsof", ["-b", "-w", "-a", "-p", String(process.pid), "-d", String(fd), "-F0n"], {
+                shell: false,
+                detached: true,
+                env: {
+                    PATH: "/usr/bin:/bin:/usr/sbin:/sbin",
+                    LANG: "C",
+                },
+                stdio: ["ignore", "pipe", "pipe"],
+            });
+        }
+        catch {
+            resolvePath(undefined);
+            return;
+        }
+        let stdout = "";
+        let stderrBytes = 0;
+        let outputExceeded = false;
+        let forcedFailure = false;
+        let settled = false;
+        const terminate = () => {
+            try {
+                if (child.pid != null)
+                    process.kill(-child.pid, "SIGKILL");
+            }
+            catch {
+                child.kill("SIGKILL");
+            }
+        };
+        const timer = setTimeout(() => {
+            forcedFailure = true;
+            terminate();
+        }, DESCRIPTOR_PATH_TIMEOUT_MS);
+        timer.unref();
+        const settle = (path) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolvePath(path);
+        };
+        child.stdout?.on("data", (chunk) => {
+            if (outputExceeded)
+                return;
+            if (Buffer.byteLength(stdout) + chunk.byteLength > DESCRIPTOR_PATH_OUTPUT_LIMIT) {
+                outputExceeded = true;
+                terminate();
+                return;
+            }
+            stdout += chunk.toString("utf-8");
+        });
+        child.stderr?.on("data", (chunk) => {
+            stderrBytes += chunk.byteLength;
+            if (stderrBytes > DESCRIPTOR_PATH_OUTPUT_LIMIT) {
+                forcedFailure = true;
+                terminate();
+            }
+        });
+        child.once("error", () => settle(undefined));
+        child.once("close", (status) => {
+            if (status !== 0 || outputExceeded || forcedFailure) {
+                settle(undefined);
+                return;
+            }
+            const names = stdout
+                .split("\0")
+                .map((field) => field.replace(/^\n+/, ""))
+                .filter((field) => field.startsWith("n"))
+                .map((field) => field.slice(1))
+                .filter((path) => path !== "" && !path.includes(" (deleted)"));
+            settle(names.length === 1 ? names[0] : undefined);
+        });
+    });
+}
+/**
+ * Read a run-relative sidecar. `relPath` MUST be relative to `rootDir`.
+ *
+ * Realpaths BOTH sides: on macOS `/tmp` (and mkdtemp dirs) is itself a symlink
+ * to `/private/tmp`, so realpathing only the target would false-reject a
+ * legitimate read.
+ */
+export async function readContainedRelativeFile(rootDir, relPath, options = {}) {
+    const container = options.containerLabel ?? "containing directory";
+    const pathLabel = options.pathLabel ?? "path";
+    if (isAbsolute(relPath)) {
+        throw new ContainedFilePolicyError(`${pathLabel} must be relative to the ${container}`);
+    }
+    const realRoot = realpathSync(resolve(rootDir));
+    const normalized = resolve(realRoot, relPath);
+    if (!containsPath(realRoot, normalized)) {
+        throw new ContainedFilePolicyError(`${pathLabel} escapes the ${container}`);
+    }
+    const base = basename(normalized);
+    if (base === "") {
+        throw new ContainedFilePolicyError(`${pathLabel} has no file component`);
+    }
+    // Canonicalize only the parent. Realpathing the final component would follow
+    // an in-root symlink before O_NOFOLLOW gets a chance to reject it.
+    const realParent = realpathSync(resolve(normalized, ".."));
+    const realTarget = resolve(realParent, base);
+    if (!containsPath(realRoot, realTarget)) {
+        throw new ContainedFilePolicyError(`${pathLabel} escapes the ${container}`);
+    }
+    try {
+        return await readOpenedContained(realTarget, [realRoot], options, options.requireExactRequestedPath === true ? normalized : undefined);
+    }
+    catch (err) {
+        if (err?.code === "ELOOP") {
+            throw new ContainedFilePolicyError(`${pathLabel} is a symlink and cannot be read`);
+        }
+        throw err;
+    }
+}
+/**
+ * Read an absolute path that must live inside at least one allowed root.
+ *
+ * Unlike {@link readContainedRelativeFile} this deliberately does NOT realpath
+ * the target before opening: resolving the final component would silently
+ * follow a symlink and defeat the "reject symlink" requirement. Only the
+ * PARENT is canonicalized for the containment check; `O_NOFOLLOW` then rejects
+ * a symlinked final component at open time.
+ */
+export async function readContainedAbsoluteFile(allowedRoots, targetPath, options = {}) {
+    if (!isAbsolute(targetPath)) {
+        throw new ContainedFilePolicyError(`path must be absolute: ${targetPath}`);
+    }
+    if (allowedRoots.length === 0) {
+        throw new ContainedFilePolicyError("no allowed roots are configured for path containment");
+    }
+    const normalized = resolve(targetPath);
+    const parent = resolve(normalized, "..");
+    const base = basename(normalized);
+    if (base === "") {
+        throw new ContainedFilePolicyError(`path has no file component: ${targetPath}`);
+    }
+    let realParent;
+    try {
+        realParent = realpathSync(parent);
+    }
+    catch {
+        throw new ContainedFilePolicyError(`path parent directory does not exist: ${parent}`);
+    }
+    // basename(), NOT slice arithmetic against `parent.length`: for a file
+    // directly under "/" the parent is "/" (length 1) and the offset math would
+    // silently eat the filename's first character.
+    const realTarget = resolve(realParent, base);
+    const realRoots = allowedRoots.map((root) => {
+        let realRoot;
+        try {
+            realRoot = realpathSync(resolve(root));
+        }
+        catch {
+            realRoot = resolve(root);
+        }
+        return realRoot;
+    });
+    const allowed = realRoots.some((realRoot) => containsPathStrictly(realRoot, realTarget));
+    if (!allowed) {
+        // `rel === ""` means the path IS an allowed root directory, not an escape —
+        // a materially different mistake that the shared "outside all allowed roots"
+        // wording actively misdescribes. Safe to re-scan: `some()` short-circuits
+        // only on true, so `allowed === false` means every root was visited and none
+        // matched. Both sub-cases carry the SAME reason: each is a rejection by the
+        // allowed-roots check, which is exactly what the reason discriminates.
+        const isExactRoot = realRoots.some((realRoot) => relative(realRoot, realTarget) === "");
+        if (isExactRoot) {
+            throw new ContainedFilePolicyError(`path "${targetPath}" resolves to an allowed root directory; expected a file within an allowed root`, "outside_allowed_roots");
+        }
+        throw new ContainedFilePolicyError(`path "${targetPath}" is outside all allowed roots [${allowedRoots.join(", ")}]`, "outside_allowed_roots");
+    }
+    try {
+        return await readOpenedContained(realTarget, realRoots, options);
+    }
+    catch (err) {
+        // ELOOP is how O_NOFOLLOW reports "the final component is a symlink".
+        if (err?.code === "ELOOP") {
+            throw new ContainedFilePolicyError(`path is a symlink and cannot be read: ${targetPath}`);
+        }
+        throw err;
+    }
+}
+//# sourceMappingURL=contained-file.js.map