lambder 6.0.1 → 7.0.1

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

@@ -0,0 +1,119 @@
+/**
+ * A Map whose entries have an expiry, which is the one thing every in-memory
+ * store here needs: idempotency records, rate-limit counters and session
+ * records all key something by a string and all stop mattering at a known
+ * second.
+ *
+ * Written once because a store that hand-rolls it tends to expire an entry
+ * only when something asks for that exact key again, which
+ * is fine for a test and a slow leak in anything long-lived: a rate-limit
+ * counter nobody asks about again is dead weight for as long as the process
+ * runs, and an idempotency record for a key that never returns is dead weight
+ * for ever. So expiry happens on read AND on an amortized sweep, and no
+ * caller has to remember either.
+ *
+ * Expiry alone bounds how long an entry lives, not how many there are: a
+ * workload that never repeats a key (a rate-limit counter per IP with a
+ * monthly window, an idempotency key per request) accumulates live entries
+ * faster than any expiry retires them. So the map also holds a ceiling and
+ * evicts once it is reached, which is what makes "in memory" a bounded claim
+ * rather than a slower leak. It evicts whatever expires SOONEST among the
+ * entries that may be evicted at all, never whatever was written earliest:
+ * insertion order would retire exactly the entries with the most life left in
+ * them, which are the long-window rate-limit counters and the day-long
+ * idempotency records, so a flood of short-lived keys could reset a monthly
+ * cap. Evicting the soonest-expiring entry costs the caller the least that
+ * can be taken, and a flood evicts mostly itself.
+ *
+ * "Soonest to expire" is the wrong answer for one kind of entry, though, and
+ * it is the one where the cost is highest: an idempotency claim lives for a
+ * few minutes while the settled record it becomes lives for a day, so at the
+ * ceiling the claim was always the first victim and two concurrent retries
+ * both executed. An entry written with `evictable: false` is therefore never
+ * chosen, and a caller whose write cannot be made room for is told so
+ * (LambderExpiringMapFullError) rather than quietly costing somebody else
+ * their claim.
+ *
+ * Times are epoch SECONDS, matching the TTL attribute DynamoDB uses, so the
+ * memory stores and their DynamoDB counterparts say the same thing.
+ */
+/**
+ * Thrown by set() when the map is at its ceiling and every entry it holds is
+ * protected from eviction. The write did not happen and nothing was dropped
+ * to make room for it: the caller decides what to do about a store that is
+ * full of live claims, and the claim already held by somebody else is not
+ * something this map will trade away.
+ */
+export declare class LambderExpiringMapFullError extends Error {
+    constructor(maxEntries: number);
+}
+export declare class LambderExpiringMap<TValue> {
+    private readonly entries;
+    private readonly now;
+    private readonly maxEntries;
+    private readonly evictionBatchSize;
+    private writesSinceSweep;
+    /**
+     * `now` is injectable so a test can move time forward without waiting.
+     * `maxEntries` caps live entries; once a sweep cannot get back under it,
+     * the soonest to expire go first, protected entries excepted.
+     */
+    constructor(options?: {
+        now?: () => number;
+        maxEntries?: number;
+    });
+    private nowSeconds;
+    /**
+     * The value, or undefined when it is absent or past its expiry. An
+     * expired entry is dropped on the way, so a read never resurrects one.
+     */
+    get(key: string): TValue | undefined;
+    /**
+     * Stores the value until `expiresAt` (epoch seconds), replacing what was
+     * there. `evictable: false` keeps the entry out of the ceiling eviction,
+     * for the entries whose loss costs more than the flood that would take
+     * them (an idempotency claim, whose loss lets a duplicate execute).
+     *
+     * Throws LambderExpiringMapFullError when the map is at its ceiling and
+     * nothing there may be evicted. `expiresAt` is checked the way the
+     * constructor checks `maxEntries`, because a NaN expiry compares false
+     * against every clock: an entry carrying one is neither read, swept nor
+     * evicted, which is one immortal record per bad TTL.
+     */
+    set(key: string, value: TValue, expiresAt: number, options?: {
+        evictable?: boolean;
+    }): void;
+    delete(key: string): void;
+    /**
+     * Every live value. Expired entries are skipped rather than deleted:
+     * reading the map is not a reason to write to it, and the amortized sweep
+     * on writes is what reclaims them.
+     */
+    values(): TValue[];
+    /** Number of live entries, counted rather than swept, for the same reason values() counts. */
+    get size(): number;
+    clear(): void;
+    /**
+     * Drops a batch of the evictable entries closest to expiring, taking the
+     * map from its ceiling down to a floor one batch below it. Reached only
+     * when expiry cannot keep up, which means the keys are not repeating.
+     * Evicting costs the caller whatever the entry was protecting (a counter
+     * resets, a stored answer re-executes on retry), so the ones taken are
+     * always the ones with the least life left: the soonest to expire were
+     * going to be lost first anyway, and choosing them means a flood of
+     * short-lived keys cannot evict a long-window counter.
+     *
+     * A batch rather than a single entry because a single one leaves the map
+     * exactly at its ceiling, so the next write crosses it again and pays for
+     * another pass: one pass per write, for as long as the flood lasts. The
+     * headroom this leaves is what the following writes spend. Measured at
+     * 100,000 entries: 0.56 ms per write one at a time, 0.007 ms per write in
+     * batches of one percent.
+     *
+     * The pass is linear and the sort is over the evictable entries only,
+     * which is affordable because reaching the ceiling at all is already
+     * pathological.
+     */
+    private evictBatch;
+    private sweep;
+}

