@fuzdev/fuz_app 0.141.0 → 0.143.0

package/dist/http/ip_canonical.js

@@ -18,7 +18,8 @@
  *    strings (`'unknown'`, `'attacker:controlled'`, `'::1\n'`) pass
  *    through unchanged so downstream strict validators can still
  *    reject them.
- * 2. Parses via Hono's `convertIPv*ToBinary` family.
+ * 2. Parses with `parse_ipv4_bits` / `parse_ipv6_bits` — the grammar of
+ *    Rust's `IpAddr::from_str`, which the spine parses with.
  * 3. Re-emits the canonical RFC 5952 string (lowercase hex,
  *    longest-zero-run compressed, IPv4-mapped emitted in the dotted
  *    form mandated by RFC 5952 §5).
@@ -27,13 +28,102 @@
  *    canonicalization because the dotted form is the only form the
  *    strip can recognize symmetrically.
  *
- * Mirrors `zzz_server::proxy::normalize_ip` (landed 2026-05-16) which
- * uses the same parse-then-canonicalize-then-strip ordering for the
- * same rate-limit-key-poisoning surface.
+ * Mirrors the Rust spine's `fuz_http::normalize_ip`, which uses the same
+ * parse-then-canonicalize-then-strip ordering for the same
+ * rate-limit-key-poisoning surface.
+ *
+ * `rate_limit_ip_key` is the bucket key an IP-keyed rate limiter uses: an
+ * IPv6 address collapses to its `/64`, the smallest block a host is commonly
+ * assigned, so rotating through one's own subnet buys no fresh budget. Only
+ * the limiter call sites apply it — the client IP stays the full address
+ * everywhere else (audit rows, token `last_used_ip`, `REMOTE_ADDR`).
+ *
+ * The module imports nothing: the action dispatcher keys its IP limiter
+ * through it, so it must not pull the optional `hono` peer.
  *
  * @module
  */
