@veryfront/ext-content-mdx 0.1.1183 → 0.1.1186

package/esm/src/platform/adapters/base.js

@@ -1,15 +1,64 @@
 const WEBSOCKET_UPGRADE_RESPONSE_KIND = "websocket-upgrade";
 export function createWebSocketUpgradeResponse(input = {}) {
-    return {
+    return Object.freeze({
         kind: WEBSOCKET_UPGRADE_RESPONSE_KIND,
         status: 101,
         statusText: input.statusText ?? "Switching Protocols",
         headers: new Headers(input.headers),
         body: null,
-    };
+    });
+}
+// A Proxy can synthesize a fresh prototype for every getPrototypeOf trap.
+// Bound each structural field lookup so an upgrade discriminator can never
+// turn into attacker-controlled, unbounded traversal.
+const MAX_UPGRADE_RESPONSE_PROTOTYPE_DEPTH = 16;
+const headersGet = Headers.prototype.get;
+function readDataProperty(value, key) {
+    const visited = new Set();
+    let current = value;
+    try {
+        for (let depth = 0; current !== null && depth < MAX_UPGRADE_RESPONSE_PROTOTYPE_DEPTH; depth++) {
+            if (visited.has(current))
+                return { readable: false };
+            visited.add(current);
+            const descriptor = Reflect.getOwnPropertyDescriptor(current, key);
+            if (descriptor) {
+                return "value" in descriptor
+                    ? { readable: true, value: descriptor.value }
+                    : { readable: false };
+            }
+            current = Reflect.getPrototypeOf(current);
+        }
+    }
+    catch {
+        return { readable: false };
+    }
+    return current === null ? { readable: true, value: undefined } : { readable: false };
 }
 export function isWebSocketUpgradeResponse(value) {
-    return typeof value === "object" && value !== null &&
-        value.kind === WEBSOCKET_UPGRADE_RESPONSE_KIND &&
-        value.status === 101;
+    if (typeof value !== "object" || value === null)
+        return false;
+    const kind = readDataProperty(value, "kind");
+    if (!kind.readable || kind.value !== WEBSOCKET_UPGRADE_RESPONSE_KIND)
+        return false;
+    const status = readDataProperty(value, "status");
+    if (!status.readable || status.value !== 101)
+        return false;
+    const statusText = readDataProperty(value, "statusText");
+    if (!statusText.readable || typeof statusText.value !== "string")
+        return false;
+    const headers = readDataProperty(value, "headers");
+    if (!headers.readable || typeof headers.value !== "object" || headers.value === null) {
+        return false;
+    }
+    try {
+        // Verify the native Headers internal slot without consulting hostile
+        // properties or Symbol.hasInstance hooks.
+        Reflect.apply(headersGet, headers.value, ["upgrade"]);
+    }
+    catch {
+        return false;
+    }
+    const body = readDataProperty(value, "body");
+    return body.readable && body.value === null;
 }

package/esm/src/platform/adapters/bounded-file-read.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Minimal handle contract shared by native filesystem adapters.
+ *
+ * The caller supplies the handle factory so each runtime can choose its native
+ * open semantics while this helper owns bounded chunking and cleanup.
+ */
+export interface BoundedFileReader {
+    read(buffer: Uint8Array): Promise<number | null>;
+}
+export interface BoundedFileReadHandle extends BoundedFileReader {
+    close(): void | Promise<void>;
+}
+export declare function requireBoundedFileReadLimit(byteLimit: unknown): number;
+/**
+ * Read at most `byteLimit` bytes without first materializing the whole file.
+ *
+ * A full-length result is intentionally ambiguous: callers that need to
+ * distinguish an exact-size file from an oversized file request their accepted
+ * maximum plus one byte.
+ */
+export declare function readBoundedFilePrefix(openHandle: () => Promise<BoundedFileReadHandle>, byteLimit: number): Promise<Uint8Array>;
+/**
+ * Read the complete file only when it fits within `byteLimit`.
+ *
+ * Unlike a prefix read, reaching the limit triggers one additional EOF probe.
+ * The probe reuses the final byte of the accepted buffer, so the helper never
+ * retains more than `byteLimit` bytes from the source.
+ */
+export declare function readFileWithinLimit(openHandle: () => Promise<BoundedFileReadHandle>, byteLimit: number): Promise<Uint8Array>;
+/** Read a bounded prefix while leaving ownership of the open handle to the caller. */
+export declare function readBoundedFileHandlePrefix(reader: BoundedFileReader, byteLimit: number): Promise<Uint8Array>;
+/** Read a complete bounded file while leaving ownership of the handle to the caller. */
+export declare function readFileHandleWithinLimit(reader: BoundedFileReader, byteLimit: number): Promise<Uint8Array>;
+//# sourceMappingURL=bounded-file-read.d.ts.map

