@openclaw/openshell-sandbox 2026.9.2 → 2026.9.4

package/node_modules/@openclaw/fs-safe/docs/local-roots.md

@@ -0,0 +1,141 @@
+# Local roots
+
+The local-roots helpers accept a file path plus a list of trusted absolute
+directories and return the first canonical root that contains the file. Use
+them when configuration may name one of several approved media, cache, or
+workspace roots.
+
+```ts
+import {
+  readLocalFileFromRoots,
+  resolveLocalPathFromRootsSync,
+} from "@openclaw/fs-safe/advanced";
+```
+
+## Input shape
+
+Both helpers take one options object. `filePath` may be absolute, home-relative,
+relative to the current working directory, or a local `file://` URL. Relative
+inputs are resolved exactly as Node resolves them; they are not searched as a
+basename under each root.
+
+```ts
+type LocalRootsInputOptions = {
+  filePath: string;
+  roots: readonly string[]; // trusted absolute paths, checked in order
+  label?: string;           // used in validation errors
+};
+```
+
+Roots may use `~` or local `file://` spellings, but each resolved root must be
+absolute. Existing root symlinks are canonicalized before containment is
+checked. Invalid root entries throw `FsSafeError("invalid-path")`; an invalid
+`file://` input throws `Error`. A path that is valid but does not fall inside
+any usable root returns `null`.
+
+## `resolveLocalPathFromRootsSync(options)`
+
+```ts
+type ResolveLocalPathFromRootsSyncOptions = LocalRootsInputOptions & {
+  allowMissing?: boolean; // default false
+  requireFile?: boolean;  // default false
+};
+
+type LocalRootsPathResult = {
+  path: string; // canonical candidate path
+  root: string; // canonical containing root
+};
+```
+
+For an existing upload:
+
+```ts
+import { resolveLocalPathFromRootsSync } from "@openclaw/fs-safe/advanced";
+
+const r = resolveLocalPathFromRootsSync({
+  filePath: "/srv/uploads/photo.jpg",
+  roots: ["/srv/uploads", "/srv/cache"],
+  requireFile: true,
+});
+
+if (!r) throw new Error("photo is outside the configured roots");
+console.log(r.path); // canonical path to photo.jpg
+console.log(r.root); // canonical /srv/uploads
+```
+
+By default the candidate must exist. `allowMissing: true` instead canonicalizes
+the nearest existing ancestor and validates the missing tail, which is useful
+when selecting a future output location. `requireFile: true` rejects existing
+directories and other non-file leaves. A missing suffix begins only at a
+component that does not exist: dangling symlinks, descendants of dangling
+symlinks, and candidates whose existing ancestors cannot be canonicalized are
+rejected rather than treated as safe missing paths.
+
+## `readLocalFileFromRoots(options)`
+
+The asynchronous helper opens the candidate through the matched [`Root`](root.md),
+so no-follow, identity, hardlink, device-path, and byte-limit checks happen at
+the read itself.
+
+```ts
+type ReadLocalFileFromRootsOptions = LocalRootsInputOptions & {
+  hardlinks?: "reject" | "allow";
+  maxBytes?: number;
+  nonBlockingRead?: boolean;
+  symlinks?: "reject" | "follow-within-root";
+};
+
+type LocalRootsReadResult = ReadResult & {
+  root: string; // canonical containing root
+};
+```
+
+```ts
+const r = await readLocalFileFromRoots({
+  filePath: "/srv/uploads/photo.jpg",
+  roots: ["/srv/uploads", "/srv/cache"],
+  maxBytes: 8 * 1024 * 1024,
+});
+if (!r) throw new Error("photo is missing, unreadable, or outside the roots");
+process.stdout.write(r.buffer);
+```
+
+The helper returns `null` when no configured root can be opened or no safe read
+succeeds. This intentionally collapses missing, outside-root, and per-root read
+failures; use a single `Root` directly when the caller must distinguish those
+outcomes. Omitting `maxBytes` preserves `Root`'s 16 MiB default.
+
+## File URL and Windows-path companions
+
+The advanced surface also exports the normalization helpers used around this
+API:
+
+```ts
+import {
+  assertNoWindowsNetworkPath,
+  basenameFromMediaSource,
+  hasEncodedFileUrlSeparator,
+  isWindowsDriveLetterPath,
+  isWindowsNetworkPath,
+  safeFileURLToPath,
+  trySafeFileURLToPath,
+} from "@openclaw/fs-safe/advanced";
+```
+
+- `safeFileURLToPath(fileUrl)` parses a local file URL and refuses remote hosts
+  or paths that decode to Windows network paths.
+- `trySafeFileURLToPath(fileUrl)` returns `undefined` instead of throwing.
+- `isWindowsDriveLetterPath()` and `isWindowsNetworkPath()` classify Windows
+  absolute and network spellings.
+- `assertNoWindowsNetworkPath()` throws for a network path on Windows.
+- `basenameFromMediaSource()` extracts a best-effort filename from a URL, data
+  URI, or path.
+- `hasEncodedFileUrlSeparator()` detects percent-encoded slash or backslash
+  spellings.
+
+## See also
+
+- [`root()`](root.md) — use when one trusted root should preserve individual
+  failure codes.
+- [Path helpers](path.md) — lexical and canonical containment primitives.
+- [`pathScope()`](path-scope.md) — result-shaped single-root validation.