-import { convertIPv6ToBinary, distinctRemoteAddr } from 'hono/utils/ipaddr';
+/** A dotted-quad IPv4 address: four decimal octets, 0–255, no leading zeros. */
+const IPV4_REGEX = /^(?:(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])\.){3}(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])$/;
+/** One IPv6 group: one to four hex digits. */
+const IPV6_GROUP_REGEX = /^[0-9a-fA-F]{1,4}$/;
+/**
+ * Parse a dotted-quad IPv4 address to its 32-bit value.
+ *
+ * Four decimal octets, each 0–255 with no leading zeros (`01.2.3.4` is
+ * refused, as Rust's `Ipv4Addr::from_str` refuses it).
+ *
+ * @returns the address as an unsigned 32-bit number, or `null` when `ip` isn't one
+ */
+export const parse_ipv4_bits = (ip) => {
+    if (!IPV4_REGEX.test(ip))
+        return null;
+    let bits = 0;
+    for (const octet of ip.split('.'))
+        bits = bits * 256 + Number(octet);
+    return bits;
+};
+/**
+ * Parse the colon-separated groups on one side of a `::` (or the whole
+ * address when there is none), `null` on a malformed one. Only the last group
+ * of the address may be a dotted-quad IPv4 tail, which fills two groups.
+ */
+const parse_ipv6_groups = (part, allow_ipv4_tail) => {
+    if (part === '')
+        return [];
+    const pieces = part.split(':');
+    const groups = [];
+    for (let i = 0; i < pieces.length; i++) {
+        const piece = pieces[i];
+        if (allow_ipv4_tail && i === pieces.length - 1 && piece.includes('.')) {
+            const ipv4 = parse_ipv4_bits(piece);
+            if (ipv4 === null)
+                return null;
+            groups.push(Math.floor(ipv4 / 0x10000), ipv4 % 0x10000);
+        }
+        else if (IPV6_GROUP_REGEX.test(piece)) {
+            groups.push(parseInt(piece, 16));
+        }
+        else {
+            return null;
+        }
+    }
+    return groups;
+};
+/**
+ * Parse an IPv6 address to its 128-bit value.
+ *
+ * The grammar of Rust's `Ipv6Addr::from_str`: eight groups of one to four
+ * hex digits (either case), or fewer around a single `::` standing for one or
+ * more zero groups, the last two groups optionally written as a dotted-quad
+ * IPv4 address. No zone (`%eth0`) — callers strip it first.
+ *
+ * @returns the address as a `bigint` in `[0, 2^128)`, or `null` when `ip` isn't one
+ */
+export const parse_ipv6_bits = (ip) => {
+    const halves = ip.split('::');
+    let groups;
+    if (halves.length === 1) {
+        const all = parse_ipv6_groups(ip, true);
+        if (all === null || all.length !== 8)
+            return null;
+        groups = all;
+    }
+    else if (halves.length === 2) {
+        const head = parse_ipv6_groups(halves[0], false);
+        const tail = parse_ipv6_groups(halves[1], true);
+        if (head === null || tail === null || head.length + tail.length > 7)
+            return null;
+        groups = [...head, ...new Array(8 - head.length - tail.length).fill(0), ...tail];
+    }
+    else {
+        return null;
+    }
+    let bits = 0n;
+    for (const group of groups)
+        bits = (bits << 16n) | BigInt(group);
+    return bits;
+};
 /**
  * Allowed character set for a bare IP literal.
  *
@@ -80,39 +170,27 @@ export const IP_LITERAL_CHARS = /^[0-9a-fA-F.:]+$/;
 export const canonicalize_ip = (ip) => {
     const lowered = ip.toLowerCase();
     // Strict char-set filter — reject brackets, whitespace, control bytes,
-    // letters g-z before invoking the parser. Hono's `convertIPv6ToBinary`
-    // silently accepts `'::1\n'` and similar; canonicalizing those would
-    // erase the malformed form so downstream `validate_ip_strict` could no
-    // longer reject it. Pass-through preserves the original string.
+    // letters g-z, and `%` (so a zone) before invoking the parser, so a
+    // malformed form passes through for downstream `validate_ip_strict` to
+    // reject
     if (!IP_LITERAL_CHARS.test(lowered))
         return lowered;
-    const family = distinctRemoteAddr(lowered);
-    if (family === 'IPv4') {
-        // IPv4's dotted-decimal form is already canonical — no transform
-        // needed. Malformed forms (`999.999.999.999`) still pass through
-        // here; downstream `validate_ip_strict` rejects them via its own
-        // round-trip parse.
+    // IPv4's dotted-decimal form is already canonical — no transform needed.
+    // Malformed forms (`999.999.999.999`) fail both parsers and pass through.
+    if (parse_ipv4_bits(lowered) !== null)
         return lowered;
+    const bits = parse_ipv6_bits(lowered);
+    if (bits === null)
+        return lowered;
+    const canonical = ipv6_bigint_to_canonical(bits);
+    // Strip `::ffff:` only when the canonical form is dotted IPv4-mapped
+    // (`::ffff:X.X.X.X`). Pure IPv6 values that happen to start with
+    // `::ffff:` (e.g. `::ffff:1` → `0:0:0:0:0:0:ffff:1`, where group[5] is 0
+    // not 0xffff) emit without the dot and are preserved.
+    if (canonical.startsWith('::ffff:') && canonical.substring(7).includes('.')) {
+        return canonical.substring(7);
     }
-    if (family === 'IPv6') {
-        try {
-            const bits = convertIPv6ToBinary(lowered);
-            const canonical = ipv6_bigint_to_canonical(bits);
-            // Strip `::ffff:` only when the canonical form is dotted
-            // IPv4-mapped (`::ffff:X.X.X.X`). Pure IPv6 values that happen
-            // to start with `::ffff:` (e.g. `::ffff:1` → `0:0:0:0:0:0:ffff:1`,
-            // where group[5] is 0 not 0xffff) emit without the dot and
-            // are preserved.
-            if (canonical.startsWith('::ffff:') && canonical.substring(7).includes('.')) {
-                return canonical.substring(7);
-            }
-            return canonical;
-        }
-        catch {
-            return lowered;
-        }
-    }
-    return lowered;
+    return canonical;
 };
 /**
  * Convert a 128-bit IPv6 binary value into its RFC 5952 canonical string form.
@@ -126,7 +204,7 @@ export const canonicalize_ip = (ip) => {
  *
  * Pure helper exported for the test suite to exercise the
  * canonicalization invariants directly without a full
- * `convertIPv6ToBinary` round-trip.
+ * `parse_ipv6_bits` round-trip.
  *
  * @param bits - the 128-bit IPv6 value as `bigint`. Must satisfy `0n <= bits < 2n ** 128n`;
  *   throws `RangeError` otherwise. Silent truncation would mask caller bugs since the
@@ -193,3 +271,37 @@ export const ipv6_bigint_to_canonical = (bits) => {
         .join(':');
     return before + '::' + after;
 };
+/** The high 64 bits of an IPv6 address — its `/64` network prefix. */
+const IPV6_PREFIX_64_MASK = ((1n << 64n) - 1n) << 64n;
+/**
+ * The bucket key an IP-keyed rate limiter uses for client IP `ip`.
+ *
+ * An IPv6 address keys its `/64`: the low 64 bits masked off, rendered in
+ * RFC 5952 canonical form with a `/64` suffix (`2001:db8:1:2::/64`; the
+ * all-zero prefix is `::/64`). A zone suffix (`%eth0`) is dropped first. An
+ * IPv4 address — an IPv4-mapped IPv6 one included — keys its canonical form,
+ * with no suffix. Anything that doesn't parse (`'unknown'` among them) is
+ * returned unchanged. Twin of the Rust spine's `fuz_http::rate_limit_ip_key`.
+ *
+ * For limiter keys only: audit rows and every other record of the client
+ * keep the full address.
+ *
+ * @example
+ * rate_limit_ip_key('2001:db8:1:2::1')        // → '2001:db8:1:2::/64'
+ * rate_limit_ip_key('2001:db8:1:2:8000::')    // → '2001:db8:1:2::/64'
+ * rate_limit_ip_key('fe80::1%eth0')           // → 'fe80::/64'
+ * rate_limit_ip_key('203.0.113.7')            // → '203.0.113.7'
+ * rate_limit_ip_key('unknown')                // → 'unknown'
+ */
+export const rate_limit_ip_key = (ip) => {
+    const zone_at = ip.indexOf('%');
+    const canonical = canonicalize_ip(zone_at === -1 ? ip : ip.slice(0, zone_at));
+    if (!IP_LITERAL_CHARS.test(canonical))
+        return ip;
+    if (parse_ipv4_bits(canonical) !== null)
+        return canonical;
+    const bits = parse_ipv6_bits(canonical);
+    if (bits === null)
+        return ip;
+    return `${ipv6_bigint_to_canonical(bits & IPV6_PREFIX_64_MASK)}/64`;
+};

