@openclaw/openshell-sandbox 2026.9.4 → 2026.9.6

package/node_modules/@openclaw/fs-safe/dist/native-pinned-write.js

@@ -50,74 +50,363 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
     var e = new Error(message);
     return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
 });
-import fsSync from "node:fs";
-import fs from "node:fs/promises";
+import fsSync, {} from "node:fs";
 import path from "node:path";
 import { inspectDirectoryIdentity } from "./directory-guard.js";
 import { FsSafeError } from "./errors.js";
-import { runPinnedWriteWindows, sameNativeIdentity } from "./native-pinned-write-windows.js";
+import { runPinnedWriteWindows } from "./native-pinned-write-windows.js";
+import { capturePolicyAwareWindowsParent } from "./native-policy-parent-windows.js";
+import { openNativeParentAdmission, openNativeRootAdmission } from "./native-parent-admission.js";
 import { assertNativeStaging, writeNativeStage } from "./native-staged-file.js";
-import { describeStagedDirectory, exactIdentityMatches } from "./staged-directory.js";
+import { captureNativeFdClose } from "./native-binding.js";
+import { NativePolicyDirectoryMismatch } from "./native-policy-directory-observation.js";
+import { assertPolicyStagedDirectoryCurrent, assertStagedDirectoryCurrent, describePolicyStagedDirectory, describeStagedDirectory, refreshPolicyStagedDirectoryObservation, } from "./staged-directory.js";
 import { inspectFileIdentitySync } from "./strict-file-identity.js";
