@usequark/quark-create-app 1.27.1 → 1.27.3

package/templates/base-project/apps/web/src/lib/analytics/umami-config.js

@@ -48,6 +48,61 @@ export function getUmamiScriptUrl(value) {
 	return `${normalizedUrl}/script.js`;
 }
 
+// ─── First-party proxy ───────────────────────────────────────────────────────
+// The tracker, web-vitals beacons, and replay batches are served through
+// same-origin URLs so blocklists never see the upstream analytics host.
+// Base `/s` carries no `umami|analytics|track|stats|collect|send` token;
+// the `/api/*` suffix under it preserves the tracker's `data-host-url`
+// convention (`data-host-url="/s"` → POST `/s/api/send` with zero forks).
+export const UMAMI_PROXY_BASE = "/s";
+export const UMAMI_PROXY_SCRIPT_PATH = "/s/script.js";
+export const UMAMI_PROXY_HOST_URL = "/s";
+export const UMAMI_PROXY_SEND_PATH = "/s/api/send";
+// Legacy alias for pre-v2 Umami (whose ingest lived at /api/collect). Nothing
+// in the scaffold posts here anymore — web-vitals uses the send schema — but
+// the pinned path costs nothing to keep forwarding. Do not remove without
+// checking supported upstream versions.
+export const UMAMI_PROXY_COLLECT_PATH = "/s/api/collect";
+export const UMAMI_PROXY_RECORD_PATH = "/s/api/record";
+
+// Server-side upstream preference: an operator that wants the analytics host
+// out of the client bundle entirely sets UMAMI_UPSTREAM_URL (or UMAMI_URL)
+// and the rewrite/handler destination follows it. NEXT_PUBLIC_UMAMI_URL
+// remains the default so existing deployments keep working with no new vars.
+export function getUmamiUpstreamBase(env = process.env) {
+	const candidates = [
+		env.UMAMI_UPSTREAM_URL,
+		env.UMAMI_URL,
+		env.NEXT_PUBLIC_UMAMI_URL,
+	];
+
+	for (const candidate of candidates) {
+		const normalized = normalizeUmamiUrl(candidate);
+		if (normalized) return normalized;
+	}
+
+	return "";
+}
+
+// Default env for browser-safe readers. Each NEXT_PUBLIC_* access MUST stay
+// a literal member expression: Next.js statically inlines those literals in
+// client bundles, where bare `process` does not exist — a whole-`process.env`
+// default throws ReferenceError in every browser, which previously killed
+// track(), web-vitals, and replay client-side. Do not refactor this into a
+// `process.env` passthrough. Exported for tests (the no-process fallback).
+export function readPublicEnv() {
+	try {
+		return {
+			NEXT_PUBLIC_UMAMI_URL: process.env.NEXT_PUBLIC_UMAMI_URL,
+			NEXT_PUBLIC_UMAMI_WEBSITE_ID: process.env.NEXT_PUBLIC_UMAMI_WEBSITE_ID,
+			NEXT_PUBLIC_UMAMI_REPLAY_ENABLED:
+				process.env.NEXT_PUBLIC_UMAMI_REPLAY_ENABLED,
+		};
+	} catch {
+		return {};
+	}
+}
+
 export function parseUmamiBooleanFlag(value) {
 	if (typeof value !== "string") return false;
 	return TRUE_VALUES.has(value.trim().toLowerCase());
@@ -59,7 +114,7 @@ export function isUmamiWebsiteId(value) {
 }
 
 export function getUmamiConfig(env = process.env) {
-	const url = normalizeUmamiUrl(env.NEXT_PUBLIC_UMAMI_URL);
+	const url = getUmamiUpstreamBase(env);
 	const rawWebsiteId =
 		typeof env.NEXT_PUBLIC_UMAMI_WEBSITE_ID === "string"
 			? env.NEXT_PUBLIC_UMAMI_WEBSITE_ID.trim()
@@ -76,20 +131,55 @@ export function getUmamiConfig(env = process.env) {
 		enabled,
 		replayEnabled:
 			enabled && parseUmamiBooleanFlag(env.NEXT_PUBLIC_UMAMI_REPLAY_ENABLED),
+		// First-party proxy URLs. Empty when analytics is disabled so
+		// callers can gate on `enabled` alone.
+		proxyBase: enabled ? UMAMI_PROXY_BASE : "",
+		proxyScriptUrl: enabled ? UMAMI_PROXY_SCRIPT_PATH : "",
+		proxyHostUrl: enabled ? UMAMI_PROXY_HOST_URL : "",
+		proxySendUrl: enabled ? UMAMI_PROXY_SEND_PATH : "",
+		proxyCollectUrl: enabled ? UMAMI_PROXY_COLLECT_PATH : "",
+		proxyRecordUrl: enabled ? UMAMI_PROXY_RECORD_PATH : "",
 	};
 }
 
-export function getUmamiCspOrigins(env = process.env) {
-	const config = getUmamiConfig(env);
-	if (!config.enabled || !config.origin) {
-		return {
-			scriptSrc: [],
-			connectSrc: [],
-		};
-	}
+// Client-safe config. Contains no upstream URL, origin, or script URL — only
+// the website ID, gates, and static first-party proxy paths. Browser code
+// must use this (never getUmamiConfig) so the analytics host cannot end up
+// in client bundles. `enabled` needs only a valid website ID because every
+// client surface is same-origin; the server layout keeps the upstream-aware
+// gate so a missing upstream never emits a 404 script tag.
+//
+// The default env is readPublicEnv(), not process.env: bare `process` does
+// not exist in browsers, so a process.env default throws on every no-arg
+// browser call.
+export function getUmamiClientConfig(env = readPublicEnv()) {
+	const rawWebsiteId =
+		typeof env.NEXT_PUBLIC_UMAMI_WEBSITE_ID === "string"
+			? env.NEXT_PUBLIC_UMAMI_WEBSITE_ID.trim()
+			: "";
+	const websiteId = isUmamiWebsiteId(rawWebsiteId) ? rawWebsiteId : "";
+	const enabled = Boolean(websiteId);
+
+	return {
+		websiteId,
+		enabled,
+		replayEnabled:
+			enabled && parseUmamiBooleanFlag(env.NEXT_PUBLIC_UMAMI_REPLAY_ENABLED),
+		proxyBase: enabled ? UMAMI_PROXY_BASE : "",
+		proxyScriptUrl: enabled ? UMAMI_PROXY_SCRIPT_PATH : "",
+		proxyHostUrl: enabled ? UMAMI_PROXY_HOST_URL : "",
+		proxySendUrl: enabled ? UMAMI_PROXY_SEND_PATH : "",
+		proxyCollectUrl: enabled ? UMAMI_PROXY_COLLECT_PATH : "",
+		proxyRecordUrl: enabled ? UMAMI_PROXY_RECORD_PATH : "",
+	};
+}
 
+export function getUmamiCspOrigins() {
+	// Proxy mode is the default path when analytics is enabled: tracker and
+	// beacons are same-origin, so CSP stays `'self'`-only and never names
+	// the upstream analytics host.
 	return {
-		scriptSrc: [config.origin],
-		connectSrc: [config.origin],
+		scriptSrc: [],
+		connectSrc: [],
 	};
 }

package/templates/base-project/apps/web/src/lib/analytics/umami-csp.js

@@ -2,8 +2,9 @@ import { getUmamiCspOrigins } from "./umami-config.js";
 
 export function buildContentSecurityPolicy(env = process.env) {
 	const isProduction = env.NODE_ENV === "production";
+	// Same-origin proxy: analytics needs no allowlist entries beyond 'self'.
 	const { connectSrc: umamiConnectSrc, scriptSrc: umamiScriptSrc } =
-		getUmamiCspOrigins(env);
+		getUmamiCspOrigins();
 
 	const scriptSrc = [
 		"script-src",

package/templates/base-project/apps/web/src/lib/analytics/umami-replay.js

@@ -1,5 +1,9 @@
 import { createLogger } from "@usequark/quark-core/logger";
-import { getUmamiConfig, normalizeUmamiUrl } from "./umami-config.js";
+import {
+	getUmamiClientConfig,
+	normalizeUmamiUrl,
+	readPublicEnv,
+} from "./umami-config.js";
 
 const log = createLogger("umami-replay");
 
@@ -18,6 +22,12 @@ export const UMAMI_REPLAY_DEFAULTS = Object.freeze({
 	blockSelector: "[data-umami-block]",
 });
 
+// Max serialized bytes per replay POST. Stays under the first-party proxy's
+// 1 MB cap with headroom for headers and JSON overhead, so a large DOM
+// snapshot cannot turn into a 413-restore-retry loop that grows the buffer
+// forever (each 413 restores the whole batch alongside new events).
+export const MAX_REPLAY_REQUEST_BYTES = 900_000;
+
 export function shouldSampleReplay(
 	randomValue = Math.random(),
 	sampleRate = UMAMI_REPLAY_DEFAULTS.sampleRate,
@@ -67,9 +77,17 @@ export function createReplayBuffer() {
 	};
 }
 
-export function buildReplayEndpoint(env = process.env) {
-	const url =
-		typeof env === "string" ? normalizeUmamiUrl(env) : getUmamiConfig(env).url;
+export function buildReplayEndpoint(env = readPublicEnv()) {
+	// First-party ingest is the default: replay batches POST same-origin so
+	// blocklists never see the upstream analytics host.
+	if (typeof env !== "string") {
+		const config = getUmamiClientConfig(env);
+		return config.enabled ? config.proxyRecordUrl : "";
+	}
+
+	// Explicit upstream URL string (legacy direct mode, e.g. server-side
+	// callers that already resolved the upstream base).
+	const url = normalizeUmamiUrl(env);
 
 	return url ? `${url}/api/record` : "";
 }
@@ -144,28 +162,22 @@ export function buildReplayBody({ websiteId, events, timestamp }) {
 	});
 }
 
-export async function postReplayBatch({
+function replayBodyBytes(body) {
+	if (typeof TextEncoder !== "undefined") {
+		return new TextEncoder().encode(body).length;
+	}
+	return body.length;
+}
+
+async function postReplayChunk({
 	endpoint,
-	cache,
+	sessionCache,
 	websiteId,
 	events,
-	timestamp = Math.floor(Date.now() / 1000),
-	useKeepalive = false,
-	getUmami = () => globalThis.window?.umami,
-	fetchImpl = globalThis.fetch?.bind(globalThis),
-} = {}) {
-	const sessionCache = resolveUmamiSessionCache({ cache, getUmami });
-
-	if (
-		!endpoint ||
-		!sessionCache ||
-		!websiteId ||
-		!events?.length ||
-		!fetchImpl
-	) {
-		return false;
-	}
-
+	timestamp,
+	useKeepalive,
+	fetchImpl,
+}) {
 	const body = buildReplayBody({ websiteId, events, timestamp });
 	const keepalive = useKeepalive && body.length < 60000;
 
@@ -181,11 +193,24 @@ export async function postReplayBatch({
 			credentials: "omit",
 		});
 
-		if (!response?.ok) return false;
+		if (!response) return "retry";
+
+		// A 413 means the bytes exceed the proxy's cap. Multi-event chunks
+		// split and retry halves; a single event that 413s can never be
+		// delivered, so drop it with a warning instead of restoring it into
+		// an infinite retry loop.
+		if (response.status === 413) {
+			if (events.length > 1) return "split";
+			log.warn("dropping replay event rejected as oversized (413)");
+			return "drop";
+		}
+
+		if (!response.ok) return "retry";
 
 		// Umami answers 200 with { ok: false, reason } when replay is disabled
-		// server-side. Treat that as a failure so events are restored instead
-		// of silently dropped.
+		// server-side — and the first-party proxy answers 202 with
+		// { ok: false } when the upstream is unavailable. Treat both as a
+		// failure so events are restored instead of silently dropped.
 		const responseBody =
 			typeof response.json === "function"
 				? await response.json().catch(() => null)
@@ -194,11 +219,130 @@ export async function postReplayBatch({
 			log.warn(
 				`batch rejected by server: ${responseBody.reason ?? "unknown reason"}`,
 			);
-			return false;
+			return "retry";
 		}
 
-		return true;
+		return "sent";
 	} catch {
+		return "retry";
+	}
+}
+
+async function postReplayChunks({
+	endpoint,
+	sessionCache,
+	websiteId,
+	events,
+	timestamp,
+	useKeepalive,
+	fetchImpl,
+}) {
+	if (!events.length) return true;
+
+	const probe = buildReplayBody({ websiteId, events, timestamp });
+	if (replayBodyBytes(probe) <= MAX_REPLAY_REQUEST_BYTES) {
+		const outcome = await postReplayChunk({
+			endpoint,
+			sessionCache,
+			websiteId,
+			events,
+			timestamp,
+			useKeepalive,
+			fetchImpl,
+		});
+		if (outcome === "sent" || outcome === "drop") return true;
+		if (outcome === "split") {
+			const mid = Math.max(1, Math.ceil(events.length / 2));
+			return (
+				(await postReplayChunks({
+					endpoint,
+					sessionCache,
+					websiteId,
+					events: events.slice(0, mid),
+					timestamp,
+					useKeepalive,
+					fetchImpl,
+				})) &&
+				(await postReplayChunks({
+					endpoint,
+					sessionCache,
+					websiteId,
+					events: events.slice(mid),
+					timestamp,
+					useKeepalive,
+					fetchImpl,
+				}))
+			);
+		}
+		return false;
+	}
+
+	// Oversized batch: split before sending. A single event that alone
+	// exceeds the cap can never be delivered, so drop it with a warning
+	// instead of restoring it into an infinite 413 loop.
+	if (events.length === 1) {
+		log.warn(
+			`dropping oversized replay event (${replayBodyBytes(probe)} bytes exceeds cap)`,
+		);
+		return true;
+	}
+
+	const mid = Math.max(1, Math.ceil(events.length / 2));
+	// Sequential halves: on partial failure the caller restores the whole
+	// batch, so an already-sent half may duplicate on retry. Accepted as
+	// rare best-effort duplication (upstream outage mid-oversized-batch);
+	// the alternative is silent loss.
+	return (
+		(await postReplayChunks({
+			endpoint,
+			sessionCache,
+			websiteId,
+			events: events.slice(0, mid),
+			timestamp,
+			useKeepalive,
+			fetchImpl,
+		})) &&
+		(await postReplayChunks({
+			endpoint,
+			sessionCache,
+			websiteId,
+			events: events.slice(mid),
+			timestamp,
+			useKeepalive,
+			fetchImpl,
+		}))
+	);
+}
+
+export async function postReplayBatch({
+	endpoint,
+	cache,
+	websiteId,
+	events,
+	timestamp = Math.floor(Date.now() / 1000),
+	useKeepalive = false,
+	getUmami = () => globalThis.window?.umami,
+	fetchImpl = globalThis.fetch?.bind(globalThis),
+} = {}) {
+	const sessionCache = resolveUmamiSessionCache({ cache, getUmami });
+
+	if (
+		!endpoint ||
+		!sessionCache ||
+		!websiteId ||
+		!events?.length ||
+		!fetchImpl
+	) {
 		return false;
 	}
+
+	return postReplayChunks({
+		endpoint,
+		sessionCache,
+		websiteId,
+		events,
+		timestamp,
+		useKeepalive,
+		fetchImpl,
+	});
 }

package/templates/base-project/apps/web/src/lib/analytics/umami-web-vitals.js

@@ -9,7 +9,9 @@
  * Privacy guarantees:
  *  - Zero user data: no email, name, ID, token, or cookie values.
  *  - Layout timings only: metric name, numeric value, rating string,
- *    and a sanitised URL path (origin stripped, never full URL with query).
+ *    a sanitised URL path (origin stripped, never full URL with query),
+ *    and the bare hostname (as the stock tracker sends; keeps these rows
+ *    out of the NULL-hostname group in Umami's sessions list).
  *  - No referrer, no user-agent, no IP collected by this script.
  *  - Uses sendBeacon for reliable delivery without blocking the page.
  *
@@ -18,11 +20,12 @@
  *  (e.g. a "use client" wrapper in the root layout).
  *
  * Environment:
- *  Controlled by NEXT_PUBLIC_UMAMI_URL and NEXT_PUBLIC_UMAMI_WEBSITE_ID.
+ *  Controlled by NEXT_PUBLIC_UMAMI_WEBSITE_ID (first-party proxy paths are
+ *  static, so no upstream URL is needed in the browser).
  *  When Umami analytics is not configured, the observer is a no-op.
  */
 
-import { getUmamiConfig } from "./umami-config.js";
+import { getUmamiClientConfig } from "./umami-config.js";
 
 // ── Initialization guard ──────────────────────────────────────
 
@@ -56,40 +59,54 @@ function sanitiseUrl(url) {
 }
 
 /**
- * Dispatches a single CWV observation to the Umami collect endpoint
- * as a custom event (event_type = 2).  The payload is fully anonymous.
+ * Dispatches a single CWV observation to Umami's send endpoint as a custom
+ * event (`name: "cwv"`, metrics in `data`). The payload is fully anonymous.
+ *
+ * Shape matters: Umami derives the event type server-side (`name` present →
+ * custom event) and persists `payload.name`/`payload.data` — `event_name`,
+ * `event_type`, and `event_data` keys are ignored, and posting anywhere
+ * other than `/api/send` (there is no `/api/collect` in Umami v2+) silently
+ * drops the beacon while recording nothing. Both mistakes shipped here
+ * before and were caught by reading Umami's send route, not by any test.
+ *
+ * Exported for tests: the browser-only shape (window/navigator) cannot be
+ * covered by observation in unit tests.
  *
  * @param {{ name: string, value: number, rating: string, navigationType?: string }} metric
  */
-function dispatchMetric(metric) {
-	const config = getUmamiConfig();
+export function dispatchMetric(metric) {
+	const config = getUmamiClientConfig();
 	if (!config.enabled) return;
 
 	const payload = {
 		type: "event",
 		payload: {
 			website: config.websiteId,
-			event_name: "cwv",
-			event_type: 2, // custom event
-			url: sanitiseUrl(window.location.href),
-			event_data: {
+			name: "cwv",
+			data: {
 				metric_name: metric.name,
 				metric_value: Math.round(metric.value * 1000) / 1000, // round to 3dp
 				metric_rating: metric.rating,
 				navigation_type: metric.navigationType || "navigate",
 			},
+			url: sanitiseUrl(window.location.href),
+			hostname: window.location.hostname,
 		},
 	};
 
 	const body = JSON.stringify(payload);
 
+	// First-party ingest: same-origin POSTs survive blocklists that match the
+	// upstream analytics host as third-party.
+	const endpoint = config.proxySendUrl || `${config.url}/api/send`;
+
 	// Use sendBeacon for reliability during page lifecycle transitions.
 	if (navigator.sendBeacon) {
 		const blob = new Blob([body], { type: "application/json" });
-		navigator.sendBeacon(`${config.url}/api/collect`, blob);
+		navigator.sendBeacon(endpoint, blob);
 	} else {
 		// Fallback to fetch with keepalive.
-		fetch(`${config.url}/api/collect`, {
+		fetch(endpoint, {
 			method: "POST",
 			body,
 			keepalive: true,

package/templates/base-project/apps/web/src/lib/analytics/umami.js

@@ -1,4 +1,4 @@
-import { getUmamiConfig } from "./umami-config.js";
+import { getUmamiClientConfig, readPublicEnv } from "./umami-config.js";
 
 /**
  * Read the Umami user role cookie set by the admin layout.
@@ -18,12 +18,15 @@ export function isUmamiStaff() {
 
 function getUmamiClient() {
 	if (typeof window === "undefined") return null;
-	if (!getUmamiConfig().enabled) return null;
+	// Client config deliberately: the server-only upstream URL is invisible
+	// here, so gating on getUmamiConfig would wrongly disable track() and
+	// identify() in server-only-upstream deployments.
+	if (!getUmamiClientConfig().enabled) return null;
 	return window.umami ?? null;
 }
 
-export function isUmamiEnabled(env = process.env) {
-	return getUmamiConfig(env).enabled;
+export function isUmamiEnabled(env = readPublicEnv()) {
+	return getUmamiClientConfig(env).enabled;
 }
 
 export function track(name, data) {

package/templates/base-project/apps/web/src/lib/proxy-auth.js

@@ -107,3 +107,66 @@ export function getRateLimitBucket(pathname, method = "GET") {
 export function isRateLimitExempt(pathname) {
 	return RATE_LIMIT_EXEMPT_ROUTES.has(pathname);
 }
+
+/**
+ * Boolean-like values that disable trusting proxy headers. Mirrors the
+ * "explicit false wins" convention used by `AUTH_ALLOW_SIGNUP` and
+ * `DB_INSTRUMENTATION`, so operators don't have to learn a new dialect.
+ */
+const PROXY_HEADERS_FALSY_VALUES = new Set(["false", "0", "no", "off"]);
+
+/**
+ * Whether the client-supplied proxy headers (`x-forwarded-for`, `x-real-ip`)
+ * may be trusted to identify the client.
+ *
+ * Default `true`: the shipped behaviour. The app assumes it sits behind a
+ * reverse proxy (Railway, Docker, nginx) that overwrites these headers on
+ * every request, so the left-most `x-forwarded-for` entry is treated as the
+ * client IP.
+ *
+ * Set `TRUST_PROXY_HEADERS=false` when the app is reachable directly (no
+ * proxy rewriting the header on the way in). Callers must then ignore both
+ * headers: proxy.js keys every client on the literal "unknown", and the
+ * Umami ingest proxy forwards "unknown" instead of attacker bytes. A header
+ * a client can set is not an identity.
+ *
+ * Read lazily (per request) rather than at module load: tests flip it and a
+ * value set after import still takes effect. Only explicit false-like values
+ * disable trusting; unset, empty, "true", or a typo all keep the default.
+ *
+ * @returns {boolean}
+ */
+export function shouldTrustProxyHeaders() {
+	const raw = process.env.TRUST_PROXY_HEADERS?.trim().toLowerCase();
+	return !(raw && PROXY_HEADERS_FALSY_VALUES.has(raw));
+}
+
+/**
+ * Boolean-like values that opt into trusting `CF-Connecting-IP`. Deliberately
+ * the mirror of the proxy-headers convention: "explicit true wins", default
+ * off. `CF-Connecting-IP` is only overwritten by Cloudflare itself — unlike
+ * `X-Forwarded-For`, most proxies (Railway, nginx, Docker) pass it through
+ * untouched. Trusting it unconditionally would let any client override an
+ * otherwise-legitimate `X-Forwarded-For` with an arbitrary IP, so it stays
+ * ignored unless the operator confirms Cloudflare is in the path.
+ */
+const CF_CONNECTING_IP_TRUTHY_VALUES = new Set(["true", "1", "yes", "on"]);
+
+/**
+ * Whether `CF-Connecting-IP` may identify the client in the Umami ingest
+ * proxy (resolution preference and upstream passthrough).
+ *
+ * Default `false`: the header is ignored entirely. Set
+ * `TRUST_CF_CONNECTING_IP=true` only when Cloudflare sits in front of the
+ * app (it overwrites the header with the true client IP on every request).
+ * Independently of this flag, `TRUST_PROXY_HEADERS=false` still forces
+ * `"unknown"` — distrust always wins over trust.
+ *
+ * Read lazily (per request) like `shouldTrustProxyHeaders`.
+ *
+ * @returns {boolean}
+ */
+export function shouldTrustCfConnectingIp() {
+	const raw = process.env.TRUST_CF_CONNECTING_IP?.trim().toLowerCase();
+	return !!raw && CF_CONNECTING_IP_TRUTHY_VALUES.has(raw);
+}

package/templates/base-project/apps/web/src/proxy.js

@@ -14,7 +14,16 @@ import { createLogger, createRateLimiter } from "@usequark/quark-core/core";
 import { NextResponse } from "next/server";
 
 import { buildContentSecurityPolicy } from "./lib/analytics/umami-csp.js";
-import { getRateLimitBucket, isRateLimitExempt } from "./lib/proxy-auth";
+import {
+	getRateLimitBucket,
+	isRateLimitExempt,
+	shouldTrustProxyHeaders,
+} from "./lib/proxy-auth";
+
+// Re-exported: proxy.test.js and external callers resolve it from here.
+// The definition lives in lib/proxy-auth.js, shared with the Umami ingest
+// proxy so both honor TRUST_PROXY_HEADERS identically.
+export { shouldTrustProxyHeaders };
 
 const logger = createLogger("proxy");
 
@@ -93,43 +102,6 @@ export async function getRateLimiter() {
 	return rateLimiterPromise;
 }
 
-/**
- * Boolean-like values that disable trusting proxy headers. Mirrors the
- * "explicit false wins" convention used by `AUTH_ALLOW_SIGNUP` and
- * `DB_INSTRUMENTATION`, so operators don't have to learn a new dialect.
- */
-const PROXY_HEADERS_FALSY_VALUES = new Set(["false", "0", "no", "off"]);
-
-/**
- * Whether the client-supplied proxy headers (`x-forwarded-for`, `x-real-ip`)
- * may be trusted to identify the client.
- *
- * Default `true`: the shipped behaviour. The app assumes it sits behind a
- * reverse proxy (Railway, Docker, nginx) that overwrites these headers on
- * every request, so the left-most `x-forwarded-for` entry is treated as the
- * client IP.
- *
- * Set `TRUST_PROXY_HEADERS=false` when the app is reachable directly (no
- * proxy rewriting the header on the way in). The headers are then ignored and
- * every client keys on the literal "unknown". Because the bucket key is
- * `${ip}:${path}`, that means one bucket shared by every client of a route —
- * not one bucket across all routes. A header a client can set is not an
- * identity, so this is what stops a spoofed `x-forwarded-for` from buying a
- * fresh bucket per request. The trade-off is the reverse of the default: one
- * client can now exhaust the shared bucket for the route it floods, which is
- * why the default keeps trusting the headers.
- *
- * Read lazily (per request) rather than at module load: tests flip it and a
- * value set after import still takes effect. Only explicit false-like values
- * disable trusting; unset, empty, "true", or a typo all keep the default.
- *
- * @returns {boolean}
- */
-export function shouldTrustProxyHeaders() {
-	const raw = process.env.TRUST_PROXY_HEADERS?.trim().toLowerCase();
-	return !(raw && PROXY_HEADERS_FALSY_VALUES.has(raw));
-}
-
 /**
  * Resolve the client IP for rate-limit keying.
  *