stitchkit 0.25.0 → 0.27.0

package/dist/{index-tje0q6gp.js → index-zfscdskj.js}

@@ -1,5 +1,6 @@
 // src/server/middleware/cors.ts
 var DEFAULT_CORS_ALLOW_HEADERS = "Content-Type, Authorization, X-Trace-Id, traceparent, tracestate";
+var DEFAULT_CORS_EXPOSE_HEADERS = "Content-Disposition, Content-Length, Content-Range, Accept-Ranges, ETag, Last-Modified, X-Trace-Id";
 function assertCorsConfig(config) {
   if (config.credentials && (config.origin === undefined || config.origin === "*")) {
     throw new Error("[stitchkit] cors: `credentials: true` cannot be combined with a wildcard origin. " + "Set `origin` to an explicit string or list.");
@@ -23,6 +24,10 @@ function corsHeaders(config, requestOrigin) {
     "Access-Control-Allow-Methods": config.methods ?? "GET, POST, PUT, PATCH, DELETE, OPTIONS",
     "Access-Control-Allow-Headers": config.headers ?? DEFAULT_CORS_ALLOW_HEADERS
   };
+  const expose = Array.isArray(config.exposeHeaders) ? config.exposeHeaders.join(", ") : config.exposeHeaders ?? DEFAULT_CORS_EXPOSE_HEADERS;
+  if (expose !== "") {
+    headers["Access-Control-Expose-Headers"] = expose;
+  }
   if (allowOrigin !== undefined) {
     headers["Access-Control-Allow-Origin"] = allowOrigin;
     if (config.credentials) {
@@ -41,4 +46,4 @@ function corsPreflightResponse(config, req) {
   });
 }
 
-export { DEFAULT_CORS_ALLOW_HEADERS, assertCorsConfig, corsHeaders, corsPreflightResponse };
+export { DEFAULT_CORS_ALLOW_HEADERS, DEFAULT_CORS_EXPOSE_HEADERS, assertCorsConfig, corsHeaders, corsPreflightResponse };

package/dist/{index-4gawbm74.js → index-zza375qp.js}

@@ -1,3 +1,7 @@
+import {
+  isRecord
+} from "./index-c7nyw0yt.js";
+
 // src/contract/errors.ts
 var APP_ERROR_BRAND = Symbol.for("stitchkit.AppError");
 
@@ -64,6 +68,15 @@ function isStitchErrorCode(code) {
 function appError(code, message, details) {
   throw new AppError(code, message, isStitchErrorCode(code) ? STITCH_ERROR_STATUS[code] : 500, details);
 }
+
+// src/contract/define.ts
+function mergeMeta(contractMeta, endpointMeta) {
+  if (!contractMeta)
+    return endpointMeta;
+  if (!endpointMeta)
+    return { ...contractMeta };
+  return { ...contractMeta, ...endpointMeta };
+}
 // src/contract/pagination.ts
 import { z } from "zod";
 
@@ -121,10 +134,35 @@ function normalizeError(err) {
   console.error("[stitchkit] unhandled error:", err);
   return new AppError("INTERNAL_SERVER_ERROR", "Internal server error", 500);
 }
-function validateHandlerOutput(schema, data) {
+function strippedPaths(before, after, prefix) {
+  if (Array.isArray(before)) {
+    if (!Array.isArray(after))
+      return [];
+    return before.flatMap((item, i) => strippedPaths(item, after[i], `${prefix}[${i}]`));
+  }
+  if (!isRecord(before) || !isRecord(after))
+    return [];
+  const paths = [];
+  for (const [key, value] of Object.entries(before)) {
+    const path = prefix ? `${prefix}.${key}` : key;
+    if (!(key in after)) {
+      paths.push(path);
+      continue;
+    }
+    paths.push(...strippedPaths(value, after[key], path));
+  }
+  return paths;
+}
+function validateHandlerOutput(schema, data, onStripped) {
   const parsed = schema.safeParse(data);
-  if (parsed.success)
+  if (parsed.success) {
+    if (onStripped) {
+      const paths = strippedPaths(data, parsed.data, "");
+      if (paths.length > 0)
+        onStripped(paths);
+    }
     return { ok: true, data: parsed.data };
+  }
   return {
     ok: false,
     message: `Handler output does not match the contract: ${formatZodError(parsed.error)}`
@@ -138,4 +176,4 @@ function isWithinDir(root, target) {
   return target === root || target === base || target.startsWith(base + sep);
 }
 
-export { AppError, notFound, badRequest, unauthorized, forbidden, conflict, rateLimited, STITCH_ERROR_STATUS, isStitchErrorCode, appError, bytesToBase64Url, base64UrlToBytes, formatZodError, zodIssues, errorCode, normalizeError, validateHandlerOutput, isWithinDir };
+export { mergeMeta, AppError, notFound, badRequest, unauthorized, forbidden, conflict, rateLimited, STITCH_ERROR_STATUS, isStitchErrorCode, appError, bytesToBase64Url, base64UrlToBytes, formatZodError, zodIssues, errorCode, normalizeError, validateHandlerOutput, isWithinDir };

package/dist/index.js

@@ -16,7 +16,7 @@ import {
   paginatedSchema,
   rateLimited,
   unauthorized
-} from "./index-x62gnfsk.js";
+} from "./index-pmftwk2a.js";
 import {
   isRecord,
   mapObject,
@@ -28,6 +28,25 @@ function inputIsQuery(method) {
   return method === "GET" || method === "DELETE";
 }
 
+// src/browser/client-multipart.ts
+function isFileDescriptor(value) {
+  return typeof value === "object" && value !== null && !(value instanceof Blob) && "uri" in value && typeof value.uri === "string" && "name" in value && typeof value.name === "string" && "type" in value && typeof value.type === "string";
+}
+function isMultipartFile(value) {
+  return value instanceof Blob || isFileDescriptor(value);
+}
+function appendMultipartFile(form, field, file) {
+  const sink = form;
+  sink.append(field, file);
+}
+function appendFormFields(formData, values, skipKeys) {
+  for (const [key, value] of Object.entries(values)) {
+    if (skipKeys.has(key) || value === undefined || value === null)
+      continue;
+    formData.append(key, typeof value === "string" ? value : JSON.stringify(value));
+  }
+}
+
 // src/browser/http.ts
 import ky, { isHTTPError } from "ky";
 
@@ -188,6 +207,9 @@ function createHttpClient(config) {
       if (options.responseType === "blob") {
         return client[method](url, kyOptions).blob();
       }
+      if (options.responseType === "response") {
+        return await client[method](url, kyOptions);
+      }
       const response = await client[method](url, kyOptions);
       if (response.status === 204 || response.headers.get("content-length") === "0") {
         return;
@@ -229,10 +251,15 @@ function createHttpClient(config) {
 }
 
 // src/browser/client.ts
-function withTimeout(options, timeout) {
-  if (timeout === undefined)
+function withTimeout(options, endpoint) {
+  const responseType = endpoint.rawResponse ? "response" : undefined;
+  if (endpoint.timeout === undefined && responseType === undefined)
     return options;
-  return { ...options, timeout };
+  return {
+    ...options,
+    ...endpoint.timeout !== undefined && { timeout: endpoint.timeout },
+    ...responseType && { responseType }
+  };
 }
 function withOutput(endpoint, result) {
   const schema = endpoint.output;
@@ -312,15 +339,15 @@ function createHttpMethod(endpoint, prefix, client, config) {
       const formData = new FormData;
       appendMultipartFile(formData, endpoint.multipart, file);
       appendFormFields(formData, firstArg, new Set([...prefixKeys, endpoint.multipart]));
-      return withOutput(endpoint, client[httpMethod](url, formData, withTimeout(undefined, endpoint.timeout)));
+      return withOutput(endpoint, client[httpMethod](url, formData, withTimeout(undefined, endpoint)));
     }
     if (isGet) {
       const params = collectQueryParams(firstArg, prefixKeys, endpoint);
-      return withOutput(endpoint, client.get(url, withTimeout(params ? { params } : undefined, endpoint.timeout)));
+      return withOutput(endpoint, client.get(url, withTimeout(params ? { params } : undefined, endpoint)));
     }
     if (httpMethod === "delete") {
       const params = collectQueryParams(firstArg, prefixKeys, endpoint);
-      return withOutput(endpoint, client.delete(url, withTimeout(params ? { params } : undefined, endpoint.timeout)));
+      return withOutput(endpoint, client.delete(url, withTimeout(params ? { params } : undefined, endpoint)));
     }
     const payload = {};
     for (const [key, value] of Object.entries(firstArg)) {
@@ -328,7 +355,7 @@ function createHttpMethod(endpoint, prefix, client, config) {
         payload[key] = value;
       }
     }
-    return withOutput(endpoint, client[httpMethod](url, Object.keys(payload).length > 0 ? payload : undefined, withTimeout(undefined, endpoint.timeout)));
+    return withOutput(endpoint, client[httpMethod](url, Object.keys(payload).length > 0 ? payload : undefined, withTimeout(undefined, endpoint)));
   };
 }
 function createFetchMethod(endpoint, prefix, config, contractConfig) {
@@ -384,6 +411,8 @@ function createFetchMethod(endpoint, prefix, config, contractConfig) {
       if (!res2.ok) {
         await throwForErrorResponse(res2, config, null);
       }
+      if (endpoint.rawResponse)
+        return res2;
       if (res2.status === 204)
         return;
       const json2 = await res2.json();
@@ -401,29 +430,14 @@ function createFetchMethod(endpoint, prefix, config, contractConfig) {
     if (!res.ok) {
       await throwForErrorResponse(res, config, { error: res.statusText });
     }
+    if (endpoint.rawResponse)
+      return res;
     if (res.status === 204)
       return;
     const json = await res.json();
     return endpoint.output ? endpoint.output.parse(json) : json;
   };
 }
-function isFileDescriptor(value) {
-  return typeof value === "object" && value !== null && !(value instanceof Blob) && "uri" in value && typeof value.uri === "string" && "name" in value && typeof value.name === "string" && "type" in value && typeof value.type === "string";
-}
-function isMultipartFile(value) {
-  return value instanceof Blob || isFileDescriptor(value);
-}
-function appendMultipartFile(form, field, file) {
-  const sink = form;
-  sink.append(field, file);
-}
-function appendFormFields(formData, values, skipKeys) {
-  for (const [key, value] of Object.entries(values)) {
-    if (skipKeys.has(key) || value === undefined || value === null)
-      continue;
-    formData.append(key, typeof value === "string" ? value : JSON.stringify(value));
-  }
-}
 async function throwForErrorResponse(res, config, fallbackBody) {
   const body = await res.json().catch(() => fallbackBody);
   config.onError?.(res.status, body);

package/dist/internal/errors.d.ts

@@ -29,8 +29,13 @@ export declare function normalizeError(err: unknown): AppError;
  * Validate a handler's return value against the contract `output` schema. A
  * mismatch is a **server** fault (the handler broke its own contract) — shared
  * by the HTTP and tool transports so both report it identically.
+ *
+ * `onStripped` is the migration diagnostic: a handler returning more than its
+ * contract declares has the extra fields **deleted**, correctly but invisibly —
+ * types cannot catch it (structural typing does not reject excess properties) and
+ * nothing logs it. Pass a reporter to find out; omit it and nothing is computed.
  */
-export declare function validateHandlerOutput(schema: ZodType, data: unknown): {
+export declare function validateHandlerOutput(schema: ZodType, data: unknown, onStripped?: (paths: string[]) => void): {
     ok: true;
     data: unknown;
 } | {

package/dist/internal/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/internal/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACtC,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAOvC,wBAAgB,cAAc,CAAC,KAAK,EAAE,CAAC,CAAC,QAAQ,GAAG,MAAM,CAMxD;AAED,qFAAqF;AACrF,MAAM,WAAW,eAAe;IAC9B,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAC;IACb,yDAAyD;IACzD,IAAI,EAAE,MAAM,CAAC;IACb,6CAA6C;IAC7C,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,CAAC,CAAC,QAAQ,GAAG,eAAe,EAAE,CAM9D;AAKD;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAI1D;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,QAAQ,CAgBrD;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,OAAO,EACf,IAAI,EAAE,OAAO,GACZ;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAO9D"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/internal/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACtC,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAQvC,wBAAgB,cAAc,CAAC,KAAK,EAAE,CAAC,CAAC,QAAQ,GAAG,MAAM,CAMxD;AAED,qFAAqF;AACrF,MAAM,WAAW,eAAe;IAC9B,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAC;IACb,yDAAyD;IACzD,IAAI,EAAE,MAAM,CAAC;IACb,6CAA6C;IAC7C,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,CAAC,CAAC,QAAQ,GAAG,eAAe,EAAE,CAM9D;AAKD;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAI1D;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,QAAQ,CAgBrD;AA4BD;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,OAAO,EACf,IAAI,EAAE,OAAO,EACb,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,IAAI,GACrC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAe9D"}

package/dist/internal/write-download.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Write a downloaded body to disk, with the containment check both download
+ * paths need.
+ *
+ * Shared by the CLI's `--output-dir` and the `mountDownload` native tool. It
+ * deliberately takes an **already-resolved** target rather than building one:
+ * the two callers derive the filename differently (an untrusted `file.name` vs a
+ * name derived from the URL) and, more importantly, report the path back to the
+ * user — so composing it here would silently change one of those outputs from
+ * relative to absolute.
+ *
+ * The containment re-check is cheap and belongs on this side: both callers reduce
+ * the name to a basename first, but that is an invariant of *their* code, and
+ * this is where the write actually happens.
+ */
+export declare function writeDownload(root: string, target: string, data: Uint8Array): Promise<void>;
+//# sourceMappingURL=write-download.d.ts.map

package/dist/internal/write-download.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write-download.d.ts","sourceRoot":"","sources":["../../src/internal/write-download.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,aAAa,CACjC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,UAAU,GACf,OAAO,CAAC,IAAI,CAAC,CAMf"}

package/dist/node.js

@@ -3,8 +3,8 @@ import {
   createImplement,
   createSocketIOServer,
   implement
-} from "./index-g8kyab85.js";
-import"./index-tje0q6gp.js";
+} from "./index-y4132gqh.js";
+import"./index-zfscdskj.js";
 import {
   AppError,
   appError,
@@ -14,7 +14,7 @@ import {
   notFound,
   rateLimited,
   unauthorized
-} from "./index-4gawbm74.js";
+} from "./index-zza375qp.js";
 import"./index-dzx781tm.js";
 import"./index-khwedj16.js";
 import"./index-c7nyw0yt.js";

package/dist/server/create.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create.d.ts","sourceRoot":"","sources":["../../src/server/create.ts"],"names":[],"mappings":"AA+BA,OAAO,KAAK,EAEV,eAAe,EACf,aAAa,EAGd,MAAM,SAAS,CAAC;AAEjB,wBAAgB,aAAa,CAAC,MAAM,EAAE,aAAa,GAAG,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CA8NxF;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,eAAe,uBAsBnD"}
+{"version":3,"file":"create.d.ts","sourceRoot":"","sources":["../../src/server/create.ts"],"names":[],"mappings":"AAgCA,OAAO,KAAK,EAEV,eAAe,EACf,aAAa,EAGd,MAAM,SAAS,CAAC;AAEjB,wBAAgB,aAAa,CAAC,MAAM,EAAE,aAAa,GAAG,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAyRxF;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,eAAe,uBAsBnD"}

package/dist/server/error-hook.d.ts

@@ -22,11 +22,16 @@
  *     CONFLICT: 'conflict', RATE_LIMITED: 'rate_limited',
  *     INTERNAL_SERVER_ERROR: 'internal',
  *   } satisfies Record<StitchErrorCode, string>,
- *   render: (info) => ({ ok: false, error: { code: info.code, message: info.message } }),
+ *   render: (info, ctx) => ({
+ *     ok: false,
+ *     error: { code: info.code, message: info.message },
+ *     traceId: ctx.traceId,
+ *   }),
  * });
  * createServer({ services, hooks: { onError } });
  * ```
  */
+import type { RuntimeContext } from '../contract';
 import { type StitchErrorCode } from '../contract';
 import type { LifecycleHooks } from './types';
 /** The normalised error handed to `render` — code already remapped. */
@@ -51,9 +56,15 @@ export interface ErrorHookConfig<TWireCode extends string = string> {
      */
     codeMap?: Record<StitchErrorCode, TWireCode>;
     /** Build the response body from the resolved error. */
-    render: (info: ResolvedError) => unknown;
+    /**
+     * Build the response body from the resolved error. `ctx` is the request's
+     * `RuntimeContext` — read `ctx.traceId` / `ctx.spanId` to put a correlation id
+     * in the envelope, which is the ordinary reason to have one. Declaring the
+     * parameter is optional: a one-argument `render` stays assignable.
+     */
+    render: (info: ResolvedError, ctx: RuntimeContext) => unknown;
     /** Observe the raw thrown value before rendering — logging / metrics. */
-    onError?: (error: unknown, info: ResolvedError) => void;
+    onError?: (error: unknown, info: ResolvedError, ctx: RuntimeContext) => void;
 }
 /** Build an `onError` hook from a code map + envelope renderer. */
 export declare function createErrorHook<TWireCode extends string = string>(config: ErrorHookConfig<TWireCode>): NonNullable<LifecycleHooks['onError']>;

package/dist/server/error-hook.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"error-hook.d.ts","sourceRoot":"","sources":["../../src/server/error-hook.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,OAAO,EAAqB,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC;AAEtE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C,uEAAuE;AACvE,MAAM,WAAW,aAAa;IAC5B,wFAAwF;IACxF,IAAI,EAAE,MAAM,CAAC;IACb,mBAAmB;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,+FAA+F;IAC/F,OAAO,EAAE,MAAM,CAAC;IAChB,mEAAmE;IACnE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,6DAA6D;IAC7D,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,oCAAoC;AACpC,MAAM,WAAW,eAAe,CAAC,SAAS,SAAS,MAAM,GAAG,MAAM;IAChE;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,eAAe,EAAE,SAAS,CAAC,CAAC;IAC7C,uDAAuD;IACvD,MAAM,EAAE,CAAC,IAAI,EAAE,aAAa,KAAK,OAAO,CAAC;IACzC,yEAAyE;IACzE,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,aAAa,KAAK,IAAI,CAAC;CACzD;AAED,mEAAmE;AACnE,wBAAgB,eAAe,CAAC,SAAS,SAAS,MAAM,GAAG,MAAM,EAC/D,MAAM,EAAE,eAAe,CAAC,SAAS,CAAC,GACjC,WAAW,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC,CAyBxC"}
+{"version":3,"file":"error-hook.d.ts","sourceRoot":"","sources":["../../src/server/error-hook.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAAqB,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC;AAEtE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C,uEAAuE;AACvE,MAAM,WAAW,aAAa;IAC5B,wFAAwF;IACxF,IAAI,EAAE,MAAM,CAAC;IACb,mBAAmB;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,+FAA+F;IAC/F,OAAO,EAAE,MAAM,CAAC;IAChB,mEAAmE;IACnE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,6DAA6D;IAC7D,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,oCAAoC;AACpC,MAAM,WAAW,eAAe,CAAC,SAAS,SAAS,MAAM,GAAG,MAAM;IAChE;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,eAAe,EAAE,SAAS,CAAC,CAAC;IAC7C,uDAAuD;IACvD;;;;;OAKG;IACH,MAAM,EAAE,CAAC,IAAI,EAAE,aAAa,EAAE,GAAG,EAAE,cAAc,KAAK,OAAO,CAAC;IAC9D,yEAAyE;IACzE,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,aAAa,EAAE,GAAG,EAAE,cAAc,KAAK,IAAI,CAAC;CAC9E;AAED,mEAAmE;AACnE,wBAAgB,eAAe,CAAC,SAAS,SAAS,MAAM,GAAG,MAAM,EAC/D,MAAM,EAAE,eAAe,CAAC,SAAS,CAAC,GACjC,WAAW,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC,CAyBxC"}

package/dist/server/implement.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"implement.d.ts","sourceRoot":"","sources":["../../src/server/implement.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE5E,OAAO,KAAK,EAAE,QAAQ,EAAa,UAAU,EAAE,MAAM,SAAS,CAAC;AAE/D;;;;;GAKG;AACH,wBAAgB,SAAS,CACvB,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,EACrC,IAAI,SAAS,cAAc,GAAG,cAAc,EAC5C,QAAQ,EAAE,WAAW,CAAC,CAAC,EAAE,MAAM,CAAC,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,UAAU,CA+C3E;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,SAAS,cAAc,MACjD,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,EAC3C,UAAU,WAAW,CAAC,CAAC,EAAE,MAAM,CAAC,EAChC,UAAU,QAAQ,CAAC,CAAC,EAAE,IAAI,CAAC,KAC1B,UAAU,CACd"}
+{"version":3,"file":"implement.d.ts","sourceRoot":"","sources":["../../src/server/implement.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAG5E,OAAO,KAAK,EAAE,QAAQ,EAAa,UAAU,EAAE,MAAM,SAAS,CAAC;AAK/D;;;;;GAKG;AACH,wBAAgB,SAAS,CACvB,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,EACrC,IAAI,SAAS,cAAc,GAAG,cAAc,EAC5C,QAAQ,EAAE,WAAW,CAAC,CAAC,EAAE,MAAM,CAAC,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,UAAU,CAyD3E;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,SAAS,cAAc,MACjD,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,EAC3C,UAAU,WAAW,CAAC,CAAC,EAAE,MAAM,CAAC,EAChC,UAAU,QAAQ,CAAC,CAAC,EAAE,IAAI,CAAC,KAC1B,UAAU,CACd"}

package/dist/server/index.d.ts

@@ -1,5 +1,6 @@
 export { AppError, appError, badRequest, conflict, forbidden, isStitchErrorCode, notFound, rateLimited, STITCH_ERROR_STATUS, type StitchErrorCode, unauthorized, } from '../contract';
 export { errorCode, formatZodError, normalizeError, type ZodIssueSummary, zodIssues, } from '../internal/errors';
+export { isWithinDir } from '../internal/within-dir';
 export { cacheHeaders, createCache } from './cache';
 export { createHandler, createServer } from './create';
 export { createErrorHook, type ErrorHookConfig, type ResolvedError, } from './error-hook';
@@ -8,7 +9,7 @@ export { type ByteRange, parseByteRange, type ServeFileOptions, serveFile, weakE
 export { createImplement, implement } from './implement';
 export { type AuthHook, type AuthHookConfig, type AuthRule, type BearerResolverConfig, createAuthHook, createBearerResolver, extractToken, type JwtPayload, type SignJwtOptions, signJwt, verifyJwt, } from './middleware/auth';
 export { type CookieDef, type CookieOptions, defineCookie, parseCookies, serializeCookie, } from './middleware/cookies';
-export { type CorsConfig, corsHeaders, corsPreflightResponse, DEFAULT_CORS_ALLOW_HEADERS, } from './middleware/cors';
+export { type CorsConfig, corsHeaders, corsPreflightResponse, DEFAULT_CORS_ALLOW_HEADERS, DEFAULT_CORS_EXPOSE_HEADERS, } from './middleware/cors';
 export { deriveCodeChallenge, type PkceMethod, verifyPkce } from './middleware/pkce';
 export { parseMultipart } from './multipart';
 export { generateOpenApiDocument, type OpenApiConfig, type OpenApiDocument, type OpenApiInfo, type OpenApiServer, openApiRoute, } from './openapi';

package/dist/server/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,QAAQ,EACR,QAAQ,EACR,UAAU,EACV,QAAQ,EACR,SAAS,EACT,iBAAiB,EACjB,QAAQ,EACR,WAAW,EACX,mBAAmB,EACnB,KAAK,eAAe,EACpB,YAAY,GACb,MAAM,aAAa,CAAC;AAIrB,OAAO,EACL,SAAS,EACT,cAAc,EACd,cAAc,EACd,KAAK,eAAe,EACpB,SAAS,GACV,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AACpD,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACvD,OAAO,EACL,eAAe,EACf,KAAK,eAAe,EACpB,KAAK,aAAa,GACnB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,cAAc,EAAE,KAAK,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,EACL,KAAK,SAAS,EACd,cAAc,EACd,KAAK,gBAAgB,EACrB,SAAS,EACT,QAAQ,GACT,MAAM,QAAQ,CAAC;AAChB,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EACL,KAAK,QAAQ,EACb,KAAK,cAAc,EACnB,KAAK,QAAQ,EACb,KAAK,oBAAoB,EACzB,cAAc,EACd,oBAAoB,EACpB,YAAY,EACZ,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,OAAO,EACP,SAAS,GACV,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,KAAK,SAAS,EACd,KAAK,aAAa,EAClB,YAAY,EACZ,YAAY,EACZ,eAAe,GAChB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,KAAK,UAAU,EACf,WAAW,EACX,qBAAqB,EACrB,0BAA0B,GAC3B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,mBAAmB,EAAE,KAAK,UAAU,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACrF,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EACL,uBAAuB,EACvB,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,YAAY,GACb,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,iBAAiB,EAAE,KAAK,eAAe,EAAE,MAAM,cAAc,CAAC;AACvE,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AAC9D,OAAO,EACL,KAAK,eAAe,EACpB,SAAS,EACT,eAAe,EACf,aAAa,EACb,eAAe,EACf,cAAc,GACf,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACvC,YAAY,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAC9E,OAAO,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACjE,OAAO,EAAE,KAAK,eAAe,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACrE,YAAY,EACV,SAAS,EACT,eAAe,EACf,aAAa,EACb,QAAQ,EACR,cAAc,EACd,SAAS,EACT,QAAQ,EACR,eAAe,EACf,UAAU,EACV,iBAAiB,EACjB,UAAU,EACV,YAAY,GACb,MAAM,SAAS,CAAC;AACjB,OAAO,EACL,KAAK,YAAY,EACjB,wBAAwB,EACxB,KAAK,sBAAsB,EAC3B,KAAK,aAAa,EAClB,aAAa,GACd,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,QAAQ,EACR,QAAQ,EACR,UAAU,EACV,QAAQ,EACR,SAAS,EACT,iBAAiB,EACjB,QAAQ,EACR,WAAW,EACX,mBAAmB,EACnB,KAAK,eAAe,EACpB,YAAY,GACb,MAAM,aAAa,CAAC;AAIrB,OAAO,EACL,SAAS,EACT,cAAc,EACd,cAAc,EACd,KAAK,eAAe,EACpB,SAAS,GACV,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AACpD,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACvD,OAAO,EACL,eAAe,EACf,KAAK,eAAe,EACpB,KAAK,aAAa,GACnB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,cAAc,EAAE,KAAK,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,EACL,KAAK,SAAS,EACd,cAAc,EACd,KAAK,gBAAgB,EACrB,SAAS,EACT,QAAQ,GACT,MAAM,QAAQ,CAAC;AAChB,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EACL,KAAK,QAAQ,EACb,KAAK,cAAc,EACnB,KAAK,QAAQ,EACb,KAAK,oBAAoB,EACzB,cAAc,EACd,oBAAoB,EACpB,YAAY,EACZ,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,OAAO,EACP,SAAS,GACV,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,KAAK,SAAS,EACd,KAAK,aAAa,EAClB,YAAY,EACZ,YAAY,EACZ,eAAe,GAChB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,KAAK,UAAU,EACf,WAAW,EACX,qBAAqB,EACrB,0BAA0B,EAC1B,2BAA2B,GAC5B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,mBAAmB,EAAE,KAAK,UAAU,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACrF,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EACL,uBAAuB,EACvB,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,YAAY,GACb,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,iBAAiB,EAAE,KAAK,eAAe,EAAE,MAAM,cAAc,CAAC;AACvE,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AAC9D,OAAO,EACL,KAAK,eAAe,EACpB,SAAS,EACT,eAAe,EACf,aAAa,EACb,eAAe,EACf,cAAc,GACf,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACvC,YAAY,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAC9E,OAAO,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACjE,OAAO,EAAE,KAAK,eAAe,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACrE,YAAY,EACV,SAAS,EACT,eAAe,EACf,aAAa,EACb,QAAQ,EACR,cAAc,EACd,SAAS,EACT,QAAQ,EACR,eAAe,EACf,UAAU,EACV,iBAAiB,EACjB,UAAU,EACV,YAAY,GACb,MAAM,SAAS,CAAC;AACjB,OAAO,EACL,KAAK,YAAY,EACjB,wBAAwB,EACxB,KAAK,sBAAsB,EAC3B,KAAK,aAAa,EAClB,aAAa,GACd,MAAM,aAAa,CAAC"}

package/dist/server/index.js

@@ -10,7 +10,7 @@ import {
   socketIoLane,
   staticRoute,
   webSocketLane
-} from "../index-g8kyab85.js";
+} from "../index-y4132gqh.js";
 import {
   createAuthHook,
   createBearerResolver,
@@ -23,12 +23,13 @@ import {
   signJwt,
   verifyJwt,
   verifyPkce
-} from "../index-a9n8m4ec.js";
+} from "../index-jvescqgr.js";
 import {
   DEFAULT_CORS_ALLOW_HEADERS,
+  DEFAULT_CORS_EXPOSE_HEADERS,
   corsHeaders,
   corsPreflightResponse
-} from "../index-tje0q6gp.js";
+} from "../index-zfscdskj.js";
 import {
   jsonSchemaFields,
   toJsonSchema
@@ -43,12 +44,13 @@ import {
   forbidden,
   formatZodError,
   isStitchErrorCode,
+  isWithinDir,
   normalizeError,
   notFound,
   rateLimited,
   unauthorized,
   zodIssues
-} from "../index-4gawbm74.js";
+} from "../index-zza375qp.js";
 import {
   extractIp,
   generateTraceId,
@@ -120,7 +122,7 @@ function cacheHeaders(maxAge, scope = "public") {
 }
 // src/server/error-hook.ts
 function createErrorHook(config) {
-  return (_ctx, error) => {
+  return (ctx, error) => {
     const appErr = normalizeError(error);
     const code = config.codeMap && isStitchErrorCode(appErr.code) ? config.codeMap[appErr.code] : appErr.code;
     const info = {
@@ -130,8 +132,8 @@ function createErrorHook(config) {
       details: appErr.details,
       hint: appErr.hint
     };
-    config.onError?.(error, info);
-    return new Response(JSON.stringify(config.render(info)), {
+    config.onError?.(error, info, ctx);
+    return new Response(JSON.stringify(config.render(info, ctx)), {
       status: info.status,
       headers: { "content-type": "application/json" }
     });
@@ -425,7 +427,16 @@ function generateOpenApiDocument(config) {
         }
       }
       const responses = { ...errorResponses(method.scope) };
-      if (method.outputSchema) {
+      if (method.rawResponse) {
+        responses["200"] = {
+          description: "Success",
+          content: {
+            [method.contentType ?? "application/octet-stream"]: {
+              schema: { type: "string", format: "binary" }
+            }
+          }
+        };
+      } else if (method.outputSchema) {
         responses["200"] = {
           description: "Success",
           content: { "application/json": { schema: safeJson(method.outputSchema, "output") } }
@@ -645,6 +656,7 @@ export {
   openApiRoute,
   notFound,
   normalizeError,
+  isWithinDir,
   isStitchErrorCode,
   implement,
   getClientInfo,
@@ -676,6 +688,7 @@ export {
   badRequest,
   appError,
   STITCH_ERROR_STATUS,
+  DEFAULT_CORS_EXPOSE_HEADERS,
   DEFAULT_CORS_ALLOW_HEADERS,
   AppError
 };

package/dist/server/middleware/cors.d.ts

@@ -3,6 +3,12 @@ export interface CorsConfig {
     credentials?: boolean;
     methods?: string;
     headers?: string;
+    /**
+     * Response headers a cross-origin caller is allowed to *read*
+     * (`Access-Control-Expose-Headers`). Defaults to
+     * {@link DEFAULT_CORS_EXPOSE_HEADERS}; pass `[]` to emit none.
+     */
+    exposeHeaders?: string | string[];
 }
 /**
  * The default `Access-Control-Allow-Headers` — the request headers stitchkit's
@@ -17,6 +23,19 @@ export interface CorsConfig {
  *   feature dies on the cross-origin preflight.
  */
 export declare const DEFAULT_CORS_ALLOW_HEADERS = "Content-Type, Authorization, X-Trace-Id, traceparent, tracestate";
+/**
+ * The default `Access-Control-Expose-Headers`. Without it a cross-origin
+ * `fetch` can read only the CORS-safelisted response headers, so a browser
+ * downloading a file cannot recover its name (`Content-Disposition`), and a
+ * client cannot revalidate (`ETag`) or resume (`Content-Range`) — the very
+ * headers `serveFile` exists to emit.
+ *
+ * An explicit list rather than `*`, because the wildcard is ignored whenever
+ * the request carries credentials — exactly the authenticated download case.
+ * These are headers the server already chose to send; exposing them reveals
+ * nothing new. Opt out with `exposeHeaders: []`.
+ */
+export declare const DEFAULT_CORS_EXPOSE_HEADERS = "Content-Disposition, Content-Length, Content-Range, Accept-Ranges, ETag, Last-Modified, X-Trace-Id";
 /**
  * Reject an unsafe CORS config at construction. `credentials: true` with a
  * wildcard origin would reflect *any* caller's `Origin` with

package/dist/server/middleware/cors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cors.d.ts","sourceRoot":"","sources":["../../../src/server/middleware/cors.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,UAAU;IACzB,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC3B,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,0BAA0B,qEAC6B,CAAC;AAErE;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,CAOzD;AAoBD,wBAAgB,WAAW,CACzB,MAAM,EAAE,UAAU,EAClB,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,GAC5B,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAqBxB;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,UAAU,EAAE,GAAG,EAAE,OAAO,GAAG,QAAQ,CAKhF"}
+{"version":3,"file":"cors.d.ts","sourceRoot":"","sources":["../../../src/server/middleware/cors.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,UAAU;IACzB,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC3B,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;CACnC;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,0BAA0B,qEAC6B,CAAC;AAErE;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,2BAA2B,uGAC8D,CAAC;AAEvG;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,CAOzD;AAoBD,wBAAgB,WAAW,CACzB,MAAM,EAAE,UAAU,EAClB,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,GAC5B,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CA2BxB;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,UAAU,EAAE,GAAG,EAAE,OAAO,GAAG,QAAQ,CAKhF"}

package/dist/server/openapi.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"openapi.d.ts","sourceRoot":"","sources":["../../src/server/openapi.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAE/D,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,WAAW,CAAC;IAClB,kDAAkD;IAClD,QAAQ,CAAC,EAAE,UAAU,EAAE,CAAC;IACxB,iFAAiF;IACjF,MAAM,CAAC,EAAE,KAAK,CAAC;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,UAAU,EAAE,CAAA;KAAE,CAAC,CAAC;IAChE,oCAAoC;IACpC,OAAO,CAAC,EAAE,aAAa,EAAE,CAAC;IAC1B;;;;;;;;;;;OAWG;IACH,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE,QAAQ,CAAC,SAAS,CAAC,KAAK,OAAO,CAAC;CAC1D;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,WAAW,CAAC;IAClB,OAAO,CAAC,EAAE,aAAa,EAAE,CAAC;IAC1B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAChD;AAsED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,aAAa,GAAG,eAAe,CAuH9E;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,GAAG,QAAQ,CAM9E"}
+{"version":3,"file":"openapi.d.ts","sourceRoot":"","sources":["../../src/server/openapi.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAE/D,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,WAAW,CAAC;IAClB,kDAAkD;IAClD,QAAQ,CAAC,EAAE,UAAU,EAAE,CAAC;IACxB,iFAAiF;IACjF,MAAM,CAAC,EAAE,KAAK,CAAC;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,UAAU,EAAE,CAAA;KAAE,CAAC,CAAC;IAChE,oCAAoC;IACpC,OAAO,CAAC,EAAE,aAAa,EAAE,CAAC;IAC1B;;;;;;;;;;;OAWG;IACH,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE,QAAQ,CAAC,SAAS,CAAC,KAAK,OAAO,CAAC;CAC1D;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,WAAW,CAAC;IAClB,OAAO,CAAC,EAAE,aAAa,EAAE,CAAC;IAC1B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAChD;AAsED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,aAAa,GAAG,eAAe,CAmI9E;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,GAAG,QAAQ,CAM9E"}

package/dist/server/router.d.ts

@@ -27,6 +27,33 @@ export declare function matchRoute(routeMap: RouteMap, httpMethod: string, pathn
 export declare function allowedMethods(routeMap: RouteMap, pathname: string): string[];
 /** Startup guard — throws when two routes collapse to the same shape. */
 export declare function validateRoutes(routeMap: RouteMap): void;
+/** One contract route that a raw route matches first, so the contract route is dead. */
+export interface ShadowedRoute {
+    /** The contract route pattern, e.g. `GET /documents/:id/pdf`. */
+    pattern: string;
+    /** `serviceName.key` of the endpoint that will never run. */
+    endpoint: string;
+    /** The raw route that wins, e.g. `GET /documents/:id/pdf` or `ALL /files/*`. */
+    rawRoute: string;
+    /** The shadowed endpoint's scope — the auth gate the raw route bypasses. */
+    scope?: string;
+}
+/**
+ * Startup diagnostic — raw routes are matched **before** contract routes, so a
+ * raw route covering a contract path silently wins and the endpoint never runs.
+ *
+ * This matters most for the migration raw-response endpoints exist to enable
+ * (→ ADR 0038): move a download out of `rawRoutes` into the contract to gain the
+ * auth gate, forget to delete the old raw route, and the bytes keep being served
+ * ungated — with no error anywhere. Reported, not thrown: an overlapping
+ * wildcard (a SPA fallback) can be deliberate, and refusing to boot a working
+ * app would be the worse failure.
+ *
+ * Detection runs the **real** `matchRawRoute` against a concrete probe path
+ * built from each contract route, so it can never disagree with what the
+ * dispatcher actually does.
+ */
+export declare function findShadowedRoutes(routeMap: RouteMap, rawRoutes: RawRoute[] | undefined): ShadowedRoute[];
 export declare function matchRawRoute(rawRoutes: RawRoute[], httpMethod: string, pathname: string): {
     route: RawRoute;
     params: Record<string, string>;

package/dist/server/router.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../../src/server/router.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAE/E,4EAA4E;AAC5E,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,UAAU,CAAC;IACpB,KAAK,CAAC,EAAE,cAAc,CAAC;CACxB;AAED,UAAU,UAAU;IAClB,MAAM,EAAE,SAAS,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,UAAU,CAAC,EAAE,cAAc,CAAC;CAC7B;AAED,+EAA+E;AAC/E,MAAM,MAAM,QAAQ,GAAG,GAAG,CAAC,MAAM,EAAE,UAAU,EAAE,CAAC,CAAC;AAEjD,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,SAAS,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,UAAU,CAAC,EAAE,cAAc,CAAC;CAC7B;AAqCD,wBAAgB,aAAa,CAAC,MAAM,EAAE,eAAe,EAAE,GAAG,QAAQ,CAmCjE;AAED,wBAAgB,UAAU,CACxB,QAAQ,EAAE,QAAQ,EAClB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACf,UAAU,GAAG,IAAI,CAkBnB;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAc7E;AAED,yEAAyE;AACzE,wBAAgB,cAAc,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAiBvD;AAID,wBAAgB,aAAa,CAC3B,SAAS,EAAE,QAAQ,EAAE,EACrB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACf;IAAE,KAAK,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GAAG,IAAI,CAkC5D;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,QAAQ,CAkCjE"}
+{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../../src/server/router.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAE/E,4EAA4E;AAC5E,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,UAAU,CAAC;IACpB,KAAK,CAAC,EAAE,cAAc,CAAC;CACxB;AAED,UAAU,UAAU;IAClB,MAAM,EAAE,SAAS,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,UAAU,CAAC,EAAE,cAAc,CAAC;CAC7B;AAED,+EAA+E;AAC/E,MAAM,MAAM,QAAQ,GAAG,GAAG,CAAC,MAAM,EAAE,UAAU,EAAE,CAAC,CAAC;AAEjD,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,SAAS,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,UAAU,CAAC,EAAE,cAAc,CAAC;CAC7B;AAqCD,wBAAgB,aAAa,CAAC,MAAM,EAAE,eAAe,EAAE,GAAG,QAAQ,CAmCjE;AAED,wBAAgB,UAAU,CACxB,QAAQ,EAAE,QAAQ,EAClB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACf,UAAU,GAAG,IAAI,CAkBnB;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAc7E;AAED,yEAAyE;AACzE,wBAAgB,cAAc,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAiBvD;AAED,wFAAwF;AACxF,MAAM,WAAW,aAAa;IAC5B,iEAAiE;IACjE,OAAO,EAAE,MAAM,CAAC;IAChB,6DAA6D;IAC7D,QAAQ,EAAE,MAAM,CAAC;IACjB,gFAAgF;IAChF,QAAQ,EAAE,MAAM,CAAC;IACjB,4EAA4E;IAC5E,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,QAAQ,EAClB,SAAS,EAAE,QAAQ,EAAE,GAAG,SAAS,GAChC,aAAa,EAAE,CAmBjB;AAID,wBAAgB,aAAa,CAC3B,SAAS,EAAE,QAAQ,EAAE,EACrB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACf;IAAE,KAAK,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GAAG,IAAI,CAkC5D;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,QAAQ,CAkCjE"}

package/dist/server/types.d.ts

@@ -5,11 +5,33 @@ type Prop<T, K extends string> = K extends keyof T ? T[K] : undefined;
 type InferParams<E> = Prop<E, 'params'> extends ZodType<infer P> ? P : undefined;
 type InferInput<E> = Prop<E, 'input'> extends ZodType<infer I> ? I : undefined;
 type InferOutput<E> = Prop<E, 'output'> extends ZodType<infer O> ? O : never;
+/**
+ * What an endpoint's handler must return: the `Response` itself for a `raw`
+ * endpoint, the output type when there is an output schema, nothing otherwise.
+ * Enforced in both directions — a raw handler returning data and a normal
+ * handler returning a `Response` are both compile errors (the latter used to
+ * be accepted and silently serialized to `{}`).
+ */
+type HandlerReturn<E> = E extends {
+    rawResponse: true;
+} ? Response | Promise<Response> : Prop<E, 'output'> extends ZodType ? Promise<InferOutput<E>> | InferOutput<E> : void | Promise<void>;
+/**
+ * `ctx.req` is optional in general — a tool call has no `Request`. A raw
+ * endpoint is HTTP-only by declaration, and its handler needs the request
+ * (`serveFile(ctx.req, …)` reads `Range` / `If-None-Match`), so it is narrowed
+ * to a guaranteed `Request` there rather than making every raw handler write
+ * a non-null assertion. → ADR 0038.
+ */
+type RequiredRequest<E> = E extends {
+    rawResponse: true;
+} ? {
+    req: Request;
+} : unknown;
 export type Handlers<C extends Record<string, EndpointDef>, TCtx extends RuntimeContext = HandlerContext> = {
     [K in keyof C]: (ctx: TCtx & {
         params: InferParams<C[K]>;
         input: InferInput<C[K]>;
-    }) => Prop<C[K], 'output'> extends ZodType ? Promise<InferOutput<C[K]>> | InferOutput<C[K]> : void | Promise<void>;
+    } & RequiredRequest<C[K]>) => HandlerReturn<C[K]>;
 };
 export interface MethodDef<TParams = unknown, TInput = unknown, TOutput = unknown> {
     method: HttpMethod;
@@ -54,6 +76,14 @@ export interface MethodDef<TParams = unknown, TInput = unknown, TOutput = unknow
      * the consumer narrows the type. Never serialized to OpenAPI. → ADR 0021.
      */
     meta?: Record<string, unknown>;
+    /**
+     * The handler returns the `Response` itself — from `EndpointDef.rawResponse`. Routed
+     * and gated like any endpoint, but never serialized, never validated against
+     * an output schema and never mounted as a tool. → ADR 0038.
+     */
+    rawResponse?: true;
+    /** Documented response media type of a raw-response endpoint — OpenAPI only. */
+    contentType?: string;
     handler: (ctx: RuntimeContext) => Promise<TOutput> | TOutput;
 }
 export interface ServiceDef {
@@ -152,6 +182,19 @@ export interface HandlerConfig {
     cors?: CorsConfig;
     hooks?: LifecycleHooks;
     logging?: boolean | StitchLogger;
+    /**
+     * Report handler-output keys the contract schema removed, as dot-paths, through
+     * the configured logger. **Off by default** — the strip itself is correct (the
+     * contract is the published shape of the response), it is only *invisible*, and
+     * a permanent key-diff on every response is the wrong price for that.
+     *
+     * Turn it on while migrating a live API: your handlers may be returning more
+     * than the contract declares, and nothing else will tell you — types cannot
+     * (structural typing does not reject excess properties) and the client just
+     * receives fewer fields. Read the list, fix or widen the contracts, turn it off.
+     * → ADR 0037.
+     */
+    warnOnOutputStrip?: boolean;
     traceId?: (req: Request) => string;
     /**
      * Trust the `x-forwarded-for` / `x-real-ip` headers for the client IP.