fix(attribution): ignore shared/NAT IPs in fingerprint matching + support CDN client-IP header (#26)

Two root-cause fixes for cross-tenant install mis-attribution:

1. Shared-IP filter: calculateConfidenceScore no longer awards the IP score
   when either IP is in a shared/non-routable range (CGNAT 100.64.0.0/10,
   RFC1918, loopback, link-local, IPv6 ULA/link-local). Those IPs don't
   identify a single device, so unrelated users behind the same NAT could
   collide on IP (40pts) + UA (30pts) = the 70 threshold and cross orgs.
   Without the IP score such installs top out at 60 and no longer match.
   New exported isAttributableIp() with tests.

2. getClientIp honors a configurable authoritative client-IP header
   (TRUSTED_CLIENT_IP_HEADER, e.g. cf-connecting-ip) so installs behind
   Cloudflare are fingerprinted on the real device IP instead of a CDN/NAT
   hop. Opt-in; default behavior unchanged.

Existing /24-match tests repointed from private to public IPs (their intent
was to verify /24 matching, which now correctly requires routable IPs).
Full suite green (125 tests).

Author: onamfc

src/lib/client-ip.test.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect, vi } from 'vitest';
+import { describe, it, expect, vi, afterEach } from 'vitest';
 import type { FastifyRequest } from 'fastify';
 import { getClientIp } from './client-ip';
 
@@ -36,6 +36,47 @@ describe('getClientIp', () => {
   });
 });
 
