lambder 4.6.1 → 4.7.1

package/Readme.md

@@ -2,6 +2,14 @@
 
 Lambder is a highly opinionated dynamic serverless framework designed to facilitate the management and implementation of routes and APIs within AWS Lambda functions, specifically tailored for TypeScript projects. It provides a streamlined approach to handling HTTP requests, managing sessions, and defining API routes, making serverless application development more intuitive and structured.
 
+**New in 4.7:**
+
+- **Compressed request payloads**: `requestCompression` on `LambderCaller` gzips the payload of any call whose JSON reaches a threshold (`true` is `{ minBytes: 4096 }`), sending it as `payloadGz` beside its byte length instead of `payload` whenever that is actually smaller; the server restores it before rate-limit key slices, guards and input validation, so no call site, handler or schema changes. Chiefly a way to fit a large payload under Lambda's ~6MB invoke cap, which applies to the compressed bytes. The envelope stays `application/json` with its routing fields in plain text, so gateways, CDNs and mocks are unaffected. `maxRequestPayloadBytes` (default 20MB) bounds what a body may expand to.
+- **One compression codec**: `shared/LambderCompressionCodec.ts` is now the only place Lambder compresses or decompresses bytes. Its `restoreBoundedText(bytes, declaredBytes, encoding)` carries the guarantee every compressed value in Lambder depends on, at rest and on the wire: the declared UTF-8 byte length bounds the decompression AND must match the result exactly, so a truncated, tampered or endlessly-expanding input fails instead of decoding to something merely plausible. Compression is split across three modules by what each one needs: the codec (zlib), the option and its resolver (pure, so the browser entry can resolve the caller's option), and the request payload format (the browser's CompressionStream). `stores/LambderDdbCompression.ts` is retired into them.
+- **One compression option, now everywhere**: the HTTP response option and the new request option resolve through the same `resolveCompressionOption` the DynamoDB stores and sessions use, and every site's option is the one generic `LambderCompressionOption<Settings>`. Same vocabulary at every site (`true` for that site's defaults, `false` for off, an object to override, `minBytes` as the threshold, `quality` as the Brotli quality, `encodings` as the negotiation order), same `Settings | null` resolved shape, and the same startup validation: `compression: { quality: 99 }` or `{ encodings: [] }` on a response is now a construction error instead of being silently ignored, and a field set to `undefined` keeps its default.
+- **Brotli responses**: response compression now negotiates `br` before `gzip`, smaller at comparable speed (15-25% on markup and prose, substantially more on the repetitive record lists API responses tend to be), which is bandwidth saved and headroom gained against the ~6MB response cap. `compression: { encodings: ["gzip"] }` opts out, `quality` (default 5) tunes it.
+- **Mandatory authorization on session APIs**: `requireSessionApiGuards: true` at creation makes `guards` a required field of every `addSessionApi`, at the type level (a missing declaration is a compile error at the registration site) and at registration (a plain-JS caller throws). An API the session alone authorizes declares a named no-op session guard, so every opt-out is explicit and one grep lists them all. The class of defect this closes is "the guard existed and the endpoint did not use it", which review discipline does not catch as a surface grows.
+
 **New in 4.6:**
 
 - **Cookies as a first-class concern**: `res.setCookie(name, value, options)` and `res.clearCookie(name, options)` serialize Set-Cookie headers through the `cookie` package (defaults Path=/, SameSite=Lax, Secure; a function-form `domain` resolves against the request hostname, the same option the session takes), replacing hand-built header strings; `serializeCookie`/`serializeClearCookie` are exported for code holding a response. `ctx.cookieList` keeps every value a cookie name arrived with beside the first-wins `ctx.cookie`.
