@fuzdev/fuz_app 0.29.0 → 0.31.0

package/dist/http/route_spec.js

@@ -133,7 +133,8 @@ const create_query_validation = (query_schema) => {
  *
  * In development, validates 2xx JSON responses against the output schema
  * and non-2xx responses against declared error schemas.
- * Logs warnings for mismatches. In production, returns the handler unchanged.
+ * Logs an error for mismatches and returns the response unchanged —
+ * does not throw. In production, returns the handler unchanged.
  */
 const wrap_output_validation = (handler, output_schema, error_schemas, log) => {
     if (!DEV)
@@ -152,7 +153,7 @@ const wrap_output_validation = (handler, output_schema, error_schemas, log) => {
                 const body = await cloned.json();
                 const result = output_schema.safeParse(body);
                 if (!result.success) {
-                    log.warn(`Output schema mismatch: ${c.req.method} ${c.req.path}`, result.error.issues);
+                    log.error(`Output schema mismatch: ${c.req.method} ${c.req.path}`, result.error.issues);
                 }
             }
             catch {
@@ -167,7 +168,7 @@ const wrap_output_validation = (handler, output_schema, error_schemas, log) => {
                     const body = await cloned.json();
                     const result = status_schema.safeParse(body);
                     if (!result.success) {
-                        log.warn(`Error schema mismatch (${response.status}): ${c.req.method} ${c.req.path}`, result.error.issues);
+                        log.error(`Error schema mismatch (${response.status}): ${c.req.method} ${c.req.path}`, result.error.issues);
                     }
                 }
                 catch {

package/dist/rate_limiter.d.ts

@@ -7,6 +7,14 @@
  * @module
  */
 import type { Context } from 'hono';
+/**
+ * Default tracked-key cap: bounds worst-case memory under key-enumeration
+ * attacks (an attacker rotating source IPs cannot grow the backing map
+ * indefinitely between cleanup ticks). Tuned to comfortably fit real
+ * traffic for a single-instance deployment while capping memory at a few
+ * MB in the worst case.
+ */
+export declare const DEFAULT_RATE_LIMITER_MAX_KEYS = 100000;
 /**
  * Configuration for a rate limiter instance.
  */
@@ -17,6 +25,22 @@ export interface RateLimiterOptions {
     window_ms: number;
     /** Interval for pruning stale entries (0 disables the timer). */
     cleanup_interval_ms: number;
+    /**
+     * Maximum tracked keys. When exceeded, the least-recently-used key is
+     * evicted — bounds memory under key-enumeration attacks. Default:
+     * `DEFAULT_RATE_LIMITER_MAX_KEYS` (100_000). Pass `null` to disable the
+     * cap (falls back to an unbounded `Map` — only recommended when the key
+     * set is known to be closed, e.g. a per-account limiter keyed to a
+     * bounded-size account table).
+     *
+     * LRU trade-off: every `check` / `record` call marks the key as
+     * most-recently-used, so keys under active attack stay fresh and won't
+     * be evicted. A slow-burn attacker spread across many low-volume keys
+     * 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.
+     */
+    max_keys?: number | null;
 }
 /** Default options for per-IP login rate limiting: 5 attempts per 15 minutes. */
 export declare const DEFAULT_LOGIN_IP_RATE_LIMIT: RateLimiterOptions;
@@ -40,6 +64,12 @@ export interface RateLimitResult {
  * outside the window are pruned. `retry_after` reports seconds until the
  * oldest active timestamp expires.
  *
+ * The backing store is an `LruMap` when `options.max_keys` is a positive
+ * number (default `DEFAULT_RATE_LIMITER_MAX_KEYS`) and a plain `Map` when
+ * `max_keys` is `null`. The `LruMap` path bounds memory under
+ * key-enumeration attack at the cost of a slight per-op overhead and the
+ * LRU trade-off described on `RateLimiterOptions.max_keys`.
+ *
  * Parameters that accept `RateLimiter | null` (e.g. `ip_rate_limiter`,
  * `login_account_rate_limiter`) silently disable rate limiting when `null`
  * is passed — no checks are performed and all requests are allowed through.

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,EAAC,OAAO,EAAC,MAAM,MAAM,CAAC;AAIlC;;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;CAC5B;AAED,iFAAiF;AACjF,eAAO,MAAM,2BAA2B,EAAE,kBAIzC,CAAC;AAEF,uFAAuF;AACvF,eAAO,MAAM,gCAAgC,EAAE,kBAI9C,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;;;;;;;;;;GAUG;AACH,qBAAa,WAAW;;IACvB,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAC;gBAOzB,OAAO,EAAE,kBAAkB;IAWvC,8BAA8B;IAC9B,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;;;;OAKG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,GAAE,MAAmB,GAAG,eAAe;IA2B7D;;;;;OAKG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,GAAE,MAAmB,GAAG,eAAe;IA0B9D;;OAEG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAIxB;;;;OAIG;IACH,OAAO,CAAC,GAAG,GAAE,MAAmB,GAAG,IAAI;IAYvC,2DAA2D;IAC3D,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":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,MAAM,CAAC;AAKlC;;;;;;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,iFAAiF;AACjF,eAAO,MAAM,2BAA2B,EAAE,kBAKzC,CAAC;AAEF,uFAAuF;AACvF,eAAO,MAAM,gCAAgC,EAAE,kBAK9C,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;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,WAAW;;IACvB,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAC;gBAOzB,OAAO,EAAE,kBAAkB;IAcvC,8BAA8B;IAC9B,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;;;;OAKG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,GAAE,MAAmB,GAAG,eAAe;IA2B7D;;;;;OAKG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,GAAE,MAAmB,GAAG,eAAe;IA0B9D;;OAEG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAIxB;;;;OAIG;IACH,OAAO,CAAC,GAAG,GAAE,MAAmB,GAAG,IAAI;IAgBvC,2DAA2D;IAC3D,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"}

package/dist/rate_limiter.js

@@ -6,18 +6,29 @@
  *
  * @module
  */
+import { LruMap } from '@fuzdev/fuz_util/lru_map.js';
 import { ERROR_RATE_LIMIT_EXCEEDED } from './http/error_schemas.js';
+/**
+ * Default tracked-key cap: bounds worst-case memory under key-enumeration
+ * attacks (an attacker rotating source IPs cannot grow the backing map
+ * indefinitely between cleanup ticks). Tuned to comfortably fit real
+ * traffic for a single-instance deployment while capping memory at a few
+ * MB in the worst case.
+ */
+export const DEFAULT_RATE_LIMITER_MAX_KEYS = 100_000;
 /** Default options for per-IP login rate limiting: 5 attempts per 15 minutes. */
 export const DEFAULT_LOGIN_IP_RATE_LIMIT = {
     max_attempts: 5,
     window_ms: 15 * 60_000,
     cleanup_interval_ms: 5 * 60_000,
+    max_keys: DEFAULT_RATE_LIMITER_MAX_KEYS,
 };
 /** Default options for per-account login rate limiting: 10 attempts per 30 minutes. */
 export const DEFAULT_LOGIN_ACCOUNT_RATE_LIMIT = {
     max_attempts: 10,
     window_ms: 30 * 60_000,
     cleanup_interval_ms: 5 * 60_000,
+    max_keys: DEFAULT_RATE_LIMITER_MAX_KEYS,
 };
 /**
  * In-memory sliding window rate limiter.
@@ -26,6 +37,12 @@ export const DEFAULT_LOGIN_ACCOUNT_RATE_LIMIT = {
  * outside the window are pruned. `retry_after` reports seconds until the
  * oldest active timestamp expires.
  *
+ * The backing store is an `LruMap` when `options.max_keys` is a positive
+ * number (default `DEFAULT_RATE_LIMITER_MAX_KEYS`) and a plain `Map` when
+ * `max_keys` is `null`. The `LruMap` path bounds memory under
+ * key-enumeration attack at the cost of a slight per-op overhead and the
+ * LRU trade-off described on `RateLimiterOptions.max_keys`.
+ *
  * Parameters that accept `RateLimiter | null` (e.g. `ip_rate_limiter`,
  * `login_account_rate_limiter`) silently disable rate limiting when `null`
  * is passed — no checks are performed and all requests are allowed through.
@@ -33,10 +50,12 @@ export const DEFAULT_LOGIN_ACCOUNT_RATE_LIMIT = {
 export class RateLimiter {
     options;
     /** Key → array of attempt timestamps. */
-    #attempts = new Map();
+    #attempts;
     #cleanup_timer = null;
     constructor(options) {
         this.options = options;
+        const max_keys = options.max_keys === undefined ? DEFAULT_RATE_LIMITER_MAX_KEYS : options.max_keys;
+        this.#attempts = max_keys === null ? new Map() : new LruMap(max_keys);
         if (options.cleanup_interval_ms > 0) {
             this.#cleanup_timer = setInterval(() => this.cleanup(), options.cleanup_interval_ms);
             // Allow the process to exit even if the timer is still active.
@@ -120,7 +139,11 @@ export class RateLimiter {
      */
     cleanup(now = Date.now()) {
         const cutoff = now - this.options.window_ms;
-        for (const [key, timestamps] of this.#attempts) {
+        // Snapshot before mutating: `LruMap.set()` on an existing key moves it
+        // to the MRU end during iteration and causes re-visit in the same pass.
+        // The `Map` path is unaffected but the snapshot is cheap on both.
+        const entries = [...this.#attempts];
+        for (const [key, timestamps] of entries) {
             const active = timestamps.filter((t) => t > cutoff);
             if (active.length === 0) {
                 this.#attempts.delete(key);

package/dist/realtime/sse_auth_guard.d.ts

@@ -14,6 +14,8 @@ import type { Logger } from '@fuzdev/fuz_util/log.js';
 import { type AuditLogEvent } from '../auth/audit_log_schema.js';
 import { SubscriberRegistry, type SubscribeOptions } from './subscriber_registry.js';
 import type { SseStream, SseNotification, EventSpec } from './sse.js';
+/** SSE channel the audit-log stream route publishes on. */
+export declare const AUDIT_LOG_CHANNEL = "audit_log";
 /**
  * Audit event types that trigger SSE stream disconnection.
  *

package/dist/realtime/sse_auth_guard.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sse_auth_guard.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/realtime/sse_auth_guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAEpD,OAAO,EAGN,KAAK,aAAa,EAClB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAC,kBAAkB,EAAE,KAAK,gBAAgB,EAAC,MAAM,0BAA0B,CAAC;AACnF,OAAO,KAAK,EAAC,SAAS,EAAE,eAAe,EAAE,SAAS,EAAC,MAAM,UAAU,CAAC;AAEpE;;;;;;;;;;GAUG;AACH,eAAO,MAAM,sBAAsB,EAAE,WAAW,CAAC,MAAM,CAKrD,CAAC;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,qBAAqB,GAAI,CAAC,EACtC,UAAU,kBAAkB,CAAC,CAAC,CAAC,EAC/B,eAAe,MAAM,GAAG,IAAI,EAC5B,KAAK,MAAM,KACT,CAAC,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CA6CjC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC3B,8FAA8F;IAC9F,SAAS,EAAE,CAAC,MAAM,EAAE,SAAS,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC,EAAE,gBAAgB,KAAK,MAAM,IAAI,CAAC;IAC1F,kFAAkF;IAClF,GAAG,EAAE,MAAM,CAAC;IACZ,kGAAkG;IAClG,cAAc,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;IAC/C,yEAAyE;IACzE,QAAQ,EAAE,kBAAkB,CAAC,eAAe,CAAC,CAAC;CAC9C;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,EAAE,KAAK,CAAC,SAAS,CAOlD,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,2BAA2B,KAAK,CAAC;AAE9C,eAAO,MAAM,oBAAoB,GAAI,SAAS;IAC7C,mEAAmE;IACnE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B,KAAG,WAgBH,CAAC"}
+{"version":3,"file":"sse_auth_guard.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/realtime/sse_auth_guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAEpD,OAAO,EAGN,KAAK,aAAa,EAClB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAC,kBAAkB,EAAE,KAAK,gBAAgB,EAAC,MAAM,0BAA0B,CAAC;AACnF,OAAO,KAAK,EAAC,SAAS,EAAE,eAAe,EAAE,SAAS,EAAC,MAAM,UAAU,CAAC;AAEpE,2DAA2D;AAC3D,eAAO,MAAM,iBAAiB,cAAc,CAAC;AAE7C;;;;;;;;;;GAUG;AACH,eAAO,MAAM,sBAAsB,EAAE,WAAW,CAAC,MAAM,CAKrD,CAAC;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,qBAAqB,GAAI,CAAC,EACtC,UAAU,kBAAkB,CAAC,CAAC,CAAC,EAC/B,eAAe,MAAM,GAAG,IAAI,EAC5B,KAAK,MAAM,KACT,CAAC,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CA6CjC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC3B,8FAA8F;IAC9F,SAAS,EAAE,CAAC,MAAM,EAAE,SAAS,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC,EAAE,gBAAgB,KAAK,MAAM,IAAI,CAAC;IAC1F,kFAAkF;IAClF,GAAG,EAAE,MAAM,CAAC;IACZ,kGAAkG;IAClG,cAAc,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;IAC/C,yEAAyE;IACzE,QAAQ,EAAE,kBAAkB,CAAC,eAAe,CAAC,CAAC;CAC9C;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,EAAE,KAAK,CAAC,SAAS,CAOlD,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,2BAA2B,KAAK,CAAC;AAE9C,eAAO,MAAM,oBAAoB,GAAI,SAAS;IAC7C,mEAAmE;IACnE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B,KAAG,WAgBH,CAAC"}

package/dist/realtime/sse_auth_guard.js

@@ -12,6 +12,8 @@
  */
 import { AUDIT_EVENT_TYPES, AuditLogEventJson, } from '../auth/audit_log_schema.js';
 import { SubscriberRegistry } from './subscriber_registry.js';
+/** SSE channel the audit-log stream route publishes on. */
+export const AUDIT_LOG_CHANNEL = 'audit_log';
 /**
  * Audit event types that trigger SSE stream disconnection.
  *
@@ -60,7 +62,7 @@ export const create_sse_auth_guard = (registry, required_role, log) => {
             return;
         // session_revoke is session-scoped, not account-scoped — close only the
         // stream subscribed under the revoked session's hash. The hash is already
-        // in the event metadata (set by the /sessions/:id/revoke handler).
+        // in the event metadata (set by the `account_session_revoke` RPC handler).
         if (event.event_type === 'session_revoke') {
             const session_id = event.metadata?.session_id;
             if (typeof session_id !== 'string' || session_id.length === 0)
@@ -124,7 +126,7 @@ export const AUDIT_LOG_EVENT_SPECS = AUDIT_EVENT_TYPES.map((event_type) => ({
     method: event_type,
     params: AuditLogEventJson,
     description: `Audit log: ${event_type.replaceAll('_', ' ')}`,
-    channel: 'audit_log',
+    channel: AUDIT_LOG_CHANNEL,
 }));
 /**
  * Default max concurrent SSE subscribers per session scope for the audit log.
@@ -146,7 +148,7 @@ export const create_audit_log_sse = (options) => {
         subscribe: registry.subscribe.bind(registry),
         log: options.log,
         on_audit_event: (event) => {
-            registry.broadcast('audit_log', { method: event.event_type, params: event });
+            registry.broadcast(AUDIT_LOG_CHANNEL, { method: event.event_type, params: event });
             guard(event);
         },
         registry,