@poe-platform/safe-fs 0.1.0

package/dist/safe-fs/fs/readonly/index.d.ts

@@ -0,0 +1,31 @@
+import type { ByteSource } from "../../contracts/io.js";
+import type { AppendFileOptions, CopyFileOptions, DirectoryEntry, FileStat, FileSystem, FileSystemCapabilities, FsOptions, MkdirOptions, ReadFileOptions, ReadStreamOptions, RemoveOptions, WriteFileOptions } from "../../contracts/filesystem.js";
+export declare class ReadOnlyFileSystem implements FileSystem {
+    #private;
+    constructor(filesystem: FileSystem);
+    get capabilities(): FileSystemCapabilities;
+    readFile(path: string, options?: ReadFileOptions): Promise<Uint8Array>;
+    stat(path: string, options?: FsOptions): Promise<FileStat>;
+    lstat(path: string, options?: FsOptions): Promise<FileStat>;
+    compareEntry(path: string, peer: FileSystem, peerPath: string, options?: FsOptions): Promise<import("../../contracts/filesystem.js").EntryComparison>;
+    readdir(path: string, options?: FsOptions): Promise<DirectoryEntry[]>;
+    realpath(path: string, options?: FsOptions): Promise<string>;
+    access(path: string, mode?: number, options?: FsOptions): Promise<void>;
+    readlink(path: string, options?: FsOptions): Promise<string>;
+    readStream(path: string, options?: ReadStreamOptions): ByteSource;
+    writeFile(path: string, _data: Uint8Array, _options?: WriteFileOptions): Promise<void>;
+    appendFile(path: string, _data: Uint8Array, _options?: AppendFileOptions): Promise<void>;
+    writeStream(path: string, _source: ByteSource, _options?: WriteFileOptions): Promise<void>;
+    mkdir(path: string, _options?: MkdirOptions): Promise<void>;
+    rm(path: string, _options?: RemoveOptions): Promise<void>;
+    unlink(path: string, _options?: FsOptions): Promise<void>;
+    rmdir(path: string, _options?: FsOptions): Promise<void>;
+    rename(source: string, destination: string, _options?: FsOptions): Promise<void>;
+    copyFile(source: string, destination: string, _options?: CopyFileOptions): Promise<void>;
+    symlink(target: string, path: string, _options?: FsOptions): Promise<void>;
+    link(existingPath: string, newPath: string, _options?: FsOptions): Promise<void>;
+    chmod(path: string, _mode: number, _options?: FsOptions): Promise<void>;
+    utimes(path: string, _atimeMs: number, _mtimeMs: number, _options?: FsOptions): Promise<void>;
+    truncate(path: string, _length?: number, _options?: FsOptions): Promise<void>;
+}
+export declare function createReadOnlyFileSystem(filesystem: FileSystem): ReadOnlyFileSystem;

package/dist/safe-fs/fs/readonly/index.js

