@openclaw/openshell-sandbox 2026.9.5 → 2026.9.7

package/node_modules/@openclaw/fs-safe/dist/native-staged-file.js

@@ -50,18 +50,21 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
     var e = new Error(message);
     return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
 });
+import { assertDarwinCreationAcl, assertPrivateCreationFile } from "./creation-boundary.js";
 import { requireNativeBinding } from "./native.js";
 import { syncFileBestEffortSync } from "./file-sync.js";
 import { randomUUID } from "node:crypto";
-import fs from "node:fs";
+import fs, {} from "node:fs";
 import path from "node:path";
 import { FsSafeError } from "./errors.js";
-import { MutationAuthorityError } from "./mutation-authority.js";
+import { assertSynchronousCallbackResult, MutationAuthorityError } from "./mutation-authority.js";
 import { captureNativeFdClose } from "./native-binding.js";
-import { writeNativeInput } from "./native-operations.js";
+import { writePinnedInput } from "./pinned-write-input.js";
 import { assertNativeCopyCompleted, createNativeCopyFile } from "./copy-file-input.js";
 import { assertStagedDirectoryCurrent, openStagedDirectory } from "./staged-directory.js";
 import { assertFinalSymlinkRejected } from "./root-symlink-policy.js";
+import { classifyNativeRenameFailure } from "./native-rename-outcome.js";
+import { createStagedFileReceipt, stagedFileFailure as failure } from "./staged-file-settlement.js";
 export function assertNativeStaging(binding) {
     if ([
         binding.closeOwnedFd,
@@ -81,54 +84,34 @@ function assertBasename(name, portable) {
     }
 }
 const NOT_PUBLISHED = Object.freeze({ status: "not-published" });
-const UNCOMMITTED_RENAME_ERRORS = new Set([
-    "EACCES", "EBADF", "EBUSY", "EEXIST", "EINVAL", "EISDIR", "ELOOP", "EMLINK",
-    "ENAMETOOLONG", "ENOENT", "ENOSPC", "ENOSYS", "ENOTDIR", "ENOTEMPTY", "ENOTSUP",
-    "EPERM", "EROFS", "ETXTBSY", "EXDEV",
-]);
-function failure(error, details) {
-    const code = error instanceof FsSafeError
-        ? error.code
-        : error?.code === "EEXIST" ? "already-exists" : "helper-failed";
-    return new FsSafeError(code, `staged file ${details.phase} failed`, { cause: error, details });
-}
 class NativeStagedFile {
-    #binding;
+    #owner;
     #closeFd;
-    #parentFd;
-    #closeParentFd;
-    #directory;
-    #portableNames;
-    #publishedMode;
-    #sync;
     #assertBeforeMutation;
-    #name = `.fs-safe-${randomUUID()}.tmp`;
+    #private;
+    #verifyMode;
     #state = { status: "open", publication: NOT_PUBLISHED };
     #receipt;
     #rejectFinalSymlink = false;
-    constructor(binding, parentFd, closeParentFd, directory, portableNames, publishedMode, sync, assertBeforeMutation) {
-        this.#closeFd = captureNativeFdClose(binding);
-        this.#binding = binding;
-        this.#parentFd = parentFd;
-        this.#closeParentFd = closeParentFd;
-        this.#directory = directory;
-        this.#portableNames = portableNames;
-        this.#publishedMode = publishedMode;
-        this.#sync = sync;
-        this.#assertBeforeMutation = assertBeforeMutation;
+    constructor(owner) {
+        const name = owner.name ?? `.fs-safe-${randomUUID()}.tmp`;
+        assertBasename(name, owner.portableNames !== false);
+        this.#closeFd = captureNativeFdClose(owner.binding);
+        this.#owner = { ...owner, name };
+        this.#assertBeforeMutation = owner.assertBeforeMutation;
+        this.#private = owner.permissionPolicy === "private-creation";
+        this.#verifyMode = owner.permissionPolicy !== undefined;
     }
     // Public staging supplies a Node parent; pinned writes supply a native parent.
     // The supplied closer owns parentFd even on construction or preparation failure.
-    static async create(binding, parentFd, closeParentFd, directory, input, mode, maxBytes, 
-    // Public staging uses portable names; existing POSIX writes accept literal names.
-    portableNames = true, sync = true, assertBeforeMutation) {
+    static async create(owner, input, maxBytes) {
         let staged;
         try {
-            staged = new NativeStagedFile(binding, parentFd, closeParentFd, directory, portableNames, mode, sync, assertBeforeMutation);
+            staged = new NativeStagedFile(owner);
         }
         catch (error) {
             try {
-                closeParentFd(parentFd);
+                owner.closeParentFd(owner.parentFd);
             }
             catch (closeError) {
                 throw new AggregateError([error, closeError], "staged owner construction and close failed");
@@ -141,15 +124,38 @@ class NativeStagedFile {
     static async write(binding, parentFd, closeParentFd, directory, params, parentGuard) {
         const env_1 = { stack: [], error: void 0, hasError: false };
         try {
+            const exclusive = params.overwrite === false && params.input.kind === "buffer" && params.input.stageBeforePublish === false;
             // This owner never escapes. Only the internal verifier borrows its fd;
             // public descriptor methods remain await-free and cannot race disposal.
-            const staged = __addDisposableResource(env_1, await NativeStagedFile.create(binding, parentFd, closeParentFd, directory, params.input, params.mode, params.maxBytes, false, params.sync, params.assertBeforeMutation), true);
+            const staged = __addDisposableResource(env_1, await NativeStagedFile.create({
+                binding, parentFd, closeParentFd, directory, mode: params.mode, sync: params.sync,
+                // Public staging uses portable names; existing POSIX writes accept literal names.
+                portableNames: false, assertBeforeMutation: params.assertBeforeMutation,
+                name: exclusive ? params.basename : undefined, strictFileSync: params.strictFileSync,
+                permissionPolicy: params.private ? "private-creation" : params.verifyPosixMode === true ? "mode-only" : undefined,
+            }, params.input, params.maxBytes), true);
             staged.#rejectFinalSymlink = params.rejectFinalSymlink === true;
             if (params.input.kind === "file")
                 await params.input.verifySource();
-            const published = await staged.publish(params.basename, { overwrite: params.overwrite !== false }, params.onPublished);
+            if (exclusive) {
+                staged.#assertCurrent();
+                params.assertBeforeMutation?.();
+                if (staged.#verifyMode)
+                    staged.#assertCurrent();
+            }
+            const published = exclusive
+                ? staged.#completePublication(params.basename, false, params.onPublished)
+                : await staged.publish(params.basename, { overwrite: params.overwrite !== false }, params.onPublished);
             const identity = published.staged.identity;
-            await params.verifyPublished?.(staged.#file(), identity, parentGuard);
+            try {
+                await params.verifyPublished?.(staged.#file(), identity, parentGuard);
+            }
+            catch (error) {
+                if (params.overwrite === false && params.input.kind !== "file" && params.input.stageBeforePublish === true) {
+                    throw failure(error, { phase: "publish", publication: published });
+                }
+                throw error;
+            }
             return { dev: identity.dev, ino: identity.ino };
         }
         catch (e_1) {
@@ -181,66 +187,96 @@ class NativeStagedFile {
         }
         return state.fileFd;
     }
-    #assertNamed(name) {
+    #assertNamed(name, expectedMode) {
         const fd = this.#file();
-        const stat = this.#binding.stagedFileMatches(this.#parentFd, name, fd)
+        const stat = this.#owner.binding.stagedFileMatches(this.#owner.parentFd, name, fd)
             ? fs.fstatSync(fd, { bigint: true }) : undefined;
         if (!stat || stat.nlink !== 1n) {
             throw new FsSafeError("path-mismatch", "staged entry no longer names the exclusive created file");
         }
+        this.#assertPermissions(fd, stat, expectedMode);
         return Number(stat.mode & 4095n);
     }
     #assertCurrent() {
         if (this.#open().publication.status !== "not-published") {
             throw new FsSafeError("helper-failed", "staged file publication has already been attempted");
         }
-        assertStagedDirectoryCurrent(this.#directory);
-        this.#assertNamed(this.#name);
+        assertStagedDirectoryCurrent(this.#owner.directory);
+        this.#assertNamed(this.#owner.name, 0o600);
+    }
+    #assertPermissions(fd, stat, expectedMode) {
+        if (this.#private)
+            assertPrivateCreationFile(stat, fd);
+        if (this.#verifyMode && Number(stat.mode & 4095n) !== expectedMode) {
+            throw new FsSafeError("insecure-permissions", "filesystem did not enforce the staged file mode");
+        }
+    }
+    #assertStagePermissions(fd) {
+        this.#assertPermissions(fd, fs.fstatSync(fd, { bigint: true }), 0o600);
     }
     async #prepare(input, maxBytes) {
         try {
-            const mode = this.#publishedMode;
+            const mode = this.#owner.mode;
             if (!Number.isInteger(mode) || mode < 0 || mode > 0o7777) {
                 throw new FsSafeError("invalid-path", "invalid staged file mode");
             }
-            assertStagedDirectoryCurrent(this.#directory);
+            const fileSignal = input.kind === "file" && this.#verifyMode ? input.signal : undefined;
+            if (input.kind === "file" && this.#verifyMode) {
+                fileSignal?.throwIfAborted();
+                if (input.clone === "always") {
+                    throw new FsSafeError("helper-unavailable", "required cloning cannot verify staged permissions before copying");
+                }
+            }
+            assertStagedDirectoryCurrent(this.#owner.directory);
             // The exclusive open performs no fallible post-open checks. Store its fd
             // before every subsequent operation, including the first metadata read.
             const state = this.#open();
+            if (this.#private)
+                assertDarwinCreationAcl(this.#owner.parentFd, "file");
             this.#assertBeforeMutation?.();
-            const copied = input.kind === "file"
-                ? await createNativeCopyFile(this.#binding, input, this.#parentFd, this.#name, maxBytes, false)
+            if (this.#private)
+                assertDarwinCreationAcl(this.#owner.parentFd, "file");
+            // Native copying populates its new file before returning its descriptor.
+            const copied = input.kind === "file" && !this.#verifyMode
+                ? await createNativeCopyFile(this.#owner.binding, input, this.#owner.parentFd, this.#owner.name, maxBytes, false)
                 : undefined;
             state.fileFd = copied?.fd;
             if (state.fileFd === undefined) {
                 this.#assertBeforeMutation?.();
-                state.fileFd = this.#binding.createStagedFile(this.#parentFd, this.#name);
+                if (this.#private)
+                    assertDarwinCreationAcl(this.#owner.parentFd, "file");
+                state.fileFd = this.#owner.binding.createStagedFile(this.#owner.parentFd, this.#owner.name);
             }
             const fd = state.fileFd;
             if (input.kind === "file")
                 assertNativeCopyCompleted(input, copied);
-            this.#assertBeforeMutation?.();
+            const assertBeforeChmod = this.#assertBeforeMutation;
+            const beforeChmodResult = assertBeforeChmod?.();
+            if (this.#private) {
+                assertSynchronousCallbackResult(beforeChmodResult, "assertBeforeMutation");
+                assertPrivateCreationFile(fs.fstatSync(fd, { bigint: true }), fd);
+            }
             fs.fchmodSync(fd, 0o600);
+            // Some filesystems report successful chmod without enforcing its mode.
+            if (this.#verifyMode)
+                this.#assertStagePermissions(fd);
+            const assertBeforeMutation = this.#verifyMode ? () => {
+                assertSynchronousCallbackResult(this.#assertBeforeMutation?.(), "assertBeforeMutation");
+                fileSignal?.throwIfAborted();
+                this.#assertStagePermissions(fd);
+            } : this.#assertBeforeMutation;
             if (!copied)
-                await writeNativeInput(fd, input, maxBytes, this.#assertBeforeMutation);
-            if (this.#sync)
-                syncFileBestEffortSync(fd);
+                await writePinnedInput(fd, input, maxBytes, assertBeforeMutation);
+            if (this.#verifyMode)
+                this.#assertStagePermissions(fd);
+            if (this.#owner.sync !== false) {
+                if (this.#owner.strictFileSync)
+                    fs.fsyncSync(fd);
+                else
+                    syncFileBestEffortSync(fd);
+            }
             const stat = fs.fstatSync(fd, { bigint: true });
-            this.#receipt = Object.freeze({
-                directory: this.#directory,
-                temporaryBasename: this.#name,
-                identity: Object.freeze({
-                    dev: stat.dev,
-                    ino: stat.ino,
-                    mode: Number(stat.mode & 4095n),
-                    nlink: stat.nlink,
-                    size: stat.size,
-                    uid: Number(stat.uid),
-                    gid: Number(stat.gid),
-                    mtimeNs: stat.mtimeNs,
-                    ctimeNs: stat.ctimeNs,
-                }),
-            });
+            this.#receipt = createStagedFileReceipt(this.#owner.directory, this.#owner.name, stat);
             this.#assertCurrent();
         }
         catch (error) {
@@ -263,55 +299,33 @@ class NativeStagedFile {
         const overwrite = options?.overwrite;
         try {
             const state = this.#open();
-            assertBasename(basename, this.#portableNames);
-            if (basename === this.#name || typeof overwrite !== "boolean") {
+            assertBasename(basename, this.#owner.portableNames !== false);
+            if (basename === this.#owner.name || typeof overwrite !== "boolean") {
                 throw new FsSafeError("invalid-path", "publication needs a distinct basename and explicit overwrite policy");
             }
             this.#assertCurrent();
-            assertFinalSymlinkRejected(path.join(this.#directory.realPath, basename), this.#rejectFinalSymlink);
+            assertFinalSymlinkRejected(path.join(this.#owner.directory.realPath, basename), this.#rejectFinalSymlink);
             this.#assertBeforeMutation?.();
+            if (this.#assertBeforeMutation) {
+                this.#assertCurrent();
+                assertFinalSymlinkRejected(path.join(this.#owner.directory.realPath, basename), this.#rejectFinalSymlink);
+            }
             try {
                 if (overwrite) {
-                    this.#binding.renameReplace(this.#parentFd, this.#name, this.#parentFd, basename);
+                    this.#owner.binding.renameReplace(this.#owner.parentFd, this.#owner.name, this.#owner.parentFd, basename);
                 }
                 else {
-                    this.#binding.renameNoReplace(this.#parentFd, this.#name, this.#parentFd, basename);
+                    this.#owner.binding.renameNoReplace(this.#owner.parentFd, this.#owner.name, this.#owner.parentFd, basename);
                 }
             }
             catch (error) {
-                // Unknown rename errors can be indeterminate on remote filesystems.
-                if (!UNCOMMITTED_RENAME_ERRORS.has(error?.code ?? "")) {
+                // Only explicit pre-dispatch provenance can rule out a committed rename.
+                if (classifyNativeRenameFailure(error) === "indeterminate") {
                     state.publication = Object.freeze({ status: "indeterminate", basename, overwrite });
                 }
                 throw error;
             }
-            // Commit is recorded synchronously before any post-rename operation.
-            const receipt = Object.freeze({
-                status: "published",
-                staged: this.receipt,
-                basename,
-                overwrite,
-            });
-            state.publication = receipt;
-            onPublished?.(receipt.staged.identity);
-            const stagedMode = this.#assertNamed(basename);
-            assertStagedDirectoryCurrent(this.#directory);
-            // Keep contents private until the published name passes its identity
-            // fence. Mode changes use the owned fd, including for final mode 000.
-            const fd = this.#file();
-            if (this.#publishedMode !== 0o600 || stagedMode !== 0o600)
-                fs.fchmodSync(fd, this.#publishedMode);
-            // With sync enabled, content was synced before rename. A lost chmod leaves staged 0600,
-            // no wider than modes retaining owner rw. Restrictive modes and observed
-            // widening of the stage still need the permission correction made durable.
-            if (this.#sync && ((this.#publishedMode & 0o600) !== 0o600 || (stagedMode & ~this.#publishedMode) !== 0)) {
-                syncFileBestEffortSync(fd);
-            }
-            if (this.#sync)
-                syncFileBestEffortSync(this.#parentFd);
-            this.#assertNamed(basename);
-            assertStagedDirectoryCurrent(this.#directory);
-            return receipt;
+            return this.#completePublication(basename, overwrite, onPublished);
         }
         catch (error) {
             if (error instanceof MutationAuthorityError)
@@ -323,6 +337,32 @@ class NativeStagedFile {
             throw failure(error, { phase: "publish", publication });
         }
     }
+    #completePublication(basename, overwrite, onPublished) {
+        // Record complete content before fallible post-publication verification.
+        const receipt = Object.freeze({ status: "published", staged: this.receipt, basename, overwrite });
+        this.#open().publication = receipt;
+        onPublished?.(receipt.staged.identity);
+        const stagedMode = this.#assertNamed(basename, 0o600);
+        assertStagedDirectoryCurrent(this.#owner.directory);
+        // Keep contents private until the name passes its identity fence. Mode
+        // changes use the owned fd, including for final mode 000.
+        const fd = this.#file();
+        if (this.#owner.mode !== 0o600 || stagedMode !== 0o600)
+            fs.fchmodSync(fd, this.#owner.mode);
+        // Content was synced during preparation. A lost chmod leaves 0600, no wider
+        // than modes retaining owner rw; restrictive modes still need a durable correction.
+        if (this.#owner.sync !== false && ((this.#owner.mode & 0o600) !== 0o600 || (stagedMode & ~this.#owner.mode) !== 0)) {
+            if (this.#owner.strictFileSync)
+                fs.fsyncSync(fd);
+            else
+                syncFileBestEffortSync(fd);
+        }
+        if (this.#owner.sync !== false)
+            syncFileBestEffortSync(this.#owner.parentFd);
+        this.#assertNamed(basename, this.#owner.mode);
+        assertStagedDirectoryCurrent(this.#owner.directory);
+        return receipt;
+    }
     #finalize() {
         if (this.#state.status === "closed") {
             return this.#state;
@@ -335,7 +375,7 @@ class NativeStagedFile {
         }
         else if (state.publication.status === "not-published" && state.fileFd !== undefined) {
             try {
-                outcome = this.#binding.removeStagedFile(this.#parentFd, this.#name, state.fileFd);
+                outcome = this.#owner.binding.removeStagedFile(this.#owner.parentFd, this.#owner.name, state.fileFd);
             }
             catch (error) {
                 outcome = "failed";
@@ -345,7 +385,7 @@ class NativeStagedFile {
         let resources = "closed";
         for (const [fd, closeFd] of [
             [state.fileFd, this.#closeFd],
-            [this.#parentFd, this.#closeParentFd],
+            [this.#owner.parentFd, this.#owner.closeParentFd],
         ]) {
             if (fd === undefined) {
                 continue;
@@ -359,7 +399,7 @@ class NativeStagedFile {
             }
         }
         const receipt = Object.freeze({
-            temporaryBasename: this.#name,
+            temporaryBasename: this.#owner.name,
             publication: state.publication,
             status: outcome,
             resources,
@@ -395,5 +435,8 @@ export async function stageFileInDirectory(options) {
     const input = { kind: "buffer", data: Buffer.from(options.content) };
     const mode = options.mode ?? 0o600;
     const parent = openStagedDirectory(options.directory);
-    return await createNativeStage(binding, parent.fd, fs.closeSync, parent.receipt, input, mode);
+    return await createNativeStage({
+        binding, parentFd: parent.fd, closeParentFd: fs.closeSync,
+        directory: parent.receipt, mode, permissionPolicy: "mode-only",
+    }, input);
 }

package/node_modules/@openclaw/fs-safe/dist/native-staged-symlink.d.ts

@@ -0,0 +1,13 @@
+import { type BigIntStats, type Stats } from "node:fs";
+import type { DirectoryReceipt } from "./directory-durability.js";
+import type { StagedSymlink, StagedSymlinkExpected } from "./staged-symlink-types.js";
+/**
+ * Admit an existing staged symlink against caller-captured identity and retain
+ * its no-follow descriptor. Admission never creates, adopts by target, or unlinks.
+ */
+export declare function retainSymlinkInDirectory(options: {
+    directory: string | DirectoryReceipt<Stats | BigIntStats>;
+    basename: string;
+    expected: StagedSymlinkExpected;
+    assertBeforeMutation: () => void;
+}): Promise<StagedSymlink>;