lambder 11.1.1 → 13.0.1

package/dist/core/LambderCallSummary.d.ts

@@ -0,0 +1,43 @@
+import type { LambderCallOutcome } from "../shared/wire/LambderCallOutcome.js";
+/**
+ * One API call as its summary line records it: what was called, how it
+ * ended, how long it took, and the ids that join it to the rest of the
+ * logs. Nothing from the call's input, its session, its cookies or its
+ * caller's address is in it, so the line can be kept and queried as long as
+ * the app likes.
+ */
+export type LambderCallSummary = {
+    /** Always "lambder.call": what a log query picks the lines out by. */
+    kind: "lambder.call";
+    /** The endpoint the call's path named (`group.action`), whether or not one is registered under it. */
+    api: string;
+    /** How the call ended; see LambderCallOutcome. */
+    outcome: LambderCallOutcome;
+    /** The refusal's code, the framework's (`lambder/rate-limited`) or the app's; null when the answer carries none. */
+    code: string | null;
+    /** The HTTP status the call was answered with. */
+    status: number;
+    /** From the invocation's start to the answer, in milliseconds. */
+    durationMs: number;
+    /** How long the API handler itself ran, in milliseconds; null when it did not run (refused before it, or replayed). */
+    handlerMs: number | null;
+    /** True when a stored idempotent answer was replayed and no handler ran. */
+    replayed: boolean;
+    /** True on the first invocation of this process, whose duration includes loading the app. */
+    coldStart: boolean;
+    /** The invocation's request id, the one Lambda's own log lines for it carry. */
+    requestId: string | null;
+    /** The request id of the invocation that called this one over a direct invoke (LambderInvokeCaller), which carries it; null otherwise. */
+    parentRequestId: string | null;
+};
+/**
+ * Where the summaries go: the default writes each as one JSON line on
+ * stdout, where a Lambda function's log group keeps it and CloudWatch Logs
+ * Insights reads its fields without a parse step; a function receives each
+ * instead; false writes none.
+ */
+export type LambderCallSummaryOption = false | ((summary: LambderCallSummary) => void);
+/** One JSON line on stdout, written directly rather than through console.log, which on Lambda prefixes a timestamp and a level that would stop the line reading as JSON. */
+export declare const writeCallSummaryLine: (summary: LambderCallSummary) => void;
+/** Milliseconds as the line records them: to a tenth, which is finer than a call can be told apart by and keeps the line short. */
+export declare const roundedMilliseconds: (milliseconds: number) => number;

package/dist/core/LambderCallSummary.js

@@ -0,0 +1,10 @@
+/** One JSON line on stdout, written directly rather than through console.log, which on Lambda prefixes a timestamp and a level that would stop the line reading as JSON. */
+export const writeCallSummaryLine = (summary) => {
+    const line = `${JSON.stringify(summary)}\n`;
+    if (typeof process !== "undefined" && typeof process.stdout?.write === "function")
+        process.stdout.write(line);
+    else
+        console.log(line.trimEnd());
+};
+/** Milliseconds as the line records them: to a tenth, which is finer than a call can be told apart by and keeps the line short. */
+export const roundedMilliseconds = (milliseconds) => Math.round(milliseconds * 10) / 10;

package/dist/core/LambderContext.d.ts

@@ -25,7 +25,7 @@ export declare const isV2HttpEvent: (event: unknown) => event is APIGatewayProxy
  * clearCookie) that write onto whatever answer the request ends with.
  *
  * TRateLimitPolicies is the app's policies map on a handler registered with
- * addApi, addSessionApi, addRoute or addSessionRoute, so a policy name is
+ * defineApi, addRoute or addSessionRoute, so a policy name is
  * checked where it is charged; anywhere else (a hook, a guard) the names are
  * any string.
  */