@@ -0,0 +1,128 @@
+import { ACCESS_MODES } from "../../contracts/filesystem.js";
+import { FsError } from "../../contracts/errors.js";
+import { readBytes } from "../../contracts/io.js";
+import { compareEntries, registerEntryView } from "../mount/comparison.js";
+function readOnly(syscall, path, dest) {
+    throw new FsError("EROFS", { syscall, path, ...(dest === undefined ? {} : { dest }) });
+}
+function snapshotStat(stat) {
+    const { type, size, allocatedBytes, mode, mtimeMs, atimeMs, ctimeMs, birthtimeMs, identityScope, ino, dev, nlink, uid, gid } = stat;
+    return {
+        type, size, mode, mtimeMs, atimeMs, ctimeMs,
+        ...(allocatedBytes === undefined ? {} : { allocatedBytes }),
+        ...(birthtimeMs === undefined ? {} : { birthtimeMs }),
+        ...(identityScope === undefined ? {} : { identityScope }),
+        ...(ino === undefined ? {} : { ino }),
+        ...(dev === undefined ? {} : { dev }),
+        ...(nlink === undefined ? {} : { nlink }),
+        ...(uid === undefined ? {} : { uid }),
+        ...(gid === undefined ? {} : { gid }),
+    };
+}
+export class ReadOnlyFileSystem {
+    #filesystem;
+    #capabilities;
+    constructor(filesystem) {
+        this.#filesystem = filesystem;
+        registerEntryView(this, async (path) => ({ filesystem: this.#filesystem, path, readOnly: true }));
+        const streamingRead = typeof filesystem.readStream === "function" ? filesystem.capabilities.streamingRead : false;
+        this.#capabilities = Object.freeze({
+            readOnly: true,
+            symlinks: filesystem.capabilities.symlinks === true && typeof filesystem.readlink === "function",
+            hardlinks: false,
+            permissions: false,
+            timestamps: false,
+            atomicRename: false,
+            ...(streamingRead === undefined ? {} : { streamingRead }),
+            streamingWrite: false,
+        });
+    }
+    get capabilities() {
+        return this.#capabilities;
+    }
+    async readFile(path, options) {
+        return new Uint8Array(await this.#filesystem.readFile(path, options));
+    }
+    async stat(path, options) {
+        return snapshotStat(await this.#filesystem.stat(path, options));
+    }
+    async lstat(path, options) {
+        return snapshotStat(await this.#filesystem.lstat(path, options));
+    }
+    compareEntry(path, peer, peerPath, options = {}) {
+        return compareEntries(this, path, peer, peerPath, options);
+    }
+    async readdir(path, options) {
+        return (await this.#filesystem.readdir(path, options)).map((entry) => ({ name: entry.name, type: entry.type }));
+    }
+    async realpath(path, options) {
+        return this.#filesystem.realpath(path, options);
+    }
+    async access(path, mode = ACCESS_MODES.F_OK, options) {
+        if (!Number.isInteger(mode) || mode < 0 || mode > 7) {
+            throw new FsError("EINVAL", { syscall: "access", path });
+        }
+        if ((mode & ACCESS_MODES.W_OK) !== 0)
+            readOnly("access", path);
+        return this.#filesystem.access(path, mode, options);
+    }
+    async readlink(path, options) {
+        if (typeof this.#filesystem.readlink !== "function") {
+            throw new FsError("ENOTSUP", { syscall: "readlink", path });
+        }
+        return this.#filesystem.readlink(path, options);
+    }
+    async *readStream(path, options) {
+        if (typeof this.#filesystem.readStream !== "function") {
+            throw new FsError("ENOTSUP", { syscall: "readStream", path });
+        }
+        for await (const chunk of readBytes(this.#filesystem.readStream(path, options), options?.signal)) {
+            yield new Uint8Array(chunk);
+        }
+    }
+    async writeFile(path, _data, _options) {
+        readOnly("writeFile", path);
+    }
+    async appendFile(path, _data, _options) {
+        readOnly("appendFile", path);
+    }
+    async writeStream(path, _source, _options) {
+        readOnly("writeStream", path);
+    }
+    async mkdir(path, _options) {
+        readOnly("mkdir", path);
+    }
+    async rm(path, _options) {
+        readOnly("rm", path);
+    }
+    async unlink(path, _options) {
+        readOnly("unlink", path);
+    }
+    async rmdir(path, _options) {
+        readOnly("rmdir", path);
+    }
+    async rename(source, destination, _options) {
+        readOnly("rename", source, destination);
+    }
+    async copyFile(source, destination, _options) {
+        readOnly("copyFile", source, destination);
+    }
+    async symlink(target, path, _options) {
+        readOnly("symlink", target, path);
+    }
+    async link(existingPath, newPath, _options) {
+        readOnly("link", existingPath, newPath);
+    }
+    async chmod(path, _mode, _options) {
+        readOnly("chmod", path);
+    }
+    async utimes(path, _atimeMs, _mtimeMs, _options) {
+        readOnly("utimes", path);
+    }
+    async truncate(path, _length, _options) {
+        readOnly("truncate", path);
+    }
+}
+export function createReadOnlyFileSystem(filesystem) {
+    return new ReadOnlyFileSystem(filesystem);
+}

package/dist/safe-fs/fs/real/allocation.d.ts

@@ -0,0 +1 @@
+export declare function nativeAllocatedBytes(blocks: unknown, platform: string): number | undefined;

package/dist/safe-fs/fs/real/allocation.js

@@ -0,0 +1,8 @@
+export function nativeAllocatedBytes(blocks, platform) {
+    if (platform !== "darwin" && platform !== "linux")
+        return undefined;
+    if (typeof blocks !== "number" || !Number.isSafeInteger(blocks) || blocks < 0)
+        return undefined;
+    const bytes = blocks * 512;
+    return Number.isSafeInteger(bytes) ? bytes : undefined;
+}

package/dist/safe-fs/fs/real/index.d.ts

@@ -0,0 +1,76 @@
+import type { AppendFileOptions, ByteSource, CopyFileOptions, DirectoryEntry, FileStat, FileSystem, FileSystemCapabilities, FsOptions, MkdirOptions, ReadFileOptions, ReadStreamOptions, RemoveOptions, WriteFileOptions } from "../../contracts/index.js";
+export interface RealFileSystemOptions {
+    /** An existing, absolute host directory. It is never created implicitly. */
+    readonly root: string;
+}
+/**
+ * Async byte filesystem for trusted POSIX hosts (Windows is unsupported).
+ * Both relative and absolute input paths are virtual POSIX paths rooted at `/`;
+ * components resolve in order, following symlinks before subsequent `..` and
+ * preserving trailing directory requirements. Empty paths are ENOENT. Excess
+ * input `..` clamps at the virtual root; symlink targets may never cross it.
+ * There is no process cwd dependency. The configured host root must already
+ * exist; its canonical location is pinned on first use or by the async factory.
+ *
+ * Absolute symlink targets created here are virtual paths, stored as rooted
+ * host targets without lexical normalization. Relative targets retain their
+ * text; safe dangling, non-directory, and looping targets may be created.
+ * Existing host symlinks are
+ * followed only when every traversed component remains beneath the root, with
+ * a 40-link traversal limit. Existing absolute host targets must start with the
+ * canonical root, not a different host alias of that root. lstat, removal, and
+ * rename inspect or modify a final symlink itself rather than its target. Absolute readlink results are
+ * translated back into virtual paths; external absolute targets are refused.
+ *
+ * SECURITY LIMIT: containment checks and subsequent Node path operations are
+ * not atomic. O_NOFOLLOW narrows final-file open races, but ancestor swaps,
+ * concurrent renames, mount changes, and preexisting hardlinks cannot be made
+ * safe by these APIs. This is NOT a race-proof sandbox or an isolation boundary
+ * against another process modifying the tree. Use an OS sandbox for that.
+ *
+ * Only regular files, directories, and symlinks are represented. Permissions,
+ * ownership, timestamp precision, case sensitivity, umask, and rename behavior
+ * are those of the host filesystem. Copy is not atomic; rename can fail EXDEV.
+ * Cancellation is cooperative between operations/chunks, not rollback: failed
+ * or canceled writes/copies may leave partial data. No native commands execute.
+ * Destructive rm/rename operands ending in `.` or `..` are refused with EINVAL,
+ * including native recursive-rm edge cases that could otherwise delete content.
+ * Public filesystem errors carry only virtual operands; native causes are
+ * intentionally omitted so host paths cannot escape through nested errors.
+ */
+export declare class RealFileSystem implements FileSystem {
+    readonly capabilities: FileSystemCapabilities;
+    private readonly configuredRoot;
+    private rootPromise;
+    constructor(options: RealFileSystemOptions | string);
+    private root;
+    private absoluteTarget;
+    private walk;
+    private path;
+    private operation;
+    private protectRoot;
+    private protectTerminal;
+    readFile(path: string, options?: ReadFileOptions): Promise<Uint8Array>;
+    writeFile(path: string, data: Uint8Array, options?: WriteFileOptions): Promise<void>;
+    appendFile(path: string, data: Uint8Array, options?: AppendFileOptions): Promise<void>;
+    stat(path: string, options?: FsOptions): Promise<FileStat>;
+    lstat(path: string, options?: FsOptions): Promise<FileStat>;
+    readdir(path: string, options?: FsOptions): Promise<DirectoryEntry[]>;
+    mkdir(path: string, options?: MkdirOptions): Promise<void>;
+    rmdir(path: string, options?: FsOptions): Promise<void>;
+    rm(path: string, options?: RemoveOptions): Promise<void>;
+    rename(source: string, destination: string, options?: FsOptions): Promise<void>;
+    copyFile(source: string, destination: string, options?: CopyFileOptions): Promise<void>;
+    realpath(path: string, options?: FsOptions): Promise<string>;
+    access(path: string, mode?: number, options?: FsOptions): Promise<void>;
+    readlink(path: string, options?: FsOptions): Promise<string>;
+    symlink(target: string, path: string, options?: FsOptions): Promise<void>;
+    link(existingPath: string, newPath: string, options?: FsOptions): Promise<void>;
+    chmod(path: string, mode: number, options?: FsOptions): Promise<void>;
+    utimes(path: string, atimeMs: number, mtimeMs: number, options?: FsOptions): Promise<void>;
+    truncate(path: string, length?: number, options?: FsOptions): Promise<void>;
+    readStream(path: string, options?: ReadStreamOptions): ByteSource;
+    writeStream(path: string, source: ByteSource, options?: WriteFileOptions): Promise<void>;
+}
+/** Construct and validate an existing root before returning the backend. */
+export declare function createRealFileSystem(options: RealFileSystemOptions | string): Promise<RealFileSystem>;