package/dist/primitive_schemas.d.ts

@@ -117,7 +117,16 @@ export declare const Email: z.ZodString;
 export type Email = z.infer<typeof Email>;
 /** Returns a new random (v4) `Uuid`. */
 export declare const create_uuid: () => Uuid;
-/** Branded UUID schema. */
+/**
+ * Branded UUID schema. Accepts either case and outputs lowercase — the form
+ * Postgres renders a `uuid` in and every id the server mints — so a parsed id
+ * compares equal to the same id read back from the database. The Rust spine
+ * canonicalizes the same way.
+ *
+ * `.toLowerCase()` rather than `.transform()`: an overwrite keeps the output
+ * type and stays invisible to `z.toJSONSchema`, where a transform would leave
+ * no input schema to render.
+ */
 export declare const Uuid: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
 export type Uuid = z.infer<typeof Uuid>;
 /** `Uuid` that defaults to a fresh `create_uuid()` when the input is `undefined`. */

package/dist/primitive_schemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"primitive_schemas.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/primitive_schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAmB,KAAK,QAAQ,EAAE,MAAM,kCAAkC,CAAC;AAIlF,gEAAgE;AAChE,MAAM,WAAW,oBAAoB;IACpC,yDAAyD;IACzD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,+BAA+B;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,mEAAmE;IACnE,WAAW,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,cAAc,GAAI,2BAA2B,oBAAoB,KAAG,CAAC,CAAC,SA8ClF,CAAC;AAEF,2EAA2E;AAC3E,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAErC,6GAA6G;AAC7G,eAAO,MAAM,mBAAmB,KAAK,CAAC;AAEtC,gNAAgN;AAChN,eAAO,MAAM,4BAA4B,MAAM,CAAC;AAEhD;;;;;;;;;GASG;AACH,eAAO,MAAM,QAAQ,wDAEc,CAAC;AACpC,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,QAAQ,CAAC,CAAC;AAEhD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,gBAAgB,wDAEqE,CAAC;AACnG,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEhE;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,MAAM,CAAC;AAqBpC;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,KAAK,aAYhB,CAAC;AACH,MAAM,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,KAAK,CAAC,CAAC;AAE1C,wCAAwC;AACxC,eAAO,MAAM,WAAW,QAAO,IAAmC,CAAC;AAEnE,2BAA2B;AAC3B,eAAO,MAAM,IAAI,8CAAyB,CAAC;AAC3C,MAAM,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,IAAI,CAAC,CAAC;AAExC,qFAAqF;AACrF,eAAO,MAAM,eAAe,4DAA4B,CAAC;AACzD,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE9D,wCAAwC;AACxC,eAAO,MAAM,QAAQ,yDAAqC,CAAC;AAC3D,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,QAAQ,CAAC,CAAC;AAEhD,gEAAgE;AAChE,eAAO,MAAM,gBAAgB,QAAO,QAAgD,CAAC;AAErF,sFAAsF;AACtF,eAAO,MAAM,WAAW,uEAAqC,CAAC;AAC9D,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEtD,uFAAuF;AACvF,eAAO,MAAM,UAAU,aAEuD,CAAC;AAC/E,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEpD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,cAAc,EAAE,CAAC,CAAC,SAAS,GAAG,CAAC,CAAC,OAAO,CAAC,QAAQ,EAAE,MAAM,CAEA,CAAC"}
+{"version":3,"file":"primitive_schemas.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/primitive_schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAmB,KAAK,QAAQ,EAAE,MAAM,kCAAkC,CAAC;AAIlF,gEAAgE;AAChE,MAAM,WAAW,oBAAoB;IACpC,yDAAyD;IACzD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,+BAA+B;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,mEAAmE;IACnE,WAAW,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,cAAc,GAAI,2BAA2B,oBAAoB,KAAG,CAAC,CAAC,SA8ClF,CAAC;AAEF,2EAA2E;AAC3E,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAErC,6GAA6G;AAC7G,eAAO,MAAM,mBAAmB,KAAK,CAAC;AAEtC,gNAAgN;AAChN,eAAO,MAAM,4BAA4B,MAAM,CAAC;AAEhD;;;;;;;;;GASG;AACH,eAAO,MAAM,QAAQ,wDAEc,CAAC;AACpC,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,QAAQ,CAAC,CAAC;AAEhD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,gBAAgB,wDAEqE,CAAC;AACnG,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEhE;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,MAAM,CAAC;AAqBpC;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,KAAK,aAYhB,CAAC;AACH,MAAM,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,KAAK,CAAC,CAAC;AAE1C,wCAAwC;AACxC,eAAO,MAAM,WAAW,QAAO,IAAmC,CAAC;AAEnE;;;;;;;;;GASG;AACH,eAAO,MAAM,IAAI,8CAAuC,CAAC;AACzD,MAAM,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,IAAI,CAAC,CAAC;AAExC,qFAAqF;AACrF,eAAO,MAAM,eAAe,4DAA4B,CAAC;AACzD,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE9D,wCAAwC;AACxC,eAAO,MAAM,QAAQ,yDAAqC,CAAC;AAC3D,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,QAAQ,CAAC,CAAC;AAEhD,gEAAgE;AAChE,eAAO,MAAM,gBAAgB,QAAO,QAAgD,CAAC;AAErF,sFAAsF;AACtF,eAAO,MAAM,WAAW,uEAAqC,CAAC;AAC9D,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEtD,uFAAuF;AACvF,eAAO,MAAM,UAAU,aAEuD,CAAC;AAC/E,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEpD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,cAAc,EAAE,CAAC,CAAC,SAAS,GAAG,CAAC,CAAC,OAAO,CAAC,QAAQ,EAAE,MAAM,CAEA,CAAC"}