package/esm/src/platform/adapters/bounded-file-read.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bounded-file-read.d.ts","sourceRoot":"","sources":["../../../../src/src/platform/adapters/bounded-file-read.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CAClD;AAED,MAAM,WAAW,qBAAsB,SAAQ,iBAAiB;IAC9D,KAAK,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/B;AAuGD,wBAAgB,2BAA2B,CAAC,SAAS,EAAE,OAAO,GAAG,MAAM,CAKtE;AAED;;;;;;GAMG;AACH,wBAAsB,qBAAqB,CACzC,UAAU,EAAE,MAAM,OAAO,CAAC,qBAAqB,CAAC,EAChD,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,UAAU,CAAC,CAMrB;AAED;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CACvC,UAAU,EAAE,MAAM,OAAO,CAAC,qBAAqB,CAAC,EAChD,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,UAAU,CAAC,CAMrB;AAED,sFAAsF;AACtF,wBAAsB,2BAA2B,CAC/C,MAAM,EAAE,iBAAiB,EACzB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,UAAU,CAAC,CAoDrB;AAED,wFAAwF;AACxF,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,iBAAiB,EACzB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,UAAU,CAAC,CAuBrB"}

package/esm/src/platform/adapters/bounded-file-read.js

@@ -0,0 +1,179 @@
+const apply = Reflect.apply;
+const arrayPush = Array.prototype.push;
+const minimum = Math.min;
+const numberIsSafeInteger = Number.isSafeInteger;
+const NativeUint8Array = Uint8Array;
+const typedArrayPrototype = Object.getPrototypeOf(NativeUint8Array.prototype);
+const typedArrayByteLengthGetterCandidate = Object.getOwnPropertyDescriptor(typedArrayPrototype, "byteLength")?.get;
+const typedArrayBufferGetterCandidate = Object.getOwnPropertyDescriptor(typedArrayPrototype, "buffer")?.get;
+const typedArrayByteOffsetGetterCandidate = Object.getOwnPropertyDescriptor(typedArrayPrototype, "byteOffset")?.get;
+const setBytes = NativeUint8Array.prototype.set;
+if (typeof typedArrayByteLengthGetterCandidate !== "function" ||
+    typeof typedArrayBufferGetterCandidate !== "function" ||
+    typeof typedArrayByteOffsetGetterCandidate !== "function") {
+    throw new TypeError("Required Uint8Array intrinsics are unavailable");
+}
+const typedArrayByteLengthGetter = typedArrayByteLengthGetterCandidate;
+const typedArrayBufferGetter = typedArrayBufferGetterCandidate;
+const typedArrayByteOffsetGetter = typedArrayByteOffsetGetterCandidate;
+function byteLengthOf(value) {
+    const byteLength = apply(typedArrayByteLengthGetter, value, []);
+    if (!numberIsSafeInteger(byteLength) || byteLength < 0) {
+        throw new TypeError("Filesystem read buffer has an invalid byte length");
+    }
+    return byteLength;
+}
+function allocateBytes(byteLength) {
+    const bytes = new NativeUint8Array(byteLength);
+    if (byteLengthOf(bytes) !== byteLength) {
+        throw new TypeError("Filesystem byte buffer allocation returned an invalid size");
+    }
+    return bytes;
+}
+function viewBytes(value, start, byteLength) {
+    const sourceByteLength = byteLengthOf(value);
+    if (!numberIsSafeInteger(start) || start < 0 ||
+        !numberIsSafeInteger(byteLength) || byteLength < 0 ||
+        start > sourceByteLength - byteLength) {
+        throw new RangeError("Filesystem byte view is outside its source buffer");
+    }
+    const buffer = apply(typedArrayBufferGetter, value, []);
+    const byteOffset = apply(typedArrayByteOffsetGetter, value, []);
+    const view = new NativeUint8Array(buffer, byteOffset + start, byteLength);
+    if (byteLengthOf(view) !== byteLength) {
+        throw new TypeError("Filesystem byte view allocation returned an invalid size");
+    }
+    return view;
+}
+// Keep a large caller-supplied limit from becoming an equally large eager
+// allocation when the source is small. The aggregate returned data remains
+// bounded by the caller's limit.
+const BOUNDED_FILE_READ_CHUNK_BYTES = 64 * 1024;
+async function readAndCloseHandle(openHandle, read) {
+    const handle = await openHandle();
+    let result;
+    let primaryFailure;
+    let primaryFailed = false;
+    try {
+        result = await read(handle);
+    }
+    catch (error) {
+        primaryFailed = true;
+        primaryFailure = error;
+    }
+    try {
+        await handle.close();
+    }
+    catch (cleanupFailure) {
+        if (primaryFailed) {
+            throw new AggregateError([primaryFailure, cleanupFailure], "Filesystem read and handle cleanup both failed");
+        }
+        throw cleanupFailure;
+    }
+    if (primaryFailed)
+        throw primaryFailure;
+    return result;
+}
+export function requireBoundedFileReadLimit(byteLimit) {
+    if (!numberIsSafeInteger(byteLimit) || byteLimit <= 0) {
+        throw new RangeError("Filesystem byteLimit must be a positive safe integer");
+    }
+    return byteLimit;
+}
+/**
+ * Read at most `byteLimit` bytes without first materializing the whole file.
+ *
+ * A full-length result is intentionally ambiguous: callers that need to
+ * distinguish an exact-size file from an oversized file request their accepted
+ * maximum plus one byte.
+ */
+export async function readBoundedFilePrefix(openHandle, byteLimit) {
+    const boundedLimit = requireBoundedFileReadLimit(byteLimit);
+    return await readAndCloseHandle(openHandle, (handle) => readBoundedFileHandlePrefix(handle, boundedLimit));
+}
+/**
+ * Read the complete file only when it fits within `byteLimit`.
+ *
+ * Unlike a prefix read, reaching the limit triggers one additional EOF probe.
+ * The probe reuses the final byte of the accepted buffer, so the helper never
+ * retains more than `byteLimit` bytes from the source.
+ */
+export async function readFileWithinLimit(openHandle, byteLimit) {
+    const boundedLimit = requireBoundedFileReadLimit(byteLimit);
+    return await readAndCloseHandle(openHandle, (handle) => readFileHandleWithinLimit(handle, boundedLimit));
+}
+/** Read a bounded prefix while leaving ownership of the open handle to the caller. */
+export async function readBoundedFileHandlePrefix(reader, byteLimit) {
+    const boundedLimit = requireBoundedFileReadLimit(byteLimit);
+    const chunks = [];
+    let byteLength = 0;
+    let reachedEnd = false;
+    while (byteLength < boundedLimit) {
+        const chunk = allocateBytes(minimum(BOUNDED_FILE_READ_CHUNK_BYTES, boundedLimit - byteLength));
+        let chunkLength = 0;
+        const chunkByteLength = byteLengthOf(chunk);
+        while (chunkLength < chunkByteLength) {
+            const remaining = viewBytes(chunk, chunkLength, chunkByteLength - chunkLength);
+            const bytesRead = await reader.read(remaining);
+            if (bytesRead === null || bytesRead === 0) {
+                reachedEnd = true;
+                break;
+            }
+            if (!numberIsSafeInteger(bytesRead) ||
+                bytesRead < 0 ||
+                bytesRead > byteLengthOf(remaining)) {
+                throw new TypeError("Filesystem read returned an invalid byte count");
+            }
+            chunkLength += bytesRead;
+            byteLength += bytesRead;
+        }
+        if (chunkLength > 0) {
+            // Copy a short final chunk so a tiny result does not retain the entire
+            // fixed-size read buffer.
+            if (chunkLength === chunkByteLength) {
+                apply(arrayPush, chunks, [chunk]);
+            }
+            else {
+                const shortChunk = allocateBytes(chunkLength);
+                apply(setBytes, shortChunk, [viewBytes(chunk, 0, chunkLength)]);
+                apply(arrayPush, chunks, [shortChunk]);
+            }
+        }
+        if (reachedEnd)
+            break;
+    }
+    if (chunks.length === 0)
+        return allocateBytes(0);
+    if (chunks.length === 1)
+        return chunks[0];
+    const bytes = allocateBytes(byteLength);
+    let offset = 0;
+    for (let index = 0; index < chunks.length; index++) {
+        const chunk = chunks[index];
+        apply(setBytes, bytes, [chunk, offset]);
+        offset += byteLengthOf(chunk);
+    }
+    return bytes;
+}
+/** Read a complete bounded file while leaving ownership of the handle to the caller. */
+export async function readFileHandleWithinLimit(reader, byteLimit) {
+    const boundedLimit = requireBoundedFileReadLimit(byteLimit);
+    const bytes = await readBoundedFileHandlePrefix(reader, boundedLimit);
+    if (byteLengthOf(bytes) < boundedLimit)
+        return bytes;
+    // Reuse the final accepted byte as the EOF probe instead of allocating or
+    // retaining a maximum-plus-one buffer. Restore it when the file ends exactly
+    // at the limit; on overflow the result is discarded.
+    const finalIndex = boundedLimit - 1;
+    const acceptedFinalByte = bytes[finalIndex];
+    const probe = viewBytes(bytes, finalIndex, 1);
+    const bytesRead = await reader.read(probe);
+    if (bytesRead === null || bytesRead === 0) {
+        bytes[finalIndex] = acceptedFinalByte;
+        return bytes;
+    }
+    if (!numberIsSafeInteger(bytesRead) || bytesRead < 0 || bytesRead > byteLengthOf(probe)) {
+        throw new TypeError("Filesystem read returned an invalid byte count");
+    }
+    throw new RangeError(`File exceeds byte limit of ${boundedLimit} ${boundedLimit === 1 ? "byte" : "bytes"}`);
+}

