@poe-platform/safe-fs 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Poe Platform
+
+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,290 @@
+# safe-fs
+
+An asynchronous filesystem interface for memory, rooted host directories, S3, and WebDAV, with mounts, copy-on-write overlays, and Node-style bridges.
+
+## Quickstart
+
+Install the standalone package; it does not depend on SafeJS, Safe Bash, or the `poe-code` CLI. These examples use TypeScript in a Node ESM application.
+
+```sh
+npm install @poe-platform/safe-fs
+```
+
+```ts
+import { createMemoryFileSystem, createNodeFsBridge } from "@poe-platform/safe-fs";
+
+const storage = createMemoryFileSystem();
+await storage.mkdir("/work");
+await storage.writeFile("/work/note.txt", new TextEncoder().encode("hello"));
+console.log(new TextDecoder().decode(await storage.readFile("/work/note.txt")));
+
+const fs = createNodeFsBridge(storage, { cwd: "/work" });
+await fs.appendFile("note.txt", " world", "utf8");
+console.log(await fs.readFile("note.txt", "utf8"));
+```
+
+Output: `hello`, then `hello world`. Nothing touches the host filesystem. Raw adapters exchange `Uint8Array` values; the Node bridge adds strings, encodings, `Buffer` results, and stat predicates. Its `cwd` is both the relative-path base and the confinement boundary.
+
+For host storage, use `await createRealFileSystem({ root: "/absolute/existing/directory" })` instead. The root must already exist; virtual `/` maps to that directory. Read the safety boundary below before exposing it to untrusted code.
+
+## Entry points and shared identity
+
+| Import | Use |
+| --- | --- |
+| `@poe-platform/safe-fs` | Full Node API; selects the portable core under the `browser` condition. |
+| `@poe-platform/safe-fs/core` | Memory, mounts, overlays, read-only, WebDAV, portable bridges, types, and errors. Bundle with the `browser` condition for browsers and Workers. |
+| `@poe-platform/safe-fs/node` | Host filesystem, Node bridge, S3, and configuration helpers; unavailable in browsers. |
+| `@poe-platform/safe-fs/fs/*` | Individual adapters: `memory`, `readonly`, `mount`, `overlay`, `webdav`, `real`, `s3`, and `s3/http`. The last three are Node-only. |
+
+```ts
+import { createMemoryFileSystem, FsError, type FileSystem } from "@poe-platform/safe-fs/core";
+
+const fs: FileSystem = createMemoryFileSystem();
+```
+
+Matching scoped SafeJS and Safe Bash releases use this package's types and runtime.
+Existing `@poe-platform/safe-js/fs`, `/fs/core`, and `/fs/node` imports remain
+re-exports, so `FsError` identity is shared; do not copy its implementation or the
+`FileSystem` declaration. `FileSystem` is an interface, not a runtime class.
+
+Legacy `poe-code/safe-fs` imports still use the CLI's bundled runtime. Keep an
+application's factories, shell, and errors in one import family. At a host-owned
+legacy adapter boundary, normalize foreign filesystem failures with `toFsError`
+from the receiving runtime; it retains the code, operation paths, and original
+cause. Preserve cancellation/control exceptions separately. Cross-family
+`instanceof FsError` is not supported without normalization.
+
+## Supported operations
+
+| Operation | Interface |
+| --- | --- |
+| Read and write bytes | `readFile`, `writeFile`, `appendFile` |
+| Inspect entries | `stat`, `lstat`, `readdir`, `realpath`, `access` |
+| Change the namespace | `mkdir`, `rm`, `rename`, `copyFile` |
+| Remove an empty directory | Optional `rmdir`; never a recursive-delete fallback |
+| Links and metadata | Optional `readlink`, `symlink`, `link`, `chmod`, `utimes`, `truncate` |
+| Stream bytes | Optional `readStream`, `writeStream`, using async iterables of byte chunks |
+| Compare backing entries | Optional `compareEntry`, returning `same`, `distinct`, or `unknown` |
+
+All required methods must exist, but a backend may reject an operation with `FsError`, such as `EROFS` for a write or `ENOTSUP` for unsupported semantics. Check optional methods and `capabilities` rather than assuming every backend behaves like a local disk. Errors expose `code` and may include `syscall`, `path`, `dest`, and `cause`.
+
+| Backend or wrapper | Use it for |
+| --- | --- |
+| `createMemoryFileSystem()` | Isolated, nonpersistent storage with links, permissions, timestamps, and streams |
+| `createRealFileSystem({ root })` | An existing host directory, with virtual paths rooted inside it; Node only |
+| `new S3FileSystem({ transport, bucket, … })` | Bucket/prefix storage through an explicitly supplied transport; Node only |
+| `new WebDavFileSystem({ baseUrl, fetch, … })` | A WebDAV namespace through an explicitly supplied Fetch implementation |
+| `createReadOnlyFileSystem(filesystem)` | Rejecting writes through one view of an existing filesystem |
+| `createMountFileSystem({ root, mounts })` | Routing absolute virtual mount paths to different filesystems |
+| `createOverlayFileSystem({ upper, lower })` | Reading through to a lower layer and writing changes to an upper layer |
+
+`createNodeFsBridge` offers a promises-shaped subset, including recursive `cp` and `mkdtemp`. The portable `createFsBridge` from `@poe-platform/safe-fs/core` instead requires a caller-supplied text codec and returns `Uint8Array` values.
+
+## Write an adapter
+
+A backend implements the exported [`FileSystem` interface](src/contracts/filesystem.ts). It needs every non-optional method, a truthful `capabilities` object, byte-safe reads/writes, and appropriate errors. A configuration adapter adds `validateOptions` and a `create` factory returning that filesystem, synchronously or asynchronously.
+
+This hypothetical `catalog` adapter presents a snapshot of named text documents as read-only files at `/`. It implements the full required interface without a host filesystem or network connection. Only the root directory and single-component filenames are supported; timestamps are synthetic and optional operations are absent.
+
+```ts
+import {
+  ACCESS_MODES, FsError, createFileSystem,
+  createNodeFileSystemAdapterRegistry, readConfigRecord, validatePath,
+  type FileStat, type FileSystem, type FileSystemAdapterDescriptor,
+  type FsOptions,
+} from "@poe-platform/safe-fs";
+
+const catalogAdapter = {
+  validateOptions(options) {
+    const config = readConfigRecord(options, "catalog option", ["files"]);
+    const files = readConfigRecord(config.files, "catalog files");
+    for (const [name, text] of Object.entries(files)) {
+      if (!name || name === "." || name === ".." || name.includes("/")
+        || name.includes("\0") || typeof text !== "string") {
+        throw new TypeError("files must map single-component names to strings");
+      }
+    }
+  },
+  create(options): FileSystem {
+    const files = new Map(Object.entries(readConfigRecord(options.files, "catalog files"))
+      .map(([name, text]) => [name, new TextEncoder().encode(text as string)]));
+
+    function lookup(path: string, options?: FsOptions) {
+      if (options?.signal?.aborted) throw new FsError("ECANCELED", { path });
+      validatePath(path);
+      let name = "";
+      let bytes: Uint8Array | undefined;
+      for (const part of path.split("/")) {
+        if (bytes !== undefined) throw new FsError("ENOTDIR", { path });
+        if (part === "" || part === "." || part === "..") continue;
+        bytes = files.get(part);
+        if (bytes === undefined) throw new FsError("ENOENT", { path });
+        name = part;
+      }
+      return { path: `/${name}`, bytes };
+    }
+
+    async function inspect(path: string, options?: FsOptions): Promise<FileStat> {
+      const { bytes } = lookup(path, options);
+      return {
+        type: bytes === undefined ? "directory" : "file",
+        size: bytes?.byteLength ?? 0,
+        mode: bytes === undefined ? 0o40555 : 0o100444,
+        atimeMs: 0, mtimeMs: 0, ctimeMs: 0,
+      };
+    }
+
+    async function denyWrite(): Promise<never> {
+      throw new FsError("EROFS");
+    }
+
+    return {
+      capabilities: { readOnly: true },
+      async readFile(path, options) {
+        const { bytes } = lookup(path, options);
+        if (bytes === undefined) throw new FsError("EISDIR", { path });
+        const limit = options?.maxBytes ?? Number.MAX_SAFE_INTEGER;
+        if (!Number.isSafeInteger(limit) || limit < 0) throw new FsError("EINVAL", { path });
+        if (bytes.byteLength > limit) throw new FsError("EFBIG", { path });
+        return bytes.slice();
+      },
+      stat: inspect,
+      lstat: inspect,
+      async readdir(path, options) {
+        if (lookup(path, options).bytes !== undefined) throw new FsError("ENOTDIR", { path });
+        return [...files.keys()].sort().map(name => ({ name, type: "file" as const }));
+      },
+      async realpath(path, options) {
+        const entry = lookup(path, options);
+        return entry.path;
+      },
+      async access(path, mode = ACCESS_MODES.F_OK, options) {
+        const entry = lookup(path, options);
+        if (!Number.isInteger(mode) || mode < 0 || mode > 7) throw new FsError("EINVAL", { path });
+        if (mode & ACCESS_MODES.W_OK) throw new FsError("EROFS", { path });
+        if ((mode & ACCESS_MODES.X_OK) && entry.bytes !== undefined) {
+          throw new FsError("EACCES", { path });
+        }
+      },
+      writeFile: denyWrite, appendFile: denyWrite, mkdir: denyWrite,
+      rm: denyWrite, rename: denyWrite, copyFile: denyWrite,
+    };
+  },
+} satisfies FileSystemAdapterDescriptor;
+
+const registry = createNodeFileSystemAdapterRegistry(new Map([["catalog", catalogAdapter]]));
+const catalog = await createFileSystem({
+  type: "catalog",
+  options: { files: { "welcome.txt": "Hello from the catalog" } },
+}, { registry });
+
+console.log(new TextDecoder().decode(await catalog.readFile("/welcome.txt")));
+```
+
+Output: `Hello from the catalog`. `readFile` returns a copy so callers cannot mutate the stored snapshot. Reads check cancellation and `maxBytes`; required mutations always reject with `EROFS`. `stat` and `lstat` share an implementation because this adapter has no symlinks.
+
+`createFileSystem` validates options before calling the factory. The Node registry includes `memory` and `real`, accepts new names, and rejects attempts to replace those defaults. For an explicit allowlist without either default, pass `new Map([["catalog", catalogAdapter]])` directly as `registry`. Names select registered factories; they do not load modules from config.
+
+For a mutable backend, preserve exclusive-create behavior, return independent byte buffers, handle cancellation and size limits, and declare only capabilities you actually provide. Use `FsError` for filesystem failures. Do not invent entry identity from matching paths or metadata; omit `compareEntry` when identity is unknown.
+
+## Options
+
+There are no package environment variables, implicit credentials, or automatic `.env` loading. Applications supply configuration, transports, and credentials explicitly. Factories accept the same options as their corresponding classes.
+
+### Local storage, composition, and bridges
+
+| API | Options and defaults |
+| --- | --- |
+| `createFileSystem(config, { registry })` | Required `config.type`; `config.options` defaults to an empty record. `registry` is required. Built-in `memory` accepts no options; built-in `real` requires `root`. |
+| `createNodeFileSystemAdapterRegistry(extensions?)` | Optional map of additional adapter descriptors; defaults to only `memory` and `real`. |
+| Memory / read-only | Memory takes no options. Read-only takes the backing filesystem, without an options object. |
+| Real | Required `root`: existing absolute host directory; the constructor/factory also accepts the root string directly. |
+| Mount | Required `root`: fallback filesystem. `mounts` defaults to `{}` and maps absolute virtual paths to filesystems. |
+| Overlay | Required `upper` and `lower`; `maxBufferBytes` defaults to 64 MiB. |
+| Node bridge | `cwd` defaults to `/`, must be an absolute virtual path; optional lifetime `signal`. |
+| Portable bridge | Same `cwd` and `signal`, plus required `codec` with `isEncoding`, `encode`, and `decode` functions. |
+| Catalog example | Required `files`: a plain record of single-component filenames to text strings; no other options. |
+
+### Per-operation options
+
+Every raw filesystem operation accepts an optional `signal`. Additional fields are:
+
+| Operation | Options |
+| --- | --- |
+| `readFile` | `maxBytes`: upper bound on collected bytes |
+| `writeFile`, `writeStream` | `flag`: `w` (default, replace), `wx` (exclusive create), `a` (append), or `ax` (exclusive append/create); optional `mode` |
+| `appendFile` | Optional `mode` |
+| `mkdir` | `recursive` (default false); optional `mode` |
+| `rm` | `recursive` and `force` (default false) |
+| `copyFile` | `exclusive` (default false) |
+| `readStream` | `start` (default 0), `endExclusive` (default end of file), `chunkSize` (built-in default 64 KiB) |
+
+`access` takes a separate mode bitmask from `ACCESS_MODES`. `chmod` takes a mode, `utimes` takes millisecond timestamps, and `truncate` takes a byte length (default 0). Backend limits still apply. Node-shaped bridge methods translate their own options rather than accepting these raw option objects; see the [bridge signatures](src/bridge/filesystem.ts).
+
+<details>
+<summary>S3 filesystem and HTTP transport options</summary>
+
+`S3FileSystem` requires `transport` and `bucket`. A transport supplies `headObject`, `getObject`, `putObject`, `deleteObject`, `copyObject`, and `listObjectsV2`; see the [transport interface](src/fs/s3/transport.ts).
+
+`createS3Transport(client, capabilities?)` wraps a compatible client with explicit `streamingRead`, `streamingWrite`, `conditionalPut`, `conditionalCopy`, and `conditionalDelete` flags (all absent by default). Direct transport requests accept an optional `abortSignal`.
+
+For in-memory S3 simulations, `new MockS3Client({ buckets, pageSize?, now?, authorize? })` requires bucket names. `pageSize` defaults to 1,000 (range 1–1,000), `now` defaults to the current date/time, and optional `authorize(request)` can reject requests. It does not verify a real provider.
+
+| Optional field | Default / meaning |
+| --- | --- |
+| `prefix` | Empty; canonical relative object-key prefix |
+| `readOnly` | `false` |
+| `allowNonAtomicRename` | `true`; rename copies then deletes, without rollback guarantees |
+| `pageSize` | 1,000; range 1–1,000 |
+| `maxReadBytes` | 64 MiB |
+| `maxStreamBytes` | 5,000,000,000 bytes; also the maximum accepted value |
+| `maxListEntries` | 100,000 |
+| `compareEntry` | Optional trusted backing-identity callback |
+
+`createS3HttpTransport` requires `endpoint` (an origin without path or credentials), `region`, and `credentials`. Credentials contain `accessKeyId`, `secretAccessKey`, and optional `sessionToken`, or come from an async provider receiving `{ signal }`.
+
+| Optional field | Default / meaning |
+| --- | --- |
+| `addressingStyle` | `path`; alternative `virtual-hosted` requires a DNS endpoint |
+| `listUrlEncoding` | `percent`; alternative `form` |
+| `allowInsecureHttp` | `false`; HTTPS required unless explicitly enabled |
+| `maxPutBytes`, `maxGetBytes` | 64 MiB each |
+| `maxXmlBytes` | 4 MiB; maximum 16 MiB |
+| `requestTimeoutMs` | 30,000 |
+| `enableCopy` | `true`; disabling uses a buffered GET/PUT fallback |
+| `verifiedConditionalOperations` | Optional `put`, `copy`, `delete` booleans, each defaulting to false; enable only after verifying the server's semantics |
+| `clock` | Current date/time function, used for signing |
+| `request` | Optional Node HTTP request factory; defaults to the built-in HTTP(S) client |
+
+</details>
+
+<details>
+<summary>WebDAV options</summary>
+
+`WebDavFileSystem` requires `baseUrl` and `fetch`.
+
+| Optional field | Default / meaning |
+| --- | --- |
+| `headers` | Empty; explicit authentication/custom headers. Protocol-reserved headers are rejected; authorization and cookies require HTTPS. |
+| `requestStreamSupport` | `native` for global Fetch, otherwise false; accepts `native` or a boolean declaration for the injected transport |
+| `maxResponseBytes` | 64 MiB |
+| `maxXmlBytes` | 2 MiB |
+| `maxEntries` | 10,000 |
+| `timeoutMs` | 30,000 |
+| `overwritePolicy` | `lock`; alternative `etag` uses conditional overwrites |
+| `atomicEmptyDirectory` | Optional trusted binding with the canonical `namespaceUrl` and `removeEmptyDirectory` callback; required for strict empty-only `rmdir` |
+| `compareEntry` | Optional trusted backing-identity callback on Node; unavailable under browser policy |
+
+See the [binding types](src/fs/webdav/webdav.ts) before implementing atomic directory removal. A recursive WebDAV DELETE does not satisfy that contract.
+
+</details>
+
+## Safety boundary and limitations
+
+- **Not an OS sandbox.** Rooted storage and bridge confinement check paths and symlinks, but checks and host operations can race concurrent changes. Use a separate OS isolation boundary for hostile workloads. A custom adapter or transport is trusted code with its own host authority.
+- **A read-only view is not an immutable store.** Other references can still change the backing filesystem. Overlays are not transactions; cancellation and cleanup do not guarantee rollback. Cross-mount rename can fail with `EXDEV`.
+- **Remote storage is not a POSIX disk.** S3 and WebDAV do not provide hardlinks or symlinks. S3 rename is non-atomic and may leave partial copies/deletions; `S3RenameError` reports the phase and affected keys. Strong empty-only removal and conditional writes depend on backend support, not a prior listing.
+- **The bridges are partial Node compatibility layers.** No synchronous/callback API, file handles, watchers, bigint stats, flush/retry support, or `cp` dereference/timestamp-preservation options. Missing optional operations fail rather than being approximated with destructive alternatives.
+- **Browser support is filesystem-only.** The `browser` export condition selects the portable surface: memory, mounts, overlays, read-only, WebDAV, and the codec-based bridge. Real storage, S3, the Node bridge, and the configuration registry are not browser exports. WebDAV still needs server CORS support; no OPFS or directory-handle adapter is included. This does not make the SafeJS runtime browser-compatible.
+- **Portable temporary names require secure randomness.** Browser overlay staging and portable bridge `mkdtemp` require `crypto.randomUUID` or `crypto.getRandomValues`; without either, they fail with `ENOTSUP` rather than use `Math.random`.
+- **Allocation and identity may be unknown.** Optional `FileStat.allocatedBytes` is provider-reported allocation, not logical length or reclaimable space. Do not infer identity from size, timestamps, or inode numbers across unrelated backends.

