@fuzdev/fuz_app 0.63.0 → 0.64.0

package/dist/http/ip_canonical.js

@@ -0,0 +1,191 @@
+/**
+ * IP address canonicalization — collapse equivalent string forms into a
+ * single key per RFC 5952 (IPv6) plus the dotted form for IPv4-mapped
+ * IPv6 addresses.
+ *
+ * **Why this exists.** Without canonicalization, the four representations
+ * `::1`, `::01`, `::0001`, and `0:0:0:0:0:0:0:1` are the same IPv6 address
+ * but produce four distinct strings — so an attacker rotating
+ * equivalent forms behind a trusted-passthrough proxy could defeat
+ * per-IP rate limiting (each form gets a fresh bucket) and pollute
+ * `audit_log.ip` forensics. The collision can extend to IPv4-mapped
+ * IPv6 forms (`::ffff:127.0.0.1` vs `0:0:0:0:0:ffff:7f00:1` vs the
+ * bare `127.0.0.1`) — three keys for one address.
+ *
+ * Canonicalization runs through {@link canonicalize_ip} which:
+ *
+ * 1. Lowercases and char-set filters (`IP_LITERAL_CHARS`) — non-IP
+ *    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.
+ * 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).
+ * 4. Strips the `::ffff:` prefix from dotted IPv4-mapped forms so the
+ *    bucket collapses to plain IPv4 — the strip moves AFTER
+ *    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. See
+ * `~/dev/grimoire/lore/fuz_app/TODO_PROXY.md` §IPv6 String
+ * Canonicalization for the cross-backend parity record.
+ *
+ * @module
+ */
+import { convertIPv6ToBinary, distinctRemoteAddr } from 'hono/utils/ipaddr';
+/**
+ * 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 from parsing.
+ *
+ * Same regex `proxy.ts`'s `validate_ip_strict` uses; exported here so
+ * both modules can share one source of truth.
+ */
+export const IP_LITERAL_CHARS = /^[0-9a-fA-F.:]+$/;
+/**
+ * Canonicalize an IP address string.
+ *
+ * Returns the RFC 5952 canonical form for parseable IPv4 or IPv6
+ * input. Returns the input unchanged (only lowercased) when the input
+ * is non-IP (`'unknown'`), malformed (`'attacker:controlled'`,
+ * `'::1\n'`), or any string the strict char-set filter rejects.
+ *
+ * **Idempotent.** `canonicalize_ip(canonicalize_ip(x)) === canonicalize_ip(x)`
+ * for every input.
+ *
+ * **Order-safe for IPv4-mapped IPv6.** The `::ffff:` prefix strip
+ * runs AFTER the canonical emit because the canonical form of an
+ * IPv4-mapped IPv6 address is the dotted form (`::ffff:127.0.0.1`,
+ * not `::ffff:7f00:1`). Stripping before canonicalize would miss the
+ * full-hex form. Closes the
+ * `normalize_ipv4_mapped_collapse_is_order_safe` test from the Rust
+ * port.
+ *
+ * @example
+ * canonicalize_ip('::0001')                    // → '::1'
+ * canonicalize_ip('0:0:0:0:0:0:0:1')           // → '::1'
+ * canonicalize_ip('2001:0DB8::0001')           // → '2001:db8::1'
+ * canonicalize_ip('::ffff:127.0.0.1')          // → '127.0.0.1'
+ * canonicalize_ip('0:0:0:0:0:ffff:7f00:1')     // → '127.0.0.1'
+ * canonicalize_ip('::ffff:1')                  // → '::ffff:1' (NOT IPv4-mapped — group[5] is 0, not ffff)
+ * canonicalize_ip('127.0.0.1')                 // → '127.0.0.1'
+ * canonicalize_ip('not-an-ip')                 // → 'not-an-ip' (passes through)
+ * canonicalize_ip('::1\n')                     // → '::1\n' (fails char-set; passes through)
+ * canonicalize_ip('203.0.113.1:8080')          // → '203.0.113.1:8080' (passes through; validate_ip_strict rejects)
+ */
+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.
+    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.
+        return lowered;
+    }
+    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;
+};
+/**
+ * Convert a 128-bit IPv6 binary value into its RFC 5952 canonical string form.
+ *
+ * - IPv4-mapped (groups[0..5] = 0, groups[5] = 0xffff) emits the
+ *   `::ffff:a.b.c.d` dotted form per RFC 5952 §5.
+ * - Otherwise: lowercase hex with no leading zeros per group (§4.1),
+ *   the longest run of consecutive zero groups (≥ 2 groups) is
+ *   replaced with `::` (§4.2.1, §4.2.3), and on equal-length runs the
+ *   first one wins (§4.2.3). Single-zero groups stay as `0` (§4.2.2).
+ *
+ * Pure helper exported for the test suite to exercise the
+ * canonicalization invariants directly without a full
+ * `convertIPv6ToBinary` round-trip.
+ *
+ * @param bits - the 128-bit IPv6 value as `bigint` (only the low 128 bits are read)
+ */
+export const ipv6_bigint_to_canonical = (bits) => {
+    // Split into 8 16-bit groups, big-endian (group[0] is the high-order group).
+    const groups = new Array(8);
+    let remaining = bits;
+    for (let i = 7; i >= 0; i--) {
+        groups[i] = Number(remaining & 0xffffn);
+        remaining >>= 16n;
+    }
+    // IPv4-mapped detection: leading 80 bits zero, next 16 bits 0xffff.
+    if (groups[0] === 0 &&
+        groups[1] === 0 &&
+        groups[2] === 0 &&
+        groups[3] === 0 &&
+        groups[4] === 0 &&
+        groups[5] === 0xffff) {
+        const high = groups[6];
+        const low = groups[7];
+        const a = (high >> 8) & 0xff;
+        const b = high & 0xff;
+        const c = (low >> 8) & 0xff;
+        const d = low & 0xff;
+        return `::ffff:${a}.${b}.${c}.${d}`;
+    }
+    // Find longest run of consecutive zero groups for `::` compression.
+    // RFC 5952 §4.2.1: only compress runs of two or more.
+    // RFC 5952 §4.2.3: on ties, compress the first run.
+    let best_start = -1;
+    let best_len = 0;
+    let cur_start = -1;
+    let cur_len = 0;
+    for (let i = 0; i < 8; i++) {
+        if (groups[i] === 0) {
+            if (cur_start === -1)
+                cur_start = i;
+            cur_len++;
+            if (cur_len > best_len) {
+                best_start = cur_start;
+                best_len = cur_len;
+            }
+        }
+        else {
+            cur_start = -1;
+            cur_len = 0;
+        }
+    }
+    const to_hex = (g) => g.toString(16);
+    // RFC 5952 §4.2.2 — never compress a single zero group.
+    if (best_len < 2) {
+        return groups.map(to_hex).join(':');
+    }
+    const before = groups.slice(0, best_start).map(to_hex).join(':');
+    const after = groups
+        .slice(best_start + best_len)
+        .map(to_hex)
+        .join(':');
+    return before + '::' + after;
+};

