lambder 12.0.1 → 14.0.1

package/dist/core/Lambder.js

@@ -13,7 +13,7 @@ import { LambderFiles } from "./LambderFiles.js";
 import { isLambderApiRefusal } from "../shared/wire/LambderApiRefusal.js";
 import { LambderApiPipeline } from "../api/LambderApiPipeline.js";
 import { LAMBDER_BACKEND_SWAP, LAMBDER_CRASH_WATCH } from "../shared/util/LambderTestingDoors.js";
-import { checkedRefusal, readRefusalVocabulary, resolveAllowedRefusals, toRefusalCodes, } from "../api/LambderApiRefusals.js";
+import { checkedRefusal, declaredRefusalVocabulary, readRefusalVocabulary, resolveAllowedRefusals, toRefusalCodes, } from "../api/LambderApiRefusals.js";
 import { refuse } from "../shared/wire/LambderApiRefusal.js";
 import { apiSignatureOf } from "../api/LambderApiSignature.js";
 import { apiNameKeyOf } from "../shared/wire/LambderApiSignatureMap.js";
@@ -28,10 +28,31 @@ import { bindContextTools, createContext, isV2HttpEvent, } from "./LambderContex
 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 { currentInvocation, runInvocation } from "./LambderInvocationScope.js";
+import { roundedMilliseconds, writeCallSummaryLine } from "./LambderCallSummary.js";
+import { outcomeOfAnswerText } from "../shared/wire/LambderCallOutcome.js";
+import { LAMBDER_INVOKE_API_ID, LAMBDER_PARENT_REQUEST_HEADER } from "../shared/wire/LambderInvokeApiId.js";
 import { policyBuildersFor } from "./LambderPolicyBuilders.js";
 import { assertCreateOptions, mergeNamedMaps, } from "./LambderCreateOptions.js";
 /** The refusals of a name no API is registered under: no code, and none required. */
 const NO_DECLARED_REFUSALS = { codes: new Map(), codeRequired: false };
+/** Longest endpoint name a call summary carries: a page built before paths posts the name in its body, and a line is no place for a long one. */
+const MAX_SUMMARY_API_NAME_CHARS = 200;
+/** A request id as the parent header may carry one: what Lambda's own ids look like, and no longer than any of them. */
+const REQUEST_ID_PATTERN = /^[A-Za-z0-9-]{1,128}$/;
+/**
+ * The request id of the invocation that invoked this one, from an invoke's
+ * event alone: over HTTP the header is whatever a client wrote, and an
+ * invoke's apiId is one no gateway lets a client set.
+ */
+const parentRequestIdOf = (event) => {
+    if (event.requestContext?.apiId !== LAMBDER_INVOKE_API_ID)
+        return null;
+    const value = Object.entries(event.headers ?? {}).find(([name]) => name.toLowerCase() === LAMBDER_PARENT_REQUEST_HEADER)?.[1];
+    return typeof value === "string" && REQUEST_ID_PATTERN.test(value) ? value : null;
+};
+/** The API call a request is, as its invocation records it; null for a request that is no API call. */
+const apiCallOf = (ctx, event) => ctx.api ? { api: ctx.api.apiName, parentRequestId: parentRequestIdOf(event) } : null;
 /**
  * Main Lambder class for building type-safe serverless APIs. Create
  * instances with initLambder<SessionData>().create({...}) (see below): the
@@ -130,6 +151,9 @@ export default class Lambder {
     contextTools;
     trustedClientIpHeaders;
     trustedHostHeaders;
+    originProof;
+    /** Where each API call's summary goes (the callSummary option); null writes none. Replaceable through the backend swap alone. */
+    callSummaryWriter;
     constructor(given = {}) {
         // The guards and the rate-limit policies as one map each, whether
         // they were given as one or as a list; a name two maps declare
@@ -174,7 +198,9 @@ export default class Lambder {
                         sessionSalt: session.sessionSalt,
                         enableSlidingExpiration: session.enableSlidingExpiration,
                         slidingWriteIntervalSeconds: session.slidingWriteIntervalSeconds,
-                        dataRefresh: session.dataRefresh,
+                        // As given: the manager refuses dataRefresh without
+                        // the schema, which an untyped caller can still pass.
+                        ...{ dataRefresh: session.dataRefresh, dataSchema: session.dataSchema },
                         crypto: session.crypto,
                     }),
                     tokenCookieKey: session.tokenCookieKey,
@@ -188,6 +214,8 @@ export default class Lambder {
         });
         this.trustedClientIpHeaders = options.trustedClientIpHeaders ?? [];
         this.trustedHostHeaders = options.trustedHostHeaders ?? [];
+        this.originProof = options.originProof ?? null;
+        this.callSummaryWriter = options.callSummary === false ? null : options.callSummary ?? writeCallSummaryLine;
         this.requireApiGuards = options.requireApiGuards ?? false;
         this.requireRefusalCodes = options.requireRefusalCodes ?? false;
         this.crashHandling = new LambderCrashHandling(options.crashes ?? {}, this.apiVersion);
