@poe-platform/safe-fs 0.1.0

package/dist/safe-fs/fs/webdav/xml.d.ts

@@ -0,0 +1,15 @@
+export interface XmlElement {
+    readonly namespace: string;
+    readonly localName: string;
+    readonly children: XmlElement[];
+    text: string;
+}
+export interface XmlLimits {
+    readonly maxDepth?: number;
+    readonly maxNodes?: number;
+    readonly maxAttributes?: number;
+}
+export declare function parseXml(input: string, limits?: XmlLimits): XmlElement;
+export declare function davChildren(element: XmlElement, localName: string): XmlElement[];
+export declare function davChild(element: XmlElement, localName: string): XmlElement | undefined;
+export declare function scalar(element: XmlElement): string;

package/dist/safe-fs/fs/webdav/xml.js

@@ -0,0 +1,250 @@
+const xmlNamespace = "http://www.w3.org/XML/1998/namespace";
+const xmlnsNamespace = "http://www.w3.org/2000/xmlns/";
+function invalid(message) {
+    throw new SyntaxError(`Invalid WebDAV XML: ${message}`);
+}
+function validCharacter(point) {
+    return point === 9 || point === 10 || point === 13
+        || (point >= 0x20 && point <= 0xd7ff)
+        || (point >= 0xe000 && point <= 0xfffd)
+        || (point >= 0x10000 && point <= 0x10ffff);
+}
+function nameStart(point) {
+    return point === 95 || (point >= 65 && point <= 90) || (point >= 97 && point <= 122)
+        || (point >= 0xc0 && point <= 0xd6) || (point >= 0xd8 && point <= 0xf6)
+        || (point >= 0xf8 && point <= 0x2ff) || (point >= 0x370 && point <= 0x37d)
+        || (point >= 0x37f && point <= 0x1fff) || (point >= 0x200c && point <= 0x200d)
+        || (point >= 0x2070 && point <= 0x218f) || (point >= 0x2c00 && point <= 0x2fef)
+        || (point >= 0x3001 && point <= 0xd7ff) || (point >= 0xf900 && point <= 0xfdcf)
+        || (point >= 0xfdf0 && point <= 0xfffd) || (point >= 0x10000 && point <= 0xeffff);
+}
+function namePart(point) {
+    return nameStart(point) || point === 45 || point === 46 || point === 0xb7
+        || (point >= 48 && point <= 57) || (point >= 0x300 && point <= 0x36f)
+        || (point >= 0x203f && point <= 0x2040);
+}
+function qualifiedName(name) {
+    const parts = name.split(":");
+    if (parts.length > 2 || parts.some((part) => {
+        const points = [...part].map((character) => character.codePointAt(0));
+        return points.length === 0 || !nameStart(points[0]) || points.slice(1).some((point) => !namePart(point));
+    }))
+        invalid("invalid qualified name");
+    return parts.length === 1 ? ["", parts[0]] : [parts[0], parts[1]];
+}
+function entities(text) {
+    let result = "";
+    let offset = 0;
+    while (offset < text.length) {
+        const start = text.indexOf("&", offset);
+        if (start < 0)
+            return result + text.slice(offset);
+        result += text.slice(offset, start);
+        const end = text.indexOf(";", start + 1);
+        if (end < 0)
+            invalid("unterminated entity");
+        const entity = text.slice(start + 1, end);
+        const predefined = { amp: "&", lt: "<", gt: ">", quot: '"', apos: "'" };
+        if (Object.hasOwn(predefined, entity))
+            result += predefined[entity];
+        else {
+            const hexadecimal = entity.startsWith("#x");
+            const digits = entity.slice(hexadecimal ? 2 : 1);
+            if (!entity.startsWith("#") || !(hexadecimal ? /^[0-9a-fA-F]+$/ : /^[0-9]+$/).test(digits)) {
+                invalid("undeclared entity");
+            }
+            const point = Number.parseInt(digits, hexadecimal ? 16 : 10);
+            if (!validCharacter(point))
+                invalid("invalid character reference");
+            result += String.fromCodePoint(point);
+        }
+        offset = end + 1;
+    }
+    return result;
+}
+export function parseXml(input, limits = {}) {
+    const maxDepth = limits.maxDepth ?? 64;
+    const maxNodes = limits.maxNodes ?? 100_000;
+    const maxAttributes = limits.maxAttributes ?? 10_000;
+    for (const limit of [maxDepth, maxNodes, maxAttributes]) {
+        if (!Number.isSafeInteger(limit) || limit < 1)
+            throw new RangeError("XML limits must be positive integers");
+    }
+    for (const character of input) {
+        if (!validCharacter(character.codePointAt(0)))
+            invalid("invalid character");
+    }
+    const source = input.replace(/^\uFEFF/, "").replace(/\r\n?/g, "\n");
+    const stack = [];
+    let root;
+    let offset = 0;
+    let nodes = 0;
+    let attributeCount = 0;
+    const whitespace = () => {
+        while (offset < source.length && " \t\n\r".includes(source[offset]))
+            offset++;
+    };
+    const readName = () => {
+        const start = offset;
+        while (offset < source.length && !" \t\r\n/=>?".includes(source[offset]))
+            offset++;
+        const name = source.slice(start, offset);
+        qualifiedName(name);
+        return name;
+    };
+    const appendText = (text) => {
+        const parent = stack.at(-1);
+        if (parent)
+            parent.element.text += text;
+        else if (!/^[ \t\r\n]*$/.test(text))
+            invalid("text outside the root");
+    };
+    while (offset < source.length) {
+        if (source[offset] !== "<") {
+            const next = source.indexOf("<", offset);
+            const text = source.slice(offset, next < 0 ? source.length : next);
+            if (text.includes("]]>"))
+                invalid("CDATA terminator in text");
+            appendText(entities(text));
+            offset += text.length;
+        }
+        else if (source.startsWith("<!--", offset)) {
+            const end = source.indexOf("-->", offset + 4);
+            if (end < 0 || source.slice(offset + 4, end).includes("--") || source.slice(offset + 4, end).endsWith("-")) {
+                invalid("malformed comment");
+            }
+            offset = end + 3;
+        }
+        else if (source.startsWith("<![CDATA[", offset)) {
+            if (!stack.length)
+                invalid("CDATA outside root");
+            const end = source.indexOf("]]>", offset + 9);
+            if (end < 0)
+                invalid("unterminated CDATA");
+            appendText(source.slice(offset + 9, end));
+            offset = end + 3;
+        }
+        else if (source.startsWith("<?", offset)) {
+            const start = offset;
+            offset += 2;
+            const target = readName();
+            const end = source.indexOf("?>", offset);
+            if (end < 0)
+                invalid("unterminated processing instruction");
+            const content = source.slice(offset, end);
+            if (target.toLowerCase() === "xml") {
+                if (start !== 0 || target !== "xml"
+                    || !/^\s+version\s*=\s*(['"])1\.0\1(?:\s+encoding\s*=\s*(['"])(?:UTF-8|UTF-16|UTF-16LE|UTF-16BE)\2)?(?:\s+standalone\s*=\s*(['"])(?:yes|no)\3)?\s*$/i.test(content)) {
+                    invalid("unsupported XML declaration");
+                }
+            }
+            else if (content && !" \t\n\r".includes(content[0]))
+                invalid("invalid processing instruction");
+            offset = end + 2;
+        }
+        else if (source.startsWith("<!", offset)) {
+            invalid("DTD and entity declarations are forbidden");
+        }
+        else if (source.startsWith("</", offset)) {
+            offset += 2;
+            const name = readName();
+            whitespace();
+            if (source[offset++] !== ">" || stack.pop()?.name !== name)
+                invalid("mismatched closing tag");
+        }
+        else {
+            offset++;
+            const name = readName();
+            const attributes = new Map();
+            const namespaces = new Map(stack.at(-1)?.namespaces ?? [["xml", xmlNamespace]]);
+            while (true) {
+                const beforeSpace = offset;
+                whitespace();
+                if (source[offset] === "/" || source[offset] === ">")
+                    break;
+                if (offset === beforeSpace)
+                    invalid("attributes require whitespace");
+                const attribute = readName();
+                if (attributes.has(attribute))
+                    invalid("duplicate attribute");
+                if (++attributeCount > maxAttributes || attributes.size >= 128)
+                    invalid("XML attribute limit exceeded");
+                whitespace();
+                if (source[offset++] !== "=")
+                    invalid("missing attribute equals");
+                whitespace();
+                const quote = source[offset++];
+                if (quote !== '"' && quote !== "'")
+                    invalid("unquoted attribute");
+                const end = source.indexOf(quote, offset);
+                if (end < 0)
+                    invalid("unterminated attribute");
+                const raw = source.slice(offset, end);
+                if (raw.includes("<"))
+                    invalid("less-than in attribute");
+                const value = entities(raw.replace(/[\t\n\r]/g, " "));
+                attributes.set(attribute, value);
+                offset = end + 1;
+                if (attribute === "xmlns" || attribute.startsWith("xmlns:")) {
+                    const prefix = attribute === "xmlns" ? "" : attribute.slice(6);
+                    if (prefix === "xmlns" || value === xmlnsNamespace
+                        || (prefix === "xml") !== (value === xmlNamespace)
+                        || (prefix !== "" && value === ""))
+                        invalid("invalid namespace binding");
+                    namespaces.set(prefix, value);
+                    if (namespaces.size > 256)
+                        invalid("XML namespace scope limit exceeded");
+                }
+            }
+            const expanded = new Set();
+            for (const attribute of attributes.keys()) {
+                if (attribute === "xmlns" || attribute.startsWith("xmlns:"))
+                    continue;
+                const [prefix, localName] = qualifiedName(attribute);
+                if (prefix && !namespaces.has(prefix))
+                    invalid("unbound attribute prefix");
+                const key = JSON.stringify([prefix ? namespaces.get(prefix) : "", localName]);
+                if (expanded.has(key))
+                    invalid("duplicate expanded attribute");
+                expanded.add(key);
+            }
+            const [prefix, localName] = qualifiedName(name);
+            if (prefix === "xmlns" || (prefix && !namespaces.has(prefix)))
+                invalid("unbound element prefix");
+            const element = { namespace: namespaces.get(prefix) ?? "", localName, children: [], text: "" };
+            if (++nodes > maxNodes || stack.length + 1 > maxDepth)
+                invalid("XML resource limit exceeded");
+            const parent = stack.at(-1);
+            if (parent)
+                parent.element.children.push(element);
+            else if (root)
+                invalid("multiple root elements");
+            else
+                root = element;
+            const empty = source[offset] === "/";
+            if (empty)
+                offset++;
+            if (source[offset++] !== ">")
+                invalid("unterminated start tag");
+            if (!empty)
+                stack.push({ element, name, namespaces });
+        }
+    }
+    if (stack.length || !root)
+        invalid("incomplete document");
+    return root;
+}
+export function davChildren(element, localName) {
+    return element.children.filter((child) => child.namespace === "DAV:" && child.localName === localName);
+}
+export function davChild(element, localName) {
+    const children = davChildren(element, localName);
+    if (children.length > 1)
+        invalid(`duplicate DAV:${localName}`);
+    return children[0];
+}
+export function scalar(element) {
+    if (element.children.length)
+        invalid("expected text-only element");
+    return element.text.trim();
+}

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