package/esm/src/platform/adapters/file-snapshot-error.d.ts

@@ -0,0 +1,6 @@
+export declare class FileSnapshotChangedError extends Error {
+    readonly name = "FileSnapshotChangedError";
+    constructor(message?: string);
+}
+export declare function isFileSnapshotChangedError(value: unknown): value is FileSnapshotChangedError;
+//# sourceMappingURL=file-snapshot-error.d.ts.map

package/esm/src/platform/adapters/file-snapshot-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-snapshot-error.d.ts","sourceRoot":"","sources":["../../../../src/src/platform/adapters/file-snapshot-error.ts"],"names":[],"mappings":"AAEA,qBAAa,wBAAyB,SAAQ,KAAK;IACjD,SAAkB,IAAI,8BAA8B;gBAExC,OAAO,SAA0C;CAI9D;AAED,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,OAAO,GACb,KAAK,IAAI,wBAAwB,CAEnC"}

package/esm/src/platform/adapters/file-snapshot-error.js

@@ -0,0 +1,11 @@
+const changedErrors = new WeakSet();
+export class FileSnapshotChangedError extends Error {
+    name = "FileSnapshotChangedError";
+    constructor(message = "File snapshot changed during the read") {
+        super(message);
+        changedErrors.add(this);
+    }
+}
+export function isFileSnapshotChangedError(value) {
+    return typeof value === "object" && value !== null && changedErrors.has(value);
+}

