lambder 14.0.1 → 15.0.1

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;
 }

package/dist/api/LambderApiRateLimits.js

@@ -1,5 +1,4 @@
 import { joinKeyFields } from "../shared/util/joinKeyFields.js";
-import { boundKeyField } from "../shared/util/boundKeyField.js";
 import { RATE_LIMIT_WINDOWS, } from "../shared/contracts/LambderRateLimiter.js";
 import { LambderApiRefusal, LAMBDER_REFUSAL_CODES } from "../shared/wire/LambderApiRefusal.js";
 import { parsePreflightSlice } from "./LambderApiValidationRefusal.js";
@@ -7,29 +6,43 @@ import { assertNonNegativeInteger } from "../shared/util/LambderOptionChecks.js"
 import { LAMBDER_BACKEND_SWAP } from "../shared/util/LambderTestingDoors.js";
 import { DEFAULT_IPV6_RATE_LIMIT_PREFIX, rateLimitSubjectOf } from "../shared/util/LambderClientIp.js";
 const RATE_LIMIT_WINDOW_KEYS = RATE_LIMIT_WINDOWS.map((window) => window.key);
-/** Refusal a rate-limited request answers unless the policy or the API's override names its own. */
-export const DEFAULT_RATE_LIMIT_REFUSAL = { type: "warning", code: LAMBDER_REFUSAL_CODES.rateLimited, content: "Too many requests. Please try again later." };
+/** 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 const DEFAULT_RATE_LIMIT_REFUSAL = { type: "warning", content: "Too many requests. Please try again later." };
 /**
  * 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 const rateLimitRefusal = (detail, retryAfterSeconds, message) => new LambderApiRefusal(detail, {
-    refusal: message ? { type: message.type, ...(message.title !== undefined ? { title: message.title } : {}), content: message.content, code: LAMBDER_REFUSAL_CODES.rateLimited } : DEFAULT_RATE_LIMIT_REFUSAL,
-    statusCode: 429,
-    headers: { "Retry-After": String(Math.max(1, Math.floor(retryAfterSeconds))) },
-});
+export const rateLimitRefusal = (detail, data, message = DEFAULT_RATE_LIMIT_REFUSAL) => {
+    // The header carries whole seconds of at least one, and the data says the
+    // same number: a client reading either waits as long.
+    if (!Number.isFinite(data.retryAfterSeconds))
+        throw new Error(`Lambder: a rate-limit refusal waits a finite number of seconds, got ${String(data.retryAfterSeconds)}.`);
+    const retryAfterSeconds = Math.max(1, Math.floor(data.retryAfterSeconds));
+    return new LambderApiRefusal(detail, {
+        refusal: {
+            type: message.type,
+            ...(message.title !== undefined ? { title: message.title } : {}),
+            content: message.content,
+            code: LAMBDER_REFUSAL_CODES.rateLimited,
+            data: { policy: data.policy, retryAfterSeconds },
+        },
+        statusCode: 429,
+        headers: { "Retry-After": String(retryAfterSeconds) },
+    });
+};
 /**
- * A rate-limit message carries no code of its own and no data: its code is
- * always the framework's, which rateLimitRefusal sets, and a code there would
- * read as one the app chose for clients to branch on when it never reaches
- * them.
+ * A rate-limit message carries no code of its own and no data: both are the
+ * framework's, which rateLimitRefusal sets, and a code there would read as
+ * one the app chose for clients to branch on when it never reaches them.
  */
 const assertRateLimitMessage = (where, message) => {
     if (message === undefined)
@@ -39,7 +52,7 @@ const assertRateLimitMessage = (where, message) => {
         throw new Error(`Lambder: ${where} sets a refusal code. A rate-limit refusal is always "${LAMBDER_REFUSAL_CODES.rateLimited}", so an endpoint never has to declare it; write the type, title and content only.`);
     }
     if (data !== undefined) {
-        throw new Error(`Lambder: ${where} sets refusal data. A rate-limit refusal carries none.`);
+        throw new Error(`Lambder: ${where} sets refusal data. A rate-limit refusal carries the framework's: the policy that refused and the seconds to wait.`);
     }
 };
 /**
@@ -118,8 +131,13 @@ const trackerKeyOf = (name, policy, apiName, key) => policy.budget === "perPolic
  * 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 class LambderApiRateLimitsEngine {
+    keyFieldDigest;
     limiter = null;
     failOpen = true;
     ipv6PrefixLength = DEFAULT_IPV6_RATE_LIMIT_PREFIX;
@@ -134,6 +152,9 @@ export class LambderApiRateLimitsEngine {
      * second would otherwise be as many identical log lines.
      */
     loggedFailures = new WeakSet();
