lambder 8.1.2 → 8.3.1

package/dist/secrets/LambderOneShotSecrets.js

@@ -0,0 +1,217 @@
+import { keyedDigest, randomSecret } from "../shared/util/LambderSignedClaims.js";
+import { constantTimeEquals } from "../shared/util/LambderTextDigest.js";
+import { assertPositiveInteger } from "../shared/util/LambderOptionChecks.js";
+import { joinKeyFields } from "../shared/util/joinKeyFields.js";
+const DIGITS = "0123456789";
+/**
+ * How many secrets an issue draws before giving up on a digest another scope
+ * holds. A random token never meets one; a short code drawn from a small
+ * space with many out at once can, and five taken in a row means the space is
+ * too small for the codes out, which is a configuration to change rather than
+ * a draw to repeat.
+ */
+const MAX_DRAWS = 5;
+/**
+ * Codes and tokens an app hands out once and takes back once, over a store
+ * that settles their races.
+ *
+ * ```ts
+ * const secrets = new LambderOneShotSecrets({
+ *     store: new LambderDdbOneShotSecretStore({ tableName: "app-policies" }),
+ *     secret: ONE_SHOT_SECRET,
+ *     kinds: {
+ *         emailCode: { shape: "code", length: 6, ttlSeconds: 600, maxAttempts: 5 },
+ *         activationLink: { shape: "token", ttlSeconds: 48 * 3600 },
+ *     },
+ * });
+ *
+ * const issued = await secrets.issue("emailCode", `register:${email}`, { cooldownSeconds: 30 });
+ * if(issued.issued) await sendEmail(email, issued.plaintext);
+ *
+ * const redeemed = await secrets.redeem("emailCode", `register:${email}`, typedCode);
+ * if(redeemed.state !== "accepted") refuse(...);
+ * ```
+ *
+ * The store holds digests only, keyed under the app's secret with the kind
+ * and the scope folded in: a code issued to two scopes never collides, and a
+ * code cannot be replayed against another kind or scope. The plaintext leaves
+ * once, from `issue`; nothing here logs it or stores it.
+ */
+export class LambderOneShotSecrets {
+    store;
+    secret;
+    kinds;
+    now;
+    constructor(options) {
+        if (typeof options.secret !== "string" || options.secret.length === 0)
+            throw new Error("Lambder: LambderOneShotSecrets needs a secret to key its digests with.");
+        const names = Object.keys(options.kinds);
+        if (names.length === 0)
+            throw new Error("Lambder: LambderOneShotSecrets was given no kinds; declare the kinds of secret the app hands out.");
+        for (const name of names) {
+            const kind = options.kinds[name];
+            assertPositiveInteger(kind.ttlSeconds, `kinds.${name}.ttlSeconds`);
+            if (kind.shape === "code") {
+                assertPositiveInteger(kind.length, `kinds.${name}.length`);
+                assertPositiveInteger(kind.maxAttempts, `kinds.${name}.maxAttempts`);
+                assertAlphabet(kind.alphabet ?? DIGITS, name);
+            }
+            else if (kind.shape === "token") {
+                if (kind.alphabet !== undefined || kind.length !== undefined) {
+                    assertPositiveInteger(kind.length, `kinds.${name}.length`);
+                    assertAlphabet(kind.alphabet ?? "", name);
+                }
+                else {
+                    assertPositiveInteger(kind.bytes ?? 32, `kinds.${name}.bytes`);
+                }
+            }
+            else {
+                throw new Error(`Lambder: kinds.${name}.shape must be "code" or "token", got ${JSON.stringify(kind.shape)}.`);
+            }
+        }
+        this.store = options.store;
+        this.secret = options.secret;
+        this.kinds = options.kinds;
+        this.now = options.now ?? (() => Date.now());
+    }
+    nowSeconds() { return Math.floor(this.now() / 1000); }
+    kindOf(name) {
+        const kind = Object.prototype.hasOwnProperty.call(this.kinds, name) ? this.kinds[name] : undefined;
+        if (!kind)
+            throw new Error(`Lambder: LambderOneShotSecrets knows no kind "${name}".`);
+        return kind;
+    }
+    /**
+     * The digest a secret rests as. A code's carries its kind and scope, so
+     * the same code issued to two scopes never collides and a code cannot be
+     * replayed against another; a token's carries its kind, since a token is
+     * found by its digest alone, so two scopes can draw the same one, and the
+     * store's claim on the digest at issue is what keeps them apart. The
+     * fields are joined escaped, so no two distinct field lists produce one
+     * string.
+     */
+    digestOf(kind, scope, plaintext) {
+        return keyedDigest(this.secret, scope === null ? joinKeyFields("token", kind, plaintext) : joinKeyFields("code", kind, scope, plaintext));
+    }
+    /**
+     * Mints one secret for the scope, retiring whatever the scope held, and
+     * answers the plaintext: the one time it exists outside the caller's
+     * hands. With `cooldownSeconds`, a scope whose current secret was issued
+     * less than that ago is refused instead, with the second it may ask
+     * again; of two callers racing past the cooldown, exactly one is issued.
+     * `meta` is what the app wants back at redemption: an identity, an
+     * issuing organization, as small strings.
+     *
+     * A secret whose digest another scope holds is drawn again, up to
+     * MAX_DRAWS times; past that the kind's alphabet and length leave too few
+     * secrets for the ones out at once, and the issue throws.
+     */
+    async issue(kind, scope, options = {}) {
+        const definition = this.kindOf(kind);
+        const cooldown = options.cooldownSeconds === undefined ? undefined : assertPositiveInteger(options.cooldownSeconds, "cooldownSeconds");
+        const nowSeconds = this.nowSeconds();
+        for (let draw = 0; draw < MAX_DRAWS; draw += 1) {
+            const plaintext = definition.shape === "code" ? drawCode(definition.alphabet ?? DIGITS, definition.length)
+                : definition.alphabet !== undefined ? drawCode(definition.alphabet, definition.length)
+                    : randomSecret(definition.bytes ?? 32);
+            const draft = {
+                kind,
+                scope,
+                shape: definition.shape,
+                digest: await this.digestOf(kind, definition.shape === "code" ? scope : null, plaintext),
+                issuedAt: nowSeconds,
+                expiresAt: nowSeconds + definition.ttlSeconds,
+                meta: { ...(options.meta ?? {}) },
+            };
+            const outcome = await this.store.issue(draft, { unlessIssuedAfter: cooldown === undefined ? undefined : nowSeconds - cooldown });
+            if (outcome.issued)
+                return { issued: true, plaintext, expiresAt: draft.expiresAt };
+            if (outcome.refused === "cooldown")
+                return { issued: false, refused: "cooldown", retryAt: outcome.issuedAt + (cooldown ?? 0) };
+        }
+        throw new Error(`Lambder: kind "${kind}" drew ${MAX_DRAWS} secrets in a row whose digest another scope holds; its alphabet and length leave too few for the ones out at once.`);
+    }
+    /**
+     * Redeems a code for its scope. The try is counted before the code is
+     * looked at, in the write that reads the digest, so tries sent together
+     * are all counted; a right code past the ceiling is refused as exhausted.
+     * An accepted code is spent in the same call, exactly once.
+     */
+    async redeem(kind, scope, candidate) {
+        const definition = this.kindOf(kind);
+        if (definition.shape !== "code")
+            throw new Error(`Lambder: kind "${kind}" is a token, redeemed by value with redeemToken().`);
+        const current = await this.store.findByScope(scope);
+        if (!current || current.kind !== kind)
+            return { state: "none" };
+        if (current.expiresAt <= this.nowSeconds())
+            return { state: "expired" };
+        if (current.attempts >= definition.maxAttempts)
+            return { state: "exhausted" };
+        const counted = await this.store.attempt(scope, current.id);
+        if (!counted)
+            return { state: "none" };
+        // Counted already, so this is the count with the try being made now.
+        if (counted.attempts > definition.maxAttempts)
+            return { state: "exhausted" };
+        if (!constantTimeEquals(counted.digest, await this.digestOf(kind, scope, candidate))) {
+            return { state: "wrong", attemptsLeft: Math.max(0, definition.maxAttempts - counted.attempts) };
+        }
+        return await this.accept(counted);
+    }
+    /** Redeems a token by its value: found by its digest, spent exactly once. A token of another kind, or none, is "none". */
+    async redeemToken(kind, candidate) {
+        const definition = this.kindOf(kind);
+        if (definition.shape !== "token")
+            throw new Error(`Lambder: kind "${kind}" is a code, redeemed with its scope through redeem().`);
+        // A token is 43 characters for 32 bytes; anything far past that is not one, and is not worth a digest.
+        if (candidate.length === 0 || candidate.length > 512)
+            return { state: "none" };
+        const current = await this.store.findByDigest(await this.digestOf(kind, null, candidate));
+        if (!current || current.kind !== kind)
+            return { state: "none" };
+        if (current.expiresAt <= this.nowSeconds())
+            return { state: "expired" };
+        return await this.accept(current);
+    }
+    /** Ends whatever the scope holds: after the thing it proved is settled another way, or when what was sent never arrived. */
+    async retire(scope) {
+        await this.store.retire(scope);
+    }
+    /** Spends the record; a redemption racing this one and winning makes it "none". */
+    async accept(record) {
+        if (!(await this.store.consume(record.scope, record.id)))
+            return { state: "none" };
+        return { state: "accepted", scope: record.scope, meta: { ...record.meta }, issuedAt: record.issuedAt };
+    }
+}
+const assertAlphabet = (alphabet, name) => {
+    if (alphabet.length < 2 || alphabet.length > 256 || new Set(alphabet).size !== alphabet.length) {
+        throw new Error(`Lambder: kinds.${name}.alphabet must be 2 to 256 distinct characters.`);
+    }
+};
+/**
+ * A code of `length` characters drawn uniformly from `alphabet`. Bytes at or
+ * above the largest multiple of the alphabet's size are discarded, so the
+ * modulo cannot favour the alphabet's first characters.
+ */
+const drawCode = (alphabet, length) => {
+    const webCrypto = globalThis.crypto;
+    if (typeof webCrypto?.getRandomValues !== "function") {
+        throw new Error("Lambder needs crypto.getRandomValues in this runtime to draw a code. Every browser provides it; Node 20+ provides it as globalThis.crypto.");
+    }
+    const ceiling = Math.floor(256 / alphabet.length) * alphabet.length;
+    const characters = [];
+    const buffer = new Uint8Array(length * 2);
+    while (characters.length < length) {
+        webCrypto.getRandomValues(buffer);
+        for (const byte of buffer) {
+            if (byte >= ceiling)
+                continue;
+            characters.push(alphabet[byte % alphabet.length]);
+            if (characters.length === length)
+                break;
+        }
+    }
+    return characters.join("");
+};