package/esm/src/platform/adapters/runtime/shared/native-file-capabilities.d.ts

@@ -0,0 +1,33 @@
+interface SnapshotStat {
+    readonly dev: bigint;
+    readonly ino: bigint;
+    readonly size: bigint;
+    readonly mtimeNs: bigint;
+    readonly ctimeNs: bigint;
+    isFile(): boolean;
+    isSymbolicLink(): boolean;
+}
+interface SnapshotHandle {
+    stat(): Promise<SnapshotStat>;
+    read(buffer: Uint8Array, offset: number, length: number, position: number): Promise<{
+        bytesRead: number;
+    }>;
+    writeFile(content: Uint8Array): Promise<void>;
+    close(): Promise<void>;
+}
+export interface NativeSnapshotOperations {
+    realpath(path: string): Promise<string>;
+    lstat(path: string): Promise<SnapshotStat>;
+    open(path: string, flags: number | string): Promise<SnapshotHandle>;
+}
+/** Whether the runtime can enforce a no-follow native snapshot open. */
+export declare function supportsNativeFileSnapshots(platform?: "posix" | "windows"): boolean;
+/**
+ * Read one verified regular-file generation without following a terminal link.
+ * Identity and generation are checked before and after the bounded positional read.
+ */
+export declare function readNodeFileSnapshotWithinLimit(path: string, containmentRoot: string, byteLimit: number, operations?: NativeSnapshotOperations): Promise<Uint8Array>;
+/** Create a new file without replacement and join handle cleanup. */
+export declare function createNodeFileBytesExclusive(path: string, content: Uint8Array, operations?: NativeSnapshotOperations): Promise<void>;
+export {};
+//# sourceMappingURL=native-file-capabilities.d.ts.map

