stitchkit 0.54.0 → 0.55.0

package/dist/index-1k16zv57.js

@@ -0,0 +1,269 @@
+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, 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 NOFOLLOW_FLAG = constants.O_NOFOLLOW ?? 0;
+
+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 existingParent(root, target) {
+  const parent = await realpath(dirname(target)).catch(() => null);
+  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");
+  }
+  return parent;
+}
+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 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 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 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);
+      const realTarget = await realpath(resolved.target).catch(() => null);
+      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);
+        return {
+          ref: ManagedFileRefSchema.parse({ path: resolved.path, size: bytes.byteLength }),
+          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;
+        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 });
+          }
+        }
+        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;
+          }
+        }
+        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 ref;
+      } 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-6k1937bx.js

@@ -0,0 +1,20 @@
+// src/contract/file-ref.ts
+import { z } from "zod";
+function isManagedFilePath(value) {
+  if (value.length === 0 || value.includes("\x00") || value.includes("\\"))
+    return false;
+  if (value.startsWith("/") || value.startsWith("//") || /^[A-Za-z]:/.test(value)) {
+    return false;
+  }
+  const parts = value.split("/");
+  return parts.every((part) => part.length > 0 && part !== "." && part !== "..");
+}
+var ManagedFilePathSchema = z.string().refine(isManagedFilePath, "expected a canonical relative managed-file path");
+var ManagedFileRefSchema = z.object({
+  path: ManagedFilePathSchema,
+  size: z.number().int().nonnegative(),
+  mediaType: z.string().min(1).optional(),
+  name: z.string().min(1).optional()
+});
+
+export { ManagedFilePathSchema, ManagedFileRefSchema };

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-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 };

package/dist/index-h60df7rj.js

