lambder 7.0.2 → 7.2.0

package/dist/client/LambderCaller.js

@@ -7,6 +7,8 @@ import { createCallAbort } from '../shared/util/LambderCallAbort.js';
 import { coerceToError } from '../shared/wire/LambderCrashDetail.js';
 import { isLambderTransportFailure } from '../shared/transport/LambderApiTransport.js';
 import { DEFAULT_SESSION_TOKEN_COOKIE_KEY, DEFAULT_SESSION_CSRF_COOKIE_KEY } from '../shared/wire/LambderSessionCookieNames.js';
+import { readApiSignature } from '../shared/wire/LambderApiSignature.js';
+import { LambderReloadLoopBreaker, RELOAD_LOOP_WINDOW_MS } from './LambderReloadLoopBreaker.js';
 import { lambderFetchTransport } from './lambderFetchTransport.js';
 /**
  * @typeParam TContract - The API contract, for typed names, payloads and guard inputs.
@@ -16,7 +18,10 @@ export default class LambderCaller {
     isCorsEnabled;
     apiPath;
     apiVersion;
+    apiSignatures;
     timeoutMs;
+    /** What keeps a stale bundle from reloading itself forever; see the class. */
+    reloadLoopBreaker = new LambderReloadLoopBreaker();
     /** The calls currently in flight, in the order they started. */
     fetchTrackerList = [];
     /** Whether any call is in flight. Derived, so it cannot drift from the list the way a separate flag did. */
