Skip to content

Full Toolkit for Next-Level Domain Analysis

9.2 KB
Raw Blame
import isIP from 'validator/lib/isIP';
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';

import {
  getIpDetails,
  ipToDnsName,
  ipv4ToDnsName,
  ipv6ToDnsName,
  lookupReverse,
  normalizeIpEnding,
} from './ips';

describe('ipv4ToDnsName', () => {
  // Intentionally omit the trailing root dot: these names are used as DNS query
  // inputs, not DNS master-file absolute-name presentation strings.
  it('should convert an IPv4 address to a reverse DNS lookup format', () => {
    expect(ipv4ToDnsName('8.8.8.8')).toBe('8.8.8.8.in-addr.arpa');
  });

  it('should reverse non-symmetric IPv4 octets', () => {
    expect(ipv4ToDnsName('192.0.2.1')).toBe('1.2.0.192.in-addr.arpa');
  });
});

describe('ipv6ToDnsName', () => {
  // Intentionally omit the trailing root dot: these names are used as DNS query
  // inputs, not DNS master-file absolute-name presentation strings.
  it('should convert an IPv6 address to a reverse DNS lookup format', () => {
    expect(ipv6ToDnsName('2001:db8::1')).toBe(
      '1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.8.b.d.0.1.0.0.2.ip6.arpa',
    );
  });

  it('should normalize uppercase IPv6 hex digits to lowercase reverse labels', () => {
    expect(ipv6ToDnsName('2001:DB8::1')).toBe(
      '1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.8.b.d.0.1.0.0.2.ip6.arpa',
    );
  });

  it('should convert a fully expanded IPv6 address to a reverse DNS lookup format', () => {
    expect(ipv6ToDnsName('2001:0db8:85a3:0000:0000:8a2e:0370:7334')).toBe(
      '4.3.3.7.0.7.3.0.e.2.a.8.0.0.0.0.0.0.0.0.3.a.5.8.8.b.d.0.1.0.0.2.ip6.arpa',
    );
  });

  it('should pad short hextets in an uncompressed IPv6 address', () => {
    expect(ipv6ToDnsName('2001:db8:1:2:3:4:5:6')).toBe(
      '6.0.0.0.5.0.0.0.4.0.0.0.3.0.0.0.2.0.0.0.1.0.0.0.8.b.d.0.1.0.0.2.ip6.arpa',
    );
  });

  it('should expand :: when it represents exactly one zero hextet', () => {
    expect(ipv6ToDnsName('2001:db8:0:1::2:3:4')).toBe(
      '4.0.0.0.3.0.0.0.2.0.0.0.0.0.0.0.1.0.0.0.0.0.0.0.8.b.d.0.1.0.0.2.ip6.arpa',
    );
  });

  it('should convert an IPv4-mapped IPv6 address to a reverse DNS lookup format', () => {
    expect(ipv6ToDnsName('::ffff:192.0.2.128')).toBe(
      '0.8.2.0.0.0.0.c.f.f.f.f.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.ip6.arpa',
    );
  });

  it('should convert an IPv4-embedded IPv6 address to a reverse DNS lookup format', () => {
    expect(ipv6ToDnsName('2001:db8::192.0.2.33')).toBe(
      '1.2.2.0.0.0.0.c.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.8.b.d.0.1.0.0.2.ip6.arpa',
    );
  });

  it('should expand "::" to all-zero hextets', () => {
    expect(ipv6ToDnsName('::')).toBe(
      '0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.ip6.arpa',
    );
  });

  it('should expand a leading "::" prefix', () => {
    expect(ipv6ToDnsName('::1')).toBe(
      '1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.ip6.arpa',
    );
  });

  it('should expand a trailing "::" suffix', () => {
    expect(ipv6ToDnsName('2001:db8::')).toBe(
      '0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.8.b.d.0.1.0.0.2.ip6.arpa',
    );
  });

  it('should produce exactly 32 nibbles for any valid IPv6 address', () => {
    const inputs = [
      '2001:db8::1',
      '::',
      '::1',
      '2001:db8::',
      '2001:0db8:85a3:0000:0000:8a2e:0370:7334',
      'fe80::250:56ff:fe97:2b82',
      'abcd:ef01::3456:7890',
    ];

    for (const ip of inputs) {
      expect(isIP(ip), `precondition: ${ip} is a valid IP`).toBe(true);
      const name = ipv6ToDnsName(ip);
      expect(name.endsWith('.ip6.arpa'), `${ip} -> ${name}`).toBe(true);
      const nibbles = name.slice(0, -'.ip6.arpa'.length).split('.');
      expect(nibbles.length, `${ip} -> ${name}`).toBe(32);
      for (const nibble of nibbles) {
        expect(nibble, `${ip} -> ${name}`).toMatch(/^[0-9a-f]$/);
      }
    }
  });
});

describe('ipToDnsName', () => {
  it('should convert an IPv4 address to a reverse DNS lookup format', () => {
    expect(ipToDnsName('8.8.8.8')).toBe('8.8.8.8.in-addr.arpa');
  });

  it('should reverse non-symmetric IPv4 octets', () => {
    expect(ipToDnsName('192.0.2.1')).toBe('1.2.0.192.in-addr.arpa');
  });

  it('should convert an IPv6 address to a reverse DNS lookup format', () => {
    expect(ipToDnsName('2001:db8::1')).toBe(
      '1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.8.b.d.0.1.0.0.2.ip6.arpa',
    );
  });
});

