lambder 7.2.5 → 8.0.2

package/dist/core/LambderResponse.js

@@ -29,11 +29,26 @@ export class LambderResponse {
         this.compress = init.compress ?? "auto";
         this.etag = init.etag ?? "auto";
     }
-    // The three header methods are the core's own header helpers over this
-    // response's map: the case-insensitive lookup, the replace-under-any-casing
-    // and the append-under-the-existing-casing rules are one implementation,
-    // not a copy per class, so an answer and a response can never disagree
-    // about what setting a header means.
+    /**
+     * A copy with its own header lists, for a request to write into. A
+     * handler may answer with an object it keeps between requests (a
+     * module-level 404), and everything downstream adds headers (cookies,
+     * CORS, Vary, Content-Encoding, ETag), which would carry one caller's
+     * Set-Cookie to the next. The body is shared: nothing writes into it.
+     */
+    copy() {
+        return new LambderResponse({
+            statusCode: this.statusCode,
+            headers: this.headers,
+            body: this.body,
+            isBodyBase64: this.isBodyBase64,
+            compress: this.compress,
+            etag: this.etag,
+        });
+    }
+    // The header methods delegate to the core's header helpers, so an answer
+    // and a response share one implementation of the case-insensitive lookup,
+    // replace and append rules and can never disagree about what they mean.
     getHeader(key) {
         return getAnswerHeader(this.headers, key);
     }
