lambder 8.1.2 → 9.0.1

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, "="));
+};

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

@@ -0,0 +1,78 @@
+import type { z } from "zod";
+export type LambderSignedClaimsOptions<TClaims> = {
+    /** The HMAC key. Server side, and every runtime that verifies; never a browser. */
+    secret: string;
+    /**
+     * Names this kind of token, as the first segment of every one it signs;
+     * a token of another version does not verify. Any text without a dot.
+     */
+    version: string;
+    /** The claims' shape, parsed on the way out and on the way back, so a token never carries a shape the app did not declare. */
+    schema: z.ZodType<TClaims>;
+    /** The clock `exp` is judged against, in epoch milliseconds. Default: Date.now. */
+    now?: () => number;
+};
+/**
+ * Refuses a claims type whose `exp` is not a number, at the constructor: the
+ * class would judge it as an expiry, find no number, and let the token live
+ * for ever. The property name is the message.
+ */
+type LambderExpIsSeconds<TClaims> = TClaims extends {
+    exp: infer E;
+} ? ([E] extends [number] ? unknown : {
+    readonly "lambder: the exp claim is an expiry in epoch seconds, so the schema must declare it as a number.": never;
+}) : unknown;
+/**
+ * One kind of signed token: constructed once with its secret, version and
+ * claims schema, it keeps the imported HMAC key and answers `sign` and
+ * `verify`. An app declares one instance per kind of token it hands out.
+ *
+ * The one claim with a meaning here is `exp`, an expiry in epoch seconds,
+ * the unit sessions, DynamoDB's TTL and JWTs use. A schema that declares it
+ * gets it checked on every verify; a schema without it declares a token that
+ * does not expire on its own, which is right where the thing the token names
+ * (a request, a message) decides what it may still do.
+ *
+ * `verify` answers null for every failure alike: a forged signature, another
+ * version, malformed text, claims the schema refuses, an `exp` in the past.
+ * A caller cannot tell them apart, and so cannot tell a client apart either.
+ */
+export declare class LambderSignedClaims<TClaims extends object> {
+    private readonly secret;
+    private readonly version;
+    private readonly schema;
+    private readonly now;
+    /** Imported on first use and kept: signing and verifying share one key object for the life of the instance. */
+    private keyPromise;
+    constructor(options: LambderSignedClaimsOptions<TClaims> & LambderExpIsSeconds<TClaims>);
+    /** The token for these claims, which the schema parses first. `exp`, when the schema has it, is epoch seconds. */
+    sign(claims: TClaims): Promise<string>;
+    /**
+     * The claims, when the token is this version, signed under this secret,
+     * well formed, accepted by the schema and not past its `exp`; null
+     * otherwise, for every reason alike. `now`, in epoch milliseconds, is the
+     * moment `exp` is judged against for this call; default: the clock's.
+     */
+    verify(token: string, options?: {
+        now?: number;
+    }): Promise<TClaims | null>;
+    private key;
+}
+/**
+ * The keyed digest of a secret an app stores and later looks up or compares
+ * by value: a device's secret, a code sent by email, a pairing code. Keyed
+ * under the app's secret rather than a plain hash, so a copied table alone
+ * cannot be attacked offline, and deterministic, so a lookup is one indexed
+ * read. HMAC-SHA256 as 43 characters of base64url; compare two with
+ * constantTimeEquals.
+ */
+export declare const keyedDigest: (secret: string, value: string) => Promise<string>;
+/**
+ * A fresh secret from the runtime's cryptographic random source, as base64url
+ * (43 characters for the default 32 bytes): the credential a paired device
+ * keeps, the token in a link that must not be guessable. Synchronous, since
+ * getRandomValues is, on every runtime with a WebCrypto global; a runtime
+ * without one is told so.
+ */
+export declare const randomSecret: (bytes?: number) => string;
+export {};

package/dist/shared/util/LambderSignedClaims.js

