@openclaw/fs-safe 0.14.0 → 0.16.0

package/CHANGELOG.md

@@ -1,5 +1,93 @@
 # Changelog
 
+## Unreleased
+
+## 0.16.0 - 2026-09-19
+
+### Highlights
+
+- **Private files and directories through existing APIs:** add `private: true` to Root `mkdir()`, `ensureRoot()`, `create()`, and `createJson()`, with verified owner-only permissions and creation-time Windows ACL protection. New `/advanced` helpers `createDirectory()`, `createDirectorySync()`, and `createFileSync()` create one exclusive entry under an existing trusted parent; the file helper returns an owned, disposable descriptor. ([#487](https://github.com/openclaw/fs-safe/pull/487), [#482](https://github.com/openclaw/fs-safe/issues/482))
+- **Safer secret and private writes:** verify the actual staging permissions before writing content, rejecting filesystems that accept permission changes without enforcing the required private mode. ([#491](https://github.com/openclaw/fs-safe/pull/491), [#493](https://github.com/openclaw/fs-safe/pull/493))
+- **Atomic buffered file creation:** opt into `atomic: true` on `Root.create()` or `createJson()` to keep the destination absent until its content is ready, including without the native addon. Independently select `durable: "file"` when file-flush failures must propagate. Existing defaults remain unchanged. ([#486](https://github.com/openclaw/fs-safe/pull/486))
+- **Compressed TAR without native installation:** extract and read bounded entries from zstd and bzip2 TAR archives through bundled WASM codecs, even with all optional dependencies omitted. The fallback retains the shared Rust TAR parser, full-stream validation, byte limits, and guarded publication, with no runtime interpreter or download. ([#488](https://github.com/openclaw/fs-safe/pull/488))
+- **Windows security operations without the addon:** use packaged, readable PowerShell/C# helpers for raw owner/DACL inspection, private-directory creation, and secure-file reads in native `auto` or `off` mode when capabilities are unavailable. Private permissions apply at creation, and secure reads inspect the same open handle that supplies the bytes. ([#476](https://github.com/openclaw/fs-safe/pull/476))
+
+### Compatibility and upgrade notes
+
+- Private creation on macOS requires the matching native helper's ACL-inspection capability; disabled, missing, or older helpers reject before creating parents or stages. Relevant inheritable parent ACLs reject creation, while noninheriting ACLs remain allowed. Existing entries are never repaired or made less restrictive. Nonprivate creation and native-free secret-file writes retain their behavior; see the [creation contract](https://github.com/openclaw/fs-safe/blob/v0.16.0/docs/creation.md) for supported modes and platform limits.
+- Native-free `atomic: true` creation requires hardlinks and rejects unsupported filesystems without publishing partial content. Private Windows file publication also requires hardlinks on the same local filesystem. Streamed creates continue to stage complete content; atomic visibility does not strengthen pathname containment or guarantee crash durability.
+- `durable: "file"` applies to buffered, streamed, and JSON creates and propagates file-sync errors, including `EPERM`. Parent-directory synchronization remains best-effort, independently of the selected publication strategy.
+- Windows fallbacks require system PowerShell and permission to run the packaged scripts and `.NET Add-Type` under normal system policy. They emit a path-free `FS_SAFE_NATIVE_FALLBACK` warning once per capability per process and add startup and compilation overhead; disallowed execution fails closed. No system policy is bypassed.
+- Native `require` remains strict, and failures from available native operations never trigger a fallback retry. No-clobber `Root.move()` still requires native support. ZIP fallback still needs optional `jszip`, and `inspectTarArchive()` continues to accept only plain TAR and gzip.
+- Atomic, streamed, and private creation can report cleanup, close, mode, or synchronization errors after a complete file has been published. Preserve the publication and cleanup receipts when handling failures; completed destinations remain in place, and indeterminate outcomes retain names for recovery.
+
+### Security and correctness
+
+- Verify `0600` before secret-file payload writes in native and JavaScript writers. Verify actual native private-file ownership and permissions before payload writes and at publication, rejecting filesystems that accept permission changes without enforcing them; retain explicit final modes and public staging's `0600` guarantees. ([#491](https://github.com/openclaw/fs-safe/pull/491), [#493](https://github.com/openclaw/fs-safe/pull/493))
+- Compare exact directory identities before and after durability syncs, retry unknown Windows observations once, and reject rounded or unverifiable caller receipts. Bind numeric metadata to the same observation and preserve private identity authority across receipt mutation, durable creation, publication, and retained staging. ([#483](https://github.com/openclaw/fs-safe/pull/483))
+- Retain streamed `Root.create()` authority callbacks and abort signals across producer waits so replacing caller options cannot detach a revoked lease or redirect cancellation; preserve callback receivers and owned-stage cleanup. ([#490](https://github.com/openclaw/fs-safe/pull/490))
+- Recheck retained parent and staging identities after final publication authority callbacks on JavaScript and native writers, preserving substituted entries before their bytes can be published. Flush native Windows creation through the retained writable descriptor and preserve published destinations after finalization failures.
+- Snapshot `Root.move()` mutation policy before asynchronous admission so changes to caller-owned deny paths or prefixes cannot change an in-flight move. Recheck native no-clobber source identity, type, and hardlink policy after the final authority callback; live revocation remains available through `assertBeforeMutation`.
+- Keep asynchronous Root-backed file locks waiting through successive owner handoffs instead of failing with `path-mismatch`, while retaining identity checks and requiring a fresh exclusive acquisition.
+- Return one unsupported clone-metadata result per input without the native addon on non-macOS platforms in `auto` and `off` modes. Preserve input validation, strict `require` mode, and native-only APFS metadata on macOS. ([#489](https://github.com/openclaw/fs-safe/pull/489))
+
+### Diagnostics and maintenance
+
+- Address Windows security commands by their built-in module names and restrict discovery to PowerShell's bundled system modules, avoiding broad discovery scans on helper startup. ([#484](https://github.com/openclaw/fs-safe/pull/484))
+- Clarify that `resolveExistingPathsWithinRoot()` permits missing paths while `resolveStrictExistingPathsWithinRoot()` requires existing regular files, and distinguish native beneath mechanisms from the best-effort containment reported by public Root open, read, and writable-open results. ([#485](https://github.com/openclaw/fs-safe/pull/485))
+- Honor case-insensitive Windows build environment names so configured WASM compilers and archivers remain selected in worker processes; preserve child-only compiler flags without duplicate case variants. ([#492](https://github.com/openclaw/fs-safe/pull/492))
+- Refresh JavaScript and Rust dependencies, pnpm, CodeQL, and archive/release build toolchains, including current NAPI interoperability fixes; retain Node 22 support and Rust 1.88 compatibility. Includes the Dependabot updates in [#481](https://github.com/openclaw/fs-safe/pull/481).
+
+## 0.15.0 - 2026-09-18
+
+### Highlights
+
+- Enforce Root authority throughout synchronous lock admission, stale recovery, and cleanup; keep asynchronous reclaim guards inside the Root capability.
+- Preserve directory and archive-source identity across publication, callbacks, and recovery, and reject corrupt portable ZIP payloads and metadata.
+- Support asynchronous walk filters, configurable-depth suffix probing, and bounded synchronous descriptor copying.
+
+### Compatibility and upgrade notes
+
+- Directory replacement now requires compatible native identity-fenced, no-replace support, including when the destination is absent. Disabled, missing, or older helpers reject before target-parent creation.
+- Treat ordinary post-dispatch native rename errors as indeterminate. Preserve staged files and directory backups when a rename may have committed before its reply was lost; automatic retry and rollback require explicit evidence that dispatch never occurred.
+- Synchronous Root locks require a genuine registered Root handle and enforce its policies. Interrupted asynchronous Root reclaim guards can remain after process exit or reset; recover them only after an application-owned liveness check proves the attempt ended.
+- Root lock authority checks add measurable overhead. Removing redundant observations reduces some cost, but these paths remain slower than the earlier implementation that did not enforce the same boundary.
+
+### Security and correctness
+
+- Serialize sidecar admission across raw and Root-based synchronous callers, retain separate cleanup authority, and recheck asynchronous authorization at the final stale-removal boundary.
+- Keep asynchronous Root reclaim-guard creation, token/byte ownership checks, and removal inside the capability. Preserve unsettled guards instead of following replaced parents through raw cleanup.
+- Create native Root lock records through retained-parent exclusive opens so racing contenders retry normally. Ordinary Root writes retain private staging. Treat raw reclaim guards disappearing or changing during collision inspection as contention.
+- Verify reclaim-guard ownership after the final sidecar snapshot and parser, preserving mutation authorization and parser failures. Evaluate stale age after snapshot parsing and reject cleanup when exact identity is unknown.
+- Retain source-root and child-directory authority during archive merges and bind file identity and mode to the admitted copy descriptor, including exact large Windows identities.
+- Preserve ZIP payloads and physical entry metadata during portable loading so extraction rejects corrupt empty content and honors admitted directory, symlink, and special-file kinds without reordering callbacks.
+- Snapshot FileStore policies before asynchronous work, streams, source reads, and JSON serialization; snapshot JsonStore durability/newline options before queued mutations and updater callbacks.
+- Snapshot external-output and sibling-temp options before asynchronous setup while preserving callback receivers.
+- Enforce Windows native parent mutation policies before creating each missing component and retain originating native descriptor ownership through cleanup.
+- Preserve files and symlinks replacing an observed empty FileStore directory, and leave directories that become nonempty untouched.
+- Recheck child entries before walk descent so symlink replacements during filters honor the selected policy.
+- Keep Windows owner/ACL diagnostics bounded and fail-closed for hostile thrown values. Preserve ordinary diagnostics and the original cause without invoking getters, proxy traps, coercion, or altered buffer properties.
+
+### APIs and failure handling
+
+- Allow asynchronous `include`/`descend` callbacks in `walkDirectory()` and `entryFilter` in `Root.walk()`, retaining serial selection, callback receivers, budgets, cancellation, and post-callback identity checks.
+- Add `maxDepth` to `probePathSuffixAliasesSync()` with proportional budgets, a 32,768-forward-observation ceiling, unchanged defaults and string limits, and complete owned cleanup.
+- Add `copyFileDescriptorSync()` for bounded positional transfers between caller-owned regular-file descriptors, preserving cursors, destination suffixes, descriptor lifetime, and caller-owned durability/publication.
+- Preserve the first tree-copy operation failure, including falsy values and existing codes, while closing each owned resource once. Successful operations retain output-before-input and source-before-parent close-failure precedence.
+- Preserve falsy atomic operation, cleanup, close, restoration, temporary-workspace removal, and Windows native cleanup failures; consume retained handles before close to prevent repeated release.
+- Propagate portable ZIP fallback-close failures before publication and copy-fallback writer close failures after successful unsynchronized writes, including restoration with an absent destination.
+- Preserve synchronous destination-admission failures when best-effort close also fails, and preserve directory-mode authority/deadline failures before and after dispatch.
+
+### Performance and maintenance
+
+- Bound path-prefix queue consumption on long paths while preserving short-path behavior and resolution checks.
+- Reuse eligible Windows parent-creation receipts, equivalent Root identity observations, and guarded regular-file unlink paths while retaining final identity and policy checks.
+- Consolidate native copy ownership, regular/secret read admission, copy-fallback admission, and temporary-workspace setup and settlement; remove redundant wrappers, write-admission storage, and permission-diagnostic work.
+- Bind public copy, ZIP extraction, atomic settlement, and permission benchmarks to verified workload receipts; keep setup, content checks, and cleanup verification outside timing.
+- Update @napi-rs/cli to 3.10.0 and the locked Node type definitions to 26.6.0, and align Vitest/coverage on 5.0.1.
+- Expand security-owner coverage to native/archive code, platform packages, executable benchmarks, and build/test/release configuration.
+- Raise publication and release-proof job ceilings to 90 minutes, retaining bounded registry retries and fail-closed artifact, signature, and provenance checks.
+
 ## 0.14.0 - 2026-09-17
 
 ### Highlights

package/README.md

@@ -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; native zstd/bzip2)** |
+| **`@openclaw/fs-safe`** | **✓** | **✓** | **✓** | **Linux atomic; others best-effort** | **✓ (ZIP/TAR/gzip/zstd/bzip2)** |
 
 ## Not a sandbox
 
@@ -57,7 +57,7 @@ This is a **library-level guardrail**, not OS-level isolation. It does not repla
 pnpm add @openclaw/fs-safe
 ```
 
-Node 22 or newer. Core root/path/json/temp helpers avoid framework dependencies. With all optional dependencies omitted, public subpaths remain safe to import and fallback-capable operations work in `auto` or `off`. Native-only features, including no-clobber `Root.move()`, remain unavailable and fail with `helper-unavailable`. TAR/gzip fallback uses the bundled WASM build of the same Rust parser as native and works with optional dependencies omitted. ZIP fallback still needs optional `jszip`. See the [0.6 migration guide](docs/migrating-to-0.6.md).
+Node 22 or newer. Core root/path/json/temp helpers avoid framework dependencies. With all optional dependencies omitted, public subpaths remain safe to import and fallback-capable operations work in `auto` or `off`. Native-only features, including no-clobber `Root.move()` and [`private: true` creation on macOS](docs/creation.md#permission-options), remain unavailable and fail with `helper-unavailable`. TAR, gzip, zstd, and bzip2 extraction and bounded entry reads use the same Rust TAR parser through bundled WASM when native support is disabled or absent. Zstd/bzip2 codecs are bundled too; gzip uses Node's built-in decoder. ZIP fallback still needs optional `jszip`. See the [0.6 migration guide](docs/migrating-to-0.6.md).
 
 Bun 1.4.2 is also supported with the [Bun runtime requirements](docs/install.md#bun-runtime), including the matching Rust addon on macOS and Linux. JIT-disabled Bun works too.
 
@@ -70,7 +70,7 @@ environment policy:
 import { configureFsSafeNative } from "@openclaw/fs-safe";
 
 configureFsSafeNative({ mode: "auto" });    // default: native when available
-configureFsSafeNative({ mode: "off" });     // guarded JavaScript only
+configureFsSafeNative({ mode: "off" });     // disable the addon; use supported fallbacks
 configureFsSafeNative({ mode: "require" }); // fail closed if the binding is unavailable
 ```
 
@@ -158,6 +158,23 @@ const opened = await fs.open("notes/today.txt");
 await fs.create("notes/README.md", "seed\n"); // throws if it already exists
 ```
 
+Use `private: true` on `mkdir()`, `ensureRoot()`, `create()`, or `createJson()`
+for private creation. On macOS, this requires native ACL inspection before
+creating parents or stages and verifies owner-only permissions with no ACL
+before writing payload bytes. Native `off` or a missing ACL capability rejects
+with `helper-unavailable`; nonprivate creation is unchanged. See the
+[creation contract](docs/creation.md#permission-options) for parent ACL handling
+and platform support.
+
+Pass `{ atomic: true }` to buffered `create()` or `createJson()` to keep the
+destination absent until complete content is ready, including with native support
+disabled. The JavaScript fallback requires hardlinks and never downgrades to a
+partial visible file. Omitted or `false` retains the existing buffered behavior.
+Atomic visibility is separate from the existing `durable` synchronization policy.
+Use `durable: "file"` on `create()` or `createJson()` when file-flush errors,
+including `EPERM`, must propagate. It combines with `atomic: true` without
+requiring strict parent-directory synchronization.
+
 `create()` also accepts an `AsyncIterable<Uint8Array>` for large or incrementally
 produced files. Streamed creates keep the destination absent until all chunks
 are written, support `maxBytes` and `signal`, and recheck mutation authority
@@ -259,8 +276,8 @@ contract. Low-level helpers that OpenClaw needs to compose higher-level APIs are
 | `@openclaw/fs-safe/permissions` | POSIX mode and Windows ACL inspection, raw owner/ACE facts, private-directory creation, and remediation helpers |
 | `@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, native gzip/zstd/bzip2, and bounded entry reads |
-| `@openclaw/fs-safe/advanced` | lower-level composition helpers such as path scopes, root-file open, bounded descriptor reads, [borrowed-handle copying](docs/copy.md#borrowed-filehandle-transfers), [exact directory identity](docs/directory-identity.md), [case probing](docs/path-case.md), [suffix-alias probing](docs/path-suffix-aliases.md), [in-place writes](docs/in-place-write.md), [versioned install-ID encoding](docs/install-path.md#safepathsegmenthashedv2), filename sanitizing, temp-file targets, sibling-temp writes, local-root readers, regular-file helpers, `pathExists`, and `withTimeout`; less stable than focused public subpaths |
+| `@openclaw/fs-safe/archive` | policy-driven ZIP/TAR extraction, clamp/filter policy, metadata/path-depth limits, gzip/zstd/bzip2 support, and bounded entry reads |
+| `@openclaw/fs-safe/advanced` | lower-level composition helpers such as path scopes, root-file open, bounded descriptor reads, [borrowed-handle and descriptor copying](docs/copy.md#borrowed-filehandle-transfers), [exact directory identity](docs/directory-identity.md), [case probing](docs/path-case.md), [suffix-alias probing](docs/path-suffix-aliases.md), [in-place writes](docs/in-place-write.md), [versioned install-ID encoding](docs/install-path.md#safepathsegmenthashedv2), filename sanitizing, temp-file targets, sibling-temp writes, local-root readers, regular-file helpers, `pathExists`, and `withTimeout`; less stable than focused public subpaths |
 | `@openclaw/fs-safe/errors` | `FsSafeError`, closed codes/categories, causes, and operation-specific details receipts |
 | `@openclaw/fs-safe/types` | shared types: `DirEntry`, `PathStat`, … |
 | `@openclaw/fs-safe/test-hooks` | hooks the test suite uses to inject races; registration requires `NODE_ENV=test` or `VITEST=true` |
@@ -466,8 +483,13 @@ instead of a root-relative workspace path. It opens the file first, validates th
 same handle it will read from, checks trusted directories, owner, POSIX mode or
 Windows ACLs, hardlink count, size, and optional timeout, then reads through the
 pinned handle. On Windows, both the bytes and the owner/DACL facts come from that
-handle; secure reads require the matching current native package and do not fall
-back to a pathname ACL command.
+handle. In native `auto` or `off` mode, a packaged, readable PowerShell script can
+inspect that borrowed handle when the native capability is unavailable, subject
+to the [Windows security fallback prerequisites](docs/install.md#windows-security-fallback).
+It emits one fallback warning per process for secure reads and adds PowerShell
+startup and compilation overhead per call. Native `require` remains strict, and
+native operation failures are terminal. Neither route reopens the pathname to
+inspect its ACL.
 
 ```ts
 import { readSecureFile } from "@openclaw/fs-safe/secure-file";
@@ -517,12 +539,18 @@ for (const file of scan.entries) {
 
 Check `scan.truncated` before treating the result as complete, and `scan.failedDirs` to tell an incomplete scan (a directory that could not be read) from an empty one before pruning state from the listing.
 
+`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
 truncation marker (or typed error) when a budget is reached. Its `entryFilter`
-can return `"skip-subtree"` to prune a directory, and
-`onDirectoryError: "skip-and-report"` yields typed `"directory-error"` markers
-while preserving entries from readable subtrees.
+accepts `"include"`, `"skip"`, or `"skip-subtree"`, directly or through a Promise.
+After an awaited decision resolves, the walk rechecks cancellation and the
+current listing directory and Root identities before using it. Pending callbacks
+settle before cancellation or iterator disposal completes. Callback failures
+reject the walk. `onDirectoryError: "skip-and-report"` yields typed `"directory-error"` markers
+for directory read or identity-check failures while preserving entries from
+readable subtrees.
 
 ## Archive extraction
 

package/dist/advanced.d.ts

@@ -1,5 +1,6 @@
 export { createAsyncLock } from "./async-lock.js";
-export { copyFileHandle, type CopyFileHandleOptions } from "./file-handle-transfer.js";
+export { createDirectory, createDirectorySync, createFileSync, type CreateDirectoryOptions, type CreateFileOptions, type OwnedFileDescriptorSync, } from "./create.js";
+export { copyFileHandle, copyFileDescriptorSync, type CopyFileHandleOptions } from "./file-handle-transfer.js";
 export { overwriteFileHandle, type OverwriteFileHandleOptions } from "./overwrite-file-handle.js";
 export { probePathCaseInsensitiveSync, type ProbePathCaseOptions } from "./path-case.js";
 export { resolvePathPrefixSync, type ResolvedPathPrefix } from "./path-prefix.js";

package/dist/advanced.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"advanced.d.ts","sourceRoot":"","sources":["../src/advanced.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,cAAc,EAAE,KAAK,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AACvF,OAAO,EAAE,mBAAmB,EAAE,KAAK,0BAA0B,EAAE,MAAM,4BAA4B,CAAC;AAClG,OAAO,EAAE,4BAA4B,EAAE,KAAK,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AACzF,OAAO,EAAE,qBAAqB,EAAE,KAAK,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAClF,OAAO,EAAE,0BAA0B,EAAE,KAAK,6BAA6B,EAAE,MAAM,0BAA0B,CAAC;AAC1G,OAAO,EACL,qBAAqB,EACrB,2BAA2B,EAC3B,KAAK,iBAAiB,GACvB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,oBAAoB,EACpB,KAAK,UAAU,EACf,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAC1B,KAAK,wBAAwB,EAC7B,KAAK,wBAAwB,GAC9B,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACL,yBAAyB,EACzB,6BAA6B,EAC7B,qBAAqB,GACtB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,mBAAmB,EACnB,uBAAuB,EACvB,KAAK,qBAAqB,GAC3B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,4BAA4B,EAC5B,sBAAsB,EACtB,yBAAyB,EACzB,KAAK,yBAAyB,EAC9B,KAAK,2BAA2B,EAChC,KAAK,0BAA0B,GAChC,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,uBAAuB,EACvB,iCAAiC,EACjC,uBAAuB,EACvB,oBAAoB,EACpB,0BAA0B,EAC1B,2BAA2B,EAC3B,KAAK,yBAAyB,EAC9B,KAAK,8BAA8B,EACnC,KAAK,6BAA6B,EAClC,KAAK,oBAAoB,EACzB,KAAK,4BAA4B,GAClC,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,gBAAgB,EAAE,KAAK,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC7E,OAAO,EAAE,yBAAyB,EAAE,MAAM,eAAe,CAAC;AAC1D,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AACrD,OAAO,EACL,6BAA6B,EAC7B,sBAAsB,EACtB,KAAK,sBAAsB,EAC3B,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EACzB,KAAK,6BAA6B,EAClC,KAAK,oCAAoC,GAC1C,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,0BAA0B,EAC1B,uBAAuB,EACvB,0BAA0B,EAC1B,wBAAwB,EACxB,oBAAoB,EACpB,iBAAiB,EACjB,oBAAoB,GACrB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EACL,oBAAoB,EACpB,mBAAmB,EACnB,KAAK,gBAAgB,GACtB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,2BAA2B,EAC3B,uBAAuB,EACvB,mBAAmB,EACnB,KAAK,eAAe,GACrB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,YAAY,EACZ,gBAAgB,EAChB,kBAAkB,EAClB,wBAAwB,EACxB,KAAK,kBAAkB,EACvB,KAAK,sBAAsB,EAC3B,KAAK,mBAAmB,EACxB,KAAK,yBAAyB,EAC9B,KAAK,kBAAkB,GACxB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,wBAAwB,EACxB,kCAAkC,EAClC,eAAe,EACf,mBAAmB,EACnB,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,GACzB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,yBAAyB,EACzB,SAAS,EACT,8BAA8B,EAC9B,qBAAqB,EACrB,sBAAsB,EACtB,oCAAoC,EACpC,6BAA6B,EAC7B,KAAK,SAAS,EACd,KAAK,gBAAgB,EACrB,KAAK,uBAAuB,GAC7B,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,WAAW,EACX,qBAAqB,EACrB,uBAAuB,EACvB,qBAAqB,EACrB,6BAA6B,GAC9B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,sBAAsB,EACtB,0BAA0B,EAC1B,KAAK,6BAA6B,GACnC,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,eAAe,EAAE,KAAK,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAC1E,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC;AACxD,OAAO,EACL,iBAAiB,EACjB,qBAAqB,EACrB,eAAe,EACf,mBAAmB,EACnB,6BAA6B,EAC7B,eAAe,EACf,mBAAmB,EACnB,KAAK,wBAAwB,EAC7B,KAAK,qBAAqB,GAC3B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,uBAAuB,EACvB,oBAAoB,EACpB,KAAK,QAAQ,EACb,QAAQ,EACR,YAAY,GACb,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,oBAAoB,EACpB,uBAAuB,EACvB,KAAK,2BAA2B,EAChC,KAAK,0BAA0B,GAChC,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,wBAAwB,EACxB,wBAAwB,EACxB,uBAAuB,EACvB,iBAAiB,EACjB,iBAAiB,EACjB,2BAA2B,EAC3B,mBAAmB,EACnB,KAAK,yBAAyB,EAC9B,KAAK,wBAAwB,EAC7B,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,iBAAiB,GACvB,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"advanced.d.ts","sourceRoot":"","sources":["../src/advanced.ts"],"names":[],"mappings":"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"}

package/dist/advanced.js

@@ -2,7 +2,8 @@
 // public subpaths; prefer root/json/store/temp/archive unless you are building a
 // higher-level primitive.
 export { createAsyncLock } from "./async-lock.js";
-export { copyFileHandle } from "./file-handle-transfer.js";
+export { createDirectory, createDirectorySync, createFileSync, } from "./create.js";
+export { copyFileHandle, copyFileDescriptorSync } from "./file-handle-transfer.js";
 export { overwriteFileHandle } from "./overwrite-file-handle.js";
 export { probePathCaseInsensitiveSync } from "./path-case.js";
 export { resolvePathPrefixSync } from "./path-prefix.js";

package/dist/archive-kind.d.ts

@@ -4,6 +4,5 @@ type ResolvePackedRootDirOptions = {
     rootMarkers?: string[];
 };
 export declare function resolvePackedRootDir(extractDir: string, options?: ResolvePackedRootDirOptions): Promise<string>;
-export declare function assertPortableArchiveKind(kind: ArchiveKind): void;
 export {};
 //# sourceMappingURL=archive-kind.d.ts.map

package/dist/archive-kind.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"archive-kind.d.ts","sourceRoot":"","sources":["../src/archive-kind.ts"],"names":[],"mappings":"AAOA,MAAM,MAAM,WAAW,GAAG,KAAK,GAAG,WAAW,GAAG,UAAU,GAAG,KAAK,CAAC;AAmBnE,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAcvE;AAED,KAAK,2BAA2B,GAAG;IACjC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB,CAAC;AAkBF,wBAAsB,oBAAoB,CACxC,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,2BAA2B,GACpC,OAAO,CAAC,MAAM,CAAC,CA4BjB;AAED,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,CAQjE"}
+{"version":3,"file":"archive-kind.d.ts","sourceRoot":"","sources":["../src/archive-kind.ts"],"names":[],"mappings":"AAMA,MAAM,MAAM,WAAW,GAAG,KAAK,GAAG,WAAW,GAAG,UAAU,GAAG,KAAK,CAAC;AAQnE,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAgBvE;AAED,KAAK,2BAA2B,GAAG;IACjC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB,CAAC;AAkBF,wBAAsB,oBAAoB,CACxC,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,2BAA2B,GACpC,OAAO,CAAC,MAAM,CAAC,CA4BjB"}

package/dist/archive-kind.js

@@ -1,29 +1,23 @@
 import fsSync from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
-import { FsSafeError } from "./errors.js";
 import { getNativeBinding } from "./native.js";
 import { normalizeLowercaseStringOrEmpty } from "./string-coerce.js";
 const TAR_SUFFIXES = [".tgz", ".tar.gz", ".tar"];
-const NATIVE_TAR_SUFFIXES = [
+const COMPRESSED_TAR_SUFFIXES = [
     { suffixes: [".tbz2", ".tbz", ".tar.bz2"], kind: "tar-bzip2" },
     { suffixes: [".tzst", ".tar.zst", ".tar.zstd"], kind: "tar-zstd" },
 ];
-function requireNativeArchiveKind(kind) {
-    if (!getNativeBinding()) {
-        throw new FsSafeError("helper-unavailable", `${kind} archives require the matching optional native platform package; ` +
-            "install @openclaw/fs-safe with optional dependencies enabled on a supported platform and use FS_SAFE_NATIVE_MODE=auto or require");
-    }
-    return kind;
-}
 export function resolveArchiveKind(filePath) {
     const lower = normalizeLowercaseStringOrEmpty(filePath);
     if (lower.endsWith(".zip")) {
         return "zip";
     }
-    for (const { suffixes, kind } of NATIVE_TAR_SUFFIXES) {
+    for (const { suffixes, kind } of COMPRESSED_TAR_SUFFIXES) {
         if (suffixes.some((suffix) => lower.endsWith(suffix))) {
-            return requireNativeArchiveKind(kind);
+            // Preserve strict require diagnostics even when only resolving a suffix.
+            getNativeBinding();
+            return kind;
         }
     }
     if (TAR_SUFFIXES.some((suffix) => lower.endsWith(suffix))) {
@@ -75,9 +69,3 @@ export async function resolvePackedRootDir(extractDir, options) {
     }
     return path.join(extractDir, onlyDir);
 }
-export function assertPortableArchiveKind(kind) {
-    if (kind === "tar-zstd" || kind === "tar-bzip2") {
-        throw new FsSafeError("helper-unavailable", `${kind} archives require the matching optional native platform package; ` +
-            "install @openclaw/fs-safe with optional dependencies enabled on a supported platform and use FS_SAFE_NATIVE_MODE=auto or require");
-    }
-}

package/dist/archive-merge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"archive-merge.d.ts","sourceRoot":"","sources":["../src/archive-merge.ts"],"names":[],"mappings":"AAGA,OAAO,EAAoC,KAAK,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAClG,OAAO,EAIL,KAAK,qBAAqB,EAC3B,MAAM,sBAAsB,CAAC;AAc9B,MAAM,MAAM,uBAAuB,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AACjG,KAAK,WAAW,GAAG;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,EAAE,kBAAkB,CAAC;CAC/B,CAAC;AACF,KAAK,kBAAkB,GAAG,IAAI,CAAC,WAAW,EAAE,WAAW,GAAG,UAAU,CAAC,GAAG;IACtE,gBAAgB,EAAE,qBAAqB,CAAC;CACzC,CAAC;AAEF,wBAAsB,kCAAkC,CACtD,MAAM,EAAE,kBAAkB,GAAG;IAAE,OAAO,EAAE,SAAS,uBAAuB,EAAE,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GAC9F,OAAO,CAAC,IAAI,CAAC,CAGf;AAED,wBAAsB,iCAAiC,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAS1F"}
+{"version":3,"file":"archive-merge.d.ts","sourceRoot":"","sources":["../src/archive-merge.ts"],"names":[],"mappings":"AAGA,OAAO,EAAoC,KAAK,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAClG,OAAO,EAIL,KAAK,qBAAqB,EAC3B,MAAM,sBAAsB,CAAC;AAiB9B,MAAM,MAAM,uBAAuB,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AACjG,KAAK,WAAW,GAAG;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,EAAE,kBAAkB,CAAC;CAC/B,CAAC;AACF,KAAK,kBAAkB,GAAG,IAAI,CAAC,WAAW,EAAE,WAAW,GAAG,UAAU,CAAC,GAAG;IACtE,gBAAgB,EAAE,qBAAqB,CAAC;CACzC,CAAC;AAEF,wBAAsB,kCAAkC,CACtD,MAAM,EAAE,kBAAkB,GAAG;IAAE,OAAO,EAAE,SAAS,uBAAuB,EAAE,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GAC9F,OAAO,CAAC,IAAI,CAAC,CAGf;AAED,wBAAsB,iCAAiC,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAS1F"}

package/dist/archive-merge.js

@@ -5,16 +5,19 @@ import { ownExtractionDestinationMutation } from "./archive-deadline.js";
 import { assertDirectoryIdentityGuard, assertResolvedInsideDestination, createDirectoryIdentityGuard, createArchiveSymlinkTraversalError, preparePrivateArchiveOutputPath, } 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";
 import { formatErrorDetail } from "./error-detail.js";
-import { isPathInside } from "./path.js";
+import { isNotFoundPathError, isPathInside } from "./path.js";
 import { rootFromDirectoryGuard } from "./root-impl.js";
+import { admitPathInsideRoot } from "./root-boundary.js";
 import { realpathSync } from "./realpath.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
-import { onCopyPublication } from "./copy-publication.js";
+import { onCopyPublication, onCopySourceAdmission } from "./copy-publication.js";
 import { syncFileBestEffortSync } from "./file-sync.js";
 import { finalizeArchivePublication } from "./archive-durability.js";
 import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
+import { inspectFileIdentitySync } from "./strict-file-identity.js";
 export async function mergePlannedArchiveIntoDestination(params) {
     assertMergePathInputs(params);
     await mergeTree(params, params.entries, params.durable === true);
@@ -58,6 +61,33 @@ async function mergeTree(params, publication, durable = true) {
         plan.set(stagedPath, entry);
     }
     const ancestors = [];
+    const sourceAncestors = [];
+    const assertSourceDirectory = (guard, canonical = false) => {
+        try {
+            // Child receipts already retain canonical ancestry. An exact no-follow
+            // observation checks each named association without re-running realpath.
+            if (canonical)
+                assertSyncDirectoryGuard(guard);
+            else
+                inspectDirectoryIdentitySync(guard.dir, guard.stat);
+        }
+        catch (error) {
+            if (error instanceof FsSafeError || isNotFoundPathError(error)) {
+                throw createArchiveSymlinkTraversalError(path.relative(params.sourceDir, guard.dir));
+            }
+            throw error;
+        }
+        check();
+    };
+    const assertSourceFrontier = () => {
+        const current = sourceAncestors.at(-1);
+        if (current)
+            assertSourceDirectory(current);
+    };
+    const assertSourceAncestors = () => {
+        for (const ancestor of sourceAncestors)
+            assertSourceDirectory(ancestor);
+    };
     const assertGuards = async () => {
         await assertDirectoryIdentityGuard(destinationGuard);
         check();
@@ -72,15 +102,21 @@ async function mergeTree(params, publication, durable = true) {
     };
     const walk = async (sourceDir) => {
         await assertGuards();
+        assertSourceFrontier();
         const entries = await fs.readdir(sourceDir, { withFileTypes: true });
         check();
+        if (entries.length === 0) {
+            await assertGuards();
+            assertSourceFrontier();
+        }
         for (const entry of entries) {
             await assertGuards();
+            assertSourceFrontier();
             const sourcePath = path.join(sourceDir, entry.name);
             const relPath = path.relative(params.sourceDir, sourcePath);
             const originalPath = relPath.split(path.sep).join("/");
             const destinationPath = path.join(destinationDir, relPath);
-            const sourceStat = fsSync.lstatSync(sourcePath);
+            const sourceStat = inspectFileIdentitySync(() => fsSync.lstatSync(sourcePath, { bigint: true }));
             check();
             if (sourceStat.isSymbolicLink())
                 throw createArchiveSymlinkTraversalError(originalPath);
@@ -96,61 +132,73 @@ async function mergeTree(params, publication, durable = true) {
             if (plan && ((planned && planned.kind !== kind) || (!planned && kind === "file"))) {
                 throw new FsSafeError("path-mismatch", "archive staging disagrees with the admitted publication plan");
             }
-            const mode = plan ? planned?.mode ?? 0o755 : sourceStat.mode & 0o777;
+            let mode = plan ? planned?.mode ?? 0o755 : Number(sourceStat.mode & 511n);
             await preparePrivateArchiveOutputPath({
                 destinationDir, destinationRealDir, deadline: params.deadline,
                 relPath, outPath: destinationPath, originalPath, isDirectory: kind === "directory",
             }, assertGuards, destinationGuard);
             check();
             if (kind === "directory") {
-                // Ownership spans open, descendants, finalization and close, including timeout.
-                await ownExtractionDestinationMutation(params.deadline, async () => {
-                    await assertGuards();
-                    const owner = await pinNodeDirectoryForMode(destinationPath).catch((error) => {
-                        if (error instanceof FsSafeError && (error.code === "not-file" || error.code === "path-mismatch")) {
-                            throw createArchiveSymlinkTraversalError(originalPath);
-                        }
-                        throw error;
-                    });
-                    try {
-                        check();
-                        const guard = await createDirectoryIdentityGuard(destinationPath);
-                        check();
-                        await owner.verify(check);
-                        ancestors.push({ guard, owner });
-                        try {
-                            await walk(sourcePath);
-                            if (publication) {
-                                await assertGuards();
-                                publishedDirectories.push({ guard, mode, parents: ancestors.slice(0, -1).map((ancestor) => ancestor.guard) });
-                                return;
+                // Retain the observation made before output preparation: recapturing
+                // here could silently authorize a replacement source directory.
+                sourceAncestors.push({ dir: sourcePath, realPath: sourceReal, stat: sourceStat });
+                try {
+                    // Ownership spans open, descendants, finalization and close, including timeout.
+                    await ownExtractionDestinationMutation(params.deadline, async () => {
+                        await assertGuards();
+                        assertSourceFrontier();
+                        const owner = await pinNodeDirectoryForMode(destinationPath).catch((error) => {
+                            if (error instanceof FsSafeError && (error.code === "not-file" || error.code === "path-mismatch")) {
+                                throw createArchiveSymlinkTraversalError(originalPath);
                             }
-                            await getFsSafeTestHooks()?.beforeArchiveOutputMutation?.("chmod", destinationPath);
+                            throw error;
+                        });
+                        try {
                             check();
-                            await assertGuards();
-                            // Do not recursively verify this owner from inside its serialized apply.
-                            ancestors.pop();
-                            await owner.apply(mode, { check, beforeChmod: async () => {
-                                    await assertGuards();
-                                    await assertDirectoryIdentityGuard(guard);
-                                    check();
-                                    await assertResolvedInsideDestination({
-                                        destinationRealDir, targetPath: destinationPath, originalPath,
-                                    });
-                                    check();
-                                } });
+                            const guard = await createDirectoryIdentityGuard(destinationPath);
                             check();
-                            await assertGuards();
+                            await owner.verify(check);
+                            ancestors.push({ guard, owner });
+                            try {
+                                await walk(sourcePath);
+                                if (publication) {
+                                    await assertGuards();
+                                    assertSourceAncestors();
+                                    publishedDirectories.push({ guard, mode, parents: ancestors.slice(0, -1).map((ancestor) => ancestor.guard) });
+                                    return;
+                                }
+                                await getFsSafeTestHooks()?.beforeArchiveOutputMutation?.("chmod", destinationPath);
+                                check();
+                                await assertGuards();
+                                // Do not recursively verify this owner from inside its serialized apply.
+                                ancestors.pop();
+                                await owner.apply(mode, { check, beforeChmod: async () => {
+                                        await assertGuards();
+                                        assertSourceAncestors();
+                                        await assertDirectoryIdentityGuard(guard);
+                                        check();
+                                        await assertResolvedInsideDestination({
+                                            destinationRealDir, targetPath: destinationPath, originalPath,
+                                        });
+                                        check();
+                                    } });
+                                check();
+                                await assertGuards();
+                                assertSourceAncestors();
+                            }
+                            finally {
+                                if (ancestors.at(-1)?.owner === owner)
+                                    ancestors.pop();
+                            }
                         }
                         finally {
-                            if (ancestors.at(-1)?.owner === owner)
-                                ancestors.pop();
+                            await owner.close();
                         }
-                    }
-                    finally {
-                        await owner.close();
-                    }
-                });
+                    });
+                }
+                finally {
+                    sourceAncestors.pop();
+                }
             }
             else {
                 await ownExtractionDestinationMutation(params.deadline, async () => {
@@ -158,6 +206,25 @@ async function mergeTree(params, publication, durable = true) {
                     try {
                         const options = {
                             mkdir: true, mode, durable: publication ? false : true,
+                            [onCopySourceAdmission]: (identity, realPath) => {
+                                assertSourceDirectory(sourceGuard, true);
+                                assertSourceFrontier();
+                                inspectFileIdentitySync(() => identity, sourceStat);
+                                if (!admitPathInsideRoot({
+                                    rootPath: sourceGuard.realPath, candidatePath: realPath, rootIdentity: sourceGuard.stat,
+                                }))
+                                    throw createArchiveSymlinkTraversalError(originalPath);
+                                // Public merge permissions come from the admitted descriptor;
+                                // extraction keeps the separately admitted publication plan.
+                                if (!plan)
+                                    mode = Number(identity.mode & 511n);
+                                return { mode, verify() {
+                                        // Only copy publication boundaries scan the active chain.
+                                        // Destination mkdir callbacks must not multiply this work.
+                                        assertSourceDirectory(sourceGuard, true);
+                                        assertSourceAncestors();
+                                    } };
+                            },
                         };
                         if (publication && durable) {
                             options[onCopyPublication] = async (fd, identity) => {

package/dist/archive-read.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"archive-read.d.ts","sourceRoot":"","sources":["../src/archive-read.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAiD,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AA0OpG,wBAAsB,gBAAgB,CACpC,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,WAAW,CAAA;CAAE,GAChD,OAAO,CAAC,MAAM,CAAC,CAkBjB"}
+{"version":3,"file":"archive-read.d.ts","sourceRoot":"","sources":["../src/archive-read.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAsB,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAqOzE,wBAAsB,gBAAgB,CACpC,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,WAAW,CAAA;CAAE,GAChD,OAAO,CAAC,MAAM,CAAC,CAiBjB"}

package/dist/archive-read.js

@@ -7,12 +7,13 @@ import { readBoundedAsync } from "./bounded-read.js";
 import { ArchiveFormatError, ArchiveSecurityError, isArchiveFormatErrorMessage, } from "./archive-errors.js";
 import { formatErrorDetail } from "./error-detail.js";
 import { stripArchivePath, validateArchiveEntryPath, } from "./archive-entry.js";
-import { assertPortableArchiveKind, resolveArchiveKind } from "./archive-kind.js";
+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 { 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";
@@ -22,8 +23,6 @@ import { admitZipBuffer } from "./archive-zip-admission.js";
 import { validateNativeZipManifest } from "./archive-zip-manifest.js";
 import { resolveExtractLimits, resolveTarMeterLimits } from "./archive-limits.js";
 import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
-const ZIP_UNIX_FILE_TYPE_MASK = 0o170000;
-const ZIP_UNIX_SYMLINK_TYPE = 0o120000;
 function canonicalEntryPath(entryPath) {
     validateArchiveEntryPath(entryPath, { escapeLabel: "archive root" });
     return stripArchivePath(entryPath, 0) ?? "";
@@ -109,10 +108,11 @@ async function readZipEntry(buffer, entryPath, maxBytes, admitted) {
     if (!entry || entry.dir) {
         throw new Error(`archive entry not found: ${formatErrorDetail(entryPath)}`);
     }
-    if (typeof entry.unixPermissions === "number" &&
-        (entry.unixPermissions & ZIP_UNIX_FILE_TYPE_MASK) === ZIP_UNIX_SYMLINK_TYPE) {
+    if (isZipSymlinkEntry(entry)) {
         throw new Error(`archive entry is a link: ${formatErrorDetail(entryPath)}`);
     }
+    if (zipEntryKind(entry) !== "file")
+        throw new Error(`archive entry is not a file: ${formatErrorDetail(entryPath)}`);
     const integrity = createZipIntegrityTransform(entry);
     const stream = typeof entry.nodeStream === "function"
         ? entry.nodeStream()
@@ -139,11 +139,11 @@ async function readZipEntry(buffer, entryPath, maxBytes, admitted) {
         throw normalizeZipIntegrityError(error);
     }
 }
-async function readTarEntry(archiveBuffer, entryPath, maxBytes) {
+async function readTarEntry(archiveBuffer, entryPath, maxBytes, kind) {
     const seenPaths = new Set();
     let selected;
     const limits = resolveTarMeterLimits();
-    await inspectTar({ archiveBuffer, limits, onMember(info) {
+    await inspectTar({ archiveBuffer, kind, limits, onMember(info) {
             const normalized = canonicalEntryPath(info.path);
             if (seenPaths.has(normalized)) {
                 throw new ArchiveSecurityError("entry-path", `archive contains duplicate entry path: ${formatErrorDetail(normalized)}`);
@@ -159,7 +159,7 @@ async function readTarEntry(archiveBuffer, entryPath, maxBytes) {
     }
     if (selected.size > maxBytes)
         throw new ArchiveLimitError(ARCHIVE_LIMIT_ERROR_CODE.ENTRY_EXTRACTED_SIZE_EXCEEDS_LIMIT);
-    if (!isGzipBuffer(archiveBuffer)) {
+    if (kind === "tar" && !isGzipBuffer(archiveBuffer)) {
         // Complete admission already validated this private snapshot through EOF.
         // Copy the admitted payload so the result cannot expose or mutate its input.
         const end = selected.offset + selected.size;
@@ -170,7 +170,7 @@ async function readTarEntry(archiveBuffer, entryPath, maxBytes) {
         return Buffer.from(archiveBuffer.subarray(selected.offset, end));
     }
     let result;
-    await replayTar({ archiveBuffer, limits, members: [selected], async consume(member, payload) {
+    await replayTar({ archiveBuffer, kind, limits, members: [selected], async consume(member, payload) {
             result = await readAdmittedTarPayload(payload, member.size);
         } });
     return result;
@@ -238,7 +238,6 @@ export async function readArchiveEntry(archivePath, entryPath, options) {
     const native = getNativeBinding();
     if (native)
         return await readNativeBufferEntry(native, buffer, kind, requestedEntry, entryPath, options.maxBytes, zipEntries);
-    assertPortableArchiveKind(kind);
     return kind === "zip" ? await readZipEntry(buffer, requestedEntry, options.maxBytes, zipEntries)
-        : await readTarEntry(buffer, requestedEntry, options.maxBytes);
+        : await readTarEntry(buffer, requestedEntry, options.maxBytes, kind);
 }