lambder 3.7.1 → 4.0.1

package/dist/policies/LambderApiIdempotency.d.ts

@@ -0,0 +1,58 @@
+import type { LambderRenderContext } from "../core/LambderContext.js";
+import type { LambderDdbIdempotency } from "../stores/LambderDdbIdempotency.js";
+import { LambderResponse } from "../core/LambderResponse.js";
+export type LambderApiIdempotencyConfig = {
+    /** Your idempotency store instance; may share the rate limiter's table (distinct key prefix). */
+    store: LambderDdbIdempotency;
+    /** Seconds a stored response replays for. Default: 86400 (24h). Per-API override: idempotency: { ttlSeconds }. */
+    defaultTtlSeconds?: number;
+    /** Skip idempotency (execute normally) when DynamoDB errors, instead of failing the request. Default: true. */
+    failOpen?: boolean;
+};
+/**
+ * Runtime side of the idempotency subsystem: claims a per-operation scope
+ * around handler execution, replays stored responses, and settles claims.
+ * Composed into LambderApiPolicyEngine.
+ */
+export declare class LambderApiIdempotencyEngine {
+    private store;
+    private defaultTtlSeconds;
+    private failOpen;
+    configure(config: LambderApiIdempotencyConfig): void;
+    /** True once enableApiIdempotency() ran; registration asserts check it. */
+    get isConfigured(): boolean;
+    /**
+     * The request's idempotencyKey: null when absent, the key when valid, a
+     * 400 refusal when malformed. The minimum length matters for security:
+     * see IDEMPOTENCY_MIN_KEY_LENGTH.
+     */
+    private readKey;
+    /**
+     * The record's scope. Session APIs scope per session, so even a leaked
+     * key cannot cross users. Public APIs scope by the key alone: the key is
+     * required to be long (and documented to be random), and identity proxies
+     * like the client IP are deliberately NOT part of the scope, because the
+     * retry idempotency exists for (a timeout followed by a network change)
+     * frequently arrives from a different IP.
+     */
+    private scopeOf;
+    /**
+     * Replay fast path, run BEFORE rate limits and guards: a completed record
+     * answers with its stored response so a legitimate retry neither burns
+     * rate-limit quota nor re-runs guards (the original already passed them,
+     * and no handler executes). Misses fall through to the normal pipeline;
+     * store errors follow the failOpen setting.
+     */
+    findReplay(apiName: string, ctx: LambderRenderContext): Promise<LambderResponse | null>;
+    /**
+     * Idempotency wrapper around validation-passed handler execution. Without
+     * a client idempotencyKey the handler just runs; with one, the scope
+     * (identity + api + key) is claimed atomically: duplicates of an
+     * in-flight original refuse with 409, replays of a completed one return
+     * the stored response verbatim, and a crashed original releases its claim
+     * so a retry actually retries.
+     */
+    withIdempotency(apiName: string, ctx: LambderRenderContext, config: boolean | {
+        ttlSeconds?: number;
+    }, exec: () => Promise<LambderResponse>): Promise<LambderResponse>;
+}

package/dist/policies/LambderApiIdempotency.js

