agentic-qe 3.15.9 → 3.15.11

package/dist/shared/git/git-process.js

@@ -0,0 +1,37 @@
+/**
+ * Run git without blocking the event loop (#1115).
+ *
+ * Git runs in its own process group, so a timeout stops it together with any
+ * wrapper, credential helper or fsmonitor child it started.
+ */
+import { runProcessText } from '../test-runner-process.js';
+/** Git did not finish before its deadline; its result is unknown, not empty. */
+export class GitTimeoutError extends Error {
+    constructor(args, timeoutMs) {
+        super(`git ${args.join(' ')} timed out after ${Math.max(0, timeoutMs)}ms`);
+        this.name = 'GitTimeoutError';
+    }
+}
+/**
+ * Resolve with git's stdout. Rejects with GitTimeoutError when the deadline
+ * passes, and with a plain Error when git cannot start or exits non-zero.
+ */
+export async function runGit(args, options) {
+    if (options.timeout <= 0)
+        throw new GitTimeoutError(args, options.timeout);
+    try {
+        return await runProcessText('git', args, {
+            cwd: options.cwd,
+            timeout: options.timeout,
+            maxBuffer: options.maxBuffer,
+            // Never wait for a credential prompt that no one can answer.
+            env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+        });
+    }
+    catch (error) {
+        if (error.code === 'ETIMEDOUT')
+            throw new GitTimeoutError(args, options.timeout);
+        throw error;
+    }
+}
+//# sourceMappingURL=git-process.js.map

package/dist/shared/git/index.d.ts

@@ -4,4 +4,5 @@
 export { GitAnalyzer } from './git-analyzer';
 export type { GitAnalyzerConfig, GitCommit, GitBlameInfo, FileHistory, } from './git-analyzer';
 export { assertSafeGitRef, getGitRefError } from './ref-validation';
+export { GitTimeoutError } from './git-process';
 //# sourceMappingURL=index.d.ts.map

package/dist/shared/git/index.js

@@ -3,4 +3,5 @@
  */
 export { GitAnalyzer } from './git-analyzer.js';
 export { assertSafeGitRef, getGitRefError } from './ref-validation.js';
+export { GitTimeoutError } from './git-process.js';
 //# sourceMappingURL=index.js.map

package/dist/shared/io/confined-read.d.ts