package/dist/shared/util/LambderExpiringMap.js

@@ -0,0 +1,217 @@
+/**
+ * A Map whose entries have an expiry, which is the one thing every in-memory
+ * store here needs: idempotency records, rate-limit counters and session
+ * records all key something by a string and all stop mattering at a known
+ * second.
+ *
+ * Written once because a store that hand-rolls it tends to expire an entry
+ * only when something asks for that exact key again, which
+ * is fine for a test and a slow leak in anything long-lived: a rate-limit
+ * counter nobody asks about again is dead weight for as long as the process
+ * runs, and an idempotency record for a key that never returns is dead weight
+ * for ever. So expiry happens on read AND on an amortized sweep, and no
+ * caller has to remember either.
+ *
+ * Expiry alone bounds how long an entry lives, not how many there are: a
+ * workload that never repeats a key (a rate-limit counter per IP with a
+ * monthly window, an idempotency key per request) accumulates live entries
+ * faster than any expiry retires them. So the map also holds a ceiling and
+ * evicts once it is reached, which is what makes "in memory" a bounded claim
+ * rather than a slower leak. It evicts whatever expires SOONEST among the
+ * entries that may be evicted at all, never whatever was written earliest:
+ * insertion order would retire exactly the entries with the most life left in
+ * them, which are the long-window rate-limit counters and the day-long
+ * idempotency records, so a flood of short-lived keys could reset a monthly
+ * cap. Evicting the soonest-expiring entry costs the caller the least that
+ * can be taken, and a flood evicts mostly itself.
+ *
+ * "Soonest to expire" is the wrong answer for one kind of entry, though, and
+ * it is the one where the cost is highest: an idempotency claim lives for a
+ * few minutes while the settled record it becomes lives for a day, so at the
+ * ceiling the claim was always the first victim and two concurrent retries
+ * both executed. An entry written with `evictable: false` is therefore never
+ * chosen, and a caller whose write cannot be made room for is told so
+ * (LambderExpiringMapFullError) rather than quietly costing somebody else
+ * their claim.
+ *
+ * Times are epoch SECONDS, matching the TTL attribute DynamoDB uses, so the
+ * memory stores and their DynamoDB counterparts say the same thing.
+ */
+import { assertPositiveInteger } from "./LambderOptionChecks.js";
+/** How many writes go by before the map walks itself and drops what has expired. */
+const SWEEP_WRITE_INTERVAL = 256;
+/**
+ * Live entries held before the oldest writes start being evicted. High enough
+ * that no ordinary single-process run reaches it, low enough to bound the
+ * process: crossing it means a key space that never repeats, where the
+ * alternative to evicting is growing until the process dies.
+ */
+const DEFAULT_MAX_ENTRIES = 100_000;
+/**
+ * Share of the ceiling one eviction pass reclaims. Evicting exactly the one
+ * entry that crossed the ceiling means every later write crosses it again, so
+ * the map pays a full pass per write for as long as the flood lasts; taking a
+ * batch amortizes that pass over the writes the headroom absorbs.
+ */
+const EVICTION_BATCH_SHARE = 0.01;
+/**
+ * Thrown by set() when the map is at its ceiling and every entry it holds is
+ * protected from eviction. The write did not happen and nothing was dropped
+ * to make room for it: the caller decides what to do about a store that is
+ * full of live claims, and the claim already held by somebody else is not
+ * something this map will trade away.
+ */
+export class LambderExpiringMapFullError extends Error {
+    constructor(maxEntries) {
+        super(`LambderExpiringMap: at the ceiling of ${maxEntries} entries and every entry is protected from eviction, so the write was refused.`);
+        this.name = "LambderExpiringMapFullError";
+    }
+}
+export class LambderExpiringMap {
+    entries = new Map();
+    now;
+    maxEntries;
+    evictionBatchSize;
+    writesSinceSweep = 0;
+    /**
+     * `now` is injectable so a test can move time forward without waiting.
+     * `maxEntries` caps live entries; once a sweep cannot get back under it,
+     * the soonest to expire go first, protected entries excepted.
+     */
+    constructor(options = {}) {
+        this.now = options.now ?? (() => Date.now());
+        this.maxEntries = assertPositiveInteger(options.maxEntries ?? DEFAULT_MAX_ENTRIES, "maxEntries");
+        this.evictionBatchSize = Math.max(1, Math.ceil(this.maxEntries * EVICTION_BATCH_SHARE));
+    }
+    nowSeconds() { return Math.floor(this.now() / 1000); }
+    /**
+     * The value, or undefined when it is absent or past its expiry. An
+     * expired entry is dropped on the way, so a read never resurrects one.
+     */
+    get(key) {
+        const entry = this.entries.get(key);
+        if (!entry)
+            return undefined;
+        if (entry.expiresAt <= this.nowSeconds()) {
+            this.entries.delete(key);
+            return undefined;
+        }
+        return entry.value;
+    }
+    /**
+     * Stores the value until `expiresAt` (epoch seconds), replacing what was
+     * there. `evictable: false` keeps the entry out of the ceiling eviction,
+     * for the entries whose loss costs more than the flood that would take
+     * them (an idempotency claim, whose loss lets a duplicate execute).
+     *
+     * Throws LambderExpiringMapFullError when the map is at its ceiling and
+     * nothing there may be evicted. `expiresAt` is checked the way the
+     * constructor checks `maxEntries`, because a NaN expiry compares false
+     * against every clock: an entry carrying one is neither read, swept nor
+     * evicted, which is one immortal record per bad TTL.
+     */
+    set(key, value, expiresAt, options = {}) {
+        assertPositiveInteger(expiresAt, "expiresAt");
+        this.entries.set(key, { value, expiresAt, evictable: options.evictable ?? true });
+        this.writesSinceSweep += 1;
+        if (this.writesSinceSweep >= SWEEP_WRITE_INTERVAL)
+            this.sweep();
+        if (this.entries.size <= this.maxEntries)
+            return;
+        this.evictBatch(key);
+        if (this.entries.size > this.maxEntries) {
+            // Only a key the map did not already hold can push the size past
+            // the ceiling, so dropping the one just written is what leaves the
+            // map exactly as the caller found it.
+            this.entries.delete(key);
+            throw new LambderExpiringMapFullError(this.maxEntries);
+        }
+    }
+    delete(key) { this.entries.delete(key); }
+    /**
+     * Every live value. Expired entries are skipped rather than deleted:
+     * reading the map is not a reason to write to it, and the amortized sweep
+     * on writes is what reclaims them.
+     */
+    values() {
+        const nowSeconds = this.nowSeconds();
+        const live = [];
+        for (const entry of this.entries.values()) {
+            if (entry.expiresAt > nowSeconds)
+                live.push(entry.value);
+        }
+        return live;
+    }
+    /** Number of live entries, counted rather than swept, for the same reason values() counts. */
+    get size() {
+        const nowSeconds = this.nowSeconds();
+        let count = 0;
+        for (const entry of this.entries.values()) {
+            if (entry.expiresAt > nowSeconds)
+                count += 1;
+        }
+        return count;
+    }
+    clear() {
+        this.entries.clear();
+        this.writesSinceSweep = 0;
+    }
+    /**
+     * Drops a batch of the evictable entries closest to expiring, taking the
+     * map from its ceiling down to a floor one batch below it. Reached only
+     * when expiry cannot keep up, which means the keys are not repeating.
+     * Evicting costs the caller whatever the entry was protecting (a counter
+     * resets, a stored answer re-executes on retry), so the ones taken are
+     * always the ones with the least life left: the soonest to expire were
+     * going to be lost first anyway, and choosing them means a flood of
+     * short-lived keys cannot evict a long-window counter.
+     *
+     * A batch rather than a single entry because a single one leaves the map
+     * exactly at its ceiling, so the next write crosses it again and pays for
+     * another pass: one pass per write, for as long as the flood lasts. The
+     * headroom this leaves is what the following writes spend. Measured at
+     * 100,000 entries: 0.56 ms per write one at a time, 0.007 ms per write in
+     * batches of one percent.
+     *
+     * The pass is linear and the sort is over the evictable entries only,
+     * which is affordable because reaching the ceiling at all is already
+     * pathological.
+     */
+    evictBatch(justWritten) {
+        const floorSize = Math.max(0, this.maxEntries - this.evictionBatchSize);
+        // One clock read per batch: expired entries go first, protected or
+        // not, since a claim past its own TTL holds nothing anyone can settle
+        // and is never worth a live entry's slot. Reclaimed in the same pass
+        // that collects the candidates, so a batch is still one walk.
+        const nowSeconds = this.nowSeconds();
+        const candidates = [];
+        for (const [key, entry] of this.entries) {
+            if (entry.expiresAt <= nowSeconds) {
+                this.entries.delete(key);
+                continue;
+            }
+            // The entry just written is what the caller asked to store; taking
+            // it as its own victim would answer a write that stored nothing.
+            if (entry.evictable && key !== justWritten)
+                candidates.push({ key, expiresAt: entry.expiresAt });
+        }
+        if (this.entries.size <= floorSize)
+            return;
+        // A stable sort over a list built in insertion order, so entries
+        // expiring in the same second are taken oldest first.
+        candidates.sort((first, second) => first.expiresAt - second.expiresAt);
+        for (const candidate of candidates) {
+            if (this.entries.size <= floorSize)
+                break;
+            this.entries.delete(candidate.key);
+        }
+    }
+    sweep() {
+        const nowSeconds = this.nowSeconds();
+        for (const [key, entry] of this.entries) {
+            if (entry.expiresAt <= nowSeconds)
+                this.entries.delete(key);
+        }
+        this.writesSinceSweep = 0;
+    }
+}

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

