@openclaw/signal 2026.9.5 → 2026.9.7

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

@@ -0,0 +1,193 @@
+# 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"
+  producerIsolation?: "private-directory"; // opt-in for sibling staging
+  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.
+
+The helper reads each option once before its first asynchronous operation.
+Changing the options object after invocation does not change the selected
+writer, staging mode, isolation, filename fallback, byte limit, or final mode
+for that write. Workspace writers retain the original options object as their
+callback receiver; sibling writers retain the internal staging receiver.
+
+`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 as written or 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.
+
+On Windows, `rootDir` and every target parent reject NTFS alternate-stream and
+directory-index namespace spellings such as `file:stream` and
+`dir::$INDEX_ALLOCATION`. A colon in only the requested basename still follows
+the documented portable filename sanitization above instead of being treated
+as a raw stream path. Ordinary colon-bearing POSIX roots and parents remain
+valid.
+
+## 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. Its internal `tempFile()` does
+not expose `cleanupSafety` through this API and uses compatible cleanup, with
+the final check-to-pathname-recursive-removal gap documented in
+[`tempFile`](temp.md#tempfile).
+
+By default, `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.
+Without producer isolation, 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.
+
+Add `producerIsolation: "private-directory"` to sibling staging when the
+producer can leave partial output before throwing. It receives an initially
+absent file path inside a private child workspace under the target parent, on
+the target filesystem. Directory cleanup ownership is captured before the
+callback. A callback exception triggers owned workspace cleanup, including
+partial output, subject to directory identity checks and I/O failures.
+After success, an available native helper uses guarded no-replace `Root.move`.
+With native mode off, the helper opens and identity-fences the completed regular
+file, creates the randomized sibling through an atomic no-clobber hard link,
+verifies its temporary two-link state, then removes the private name. Windows
+first transfers the pin to an independently verified sibling descriptor so the
+source name can disappear before workspace cleanup, including on runtimes with
+legacy deletion behavior. If that unlink clears the producer's read-only
+attribute, the retained descriptor restores it and the helper verifies mode and
+identity before continuing. This keeps the handoff zero-copy while preserving the
+ordinary retained-descriptor, mode,
+file-sync, and final-rename lifecycle. Escaping symlinks still fail with
+`path-alias`; filesystems without hard-link support fail with
+`helper-unavailable`.
+
+Exact bigint parent and workspace identities are rechecked before moving
+output to the sibling path to reject observed replacements. Cleanup uses the
+compatible [`withTempFile` ownership contract](temp.md#withtempfile); this
+output option does not expose `cleanupSafety: "require-bounded"`. A moved or
+replaced parent or workspace can leave artifacts, and a workspace substituted
+in the final check-to-pathname-recursive-removal gap can redirect traversal.
+The option does not promise cleanup through a retained directory after a
+rename. The existing Windows and JavaScript pathname-guard limitations remain,
+with no additional permissions or durability guarantee. Native-off publication
+is supported only where hard links are available. See the
+[producer-isolation contract](temp.md#sibling-temp-writes)
+for cleanup and pathname-race details. The option affects only `staging: "sibling"`;
+with `staging: "workspace"`, it is redundant and harmless because the producer
+already uses a private workspace. Omitting it leaves both staging defaults
+unchanged.
+
+## 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-case.md

@@ -0,0 +1,64 @@
+# Path case probing
+
+`probePathCaseInsensitiveSync()` observes whether a path's lookup location
+folds ASCII case. It returns `true`, `false`, or `undefined` when the observation
+cannot establish an answer. It does not infer a filesystem property from the
+operating system or cache its result.
+
+```ts
+import { probePathCaseInsensitiveSync } from "@openclaw/fs-safe/advanced";
+
+const insensitive = probePathCaseInsensitiveSync("/srv/data/future.json", {
+  allowTemporaryProbe: false,
+});
+if (insensitive === undefined) {
+  // The application decides how to handle an unavailable observation.
+}
+```
+
+## Lookup location
+
+The input is resolved with Node's `path.resolve()`. Existing targets, including
+directories and final symlinks, are first compared by basename in their parent.
+The probe does not follow a final symlink to decide the target's case behavior.
+Parent aliases are followed. For a missing path, it walks to the nearest existing
+directory whose metadata can be read, without creating the missing directories.
+An unreadable directory listing returns `undefined`.
+
+The probe checks existing directory entries before considering a temporary
+file. Separately listed case variants count as distinct entries even when they
+are hardlinks to the same inode. Identity comparisons retain bigint precision;
+unknown Windows identities do not count as matches. The original entry is
+rechecked after looking up its case variant, so its disappearance or replacement
+invalidates the observation. A detected directory replacement also returns
+`undefined`.
+
+## Temporary probes and cleanup
+
+`allowTemporaryProbe` defaults to `true`. When existing entries give no answer,
+the helper exclusively creates one empty `.fs-safe-case-probe-*` file in the
+selected directory at mode `0o600`. It uses the existing temporary-file owner
+to retain the descriptor and exact cleanup identity. Successful ordinary
+completion removes the probe and closes the descriptor.
+
+Set `allowTemporaryProbe: false` for strictly read-only observation. In that
+mode an empty directory, or one with no useful ASCII-case names, returns
+`undefined` without creating a temporary file. Temporary probing can change
+directory timestamps and trigger filesystem watchers even when cleanup succeeds.
+
+Operational failures, unverified identities, changed entries, and cleanup
+failures return `undefined`. A substituted or hardlinked temporary entry is
+preserved. When cleanup fails operationally, the existing owner retains its
+identity-bound process-exit retry. A creation whose identity cannot be obtained
+may leave an empty file; the helper never guesses cleanup ownership. Therefore
+`undefined` does not promise that no temporary artifact remains.
+
+## Limits
+
+This is a local ASCII-case observation, not a Unicode-normalization test,
+filesystem-wide guarantee, lock, or authorization receipt. Directory enumeration
+and metadata lookups are separate operations. Concurrent changes can invalidate
+or immediately stale a result, and the final identity check and unlink are not
+an atomic conditional deletion. Use temporary probing only where creating a
+temporary file is permitted. The caller retains any admission, serialization,
+fallback, or later mutation policy.

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

@@ -0,0 +1,74 @@
+# Resolving an existing path prefix
+
+`resolvePathPrefixSync()` follows filesystem path components until the first
+missing entry. It returns a canonical existing prefix and the unprocessed
+suffix separately, including dangling symlink targets.
+
+```ts
+import { resolvePathPrefixSync, type ResolvedPathPrefix } from "@openclaw/fs-safe/advanced";
+
+const observed: ResolvedPathPrefix = resolvePathPrefixSync("/srv/data/future/file.json");
+// When /srv/data exists but future does not:
+// observed.existingPath is the canonical spelling of /srv/data.
+// observed.unresolvedSegments is ["future", "file.json"].
+```
+
+The result has three readonly fields:
+
+| Field | Meaning |
+| --- | --- |
+| `absolutePath` | Input anchored to the current directory or Windows drive, with raw path components retained and Windows separators converted to backslashes. |
+| `existingPath` | Existing prefix canonicalized by fs-safe's native-realpath owner. This may be a file when the entire path exists. |
+| `unresolvedSegments` | Components from the first missing entry onward, after expanding any earlier symlinks. Empty when the entire path exists. |
+
+## Physical traversal and missing paths
+
+The helper resolves `link/..` from the link's physical target. It does not use
+`path.resolve()` on the full input or a symlink target, because lexical
+normalization would erase that traversal. Relative inputs use the current
+directory; Windows drive-relative inputs use Node's current directory for that
+drive. A root-relative Windows symlink target retains its containing link's
+drive or share root. Windows junctions and full UNC share roots are supported.
+
+At the first `ENOENT`, traversal stops. A suffix such as
+`missing/../live.sqlite` remains `["missing", "..", "live.sqlite"]`, even if
+`live.sqlite` exists beside the missing component. Dot components, repeated
+separators, and a trailing separator in the unresolved suffix are retained.
+Normalizing that suffix would invent an alias to a file the filesystem cannot
+reach through the missing directory. The caller owns any application-specific
+comparison or prospective-path policy.
+
+## Failures and limits
+
+Only `ENOENT` from component inspection produces a missing suffix. Permission,
+I/O, non-directory traversal, symlink-reading, and final canonicalization
+failures propagate. A vanished symlink that was already observed is an error,
+not an unprocessed missing component. NUL bytes reject with `invalid-path`.
+
+Resolution rejects with `ELOOP` after 64 symlink expansions or a repeated
+resolution state. The state retains exact bigint device/inode identity and
+the remaining suffix, so revisiting a link with a shorter suffix is permitted.
+Traversing through a non-directory, including `file/..`, `file/.`, or `file/`,
+rejects with `ENOTDIR`.
+
+Dot and parent components require the directory's search permission before
+they are collapsed. Native realpath alone does not establish this permission
+on every platform. Empty components from repeated or trailing separators do
+not introduce a `.` lookup.
+
+Raw component queues of at most 32 entries retain the legacy small-array
+consumption path. After both the initial parse and every symlink expansion, a
+longer queue uses forward cursor bookkeeping instead of moving the unprocessed
+suffix for every component. The fixed small-queue bound limits repeated front
+removal while retaining legacy shift-based consumption for shallow paths. This
+asymptotic bound is not a platform performance result; performance acceptance
+requires separate benchmark evidence. Callers should still apply their own
+input-size limits: the helper is synchronous, retains the raw suffix, and
+performs filesystem work for each non-empty existing component.
+
+This is a read-only path observation. It neither pins files nor creates a root
+boundary, authorizes access, or guarantees a consistent snapshot during
+concurrent changes. Results can become stale immediately. Use a guarded Root
+operation for subsequent access to untrusted paths; keep any database ownership,
+cache invalidation, and mutation policy with the caller. Native configuration
+and Bun realpath limitations follow the existing [runtime contract](install.md#bun-runtime).

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

@@ -0,0 +1,159 @@
+# pathScope()
+
+`pathScope()` prepares absolute paths and returns plain `{ ok, path }` results. `resolve()` and `resolveAll()` check lexical containment without touching the filesystem; `existing()`, `files()`, and `writable()` add the filesystem checks described below. Use it to prepare paths before handing them to another library, whose file-opening and mutation behavior still applies.
+
+```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).