@fuzdev/fuz_app 0.54.0 → 0.56.0

package/dist/http/pending_effects.d.ts

@@ -1,33 +1,86 @@
 /**
- * Shared post-commit side-effect helper.
+ * Two-queue side-effect machinery for request handlers.
  *
- * WS sends and `on_audit_event` SSE broadcasts must never fire mid-transaction —
- * a rollback would leak state that never existed. Anything pushed onto
- * `pending_effects` runs after the response is sent (see the request-context
- * middleware), so this helper is the canonical home for post-commit fan-out.
+ * Handlers register fire-and-forget work in one of two queues, distinguished
+ * by their timing contract:
  *
- * Satisfied by both `RouteContext` (HTTP routes) and `ActionContext` (RPC
- * actions) — they share `{log, pending_effects}` by convention, so this
- * module stays in `http/` (both depend on it).
+ * - `pending_effects: Array<Promise<void>>` — eager. Producers push pool
+ *   writes that are already in flight (audit emits, session-touch UPDATE,
+ *   api-token usage tracking). The pool write is rollback-resilient by
+ *   virtue of running outside the request transaction; pushing the
+ *   in-flight handle lets test mode (`await_pending_effects: true`) await
+ *   it.
+ * - `post_commit_effects: Array<() => void | Promise<void>>` — deferred.
+ *   Producers go through `emit_after_commit(ctx, fn)`; the flush
+ *   middleware is the only site that ever invokes the thunk, and it does
+ *   so after the request handler (and its wrapping `db.transaction`)
+ *   returns. Used for WS sends and any work that must observe a committed
+ *   transaction.
+ *
+ * The split exists because the two shapes encode different contracts:
+ * eager pushers are saying "wait for this work that's already started";
+ * thunk pushers are saying "run this after the handler returns." Burying
+ * both behind one `Array<PendingEffect>` made `c.var.pending_effects.push(x)`
+ * ambiguous at the call site. With separate queues, the field name is
+ * the contract.
+ *
+ * Both `RouteContext` (HTTP routes) and `ActionContext` (RPC + WS
+ * actions) carry both queues by convention, so this module stays in
+ * `http/` (every transport depends on it).
  *
  * @module
  */
 import type { Logger } from '@fuzdev/fuz_util/log.js';
