lambder 7.1.4 → 7.2.0

package/CHANGELOG.md

@@ -9,6 +9,58 @@ sit on its first published patch, and later patches list only what they changed.
 Releases up to 3.2.6 carry git tags; the ones after it were published without
 one, so versions are not cross-linked to tag comparisons here.
 
+## [7.1.5] - 2026-09-15
+
+### Added
+
+- **`minApiVersion`**, on `create()` and on the mock runtime: a floor under
+  the signature gate. A call naming a `version` below it answers
+  `versionExpired` whatever its signature says, which is the lever for a
+  change the digest cannot see (a security fix, a field whose meaning changed
+  under the same shape). Versions compare as dotted numbers, so `1.2.10` is
+  above `1.2.9`; a call naming no version is not judged, as one carrying no
+  signature is not gated. Creation refuses a floor that is not a dotted
+  version; a floor above `apiVersion` is taken as `apiVersion`, with a
+  warning, so a mistaken floor cannot refuse the build's own clients.
+  `compareDottedVersions` and `isDottedVersion` are exported from both
+  entries.
+
+### Changed
+
+- **`apiNameKeyOf` memoizes nothing.** It hashed each name it was asked about
+  into a module-level map, kept for the life of the process. On the server
+  that name comes off the wire, in the pre-pass that runs before anything has
+  checked that it is an endpoint at all and before any rate limit, so a
+  request naming anything grew the map by an entry, and one naming a
+  megabyte's worth grew it by a megabyte. Nothing is kept now: the digest the
+  gate rests on is the generator's, computed once at build time, and what is
+  left per call is one hash of a short name against a map already in memory.
+- **`apiVersion` must be a dotted version** (`"1.2.10"`), on `create()` and on
+  the mock runtime, where any string was taken before. `minApiVersion` reads
+  it as numbers, and a stamp the comparison cannot read (`"dev"`, a commit
+  sha, a build date) counted as zero, so setting a floor answered
+  `versionExpired` to every client of the build that set it. The clamp that
+  exists to stop exactly that could not see the case. Creation refuses it
+  instead, whether or not a floor is set today.
+- **The server reads the generated map too.** `create()` takes
+  `apiSignatures`, the same file the frontend ships with, and the pipeline
+  compares a call's signature with the map's entry; nothing is digested at
+  request time any more. The one computation is the generator's, so a schema
+  digested differently on two builds costs its clients one reload per deploy
+  and can no longer leave an endpoint refused for every caller.
+  `LambderApiSignatureDigests` and the `LambderApiSignatureSource` type are
+  gone, and `LambderApiPipeline.prepare(request)` takes no definition. A
+  server given no map gates nothing, as the mock runtime does.
+- **The signature digest hashes shape, not values.** The `default` keyword
+  zod emits is dropped before hashing: a default's value is server
+  behaviour, and for a function default (`.default(() => new Date())`,
+  `.prefault`, `.catch`) zod wrote whatever the function returned at
+  conversion, so the endpoint digested differently on every computation and
+  the generated map could never match the server. Whether the field may be
+  omitted still counts, through `required`, which is now sorted as well so
+  that reordering fields changes nothing. Endpoints with a defaulted field
+  get a new signature once.
+
 ## [7.1.1] - 2026-09-15
 
 The version gate is replaced by a signature gate: whether a client is stale is

package/dist/api/LambderApiPipeline.d.ts

@@ -4,7 +4,7 @@ import type { LambderApiAnswer } from "./LambderApiAnswer.js";
 import type { LambderApiCallContext } from "./LambderApiCallContext.js";
 import type { LambderApiCallTrace } from "./LambderApiCallContext.js";
 import type { LambderApiDefinition } from "./LambderApiDefinition.js";
-import type { LambderApiSignatureSource } from "./LambderApiSignature.js";
+import { type LambderApiSignatureMap } from "../shared/wire/LambderApiSignature.js";
 import type { LambderApiGuard } from "./LambderApiGuards.js";
 import type { LambderApiRateLimitPolicyConfig, LambderApiRateLimitsConfig } from "./LambderApiRateLimits.js";
 import type { LambderApiIdempotencyConfig } from "./LambderApiIdempotency.js";
@@ -32,12 +32,21 @@ export type LambderApiPipelineOptions<TCtx extends LambderApiCallContext<TSessio
     /** Stamped on every answer's envelope as apiVersion, so a client can tell which build answered; null when the app set none. */
     apiVersion?: string | null;
     /**
-     * Enables the signature gate: a request carrying a signature that is not
-     * the one this source expects for its endpoint answers versionExpired.
-     * Without a source every signature passes, which is what the mock runtime
-     * does unless it is given the generated map.
+     * The floor under the signature gate: a request naming a `version` below
+     * it answers versionExpired whatever its signature says. Dotted numbers
+     * ("1.2.10"), compared segment by segment. A floor above apiVersion is
+     * taken as apiVersion, so a mistaken floor cannot refuse the build's own
+     * clients.
      */
