lambder 6.0.2 → 7.0.2

package/dist/api/LambderApiPipeline.js

@@ -0,0 +1,221 @@
+import { restoreCompressedPayload } from "./LambderApiRequest.js";
+import { apiNotFoundAnswer, invalidPayloadAnswer, refusalAnswer, sessionExpiredAnswer, validationAnswer, versionExpiredAnswer, } from "./LambderApiEnvelope.js";
+import { LambderApiValidationRefusal, isLambderApiValidationRefusal } from "./LambderApiValidationRefusal.js";
+import { isLambderApiRefusal } from "../shared/wire/LambderApiRefusal.js";
+import { DEFAULT_MAX_RESTORED_PAYLOAD_BYTES } from "../shared/wire/LambderRequestPayload.js";
+import { assertPositiveInteger } from "../shared/util/LambderOptionChecks.js";
+import { LambderApiPolicyEngine } from "./LambderApiPolicyEngine.js";
+import LambderSessionController, { assertSessionCookiePrefixes, } from "../session/LambderSessionController.js";
+import { DEFAULT_SESSION_CSRF_COOKIE_KEY, DEFAULT_SESSION_TOKEN_COOKIE_KEY } from "../shared/wire/LambderSessionCookieNames.js";
+/**
+ * The API pipeline: one API call from a parsed request to a plain answer,
+ * in the order the protocol defines. The Lambda server and the mock runtime
+ * are adapters over this class; neither reimplements a step of it.
+ *
+ * ```
+ * version gate → restore payload → rate limits that need no session
+ * → session (session mode) → idempotency replay → the remaining rate limits
+ * → guards → input validation → exec, inside the idempotency claim
+ * → drain response headers → answer
+ * ```
+ *
+ * Steps whose subsystem is not configured are skipped. A LambderApiRefusal
+ * thrown by any step, guard or handler is rendered here, in one place: a
+ * validation error through onInvalidInput, any other refusal as the refusal
+ * envelope. Anything else propagates, because only the adapter knows what a
+ * crash means (a global error handler, a mock event).
+ *
+ * `run` never sees a name it has no definition for; resolving a name to a
+ * definition is the one thing the adapters legitimately do differently (an
+ * action list versus a registry), and answerUnknownApi is what they answer
+ * with.
+ */
+export class LambderApiPipeline {
+    apiVersion;
+    policies = new LambderApiPolicyEngine();
+    maxRequestPayloadBytes;
+    onInvalidInput;
+    sessions;
+    constructor(options = {}) {
+        this.apiVersion = options.apiVersion ?? null;
+        this.maxRequestPayloadBytes = assertPositiveInteger(options.maxRequestPayloadBytes ?? DEFAULT_MAX_RESTORED_PAYLOAD_BYTES, "maxRequestPayloadBytes");
+        this.onInvalidInput = options.onInvalidInput ?? null;
+        this.sessions = options.sessions
+            ? {
+                manager: options.sessions.manager,
+                tokenCookieKey: options.sessions.tokenCookieKey ?? DEFAULT_SESSION_TOKEN_COOKIE_KEY,
+                csrfCookieKey: options.sessions.csrfCookieKey ?? DEFAULT_SESSION_CSRF_COOKIE_KEY,
+                cookieOptions: options.sessions.cookieOptions ?? {},
+            }
+            : null;
+        if (this.sessions)
+            assertSessionCookiePrefixes(this.sessions);
+        if (options.rateLimits)
+            this.policies.configureRateLimits(options.rateLimits);
+        if (options.guards)
+            this.policies.configureGuards(options.guards);
+        if (options.idempotency)
+            this.policies.configureIdempotency(options.idempotency);
+    }
+    /** True when a session manager was configured. */
+    get hasSessions() { return this.sessions !== null; }
+    /** The session manager, for adapters that hand it out; throws when sessions are not configured. */
+    get sessionManager() {
+        if (!this.sessions)
+            throw new Error("Session is not enabled. Configure the session option at creation.");
+        return this.sessions.manager;
+    }
+    /**
+     * A session controller for one request: what handlers use to create,
+     * rotate, refresh and end sessions. The request info is the API request's
+     * (its cookies and posted CSRF token) or a route's (cookies and no CSRF).
+     */
+    sessionController(ctx, request) {
+        if (!this.sessions)
+            throw new Error("Session is not enabled. Configure the session option at creation.");
+        return new LambderSessionController({
+            manager: this.sessions.manager,
+            tokenCookieKey: this.sessions.tokenCookieKey,
+            csrfCookieKey: this.sessions.csrfCookieKey,
+            cookieOptions: this.sessions.cookieOptions,
+            ctx,
+            request,
+        });
+    }
+    /** The session request info of an API request: its cookies, and the CSRF token it posted. */
+    static sessionInfoOf(request) {
+        return { host: request.host, cookies: request.cookies, csrfToken: request.token };
+    }
+    /** Registration-time checks of one definition's declarative options; the same messages on the server and in the mock. */
+    assertRegistration(definition) {
+        this.policies.assertRegistration(definition);
+    }
+    /** True when the gate is on and the request names a different version. */
+    isVersionStale(request) {
+        return !!this.apiVersion && !!request.version && request.version !== this.apiVersion;
+    }
+    /**
+     * The answer for a request naming no registered API: the apiNotFound
+     * refusal, carrying whatever the call already wrote (a CORS header, a
+     * cookie eviction). No version gate here: both adapters run prepare() on
+     * the way in, before a name is resolved, so a stale client has already
+     * been answered by the time anything asks for an unknown name.
+     */
+    answerUnknownApi(request, ctx) {
+        const answer = apiNotFoundAnswer(this.apiVersion, ctx?.logList);
+        ctx?.responseHeaders.applyInto(answer.headers);
+        return answer;
+    }
+    /**
+     * The steps that come before anything may read the request: the version
+     * gate, then the compressed-payload restore that every later reader (a
+     * rate-limit key slice, a guard, the input schema) depends on having
+     * happened.
+     *
+     * Public and named because the server runs them earlier than run() does,
+     * on the way in, so that its hooks see a plain payload and a stale client
+     * is answered before any of them, whether or not the name it asked for
+     * exists. run() calls it too, so an adapter that has no such step still
+     * gets the whole protocol. Calling it twice is safe by construction: the
+     * gate is a pure comparison and the restore has already removed the wire
+     * fields it reads.
+     *
+     * Returns the answer that ends the call, or null when the request is
+     * ready to dispatch.
+     */
+    async prepare(request) {
+        if (this.isVersionStale(request))
+            return versionExpiredAnswer(this.apiVersion);
+        const restored = await restoreCompressedPayload(request, this.maxRequestPayloadBytes);
+        if (!restored.ok)
+            return invalidPayloadAnswer(this.apiVersion, restored.message);
+        return null;
+    }
+    /**
+     * One call, one answer. Refusals are rendered; crashes propagate.
+     *
+     * An adapter that wants to report what the call did even when it crashed
+     * passes its own trace object: the pipeline writes into that one, so a
+     * handler that threw still leaves the guards it ran behind for the
+     * adapter's catch. Without it the trace was created here and lost with
+     * the throw, and the mock's call log showed no guards on exactly the
+     * calls a developer opens the log for.
+     */
+    async run(request, ctx, definition, exec, trace = { guardsRun: [], replayed: false }) {
+        let answer;
+        try {
+            answer = await this.execute(request, ctx, definition, exec, trace);
+        }
+        catch (err) {
+            if (isLambderApiValidationRefusal(err)) {
+                answer = await this.refuseInput(err, ctx, request);
+            }
+            else if (isLambderApiRefusal(err)) {
+                answer = refusalAnswer(err, this.apiVersion, ctx.logList);
+            }
+            else {
+                throw err;
+            }
+        }
+        // Every header written during the call belongs on the answer, whichever
+        // way it was produced: a cookie eviction from the session read, a
+        // handler's setHeader before it refused, the handler's own headers
+        // (already on it, so re-applying them here changes nothing).
+        ctx.responseHeaders.applyInto(answer.headers);
+        return { answer, ...trace };
+    }
+    async execute(request, ctx, definition, exec, trace) {
+        const unprepared = await this.prepare(request);
+        if (unprepared)
+            return unprepared;
+        // The limits whose key is known from the request alone, before the
+        // session store is asked anything: a request carrying bogus session
+        // cookies costs up to four store reads, and answering it
+        // sessionExpired without the limiter having run let one address spend
+        // the session store's read budget freely. A replay costs the same
+        // reads, so an ip-limited replay counts against that budget too: the
+        // limit protects the stores, not the handler.
+        await this.policies.runSessionlessRateLimits(request, ctx, definition);
+        if (definition.mode === "session") {
+            if (!this.sessions)
+                throw new Error(`Lambder: API "${definition.name}" is a session API, but no session store was configured at creation.`);
+            const session = await this.sessionController(ctx, LambderApiPipeline.sessionInfoOf(request)).fetchSessionIfExists();
+            if (!session)
+                return sessionExpiredAnswer(this.apiVersion, ctx.logList);
+        }
+        // Replay fast path: a completed idempotent request answers its stored
+        // answer without burning the remaining rate-limit quota or re-running
+        // guards. After the session read, because the replay scope is keyed
+        // per session.
+        const replay = await this.policies.findReplay(request, ctx, definition, trace);
+        if (replay)
+            return replay;
+        await this.policies.runPreflight(request, ctx, definition, trace);
+        if (definition.input) {
+            const parsed = definition.input.safeParse(request.payload);
+            if (!parsed.success)
+                throw new LambderApiValidationRefusal(parsed.error);
+            request.payload = parsed.data;
+        }
+        // The handler's own answer, and only that: what it wrote into
+        // responseHeaders during the call is on it before the idempotency
+        // engine judges and stores it, while a header written EARLIER in the
+        // call is not. That line matters, because the engine refuses to store
+        // an answer carrying a Set-Cookie: charge it with the stale-session
+        // cookie the session read evicted and an otherwise idempotent
+        // operation would silently stop being idempotent and re-execute on
+        // every retry. The call's earlier headers still reach the client;
+        // run() applies them to the answer on the way out.
+        const runHandler = async () => {
+            const handlerFirstHeader = ctx.responseHeaders.size;
+            const produced = await exec(ctx);
+            ctx.responseHeaders.applyInto(produced.headers, handlerFirstHeader);
+            return produced;
+        };
+        return await this.policies.withIdempotency(request, ctx, definition, trace, runHandler);
+    }
+    async refuseInput(err, ctx, request) {
+        const custom = this.onInvalidInput ? await this.onInvalidInput(err.zodError, ctx, request) : null;
+        return custom ?? validationAnswer(err.zodError, ctx.logList);
+    }
+}