@@ -579,6 +607,8 @@ export default class Lambder {
     [LAMBDER_BACKEND_SWAP](backends) {
         if (this.files && backends.fileSource)
             this.files[LAMBDER_BACKEND_SWAP](backends.fileSource);
+        if (backends.callSummary !== undefined)
+            this.callSummaryWriter = backends.callSummary;
         return { ...this.pipeline[LAMBDER_BACKEND_SWAP](backends), files: this.files !== null };
     }
     /**
@@ -872,7 +902,19 @@ export default class Lambder {
             return beforeRenderResult;
         return await matched.action.actionFn(beforeRenderResult, resolver);
     }
+    /**
+     * One HTTP invocation, from the event to the finalized response, under
+     * an invocation record of its own (see LambderInvocationScope): what an
+     * API call's summary line is written from once the response is final.
+     */
     async render(event, lambdaContext) {
+        return await runInvocation(lambdaContext, async (invocation) => {
+            const response = await this.renderRequest(event, lambdaContext, invocation);
+            this.writeCallSummary(invocation, response.statusCode);
+            return response;
+        });
+    }
+    async renderRequest(event, lambdaContext, invocation) {
         let ctx = null;
         let started = false;
         // Settled as soon as the context exists and reused by every answer,
@@ -881,11 +923,8 @@ export default class Lambder {
         try {
             await this.ensureInitialized();
             started = true;
-            ctx = bindContextTools(createContext(event, lambdaContext, {
-                apiPath: this.apiPath,
-                trustedClientIpHeaders: this.trustedClientIpHeaders,
-                trustedHostHeaders: this.trustedHostHeaders,
-            }), this.contextTools);
+            ctx = bindContextTools(createContext(event, lambdaContext, this.contextOptions()), this.contextTools);
+            invocation.call = apiCallOf(ctx, event);
             if (this.corsConfig)
                 allowedOrigin = allowedCorsOriginOf(this.corsConfig, ctx);
             const resolver = this.getResolver(ctx);
@@ -934,12 +973,33 @@ export default class Lambder {
             // reach it.
             ctx.responseHeaders.applyTo(response, response === responseIntoHooks ? headersAppliedIntoHooks : 0);
             this.applyCors(allowedOrigin, response, this.isCorsPreflight(ctx));
+            invocation.outcome = response.callOutcome ?? { outcome: "other", code: null };
             return await finalizeResponse(ctx, response, this.finalizeOptions, ctx.eventFormat);
         }
         catch (err) {
+            // A crash before the context existed (a created hook that failed)
+            // still answers an API call, and its summary line is the one a
+            // dashboard counts the crash by. The context is read from the
+            // event and the instance's options alone, so it can be read here;
+            // an event it cannot be read from has no call to name.
+            if (!ctx) {
+                try {
+                    invocation.call = apiCallOf(createContext(event, lambdaContext, this.contextOptions()), event);
+                }
+                catch { /* no call to name */ }
+            }
             return await this.answerCrash(err, ctx, allowedOrigin, started, event, lambdaContext);
         }
     }
+    /** What createContext reads this instance's requests with. */
+    contextOptions() {
+        return {
+            apiPath: this.apiPath,
+            trustedClientIpHeaders: this.trustedClientIpHeaders,
+            trustedHostHeaders: this.trustedHostHeaders,
+            originProof: this.originProof,
+        };
+    }
     /**
      * A thrown value that is an answer rather than a crash, as the response;
      * anything else is rethrown to the crash path.
@@ -978,6 +1038,10 @@ export default class Lambder {
         // invocation would reject with a 502 no client can parse.
         const error = coerceToError(thrown, "an unstringifiable thrown value");
         this.crashWatcher?.(error);
+        // A crash, whatever the global error handler then answers with.
+        const invocation = currentInvocation();
+        if (invocation)
+            invocation.outcome = { outcome: "crash", code: null };
         const site = !started ? { kind: "startup", lambdaContext }
             : ctx?.api ? { kind: "api", ctx, lambdaContext }
                 : { kind: "route", ctx, lambdaContext };
@@ -1014,6 +1078,37 @@ export default class Lambder {
         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);
     }
+    /**
+     * The summary line of an API call, once its response is final: nothing
+     * for an invocation that served no API call. A writer that throws costs
+     * the call its line and nothing else.
+     */
+    writeCallSummary(invocation, status) {
+        const { call } = invocation;
+        if (!call || !this.callSummaryWriter)
+            return;
+        const summary = {
+            kind: "lambder.call",
+            // The path form is two identifiers; a page built before paths
+            // posts the name in its body, which is whatever it sent.
+            api: call.api.slice(0, MAX_SUMMARY_API_NAME_CHARS),
+            outcome: invocation.outcome?.outcome ?? "other",
+            code: invocation.outcome?.code ?? null,
+            status,
+            durationMs: roundedMilliseconds(performance.now() - invocation.startedAt),
+            handlerMs: invocation.handlerMs === null ? null : roundedMilliseconds(invocation.handlerMs),
+            replayed: invocation.replayed,
+            coldStart: invocation.coldStart,
+            requestId: invocation.requestId,
+            parentRequestId: call.parentRequestId,
+        };
+        try {
+            this.callSummaryWriter(summary);
+        }
+        catch (err) {
+            console.error(`Lambder: the callSummary writer threw, so the summary of "${summary.api}" was not written. ${coerceToError(err).message}`);
+        }
+    }
     /**
      * 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
@@ -1070,6 +1165,11 @@ export default class Lambder {
      * so Lambda's retries and dead-letter queues still see the failure.
      */
     async renderEvent(event, lambdaContext) {
+        // Under an invocation record, like an HTTP invocation, so the calls an
+        // action makes over invoke carry its request id.
+        return await runInvocation(lambdaContext, () => this.renderEventAction(event, lambdaContext));
+    }
+    async renderEventAction(event, lambdaContext) {
         let started = false;
         try {
             await this.ensureInitialized();
@@ -1101,7 +1201,8 @@ export default class Lambder {
      */
     async inputValidationRefusal(ctx, zodError) {
         if (this.apiInputValidationErrorHandler) {
-            return answerFromResponse(await this.apiInputValidationErrorHandler(ctx, this.getResolver(ctx), zodError));
+            // A validation refusal, however the app words it.
+            return { ...answerFromResponse(await this.apiInputValidationErrorHandler(ctx, this.getResolver(ctx), zodError)), outcome: { outcome: "validation", code: null } };
         }
         // null asks the pipeline for the standard 422, so that answer is
         // written once, in the core, rather than here as well.
@@ -1140,9 +1241,18 @@ export default class Lambder {
         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 { answer } = await this.pipeline.run(request, ctx, definition, async () => {
+        const invocation = currentInvocation();
+        const { answer, replayed } = await this.pipeline.run(request, ctx, definition, async () => {
             ctx.apiPayload = request.payload;
-            const returned = await handler(ctx);
+            const handlerStarted = performance.now();
+            let returned;
+            try {
+                returned = await handler(ctx);
+            }
+            finally {
+                if (invocation)
+                    invocation.handlerMs = performance.now() - handlerStarted;
+            }
             let parsed;
             try {
                 parsed = output.safeParse(returned);
@@ -1157,8 +1267,11 @@ export default class Lambder {
             return envelopeAnswer(successEnvelope(this.apiVersion, parsed.data, ctx.logList));
         });
         // The API's compress option, on whatever answer the call ended with:
-        // a replayed one comes back from its store without the hint.
-        return responseFromAnswer({ ...answer, compress });
+        // a replayed one comes back from its store without the hints, and
+        // its outcome is read back from its text, which only a replay costs.
+        if (invocation)
+            invocation.replayed = replayed;
+        return responseFromAnswer({ ...answer, compress, outcome: answer.outcome ?? outcomeOfAnswerText(answer.statusCode, answer.body) });
     }
     /**
      * A thrown LambderApiRefusal (from a hook, say) as the structured API
@@ -1204,7 +1317,10 @@ export const initLambder = () => ({
      * Declares the app's refusal vocabulary: every code once, with the schema
      * of its data (`{ data: schema }`) or none (`{}`), the status every
      * refusal with it leaves with (`status`, 200 by default) and whether it
-     * sets the notAuthorized flag (`notAuthorized: true`). Returns the init
+     * sets the notAuthorized flag (`notAuthorized: true`). One map of codes,
+     * or a list of them, as guards and rate-limit policies are declared, so
+     * each part of an app declares its own codes; a code two maps declare is
+     * refused, at compile time and at the call. Returns the init
      * bound to it: its guard() types ctx.refuse to a guard's refusals and
      * refuses a guard naming a code outside the vocabulary, its refuse is
      * typed to the whole vocabulary, and its create() hands the vocabulary to
@@ -1213,9 +1329,11 @@ export const initLambder = () => ({
      * "no" a client reads names a code.
      */
     declareRefusals(refusals, options = {}) {
-        const vocabulary = readRefusalVocabulary(refusals);
-        if (!vocabulary)
-            throw new Error("Lambder: declareRefusals() takes the vocabulary, an object of codes.");
-        return lambderInitOf({ refusals, vocabulary, requireCodes: (options.requireCodes ?? false) });
+        const declared = declaredRefusalVocabulary(refusals, "Lambder");
+        return lambderInitOf({
+            refusals: declared.refusals,
+            vocabulary: declared.vocabulary,
+            requireCodes: (options.requireCodes ?? false),
+        });
     },
 });

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

@@ -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,6 +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";
@@ -69,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;
@@ -82,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;
@@ -127,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
@@ -135,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) : "")

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,10 +155,8 @@ 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. */
@@ -274,6 +264,38 @@ 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 a guard that needs a session, and for addSessionRoute. */
@@ -474,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"]>;
     };
@@ -493,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
@@ -56,4 +46,33 @@ export const assertCreateOptions = (options) => {
     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;