package/dist/session/LambderSessionCrypto.js

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

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

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

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

@@ -0,0 +1,122 @@
+/**
+ * The one-shot secret vocabulary: what a store holds of a secret, and the six
+ * methods LambderOneShotSecrets asks of it. Kept apart from the class, like
+ * every store interface here: a store implements this and nothing else, and
+ * depends on nothing.
+ *
+ * A record is the digest of a secret and the facts around it, never the
+ * secret itself. One record is live per scope: issuing a new one retires
+ * whatever the scope held, in the same act. A record stops being live when it
+ * is consumed, replaced, or retired; an expired record is still handed back,
+ * because the class answers "expired" from it rather than "none", for as long
+ * as the store's own housekeeping keeps it.
+ *
+ * Every race a one-shot secret meets is settled here, once, and the
+ * conformance suite `lambder/testing` exports
+ * (lambderOneShotSecretStoreConformance) asserts each, against Lambder's
+ * stores and against an app's own:
+ *
+ * - `issue` writes the new record and retires the old in one act, and a
+ *   cooldown is a condition on that same write, so of two callers asking at
+ *   once exactly one is answered with a secret and the other with the moment
+ *   it may ask again.
+ * - `issue` claims a token's digest in that same act. A token is found by its
+ *   digest alone, so two scopes that drew the same token (a short code typed
+ *   by hand, with many out at once) would otherwise share one digest, and the
+ *   holder of one would redeem the other's. The claim is refused while
+ *   another scope's record holds the digest, and the class draws again.
+ * - `attempt` counts the try in the same act that reads the digest, so tries
+ *   sent together are all counted; counted afterwards, they would all read
+ *   the same count and a ceiling of five would be as many as a caller cared
+ *   to send at once.
+ * - `consume` is conditional on the record still being the one the caller
+ *   read, so of two redemptions of one secret exactly one is accepted.
+ *
+ * `attempt` and `consume` name a record by its scope and its id together,
+ * and a record of another scope is not the one named, whatever its id.
+ */
+/** What a store holds of one secret: its digest and the facts around it, never the secret. */
+export type LambderOneShotSecretRecord = {
+    /** The store's own identity for this record, what attempt() and consume() name so a record replaced meanwhile is not the one acted on. */
+    id: string;
+    /** Which kind of secret, in the app's vocabulary. */
+    kind: string;
+    /** What the secret proves, in the app's words: an address for a purpose, a recipient, a device. */
+    scope: string;
+    /** The keyed digest of the secret, as the class computes it. */
+    digest: string;
+    /** Epoch seconds. */
+    issuedAt: number;
+    /** Epoch seconds; the store's TTL where it has one. */
+    expiresAt: number;
+    /** Tries made against the record so far. */
+    attempts: number;
+    /** What the app asked to have back at redemption: small strings only. */
+    meta: Record<string, string>;
+};
+/**
+ * How a secret is redeemed, which is what a store needs to know of it at
+ * issue: a code with its scope (its digest carries the scope, so no other
+ * scope can hold it), a token by its value alone (so its digest is claimed).
+ */
+export type LambderOneShotSecretShape = "code" | "token";
+/** A record as the class writes it: everything but what the store assigns, and how it is redeemed. */
+export type LambderOneShotSecretDraft = Omit<LambderOneShotSecretRecord, "id" | "attempts"> & {
+    shape: LambderOneShotSecretShape;
+};
+export type LambderOneShotIssueOutcome = {
+    issued: true;
+    id: string;
+}
+/** Refused by the cooldown: the scope's record was issued after the second named, at `issuedAt`. Nothing was written. */
+ | {
+    issued: false;
+    refused: "cooldown";
+    issuedAt: number;
+}
+/** Refused because another scope's record holds this digest. Nothing was written; the class draws another secret. */
+ | {
+    issued: false;
+    refused: "digestTaken";
+};
+export interface LambderOneShotSecretStore {
+    /**
+     * Stores `draft` as the scope's one live record, retiring whatever the
+     * scope held, in one act. With `unlessIssuedAfter` (epoch seconds), the
+     * write is refused when the scope's current record was issued after that
+     * second, and the refusal carries when it was issued; of two callers
+     * racing past a cooldown, exactly one is issued.
+     *
+     * For a token, the same act claims the digest: refused as `digestTaken`,
+     * writing nothing, while a record of another scope holds it, so of two
+     * scopes racing for one digest exactly one is issued. A store may be
+     * stricter than that and refuse a digest no live record holds (one it
+     * has not cleaned up yet, or one its history of spent secrets already
+     * has, a code's included); the class draws again either way.
+     */
+    issue(draft: LambderOneShotSecretDraft, options: {
+        unlessIssuedAfter?: number;
+    }): Promise<LambderOneShotIssueOutcome>;
+    /** The scope's current record, expired or not, or null once it is consumed, retired, or gone. */
+    findByScope(scope: string): Promise<LambderOneShotSecretRecord | null>;
+    /**
+     * The current record holding this digest, or null: a digest of a record
+     * that was replaced finds nothing. Asked only for a token; a store need
+     * not find a code by its digest.
+     */
+    findByDigest(digest: string): Promise<LambderOneShotSecretRecord | null>;
+    /**
+     * Counts one try against the record, in the act that reads it: the
+     * record with the try already counted, or null when the scope's current
+     * record is no longer the one named (consumed, replaced, retired).
+     *
+     * Only a code is tried against its scope; a token is redeemed by value.
+     * A store that holds token kinds alone is never asked, and may keep no
+     * count of tries at all.
+     */
+    attempt(scope: string, id: string): Promise<LambderOneShotSecretRecord | null>;
+    /** Ends the record named, so it is found no more; false when it is no longer the scope's current record, another consume included. */
+    consume(scope: string, id: string): Promise<boolean>;
+    /** Ends the scope's current record, whatever it is. */
+    retire(scope: string): Promise<void>;
+}

