lambder 7.3.1 → 8.1.1

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/LambderTextDigest.d.ts

@@ -1,9 +1,9 @@
 /**
- * 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).
+ * 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.
  */
 /** Lowercase hex of a byte array, two characters per byte. */
 export declare const bytesToHexString: (bytes: Uint8Array) => string;
@@ -15,3 +15,5 @@ export declare const bytesToHexString: (bytes: Uint8Array) => string;
 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>;
+/** 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>;

package/dist/shared/util/LambderTextDigest.js

@@ -1,10 +1,11 @@
+import { bytesToBase64 } from "./LambderBase64.js";
 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).
+ * 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.
  */
 /** 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("");
@@ -32,3 +33,8 @@ export const sha256HexOf = async (text) => {
     const digest = await webCrypto.subtle.digest("SHA-256", new TextEncoder().encode(text));
     return bytesToHexString(new Uint8Array(digest));
 };
+/** The SHA-256 digest of `bytes`, as base64: the form object storage checks an upload's checksum in. */
+export const sha256Base64Of = async (bytes) => {
+    const webCrypto = await resolveWebCrypto();
+    return bytesToBase64(new Uint8Array(await webCrypto.subtle.digest("SHA-256", bytes)));
+};

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>;

package/dist/shared/util/boundKeyField.js

@@ -0,0 +1,34 @@
+/**
+ * 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.
+ */
+import { joinKeyFields } from "./joinKeyFields.js";
+import { sha256HexOf } from "./LambderTextDigest.js";
+/**
+ * The ceiling, in UTF-8 bytes, on the field as it is written into the key;
+ * past it, the field is replaced by its digest. Measured escaped, since
+ * joinKeyFields doubles every separator and escape character: a field of
+ * 1,000 separators is 2,000 bytes in the key. 1024 sits well inside every
+ * store's key limit, with the store's prefix and the engine's other fields
+ * (API and policy names, a posted idempotency key of at most 200 characters)
+ * joined around it.
+ */
+const MAX_KEY_FIELD_BYTES = 1024;
+/**
+ * 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 const boundKeyField = async (kind, value) => new TextEncoder().encode(joinKeyFields(value)).length > MAX_KEY_FIELD_BYTES
+    ? `${kind}:h:${await sha256HexOf(value)}`
+    : `${kind}:${value}`;

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

@@ -0,0 +1,11 @@
+/**
+ * JSON with object keys sorted at every level, so two values that are the
+ * same data hash the same whatever order their keys were built in. Arrays
+ * keep their order: a tuple's positions and an enum's values are part of the
+ * data. Undefined entries are dropped, as JSON.stringify would drop them.
+ *
+ * What the API signature digests a schema's description with, and what the
+ * idempotency engine fingerprints a request with: two hashes that must not
+ * depend on the order a client or a builder happened to write keys in.
+ */
+export declare const canonicalJson: (value: unknown) => string;

package/dist/shared/util/canonicalJson.js

@@ -0,0 +1,28 @@
+/**
+ * JSON with object keys sorted at every level, so two values that are the
+ * same data hash the same whatever order their keys were built in. Arrays
+ * keep their order: a tuple's positions and an enum's values are part of the
+ * data. Undefined entries are dropped, as JSON.stringify would drop them.
+ *
+ * What the API signature digests a schema's description with, and what the
+ * idempotency engine fingerprints a request with: two hashes that must not
+ * depend on the order a client or a builder happened to write keys in.
+ */
+export const canonicalJson = (value) => JSON.stringify(sortKeys(value));
+const sortKeys = (value) => {
+    if (Array.isArray(value))
+        return value.map(sortKeys);
+    if (value === null || typeof value !== "object")
+        return value;
+    const source = value;
+    // No prototype, so a "__proto__" key (JSON.parse makes it an own key) is
+    // kept as data. On a plain object the assignment would set the prototype
+    // instead, and two payloads differing only under "__proto__" would share
+    // one fingerprint.
+    const sorted = Object.create(null);
+    for (const key of Object.keys(source).sort()) {
+        if (source[key] !== undefined)
+            sorted[key] = sortKeys(source[key]);
+    }
+    return sorted;
+};

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

@@ -0,0 +1,20 @@
+/**
+ * Joining the fields of a tracker or scope key.
+ *
+ * The rate limiter and the idempotency engine each join fields with a
+ * separator, and at least one field is caller data (a policy's rate-limit
+ * key, a posted idempotency key). A plain join lets two field lists produce
+ * one string, so two callers would share a counter or one would read
+ * another's stored answer. The caller's separator is escaped, not refused: a
+ * limit that rejects a legal key is a bug of its own.
+ *
+ * The join is one-way (a key is looked up or compared, never taken apart),
+ * unlike LambderDdbCache's reversible sort-key escape, which listSortKeys
+ * must decode to exactly what was written; neither stands in for the other.
+ * Both engines share this one implementation so they cannot drift apart.
+ */
+/**
+ * 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/joinKeyFields.js

@@ -0,0 +1,22 @@
+/**
+ * Joining the fields of a tracker or scope key.
+ *
+ * The rate limiter and the idempotency engine each join fields with a
+ * separator, and at least one field is caller data (a policy's rate-limit
+ * key, a posted idempotency key). A plain join lets two field lists produce
+ * one string, so two callers would share a counter or one would read
+ * another's stored answer. The caller's separator is escaped, not refused: a
+ * limit that rejects a legal key is a bug of its own.
+ *
+ * The join is one-way (a key is looked up or compared, never taken apart),
+ * unlike LambderDdbCache's reversible sort-key escape, which listSortKeys
+ * must decode to exactly what was written; neither stands in for the other.
+ * Both engines share this one implementation so they cannot drift apart.
+ */
+/** 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("|");