package/dist/api/LambderApiPolicyEngine.d.ts

@@ -0,0 +1,36 @@
+import type { LambderApiRequest } from "./LambderApiRequest.js";
+import type { LambderApiCallContext, LambderApiCallTrace } from "./LambderApiCallContext.js";
+import type { LambderApiAnswer } from "./LambderApiAnswer.js";
+import type { LambderApiDefinition } from "./LambderApiDefinition.js";
+import { type LambderApiGuard } from "./LambderApiGuards.js";
+import { type LambderApiRateLimitPolicyConfig, type LambderApiRateLimitsConfig } from "./LambderApiRateLimits.js";
+import { type LambderApiIdempotencyConfig } 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. Owned by LambderApiPipeline; apps interact through the
+ * create() options (rateLimits, guards, idempotency) and the per-API
+ * options.
+ */
+export declare class LambderApiPolicyEngine {
+    private rateLimits;
+    private guards;
+    private idempotency;
+    /** True once any of the three subsystems was configured. */
+    get isConfigured(): boolean;
+    configureRateLimits(config: LambderApiRateLimitsConfig<Record<string, LambderApiRateLimitPolicyConfig>>): void;
+    configureGuards(guards: Record<string, LambderApiGuard<any, any, any>>): void;
+    configureIdempotency(config: LambderApiIdempotencyConfig): void;
+    /** Startup validation of one API's declarative options. */
+    assertRegistration(definition: LambderApiDefinition): void;
+    /** The rate-limit policies that can be checked before the session is read: see LambderApiRateLimitsEngine.run. */
+    runSessionlessRateLimits(request: LambderApiRequest, ctx: LambderApiCallContext, definition: LambderApiDefinition): Promise<void>;
+    /** The remaining rate limits, then guards, in declared order. Refusals throw; the trace records each guard as it runs. */
+    runPreflight(request: LambderApiRequest, ctx: LambderApiCallContext, definition: LambderApiDefinition, trace: LambderApiCallTrace): Promise<void>;
+    /** Idempotency replay fast path, run before the preflight: see LambderApiIdempotencyEngine.findReplay. */
+    findReplay(request: LambderApiRequest, ctx: LambderApiCallContext, definition: LambderApiDefinition, trace: LambderApiCallTrace): Promise<LambderApiAnswer | null>;
+    /** Idempotency claim/replay wrapper around handler execution: see LambderApiIdempotencyEngine.withIdempotency. */
+    withIdempotency(request: LambderApiRequest, ctx: LambderApiCallContext, definition: LambderApiDefinition, trace: LambderApiCallTrace, exec: () => Promise<LambderApiAnswer>): Promise<LambderApiAnswer>;
+}