@@ -0,0 +1,32 @@
+/**
+ * Joining the fields of a tracker or scope key.
+ *
+ * Both the rate limiter and the idempotency engine build a key by joining a
+ * few fields with a separator, and at least one field in each is caller data:
+ * a rate-limit key returned by a policy handler, an idempotency key posted
+ * with the request. A plain join lets two different field lists produce one
+ * string, so two callers land on one counter or one caller reads another's
+ * stored answer.
+ *
+ * Escaping the caller's use of the separator rather than rejecting or
+ * reserving it: the caller chose the character for its own reasons, and a
+ * limit that refuses a legal key is a bug of its own.
+ *
+ * The join is one-way. Nothing here reads a key back apart, because nothing
+ * needs to: a key is looked up, counted against or compared, never taken to
+ * pieces. The escaping is there so that distinct field lists cannot collide,
+ * not so that the fields can be recovered.
+ *
+ * LambderDdbCache's sort-key encoding looks similar and is deliberately the
+ * other thing: a reversible escape, because a cached entry's sort key is
+ * handed back to the caller by listSortKeys and therefore has to decode to
+ * exactly what was written. Two schemes, two jobs; neither should be reached
+ * for in the other's place.
+ *
+ * Written once because the two engines had drifted, one escaping and one not.
+ */
+/**
+ * The fields joined into one key, each escaped, so no two distinct field
+ * lists can produce the same string.
+ */
+export declare const joinKeyFields: (...fields: string[]) => string;

