lambder 7.2.5 → 8.0.2

package/dist/api/LambderApiRateLimits.js

@@ -1,9 +1,11 @@
-import { joinKeyFields } from "../shared/util/LambderKeyFields.js";
-import { sha256HexOf } from "../shared/util/LambderTextDigest.js";
+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";
 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." };
@@ -26,11 +28,10 @@ export const rateLimitRefusal = (detail, retryAfterSeconds, message) => new Lamb
  * exposes it as `rateLimitKey`.
  *
  * Bound rather than left open because the engine hands the handler whatever
- * context the adapter runs on, and the two adapters run on different ones. A
- * single builder pinned to the server's context type compiled against the
- * mock and then handed the handler a context with no `ip`, `method` or
- * `path`, so every caller collapsed onto one counter and the limit a test was
- * written to prove silently proved nothing.
+ * context the adapter runs on, and the two adapters differ. A builder pinned
+ * to the server's context type would compile against the mock, then receive
+ * a context with no `ip`, `method` or `path`: every caller would share one
+ * counter and a test of the limit would silently prove nothing.
  */
 export const lambderRateLimitKeyBuilder = () => ((key) => key);
 /** Normalize the three rateLimit-option forms into ordered entries; an explicit `undefined` map value declares nothing. */
@@ -45,11 +46,10 @@ const toRateLimitEntries = (value) => {
 };
 /**
  * A limiter is handed only limits it can act on, so no implementation has to
- * invent an answer for a nonsense one: that is where two limiters drift apart,
- * one refusing the first attempt against a negative cap and the other allowing
- * it. Zero is legal and leaves the window
- * unenforced, which is why this is the non-negative check and not the
- * positive one.
+ * invent an answer for a nonsense one (where two limiters would drift apart,
+ * one refusing the first attempt against a negative cap and one allowing it).
+ * Zero is legal and leaves the window unenforced, hence non-negative rather
+ * than positive.
  */
 const assertWindowLimits = (subject, windows) => {
     for (const key of RATE_LIMIT_WINDOW_KEYS) {
@@ -60,91 +60,119 @@ const assertWindowLimits = (subject, windows) => {
     }
 };
 const hasWindowOverride = (override) => RATE_LIMIT_WINDOW_KEYS.some((key) => override[key] !== undefined);
-const phaseOf = (per) => per === "ip" ? "beforeSession" : "afterSession";
-/**
- * The ceiling on the variable half of a tracker key, in UTF-8 bytes, past
- * which that half is replaced by its own digest. 1024 sits comfortably inside
- * every store's key limit (a DynamoDB partition key is 2048 bytes, and the
- * limiter's own prefix plus the api and policy names are joined in front of
- * this half).
- *
- * The bound lives in the engine rather than in a limiter because a store that
- * REFUSES an over-long key refuses it by throwing, and a throw from a limiter
- * is exactly what failOpen swallows: a custom key derived from a payload field
- * (the documented shape, an email address) that a caller posts 3,000
- * characters long makes every window of every policy fail the same way, and
- * the request goes through unmetered with the limit silently off. Folding the
- * over-long half into a digest keeps distinct callers on distinct counters,
- * and a key that fits stays readable in the table.
- *
- * `per: "ip"` needs none of this: normalizeClientIp already caps an address at
- * 45 characters, whichever header or gateway field named it.
- */
-const MAX_TRACKER_KEY_PART_BYTES = 1024;
-/**
- * The variable half of a tracker key, bounded: `<kind>:<value>` while the
- * value fits, `<kind>:h:<sha256 hex>` once it does not. The api and policy
- * names are joined around it afterwards, so an over-long key still says which
- * policy it belongs to.
- */
-const boundTrackerKeyPart = async (kind, value) => new TextEncoder().encode(value).length > MAX_TRACKER_KEY_PART_BYTES
-    ? `${kind}:h:${await sha256HexOf(value)}`
-    : `${kind}:${value}`;
+const phaseOf = (per, chargeAt) => {
+    if (per === "ip")
+        return "beforeSession";
+    if (per === "session")
+        return "beforeGuards";
+    return chargeAt ?? "afterGuards";
+};
 /** The windows one check ran against, for a log line that must not carry the tracker key. */
 const describeWindows = (limits) => RATE_LIMIT_WINDOW_KEYS.filter((key) => limits[key] !== undefined).map((key) => `${key}: ${String(limits[key])}`).join(", ") || "no window";
+/** The windows a check runs against: the policy's own, each replaced by the API's override where it names one. */
+const windowsOf = (policy, override) => {
+    const limits = {};
+    for (const windowKey of RATE_LIMIT_WINDOW_KEYS) {
+        const limit = override?.[windowKey] ?? policy[windowKey];
+        if (limit !== undefined)
+            limits[windowKey] = limit;
+    }
+    return limits;
+};
+/**
+ * The counter one check charges. "perPolicy" shares one counter across every
+ * API referencing the policy; "perApi" keys each API separately, which is
+ * also what lets an API override the windows without colliding. A charge
+ * made outside an API call (a route's handler) has no API to be counted
+ * under, so it counts against the policy's shared counter.
+ */
+const trackerKeyOf = (name, policy, apiName, key) => policy.budget === "perPolicy" || apiName === null
+    ? joinKeyFields("policy", name, key)
+    : joinKeyFields("api", apiName, name, key);
 /**
  * Runtime side of the rate-limit subsystem: holds the limiter and its named
  * policies, asserts API registrations against them at startup, and checks an
  * API's declared policies during preflight. Composed into
- * LambderApiPolicyEngine. Reads the request's ip and the context's session
- * and nothing else, so it runs unchanged under the server and the mock
- * runtime.
+ * LambderApiPipeline. Reads the request (its ip, and a key's payload
+ * 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.
  */
 export class LambderApiRateLimitsEngine {
     limiter = null;
     failOpen = true;
-    // A Map for the same reason the guard registry is one: a plain object
-    // answers for "toString" and "constructor" through its prototype, so a
-    // policy named one of those would slip past the registration check and
-    // fail on every request instead.
+    ipv6PrefixLength = DEFAULT_IPV6_RATE_LIMIT_PREFIX;
+    // A Map, not a plain object: an object answers for "toString" and
+    // "constructor" through its prototype, so a policy named one of those
+    // would slip past the registration check and fail on every request.
     policies = new Map();
+    /**
+     * The limiter failures already logged. A limiter answering a run of
+     * requests with one continuing failure throws the same error for each
+     * (see LambderRateLimiter), and a flood of a few thousand requests a
+     * second would otherwise be as many identical log lines.
+     */
+    loggedFailures = new WeakSet();
     /** True once rateLimits were configured. */
     get isConfigured() { return this.limiter !== null; }
     configure(config) {
         if (this.limiter)
             throw new Error("Lambder: rateLimits were already configured.");
-        // The same rule the guards option follows, and the one an API's own
-        // `rateLimit: {}` is already held to: declaring the option is
-        // declaring a limit. An empty map configured a limiter with nothing to
-        // enforce and reported every API that named a policy as if the option
-        // had never been given, which sends the reader to the wrong line.
+        // Declaring the option is declaring a limit, as for the guards option
+        // and an API's own `rateLimit: {}`. An empty map would configure a
+        // limiter with nothing to enforce, and every API naming a policy would
+        // be reported as if the option were missing: the wrong line to fix.
         if (Object.keys(config.policies).length === 0) {
             throw new Error("Lambder: the rateLimits option was declared with no policies in it, which configures nothing. Name the policies APIs will declare, or leave the option off.");
         }
         for (const [name, policy] of Object.entries(config.policies)) {
             const per = policy.per;
-            if (!per || (per !== "ip" && per !== "session" && typeof per.handler !== "function")) {
-                throw new Error(`Lambder: rate-limit policy "${name}" needs per: "ip", "session", or a { apiInput?, handler } key.`);
+            if (per !== undefined && per !== "ip" && per !== "session" && typeof per?.handler !== "function") {
+                throw new Error(`Lambder: rate-limit policy "${name}" has a per that is not "ip", "session", or a { apiInput?, handler } key. Leave per out for a policy the handler charges with its own key.`);
             }
             if (!RATE_LIMIT_WINDOW_KEYS.some((key) => policy[key])) {
                 throw new Error(`Lambder: rate-limit policy "${name}" declares no window (${RATE_LIMIT_WINDOW_KEYS.join("/")}).`);
             }
             assertWindowLimits(`rate-limit policy "${name}"`, policy);
+            const chargeAt = policy.chargeAt;
+            if (chargeAt !== undefined) {
+                if (chargeAt !== "beforeGuards" && chargeAt !== "afterGuards") {
+                    throw new Error(`Lambder: rate-limit policy "${name}" has chargeAt "${String(chargeAt)}"; use "afterGuards" (default) or "beforeGuards".`);
+                }
+                if (per === undefined || per === "ip" || per === "session") {
+                    throw new Error(`Lambder: rate-limit policy "${name}" sets chargeAt, which only a policy keyed by a { apiInput?, handler } key takes: per "ip" and per "session" each run at one fixed place, and a policy without per is charged by the code that names it.`);
+                }
+            }
             const budget = policy.budget;
             if (budget !== undefined && budget !== "perApi" && budget !== "perPolicy") {
                 throw new Error(`Lambder: rate-limit policy "${name}" has budget "${String(budget)}"; use "perApi" (default: each referencing API counts separately) or "perPolicy" (one counter shared by every referencing API).`);
             }
         }
+        const ipv6PrefixLength = config.ipv6PrefixLength ?? DEFAULT_IPV6_RATE_LIMIT_PREFIX;
+        if (!Number.isInteger(ipv6PrefixLength) || ipv6PrefixLength < 1 || ipv6PrefixLength > 128) {
+            throw new Error(`Lambder: rateLimits.ipv6PrefixLength must be a whole number from 1 to 128, got ${String(ipv6PrefixLength)}.`);
+        }
         this.limiter = config.limiter;
         this.failOpen = config.failOpen ?? true;
+        this.ipv6PrefixLength = ipv6PrefixLength;
         this.policies = new Map(Object.entries(config.policies));
     }
+    /**
+     * Puts the engine over another limiter, for `lambder/testing`; the named
+     * policies and failOpen stay as configured. False when rateLimits were
+     * never configured: there is nothing for a limiter to sit under.
+     */
+    [LAMBDER_BACKEND_SWAP](limiter) {
+        if (!this.limiter)
+            return false;
+        this.limiter = limiter;
+        return true;
+    }
     /** Startup validation of one API registration's rateLimit option. */
     assertRegistration(apiName, mode, rateLimitOption) {
         const entries = toRateLimitEntries(rateLimitOption);
-        // The same rule the guards option follows: declaring the option is
-        // declaring a limit. `{}`, `[]` and `{ name: undefined }` are
-        // present-but-empty, and would otherwise register an API that
+        // Declaring the option is declaring a limit, as for guards: `{}`,
+        // `[]` and `{ name: undefined }` would register an API that
         // announces a rate limit and enforces none.
         if (rateLimitOption !== undefined && entries.length === 0) {
             throw new Error(`Lambder: API "${apiName}" declares an empty rateLimit option, which limits nothing. ` +
@@ -155,6 +183,9 @@ export class LambderApiRateLimitsEngine {
             if (!policy) {
                 throw new Error(`Lambder: API "${apiName}" references unknown rate-limit policy "${name}". Declare it in the rateLimits option at creation.`);
             }
+            if (policy.per === undefined) {
+                throw new Error(`Lambder: API "${apiName}" references rate-limit policy "${name}", which declares no per: its key is the one a handler passes to ctx.rateLimit("${name}", key), so the request alone cannot be counted against it.`);
+            }
             if (policy.per === "session" && mode !== "session") {
                 throw new Error(`Lambder: API "${apiName}" uses rate-limit policy "${name}" (per "session"), which requires addSessionApi.`);
             }
@@ -176,64 +207,122 @@ export class LambderApiRateLimitsEngine {
      * counter, when a later guard or validation refuses) keeps its increment,
      * so list first the policy you want charged on refusals.
      *
-     * Run twice per call, once per phase: the policies whose key needs no
-     * session are checked BEFORE the session is read, so a flood of requests
-     * carrying bogus session cookies is refused without touching the session
-     * store; the rest are checked after it, since `per: "session"` and a
-     * custom key handler may both read ctx.session. Declared order is kept
-     * inside each phase.
+     * Runs once per phase (see LambderRateLimitPhase), keeping declared order
+     * within each: `per: "ip"` before the session read, so a flood of bogus
+     * session cookies never reaches the session store; `per: "session"` after
+     * it; a custom key after the guards unless its policy's `chargeAt` says
+     * "beforeGuards", so a caller they refuse cannot spend somebody else's
+     * budget.
      */
     async run(apiName, request, ctx, rateLimitOption, phase) {
         for (const { name, override } of toRateLimitEntries(rateLimitOption)) {
+            // Registration refused an unknown policy and one without per.
             const policy = this.policies.get(name);
-            if (!policy || !this.limiter)
-                throw new Error(`Lambder: rate-limit policy "${name}" is not configured. Declare it in the rateLimits option at creation.`);
-            if (phaseOf(policy.per) !== phase)
-                continue;
-            const key = await this.resolveKey(request, ctx, policy.per);
-            // "perPolicy" shares one counter across every API referencing the
-            // policy; "perApi" keys each API separately, which is also what
-            // lets an API override the windows without colliding.
-            const trackerKey = policy.budget === "perPolicy"
-                ? joinKeyFields("policy", name, key)
-                : joinKeyFields("api", apiName, name, key);
-            const limits = {};
-            for (const windowKey of RATE_LIMIT_WINDOW_KEYS) {
-                const limit = override?.[windowKey] ?? policy[windowKey];
-                if (limit !== undefined)
-                    limits[windowKey] = limit;
-            }
-            let exceeded;
-            try {
-                exceeded = await this.limiter.isRateLimited(trackerKey, limits);
-            }
-            catch (limiterErr) {
-                if (!this.failOpen)
-                    throw limiterErr;
-                // 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, and a log line is not
-                // the place for it.
-                console.error(`Lambder rate limits: policy "${name}" (${describeWindows(limits)}) could not be checked for API "${apiName}"; ` +
-                    "the request is being allowed through. Set rateLimits.failOpen: false to refuse instead.", limiterErr);
+            const per = policy.per;
+            if (phaseOf(per, policy.chargeAt) !== phase)
                 continue;
-            }
+            const key = await this.resolveKey(name, request, ctx, per);
+            const limits = windowsOf(policy, override);
+            const exceeded = await this.countAttempt(name, trackerKeyOf(name, policy, apiName, key), limits, `API "${apiName}"`);
             if (exceeded) {
-                const retryAfterSeconds = Math.max(1, exceeded.resetAt - Math.floor(Date.now() / 1000));
-                throw rateLimitRefusal(`Rate limited: "${apiName}" exceeded policy "${name}" (${exceeded.window}: ${exceeded.limit}).`, retryAfterSeconds, override?.errorMessage ?? policy.errorMessage);
+                throw rateLimitRefusal(`Rate limited: "${apiName}" exceeded policy "${name}" (${exceeded.window}: ${exceeded.limit}).`, this.retryAfterOf(exceeded), override?.errorMessage ?? policy.errorMessage);
             }
         }
     }
-    async resolveKey(request, ctx, per) {
-        if (per === "ip")
-            return `ip:${request.ip}`;
-        if (per === "session") {
-            const sessionKey = ctx.session?.sessionKey;
-            if (!sessionKey)
-                throw new Error('Lambder: rate-limit per "session" evaluated without a session on the context.');
-            return await boundTrackerKeyPart("session", sessionKey);
+    /**
+     * 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
+     * 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.
+     */
+    async chargePolicy(name, subject) {
+        if (!this.limiter)
+            throw new Error(`Lambder: charging rate-limit policy "${name}" needs the rateLimits option at creation.`);
+        const policy = this.policies.get(name);
+        if (!policy)
+            throw new Error(`Lambder: unknown rate-limit policy "${name}". Declare it in the rateLimits option at creation.`);
+        const key = await this.chargeKeyOf(name, policy, subject);
+        const limits = windowsOf(policy);
+        const where = subject.apiName === null ? "a route" : `API "${subject.apiName}"`;
+        const exceeded = await this.countAttempt(name, trackerKeyOf(name, policy, subject.apiName, key), limits, where);
+        if (!exceeded)
+            return { checkResult: false, refusal: null };
+        const retryAfterSeconds = this.retryAfterOf(exceeded);
+        return {
+            checkResult: { ...exceeded, retryAfterSeconds },
+            refusal: rateLimitRefusal(`Rate limited: ${where} exceeded policy "${name}" (${exceeded.window}: ${exceeded.limit}).`, retryAfterSeconds, policy.errorMessage),
+        };
+    }
+    /**
+     * Seconds until the refusing window resets, read against the limiter's
+     * own clock when it keeps one: `resetAt` is a second on that clock, and a
+     * limiter under a test clock would otherwise be told a Retry-After
+     * measured from another time entirely.
+     */
+    retryAfterOf(exceeded) {
+        const nowMilliseconds = this.limiter?.clockMilliseconds?.() ?? Date.now();
+        return Math.max(1, exceeded.resetAt - Math.floor(nowMilliseconds / 1000));
+    }
+    /**
+     * 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.
+     */
+    async countAttempt(name, trackerKey, limits, where) {
+        try {
+            return await this.limiter.isRateLimited(trackerKey, limits);
         }
-        const payload = per.apiInput ? parsePreflightSlice(per.apiInput, request.payload) : undefined;
-        return await boundTrackerKeyPart("custom", await per.handler(ctx, payload));
+        catch (limiterErr) {
+            if (!this.failOpen)
+                throw limiterErr;
+            if (typeof limiterErr === "object" && limiterErr !== null) {
+                if (this.loggedFailures.has(limiterErr))
+                    return false;
+                this.loggedFailures.add(limiterErr);
+            }
+            console.error(`Lambder rate limits: policy "${name}" (${describeWindows(limits)}) could not be checked for ${where}; ` +
+                "the request is being allowed through. Set rateLimits.failOpen: false to refuse instead.", limiterErr);
+            return false;
+        }
+    }
+    async chargeKeyOf(name, policy, subject) {
+        const per = policy.per;
+        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);
+        }
+        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.`);
+        }
+        if (subject.key !== undefined)
+            throw new Error(`Lambder: rate-limit policy "${name}" is keyed per "${per}", so charging it takes no key.`);
+        return await this.requestKeyOf(name, per, subject.ip, subject.session);
+    }
+    async resolveKey(name, request, ctx, per) {
+        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));
+    }
+    /**
+     * 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.
+     */
+    async requestKeyOf(name, per, ip, session) {
+        if (per === "ip")
+            return `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);
     }
 }

package/dist/api/LambderApiRequest.d.ts

@@ -2,11 +2,10 @@
  * Cookie header pairs (`name=value`) as every value per name, in header
  * order. Parsed pair by pair, because a whole-header parse keeps only the
  * first value of a name the browser holds at two scopes, and the session
- * controller weighs every copy. The map has no prototype: a cookie is client
- * data, and a name such as `__proto__` or `constructor` must land as a key
- * of its own rather than resolve to Object.prototype, which is what turned
- * one planted cookie into a 500 on every request. Every adapter builds its
- * request's cookies through this one function.
+ * controller weighs every copy. The map has no prototype: a cookie named
+ * `__proto__` or `constructor` must land as its own key rather than resolve
+ * to Object.prototype, or one planted cookie would 500 every request. Every
+ * adapter builds its request's cookies through this one function.
  */
 export declare const cookieValuesByName: (pairs: readonly string[]) => Record<string, string[]>;
 /** Request headers under lowercased names, so a lookup never depends on how the gateway spelled them. */
@@ -34,10 +33,9 @@ export type LambderApiRequest = {
     guardInputs: Record<string, unknown> | undefined;
     /**
      * The idempotency key exactly as posted, so `unknown`: it is client data,
-     * and the shape check plus the client-facing 400 belong to the
-     * idempotency engine. Typed `string | undefined` here, every reader was
-     * entitled to treat a number or an object as a key, and the only one
-     * there is had to widen it back before it could check anything.
+     * and the shape check and its client-facing 400 belong to the idempotency
+     * engine. A string type here would entitle every reader to treat a
+     * posted number or object as a key.
      */
     idempotencyKey: unknown;
     /** Request headers, names lowercased. */
@@ -49,10 +47,9 @@ export type LambderApiRequest = {
     /** The Host the request was made to. */
     host: string;
     /**
-     * The caller's abort signal, carried for adapters that have one (the mock
-     * runtime aborts its own latency wait with it). The pipeline itself
-     * neither reads nor honours it: a Lambda invocation has no signal, and an
-     * adapter that does own one is the layer that knows what abandoning a
+     * The caller's abort signal, for adapters that have one (the mock runtime
+     * aborts its latency wait with it). The pipeline ignores it: a Lambda
+     * invocation has no signal, and only the adapter knows what abandoning a
      * half-run call means for it.
      */
     signal?: AbortSignal;
@@ -71,6 +68,16 @@ export type LambderApiRequestInfo = {
     host: string;
     signal?: AbortSignal;
 };
+/**
+ * Whether a POST's Content-Type makes it an API call: application/json,
+ * which a browser sends cross-origin only after a CORS preflight. A form
+ * (text/plain, urlencoded, multipart) needs none, so any website could post
+ * one and, read as an API call, call a public login and plant the
+ * attacker's session cookies in a visitor's browser. Every Lambder caller
+ * sends application/json; the server and the mock's HTTP-shaped adapters
+ * read the same rule here.
+ */
+export declare const isApiCallContentType: (lowercasedHeaders: Record<string, string | undefined>) => boolean;
 /**
  * Reads the posted envelope into a request. Null when the body carries no
  * apiName, which is how the server tells an API call from a route with a
@@ -90,14 +97,13 @@ export type LambderRestorePayloadResult = {
  * Restores a payload the caller sent compressed (`payloadGz` or `payloadBr`,
  * beside `payloadBytes`) onto request.payload, so every later stage
  * (rate-limit key slices, guards, input validation, the handler) reads an
- * ordinary payload and needs no awareness of the wire format. The field
- * names the encoding; a request carrying both is refused. A request that
- * sent a plain payload passes through untouched.
+ * ordinary payload. The field names the encoding; a request carrying both is
+ * refused. A plain payload passes through untouched.
  *
- * Every failure answers with a message instead of throwing: a malformed body
- * is a client error, not a crash. The declared byte length both bounds the
- * decompression and verifies it, so an over-large or tampered body is
- * refused rather than expanded. Runs on Node through zlib and in a browser
- * through DecompressionStream, under the same bound.
+ * Failures return a message instead of throwing: a malformed body is a
+ * client error, not a crash. The declared byte length both bounds and
+ * verifies the decompression, so an over-large or tampered body is refused
+ * rather than expanded. Runs on Node (zlib) and in a browser
+ * (DecompressionStream) under the same bound.
  */
 export declare const restoreCompressedPayload: (request: LambderApiRequest, maxPayloadBytes: number) => Promise<LambderRestorePayloadResult>;

package/dist/api/LambderApiRequest.js

@@ -6,11 +6,10 @@ import { restoreText, LambderCompressionError, LAMBDER_RESTORE_FAILURES } from "
  * Cookie header pairs (`name=value`) as every value per name, in header
  * order. Parsed pair by pair, because a whole-header parse keeps only the
  * first value of a name the browser holds at two scopes, and the session
- * controller weighs every copy. The map has no prototype: a cookie is client
- * data, and a name such as `__proto__` or `constructor` must land as a key
- * of its own rather than resolve to Object.prototype, which is what turned
- * one planted cookie into a 500 on every request. Every adapter builds its
- * request's cookies through this one function.
+ * controller weighs every copy. The map has no prototype: a cookie named
+ * `__proto__` or `constructor` must land as its own key rather than resolve
+ * to Object.prototype, or one planted cookie would 500 every request. Every
+ * adapter builds its request's cookies through this one function.
  */
 export const cookieValuesByName = (pairs) => {
     const cookies = Object.create(null);
@@ -24,9 +23,8 @@ export const cookieValuesByName = (pairs) => {
 };
 /** Request headers under lowercased names, so a lookup never depends on how the gateway spelled them. */
 export const lowercaseHeaderNames = (headers) => {
-    // Prototype-free for the same reason the cookie map is: a header is
-    // client data, and a name such as `__proto__` must land as a key rather
-    // than reach Object.prototype's setter and vanish.
+    // Prototype-free like the cookie map: a header named `__proto__` must
+    // land as a key rather than reach Object.prototype's setter and vanish.
     const lowered = Object.create(null);
     for (const [key, value] of Object.entries(headers ?? {})) {
         if (value !== undefined)
@@ -34,6 +32,16 @@ export const lowercaseHeaderNames = (headers) => {
     }
     return lowered;
 };
+/**
+ * Whether a POST's Content-Type makes it an API call: application/json,
+ * which a browser sends cross-origin only after a CORS preflight. A form
+ * (text/plain, urlencoded, multipart) needs none, so any website could post
+ * one and, read as an API call, call a public login and plant the
+ * attacker's session cookies in a visitor's browser. Every Lambder caller
+ * sends application/json; the server and the mock's HTTP-shaped adapters
+ * read the same rule here.
+ */
+export const isApiCallContentType = (lowercasedHeaders) => (lowercasedHeaders["content-type"] ?? "").split(";")[0].trim().toLowerCase() === "application/json";
 /**
  * Reads the posted envelope into a request. Null when the body carries no
  * apiName, which is how the server tells an API call from a route with a
@@ -57,9 +65,9 @@ export const readApiEnvelope = (post, info) => {
         compressedPayload: hasGzip || hasBrotli
             ? { gzip: post[COMPRESSED_PAYLOAD_GZ_FIELD], brotli: post[COMPRESSED_PAYLOAD_BR_FIELD], declaredBytes: post[COMPRESSED_PAYLOAD_BYTES_FIELD] }
             : null,
-        // Arrays are objects, and an array answers for its own properties, so
-        // a guard named "length" received a number where the client sent it
-        // nothing. Same reasoning as reading the map with hasOwnProperty.
+        // Arrays are refused: an array answers for its own properties, so a
+        // guard named "length" would receive a number the client never sent.
+        // Same reasoning as reading the map with hasOwnProperty.
         guardInputs: guardInputs !== null && typeof guardInputs === "object" && !Array.isArray(guardInputs) ? guardInputs : undefined,
         idempotencyKey: post.idempotencyKey,
         headers: info.headers,
@@ -73,15 +81,14 @@ export const readApiEnvelope = (post, info) => {
  * Restores a payload the caller sent compressed (`payloadGz` or `payloadBr`,
  * beside `payloadBytes`) onto request.payload, so every later stage
  * (rate-limit key slices, guards, input validation, the handler) reads an
- * ordinary payload and needs no awareness of the wire format. The field
- * names the encoding; a request carrying both is refused. A request that
- * sent a plain payload passes through untouched.
+ * ordinary payload. The field names the encoding; a request carrying both is
+ * refused. A plain payload passes through untouched.
  *
- * Every failure answers with a message instead of throwing: a malformed body
- * is a client error, not a crash. The declared byte length both bounds the
- * decompression and verifies it, so an over-large or tampered body is
- * refused rather than expanded. Runs on Node through zlib and in a browser
- * through DecompressionStream, under the same bound.
+ * Failures return a message instead of throwing: a malformed body is a
+ * client error, not a crash. The declared byte length both bounds and
+ * verifies the decompression, so an over-large or tampered body is refused
+ * rather than expanded. Runs on Node (zlib) and in a browser
+ * (DecompressionStream) under the same bound.
  */
 export const restoreCompressedPayload = async (request, maxPayloadBytes) => {
     const fields = request.compressedPayload;

package/dist/api/LambderApiSignature.d.ts

@@ -1,10 +1,9 @@
 import type { LambderApiDefinition } from "./LambderApiDefinition.js";
 import { type LambderApiGuard } from "./LambderApiGuards.js";
 /**
- * One endpoint as the generator sees it: the key its signature is stored
- * under, the signature, and the name both were computed from. The name is
- * what the shipped map deliberately does not carry, so this is the build-time
- * view of the same data, and the only place a generated map can be diffed by
+ * One endpoint as the generator sees it: the map key, the signature, and the
+ * name both were computed from. The shipped map deliberately omits the name,
+ * so this build-time view is the only place a generated map can be diffed by
  * endpoint rather than by opaque key.
  */
 export type LambderApiSignatureEntry = {
@@ -18,17 +17,15 @@ export type LambderApiSignatureEntry = {
  * input and output schemas as JSON Schema, every guard it declares with the
  * schema that guard validates (the guardInput the client sends separately,
  * or the apiInput slice of the payload), and whether it demands an
- * idempotency key. Anything else about the endpoint (its rate limits, a
- * guard's parameter, the handler) changes nothing for a client and is left
- * out, so changing it never forces a reload.
+ * idempotency key. Anything else (rate limits, a guard's parameter, the
+ * handler) changes nothing for a client and is left out, so changing it never
+ * forces a reload.
  *
- * 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, with one exception the schema declares itself:
- * the values of an extensibleEnum() in an output (see keepShapeOnly). 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.
+ * Schemas are hashed as built, descriptions and titles included, so a client
+ * built against a different one reloads once. The exception is an output
+ * extensibleEnum()'s values (see keepShapeOnly). Schemas must be 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>;