lambder 14.1.1 → 15.0.2

package/dist/api/LambderApiGuards.d.ts

@@ -46,6 +46,23 @@ export type LambderGuardPlacement = {
     /** Default: "beforeInputValidation". */
     runAt?: LambderGuardRunAt;
 };
+/** What a `guardInput` guard's value is to an idempotency key's request. */
+export type LambderGuardInputUse = {
+    /**
+     * The value can differ between attempts of one operation: a single-use
+     * proof (a captcha token, a one-time code) or a credential refreshed
+     * between attempts (a short-lived token). A genuine retry may carry a new
+     * one, so the value is left out of the fingerprint that tells one request
+     * under an idempotency key from another; counted, it would turn the retry
+     * into a 409 and the person's next attempt into a second run. Default:
+     * false, the value counts, so the same key sent with
+     * another value (another store, another tenant) is refused as another
+     * request rather than replayed the first one's answer. Only a
+     * `guardInput` guard takes it: an `apiInput` guard's value is the
+     * payload's, which always counts.
+     */
+    singleUseInput?: boolean;
+};
 /**
  * The refusal codes a guard may refuse with, from the app's vocabulary (the
  * `refusals` option at creation). They join the codes of every API that
@@ -70,6 +87,13 @@ export type LambderGuardRefusals<TRefusals extends readonly string[] = readonly
  *   call that omits it. The API payload and handler never see the value.
  * - neither: the guard reads only the context.
  *
+ * A `guardInput` is part of what an idempotency key's request is, beside its
+ * payload: the same key sent with another value (another store, another
+ * tenant) is another request. A guard whose value can differ between
+ * attempts of one operation (a captcha token, a one-time code, a short-lived
+ * token refreshed in between) declares `singleUseInput: true`, and its value
+ * is left out of that, since a genuine retry may carry a new one.
+ *
  * Orthogonally, a guard may also:
  *
  * - declare `session: true`: the guard needs ctx.session, so it makes every
@@ -102,31 +126,35 @@ export type LambderGuardRefusals<TRefusals extends readonly string[] = readonly
 export type LambderApiGuard<TInput extends z.ZodType = z.ZodType, TParam = any, TOutput = any, TCtx = any, TSessionCtx = TCtx> = LambderGuardPlacement & LambderGuardRefusals & ({
     apiInput: TInput;
     guardInput?: undefined;
+    singleUseInput?: undefined;
     session: true;
     handler: LambderGuardHandler<TSessionCtx, z.output<TInput>, TParam, TOutput>;
 } | {
     apiInput: TInput;
     guardInput?: undefined;
+    singleUseInput?: undefined;
     session?: false;
     handler: LambderGuardHandler<TCtx, z.output<TInput>, TParam, TOutput>;
-} | {
+} | ({
     guardInput: TInput;
     apiInput?: undefined;
     session: true;
     handler: LambderGuardHandler<TSessionCtx, z.output<TInput>, TParam, TOutput>;
-} | {
+} & LambderGuardInputUse) | ({
     guardInput: TInput;
     apiInput?: undefined;
     session?: false;
     handler: LambderGuardHandler<TCtx, z.output<TInput>, TParam, TOutput>;
-} | {
+} & LambderGuardInputUse) | {
     apiInput?: undefined;
     guardInput?: undefined;
+    singleUseInput?: undefined;
     session: true;
     handler: LambderGuardHandler<TSessionCtx, undefined, TParam, TOutput>;
 } | {
     apiInput?: undefined;
     guardInput?: undefined;
+    singleUseInput?: undefined;
     session?: false;
     handler: LambderGuardHandler<TCtx, undefined, TParam, TOutput>;
 });
@@ -190,20 +218,22 @@ export type LambderGuardBuilder<TCtx, TSessionCtx, TVocabulary = never, TCodesRe
         guardInput: TInput;
         session: true;
         handler: (ctx: TSessionCtx & LambderGuardRefuse<TVocabulary, TRefusals, TCodesRequired>, payload: z.output<TInput>, param: TParam) => TOutput | Promise<TOutput>;
-    } & LambderGuardPlacement & LambderGuardRefusals<TRefusals> & LambderGuardRefusalsKnownIn<TVocabulary, TRefusals> & LambderGuardAnswerCheck<TOutput>): LambderGuardOf<TOutput, {
+    } & LambderGuardInputUse & LambderGuardPlacement & LambderGuardRefusals<TRefusals> & LambderGuardRefusalsKnownIn<TVocabulary, TRefusals> & LambderGuardAnswerCheck<TOutput>): LambderGuardOf<TOutput, {
         refusals?: NoInfer<TRefusals>;
         guardInput: TInput;
         apiInput?: undefined;
+        singleUseInput?: boolean;
         session: true;
         handler: (ctx: TSessionCtx, payload: z.output<TInput>, param: TParam) => TOutput | Promise<TOutput>;
     }>;
     <TInput extends z.ZodType, TParam = undefined, TOutput = void, const TRefusals extends readonly string[] = readonly []>(guard: {
         guardInput: TInput;
         handler: (ctx: TCtx & LambderGuardRefuse<TVocabulary, TRefusals, TCodesRequired>, payload: z.output<TInput>, param: TParam) => TOutput | Promise<TOutput>;
-    } & LambderGuardPlacement & LambderGuardRefusals<TRefusals> & LambderGuardRefusalsKnownIn<TVocabulary, TRefusals> & LambderGuardAnswerCheck<TOutput>): LambderGuardOf<TOutput, {
+    } & LambderGuardInputUse & LambderGuardPlacement & LambderGuardRefusals<TRefusals> & LambderGuardRefusalsKnownIn<TVocabulary, TRefusals> & LambderGuardAnswerCheck<TOutput>): LambderGuardOf<TOutput, {
         refusals?: NoInfer<TRefusals>;
         guardInput: TInput;
         apiInput?: undefined;
+        singleUseInput?: boolean;
         session?: undefined;
         handler: (ctx: TCtx, payload: z.output<TInput>, param: TParam) => TOutput | Promise<TOutput>;
     }>;
@@ -375,6 +405,15 @@ export declare class LambderApiGuardsEngine {
     configure(guards: Record<string, LambderApiGuard<any, any, any>>): void;
     /** Startup validation of one API registration's guards option. */
     assertRegistration(apiName: string, mode: LambderApiMode, guardsOption?: LambderGuardsOptionValue): void;
