lambder 7.2.5 → 8.0.2

package/dist/api/LambderApiRateLimits.d.ts

@@ -3,9 +3,11 @@ import type { LambderRateLimitOptionValue, LambderRateLimitOverride } from "../s
 import type { z } from "zod";
 import type { LambderApiRequest } from "./LambderApiRequest.js";
 import type { LambderApiCallContext } from "./LambderApiCallContext.js";
-import { type LambderRateLimiter, type LambderRateLimitPolicy } from "../shared/contracts/LambderRateLimiter.js";
+import { type LambderRateLimiter, type LambderRateLimitExceeded, type LambderRateLimitPolicy } from "../shared/contracts/LambderRateLimiter.js";
+import type { LambderSessionRecord } from "../shared/contracts/LambderSessionStore.js";
 import { LambderApiRefusal, type LambderAppRefusalMessage } 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. */
 export declare const DEFAULT_RATE_LIMIT_REFUSAL: {
     type: "warning";
@@ -22,22 +24,20 @@ export declare const DEFAULT_RATE_LIMIT_REFUSAL: {
 export declare const rateLimitRefusal: (detail: string, retryAfterSeconds: number, message?: LambderAppRefusalMessage) => LambderApiRefusal;
 /**
  * A custom rate-limit key. `apiInput` names the fields of the API's OWN
- * payload the key derives from: the slice is validated against the raw
+ * payload the key derives from: that slice is validated against the raw
  * payload before `handler` runs (failures answer like regular input
- * validation, through setApiInputValidationErrorHandler when set) and the
- * handler receives it typed. Referencing the policy from an API whose input
- * schema does not carry those fields is a compile error, so the API's schema
- * stays the single owner of the field. Build with lambderRateLimitKey() so
- * the handler's payload type follows `apiInput`. The context is the
- * adapter's (the render context on the server); the engine reads nothing
- * from it itself.
+ * validation, through setApiInputValidationErrorHandler when set) and reaches
+ * the handler typed. Referencing the policy from an API whose input schema
+ * lacks those fields is a compile error, so the API's schema stays the single
+ * owner of the field. Build with lambderRateLimitKey() so the handler's
+ * payload type follows `apiInput`. The context is the adapter's (the render
+ * context on the server); the engine itself reads nothing from it.
  *
- * ONE member, with `apiInput` optional, rather than a union of the two
- * shapes: a union with a function member in each arm defeats contextual
- * typing, so annotating a policies map with LambderRateLimitPer or
- * LambderApiRateLimitPolicyConfig left `ctx` implicitly any and the
- * annotation did not compile at all. The builder's overloads are where the
- * apiInput/payload correlation is kept.
+ * One member with `apiInput` optional, not a union of two shapes: a union
+ * with a function in each arm defeats contextual typing, so annotating a
+ * policies map with LambderRateLimitPer or LambderApiRateLimitPolicyConfig
+ * would leave `ctx` implicitly any and fail to compile. The builder's
+ * overloads keep the apiInput/payload correlation instead.
  */
 export type LambderRateLimitKeyFn<TInput extends z.ZodType = z.ZodType, TCtx = any> = {
     apiInput?: TInput;
@@ -70,11 +70,10 @@ export type LambderRateLimitKeyBuilder<TCtx> = {
  * 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 declare const lambderRateLimitKeyBuilder: <TCtx>() => LambderRateLimitKeyBuilder<TCtx>;
 /** What one rate-limit counter tracks: the client IP, the session identity, or a custom payload-derived key. */
@@ -92,19 +91,47 @@ export type LambderRateLimitPer<TCtx = any> = "ip" | "session" | LambderRateLimi
  *   and report APIs separate shared budgets, declare two policies.
  */
 export type LambderRateLimitBudget = "perApi" | "perPolicy";
+/**
+ * When a custom-keyed policy is charged, relative to the guards and the input
+ * schema.
+ *
+ * - "afterGuards" (default): after every guard and the input schema passed.
+ *   The key is a value the caller chose (an email in the payload), so a
+ *   caller who never passes a captcha guard cannot spend a victim's budget
+ *   and lock them out of reset, register and send-code.
+ * - "beforeGuards": before the guards and the input schema, so an attempt
+ *   they refuse is counted too. For a limit on guessing a secret a guard or
+ *   the schema checks (a one-time code checked by a guard, keyed per email):
+ *   charged after them, a wrong guess is refused before it is ever counted.
+ *   Pair it with an IP limit, since anyone may spend this budget.
+ */
+export type LambderRateLimitChargeAt = "beforeGuards" | "afterGuards";
 /**
  * A named rate-limit policy: fixed windows, the key one counter tracks, and
  * what one budget spans.
  *
  * Generic over the context a custom key handler receives, so the adapter's
  * policies map pins it: the server's is the render context, the mock's is the
- * mock call context. Left open, a handler written for one adapter compiled
- * against the other and then read fields that were not there.
+ * mock call context. Left open, a handler written for one adapter would
+ * compile against the other and read fields that are not there.
  */
 export type LambderApiRateLimitPolicyConfig<TCtx = any> = LambderRateLimitPolicy & {
-    per: LambderRateLimitPer<TCtx>;
+    /**
+     * What one counter tracks when an API declares the policy. Left out, the
+     * policy is keyed by the code that charges it (`ctx.rateLimit(name, key)`
+     * in a handler), for a key only the handler knows, such as one recipient
+     * of an invitation; such a policy cannot be named in an API's `rateLimit`
+     * option, since the request alone does not say what to count.
+     */
+    per?: LambderRateLimitPer<TCtx>;
     /** Whether the windows are a per-API ceiling (default) or one budget shared by every referencing API. See LambderRateLimitBudget. */
     budget?: LambderRateLimitBudget;
+    /**
+     * When a policy keyed by a `{ apiInput?, handler }` key is charged. See
+     * LambderRateLimitChargeAt. Default: "afterGuards". Only such a policy
+     * takes it: `per: "ip"` and `per: "session"` have one place each.
+     */
+    chargeAt?: LambderRateLimitChargeAt;
     /** Envelope errorMessage for refused requests; inherits code "lambder/rate-limited" unless it sets its own. Default: a warning saying too many requests. */
     errorMessage?: LambderAppRefusalMessage;
 };
@@ -118,28 +145,101 @@ export type LambderApiRateLimitsConfig<TPolicies extends Record<string, LambderA
      * down, an IAM action is missing), instead of failing the request.
      * Default: true, and the failure is logged either way.
      *
-     * It lives here rather than on a limiter implementation because it is a
-     * decision about the REQUEST, not about a store: a custom limiter had no
-     * fail-open at all, and two limiters could answer the same outage
-     * differently. Set it to false on an app where an unmetered request is
-     * worse than a refused one.
+     * It lives here rather than on a limiter because it is a decision about
+     * the REQUEST, not the store: on the limiter, every custom limiter would
+     * need its own, and two limiters could answer the same outage
+     * differently. Set it to false where an unmetered request is worse than
+     * a refused one.
      */
     failOpen?: boolean;
+    /**
+     * How much of an IPv6 address one `per: "ip"` counter covers. A
+     * subscriber, a VPS included, holds at least a /64 and may pick any
+     * address inside it, so counting full addresses gives anyone who rotates
+     * a fresh counter per request. Default: 64. A smaller number (48, 56)
+     * counts a whole allocation as one caller.
+     */
+    ipv6PrefixLength?: number;
 };
+/**
+ * A policy's `per` as its type declares it: undefined for a policy declared
+ * without one, and a union holding undefined for a policy typed as the
+ * general LambderApiRateLimitPolicyConfig, where only registration can tell.
+ */
+type LambderPolicyPerOf<TPolicy> = "per" extends keyof TPolicy ? TPolicy["per" & keyof TPolicy] : undefined;
 /**
  * Policy names an API may reference: session-keyed policies only on session
- * APIs, and apiInput-keyed policies only when the API's payload carries the
- * key's fields.
+ * APIs, apiInput-keyed policies only when the API's payload carries the
+ * key's fields, and never a policy without `per`, whose key only the code
+ * that charges it knows. A policy whose type does not settle its `per` is
+ * allowed here and checked at registration.
+ *
+ * The payload is compared whole, as the guards' check does it: a union input
+ * one of whose members lacks the key's fields does not carry them, and every
+ * request of that member would be refused by the key slice's parse.
  */
 export type LambderAllowedPolicyNames<TPolicies, TPayload, TIncludeSession extends boolean> = {
+    [K in keyof TPolicies]: [
+        LambderPolicyPerOf<TPolicies[K]>
+    ] extends [undefined] ? never : [LambderPolicyPerOf<TPolicies[K]>] extends ["session"] ? (TIncludeSession extends true ? K : never) : [LambderPolicyPerOf<TPolicies[K]>] extends [{
+        apiInput: infer S extends z.ZodType;
+    }] ? ([TPayload] extends [z.input<S>] ? K : never) : K;
+}[keyof TPolicies] & string;
+/**
+ * Policy names a handler may charge itself: every policy except one keyed by
+ * a `{ apiInput?, handler }` key, which derives its key from an API's payload
+ * and so is charged by the APIs that declare it.
+ */
+export type LambderChargeablePolicyNames<TPolicies> = {
     [K in keyof TPolicies]: TPolicies[K] extends {
-        per: "session";
-    } ? (TIncludeSession extends true ? K : never) : TPolicies[K] extends {
-        per: {
-            apiInput: infer S extends z.ZodType;
-        };
-    } ? (TPayload extends z.output<S> ? K : never) : K;
+        per: LambderRateLimitKeyFn<any, any>;
+    } ? never : K;
 }[keyof TPolicies] & string;
+/**
+ * The key argument charging a policy takes: none for `per: "ip"` and
+ * `per: "session"`, which the request supplies, and the key itself for a
+ * policy that declares no `per`. Optional where the types cannot tell: on a
+ * context that does not know the app's policies (a hook's, a guard's), and
+ * for a policy typed as the general LambderApiRateLimitPolicyConfig.
+ */
+export type LambderChargeKeyArgs<TPolicies, K> = string extends K ? [key?: string] : string extends keyof TPolicies ? [key?: string] : K extends keyof TPolicies ? [LambderPolicyPerOf<TPolicies[K]>] extends [undefined] ? [key: string] : [LambderPolicyPerOf<TPolicies[K]>] extends ["ip" | "session"] ? [] : undefined extends LambderPolicyPerOf<TPolicies[K]> ? [key?: string] : [key: string] : never;
+/**
+ * What `ctx.isRateLimited` answers: false when the attempt was allowed,
+ * otherwise the window that refused it, when that window resets, and the
+ * seconds until then.
+ */
+export type LambderRateLimitCheckResult = false | (LambderRateLimitExceeded & {
+    retryAfterSeconds: number;
+});
+/**
+ * `ctx.rateLimit(policy, key?)`: counts one attempt against a named policy
+ * and, when it is over, refuses the request the way a declared limit does (a
+ * 429 with Retry-After and the policy's errorMessage). For a limit whose key
+ * only the handler knows, or one to charge only on some paths through it.
+ *
+ * The key tuple is NoInfer: left inferable, a key passed where none belongs
+ * would infer K as a string, which the constraint widens to every policy
+ * name, and the call would then accept the key it has to refuse.
+ */
+export type LambderContextRateLimit<TPolicies> = <K extends LambderChargeablePolicyNames<TPolicies>>(policy: K, ...key: NoInfer<LambderChargeKeyArgs<TPolicies, K>>) => Promise<void>;
+/**
+ * `ctx.isRateLimited(policy, key?)`: the same count, answered rather than
+ * thrown, for a handler that says "too many" in its own output shape.
+ */
+export type LambderContextRateLimitCheck<TPolicies> = <K extends LambderChargeablePolicyNames<TPolicies>>(policy: K, ...key: NoInfer<LambderChargeKeyArgs<TPolicies, K>>) => Promise<LambderRateLimitCheckResult>;
+/** Who is charging a policy from code: the API the call is (null on a route), and what a `per: "ip"` or `per: "session"` key reads. */
+export type LambderRateLimitChargeSubject = {
+    apiName: string | null;
+    ip: string;
+    session: LambderSessionRecord<any> | null;
+    /** The key the code supplied; required for a policy without `per`, refused for any other. */
+    key: string | undefined;
+};
+/** What charging a policy from code came to: the check result, and the refusal to throw when it is over. */
+export type LambderRateLimitChargeResult = {
+    checkResult: LambderRateLimitCheckResult;
+    refusal: LambderApiRefusal | null;
+};
 type LambderRateLimitOverrideFor<TPolicy> = TPolicy extends {
     budget: "perPolicy";
 } ? Pick<LambderRateLimitOverride, "errorMessage"> : LambderRateLimitOverride;
@@ -153,37 +253,57 @@ type LambderRateLimitMap<TPolicies, TPayload, TIncludeSession extends boolean> =
  * (`true` applies the policy as declared). Map entries are checked in
  * insertion order.
  *
- * Every form is non-empty by construction, the same machinery the guards
- * option uses (LambderNonEmptyOptionMap): `rateLimit: {}`, `rateLimit: []`
- * and `rateLimit: { policy: undefined }` announce a limit and enforce none.
+ * Every form is non-empty by construction (LambderNonEmptyOptionMap, as the
+ * guards option uses), since `rateLimit: {}`, `rateLimit: []` and
+ * `rateLimit: { policy: undefined }` would announce a limit and enforce none.
  */
 export type LambderRateLimitOption<TPolicies, TPayload, TIncludeSession extends boolean> = LambderAllowedPolicyNames<TPolicies, TPayload, TIncludeSession> | readonly [
     LambderAllowedPolicyNames<TPolicies, TPayload, TIncludeSession>,
     ...LambderAllowedPolicyNames<TPolicies, TPayload, TIncludeSession>[]
 ] | LambderNonEmptyOptionMap<LambderRateLimitMap<TPolicies, TPayload, TIncludeSession>>;
 /**
- * When in a call a policy can be checked. A `per: "ip"` counter is known from
- * the request alone, so it runs before the session read and bounds how often
- * one address may make the session store look a token up. Everything else
- * runs after: `per: "session"` needs the session, and a custom key handler is
- * app code that may read ctx.session too.
+ * When in a call a policy is checked.
+ *
+ * - `per: "ip"` is known from the request alone, so it runs before the
+ *   session read and bounds how often one address may make the session store
+ *   look a token up.
+ * - `per: "session"` needs the session, so it runs after the read, and
+ *   before the guards, which it protects the same way.
+ * - A custom key runs where its policy's `chargeAt` puts it (see
+ *   LambderRateLimitChargeAt): after the guards by default, or with the
+ *   session-keyed limits, before the guards, for "beforeGuards".
  */
-type LambderRateLimitPhase = "beforeSession" | "afterSession";
+type LambderRateLimitPhase = "beforeSession" | LambderRateLimitChargeAt;
 /**
  * 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 declare class LambderApiRateLimitsEngine {
     private limiter;
     private failOpen;
+    private ipv6PrefixLength;
     private policies;
+    /**
+     * 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.
+     */
+    private readonly loggedFailures;
     /** True once rateLimits were configured. */
     get isConfigured(): boolean;
     configure(config: LambderApiRateLimitsConfig<Record<string, LambderApiRateLimitPolicyConfig>>): void;
+    /**
+     * 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: LambderRateLimiter): boolean;
     /** Startup validation of one API registration's rateLimit option. */
     assertRegistration(apiName: string, mode: LambderApiMode, rateLimitOption?: LambderRateLimitOptionValue): void;
     /**
@@ -193,14 +313,48 @@ export declare 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.
      */
     run(apiName: string, request: LambderApiRequest, ctx: LambderApiCallContext, rateLimitOption: LambderRateLimitOptionValue | undefined, phase: LambderRateLimitPhase): Promise<void>;
+    /**
+     * 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.
+     */
+    chargePolicy(name: string, subject: LambderRateLimitChargeSubject): Promise<LambderRateLimitChargeResult>;
+    /**
+     * 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.
+     */
+    private retryAfterOf;
+    /**
+     * 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.
+     */
+    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.
+     */
+    private requestKeyOf;
 }
 export {};