stitchkit 0.54.0 → 0.56.0

package/dist/{index-bmnhqtya.js → index-7eq9va6e.js}

@@ -1,6 +1,3 @@
-import { createRequire } from "node:module";
-var __require = /* @__PURE__ */ createRequire(import.meta.url);
-
 // src/observability/trace.ts
 var TRACEPARENT_RE = /^([0-9a-f]{2})-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})(.*)$/i;
 function randomHex(bytes) {
@@ -149,4 +146,4 @@ function mapObject(source, mapper) {
   return result;
 }
 
-export { __require, parseTrailingWildcard, typedEntries, isRecord, callRuntimeHandler, transportResult, mapObject, createTraceContext, parseTraceparent, formatTraceparent, resolveTraceContext, childSpan, resolvePropagationContext };
+export { parseTrailingWildcard, typedEntries, isRecord, callRuntimeHandler, transportResult, mapObject, createTraceContext, parseTraceparent, formatTraceparent, resolveTraceContext, childSpan, resolvePropagationContext };

package/dist/index-bfcpjw20.js

@@ -0,0 +1,363 @@
+import {
+  isWithinDir
+} from "./index-sbdmyz75.js";
+import {
+  ManagedFilePathSchema,
+  ManagedFileRefSchema
+} from "./index-6k1937bx.js";
+
+// src/files/boundary.ts
+import { randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+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;
+  constructor(code, message, options) {
+    super(message, options);
+    this.code = code;
+    this.name = "ManagedFileError";
+  }
+}
+function positiveLimit(value, fallback, name) {
+  const resolved = value ?? fallback;
+  if (!Number.isSafeInteger(resolved) || resolved <= 0) {
+    throw new TypeError(`${name} must be a positive safe integer`);
+  }
+  return resolved;
+}
+function filePath(path) {
+  const parsed = ManagedFilePathSchema.safeParse(path);
+  if (!parsed.success) {
+    throw new ManagedFileError("FILE_INVALID_PATH", "invalid managed-file path");
+  }
+  return parsed.data;
+}
+function errorCode(error) {
+  if (typeof error !== "object" || error === null || !("code" in error))
+    return;
+  return typeof error.code === "string" ? error.code : undefined;
+}
+function ioError(message, error) {
+  if (error instanceof ManagedFileError)
+    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 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((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;
+  while (true) {
+    signal?.throwIfAborted();
+    const capacity = Math.min(64 * 1024, maxBytes + 1 - total);
+    if (capacity <= 0) {
+      throw new ManagedFileError("FILE_TOO_LARGE", `file exceeds the ${maxBytes}-byte cap`);
+    }
+    const chunk = new Uint8Array(capacity);
+    const { bytesRead } = await handle.read(chunk, 0, capacity);
+    if (bytesRead === 0)
+      break;
+    total += bytesRead;
+    if (total > maxBytes) {
+      throw new ManagedFileError("FILE_TOO_LARGE", `file exceeds the ${maxBytes}-byte cap`);
+    }
+    chunks.push(chunk.subarray(0, bytesRead));
+  }
+  const bytes = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return bytes;
+}
+async function writeChunk(handle, chunk) {
+  let offset = 0;
+  while (offset < chunk.byteLength) {
+    const { bytesWritten } = await handle.write(chunk, offset, chunk.byteLength - offset);
+    if (bytesWritten === 0)
+      throw new Error("zero-byte managed-file write");
+    offset += bytesWritten;
+  }
+}
+async function writeSource(handle, source, maxBytes, inspectionBytes, signal) {
+  let size = 0;
+  const prefixChunks = [];
+  let prefixSize = 0;
+  const consume = async (chunk) => {
+    signal?.throwIfAborted();
+    size += chunk.byteLength;
+    if (size > maxBytes) {
+      throw new ManagedFileError("FILE_TOO_LARGE", `file exceeds the ${maxBytes}-byte cap`);
+    }
+    if (prefixSize < inspectionBytes) {
+      const kept = chunk.subarray(0, inspectionBytes - prefixSize);
+      prefixChunks.push(kept);
+      prefixSize += kept.byteLength;
+    }
+    await writeChunk(handle, chunk);
+  };
+  if (source instanceof Uint8Array) {
+    await consume(source);
+  } else {
+    const reader = source.getReader();
+    try {
+      while (true) {
+        const result = await reader.read();
+        if (result.done)
+          break;
+        await consume(result.value);
+      }
+    } catch (error) {
+      await reader.cancel(error).catch(() => {
+        return;
+      });
+      throw error;
+    } finally {
+      reader.releaseLock();
+    }
+  }
+  const prefix = new Uint8Array(prefixSize);
+  let offset = 0;
+  for (const chunk of prefixChunks) {
+    prefix.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return { size, prefix };
+}
+async function createManagedFileBoundary(config) {
+  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("/"));
+    if (!isWithinDir(root, target)) {
+      throw new ManagedFileError("FILE_OUTSIDE_ROOT", "managed-file path escapes its boundary");
+    }
+    return { path: relative, target };
+  };
+  return {
+    async read(path, options = {}) {
+      const resolved = targetFor(path);
+      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");
+      }
+      if (!isWithinDir(root, realTarget)) {
+        throw new ManagedFileError("FILE_OUTSIDE_ROOT", "managed-file path escapes its boundary");
+      }
+      const maxBytes = positiveLimit(options.maxBytes, maxReadBytes, "maxBytes");
+      let handle;
+      try {
+        handle = await open(realTarget, constants.O_RDONLY | NOFOLLOW_FLAG);
+        const info = await handle.stat();
+        if (!info.isFile()) {
+          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: inspectedRef(resolved.path, bytes.byteLength, inspection),
+          bytes
+        };
+      } catch (error) {
+        if (options.signal?.aborted && error === options.signal.reason)
+          throw error;
+        if (errorCode(error) === "ENOENT") {
+          throw new ManagedFileError("FILE_NOT_FOUND", "managed file not found");
+        }
+        throw ioError("failed to read managed file", error);
+      } finally {
+        await handle?.close().catch(() => {
+          return;
+        });
+      }
+    },
+    async write(path, source, options = {}) {
+      options.signal?.throwIfAborted();
+      const resolved = targetFor(path);
+      const parent = await existingParent(root, resolved.target);
+      const maxBytes = positiveLimit(options.maxBytes, maxWriteBytes, "maxBytes");
+      const temporary = resolve(parent, `.stitchkit-${randomUUID()}.tmp`);
+      let handle;
+      let committed = false;
+      let size = 0;
+      try {
+        handle = await open(temporary, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | NOFOLLOW_FLAG, 384);
+        const written = await writeSource(handle, source, maxBytes, inspectionBytes, options.signal);
+        size = written.size;
+        if (options.durable)
+          await handle.sync();
+        await handle.close();
+        handle = undefined;
+        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);
+          committed = true;
+        } else {
+          try {
+            await link(temporary, resolved.target);
+            committed = true;
+          } catch (error) {
+            if (errorCode(error) === "EEXIST") {
+              throw new ManagedFileError("FILE_EXISTS", "managed file already exists");
+            }
+            throw error;
+          }
+        }
+        return inspectedRef(resolved.path, size, inspection, {
+          mediaType: options.mediaType,
+          name: options.name
+        });
+      } catch (error) {
+        if (options.signal?.aborted && error === options.signal.reason)
+          throw error;
+        throw ioError("failed to write managed file", error);
+      } finally {
+        await handle?.close().catch(() => {
+          return;
+        });
+        if (!options.replace || !committed) {
+          await unlink(temporary).catch((error) => {
+            if (errorCode(error) !== "ENOENT")
+              config.onCleanupError?.(error);
+          });
+        }
+      }
+    }
+  };
+}
+
+export { ManagedFileError, createManagedFileBoundary };

package/dist/{index-yxpe3phd.js → index-cby4ar3v.js}

@@ -1,20 +1,3 @@
-// src/internal/within-dir.ts
-import { realpath } from "node:fs/promises";
-import { sep } from "node:path";
-function isWithinDir(root, target) {
-  const base = root.endsWith(sep) ? root.slice(0, -sep.length) : root;
-  return target === root || target === base || target.startsWith(base + sep);
-}
-async function realPathWithinDir(root, target) {
-  const [realRoot, realTarget] = await Promise.all([
-    realpath(root).catch(() => null),
-    realpath(target).catch(() => null)
-  ]);
-  if (realRoot === null || realTarget === null)
-    return null;
-  return isWithinDir(realRoot, realTarget) ? realTarget : null;
-}
-
 // src/tools/json-schema.ts
 import { z } from "zod";
 function toJsonSchema(schema, io, unrepresentable = "throw", target = "draft-2020-12") {
@@ -60,4 +43,4 @@ function jsonSchemaFields(jsonSchema) {
   return fields;
 }
 
-export { isWithinDir, realPathWithinDir, toJsonSchema, jsonSchemaFields };
+export { toJsonSchema, jsonSchemaFields };