@fuzdev/fuz_app 0.62.0 → 0.64.0

package/dist/http/CLAUDE.md

@@ -5,12 +5,12 @@ surface introspection, JSON-RPC envelope + error taxonomy, proxy/origin
 middleware primitives, post-commit effect helper, generic admin route specs.
 
 **Nothing in this directory is auth-specific.** Auth middleware, routes, and
-guards live in `../auth/` and consume these primitives. Routes and actions in
+guards live in `auth/` and consume these primitives. Routes and actions in
 other domains should do the same — extend, don't special-case.
 
 For the design rationale behind declarative routes, DEV-only output
 validation, the three-layer error-schema merge, and fire-and-forget effects,
-see `../../docs/architecture.md`.
+see ../../docs/architecture.md.
 
 ## Module Map
 
@@ -24,7 +24,8 @@ see `../../docs/architecture.md`.
 | `surface.ts`         | `AppSurface`, `AppSurfaceSpec`, `generate_app_surface`, diagnostics                                    |
 | `surface_query.ts`   | Pure filters/groupings over `AppSurface`                                                               |
 | `proxy.ts`           | Trusted-proxy middleware, CIDR parsing, rightmost-first XFF resolution                                 |
-| `origin.ts`          | Origin/Referer allowlist middleware with wildcard patterns                                             |
+| `ip_canonical.ts`    | RFC 5952 IPv6 canonicalization + IPv4-mapped collapse; `IP_LITERAL_CHARS` regex                        |
+| `origin.ts`          | Origin allowlist middleware with wildcard patterns (Origin-only)                                       |
 | `jsonrpc.ts`         | JSON-RPC 2.0 envelope schemas (MCP superset), `JsonrpcErrorCode`, `_meta`                              |
 | `jsonrpc_errors.ts`  | `ThrownJsonrpcError`, `jsonrpc_errors` throwers, HTTP-status mappings                                  |
 | `jsonrpc_helpers.ts` | Message builders, type guards, input/result normalizers                                                |
@@ -42,7 +43,7 @@ by `generate_app_surface`. Same-shaped data, different consumers.
 
 - `method` — `'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH'`
 - `path` — Hono path (supports `:param` segments)
-- `auth: RouteAuth` — flat record `{account, actor, roles?, credential_types?}` from `auth_shape.ts`. Each axis is `'none' | 'optional' | 'required'`. Same shape governs `ActionSpec.auth` (see `../actions/CLAUDE.md`).
+- `auth: RouteAuth` — flat record `{account, actor, roles?, credential_types?}` from `auth_shape.ts`. Each axis is `'none' | 'optional' | 'required'`. Same shape governs `ActionSpec.auth` (see `actions/CLAUDE.md`).
 - `handler: RouteHandler` — `(c: Context, route: RouteContext) => Response | Promise<Response>`
 - `description` — free-text, surfaced in `AppSurface`
 - `params?: z.ZodObject` — strict-object schema for URL path params
@@ -84,7 +85,7 @@ interface RouteContext {
   `db.transaction`.
 
 Pool-level fire-and-forget writes (audit logs, etc.) run through the bound
-`AppDeps.audit` capability — see `../auth/CLAUDE.md` §Deps. Handlers that
+`AppDeps.audit` capability — see `auth/CLAUDE.md` §Deps. Handlers that
 need rollback-resilient writes call `deps.audit.emit(route, input)`, which
 captures the pool inside the bound emitter so the row lands even when
 the handler's transaction rolls back.
@@ -98,7 +99,7 @@ the handler's transaction rolls back.
 
 Override explicitly when a mutation route must manage its own transactions
 (e.g. signup, which does a multi-step flow that can't live inside a single
-wrapper). See `../auth/signup_routes.ts`.
+wrapper). See `auth/signup_routes.ts`.
 
 ### Validation pipeline (per-route middleware order)
 
@@ -114,7 +115,7 @@ wrapper). See `../auth/signup_routes.ts`.
    or `auth.actor === 'required'`. Fires before any body parsing so
    unauthenticated callers never see route-shape information from
    input parse failures. The `AuthGuardResolver` (e.g.
-   `fuz_auth_guard_resolver` from `../auth/auth_guard_resolver.ts`) returns
+   `fuz_auth_guard_resolver` from `auth/auth_guard_resolver.ts`) returns
    this set as `pre_validation: Array<MiddlewareHandler>`.
 4. **Input validation** — JSON body parsed + validated; mismatch returns
    400 `ERROR_INVALID_JSON_BODY` (not JSON) or `ERROR_INVALID_REQUEST_BODY`
