lambder 6.0.2 → 7.0.1

package/dist/api/LambderApiGuards.d.ts

@@ -0,0 +1,302 @@
+import type { LambderNonEmptyOptionMap } from "../shared/util/LambderTypeUtilities.js";
+import type { z } from "zod";
+import type { LambderApiRequest } from "./LambderApiRequest.js";
+import type { LambderApiCallContext, LambderApiCallTrace } from "./LambderApiCallContext.js";
+import type { LambderApiMode, LambderGuardNamesIn } from "../shared/wire/LambderApiContract.js";
+import type { LambderGuardsOptionValue } from "../shared/wire/LambderApiOptionValues.js";
+import { LAMBDER_RESPONSE_BRAND } from "../shared/util/LambderResponseBrand.js";
+/**
+ * What lambderGuard() returns for a handler that answers instead of
+ * authorizing. Nothing accepts it, so the guards map is where the mistake
+ * surfaces, named.
+ */
+type LambderGuardMustNotAnswer = {
+    readonly "lambder: a guard authorizes, it does not answer. Say no with refuse() or by throwing a LambderApiRefusal.": never;
+};
+/**
+ * Intersected into the builder's parameter so the mistake is reported where
+ * it is written, at the lambderGuard() call, rather than further away where
+ * the guard is put into a map. An answering handler makes this a required
+ * property no object literal can satisfy, and the property name is the
+ * message.
+ */
+type LambderGuardAnswerCheck<TOutput> = [
+    TOutput
+] extends [never] ? unknown : 0 extends 1 & TOutput ? unknown : [Extract<TOutput, {
+    readonly [LAMBDER_RESPONSE_BRAND]: unknown;
+}>] extends [never] ? unknown : LambderGuardMustNotAnswer;
+/**
+ * A built guard, unless its handler answers instead of authorizing. Applied
+ * to the builder's RESULT rather than to its parameters, so the handler's
+ * unannotated arguments keep taking their types from the overload that
+ * matched and only the returned shape changes. A guard that hands back a
+ * response denies nothing at runtime (the value would become
+ * ctx.guardData[name] and the call would carry on), so it must not reach a
+ * guards map: this turns the ordinary spelling of that mistake into a build
+ * error, and the engine throws on the ones a cast smuggles past.
+ *
+ * Defined in terms of LambderGuardAnswerCheck so the two cannot drift: one
+ * rule for what counts as answering, read twice.
+ */
+type LambderGuardOf<TOutput, TGuard> = LambderGuardAnswerCheck<TOutput> extends LambderGuardMustNotAnswer ? LambderGuardMustNotAnswer : TGuard;
+/** One guard handler: the adapter's context, the validated input slice (undefined in the no-input mode), and the per-API parameter. */
+type LambderGuardHandler<TCtx, TPayload, TParam, TOutput> = (ctx: TCtx, payload: TPayload, param: TParam) => TOutput | Promise<TOutput>;
+/**
+ * A named guard, run before the API's own input validation. Three input
+ * modes:
+ *
+ * - `apiInput`: the guard checks fields of the API's OWN payload. The slice
+ *   is validated against the raw payload before `handler` runs and handed to
+ *   it typed. The API's input schema stays the owner of those fields:
+ *   declaring the guard on an API whose schema does not carry them is a
+ *   compile error.
+ * - `guardInput`: the guard has its own value the client sends SEPARATELY,
+ *   outside the API payload, via the caller's options.guardInputs[name].
+ *   The requirement lands on the API's contract (`guardInputs`), so the
+ *   typed caller refuses to compile a call that does not send it. The API
+ *   payload and handler never see the value.
+ * - neither: the guard reads only the context.
+ *
+ * Orthogonally, a guard may also:
+ *
+ * - declare `session: true`: the guard needs ctx.session, so it is only
+ *   declarable on addSessionApi (compile error and startup assert on public
+ *   APIs) and its handler receives the session-typed context.
+ * - take a PARAMETER: annotate a 3rd handler argument
+ *   (`(ctx, payload, param: YourType) => ...`) and APIs pass the value in
+ *   their declaration: `guards: { yourGuard: paramValue }`. The value is
+ *   trusted registration-time code (never client data), typed per guard.
+ * - RETURN a value: whatever the handler returns (awaited) is attached to
+ *   the API handler's context as `ctx.guardData[guardName]`, fully typed.
+ *   Guards that return nothing never appear in guardData.
+ *
+ * A guard says no by throwing: refuse() or a LambderApiRefusal, which the
+ * pipeline renders as the structured refusal envelope. A validation failure
+ * of its input slice answers like the API's own input validation (the app's
+ * setApiInputValidationErrorHandler when set, else the standard 422). Guards
+ * build no responses and hold no resolver, which is what lets the same
+ * engine run them on the server and in the mock runtime. Build with
+ * lambderGuard() so the handler's payload/ctx/param types line up.
+ *
+ * TCtx and TSessionCtx are the two contexts an adapter runs guards on, and
+ * an adapter's guards map pins them (the server's to the render contexts,
+ * the mock's to the mock call contexts). Left open, the binding the builder
+ * establishes was thrown away at the map: a guard written for the server
+ * compiled into a mock guards map and then read `ctx.ip` as undefined, so it
+ * authorized or refused everything.
+ */
+export type LambderApiGuard<TInput extends z.ZodType = z.ZodType, TParam = any, TOutput = any, TCtx = any, TSessionCtx = TCtx> = {
+    apiInput: TInput;
+    guardInput?: undefined;
+    session: true;
+    handler: LambderGuardHandler<TSessionCtx, z.output<TInput>, TParam, TOutput>;
+} | {
+    apiInput: TInput;
+    guardInput?: undefined;
+    session?: false;
+    handler: LambderGuardHandler<TCtx, z.output<TInput>, TParam, TOutput>;
+} | {
+    guardInput: TInput;
+    apiInput?: undefined;
+    session: true;
+    handler: LambderGuardHandler<TSessionCtx, z.output<TInput>, TParam, TOutput>;
+} | {
+    guardInput: TInput;
+    apiInput?: undefined;
+    session?: false;
+    handler: LambderGuardHandler<TCtx, z.output<TInput>, TParam, TOutput>;
+} | {
+    apiInput?: undefined;
+    guardInput?: undefined;
+    session: true;
+    handler: LambderGuardHandler<TSessionCtx, undefined, TParam, TOutput>;
+} | {
+    apiInput?: undefined;
+    guardInput?: undefined;
+    session?: false;
+    handler: LambderGuardHandler<TCtx, undefined, TParam, TOutput>;
+};
+/**
+ * The builder's shape, generic over the two context types a guard may
+ * receive: the plain one and the session-typed one. Ties the handler's
+ * payload, context, param, and output types together inside one literal
+ * and returns the exact shape so type extraction (mode, session, param,
+ * output) works downstream. The param type is inferred from the handler's
+ * 3rd argument annotation; the output from its return type.
+ */
+export type LambderGuardBuilder<TCtx, TSessionCtx> = {
+    <TInput extends z.ZodType, TParam = undefined, TOutput = void>(guard: {
+        apiInput: TInput;
+        session: true;
+        handler: (ctx: TSessionCtx, payload: z.output<TInput>, param: TParam) => TOutput | Promise<TOutput>;
+    } & LambderGuardAnswerCheck<TOutput>): LambderGuardOf<TOutput, {
+        apiInput: TInput;
+        guardInput?: undefined;
+        session: true;
+        handler: (ctx: TSessionCtx, payload: z.output<TInput>, param: TParam) => TOutput | Promise<TOutput>;
+    }>;
+    <TInput extends z.ZodType, TParam = undefined, TOutput = void>(guard: {
+        apiInput: TInput;
+        handler: (ctx: TCtx, payload: z.output<TInput>, param: TParam) => TOutput | Promise<TOutput>;
+    } & LambderGuardAnswerCheck<TOutput>): LambderGuardOf<TOutput, {
+        apiInput: TInput;
+        guardInput?: undefined;
+        session?: undefined;
+        handler: (ctx: TCtx, payload: z.output<TInput>, param: TParam) => TOutput | Promise<TOutput>;
+    }>;
+    <TInput extends z.ZodType, TParam = undefined, TOutput = void>(guard: {
+        guardInput: TInput;
+        session: true;
+        handler: (ctx: TSessionCtx, payload: z.output<TInput>, param: TParam) => TOutput | Promise<TOutput>;
+    } & LambderGuardAnswerCheck<TOutput>): LambderGuardOf<TOutput, {
+        guardInput: TInput;
+        apiInput?: undefined;
+        session: true;
+        handler: (ctx: TSessionCtx, payload: z.output<TInput>, param: TParam) => TOutput | Promise<TOutput>;
+    }>;
+    <TInput extends z.ZodType, TParam = undefined, TOutput = void>(guard: {
+        guardInput: TInput;
+        handler: (ctx: TCtx, payload: z.output<TInput>, param: TParam) => TOutput | Promise<TOutput>;
+    } & LambderGuardAnswerCheck<TOutput>): LambderGuardOf<TOutput, {
+        guardInput: TInput;
+        apiInput?: undefined;
+        session?: undefined;
+        handler: (ctx: TCtx, payload: z.output<TInput>, param: TParam) => TOutput | Promise<TOutput>;
+    }>;
+    <TParam = undefined, TOutput = void>(guard: {
+        session: true;
+        handler: (ctx: TSessionCtx, payload: undefined, param: TParam) => TOutput | Promise<TOutput>;
+    } & LambderGuardAnswerCheck<TOutput>): LambderGuardOf<TOutput, {
+        apiInput?: undefined;
+        guardInput?: undefined;
+        session: true;
+        handler: (ctx: TSessionCtx, payload: undefined, param: TParam) => TOutput | Promise<TOutput>;
+    }>;
+    <TParam = undefined, TOutput = void>(guard: {
+        handler: (ctx: TCtx, payload: undefined, param: TParam) => TOutput | Promise<TOutput>;
+    } & LambderGuardAnswerCheck<TOutput>): LambderGuardOf<TOutput, {
+        apiInput?: undefined;
+        guardInput?: undefined;
+        session?: undefined;
+        handler: (ctx: TCtx, payload: undefined, param: TParam) => TOutput | Promise<TOutput>;
+    }>;
+};
+/**
+ * A guard builder bound to a pair of context types. The server's
+ * lambderGuard() is this bound to the render contexts; the mock runtime
+ * binds it to its own handler contexts, so mock guards are the same shape
+ * as server guards and run through the same engine.
+ */
+export declare const lambderGuardBuilder: <TCtx, TSessionCtx>() => LambderGuardBuilder<TCtx, TSessionCtx>;
+/** The param type a guard's handler declares as its 3rd argument; undefined for paramless guards. */
+type LambderGuardParamOf<G> = G extends {
+    handler: (...args: infer A) => any;
+} ? (A extends [any, any, infer P, ...any[]] ? P : undefined) : undefined;
+/** What a guard's handler returns (awaited); void for check-only guards. */
+type LambderGuardOutputOf<G> = G extends {
+    handler: (...args: any[]) => infer R;
+} ? Awaited<R> : never;
+/** Per-guard metadata carried on the Lambder instance: input mode, session requirement, param type, output type. */
+export type LambderGuardMeta<G> = (G extends {
+    apiInput: infer S extends z.ZodType;
+} ? {
+    apiInput: z.output<S>;
+} : G extends {
+    guardInput: infer S extends z.ZodType;
+} ? {
+    guardInput: z.output<S>;
+} : {}) & (G extends {
+    session: true;
+} ? {
+    session: true;
+} : {}) & {
+    param: LambderGuardParamOf<G>;
+    output: LambderGuardOutputOf<G>;
+};
+export type LambderGuardMetaMap<TGuards> = {
+    [K in keyof TGuards]: LambderGuardMeta<TGuards[K]>;
+};
+type LambderGuardNameIfPayloadOk<TGuards, K extends keyof TGuards, TPayload> = TGuards[K] extends {
+    apiInput: infer R;
+} ? (TPayload extends R ? K : never) : K;
+/**
+ * Guard names an API may declare: apiInput-mode guards only when the API's
+ * payload carries their fields, session guards only on session APIs.
+ */
+export type LambderAllowedGuardNames<TGuards, TPayload, TIncludeSession extends boolean = true> = {
+    [K in keyof TGuards]: TGuards[K] extends {
+        session: true;
+    } ? (TIncludeSession extends true ? LambderGuardNameIfPayloadOk<TGuards, K, TPayload> : never) : LambderGuardNameIfPayloadOk<TGuards, K, TPayload>;
+}[keyof TGuards] & string;
+/** The allowed guard names whose handler takes no param (usable in the string/array forms). */
+export type LambderParamlessGuardNames<TGuards, TPayload, TIncludeSession extends boolean> = {
+    [K in LambderAllowedGuardNames<TGuards, TPayload, TIncludeSession> & keyof TGuards]: TGuards[K] extends {
+        param: undefined;
+    } ? K & string : never;
+}[LambderAllowedGuardNames<TGuards, TPayload, TIncludeSession> & keyof TGuards];
+/** The map form's full shape: every declarable guard name, each carrying its own param type. */
+type LambderGuardsMap<TGuards, TPayload, TIncludeSession extends boolean> = {
+    readonly [K in LambderAllowedGuardNames<TGuards, TPayload, TIncludeSession> & keyof TGuards]?: TGuards[K] extends {
+        param: undefined;
+    } ? true : TGuards[K] extends {
+        param: infer P;
+    } ? P : true;
+};
+/**
+ * The per-API `guards` option: one paramless guard name, a non-empty ordered
+ * list of paramless names, or a non-empty object map that can carry each
+ * guard's param (`true` enables a paramless guard). Map entries run in
+ * insertion order.
+ *
+ * Every form is non-empty by construction, so declaring the option is always
+ * declaring a guard. See LambderNonEmptyOptionMap.
+ */
+export type LambderGuardsOption<TGuards, TPayload, TIncludeSession extends boolean> = LambderParamlessGuardNames<TGuards, TPayload, TIncludeSession> | readonly [
+    LambderParamlessGuardNames<TGuards, TPayload, TIncludeSession>,
+    ...LambderParamlessGuardNames<TGuards, TPayload, TIncludeSession>[]
+] | LambderNonEmptyOptionMap<LambderGuardsMap<TGuards, TPayload, TIncludeSession>>;
+/**
+ * The typed ctx.guardData an API's handler sees: declared guards that return
+ * a value, keyed by name. Check-only (void) guards never appear.
+ */
+export type LambderGuardDataOf<TGuards, TOpt> = {
+    [K in LambderGuardNamesIn<TOpt> & keyof TGuards as [
+        TGuards[K] extends {
+            output: infer O;
+        } ? O : never
+    ] extends [void] ? never : K & string]: TGuards[K] extends {
+        output: infer O;
+    } ? O : never;
+};
+type GuardInputsEntries<TGuards, TOpt> = {
+    [K in Extract<LambderGuardNamesIn<TOpt>, keyof TGuards> as TGuards[K] extends {
+        guardInput: any;
+    } ? K : never]: TGuards[K] extends {
+        guardInput: infer V;
+    } ? V : never;
+};
+/** The guardInputs map an API's contract requires clients to send; never when no declared guard uses guardInput mode. */
+export type LambderGuardInputsOf<TGuards, TOpt> = keyof GuardInputsEntries<TGuards, TOpt> extends never ? never : GuardInputsEntries<TGuards, TOpt>;
+/**
+ * Runtime side of the guards subsystem: holds the defined guards, asserts
+ * API registrations against them at startup, and executes an API's declared
+ * guards during preflight. Composed into LambderApiPolicyEngine. Reads the
+ * request and writes the call context, so it runs unchanged under the
+ * server and the mock runtime.
+ */
+export declare class LambderApiGuardsEngine {
+    private guards;
+    /** True once a guards map was configured. */
+    get isConfigured(): boolean;
+    /** Take the guards map given at creation; named like the other two engines' configure(). */
+    configure(guards: Record<string, LambderApiGuard<any, any, any>>): void;
+    /** Startup validation of one API registration's guards option. */
+    assertRegistration(apiName: string, mode: LambderApiMode, guardsOption?: LambderGuardsOptionValue): void;
+    /**
+     * Run the API's guards in declared order. Refusals throw; outputs land on
+     * ctx.guardData. Each guard is recorded on the trace as it returns, so a
+     * call that a later guard refused still reports the ones that passed.
+     */
+    run(request: LambderApiRequest, ctx: LambderApiCallContext, guardsOption: LambderGuardsOptionValue | undefined, trace: LambderApiCallTrace): Promise<void>;
+}
+export {};