@@ -0,0 +1,110 @@
+// src/contract/errors.ts
+var APP_ERROR_BRAND = Symbol.for("stitchkit.AppError");
+
+class AppError extends Error {
+  code;
+  status;
+  details;
+  hint;
+  traceId;
+  constructor(code, message, status = 500, details, hint, traceId) {
+    super(message ?? code);
+    this.code = code;
+    this.status = status;
+    this.details = details;
+    this.hint = hint;
+    this.traceId = traceId;
+    this.name = "AppError";
+    Object.defineProperty(this, APP_ERROR_BRAND, { value: true });
+  }
+  static is(err) {
+    return typeof err === "object" && err !== null && APP_ERROR_BRAND in err;
+  }
+  toJSON() {
+    return {
+      error: {
+        code: this.code,
+        message: this.message,
+        ...this.details && { details: this.details },
+        ...this.hint && { hint: this.hint }
+      }
+    };
+  }
+}
+function notFound(message = "Not found") {
+  throw new AppError("NOT_FOUND", message, 404);
+}
+function badRequest(message, details) {
+  throw new AppError("BAD_REQUEST", message, 400, details);
+}
+function unauthorized(message = "Unauthorized") {
+  throw new AppError("UNAUTHORIZED", message, 401);
+}
+function forbidden(message = "Forbidden") {
+  throw new AppError("FORBIDDEN", message, 403);
+}
+function conflict(message = "Conflict", details) {
+  throw new AppError("CONFLICT", message, 409, details);
+}
+function rateLimited(message = "Too many requests") {
+  throw new AppError("RATE_LIMITED", message, 429);
+}
+var STITCH_ERROR_STATUS = {
+  BAD_REQUEST: 400,
+  UNAUTHORIZED: 401,
+  FORBIDDEN: 403,
+  NOT_FOUND: 404,
+  METHOD_NOT_ALLOWED: 405,
+  CONFLICT: 409,
+  RATE_LIMITED: 429,
+  VALIDATION_ERROR: 400,
+  REALTIME_CONTRACT_VIOLATION: 500,
+  INTERNAL_SERVER_ERROR: 500
+};
+function isStitchErrorCode(code) {
+  return Object.hasOwn(STITCH_ERROR_STATUS, code);
+}
+function appError(code, message, details) {
+  throw new AppError(code, message, isStitchErrorCode(code) ? STITCH_ERROR_STATUS[code] : 500, details);
+}
+
+// src/contract/define.ts
+import { z } from "zod";
+
+// src/internal/safe-json.ts
+function isUnsafeKey(key) {
+  return key === "__proto__";
+}
+function safeJsonParse(text) {
+  return JSON.parse(text, (key, value) => isUnsafeKey(key) ? undefined : value);
+}
+
+// src/contract/define.ts
+function mergeMeta(contractMeta, endpointMeta) {
+  if (!contractMeta)
+    return endpointMeta;
+  if (!endpointMeta)
+    return { ...contractMeta };
+  return { ...contractMeta, ...endpointMeta };
+}
+// src/contract/errors-factory.ts
+import { z as z2 } from "zod";
+// src/contract/pagination.ts
+import { z as z3 } from "zod";
+
+// src/internal/base64url.ts
+function bytesToBase64Url(bytes) {
+  let binary = "";
+  for (const byte of bytes)
+    binary += String.fromCharCode(byte);
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function base64UrlToBytes(segment) {
+  if (!/^[A-Za-z0-9_-]*$/.test(segment) || segment.length % 4 === 1) {
+    throw new Error("invalid base64url segment");
+  }
+  const b64 = segment.replace(/-/g, "+").replace(/_/g, "/");
+  const padded = b64.padEnd(Math.ceil(b64.length / 4) * 4, "=");
+  return Uint8Array.from(atob(padded), (c) => c.charCodeAt(0));
+}
+export { isUnsafeKey, safeJsonParse, mergeMeta, AppError, notFound, badRequest, unauthorized, forbidden, conflict, rateLimited, STITCH_ERROR_STATUS, isStitchErrorCode, appError, bytesToBase64Url, base64UrlToBytes };

package/dist/{index-yez419px.js → index-js7yexng.js}

@@ -1,3 +1,6 @@
+import {
+  mergeContextContribution
+} from "./index-pzc32v75.js";
 import {
   base64UrlToBytes,
   bytesToBase64Url,
@@ -5,10 +8,10 @@ import {
   isUnsafeKey,
   safeJsonParse,
   unauthorized
-} from "./index-173tvqcp.js";
+} from "./index-h60df7rj.js";
 import {
   isRecord
-} from "./index-bmnhqtya.js";
+} from "./index-7eq9va6e.js";
 
 // src/server/middleware/cookies.ts
 function parseCookies(header) {
@@ -151,7 +154,11 @@ function extractToken(req, cookieName) {
   return null;
 }
 function isThenable(value) {
-  return "then" in value && typeof value.then === "function";
+  try {
+    return "then" in value && typeof value.then === "function";
+  } catch {
+    return false;
+  }
 }
 function createAuthHook(config) {
   const onAnonymous = config.onAnonymous ?? (() => unauthorized());
@@ -169,10 +176,10 @@ function createAuthHook(config) {
     const rule = typeof entry === "object" ? entry.rule : entry;
     if (typeof entry === "object" && entry.inject && identity !== null) {
       const fields = entry.inject(identity, ctx);
-      if (isThenable(fields)) {
+      if (typeof fields === "object" && fields !== null && isThenable(fields)) {
         throw new Error(`[stitchkit] auth: the inject of scope "${scope}" must be synchronous — an async inject merges a Promise, not fields`);
       }
-      Object.assign(ctx, fields);
+      mergeContextContribution(ctx, fields, scope);
     }
     if (rule === "public")
       return;
@@ -182,8 +189,14 @@ function createAuthHook(config) {
     }
     if (rule === "authenticated")
       return;
-    if (!await rule(identity, ctx))
+    const result = await rule(identity, ctx);
+    if (result === false) {
       onForbidden();
+      return;
+    }
+    if (result === true)
+      return;
+    mergeContextContribution(ctx, result, scope);
   }
   return auth;
 }

package/dist/index-k4dftwf7.js

@@ -0,0 +1,66 @@
+// src/tools/names.ts
+var SINGULAR_EXCEPTIONS = new Set([
+  "analytics",
+  "status",
+  "stats",
+  "settings",
+  "media",
+  "progress",
+  "news"
+]);
+var TOOL_NAME_RE = /^[a-zA-Z0-9_-]{1,64}$/;
+function normalizeService(value) {
+  return value.replace(/[^a-zA-Z0-9_]/g, "_");
+}
+function normalizeMethod(value) {
+  return value.replace(/[^a-zA-Z0-9_-]/g, "_");
+}
+function singularize(name) {
+  if (SINGULAR_EXCEPTIONS.has(name))
+    return name;
+  if (name.endsWith("ies"))
+    return `${name.slice(0, -3)}y`;
+  if (name.endsWith("s") && !name.endsWith("ss"))
+    return name.slice(0, -1);
+  return name;
+}
+function singularizeTail(name) {
+  const cut = name.lastIndexOf("_");
+  if (cut === -1)
+    return singularize(name);
+  return `${name.slice(0, cut + 1)}${singularize(name.slice(cut + 1))}`;
+}
+function hasUsableChars(value) {
+  return /[a-zA-Z0-9]/.test(value);
+}
+function assertToolName(name, serviceName, key) {
+  const where = `service "${serviceName}", method "${key}"`;
+  if (!TOOL_NAME_RE.test(name)) {
+    const why = name.length > 64 ? `is ${name.length} characters (max 64) — set an explicit \`toolName\`` : "must match [a-zA-Z0-9_-]";
+    throw new Error(`Tool name "${name}" (${where}) ${why}`);
+  }
+}
+function toToolName(serviceName, methodName) {
+  const normalized = normalizeService(serviceName);
+  const singular = singularizeTail(normalized);
+  const method = normalizeMethod(methodName);
+  if (method === "list")
+    return `list_${normalized}`;
+  if (method === "get")
+    return `get_${singular}`;
+  if (method === "create")
+    return `create_${singular}`;
+  if (method === "update")
+    return `update_${singular}`;
+  if (method === "delete")
+    return `delete_${singular}`;
+  const snake = method.replace(/([A-Z])/g, "_$1").toLowerCase();
+  return `${snake}_${singular}`.replace(/^_/, "");
+}
+function assertUniqueToolName(name, taken, surface) {
+  if (taken) {
+    throw new Error(`Duplicate ${surface} "${name}" across mounted operations`);
+  }
+}
+
+export { hasUsableChars, assertToolName, toToolName, assertUniqueToolName };

package/dist/{index-z7761jk2.js → index-npye5kt7.js}

@@ -1,39 +1,44 @@
 import {
   DEFAULT_PROCESS_SIGNALS,
+  RUNTIME_CONTEXT_RESERVED_KEYS,
   assertCorsConfig,
   corsHeaders,
   corsPreflightResponse,
   defaultSignalSource,
   guardSignalCallback,
   reportSignalError
-} from "./index-b15rtha1.js";
+} from "./index-pzc32v75.js";
 import {
-  AppError,
-  badRequest,
   errorCode,
   extractIp,
   getClientInfo,
   getRequestContext,
-  isUnsafeKey,
   normalizeError,
   parseQueryParams,
   recordedErrorMessage,
   resolveSocketIp,
   resolveTraceId,
   runWithRequestContext,
-  safeJsonParse,
   setRequestEndpoint,
   setRequestError,
   validateDeclaredOutput,
   zodIssues
-} from "./index-173tvqcp.js";
+} from "./index-v4bbq3p4.js";
+import {
+  AppError,
+  badRequest,
+  isUnsafeKey,
+  safeJsonParse
+} from "./index-h60df7rj.js";
 import {
-  __require,
   isRecord,
   parseTrailingWildcard,
   resolveTraceContext,
   transportResult
-} from "./index-bmnhqtya.js";
+} from "./index-7eq9va6e.js";
+import {
+  __require
+} from "./index-1bx83sw4.js";
 
 // src/server/multipart.ts
 var DEFAULT_MAX_REQUEST_BYTES = 25 * 1024 * 1024;