package/node_modules/@openclaw/fs-safe/docs/migrating-to-0.5.md

@@ -0,0 +1,196 @@
+---
+title: Migrating to 0.5
+description: "Ordered checklist for moving a 0.4 consumer from the Python helper to native mode and adopting the 0.5 API contracts."
+---
+
+# Migrating from 0.4 to 0.5
+
+Use this checklist from top to bottom. Version 0.5 replaces the Python worker,
+changes the default archive mode policy, and adds explicit contracts for
+publication, walking, locks, secrets, and native-only features. Nothing in this
+guide requires a Rust toolchain: all supported native binaries are prebuilt.
+Current releases install the matching exact-version optional platform package.
+
+## 1. Update the package and runtime
+
+- Run on Node.js 22 or newer.
+- Update `@openclaw/fs-safe` and regenerate every lock or shrinkwrap file your
+  deployment consumes.
+- Keep optional dependencies enabled if you want JavaScript ZIP/TAR support.
+  Native loading no longer depends on Python. Keep optional dependencies enabled
+  for the matching native package and JavaScript ZIP/TAR decoders. An install
+  that omits them can still import fs-safe, but native-only features and missing
+  JS archive decoders fail with actionable errors.
+
+If you call `resolveRootPath()` or `resolveRootPathSync()` directly, upgrade to
+0.5: versions through 0.4.7 could approve an in-root symlink traversal that
+resolved outside the root. `root()` handles were not affected. See the
+[affected versions and exposure](security-model.md#affected-versions-exposure).
+
+## 2. Replace Python helper configuration
+
+Change startup configuration before the first filesystem operation:
+
+```ts
+import { configureFsSafeNative } from "@openclaw/fs-safe/config";
+
+configureFsSafeNative({ mode: "auto" });
+```
+
+| Remove from 0.4 | Use in 0.5 |
+|---|---|
+| `configureFsSafePython({ mode })` | `configureFsSafeNative({ mode })` |
+| `FS_SAFE_PYTHON_MODE` | `FS_SAFE_NATIVE_MODE` |
+| `OPENCLAW_FS_SAFE_PYTHON_MODE` | `OPENCLAW_FS_SAFE_NATIVE_MODE` |
+| `pythonPath`, `FS_SAFE_PYTHON`, pinned-Python aliases | Nothing; prebuilt native binaries do not use an interpreter |
+
+The old names warn once and map `auto`, `off`, or `require` so a shipped 0.4
+deployment does not silently change policy. Interpreter paths are ignored and
+Python is never spawned. Treat that warning as an upgrade diagnostic, not as a
+second supported helper path.
+
+Choose the production mode deliberately:
+
+- `auto` keeps guarded JavaScript fallbacks when a binding is unavailable.
+- `off` makes fallback testing deterministic.
+- `require` fails with `helper-unavailable` instead of weakening an operation
+  that expected native support.
+
+See [Native helper policy](native-helper.md) and
+[Native architecture](native.md).
+
+## 3. Audit every archive call
+
+The 0.5 default is `entryModes: "clamp"`. Directories become `0o755`; files
+become `0o644` or `0o755` when owner-execute was archived. Set
+`entryModes: "preserve"` explicitly only if your 0.4 consumer intentionally
+relied on archived rwx bits. Setuid, setgid, sticky bits, and archived ownership
+are never restored.
+
+```ts
+await extractArchive({
+  archivePath: uploadPath,
+  destDir: restoreRoot,
+  timeoutMs: 30_000,
+  entryModes: "clamp",
+  entryFilter: (entry) =>
+    entry.path.startsWith("snapshot/cache/") ? "skip" : "extract",
+  onFiltered: "skip-entry",
+  limits: {
+    maxArchiveBytes: 256 * 1024 * 1024,
+    maxEntries: 50_000,
+    maxExtractedBytes: 512 * 1024 * 1024,
+    maxEntryBytes: 256 * 1024 * 1024,
+    maxMetaEntryBytes: 1024 * 1024,
+    maxEntryPathComponents: 64,
+  },
+});
+```
+
+Returning `"skip"` rejects the archive unless `onFiltered: "skip-entry"` is
+explicit. Zstd and bzip2 TAR are native-only; ZIP, TAR, and gzip retain guarded
+JavaScript implementations. Catch `ArchiveLimitError` by its code, including
+`archive-entry-path-components-exceeds-limit` for deep implicit-directory
+attacks. See [Archive extraction](archive.md).
+
+## 4. Pick a publication failure policy
+
+`publishFileExclusive()` never replaces an existing target. Choose a strategy
+and decide what a post-create directory-sync failure means to your application:
+
+```ts
+await publishFileExclusive({
+  sourcePath: stagedArchive,
+  targetPath: finalArchive,
+  strategy: "link-or-copy",
+  onSyncFailure: "preserve",
+});
+```
+
+`rollback` is the default: an unchanged target created by this call is removed
+when directory sync throws. `preserve` keeps a complete but possibly
+non-durable target and reports `cleanup: "preserved"` plus
+`directorySync: { status: "failed", code? }` in the typed error. Backup
+archives commonly need `preserve`; transactional protocols that expose only
+durably committed names usually want `rollback`. See
+[Directory durability](durability.md).
+
+## 5. Replace recursive scans with an explicit walk policy
+
+Use `Root.walk()` for caller-controlled relative paths. Every examined entry
+consumes the budget even when filtered:
+
+```ts
+for await (const entry of workspace.walk("memory", {
+  maxDepth: 12,
+  maxEntries: 50_000,
+  symlinkPolicy: "skip",
+  entryFilter: (entry) =>
+    entry.kind === "directory" && entry.relativePath.endsWith("/.git")
+      ? "skip-subtree"
+      : "include",
+  onDirectoryError: "skip-and-report",
+})) {
+  if (entry.kind === "directory-error") {
+    reportIncompleteSubtree(entry.relativePath, entry.error);
+    continue;
+  }
+  indexEntry(entry);
+}
+```
+
+The default directory-error policy remains `throw`. See
+[Directory walking](walk.md).
+
+## 6. Adopt the focused concurrency and secret APIs
+
+- Use `acquireFileLockSync()` only in synchronous boot or migration code; retry
+  waits block the thread. Request-serving paths should use `withFileLock()`.
+- Remove the `allowReentrant` boolean from async file-lock options. If a logical
+  holder intentionally nests acquisition, pass the same operation-scoped
+  `reentrantOwner` string to each acquisition; different or missing owners
+  contend normally. Never replace the boolean with a process-wide constant.
+  Locked and unlocked `jsonStore` mutations serialize by canonical file path
+  and do not opt into lock reentrancy; nested same-file mutations from an update
+  callback fail with `store-reentrant-update`, so return the complete value from
+  the outer callback instead.
+- Use `createSecretFileAtomic()` for first-writer-wins credentials and catch
+  `secret-exists`; use `writeSecretFileAtomic()` only when replacement is the
+  intended protocol.
+- Async `readSecretFile()` is strict; `tryReadSecretFile()` returns `undefined`
+  only for missing or blank content and still rejects suspicious files.
+- Check `tempWorkspace.cleanup()` results when ownership matters;
+  `identity-mismatch` deliberately preserves a replacement path.
+
+See [File locks](sidecar-lock.md), [Secret files](secret-file.md), and
+[Temp workspaces](temp.md).
+
+## 7. Gate native-only features
+
+`createPrivateDirectory()` is Windows-only and native-only because a pathname
+fallback cannot promise the same creation-time DACL. Zstd/bzip2 extraction and
+`strategy: "rename-noreplace"` are also native-only. Test the unavailable path
+instead of assuming installation always succeeds.
+
+## 8. Run both behavior families in CI
+
+For each consumer workflow that matters:
+
+1. Run once with `FS_SAFE_NATIVE_MODE=auto` on every supported OS.
+2. Run once with `FS_SAFE_NATIVE_MODE=off` to prove the JavaScript fallback.
+3. Run native-required or native-only cases with `FS_SAFE_NATIVE_MODE=require`.
+4. Exercise archive traversal/link/depth limits, publication sync failure, and
+   partial-walk reporting with production-shaped fixtures.
+
+For downstream staging and backup consumers:
+
+- [ ] Replace private whole-file hashing with `sha256File(path | FileHandle)`
+      from `durability`; native mode keeps digest work off the event loop and
+      the JavaScript fallback remains streaming.
+- [ ] If Windows trust policy depends on exact principals, consume
+      `readOwnerAndDacl()` from `permissions`, reject incomplete/null/remote
+      descriptors as your policy requires, skip inherit-only ACEs where
+      appropriate, and apply the application's own SID allowlist.
+
+The [Testing](testing.md) page documents the test hooks and mode setup used by
+fs-safe itself.

package/node_modules/@openclaw/fs-safe/docs/migrating-to-0.6.md

@@ -0,0 +1,43 @@
+---
+title: Migrating to 0.6
+description: "Upgrade checklist for the platform-native package split."
+---
+
+# Migrating from 0.5 to 0.6
+
+Version 0.6 moves native bindings out of the root `@openclaw/fs-safe` tarball
+and into exact-version platform packages. This removes unrelated operating
+system and architecture binaries from each installation.
+
+## Keep optional dependencies enabled for native mode
+
+Package managers select one binding by OS, CPU, and Linux libc. A normal
+install needs no command change:
+
+```bash
+pnpm add @openclaw/fs-safe
+```
+
+If a deployment currently installs 0.5 with `--omit=optional`, `--no-optional`,
+or an equivalent lockfile policy, change that policy before upgrading when it
+uses native mode `require` or any native-only feature. Version 0.5 kept its
+binding in the root tarball; version 0.6 intentionally does not.
+
+Omitting optional dependencies remains supported for fallback-capable APIs in
+`auto` mode. It disables native-only features such as zstd/bzip2 TAR handling,
+retained-directory staging, atomic `rename-noreplace`, and Windows private
+directory creation. Native mode `require` reports `helper-unavailable` when the
+matching package is absent or incompatible.
+
+## Deployment checklist
+
+1. Remove any option or policy that omits optional dependencies when native
+   support is required.
+2. Regenerate every lockfile or shrinkwrap file consumed by deployment.
+3. Verify that the lock contains the matching `@openclaw/fs-safe-*` package.
+4. Run a native-required operation on every deployed OS/libc target.
+5. Keep an `FS_SAFE_NATIVE_MODE=off` lane when the guarded JavaScript fallback
+   is part of the application contract.
+
+No Rust toolchain, postinstall build, or runtime download is introduced. See
+[Native helper policy](native-helper.md) for the exact fallback boundary.

package/node_modules/@openclaw/fs-safe/docs/native-helper.md

@@ -0,0 +1,118 @@
+---
+title: Native helper policy
+description: "How fs-safe loads its platform-specific native filesystem primitives and how auto, require, and off affect guarded fallbacks."
+---
+
+# Native helper policy
+
+`@openclaw/fs-safe` declares seven exact-version optional packages for Linux
+x64/arm64 (glibc or musl), macOS x64/arm64, and Windows x64. Package-manager
+OS, CPU, and libc filters install only the matching package. The loader requires
+that package lazily, without runtime downloads, postinstall scripts, or a
+consumer Rust build.
+
+```ts
+import { configureFsSafeNative } from "@openclaw/fs-safe/config";
+
+configureFsSafeNative({ mode: "auto" });    // default
+configureFsSafeNative({ mode: "off" });     // guarded JavaScript only
+configureFsSafeNative({ mode: "require" }); // fail closed when the binding is unavailable
+```
+
+The equivalent environment variables are `FS_SAFE_NATIVE_MODE` and `OPENCLAW_FS_SAFE_NATIVE_MODE`. Accepted values are `auto`, `off`, `require`, `true`, `false`, `on`, `never`, `required`, `1`, and `0`.
+
+## Modes
+
+| Mode | Behavior |
+|---|---|
+| `auto` | Prefer native primitives when the current platform package loads; otherwise silently use the guarded JavaScript path. |
+| `off` | Do not load a native package. Use the guarded JavaScript path deterministically. |
+| `require` | Throw `FsSafeError("helper-unavailable")` instead of falling back when an operation needs the native binding and it cannot load. |
+
+TAR/gzip in the guarded JavaScript path uses a bundled, import-free WASM build
+of the same Rust parser used by native. `off` still disables native filesystem
+code; it does not disable this portable parser. ZIP fallback still requires
+optional `jszip`, and zstd/bzip2 remain native-only.
+
+Configure the mode once during startup. Loading is lazy and cached; changing from `auto` to `require` after a failed load changes failure policy but does not repeatedly probe the binary.
+
+[`tempWorkspace()` and its scoped/sync variants](temp.md#private-temp-workspaces)
+remain available in every mode. Their default compatible cleanup uses guarded
+JavaScript quarantine when owned native tree removal is unavailable.
+`cleanupSafety: "require-bounded"` instead rejects before child creation unless
+no-replace quarantine plus descriptor-relative owned-tree removal are available.
+On Linux, admission probes the exact `openat2` child-directory flags, including
+`RESOLVE_NO_XDEV`, at runtime. An unavailable or denied probe selects compatible
+JavaScript cleanup even in global `require` mode; `require-bounded` rejects before
+child creation.
+Already-created strict workspaces retain their binding
+and descriptors across later mode changes.
+
+[`stageFileInDirectory()`](staged-file.md) always requires native support on
+Linux/macOS and rejects before creation when off, unavailable, or missing the
+required capability. Windows is unsupported for this lifecycle. This does not
+change the mode policy of existing fallback-capable APIs.
+
+## Native boundary
+
+The native layer exposes policy-free filesystem mechanisms: beneath-root
+open/mkdir/link, replace and no-replace rename, identity reads, archive decode/execution,
+clone/copy/hash workers, and Windows security descriptor calls. The TypeScript
+layer owns policy, retries, filters, budgets, modes, cleanup, error
+normalization, and the decision to fall back.
+
+- Linux uses `openat2` with `RESOLVE_BENEATH | RESOLVE_NO_MAGICLINKS`, `renameat`, and `renameat2(RENAME_NOREPLACE)`. Owned-tree cleanup enumerates and unlinks through retained directory descriptors and rejects device crossings.
+- macOS 15.4 and newer prefer `O_RESOLVE_BENEATH`; older kernels resolve components with `O_NOFOLLOW` and restart in-root symlinks from the pinned root descriptor. Both routes use an `F_GETPATH` post-open escape detector and report `best-effort` because directory rename races are not atomic with that check. Publication uses `renameat` for replacement and `renameatx_np(RENAME_EXCL)` for no-replace; owned-tree cleanup uses descriptor-relative `openat`/`unlinkat`.
+- Windows uses handle-relative `NtCreateFile`, rejects reparse points during root-bounded traversal, uses `FileRenameInfoEx` with replacement selected explicitly by the TypeScript policy layer, and deletes owned trees through exact opened handles with `FileDispositionInfoEx`; symlink/reparse entries in owned trees are removed as leaves and never traversed.
+
+Native primitives back create-only and replacing pinned writes, async sidecar creation,
+guarded publication, archive acceleration, and direct Windows ACL operations.
+Equivalent JavaScript paths remain available for documented fallback-capable
+features. See [Native architecture](native.md#javascript-fallback-guarantees-and-delta)
+for the exact difference.
+
+The guarded JavaScript mutation path is detection-based, not containment-atomic.
+If a same-privilege peer can replace a writable parent after its identity guard
+but before Node resolves a pathname mutation, the mutation can land outside the
+intended root before the post-operation guard throws. Select `require` rather
+than `auto` or `off` when that concurrent attacker is part of the threat model.
+
+`openBeneath()` returns `{ fd, containment }`. `containment` is
+`"kernel-atomic"` for Linux `openat2` and `"best-effort"` for macOS and
+Windows. Public JavaScript root open/read/writable results also expose the
+field and report `"best-effort"`; the label reports mechanism, not policy.
+
+## Migration from the Python helper
+
+Version 0.5 removes the Python worker and interpreter-path selection. The mode
+contract is unchanged, so migrate startup configuration directly:
+
+| Python helper configuration | Native replacement |
+|---|---|
+| `configureFsSafePython({ mode: "auto" })` | `configureFsSafeNative({ mode: "auto" })` |
+| `configureFsSafePython({ mode: "off" })` | `configureFsSafeNative({ mode: "off" })` |
+| `configureFsSafePython({ mode: "require" })` | `configureFsSafeNative({ mode: "require" })` |
+| `FS_SAFE_PYTHON_MODE` | `FS_SAFE_NATIVE_MODE` |
+| `OPENCLAW_FS_SAFE_PYTHON_MODE` | `OPENCLAW_FS_SAFE_NATIVE_MODE` |
+| `pythonPath`, `FS_SAFE_PYTHON`, and the OpenClaw interpreter-path aliases | Remove; prebuilt bindings do not use an interpreter path |
+
+In 0.5, `configureFsSafePython` and the legacy Python environment names
+remain only as an upgrade bridge. On the first config read they emit one
+`DeprecationWarning` with code `FS_SAFE_PYTHON_DEPRECATED`, state the mapped
+native mode, and then apply that mode. A legacy interpreter path without an
+explicit mode maps to `auto` and the path itself is ignored. Native config has
+the normal precedence over legacy environment config.
+
+There is no silent alias and no Python execution fallback. The bridge exists
+only to make shipped 0.4 configuration visible and predictable while the
+consumer performs its 0.5 upgrade.
+
+## Related pages
+
+- [Config](config.md)
+- [Security model](security-model.md)
+- [Writing](writing.md)
+- [File locks](sidecar-lock.md)
+- [Durability](durability.md)
+- [Migrating to 0.5](migrating-to-0.5.md)
+- [Migrating to 0.6](migrating-to-0.6.md)