package/dist/safe-fs/bridge/confinement.d.ts

@@ -0,0 +1,3 @@
+import type { FileSystem, FsOptions } from "../contracts/filesystem.js";
+export declare function assertBridgePath(root: string, path: string): void;
+export declare function checkedBridgePath(fs: FileSystem, root: string, path: string, options: FsOptions, followFinal: boolean): Promise<string>;

package/dist/safe-fs/bridge/confinement.js

@@ -0,0 +1,171 @@
+import { FsError, isFsError } from "../contracts/errors.js";
+import { dirname } from "../contracts/virtual-path.js";
+import { checkSignal } from "./values.js";
+function denied(path) {
+    throw new FsError("EACCES", { syscall: "resolve", path, message: "path escapes the bridge cwd" });
+}
+function relativeComponents(root, path) {
+    if (typeof path !== "string" || !path.startsWith("/") || path.includes("\0"))
+        denied(path);
+    const boundary = root.split("/").filter(Boolean);
+    const components = path.split("/").filter(Boolean);
+    let index = 0;
+    for (const component of boundary) {
+        while (components[index] === ".")
+            index++;
+        if (components[index] !== component)
+            denied(path);
+        index++;
+    }
+    const relative = components.slice(index);
+    let depth = 0;
+    for (const component of relative) {
+        if (component === ".")
+            continue;
+        if (component === "..") {
+            if (depth === 0)
+                denied(path);
+            depth--;
+        }
+        else
+            depth++;
+    }
+    if (path.endsWith("/"))
+        relative.push(".");
+    return relative;
+}
+export function assertBridgePath(root, path) {
+    if (root !== "/")
+        relativeComponents(root, path);
+}
+async function assertCanonicalPath(fs, root, path, options) {
+    checkSignal(options.signal);
+    const canonical = await fs.realpath(path, options);
+    checkSignal(options.signal);
+    assertBridgePath(root, canonical);
+    if (canonical !== path)
+        denied(path);
+}
+async function assertCanonicalOperand(fs, root, path, expected, options) {
+    let operand = path;
+    let target = expected;
+    while (true) {
+        checkSignal(options.signal);
+        try {
+            const canonical = await fs.realpath(operand, options);
+            checkSignal(options.signal);
+            assertBridgePath(root, canonical);
+            if (canonical !== target)
+                denied(path);
+            return;
+        }
+        catch (error) {
+            checkSignal(options.signal);
+            if (!isFsError(error) || error.code !== "ENOENT")
+                throw error;
+            let missing = false;
+            try {
+                await fs.lstat(operand, options);
+            }
+            catch (inspectionError) {
+                checkSignal(options.signal);
+                if (!isFsError(inspectionError) || inspectionError.code !== "ENOENT")
+                    throw inspectionError;
+                missing = true;
+            }
+            checkSignal(options.signal);
+            if (!missing || operand === root)
+                denied(path);
+            operand = dirname(operand);
+            target = dirname(target);
+            assertBridgePath(root, operand);
+            assertBridgePath(root, target);
+        }
+    }
+}
+export async function checkedBridgePath(fs, root, path, options, followFinal) {
+    if (root === "/")
+        return path;
+    let pending = relativeComponents(root, path);
+    let current = "";
+    for (const component of root.split("/").filter(Boolean)) {
+        current += `/${component}`;
+        checkSignal(options.signal);
+        try {
+            const stat = await fs.lstat(current, options);
+            checkSignal(options.signal);
+            if (stat.type === "symlink")
+                denied(current);
+            if (stat.type !== "directory")
+                throw new FsError("ENOTDIR", { syscall: "resolve", path: current });
+        }
+        catch (error) {
+            checkSignal(options.signal);
+            if (!isFsError(error) || error.code !== "ENOENT")
+                throw error;
+            if (current !== root)
+                denied(path);
+            if (pending.includes(".."))
+                throw error;
+            const parent = dirname(root);
+            await assertCanonicalPath(fs, parent, parent, options);
+            return path;
+        }
+    }
+    await assertCanonicalPath(fs, root, root, options);
+    let links = 0;
+    let finalLink = false;
+    let index = 0;
+    while (index < pending.length) {
+        const component = pending[index++];
+        checkSignal(options.signal);
+        if (component === ".")
+            continue;
+        if (component === "..") {
+            if (current === root)
+                denied(path);
+            current = dirname(current);
+            continue;
+        }
+        const candidate = `${current}/${component}`;
+        let stat;
+        try {
+            stat = await fs.lstat(candidate, options);
+        }
+        catch (error) {
+            checkSignal(options.signal);
+            if (!isFsError(error) || error.code !== "ENOENT")
+                throw error;
+            if (pending.slice(index).includes(".."))
+                throw error;
+            await assertCanonicalPath(fs, root, current, options);
+            const expected = [candidate, ...pending.slice(index)].join("/");
+            await assertCanonicalOperand(fs, root, path, expected, options);
+            return path;
+        }
+        checkSignal(options.signal);
+        if (stat.type === "symlink" && (followFinal || index < pending.length)) {
+            if (++links > 40)
+                throw new FsError("ELOOP", { syscall: "resolve", path });
+            if (typeof fs.readlink !== "function")
+                throw new FsError("ENOTSUP", { syscall: "readlink", path: candidate });
+            const target = await fs.readlink(candidate, options);
+            checkSignal(options.signal);
+            if (typeof target !== "string" || target.length === 0 || target.includes("\0"))
+                denied(candidate);
+            const absolute = target.startsWith("/") ? target : `${current}/${target}`;
+            pending = [...relativeComponents(root, absolute), ...pending.slice(index)];
+            index = 0;
+            current = root;
+            continue;
+        }
+        if (index < pending.length && stat.type !== "directory") {
+            throw new FsError("ENOTDIR", { syscall: "resolve", path: candidate });
+        }
+        current = candidate;
+        finalLink = stat.type === "symlink";
+    }
+    await assertCanonicalPath(fs, root, finalLink ? dirname(current) : current, options);
+    await assertCanonicalOperand(fs, root, finalLink ? dirname(path) : path, finalLink ? dirname(current) : current, options);
+    return path;
+}