-    signatures?: LambderApiSignatureSource;
+    minApiVersion?: string | null;
+    /**
+     * Enables the signature gate: the generated map (Lambder.apiSignatures(),
+     * the same file the client ships with). A request carrying a signature
+     * that is not the map's entry for its endpoint answers versionExpired,
+     * and so does one for an endpoint the map does not hold: that client was
+     * built against another contract. Without a map every signature passes.
+     */
+    apiSignatures?: LambderApiSignatureMap;
     /** Ceiling on what a compressed request payload may restore to. Default: 20,000,000. */
     maxRequestPayloadBytes?: number;
     onInvalidInput?: LambderApiInputRefusal<TCtx>;
@@ -60,7 +69,7 @@ export type LambderApiExec<TCtx> = (ctx: TCtx) => Promise<LambderApiAnswer>;
  * are adapters over this class; neither reimplements a step of it.
  *
  * ```
- * signature gate → restore payload → rate limits that need no session
+ * version floor → signature gate → restore payload → rate limits that need no session
  * → session (session mode) → idempotency replay → the remaining rate limits
  * → guards → input validation → exec, inside the idempotency claim
  * → drain response headers → answer
@@ -79,11 +88,12 @@ export type LambderApiExec<TCtx> = (ctx: TCtx) => Promise<LambderApiAnswer>;
  */
 export declare class LambderApiPipeline<TCtx extends LambderApiCallContext<TSessionData>, TSessionData = any> {
     readonly apiVersion: string | null;
+    readonly minApiVersion: string | null;
     private readonly policies;
     private readonly maxRequestPayloadBytes;
     private readonly onInvalidInput;
     private readonly sessions;
-    private readonly signatures;
+    private readonly apiSignatures;
     constructor(options?: LambderApiPipelineOptions<TCtx, TSessionData>);
     /** True when a session manager was configured. */
     get hasSessions(): boolean;
@@ -103,23 +113,27 @@ export declare class LambderApiPipeline<TCtx extends LambderApiCallContext<TSess
      * The answer for a request naming no registered API: the apiNotFound
      * refusal, carrying whatever the call already wrote (a CORS header, a
      * cookie eviction). No signature gate here: both adapters run prepare()
-     * on the way in, with the definition the name resolved to or null, so a
-     * signed request for an unknown name (a client built against a contract
-     * that had it) has already been answered versionExpired by the time
-     * anything asks for an unknown name.
+     * on the way in, so a signed request for a name the map does not hold (a
+     * client built against a contract that had it) has already been answered
+     * versionExpired by the time anything asks for an unknown name.
      */
     answerUnknownApi(request: LambderApiRequest, ctx?: TCtx): LambderApiAnswer;
     /**
-     * The steps that come before anything may read the request: the
-     * signature gate, then the compressed-payload restore that every later
-     * reader (a rate-limit key slice, a guard, the input schema) depends on
-     * having happened.
+     * The steps that come before anything may read the request: the version
+     * floor, the signature gate, then the compressed-payload restore that
+     * every later reader (a rate-limit key slice, a guard, the input schema)
+     * depends on having happened.
+     *
+     * The floor answers versionExpired to a request naming a version below
+     * minApiVersion whatever its signature says: the lever for a change the
+     * digest cannot see (a security fix, a field whose meaning changed under
+     * the same shape). A request naming no version is not judged by it, as
+     * one carrying no signature is not gated.
      *
-     * The gate compares the signature the request carries with the one the
-     * source expects for the endpoint the name resolved to (`definition`,
-     * null for a name the adapter does not know). A match runs; anything
-     * else is a client built against another shape of this endpoint, or
-     * against an endpoint that no longer exists, and is answered
+     * The gate compares the signature the request carries with the map's
+     * entry for the endpoint it names. A match runs; anything else, another
+     * entry or none, is a client built against another shape of this
+     * endpoint or against an endpoint that no longer exists, and is answered
      * versionExpired. A request carrying no signature is never gated.
      *
      * Public and named because the server runs them earlier than run() does,
@@ -127,13 +141,13 @@ export declare class LambderApiPipeline<TCtx extends LambderApiCallContext<TSess
      * is answered before any of them, whether or not the name it asked for
      * exists. run() calls it too, so an adapter that has no such step still
      * gets the whole protocol. Calling it twice is safe by construction: the
-     * gate compares against a memoized digest and the restore has already
-     * removed the wire fields it reads.
+     * gates are comparisons and the restore has already removed the wire
+     * fields it reads.
      *
      * Returns the answer that ends the call, or null when the request is
      * ready to dispatch.
      */
-    prepare(request: LambderApiRequest, definition: LambderApiDefinition | null): Promise<LambderApiAnswer | null>;
+    prepare(request: LambderApiRequest): Promise<LambderApiAnswer | null>;
     /**
      * One call, one answer. Refusals are rendered; crashes propagate.
      *

package/dist/api/LambderApiPipeline.js

@@ -1,9 +1,11 @@
 import { restoreCompressedPayload } from "./LambderApiRequest.js";
+import { lookupApiSignature } from "../shared/wire/LambderApiSignature.js";
 import { apiNotFoundAnswer, invalidPayloadAnswer, refusalAnswer, sessionExpiredAnswer, validationAnswer, versionExpiredAnswer, } from "./LambderApiEnvelope.js";
 import { LambderApiValidationRefusal, isLambderApiValidationRefusal } from "./LambderApiValidationRefusal.js";
 import { isLambderApiRefusal } from "../shared/wire/LambderApiRefusal.js";
 import { DEFAULT_MAX_RESTORED_PAYLOAD_BYTES } from "../shared/wire/LambderRequestPayload.js";
 import { assertPositiveInteger } from "../shared/util/LambderOptionChecks.js";
+import { compareDottedVersions, isDottedVersion } from "../shared/wire/LambderVersionOrder.js";
 import { LambderApiPolicyEngine } from "./LambderApiPolicyEngine.js";
 import LambderSessionController, { assertSessionCookiePrefixes, } from "../session/LambderSessionController.js";
 import { DEFAULT_SESSION_CSRF_COOKIE_KEY, DEFAULT_SESSION_TOKEN_COOKIE_KEY } from "../shared/wire/LambderSessionCookieNames.js";
@@ -13,7 +15,7 @@ import { DEFAULT_SESSION_CSRF_COOKIE_KEY, DEFAULT_SESSION_TOKEN_COOKIE_KEY } fro
  * are adapters over this class; neither reimplements a step of it.
  *
  * ```