@@ -0,0 +1,14 @@
+export * from "./contracts/index.js";
+export * from "./fs/memory/index.js";
+export * from "./fs/real/index.js";
+export * from "./fs/s3/index.js";
+export type { S3StreamGetInput, S3StreamGetOutput, S3StreamPutInput } from "./fs/s3/transport.js";
+export * from "./fs/s3/http/index.js";
+export * from "./fs/webdav/index.js";
+export * from "./fs/readonly/index.js";
+export * from "./fs/mount/index.js";
+export * from "./fs/overlay/index.js";
+export * from "./node/index.js";
+export { createFileSystem, readConfigRecord, validateFileSystemConfig } from "./config.js";
+export type { FileSystemConfig, FileSystemAdapterDescriptor, FileSystemAdapterRegistry } from "./config.js";
+export { createNodeFileSystemAdapterRegistry } from "./config.node.js";

package/dist/safe-fs/index.js

@@ -0,0 +1,12 @@
+export * from "./contracts/index.js";
+export * from "./fs/memory/index.js";
+export * from "./fs/real/index.js";
+export * from "./fs/s3/index.js";
+export * from "./fs/s3/http/index.js";
+export * from "./fs/webdav/index.js";
+export * from "./fs/readonly/index.js";
+export * from "./fs/mount/index.js";
+export * from "./fs/overlay/index.js";
+export * from "./node/index.js";
+export { createFileSystem, readConfigRecord, validateFileSystemConfig } from "./config.js";
+export { createNodeFileSystemAdapterRegistry } from "./config.node.js";

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