package/dist/primitive_schemas.js

@@ -181,8 +181,17 @@ export const Email = z
 });
 /** Returns a new random (v4) `Uuid`. */
 export const create_uuid = () => crypto.randomUUID();
-/** Branded UUID schema. */
-export const Uuid = z.uuid().brand('Uuid');
+/**
+ * Branded UUID schema. Accepts either case and outputs lowercase — the form
+ * Postgres renders a `uuid` in and every id the server mints — so a parsed id
+ * compares equal to the same id read back from the database. The Rust spine
+ * canonicalizes the same way.
+ *
+ * `.toLowerCase()` rather than `.transform()`: an overwrite keeps the output
+ * type and stays invisible to `z.toJSONSchema`, where a transform would leave
+ * no input schema to render.
+ */
+export const Uuid = z.uuid().toLowerCase().brand('Uuid');
 /** `Uuid` that defaults to a fresh `create_uuid()` when the input is `undefined`. */
 export const UuidWithDefault = Uuid.default(create_uuid);
 /** Branded ISO 8601 datetime schema. */

package/dist/rate_limiter.d.ts

@@ -4,6 +4,23 @@
  * Tracks failed attempts per key (typically IP address) using a sliding
  * time window. No external dependencies — state resets on server restart.
  *
+ * **Reserve, then settle.** A handler that checks the limiter, awaits work,
+ * and records afterwards lets every request of a concurrent burst pass the
+ * check before any of them records — a burst of any size gets through.
+ * `RateLimiter.try_reserve` closes that: it admits a request and counts it in
+ * flight in one synchronous step, and the attempt counts against the cap
+ * until its `RateLimitReservation` is settled — `record` keeps it as an
+ * attempt, `release` gives it back. Every handler whose outcome decides
+ * whether the attempt counts reserves, and releases in a `finally` so an
+ * early return or a throw never leaks an in-flight slot; `check` + `record`
+ * stays for callers that record in the same synchronous step they check.
+ *
+ * **Attempts count while in flight, whatever their outcome** — so a burst of
+ * *correct* concurrent attempts from one key is capped too. The password
+ * surfaces therefore reserve with `RateLimiter.reserve`, which waits up to
+ * `RESERVATION_WAIT_MAX_MS` for a slot when the cap is reached only by
+ * attempts in flight, and refuses at once when it is reached by recorded ones.
+ *
  * @module
  */
 import type { Context } from 'hono';
