@openclaw/fs-safe 0.7.2 → 0.8.1

package/CHANGELOG.md

@@ -1,5 +1,76 @@
 # Changelog
 
+## 0.8.1 - 2026-09-04
+
+- Add `retainOnExit` to sidecar lock acquisition so deliberately retained ownership records (for example fail-closed build locks) survive natural process exit; default process-exit release behavior is unchanged.
+
+## 0.8.0 - 2026-09-04
+
+### Compatibility and upgrade notes
+
+- **Existing secret directories must already have the requested mode.** Wrong permissions now fail the write with `insecure-permissions` instead of being chmod-repaired; audit and fix existing directories before upgrading.
+- **FileStore keys are enforced portably.** Parent-segment and backslash aliases are rejected with `invalid-path` across async reads, `exists`, and `remove`, matching the sync and write paths.
+- **Lock and queue failures now surface.** Durable queue enqueue, migration, and acknowledgement sync failures propagate instead of returning empty or partial success; sidecar payloads above 1 MiB are rejected with `too-large`; async lock retry counts apply even with infinite deadlines. Handle these rejections explicitly.
+- **Create-only visibility is backend-scoped.** The sibling-temp no-visibility guarantee for `create`, `createJson`, and `write({ overwrite: false })` holds with the native binding (`require` mode, or `auto` when the binding loads); the JavaScript fallback claims the final name before content is written.
+
+### Highlights
+
+- **Stricter secret storage:** existing secret directories are never chmod-repaired — wrong permissions fail the write — and directory identity is tracked exactly through private locks and native writes, closing replacement races.
+- **Exact file modes everywhere:** explicit modes, including set-ID bits, are applied after content writes and verified in full at publication, and synchronous appends no longer drop bytes when the kernel writes short.
+- **Restrictive secret modes work:** write-only and no-access files such as `0o200` and `0o000` publish successfully through the writer's retained descriptor, without a readonly reopen or widened permissions.
+- **Resilient locks and queues:** Windows sidecar creation retries genuine denials within the existing budgets, Root-backed locks release on natural process exit, and queue enqueue/migration/ack sync failures propagate instead of returning false success.
+- **Honest backend guarantees:** the no-visibility guarantee for create-only Root writes is scoped to backends with atomic no-replace publication (`require`, or `auto` with a loaded binding); the JavaScript fallback's behavior is documented and regression-pinned.
+
+### Secret files and permissions
+
+- Preserve existing secret-directory permissions instead of repairing them; retain lossless directory identities through private locks and native writes, initialize new directories through guarded descriptor authority, honor full directory mode bits, and fail closed for unpinnable parents, including non-root macOS directories created under `umask(0o777)`.
+- Finalize explicit file modes after content writes across pinned writers, verify all `0o7777` POSIX bits for secret publication, and use exact identities before native Windows mode changes and failed-write cleanup; JavaScript fallback cleanup preserves unverified replacements.
+- Complete short synchronous regular-file appends and preserve explicitly requested special mode bits in both append helpers, retaining permission tightening before any data is written.
+- Verify atomic secret writes through the writer's retained descriptor so restrictive POSIX modes such as `0o000` and `0o200` succeed without a readonly reopen or widened permissions.
+- Retry and fully revalidate raced secret-parent creation so concurrent writes to distinct leaves succeed without leaking `EEXIST` or reporting a false `secret-exists` collision.
+- Scope the sibling-temp no-visibility guarantee for create-only Root writes (`create`, `createJson`, `write({ overwrite: false })`) to backends with atomic no-replace publication: the native binding stages privately and renames without clobbering, while the pure-JavaScript fallback claims the final name exclusively before content is written. Regression tests now pin both behaviors.
+- Normalize every exclusive-copy target to mode `0o600` through its owned descriptor, including under restrictive umasks and native macOS clone staging.
+
+### Locks and durable queues
+
+- Retry Windows Root-backed sidecar exclusive-create denials within the existing eight-retry and caller budgets, using per-call provenance while preserving callback errors and rejecting replayed failure evidence.
+- Release asynchronously acquired Root-backed sidecar locks on natural event-loop shutdown through their retained ownership receipts, preserving changed sidecars and avoiding cleanup retry loops.
+- Keep async Root-backed lock normalization read-only, rejecting deleted or replaced admitted parents without recreating them while preserving explicit in-root sidecars for external target keys.
+- Reject serialized sidecar lock payloads above 1 MiB of UTF-8 bytes, including ownership overhead, with `too-large` before async or sync acquisition so admitted locks remain verifiable and releasable.
+- Honor explicit async file-lock retry counts independently of infinite deadlines, matching sync locks while preserving unlimited retries when the count is omitted.
+- Propagate durable queue enqueue parent-sync failures and keep published-file identity checks after synchronization, sharing the guarded writer with migrations while retaining retry state.
+- Propagate durable queue batch claim and migration failures instead of returning empty or partial success, and strictly sync migration publication in both loaders while preserving retry state.
+- Resync durable queue acknowledgement retries after final marker unlink before reporting completion or a newer-generation mismatch.
+
+### Paths, stores, and moves
+
+- Enforce portable FileStore keys consistently across methods: async reads, `exists`, and `remove` now reject parent-segment and backslash aliases with `invalid-path` for existing roots, matching sync and write methods while preserving missing-root error precedence and Root's confined existing-object compatibility.
+- Prevent no-reader FIFOs from stalling POSIX `Root.openWritable()` and async/sync regular-file append admission, preserving regular-file write semantics and existing-target cleanup fencing.
+- Accept canonical in-root absolute paths in `Root.readAbsolute()` and `Root.reader()` when the Root was configured through a directory symlink or Windows junction.
+- Reject dangling symlink leaves and ancestors under strict absolute-write and missing local-root resolution instead of treating unresolved aliases as safe missing paths.
+- Move dangling symlink sources through staged and cross-device fallback without dereferencing their absent referents, while retaining same-entry, descendant, and source-substitution guards.
+- Retire every copied source name after cross-device moves with allowed in-tree hardlink aliases, while preserving `ESTALE` fences for unverified external mutations.
+- End `Root.walk()` immediately after its single truncation marker, including when a nested depth or entry budget is reached.
+- Bound callback staging components to 255 NFC/NFD bytes so filesystem-valid long destination names work without changing final names or short callback paths.
+
+### Archives
+
+- Separate archive staging permissions from final publication modes so zero/write-only files and restrictive directories extract correctly; finalize explicit and implicit directory modes through retained, verified authority and reject unsafe mode application instead of silently skipping it.
+- Preserve pre-existing and substituted destination files when an archive merge fails, leaving guarded copy cleanup to the operation that owns publication.
+- Decode absent TAR modes and supported signed GNU binary permission bits in native manifests, matching JavaScript defaults without changing the native ABI.
+- Close a selected archive input if private staging allocation fails, preventing `readArchiveEntry()` setup errors from retaining file descriptors until garbage collection.
+- Avoid opening the TAR metadata stream until preflight setup succeeds, and always destroy it after pipeline completion, preventing descriptor leaks on setup failures. Thanks @SebTardif.
+
+### Docs, packaging, and validation
+
+- Add the narrow `@openclaw/fs-safe/secure-temp-root` package subpath so consumers can import `resolveSecureTempRoot()` and its options type without loading the temp workspace implementation.
+- Exercise secret-directory admission from isolated npm/pnpm consumer installs, retain real-identity and native-load proof, and honor explicit package-proof output paths.
+- Correct lower-level archive helper signatures in the reference docs and guard them against drifting from the public declarations.
+- Keep slow physical-package fixture setup outside the process-exit test deadline, drain fixture work before teardown, and give each adversarial corpus payload its own test lifetime while retaining Windows boundary assertions.
+- Bound workflow-dispatch test subprocesses and terminate their process groups before fixture cleanup, so stuck shell descendants fail validation instead of hanging the suite.
+- Assign cross-platform sidecar contention proof liveness to its whole-worker watchdog instead of false-failing healthy unfair acquisition; production lock timeout behavior is unchanged.
+- Refresh the Node type definitions, align development and CI on pnpm 11.25.0, and update the pinned Pages deployment action to v5.0.1 for polling backoff and jitter. Thanks @dependabot.
+
 ## 0.7.2 - 2026-09-01
 
 - Add `movePathWithCopyFallback({ assertBeforeRename })` to synchronously recheck caller-owned authorization immediately before direct or staged rename, preserving refusal errors and rejecting asynchronous callbacks without publishing the move.