@@ -191,7 +192,7 @@ are the contract with external callers.
 
 The production behavior short-circuits to the unwrapped handler — no
 parse work on the hot path. Uniform across all three action-handler
-surfaces (REST, RPC, WS); see `../../docs/architecture.md` §DEV-only
+surfaces (REST, RPC, WS); see ../../docs/architecture.md §DEV-only
 Output Validation.
 
 ### Helpers
@@ -205,8 +206,8 @@ Output Validation.
 
 `error_schemas.ts` is the **declarative** error surface:
 
-- `ERROR_*` snake*case string constants — single source of truth; use
-  `.literal(ERROR*\*)` in Zod schemas and inline checks in handlers
+- `ERROR_*` `snake_case` string constants — single source of truth; use
+  `.literal(ERROR_*)` in Zod schemas and inline checks in handlers
 - `ApiError`, `ValidationError`, `PermissionError`,
   `CredentialTypeRequiredError`, `RateLimitError`, `PayloadTooLargeError`,
   `ForeignKeyError` — standard shapes
@@ -280,7 +281,7 @@ invariant 2's throw) was the empirical confirmation.
 - **Auth**: `ERROR_AUTHENTICATION_REQUIRED`, `ERROR_INSUFFICIENT_PERMISSIONS`,
   `ERROR_CREDENTIAL_TYPE_REQUIRED`, `ERROR_RATE_LIMIT_EXCEEDED`,
   `ERROR_INVALID_CREDENTIALS`, `ERROR_PAYLOAD_TOO_LARGE`
-- **Origin + bearer**: `ERROR_FORBIDDEN_ORIGIN`, `ERROR_FORBIDDEN_REFERER`,
+- **Origin + bearer**: `ERROR_FORBIDDEN_ORIGIN`, `ERROR_FORBIDDEN_REFERER` (retained for consumer compat; no longer emitted),
   `ERROR_BEARER_REJECTED_BROWSER`, `ERROR_INVALID_TOKEN`, `ERROR_ACCOUNT_NOT_FOUND`
 - **Keeper/daemon**: `ERROR_INVALID_DAEMON_TOKEN`,
   `ERROR_KEEPER_ACCOUNT_NOT_CONFIGURED`, `ERROR_KEEPER_ACCOUNT_NOT_FOUND`
@@ -413,12 +414,17 @@ connection is from a configured trusted proxy. Without this middleware,
 `get_client_ip(c)` returns `'unknown'`.
 
 Must run **before** auth and rate-limiting middleware. See the root
-`../../CLAUDE.md` §Middleware Ordering.
-
-- `normalize_ip(ip)` — idempotent: lowercase + strip `::ffff:` prefix on
-  IPv4-mapped IPv6 addresses; safe on non-IP strings (`'unknown'` → `'unknown'`).
-  Subtle: only strips `::ffff:` when the suffix contains `.`, so pure
-  IPv6 like `::ffff:1` is preserved
+../../CLAUDE.md §Middleware Ordering.
+
+- `normalize_ip(ip)` — delegates to `canonicalize_ip` from `ip_canonical.ts`:
+  RFC 5952 IPv6 canonicalization (lowercase hex, longest-zero-run
+  compression), IPv4-mapped IPv6 emitted in dotted form and stripped of
+  the `::ffff:` prefix so the bucket collapses to plain IPv4. Idempotent;
+  safe on non-IP strings (`'unknown'` → `'unknown'`); strict char-set
+  filter (`IP_LITERAL_CHARS`) preserves malformed forms unchanged so
+  downstream `validate_ip_strict` can still reject them. Pure IPv6 like
+  `::ffff:1` (group[5]=0, not 0xffff — NOT IPv4-mapped) stays preserved.
+  Mirrors `zzz_server::proxy::normalize_ip`
 - `ProxyOptions` — `{trusted_proxies, get_connection_ip, log?}`
 - `ParsedProxy` — `{type: 'ip'; address}` or `{type: 'cidr'; network; prefix; address_type}`
 - `parse_proxy_entry(entry)` — accepts `'127.0.0.1'`, `'::1'`,
@@ -461,19 +467,29 @@ distinction in rate limiting and collapse to the proxy's connection
 IP (one bucket for everyone behind that proxy). nginx + cloud LBs
 don't include ports — bounded by operator configuration in practice.
 