@@ -147,6 +147,17 @@ export type LambderContextTools = {
  * again by the instance on whatever context a beforeRender hook hands back.
  */
 export declare const bindContextTools: (ctx: Omit<LambderRenderContext, LambderContextToolName> | LambderRenderContext, tools: LambderContextTools) => LambderRenderContext;
+/**
+ * Proof that a request came through the proxy in front of the app: a header
+ * the proxy sets to a secret on every request it forwards, which a request
+ * sent to the origin directly cannot carry. See `originProof` at create().
+ */
+export type LambderOriginProof = {
+    /** The header the proxy sets, such as "x-origin-proof". */
+    header: string;
+    /** The values it may carry: the current secret, and during a rotation the one before it. */
+    secrets: readonly string[];
+};
 /** What createContext reads a request with: the instance's own settings for where an API call goes and which forwarded headers it trusts. */
 export type LambderContextOptions = {
     /** See `apiPath` at create(). Default: "/api", as there. */
@@ -155,7 +166,9 @@ export type LambderContextOptions = {
     trustedClientIpHeaders?: readonly string[];
     /** See `trustedHostHeaders` at create(). Default: none. */
     trustedHostHeaders?: readonly string[];
+    /** See `originProof` at create(). Default: none, so the trusted headers are read on every request. */
+    originProof?: LambderOriginProof | null;
 };
 /** The render context for one request: everything a route handler, an API handler, a hook or a guard reads about it, built once from the Lambda event. */
-export declare const createContext: (event: LambderHttpEvent, lambdaContext: Context, { apiPath, trustedClientIpHeaders, trustedHostHeaders }?: LambderContextOptions) => LambderRenderContext;
+export declare const createContext: (event: LambderHttpEvent, lambdaContext: Context, { apiPath, trustedClientIpHeaders, trustedHostHeaders, originProof }?: LambderContextOptions) => LambderRenderContext;
 export {};

package/dist/core/LambderContext.js

@@ -1,5 +1,7 @@
 import { readApiEnvelope, cookieValuesByName, isApiCallContentType, lowercaseHeaderNames } from "../api/LambderApiRequest.js";
+import { apiNameOfCallPath } from "../shared/wire/LambderApiNames.js";
 import { resolveClientIp } from "../shared/util/LambderClientIp.js";
+import { constantTimeEquals } from "../shared/util/LambderTextDigest.js";
 import { base64ToText } from "../shared/util/LambderBase64.js";
 import { LambderAnswerHeaders } from "../shared/wire/LambderAnswerHeaders.js";
 import { DEFAULT_API_PATH } from "../shared/wire/LambderDefaultApiPath.js";
@@ -68,7 +70,7 @@ const withoutStagePrefix = (path, stage) => stage && stage !== "$default" && (pa
     ? path.slice(stage.length + 1) || "/"
     : path;
 /** The render context for one request: everything a route handler, an API handler, a hook or a guard reads about it, built once from the Lambda event. */
-export const createContext = (event, lambdaContext, { apiPath = DEFAULT_API_PATH, trustedClientIpHeaders = [], trustedHostHeaders = [] } = {}) => {
+export const createContext = (event, lambdaContext, { apiPath = DEFAULT_API_PATH, trustedClientIpHeaders = [], trustedHostHeaders = [], originProof = null } = {}) => {
     // Normalize the two API Gateway payload formats into one shape.
     const eventFormat = isV2HttpEvent(event) ? "v2" : "v1";
     let host;
@@ -81,7 +83,7 @@ export const createContext = (event, lambdaContext, { apiPath = DEFAULT_API_PATH
     let get;
     let cookiePairs;
     let sourceIp;
-    const headers = event.headers ?? {};
+    let headers = event.headers ?? {};
     if (isV2HttpEvent(event)) {
         host = headers.host || event.requestContext.domainName || "";
         const apiId = event.requestContext.apiId;
@@ -126,6 +128,19 @@ export const createContext = (event, lambdaContext, { apiPath = DEFAULT_API_PATH
     for (const [name, values] of Object.entries(cookieList))
         cookie[name] = values[0];
     const lowercasedHeaders = lowercaseHeaderNames(headers);
+    // The origin proof is read, then taken off the headers the app reads
+    // (ctx.headers, ctx.header()), so no handler, hook or log of them meets
+    // the secret; the raw event keeps it. A request that does not carry it
+    // came to the origin some other way than through the proxy, and the
+    // proxy's headers on it are whatever its sender wrote.
+    let proven = true;
+    if (originProof) {
+        const proofHeader = originProof.header.toLowerCase();
+        const presented = lowercasedHeaders[proofHeader] ?? "";
+        proven = originProof.secrets.some((secret) => constantTimeEquals(presented, secret));
+        delete lowercasedHeaders[proofHeader];
+        headers = Object.fromEntries(Object.entries(headers).filter(([name]) => name.toLowerCase() !== proofHeader));
+    }
     const header = (name) => lowercasedHeaders[name.toLowerCase()];
     // A trusted forwarding header is trusted because a proxy in front of this
     // function writes it. A direct invoke has no such proxy: its headers are
@@ -134,19 +149,20 @@ export const createContext = (event, lambdaContext, { apiPath = DEFAULT_API_PATH
     // address and the host are the ones the invoker named (clientIp and host,
     // delivered as sourceIp and Host), and no header is read for either.
     const invokedDirectly = event.requestContext?.apiId === LAMBDER_INVOKE_API_ID;
+    const readsForwarding = proven && !invokedDirectly;
     // The first trusted header carrying a well-formed host, leftmost entry,
     // else the host the gateway saw. Behind CloudFront a Function URL sees
     // its own lambda-url domain, since CloudFront sends an origin its own
     // Host, so cookie domains and host routing need the viewer's host from a
     // header the distribution writes.
-    for (const name of invokedDirectly ? [] : trustedHostHeaders) {
+    for (const name of readsForwarding ? trustedHostHeaders : []) {
         const forwarded = (lowercasedHeaders[name.toLowerCase()] ?? "").split(",")[0].trim();
         if (HOST_VALUE_PATTERN.test(forwarded)) {
             host = forwarded;
             break;
         }
     }
-    const ip = resolveClientIp(lowercasedHeaders, sourceIp, invokedDirectly ? [] : trustedClientIpHeaders);
+    const ip = resolveClientIp(lowercasedHeaders, sourceIp, readsForwarding ? trustedClientIpHeaders : []);
     // Decode body: keep the raw string, then parse as JSON with urlencoded fallback.
     const rawBody = event.isBase64Encoded
         ? (event.body ? base64ToText(event.body) : "")
@@ -162,13 +178,20 @@ export const createContext = (event, lambdaContext, { apiPath = DEFAULT_API_PATH
             post[key] = value;
         }
     }
-    // A JSON POST to the API path whose body names an API is an API call;
+    // A JSON POST to `{apiPath}/{group}/{action}` is a call to that endpoint;
     // the core reads the envelope, and everything downstream reads ctx.api.
     // JSON only (isApiCallContentType): any site can submit a plain HTML form
-    // to this path, and enctype="text/plain" lays out a JSON body exactly.
-    const api = method === "POST" && !!apiPath && path === apiPath && isApiCallContentType(lowercasedHeaders)
-        ? readApiEnvelope(post, { headers: lowercasedHeaders, cookies: cookieList, ip, host })
-        : null;
+    // to this path, and enctype="text/plain" lays out a JSON body exactly. A
+    // JSON POST to apiPath itself whose body names an endpoint comes from a
+    // page built before endpoints had paths, and is read as a call on the
+    // retired path, which the core answers with versionExpired.
+    const isJsonPost = method === "POST" && !!apiPath && isApiCallContentType(lowercasedHeaders);
+    const calledName = isJsonPost ? apiNameOfCallPath(apiPath, path) : null;
+    const requestInfo = { headers: lowercasedHeaders, cookies: cookieList, ip, host };
+    const api = calledName !== null ? readApiEnvelope(post, requestInfo, calledName)
+        : isJsonPost && path === apiPath && typeof post.apiName === "string" && post.apiName !== ""
+            ? readApiEnvelope(post, requestInfo, post.apiName, { retiredPath: true })
+            : null;
     return bindContextTools({
         host, path, rawPath, pathParams: {}, method,
         get, post, cookie, cookieList, event,

package/dist/core/LambderCreateOptions.d.ts

@@ -4,7 +4,8 @@ import type { Context } from "aws-lambda";
 import type LambderResolver from "./LambderResolver.js";
 import type LambderResponseBuilder from "./LambderResponseBuilder.js";
 import type { LambderResponse, LambderHttpResponse, LambderResponseCompressionOption, LambderResponseCompressionSettings } from "./LambderResponse.js";
-import type { LambderRenderContext, LambderSessionRenderContext, LambderHttpEvent } from "./LambderContext.js";
+import type { LambderRenderContext, LambderSessionRenderContext, LambderHttpEvent, LambderOriginProof } from "./LambderContext.js";
+import type { LambderCallSummaryOption } from "./LambderCallSummary.js";
 import type { LambderFilesOption } from "./LambderFiles.js";
 import type { LambderCorsConfig } from "./LambderCors.js";
 import type { LambderSessionDataRefreshConfig } from "../session/LambderSessionManager.js";
@@ -112,26 +113,8 @@ export type LambderHandler = {
     (event: LambderHttpEvent, context: Context): Promise<LambderHttpResponse>;
     (event: unknown, context: Context): Promise<unknown>;
 };
-/**
- * One map of named declarations, or a list of them. An app made of parts,
- * each declaring its own guards or rate-limit policies beside its APIs, hands
- * create() the list, and the instance declares every name in it. A name two
- * maps declare is refused rather than one quietly replacing the other.
- */
-export type LambderNamedMapsOption<TMap> = TMap | readonly TMap[];
-/** The one map a named-maps option declares: a list's members intersected, a lone map as it is. */
-export type LambderMergedNamedMaps<T> = T extends readonly [] ? {} : T extends readonly [infer TFirst, ...infer TRest] ? TFirst & LambderMergedNamedMaps<TRest> : T extends readonly (infer TMember)[] ? TMember : T;
-/** The names a list declares in more than one of its maps: never for a lone map, or for a list whose members are not known one by one. */
-type LambderRepeatedNames<T, TSeen extends PropertyKey = never> = T extends readonly [infer TFirst, ...infer TRest] ? (keyof TFirst & TSeen) | LambderRepeatedNames<TRest, TSeen | keyof TFirst> : never;
-/** Intersected onto a list: a name declared in two of its maps is a compile error, and the property name is the message. */
-type LambderNoRepeatedNames<T> = [LambderRepeatedNames<T>] extends [never] ? unknown : {
-    readonly "lambder: a name is declared in more than one of these maps. Declare each guard and each rate-limit policy once.": LambderRepeatedNames<T>;
-};
-/**
- * A named-maps option as one map: a lone map as it is, a list merged in
- * order. A name declared in two maps of the list is refused.
- */
-export declare const mergeNamedMaps: <TMap extends Record<string, unknown>>(option: LambderNamedMapsOption<TMap>, what: "guard" | "rate-limit policy") => TMap;
+export { mergeNamedMaps, type LambderMergedNamedMaps, type LambderNamedMapsOption } from "../shared/util/LambderNamedMaps.js";
+import type { LambderNamedMapsOption, LambderNoRepeatedNames } from "../shared/util/LambderNamedMaps.js";
 /** Session configuration (the `session` option of create/new): where sessions rest, and how their cookies are scoped. */
 export type LambderSessionOptions<TSessionData = any> = {
     /**
@@ -155,6 +138,15 @@ export type LambderSessionOptions<TSessionData = any> = {
     /** Session cookie names. Defaults: LMDRSESSIONTKID / LMDRSESSIONCSTK. */
     tokenCookieKey?: string;
     csrfCookieKey?: string;
+    /** Hashing and randomness for the session tokens. Default: WebCrypto. */
+    crypto?: LambderSessionCrypto;
+} & ({
+    /** The schema of session.data, checked on every read; data that does not match ends the session. See LambderSessionDataOptions. */
+    dataSchema?: z.ZodType<TSessionData>;
+    dataRefresh?: undefined;
+} | {
+    /** The schema of session.data, checked on every read and on every refresh's output; data that does not match refreshes at once. Required beside dataRefresh. See LambderSessionDataOptions. */
+    dataSchema: z.ZodType<TSessionData>;
     /**
      * Opt-in freshness for session.data derived from external state (roles,
      * permissions, feature flags...). Every session read renews data past
@@ -163,17 +155,15 @@ export type LambderSessionOptions<TSessionData = any> = {
      * end the session. See LambderSessionDataRefreshConfig for the exact
      * semantics.
      */
-    dataRefresh?: LambderSessionDataRefreshConfig<TSessionData>;
-    /** Hashing and randomness for the session tokens. Default: WebCrypto. */
-    crypto?: LambderSessionCrypto;
-};
+    dataRefresh: LambderSessionDataRefreshConfig<TSessionData>;
+});
 /** One map of the server's guards, each pinned to the render contexts of the app's session type. */
 export type LambderGuardsMap<TSessionData = any> = Record<string, LambderApiGuard<any, any, any, LambderRenderContext<any, Record<string, string>, {}, TSessionData>, LambderSessionRenderContext<any, TSessionData>>>;
 /** One map of the server's rate-limit policies. */
 export type LambderRateLimitPoliciesMap = Record<string, LambderApiRateLimitPolicyConfig<LambderRenderContext>>;
 /** The `rateLimits` option of create(): the engine's config, with `policies` as one map or a list of maps. */
 export type LambderCreateRateLimitsOption = Omit<LambderApiRateLimitsConfig<LambderRateLimitPoliciesMap>, "policies"> & {
-    /** Named policies referenced (typed) from addApi/addSessionApi: one map, or a list of maps merged in order. */
+    /** Named policies referenced (typed) from defineApi: one map, or a list of maps merged in order. */
     policies: LambderNamedMapsOption<LambderRateLimitPoliciesMap>;
 };
 /** The options as the instance holds them: the guards and the rate-limit policies merged into one map each. */
@@ -274,9 +264,41 @@ export type LambderCreateOptions<TSessionData = any> = {
      * invoker's `host`.
      */
     trustedHostHeaders?: readonly string[];
+    /**
+     * Proof that a request came through the proxy the trusted headers are
+     * trusted for: `{ header, secrets }`, a header the proxy sets on every
+     * request it forwards (a Cloudflare transform rule, a CloudFront origin
+     * custom header) and the secret it carries, with the previous one beside
+     * it during a rotation. The trusted client address and host headers are
+     * read only from a request that carries it. One sent to the origin
+     * directly (an API Gateway's own execute-api URL, a Function URL) has
+     * its address and host from the gateway, whatever headers it wrote, so
+     * a `per: "ip"` limit counts it by the address it really came from. The
+     * header is taken off `ctx.headers` and `ctx.header()`, so no handler or
+     * hook meets the secret. Default: none, so the trusted headers are read
+     * on every request, which is right only for an origin nothing but the
+     * proxy can reach.
+     */
+    originProof?: LambderOriginProof;
+    /**
+     * One summary per API call, written when the call is answered: the
+     * endpoint, how it ended (success, a refusal and its code, a flag, a
+     * validation refusal, a crash), the status, the duration and the
+     * handler's own time, whether an idempotent answer was replayed, whether
+     * the invocation was the process's first, and its request id with the
+     * id of the invocation that called it over invoke. Nothing from the
+     * input, the session, the cookies or the caller's address. See
+     * LambderCallSummary.
+     *
+     * Default: each summary as one JSON line on stdout, which a Lambda
+     * function's log group keeps and CloudWatch Logs Insights reads field by
+     * field. A function receives each summary instead (another logger, a
+     * metrics client); false writes none.
+     */
+    callSummary?: LambderCallSummaryOption;
     /** CORS: true allows any origin; or pass a LambderCorsConfig. Default: off. */
     cors?: boolean | LambderCorsConfig;
-    /** Sessions over a store of your choosing; required for addSessionApi/addSessionRoute. */
+    /** Sessions over a store of your choosing; required for a guard that needs a session, and for addSessionRoute. */
     session?: LambderSessionOptions<TSessionData>;
     /**
      * Declarative per-API rate limiting: your limiter plus named policies APIs
@@ -318,58 +340,50 @@ export type LambderCreateOptions<TSessionData = any> = {
      */
     requireRefusalCodes?: boolean;
     /**
-     * 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 whose session 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;
-    /**
-     * The same for public APIs: every addApi must declare `guards`, at the
-     * type level and at registration.
+     * Make an authorization declaration part of declaring an endpoint: every
+     * defineApi must declare `guards`, at the type level (a missing `guards`
+     * is a compile error) and at registration (a plain-JS caller throws).
      *
-     * Public APIs are open by default, which is the right default, so this is
-     * off unless an app decides otherwise. Turned on, a public endpoint's
-     * openness becomes a written decision rather than an omission: the ones
-     * anybody may call declare a named no-op guard carrying the reason, and
-     * the ones that authorize their caller some other way (a signature, a
-     * device secret, a one-shot token) name where that happens. One grep over
-     * the guard names then lists every public door and why it is open. Needs
-     * a guards map to pick from. Default: false.
+     * An endpoint is open by default, which is the right default, so this is
+     * off unless an app decides otherwise. Turned on, every endpoint's
+     * authorization becomes a written decision rather than an omission: one
+     * anybody may call declares a named no-op guard carrying the reason, one
+     * whose session is the whole authorization (the signed-in user's own
+     * account) a named no-op session guard, and one that authorizes its
+     * caller some other way (a signature, a device secret, a one-shot token)
+     * names where that happens. One grep over the guard names then lists
+     * every door and why it opens. Needs a guards map to pick from. Default:
+     * false.
      */
-    requirePublicApiGuards?: boolean;
+    requireApiGuards?: boolean;
     /** Declarative idempotency: your store plus replay defaults; APIs opt in via `idempotency: true | { ttlSeconds }`. */
     idempotency?: LambderApiIdempotencyConfig;
     /** Crash reporting on every path, and who may read a crash in the answer. See LambderCrashOptions. */
     crashes?: LambderCrashOptions;
 };
 /**
- * What the `guards` field asks for when an API on a require*ApiGuards
+ * What the `guards` field asks for when an API on a requireApiGuards
  * instance declares none. With nothing to infer from, the inference parameter
  * defaults to `never`, and "Property 'guards' is missing ... but required in
  * type { guards: never }" would read as though nothing could be written
  * there; the property name says what is wanted.
  */
 type LambderGuardsDeclarationRequired = {
-    readonly "lambder: this instance requires every API of this kind to declare guards. Name the guard that authorizes this API, or the named no-op guard that records why anyone may call it.": never;
+    readonly "lambder: this instance requires every API to declare guards. Name the guard that authorizes this API, or the named no-op guard that records why it needs nothing more.": never;
 };
 /**
- * What addSessionApi and addSessionRoute need of the instance they are called
- * on. Nothing satisfies it without the session option, so registering a
- * session API on an instance that has no sessions is a compile error rather
- * than only the registration-time throw.
+ * What addSessionRoute needs of the instance it is called on. Nothing
+ * satisfies it without the session option, so registering a session route
+ * on an instance that has no sessions is a compile error rather than only a
+ * throw when it is first requested.
  */
 type LambderSessionOptionRequired = {
-    readonly "lambder: sessions are not configured on this instance. Pass the session option to create() before registering a session API or a session route.": never;
+    readonly "lambder: sessions are not configured on this instance. Pass the session option to create() before registering a session route.": never;
 };
 /**
- * Intersected into what addSessionApi and addSessionRoute take, so an
- * instance created without the session option refuses the registration at
- * the call site. `unknown` once sessions are configured, which intersects
- * away to nothing.
+ * Intersected into what addSessionRoute takes, so an instance created
+ * without the session option refuses the registration at the call site.
+ * `unknown` once sessions are configured, which intersects away to nothing.
  */
 export type LambderSessionEnabledInstance<TSessionsEnabled extends boolean> = TSessionsEnabled extends true ? unknown : LambderSessionOptionRequired;
 /**
@@ -412,11 +426,8 @@ type LambderRateLimitSliceCheck<TLacking> = [TLacking] extends [never] ? unknown
 };
 /**
  * The `guards` field of an API's options: optional by default, required once
- * create() received the require*ApiGuards flag for that kind of API, so that
- * an authorization declaration cannot be forgotten at the type level.
- *
- * One type for both kinds: the requirement is the same shape either way, and
- * only which flag switches it on differs.
+ * create() received requireApiGuards, so that an authorization declaration
+ * cannot be forgotten at the type level.
  */
 export type LambderRequirableGuardsField<TRequired extends boolean, TGuardsOpt> = TRequired extends true ? {
     /** Named guards, run in declared order before input validation (after it for a guard declared runAt: "afterInputValidation"): a name, a non-empty list of names, or a non-empty { name: param } map for parameterized guards. Required on this instance: an API that needs no authorization declares a named no-op guard, so every opt-out is explicit and one grep lists them all. Their input requirements merge into this API's contract input; their return values land typed on ctx.guardData. */
@@ -485,6 +496,7 @@ export type LambderNestedOptionChecks<TSessionData, TOptions extends LambderCrea
     };
     idempotency?: LambderNoExtraKeys<NonNullable<TOptions["idempotency"]>, LambderOptionShape<TSessionData, "idempotency">>;
     crashes?: LambderNoExtraKeys<NonNullable<TOptions["crashes"]>, LambderOptionShape<TSessionData, "crashes">>;
+    originProof?: LambderNoExtraKeys<NonNullable<TOptions["originProof"]>, LambderOptionShape<TSessionData, "originProof">>;
     rateLimits?: LambderNoExtraKeys<NonNullable<TOptions["rateLimits"]>, LambderOptionShape<TSessionData, "rateLimits">> & {
         policies?: LambderRateLimitPolicyChecks<NonNullable<TOptions["rateLimits"]>["policies"]>;
     };
@@ -504,3 +516,5 @@ export type LambderNestedOptionChecks<TSessionData, TOptions extends LambderCrea
  * response (maxResponseBytes: 0) that an app discovers in production.
  */
 export declare const assertCreateOptions: (options: LambderMergedCreateOptions<any>) => void;
+/** Shortest secret an origin proof takes: one a sender could guess is no proof. 32 characters of hex or base64 is 128 bits or more. */
+export declare const MIN_ORIGIN_PROOF_SECRET_LENGTH = 32;

package/dist/core/LambderCreateOptions.js

@@ -1,23 +1,13 @@
 import { assertRefusalCodesDeclared, readRefusalVocabulary } from "../api/LambderApiRefusals.js";
 import { assertPositiveInteger } from "../shared/util/LambderOptionChecks.js";
-/**
- * A named-maps option as one map: a lone map as it is, a list merged in
- * order. A name declared in two maps of the list is refused.
- */
-export const mergeNamedMaps = (option, what) => {
-    if (!Array.isArray(option))
-        return option;
-    const merged = {};
-    for (const map of option) {
-        for (const [name, declaration] of Object.entries(map)) {
-            if (Object.prototype.hasOwnProperty.call(merged, name)) {
-                throw new Error(`Lambder: the ${what} "${name}" is declared in two of the maps given to create(). Declare each name once.`);
-            }
-            merged[name] = declaration;
-        }
-    }
-    return merged;
-};
+// ---------------------------------------------------------------------------
+// Named maps: the guards and the rate-limit policies, each declared in one
+// map or in a list of maps (one per part of an app), merged in order.
+// ---------------------------------------------------------------------------
+// The named-maps option (one map, or a list of them) lives with the shared
+// utilities, since the refusal vocabulary takes it too; re-exported here,
+// where its users import it.
+export { mergeNamedMaps } from "../shared/util/LambderNamedMaps.js";
 /**
  * Everything create() refuses before an instance exists, in one place: a
  * value that cannot work is a startup error naming the option, not a 404 on
@@ -53,8 +43,36 @@ export const assertCreateOptions = (options) => {
     if (options.requireRefusalCodes && !vocabulary) {
         throw new Error("Lambder: requireRefusalCodes needs a refusals vocabulary to name codes from; declare one with initLambder().declareRefusals().");
     }
-    if ((options.requireSessionApiGuards || options.requirePublicApiGuards) && !options.guards) {
-        const requireFlag = options.requireSessionApiGuards ? "requireSessionApiGuards" : "requirePublicApiGuards";
-        throw new Error(`Lambder: ${requireFlag} needs a guards map at creation for APIs to declare from.`);
+    if (options.requireApiGuards && !options.guards) {
+        throw new Error("Lambder: requireApiGuards needs a guards map at creation for APIs to declare from.");
+    }
+    if (options.originProof !== undefined)
+        assertOriginProof(options);
+    if (options.callSummary !== undefined && options.callSummary !== false && typeof options.callSummary !== "function") {
+        throw new Error("Lambder: callSummary is false, or a function that receives each call's summary.");
+    }
+};
+/** Shortest secret an origin proof takes: one a sender could guess is no proof. 32 characters of hex or base64 is 128 bits or more. */
+export const MIN_ORIGIN_PROOF_SECRET_LENGTH = 32;
+/** An origin proof that proves something: a header name, secrets long enough not to guess, and trusted headers for it to guard. */
+const assertOriginProof = (options) => {
+    const proof = options.originProof;
+    if (typeof proof?.header !== "string" || !/^[A-Za-z0-9-]+$/.test(proof.header)) {
+        throw new Error("Lambder: originProof.header must be a header name, such as \"x-origin-proof\".");
+    }
+    if (!Array.isArray(proof.secrets) || proof.secrets.length === 0) {
+        throw new Error("Lambder: originProof.secrets must list the secret the proxy sets, with the previous one beside it during a rotation.");
+    }
+    for (const secret of proof.secrets) {
+        if (typeof secret !== "string" || secret.length < MIN_ORIGIN_PROOF_SECRET_LENGTH) {
+            throw new Error(`Lambder: every originProof secret must be a string of at least ${MIN_ORIGIN_PROOF_SECRET_LENGTH} characters; a shorter one could be guessed, and a guessed proof proves nothing.`);
+        }
+    }
+    const trusted = [...(options.trustedClientIpHeaders ?? []), ...(options.trustedHostHeaders ?? [])];
+    if (trusted.length === 0) {
+        throw new Error("Lambder: originProof guards the trustedClientIpHeaders and trustedHostHeaders, and this instance trusts none, so it would prove nothing.");
+    }
+    if (trusted.some((name) => name.toLowerCase() === proof.header.toLowerCase())) {
+        throw new Error(`Lambder: originProof.header "${proof.header}" is also a trusted header; the proof is its own header, which the app never reads.`);
     }
 };

package/dist/core/LambderInvocationScope.d.ts

@@ -0,0 +1,25 @@
+import type { Context } from "aws-lambda";
+import type { LambderCallOutcomeHint } from "../shared/wire/LambderCallOutcome.js";
+import { type LambderInvocation } from "../shared/util/LambderInvocationScope.js";
+/** What one invocation records about itself while it runs, for its call summary and for the calls it makes. */
+export type LambderInvocationRecord = LambderInvocation & {
+    /** When the invocation started, on performance.now()'s clock. */
+    readonly startedAt: number;
+    /** Whether this is the first invocation this process has run. */
+    readonly coldStart: boolean;
+    /** How long the API handler itself ran, in milliseconds; null until it has. */
+    handlerMs: number | null;
+    /** Whether an idempotent answer was replayed, so no handler ran. */
+    replayed: boolean;
+    /** The API call the invocation serves: the endpoint its path named, and the invocation that invoked it, when one did. Null for anything else. */
+    call: {
+        api: string;
+        parentRequestId: string | null;
+    } | null;
+    /** What the answer is, once the call has one. */
+    outcome: LambderCallOutcomeHint | null;
+};
+/** Runs one invocation under a record of its own, which `currentInvocation()` finds from anything it runs. */
+export declare const runInvocation: <T>(lambdaContext: Context | null | undefined, run: (record: LambderInvocationRecord) => Promise<T>) => Promise<T>;
+/** The invocation the calling code runs under, or null outside one (a script, a test calling a library directly). */
+export declare const currentInvocation: () => LambderInvocationRecord | null;

package/dist/core/LambderInvocationScope.js

@@ -0,0 +1,21 @@
+import { invocationScope } from "../shared/util/LambderInvocationScope.js";
+/** Whether this process has started an invocation yet: the first one is its cold start. */
+let processStarted = false;
+/** Runs one invocation under a record of its own, which `currentInvocation()` finds from anything it runs. */
+export const runInvocation = (lambdaContext, run) => {
+    const record = {
+        requestId: typeof lambdaContext?.awsRequestId === "string" && lambdaContext.awsRequestId ? lambdaContext.awsRequestId : null,
+        startedAt: performance.now(),
+        coldStart: !processStarted,
+        handlerMs: null,
+        replayed: false,
+        call: null,
+        outcome: null,
+    };
+    processStarted = true;
+    return invocationScope.run(record, () => run(record));
+};
+/** The invocation the calling code runs under, or null outside one (a script, a test calling a library directly). */
+export const currentInvocation = () => 
+// Only runInvocation opens the scope, and always with a whole record.
+invocationScope.getStore() ?? null;

package/dist/core/LambderResponse.d.ts

@@ -3,6 +3,7 @@ import type { LambderCompressionOption, LambderCompressionSettingsBase, LambderE
 import type { LambderRenderContext, LambderHttpEventFormat } from "./LambderContext.js";
 import type { LambderApiAnswer } from "../api/LambderApiAnswer.js";
 import type { LambderHttpStatusCode } from "../shared/wire/LambderHttpStatus.js";
+import type { LambderCallOutcomeHint } from "../shared/wire/LambderCallOutcome.js";
 export type LambderHeadersInput = Record<string, string | string[]>;
 /**
  * Final Lambda response: v1 (REST API) uses multiValueHeaders, v2 (HTTP API /
@@ -31,6 +32,8 @@ type LambderResponseInit = {
     compress?: boolean | "auto";
     /** "auto": ETag on GET/HEAD 200 when globally enabled. true: force. false: never. */
     etag?: boolean | "auto";
+    /** What the response answers an API call with, when it was written as an API answer; see LambderResponse.callOutcome. */
+    callOutcome?: LambderCallOutcomeHint | null;
 };
 /**
  * Intermediate response object returned by all response builder methods and by
@@ -49,6 +52,14 @@ export declare class LambderResponse {
     isBodyBase64: boolean;
     compress: boolean | "auto";
     etag: boolean | "auto";
+    /**
+     * What this response answers an API call with (a success, a refusal and
+     * its code, a flag), when it was written as an API answer: the envelope
+     * builders and res.apiRefusal() set it, and the call's summary line reads
+     * it, so the line does not parse the body back. Null on any other
+     * response, which the line names `other`.
+     */
+    callOutcome: LambderCallOutcomeHint | null;
     constructor(init: LambderResponseInit);
     /**
      * A copy with its own header lists, for a request to write into. A

package/dist/core/LambderResponse.js

@@ -21,6 +21,14 @@ export class LambderResponse {
     isBodyBase64;
     compress;
     etag;
+    /**
+     * What this response answers an API call with (a success, a refusal and
+     * its code, a flag), when it was written as an API answer: the envelope
+     * builders and res.apiRefusal() set it, and the call's summary line reads
+     * it, so the line does not parse the body back. Null on any other
+     * response, which the line names `other`.
+     */
+    callOutcome;
     constructor(init) {
         this.statusCode = init.statusCode;
         this.headers = normalizeHeaders(init.headers);
@@ -28,6 +36,7 @@ export class LambderResponse {
         this.isBodyBase64 = init.isBodyBase64 ?? false;
         this.compress = init.compress ?? "auto";
         this.etag = init.etag ?? "auto";
+        this.callOutcome = init.callOutcome ?? null;
     }
     /**
      * A copy with its own header lists, for a request to write into. A
@@ -44,6 +53,7 @@ export class LambderResponse {
             isBodyBase64: this.isBodyBase64,
             compress: this.compress,
             etag: this.etag,
+            callOutcome: this.callOutcome,
         });
     }
     // The header methods delegate to the core's header helpers, so an answer
@@ -77,6 +87,7 @@ export const answerFromResponse = (response) => {
         isBodyBase64: response.isBodyBase64 || binary,
         compress: response.compress,
         etag: response.etag,
+        ...(response.callOutcome ? { outcome: response.callOutcome } : {}),
     };
 };
 /**
@@ -98,6 +109,7 @@ export const responseFromAnswer = (answer) => new LambderResponse({
     isBodyBase64: answer.isBodyBase64 ?? false,
     compress: answer.compress ?? "auto",
     etag: answer.etag ?? "auto",
+    callOutcome: answer.outcome ?? null,
 });
 const mimeOf = (contentType) => (contentType?.split(";")[0] ?? "").trim().toLowerCase();
 /** A content type whose body is text: sent as text when it is valid UTF-8 and not compressed. */