- * signature gate → restore payload → rate limits that need no session
+ * version floor → signature gate → restore payload → rate limits that need no session
  * → session (session mode) → idempotency replay → the remaining rate limits
  * → guards → input validation → exec, inside the idempotency claim
  * → drain response headers → answer
@@ -32,14 +34,37 @@ import { DEFAULT_SESSION_CSRF_COOKIE_KEY, DEFAULT_SESSION_TOKEN_COOKIE_KEY } fro
  */
 export class LambderApiPipeline {
     apiVersion;
+    minApiVersion;
     policies = new LambderApiPolicyEngine();
     maxRequestPayloadBytes;
     onInvalidInput;
     sessions;
-    signatures;
+    apiSignatures;
     constructor(options = {}) {
         this.apiVersion = options.apiVersion ?? null;
-        this.signatures = options.signatures ?? null;
+        // Dotted, always, whether or not a floor is set today: the floor reads
+        // this string as numbers, and a stamp the comparison cannot read
+        // ("dev", a commit sha) counts as 0, so setting minApiVersion later
+        // would answer versionExpired to every client of this very build.
+        if (this.apiVersion !== null && !isDottedVersion(this.apiVersion)) {
+            throw new Error(`Lambder: apiVersion must be a dotted version such as "1.2.10", got ${JSON.stringify(this.apiVersion)}.`);
+        }
+        this.minApiVersion = options.minApiVersion ?? null;
+        if (this.minApiVersion !== null) {
+            if (!isDottedVersion(this.minApiVersion)) {
+                throw new Error(`Lambder: minApiVersion must be a dotted version such as "1.2.10", got ${JSON.stringify(this.minApiVersion)}.`);
+            }
+            // A floor above the version this server stamps on its answers
+            // would refuse the very clients this build serves, and the first
+            // symptom would be every tab reloading. The lower of the two is
+            // the most a floor can mean here, so that is what it becomes, and
+            // the mistake is said once at creation.
+            if (this.apiVersion !== null && compareDottedVersions(this.minApiVersion, this.apiVersion) > 0) {
+                console.warn(`Lambder: minApiVersion ${this.minApiVersion} is above apiVersion ${this.apiVersion}; the floor is taken as ${this.apiVersion}.`);
+                this.minApiVersion = this.apiVersion;
+            }
+        }
+        this.apiSignatures = options.apiSignatures ?? null;
         this.maxRequestPayloadBytes = assertPositiveInteger(options.maxRequestPayloadBytes ?? DEFAULT_MAX_RESTORED_PAYLOAD_BYTES, "maxRequestPayloadBytes");
         this.onInvalidInput = options.onInvalidInput ?? null;
         this.sessions = options.sessions
@@ -96,10 +121,9 @@ export class LambderApiPipeline {
      * The answer for a request naming no registered API: the apiNotFound
      * refusal, carrying whatever the call already wrote (a CORS header, a
      * cookie eviction). No signature gate here: both adapters run prepare()
-     * on the way in, with the definition the name resolved to or null, so a
-     * signed request for an unknown name (a client built against a contract
-     * that had it) has already been answered versionExpired by the time
-     * anything asks for an unknown name.
+     * on the way in, so a signed request for a name the map does not hold (a
+     * client built against a contract that had it) has already been answered
+     * versionExpired by the time anything asks for an unknown name.
      */
     answerUnknownApi(request, ctx) {
         const answer = apiNotFoundAnswer(this.apiVersion, ctx?.logList);
@@ -107,16 +131,21 @@ export class LambderApiPipeline {
         return answer;
     }
     /**
-     * The steps that come before anything may read the request: the
-     * signature gate, then the compressed-payload restore that every later
-     * reader (a rate-limit key slice, a guard, the input schema) depends on
-     * having happened.
+     * The steps that come before anything may read the request: the version
+     * floor, the signature gate, then the compressed-payload restore that
+     * every later reader (a rate-limit key slice, a guard, the input schema)
+     * depends on having happened.
+     *
+     * The floor answers versionExpired to a request naming a version below
+     * minApiVersion whatever its signature says: the lever for a change the
+     * digest cannot see (a security fix, a field whose meaning changed under
+     * the same shape). A request naming no version is not judged by it, as
+     * one carrying no signature is not gated.
      *
-     * The gate compares the signature the request carries with the one the
-     * source expects for the endpoint the name resolved to (`definition`,
-     * null for a name the adapter does not know). A match runs; anything
-     * else is a client built against another shape of this endpoint, or
-     * against an endpoint that no longer exists, and is answered
+     * The gate compares the signature the request carries with the map's
+     * entry for the endpoint it names. A match runs; anything else, another
+     * entry or none, is a client built against another shape of this
+     * endpoint or against an endpoint that no longer exists, and is answered
      * versionExpired. A request carrying no signature is never gated.
      *
      * Public and named because the server runs them earlier than run() does,
@@ -124,15 +153,18 @@ export class LambderApiPipeline {
      * is answered before any of them, whether or not the name it asked for
      * exists. run() calls it too, so an adapter that has no such step still
      * gets the whole protocol. Calling it twice is safe by construction: the
-     * gate compares against a memoized digest and the restore has already
-     * removed the wire fields it reads.
+     * gates are comparisons and the restore has already removed the wire
+     * fields it reads.
      *
      * Returns the answer that ends the call, or null when the request is
      * ready to dispatch.
      */
-    async prepare(request, definition) {
-        if (request.signature !== null && this.signatures) {
-            const expected = await this.signatures.expectedSignatureOf(request.apiName, definition);
+    async prepare(request) {
+        if (this.minApiVersion !== null && request.version !== null && compareDottedVersions(request.version, this.minApiVersion) < 0) {
+            return versionExpiredAnswer(this.apiVersion);
+        }
+        if (request.signature !== null && this.apiSignatures) {
+            const expected = await lookupApiSignature(this.apiSignatures, request.apiName);
             if (expected !== request.signature)
                 return versionExpiredAnswer(this.apiVersion);
         }
@@ -175,7 +207,7 @@ export class LambderApiPipeline {
         return { answer, ...trace };
     }
     async execute(request, ctx, definition, exec, trace) {
-        const unprepared = await this.prepare(request, definition);
+        const unprepared = await this.prepare(request);
         if (unprepared)
             return unprepared;
         // The limits whose key is known from the request alone, before the

package/dist/api/LambderApiSignature.d.ts

@@ -1,16 +1,5 @@
 import type { LambderApiDefinition } from "./LambderApiDefinition.js";
 import { type LambderApiGuard } from "./LambderApiGuards.js";
-/**
- * Where the pipeline asks what signature a request should carry. Null for
- * an endpoint the source does not know, so a signed call for a name the
- * server does not have is answered versionExpired rather than apiNotFound:
- * the client was built against a contract that had it. The server answers
- * from its own schemas (LambderApiSignatureDigests); the mock runtime, which
- * holds no server schema, answers from the generated map when given one.
- */
-export type LambderApiSignatureSource = {
-    expectedSignatureOf(apiName: string, definition: LambderApiDefinition | null): Promise<string | null>;
-};
 /**
  * The digest of an endpoint's client-facing shape: its name and mode, its
  * input and output schemas as JSON Schema, every guard it declares with the
@@ -22,20 +11,9 @@ export type LambderApiSignatureSource = {
  *
  * The description is hashed as built, descriptions and titles included: a
  * schema is what the server says it is, and a client built against a
- * different one reloads once.
+ * different one reloads once. What must hold for the digest to mean anything
+ * is that a schema is built from static values: one that reads the clock, a
+ * random source or the environment at construction digests differently in
+ * the generator's process and on the server.
  */
 export declare const apiSignatureOf: (definition: LambderApiDefinition, guards: Record<string, LambderApiGuard<any, any, any>> | undefined) => Promise<string>;
-/**
- * The server's signature source: every registered endpoint digested from
- * its own schemas, once per endpoint per container, on first use. What
- * Lambder.apiSignatures() reads to build the client's map, and what the
- * pipeline compares a request's signature against.
- */
-export declare class LambderApiSignatureDigests implements LambderApiSignatureSource {
-    private readonly guards;
-    private readonly digests;
-    constructor(guards: Record<string, LambderApiGuard<any, any, any>> | undefined);
-    /** The endpoint's signature, computed on the first ask and kept. A digest that failed is not kept, so the next call tries again rather than failing forever. */
-    signatureOf(definition: LambderApiDefinition): Promise<string>;
-    expectedSignatureOf(apiName: string, definition: LambderApiDefinition | null): Promise<string | null>;
-}

package/dist/api/LambderApiSignature.js

@@ -2,6 +2,13 @@ import { z } from "zod";
 import { toGuardEntries } from "./LambderApiGuards.js";
 import { API_SIGNATURE_HEX_LENGTH } from "../shared/wire/LambderApiSignature.js";
 import { sha256HexOf } from "../shared/util/LambderTextDigest.js";
+/*
+ * The digest of an endpoint's client-facing shape, computed once, by the
+ * generator, through Lambder.apiSignatures(). Nothing digests at request
+ * time: the server and the client both carry the generated map and the
+ * pipeline compares entries, so the one computation has nothing to agree
+ * with but itself. See LambderApiSignatureMap.
+ */
 /**
  * JSON with object keys sorted at every level, so two descriptions of the
  * same shape hash the same whatever order they were built in. Arrays keep
@@ -23,12 +30,33 @@ const sortKeys = (value) => {
     return sorted;
 };
 /**
- * A schema as JSON Schema, exactly as zod emits it. A type JSON Schema
- * cannot express (a transform's output, a custom check) becomes `{}` rather
- * than throwing, because a digest has to exist for every endpoint; what the
- * digest cannot see is documented with it.
+ * Two edits to every node zod emits, before it is hashed.
+ *
+ * The `default` keyword goes. Its value is server behaviour, not shape: a
+ * client never sends it, and its compiled types do not carry it. And for a
+ * function default (`.default(() => new Date())`, `.prefault`, `.catch`)
+ * zod writes whatever the function returned at conversion time, a clock
+ * reading or a random value, which would give the endpoint a different
+ * digest on every computation and a generated map that never matches the
+ * server. Nothing distinguishes such a default from a constant one once zod
+ * has evaluated it, so every default goes, and the one thing about a default
+ * a client can see, that the field may be omitted, stays through `required`.
+ *
+ * `required` is sorted. It is a set, and the order fields are declared in is
+ * not shape either; left as emitted, reordering two fields forced a reload.
+ */
+const keepShapeOnly = (node) => {
+    delete node.default;
+    if (Array.isArray(node.required))
+        node.required.sort();
+};
+/**
+ * A schema as JSON Schema, as zod emits it minus what keepShapeOnly removes.
+ * A type JSON Schema cannot express (a transform's output, a custom check)
+ * becomes `{}` rather than throwing, because a digest has to exist for every
+ * endpoint; what the digest cannot see is documented with it.
  */
-const jsonSchemaOf = (schema, io) => schema ? z.toJSONSchema(schema, { io, unrepresentable: "any" }) : null;
+const jsonSchemaOf = (schema, io) => schema ? z.toJSONSchema(schema, { io, unrepresentable: "any", override: ({ jsonSchema }) => keepShapeOnly(jsonSchema) }) : null;
 const ownGuard = (guards, name) => guards !== undefined && Object.prototype.hasOwnProperty.call(guards, name) ? guards[name] : undefined;
 /**
  * The digest of an endpoint's client-facing shape: its name and mode, its
@@ -41,7 +69,10 @@ const ownGuard = (guards, name) => guards !== undefined && Object.prototype.hasO
  *
  * The description is hashed as built, descriptions and titles included: a
  * schema is what the server says it is, and a client built against a
- * different one reloads once.
+ * different one reloads once. What must hold for the digest to mean anything
+ * is that a schema is built from static values: one that reads the clock, a
+ * random source or the environment at construction digests differently in
+ * the generator's process and on the server.
  */
 export const apiSignatureOf = async (definition, guards) => {
     const guardShapes = toGuardEntries(definition.guards).map(({ name }) => {
@@ -63,29 +94,3 @@ export const apiSignatureOf = async (definition, guards) => {
     const hex = await sha256HexOf(canonicalJson(description));
     return hex.slice(0, API_SIGNATURE_HEX_LENGTH);
 };
-/**
- * The server's signature source: every registered endpoint digested from
- * its own schemas, once per endpoint per container, on first use. What
- * Lambder.apiSignatures() reads to build the client's map, and what the
- * pipeline compares a request's signature against.
- */
-export class LambderApiSignatureDigests {
-    guards;
-    digests = new Map();
-    constructor(guards) {
-        this.guards = guards;
-    }
-    /** The endpoint's signature, computed on the first ask and kept. A digest that failed is not kept, so the next call tries again rather than failing forever. */
-    signatureOf(definition) {
-        let pending = this.digests.get(definition.name);
-        if (!pending) {
-            pending = apiSignatureOf(definition, this.guards);
-            this.digests.set(definition.name, pending);
-            pending.catch(() => this.digests.delete(definition.name));
-        }
-        return pending;
-    }
-    async expectedSignatureOf(apiName, definition) {
-        return definition ? await this.signatureOf(definition) : null;
-    }
-}

package/dist/client.d.ts

@@ -18,6 +18,7 @@ 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

@@ -17,6 +17,7 @@ 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

@@ -69,10 +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;
-    /** Every registered API by name: what resolves a request's name to its definition ahead of the pipeline, and what apiSignatures() digests. */
+    /** Every registered API by name: the duplicate-name check, and what apiSignatures() digests. */
     private readonly apiDefinitions;
-    /** The signature of each endpoint as this server serves it, digested once per endpoint on first use. */
-    private readonly signatureDigests;
+    /** 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;
@@ -172,11 +172,13 @@ export default class Lambder<TSessionData = any, _TContract extends Record<strin
     getSessionManager(): LambderSessionManager<TSessionData>;
     /**
      * Every registered endpoint's signature, keyed by its hashed name: the
-     * LambderApiSignatureMap a client build ships with. A generator imports
-     * the finished instance, awaits this, and writes the result to a file the
-     * frontend passes to LambderCaller as apiSignatures; at request time the
-     * server compares each call's signature against these same digests. Keys
-     * are sorted, so the generated file diffs by endpoint.
+     * 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>;

package/dist/core/Lambder.js

@@ -10,7 +10,7 @@ import { LambderIndexHtmlHandler } from "./LambderIndexHtml.js";
 import { LambderFiles } from "./LambderFiles.js";
 import { isLambderApiRefusal } from "../shared/wire/LambderApiRefusal.js";
 import { LambderApiPipeline } from "../api/LambderApiPipeline.js";
-import { LambderApiSignatureDigests } from "../api/LambderApiSignature.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";
@@ -65,10 +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;
-    /** Every registered API by name: what resolves a request's name to its definition ahead of the pipeline, and what apiSignatures() digests. */
+    /** Every registered API by name: the duplicate-name check, and what apiSignatures() digests. */
     apiDefinitions = new Map();
-    /** The signature of each endpoint as this server serves it, digested once per endpoint on first use. */
-    signatureDigests;
+    /** 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;
@@ -101,10 +101,11 @@ export default class Lambder {
             this.corsConfig = options.cors === true ? {} : options.cors;
         }
         const session = options.session;
-        this.signatureDigests = new LambderApiSignatureDigests(options.guards);
+        this.guards = options.guards;
         this.pipeline = new LambderApiPipeline({
             apiVersion: this.apiVersion,
-            signatures: this.signatureDigests,
+            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.
@@ -288,14 +289,16 @@ export default class Lambder {
     }
     /**
      * Every registered endpoint's signature, keyed by its hashed name: the
-     * LambderApiSignatureMap a client build ships with. A generator imports
-     * the finished instance, awaits this, and writes the result to a file the
-     * frontend passes to LambderCaller as apiSignatures; at request time the
-     * server compares each call's signature against these same digests. Keys
-     * are sorted, so the generated file diffs by endpoint.
+     * 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 this.signatureDigests.signatureOf(definition)]));
+        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);
     }
@@ -424,9 +427,8 @@ export default class Lambder {
             // The protocol's own pre-pass, run here rather than left to the
             // pipeline so that hooks and route matching see a plain payload,
             // and so a stale client is answered before any of them, whether or
-            // not the name it asked for exists: the gate is handed the
-            // definition the name resolves to, or null.
-            const prepared = await this.pipeline.prepare(ctx.api, this.apiDefinitions.get(ctx.api.apiName) ?? null);
+            // not the name it asked for exists.
+            const prepared = await this.pipeline.prepare(ctx.api);
             if (prepared)
                 return responseFromAnswer(prepared);
             // ctx.post is the raw body view; it shows the restored payload and

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";
@@ -101,11 +102,33 @@ export type LambderCreateOptions<TSessionData = any> = {
     apiPath?: string;
     /**
      * Stamped on every API answer's envelope as `apiVersion`, so a client can
-     * tell which build answered. Informational: whether a client is stale is
-     * decided per endpoint by the signature it sends (see
-     * Lambder.apiSignatures()), not by this string.
+     * 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/index.d.ts

@@ -25,11 +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, LambderApiSignatureDigests } from "./api/LambderApiSignature.js";
-export type { LambderApiSignatureSource } from "./api/LambderApiSignature.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

@@ -17,9 +17,10 @@ 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, LambderApiSignatureDigests } from "./api/LambderApiSignature.js";
+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/mock/LambderMockApp.js

@@ -1,4 +1,3 @@
-import { lookupApiSignature } from "../shared/wire/LambderApiSignature.js";
 import { LambderApiPipeline } from "../api/LambderApiPipeline.js";
 import { readApiEnvelope, cookieValuesByName, lowercaseHeaderNames } from "../api/LambderApiRequest.js";
 import { createApiCallContext } from "../api/LambderApiCallContext.js";
@@ -117,13 +116,10 @@ export class LambderMockApp {
         const idempotencyOptions = options.idempotency === true ? {} : options.idempotency || null;
         const memoryIdempotency = idempotencyOptions && !idempotencyOptions.store ? new LambderMemoryIdempotencyStore() : null;
         this.idempotencyStore = memoryIdempotency;
-        // The generated map stands in for the server's schemas: the runtime
-        // cannot digest what it does not hold, so it answers with the map's
-        // entry for the name and the pipeline compares, as on the server.
-        const apiSignatures = options.apiSignatures;
         this.pipeline = new LambderApiPipeline({
             apiVersion: this.apiVersion,
-            signatures: apiSignatures ? { expectedSignatureOf: (apiName) => lookupApiSignature(apiSignatures, apiName) } : undefined,
+            minApiVersion: options.minApiVersion,
+            apiSignatures: options.apiSignatures,
             maxRequestPayloadBytes: options.maxRequestPayloadBytes,
             sessions: sessionOptions
                 ? {
@@ -599,18 +595,16 @@ export class LambderMockApp {
         let outcome;
         let error;
         try {
-            // The protocol's pre-pass, run ahead of dispatch with the
-            // definition the name resolved to (null for a name nothing
-            // registered), which is where the server runs it. Two things
-            // depended on it: an 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 the payload, so a dev panel
-            // watching calls in flight showed nothing for exactly the
-            // compressed calls someone opens a panel for. run() calls prepare
-            // again, which is safe by construction.
-            const prepared = await this.pipeline.prepare(request, registered?.definition ?? null);
+            // 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 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
+            // the payload, so a dev panel watching calls in flight showed
+            // nothing for exactly the compressed calls someone opens a panel
+            // for. run() calls prepare again, which is safe by construction.
+            const prepared = await this.pipeline.prepare(request);
             this.emit(this.requestEvent(id, request, mode, startedAt));
             await this.failures.wait(this.failures.latencyFor(request.apiName), request.signal);
             if (this.failures.offline)

package/dist/mock/LambderMockCreateOptions.d.ts

@@ -102,13 +102,9 @@ type LambderMockGuardShapes<S, G> = {
 export type LambderMockAppOptions<C, S, G, P extends LambderMockRateLimitPolicies<S> = LambderMockRateLimitPolicies<S>, I extends boolean | LambderMockIdempotencyOptions<S> = boolean | LambderMockIdempotencyOptions<S>> = LambderMockGuardsOption<C, S, G> & {
     /** Stamped on every answer's envelope as apiVersion, as the server's option is. */
     apiVersion?: string;
-    /**
-     * The generated signature map the caller carries, so the runtime refuses a
-     * stale signature exactly as the server would: a call whose signature is
-     * not the map's entry for its endpoint answers versionExpired. Without it
-     * every signature passes, since the runtime holds no server schema to
-     * digest.
-     */
+    /** 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;

package/dist/shared/wire/LambderApiSignature.d.ts

@@ -20,7 +20,20 @@ export type LambderApiSignatureMap = Record<string, string>;
  * the shapes one endpoint takes over its life, and the map stays small.
  */
 export declare const API_SIGNATURE_HEX_LENGTH = 16;
-/** The key an endpoint's signature is stored under: SHA-256 over the prefixed name, cut to API_SIGNATURE_HEX_LENGTH hex characters. */
+/**
+ * The key an endpoint's signature is stored under: SHA-256 over the prefixed
+ * name, cut to API_SIGNATURE_HEX_LENGTH hex characters. Async because
+ * WebCrypto's digest is, and it is the only SHA-256 a browser has.
+ *
+ * Computed on the spot, every time, and nothing is kept. The digest that
+ * actually describes an endpoint is the generator's, computed once at build
+ * time; what is left here is one hash of a short name against a map already
+ * in memory, which is nothing beside the request it belongs to. A cache of
+ * it would have to be keyed by name, and on the server the name comes off
+ * the wire before anything has checked that it is an endpoint at all, so it
+ * would grow by an entry for every name a request cared to invent and never
+ * shrink.
+ */
 export declare const apiNameKeyOf: (apiName: string) => Promise<string>;
 /** The map's signature for one endpoint, or null when the map holds none for it. */
 export declare const lookupApiSignature: (signatures: LambderApiSignatureMap, apiName: string) => Promise<string | null>;

package/dist/shared/wire/LambderApiSignature.js

@@ -7,20 +7,21 @@ import { sha256HexOf } from "../util/LambderTextDigest.js";
 export const API_SIGNATURE_HEX_LENGTH = 16;
 /** Domain-separated, so a name's key can never equal a signature computed over a description that happens to read the same. */
 const API_NAME_KEY_PREFIX = "lambder-api-name:";
-/** Memoized per name: a caller hashes each endpoint it calls once per process. */
-const nameKeys = new Map();
-/** The key an endpoint's signature is stored under: SHA-256 over the prefixed name, cut to API_SIGNATURE_HEX_LENGTH hex characters. */
-export const apiNameKeyOf = (apiName) => {
-    let pending = nameKeys.get(apiName);
-    if (!pending) {
-        pending = sha256HexOf(API_NAME_KEY_PREFIX + apiName).then((hex) => hex.slice(0, API_SIGNATURE_HEX_LENGTH));
-        nameKeys.set(apiName, pending);
-        // A failed digest (no WebCrypto) is not kept, so a later call in a
-        // context that has it succeeds instead of replaying the rejection.
-        pending.catch(() => nameKeys.delete(apiName));
-    }
-    return pending;
-};
+/**
+ * The key an endpoint's signature is stored under: SHA-256 over the prefixed
+ * name, cut to API_SIGNATURE_HEX_LENGTH hex characters. Async because
+ * WebCrypto's digest is, and it is the only SHA-256 a browser has.
+ *
+ * Computed on the spot, every time, and nothing is kept. The digest that
+ * actually describes an endpoint is the generator's, computed once at build
+ * time; what is left here is one hash of a short name against a map already
+ * in memory, which is nothing beside the request it belongs to. A cache of
+ * it would have to be keyed by name, and on the server the name comes off
+ * the wire before anything has checked that it is an endpoint at all, so it
+ * would grow by an entry for every name a request cared to invent and never
+ * shrink.
+ */
+export const apiNameKeyOf = async (apiName) => (await sha256HexOf(API_NAME_KEY_PREFIX + apiName)).slice(0, API_SIGNATURE_HEX_LENGTH);
 /** The map's signature for one endpoint, or null when the map holds none for it. */
 export const lookupApiSignature = async (signatures, apiName) => {
     const key = await apiNameKeyOf(apiName);

package/dist/shared/wire/LambderVersionOrder.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Dotted version strings ("1.2.10"), compared segment by segment as numbers,
+ * so "1.2.10" sorts after "1.2.9" where a string comparison would put it
+ * first. The server's version floor (minApiVersion) reads a caller's version
+ * this way, and an app deciding whether a client is behind can read the
+ * envelope's apiVersion the same way.
+ */
+/** True for one or more decimal segments joined by dots: "7", "1.2", "1.2.10". */
+export declare const isDottedVersion: (value: string) => boolean;
+/** -1 when `a` is older than `b`, 1 when newer, 0 when equal. A missing segment counts as 0, so "1.2" equals "1.2.0". */
+export declare const compareDottedVersions: (a: string, b: string) => -1 | 0 | 1;

package/dist/shared/wire/LambderVersionOrder.js

@@ -0,0 +1,28 @@
+/**
+ * Dotted version strings ("1.2.10"), compared segment by segment as numbers,
+ * so "1.2.10" sorts after "1.2.9" where a string comparison would put it
+ * first. The server's version floor (minApiVersion) reads a caller's version
+ * this way, and an app deciding whether a client is behind can read the
+ * envelope's apiVersion the same way.
+ */
+/** True for one or more decimal segments joined by dots: "7", "1.2", "1.2.10". */
+export const isDottedVersion = (value) => /^\d+(\.\d+)*$/.test(value);
+/** A segment as a number; anything that is not one counts as 0, so a version nothing can read sorts below every real one. */
+const segmentOf = (text) => {
+    const parsed = parseInt(text, 10);
+    return Number.isFinite(parsed) ? parsed : 0;
+};
+/** -1 when `a` is older than `b`, 1 when newer, 0 when equal. A missing segment counts as 0, so "1.2" equals "1.2.0". */
+export const compareDottedVersions = (a, b) => {
+    const left = a.split(".").map(segmentOf);
+    const right = b.split(".").map(segmentOf);
+    for (let i = 0; i < Math.max(left.length, right.length); i += 1) {
+        const x = left[i] ?? 0;
+        const y = right[i] ?? 0;
+        if (x < y)
+            return -1;
+        if (x > y)
+            return 1;
+    }
+    return 0;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lambder",
-  "version": "7.1.4",
+  "version": "7.2.0",
   "sideEffects": false,
   "description": "Opinionated serverless web framework for TypeScript on AWS Lambda: type-safe APIs from Zod schemas, DynamoDB sessions, and declarative rate limits, authorization guards and idempotency.",
   "keywords": [