@@ -19,11 +36,19 @@ export declare const DEFAULT_RATE_LIMITER_MAX_KEYS = 100000;
  * Configuration for a rate limiter instance.
  */
 export interface RateLimiterOptions {
-    /** Maximum allowed attempts within the window. */
+    /**
+     * Maximum allowed attempts within the window, a safe integer ≥ 0. `0`
+     * refuses every attempt — `check`, `try_reserve`, and `reserve` answer at
+     * once with the window's length as `retry_after`, tracking nothing.
+     */
     max_attempts: number;
-    /** Sliding window duration in milliseconds. */
+    /** Sliding window duration in milliseconds, a safe integer ≥ 0. */
     window_ms: number;
-    /** Interval for pruning stale entries (0 disables the timer). */
+    /**
+     * Interval for pruning stale entries, an integer from `0` to
+     * `PERIODIC_INTERVAL_MS_MAX` (`0` disables the timer) — the largest delay
+     * a timer honours; past it `setInterval` fires every millisecond.
+     */
     cleanup_interval_ms: number;
     /**
      * Maximum tracked keys. When exceeded, the least-recently-used key is
@@ -39,6 +64,8 @@ export interface RateLimiterOptions {
      * can, however, drop out of the table and reset their budget — set
      * `max_keys` high enough to fit the expected legitimate key set and
      * this stays theoretical.
+     *
+     * A number must be a positive safe integer.
      */
     max_keys?: number | null;
 }
@@ -112,21 +139,78 @@ export declare const RATE_LIMITERS_DISABLED_BANNER = "!!! RATE LIMITERS DISABLED
  * `RateLimiterMode::limiter`.
  */
 export declare const announce_rate_limiters_disabled: () => void;