@@ -0,0 +1,109 @@
+import { base64UrlToBytes, bytesToBase64Url, isBase64Url } from "./LambderBase64.js";
+import { hmacSha256Of, importHmacKey, resolveWebCrypto } from "./LambderTextDigest.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
+ * `verify`. An app declares one instance per kind of token it hands out.
+ *
+ * The one claim with a meaning here is `exp`, an expiry in epoch seconds,
+ * the unit sessions, DynamoDB's TTL and JWTs use. A schema that declares it
+ * gets it checked on every verify; a schema without it declares a token that
+ * does not expire on its own, which is right where the thing the token names
+ * (a request, a message) decides what it may still do.
+ *
+ * `verify` answers null for every failure alike: a forged signature, another
+ * version, malformed text, claims the schema refuses, an `exp` in the past.
+ * A caller cannot tell them apart, and so cannot tell a client apart either.
+ */
+export class LambderSignedClaims {
+    secret;
+    version;
+    schema;
+    now;
+    /** Imported on first use and kept: signing and verifying share one key object for the life of the instance. */
+    keyPromise;
+    constructor(options) {
+        if (typeof options.secret !== "string" || options.secret.length === 0) {
+            throw new Error("Lambder: LambderSignedClaims needs a secret to sign with.");
+        }
+        if (typeof options.version !== "string" || options.version.length === 0 || options.version.includes(".")) {
+            throw new Error(`Lambder: LambderSignedClaims version must be text without a dot, got ${JSON.stringify(options.version)}: it is the first of the token's three dot-separated segments.`);
+        }
+        this.secret = options.secret;
+        this.version = options.version;
+        this.schema = options.schema;
+        this.now = options.now ?? (() => Date.now());
+    }
+    /** The token for these claims, which the schema parses first. `exp`, when the schema has it, is epoch seconds. */
+    async sign(claims) {
+        const body = bytesToBase64Url(new TextEncoder().encode(JSON.stringify(this.schema.parse(claims))));
+        const message = `${this.version}.${body}`;
+        const webCrypto = await resolveWebCrypto();
+        const mac = await webCrypto.subtle.sign("HMAC", await this.key(webCrypto), new TextEncoder().encode(message));
+        return `${message}.${bytesToBase64Url(new Uint8Array(mac))}`;
+    }
+    /**
+     * The claims, when the token is this version, signed under this secret,
+     * well formed, accepted by the schema and not past its `exp`; null
+     * otherwise, for every reason alike. `now`, in epoch milliseconds, is the
+     * moment `exp` is judged against for this call; default: the clock's.
+     */
+    async verify(token, options = {}) {
+        const parts = token.split(".");
+        if (parts.length !== 3 || parts[0] !== this.version)
+            return null;
+        const [, body, mac] = parts;
+        if (!isBase64Url(body) || !isBase64Url(mac))
+            return null;
+        // The last character of a MAC carries bits decoding ignores, so four
+        // spellings decode to the same bytes. Only the one sign() writes is a
+        // token: an app that keys anything on the token string (a list of
+        // spent tokens, a rate limit) must not meet the same token again
+        // under another spelling.
+        const macBytes = base64UrlToBytes(mac);
+        if (bytesToBase64Url(macBytes) !== mac)
+            return null;
+        const webCrypto = await resolveWebCrypto();
+        const valid = await webCrypto.subtle.verify("HMAC", await this.key(webCrypto), macBytes, new TextEncoder().encode(`${this.version}.${body}`));
+        if (!valid)
+            return null;
+        let claims;
+        try {
+            claims = this.schema.parse(JSON.parse(new TextDecoder().decode(base64UrlToBytes(body))));
+        }
+        catch {
+            return null;
+        }
+        const exp = claims.exp;
+        if (typeof exp === "number" && exp * 1000 <= (options.now ?? this.now()))
+            return null;
+        return claims;
+    }
+    key(webCrypto) {
+        this.keyPromise ??= importHmacKey(webCrypto, this.secret, ["sign", "verify"]);
+        return this.keyPromise;
+    }
+}
+/**
+ * The keyed digest of a secret an app stores and later looks up or compares
+ * by value: a device's secret, a code sent by email, a pairing code. Keyed
+ * under the app's secret rather than a plain hash, so a copied table alone
+ * cannot be attacked offline, and deterministic, so a lookup is one indexed
+ * read. HMAC-SHA256 as 43 characters of base64url; compare two with
+ * constantTimeEquals.
+ */
+export const keyedDigest = async (secret, value) => bytesToBase64Url(await hmacSha256Of(secret, value));
+/**
+ * A fresh secret from the runtime's cryptographic random source, as base64url
+ * (43 characters for the default 32 bytes): the credential a paired device
+ * keeps, the token in a link that must not be guessable. Synchronous, since
+ * getRandomValues is, on every runtime with a WebCrypto global; a runtime
+ * without one is told so.
+ */
+export const randomSecret = (bytes = 32) => {
+    const webCrypto = globalThis.crypto;
+    if (typeof webCrypto?.getRandomValues !== "function") {
+        throw new Error("Lambder needs crypto.getRandomValues in this runtime to mint a secret. Every browser provides it; Node 20+ provides it as globalThis.crypto.");
+    }
+    return bytesToBase64Url(webCrypto.getRandomValues(new Uint8Array(bytes)));
+};

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