package/dist/shared/contracts/LambderOneShotSecretStore.js

@@ -0,0 +1,38 @@
+/**
+ * The one-shot secret vocabulary: what a store holds of a secret, and the six
+ * methods LambderOneShotSecrets asks of it. Kept apart from the class, like
+ * every store interface here: a store implements this and nothing else, and
+ * depends on nothing.
+ *
+ * A record is the digest of a secret and the facts around it, never the
+ * secret itself. One record is live per scope: issuing a new one retires
+ * whatever the scope held, in the same act. A record stops being live when it
+ * is consumed, replaced, or retired; an expired record is still handed back,
+ * because the class answers "expired" from it rather than "none", for as long
+ * as the store's own housekeeping keeps it.
+ *
+ * Every race a one-shot secret meets is settled here, once, and the
+ * conformance suite `lambder/testing` exports
+ * (lambderOneShotSecretStoreConformance) asserts each, against Lambder's
+ * stores and against an app's own:
+ *
+ * - `issue` writes the new record and retires the old in one act, and a
+ *   cooldown is a condition on that same write, so of two callers asking at
+ *   once exactly one is answered with a secret and the other with the moment
+ *   it may ask again.
+ * - `issue` claims a token's digest in that same act. A token is found by its
+ *   digest alone, so two scopes that drew the same token (a short code typed
+ *   by hand, with many out at once) would otherwise share one digest, and the
+ *   holder of one would redeem the other's. The claim is refused while
+ *   another scope's record holds the digest, and the class draws again.
+ * - `attempt` counts the try in the same act that reads the digest, so tries
+ *   sent together are all counted; counted afterwards, they would all read
+ *   the same count and a ceiling of five would be as many as a caller cared
+ *   to send at once.
+ * - `consume` is conditional on the record still being the one the caller
+ *   read, so of two redemptions of one secret exactly one is accepted.
+ *
+ * `attempt` and `consume` name a record by its scope and its id together,
+ * and a record of another scope is not the one named, whatever its id.
+ */
+export {};

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