+/**
+ * `retry_after` reported while a key is at its cap only because of attempts
+ * still in flight. Those settle within a request's lifetime, so the earliest
+ * moment worth retrying is the next second, not the oldest recorded attempt's
+ * expiry. Mirrors the Rust spine's `IN_FLIGHT_RETRY_AFTER_SECONDS`.
+ */
+export declare const IN_FLIGHT_RETRY_AFTER_SECONDS = 1;
+/**
+ * How long a password-surface reservation (`RateLimiter.reserve`) waits for a
+ * slot when the key is at its cap only because of attempts still in flight,
+ * before answering `429`. Mirrors the Rust spine's `RESERVATION_WAIT_MAX`.
+ *
+ * Counting attempts while they are in flight caps *successful* concurrent
+ * attempts from one key too — a class behind one NAT logging in together.
+ * Those attempts settle within a request's lifetime, so a short wait turns
+ * most of those refusals into a late success, while a key at its cap on
+ * *recorded* attempts is still refused at once.
+ */
+export declare const RESERVATION_WAIT_MAX_MS = 5000;
 /**
  * Result of a rate limit check or record operation.
  */
 export interface RateLimitResult {
     /** Whether the request is allowed. */
     allowed: boolean;
-    /** Remaining attempts before blocking. */
+    /** Remaining attempts before blocking, counting attempts still in flight. */
     remaining: number;
     /** Seconds until the oldest active attempt expires (0 if allowed). */
     retry_after: number;
 }
+/**
+ * An attempt admitted by `RateLimiter.try_reserve` or `RateLimiter.reserve`,
+ * counted against the key's cap until settled.
+ *
+ * Settle it exactly once: `record` keeps it as an attempt (a failure, on the
+ * failure-counting surfaces), `release` gives it back. Both are idempotent and
+ * the first call wins, so a handler calls `record` where the outcome is known
+ * and `release` in a `finally`. When the key's entry was evicted or reset
+ * meanwhile, `record` still records (into the key's current entry) and
+ * `release` is a no-op. A reservation made against no limiter
+ * (`try_reserve_optional` / `reserve_optional` with `null`) is inert.
+ */
+export interface RateLimitReservation {
+    /**
+     * Settle as a recorded attempt.
+     *
+     * @param now - current timestamp in ms (defaults to `Date.now()`)
+     */
+    record: (now?: number) => void;
+    /** Settle without recording an attempt. */
+    release: () => void;
+}
+/** Result of `RateLimiter.try_reserve` and `RateLimiter.reserve`. */
+export type RateLimitReserveResult = {
+    ok: true;
+    reservation: RateLimitReservation;
+} | {
+    ok: false;
+    retry_after: number;
+};
+/** Options for `RateLimiter.reserve`. */
+export interface RateLimitReserveOptions {
+    /** How long to wait for a slot. Default `RESERVATION_WAIT_MAX_MS`. */
+    max_wait_ms?: number;
+    /** Stops the wait (a refusal, `retry_after: IN_FLIGHT_RETRY_AFTER_SECONDS`) — pass the request's signal. */
+    signal?: AbortSignal;
+}
 /**
  * In-memory sliding window rate limiter.
  *
- * Stores an array of timestamps per key. On `check`/`record`, timestamps
+ * Stores an array of timestamps per key, plus a count of attempts reserved
+ * (`try_reserve`) and not yet settled. On `check`/`record`, timestamps
  * outside the window are pruned. `retry_after` reports seconds until the
  * oldest active timestamp expires.
  *
@@ -144,15 +228,32 @@ export interface RateLimitResult {
 export declare class RateLimiter {
     #private;
     readonly options: RateLimiterOptions;
+    /**
+     * @param options - the limiter's bounds
+     * @throws {RangeError} when `max_attempts`, `window_ms`, or `cleanup_interval_ms` is not a safe integer ≥ 0, `cleanup_interval_ms` exceeds `PERIODIC_INTERVAL_MS_MAX`, or `max_keys` is neither `null` nor a positive safe integer
+     */
     constructor(options: RateLimiterOptions);
     /** Number of tracked keys. */
     get size(): number;
     /**
-     * Check whether `key` is allowed without recording an attempt.
+     * Keys holding a parked-waiter slot right now (see `reserve`): each slot is
+     * removed with its key's last waiter. For tests pinning that a waiter
+     * leaves nothing behind; the twin of the Rust spine's test-only
+     * `waiter_keys`.
+     *
+     * @internal
+     */
+    get waiter_keys(): number;
+    /**
+     * Check whether `key` is allowed without recording an attempt, counting
+     * recorded attempts and reserved ones still in flight.
      *
      * Prunes timestamps that fell outside the window as a side effect (and
-     * removes the key entirely when none remain), so the backing map stays
-     * bounded even under read-only traffic.
+     * removes the key entirely when none remain and none are in flight), so
+     * the backing map stays bounded even under read-only traffic.
+     *
+     * A check followed by an awaited operation and then a `record` lets a
+     * concurrent burst past the cap; reserve with `try_reserve` instead.
      *
      * @param key - rate limit key (e.g. IP address)
      * @param now - current timestamp in ms (defaults to `Date.now()`)
@@ -167,6 +268,44 @@ export declare class RateLimiter {
      * @mutates internal map - appends `now` to the timestamp list for `key` (after pruning expired entries)
      */
     record(key: string, now?: number): RateLimitResult;
