/**
 * Path containment guard for the sandboxed execution paths: the built-in file
 * tools, bash's `cwd` argument and the background-command runner all check
 * against caller-declared roots here, so the strong form lives in one place.
 *
 * The load-bearing detail is **realpath**. A string comparison on resolved
 * paths is defeated by a symlink: `<root>/escape → /etc` resolves lexically to
 * `<root>/escape`, which passes, and then the command runs in `/etc`. Both
 * sides are therefore resolved through the filesystem before they are
 * compared, and a target that cannot be resolved is refused rather than
 * assumed innocent.
 *
 * The `+ sep` suffix on the prefix test is the other one: without it
 * `/home/app-evil` passes a containment check against `/home/app`.
 *
 * @module utils/pathSandbox
 */
import type { PathSandboxResult } from "../types/index.js";
/**
 * Separator-bounded containment. A root that already ends in the separator
 * (`/`, `C:\\`) contains every path that starts with it; appending another
 * separator would turn `/` into `//` and deny everything.
 */
export declare function isPathInsideRoot(candidate: string, root: string): boolean;
/**
 * Resolve `target` and confirm it is `root` or lies inside it, with symlinks
 * followed on both sides.
 *
 * Both must exist and be directories — a containment check on a path that is
 * not there yet cannot be honest, because whatever appears later may be a
 * symlink out.
 *
 * @param target Directory to check. Relative paths resolve against `root`.
 * @param root   Sandbox root the target must not escape.
 * @returns The resolved REAL path, or the reason it was refused.
 */
export declare function resolveWithinRoot(target: string, root: string): PathSandboxResult;
/**
 * The file twin of {@link resolveWithinRoot}: contain a path that may name a
 * file, or may not exist at all (a path argument to `git log`, say).
 *
 * A path that exists is resolved through its symlinks and checked directly. A
 * path that does not exist is checked on its nearest EXISTING ancestor, which
 * is the deepest point a symlink could redirect — everything below that is a
 * name, not a link. Deleted files therefore stay askable about, and
 * `../../etc/passwd` still does not.
 *
 * @param target Path to check. Relative paths resolve against `root`.
 * @param root   Sandbox root the target must not escape.
 * @returns The resolved absolute path, or the reason it was refused.
 */
export declare function resolvePathWithinRoot(target: string, root: string): PathSandboxResult;