describe('getIpDetails', () => {
  it('should throw a user-facing error for invalid IP addresses', async () => {
    await expect(getIpDetails('not-an-ip')).rejects.toThrow(
      /Invalid IP address/,
    );
    await expect(getIpDetails('../../../etc/passwd')).rejects.toThrow(
      /Invalid IP address/,
    );
    await expect(getIpDetails('999.999.999.999')).rejects.toThrow(
      /Invalid IP address/,
    );
  });
});

describe('lookupReverse', () => {
  const fetchMock = vi.fn();

  beforeEach(() => {
    fetchMock.mockReset();
    vi.stubGlobal('fetch', fetchMock);
  });

  afterEach(() => vi.unstubAllGlobals());

  it('returns only PTR hostnames through the uncached Cloudflare resolver', async () => {
    fetchMock.mockResolvedValue(
      Response.json({
        Status: 0,
        Answer: [
          {
            name: '8.8.8.8.in-addr.arpa',
            type: 5,
            TTL: 30,
            data: 'alias.example.',
          },
          { name: 'alias.example', type: 12, TTL: 300, data: 'dns.google.' },
          {
            name: 'alias.example',
            type: 12,
            TTL: 300,
            data: 'another.dns.google',
          },
        ],
      }),
    );

    expect(await lookupReverse('8.8.8.8')).toEqual([
      'dns.google',
      'another.dns.google',
    ]);
    expect(fetchMock).toHaveBeenCalledWith(
      new URL(
        'https://cloudflare-dns.com/dns-query?name=8.8.8.8.in-addr.arpa&type=PTR',
      ),
      expect.objectContaining({ cache: 'no-store' }),
    );
  });

  it.each([{ Status: 0 }, { Status: 3 }, { Status: 2 }])(
    'returns no hostnames for a DNS response without answers: %j',
    async (body) => {
      fetchMock.mockResolvedValue(Response.json(body));
      expect(await lookupReverse('8.8.4.4')).toEqual([]);
    },
  );

  it('preserves resolver errors for failed HTTP responses', async () => {
    fetchMock.mockResolvedValue(
      new Response(null, {
        status: 503,
        statusText: 'Service Unavailable',
      }),
    );
    await expect(lookupReverse('8.8.4.4')).rejects.toMatchObject({
      payload: { title: 'DNS resolver is unavailable', retryable: true },
    });
  });

  it('wraps network failures in a user-facing error', async () => {
    const error = new Error('Connection failed');
    fetchMock.mockRejectedValue(error);
    await expect(lookupReverse('8.8.4.4')).rejects.toMatchObject({
      payload: { title: "Couldn't reach Cloudflare DNS", retryable: true },
      cause: error,
    });
  });

  it('rejects malformed DNS data instead of returning an invalid hostname', async () => {
    fetchMock.mockResolvedValue(
      Response.json({
        Status: 0,
        Answer: [
          { name: '8.8.4.4.in-addr.arpa', type: 12, TTL: 300, data: null },
        ],
      }),
    );
    await expect(lookupReverse('8.8.4.4')).rejects.toThrow();
  });

  it('rejects invalid IP addresses before starting a DNS lookup', async () => {
    await expect(lookupReverse('not-an-ip')).rejects.toThrow(
      'Invalid IP address',
    );
    expect(fetchMock).not.toHaveBeenCalled();
  });
});

describe('normalizeIpEnding', () => {
  it('should normalize the last octet of an IPv4 address to .0', () => {
    expect(normalizeIpEnding('192.168.1.254')).toBe('192.168.1.0');
    expect(normalizeIpEnding('10.0.0.1')).toBe('10.0.0.0');
  });

  it('should normalize the last group of an IPv6 address to 0', () => {
    expect(normalizeIpEnding('fe80::250:56ff:fe97:2b82')).toBe(
      'fe80::250:56ff:fe97:0',
    );
    expect(normalizeIpEnding('2001:db8::1428:57ab')).toBe('2001:db8::1428:0');
  });

  it('should not alter the IP address if there is no trailing segment to normalize', () => {
    expect(normalizeIpEnding('192.168.1.0')).toBe('192.168.1.0');
    expect(normalizeIpEnding('2001:db8::1428:0')).toBe('2001:db8::1428:0');
  });

  it('should canonicalize compressed zero-tail IPv6 to the same key as the expanded form', () => {
    expect(normalizeIpEnding('2001:db8::')).toBe(
      normalizeIpEnding('2001:db8::0'),
    );
    expect(normalizeIpEnding('fe80::')).toBe(normalizeIpEnding('fe80::0'));
    expect(normalizeIpEnding('::')).toBe(normalizeIpEnding('::0'));
  });

  it('should still normalize based on pattern even for non-standard inputs', () => {
    expect(normalizeIpEnding('999.999.999.999')).toBe('999.999.999.0');
    expect(normalizeIpEnding('abcd:ef01::3456:7890')).toBe('abcd:ef01::3456:0');
  });

  it('should produce a valid IP address for valid inputs', () => {
    const inputs = [
      '192.168.1.254',
      '10.0.0.1',
      '8.8.8.8',
      'fe80::250:56ff:fe97:2b82',
      '2001:db8::1428:57ab',
      'abcd:ef01::3456:7890',
      '2001:0db8:85a3:0000:0000:8a2e:0370:7334',
      '::1',
    ];

    for (const ip of inputs) {
      expect(isIP(ip), `precondition: ${ip} is a valid IP`).toBe(true);
      const normalized = normalizeIpEnding(ip);
      expect(isIP(normalized), `${ip} -> ${normalized}`).toBe(true);
    }
  });
});