package/esm/src/platform/adapters/runtime/shared/native-file-capabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"native-file-capabilities.d.ts","sourceRoot":"","sources":["../../../../../../src/src/platform/adapters/runtime/shared/native-file-capabilities.ts"],"names":[],"mappings":"AAIA,UAAU,YAAY;IACpB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,MAAM,IAAI,OAAO,CAAC;IAClB,cAAc,IAAI,OAAO,CAAC;CAC3B;AAED,UAAU,cAAc;IACtB,IAAI,IAAI,OAAO,CAAC,YAAY,CAAC,CAAC;IAC9B,IAAI,CACF,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAClC,SAAS,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACxC,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IAC3C,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;CACrE;AAED,wEAAwE;AACxE,wBAAgB,2BAA2B,CACzC,QAAQ,GAAE,OAAO,GAAG,SAA2D,GAC9E,OAAO,CAET;AAkFD;;;GAGG;AACH,wBAAsB,+BAA+B,CACnD,IAAI,EAAE,MAAM,EACZ,eAAe,EAAE,MAAM,EACvB,SAAS,EAAE,MAAM,EACjB,UAAU,CAAC,EAAE,wBAAwB,GACpC,OAAO,CAAC,UAAU,CAAC,CAsHrB;AAED,qEAAqE;AACrE,wBAAsB,4BAA4B,CAChD,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,UAAU,EACnB,UAAU,CAAC,EAAE,wBAAwB,GACpC,OAAO,CAAC,IAAI,CAAC,CAYf"}

package/esm/src/platform/adapters/runtime/shared/native-file-capabilities.js

