@sprqvntrs/bot-verify 0.1.1

package/src/__tests__/ua.test.ts

@@ -0,0 +1,145 @@
+import { describe, it, expect } from 'vitest';
+import { detectClaimedCrawler, GOOGLE_CRAWLER_TOKENS } from '../ua.js';
+
+describe('detectClaimedCrawler', () => {
+  describe('Googlebot desktop', () => {
+    it('detects standard Googlebot UA', () => {
+      const ua = 'Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)';
+      expect(detectClaimedCrawler(ua)).toBe('Googlebot');
+    });
+
+    it('detects Googlebot with extra context', () => {
+      const ua = 'Googlebot/2.1 (+http://www.google.com/bot.html)';
+      expect(detectClaimedCrawler(ua)).toBe('Googlebot');
+    });
+  });
+
+  describe('Googlebot mobile', () => {
+    it('detects Googlebot-Mobile token', () => {
+      const ua =
+        'Mozilla/5.0 (Linux; Android 6.0.1; Nexus 5X Build/MMB29P) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/W.X.Y.Z Mobile Safari/537.36 (compatible; Googlebot-Mobile/2.1; +http://www.google.com/bot.html)';
+      expect(detectClaimedCrawler(ua)).toBe('Googlebot-Mobile');
+    });
+  });
+
+  describe('Googlebot-Image', () => {
+    it('returns Googlebot-Image (more specific than Googlebot)', () => {
+      const ua = 'Googlebot-Image/1.0';
+      expect(detectClaimedCrawler(ua)).toBe('Googlebot-Image');
+    });
+  });
+
+  describe('AdsBot-Google', () => {
+    it('detects AdsBot-Google desktop UA', () => {
+      const ua = 'AdsBot-Google (+http://www.google.com/adsbot.html)';
+      expect(detectClaimedCrawler(ua)).toBe('AdsBot-Google');
+    });
+
+    it('detects AdsBot-Google-Mobile (more specific)', () => {
+      const ua = 'Mozilla/5.0 (iPhone; CPU iPhone OS 14_0 like Mac OS X) AdsBot-Google-Mobile/1.0';
+      expect(detectClaimedCrawler(ua)).toBe('AdsBot-Google-Mobile');
+    });
+  });
+
+  describe('Google-InspectionTool', () => {
+    it('detects Google-InspectionTool', () => {
+      const ua = 'Mozilla/5.0 (compatible; Google-InspectionTool/1.0; +https://developers.google.com/search/docs/crawling-indexing/overview-google-crawlers)';
+      expect(detectClaimedCrawler(ua)).toBe('Google-InspectionTool');
+    });
+  });
+
+  describe('Mediapartners-Google', () => {
+    it('detects Mediapartners-Google', () => {
+      const ua = 'Mediapartners-Google';
+      expect(detectClaimedCrawler(ua)).toBe('Mediapartners-Google');
+    });
+  });
+
+  describe('GoogleOther', () => {
+    it('detects GoogleOther standalone', () => {
+      const ua = 'GoogleOther';
+      expect(detectClaimedCrawler(ua)).toBe('GoogleOther');
+    });
+
+    it('detects GoogleOther inside parentheses — close-paren boundary (regression)', () => {
+      // The token is terminated by ')' — the old character-class regex missed this
+      const ua =
+        'Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; GoogleOther) Chrome/148.0 Safari/537.36';
+      expect(detectClaimedCrawler(ua)).toBe('GoogleOther');
+    });
+  });
+
+  describe('paren-terminated tokens (close-paren boundary fix)', () => {
+    it('detects Googlebot when token ends with ")"', () => {
+      // Simulates a UA string where the token is the last word before the closing paren
+      const ua = 'Mozilla/5.0 (compatible; Googlebot)';
+      expect(detectClaimedCrawler(ua)).toBe('Googlebot');
+    });
+
+    it('detects Googlebot-Image with slash suffix (regression guard)', () => {
+      const ua = 'Googlebot-Image/1.0';
+      expect(detectClaimedCrawler(ua)).toBe('Googlebot-Image');
+    });
+
+    it('detects Googlebot inside standard paren UA (regression guard)', () => {
+      const ua = 'Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)';
+      expect(detectClaimedCrawler(ua)).toBe('Googlebot');
+    });
+  });
+
+  describe('non-Google browsers → null', () => {
+    it('returns null for Chrome desktop UA', () => {
+      const ua =
+        'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36';
+      expect(detectClaimedCrawler(ua)).toBeNull();
+    });
+
+    it('returns null for Safari UA', () => {
+      const ua =
+        'Mozilla/5.0 (Macintosh; Intel Mac OS X 14_0) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Safari/605.1.15';
+      expect(detectClaimedCrawler(ua)).toBeNull();
+    });
+
+    it('returns null for Firefox UA', () => {
+      const ua = 'Mozilla/5.0 (X11; Linux x86_64; rv:120.0) Gecko/20100101 Firefox/120.0';
+      expect(detectClaimedCrawler(ua)).toBeNull();
+    });
+
+    it('returns null for empty string', () => {
+      expect(detectClaimedCrawler('')).toBeNull();
+    });
+
+    it('returns null for a UA that merely mentions google.com', () => {
+      const ua = 'Mozilla/5.0 (compatible; MyCrawler/1.0; see http://www.google.com/)';
+      expect(detectClaimedCrawler(ua)).toBeNull();
+    });
+
+    it('returns null when token appears as substring of a longer word', () => {
+      // "notagooglebot-thing" contains "Googlebot" but embedded — must not match
+      const ua = 'SomeBrowser/1.0 (notagooglebot-thing)';
+      expect(detectClaimedCrawler(ua)).toBeNull();
+    });
+
+    it('returns null for normal Chrome UA (no Google crawler tokens)', () => {
+      const ua =
+        'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36';
+      expect(detectClaimedCrawler(ua)).toBeNull();
+    });
+  });
+
+  describe('GOOGLE_CRAWLER_TOKENS export', () => {
+    it('is a non-empty readonly array', () => {
+      expect(GOOGLE_CRAWLER_TOKENS.length).toBeGreaterThan(0);
+    });
+
+    it('contains Googlebot', () => {
+      expect(GOOGLE_CRAWLER_TOKENS).toContain('Googlebot');
+    });
+
+    it('contains AdsBot-Google-Mobile before AdsBot-Google', () => {
+      const mobileIdx = GOOGLE_CRAWLER_TOKENS.indexOf('AdsBot-Google-Mobile');
+      const desktopIdx = GOOGLE_CRAWLER_TOKENS.indexOf('AdsBot-Google');
+      expect(mobileIdx).toBeLessThan(desktopIdx);
+    });
+  });
+});