@@ -0,0 +1,215 @@
+import { LambderApiError } from "../shared/LambderApiError.js";
+import { LambderResponse, normalizeHeaders } from "../core/LambderResponse.js";
+/** A crashed original must not block retries forever: pending claims expire on their own. */
+const IDEMPOTENCY_PENDING_TTL_SECONDS = 300;
+/**
+ * Keys must be unguessable: without a session, the replay scope is the key
+ * itself, so a guessable key would let one client read another's stored
+ * response. LambderCaller.createIdempotencyKey() returns 36 chars.
+ */
+const IDEMPOTENCY_MIN_KEY_LENGTH = 16;
+const IDEMPOTENCY_MAX_KEY_LENGTH = 200;
+/**
+ * Runtime side of the idempotency subsystem: claims a per-operation scope
+ * around handler execution, replays stored responses, and settles claims.
+ * Composed into LambderApiPolicyEngine.
+ */
+export class LambderApiIdempotencyEngine {
+    store = null;
+    defaultTtlSeconds = 24 * 3600;
+    failOpen = true;
+    configure(config) {
+        if (this.store)
+            throw new Error("Lambder: enableApiIdempotency() was already called.");
+        this.store = config.store;
+        this.defaultTtlSeconds = config.defaultTtlSeconds ?? 24 * 3600;
+        this.failOpen = config.failOpen ?? true;
+    }
+    /** True once enableApiIdempotency() ran; registration asserts check it. */
+    get isConfigured() { return this.store !== null; }
+    /**
+     * The request's idempotencyKey: null when absent, the key when valid, a
+     * 400 refusal when malformed. The minimum length matters for security:
+     * see IDEMPOTENCY_MIN_KEY_LENGTH.
+     */
+    readKey(ctx) {
+        const rawKey = ctx.post?.idempotencyKey;
+        if (rawKey === undefined || rawKey === null)
+            return null;
+        if (typeof rawKey !== "string" || rawKey.length < IDEMPOTENCY_MIN_KEY_LENGTH || rawKey.length > IDEMPOTENCY_MAX_KEY_LENGTH) {
+            throw new LambderApiError(`Invalid idempotency key: must be a string of ${IDEMPOTENCY_MIN_KEY_LENGTH}-${IDEMPOTENCY_MAX_KEY_LENGTH} characters.`, { statusCode: 400 });
+        }
+        return rawKey;
+    }
+    /**
+     * The record's scope. Session APIs scope per session, so even a leaked
+     * key cannot cross users. Public APIs scope by the key alone: the key is
+     * required to be long (and documented to be random), and identity proxies
+     * like the client IP are deliberately NOT part of the scope, because the
+     * retry idempotency exists for (a timeout followed by a network change)
+     * frequently arrives from a different IP.
+     */
+    scopeOf(apiName, ctx, key) {
+        const sessionKey = ctx.session?.sessionKey;
+        return `${sessionKey ? `s:${sessionKey}` : "k"}|${apiName}|${key}`;
+    }
+    /**
+     * Replay fast path, run BEFORE rate limits and guards: a completed record
+     * answers with its stored response so a legitimate retry neither burns
+     * rate-limit quota nor re-runs guards (the original already passed them,
+     * and no handler executes). Misses fall through to the normal pipeline;
+     * store errors follow the failOpen setting.
+     */
+    async findReplay(apiName, ctx) {
+        const store = this.store;
+        if (!store)
+            return null;
+        const key = this.readKey(ctx);
+        if (key === null)
+            return null;
+        try {
+            const done = await store.peek(this.scopeOf(apiName, ctx, key));
+            if (!done)
+                return null;
+            return new LambderResponse({
+                statusCode: done.statusCode,
+                headers: done.headers,
+                body: done.body,
+            });
+        }
+        catch (err) {
+            if (this.failOpen)
+                return null;
+            throw err;
+        }
+    }
+    /**
+     * Idempotency wrapper around validation-passed handler execution. Without
+     * a client idempotencyKey the handler just runs; with one, the scope
+     * (identity + api + key) is claimed atomically: duplicates of an
+     * in-flight original refuse with 409, replays of a completed one return
+     * the stored response verbatim, and a crashed original releases its claim
+     * so a retry actually retries.
+     */
+    async withIdempotency(apiName, ctx, config, exec) {
+        const store = this.store;
+        if (!store)
+            return await exec();
+        const rawKey = this.readKey(ctx);
+        if (rawKey === null)
+            return await exec();
+        const ttlSeconds = (typeof config === "object" ? config.ttlSeconds : undefined) ?? this.defaultTtlSeconds;
+        const scopeKey = this.scopeOf(apiName, ctx, rawKey);
+        let begun;
+        try {
+            begun = await store.begin(scopeKey, { pendingTtlSeconds: IDEMPOTENCY_PENDING_TTL_SECONDS });
+        }
+        catch (err) {
+            if (this.failOpen)
+                return await exec();
+            throw err;
+        }
+        if (begun.state === "pending") {
+            throw new LambderApiError(`Duplicate request for "${apiName}": the original is still processing.`, {
+                statusCode: 409,
+                errorMessage: "This request is already being processed.",
+            });
+        }
+        if (begun.state === "done") {
+            return new LambderResponse({
+                statusCode: begun.statusCode,
+                headers: begun.headers,
+                body: begun.body,
+            });
+        }
+        const ownerToken = begun.ownerToken;
+        // Headers pushed via res.setHeader/res.addHeader (and session cookie
+        // writes) land on ctx accumulators and are applied AFTER this wrapper
+        // returns, so snapshot the baseline: entries added during exec belong
+        // to this response and must be stored with it, and a Set-Cookie among
+        // them makes the response uncacheable (replaying another request's
+        // cookies, e.g. session tokens, would be wrong).
+        const setBaseline = ctx._otherInternal.setHeaderFnAccumulator.length;
+        const addBaseline = ctx._otherInternal.addHeaderFnAccumulator.length;
+        // Store the response for replays when it qualifies, release the claim
+        // otherwise. Settle failures only surface when failing closed.
+        const settleClaim = async (response) => {
+            const execSetHeaders = ctx._otherInternal.setHeaderFnAccumulator.slice(setBaseline);
+            const execAddHeaders = ctx._otherInternal.addHeaderFnAccumulator.slice(addBaseline);
+            const setsCookie = response.getHeader("Set-Cookie") !== undefined
+                || [...execSetHeaders, ...execAddHeaders].some((h) => h.key.toLowerCase() === "set-cookie");
+            // The store owns the size decision: bodies are Brotli-compressed
+            // there, and only ones exceeding the item budget even compressed
+            // come back as "too-large".
+            const cacheable = response.statusCode < 500
+                && !setsCookie
+                && typeof response.body === "string"
+                && !response.isBodyBase64;
+            try {
+                if (cacheable) {
+                    // Merge during-exec accumulator headers into the stored
+                    // copy (same replace/append semantics the render pipeline
+                    // applies), so a replay reproduces the full header set.
+                    const storedResponse = new LambderResponse({
+                        statusCode: response.statusCode,
+                        headers: normalizeHeaders(response.headers),
+                        body: response.body,
+                    });
+                    for (const header of execSetHeaders)
+                        storedResponse.setHeader(header.key, header.value);
+                    for (const header of execAddHeaders)
+                        storedResponse.addHeader(header.key, header.value);
+                    const completion = await store.complete(scopeKey, ownerToken, {
+                        statusCode: response.statusCode,
+                        headers: storedResponse.headers,
+                        body: response.body,
+                        ttlSeconds,
+                    });
+                    if (completion !== "too-large")
+                        return;
+                    // Too large to replay: fall through to release the claim
+                    // so retries re-execute instead of 409ing.
+                }
+                await store.abandon(scopeKey, ownerToken);
+            }
+            catch (storeErr) {
+                // A failed complete() must not leave the pending claim
+                // dangling (it would 409 retries until the pending TTL).
+                try {
+                    await store.abandon(scopeKey, ownerToken);
+                }
+                catch { /* claim expires on its own */ }
+                if (!this.failOpen)
+                    throw storeErr;
+            }
+        };
+        try {
+            const response = await exec();
+            await settleClaim(response);
+            return response;
+        }
+        catch (err) {
+            // A thrown LambderResponse IS the response (res.die.*, throw
+            // res.api(...)): settle the claim like a returned one so its side
+            // effect replays, then rethrow so the pipeline emits it.
+            if (err instanceof LambderResponse) {
+                await settleClaim(err);
+                throw err;
+            }
+            // A real crash (or a thrown refusal like LambderApiError /
+            // refuse()) releases the claim so a retry actually retries. This
+            // is the deliberate rule: RESPONSES are stored and replayed,
+            // refusals delivered as returned envelopes included; EXCEPTIONS
+            // are not, so a thrown refusal re-executes on retry and the
+            // handler decides afresh. Pick the idiom accordingly.
+            try {
+                await store.abandon(scopeKey, ownerToken);
+            }
+            catch (cleanupErr) {
+                if (!this.failOpen)
+                    throw cleanupErr;
+            }
+            throw err;
+        }
+    }
+}

