🐸 Rybbit - open-source and privacy-friendly alternative to Google Analytics that is 10x more intuitive.
Enhance proxy guide and troubleshooting documentation for IP forwarding
Bill Yang08a3e2045c9e
diff --git a/docs/content/docs/proxy-guide/get-started.mdx b/docs/content/docs/proxy-guide/get-started.mdxindex 1232f8ca6..d317f3528 100644--- a/docs/content/docs/proxy-guide/get-started.mdx+++ b/docs/content/docs/proxy-guide/get-started.mdx@@ -85,6 +85,7 @@ Your domain path → Rybbit backend- Forward necessary headers (User-Agent, X-Forwarded-For, Referer)- Maintain request/response body for POST requests- Set appropriate Content-Type headers+- For CDN or edge proxies, forward the visitor IP in `X-Forwarded-For` or `X-Real-IP`### Configure Caching (Optional but Recommended)@@ -176,6 +177,25 @@ For accurate tracking, ensure these headers are forwarded to the Rybbit backend:**IP Forwarding**: Rybbit uses IP addresses for geolocation (country/city) and creating anonymous user identifiers (hashed IP + User Agent). If you don't forward the `X-Forwarded-For` or `X-Real-IP` header, all traffic will appear to come from your proxy server's IP.</Callout>+### Forwarded IP Headers++If your proxy runs on infrastructure such as Cloudflare Workers, AWS CloudFront, Fastly, or another edge/CDN provider, make sure the proxy sets `X-Forwarded-For` or `X-Real-IP` to the original visitor IP. Rybbit reads these headers before the connecting edge IP, so this prevents traffic from being geolocated to the proxy or classified by the proxy's ASN.++**Cloudflare Worker example:**++```javascript+const clientIp = request.headers.get('CF-Connecting-IP') || '0.0.0.0';++const proxyHeaders = new Headers(request.headers);+proxyHeaders.set('X-Real-IP', clientIp);+proxyHeaders.set('X-Forwarded-For', clientIp);+```++**CloudFront example:**++- Forward `X-Forwarded-For`, or set `X-Real-IP` to the viewer IP from a CloudFront Function/Lambda@Edge+- Forward `User-Agent`, `Referer`, and `Accept-Language`+## Bandwidth ConsiderationsProxying adds bandwidth usage to your infrastructure. Here's what to expect:@@ -291,7 +311,7 @@ If something isn't working, check:1. **Script loads but no events tracked**: Verify all tracking endpoints (`/api/track`, etc.) are proxied2. **CORS errors**: Ensure CORS headers are preserved from Rybbit backend3. **404 errors**: Check that URL paths exactly match expected format-4. **Incorrect geolocation**: Verify `X-Forwarded-For` header is forwarded+4. **Incorrect geolocation**: Verify `X-Forwarded-For` or `X-Real-IP` is set to the visitor IP5. **Session replay not working**: Add `/api/replay.js` and `/api/session-replay/record/:siteId` endpointsFor more detailed troubleshooting, see our [troubleshooting guide](/docs/proxy-guide/troubleshooting).diff --git a/docs/content/docs/proxy-guide/troubleshooting.mdx b/docs/content/docs/proxy-guide/troubleshooting.mdxindex a9ed5cb8b..e9eb46faf 100644--- a/docs/content/docs/proxy-guide/troubleshooting.mdx+++ b/docs/content/docs/proxy-guide/troubleshooting.mdx@@ -214,6 +214,36 @@ proxyHeaders.set('X-Real-IP', clientIp);---+### Proxied Requests Are Detected as Bots++**Symptoms:**+- `/analytics/track` returns `200 OK`+- Events do not appear in the normal analytics dashboard+- Bot logs or older responses say the event was not tracked because a bot was detected+- The bot reason mentions `bot asn`+- Geolocation points to your CDN or proxy region, such as a Cloudflare Worker or AWS CloudFront edge location++**Cause:** Rybbit is seeing the proxy IP instead of the original visitor IP. This is common when a first-party proxy is hosted on CDN or cloud infrastructure. Those networks use hosting/datacenter ASNs, so traffic can look like bot infrastructure if the visitor IP is not passed in a trusted way.++Set `X-Forwarded-For` or `X-Real-IP` to the original visitor IP before forwarding the request to Rybbit. Rybbit reads those headers before the connecting edge IP.++**Cloudflare Workers:**++```javascript+const clientIp = request.headers.get('CF-Connecting-IP') || '0.0.0.0';++const proxyHeaders = new Headers(request.headers);+proxyHeaders.set('X-Real-IP', clientIp);+proxyHeaders.set('X-Forwarded-For', clientIp);+```++**AWS CloudFront:**++- Forward `X-Forwarded-For`, or set `X-Real-IP` to the viewer IP from a CloudFront Function/Lambda@Edge+- Forward `User-Agent`, `Referer`, and `Accept-Language`++---+## Session Replay Issues### Session Replay Not Workingdiff --git a/server/src/lib/auth-utils.ts b/server/src/lib/auth-utils.tsindex 053fd2e47..a54b5b67a 100644--- a/server/src/lib/auth-utils.ts+++ b/server/src/lib/auth-utils.ts@@ -236,15 +236,13 @@ export async function checkApiKey(options: { organizationId?: string; siteId?: string | number }): Promise<{ valid: boolean; role: string | null; rateLimited?: boolean }> {// Check if a valid API key was provided- // Priority: 1. Authorization: Bearer header, 2. X-Rybbit-Api-Key origin/proxy header, 3. Query parameter (testing only)+ // Priority: 1. Authorization: Bearer header (recommended), 2. Query parameter (testing only)const authHeader = req.headers["authorization"];const bearerToken =authHeader && typeof authHeader === "string" && authHeader.startsWith("Bearer ") ? authHeader.substring(7) : null;- const proxyApiKeyHeader = req.headers["x-rybbit-api-key"];- const proxyApiKey = typeof proxyApiKeyHeader === "string" ? proxyApiKeyHeader : null;const queryApiKey = (req.query as any)?.api_key;- const apiKey = bearerToken || proxyApiKey || queryApiKey;+ const apiKey = bearerToken || queryApiKey;if (apiKey && typeof apiKey === "string") {try {diff --git a/server/src/services/tracker/botBlocking/README.md b/server/src/services/tracker/botBlocking/README.mdindex 108d28f2d..19e528a9f 100644--- a/server/src/services/tracker/botBlocking/README.md+++ b/server/src/services/tracker/botBlocking/README.md@@ -100,8 +100,6 @@ This catches obvious floods and fast crawlers, but it is local to a Node process## Trust Boundaries-Bot blocking assumes the resolved IP is trustworthy. In production, the origin should only accept traffic from trusted proxy infrastructure, or the edge should strip and rebuild forwarding headers. Public tracking requests ignore client-supplied `ip_address` and `user_agent`; those overrides are only honored for trusted server-side ingestion.--First-party customer proxies can pass the real visitor IP without disabling bot blocking by sending `X-Rybbit-Proxy: 1` plus a valid API key from the proxy to Rybbit. The API key can be sent as `Authorization: Bearer <api key>` or as the origin-only `X-Rybbit-Api-Key` header. In that mode the tracker trusts proxy-provided IP headers for IP resolution only, preferring `X-Rybbit-Client-IP`, then `True-Client-IP`, `CloudFront-Viewer-Address`, `X-Real-IP`, `X-Forwarded-For`, and `Forwarded`. It still uses the request user-agent header and still runs every bot detection layer.+Bot blocking assumes the resolved IP is meaningful. The tracker resolves IPs from `X-Forwarded-For`, then `X-Real-IP`, then `CF-Connecting-IP`, then the Fastify request IP. Public tracking requests ignore client-supplied `ip_address` and `user_agent`; those overrides are only honored for trusted server-side ingestion.Client-supplied `_bs` and `_bsm` are useful inputs but are not secure proof.diff --git a/server/src/services/tracker/requestIdentity.test.ts b/server/src/services/tracker/requestIdentity.test.tsindex a923f0ec2..8a3a43d03 100644--- a/server/src/services/tracker/requestIdentity.test.ts+++ b/server/src/services/tracker/requestIdentity.test.ts@@ -20,7 +20,7 @@ describe("resolveTrackingIdentity", () => {ip_address: "203.0.113.10",user_agent: "SpoofedBot/1.0",},- {}+ false)).toEqual({ipAddress: "198.51.100.20",@@ -41,71 +41,11 @@ describe("resolveTrackingIdentity", () => {ip_address: "203.0.113.10",user_agent: "Mozilla/5.0 Chrome/120 Safari/537.36",},- { trustedServerSideIngestion: true }+ true)).toEqual({ipAddress: "203.0.113.10",userAgent: "Mozilla/5.0 Chrome/120 Safari/537.36",});});-- it("uses verified first-party proxy IP headers without trusting payload overrides", () => {- const request = requestWithHeaders({- "cf-connecting-ip": "198.51.100.20",- "user-agent": "Mozilla/5.0 Chrome/120 Safari/537.36",- "x-rybbit-client-ip": "203.0.113.10",- });-- expect(- resolveTrackingIdentity(- request,- {- ip_address: "192.0.2.10",- user_agent: "SpoofedBot/1.0",- },- { trustedFirstPartyProxy: true }- )- ).toEqual({- ipAddress: "203.0.113.10",- userAgent: "Mozilla/5.0 Chrome/120 Safari/537.36",- });- });-- it("does not trust first-party proxy IP headers without trusted proxy mode", () => {- const request = requestWithHeaders({- "cf-connecting-ip": "198.51.100.20",- "user-agent": "Mozilla/5.0 Chrome/120 Safari/537.36",- "x-rybbit-client-ip": "203.0.113.10",- });-- expect(resolveTrackingIdentity(request, {}, {})).toEqual({- ipAddress: "198.51.100.20",- userAgent: "Mozilla/5.0 Chrome/120 Safari/537.36",- });- });-- it("parses CloudFront viewer addresses with ports for trusted proxy mode", () => {- const request = requestWithHeaders({- "cloudfront-viewer-address": "203.0.113.20:443",- "user-agent": "Mozilla/5.0 Chrome/120 Safari/537.36",- });-- expect(resolveTrackingIdentity(request, {}, { trustedFirstPartyProxy: true })).toEqual({- ipAddress: "203.0.113.20",- userAgent: "Mozilla/5.0 Chrome/120 Safari/537.36",- });- });-- it("falls back to the normal request IP when trusted proxy headers are invalid", () => {- const request = requestWithHeaders({- "cf-connecting-ip": "198.51.100.20",- "user-agent": "Mozilla/5.0 Chrome/120 Safari/537.36",- "x-rybbit-client-ip": "not-an-ip",- });-- expect(resolveTrackingIdentity(request, {}, { trustedFirstPartyProxy: true })).toEqual({- ipAddress: "198.51.100.20",- userAgent: "Mozilla/5.0 Chrome/120 Safari/537.36",- });- });});diff --git a/server/src/services/tracker/requestIdentity.ts b/server/src/services/tracker/requestIdentity.tsindex 231db6a08..c43d9f5b3 100644--- a/server/src/services/tracker/requestIdentity.ts+++ b/server/src/services/tracker/requestIdentity.ts@@ -1,5 +1,4 @@import { FastifyRequest } from "fastify";-import { isIP } from "node:net";import { getIpAddress } from "../../utils.js";interface TrackingIdentityPayload {@@ -7,97 +6,11 @@ interface TrackingIdentityPayload {user_agent?: string;}-export interface TrackingIdentityOptions {- trustedServerSideIngestion?: boolean;- trustedFirstPartyProxy?: boolean;-}-interface TrackingIdentity {ipAddress: string;userAgent: string;}-function firstHeaderValue(value: string | string[] | undefined): string | null {- if (Array.isArray(value)) {- return value[0] || null;- }- return value || null;-}--function normalizeIpCandidate(value: string): string | null {- const candidate = value.trim().replace(/^"|"$/g, "");- if (!candidate) {- return null;- }-- const bracketedIpv6 = candidate.match(/^\[([^\]]+)](?::\d+)?$/);- if (bracketedIpv6 && isIP(bracketedIpv6[1])) {- return bracketedIpv6[1];- }-- if (isIP(candidate)) {- return candidate;- }-- const ipv4WithPort = candidate.match(/^(\d{1,3}(?:\.\d{1,3}){3})(?::\d+)?$/);- if (ipv4WithPort && isIP(ipv4WithPort[1])) {- return ipv4WithPort[1];- }-- return null;-}--function firstIpFromList(value: string | null): string | null {- if (!value) {- return null;- }-- for (const part of value.split(",")) {- const ip = normalizeIpCandidate(part);- if (ip) {- return ip;- }- }-- return null;-}--function firstIpFromForwardedHeader(value: string | null): string | null {- if (!value) {- return null;- }-- for (const forwardedEntry of value.split(",")) {- for (const param of forwardedEntry.split(";")) {- const [key, rawValue] = param.split("=");- if (key?.trim().toLowerCase() !== "for" || !rawValue) {- continue;- }-- const ip = normalizeIpCandidate(rawValue);- if (ip) {- return ip;- }- }- }-- return null;-}--function getTrustedFirstPartyProxyIpAddress(request: FastifyRequest): string | null {- const headers = request.headers;-- return (- normalizeIpCandidate(firstHeaderValue(headers["x-rybbit-client-ip"]) ?? "") ||- normalizeIpCandidate(firstHeaderValue(headers["true-client-ip"]) ?? "") ||- normalizeIpCandidate(firstHeaderValue(headers["cloudfront-viewer-address"]) ?? "") ||- normalizeIpCandidate(firstHeaderValue(headers["x-real-ip"]) ?? "") ||- firstIpFromList(firstHeaderValue(headers["x-forwarded-for"])) ||- firstIpFromForwardedHeader(firstHeaderValue(headers.forwarded)) ||- null- );-}-export function getRequestUserAgent(request: FastifyRequest): string {const userAgentHeader = request.headers["user-agent"];if (Array.isArray(userAgentHeader)) {@@ -109,17 +22,13 @@ export function getRequestUserAgent(request: FastifyRequest): string {export function resolveTrackingIdentity(request: FastifyRequest,payload: TrackingIdentityPayload,- options: TrackingIdentityOptions = {}+ trustedServerSideIngestion: boolean): TrackingIdentity {- const { trustedServerSideIngestion = false, trustedFirstPartyProxy = false } = options;const requestIpAddress = getIpAddress(request);const requestUserAgent = getRequestUserAgent(request);- const trustedProxyIpAddress = trustedFirstPartyProxy ? getTrustedFirstPartyProxyIpAddress(request) : null;return {- ipAddress: trustedServerSideIngestion- ? payload.ip_address || requestIpAddress- : trustedProxyIpAddress || requestIpAddress,+ ipAddress: trustedServerSideIngestion ? payload.ip_address || requestIpAddress : requestIpAddress,userAgent: trustedServerSideIngestion ? payload.user_agent || requestUserAgent : requestUserAgent,};}diff --git a/server/src/services/tracker/trackEvent.ts b/server/src/services/tracker/trackEvent.tsindex c56ccf181..14113c0ba 100644--- a/server/src/services/tracker/trackEvent.ts+++ b/server/src/services/tracker/trackEvent.ts@@ -246,26 +246,7 @@ export const trackingPayloadSchema = z.discriminatedUnion("type", [const logger = createServiceLogger("track-event");-function isFirstPartyProxyRequest(request: FastifyRequest): boolean {- const proxyHeader = request.headers["x-rybbit-proxy"];- const value = Array.isArray(proxyHeader) ? proxyHeader[0] : proxyHeader;- return value === "1" || value?.toLowerCase() === "true";-}--async function isTrustedFirstPartyProxy(request: FastifyRequest, siteId: number): Promise<boolean> {- if (!isFirstPartyProxyRequest(request)) {- return false;- }-- const apiKeyResult = await checkApiKey(request, { siteId });- return apiKeyResult.valid;-}-async function isTrustedServerSideIngestion(request: FastifyRequest, siteId: number): Promise<boolean> {- if (isFirstPartyProxyRequest(request)) {- return false;- }-const authHeader = request.headers["authorization"];if (typeof authHeader !== "string" || !authHeader.startsWith("Bearer ")) {return false;@@ -302,14 +283,8 @@ export async function trackEvent(request: FastifyRequest, reply: FastifyReply) {});}- const trustedFirstPartyProxy = await isTrustedFirstPartyProxy(request, siteConfiguration.siteId);- const trustedServerSideIngestion = trustedFirstPartyProxy- ? false- : await isTrustedServerSideIngestion(request, siteConfiguration.siteId);- const trackingIdentity = resolveTrackingIdentity(request, validatedPayload, {- trustedServerSideIngestion,- trustedFirstPartyProxy,- });+ const trustedServerSideIngestion = await isTrustedServerSideIngestion(request, siteConfiguration.siteId);+ const trackingIdentity = resolveTrackingIdentity(request, validatedPayload, trustedServerSideIngestion);const requestIP = trackingIdentity.ipAddress;const botDetectionResult = checkBotBlocking({@@ -374,10 +349,7 @@ export async function trackEvent(request: FastifyRequest, reply: FastifyReply) {validatedPayload.type,validatedPayload, // Pass original validated payloadsiteConfiguration,- {- trustedServerSideIngestion,- trustedFirstPartyProxy,- }+ trustedServerSideIngestion);// Update session (use numeric siteId)diff --git a/server/src/services/tracker/utils.ts b/server/src/services/tracker/utils.tsindex b0f0cc4b4..b480fbdfd 100644--- a/server/src/services/tracker/utils.ts+++ b/server/src/services/tracker/utils.ts@@ -5,7 +5,7 @@ import { userIdService } from "../userId/userIdService.js";import { trackingPayloadSchema } from "./trackEvent.js";import { TrackingPayload } from "./types.js";import { SiteConfigData } from "../../lib/siteConfig.js";-import { resolveTrackingIdentity, type TrackingIdentityOptions } from "./requestIdentity.js";+import { resolveTrackingIdentity } from "./requestIdentity.js";export type TotalTrackingPayload = TrackingPayload & {userId: string; // Always the device fingerprint@@ -106,9 +106,9 @@ export async function createBasePayload(| "input_change" = "pageview",validatedBody: ValidatedTrackingPayload,siteConfiguration: SiteConfigData,- trackingIdentityOptions: TrackingIdentityOptions = {}+ trustedServerSideIngestion = false): Promise<TotalTrackingPayload> {- const { ipAddress, userAgent } = resolveTrackingIdentity(request, validatedBody, trackingIdentityOptions);+ const { ipAddress, userAgent } = resolveTrackingIdentity(request, validatedBody, trustedServerSideIngestion);const { ip_address: _ipAddressOverride, user_agent: _userAgentOverride, ...payloadBody } = validatedBody;// Always compute anonymous_id based on IP+UserAgent (device fingerprint)diff --git a/server/src/utils.test.ts b/server/src/utils.test.tsindex 249c7a5a0..c6a6190bf 100644--- a/server/src/utils.test.ts+++ b/server/src/utils.test.ts@@ -1,5 +1,36 @@import { describe, it, expect } from "vitest";-import { normalizeOrigin } from "./utils.js";+import { FastifyRequest } from "fastify";+import { getIpAddress, normalizeOrigin } from "./utils.js";++function requestWithHeaders(headers: Record<string, string | string[]>, ip = "198.51.100.10"): FastifyRequest {+ return { headers, ip } as unknown as FastifyRequest;+}++describe("getIpAddress", () => {+ it("uses the first X-Forwarded-For IP before Cloudflare's connecting IP", () => {+ const request = requestWithHeaders({+ "cf-connecting-ip": "198.51.100.20",+ "x-forwarded-for": "203.0.113.10, 198.51.100.20",+ "x-real-ip": "192.0.2.10",+ });++ expect(getIpAddress(request)).toBe("203.0.113.10");+ });++ it("uses X-Real-IP before Cloudflare's connecting IP when X-Forwarded-For is missing", () => {+ const request = requestWithHeaders({+ "cf-connecting-ip": "198.51.100.20",+ "x-real-ip": "203.0.113.10",+ });++ expect(getIpAddress(request)).toBe("203.0.113.10");+ });++ it("falls back to Cloudflare's connecting IP and then the request IP", () => {+ expect(getIpAddress(requestWithHeaders({ "cf-connecting-ip": "198.51.100.20" }))).toBe("198.51.100.20");+ expect(getIpAddress(requestWithHeaders({}))).toBe("198.51.100.10");+ });+});describe("normalizeOrigin", () => {describe("Basic subdomain removal", () => {diff --git a/server/src/utils.ts b/server/src/utils.tsindex 89364d692..5820c005e 100644--- a/server/src/utils.ts+++ b/server/src/utils.ts@@ -239,13 +239,7 @@ export const normalizeOrigin = (input: string): string => {// Helper function to get IP addressexport const getIpAddress = (request: FastifyRequest): string => {- // Priority 1: Cloudflare header (already validated by CF)- const cfConnectingIp = request.headers["cf-connecting-ip"];- if (cfConnectingIp && typeof cfConnectingIp === "string") {- return cfConnectingIp.trim();- }-- // Priority 2: X-Forwarded-For - just use the first IP+ // Priority 1: X-Forwarded-For - use the first IP, which should be the original client.const forwardedFor = request.headers["x-forwarded-for"];if (forwardedFor && typeof forwardedFor === "string") {const ips = forwardedFor@@ -258,5 +252,17 @@ export const getIpAddress = (request: FastifyRequest): string => {}}+ // Priority 2: X-Real-IP+ const realIp = request.headers["x-real-ip"];+ if (realIp && typeof realIp === "string") {+ return realIp.trim();+ }++ // Priority 3: Cloudflare header+ const cfConnectingIp = request.headers["cf-connecting-ip"];+ if (cfConnectingIp && typeof cfConnectingIp === "string") {+ return cfConnectingIp.trim();+ }+return request.ip;};