package/README.md

@@ -176,7 +176,7 @@ Root reads default to `DEFAULT_ROOT_MAX_BYTES` (16 MiB). Pass a larger `maxBytes
 for expected large reads, or `Number.POSITIVE_INFINITY` when the caller has a
 separate size budget.
 
-`reader()` returns a callback that reads absolute or relative paths through the same root boundary. It is useful for APIs that accept a `(path) => Promise<Buffer>` loader. Absolute paths outside the root are rejected with `outside-workspace`. `readAbsolute()` has the same absolute-path behavior directly.
+`reader()` returns a callback that reads absolute or relative paths through the same root boundary. It is useful for APIs that accept a `(path) => Promise<Buffer>` loader. For roots configured through a directory symlink or Windows junction, absolute inputs may use either the configured spelling or the canonical real path. Absolute paths outside the root are rejected with `outside-workspace`. `readAbsolute()` has the same absolute-path behavior directly.
 
 When you need a writable `FileHandle`, use `openWritable()` and prefer `await using` for cleanup:
 
@@ -189,6 +189,10 @@ await using opened = await fs.openWritable("logs/current.log", { writeMode: "app
 
 `nonBlockingRead` remains as a compatibility hint in `RootDefaults`. Safe read/open operations already use nonblocking descriptor opens where the platform supports them so a raced FIFO cannot pin a worker; filesystem safety policy remains explicit through `hardlinks`, `symlinks`, and `denyMutations`.
 
+On POSIX, `openWritable()` also uses nonblocking admission for existing targets
+so a no-reader FIFO cannot stall validation. Ordinary regular-file write
+semantics are unchanged; see [writing](docs/writing.md#openwritable-for-streaming).
+
 ```ts
 const locked = await root("/srv/workspace", {
   denyMutations: {

package/dist/absolute-path.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"absolute-path.d.ts","sourceRoot":"","sources":["../src/absolute-path.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,WAAW,EAAE,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC;AAGhE,MAAM,MAAM,yBAAyB,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAU5D,MAAM,MAAM,oBAAoB,GAAG;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,4BAA4B,GAAG,oBAAoB,GAAG;IAChE,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,OAAO,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,8BAA8B,GAAG;IAC3C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,6BAA6B,GACrC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC1B;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,eAAe,CAAC;IAAC,KAAK,EAAE,WAAW,CAAA;CAAE,CAAC;AAmL7D,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAWhE;AAED,wBAAsB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAEnF;AAuBD,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,8BAAmC,GAC3C,OAAO,CAAC,6BAA6B,CAAC,CA+ExC;AAED,wBAAsB,iCAAiC,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAazF;AAED,wBAAsB,0BAA0B,CAC9C,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,yBAAyB,CAAA;CAAO,GACrD,OAAO,CAAC,oBAAoB,CAAC,CAgB/B;AAED,wBAAsB,2BAA2B,CAC/C,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,yBAAyB,CAAA;CAAO,GACrD,OAAO,CAAC,4BAA4B,CAAC,CA6BvC"}
+{"version":3,"file":"absolute-path.d.ts","sourceRoot":"","sources":["../src/absolute-path.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,WAAW,EAAE,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC;AAIhE,MAAM,MAAM,yBAAyB,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAU5D,MAAM,MAAM,oBAAoB,GAAG;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,4BAA4B,GAAG,oBAAoB,GAAG;IAChE,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,OAAO,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,8BAA8B,GAAG;IAC3C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,6BAA6B,GACrC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC1B;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,eAAe,CAAC;IAAC,KAAK,EAAE,WAAW,CAAA;CAAE,CAAC;AAmL7D,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAWhE;AAED,wBAAsB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAEnF;AAuBD,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,8BAAmC,GAC3C,OAAO,CAAC,6BAA6B,CAAC,CA+ExC;AAED,wBAAsB,iCAAiC,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAazF;AAED,wBAAsB,0BAA0B,CAC9C,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,yBAAyB,CAAA;CAAO,GACrD,OAAO,CAAC,oBAAoB,CAAC,CAgB/B;AAED,wBAAsB,2BAA2B,CAC/C,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,yBAAyB,CAAA;CAAO,GACrD,OAAO,CAAC,4BAA4B,CAAC,CA2BvC"}

package/dist/absolute-path.js

@@ -3,6 +3,7 @@ import path from "node:path";
 import { assertAsyncDirectoryGuard, createAsyncDirectoryGuard, } from "./directory-guard.js";
 import { FsSafeError } from "./errors.js";
 import { pathExists } from "./fs.js";
+import { resolveRootPath } from "./root-path.js";
 function resolveSymlinkPolicy(policy) {
     if (policy === undefined)
         return "reject";
@@ -281,16 +282,14 @@ export async function resolveAbsolutePathForWrite(filePath, options = {}) {
     const parentDir = path.dirname(normalized);
     const parentExists = await pathExists(parentDir);
     if (symlinks === "reject") {
-        const ancestor = await findExistingAncestor(parentDir);
-        if (ancestor) {
-            const canonicalAncestor = await fs.realpath(ancestor).catch(() => ancestor);
-            if (canonicalAncestor !== ancestor) {
-                const canonicalPath = path.join(canonicalAncestor, path.relative(ancestor, normalized));
-                throw new FsSafeError("symlink", "path traverses a symlink", {
-                    cause: { canonicalPath },
-                });
-            }
-        }
+        const filesystemRoot = path.parse(normalized).root;
+        await resolveRootPath({
+            absolutePath: normalized,
+            rootPath: filesystemRoot,
+            rootCanonicalPath: filesystemRoot,
+            boundaryLabel: "absolute path",
+            rejectSymlinks: true,
+        });
     }
     const canonicalPath = await canonicalPathFromExistingAncestor(normalized);
     if (symlinks === "reject" && canonicalPath !== normalized) {

package/dist/archive-merge.d.ts

@@ -0,0 +1,18 @@
+import { type ExtractionDeadline } from "./archive-deadline.js";
+export type ArchivePublicationEntry = {
+    path: string;
+    kind: "file" | "directory";
+    mode: number;
+};
+type MergeParams = {
+    sourceDir: string;
+    destinationDir: string;
+    destinationRealDir: string;
+    deadline?: ExtractionDeadline;
+};
+export declare function mergePlannedArchiveIntoDestination(params: MergeParams & {
+    entries: readonly ArchivePublicationEntry[];
+}): Promise<void>;
+export declare function mergeExtractedTreeIntoDestination(params: MergeParams): Promise<void>;
+export {};
+//# sourceMappingURL=archive-merge.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"archive-merge.d.ts","sourceRoot":"","sources":["../src/archive-merge.ts"],"names":[],"mappings":"AAEA,OAAO,EAAoC,KAAK,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAelG,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;AAEF,wBAAsB,kCAAkC,CACtD,MAAM,EAAE,WAAW,GAAG;IAAE,OAAO,EAAE,SAAS,uBAAuB,EAAE,CAAA;CAAE,GACpE,OAAO,CAAC,IAAI,CAAC,CAEf;AAED,wBAAsB,iCAAiC,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAE1F"}

package/dist/archive-merge.js

@@ -0,0 +1,157 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { ownExtractionDestinationMutation } from "./archive-deadline.js";
+import { assertDirectoryIdentityGuard, assertResolvedInsideDestination, createDirectoryIdentityGuard, createArchiveSymlinkTraversalError, preparePrivateArchiveOutputPath, } from "./archive-staging.js";
+import {} from "./directory-guard.js";
+import {} from "./directory-mode-owner.js";
+import { pinNodeDirectoryForMode } from "./directory-mode-node.js";
+import { FsSafeError } from "./errors.js";
+import { formatErrorDetail } from "./error-detail.js";
+import { isPathInside } from "./path.js";
+import { root } from "./root.js";
+import { getFsSafeTestHooks } from "./test-hooks.js";
+export async function mergePlannedArchiveIntoDestination(params) {
+    await mergeTree(params, params.entries);
+}
+export async function mergeExtractedTreeIntoDestination(params) {
+    await mergeTree(params);
+}
+async function mergeTree(params, publication) {
+    const check = () => params.deadline?.check();
+    check();
+    const destinationGuard = await createDirectoryIdentityGuard(params.destinationRealDir);
+    check();
+    const targetRoot = await root(params.destinationRealDir);
+    check();
+    const sourceGuard = await createDirectoryIdentityGuard(params.sourceDir);
+    check();
+    const plan = publication ? new Map() : undefined;
+    for (const entry of publication ?? []) {
+        // Resolve admitted spelling in private staging, preserving the volume's case
+        // and Unicode behavior without assigning explicit modes to distinct parents.
+        const stagedPath = await fs.realpath(path.join(params.sourceDir, entry.path));
+        check();
+        if (!isPathInside(sourceGuard.realPath, stagedPath) || plan.has(stagedPath)) {
+            throw new FsSafeError("path-mismatch", "archive publication paths changed in staging");
+        }
+        plan.set(stagedPath, entry);
+    }
+    const ancestors = [];
+    const assertGuards = async () => {
+        await assertDirectoryIdentityGuard(destinationGuard);
+        check();
+        for (const ancestor of ancestors) {
+            await assertDirectoryIdentityGuard(ancestor.guard);
+            check();
+            await ancestor.owner.verify(check);
+            check();
+        }
+        await assertDirectoryIdentityGuard(sourceGuard);
+        check();
+    };
+    const walk = async (sourceDir) => {
+        await assertGuards();
+        const entries = await fs.readdir(sourceDir, { withFileTypes: true });
+        check();
+        for (const entry of entries) {
+            await assertGuards();
+            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(params.destinationDir, relPath);
+            const sourceStat = await fs.lstat(sourcePath);
+            check();
+            if (sourceStat.isSymbolicLink())
+                throw createArchiveSymlinkTraversalError(originalPath);
+            const sourceReal = await fs.realpath(sourcePath);
+            check();
+            if (!isPathInside(sourceGuard.realPath, sourceReal))
+                throw createArchiveSymlinkTraversalError(originalPath);
+            if (!sourceStat.isFile() && !sourceStat.isDirectory()) {
+                throw new Error(`archive staging contains unsupported entry: ${formatErrorDetail(originalPath)}`);
+            }
+            const kind = sourceStat.isDirectory() ? "directory" : "file";
+            const planned = plan?.get(sourceReal);
+            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;
+            await preparePrivateArchiveOutputPath({
+                ...params, relPath, outPath: destinationPath, originalPath, isDirectory: kind === "directory",
+            }, assertGuards);
+            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);
+                            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();
+                                    await assertDirectoryIdentityGuard(guard);
+                                    check();
+                                    await assertResolvedInsideDestination({
+                                        destinationRealDir: params.destinationRealDir, targetPath: destinationPath, originalPath,
+                                    });
+                                    check();
+                                } });
+                            check();
+                            await assertGuards();
+                        }
+                        finally {
+                            if (ancestors.at(-1)?.owner === owner)
+                                ancestors.pop();
+                        }
+                    }
+                    finally {
+                        await owner.close();
+                    }
+                });
+            }
+            else {
+                await ownExtractionDestinationMutation(params.deadline, async () => {
+                    await assertGuards();
+                    try {
+                        await targetRoot.copyIn(relPath, sourcePath, { mkdir: true, mode });
+                        check();
+                        await assertGuards();
+                        await assertResolvedInsideDestination({
+                            destinationRealDir: params.destinationRealDir, targetPath: destinationPath, originalPath,
+                        });
+                        check();
+                        const stat = await fs.lstat(destinationPath);
+                        check();
+                        if (stat.isSymbolicLink() || (stat.isFile() && stat.nlink > 1)) {
+                            throw createArchiveSymlinkTraversalError(originalPath);
+                        }
+                    }
+                    catch (error) {
+                        // copyIn alone owns cleanup; no receipt permits archive-layer unlink.
+                        if (error instanceof FsSafeError && (error.code === "hardlink" || error.code === "path-alias")) {
+                            throw createArchiveSymlinkTraversalError(originalPath);
+                        }
+                        throw error;
+                    }
+                });
+            }
+        }
+    };
+    await walk(params.sourceDir);
+}

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

