stitchkit 0.55.0 → 0.56.0

package/dist/{index-1k16zv57.js → index-bfcpjw20.js}

@@ -9,11 +9,16 @@ import {
 // src/files/boundary.ts
 import { randomUUID } from "node:crypto";
 import { constants } from "node:fs";
-import { link, open, realpath, rename, stat, unlink } from "node:fs/promises";
+import { link, mkdir, open, realpath, rename, stat, unlink } from "node:fs/promises";
 import { basename, dirname, resolve } from "node:path";
 var DEFAULT_MAX_BYTES = 100 * 1024 * 1024;
 var DEFAULT_INSPECTION_BYTES = 64 * 1024;
+var DEFAULT_INSPECTION_TIMEOUT_MS = 15000;
 var NOFOLLOW_FLAG = constants.O_NOFOLLOW ?? 0;
+var ManagedFileInspectionSchema = ManagedFileRefSchema.pick({
+  mediaType: true,
+  name: true
+});
 
 class ManagedFileError extends Error {
   code;
@@ -47,20 +52,118 @@ function ioError(message, error) {
     return error;
   return new ManagedFileError("FILE_IO_ERROR", message, { cause: error });
 }
+async function realpathOrNull(path, message) {
+  try {
+    return await realpath(path);
+  } catch (error) {
+    if (errorCode(error) === "ENOENT")
+      return null;
+    throw ioError(message, error);
+  }
+}
+async function bindRoot(config) {
+  const requested = resolve(config.root);
+  let canonical = await realpathOrNull(requested, "failed to resolve managed-file root");
+  if (canonical === null && config.createRoot) {
+    const parent = await realpathOrNull(dirname(requested), "failed to resolve managed-file root parent");
+    if (parent === null) {
+      throw new ManagedFileError("FILE_NOT_FOUND", "managed-file root parent must exist");
+    }
+    const parentInfo = await stat(parent).catch((error) => {
+      throw ioError("failed to inspect managed-file root parent", error);
+    });
+    if (!parentInfo.isDirectory()) {
+      throw new ManagedFileError("FILE_NOT_REGULAR", "managed-file root parent must be a directory");
+    }
+    try {
+      await mkdir(requested, { mode: 448 });
+    } catch (error) {
+      if (errorCode(error) !== "EEXIST") {
+        if (errorCode(error) === "ENOENT") {
+          throw new ManagedFileError("FILE_NOT_FOUND", "managed-file root parent must exist");
+        }
+        throw ioError("failed to create managed-file root", error);
+      }
+    }
+    canonical = await realpathOrNull(requested, "failed to resolve managed-file root");
+  }
+  if (canonical === null) {
+    throw new ManagedFileError("FILE_NOT_FOUND", "managed-file root must exist");
+  }
+  const info = await stat(canonical).catch((error) => {
+    throw ioError("failed to inspect managed-file root", error);
+  });
+  if (!info.isDirectory()) {
+    throw new ManagedFileError("FILE_NOT_REGULAR", "managed-file root must be a directory");
+  }
+  return canonical;
+}
 async function existingParent(root, target) {
-  const parent = await realpath(dirname(target)).catch(() => null);
+  const parent = await realpathOrNull(dirname(target), "failed to resolve managed-file parent directory");
   if (parent === null) {
     throw new ManagedFileError("FILE_NOT_FOUND", "managed-file parent directory not found");
   }
   if (!isWithinDir(root, parent)) {
     throw new ManagedFileError("FILE_OUTSIDE_ROOT", "managed-file path escapes its boundary");
   }
-  const info = await stat(parent).catch(() => null);
-  if (!info?.isDirectory()) {
-    throw new ManagedFileError("FILE_NOT_FOUND", "managed-file parent directory not found");
+  const info = await stat(parent).catch((error) => {
+    throw ioError("failed to inspect managed-file parent directory", error);
+  });
+  if (!info.isDirectory()) {
+    throw new ManagedFileError("FILE_NOT_REGULAR", "managed-file parent is not a directory");
   }
   return parent;
 }
+function abortReason(signal) {
+  return signal.reason ?? new DOMException("The operation was aborted", "AbortError");
+}
+function raceWithSignal(operation, signal) {
+  signal.throwIfAborted();
+  return new Promise((resolvePromise, rejectPromise) => {
+    let settled = false;
+    const settle = (complete) => {
+      if (settled)
+        return;
+      settled = true;
+      signal.removeEventListener("abort", onAbort);
+      complete();
+    };
+    const onAbort = () => settle(() => rejectPromise(abortReason(signal)));
+    signal.addEventListener("abort", onAbort, { once: true });
+    if (signal.aborted)
+      onAbort();
+    operation.then((value) => settle(() => resolvePromise(value)), (error) => settle(() => rejectPromise(error)));
+  });
+}
+async function inspectFile(inspector, input, timeoutMs, outerSignal) {
+  if (!inspector)
+    return {};
+  outerSignal?.throwIfAborted();
+  const timeoutSignal = AbortSignal.timeout(timeoutMs);
+  const signal = outerSignal ? AbortSignal.any([outerSignal, timeoutSignal]) : timeoutSignal;
+  try {
+    const inspected = await raceWithSignal(Promise.resolve().then(() => inspector({ ...input, signal })), signal);
+    return ManagedFileInspectionSchema.parse(inspected);
+  } catch (error) {
+    if (outerSignal?.aborted)
+      throw abortReason(outerSignal);
+    throw new ManagedFileError("FILE_INSPECTION_REJECTED", "managed file rejected by inspection", { cause: error });
+  }
+}
+function inspectedRef(path, size, inspection, fallback = {}) {
+  const mediaType = inspection.mediaType ?? fallback.mediaType;
+  const name = inspection.name ?? fallback.name;
+  const parsed = ManagedFileRefSchema.safeParse({
+    path,
+    size,
+    ...mediaType ? { mediaType } : {},
+    ...name ? { name } : {}
+  });
+  if (!parsed.success) {
+    throw new ManagedFileError("FILE_INSPECTION_REJECTED", "managed file rejected by inspection", { cause: parsed.error });
+  }
+  return parsed.data;
+}
 async function readHandle(handle, maxBytes, signal) {
   const chunks = [];
   let total = 0;
@@ -143,13 +246,11 @@ async function writeSource(handle, source, maxBytes, inspectionBytes, signal) {
   return { size, prefix };
 }
 async function createManagedFileBoundary(config) {
-  const root = await realpath(resolve(config.root)).catch(() => null);
-  if (root === null || !(await stat(root).catch(() => null))?.isDirectory()) {
-    throw new ManagedFileError("FILE_NOT_FOUND", "managed-file root must exist");
-  }
+  const root = await bindRoot(config);
   const maxReadBytes = positiveLimit(config.maxReadBytes, DEFAULT_MAX_BYTES, "maxReadBytes");
   const maxWriteBytes = positiveLimit(config.maxWriteBytes, DEFAULT_MAX_BYTES, "maxWriteBytes");
   const inspectionBytes = positiveLimit(config.inspectionBytes, DEFAULT_INSPECTION_BYTES, "inspectionBytes");
+  const inspectionTimeoutMs = positiveLimit(config.inspectionTimeoutMs, DEFAULT_INSPECTION_TIMEOUT_MS, "inspectionTimeoutMs");
   const targetFor = (path) => {
     const relative = filePath(path);
     const target = resolve(root, ...relative.split("/"));
@@ -161,7 +262,8 @@ async function createManagedFileBoundary(config) {
   return {
     async read(path, options = {}) {
       const resolved = targetFor(path);
-      const realTarget = await realpath(resolved.target).catch(() => null);
+      options.signal?.throwIfAborted();
+      const realTarget = await realpathOrNull(resolved.target, "failed to resolve managed file");
       if (realTarget === null) {
         throw new ManagedFileError("FILE_NOT_FOUND", "managed file not found");
       }
@@ -177,8 +279,12 @@ async function createManagedFileBoundary(config) {
           throw new ManagedFileError("FILE_NOT_REGULAR", "managed path is not a regular file");
         }
         const bytes = await readHandle(handle, maxBytes, options.signal);
+        const inspection = await inspectFile(config.inspect, {
+          prefix: bytes.slice(0, inspectionBytes),
+          name: basename(resolved.path)
+        }, inspectionTimeoutMs, options.signal);
         return {
-          ref: ManagedFileRefSchema.parse({ path: resolved.path, size: bytes.byteLength }),
+          ref: inspectedRef(resolved.path, bytes.byteLength, inspection),
           bytes
         };
       } catch (error) {
@@ -211,18 +317,11 @@ async function createManagedFileBoundary(config) {
           await handle.sync();
         await handle.close();
         handle = undefined;
-        let inspection = {};
-        if (config.inspect) {
-          try {
-            inspection = await config.inspect({
-              prefix: written.prefix,
-              declaredMediaType: options.mediaType,
-              name: options.name ?? basename(resolved.path)
-            });
-          } catch (error) {
-            throw new ManagedFileError("FILE_INSPECTION_REJECTED", "managed file rejected by inspection", { cause: error });
-          }
-        }
+        const inspection = await inspectFile(config.inspect, {
+          prefix: written.prefix,
+          ...options.mediaType ? { declaredMediaType: options.mediaType } : {},
+          name: options.name ?? basename(resolved.path)
+        }, inspectionTimeoutMs, options.signal);
         options.signal?.throwIfAborted();
         if (options.replace) {
           await rename(temporary, resolved.target);
@@ -238,15 +337,10 @@ async function createManagedFileBoundary(config) {
             throw error;
           }
         }
-        const mediaType = inspection.mediaType ?? options.mediaType;
-        const name = inspection.name ?? options.name;
-        const ref = ManagedFileRefSchema.parse({
-          path: resolved.path,
-          size,
-          ...mediaType ? { mediaType } : {},
-          ...name ? { name } : {}
+        return inspectedRef(resolved.path, size, inspection, {
+          mediaType: options.mediaType,
+          name: options.name
         });
-        return ref;
       } catch (error) {
         if (options.signal?.aborted && error === options.signal.reason)
           throw error;