feat: add client IP resolution and debugging utilities

- Implemented `resolveClientIp` function to accurately determine the client's real IP address behind proxies and CDNs, enhancing security and audit capabilities.
- Introduced `buildClientIpDebugPayload` for detailed debugging information regarding client IP resolution, including raw header values and hints for proper proxy configuration.
- Added unit tests to validate the functionality of IP resolution and debugging utilities, ensuring robustness against various scenarios.

Author: tacxou

apps/api/src/_common/functions/resolve-client-ip.ts

@@ -0,0 +1,192 @@
+import type { Request } from 'express';
+import requestIp from 'request-ip';
+
+/**
+ * Lit une en-tête HTTP (string ou première entrée d'un tableau).
+ */
+function headerString(req: Request, name: string): string | undefined {
+  const v = req.headers[name.toLowerCase()];
+  if (typeof v === 'string') {
+    return v;
+  }
+  if (Array.isArray(v) && v.length > 0 && typeof v[0] === 'string') {
+    return v[0];
+  }
+  return undefined;
+}
+
+/**
+ * Prend la première valeur d'une liste CSV (ex. X-Forwarded-For: client, proxy1).
+ */
+function firstCsvSegment(value: string | undefined): string | null {
+  if (!value || typeof value !== 'string') {
+    return null;
+  }
+  const part = value.split(',')[0]?.trim();
+  return part && part.length > 0 ? part : null;
+}
+
+function normalizeIp(raw: string | undefined | null): string | null {
+  if (!raw || typeof raw !== 'string') {
+    return null;
+  }
+  const value = raw.trim();
+  if (value.length === 0) {
+    return null;
+  }
+  return value.startsWith('::ffff:') ? value.slice(7) : value;
+}
+
+function isLoopbackIp(ip: string | null): boolean {
+  return ip === '127.0.0.1' || ip === '::1';
+}
+
+function isPrivateIpv4(ip: string): boolean {
+  const parts = ip.split('.').map((p): number => Number.parseInt(p, 10));
+  if (parts.length !== 4 || parts.some((n) => Number.isNaN(n) || n < 0 || n > 255)) {
+    return false;
+  }
+  const [a, b] = parts;
+  if (a === 10) {
+    return true;
+  }
+  if (a === 172 && b >= 16 && b <= 31) {
+    return true;
+  }
+  if (a === 192 && b === 168) {
+    return true;
+  }
+  return false;
+}
+
+function hasForwardingHeaders(req: Request): boolean {
+  const forwarded = ['x-forwarded-for', 'x-real-ip', 'cf-connecting-ip', 'true-client-ip'] as const;
+  return forwarded.some((name) => Boolean(normalizeIp(firstCsvSegment(headerString(req, name)) ?? headerString(req, name) ?? null)));
+}
+
+function hostLooksLocal(req: Request): boolean {
+  const host = headerString(req, 'host');
+  if (!host) {
+    return false;
+  }
+  const hostname = host.split(':')[0]?.trim().toLowerCase();
+  return hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '::1';
+}
+
+function localDevFallbackIp(req: Request, peerIp: string | null): string | null {
+  if (!hostLooksLocal(req) || hasForwardingHeaders(req) || !peerIp) {
+    return null;
+  }
+  if (isLoopbackIp(peerIp) || isPrivateIpv4(peerIp)) {
+    return null;
+  }
+  return '127.0.0.1';
+}
+
+/** Paire TCP (souvent le dernier proxy / relai), normalisée. */
+function tcpPeerIp(req: Request): string | null {
+  return normalizeIp(req.socket?.remoteAddress ?? null);
+}
+
+/**
+ * Nitro / certains proxies posent X-Forwarded-For = IP du pair TCP sans ajouter la vraie IP client.
+ * Dans ce cas l’en-tête est trompeur : on l’ignore pour request-ip aussi.
+ */
+function requestForIpResolution(req: Request): Request {
+  const peer = tcpPeerIp(req);
+  const xffRaw = headerString(req, 'x-forwarded-for');
+  const xffFirst = normalizeIp(firstCsvSegment(xffRaw) ?? (xffRaw?.trim() || null));
+  if (!peer || !xffFirst || xffFirst !== peer) {
+    return req;
+  }
+  const headers = { ...req.headers } as Request['headers'];
+  delete headers['x-forwarded-for'];
+  return { ...req, headers } as Request;
+}
+
+/**
+ * Résout l'IP client réelle derrière CDN / reverse-proxy (Cloudflare, nginx, etc.).
+ * À utiliser pour l'auth et les audits ; combiner avec `trust proxy` sur Express si besoin.
+ *
+ * Si X-Forwarded-For ne fait que répéter l’IP du socket (souvent en dev derrière Nitro / Docker),
+ * cette valeur n’est pas considérée comme « client d’origine » : on retombe sur la même IP pair
+ * (cela ne fabrique pas une IP LAN magique — pour ça il faut un proxy qui pose une vraie chaîne XFF).
+ */
+export function resolveClientIp(req: Request): string | null {
+  const peerIp = tcpPeerIp(req);
+  const forcedLocalIp = localDevFallbackIp(req, peerIp);
+  if (forcedLocalIp) {
+    return forcedLocalIp;
+  }
+  const orderedHeaders = ['cf-connecting-ip', 'true-client-ip', 'x-real-ip', 'x-forwarded-for'] as const;
+
+  for (const name of orderedHeaders) {
+    const raw = headerString(req, name);
+    const segment = firstCsvSegment(raw) ?? (raw?.trim() || null);
+    const ip = normalizeIp(segment);
+    if (!ip) {
+      continue;
+    }
+    // Ne pas prendre un « forwarded » qui ne fait que recopier le pair TCP (pas de chaîne utile).
+    if (peerIp && ip === peerIp) {
+      continue;
+    }
+    return ip;
+  }
+
+  const fromLib = normalizeIp(requestIp.getClientIp(requestForIpResolution(req)) ?? null);
+  if (fromLib) {
+    return fromLib;
+  }
+
+  const expressIp = normalizeIp(req.ip ?? null);
+  if (expressIp) {
+    return expressIp;
+  }
+
+  return peerIp;
+}
+
+/**
+ * Objet JSON pour l’endpoint de debug (footer) : champs bruts + interprétation.
+ */
+export function buildClientIpDebugPayload(req: Request): Record<string, unknown> {
+  const pick = (name: string): string | string[] | undefined => {
+    const v = req.headers[name.toLowerCase()];
+    return v;
+  };
+
+  const peerIp = tcpPeerIp(req);
+  const xffRaw = headerString(req, 'x-forwarded-for');
+  const xffFirst = normalizeIp(firstCsvSegment(xffRaw) ?? (xffRaw?.trim() || null));
+  const xffEchoesPeer = Boolean(peerIp && xffFirst && peerIp === xffFirst);
+  const clientIp = resolveClientIp(req);
+  const hasTrustedForward =
+    Boolean(normalizeIp(headerString(req, 'x-real-ip'))) ||
+    Boolean(normalizeIp(headerString(req, 'cf-connecting-ip'))) ||
+    Boolean(normalizeIp(headerString(req, 'true-client-ip')));
+
+  let hintFr =
+    'clientIp = valeur utilisée par Nest (auth, audits). Ce n’est pas forcément « votre PC » si la connexion TCP passe par un relai (tunnel, port forward, Docker/Nitro).';
+
+  if (xffEchoesPeer && !hasTrustedForward) {
+    hintFr +=
+      ' Ici X-Forwarded-For ne fait que répéter l’IP du pair TCP (relai) : il est ignoré pour la résolution. Sans X-Real-IP / CF-Connecting-IP / premier hop X-Forwarded-For fiable, Nest ne peut pas inventer votre IP LAN. Solution : reverse-proxy (nginx, Traefik…) qui transmet le client, puis SESAME_TRUST_PROXY=1 sur l’API.';
+  }
+
+  return {
+    clientIp,
+    tcpPeerNormalized: peerIp,
+    xForwardedForFirstNormalized: xffFirst,
+    xffIgnoredAsEchoOfTcpPeer: xffEchoesPeer,
+    remoteAddress: req.socket?.remoteAddress ?? null,
+    ip: req.ip ?? null,
+    headers: req.headers,
+    xForwardedFor: pick('x-forwarded-for') ?? null,
+    xRealIp: pick('x-real-ip') ?? null,
+    cfConnectingIp: pick('cf-connecting-ip') ?? null,
+    host: pick('host') ?? null,
+    trustProxyEnv: process.env['SESAME_TRUST_PROXY'] ?? null,
+    hintFr,
+  };
+}