-/** Minimal structural context required by `emit_after_commit`. */
-export interface PendingEffectsContext {
+/**
+ * Minimal structural context required by `emit_after_commit`. Both
+ * `RouteContext` and `ActionContext` satisfy this — they each carry
+ * `log` and `post_commit_effects`.
+ */
+export interface EmitAfterCommitContext {
     log: Logger;
-    pending_effects: Array<Promise<void>>;
+    post_commit_effects: Array<() => void | Promise<void>>;
 }
 /**
  * Defer a side effect until after the handler's transaction commits.
  *
- * Exceptions thrown by `fn` are caught and logged via `ctx.log.error`, so one
- * failed send cannot corrupt the already-committed response or starve other
- * queued effects in the same tick.
+ * Pushes a raw thunk onto `ctx.post_commit_effects` — the flush
+ * middleware (in `server/app_server.ts` and the per-message WS dispatcher)
+ * is the only site that ever invokes `fn`. This is load-bearing: a
+ * previous implementation queued `Promise.resolve().then(fn)`, which
+ * JavaScript's microtask scheduler drains before the wrapping
+ * `await db.query('COMMIT')` resumes — `fn` fired mid-transaction and a
+ * rollback would leak a notification for state that never landed.
+ *
+ * The thunk shape closes that gap by deferring the work to flush time.
+ * The flush owns the per-thunk `try/catch` + `log.error` so any
+ * directly-pushed thunk (tests included) cannot escape the safety net.
+ *
+ * @param ctx - context carrying `log` and the `post_commit_effects` queue
+ * @param fn - side effect to run after commit; may return `void` or `Promise<void>`
+ * @mutates `ctx.post_commit_effects` - appends `fn` verbatim
+ */
+export declare const emit_after_commit: (ctx: EmitAfterCommitContext, fn: () => void | Promise<void>) => void;
+/**
+ * Drain an eager `pending_effects` queue: `Promise.allSettled` the
+ * in-flight handles, route every rejection through `log.error`, and
+ * fan out to `on_rejection` when supplied (production wires this to
+ * `on_effect_error` for monitoring).
+ *
+ * Returned promise resolves once every effect has settled. Never
+ * rejects. No-op when `effects` is empty (common on read-only
+ * requests).
+ *
+ * Symmetric with `flush_post_commit_effects` for the deferred queue.
+ */
+export declare const flush_pending_effects: (effects: ReadonlyArray<Promise<void>>, log: Logger, on_rejection?: (reason: unknown) => void) => Promise<void>;
+/**
+ * Drain a `post_commit_effects` queue: invoke each thunk under
+ * `try/catch`, collect any returned promises, and `Promise.allSettled`
+ * them. Synchronous throws and async rejections are routed through
+ * `log.error` so one failing effect cannot starve siblings.
  *
- * @param ctx - context carrying `log` and the `pending_effects` queue
- * @param fn - synchronous side effect to run after commit
- * @mutates `ctx.pending_effects` - appends a never-rejecting promise wrapping `fn`
+ * Returned promise resolves once every thunk has finished. Never
+ * rejects.
  */
-export declare const emit_after_commit: (ctx: PendingEffectsContext, fn: () => void) => void;
+export declare const flush_post_commit_effects: (effects: ReadonlyArray<() => void | Promise<void>>, log: Logger) => Promise<void>;
 //# sourceMappingURL=pending_effects.d.ts.map

package/dist/http/pending_effects.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pending_effects.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/http/pending_effects.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAEpD,kEAAkE;AAClE,MAAM,WAAW,qBAAqB;IACrC,GAAG,EAAE,MAAM,CAAC;IACZ,eAAe,EAAE,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;CACtC;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iBAAiB,GAAI,KAAK,qBAAqB,EAAE,IAAI,MAAM,IAAI,KAAG,IAU9E,CAAC"}
+{"version":3,"file":"pending_effects.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/http/pending_effects.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAEpD;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACtC,GAAG,EAAE,MAAM,CAAC;IACZ,mBAAmB,EAAE,KAAK,CAAC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;CACvD;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,iBAAiB,GAC7B,KAAK,sBAAsB,EAC3B,IAAI,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAC5B,IAEF,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,qBAAqB,GACjC,SAAS,aAAa,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,EACrC,KAAK,MAAM,EACX,eAAe,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,KACtC,OAAO,CAAC,IAAI,CASd,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,yBAAyB,GACrC,SAAS,aAAa,CAAC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,EAClD,KAAK,MAAM,KACT,OAAO,CAAC,IAAI,CAiBd,CAAC"}

package/dist/http/pending_effects.js

@@ -1,35 +1,104 @@
 /**
- * Shared post-commit side-effect helper.
+ * Two-queue side-effect machinery for request handlers.
  *
- * WS sends and `on_audit_event` SSE broadcasts must never fire mid-transaction —
- * a rollback would leak state that never existed. Anything pushed onto
- * `pending_effects` runs after the response is sent (see the request-context
- * middleware), so this helper is the canonical home for post-commit fan-out.
+ * Handlers register fire-and-forget work in one of two queues, distinguished
+ * by their timing contract:
  *
- * Satisfied by both `RouteContext` (HTTP routes) and `ActionContext` (RPC
- * actions) — they share `{log, pending_effects}` by convention, so this
- * module stays in `http/` (both depend on it).
+ * - `pending_effects: Array<Promise<void>>` — eager. Producers push pool
+ *   writes that are already in flight (audit emits, session-touch UPDATE,
+ *   api-token usage tracking). The pool write is rollback-resilient by
+ *   virtue of running outside the request transaction; pushing the
+ *   in-flight handle lets test mode (`await_pending_effects: true`) await
+ *   it.
+ * - `post_commit_effects: Array<() => void | Promise<void>>` — deferred.
+ *   Producers go through `emit_after_commit(ctx, fn)`; the flush
+ *   middleware is the only site that ever invokes the thunk, and it does
+ *   so after the request handler (and its wrapping `db.transaction`)
+ *   returns. Used for WS sends and any work that must observe a committed
+ *   transaction.
+ *
+ * The split exists because the two shapes encode different contracts:
+ * eager pushers are saying "wait for this work that's already started";
+ * thunk pushers are saying "run this after the handler returns." Burying
+ * both behind one `Array<PendingEffect>` made `c.var.pending_effects.push(x)`
+ * ambiguous at the call site. With separate queues, the field name is
+ * the contract.
+ *
+ * Both `RouteContext` (HTTP routes) and `ActionContext` (RPC + WS
+ * actions) carry both queues by convention, so this module stays in
+ * `http/` (every transport depends on it).
  *
  * @module
  */
 /**
  * Defer a side effect until after the handler's transaction commits.
  *
- * Exceptions thrown by `fn` are caught and logged via `ctx.log.error`, so one
- * failed send cannot corrupt the already-committed response or starve other
- * queued effects in the same tick.
+ * Pushes a raw thunk onto `ctx.post_commit_effects` — the flush
+ * middleware (in `server/app_server.ts` and the per-message WS dispatcher)
+ * is the only site that ever invokes `fn`. This is load-bearing: a
+ * previous implementation queued `Promise.resolve().then(fn)`, which
+ * JavaScript's microtask scheduler drains before the wrapping
+ * `await db.query('COMMIT')` resumes — `fn` fired mid-transaction and a
+ * rollback would leak a notification for state that never landed.
  *
- * @param ctx - context carrying `log` and the `pending_effects` queue
- * @param fn - synchronous side effect to run after commit
- * @mutates `ctx.pending_effects` - appends a never-rejecting promise wrapping `fn`
+ * The thunk shape closes that gap by deferring the work to flush time.
+ * The flush owns the per-thunk `try/catch` + `log.error` so any
+ * directly-pushed thunk (tests included) cannot escape the safety net.
+ *
+ * @param ctx - context carrying `log` and the `post_commit_effects` queue
+ * @param fn - side effect to run after commit; may return `void` or `Promise<void>`
+ * @mutates `ctx.post_commit_effects` - appends `fn` verbatim
  */
 export const emit_after_commit = (ctx, fn) => {
-    ctx.pending_effects.push(Promise.resolve().then(() => {
+    ctx.post_commit_effects.push(fn);
+};
+/**
+ * Drain an eager `pending_effects` queue: `Promise.allSettled` the
+ * in-flight handles, route every rejection through `log.error`, and
+ * fan out to `on_rejection` when supplied (production wires this to
+ * `on_effect_error` for monitoring).
+ *
+ * Returned promise resolves once every effect has settled. Never
+ * rejects. No-op when `effects` is empty (common on read-only
+ * requests).
+ *
+ * Symmetric with `flush_post_commit_effects` for the deferred queue.
+ */
+export const flush_pending_effects = async (effects, log, on_rejection) => {
+    if (effects.length === 0)
+        return;
+    const results = await Promise.allSettled(effects);
+    for (const result of results) {
+        if (result.status === 'rejected') {
+            log.error('pending effect rejected:', result.reason);
+            on_rejection?.(result.reason);
+        }
+    }
+};
+/**
+ * Drain a `post_commit_effects` queue: invoke each thunk under
+ * `try/catch`, collect any returned promises, and `Promise.allSettled`
+ * them. Synchronous throws and async rejections are routed through
+ * `log.error` so one failing effect cannot starve siblings.
+ *
+ * Returned promise resolves once every thunk has finished. Never
+ * rejects.
+ */
+export const flush_post_commit_effects = async (effects, log) => {
+    const promises = [];
+    for (const fn of effects) {
         try {
-            fn();
+            const result = fn();
+            if (result instanceof Promise) {
+                promises.push(result.catch((err) => {
+                    log.error('post-commit side effect failed:', err);
+                }));
+            }
         }
         catch (err) {
-            ctx.log.error('post-commit side effect failed:', err);
+            log.error('post-commit side effect failed:', err);
         }
-    }));
+    }
+    if (promises.length)
+        await Promise.allSettled(promises);
 };

package/dist/http/proxy.d.ts

@@ -54,23 +54,70 @@ export type ParsedProxy = {
  * @throws Error on invalid IP, invalid CIDR network, or NaN/negative/over-range prefix
  */
 export declare const parse_proxy_entry: (entry: string) => ParsedProxy;
+/**
+ * Strict IP validity check.
+ *
+ * Defense in depth around Hono's `hono/utils/ipaddr` helpers, which are
+ * lax in two ways:
+ *
+ * 1. `distinctRemoteAddr` classifies anything-with-a-colon as `'IPv6'`,
+ *    including `'host:port'`, `'attacker:controlled'`, `'203.0.113.1:8080'`.
+ * 2. `convertIPv6ToBinary` silently accepts malformed forms like
+ *    `'[::1]:8080'` and `'::1\n'`, parsing them as inconsistent binary
+ *    values that would still serve as distinct rate-limit keys for an
+ *    attacker rotating the suffix.
+ *
+ * Strict validation here is two-layered: a character-set pre-filter
+ * (`IP_LITERAL_CHARS`), then a round-trip through `convertIPv*ToBinary`
+ * to confirm the input parses cleanly. Either layer alone has holes;
+ * together they reject every input form we've seen Hono mis-handle.
+ *
+ * Used as the security primitive for any code path that takes an IP
+ * string from an untrusted source (XFF, query params) and uses it as a
+ * key (rate limiting, audit subject) or compares it against trusted
+ * proxies via CIDR (where the latent throw would otherwise bubble out).
+ *
+ * @returns the address family on success, `undefined` if the string is
+ *          not a strictly-valid IP
+ */
+export declare const validate_ip_strict: (ip: string) => "IPv4" | "IPv6" | undefined;
 /**
  * Check whether `ip` matches any entry in the trusted proxy list.
  *
  * Normalizes `ip` before matching (lowercase, IPv4-mapped IPv6 stripped).
+ * Uses `validate_ip_strict` to reject malformed input — without strict
+ * validation, Hono's lax `distinctRemoteAddr` would let an entry like
+ * `'203.0.113.1:8080'` (false-positive `'IPv6'`) reach
+ * `convertIPv6ToBinary` in the CIDR-match branch and throw.
  */
 export declare const is_trusted_ip: (ip: string, proxies: Array<ParsedProxy>) => boolean;
 /**
  * Resolve the real client IP from an `X-Forwarded-For` header value.
  *
- * Walks right-to-left, skipping trusted proxy entries. The first
- * non-trusted entry is the client IP. If all entries are trusted,
- * returns the leftmost entry. All entries are normalized before
- * matching and in the returned value.
+ * Walks right-to-left, skipping trusted proxy entries AND any entry
+ * that fails strict IP validation (`validate_ip_strict`). The first
+ * untrusted, strictly-valid entry is the client IP. If every walked
+ * entry is trusted or malformed, returns the leftmost strictly-valid
+ * (trusted) entry (likely-misconfigured all-trusted case) or
+ * `undefined` (everything was malformed — middleware falls back to
+ * the connection IP). All entries are normalized before matching and
+ * in the returned value.
+ *
+ * Skipping malformed entries is the rate-limit-key fix for the
+ * "attacker controls XFF and the proxy passes it through" surface —
+ * without the skip, an attacker could rotate arbitrary strings (incl.
+ * `'attacker:controlled'`, which Hono's lax `distinctRemoteAddr`
+ * misclassifies as IPv6) as XFF values to get fresh per-IP rate-limit
+ * buckets. Tradeoff: legitimate non-standard proxies that include
+ * ports in XFF entries (e.g. `203.0.113.1:8080`) also fail strict
+ * validation, so those entries get skipped and the rate-limit bucket
+ * collapses to the proxy's connection IP (one bucket for everyone
+ * behind that proxy). Standard proxies (nginx, cloud LBs) don't
+ * include ports.
  *
  * @param forwarded_for - the `X-Forwarded-For` header value
  * @param proxies - parsed trusted proxy entries
- * @returns the normalized client IP, or `undefined` if the header is empty
+ * @returns the normalized client IP, or `undefined` if the header is empty / all entries malformed
  */
 export declare const resolve_client_ip: (forwarded_for: string, proxies: Array<ParsedProxy>) => string | undefined;
 /**

package/dist/http/proxy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"proxy.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/http/proxy.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,OAAO,EAAE,iBAAiB,EAAC,MAAM,MAAM,CAAC;AAErD,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAEpD,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,sBAAsB,CAAC;AAEzD;;;;;;;;GAQG;AACH,eAAO,MAAM,YAAY,GAAI,IAAI,MAAM,KAAG,MAQzC,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,YAAY;IAC5B,sFAAsF;IACtF,eAAe,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC/B,+DAA+D;IAC/D,iBAAiB,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,MAAM,GAAG,SAAS,CAAC;IACtD,wDAAwD;IACxD,GAAG,CAAC,EAAE,MAAM,CAAC;CACb;AAED;;GAEG;AACH,MAAM,MAAM,WAAW,GACpB;IAAC,IAAI,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAC,GAC7B;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAAA;CAAC,CAAC;AAElF;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB,GAAI,OAAO,MAAM,KAAG,WA6CjD,CAAC;AAiBF;;;;GAIG;AACH,eAAO,MAAM,aAAa,GAAI,IAAI,MAAM,EAAE,SAAS,KAAK,CAAC,WAAW,CAAC,KAAG,OAqBvE,CAAC;AAQF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,iBAAiB,GAC7B,eAAe,MAAM,EACrB,SAAS,KAAK,CAAC,WAAW,CAAC,KACzB,MAAM,GAAG,SAiBX,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,uBAAuB,GAAI,SAAS,YAAY,KAAG,iBAyC/D,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,4BAA4B,GAAI,SAAS,YAAY,KAAG,cAInE,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,aAAa,GAAI,GAAG,OAAO,KAAG,MAAyC,CAAC"}
+{"version":3,"file":"proxy.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/http/proxy.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,OAAO,EAAE,iBAAiB,EAAC,MAAM,MAAM,CAAC;AAErD,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAEpD,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,sBAAsB,CAAC;AAEzD;;;;;;;;GAQG;AACH,eAAO,MAAM,YAAY,GAAI,IAAI,MAAM,KAAG,MAQzC,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,YAAY;IAC5B,sFAAsF;IACtF,eAAe,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC/B,+DAA+D;IAC/D,iBAAiB,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,MAAM,GAAG,SAAS,CAAC;IACtD,wDAAwD;IACxD,GAAG,CAAC,EAAE,MAAM,CAAC;CACb;AAED;;GAEG;AACH,MAAM,MAAM,WAAW,GACpB;IAAC,IAAI,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAC,GAC7B;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAAA;CAAC,CAAC;AAElF;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB,GAAI,OAAO,MAAM,KAAG,WA6CjD,CAAC;AA2BF;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,kBAAkB,GAAI,IAAI,MAAM,KAAG,MAAM,GAAG,MAAM,GAAG,SAWjE,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,aAAa,GAAI,IAAI,MAAM,EAAE,SAAS,KAAK,CAAC,WAAW,CAAC,KAAG,OAqBvE,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,iBAAiB,GAC7B,eAAe,MAAM,EACrB,SAAS,KAAK,CAAC,WAAW,CAAC,KACzB,MAAM,GAAG,SA0BX,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,uBAAuB,GAAI,SAAS,YAAY,KAAG,iBAyC/D,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,4BAA4B,GAAI,SAAS,YAAY,KAAG,cAInE,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,aAAa,GAAI,GAAG,OAAO,KAAG,MAAyC,CAAC"}

package/dist/http/proxy.js

@@ -91,14 +91,70 @@ const cidr_contains = (ip_binary, network, prefix, total_bits) => {
     const shift = BigInt(total_bits - prefix);
     return ip_binary >> shift === network >> shift;
 };
+/**
+ * Allowed character set for a bare IP literal.
+ *
+ * Covers the union of IPv4 (digits + `.`), IPv6 (hex digits + `:`), and
+ * IPv4-mapped IPv6 forms (`::ffff:127.0.0.1`). Anything outside this
+ * set — brackets, whitespace, control bytes, letters g-z — disqualifies
+ * the input regardless of what Hono's parser does with it.
+ */
+const IP_LITERAL_CHARS = /^[0-9a-fA-F.:]+$/;
+/**
+ * Strict IP validity check.
+ *
+ * Defense in depth around Hono's `hono/utils/ipaddr` helpers, which are
+ * lax in two ways:
+ *
+ * 1. `distinctRemoteAddr` classifies anything-with-a-colon as `'IPv6'`,
+ *    including `'host:port'`, `'attacker:controlled'`, `'203.0.113.1:8080'`.
+ * 2. `convertIPv6ToBinary` silently accepts malformed forms like
+ *    `'[::1]:8080'` and `'::1\n'`, parsing them as inconsistent binary
+ *    values that would still serve as distinct rate-limit keys for an
+ *    attacker rotating the suffix.
+ *
+ * Strict validation here is two-layered: a character-set pre-filter
+ * (`IP_LITERAL_CHARS`), then a round-trip through `convertIPv*ToBinary`
+ * to confirm the input parses cleanly. Either layer alone has holes;
+ * together they reject every input form we've seen Hono mis-handle.
+ *
+ * Used as the security primitive for any code path that takes an IP
+ * string from an untrusted source (XFF, query params) and uses it as a
+ * key (rate limiting, audit subject) or compares it against trusted
+ * proxies via CIDR (where the latent throw would otherwise bubble out).
+ *
+ * @returns the address family on success, `undefined` if the string is
+ *          not a strictly-valid IP
+ */
+export const validate_ip_strict = (ip) => {
+    if (!IP_LITERAL_CHARS.test(ip))
+        return undefined;
+    const type = distinctRemoteAddr(ip);
+    if (!type)
+        return undefined;
+    try {
+        if (type === 'IPv4')
+            convertIPv4ToBinary(ip);
+        else
+            convertIPv6ToBinary(ip);
+        return type;
+    }
+    catch {
+        return undefined;
+    }
+};
 /**
  * Check whether `ip` matches any entry in the trusted proxy list.
  *
  * Normalizes `ip` before matching (lowercase, IPv4-mapped IPv6 stripped).
+ * Uses `validate_ip_strict` to reject malformed input — without strict
+ * validation, Hono's lax `distinctRemoteAddr` would let an entry like
+ * `'203.0.113.1:8080'` (false-positive `'IPv6'`) reach
+ * `convertIPv6ToBinary` in the CIDR-match branch and throw.
  */
 export const is_trusted_ip = (ip, proxies) => {
     const normalized = normalize_ip(ip);
-    const address_type = distinctRemoteAddr(normalized);
+    const address_type = validate_ip_strict(normalized);
     if (!address_type)
         return false;
     for (const proxy of proxies) {
@@ -121,22 +177,33 @@ export const is_trusted_ip = (ip, proxies) => {
     }
     return false;
 };
-// NOTE: some non-standard proxies include ports in XFF entries (e.g.
-// 203.0.113.1:8080). The entry fails distinctRemoteAddr and is treated as
-// untrusted (safe default), but rate limiting keys on the port-suffixed
-// string instead of the bare IP. Low risk — nginx and cloud LBs don't
-// include ports.
 /**
  * Resolve the real client IP from an `X-Forwarded-For` header value.
  *
- * Walks right-to-left, skipping trusted proxy entries. The first
- * non-trusted entry is the client IP. If all entries are trusted,
- * returns the leftmost entry. All entries are normalized before
- * matching and in the returned value.
+ * Walks right-to-left, skipping trusted proxy entries AND any entry
+ * that fails strict IP validation (`validate_ip_strict`). The first
+ * untrusted, strictly-valid entry is the client IP. If every walked
+ * entry is trusted or malformed, returns the leftmost strictly-valid
+ * (trusted) entry (likely-misconfigured all-trusted case) or
+ * `undefined` (everything was malformed — middleware falls back to
+ * the connection IP). All entries are normalized before matching and
+ * in the returned value.
+ *
+ * Skipping malformed entries is the rate-limit-key fix for the
+ * "attacker controls XFF and the proxy passes it through" surface —
+ * without the skip, an attacker could rotate arbitrary strings (incl.
+ * `'attacker:controlled'`, which Hono's lax `distinctRemoteAddr`
+ * misclassifies as IPv6) as XFF values to get fresh per-IP rate-limit
+ * buckets. Tradeoff: legitimate non-standard proxies that include
+ * ports in XFF entries (e.g. `203.0.113.1:8080`) also fail strict
+ * validation, so those entries get skipped and the rate-limit bucket
+ * collapses to the proxy's connection IP (one bucket for everyone
+ * behind that proxy). Standard proxies (nginx, cloud LBs) don't
+ * include ports.
  *
  * @param forwarded_for - the `X-Forwarded-For` header value
  * @param proxies - parsed trusted proxy entries
- * @returns the normalized client IP, or `undefined` if the header is empty
+ * @returns the normalized client IP, or `undefined` if the header is empty / all entries malformed
  */
 export const resolve_client_ip = (forwarded_for, proxies) => {
     const entries = [];
@@ -147,15 +214,26 @@ export const resolve_client_ip = (forwarded_for, proxies) => {
     }
     if (entries.length === 0)
         return undefined;
-    // Walk from right to left, skip trusted proxies
+    // Walk from right to left, skip trusted proxies and malformed entries.
+    // Returning a malformed entry as the client IP would let an attacker
+    // who controls XFF poison the per-IP rate-limit key.
     for (let i = entries.length - 1; i >= 0; i--) {
         const entry = entries[i];
+        if (!validate_ip_strict(entry))
+            continue;
         if (!is_trusted_ip(entry, proxies)) {
             return entry;
         }
     }
-    // All entries are trusted — return leftmost (edge case, likely misconfigured)
-    return entries[0];
+    // Every entry was trusted or malformed. Prefer the leftmost
+    // strictly-valid (trusted) entry — the misconfiguration warn in
+    // the middleware fires on it. If none, fall through to undefined
+    // and let the middleware fall back to the connection IP.
+    for (const entry of entries) {
+        if (validate_ip_strict(entry))
+            return entry;
+    }
+    return undefined;
 };
 /**
  * Create a Hono middleware that resolves the client IP from trusted proxies.