lambder 8.1.1 → 8.3.1

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;
+}

package/dist/secrets/LambderOneShotSecrets.js

@@ -0,0 +1,217 @@
+import { keyedDigest, randomSecret } from "../shared/util/LambderSignedClaims.js";
+import { constantTimeEquals } from "../shared/util/LambderTextDigest.js";
+import { assertPositiveInteger } from "../shared/util/LambderOptionChecks.js";
+import { joinKeyFields } from "../shared/util/joinKeyFields.js";
+const DIGITS = "0123456789";
+/**
+ * How many secrets an issue draws before giving up on a digest another scope
+ * holds. A random token never meets one; a short code drawn from a small
+ * space with many out at once can, and five taken in a row means the space is
+ * too small for the codes out, which is a configuration to change rather than
+ * a draw to repeat.
+ */
+const MAX_DRAWS = 5;
+/**
+ * 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 class LambderOneShotSecrets {
+    store;
+    secret;
+    kinds;
+    now;
+    constructor(options) {
+        if (typeof options.secret !== "string" || options.secret.length === 0)
+            throw new Error("Lambder: LambderOneShotSecrets needs a secret to key its digests with.");
+        const names = Object.keys(options.kinds);
+        if (names.length === 0)
+            throw new Error("Lambder: LambderOneShotSecrets was given no kinds; declare the kinds of secret the app hands out.");
+        for (const name of names) {
+            const kind = options.kinds[name];
+            assertPositiveInteger(kind.ttlSeconds, `kinds.${name}.ttlSeconds`);
+            if (kind.shape === "code") {
+                assertPositiveInteger(kind.length, `kinds.${name}.length`);
+                assertPositiveInteger(kind.maxAttempts, `kinds.${name}.maxAttempts`);
+                assertAlphabet(kind.alphabet ?? DIGITS, name);
+            }
+            else if (kind.shape === "token") {
+                if (kind.alphabet !== undefined || kind.length !== undefined) {
+                    assertPositiveInteger(kind.length, `kinds.${name}.length`);
+                    assertAlphabet(kind.alphabet ?? "", name);
+                }
+                else {
+                    assertPositiveInteger(kind.bytes ?? 32, `kinds.${name}.bytes`);
+                }
+            }
+            else {
+                throw new Error(`Lambder: kinds.${name}.shape must be "code" or "token", got ${JSON.stringify(kind.shape)}.`);
+            }
+        }
+        this.store = options.store;
+        this.secret = options.secret;
+        this.kinds = options.kinds;
+        this.now = options.now ?? (() => Date.now());
+    }
+    nowSeconds() { return Math.floor(this.now() / 1000); }
+    kindOf(name) {
+        const kind = Object.prototype.hasOwnProperty.call(this.kinds, name) ? this.kinds[name] : undefined;
+        if (!kind)
+            throw new Error(`Lambder: LambderOneShotSecrets knows no kind "${name}".`);
+        return kind;
+    }
+    /**
+     * 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.
+     */
+    digestOf(kind, scope, plaintext) {
+        return keyedDigest(this.secret, scope === null ? joinKeyFields("token", kind, plaintext) : joinKeyFields("code", kind, scope, plaintext));
+    }
+    /**
+     * 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.
+     */
+    async issue(kind, scope, options = {}) {
+        const definition = this.kindOf(kind);
+        const cooldown = options.cooldownSeconds === undefined ? undefined : assertPositiveInteger(options.cooldownSeconds, "cooldownSeconds");
+        const nowSeconds = this.nowSeconds();
+        for (let draw = 0; draw < MAX_DRAWS; draw += 1) {
+            const plaintext = definition.shape === "code" ? drawCode(definition.alphabet ?? DIGITS, definition.length)
+                : definition.alphabet !== undefined ? drawCode(definition.alphabet, definition.length)
+                    : randomSecret(definition.bytes ?? 32);
+            const draft = {
+                kind,
+                scope,
+                shape: definition.shape,
+                digest: await this.digestOf(kind, definition.shape === "code" ? scope : null, plaintext),
+                issuedAt: nowSeconds,
+                expiresAt: nowSeconds + definition.ttlSeconds,
+                meta: { ...(options.meta ?? {}) },
+            };
+            const outcome = await this.store.issue(draft, { unlessIssuedAfter: cooldown === undefined ? undefined : nowSeconds - cooldown });
+            if (outcome.issued)
+                return { issued: true, plaintext, expiresAt: draft.expiresAt };
+            if (outcome.refused === "cooldown")
+                return { issued: false, refused: "cooldown", retryAt: outcome.issuedAt + (cooldown ?? 0) };
+        }
+        throw new Error(`Lambder: kind "${kind}" drew ${MAX_DRAWS} secrets in a row whose digest another scope holds; its alphabet and length leave too few for the ones out at once.`);
+    }
+    /**
+     * 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.
+     */
+    async redeem(kind, scope, candidate) {
+        const definition = this.kindOf(kind);
+        if (definition.shape !== "code")
+            throw new Error(`Lambder: kind "${kind}" is a token, redeemed by value with redeemToken().`);
+        const current = await this.store.findByScope(scope);
+        if (!current || current.kind !== kind)
+            return { state: "none" };
+        if (current.expiresAt <= this.nowSeconds())
+            return { state: "expired" };
+        if (current.attempts >= definition.maxAttempts)
+            return { state: "exhausted" };
+        const counted = await this.store.attempt(scope, current.id);
+        if (!counted)
+            return { state: "none" };
+        // Counted already, so this is the count with the try being made now.
+        if (counted.attempts > definition.maxAttempts)
+            return { state: "exhausted" };
+        if (!constantTimeEquals(counted.digest, await this.digestOf(kind, scope, candidate))) {
+            return { state: "wrong", attemptsLeft: Math.max(0, definition.maxAttempts - counted.attempts) };
+        }
+        return await this.accept(counted);
+    }
+    /** Redeems a token by its value: found by its digest, spent exactly once. A token of another kind, or none, is "none". */
+    async redeemToken(kind, candidate) {
+        const definition = this.kindOf(kind);
+        if (definition.shape !== "token")
+            throw new Error(`Lambder: kind "${kind}" is a code, redeemed with its scope through redeem().`);
+        // A token is 43 characters for 32 bytes; anything far past that is not one, and is not worth a digest.
+        if (candidate.length === 0 || candidate.length > 512)
+            return { state: "none" };
+        const current = await this.store.findByDigest(await this.digestOf(kind, null, candidate));
+        if (!current || current.kind !== kind)
+            return { state: "none" };
+        if (current.expiresAt <= this.nowSeconds())
+            return { state: "expired" };
+        return await this.accept(current);
+    }
+    /** Ends whatever the scope holds: after the thing it proved is settled another way, or when what was sent never arrived. */
+    async retire(scope) {
+        await this.store.retire(scope);
+    }
+    /** Spends the record; a redemption racing this one and winning makes it "none". */
+    async accept(record) {
+        if (!(await this.store.consume(record.scope, record.id)))
+            return { state: "none" };
+        return { state: "accepted", scope: record.scope, meta: { ...record.meta }, issuedAt: record.issuedAt };
+    }
+}
+const assertAlphabet = (alphabet, name) => {
+    if (alphabet.length < 2 || alphabet.length > 256 || new Set(alphabet).size !== alphabet.length) {
+        throw new Error(`Lambder: kinds.${name}.alphabet must be 2 to 256 distinct characters.`);
+    }
+};
+/**
+ * A code of `length` characters drawn uniformly from `alphabet`. Bytes at or
+ * above the largest multiple of the alphabet's size are discarded, so the
+ * modulo cannot favour the alphabet's first characters.
+ */
+const drawCode = (alphabet, length) => {
+    const webCrypto = globalThis.crypto;
+    if (typeof webCrypto?.getRandomValues !== "function") {
+        throw new Error("Lambder needs crypto.getRandomValues in this runtime to draw a code. Every browser provides it; Node 20+ provides it as globalThis.crypto.");
+    }
+    const ceiling = Math.floor(256 / alphabet.length) * alphabet.length;
+    const characters = [];
+    const buffer = new Uint8Array(length * 2);
+    while (characters.length < length) {
+        webCrypto.getRandomValues(buffer);
+        for (const byte of buffer) {
+            if (byte >= ceiling)
+                continue;
+            characters.push(alphabet[byte % alphabet.length]);
+            if (characters.length === length)
+                break;
+        }
+    }
+    return characters.join("");
+};