@@ -0,0 +1,11 @@
+import type * as FsPromises from "node:fs/promises";
+import type { FileSystem, FsOptions } from "../contracts/filesystem.js";
+export type NodeFsImplementation = Pick<typeof FsPromises, "access" | "appendFile" | "chmod" | "copyFile" | "cp" | "link" | "lstat" | "mkdir" | "mkdtemp" | "readFile" | "readdir" | "readlink" | "realpath" | "rename" | "rm" | "rmdir" | "stat" | "symlink" | "truncate" | "utimes" | "writeFile">;
+export interface NodeFsBridgeOptions {
+    readonly cwd?: string;
+    readonly signal?: AbortSignal;
+}
+export interface NodeFsBridgeFileSystem extends FileSystem {
+    rmdir?(path: string, options?: FsOptions): Promise<void>;
+}
+export declare function createNodeFsBridge(fs: FileSystem, options?: NodeFsBridgeOptions): NodeFsImplementation;

package/dist/safe-fs/node/filesystem.js

@@ -0,0 +1,28 @@
+import { Buffer } from "node:buffer";
+import { randomBytes } from "node:crypto";
+import { posix } from "node:path";
+import { fileURLToPath } from "node:url";
+import { FileSystemBridge } from "../bridge/filesystem.js";
+export function createNodeFsBridge(fs, options = {}) {
+    return new FileSystemBridge(fs, options, {
+        codec: {
+            isEncoding: Buffer.isEncoding,
+            encode(text, encoding) {
+                if (!Buffer.isEncoding(encoding))
+                    throw new TypeError("Invalid encoding");
+                return Buffer.from(text, encoding);
+            },
+            decode(bytes, encoding) {
+                if (!Buffer.isEncoding(encoding))
+                    throw new TypeError("Invalid encoding");
+                return Buffer.from(bytes).toString(encoding);
+            }
+        },
+        copyBytes: Buffer.from,
+        pathValue(value) {
+            return value instanceof URL ? fileURLToPath(value) : Buffer.isBuffer(value) ? value.toString("utf8") : value;
+        },
+        randomSuffix() { return randomBytes(6).toString("hex").slice(0, 6); },
+        paths: posix
+    });
+}

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