package/dist/http/origin.d.ts

@@ -35,16 +35,24 @@ export declare const parse_allowed_origins: (env_value: string | undefined) => A
  * Tests if a request source (origin or referer) matches any of the allowed patterns.
  * Pattern matching is case-insensitive for domains (as per web standards).
  */
-export declare const should_allow_origin: (origin: string, allowed_patterns: Array<RegExp>) => boolean;
+export declare const should_allow_origin: (origin: string, allowed_patterns: ReadonlyArray<RegExp>) => boolean;
 /**
  * Middleware that verifies the request source against an allowlist.
  *
  * Origin allowlisting (not the CSRF layer — that's `SameSite: strict` cookies):
- * - Checks the `Origin` header first (if present)
- * - Falls back to `Referer` header (if no `Origin`)
- * - Allows requests without `Origin`/`Referer` headers (direct access, curl, etc.)
+ * - Checks the `Origin` header (if present) against the allowlist
+ * - Allows requests without an `Origin` header (direct access, curl, etc.)
+ *
+ * Origin-only by design — Fetch spec mandates `Origin` on every unsafe
+ * method (POST / PUT / DELETE / PATCH) regardless of `Referrer-Policy`,
+ * so every real browser request on the state-changing surface carries it.
+ * Non-browser clients (curl, server-to-server, CLI) don't ship auto-
+ * attached session cookies, so CSRF isn't the relevant threat there —
+ * auth (bearer / daemon token) is the actual control. A Referer fallback
+ * would only widen the accepted-shape envelope without closing a real
+ * CSRF hole; mirrors `zzz_server::auth::is_request_origin_allowed`.
  *
  * @param allowed_patterns - compiled regex patterns from `parse_allowed_origins`
  */
