lambder 7.3.1 → 8.0.2

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

@@ -13,20 +13,36 @@ export declare const LOOPBACK_CLIENT_IP = "127.0.0.1";
 /**
  * One textual form per address, so a rate-limit counter cannot be split.
  * A forwarding proxy may write the RFC 7239 bracket-and-port form
- * ([2001:db8::1]:443) or a plain host:port, and IPv6 has many spellings for
- * one address; each variant would otherwise be its own counter, which is a
- * limit that does not limit. Anything longer than the longest valid address
- * is truncated rather than trusted as a key.
+ * ([2001:db8::1]:443) or a plain host:port; each variant would otherwise be
+ * its own counter, which is a limit that does not limit. An unbracketed IPv6
+ * address with a port after it cannot be told apart by its text
+ * (`2001:db8::1:443` is an address too), so this leaves it alone; the header
+ * that writes that form has its port taken off by resolveClientIp, which
+ * knows where the value came from. Anything longer than the longest valid
+ * address is truncated rather than trusted as a key.
  */
 export declare const normalizeClientIp: (value: string) => string;
+/** The IPv6 prefix a per-IP rate limit counts by default: the /64 every subscriber holds at least. */
+export declare const DEFAULT_IPV6_RATE_LIMIT_PREFIX = 64;
+/**
+ * The caller a per-IP rate limit counts, which is not always the address
+ * itself. An IPv4 address is one subscriber. An IPv6 subscriber, a VPS
+ * included, holds at least a /64 and may pick any interface id inside it, so
+ * one counter per full address is a fresh counter per request for anyone
+ * who rotates: the prefix is what is counted (`2001:db8:1:2:0:0:0:0/64`). An
+ * IPv4-mapped IPv6 address (::ffff:192.0.2.1) is its IPv4 address, so the
+ * two spellings share a counter. A value that is not an address is counted
+ * as it is. ctx.ip itself stays the exact address, for logs.
+ */
+export declare const rateLimitSubjectOf: (ip: string, ipv6PrefixLength?: number) => string;
 /**
  * The first trusted header that carries anything, leftmost entry, else the
- * address the gateway observed. Nothing is trusted by default, and there is
- * no exception for an invoke: the marker header that would have signalled
- * one is an ordinary request header that any HTTP caller can set, so
- * honouring it would hand every caller the value again. A genuine invoke
- * needs no exception, because the synthesized event carries the end user's
- * address in requestContext.http.sourceIp, which is where `sourceIp` comes
- * from anyway.
+ * address the gateway observed; a header that always appends the port (see
+ * PORT_SUFFIXED_IP_HEADERS) has it taken off. Nothing is trusted by default,
+ * and there is no exception for an invoke: the invoke marker is an ordinary
+ * request header any HTTP caller can set, so honouring it would let every
+ * caller choose its own address. A genuine invoke needs no exception,
+ * because the synthesized event carries the end user's address in
+ * requestContext.http.sourceIp, which is where `sourceIp` comes from anyway.
  */
 export declare const resolveClientIp: (lowercasedHeaders: Record<string, string>, sourceIp: string, trustedClientIpHeaders?: readonly string[]) => string;

package/dist/shared/util/LambderClientIp.js

@@ -12,13 +12,60 @@
 export const LOOPBACK_CLIENT_IP = "127.0.0.1";
 /** Longest textual IPv6 address (39) plus a scope id; beyond this the value is not an address. */
 const MAX_CLIENT_IP_LENGTH = 45;