package/dist/policies/LambderApiPolicies.d.ts

@@ -0,0 +1,40 @@
+import type { LambderRenderContext } from "../core/LambderContext.js";
+import type LambderResolver from "../core/LambderResolver.js";
+import type { LambderResponse } from "../core/LambderResponse.js";
+import { type LambderApiGuard, type LambderGuardsOptionValue } from "./LambderApiGuards.js";
+import { type LambderApiRateLimitPolicyConfig, type LambderApiRateLimitsConfig } from "./LambderApiRateLimits.js";
+import { type LambderApiIdempotencyConfig } from "./LambderApiIdempotency.js";
+/** The declarative options one API registration may carry. */
+type LambderApiPolicyOptions = {
+    rateLimit?: string | readonly string[];
+    guards?: LambderGuardsOptionValue;
+    idempotency?: unknown;
+};
+/**
+ * Runtime side of the declarative API options: composes the three policy
+ * subsystems (rate limits in ./LambderApiRateLimits.ts, guards in
+ * ./LambderApiGuards.ts, idempotency in ./LambderApiIdempotency.ts), asserts
+ * registrations against them at startup, and executes them around handlers
+ * at request time. Internal to Lambder; apps interact through
+ * enableApiRateLimits(), enableApiIdempotency(), defineApiGuards() and the
+ * per-API options.
+ */
+export declare class LambderApiPolicyEngine {
+    private rateLimits;
+    private guards;
+    private idempotency;
+    setRateLimits(config: LambderApiRateLimitsConfig<Record<string, LambderApiRateLimitPolicyConfig>>): void;
+    addGuards(guards: Record<string, LambderApiGuard<any, any, any>>): void;
+    setIdempotency(config: LambderApiIdempotencyConfig): void;
+    /** Startup validation of one API registration's declarative options. */
+    assertRegistration(apiName: string, mode: "public" | "session", options: LambderApiPolicyOptions): void;
+    /** Rate limits then guards, in declared order. Refusals throw (LambderApiError or a guard's own throw). */
+    runPreflight(apiName: string, ctx: LambderRenderContext, resolver: LambderResolver, options: LambderApiPolicyOptions): Promise<void>;
+    /** Idempotency replay fast path, run before the preflight: see LambderApiIdempotencyEngine.findReplay. */
+    findReplay(apiName: string, ctx: LambderRenderContext): Promise<LambderResponse | null>;
+    /** Idempotency claim/replay wrapper around handler execution: see LambderApiIdempotencyEngine.withIdempotency. */
+    withIdempotency(apiName: string, ctx: LambderRenderContext, config: boolean | {
+        ttlSeconds?: number;
+    }, exec: () => Promise<LambderResponse>): Promise<LambderResponse>;
+}
+export {};

