lambder 7.3.1 → 8.0.2

package/dist/core/Lambder.js

@@ -2,9 +2,11 @@ import LambderResolver from "./LambderResolver.js";
 import LambderResponseBuilder from "./LambderResponseBuilder.js";
 import { LambderResponse, finalizeResponse, answerFromResponse, responseFromAnswer, emitResponse, DEFAULT_FINALIZE_OPTIONS, DEFAULT_RESPONSE_COMPRESSION_SETTINGS, } from "./LambderResponse.js";
 import { compileRouteMatcher } from "./LambderRouting.js";
-import { applyCorsHeaders } from "./LambderCors.js";
+import { allowedCorsOriginOf, applyCorsHeaders } from "./LambderCors.js";
 import LambderSessionManager from "../session/LambderSessionManager.js";
 import { resolveCompressionOption } from "../shared/wire/LambderCompressionOption.js";
+import { DEFAULT_API_PATH } from "../shared/wire/LambderDefaultApiPath.js";
+import { LambderSessionNotFoundError } from "../session/LambderSessionController.js";
 import { LambderPublicFilesHandler } from "./LambderPublicFiles.js";
 import { LambderIndexHtmlHandler } from "./LambderIndexHtml.js";
 import { LambderFiles } from "./LambderFiles.js";
@@ -13,10 +15,12 @@ import { LambderApiPipeline } from "../api/LambderApiPipeline.js";
 import { LAMBDER_BACKEND_SWAP, LAMBDER_CRASH_WATCH } from "../shared/util/LambderTestingDoors.js";
 import { apiSignatureOf } from "../api/LambderApiSignature.js";
 import { apiNameKeyOf } from "../shared/wire/LambderApiSignature.js";
-import { apiNotFoundAnswer, crashAnswer, refusalAnswer, } from "../api/LambderApiEnvelope.js";
-import { createContext, isV2HttpEvent } from "./LambderContext.js";
+import { apiNotFoundAnswer, refusalAnswer, sessionExpiredAnswer, } from "../api/LambderApiEnvelope.js";
+import { bindContextTools, createContext, isV2HttpEvent, } from "./LambderContext.js";
 import { COMPRESSED_PAYLOAD_GZ_FIELD, COMPRESSED_PAYLOAD_BR_FIELD, COMPRESSED_PAYLOAD_BYTES_FIELD } from "../shared/wire/LambderRequestPayload.js";
 import { coerceToError } from "../shared/wire/LambderCrashDetail.js";
+import { LambderCrashHandling } from "./LambderCrashHandling.js";
+import { policyBuildersFor } from "./LambderPolicyBuilders.js";
 import { assertCreateOptions, } from "./LambderCreateOptions.js";
 /**
  * Main Lambder class for building type-safe serverless APIs. Create
@@ -31,7 +35,7 @@ import { assertCreateOptions, } from "./LambderCreateOptions.js";
  * @typeParam _TIdempotencyEnabled - @internal True when create() received idempotency (do not pass manually)
  * @typeParam _TSessionGuardsRequired - @internal True when create() received requireSessionApiGuards (do not pass manually)
  * @typeParam _TPublicGuardsRequired - @internal True when create() received requirePublicApiGuards (do not pass manually)
- * @typeParam _TSessionsEnabled - @internal True when create() received the session option (do not pass manually). It defaults to TRUE, unlike its siblings: a plugin module annotates its parameter as the bare Lambder<SessionData>, and that annotation has to keep registering session APIs. create() is where the option is actually known, so create() is where the false comes from; `new Lambder(...)` keeps only the registration-time throw.
+ * @typeParam _TSessionsEnabled - @internal True when create() received the session option (do not pass manually). Defaults to true, unlike its siblings, so a plugin annotating its parameter as the bare Lambder<SessionData> can still register session APIs. create() knows the option and supplies the false; `new Lambder(...)` relies on the registration-time throw alone.
  *
  * @example
  * ```typescript
@@ -53,15 +57,15 @@ export default class Lambder {
     /** The instance's file reader (source + caches), or null without the files option. */
     files;
     /**
-     * Type property for extracting the API contract
-     * Use this to export your API types to the frontend
+     * Type property for extracting the API contract, to export your API
+     * types to the frontend.
      *
      * Export it as an interface extending LambderFlattenContract, not as a
      * type alias. Chaining builds the contract as an intersection one member
-     * deep per endpoint, and an interface collapses that into one declared
-     * set of members, which every generic read of the contract (a mock
-     * registry, a needs map, the typed caller) is then far cheaper against.
-     * See LambderFlattenContract for the measurements.
+     * deep per endpoint; an interface collapses that into one declared set of
+     * members, which every generic read of the contract (a mock registry, a
+     * needs map, the typed caller) checks far more cheaply. See
+     * LambderFlattenContract for the measurements.
      *
      * @example
      * ```typescript
@@ -93,17 +97,24 @@ export default class Lambder {
     requireSessionApiGuards;
     /** Told what a request threw, beside whatever answers it; null outside a test. See LAMBDER_CRASH_WATCH. */
     crashWatcher = null;
+    /** The crashes option applied: reporting, and the framework's own 500. */
+    crashHandling;
+    /** What this instance binds onto every context it renders (ctx.sessionController, ctx.rateLimit, ctx.isRateLimited). */
+    contextTools;
     trustedClientIpHeaders;