+/** A dotted IPv4 address as its four octets, or null when the text is not one. */
+const parseIpv4 = (value) => {
+    const parts = value.split(".");
+    if (parts.length !== 4 || !parts.every((part) => /^\d{1,3}$/.test(part)))
+        return null;
+    const octets = parts.map(Number);
+    return octets.every((octet) => octet <= 255) ? octets : null;
+};
+/**
+ * An IPv6 address as its eight 16-bit groups, or null when the text is not
+ * one: every spelling of one address (compressed or not, any case, with an
+ * embedded IPv4 tail) parses to the same groups.
+ */
+const parseIpv6 = (value) => {
+    // A zone id names the interface an address was reached on, not the address.
+    let text = value.split("%")[0];
+    const lastColon = text.lastIndexOf(":");
+    if (lastColon === -1)
+        return null;
+    const tail = text.slice(lastColon + 1);
+    if (tail.includes(".")) {
+        const octets = parseIpv4(tail);
+        if (!octets)
+            return null;
+        text = `${text.slice(0, lastColon + 1)}${((octets[0] << 8) | octets[1]).toString(16)}:${((octets[2] << 8) | octets[3]).toString(16)}`;
+    }
+    const halves = text.split("::");
+    if (halves.length > 2)
+        return null;
+    const groupsOf = (part) => {
+        if (part === "")
+            return [];
+        const groups = part.split(":");
+        return groups.every((group) => /^[0-9a-f]{1,4}$/i.test(group)) ? groups.map((group) => parseInt(group, 16)) : null;
+    };
+    const head = groupsOf(halves[0]);
+    const rest = halves.length === 2 ? groupsOf(halves[1]) : [];
+    if (!head || !rest)
+        return null;
+    if (halves.length === 1)
+        return head.length === 8 ? head : null;
+    const missing = 8 - head.length - rest.length;
+    return missing >= 1 ? [...head, ...new Array(missing).fill(0), ...rest] : null;
+};
 /**
  * One textual form per address, so a rate-limit counter cannot be split.
  * A forwarding proxy may write the RFC 7239 bracket-and-port form
- * ([2001:db8::1]:443) or a plain host:port, and IPv6 has many spellings for
- * one address; each variant would otherwise be its own counter, which is a
- * limit that does not limit. Anything longer than the longest valid address
- * is truncated rather than trusted as a key.
+ * ([2001:db8::1]:443) or a plain host:port; each variant would otherwise be
+ * its own counter, which is a limit that does not limit. An unbracketed IPv6
+ * address with a port after it cannot be told apart by its text
+ * (`2001:db8::1:443` is an address too), so this leaves it alone; the header
+ * that writes that form has its port taken off by resolveClientIp, which
+ * knows where the value came from. Anything longer than the longest valid
+ * address is truncated rather than trusted as a key.
  */
 export const normalizeClientIp = (value) => {
     let ip = value.trim();
@@ -35,22 +82,58 @@ export const normalizeClientIp = (value) => {
     }
     return ip.toLowerCase().slice(0, MAX_CLIENT_IP_LENGTH);
 };
+/**
+ * Headers whose value always ends in `:port`, whatever the address before
+ * it: CloudFront-Viewer-Address writes `192.0.2.1:443` and
+ * `2001:db8::1:443` alike, with no brackets. The last colon-separated
+ * segment of such a value is the port by definition. Read from the text
+ * instead, a compressed IPv6 address with its port on still parses, the port
+ * becomes its last group, and the /64 a per-IP limit counts moves with the
+ * interface id the caller picks.
+ */
+const PORT_SUFFIXED_IP_HEADERS = new Set(["cloudfront-viewer-address"]);
+/** The IPv6 prefix a per-IP rate limit counts by default: the /64 every subscriber holds at least. */
+export const DEFAULT_IPV6_RATE_LIMIT_PREFIX = 64;
+/**
+ * The caller a per-IP rate limit counts, which is not always the address
+ * itself. An IPv4 address is one subscriber. An IPv6 subscriber, a VPS
+ * included, holds at least a /64 and may pick any interface id inside it, so
+ * one counter per full address is a fresh counter per request for anyone
+ * who rotates: the prefix is what is counted (`2001:db8:1:2:0:0:0:0/64`). An
+ * IPv4-mapped IPv6 address (::ffff:192.0.2.1) is its IPv4 address, so the
+ * two spellings share a counter. A value that is not an address is counted
+ * as it is. ctx.ip itself stays the exact address, for logs.
+ */
+export const rateLimitSubjectOf = (ip, ipv6PrefixLength = DEFAULT_IPV6_RATE_LIMIT_PREFIX) => {
+    const groups = parseIpv6(ip);
+    if (!groups)
+        return ip;
+    if (groups.slice(0, 5).every((group) => group === 0) && groups[5] === 0xffff) {
+        return `${groups[6] >> 8}.${groups[6] & 0xff}.${groups[7] >> 8}.${groups[7] & 0xff}`;
+    }
+    const masked = groups.map((group, index) => {
+        const kept = Math.max(0, Math.min(16, ipv6PrefixLength - index * 16));
+        return kept === 0 ? 0 : group & ((0xffff << (16 - kept)) & 0xffff);
+    });
+    return `${masked.map((group) => group.toString(16)).join(":")}/${ipv6PrefixLength}`;
+};
 /**
  * The first trusted header that carries anything, leftmost entry, else the
- * address the gateway observed. Nothing is trusted by default, and there is
- * no exception for an invoke: the marker header that would have signalled
- * one is an ordinary request header that any HTTP caller can set, so
- * honouring it would hand every caller the value again. A genuine invoke
- * needs no exception, because the synthesized event carries the end user's
- * address in requestContext.http.sourceIp, which is where `sourceIp` comes
- * from anyway.
+ * address the gateway observed; a header that always appends the port (see
+ * PORT_SUFFIXED_IP_HEADERS) has it taken off. Nothing is trusted by default,
+ * and there is no exception for an invoke: the invoke marker is an ordinary
+ * request header any HTTP caller can set, so honouring it would let every
+ * caller choose its own address. A genuine invoke needs no exception,
+ * because the synthesized event carries the end user's address in
+ * requestContext.http.sourceIp, which is where `sourceIp` comes from anyway.
  */
 export const resolveClientIp = (lowercasedHeaders, sourceIp, trustedClientIpHeaders = []) => {
     for (const name of trustedClientIpHeaders) {
-        const value = lowercasedHeaders[name.toLowerCase()];
+        const header = name.toLowerCase();
+        const value = lowercasedHeaders[header];
         const first = value ? (value.split(",")[0] ?? "").trim() : "";
         if (first)
-            return normalizeClientIp(first);
+            return normalizeClientIp(PORT_SUFFIXED_IP_HEADERS.has(header) ? first.replace(/:\d+$/, "") : first);
     }
     return normalizeClientIp(sourceIp) || "";
 };

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