@@ -0,0 +1,74 @@
+/**
+ * #1161: read a file inside the project root without a check-then-use race.
+ *
+ * The payload path guard (#1126) checks a path by name and the handler opens
+ * it again later, so a file or symlink swapped in between could be read
+ * unchecked. These readers OPEN first and validate what was opened:
+ *
+ * - the path's realpath is opened with O_NOFOLLOW (a symlink swapped onto the
+ *   final name fails the open) and O_NONBLOCK (a FIFO cannot hang the open);
+ * - the descriptor must be a regular file within the size limit (fstat);
+ * - the descriptor's real location (/proc/self/fd/N on Linux; elsewhere the
+ *   re-resolved realpath, which must be the same inode) must lie inside the
+ *   project root, so a directory component swapped for a symlink is caught;
+ * - the content is read from that same descriptor, and never past the limit,
+ *   even if the file grows after the fstat.
+ *
+ * A path spelled outside the root is refused before any filesystem call,
+ * unless the caller opts into `outsideRoot: 'allow'` for paths it accepts
+ * from a trusted source (the other checks still apply).
+ */
+import { type Stats } from 'node:fs';
+import { CallerInputError } from '../error-utils.js';
+/** Default upper bound for a confined read when the caller names none. */
+export declare const DEFAULT_MAX_CONFINED_READ_BYTES: number;
+export type ConfinedReadReason = 'not-found' | 'not-a-file' | 'outside-project-root' | 'unreadable' | 'too-large';
+export interface ConfinedReadOptions {
+    /** Project root; defaults to findProjectRoot(). */
+    projectRoot?: string;
+    /** Refuse files larger than this; defaults to DEFAULT_MAX_CONFINED_READ_BYTES. */
+    maxBytes?: number;
+    /**
+     * A path spelled outside the project root is refused ('refuse', default),
+     * or read without the containment check ('allow') when the caller already
+     * trusts it. Paths spelled inside the root are always held to the root.
+     */
+    outsideRoot?: 'refuse' | 'allow';
+}
+/**
+ * A confined read that was refused; `reason` matches the payload guard's.
+ * `code` is the errno code when the filesystem gave one (ENOENT, ELOOP, ...),
+ * otherwise the reason in errno style (OUTSIDE_PROJECT_ROOT, NOT_A_FILE,
+ * TOO_LARGE), so callers that report error codes keep working.
+ */
+export declare class ConfinedReadError extends CallerInputError {
+    readonly filePath: string;
+    readonly reason: ConfinedReadReason;
+    readonly code: string;
+    constructor(filePath: string, reason: ConfinedReadReason, errnoCode?: string);
+}
+/** Flags for opening a checked realpath: read-only, no final symlink, no FIFO wait. */
+export declare const CONFINED_OPEN_FLAGS: number;
+/** True when `candidate` is `root` or lies beneath it (both absolute). */
+export declare function isWithinRoot(root: string, candidate: string): boolean;
+/**
+ * Where an OPEN descriptor really points. On Linux, /proc/self/fd/N resolves
+ * to the opened file itself. Elsewhere, re-resolve the path and accept it only
+ * if it is the same inode as the descriptor, so a swap after the open is
+ * detected. Returns null when it cannot be proven.
+ */
+export declare function openedLocation(fd: number, lexical: string, opened: Stats): Promise<string | null>;
+/** Synchronous openedLocation, for callers that read synchronously. */
+export declare function openedLocationSync(fd: number, lexical: string, opened: Stats): string | null;
+/**
+ * Read a file by path, confined to the project root and validated on the
+ * opened descriptor (see the module comment). Throws ConfinedReadError.
+ */
+export declare function readConfinedFile(filePath: string, options?: ConfinedReadOptions): Promise<Buffer>;
+/** readConfinedFile decoded as UTF-8. */
+export declare function readConfinedText(filePath: string, options?: ConfinedReadOptions): Promise<string>;
+/** Synchronous readConfinedFile, for callers that cannot await. */
+export declare function readConfinedFileSync(filePath: string, options?: ConfinedReadOptions): Buffer;
+/** readConfinedFileSync decoded as UTF-8. */
+export declare function readConfinedTextSync(filePath: string, options?: ConfinedReadOptions): string;
+//# sourceMappingURL=confined-read.d.ts.map

package/dist/shared/io/confined-read.js

