@poe-platform/safe-fs 0.1.722 → 0.1.724

package/README.md

@@ -25,7 +25,7 @@ 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 the relative-path base and, by default, the confinement boundary. Set an explicit `root` to use a different boundary, for example `{ cwd: "/work", root: "/" }` to address a complete provider namespace. The bridge supports `unlink` when the provider offers atomic file removal; unsupported methods fail without host fallback. `createHostFileSystem()` provides trusted, unrestricted native host access when a rooted adapter is not desired.
 
-For host storage, use `await createRealFileSystem({ root: "/absolute/existing/directory" })` instead. The root must already exist; virtual `/` maps to that directory. ZIP creation, updates, and extraction can use this adapter's private owned staging in an isolated host tree. Its `trustedOwnedStaging` capability checks original entries before publication and cleanup, and preserves foreign staging children. It does not advertise atomic conditional mutations: keep external writers and other in-flight writes away from the tree during these operations. Read the safety boundary below before exposing it to untrusted code.
+For host storage, use `await createRealFileSystem({ root: "/absolute/existing/directory" })` instead. The root must already exist; virtual `/` maps to that directory. ZIP creation and updates can use this adapter's private owned staging in an isolated host tree. Unzip extraction requires atomic ancestry verification, currently supported by MemoryFileSystem; the real adapter and mount views refuse it. Its `trustedOwnedStaging` capability checks original entries before publication and cleanup, and preserves foreign staging children. It does not advertise atomic conditional mutations: keep external writers and other in-flight writes away from the tree during these operations. Read the safety boundary below before exposing it to untrusted code.
 
 To create new outputs with Safe Bash's `dos2unix`, `unix2dos`, or compression commands, host adapters need atomic no-replace publication. Supply `createRealFileSystem({ root, renameNoReplace })` only when that callback binds a qualified native primitive such as Linux `renameat2` with `RENAME_NOREPLACE`. It receives resolved absolute host paths and an optional signal in its third argument. Existing destinations must reject `EEXIST` atomically; existence checks followed by rename and copy/delete are insufficient. Without this binding the adapter explicitly refuses those operations. See the [no-replace contract](src/contracts/filesystem.md#atomic-no-replace-rename).
 
@@ -109,7 +109,7 @@ before implementing the host operation; ordinary writes do not provide it.
 | `createOverlayFileSystem({ upper, lower })` | Reading through to a lower layer and writing changes to an upper layer |
 | `withFileSystemQuota(filesystem, { maxBytes })` | Enforcing a cumulative logical-byte ceiling across every write path |
 
-`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.
+`createNodeFsBridge` offers a promises-shaped subset, including recursive `cp` and `mkdtemp`. A trusted `reserveReadFile` callback can reserve host resources and return a release function; cancellation retains the reservation until the backend read settles. The portable `createFsBridge` from `@poe-platform/safe-fs/core` instead requires a caller-supplied text codec and returns `Uint8Array` values.
 
 ## Write an adapter
 
@@ -233,8 +233,8 @@ There are no package environment variables, implicit credentials, or automatic `
 | Mount | Required `root`: fallback filesystem. `mounts` defaults to `{}` and maps absolute virtual paths to filesystems. |
 | Overlay | Required `upper` and `lower`; `maxBufferBytes` is unlimited unless configured. |
 | Quota | `withFileSystemQuota` requires a nonnegative safe-integer `maxBytes`. It serializes mutations and counts files, symlinks, copies, hard links, truncation, and streaming writes. |
-| 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. |
+| Node bridge | `cwd` defaults to `/`, must be an absolute virtual path; optional lifetime `signal` and trusted `readFileMaxBytes` cap forwarded to backend reads before copy/decode. |
+| Portable bridge | Same `cwd`, `signal` and `readFileMaxBytes`, 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

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

