@openclaw/openshell-sandbox 2026.9.6 → 2026.9.8

package/node_modules/@openclaw/fs-safe/README.md

@@ -10,7 +10,7 @@
 
 Capability-style filesystem roots for Node.js apps that handle untrusted relative paths.
 
-Think Go's `os.Root` / `OpenInRoot` or Rust's [`cap-std`](https://github.com/bytecodealliance/cap-std), but for Node. Hand `root()` a trusted directory and you get back a handle whose every method resolves relative paths against it and defends against `..`, symlink swaps, hardlink aliases, and TOCTOU rename races. The exact containment strength is reported per mechanism: Linux native opens are kernel-atomic; macOS, Windows, and JavaScript paths are best-effort.
+Think Go's `os.Root` / `OpenInRoot` or Rust's [`cap-std`](https://github.com/bytecodealliance/cap-std), but for Node. Hand `root()` a trusted directory and you get back a handle whose every method resolves relative paths against it and defends against `..`, symlink swaps, hardlink aliases, and TOCTOU rename races. The exact containment strength is reported per mechanism: Linux `openat2` opens are kernel-atomic; guarded Linux fallback, macOS, Windows, and JavaScript paths are best-effort.
 
 ```ts
 import { root } from "@openclaw/fs-safe";
@@ -45,7 +45,7 @@ The same idea has landed in other languages. Go [added `os.Root` and `OpenInRoot
 | `path.resolve().startsWith()` | string check only | – | – | – | – |
 | [`write-file-atomic`](https://www.npmjs.com/package/write-file-atomic) | – | ✓ | – | – | – |
 | Go [`os.Root`](https://go.dev/blog/osroot) / Rust [`cap-std`](https://github.com/bytecodealliance/cap-std) | ✓ | platform | ✓ | ✓ | – |
-| **`@openclaw/fs-safe`** | **✓** | **✓** | **✓** | **Linux atomic; others best-effort** | **✓ (ZIP/TAR/gzip/zstd/bzip2)** |
+| **`@openclaw/fs-safe`** | **✓** | **✓** | **✓** | **Linux openat2 atomic; others best-effort** | **✓ (ZIP/TAR/gzip/zstd/bzip2)** |
 
 ## Not a sandbox
 
@@ -84,7 +84,9 @@ reports the escape. Use `require` when hostile concurrent mutation is in scope.
 
 Equivalent env var: `FS_SAFE_NATIVE_MODE=auto|off|require`. The seven bindings
 ship as exact-version optional packages filtered by OS, CPU, and Linux libc, so
-a normal install receives only its matching binary. There are no postinstall
+a normal install receives only its matching binary. Linux GNU x64/arm64 bindings
+support [glibc 2.28 or newer](docs/install.md#supported-native-platforms), including
+RHEL 8-family systems. There are no postinstall
 steps, runtime downloads, or consumer Rust builds. On a platform without a
 published binding, or when optional dependencies are omitted, `auto` silently retains lexical and canonical root
 checks, no-follow opens, guarded temp+rename writes, and post-write identity
@@ -94,8 +96,11 @@ tradeoff, and [native architecture](docs/native.md) for the platform mechanisms
 and policy ownership model.
 
 Open results report the mechanism's containment class as `"kernel-atomic"` or
-`"best-effort"`. Linux native `openBeneath()` is kernel-atomic; macOS, Windows,
-and guarded JavaScript results are best-effort. See the [security model](docs/security-model.md#containment-guarantees-by-platform) before using that fact in higher-level policy.
+`"best-effort"`. Linux native `openBeneath()` is kernel-atomic when `openat2`
+is available. Older kernels and syscall-filtered containers use a guarded
+descriptor-relative walk reporting best-effort; nested no-clobber moves keep
+atomic `renameat2(RENAME_NOREPLACE)`. macOS, Windows, and guarded JavaScript
+results are best-effort. See [Linux compatibility](docs/native.md#linux-without-openat2). See the [security model](docs/security-model.md#containment-guarantees-by-platform) before using that fact in higher-level policy.
 
 ## Migrating from the Python helper
 
@@ -274,6 +279,7 @@ contract. Low-level helpers that OpenClaw needs to compose higher-level APIs are
 | `@openclaw/fs-safe/secure-file` | fd-pinned absolute file reads with owner, mode, ACL, trusted-dir, size, and timeout checks |
 | `@openclaw/fs-safe/file-lock` | async/sync sidecar locks, root-bounded sidecars, ownership verification, and stale policy |
 | `@openclaw/fs-safe/permissions` | POSIX mode and Windows ACL inspection, raw owner/ACE facts, private-directory creation, and remediation helpers |
+| [`@openclaw/fs-safe/watch`](docs/watch.md) | Guarded observation with native event hints, bounded scans, and joined close |
 | `@openclaw/fs-safe/walk` | budget-bounded directory walking with symlink policy, filters, and truncation accounting; not root-bounded |
 | `@openclaw/fs-safe/copy` | directory copying with `clone: "auto"`, `"always"`, or `"never"`; native APFS, Btrfs, ReFS, XFS, and ZFS cloning, portable byte copying, and clone metadata; see [directory copying](docs/copy.md) |
 | `@openclaw/fs-safe/archive` | policy-driven ZIP/TAR extraction, clamp/filter policy, metadata/path-depth limits, gzip/zstd/bzip2 support, and bounded entry reads |
@@ -342,6 +348,11 @@ original directory on Linux/macOS and requires native support for this operation
 It offers atomic replace/no-replace publication, not expected-inode replacement
 or a crash-durability promise; application checks and coordination remain yours.
 
+For an already staged POSIX symlink, [`retainSymlinkInDirectory()`](docs/staged-symlink.md)
+admits caller-captured identity and retains that exact inode through no-replace
+publication or explicit recovery. Same-target foreign replacements are not adopted.
+Staging, cooperative locking and crash recovery remain application responsibilities.
+
 `replaceFileAtomic()` writes a sibling temp file, applies its exact mode through the still-open descriptor, optionally fsyncs it, and renames it over the destination. It never follows the published destination path to set file permissions. Mode preservation inherits only rwx bits from an existing non-symlink regular file; special bits, ownership, ACLs, and extended attributes are not copied. Pinned-destination hardlink rejection, rename retry / copy fallback on `EPERM`, bounded original-content restoration after a torn fallback, parent-directory fsync, and a `beforeRename` hook for backup or observer flows are all opt-in. `movePathWithCopyFallback()` stages cross-device moves before commit and removes only the copied source entries, so concurrent source additions or replacements are preserved. Its optional synchronous `assertBeforeMutation` hook rechecks caller authority before renames and each source removal; `onDestinationPublished` reports an exact bigint destination identity before later checks or cleanup can fail. See [mutation authority and publication receipts](docs/atomic.md#mutation-authority-and-publication-receipts).
 
 ```ts
@@ -358,6 +369,12 @@ await replaceFileAtomic({
 
 `replaceFileAtomicSync()` covers the synchronous case with the same options shape. Both accept an injectable `fileSystem` for tests. Async adapters use `chmod()` on the `FileHandle` returned by their required `open()` operation; custom sync adapters using `mode` or `preserveExistingMode` provide the optional descriptor-bound `fchmodSync` operation.
 
+Both variants accept `assertBeforeMutation` for revocable caller authority and
+`onDestinationState` for observed removal, partial-write, and publication facts.
+The observer receives exact bigint identities from retained descriptors, including
+when later completion fails. These facts do not authorize rollback; the caller
+still owns current authority and content checks. See [atomic write authority](docs/atomic.md#atomic-write-authority-and-destination-state).
+
 ## External outputs
 
 Use `writeExternalFileWithinRoot()` when a browser download, renderer, media
@@ -549,7 +566,8 @@ Check `scan.truncated` before treating the result as complete, and `scan.failedD
 `walkDirectory()` accepts asynchronous `include` and `descend` callbacks through `AsyncWalkDirectoryOptions`, so a marker lookup can prune a directory before its children are read. Decisions remain serial and retain the options object as their `this` receiver; `walkDirectorySync()` and its options remain synchronous. See [Directory walking](docs/walk.md) for callback timing, JavaScript result compatibility, and error handling.
 
 For caller-controlled paths, `Root.walk()` is the root-bounded async iterator.
-It supports entry/depth budgets, in-root symlink following, cancellation, and a
+It supports entry/depth budgets, including links without following their targets,
+in-root symlink following, cancellation, and a
 truncation marker (or typed error) when a budget is reached. Its `entryFilter`
 accepts `"include"`, `"skip"`, or `"skip-subtree"`, directly or through a Promise.
 After an awaited decision resolves, the walk rechecks cancellation and the

package/node_modules/@openclaw/fs-safe/dist/advanced.d.ts

@@ -8,6 +8,8 @@ export { resolvePathPrefixSync, type ResolvedPathPrefix } from "./path-prefix.js
 export { probePathSuffixAliasesSync, type ProbePathSuffixAliasesOptions } from "./path-suffix-aliases.js";
 export { readDirectoryIdentity, assertDirectoryIdentitySync, type DirectoryIdentity, } from "./directory-guard.js";
 export { stageFileInDirectory, } from "./native-staged-file.js";
+export { retainSymlinkInDirectory } from "./native-staged-symlink.js";
+export type { StagedSymlink, StagedSymlinkExpected, StagedSymlinkReceipt, PublishedSymlinkReceipt, StagedSymlinkPublication, StagedSymlinkRemoval, StagedSymlinkCleanupReceipt, StagedSymlinkFailureDetails, } from "./staged-symlink-types.js";
 export type { StagedFile, StagedFileReceipt, PublishedFileReceipt, StagedFilePublication, StagedFileCleanupReceipt, StagedFileFailureDetails, } from "./staged-file-types.js";
 export { readFileDescriptorBounded, readFileDescriptorBoundedSync, readFileHandleBounded, } from "./bounded-read.js";
 export { readFileWindowFully, readFileWindowFullySync, type ReadFileWindowOptions, } from "./positional-read.js";
@@ -33,4 +35,7 @@ export { resolveHomeRelativePath } from "./home-dir.js";
 export { appendRegularFile, appendRegularFileSync, readRegularFile, readRegularFileSync, resolveRegularFileAppendFlags, statRegularFile, statRegularFileSync, type AppendRegularFileOptions, type RegularFileStatResult, } from "./regular-file.js";
 export { buildRandomTempFilePath, sanitizeTempFileName, type TempFile, tempFile, withTempFile, } from "./temp-target.js";
 export { writeSiblingTempFile, writeViaSiblingTempPath, type WriteSiblingTempFileOptions, type WriteSiblingTempFileResult, } from "./sibling-temp.js";
-export { createIcaclsResetCommand, formatIcaclsResetCommand, formatWindowsAclSummary, inspectWindowsAcl, parseIcaclsOutput, resolveWindowsUserPrincipal, summarizeWindowsAcl, type IcaclsResetCommandOptions, type PermissionCommandFailure, type PermissionExec, type WindowsAclEntry, type WindowsAclSummary, } from "./permissions.js";
+export { createIcaclsResetCommand, formatIcaclsResetCommand, formatWindowsAclSummary, inspectWindowsAcl, parseIcaclsOutput, resolveWindowsUserPrincipal, summarizeWindowsAcl, type IcaclsResetCommandOptions, type PermissionExec, type WindowsAclEntry, type WindowsAclSummary, } from "./permissions-windows.js";
+export type { PermissionCommandFailure } from "./permission-exec.js";
+export { retainFileInDirectory } from "./retained-file.js";
+export type { RetainedFile, RetainedFileAdmission, RetainedFileExpected, RetainedFileIssue, RetainedFileReceipt, RetainedFileResult, RetainFileInDirectoryOptions, } from "./retained-file-types.js";

package/node_modules/@openclaw/fs-safe/dist/advanced.js

@@ -11,6 +11,7 @@ export { resolvePathPrefixSync } from "./path-prefix.js";
 export { probePathSuffixAliasesSync } from "./path-suffix-aliases.js";
 export { readDirectoryIdentity, assertDirectoryIdentitySync, } from "./directory-guard.js";
 export { stageFileInDirectory, } from "./native-staged-file.js";
+export { retainSymlinkInDirectory } from "./native-staged-symlink.js";
 export { readFileDescriptorBounded, readFileDescriptorBoundedSync, readFileHandleBounded, } from "./bounded-read.js";
 export { readFileWindowFully, readFileWindowFullySync, } from "./positional-read.js";
 export { writeFileWindowFully } from "./write-file-handle.js";
@@ -35,4 +36,5 @@ export { resolveHomeRelativePath } from "./home-dir.js";
 export { appendRegularFile, appendRegularFileSync, readRegularFile, readRegularFileSync, resolveRegularFileAppendFlags, statRegularFile, statRegularFileSync, } from "./regular-file.js";
 export { buildRandomTempFilePath, sanitizeTempFileName, tempFile, withTempFile, } from "./temp-target.js";
 export { writeSiblingTempFile, writeViaSiblingTempPath, } from "./sibling-temp.js";
-export { createIcaclsResetCommand, formatIcaclsResetCommand, formatWindowsAclSummary, inspectWindowsAcl, parseIcaclsOutput, resolveWindowsUserPrincipal, summarizeWindowsAcl, } from "./permissions.js";
+export { createIcaclsResetCommand, formatIcaclsResetCommand, formatWindowsAclSummary, inspectWindowsAcl, parseIcaclsOutput, resolveWindowsUserPrincipal, summarizeWindowsAcl, } from "./permissions-windows.js";
+export { retainFileInDirectory } from "./retained-file.js";

package/node_modules/@openclaw/fs-safe/dist/archive-durability.js

@@ -78,7 +78,7 @@ export async function finalizeArchivePublication(params) {
                     const env_1 = { stack: [], error: void 0, hasError: false };
                     try {
                         await assertGuards(file.guards);
-                        const opened = __addDisposableResource(env_1, await params.targetRoot.open(file.relativePath, { hardlinks: "reject", symlinks: "reject" })
+                        const opened = __addDisposableResource(env_1, await params.targetRoot.open(`./${file.relativePath}`, { hardlinks: "reject", symlinks: "reject" })
                             .catch((error) => {
                             if (error instanceof FsSafeError && (error.code === "hardlink" || error.code === "path-alias")) {
                                 throw createArchiveSymlinkTraversalError(file.relativePath);

package/node_modules/@openclaw/fs-safe/dist/archive-merge.js

@@ -3,7 +3,6 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { ownExtractionDestinationMutation } from "./archive-deadline.js";
 import { assertDirectoryIdentityGuard, assertResolvedInsideDestination, createDirectoryIdentityGuard, createArchiveSymlinkTraversalError, preparePrivateArchiveOutputPath, withStagedArchiveDestination, } from "./archive-staging.js";
-import {} from "./directory-mode-owner.js";
 import { pinNodeDirectoryForMode } from "./directory-mode-node.js";
 import { assertSyncDirectoryGuard, inspectDirectoryIdentitySync } from "./directory-guard.js";
 import { FsSafeError } from "./errors.js";
@@ -251,7 +250,7 @@ async function mergeTree(params, publication, durable = true, entryUmask = 0) {
                                 }
                             };
                         }
-                        await targetRoot.copyIn(relPath, sourcePath, options);
+                        await targetRoot.copyIn(`./${relPath}`, sourcePath, options);
                         check();
                         await assertGuards();
                         await assertResolvedInsideDestination({

package/node_modules/@openclaw/fs-safe/dist/archive-plan.d.ts

@@ -54,14 +54,9 @@ export type TarEntryInfo = {
     mode?: number;
 };
 export declare function createTarEntryPlanner(params: ArchivePlanOptions): (entry: TarEntryInfo) => ArchivePlanEntry | null;
-export declare function createTarEntryPreflightChecker(params: {
+export declare function createTarEntryPreflightChecker(params: Omit<ArchivePlanOptions & {
     rootDir: string;
-    stripComponents?: number;
-    limits?: ArchiveExtractLimits;
-    escapeLabel?: string;
-    entryFilter?: ArchiveEntryFilter;
-    onFiltered?: ArchiveFilteredEntryPolicy;
-}): (entry: TarEntryInfo) => boolean;
+}, "entryModes">): (entry: TarEntryInfo) => boolean;
 export type ArchiveLogger = {
     info?: (message: string) => void;
     warn?: (message: string) => void;

package/node_modules/@openclaw/fs-safe/dist/archive-read.js

@@ -11,9 +11,8 @@ import { resolveArchiveKind } from "./archive-kind.js";
 import { DEFAULT_MAX_ARCHIVE_BYTES_ZIP, ArchiveLimitError, ARCHIVE_LIMIT_ERROR_CODE, } from "./archive-limits.js";
 import { isGzipBuffer } from "./archive-gzip-tail.js";
 import { inspectTar, replayTar } from "./archive-tar-stream.js";
-import { loadAdmittedZipArchive } from "./archive-zip-loader.js";
+import { loadAdmittedZipArchive, assertZipEntryBinding } from "./archive-zip-loader.js";
 import { createZipIntegrityTransform, normalizeZipIntegrityError, } from "./archive-zip-integrity.js";
-import { isZipSymlinkEntry, zipEntryKind } from "./archive-zip-entry.js";
 import { FsSafeError } from "./errors.js";
 import { inspectFileIdentity } from "./strict-file-identity.js";
 import { resolveReadOpenFlags } from "./read-open-flags.js";
@@ -93,27 +92,19 @@ async function readArchiveInput(archivePath) {
     }
 }
 async function readZipEntry(buffer, entryPath, maxBytes, admitted) {
-    const archive = await loadAdmittedZipArchive(buffer, admitted);
-    let entry;
-    // JSZip keys retain some aliases and may use Unicode Path metadata. Scan the
-    // effective entries once, after raw ZIP admission has rejected collisions.
-    for (const candidate of Object.values(archive.files)) {
-        if (canonicalEntryPath(candidate.name) !== entryPath)
-            continue;
-        if (entry) {
-            throw new ArchiveSecurityError("entry-path", `archive contains duplicate entry path: ${formatErrorDetail(entryPath)}`);
-        }
-        entry = candidate;
-    }
-    if (!entry || entry.dir) {
+    const { archive, entries } = await loadAdmittedZipArchive(buffer, admitted);
+    const record = entries.get(entryPath);
+    if (!record || record.entry.dir) {
         throw new Error(`archive entry not found: ${formatErrorDetail(entryPath)}`);
     }
-    if (isZipSymlinkEntry(entry)) {
+    assertZipEntryBinding(archive, record, entryPath);
+    const { entry, kind } = record;
+    if (kind === "symlink") {
         throw new Error(`archive entry is a link: ${formatErrorDetail(entryPath)}`);
     }
-    if (zipEntryKind(entry) !== "file")
+    if (kind !== "file")
         throw new Error(`archive entry is not a file: ${formatErrorDetail(entryPath)}`);
-    const integrity = createZipIntegrityTransform(entry);
+    const integrity = createZipIntegrityTransform(record);
     const stream = typeof entry.nodeStream === "function"
         ? entry.nodeStream()
         : Readable.from(await entry.async("nodebuffer"));

package/node_modules/@openclaw/fs-safe/dist/archive-staging.d.ts

@@ -3,7 +3,6 @@ import { type AsyncDirectoryGuard } from "./directory-guard.js";
 import { type ExtractionDeadline } from "./archive-deadline.js";
 import { ArchiveSecurityError } from "./archive-errors.js";
 export type ArchiveDirectoryGuard = AsyncDirectoryGuard<BigIntStats>;
-export { ArchiveSecurityError, type ArchiveSecurityErrorCode } from "./archive-errors.js";
 export declare function createDirectoryIdentityGuard(dir: string): Promise<ArchiveDirectoryGuard>;
 export declare function assertDirectoryIdentityGuard(guard: ArchiveDirectoryGuard): Promise<void>;
 export declare function prepareArchiveDestinationGuard(destDir: string): Promise<ArchiveDirectoryGuard>;
@@ -29,5 +28,5 @@ export declare function withStagedArchiveDestination<T>(params: {
     stagingDirPrefix?: string;
     run: (stagingDir: string) => Promise<T>;
 }): Promise<T>;
-export { mergeExtractedTreeIntoDestination } from "./archive-merge.js";
 export declare function createArchiveSymlinkTraversalError(originalPath: string): ArchiveSecurityError;
+export {};

package/node_modules/@openclaw/fs-safe/dist/archive-staging.js

@@ -21,7 +21,6 @@ const ARCHIVE_STAGING_MODE = 0o700;
 function checkExtractionDeadline(deadline) {
     deadline?.check();
 }
-export { ArchiveSecurityError } from "./archive-errors.js";
 function symlinkTraversalError(originalPath) {
     return new ArchiveSecurityError("destination-symlink-traversal", `${ERROR_ARCHIVE_ENTRY_TRAVERSES_SYMLINK}: ${formatErrorDetail(originalPath)}`);
 }
@@ -134,7 +133,9 @@ export async function assertResolvedInsideDestination(params) {
 }
 async function mkdirArchiveOutput(params) {
     try {
-        await params.targetRoot.mkdir(params.relativePath);
+        const relativePath = params.relativePath;
+        // Archive names are literal; retain Root.mkdir's admission without home expansion.
+        await params.targetRoot.mkdir(relativePath === "~" || relativePath.startsWith("~/") ? `./${relativePath}` : relativePath);
     }
     catch (error) {
         if (error instanceof FsSafeError) {
@@ -302,7 +303,6 @@ export async function withStagedArchiveDestination(params) {
         }
     }
 }
-export { mergeExtractedTreeIntoDestination } from "./archive-merge.js";
 export function createArchiveSymlinkTraversalError(originalPath) {
     return symlinkTraversalError(originalPath);
 }

package/node_modules/@openclaw/fs-safe/dist/archive-zip-directory.js

@@ -1,5 +1,6 @@
 import { assertArchiveEntryCountWithinLimit, } from "./archive-limits.js";
 import { admitZipNames, zipExtraFields, zipFormat, zipUInt64 } from "./archive-zip-names.js";
+import { createArchiveOutputPathTracker } from "./archive-entry.js";
 function entryKind(attributes, directory) {
     const type = (attributes >>> 16) & 0o170000;
     // High-word symlinks remain links regardless of the creator or directory bits.
@@ -186,6 +187,7 @@ export function* scanZipDirectory(size, limits, onEntry) {
     const directory = yield* layout(size);
     assertArchiveEntryCountWithinLimit(directory.count, limits);
     const seen = new Set();
+    const trackKnownPath = createArchiveOutputPathTracker();
     const spans = [];
     let at = directory.start;
     let count = 0;
@@ -226,6 +228,8 @@ export function* scanZipDirectory(size, limits, onEntry) {
         const localNames = yield* read(localAt + 30, localNameLength + localExtraLength, directory.start);
         const localExtra = zipExtraFields(localNames.subarray(localNameLength));
         const admittedName = admitZipNames({ central: centralName, local: localNames.subarray(0, localNameLength), flags, centralExtra, localExtra, seen });
+        if (admittedName.path !== undefined)
+            trackKnownPath(admittedName.path, admittedName.path);
         const localValues = wideValues(local, localExtra, false);
         const crc = central.readUInt32LE(16);
         if (!(flags & 8) && (local.readUInt32LE(14) !== crc || localValues.compressed !== values.compressed || localValues.uncompressed !== values.uncompressed)) {

package/node_modules/@openclaw/fs-safe/dist/archive-zip-entry.d.ts

@@ -1,4 +1,4 @@
-import { type ArchiveEntryModePolicy, type ArchiveEntryKind } from "./archive-plan.js";
+import type { ArchiveEntryKind } from "./archive-plan.js";
 import type { ZipDirectoryEntry } from "./archive-zip-directory.js";
 export type ZipEntry = {
     name: string;
@@ -12,13 +12,13 @@ export type ZipEntry = {
     nodeStream?: () => NodeJS.ReadableStream;
     async: (type: "nodebuffer") => Promise<Buffer>;
 };
-/** Internal: register only after the complete decoder/admission association. */
-export declare function registerAdmittedZipEntry(entry: ZipEntry, physical: ZipDirectoryEntry): void;
-export declare function zipEntryIntegrityMetadata(entry: ZipEntry): {
-    crc32?: number;
-    uncompressedSize?: number;
-} | undefined;
-export declare function isZipSymlinkEntry(entry: ZipEntry): boolean;
-export declare function zipEntryKind(entry: ZipEntry): ArchiveEntryKind;
-export declare function zipEntryMode(entry: ZipEntry, policy: ArchiveEntryModePolicy | undefined): number;
-export declare function zipEntryDeclaredSize(entry: ZipEntry): number;
+export type AdmittedZipEntry = Readonly<{
+    entry: ZipEntry;
+    name: string;
+    kind: ArchiveEntryKind;
+    mode: number | undefined;
+    size: number;
+    crc32: number;
+}>;
+/** Internal: create only after the complete decoder/admission association. */
+export declare function createAdmittedZipEntry(entry: ZipEntry, name: string, physical: ZipDirectoryEntry): AdmittedZipEntry;

package/node_modules/@openclaw/fs-safe/dist/archive-zip-entry.js

@@ -1,42 +1,10 @@
-import { resolveArchiveEntryMode, } from "./archive-plan.js";
-const admittedMetadata = new WeakMap();
-/** Internal: register only after the complete decoder/admission association. */
-export function registerAdmittedZipEntry(entry, physical) {
+/** Internal: create only after the complete decoder/admission association. */
+export function createAdmittedZipEntry(entry, name, physical) {
     const mode = physical.creatorSystem === 3 ? physical.externalAttributes >>> 16 : undefined;
-    admittedMetadata.set(entry, { kind: physical.kind, mode, size: physical.size });
     entry.dir = physical.kind === "directory";
     // Previously unsupported non-UNIX symlinks must also be recognizable to
     // public preflight consumers using JSZip's conventional type inspection.
     entry.unixPermissions = mode ?? (physical.kind === "symlink" ? 0o120000 : null);
     entry.dosPermissions = physical.creatorSystem === 0 ? physical.externalAttributes & 0x3f : null;
-}
-export function zipEntryIntegrityMetadata(entry) {
-    const data = entry._data;
-    if (!data || "then" in data)
-        return undefined;
-    return data;
-}
-const ZIP_UNIX_FILE_TYPE_MASK = 0o170000;
-const ZIP_UNIX_SYMLINK_TYPE = 0o120000;
-export function isZipSymlinkEntry(entry) {
-    return zipEntryKind(entry) === "symlink";
-}
-export function zipEntryKind(entry) {
-    const metadata = admittedMetadata.get(entry);
-    if (metadata)
-        return metadata.kind;
-    return typeof entry.unixPermissions === "number" &&
-        (entry.unixPermissions & ZIP_UNIX_FILE_TYPE_MASK) === ZIP_UNIX_SYMLINK_TYPE
-        ? "symlink" : entry.dir ? "directory" : "file";
-}
-export function zipEntryMode(entry, policy) {
-    const metadata = admittedMetadata.get(entry);
-    return resolveArchiveEntryMode({
-        kind: entry.dir ? "directory" : "file",
-        archivedMode: metadata ? metadata.mode : entry.unixPermissions,
-        policy,
-    });
-}
-export function zipEntryDeclaredSize(entry) {
-    return admittedMetadata.get(entry)?.size ?? Math.max(0, Math.floor(zipEntryIntegrityMetadata(entry)?.uncompressedSize ?? 0));
+    return { entry, name, kind: physical.kind, mode, size: physical.size, crc32: physical.crc32 };
 }

package/node_modules/@openclaw/fs-safe/dist/archive-zip-integrity.d.ts

@@ -1,4 +1,4 @@
 import { Transform } from "node:stream";
-import { type ZipEntry } from "./archive-zip-entry.js";
+import type { AdmittedZipEntry } from "./archive-zip-entry.js";
 export declare function normalizeZipIntegrityError(error: unknown): Error;
-export declare function createZipIntegrityTransform(entry: ZipEntry): Transform;
+export declare function createZipIntegrityTransform(record: AdmittedZipEntry): Transform;

package/node_modules/@openclaw/fs-safe/dist/archive-zip-integrity.js

@@ -1,6 +1,5 @@
 import { Transform } from "node:stream";
 import { ArchiveFormatError } from "./archive-errors.js";
-import { zipEntryIntegrityMetadata, } from "./archive-zip-entry.js";
 import { updateCrc32 } from "./archive-crc32.js";
 export function normalizeZipIntegrityError(error) {
     if (error instanceof Error &&
@@ -9,17 +8,8 @@ export function normalizeZipIntegrityError(error) {
     }
     return error instanceof Error ? error : new Error(String(error));
 }
-export function createZipIntegrityTransform(entry) {
-    const metadata = zipEntryIntegrityMetadata(entry);
-    const expectedCrc32 = metadata?.crc32;
-    const expectedSize = metadata?.uncompressedSize;
-    if (typeof expectedCrc32 !== "number" ||
-        !Number.isInteger(expectedCrc32) ||
-        typeof expectedSize !== "number" ||
-        !Number.isSafeInteger(expectedSize) ||
-        expectedSize < 0) {
-        throw new ArchiveFormatError(`zip entry has invalid integrity metadata: ${entry.name}`);
-    }
+export function createZipIntegrityTransform(record) {
+    const { entry, crc32: expectedCrc32, size: expectedSize } = record;
     let actualCrc32 = 0;
     let actualSize = 0;
     return new Transform({

package/node_modules/@openclaw/fs-safe/dist/archive-zip-loader.d.ts

@@ -1,8 +1,12 @@
 import type { ZipDirectoryEntry } from "./archive-zip-directory.js";
-import { type ZipEntry } from "./archive-zip-entry.js";
+import { type AdmittedZipEntry } from "./archive-zip-entry.js";
 export type ZipArchiveWithFiles = {
     files: Record<string, unknown>;
 };
-export declare function admittedZipEntries(archive: ZipArchiveWithFiles): readonly ZipEntry[];
+export type ZipArchiveAdmission = {
+    archive: ZipArchiveWithFiles;
+    entries: ReadonlyMap<string, AdmittedZipEntry>;
+};
+export declare function assertZipEntryBinding(archive: ZipArchiveWithFiles, record: AdmittedZipEntry, path: string): void;
 /** Internal: the caller has admitted these unchanged bytes and their metadata. */
-export declare function loadAdmittedZipArchive(buffer: Buffer | Uint8Array, admitted: ZipDirectoryEntry[]): Promise<ZipArchiveWithFiles>;
+export declare function loadAdmittedZipArchive(buffer: Buffer | Uint8Array, admitted: ZipDirectoryEntry[]): Promise<ZipArchiveAdmission>;

package/node_modules/@openclaw/fs-safe/dist/archive-zip-loader.js

@@ -1,10 +1,13 @@
 import { ArchiveFormatError, ArchiveSecurityError } from "./archive-errors.js";
-import { validateArchiveEntryPath } from "./archive-entry.js";
-import { registerAdmittedZipEntry } from "./archive-zip-entry.js";
+import { createArchiveOutputPathTracker, validateArchiveEntryPath } from "./archive-entry.js";
+import { createAdmittedZipEntry } from "./archive-zip-entry.js";
 import { zipPathKey } from "./archive-zip-names.js";
-const orderedEntries = new WeakMap();
-export function admittedZipEntries(archive) {
-    return orderedEntries.get(archive) ?? disagreement();
+export function assertZipEntryBinding(archive, record, path) {
+    const { entry } = record;
+    const name = entry.name;
+    validateArchiveEntryPath(name, { escapeLabel: "archive root" });
+    if (archive.files[record.name] !== entry || zipPathKey(name) !== path)
+        disagreement();
 }
 function disagreement() {
     throw new ArchiveFormatError("ZIP decoder disagrees with admitted directory metadata");
@@ -24,7 +27,9 @@ function matchesData(value, physical) {
 /** Internal: the caller has admitted these unchanged bytes and their metadata. */
 export async function loadAdmittedZipArchive(buffer, admitted) {
     const physicalByPath = new Map();
+    const trackOutputPath = createArchiveOutputPathTracker();
     for (const entry of admitted) {
+        trackOutputPath(entry.portableKey, entry.portableKey);
         if (physicalByPath.has(entry.portableKey))
             collision();
         physicalByPath.set(entry.portableKey, entry);
@@ -110,7 +115,7 @@ export async function loadAdmittedZipArchive(buffer, admitted) {
     if (remaining.size || inserted.size)
         disagreement();
     const files = Object.create(null);
-    const entries = [];
+    const entries = new Map();
     for (const [name, entry, physical] of normalized) {
         const appendSlash = physical.kind === "directory" && !name.endsWith("/");
         const normalizedName = appendSlash ? `${name}/` : name;
@@ -120,12 +125,10 @@ export async function loadAdmittedZipArchive(buffer, admitted) {
             entry.name = `${entry.name}/`;
         }
         files[normalizedName] = entry;
-        registerAdmittedZipEntry(entry, physical);
-        entries.push(entry);
+        entries.set(physical.portableKey, createAdmittedZipEntry(entry, normalizedName, physical));
     }
     archive.files = files;
-    orderedEntries.set(archive, entries);
-    return archive;
+    return { archive, entries };
 }
 async function importOptionalJsZip() {
     try {

package/node_modules/@openclaw/fs-safe/dist/archive-zip-manifest.js

@@ -1,10 +1,11 @@
 import { ArchiveFormatError, ArchiveSecurityError } from "./archive-errors.js";
-import { stripArchivePath } from "./archive-entry.js";
+import { createArchiveOutputPathTracker, stripArchivePath } from "./archive-entry.js";
 /** Associate all native entries with physical admission before exposing any. */
 export function validateNativeZipManifest(manifest, admitted) {
     if (manifest.length !== admitted.length) {
         throw new ArchiveSecurityError("entry-path", "zip decoder collapsed entry names");
     }
+    const trackOutputPath = createArchiveOutputPathTracker();
     for (const [ordinal, entry] of manifest.entries()) {
         const physical = admitted[ordinal];
         const physicalPath = physical?.path;
@@ -18,5 +19,6 @@ export function validateNativeZipManifest(manifest, admitted) {
             (physical.creatorSystem === 3 && entry.mode !== physical.externalAttributes >>> 16)) {
             throw new ArchiveFormatError("ZIP decoder disagrees with admitted directory metadata");
         }
+        trackOutputPath(entry.path, entry.path);
     }
 }

package/node_modules/@openclaw/fs-safe/dist/archive-zip-preflight.d.ts

@@ -1,5 +1,4 @@
 import { type ArchiveExtractLimits } from "./archive-limits.js";
-import { type ZipArchiveWithFiles } from "./archive-zip-loader.js";
-export { readZipCentralDirectoryEntryCount } from "./archive-zip-count.js";
-export type { ZipArchiveWithFiles } from "./archive-zip-loader.js";
+import { type ZipArchiveAdmission, type ZipArchiveWithFiles } from "./archive-zip-loader.js";
+export declare function loadZipArchiveWithAdmission(buffer: Buffer | Uint8Array, limits?: ArchiveExtractLimits): Promise<ZipArchiveAdmission>;
 export declare function loadZipArchiveWithPreflight(buffer: Buffer | Uint8Array, limits?: ArchiveExtractLimits): Promise<ZipArchiveWithFiles>;

package/node_modules/@openclaw/fs-safe/dist/archive-zip-preflight.js

@@ -1,13 +1,21 @@
 import { ARCHIVE_LIMIT_ERROR_CODE, ArchiveLimitError, resolveExtractLimits, } from "./archive-limits.js";
 import { admitZipBuffer } from "./archive-zip-admission.js";
 import { loadAdmittedZipArchive } from "./archive-zip-loader.js";
-export { readZipCentralDirectoryEntryCount } from "./archive-zip-count.js";
-export async function loadZipArchiveWithPreflight(buffer, limits) {
-    const resolvedLimits = resolveExtractLimits(limits);
-    if (buffer.byteLength > resolvedLimits.maxArchiveBytes) {
-        throw new ArchiveLimitError(ARCHIVE_LIMIT_ERROR_CODE.ARCHIVE_SIZE_EXCEEDS_LIMIT);
+export function loadZipArchiveWithAdmission(buffer, limits) {
+    try {
+        const resolvedLimits = resolveExtractLimits(limits);
+        if (buffer.byteLength > resolvedLimits.maxArchiveBytes) {
+            throw new ArchiveLimitError(ARCHIVE_LIMIT_ERROR_CODE.ARCHIVE_SIZE_EXCEEDS_LIMIT);
+        }
+        const entries = [];
+        admitZipBuffer(buffer, resolvedLimits, entry => { entries.push(entry); });
+        return loadAdmittedZipArchive(buffer, entries);
+    }
+    catch (error) {
+        // Keep validation failures in the promise handed to the extraction deadline.
+        return Promise.reject(error);
     }
-    const entries = [];
-    admitZipBuffer(buffer, resolvedLimits, entry => { entries.push(entry); });
-    return await loadAdmittedZipArchive(buffer, entries);
+}
+export async function loadZipArchiveWithPreflight(buffer, limits) {
+    return (await loadZipArchiveWithAdmission(buffer, limits)).archive;
 }

package/node_modules/@openclaw/fs-safe/dist/archive.d.ts

@@ -6,10 +6,13 @@ export { resolveArchiveKind, resolvePackedRootDir, type ArchiveKind } from "./ar
 export { readArchiveEntry } from "./archive-read.js";
 export { ARCHIVE_LIMIT_ERROR_CODE, ArchiveLimitError, DEFAULT_MAX_ARCHIVE_BYTES_ZIP, DEFAULT_MAX_ENTRIES, DEFAULT_MAX_EXTRACTED_BYTES, DEFAULT_MAX_ENTRY_BYTES, DEFAULT_MAX_META_ENTRY_BYTES, DEFAULT_MAX_ENTRY_PATH_COMPONENTS, type ArchiveExtractLimits, type ArchiveLimitErrorCode, } from "./archive-limits.js";
 export { ArchiveFormatError, type ArchiveFormatErrorCode } from "./archive-errors.js";
-export { ArchiveSecurityError, type ArchiveSecurityErrorCode } from "./archive-staging.js";
-export { createArchiveSymlinkTraversalError, mergeExtractedTreeIntoDestination, prepareArchiveDestinationDir, prepareArchiveOutputPath, withStagedArchiveDestination, } from "./archive-staging.js";
+export { ArchiveSecurityError, type ArchiveSecurityErrorCode } from "./archive-errors.js";
+export { createArchiveSymlinkTraversalError, prepareArchiveDestinationDir, prepareArchiveOutputPath, withStagedArchiveDestination, } from "./archive-staging.js";
+export { mergeExtractedTreeIntoDestination } from "./archive-merge.js";
 export { createTarEntryPreflightChecker, type TarEntryInfo } from "./archive-plan.js";
-export { loadZipArchiveWithPreflight, readZipCentralDirectoryEntryCount, type ZipArchiveWithFiles, } from "./archive-zip-preflight.js";
+export { loadZipArchiveWithPreflight } from "./archive-zip-preflight.js";
+export { readZipCentralDirectoryEntryCount } from "./archive-zip-count.js";
+export type { ZipArchiveWithFiles } from "./archive-zip-loader.js";
 export declare function extractArchive(params: ExtractArchiveOptions): Promise<void>;
 export type InspectTarArchiveOptions = Pick<ExtractArchiveOptions, "archivePath" | "timeoutMs" | "limits" | "entryFilter" | "onFiltered">;
 export type InspectedTarEntry = Readonly<Pick<ArchivePlanEntry, "path" | "kind" | "size">>;