@usequark/quark-create-app 1.27.2 → 1.27.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usequark/quark-create-app",
-  "version": "1.27.2",
+  "version": "1.27.4",
   "description": "CLI to scaffold new Quark projects with Next.js, Prisma, BullMQ, and Railway deployment",
   "keywords": [
     "quark",

package/templates/base-project/apps/web/.env.example

@@ -118,6 +118,18 @@ ADMIN_PASSWORD=SET_ME
 # cannot earn a fresh bucket. Boolean-like: true/false/1/0/yes/no/on/off.
 # TRUST_PROXY_HEADERS=true
 
+# --- Umami Ingest Proxy & Cloudflare ---
+# The first-party analytics proxy (/s/*) resolves the visitor IP from proxy
+# headers. Unlike x-forwarded-for, CF-Connecting-IP is NOT sanitized by
+# generic proxies (Railway, nginx, Docker pass it through), so trusting it
+# unconditionally would let any client override a legitimate X-Forwarded-For.
+# Default (unset) ignores it. Set to true ONLY when Cloudflare sits in front
+# of the app (it overwrites the header with the true client IP): correct geo
+# and stable Umami sessions behind Cloudflare → Railway. Boolean-like:
+# true/1/yes/on enable; anything else (including unset) disables.
+# Independent of TRUST_PROXY_HEADERS, which still forces "unknown" when false.
+# TRUST_CF_CONNECTING_IP=true
+
 # --- File Storage ---
 # Default: local filesystem (./uploads). No further config needed for development.
 STORAGE_PROVIDER=local

package/templates/base-project/apps/web/src/app/s/api/[endpoint]/route.js

@@ -14,9 +14,16 @@
  * - POST-only — every other method answers 405.
  * - Header hygiene — `cookie`, `authorization`, and `x-metrics-token` are
  *   never forwarded; only the analytics-relevant headers cross the boundary.
- * - `X-Forwarded-For` / `X-Real-IP` are preserved so Umami geolocates the
- *   visitor, not the Railway egress IP — unless TRUST_PROXY_HEADERS=false,
- *   in which case "unknown" crosses instead (same rule as proxy.js).
+ * - `X-Forwarded-For` / `X-Real-IP` carry the single resolved visitor IP so
+ *   Umami geolocates the visitor, not the Railway egress IP — unless
+ *   TRUST_PROXY_HEADERS=false, in which case "unknown" crosses instead (same
+ *   rule as proxy.js). Resolution prefers `CF-Connecting-IP`, but only with
+ *   explicit opt-in (`TRUST_CF_CONNECTING_IP=true`, for Cloudflare-fronted
+ *   deployments): the header takes precedence yet generic proxies pass it
+ *   through unsanitized, so unconditional trust would let any client override
+ *   a legitimate X-Forwarded-For. `CF-Connecting-IP` passthrough follows the
+ *   same opt-in — never when untrusted. Tracker metadata (`x-umami-cache`) is forwarded; `cookie`,
+ *   `authorization`, and `x-metrics-token` never are.
  * - 1 MB body cap enforced while streaming (a missing/lying Content-Length
  *   cannot force full buffering) + 5s upstream timeout bound abuse cost.
  * - `Cache-Control: no-store` on every response; upstream `Set-Cookie` is
@@ -35,7 +42,10 @@
 import { createLogger } from "@usequark/quark-core/core";
 import { NextResponse } from "next/server";
 import { getUmamiUpstreamBase } from "@/lib/analytics/umami-config.js";
-import { shouldTrustProxyHeaders } from "@/lib/proxy-auth.js";
+import {
+	shouldTrustCfConnectingIp,
+	shouldTrustProxyHeaders,
+} from "@/lib/proxy-auth.js";
 
 const logger = createLogger("umami-proxy");
 
@@ -54,8 +64,8 @@ function methodNotAllowed() {
 	);
 }
 
-// Fail-open without losing replay data. Tracker (`send`) and web-vitals
-// (`collect`) beacons are fire-and-forget with no retry path, so they keep
+// Fail-open without losing replay data. Tracker, web-vitals, and legacy
+// `collect` beacons are fire-and-forget with no retry path, so they keep
 // `{ ok: true }` to avoid any client-side retry storm against a struggling
 // upstream. Replay (`record`) has a restore/retry path keyed on
 // `body.ok === false` in postReplayBatch: answering `ok: true` there would
@@ -72,7 +82,26 @@ function failOpenResponse(endpoint) {
 	});
 }
 
