@openclaw/fs-safe 0.19.0 → 0.21.0

package/CHANGELOG.md

@@ -2,6 +2,56 @@
 
 ## Unreleased
 
+## 0.21.0 - 2026-09-26
+
+### Highlights
+
+- **Guarded filesystem observation:** `@openclaw/fs-safe/watch` observes literal entry and tree scopes beneath an admitted Root and delivers bounded advisory invalidations; guarded scans stay authoritative. One shared Rust event thread per process uses inotify, FSEvents and ReadDirectoryChangesW on Linux, macOS and Windows, sleeps while idle, and falls back to portable polling under `mode: "auto"`. Subscriptions become ready after one baseline scan, stay available under sustained writes, fence stale generations on `setScopes()`, join native work on `close()`, and support `persistent: false` so one-shot Node commands can exit. Thanks @vincentkoc. ([#690](https://github.com/openclaw/fs-safe/pull/690), [#695](https://github.com/openclaw/fs-safe/pull/695), [#697](https://github.com/openclaw/fs-safe/pull/697), [#703](https://github.com/openclaw/fs-safe/pull/703), [#707](https://github.com/openclaw/fs-safe/pull/707))
+- **Linux user namespaces:** private temp workspaces now work beneath unmapped ancestors, including systemd user services with `PrivateUsers=true`, while UID/GID mappings and ancestor permissions are still rechecked. ([#693](https://github.com/openclaw/fs-safe/pull/693))
+
+### Features
+
+- **Revocable atomic writes:** atomic replacement can recheck caller authority before new effects and report retained destination identities for partial writes and publication, without treating receipts as permission to roll back. ([#694](https://github.com/openclaw/fs-safe/pull/694))
+- **Root walking:** `symlinkPolicy: "include"` reports links without following their targets, preserving sorted traversal, entry budgets, and the existing skip/follow result types. Directory-to-symlink substitutions fail before descent. ([#692](https://github.com/openclaw/fs-safe/pull/692))
+- **Windows file retirement:** the advanced surface can retire existing NTFS files through a retained handle, with exact producer identity, current authority, and separate disposition and settlement facts. There is no persistence guarantee. ([#706](https://github.com/openclaw/fs-safe/pull/706))
+
+### Performance
+
+- **Temporary filename sanitization:** skip duplicate normalization after reserved-device suffixing while preserving filename admission and fallback rules. ([#689](https://github.com/openclaw/fs-safe/pull/689))
+
+### Compatibility
+
+- Supplied temp workspace roots must be owned by the effective user and must not be group- or world-writable; use a private per-user root instead of shared `/tmp`. A one-time warning reports host ownership that cannot be verified. ([#693](https://github.com/openclaw/fs-safe/pull/693))
+- On Windows, an events-mode watch holds one handle on each watched Root, so the Root's own ancestor directories cannot be renamed while it is open; renaming inside the Root is unaffected. Use `mode: "poll"` where that matters. ([#697](https://github.com/openclaw/fs-safe/pull/697))
+- `watch()` requires an explicit `mode` (`"auto"`, `"events"` or `"poll"`); `"events"` fails readiness with `helper-unavailable` when no native backend is available, and Bun currently selects polling under `"auto"`. ([#690](https://github.com/openclaw/fs-safe/pull/690))
+
+## 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

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
 
@@ -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/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";
@@ -35,3 +37,5 @@ export { buildRandomTempFilePath, sanitizeTempFileName, type TempFile, tempFile,
 export { writeSiblingTempFile, writeViaSiblingTempPath, type WriteSiblingTempFileOptions, type WriteSiblingTempFileResult, } from "./sibling-temp.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/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";
@@ -36,3 +37,4 @@ export { appendRegularFile, appendRegularFileSync, readRegularFile, readRegularF
 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-windows.js";
+export { retainFileInDirectory } from "./retained-file.js";

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-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/atomic.d.ts

@@ -1,4 +1,4 @@
-export { replaceFileAtomic, replaceFileAtomicSync, type ReplaceFileAtomicFileSystem, type ReplaceFileAtomicOptions, type ReplaceFileAtomicResult, type ReplaceFileAtomicSyncFileSystem, type ReplaceFileAtomicSyncOptions, } from "./replace-file.js";
+export { replaceFileAtomic, replaceFileAtomicSync, type ReplaceFileAtomicFileSystem, type ReplaceFileAtomicOptions, type ReplaceFileAtomicResult, type ReplaceFileAtomicDestinationState, type ReplaceFileAtomicSyncFileSystem, type ReplaceFileAtomicSyncOptions, } from "./replace-file.js";
 export type { RenameIdentityPolicy } from "./pinned-write-types.js";
 export type { ReplaceFileAtomicRestoreCleanup, ReplaceFileAtomicRestoreFailureDetails, ReplaceFileCopyFallbackRestorePolicy, ReplaceFileDestinationHardlinkPolicy, } from "./replace-file-copy-fallback.js";
 export { writeTextAtomic, type WriteTextAtomicOptions } from "./text-atomic.js";

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 {};