package/dist/shared/util/LambderKeyFields.js

@@ -0,0 +1,34 @@
+/**
+ * Joining the fields of a tracker or scope key.
+ *
+ * Both the rate limiter and the idempotency engine build a key by joining a
+ * few fields with a separator, and at least one field in each is caller data:
+ * a rate-limit key returned by a policy handler, an idempotency key posted
+ * with the request. A plain join lets two different field lists produce one
+ * string, so two callers land on one counter or one caller reads another's
+ * stored answer.
+ *
+ * Escaping the caller's use of the separator rather than rejecting or
+ * reserving it: the caller chose the character for its own reasons, and a
+ * limit that refuses a legal key is a bug of its own.
+ *
+ * The join is one-way. Nothing here reads a key back apart, because nothing
+ * needs to: a key is looked up, counted against or compared, never taken to
+ * pieces. The escaping is there so that distinct field lists cannot collide,
+ * not so that the fields can be recovered.
+ *
+ * LambderDdbCache's sort-key encoding looks similar and is deliberately the
+ * other thing: a reversible escape, because a cached entry's sort key is
+ * handed back to the caller by listSortKeys and therefore has to decode to
+ * exactly what was written. Two schemes, two jobs; neither should be reached
+ * for in the other's place.
+ *
+ * Written once because the two engines had drifted, one escaping and one not.
+ */
+/** One field, with the separator and its own escape character escaped. */
+const escapeKeyField = (value) => value.replace(/\\/g, "\\\\").replace(/\|/g, "\\|");
+/**
+ * The fields joined into one key, each escaped, so no two distinct field
+ * lists can produce the same string.
+ */
+export const joinKeyFields = (...fields) => fields.map(escapeKeyField).join("|");

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