+    trustedHostHeaders;
     requirePublicApiGuards;
     constructor(options = {}) {
         assertCreateOptions(options);
         this.files = options.files ? new LambderFiles(options.files) : null;
-        this.apiPath = options.apiPath ?? "/api";
+        this.apiPath = options.apiPath ?? DEFAULT_API_PATH;
         this.apiVersion = options.apiVersion ?? null;
+        // Resolved (and validated) by the same function the at-rest stores
+        // use; on unless explicitly disabled, except on a REST API, where it
+        // is on only when the app names it: see LambderFinalizeOptions.
+        const compression = resolveCompressionOption(options.compression, DEFAULT_RESPONSE_COMPRESSION_SETTINGS);
         this.finalizeOptions = {
-            // Resolved (and validated) by the same function the at-rest
-            // stores use; on unless explicitly disabled.
-            compression: resolveCompressionOption(options.compression, DEFAULT_RESPONSE_COMPRESSION_SETTINGS),
+            compression: { v1: options.compression === undefined ? null : compression, v2: compression },
             etag: options.etag ?? DEFAULT_FINALIZE_OPTIONS.etag,
             maxResponseBytes: options.maxResponseBytes ?? DEFAULT_FINALIZE_OPTIONS.maxResponseBytes,
         };
@@ -140,8 +151,34 @@ export default class Lambder {
             idempotency: options.idempotency,
         });
         this.trustedClientIpHeaders = options.trustedClientIpHeaders ?? [];
+        this.trustedHostHeaders = options.trustedHostHeaders ?? [];
         this.requireSessionApiGuards = options.requireSessionApiGuards ?? false;
         this.requirePublicApiGuards = options.requirePublicApiGuards ?? false;
+        this.crashHandling = new LambderCrashHandling(options.crashes ?? {}, this.apiVersion);
+        this.contextTools = {
+            sessionControllerFor: (ctx) => this.getSessionController(ctx),
+            chargeRateLimit: async (ctx, policy, key, refuse) => {
+                const { checkResult, refusal } = await this.pipeline.chargeRateLimit(policy, {
+                    // A per-API budget counts per registered API. The posted
+                    // name of a call no API matched (a hook or the fallback
+                    // charging it) is the caller's choice, and a fresh name
+                    // per request would be a fresh counter.
+                    apiName: ctx.api && this.apiDefinitions.has(ctx.api.apiName) ? ctx.api.apiName : null,
+                    ip: ctx.ip,
+                    session: ctx.session,
+                    key,
+                });
+                if (refuse && refusal) {
+                    if (ctx.api)
+                        throw refusal;
+                    // A route has no envelope to carry a refusal, so it
+                    // answers the same 429 as text, with the same Retry-After
+                    // and the policy's own words.
+                    throw this.getResolver(ctx).text(refusal.errorMessage.content, { statusCode: 429, headers: refusal.headers });
+                }
+                return checkResult;
+            },
+        };
     }
     // =====================================================================
     // Registration
@@ -163,7 +200,13 @@ export default class Lambder {
         this.globalErrorHandler = globalErrorHandler;
         return this;
     }
