lambder 8.1.2 → 8.3.1

package/dist/build/writeApiOptions.js

@@ -0,0 +1,102 @@
+import { existsSync, readFileSync } from "fs";
+import { resolve } from "path";
+import { headerLinesOf, loadApiOptionEntries, nameChangesOf, readGeneratedTable, settleGeneratedFile, tableStatementLines, } from "./generatedTables.js";
+/*
+ * The declared options of an app's APIs as a generated module of plain data:
+ * every API's mode and its guards, rateLimit and idempotency options as
+ * written, every rate-limit policy less its key handler, and every guard's
+ * input mode, session flag and place in the call. The contract already
+ * carries the options as types; this is the same fact as a value, for the
+ * code that decides something at runtime with it: a mock restating the
+ * server's declarations, a test walking the public surface. Neither imports
+ * the server for it. The file names every endpoint, so a production bundle
+ * imports none of it: a screen that gates on a guard reads that guard's
+ * parameters alone (writeApiGuardParams).
+ *
+ * Plain data by construction: the instance refuses to report a guard
+ * parameter that is code or a class instance (see Lambder.apiOptionEntries),
+ * a policy's key handler is reduced to `per: "custom"`, and a guard's schema
+ * to its input mode. No secret can reach the file, because nothing that could
+ * hold one is written.
+ */
+const DEFAULT_HEADER = [
+    "Generated by writeApiOptions() from lambder/build. Do not edit.",
+    "",
+    "Every API the server registers with its declared options, every rate-limit",
+    "policy less its key handler, and every guard's input mode: the server's",
+    "declarations as plain data, for the code that decides something with them",
+    "without importing the server.",
+].join("\n");
+/** The three tables the module exports, in the order they are written. */
+const TABLES = [
+    { name: "apiOptions", key: "apis", type: "LambderApiOptionEntry", doc: "Every API the server registers: its mode and its guards, rateLimit and idempotency options as written." },
+    { name: "rateLimitPolicies", key: "rateLimitPolicies", type: "LambderRateLimitPolicyEntry", doc: "Every rate-limit policy the server declares, its key reduced to what it counts: an address, a session, or a key the app derives (\"custom\")." },
+    { name: "guardDeclarations", key: "guards", type: "LambderGuardDeclarationEntry", doc: "Every guard the server declares: how it is fed, whether it needs a session, and when it runs." },
+];
+/** The tables a generated file holds, read back as data, or null for a file that does not hold all three as written (never written, or rewritten by hand). */
+export const readOptionTables = (contents) => {
+    const tables = {};
+    for (const table of TABLES) {
+        const read = readGeneratedTable(contents, table.name);
+        if (!read)
+            return null;
+        tables[table.key] = read;
+    }
+    return tables;
+};
+const renderOptionsFile = (entries, options) => {
+    const semicolon = options.semicolons === false ? "" : ";";
+    return [
+        ...headerLinesOf(options.header ?? DEFAULT_HEADER),
+        `import type { ${TABLES.map((table) => table.type).join(", ")} } from "lambder/client"${semicolon}`,
+        ...TABLES.flatMap((table) => [
+            "",
+            ...tableStatementLines({ name: table.name, doc: table.doc, value: entries[table.key], satisfies: `Record<string, ${table.type}>`, semicolon }),
+        ]),
+        "",
+    ].join("\n");
+};
+/**
+ * Writes the declared options of an app's APIs as a module of plain data, or
+ * checks the one on disk, and says which APIs, policies and guards moved.
+ *
+ * Call it from a generator script beside writeApiSignatures, naming the
+ * module that exports the app's instance:
+ *
+ * ```ts
+ * import { writeApiOptions } from "lambder/build";
+ *
+ * const result = await writeApiOptions({
+ *     module: "server/src/index.ts",   // export const lambder = initLambder()...
+ *     exportName: "lambder",
+ *     file: "shared/generated/apiOptions.generated.ts",
+ *     check: process.argv.includes("--check"),
+ * });
+ * console.log(result.lines.join("\n"));
+ * process.exit(result.ok ? 0 : 1);
+ * ```
+ *
+ * The tables are compared as the data the file holds, so a checkout that
+ * rewrote its line endings or a formatter that re-indented it is neither
+ * stale nor rewritten, and a file whose data is current is left as it is.
+ * There is no fresh-process check: nothing here is digested, so nothing can
+ * differ per process. A module that does not load, an export that is not an
+ * instance, or a guard parameter that is not plain data throws.
+ */
+export const writeApiOptions = async (options) => {
+    const file = resolve(options.file);
+    const entries = await loadApiOptionEntries(options, "writeApiOptions");
+    const previousText = existsSync(file) ? readFileSync(file, "utf8") : null;
+    const previous = previousText === null ? null : readOptionTables(previousText);
+    const changes = Object.fromEntries(TABLES.map((table) => [table.key, nameChangesOf(entries[table.key], previous?.[table.key] ?? {})]));
+    const counts = Object.fromEntries(TABLES.map((table) => [table.key, Object.keys(entries[table.key]).length]));
+    const settled = settleGeneratedFile({
+        name: options.file, file, check: options.check, previousText, readBack: previous !== null,
+        tables: TABLES.map((table) => ({ name: table.name, count: counts[table.key], changes: changes[table.key] })),
+        held: `${counts.apis} APIs, ${counts.rateLimitPolicies} policies, ${counts.guards} guards`,
+        tablesNoun: "the three tables",
+        unmovedLine: "no options changed",
+        render: () => renderOptionsFile(entries, options),
+    });
+    return { ...settled, file, counts, changes };
+};

