lambder 8.1.2 → 8.3.1

package/dist/mock/LambderMockApp.js

@@ -47,7 +47,8 @@ const defaultCookieHost = () => globalThis.location?.host || "localhost";
  *
  * Create one with initLambderMock<Contract, SessionData>().create(...),
  * which fixes the contract and session types first so everything else is
- * inferred from the options.
+ * inferred from the options. `TDerived` is true for a mock created with the
+ * generated `apiOptions` table, whose entries are their handlers alone.
  */
 export class LambderMockApp {
     apiVersion;
@@ -85,10 +86,13 @@ export class LambderMockApp {
     recorder;
     /** Registered entries and the overrides over them (see LambderMockEntryRegistry). */
     registry = new LambderMockEntryRegistry();
+    /** The server's declared options per API, when create() was given the generated table; the entries' declarations come from here. */
+    apiOptions;
     /** The jars the runtime owns and what it planted in document.cookie (see LambderMockBrowserCookies). */
     browserCookies = new LambderMockBrowserCookies();
     constructor(options) {
         this.apiVersion = options.apiVersion ?? null;
+        this.apiOptions = options.apiOptions ?? null;
         this.failures = new LambderMockFailureInjector({ apiVersion: this.apiVersion, latency: options.latency ?? 0 });
         this.recorder = new LambderMockCallRecorder({ callLogSize: options.callLogSize ?? DEFAULT_CALL_LOG_SIZE });
         // The loopback address when nothing names a client, as for a request
@@ -196,13 +200,49 @@ export class LambderMockApp {
             throw new Error(`LambderMockApp: session endpoint "${definition.name}" needs the sessions option at creation.`);
         }
     }
+    /**
+     * The table's entry for an endpoint, when create() was given one: null
+     * without a table, and a throw for a name the table does not hold or an
+     * entry registered under the other mode. The compiler already refuses
+     * both against the contract; this is where a stale table meets a caller
+     * the compiler did not see.
+     */
+    declaredOptionsOf(name, mode) {
+        if (!this.apiOptions)
+            return null;
+        const declared = Object.prototype.hasOwnProperty.call(this.apiOptions, name) ? this.apiOptions[name] : undefined;
+        if (!declared) {
+            throw new Error(`LambderMockApp: "${name}" has no entry in the apiOptions table given to create(). The table predates this endpoint: regenerate it with writeApiOptions.`);
+        }
+        if (declared.mode !== mode) {
+            throw new Error(`LambderMockApp: "${name}" is a ${declared.mode} endpoint in the apiOptions table, registered here as a ${mode} one.`);
+        }
+        return declared;
+    }
+    /** The mode the apiOptions table gives a name, or null without a table or for a name it does not hold. */
+    declaredModeOf(name) {
+        if (!this.apiOptions || !Object.prototype.hasOwnProperty.call(this.apiOptions, name))
+            return null;
+        return this.apiOptions[name].mode;
+    }
     buildEntry(name, mode, input) {
         const options = (typeof input === "function" ? { handler: input } : input);
+        const declared = this.declaredOptionsOf(name, mode);
+        if (declared) {
+            // A caller the compiler did not see (a JavaScript slice, a cast)
+            // would otherwise have its restatement silently lose to the table.
+            for (const field of ["guards", "rateLimit", "idempotency"]) {
+                if (options[field] !== undefined) {
+                    throw new Error(`LambderMockApp: "${name}" restates its ${field} option, which the apiOptions table given to create() already declares. Leave it out of the entry.`);
+                }
+            }
+        }
+        const declarations = declared ?? options;
         const definition = {
             name, mode,
-            guards: options.guards,
-            rateLimit: options.rateLimit,
-            idempotency: options.idempotency,
+            guards: declarations.guards,
+            rateLimit: declarations.rateLimit,
+            idempotency: declarations.idempotency,
             // No cast: the entry's schema is a z.ZodType, the same type the
             // definition holds. A structural { safeParse } here would let a
             // validator that is not a zod schema reach the 422 body as
@@ -257,18 +297,21 @@ export class LambderMockApp {
      * still refused, and an entry registered later (registerPartial, or a
      * second register) takes its endpoint back from the rest.
      *
-     * What it cannot do is the session read. The mode of an unregistered name
-     * is not knowable at runtime (the contract is a type), so a call it
-     * answers is processed as public: the protocol's pre-pass still runs, so
-     * a stale client still hears versionExpired, but a signed-out call to an
-     * unmocked session endpoint answers "not mocked" where the server answers
-     * sessionExpired. Declare an endpoint whose signed-out path a test cares
-     * about with sessionNotMocked instead.
+     * The mode of an unregistered name comes from the apiOptions table, when
+     * create() was given one, so an unmocked session endpoint still reads the
+     * session and a signed-out call answers sessionExpired as on the server.
+     * Without the table the mode is not knowable at runtime (the contract is
+     * a type), and a call it answers is processed as public: the protocol's
+     * pre-pass still runs, so a stale client still hears versionExpired, but
+     * a signed-out call to an unmocked session endpoint answers "not mocked"
+     * where the server answers sessionExpired. Declare an endpoint whose
+     * signed-out path a test cares about with sessionNotMocked there.
      */
     restNotMocked(reason) {
         return { restNotMockedReason: reason };
     }
     buildNotMockedEntry(name, mode, reason) {
+        this.declaredOptionsOf(name, mode);
         const definition = { name, mode };
         this.assertEntryRegistration(definition);
         return { name, mode, definition, handler: null, notMockedReason: reason };
@@ -352,16 +395,18 @@ export class LambderMockApp {
     /**
      * The entry that answers a name nothing registered, when register() was
      * given a rest entry: the notMocked refusal carrying its reason, run
-     * through the pipeline as a public endpoint, since the mode of an
-     * unregistered name cannot be recovered at runtime. Everything before
-     * dispatch still runs (the signature gate, the payload restore); the
-     * missing session read is the fidelity limit restNotMocked documents.
+     * through the pipeline under the mode the apiOptions table gives the
+     * name, and as a public endpoint where there is no table to say (the
+     * mode of an unregistered name cannot otherwise be recovered at runtime).
+     * Everything before dispatch still runs (the signature gate, the payload
+     * restore, and for a session endpoint the session read).
      */
     restNotMockedEntry(apiName) {
         const reason = this.registry.restNotMockedReason;
         if (reason === null)
             return null;
-        return { name: apiName, mode: "public", definition: { name: apiName, mode: "public" }, handler: null, notMockedReason: reason };
+        const mode = this.declaredModeOf(apiName) ?? "public";
+        return { name: apiName, mode, definition: { name: apiName, mode }, handler: null, notMockedReason: reason };
     }
     // -----------------------------------------------------------------------
     // Control surface
@@ -581,12 +626,13 @@ export class LambderMockApp {
         const id = this.recorder.nextCallId();
         const registered = this.entryFor(request.apiName);
         // The rest entry answers whatever nothing registered, when register()
-        // was given one. The mode reported stays the registered entry's, so it
-        // is null here exactly as it is for a name the registry does not know:
-        // the rest answer is processed as public, which is a property of the
-        // answer rather than a claim about the endpoint.
+        // was given one. The mode reported is the registered entry's, or the
+        // apiOptions table's for a name it holds, and null otherwise, exactly
+        // as for a name nothing knows: without the table a rest answer is
+        // processed as public, which is a property of the answer rather than
+        // a claim about the endpoint.
         const entry = registered ?? this.restNotMockedEntry(request.apiName);
-        const mode = registered?.mode ?? null;
+        const mode = registered?.mode ?? this.declaredModeOf(request.apiName);
         const facts = this.callFacts(id, request, mode);
         const startedAt = facts.startedAt;
         const ctx = this.createContext(request);

package/dist/mock/LambderMockCreateOptions.d.ts

@@ -3,8 +3,9 @@ import type { LambderApiSignatureMap } from "../shared/wire/LambderApiSignature.
 import type { LambderApiResponseConfig } from "../shared/wire/LambderApiContract.js";
 import type { LambderHttpStatusCode } from "../shared/wire/LambderHttpStatus.js";
 import type { MaybePromise } from "../shared/util/LambderTypeUtilities.js";
-import type { LambderContractGuardNames, LambderContractIdempotencyOf, LambderContractKeysWithMode, LambderContractRateLimitNames, LambderContractRateLimitOf } from "../shared/wire/LambderApiContract.js";
+import type { LambderContractGuardNames, LambderContractIdempotencyOf, LambderContractKeysWithMode, LambderContractMode, LambderContractRateLimitNames, LambderContractRateLimitOf } from "../shared/wire/LambderApiContract.js";
 import type { LambderApiGuard } from "../api/LambderApiGuards.js";
+import type { LambderApiOptionEntry, LambderGuardDeclarationEntry } from "../shared/wire/LambderApiOptionEntries.js";
 import type { LambderApiRateLimitPolicyConfig } from "../api/LambderApiRateLimits.js";
 import type { LambderApiRequest } from "../api/LambderApiRequest.js";
 import type { LambderApiTransport } from "../shared/transport/LambderApiTransport.js";
@@ -114,6 +115,37 @@ type LambderMockRateLimitsOptions<C, S, P extends LambderMockRateLimitPolicies<S
     /** Let a call through when the limiter throws, instead of refusing it. Default: true. */
     failOpen?: boolean;
 };
+/**
+ * The shape a mock guard has to have to stand in for a server guard the
+ * generated `guardDeclarations` table describes: the same input mode and the
+ * same session requirement. The contract cannot say these for every guard
+ * (it names a guardInput's shape, and nothing about a guard fed from the
+ * payload or from nothing), so a mock guard that reads a payload slice the
+ * server's guard never sees, or that requires a session where the server's
+ * does not, would run and decide differently without this.
+ */
+export type LambderMockGuardShapeOf<D> = (D extends {
+    input: "apiInput";
+} ? {
+    apiInput: z.ZodType;
+} : D extends {
+    input: "guardInput";
+} ? {
+    guardInput: z.ZodType;
+} : {
+    apiInput?: undefined;
+    guardInput?: undefined;
+}) & (D extends {
+    session: true;
+} ? {
+    session: true;
+} : {
+    session?: false | undefined;
+});
+/** Each mock guard the declarations know held to its declared shape; a guard the table does not have is free. */
+type LambderMockGuardsAgree<G, D> = {
+    [N in keyof G & keyof D]: G[N] extends LambderMockGuardShapeOf<D[N]> ? unknown : LambderMockGuardShapeOf<D[N]>;
+};
 /**
  * The guards option: required whenever the contract declares any guard name,
  * omittable only for a contract that declares none.
@@ -123,12 +155,12 @@ type LambderMockRateLimitsOptions<C, S, P extends LambderMockRateLimitPolicies<S
  * would answer 200 here. Optional, it would be the droppable half of exactly
  * the check it exists for.
  */
-type LambderMockGuardsOption<C, S, G> = [
+type LambderMockGuardsOption<C, S, G, D> = [
     LambderContractGuardNames<C>
 ] extends [never] ? {
-    guards?: G & LambderMockGuards<C, S> & LambderMockGuardShapes<S, G>;
+    guards?: G & LambderMockGuards<C, S> & LambderMockGuardShapes<S, G> & LambderMockGuardsAgree<G, NoInfer<D>>;
 } : {
-    guards: G & LambderMockGuards<C, S> & LambderMockGuardShapes<S, G>;
+    guards: G & LambderMockGuards<C, S> & LambderMockGuardShapes<S, G> & LambderMockGuardsAgree<G, NoInfer<D>>;
 };
 /**
  * The sessions, idempotency and rateLimits options: each required whenever
@@ -168,7 +200,38 @@ type LambderMockRateLimitsOption<C, S, P extends LambderMockRateLimitPolicies<S>
 type LambderMockGuardShapes<S, G> = {
     [N in keyof G]: LambderMockSurplusKeys<G[N], LambderApiGuard<any, any, any, LambderMockCallContext<S>, LambderMockSessionCallContext<S>>>;
 };
-export type LambderMockAppOptions<C, S, G, P extends LambderMockRateLimitPolicies<S> = LambderMockRateLimitPolicies<S>, I extends boolean | LambderMockIdempotencyOptions<S> = boolean | LambderMockIdempotencyOptions<S>> = LambderMockGuardsOption<C, S, G> & LambderMockSessionsOption<C, S> & LambderMockIdempotencyOption<C, S, I> & LambderMockRateLimitsOption<C, S, P> & {
+/**
+ * What the generated `apiOptions` table has to hold to stand in for the
+ * restated declarations of a contract's entries: an entry for every endpoint
+ * the contract declares, of the endpoint's mode. A table generated before an
+ * endpoint was added, or before one changed mode, is a compile error at the
+ * option rather than a throw when that endpoint's entry registers.
+ */
+export type LambderMockApiOptionsCover<C> = {
+    [K in keyof C & string]: {
+        mode: LambderContractMode<C, K>;
+    };
+};
+export type LambderMockAppOptions<C, S, G, P extends LambderMockRateLimitPolicies<S> = LambderMockRateLimitPolicies<S>, I extends boolean | LambderMockIdempotencyOptions<S> = boolean | LambderMockIdempotencyOptions<S>, D extends Record<string, LambderGuardDeclarationEntry> = {}, A extends Record<string, LambderApiOptionEntry> | undefined = undefined> = LambderMockGuardsOption<C, S, G, D> & LambderMockSessionsOption<C, S> & LambderMockIdempotencyOption<C, S, I> & LambderMockRateLimitsOption<C, S, P> & {
+    /**
+     * The server's guard declarations, as the generated options module
+     * exports them (`guardDeclarations`). Given, every mock guard of a name
+     * the table has is held to its input mode and session requirement at
+     * the `guards` option (see LambderMockGuardShapeOf). Nothing runs on it.
+     */
+    guardDeclarations?: D;
+    /**
+     * The server's declared options per API, as the generated options module
+     * exports them (`apiOptions`). Given, every entry's guards, rateLimit and
+     * idempotency are read off the table rather than restated: an entry is
+     * its handler (and an input schema, if it has one), a restated option is
+     * a compile error, and an endpoint whose mode the table and the builder
+     * disagree on is refused at registration. A restNotMocked answer reads
+     * the endpoint's mode off the table too, so a session endpoint nothing
+     * mocks still reads the session first. The table has to cover the
+     * contract (see LambderMockApiOptionsCover).
+     */
+    apiOptions?: A & LambderMockApiOptionsCover<C>;
     /** Stamped on every answer's envelope as apiVersion, as the server's option is. */
     apiVersion?: string;
     /** The version floor, as on the server: a call naming a lower `version` answers versionExpired whatever its signature says. */

package/dist/mock/LambderMockTypes.d.ts

@@ -186,8 +186,26 @@ type LambderMockInputPin<C, K extends keyof C, TSchema extends z.ZodType> = [
 }) : {
     "LambderMockApp: this input schema takes something else than the endpoint's contract input": LambderMockInputOf<C, K>;
 };
-/** An entry written in full: the declarations restated and pinned, plus the handler. */
-export type LambderMockEntryOptions<C, K extends keyof C, S, G, TInputSchema extends z.ZodType = z.ZodType> = LambderMockGuardsField<C, K> & LambderMockRateLimitField<C, K> & LambderMockIdempotencyField<C, K> & {
+/**
+ * The three declaration fields of an entry on a mock created with the
+ * generated `apiOptions` table: absent, because the runtime reads them off
+ * the table. A restatement beside the table would be a second copy of the
+ * server's declaration, so writing one is an error rather than an override.
+ */
+type LambderMockDerivedFields = {
+    /** Read off the apiOptions table given to create(); not restated. */
+    guards?: never;
+    /** Read off the apiOptions table given to create(); not restated. */
+    rateLimit?: never;
+    /** Read off the apiOptions table given to create(); not restated. */
+    idempotency?: never;
+};
+/**
+ * An entry written in full: the handler, and the declarations restated and
+ * pinned to the contract, or, with `TDerived` (a mock created with the
+ * generated `apiOptions` table), the handler alone.
+ */
+export type LambderMockEntryOptions<C, K extends keyof C, S, G, TInputSchema extends z.ZodType = z.ZodType, TDerived extends boolean = false> = (TDerived extends true ? LambderMockDerivedFields : LambderMockGuardsField<C, K> & LambderMockRateLimitField<C, K> & LambderMockIdempotencyField<C, K>) & {
     /**
      * A schema to validate the posted payload against, so the mock answers
      * 422 exactly as the server would. Optional, and the mock's own: the
@@ -201,15 +219,16 @@ export type LambderMockEntryOptions<C, K extends keyof C, S, G, TInputSchema ext
     handler: LambderMockHandler<C, K, S, G>;
 };
 /**
- * What publicApi/sessionApi accept: a bare handler only for an endpoint the
- * contract declares nothing for, the full options otherwise, so the form that
- * cannot carry a restatement is unavailable exactly where one is owed. Keyed
- * on all three declarations: keyed on guards alone, a guardless endpoint
- * could drop its rate limit and idempotency through the bare form.
+ * What publicApi/sessionApi accept. On a mock created with the generated
+ * `apiOptions` table (`TDerived`), a bare handler or the options without the
+ * declarations, for every endpoint. Otherwise a bare handler only for an
+ * endpoint the contract declares nothing for, the full options elsewhere, so
+ * the form that cannot carry a restatement is unavailable exactly where one
+ * is owed. Keyed on all three declarations: keyed on guards alone, a
+ * guardless endpoint could drop its rate limit and idempotency through the
+ * bare form.
  */
-export type LambderMockEntryInput<C, K extends keyof C, S, G, TInputSchema extends z.ZodType = z.ZodType> = [
-    LambderContractGuardsOf<C, K> | LambderContractRateLimitOf<C, K> | LambderContractIdempotencyOf<C, K>
-] extends [never] ? LambderMockHandler<C, K, S, G> | LambderMockEntryOptions<C, K, S, G, TInputSchema> : LambderMockEntryOptions<C, K, S, G, TInputSchema>;
+export type LambderMockEntryInput<C, K extends keyof C, S, G, TInputSchema extends z.ZodType = z.ZodType, TDerived extends boolean = false> = TDerived extends true ? LambderMockHandler<C, K, S, G> | LambderMockEntryOptions<C, K, S, G, TInputSchema, true> : [LambderContractGuardsOf<C, K> | LambderContractRateLimitOf<C, K> | LambderContractIdempotencyOf<C, K>] extends [never] ? LambderMockHandler<C, K, S, G> | LambderMockEntryOptions<C, K, S, G, TInputSchema> : LambderMockEntryOptions<C, K, S, G, TInputSchema>;
 /** One registry entry: the endpoint's definition as the pipeline runs it, and its handler (null when registered as not mocked). */
 export type LambderMockEntry<C, K extends keyof C & string> = {
     readonly name: K;

package/dist/mock/lambderMockPoliciesFrom.d.ts

@@ -0,0 +1,51 @@
+import type { LambderRateLimitKeyFn } from "../api/LambderApiRateLimits.js";
+import type { LambderRateLimitPolicyEntry } from "../shared/wire/LambderApiOptionEntries.js";
+/** The names of the policies in a generated table whose key the app derives, and so the ones a mock has to supply a key handler for. */
+export type LambderCustomKeyedPolicyNames<TPolicies> = {
+    [N in keyof TPolicies]: TPolicies[N] extends {
+        per: "custom";
+    } ? N : never;
+}[keyof TPolicies] & string;
+/** One policy as the mock runs it: the table's entry with its `per` put back, the key handler for a custom one and the literal for the rest. */
+type LambderMockPolicyOf<TPolicy, TKey> = Omit<TPolicy, "per"> & (TPolicy extends {
+    per: "custom";
+} ? {
+    per: TKey;
+} : TPolicy extends {
+    per: infer P;
+} ? {
+    per: P;
+} : {});
+/** The key handlers a table needs: one per custom-keyed policy, none where the table has none. */
+export type LambderMockPolicyKeys<TPolicies> = {
+    [N in LambderCustomKeyedPolicyNames<TPolicies>]: LambderRateLimitKeyFn<any, any>;
+};
+/**
+ * The rate-limit policies a mock's create() takes, built from a generated
+ * `rateLimitPolicies` table and the key handlers for its custom-keyed
+ * policies (built with the mock's own `rateLimitKey`, so they see the mock's
+ * context). Required for exactly those policies, refused for any other:
+ *
+ * ```ts
+ * const mockApp = mock.create({
+ *     rateLimits: {
+ *         policies: lambderMockPoliciesFrom(rateLimitPolicies, {
+ *             keys: {
+ *                 codePerEmail: mock.rateLimitKey({ apiInput: z.object({ email: z.string() }), handler: (_ctx, { email }) => email.toLowerCase() }),
+ *             },
+ *         }),
+ *     },
+ * });
+ * ```
+ *
+ * Everything else about a policy (windows, budget, charge point, message) is
+ * the table's, so a mock never disagrees with the server about a limit it
+ * did not mean to change. The result keeps each policy's `per` and `budget`
+ * as literals, which is what lets create() hold it to the contract.
+ */
+export declare const lambderMockPoliciesFrom: <const TPolicies extends Record<string, LambderRateLimitPolicyEntry>, const TKeys extends LambderMockPolicyKeys<TPolicies> = LambderMockPolicyKeys<TPolicies>>(policies: TPolicies, options: [LambderCustomKeyedPolicyNames<TPolicies>] extends [never] ? {
+    keys?: TKeys & Record<Exclude<keyof TKeys, LambderCustomKeyedPolicyNames<TPolicies>>, never>;
+} : {
+    keys: TKeys & Record<Exclude<keyof TKeys, LambderCustomKeyedPolicyNames<TPolicies>>, never>;
+}) => { [N in keyof TPolicies]: LambderMockPolicyOf<TPolicies[N], N extends keyof TKeys ? TKeys[N] : never>; };
+export {};

package/dist/mock/lambderMockPoliciesFrom.js

@@ -0,0 +1,46 @@
+/**
+ * The rate-limit policies a mock's create() takes, built from a generated
+ * `rateLimitPolicies` table and the key handlers for its custom-keyed
+ * policies (built with the mock's own `rateLimitKey`, so they see the mock's
+ * context). Required for exactly those policies, refused for any other:
+ *
+ * ```ts
+ * const mockApp = mock.create({
+ *     rateLimits: {
+ *         policies: lambderMockPoliciesFrom(rateLimitPolicies, {
+ *             keys: {
+ *                 codePerEmail: mock.rateLimitKey({ apiInput: z.object({ email: z.string() }), handler: (_ctx, { email }) => email.toLowerCase() }),
+ *             },
+ *         }),
+ *     },
+ * });
+ * ```
+ *
+ * Everything else about a policy (windows, budget, charge point, message) is
+ * the table's, so a mock never disagrees with the server about a limit it
+ * did not mean to change. The result keeps each policy's `per` and `budget`
+ * as literals, which is what lets create() hold it to the contract.
+ */
+export const lambderMockPoliciesFrom = (policies, options) => {
+    const keys = (options.keys ?? {});
+    const built = {};
+    for (const [name, entry] of Object.entries(policies)) {
+        const { per, ...rest } = entry;
+        if (per === "custom") {
+            const key = keys[name];
+            if (typeof key?.handler !== "function") {
+                throw new Error(`LambderMockApp: rate-limit policy "${name}" is keyed by a handler of the server's, so the mock has to supply one: lambderMockPoliciesFrom(rateLimitPolicies, { keys: { ${name}: mock.rateLimitKey({ ... }) } }).`);
+            }
+            built[name] = { ...rest, per: key };
+        }
+        else {
+            built[name] = per === undefined ? { ...rest } : { ...rest, per };
+        }
+    }
+    for (const name of Object.keys(keys)) {
+        if (policies[name]?.per !== "custom") {
+            throw new Error(`LambderMockApp: a key handler was given for rate-limit policy "${name}", which the server ${name in policies ? "does not key by a handler" : "does not declare"}.`);
+        }
+    }
+    return built;
+};

package/dist/mock.d.ts

@@ -10,6 +10,9 @@ export { LambderMockApp, initLambderMock } from "./mock/LambderMockApp.js";
 export { LambderMockTransportError } from "./mock/LambderMockFailureInjector.js";
 export type { LambderMockAppOptions, LambderMockSessionsOptions, LambderMockIdempotencyOptions, LambderMockInvalidInputAnswer, LambderMockTransport, LambderMockTransportOptions } from "./mock/LambderMockCreateOptions.js";
 export type { LambderMockCallContext, LambderMockSessionCallContext, LambderMockContext, LambderMockGuards, LambderMockHandler, LambderMockEntry, LambderMockEntryOptions, LambderMockEntryInput, LambderMockSlice, LambderMockRestEntry, LambderMockRegistryCheck, LambderMockMissingNames, LambderMockStrayNames, LambderMockDuplicateNames, LambderMockPublicNames, LambderMockSessionNames, LambderMockLatency, LambderMockFailure, LambderMockFailureReason, LambderMockOutcome, LambderMockCallEvent, LambderMockRequestEvent, LambderMockResponseEvent, LambderMockCallRecord, LambderMockListener, LambderMockRateLimitPolicies, LambderMockInputOf, LambderMockOutputOf, LambderMockOverride, } from "./mock/LambderMockTypes.js";
+export { lambderMockPoliciesFrom } from "./mock/lambderMockPoliciesFrom.js";
+export type { LambderCustomKeyedPolicyNames, LambderMockPolicyKeys } from "./mock/lambderMockPoliciesFrom.js";
+export type { LambderMockGuardShapeOf } from "./mock/LambderMockCreateOptions.js";
 export { lambderMockConsoleLogger } from "./mock/lambderMockConsoleLogger.js";
 export type { LambderMockConsoleLoggerOptions } from "./mock/lambderMockConsoleLogger.js";
 export { lambderMockMswHandler } from "./mock/lambderMockMswHandler.js";

package/dist/mock.js

@@ -12,6 +12,9 @@ export { LambderMockApp, initLambderMock } from "./mock/LambderMockApp.js";
 // exported: the runtime is reached through the app. Only the error a
 // transport rejects with is public.
 export { LambderMockTransportError } from "./mock/LambderMockFailureInjector.js";
+// The server's rate-limit policies as the mock restates them, from the
+// generated options module plus the key handlers the module cannot hold.
+export { lambderMockPoliciesFrom } from "./mock/lambderMockPoliciesFrom.js";
 export { lambderMockConsoleLogger } from "./mock/lambderMockConsoleLogger.js";
 export { lambderMockMswHandler } from "./mock/lambderMockMswHandler.js";
 // The storage a mock app's uploads go to: a memory bucket the mock's ticket and

package/dist/secrets/LambderOneShotSecrets.d.ts

@@ -0,0 +1,166 @@
+import type { LambderOneShotSecretStore } from "../shared/contracts/LambderOneShotSecretStore.js";
+/**
+ * The shapes a kind of secret takes, told apart by how they are redeemed. A
+ * code is bound to a scope the app names (an address for a purpose, a
+ * recipient, a device), redeemed with that scope, and defended by a ceiling on
+ * tries, which is what lets it be short. A token carries its own identity, is
+ * redeemed by value alone, and has no ceiling: random bytes, long enough that
+ * guessing is not a thing, or, for a code somebody types without knowing what
+ * it is for (a pairing code), characters of an alphabet, which is guessable
+ * and which the app then holds off another way, such as a rate limit per
+ * address.
+ */
+export type LambderOneShotSecretKind = {
+    shape: "code";
+    /** The characters a code is drawn from, each once. Default: the ten digits. */
+    alphabet?: string;
+    length: number;
+    ttlSeconds: number;
+    /** Wrong tries the code survives; the try that would pass this refuses the code as exhausted, right or wrong. */
+    maxAttempts: number;
+} | {
+    shape: "token";
+    /** Random bytes behind the token, which is their base64url. Default: 32. */
+    bytes?: number;
+    alphabet?: undefined;
+    length?: undefined;
+    ttlSeconds: number;
+} | {
+    shape: "token";
+    /** The characters the token is drawn from, each once, for a token somebody types. */
+    alphabet: string;
+    length: number;
+    bytes?: undefined;
+    ttlSeconds: number;
+};
+export type LambderOneShotSecretsOptions<TKinds extends Record<string, LambderOneShotSecretKind>> = {
+    store: LambderOneShotSecretStore;
+    /** Keys every digest at rest, so a copied store cannot be attacked offline. Server side only. */
+    secret: string;
+    kinds: TKinds;
+    /** The clock, in epoch milliseconds. Default: Date.now. */
+    now?: () => number;
+};
+export type LambderOneShotIssueResult = {
+    issued: true;
+    /** The secret, as it leaves this module the one time it does: a code as written, a token as base64url. */
+    plaintext: string;
+    /** Epoch seconds. */
+    expiresAt: number;
+} | {
+    issued: false;
+    refused: "cooldown"; /** Epoch seconds when the cooldown ends. */
+    retryAt: number;
+};
+export type LambderOneShotRedeemResult = 
+/** The secret is the one out: spent now, with the scope it proved and what the app stored beside it. */
+{
+    state: "accepted";
+    scope: string;
+    meta: Record<string, string>;
+    issuedAt: number;
+}
+/** Not the code that is out; the try was counted. */
+ | {
+    state: "wrong";
+    attemptsLeft: number;
+}
+/** The code that is out has run out of time; ask for a new one. */
+ | {
+    state: "expired";
+}
+/** The code that is out has run out of tries, this one included; ask for a new one. */
+ | {
+    state: "exhausted";
+}
+/** Nothing is out for this scope or this value: never issued, spent, replaced, retired, or unknown. */
+ | {
+    state: "none";
+};
+/** The names of the kinds a scoped code is redeemed under. */
+export type LambderOneShotCodeKindNames<TKinds> = {
+    [K in keyof TKinds]: TKinds[K] extends {
+        shape: "code";
+    } ? K : never;
+}[keyof TKinds] & string;
+/** The names of the kinds a token is redeemed under, by value. */
+export type LambderOneShotTokenKindNames<TKinds> = {
+    [K in keyof TKinds]: TKinds[K] extends {
+        shape: "token";
+    } ? K : never;
+}[keyof TKinds] & string;
+/**
+ * Codes and tokens an app hands out once and takes back once, over a store
+ * that settles their races.
+ *
+ * ```ts
+ * const secrets = new LambderOneShotSecrets({
+ *     store: new LambderDdbOneShotSecretStore({ tableName: "app-policies" }),
+ *     secret: ONE_SHOT_SECRET,
+ *     kinds: {
+ *         emailCode: { shape: "code", length: 6, ttlSeconds: 600, maxAttempts: 5 },
+ *         activationLink: { shape: "token", ttlSeconds: 48 * 3600 },
+ *     },
+ * });
+ *
+ * const issued = await secrets.issue("emailCode", `register:${email}`, { cooldownSeconds: 30 });
+ * if(issued.issued) await sendEmail(email, issued.plaintext);
+ *
+ * const redeemed = await secrets.redeem("emailCode", `register:${email}`, typedCode);
+ * if(redeemed.state !== "accepted") refuse(...);
+ * ```
+ *
+ * The store holds digests only, keyed under the app's secret with the kind
+ * and the scope folded in: a code issued to two scopes never collides, and a
+ * code cannot be replayed against another kind or scope. The plaintext leaves
+ * once, from `issue`; nothing here logs it or stores it.
+ */
+export declare class LambderOneShotSecrets<TKinds extends Record<string, LambderOneShotSecretKind>> {
+    private readonly store;
+    private readonly secret;
+    private readonly kinds;
+    private readonly now;
+    constructor(options: LambderOneShotSecretsOptions<TKinds>);
+    private nowSeconds;
+    private kindOf;
+    /**
+     * The digest a secret rests as. A code's carries its kind and scope, so
+     * the same code issued to two scopes never collides and a code cannot be
+     * replayed against another; a token's carries its kind, since a token is
+     * found by its digest alone, so two scopes can draw the same one, and the
+     * store's claim on the digest at issue is what keeps them apart. The
+     * fields are joined escaped, so no two distinct field lists produce one
+     * string.
+     */
+    private digestOf;
+    /**
+     * Mints one secret for the scope, retiring whatever the scope held, and
+     * answers the plaintext: the one time it exists outside the caller's
+     * hands. With `cooldownSeconds`, a scope whose current secret was issued
+     * less than that ago is refused instead, with the second it may ask
+     * again; of two callers racing past the cooldown, exactly one is issued.
+     * `meta` is what the app wants back at redemption: an identity, an
+     * issuing organization, as small strings.
+     *
+     * A secret whose digest another scope holds is drawn again, up to
+     * MAX_DRAWS times; past that the kind's alphabet and length leave too few
+     * secrets for the ones out at once, and the issue throws.
+     */
+    issue(kind: keyof TKinds & string, scope: string, options?: {
+        cooldownSeconds?: number;
+        meta?: Record<string, string>;
+    }): Promise<LambderOneShotIssueResult>;
+    /**
+     * Redeems a code for its scope. The try is counted before the code is
+     * looked at, in the write that reads the digest, so tries sent together
+     * are all counted; a right code past the ceiling is refused as exhausted.
+     * An accepted code is spent in the same call, exactly once.
+     */
+    redeem(kind: LambderOneShotCodeKindNames<TKinds>, scope: string, candidate: string): Promise<LambderOneShotRedeemResult>;
+    /** Redeems a token by its value: found by its digest, spent exactly once. A token of another kind, or none, is "none". */
+    redeemToken(kind: LambderOneShotTokenKindNames<TKinds>, candidate: string): Promise<LambderOneShotRedeemResult>;
+    /** Ends whatever the scope holds: after the thing it proved is settled another way, or when what was sent never arrived. */
+    retire(scope: string): Promise<void>;
+    /** Spends the record; a redemption racing this one and winning makes it "none". */
+    private accept;
+}