package/dist/api/LambderApiGuards.js

@@ -0,0 +1,134 @@
+import { parsePreflightSlice } from "./LambderApiValidationRefusal.js";
+import { LAMBDER_RESPONSE_BRAND, isLambderResponseLike } from "../shared/util/LambderResponseBrand.js";
+/**
+ * A guard builder bound to a pair of context types. The server's
+ * lambderGuard() is this bound to the render contexts; the mock runtime
+ * binds it to its own handler contexts, so mock guards are the same shape
+ * as server guards and run through the same engine.
+ */
+export const lambderGuardBuilder = () => ((guard) => guard);
+/** Normalize the three guards-option forms into ordered { name, param } entries. Internal to the engine: nothing outside it reads a guards option. */
+const toGuardEntries = (value) => {
+    if (value === undefined)
+        return [];
+    if (typeof value === "string")
+        return [{ name: value, param: undefined }];
+    if (Array.isArray(value))
+        return value.map((name) => ({ name: String(name), param: undefined }));
+    // Object form: insertion order, params passed verbatim (paramless guards
+    // are declared with `true` and their handlers take no param argument).
+    return Object.entries(value).map(([name, param]) => ({ name, param }));
+};
+/**
+ * One guard's input out of the map the client posted. The map is client
+ * data, so it is read as data: a guard named for something Object.prototype
+ * carries ("toString", "constructor") must come back absent when the client
+ * sent nothing, not as the inherited function. Guard names are deliberately
+ * unrestricted, which is what makes this the read's problem rather than the
+ * name's.
+ */
+const readGuardInput = (guardInputs, name) => guardInputs !== undefined && Object.prototype.hasOwnProperty.call(guardInputs, name) ? guardInputs[name] : undefined;
+/**
+ * Runtime side of the guards subsystem: holds the defined guards, asserts
+ * API registrations against them at startup, and executes an API's declared
+ * guards during preflight. Composed into LambderApiPolicyEngine. Reads the
+ * request and writes the call context, so it runs unchanged under the
+ * server and the mock runtime.
+ */
+export class LambderApiGuardsEngine {
+    // A Map, not an object: a plain object answers for "toString" and
+    // "constructor" through its prototype, so an API declaring one of those as
+    // a guard name would pass the registration check that exists to catch
+    // exactly that typo, and then fail on every request. It also refuses to
+    // register a guard legitimately named one of them.
+    guards = new Map();
+    /** True once a guards map was configured. */
+    get isConfigured() { return this.guards.size > 0; }
+    /** Take the guards map given at creation; named like the other two engines' configure(). */
+    configure(guards) {
+        // One configuration per instance, the rule the rate-limit and
+        // idempotency engines already hold to: a second map would silently
+        // merge into the first, and which of two same-named guards ran would
+        // depend on the order the calls happened to be made in.
+        if (this.guards.size > 0)
+            throw new Error("Lambder: guards were already configured.");
+        // Declaring the option is always declaring a guard, the same rule an
+        // API's own `guards: {}` is held to. Without this the engine stays
+        // unconfigured and every API that declares a guard is told that no
+        // guards option was given at all, which sends the reader to the wrong
+        // line.
+        if (Object.keys(guards).length === 0) {
+            throw new Error("Lambder: the guards option was declared with no guards in it, which configures nothing. Name the guards APIs will declare, or leave the option off.");
+        }
+        for (const [name, guardDef] of Object.entries(guards)) {
+            if (this.guards.has(name))
+                throw new Error(`Lambder: guard "${name}" is already defined.`);
+            if (typeof guardDef?.handler !== "function")
+                throw new Error(`Lambder: guard "${name}" has no handler function.`);
+            if (guardDef.apiInput && guardDef.guardInput)
+                throw new Error(`Lambder: guard "${name}" declares both apiInput and guardInput; pick one.`);
+            this.guards.set(name, guardDef);
+        }
+    }
+    /** Startup validation of one API registration's guards option. */
+    assertRegistration(apiName, mode, guardsOption) {
+        const entries = toGuardEntries(guardsOption);
+        // The runtime half of LambderNonEmptyGuardsMap. `guards: {}` and
+        // `guards: []` are present-but-empty: they satisfy the require*ApiGuards
+        // field check while running nothing, which is the one shape that turns a
+        // mandatory authorization declaration back into an optional one. The type
+        // rejects both; a plain-JS caller, a cast, or a spread that happened to
+        // produce an empty object lands here instead.
+        if (guardsOption !== undefined && entries.length === 0) {
+            throw new Error(`Lambder: API "${apiName}" declares an empty guards option, which authorizes nothing. ` +
+                `Name the guard that authorizes it, or omit the option entirely.`);
+        }
+        for (const { name } of entries) {
+            const guardDef = this.guards.get(name);
+            if (!guardDef) {
+                throw new Error(`Lambder: API "${apiName}" references unknown guard "${name}". Declare it in the guards option at creation.`);
+            }
+            if (guardDef.session && mode !== "session") {
+                throw new Error(`Lambder: API "${apiName}" uses guard "${name}" (session: true), which requires addSessionApi.`);
+            }
+        }
+    }
+    /**
+     * Run the API's guards in declared order. Refusals throw; outputs land on
+     * ctx.guardData. Each guard is recorded on the trace as it returns, so a
+     * call that a later guard refused still reports the ones that passed.
+     */
+    async run(request, ctx, guardsOption, trace) {
+        for (const { name, param } of toGuardEntries(guardsOption)) {
+            const guardDef = this.guards.get(name);
+            if (!guardDef)
+                throw new Error(`Lambder: guard "${name}" is not configured. Declare it in the guards option at creation.`);
+            // Recorded before anything this guard does can refuse, so the list
+            // says which guards were reached and the one that said no is the
+            // last name on it. Recording after the return named every guard
+            // except the one someone reading the trace was looking for; doing
+            // it after the slice parse below had the same effect for a guard
+            // that refuses by rejecting its own input, which answers 422 and
+            // is exactly the refusal a reader is trying to place.
+            trace.guardsRun.push(name);
+            let payload;
+            if (guardDef.apiInput) {
+                payload = parsePreflightSlice(guardDef.apiInput, request.payload);
+            }
+            else if (guardDef.guardInput) {
+                payload = parsePreflightSlice(guardDef.guardInput, readGuardInput(request.guardInputs, name));
+            }
+            // A guard's return value becomes the handler's typed
+            // ctx.guardData[name]; check-only guards return undefined.
+            const output = await guardDef.handler(ctx, payload, param);
+            if (isLambderResponseLike(output)) {
+                throw new Error(`Lambder: guard "${name}" returned a LambderResponse. A guard authorizes, it does not answer: ` +
+                    `say no with refuse() or by throwing a LambderApiRefusal. Returning a response denies nothing, ` +
+                    `because the value would be attached to ctx.guardData and the call would continue.`);
+            }
+            if (output !== undefined) {
+                ctx.guardData[name] = output;
+            }
+        }
+    }
+}