@@ -0,0 +1,2 @@
+export { createNodeFsBridge } from "./filesystem.js";
+export type { NodeFsBridgeOptions, NodeFsBridgeFileSystem, NodeFsImplementation } from "./filesystem.js";

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

@@ -0,0 +1 @@
+export { createNodeFsBridge } from "./filesystem.js";

package/dist/safe-fs/node/stats.d.ts

@@ -0,0 +1 @@
+export { bridgeDirent as nodeDirent, bridgeStats as nodeStats } from "../bridge/stats.js";

package/dist/safe-fs/node/stats.js

@@ -0,0 +1 @@
+export { bridgeDirent as nodeDirent, bridgeStats as nodeStats } from "../bridge/stats.js";

package/dist/safe-fs/node/values.d.ts

@@ -0,0 +1 @@
+export { abortError, booleanValue, checkSignal, onlyKeys, record, withSignal } from "../bridge/values.js";

package/dist/safe-fs/node/values.js

@@ -0,0 +1 @@
+export { abortError, booleanValue, checkSignal, onlyKeys, record, withSignal } from "../bridge/values.js";

package/dist/safe-fs/node-host.d.ts

@@ -0,0 +1 @@
+export * from "./index.js";

package/dist/safe-fs/node-host.js

@@ -0,0 +1 @@
+export * from "./index.js";

