@openclaw/fs-safe 0.18.2 → 0.20.0

package/CHANGELOG.md

@@ -2,6 +2,53 @@
 
 ## Unreleased
 
+## 0.20.0 - 2026-09-25
+
+### Highlights
+
+- **Older Linux systems:** when `openat2` is absent (Linux before 5.6) or blocked by seccomp, native operations fall back to a guarded no-follow walk instead of failing with `ENOSYS`. Nested no-clobber moves keep working, and GNU x64/arm64 bindings now target glibc 2.28, so native operations load on RHEL 8-family systems. ([#686](https://github.com/openclaw/fs-safe/pull/686), [#685](https://github.com/openclaw/fs-safe/pull/685); fixes [#572](https://github.com/openclaw/fs-safe/issues/572), [#511](https://github.com/openclaw/fs-safe/issues/511), [#548](https://github.com/openclaw/fs-safe/issues/548))
+- **Path hardening:** trash moves stay inside allowed roots, symlink-parent checks inspect raw segments before dotdot normalization, relative-escape checks recognize either Windows separator and nested escapes, and safe path segments reject Windows reserved device names. Thanks @SebTardif. ([#611](https://github.com/openclaw/fs-safe/pull/611), [#615](https://github.com/openclaw/fs-safe/pull/615), [#614](https://github.com/openclaw/fs-safe/pull/614), [#612](https://github.com/openclaw/fs-safe/pull/612))
+- **ZIP admission per operation:** portable ZIP reads and extraction bind entry selection to the admitted archive, name, and decoder object, and verify payloads against the admitted CRC and size. Substituted, renamed, or replaced decoder entries are rejected. ([#660](https://github.com/openclaw/fs-safe/pull/660))
+
+### Features
+
+- **Retained symlink publication:** `retainSymlinkInDirectory()` on the advanced surface holds an explicitly identified POSIX symlink through exact-slot no-replace publication and explicit recovery, preserving observed foreign replacements and uncertain outcomes. ([#682](https://github.com/openclaw/fs-safe/pull/682))
+- **Batched Windows ACL facts:** `readOwnerAndDaclBatch()` inspects ordered paths in one isolated native worker or one PowerShell process, with a configurable whole-batch timeout and bounded output. Results are bounded during collection; oversized batches reject with `too-large` before later paths are queried. ([#669](https://github.com/openclaw/fs-safe/pull/669), [#680](https://github.com/openclaw/fs-safe/pull/680))
+- **Atomic text options:** `writeTextAtomic()` forwards the existing `beforeRename` hook and `tempPrefix` option to atomic replacement, keeping its validation and identity checks. ([#580](https://github.com/openclaw/fs-safe/pull/580))
+
+### Fixes
+
+- **Lock exit cleanup:** leave raw sidecars in place when Windows reports an unknown device or inode, while keeping token-owned cleanup working when the descriptor and path identities legitimately differ (for example on VirtioFS). Thanks @SebTardif. ([#617](https://github.com/openclaw/fs-safe/pull/617))
+- **Retained symlink errors:** preserve uncertain publication outcomes and cached cleanup/recovery failures when inspecting thrown error metadata fails, retaining the original cause without retrying mutations, callbacks, or descriptor closes. ([#684](https://github.com/openclaw/fs-safe/pull/684))
+- **Create collision cleanup:** atomic and streamed creates remove their private stage when the JavaScript fallback observes a competing destination before publication; failures after a link attempt retain their existing recovery evidence. ([#683](https://github.com/openclaw/fs-safe/pull/683))
+
+### Compatibility
+
+- Safe path segments now reject Windows reserved device names (`CON`, `NUL`, `COM1`, `CON.json`, …) on every platform, because segments are portable identifiers. Temporary filename sanitization still suffixes them (`CON.txt` becomes `CON_.txt`). ([#612](https://github.com/openclaw/fs-safe/pull/612))
+- `assertNoSymlinkParents()` and guarded appends with `rejectSymlinkParents` reject raw spellings whose dotdot segments would cancel a symlink or re-enter the root after leaving it. ([#615](https://github.com/openclaw/fs-safe/pull/615))
+- Without `openat2`, beneath opens report `best-effort` containment instead of `kernel-atomic`, anonymous `O_TMPFILE` opens report `ENOTSUP`, and bounded tree cleanup fails closed with `helper-unavailable` because it requires `RESOLVE_NO_XDEV`. ([#686](https://github.com/openclaw/fs-safe/pull/686))
+- The Linux GNU binding floor is glibc 2.28 for both x64 and arm64 (arm64 was previously built against 2.17), matching Node 22's own Linux baseline. ([#685](https://github.com/openclaw/fs-safe/pull/685))
+
+## 0.19.0 - 2026-09-24
+
+### Highlights
+
+- **Strict secret-file durability:** `createSecretFileAtomic()` accepts `durable: "file"` to require every file flush to succeed, including on `EPERM`; parent-directory synchronization remains best effort. ([#644](https://github.com/openclaw/fs-safe/pull/644))
+- **Literal `~` names:** keep FileStore keys, absolute Root reads, discovered walk entries, and ZIP/TAR entries literal instead of treating them as home-directory shorthand. Reads, writes, removal, pruning, extraction, and durable publication select the intended entry. ([#633](https://github.com/openclaw/fs-safe/pull/633))
+- **Native Unix descriptor safety:** reject negative descriptors in low-level root, query, hash, copy, clone, staging, and cleanup calls without Rust panics or working-directory operations. Modern macOS beneath opens report `EBADF` for negative roots instead of `EIO`. ([#640](https://github.com/openclaw/fs-safe/pull/640), [#643](https://github.com/openclaw/fs-safe/pull/643), [#646](https://github.com/openclaw/fs-safe/pull/646))
+
+### Fixes
+
+- **Guest directory permissions:** cross-device moves preserve mode `000`, including nested directories, without changing other modes' umask behavior. Restore top-level permissions through the retained directory descriptor and preserve published entries on failure. Thanks @SebTardif. ([#616](https://github.com/openclaw/fs-safe/pull/616))
+- **ReFS clone cleanup:** remove ordinary partial output when Windows rejects the ignore-readonly deletion flag. Keep readonly attributes intact and include cleanup failures in the original clone error; readonly files or other processes' open handles can still leave output behind. ([#648](https://github.com/openclaw/fs-safe/pull/648))
+
+### Compatibility and documentation
+
+- Secret creation's default and boolean durability options retain their behavior, and `writeSecretFileAtomic()` remains boolean-only. Strict file synchronization preserves existing publication and cleanup semantics: a failure after publication can leave a complete file present. ([#644](https://github.com/openclaw/fs-safe/pull/644))
+- `Root.walk("~")` and `Root.walk("~/dir")` expand home shorthand when iteration starts and return admitted canonical paths relative to the Root. Use `./~/dir` for a literal tilde directory, and prefix returned entry paths with `./` when passing them to another Root method. Relative Root `~/name` inputs still expand home; FileStore keys do not. ([#633](https://github.com/openclaw/fs-safe/pull/633))
+- Guest moves still require OS permission to read mode-000 source directories; they do not widen source permissions. If permission restoration fails after publication, the source and published copy remain for caller reconciliation. ([#616](https://github.com/openclaw/fs-safe/pull/616))
+- Clarify that `Root.append()` and `openWritable()` creation modes remain subject to the process umask and do not chmod existing files. This documents existing behavior. ([#636](https://github.com/openclaw/fs-safe/pull/636))
+
 ## 0.18.2 - 2026-09-22
 
 ### Fixes

package/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
 
@@ -342,6 +347,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

package/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";

package/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";

package/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/dist/archive-merge.js

@@ -250,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/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/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/dist/archive-staging.js

@@ -133,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) {

package/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/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/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/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/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/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 { 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");
@@ -110,7 +113,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 +123,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/dist/archive-zip-preflight.d.ts

@@ -1,3 +1,4 @@
 import { type ArchiveExtractLimits } from "./archive-limits.js";
-import { 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/dist/archive-zip-preflight.js

@@ -1,12 +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 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/dist/archive.js

@@ -1,4 +1,4 @@
-import { createTarEntryPlanner, createArchiveEntrySelector, resolveArchiveFilteredEntryPolicy, createArchiveEntryPlanner, } from "./archive-plan.js";
+import { createTarEntryPlanner, createArchiveEntrySelector, resolveArchiveFilteredEntryPolicy, resolveArchiveEntryMode, createArchiveEntryPlanner, } from "./archive-plan.js";
 import { inspectTar, replayTar } from "./archive-tar-stream.js";
 import { runPinnedWriteHelper } from "./pinned-write.js";
 import { constants as fsConstants } from "node:fs";
@@ -11,9 +11,7 @@ import { assertArchiveEntryCountWithinLimit, createByteBudgetTracker, createExtr
 import { resolveArchiveKind } from "./archive-kind.js";
 import { prepareArchiveDestinationGuard, preparePrivateArchiveOutputPath, } from "./archive-staging.js";
 import { withStagedArchivePublication } from "./archive-merge.js";
-import { loadZipArchiveWithPreflight } from "./archive-zip-preflight.js";
-import { admittedZipEntries } from "./archive-zip-loader.js";
-import { zipEntryKind, zipEntryDeclaredSize, zipEntryMode, } from "./archive-zip-entry.js";
+import { loadZipArchiveWithAdmission } from "./archive-zip-preflight.js";
 import { createZipIntegrityTransform, normalizeZipIntegrityError, } from "./archive-zip-integrity.js";
 import { ArchiveSecurityError, ArchiveFormatError, isArchiveFormatErrorMessage, } from "./archive-errors.js";
 import { stageArchiveFileForExtraction } from "./archive-input.js";
@@ -51,7 +49,7 @@ async function readZipEntryStream(entry) {
 async function writeZipFileEntry(params) {
     params.deadline.check();
     params.budget.startEntry();
-    const readable = await readZipEntryStream(params.entry);
+    const readable = await readZipEntryStream(params.record.entry);
     const destinationPath = params.outPath;
     let tempHandle = null;
     let handleClosedByStream = false;
@@ -69,7 +67,7 @@ async function writeZipFileEntry(params) {
                     handleClosedByStream = true;
                 });
                 try {
-                    await pipeline(readable, createExtractBudgetTransform({ onChunkBytes: params.budget.addBytes }), createZipIntegrityTransform(params.entry), writable, { signal: params.deadline.signal });
+                    await pipeline(readable, createExtractBudgetTransform({ onChunkBytes: params.budget.addBytes }), createZipIntegrityTransform(params.record), writable, { signal: params.deadline.signal });
                 }
                 catch (err) {
                     throw normalizeZipIntegrityError(createPipelineTimeoutError(err, params.deadline));
@@ -103,26 +101,29 @@ async function extractZip(params) {
     deadline.check();
     const buffer = await fs.readFile(params.archivePath, { signal: deadline.signal });
     deadline.check();
-    const zip = await waitForDeadline(loadZipArchiveWithPreflight(buffer, limits), deadline);
+    const { entries } = await waitForDeadline(loadZipArchiveWithAdmission(buffer, limits), deadline);
     deadline.check();
-    const entries = admittedZipEntries(zip);
-    assertArchiveEntryCountWithinLimit(entries.length, limits);
+    assertArchiveEntryCountWithinLimit(entries.size, limits);
     const budget = createByteBudgetTracker(limits);
     await withStagedArchivePublication({ ...params, destinationGuard }, async (stagingDir) => {
         const { select } = createArchiveEntrySelector({ ...params, rootDir: stagingDir });
         const acceptedEntries = [];
-        for (const entry of entries) {
+        for (const record of entries.values()) {
             deadline.check();
-            const entryKind = zipEntryKind(entry);
-            const relPath = select({ path: entry.name, kind: entryKind, size: zipEntryDeclaredSize(entry) });
+            const { entry, kind: entryKind, size, mode: archivedMode } = record;
+            const relPath = select({ path: record.name, kind: entryKind, size });
             if (relPath === null)
                 continue;
             if (entryKind === "symlink") {
-                throw new ArchiveSecurityError("entry-link", `zip entry is a link: ${entry.name}`);
+                throw new ArchiveSecurityError("entry-link", `zip entry is a link: ${record.name}`);
             }
             if (entryKind === "other")
                 continue;
-            const mode = zipEntryMode(entry, params.entryModes);
+            const mode = resolveArchiveEntryMode({
+                kind: entry.dir ? "directory" : "file",
+                archivedMode,
+                policy: params.entryModes,
+            });
             acceptedEntries.push({ path: relPath, kind: entry.dir ? "directory" : "file", mode });
             const outPath = path.join(stagingDir, relPath);
             await preparePrivateArchiveOutputPath({
@@ -130,12 +131,12 @@ async function extractZip(params) {
                 destinationRealDir: stagingDir,
                 relPath,
                 outPath,
-                originalPath: entry.name,
+                originalPath: record.name,
                 isDirectory: entry.dir,
                 deadline,
             });
             if (!entry.dir) {
-                await writeZipFileEntry({ entry, outPath, budget, deadline });
+                await writeZipFileEntry({ record, outPath, budget, deadline });
             }
         }
         return acceptedEntries;

package/dist/directory-receipt.js

@@ -70,11 +70,6 @@ function snapshotDirectoryMetadata(stat, identity) {
 export function directoryReceiptAuthority(receipt) {
     return authorities.get(receipt) ?? snapshotDirectoryReceipt(receipt);
 }
-function rememberReceipt(receipt, authority) {
-    authorities.set(receipt, authority);
-    identities.set(receipt.identity, authority);
-    return receipt;
-}
 export function ownDirectoryReceipt(receipt) {
     return receiptFromAuthority(snapshotDirectoryReceipt(receipt));
 }
@@ -83,11 +78,14 @@ export function copyRetainedDirectoryReceipt(receipt) {
     return receiptFromAuthority(authority);
 }
 function receiptFromAuthority(authority) {
-    return rememberReceipt({
+    const receipt = {
         path: authority.path,
         realPath: authority.realPath,
         identity: Object.assign(Object.create(fs.Stats.prototype), authority.metadata),
-    }, authority);
+    };
+    authorities.set(receipt, authority);
+    identities.set(receipt.identity, authority);
+    return receipt;
 }
 // The caller already admitted the exact observation and its paths.
 export function createDirectoryReceiptFromIdentity(pathname, realPath, exactStat) {

package/dist/effective-uid.js

@@ -1,6 +1,3 @@
-function isValidUid(value) {
-    return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
-}
 function unavailable(cause) {
     return new Error("Effective user identity is unavailable.", {
         ...(cause === undefined ? {} : { cause }),
@@ -18,7 +15,7 @@ export function resolveEffectiveUid() {
     catch (cause) {
         throw unavailable(cause);
     }
-    if (!isValidUid(uid)) {
+    if (!(typeof uid === "number" && Number.isSafeInteger(uid) && uid >= 0)) {
         throw unavailable();
     }
     return uid;

package/dist/errors.d.ts

@@ -1,6 +1,7 @@
-export type FsSafeErrorCode = "already-exists" | "denied-path" | "device-path" | "hardlink" | "helper-failed" | "helper-unavailable" | "invalid-path" | "insecure-permissions" | "not-empty" | "not-file" | "not-found" | "not-owned" | "not-removable" | "outside-workspace" | "path-alias" | "path-mismatch" | "permission-unverified" | "read-failed" | "secret-exists" | "store-reentrant-update" | "symlink" | "timeout" | "too-large" | "unsupported-platform";
+export type FsSafeErrorCode = (typeof OPERATIONAL_CODE_VALUES)[number] | "already-exists" | "denied-path" | "device-path" | "hardlink" | "invalid-path" | "insecure-permissions" | "not-file" | "not-owned" | "outside-workspace" | "path-alias" | "path-mismatch" | "secret-exists" | "store-reentrant-update" | "symlink" | "too-large";
 export type FsSafeErrorCategory = "policy" | "operational";
 export type FsSafeErrorDetails = Readonly<Record<string, unknown>>;
+declare const OPERATIONAL_CODE_VALUES: readonly ["helper-failed", "helper-unavailable", "not-empty", "not-found", "not-removable", "permission-unverified", "read-failed", "timeout", "unsupported-platform"];
 export declare function categorizeFsSafeError(code: FsSafeErrorCode): FsSafeErrorCategory;
 export declare class FsSafeError extends Error {
     readonly code: FsSafeErrorCode;
@@ -11,3 +12,4 @@ export declare class FsSafeError extends Error {
         details?: FsSafeErrorDetails;
     });
 }
+export {};

package/dist/errors.js

@@ -1,4 +1,4 @@
-const OPERATIONAL_CODES = new Set([
+const OPERATIONAL_CODE_VALUES = [
     "helper-failed",
     "helper-unavailable",
     "not-empty",
@@ -8,7 +8,8 @@ const OPERATIONAL_CODES = new Set([
     "read-failed",
     "timeout",
     "unsupported-platform",
-]);
+];
+const OPERATIONAL_CODES = new Set(OPERATIONAL_CODE_VALUES);
 export function categorizeFsSafeError(code) {
     return OPERATIONAL_CODES.has(code) ? "operational" : "policy";
 }