@@ -1,9 +1,11 @@
 /**
- * SHA-256 through WebCrypto: the one digest every layer shares. The session
- * crypto hashes bearer secrets with it and the rate-limit engine folds an
- * over-long tracker key with it, so both key spaces are built from the same
- * primitive 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.
+ * 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.
  */
 /** Lowercase hex of a byte array, two characters per byte. */
 export declare const bytesToHexString: (bytes: Uint8Array) => string;
@@ -17,3 +19,15 @@ export declare const resolveWebCrypto: () => Promise<Crypto>;
 export declare const sha256HexOf: (text: string) => Promise<string>;
 /** The SHA-256 digest of `bytes`, as base64: the form object storage checks an upload's checksum in. */
 export declare const sha256Base64Of: (bytes: Uint8Array) => Promise<string>;
+/** An HMAC-SHA256 key over `secret` (UTF-8), for `usages`; a holder that signs often keeps the key rather than importing it per call. */
+export declare const importHmacKey: (webCrypto: Crypto, secret: string, usages?: KeyUsage[]) => Promise<CryptoKey>;
+/** HMAC-SHA256 of `text` under `secret` (both UTF-8), as bytes. */
+export declare const hmacSha256Of: (secret: string, text: string) => Promise<Uint8Array>;
+/**
+ * Length-aware, timing-neutral string comparison: no early exit on the first
+ * differing character, so how long it takes says nothing about where two
+ * digests part. For comparing a stored digest with the digest of a candidate;
+ * a signature is verified by WebCrypto, which compares in constant time
+ * itself.
+ */
+export declare const constantTimeEquals: (a: string, b: string) => boolean;

package/dist/shared/util/LambderTextDigest.js

@@ -1,11 +1,13 @@
 import { bytesToBase64 } from "./LambderBase64.js";
 import { getCrypto } from "./LambderNodeModules.js";
 /**
- * SHA-256 through WebCrypto: the one digest every layer shares. The session
- * crypto hashes bearer secrets with it and the rate-limit engine folds an
- * over-long tracker key with it, so both key spaces are built from the same
- * primitive 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.
+ * 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.
  */
 /** 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("");
@@ -38,3 +40,26 @@ export const sha256Base64Of = async (bytes) => {
     const webCrypto = await resolveWebCrypto();
     return bytesToBase64(new Uint8Array(await webCrypto.subtle.digest("SHA-256", bytes)));
 };
+/** An HMAC-SHA256 key over `secret` (UTF-8), for `usages`; a holder that signs often keeps the key rather than importing it per call. */
+export const importHmacKey = async (webCrypto, secret, usages = ["sign"]) => await webCrypto.subtle.importKey("raw", new TextEncoder().encode(secret), { name: "HMAC", hash: "SHA-256" }, false, usages);
+/** HMAC-SHA256 of `text` under `secret` (both UTF-8), as bytes. */
+export const hmacSha256Of = async (secret, text) => {
+    const webCrypto = await resolveWebCrypto();
+    const key = await importHmacKey(webCrypto, secret);
+    return new Uint8Array(await webCrypto.subtle.sign("HMAC", key, new TextEncoder().encode(text)));
+};
+/**
+ * Length-aware, timing-neutral string comparison: no early exit on the first
+ * differing character, so how long it takes says nothing about where two
+ * digests part. For comparing a stored digest with the digest of a candidate;
+ * a signature is verified by WebCrypto, which compares in constant time
+ * itself.
+ */
+export const constantTimeEquals = (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;
+};

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