package/dist/api/LambderApiPolicyEngine.js

@@ -0,0 +1,77 @@
+import { LambderApiGuardsEngine } from "./LambderApiGuards.js";
+import { LambderApiRateLimitsEngine } from "./LambderApiRateLimits.js";
+import { LambderApiIdempotencyEngine } from "./LambderApiIdempotency.js";
+/** An API that asks for idempotency: declared, and not the explicit `false` opt-out. */
+const usesIdempotency = (definition) => definition.idempotency !== undefined && definition.idempotency !== false;
+/**
+ * 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. Owned by LambderApiPipeline; apps interact through the
+ * create() options (rateLimits, guards, idempotency) and the per-API
+ * options.
+ */
+export class LambderApiPolicyEngine {
+    rateLimits = new LambderApiRateLimitsEngine();
+    guards = new LambderApiGuardsEngine();
+    idempotency = new LambderApiIdempotencyEngine();
+    /** True once any of the three subsystems was configured. */
+    get isConfigured() {
+        return this.rateLimits.isConfigured || this.guards.isConfigured || this.idempotency.isConfigured;
+    }
+    configureRateLimits(config) {
+        this.rateLimits.configure(config);
+    }
+    configureGuards(guards) {
+        this.guards.configure(guards);
+    }
+    configureIdempotency(config) {
+        this.idempotency.configure(config);
+    }
+    /** Startup validation of one API's declarative options. */
+    assertRegistration(definition) {
+        const { name, mode } = definition;
+        // Each subsystem reports its own absence. One combined message would
+        // tell an API that declares guards on an instance with no guards map
+        // that none of the three was configured, which reads as a question
+        // about all three when only one of them is missing.
+        if (definition.rateLimit !== undefined && !this.rateLimits.isConfigured) {
+            throw new Error(`Lambder: API "${name}" declares rateLimit but no rateLimits option was configured at creation.`);
+        }
+        if (definition.guards !== undefined && !this.guards.isConfigured) {
+            throw new Error(`Lambder: API "${name}" declares guards but no guards option was configured at creation.`);
+        }
+        this.rateLimits.assertRegistration(name, mode, definition.rateLimit);
+        this.guards.assertRegistration(name, mode, definition.guards);
+        // `idempotency: false` is an explicit opt-out, not a use: it asks for
+        // nothing and so needs no store behind it.
+        if (usesIdempotency(definition)) {
+            if (!this.idempotency.isConfigured) {
+                throw new Error(`Lambder: API "${name}" declares idempotency but no idempotency store was configured at creation.`);
+            }
+            this.idempotency.assertRegistration(name, definition.idempotency);
+        }
+    }
+    /** The rate-limit policies that can be checked before the session is read: see LambderApiRateLimitsEngine.run. */
+    async runSessionlessRateLimits(request, ctx, definition) {
+        await this.rateLimits.run(definition.name, request, ctx, definition.rateLimit, "beforeSession");
+    }
+    /** The remaining rate limits, then guards, in declared order. Refusals throw; the trace records each guard as it runs. */
+    async runPreflight(request, ctx, definition, trace) {
+        await this.rateLimits.run(definition.name, request, ctx, definition.rateLimit, "afterSession");
+        await this.guards.run(request, ctx, definition.guards, trace);
+    }
+    /** Idempotency replay fast path, run before the preflight: see LambderApiIdempotencyEngine.findReplay. */
+    async findReplay(request, ctx, definition, trace) {
+        if (!definition.idempotency)
+            return null;
+        return await this.idempotency.findReplay(definition.name, request, ctx, trace);
+    }
+    /** Idempotency claim/replay wrapper around handler execution: see LambderApiIdempotencyEngine.withIdempotency. */
+    async withIdempotency(request, ctx, definition, trace, exec) {
+        if (!definition.idempotency)
+            return await exec();
+        return await this.idempotency.withIdempotency(definition.name, request, ctx, definition.idempotency, trace, exec);
+    }
+}