@@ -67,13 +82,12 @@ export const answerFromResponse = (response) => {
 /**
  * An answer's status as the response model spells statuses.
  *
- * LambderHttpStatusCode is an authoring surface: it exists so `res.status(...)`
- * offers the codes an app writes and catches the typo'd one. An answer is
- * plain data that already left that surface (a replay the idempotency store
- * persisted, a mock's answer, a third adapter's), so its status is a number
- * and a code outside the union is not a reason to refuse a request the app
- * has already answered. Stated once here rather than as a bare cast at the
- * call site, so the widening is a decision a reader can see.
+ * LambderHttpStatusCode is an authoring surface: it lets `res.status(...)`
+ * offer the codes an app writes and catch a typo. An answer is plain data
+ * that has already left that surface (a persisted replay, a mock's answer),
+ * so a code outside the union is no reason to refuse a request the app has
+ * already answered. A named function rather than a bare cast at the call
+ * site, so the widening is visible to a reader.
  */
 const httpStatusOfAnswer = (statusCode) => statusCode;
 /** A core answer as the response hooks, CORS and finalization work on. */
@@ -85,10 +99,10 @@ export const responseFromAnswer = (answer) => new LambderResponse({
     compress: answer.compress ?? "auto",
     etag: answer.etag ?? "auto",
 });
-const isCompressibleContentType = (contentType) => {
-    if (!contentType)
-        return false;
-    const mime = (contentType.split(";")[0] ?? "").trim().toLowerCase();
+const mimeOf = (contentType) => (contentType?.split(";")[0] ?? "").trim().toLowerCase();
+/** A content type whose body is text: sent as text when it is valid UTF-8 and not compressed. */
+const isTextContentType = (contentType) => {
+    const mime = mimeOf(contentType);
     if (mime.startsWith("text/"))
         return true;
     if (mime.endsWith("+json") || mime.endsWith("+xml"))
@@ -98,11 +112,21 @@ const isCompressibleContentType = (contentType) => {
         "application/javascript",
         "application/x-javascript",
         "application/xml",
-        "application/wasm",
-        "image/svg+xml",
         "application/lambder-json-stream",
     ].includes(mime);
 };
+const isCompressibleContentType = (contentType) => isTextContentType(contentType) || mimeOf(contentType) === "application/wasm";
+/** Strict, and keeping a byte-order mark, so a body that decodes is exactly its bytes as text. */
+const strictUtf8 = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+/** The bytes as text when they are valid UTF-8, or null. */
+const utf8TextOf = (bytes) => {
+    try {
+        return strictUtf8.decode(bytes);
+    }
+    catch {
+        return null;
+    }
+};
 const acceptsEncoding = (acceptEncoding, encoding) => {
     if (!acceptEncoding)
         return false;
@@ -129,7 +153,7 @@ export const DEFAULT_RESPONSE_COMPRESSION_SETTINGS = {
     quality: 5,
 };
 export const DEFAULT_FINALIZE_OPTIONS = {
-    compression: DEFAULT_RESPONSE_COMPRESSION_SETTINGS,
+    compression: { v1: null, v2: DEFAULT_RESPONSE_COMPRESSION_SETTINGS },
     etag: true,
     maxResponseBytes: 5_500_000,
 };
@@ -137,27 +161,66 @@ export const DEFAULT_FINALIZE_OPTIONS = {
  * The headers a 304 leaves behind: they describe a body, and a 304 carries
  * none. Everything else goes with it.
  *
- * A keep-list of cache headers instead of this drop-list would quietly make a
- * revalidation the one exit of the request where the call's headers do not
- * belong to the call: a cacheable GET that also slides a session cookie would
- * stop refreshing it the moment the browser held the ETag, and a cross-origin
- * revalidation would lose Access-Control-Allow-Origin, so the browser would
- * refuse the 304 it had asked for.
+ * A keep-list of cache headers would make revalidation the one exit where the
+ * call's headers do not reach the client: a cacheable GET that slides a
+ * session cookie would stop refreshing it once the browser held the ETag, and
+ * a cross-origin revalidation would lose Access-Control-Allow-Origin, so the
+ * browser would refuse the 304 it asked for.
  */
 const HEADERS_DROPPED_ON_NOT_MODIFIED = ["content-type", "content-length", "content-encoding"];
+/** The hash an ETag is made from, or null where Node's crypto is not available. */
+const bodyHashOf = async (body) => {
+    const crypto = await getCrypto();
+    if (!crypto)
+        return null;
+    return crypto.createHash("sha256").update(body).digest("hex").slice(0, 32);
+};
+/** Cache-Control directives that offer a copy to shared caches, or describe that shared copy. */
+const SHARED_CACHE_DIRECTIVES = ["public", "s-maxage", "immutable"];
+/** Cache-Control directives that already keep a whole answer out of shared caches. */
+const PRIVATE_CACHE_DIRECTIVES = ["private", "no-store"];
+/**
+ * The headers with their Cache-Control made `private` when the answer sets a
+ * cookie. A cookie is one visitor's, and a shared cache (a CDN, a proxy)
+ * that stores an answer with its Set-Cookie hands that cookie to everyone it
+ * serves the copy to: a hook that issues a guest session, or a session read
+ * that slides the cookies, would otherwise send a visitor's session out on a
+ * content-hashed asset marked `public, max-age=31536000, immutable`. So
+ * `public` gives way to `private`, and `s-maxage` and `immutable` go with
+ * it: the first speaks only to shared caches, and the second promises a
+ * representation every visitor shares, which an answer carrying one
+ * visitor's cookie is not. The visitor's own cache keeps max-age. An answer
+ * that already says `private` or `no-store`, or says nothing about caching,
+ * is left as it is. Never mutates what it was given.
+ */
+const privateWhenSettingCookies = (headers) => {
+    const cacheControl = getAnswerHeader(headers, "cache-control");
+    if (!cacheControl?.length || !getAnswerHeader(headers, "set-cookie")?.length)
+        return headers;
+    const directives = cacheControl.flatMap((value) => value.split(",")).map((directive) => directive.trim()).filter(Boolean);
+    const nameOf = (directive) => (directive.split("=")[0] ?? "").trim().toLowerCase();
+    if (directives.some((directive) => PRIVATE_CACHE_DIRECTIVES.includes(nameOf(directive))))
+        return headers;
+    const privateHeaders = { ...headers };
+    setAnswerHeader(privateHeaders, "Cache-Control", ["private", ...directives.filter((directive) => !SHARED_CACHE_DIRECTIVES.includes(nameOf(directive)))].join(", "));
+    return privateHeaders;
+};
 /**
  * Emit the format-specific Lambda response shape. Exported because the
  * last-resort crash path has to emit without finalizing (finalization may be
- * what failed) and must still get the shape right; hand-writing it there left
- * the v1/v2 split in four places.
+ * what failed) and must still get the shape right, so the v1/v2 split lives
+ * in this one place. Being the one exit every answer leaves through (each of
+ * finalization's, the 304 included, and the crash path's), it is also where
+ * an answer that sets a cookie is made private (privateWhenSettingCookies).
  */
 export const emitResponse = (format, statusCode, headers, body, isBase64Encoded) => {
+    const sentHeaders = privateWhenSettingCookies(headers);
     if (format === "v2") {
         // Payload v2 has no multiValueHeaders: multi-values are comma-joined,
         // except Set-Cookie which uses the dedicated cookies array.
         const singleHeaders = {};
         const cookies = [];
-        for (const [key, values] of Object.entries(headers)) {
+        for (const [key, values] of Object.entries(sentHeaders)) {
             if (key.toLowerCase() === "set-cookie")
                 cookies.push(...values);
             else
@@ -165,80 +228,105 @@ export const emitResponse = (format, statusCode, headers, body, isBase64Encoded)
         }
         return { statusCode, headers: singleHeaders, cookies, body, isBase64Encoded };
     }
-    return { statusCode, multiValueHeaders: headers, body, isBase64Encoded };
+    return { statusCode, multiValueHeaders: sentHeaders, body, isBase64Encoded };
 };
 /**
  * Convert an intermediate LambderResponse into the final Lambda response:
- * gzip negotiation (Accept-Encoding), ETag + If-None-Match 304, base64
+ * compression negotiation (Accept-Encoding), ETag + If-None-Match 304, base64
  * encoding, HEAD body stripping, and Lambda payload size guard. Emits the v1
  * (REST API) or v2 (HTTP API / Function URL) response shape.
+ *
+ * Text goes out as text and only bytes as base64: a REST API decodes base64
+ * only for its binaryMediaTypes, so a stylesheet sent as base64 would reach
+ * the browser as base64. The ETag is settled before anything is compressed, so
+ * a revalidation that ends in a 304 compresses nothing.
  */
 export const finalizeResponse = async (
 // ctx.header rather than ctx.headers: the context already carries the
-// case-insensitive lookup, and taking the raw map meant a second
-// implementation of it lived here for the two headers this reads.
+// case-insensitive lookup, and taking the raw map would need a second
+// implementation of it here.
 ctx, response, options, format = "v1") => {
     const method = (ctx?.method ?? "GET").toUpperCase();
     if (response.body === null) {
         return emitResponse(format, response.statusCode, response.headers, "", false);
     }
+    const etagEnabled = response.etag === true || (response.etag === "auto" &&
+        options.etag &&
+        response.statusCode === 200 &&
+        (method === "GET" || method === "HEAD"));
+    /** Tags the response, and answers the 304 when the client already holds this representation. */
+    const notModifiedFor = async (hashed, encoding) => {
+        if (!etagEnabled)
+            return null;
+        const hash = await bodyHashOf(hashed);
+        if (hash === null)
+            return null;
+        // One tag per representation: the compressed bytes are not the identity ones.
+        const etagValue = encoding ? `"${hash}-${encoding}"` : `"${hash}"`;
+        response.setHeader("ETag", etagValue);
+        const ifNoneMatch = ctx?.header("if-none-match");
+        if (!ifNoneMatch || !ifNoneMatch.split(",").map((s) => s.trim()).includes(etagValue))
+            return null;
+        const notModifiedHeaders = {};
+        for (const [key, values] of Object.entries(response.headers)) {
+            if (!HEADERS_DROPPED_ON_NOT_MODIFIED.includes(key.toLowerCase()))
+                notModifiedHeaders[key] = values;
+        }
+        return emitResponse(format, 304, notModifiedHeaders, "", false);
+    };
     let outBody;
     let isBase64 = false;
     if (response.isBodyBase64) {
         // Pre-encoded binary content: passes through untouched (no compression).
         outBody = String(response.body);
         isBase64 = true;
+        const notModified = await notModifiedFor(outBody, null);
+        if (notModified)
+            return notModified;
     }
     else {
-        let bodyBuffer = Buffer.isBuffer(response.body)
+        const identity = Buffer.isBuffer(response.body)
             ? response.body
             : Buffer.from(String(response.body), "utf8");
         const contentType = response.getHeader("Content-Type")?.[0];
         const alreadyEncoded = !!response.getHeader("Content-Encoding");
+        const formatCompression = options.compression[format];
         const eligibleForCompression = !alreadyEncoded && (response.compress === true ||
             (response.compress === "auto" &&
-                options.compression !== null &&
-                bodyBuffer.length >= options.compression.minBytes &&
+                formatCompression !== null &&
+                identity.length >= formatCompression.minBytes &&
                 isCompressibleContentType(contentType)));
+        // compress: true forces compression even with it off, so the
+        // settings fall back to the defaults rather than being absent.
+        const settings = formatCompression ?? DEFAULT_RESPONSE_COMPRESSION_SETTINGS;
+        let encoding = null;
         if (eligibleForCompression) {
             // Vary even when this client didn't accept an encoding, to keep caches correct.
             response.addHeader("Vary", "Accept-Encoding");
-            // compress: true forces compression even with it globally off, so
-            // the settings fall back to the defaults rather than being absent.
-            const settings = options.compression ?? DEFAULT_RESPONSE_COMPRESSION_SETTINGS;
             const acceptEncoding = ctx?.header("accept-encoding");
-            const encoding = settings.encodings.find((candidate) => acceptsEncoding(acceptEncoding, candidate));
-            if (encoding) {
-                // The same codec, quality and TEXT mode a stored record gets.
-                bodyBuffer = await compressText(bodyBuffer, encoding, settings.quality);
-                response.setHeader("Content-Encoding", encoding);
-            }
+            encoding = settings.encodings.find((candidate) => acceptsEncoding(acceptEncoding, candidate)) ?? null;
         }
-        if (Buffer.isBuffer(response.body) || response.getHeader("Content-Encoding")) {
-            outBody = bytesToBase64(bodyBuffer);
+        const notModified = await notModifiedFor(identity, encoding);
+        if (notModified)
+            return notModified;
+        if (encoding) {
+            // The same codec, quality and TEXT mode a stored record gets.
+            outBody = bytesToBase64(await compressText(identity, encoding, settings.quality));
             isBase64 = true;
+            response.setHeader("Content-Encoding", encoding);
         }
         else {
-            outBody = bodyBuffer.toString("utf8");
-        }
-    }
-    const etagEnabled = response.etag === true || (response.etag === "auto" &&
-        options.etag &&
-        response.statusCode === 200 &&
-        (method === "GET" || method === "HEAD"));
-    if (etagEnabled) {
-        const crypto = await getCrypto();
-        if (crypto) {
-            const etagValue = `"${crypto.createHash("sha256").update(outBody).digest("hex").slice(0, 32)}"`;
-            response.setHeader("ETag", etagValue);
-            const ifNoneMatch = ctx?.header("if-none-match");
-            if (ifNoneMatch && ifNoneMatch.split(",").map((s) => s.trim()).includes(etagValue)) {
-                const notModifiedHeaders = {};
-                for (const [key, values] of Object.entries(response.headers)) {
-                    if (!HEADERS_DROPPED_ON_NOT_MODIFIED.includes(key.toLowerCase()))
-                        notModifiedHeaders[key] = values;
-                }
-                return emitResponse(format, 304, notModifiedHeaders, "", false);
+            const text = alreadyEncoded
+                ? null
+                : Buffer.isBuffer(response.body)
+                    ? (isTextContentType(contentType) ? utf8TextOf(identity) : null)
+                    : String(response.body);
+            if (text !== null) {
+                outBody = text;
+            }
+            else {
+                outBody = bytesToBase64(identity);
+                isBase64 = true;
             }
         }
     }
@@ -246,10 +334,9 @@ ctx, response, options, format = "v1") => {
         return emitResponse(format, response.statusCode, response.headers, "", false);
     }
     // What Lambda weighs is bytes. A base64 body is ASCII, so its length is
-    // its byte count; a plain UTF-8 one is not, and counting its UTF-16 code
-    // units under-reported a non-ASCII response by up to 3x, which is the one
-    // way this guard could pass a body Lambda then refuses with an opaque
-    // payload-size error and no envelope.
+    // its byte count; a UTF-8 one is not, and counting UTF-16 code units would
+    // under-report a non-ASCII body by up to 3x, passing a body Lambda then
+    // refuses with an opaque payload-size error and no envelope.
     const outBytes = isBase64 ? outBody.length : Buffer.byteLength(outBody, "utf8");
     if (outBytes > options.maxResponseBytes) {
         throw new Error(`Lambder: final response body is ${outBytes} bytes which exceeds the configured ` +

package/dist/core/LambderResponseBuilder.d.ts

@@ -1,3 +1,4 @@
+import type { z } from "zod";
 import type { LambderRenderContext } from "./LambderContext.js";
 import { type LambderCookieOptions, type LambderClearCookieOptions } from "../shared/wire/LambderCookie.js";
 import type { LambderFiles } from "./LambderFiles.js";
@@ -22,9 +23,9 @@ export type LambderResponseOptions = {
  * `null` beside a config that says why (a refusal flag, an `errorMessage`, a
  * `message`). A bare `res.api(null)` compiles only when the output type
  * itself allows null, so a success payload is always the declared output,
- * which is what lets a typed caller (LambderInvokeCaller.api) promise it.
- * Untyped resolvers (`TOutput = any`) accept anything, as before. This is
- * the resolver's method type; the core's answer type is LambderApiAnswer.
+ * which lets a typed caller (LambderInvokeCaller.api) promise it. Untyped
+ * resolvers (`TOutput = any`) accept anything. This is the resolver's method
+ * type; the core's answer type is LambderApiAnswer.
  */
 export type LambderResolverApiMethod<TOutput, TResult> = {
     (payload: TOutput, config?: LambderApiResponseConfig, options?: LambderResponseOptions): TResult;
@@ -43,10 +44,13 @@ export default class LambderResponseBuilder<TResponse = any> {
     protected files: LambderFiles | null;
     protected apiVersion: string | null;
     protected ctx?: LambderRenderContext;
-    constructor({ files, apiVersion, ctx }: {
+    /** The output schema of the API this builder answers, which every success payload is parsed through; null outside an API handler. */
+    protected apiOutput: z.ZodType | null;
+    constructor({ files, apiVersion, ctx, apiOutput }: {
         files?: LambderFiles | null;
         apiVersion?: string | null;
         ctx?: LambderRenderContext;
+        apiOutput?: z.ZodType;
     });
     private buildResponse;
     /** The instance's file reader, which res.file and res.templateFile need. */
@@ -76,6 +80,19 @@ export default class LambderResponseBuilder<TResponse = any> {
     html(data: string | LambderSafeHtml, options?: LambderResponseOptions): LambderResponse;
     status(statusCode: LambderHttpStatusCode, body?: string, options?: LambderResponseOptions): LambderResponse;
     status404(data: string, options?: LambderResponseOptions): LambderResponse;
+    /**
+     * A redirect to `url`, which may be a path or a whole URL. A path stays on
+     * this origin: a leading run of slashes and backslashes collapses to one
+     * slash, since `//evil.example` is a protocol-relative URL and a browser
+     * reads `/\evil.example` as the same thing, so a path built from a
+     * decoded ctx.path cannot send the visitor to another host. Another host
+     * is named with its scheme. What a URL may not carry as it is (control
+     * characters, a space, a backslash, anything outside ASCII) is
+     * percent-encoded for every caller: a browser drops a TAB or line break
+     * inside a Location, so `/<TAB>/evil.example` would otherwise be that
+     * host, and a line break would end the header. `%` is left alone, so an
+     * encoded URL stays as it was written.
+     */
     redirect(url: string, statusCode?: LambderHttpStatusCode, options?: LambderResponseOptions): LambderResponse;
     versionExpired(options?: LambderResponseOptions): LambderResponse;
     fileBase64(fileBase64: string, mimeType: string, options?: LambderResponseOptions): LambderResponse;
@@ -94,6 +111,34 @@ export default class LambderResponseBuilder<TResponse = any> {
     }): Promise<LambderResponse>;
     api(payload: TResponse, config?: LambderApiResponseConfig, options?: LambderResponseOptions): LambderResponse;
     api(payload: null, config: LambderApiNullAnswerConfig, options?: LambderResponseOptions): LambderResponse;
+    /**
+     * A payload as the API's output schema declares it. The type system
+     * accepts a value that carries more than the schema (a row read straight
+     * from a table is assignable to a narrower object type), and without this
+     * the extra fields, a password hash included, would reach the client.
+     * zod strips what the schema does not declare, fills its defaults and
+     * applies its transforms, so the wire and the idempotency store only see
+     * the declared shape. A refusal's payload beside an errorMessage or a
+     * flag is parsed the same way; only null passes as it is. Only an API
+     * handler's own resolver holds the schema: a hook, a validation handler
+     * or an error handler answers in shapes of its own, a cached answer in
+     * its wire form, and is sent as given.
+     *
+     * The payload is the schema's input form (what a handler writes before
+     * the transforms), so a transform runs exactly once. A payload the schema
+     * rejects is a handler breaking its contract, answered as a crash rather
+     * than sent (LambderApiOutputValidationError, which an idempotency key
+     * records as its answer, since the handler has already run).
+     *
+     * The parse is synchronous, so an output schema cannot be async: zod
+     * throws from a synchronous parse that meets an async refinement or
+     * transform, and a transform may throw of its own accord. Either throw
+     * becomes the same LambderApiOutputValidationError, carrying what was
+     * thrown as its cause. Left to escape as it is, it would read as the
+     * handler crashing before its answer: the idempotency engine would
+     * release the key's claim and every retry would run the operation again.
+     */
+    private declaredPayload;
     /** Same as api() but forces compression of the response body. */
     apiBinary(payload: TResponse, config?: LambderApiResponseConfig, options?: LambderResponseOptions): LambderResponse;
     apiBinary(payload: null, config: LambderApiNullAnswerConfig, options?: LambderResponseOptions): LambderResponse;

package/dist/core/LambderResponseBuilder.js

@@ -1,14 +1,18 @@
 import { serializeCookie, serializeClearCookie } from "../shared/wire/LambderCookie.js";
 import { LambderResponse } from "./LambderResponse.js";
 import { buildApiEnvelope } from "../api/LambderApiEnvelope.js";
+import { LambderApiOutputValidationError } from "../api/LambderApiOutputValidationError.js";
 export default class LambderResponseBuilder {
     files;
     apiVersion;
     ctx;
-    constructor({ files, apiVersion, ctx }) {
+    /** The output schema of the API this builder answers, which every success payload is parsed through; null outside an API handler. */
+    apiOutput;
+    constructor({ files, apiVersion, ctx, apiOutput }) {
         this.files = files ?? null;
         this.apiVersion = apiVersion ?? null;
         this.ctx = ctx;
+        this.apiOutput = apiOutput ?? null;
     }
     ;
     buildResponse(statusCode, contentType, body, options, defaults) {
@@ -109,9 +113,24 @@ export default class LambderResponseBuilder {
         return this.buildResponse(404, "text/html; charset=utf-8", data, options);
     }
     ;
+    /**
+     * A redirect to `url`, which may be a path or a whole URL. A path stays on
+     * this origin: a leading run of slashes and backslashes collapses to one
+     * slash, since `//evil.example` is a protocol-relative URL and a browser
+     * reads `/\evil.example` as the same thing, so a path built from a
+     * decoded ctx.path cannot send the visitor to another host. Another host
+     * is named with its scheme. What a URL may not carry as it is (control
+     * characters, a space, a backslash, anything outside ASCII) is
+     * percent-encoded for every caller: a browser drops a TAB or line break
+     * inside a Location, so `/<TAB>/evil.example` would otherwise be that
+     * host, and a line break would end the header. `%` is left alone, so an
+     * encoded URL stays as it was written.
+     */
     redirect(url, statusCode = 302, options) {
         const response = this.buildResponse(statusCode, null, null, options);
-        response.setHeader("Location", url);
+        const target = /^[a-z][a-z0-9+.-]*:/iu.test(url) ? url : url.replace(/^[/\\]+/u, "/");
+        // Everything outside printable ASCII (`!` to `~`), and the backslash.
+        response.setHeader("Location", target.replace(/[^!-~]|\\/gu, (character) => encodeURIComponent(character)));
         return response;
     }
     ;
@@ -162,10 +181,52 @@ export default class LambderResponseBuilder {
         // The envelope is the core's (one writer for both the server and the
         // mock runtime); the logList channel is what this request accumulated
         // unless the config names its own.
-        const envelope = buildApiEnvelope(this.apiVersion, payload, { ...config, logList: config.logList || this.ctx?.logList });
+        const envelope = buildApiEnvelope(this.apiVersion, this.declaredPayload(payload), { ...config, logList: config.logList || this.ctx?.logList });
         return this.json(envelope, options);
     }
     ;
+    /**
+     * A payload as the API's output schema declares it. The type system
+     * accepts a value that carries more than the schema (a row read straight
+     * from a table is assignable to a narrower object type), and without this
+     * the extra fields, a password hash included, would reach the client.
+     * zod strips what the schema does not declare, fills its defaults and
+     * applies its transforms, so the wire and the idempotency store only see
+     * the declared shape. A refusal's payload beside an errorMessage or a
+     * flag is parsed the same way; only null passes as it is. Only an API
+     * handler's own resolver holds the schema: a hook, a validation handler
+     * or an error handler answers in shapes of its own, a cached answer in
+     * its wire form, and is sent as given.
+     *
+     * The payload is the schema's input form (what a handler writes before
+     * the transforms), so a transform runs exactly once. A payload the schema
+     * rejects is a handler breaking its contract, answered as a crash rather
+     * than sent (LambderApiOutputValidationError, which an idempotency key
+     * records as its answer, since the handler has already run).
+     *
+     * The parse is synchronous, so an output schema cannot be async: zod
+     * throws from a synchronous parse that meets an async refinement or
+     * transform, and a transform may throw of its own accord. Either throw
+     * becomes the same LambderApiOutputValidationError, carrying what was
+     * thrown as its cause. Left to escape as it is, it would read as the
+     * handler crashing before its answer: the idempotency engine would
+     * release the key's claim and every retry would run the operation again.
+     */
+    declaredPayload(payload) {
+        if (!this.apiOutput || payload === null)
+            return payload;
+        const apiName = this.ctx?.apiName ?? "?";
+        let parsed;
+        try {
+            parsed = this.apiOutput.safeParse(payload);
+        }
+        catch (thrown) {
+            throw new LambderApiOutputValidationError(apiName, { thrown });
+        }
+        if (parsed.success)
+            return parsed.data;
+        throw new LambderApiOutputValidationError(apiName, { zodError: parsed.error });
+    }
     apiBinary(payload, config = {}, options) {
         return this.api(payload, config, { ...options, compress: true });
     }

package/dist/core/LambderRouting.d.ts

@@ -24,9 +24,8 @@ export type CompiledMatcher = (ctx: LambderRenderContext) => false | Record<stri
  * unless the list names HEAD itself: a HEAD is a GET whose body finalization
  * strips, so an app that narrowed a slot to ["GET"] did not mean to 404 it.
  *
- * The three places that gate on a method (a route matcher's `method`,
- * servePublicFiles and serveIndexHtml) share this one rule, so neighbouring
- * slots cannot disagree about what a method means.
+ * A route matcher's `method`, servePublicFiles and serveIndexHtml all use
+ * this rule, so neighbouring slots cannot disagree about what a method means.
  */
 export declare const allowsRequestMethod: (methods: ReadonlySet<string>, requestMethod: string) => boolean;
 /** Compile a route condition once at registration time. */

package/dist/core/LambderRouting.js

@@ -1,7 +1,16 @@
 import { match as pathToRegexpMatch } from "path-to-regexp";
+import { decodePathParam } from "./LambderRequestPath.js";
 const compilePathMatcher = (path) => {
     if (typeof path === "string") {
-        const matchFn = pathToRegexpMatch(path, { decode: decodeURIComponent });
+        // ctx.path is already decoded, so decoding a param again would read a
+        // literal "%41" as "A". decodePathParam only turns the two escapes
+        // ctx.path keeps back into "/" and "%". The slash is the only delimiter:
+        // a decoded path carries "#" and "?" as text ("/tags/C%23" is the tag
+        // "C#"), and path-to-regexp's default would end a param at them.
+        // Case-sensitive, as API Gateway routes and CloudFront behaviors are:
+        // matched without case, `/ADMIN/users` would miss an authorizer on
+        // `/admin/*` in front of the function and still reach "/admin/:x".
+        const matchFn = pathToRegexpMatch(path, { decode: decodePathParam, delimiter: "/", sensitive: true });
         return (requestPath) => {
             const result = matchFn(requestPath);
             if (!result)
@@ -13,16 +22,23 @@ const compilePathMatcher = (path) => {
             return params;
         };
     }
+    // A RegExp matches ctx.path as written, its kept %2F and %25 included;
+    // what it captures is handed over turned back, as a string route's params are.
     return (requestPath) => {
         const matched = requestPath.match(path);
         if (!matched)
             return false;
-        if (matched.groups)
-            return { ...matched.groups };
         const params = {};
+        if (matched.groups) {
+            for (const [key, value] of Object.entries(matched.groups)) {
+                if (value !== undefined)
+                    params[key] = decodePathParam(value);
+            }
+            return params;
+        }
         matched.forEach((value, index) => {
             if (value !== undefined)
-                params[String(index)] = value;
+                params[String(index)] = decodePathParam(value);
         });
         return params;
     };
@@ -32,9 +48,8 @@ const compilePathMatcher = (path) => {
  * unless the list names HEAD itself: a HEAD is a GET whose body finalization
  * strips, so an app that narrowed a slot to ["GET"] did not mean to 404 it.
  *
- * The three places that gate on a method (a route matcher's `method`,
- * servePublicFiles and serveIndexHtml) share this one rule, so neighbouring
- * slots cannot disagree about what a method means.
+ * A route matcher's `method`, servePublicFiles and serveIndexHtml all use
+ * this rule, so neighbouring slots cannot disagree about what a method means.
  */
 export const allowsRequestMethod = (methods, requestMethod) => {
     const method = requestMethod.toUpperCase();