@@ -0,0 +1,9 @@
+/**
+ * The Node built-ins Lambder uses where they exist, and nothing where they do
+ * not: the same code runs on Lambda and in a browser, so every one of these
+ * is optional and every caller handles null.
+ */
+export declare const getFS: () => Promise<typeof import('fs') | null>;
+export declare const getPath: () => Promise<typeof import('path') | null>;
+export declare const getZlib: () => Promise<typeof import('zlib') | null>;
+export declare const getCrypto: () => Promise<typeof import('crypto') | null>;

package/dist/shared/util/LambderNodeModules.js

@@ -0,0 +1,39 @@
+/**
+ * The Node built-ins Lambder uses where they exist, and nothing where they do
+ * not: the same code runs on Lambda and in a browser, so every one of these
+ * is optional and every caller handles null.
+ */
+/**
+ * One of these modules, or null where the runtime has no such thing.
+ *
+ * A failed import is only half of "no such thing". The other half is a
+ * bundler: package.json maps fs, path, zlib and crypto to `false` for the
+ * browser, and webpack, Vite and esbuild each honour that by resolving the
+ * import to a stub module rather than by rejecting it. Those stubs are
+ * objects, so a truthiness test calls them usable and the caller dies on the
+ * first real function it reaches. `expect` names a function the genuine
+ * module exports; a module that cannot answer it is not the module.
+ *
+ * The answer is memoized either way, absence included, so the probe runs once
+ * per module however often a request asks for it.
+ */
+const loadNodeModule = (load, expect) => {
+    let pending = null;
+    return () => {
+        pending ??= (async () => {
+            try {
+                const nodeModule = await load();
+                return typeof nodeModule?.[expect] === "function" ? nodeModule : null;
+            }
+            catch {
+                // Silently fail - we're in a browser environment
+                return null;
+            }
+        })();
+        return pending;
+    };
+};
+export const getFS = loadNodeModule(() => import('fs'), "readFile");
+export const getPath = loadNodeModule(() => import('path'), "join");
+export const getZlib = loadNodeModule(() => import('zlib'), "gunzip");
+export const getCrypto = loadNodeModule(() => import('crypto'), "createHash");

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