-function resolveClientIp(request) {
+function resolveClientIp(request, { trustCfConnectingIp = false } = {}) {
+	// Preference (only when the operator opted in via TRUST_CF_CONNECTING_IP):
+	// Cloudflare overwrites CF-Connecting-IP with the true client IP and
+	// Railway passes it through, while Railway REPLACES X-Forwarded-For with
+	// the Cloudflare edge address. Reading XFF alone therefore misattributes
+	// every visitor behind Cloudflare — wrong geo, and rotating edge IPs
+	// change Umami's hash(IP, UA, site) session identity between requests of
+	// one visit, splitting it into duplicate sessions.
+	//
+	// The opt-in is load-bearing, not bureaucracy: CF-Connecting-IP takes
+	// precedence over X-Forwarded-For, and most proxies pass it through
+	// untouched — so trusting it unconditionally would let any client override
+	// an otherwise-legitimate XFF with an arbitrary IP. Only Cloudflare
+	// itself sanitizes this header, hence explicit opt-in (and
+	// TRUST_PROXY_HEADERS=false still forces "unknown" at the call site).
+	const cloudflareIp = trustCfConnectingIp
+		? request.headers.get("cf-connecting-ip")?.trim()
+		: null;
+	if (cloudflareIp) return cloudflareIp;
+
 	const forwardedFor = request.headers.get("x-forwarded-for");
 	if (forwardedFor) {
 		const client = forwardedFor
@@ -187,23 +216,36 @@ export async function POST(request, { params } = {}) {
 	// TRUST_PROXY_HEADERS=false the app is directly reachable, the headers
 	// are attacker-controlled, and forwarding them would poison Umami geo.
 	// "unknown" (never client bytes) crosses the boundary instead.
+	// CF-Connecting-IP additionally needs TRUST_CF_CONNECTING_IP=true:
+	// unlike XFF it is not sanitized by generic proxies, so trusting it
+	// unconditionally would let a client override a legitimate XFF.
 	const trustProxyHeaders = shouldTrustProxyHeaders();
-	const incomingForwardedFor = trustProxyHeaders
-		? request.headers.get("x-forwarded-for")
-		: null;
-	const clientIp = trustProxyHeaders ? resolveClientIp(request) : "unknown";
-	const forwardedFor = incomingForwardedFor?.trim()
-		? incomingForwardedFor
-		: clientIp;
+	const trustCfConnectingIp = trustProxyHeaders && shouldTrustCfConnectingIp();
+	const clientIp = trustProxyHeaders
+		? resolveClientIp(request, { trustCfConnectingIp })
+		: "unknown";
 
 	const forwardHeaders = {
 		"Content-Type": "application/json",
-		"X-Forwarded-For": forwardedFor,
-		"X-Real-IP": trustProxyHeaders
-			? request.headers.get("x-real-ip")?.trim() || clientIp
-			: clientIp,
+		// Single stable IP, never the incoming chain: Umami hashes
+		// (IP, UA, site) into its session identity, so a rotating edge IP
+		// anywhere in a forwarded chain splits one visit into duplicate
+		// sessions (and geolocates the edge, not the visitor). Chain entries
+		// beyond the client are proxies — no analytics value, only leak.
+		"X-Forwarded-For": clientIp,
+		"X-Real-IP": clientIp,
 	};
 
+	// Umami reads cf-connecting-ip before X-Forwarded-For, and behind
+	// Cloudflare it is the only header carrying the true client IP (Railway
+	// replaces XFF with the edge address). Pass it through — but only under
+	// the same opt-in that allowed it to win resolution above, and never when
+	// untrusted, when it is client-set bytes like every other proxy header.
+	if (trustCfConnectingIp) {
+		const cloudflareIp = request.headers.get("cf-connecting-ip")?.trim();
+		if (cloudflareIp) forwardHeaders["CF-Connecting-IP"] = cloudflareIp;
+	}
+
 	const userAgent = request.headers.get("user-agent");
 	if (userAgent) forwardHeaders["User-Agent"] = userAgent;
 

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

@@ -58,12 +58,16 @@ 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
+// and the 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 = [

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.
  *
@@ -57,12 +59,22 @@ 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) {
+export function dispatchMetric(metric) {
 	const config = getUmamiClientConfig();
 	if (!config.enabled) return;
 
@@ -70,23 +82,26 @@ function dispatchMetric(metric) {
 		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.proxyCollectUrl || `${config.url}/api/collect`;
+	// upstream analytics host as third-party. The client config carries no
+	// upstream URL, so there is no direct-mode fallback — when disabled the
+	// function already returned above.
+	const endpoint = config.proxySendUrl;
+	if (!endpoint) return;
 
 	// Use sendBeacon for reliability during page lifecycle transitions.
 	if (navigator.sendBeacon) {

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

@@ -140,3 +140,33 @@ 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);
+}