package/dist/safe-fs/node-unavailable.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/safe-fs/node-unavailable.js

@@ -0,0 +1 @@
+export {};

package/dist/safe-fs/platform/browser.d.ts

@@ -0,0 +1,12 @@
+import type { FsOptions } from "../contracts/filesystem.js";
+export type PlatformErrno = number | undefined;
+export type PlatformComparisonCallback<Callback> = Callback & never;
+export declare const platform: Readonly<{
+    errno(_code: string): PlatformErrno;
+    callbackAuthorities: false;
+    randomUUID(): string;
+}>;
+export declare const comparisonContext: Readonly<{
+    active(options: FsOptions): boolean;
+    run<Result>(options: FsOptions, action: (nested: FsOptions) => Promise<Result>): Promise<Result>;
+}>;

package/dist/safe-fs/platform/browser.js

@@ -0,0 +1,39 @@
+import { FsError } from "../contracts/errors.js";
+export const platform = Object.freeze({
+    errno(_code) {
+        return undefined;
+    },
+    callbackAuthorities: false,
+    randomUUID() {
+        const crypto = globalThis.crypto;
+        if (typeof crypto?.randomUUID === "function")
+            return crypto.randomUUID();
+        if (typeof crypto?.getRandomValues !== "function") {
+            throw new FsError("ENOTSUP", { message: "secure crypto is required for overlay staging" });
+        }
+        const bytes = crypto.getRandomValues(new Uint8Array(16));
+        bytes[6] = (bytes[6] & 0x0f) | 0x40;
+        bytes[8] = (bytes[8] & 0x3f) | 0x80;
+        const hex = Array.from(bytes, byte => byte.toString(16).padStart(2, "0")).join("");
+        return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+    }
+});
+const operationKey = Symbol("filesystem-comparison");
+const contexts = new WeakSet();
+export const comparisonContext = Object.freeze({
+    active(options) {
+        const context = options[operationKey];
+        return context !== undefined && contexts.has(context);
+    },
+    async run(options, action) {
+        const context = Object.freeze({});
+        contexts.add(context);
+        const nested = { ...options, [operationKey]: context };
+        try {
+            return await action(nested);
+        }
+        finally {
+            contexts.delete(context);
+        }
+    }
+});

package/dist/safe-fs/platform/node.d.ts

@@ -0,0 +1,13 @@
+import { randomUUID } from "node:crypto";
+import type { FsOptions } from "../contracts/filesystem.js";
+export type PlatformErrno = number;
+export type PlatformComparisonCallback<Callback> = Callback;
+export declare const platform: Readonly<{
+    errno(code: string): PlatformErrno;
+    callbackAuthorities: true;
+    randomUUID: typeof randomUUID;
+}>;
+export declare const comparisonContext: Readonly<{
+    active(_options: FsOptions): boolean;
+    run<Result>(options: FsOptions, action: (nested: FsOptions) => Promise<Result>): Promise<Result>;
+}>;

package/dist/safe-fs/platform/node.js

@@ -0,0 +1,26 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { randomUUID } from "node:crypto";
+import * as util from "node:util";
+import { constants } from "node:os";
+const systemErrnos = typeof util.getSystemErrorMap === "function"
+    ? new Map([...util.getSystemErrorMap()].map(([errno, [name]]) => [name, errno]))
+    : new Map(Object.entries(constants.errno).map(([name, errno]) => [name, -Math.abs(errno)]));
+const negotiating = new AsyncLocalStorage();
+export const platform = Object.freeze({
+    errno(code) {
+        const errno = systemErrnos.get(code === "EOPNOTSUPP" ? "ENOTSUP" : code);
+        if (errno === undefined)
+            throw new TypeError(`Unsupported platform errno code: ${code}`);
+        return errno;
+    },
+    callbackAuthorities: true,
+    randomUUID
+});
+export const comparisonContext = Object.freeze({
+    active(_options) {
+        return negotiating.getStore() === true;
+    },
+    run(options, action) {
+        return negotiating.run(true, () => action(options));
+    }
+});