package/dist/api/LambderApiRateLimits.d.ts

@@ -0,0 +1,206 @@
+import type { LambderApiMode } from "../shared/wire/LambderApiContract.js";
+import type { LambderRateLimitOptionValue, LambderRateLimitOverride } from "../shared/wire/LambderApiOptionValues.js";
+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 { LambderApiRefusal, type LambderAppRefusalMessage } from "../shared/wire/LambderApiRefusal.js";
+import type { LambderNonEmptyOptionMap } from "../shared/util/LambderTypeUtilities.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";
+    code: "lambder/rate-limited";
+    content: string;
+};
+/**
+ * The refusal a rate-limited call answers with: a 429 envelope carrying the
+ * framework code (a policy's own message inherits it unless it sets a more
+ * specific one) 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.
+ */
+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 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.
+ *
+ * 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.
+ */
+export type LambderRateLimitKeyFn<TInput extends z.ZodType = z.ZodType, TCtx = any> = {
+    apiInput?: TInput;
+    handler: (ctx: TCtx, payload: z.output<TInput>) => 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 type LambderRateLimitKeyBuilder<TCtx> = {
+    <TInput extends z.ZodType>(key: {
+        apiInput: TInput;
+        handler: (ctx: TCtx, payload: z.output<TInput>) => string | Promise<string>;
+    }): {
+        apiInput: TInput;
+        handler: (ctx: TCtx, payload: z.output<TInput>) => string | Promise<string>;
+    };
+    (key: {
+        handler: (ctx: TCtx, payload: undefined) => string | Promise<string>;
+    }): {
+        apiInput?: undefined;
+        handler: (ctx: TCtx, payload: undefined) => string | Promise<string>;
+    };
+};
+/**
+ * A key builder bound to a context type, the counterpart of
+ * lambderGuardBuilder. The server's lambderRateLimitKey() is this bound to
+ * the render context; the mock runtime binds it to its own call context and
+ * 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.
+ */
+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. */
+export type LambderRateLimitPer<TCtx = any> = "ip" | "session" | LambderRateLimitKeyFn<any, TCtx>;
+/**
+ * What one budget spans:
+ *
+ * - "perApi" (default): every API referencing the policy gets its own
+ *   counter, so the windows are a per-API ceiling (three APIs referencing a
+ *   60/min policy allow one subject 180/min in total). An API may tune the
+ *   windows in its declaration: `rateLimit: { name: { perMin: 20 } }`.
+ * - "perPolicy": 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). The policy IS the group: to give user APIs
+ *   and report APIs separate shared budgets, declare two policies.
+ */
+export type LambderRateLimitBudget = "perApi" | "perPolicy";
+/**
+ * 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.
+ */
+export type LambderApiRateLimitPolicyConfig<TCtx = any> = LambderRateLimitPolicy & {
+    per: LambderRateLimitPer<TCtx>;
+    /** Whether the windows are a per-API ceiling (default) or one budget shared by every referencing API. See LambderRateLimitBudget. */
+    budget?: LambderRateLimitBudget;
+    /** Envelope errorMessage for refused requests; inherits code "lambder/rate-limited" unless it sets its own. Default: a warning saying too many requests. */
+    errorMessage?: LambderAppRefusalMessage;
+};
+export type LambderApiRateLimitsConfig<TPolicies extends Record<string, LambderApiRateLimitPolicyConfig<any>>> = {
+    /** Your limiter instance (LambderDdbRateLimiter, LambderMemoryRateLimiter, or your own); its table and keyPrefix apply as configured on it. */
+    limiter: LambderRateLimiter;
+    /** Named policies referenced (typed) from addApi/addSessionApi. */
+    policies: TPolicies;
+    /**
+     * Let the request through when the limiter itself fails (the table is
+     * 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.
+     */
+    failOpen?: boolean;
+};
+/**
+ * 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.ZodType;
+        };
+    } ? (TPayload extends z.output<S> ? K : never) : K;
+}[keyof TPolicies] & string;
+type LambderRateLimitOverrideFor<TPolicy> = TPolicy extends {
+    budget: "perPolicy";
+} ? Pick<LambderRateLimitOverride, "errorMessage"> : LambderRateLimitOverride;
+/** The map form's full shape: every referable policy name, each carrying its own override. */
+type LambderRateLimitMap<TPolicies, TPayload, TIncludeSession extends boolean> = {
+    readonly [K in LambderAllowedPolicyNames<TPolicies, TPayload, TIncludeSession> & keyof TPolicies]?: true | LambderRateLimitOverrideFor<TPolicies[K]>;
+};
+/**
+ * The per-API `rateLimit` option: one policy name, a non-empty ordered list
+ * of names, or a non-empty object map that can carry each policy's override
+ * (`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.
+ */
+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.
+ */
+type LambderRateLimitPhase = "beforeSession" | "afterSession";
+/**
+ * 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.
+ */
+export declare class LambderApiRateLimitsEngine {
+    private limiter;
+    private failOpen;
+    private policies;
+    /** True once rateLimits were configured. */
+    get isConfigured(): boolean;
+    configure(config: LambderApiRateLimitsConfig<Record<string, LambderApiRateLimitPolicyConfig>>): void;
+    /** Startup validation of one API registration's rateLimit option. */
+    assertRegistration(apiName: string, mode: LambderApiMode, rateLimitOption?: LambderRateLimitOptionValue): void;
+    /**
+     * Check the API's policies in declared order; the first exceeded one
+     * refuses with a 429 envelope and a Retry-After header. Attempts count,
+     * not successes: every counter checked before the refusing one (and every
+     * 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.
+     */
+    run(apiName: string, request: LambderApiRequest, ctx: LambderApiCallContext, rateLimitOption: LambderRateLimitOptionValue | undefined, phase: LambderRateLimitPhase): Promise<void>;
+    private resolveKey;
+}
+export {};