-export async function runPinnedWriteNative(binding, params) {
+import { realpathSync } from "./realpath.js";
+import { errorCauseOptions } from "./root-errors.js";
+import { isNotFoundPathError, isSymlinkOpenError } from "./path.js";
+import { checkedMutationDirectory, } from "./pinned-mutation-observation.js";
+import { createPathSegmentRoute, joinPathSegmentRoute } from "./path-segment-route.js";
+function sameAbsolutePath(left, right) {
+    return path.relative(path.resolve(left), path.resolve(right)) === "";
+}
+function assertDirectChildBasename(basename) {
+    if (!basename || basename === "." || basename === ".." || basename.includes("/") ||
+        basename.includes("\0") || (process.platform === "win32" && basename.includes("\\"))) {
+        throw new FsSafeError("invalid-path", "native parent creation requires one direct-child basename");
+    }
+}
+function mkdirPolicyChild(binding, parentFd, basename, mode) {
+    assertDirectChildBasename(basename);
+    const mkdirChild = binding.mkdirChildBeneath;
+    if (typeof mkdirChild === "function") {
+        const created = mkdirChild.call(binding, parentFd, basename, mode);
+        if (typeof created === "boolean")
+            return created;
+    }
+    // Old or malformed optional helpers still execute through the established
+    // recursive primitive, but cannot provide exclusive-creation provenance.
+    binding.mkdirBeneath(parentFd, basename, mode);
+    return false;
+}
+async function authorizePinnedMutation(params, request) {
+    return await params.mutationAdmission?.authorize(Object.freeze(request));
+}
+function normalizePolicyParentOpenError(error, params) {
+    if (!isSymlinkOpenError(error))
+        return error;
+    return params.mutationAdmission?.rejectParentSymlinks
+        ? new FsSafeError("symlink", "symlink path component not allowed", errorCauseOptions(error))
+        : new FsSafeError("path-mismatch", "native write parent changed during policy admission", errorCauseOptions(error));
+}
+async function describePosixParent(parentFd, pathname) {
+    const parentPath = realpathSync.native(pathname);
+    const directory = describeStagedDirectory(parentFd, parentPath);
+    const parentPathStat = await inspectDirectoryIdentity(parentPath, inspectFileIdentitySync(() => fsSync.fstatSync(parentFd, { bigint: true })));
+    return {
+        parentFd,
+        parentPath,
+        directory,
+        parentPathStat,
+        observation: checkedMutationDirectory(parentPath, directory.realPath, parentPathStat),
+    };
+}
+function describePolicyPosixParent(binding, parentFd, pathname) {
+    const policyDirectory = describePolicyStagedDirectory(parentFd, pathname, binding);
+    return {
+        parentFd,
+        parentPath: policyDirectory.directory.realPath,
+        directory: policyDirectory.directory,
+        parentPathStat: policyDirectory.stat,
+        observation: policyDirectory.observation,
+        policyDirectory,
+    };
+}
+function policyParentCaptureDeopt(error) {
+    return error instanceof FsSafeError &&
+        !(error instanceof NativePolicyDirectoryMismatch) &&
+        (error.code === "path-mismatch" || error.code === "not-file");
+}
+function tryDescribePolicyPosixParent(binding, parentFd, pathname) {
+    try {
+        return describePolicyPosixParent(binding, parentFd, pathname);
+    }
+    catch (error) {
+        if (!policyParentCaptureDeopt(error))
+            throw error;
+        return undefined;
+    }
+}
+function assertPosixParentCurrent(parent) {
+    return parent.policyDirectory
+        ? assertPolicyStagedDirectoryCurrent(parent.policyDirectory)
+        : assertStagedDirectoryCurrent(parent.directory);
+}
+async function capturePolicyAwarePosixParent(binding, params, rootFd, directoryFlags) {
     const env_1 = { stack: [], error: void 0, hasError: false };
     try {
+        const closeFd = captureNativeFdClose(binding);
+        const observationDisposers = new Map();
+        const disposeObservation = (fd) => {
+            const dispose = observationDisposers.get(fd);
+            observationDisposers.delete(fd);
+            dispose?.();
+        };
+        const observationScope = __addDisposableResource(env_1, {
+            [Symbol.dispose]() { for (const dispose of observationDisposers.values())
+                dispose(); },
+        }, false);
+        const capturePolicyParent = (fd, pathname) => {
+            const captured = tryDescribePolicyPosixParent(binding, fd, pathname);
+            const dispose = captured?.policyDirectory?.disposeObservation;
+            if (dispose)
+                observationDisposers.set(fd, dispose);
+            return captured;
+        };
+        const segments = params.relativeParentPath.split("/").filter(Boolean);
+        const parentSpelling = segments.length
+            ? path.join(params.rootPath, ...segments)
+            : params.rootPath;
+        const segmentRoute = createPathSegmentRoute(segments);
+        const initialTarget = joinPathSegmentRoute(params.rootPath, segmentRoute, 0, params.basename);
+        let retainedTargetPath = params.mutationAdmission?.beginParentWalk?.();
+        if (retainedTargetPath && !sameAbsolutePath(retainedTargetPath, initialTarget)) {
+            retainedTargetPath = undefined;
+        }
+        // Preserve the one-open hot path when the complete parent still exists.
+        // Policy is attached only after the opened descriptor is associated with its
+        // current canonical pathname, so a contained redirect cannot retain the old
+        // preflight authorization.
+        let completeParentFd;
+        try {
+            completeParentFd = binding.openBeneath(rootFd, params.relativeParentPath, directoryFlags).fd;
+        }
+        catch (error) {
+            if (error?.code !== "ENOENT" || !params.mkdir)
+                throw error;
+        }
+        if (completeParentFd !== undefined) {
+            const parentFd = completeParentFd;
+            try {
+                let admitted = retainedTargetPath
+                    ? capturePolicyParent(parentFd, parentSpelling)
+                    : undefined;
+                if (!admitted) {
+                    retainedTargetPath = undefined;
+                    admitted = await describePosixParent(parentFd, parentSpelling);
+                }
+                const targetPath = path.join(admitted.parentPath, params.basename);
+                await authorizePinnedMutation(params, {
+                    targetPath,
+                    mutationPath: targetPath,
+                    phase: "parent",
+                });
+                assertPosixParentCurrent(admitted);
+                return admitted;
+            }
+            catch (error) {
+                disposeObservation(parentFd);
+                closeFd(parentFd);
+                throw error;
+            }
+        }
+        // The canonical preflight spelling has no intentional symlinks in its
+        // existing prefix. Walk missing-parent cases one direct child at a time so
+        // every existing/opened object is authorized and every mkdir is authorized
+        // before dispatch. O_NOFOLLOW makes a concurrently introduced link fail
+        // before the next component can be created through it.
+        const secureDirectoryFlags = directoryFlags | (fsSync.constants.O_NOFOLLOW ?? 0);
+        let currentFd = rootFd;
+        let currentOwnedFd;
+        let currentPath = params.rootPath;
+        let current = retainedTargetPath
+            ? capturePolicyParent(rootFd, currentPath)
+            : undefined;
+        if (!current) {
+            retainedTargetPath = undefined;
+            current = await describePosixParent(rootFd, currentPath);
+        }
+        try {
+            await authorizePinnedMutation(params, {
+                targetPath: retainedTargetPath ?? initialTarget,
+                mutationPath: retainedTargetPath ?? initialTarget,
+                phase: "parent",
+            });
+            assertPosixParentCurrent(current);
+            for (let index = 0; index < segments.length; index += 1) {
+                const segment = segments[index];
+                const childPath = path.join(currentPath, segment);
+                let childFd;
+                let createdByMkdir = false;
+                let createReceipt;
+                try {
+                    childFd = binding.openBeneath(currentFd, segment, secureDirectoryFlags).fd;
+                }
+                catch (openError) {
+                    if (!isNotFoundPathError(openError)) {
+                        throw normalizePolicyParentOpenError(openError, params);
+                    }
+                    const targetPath = retainedTargetPath ?? joinPathSegmentRoute(currentPath, segmentRoute, index, params.basename);
+                    const request = Object.freeze({
+                        targetPath,
+                        mutationPath: childPath,
+                        phase: "parent-create",
+                    });
+                    createReceipt = params.mutationAdmission?.tryAuthorizeAtParent?.(request, current.observation);
+                    if (!createReceipt) {
+                        createReceipt = await authorizePinnedMutation(params, request);
+                        assertPosixParentCurrent(current);
+                    }
+                    params.assertBeforeMutation?.();
+                    // Do not carry pathname freshness across the live authority callback.
+                    assertPosixParentCurrent(current);
+                    createdByMkdir = mkdirPolicyChild(binding, currentFd, segment, 0o777);
+                    try {
+                        childFd = binding.openBeneath(currentFd, segment, secureDirectoryFlags).fd;
+                    }
+                    catch (createdOpenError) {
+                        throw normalizePolicyParentOpenError(createdOpenError, params);
+                    }
+                }
+                let child;
+                try {
+                    const acceleratedChild = retainedTargetPath
+                        ? capturePolicyParent(childFd, childPath)
+                        : undefined;
+                    if (acceleratedChild) {
+                        child = acceleratedChild;
+                    }
+                    else {
+                        retainedTargetPath = undefined;
+                        child = await describePosixParent(childFd, childPath);
+                    }
+                    if (!sameAbsolutePath(child.parentPath, childPath))
+                        retainedTargetPath = undefined;
+                    let childAuthorization;
+                    if (createdByMkdir && createReceipt && params.mutationAdmission?.advanceCreatedDirectory) {
+                        let evidence;
+                        try {
+                            const parent = current.policyDirectory
+                                ? refreshPolicyStagedDirectoryObservation(current.policyDirectory)
+                                : checkedMutationDirectory(currentPath, current.directory.realPath, assertStagedDirectoryCurrent(current.directory));
+                            evidence = Object.freeze({
+                                admission: createReceipt,
+                                parent,
+                                child: child.observation,
+                            });
+                        }
+                        catch {
+                            // Leave failed evidence to the full ordered admission below.
+                        }
+                        if (evidence) {
+                            childAuthorization = params.mutationAdmission.advanceCreatedDirectory(evidence);
+                        }
+                    }
+                    const targetPath = retainedTargetPath ?? joinPathSegmentRoute(child.parentPath, segmentRoute, index + 1, params.basename);
+                    const request = Object.freeze({
+                        targetPath,
+                        mutationPath: targetPath,
+                        phase: "parent",
+                    });
+                    childAuthorization ??= params.mutationAdmission?.tryAuthorizeAtParent?.(request, child.observation);
+                    if (!childAuthorization) {
+                        await authorizePinnedMutation(params, request);
+                        assertPosixParentCurrent(child);
+                    }
+                }
+                catch (error) {
+                    disposeObservation(childFd);
+                    closeFd(childFd);
+                    throw error;
+                }
+                const previousOwnedFd = currentOwnedFd;
+                disposeObservation(current.parentFd);
+                currentOwnedFd = child.parentFd;
+                currentFd = child.parentFd;
+                currentPath = child.parentPath;
+                current = child;
+                if (previousOwnedFd !== undefined)
+                    closeFd(previousOwnedFd);
+                if (index === segments.length - 1) {
+                    currentOwnedFd = undefined;
+                    return child;
+                }
+            }
+            // Empty relative parents are handled by the complete-parent fast path.
+            throw new FsSafeError("path-mismatch", "native write parent admission did not complete");
+        }
+        finally {
+            if (currentOwnedFd !== undefined) {
+                disposeObservation(currentOwnedFd);
+                closeFd(currentOwnedFd);
+            }
+        }
+    }
+    catch (e_1) {
+        env_1.error = e_1;
+        env_1.hasError = true;
+    }
+    finally {
+        __disposeResources(env_1);
+    }
+}
+export async function runPinnedWriteNative(binding, params) {
+    const env_2 = { stack: [], error: void 0, hasError: false };
+    try {
+        const closeFd = captureNativeFdClose(binding);
         const windows = process.platform === "win32";
         if (!windows) {
             assertNativeStaging(binding);
         }
         const directoryFlags = fsSync.constants.O_RDONLY | (fsSync.constants.O_DIRECTORY ?? 0);
-        const root = await fs.open(params.rootPath, directoryFlags);
-        const posixRoot = __addDisposableResource(env_1, windows ? undefined : root, true);
+        const completeCreate = params.overwrite === false && params.input.kind !== "file" && params.input.stageBeforePublish === true;
+        const rootAdmission = await openNativeRootAdmission(binding, {
+            rootPath: params.rootPath,
+            rootIdentity: params.rootIdentity,
+            operation: "native write",
+            reportCloseErrors: completeCreate,
+        });
+        const root = rootAdmission.root;
+        const posixRoot = __addDisposableResource(env_2, windows ? undefined : root, true);
         let parentFd;
         let windowsOwnsDirectories = false;
+        let admissionFailure;
         // Until stage construction takes ownership, even admission failures must close
         // the raw POSIX parent. Disposal preserves both admission and close failures.
-        const parentGuard = __addDisposableResource(env_1, {
+        const parentGuard = __addDisposableResource(env_2, {
             [Symbol.dispose]() {
                 if (!windows && parentFd !== undefined) {
-                    fsSync.closeSync(parentFd);
+                    closeFd(parentFd);
                 }
             },
         }, false);
         try {
-            const exactRoot = typeof params.rootIdentity?.dev === "bigint" && typeof params.rootIdentity.ino === "bigint"
-                ? { dev: params.rootIdentity.dev, ino: params.rootIdentity.ino } : undefined;
-            let rootMatches;
-            if (exactRoot) {
-                inspectFileIdentitySync(() => fsSync.fstatSync(root.fd, { bigint: true }), exactRoot);
-                rootMatches = true;
+            let parentPath;
+            let directory;
+            let parentPathStat;
+            if (!windows && params.mutationAdmission) {
+                const admitted = await capturePolicyAwarePosixParent(binding, params, root.fd, directoryFlags);
+                parentFd = admitted.parentFd;
+                parentPath = admitted.parentPath;
+                directory = admitted.directory;
+                parentPathStat = admitted.parentPathStat;
             }
-            else if (windows) {
-                const identity = binding.fstatIdentity(root.fd);
-                rootMatches = !params.rootIdentity || sameNativeIdentity(params.rootIdentity, identity);
+            else if (windows && params.mutationAdmission) {
+                const admitted = await capturePolicyAwareWindowsParent(binding, params, rootAdmission);
+                parentFd = admitted.fd;
+                parentPath = admitted.guard.realPath;
+                parentPathStat = admitted.guard.stat;
             }
             else {
-                const identity = fsSync.fstatSync(root.fd, { bigint: true });
-                rootMatches = !params.rootIdentity || exactIdentityMatches(params.rootIdentity, identity);
-            }
-            if (!rootMatches) {
-                throw new FsSafeError("path-mismatch", "root path changed during native write");
-            }
-            if (params.mkdir) {
-                binding.mkdirBeneath(root.fd, params.relativeParentPath, 0o777);
-            }
-            parentFd = binding.openBeneath(root.fd, params.relativeParentPath, directoryFlags).fd;
-            const parentPath = fsSync.realpathSync.native(params.relativeParentPath
-                ? path.join(params.rootPath, ...params.relativeParentPath.split("/"))
-                : params.rootPath);
-            const directory = windows ? undefined : describeStagedDirectory(parentFd, parentPath);
-            const parentPathStat = exactRoot
-                ? await inspectDirectoryIdentity(parentPath, inspectFileIdentitySync(() => fsSync.fstatSync(parentFd, { bigint: true })))
-                : fsSync.lstatSync(parentPath);
-            if (windows && !exactRoot) {
-                const parentIdentity = binding.fstatIdentity(parentFd);
-                if (parentPathStat.isSymbolicLink() || !sameNativeIdentity(parentPathStat, parentIdentity)) {
-                    throw new FsSafeError("path-mismatch", "native write parent changed during resolution");
+                if (params.mkdir) {
+                    params.assertBeforeMutation?.();
+                    binding.mkdirBeneath(root.fd, params.relativeParentPath, 0o777);
                 }
-            }
-            else if (!windows && (parentPathStat.isSymbolicLink() || !exactIdentityMatches(parentPathStat, directory.identity))) {
-                throw new FsSafeError("path-mismatch", "native write parent changed during resolution");
+                const admitted = await openNativeParentAdmission(binding, rootAdmission, params.relativeParentPath);
+                parentFd = admitted.fd;
+                parentPath = admitted.guard.realPath;
+                directory = admitted.stagedDirectory;
+                parentPathStat = admitted.guard.stat;
             }
             const verificationGuard = { dir: parentPath, realPath: parentPath, stat: parentPathStat };
             if (params.overwrite === false) {
@@ -138,23 +427,45 @@ export async function runPinnedWriteNative(binding, params) {
             }
             const ownedParent = parentFd;
             parentFd = undefined;
-            return await writeNativeStage(binding, ownedParent, directory, params, verificationGuard);
+            return await writeNativeStage(binding, ownedParent, closeFd, directory, params, verificationGuard);
+        }
+        catch (error) {
+            admissionFailure = { error };
+            throw error;
         }
         finally {
             if (windows && !windowsOwnsDirectories) {
+                const closeErrors = [];
                 if (parentFd !== undefined) {
-                    fsSync.closeSync(parentFd);
+                    // Match the Windows leaf cleanup contract: an admission or identity
+                    // failure remains primary, while every owned directory is still given
+                    // a close attempt. In particular, a parent close failure must not skip
+                    // the root FileHandle close.
+                    try {
+                        closeFd(parentFd);
+                    }
+                    catch (error) {
+                        closeErrors.push(error);
+                    }
+                }
+                try {
+                    await root.close();
+                }
+                catch (error) {
+                    closeErrors.push(error);
+                }
+                if (completeCreate && closeErrors.length > 0) {
+                    throw new AggregateError([...(admissionFailure ? [admissionFailure.error] : []), ...closeErrors], "native create admission and close failed");
                 }
-                await root.close().catch(() => undefined);
             }
         }
     }
-    catch (e_1) {
-        env_1.error = e_1;
-        env_1.hasError = true;
+    catch (e_2) {
+        env_2.error = e_2;
+        env_2.hasError = true;
     }
     finally {
-        const result_1 = __disposeResources(env_1);
+        const result_1 = __disposeResources(env_2);
         if (result_1)
             await result_1;
     }

package/node_modules/@openclaw/fs-safe/dist/native-policy-directory-observation.d.ts

@@ -0,0 +1,11 @@
+import { FsSafeError } from "./errors.js";
+import type { NativeBinding } from "./native-binding.js";
+import type { MutationDirectoryObserver } from "./pinned-mutation-observation.js";
+export declare class NativePolicyDirectoryMismatch extends FsSafeError {
+    constructor(cause?: Error);
+}
+export type NativePolicyDirectoryObserver = MutationDirectoryObserver & {
+    dispose(): void;
+};
+/** Fresh name/metadata/canonical facts from a caller-owned POSIX descriptor. */
+export declare function nativePolicyDirectoryObserver(binding: NativeBinding | undefined, fd: number, pathname: string): NativePolicyDirectoryObserver | undefined;

package/node_modules/@openclaw/fs-safe/dist/native-policy-directory-observation.js

@@ -0,0 +1,61 @@
+import path from "node:path";
+import { FsSafeError } from "./errors.js";
+import { getFsSafeNativeConfig } from "./native-config.js";
+export class NativePolicyDirectoryMismatch extends FsSafeError {
+    constructor(cause) {
+        super("path-mismatch", "staging directory pathname changed", { cause });
+    }
+}
+/** Fresh name/metadata/canonical facts from a caller-owned POSIX descriptor. */
+export function nativePolicyDirectoryObserver(binding, fd, pathname) {
+    if (!binding || process.platform === "win32" || process.versions.bun)
+        return undefined;
+    const observe = binding.observeDirectoryFd;
+    if (typeof observe !== "function")
+        return undefined;
+    const mode = getFsSafeNativeConfig().mode;
+    let disposed = false;
+    const inspect = () => {
+        if (disposed)
+            throw new NativePolicyDirectoryMismatch();
+        if (getFsSafeNativeConfig().mode !== mode)
+            return undefined;
+        let observed;
+        try {
+            observed = observe.call(binding, fd, pathname);
+        }
+        catch (error) {
+            if (error?.code === "OBSERVATION_UNAVAILABLE")
+                return undefined;
+            if (error?.code === "OBSERVATION_REDIRECTED") {
+                // A contained redirect requires ordinary selected-object admission;
+                // it has not yet supplied inconsistent descriptor/name evidence.
+                throw new FsSafeError("path-mismatch", "staging directory pathname redirected");
+            }
+            if (error?.code === "path-mismatch") {
+                throw new NativePolicyDirectoryMismatch(error instanceof Error ? error : undefined);
+            }
+            throw error;
+        }
+        if (getFsSafeNativeConfig().mode !== mode)
+            return undefined;
+        if (!observed || typeof observed.dev !== "bigint" || observed.dev < 0n || observed.dev > 0xffffffffffffffffn ||
+            typeof observed.ino !== "bigint" || observed.ino < 0n || observed.ino > 0xffffffffffffffffn ||
+            typeof observed.mode !== "bigint" || observed.mode < 0n || observed.mode > 0xffffffffn ||
+            typeof observed.nlink !== "bigint" || observed.nlink < 0n || observed.nlink > 0xffffffffffffffffn ||
+            typeof observed.realPath !== "string" || observed.realPath.includes("\0") ||
+            !path.isAbsolute(observed.realPath))
+            return undefined;
+        if ((observed.mode & 61440n) !== 16384n || observed.nlink === 0n ||
+            observed.realPath !== pathname) {
+            throw new NativePolicyDirectoryMismatch();
+        }
+        return Object.freeze({
+            canonicalPath: observed.realPath,
+            identity: Object.freeze({
+                dev: observed.dev, ino: observed.ino, mode: observed.mode, nlink: observed.nlink,
+            }),
+        });
+    };
+    return Object.assign(inspect, { dispose() { disposed = true; } });
+}

package/node_modules/@openclaw/fs-safe/dist/native-policy-parent-windows.d.ts

@@ -0,0 +1,13 @@
+import { type BigIntStats } from "node:fs";
+import { type AsyncDirectoryGuard } from "./directory-guard.js";
+import { type NativeRootAdmission } from "./native-parent-admission.js";
+import type { NativeBinding } from "./native.js";
+import type { PinnedWriteParams } from "./pinned-write-types.js";
+import { type MutationDirectoryObservation } from "./pinned-mutation-observation.js";
+type PolicyParent = {
+    fd: number;
+    guard: AsyncDirectoryGuard<BigIntStats>;
+    observation: MutationDirectoryObservation;
+};
+export declare function capturePolicyAwareWindowsParent(binding: NativeBinding, params: PinnedWriteParams, rootAdmission: NativeRootAdmission): Promise<PolicyParent>;
+export {};