@@ -12,6 +12,24 @@
  * awaits either.
  */
 export type MaybePromise<T> = T | Promise<T>;
+/**
+ * T with every object and array readonly, all the way down: what an API
+ * handler's returned answer is checked against.
+ *
+ * An answer is a return value, and TypeScript widens the literals of a
+ * return value whose expected type is still generic (`{ kind: "a" }` reads
+ * as `{ kind: string }`), where a call argument keeps them. The handler's
+ * return is therefore its own `const` type parameter, which keeps literals;
+ * `const` also makes array literals readonly, which a schema's mutable arrays
+ * would refuse, so the bound is this readonly view of the output. Nothing
+ * writes to an answer (it is parsed and sent), so readonly costs nothing.
+ * Functions and Dates pass through whole. Eight levels deep and no further,
+ * because an output may be recursive (`z.json()`), and past that depth the
+ * type is left as it is.
+ */
+export type LambderReadonlyDeep<T, TDepth extends unknown[] = []> = TDepth["length"] extends 8 ? T : T extends (...args: never[]) => unknown ? T : T extends Date ? T : T extends object ? {
+    readonly [K in keyof T]: LambderReadonlyDeep<T[K], [...TDepth, unknown]>;
+} : T;
 /**
  * A declaration map with AT LEAST ONE entry: the union, over every declarable
  * name, of "this one required and the rest optional".

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

@@ -0,0 +1,9 @@
+/**
+ * Whether a value survives JSON unchanged, and so can be written into a
+ * generated module as the data it is: strings, finite numbers, booleans,
+ * null, and arrays and plain objects of them. Anything else (a function, a
+ * class instance such as a zod schema, a symbol, a bigint, NaN, undefined
+ * inside a container) is code or a shape JSON would silently rewrite, and
+ * the caller is told where it sits.
+ */
+export declare const assertPlainData: (value: unknown, subject: string) => void;

package/dist/shared/util/assertPlainData.js

@@ -0,0 +1,41 @@
+/**
+ * Whether a value survives JSON unchanged, and so can be written into a
+ * generated module as the data it is: strings, finite numbers, booleans,
+ * null, and arrays and plain objects of them. Anything else (a function, a
+ * class instance such as a zod schema, a symbol, a bigint, NaN, undefined
+ * inside a container) is code or a shape JSON would silently rewrite, and
+ * the caller is told where it sits.
+ */
+export const assertPlainData = (value, subject) => {
+    const offence = findNonPlain(value, "");
+    if (offence === null)
+        return;
+    throw new Error(`Lambder: ${subject} must be plain data (strings, finite numbers, booleans, null, and arrays and plain objects of them) to be written as a value, but ${offence.path || "it"} is ${offence.kind}.`);
+};
+const findNonPlain = (value, path) => {
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return null;
+    if (typeof value === "number")
+        return Number.isFinite(value) ? null : { path, kind: String(value) };
+    if (Array.isArray(value)) {
+        for (let index = 0; index < value.length; index += 1) {
+            const offence = findNonPlain(value[index], `${path}[${index}]`);
+            if (offence)
+                return offence;
+        }
+        return null;
+    }
+    if (typeof value === "object") {
+        const prototype = Object.getPrototypeOf(value);
+        if (prototype !== Object.prototype && prototype !== null) {
+            return { path, kind: `an instance of ${value.constructor?.name || "a class"}` };
+        }
+        for (const [key, member] of Object.entries(value)) {
+            const offence = findNonPlain(member, path ? `${path}.${key}` : key);
+            if (offence)
+                return offence;
+        }
+        return null;
+    }
+    return { path, kind: typeof value === "function" ? "a function" : `a ${typeof value}` };
+};

package/dist/shared/wire/LambderAnswerHeaders.d.ts