@@ -0,0 +1,256 @@
+/**
+ * #1161: read a file inside the project root without a check-then-use race.
+ *
+ * The payload path guard (#1126) checks a path by name and the handler opens
+ * it again later, so a file or symlink swapped in between could be read
+ * unchecked. These readers OPEN first and validate what was opened:
+ *
+ * - the path's realpath is opened with O_NOFOLLOW (a symlink swapped onto the
+ *   final name fails the open) and O_NONBLOCK (a FIFO cannot hang the open);
+ * - the descriptor must be a regular file within the size limit (fstat);
+ * - the descriptor's real location (/proc/self/fd/N on Linux; elsewhere the
+ *   re-resolved realpath, which must be the same inode) must lie inside the
+ *   project root, so a directory component swapped for a symlink is caught;
+ * - the content is read from that same descriptor, and never past the limit,
+ *   even if the file grows after the fstat.
+ *
+ * A path spelled outside the root is refused before any filesystem call,
+ * unless the caller opts into `outsideRoot: 'allow'` for paths it accepts
+ * from a trusted source (the other checks still apply).
+ */
+import { constants as fsConstants } from 'node:fs';
+import * as fsSync from 'node:fs';
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { findProjectRoot } from '../../kernel/project-root.js';
+import { CallerInputError } from '../error-utils.js';
+/** Default upper bound for a confined read when the caller names none. */
+export const DEFAULT_MAX_CONFINED_READ_BYTES = 128 * 1024 * 1024;
+/**
+ * A confined read that was refused; `reason` matches the payload guard's.
+ * `code` is the errno code when the filesystem gave one (ENOENT, ELOOP, ...),
+ * otherwise the reason in errno style (OUTSIDE_PROJECT_ROOT, NOT_A_FILE,
+ * TOO_LARGE), so callers that report error codes keep working.
+ */
+export class ConfinedReadError extends CallerInputError {
+    filePath;
+    reason;
+    code;
+    constructor(filePath, reason, errnoCode) {
+        super(`Cannot read ${filePath}: ${reason}`);
+        this.filePath = filePath;
+        this.reason = reason;
+        this.name = 'ConfinedReadError';
+        this.code = errnoCode ?? reason.toUpperCase().replace(/-/g, '_');
+    }
+}
+/** Flags for opening a checked realpath: read-only, no final symlink, no FIFO wait. */
+export const CONFINED_OPEN_FLAGS = fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW ?? 0) | (fsConstants.O_NONBLOCK ?? 0);
+/** True when `candidate` is `root` or lies beneath it (both absolute). */
+export function isWithinRoot(root, candidate) {
+    const relative = path.relative(root, candidate);
+    return relative === '' || (relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative));
+}
+/**
+ * Where an OPEN descriptor really points. On Linux, /proc/self/fd/N resolves
+ * to the opened file itself. Elsewhere, re-resolve the path and accept it only
+ * if it is the same inode as the descriptor, so a swap after the open is
+ * detected. Returns null when it cannot be proven.
+ */
+export async function openedLocation(fd, lexical, opened) {
+    const sameFile = async (candidate) => {
+        const st = await fs.stat(candidate).catch(() => null);
+        return st !== null && st.dev === opened.dev && st.ino === opened.ino;
+    };
+    const viaProc = await fs.realpath(`/proc/self/fd/${fd}`).catch(() => null);
+    if (viaProc && path.isAbsolute(viaProc) && await sameFile(viaProc))
+        return viaProc;
+    const real = await fs.realpath(lexical).catch(() => null);
+    if (real && await sameFile(real))
+        return real;
+    return null;
+}
+/** Synchronous openedLocation, for callers that read synchronously. */
+export function openedLocationSync(fd, lexical, opened) {
+    const sameFile = (candidate) => {
+        try {
+            const st = fsSync.statSync(candidate);
+            return st.dev === opened.dev && st.ino === opened.ino;
+        }
+        catch {
+            return false;
+        }
+    };
+    const realOrNull = (p) => {
+        try {
+            return fsSync.realpathSync(p);
+        }
+        catch {
+            return null;
+        }
+    };
+    const viaProc = realOrNull(`/proc/self/fd/${fd}`);
+    if (viaProc && path.isAbsolute(viaProc) && sameFile(viaProc))
+        return viaProc;
+    const real = realOrNull(lexical);
+    if (real && sameFile(real))
+        return real;
+    return null;
+}
+function reasonFor(error) {
+    const code = error?.code;
+    if (code === 'ENOENT' || code === 'ENOTDIR')
+        return 'not-found';
+    // ELOOP: a symlink was swapped onto the checked realpath's final name.
+    if (code === 'EISDIR' || code === 'ELOOP')
+        return 'not-a-file';
+    return 'unreadable';
+}
+function fail(filePath, reason, error) {
+    return new ConfinedReadError(filePath, reason, error?.code);
+}
+function plan(filePath, rootReal, options) {
+    if (typeof filePath !== 'string' || filePath === '' || filePath.includes('\0')) {
+        throw fail(String(filePath), 'unreadable');
+    }
+    const rootLexical = path.resolve(options.projectRoot ?? findProjectRoot());
+    const lexical = path.resolve(filePath);
+    const inRoot = isWithinRoot(rootLexical, lexical) || isWithinRoot(rootReal, lexical);
+    // Spelled outside the root: refused before any filesystem call, so the
+    // reason cannot reveal whether an outside path exists.
+    if (!inRoot && options.outsideRoot !== 'allow')
+        throw fail(filePath, 'outside-project-root');
+    return { lexical, rootReal, inRoot, limit: options.maxBytes ?? DEFAULT_MAX_CONFINED_READ_BYTES };
+}
+/** Check the opened descriptor's stat before anything is read. */
+function checkOpened(filePath, st, limit) {
+    if (!st.isFile())
+        throw fail(filePath, 'not-a-file');
+    if (st.size > limit)
+        throw fail(filePath, 'too-large');
+}
+/**
+ * Read a file by path, confined to the project root and validated on the
+ * opened descriptor (see the module comment). Throws ConfinedReadError.
+ */
+export async function readConfinedFile(filePath, options = {}) {
+    const root = path.resolve(options.projectRoot ?? findProjectRoot());
+    const rootReal = await fs.realpath(root).catch(() => root);
+    const p = plan(filePath, rootReal, options);
+    let real;
+    try {
+        real = await fs.realpath(p.lexical);
+    }
+    catch (error) {
+        throw fail(filePath, reasonFor(error), error);
+    }
+    if (p.inRoot && !isWithinRoot(p.rootReal, real))
+        throw fail(filePath, 'outside-project-root');
+    let handle;
+    try {
+        handle = await fs.open(real, CONFINED_OPEN_FLAGS);
+    }
+    catch (error) {
+        throw fail(filePath, reasonFor(error), error);
+    }
+    try {
+        const st = await handle.stat();
+        checkOpened(filePath, st, p.limit);
+        if (p.inRoot) {
+            const location = await openedLocation(handle.fd, real, st);
+            if (!location || !isWithinRoot(p.rootReal, location))
+                throw fail(filePath, 'outside-project-root');
+        }
+        // Read at most limit + 1 bytes from this descriptor: a file that grew
+        // after the fstat is refused rather than read without bound.
+        const chunks = [];
+        let total = 0;
+        for (;;) {
+            const chunk = Buffer.allocUnsafe(Math.min(64 * 1024, p.limit + 1 - total));
+            const { bytesRead } = await handle.read(chunk, 0, chunk.length, null);
+            if (bytesRead === 0)
+                break;
+            chunks.push(chunk.subarray(0, bytesRead));
+            total += bytesRead;
+            if (total > p.limit)
+                throw fail(filePath, 'too-large');
+        }
+        return Buffer.concat(chunks, total);
+    }
+    catch (error) {
+        if (error instanceof ConfinedReadError)
+            throw error;
+        throw fail(filePath, reasonFor(error), error);
+    }
+    finally {
+        await handle.close().catch(() => undefined);
+    }
+}
+/** readConfinedFile decoded as UTF-8. */
+export async function readConfinedText(filePath, options = {}) {
+    return (await readConfinedFile(filePath, options)).toString('utf-8');
+}
+/** Synchronous readConfinedFile, for callers that cannot await. */
+export function readConfinedFileSync(filePath, options = {}) {
+    const root = path.resolve(options.projectRoot ?? findProjectRoot());
+    let rootReal = root;
+    try {
+        rootReal = fsSync.realpathSync(root);
+    }
+    catch { /* keep the lexical root */ }
+    const p = plan(filePath, rootReal, options);
+    let real;
+    try {
+        real = fsSync.realpathSync(p.lexical);
+    }
+    catch (error) {
+        throw fail(filePath, reasonFor(error), error);
+    }
+    if (p.inRoot && !isWithinRoot(p.rootReal, real))
+        throw fail(filePath, 'outside-project-root');
+    let fd;
+    try {
+        fd = fsSync.openSync(real, CONFINED_OPEN_FLAGS);
+    }
+    catch (error) {
+        throw fail(filePath, reasonFor(error), error);
+    }
+    try {
+        const st = fsSync.fstatSync(fd);
+        checkOpened(filePath, st, p.limit);
+        if (p.inRoot) {
+            const location = openedLocationSync(fd, real, st);
+            if (!location || !isWithinRoot(p.rootReal, location))
+                throw fail(filePath, 'outside-project-root');
+        }
+        const chunks = [];
+        let total = 0;
+        for (;;) {
+            const chunk = Buffer.allocUnsafe(Math.min(64 * 1024, p.limit + 1 - total));
+            const bytesRead = fsSync.readSync(fd, chunk, 0, chunk.length, null);
+            if (bytesRead === 0)
+                break;
+            chunks.push(chunk.subarray(0, bytesRead));
+            total += bytesRead;
+            if (total > p.limit)
+                throw fail(filePath, 'too-large');
+        }
+        return Buffer.concat(chunks, total);
+    }
+    catch (error) {
+        if (error instanceof ConfinedReadError)
+            throw error;
+        throw fail(filePath, reasonFor(error), error);
+    }
+    finally {
+        try {
+            fsSync.closeSync(fd);
+        }
+        catch { /* already closed */ }
+    }
+}
+/** readConfinedFileSync decoded as UTF-8. */
+export function readConfinedTextSync(filePath, options = {}) {
+    return readConfinedFileSync(filePath, options).toString('utf-8');
+}
+//# sourceMappingURL=confined-read.js.map