package/dist/build.d.ts

@@ -2,13 +2,19 @@
  * Build entry point (`import ... from "lambder/build"`).
  *
  * What a generator script runs at build time to write the files a deployment
- * ships: the signature file both sides read, from the app's own instance, and
- * the contract a client compiles against, from the server's sources. Node-only
- * and imported by nothing else in the package, so no deployment or bundle
- * carries it.
+ * ships: the signature file both sides read, the declared options as plain
+ * data, and one guard's parameters as the least a browser needs of them, all
+ * from the app's own instance; and the contract a client compiles against,
+ * from the server's sources. Node-only and imported by nothing else
+ * in the package, so no deployment or bundle carries it.
  */
 export { writeApiSignatures } from "./build/writeApiSignatures.js";
 export type { LambderApiSignatureSource, LambderApiSignatureFileOptions, LambderApiSignatureFileResult, } from "./build/writeApiSignatures.js";
 export { writeApiContract } from "./build/writeApiContract.js";
 export type { LambderApiContractFileOptions, LambderApiContractFileResult, } from "./build/writeApiContract.js";
+export { writeApiOptions } from "./build/writeApiOptions.js";
+export type { LambderApiOptionsFileOptions, LambderApiOptionsFileResult, } from "./build/writeApiOptions.js";
+export { writeApiGuardParams } from "./build/writeApiGuardParams.js";
+export type { LambderApiGuardParamsFileOptions, LambderApiGuardParamsFileResult, } from "./build/writeApiGuardParams.js";
+export type { LambderApiOptionsSource, LambderNameChanges } from "./build/generatedTables.js";
 export type { LambderModuleLocation } from "./build/moduleLocation.js";

package/dist/build.js

@@ -2,10 +2,13 @@
  * Build entry point (`import ... from "lambder/build"`).
  *
  * What a generator script runs at build time to write the files a deployment
- * ships: the signature file both sides read, from the app's own instance, and
- * the contract a client compiles against, from the server's sources. Node-only
- * and imported by nothing else in the package, so no deployment or bundle
- * carries it.
+ * ships: the signature file both sides read, the declared options as plain
+ * data, and one guard's parameters as the least a browser needs of them, all
+ * from the app's own instance; and the contract a client compiles against,
+ * from the server's sources. Node-only and imported by nothing else
+ * in the package, so no deployment or bundle carries it.
  */
 export { writeApiSignatures } from "./build/writeApiSignatures.js";
 export { writeApiContract } from "./build/writeApiContract.js";
+export { writeApiOptions } from "./build/writeApiOptions.js";
+export { writeApiGuardParams } from "./build/writeApiGuardParams.js";

package/dist/client/LambderUploadRunner.d.ts