+    /**
+     * The posted guard inputs an idempotency fingerprint holds for an API
+     * declaring `guardsOption`: the value of each of its `guardInput` guards
+     * by name, except a guard's declared singleUseInput. Read as posted, as
+     * the payload is, before any guard parses it; a guard the client sent
+     * nothing for is left out. A null-prototype map, so a guard named
+     * "__proto__" is a key like any other.
+     */
+    fingerprintedInputsOf(request: LambderApiRequest, guardsOption: LambderGuardsOptionValue | undefined): Record<string, unknown>;
     /**
      * Run the API's guards that run at `runAt` (see LambderGuardRunAt) in
      * declared order. Refusals throw; outputs land on ctx.guardData; the

package/dist/api/LambderApiGuards.js

@@ -80,6 +80,13 @@ export class LambderApiGuardsEngine {
             if (runAt !== undefined && runAt !== "beforeInputValidation" && runAt !== "afterInputValidation") {
                 throw new Error(`Lambder: guard "${name}" has runAt "${String(runAt)}"; use "beforeInputValidation" (default) or "afterInputValidation".`);
             }
+            const singleUseInput = guardDef.singleUseInput;
+            if (singleUseInput !== undefined && typeof singleUseInput !== "boolean") {
+                throw new Error(`Lambder: guard "${name}" has singleUseInput ${String(singleUseInput)}; write true for a value a retry carries fresh, or leave it off.`);
+            }
+            if (singleUseInput && !guardDef.guardInput) {
+                throw new Error(`Lambder: guard "${name}" declares singleUseInput without a guardInput. Only a value the client sends beside the payload can be left out of an idempotent request's fingerprint; a slice of the payload always counts.`);
+            }
             this.guards.set(name, guardDef);
         }
     }
@@ -105,6 +112,26 @@ export class LambderApiGuardsEngine {
             }
         }
     }
+    /**
+     * The posted guard inputs an idempotency fingerprint holds for an API
+     * declaring `guardsOption`: the value of each of its `guardInput` guards
+     * by name, except a guard's declared singleUseInput. Read as posted, as
+     * the payload is, before any guard parses it; a guard the client sent
+     * nothing for is left out. A null-prototype map, so a guard named
+     * "__proto__" is a key like any other.
+     */
+    fingerprintedInputsOf(request, guardsOption) {
+        const inputs = Object.create(null);
+        for (const { name } of toGuardEntries(guardsOption)) {
+            const guardDef = this.guards.get(name);
+            if (!guardDef?.guardInput || guardDef.singleUseInput)
+                continue;
+            const input = readGuardInput(request.guardInputs, name);
+            if (input !== undefined)
+                inputs[name] = input;
+        }
+        return inputs;
+    }
     /**
      * Run the API's guards that run at `runAt` (see LambderGuardRunAt) in
      * declared order. Refusals throw; outputs land on ctx.guardData; the

package/dist/api/LambderApiIdempotency.d.ts

@@ -3,6 +3,7 @@ import type { LambderApiCallContext, LambderApiCallTrace } from "./LambderApiCal
 import type { LambderApiAnswer } from "./LambderApiAnswer.js";
 import type { LambderIdempotencyStore } from "../shared/contracts/LambderIdempotencyStore.js";
 import type { LambderApiIdempotencyOption } from "../shared/wire/LambderApiOptionValues.js";
+import type { LambderKeyFieldDigest } from "../shared/util/LambderKeyFieldDigest.js";
 import { LAMBDER_BACKEND_SWAP } from "../shared/util/LambderTestingDoors.js";
 export type LambderApiIdempotencyConfig = {
     /** Your idempotency store instance; may share the rate limiter's table (distinct key prefix). */