package/dist/policies/LambderApiPolicies.js

@@ -0,0 +1,47 @@
+import { LambderApiGuardsEngine } from "./LambderApiGuards.js";
+import { LambderApiRateLimitsEngine } from "./LambderApiRateLimits.js";
+import { LambderApiIdempotencyEngine } from "./LambderApiIdempotency.js";
+/**
+ * Runtime side of the declarative API options: composes the three policy
+ * subsystems (rate limits in ./LambderApiRateLimits.ts, guards in
+ * ./LambderApiGuards.ts, idempotency in ./LambderApiIdempotency.ts), asserts
+ * registrations against them at startup, and executes them around handlers
+ * at request time. Internal to Lambder; apps interact through
+ * enableApiRateLimits(), enableApiIdempotency(), defineApiGuards() and the
+ * per-API options.
+ */
+export class LambderApiPolicyEngine {
+    rateLimits = new LambderApiRateLimitsEngine();
+    guards = new LambderApiGuardsEngine();
+    idempotency = new LambderApiIdempotencyEngine();
+    setRateLimits(config) {
+        this.rateLimits.configure(config);
+    }
+    addGuards(guards) {
+        this.guards.addGuards(guards);
+    }
+    setIdempotency(config) {
+        this.idempotency.configure(config);
+    }
+    /** Startup validation of one API registration's declarative options. */
+    assertRegistration(apiName, mode, options) {
+        this.rateLimits.assertRegistration(apiName, mode, options.rateLimit);
+        this.guards.assertRegistration(apiName, mode, options.guards);
+        if (options.idempotency !== undefined && !this.idempotency.isConfigured) {
+            throw new Error(`Lambder: API "${apiName}" declares idempotency but enableApiIdempotency() was not called first.`);
+        }
+    }
+    /** Rate limits then guards, in declared order. Refusals throw (LambderApiError or a guard's own throw). */
+    async runPreflight(apiName, ctx, resolver, options) {
+        await this.rateLimits.run(apiName, ctx, resolver, options.rateLimit);
+        await this.guards.run(ctx, resolver, options.guards);
+    }
+    /** Idempotency replay fast path, run before the preflight: see LambderApiIdempotencyEngine.findReplay. */
+    async findReplay(apiName, ctx) {
+        return await this.idempotency.findReplay(apiName, ctx);
+    }
+    /** Idempotency claim/replay wrapper around handler execution: see LambderApiIdempotencyEngine.withIdempotency. */
+    async withIdempotency(apiName, ctx, config, exec) {
+        return await this.idempotency.withIdempotency(apiName, ctx, config, exec);
+    }
+}