@@ -0,0 +1,205 @@
+import { isAbsolute, relative, resolve, sep } from "../../../compat/path/index.js";
+import { runtimeUsesWindowsPaths } from "../../../compat/path/portable.js";
+import { FileSnapshotChangedError } from "../../file-snapshot-error.js";
+/** Whether the runtime can enforce a no-follow native snapshot open. */
+export function supportsNativeFileSnapshots(platform = runtimeUsesWindowsPaths() ? "windows" : "posix") {
+    return platform === "posix";
+}
+function toSnapshotStat(stats) {
+    return {
+        dev: stats.dev,
+        ino: stats.ino,
+        size: stats.size,
+        mtimeNs: stats.mtimeNs,
+        ctimeNs: stats.ctimeNs,
+        isFile: () => stats.isFile(),
+        isSymbolicLink: () => stats.isSymbolicLink(),
+    };
+}
+async function defaultOperations() {
+    const fs = await import("node:fs/promises");
+    return {
+        realpath: (path) => fs.realpath(path),
+        async lstat(path) {
+            return toSnapshotStat(await fs.lstat(path, { bigint: true }));
+        },
+        async open(path, flags) {
+            const handle = await fs.open(path, flags);
+            return {
+                async stat() {
+                    return toSnapshotStat(await handle.stat({ bigint: true }));
+                },
+                read: (buffer, offset, length, position) => handle.read(buffer, offset, length, position),
+                writeFile: (content) => handle.writeFile(content),
+                close: () => handle.close(),
+            };
+        },
+    };
+}
+function requireByteLimit(value) {
+    if (!Number.isSafeInteger(value) || value <= 0) {
+        throw new RangeError("Snapshot byte limit must be a positive safe integer");
+    }
+    return value;
+}
+function isContainedPath(path, root) {
+    const relation = relative(root, path);
+    return relation === "" ||
+        (relation !== ".." && !relation.startsWith(`..${sep}`) && !isAbsolute(relation));
+}
+function sameIdentity(left, right) {
+    return left.dev === right.dev && left.ino === right.ino;
+}
+function sameGeneration(left, right) {
+    return sameIdentity(left, right) && left.size === right.size &&
+        left.mtimeNs === right.mtimeNs && left.ctimeNs === right.ctimeNs;
+}
+function changed(message, cause) {
+    const error = new FileSnapshotChangedError(message);
+    if (cause !== undefined)
+        Object.defineProperty(error, "cause", { value: cause });
+    return error;
+}
+async function closeSnapshotHandle(handle, primaryFailure, failed) {
+    try {
+        await handle.close();
+    }
+    catch (cleanupFailure) {
+        if (failed) {
+            throw new AggregateError([primaryFailure, cleanupFailure], "Filesystem snapshot read and handle cleanup both failed");
+        }
+        throw cleanupFailure;
+    }
+    if (failed)
+        throw primaryFailure;
+}
+/**
+ * Read one verified regular-file generation without following a terminal link.
+ * Identity and generation are checked before and after the bounded positional read.
+ */
+export async function readNodeFileSnapshotWithinLimit(path, containmentRoot, byteLimit, operations) {
+    const admittedLimit = requireByteLimit(byteLimit);
+    const lexicalRoot = resolve(containmentRoot);
+    const candidate = resolve(path);
+    const fsOperations = operations ?? await defaultOperations();
+    const { constants } = await import("node:fs");
+    if (!Number.isSafeInteger(constants.O_NOFOLLOW) || constants.O_NOFOLLOW === 0) {
+        throw new TypeError("This runtime cannot guarantee no-follow snapshot opens");
+    }
+    const canonicalRoot = await fsOperations.realpath(lexicalRoot);
+    if (!isContainedPath(candidate, lexicalRoot) &&
+        !isContainedPath(candidate, canonicalRoot)) {
+        throw new TypeError("Snapshot path must be contained by the requested root");
+    }
+    const pathnameBefore = await fsOperations.lstat(candidate);
+    if (pathnameBefore.isSymbolicLink()) {
+        throw new TypeError("Snapshot path must not be a symbolic link");
+    }
+    if (!pathnameBefore.isFile()) {
+        throw new TypeError("Snapshot path must identify a regular file");
+    }
+    let handle;
+    try {
+        handle = await fsOperations.open(candidate, constants.O_RDONLY | constants.O_NOFOLLOW);
+    }
+    catch (cause) {
+        throw changed("File identity became uncertain while opening the snapshot", cause);
+    }
+    let failed = false;
+    let primaryFailure;
+    let result;
+    try {
+        let handleBefore;
+        try {
+            handleBefore = await handle.stat();
+        }
+        catch (cause) {
+            throw changed("Opened file identity could not be verified", cause);
+        }
+        if (!handleBefore.isFile() || !sameGeneration(pathnameBefore, handleBefore)) {
+            throw changed("File identity changed while opening the snapshot");
+        }
+        let canonicalTarget;
+        let pathnameOpened;
+        try {
+            [canonicalTarget, pathnameOpened] = await Promise.all([
+                fsOperations.realpath(candidate),
+                fsOperations.lstat(candidate),
+            ]);
+        }
+        catch (cause) {
+            throw changed("File target became uncertain while opening the snapshot", cause);
+        }
+        if (pathnameOpened.isSymbolicLink() || !pathnameOpened.isFile() ||
+            !sameGeneration(handleBefore, pathnameOpened)) {
+            throw changed("File identity changed while opening the snapshot");
+        }
+        if (!isContainedPath(canonicalTarget, canonicalRoot)) {
+            throw new TypeError("Snapshot target must be contained by the canonical root");
+        }
+        if (handleBefore.size < 0n) {
+            throw changed("File size became uncertain while opening the snapshot");
+        }
+        if (handleBefore.size > BigInt(admittedLimit)) {
+            throw new RangeError(`File exceeds byte limit of ${admittedLimit} bytes`);
+        }
+        const size = Number(handleBefore.size);
+        let bytes;
+        try {
+            bytes = new Uint8Array(size);
+        }
+        catch (cause) {
+            throw new Error("Unable to allocate the admitted snapshot buffer", { cause });
+        }
+        let offset = 0;
+        while (offset < size) {
+            const { bytesRead } = await handle.read(bytes, offset, size - offset, offset);
+            if (!Number.isSafeInteger(bytesRead) || bytesRead <= 0 || bytesRead > size - offset) {
+                throw changed("File size changed while reading the snapshot");
+            }
+            offset += bytesRead;
+        }
+        let handleAfter;
+        let pathnameAfter;
+        let canonicalTargetAfter;
+        try {
+            [handleAfter, pathnameAfter, canonicalTargetAfter] = await Promise.all([
+                handle.stat(),
+                fsOperations.lstat(candidate),
+                fsOperations.realpath(candidate),
+            ]);
+        }
+        catch (cause) {
+            throw changed("File identity became uncertain after reading the snapshot", cause);
+        }
+        if (pathnameAfter.isSymbolicLink() || !pathnameAfter.isFile() ||
+            !sameGeneration(handleBefore, handleAfter) ||
+            !sameGeneration(handleBefore, pathnameAfter) ||
+            canonicalTargetAfter !== canonicalTarget ||
+            !isContainedPath(canonicalTargetAfter, canonicalRoot)) {
+            throw changed("File snapshot changed during the read");
+        }
+        result = bytes;
+    }
+    catch (error) {
+        failed = true;
+        primaryFailure = error;
+    }
+    await closeSnapshotHandle(handle, primaryFailure, failed);
+    return result;
+}
+/** Create a new file without replacement and join handle cleanup. */
+export async function createNodeFileBytesExclusive(path, content, operations) {
+    const fsOperations = operations ?? await defaultOperations();
+    const handle = await fsOperations.open(path, "wx");
+    let failed = false;
+    let primaryFailure;
+    try {
+        await handle.writeFile(content);
+    }
+    catch (error) {
+        failed = true;
+        primaryFailure = error;
+    }
+    await closeSnapshotHandle(handle, primaryFailure, failed);
+}