@@ -500,19 +505,6 @@ async function readRequestText(req, maxBytes) {
 }
 
 // src/server/context.ts
-var RESERVED_KEYS = new Set([
-  "params",
-  "input",
-  "source",
-  "req",
-  "url",
-  "headers",
-  "rawBody",
-  "traceId",
-  "spanId",
-  "ipAddress",
-  "userAgent"
-]);
 function parseJsonBody(req, text) {
   if (text.trim() === "")
     return {};
@@ -528,7 +520,7 @@ function parseJsonBody(req, text) {
 function buildBaseContext(req, url, pathParams, traceId, clientIp) {
   const safePathParams = {};
   for (const [k, v] of Object.entries(pathParams)) {
-    if (!RESERVED_KEYS.has(k) && !isUnsafeKey(k))
+    if (!RUNTIME_CONTEXT_RESERVED_KEYS.has(k) && !isUnsafeKey(k))
       safePathParams[k] = v;
   }
   return {
@@ -538,6 +530,7 @@ function buildBaseContext(req, url, pathParams, traceId, clientIp) {
     req,
     url,
     headers: req.headers,
+    signal: req.signal,
     ...safePathParams,
     traceId,
     ...getClientInfo(req, clientIp)
@@ -585,6 +578,7 @@ function buildErrorContext(req, url, traceId, clientIp) {
     req,
     url,
     headers: req.headers,
+    signal: req.signal,
     traceId,
     ...getClientInfo(req, clientIp)
   };