+describe('getClientIp with TRUSTED_CLIENT_IP_HEADER', () => {
+  const ORIGINAL = process.env.TRUSTED_CLIENT_IP_HEADER;
+  afterEach(() => {
+    if (ORIGINAL === undefined) delete process.env.TRUSTED_CLIENT_IP_HEADER;
+    else process.env.TRUSTED_CLIENT_IP_HEADER = ORIGINAL;
+  });
+
+  it('prefers the configured header over request.ip', () => {
+    process.env.TRUSTED_CLIENT_IP_HEADER = 'cf-connecting-ip';
+    const request = {
+      ip: '162.158.23.75', // a Cloudflare edge IP
+      headers: { 'cf-connecting-ip': '203.0.113.50' },
+    } as unknown as FastifyRequest;
+    expect(getClientIp(request)).toBe('203.0.113.50');
+  });
+
+  it('falls back to request.ip when the configured header is absent', () => {
+    process.env.TRUSTED_CLIENT_IP_HEADER = 'cf-connecting-ip';
+    const request = { ip: '203.0.113.50', headers: {} } as unknown as FastifyRequest;
+    expect(getClientIp(request)).toBe('203.0.113.50');
+  });
+
+  it('takes the first entry of a comma-separated header value', () => {
+    process.env.TRUSTED_CLIENT_IP_HEADER = 'true-client-ip';
+    const request = {
+      ip: '10.0.0.1',
+      headers: { 'true-client-ip': '203.0.113.50, 70.0.0.1' },
+    } as unknown as FastifyRequest;
+    expect(getClientIp(request)).toBe('203.0.113.50');
+  });
+
+  it('ignores the header when the env var is unset (default behavior)', () => {
+    delete process.env.TRUSTED_CLIENT_IP_HEADER;
+    const request = {
+      ip: '203.0.113.50',
+      headers: { 'cf-connecting-ip': '1.2.3.4' },
+    } as unknown as FastifyRequest;
+    expect(getClientIp(request)).toBe('203.0.113.50');
+  });
+});
+
 describe('getClientIp with Fastify trustProxy (proxied request)', () => {
   it('uses X-Forwarded-For when trustProxy is true', async () => {
     const Fastify = (await import('fastify')).default;

src/lib/client-ip.ts

@@ -1,18 +1,40 @@
 import type { FastifyRequest } from 'fastify';
 
+function normalizeIp(ip: string): string {
+  // IPv6-mapped IPv4: ::ffff:192.168.1.1 -> 192.168.1.1
+  return ip.startsWith('::ffff:') ? ip.slice(7) : ip;
+}
+
 /**
  * Returns the trusted client IP for the request.
  * Use this everywhere client IP is needed (targeting, attribution, fingerprinting).
- * When the server is behind a reverse proxy, set Fastify's trustProxy option
- * so that request.ip is populated from X-Forwarded-For; this helper then
- * returns that trusted value.
+ *
+ * Behind a CDN/proxy that terminates the connection (e.g. Cloudflare), the
+ * left-most `X-Forwarded-For` entry that Fastify exposes as `request.ip` is not
+ * reliably the real client — it can be a CDN edge or NAT hop. When the proxy
+ * sends an authoritative client-IP header (Cloudflare's `CF-Connecting-IP`, or
+ * `True-Client-IP`), prefer it.
+ *
+ * Set `TRUSTED_CLIENT_IP_HEADER` to that header name to opt in (e.g.
+ * `cf-connecting-ip`). IMPORTANT: only enable this when the origin is reachable
+ * ONLY through that proxy — otherwise a direct client could spoof the header.
+ * When unset, behavior is unchanged (uses `request.ip`).
  */
 export function getClientIp(request: FastifyRequest): string {
+  const headerName = process.env.TRUSTED_CLIENT_IP_HEADER?.toLowerCase().trim();
+  if (headerName) {
+    const raw = request.headers[headerName];
+    const value = Array.isArray(raw) ? raw[0] : raw;
+    if (value && typeof value === 'string') {
+      // Some proxies send a comma-separated list — take the first entry.
+      const first = value.split(',')[0]?.trim();
+      if (first) return normalizeIp(first);
+    }
+  }
+
   const ip = request.ip ?? request.raw.socket?.remoteAddress;
   if (ip && typeof ip === 'string') {
-    // IPv6-mapped IPv4: ::ffff:192.168.1.1 -> 192.168.1.1
-    if (ip.startsWith('::ffff:')) return ip.slice(7);
-    return ip;
+    return normalizeIp(ip);
   }
   return '';
 }

src/lib/fingerprint.test.ts

@@ -13,7 +13,7 @@ import { db } from './database';
 const mockDbQuery = db.query as Mock;
 
 const baseFingerprint = {
-  ipAddress: '192.168.1.100',
+  ipAddress: '24.5.10.100',
   userAgent:
     'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/95.0.4638.69 Safari/537.36',
   timezone: 'America/Los_Angeles',
@@ -66,7 +66,7 @@ describe('calculateConfidenceScore', () => {
   it('matches IP within the same /24 subnet and normalizes user agent', () => {
     const click = {
       ...baseFingerprint,
-      ipAddress: '192.168.1.250',
+      ipAddress: '24.5.10.250',
       timezone: 'Africa/Cairo',
       language: 'fr-FR',
       screenWidth: 800,
@@ -76,7 +76,7 @@ describe('calculateConfidenceScore', () => {
 
     const install = {
       ...baseFingerprint,
-      ipAddress: '192.168.1.123',
+      ipAddress: '24.5.10.123',
       userAgent: baseFingerprint.userAgent.replace('Chrome/95.0.4638.69', 'Chrome/116.0.0.0'),
       timezone: 'Europe/London',
       language: 'de-DE',
@@ -149,6 +149,66 @@ describe('calculateConfidenceScore', () => {
   });
 });
 
+describe('isAttributableIp', () => {
+  it('treats public IPv4 as attributable', () => {
+    expect(fingerprint.isAttributableIp('24.5.10.100')).toBe(true);
+    expect(fingerprint.isAttributableIp('8.8.8.8')).toBe(true);
+  });
+
+  it('rejects CGNAT (100.64.0.0/10) — the Marriage365 case', () => {
+    expect(fingerprint.isAttributableIp('100.64.0.5')).toBe(false);
+    expect(fingerprint.isAttributableIp('100.127.255.254')).toBe(false);
+  });
+
+  it('rejects RFC1918 private, loopback and link-local', () => {
+    expect(fingerprint.isAttributableIp('10.0.0.1')).toBe(false);
+    expect(fingerprint.isAttributableIp('172.16.0.1')).toBe(false);
+    expect(fingerprint.isAttributableIp('192.168.1.1')).toBe(false);
+    expect(fingerprint.isAttributableIp('127.0.0.1')).toBe(false);
+    expect(fingerprint.isAttributableIp('169.254.1.1')).toBe(false);
+  });
+
+  it('handles IPv6: public attributable, ULA/link-local/loopback not', () => {
+    expect(fingerprint.isAttributableIp('2600:1700:6508:8040::1')).toBe(true);
+    expect(fingerprint.isAttributableIp('fd00::1')).toBe(false); // ULA
+    expect(fingerprint.isAttributableIp('fe80::1')).toBe(false); // link-local
+    expect(fingerprint.isAttributableIp('::1')).toBe(false); // loopback
+  });
+
+  it('unwraps IPv4-mapped IPv6 before classifying', () => {
+    expect(fingerprint.isAttributableIp('::ffff:100.64.0.5')).toBe(false);
+    expect(fingerprint.isAttributableIp('::ffff:24.5.10.100')).toBe(true);
+  });
+
+  it('returns false for empty/garbage input', () => {
+    expect(fingerprint.isAttributableIp('')).toBe(false);
+    expect(fingerprint.isAttributableIp('not-an-ip')).toBe(false);
+  });
+});
+
+describe('calculateConfidenceScore — shared-IP filter', () => {
+  it('does NOT award the IP score for two devices sharing a CGNAT /24', () => {
+    // Exactly the Marriage365 leak: unrelated installs collapsing onto 100.64.0.x.
+    const click = { ...baseFingerprint, ipAddress: '100.64.0.5' };
+    const install = { ...baseFingerprint, ipAddress: '100.64.0.9' };
+
+    const { score, matchedFactors } = fingerprint.calculateConfidenceScore(click, install);
+
+    expect(matchedFactors).not.toContain('ip');
+    // UA(30)+TZ(10)+lang(10)+screen(10) = 60, below the 70 threshold → no match.
+    expect(score).toBe(60);
+    expect(score).toBeLessThan(fingerprint.CONFIDENCE_THRESHOLD);
+  });
+
+  it('still awards the IP score for two devices sharing a public /24', () => {
+    const click = { ...baseFingerprint, ipAddress: '24.5.10.5' };
+    const install = { ...baseFingerprint, ipAddress: '24.5.10.9' };
+
+    const { matchedFactors } = fingerprint.calculateConfidenceScore(click, install);
+    expect(matchedFactors).toContain('ip');
+  });
+});
+
 describe('matchInstallToClick', () => {
   beforeEach(() => {
     vi.useFakeTimers();
@@ -176,7 +236,7 @@ describe('matchInstallToClick', () => {
       link_id: 'link-a',
       clicked_at: clickTime.toISOString(),
       attribution_window_hours: 24,
-      ip_address: '192.168.1.200',
+      ip_address: '24.5.10.200',
       user_agent: 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) Safari/537.36',
       timezone: 'Asia/Tokyo',
       language: 'ja-JP',
@@ -192,7 +252,7 @@ describe('matchInstallToClick', () => {
       link_id: 'link-b',
       clicked_at: clickTime.toISOString(),
       attribution_window_hours: 24,
-      ip_address: '192.168.1.250',
+      ip_address: '24.5.10.250',
       user_agent:
         'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/116.0.0.0 Safari/537.36',
       timezone: 'America/Los_Angeles',
@@ -207,7 +267,7 @@ describe('matchInstallToClick', () => {
 
     const installFingerprint = {
       ...baseFingerprint,
-      ipAddress: '192.168.1.123',
+      ipAddress: '24.5.10.123',
       userAgent: baseFingerprint.userAgent.replace('Chrome/95.0.4638.69', 'Chrome/116.0.0.0'),
     };
 

src/lib/fingerprint.ts

@@ -72,6 +72,73 @@ export function generateFingerprintHash(data: FingerprintData): string {
  * Normalize IP address for comparison
  * Handles IPv4 and IPv6, removes subnet variations
  */
+function ipv4ToInt(ip: string): number | null {
+  const parts = ip.split('.');
+  if (parts.length !== 4) return null;
+  let n = 0;
+  for (const p of parts) {
+    const o = Number(p);
+    if (!Number.isInteger(o) || o < 0 || o > 255) return null;
+    n = (n << 8) | o;
+  }
+  return n >>> 0;
+}
+
+function inCidr4(ipInt: number, baseIp: string, prefix: number): boolean {
+  const base = ipv4ToInt(baseIp);
+  if (base === null) return false;
+  const mask = prefix === 0 ? 0 : (~0 << (32 - prefix)) >>> 0;
+  return (ipInt & mask) === (base & mask);
+}
+
+// Shared / non-routable IPv4 ranges that can't identify a single device:
+// carrier-grade NAT, RFC1918 private, loopback, link-local, etc. Two different
+// users routinely share these (mobile carrier NAT, office Wi-Fi, VPN egress).
+const NON_ATTRIBUTABLE_V4: ReadonlyArray<readonly [string, number]> = [
+  ['0.0.0.0', 8],
+  ['10.0.0.0', 8],
+  ['100.64.0.0', 10], // CGNAT (RFC 6598)
+  ['127.0.0.0', 8], // loopback
+  ['169.254.0.0', 16], // link-local
+  ['172.16.0.0', 12], // private
+  ['192.0.0.0', 24], // IETF protocol assignments
+  ['192.168.0.0', 16], // private
+  ['198.18.0.0', 15], // benchmarking
+];
+
+/**
+ * Whether an IP is specific enough to use as an attribution signal. Returns
+ * false for shared/non-routable ranges (CGNAT, RFC1918, loopback, link-local,
+ * IPv6 ULA/link-local) where the IP does NOT identify a single device, so it
+ * must not contribute to a fingerprint match. Public IPs return true.
+ */
+export function isAttributableIp(ip: string): boolean {
+  if (!ip) return false;
+  let addr = ip.trim();
+  if (addr.startsWith('::ffff:')) addr = addr.slice(7); // IPv4-mapped IPv6
+
+  // IPv4
+  if (addr.includes('.') && !addr.includes(':')) {
+    const n = ipv4ToInt(addr);
+    if (n === null) return false;
+    return !NON_ATTRIBUTABLE_V4.some(([base, prefix]) => inCidr4(n, base, prefix));
+  }
+
+  // IPv6
+  if (addr.includes(':')) {
+    const low = addr.toLowerCase();
+    if (low === '::' || low === '::1') return false; // unspecified / loopback
+    if (low.startsWith('fc') || low.startsWith('fd')) return false; // fc00::/7 ULA
+    if (low.startsWith('fe8') || low.startsWith('fe9') || low.startsWith('fea') || low.startsWith('feb')) {
+      return false; // fe80::/10 link-local
+    }
+    return true;
+  }
+
+  // Not a recognizable IPv4 or IPv6 address.
+  return false;
+}
+
 function normalizeIP(ip: string): string {
   if (!ip) return '';
 
@@ -119,8 +186,15 @@ export function calculateConfidenceScore(
   let score = 0;
   const matchedFactors: string[] = [];
 
-  // Compare IP addresses (normalized to /24 subnet for IPv4)
-  if (fingerprint1.ipAddress && fingerprint2.ipAddress) {
+  // Compare IP addresses (normalized to /24 subnet for IPv4). Only count IPs
+  // that actually identify a device — shared/NAT ranges (CGNAT, RFC1918, etc.)
+  // are skipped so unrelated users behind the same NAT can't match on IP.
+  if (
+    fingerprint1.ipAddress &&
+    fingerprint2.ipAddress &&
+    isAttributableIp(fingerprint1.ipAddress) &&
+    isAttributableIp(fingerprint2.ipAddress)
+  ) {
     const ip1 = normalizeIP(fingerprint1.ipAddress);
     const ip2 = normalizeIP(fingerprint2.ipAddress);