@@ -0,0 +1,82 @@
+/**
+ * One pending wait at a time, where each retry after a failure waits longer
+ * than the one before it.
+ *
+ * Most things that retry also wait for other reasons (a refresh cadence, a
+ * pause before recreating something), and those waits must never stack with a
+ * retry. So the timer holds exactly one wait of either kind: `retry` and
+ * `wait` climb the ladder, `after` waits a fixed time without climbing it, and
+ * scheduling any of them replaces whatever was waiting. A caller says what to
+ * run and when it worked, and never keeps a handle and a counter of its own.
+ *
+ * The ladder: a retry waits the base plus a share of a ceiling that grows by
+ * `factor` with every failed attempt, the whole never past `maxMs`. With full
+ * jitter (the default) the share is random, so anything many clients fail at
+ * together (a deploy dropping every socket, a power cut bringing every screen
+ * in a building up at once) is retried across the whole window instead of in
+ * step, which is what keeps the herd off the server.
+ *
+ * Runs wherever setTimeout does: a browser, a Worker, Node. The upload runner
+ * waits on one between tries at storage, and an app's reconnecting client or
+ * self-healing screen holds one of its own.
+ */
+export type LambderBackoffTimerOptions = {
+    /**
+     * The shortest retry wait, in milliseconds. The first after a reset falls
+     * between it and twice it (exactly twice with `jitter: "none"`), so even
+     * the first retries of many clients spread out. Default: 1000.
+     */
+    baseMs?: number;
+    /**
+     * The longest any retry wait is, in milliseconds, however many attempts
+     * have failed; at least `baseMs`. Default: 60000, or `baseMs` when that is
+     * longer.
+     */
+    maxMs?: number;
+    /** How much the ceiling grows with each failed attempt. Default: 2. */
+    factor?: number;
+    /**
+     * "full" (the default): the base plus a random share of the ceiling, which
+     * spreads a herd out. "none": the base plus the whole ceiling, a
+     * predictable ladder for a caller that is alone.
+     */
+    jitter?: "full" | "none";
+};
+export declare class LambderBackoffTimer {
+    private readonly baseMs;
+    private readonly maxMs;
+    private readonly factor;
+    private readonly jitter;
+    private attempts;
+    private timer;
+    /** Settles the promise of a `wait` that cancel() or a replacement drops, so no `await` is left hanging. */
+    private dropPending;
+    constructor(options?: LambderBackoffTimerOptions);
+    /** True while a wait of any kind is pending. False again by the time it runs. */
+    get pending(): boolean;
+    /**
+     * Runs `run` after the next rung of the ladder, counting one more failed
+     * attempt. Replaces whatever was waiting.
+     */
+    retry(run: () => void): void;
+    /**
+     * Resolves after the next rung of the ladder, counting one more failed
+     * attempt: 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.
+     */
+    wait(signal?: AbortSignal): Promise<void>;
+    /**
+     * Runs `run` after a fixed wait, off the ladder: nothing failed, so nothing
+     * climbs. Replaces whatever was waiting.
+     */
+    after(delayMs: number, run: () => void): void;
+    /** The attempt worked: the next failure waits the shortest time again. A pending wait is left alone. */
+    reset(): void;
+    /** Drops the pending wait (the caller is trying right now, or going away), keeping the count. */
+    cancel(): void;
+    /** The next wait on the ladder, in milliseconds, counting one more failed attempt. */
+    private nextRung;
+    private schedule;
+}