@@ -0,0 +1,17 @@
+/**
+ * The checks every option that names a count, a size or a duration goes
+ * through at creation, so a bad value is one wording and one predicate
+ * everywhere rather than seven spellings of the same rule. `name` is the
+ * option as the reader wrote it (`maxResponseBytes`, `session.ttlSeconds`),
+ * so the error says which one to fix.
+ */
+/** A safe integer of one or more; returns it so the check reads as an assignment. */
+export declare const assertPositiveInteger: (value: unknown, name: string) => number;
+/** A safe integer of zero or more; returns it so the check reads as an assignment. */
+export declare const assertNonNegativeInteger: (value: unknown, name: string) => number;
+/**
+ * A finite number at or above `minimum`, fractions included; returns it so
+ * the check reads as an assignment. For the options that scale something
+ * rather than count it, where 1.5 is a legitimate value.
+ */
+export declare const assertNumberAtLeast: (value: unknown, minimum: number, name: string) => number;

package/dist/shared/util/LambderOptionChecks.js

@@ -0,0 +1,33 @@
+/**
+ * The checks every option that names a count, a size or a duration goes
+ * through at creation, so a bad value is one wording and one predicate
+ * everywhere rather than seven spellings of the same rule. `name` is the
+ * option as the reader wrote it (`maxResponseBytes`, `session.ttlSeconds`),
+ * so the error says which one to fix.
+ */
+const describe = (value) => typeof value === "string" ? JSON.stringify(value) : String(value);
+/** A safe integer of one or more; returns it so the check reads as an assignment. */
+export const assertPositiveInteger = (value, name) => {
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 1) {
+        throw new Error(`Lambder: ${name} must be a positive integer, got ${describe(value)}.`);
+    }
+    return value;
+};
+/** A safe integer of zero or more; returns it so the check reads as an assignment. */
+export const assertNonNegativeInteger = (value, name) => {
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
+        throw new Error(`Lambder: ${name} must be a non-negative integer, got ${describe(value)}.`);
+    }
+    return value;
+};
+/**
+ * A finite number at or above `minimum`, fractions included; returns it so
+ * the check reads as an assignment. For the options that scale something
+ * rather than count it, where 1.5 is a legitimate value.
+ */
+export const assertNumberAtLeast = (value, minimum, name) => {
+    if (typeof value !== "number" || !Number.isFinite(value) || value < minimum) {
+        throw new Error(`Lambder: ${name} must be a number of ${minimum} or more, got ${describe(value)}.`);
+    }
+    return value;
+};

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

@@ -0,0 +1,20 @@
+/**
+ * Marks an object as a response without anyone having to import the class to
+ * ask. Layers that must recognise one but must not depend on core at runtime
+ * (the guards engine, which runs in the browser too) test for this key.
+ * Symbol.for keeps it true across realms and across duplicate copies of the
+ * package. Defined here, in shared, so the class that carries the brand and
+ * the engine that checks for it import the one constant: a hand-typed copy
+ * of the symbol's name would keep compiling after a rename while the runtime
+ * check silently stopped matching.
+ */
+export declare const LAMBDER_RESPONSE_BRAND: unique symbol;
+/**
+ * Whether a value carries the response brand. Tested by brand rather than by
+ * `instanceof`, so a browser-side engine stays free of a runtime dependency
+ * on core and keeps working across realms and duplicate copies of the
+ * package.
+ */
+export declare const isLambderResponseLike: (value: unknown) => value is {
+    readonly [LAMBDER_RESPONSE_BRAND]: true;
+};

package/dist/shared/util/LambderResponseBrand.js

@@ -0,0 +1,18 @@
+/**
+ * Marks an object as a response without anyone having to import the class to
+ * ask. Layers that must recognise one but must not depend on core at runtime
+ * (the guards engine, which runs in the browser too) test for this key.
+ * Symbol.for keeps it true across realms and across duplicate copies of the
+ * package. Defined here, in shared, so the class that carries the brand and
+ * the engine that checks for it import the one constant: a hand-typed copy
+ * of the symbol's name would keep compiling after a rename while the runtime
+ * check silently stopped matching.
+ */
+export const LAMBDER_RESPONSE_BRAND = Symbol.for("lambder.response");
+/**
+ * Whether a value carries the response brand. Tested by brand rather than by
+ * `instanceof`, so a browser-side engine stays free of a runtime dependency
+ * on core and keeps working across realms and duplicate copies of the
+ * package.
+ */
+export const isLambderResponseLike = (value) => typeof value === "object" && value !== null && value[LAMBDER_RESPONSE_BRAND] === true;

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

