@openclaw/fs-safe 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## 0.1.0 - 2026-05-06
+
+### Features
+
+- Added `root()` capability-style filesystem handles for root-bounded reads, writes, appends, moves, copies, directory listing, stat, mkdir, remove, JSON, streams, and existence checks.
+- Added traversal, symlink, hardlink, alias, and post-open/post-write identity checks for untrusted relative paths.
+- Added process-global Python helper configuration for stronger POSIX fd-relative mutation paths, with `auto`, `off`, and `require` modes.
+- Added atomic file and directory replacement helpers with mode control, fsync options, retry handling, and copy-fallback behavior.
+- Added JSON helpers, `fileStore()`, `jsonStore()`, private store mode, and file-backed temporary workspaces.
+- Added secure absolute file reads, secret-file helpers, permissions inspection, Windows ACL helpers, and local-root readers.
+- Added archive extraction and preflight helpers for ZIP/TAR with optional `jszip` and `tar` dependencies, size/count/path/link limits, and staged destination writes.
+- Added file locks, async locks, bounded directory walking, install-path sanitizers, filename sanitization, regular-file helpers, trash moves, and advanced composition helpers.
+- Added OpenClaw bypass-parity coverage, API coverage, a benchmark workflow, docs site generation, security docs, and coverage CI.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 openclaw
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,390 @@
+# @openclaw/fs-safe
+
+Capability-style filesystem roots for Node.js apps that handle untrusted relative paths.
+
+Think Go's `os.Root` / `OpenInRoot` or Rust's [`cap-std`](https://github.com/bytecodealliance/cap-std), but for Node. Hand `root()` a trusted directory and you get back a handle whose every method resolves relative paths against it and refuses to escape — through `..`, symlink swaps, hardlink aliases, or TOCTOU rename races between check and use.
+
+```ts
+import { root } from "@openclaw/fs-safe";
+
+const fs = await root("/safe/workspace");
+await fs.write("notes/today.txt", "hello\n");   // ok
+await fs.write("../escape.txt", "x");            // throws FsSafeError("outside-workspace")
+```
+
+That's the whole pitch. `root()` is the product; the rest of the package — JSON stores, atomic writes, secret files, archive extraction, temp workspaces — is supporting cast for the same boundary.
+
+## Why this exists
+
+Most Node code that has to touch caller-controlled paths reaches for:
+
+```ts
+path.resolve(root, input).startsWith(root)
+```
+
+That validates a *string*. It does not pin the file you opened, defend against a symlink retarget between check and use, reject hardlinked aliases of out-of-tree inodes, or verify that a write landed where you intended after a rename. The pieces to do those things exist scattered across the ecosystem — [`write-file-atomic`](https://www.npmjs.com/package/write-file-atomic) for atomic writes, `tar` / `jszip` for archive extraction, various `safefs`-style convenience wrappers — but none of them give you one root handle with traversal-resistant semantics across every operation.
+
+The same idea has landed in other languages. Go [added `os.Root` and `OpenInRoot`](https://go.dev/blog/osroot); Rust has had [`cap-std`](https://github.com/bytecodealliance/cap-std) for years. Node's `fs` is path-string-oriented and exposes flags like `O_NOFOLLOW` but not an ergonomic "operate inside this root" API. `fs-safe` fills that gap.
+
+## Not a sandbox
+
+This is a **library-level guardrail**, not OS-level isolation. It does not replace containers, seccomp, AppArmor, or filesystem permissions. It is for code that already runs with the privileges of its workspace and wants to stop trivial path tricks from escaping it. If your threat model is a hostile process, you need OS isolation; if your threat model is "an agent, plugin, upload handler, or CLI will eventually be tricked into writing somewhere it shouldn't," `fs-safe` catches that.
+
+## Install
+
+```sh
+pnpm add @openclaw/fs-safe
+```
+
+Node 20.11 or newer. Core root/path/json/temp helpers avoid framework dependencies. Archive helpers use optional `jszip` and `tar` dependencies for ZIP/TAR support; installs that omit optional dependencies can still use every non-archive subpath.
+
+On POSIX, `root()` uses one process-global persistent Python helper for the
+fd-relative operations Node does not expose ergonomically (`renameat`,
+`unlinkat`, recursive `mkdirat`-style walks, and parent-fd writes). Configure it
+before first use when you need a strict environment policy:
+
+```ts
+import { configureFsSafePython } from "@openclaw/fs-safe";
+
+configureFsSafePython({ mode: "auto" });    // default: use helper, fall back if unavailable
+configureFsSafePython({ mode: "off" });     // never spawn Python; use Node fallbacks
+configureFsSafePython({ mode: "require" }); // fail closed if helper cannot start
+```
+
+Equivalent env vars: `FS_SAFE_PYTHON_MODE=auto|off|require` and
+`FS_SAFE_PYTHON=/path/to/python3`. Without Python, `fs-safe` keeps lexical and
+canonical root checks, no-follow opens, atomic temp+rename writes, and
+post-write identity verification. What you lose is the strongest POSIX
+fd-relative protection against a same-process-user racer swapping parent
+directories between validation and mutation. Windows already uses the Node
+fallback path. See the [Python helper policy](docs/python-helper.md) for
+deployment guidance.
+
+## Quick start
+
+```ts
+import { root } from "@openclaw/fs-safe";
+
+const fs = await root("/safe/workspace", {
+  hardlinks: "reject",
+  symlinks: "reject",
+  mkdir: true,
+  mode: 0o600,
+});
+
+await fs.write("notes/today.txt", "hello\n");
+const text = await fs.readText("notes/today.txt");
+const config = await fs.readJson("config.json");
+await fs.copyIn("uploads/upload.png", "/tmp/upload.png");
+await fs.move("notes/today.txt", "notes/archive/today.txt", { overwrite: true });
+await fs.remove("notes/archive/today.txt");
+```
+
+`root()` takes the trusted directory; relative paths in subsequent calls are resolved against it. Defaults you pass to `root()` apply to every call below; per-call options override them.
+
+When you need metadata or a `FileHandle`:
+
+```ts
+const { buffer, realPath, stat } = await fs.read("notes/today.txt");
+const opened = await fs.open("notes/today.txt");
+```
+
+`create()` is the don't-clobber variant of `write()` and throws `already-exists` when the target already exists:
+
+```ts
+await fs.create("notes/README.md", "seed\n"); // throws if it already exists
+```
+
+`write()` replaces file contents by default; pass `{ overwrite: false }` or use `create()` when an existing file should be an error. `move()` defaults to no clobber because it can otherwise delete an unrelated target while also consuming the source. Pass `{ overwrite: true }` when replacing the target is intended.
+
+Use `ensureRoot()` when a computed relative directory target resolves to the root itself (`""` or `"."`) and you want the operation to be accepted. `root()` still requires the trusted root directory to already exist.
+
+## Reading
+
+Pick the narrowest read shape that gives you what you need:
+
+```ts
+await fs.readJson("config.json"); // parsed value; validate it at your boundary
+await fs.readText("notes/today.txt");
+await fs.readBytes("image.png");
+await fs.read("notes/today.txt"); // { buffer, realPath, stat }
+const opened = await fs.open("large.log"); // FileHandle for streaming
+```
+
+For streams, use `open()` and the returned `FileHandle`:
+
+```ts
+await using opened = await fs.open("large.log");
+{
+  const stream = opened.handle.createReadStream();
+  // consume stream
+}
+```
+
+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.
+
+When you need a writable `FileHandle`, use `openWritable()` and prefer `await using` for cleanup:
+
+```ts
+await using opened = await fs.openWritable("logs/current.log", { writeMode: "append" });
+{
+  await opened.handle.appendFile("line\n");
+}
+```
+
+`nonBlockingRead` is the only I/O scheduling knob in `RootDefaults`; it applies to read/open operations because it changes how file descriptors are opened. Filesystem safety policy remains explicit through `hardlinks` and `symlinks`.
+
+`stat()`, `exists()`, and `list()` are boundary-checked, but they cannot pin a later operation to the same filesystem object. Use `read()`, `open()`, `write()`, `create()`, `copyIn()`, `move()`, or `remove()` for operations that must be race-resistant at the point of use.
+
+## Subpaths
+
+The main entry point is intentionally small: `root`, the root option/result
+types, and `FsSafeError`. Use subpaths for everything else. Low-level helpers
+that OpenClaw needs to compose higher-level APIs are grouped under
+`@openclaw/fs-safe/advanced` instead of being separate public leaf contracts.
+
+| Subpath | Contents |
+|---|---|
+| `@openclaw/fs-safe/root` | `root()`, `Root`, `RootDefaults`, related types |
+| `@openclaw/fs-safe/config` | process-global Python helper configuration |
+| `@openclaw/fs-safe/path` | canonical path checks: `isPathInside`, `safeRealpathSync`, `isNotFoundPathError`, `isSymlinkOpenError` |
+| `@openclaw/fs-safe/json` | `tryReadJson`, `readJson`, `readJsonIfExists`, `writeJson`, sync variants |
+| `@openclaw/fs-safe/store` | `fileStore`, `fileStoreSync`, and `jsonStore` |
+| `@openclaw/fs-safe/secret` | strict and try-style secret file read/write helpers |
+| `@openclaw/fs-safe/atomic` | `replaceFileAtomic`, `replaceFileAtomicSync`, `replaceDirectoryAtomic`, `movePathWithCopyFallback` |
+| `@openclaw/fs-safe/temp` | `tempWorkspace`, `tempWorkspaceSync`, `withTempWorkspace`, `resolveSecureTempRoot` |
+| `@openclaw/fs-safe/secure-file` | fd-pinned absolute file reads with owner, mode, ACL, trusted-dir, size, and timeout checks |
+| `@openclaw/fs-safe/file-lock` | `acquireFileLock`, `withFileLock`, `createFileLockManager`, and related lock types |
+| `@openclaw/fs-safe/permissions` | POSIX mode and Windows ACL inspection plus remediation formatting helpers |
+| `@openclaw/fs-safe/walk` | budget-bounded directory walking with symlink policy, filters, and truncation accounting; not root-bounded |
+| `@openclaw/fs-safe/archive` | `extractArchive`, `resolveArchiveKind`, `ArchiveLimitError`, preflight helpers |
+| `@openclaw/fs-safe/advanced` | lower-level composition helpers such as path scopes, root-file open, install paths, 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`, `FsSafeErrorCode` |
+| `@openclaw/fs-safe/types` | shared types: `DirEntry`, `PathStat`, … |
+| `@openclaw/fs-safe/test-hooks` | hooks the test suite uses to inject races; only active under `NODE_ENV=test` |
+
+## Failure semantics in the name
+
+When two helpers behave differently on the same input, the difference is in the name, not the docs.
+
+```ts
+import { readJson, tryReadJson } from "@openclaw/fs-safe/json";
+
+await tryReadJson("./config.json"); // returns null on missing or invalid
+await readJson("./manifest.json");  // throws on missing or invalid
+```
+
+## Atomic writes
+
+`replaceFileAtomic()` writes a sibling temp file, optionally fsyncs it, and renames it over the destination. Mode preservation, rename retry / copy fallback on `EPERM`, parent-directory fsync, and a `beforeRename` hook for backup or observer flows are all opt-in.
+
+```ts
+import { replaceFileAtomic } from "@openclaw/fs-safe/atomic";
+
+await replaceFileAtomic({
+  filePath: "/safe/workspace/state.json",
+  content: JSON.stringify(state, null, 2),
+  mode: 0o600,
+  syncTempFile: true,
+  syncParentDir: true,
+});
+```
+
+`replaceFileAtomicSync()` covers the synchronous case with the same options shape. Both accept an injectable `fileSystem` for tests.
+
+## Stores
+
+Use `fileStore().json()` for small state files that need explicit fallback
+reads, atomic writes, and optional sidecar locking around read-modify-write
+updates:
+
+```ts
+import { fileStore } from "@openclaw/fs-safe/store";
+
+const files = fileStore({ rootDir: "/safe/workspace/state", private: true });
+const store = files.json("settings.json", { lock: true });
+
+await store.updateOr({ enabled: false }, (current) => ({ ...current, enabled: true }));
+```
+
+`jsonStore({ filePath })` is the absolute-path convenience wrapper for the same
+primitive.
+
+Use `update()` when missing state is part of your model; use `updateOr()` for
+the common merge-into-defaults case. Standalone helpers use options bags
+because they do not carry a bound root and often need multiple authority, path,
+and policy knobs.
+
+Use `fileStore()` for cache/blob/media-style directories where callers
+need safe relative paths, size limits, atomic replacement, stream writes, and
+TTL cleanup behind one root. Pass `private: true` for credentials, auth
+profiles, tokens, and per-agent private state; private mode keeps the same
+store shape while routing writes through the secret-file atomic path.
+
+```ts
+import { fileStore } from "@openclaw/fs-safe/store";
+
+const media = fileStore({
+  rootDir: "/safe/workspace/media",
+  maxBytes: 5 * 1024 * 1024,
+  mode: 0o600,
+});
+
+await media.write("inbound/photo.jpg", bytes);
+await media.writeJson("state/photo.json", { id: "photo" });
+const cached = await media.readJsonIfExists("state/photo.json");
+const opened = await media.open("inbound/photo.jpg");
+await media.pruneExpired({ ttlMs: 10 * 60 * 1000, recursive: true });
+```
+
+`tempWorkspace()` also exposes `writeText()`, `writeJson()`, and `copyIn()` for
+single-file scratch workflows without hand-rolled path joins.
+
+`tempFile()` is the smaller one-file temp helper. It is intentionally an
+advanced primitive: use `tempWorkspace()` for the stable temp surface and reach
+for `tempFile()` only when you need a raw file target.
+
+```ts
+import { tempFile } from "@openclaw/fs-safe/advanced";
+
+await using target = await tempFile({ prefix: "download", fileName: "payload.bin" });
+await fs.promises.writeFile(target.path, bytes);
+const checksumPath = target.file("payload.sha256");
+```
+
+## Secure absolute file reads
+
+Use `readSecureFile()` when the caller gives you an absolute credential path
+instead of a root-relative workspace path. It opens the file first, validates the
+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.
+
+```ts
+import { readSecureFile } from "@openclaw/fs-safe/secure-file";
+
+const { buffer } = await readSecureFile({
+  filePath: "/var/lib/app/token",
+  label: "auth token",
+  trust: { trustedDirs: ["/var/lib/app"] },
+  io: { maxBytes: 16 * 1024, timeoutMs: 5_000 },
+});
+```
+
+Use `permissions: { allowInsecure: true }` only for migration or explicit local-development
+flows where a warning is preferable to refusing the file.
+
+## Directory walking
+
+`walkDirectory()` and `walkDirectorySync()` replace ad-hoc recursive
+`readdir()` loops with entry and depth budgets, a symlink policy, and stable
+relative paths.
+
+```ts
+import { walkDirectory } from "@openclaw/fs-safe/walk";
+
+const scan = await walkDirectory("/safe/workspace", {
+  maxDepth: 4,
+  maxEntries: 10_000,
+  symlinks: "skip",
+  include: (entry) => entry.kind === "file",
+});
+
+for (const file of scan.entries) {
+  console.log(file.relativePath);
+}
+```
+
+Check `scan.truncated` before treating the result as complete.
+
+## Archive extraction
+
+`extractArchive()` handles ZIP and TAR behind one API, with traversal checks, blocked-link-type rejection, and entry-count and byte budgets.
+
+```ts
+import { extractArchive, resolveArchiveKind } from "@openclaw/fs-safe/archive";
+
+const kind = resolveArchiveKind(uploadPath);
+if (!kind) throw new Error(`unsupported archive: ${uploadPath}`);
+
+await extractArchive({
+  archivePath: uploadPath,
+  destDir: "/safe/workspace/plugin",
+  kind,
+  timeoutMs: 15_000,
+  limits: {
+    maxArchiveBytes: 256 * 1024 * 1024,
+    maxEntries: 50_000,
+    maxExtractedBytes: 512 * 1024 * 1024,
+    maxEntryBytes: 256 * 1024 * 1024,
+  },
+});
+```
+
+Extraction stages into a private directory and merges through the same safe-open boundary used by direct writes, so a symlinked entry can't trick the merge into following an out-of-tree path.
+
+## Advanced path scopes
+
+For code that already has a trusted absolute path and wants lower-level boundary
+validation without going through `root()`:
+
+```ts
+import { pathScope } from "@openclaw/fs-safe/advanced";
+
+const uploads = pathScope("/safe/uploads", { label: "uploads directory" });
+const files = await uploads.files(["photo.jpg"]);
+const target = await uploads.writable("report.pdf");
+```
+
+## Errors
+
+Every failure surfaces as an `FsSafeError` with a closed `code` union you can branch on:
+
+```ts
+import { FsSafeError } from "@openclaw/fs-safe/errors";
+
+try {
+  await fs.write("../escape.txt", "x");
+} catch (err) {
+  if (err instanceof FsSafeError && err.code === "outside-workspace") {
+    // handle
+  }
+  throw err;
+}
+```
+
+Codes are grouped by category:
+
+```ts
+if (err instanceof FsSafeError) {
+  if (err.category === "policy") {
+    // Unsafe caller input or filesystem state.
+  } else {
+    // Operational problem such as helper startup, timeout, or unverifiable permissions.
+  }
+}
+```
+
+Current `FsSafeErrorCode` values are `already-exists`, `hardlink`, `helper-failed`, `helper-unavailable`, `invalid-path`, `insecure-permissions`, `not-empty`, `not-file`, `not-found`, `not-owned`, `not-removable`, `outside-workspace`, `path-alias`, `path-mismatch`, `permission-unverified`, `symlink`, `timeout`, `too-large`, and `unsupported-platform`.
+
+## Safety model
+
+- root-bounded APIs resolve paths against a configured root and reject canonical escapes
+- reads open with `O_NOFOLLOW` where available, then verify fd identity matches the path identity before returning the buffer or handle
+- writes use pinned parent-directory helpers and atomic replacement on POSIX, with verified post-write identity
+- `remove`, `mkdir`, `move`, `stat`, `list`, and parent-fd writes use one persistent fd-relative Python helper on POSIX, with Node fallbacks when the helper is disabled or unavailable
+- archive extraction stages into a private directory and merges through the same boundary checks used by direct writes
+
+## Limitations
+
+- Windows uses the safest Node-level behavior available; some fd-relative POSIX hardening is unavailable there.
+- Hardlink rejection depends on platform metadata. Treat it as defense-in-depth, not authorization.
+- `fs-safe` does not validate file contents or archive payload semantics beyond filesystem safety constraints. Schemas, signatures, and authorization belong in the layer above.
+
+## License
+
+MIT.

package/SECURITY.md

@@ -0,0 +1,12 @@
+# Security Policy
+
+`@openclaw/fs-safe` is a filesystem-safety library, so potential boundary bypasses should be reported privately first.
+
+Email security reports to Peter Steinberger at `steipete@gmail.com` with:
+
+- affected version or commit
+- platform and filesystem details
+- minimal reproduction steps
+- expected impact
+
+Please do not open a public issue for traversal, symlink, hardlink, archive extraction, or credential-file bugs until we have coordinated disclosure.

package/dist/absolute-path.d.ts

@@ -0,0 +1,19 @@
+export type AbsolutePathSymlinkPolicy = "reject" | "follow";
+export type ResolvedAbsolutePath = {
+    path: string;
+    canonicalPath: string;
+};
+export type ResolvedWritableAbsolutePath = ResolvedAbsolutePath & {
+    parentDir: string;
+    parentExists: boolean;
+};
+export declare function assertAbsolutePathInput(filePath: string): string;
+export declare function findExistingAncestor(filePath: string): Promise<string | null>;
+export declare function canonicalPathFromExistingAncestor(filePath: string): Promise<string>;
+export declare function resolveAbsolutePathForRead(filePath: string, options?: {
+    symlinks?: AbsolutePathSymlinkPolicy;
+}): Promise<ResolvedAbsolutePath>;
+export declare function resolveAbsolutePathForWrite(filePath: string, options?: {
+    symlinks?: AbsolutePathSymlinkPolicy;
+}): Promise<ResolvedWritableAbsolutePath>;
+//# sourceMappingURL=absolute-path.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"absolute-path.d.ts","sourceRoot":"","sources":["../src/absolute-path.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,yBAAyB,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE5D,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,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAWhE;AAWD,wBAAsB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAiBnF;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,CAe/B;AAED,wBAAsB,2BAA2B,CAC/C,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,yBAAyB,CAAA;CAAO,GACrD,OAAO,CAAC,4BAA4B,CAAC,CAsBvC"}

package/dist/absolute-path.js

@@ -0,0 +1,98 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { FsSafeError } from "./errors.js";
+export function assertAbsolutePathInput(filePath) {
+    if (!filePath) {
+        throw new FsSafeError("invalid-path", "path is required");
+    }
+    if (filePath.includes("\0")) {
+        throw new FsSafeError("invalid-path", "path must not contain NUL bytes");
+    }
+    if (!path.isAbsolute(filePath)) {
+        throw new FsSafeError("invalid-path", "path must be absolute");
+    }
+    return path.normalize(filePath);
+}
+async function pathExists(filePath) {
+    try {
+        await fs.access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function findExistingAncestor(filePath) {
+    let current = path.resolve(filePath);
+    while (true) {
+        try {
+            await fs.lstat(current);
+            return current;
+        }
+        catch (err) {
+            if (err.code !== "ENOENT") {
+                throw err;
+            }
+        }
+        const parent = path.dirname(current);
+        if (parent === current) {
+            return null;
+        }
+        current = parent;
+    }
+}
+export async function canonicalPathFromExistingAncestor(filePath) {
+    const ancestor = await findExistingAncestor(filePath);
+    if (!ancestor) {
+        return path.resolve(filePath);
+    }
+    let canonicalAncestor = ancestor;
+    try {
+        canonicalAncestor = await fs.realpath(ancestor);
+    }
+    catch {
+        // Keep lexical path when the existing ancestor cannot be canonicalized.
+    }
+    const relative = path.relative(ancestor, filePath);
+    return relative ? path.join(canonicalAncestor, relative) : canonicalAncestor;
+}
+export async function resolveAbsolutePathForRead(filePath, options = {}) {
+    const normalized = assertAbsolutePathInput(filePath);
+    let canonicalPath;
+    try {
+        canonicalPath = await fs.realpath(normalized);
+    }
+    catch (err) {
+        if (err.code === "ENOENT") {
+            throw new FsSafeError("not-found", "path not found", { cause: err });
+        }
+        throw err;
+    }
+    if ((options.symlinks ?? "reject") === "reject" && canonicalPath !== normalized) {
+        throw new FsSafeError("symlink", "path traverses a symlink", { cause: { canonicalPath } });
+    }
+    return { path: normalized, canonicalPath };
+}
+export async function resolveAbsolutePathForWrite(filePath, options = {}) {
+    const normalized = assertAbsolutePathInput(filePath);
+    const parentDir = path.dirname(normalized);
+    const parentExists = await pathExists(parentDir);
+    if ((options.symlinks ?? "reject") === "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 },
+                });
+            }
+        }
+    }
+    return {
+        path: normalized,
+        canonicalPath: await canonicalPathFromExistingAncestor(normalized),
+        parentDir,
+        parentExists,
+    };
+}

package/dist/advanced.d.ts

@@ -0,0 +1,22 @@
+export { createAsyncLock } from "./async-lock.js";
+export { assertAbsolutePathInput, canonicalPathFromExistingAncestor, findExistingAncestor, resolveAbsolutePathForRead, resolveAbsolutePathForWrite, type AbsolutePathSymlinkPolicy, type ResolvedAbsolutePath, type ResolvedWritableAbsolutePath, } from "./absolute-path.js";
+export { sameFileIdentity, type FileIdentityStat } from "./file-identity.js";
+export { sanitizeUntrustedFileName } from "./filename.js";
+export { pathExists, pathExistsSync } from "./fs.js";
+export { resolveLocalPathFromRootsSync, readLocalFileFromRoots, type LocalRootsInputOptions, type LocalRootsPathResult, type LocalRootsReadResult, type ReadLocalFileFromRootsOptions, type ResolveLocalPathFromRootsSyncOptions, } from "./local-roots.js";
+export { assertNoWindowsNetworkPath, basenameFromMediaSource, hasEncodedFileUrlSeparator, isWindowsDriveLetterPath, isWindowsNetworkPath, safeFileURLToPath, trySafeFileURLToPath, } from "./local-file-access.js";
+export { formatPosixMode } from "./mode.js";
+export { assertNoHardlinkedFinalPath, assertNoPathAliasEscape, PATH_ALIAS_POLICIES, type PathAliasPolicy, } from "./path-policy.js";
+export { openRootFile, openRootFileSync, canUseRootFileOpen, matchRootFileOpenFailure, type OpenRootFileParams, type OpenRootFileSyncParams, type RootFileOpenFailure, type RootFileOpenFailureReason, type RootFileOpenResult, } from "./root-file.js";
+export { ROOT_PATH_ALIAS_POLICIES, resolvePathViaExistingAncestorSync, resolveRootPath, resolveRootPathSync, type ResolvedRootPath, type RootPathAliasPolicy, } from "./root-path.js";
+export { ensureDirectoryWithinRoot, pathScope, resolveExistingPathsWithinRoot, resolvePathWithinRoot, resolvePathsWithinRoot, resolveStrictExistingPathsWithinRoot, resolveWritablePathWithinRoot, type PathScope, type PathScopeOptions, type PathScopeResolveOptions, } from "./root-paths.js";
+export { safeDirName, safePathSegmentHashed, resolveSafeInstallDir, assertCanonicalPathWithinBase, } from "./install-path.js";
+export { assertNoSymlinkParents, assertNoSymlinkParentsSync, type AssertNoSymlinkParentsOptions, } from "./symlink-parents.js";
+export { movePathToTrash, type MovePathToTrashOptions } from "./trash.js";
+export { withTimeout } from "./timing.js";
+export { resolveHomeRelativePath } from "./home-dir.js";
+export { appendRegularFile, appendRegularFileSync, readRegularFile, readRegularFileSync, resolveRegularFileAppendFlags, statRegularFile, statRegularFileSync, type AppendRegularFileOptions, type RegularFileStatResult, } from "./regular-file.js";
+export { buildRandomTempFilePath, sanitizeTempFileName, type TempFile, tempFile, withTempFile, } from "./temp-target.js";
+export { writeSiblingTempFile, writeViaSiblingTempPath, type WriteSiblingTempFileOptions, type WriteSiblingTempFileResult, } from "./sibling-temp.js";
+export { createIcaclsResetCommand, formatIcaclsResetCommand, formatWindowsAclSummary, inspectWindowsAcl, parseIcaclsOutput, resolveWindowsUserPrincipal, summarizeWindowsAcl, type IcaclsResetCommandOptions, type PermissionExec, type WindowsAclEntry, type WindowsAclSummary, } from "./permissions.js";
+//# sourceMappingURL=advanced.d.ts.map

package/dist/advanced.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"advanced.d.ts","sourceRoot":"","sources":["../src/advanced.ts"],"names":[],"mappings":"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"}

package/dist/advanced.js

@@ -0,0 +1,24 @@
+// Advanced composition surface. These exports are less stable than the focused
+// public subpaths; prefer root/json/store/temp/archive unless you are building a
+// higher-level primitive.
+export { createAsyncLock } from "./async-lock.js";
+export { assertAbsolutePathInput, canonicalPathFromExistingAncestor, findExistingAncestor, resolveAbsolutePathForRead, resolveAbsolutePathForWrite, } from "./absolute-path.js";
+export { sameFileIdentity } from "./file-identity.js";
+export { sanitizeUntrustedFileName } from "./filename.js";
+export { pathExists, pathExistsSync } from "./fs.js";
+export { resolveLocalPathFromRootsSync, readLocalFileFromRoots, } from "./local-roots.js";
+export { assertNoWindowsNetworkPath, basenameFromMediaSource, hasEncodedFileUrlSeparator, isWindowsDriveLetterPath, isWindowsNetworkPath, safeFileURLToPath, trySafeFileURLToPath, } from "./local-file-access.js";
+export { formatPosixMode } from "./mode.js";
+export { assertNoHardlinkedFinalPath, assertNoPathAliasEscape, PATH_ALIAS_POLICIES, } from "./path-policy.js";
+export { openRootFile, openRootFileSync, canUseRootFileOpen, matchRootFileOpenFailure, } from "./root-file.js";
+export { ROOT_PATH_ALIAS_POLICIES, resolvePathViaExistingAncestorSync, resolveRootPath, resolveRootPathSync, } from "./root-path.js";
+export { ensureDirectoryWithinRoot, pathScope, resolveExistingPathsWithinRoot, resolvePathWithinRoot, resolvePathsWithinRoot, resolveStrictExistingPathsWithinRoot, resolveWritablePathWithinRoot, } from "./root-paths.js";
+export { safeDirName, safePathSegmentHashed, resolveSafeInstallDir, assertCanonicalPathWithinBase, } from "./install-path.js";
+export { assertNoSymlinkParents, assertNoSymlinkParentsSync, } from "./symlink-parents.js";
+export { movePathToTrash } from "./trash.js";
+export { withTimeout } from "./timing.js";
+export { resolveHomeRelativePath } from "./home-dir.js";
+export { appendRegularFile, appendRegularFileSync, readRegularFile, readRegularFileSync, resolveRegularFileAppendFlags, statRegularFile, statRegularFileSync, } from "./regular-file.js";
+export { buildRandomTempFilePath, sanitizeTempFileName, tempFile, withTempFile, } from "./temp-target.js";
+export { writeSiblingTempFile, writeViaSiblingTempPath, } from "./sibling-temp.js";
+export { createIcaclsResetCommand, formatIcaclsResetCommand, formatWindowsAclSummary, inspectWindowsAcl, parseIcaclsOutput, resolveWindowsUserPrincipal, summarizeWindowsAcl, } from "./permissions.js";

package/dist/archive-entry.d.ts

@@ -0,0 +1,13 @@
+export declare function isWindowsDrivePath(value: string): boolean;
+export declare function normalizeArchiveEntryPath(raw: string): string;
+export declare function validateArchiveEntryPath(entryPath: string, params?: {
+    escapeLabel?: string;
+}): void;
+export declare function stripArchivePath(entryPath: string, stripComponents: number): string | null;
+export declare function resolveArchiveOutputPath(params: {
+    rootDir: string;
+    relPath: string;
+    originalPath: string;
+    escapeLabel?: string;
+}): string;
+//# sourceMappingURL=archive-entry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"archive-entry.d.ts","sourceRoot":"","sources":["../src/archive-entry.ts"],"names":[],"mappings":"AAGA,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEzD;AAED,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE7D;AAED,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE;IAAE,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,GAChC,IAAI,CAeN;AAED,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAc1F;AAED,wBAAgB,wBAAwB,CAAC,MAAM,EAAE;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,GAAG,MAAM,CAQT"}