package/dist/shared/util/LambderBackoffTimer.js

@@ -0,0 +1,86 @@
+import { assertNumberAtLeast } from "./LambderOptionChecks.js";
+export class LambderBackoffTimer {
+    baseMs;
+    maxMs;
+    factor;
+    jitter;
+    attempts = 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");
+        this.maxMs = assertNumberAtLeast(options.maxMs ?? Math.max(60_000, this.baseMs), this.baseMs, "maxMs");
+        this.factor = assertNumberAtLeast(options.factor ?? 2, 1, "factor");
+        this.jitter = options.jitter ?? "full";
+    }
+    /** 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.
+     */
+    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.
+     * 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.
+     */
+    wait(signal) {
+        return new Promise((resolve, reject) => {
+            if (signal?.aborted)
+                return reject(abortReasonOf(signal));
+            const onAbort = () => this.cancel();
+            const settle = (outcome) => {
+                signal?.removeEventListener("abort", onAbort);
+                outcome();
+            };
+            this.schedule(this.nextRung(), () => settle(resolve), () => settle(() => reject(signal?.aborted ? abortReasonOf(signal) : new Error("LambderBackoffTimer: the wait was dropped by cancel() or by a later wait before it ran."))));
+            signal?.addEventListener("abort", onAbort, { once: true });
+        });
+    }
+    /**
+     * Runs `run` after a fixed wait, off the ladder: nothing failed, so nothing
+     * climbs. Replaces whatever was waiting.
+     */
+    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. */
+    reset() {
+        this.attempts = 0;
+    }
+    /** Drops the pending wait (the caller is trying right now, or going away), keeping the count. */
+    cancel() {
+        if (this.timer === null)
+            return;
+        clearTimeout(this.timer);
+        this.timer = null;
+        const drop = this.dropPending;
+        this.dropPending = null;
+        drop?.();
+    }
+    /** The next wait on the ladder, in milliseconds, counting one more failed attempt. */
+    nextRung() {
+        const ceiling = Math.min(this.baseMs * this.factor ** this.attempts, this.maxMs - this.baseMs);
+        this.attempts += 1;
+        return this.baseMs + (this.jitter === "full" ? Math.random() : 1) * ceiling;
+    }
+    schedule(delayMs, run, drop) {
+        this.cancel();
+        this.dropPending = drop;
+        this.timer = setTimeout(() => {
+            this.timer = null;
+            this.dropPending = null;
+            run();
+        }, delayMs);
+    }
+}
+/** What an aborted signal carries, or an Error for a runtime whose signals carry nothing. */
+const abortReasonOf = (signal) => signal.reason ?? new Error("LambderBackoffTimer: the wait was aborted.");

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

