lambder 14.1.1 → 15.0.2

package/dist/shared/util/LambderBackoffTimer.js

@@ -1,33 +1,61 @@
 import { assertNumberAtLeast } from "./LambderOptionChecks.js";
+/**
+ * The longest delay setTimeout keeps: a longer one overflows its 32-bit
+ * millisecond count and fires at once, in browsers and in Node alike, so a
+ * ladder that reached past it would retry with no pause at all.
+ */
+const LONGEST_TIMER_DELAY_MS = 2_147_483_647;
 export class LambderBackoffTimer {
     baseMs;
     maxMs;
     factor;
     jitter;
-    attempts = 0;
+    retriesSinceReset = 0;
     timer = null;
     /** Settles the promise of a `wait` that cancel() or a replacement drops, so no `await` is left hanging. */
     dropPending = null;
     constructor(options = {}) {
-        this.baseMs = assertNumberAtLeast(options.baseMs ?? 1_000, 0, "baseMs");
+        const baseMs = options.baseMs ?? 1_000;
+        // Every rung is a multiple of the base, so a base of 0 is a retry
+        // loop with no pause.
+        if (typeof baseMs !== "number" || !(baseMs > 0) || baseMs > LONGEST_TIMER_DELAY_MS) {
+            throw new Error(`Lambder: LambderBackoffTimer baseMs must be a number above 0 and at most ${LONGEST_TIMER_DELAY_MS}, got ${String(baseMs)}: every wait is a multiple of it, so 0 retries with no pause, and setTimeout fires a longer delay at once.`);
+        }
+        this.baseMs = baseMs;
         this.maxMs = assertNumberAtLeast(options.maxMs ?? Math.max(60_000, this.baseMs), this.baseMs, "maxMs");
+        if (this.maxMs > LONGEST_TIMER_DELAY_MS) {
+            throw new Error(`Lambder: LambderBackoffTimer maxMs must be at most ${LONGEST_TIMER_DELAY_MS}, got ${this.maxMs}: setTimeout fires a longer delay at once, so the top of the ladder would retry with no pause.`);
+        }
         this.factor = assertNumberAtLeast(options.factor ?? 2, 1, "factor");
-        this.jitter = options.jitter ?? "full";
+        const jitter = options.jitter ?? "full";
+        if (jitter !== "full" && jitter !== "none") {
+            throw new Error(`Lambder: LambderBackoffTimer jitter must be "full" or "none", got ${JSON.stringify(jitter)}.`);
+        }
+        this.jitter = jitter;
     }
     /** True while a wait of any kind is pending. False again by the time it runs. */
     get pending() {
         return this.timer !== null;
     }
     /**
-     * Runs `run` after the next rung of the ladder, counting one more failed
-     * attempt. Replaces whatever was waiting.
+     * How many retries `retry` and `wait` have scheduled since the last reset
+     * (or since the timer was built), a dropped one included: the rung the
+     * next one climbs from. A loop that gives up after so many retries reads
+     * it here rather than keeping a counter of its own.
+     */
+    get retries() {
+        return this.retriesSinceReset;
+    }
+    /**
+     * Runs `run` after the next rung of the ladder, counting one more retry.
+     * Replaces whatever was waiting.
      */
     retry(run) {
         this.schedule(this.nextRung(), run, null);
     }
     /**
-     * Resolves after the next rung of the ladder, counting one more failed
-     * attempt: the `retry` for code that awaits rather than calls back.
+     * Resolves after the next rung of the ladder, counting one more retry:
+     * the `retry` for code that awaits rather than calls back.
      * Replaces whatever was waiting. Rejects at once with the signal's reason
      * when `signal` aborts, and with an Error when cancel() or a later wait
      * drops it before it ran, so an await on it always settles.
@@ -52,9 +80,9 @@ export class LambderBackoffTimer {
     after(delayMs, run) {
         this.schedule(delayMs, run, null);
     }
-    /** The attempt worked: the next failure waits the shortest time again. A pending wait is left alone. */
+    /** The attempt worked: the next failure waits the shortest time again, and `retries` is 0. A pending wait is left alone. */
     reset() {
-        this.attempts = 0;
+        this.retriesSinceReset = 0;
     }
     /** Drops the pending wait (the caller is trying right now, or going away), keeping the count. */
     cancel() {
@@ -66,10 +94,10 @@ export class LambderBackoffTimer {
         this.dropPending = null;
         drop?.();
     }
-    /** The next wait on the ladder, in milliseconds, counting one more failed attempt. */
+    /** The next wait on the ladder, in milliseconds, counting one more retry. */
     nextRung() {
-        const ceiling = Math.min(this.baseMs * this.factor ** this.attempts, this.maxMs - this.baseMs);
-        this.attempts += 1;
+        const ceiling = Math.min(this.baseMs * this.factor ** this.retriesSinceReset, this.maxMs - this.baseMs);
+        this.retriesSinceReset += 1;
         return this.baseMs + (this.jitter === "full" ? Math.random() : 1) * ceiling;
     }
     schedule(delayMs, run, drop) {

package/dist/shared/util/LambderCallAbort.d.ts

@@ -9,13 +9,22 @@
  * the two from drifting apart: a caller that believed a late answer would
  * report `ok: true` for a call its site had already abandoned.
  *
+ * Who gave up matters as much as when. A call's own timeout is a failure the
+ * callers report; the site's own signal is the site's choice (a superseded
+ * read, a view that closed), which nothing should report as something gone
+ * wrong, so the two are told apart here, once. A site signal can carry a
+ * deadline of its own, though: AbortSignal.timeout() aborts with a
+ * TimeoutError, alone or inside AbortSignal.any(), and a call it ends is
+ * timed out like one its own timeoutMs ended. Read as the site's choice, it
+ * would fail with nothing reporting it.
+ *
  * The listener on an external signal is removed in detach() rather than left
  * to `once`: a site's signal usually outlives the call (one controller per
  * page, per view, per request), so a listener per call would accumulate on it
  * for as long as the signal lives.
  */
-/** How an abandoned call is reported: its own timeout fired, or the site's signal did, which is a `network` failure like any other abort. */
-type LambderCallAbortReason = "timeout" | "network";
+/** Who gave up on a call: a deadline ended it (`timeout`: its own timeoutMs, or a site signal that aborted with a TimeoutError), or the site's own signal did (`aborted`). */
+export type LambderCallAbortReason = "timeout" | "aborted";
 /** The reason and the error to report for a call that was given up on. */
 type LambderCallAbortFailure = {
     reason: LambderCallAbortReason;
@@ -29,8 +38,12 @@ export type LambderCallAbortStage = "beforeSending" | "afterAnswering";
 type LambderCallAbort = {
     /** What the transport is handed: the chained signal when a timeout is set, the site's own otherwise, and nothing when there is neither. */
     signal: AbortSignal | undefined;
-    /** Whether this call's own timeout is what aborted it, rather than the site's signal. */
-    timedOut: () => boolean;
+    /**
+     * Who aborted the call, or null while nothing has. A transport that
+     * rejects once the call is aborted is read by this first, whatever it
+     * rejected with: only the caller knows which of the two aborted it.
+     */
+    abortReason: () => LambderCallAbortReason | null;
     /**
      * The failure to report, or null while the call still stands. Run before
      * handing the request to the transport (a call already abandoned should
@@ -55,8 +68,11 @@ export declare const createCallAbort: (options: {
  * transports a signal has nothing to cancel, and by the crash reporter's
  * time bound (LambderCrashHandling), where the app's report runs on.
  *
- * The listener is detached on either outcome, for the reason createCallAbort
- * detaches its own.
+ * A signal that aborted before the wait began rejects it at once with the
+ * signal's reason, since it fires no event for a listener added afterwards.
+ * `pending` is still attached to either way, so what it later rejects with is
+ * settled here rather than left an unhandled rejection. The listener is
+ * detached on either outcome, for the reason createCallAbort detaches its own.
  */
 export declare const stopWaitingWhenAborted: <T>(pending: Promise<T>, signal: AbortSignal | undefined) => Promise<T>;
 export {};

package/dist/shared/util/LambderCallAbort.js

@@ -9,11 +9,22 @@
  * the two from drifting apart: a caller that believed a late answer would
  * report `ok: true` for a call its site had already abandoned.
  *
+ * Who gave up matters as much as when. A call's own timeout is a failure the
+ * callers report; the site's own signal is the site's choice (a superseded
+ * read, a view that closed), which nothing should report as something gone
+ * wrong, so the two are told apart here, once. A site signal can carry a
+ * deadline of its own, though: AbortSignal.timeout() aborts with a
+ * TimeoutError, alone or inside AbortSignal.any(), and a call it ends is
+ * timed out like one its own timeoutMs ended. Read as the site's choice, it
+ * would fail with nothing reporting it.
+ *
  * The listener on an external signal is removed in detach() rather than left
  * to `once`: a site's signal usually outlives the call (one controller per
  * page, per view, per request), so a listener per call would accumulate on it
  * for as long as the signal lives.
  */
+/** What AbortSignal.timeout() aborts with: a DOMException, which is not an Error everywhere, so it is read by its name. */
+const isTimeoutReason = (reason) => typeof reason === "object" && reason !== null && reason.name === "TimeoutError";
 export const createCallAbort = (options) => {
     const { timeoutMs, signal: external } = options;
     let timedOut = false;
@@ -34,21 +45,32 @@ export const createCallAbort = (options) => {
                 detachExternal = () => external.removeEventListener("abort", forwardAbort);
             }
         }
-        timeoutId = setTimeout(() => { timedOut = true; controller.abort(); }, timeoutMs);
+        timeoutId = setTimeout(() => {
+            // The first abort names the call: a timer that fires after the
+            // site's signal already aborted it finds the call given up on by
+            // the site, and must not report it as a timeout.
+            if (!controller.signal.aborted)
+                timedOut = true;
+            controller.abort();
+        }, timeoutMs);
         signal = controller.signal;
     }
+    // The chained controller aborts with the site signal's own reason, so a
+    // deadline the site set is still readable here.
+    const abortReason = () => !signal?.aborted ? null : timedOut || isTimeoutReason(signal.reason) ? "timeout" : "aborted";
     return {
         signal,
-        timedOut: () => timedOut,
+        abortReason,
         abortFailure: (stage) => {
-            if (!signal?.aborted)
+            const reason = abortReason();
+            if (!reason)
                 return null;
             const detail = stage === "beforeSending"
                 ? "the call was given up on before it was sent"
                 : "the answer arrived too late to be used";
-            return timedOut
-                ? { reason: "timeout", error: new Error(`Request timed out after ${timeoutMs}ms; ${detail}.`) }
-                : { reason: "network", error: new Error(`Request aborted; ${detail}.`) };
+            if (reason === "aborted")
+                return { reason, error: new Error(`Request aborted by its signal; ${detail}.`) };
+            return { reason, error: new Error(timedOut ? `Request timed out after ${timeoutMs}ms; ${detail}.` : `Request timed out by its signal; ${detail}.`) };
         },
         detach: () => {
             if (timeoutId !== undefined)
@@ -66,15 +88,21 @@ export const createCallAbort = (options) => {
  * transports a signal has nothing to cancel, and by the crash reporter's
  * time bound (LambderCrashHandling), where the app's report runs on.
  *
- * The listener is detached on either outcome, for the reason createCallAbort
- * detaches its own.
+ * A signal that aborted before the wait began rejects it at once with the
+ * signal's reason, since it fires no event for a listener added afterwards.
+ * `pending` is still attached to either way, so what it later rejects with is
+ * settled here rather than left an unhandled rejection. The listener is
+ * detached on either outcome, for the reason createCallAbort detaches its own.
  */
 export const stopWaitingWhenAborted = (pending, signal) => {
     if (!signal)
         return pending;
     return new Promise((resolve, reject) => {
         const onAbort = () => reject(signal.reason);
-        signal.addEventListener("abort", onAbort, { once: true });
+        if (signal.aborted)
+            onAbort();
+        else
+            signal.addEventListener("abort", onAbort, { once: true });
         pending.then(resolve, reject).finally(() => signal.removeEventListener("abort", onAbort));
     });
 };

package/dist/shared/util/LambderErrorReportMark.d.ts

@@ -0,0 +1,4 @@
+/** Marks an error as reported where it arose. */
+export declare const markErrorReported: (error: Error) => void;
+/** Whether an error was marked as reported where it arose. Read by brand, so it holds across realms and package copies. */
+export declare const isErrorReported: (error: unknown) => boolean;

package/dist/shared/util/LambderErrorReportMark.js

@@ -0,0 +1,22 @@
+/**
+ * The mark on an error that has already been reported, so the crash
+ * reporting it reaches next does not report it a second time.
+ *
+ * LambderInvokeCaller marks the error of a failure its onFailure handler
+ * took: api() then throws that same error, and an app that lets it propagate
+ * hands it to the instance's crash reporting, which skips a marked error and
+ * still answers it as a crash. The two ends live in invoke/ and core/, which
+ * may not import each other, so the mark sits below both.
+ *
+ * A key from the global symbol registry rather than a WeakSet kept here: a
+ * caller and a server from two copies of the package (an app's and a
+ * dependency's) agree on it, as they do on every Lambder brand. It is set
+ * non-enumerable, so it never shows up in a serialized error or a log line.
+ */
+const LAMBDER_ERROR_REPORTED = Symbol.for("lambder.errorReported");
+/** Marks an error as reported where it arose. */
+export const markErrorReported = (error) => {
+    Object.defineProperty(error, LAMBDER_ERROR_REPORTED, { value: true, configurable: true });
+};
+/** Whether an error was marked as reported where it arose. Read by brand, so it holds across realms and package copies. */
+export const isErrorReported = (error) => typeof error === "object" && error !== null && error[LAMBDER_ERROR_REPORTED] === true;

package/dist/shared/util/LambderKeyFieldDigest.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The digest a caller-controlled field of a store key is written as.
+ *
+ * The rate-limit engine and the idempotency engine each build a store key
+ * around fields only the caller controls: an address, a session key, whatever
+ * a custom rate-limit key returned, a callerIdentity, a posted idempotency
+ * key. Written as they are, a table read shows who called (an email, a device
+ * token, an address), and a long one passes a store's own key limit, which
+ * the store answers by throwing and both engines' failOpen turns into no
+ * limit or no idempotency for that caller. So every such field is written as
+ * a digest of a fixed length, whatever its own, in one implementation the two
+ * engines share: `<kind>:<64 hex>`, with the kind (ip, session, custom, ...)
+ * left readable, as the API and policy names around it are.
+ *
+ * Keyed when the app has an at-rest secret (the session salt): an HMAC under
+ * a subkey derived from it for this one purpose, so a table read alone cannot
+ * test a guess. Derived through HKDF rather than used as it is because the
+ * session store keys its partition hash with the salt itself, and that hash
+ * rides in every session cookie: a sessionKey a user can choose would
+ * otherwise let them read off a cookie the digest of any value they like.
+ * Without a secret the digest is a plain SHA-256, which keeps the values out
+ * of the table but lets a reader test guesses: an email from a list, an IPv4
+ * address from all four billion.
+ */
+export declare class LambderKeyFieldDigest {
+    /** Whether the digest is keyed by the app's at-rest secret, or a plain SHA-256. */
+    readonly isKeyed: boolean;
+    private readonly atRestSecret;
+    private hmacKeyPromise;
+    constructor(atRestSecret: string | null);
+    /**
+     * `value` written as a field of `kind`: `<kind>:<hex>`. The kind is part
+     * of what is digested, so one value under two kinds (a session key
+     * counted by a rate limit and scoping an idempotency record) gives two
+     * unrelated digests, and a table read cannot join the two.
+     *
+     * A runtime without WebCrypto (the mock on a page served over plain http,
+     * a phone on the LAN) writes `<kind>:<value>` instead: the only stores
+     * such a runtime runs over are the mock's memory ones, which nobody reads
+     * at rest and which have no key limit, and a key there is only ever
+     * compared with keys the same runtime wrote.
+     */
+    digestOf(kind: string, value: string): Promise<string>;
+    /** The HMAC key, derived once per instance: HKDF-SHA256 over the secret, with no salt and this purpose as its info. */
+    private hmacKey;
+}

package/dist/shared/util/LambderKeyFieldDigest.js

@@ -0,0 +1,75 @@
+/**
+ * The digest a caller-controlled field of a store key is written as.
+ *
+ * The rate-limit engine and the idempotency engine each build a store key
+ * around fields only the caller controls: an address, a session key, whatever
+ * a custom rate-limit key returned, a callerIdentity, a posted idempotency
+ * key. Written as they are, a table read shows who called (an email, a device
+ * token, an address), and a long one passes a store's own key limit, which
+ * the store answers by throwing and both engines' failOpen turns into no
+ * limit or no idempotency for that caller. So every such field is written as
+ * a digest of a fixed length, whatever its own, in one implementation the two
+ * engines share: `<kind>:<64 hex>`, with the kind (ip, session, custom, ...)
+ * left readable, as the API and policy names around it are.
+ *
+ * Keyed when the app has an at-rest secret (the session salt): an HMAC under
+ * a subkey derived from it for this one purpose, so a table read alone cannot
+ * test a guess. Derived through HKDF rather than used as it is because the
+ * session store keys its partition hash with the salt itself, and that hash
+ * rides in every session cookie: a sessionKey a user can choose would
+ * otherwise let them read off a cookie the digest of any value they like.
+ * Without a secret the digest is a plain SHA-256, which keeps the values out
+ * of the table but lets a reader test guesses: an email from a list, an IPv4
+ * address from all four billion.
+ */
+import { joinKeyFields } from "./joinKeyFields.js";
+import { bytesToHexString, resolveWebCrypto } from "./LambderTextDigest.js";
+/** HKDF's `info`: the purpose the subkey is derived for, so no other derivation from the same secret meets it. */
+const KEY_FIELD_DIGEST_PURPOSE = "lambder/key-field-digest";
+export class LambderKeyFieldDigest {
+    /** Whether the digest is keyed by the app's at-rest secret, or a plain SHA-256. */
+    isKeyed;
+    atRestSecret;
+    hmacKeyPromise;
+    constructor(atRestSecret) {
+        if (atRestSecret !== null && (typeof atRestSecret !== "string" || atRestSecret === "")) {
+            throw new Error("Lambder: the at-rest secret that keys the digest of rate-limit and idempotency keys is empty. Pass the app's real secret (the session salt), or none.");
+        }
+        this.atRestSecret = atRestSecret;
+        this.isKeyed = atRestSecret !== null;
+    }
+    /**
+     * `value` written as a field of `kind`: `<kind>:<hex>`. The kind is part
+     * of what is digested, so one value under two kinds (a session key
+     * counted by a rate limit and scoping an idempotency record) gives two
+     * unrelated digests, and a table read cannot join the two.
+     *
+     * A runtime without WebCrypto (the mock on a page served over plain http,
+     * a phone on the LAN) writes `<kind>:<value>` instead: the only stores
+     * such a runtime runs over are the mock's memory ones, which nobody reads
+     * at rest and which have no key limit, and a key there is only ever
+     * compared with keys the same runtime wrote.
+     */
+    async digestOf(kind, value) {
+        let webCrypto;
+        try {
+            webCrypto = await resolveWebCrypto();
+        }
+        catch {
+            return `${kind}:${value}`;
+        }
+        const message = new TextEncoder().encode(joinKeyFields(kind, value));
+        const digest = this.atRestSecret === null
+            ? await webCrypto.subtle.digest("SHA-256", message)
+            : await webCrypto.subtle.sign("HMAC", await this.hmacKey(webCrypto, this.atRestSecret), message);
+        return `${kind}:${bytesToHexString(new Uint8Array(digest))}`;
+    }
+    /** The HMAC key, derived once per instance: HKDF-SHA256 over the secret, with no salt and this purpose as its info. */
+    hmacKey(webCrypto, atRestSecret) {
+        this.hmacKeyPromise ??= (async () => {
+            const secretKey = await webCrypto.subtle.importKey("raw", new TextEncoder().encode(atRestSecret), "HKDF", false, ["deriveKey"]);
+            return await webCrypto.subtle.deriveKey({ name: "HKDF", hash: "SHA-256", salt: new Uint8Array(0), info: new TextEncoder().encode(KEY_FIELD_DIGEST_PURPOSE) }, secretKey, { name: "HMAC", hash: "SHA-256", length: 256 }, false, ["sign"]);
+        })();
+        return this.hmacKeyPromise;
+    }
+}

package/dist/shared/util/LambderSignedClaims.d.ts

@@ -75,4 +75,23 @@ export declare const keyedDigest: (secret: string, value: string) => Promise<str
  * without one is told so.
  */
 export declare const randomSecret: (bytes?: number) => string;
+/**
+ * The characters of an alphabet a code is drawn from, as code points, once
+ * they are 2 to 256 distinct ones; anything else throws, naming `name`. One
+ * character draws nothing random, a repeat weighs its character double, and
+ * past 256 the one byte randomCode draws per character cannot reach every
+ * character. Returns the characters so the check reads as an assignment.
+ */
+export declare const assertCodeAlphabet: (alphabet: unknown, name: string) => string[];
+/**
+ * A code of `length` characters drawn uniformly from `alphabet` with the
+ * runtime's cryptographic random source: the digits emailed to an address,
+ * the letters of a pairing code somebody types. One byte draws one
+ * character, and a byte at or above the largest multiple of the alphabet's
+ * size is discarded and drawn again, since `byte % alphabet.length` alone
+ * favours the alphabet's first characters. The alphabet is 2 to 256 distinct
+ * characters (code points) and `length` a positive integer; anything else
+ * throws. Synchronous, as randomSecret is.
+ */
+export declare const randomCode: (alphabet: string, length: number) => string;
 export {};

package/dist/shared/util/LambderSignedClaims.js

@@ -1,5 +1,6 @@
 import { base64UrlToBytes, bytesToBase64Url, isBase64Url } from "./LambderBase64.js";
 import { hmacSha256Of, importHmacKey, resolveWebCrypto } from "./LambderTextDigest.js";
+import { assertPositiveInteger } from "./LambderOptionChecks.js";
 /**
  * One kind of signed token: constructed once with its secret, version and
  * claims schema, it keeps the imported HMAC key and answers `sign` and
@@ -107,3 +108,56 @@ export const randomSecret = (bytes = 32) => {
     }
     return bytesToBase64Url(webCrypto.getRandomValues(new Uint8Array(bytes)));
 };
+/** The most bytes one getRandomValues call fills. */
+const MAX_RANDOM_BYTES_PER_CALL = 65536;
+/**
+ * The characters of an alphabet a code is drawn from, as code points, once
+ * they are 2 to 256 distinct ones; anything else throws, naming `name`. One
+ * character draws nothing random, a repeat weighs its character double, and
+ * past 256 the one byte randomCode draws per character cannot reach every
+ * character. Returns the characters so the check reads as an assignment.
+ */
+export const assertCodeAlphabet = (alphabet, name) => {
+    const characters = typeof alphabet === "string" ? Array.from(alphabet) : [];
+    const distinct = new Set(characters).size;
+    if (characters.length < 2 || characters.length > 256 || distinct !== characters.length) {
+        const found = typeof alphabet === "string" ? `${characters.length} characters, ${distinct} of them distinct` : typeof alphabet;
+        throw new Error(`Lambder: ${name} must be 2 to 256 distinct characters, got ${found}.`);
+    }
+    return characters;
+};
+/**
+ * A code of `length` characters drawn uniformly from `alphabet` with the
+ * runtime's cryptographic random source: the digits emailed to an address,
+ * the letters of a pairing code somebody types. One byte draws one
+ * character, and a byte at or above the largest multiple of the alphabet's
+ * size is discarded and drawn again, since `byte % alphabet.length` alone
+ * favours the alphabet's first characters. The alphabet is 2 to 256 distinct
+ * characters (code points) and `length` a positive integer; anything else
+ * throws. Synchronous, as randomSecret is.
+ */
+export const randomCode = (alphabet, length) => {
+    const characters = assertCodeAlphabet(alphabet, "randomCode alphabet");
+    assertPositiveInteger(length, "randomCode 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 / characters.length) * characters.length;
+    const drawn = [];
+    // Twice the length lets one call cover the discarded bytes nearly
+    // always; an alphabet that discards close to half of them may need
+    // another, which the loop draws.
+    const buffer = new Uint8Array(Math.min(length * 2, MAX_RANDOM_BYTES_PER_CALL));
+    while (drawn.length < length) {
+        webCrypto.getRandomValues(buffer);
+        for (const byte of buffer) {
+            if (byte >= ceiling)
+                continue;
+            drawn.push(characters[byte % characters.length]);
+            if (drawn.length === length)
+                break;
+        }
+    }
+    return drawn.join("");
+};

package/dist/shared/util/LambderSwappableInstances.d.ts

@@ -0,0 +1,29 @@
+/** A registered instance as the test kit reaches it. */
+export type LambderSwappableInstance = {
+    readonly instance: object;
+    /**
+     * Calls the instance's swap door with the twins the test kit offers. The
+     * door picks the one its class needs, so this list need not know what
+     * each instance is.
+     */
+    swapIn(twins: unknown): void;
+};
+/**
+ * Registers an instance `lambder/testing` puts a memory twin under, from the
+ * end of its constructor: the swap door keyed LAMBDER_BACKEND_SWAP must work
+ * by then, since a test app already in charge swaps it on the spot.
+ */
+export declare const registerSwappableInstance: (instance: object) => void;
+/** Every registered instance still alive, in the order they were constructed. */
+export declare const liveSwappableInstances: () => LambderSwappableInstance[];
+/** Hands every instance registered from now on to the watcher, in place of any earlier one. */
+export declare const watchSwappableInstances: (watcher: (instance: LambderSwappableInstance) => void) => void;
+/**
+ * Makes every member named answer from the twin, in place: an own property of
+ * the instance, bound to the twin, over the class's method. Whatever holds the
+ * instance (a module-level constant, a class built over it) reaches the twin
+ * on its next call without being told, and a second twin replaces the first.
+ * The members are a record over the interface's keys, so an interface that
+ * grows a method fails to compile until its stores' doors hand it over too.
+ */
+export declare const delegateToTwin: <TInterface extends object>(instance: TInterface, twin: TInterface, members: { readonly [TMember in keyof TInterface]-?: true; }) => void;

package/dist/shared/util/LambderSwappableInstances.js

@@ -0,0 +1,54 @@
+import { LAMBDER_BACKEND_SWAP } from "./LambderTestingDoors.js";
+const REGISTRY_KEY = Symbol.for("lambder.swappableInstances");
+const MIN_SWEEP_AT = 64;
+/** Created on first use rather than when the module loads, so importing it does nothing. */
+const registry = () => {
+    const holder = globalThis;
+    return holder[REGISTRY_KEY] ??= { entries: [], sweepAt: MIN_SWEEP_AT, watcher: null };
+};
+const handleOf = (instance, door) => ({
+    instance,
+    swapIn: (twins) => instance[door](twins),
+});
+/**
+ * Registers an instance `lambder/testing` puts a memory twin under, from the
+ * end of its constructor: the swap door keyed LAMBDER_BACKEND_SWAP must work
+ * by then, since a test app already in charge swaps it on the spot.
+ */
+export const registerSwappableInstance = (instance) => {
+    const state = registry();
+    state.entries.push({ ref: new WeakRef(instance), door: LAMBDER_BACKEND_SWAP });
+    if (state.entries.length >= state.sweepAt) {
+        state.entries = state.entries.filter((entry) => entry.ref.deref() !== undefined);
+        state.sweepAt = Math.max(MIN_SWEEP_AT, state.entries.length * 2);
+    }
+    state.watcher?.(handleOf(instance, LAMBDER_BACKEND_SWAP));
+};
+/** Every registered instance still alive, in the order they were constructed. */
+export const liveSwappableInstances = () => {
+    const handles = [];
+    for (const entry of registry().entries) {
+        const instance = entry.ref.deref();
+        if (instance !== undefined)
+            handles.push(handleOf(instance, entry.door));
+    }
+    return handles;
+};
+/** Hands every instance registered from now on to the watcher, in place of any earlier one. */
+export const watchSwappableInstances = (watcher) => {
+    registry().watcher = watcher;
+};
+/**
+ * Makes every member named answer from the twin, in place: an own property of
+ * the instance, bound to the twin, over the class's method. Whatever holds the
+ * instance (a module-level constant, a class built over it) reaches the twin
+ * on its next call without being told, and a second twin replaces the first.
+ * The members are a record over the interface's keys, so an interface that
+ * grows a method fails to compile until its stores' doors hand it over too.
+ */
+export const delegateToTwin = (instance, twin, members) => {
+    for (const member of Object.keys(members)) {
+        const method = twin[member];
+        Object.defineProperty(instance, member, { value: method.bind(twin), configurable: true, writable: true });
+    }
+};

package/dist/shared/util/LambderTestingDoors.d.ts

@@ -1,5 +1,6 @@
 /**
- * The keys of the two doors `lambder/testing` opens on a built instance.
+ * The keys of the two doors `lambder/testing` opens on a built instance, the
+ * first of which it also opens on the classes an app builds beside it.
  *
  * Symbols rather than named methods, and exported by no entry point: the
  * package's exports map is what a consumer can import, so only
@@ -14,7 +15,10 @@
  * other stores: the copy's closures would still reach the original and the
  * production table under it. The stores are therefore replaced in place, and
  * every class that holds one answers to this key with a method that takes the
- * replacement.
+ * replacement. A class an app builds itself, beside the instance (a cache, an
+ * upload bucket, an invoke caller), registers as it is constructed (see
+ * LambderSwappableInstances) and answers to this key with a method that puts
+ * a memory twin, or a mock app, under itself in place.
  */
 export declare const LAMBDER_BACKEND_SWAP: unique symbol;
 /**

package/dist/shared/util/LambderTestingDoors.js

@@ -1,5 +1,6 @@
 /**
- * The keys of the two doors `lambder/testing` opens on a built instance.
+ * The keys of the two doors `lambder/testing` opens on a built instance, the
+ * first of which it also opens on the classes an app builds beside it.
  *
  * Symbols rather than named methods, and exported by no entry point: the
  * package's exports map is what a consumer can import, so only
@@ -14,7 +15,10 @@
  * other stores: the copy's closures would still reach the original and the
  * production table under it. The stores are therefore replaced in place, and
  * every class that holds one answers to this key with a method that takes the
- * replacement.
+ * replacement. A class an app builds itself, beside the instance (a cache, an
+ * upload bucket, an invoke caller), registers as it is constructed (see
+ * LambderSwappableInstances) and answers to this key with a method that puts
+ * a memory twin, or a mock app, under itself in place.
  */
 export const LAMBDER_BACKEND_SWAP = Symbol("lambder.backendSwap");
 /**

package/dist/shared/util/LambderTextDigest.d.ts

@@ -1,11 +1,11 @@
 /**
  * SHA-256 and HMAC-SHA256 through WebCrypto: the digests every layer shares.
  * The session crypto hashes bearer secrets with the first and partitions
- * session keys with the second, the rate-limit engine folds an over-long
- * tracker key, signed claims and keyed digests are HMACs under an app's
- * secret, so every key space is built from the same primitives on every
- * runtime (browsers on a secure context, Node 20+, edge runtimes); an
- * upload's checksum is the same digest over the file's bytes.
+ * session keys with the second, the policy engines digest the caller's
+ * fields of their store keys, signed claims and keyed digests are HMACs
+ * under an app's secret, so every key space is built from the same
+ * primitives on every runtime (browsers on a secure context, Node 20+, edge
+ * runtimes); an upload's checksum is the same digest over the file's bytes.
  */
 /** Lowercase hex of a byte array, two characters per byte. */
 export declare const bytesToHexString: (bytes: Uint8Array) => string;

package/dist/shared/util/LambderTextDigest.js

@@ -3,11 +3,11 @@ import { getCrypto } from "./LambderNodeModules.js";
 /**
  * SHA-256 and HMAC-SHA256 through WebCrypto: the digests every layer shares.
  * The session crypto hashes bearer secrets with the first and partitions
- * session keys with the second, the rate-limit engine folds an over-long
- * tracker key, signed claims and keyed digests are HMACs under an app's
- * secret, so every key space is built from the same primitives on every
- * runtime (browsers on a secure context, Node 20+, edge runtimes); an
- * upload's checksum is the same digest over the file's bytes.
+ * session keys with the second, the policy engines digest the caller's
+ * fields of their store keys, signed claims and keyed digests are HMACs
+ * under an app's secret, so every key space is built from the same
+ * primitives on every runtime (browsers on a secure context, Node 20+, edge
+ * runtimes); an upload's checksum is the same digest over the file's bytes.
  */
 /** Lowercase hex of a byte array, two characters per byte. */
 export const bytesToHexString = (bytes) => Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");