@@ -48,10 +48,11 @@ export type LambderUploadRunnerOptions<Reference, Receipt> = {
     /**
      * How storage is tried again when it cannot be reached, stalls, or answers
      * a failure a retry can cure (a 5xx, RequestTimeout, SlowDown). Each wait
-     * is a random time between `baseDelayMs` and a ceiling of twice that,
-     * doubling with every failed attempt and never past `maxDelayMs`, so many
-     * browsers dropped together do not come back in step, not even the first
-     * time. Default: 4 attempts, waits from one second to 15.
+     * is `baseDelayMs` plus a random share of a ceiling that starts at
+     * `baseDelayMs` and doubles with every failed attempt, the whole never
+     * past `maxDelayMs` (the ladder of LambderBackoffTimer), so many browsers
+     * dropped together do not come back in step, not even the first time.
+     * Default: 4 attempts, waits from one second to 15.
      */
     storageRetry?: {
         attempts?: number;
@@ -69,8 +70,8 @@ export type LambderUploadRunnerOptions<Reference, Receipt> = {
 export declare class LambderUploadRunner<Reference, Receipt> {
     private readonly options;
     private readonly attempts;
-    private readonly baseDelayMs;
-    private readonly maxDelayMs;
+    /** The ladder one upload's waits climb; each upload() builds a timer of its own from it, so two uploads never share a count. */
+    private readonly backoff;
     private readonly stallTimeoutMs;
     constructor(options: LambderUploadRunnerOptions<Reference, Receipt>);
     /** For a file input's `accept`, so the picker only offers what the rule takes. */
@@ -90,7 +91,6 @@ export declare class LambderUploadRunner<Reference, Receipt> {
     }): Promise<Receipt>;
     /** Forgets a confirmed upload through the app's endpoint, when it declared one. */
     discard(receipt: Receipt): Promise<void>;
-    private waitBeforeRetry;
     /** One post of the file to storage. Never throws: every ending is an outcome. */
     private post;
 }

package/dist/client/LambderUploadRunner.js

@@ -1,4 +1,5 @@
 import { checkUploadRule, } from "../shared/contracts/LambderUploadBucket.js";
+import { LambderBackoffTimer } from "../shared/util/LambderBackoffTimer.js";
 import { sha256Base64Of } from "../shared/util/LambderTextDigest.js";
 /** How an upload failed: `reason` for a screen to word, the underlying error as `cause`. */
 export class LambderUploadError extends Error {
@@ -21,14 +22,16 @@ const TRANSIENT_STORAGE_CODES = new Set(["RequestTimeout", "SlowDown", "Internal
 export class LambderUploadRunner {
     options;
     attempts;
-    baseDelayMs;
-    maxDelayMs;
+    /** The ladder one upload's waits climb; each upload() builds a timer of its own from it, so two uploads never share a count. */
+    backoff;
     stallTimeoutMs;
     constructor(options) {
         this.options = options;
         this.attempts = Math.max(1, options.storageRetry?.attempts ?? 4);
-        this.baseDelayMs = options.storageRetry?.baseDelayMs ?? 1_000;
-        this.maxDelayMs = options.storageRetry?.maxDelayMs ?? 15_000;
+        const baseDelayMs = options.storageRetry?.baseDelayMs ?? 1_000;
+        const maxDelayMs = options.storageRetry?.maxDelayMs ?? 15_000;
+        // A longest wait below the shortest is every wait at the shortest.
+        this.backoff = { baseMs: baseDelayMs, maxMs: Math.max(baseDelayMs, maxDelayMs) };
         this.stallTimeoutMs = options.stallTimeoutMs ?? 60_000;
     }
     /** For a file input's `accept`, so the picker only offers what the rule takes. */
@@ -81,6 +84,7 @@ export class LambderUploadRunner {
             }
         };
         let issued = await requestTicket();
+        const backoff = new LambderBackoffTimer(this.backoff);
         let failedAttempts = 0;
         let ticketRenewals = 0;
         for (;;) {
@@ -103,7 +107,10 @@ export class LambderUploadRunner {
             // connection does not leave the app a record per attempt.
             if (++failedAttempts >= this.attempts)
                 throw new LambderUploadError("networkFailed");
-            await this.waitBeforeRetry(failedAttempts, signal);
+            // The wait rejects only for the signal: nothing else cancels it.
+            await backoff.wait(signal).catch((cause) => {
+                throw new LambderUploadError("cancelled", { cause });
+            });
         }
         report("confirming", file.size);
         try {
@@ -117,22 +124,6 @@ export class LambderUploadRunner {
     async discard(receipt) {
         await this.options.discardUpload?.(receipt);
     }
-    waitBeforeRetry(failedAttempts, signal) {
-        const ceiling = Math.max(this.baseDelayMs, Math.min(this.baseDelayMs * 2 ** failedAttempts, this.maxDelayMs));
-        return new Promise((resolve, reject) => {
-            if (signal?.aborted)
-                return reject(new LambderUploadError("cancelled"));
-            const cancel = () => {
-                clearTimeout(timer);
-                reject(new LambderUploadError("cancelled"));
-            };
-            const timer = setTimeout(() => {
-                signal?.removeEventListener("abort", cancel);
-                resolve();
-            }, this.baseDelayMs + Math.random() * (ceiling - this.baseDelayMs));
-            signal?.addEventListener("abort", cancel, { once: true });
-        });
-    }
     /** One post of the file to storage. Never throws: every ending is an outcome. */
     post(ticket, file, signal, onSent) {
         if (signal?.aborted)

package/dist/client.d.ts

@@ -26,6 +26,8 @@ export type { LambderIdempotencyKeyScope } from "./shared/wire/LambderIdempotenc
 export { LambderApiRefusal, isLambderApiRefusal, refuse, refusalMessageOf, LAMBDER_REFUSAL_CODES } from "./shared/wire/LambderApiRefusal.js";
 export type { LambderApiRefusalOptions, LambderRefusalMessage, LambderAppRefusalMessage, LambderRefusalCode, LambderRefuseOptions } from "./shared/wire/LambderApiRefusal.js";
 export type { LambderApiContractShape, LambderApiMode, LambderApiEnvelopeBody, LambderApiResponseConfig, LambderGuardNamesIn, LambderContractMode, LambderContractKeysWithMode, LambderContractKeysWithGuard, LambderJsonOf, LambderJsonOutputOf, LambderContractGuardsOf, LambderContractGuardNames, LambderContractGuardInputsOf, LambderContractGuardInput, LambderContractGuardInputNames, LambderContractRateLimitOf, LambderContractRateLimitNames, LambderContractIdempotencyOf, } from "./shared/wire/LambderApiContract.js";
+export { apiGuardParam } from "./shared/wire/LambderApiOptionEntries.js";
+export type { LambderApiOptionEntries, LambderApiOptionEntry, LambderRateLimitPolicyEntry, LambderGuardDeclarationEntry, LambderApisWithGuard, LambderApisGuardedBy, LambderApisWithMode, LambderGuardParamOf, } from "./shared/wire/LambderApiOptionEntries.js";
 export { describeCrash, errorFromCrashDetail } from "./shared/wire/LambderCrashDetail.js";
 export type { LambderCrashDetail, LambderCrashCause } from "./shared/wire/LambderCrashDetail.js";
 export { compressPayloadGzip, isRequestCompressionAvailable, COMPRESSED_PAYLOAD_GZ_FIELD, COMPRESSED_PAYLOAD_BR_FIELD, COMPRESSED_PAYLOAD_BYTES_FIELD, DEFAULT_REQUEST_COMPRESSION_SETTINGS, } from "./shared/wire/LambderRequestPayload.js";
@@ -36,6 +38,11 @@ export { html, xml, raw, jsonScript, escapeHtml, renderHtmlValue, LambderSafeHtm
 export { createLambderI18n } from "./shared/LambderI18n.js";
 export type { LambderLanguageMeta, LambderI18nConfig, LambderI18nInstance, LambderI18nTranslator, LambderI18nExtractParams, LambderI18nDictionaryLoader, LambderI18nCodes, LambderI18nKeys, LambderI18nTranslatorFor, } from "./shared/LambderI18n.js";
 export type { LambderHttpStatusCode } from "./shared/wire/LambderHttpStatus.js";
+export { LambderBackoffTimer } from "./shared/util/LambderBackoffTimer.js";
+export type { LambderBackoffTimerOptions } from "./shared/util/LambderBackoffTimer.js";
+export { LambderSignedClaims, keyedDigest, randomSecret } from "./shared/util/LambderSignedClaims.js";
+export type { LambderSignedClaimsOptions } from "./shared/util/LambderSignedClaims.js";
+export { constantTimeEquals } from "./shared/util/LambderTextDigest.js";
 export { LambderUploadRunner, LambderUploadError } from "./client/LambderUploadRunner.js";
 export type { LambderUploadRunnerOptions, LambderUploadProgress, LambderUploadPhase, LambderUploadFailureReason } from "./client/LambderUploadRunner.js";
 export { checkUploadRule } from "./shared/contracts/LambderUploadBucket.js";

package/dist/client.js

@@ -23,6 +23,9 @@ export { createIdempotencyKey, createIdempotencyKeyScope } from "./shared/wire/L
 // Typed API refusals (isomorphic: shared code may throw them from anywhere;
 // in the browser they are plain Errors).
 export { LambderApiRefusal, isLambderApiRefusal, refuse, refusalMessageOf, LAMBDER_REFUSAL_CODES } from "./shared/wire/LambderApiRefusal.js";
+// The server's declared options as plain data (the generated options module's
+// entry types) and the readers a client derives its own facts from.
+export { apiGuardParam } from "./shared/wire/LambderApiOptionEntries.js";
 // A crash described for a caller allowed to see it (the envelope's `crash` field; pure, no Node built-ins).
 export { describeCrash, errorFromCrashDetail } from "./shared/wire/LambderCrashDetail.js";
 // Request payload compression (browser-safe: gzip via CompressionStream, no Node built-ins).
@@ -33,6 +36,14 @@ export { resolveCompressionOption } from "./shared/wire/LambderCompressionOption
 export { html, xml, raw, jsonScript, escapeHtml, renderHtmlValue, LambderSafeHtml } from "./shared/LambderHtml.js";
 // Typed translations (standalone, isomorphic)
 export { createLambderI18n } from "./shared/LambderI18n.js";
+// Waiting longer after each failure, once: for a reconnecting client or a
+// screen that has to come back by itself.
+export { LambderBackoffTimer } from "./shared/util/LambderBackoffTimer.js";
+// Signed claims tokens, for the isomorphic code that verifies them where a
+// server's secret is at hand (an edge Worker, a shared backend package);
+// never in a page, which holds no secret to verify with.
+export { LambderSignedClaims, keyedDigest, randomSecret } from "./shared/util/LambderSignedClaims.js";
+export { constantTimeEquals } from "./shared/util/LambderTextDigest.js";
 // Direct uploads: the runner that takes a file from the browser straight to
 // storage, and the vocabulary it shares with the server's bucket.
 export { LambderUploadRunner, LambderUploadError } from "./client/LambderUploadRunner.js";

package/dist/core/Lambder.d.ts

@@ -14,6 +14,7 @@ import type { LambderFileSource } from "../shared/contracts/LambderFileSource.js
 import { LAMBDER_BACKEND_SWAP, LAMBDER_CRASH_WATCH } from "../shared/util/LambderTestingDoors.js";
 import { type LambderApiSignatureEntry } from "../api/LambderApiSignature.js";
 import { type LambderApiSignatureMap } from "../shared/wire/LambderApiSignature.js";
+import type { LambderApiOptionEntries } from "../shared/wire/LambderApiOptionEntries.js";
 import type { LambderApiIdempotencyOption } from "../shared/wire/LambderApiOptionValues.js";
 import type { LambderApiGuard, LambderGuardMetaMap, LambderGuardsOption, LambderGuardDataOf, LambderGuardInputsOf } from "../api/LambderApiGuards.js";
 import type { LambderApiRateLimitPolicyConfig, LambderRateLimitOption } from "../api/LambderApiRateLimits.js";
@@ -91,6 +92,8 @@ export default class Lambder<TSessionData = any, _TContract extends Record<strin
     private readonly apiDefinitions;
     /** The guards map given at creation, kept for apiSignatures(): a guard's schema is part of the signature of every endpoint declaring it. */
     private readonly guards;
+    /** The rate-limit policies given at creation, kept for apiOptionEntries(), which records each one less its key handler. */
+    private readonly rateLimitPolicies;
     private hookList;
     private createdHooks;
     private initPromise;
@@ -246,6 +249,24 @@ export default class Lambder<TSessionData = any, _TContract extends Record<strin
      * unless the generator writes it there.
      */
     apiSignatureEntries(): Promise<LambderApiSignatureEntry[]>;
+    /**
+     * Every registered API's mode and declared options as plain data, with
+     * the rate-limit policies and guards they name reduced to what is not
+     * code: what writeApiOptions (lambder/build) writes to a module a client,
+     * a mock or a test imports instead of the server. The contract carries
+     * the same options as types; this is the same fact as a value, for code
+     * that decides something at runtime with it.
+     *
+     * Nothing here is a secret or a handler by construction. A guard's
+     * parameter is written as it was declared, so it has to be plain data
+     * (a permission string, a list, a reason); one that is not fails by API
+     * and guard name. A policy's key handler is never written: its `per`
+     * says "custom" and no more. A guard's input schema is never written
+     * either; its declaration says only which of the three input modes it
+     * has. Every table is sorted by name, so the module diffs by endpoint
+     * and never moves when registrations are reordered.
+     */
+    apiOptionEntries(): LambderApiOptionEntries;
     getResponseBuilder(ctx?: LambderRenderContext): LambderResponseBuilder<any>;
     private getResolver;
     getHandler(): LambderHandler;

package/dist/core/Lambder.js

@@ -15,6 +15,7 @@ import { LambderApiPipeline } from "../api/LambderApiPipeline.js";
 import { LAMBDER_BACKEND_SWAP, LAMBDER_CRASH_WATCH } from "../shared/util/LambderTestingDoors.js";
 import { apiSignatureOf } from "../api/LambderApiSignature.js";
 import { apiNameKeyOf } from "../shared/wire/LambderApiSignature.js";
+import { assertPlainData } from "../shared/util/assertPlainData.js";
 import { apiNotFoundAnswer, refusalAnswer, sessionExpiredAnswer, } from "../api/LambderApiEnvelope.js";
 import { bindContextTools, createContext, isV2HttpEvent, } from "./LambderContext.js";
 import { COMPRESSED_PAYLOAD_GZ_FIELD, COMPRESSED_PAYLOAD_BR_FIELD, COMPRESSED_PAYLOAD_BYTES_FIELD } from "../shared/wire/LambderRequestPayload.js";
@@ -80,6 +81,8 @@ export default class Lambder {
     apiDefinitions = new Map();
     /** The guards map given at creation, kept for apiSignatures(): a guard's schema is part of the signature of every endpoint declaring it. */
     guards;
+    /** The rate-limit policies given at creation, kept for apiOptionEntries(), which records each one less its key handler. */
+    rateLimitPolicies;
     hookList = { "beforeRender": [], "afterRender": [], "fallback": [] };
     createdHooks = [];
     initPromise = null;
@@ -122,6 +125,7 @@ export default class Lambder {
         }
         const session = options.session;
         this.guards = options.guards;
+        this.rateLimitPolicies = options.rateLimits?.policies;
         this.pipeline = new LambderApiPipeline({
             apiVersion: this.apiVersion,
             minApiVersion: options.minApiVersion,
@@ -413,6 +417,71 @@ export default class Lambder {
         entries.sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
         return entries;
     }
+    /**
+     * Every registered API's mode and declared options as plain data, with
+     * the rate-limit policies and guards they name reduced to what is not
+     * code: what writeApiOptions (lambder/build) writes to a module a client,
+     * a mock or a test imports instead of the server. The contract carries
+     * the same options as types; this is the same fact as a value, for code
+     * that decides something at runtime with it.
+     *
+     * Nothing here is a secret or a handler by construction. A guard's
+     * parameter is written as it was declared, so it has to be plain data
+     * (a permission string, a list, a reason); one that is not fails by API
+     * and guard name. A policy's key handler is never written: its `per`
+     * says "custom" and no more. A guard's input schema is never written
+     * either; its declaration says only which of the three input modes it
+     * has. Every table is sorted by name, so the module diffs by endpoint
+     * and never moves when registrations are reordered.
+     */
+    apiOptionEntries() {
+        const apis = {};
+        for (const name of [...this.apiDefinitions.keys()].sort()) {
+            const { mode, guards, rateLimit, idempotency } = this.apiDefinitions.get(name);
+            const entry = { mode };
+            if (guards !== undefined) {
+                assertPlainData(guards, `the guards option of API "${name}"`);
+                entry.guards = guards;
+            }
+            if (rateLimit !== undefined) {
+                assertPlainData(rateLimit, `the rateLimit option of API "${name}"`);
+                entry.rateLimit = rateLimit;
+            }
+            if (idempotency !== undefined)
+                entry.idempotency = idempotency;
+            apis[name] = entry;
+        }
+        const rateLimitPolicies = {};
+        for (const name of Object.keys(this.rateLimitPolicies ?? {}).sort()) {
+            const { per, budget, chargeAt, errorMessage, ...windows } = this.rateLimitPolicies[name];
+            const entry = {};
+            for (const [window, limit] of Object.entries(windows)) {
+                if (limit !== undefined)
+                    entry[window] = limit;
+            }
+            if (per !== undefined)
+                entry.per = per === "ip" || per === "session" ? per : "custom";
+            if (budget !== undefined)
+                entry.budget = budget;
+            if (chargeAt !== undefined)
+                entry.chargeAt = chargeAt;
+            if (errorMessage !== undefined) {
+                assertPlainData(errorMessage, `the errorMessage of rate-limit policy "${name}"`);
+                entry.errorMessage = errorMessage;
+            }
+            rateLimitPolicies[name] = entry;
+        }
+        const guards = {};
+        for (const name of Object.keys(this.guards ?? {}).sort()) {
+            const guard = this.guards[name];
+            guards[name] = {
+                input: guard.apiInput ? "apiInput" : guard.guardInput ? "guardInput" : "none",
+                session: guard.session === true,
+                runAt: guard.runAt ?? "beforeInputValidation",
+            };
+        }
+        return { apis, rateLimitPolicies, guards };
+    }
     getResponseBuilder(ctx) {
         return new LambderResponseBuilder({
             files: this.files,

package/dist/index.d.ts

@@ -12,6 +12,11 @@ export { lambderCookieJarTransport } from "./shared/transport/lambderCookieJarTr
 export type { LambderApiTransport, LambderApiTransportRequest, LambderTransportFailureReason } from "./shared/transport/LambderApiTransport.js";
 export { LambderCookieJar, parseSetCookie } from "./shared/transport/LambderCookieJar.js";
 export { LambderExpiringMap, LambderExpiringMapFullError } from "./shared/util/LambderExpiringMap.js";
+export { LambderBackoffTimer } from "./shared/util/LambderBackoffTimer.js";
+export type { LambderBackoffTimerOptions } from "./shared/util/LambderBackoffTimer.js";
+export { LambderSignedClaims, keyedDigest, randomSecret } from "./shared/util/LambderSignedClaims.js";
+export type { LambderSignedClaimsOptions } from "./shared/util/LambderSignedClaims.js";
+export { constantTimeEquals } from "./shared/util/LambderTextDigest.js";
 export type { LambderStoredCookie } from "./shared/transport/LambderCookieJar.js";
 export { lambderHandlerTransport } from "./invoke/lambderHandlerTransport.js";
 export type { LambderHandlerTransportOptions } from "./invoke/lambderHandlerTransport.js";
@@ -106,6 +111,12 @@ export type { LambderRateLimiter, LambderRateLimitWindow, LambderRateLimitPolicy
 export { LambderDdbRateLimiter } from "./stores/LambderDdbRateLimiter.js";
 export type { LambderDdbRateLimiterOptions } from "./stores/LambderDdbRateLimiter.js";
 export { LambderMemoryRateLimiter } from "./stores/LambderMemoryRateLimiter.js";
+export { LambderOneShotSecrets } from "./secrets/LambderOneShotSecrets.js";
+export type { LambderOneShotSecretKind, LambderOneShotSecretsOptions, LambderOneShotIssueResult, LambderOneShotRedeemResult, LambderOneShotCodeKindNames, LambderOneShotTokenKindNames, } from "./secrets/LambderOneShotSecrets.js";
+export type { LambderOneShotSecretStore, LambderOneShotSecretRecord, LambderOneShotSecretDraft, LambderOneShotSecretShape, LambderOneShotIssueOutcome, } from "./shared/contracts/LambderOneShotSecretStore.js";
+export { LambderDdbOneShotSecretStore } from "./stores/LambderDdbOneShotSecretStore.js";
+export type { LambderDdbOneShotSecretStoreOptions } from "./stores/LambderDdbOneShotSecretStore.js";
+export { LambderMemoryOneShotSecretStore } from "./stores/LambderMemoryOneShotSecretStore.js";
 export type { LambderIdempotencyStore, LambderIdempotencyBeginResult, LambderIdempotencyDoneRecord, } from "./shared/contracts/LambderIdempotencyStore.js";
 export { LambderDdbIdempotencyStore } from "./stores/LambderDdbIdempotencyStore.js";
 export type { LambderDdbIdempotencyStoreOptions } from "./stores/LambderDdbIdempotencyStore.js";
@@ -118,6 +129,8 @@ export type { LambderRateLimitKeyBuilder } from "./api/LambderApiRateLimits.js";
 export type { LambderContextRateLimit, LambderContextRateLimitCheck, LambderRateLimitCheckResult, LambderChargeablePolicyNames, LambderChargeKeyArgs, LambderRateLimitKeyFn, LambderRateLimitPer, LambderRateLimitBudget, LambderRateLimitChargeAt, LambderApiRateLimitPolicyConfig, LambderApiRateLimitsConfig, LambderAllowedPolicyNames, LambderRateLimitOption, } from "./api/LambderApiRateLimits.js";
 export type { LambderApiIdempotencyConfig } from "./api/LambderApiIdempotency.js";
 export type { LambderGuardsOptionValue, LambderRateLimitOverride, LambderRateLimitOptionValue, LambderApiIdempotencyOption, } from "./shared/wire/LambderApiOptionValues.js";
+export { apiGuardParam } from "./shared/wire/LambderApiOptionEntries.js";
+export type { LambderApiOptionEntries, LambderApiOptionEntry, LambderRateLimitPolicyEntry, LambderGuardDeclarationEntry, LambderApisWithGuard, LambderApisGuardedBy, LambderApisWithMode, LambderGuardParamOf, } from "./shared/wire/LambderApiOptionEntries.js";
 export { createLambderI18n } from "./shared/LambderI18n.js";
 export type { LambderLanguageMeta, LambderI18nConfig, LambderI18nInstance, LambderI18nTranslator, LambderI18nExtractParams, LambderI18nDictionaryLoader, LambderI18nCodes, LambderI18nKeys, LambderI18nTranslatorFor, } from "./shared/LambderI18n.js";
 export type { LambderApiContractShape, LambderApiMode, LambderApiEnvelopeBody, LambderApiResponseConfig, LambderApiNullAnswerConfig, LambderContractEntry, LambderMergeContract, LambderGuardNamesIn, LambderContractMode, LambderContractKeysWithMode, LambderContractKeysWithGuard, LambderJsonOf, LambderJsonOutputOf, LambderContractGuardsOf, LambderContractGuardNames, LambderContractGuardInputsOf, LambderContractGuardInput, LambderContractGuardInputNames, LambderContractRateLimitOf, LambderContractRateLimitNames, LambderContractIdempotencyOf, } from "./shared/wire/LambderApiContract.js";

package/dist/index.js

@@ -9,6 +9,11 @@ export { buildTransportEnvelope, LambderTransportFailure, isLambderTransportFail
 export { lambderCookieJarTransport } from "./shared/transport/lambderCookieJarTransport.js";
 export { LambderCookieJar, parseSetCookie } from "./shared/transport/LambderCookieJar.js";
 export { LambderExpiringMap, LambderExpiringMapFullError } from "./shared/util/LambderExpiringMap.js";
+// Waiting longer after each failure, once: what the upload runner and an app's own retrying code climb.
+export { LambderBackoffTimer } from "./shared/util/LambderBackoffTimer.js";
+// Signed claims tokens, and the keyed digest and random secret for the secrets an app stores.
+export { LambderSignedClaims, keyedDigest, randomSecret } from "./shared/util/LambderSignedClaims.js";
+export { constantTimeEquals } from "./shared/util/LambderTextDigest.js";
 export { lambderHandlerTransport } from "./invoke/lambderHandlerTransport.js";
 export { synthesizeLambdaHttpEvent, decodeLambdaHttpResult, localLambdaContext, LAMBDER_INVOKE_HEADER, LAMBDER_INVOKED_BY_HEADER, LAMBDER_INVOKE_PROTOCOL, } from "./invoke/LambderLambdaEvent.js";
 // The API core: the request, answer, envelope and pipeline both the server and the mock runtime run
@@ -71,6 +76,11 @@ export { LambderMemoryCache } from "./stores/LambderMemoryCache.js";
 export { RATE_LIMIT_WINDOWS } from "./shared/contracts/LambderRateLimiter.js";
 export { LambderDdbRateLimiter } from "./stores/LambderDdbRateLimiter.js";
 export { LambderMemoryRateLimiter } from "./stores/LambderMemoryRateLimiter.js";
+// One-shot secrets: codes and tokens handed out once and taken back once, the
+// store interface they live in, and the DynamoDB and in-memory stores
+export { LambderOneShotSecrets } from "./secrets/LambderOneShotSecrets.js";
+export { LambderDdbOneShotSecretStore } from "./stores/LambderDdbOneShotSecretStore.js";
+export { LambderMemoryOneShotSecretStore } from "./stores/LambderMemoryOneShotSecretStore.js";
 export { LambderDdbIdempotencyStore } from "./stores/LambderDdbIdempotencyStore.js";
 export { LambderMemoryIdempotencyStore } from "./stores/LambderMemoryIdempotencyStore.js";
 // Declarative per-API policies: guards
@@ -78,6 +88,9 @@ export { lambderGuard, lambderRateLimitKey } from "./core/LambderPolicyBuilders.
 export { lambderGuardBuilder } from "./api/LambderApiGuards.js";
 // Declarative per-API policies: rate limits
 export { lambderRateLimitKeyBuilder, rateLimitRefusal, DEFAULT_RATE_LIMIT_REFUSAL } from "./api/LambderApiRateLimits.js";
+// The declared options as plain data: what apiOptionEntries() reports and
+// writeApiOptions writes, and the readers over the generated tables.
+export { apiGuardParam } from "./shared/wire/LambderApiOptionEntries.js";
 // Typed translations (standalone, isomorphic)
 export { createLambderI18n } from "./shared/LambderI18n.js";
 export { resolveApiOutcome } from "./shared/wire/LambderApiOutcome.js";

package/dist/mock/LambderMockApp.d.ts

@@ -10,6 +10,7 @@ import { LambderMemoryIdempotencyStore } from "../stores/LambderMemoryIdempotenc
 import { LambderMemorySessionStore } from "../stores/LambderMemorySessionStore.js";
 import LambderSessionManager, { type LambderCreatedSession } from "../session/LambderSessionManager.js";
 import type { LambderMockAppOptions, LambderMockIdempotencyOptions, LambderMockTransport, LambderMockTransportOptions } from "./LambderMockCreateOptions.js";
+import type { LambderApiOptionEntry, LambderGuardDeclarationEntry } from "../shared/wire/LambderApiOptionEntries.js";
 import type { LambderMockCallContext, LambderMockCallRecord, LambderMockEntry, LambderMockEntryInput, LambderMockFailure, LambderMockFailureReason, LambderMockHandler, LambderMockLatency, LambderMockListener, LambderMockPublicNames, LambderMockRateLimitPolicies, LambderMockRegistryCheck, LambderMockRestEntry, LambderMockSessionCallContext, LambderMockSessionNames, LambderMockSlice, LambderMockOverride } from "./LambderMockTypes.js";
 /**
  * The mock runtime: the API core (LambderApiPipeline, the same class the
@@ -23,9 +24,10 @@ import type { LambderMockCallContext, LambderMockCallRecord, LambderMockEntry, L
  *
  * 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 declare class LambderMockApp<C extends LambderApiContractShape, S = any, G extends Record<string, LambderApiGuard<any, any, any>> = {}> {
+export declare class LambderMockApp<C extends LambderApiContractShape, S = any, G extends Record<string, LambderApiGuard<any, any, any>> = {}, TDerived extends boolean = false> {
     readonly apiVersion: string | null;
     /** The memory stores, for assertions and reset; null for a subsystem that is off or backed by a store of yours. */
     readonly sessionStore: LambderMemorySessionStore<S> | null;
@@ -61,9 +63,11 @@ export declare class LambderMockApp<C extends LambderApiContractShape, S = any,
     private readonly recorder;
     /** Registered entries and the overrides over them (see LambderMockEntryRegistry). */
     private readonly registry;
+    /** The server's declared options per API, when create() was given the generated table; the entries' declarations come from here. */
+    private readonly apiOptions;
     /** The jars the runtime owns and what it planted in document.cookie (see LambderMockBrowserCookies). */
     private readonly browserCookies;
-    constructor(options: LambderMockAppOptions<C, S, G>);
+    constructor(options: LambderMockAppOptions<C, S, G, LambderMockRateLimitPolicies<S>, boolean | LambderMockIdempotencyOptions<S>, {}, Record<string, LambderApiOptionEntry> | undefined>);
     /**
      * The registration-time checks every entry goes through, mocked or not:
      * the ones the server runs on a definition, and the mock's own "a session
@@ -75,11 +79,21 @@ export declare class LambderMockApp<C extends LambderApiContractShape, S = any,
      * option, for a mistake fixed by one option at create().
      */
     private assertEntryRegistration;
+    /**
+     * 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.
+     */
+    private declaredOptionsOf;
+    /** The mode the apiOptions table gives a name, or null without a table or for a name it does not hold. */
+    private declaredModeOf;
     private buildEntry;
     /** A mock for a public endpoint: a handler, or the handler with the endpoint's declarations restated. */
-    publicApi<K extends LambderMockPublicNames<C>, TInputSchema extends z.ZodType = z.ZodType>(name: K, entry: LambderMockEntryInput<C, K, S, G, TInputSchema>): LambderMockEntry<C, K>;
+    publicApi<K extends LambderMockPublicNames<C>, TInputSchema extends z.ZodType = z.ZodType>(name: K, entry: LambderMockEntryInput<C, K, S, G, TInputSchema, TDerived>): LambderMockEntry<C, K>;
     /** A mock for a session endpoint: the pipeline fetches the session before the handler runs, and refuses without one. */
-    sessionApi<K extends LambderMockSessionNames<C>, TInputSchema extends z.ZodType = z.ZodType>(name: K, entry: LambderMockEntryInput<C, K, S, G, TInputSchema>): LambderMockEntry<C, K>;
+    sessionApi<K extends LambderMockSessionNames<C>, TInputSchema extends z.ZodType = z.ZodType>(name: K, entry: LambderMockEntryInput<C, K, S, G, TInputSchema, TDerived>): LambderMockEntry<C, K>;
     /**
      * A public endpoint deliberately left without a mock; a call answers the
      * notMocked refusal carrying the reason.
@@ -111,13 +125,15 @@ export declare class LambderMockApp<C extends LambderApiContractShape, S = any,
      * 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: string): LambderMockRestEntry;
     private buildNotMockedEntry;
@@ -165,10 +181,11 @@ export declare class LambderMockApp<C extends LambderApiContractShape, S = any,
     /**
      * 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).
      */
     private restNotMockedEntry;
     /** The next call to the endpoint fails this way; several calls queue in order. */
@@ -332,5 +349,5 @@ export declare const initLambderMock: <C extends LambderApiContractShape, S = an
      * dropped. `I` exists for the same reason `P` does, and
      * LambderMockSurplusKeys puts the error back on the key.
      */
-    create<const G extends Record<string, LambderApiGuard<any, any, any, LambderMockCallContext<S>, LambderMockSessionCallContext<S>>> = {}, const P extends LambderMockRateLimitPolicies<S> = {}, I extends boolean | LambderMockIdempotencyOptions<S> = boolean | LambderMockIdempotencyOptions<S>>(options: LambderMockAppOptions<C, S, G, P, I>): LambderMockApp<C, S, G>;
+    create<const G extends Record<string, LambderApiGuard<any, any, any, LambderMockCallContext<S>, LambderMockSessionCallContext<S>>> = {}, const P extends LambderMockRateLimitPolicies<S> = {}, I extends boolean | LambderMockIdempotencyOptions<S> = boolean | LambderMockIdempotencyOptions<S>, const D extends Record<string, LambderGuardDeclarationEntry> = {}, const A extends Record<string, LambderApiOptionEntry> | undefined = undefined>(options: LambderMockAppOptions<C, S, G, P, I, D, A>): LambderMockApp<C, S, G, [A] extends [undefined] ? false : true>;
 };