-    /** Response for session routes when the session is missing/expired (non-API). Default: 401. */
+    /**
+     * Response for a session route when the session is missing or expired,
+     * and for any non-API request whose route or hook meets a
+     * LambderSessionNotFoundError (the session ended while the request held
+     * it, or a session read found none, or cookies naming several: a
+     * LambderSessionAmbiguousError). Default: 401.
+     */
     setSessionExpiredRouteHandler(handler) {
         this.sessionExpiredRouteHandler = handler;
         return this;
@@ -173,10 +216,10 @@ export default class Lambder {
      * never shadow routes registered after it. Serves files from the `files`
      * source configured at creation, under the reader's path rule, mime-typed,
      * memory-cached, with the immutable-cache heuristic for content-hashed
-     * assets. Only configured methods reach it, default GET/HEAD, as for
-     * serveIndexHtml; a gated-out method and a path the source has no file
-     * for both fall through to setRouteFallbackHandler, where the app decides
-     * what remains (e.g. render an app shell with res.templateFile).
+     * assets. Only configured methods reach it (default GET/HEAD); a
+     * gated-out method or a path with no file falls through to
+     * setRouteFallbackHandler, where the app decides what remains (e.g.
+     * render an app shell with res.templateFile).
      */
     servePublicFiles(options = {}) {
         if (!this.files)
@@ -218,29 +261,51 @@ export default class Lambder {
     }
     // Typed API with Zod
     addApi(name, schema, handler) {
-        this.assertApiRegistration(name, "public", schema);
-        const definition = { name, mode: "public", guards: schema.guards, rateLimit: schema.rateLimit, idempotency: schema.idempotency, input: schema.input, output: schema.output };
-        this.apiDefinitions.set(name, definition);
-        this.actionList.push({
-            match: (ctx) => ctx.apiName === name ? {} : false,
-            actionFn: (ctx, resolver) => this.runApi(ctx, resolver, definition, handler),
-        });
+        this.registerApi(name, "public", schema, handler);
         return this;
     }
     // Typed Session API with Zod
     addSessionApi(name, schema, handler) {
-        this.assertApiRegistration(name, "session", schema);
-        const definition = { name, mode: "session", guards: schema.guards, rateLimit: schema.rateLimit, idempotency: schema.idempotency, input: schema.input, output: schema.output };
+        this.registerApi(name, "session", schema, handler);
+        return this;
+    }
+    /**
+     * What registering an API is, for addApi and addSessionApi alike: the
+     * checks that can refuse it, then its definition recorded (what
+     * apiSignatures() digests) and its action appended to the first-match
+     * chain. The two public methods differ only in the mode and in the types
+     * they give the handler.
+     */
+    registerApi(name, mode, schema, handler) {
+        if (this.apiDefinitions.has(name)) {
+            throw new Error(`Lambder: duplicate API name "${name}". Dispatch is first-match, so the second registration would be silently dead code.`);
+        }
+        // Everything that can refuse the registration runs before the name is
+        // claimed below: a refusal the app catches and fixes would otherwise
+        // leave the name taken, and the retry would report a duplicate
+        // instead of the problem it was fixing.
+        if (mode === "session" && !this.pipeline.hasSessions) {
+            throw new Error(`Lambder: session API "${name}" needs the session option at creation.`);
+        }
+        const guardsRequired = mode === "session" ? this.requireSessionApiGuards : this.requirePublicApiGuards;
+        if (guardsRequired && schema.guards === undefined) {
+            const optOut = mode === "session"
+                ? "the named no-op guard that marks the session itself as the whole authorization"
+                : "the named no-op guard that records why anyone may call it";
+            throw new Error(`Lambder: ${mode} API "${name}" declares no guards, and require${mode === "session" ? "Session" : "Public"}ApiGuards is on. ` +
+                `Declare the guard that authorizes it, or ${optOut}.`);
+        }
+        const definition = { name, mode, guards: schema.guards, rateLimit: schema.rateLimit, idempotency: schema.idempotency, input: schema.input, output: schema.output };
+        this.pipeline.assertRegistration(definition);
         this.apiDefinitions.set(name, definition);
         this.actionList.push({
             match: (ctx) => ctx.apiName === name ? {} : false,
-            actionFn: (ctx, resolver) => this.runApi(ctx, resolver, definition, handler),
+            actionFn: (ctx) => this.runApi(ctx, definition, handler),
         });
-        return this;
     }
     addHook(hookEvent, hookFn, priority = 0) {
         if (hookEvent === "created") {
-            // Runs once, lazily, at the first render() call.
+            // Runs once, lazily, before the first request or event is handled.
             this.createdHooks.push(hookFn);
         }
         else {
@@ -272,11 +337,10 @@ export default class Lambder {
     // The policy generics are `any` in the plugin signature on purpose: a
     // module may annotate its parameter as the bare Lambder<SessionData> or
     // as the app's narrowed alias, and both must chain. Registration-time
-    // assertions still verify every referenced policy/guard name at runtime.
-    // Every policy generic must be listed here: one short of the class's
-    // parameter list and the missing one silently falls back to its default,
-    // which makes an instance carrying the non-default value unassignable to
-    // its own plugins.
+    // assertions still check every referenced policy/guard name. Every
+    // policy generic must be listed: a missing one falls back to its default,
+    // making an instance with a non-default value unassignable to its own
+    // plugins.
     use(plugin) {
         return plugin(this);
     }
@@ -285,9 +349,11 @@ export default class Lambder {
     // What a handler or an app asks the instance for.
     // =====================================================================
     /**
-     * Sessions for this request: what handlers create, rotate, refresh and
-     * end sessions with. An API call presents its posted CSRF token; a route
-     * presents cookies alone.
+     * A session controller for a context: what creates, rotates, refreshes
+     * and ends sessions. An API call presents its posted CSRF token; a route
+     * presents cookies alone. A context this instance renders already
+     * carries one as `ctx.sessionController`; this is for a context it did
+     * not render, such as one createContext() built from an event on its own.
      */
     getSessionController(ctx) {
         const context = ctx;
@@ -320,26 +386,24 @@ export default class Lambder {
     /**
      * Every registered endpoint's signature, keyed by its hashed name: the
      * LambderApiSignatureMap both sides ship with. A generator imports the
-     * finished instance, awaits this, and writes the result to a file the
-     * frontend passes to LambderCaller as apiSignatures and the server passes
-     * to create() as apiSignatures; at request time the pipeline compares a
-     * call's signature with the server's copy of the same map. This is the
-     * one place a digest is computed, so it has nothing to agree with but
-     * itself. Keys are sorted, so the generated file diffs by endpoint.
+     * finished instance, awaits this, and writes a file that LambderCaller
+     * and create() both take as apiSignatures; at request time the pipeline
+     * compares a call's signature with the server's copy. This is the only
+     * place a digest is computed, so there is no second computation to drift
+     * from it. Keys are sorted, so the generated file diffs by endpoint.
      */
     async apiSignatures() {
         return Object.fromEntries((await this.apiSignatureEntries()).map(({ key, signature }) => [key, signature]));
     }
     /**
-     * The same signatures with the endpoint name each one was digested from,
-     * sorted by key as the map is. What apiSignatures() leaves out on purpose:
-     * the map a client ships lists no names, so a generator that only had the
-     * map could report that four signatures changed but not which endpoints.
-     * Reading this instead, it can name them.
+     * The same signatures, sorted by key as the map is, with the endpoint
+     * name each was digested from. The map a client ships deliberately lists
+     * no names, so a generator reading only the map could say how many
+     * signatures changed but not which endpoints; this lets it name them.
      *
-     * A build-time view by construction. It comes off the server instance,
-     * which a generator imports and a client never does, so nothing here
-     * reaches a bundle unless the generator writes it there.
+     * A build-time view: it comes off the server instance, which a generator
+     * imports and a client never does, so nothing here reaches a bundle
+     * unless the generator writes it there.
      */
     async apiSignatureEntries() {
         const entries = await Promise.all([...this.apiDefinitions.values()].map(async (definition) => ({
@@ -392,32 +456,35 @@ export default class Lambder {
             })();
             this.initPromise = pending;
             // A `created` hook usually reaches something that can be briefly
-            // unavailable (a first DynamoDB read, a secret fetch). Keeping the
-            // rejected promise meant the warm container answered every later
-            // invocation with the first failure and never recovered, so the
-            // failure is forgotten and the next invocation runs the hooks
-            // again. Whoever is awaiting this one still gets the rejection.
+            // unavailable (a first DynamoDB read, a secret fetch). A kept
+            // rejection would answer every later invocation on the warm
+            // container with that first failure, so it is forgotten and the
+            // next invocation runs the hooks again. Whoever is awaiting this
+            // one still gets the rejection.
             pending.catch(() => { if (this.initPromise === pending)
                 this.initPromise = null; });
         }
         return this.initPromise;
     }
-    applyCors(ctx, response, isPreflight) {
-        applyCorsHeaders(this.corsConfig, ctx, response, isPreflight);
+    applyCors(allowedOrigin, response, isPreflight) {
+        applyCorsHeaders(this.corsConfig, allowedOrigin, response, isPreflight);
     }
     /**
      * The beforeRender hooks, in priority order: the replaced context to
      * continue with, or the response one of them answered with.
      *
-     * Its own method because BOTH request paths run it. Left inline after the
-     * match, it ran for routes and APIs and for nothing else, so a
-     * servePublicFiles or serveIndexHtml answer, which is every asset and
-     * every app-shell page, skipped the one hook that can inspect a request,
-     * replace its context or short-circuit it: a security header written in a
-     * hook reached the API answers and not the HTML it was written for, and a
-     * maintenance-mode hook served the whole frontend anyway.
+     * Its own method because both request paths run it. Run only after a
+     * match, it would skip every servePublicFiles and serveIndexHtml answer
+     * (every asset and app-shell page): a security header written in a hook
+     * would miss the HTML it was written for, and a maintenance-mode hook
+     * would still serve the whole frontend.
+     *
+     * Each replacement is also handed to `onContextReplaced` as it is made,
+     * rather than only returned: render() answers from it after the handler
+     * too (the afterRender hooks, a crash's report, reveal and global error
+     * handler), and a handler or a later hook that throws returns nothing.
      */
-    async runBeforeRenderHooks(ctx, resolver) {
+    async runBeforeRenderHooks(ctx, resolver, onContextReplaced) {
         let currentCtx = ctx;
         for (const hook of this.hookList["beforeRender"]) {
             const hookResult = await hook.hookFn(currentCtx, resolver);
@@ -425,14 +492,20 @@ export default class Lambder {
                 throw hookResult;
             if (hookResult instanceof LambderResponse)
                 return hookResult;
-            currentCtx = hookResult;
+            if (hookResult === currentCtx)
+                continue;
+            // A hook that answered with a new object (`{ ...ctx, extra }`)
+            // carries none of the tools, which are not enumerable, so they are
+            // bound again, onto the object the rest of the request uses.
+            currentCtx = bindContextTools(hookResult, this.contextTools);
+            onContextReplaced(currentCtx);
         }
         return currentCtx;
     }
-    async handleNoMatchedAction(ctx, resolver) {
+    async handleNoMatchedAction(ctx, resolver, onContextReplaced) {
         // Before the fallback hooks, and with the same power it has on a
         // matched route: the fallback hooks are typed void and cannot answer.
-        const beforeRenderResult = await this.runBeforeRenderHooks(ctx, resolver);
+        const beforeRenderResult = await this.runBeforeRenderHooks(ctx, resolver, onContextReplaced);
         if (beforeRenderResult instanceof LambderResponse)
             return beforeRenderResult;
         const currentCtx = beforeRenderResult;
@@ -443,7 +516,7 @@ export default class Lambder {
         if (isAPI) {
             if (this.apiFallbackHandler)
                 return await this.apiFallbackHandler(currentCtx, resolver);
-            return responseFromAnswer(currentCtx.api ? this.pipeline.answerUnknownApi(currentCtx.api, currentCtx) : apiNotFoundAnswer(this.apiVersion, currentCtx.logList));
+            return responseFromAnswer(currentCtx.api ? this.pipeline.answerUnknownApi(currentCtx) : apiNotFoundAnswer(this.apiVersion, currentCtx.logList));
         }
         if (this.publicFilesHandler) {
             const fileResponse = await this.publicFilesHandler.handle(currentCtx);
@@ -459,16 +532,16 @@ export default class Lambder {
     }
     /**
      * True for the OPTIONS request the CORS layer answers by itself. Asked
-     * twice: once to build the 204, once at the end of render() to decide
-     * which form of the headers goes on. Asking once and letting the tail
-     * apply the ordinary headers on top of the 204's would put both forms on
-     * a preflight, answering `Vary: Origin, Origin` and an
-     * Access-Control-Expose-Headers that means nothing before a request.
+     * twice: once to build the 204, once at the end of render() to pick which
+     * form of the headers goes on. Applying the ordinary headers on top of
+     * the 204's would put both forms on a preflight: `Vary: Origin, Origin`
+     * and an Access-Control-Expose-Headers that means nothing before a
+     * request.
      */
     isCorsPreflight(ctx) {
         return ctx.method === "OPTIONS" && !!this.corsConfig;
     }
-    async resolveRequest(ctx, resolver) {
+    async resolveRequest(ctx, resolver, onContextReplaced) {
         if (this.isCorsPreflight(ctx))
             return new LambderResponse({ statusCode: 204, body: null });
         if (ctx.api) {
@@ -496,44 +569,51 @@ export default class Lambder {
             }
         }
         if (!matched)
-            return await this.handleNoMatchedAction(ctx, resolver);
+            return await this.handleNoMatchedAction(ctx, resolver, onContextReplaced);
         // Set before the hooks run, so a beforeRender hook on a matched route
         // sees the route's own path params.
         ctx.pathParams = matched.params;
-        const beforeRenderResult = await this.runBeforeRenderHooks(ctx, resolver);
+        const beforeRenderResult = await this.runBeforeRenderHooks(ctx, resolver, onContextReplaced);
         if (beforeRenderResult instanceof LambderResponse)
             return beforeRenderResult;
         return await matched.action.actionFn(beforeRenderResult, resolver);
     }
     async render(event, lambdaContext) {
         let ctx = null;
+        let started = false;
+        // Settled as soon as the context exists and reused by every answer,
+        // the crash path's included; see allowedCorsOriginOf.
+        let allowedOrigin = null;
         try {
             await this.ensureInitialized();
-            ctx = createContext(event, lambdaContext, this.apiPath, this.trustedClientIpHeaders);
+            started = true;
+            ctx = bindContextTools(createContext(event, lambdaContext, {
+                apiPath: this.apiPath,
+                trustedClientIpHeaders: this.trustedClientIpHeaders,
+                trustedHostHeaders: this.trustedHostHeaders,
+            }), this.contextTools);
+            if (this.corsConfig)
+                allowedOrigin = allowedCorsOriginOf(this.corsConfig, ctx);
             const resolver = this.getResolver(ctx);
             let response;
             try {
-                response = await this.resolveRequest(ctx, resolver);
+                // A context a beforeRender hook hands back is the request's
+                // from then on, here as in the handler: the afterRender hooks,
+                // a thrown answer and a crash's report, reveal and global
+                // error handler all read what the hook added, and the session
+                // a session route or API read onto it.
+                response = await this.resolveRequest(ctx, resolver, (replacement) => { ctx = replacement; });
             }
             catch (err) {
-                // A thrown LambderResponse IS the response (res.die.*, throw res.html(...)).
-                if (err instanceof LambderResponse) {
-                    response = err;
-                }
-                // A thrown LambderApiRefusal on an API call IS a structured refusal
-                // (brand-checked, not instanceof, to survive duplicate installs).
-                else if (isLambderApiRefusal(err) && ctx.api) {
-                    response = this.apiErrorResponse(err, ctx);
-                }
-                else {
-                    throw err;
-                }
+                response = await this.answerThrown(err, ctx, resolver);
             }
-            // What the call wrote goes on BEFORE the hooks run, so an
+            // Everything from here writes into the response, and the object a
+            // handler answered with may be one it keeps between requests.
+            response = response.copy();
+            // What the call wrote goes on before the hooks run, so an
             // afterRender hook can override or delete a header the handler
-            // wrote: replaying the operations afterwards put the handler's
-            // value straight back, and a hook could not win an argument it
-            // was the last to speak in.
+            // wrote. Applied afterwards, it would put the handler's value
+            // straight back over the hook's.
             const responseIntoHooks = response;
             const headersAppliedIntoHooks = ctx.responseHeaders.size;
             ctx.responseHeaders.applyTo(response);
@@ -542,143 +622,183 @@ export default class Lambder {
                     const hookResponse = await hook.hookFn(ctx, resolver, response);
                     if (hookResponse instanceof Error)
                         throw hookResponse;
-                    response = hookResponse;
+                    // A response a hook answers with may be one it keeps
+                    // between requests, like a handler's, and the hooks after
+                    // it write into it: copied for the same reason.
+                    if (hookResponse !== response)
+                        response = hookResponse.copy();
                 }
             }
             catch (err) {
-                if (err instanceof LambderResponse) {
-                    response = err;
-                }
-                else if (isLambderApiRefusal(err) && ctx.api) {
-                    response = this.apiErrorResponse(err, ctx);
-                }
-                else {
-                    throw err;
-                }
+                response = (await this.answerThrown(err, ctx, resolver)).copy();
             }
             // Only what the hooks themselves wrote (res.setHeader inside a
-            // hook) is left to apply, which is what leaves their overrides
-            // standing. A hook that answered with a DIFFERENT response takes
-            // the whole set instead: headers belong to the call rather than to
-            // the response that first carried them, so the session cookie the
-            // call wrote has to travel across to it.
+            // hook) is left to apply, which leaves their overrides standing.
+            // A hook that answered with a different response takes the whole
+            // set instead: headers belong to the call, not to the response
+            // that first carried them, so the call's session cookie must
+            // reach it.
             ctx.responseHeaders.applyTo(response, response === responseIntoHooks ? headersAppliedIntoHooks : 0);
-            this.applyCors(ctx, response, this.isCorsPreflight(ctx));
+            this.applyCors(allowedOrigin, response, this.isCorsPreflight(ctx));
             return await finalizeResponse(ctx, response, this.finalizeOptions, ctx.eventFormat);
         }
         catch (err) {
-            // Describing the thrown value can itself throw: an object with a
-            // null prototype, a Proxy, or a throwing toString/Symbol.toPrimitive.
-            // Coercing it unguarded in the FIRST statement of the last-resort
-            // catch made the catch throw, so the error handler never ran, no
-            // envelope was produced, and the invocation rejected with a 502 no
-            // client could parse. coerceToError is the shared version of that
-            // care, the one every site in the framework now uses.
-            const wrappedError = coerceToError(err, "an unstringifiable thrown value");
-            this.crashWatcher?.(wrappedError);
-            // ctx may be null (createContext failed): derive the format from the raw event.
-            const eventFormat = ctx?.eventFormat ?? (isV2HttpEvent(event) ? "v2" : "v1");
-            try {
-                if (this.globalErrorHandler) {
-                    const responseBuilder = this.getResponseBuilder(ctx ?? undefined);
-                    const errorResponse = await this.globalErrorHandler(wrappedError, ctx, responseBuilder);
-                    // The same rule the success path follows: headers belong
-                    // to the call, not to the response that first carried
-                    // them. A call that wrote a session cookie and then threw
-                    // still owes the browser that cookie, and a cross-origin
-                    // caller cannot read the error at all without the CORS
-                    // headers.
-                    ctx?.responseHeaders.applyTo(errorResponse);
-                    if (ctx)
-                        this.applyCors(ctx, errorResponse, false);
-                    return await finalizeResponse(ctx, errorResponse, this.finalizeOptions, eventFormat);
-                }
+            return await this.answerCrash(err, ctx, allowedOrigin, started, event, lambdaContext);
+        }
+    }
+    /**
+     * A thrown value that is an answer rather than a crash, as the response;
+     * anything else is rethrown to the crash path.
+     *
+     * - A LambderResponse IS the response (res.die.*, throw res.html(...)).
+     * - A LambderApiRefusal on an API call is its structured refusal
+     *   (brand-checked, not instanceof, to survive duplicate installs).
+     * - A LambderSessionNotFoundError is a missing session: one that ended
+     *   while the request held it (a logout or a password change landing
+     *   mid-request), or one a route or hook asked for that the request
+     *   never had or whose cookies named several (its subclass
+     *   LambderSessionAmbiguousError). It is answered the way a missing
+     *   session is answered here, the decision the API pipeline makes for a
+     *   handler, applied to the routes and hooks it never sees.
+     */
+    async answerThrown(thrown, ctx, resolver) {
+        if (thrown instanceof LambderResponse)
+            return thrown;
+        if (isLambderApiRefusal(thrown) && ctx.api)
+            return this.apiErrorResponse(thrown, ctx);
+        if (thrown instanceof LambderSessionNotFoundError)
+            return await this.sessionMissingResponse(ctx, resolver);
+        throw thrown;
+    }
+    /**
+     * A crash, from the thrown value to the answer. It is told to the test
+     * watch and reported before anything answers, so the report depends on
+     * nothing the answer might break; then the app's global error handler
+     * answers it, or the framework's own 500 does when there is none or it
+     * failed too.
+     */
+    async answerCrash(thrown, ctx, allowedOrigin, started, event, lambdaContext) {
+        // Describing the thrown value can itself throw (a null-prototype
+        // object, a Proxy, a throwing toString/Symbol.toPrimitive). Unguarded,
+        // the crash path would throw too, no handler would run, and the
+        // invocation would reject with a 502 no client can parse.
+        const error = coerceToError(thrown, "an unstringifiable thrown value");
+        this.crashWatcher?.(error);
+        const site = !started ? { kind: "startup", lambdaContext }
+            : ctx?.api ? { kind: "api", ctx, lambdaContext }
+                : { kind: "route", ctx, lambdaContext };
+        await this.crashHandling.report(error, site);
+        // ctx may be null (createContext failed): derive the format from the raw event.
+        const eventFormat = ctx?.eventFormat ?? (isV2HttpEvent(event) ? "v2" : "v1");
+        let errorHandlerCrash = null;
+        try {
+            if (this.globalErrorHandler) {
+                const errorResponse = await this.globalErrorHandler(error, ctx, this.getResponseBuilder(ctx ?? undefined));
+                return await finalizeResponse(ctx, this.withCallHeaders(ctx, allowedOrigin, errorResponse), this.finalizeOptions, eventFormat);
             }
-            catch (handlerErr) {
-                if (handlerErr instanceof LambderResponse) {
-                    ctx?.responseHeaders.applyTo(handlerErr);
-                    if (ctx)
-                        this.applyCors(ctx, handlerErr, false);
-                    try {
-                        return await finalizeResponse(ctx, handlerErr, this.finalizeOptions, eventFormat);
-                    }
-                    catch { /* fall through */ }
+        }
+        catch (handlerErr) {
+            if (handlerErr instanceof LambderResponse) {
+                try {
+                    return await finalizeResponse(ctx, this.withCallHeaders(ctx, allowedOrigin, handlerErr), this.finalizeOptions, eventFormat);
                 }
+                catch { /* fall through */ }
+            }
+            else {
+                // A second crash, in the code meant to answer the first:
+                // reported in its own right, with the thrown value as its
+                // cause, so neither of the two disappears.
+                errorHandlerCrash = new Error("Lambder: the global error handler threw while answering a crash.", {
+                    cause: coerceToError(handlerErr, "an unstringifiable thrown value"),
+                });
+                await this.crashHandling.report(errorHandlerCrash, site);
             }
-            // Last-resort 500. API calls get the core's crash envelope so
-            // clients can parse a structured failure; everything else keeps
-            // plain text. Emitted directly rather than finalized, because
-            // finalization may be what failed. The headers still go on: they
-            // belong to the call and not to the response that first carried
-            // them, so a call that wrote a session cookie and then threw still
-            // owes the browser that cookie, and a cross-origin caller cannot
-            // read this error at all without the CORS headers. Applying them
-            // is plain object work, none of the compression, base64 or size
-            // handling that finalization does.
-            const crashResponse = ctx?.api
-                ? responseFromAnswer(crashAnswer(this.apiVersion))
-                : new LambderResponse({ statusCode: 500, body: "Internal Server Error." });
-            ctx?.responseHeaders.applyTo(crashResponse);
-            if (ctx)
-                this.applyCors(ctx, crashResponse, false);
-            return emitResponse(eventFormat, crashResponse.statusCode, crashResponse.headers, typeof crashResponse.body === "string" ? crashResponse.body : "", false);
         }
+        // Emitted directly rather than finalized, because finalization may be
+        // what failed; applying the call's headers is plain object work, none
+        // of the compression, base64 or size handling finalization does.
+        const crashResponse = this.withCallHeaders(ctx, allowedOrigin, await this.crashHandling.frameworkResponse(error, ctx, errorHandlerCrash));
+        return emitResponse(eventFormat, crashResponse.statusCode, crashResponse.headers, typeof crashResponse.body === "string" ? crashResponse.body : "", false);
+    }
+    /**
+     * An answer to a crash, carrying what the call wrote and its CORS headers.
+     * As on the success path, headers belong to the call: a call that wrote a
+     * session cookie and then threw still owes the browser that cookie, and a
+     * cross-origin caller cannot read the error at all without CORS headers.
+     * The CORS verdict is the one the request settled before it crashed, so
+     * answering a crash runs none of the app's code.
+     */
+    withCallHeaders(ctx, allowedOrigin, answer) {
+        // A copy, as on the success path: an error handler may answer with an object it keeps.
+        const response = answer.copy();
+        if (!ctx)
+            return response;
+        ctx.responseHeaders.applyTo(response);
+        this.applyCors(allowedOrigin, response, false);
+        return response;
     }
     /**
      * Fetch the session for a session route or short-circuit it with the
-     * sessionExpiredRouteHandler response (default 401). Session APIs never
-     * come through here: the pipeline answers them with the protocol's
-     * { sessionExpired: true } envelope itself.
+     * answer for a missing session. Session APIs never come through here:
+     * the pipeline answers them with the protocol's { sessionExpired: true }
+     * envelope itself.
      */
     async requireSession(ctx, resolver) {
         const session = await this.getSessionController(ctx).fetchSessionIfExists();
-        if (!session) {
-            if (this.sessionExpiredRouteHandler) {
-                throw await this.sessionExpiredRouteHandler(ctx, resolver);
-            }
-            throw resolver.status(401, "Session required.");
+        if (!session)
+            throw await this.sessionMissingResponse(ctx, resolver);
+    }
+    /**
+     * The answer to a request that needed a session and has none, whether it
+     * never had one or it ended while the request held it: an API call gets
+     * the protocol's sessionExpired envelope, as the pipeline gives a session
+     * API, and anything else the setSessionExpiredRouteHandler answer, a 401
+     * by default.
+     */
+    async sessionMissingResponse(ctx, resolver) {
+        if (ctx.api)
+            return responseFromAnswer(sessionExpiredAnswer(this.apiVersion, ctx.logList));
+        if (!this.sessionExpiredRouteHandler)
+            return resolver.status(401, "Session required.");
+        try {
+            return await this.sessionExpiredRouteHandler(ctx, resolver);
+        }
+        catch (err) {
+            // It may answer by throwing, as any handler may.
+            if (err instanceof LambderResponse)
+                return err;
+            throw err;
         }
     }
-    /** Dispatch a non-HTTP Lambda event to the registered actions. */
+    /**
+     * Dispatch a non-HTTP Lambda event to the registered actions. What an
+     * action throws is reported (crashes.report) and then rethrown untouched,
+     * so Lambda's retries and dead-letter queues still see the failure.
+     */
     async renderEvent(event, lambdaContext) {
-        await this.ensureInitialized();
-        for (const action of this.eventActionList) {
-            if (action.match(event)) {
-                return await action.actionFn(event, lambdaContext);
+        let started = false;
+        try {
+            await this.ensureInitialized();
+            started = true;
+            for (const action of this.eventActionList) {
+                if (action.match(event)) {
+                    return await action.actionFn(event, lambdaContext);
+                }
             }
+            const summary = event && typeof event === "object"
+                ? ` (source: ${String(event.source ?? "?")}, detail-type: ${String(event["detail-type"] ?? "?")})`
+                : "";
+            throw new Error(`Lambder: no action matched non-HTTP event${summary}. Register one with addAction(); a trailing addAction(() => true, ...) acts as a fallback.`);
+        }
+        catch (err) {
+            await this.crashHandling.report(coerceToError(err, "an unstringifiable thrown value"), started ? { kind: "event", event, lambdaContext } : { kind: "startup", lambdaContext });
+            throw err;
         }
-        const summary = event && typeof event === "object"
-            ? ` (source: ${String(event.source ?? "?")}, detail-type: ${String(event["detail-type"] ?? "?")})`
-            : "";
-        throw new Error(`Lambder: no action matched non-HTTP event${summary}. Register one with addAction(); a trailing addAction(() => true, ...) acts as a fallback.`);
     }
     // =====================================================================
     // The API path
     // The steps only an API call takes, around the shared core.
     // =====================================================================
-    /** Registration-time checks shared by addApi/addSessionApi. */
-    assertApiRegistration(name, mode, options) {
-        if (this.apiDefinitions.has(name)) {
-            throw new Error(`Lambder: duplicate API name "${name}". Dispatch is first-match, so the second registration would be silently dead code.`);
-        }
-        // Everything that can refuse this registration runs before the name is
-        // claimed. Claiming it first meant a caught registration error burned
-        // the name, and the retry reported a duplicate instead of the problem
-        // the app was fixing; the session check was still on the far side of
-        // that line, one method down in addSessionApi.
-        if (mode === "session" && !this.pipeline.hasSessions) {
-            throw new Error(`Lambder: session API "${name}" needs the session option at creation.`);
-        }
-        const guardsRequired = mode === "session" ? this.requireSessionApiGuards : this.requirePublicApiGuards;
-        if (guardsRequired && options.guards === undefined) {
-            const optOut = mode === "session"
-                ? "the named no-op guard that marks the session itself as the whole authorization"
-                : "the named no-op guard that records why anyone may call it";
-            throw new Error(`Lambder: ${mode} API "${name}" declares no guards, and require${mode === "session" ? "Session" : "Public"}ApiGuards is on. ` +
-                `Declare the guard that authorizes it, or ${optOut}.`);
-        }
-        this.pipeline.assertRegistration({ name, mode, guards: options.guards, rateLimit: options.rateLimit, idempotency: options.idempotency });
-    }
     /**
      * The answer for a rejected input: the app's
      * setApiInputValidationErrorHandler when set, otherwise the standard 422
@@ -699,12 +819,14 @@ export default class Lambder {
      * via res.die.*) becomes the answer the pipeline stores and hands back.
      * The context is the pipeline's context, so a session it fetched is on
      * ctx.session and the validated payload is on ctx.apiPayload when the
-     * handler runs.
+     * handler runs. The handler's resolver knows the API's output schema, so
+     * every success payload is parsed through it before it is sent.
      */
-    async runApi(ctx, resolver, definition, handler) {
+    async runApi(ctx, definition, handler) {
         const request = ctx.api;
         if (!request)
             throw new Error(`Lambder: API "${definition.name}" was matched by a request that is not an API call.`);
+        const resolver = new LambderResolver({ files: this.files, apiVersion: this.apiVersion, ctx, apiOutput: definition.output });
         // What the handler produced, in both forms: the answer went to the
         // pipeline, and the response is kept so it can carry on unchanged.
         const handled = { output: null };
@@ -725,13 +847,13 @@ export default class Lambder {
             handled.output = { response, answer: answerFromResponse(response) };
             return handled.output.answer;
         });
-        // The handler's own response carries on when the pipeline answered
-        // with it, rather than a rebuild of its answer. An answer holds a
-        // Buffer body base64-encoded, because that is the plain shape the
-        // idempotency store persists, and rebuilding a response from that
-        // would hand finalization a base64 string it must pass through
-        // uncompressed. Identity is what settles it: the pipeline may have
-        // answered with a stored replay or a refusal instead.
+        // When the pipeline answered with the handler's own answer, its
+        // response carries on rather than a rebuild. An answer holds a Buffer
+        // body base64-encoded (the plain shape the idempotency store
+        // persists), and a response rebuilt from it would hand finalization a
+        // base64 string it must pass through uncompressed. Identity decides,
+        // since the pipeline may have answered with a stored replay or a
+        // refusal instead.
         if (handled.output?.answer === answer)
             return handled.output.response;
         return responseFromAnswer(answer);
@@ -743,11 +865,10 @@ export default class Lambder {
 }
 /**
  * The canonical way to create an instance: fix the session data type first,
- * then create with the full configuration in one declaration; the policy,
- * guard, and idempotency types are INFERRED from the options, so the
- * instance is born fully typed and `typeof lambderApp` is the annotation
- * type for api modules. No enable/define chain exists, so there are no
- * ordering rules and nothing can be half-configured.
+ * then create with the full configuration in one declaration. The policy,
+ * guard and idempotency types are inferred from the options, so the instance
+ * is born fully typed and `typeof lambderApp` is the annotation type for api
+ * modules. There are no ordering rules, and nothing can be half-configured.
  *
  * ```typescript
  * // app.ts (imports no api modules, so modules can import the type back)
@@ -768,15 +889,14 @@ export default class Lambder {
  * export const handler = lambder.getHandler();
  * ```
  *
- * Why curried (`initLambder<S>().create(...)` rather than
- * `new Lambder<S>(...)`): TypeScript type arguments are all-or-nothing per
- * call, so explicitly passing the session data type to the constructor
- * would silently WIDEN the inferred policy and guard types to their {}
- * defaults. Fixing the session type in the first call lets the second call
- * infer everything else from the options. `new Lambder(options)` remains
- * for untyped or session-data-free instances.
+ * Curried because TypeScript type arguments are all-or-nothing per call:
+ * passing the session data type to `new Lambder<S>(...)` would silently
+ * widen the inferred policy and guard types to their {} defaults. Fixing the
+ * session type in the first call lets the second infer everything else.
+ * `new Lambder(options)` serves untyped or session-data-free instances.
  */
 export const initLambder = () => ({
+    ...policyBuildersFor(),
     create(options) {
         return new Lambder(options);
     },