-export declare const verify_request_source: (allowed_patterns: Array<RegExp>) => Handler;
+export declare const verify_request_source: (allowed_patterns: ReadonlyArray<RegExp>) => Handler;
 //# sourceMappingURL=origin.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"origin.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/http/origin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,MAAM,CAAC;AAIlC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,qBAAqB,GAAI,WAAW,MAAM,GAAG,SAAS,KAAG,KAAK,CAAC,MAAM,CAO5E,CAAC;AAEP;;;GAGG;AACH,eAAO,MAAM,mBAAmB,GAAI,QAAQ,MAAM,EAAE,kBAAkB,KAAK,CAAC,MAAM,CAAC,KAAG,OACzC,CAAC;AAE9C;;;;;;;;;GASG;AACH,eAAO,MAAM,qBAAqB,GAChC,kBAAkB,KAAK,CAAC,MAAM,CAAC,KAAG,OA2BlC,CAAC"}
+{"version":3,"file":"origin.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/http/origin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,MAAM,CAAC;AAIlC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,qBAAqB,GAAI,WAAW,MAAM,GAAG,SAAS,KAAG,KAAK,CAAC,MAAM,CAO5E,CAAC;AAEP;;;GAGG;AACH,eAAO,MAAM,mBAAmB,GAC/B,QAAQ,MAAM,EACd,kBAAkB,aAAa,CAAC,MAAM,CAAC,KACrC,OAAuD,CAAC;AAE3D;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,qBAAqB,GAChC,kBAAkB,aAAa,CAAC,MAAM,CAAC,KAAG,OAgB1C,CAAC"}

package/dist/http/origin.js

@@ -10,7 +10,7 @@
  * @module
  */
 import { escape_regexp } from '@fuzdev/fuz_util/regexp.js';
-import { ERROR_FORBIDDEN_ORIGIN, ERROR_FORBIDDEN_REFERER } from './error_schemas.js';
+import { ERROR_FORBIDDEN_ORIGIN } from './error_schemas.js';
 /**
  * Parses ALLOWED_ORIGINS env var into regex matchers for request source verification.
  * Origin allowlisting for locally-running services — not the CSRF layer
@@ -47,9 +47,17 @@ export const should_allow_origin = (origin, allowed_patterns) => allowed_pattern
  * Middleware that verifies the request source against an allowlist.
  *
  * Origin allowlisting (not the CSRF layer — that's `SameSite: strict` cookies):
- * - Checks the `Origin` header first (if present)
- * - Falls back to `Referer` header (if no `Origin`)
- * - Allows requests without `Origin`/`Referer` headers (direct access, curl, etc.)
+ * - Checks the `Origin` header (if present) against the allowlist
+ * - Allows requests without an `Origin` header (direct access, curl, etc.)
+ *
+ * Origin-only by design — Fetch spec mandates `Origin` on every unsafe
+ * method (POST / PUT / DELETE / PATCH) regardless of `Referrer-Policy`,
+ * so every real browser request on the state-changing surface carries it.
+ * Non-browser clients (curl, server-to-server, CLI) don't ship auto-
+ * attached session cookies, so CSRF isn't the relevant threat there —
+ * auth (bearer / daemon token) is the actual control. A Referer fallback
+ * would only widen the accepted-shape envelope without closing a real
+ * CSRF hole; mirrors `zzz_server::auth::is_request_origin_allowed`.
  *
  * @param allowed_patterns - compiled regex patterns from `parse_allowed_origins`
  */
@@ -64,17 +72,7 @@ export const verify_request_source = (allowed_patterns) => (c, next) => {
         }
         return next();
     }
-    // Check referer header (fallback for some requests like gets and navigation).
-    // Same !== undefined check as origin.
-    const referer = c.req.header('referer');
-    if (referer !== undefined) {
-        const referer_origin = extract_origin_from_referer(referer);
-        if (!should_allow_origin(referer_origin, allowed_patterns)) {
-            return c.json({ error: ERROR_FORBIDDEN_REFERER }, 403);
-        }
-        return next();
-    }
-    // No origin or referer - direct access (curl, CLI, etc.)
+    // No origin header - direct access (curl, CLI, etc.)
     // Allow through since token auth is the primary security control.
     return next();
 };
@@ -182,19 +180,3 @@ const origin_pattern_to_regexp = (pattern) => {
     // Case-insensitive matching (web standards specify domains are case-insensitive)
     return new RegExp(regex_pattern, 'i');
 };
-/**
- * Extracts the origin from a referer URL, removing the path, query string, and fragment.
- *
- * @param referer - the referer URL (e.g., `https://fuz.dev/path?query#hash`)
- * @returns the origin part (e.g., `https://fuz.dev`)
- */
-const extract_origin_from_referer = (referer) => {
-    try {
-        return new URL(referer).origin;
-    }
-    catch {
-        // If URL parsing fails, return the original string
-        // (it will likely fail pattern matching anyway)
-        return referer;
-    }
-};