-### Origin/Referer allowlist — `origin.ts`
+### Origin allowlist — `origin.ts`
 
 Origin allowlisting for locally-running services — **not** the CSRF
 layer. CSRF is handled by `SameSite: strict` on session cookies (see
-`../auth/session_middleware.ts`).
+`auth/session_middleware.ts`).
 
 - `parse_allowed_origins(env_value)` — comma-separated patterns → `Array<RegExp>`
 - `should_allow_origin(origin, patterns)` — case-insensitive match
 - `verify_request_source(allowed_patterns)` — Hono handler:
   1. `Origin` header present → must match allowlist or 403 `ERROR_FORBIDDEN_ORIGIN`
-  2. No `Origin` + `Referer` present → extract origin, check, 403
-     `ERROR_FORBIDDEN_REFERER` on mismatch
-  3. Neither header → allow through (curl, CLI, token auth is primary control)
+  2. No `Origin` → allow through (curl, CLI, token auth is primary control)
+
+**Origin-only by design.** Fetch spec mandates `Origin` on every unsafe
+method, so a real browser request on any state-changing surface always
+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`.
+
+`ERROR_FORBIDDEN_REFERER` stays exported from `error_schemas.ts` for
+consumers whose error-schema unions or test assertions still reference
+it — the emit site is gone, the constant is not.
 
 Pattern syntax:
 
@@ -664,7 +680,7 @@ emit_after_commit(ctx, () => notification_sender.send_to_account(account_id, msg
 ```
 
 Used for WS sends (`NotificationSender.send_to_account` for
-role-grant-offer notifications — see `../auth/CLAUDE.md` §WS notifications)
+role-grant-offer notifications — see `auth/CLAUDE.md` §WS notifications)
 and any side effect that must run only after the transaction commits.
 
 ### Key properties
@@ -712,7 +728,7 @@ auth-domain dependencies:
   surface data reveals API structure (schemas, auth, routes)
 
 Auth-aware variants (account status, bootstrap status) live in
-`../auth/` — `common_routes.ts` stays generic.
+`auth/` — `common_routes.ts` stays generic.
 
 ## DB Routes (Generic Browser)
 
@@ -743,7 +759,7 @@ Interfaces exported for consumer use: `TableInfo`, `TableWithCount`,
 ## Cross-Module Notes
 
 - **Middleware ordering** is assembled by `create_app_server` — see the
-  root `../../CLAUDE.md` §Middleware Ordering. The invariants `http/`
+  root ../../CLAUDE.md §Middleware Ordering. The invariants `http/`
   needs consumers to uphold: trusted-proxy runs before auth/rate-limit;
   origin verification runs before session parsing; `client_ip` must be
   set before any handler or rate limiter reads it
@@ -753,7 +769,7 @@ Interfaces exported for consumer use: `TableInfo`, `TableWithCount`,
 - **Input/output schemas align with SAES.** When wiring RPC via
   `actions/action_rpc.ts` or bridging to `RouteSpec` via
   `actions/action_bridge.ts`, the same Zod types flow through unchanged
-  (see `../actions/CLAUDE.md` §Single JSON-RPC 2.0 endpoint and §HTTP bridge)
+  (see `actions/CLAUDE.md` §Single JSON-RPC 2.0 endpoint and §HTTP bridge)
 - **Error modules are complementary, not redundant.** `error_schemas.ts`
   is Zod-first (for routes and surface); `jsonrpc_errors.ts` is
   throw-first (for handlers and the catch layer). A single `ERROR_*`

package/dist/http/ip_canonical.d.ts

@@ -0,0 +1,99 @@
+/**
+ * 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
+ */
+/**
+ * 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 declare const IP_LITERAL_CHARS: RegExp;
+/**
+ * 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 declare const canonicalize_ip: (ip: string) => string;
+/**
+ * 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 declare const ipv6_bigint_to_canonical: (bits: bigint) => string;
+//# sourceMappingURL=ip_canonical.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ip_canonical.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/http/ip_canonical.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAIH;;;;;;;;;;GAUG;AACH,eAAO,MAAM,gBAAgB,QAAqB,CAAC;AAEnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,eAAe,GAAI,IAAI,MAAM,KAAG,MAmC5C,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,wBAAwB,GAAI,MAAM,MAAM,KAAG,MA6DvD,CAAC"}

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