package/dist/policies/LambderApiRateLimits.d.ts

@@ -0,0 +1,90 @@
+import type { z } from "zod";
+import type { LambderRenderContext } from "../core/LambderContext.js";
+import type LambderResolver from "../core/LambderResolver.js";
+import type { LambderRateLimitPolicy, LambderDdbRateLimiter } from "../stores/LambderDdbRateLimiter.js";
+/**
+ * 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 before `handler` runs (failures answer the standard 422 validation
+ * shape) 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`.
+ */
+export type LambderRateLimitKeyFn<TInput extends z.ZodTypeAny = z.ZodTypeAny> = {
+    apiInput: TInput;
+    handler: (ctx: LambderRenderContext, payload: z.output<TInput>) => string | Promise<string>;
+} | {
+    apiInput?: undefined;
+    handler: (ctx: LambderRenderContext, payload: undefined) => string | Promise<string>;
+};
+/**
+ * Builder that ties the handler's payload type to the `apiInput` schema
+ * inside one literal. Returns the exact union member so type extraction can
+ * see the schema.
+ */
+export declare function lambderRateLimitKey<TInput extends z.ZodTypeAny>(key: {
+    apiInput: TInput;
+    handler: (ctx: LambderRenderContext, payload: z.output<TInput>) => string | Promise<string>;
+}): {
+    apiInput: TInput;
+    handler: (ctx: LambderRenderContext, payload: z.output<TInput>) => string | Promise<string>;
+};
+export declare function lambderRateLimitKey(key: {
+    handler: (ctx: LambderRenderContext, payload: undefined) => string | Promise<string>;
+}): {
+    apiInput?: undefined;
+    handler: (ctx: LambderRenderContext, payload: undefined) => string | Promise<string>;
+};
+/** What one rate-limit counter tracks: the client IP, the session identity, or a custom payload-derived key. */
+export type LambderRateLimitPer = "ip" | "session" | LambderRateLimitKeyFn<any>;
+/** A named rate-limit policy: fixed windows plus the key one counter tracks. */
+export type LambderApiRateLimitPolicyConfig = LambderRateLimitPolicy & {
+    per: LambderRateLimitPer;
+    /**
+     * What one counter spans. "api" (default): each API referencing the
+     * policy gets its own counter, so the windows are a per-API budget.
+     * "policy": every API referencing the policy shares one counter, so the
+     * windows are one combined budget (e.g. one per-email allowance across
+     * send, register, and reset endpoints).
+     */
+    scope?: "api" | "policy";
+    /** Envelope errorMessage for refused requests. Default: a generic too-many-requests message. */
+    errorMessage?: any;
+};
+export type LambderApiRateLimitsConfig<TPolicies extends Record<string, LambderApiRateLimitPolicyConfig>> = {
+    /** Your limiter instance; its table, keyPrefix and failOpen apply as configured on it. */
+    limiter: LambderDdbRateLimiter;
+    /** Named policies referenced (typed) from addApi/addSessionApi. */
+    policies: TPolicies;
+};
+/**
+ * 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.
+ */
+export type LambderAllowedPolicyNames<TPolicies, TPayload, TIncludeSession extends boolean> = {
+    [K in keyof TPolicies]: TPolicies[K] extends {
+        per: "session";
+    } ? (TIncludeSession extends true ? K : never) : TPolicies[K] extends {
+        per: {
+            apiInput: infer S extends z.ZodTypeAny;
+        };
+    } ? (TPayload extends z.output<S> ? K : never) : K;
+}[keyof TPolicies] & string;
+/**
+ * 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.
+ */
+export declare class LambderApiRateLimitsEngine {
+    private limiter;
+    private policies;
+    configure(config: LambderApiRateLimitsConfig<Record<string, LambderApiRateLimitPolicyConfig>>): void;
+    /** Startup validation of one API registration's rateLimit option. */
+    assertRegistration(apiName: string, mode: "public" | "session", rateLimitOption?: string | readonly string[]): void;
+    /** Check the API's policies in declared order; the first exceeded one refuses with a 429 envelope. */
+    run(apiName: string, ctx: LambderRenderContext, resolver: LambderResolver, rateLimitOption?: string | readonly string[]): Promise<void>;
+    private resolveKey;
+}