@@ -74,6 +82,24 @@ npm install lambder zod
 yarn add lambder zod
 ```
 
+`zod` and the AWS SDK clients are optional peer dependencies, so installing
+lambder never drags them into your tree. Add whatever the code you actually
+import needs:
+
+| What you import | What to install alongside |
+|---|---|
+| `lambder/client` (browser, shared isomorphic code) | `zod` |
+| `lambder` on AWS Lambda (`nodejs18.x` and later) | `zod`. The runtime already provides the AWS SDK v3, so mark the SDK packages as dev dependencies and keep them out of the deployment package |
+| `lambder` anywhere else (a long-running server, a container, local tests) | `zod`, `@aws-sdk/client-dynamodb`, `@aws-sdk/lib-dynamodb` |
+| `LambderS3FileSource` | `@aws-sdk/client-s3`, loaded on first read |
+| `lambder/testing` | `msw` |
+
+The SDK and its `@smithy` tree are roughly 21MB installed, which is why they are
+peers rather than dependencies: a frontend importing only `lambder/client` has
+no use for any of it, and a Lambda deployment package should not ship a second
+copy of what the runtime already loads. The runtime pins its own SDK version,
+so if you need a specific one, install it and bundle it yourself.
+
 ## Package Entry Points
 
 The package ships three entry points; pick by where the code runs:
@@ -385,7 +411,7 @@ Semantics:
 
 #### Session data at rest (`compression`)
 
-`session.data` is stored Brotli-compressed by default: the record carries the data's JSON as Brotli bytes in `dataBr` beside its byte length in `dataBytes`, in place of a plain `data` attribute. It is the scheme `LambderDdbCache` and `LambderDdbIdempotency` already use, from one shared implementation, and the byte length both bounds the decompression and verifies it, so a truncated record fails to decode rather than decoding to something else. Session data that caches roles, permissions or product lists typically shrinks 2-3x, which keeps a growing session within one DynamoDB read unit (4KB for the consistent reads sessions use) and one write unit (1KB) for longer.
+`session.data` is stored Brotli-compressed by default: the record carries the data's JSON as Brotli bytes in `dataBr` beside its byte length in `dataBytes`, in place of a plain `data` attribute. It is the scheme `LambderDdbCache` and `LambderDdbIdempotency` already use, from the one shared codec that also restores compressed request payloads, and the byte length both bounds the decompression and verifies it, so a truncated record fails to decode rather than decoding to something else. Session data that caches roles, permissions or product lists typically shrinks 2-3x, which keeps a growing session within one DynamoDB read unit (4KB for the consistent reads sessions use) and one write unit (1KB) for longer.
 
 ```typescript
 session: {
@@ -549,9 +575,18 @@ The `ctx` object provides access to request data:
 | `await res.file(path, options? & { fallback? })` | Serve file from public directory (404 when missing) |
 | `await res.templateFile(path, data?, options?)` | Render an HTML file via LambderTemplatingEngine (cached; throws when missing) |
 | `res.api(payload, config?, options?)` | Standardized API response |
-| `res.apiBinary(payload, config?, options?)` | API response with forced gzip |
+| `res.apiBinary(payload, config?, options?)` | API response with forced compression |
 
-Responses are finalized once at the end of the request: automatic gzip (when the client accepts it, the body is compressible and large enough), automatic ETag + `If-None-Match` 304 handling on GET/HEAD, and a clear error if the body would exceed Lambda's ~6MB cap. Override per response with `compress: true | false` and `etag: false`.
+Responses are finalized once at the end of the request: automatic compression (when the client accepts it, the body is compressible and large enough), automatic ETag + `If-None-Match` 304 handling on GET/HEAD, and a clear error if the body would exceed Lambda's ~6MB cap. Override per response with `compress: true | false` and `etag: false`.
+
+The encoding is negotiated against `Accept-Encoding` in the order `compression.encodings` declares, `["br", "gzip"]` by default. Brotli at quality 5 (`compression.quality`) runs at roughly gzip's speed while producing smaller bodies: 15-25% on markup and prose, and substantially more on the repetitive record lists API responses tend to be. Because the ~6MB cap is checked on the FINAL body, that is headroom as well as bandwidth. A client that offers only gzip gets gzip, and `compression: { encodings: ["gzip"] }` turns Brotli off entirely for a CDN or client that mishandles it. `Vary: Accept-Encoding` rides every compressible response, whether or not this particular client accepted an encoding, so shared caches stay correct.
+
+```typescript
+initLambder().create({
+    compression: { minBytes: 860, encodings: ["br", "gzip"], quality: 5 },  // the defaults
+    // compression: false,  // no automatic compression at all
+});
+```
 
 **API Config Options**: `{ notAuthorized, message, errorMessage, versionExpired, sessionExpired, logList }`
 
@@ -697,6 +732,24 @@ lambder.addSessionApi("secure.order.create", {
 
 Guard results are typed end to end: the handler's `ctx.guardData` carries exactly the declared guards that return a value, a session guard on a public API is a compile error (and a startup assert), an apiInput guard is declarable only where the API's schema carries its fields, and a parameterized guard's param is typechecked in the declaration.
 
+**Requiring an authorization declaration (`requireSessionApiGuards`)**: by default a session API may declare no guards, which reads as "any signed-in user". Once an app has an authorization vocabulary, that silence is where defects hide: the guard exists, a new endpoint forgets it, and nothing notices. With `requireSessionApiGuards: true` at creation, `guards` becomes a required field of every `addSessionApi`: omitting it is a compile error at the registration site ("Property 'guards' is missing"), and a plain-JS registration throws. Public APIs are unaffected. An API that legitimately needs no authorization beyond the session (the signed-in user's own account, a log-out) declares a named no-op session guard, so the opt-out is explicit, greppable, and cannot be used on a public API:
+
+```typescript
+const lambder = initLambder<SessionData>().create({
+    apiPath: "/api",
+    guards: {
+        orgPermission: lambderGuard({ session: true, handler: (ctx, _p, _r, permission: PermissionString) => requireOrRefuse(ctx.session, permission) }),
+        // The one opt-out: the session itself is the whole authorization.
+        sessionOnly: lambderGuard({ session: true, handler: () => {} }),
+    },
+    requireSessionApiGuards: true,
+});
+
+lambder.addSessionApi("secure.order.create", { input, output, guards: { orgPermission: "ORDERS.CREATE" } }, handler);
+lambder.addSessionApi("secure.me.logOut", { input, output, guards: "sessionOnly" }, handler);
+lambder.addSessionApi("secure.report.list", { input, output }, handler);   // compile error: which guard?
+```
+
 For api modules split across files, DERIVE the annotation type from the real instance instead of writing it by hand: create the instance next to the policy declarations and export `typeof` it. The type can never drift from what actually runs, and modules import it without a cycle (the app file imports no modules):
 
 ```typescript
@@ -805,6 +858,38 @@ const user = await lambderCaller.api("getCompanyPage", { companyName: "Acme" });
 // - Expected output type
 ```
 
+### Compressed Request Payloads
+
+Large payloads run into Lambda's ~6MB invoke payload cap long before the API Gateway limit, and the cap applies to what the gateway hands the function. `requestCompression` gzips the payload of any call whose JSON reaches the threshold, so that budget holds the compressed bytes instead of the raw ones:
+
+```typescript
+const lambderCaller = new LambderCaller<ApiContractType>({
+    apiPath: "/api",
+    isCorsEnabled: false,
+    requestCompression: true,            // { minBytes: 4096 }
+    // requestCompression: { minBytes: 64_000 },  // only genuinely large calls
+});
+
+// Nothing at the call sites changes; this one goes compressed, that one plain.
+await lambderCaller.api("importStops", { stops: bigArray });
+await lambderCaller.api("getStop", { id: "42" });
+
+// Per call, either way:
+await lambderCaller.api("importStops", huge, { compressRequest: false });
+```
+
+A compressed call sends `payloadGz` (gzip bytes, base64) beside `payloadBytes` (the JSON's UTF-8 byte length) in place of `payload`. It is only sent when it is smaller than the JSON it replaces: a payload that is mostly a base64 image gzips to nearly its own size, and such a call goes plain rather than slightly larger. Everything else in the envelope stays plain text, so `apiName` routing, request logs and MSW mocks are unaffected, and the request stays `application/json`: no `Content-Encoding` negotiation for a gateway, CDN or proxy to get wrong, and no new CORS preflight surface. Base64 inside the JSON rather than a binary body is not a compromise for the size cap, because API Gateway hands a binary request body to Lambda base64-encoded anyway; base64's 4/3 overhead applies to bytes that already shrank several times over. Record-shaped JSON typically gzips 5-10x, so a ~5MB budget of compressed payload carries roughly 25-40MB of it.
+
+The option is off by default and safe to turn on or off at any time: the server understands both shapes regardless, so a deployed client and server never need to agree. gzip rather than Brotli because the browser's `CompressionStream` offers gzip and deflate only; responses, compressed by Node, do prefer Brotli. A runtime without `CompressionStream` sends payloads plainly.
+
+**Server side**: nothing to enable. The payload is restored before rate-limit key slices, guards and input validation run, so handlers, schemas and policies see an ordinary payload and need no awareness of the wire format. `payloadBytes` both bounds the decompression and verifies it (the restored length must match exactly), so a truncated or hostile body is refused rather than expanded, and `maxRequestPayloadBytes` at creation (default 20,000,000) caps what any body may expand to. Size that ceiling to the function's memory: the restored JSON is parsed in full before any session or policy check, and a parsed document occupies several times its text size on the heap. Every malformed case answers a 400 envelope coded `lambder/invalid-request-payload` instead of a 500.
+
+```typescript
+initLambder().create({ apiPath: "/api", maxRequestPayloadBytes: 20_000_000 });
+```
+
+Compression moves the ceiling rather than removing it. Past roughly 25-40MB of JSON the answer is a presigned S3 upload plus a job reference, or chunking, not a better codec.
+
 ### Failure Semantics (apiOutcome, timeouts, per-call overrides)
 
 `api()` collapses every failure to `null`, which is indistinguishable from a legitimately-null payload. When the call site needs to know why, use `apiOutcome()`; it never throws and resolves to a discriminated union:

package/dist/client/LambderCaller.d.ts

@@ -1,3 +1,4 @@
+import { type LambderRequestCompressionOption } from '../shared/LambderRequestPayload.js';
 import type { LambderApiResponse } from '../shared/LambderApiContract.js';
 import type { ApiContractShape } from '../shared/LambderApiContract.js';
 import type { z } from "zod";
@@ -114,6 +115,13 @@ export type LambderCallOptions = {
     timeoutMs?: number;
     /** External abort signal, combined with the timeout when both are set. */
     signal?: AbortSignal;
+    /**
+     * Overrides the constructor's requestCompression for this call: `false`
+     * sends the payload plainly (a hot path where the CPU matters more than
+     * the bytes), `true` compresses it regardless of the size threshold.
+     * Either way a payload is only sent compressed when that is smaller.
+     */
+    compressRequest?: boolean;
     /**
      * Values for the API's guardInput-mode guards, keyed by guard name; sent
      * beside the payload and consumed by the guards before validation. The
@@ -159,6 +167,16 @@ type LambderCallerBaseOptions = {
     apiInputValidationErrorHandler?: ValidationErrorHandler;
     /** Must mirror the server's session cookie Domain, otherwise expired cookies cannot be cleared. */
     sessionCookieDomain?: string | ((hostname: string) => string | undefined | null);
+    /**
+     * Gzip the payload of calls whose JSON reaches the threshold, sending it
+     * as `payloadGz` beside its byte length instead of `payload` whenever
+     * that is smaller (a base64 image, say, is not, and goes plain). Off by
+     * default; `true` is `{ minBytes: 4096 }`. Nothing at the call sites
+     * changes, and the server understands both shapes either way, so it can
+     * be turned on or off freely. Chiefly a way to fit a large payload under
+     * Lambda's ~6MB invoke cap, which applies to the compressed bytes.
+     */
+    requestCompression?: LambderRequestCompressionOption;
 };
 /** Constructor options: the base options plus guardInputsProvider, mandatory once TProvided names guards. */
 export type LambderCallerOptions<TContract, TProvided extends string = never> = LambderCallerBaseOptions & GuardInputsProviderOption<TContract, TProvided>;
@@ -186,6 +204,7 @@ export default class LambderCaller<TContract extends ApiContractShape = any, TPr
     private sessionTokenCookieKey;
     private sessionCsrfCookieKey;
     private sessionCookieDomain?;
+    private requestCompression;
     constructor(options: LambderCallerOptions<TContract, TProvidedGuards>);
     setSessionCookieKey(sessionTokenCookieKey: string, sessionCsrfCookieKey: string): void;
     /**

package/dist/client/LambderCaller.js

@@ -1,4 +1,6 @@
 import Cookies from 'js-cookie';
+import { compressPayloadJson, isRequestCompressionAvailable, DEFAULT_REQUEST_COMPRESSION_SETTINGS, } from '../shared/LambderRequestPayload.js';
+import { resolveCompressionOption } from '../shared/LambderCompressionOption.js';
 /**
  * @typeParam TContract - The API contract, for typed names, payloads and guard inputs.
  * @typeParam TProvidedGuards - Guard names guardInputsProvider covers; those APIs' options argument becomes optional.
@@ -23,15 +25,18 @@ export default class LambderCaller {
     sessionTokenCookieKey = "LMDRSESSIONTKID";
     sessionCsrfCookieKey = "LMDRSESSIONCSTK";
     sessionCookieDomain;
+    requestCompression;
     constructor(options) {
         // The conditional provider option is resolved per instantiation;
         // inside the class it is read through the plain shape.
-        const { apiPath, apiVersion, isCorsEnabled = false, timeoutMs, versionExpiredHandler, sessionExpiredHandler, messageHandler, errorMessageHandler, notAuthorizedHandler, errorHandler, fetchStartedHandler, fetchEndedHandler, apiInputValidationErrorHandler, sessionCookieDomain, guardInputsProvider, } = options;
+        const { apiPath, apiVersion, isCorsEnabled = false, timeoutMs, versionExpiredHandler, sessionExpiredHandler, messageHandler, errorMessageHandler, notAuthorizedHandler, errorHandler, fetchStartedHandler, fetchEndedHandler, apiInputValidationErrorHandler, sessionCookieDomain, requestCompression, guardInputsProvider, } = options;
         this.apiPath = apiPath ?? "/api";
         this.apiVersion = apiVersion;
         this.isCorsEnabled = isCorsEnabled;
         this.timeoutMs = timeoutMs;
         this.sessionCookieDomain = sessionCookieDomain;
+        // `?? false`: unlike the at-rest stores, this one is off unless asked for.
+        this.requestCompression = resolveCompressionOption(requestCompression ?? false, DEFAULT_REQUEST_COMPRESSION_SETTINGS);
         this.versionExpiredHandler = versionExpiredHandler;
         this.sessionExpiredHandler = sessionExpiredHandler;
         this.messageHandler = messageHandler;
@@ -178,6 +183,17 @@ export default class LambderCaller {
             const guardInputs = providedGuardInputs !== undefined || options?.guardInputs !== undefined
                 ? { ...providedGuardInputs, ...options?.guardInputs }
                 : undefined;
+            // Compressed when enabled and the payload's JSON reaches the
+            // threshold; `compressRequest` overrides both ways, and a runtime
+            // without CompressionStream always sends the payload plainly.
+            // Nothing here runs (the extra stringify included) unless
+            // compression is actually a possibility for this call.
+            const compressionMinBytes = options?.compressRequest === true ? 0
+                : options?.compressRequest === false ? null
+                    : this.requestCompression?.minBytes ?? null;
+            const compressedPayload = compressionMinBytes !== null && payload !== undefined && isRequestCompressionAvailable()
+                ? await compressPayloadJson(JSON.stringify(payload), compressionMinBytes)
+                : null;
             let res;
             try {
                 res = await fetch(this.apiPath, {
@@ -188,7 +204,8 @@ export default class LambderCaller {
                     redirect: 'follow', referrerPolicy: 'origin',
                     headers: { 'Content-Type': 'application/json', ...(headers || {}) },
                     body: JSON.stringify({
-                        apiName, version, token, siteHost, payload,
+                        apiName, version, token, siteHost,
+                        ...(compressedPayload ?? { payload }),
                         ...(guardInputs !== undefined ? { guardInputs } : {}),
                         ...(options?.idempotencyKey !== undefined ? { idempotencyKey: options.idempotencyKey } : {}),
                     }),

package/dist/client/LambderMSW.js

@@ -1,3 +1,4 @@
+import { COMPRESSED_PAYLOAD_FIELD, COMPRESSED_PAYLOAD_BYTES_FIELD, decompressPayloadJson } from '../shared/LambderRequestPayload.js';
 export default class LambderMSW {
     apiPath;
     apiVersion;
@@ -42,6 +43,20 @@ export default class LambderMSW {
             if (body.apiName !== apiName) {
                 return;
             }
+            // A caller with requestCompression on sends the payload gzipped;
+            // mock handlers still receive the payload itself, and the wire
+            // fields are consumed the way the server consumes them.
+            if (typeof body[COMPRESSED_PAYLOAD_FIELD] === 'string') {
+                try {
+                    body.payload = await decompressPayloadJson(body[COMPRESSED_PAYLOAD_FIELD]);
+                }
+                catch {
+                    console.warn("LambderMSW: Failed to decompress the request payload");
+                    return;
+                }
+                delete body[COMPRESSED_PAYLOAD_FIELD];
+                delete body[COMPRESSED_PAYLOAD_BYTES_FIELD];
+            }
             try {
                 // Add artificial delay if specified
                 if (options?.delay) {

package/dist/client.d.ts

@@ -11,6 +11,10 @@ export type { LambderApiOutcome, LambderApiFailureReason, LambderCallOptions, La
 export { LambderApiError, isLambderApiError, refuse, LAMBDER_REFUSAL_CODES } from "./shared/LambderApiError.js";
 export type { LambderApiErrorOptions, LambderRefusalMessage, LambderRefusalCode, LambderRefuseOptions } from "./shared/LambderApiError.js";
 export type { ApiContractShape, LambderApiResponse, LambderApiResponseConfig } from "./shared/LambderApiContract.js";
+export { compressPayloadJson, decompressPayloadJson, isRequestCompressionAvailable, COMPRESSED_PAYLOAD_FIELD, COMPRESSED_PAYLOAD_BYTES_FIELD, DEFAULT_REQUEST_COMPRESSION_SETTINGS, } from "./shared/LambderRequestPayload.js";
+export type { LambderCompressedPayload, LambderRequestCompressionOption, LambderRequestCompressionSettings, } from "./shared/LambderRequestPayload.js";
+export { resolveCompressionOption } from "./shared/LambderCompressionOption.js";
+export type { LambderCompressionOption, LambderCompressionSettingsBase } from "./shared/LambderCompressionOption.js";
 export { html, xml, raw, jsonScript, escapeHtml, renderHtmlValue, LambderSafeHtml, type LambderHtmlValue } from "./shared/LambderHtml.js";
 export { createLambderI18n } from "./shared/LambderI18n.js";
 export type { LambderLanguageMeta, LambderI18nConfig, LambderI18nInstance, LambderI18nTranslator, LambderI18nExtractParams, LambderI18nCodes, LambderI18nKeys, LambderI18nTranslatorFor, } from "./shared/LambderI18n.js";

package/dist/client.js

@@ -11,6 +11,10 @@ export { default as LambderCaller } from "./client/LambderCaller.js";
 // Typed API refusals (isomorphic: shared code may throw them from anywhere;
 // in the browser they are plain Errors).
 export { LambderApiError, isLambderApiError, refuse, LAMBDER_REFUSAL_CODES } from "./shared/LambderApiError.js";
+// Request payload compression (browser-safe: gzip via CompressionStream, no Node built-ins).
+export { compressPayloadJson, decompressPayloadJson, isRequestCompressionAvailable, COMPRESSED_PAYLOAD_FIELD, COMPRESSED_PAYLOAD_BYTES_FIELD, DEFAULT_REQUEST_COMPRESSION_SETTINGS, } from "./shared/LambderRequestPayload.js";
+// The compression option vocabulary every Lambder surface shares (pure: no zlib).
+export { resolveCompressionOption } from "./shared/LambderCompressionOption.js";
 // Type-safe templating (tagged templates with auto-escaping)
 export { html, xml, raw, jsonScript, escapeHtml, renderHtmlValue, LambderSafeHtml } from "./shared/LambderHtml.js";
 // Typed translations (standalone, isomorphic)

package/dist/core/Lambder.d.ts

@@ -2,11 +2,11 @@ import type { z } from "zod";
 import type { Context } from "aws-lambda";
 import LambderResolver from "./LambderResolver.js";
 import LambderResponseBuilder from "./LambderResponseBuilder.js";
-import { LambderResponse, type LambderHttpResponse } from "./LambderResponse.js";
+import { LambderResponse, type LambderHttpResponse, type LambderResponseCompressionOption } from "./LambderResponse.js";
 import { type ConditionFunction, type LambderRouteMatcher, type PathParamsOf } from "./LambderRouting.js";
 import { type LambderCorsConfig } from "./LambderCors.js";
 import { type LambderSessionDataRefreshConfig } from "../session/LambderSessionManager.js";
-import type { LambderCompressionOption } from "../stores/LambderDdbCompression.js";
+import { type LambderCompressionOption } from "../shared/LambderCompressionOption.js";
 import LambderSessionController, { type LambderSessionCookieOptions } from "../session/LambderSessionController.js";
 import { type LambderPublicFilesOptions } from "./LambderPublicFiles.js";
 import { LambderFiles, type LambderFilesOption } from "./LambderFiles.js";
@@ -21,7 +21,7 @@ type MaybePromise<T> = T | Promise<T>;
 type Path = `/${string}`;
 type ActionFunction = (ctx: LambderRenderContext, resolver: LambderResolver) => MaybePromise<LambderResponse>;
 type SessionActionFunction<SessionData = any> = (ctx: LambderSessionRenderContext<any, SessionData>, resolver: LambderResolver) => MaybePromise<LambderResponse>;
-type HookCreatedFunction = (lambderInstance: Lambder<any, any, any, any, any>) => void | Promise<void>;
+type HookCreatedFunction = (lambderInstance: Lambder<any, any, any, any, any, any>) => void | Promise<void>;
 /** Return the (possibly replaced) ctx to continue, a LambderResponse to short-circuit, or an Error to fail. */
 type HookBeforeRenderFunction = (ctx: LambderRenderContext, resolver: LambderResolver) => MaybePromise<LambderRenderContext | LambderResponse | Error>;
 type HookAfterRenderFunction = (ctx: LambderRenderContext, resolver: LambderResolver, response: LambderResponse) => MaybePromise<LambderResponse | Error>;
@@ -118,14 +118,26 @@ export type LambderCreateOptions<TSessionData = any> = {
     files?: LambderFilesOption;
     apiPath?: string;
     apiVersion?: string;
-    /** Automatic gzip for compressible responses. `true` (the default) is `{ minBytes: 860 }`; `false` disables it. */
-    compression?: boolean | {
-        minBytes?: number;
-    };
+    /**
+     * Automatic compression for compressible responses. `true` (the default)
+     * is `{ minBytes: 860, encodings: ["br", "gzip"], quality: 5 }`; `false`
+     * disables it. `encodings` is a preference order, so `["gzip"]` opts out
+     * of Brotli for a client or CDN that mishandles it, and `quality` is the
+     * Brotli quality, the same field the at-rest stores take.
+     */
+    compression?: LambderResponseCompressionOption;
     /** Automatic ETag + If-None-Match 304 on GET/HEAD 200 responses. Default: true. */
     etag?: boolean;
     /** Guard threshold for Lambda's ~6MB response cap. Default: 5,500,000. */
     maxResponseBytes?: number;
+    /**
+     * Ceiling on what a gzipped request payload may restore to (Lambda's
+     * ~6MB invoke cap already bounds the compressed bytes). Default:
+     * 20,000,000. Requests over it are refused rather than decompressed.
+     * The restored JSON is parsed in full before any policy or session
+     * check, so size it to the function's memory.
+     */
+    maxRequestPayloadBytes?: number;
     /** CORS: true allows any origin; or pass a LambderCorsConfig. Default: off. */
     cors?: boolean | LambderCorsConfig;
     /** DynamoDB-backed sessions; required for addSessionApi/addSessionRoute. */
@@ -134,9 +146,32 @@ export type LambderCreateOptions<TSessionData = any> = {
     rateLimits?: LambderApiRateLimitsConfig<Record<string, LambderApiRateLimitPolicyConfig>>;
     /** Named guards APIs reference (typed) via the `guards` option; build each with lambderGuard(). */
     guards?: Record<string, LambderApiGuard<any, any, any>>;
+    /**
+     * Make an authorization declaration part of registering a session API:
+     * every addSessionApi must declare `guards`, at the type level (a
+     * missing `guards` is a compile error) and at registration (a plain-JS
+     * caller throws). An API that legitimately needs none, because the
+     * session itself is the whole authorization (the signed-in user's own
+     * account), declares a named no-op session guard, so every opt-out is
+     * explicit and one grep lists them all. Needs a guards map to pick
+     * from. Default: false.
+     */
+    requireSessionApiGuards?: boolean;
     /** Declarative idempotency: your store plus replay defaults; APIs opt in via `idempotency: true | { ttlSeconds }`. */
     idempotency?: LambderApiIdempotencyConfig;
 };
+/**
+ * The `guards` field of a session API's options: optional by default,
+ * required once create() received requireSessionApiGuards, so that an
+ * authorization declaration cannot be forgotten at the type level.
+ */
+type LambderSessionGuardsField<TRequired extends boolean, TGuardsOpt> = TRequired extends true ? {
+    /** Named guards, run in declared order before input validation: a name, a list of names, or a { name: param } map for parameterized guards. Required on this instance (requireSessionApiGuards): an API the session alone authorizes declares the named no-op session guard. Their input requirements merge into this API's contract input; their return values land typed on ctx.guardData. */
+    guards: TGuardsOpt;
+} : {
+    /** Named guards, run in declared order before input validation: a name, a list of names, or a { name: param } map for parameterized guards. Their input requirements merge into this API's contract input; their return values land typed on ctx.guardData. */
+    guards?: TGuardsOpt;
+};
 /**
  * Main Lambder class for building type-safe serverless APIs. Create
  * instances with initLambder<SessionData>().create({...}) (see below): the
@@ -148,6 +183,7 @@ export type LambderCreateOptions<TSessionData = any> = {
  * @typeParam _TRateLimitPolicies - @internal Inferred from create()'s rateLimits.policies (do not pass manually)
  * @typeParam _TGuards - @internal Guard metadata map inferred from create()'s guards (do not pass manually)
  * @typeParam _TIdempotencyEnabled - @internal True when create() received idempotency (do not pass manually)
+ * @typeParam _TSessionGuardsRequired - @internal True when create() received requireSessionApiGuards (do not pass manually)
  *
  * @example
  * ```typescript
@@ -158,7 +194,7 @@ export type LambderCreateOptions<TSessionData = any> = {
  *   .addApi('createUser', { input: z.object({...}), output: z.object({...}) }, handler);
  * ```
  */
-export default class Lambder<TSessionData = any, _TContract extends Record<string, any> = {}, _TRateLimitPolicies extends Record<string, LambderApiRateLimitPolicyConfig> = {}, _TGuards extends Record<string, any> = {}, _TIdempotencyEnabled extends boolean = false> {
+export default class Lambder<TSessionData = any, _TContract extends Record<string, any> = {}, _TRateLimitPolicies extends Record<string, LambderApiRateLimitPolicyConfig> = {}, _TGuards extends Record<string, any> = {}, _TIdempotencyEnabled extends boolean = false, _TSessionGuardsRequired extends boolean = false> {
     apiPath: string;
     apiVersion: null | string;
     /** The instance's file reader (source + caches), or null without the files option. */
@@ -190,6 +226,8 @@ export default class Lambder<TSessionData = any, _TContract extends Record<strin
     private eventActionList;
     private corsConfig;
     private finalizeOptions;
+    private maxRequestPayloadBytes;
+    private requireSessionApiGuards;
     private lambderSessionManager?;
     private sessionCookieOptions;
     private sessionTokenCookieKey;
@@ -237,7 +275,7 @@ export default class Lambder<TSessionData = any, _TContract extends Record<strin
     addRoute(condition: RegExp | ConditionFunction | LambderRouteMatcher, actionFn: ActionFunction): this;
     addSessionRoute<TPath extends Path>(condition: TPath, actionFn: (ctx: LambderSessionRenderContext<any, TSessionData, PathParamsOf<TPath>>, resolver: LambderResolver) => MaybePromise<LambderResponse>): this;
     addSessionRoute(condition: RegExp | ConditionFunction | LambderRouteMatcher, actionFn: SessionActionFunction<TSessionData>): this;
-    use<_TNewContract extends Record<string, any>>(plugin: (lambder: Lambder<TSessionData, _TContract, any, any, any>) => Lambder<TSessionData, _TNewContract, any, any, any>): Lambder<TSessionData, _TNewContract extends _TContract ? _TNewContract : (_TContract & _TNewContract), _TRateLimitPolicies, _TGuards, _TIdempotencyEnabled>;
+    use<_TNewContract extends Record<string, any>>(plugin: (lambder: Lambder<TSessionData, _TContract, any, any, any>) => Lambder<TSessionData, _TNewContract, any, any, any>): Lambder<TSessionData, _TNewContract extends _TContract ? _TNewContract : (_TContract & _TNewContract), _TRateLimitPolicies, _TGuards, _TIdempotencyEnabled, _TSessionGuardsRequired>;
     addApi<TName extends string, TInput extends z.ZodTypeAny, TOutput extends z.ZodTypeAny, const TRateOpt extends LambderRateLimitOption<_TRateLimitPolicies, z.infer<TInput>, false> = never, const TGuardsOpt extends LambderGuardsOption<_TGuards, z.infer<TInput>, false> = never>(name: TName, schema: {
         input: TInput;
         output: TOutput;
@@ -250,20 +288,18 @@ export default class Lambder<TSessionData = any, _TContract extends Record<strin
         idempotency?: _TIdempotencyEnabled extends true ? (boolean | {
             ttlSeconds?: number;
         }) : never;
-    }, handler: (ctx: LambderRenderContext<z.infer<TInput>, Record<string, string>, LambderGuardDataOf<_TGuards, TGuardsOpt>>, resolver: LambderResolver<z.infer<TOutput>>) => MaybePromise<LambderResponse>): Lambder<TSessionData, MergeContract<_TContract, TName, z.infer<TInput>, z.infer<TOutput>, LambderGuardInputsOf<_TGuards, TGuardsOpt>>, _TRateLimitPolicies, _TGuards, _TIdempotencyEnabled>;
+    }, handler: (ctx: LambderRenderContext<z.infer<TInput>, Record<string, string>, LambderGuardDataOf<_TGuards, TGuardsOpt>>, resolver: LambderResolver<z.infer<TOutput>>) => MaybePromise<LambderResponse>): Lambder<TSessionData, MergeContract<_TContract, TName, z.infer<TInput>, z.infer<TOutput>, LambderGuardInputsOf<_TGuards, TGuardsOpt>>, _TRateLimitPolicies, _TGuards, _TIdempotencyEnabled, _TSessionGuardsRequired>;
     addSessionApi<TName extends string, TInput extends z.ZodTypeAny, TOutput extends z.ZodTypeAny, const TRateOpt extends LambderRateLimitOption<_TRateLimitPolicies, z.infer<TInput>, true> = never, const TGuardsOpt extends LambderGuardsOption<_TGuards, z.infer<TInput>, true> = never>(name: TName, schema: {
         input: TInput;
         output: TOutput;
     } & {
         /** Named rate limits, checked in declared order before guards and validation: a name, a list of names, or a { name: true | override } map (windows overridable on perApi budgets, errorMessage on any). The first exceeded one refuses (429 envelope + Retry-After); attempts count on every counter checked before it. */
         rateLimit?: TRateOpt;
-        /** Named guards, run in declared order before input validation: a name, a list of names, or a { name: param } map for parameterized guards. Their input requirements merge into this API's contract input; their return values land typed on ctx.guardData. */
-        guards?: TGuardsOpt;
         /** Replay-protect this API per client idempotencyKey. Requires the idempotency option at creation. */
         idempotency?: _TIdempotencyEnabled extends true ? (boolean | {
             ttlSeconds?: number;
         }) : never;
-    }, handler: (ctx: LambderSessionRenderContext<z.infer<TInput>, TSessionData, Record<string, string>, LambderGuardDataOf<_TGuards, TGuardsOpt>>, resolver: LambderResolver<z.infer<TOutput>>) => MaybePromise<LambderResponse>): Lambder<TSessionData, MergeContract<_TContract, TName, z.infer<TInput>, z.infer<TOutput>, LambderGuardInputsOf<_TGuards, TGuardsOpt>>, _TRateLimitPolicies, _TGuards, _TIdempotencyEnabled>;
+    } & LambderSessionGuardsField<_TSessionGuardsRequired, TGuardsOpt>, handler: (ctx: LambderSessionRenderContext<z.infer<TInput>, TSessionData, Record<string, string>, LambderGuardDataOf<_TGuards, TGuardsOpt>>, resolver: LambderResolver<z.infer<TOutput>>) => MaybePromise<LambderResponse>): Lambder<TSessionData, MergeContract<_TContract, TName, z.infer<TInput>, z.infer<TOutput>, LambderGuardInputsOf<_TGuards, TGuardsOpt>>, _TRateLimitPolicies, _TGuards, _TIdempotencyEnabled, _TSessionGuardsRequired>;
     /**
      * Fetch the session or short-circuit the request: API calls get the
      * protocol's { sessionExpired: true } response (handled by LambderCaller),
@@ -346,5 +382,5 @@ export default class Lambder<TSessionData = any, _TContract extends Record<strin
 export declare const initLambder: <TSessionData = any>() => {
     create<const TOptions extends LambderCreateOptions<TSessionData>>(options: TOptions): Lambder<TSessionData, {}, TOptions["rateLimits"] extends {
         policies: infer TPolicies extends Record<string, LambderApiRateLimitPolicyConfig>;
-    } ? TPolicies : {}, TOptions["guards"] extends Record<string, LambderApiGuard<any, any, any>> ? LambderGuardMetaMap<TOptions["guards"]> : {}, TOptions["idempotency"] extends LambderApiIdempotencyConfig ? true : false>;
+    } ? TPolicies : {}, TOptions["guards"] extends Record<string, LambderApiGuard<any, any, any>> ? LambderGuardMetaMap<TOptions["guards"]> : {}, TOptions["idempotency"] extends LambderApiIdempotencyConfig ? true : false, TOptions["requireSessionApiGuards"] extends true ? true : false>;
 };

package/dist/core/Lambder.js

@@ -1,15 +1,17 @@
 import LambderResolver from "./LambderResolver.js";
 import LambderResponseBuilder from "./LambderResponseBuilder.js";
-import { LambderResponse, finalizeResponse, DEFAULT_FINALIZE_OPTIONS, } from "./LambderResponse.js";
+import { LambderResponse, finalizeResponse, DEFAULT_FINALIZE_OPTIONS, DEFAULT_RESPONSE_COMPRESSION_SETTINGS, } from "./LambderResponse.js";
 import { compileRouteMatcher } from "./LambderRouting.js";
 import { applyCorsHeaders } from "./LambderCors.js";
 import LambderSessionManager from "../session/LambderSessionManager.js";
+import { resolveCompressionOption } from "../shared/LambderCompressionOption.js";
 import LambderSessionController from "../session/LambderSessionController.js";
 import { LambderPublicFilesHandler } from "./LambderPublicFiles.js";
 import { LambderFiles } from "./LambderFiles.js";
 import { isLambderApiError, LAMBDER_REFUSAL_CODES } from "../shared/LambderApiError.js";
 import { LambderApiPolicyEngine } from "../policies/LambderApiPolicies.js";
-import { createContext, isV2HttpEvent } from "./LambderContext.js";
+import { createContext, isV2HttpEvent, restoreCompressedApiPayload } from "./LambderContext.js";
+import { DEFAULT_MAX_REQUEST_PAYLOAD_BYTES } from "../shared/LambderRequestPayload.js";
 /**
  * Main Lambder class for building type-safe serverless APIs. Create
  * instances with initLambder<SessionData>().create({...}) (see below): the
@@ -21,6 +23,7 @@ import { createContext, isV2HttpEvent } from "./LambderContext.js";
  * @typeParam _TRateLimitPolicies - @internal Inferred from create()'s rateLimits.policies (do not pass manually)
  * @typeParam _TGuards - @internal Guard metadata map inferred from create()'s guards (do not pass manually)
  * @typeParam _TIdempotencyEnabled - @internal True when create() received idempotency (do not pass manually)
+ * @typeParam _TSessionGuardsRequired - @internal True when create() received requireSessionApiGuards (do not pass manually)
  *
  * @example
  * ```typescript
@@ -63,6 +66,8 @@ export default class Lambder {
     eventActionList = [];
     corsConfig = null;
     finalizeOptions;
+    maxRequestPayloadBytes;
+    requireSessionApiGuards;
     lambderSessionManager;
     sessionCookieOptions = {};
     sessionTokenCookieKey = "LMDRSESSIONTKID";
@@ -72,13 +77,16 @@ export default class Lambder {
         this.apiPath = options.apiPath ?? "/api";
         this.apiVersion = options.apiVersion ?? null;
         this.finalizeOptions = {
-            compression: options.compression === false
-                ? false
-                : { minBytes: (typeof options.compression === "object" ? options.compression.minBytes : undefined)
-                        ?? DEFAULT_FINALIZE_OPTIONS.compression.minBytes },
+            // Resolved (and validated) by the same function the at-rest
+            // stores use; on unless explicitly disabled.
+            compression: resolveCompressionOption(options.compression, DEFAULT_RESPONSE_COMPRESSION_SETTINGS),
             etag: options.etag ?? DEFAULT_FINALIZE_OPTIONS.etag,
             maxResponseBytes: options.maxResponseBytes ?? DEFAULT_FINALIZE_OPTIONS.maxResponseBytes,
         };
+        this.maxRequestPayloadBytes = options.maxRequestPayloadBytes ?? DEFAULT_MAX_REQUEST_PAYLOAD_BYTES;
+        if (!Number.isSafeInteger(this.maxRequestPayloadBytes) || this.maxRequestPayloadBytes <= 0) {
+            throw new Error("maxRequestPayloadBytes must be a positive integer");
+        }
         if (options.cors !== undefined && options.cors !== false) {
             this.corsConfig = options.cors === true ? {} : options.cors;
         }
@@ -107,6 +115,10 @@ export default class Lambder {
             this.getOrCreatePolicyEngine().addGuards(options.guards);
         if (options.idempotency)
             this.getOrCreatePolicyEngine().setIdempotency(options.idempotency);
+        this.requireSessionApiGuards = options.requireSessionApiGuards ?? false;
+        if (this.requireSessionApiGuards && !options.guards) {
+            throw new Error("Lambder: requireSessionApiGuards needs a guards map at creation for session APIs to declare from.");
+        }
     }
     setRouteFallbackHandler(routeFallbackHandler) {
         this.routeFallbackHandler = routeFallbackHandler;
@@ -203,6 +215,10 @@ export default class Lambder {
             throw new Error(`Lambder: duplicate API name "${name}". Dispatch is first-match, so the second registration would be silently dead code.`);
         }
         this.registeredApiNames.add(name);
+        if (mode === "session" && this.requireSessionApiGuards && options.guards === undefined) {
+            throw new Error(`Lambder: session API "${name}" declares no guards, and requireSessionApiGuards is on. ` +
+                `Declare the guard that authorizes it, or the named no-op guard that marks the session itself as the whole authorization.`);
+        }
         const usesPolicies = options.rateLimit !== undefined || options.guards !== undefined || options.idempotency !== undefined;
         if (!usesPolicies)
             return;
@@ -454,6 +470,20 @@ export default class Lambder {
         if (this.apiVersion && ctx._otherInternal.requestVersion && ctx._otherInternal.requestVersion !== this.apiVersion) {
             return resolver.versionExpired();
         }
+        // A gzipped payload is restored before anything reads it: rate-limit
+        // key slices, guards and input validation all see a plain payload.
+        if (ctx._otherInternal.isApiCall) {
+            const restored = await restoreCompressedApiPayload(ctx, this.maxRequestPayloadBytes);
+            if (!restored.ok) {
+                return resolver.api(null, {
+                    errorMessage: {
+                        type: "error",
+                        code: LAMBDER_REFUSAL_CODES.invalidRequestPayload,
+                        content: restored.message,
+                    },
+                }, { statusCode: 400 });
+            }
+        }
         let matched = null;
         for (const action of this.actionList) {
             const params = action.match(ctx);

package/dist/core/LambderContext.d.ts

@@ -58,3 +58,23 @@ export type LambderSessionRenderContext<TApiPayload = any, SessionData = any, TP
     session: LambderSessionContext<SessionData>;
 };
 export declare const createContext: (event: LambderHttpEvent, lambdaContext: Context, apiPath: string) => LambderRenderContext;
+/** Outcome of restoring a compressed request payload; the message is client-facing. */
+export type LambderRestorePayloadResult = {
+    ok: true;
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * Restores a request payload the caller sent gzipped (`payloadGz` +
+ * `payloadBytes`) onto ctx.post.payload and ctx.apiPayload, so every later
+ * stage (rate-limit key slices, guards, input validation, the handler) reads
+ * an ordinary payload and needs no awareness of the wire format. A request
+ * that sent a plain payload passes through untouched.
+ *
+ * Every failure answers with a message instead of throwing: a malformed body
+ * is a client error, not a crash. The declared byte length both bounds the
+ * decompression and verifies it, so an over-large or tampered body is
+ * refused rather than expanded.
+ */
+export declare const restoreCompressedApiPayload: (ctx: LambderRenderContext, maxPayloadBytes: number) => Promise<LambderRestorePayloadResult>;