@@ -0,0 +1,17 @@
+/**
+ * SHA-256 over text through WebCrypto, as hex: 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).
+ */
+/** Lowercase hex of a byte array, two characters per byte. */
+export declare const bytesToHexString: (bytes: Uint8Array) => string;
+/**
+ * globalThis.crypto where the runtime has it, else Node's webcrypto (a Node
+ * without the global). Resolved once per process; a runtime with neither
+ * throws, naming what is missing.
+ */
+export declare const resolveWebCrypto: () => Promise<Crypto>;
+/** The SHA-256 digest of `text` (UTF-8), as 64 lowercase hex characters. */
+export declare const sha256HexOf: (text: string) => Promise<string>;

package/dist/shared/util/LambderTextDigest.js

@@ -0,0 +1,34 @@
+import { getCrypto } from "./LambderNodeModules.js";
+/**
+ * SHA-256 over text through WebCrypto, as hex: 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).
+ */
+/** 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("");
+let webCryptoPromise;
+/**
+ * globalThis.crypto where the runtime has it, else Node's webcrypto (a Node
+ * without the global). Resolved once per process; a runtime with neither
+ * throws, naming what is missing.
+ */
+export const resolveWebCrypto = () => {
+    webCryptoPromise ??= (async () => {
+        if (typeof globalThis.crypto?.subtle?.digest === "function")
+            return globalThis.crypto;
+        const nodeCrypto = await getCrypto();
+        const webCrypto = nodeCrypto?.webcrypto;
+        if (webCrypto?.subtle)
+            return webCrypto;
+        throw new Error("Lambder needs WebCrypto (crypto.subtle) in this runtime. A browser provides it on a secure context (https or localhost); Node 20+ provides it as globalThis.crypto.");
+    })();
+    return webCryptoPromise;
+};
+/** The SHA-256 digest of `text` (UTF-8), as 64 lowercase hex characters. */
+export const sha256HexOf = async (text) => {
+    const webCrypto = await resolveWebCrypto();
+    const digest = await webCrypto.subtle.digest("SHA-256", new TextEncoder().encode(text));
+    return bytesToHexString(new Uint8Array(digest));
+};

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

@@ -0,0 +1,33 @@
+/**
+ * The small type utilities more than one module needs.
+ *
+ * Nothing here is Lambder's own vocabulary: these are the shapes TypeScript
+ * does not ship, written once because the alternative is the same three
+ * lines in every module that wants them, drifting in name and in meaning.
+ */
+/**
+ * A value a caller may hand back either synchronously or as a promise. Every
+ * handler, hook and callback Lambder takes is declared over this: an app
+ * writes the synchronous form when it has nothing to await, and the framework
+ * awaits either.
+ */
+export type MaybePromise<T> = T | Promise<T>;
+/**
+ * A declaration map with AT LEAST ONE entry: the union, over every declarable
+ * name, of "this one required and the rest optional".
+ *
+ * An all-optional map is inhabited by `{}`, which would let `guards: {}`
+ * satisfy requireSessionApiGuards / requirePublicApiGuards at the type level
+ * while declaring no guard at all: the option is present, so the required-field
+ * check passes, and it normalizes to zero entries, so nothing runs. Requiring
+ * the chosen key also rejects `{ theGuard: undefined }`, which an optional
+ * property accepts and which would otherwise reach the guard's handler with an
+ * undefined param.
+ *
+ * Option-neutral, and the rate-limit option's map form is built with the same
+ * type: the two had drifted, and `rateLimit: {}` compiled while `guards: {}`
+ * did not.
+ */
+export type LambderNonEmptyOptionMap<TMap> = {
+    [K in keyof TMap]-?: Required<Pick<TMap, K>> & Omit<TMap, K>;
+}[keyof TMap];

package/dist/shared/util/LambderTypeUtilities.js

@@ -0,0 +1,8 @@
+/**
+ * The small type utilities more than one module needs.
+ *
+ * Nothing here is Lambder's own vocabulary: these are the shapes TypeScript
+ * does not ship, written once because the alternative is the same three
+ * lines in every module that wants them, drifting in name and in meaning.
+ */
+export {};