package/dist/api/LambderApiIdempotency.d.ts

@@ -0,0 +1,122 @@
+import type { LambderApiRequest } from "./LambderApiRequest.js";
+import type { LambderApiCallContext, LambderApiCallTrace } from "./LambderApiCallContext.js";
+import type { LambderApiAnswer } from "./LambderApiAnswer.js";
+import type { LambderIdempotencyStore } from "../shared/contracts/LambderIdempotencyStore.js";
+import type { LambderApiIdempotencyOption } from "../shared/wire/LambderApiOptionValues.js";
+export type LambderApiIdempotencyConfig = {
+    /** Your idempotency store instance; may share the rate limiter's table (distinct key prefix). */
+    store: LambderIdempotencyStore;
+    /** Seconds a stored response replays for. Default: 86400 (24h). Per-API override: idempotency: { ttlSeconds }. */
+    defaultTtlSeconds?: number;
+    /**
+     * Seconds a claim stays pending before a retry may take the scope.
+     * Default: 300. Raise it past the longest a handler of yours can run, or
+     * a retry arriving after it expires executes the operation again while
+     * the original is still working. Per-API override:
+     * idempotency: { pendingTtlSeconds }.
+     */
+    defaultPendingTtlSeconds?: number;
+    /** Skip idempotency (execute normally) when the store errors, instead of failing the request. Default: true. */
+    failOpen?: boolean;
+    /**
+     * Who a request is acting as, for scoping a PUBLIC API's stored answer.
+     * Session APIs already scope per session, so this only affects the ones
+     * that do not have a session to scope by.
+     *
+     * Without it, a public API's scope is the posted key alone, which makes
+     * that key a bearer token for its own stored answer: anyone presenting it
+     * gets the response back, and the replay is served BEFORE guards run, so
+     * an API whose authorization is a guard hands its answer over without the
+     * guard ever being consulted. Returning an identity here puts that caller
+     * in the scope, so a key only replays to whoever it was issued to.
+     *
+     * Consulted only on public APIs, and a public API reads no session, so
+     * there is no session here to read: the context arrives without one, and
+     * an identity that came from a session would be the session scope the
+     * engine already applies. It sees what the request itself carries, and
+     * that is the point of it: `request.guardInputs`, `request.payload`,
+     * `request.headers` and `request.ip`.
+     *
+     * Read the credential a guard would check, not a value that changes
+     * between attempts: a single-use token (a captcha) would give the
+     * legitimate retry a different scope and defeat the replay it needs.
+     * Return null for requests with no identity to speak of.
+     */
+    callerIdentity?: (ctx: Omit<LambderApiCallContext, "session">, request: LambderApiRequest) => string | null | Promise<string | null>;
+};
+/**
+ * Runtime side of the idempotency subsystem: claims a per-operation scope
+ * around handler execution, replays stored answers, and settles claims.
+ * Composed into LambderApiPolicyEngine. Works on plain answers, so it runs
+ * unchanged under the server and the mock runtime.
+ */
+export declare class LambderApiIdempotencyEngine {
+    private store;
+    private defaultTtlSeconds;
+    private defaultPendingTtlSeconds;
+    private failOpen;
+    private callerIdentity;
+    /**
+     * The scope this call resolved to, keyed by its context, which is the one
+     * object per call the engine is handed. A keyed request asks for it
+     * twice, at the replay lookup and at the claim, and callerIdentity is app
+     * code that may verify a token or read a store: running it twice per
+     * request is a cost the app never asked for, and one it cannot see.
+     * Entries go when the call's context does.
+     */
+    private readonly scopeByCall;
+    configure(config: LambderApiIdempotencyConfig): void;
+    /** Startup validation of one API registration's idempotency option. */
+    assertRegistration(apiName: string, config: LambderApiIdempotencyOption): void;
+    /** True once the idempotency option was configured; 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 unless the
+     * app supplies callerIdentity, because 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: the retry idempotency exists
+     * for (a timeout followed by a network change) frequently arrives from a
+     * different IP. An app whose public APIs are authorized by a guard should
+     * give callerIdentity, since the replay is served before guards run.
+     *
+     * Fields are escaped and joined through joinKeyFields, so no two distinct
+     * scopes can produce one string.
+     */
+    private scopeOf;
+    private computeScope;
+    /**
+     * Replay fast path, run before the remaining rate limits and before
+     * guards: a completed record answers with its stored answer, so a
+     * legitimate retry neither burns rate-limit quota nor re-runs guards (the
+     * original already passed them, and no handler executes). The `per: "ip"`
+     * limits are the exception and are checked ahead of this, since the store
+     * read a replay costs is one of the things they exist to bound. Misses
+     * fall through to the normal pipeline; store errors follow the failOpen
+     * setting.
+     */
+    findReplay(apiName: string, request: LambderApiRequest, ctx: LambderApiCallContext, trace: LambderApiCallTrace): Promise<LambderApiAnswer | 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 answer verbatim, and a crashed original releases its claim
+     * so a retry actually retries.
+     *
+     * `exec` must hand back the handler's own answer, the headers the handler
+     * itself wrote included: the pipeline applies those before returning here,
+     * so a Set-Cookie the handler set is visible to the caching rule below.
+     * Headers written EARLIER in the call (a session read evicting a stale
+     * cookie) are deliberately not on it: they are the call's, they reach the
+     * client either way, and charging them to this answer would make an
+     * idempotent operation silently stop being idempotent.
+     */
+    withIdempotency(apiName: string, request: LambderApiRequest, ctx: LambderApiCallContext, config: LambderApiIdempotencyOption, trace: LambderApiCallTrace, exec: () => Promise<LambderApiAnswer>): Promise<LambderApiAnswer>;
+}