package/dist/safe-fs/bridge/filesystem.d.ts

@@ -0,0 +1,88 @@
+import type { FileSystem } from "../contracts/filesystem.js";
+import type { BridgePrimitives, BufferEncodingOption, FsBridgeDirent, FsBridgeEncoding, FsBridgeStats, MakeDirectoryOptions, Mode, ObjectEncodingOptions, StatOptions } from "./types.js";
+type Encoding = FsBridgeEncoding | "buffer";
+type ReadOptions = ObjectEncodingOptions & {
+    flag?: string | number | undefined;
+    signal?: AbortSignal | undefined;
+};
+type DirectoryOptions = {
+    encoding?: Encoding | null | undefined;
+    recursive?: boolean | undefined;
+    withFileTypes?: boolean | undefined;
+};
+export declare class FileSystemBridge<Binary extends Uint8Array> {
+    #private;
+    constructor(fs: FileSystem, options: {
+        readonly cwd?: string;
+        readonly signal?: AbortSignal;
+    }, primitives: BridgePrimitives<Binary>);
+    readFile(path: unknown, options?: {
+        encoding?: null | undefined;
+        flag?: string | number | undefined;
+        signal?: AbortSignal | undefined;
+    } | null): Promise<Binary>;
+    readFile(path: unknown, options: FsBridgeEncoding | (ReadOptions & {
+        encoding: FsBridgeEncoding;
+    })): Promise<string>;
+    readFile(path: unknown, options?: ReadOptions | FsBridgeEncoding | null): Promise<string | Binary>;
+    writeFile(path: unknown, data: unknown, options?: unknown): Promise<void>;
+    appendFile(path: unknown, data: unknown, options?: unknown): Promise<void>;
+    stat(path: unknown, options?: StatOptions & {
+        bigint?: false | undefined;
+    }): Promise<FsBridgeStats>;
+    stat(path: unknown, options: StatOptions & {
+        bigint: true;
+    }): Promise<never>;
+    stat(path: unknown, options?: StatOptions): Promise<FsBridgeStats>;
+    lstat(path: unknown, options?: StatOptions & {
+        bigint?: false | undefined;
+    }): Promise<FsBridgeStats>;
+    lstat(path: unknown, options: StatOptions & {
+        bigint: true;
+    }): Promise<never>;
+    lstat(path: unknown, options?: StatOptions): Promise<FsBridgeStats>;
+    readdir(path: unknown, options?: FsBridgeEncoding | (ObjectEncodingOptions & {
+        withFileTypes?: false | undefined;
+        recursive?: boolean | undefined;
+    }) | null): Promise<string[]>;
+    readdir(path: unknown, options: "buffer" | (DirectoryOptions & {
+        encoding: "buffer";
+        withFileTypes?: false | undefined;
+    })): Promise<Binary[]>;
+    readdir(path: unknown, options: ObjectEncodingOptions & {
+        withFileTypes: true;
+        recursive?: boolean | undefined;
+    }): Promise<FsBridgeDirent[]>;
+    readdir(path: unknown, options: DirectoryOptions & {
+        encoding: "buffer";
+        withFileTypes: true;
+    }): Promise<FsBridgeDirent<Binary>[]>;
+    mkdir(path: unknown, options: MakeDirectoryOptions & {
+        recursive: true;
+    }): Promise<string | undefined>;
+    mkdir(path: unknown, options?: Mode | (MakeDirectoryOptions & {
+        recursive?: false | undefined;
+    }) | null): Promise<void>;
+    mkdir(path: unknown, options?: Mode | MakeDirectoryOptions | null): Promise<string | undefined>;
+    access(path: unknown, mode?: number): Promise<void>;
+    rm(path: unknown, value?: unknown): Promise<void>;
+    rmdir(path: unknown, value?: unknown): Promise<void>;
+    rename(source: unknown, destination: unknown): Promise<void>;
+    copyFile(source: unknown, destination: unknown, mode?: number): Promise<void>;
+    cp(source: unknown, destination: unknown, value?: unknown): Promise<void>;
+    readlink(path: unknown, options?: ObjectEncodingOptions | FsBridgeEncoding | null): Promise<string>;
+    readlink(path: unknown, options: BufferEncodingOption): Promise<Binary>;
+    readlink(path: unknown, options?: ObjectEncodingOptions | BufferEncodingOption | string | null): Promise<string | Binary>;
+    realpath(path: unknown, options?: ObjectEncodingOptions | FsBridgeEncoding | null): Promise<string>;
+    realpath(path: unknown, options: BufferEncodingOption): Promise<Binary>;
+    realpath(path: unknown, options?: ObjectEncodingOptions | BufferEncodingOption | string | null): Promise<string | Binary>;
+    mkdtemp(prefix: string, options?: ObjectEncodingOptions | FsBridgeEncoding | null): Promise<string>;
+    mkdtemp(prefix: string, options: BufferEncodingOption): Promise<Binary>;
+    mkdtemp(prefix: string, options?: ObjectEncodingOptions | BufferEncodingOption | string | null): Promise<string | Binary>;
+    symlink(target: unknown, path: unknown, type?: unknown): Promise<void>;
+    link(existing: unknown, path: unknown): Promise<void>;
+    chmod(path: unknown, value: unknown): Promise<void>;
+    utimes(path: unknown, atime: unknown, mtime: unknown): Promise<void>;
+    truncate(path: unknown, length?: number): Promise<void>;
+}
+export {};