+    constructor(keyFieldDigest) {
+        this.keyFieldDigest = keyFieldDigest;
+    }
     /** True once rateLimits were configured. */
     get isConfigured() { return this.limiter !== null; }
     configure(config) {
@@ -249,14 +270,14 @@ export class LambderApiRateLimitsEngine {
             const limits = windowsOf(policy, override);
             const exceeded = await this.countAttempt(name, trackerKeyOf(name, policy, apiName, key), limits, `API "${apiName}"`);
             if (exceeded) {
-                throw rateLimitRefusal(`Rate limited: "${apiName}" exceeded policy "${name}" (${exceeded.window}: ${exceeded.limit}).`, this.retryAfterOf(exceeded), override?.refusal ?? policy.refusal);
+                throw rateLimitRefusal(`Rate limited: "${apiName}" exceeded policy "${name}" (${exceeded.window}: ${exceeded.limit}).`, { policy: name, retryAfterSeconds: this.retryAfterOf(exceeded) }, override?.refusal ?? policy.refusal);
             }
         }
     }
     /**
      * 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.
@@ -276,7 +297,7 @@ export class LambderApiRateLimitsEngine {
         const retryAfterSeconds = this.retryAfterOf(exceeded);
         return {
             checkResult: { ...exceeded, retryAfterSeconds },
-            refusal: rateLimitRefusal(`Rate limited: ${where} exceeded policy "${name}" (${exceeded.window}: ${exceeded.limit}).`, retryAfterSeconds, policy.refusal),
+            refusal: rateLimitRefusal(`Rate limited: ${where} exceeded policy "${name}" (${exceeded.window}: ${exceeded.limit}).`, { policy: name, retryAfterSeconds }, policy.refusal),
         };
     }
     /**
@@ -292,10 +313,10 @@ export 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.
      */
     async countAttempt(name, trackerKey, limits, where) {
         try {
@@ -319,7 +340,7 @@ export class LambderApiRateLimitsEngine {
         if (per === undefined) {
             if (subject.key === undefined)
                 throw new Error(`Lambder: rate-limit policy "${name}" declares no per, so the code charging it passes the key: ctx.rateLimit("${name}", key).`);
-            return await boundKeyField("custom", subject.key);
+            return await this.keyFieldDigest.digestOf("custom", subject.key);
         }
         if (per !== "ip" && per !== "session") {
             throw new Error(`Lambder: rate-limit policy "${name}" derives its key from an API's payload, so only the APIs declaring it can charge it.`);
@@ -332,21 +353,20 @@ export class LambderApiRateLimitsEngine {
         if (per === "ip" || per === "session")
             return await this.requestKeyOf(name, per, request.ip, ctx.session);
         const payload = per.apiInput ? await parsePreflightSlice(per.apiInput, request.payload) : undefined;
-        return await boundKeyField("custom", await per.handler(ctx, payload));
+        return await this.keyFieldDigest.digestOf("custom", await per.handler(ctx, payload));
     }
     /**
      * 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.
      */
     async requestKeyOf(name, per, ip, session) {
         if (per === "ip")
-            return `ip:${rateLimitSubjectOf(ip, this.ipv6PrefixLength)}`;
+            return await this.keyFieldDigest.digestOf("ip", rateLimitSubjectOf(ip, this.ipv6PrefixLength));
         const sessionKey = session?.sessionKey;
         if (!sessionKey)
             throw new Error(`Lambder: rate-limit policy "${name}" is keyed per "session", and the request charging it has no session.`);
-        return await boundKeyField("session", sessionKey);
+        return await this.keyFieldDigest.digestOf("session", sessionKey);
     }
 }

package/dist/api/LambderApiRefusals.d.ts

@@ -8,7 +8,7 @@ import { type LambderMergedNamedMaps, type LambderNamedMapsOption, type LambderN
  * One code of an app's refusal vocabulary: the schema of the data it carries,
  * when it carries data, and how every refusal with the code leaves the
  * server. A code's data is an object or an array, as an API's output is. The
- * status and the flag are declared once here rather than at each raise site,
+ * status and the flags are declared once here rather than at each raise site,
  * so a code always reaches a caller the same way.
  */
 export type LambderRefusalDeclaration = {
@@ -18,6 +18,14 @@ export type LambderRefusalDeclaration = {
     status?: LambderRefusalStatusCode;
     /** Whether every refusal with this code sets the envelope's notAuthorized flag, which a caller routes to its notAuthorizedHandler. */
     notAuthorized?: true;
+    /**
+     * Whether every refusal with this code sets the envelope's sessionExpired
+     * flag, which a caller answers by clearing its session and routing to its
+     * sessionExpiredHandler: for a session the handler found no longer good
+     * (its login deleted, say), which the pipeline's own check could not know.
+     * The server ends the session the call held as the refusal leaves.
+     */
+    sessionExpired?: true;
 };
 /**
  * One code as its endpoint may send it: the status and flag its declaration
@@ -30,6 +38,8 @@ export type LambderApiAllowedRefusal = {
     status?: LambderRefusalStatusCode;
     /** Present when every refusal with the code sets the envelope's notAuthorized flag. */
     notAuthorized?: true;
+    /** Present when every refusal with the code sets the envelope's sessionExpired flag. */
+    sessionExpired?: true;
 } & ({
     data: false;
 } | {
@@ -61,7 +71,7 @@ type LambderRefusalDataRefusal = {
 };
 /**
  * The vocabulary as declareRefusals() checks it, code by code: no `lambder/`
- * prefix, no key beside data, status and notAuthorized (a `dat:` would leave
+ * prefix, no key beside data, status and the two flags (a `dat:` would leave
  * a code that carries data declared as one that does not), and data that is
  * an object or an array.
  */
@@ -120,6 +130,8 @@ type LambderRefusalViolation = {
     thrown: unknown;
 } | {
     notObject: string;
+} | {
+    notRateLimitData: true;
 };
 /**
  * A refusal an endpoint is not allowed to send, so it was not sent and the
@@ -127,8 +139,10 @@ type LambderRefusalViolation = {
  * the endpoint does not declare (neither
  * in its own `refusals` option nor through a guard), data on a refusal whose
  * code declares none, no data on one whose code carries data, data its code's
- * schema rejects or that is not an object or an array, or a declared code
- * raised with a status or flag of its own, which its declaration owns.
+ * schema rejects or that is not an object or an array, a framework code
+ * without the data it carries (`lambder/rate-limited`'s policy and wait), or
+ * a declared code raised with a status or flag of its own, which its
+ * declaration owns.
  *
  * What makes a client's refusal type exact: a reader narrows `code` to the
  * endpoint's declared codes and the framework's own, and relies on this to
@@ -152,10 +166,12 @@ export declare class LambderApiRefusalValidationError extends Error {
  * here first.
  *
  * - An uncoded refusal, or one carrying a framework code, goes out as it is,
- *   provided it carries no data. Where the app requires codes, an uncoded
- *   refusal is refused too; a framework code still passes.
- * - A declared code leaves with its declaration's status and notAuthorized
- *   flag, and with data exactly when the code carries data, parsed through
+ *   provided it carries the data its code does: the policy and the seconds
+ *   to wait for `lambder/rate-limited`, none for every other. Where the app
+ *   requires codes, an uncoded refusal is refused too; a framework code
+ *   still passes.
+ * - A declared code leaves with its declaration's status and flags, and
+ *   with data exactly when the code carries data, parsed through
  *   the code's schema as an output is: undeclared fields stripped, defaults
  *   filled, transforms run. The parse is synchronous, so a data schema cannot
  *   be async.
@@ -187,8 +203,8 @@ export declare const toRefusalCodes: (value: string | readonly string[] | undefi
  * The vocabulary, checked: every code a non-empty string outside the
  * framework's `lambder/` prefix, every declaration an object whose `data`,
  * when present, is a zod schema, whose `status`, when present, is one a
- * reader files as a refusal, and whose `notAuthorized`, when present, is
- * true. A Map, so a code named for something Object.prototype carries
+ * reader files as a refusal, and whose `notAuthorized` and `sessionExpired`,
+ * when present, are true. A Map, so a code named for something Object.prototype carries
  * ("toString") is still an ordinary code.
  */
 export declare const readRefusalVocabulary: (refusals: Record<string, LambderRefusalDeclaration> | undefined) => Map<string, LambderRefusalDeclaration> | null;

package/dist/api/LambderApiRefusals.js

@@ -1,4 +1,4 @@
-import { LambderApiRefusal, isLambderRefusalCode } from "../shared/wire/LambderApiRefusal.js";
+import { LambderApiRefusal, LAMBDER_REFUSAL_CODES, isLambderRefusalCode } from "../shared/wire/LambderApiRefusal.js";
 import { describePayloadKind, isObjectPayload } from "../shared/wire/LambderObjectPayload.js";
 import { mergeNamedMaps } from "../shared/util/LambderNamedMaps.js";
 /**
@@ -18,17 +18,31 @@ export const allowedRefusalOf = (declaration) => {
     const leaves = {
         ...(declaration.status !== undefined ? { status: declaration.status } : {}),
         ...(declaration.notAuthorized ? { notAuthorized: true } : {}),
+        ...(declaration.sessionExpired ? { sessionExpired: true } : {}),
     };
     return declaration.data === undefined ? { ...leaves, data: false } : { ...leaves, data: true, schema: declaration.data };
 };
+/**
+ * Whether a `lambder/rate-limited` refusal's data is the shape a client
+ * narrows it to: the policy's name, and the whole seconds of at least one
+ * that the Retry-After header carries.
+ */
+const isRateLimitRefusalData = (data) => {
+    if (data === null || typeof data !== "object")
+        return false;
+    const { policy, retryAfterSeconds } = data;
+    return typeof policy === "string" && Number.isInteger(retryAfterSeconds) && retryAfterSeconds >= 1;
+};
 /**
  * A refusal an endpoint is not allowed to send, so it was not sent and the
  * call is answered as a crash: no code where the app requires one, a code
  * the endpoint does not declare (neither
  * in its own `refusals` option nor through a guard), data on a refusal whose
  * code declares none, no data on one whose code carries data, data its code's
- * schema rejects or that is not an object or an array, or a declared code
- * raised with a status or flag of its own, which its declaration owns.
+ * schema rejects or that is not an object or an array, a framework code
+ * without the data it carries (`lambder/rate-limited`'s policy and wait), or
+ * a declared code raised with a status or flag of its own, which its
+ * declaration owns.
  *
  * What makes a client's refusal type exact: a reader narrows `code` to the
  * endpoint's declared codes and the framework's own, and relies on this to
@@ -63,7 +77,7 @@ export class LambderApiRefusalValidationError extends Error {
         }
         else if ("ownStatusOrFlag" in violation) {
             message = `Lambder: API "${apiName}" refused with the declared code "${String(code)}" and a status or flag of its own, so the refusal was not sent. `
-                + "A declared code's status and notAuthorized flag are its declaration's: set them in the refusals vocabulary, and leave them off the refuse() call.";
+                + "A declared code's status and its notAuthorized and sessionExpired flags are its declaration's: set them in the refusals vocabulary, and leave them off the refuse() call.";
         }
         else if ("zodError" in violation) {
             // Paths and messages only, never the values: they may be the
@@ -75,6 +89,10 @@ export class LambderApiRefusalValidationError extends Error {
             message = `Lambder: API "${apiName}" refused with the code "${String(code)}" and data its schema threw on while parsing it (a transform that threw, `
                 + "or an async step: a refusal's data is parsed synchronously), so the refusal was not sent.";
         }
+        else if ("notRateLimitData" in violation) {
+            message = `Lambder: API "${apiName}" refused with the code "${String(code)}" and data that is not { policy, retryAfterSeconds }, so the refusal was not sent. `
+                + "Refuse a rate limit through ctx.rateLimit, or throw rateLimitRefusal(), which writes the data a client narrows it by.";
+        }
         else {
             message = `Lambder: API "${apiName}" refused with the code "${String(code)}" and data that is ${violation.notObject}, and a refusal's data is an object or an array, so the refusal was not sent.`;
         }
@@ -93,10 +111,12 @@ export class LambderApiRefusalValidationError extends Error {
  * here first.
  *
  * - An uncoded refusal, or one carrying a framework code, goes out as it is,
- *   provided it carries no data. Where the app requires codes, an uncoded
- *   refusal is refused too; a framework code still passes.
- * - A declared code leaves with its declaration's status and notAuthorized
- *   flag, and with data exactly when the code carries data, parsed through
+ *   provided it carries the data its code does: the policy and the seconds
+ *   to wait for `lambder/rate-limited`, none for every other. Where the app
+ *   requires codes, an uncoded refusal is refused too; a framework code
+ *   still passes.
+ * - A declared code leaves with its declaration's status and flags, and
+ *   with data exactly when the code carries data, parsed through
  *   the code's schema as an output is: undeclared fields stripped, defaults
  *   filled, transforms run. The parse is synchronous, so a data schema cannot
  *   be async.
@@ -110,6 +130,13 @@ export const checkedRefusal = (apiName, endpoint, thrown) => {
     if (endpoint === undefined)
         return thrown;
     const { code, data } = thrown.refusal;
+    if (code === LAMBDER_REFUSAL_CODES.rateLimited) {
+        if (data === undefined)
+            throw new LambderApiRefusalValidationError(apiName, thrown, { missingData: code });
+        if (!isRateLimitRefusalData(data))
+            throw new LambderApiRefusalValidationError(apiName, thrown, { notRateLimitData: true });
+        return thrown;
+    }
     if (code === undefined || isLambderRefusalCode(code)) {
         if (code === undefined && endpoint.codeRequired)
             throw new LambderApiRefusalValidationError(apiName, thrown, { uncoded: true });
@@ -145,11 +172,12 @@ export const checkedRefusal = (apiName, endpoint, thrown) => {
             throw new LambderApiRefusalValidationError(apiName, thrown, { notObject: describePayloadKind(parsed.data) });
         sent = parsed.data;
     }
-    // The declaration's status and flag, and the data as parsed: how every
+    // The declaration's status and flags, and the data as parsed: how every
     // refusal with this code leaves, wherever it was raised.
     return new LambderApiRefusal(thrown.message, {
         refusal: { ...thrown.refusal, ...(sent !== undefined ? { data: sent } : {}) },
         notAuthorized: declaration.notAuthorized,
+        sessionExpired: declaration.sessionExpired,
         statusCode: declaration.status,
         headers: thrown.headers,
         cause: thrown.cause,
@@ -195,8 +223,8 @@ export const toRefusalCodes = (value) => value === undefined ? [] : typeof value
  * The vocabulary, checked: every code a non-empty string outside the
  * framework's `lambder/` prefix, every declaration an object whose `data`,
  * when present, is a zod schema, whose `status`, when present, is one a
- * reader files as a refusal, and whose `notAuthorized`, when present, is
- * true. A Map, so a code named for something Object.prototype carries
+ * reader files as a refusal, and whose `notAuthorized` and `sessionExpired`,
+ * when present, are true. A Map, so a code named for something Object.prototype carries
  * ("toString") is still an ordinary code.
  */
 export const readRefusalVocabulary = (refusals) => {
@@ -215,9 +243,9 @@ export const readRefusalVocabulary = (refusals) => {
         if (declaration === null || typeof declaration !== "object") {
             throw new Error(`Lambder: the refusal "${code}" is not declared as an object: write {} for a code with no data, or { data: schema }.`);
         }
-        const extra = Object.keys(declaration).filter((key) => key !== "data" && key !== "status" && key !== "notAuthorized");
+        const extra = Object.keys(declaration).filter((key) => key !== "data" && key !== "status" && key !== "notAuthorized" && key !== "sessionExpired");
         if (extra.length) {
-            throw new Error(`Lambder: the refusal "${code}" has ${extra.map((key) => `"${key}"`).join(", ")} beside data, status and notAuthorized, which a refusal declaration does not take.`);
+            throw new Error(`Lambder: the refusal "${code}" has ${extra.map((key) => `"${key}"`).join(", ")} beside data, status, notAuthorized and sessionExpired, which a refusal declaration does not take.`);
         }
         // Read for what it is used as rather than by class, so a schema from
         // a second copy of zod in the bundle still counts.
@@ -228,8 +256,13 @@ export const readRefusalVocabulary = (refusals) => {
         if (status !== undefined && (typeof status !== "number" || !Number.isInteger(status) || status < 200 || status >= 500 || status === 422)) {
             throw new Error(`Lambder: the refusal "${code}" declares the status ${String(status)}. A declared refusal leaves with a status from 200 to 499 other than 422: a reader files a 5xx as a server failure and a 422 as an input validation failure.`);
         }
-        if (declaration.notAuthorized !== undefined && declaration.notAuthorized !== true) {
-            throw new Error(`Lambder: the refusal "${code}" declares notAuthorized as ${String(declaration.notAuthorized)}; write true, or leave it off.`);
+        for (const flag of ["notAuthorized", "sessionExpired"]) {
+            if (declaration[flag] !== undefined && declaration[flag] !== true) {
+                throw new Error(`Lambder: the refusal "${code}" declares ${flag} as ${String(declaration[flag])}; write true, or leave it off.`);
+            }
+        }
+        if (declaration.notAuthorized && declaration.sessionExpired) {
+            throw new Error(`Lambder: the refusal "${code}" declares both notAuthorized and sessionExpired. A caller routes a refusal one way: a session that is gone is not also a session that is not allowed.`);
         }
     }
     return new Map(entries);

package/dist/api/LambderApiRequest.d.ts

@@ -27,6 +27,13 @@ export type LambderApiRequest = {
      * expired, which reloads it.
      */
     retiredPath?: true;
+    /**
+     * Set when the call's body is no envelope: not a JSON object (a number,
+     * a string, a boolean, null, an array) or not JSON at all. The
+     * client-facing reason, which the pipeline answers with the
+     * invalid-payload refusal (prepare) before anything reads the call.
+     */
+    invalidEnvelope?: string;
     /** The caller's apiVersion, informational; null when it sent none. */
     version: string | null;
     /** The signature the caller carries for this endpoint (see LambderApiSignatureMap), for the signature gate; null when it sent none. */
@@ -91,10 +98,23 @@ export declare const isApiCallContentType: (lowercasedHeaders: Record<string, st
  * comes from where the call was posted, never from the body. Everything is
  * taken as posted: a malformed idempotencyKey or guardInputs value is the
  * engines' to refuse, with the client-facing message they already give.
+ *
+ * `posted` is the body as JSON parsed it; undefined (no body) reads as an
+ * empty envelope. A body that is not a JSON object, or one the adapter could
+ * not parse (`bodyNotJson`), is flagged on the request as invalidEnvelope
+ * and read as an empty envelope, so every adapter refuses it alike, in the
+ * pipeline, rather than each deciding what such a body means.
  */
-export declare const readApiEnvelope: (post: Record<string, unknown> | null | undefined, info: LambderApiRequestInfo, apiName: string, flags?: {
+export declare const readApiEnvelope: (posted: unknown, info: LambderApiRequestInfo, apiName: string, flags?: {
     retiredPath?: true;
+    bodyNotJson?: true;
 }) => LambderApiRequest;
+/**
+ * readApiEnvelope over a body's text, for an adapter that holds the text and
+ * nothing parsed from it: an empty body reads as an empty envelope, and text
+ * that is not JSON is flagged as no envelope, as the server flags it.
+ */
+export declare const readApiEnvelopeText: (text: string, info: LambderApiRequestInfo, apiName: string) => LambderApiRequest;
 /** Outcome of restoring a compressed request payload; the message is client-facing. */
 export type LambderRestorePayloadResult = {
     ok: true;

package/dist/api/LambderApiRequest.js

@@ -42,20 +42,34 @@ export const lowercaseHeaderNames = (headers) => {
  * read the same rule here.
  */
 export const isApiCallContentType = (lowercasedHeaders) => (lowercasedHeaders["content-type"] ?? "").split(";")[0].trim().toLowerCase() === "application/json";
+/** The one shape an API call's body may take: a JSON object, the envelope every Lambder caller posts. */
+const isEnvelopeObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+/** Why a body that did parse is no envelope, client-facing: its kind, never its value. */
+const notAnEnvelopeMessage = (posted) => `Request body must be a JSON object, got ${Array.isArray(posted) ? "an array" : posted === null ? "null" : `a ${typeof posted}`}.`;
 /**
  * Reads the posted envelope of a call to `apiName` into a request; the name
  * comes from where the call was posted, never from the body. Everything is
  * taken as posted: a malformed idempotencyKey or guardInputs value is the
  * engines' to refuse, with the client-facing message they already give.
+ *
+ * `posted` is the body as JSON parsed it; undefined (no body) reads as an
+ * empty envelope. A body that is not a JSON object, or one the adapter could
+ * not parse (`bodyNotJson`), is flagged on the request as invalidEnvelope
+ * and read as an empty envelope, so every adapter refuses it alike, in the
+ * pipeline, rather than each deciding what such a body means.
  */
-export const readApiEnvelope = (post, info, apiName, flags = {}) => {
-    post ??= {};
+export const readApiEnvelope = (posted, info, apiName, flags = {}) => {
+    const invalidEnvelope = flags.bodyNotJson ? "Request body must be a JSON object, and it is not valid JSON."
+        : posted === undefined || isEnvelopeObject(posted) ? null
+            : notAnEnvelopeMessage(posted);
+    const post = isEnvelopeObject(posted) ? posted : {};
     const hasGzip = post[COMPRESSED_PAYLOAD_GZ_FIELD] !== undefined;
     const hasBrotli = post[COMPRESSED_PAYLOAD_BR_FIELD] !== undefined;
     const guardInputs = post.guardInputs;
     return {
         apiName,
         ...(flags.retiredPath ? { retiredPath: true } : {}),
+        ...(invalidEnvelope !== null ? { invalidEnvelope } : {}),
         version: typeof post.version === "string" ? post.version : null,
         signature: typeof post.signature === "string" ? post.signature : null,
         token: typeof post.token === "string" ? post.token : "",
@@ -76,6 +90,21 @@ export const readApiEnvelope = (post, info, apiName, flags = {}) => {
         ...(info.signal ? { signal: info.signal } : {}),
     };
 };
+/**
+ * readApiEnvelope over a body's text, for an adapter that holds the text and
+ * nothing parsed from it: an empty body reads as an empty envelope, and text
+ * that is not JSON is flagged as no envelope, as the server flags it.
+ */
+export const readApiEnvelopeText = (text, info, apiName) => {
+    let posted;
+    try {
+        posted = JSON.parse(text || "{}");
+    }
+    catch {
+        return readApiEnvelope(undefined, info, apiName, { bodyNotJson: true });
+    }
+    return readApiEnvelope(posted, info, apiName);
+};
 /**
  * Restores a payload the caller sent compressed (`payloadGz` or `payloadBr`,
  * beside `payloadBytes`) onto request.payload, so every later stage