@@ -16,6 +16,8 @@ export declare class FileSystemBridge<Binary extends Uint8Array> {
         readonly cwd?: string;
         readonly root?: string;
         readonly signal?: AbortSignal;
+        readonly readFileMaxBytes?: number;
+        readonly reserveReadFile?: () => () => void;
     }, primitives: BridgePrimitives<Binary>);
     readFile(path: unknown, options?: {
         encoding?: null | undefined;

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

@@ -44,6 +44,8 @@ export class FileSystemBridge {
     #cwd;
     #root;
     #signal;
+    #readFileMaxBytes;
+    #reserveReadFile;
     #primitives;
     #codec;
     constructor(fs, options, primitives) {
@@ -67,6 +69,13 @@ export class FileSystemBridge {
         this.#root = primitives.paths.resolve("/", options.root ?? cwd);
         assertBridgePath(this.#root, this.#cwd);
         this.#signal = options.signal;
+        const maximum = options.readFileMaxBytes;
+        if (maximum !== undefined && (!Number.isSafeInteger(maximum) || maximum < 0))
+            throw new TypeError("Invalid readFileMaxBytes");
+        this.#readFileMaxBytes = maximum;
+        if (options.reserveReadFile !== undefined && typeof options.reserveReadFile !== "function")
+            throw new TypeError("Invalid reserveReadFile");
+        this.#reserveReadFile = options.reserveReadFile;
     }
     #encoding(value, fallback, names = false) {
         const selected = value == null ? fallback : value;
@@ -121,9 +130,29 @@ export class FileSystemBridge {
         if (options.encoding === "buffer")
             throw new TypeError("Invalid read encoding");
         const codec = this.#encoding(options.encoding, "buffer");
-        const bytes = await this.#call([path], (signal, resolved) => this.#fs.readFile(resolved[0], signal), options.signal);
-        const buffer = this.#primitives.copyBytes(bytes);
-        return codec === "buffer" ? buffer : this.#codec.decode(buffer, codec);
+        const maxBytes = this.#readFileMaxBytes;
+        const release = this.#reserveReadFile?.();
+        let pending;
+        try {
+            const bytes = await this.#call([path], (signal, resolved) => {
+                pending = this.#fs.readFile(resolved[0], { ...signal, ...(maxBytes === undefined ? {} : { maxBytes }) });
+                return pending;
+            }, options.signal);
+            if (maxBytes !== undefined && bytes.byteLength > maxBytes)
+                throw fsError("EFBIG", "readFile");
+            const buffer = this.#primitives.copyBytes(bytes);
+            return codec === "buffer" ? buffer : this.#codec.decode(buffer, codec);
+        }
+        finally {
+            // Cancellation may reject #call before a backend acknowledges it. Keep
+            // its reservation until the actual read settles, as well as through decode.
+            if (release !== undefined) {
+                if (pending === undefined)
+                    release();
+                else
+                    void pending.then(release, release);
+            }
+        }
     }
     async #write(path, data, value, fallback) {
         const options = optionsRecord(value, ["encoding", "flag", "mode", "flush", "signal"]);

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

@@ -10,6 +10,10 @@ export interface FsBridgeOptions {
     /** Optional confinement boundary; defaults to cwd. */
     readonly root?: string;
     readonly signal?: AbortSignal;
+    /** Trusted per-read backend byte cap, enforced before copying or decoding. */
+    readonly readFileMaxBytes?: number;
+    /** Reserve host resources; release after decoding and actual backend settlement, including cancellation. */
+    readonly reserveReadFile?: () => () => void;
 }
 export interface FsBridgeFileSystem extends FileSystem {
     rmdir?(path: string, options?: FsOptions): Promise<void>;

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

@@ -70,6 +70,8 @@ export interface FileSystemCapabilities {
     /** Owned staging serialized within a trusted host; requires external tree isolation. */
     readonly trustedOwnedStaging?: boolean;
     readonly atomicFileStaging?: boolean;
+    /** Atomically verifies every supplied root-to-parent directory identity at publication. */
+    readonly atomicStagingAncestry?: boolean;
     readonly atomicFilePublication?: boolean;
     readonly atomicFileMutation?: boolean;
     readonly atomicEntryRemoval?: boolean;
@@ -206,6 +208,7 @@ export interface CreateStagedFileOptions extends FsOptions {
     readonly mtimeMs?: number;
 }
 export interface PublishStagedFileOptions extends FsOptions {
+    readonly ancestors?: readonly FileStagingEntry[];
     readonly parent: FileStat;
     readonly destination: FileStat | null;
 }

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

@@ -35,6 +35,7 @@ export declare class MemoryFileSystem implements FileSystem {
         timestamps: true;
         atomicRename: true;
         atomicFileStaging: true;
+        atomicStagingAncestry: true;
         atomicFileMutation: true;
         atomicEntryRemoval: true;
         atomicTreeRemoval: true;

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

@@ -68,7 +68,7 @@ export class MemoryFileSystem {
             permissions: true,
             timestamps: true,
             atomicRename: true,
-            atomicFileStaging: true, atomicFileMutation: true, atomicEntryRemoval: true, atomicTreeRemoval: true,
+            atomicFileStaging: true, atomicStagingAncestry: true, atomicFileMutation: true, atomicEntryRemoval: true, atomicTreeRemoval: true,
             atomicDirectoryMetadata: true,
             streamingRead: true,
             retainedRead: true,
@@ -134,7 +134,7 @@ export class MemoryFileSystem {
             }
             retained.set("/", this.root);
         }
-        const allowed = new Set(["mkdir", "rm", "rmdir", "rename", "symlink", "link", "chmod", "utimes", "writeFile", "appendFile", "writeStream"]);
+        const allowed = new Set(["mkdir", "rm", "rmdir", "rename", "symlink", "link", "chmod", "utimes", "writeFile", "appendFile", "writeStream", "writeFileConditional", "removeFileConditional"]);
         const reads = new Set(["access", "capabilitiesFor", "compareEntry", "lstat", "stat", "readFile", "readStream", "readdir", "readlink", "realpath"]);
         const check = (path, followFinal) => {
             if (!roots.some(root => root === "/" || path === root || path.startsWith(`${root}/`)))
@@ -172,7 +172,7 @@ export class MemoryFileSystem {
                     for (const path of paths) {
                         if (typeof path !== "string")
                             throw new FsError("EINVAL");
-                        check(path, ["chmod", "utimes", "appendFile", "writeFile", "writeStream", "link"].includes(String(property)));
+                        check(path, ["chmod", "utimes", "appendFile", "writeFile", "writeStream", "writeFileConditional", "link"].includes(String(property)));
                     }
                     return Reflect.apply(value, target, args);
                 };
@@ -655,6 +655,25 @@ export class MemoryFileSystem {
     }
     async publishStagedFile(staging, destination, options) {
         options.signal?.throwIfAborted();
+        if (options.ancestors) {
+            let path = "/";
+            const parentPath = destination.slice(0, destination.lastIndexOf("/")) || "/";
+            const paths = ["/", ...parentPath.split("/").filter(Boolean).map(component => {
+                    path = path === "/" ? `/${component}` : `${path}/${component}`;
+                    return path;
+                })];
+            if (paths.length !== options.ancestors.length)
+                this.fail("EINVAL", "publishStagedFile", destination);
+            for (let index = 0; index < paths.length; index++) {
+                const expected = options.ancestors[index];
+                if (expected.path !== paths[index])
+                    this.fail("EINVAL", "publishStagedFile", destination);
+                const entry = this.entry(expected.path, "publishStagedFile");
+                if (entry.node?.type !== "directory")
+                    this.fail("EAGAIN", "publishStagedFile", destination);
+                this.expectEntry(entry.node, expected.stat, expected.path, false);
+            }
+        }
         const { directory, file } = this.stagingLocations(staging);
         this.expectEntry(file.node, staging.file.stat, staging.file.path);
         const target = this.entry(destination, "publishStagedFile", true);

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

@@ -131,6 +131,7 @@ export class MountFileSystem {
             readOnly: all("readOnly"),
             ...(append === undefined ? {} : { append }),
             ...semantics,
+            atomicStagingAncestry: false,
             atomicRename: mounts.length === 1 && all("atomicRename"),
             ...(streamingRead === undefined ? {} : { streamingRead }),
             ...(streamingWrite === undefined ? {} : { streamingWrite }),
@@ -154,7 +155,7 @@ export class MountFileSystem {
                 ? { ...observed, descriptorWriteStream: false } : observed;
             const resize = declared.atomicResize === true && (typeof location.mount.backend.resizeFile !== "function" || declared.readOnly === true)
                 ? { ...declared, atomicResize: false } : declared;
-            const withOpen = { ...resize, ...(typeof location.mount.backend.open === "function" ? {} : { open: false }) };
+            const withOpen = { ...resize, atomicStagingAncestry: false, ...(typeof location.mount.backend.open === "function" ? {} : { open: false }) };
             const capabilities = location.synthetic ? { ...withOpen, open: false, retainedRead: false }
                 : retainedResizeCapabilities(location.mount.backend, retainedReadCapabilities(location.mount.backend, withOpen));
             if (location.synthetic)

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

@@ -2,11 +2,15 @@ import type { FileStat, FileSystem, FsOptions, OpenFileOptions } from "../../con
 import type { ByteSource } from "../../contracts/io.js";
 export interface ObjectFileVersion {
     readonly revision: string;
+    /** Opaque lease/reservation token; independent of namespace revision. */
+    readonly publicationToken?: string;
     readonly stat: FileStat;
     read(position: number, maxBytes: number, options?: FsOptions): Promise<Uint8Array>;
     close(): Promise<void>;
 }
 export interface ObjectFilePublicationOptions extends FsOptions {
+    /** Token from this descriptor's current retained version, if supplied by its store. */
+    readonly previousToken?: string;
     readonly size: number;
     readonly mode: number;
 }

package/dist/safe-fs/fs/object-publication/index.js

@@ -50,6 +50,7 @@ export function withObjectFileDescriptors(filesystem, store, options = {}) {
     };
     const version = (value) => {
         if (!value || typeof value.revision !== "string" || value.revision.length === 0 || value.revision.length > 4096
+            || value.publicationToken !== undefined && (typeof value.publicationToken !== "string" || value.publicationToken.length === 0 || value.publicationToken.length > 4096)
             || !value.stat || value.stat.type !== "file" || !Number.isSafeInteger(value.stat.size) || value.stat.size < 0
             || !Number.isSafeInteger(value.stat.mode) || value.stat.mode < 0 || value.stat.mode > 0o177777
             || ![value.stat.mtimeMs, value.stat.atimeMs, value.stat.ctimeMs].every(Number.isFinite)
@@ -57,7 +58,7 @@ export function withObjectFileDescriptors(filesystem, store, options = {}) {
             throw new FsError("EIO", { message: "Invalid immutable object version" });
         if (value.stat.size > maxFileBytes)
             throw new FsError("EFBIG", { message: "Object descriptor file limit exceeded" });
-        return Object.freeze({ revision: value.revision, stat: Object.freeze({ ...value.stat }), read: value.read.bind(value), close: value.close.bind(value) });
+        return Object.freeze({ revision: value.revision, ...(value.publicationToken === undefined ? {} : { publicationToken: value.publicationToken }), stat: Object.freeze({ ...value.stat }), read: value.read.bind(value), close: value.close.bind(value) });
     };
     const clearPages = (state) => {
         stagedBytes -= state.pages.size * chunkBytes;
@@ -181,7 +182,7 @@ export function withObjectFileDescriptors(filesystem, store, options = {}) {
                             yield bytes;
                         }
                     })();
-                    received = await store.publish(path, expected, source, { ...selected, size: state.size, mode: (state.head?.stat.mode ?? admitted.mode) & 0o7777 });
+                    received = await store.publish(path, expected, source, { ...selected, ...(state.head?.publicationToken === undefined ? {} : { previousToken: state.head.publicationToken }), size: state.size, mode: (state.head?.stat.mode ?? admitted.mode) & 0o7777 });
                 });
                 const published = version(received);
                 if (emitted !== state.size || published.stat.size !== state.size || published.revision === expected)

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

@@ -27,7 +27,9 @@ function namespaceMetadata(metadata, signal) {
             abort();
     });
 }
-async function scanUsedBytes(fs, limits, options, change, retained = change?.retained === true) {
+async function scanUsedBytes(fs, limits, options, changeInput, retained = typeof changeInput !== "function" && changeInput?.retained === true) {
+    let change = typeof changeInput === "function" ? undefined : changeInput;
+    let prepare = typeof changeInput === "function" ? changeInput : undefined;
     let total = 0;
     let retainedTotal = 0n;
     let shrinkCredited = false;
@@ -46,6 +48,24 @@ async function scanUsedBytes(fs, limits, options, change, retained = change?.ret
         const count = entries.length;
         admitDirectoryEntries(count, remaining, directory.path);
         remaining -= count;
+        if (prepare) {
+            change = await prepare();
+            prepare = undefined;
+        }
+        if (change?.stat.type === "directory") {
+            const stat = await fs.stat(directory.path, options);
+            const comparable = completeIdentity(stat) && completeIdentity(change.stat);
+            const comparison = comparable
+                ? stat.identityScope === change.stat.identityScope && stat.dev === change.stat.dev && stat.ino === change.stat.ino ? "same" : "distinct"
+                : fs.compareEntry ? await fs.compareEntry(change.path, fs, directory.path, options) : "unknown";
+            options?.signal?.throwIfAborted();
+            if (comparison !== "same" && comparison !== "distinct" && comparison !== "unknown")
+                throw new FsError("EIO", { syscall: "compareEntry", path: change.path });
+            if (comparison !== "distinct") {
+                total += Math.max(0, change.delta);
+                possibleAliases++;
+            }
+        }
         let processed = 0;
         for (const entry of entries) {
             options?.signal?.throwIfAborted();
@@ -69,7 +89,7 @@ async function scanUsedBytes(fs, limits, options, change, retained = change?.ret
                     if (!Number.isSafeInteger(stat.size) || stat.size < 0)
                         throw new FsError("EIO", { syscall: "lstat", path, message: "invalid quota entry size" });
                     retainedTotal += BigInt(stat.size);
-                    if (!change || stat.type !== "file")
+                    if (!change || change.stat.type !== "file" || stat.type !== "file")
                         continue;
                     const known = completeIdentity(stat);
                     const same = known && change.stat.identityScope === stat.identityScope && change.stat.dev === stat.dev && change.stat.ino === stat.ino;
@@ -89,7 +109,7 @@ async function scanUsedBytes(fs, limits, options, change, retained = change?.ret
                     continue;
                 }
                 total += stat.size;
-                if (!change || stat.type !== "file")
+                if (!change || change.stat.type !== "file" || stat.type !== "file")
                     continue;
                 const scope = change.stat.identityScope;
                 const comparable = [scope, stat.identityScope].every(value => typeof value === "symbol" || typeof value === "object" && value !== null)
@@ -169,6 +189,35 @@ export function withFileSystemQuota(fs, options) {
             return typeof original === "function" ? original.bind(fs) : original;
         },
     });
+    const creationChange = async (path, delta, fsOptions) => {
+        // Resolve existing ancestors before comparing directory identities. A dangling
+        // final symlink cannot safely identify its publication directory here.
+        let target;
+        try {
+            target = fs.canonicalizeMissingTarget?.(path, fsOptions) ?? path;
+        }
+        catch (error) {
+            if (error instanceof Error && "code" in error && error.code === "ENOENT")
+                throw new FileSystemQuotaError(options.maxBytes);
+            throw error;
+        }
+        try {
+            const entry = fs.canonicalizeMissingTarget ? undefined : await fs.lstat(target, fsOptions);
+            if (entry?.type === "symlink")
+                throw new FsError("ENOTSUP", { syscall: "write", path, message: "quota cannot locate missing symlink referent" });
+        }
+        catch (error) {
+            if (!(error instanceof Error && "code" in error && error.code === "ENOENT"))
+                throw error;
+        }
+        const boundary = target.lastIndexOf("/");
+        const parent = await fs.realpath(boundary <= 0 ? "/" : target.slice(0, boundary), fsOptions);
+        const stat = await fs.stat(parent, fsOptions);
+        fsOptions?.signal?.throwIfAborted();
+        if (stat.type !== "directory")
+            throw new FsError("ENOTDIR", { syscall: "write", path });
+        return { path: parent, stat, delta };
+    };
     const assertDelta = async (path, nextBytes, fsOptions) => {
         fsOptions?.signal?.throwIfAborted();
         let current;
@@ -181,7 +230,9 @@ export function withFileSystemQuota(fs, options) {
         }
         const projected = current?.type === "file" && nextBytes > current.size
             ? await usedBytes(fs, scanLimits, fsOptions, { path, stat: current, delta: nextBytes - current.size })
-            : await usedBytes(fs, scanLimits, fsOptions) - (current?.type === "directory" ? 0 : current?.size ?? 0) + nextBytes;
+            : !current && nextBytes > 0
+                ? await usedBytes(fs, scanLimits, fsOptions, () => creationChange(path, nextBytes, fsOptions))
+                : await usedBytes(fs, scanLimits, fsOptions) - (current?.type === "directory" ? 0 : current?.size ?? 0) + nextBytes;
         fsOptions?.signal?.throwIfAborted();
         if (projected > options.maxBytes)
             throw new FileSystemQuotaError(options.maxBytes);
@@ -205,8 +256,15 @@ export function withFileSystemQuota(fs, options) {
                     const conditional = descriptor.capabilities.publication === "conditional" && pinned !== undefined;
                     let publishedSize = pinned?.size ?? 0;
                     let reserved = 0;
+                    let publicationAliases = 1;
+                    if (conditional) {
+                        const baseline = await usedBytes(fs, scanLimits, admitted);
+                        publicationAliases = await usedBytes(fs, scanLimits, admitted, () => creationChange(path, 1, admitted)) - baseline;
+                        if (!Number.isSafeInteger(publicationAliases) || publicationAliases < 1)
+                            throw new FsError("ENOTSUP", { syscall: "open", path, message: "quota cannot determine publication aliases" });
+                    }
                     const reserve = (size) => {
-                        const next = Math.max(0, size - publishedSize);
+                        const next = Math.max(0, size - publishedSize) * publicationAliases;
                         reservedBytes += next - reserved;
                         reserved = next;
                     };
@@ -231,13 +289,13 @@ export function withFileSystemQuota(fs, options) {
                         if (!Number.isSafeInteger(nextBytes) || nextBytes < 0)
                             throw new FsError("EFBIG", { syscall: "write", path });
                         const projected = conditional
-                            ? await usedBytes(fs, scanLimits, operationOptions) - reserved + Math.max(0, nextBytes - publishedSize)
+                            ? await usedBytes(fs, scanLimits, operationOptions) - reserved + Math.max(0, nextBytes - publishedSize) * publicationAliases
                             : await usedBytes(fs, scanLimits, operationOptions, { path, stat, delta: nextBytes - stat.size, retained: true });
                         operationOptions.signal?.throwIfAborted();
                         if (projected > options.maxBytes)
                             throw new FileSystemQuotaError(options.maxBytes);
                         if (conditional)
-                            reserve(Math.max(nextBytes, publishedSize + reserved));
+                            reserve(Math.max(nextBytes, publishedSize + reserved / publicationAliases));
                     };
                     const forwarded = forwardFileDescriptor(descriptor, (syscall, operationOptions, action) => syscall === "close" && !conditional ? action() : mutate(async () => {
                         try {

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

@@ -429,7 +429,9 @@ export class S3FileSystem {
                 fail("EIO", "readFile", path, "response body length does not match ContentLength");
             return bytes;
         }).catch((error) => {
-            this.dispose(iterator ?? output.Body);
+            this.dispose(iterator);
+            if (output.Body !== iterator)
+                this.dispose(output.Body, iterator === undefined);
             throw error;
         });
     }

package/dist/safe-fs/fs/s3/manifest-admission.d.ts

@@ -0,0 +1,8 @@
+import { type ByteSource } from '../../contracts/io.js';
+/** Admit the fixed manifest grammar before JSON.parse can allocate its graph. */
+export declare function admitManifest(source: ByteSource, options: {
+    maxManifestBytes: number;
+    maxEntries: number;
+    maxBytes: number;
+    signal?: AbortSignal | undefined;
+}): ByteSource;

package/dist/safe-fs/fs/s3/manifest-admission.js

@@ -0,0 +1,171 @@
+import { FsError } from '../../contracts/errors.js';
+import { readBytes } from '../../contracts/io.js';
+/** Admit the fixed manifest grammar before JSON.parse can allocate its graph. */
+export async function* admitManifest(source, options) {
+    const decoder = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });
+    const frames = [];
+    let started = false;
+    let done = false;
+    let token = '';
+    let quoted = false;
+    let escaped = false;
+    let entries = 0;
+    let bytes = 0;
+    let wireBytes = 0;
+    let allocation = 0;
+    // Conservative accounting for graph storage, array growth, and validation
+    // tables. This is an admission estimate, not a process-RSS guarantee.
+    const allocationLimit = options.maxManifestBytes * 4;
+    const invalid = () => { throw new FsError('EIO', { message: 'Invalid S3 namespace structure' }); };
+    const reserve = (amount) => {
+        if (amount > allocationLimit - allocation)
+            throw new FsError('EFBIG', { message: 'S3 namespace graph exceeds allocation budget' });
+        allocation += amount;
+    };
+    const open = (shape) => {
+        reserve(256);
+        frames.push({ shape, state: shape === 'bytes' ? 'valueOrEnd' : 'keyOrEnd', key: '', keys: new Set() });
+    };
+    const scalar = () => {
+        const frame = frames.at(-1) ?? invalid();
+        let value;
+        try {
+            value = JSON.parse(token);
+        }
+        catch {
+            invalid();
+        }
+        token = '';
+        if (frame.state === 'key' || frame.state === 'keyOrEnd') {
+            if (typeof value !== 'string' || frame.keys.has(value))
+                invalid();
+            const key = value;
+            if (frame.shape === 'nodes') {
+                if (key.length > 4096)
+                    invalid();
+                if (++entries > options.maxEntries)
+                    throw new FsError('ENOSPC');
+            }
+            else {
+                const fields = frame.shape === 'namespace' ? ['version', 'identity', 'nextInode', 'nodes']
+                    : ['ino', 'revision', 'type', 'mode', 'time', 'bytes'];
+                if (!fields.includes(key))
+                    invalid();
+            }
+            reserve(64 + key.length * 2);
+            frame.keys.add(key);
+            frame.key = key;
+            frame.state = 'colon';
+            return;
+        }
+        if (frame.state !== 'value' && frame.state !== 'valueOrEnd')
+            invalid();
+        if (frame.shape === 'bytes') {
+            if (!Number.isInteger(value) || value < 0 || value > 255)
+                invalid();
+            if (++bytes > options.maxBytes)
+                throw new FsError('ENOSPC');
+            reserve(16);
+        }
+        else if (frame.shape === 'nodes' || frame.key === 'nodes' || frame.key === 'bytes')
+            invalid();
+        else if (frame.key === 'identity' || frame.key === 'type') {
+            if (typeof value !== 'string' || (frame.key === 'identity' ? value.length < 1 || value.length > 128 : !['file', 'directory'].includes(value)))
+                invalid();
+            reserve(value.length * 2);
+        }
+        else if (typeof value !== 'number' || !Number.isFinite(value))
+            invalid();
+        frame.state = 'commaOrEnd';
+    };
+    const feed = (text) => {
+        for (const character of text) {
+            if (token) {
+                if (quoted) {
+                    token += character;
+                    if (token.length > 4096 * 6 + 2)
+                        invalid();
+                    if (escaped)
+                        escaped = false;
+                    else if (character === '\\')
+                        escaped = true;
+                    else if (character === '"') {
+                        quoted = false;
+                        scalar();
+                    }
+                    continue;
+                }
+                if (![' ', '\n', '\r', '\t', ',', '}', ']'].includes(character)) {
+                    if (token.length >= 64)
+                        invalid();
+                    token += character;
+                    continue;
+                }
+                scalar();
+            }
+            if ([' ', '\n', '\r', '\t'].includes(character))
+                continue;
+            if (done)
+                invalid();
+            if (!started) {
+                if (character !== '{')
+                    invalid();
+                started = true;
+                open('namespace');
+                continue;
+            }
+            const frame = frames.at(-1) ?? invalid();
+            if (character === '}' || character === ']') {
+                if ((character === ']') !== (frame.shape === 'bytes')
+                    || !['commaOrEnd', 'keyOrEnd', 'valueOrEnd'].includes(frame.state))
+                    invalid();
+                if (frame.shape === 'namespace' && frame.keys.size !== 4 || frame.shape === 'node' && frame.keys.size !== 6)
+                    invalid();
+                frames.pop();
+                if (!frames.length)
+                    done = true;
+                continue;
+            }
+            if (frame.state === 'commaOrEnd') {
+                if (character !== ',')
+                    invalid();
+                frame.state = frame.shape === 'bytes' ? 'value' : 'key';
+                continue;
+            }
+            if (frame.state === 'colon') {
+                if (character !== ':')
+                    invalid();
+                frame.state = 'value';
+                continue;
+            }
+            if (frame.state === 'key' || frame.state === 'keyOrEnd') {
+                if (character !== '"')
+                    invalid();
+            }
+            else if (character === '{' || character === '[') {
+                const shape = frame.shape === 'namespace' && frame.key === 'nodes' ? 'nodes'
+                    : frame.shape === 'nodes' ? 'node' : frame.shape === 'node' && frame.key === 'bytes' ? 'bytes' : invalid();
+                if ((character === '[') !== (shape === 'bytes'))
+                    invalid();
+                frame.state = 'commaOrEnd';
+                open(shape);
+                continue;
+            }
+            else if (frame.shape === 'nodes' || frame.key === 'nodes' || frame.key === 'bytes')
+                invalid();
+            quoted = character === '"';
+            escaped = false;
+            token = character;
+        }
+    };
+    for await (const chunk of readBytes(source, options.signal)) {
+        if (chunk.byteLength > options.maxManifestBytes - wireBytes)
+            throw new FsError('EFBIG');
+        wireBytes += chunk.byteLength;
+        feed(decoder.decode(chunk, { stream: true }));
+        yield chunk;
+    }
+    feed(decoder.decode());
+    if (!done || token || frames.length)
+        invalid();
+}

package/dist/safe-fs/fs/s3/namespace.js

@@ -2,6 +2,7 @@ import { FsError } from '../../contracts/errors.js';
 import { collectBytes } from '../../contracts/io.js';
 import { dirname, normalizePath, validatePath } from '../../contracts/virtual-path.js';
 import { withObjectFileDescriptors } from '../object-publication/index.js';
+import { admitManifest } from './manifest-admission.js';
 function limit(value) {
     if (value === undefined)
         return Infinity;
@@ -17,7 +18,7 @@ export async function createS3NamespaceFileSystem(options) {
         throw new TypeError('An explicit S3 bucket and manifest key are required');
     const maxBytes = limit(options.maxBytes);
     const maxEntries = limit(options.maxEntries);
-    const maxManifestBytes = limit(options.maxManifestBytes);
+    const maxManifestBytes = limit(options.maxManifestBytes ?? 4 * 1024 * 1024);
     const maxAttempts = limit(options.maxAttempts);
     const descriptorOptions = options;
     for (const key of ['chunkBytes', 'maxStagedBytes', 'maxStagedPages', 'maxFileBytes', 'maxOpenFiles']) {
@@ -78,7 +79,7 @@ export async function createS3NamespaceFileSystem(options) {
         forwarded.signal?.throwIfAborted();
         try {
             const response = await client.getObjectStream(object, forwarded.signal ? { abortSignal: forwarded.signal } : {});
-            const body = await collectBytes(response.Body, { ...forwarded, ...(maxManifestBytes === Infinity ? {} : { maxBytes: maxManifestBytes }) });
+            const body = await collectBytes(admitManifest(response.Body, { maxManifestBytes, maxEntries, maxBytes, ...(forwarded.signal ? { signal: forwarded.signal } : {}) }), { ...forwarded, maxBytes: maxManifestBytes });
             if (typeof response.ETag !== 'string' || !response.ETag || response.ETag.startsWith('W/'))
                 throw new FsError('EIO', { message: 'S3 namespace requires a strong object validator' });
             let decoded;

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

@@ -6,6 +6,76 @@ import { admitDirectoryEntries, directoryEntryLimit } from "../directory-admissi
 import { assertCallbackAuthorityAllowed, compareEntries, registerEntryAuthority } from "../mount/comparison.js";
 import { compareWebDavResources, ownedResponseIdentifier, recordOwnedResourceStat, registerResourceQuery, resourceIdentifier } from "./resource-id.js";
 const timestampNamespace = "urn:virtual-bash:metadata";
+const maxTimestampPropertyBytes = 4096;
+/** Admit only five scalar members before native JSON parsing can allocate a graph. */
+function preflightTimestamps(property) {
+    // Check the untrimmed text first; counting UTF-8 bytes does not allocate an encoded copy.
+    let bytes = 0;
+    for (const point of property.text) {
+        const code = point.codePointAt(0);
+        bytes += code <= 0x7f ? 1 : code <= 0x7ff ? 2 : code <= 0xffff ? 3 : 4;
+        if (bytes > maxTimestampPropertyBytes)
+            throw new Error("timestamp property exceeds 4KiB limit");
+    }
+    const text = scalar(property);
+    let offset = 0;
+    const invalid = () => { throw new Error("invalid timestamp property structure"); };
+    const whitespace = () => {
+        while (" \t\r\n".includes(text[offset] ?? "\0"))
+            offset++;
+    };
+    const stringEnd = () => {
+        if (text[offset++] !== '"')
+            invalid();
+        while (offset < text.length) {
+            const char = text[offset++];
+            if (char === '"')
+                return;
+            if (char === "\\")
+                offset++;
+        }
+        invalid();
+    };
+    if (text[offset++] !== "{")
+        invalid();
+    const fields = new Set();
+    while (true) {
+        whitespace();
+        const start = offset;
+        stringEnd();
+        const field = JSON.parse(text.slice(start, offset));
+        if (typeof field !== "string" || !["version", "etag", "type", "atimeMs", "mtimeMs"].includes(field)
+            || fields.has(field) || fields.size >= 5)
+            return invalid();
+        fields.add(field);
+        whitespace();
+        if (text[offset++] !== ":")
+            invalid();
+        whitespace();
+        if (text[offset] === '"')
+            stringEnd();
+        else {
+            const start = offset;
+            while (offset < text.length && text[offset] !== "," && text[offset] !== "}") {
+                if ('{[:"\\]'.includes(text[offset]))
+                    invalid();
+                offset++;
+            }
+            if (offset === start)
+                invalid();
+        }
+        whitespace();
+        const delimiter = text[offset++];
+        if (delimiter === "}")
+            break;
+        if (delimiter !== ",")
+            invalid();
+    }
+    whitespace();
+    if (offset !== text.length || fields.size !== 5)
+        invalid();
+    return text;
+}
 const propfindBody = '<?xml version="1.0" encoding="utf-8"?>'
     + '<d:propfind xmlns:d="DAV:"><d:prop><d:resourcetype/><d:getcontentlength/>'
     + `<d:getlastmodified/><d:creationdate/><d:getetag/><v:timestamps xmlns:v="${timestampNamespace}"/></d:prop></d:propfind>`;
@@ -612,7 +682,7 @@ export class WebDavFileSystem {
         let mtimeMs = date("getlastmodified") ?? 0;
         let atimeMs = 0;
         if (timestampProperty) {
-            const timestamps = JSON.parse(scalar(timestampProperty));
+            const timestamps = JSON.parse(preflightTimestamps(timestampProperty));
             if (typeof timestamps !== "object" || timestamps === null
                 || !("version" in timestamps) || timestamps.version !== 1
                 || !("etag" in timestamps) || typeof timestamps.etag !== "string" || !/^"[\x21\x23-\x7e\x80-\xff]*"$/.test(timestamps.etag)

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

@@ -6,6 +6,10 @@ export interface NodeFsBridgeOptions {
     /** Optional confinement boundary; defaults to cwd. */
     readonly root?: string;
     readonly signal?: AbortSignal;
+    /** Trusted per-read backend byte cap, enforced before copying or decoding. */
+    readonly readFileMaxBytes?: number;
+    /** Reserve host resources; release after decoding and actual backend settlement, including cancellation. */
+    readonly reserveReadFile?: () => () => void;
 }
 export interface NodeFsBridgeFileSystem extends FileSystem {
     rmdir?(path: string, options?: FsOptions): Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poe-platform/safe-fs",
-  "version": "0.1.722",
+  "version": "0.1.724",
   "description": "Composable filesystem with a portable core and explicit Node adapters",
   "type": "module",
   "license": "MIT",