package/dist/http/pending_effects.d.ts

@@ -47,7 +47,7 @@ export interface EmitAfterCommitContext {
  * 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
+ * JS'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.
  *

package/dist/http/pending_effects.js

@@ -37,7 +37,7 @@
  * 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
+ * JS'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.
  *

package/dist/http/proxy.d.ts

@@ -13,11 +13,19 @@ import type { MiddlewareSpec } from './middleware_spec.js';
 /**
  * Normalize an IP address for consistent matching and storage.
  *
- * - Strips `::ffff:` prefix from IPv4-mapped IPv6 addresses
- *   (e.g. `::ffff:127.0.0.1` → `127.0.0.1`)
- * - Lowercases for case-insensitive IPv6 comparison
- * - Idempotent: calling twice produces the same result
- * - Safe on non-IP strings: `normalize_ip('unknown')` returns `'unknown'`
+ * Delegates to `canonicalize_ip` from `ip_canonical.ts` — collapses
+ * RFC 5952-equivalent IPv6 forms (`::1`, `::0001`, `0:0:0:0:0:0:0:1`)
+ * into a single key, emits IPv4-mapped IPv6 in dotted form, and
+ * strips the `::ffff:` prefix from dotted IPv4-mapped values so the
+ * bucket collapses to plain IPv4.
+ *
+ * - Lowercases for case-insensitive IPv6 comparison.
+ * - Idempotent: calling twice produces the same result.
+ * - Safe on non-IP strings: `normalize_ip('unknown')` returns `'unknown'`.
+ *   Malformed inputs (`'attacker:controlled'`, `'::1\n'`,
+ *   `'203.0.113.1:8080'`) pass through unchanged so downstream
+ *   `validate_ip_strict` can still reject them — canonicalization
+ *   never erases the malformed-form signal.
  */
 export declare const normalize_ip: (ip: string) => string;
 /**

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;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"}
+{"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;AAGzD;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,YAAY,GAAI,IAAI,MAAM,KAAG,MAA6B,CAAC;AAExE;;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;;;;;;;;;;;;;;;;;;;;;;;;;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

@@ -8,24 +8,25 @@
  * @module
  */
 import { convertIPv4ToBinary, convertIPv6ToBinary, distinctRemoteAddr } from 'hono/utils/ipaddr';
+import { canonicalize_ip, IP_LITERAL_CHARS } from './ip_canonical.js';
 /**
  * Normalize an IP address for consistent matching and storage.
  *
- * - Strips `::ffff:` prefix from IPv4-mapped IPv6 addresses
- *   (e.g. `::ffff:127.0.0.1` → `127.0.0.1`)
- * - Lowercases for case-insensitive IPv6 comparison
- * - Idempotent: calling twice produces the same result
- * - Safe on non-IP strings: `normalize_ip('unknown')` returns `'unknown'`
+ * Delegates to `canonicalize_ip` from `ip_canonical.ts` — collapses
+ * RFC 5952-equivalent IPv6 forms (`::1`, `::0001`, `0:0:0:0:0:0:0:1`)
+ * into a single key, emits IPv4-mapped IPv6 in dotted form, and
+ * strips the `::ffff:` prefix from dotted IPv4-mapped values so the
+ * bucket collapses to plain IPv4.
+ *
+ * - Lowercases for case-insensitive IPv6 comparison.
+ * - Idempotent: calling twice produces the same result.
+ * - Safe on non-IP strings: `normalize_ip('unknown')` returns `'unknown'`.
+ *   Malformed inputs (`'attacker:controlled'`, `'::1\n'`,
+ *   `'203.0.113.1:8080'`) pass through unchanged so downstream
+ *   `validate_ip_strict` can still reject them — canonicalization
+ *   never erases the malformed-form signal.
  */
-export const normalize_ip = (ip) => {
-    const lowered = ip.toLowerCase();
-    // Strip ::ffff: prefix only when remainder contains a dot (IPv4-mapped IPv6).
-    // This distinguishes ::ffff:127.0.0.1 (IPv4-mapped) from ::ffff:1 (pure IPv6).
-    if (lowered.startsWith('::ffff:') && lowered.substring(7).includes('.')) {
-        return lowered.substring(7);
-    }
-    return lowered;
-};
+export const normalize_ip = (ip) => canonicalize_ip(ip);
 /**
  * Parse a trusted proxy entry string into a structured form.
  *
@@ -91,15 +92,6 @@ 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.
  *

package/dist/http/surface.d.ts

@@ -13,6 +13,8 @@ import type { RouteSpec } from './route_spec.js';
 import type { RouteAuth } from './auth_shape.js';
 import type { RateLimitKey, RouteErrorSchemas } from './error_schemas.js';
 import type { RpcAction } from '../actions/action_rpc.js';
+import type { ActionKind } from '../actions/action_spec.js';
+import type { WsEndpointSpec } from '../actions/ws_endpoint_spec.js';
 import type { Sensitivity } from '../sensitivity.js';
 /** A route in the generated attack surface (JSON-serializable). */
 export interface AppSurfaceRoute {
@@ -79,6 +81,45 @@ export interface AppSurfaceRpcEndpoint {
     path: string;
     methods: Array<AppSurfaceRpcMethod>;
 }
+/** A method within a WebSocket endpoint in the generated attack surface (JSON-serializable). */
+export interface AppSurfaceWsMethod {
+    name: string;
+    /** `request_response` (inbound dispatch) or `remote_notification` (server → client). */
+    kind: ActionKind;
+    /**
+     * Per-action auth shape. `null` for `remote_notification` (server →
+     * client) — notifications have no inbound dispatch and therefore no
+     * auth axis. `request_response` always carries a `RouteAuth`.
+     */
+    auth: RouteAuth | null;
+    /** JSON Schema of the input schema. `null` for nullary inputs. */
+    input_schema: unknown;
+    /** JSON Schema of the output schema. */
+    output_schema: unknown;
+    description: string;
+    side_effects: boolean;
+    /** Rate limit key declared on the action spec. `null` when not rate-limited. */
+    rate_limit_key: RateLimitKey | null;
+}
+/** A WebSocket endpoint in the generated attack surface (JSON-serializable). */
+export interface AppSurfaceWsEndpoint {
+    path: string;
+    /**
+     * Upgrade-time origin allowlist, one entry per `WsEndpointSpec.allowed_origins`
+     * regex stringified via `RegExp.prototype.toString()` (`'/<source>/<flags>'`).
+     * Empty array when no origins were declared (any-origin); reviewers read this
+     * as the exact pattern matched at the upgrade gate, not a wildcard
+     * approximation. Reconstruct via `new RegExp(source, flags)` if needed.
+     */
+    allowed_origins: ReadonlyArray<string>;
+    /**
+     * Upgrade-time role gate — empty array when no `required_roles` was
+     * declared (any-authenticated). Documents the coarse gate; per-action
+     * `auth` on each method covers per-message authorization.
+     */
+    required_roles: ReadonlyArray<string>;
+    methods: Array<AppSurfaceWsMethod>;
+}
 /** Assembly-time diagnostic collected during surface generation or server assembly. */
 export interface AppSurfaceDiagnostic {
     level: 'warning' | 'info';
@@ -91,6 +132,7 @@ export interface AppSurface {
     middleware: Array<AppSurfaceMiddleware>;
     routes: Array<AppSurfaceRoute>;
     rpc_endpoints: Array<AppSurfaceRpcEndpoint>;
+    ws_endpoints: Array<AppSurfaceWsEndpoint>;
     env: Array<AppSurfaceEnv>;
     events: Array<AppSurfaceEvent>;
     diagnostics: Array<AppSurfaceDiagnostic>;
@@ -106,6 +148,7 @@ export interface AppSurfaceSpec {
     route_specs: Array<RouteSpec>;
     middleware_specs: Array<MiddlewareSpec>;
     rpc_endpoints: Array<RpcEndpointSpec>;
+    ws_endpoints: Array<WsEndpointSpec>;
 }
 /** An RPC endpoint definition for surface generation. */
 export interface RpcEndpointSpec {
@@ -119,6 +162,13 @@ export interface GenerateAppSurfaceOptions {
     env_schema?: z.ZodObject;
     event_specs?: Array<EventSpec>;
     rpc_endpoints?: Array<RpcEndpointSpec>;
+    /**
+     * Mounted WS endpoints (the same array `create_app_server.ws_endpoints`
+     * auto-mounts). Each entry's actions surface into
+     * `AppSurface.ws_endpoints[i].methods` for attack-surface tests +
+     * startup logging.
+     */
+    ws_endpoints?: ReadonlyArray<WsEndpointSpec>;
 }
 /**
  * Collect error schemas from all middleware that applies to a route path.

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

@@ -1 +1 @@
-{"version":3,"file":"surface.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/http/surface.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAEtB,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,oBAAoB,CAAC;AAClD,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,sBAAsB,CAAC;AACzD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,iBAAiB,CAAC;AAC/C,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,iBAAiB,CAAC;AAC/C,OAAO,KAAK,EAAC,YAAY,EAAE,iBAAiB,EAAC,MAAM,oBAAoB,CAAC;AACxE,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,0BAA0B,CAAC;AAQxD,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,mBAAmB,CAAC;AAKnD,mEAAmE;AACnE,MAAM,WAAW,eAAe;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,SAAS,CAAC;IAChB,qBAAqB,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACrC,WAAW,EAAE,MAAM,CAAC;IACpB,mEAAmE;IACnE,WAAW,EAAE,OAAO,CAAC;IACrB,uEAAuE;IACvE,WAAW,EAAE,OAAO,CAAC;IACrB,oFAAoF;IACpF,cAAc,EAAE,YAAY,GAAG,IAAI,CAAC;IACpC,uFAAuF;IACvF,aAAa,EAAE,OAAO,CAAC;IACvB,8FAA8F;IAC9F,YAAY,EAAE,OAAO,CAAC;IACtB,wFAAwF;IACxF,YAAY,EAAE,OAAO,CAAC;IACtB,iEAAiE;IACjE,aAAa,EAAE,OAAO,CAAC;IACvB,mGAAmG;IACnG,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CAC9C;AAED,wEAAwE;AACxE,MAAM,WAAW,oBAAoB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,mGAAmG;IACnG,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CAC9C;AAED,sEAAsE;AACtE,MAAM,WAAW,aAAa;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,gFAAgF;IAChF,WAAW,EAAE,WAAW,GAAG,IAAI,CAAC;IAChC,WAAW,EAAE,OAAO,CAAC;IACrB,QAAQ,EAAE,OAAO,CAAC;CAClB;AAED,wEAAwE;AACxE,MAAM,WAAW,eAAe;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,aAAa,EAAE,OAAO,CAAC;CACvB;AAED,2FAA2F;AAC3F,MAAM,WAAW,mBAAmB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,SAAS,CAAC;IAChB,qFAAqF;IACrF,YAAY,EAAE,OAAO,CAAC;IACtB,uDAAuD;IACvD,aAAa,EAAE,OAAO,CAAC;IACvB,YAAY,EAAE,OAAO,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,gFAAgF;IAChF,cAAc,EAAE,YAAY,GAAG,IAAI,CAAC;CACpC;AAED,2EAA2E;AAC3E,MAAM,WAAW,qBAAqB;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,KAAK,CAAC,mBAAmB,CAAC,CAAC;CACpC;AAED,uFAAuF;AACvF,MAAM,WAAW,oBAAoB;IACpC,KAAK,EAAE,SAAS,GAAG,MAAM,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,oDAAoD;AACpD,MAAM,WAAW,UAAU;IAC1B,UAAU,EAAE,KAAK,CAAC,oBAAoB,CAAC,CAAC;IACxC,MAAM,EAAE,KAAK,CAAC,eAAe,CAAC,CAAC;IAC/B,aAAa,EAAE,KAAK,CAAC,qBAAqB,CAAC,CAAC;IAC5C,GAAG,EAAE,KAAK,CAAC,aAAa,CAAC,CAAC;IAC1B,MAAM,EAAE,KAAK,CAAC,eAAe,CAAC,CAAC;IAC/B,WAAW,EAAE,KAAK,CAAC,oBAAoB,CAAC,CAAC;CACzC;AAED;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC9B,OAAO,EAAE,UAAU,CAAC;IACpB,WAAW,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;IAC9B,gBAAgB,EAAE,KAAK,CAAC,cAAc,CAAC,CAAC;IACxC,aAAa,EAAE,KAAK,CAAC,eAAe,CAAC,CAAC;CACtC;AAED,yDAAyD;AACzD,MAAM,WAAW,eAAe;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;CAC1B;AAED,0CAA0C;AAC1C,MAAM,WAAW,yBAAyB;IACzC,WAAW,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;IAC9B,gBAAgB,EAAE,KAAK,CAAC,cAAc,CAAC,CAAC;IACxC,UAAU,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC;IACzB,WAAW,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;IAC/B,aAAa,CAAC,EAAE,KAAK,CAAC,eAAe,CAAC,CAAC;CACvC;AAID;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,GACrC,YAAY,KAAK,CAAC,cAAc,CAAC,EACjC,YAAY,MAAM,KAChB,iBAAiB,GAAG,IAQtB,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,GAAI,QAAQ,CAAC,CAAC,SAAS,KAAG,KAAK,CAAC,aAAa,CAe9E,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,iBAAiB,GAAI,aAAa,KAAK,CAAC,SAAS,CAAC,KAAG,KAAK,CAAC,eAAe,CAOtF,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,oBAAoB,GAAI,SAAS,yBAAyB,KAAG,UAyFzE,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,uBAAuB,GAAI,SAAS,yBAAyB,KAAG,cAQ5E,CAAC"}
+{"version":3,"file":"surface.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/http/surface.ts"],"names":[],"mappings":"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"}

package/dist/http/surface.js

@@ -60,7 +60,7 @@ export const events_to_surface = (event_specs) => {
  * and optional env/event metadata.
  */
 export const generate_app_surface = (options) => {
-    const { route_specs, middleware_specs, env_schema, event_specs, rpc_endpoints } = options;
+    const { route_specs, middleware_specs, env_schema, event_specs, rpc_endpoints, ws_endpoints } = options;
     const diagnostics = [];
     // Spec-level diagnostics: check for non-strict input schemas
     for (const r of route_specs) {
@@ -141,6 +141,31 @@ export const generate_app_surface = (options) => {
                 })),
             }))
             : [],
+        ws_endpoints: ws_endpoints?.length
+            ? ws_endpoints.map((ep) => ({
+                path: ep.path,
+                allowed_origins: ep.allowed_origins.map((re) => re.toString()),
+                required_roles: ep.required_roles ?? [],
+                // `local_call` specs are frontend-side helpers — registry-only
+                // on the backend, never dispatched over WS. Drop them from the
+                // surface so attack-surface tests reflect dispatchable methods
+                // only. Notifications are kept (server → client emit).
+                methods: ep.actions
+                    .filter((a) => a.spec.kind !== 'local_call')
+                    .map((a) => ({
+                    name: a.spec.method,
+                    kind: a.spec.kind,
+                    // `request_response` carries a `RouteAuth`; notifications
+                    // have `auth: null` (server-pushed, no inbound dispatch).
+                    auth: a.spec.auth,
+                    input_schema: schema_to_surface(a.spec.input),
+                    output_schema: schema_to_surface(a.spec.output),
+                    description: a.spec.description,
+                    side_effects: a.spec.side_effects,
+                    rate_limit_key: a.spec.kind === 'request_response' ? (a.spec.rate_limit ?? null) : null,
+                })),
+            }))
+            : [],
         env: env_schema ? env_schema_to_surface(env_schema) : [],
         events: event_specs?.length ? events_to_surface(event_specs) : [],
     };
@@ -155,5 +180,6 @@ export const create_app_surface_spec = (options) => {
         route_specs: options.route_specs,
         middleware_specs: options.middleware_specs,
         rpc_endpoints: options.rpc_endpoints ?? [],
+        ws_endpoints: options.ws_endpoints ? [...options.ws_endpoints] : [],
     };
 };