@@ -8,3 +8,17 @@ export declare const bytesToBase64: (bytes: Uint8Array) => string;
 export declare const base64ToBytes: (base64: string) => Uint8Array;
 /** The base64 of UTF-8 text back to the text. */
 export declare const base64ToText: (base64: string) => string;
+/**
+ * The base64url alphabet (RFC 4648 section 5) without padding: what a token
+ * or a digest carries where "+", "/" and "=" would need escaping, in a URL, a
+ * header or a database column.
+ */
+export declare const bytesToBase64Url: (bytes: Uint8Array) => string;
+/**
+ * Whether `text` is base64url and nothing else, so decoding it decodes rather
+ * than guesses; Buffer decodes anything. A length that leaves a remainder of
+ * one past a multiple of four is no encoding of any bytes, and the platform's
+ * atob throws on it where Buffer shrugs, so it is refused here on both.
+ */
+export declare const isBase64Url: (text: string) => boolean;
+export declare const base64UrlToBytes: (base64Url: string) => Uint8Array;

package/dist/shared/util/LambderBase64.js

@@ -25,3 +25,20 @@ export const base64ToBytes = (base64) => {
 };
 /** The base64 of UTF-8 text back to the text. */
 export const base64ToText = (base64) => new TextDecoder().decode(base64ToBytes(base64));
+/**
+ * The base64url alphabet (RFC 4648 section 5) without padding: what a token
+ * or a digest carries where "+", "/" and "=" would need escaping, in a URL, a
+ * header or a database column.
+ */
+export const bytesToBase64Url = (bytes) => bytesToBase64(bytes).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+/**
+ * Whether `text` is base64url and nothing else, so decoding it decodes rather
+ * than guesses; Buffer decodes anything. A length that leaves a remainder of
+ * one past a multiple of four is no encoding of any bytes, and the platform's
+ * atob throws on it where Buffer shrugs, so it is refused here on both.
+ */
+export const isBase64Url = (text) => text.length % 4 !== 1 && /^[A-Za-z0-9_-]*$/.test(text);
+export const base64UrlToBytes = (base64Url) => {
+    const base64 = base64Url.replace(/-/g, "+").replace(/_/g, "/");
+    return base64ToBytes(base64.padEnd(base64.length + (4 - base64.length % 4) % 4, "="));
+};