package/dist/policies/LambderApiRateLimits.js

@@ -0,0 +1,77 @@
+import { LambderApiError } from "../shared/LambderApiError.js";
+import { parsePreflightSlice } from "./LambderApiGuards.js";
+const RATE_LIMIT_WINDOW_KEYS = ["perMin", "per10Min", "perHour", "perDay", "perWeek", "perMonth"];
+export function lambderRateLimitKey(key) { return key; }
+const toList = (value) => value === undefined ? [] : typeof value === "string" ? [value] : value;
+/**
+ * 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.
+ */
+export class LambderApiRateLimitsEngine {
+    limiter = null;
+    policies = {};
+    configure(config) {
+        if (this.limiter)
+            throw new Error("Lambder: enableApiRateLimits() was already called.");
+        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 (!RATE_LIMIT_WINDOW_KEYS.some((key) => policy[key])) {
+                throw new Error(`Lambder: rate-limit policy "${name}" declares no window (${RATE_LIMIT_WINDOW_KEYS.join("/")}).`);
+            }
+        }
+        this.limiter = config.limiter;
+        this.policies = { ...config.policies };
+    }
+    /** Startup validation of one API registration's rateLimit option. */
+    assertRegistration(apiName, mode, rateLimitOption) {
+        for (const name of toList(rateLimitOption)) {
+            const policy = this.policies[name];
+            if (!policy) {
+                throw new Error(`Lambder: API "${apiName}" references unknown rate-limit policy "${name}". Declare it via enableApiRateLimits() before registering the API.`);
+            }
+            if (policy.per === "session" && mode !== "session") {
+                throw new Error(`Lambder: API "${apiName}" uses rate-limit policy "${name}" (per "session"), which requires addSessionApi.`);
+            }
+        }
+    }
+    /** Check the API's policies in declared order; the first exceeded one refuses with a 429 envelope. */
+    async run(apiName, ctx, resolver, rateLimitOption) {
+        for (const name of toList(rateLimitOption)) {
+            const policy = this.policies[name];
+            if (!policy || !this.limiter)
+                throw new Error(`Lambder: rate-limit policy "${name}" is not configured.`);
+            const key = await this.resolveKey(ctx, resolver, policy.per);
+            // scope "policy" shares one counter across every API referencing
+            // the policy; the default gives each API its own budget.
+            const trackerKey = policy.scope === "policy"
+                ? `policy|${name}|${key}`
+                : `api|${apiName}|${name}|${key}`;
+            const limited = await this.limiter.isRateLimited(trackerKey, policy);
+            if (limited) {
+                throw new LambderApiError(`Rate limited: "${apiName}" exceeded policy "${name}".`, {
+                    errorMessage: policy.errorMessage ?? "Too many requests. Please try again later.",
+                    statusCode: 429,
+                });
+            }
+        }
+    }
+    async resolveKey(ctx, resolver, per) {
+        if (per === "ip")
+            return `ip:${ctx.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 `session:${sessionKey}`;
+        }
+        const payload = per.apiInput
+            ? parsePreflightSlice(per.apiInput, ctx.post?.payload, resolver)
+            : undefined;
+        return `custom:${await per.handler(ctx, payload)}`;
+    }
+}

package/dist/{LambderSessionController.d.ts → session/LambderSessionController.d.ts}

@@ -1,4 +1,4 @@
-import { LambderRenderContext, LambderSessionRenderContext } from "./LambderContext.js";
+import { LambderRenderContext, LambderSessionRenderContext } from "../core/LambderContext.js";
 import type LambderSessionManager from "./LambderSessionManager.js";
 import { type LambderSessionContext } from "./LambderSessionManager.js";
 export type LambderSessionCookieOptions = {
@@ -26,6 +26,7 @@ export default class LambderSessionController<TSessionData = any> {
         ctx: LambderRenderContext<any> | LambderSessionRenderContext<any, TSessionData>;
     });
     private buildCookie;
+    /** Raw secrets exist only on the LambderCreatedSession result and in these cookies; the record stores hashes. */
     private setSessionCookies;
     private clearSessionCookies;
     private areRequestSessionTokensValid;

package/dist/{LambderSessionController.js → session/LambderSessionController.js}

@@ -1,4 +1,4 @@
-import { LambderSessionDataRefreshError } from "./LambderSessionManager.js";
+import { LambderSessionDataRefreshError, LambderSessionReadError } from "./LambderSessionManager.js";
 export default class LambderSessionController {
     lambderSessionManager;
     sessionTokenCookieKey;
@@ -30,9 +30,11 @@ export default class LambderSessionController {
         return parts.join("; ");
     }
     ;
-    setSessionCookies(session) {
-        this.ctx._otherInternal.addHeaderFnAccumulator.push({ key: "Set-Cookie", value: this.buildCookie(this.sessionTokenCookieKey, session.sessionToken, session.expiresAt * 1000, true) });
-        this.ctx._otherInternal.addHeaderFnAccumulator.push({ key: "Set-Cookie", value: this.buildCookie(this.sessionCsrfCookieKey, session.csrfToken, session.expiresAt * 1000, false) });
+    /** Raw secrets exist only on the LambderCreatedSession result and in these cookies; the record stores hashes. */
+    setSessionCookies(created) {
+        const expiresAtMs = created.session.expiresAt * 1000;
+        this.ctx._otherInternal.addHeaderFnAccumulator.push({ key: "Set-Cookie", value: this.buildCookie(this.sessionTokenCookieKey, created.sessionToken, expiresAtMs, true) });
+        this.ctx._otherInternal.addHeaderFnAccumulator.push({ key: "Set-Cookie", value: this.buildCookie(this.sessionCsrfCookieKey, created.csrfToken, expiresAtMs, false) });
     }
     ;
     clearSessionCookies() {
@@ -55,18 +57,18 @@ export default class LambderSessionController {
     }
     ;
     async createSession(sessionKey, data, ttlInSeconds) {
-        const session = await this.lambderSessionManager.createSession(sessionKey, data, ttlInSeconds);
-        this.setSessionCookies(session);
-        this.ctx.session = session;
+        const created = await this.lambderSessionManager.createSession(sessionKey, data, ttlInSeconds);
+        this.setSessionCookies(created);
+        this.ctx.session = created.session;
         return this.ctx.session;
     }
     ;
     async regenerateSession() {
         if (!this.ctx.session)
             throw new Error("Session not found.");
-        const newSession = await this.lambderSessionManager.regenerateSession(this.ctx.session);
-        this.setSessionCookies(newSession);
-        this.ctx.session = newSession;
+        const created = await this.lambderSessionManager.regenerateSession(this.ctx.session);
+        this.setSessionCookies(created);
+        this.ctx.session = created.session;
         return this.ctx.session;
     }
     ;
@@ -92,9 +94,12 @@ export default class LambderSessionController {
         }
         catch (err) {
             // Missing or invalid sessions become null, but a failing
-            // dataRefresh callback must not masquerade as a logout.
+            // dataRefresh callback or a DynamoDB read failure must not
+            // masquerade as a logout.
             if (err instanceof LambderSessionDataRefreshError)
                 throw err;
+            if (err instanceof LambderSessionReadError)
+                throw err;
             return null;
         }
     }