package/dist/primitive_schemas.d.ts

@@ -21,11 +21,27 @@ export declare const USERNAME_LENGTH_MIN = 3;
 export declare const USERNAME_LENGTH_MAX = 39;
 /** Maximum length for username input on login/lookup — more permissive than `USERNAME_LENGTH_MAX` for forward-compatibility if the creation limit is raised. */
 export declare const USERNAME_PROVIDED_LENGTH_MAX = 255;
-/** Username for account creation — starts with letter, alphanumeric/dash/underscore middle, ends with alphanumeric. No @ or . allowed. */
-export declare const Username: z.ZodString;
+/**
+ * Username for account creation — starts with letter, alphanumeric/dash/underscore middle, ends with alphanumeric. No @ or . allowed.
+ *
+ * Canonicalized to lowercase at parse time. The regex rejects whitespace
+ * outright, so `.trim()` is unnecessary here. Storage is canonical across
+ * every creation site (bootstrap, signup, admin-create, invite acceptance)
+ * because the schema is the single source of truth — eliminates the
+ * per-caller `trim().toLowerCase()` ritual and keeps the
+ * `LOWER(username) = LOWER($1)` lookup contract simple.
+ */
+export declare const Username: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
 export type Username = z.infer<typeof Username>;
-/** Username submitted for login or lookup — minimal validation for forward-compatibility if format rules change. */
-export declare const UsernameProvided: z.ZodString;
+/**
+ * Username submitted for login or lookup — minimal validation for forward-compatibility if format rules change.
+ *
+ * Canonicalized via `.trim().toLowerCase()` at parse time so login's
+ * per-account rate-limit key and DB lookup see a uniform value
+ * regardless of casing or surrounding whitespace. Mirrors the storage
+ * canonicalization on `Username` so submission and storage agree.
+ */
+export declare const UsernameProvided: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
 export type UsernameProvided = z.infer<typeof UsernameProvided>;
 /**
  * Email validation. Lives here rather than `@fuzdev/fuz_util` because every

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;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAItB,2EAA2E;AAC3E,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAErC,wDAAwD;AACxD,eAAO,MAAM,mBAAmB,KAAK,CAAC;AAEtC,gKAAgK;AAChK,eAAO,MAAM,4BAA4B,MAAM,CAAC;AAEhD,0IAA0I;AAC1I,eAAO,MAAM,QAAQ,aAIyB,CAAC;AAC/C,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,QAAQ,CAAC,CAAC;AAEhD,oHAAoH;AACpH,eAAO,MAAM,gBAAgB,aAAsD,CAAC;AACpF,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEhE;;;;;;GAMG;AACH,eAAO,MAAM,KAAK,YAAY,CAAC;AAC/B,MAAM,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,KAAK,CAAC,CAAC"}
+{"version":3,"file":"primitive_schemas.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/primitive_schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAItB,2EAA2E;AAC3E,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAErC,wDAAwD;AACxD,eAAO,MAAM,mBAAmB,KAAK,CAAC;AAEtC,gKAAgK;AAChK,eAAO,MAAM,4BAA4B,MAAM,CAAC;AAEhD;;;;;;;;;GASG;AACH,eAAO,MAAM,QAAQ,wDAKc,CAAC;AACpC,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,QAAQ,CAAC,CAAC;AAEhD;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,wDAIa,CAAC;AAC3C,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEhE;;;;;;GAMG;AACH,eAAO,MAAM,KAAK,YAAY,CAAC;AAC/B,MAAM,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,KAAK,CAAC,CAAC"}

package/dist/primitive_schemas.js

@@ -22,14 +22,35 @@ export const USERNAME_LENGTH_MIN = 3;
 export const USERNAME_LENGTH_MAX = 39;
 /** Maximum length for username input on login/lookup — more permissive than `USERNAME_LENGTH_MAX` for forward-compatibility if the creation limit is raised. */
 export const USERNAME_PROVIDED_LENGTH_MAX = 255;
