lambder 7.2.5 → 8.0.2

package/dist/core/LambderIndexHtml.js

@@ -1,5 +1,6 @@
 import { isV2HttpEvent } from "./LambderContext.js";
 import { allowsRequestMethod } from "./LambderRouting.js";
+import { encodePathForLocation } from "./LambderRequestPath.js";
 /**
  * Serves the app shell for page requests that nothing else handled,
  * registered via lambder.serveIndexHtml(). Runs after servePublicFiles in the
@@ -26,7 +27,7 @@ export class LambderIndexHtmlHandler {
         if (options.redirectTrailingSlash && ctx.path.length > 1 && ctx.path.endsWith("/")) {
             const target = sameOriginRedirectTarget(ctx.path);
             if (target !== null)
-                return resolver.redirect(target + buildQueryString(ctx), 301);
+                return resolver.redirect(encodePathForLocation(target) + buildQueryString(ctx), 301);
         }
         const response = handler
             ? await handler(ctx, resolver)
@@ -42,13 +43,14 @@ export class LambderIndexHtmlHandler {
  * cannot leave this origin, or null when no such form exists.
  *
  * `Location: //evil.example` is a protocol-relative URL, so a browser
- * navigates to that host; every browser normalizes backslashes into slashes
- * first, so `/\evil.example` is the same thing. This header is built from the
- * request path, which the caller writes, so redirectTrailingSlash was an open
- * redirect for anyone who asked for `GET //evil.example/`. The leading run of
- * slashes and backslashes collapses to the single slash a path may have, and
- * the result is then checked rather than assumed: the check is what the
- * header's safety rests on, and it costs one comparison.
+ * navigates to that host, and browsers normalize backslashes into slashes, so
+ * `/\evil.example` is the same thing. The header is built from the request
+ * path, which the caller writes, so without this `GET //evil.example/` would
+ * make redirectTrailingSlash an open redirect. The leading run of slashes and
+ * backslashes collapses to one slash, and the result is then checked rather
+ * than assumed, since the header's safety rests on that check. The caller
+ * then percent-encodes it (encodePathForLocation), so a TAB or line break,
+ * which a browser drops, cannot make a second slash out of it.
  */
 const sameOriginRedirectTarget = (path) => {
     const target = path.replace(/^[/\\]+/, "/").replace(/[/\\]+$/, "") || "/";
@@ -59,9 +61,8 @@ const sameOriginRedirectTarget = (path) => {
 /**
  * Rebuild the query string from the API Gateway event for redirects.
  *
- * From the raw event rather than from ctx.get, which has flattened repeated
- * keys to one value each and lost the order they arrived in; a redirect has
- * to hand back the query it was given.
+ * From the raw event rather than ctx.get, which keeps one value per key and
+ * loses their order; a redirect has to hand back the query it was given.
  */
 const buildQueryString = (ctx) => {
     if (isV2HttpEvent(ctx.event)) {

package/dist/core/LambderPolicyBuilders.d.ts

@@ -2,11 +2,10 @@
  * The server's policy builders: the generic builders from `api/`, bound to
  * the render contexts a Lambda handler runs on.
  *
- * They live in `core/` rather than beside the engines because binding them is
- * the one thing about a guard or a rate-limit key that is the SERVER's, and
- * having them in `api/` was the last reason that layer imported from `core/`
- * at all. The mock runtime binds the same builders to its own call contexts,
- * in its own layer, which is why the builders themselves are generic.
+ * They live in `core/` rather than beside the engines because the binding is
+ * the only server-specific part of a guard or a rate-limit key, and keeping it
+ * here means `api/` never imports from `core/`. The mock runtime binds the
+ * same generic builders to its own call contexts in its own layer.
  */
 import type { LambderRenderContext, LambderSessionRenderContext } from "./LambderContext.js";
 import { type LambderGuardBuilder } from "../api/LambderApiGuards.js";
@@ -15,3 +14,16 @@ import { type LambderRateLimitKeyBuilder } from "../api/LambderApiRateLimits.js"
 export declare const lambderGuard: LambderGuardBuilder<LambderRenderContext, LambderSessionRenderContext<any, any>>;
 /** Builder for the server's rate-limit keys: the handler sees the render context. */
 export declare const lambderRateLimitKey: LambderRateLimitKeyBuilder<LambderRenderContext>;
+/**
+ * The same two builders bound to one app's session data, which is what
+ * initLambder<SessionData>() hands out beside create(): a guard's
+ * `ctx.session.data` and `ctx.sessionController` are SessionData where the standalone
+ * lambderGuard() leaves them `any`. The server's counterpart of the mock's
+ * `guard` and `rateLimitKey`.
+ */
+export declare const policyBuildersFor: <TSessionData>() => {
+    /** Builds a guard whose handler sees this app's session type. */
+    guard: LambderGuardBuilder<LambderRenderContext<any, Record<string, string>, {}, TSessionData>, LambderSessionRenderContext<any, TSessionData>>;
+    /** Builds a rate-limit key whose handler sees this app's session type; the counterpart of `guard`. */
+    rateLimitKey: LambderRateLimitKeyBuilder<LambderRenderContext<any, Record<string, string>, {}, TSessionData>>;
+};

package/dist/core/LambderPolicyBuilders.js

@@ -2,11 +2,10 @@
  * The server's policy builders: the generic builders from `api/`, bound to
  * the render contexts a Lambda handler runs on.
  *
- * They live in `core/` rather than beside the engines because binding them is
- * the one thing about a guard or a rate-limit key that is the SERVER's, and
- * having them in `api/` was the last reason that layer imported from `core/`
- * at all. The mock runtime binds the same builders to its own call contexts,
- * in its own layer, which is why the builders themselves are generic.
+ * They live in `core/` rather than beside the engines because the binding is
+ * the only server-specific part of a guard or a rate-limit key, and keeping it
+ * here means `api/` never imports from `core/`. The mock runtime binds the
+ * same generic builders to its own call contexts in its own layer.
  */
 import { lambderGuardBuilder } from "../api/LambderApiGuards.js";
 import { lambderRateLimitKeyBuilder } from "../api/LambderApiRateLimits.js";
@@ -14,3 +13,16 @@ import { lambderRateLimitKeyBuilder } from "../api/LambderApiRateLimits.js";
 export const lambderGuard = lambderGuardBuilder();
 /** Builder for the server's rate-limit keys: the handler sees the render context. */
 export const lambderRateLimitKey = lambderRateLimitKeyBuilder();
+/**
+ * The same two builders bound to one app's session data, which is what
+ * initLambder<SessionData>() hands out beside create(): a guard's
+ * `ctx.session.data` and `ctx.sessionController` are SessionData where the standalone
+ * lambderGuard() leaves them `any`. The server's counterpart of the mock's
+ * `guard` and `rateLimitKey`.
+ */
+export const policyBuildersFor = () => ({
+    /** Builds a guard whose handler sees this app's session type. */
+    guard: lambderGuardBuilder(),
+    /** Builds a rate-limit key whose handler sees this app's session type; the counterpart of `guard`. */
+    rateLimitKey: lambderRateLimitKeyBuilder(),
+});

package/dist/core/LambderPublicFiles.d.ts

@@ -7,15 +7,21 @@ export type LambderPublicFilesOptions = {
     methods?: string[];
     /**
      * Map the request to a file path (app-owned logic, e.g. per-tenant
-     * roots: (ctx) => `${brand(ctx.host)}${ctx.path}`). Return
-     * null/undefined to skip. Default: (ctx) => ctx.path.
+     * roots: (ctx, filePath) => `${brand(ctx.host)}${filePath}`). `filePath`
+     * is the file ctx.path names, its kept `%25` read as `%`; a path with an
+     * encoded slash inside a segment names no file and never reaches the
+     * mapper. Return null/undefined to skip. Default: the file path as it is.
      */
-    path?: (ctx: LambderRenderContext) => string | null | undefined;
+    path?: (ctx: LambderRenderContext, filePath: string) => string | null | undefined;
     /** Cache-Control for served files; the function receives the relative file path. Default: "public, max-age=3600". */
     cacheControl?: string | ((ctx: LambderRenderContext, relativePath: string) => string);
-    /** Filenames matching this get immutableCacheControl. Default: content-hash heuristic. Set false to disable. */
+    /** Relative paths matching this get immutableCacheControl. Default: content-hashed names in a bundler's output folder (assets/, static/, _next/static/). Set false to disable. */
     immutablePattern?: RegExp | false;
-    /** Default: "public, max-age=31536000, immutable". */
+    /**
+     * Default: "public, max-age=31536000, immutable". Like any Cache-Control,
+     * it goes out private, without `immutable`, on an answer that also sets a
+     * cookie (a hook's guest session, a slid session cookie): see emitResponse.
+     */
     immutableCacheControl?: string;
     /**
      * Compression per file: "auto" (default: compressible mime + size threshold),

package/dist/core/LambderPublicFiles.js

@@ -1,8 +1,33 @@
 import { LambderResponse } from "./LambderResponse.js";
 import { allowsRequestMethod } from "./LambderRouting.js";
-// Content-hashed build outputs (Vite/webpack/Rollup): a [-.] separated run of
-// 8+ hash chars containing at least one digit, before the extension.
-const DEFAULT_IMMUTABLE_PATTERN = /[-.](?=[A-Za-z0-9_-]*\d)[A-Za-z0-9_-]{8,}\.[A-Za-z0-9]+$/;
+import { filePathOf } from "./LambderRequestPath.js";
+/*
+ * Build outputs whose names carry a content hash, so a changed file gets a
+ * new name and the old one may be cached for good. Only what a bundler wrote:
+ *   - everything under Next.js's _next/static/;
+ *   - under assets/ or static/ (Vite, Rollup, esbuild, webpack and CRA, a
+ *     Django manifest), a name ending in its hash, then an optional `.chunk`
+ *     and the extension. The hash is either exactly 8 base64url characters
+ *     after a hyphen (Vite, Rollup, esbuild), or 8 or more letters and
+ *     digits with both kinds among them (webpack's contenthash, after a dot
+ *     or a hyphen).
+ * The 8-character form has to look random, since a hand-named file's last
+ * word is often 8 characters too: a capital, a lowercase letter and a digit,
+ * or, with no digit, at least three capitals and a lowercase letter. A word
+ * in PascalCase (Inter-SemiBold.woff2, icon-Settings.svg) has fewer capitals
+ * than that, and lowercase words around a version (og-image-v2-final.png)
+ * have none. A hyphen may sit inside the 8, as Rollup's hashes put one
+ * there. The lookaheads cannot read past the 8, since a dot follows them.
+ * About one real hash in twenty fails the test (one without a digit and
+ * with fewer than three capitals) and is served with the ordinary
+ * Cache-Control: a revalidation, never a stale file.
+ * A hand-named file (android-chrome-192x192.png, team-photo-2023.jpg,
+ * privacy-policy-v2.html) keeps the ordinary Cache-Control: marked immutable,
+ * a replaced copy would never reach a browser that already had it.
+ */
+const EXACT_BUNDLER_HASH = "-(?=[\\w-]{0,7}[a-z])(?:(?=[\\w-]{0,7}[A-Z])(?=[\\w-]{0,7}[0-9])|(?=(?:[a-z0-9_-]*[A-Z]){3}))[\\w-]{8}";
+const LONG_BUNDLER_HASH = "[-.](?=\\w*[A-Za-z])(?=\\w*\\d)\\w{8,}";
+const DEFAULT_IMMUTABLE_PATTERN = new RegExp(`(?:^|/)_next/static/|(?:^|/)(?:assets|static)/(?:[^/]+/)*[^/]*(?:${EXACT_BUNDLER_HASH}|${LONG_BUNDLER_HASH})(?:\\.chunk)?\\.[A-Za-z0-9]+$`);
 const DEFAULT_IMMUTABLE_CACHE_CONTROL = "public, max-age=31536000, immutable";
 const DEFAULT_CACHE_CONTROL = "public, max-age=3600";
 /**
@@ -26,7 +51,10 @@ export class LambderPublicFilesHandler {
     async handle(ctx) {
         if (!allowsRequestMethod(this.methods, ctx.method))
             return null;
-        const mappedPath = this.options.path ? this.options.path(ctx) : ctx.path;
+        const filePath = filePathOf(ctx.path);
+        if (filePath === null)
+            return null;
+        const mappedPath = this.options.path ? this.options.path(ctx, filePath) : filePath;
         if (!mappedPath)
             return null;
         const file = await this.files.read(mappedPath);

package/dist/core/LambderRequestPath.d.ts

@@ -0,0 +1,43 @@
+/**
+ * A request path between the spelling a gateway delivers and the one routes,
+ * files and redirects work with.
+ *
+ * The gateways disagree: a REST API and a Function URL hand the path over
+ * percent-encoded, an HTTP API hands it over decoded. Routes and file
+ * lookups need one form, or `addRoute("/hakkımızda")` and a file named
+ * `team photo.jpg` are found on one gateway and not on another.
+ *
+ * That form, `ctx.path`, is the path decoded with two escapes kept: a slash
+ * inside a segment stays `%2F`, so it cannot become a separator, and a
+ * percent sign stays `%25`, so no decoded text can pass for an escape. Every
+ * path is decoded exactly once, whoever sent it: `/%2561dmin` names the text
+ * `%61dmin` (written `/%2561dmin`), and never `/admin`.
+ */
+/**
+ * The path routes and files see (`ctx.path`), from the path the gateway
+ * delivered. `alreadyDecoded` for an HTTP API, which decodes the path before
+ * the function sees it (its encoded slashes into separators, too): decoded
+ * again, a `/%2561dmin` the gateway handed over as `/%61dmin` would route to
+ * `/admin`, past an authorizer, a WAF rule or a CloudFront behavior in front
+ * of the function that checked the path once. The segment checks that guard
+ * file reads (no `..`, no empty or backslashed segment) run on this form, so
+ * an encoded `%2e%2e` is refused as the `..` it is.
+ */
+export declare const decodeRequestPath: (rawPath: string, alreadyDecoded: boolean) => string;
+/** A path parameter's value: its text from ctx.path, with the kept `%2F` and `%25` turned back into `/` and `%`. */
+export declare const decodePathParam: (value: string) => string;
+/**
+ * The file a path names, for servePublicFiles: the kept `%25` turned back
+ * into `%`, or null for a path with a slash inside a segment, which no file
+ * name holds.
+ */
+export declare const filePathOf: (path: string) => string | null;
+/**
+ * A decoded path as a Location header: every character a URL path may not
+ * carry is percent-encoded, `%` itself left alone so the kept `%2F` and `%25`
+ * stay the escapes they are. A browser drops a TAB or line break inside a
+ * Location before resolving it, so `/<TAB>/evil.example` sent as it is would
+ * reach the browser as `//evil.example`, another host; encoded, it stays a
+ * path on this one.
+ */
+export declare const encodePathForLocation: (path: string) => string;

package/dist/core/LambderRequestPath.js

@@ -0,0 +1,63 @@
+/**
+ * A request path between the spelling a gateway delivers and the one routes,
+ * files and redirects work with.
+ *
+ * The gateways disagree: a REST API and a Function URL hand the path over
+ * percent-encoded, an HTTP API hands it over decoded. Routes and file
+ * lookups need one form, or `addRoute("/hakkımızda")` and a file named
+ * `team photo.jpg` are found on one gateway and not on another.
+ *
+ * That form, `ctx.path`, is the path decoded with two escapes kept: a slash
+ * inside a segment stays `%2F`, so it cannot become a separator, and a
+ * percent sign stays `%25`, so no decoded text can pass for an escape. Every
+ * path is decoded exactly once, whoever sent it: `/%2561dmin` names the text
+ * `%61dmin` (written `/%2561dmin`), and never `/admin`.
+ */
+/** An encoded slash: a slash that belongs to a segment's text rather than separating two segments. */
+const ENCODED_SLASH = /%2F/gi;
+/** Decoded text as ctx.path writes it: every percent sign kept as `%25`. */
+const keepPercentSigns = (text) => text.replaceAll("%", "%25");
+/**
+ * One segment decoded, its encoded slashes kept as `%2F` and its percent
+ * signs as `%25`. A segment whose escapes do not decode (a stray `%`, a byte
+ * sequence that is not UTF-8) is read as the text it arrived as: it names
+ * nothing that decoding would have named.
+ */
+const decodeSegment = (segment) => {
+    if (!segment.includes("%"))
+        return segment;
+    try {
+        return segment.split(ENCODED_SLASH).map((piece) => keepPercentSigns(decodeURIComponent(piece))).join("%2F");
+    }
+    catch {
+        return keepPercentSigns(segment);
+    }
+};
+/**
+ * The path routes and files see (`ctx.path`), from the path the gateway
+ * delivered. `alreadyDecoded` for an HTTP API, which decodes the path before
+ * the function sees it (its encoded slashes into separators, too): decoded
+ * again, a `/%2561dmin` the gateway handed over as `/%61dmin` would route to
+ * `/admin`, past an authorizer, a WAF rule or a CloudFront behavior in front
+ * of the function that checked the path once. The segment checks that guard
+ * file reads (no `..`, no empty or backslashed segment) run on this form, so
+ * an encoded `%2e%2e` is refused as the `..` it is.
+ */
+export const decodeRequestPath = (rawPath, alreadyDecoded) => rawPath.split("/").map(alreadyDecoded ? keepPercentSigns : decodeSegment).join("/");
+/** A path parameter's value: its text from ctx.path, with the kept `%2F` and `%25` turned back into `/` and `%`. */
+export const decodePathParam = (value) => value.replace(/%2F|%25/gi, (escape) => (escape === "%25" ? "%" : "/"));
+/**
+ * The file a path names, for servePublicFiles: the kept `%25` turned back
+ * into `%`, or null for a path with a slash inside a segment, which no file
+ * name holds.
+ */
+export const filePathOf = (path) => /%2F/i.test(path) ? null : path.replaceAll("%25", "%");
+/**
+ * A decoded path as a Location header: every character a URL path may not
+ * carry is percent-encoded, `%` itself left alone so the kept `%2F` and `%25`
+ * stay the escapes they are. A browser drops a TAB or line break inside a
+ * Location before resolving it, so `/<TAB>/evil.example` sent as it is would
+ * reach the browser as `//evil.example`, another host; encoded, it stays a
+ * path on this one.
+ */
+export const encodePathForLocation = (path) => path.replace(/[^A-Za-z0-9\-._~!$&'()*+,;=:@/%]/gu, (character) => encodeURIComponent(character));

package/dist/core/LambderResponse.d.ts

@@ -50,6 +50,14 @@ export declare class LambderResponse {
     compress: boolean | "auto";
     etag: boolean | "auto";
     constructor(init: LambderResponseInit);
+    /**
+     * 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(): LambderResponse;
     getHeader(key: string): string[] | undefined;
     setHeader(key: string, value: string | string[]): this;
     addHeader(key: string, value: string): this;
@@ -74,8 +82,14 @@ export type LambderResponseCompressionSettings = LambderCompressionSettingsBase
 /** The `compression` option at creation: `true` for the defaults, `false` for off, or overrides. */
 export type LambderResponseCompressionOption = LambderCompressionOption<LambderResponseCompressionSettings>;
 export type LambderFinalizeOptions = {
-    /** Resolved settings, or null when compression is off: the same `Settings | null` contract the stores hold. */
-    compression: LambderResponseCompressionSettings | null;
+    /**
+     * Resolved settings per event format, or null where compression is off:
+     * the same `Settings | null` contract the stores hold. Per format because
+     * a REST API (v1) hands a compressed body on to the browser only when its
+     * binaryMediaTypes match, which in practice means `*\/*`: compressing
+     * there by default would send most answers as base64 text.
+     */
+    compression: Record<LambderHttpEventFormat, LambderResponseCompressionSettings | null>;
     etag: boolean;
     /** Guard against Lambda's ~6MB response cap with a clear error. */
     maxResponseBytes: number;
@@ -93,15 +107,22 @@ export declare const DEFAULT_FINALIZE_OPTIONS: LambderFinalizeOptions;
 /**
  * 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 declare const emitResponse: (format: LambderHttpEventFormat, statusCode: number, headers: Record<string, string[]>, body: string, isBase64Encoded: boolean) => LambderHttpResponse;
 /**
  * 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 declare const finalizeResponse: (ctx: Pick<LambderRenderContext, "method" | "header"> | null, response: LambderResponse, options: LambderFinalizeOptions, format?: LambderHttpEventFormat) => Promise<LambderHttpResponse>;
 export {};