@@ -1,48 +1,38 @@
 /**
- * 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.
+ * A Map whose entries expire, which 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.
+ * Entries expire on read and on an amortized sweep, so no caller has to
+ * remember either. Expiring only when the same key is read again would leak
+ * in anything long-lived: a counter nobody asks about again, or a record for
+ * a key that never returns, would stay for as long as the process runs.
  *
- * 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.
+ * Expiry bounds how long an entry lives, not how many there are: a workload
+ * that never repeats a key (a per-IP counter with a monthly window, an
+ * idempotency key per request) accumulates live entries faster than expiry
+ * retires them. So the map also holds a ceiling, where it evicts the
+ * evictable entries that expire soonest. Insertion order would instead
+ * retire the entries with the most life left (long-window counters, day-long
+ * idempotency records), letting a flood of short-lived keys reset a monthly
+ * cap; soonest-to-expire costs the caller least, 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
+ * An idempotency claim lives minutes while the record it settles into lives
+ * a day, so at the ceiling it would always be the first victim and two
+ * concurrent retries would both execute. An entry written with `evictable:
+ * false` is never chosen, and a write that cannot be made room for is
+ * refused (LambderExpiringMapFullError) rather than 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.
+ * Times are epoch seconds, matching DynamoDB's TTL attribute, 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.
+ * to make room for it: the caller decides what to do about a store full of
+ * live claims, and a claim somebody else holds is never traded away.
  */
 export declare class LambderExpiringMapFullError extends Error {
     constructor(maxEntries: number);
@@ -97,22 +87,18 @@ export declare class LambderExpiringMap<TValue> {
      * 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.
+     * Evicting costs the caller whatever the entry protected (a counter
+     * resets, a stored answer re-executes on retry), so the entries taken are
+     * those with the least life left, and 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.
+     * A batch rather than one entry, because one leaves the map exactly at
+     * its ceiling and the next write pays for another pass: one pass per
+     * write for as long as the flood lasts. At 100,000 entries that is 0.56
+     * ms per write, against 0.007 ms with 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.
+     * The pass is linear and the sort covers only evictable entries, which is
+     * affordable because reaching the ceiling at all is already pathological.
      */
     private evictBatch;
     private sweep;

package/dist/shared/util/LambderExpiringMap.js

@@ -1,65 +1,53 @@
 /**
- * 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.
+ * A Map whose entries expire, which 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.
+ * Entries expire on read and on an amortized sweep, so no caller has to
+ * remember either. Expiring only when the same key is read again would leak
+ * in anything long-lived: a counter nobody asks about again, or a record for
+ * a key that never returns, would stay for as long as the process runs.
  *
- * 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.
+ * Expiry bounds how long an entry lives, not how many there are: a workload
+ * that never repeats a key (a per-IP counter with a monthly window, an
+ * idempotency key per request) accumulates live entries faster than expiry
+ * retires them. So the map also holds a ceiling, where it evicts the
+ * evictable entries that expire soonest. Insertion order would instead
+ * retire the entries with the most life left (long-window counters, day-long
+ * idempotency records), letting a flood of short-lived keys reset a monthly
+ * cap; soonest-to-expire costs the caller least, 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
+ * An idempotency claim lives minutes while the record it settles into lives
+ * a day, so at the ceiling it would always be the first victim and two
+ * concurrent retries would both execute. An entry written with `evictable:
+ * false` is never chosen, and a write that cannot be made room for is
+ * refused (LambderExpiringMapFullError) rather than 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.
+ * Times are epoch seconds, matching DynamoDB's TTL attribute, 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.
+ * Live entries held before eviction starts. 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.
+ * Share of the ceiling one eviction pass reclaims, so the pass is amortized
+ * over the writes the headroom absorbs (see evictBatch).
  */
 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.
+ * to make room for it: the caller decides what to do about a store full of
+ * live claims, and a claim somebody else holds is never traded away.
  */
 export class LambderExpiringMapFullError extends Error {
     constructor(maxEntries) {
@@ -160,22 +148,18 @@ export class LambderExpiringMap {
      * 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.
+     * Evicting costs the caller whatever the entry protected (a counter
+     * resets, a stored answer re-executes on retry), so the entries taken are
+     * those with the least life left, and 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.
+     * A batch rather than one entry, because one leaves the map exactly at
+     * its ceiling and the next write pays for another pass: one pass per
+     * write for as long as the flood lasts. At 100,000 entries that is 0.56
+     * ms per write, against 0.007 ms with 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.
+     * The pass is linear and the sort covers only evictable entries, which is
+     * affordable because reaching the ceiling at all is already pathological.
      */
     evictBatch(justWritten) {
         const floorSize = Math.max(0, this.maxEntries - this.evictionBatchSize);

package/dist/shared/util/LambderNodeModules.js

@@ -8,14 +8,13 @@
  *
  * 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.
+ * browser, and webpack, Vite and esbuild resolve such an import to a stub
+ * object rather than rejecting it, so a truthiness test would call the stub
+ * usable and the caller would die on its first real call. `expect` names a
+ * function the genuine module exports; a module without 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.
+ * The answer, absence included, is memoized, so the probe runs once per
+ * module.
  */
 const loadNodeModule = (load, expect) => {
     let pending = null;

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

@@ -1,9 +1,9 @@
 /**
  * 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.
+ * through at creation, so a bad value meets one predicate and one wording
+ * everywhere. `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;

package/dist/shared/util/LambderOptionChecks.js

@@ -1,9 +1,9 @@
 /**
  * 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.
+ * through at creation, so a bad value meets one predicate and one wording
+ * everywhere. `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. */

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

@@ -2,11 +2,11 @@
  * 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.
+ * Symbol.for keeps it true across realms and duplicate copies of the
+ * package. Defined in shared so the class that carries the brand and the
+ * engine that checks it import 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;
 /**

package/dist/shared/util/LambderResponseBrand.js

@@ -2,11 +2,11 @@
  * 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.
+ * Symbol.for keeps it true across realms and duplicate copies of the
+ * package. Defined in shared so the class that carries the brand and the
+ * engine that checks it import 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");
 /**

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

@@ -1,9 +1,9 @@
 /**
  * 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.
+ * Nothing here is Lambder's own vocabulary: these are shapes TypeScript does
+ * not ship, written once so they cannot drift in name or meaning across the
+ * modules that use them.
  */
 /**
  * A value a caller may hand back either synchronously or as a promise. Every
@@ -18,15 +18,14 @@ export type MaybePromise<T> = T | Promise<T>;
  *
  * 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
+ * while declaring no guard: 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
+ * property accepts and which would 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.
+ * Option-neutral: the rate-limit option's map form uses it too, so
+ * `rateLimit: {}` and `guards: {}` are refused alike.
  */
 export type LambderNonEmptyOptionMap<TMap> = {
     [K in keyof TMap]-?: Required<Pick<TMap, K>> & Omit<TMap, K>;

package/dist/shared/util/LambderTypeUtilities.js

@@ -1,8 +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.
+ * Nothing here is Lambder's own vocabulary: these are shapes TypeScript does
+ * not ship, written once so they cannot drift in name or meaning across the
+ * modules that use them.
  */
 export {};

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

@@ -0,0 +1,20 @@
+/**
+ * Bounding the caller-supplied field of a tracker or scope key.
+ *
+ * The rate-limit engine and the idempotency engine each build a store key
+ * around a field only the caller controls: a custom rate-limit key or a
+ * session key, a callerIdentity or a session key. A store has a key limit of
+ * its own (a DynamoDB partition key stops at 2048 bytes) and refuses a key
+ * past it by throwing, and both engines fail open on a store throw by
+ * default: a long enough field (a 3,000-character email, a device token)
+ * would turn the rate limit or the idempotency off for that caller, in
+ * silence, while the table held the field in plain text. So the field is
+ * bounded before any store sees it, in one implementation the two engines
+ * share, so they cannot drift apart.
+ */
+/**
+ * The field bounded: `<kind>:<value>` while the value fits, `<kind>:h:<sha256
+ * hex>` once it does not. The digest keeps distinct callers on distinct
+ * counters and scopes, and a value that fits stays readable in the table.
+ */
+export declare const boundKeyField: (kind: string, value: string) => Promise<string>;