-/** Username for account creation — starts with letter, alphanumeric/dash/underscore middle, ends with alphanumeric. No @ or . allowed. */
+/**
+ * Username for account creation — starts with letter, alphanumeric/dash/underscore middle, ends with alphanumeric. No @ or . allowed.
+ *
+ * Canonicalized to lowercase at parse time. The regex rejects whitespace
+ * outright, so `.trim()` is unnecessary here. Storage is canonical across
+ * every creation site (bootstrap, signup, admin-create, invite acceptance)
+ * because the schema is the single source of truth — eliminates the
+ * per-caller `trim().toLowerCase()` ritual and keeps the
+ * `LOWER(username) = LOWER($1)` lookup contract simple.
+ */
 export const Username = z
     .string()
     .min(USERNAME_LENGTH_MIN)
     .max(USERNAME_LENGTH_MAX)
-    .regex(/^[a-zA-Z][0-9a-zA-Z_-]*[0-9a-zA-Z]$/);
-/** Username submitted for login or lookup — minimal validation for forward-compatibility if format rules change. */
-export const UsernameProvided = z.string().min(1).max(USERNAME_PROVIDED_LENGTH_MAX);
+    .regex(/^[a-zA-Z][0-9a-zA-Z_-]*[0-9a-zA-Z]$/)
+    .transform((s) => s.toLowerCase());
+/**
+ * Username submitted for login or lookup — minimal validation for forward-compatibility if format rules change.
+ *
+ * Canonicalized via `.trim().toLowerCase()` at parse time so login's
+ * per-account rate-limit key and DB lookup see a uniform value
+ * regardless of casing or surrounding whitespace. Mirrors the storage
+ * canonicalization on `Username` so submission and storage agree.
+ */
+export const UsernameProvided = z
+    .string()
+    .min(1)
+    .max(USERNAME_PROVIDED_LENGTH_MAX)
+    .transform((s) => s.trim().toLowerCase());
 /**
  * Email validation. Lives here rather than `@fuzdev/fuz_util` because every
  * current consumer pairs it with `Username` (signup, invites, audit log) —