package/dist/session/LambderSessionCrypto.js

@@ -11,16 +11,7 @@
  * not a table anybody can leak, so hashing there protects nothing.
  */
 import { getCrypto } from "../shared/util/LambderNodeModules.js";
-import { bytesToHexString, resolveWebCrypto, sha256HexOf } from "../shared/util/LambderTextDigest.js";
-/** Length-aware, timing-neutral string comparison: no early exit on the first differing character. */
-const constantTimeEqual = (a, b) => {
-    if (a.length !== b.length)
-        return false;
-    let difference = 0;
-    for (let i = 0; i < a.length; i += 1)
-        difference |= a.charCodeAt(i) ^ b.charCodeAt(i);
-    return difference === 0;
-};
+import { bytesToHexString, constantTimeEquals, hmacSha256Of, resolveWebCrypto, sha256HexOf } from "../shared/util/LambderTextDigest.js";
 /** True when this runtime offers WebCrypto's subtle API (secure contexts in browsers; Node 20+). */
 export const isWebCryptoAvailable = () => typeof globalThis.crypto?.subtle?.digest === "function" && typeof globalThis.crypto.getRandomValues === "function";
 /** sha256 and HMAC through crypto.subtle and randomness through getRandomValues: the default. */
@@ -62,10 +53,9 @@ export class LambderWebCrypto {
         return await sha256HexOf(value);
     }
     async hmacSha256Hex(key, value) {
-        const webCrypto = await this.ready();
-        const encoder = new TextEncoder();
-        const hmacKey = await webCrypto.subtle.importKey("raw", encoder.encode(key), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
-        return bytesToHexString(new Uint8Array(await webCrypto.subtle.sign("HMAC", hmacKey, encoder.encode(value))));
+        // ready() first, as for sha256Hex; the HMAC is the one every layer shares.
+        await this.ready();
+        return bytesToHexString(await hmacSha256Of(key, value));
     }
     async randomHex(bytes) {
         const webCrypto = await this.ready();
@@ -82,7 +72,7 @@ export class LambderWebCrypto {
             if (left.length === right.length)
                 return nodeCrypto.timingSafeEqual(left, right);
         }
-        return constantTimeEqual(a, b);
+        return constantTimeEquals(a, b);
     }
 }
 /**
@@ -110,6 +100,6 @@ export class LambderPlainSessionCrypto {
         return bytesToHexString(random);
     }
     constantTimeEqual(a, b) {
-        return constantTimeEqual(a, b);
+        return constantTimeEquals(a, b);
     }
 }

package/dist/shared/contracts/LambderIdempotencyStore.d.ts

@@ -38,8 +38,9 @@ export type LambderIdempotencyBeginResult = {
  * atomically, settled by the claim's owner. LambderDdbIdempotencyStore and
  * LambderMemoryIdempotencyStore implement it; an app may bring its own.
  *
- * tests/store-conformance asserts the rules against every implementation.
- * Four are easy to get wrong:
+ * The conformance suite `lambder/testing` exports
+ * (lambderIdempotencyStoreConformance) asserts the rules, against these two
+ * and against an app's own. Four are easy to get wrong:
  *
  * A read hands back a COPY of the record, never the stored object, because a
  * caller applies its own headers onto what it gets back.