+    /**
+     * Admit an attempt for `key` and count it in flight, in one synchronous
+     * step.
+     *
+     * The attempt counts against the cap — for this request and every
+     * concurrent one — until the returned reservation is settled: recorded as
+     * an attempt, or released. So no burst of concurrent requests gets more
+     * than `max_attempts` past the limiter between them. Release in a
+     * `finally`: nothing settles a reservation for you, so one left unsettled
+     * holds its slot for the life of the process.
+     *
+     * @param key - rate limit key (e.g. IP address)
+     * @param now - current timestamp in ms (defaults to `Date.now()`)
+     * @returns the reservation, or `{ok: false, retry_after}` when recorded plus in-flight attempts already reach the cap (nothing is reserved then)
+     * @mutates internal map - increments `key`'s in-flight count, creating its entry when absent
+     */
+    try_reserve(key: string, now?: number): RateLimitReserveResult;
+    /**
+     * `try_reserve`, waiting up to `max_wait_ms` for a slot when the key is at
+     * its cap only because of attempts still in flight.
+     *
+     * Each settle (and record and reset) on the key wakes its waiters to
+     * re-decide — that key's only, so a settle costs nothing for waiters parked
+     * elsewhere: a freed slot is reserved; recorded attempts reaching the cap
+     * refuse at once with their real `retry_after`; reaching `max_wait_ms` (or
+     * `signal` aborting) refuses with `IN_FLIGHT_RETRY_AFTER_SECONDS`. At most
+     * `max_attempts` reservations wait on one key — one more is refused at
+     * once — so a flood can't park requests without bound. A waiter that
+     * leaves, by any path, leaves the key's waiter count as it found it. A
+     * waiter holds no place in a queue: each wake, every waiter re-decides, so
+     * one can lose every race for a freed slot until `max_wait_ms` refuses it.
+     *
+     * @param key - rate limit key (e.g. IP address)
+     * @param options - the wait bound and an abort signal
+     * @returns the reservation, or `{ok: false, retry_after}` as described (nothing is reserved then)
+     * @mutates internal map - increments `key`'s in-flight count on admission; counts the call in `key`'s waiters while it waits
+     */
+    reserve(key: string, options?: RateLimitReserveOptions): Promise<RateLimitReserveResult>;
     /**
      * Clear all attempts for `key`.
      *
@@ -181,8 +320,9 @@ export declare class RateLimiter {
      * otherwise an attacker interleaves their own logins (or, under open signup,
      * throwaway account creations needing no credential at all) with guesses
      * against arbitrary victims and sprays indefinitely from one address.
-     * Nothing records on the IP bucket on success on any path, so with no reset
-     * it is a pure monotone-within-window failure counter that only time clears.
+     * The only success that records on an IP bucket is an open signup (charged
+     * like a failure); no success clears one, so with no reset each is a
+     * monotone-within-window counter that only time clears.
      *
      * Because they are monotone, the IP buckets are **one instance per auth
      * surface** (`login_ip_rate_limiter`, `signup_ip_rate_limiter`,
@@ -192,11 +332,15 @@ export declare class RateLimiter {
      * four routes at once — a cost that used to be masked by the reset this
      * doc forbids.
      *
-     * @mutates internal map - removes the entry for `key`
+     * Attempts still in flight on `key` (reserved by concurrent requests) are
+     * kept: a reset forgives what was recorded, not what is still running.
+     *
+     * @mutates internal map - removes the entry for `key`, or clears its timestamps while attempts are in flight
      */
     reset(key: string): void;
     /**
-     * Remove entries whose timestamps are all outside the window.
+     * Remove entries whose timestamps are all outside the window and that
+     * have no attempt in flight.
      *
      * @param now - current timestamp in ms (defaults to `Date.now()`)
      * @mutates internal map - prunes expired timestamps and deletes empty keys
@@ -209,6 +353,29 @@ export declare class RateLimiter {
      */
     dispose(): void;
 }