package/src/__tests__/verify.test.ts

@@ -0,0 +1,259 @@
+import { describe, it, expect, vi } from 'vitest';
+import { createBotVerifier } from '../verify.js';
+import { parsePrefixes } from '../ranges.js';
+
+// Load the bundled data to pick sample IPs — same data the production store uses
+import googlebotData from '../data/googlebot.json' assert { type: 'json' };
+import specialCrawlersData from '../data/special-crawlers.json' assert { type: 'json' };
+import userTriggeredData from '../data/user-triggered-fetchers.json' assert { type: 'json' };
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+const GOOGLEBOT_UA = 'Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)';
+const CHROME_UA = 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 Chrome/120.0 Safari/537.36';
+const SPOOF_IP = '45.39.15.48'; // Not a Google IP
+
+/** Creates a verifier that will never touch the network */
+function createTestVerifier(overrides?: Parameters<typeof createBotVerifier>[0]) {
+  return createBotVerifier({
+    fetchImpl: () => { throw new Error('network disabled in tests'); },
+    rdns: false,
+    ...overrides,
+  });
+}
+
+// ─── Sample IPs from each bundled file ──────────────────────────────────────
+
+const googlebotPrefixes = parsePrefixes(googlebotData);
+const specialPrefixes = parsePrefixes(specialCrawlersData);
+const userTriggeredPrefixes = parsePrefixes(userTriggeredData);
+
+/** Pick the first IP from a /N CIDR prefix (the network address + 1 for hosts) */
+function firstIpInPrefix(cidr: string): string {
+  const [base] = cidr.split('/');
+  if (base === undefined) throw new Error(`Invalid CIDR: ${cidr}`);
+  // For IPv4, increment the last octet by 1 to get a host address
+  if (!base.includes(':')) {
+    const parts = base.split('.');
+    const last = parts[3];
+    if (last !== undefined) {
+      const n = parseInt(last, 10);
+      parts[3] = String(n + 1);
+      return parts.join('.');
+    }
+  }
+  // For IPv6, append ::1
+  return `${base}1`;
+}
+
+// A few sample IPs from each file
+const googlebotIpv4 = (() => {
+  const p = googlebotPrefixes.find((c) => !c.includes(':'));
+  if (!p) throw new Error('No IPv4 prefix in googlebot.json');
+  return firstIpInPrefix(p);
+})();
+
+const googlebotIpv6 = (() => {
+  const p = googlebotPrefixes.find((c) => c.includes(':'));
+  if (!p) throw new Error('No IPv6 prefix in googlebot.json');
+  return firstIpInPrefix(p);
+})();
+
+const specialIpv4 = (() => {
+  const p = specialPrefixes.find((c) => !c.includes(':'));
+  if (!p) throw new Error('No IPv4 prefix in special-crawlers.json');
+  return firstIpInPrefix(p);
+})();
+
+const userTriggeredIpv4 = (() => {
+  const p = userTriggeredPrefixes.find((c) => !c.includes(':'));
+  if (!p) throw new Error('No IPv4 prefix in user-triggered-fetchers.json');
+  return firstIpInPrefix(p);
+})();
+
+// ─── Tests ──────────────────────────────────────────────────────────────────
+
+describe('createBotVerifier', () => {
+  describe('not-a-claim (non-Google UA)', () => {
+    it('returns not-a-claim for a normal browser UA', async () => {
+      const verifier = createTestVerifier();
+      const result = await verifier.verify({ userAgent: CHROME_UA, ip: SPOOF_IP });
+      expect(result.verdict).toBe('not-a-claim');
+      expect(result.claimedBot).toBeNull();
+      expect(result.method).toBe('none');
+    });
+  });
+
+  describe('uncertain (missing/invalid IP)', () => {
+    it('returns uncertain when ip is null', async () => {
+      const verifier = createTestVerifier({ rdns: true });
+      const result = await verifier.verify({ userAgent: GOOGLEBOT_UA, ip: null });
+      expect(result.verdict).toBe('uncertain');
+      expect(result.claimedBot).toBe('Googlebot');
+    });
+
+    it('returns uncertain when ip is empty string', async () => {
+      const verifier = createTestVerifier({ rdns: true });
+      const result = await verifier.verify({ userAgent: GOOGLEBOT_UA, ip: '' });
+      expect(result.verdict).toBe('uncertain');
+    });
+
+    it('returns uncertain when ip is not a valid address', async () => {
+      const verifier = createTestVerifier({ rdns: true });
+      const result = await verifier.verify({ userAgent: GOOGLEBOT_UA, ip: 'not-an-ip' });
+      expect(result.verdict).toBe('uncertain');
+    });
+  });
+
+  describe('verified via ip-range', () => {
+    it('verifies a real Googlebot IPv4 from googlebot.json', async () => {
+      const verifier = createTestVerifier();
+      const result = await verifier.verify({ userAgent: GOOGLEBOT_UA, ip: googlebotIpv4 });
+      expect(result.verdict).toBe('verified');
+      expect(result.method).toBe('ip-range');
+    });
+
+    it('verifies a real Googlebot IPv6 from googlebot.json', async () => {
+      const verifier = createTestVerifier();
+      const result = await verifier.verify({ userAgent: GOOGLEBOT_UA, ip: googlebotIpv6 });
+      expect(result.verdict).toBe('verified');
+      expect(result.method).toBe('ip-range');
+    });
+
+    it('verifies a real IP from special-crawlers.json', async () => {
+      const verifier = createTestVerifier();
+      const result = await verifier.verify({ userAgent: GOOGLEBOT_UA, ip: specialIpv4 });
+      expect(result.verdict).toBe('verified');
+      expect(result.method).toBe('ip-range');
+    });
+
+    it('verifies a real IP from user-triggered-fetchers.json', async () => {
+      const verifier = createTestVerifier();
+      const result = await verifier.verify({ userAgent: GOOGLEBOT_UA, ip: userTriggeredIpv4 });
+      expect(result.verdict).toBe('verified');
+      expect(result.method).toBe('ip-range');
+    });
+  });
+
+  describe('spoofed (rdns: false)', () => {
+    it('returns spoofed for a non-Google IP when rdns is disabled', async () => {
+      const verifier = createTestVerifier({ rdns: false });
+      const result = await verifier.verify({ userAgent: GOOGLEBOT_UA, ip: SPOOF_IP });
+      expect(result.verdict).toBe('spoofed');
+      expect(result.method).toBe('ip-range');
+      expect(result.claimedBot).toBe('Googlebot');
+    });
+  });
+
+  describe('rdns outcomes', () => {
+    it('returns verified when rdnsImpl confirms', async () => {
+      const verifier = createTestVerifier({
+        rdns: true,
+        rdnsImpl: async () => 'confirmed',
+      });
+      const result = await verifier.verify({ userAgent: GOOGLEBOT_UA, ip: SPOOF_IP });
+      expect(result.verdict).toBe('verified');
+      expect(result.method).toBe('rdns');
+    });
+
+    it('returns spoofed when rdnsImpl returns failed', async () => {
+      const verifier = createTestVerifier({
+        rdns: true,
+        rdnsImpl: async () => 'failed',
+      });
+      const result = await verifier.verify({ userAgent: GOOGLEBOT_UA, ip: SPOOF_IP });
+      expect(result.verdict).toBe('spoofed');
+      expect(result.method).toBe('rdns');
+    });
+
+    it('returns uncertain when rdnsImpl returns error (fail-open)', async () => {
+      const verifier = createTestVerifier({
+        rdns: true,
+        rdnsImpl: async () => 'error',
+      });
+      const result = await verifier.verify({ userAgent: GOOGLEBOT_UA, ip: SPOOF_IP });
+      expect(result.verdict).toBe('uncertain');
+      expect(result.method).toBe('rdns');
+    });
+  });
+
+  describe('INVARIANT: no real Google IP is ever classified as spoofed', () => {
+    it('verifies multiple sample IPs from each bundled file', async () => {
+      const verifier = createTestVerifier({ rdns: false });
+
+      // Pick a few v4 and v6 samples from each file
+      const allPrefixes = [
+        ...googlebotPrefixes.slice(0, 3),
+        ...specialPrefixes.slice(0, 3),
+        ...userTriggeredPrefixes.slice(0, 3),
+      ];
+
+      for (const prefix of allPrefixes) {
+        const ip = firstIpInPrefix(prefix);
+        const result = await verifier.verify({ userAgent: GOOGLEBOT_UA, ip });
+        expect(result.verdict, `Expected verified for ${ip} (${prefix})`).toBe('verified');
+      }
+    });
+  });
+
+  describe('fail-open: empty range store + rdns error → uncertain (never spoofed)', () => {
+    it('returns uncertain, not spoofed, when ranges are empty and rDNS errors', async () => {
+      const verifier = createBotVerifier({
+        initialRanges: [],
+        fetchImpl: () => { throw new Error('no network'); },
+        rdns: true,
+        rdnsImpl: async () => 'error',
+      });
+      const result = await verifier.verify({ userAgent: GOOGLEBOT_UA, ip: SPOOF_IP });
+      expect(result.verdict).toBe('uncertain');
+      expect(result.verdict).not.toBe('spoofed');
+    });
+  });
+
+  describe('logger', () => {
+    it('calls the logger with the result', async () => {
+      const loggedResults: unknown[] = [];
+      const verifier = createTestVerifier({
+        logger: (r) => loggedResults.push(r),
+      });
+      await verifier.verify({ userAgent: GOOGLEBOT_UA, ip: SPOOF_IP });
+      expect(loggedResults).toHaveLength(1);
+    });
+
+    it('does not propagate logger errors', async () => {
+      const verifier = createTestVerifier({
+        logger: () => { throw new Error('logger exploded'); },
+      });
+      await expect(
+        verifier.verify({ userAgent: GOOGLEBOT_UA, ip: SPOOF_IP }),
+      ).resolves.not.toThrow();
+    });
+  });
+
+  describe('refreshRanges', () => {
+    it('returns false when fetch fails', async () => {
+      const verifier = createTestVerifier();
+      const ok = await verifier.refreshRanges();
+      expect(ok).toBe(false);
+    });
+
+    it('returns true when fetch succeeds with valid data', async () => {
+      const samplePayload = {
+        prefixes: [
+          { ipv4Prefix: '192.0.2.0/24' },
+        ],
+      };
+      const mockFetch = vi.fn(async () => ({
+        ok: true,
+        json: async () => samplePayload,
+      } as unknown as Response));
+
+      const verifier = createBotVerifier({
+        fetchImpl: mockFetch as typeof fetch,
+        rdns: false,
+      });
+      const ok = await verifier.refreshRanges();
+      expect(ok).toBe(true);
+    });
+  });
+});

