@fuzdev/fuz_app 0.140.0 → 0.142.0

package/dist/http/surface.js

@@ -1,13 +1,13 @@
 /**
  * App surface generation — JSON-serializable attack surface from route and middleware specs.
  *
- * Pure schema helpers (`is_null_schema`, `schema_to_surface`, `middleware_applies`,
+ * Pure schema helpers (`is_null_schema`, `schema_to_surface`, `middleware_applies`, `middleware_spec_applies`,
  * `merge_error_schemas`) live in `http/schema_helpers.ts`.
  *
  * @module
  */
 import { z } from 'zod';
-import { schema_to_surface, middleware_applies, merge_error_schemas, is_null_schema, is_strict_object_schema } from './schema_helpers.js';
+import { schema_to_surface, middleware_spec_applies, merge_error_schemas, is_null_schema, is_strict_object_schema } from './schema_helpers.js';
 // --- Surface generation ---
 /**
  * Collect error schemas from all middleware that applies to a route path.
@@ -17,7 +17,7 @@ import { schema_to_surface, middleware_applies, merge_error_schemas, is_null_sch
 export const collect_middleware_errors = (middleware, route_path) => {
     const errors = {};
     for (const mw of middleware) {
-        if (mw.errors && middleware_applies(mw.path, route_path)) {
+        if (mw.errors && middleware_spec_applies(mw, route_path)) {
             Object.assign(errors, mw.errors);
         }
     }
@@ -89,11 +89,18 @@ export const generate_app_surface = (options) => {
                     mw_error_schemas = schemas;
                 }
             }
-            return { name: m.name, path: m.path, error_schemas: mw_error_schemas };
+            return {
+                name: m.name,
+                path: m.path,
+                error_schemas: mw_error_schemas,
+                ...(m.carve_outs?.length && {
+                    carve_outs: m.carve_outs.map(({ path, reason }) => ({ path, reason }))
+                })
+            };
         }),
         routes: route_specs.map((r) => {
             const applicable_middleware = middleware_specs
-                .filter((m) => middleware_applies(m.path, r.path))
+                .filter((m) => middleware_spec_applies(m, r.path))
                 .map((m) => m.name);
             // Merge auto-derived + middleware + explicit error schemas
             const mw_errors = collect_middleware_errors(middleware_specs, r.path);

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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"}