@@ -40,9 +45,10 @@ export default class LambderCaller {
     constructor(options) {
         // The conditional provider option is resolved per instantiation;
         // inside the class it is read through the plain shape.
-        const { apiPath, apiVersion, isCorsEnabled, timeoutMs, versionExpiredHandler, sessionExpiredHandler, messageHandler, errorMessageHandler, notAuthorizedHandler, errorHandler, logListHandler, fetchStartedHandler, fetchEndedHandler, apiInputValidationErrorHandler, sessionCookieDomain, requestCompression, guardInputsProvider, transport, } = options;
+        const { apiPath, apiVersion, apiSignatures, isCorsEnabled, timeoutMs, versionExpiredHandler, sessionExpiredHandler, messageHandler, errorMessageHandler, notAuthorizedHandler, errorHandler, logListHandler, fetchStartedHandler, fetchEndedHandler, apiInputValidationErrorHandler, sessionCookieDomain, requestCompression, guardInputsProvider, transport, } = options;
         this.apiPath = apiPath;
         this.apiVersion = apiVersion;
+        this.apiSignatures = apiSignatures;
         this.isCorsEnabled = isCorsEnabled;
         this.timeoutMs = timeoutMs;
         this.sessionCookieDomain = sessionCookieDomain;
@@ -198,6 +204,10 @@ export default class LambderCaller {
                     activeFetchList: [...this.fetchTrackerList],
                 });
             const version = this.apiVersion;
+            // The server's signature for this endpoint, when this build
+            // carries the map. A name the map lacks fails the call here, as a
+            // provider that threw would: the map predates the endpoint.
+            const signature = this.apiSignatures ? await readApiSignature(this.apiSignatures, apiName) : undefined;
             // js-cookie reads nothing without a document, and there is no
             // location outside a page: both are "" then, and a transport that
             // carries a cookie jar fills the token in from it.
@@ -228,6 +238,7 @@ export default class LambderCaller {
                 answer = await this.transport({
                     apiPath: this.apiPath,
                     apiName, version, token, siteHost,
+                    ...(signature !== undefined ? { signature } : {}),
                     csrfCookieKey: this.sessionCsrfCookieKey,
                     ...(compressedPayload ? { compressed: compressedPayload } : { payload }),
                     ...(guardInputs !== undefined ? { guardInputs } : {}),
@@ -292,6 +303,15 @@ export default class LambderCaller {
             const data = outcome.response;
             await fetchEnded(data);
             if (!outcome.ok && outcome.reason === 'versionExpired') {
+                // A repeat of a recent versionExpired for the same endpoint and
+                // signature means the reload the handler performed brought the
+                // same bundle back, and reloading again would loop. The
+                // handler is not called; the failure is reported instead, and
+                // the outcome still says versionExpired.
+                if (this.reloadLoopBreaker.isRepeat(apiName, signature ?? "")) {
+                    await reportError(new Error(`Version expired again for API "${apiName}" within ${RELOAD_LOOP_WINDOW_MS / 60000} minutes with the same signature: the bundle being served is still the stale one, so versionExpiredHandler was not called again.`));
+                    return outcome;
+                }
                 if (versionExpiredHandler) {
                     await versionExpiredHandler();
                 }

package/dist/client/LambderReloadLoopBreaker.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Stops a stale client from reloading forever.
+ *
+ * A versionExpired answer means "this client's signature for the endpoint is
+ * not the one the server holds", and the ordinary response is to reload and
+ * get the current bundle. When the bundle being served is itself the stale
+ * one (a frontend deployed with a signature map the server does not match, a
+ * cached bundle, a server deploy that failed behind a fresh frontend), the
+ * reload brings back the same signature, the same call fails the same way,
+ * and the page reloads again, indefinitely.
+ *
+ * The evidence of that loop is a versionExpired for the same endpoint with
+ * the same signature shortly after the last one: a bundle that had actually
+ * changed the endpoint would carry a different signature. The record lives
+ * in sessionStorage, which is per tab and survives a reload, so the new page
+ * instance sees what the previous one saw; without sessionStorage (a test, a
+ * non-browser runtime) an in-memory record does the same within one page.
+ *
+ * Once a repeat is confirmed, every versionExpired within the window from
+ * the first one counts as a repeat too, whichever endpoint it names: a stale
+ * bundle is usually stale for several endpoints, and one reload per endpoint
+ * is still a loop, only a slower one. After the window a reload is allowed
+ * again, so a client stuck on a stale bundle retries a few times an hour and
+ * recovers by itself once the deploy is fixed.
+ */
+/** How long after the first versionExpired a repeat counts as the same loop. */
+export declare const RELOAD_LOOP_WINDOW_MS: number;
+export declare class LambderReloadLoopBreaker {
+    /** The record when sessionStorage is unavailable; sessionStorage is read first wherever it exists. */
+    private memory;
+    /**
+     * Records this versionExpired and says whether it repeats a recent one,
+     * in which case the caller must not invoke versionExpiredHandler again.
+     */
+    isRepeat(apiName: string, signature: string, now?: number): boolean;
+    private read;
+    private write;
+}

package/dist/client/LambderReloadLoopBreaker.js

@@ -0,0 +1,71 @@
+/**
+ * Stops a stale client from reloading forever.
+ *
+ * A versionExpired answer means "this client's signature for the endpoint is
+ * not the one the server holds", and the ordinary response is to reload and
+ * get the current bundle. When the bundle being served is itself the stale
+ * one (a frontend deployed with a signature map the server does not match, a
+ * cached bundle, a server deploy that failed behind a fresh frontend), the
+ * reload brings back the same signature, the same call fails the same way,
+ * and the page reloads again, indefinitely.
+ *
+ * The evidence of that loop is a versionExpired for the same endpoint with
+ * the same signature shortly after the last one: a bundle that had actually
+ * changed the endpoint would carry a different signature. The record lives
+ * in sessionStorage, which is per tab and survives a reload, so the new page
+ * instance sees what the previous one saw; without sessionStorage (a test, a
+ * non-browser runtime) an in-memory record does the same within one page.
+ *
+ * Once a repeat is confirmed, every versionExpired within the window from
+ * the first one counts as a repeat too, whichever endpoint it names: a stale
+ * bundle is usually stale for several endpoints, and one reload per endpoint
+ * is still a loop, only a slower one. After the window a reload is allowed
+ * again, so a client stuck on a stale bundle retries a few times an hour and
+ * recovers by itself once the deploy is fixed.
+ */
+/** How long after the first versionExpired a repeat counts as the same loop. */
+export const RELOAD_LOOP_WINDOW_MS = 5 * 60 * 1000;
+const STORAGE_KEY = "lambder:version-expired";
+const isExpiredRecord = (value) => typeof value === "object" && value !== null
+    && typeof value.apiName === "string"
+    && typeof value.signature === "string"
+    && typeof value.at === "number"
+    && typeof value.confirmed === "boolean";
+export class LambderReloadLoopBreaker {
+    /** The record when sessionStorage is unavailable; sessionStorage is read first wherever it exists. */
+    memory = null;
+    /**
+     * Records this versionExpired and says whether it repeats a recent one,
+     * in which case the caller must not invoke versionExpiredHandler again.
+     */
+    isRepeat(apiName, signature, now = Date.now()) {
+        const last = this.read();
+        if (last && now - last.at < RELOAD_LOOP_WINDOW_MS && (last.confirmed || (last.apiName === apiName && last.signature === signature))) {
+            // `at` stays the first event's, so the window runs from the start
+            // of the loop rather than being pushed forward by every repeat.
+            this.write({ apiName, signature, at: last.at, confirmed: true });
+            return true;
+        }
+        this.write({ apiName, signature, at: now, confirmed: false });
+        return false;
+    }
+    read() {
+        try {
+            const raw = globalThis.sessionStorage?.getItem(STORAGE_KEY);
+            if (raw) {
+                const parsed = JSON.parse(raw);
+                if (isExpiredRecord(parsed))
+                    return parsed;
+            }
+        }
+        catch { /* a private window or blocked storage: the in-memory record stands in */ }
+        return this.memory;
+    }
+    write(record) {
+        this.memory = record;
+        try {
+            globalThis.sessionStorage?.setItem(STORAGE_KEY, JSON.stringify(record));
+        }
+        catch { /* same: the in-memory record stands in */ }
+    }
+}

package/dist/client.d.ts

@@ -15,6 +15,10 @@ export type { LambderApiTransport, LambderApiTransportRequest, LambderTransportF
 export { LambderCookieJar, parseSetCookie } from "./shared/transport/LambderCookieJar.js";
 export type { LambderStoredCookie } from "./shared/transport/LambderCookieJar.js";
 export { resolveApiOutcome } from "./shared/wire/LambderApiOutcome.js";
+export { apiNameKeyOf, lookupApiSignature, readApiSignature, API_SIGNATURE_HEX_LENGTH } from "./shared/wire/LambderApiSignature.js";
+export type { LambderApiSignatureMap } from "./shared/wire/LambderApiSignature.js";
+export { RELOAD_LOOP_WINDOW_MS } from "./client/LambderReloadLoopBreaker.js";
+export { compareDottedVersions, isDottedVersion } from "./shared/wire/LambderVersionOrder.js";
 export type { LambderApiAnswerOutcome, LambderApiSuccessOutcome, LambderApiCallFailure, LambderApiValidationFailure, LambderApiEnvelopeFailure, LambderApiHttpAnswer, } from "./shared/wire/LambderApiOutcome.js";
 export type { LambderApiOutcome, LambderApiFailureReason, LambderValidationError, LambderCallOptions, LambderCallerOptions, LambderGuardInputsProvider, LambderProvidedGuardInputs, LambderIdempotencyKeyScope, LambderLogListHandler, } from "./client/LambderCaller.js";
 export { LambderApiRefusal, isLambderApiRefusal, refuse, LAMBDER_REFUSAL_CODES } from "./shared/wire/LambderApiRefusal.js";

package/dist/client.js

@@ -14,6 +14,10 @@ export { buildTransportEnvelope, LambderTransportFailure, isLambderTransportFail
 export { lambderCookieJarTransport } from "./shared/transport/lambderCookieJarTransport.js";
 export { LambderCookieJar, parseSetCookie } from "./shared/transport/LambderCookieJar.js";
 export { resolveApiOutcome } from "./shared/wire/LambderApiOutcome.js";
+// The per-endpoint signature map a build ships with, how a caller reads it, and the reload-loop window.
+export { apiNameKeyOf, lookupApiSignature, readApiSignature, API_SIGNATURE_HEX_LENGTH } from "./shared/wire/LambderApiSignature.js";
+export { RELOAD_LOOP_WINDOW_MS } from "./client/LambderReloadLoopBreaker.js";
+export { compareDottedVersions, isDottedVersion } from "./shared/wire/LambderVersionOrder.js";
 // Typed API refusals (isomorphic: shared code may throw them from anywhere;
 // in the browser they are plain Errors).
 export { LambderApiRefusal, isLambderApiRefusal, refuse, LAMBDER_REFUSAL_CODES } from "./shared/wire/LambderApiRefusal.js";

package/dist/core/Lambder.d.ts

@@ -9,6 +9,7 @@ import type LambderSessionController from "../session/LambderSessionController.j
 import { type LambderPublicFilesOptions } from "./LambderPublicFiles.js";
 import { type LambderIndexHtmlOptions } from "./LambderIndexHtml.js";
 import { LambderFiles } from "./LambderFiles.js";
+import { type LambderApiSignatureMap } from "../shared/wire/LambderApiSignature.js";
 import type { LambderApiIdempotencyOption } from "../shared/wire/LambderApiOptionValues.js";
 import type { LambderApiGuard, LambderGuardMetaMap, LambderGuardsOption, LambderGuardDataOf, LambderGuardInputsOf } from "../api/LambderApiGuards.js";
 import type { LambderApiRateLimitPolicyConfig, LambderRateLimitOption } from "../api/LambderApiRateLimits.js";
@@ -50,6 +51,7 @@ export type LambderCreatedHook = (lambderInstance: Lambder<any, any, any, any, a
  */
 export default class Lambder<TSessionData = any, _TContract extends Record<string, any> = {}, _TRateLimitPolicies extends Record<string, LambderApiRateLimitPolicyConfig> = {}, _TGuards extends Record<string, any> = {}, _TIdempotencyEnabled extends boolean = false, _TSessionGuardsRequired extends boolean = false, _TPublicGuardsRequired extends boolean = false, _TSessionsEnabled extends boolean = true> {
     apiPath: string;
+    /** Stamped on every API answer's envelope as apiVersion. Informational: a client's staleness is judged per endpoint by its signature, see apiSignatures(). */
     apiVersion: null | string;
     /** The instance's file reader (source + caches), or null without the files option. */
     files: LambderFiles | null;
@@ -67,7 +69,10 @@ export default class Lambder<TSessionData = any, _TContract extends Record<strin
     private actionList;
     /** The API core: the pipeline every API call runs through, shared in shape with the mock runtime. */
     private readonly pipeline;
-    private registeredApiNames;
+    /** Every registered API by name: the duplicate-name check, and what apiSignatures() digests. */
+    private readonly apiDefinitions;
+    /** The guards map given at creation, kept for apiSignatures(): a guard's schema is part of the signature of every endpoint declaring it. */
+    private readonly guards;
     private hookList;
     private createdHooks;
     private initPromise;
@@ -165,6 +170,17 @@ export default class Lambder<TSessionData = any, _TContract extends Record<strin
     getSessionController(ctx: LambderRenderContext | LambderSessionRenderContext<any, TSessionData>): LambderSessionController<TSessionData>;
     /** The session manager, for code that works on sessions outside a request (maintenance, tests). */
     getSessionManager(): LambderSessionManager<TSessionData>;
+    /**
+     * 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.
+     */
+    apiSignatures(): Promise<LambderApiSignatureMap>;
     getResponseBuilder(ctx?: LambderRenderContext): LambderResponseBuilder<any>;
     private getResolver;
     getHandler(): LambderHandler;

package/dist/core/Lambder.js

@@ -10,6 +10,8 @@ import { LambderIndexHtmlHandler } from "./LambderIndexHtml.js";
 import { LambderFiles } from "./LambderFiles.js";
 import { isLambderApiRefusal } from "../shared/wire/LambderApiRefusal.js";
 import { LambderApiPipeline } from "../api/LambderApiPipeline.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 { COMPRESSED_PAYLOAD_GZ_FIELD, COMPRESSED_PAYLOAD_BR_FIELD, COMPRESSED_PAYLOAD_BYTES_FIELD } from "../shared/wire/LambderRequestPayload.js";
@@ -45,6 +47,7 @@ export default class Lambder {
     // Everything an instance is, fixed before the first registration.
     // =====================================================================
     apiPath;
+    /** Stamped on every API answer's envelope as apiVersion. Informational: a client's staleness is judged per endpoint by its signature, see apiSignatures(). */
     apiVersion;
     /** The instance's file reader (source + caches), or null without the files option. */
     files;
@@ -62,7 +65,10 @@ export default class Lambder {
     actionList = [];
     /** The API core: the pipeline every API call runs through, shared in shape with the mock runtime. */
     pipeline;
-    registeredApiNames = new Set();
+    /** Every registered API by name: the duplicate-name check, and what apiSignatures() digests. */
+    apiDefinitions = new Map();
+    /** The guards map given at creation, kept for apiSignatures(): a guard's schema is part of the signature of every endpoint declaring it. */
+    guards;
     hookList = { "beforeRender": [], "afterRender": [], "fallback": [] };
     createdHooks = [];
     initPromise = null;
@@ -95,8 +101,11 @@ export default class Lambder {
             this.corsConfig = options.cors === true ? {} : options.cors;
         }
         const session = options.session;
+        this.guards = options.guards;
         this.pipeline = new LambderApiPipeline({
             apiVersion: this.apiVersion,
+            minApiVersion: options.minApiVersion,
+            apiSignatures: options.apiSignatures,
             maxRequestPayloadBytes: options.maxRequestPayloadBytes,
             // The app's own validation handler is read at call time, since
             // setApiInputValidationErrorHandler runs after creation.
@@ -200,7 +209,8 @@ 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 };
+        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),
@@ -210,7 +220,8 @@ export default class Lambder {
     // 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 };
+        const definition = { name, mode: "session", 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),
@@ -276,6 +287,21 @@ export default class Lambder {
     getSessionManager() {
         return this.pipeline.sessionManager;
     }
+    /**
+     * 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.
+     */
+    async apiSignatures() {
+        const entries = await Promise.all([...this.apiDefinitions.values()].map(async (definition) => [await apiNameKeyOf(definition.name), await apiSignatureOf(definition, this.guards)]));
+        entries.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+        return Object.fromEntries(entries);
+    }
     getResponseBuilder(ctx) {
         return new LambderResponseBuilder({
             files: this.files,
@@ -583,7 +609,7 @@ export default class Lambder {
     // =====================================================================
     /** Registration-time checks shared by addApi/addSessionApi. */
     assertApiRegistration(name, mode, options) {
-        if (this.registeredApiNames.has(name)) {
+        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
@@ -603,7 +629,6 @@ export default class Lambder {
                 `Declare the guard that authorizes it, or ${optOut}.`);
         }
         this.pipeline.assertRegistration({ name, mode, guards: options.guards, rateLimit: options.rateLimit, idempotency: options.idempotency });
-        this.registeredApiNames.add(name);
     }
     /**
      * The answer for a rejected input: the app's

package/dist/core/LambderCreateOptions.d.ts

@@ -1,4 +1,5 @@
 import type { z } from "zod";
+import type { LambderApiSignatureMap } from "../shared/wire/LambderApiSignature.js";
 import type { Context } from "aws-lambda";
 import type LambderResolver from "./LambderResolver.js";
 import type LambderResponseBuilder from "./LambderResponseBuilder.js";
@@ -99,7 +100,35 @@ export type LambderCreateOptions<TSessionData = any> = {
      */
     files?: LambderFilesOption;
     apiPath?: string;
+    /**
+     * Stamped on every API answer's envelope as `apiVersion`, so a client can
+     * tell which build answered. Whether a client is stale is decided per
+     * endpoint by the signature it sends (see Lambder.apiSignatures()), not
+     * by this string; `minApiVersion` is the one thing that reads it. Dotted
+     * numbers ("1.2.10"), since that is how the floor compares it, so a
+     * commit sha or a build date is refused rather than read as zero.
+     */
     apiVersion?: string;
+    /**
+     * The oldest client build still served: a call naming a `version` below
+     * it answers `versionExpired` whatever its signature says. The lever for
+     * a change the signatures cannot see (a security fix, a field whose
+     * meaning changed under the same shape). Dotted numbers ("1.2.10"),
+     * compared segment by segment; a call naming no version is not judged.
+     * A floor above `apiVersion` is taken as `apiVersion`, with a warning,
+     * so a mistaken floor cannot refuse this build's own clients. Default:
+     * none.
+     */
+    minApiVersion?: string;
+    /**
+     * The generated signature map (Lambder.apiSignatures()), the same file
+     * the frontend ships with. Enables the signature gate: a call carrying a
+     * signature that is not this map's entry for its endpoint answers
+     * `versionExpired`. Generated once, at build time, and handed to both
+     * sides, so nothing is digested at request time and the two sides cannot
+     * disagree on a digest. Default: none, and no gate.
+     */
+    apiSignatures?: LambderApiSignatureMap;
     /**
      * Automatic compression for compressible responses. `true` (the default)
      * is `{ minBytes: 860, encodings: ["br", "gzip"], quality: 5 }`; `false`

package/dist/core/LambderCreateOptions.js

@@ -23,11 +23,6 @@ export const assertCreateOptions = (options) => {
     if (options.apiPath !== undefined && (options.apiPath === "" || !options.apiPath.startsWith("/"))) {
         throw new Error(`Lambder: apiPath must be a path starting with "/", got ${JSON.stringify(options.apiPath)}.`);
     }
-    // "" is the one string that turns the version gate off while looking like
-    // it was set; say so rather than accepting every version a client names.
-    if (options.apiVersion === "") {
-        throw new Error("Lambder: apiVersion must not be empty. Leave it out to run without the version gate.");
-    }
     // 0 or a negative ceiling turned every response into the size guard's own 500.
     if (options.maxResponseBytes !== undefined)
         assertPositiveInteger(options.maxResponseBytes, "maxResponseBytes");

package/dist/index.d.ts

@@ -25,6 +25,11 @@ export { LambderAnswerHeaders, getAnswerHeader, setAnswerHeader, addAnswerHeader
 export { createApiCallContext } from "./api/LambderApiCallContext.js";
 export type { LambderApiCallContext, LambderApiCallTrace } from "./api/LambderApiCallContext.js";
 export type { LambderApiDefinition } from "./api/LambderApiDefinition.js";
+export { apiSignatureOf } from "./api/LambderApiSignature.js";
+export { apiNameKeyOf, lookupApiSignature, readApiSignature, API_SIGNATURE_HEX_LENGTH } from "./shared/wire/LambderApiSignature.js";
+export type { LambderApiSignatureMap } from "./shared/wire/LambderApiSignature.js";
+export { RELOAD_LOOP_WINDOW_MS } from "./client/LambderReloadLoopBreaker.js";
+export { compareDottedVersions, isDottedVersion } from "./shared/wire/LambderVersionOrder.js";
 export { buildApiEnvelope, envelopeAnswer, refusalAnswer, validationAnswer, apiNotFoundAnswer, sessionExpiredAnswer, versionExpiredAnswer, invalidPayloadAnswer, crashAnswer, API_ANSWER_CONTENT_TYPE, } from "./api/LambderApiEnvelope.js";
 export type { LambderApiEnvelopeConfig, LambderValidationAnswerBody } from "./api/LambderApiEnvelope.js";
 export { LambderApiValidationRefusal, isLambderApiValidationRefusal } from "./api/LambderApiValidationRefusal.js";

package/dist/index.js

@@ -16,6 +16,11 @@ export { readApiEnvelope, restoreCompressedPayload } from "./api/LambderApiReque
 export { toHttpAnswer } from "./api/LambderApiAnswer.js";
 export { LambderAnswerHeaders, getAnswerHeader, setAnswerHeader, addAnswerHeader } from "./shared/wire/LambderAnswerHeaders.js";
 export { createApiCallContext } from "./api/LambderApiCallContext.js";
+// Per-endpoint signatures: what a client build ships with, digested from the server's own registrations.
+export { apiSignatureOf } from "./api/LambderApiSignature.js";
+export { apiNameKeyOf, lookupApiSignature, readApiSignature, API_SIGNATURE_HEX_LENGTH } from "./shared/wire/LambderApiSignature.js";
+export { RELOAD_LOOP_WINDOW_MS } from "./client/LambderReloadLoopBreaker.js";
+export { compareDottedVersions, isDottedVersion } from "./shared/wire/LambderVersionOrder.js";
 export { buildApiEnvelope, envelopeAnswer, refusalAnswer, validationAnswer, apiNotFoundAnswer, sessionExpiredAnswer, versionExpiredAnswer, invalidPayloadAnswer, crashAnswer, API_ANSWER_CONTENT_TYPE, } from "./api/LambderApiEnvelope.js";
 export { LambderApiValidationRefusal, isLambderApiValidationRefusal } from "./api/LambderApiValidationRefusal.js";
 // Calling a Lambder app from another lambda (server-only: the Lambda SDK, zlib)

package/dist/invoke/LambderInvokeCaller.d.ts

@@ -22,6 +22,7 @@
  */
 import type { APIGatewayProxyEventV2, Context } from "aws-lambda";
 import { type LambderInvokeFailure, type LambderInvokeOutcome } from "./LambderInvokeOutcome.js";
+import { type LambderApiSignatureMap } from "../shared/wire/LambderApiSignature.js";
 import type { LambdaClient, LambdaClientConfig } from "@aws-sdk/client-lambda";
 import type { LambderApiContractShape } from "../shared/wire/LambderApiContract.js";
 import { type LambderCallArgs, type LambderContractOutputOf, type LambderGuardInputsProviderOption, type LambderSharedCallOptions } from "../shared/wire/LambderCallOptions.js";
@@ -92,8 +93,15 @@ type LambderInvokeCallerBaseOptions = {
     clientConfig?: LambdaClientConfig;
     /** Must match the callee's apiPath. Default: "/api". */
     apiPath?: string;
-    /** Sent as `version`; the callee answers versionExpired on a mismatch when it has one too. Default: none. */
+    /** Sent as `version`, informational: the callee stamps its own on every answer. Default: none. */
     apiVersion?: string;
+    /**
+     * The callee's signature map, generated from its instance
+     * (Lambder.apiSignatures()) when this caller was built. Sent per call as
+     * `signature`, so the callee answers versionExpired to a call built
+     * against another shape of the endpoint. Default: none, and no gate.
+     */
+    apiSignatures?: LambderApiSignatureMap;
     /** The Host the callee sees (ctx.host). Default: functionName. */
     host?: string;
     /**
@@ -146,6 +154,8 @@ export type LambderInvokeEventInit = {
     /** Default: "lambder-invoke". */
     host?: string;
     apiVersion?: string;
+    /** The caller's signature for the endpoint, out of the callee's map. */
+    signature?: string;
     guardInputs?: Record<string, unknown>;
     idempotencyKey?: string;
     clientIp?: string;
@@ -161,6 +171,7 @@ export default class LambderInvokeCaller<TContract extends LambderApiContractSha
     private readonly functionName;
     private readonly apiPath;
     private readonly apiVersion?;
+    private readonly apiSignatures?;
     private readonly host;
     private readonly requestCompression;
     private readonly maxResponsePayloadBytes;

package/dist/invoke/LambderInvokeCaller.js

@@ -22,6 +22,7 @@
  */
 import { classifyDeliveryFailure, describeFailure, errorFromFunctionError, LambderInvokeError, parseFunctionError, } from "./LambderInvokeOutcome.js";
 import { DEFAULT_SESSION_TOKEN_COOKIE_KEY } from "../shared/wire/LambderSessionCookieNames.js";
+import { readApiSignature } from "../shared/wire/LambderApiSignature.js";
 import { resolveApiOutcome } from "../shared/wire/LambderApiOutcome.js";
 import { mergeGuardInputs, } from "../shared/wire/LambderCallOptions.js";
 import { createCallAbort, stopWaitingWhenAborted } from "../shared/util/LambderCallAbort.js";
@@ -44,6 +45,7 @@ export default class LambderInvokeCaller {
     functionName;
     apiPath;
     apiVersion;
+    apiSignatures;
     host;
     requestCompression;
     maxResponsePayloadBytes;
@@ -57,7 +59,7 @@ export default class LambderInvokeCaller {
     client;
     sdk;
     constructor(options) {
-        const { functionName, client, clientConfig, apiPath, apiVersion, host, requestCompression, maxResponsePayloadBytes, timeoutMs, onLogList, onFailure, sessionTokenCookieKey, transport, guardInputsProvider, } = options;
+        const { functionName, client, clientConfig, apiPath, apiVersion, apiSignatures, host, requestCompression, maxResponsePayloadBytes, timeoutMs, onLogList, onFailure, sessionTokenCookieKey, transport, guardInputsProvider, } = options;
         if (!functionName?.trim())
             throw new Error("LambderInvokeCaller: functionName is required");
         this.functionName = functionName;
@@ -65,6 +67,7 @@ export default class LambderInvokeCaller {
         this.clientConfig = clientConfig;
         this.apiPath = apiPath ?? "/api";
         this.apiVersion = apiVersion;
+        this.apiSignatures = apiSignatures;
         this.host = host ?? functionName;
         // `?? false`: like the browser caller, off unless asked for.
         this.requestCompression = resolveCompressionOption(requestCompression ?? false, DEFAULT_INVOKE_REQUEST_COMPRESSION_SETTINGS);
@@ -93,6 +96,7 @@ export default class LambderInvokeCaller {
             body: buildEnvelopeJson({
                 apiName: init.apiName,
                 version: init.apiVersion,
+                signature: init.signature,
                 csrf: init.session?.csrf,
                 siteHost: host,
                 payloadJson: init.payload !== undefined ? JSON.stringify(init.payload) : undefined,
@@ -290,6 +294,10 @@ export default class LambderInvokeCaller {
         let event;
         let eventJson;
         try {
+            // The callee's signature for this endpoint, when this caller was
+            // built with the callee's map. A name the map lacks fails here,
+            // as a provider that threw would: the map predates the endpoint.
+            const signature = this.apiSignatures ? await readApiSignature(this.apiSignatures, apiName) : undefined;
             // Provider values underneath, per-call values on top.
             const provided = this.guardInputsProvider
                 ? await this.guardInputsProvider(apiName)
@@ -314,6 +322,7 @@ export default class LambderInvokeCaller {
                 body: buildEnvelopeJson({
                     apiName,
                     version: this.apiVersion,
+                    signature,
                     csrf: options.session?.csrf,
                     siteHost: this.host,
                     payloadJson: compressed ? undefined : payloadJson,

package/dist/invoke/LambderLambdaEvent.d.ts

@@ -57,6 +57,7 @@ export declare const synthesizeLambdaHttpEvent: (request: LambderSynthesizedRequ
 export declare const buildEnvelopeJson: (fields: {
     apiName: string;
     version?: string;
+    signature?: string;
     csrf?: string;
     siteHost: string;
     /** The payload's own JSON, when it goes plainly. */

package/dist/invoke/LambderLambdaEvent.js

@@ -117,6 +117,7 @@ export const buildEnvelopeJson = (fields) => {
     const withoutPayload = JSON.stringify(buildEnvelopeFields({
         apiName: fields.apiName,
         version: fields.version,
+        signature: fields.signature,
         token: fields.csrf ?? "",
         siteHost: fields.siteHost,
         compressed: fields.compressed,

package/dist/mock/LambderMockApp.d.ts

@@ -16,7 +16,7 @@ import type { LambderMockCallContext, LambderMockCallRecord, LambderMockEntry, L
  * Lambda server runs) over memory stores, with a registry of typed mock
  * handlers where the server has app handlers, and mock guards where it has
  * app guards. Everything the protocol does (envelope, refusals, sessions
- * and their cookies, guards, rate limits, idempotency, the version gate)
+ * and their cookies, guards, rate limits, idempotency, the signature gate)
  * happens in the core; this class only resolves a name to an entry, wraps
  * the handler's return into the envelope, and adds what a mock needs on
  * top: failure injection, latency, a subscription, a call log, reset.
@@ -176,7 +176,7 @@ export declare class LambderMockApp<C extends LambderApiContractShape, S = any,
      *
      * Public because the mode of an unregistered name cannot be recovered at
      * runtime, the contract being a type. Everything that precedes dispatch
-     * still runs (the version gate, the payload restore); the session read is
+     * still runs (the signature gate, the payload restore); the session read is
      * the one step this answer cannot have, which is the fidelity limit
      * restNotMocked documents.
      */

package/dist/mock/LambderMockApp.js

@@ -40,7 +40,7 @@ const defaultCookieHost = () => globalThis.location?.host || "localhost";
  * Lambda server runs) over memory stores, with a registry of typed mock
  * handlers where the server has app handlers, and mock guards where it has
  * app guards. Everything the protocol does (envelope, refusals, sessions
- * and their cookies, guards, rate limits, idempotency, the version gate)
+ * and their cookies, guards, rate limits, idempotency, the signature gate)
  * happens in the core; this class only resolves a name to an entry, wraps
  * the handler's return into the envelope, and adds what a mock needs on
  * top: failure injection, latency, a subscription, a call log, reset.
@@ -118,6 +118,8 @@ export class LambderMockApp {
         this.idempotencyStore = memoryIdempotency;
         this.pipeline = new LambderApiPipeline({
             apiVersion: this.apiVersion,
+            minApiVersion: options.minApiVersion,
+            apiSignatures: options.apiSignatures,
             maxRequestPayloadBytes: options.maxRequestPayloadBytes,
             sessions: sessionOptions
                 ? {
@@ -351,7 +353,7 @@ export class LambderMockApp {
      *
      * Public because the mode of an unregistered name cannot be recovered at
      * runtime, the contract being a type. Everything that precedes dispatch
-     * still runs (the version gate, the payload restore); the session read is
+     * still runs (the signature gate, the payload restore); the session read is
      * the one step this answer cannot have, which is the fidelity limit
      * restNotMocked documents.
      */
@@ -549,7 +551,7 @@ export class LambderMockApp {
         return {
             phase: "request", id, apiName: request.apiName, mode,
             payload: request.payload, guardInputs: request.guardInputs, idempotencyKey: request.idempotencyKey,
-            version: request.version, headers: request.headers,
+            version: request.version, signature: request.signature, headers: request.headers,
             hasSessionCookie: (request.cookies[this.tokenCookieKey]?.length ?? 0) > 0,
             at,
         };
@@ -595,7 +597,7 @@ export class LambderMockApp {
         try {
             // The protocol's pre-pass, run before the name is resolved, which
             // is where the server runs it. Two things depended on it: an
-            // unknown name reached the notFound refusal without the version
+            // unknown name reached the notFound refusal without the signature
             // gate or the payload restore, so a stale client or a malformed
             // compressed payload was answered differently here than on the
             // server; and the request event carried the wire fields instead of

package/dist/mock/LambderMockCreateOptions.d.ts

@@ -1,3 +1,4 @@
+import type { LambderApiSignatureMap } from "../shared/wire/LambderApiSignature.js";
 import type { LambderContractGuardNames } from "../shared/wire/LambderApiContract.js";
 import type { LambderApiGuard } from "../api/LambderApiGuards.js";
 import type { LambderApiRateLimitPolicyConfig } from "../api/LambderApiRateLimits.js";
@@ -99,8 +100,12 @@ type LambderMockGuardShapes<S, G> = {
     [N in keyof G]: LambderMockSurplusKeys<G[N], LambderApiGuard<any, any, any, LambderMockCallContext<S>, LambderMockSessionCallContext<S>>>;
 };
 export type LambderMockAppOptions<C, S, G, P extends LambderMockRateLimitPolicies<S> = LambderMockRateLimitPolicies<S>, I extends boolean | LambderMockIdempotencyOptions<S> = boolean | LambderMockIdempotencyOptions<S>> = LambderMockGuardsOption<C, S, G> & {
-    /** Enables the version gate: a call naming another version answers versionExpired, exactly as the server would. */
+    /** Stamped on every answer's envelope as apiVersion, as the server's option is. */
     apiVersion?: string;
+    /** The version floor, as on the server: a call naming a lower `version` answers versionExpired whatever its signature says. */
+    minApiVersion?: string;
+    /** The generated signature map, as the server's option is: a call whose signature is not the map's entry for its endpoint answers versionExpired. Without it every signature passes. */
+    apiSignatures?: LambderApiSignatureMap;
     /** Artificial latency per call; off by default. */
     latency?: LambderMockLatency;
     /** Sessions over the memory store: `true` for the defaults, or the options. Off by default: session endpoints then fail at registration. */