@@ -21,8 +21,9 @@ export type LambderHeaderTarget = {
     addHeader(key: string, value: string): unknown;
 };
 /**
- * Response headers written while a call runs (`res.setHeader`, `res.addHeader`,
- * the session controller's Set-Cookie), applied onto the answer once the
+ * Response headers written while a call runs (`ctx.setResponseHeader`,
+ * `ctx.addResponseHeader`, `ctx.setCookie`, the session controller's
+ * Set-Cookie), applied onto the answer once the
  * call has one. Recorded as operations in call order rather than as a map,
  * so `set` replaces what the answer itself carries (a Content-Type, say) and
  * `add` appends to it, exactly as if called on the answer directly.

package/dist/shared/wire/LambderAnswerHeaders.js

@@ -36,8 +36,9 @@ export const addAnswerHeader = (headers, name, value) => {
         headers[name] = [value];
 };
 /**
- * Response headers written while a call runs (`res.setHeader`, `res.addHeader`,
- * the session controller's Set-Cookie), applied onto the answer once the
+ * Response headers written while a call runs (`ctx.setResponseHeader`,
+ * `ctx.addResponseHeader`, `ctx.setCookie`, the session controller's
+ * Set-Cookie), applied onto the answer once the
  * call has one. Recorded as operations in call order rather than as a map,
  * so `set` replaces what the answer itself carries (a Content-Type, say) and
  * `add` appends to it, exactly as if called on the answer directly.

package/dist/shared/wire/LambderApiContract.d.ts

@@ -4,7 +4,6 @@
  * Contracts are built via method chaining and inferred using typeof lambder.ApiContract
  */
 import type { LambderCrashDetail } from "./LambderCrashDetail.js";
-import type { LambderNonEmptyOptionMap } from "../util/LambderTypeUtilities.js";
 import type { LambderAppRefusalMessage } from "./LambderApiRefusal.js";
 import type { LambderApiIdempotencyOption, LambderGuardsOptionValue, LambderRateLimitOptionValue } from "./LambderApiOptionValues.js";
 /** Whether an endpoint runs without a session or requires one (addApi versus addSessionApi). */
@@ -32,15 +31,18 @@ export type LambderApiContractShape = Record<string, {
     /** Present when the API declares idempotency: the `idempotency` option exactly as written. */
     idempotency?: LambderApiIdempotencyOption;
 }>;
-/** Envelope flags/channels the server may set beside (or instead of) the payload. */
+/**
+ * Envelope flags and channels beside (or instead of) the payload: what a
+ * refusal, the pipeline's own answers, a hook or an error handler set. An API
+ * handler sets none of them itself: it returns its output or refuses.
+ */
 export type LambderApiResponseConfig = {
     versionExpired?: boolean;
     sessionExpired?: boolean;
     notAuthorized?: boolean;
-    message?: any;
     /**
-     * A refusal message, or a plain string when writing
-     * (`res.api(null, { errorMessage: "..." })`): the envelope goes out with
+     * A refusal message, or a plain string when writing (a refusal thrown
+     * with refuse(), or an error handler's `res.api(null, { errorMessage })`): the envelope goes out with
      * the message object either way. Read off the wire it can still be a
      * string, or no message at all, wherever a Lambder server did not write
      * the body (a hand-built mock answer, a proxy); refusalMessageOf reads
@@ -58,15 +60,8 @@ export type LambderApiResponseConfig = {
     crash?: LambderCrashDetail;
 };
 /**
- * The config a null answer carries: at least one of the reason fields, so
- * `res.api(null, {})` is a compile error. A bare null with no flag and no
- * message reaches the caller as a success whose payload is null, which is
- * indistinguishable from an endpoint that answered nothing on purpose.
- */
-export type LambderApiNullAnswerConfig = LambderNonEmptyOptionMap<Pick<LambderApiResponseConfig, "versionExpired" | "sessionExpired" | "notAuthorized" | "errorMessage" | "message">> & LambderApiResponseConfig;
-/**
- * The API wire envelope both sides speak: res.api() emits it, LambderCaller
- * parses it. `apiVersion` is always there (null when the server set none):
+ * The API wire envelope both sides speak: the server writes it around a
+ * handler's output or a refusal, LambderCaller parses it. `apiVersion` is always there (null when the server set none):
  * it is how a reader tells a Lambder envelope from another JSON answer, such
  * as API Gateway's own `{ "message": ... }` errors, so an answer without it
  * reads as a server failure.