@openclaw/openshell-sandbox 2026.9.2 → 2026.9.4

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

@@ -0,0 +1,196 @@
+---
+title: Native architecture
+description: "The platform-specific native bindings, fd-relative beneath model, platform mechanisms, loader security, and JavaScript fallback contract."
+---
+
+# Native architecture
+
+`@openclaw/fs-safe` uses native bindings that supply mechanisms Node does
+not expose directly. The Rust layer is deliberately not a second policy engine.
+TypeScript owns trusted-root selection, path validation, archive filtering,
+budgets, modes, identity fencing, cleanup decisions, and error normalization.
+Rust receives already-decided relative operations and performs the smallest
+platform syscall sequence that can preserve the boundary.
+
+Every operation that has an equivalent safe Node implementation keeps that
+guarded JavaScript path. Native loading is lazy; installs do not compile Rust,
+run postinstall code, or fetch binaries at runtime. Seven exact-version optional
+packages are filtered by OS, CPU, and Linux libc, so an installation receives
+only its matching prebuilt binding.
+Native-only formats and creation-time Windows DACL guarantees fail explicitly
+instead of substituting a weaker implementation.
+
+## The beneath model
+
+A trusted directory descriptor is the capability. Native operations accept
+that descriptor plus a validated relative path and never reconstruct authority
+from a process working directory. Newly created files use exclusive creation,
+and TypeScript compares descriptor, pathname, and expected identities before
+accepting results.
+
+Conceptually, a caller grants authority to an already-open root—not to a path
+string that can be reinterpreted later:
+
+```text
+validated Root handle
+  └─ relative components (untrusted)
+       └─ open/link/mkdir beneath the handle
+            └─ compare descriptor + pathname + expected identity
+```
+
+The TypeScript layer validates and decides. The native layer never decides
+whether a path, archive entry, mode, owner, or cleanup policy is acceptable.
+
+- Linux uses `openat2(RESOLVE_BENEATH | RESOLVE_NO_MAGICLINKS)`, fd-relative
+  `mkdirat`/`linkat`/`renameat`/`renameat2`, `FICLONE`, and `copy_file_range`.
+- macOS 15.4 and newer first use `openat(O_RESOLVE_BENEATH)`; older kernels walk
+  components with `openat(O_NOFOLLOW)` and restart in-root symlinks from the
+  pinned root. Both routes apply an `F_GETPATH` post-open containment detector,
+  but directory rename races mean the result remains `best-effort`, not
+  race-atomic. macOS uses `renameatx_np(RENAME_EXCL)` and permits
+  `fclonefileat` in an owned, non-shared parent. The clone is normalized inside
+  a private staging directory: flags, ACLs, extended attributes, and broad mode
+  bits are cleared before no-replace publication.
+- Windows uses handle-relative `NtCreateFile` with `OBJ_DONT_REPARSE` and
+  `FILE_OPEN_REPARSE_POINT`, then explicitly rejects reparse points. Rename and
+  hardlink operations stay rooted in already-open handles. Owner/DACL reads
+  use `GetSecurityInfo`; private directories receive their protected DACL in
+  the `CreateDirectoryW` call itself.
+
+## Archives
+
+Rust streams ZIP and TAR payloads, including gzip, zstd, and bzip2. It first
+returns a bounded manifest. TypeScript applies the shared path, filter, strip,
+mode, and byte policies and returns an index-bound extraction plan. Rust then
+creates only those planned entries beneath a private staging descriptor.
+
+The `fs-safe-archive-core` Rust workspace crate owns TAR framing, paths, types,
+mode decoding, GNU metadata, and byte-counted local PAX records. The native
+binding and bundled WASM module compile the same source. No `tar::Archive` or
+Node TAR parser reinterprets admitted identities or sizes. Executors replay
+admitted payload ranges after complete bounded admission; native writes retain
+the platform's descriptor-relative primitives, while fallback writes retain
+the guarded Node staging/publication boundary. ZIP behavior is unchanged.
+`maxMetaEntryBytes` bounds bodies before allocation; unsupported global/old
+metadata and sparse forms fail closed. See [bounded local PAX support](archive.md#bounded-local-pax-support).
+
+Every raw pass receives only TypeScript's resolved `maxEntries`,
+`maxMetaEntryBytes`, and `maxDecodedBytes`. Shared resolution caps metadata and
+decoded byte fields at JavaScript's safe-integer maximum and entry counts at
+`2^32 - 1` before backend selection. Large finite limits remain accepted;
+native conversion mirrors those caps and rejects malformed non-finite or
+negative direct-call values before casting. Logical member headers count
+before filtering/stripping; metadata records do not. `maxEntryBytes` and
+`maxExtractedBytes` remain exclusively in TypeScript's accepted-plan builder,
+after strip/filter policy, and are absent from the raw meter's interface.
+Bounded reads use the default count/metadata/decoded bounds; public `maxBytes`
+bounds only the requested output. TypeScript derives the internal decoded cap
+by safely adding `maxExtractedBytes` and `maxArchiveBytes`, clamped to the safe
+integer maximum. Every native pass receives that same cap and charges headers,
+metadata, bodies, padding, EOF blocks, and trailing zeros. It rejects overflow
+with `archive-decoded-size-exceeds-limit`; no ratio policy is implied.
+Extraction and entry reads drain the metered reader through physical EOF after
+admitted-range replay. Trailing framing or decoded-limit failures propagate before
+directory modes are finalized, staging is published, or selected bytes return.
+Native gzip uses the existing flate2 member decoder with an explicit bounded
+member/padding transition; JavaScript retains Node gunzip and validates its
+unconsumed compressed suffix. Only all-zero physical padding after a complete
+validated trailer is accepted, still within the original archive-byte budget.
+Native reads stop at framing boundaries so a rejected header does not request
+its body from the decoder; codec buffering can still read ahead internally.
+Inspection finishes the complete bounded framing pass before returning its manifest. Directory
+and link bodies, missing two-block EOF, and nonzero trailers reject on both
+backends, as detailed in [raw TAR framing](archive.md#raw-tar-framing). Raw and
+padded sizes above JavaScript's safe-integer maximum reject as invalid framing
+before applying member budgets, including when local PAX overrides the size.
+
+## Publication and hashing
+
+Exclusive publication tries a hardlink, then a copy-on-write clone, Linux
+`copy_file_range`, and finally the existing asynchronous JavaScript byte loop.
+All routes preserve `wx` semantics and the same source/target identity and
+SHA-256 fencing. Native hashing and Linux whole-file copying run on N-API async
+workers rather than the JavaScript event loop.
+
+## Mode semantics
+
+| Mode | Native loading | Fallback |
+|---|---|---|
+| `auto` | Try once, cache the result | Use guarded JavaScript when unavailable |
+| `require` | Try once, cache the result | Throw `FsSafeError("helper-unavailable")` |
+| `off` | Never attempt a binding load | Always use guarded JavaScript |
+
+Features without a safe JavaScript implementation, including zstd/bzip2 TAR,
+Windows private-directory creation, and [retained-directory staging](staged-file.md),
+fail with `helper-unavailable` when native support is absent or off. Staging
+is currently Linux/macOS only and rejects Windows with `unsupported-platform`.
+
+The staged-file owner also serves POSIX native pinned writes, including streaming.
+Unpublished files remain at `0600`; requested modes are applied through the
+owned file descriptor only after rename and published-entry identity validation.
+Post-rename chmod or sync failures retain the publication receipt and final name.
+Its direct-child exclusive `openat` hands off the descriptor before any fallible
+post-open checks; non-following `statat` compares against that descriptor with
+exact native identities, and cleanup uses `unlinkat` in the retained parent.
+The separate checks and unlink are not atomic conditional deletion. Windows
+pinned writes and other fallback-capable APIs retain their existing mechanisms.
+Native writers share root and parent admission, but keep their platform identity
+checks and leaf ownership. POSIX coordinator disposal uses `SuppressedError` to
+retain both an operation failure and a disposal failure, including their receipts;
+stage preparation and cleanup keep their documented error mappings.
+Root replacement verification borrows the published descriptor after final mode
+application, while a private coordinator retains the staged owner until the
+asynchronous check finishes. The owner never escapes that coordinator; public
+staging methods and receipts expose no descriptor or verification callback.
+Verification failures preserve the published name, and disposal still retains
+both verification and cleanup errors when both fail.
+The private verification channel carries exact bigint identity from the original
+owned descriptor (or the content-accepted FUSE descriptor). Root compares it
+against exact fd and pathname metadata; legacy helper return facts and public
+read metadata behavior are unchanged. Missing Windows pathname identity still
+requires a guarded path reopen and comparison with the original retained file;
+that fallback does not apply to POSIX no-read modes.
+
+## JavaScript fallback guarantees and delta
+
+Public policy does not change with the selected mechanism: traversal and link
+rejection, archive filters/limits/modes, exclusive target creation, source and
+target identity fencing, publication cleanup receipts, and secret/lock policy
+remain TypeScript-owned. What changes is the syscall strength or availability:
+
+| Capability | Native path | Guarded JavaScript path |
+|---|---|---|
+| Root-relative opens/mutations | Descriptor-relative beneath operations. Pinned writes create parents and publish both replacement and no-replace targets relative to open directory descriptors. Linux reports `kernel-atomic`; macOS and Windows report `best-effort`. macOS uses `O_RESOLVE_BENEATH` when available plus an `F_GETPATH` detector, while Windows rejects reparse traversal in the object-manager call. | Reports `best-effort`: component-wise alias checks, no-follow opens where Node exposes them, private temp/rename, and post-operation identity verification. A same-privilege peer can replace a writable parent after a guard assertion but before Node resolves the pathname mutation; the mutation may land outside the intended root before the post-check detects it. |
+| ZIP/TAR/gzip | Rust streaming decode and fd-relative output creation. | Optional JSZip or bundled WASM TAR into guarded private staging, then the same guarded merge policy. |
+| Zstd/bzip2 TAR | Supported. | Unsupported; typed `helper-unavailable`. |
+| Publication copy | Clone, Linux `copy_file_range`, async native SHA-256. | Exclusive `wx` byte loop and Node SHA-256 with the same content/identity fences. |
+| `rename-noreplace` | Atomic platform no-replace rename. | Unsupported; no emulation by check-then-rename. |
+| Windows DACL read | Direct `GetSecurityInfo`; the public facts API exposes ordered basic allow/deny ACE SIDs, masks, and decoded flags without trust policy. | Established .NET/`icacls` inspection fallback for coarse permission checks; raw ACE facts are native-only. |
+| Windows private directory | Creation-time protected DACL. | Unsupported; no weaker pathname-only substitute. |
+
+Use `off` in CI to keep the fallback contract exercised. Use `require` when a
+deployment depends on the stronger mechanism or a native-only feature; do not
+infer native loading from timing.
+
+## Loader security
+
+Importing fs-safe never executes a child process. Linux libc selection uses
+the Node process report, conventional musl library filenames, and the ELF
+`PT_INTERP` field of `process.execPath`. If all probes are inconclusive, the
+loader conservatively attempts the glibc package and lets normal module loading
+fail into `auto` fallback. The loader requires only the package selected from
+the detected target; it never probes unrelated packages, downloads code, or
+runs a postinstall step. A missing or incompatible binary
+silently selects the JavaScript fallback in `auto`, throws typed
+`helper-unavailable` in `require`, and is never inspected in `off`. Tests reject
+`child_process`, `exec`, or `spawn` usage in the loader.
+
+## Related pages
+
+- [Native helper policy](native-helper.md)
+- [Security model](security-model.md)
+- [Archive extraction](archive.md)
+- [Durability](durability.md)
+- [Permissions](permissions.md)
+- [Migrating to 0.5](migrating-to-0.5.md)
+- [Migrating to 0.6](migrating-to-0.6.md)

package/node_modules/@openclaw/fs-safe/docs/output.md

@@ -0,0 +1,139 @@
+# External outputs
+
+`@openclaw/fs-safe/output` covers the case where another library insists on
+writing to an absolute path you give it. Browser downloads, renderers, media
+tools, and native libraries often have this shape:
+
+```ts
+import { writeExternalFileWithinRoot } from "@openclaw/fs-safe/output";
+
+await writeExternalFileWithinRoot({
+  rootDir: "/srv/workspace/downloads",
+  path: "reports/today.pdf",
+  write: async (filePath) => {
+    await download.saveAs(filePath);
+  },
+});
+```
+
+The external writer receives a staged path instead of the final destination.
+The default private-workspace mode finalizes through `Root.copyIn()`. An
+opt-in sibling mode stages in the destination directory and atomically renames
+the completed file over the target.
+
+## Signature
+
+```ts
+function writeExternalFileWithinRoot<T = void>(
+  options: ExternalFileWriteOptions<T>,
+): Promise<ExternalFileWriteResult<T>>;
+
+type ExternalFileWriteOptions<T = void> = {
+  rootDir: string;
+  path: string; // relative or absolute, but must stay under rootDir
+  write: (filePath: string) => Promise<T>;
+  maxBytes?: number;
+  mode?: number;
+  staging?: "workspace" | "sibling"; // default: "workspace"
+  fallbackFileName?: string;          // safe staged-name fallback
+};
+
+type ExternalFileWriteResult<T = void> = {
+  path: string; // final absolute path under the canonical root
+  result: T;    // value returned by write()
+};
+```
+
+The requested `path` must name a file. Missing destination parents are created
+by the helper because the operation is "produce this output file under the
+root"; callers should choose the filename before calling this API.
+
+`maxBytes` must be a non-negative safe integer or positive `Infinity`; zero is an active cap and `Infinity` disables it. Invalid values reject before the producer or filesystem staging runs.
+
+Use `maxBytes` when the external producer can create arbitrarily large files,
+and `mode` when the finalized file needs a specific POSIX mode. Both staging
+modes enforce them after the producer returns and before committing the target.
+Requested basenames containing C0/C1 controls or Windows-invalid characters go
+through the package's filename sanitizer; `fallbackFileName` supplies the name
+when nothing remains. This removes traversal, device-name, and invalid-character
+hazards but does not trim Windows-normalized trailing dots or spaces; reject or
+rewrite those when cross-platform filename uniqueness matters.
+`staging: "workspace"` passes the sanitized basename to the producer.
+`staging: "sibling"` embeds that basename in its randomized temporary name.
+When the complete temporary component would exceed 255 bytes under NFC or NFD,
+only the embedded tail is shortened, preserving its extension when possible;
+short callback paths remain unchanged. The final target and returned `path` use
+the destination basename, sanitized
+when needed as described above. Guarded temporary files used only inside
+fs-safe have independent names so their length does not grow with the
+destination basename.
+
+## Choosing a staging mode
+
+`staging: "workspace"` is the default. The producer writes in private temp
+storage, then fs-safe copies through the guarded root boundary. Choose it when
+the temp and destination filesystems may differ, or when an externally produced
+partial file must never appear in the destination directory. The final target
+still appears only after guarded finalization.
+
+`staging: "sibling"` gives the producer a randomized temp path in the target
+directory. Choose it only when that directory itself is the approved writable
+boundary and same-filesystem atomic replacement is required. After the callback
+returns, fs-safe pins and validates the staged regular file, rejects hardlinks
+and size-limit violations, applies `mode`, fsyncs it, and atomically renames it
+over the target. Existing files and symlink entries are replaced without
+following their contents or referents. The parent identity is guarded across
+the operation and the parent directory is synchronized best-effort after
+rename. If an error leaves the sibling temp in place and immediate cleanup
+fails, its verified identity remains registered for a best-effort process-exit
+cleanup retry.
+
+Sibling staging shares the [callback sibling owner](temp.md#sibling-temp-writes):
+it checks exact pre-open, descriptor, and current-path identities, retains the
+descriptor through publication, and never chmods or reads a replacement by path.
+Cleanup preserves unverified paths, including partial output when the callback
+throws before admission. Native-off and Windows operation remain supported with
+the platform limits and non-atomic rename/unlink identity checks described there.
+When `mode` is omitted, output-sibling staging preserves the producer's mode.
+
+## Why not pass the final path to the library?
+
+If a target parent can be swapped after validation, handing an external library
+the final path can make the library write outside the intended root before
+fs-safe has a chance to finalize or reject the operation. Workspace staging
+keeps the trust-boundary write inside fs-safe's root-aware copy/atomic-write
+path. Sibling staging intentionally shifts the writable boundary to the
+destination directory, while keeping pathname validation, staged-file identity
+checks, and the final rename under fs-safe's control.
+
+## Browser download example
+
+```ts
+const outputPath = requestedOutputPath || sanitizeBrowserSuggestedName(suggestedFilename);
+
+await writeExternalFileWithinRoot({
+  rootDir: downloadsRoot,
+  path: outputPath,
+  maxBytes: 512 * 1024 * 1024,
+  write: async (filePath) => {
+    await download.saveAs(filePath);
+  },
+});
+```
+
+The chosen path may be absolute if it is already inside `downloadsRoot`, or
+relative to `downloadsRoot`. Traversal, symlink parent escapes, hardlinked final
+targets, over-large staged files, and missing temp files surface as
+`FsSafeError`s.
+
+This helper is not the right fit when the final filename depends on inspecting
+the produced bytes. In that case, write to a private temp workspace, sniff or
+validate the file, choose the final name, then copy or write into the root with
+the normal root APIs.
+
+## See also
+
+- [Root writes](writing.md) — `write`, `copyIn`, `move`, and `mkdir`.
+- [Temp workspaces](temp.md) — private scratch directories for longer workflows.
+- [`pathScope()`](path-scope.md) — validation-only helper when you must pass an
+  absolute path directly to another library.

package/node_modules/@openclaw/fs-safe/docs/path-scope.md

@@ -0,0 +1,159 @@
+# pathScope()
+
+`pathScope()` is an advanced helper with the same boundary semantics as `root()`, but it operates on **absolute paths** the caller already trusts and returns plain `{ ok, path }` results instead of throwing. Use it when you want the boundary check up front before handing an absolute path to another library.
+
+```ts
+import { pathScope } from "@openclaw/fs-safe/advanced";
+
+const uploads = pathScope("/srv/uploads", { label: "uploads directory" });
+
+const photo = uploads.resolve("user/photo.jpg");
+if (!photo.ok) throw new Error(photo.error);
+
+await sharp(photo.path).resize(800).toFile(/* … */);
+```
+
+## When to reach for it
+
+`root()` is the right answer when you want method-style I/O (`fs.write`, `fs.readText`). `pathScope()` is the right answer when:
+
+- You're handing absolute paths to **other libraries** that take absolute path strings (Sharp, FFmpeg, `tar`, native modules) and just want the boundary check up front.
+- You want to validate user-supplied paths in bulk and return a typed `Result` rather than catching exceptions.
+- You want the scope's `label` to appear in the error message: `"Invalid path: must stay within uploads directory"`.
+
+## Signature
+
+```ts
+import type { FsSafeError } from "@openclaw/fs-safe/errors";
+
+function pathScope(rootDir: string, options: PathScopeOptions): PathScope;
+
+type PathScopeOptions = {
+  label: string;          // appears in error messages
+};
+
+type PathScopeResolveOptions = {
+  defaultName?: string;   // used when the requested path is empty
+};
+
+type PathResult = { ok: true; path: string } | { ok: false; error: string };
+type PathsResult = { ok: true; paths: string[] } | { ok: false; error: string };
+// Illustrative result alias, not a named package export.
+type DirectoryResult =
+  | { ok: true; path: string }
+  | { ok: false; error: string; diagnostic?: FsSafeError };
+
+type PathScope = {
+  rootDir: string;
+  label: string;
+  resolve(requestedPath: string, options?: PathScopeResolveOptions): PathResult;
+  resolveAll(requestedPaths: string[]): PathsResult;
+  existing(requestedPaths: string[]): Promise<PathsResult>;
+  files(requestedPaths: string[]): Promise<PathsResult>;
+  writable(requestedPath: string, options?: PathScopeResolveOptions): Promise<PathResult>;
+  ensureDir(requestedPath: string, options?: PathScopeResolveOptions & { mode?: number }): Promise<DirectoryResult>;
+};
+```
+
+## Methods
+
+### `resolve(rel, options?)`
+
+Synchronous, lexical only — no filesystem touch. Resolves the relative path against `rootDir` and verifies the result stays inside the scope. Use when you only need the path string:
+
+```ts
+const r = uploads.resolve("user/photo.jpg");
+if (!r.ok) return reply(400, r.error);
+console.log(r.path); // /srv/uploads/user/photo.jpg
+```
+
+If the requested path is empty, `defaultName` (when set) is used.
+
+### `resolveAll(rels)`
+
+Synchronous bulk resolve. Returns `{ ok: true, paths }` if every input is in scope, or `{ ok: false, error }` on the first failure.
+
+### `existing(rels)`
+
+Async. Like `resolveAll`, but additionally allows trusted absolute paths whose `realpath` is inside the scope. Useful when callers pass either a relative path or an absolute path you've already validated.
+
+### `files(rels)`
+
+Async. Strict variant: every input must already exist as a regular file inside the scope, with `nlink === 1`. Symlinked entries are rejected.
+
+### `writable(rel, options?)`
+
+Async. Resolves a writable target: requires the parent directory to already
+exist canonically inside the scope, refuses targets whose existing inode is a
+symlink or hardlinked, and returns the absolute path to use for the write. Use
+`ensureDir()` first when the parent needs to be created.
+
+```ts
+const t = await uploads.writable("reports/2026/05/report.pdf");
+if (!t.ok) return reply(400, t.error);
+await fs.writeFile(t.path, body);
+```
+
+### `ensureDir(rel, options?)`
+
+Async. `mkdir -p` inside the scope. Walks each segment, refuses any symlink in the path, creates missing directories. Optional `mode` sets the directory mode.
+
+Failures remain nonthrowing results with `error: string`. Policy rejections
+(including traversal, NUL input, symlinks and non-directory segments) omit
+`diagnostic`. Operational failures from `lstat`, `realpath` or `mkdir` include
+an `FsSafeError` with `code: "helper-failed"`, `category: "operational"`, and
+the exact original error in `cause`, including its native `code`, `errno` and
+`syscall` when available. Only `ensureDir()` adds this diagnostic; other scope
+methods retain their existing result shapes.
+
+`error` equals `diagnostic.message` for operational failures, for example
+`"Could not prepare uploads directory: ENAMETOOLONG during lstat"`. Display
+text bounds and escapes the label and native code/syscall, without copying
+the requested path or native error message. Treat the raw cause as sensitive
+local diagnostic data, not as text to return to an untrusted caller. A failure
+can leave already-created parent directories; it does not roll them back or
+retry through an unchecked filesystem path.
+
+```ts
+const dir = await uploads.ensureDir("inbox", { mode: 0o755 });
+if (!dir.ok) {
+  // Pass the cause only to an appropriately restricted local diagnostic sink.
+  if (dir.diagnostic) recordLocalFailure(dir.diagnostic.cause);
+  return reply(dir.diagnostic ? 500 : 400, dir.error);
+}
+```
+
+## Result type vs throwing
+
+`pathScope` returns `{ ok: true, path }` / `{ ok: false, error }` instead of throwing. This makes it pleasant to use at validation boundaries:
+
+```ts
+function handle(req: Req, res: Res) {
+  const r = uploads.resolve(req.body.path);
+  if (!r.ok) return res.status(400).json({ error: r.error });
+  return doWork(r.path);
+}
+```
+
+For exception-flavored APIs, use `root()` instead — it throws `FsSafeError` with a typed `code`.
+
+## Combine with `root()`
+
+A common pattern at the edge of an HTTP handler: validate the input with `pathScope`, do the I/O with `root()`:
+
+```ts
+const uploads = pathScope("/srv/uploads", { label: "uploads" });
+const fs = await root("/srv/uploads", { hardlinks: "reject" });
+
+const r = uploads.resolve(req.body.path);
+if (!r.ok) return reply(400, r.error);
+const rel = path.relative(fs.rootReal, r.path);
+
+const text = await fs.readText(rel);
+```
+
+## See also
+
+- [`root()`](root.md) — method-style boundary that throws on failure.
+- [Path helpers](path.md) — `isPathInside`, `safeRealpathSync`, `isWithinDir` for ad-hoc checks.
+- [Errors](errors.md) — error semantics (note: `pathScope` returns errors, doesn't throw).