package/dist/shared/io/file-reader.d.ts

@@ -74,12 +74,12 @@ export declare class FileReader {
      */
     private inProjectRoot;
     /**
-     * #1021 round 2b: read an in-root path without a check-then-use race.
-     * The file is OPENED first and the open descriptor is verified — its real
-     * location (/proc/self/fd/N on Linux; otherwise the re-resolved realpath,
-     * which must be the same inode) must lie inside the root — and the content
-     * is read from that same descriptor. Swapping a symlink (file or directory
-     * component) between the check and the read can no longer redirect it.
+     * #1021 round 2b / #1161: read an in-root path without a check-then-use
+     * race. readConfinedText opens the path once and verifies the opened
+     * descriptor (a regular file whose real location lies inside the root) and
+     * reads from that same descriptor, so swapping a symlink (file or directory
+     * component) between a check and the read cannot redirect it, and a FIFO or
+     * device cannot hang or flood the read.
      */
     private readContained;
     /**

package/dist/shared/io/file-reader.js

@@ -7,6 +7,7 @@ import * as path from 'node:path';
 import { ok, err } from '../types/index.js';
 import { validatePath } from '../security/path-traversal-validator.js';
 import { safeJsonParse } from '../safe-json.js';
+import { ConfinedReadError, readConfinedText } from './confined-read.js';
 /** Extensions never read, inside or outside the project root. */
 const DENIED_EXTENSIONS = ['.exe', '.bat', '.cmd', '.ps1', '.dll', '.so'];
 export class FileReadError extends Error {
@@ -65,25 +66,6 @@ function readError(error, absolutePath) {
     }
     return new FileReadError(message, absolutePath, nodeError.code, nodeError);
 }
-/**
- * #1021 round 2b: where an OPEN descriptor really points. On Linux,
- * /proc/self/fd/N resolves to the opened file itself. Elsewhere, re-resolve
- * the path and accept it only if it is the same inode as the descriptor, so
- * a swap after the open is detected. Returns null when it cannot be proven.
- */
-async function openedLocation(fd, lexical, opened) {
-    const sameFile = async (candidate) => {
-        const st = await fs.stat(candidate).catch(() => null);
-        return st !== null && st.dev === opened.dev && st.ino === opened.ino;
-    };
-    const viaProc = await fs.realpath(`/proc/self/fd/${fd}`).catch(() => null);
-    if (viaProc && path.isAbsolute(viaProc) && await sameFile(viaProc))
-        return viaProc;
-    const real = await fs.realpath(lexical).catch(() => null);
-    if (real && await sameFile(real))
-        return real;
-    return null;
-}
 /** True when `candidate` is `root` or lies beneath it (both absolute). */
 function isWithin(root, candidate) {
     const relative = path.relative(root, candidate);
@@ -341,38 +323,30 @@ export class FileReader {
         return { lexical, rootReal };
     }
     /**
-     * #1021 round 2b: read an in-root path without a check-then-use race.
-     * The file is OPENED first and the open descriptor is verified — its real
-     * location (/proc/self/fd/N on Linux; otherwise the re-resolved realpath,
-     * which must be the same inode) must lie inside the root — and the content
-     * is read from that same descriptor. Swapping a symlink (file or directory
-     * component) between the check and the read can no longer redirect it.
+     * #1021 round 2b / #1161: read an in-root path without a check-then-use
+     * race. readConfinedText opens the path once and verifies the opened
+     * descriptor (a regular file whose real location lies inside the root) and
+     * reads from that same descriptor, so swapping a symlink (file or directory
+     * component) between a check and the read cannot redirect it, and a FIFO or
+     * device cannot hang or flood the read.
      */
     async readContained(filePath, lexical, rootReal) {
         this.stats.totalReads++;
-        let handle;
         try {
-            handle = await fs.open(lexical, 'r');
+            // The lexical root, so a path spelled under a symlinked root still
+            // counts as inside; the primitive resolves the root's realpath itself.
+            return ok(await readConfinedText(lexical, { projectRoot: this.projectRoot ?? rootReal }));
         }
         catch (error) {
-            return err(readError(error, lexical));
-        }
-        try {
-            const opened = await handle.stat();
-            const location = await openedLocation(handle.fd, lexical, opened);
-            if (!location || !isWithin(rootReal, location)) {
+            if (!(error instanceof ConfinedReadError))
+                return err(readError(error, lexical));
+            if (error.reason === 'outside-project-root') {
                 return err(new PathTraversalError(filePath, ['Path resolves outside the project root'], 'critical'));
             }
-            if (!opened.isFile()) {
-                return err(new FileReadError('Path is a directory: ' + lexical, lexical, 'EISDIR'));
+            if (error.reason === 'not-a-file') {
+                return err(new FileReadError('Not a regular file: ' + lexical, lexical, error.code === 'NOT_A_FILE' ? 'EISDIR' : error.code));
             }
-            return ok(await handle.readFile('utf-8'));
-        }
-        catch (error) {
-            return err(readError(error, lexical));
-        }
-        finally {
-            await handle.close().catch(() => undefined);
+            return err(readError({ code: error.reason === 'not-found' ? 'ENOENT' : error.code }, lexical));
         }
     }
     /**

package/dist/shared/io/payload-path-guard.d.ts

@@ -0,0 +1,75 @@
+/**
+ * #1126: decide which caller-named paths a task handler may read.
+ *
+ * A task payload can come from MCP task_submit, task_orchestrate, a domain
+ * MCP tool or `aqe task submit`, so every handler that reads a path from its
+ * payload applies the same rule as code indexing (#1096) and sast-scan
+ * (#1144): a path is read only when its realpath is a regular file (or, for a
+ * target to walk, a directory) inside the project root's realpath. A path
+ * spelled outside the root is refused before any filesystem call, so the
+ * reason does not reveal whether it exists, and an outside directory is never
+ * listed. A symlink pointing out, a device such as /dev/zero or a directory
+ * is refused by name, and so is a file over the size limit when the handler
+ * reads files whole.
+ *
+ * The check runs inside each handler rather than at one MCP entry point, so
+ * no route into the handler can skip it. A refusal is a CallerInputError: it
+ * is not retried and does not count toward the domain circuit breaker.
+ */
+import { Result } from '../types';
+/** Largest file a handler reads whole into memory (the #1144 sast limit). */
+export declare const MAX_PAYLOAD_FILE_BYTES: number;
+export type PayloadPathSkipReason = 'not-found' | 'not-a-file' | 'outside-project-root' | 'unreadable' | 'too-large';
+export interface SkippedPayloadPath {
+    path: string;
+    reason: PayloadPathSkipReason;
+}
+export interface ConfinedPayloadPaths {
+    /** Requested paths (as given) that are regular files inside the project root. */
+    accepted: string[];
+    /** The real path checked for each accepted entry, in the same order. */
+    resolved: string[];
+    skipped: SkippedPayloadPath[];
+}
+export interface PayloadPathOptions {
+    /** Project root; defaults to findProjectRoot(). */
+    projectRoot?: string;
+    /** Base for relative paths; defaults to process.cwd(), as FileReader does. */
+    basePath?: string;
+    /** Refuse files larger than this. Omit when the handler does not read files whole. */
+    maxBytes?: number;
+    /**
+     * Accept a path inside the root that does not exist, for handlers that
+     * report a missing file themselves (a test runner, a deleted file in a
+     * changeset). A missing path outside the root is still refused.
+     */
+    allowMissing?: boolean;
+}
+/** Options for a single caller-named target that may be a directory. */
+export interface PayloadTargetOptions extends PayloadPathOptions {
+    /** Accept a directory inside the root as well as a regular file. */
+    allowDirectory?: boolean;
+}
+/**
+ * Split `paths` into those a handler may read and those it must refuse.
+ * `resolved[i]` is the symlink-free path checked for `accepted[i]` (relative
+ * to basePath when the request was relative); a handler opens that path,
+ * never the caller's string.
+ */
+export declare function confinePayloadPaths(paths: readonly string[], options?: PayloadTargetOptions): Promise<ConfinedPayloadPaths>;
+/**
+ * Handler-side check for a payload path list: `value` must be an array of
+ * non-empty path strings, and every entry must pass confinePayloadPaths.
+ * Otherwise the whole request is refused and nothing is read. Returns the real
+ * paths that were checked; the handler reads those, not the payload strings.
+ * `taskType` and `field` name the payload in the error.
+ */
+export declare function requirePayloadFiles(taskType: string, field: string, value: unknown, options?: PayloadTargetOptions): Promise<Result<string[], Error>>;
+/**
+ * Handler-side check for one caller-named path (a file, or with
+ * allowDirectory a directory to walk). Returns the real path that was
+ * checked, which the handler reads instead of the payload string, or an error
+ * naming the reason without reading anything.
+ */
+export declare function requirePayloadPath(taskType: string, field: string, value: unknown, options?: PayloadTargetOptions): Promise<Result<string, Error>>;
+//# sourceMappingURL=payload-path-guard.d.ts.map