apps/api/tests/unit/_common/functions/resolve-client-ip.spec.ts

@@ -0,0 +1,86 @@
+import type { Request } from 'express';
+import { buildClientIpDebugPayload, resolveClientIp } from '~/_common/functions/resolve-client-ip';
+
+function makeReq(partial: Partial<Request> & { headers?: Record<string, string | string[] | undefined> }): Request {
+  return {
+    headers: {},
+    ip: undefined,
+    socket: { remoteAddress: undefined },
+    ...partial,
+  } as Request;
+}
+
+describe('resolveClientIp', () => {
+  it('returns CF-Connecting-IP when present', () => {
+    const req = makeReq({
+      headers: { 'cf-connecting-ip': '198.51.100.2' },
+      ip: '10.0.0.1',
+    });
+    expect(resolveClientIp(req)).toBe('198.51.100.2');
+  });
+
+  it('returns first X-Forwarded-For hop', () => {
+    const req = makeReq({
+      headers: { 'x-forwarded-for': '203.0.113.1, 10.0.0.2' },
+      ip: '10.0.0.2',
+    });
+    expect(resolveClientIp(req)).toBe('203.0.113.1');
+  });
+
+  it('returns X-Real-IP before falling back to req.ip', () => {
+    const req = makeReq({
+      headers: { 'x-real-ip': '192.0.2.50' },
+      ip: '10.0.0.3',
+    });
+    expect(resolveClientIp(req)).toBe('192.0.2.50');
+  });
+
+  it('strips IPv4-mapped IPv6 prefix', () => {
+    const req = makeReq({
+      headers: { 'x-real-ip': '::ffff:192.0.2.1' },
+    });
+    expect(resolveClientIp(req)).toBe('192.0.2.1');
+  });
+
+  it('ignores X-Forwarded-For when it only echoes tcp peer but still prefers X-Real-IP', () => {
+    const req = makeReq({
+      headers: {
+        'x-forwarded-for': '140.82.121.5',
+        'x-real-ip': '192.168.1.50',
+      },
+      ip: '140.82.121.5',
+      socket: { remoteAddress: '::ffff:140.82.121.5' } as any,
+    });
+    expect(resolveClientIp(req)).toBe('192.168.1.50');
+  });
+
+  it('ignores echoing X-Forwarded-For and falls back to same peer ip', () => {
+    const req = makeReq({
+      headers: { 'x-forwarded-for': '140.82.121.5' },
+      ip: '140.82.121.5',
+      socket: { remoteAddress: '140.82.121.5' } as any,
+    });
+    expect(resolveClientIp(req)).toBe('140.82.121.5');
+  });
+
+  it('buildClientIpDebugPayload flags echoing XFF', () => {
+    const req = makeReq({
+      headers: { 'x-forwarded-for': '140.82.121.5' },
+      ip: '140.82.121.5',
+      socket: { remoteAddress: '140.82.121.5' } as any,
+    });
+    const p = buildClientIpDebugPayload(req);
+    expect(p.xffIgnoredAsEchoOfTcpPeer).toBe(true);
+    expect(p.tcpPeerNormalized).toBe('140.82.121.5');
+    expect(p.hintFr).toEqual(expect.stringContaining('X-Forwarded-For'));
+  });
+
+  it('forces localhost when host is local and peer is unexpected public ip without forwarding headers', () => {
+    const req = makeReq({
+      headers: { host: '127.0.0.1:4002' },
+      ip: '140.82.121.5',
+      socket: { remoteAddress: '::ffff:140.82.121.5' } as any,
+    });
+    expect(resolveClientIp(req)).toBe('127.0.0.1');
+  });
+});