import { type BigIntStats } from "node:fs";
import { type FileHandle } from "node:fs/promises";
export type ConfinedReadableFile = {
    handle: FileHandle;
    realPath: string;
    displayPath: string;
    size: number;
};
type ConfinedFileTestHook = (realPath: string) => void | Promise<void>;
type PreparedReadableFile = {
    displayPath: string;
    expectedStats: readonly BigIntStats[];
    realPath: string;
};
/**
 * Test-only seam after the trusted file identity is captured and before the descriptor opens.
 * Production code must leave this unset.
 */
export declare function setAfterConfinedPathVerifiedForTests(hook: ConfinedFileTestHook | undefined): void;
export declare function resolveReadableFile(realRoot: string, root: string, filePath: string): Promise<PreparedReadableFile>;
/**
 * Resolve a project path, open it, and verify the opened descriptor before any read.
 *
 * Flow: capture the lexical file identity (following any alias) -> realpath confinement -> capture
 * the resolved regular file identity -> optional test hook -> open the realpath'd target -> `fstat`
 * on that descriptor -> compare it to every pre-open identity -> callers read only through the
 * returned handle (never re-resolve the path string).
 *
 * POSIX: open uses `O_RDONLY | O_NOFOLLOW` so a leaf symlink swap fails the open with ELOOP.
 * win32: Node's `fs.open` has no portable `O_NOFOLLOW` (`fs.constants.O_NOFOLLOW` is absent).
 * Guarantee there is post-open identity: `fstat.ino` must match every pre-open identity. `dev` is
 * compared when both sides expose it. When win32 `lstat.dev` is zero while `fstat.dev` has the
 * volume serial, the creation time must also match, so a cross-volume junction swap cannot pass
 * on a colliding inode alone.
 *
 * In-root symlinks still work: confinement realpaths them first, then the open targets the
 * resolved regular file inside the root, not the symlink leaf.
 *
 * A pre-existing in-root hard link remains indistinguishable from one whose other directory entry
 * is outside the root. Pathname confinement proves the opened descriptor, not hard-link provenance.
 */
export declare function openConfinedReadableFile(realRoot: string, root: string, filePath: string): Promise<ConfinedReadableFile>;
export declare function readConfinedUtf8File(realRoot: string, root: string, filePath: string): Promise<string>;
export declare function resolveProjectFile(realRoot: string, root: string, filePath: string): Promise<string>;
export declare function assertRealPathCandidateWithinRoot(realRoot: string, filePath: string, label: string): Promise<string>;
export declare function findNearestExistingPath(filePath: string): Promise<string>;
export {};
//# sourceMappingURL=confinedFile.d.ts.map