@openclaw/fs-safe 0.4.6 → 0.5.0

package/dist/move-path.js

@@ -2,6 +2,7 @@ import { randomUUID } from "node:crypto";
 import { constants as fsConstants } from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
+import { FsSafeError } from "./errors.js";
 import { guardedRename } from "./guarded-mutation.js";
 export function moveCopyFallbackReasonForRenameError(error, platform = process.platform) {
     const code = error?.code;
@@ -13,6 +14,49 @@ export function moveCopyFallbackReasonForRenameError(error, platform = process.p
     }
     return undefined;
 }
+const MAX_HARDLINK_PREFLIGHT_ENTRIES = 50_000;
+function hardlinkedSourceError(sourcePath) {
+    return new FsSafeError("hardlink", `Refusing to move hardlinked file: ${sourcePath}`);
+}
+function hardlinkWalkTooLargeError() {
+    return new FsSafeError("too-large", `Source hardlink preflight exceeds ${MAX_HARDLINK_PREFLIGHT_ENTRIES} entries`);
+}
+async function preflightSourceHardlinks(sourcePath) {
+    const pending = [sourcePath];
+    let discovered = 1;
+    while (pending.length > 0) {
+        const current = pending.pop();
+        const stat = await fs.lstat(current);
+        if (stat.isFile() && stat.nlink > 1) {
+            throw hardlinkedSourceError(current);
+        }
+        if (!stat.isDirectory()) {
+            continue;
+        }
+        const directory = await fs.opendir(current);
+        for await (const entry of directory) {
+            discovered += 1;
+            if (discovered > MAX_HARDLINK_PREFLIGHT_ENTRIES) {
+                throw hardlinkWalkTooLargeError();
+            }
+            pending.push(path.join(current, entry.name));
+        }
+    }
+}
+function isSameOrDescendant(parentPath, candidatePath) {
+    const relative = path.relative(parentPath, candidatePath);
+    return (relative === "" ||
+        (!path.isAbsolute(relative) && !relative.startsWith(`..${path.sep}`) && relative !== ".."));
+}
+async function assertCopyDestinationOutsideSource(sourcePath, targetPath) {
+    const sourceReal = await fs.realpath(sourcePath);
+    const normalizedTarget = path.resolve(targetPath);
+    const targetParentReal = await fs.realpath(path.dirname(normalizedTarget));
+    const targetCandidate = path.join(targetParentReal, path.basename(normalizedTarget));
+    if (isSameOrDescendant(sourceReal, targetCandidate)) {
+        throw new FsSafeError("invalid-path", "Move destination must not be inside the source");
+    }
+}
 function entryIdentity(stat) {
     return {
         ctimeMs: stat.ctimeMs,
@@ -20,6 +64,7 @@ function entryIdentity(stat) {
         ino: stat.ino,
         mode: stat.mode,
         mtimeMs: stat.mtimeMs,
+        nlink: stat.nlink,
         size: stat.size,
     };
 }
@@ -27,6 +72,7 @@ function sameIdentity(a, b) {
     return (a.dev === b.dev &&
         a.ino === b.ino &&
         a.mode === b.mode &&
+        a.nlink === b.nlink &&
         a.size === b.size &&
         a.mtimeMs === b.mtimeMs &&
         a.ctimeMs === b.ctimeMs);
@@ -51,6 +97,9 @@ function regularReadFlags() {
     return (fsConstants.O_RDONLY |
         (typeof fsConstants.O_NOFOLLOW === "number" && process.platform !== "win32"
             ? fsConstants.O_NOFOLLOW
+            : 0) |
+        (typeof fsConstants.O_NONBLOCK === "number" && process.platform !== "win32"
+            ? fsConstants.O_NONBLOCK
             : 0));
 }
 async function writeAll(handle, buffer, bytesRead) {
@@ -75,6 +124,9 @@ async function copyRegularFilePinned(params) {
     }
     try {
         const openedStat = await sourceHandle.stat();
+        if (params.rejectHardlinks && openedStat.nlink > 1) {
+            throw hardlinkedSourceError(params.from);
+        }
         if (!openedStat.isFile() || !sameIdentity(params.identity, entryIdentity(openedStat))) {
             throw sourceChangedError(params.from);
         }
@@ -95,7 +147,11 @@ async function copyRegularFilePinned(params) {
         }
         // Re-check the opened handle before the staged tree can be committed. If
         // the source changed while we copied, the caller should retry the move.
-        if (!sameIdentity(params.identity, entryIdentity(await sourceHandle.stat()))) {
+        const finalSourceStat = await sourceHandle.stat();
+        if (params.rejectHardlinks && finalSourceStat.nlink > 1) {
+            throw hardlinkedSourceError(params.from);
+        }
+        if (!sameIdentity(params.identity, entryIdentity(finalSourceStat))) {
             throw sourceChangedError(params.from);
         }
         await fs.chmod(params.to, modeBits(params.mode)).catch(() => undefined);
@@ -123,7 +179,15 @@ async function copyEntryWithManifest(from, to, options) {
     if (sourceStat.isDirectory()) {
         await fs.mkdir(to, { mode: modeBits(sourceStat.mode) || 0o755 });
         const children = [];
-        for (const child of await fs.readdir(from)) {
+        const childNames = [];
+        const directory = await fs.opendir(from);
+        for await (const entry of directory) {
+            if (options.budget && ++options.budget.discovered > MAX_HARDLINK_PREFLIGHT_ENTRIES) {
+                throw hardlinkWalkTooLargeError();
+            }
+            childNames.push(entry.name);
+        }
+        for (const child of childNames) {
             children.push({
                 name: child,
                 manifest: await copyEntryWithManifest(path.join(from, child), path.join(to, child), options),
@@ -141,9 +205,15 @@ async function copyEntryWithManifest(from, to, options) {
         throw new Error(`Refusing to move non-file path with copy fallback: ${from}`);
     }
     if (options.sourceHardlinks === "reject" && sourceStat.nlink > 1) {
-        throw new Error(`Refusing to move hardlinked file with copy fallback: ${from}`);
+        throw hardlinkedSourceError(from);
     }
-    await copyRegularFilePinned({ from, identity, mode: sourceStat.mode, to });
+    await copyRegularFilePinned({
+        from,
+        identity,
+        mode: sourceStat.mode,
+        rejectHardlinks: options.sourceHardlinks === "reject",
+        to,
+    });
     return { ...identity, kind: "leaf" };
 }
 function mergeCleanupResults(a, b) {
@@ -189,27 +259,41 @@ async function cleanupCopiedEntry(sourcePath, manifest) {
     return "removed";
 }
 export async function movePathWithCopyFallback(options) {
-    let fallbackReason;
-    try {
-        await guardedRename({ from: options.from, to: options.to });
-        return;
+    const sourcePath = path.resolve(options.from);
+    const targetPath = path.resolve(options.to);
+    const rejectHardlinks = options.sourceHardlinks === "reject";
+    if (rejectHardlinks) {
+        await preflightSourceHardlinks(sourcePath);
     }
-    catch (error) {
-        fallbackReason = moveCopyFallbackReasonForRenameError(error);
-        if (!fallbackReason) {
-            throw error;
+    if (!rejectHardlinks) {
+        try {
+            await guardedRename({ from: sourcePath, to: targetPath });
+            return;
+        }
+        catch (error) {
+            if (!moveCopyFallbackReasonForRenameError(error)) {
+                throw error;
+            }
         }
     }
-    const targetDir = path.dirname(path.resolve(options.to));
+    else {
+        // A pathname preflight cannot make nlink and rename one atomic operation.
+        // Commit a fresh inode through the copy path so a post-scan hardlink can
+        // never become the published target; the copy loop fences nlink again.
+    }
+    await assertCopyDestinationOutsideSource(sourcePath, targetPath);
+    const targetDir = path.dirname(targetPath);
     const staged = path.join(targetDir, `.fs-safe-move-${process.pid}-${randomUUID()}.tmp`);
     try {
-        const manifest = await copyEntryWithManifest(options.from, staged, {
+        const manifest = await copyEntryWithManifest(sourcePath, staged, {
             sourceHardlinks: options.sourceHardlinks ?? "allow",
+            ...(rejectHardlinks ? { budget: { discovered: 1 } } : {}),
         });
-        await guardedRename({ from: staged, to: options.to });
-        const cleanupResult = await cleanupCopiedEntry(options.from, manifest);
+        await assertCopyDestinationOutsideSource(sourcePath, targetPath);
+        await guardedRename({ from: staged, to: targetPath });
+        const cleanupResult = await cleanupCopiedEntry(sourcePath, manifest);
         if (cleanupResult === "stale") {
-            throw sourceChangedError(options.from);
+            throw sourceChangedError(sourcePath);
         }
     }
     finally {

package/dist/native-binding.d.ts

@@ -0,0 +1,79 @@
+export interface NativeFileHash {
+    bytes: number;
+    digest: string;
+}
+export interface NativeFileIdentity {
+    dev: number;
+    ino: number;
+    mode: number;
+    nlink: number;
+    size: number;
+    isFile: boolean;
+    isDirectory: boolean;
+    isSymbolicLink: boolean;
+}
+export interface NativeArchiveEntry {
+    index: number;
+    path: string;
+    kind: string;
+    size: number;
+    mode: number;
+}
+export interface NativeArchivePlanEntry extends NativeArchiveEntry {
+}
+export interface NativeCopyResult {
+    fd: number;
+    bytes: number;
+    errorCode?: string;
+    errorMessage?: string;
+}
+export interface NativeOpenBeneathResult {
+    fd: number;
+    containment: "kernel-atomic" | "best-effort";
+}
+export interface NativeWindowsAccessControlEntry {
+    sid: string;
+    mask: number;
+    aceType: string;
+    flags: {
+        raw: number;
+        objectInherit: boolean;
+        containerInherit: boolean;
+        noPropagateInherit: boolean;
+        inheritOnly: boolean;
+        inherited: boolean;
+        successfulAccess: boolean;
+        failedAccess: boolean;
+    };
+}
+export interface NativeWindowsSecurityFacts {
+    ownerSid: string;
+    currentUserSid: string;
+    ownerClass: string;
+    worldWritable: boolean;
+    groupWritable: boolean;
+    worldReadable: boolean;
+    groupReadable: boolean;
+    fallbackRequired: boolean;
+    daclPresent: boolean;
+    isLocal: boolean;
+    aceListComplete: boolean;
+    unsupportedAceTypes: number[];
+    aces: NativeWindowsAccessControlEntry[];
+}
+export interface NativeBinding {
+    cloneFileExclusive(sourceFd: number, targetRootFd: number, targetRelPath: string): number;
+    copyFileRangeExclusive(sourceFd: number, targetRootFd: number, targetRelPath: string): Promise<NativeCopyResult>;
+    createPrivateDirectory(path: string): void;
+    extractArchiveNative(path: string, kind: string, rootFd: number, plan: NativeArchivePlanEntry[], maxMetaEntryBytes: number, signal: AbortSignal): Promise<void>;
+    fstatIdentity(fd: number): NativeFileIdentity;
+    inspectArchiveNative(path: string, kind: string, maxEntries: number, maxMetaEntryBytes: number, maxManifestBytes: number, signal: AbortSignal): Promise<NativeArchiveEntry[]>;
+    linkBeneath(sourceRootFd: number, sourceRelPath: string, targetRootFd: number, targetRelPath: string): void;
+    mkdirBeneath(rootFd: number, relPath: string, mode: number): void;
+    openBeneath(rootFd: number, relPath: string, flags: number): NativeOpenBeneathResult;
+    readArchiveEntryNative(path: string, kind: string, requested: string, maxBytes: number, maxEntries: number, maxMetaEntryBytes: number, signal: AbortSignal): Promise<Buffer>;
+    readOwnerAndDacl(path: string): NativeWindowsSecurityFacts;
+    renameNoReplace(sourceRootFd: number, sourceRelPath: string, targetRootFd: number, targetRelPath: string): void;
+    sha256File(fd: number): Promise<NativeFileHash>;
+}
+//# sourceMappingURL=native-binding.d.ts.map

package/dist/native-binding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"native-binding.d.ts","sourceRoot":"","sources":["../src/native-binding.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,CAAC;IAChB,WAAW,EAAE,OAAO,CAAC;IACrB,cAAc,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,sBAAuB,SAAQ,kBAAkB;CAAG;AAErE,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,uBAAuB;IACtC,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,eAAe,GAAG,aAAa,CAAC;CAC9C;AAED,MAAM,WAAW,+BAA+B;IAC9C,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE;QACL,GAAG,EAAE,MAAM,CAAC;QACZ,aAAa,EAAE,OAAO,CAAC;QACvB,gBAAgB,EAAE,OAAO,CAAC;QAC1B,kBAAkB,EAAE,OAAO,CAAC;QAC5B,WAAW,EAAE,OAAO,CAAC;QACrB,SAAS,EAAE,OAAO,CAAC;QACnB,gBAAgB,EAAE,OAAO,CAAC;QAC1B,YAAY,EAAE,OAAO,CAAC;KACvB,CAAC;CACH;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,OAAO,CAAC;IACvB,aAAa,EAAE,OAAO,CAAC;IACvB,aAAa,EAAE,OAAO,CAAC;IACvB,aAAa,EAAE,OAAO,CAAC;IACvB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,WAAW,EAAE,OAAO,CAAC;IACrB,OAAO,EAAE,OAAO,CAAC;IACjB,eAAe,EAAE,OAAO,CAAC;IACzB,mBAAmB,EAAE,MAAM,EAAE,CAAC;IAC9B,IAAI,EAAE,+BAA+B,EAAE,CAAC;CACzC;AAED,MAAM,WAAW,aAAa;IAC5B,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,MAAM,CAAC;IAC1F,sBAAsB,CACpB,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAC7B,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3C,oBAAoB,CAClB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,sBAAsB,EAAE,EAC9B,iBAAiB,EAAE,MAAM,EACzB,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,kBAAkB,CAAC;IAC9C,oBAAoB,CAClB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,EAClB,iBAAiB,EAAE,MAAM,EACzB,gBAAgB,EAAE,MAAM,EACxB,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAAC;IACjC,WAAW,CACT,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,MAAM,EACrB,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,MAAM,GACpB,IAAI,CAAC;IACR,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAClE,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,uBAAuB,CAAC;IACrF,sBAAsB,CACpB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,iBAAiB,EAAE,MAAM,EACzB,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,MAAM,CAAC,CAAC;IACnB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,0BAA0B,CAAC;IAC3D,eAAe,CACb,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,MAAM,EACrB,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,MAAM,GACpB,IAAI,CAAC;IACR,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;CACjD"}

package/dist/native-binding.js

@@ -0,0 +1 @@
+export {};

package/dist/native-config.d.ts

@@ -0,0 +1,17 @@
+export type FsSafeNativeMode = "auto" | "off" | "require";
+export type FsSafeNativeConfig = {
+    mode: FsSafeNativeMode;
+};
+/** @deprecated Compatibility bridge for 0.4 upgrades. Use {@link FsSafeNativeConfig}. */
+export type FsSafePythonConfig = {
+    mode: FsSafeNativeMode;
+    pythonPath?: string;
+};
+export declare function configureFsSafeNative(config: Partial<FsSafeNativeConfig>): void;
+/**
+ * @deprecated Compatibility bridge for 0.4 upgrades. Use configureFsSafeNative.
+ */
+export declare function configureFsSafePython(config: Partial<FsSafePythonConfig>): void;
+export declare function getFsSafeNativeConfig(): FsSafeNativeConfig;
+export declare function __resetFsSafeNativeConfigForTest(): void;
+//# sourceMappingURL=native-config.d.ts.map

package/dist/native-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"native-config.d.ts","sourceRoot":"","sources":["../src/native-config.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,KAAK,GAAG,SAAS,CAAC;AAE1D,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,gBAAgB,CAAC;CACxB,CAAC;AAEF,yFAAyF;AACzF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,gBAAgB,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AA8BF,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,OAAO,CAAC,kBAAkB,CAAC,GAAG,IAAI,CAE/E;AA4BD;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,OAAO,CAAC,kBAAkB,CAAC,GAAG,IAAI,CAM/E;AAED,wBAAgB,qBAAqB,IAAI,kBAAkB,CAU1D;AAED,wBAAgB,gCAAgC,IAAI,IAAI,CAGvD"}

package/dist/native-config.js

@@ -0,0 +1,71 @@
+let overrideConfig = {};
+let legacyWarningEmitted = false;
+const legacyModeEnvKeys = ["FS_SAFE_PYTHON_MODE", "OPENCLAW_FS_SAFE_PYTHON_MODE"];
+const legacyPathEnvKeys = [
+    "FS_SAFE_PYTHON",
+    "OPENCLAW_FS_SAFE_PYTHON",
+    "OPENCLAW_PINNED_PYTHON",
+    "OPENCLAW_PINNED_WRITE_PYTHON",
+];
+function parseMode(value) {
+    if (!value) {
+        return undefined;
+    }
+    const normalized = value.trim().toLowerCase();
+    if (normalized === "0" || normalized === "false" || normalized === "off" || normalized === "never") {
+        return "off";
+    }
+    if (normalized === "1" || normalized === "true" || normalized === "on" || normalized === "auto") {
+        return "auto";
+    }
+    if (normalized === "required" || normalized === "require") {
+        return "require";
+    }
+    return undefined;
+}
+export function configureFsSafeNative(config) {
+    overrideConfig = { ...overrideConfig, ...config };
+}
+function warnLegacyPythonConfiguration(source, mappedMode) {
+    if (legacyWarningEmitted) {
+        return;
+    }
+    legacyWarningEmitted = true;
+    process.emitWarning(`${source} is a deprecated 0.4 compatibility bridge; mapped to native mode ` +
+        `"${mappedMode}". Use configureFsSafeNative({ mode: "${mappedMode}" }) or ` +
+        `FS_SAFE_NATIVE_MODE=${mappedMode}. Python interpreter paths are no longer used.`, { code: "FS_SAFE_PYTHON_DEPRECATED", type: "DeprecationWarning" });
+}
+function readLegacyPythonMode() {
+    const configuredKeys = [...legacyModeEnvKeys, ...legacyPathEnvKeys].filter((key) => process.env[key] !== undefined);
+    if (configuredKeys.length === 0) {
+        return undefined;
+    }
+    const rawMode = legacyModeEnvKeys.map((key) => process.env[key]).find((value) => value !== undefined);
+    const mappedMode = parseMode(rawMode) ?? "auto";
+    warnLegacyPythonConfiguration(`Legacy ${configuredKeys.join(", ")}`, mappedMode);
+    return mappedMode;
+}
+/**
+ * @deprecated Compatibility bridge for 0.4 upgrades. Use configureFsSafeNative.
+ */
+export function configureFsSafePython(config) {
+    const mappedMode = config.mode ?? "auto";
+    warnLegacyPythonConfiguration("configureFsSafePython()", mappedMode);
+    if (config.mode !== undefined) {
+        configureFsSafeNative({ mode: config.mode });
+    }
+}
+export function getFsSafeNativeConfig() {
+    const legacyMode = readLegacyPythonMode();
+    return {
+        mode: overrideConfig.mode ??
+            parseMode(process.env.FS_SAFE_NATIVE_MODE) ??
+            parseMode(process.env.OPENCLAW_FS_SAFE_NATIVE_MODE) ??
+            legacyMode ??
+            "auto",
+    };
+}
+export function __resetFsSafeNativeConfigForTest() {
+    overrideConfig = {};
+    legacyWarningEmitted = false;
+}

package/dist/native-operations.d.ts

@@ -0,0 +1,21 @@
+import { type Stats } from "node:fs";
+import type { ContainmentGuarantee } from "./containment.js";
+import { type NativeBinding } from "./native.js";
+export type NativeFileHandle = {
+    readonly fd: number;
+    readonly containment: ContainmentGuarantee;
+    close(): Promise<void>;
+    stat(): Promise<Stats>;
+    writeFile(data: string | Buffer, encoding?: BufferEncoding): Promise<void>;
+};
+export declare function removeNativeCreatedFileIfStillPinned(params: {
+    binding: NativeBinding;
+    parentPath: string;
+    parentFd: number;
+    basename: string;
+    created?: Stats;
+}): void;
+export declare function createNativeExclusiveFile(targetPath: string, mode: number): Promise<NativeFileHandle | undefined>;
+export declare function syncNativeFileBestEffort(fd: number): void;
+export declare function writeNativeFd(fd: number, data: Buffer): void;
+//# sourceMappingURL=native-operations.d.ts.map

package/dist/native-operations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"native-operations.d.ts","sourceRoot":"","sources":["../src/native-operations.ts"],"names":[],"mappings":"AAAA,OAAe,EAAE,KAAK,KAAK,EAAE,MAAM,SAAS,CAAC;AAG7C,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAE7D,OAAO,EAAoB,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAEnE,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,WAAW,EAAE,oBAAoB,CAAC;IAC3C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,IAAI,IAAI,OAAO,CAAC,KAAK,CAAC,CAAC;IACvB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,QAAQ,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5E,CAAC;AA0CF,wBAAgB,oCAAoC,CAAC,MAAM,EAAE;IAC3D,OAAO,EAAE,aAAa,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,KAAK,CAAC;CACjB,GAAG,IAAI,CAsBP;AAED,wBAAsB,yBAAyB,CAC7C,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC,CA6CvC;AAED,wBAAgB,wBAAwB,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAQzD;AAED,wBAAgB,aAAa,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAE5D"}

package/dist/native-operations.js

@@ -0,0 +1,115 @@
+import fsSync, {} from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { sameFileIdentity } from "./file-identity.js";
+import { getNativeBinding } from "./native.js";
+function nativeOpenFlags(flags) {
+    const closeOnExec = fsSync.constants.O_CLOEXEC;
+    return (flags |
+        (closeOnExec ?? 0) |
+        (typeof fsSync.constants.O_NOFOLLOW === "number" ? fsSync.constants.O_NOFOLLOW : 0));
+}
+function writeAll(fd, data) {
+    let offset = 0;
+    while (offset < data.byteLength) {
+        const written = fsSync.writeSync(fd, data, offset, data.byteLength - offset);
+        if (written <= 0) {
+            throw Object.assign(new Error("native file write made no progress"), { code: "EIO" });
+        }
+        offset += written;
+    }
+}
+function wrapNativeFd(fd, containment) {
+    let open = true;
+    return {
+        fd,
+        containment,
+        async close() {
+            if (open) {
+                open = false;
+                fsSync.closeSync(fd);
+            }
+        },
+        async stat() {
+            return fsSync.fstatSync(fd);
+        },
+        async writeFile(data, encoding) {
+            writeAll(fd, Buffer.isBuffer(data) ? data : Buffer.from(data, encoding ?? "utf8"));
+        },
+    };
+}
+export function removeNativeCreatedFileIfStillPinned(params) {
+    if (!params.created) {
+        return;
+    }
+    try {
+        const parentPathStat = fsSync.lstatSync(params.parentPath);
+        const parentFdStat = params.binding.fstatIdentity(params.parentFd);
+        const targetPath = path.join(params.parentPath, params.basename);
+        const target = fsSync.lstatSync(targetPath);
+        if (!parentPathStat.isSymbolicLink() &&
+            parentPathStat.dev === parentFdStat.dev &&
+            parentPathStat.ino === parentFdStat.ino &&
+            !target.isSymbolicLink() &&
+            sameFileIdentity(target, params.created)) {
+            fsSync.rmSync(targetPath);
+        }
+    }
+    catch {
+        // Failed cleanup leaves a fail-closed artifact instead of deleting an
+        // unverified pathname.
+    }
+}
+export async function createNativeExclusiveFile(targetPath, mode) {
+    const binding = getNativeBinding();
+    if (!binding) {
+        return undefined;
+    }
+    const parentPath = path.dirname(targetPath);
+    const basename = path.basename(targetPath);
+    const parent = await fs.open(parentPath, fsSync.constants.O_RDONLY |
+        (typeof fsSync.constants.O_DIRECTORY === "number" ? fsSync.constants.O_DIRECTORY : 0));
+    let fd;
+    let created;
+    try {
+        const opened = binding.openBeneath(parent.fd, basename, nativeOpenFlags(fsSync.constants.O_WRONLY | fsSync.constants.O_CREAT | fsSync.constants.O_EXCL));
+        fd = opened.fd;
+        fsSync.fchmodSync(fd, mode);
+        created = fsSync.fstatSync(fd);
+        return wrapNativeFd(fd, opened.containment);
+    }
+    catch (error) {
+        if (fd !== undefined) {
+            try {
+                fsSync.closeSync(fd);
+            }
+            catch {
+                // Preserve the original error.
+            }
+            removeNativeCreatedFileIfStillPinned({
+                binding,
+                parentPath,
+                parentFd: parent.fd,
+                basename,
+                created,
+            });
+        }
+        throw error;
+    }
+    finally {
+        await parent.close().catch(() => undefined);
+    }
+}
+export function syncNativeFileBestEffort(fd) {
+    try {
+        fsSync.fsyncSync(fd);
+    }
+    catch (error) {
+        if (error.code !== "EPERM") {
+            throw error;
+        }
+    }
+}
+export function writeNativeFd(fd, data) {
+    writeAll(fd, data);
+}

package/dist/native-pinned-write.d.ts

@@ -0,0 +1,5 @@
+import type { FileIdentityStat } from "./file-identity.js";
+import type { NativeBinding } from "./native.js";
+import type { PinnedWriteParams } from "./pinned-write.js";
+export declare function runPinnedWriteNative(binding: NativeBinding, params: PinnedWriteParams): Promise<FileIdentityStat>;
+//# sourceMappingURL=native-pinned-write.d.ts.map

package/dist/native-pinned-write.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"native-pinned-write.d.ts","sourceRoot":"","sources":["../src/native-pinned-write.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAM3D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,KAAK,EAAoB,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAiD7E,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,aAAa,EACtB,MAAM,EAAE,iBAAiB,GACxB,OAAO,CAAC,gBAAgB,CAAC,CA4F3B"}

package/dist/native-pinned-write.js

@@ -0,0 +1,115 @@
+import { randomUUID } from "node:crypto";
+import fsSync, {} from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { FsSafeError } from "./errors.js";
+import { removeNativeCreatedFileIfStillPinned, syncNativeFileBestEffort, writeNativeFd, } from "./native-operations.js";
+function assertWithinMaxBytes(bytes, maxBytes) {
+    if (maxBytes !== undefined && bytes > maxBytes) {
+        throw new FsSafeError("too-large", `file exceeds limit of ${maxBytes} bytes (got at least ${bytes})`);
+    }
+}
+async function inputToBuffer(input, maxBytes) {
+    if (input.kind === "buffer") {
+        const data = typeof input.data === "string"
+            ? Buffer.from(input.data, input.encoding ?? "utf8")
+            : Buffer.from(input.data);
+        assertWithinMaxBytes(data.byteLength, maxBytes);
+        return data;
+    }
+    const chunks = [];
+    let bytes = 0;
+    for await (const chunk of input.stream) {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        bytes += buffer.byteLength;
+        assertWithinMaxBytes(bytes, maxBytes);
+        chunks.push(buffer);
+    }
+    return Buffer.concat(chunks, bytes);
+}
+function nativeOpenFlags(flags) {
+    const closeOnExec = fsSync.constants.O_CLOEXEC;
+    return (flags |
+        (closeOnExec ?? 0) |
+        (typeof fsSync.constants.O_NOFOLLOW === "number" ? fsSync.constants.O_NOFOLLOW : 0));
+}
+function sameNativeIdentity(left, right) {
+    return left.dev === right.dev && left.ino === right.ino;
+}
+export async function runPinnedWriteNative(binding, params) {
+    const data = await inputToBuffer(params.input, params.maxBytes);
+    const root = await fs.open(params.rootPath, fsSync.constants.O_RDONLY |
+        (typeof fsSync.constants.O_DIRECTORY === "number" ? fsSync.constants.O_DIRECTORY : 0));
+    let parentFd;
+    let tempFd;
+    let targetFd;
+    let tempIdentity;
+    let parentPath = params.rootPath;
+    const tempName = `.${params.basename}.${randomUUID()}.native.tmp`;
+    let renamed = false;
+    try {
+        const rootIdentity = binding.fstatIdentity(root.fd);
+        if (params.rootIdentity && !sameNativeIdentity(params.rootIdentity, rootIdentity)) {
+            throw new FsSafeError("path-mismatch", "root path changed during native write");
+        }
+        if (params.mkdir) {
+            binding.mkdirBeneath(root.fd, params.relativeParentPath, 0o777);
+        }
+        const parentFlags = fsSync.constants.O_RDONLY |
+            (typeof fsSync.constants.O_DIRECTORY === "number" ? fsSync.constants.O_DIRECTORY : 0);
+        parentFd = binding.openBeneath(root.fd, params.relativeParentPath, parentFlags).fd;
+        parentPath = await fs.realpath(params.relativeParentPath
+            ? path.join(params.rootPath, ...params.relativeParentPath.split("/"))
+            : params.rootPath);
+        const parentPathStat = await fs.lstat(parentPath);
+        const parentIdentity = binding.fstatIdentity(parentFd);
+        if (parentPathStat.isSymbolicLink() ||
+            !sameNativeIdentity(parentPathStat, parentIdentity)) {
+            throw new FsSafeError("path-mismatch", "native write parent changed during resolution");
+        }
+        try {
+            await fs.lstat(path.join(parentPath, params.basename));
+            throw Object.assign(new Error("destination already exists"), { code: "EEXIST" });
+        }
+        catch (error) {
+            if (error.code !== "ENOENT") {
+                throw error;
+            }
+        }
+        tempFd = binding.openBeneath(parentFd, tempName, nativeOpenFlags(fsSync.constants.O_WRONLY | fsSync.constants.O_CREAT | fsSync.constants.O_EXCL)).fd;
+        fsSync.fchmodSync(tempFd, params.mode || 0o600);
+        writeNativeFd(tempFd, data);
+        syncNativeFileBestEffort(tempFd);
+        tempIdentity = fsSync.fstatSync(tempFd);
+        binding.renameNoReplace(parentFd, tempName, parentFd, params.basename);
+        renamed = true;
+        targetFd = binding.openBeneath(parentFd, params.basename, nativeOpenFlags(fsSync.constants.O_RDONLY)).fd;
+        const targetIdentity = binding.fstatIdentity(targetFd);
+        if (!targetIdentity.isFile || !sameNativeIdentity(tempIdentity, targetIdentity)) {
+            throw new FsSafeError("path-mismatch", "native write target changed after rename");
+        }
+        syncNativeFileBestEffort(parentFd);
+        return { dev: targetIdentity.dev, ino: targetIdentity.ino };
+    }
+    finally {
+        if (targetFd !== undefined) {
+            fsSync.closeSync(targetFd);
+        }
+        if (tempFd !== undefined) {
+            fsSync.closeSync(tempFd);
+        }
+        if (!renamed && parentFd !== undefined) {
+            removeNativeCreatedFileIfStillPinned({
+                binding,
+                parentPath,
+                parentFd,
+                basename: tempName,
+                created: tempIdentity,
+            });
+        }
+        if (parentFd !== undefined) {
+            fsSync.closeSync(parentFd);
+        }
+        await root.close().catch(() => undefined);
+    }
+}