package/esm/src/platform/compat/fs.d.ts

@@ -1,10 +1,16 @@
 import type { FileInfo } from "../adapters/base.js";
+export { isNotFoundError } from "./not-found-error.js";
 /** Public API contract for file system. */
 export interface FileSystem {
     readTextFile(path: string): Promise<string>;
     readFile(path: string): Promise<Uint8Array>;
+    readFileBytesWithinLimit?(path: string, byteLimit: number): Promise<Uint8Array>;
+    readFileSnapshotWithinLimit?(path: string, containmentRoot: string, byteLimit: number): Promise<Uint8Array>;
     writeTextFile(path: string, data: string): Promise<void>;
     writeFile(path: string, data: Uint8Array): Promise<void>;
+    /** Atomically replace a path when same-filesystem rename is supported. */
+    createFileBytesExclusive?(path: string, data: Uint8Array): Promise<void>;
+    rename?(from: string, to: string): Promise<void>;
     exists(path: string): Promise<boolean>;
     stat(path: string): Promise<FileInfo>;
     lstat?(path: string): Promise<FileInfo>;
@@ -69,8 +75,6 @@ export declare function symlink(target: string, path: string): Promise<void>;
  * symlink could otherwise escape an intended directory.
  */
 export declare function realPath(path: string): Promise<string>;
-/** Error shape for is not found. */
-export declare function isNotFoundError(error: unknown, seen?: Set<unknown>): boolean;
 /** Error shape for is already exists. */
 export declare function isAlreadyExistsError(error: unknown): boolean;
 //# sourceMappingURL=fs.d.ts.map

package/esm/src/platform/compat/fs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fs.d.ts","sourceRoot":"","sources":["../../../../src/src/platform/compat/fs.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"fs.d.ts","sourceRoot":"","sources":["../../../../src/src/platform/compat/fs.ts"],"names":[],"mappings":"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"}