@@ -57,12 +58,14 @@ export type LambderIdempotentCall = {
 export declare class LambderApiIdempotencyEngine {
     /** Stamped on the crash answer the engine records for an answer that broke its output schema. */
     private readonly apiVersion;
+    /** What every caller-controlled field of a scope is written as. */
+    private readonly keyFieldDigest;
     private store;
     private defaultTtlSeconds;
     private defaultPendingTtlSeconds;
     private failOpen;
     private callerIdentity;
-    constructor(apiVersion: string | null);
+    constructor(apiVersion: string | null, keyFieldDigest: LambderKeyFieldDigest);
     configure(config: LambderApiIdempotencyConfig): void;
     /**
      * Puts the engine over another store, for `lambder/testing`; the replay
@@ -92,10 +95,12 @@ export declare class LambderApiIdempotencyEngine {
      * served before guards run.
      *
      * joinKeyFields escapes the fields, so no two distinct scopes collide.
-     * The identity field is the caller's (a device token in the docs' own
-     * example), so it is bounded first (boundKeyField): an over-long one
-     * would push the scope past a store's key limit, and the store's refusal
-     * is a throw that failOpen turns into no idempotency for that caller.
+     * Every field but the API name is the caller's (a session key, an
+     * identity such as the docs' device token, the posted key), so each is
+     * written as its digest (LambderKeyFieldDigest): a table read shows which
+     * API a record answers and never whose it is, and no field is long
+     * enough to push the scope past a store's key limit, whose refusal is a
+     * throw that failOpen turns into no idempotency for that caller.
      */
     private scopeOf;
     /**
@@ -105,9 +110,11 @@ export declare class LambderApiIdempotencyEngine {
      * refuses with a 400. Taken at the replay lookup, before input validation
      * replaces the payload with its parsed form, so the fingerprint is of the
      * request as it was posted, and callerIdentity (app code that may verify
-     * a token or read a store) runs once.
+     * a token or read a store) runs once. `guardInputs` are the posted guard
+     * inputs the fingerprint holds, as the guards engine picks them
+     * (fingerprintedInputsOf): the engine that knows which are single use.
      */
-    resolveKeyedCall(apiName: string, request: LambderApiRequest, ctx: LambderApiCallContext): Promise<LambderIdempotentCall | null>;
+    resolveKeyedCall(apiName: string, request: LambderApiRequest, ctx: LambderApiCallContext, guardInputs: Readonly<Record<string, unknown>>): Promise<LambderIdempotentCall | null>;
     /**
      * Replay fast path, run before guards and all rate limits except
      * `per: "ip"`: a completed record returns its stored answer, so a

package/dist/api/LambderApiIdempotency.js

@@ -1,7 +1,6 @@
 import { getAnswerHeader } from "../shared/wire/LambderAnswerHeaders.js";
 import { LambderApiRefusal, LAMBDER_REFUSAL_CODES } from "../shared/wire/LambderApiRefusal.js";
 import { joinKeyFields } from "../shared/util/joinKeyFields.js";
-import { boundKeyField } from "../shared/util/boundKeyField.js";
 import { assertPositiveInteger } from "../shared/util/LambderOptionChecks.js";
 import { LAMBDER_BACKEND_SWAP } from "../shared/util/LambderTestingDoors.js";
 import { canonicalJson } from "../shared/util/canonicalJson.js";
@@ -85,22 +84,26 @@ const keyReusedRefusal = (apiName) => new LambderApiRefusal(`Idempotency key reu
 });
 /**
  * A request's fingerprint: what makes two requests under one key the same
- * request. The payload as it was posted, as canonical JSON so key order does
- * not matter, digested so a record keeps 64 characters rather than the
- * payload. Guard inputs stay out: a captcha or proof token is single use, so
- * a genuine retry carries a new one, and a fingerprint over it would refuse
- * that retry as another request. A runtime without
- * WebCrypto (the mock on a page served over plain http, a phone on the LAN)
- * keeps the canonical JSON itself: a fingerprint is only compared with ones
- * the same runtime took, so its form does not matter, only that one payload
- * always gives the same one. Either form is non-empty (canonical JSON is at
- * least `null`), which is what lets a store report the empty string for a
- * record it cannot tie to any request.
+ * request. The payload as it was posted, beside the guard inputs that say
+ * what the call is about (see LambderApiGuardsEngine.fingerprintedInputsOf),
+ * as canonical JSON so key order does not matter, digested so a record keeps
+ * 64 characters rather than the request. A guard input selecting a store or
+ * a tenant is part of the request as surely as the payload is: left out, the
+ * same key sent for another tenant would replay the first tenant's answer. A
+ * guard input declared single use (a captcha token) is left out by the
+ * guards engine, since a genuine retry carries a fresh one.
+ *
+ * A runtime without WebCrypto (the mock on a page served over plain http, a
+ * phone on the LAN) keeps the canonical JSON itself: a fingerprint is only
+ * compared with ones the same runtime took, so its form does not matter,
+ * only that one request always gives the same one. Either form is non-empty,
+ * which is what lets a store report the empty string for a record it cannot
+ * tie to any request.
  */
-const requestFingerprintOf = async (payload) => {
+const requestFingerprintOf = async (payload, guardInputs) => {
     let canonical;
     try {
-        canonical = canonicalJson(payload ?? null);
+        canonical = canonicalJson({ payload: payload ?? null, guardInputs });
     }
     catch {
         // Sorting the keys recurses once per nesting level, so a payload
@@ -125,8 +128,9 @@ const requestFingerprintOf = async (payload) => {
  * is the right default, but silently it looks exactly like working: permanent
  * failures (a missing table, a missing IAM action, an SDK that would not
  * install) could have an app execute every retry twice for months with
- * nothing in its logs. The scope key is left out, since it carries the
- * caller's identity and posted key.
+ * nothing in its logs. The scope key is left out: digested as its caller's
+ * fields are, it is still the same for every attempt of one caller, and a
+ * log is read by more people than the table.
  */
 const reportFailOpen = (apiName, attempted, err) => {
     console.error(`Lambder idempotency: "${apiName}" could not ${attempted}; the request is being executed as if it carried no idempotency key. ` +
@@ -141,13 +145,16 @@ const reportFailOpen = (apiName, attempted, err) => {
 export class LambderApiIdempotencyEngine {
     /** Stamped on the crash answer the engine records for an answer that broke its output schema. */
     apiVersion;
+    /** What every caller-controlled field of a scope is written as. */
+    keyFieldDigest;
     store = null;
     defaultTtlSeconds = 24 * 3600;
     defaultPendingTtlSeconds = DEFAULT_IDEMPOTENCY_PENDING_TTL_SECONDS;
     failOpen = true;
     callerIdentity = undefined;
-    constructor(apiVersion) {
+    constructor(apiVersion, keyFieldDigest) {
         this.apiVersion = apiVersion;
+        this.keyFieldDigest = keyFieldDigest;
     }
     configure(config) {
         if (this.store)
@@ -210,22 +217,25 @@ export class LambderApiIdempotencyEngine {
      * served before guards run.
      *
      * joinKeyFields escapes the fields, so no two distinct scopes collide.
-     * The identity field is the caller's (a device token in the docs' own
-     * example), so it is bounded first (boundKeyField): an over-long one
-     * would push the scope past a store's key limit, and the store's refusal
-     * is a throw that failOpen turns into no idempotency for that caller.
+     * Every field but the API name is the caller's (a session key, an
+     * identity such as the docs' device token, the posted key), so each is
+     * written as its digest (LambderKeyFieldDigest): a table read shows which
+     * API a record answers and never whose it is, and no field is long
+     * enough to push the scope past a store's key limit, whose refusal is a
+     * throw that failOpen turns into no idempotency for that caller.
      */
     async scopeOf(apiName, ctx, request, key) {
+        const postedKey = await this.keyFieldDigest.digestOf("key", key);
         const sessionKey = ctx.session?.sessionKey;
         if (sessionKey)
-            return joinKeyFields(await boundKeyField("s", sessionKey), apiName, key);
+            return joinKeyFields(await this.keyFieldDigest.digestOf("s", sessionKey), apiName, postedKey);
         // No session to scope by. The app may still say who this is, through
         // callerIdentity; without one the key alone is the scope, which is
         // what makes it a bearer token for its own answer.
         const identity = this.callerIdentity ? await this.callerIdentity(ctx, request) : null;
         return identity
-            ? joinKeyFields(await boundKeyField("i", identity), apiName, key)
-            : joinKeyFields("k", apiName, key);
+            ? joinKeyFields(await this.keyFieldDigest.digestOf("i", identity), apiName, postedKey)
+            : joinKeyFields("k", apiName, postedKey);
     }
     /**
      * The call's key worked out, once per call: its scope and its request's
@@ -234,9 +244,11 @@ export class LambderApiIdempotencyEngine {
      * refuses with a 400. Taken at the replay lookup, before input validation
      * replaces the payload with its parsed form, so the fingerprint is of the
      * request as it was posted, and callerIdentity (app code that may verify
-     * a token or read a store) runs once.
+     * a token or read a store) runs once. `guardInputs` are the posted guard
+     * inputs the fingerprint holds, as the guards engine picks them
+     * (fingerprintedInputsOf): the engine that knows which are single use.
      */
-    async resolveKeyedCall(apiName, request, ctx) {
+    async resolveKeyedCall(apiName, request, ctx, guardInputs) {
         if (!this.store)
             return null;
         const key = this.readKey(request);
@@ -244,7 +256,7 @@ export class LambderApiIdempotencyEngine {
             return null;
         return {
             scopeKey: await this.scopeOf(apiName, ctx, request, key),
-            fingerprint: await requestFingerprintOf(request.payload),
+            fingerprint: await requestFingerprintOf(request.payload, guardInputs),
         };
     }
     /**

package/dist/api/LambderApiPipeline.d.ts

@@ -39,8 +39,7 @@ export type LambderApiPipelineOptions<TCtx extends LambderApiCallContext<TSessio
      * 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.
+     * refused at construction, since it would refuse the build's own clients.
      */
     minApiVersion?: string | null;
     /**
@@ -60,6 +59,16 @@ export type LambderApiPipelineOptions<TCtx extends LambderApiCallContext<TSessio
         session: LambderSessionRecord<TSessionData>;
     }>>;
     idempotency?: LambderApiIdempotencyConfig;
+    /**
+     * The app's at-rest secret: the session salt, which both adapters pass
+     * when sessions are configured. A subkey derived from it for this one
+     * purpose keys the digest every caller-controlled field of a rate-limit
+     * tracker key and an idempotency scope is written as
+     * (LambderKeyFieldDigest), so a table read can neither show who called
+     * nor test a guess. Without one the digest is a plain SHA-256, which
+     * keeps the values out of the table but lets a reader test guesses.
+     */
+    atRestSecret?: string;
 };
 /** The stores `lambder/testing` puts under a built pipeline. One the pipeline has no subsystem for is left aside. */
 export type LambderPipelineBackends = {
@@ -93,11 +102,11 @@ export type LambderApiExec<TCtx> = (ctx: TCtx) => Promise<LambderApiAnswer>;
  * are adapters over this class; neither reimplements a step of it.
  *
  * ```
- * version floor → signature gate → restore payload → rate limits keyed per ip
- * → session (session mode) → idempotency replay → rate limits keyed per session
- * (and custom keys charged beforeGuards) → guards → input validation → guards
- * placed after it → rate limits keyed by a custom key → exec, inside the
- * idempotency claim → drain response headers → answer
+ * envelope check → version floor → signature gate → restore payload → rate
+ * limits keyed per ip → session (session mode) → idempotency replay → rate
+ * limits keyed per session (and custom keys charged beforeGuards) → guards →
+ * input validation → guards placed after it → rate limits keyed by a custom
+ * key → exec, inside the idempotency claim → drain response headers → answer
  * ```
  *
  * Each policy subsystem (rate limits, guards, idempotency) is its own
@@ -182,10 +191,15 @@ export declare class LambderApiPipeline<TCtx extends LambderApiCallContext<TSess
      */
     answerRefusal(apiName: string, refusals: LambderEndpointRefusals | undefined, thrown: LambderApiRefusal, ctx: TCtx): Promise<LambderApiAnswer>;
     /**
-     * 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)
-     * relies on.
+     * The steps that come before anything may read the request: the
+     * envelope check, 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) relies on.
+     *
+     * A body that is no envelope (readApiEnvelope flagged it invalidEnvelope)
+     * carries nothing to call with, no payload, version or signature, and is
+     * answered with the invalid-payload refusal, here, so every adapter
+     * refuses it alike.
      *
      * The floor refuses a request naming a version below minApiVersion,
      * whatever its signature says: the lever for a change the digest cannot

package/dist/api/LambderApiPipeline.js

@@ -11,6 +11,7 @@ import { LambderApiGuardsEngine } from "./LambderApiGuards.js";
 import { LambderApiRateLimitsEngine, } from "./LambderApiRateLimits.js";
 import { LambderApiIdempotencyEngine } from "./LambderApiIdempotency.js";
 import { LAMBDER_BACKEND_SWAP } from "../shared/util/LambderTestingDoors.js";
+import { LambderKeyFieldDigest } from "../shared/util/LambderKeyFieldDigest.js";
 import LambderSessionController, { assertSessionCookiePrefixes, LambderSessionNotFoundError, } from "../session/LambderSessionController.js";
 import { DEFAULT_SESSION_CSRF_COOKIE_KEY, DEFAULT_SESSION_TOKEN_COOKIE_KEY } from "../shared/wire/LambderSessionCookieNames.js";
 /** An API that asks for idempotency: declared, and not the explicit `false` opt-out. */
@@ -21,11 +22,11 @@ const usesIdempotency = (definition) => definition.idempotency !== undefined &&
  * are adapters over this class; neither reimplements a step of it.
  *
  * ```
- * version floor → signature gate → restore payload → rate limits keyed per ip
- * → session (session mode) → idempotency replay → rate limits keyed per session
- * (and custom keys charged beforeGuards) → guards → input validation → guards
- * placed after it → rate limits keyed by a custom key → exec, inside the
- * idempotency claim → drain response headers → answer
+ * envelope check → version floor → signature gate → restore payload → rate
+ * limits keyed per ip → session (session mode) → idempotency replay → rate
+ * limits keyed per session (and custom keys charged beforeGuards) → guards →
+ * input validation → guards placed after it → rate limits keyed by a custom
+ * key → exec, inside the idempotency claim → drain response headers → answer
  * ```
  *
  * Each policy subsystem (rate limits, guards, idempotency) is its own
@@ -52,7 +53,7 @@ const usesIdempotency = (definition) => definition.idempotency !== undefined &&
 export class LambderApiPipeline {
     apiVersion;
     minApiVersion;
-    rateLimits = new LambderApiRateLimitsEngine();
+    rateLimits;
     guards = new LambderApiGuardsEngine();
     idempotency;
     maxRequestPayloadBytes;
@@ -75,14 +76,19 @@ export class LambderApiPipeline {
             }
             // A floor above the version this server stamps would refuse this
             // build's own clients, and the first symptom would be every tab
-            // reloading. The floor is clamped to apiVersion and the mistake
-            // reported once, at creation.
+            // reloading. Refused at creation, as every other misconfiguration
+            // is, rather than quietly read as some other floor than the one
+            // written: which of the two versions is wrong is the app's call.
             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;
+                throw new Error(`Lambder: minApiVersion ${this.minApiVersion} is above apiVersion ${this.apiVersion}, so it would refuse this build's own clients. ` +
+                    `Set minApiVersion to the oldest client version still served, at most ${this.apiVersion}.`);
             }
         }
-        this.idempotency = new LambderApiIdempotencyEngine(this.apiVersion);
+        // One digest for both engines, so its subkey is derived once per
+        // instance.
+        const keyFieldDigest = new LambderKeyFieldDigest(options.atRestSecret ?? null);
+        this.rateLimits = new LambderApiRateLimitsEngine(keyFieldDigest);
+        this.idempotency = new LambderApiIdempotencyEngine(this.apiVersion, keyFieldDigest);
         this.apiSignatures = options.apiSignatures ?? null;
         this.maxRequestPayloadBytes = assertPositiveInteger(options.maxRequestPayloadBytes ?? DEFAULT_MAX_RESTORED_PAYLOAD_BYTES, "maxRequestPayloadBytes");
         this.onInvalidInput = options.onInvalidInput ?? null;
@@ -211,10 +217,15 @@ export class LambderApiPipeline {
         return refusalAnswer(checked, this.apiVersion, ctx.logList);
     }
     /**
-     * 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)
-     * relies on.
+     * The steps that come before anything may read the request: the
+     * envelope check, 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) relies on.
+     *
+     * A body that is no envelope (readApiEnvelope flagged it invalidEnvelope)
+     * carries nothing to call with, no payload, version or signature, and is
+     * answered with the invalid-payload refusal, here, so every adapter
+     * refuses it alike.
      *
      * The floor refuses a request naming a version below minApiVersion,
      * whatever its signature says: the lever for a change the digest cannot
@@ -236,6 +247,8 @@ export class LambderApiPipeline {
      * ready to dispatch.
      */
     async prepare(request) {
+        if (request.invalidEnvelope !== undefined)
+            return invalidPayloadAnswer(this.apiVersion, request.invalidEnvelope);
         if (this.minApiVersion !== null && request.version !== null && compareDottedVersions(request.version, this.minApiVersion) < 0) {
             return versionExpiredAnswer(this.apiVersion);
         }
@@ -318,8 +331,12 @@ export class LambderApiPipeline {
         // Replay fast path: a completed idempotent request answers its stored
         // answer without burning the remaining rate-limit quota or re-running
         // guards. After the session read, because the replay scope is keyed
-        // per user, by the session's sessionKey.
-        const keyedCall = usesIdempotency(definition) ? await this.idempotency.resolveKeyedCall(definition.name, request, ctx) : null;
+        // per user, by the session's sessionKey. The guards engine says which
+        // posted guard inputs belong to the request's fingerprint, since only
+        // it knows which of them are single use.
+        const keyedCall = usesIdempotency(definition)
+            ? await this.idempotency.resolveKeyedCall(definition.name, request, ctx, this.guards.fingerprintedInputsOf(request, definition.guards))
+            : null;
         const replay = keyedCall ? await this.idempotency.findReplay(definition.name, keyedCall, trace) : null;
         if (replay)
             return replay;

package/dist/api/LambderApiRateLimits.d.ts

@@ -1,31 +1,33 @@
 import type { LambderApiMode } from "../shared/wire/LambderApiContract.js";
 import type { LambderRateLimitMessage, LambderRateLimitOptionValue, LambderRateLimitOverride } from "../shared/wire/LambderApiOptionValues.js";
+import type { LambderKeyFieldDigest } from "../shared/util/LambderKeyFieldDigest.js";
 import type { z } from "zod";
 import type { LambderApiRequest } from "./LambderApiRequest.js";
 import type { LambderApiCallContext } from "./LambderApiCallContext.js";
 import { type LambderRateLimiter, type LambderRateLimitExceeded, type LambderRateLimitPolicy } from "../shared/contracts/LambderRateLimiter.js";
 import type { LambderSessionRecord } from "../shared/contracts/LambderSessionStore.js";
-import { LambderApiRefusal } from "../shared/wire/LambderApiRefusal.js";
+import { LambderApiRefusal, type LambderRateLimitRefusalData } from "../shared/wire/LambderApiRefusal.js";
 import type { LambderNonEmptyOptionMap } from "../shared/util/LambderTypeUtilities.js";
 import { LAMBDER_BACKEND_SWAP } from "../shared/util/LambderTestingDoors.js";
-/** Refusal a rate-limited request answers unless the policy or the API's override names its own. */
+/** The words a rate-limited call answers with unless the policy or the API's override writes its own (the `refusal` option of each). */
 export declare const DEFAULT_RATE_LIMIT_REFUSAL: {
     type: "warning";
-    code: "lambder/rate-limited";
     content: string;
 };
 /**
  * The refusal a rate-limited call answers with: a 429 envelope carrying the
- * framework code, whatever message a policy or an API wrote, and a
- * Retry-After header. The engine throws it; the mock runtime's failure
- * injection throws the same one, so an injected rate limit is
- * indistinguishable from a real one.
+ * framework code, the words a policy or an API wrote, the policy's name and
+ * the seconds to wait as its data, and a Retry-After header of those same
+ * seconds. The engine throws it; the mock runtime's failure injection throws
+ * the same one, so an injected rate limit is indistinguishable from a real
+ * one.
  *
- * The code goes on after the message, so a message that carries one anyway
- * (a plain-JS caller, a cast) cannot replace it: a rate limit is never a code
- * an endpoint declares, and the pipeline would refuse to send one it did not.
+ * Only the words are read off the message, so one that carries a code or
+ * data anyway (a plain-JS caller, a cast) cannot replace them: a rate limit
+ * is never a code an endpoint declares, and the pipeline sends one only with
+ * the data a client narrows it by.
  */
-export declare const rateLimitRefusal: (detail: string, retryAfterSeconds: number, message?: LambderRateLimitMessage) => LambderApiRefusal;
+export declare const rateLimitRefusal: (detail: string, data: LambderRateLimitRefusalData, message?: LambderRateLimitMessage) => LambderApiRefusal;
 /**
  * A custom rate-limit key. `apiInput` names the fields of the API's OWN
  * payload the key derives from: that slice is validated against the raw
@@ -110,7 +112,7 @@ export type LambderApiRateLimitPolicyConfig<TCtx = any> = LambderRateLimitPolicy
      * takes it: `per: "ip"` and `per: "session"` have one place each.
      */
     chargeAt?: LambderRateLimitChargeAt;
-    /** The refusal's message for refused requests: its type, title and content, under the code "lambder/rate-limited". Default: a warning saying too many requests. */
+    /** The refusal's words for refused requests: its type, title and content, under the code "lambder/rate-limited" and beside the data that names this policy to the client. Default: a warning saying too many requests. */
     refusal?: LambderRateLimitMessage;
 };
 export type LambderApiRateLimitsConfig<TPolicies extends Record<string, LambderApiRateLimitPolicyConfig<any>>> = {
@@ -276,8 +278,13 @@ type LambderRateLimitPhase = "beforeSession" | LambderRateLimitChargeAt;
  * slice) and hands the context to a custom key's handler, reading nothing
  * of the context itself but its session, so it runs unchanged under the
  * server and the mock runtime.
+ *
+ * The caller's half of every tracker key (the address, the session key, a
+ * custom key) reaches the limiter as a digest (LambderKeyFieldDigest), so a
+ * table read names the API and the policy and never who was counted.
  */
 export declare class LambderApiRateLimitsEngine {
+    private readonly keyFieldDigest;
     private limiter;
     private failOpen;
     private ipv6PrefixLength;
@@ -289,6 +296,7 @@ export declare class LambderApiRateLimitsEngine {
      * second would otherwise be as many identical log lines.
      */
     private readonly loggedFailures;
+    constructor(keyFieldDigest: LambderKeyFieldDigest);
     /** True once rateLimits were configured. */
     get isConfigured(): boolean;
     configure(config: LambderApiRateLimitsConfig<Record<string, LambderApiRateLimitPolicyConfig>>): void;
@@ -318,7 +326,7 @@ export declare class LambderApiRateLimitsEngine {
     /**
      * One policy charged by code rather than by a declaration, for
      * `ctx.rateLimit` and `ctx.isRateLimited`. Counters, failOpen, key
-     * bounding and refusal are those of a declared limit; only who knows the
+     * digests and refusal are those of a declared limit; only who knows the
      * key differs. A policy without `per` takes the key the code passes, a
      * `per: "ip"` or `per: "session"` one reads it off the request, and one
      * keyed by an API payload is refused, since only its APIs know the key.
@@ -334,20 +342,19 @@ export declare class LambderApiRateLimitsEngine {
     /**
      * Counts one attempt, or lets it through when the limiter itself fails
      * and failOpen is on. The log line names the policy and its windows,
-     * never the tracker key: the key carries whatever a custom handler
-     * returned, which the docs' own example makes an email address. A
-     * failure the limiter throws again (see loggedFailures) is not logged
-     * again.
+     * never the tracker key: digested as its caller's half is, the key is
+     * still the same for every attempt of one caller, and a log is read by
+     * more people than the table. A failure the limiter throws again (see
+     * loggedFailures) is not logged again.
      */
     private countAttempt;
     private chargeKeyOf;
     private resolveKey;
     /**
      * The key a `per: "ip"` or `per: "session"` policy counts under: what the
-     * request carries, however the policy is charged. A session key is
-     * bounded like a custom one (see boundKeyField); an address needs no
-     * bound, since normalizeClientIp caps it at 45 characters whichever
-     * header or gateway field named it.
+     * request carries, however the policy is charged, digested as a custom
+     * key is. The address is the subject rateLimitSubjectOf counts (an IPv6
+     * caller's /64), so the digest of one subscriber's every address is one.
      */
     private requestKeyOf;
 }