package/src/cidr.ts

@@ -0,0 +1,114 @@
+/**
+ * IP address and CIDR matching utilities using ipaddr.js.
+ *
+ * All functions are fail-open: malformed input returns `false` / `null`
+ * rather than throwing.
+ *
+ * @packageDocumentation
+ */
+
+import ipaddr from 'ipaddr.js';
+
+/**
+ * Normalizes an IP address string to a canonical form:
+ * - IPv4: standard dotted-decimal, no trailing zeros
+ * - IPv6: lowercase compressed form (RFC 5952); v4-mapped addresses (`::ffff:1.2.3.4`)
+ *   are unwrapped to their plain IPv4 form
+ *
+ * Returns `null` for any input that is not a valid IP address.
+ *
+ * @param ip - Raw IP string (may include port brackets like `[::1]`)
+ */
+export function normalizeIp(ip: string): string | null {
+  const stripped = stripBracketsAndPort(ip);
+  if (!stripped) {
+    return null;
+  }
+
+  try {
+    const parsed = ipaddr.parse(stripped);
+
+    if (parsed.kind() === 'ipv6') {
+      const v6 = parsed as ipaddr.IPv6;
+      if (v6.isIPv4MappedAddress()) {
+        // Unwrap ::ffff:x.x.x.x → plain IPv4
+        return v6.toIPv4Address().toString();
+      }
+      // toRFC5952String() produces compressed lowercase form (e.g. "::1")
+      return v6.toRFC5952String();
+    }
+
+    return parsed.toString();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Tests whether `ip` falls within the given `cidr` range.
+ *
+ * Handles v4, v6, and v4-mapped-v6 by normalizing before comparison.
+ * Different address families never match each other.
+ * Returns `false` for any malformed input rather than throwing.
+ *
+ * @param ip - The IP address to test
+ * @param cidr - A CIDR string such as `'66.249.64.0/19'` or `'2001:4860:4800::/32'`
+ */
+export function ipInCidr(ip: string, cidr: string): boolean {
+  try {
+    const normalizedIpStr = normalizeIp(ip);
+    if (normalizedIpStr === null) {
+      return false;
+    }
+
+    const addr = ipaddr.parse(normalizedIpStr);
+    const [network, prefixLen] = ipaddr.parseCIDR(cidr);
+
+    // Different kinds (v4 vs v6) never match
+    if (addr.kind() !== network.kind()) {
+      return false;
+    }
+
+    return addr.match([network, prefixLen]);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Tests whether `ip` falls within any of the given `cidrs`.
+ *
+ * Short-circuits on first match. Returns `false` if the list is empty.
+ */
+export function ipInAnyCidr(ip: string, cidrs: readonly string[]): boolean {
+  for (const cidr of cidrs) {
+    if (ipInCidr(ip, cidr)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Strips IPv6 bracket notation and optional port from an IP string.
+ * e.g. `[::1]:8080` → `::1`, `1.2.3.4:80` (plain IPv4 with port) stays as-is
+ * since ipaddr.js handles plain dotted IPv4 without ports.
+ */
+function stripBracketsAndPort(raw: string): string {
+  const trimmed = raw.trim();
+
+  // IPv6 bracket form: [addr] or [addr]:port
+  if (trimmed.startsWith('[')) {
+    const end = trimmed.indexOf(']');
+    if (end === -1) {
+      return '';
+    }
+    return trimmed.slice(1, end);
+  }
+
+  return trimmed;
+}

package/src/client-ip.ts

@@ -0,0 +1,94 @@
+/**
+ * Secure client IP extraction from HTTP headers.
+ *
+ * SECURITY MODEL:
+ * - The leftmost X-Forwarded-For entry is ALWAYS attacker-controlled and
+ *   must never be trusted as the real client IP without a trusted proxy chain.
+ * - Only a header set by a proxy we control (`trustedHeader`) or the rightmost
+ *   N entries in XFF (where N = trusted proxy count) are safe to use.
+ *
+ * @packageDocumentation
+ */
+
+import { normalizeIp } from './cidr.js';
+
+/** Options for {@link getClientIp}. */
+export interface ClientIpOptions {
+  /**
+   * Name of a header (lowercase) that a trusted reverse-proxy overwrites with
+   * the real client IP, e.g. `'x-real-ip'`. When present and valid, this
+   * header is returned verbatim without inspecting X-Forwarded-For.
+   *
+   * Only use this if the proxy unconditionally overwrites the header (not
+   * merely appends to it), so it cannot be spoofed by the client.
+   */
+  trustedHeader?: string;
+  /**
+   * Number of trusted proxies in the infrastructure chain, counted from the
+   * RIGHT of the X-Forwarded-For list. Default `0` (only the rightmost entry,
+   * added by the edge proxy, is trusted).
+   *
+   * Example: `"clientIP, proxy1, proxy2"` with `xffTrustedProxyCount: 1`
+   * means `proxy2` is trusted, so the real client IP is `proxy1`.
+   *
+   * NEVER set this higher than the number of proxies you control.
+   */
+  xffTrustedProxyCount?: number;
+}
+
+/**
+ * Extracts the best-available client IP from the request headers.
+ *
+ * Priority:
+ * 1. `trustedHeader` (if configured and contains a valid IP)
+ * 2. X-Forwarded-For, counting `xffTrustedProxyCount` proxies from the right
+ *
+ * Returns `null` when no valid IP can be determined.
+ *
+ * IMPORTANT: The leftmost X-Forwarded-For entry is attacker-controlled.
+ * A forged Google IP in position 0 does NOT affect the result when
+ * `xffTrustedProxyCount` is `0` (the default).
+ *
+ * @param headers - The request Headers object
+ * @param opts - IP extraction options
+ */
+export function getClientIp(headers: Headers, opts?: ClientIpOptions): string | null {
+  if (opts?.trustedHeader) {
+    const headerValue = headers.get(opts.trustedHeader);
+    if (headerValue) {
+      const normalized = normalizeIp(headerValue.trim());
+      if (normalized !== null) {
+        return normalized;
+      }
+    }
+  }
+
+  const xffHeader = headers.get('x-forwarded-for');
+  if (!xffHeader) {
+    return null;
+  }
+
+  const entries = xffHeader
+    .split(',')
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+
+  if (entries.length === 0) {
+    return null;
+  }
+
+  const k = opts?.xffTrustedProxyCount ?? 0;
+  // The entry at `len - 1 - k` is the first untrusted entry from the right
+  const targetIndex = entries.length - 1 - k;
+
+  if (targetIndex < 0 || targetIndex >= entries.length) {
+    return null;
+  }
+
+  const candidate = entries[targetIndex];
+  if (candidate === undefined) {
+    return null;
+  }
+
+  return normalizeIp(candidate);
+}