+/**
+ * `RateLimiter.try_reserve` against a limiter that may be absent.
+ *
+ * An inert reservation when `limiter` is `null` (disabled) or `key` is `null`
+ * (no resolvable key — e.g. no client IP), so a handler reserves and settles
+ * the same way whether or not the surface is limited. Twin of the Rust
+ * spine's `try_reserve_optional`.
+ *
+ * @param limiter - the limiter, or `null` when disabled
+ * @param key - rate limit key, or `null` to skip
+ * @param now - current timestamp in ms (defaults to `Date.now()`)
+ */
+export declare const try_reserve_optional: (limiter: RateLimiter | null, key: string | null, now?: number) => RateLimitReserveResult;
+/**
+ * `RateLimiter.reserve` against a limiter that may be absent — an inert
+ * reservation when `limiter` or `key` is `null`. Twin of the Rust spine's
+ * `reserve_optional`.
+ *
+ * @param limiter - the limiter, or `null` when disabled
+ * @param key - rate limit key, or `null` to skip
+ * @param options - the wait bound and an abort signal
+ */
+export declare const reserve_optional: (limiter: RateLimiter | null, key: string | null, options?: RateLimitReserveOptions) => Promise<RateLimitReserveResult>;
 /**
  * Create a `RateLimiter` with sensible defaults for per-IP login protection.
  *

package/dist/rate_limiter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rate_limiter.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/rate_limiter.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAKpC;;;;;;GAMG;AACH,eAAO,MAAM,6BAA6B,SAAU,CAAC;AAErD;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAClC,kDAAkD;IAClD,YAAY,EAAE,MAAM,CAAC;IACrB,+CAA+C;IAC/C,SAAS,EAAE,MAAM,CAAC;IAClB,iEAAiE;IACjE,mBAAmB,EAAE,MAAM,CAAC;IAC5B;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,2BAA2B,EAAE,kBAKzC,CAAC;AAEF,uFAAuF;AACvF,eAAO,MAAM,gCAAgC,EAAE,kBAK9C,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,4BAA4B,EAAE,kBAK1C,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,iCAAiC,EAAE,kBAK/C,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,MAAM,eAAe,GAAG,UAAU,GAAG,sBAAsB,CAAC;AAElE;;;GAGG;AACH,eAAO,MAAM,6BAA6B,iGACgD,CAAC;AAI3F;;;;;;;;;;GAUG;AACH,eAAO,MAAM,+BAA+B,QAAO,IAIlD,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,eAAe;IAC/B,sCAAsC;IACtC,OAAO,EAAE,OAAO,CAAC;IACjB,0CAA0C;IAC1C,SAAS,EAAE,MAAM,CAAC;IAClB,sEAAsE;IACtE,WAAW,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,WAAW;;IACvB,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAC;gBAOzB,OAAO,EAAE,kBAAkB;IAcvC,8BAA8B;IAC9B,IAAI,IAAI,IAAI,MAAM,CAEjB;IAcD;;;;;;;;;;OAUG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,GAAE,MAAmB,GAAG,eAAe;IA2B7D;;;;;;OAMG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,GAAE,MAAmB,GAAG,eAAe;IA0B9D;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAIxB;;;;;OAKG;IACH,OAAO,CAAC,GAAG,GAAE,MAAmB,GAAG,IAAI;IAgBvC;;;;OAIG;IACH,OAAO,IAAI,IAAI;CAMf;AAED;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,GAAI,UAAU,OAAO,CAAC,kBAAkB,CAAC,KAAG,WAE3E,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,4BAA4B,GAAI,GAAG,OAAO,EAAE,aAAa,MAAM,KAAG,QAI7E,CAAC"}
+{"version":3,"file":"rate_limiter.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/rate_limiter.ts"],"names":[],"mappings":"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"}