@spacefast/common 0.0.13 → 0.0.18

package/dist/utils/secure-local-file.js

@@ -0,0 +1,1373 @@
+import { execFile } from "node:child_process";
+import { createHash, randomUUID } from "node:crypto";
+/* oxlint-disable eslint/no-await-in-loop -- Secure traversal and identity validation must preserve filesystem component order. */
+import { constants } from "node:fs";
+import { copyFile, chmod, link, lstat, mkdir, open, readFile, readdir, realpath, rename, rm, unlink, } from "node:fs/promises";
+import path from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+export class SecureLocalFileError extends Error {
+    name = "SecureLocalFileError";
+}
+export class SecureLocalFileConflictError extends SecureLocalFileError {
+    name = "SecureLocalFileConflictError";
+}
+function writeConflict(message) {
+    return new SecureLocalFileConflictError(message);
+}
+function validationError(message) {
+    return new SecureLocalFileError(message);
+}
+function commonAncestor(left, right) {
+    const leftRoot = path.parse(left).root;
+    const rightRoot = path.parse(right).root;
+    if (process.platform === "win32"
+        ? leftRoot.toLowerCase() !== rightRoot.toLowerCase()
+        : leftRoot !== rightRoot) {
+        return path.dirname(right);
+    }
+    const leftParts = left.slice(leftRoot.length).split(path.sep).filter(Boolean);
+    const rightParts = right.slice(rightRoot.length).split(path.sep).filter(Boolean);
+    const common = [];
+    for (let index = 0; index < Math.min(leftParts.length, rightParts.length); index += 1) {
+        const leftPart = leftParts[index];
+        const rightPart = rightParts[index];
+        if (leftPart === undefined ||
+            rightPart === undefined ||
+            (process.platform === "win32"
+                ? leftPart.toLowerCase() !== rightPart.toLowerCase()
+                : leftPart !== rightPart)) {
+            break;
+        }
+        common.push(leftPart);
+    }
+    return path.join(leftRoot, ...common);
+}
+export function secureOutputLocation(trustedPath, outputPath) {
+    const trusted = path.resolve(trustedPath);
+    const output = path.resolve(outputPath);
+    const relativeToTrusted = path.relative(trusted, output);
+    const withinTrusted = relativeToTrusted !== ".." &&
+        !relativeToTrusted.startsWith(`..${path.sep}`) &&
+        !path.isAbsolute(relativeToTrusted);
+    const root = withinTrusted ? trusted : commonAncestor(trusted, path.dirname(output));
+    return { root, relativePath: path.relative(root, output) };
+}
+function noFollowDirectoryFlags() {
+    return constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW;
+}
+function noFollowCreateFlags() {
+    return constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW;
+}
+function portableCreateFlags() {
+    return constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL;
+}
+function portableReadFlags() {
+    return constants.O_RDONLY;
+}
+function isMissing(error) {
+    return error.code === "ENOENT";
+}
+function isAlreadyExists(error) {
+    return error.code === "EEXIST";
+}
+function descriptorPath(directory, child) {
+    const base = `/proc/self/fd/${directory.fd}`;
+    return child === undefined ? base : path.join(base, child);
+}
+function supportsDescriptorRelativeOutput() {
+    return (process.platform === "linux" &&
+        typeof constants.O_DIRECTORY === "number" &&
+        typeof constants.O_NOFOLLOW === "number");
+}
+function assertSafeComponent(component) {
+    if (!component || component === "." || component === ".." || component.includes(path.sep)) {
+        throw validationError(`Refusing unsafe output path component: ${component || "(empty)"}`);
+    }
+}
+async function directoryIdentity(directoryPath, handle) {
+    const stats = await handle.stat({ bigint: true });
+    if (!stats.isDirectory()) {
+        throw validationError(`Refusing non-directory output ancestor: ${directoryPath}`);
+    }
+    return {
+        path: directoryPath,
+        dev: stats.dev,
+        ino: stats.ino,
+    };
+}
+async function openDirectory(directoryPath) {
+    const pathStats = await lstat(directoryPath);
+    if (pathStats.isSymbolicLink()) {
+        throw validationError(`Refusing symlinked output ancestor: ${directoryPath}`);
+    }
+    if (!pathStats.isDirectory()) {
+        throw validationError(`Refusing non-directory output ancestor: ${directoryPath}`);
+    }
+    try {
+        const handle = await open(directoryPath, noFollowDirectoryFlags());
+        return { handle, identity: await directoryIdentity(directoryPath, handle) };
+    }
+    catch (error) {
+        if (error.code === "ELOOP") {
+            throw validationError(`Refusing symlinked output ancestor: ${directoryPath}`);
+        }
+        throw error;
+    }
+}
+async function openRoot(root, create) {
+    const parsed = path.parse(root);
+    let visible = parsed.root;
+    let current = await openDirectory(parsed.root);
+    const identities = [current.identity];
+    try {
+        for (const component of root.slice(parsed.root.length).split(path.sep).filter(Boolean)) {
+            const next = await openChildDirectory(current.handle, visible, component, create);
+            await current.handle.close();
+            current = next;
+            visible = path.join(visible, component);
+            identities.push(next.identity);
+        }
+        return { handle: current.handle, identities };
+    }
+    catch (error) {
+        await current.handle.close();
+        throw error;
+    }
+}
+async function openChildDirectory(parent, visibleParent, component, create) {
+    assertSafeComponent(component);
+    const childPath = descriptorPath(parent, component);
+    if (create) {
+        try {
+            await mkdir(childPath);
+        }
+        catch (error) {
+            if (!isAlreadyExists(error))
+                throw error;
+        }
+    }
+    const opened = await openDirectory(childPath);
+    return {
+        handle: opened.handle,
+        identity: await directoryIdentity(path.join(visibleParent, component), opened.handle),
+    };
+}
+async function validateDirectoryBindings(identities) {
+    for (const identity of identities) {
+        let stats;
+        try {
+            stats = await lstat(identity.path, { bigint: true });
+        }
+        catch (error) {
+            if (isMissing(error)) {
+                throw validationError(`Output ancestor changed during write: ${identity.path}`);
+            }
+            throw error;
+        }
+        if (stats.isSymbolicLink() ||
+            !stats.isDirectory() ||
+            stats.dev !== identity.dev ||
+            stats.ino !== identity.ino) {
+            throw validationError(`Output ancestor changed during write: ${identity.path}`);
+        }
+    }
+}
+async function visibleDirectoryIdentity(directoryPath) {
+    let stats;
+    try {
+        stats = await lstat(directoryPath, { bigint: true });
+    }
+    catch (error) {
+        if (isMissing(error)) {
+            throw validationError(`Output ancestor changed during write: ${directoryPath}`);
+        }
+        throw error;
+    }
+    if (stats.isSymbolicLink()) {
+        throw validationError(`Refusing symlinked output ancestor: ${directoryPath}`);
+    }
+    if (!stats.isDirectory()) {
+        throw validationError(`Refusing non-directory output ancestor: ${directoryPath}`);
+    }
+    return {
+        path: directoryPath,
+        dev: stats.dev,
+        ino: stats.ino,
+    };
+}
+async function openPortableRoot(root, create) {
+    const parsed = path.parse(root);
+    let visible = parsed.root;
+    const identities = [await visibleDirectoryIdentity(visible)];
+    for (const component of root.slice(parsed.root.length).split(path.sep).filter(Boolean)) {
+        assertSafeComponent(component);
+        visible = path.join(visible, component);
+        if (create) {
+            try {
+                await mkdir(visible);
+            }
+            catch (error) {
+                if (!isAlreadyExists(error))
+                    throw error;
+            }
+        }
+        identities.push(await visibleDirectoryIdentity(visible));
+    }
+    return identities;
+}
+async function canonicalPortableWriteRoot(rootInput) {
+    const missingComponents = [];
+    let existingAncestor = path.resolve(rootInput);
+    while (true) {
+        try {
+            return path.join(await realpath(existingAncestor), ...missingComponents);
+        }
+        catch (error) {
+            if (!isMissing(error))
+                throw error;
+            const parent = path.dirname(existingAncestor);
+            if (parent === existingAncestor)
+                throw error;
+            missingComponents.unshift(path.basename(existingAncestor));
+            existingAncestor = parent;
+        }
+    }
+}
+async function openPortableChildDirectory(identities, visibleParent, component, create) {
+    assertSafeComponent(component);
+    const childPath = path.join(visibleParent, component);
+    // A missing directory is the normal "file not found" result for secure
+    // reads. Probe before identity capture so callers can handle ENOENT. If the
+    // directory disappears after this probe, visibleDirectoryIdentity still
+    // fails closed because an observed ancestor binding changed mid-read.
+    if (!create) {
+        await lstat(childPath);
+    }
+    if (create) {
+        try {
+            await mkdir(childPath);
+        }
+        catch (error) {
+            if (!isAlreadyExists(error))
+                throw error;
+        }
+    }
+    const identity = await visibleDirectoryIdentity(childPath);
+    identities.push(identity);
+    await validateDirectoryBindings(identities);
+    return childPath;
+}
+function validateRelativePath(relativePathInput, operation) {
+    const relativePath = path.normalize(relativePathInput);
+    if (path.isAbsolute(relativePath) ||
+        relativePath === ".." ||
+        relativePath.startsWith(`..${path.sep}`)) {
+        throw validationError(`Refusing to ${operation} outside ${operation === "read" ? "local root" : "output directory"}: ${relativePathInput}`);
+    }
+    return relativePath;
+}
+function lockName(leaf) {
+    const identity = process.platform === "win32" || process.platform === "darwin"
+        ? leaf.normalize("NFC").toLowerCase()
+        : leaf;
+    const digest = createHash("sha256").update(identity).digest("hex").slice(0, 24);
+    return `.spacefast-${digest}.lock`;
+}
+const LEGACY_LEAF_LOCK_STALE_MS = 2 * 60_000;
+function serializeLeafLockOwner(owner) {
+    const { phase, ...identity } = owner;
+    return `${phase === "active" ? "A" : "R"}${JSON.stringify(identity)}\n`;
+}
+function parseLeafLockOwner(raw) {
+    try {
+        const phase = raw[0] === "A" ? "active" : raw[0] === "R" ? "released" : null;
+        const value = JSON.parse(raw.slice(1));
+        if (phase &&
+            Number.isSafeInteger(value.pid) &&
+            (value.pid ?? 0) > 0 &&
+            typeof value.nonce === "string" &&
+            value.nonce.length > 0 &&
+            typeof value.processStartIdentity === "string" &&
+            value.processStartIdentity.length > 0 &&
+            typeof value.createdAt === "string" &&
+            (value.temporaryName === undefined ||
+                (typeof value.temporaryName === "string" &&
+                    /^\.spacefast-[0-9a-f-]{36}\.tmp$/.test(value.temporaryName)))) {
+            return { ...value, phase };
+        }
+    }
+    catch {
+        return null;
+    }
+    return null;
+}
+const PROCESS_IDENTITY_TIMEOUT_MS = 5_000;
+let selfStartIdentity;
+function commandStdout(command, args) {
+    return new Promise((resolve) => {
+        execFile(command, args, {
+            encoding: "utf8",
+            killSignal: "SIGKILL",
+            timeout: PROCESS_IDENTITY_TIMEOUT_MS,
+        }, (error, stdout) => resolve(error ? null : stdout));
+    });
+}
+function processStartIdentity(pid) {
+    if (pid === process.pid) {
+        selfStartIdentity ??= resolveProcessStartIdentity(pid);
+        return selfStartIdentity;
+    }
+    return resolveProcessStartIdentity(pid);
+}
+async function resolveProcessStartIdentity(pid) {
+    if (process.platform === "linux") {
+        const stat = await readFile(`/proc/${pid}/stat`, "utf8").catch(() => null);
+        if (!stat)
+            return null;
+        const commandEnd = stat.lastIndexOf(")");
+        if (commandEnd < 0)
+            return null;
+        const startTicks = stat
+            .slice(commandEnd + 2)
+            .trim()
+            .split(/\s+/)[19];
+        return startTicks ? `linux:${startTicks}` : null;
+    }
+    if (process.platform === "darwin") {
+        const output = await commandStdout("/bin/ps", ["-o", "lstart=", "-p", String(pid)]);
+        const started = output?.trim();
+        return started ? `darwin:${started}` : null;
+    }
+    if (process.platform === "win32") {
+        const output = await commandStdout("powershell.exe", [
+            "-NoProfile",
+            "-NonInteractive",
+            "-Command",
+            `(Get-Process -Id ${pid}).StartTime.ToUniversalTime().Ticks`,
+        ]);
+        const started = output?.trim();
+        return started ? `win32:${started}` : null;
+    }
+    return null;
+}
+function processIsAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code !== "ESRCH";
+    }
+}
+async function leafLockRecordIsStale(record) {
+    // The original lock format was an empty exclusive file. It carries no owner
+    // identity, so a short age fence is the only safe compatibility signal: a
+    // fresh legacy writer stays exclusive, while crash wreckage can recover.
+    if (record?.kind === "legacy") {
+        return Date.now() - record.modifiedAtMs > LEGACY_LEAF_LOCK_STALE_MS;
+    }
+    // A malformed non-empty record is not proof that no writer owns it. New lock
+    // records are atomically published, so corruption still needs explicit recovery.
+    if (record?.kind !== "owned")
+        return false;
+    const { owner } = record;
+    if (owner.phase === "released")
+        return true;
+    if (!processIsAlive(owner.pid))
+        return true;
+    const currentStartIdentity = await processStartIdentity(owner.pid);
+    return currentStartIdentity !== null && currentStartIdentity !== owner.processStartIdentity;
+}
+async function readLeafLockRecord(filePath) {
+    let file;
+    try {
+        file = await open(filePath, supportsDescriptorRelativeOutput()
+            ? constants.O_RDONLY | constants.O_NOFOLLOW
+            : portableReadFlags());
+    }
+    catch (error) {
+        return isMissing(error) ? { kind: "missing" } : { kind: "invalid" };
+    }
+    try {
+        const metadata = await file.stat();
+        const visibleMetadata = await lstat(filePath).catch(() => null);
+        if (!metadata.isFile() ||
+            !visibleMetadata ||
+            visibleMetadata.isSymbolicLink() ||
+            !visibleMetadata.isFile() ||
+            visibleMetadata.dev !== metadata.dev ||
+            visibleMetadata.ino !== metadata.ino) {
+            return { kind: "invalid" };
+        }
+        const raw = await file.readFile("utf8");
+        const owner = parseLeafLockOwner(raw);
+        if (owner)
+            return { kind: "owned", owner };
+        return raw.length === 0
+            ? { kind: "legacy", modifiedAtMs: metadata.mtimeMs }
+            : { kind: "invalid" };
+    }
+    finally {
+        await file.close();
+    }
+}
+async function publishLeafLock(lockPath, owner) {
+    const candidatePath = `${lockPath}.candidate.${owner.pid}.${owner.nonce}`;
+    try {
+        const candidate = await open(candidatePath, supportsDescriptorRelativeOutput() ? noFollowCreateFlags() : portableCreateFlags(), 0o600);
+        try {
+            await candidate.writeFile(serializeLeafLockOwner(owner), "utf8");
+            await candidate.sync();
+        }
+        finally {
+            await candidate.close();
+        }
+        await link(candidatePath, lockPath);
+    }
+    finally {
+        await unlink(candidatePath).catch(() => undefined);
+    }
+}
+async function cleanupAbandonedTemporary(lockPath, owner) {
+    if (!owner.temporaryName)
+        return;
+    const temporaryPath = path.join(path.dirname(lockPath), owner.temporaryName);
+    const metadata = await lstat(temporaryPath).catch(() => null);
+    if (metadata?.isFile() && !metadata.isSymbolicLink()) {
+        await unlink(temporaryPath).catch(() => undefined);
+    }
+}
+async function leafLockArtifacts(lockPath) {
+    const directory = path.dirname(lockPath);
+    const lockLeaf = path.basename(lockPath);
+    const displacedPrefix = `${lockLeaf}.displaced.`;
+    return (await readdir(directory).catch(() => []))
+        .filter((candidate) => candidate === lockLeaf || candidate.startsWith(displacedPrefix))
+        .map((candidate) => path.join(directory, candidate));
+}
+async function cleanupStaleLeafLockCandidates(lockPath) {
+    const directory = path.dirname(lockPath);
+    const candidatePrefix = `${path.basename(lockPath)}.candidate.`;
+    for (const candidate of await readdir(directory).catch(() => [])) {
+        if (!candidate.startsWith(candidatePrefix))
+            continue;
+        const candidatePath = path.join(directory, candidate);
+        const embeddedPid = Number(candidate.slice(candidatePrefix.length).split(".", 1)[0]);
+        const record = await readLeafLockRecord(candidatePath);
+        if ((Number.isSafeInteger(embeddedPid) && embeddedPid > 0 && !processIsAlive(embeddedPid)) ||
+            (record.kind !== "missing" && (await leafLockRecordIsStale(record)))) {
+            await unlink(candidatePath).catch(() => undefined);
+        }
+    }
+}
+async function unlinkOwnedLeafLockArtifact(lockPath, artifactPath, nonce) {
+    const retiredPath = `${lockPath}.displaced.${process.pid}.${randomUUID()}`;
+    try {
+        await rename(artifactPath, retiredPath);
+    }
+    catch (error) {
+        if (isMissing(error))
+            return;
+        throw error;
+    }
+    const retired = await readLeafLockRecord(retiredPath);
+    if (retired.kind === "owned" && retired.owner.nonce === nonce) {
+        await unlink(retiredPath).catch(() => undefined);
+        return;
+    }
+    // The pathname changed after its owner was inspected. Restore the exact inode
+    // when the name is still free; if another lock is already visible, keep this
+    // one displaced so contenders detect it instead of deleting a fresh owner.
+    let restored = false;
+    try {
+        await link(retiredPath, artifactPath);
+        restored = true;
+    }
+    catch (error) {
+        if (isMissing(error))
+            return;
+        if (!isAlreadyExists(error))
+            throw error;
+    }
+    if (restored)
+        await unlink(retiredPath).catch(() => undefined);
+}
+async function unlinkOwnedLeafLockArtifacts(lockPath, nonce) {
+    for (const artifactPath of await leafLockArtifacts(lockPath)) {
+        await unlinkOwnedLeafLockArtifact(lockPath, artifactPath, nonce);
+    }
+}
+async function hasCompetingDisplacedLock(lockPath, nonce) {
+    for (const artifactPath of await leafLockArtifacts(lockPath)) {
+        if (artifactPath === lockPath)
+            continue;
+        const record = await readLeafLockRecord(artifactPath);
+        if (record.kind === "missing")
+            continue;
+        if (record.kind === "owned" && record.owner.nonce === nonce)
+            continue;
+        if (!(await leafLockRecordIsStale(record)))
+            return true;
+        if (record?.kind === "owned") {
+            await cleanupAbandonedTemporary(lockPath, record.owner);
+        }
+        await unlink(artifactPath).catch(() => undefined);
+    }
+    return false;
+}
+const LEAF_LOCK_RETRY_LIMIT = 8;
+const LEAF_LOCK_RETRY_DELAY_MS = 5;
+async function acquireLeafLock(lockPath, temporaryPath) {
+    await cleanupStaleLeafLockCandidates(lockPath);
+    const currentProcessStartIdentity = (await processStartIdentity(process.pid)) ?? `${process.platform}:unverified`;
+    const owner = {
+        pid: process.pid,
+        nonce: randomUUID(),
+        processStartIdentity: currentProcessStartIdentity,
+        createdAt: new Date().toISOString(),
+        ...(temporaryPath ? { temporaryName: path.basename(temporaryPath) } : {}),
+        phase: "active",
+    };
+    for (let attempt = 0; attempt < LEAF_LOCK_RETRY_LIMIT; attempt += 1) {
+        let published = false;
+        let ownerHandle = null;
+        try {
+            await publishLeafLock(lockPath, owner);
+            published = true;
+            ownerHandle = await open(lockPath, supportsDescriptorRelativeOutput()
+                ? constants.O_RDWR | constants.O_NOFOLLOW
+                : constants.O_RDWR);
+            const identity = await ownerHandle.stat({ bigint: true });
+            const visibleIdentity = await lstat(lockPath, { bigint: true });
+            const currentOwner = parseLeafLockOwner(await ownerHandle.readFile("utf8"));
+            if (visibleIdentity.isSymbolicLink() ||
+                !visibleIdentity.isFile() ||
+                visibleIdentity.dev !== identity.dev ||
+                visibleIdentity.ino !== identity.ino ||
+                currentOwner?.nonce !== owner.nonce ||
+                (await hasCompetingDisplacedLock(lockPath, owner.nonce))) {
+                await unlinkOwnedLeafLockArtifacts(lockPath, owner.nonce);
+                throw writeConflict(`Output file is already being modified: ${lockPath}`);
+            }
+            let released = false;
+            const acquiredHandle = ownerHandle;
+            return async () => {
+                if (released)
+                    return;
+                released = true;
+                // Move the canonical name into unique cleanup custody while its inode
+                // is still active. Once that atomic rename happens a new owner may
+                // publish, but cleanup only ever unlinks the retired name it inspected.
+                await unlinkOwnedLeafLockArtifact(lockPath, lockPath, owner.nonce).catch(() => undefined);
+                try {
+                    // A delayed stale reclaimer may already hold this inode at a displaced
+                    // name. Mark it complete through the handle so that artifact can be
+                    // reclaimed even though this process remains alive.
+                    const releasedWrite = await acquiredHandle.write(Buffer.from("R"), 0, 1, 0);
+                    if (releasedWrite.bytesWritten === 1)
+                        await acquiredHandle.sync();
+                }
+                catch {
+                    // Best-effort recovery cleanup, as above.
+                }
+                finally {
+                    await cleanupStaleLeafLockCandidates(lockPath).catch(() => undefined);
+                    await acquiredHandle.close().catch(() => undefined);
+                }
+            };
+        }
+        catch (error) {
+            await ownerHandle?.close().catch(() => undefined);
+            if (published) {
+                await unlinkOwnedLeafLockArtifacts(lockPath, owner.nonce);
+                if (isMissing(error)) {
+                    throw writeConflict(`Output file is already being modified: ${lockPath}`);
+                }
+                throw error;
+            }
+            if (!isAlreadyExists(error))
+                throw error;
+        }
+        const current = await readLeafLockRecord(lockPath);
+        if (current.kind === "missing") {
+            await delay(LEAF_LOCK_RETRY_DELAY_MS);
+            continue;
+        }
+        if (!(await leafLockRecordIsStale(current))) {
+            throw writeConflict(`Output file is already being modified: ${lockPath}`);
+        }
+        const displacedPath = `${lockPath}.displaced.${process.pid}.${randomUUID()}`;
+        try {
+            await rename(lockPath, displacedPath);
+        }
+        catch (error) {
+            if (isMissing(error)) {
+                await delay(LEAF_LOCK_RETRY_DELAY_MS);
+                continue;
+            }
+            throw error;
+        }
+        const displaced = await readLeafLockRecord(displacedPath);
+        if (!(await leafLockRecordIsStale(displaced))) {
+            // A fresh owner won between our stale read and rename. Put its exact inode
+            // back when possible; every contender also scans displaced names before
+            // entering, so a live writer is never silently unlocked.
+            try {
+                await link(displacedPath, lockPath);
+            }
+            catch (error) {
+                if (isMissing(error)) {
+                    // Its owner completed cleanup while we inspected the displaced inode.
+                    // Nothing remains to restore; compete again for the now-current name.
+                    await delay(LEAF_LOCK_RETRY_DELAY_MS);
+                    continue;
+                }
+                if (!isAlreadyExists(error))
+                    throw error;
+            }
+            throw writeConflict(`Output file is already being modified: ${lockPath}`);
+        }
+        if (displaced?.kind === "owned") {
+            await cleanupAbandonedTemporary(lockPath, displaced.owner);
+        }
+        await unlink(displacedPath).catch(() => undefined);
+        await delay(LEAF_LOCK_RETRY_DELAY_MS);
+    }
+    throw writeConflict(`Output file is already being modified: ${lockPath}`);
+}
+function matchesEntryIdentity(stats, expected) {
+    return (stats.dev === expected.dev &&
+        stats.ino === expected.ino &&
+        stats.mode === expected.mode &&
+        stats.ctimeNs === expected.ctimeNs);
+}
+async function assertSafeLeaf(leafPath, overwrite) {
+    try {
+        const stats = await lstat(leafPath);
+        if (stats.isSymbolicLink()) {
+            throw validationError(`Refusing symlinked output file: ${leafPath}`);
+        }
+        if (!stats.isFile()) {
+            throw validationError(`Refusing non-file output path: ${leafPath}`);
+        }
+        if (!overwrite) {
+            throw validationError(`Refusing to overwrite existing file: ${leafPath}`);
+        }
+    }
+    catch (error) {
+        if (isMissing(error))
+            return;
+        throw error;
+    }
+}
+async function assertExpectedLeaf(leafPath, expectedContent) {
+    if (expectedContent === undefined)
+        return;
+    let current;
+    try {
+        const file = await open(leafPath, supportsDescriptorRelativeOutput()
+            ? constants.O_RDONLY | constants.O_NOFOLLOW
+            : portableReadFlags());
+        try {
+            const metadata = await file.stat();
+            if (!metadata.isFile()) {
+                throw validationError(`Refusing non-file output path: ${leafPath}`);
+            }
+            current = await file.readFile();
+        }
+        finally {
+            await file.close();
+        }
+    }
+    catch (error) {
+        if (!isMissing(error))
+            throw error;
+        current = null;
+    }
+    const expected = expectedContent === null
+        ? null
+        : Buffer.isBuffer(expectedContent)
+            ? expectedContent
+            : Buffer.from(expectedContent);
+    if (current === null ? expected !== null : expected === null || !current.equals(expected)) {
+        throw writeConflict(`Output file changed during write: ${leafPath}`);
+    }
+}
+async function commitStagedFile(input) {
+    const leafPath = descriptorPath(input.parent, input.leaf);
+    const backupPath = descriptorPath(input.parent, `.spacefast-${randomUUID()}.rollback`);
+    const lockPath = descriptorPath(input.parent, lockName(input.leaf));
+    let backupCreated = false;
+    let committed = false;
+    const releaseLock = await acquireLeafLock(lockPath, input.temporaryPath);
+    try {
+        await input.beforeCommit?.();
+        await validateDirectoryBindings(input.identities);
+        await assertExpectedLeaf(leafPath, input.expectedContent);
+        await assertSafeLeaf(leafPath, input.overwrite);
+        if (input.overwrite) {
+            try {
+                await link(leafPath, backupPath);
+                backupCreated = true;
+            }
+            catch (error) {
+                if (!isMissing(error))
+                    throw error;
+            }
+            await input.afterBackup?.();
+            await rename(input.temporaryPath, leafPath);
+            committed = true;
+        }
+        else {
+            try {
+                await link(input.temporaryPath, leafPath);
+            }
+            catch (error) {
+                if (isAlreadyExists(error)) {
+                    throw validationError(`Refusing to overwrite existing file: ${leafPath}`);
+                }
+                throw error;
+            }
+            committed = true;
+            await unlink(input.temporaryPath);
+        }
+        await input.parent.sync();
+        await validateDirectoryBindings(input.identities);
+        if (backupCreated) {
+            await unlink(backupPath);
+            backupCreated = false;
+            await input.parent.sync();
+        }
+    }
+    catch (error) {
+        if (committed) {
+            if (backupCreated) {
+                await rename(backupPath, leafPath);
+                backupCreated = false;
+            }
+            else {
+                await unlink(leafPath).catch((cleanupError) => {
+                    if (!isMissing(cleanupError))
+                        throw cleanupError;
+                });
+            }
+            await input.parent.sync();
+        }
+        throw error;
+    }
+    finally {
+        if (backupCreated) {
+            await unlink(backupPath).catch((error) => {
+                if (!isMissing(error))
+                    throw error;
+            });
+        }
+        await releaseLock();
+    }
+}
+async function commitPortableStagedFile(input) {
+    const parentPath = path.dirname(input.leafPath);
+    const backupPath = path.join(parentPath, `.spacefast-${randomUUID()}.rollback`);
+    const lockPath = path.join(parentPath, lockName(path.basename(input.leafPath)));
+    let backupCreated = false;
+    let committed = false;
+    const releaseLock = await acquireLeafLock(lockPath, input.temporaryPath);
+    try {
+        await input.beforeCommit?.();
+        await validateDirectoryBindings(input.identities);
+        await assertExpectedLeaf(input.leafPath, input.expectedContent);
+        await assertSafeLeaf(input.leafPath, input.overwrite);
+        if (input.overwrite) {
+            if (process.platform === "win32") {
+                try {
+                    await rename(input.leafPath, backupPath);
+                    backupCreated = true;
+                }
+                catch (error) {
+                    if (!isMissing(error))
+                        throw error;
+                }
+                await validateDirectoryBindings(input.identities);
+            }
+            else {
+                try {
+                    await link(input.leafPath, backupPath);
+                    backupCreated = true;
+                }
+                catch (error) {
+                    if (!isMissing(error))
+                        throw error;
+                }
+            }
+            await input.afterBackup?.();
+            await rename(input.temporaryPath, input.leafPath);
+            committed = true;
+        }
+        else {
+            try {
+                await link(input.temporaryPath, input.leafPath);
+            }
+            catch (error) {
+                if (isAlreadyExists(error)) {
+                    throw validationError(`Refusing to overwrite existing file: ${input.leafPath}`);
+                }
+                if (error.code !== "EPERM" &&
+                    error.code !== "ENOTSUP") {
+                    throw error;
+                }
+                try {
+                    await copyFile(input.temporaryPath, input.leafPath, constants.COPYFILE_EXCL);
+                }
+                catch (copyError) {
+                    if (isAlreadyExists(copyError)) {
+                        throw validationError(`Refusing to overwrite existing file: ${input.leafPath}`);
+                    }
+                    await unlink(input.leafPath).catch((cleanupError) => {
+                        if (!isMissing(cleanupError))
+                            throw cleanupError;
+                    });
+                    throw copyError;
+                }
+            }
+            committed = true;
+            await unlink(input.temporaryPath);
+        }
+        await validateDirectoryBindings(input.identities);
+        if (backupCreated) {
+            await unlink(backupPath);
+            backupCreated = false;
+        }
+    }
+    catch (error) {
+        if (committed) {
+            if (backupCreated) {
+                await rename(backupPath, input.leafPath);
+                backupCreated = false;
+            }
+            else {
+                await unlink(input.leafPath).catch((cleanupError) => {
+                    if (!isMissing(cleanupError))
+                        throw cleanupError;
+                });
+            }
+        }
+        else if (backupCreated) {
+            await rename(backupPath, input.leafPath);
+            backupCreated = false;
+        }
+        throw error;
+    }
+    finally {
+        if (backupCreated) {
+            await rename(backupPath, input.leafPath).catch(async (error) => {
+                if (!isMissing(error))
+                    throw error;
+            });
+        }
+        await releaseLock();
+    }
+}
+async function secureWriteFilePortable(options) {
+    // The caller explicitly trusts the root. Canonicalize that boundary once so
+    // supported system aliases such as macOS `/var -> /private/var` do not look
+    // like attacker-controlled children; every path below it is still walked
+    // component-by-component without following symlinks.
+    const root = await canonicalPortableWriteRoot(options.root);
+    const relativePath = validateRelativePath(options.relativePath, "write");
+    const components = relativePath.split(path.sep);
+    const leaf = components.pop();
+    if (!leaf) {
+        throw validationError(`Refusing invalid output file path: ${options.relativePath}`);
+    }
+    assertSafeComponent(leaf);
+    const identities = await openPortableRoot(root, true);
+    if (options.rootMode !== undefined) {
+        await chmod(root, options.rootMode);
+    }
+    let visibleParent = root;
+    for (const component of components) {
+        if (!component || component === ".")
+            continue;
+        visibleParent = await openPortableChildDirectory(identities, visibleParent, component, true);
+    }
+    const temporaryPath = path.join(visibleParent, `.spacefast-${randomUUID()}.tmp`);
+    let temporaryPresent = true;
+    try {
+        await validateDirectoryBindings(identities);
+        const temporary = await open(temporaryPath, portableCreateFlags(), 0o600);
+        try {
+            if (options.data !== undefined) {
+                await temporary.writeFile(options.data);
+            }
+            else {
+                const writer = options.write;
+                if (!writer) {
+                    throw validationError("Secure output write source disappeared before staging.");
+                }
+                await writer(temporary);
+            }
+            await temporary.chmod(options.mode ?? 0o600);
+            await temporary.sync();
+        }
+        finally {
+            await temporary.close();
+        }
+        await commitPortableStagedFile({
+            leafPath: path.join(visibleParent, leaf),
+            temporaryPath,
+            overwrite: options.overwrite === true,
+            expectedContent: options.expectedContent,
+            identities,
+            ...(options.beforeCommit ? { beforeCommit: options.beforeCommit } : {}),
+            ...(options.afterBackup ? { afterBackup: options.afterBackup } : {}),
+        });
+        temporaryPresent = false;
+    }
+    finally {
+        if (temporaryPresent) {
+            await unlink(temporaryPath).catch((error) => {
+                if (!isMissing(error))
+                    throw error;
+            });
+        }
+    }
+}
+/**
+ * Writes beneath an explicitly trusted root without following output-tree
+ * symlinks. Linux uses descriptor-relative operations; other supported
+ * platforms use exclusive staging plus before-and-after ancestor identity
+ * validation and fail closed if any binding changes.
+ */
+export async function secureWriteFile(options) {
+    if ((options.data === undefined) === (options.write === undefined)) {
+        throw validationError("Secure output requires exactly one data or write source.");
+    }
+    if (!supportsDescriptorRelativeOutput()) {
+        return secureWriteFilePortable(options);
+    }
+    const root = path.resolve(options.root);
+    const relativePath = validateRelativePath(options.relativePath, "write");
+    const components = relativePath.split(path.sep);
+    const leaf = components.pop();
+    if (!leaf) {
+        throw validationError(`Refusing invalid output file path: ${options.relativePath}`);
+    }
+    assertSafeComponent(leaf);
+    const openedRoot = await openRoot(root, true);
+    if (options.rootMode !== undefined) {
+        await openedRoot.handle.chmod(options.rootMode);
+    }
+    let parent = openedRoot.handle;
+    const identities = [...openedRoot.identities];
+    let visibleParent = root;
+    let temporaryPath = null;
+    try {
+        for (const component of components) {
+            if (!component || component === ".")
+                continue;
+            const next = await openChildDirectory(parent, visibleParent, component, true);
+            await parent.close();
+            parent = next.handle;
+            visibleParent = path.join(visibleParent, component);
+            identities.push(next.identity);
+        }
+        const temporaryName = `.spacefast-${randomUUID()}.tmp`;
+        temporaryPath = descriptorPath(parent, temporaryName);
+        const temporary = await open(temporaryPath, noFollowCreateFlags(), 0o600);
+        try {
+            if (options.data !== undefined) {
+                await temporary.writeFile(options.data);
+            }
+            else {
+                const writer = options.write;
+                if (!writer) {
+                    throw validationError("Secure output write source disappeared before staging.");
+                }
+                await writer(temporary);
+            }
+            await temporary.chmod(options.mode ?? 0o600);
+            await temporary.sync();
+        }
+        finally {
+            await temporary.close();
+        }
+        await commitStagedFile({
+            parent,
+            leaf,
+            temporaryPath,
+            overwrite: options.overwrite === true,
+            expectedContent: options.expectedContent,
+            identities,
+            ...(options.beforeCommit ? { beforeCommit: options.beforeCommit } : {}),
+            ...(options.afterBackup ? { afterBackup: options.afterBackup } : {}),
+        });
+        temporaryPath = null;
+    }
+    finally {
+        if (temporaryPath) {
+            await unlink(temporaryPath).catch((error) => {
+                if (!isMissing(error))
+                    throw error;
+            });
+        }
+        await parent.close();
+    }
+}
+export async function secureReadFile(options) {
+    if (!supportsDescriptorRelativeOutput()) {
+        return secureReadFilePortable(options);
+    }
+    const root = path.resolve(options.root);
+    const relativePath = validateRelativePath(options.relativePath, "read");
+    const components = relativePath.split(path.sep);
+    const leaf = components.pop();
+    if (!leaf) {
+        throw validationError(`Refusing invalid local file path: ${options.relativePath}`);
+    }
+    assertSafeComponent(leaf);
+    const openedRoot = await openRoot(root, false);
+    let parent = openedRoot.handle;
+    const identities = [...openedRoot.identities];
+    let visibleParent = root;
+    try {
+        for (const component of components) {
+            if (!component || component === ".")
+                continue;
+            const next = await openChildDirectory(parent, visibleParent, component, false);
+            await parent.close();
+            parent = next.handle;
+            visibleParent = path.join(visibleParent, component);
+            identities.push(next.identity);
+        }
+        await validateDirectoryBindings(identities);
+        const leafPath = descriptorPath(parent, leaf);
+        let file;
+        try {
+            file = await open(leafPath, constants.O_RDONLY | constants.O_NOFOLLOW);
+        }
+        catch (error) {
+            if (error.code === "ELOOP") {
+                throw validationError(`Refusing symlinked local file: ${path.join(visibleParent, leaf)}`);
+            }
+            throw error;
+        }
+        try {
+            const metadata = await file.stat();
+            if (!metadata.isFile()) {
+                throw validationError(`Refusing non-file local path: ${path.join(visibleParent, leaf)}`);
+            }
+            if (metadata.nlink !== 1) {
+                const writerLock = await lstat(descriptorPath(parent, lockName(leaf))).catch(() => null);
+                if (writerLock) {
+                    throw writeConflict(`Local file is being replaced: ${path.join(visibleParent, leaf)}`);
+                }
+                throw validationError(`Refusing hard-linked local file: ${path.join(visibleParent, leaf)}`);
+            }
+            const content = await file.readFile(options.encoding ? { encoding: options.encoding } : {});
+            await validateDirectoryBindings(identities);
+            return content;
+        }
+        finally {
+            await file.close();
+        }
+    }
+    finally {
+        await parent.close();
+    }
+}
+async function secureReadFilePortable(options) {
+    const root = await realpath(path.resolve(options.root));
+    const relativePath = validateRelativePath(options.relativePath, "read");
+    const components = relativePath.split(path.sep);
+    const leaf = components.pop();
+    if (!leaf) {
+        throw validationError(`Refusing invalid local file path: ${options.relativePath}`);
+    }
+    assertSafeComponent(leaf);
+    const identities = await openPortableRoot(root, false);
+    let visibleParent = root;
+    for (const component of components) {
+        if (!component || component === ".")
+            continue;
+        visibleParent = await openPortableChildDirectory(identities, visibleParent, component, false);
+    }
+    await validateDirectoryBindings(identities);
+    const leafPath = path.join(visibleParent, leaf);
+    const pathStats = await lstat(leafPath);
+    if (pathStats.isSymbolicLink()) {
+        throw validationError(`Refusing symlinked local file: ${leafPath}`);
+    }
+    const file = await open(leafPath, portableReadFlags());
+    try {
+        const metadata = await file.stat({ bigint: true });
+        if (!metadata.isFile()) {
+            throw validationError(`Refusing non-file local path: ${leafPath}`);
+        }
+        if (metadata.nlink !== 1n) {
+            const writerLock = await lstat(path.join(visibleParent, lockName(leaf))).catch(() => null);
+            if (writerLock) {
+                throw writeConflict(`Local file is being replaced: ${leafPath}`);
+            }
+            throw validationError(`Refusing hard-linked local file: ${leafPath}`);
+        }
+        const content = await file.readFile(options.encoding ? { encoding: options.encoding } : {});
+        await validateDirectoryBindings(identities);
+        const finalStats = await lstat(leafPath, { bigint: true });
+        if (finalStats.isSymbolicLink() ||
+            !finalStats.isFile() ||
+            finalStats.dev !== metadata.dev ||
+            finalStats.ino !== metadata.ino) {
+            throw validationError(`Local file changed during read: ${leafPath}`);
+        }
+        return content;
+    }
+    finally {
+        await file.close();
+    }
+}
+/**
+ * Removes only the exact non-directory leaf identity previously inspected.
+ * The same leaf lock used by secureWriteFile covers the identity check and
+ * rename, so a cooperating writer cannot replace the leaf between them.
+ */
+export async function secureRemoveLocalEntry(options) {
+    const relativePath = validateRelativePath(options.relativePath, "write");
+    const components = relativePath.split(path.sep);
+    const leaf = components.pop();
+    if (!leaf) {
+        throw validationError(`Refusing invalid output file path: ${options.relativePath}`);
+    }
+    assertSafeComponent(leaf);
+    if (!supportsDescriptorRelativeOutput()) {
+        const root = await realpath(path.resolve(options.root));
+        const identities = await openPortableRoot(root, false);
+        let visibleParent = root;
+        for (const component of components) {
+            if (!component || component === ".")
+                continue;
+            visibleParent = await openPortableChildDirectory(identities, visibleParent, component, false);
+        }
+        const leafPath = path.join(visibleParent, leaf);
+        const retiredPath = path.join(visibleParent, `.spacefast-${randomUUID()}.retired`);
+        const releaseLock = await acquireLeafLock(path.join(visibleParent, lockName(leaf)));
+        try {
+            await validateDirectoryBindings(identities);
+            let stats;
+            try {
+                stats = await lstat(leafPath, { bigint: true });
+            }
+            catch (error) {
+                if (isMissing(error))
+                    return false;
+                throw error;
+            }
+            if (!matchesEntryIdentity(stats, options.expectedIdentity))
+                return false;
+            if (stats.isDirectory()) {
+                throw validationError(`Refusing to remove directory output path: ${leafPath}`);
+            }
+            await rename(leafPath, retiredPath);
+            await validateDirectoryBindings(identities);
+            await unlink(retiredPath);
+            await validateDirectoryBindings(identities);
+            return true;
+        }
+        finally {
+            await releaseLock();
+        }
+    }
+    const root = path.resolve(options.root);
+    const openedRoot = await openRoot(root, false);
+    let parent = openedRoot.handle;
+    const identities = [...openedRoot.identities];
+    let visibleParent = root;
+    try {
+        for (const component of components) {
+            if (!component || component === ".")
+                continue;
+            const next = await openChildDirectory(parent, visibleParent, component, false);
+            await parent.close();
+            parent = next.handle;
+            visibleParent = path.join(visibleParent, component);
+            identities.push(next.identity);
+        }
+        const leafPath = descriptorPath(parent, leaf);
+        const retiredName = `.spacefast-${randomUUID()}.retired`;
+        const retiredPath = descriptorPath(parent, retiredName);
+        const releaseLock = await acquireLeafLock(descriptorPath(parent, lockName(leaf)));
+        try {
+            await validateDirectoryBindings(identities);
+            let stats;
+            try {
+                stats = await lstat(leafPath, { bigint: true });
+            }
+            catch (error) {
+                if (isMissing(error))
+                    return false;
+                throw error;
+            }
+            if (!matchesEntryIdentity(stats, options.expectedIdentity))
+                return false;
+            if (stats.isDirectory()) {
+                throw validationError(`Refusing to remove directory output path: ${path.join(visibleParent, leaf)}`);
+            }
+            await rename(leafPath, retiredPath);
+            await parent.sync();
+            await validateDirectoryBindings(identities);
+            await unlink(retiredPath);
+            await parent.sync();
+            await validateDirectoryBindings(identities);
+            return true;
+        }
+        finally {
+            await releaseLock();
+        }
+    }
+    finally {
+        await parent.close();
+    }
+}
+/**
+ * Creates one new directory leaf beneath a trusted root. The returned rollback
+ * removes only the exact directory inode created by this call.
+ */
+export async function secureCreateDirectory(options) {
+    const root = path.resolve(options.root);
+    const relativePath = validateRelativePath(options.relativePath, "write");
+    const components = relativePath.split(path.sep).filter((component) => component !== ".");
+    const leaf = components.pop();
+    if (!leaf) {
+        throw validationError(`Refusing invalid output directory path: ${options.relativePath}`);
+    }
+    assertSafeComponent(leaf);
+    if (!supportsDescriptorRelativeOutput()) {
+        const portableRoot = await realpath(root);
+        const identities = await openPortableRoot(portableRoot, false);
+        let visibleParent = portableRoot;
+        for (const component of components) {
+            visibleParent = await openPortableChildDirectory(identities, visibleParent, component, false);
+        }
+        await validateDirectoryBindings(identities);
+        const createdPath = path.join(visibleParent, leaf);
+        try {
+            await mkdir(createdPath, { mode: options.mode ?? 0o755 });
+        }
+        catch (error) {
+            if (isAlreadyExists(error)) {
+                throw validationError(`Target already exists: ${createdPath}`);
+            }
+            throw error;
+        }
+        const createdIdentity = await visibleDirectoryIdentity(createdPath);
+        await validateDirectoryBindings(identities);
+        let completed = false;
+        return {
+            path: path.join(root, relativePath),
+            validate: async () => {
+                await validateDirectoryBindings(identities);
+                const current = await visibleDirectoryIdentity(createdPath);
+                if (current.dev !== createdIdentity.dev || current.ino !== createdIdentity.ino) {
+                    throw validationError(`Created output directory changed: ${createdPath}`);
+                }
+            },
+            commit: async () => {
+                if (completed)
+                    return;
+                await validateDirectoryBindings(identities);
+                const current = await visibleDirectoryIdentity(createdPath);
+                if (current.dev !== createdIdentity.dev || current.ino !== createdIdentity.ino) {
+                    throw validationError(`Created output directory changed: ${createdPath}`);
+                }
+                completed = true;
+            },
+            rollback: async () => {
+                if (completed)
+                    return;
+                completed = true;
+                await validateDirectoryBindings(identities);
+                const current = await visibleDirectoryIdentity(createdPath);
+                if (current.dev !== createdIdentity.dev || current.ino !== createdIdentity.ino) {
+                    throw validationError(`Created output directory changed: ${createdPath}`);
+                }
+                await rm(createdPath, { recursive: true });
+                await validateDirectoryBindings(identities);
+            },
+        };
+    }
+    const openedRoot = await openRoot(root, false);
+    let parent = openedRoot.handle;
+    const identities = [...openedRoot.identities];
+    let visibleParent = root;
+    try {
+        for (const component of components) {
+            const next = await openChildDirectory(parent, visibleParent, component, false);
+            await parent.close();
+            parent = next.handle;
+            visibleParent = path.join(visibleParent, component);
+            identities.push(next.identity);
+        }
+        await validateDirectoryBindings(identities);
+        const createdPath = descriptorPath(parent, leaf);
+        try {
+            await mkdir(createdPath, { mode: options.mode ?? 0o755 });
+        }
+        catch (error) {
+            if (isAlreadyExists(error)) {
+                throw validationError(`Target already exists: ${path.join(visibleParent, leaf)}`);
+            }
+            throw error;
+        }
+        const openedCreated = await openDirectory(createdPath);
+        const createdIdentity = await directoryIdentity(path.join(visibleParent, leaf), openedCreated.handle);
+        let completed = false;
+        const validateCreatedDirectory = async () => {
+            await validateDirectoryBindings(identities);
+            const currentIdentity = await directoryIdentity(createdIdentity.path, openedCreated.handle);
+            const visibleIdentity = await visibleDirectoryIdentity(createdIdentity.path);
+            if (currentIdentity.dev !== createdIdentity.dev ||
+                currentIdentity.ino !== createdIdentity.ino ||
+                visibleIdentity.dev !== createdIdentity.dev ||
+                visibleIdentity.ino !== createdIdentity.ino) {
+                throw validationError(`Created output directory changed: ${createdIdentity.path}`);
+            }
+        };
+        return {
+            path: path.join(root, relativePath),
+            validate: async () => {
+                if (completed) {
+                    throw validationError(`Created output directory handle is closed: ${createdIdentity.path}`);
+                }
+                await validateCreatedDirectory();
+            },
+            commit: async () => {
+                if (completed)
+                    return;
+                await validateCreatedDirectory();
+                completed = true;
+                await openedCreated.handle.close();
+                await parent.close();
+            },
+            rollback: async () => {
+                try {
+                    if (completed)
+                        return;
+                    completed = true;
+                    await validateDirectoryBindings(identities);
+                    await validateCreatedDirectory();
+                    await openedCreated.handle.close();
+                    await rm(createdPath, { recursive: true });
+                    await validateDirectoryBindings(identities);
+                }
+                finally {
+                    await openedCreated.handle.close().catch(() => { });
+                    await parent.close();
+                }
+            },
+        };
+    }
+    catch (error) {
+        // Any created-directory handle is closed in the branch that owns it.
+        await parent.close();
+        throw error;
+    }
+}