lambder 8.1.2 → 8.3.1

package/CHANGELOG.md

@@ -9,6 +9,142 @@ sit on its first published patch, and later patches list only what they changed.
 Releases up to 3.2.6 carry git tags; the ones after it were published without
 one, so versions are not cross-linked to tag comparisons here.
 
+## [8.3.1] - 2026-09-27
+
+Six additions, each a thing an app otherwise writes for itself once per kind
+of token, secret, retry loop, copied declaration or store: signed claims
+tokens, one-shot secrets over a store that settles their races, the declared
+API options as generated files of plain data, a backoff timer, the digest and
+random secret behind stored secrets, and the store conformance suites for a
+store an app writes over its own database. Nothing changes on the wire, and
+every existing option keeps its meaning.
+
+### Added
+
+- **`writeApiOptions` in `lambder/build`: the declared options as a generated
+  file.** The contract carries every API's `guards`, `rateLimit` and
+  `idempotency` options as types; code that decides something at runtime with
+  them (a mock restating the server's policies, a test walking the public
+  surface, a screen asking which permission an endpoint needs) copied them by
+  hand and held the copies honest with tests that read the source.
+  `writeApiOptions({ module, exportName, file, check })` writes them once, as
+  three `as const` tables of plain data (`apiOptions`, `rateLimitPolicies`,
+  `guardDeclarations`) from the new `lambder.apiOptionEntries()`, sorted by
+  name, and `check: true` fails a stale file naming what moved per table.
+  Nothing in the file is code: a guard parameter that is not plain data fails
+  the write by API name, a policy keyed by a handler is written as `per:
+  "custom"` and no more, and a guard's schema as its input mode alone.
+  - Readers in `lambder/client`, typed to the tables' literals:
+    `LambderApisWithGuard`, `LambderApisGuardedBy`, `LambderApisWithMode`,
+    `LambderGuardParamOf` and `apiGuardParam(apiOptions, name, guard)`.
+  - `writeApiGuardParams({ module, exportName, guard, file, check })` writes
+    one guard's parameters beside it, as an `as const` table (`guardParams`)
+    of the APIs that declare the guard and what each gives it, with nothing
+    else about any API and no import: the least a browser gating a screen on
+    that guard needs, where importing `apiOptions` as a value would ship
+    every endpoint name and every guard's parameter, reasons included.
+  - `lambderMockPoliciesFrom(rateLimitPolicies, { keys })` in `lambder/mock`
+    rebuilds the policy configs `create()` takes from the table, requiring a
+    key handler for exactly the custom-keyed policies; `create()` takes a
+    `guardDeclarations` option that holds each mock guard to the server
+    guard's input mode and session requirement (`LambderMockGuardShapeOf`);
+    and an `apiOptions` option, the table itself, from which every entry's
+    guards, rate limit and idempotency are read. Given it, an entry is its
+    handler alone, a restated option is a compile error and a throw, the
+    table must cover the contract under each endpoint's mode
+    (`LambderMockApiOptionsCover`), and a `restNotMocked` answer runs under
+    the mode the table gives the name, so an unmocked session endpoint reads
+    the session first.
+  - The entry types `LambderApiOptionEntries`, `LambderApiOptionEntry`,
+    `LambderRateLimitPolicyEntry` and `LambderGuardDeclarationEntry` live in
+    `shared/wire`, with `LambderGuardRunAt`, `LambderRateLimitBudget` and
+    `LambderRateLimitChargeAt`, which moved down there unchanged.
+
+  See [the options as a generated file](./docs/apis.md#the-options-as-a-generated-file).
+
+- **`LambderSignedClaims`: signed tokens that are their own record.** One
+  instance per kind of token, built once with the secret, a version and the
+  zod schema of its claims; `sign(claims)` writes `<version>.<base64url
+  claims>.<base64url HMAC-SHA256>`, `verify(token, { now? })` answers the
+  claims or null for a forged, foreign, malformed, refused or expired token
+  alike. An optional `exp` claim in epoch seconds is judged on every verify,
+  against an injectable clock. WebCrypto only, exported from `lambder` and
+  `lambder/client` for the edge runtimes and shared backend packages that
+  verify where the secret is at hand. Beside it, `keyedDigest(secret,
+  value)`, the HMAC-SHA256 as base64url a stored secret rests as;
+  `randomSecret(bytes?)`; and `constantTimeEquals`.
+
+- **`LambderOneShotSecrets`: codes and tokens handed out once and taken back
+  once.** The code emailed to an address, the link in an activation mail, the
+  code texted before a document opens, the code read out to pair a device:
+  one life (minted, sent, stored as a digest, tried against, spent), written
+  once, over a `LambderOneShotSecretStore` that settles its races in six
+  methods. An app declares its kinds (a `code` of an alphabet and length with
+  a ceiling on tries, or a `token` redeemed by value: random bytes, or an
+  alphabet's characters for one somebody types) and names, per secret,
+  the scope it proves; `issue(kind, scope, { cooldownSeconds?, meta? })`
+  answers the plaintext exactly once, `redeem(kind, scope, candidate)` and
+  `redeemToken(kind, candidate)` answer `accepted`, `wrong` (with the tries
+  left), `expired`, `exhausted` or `none`, and `retire(scope)` ends what the
+  scope holds. One record is live per scope; a cooldown is a condition on
+  the issuing write; a token's digest is claimed by one scope at a time in
+  that same write, and a secret drawn onto a digest another scope holds is
+  drawn again (up to five times), so two scopes that drew the same short
+  code never redeem each other's; a try is counted in the write that reads
+  the digest; a redemption is a conditional consume.
+  `LambderDdbOneShotSecretStore` keeps a code as one item under `OTS#` in
+  the policy table and a token as two, written in one transaction, and sends
+  a write DynamoDB refused for a concurrent transaction on its item again, up
+  to three times; `LambderMemoryOneShotSecretStore` keeps the same in a map, and
+  `lambderOneShotSecretStoreConformance` holds both, and an app's own store,
+  to one set of rules. The class sits in a new `src/secrets/` layer beside
+  `session/`.
+
+- **`LambderBackoffTimer`: waiting longer after each failure, once.** One
+  pending wait at a time: `retry(run)` and `wait(signal?)` climb a jittered
+  ladder (`baseMs` the shortest wait, `maxMs` the longest, `factor`,
+  `jitter`), `after(ms, run)` waits off
+  it, `reset()` and `cancel()`; `wait` rejects with the signal's reason on
+  abort and with an Error when dropped, so an await on it always settles.
+  Exported from `lambder` and `lambder/client`.
+
+  See [Secrets and retries](./docs/secrets.md).
+
+- **Store conformance suites in `lambder/testing`.** The rules each store
+  interface promises its engine were asserted in Lambder's own test suite,
+  where only Lambder's stores could meet them; a store an app writes over its
+  own database had nothing to hold it to the same rules. They are now
+  exported, one suite per interface: `lambderSessionStoreConformance`,
+  `lambderIdempotencyStoreConformance`, `lambderRateLimiterConformance` and
+  `lambderOneShotSecretStoreConformance`. Each takes the runner's own `it`
+  and `expect` (any jest-style `expect`; Lambder imports no runner) and a
+  `create` that builds a store for one case, handed the case's clock as
+  `now`. The one-shot suite also takes what a store over existing rows needs
+  in place of its defaults: two `scopes` it can hold, the kind it keeps for
+  each shape it holds (`kinds: { code?, token? }`, which decides whether the
+  cases about tries or the ones about digests run), the `meta`, and the
+  `lifetimeSeconds` it derives an expiry from. Among its rules: two issues
+  racing for one scope leave exactly one live record, two scopes racing for
+  one token digest leave it with exactly one, and `attempt` and `consume`
+  name a record by its scope and id together, so a record of another scope
+  is never the one named. Lambder's memory and DynamoDB stores run through
+  the same suites.
+
+  See [A store of your own](./docs/testing.md#a-store-of-your-own).
+
+### Changed
+
+- **`LambderUploadRunner` waits on a `LambderBackoffTimer` between tries at
+  storage.** The ladder is the timer's: each wait is `baseDelayMs` plus a
+  random share of a ceiling that starts at `baseDelayMs` and doubles per
+  failed attempt, the whole never past `maxDelayMs`. The first wait is
+  unchanged (between the base and twice it); a later one may be shorter than
+  before, since the ceiling now counts from the base rather than from twice
+  it.
+- **The session crypto shares its HMAC and its constant-time comparison** with
+  the new module through `shared/util/LambderTextDigest.ts` rather than
+  keeping copies of its own. Behaviour is unchanged.
+
 ## [8.1.2] - 2026-09-26
 
 ### Fixed

package/README.md

@@ -113,10 +113,10 @@ The package ships five entry points; pick by where the code runs:
 | Entry | Runs in | Carries |
 | --- | --- | --- |
 | `lambder` | Server (Lambda) | The full framework: pipeline, sessions, DDB stores, policies, plus the API core's building blocks and everything from `lambder/client` except the two request-compression helpers, `compressPayloadGzip` and `isRequestCompressionAvailable`, which stay on the client entry where a payload is compressed |
-| `lambder/client` | Browser and isomorphic shared code | `LambderCaller`, `LambderApiRefusal`/`refuse`, the API contract and envelope types, `html`/`xml` tagged templates, `createLambderI18n` |
+| `lambder/client` | Browser and isomorphic shared code | `LambderCaller`, `LambderApiRefusal`/`refuse`, the API contract and envelope types, `LambderUploadRunner`, `LambderBackoffTimer`, `LambderSignedClaims`, `html`/`xml` tagged templates, `createLambderI18n` |
 | `lambder/mock` | Browser and Node, in development and tests | `LambderMockApp`, the mock runtime: your typed contract served from mock handlers over the real API pipeline and memory stores |
-| `lambder/testing` | Node, in tests | `lambderTestApp`: your real instance under test in this process, memory stores put under it in place, simulated browsers with typed callers in front of it, and the outcome assertions |
-| `lambder/build` | Node, in a build step | `writeApiSignatures`: the signature file both sides ship, written or checked from your instance; `writeApiContract`: the contract as plain types a client compiles instead of the server |
+| `lambder/testing` | Node, in tests | `lambderTestApp`: your real instance under test in this process, memory stores put under it in place, simulated browsers with typed callers in front of it, and the outcome assertions; the store conformance suites, to hold a store you write to the rules Lambder's own meet |
+| `lambder/build` | Node, in a build step | `writeApiSignatures`: the signature file both sides ship, written or checked from your instance; `writeApiOptions`: every API's declared options, policies and guard declarations as plain data, for the code that decides with them; `writeApiGuardParams`: one guard's parameters and nothing else, what a browser gating on that guard carries; `writeApiContract`: the contract as plain types a client compiles instead of the server |
 
 Frontends and shared isomorphic packages should import from `lambder/client`
 only; the entry's module graph contains no AWS SDK, Node built-ins, or server
@@ -126,14 +126,15 @@ tree-shaking.
 Source layout mirrors this: `src/api/` (the isomorphic API core: request,
 answer, envelope, pipeline, and the declarative policies the pipeline runs),
 `src/core/` (the Lambda server adapter: routes, files, hooks, finalization),
-`src/session/` (the session manager, controller and crypto), `src/stores/`
+`src/session/` (the session manager, controller and crypto), `src/secrets/`
+(one-shot secrets over their store), `src/stores/`
 (every store and file-source implementation, DynamoDB and in-memory alike,
 and the helpers the two caches share), `src/client/`,
 `src/invoke/` (the lambda-to-lambda caller and the in-process handler
-transport), `src/mock/` (the mock runtime), `src/testing/` (the test app),
+transport), `src/mock/` (the mock runtime), `src/testing/` (the test app and the store conformance suites),
 `src/build/` (what a generator script runs at build time), and `src/shared/`
 (isomorphic modules every entry re-exports, grouped into `wire/` for the
-format both sides speak, `contracts/` for the five store and source
+format both sides speak, `contracts/` for the six store and source
 interfaces, `transport/` for the caller-to-server seam, and `util/` for
 helpers).
 Directories are layers and imports only ever point down;
@@ -156,7 +157,7 @@ guide that matches what you are building. The full index lives in
 | [Sessions](./docs/sessions.md) | Sessions over a store, cookie scope, secrets at rest, `dataRefresh`, the controller API |
 | [API policies](./docs/api-policies.md) | Declarative rate limits, guards and idempotency, and mandatory authorization declarations |
 | [Calling another lambda](./docs/invoke.md) | `LambderInvokeCaller`: invoking a Lambder app in another function, its contract, failures and compression |
-| [Testing](./docs/testing.md) | `lambderTestApp`: the real instance under test with no HTTP and no AWS, visitors, sign-in without a login endpoint, outcome assertions, crashes, time |
+| [Testing](./docs/testing.md) | `lambderTestApp`: the real instance under test with no HTTP and no AWS, visitors, sign-in without a login endpoint, outcome assertions, crashes, time, store conformance suites |
 | [The API core](./docs/api-core.md) | `LambderApiPipeline`: the one pipeline the server and the mock runtime run, the store interfaces, the transports |
 | [Frontend client](./docs/client.md) | `LambderCaller`: typed calls, failure outcomes, timeouts, guard inputs, request compression, transports |
 | [Frontend hosting](./docs/frontend-hosting.md) | File sources, `servePublicFiles`, `serveIndexHtml`, `res.templateFile` |

package/dist/api/LambderApiGuards.d.ts

@@ -37,22 +37,8 @@ type LambderGuardAnswerCheck<TOutput> = [
 type LambderGuardOf<TOutput, TGuard> = LambderGuardAnswerCheck<TOutput> extends LambderGuardMustNotAnswer ? LambderGuardMustNotAnswer : TGuard;
 /** One guard handler: the adapter's context, the validated input slice (undefined in the no-input mode), and the per-API parameter. */
 type LambderGuardHandler<TCtx, TPayload, TParam, TOutput> = (ctx: TCtx, payload: TPayload, param: TParam) => TOutput | Promise<TOutput>;
-/**
- * When a guard runs, relative to the API's input validation.
- *
- * - "beforeInputValidation" (default): an unauthorized caller learns nothing
- *   about the input, and no async refinement in the schema runs for it.
- * - "afterInputValidation": for a guard that spends something on the
- *   request, such as a single-use captcha token, which a request refused for
- *   a mistyped field would otherwise waste. The API's input schema then runs
- *   for callers this guard would refuse, so keep lookups (an "email is free"
- *   refinement) out of it, in the handler.
- *
- * Guards run in their declared order within each, and the limits keyed by
- * caller data are charged after both unless their policy says otherwise
- * (LambderRateLimitChargeAt).
- */
-export type LambderGuardRunAt = "beforeInputValidation" | "afterInputValidation";
+import type { LambderGuardRunAt } from "../shared/wire/LambderApiOptionEntries.js";
+export type { LambderGuardRunAt };
 /** Where in the call a guard runs: see LambderGuardRunAt. */
 export type LambderGuardPlacement = {
     /** Default: "beforeInputValidation". */
@@ -331,4 +317,3 @@ export declare class LambderApiGuardsEngine {
      */
     run(request: LambderApiRequest, ctx: LambderApiCallContext, guardsOption: LambderGuardsOptionValue | undefined, trace: LambderApiCallTrace, runAt: LambderGuardRunAt): Promise<void>;
 }
-export {};

package/dist/api/LambderApiRateLimits.d.ts

@@ -78,34 +78,8 @@ export type LambderRateLimitKeyBuilder<TCtx> = {
 export declare const lambderRateLimitKeyBuilder: <TCtx>() => LambderRateLimitKeyBuilder<TCtx>;
 /** What one rate-limit counter tracks: the client IP, the session identity, or a custom payload-derived key. */
 export type LambderRateLimitPer<TCtx = any> = "ip" | "session" | LambderRateLimitKeyFn<any, TCtx>;
-/**
- * What one budget spans:
- *
- * - "perApi" (default): every API referencing the policy gets its own
- *   counter, so the windows are a per-API ceiling (three APIs referencing a
- *   60/min policy allow one subject 180/min in total). An API may tune the
- *   windows in its declaration: `rateLimit: { name: { perMin: 20 } }`.
- * - "perPolicy": every API referencing the policy shares ONE counter, so the
- *   windows are one combined budget (e.g. one per-email allowance across
- *   send, register, and reset). The policy IS the group: to give user APIs
- *   and report APIs separate shared budgets, declare two policies.
- */
-export type LambderRateLimitBudget = "perApi" | "perPolicy";
-/**
- * When a custom-keyed policy is charged, relative to the guards and the input
- * schema.
- *
- * - "afterGuards" (default): after every guard and the input schema passed.
- *   The key is a value the caller chose (an email in the payload), so a
- *   caller who never passes a captcha guard cannot spend a victim's budget
- *   and lock them out of reset, register and send-code.
- * - "beforeGuards": before the guards and the input schema, so an attempt
- *   they refuse is counted too. For a limit on guessing a secret a guard or
- *   the schema checks (a one-time code checked by a guard, keyed per email):
- *   charged after them, a wrong guess is refused before it is ever counted.
- *   Pair it with an IP limit, since anyone may spend this budget.
- */
-export type LambderRateLimitChargeAt = "beforeGuards" | "afterGuards";
+import type { LambderRateLimitBudget, LambderRateLimitChargeAt } from "../shared/wire/LambderApiOptionEntries.js";
+export type { LambderRateLimitBudget, LambderRateLimitChargeAt };
 /**
  * A named rate-limit policy: fixed windows, the key one counter tracks, and
  * what one budget spans.
@@ -357,4 +331,3 @@ export declare class LambderApiRateLimitsEngine {
      */
     private requestKeyOf;
 }
-export {};

package/dist/build/generatedTables.d.ts

@@ -0,0 +1,72 @@
+import type { LambderApiOptionEntries } from "../shared/wire/LambderApiOptionEntries.js";
+import { type LambderModuleLocation } from "./moduleLocation.js";
+/** What the generators read the options from: a Lambder instance, or anything else that reports them the same way. */
+export type LambderApiOptionsSource = {
+    apiOptionEntries(): LambderApiOptionEntries;
+};
+/** Which names of one table moved: entries that changed, entries the file did not have, entries the file had and the instance no longer reports. */
+export type LambderNameChanges = {
+    changed: string[];
+    added: string[];
+    removed: string[];
+};
+/** Imports the module, finds the instance under its export, and answers what it reports. `generator` names the caller in the errors. */
+export declare const loadApiOptionEntries: (location: {
+    module: LambderModuleLocation;
+    exportName?: string;
+}, generator: string) => Promise<LambderApiOptionEntries>;
+/** One table of a generated file, read back as data, or null for a file that does not hold it as written. */
+export declare const readGeneratedTable: (contents: string, exportName: string) => Record<string, unknown> | null;
+/** How one table's entries differ from the ones a file held, by name, compared as canonical JSON so key order is not a change. */
+export declare const nameChangesOf: (current: Record<string, unknown>, previous: Record<string, unknown>) => LambderNameChanges;
+/** The opening comment of a generated file, one `//` line per line of the header. */
+export declare const headerLinesOf: (header: string) => string[];
+/**
+ * One table as a statement: its doc comment, the `// prettier-ignore` that
+ * keeps a formatter off the JSON a check reads back, and the table itself,
+ * `as const` with whatever `satisfies` clause the caller gives.
+ */
+export declare const tableStatementLines: (table: {
+    name: string;
+    doc: string;
+    value: unknown;
+    satisfies?: string;
+    semicolon: string;
+}) => string[];
+/**
+ * The end of a generator's run. With `check`, it answers whether the file
+ * holds what the instance reports and writes nothing. Otherwise it writes
+ * the file unless it already holds these tables, however it is formatted, so
+ * a watcher or an incremental build sees no change where there is none (a
+ * change of header or semicolons shows the next time a table changes).
+ * Either way the lines say what moved.
+ */
+export declare const settleGeneratedFile: (run: {
+    /** The file as the caller named it, for the lines. */
+    name: string;
+    /** The absolute path. */
+    file: string;
+    check: boolean | undefined;
+    /** The file's text before this run, or null when there was none. */
+    previousText: string | null;
+    /** Whether that text held the tables as written; false for a file rewritten by hand. */
+    readBack: boolean;
+    /** Each table the file holds, under its exported name: how many entries it has now, and which of them moved. */
+    tables: readonly {
+        name: string;
+        count: number;
+        changes: LambderNameChanges;
+    }[];
+    /** What the tables hold, for the lines: "6 APIs, 4 policies, 5 guards". */
+    held: string;
+    /** What the file holds when it is as written, for the line when it is not: "the three tables". */
+    tablesNoun: string;
+    /** The line when nothing moved: "no options changed". */
+    unmovedLine: string;
+    /** The file's contents, rendered only when it is written. */
+    render: () => string;
+}) => {
+    ok: boolean;
+    written: boolean;
+    lines: string[];
+};

package/dist/build/generatedTables.js

@@ -0,0 +1,99 @@
+import { canonicalJson } from "../shared/util/canonicalJson.js";
+import { moduleUrlOf } from "./moduleLocation.js";
+import { writeFileAtomically } from "./writeFileAtomically.js";
+/** Imports the module, finds the instance under its export, and answers what it reports. `generator` names the caller in the errors. */
+export const loadApiOptionEntries = async (location, generator) => {
+    const moduleUrl = moduleUrlOf(location.module);
+    const exportName = location.exportName ?? "default";
+    let namespace;
+    try {
+        namespace = await import(moduleUrl);
+    }
+    catch (err) {
+        throw new Error(`${generator} could not load ${moduleUrl}`, { cause: err });
+    }
+    const source = namespace[exportName];
+    if (typeof source?.apiOptionEntries !== "function") {
+        throw new Error(`${moduleUrl} has no export "${exportName}" that reports API options: name the export holding the instance in exportName`);
+    }
+    return source.apiOptionEntries();
+};
+/** One table of a generated file, read back as data, or null for a file that does not hold it as written. */
+export const readGeneratedTable = (contents, exportName) => {
+    const match = new RegExp(`export const ${exportName}\\s*=\\s*([\\s\\S]*?)\\s+as const\\b`).exec(contents);
+    if (!match)
+        return null;
+    try {
+        const table = JSON.parse(match[1]);
+        return table !== null && typeof table === "object" && !Array.isArray(table) ? table : null;
+    }
+    catch {
+        return null;
+    }
+};
+/** How one table's entries differ from the ones a file held, by name, compared as canonical JSON so key order is not a change. */
+export const nameChangesOf = (current, previous) => {
+    const same = (name) => canonicalJson(current[name]) === canonicalJson(previous[name]);
+    return {
+        changed: Object.keys(current).filter((name) => name in previous && !same(name)).sort(),
+        added: Object.keys(current).filter((name) => !(name in previous)).sort(),
+        removed: Object.keys(previous).filter((name) => !(name in current)).sort(),
+    };
+};
+/** One line per name that moved, marked `~` changed, `+` added or `-` removed, under the table's name. */
+const movedLinesOf = (tableName, changes) => [
+    ...changes.changed.map((name) => `  ~ ${tableName} ${name}`),
+    ...changes.added.map((name) => `  + ${tableName} ${name}`),
+    ...changes.removed.map((name) => `  - ${tableName} ${name}`),
+];
+/** The opening comment of a generated file, one `//` line per line of the header. */
+export const headerLinesOf = (header) => header.split("\n").map((line) => line ? `// ${line}` : "//");
+/**
+ * One table as a statement: its doc comment, the `// prettier-ignore` that
+ * keeps a formatter off the JSON a check reads back, and the table itself,
+ * `as const` with whatever `satisfies` clause the caller gives.
+ */
+export const tableStatementLines = (table) => [
+    `/** ${table.doc} */`,
+    "// prettier-ignore",
+    `export const ${table.name} = ${JSON.stringify(table.value, null, 4)} as const${table.satisfies ? ` satisfies ${table.satisfies}` : ""}${table.semicolon}`,
+];
+/**
+ * The end of a generator's run. With `check`, it answers whether the file
+ * holds what the instance reports and writes nothing. Otherwise it writes
+ * the file unless it already holds these tables, however it is formatted, so
+ * a watcher or an incremental build sees no change where there is none (a
+ * change of header or semicolons shows the next time a table changes).
+ * Either way the lines say what moved.
+ */
+export const settleGeneratedFile = (run) => {
+    const movedLines = run.tables.flatMap((table) => movedLinesOf(table.name, table.changes));
+    const summary = run.tables.map(({ name, count, changes }) => `${name}: ${changes.changed.length} changed, ${changes.added.length} added, ${changes.removed.length} removed (${count - changes.changed.length - changes.added.length} unchanged)`).join("; ");
+    const unchanged = run.readBack && movedLines.length === 0;
+    if (run.check) {
+        if (unchanged)
+            return { ok: true, written: false, lines: [`✓ ${run.name} matches the ${run.held}`] };
+        return {
+            ok: false,
+            written: false,
+            lines: [
+                run.previousText !== null && !run.readBack
+                    ? `✗ ${run.name} does not hold ${run.tablesNoun} as written: regenerate it`
+                    : `✗ ${run.name} is stale: regenerate it`,
+                `  ${summary}`,
+                ...movedLines,
+            ],
+        };
+    }
+    const written = !unchanged;
+    if (written)
+        writeFileAtomically(run.file, run.render(), run.previousText !== null);
+    return {
+        ok: true,
+        written,
+        lines: [
+            written ? `✓ Wrote ${run.name} (${run.held})` : `✓ ${run.name} is up to date (${run.held})`,
+            ...(movedLines.length ? [`  ${summary}`, ...movedLines] : [`  ${run.unmovedLine}`]),
+        ],
+    };
+};

package/dist/build/writeApiGuardParams.d.ts

@@ -0,0 +1,60 @@
+import type { LambderModuleLocation } from "./moduleLocation.js";
+import { type LambderNameChanges } from "./generatedTables.js";
+export type LambderApiGuardParamsFileOptions = {
+    /**
+     * The module that exports the instance, usually the server's entry: a
+     * path relative to the working directory, or a file URL. It is imported
+     * in this process, so a TypeScript module needs the process's loader
+     * (`tsx`, `node --import tsx`), as the generator script itself does.
+     */
+    module: LambderModuleLocation;
+    /** The export that holds the instance. Default: "default", the module's default export. */
+    exportName?: string;
+    /** The guard whose parameters the file holds, as the server declares it. A name the server declares no guard under throws. */
+    guard: string;
+    /** The TypeScript module to write, exporting `guardParams`. Relative to the working directory. */
+    file: string;
+    /** Write nothing, and answer whether the file on disk holds what the instance reports now. Default: false. */
+    check?: boolean;
+    /** The comment the file opens with, one `//` line per line. It should name what generates the file. Default: a note naming writeApiGuardParams() and the guard. */
+    header?: string;
+    /** End the generated statement with a semicolon. Default: true. The table itself is JSON, double quotes included, whatever the project's style: that is what lets a check read it back. */
+    semicolons?: boolean;
+};
+export type LambderApiGuardParamsFileResult = {
+    /** False when a check found the file stale or unreadable. */
+    ok: boolean;
+    /** The absolute path. */
+    file: string;
+    /** True when the file was (re)written; a file that already holds this table is left untouched, however it is formatted. */
+    written: boolean;
+    /** How many APIs declare the guard. */
+    count: number;
+    /** Which APIs moved against the file that was on disk. */
+    changes: LambderNameChanges;
+    /** What happened, as lines to print: a summary, then one line per name that moved. */
+    lines: string[];
+};
+/**
+ * Writes one guard's parameters as a module of plain data, or checks the one
+ * on disk, and says which APIs moved.
+ *
+ * ```ts
+ * import { writeApiGuardParams } from "lambder/build";
+ *
+ * const result = await writeApiGuardParams({
+ *     module: "server/src/index.ts",
+ *     exportName: "lambder",
+ *     guard: "store",
+ *     file: "web/src/generated/storeGuardParams.generated.ts",
+ *     check: process.argv.includes("--check"),
+ * });
+ * ```
+ *
+ * The module exports `guardParams`, `as const`, so a client reads its types
+ * straight off it: `keyof typeof guardParams` is the APIs behind the guard,
+ * and `(typeof guardParams)[K]` the literal API K declared, `true` for a
+ * guard named without a parameter (the string and list forms). A parameter
+ * that is not plain data fails the write, as it does for writeApiOptions.
+ */
+export declare const writeApiGuardParams: (options: LambderApiGuardParamsFileOptions) => Promise<LambderApiGuardParamsFileResult>;

package/dist/build/writeApiGuardParams.js

@@ -0,0 +1,85 @@
+import { existsSync, readFileSync } from "fs";
+import { resolve } from "path";
+import { apiGuardParam } from "../shared/wire/LambderApiOptionEntries.js";
+import { headerLinesOf, loadApiOptionEntries, nameChangesOf, readGeneratedTable, settleGeneratedFile, tableStatementLines, } from "./generatedTables.js";
+/*
+ * One guard's parameters as a generated module a browser may carry: for each
+ * API that declares the guard, the parameter it gives it, and nothing else
+ * about any API.
+ *
+ * The file writeApiOptions writes holds every declaration, because a mock
+ * and a test need every declaration. A screen that decides whether to offer
+ * a control by the permission an endpoint's guard asks needs one guard's
+ * parameter, and a browser that imports the whole table as a value carries
+ * every API name, every mode and every guard's parameter, a reviewer's
+ * reason beside an open endpoint included. This is the least that screen
+ * needs: the names of the APIs behind the guard (which the client calls, so
+ * its own code names them already) and what each asks.
+ */
+const TABLE_NAME = "guardParams";
+const defaultHeader = (guard) => [
+    "Generated by writeApiGuardParams() from lambder/build. Do not edit.",
+    "",
+    `The parameter each API the server guards with "${guard}" gives that guard,`,
+    "and nothing else about any API: what a client decides with it, without",
+    "carrying the server's other declarations.",
+].join("\n");
+/**
+ * Writes one guard's parameters as a module of plain data, or checks the one
+ * on disk, and says which APIs moved.
+ *
+ * ```ts
+ * import { writeApiGuardParams } from "lambder/build";
+ *
+ * const result = await writeApiGuardParams({
+ *     module: "server/src/index.ts",
+ *     exportName: "lambder",
+ *     guard: "store",
+ *     file: "web/src/generated/storeGuardParams.generated.ts",
+ *     check: process.argv.includes("--check"),
+ * });
+ * ```
+ *
+ * The module exports `guardParams`, `as const`, so a client reads its types
+ * straight off it: `keyof typeof guardParams` is the APIs behind the guard,
+ * and `(typeof guardParams)[K]` the literal API K declared, `true` for a
+ * guard named without a parameter (the string and list forms). A parameter
+ * that is not plain data fails the write, as it does for writeApiOptions.
+ */
+export const writeApiGuardParams = async (options) => {
+    const file = resolve(options.file);
+    const entries = await loadApiOptionEntries(options, "writeApiGuardParams");
+    if (!Object.prototype.hasOwnProperty.call(entries.guards, options.guard)) {
+        const declared = Object.keys(entries.guards);
+        throw new Error(`writeApiGuardParams: the server declares no guard "${options.guard}" (it declares ${declared.length ? declared.map((name) => `"${name}"`).join(", ") : "none"}).`);
+    }
+    const params = {};
+    for (const name of Object.keys(entries.apis).sort()) {
+        const param = apiGuardParam(entries.apis, name, options.guard);
+        if (param !== undefined)
+            params[name] = param;
+    }
+    const previousText = existsSync(file) ? readFileSync(file, "utf8") : null;
+    const previous = previousText === null ? null : readGeneratedTable(previousText, TABLE_NAME);
+    const changes = nameChangesOf(params, previous ?? {});
+    const count = Object.keys(params).length;
+    const settled = settleGeneratedFile({
+        name: options.file, file, check: options.check, previousText, readBack: previous !== null,
+        tables: [{ name: TABLE_NAME, count, changes }],
+        held: `${count} APIs guarded by "${options.guard}"`,
+        tablesNoun: "the table",
+        unmovedLine: "no parameters changed",
+        render: () => [
+            ...headerLinesOf(options.header ?? defaultHeader(options.guard)),
+            "",
+            ...tableStatementLines({
+                name: TABLE_NAME,
+                doc: `The parameter each API guarded by "${options.guard}" gives it: the value as declared, or true for the guard named without one.`,
+                value: params,
+                semicolon: options.semicolons === false ? "" : ";",
+            }),
+            "",
+        ].join("\n"),
+    });
+    return { ...settled, file, count, changes };
+};

package/dist/build/writeApiOptions.d.ts

@@ -0,0 +1,68 @@
+import type { LambderApiOptionEntries } from "../shared/wire/LambderApiOptionEntries.js";
+import type { LambderModuleLocation } from "./moduleLocation.js";
+import { type LambderNameChanges } from "./generatedTables.js";
+type TableKey = keyof LambderApiOptionEntries;
+export type LambderApiOptionsFileOptions = {
+    /**
+     * The module that exports the instance, usually the server's entry: a
+     * path relative to the working directory, or a file URL. It is imported
+     * in this process, so a TypeScript module needs the process's loader
+     * (`tsx`, `node --import tsx`), as the generator script itself does.
+     */
+    module: LambderModuleLocation;
+    /** The export that holds the instance. Default: "default", the module's default export. */
+    exportName?: string;
+    /** The TypeScript module to write, exporting `apiOptions`, `rateLimitPolicies` and `guardDeclarations`. Relative to the working directory. */
+    file: string;
+    /** Write nothing, and answer whether the file on disk holds what the instance reports now. Default: false. */
+    check?: boolean;
+    /** The comment the file opens with, one `//` line per line. It should name what generates the file. Default: a note naming writeApiOptions(). */
+    header?: string;
+    /** End the generated statements with semicolons. Default: true. The tables themselves are JSON, double quotes included, whatever the project's style: that is what lets a check read them back. */
+    semicolons?: boolean;
+};
+export type LambderApiOptionsFileResult = {
+    /** False when a check found the file stale or unreadable. */
+    ok: boolean;
+    /** The absolute path. */
+    file: string;
+    /** True when the file was (re)written; a file that already holds these tables is left untouched, however it is formatted. */
+    written: boolean;
+    /** How many APIs, policies and guards the tables hold. */
+    counts: Record<TableKey, number>;
+    /** What moved, per table, against the file that was on disk. */
+    changes: Record<TableKey, LambderNameChanges>;
+    /** What happened, as lines to print: a summary, then one line per name that moved. */
+    lines: string[];
+};
+/** 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 declare const readOptionTables: (contents: string) => LambderApiOptionEntries | null;
+/**
+ * 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 declare const writeApiOptions: (options: LambderApiOptionsFileOptions) => Promise<LambderApiOptionsFileResult>;
+export {};