package/package.json

@@ -0,0 +1,108 @@
+{
+  "name": "@poe-platform/safe-fs",
+  "version": "0.1.0",
+  "description": "Composable filesystem with a portable core and explicit Node adapters",
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.18"
+  },
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": {
+        "browser": "./dist/safe-fs/core.d.ts",
+        "default": "./dist/safe-fs/index.d.ts"
+      },
+      "browser": "./dist/safe-fs/core.js",
+      "import": "./dist/safe-fs/index.js"
+    },
+    "./contracts": {
+      "types": {
+        "browser": "./dist/safe-fs/core.d.ts",
+        "default": "./dist/safe-fs/contracts/index.d.ts"
+      },
+      "browser": "./dist/safe-fs/core.js",
+      "import": "./dist/safe-fs/contracts/index.js"
+    },
+    "./core": {
+      "types": "./dist/safe-fs/core.d.ts",
+      "import": "./dist/safe-fs/core.js"
+    },
+    "./node": {
+      "types": {
+        "browser": "./dist/safe-fs/node-unavailable.d.ts",
+        "default": "./dist/safe-fs/node-host.d.ts"
+      },
+      "browser": null,
+      "import": "./dist/safe-fs/node-host.js"
+    },
+    "./fs/memory": {
+      "types": "./dist/safe-fs/fs/memory/index.d.ts",
+      "import": "./dist/safe-fs/fs/memory/index.js"
+    },
+    "./fs/real": {
+      "types": {
+        "browser": "./dist/safe-fs/node-unavailable.d.ts",
+        "default": "./dist/safe-fs/fs/real/index.d.ts"
+      },
+      "browser": null,
+      "import": "./dist/safe-fs/fs/real/index.js"
+    },
+    "./fs/s3/http": {
+      "types": {
+        "browser": "./dist/safe-fs/node-unavailable.d.ts",
+        "default": "./dist/safe-fs/fs/s3/http/index.d.ts"
+      },
+      "browser": null,
+      "import": "./dist/safe-fs/fs/s3/http/index.js"
+    },
+    "./fs/s3": {
+      "types": {
+        "browser": "./dist/safe-fs/node-unavailable.d.ts",
+        "default": "./dist/safe-fs/fs/s3/index.d.ts"
+      },
+      "browser": null,
+      "import": "./dist/safe-fs/fs/s3/index.js"
+    },
+    "./fs/webdav": {
+      "types": "./dist/safe-fs/fs/webdav/index.d.ts",
+      "import": "./dist/safe-fs/fs/webdav/index.js"
+    },
+    "./fs/readonly": {
+      "types": "./dist/safe-fs/fs/readonly/index.d.ts",
+      "import": "./dist/safe-fs/fs/readonly/index.js"
+    },
+    "./fs/mount": {
+      "types": "./dist/safe-fs/fs/mount/index.d.ts",
+      "import": "./dist/safe-fs/fs/mount/index.js"
+    },
+    "./fs/overlay": {
+      "types": "./dist/safe-fs/fs/overlay/index.d.ts",
+      "import": "./dist/safe-fs/fs/overlay/index.js"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/poe-platform/poe-code.git",
+    "directory": "packages/safe-fs"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@types/node": "^25.2.2"
+  },
+  "imports": {
+    "#safe-fs-platform": {
+      "types": {
+        "browser": "./dist/safe-fs/platform/browser.d.ts",
+        "default": "./dist/safe-fs/platform/node.d.ts"
+      },
+      "browser": "./dist/safe-fs/platform/browser.js",
+      "default": "./dist/safe-fs/platform/node.js"
+    }
+  }
+}