@@ -1 +1 @@
-{"version":3,"file":"archive-native.d.ts","sourceRoot":"","sources":["../src/archive-native.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAEhE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAML,KAAK,4BAA4B,EACjC,KAAK,cAAc,EACpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAOlE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AA2BjD,wBAAsB,oBAAoB,CAAC,MAAM,EAAE;IACjD,OAAO,EAAE,aAAa,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,WAAW,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,MAAM,EAAE,4BAA4B,CAAC;IACrC,SAAS,EAAE,cAAc,CAAC;IAC1B,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,UAAU,CAAC,EAAE,qBAAqB,CAAC,YAAY,CAAC,CAAC;IACjD,WAAW,CAAC,EAAE,qBAAqB,CAAC,aAAa,CAAC,CAAC;IACnD,UAAU,CAAC,EAAE,qBAAqB,CAAC,YAAY,CAAC,CAAC;CAClD,GAAG,OAAO,CAAC,IAAI,CAAC,CAsIhB"}
+{"version":3,"file":"archive-native.d.ts","sourceRoot":"","sources":["../src/archive-native.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAEhE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAML,KAAK,4BAA4B,EACjC,KAAK,cAAc,EACpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAQlE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AA2BjD,wBAAsB,oBAAoB,CAAC,MAAM,EAAE;IACjD,OAAO,EAAE,aAAa,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,WAAW,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,MAAM,EAAE,4BAA4B,CAAC;IACrC,SAAS,EAAE,cAAc,CAAC;IAC1B,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,UAAU,CAAC,EAAE,qBAAqB,CAAC,YAAY,CAAC,CAAC;IACjD,WAAW,CAAC,EAAE,qBAAqB,CAAC,aAAa,CAAC,CAAC;IACnD,UAAU,CAAC,EAAE,qBAAqB,CAAC,YAAY,CAAC,CAAC;CAClD,GAAG,OAAO,CAAC,IAAI,CAAC,CAyJhB"}

package/dist/archive-native.js

@@ -6,7 +6,8 @@ import { createArchiveOutputPathTracker, resolveArchiveOutputPath, stripArchiveP
 import { stageArchiveFileForExtraction } from "./archive-input.js";
 import { ARCHIVE_LIMIT_ERROR_CODE, ArchiveLimitError, assertArchiveEntryCountWithinLimit, assertArchiveEntryPathComponentsWithinLimit, createByteBudgetTracker, } from "./archive-limits.js";
 import { resolveArchiveEntryMode, shouldExtractArchiveEntry } from "./archive-policy.js";
-import { mergeExtractedTreeIntoDestination, prepareArchiveDestinationDir, withStagedArchiveDestination, } from "./archive-staging.js";
+import { prepareArchiveDestinationDir, withStagedArchiveDestination, } from "./archive-staging.js";
+import { mergePlannedArchiveIntoDestination } from "./archive-merge.js";
 import { admitZipFile } from "./archive-zip-admission.js";
 function policyKind(kind) {
     if (kind === "file" || kind === "directory")
@@ -41,8 +42,9 @@ export async function extractNativeArchive(params) {
         deadline: params.deadline,
     });
     try {
+        const zipEntries = [];
         const physicalCount = params.kind === "zip"
-            ? await admitZipFile(stagedArchive.path, limits, params.deadline)
+            ? await admitZipFile(stagedArchive.path, limits, params.deadline, (entry) => { zipEntries.push(entry); })
             : undefined;
         const destinationRealDir = await prepareArchiveDestinationDir(params.destDir);
         await withStagedArchiveDestination({
@@ -57,6 +59,19 @@ export async function extractNativeArchive(params) {
                 if (physicalCount !== undefined && manifest.length !== physicalCount) {
                     throw new ArchiveSecurityError("entry-path", "zip decoder collapsed entry names");
                 }
+                if (params.kind === "zip") {
+                    for (const [ordinal, entry] of manifest.entries()) {
+                        const physical = zipEntries[ordinal];
+                        // Native ZIP indices are physical central-directory ordinals. Legacy
+                        // filename decoding remains native-selected; compare names when known.
+                        if (!physical || physical.index !== ordinal || entry.index !== ordinal ||
+                            entry.size !== physical.size ||
+                            (physical.path !== undefined && stripArchivePath(entry.path, 0) !== stripArchivePath(physical.path, 0)) ||
+                            (physical.creatorSystem === 3 && entry.mode !== physical.externalAttributes >>> 16)) {
+                            throw new ArchiveFormatError("ZIP decoder disagrees with admitted directory metadata");
+                        }
+                    }
+                }
                 // Recheck the native manifest at the shared policy boundary before
                 // any caller callback observes an entry.
                 if (params.kind !== "zip") {
@@ -111,7 +126,11 @@ export async function extractNativeArchive(params) {
                             size: entry.size,
                             mode: resolveArchiveEntryMode({
                                 kind,
-                                archivedMode: entry.mode,
+                                archivedMode: params.kind === "zip"
+                                    ? zipEntries[entry.index].creatorSystem === 3
+                                        ? zipEntries[entry.index].externalAttributes >>> 16
+                                        : undefined
+                                    : entry.mode,
                                 policy: params.entryModes,
                             }),
                         });
@@ -121,13 +140,14 @@ export async function extractNativeArchive(params) {
                     (typeof fsConstants.O_DIRECTORY === "number" ? fsConstants.O_DIRECTORY : 0));
                 try {
                     params.deadline.check();
-                    await params.binding.extractArchiveNative(stagedArchive.path, params.kind, directory.fd, plan, tarLimits, params.deadline.signal).catch(throwMappedNativeError);
+                    await params.binding.extractArchiveNative(stagedArchive.path, params.kind, directory.fd, plan.map((entry) => ({ ...entry, mode: entry.kind === "directory" ? 0o700 : 0o600 })), tarLimits, params.deadline.signal).catch(throwMappedNativeError);
                 }
                 finally {
                     await directory.close().catch(() => undefined);
                 }
                 params.deadline.check();
-                await mergeExtractedTreeIntoDestination({
+                await mergePlannedArchiveIntoDestination({
+                    entries: plan,
                     sourceDir: stagingDir,
                     destinationDir: params.destDir,
                     destinationRealDir,

package/dist/archive-policy.d.ts

@@ -10,7 +10,7 @@ export type ArchiveEntryFilter = (entry: {
 export declare function archiveEntryKindFromTarType(type: string): ArchiveEntryKind;
 export declare function resolveArchiveEntryMode(params: {
     kind: "file" | "directory";
-    archivedMode?: number;
+    archivedMode?: number | null;
     policy?: ArchiveEntryModePolicy;
 }): number;
 export declare function resolveArchiveFilteredEntryPolicy(value: unknown): ArchiveFilteredEntryPolicy;

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

@@ -1 +1 @@
-{"version":3,"file":"archive-policy.d.ts","sourceRoot":"","sources":["../src/archive-policy.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,WAAW,GAAG,SAAS,GAAG,OAAO,CAAC;AAC1E,MAAM,MAAM,sBAAsB,GAAG,OAAO,GAAG,UAAU,CAAC;AAC1D,MAAM,MAAM,0BAA0B,GAAG,gBAAgB,GAAG,YAAY,CAAC;AACzE,MAAM,MAAM,kBAAkB,GAAG,CAAC,KAAK,EAAE;IACvC,iGAAiG;IACjG,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,gBAAgB,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;CACd,KAAK,SAAS,GAAG,MAAM,CAAC;AAEzB,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,CAK1E;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE;IAC9C,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;IAC3B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,sBAAsB,CAAC;CACjC,GAAG,MAAM,CAST;AAED,wBAAgB,iCAAiC,CAC/C,KAAK,EAAE,OAAO,GACb,0BAA0B,CAM5B;AAED,wBAAgB,yBAAyB,CAAC,MAAM,EAAE;IAChD,MAAM,CAAC,EAAE,kBAAkB,CAAC;IAC5B,UAAU,CAAC,EAAE,0BAA0B,CAAC;IACxC,KAAK,EAAE,UAAU,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC,CAAC;CAC1C,GAAG,OAAO,CAYV"}
+{"version":3,"file":"archive-policy.d.ts","sourceRoot":"","sources":["../src/archive-policy.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,WAAW,GAAG,SAAS,GAAG,OAAO,CAAC;AAC1E,MAAM,MAAM,sBAAsB,GAAG,OAAO,GAAG,UAAU,CAAC;AAC1D,MAAM,MAAM,0BAA0B,GAAG,gBAAgB,GAAG,YAAY,CAAC;AACzE,MAAM,MAAM,kBAAkB,GAAG,CAAC,KAAK,EAAE;IACvC,iGAAiG;IACjG,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,gBAAgB,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;CACd,KAAK,SAAS,GAAG,MAAM,CAAC;AAEzB,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,CAK1E;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE;IAC9C,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;IAC3B,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,MAAM,CAAC,EAAE,sBAAsB,CAAC;CACjC,GAAG,MAAM,CAST;AAED,wBAAgB,iCAAiC,CAC/C,KAAK,EAAE,OAAO,GACb,0BAA0B,CAM5B;AAED,wBAAgB,yBAAyB,CAAC,MAAM,EAAE;IAChD,MAAM,CAAC,EAAE,kBAAkB,CAAC;IAC5B,UAAU,CAAC,EAAE,0BAA0B,CAAC;IACxC,KAAK,EAAE,UAAU,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC,CAAC;CAC1C,GAAG,OAAO,CAYV"}

package/dist/archive-policy.js

@@ -12,7 +12,7 @@ export function archiveEntryKindFromTarType(type) {
 export function resolveArchiveEntryMode(params) {
     const archivedMode = (params.archivedMode ?? 0) & 0o777;
     if (params.policy === "preserve") {
-        return archivedMode || (params.kind === "directory" ? 0o755 : 0o644);
+        return params.archivedMode == null ? (params.kind === "directory" ? 0o755 : 0o644) : archivedMode;
     }
     if (params.kind === "directory") {
         return 0o755;

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

@@ -1 +1 @@
-{"version":3,"file":"archive-read.d.ts","sourceRoot":"","sources":["../src/archive-read.ts"],"names":[],"mappings":"AAcA,OAAO,EAAsB,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAgOzE,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,CAuFjB"}
+{"version":3,"file":"archive-read.d.ts","sourceRoot":"","sources":["../src/archive-read.ts"],"names":[],"mappings":"AAcA,OAAO,EAAsB,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAiOzE,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,CAuFjB"}

package/dist/archive-read.js

@@ -73,8 +73,9 @@ async function stageArchiveInput(archivePath) {
         return stat;
     });
     const handle = await fs.open(resolved, resolveReadOpenFlags());
-    const staged = await tempFile({ prefix: "fs-safe-archive-read", fileName: "archive.bin" });
+    let staged;
     try {
+        staged = await tempFile({ prefix: "fs-safe-archive-read", fileName: "archive.bin" });
         const opened = await inspectFileIdentity(async () => {
             const stat = await handle.stat({ bigint: true });
             if (!stat.isFile())
@@ -92,7 +93,7 @@ async function stageArchiveInput(archivePath) {
         return { path: staged.path, buffer, cleanup: staged.cleanup };
     }
     catch (error) {
-        await staged.cleanup().catch(() => undefined);
+        await staged?.cleanup().catch(() => undefined);
         if (error instanceof FsSafeError && error.code === "path-mismatch") {
             throw new FsSafeError("path-mismatch", "archive changed during validation", { cause: error });
         }

package/dist/archive-staging.d.ts

@@ -1,8 +1,16 @@
+import { type AsyncDirectoryGuard } from "./directory-guard.js";
 import { type ExtractionDeadline } from "./archive-deadline.js";
 import { ArchiveSecurityError } from "./archive-errors.js";
 export { ArchiveSecurityError, type ArchiveSecurityErrorCode } from "./archive-errors.js";
+export declare function createDirectoryIdentityGuard(dir: string): Promise<AsyncDirectoryGuard>;
+export declare function assertDirectoryIdentityGuard(guard: AsyncDirectoryGuard): Promise<void>;
 export declare function prepareArchiveDestinationDir(destDir: string): Promise<string>;
-export declare function prepareArchiveOutputPath(params: {
+export declare function assertResolvedInsideDestination(params: {
+    destinationRealDir: string;
+    targetPath: string;
+    originalPath: string;
+}): Promise<void>;
+type ArchiveOutputPathParams = {
     destinationDir: string;
     destinationRealDir: string;
     relPath: string;
@@ -10,17 +18,14 @@ export declare function prepareArchiveOutputPath(params: {
     originalPath: string;
     isDirectory: boolean;
     deadline?: ExtractionDeadline;
-}): Promise<void>;
+};
+export declare function prepareArchiveOutputPath(params: ArchiveOutputPathParams): Promise<void>;
+export declare function preparePrivateArchiveOutputPath(params: ArchiveOutputPathParams, assertGuards?: () => Promise<void>): Promise<void>;
 export declare function withStagedArchiveDestination<T>(params: {
     destinationRealDir: string;
     stagingDirPrefix?: string;
     run: (stagingDir: string) => Promise<T>;
 }): Promise<T>;
-export declare function mergeExtractedTreeIntoDestination(params: {
-    sourceDir: string;
-    destinationDir: string;
-    destinationRealDir: string;
-    deadline?: ExtractionDeadline;
-}): Promise<void>;
+export { mergeExtractedTreeIntoDestination } from "./archive-merge.js";
 export declare function createArchiveSymlinkTraversalError(originalPath: string): ArchiveSecurityError;
 //# sourceMappingURL=archive-staging.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"archive-staging.d.ts","sourceRoot":"","sources":["../src/archive-staging.ts"],"names":[],"mappings":"AAOA,OAAO,EAEL,KAAK,kBAAkB,EACxB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,oBAAoB,EAErB,MAAM,qBAAqB,CAAC;AAgB7B,OAAO,EAAE,oBAAoB,EAAE,KAAK,wBAAwB,EAAE,MAAM,qBAAqB,CAAC;AAkC1F,wBAAsB,4BAA4B,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CA4BnF;AA4DD,wBAAsB,wBAAwB,CAAC,MAAM,EAAE;IACrD,cAAc,EAAE,MAAM,CAAC;IACvB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,EAAE,kBAAkB,CAAC;CAC/B,GAAG,OAAO,CAAC,IAAI,CAAC,CA6DhB;AAsID,wBAAsB,4BAA4B,CAAC,CAAC,EAAE,MAAM,EAAE;IAC5D,kBAAkB,EAAE,MAAM,CAAC;IAC3B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,GAAG,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;CACzC,GAAG,OAAO,CAAC,CAAC,CAAC,CA6Bb;AAED,wBAAsB,iCAAiC,CAAC,MAAM,EAAE;IAC9D,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,EAAE,kBAAkB,CAAC;CAC/B,GAAG,OAAO,CAAC,IAAI,CAAC,CA8FhB;AAED,wBAAgB,kCAAkC,CAAC,YAAY,EAAE,MAAM,GAAG,oBAAoB,CAE7F"}
+{"version":3,"file":"archive-staging.d.ts","sourceRoot":"","sources":["../src/archive-staging.ts"],"names":[],"mappings":"AAEA,OAAO,EAGL,KAAK,mBAAmB,EACzB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAEL,KAAK,kBAAkB,EACxB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,oBAAoB,EAErB,MAAM,qBAAqB,CAAC;AAkB7B,OAAO,EAAE,oBAAoB,EAAE,KAAK,wBAAwB,EAAE,MAAM,qBAAqB,CAAC;AAS1F,wBAAsB,4BAA4B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAS5F;AAED,wBAAsB,4BAA4B,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAY5F;AAED,wBAAsB,4BAA4B,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CA4BnF;AA0BD,wBAAsB,+BAA+B,CAAC,MAAM,EAAE;IAC5D,kBAAkB,EAAE,MAAM,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;CACtB,GAAG,OAAO,CAAC,IAAI,CAAC,CAahB;AAiBD,KAAK,uBAAuB,GAAG;IAC7B,cAAc,EAAE,MAAM,CAAC;IACvB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,EAAE,kBAAkB,CAAC;CAC/B,CAAC;AAEF,wBAAsB,wBAAwB,CAAC,MAAM,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC,CAE7F;AAED,wBAAsB,+BAA+B,CACnD,MAAM,EAAE,uBAAuB,EAAE,YAAY,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAClE,OAAO,CAAC,IAAI,CAAC,CAEf;AA8GD,wBAAsB,4BAA4B,CAAC,CAAC,EAAE,MAAM,EAAE;IAC5D,kBAAkB,EAAE,MAAM,CAAC;IAC3B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,GAAG,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;CACzC,GAAG,OAAO,CAAC,CAAC,CAAC,CA6Bb;AAED,OAAO,EAAE,iCAAiC,EAAE,MAAM,oBAAoB,CAAC;AAEvE,wBAAgB,kCAAkC,CAAC,YAAY,EAAE,MAAM,GAAG,oBAAoB,CAE7F"}