Skip to content

Full Toolkit for Next-Level Domain Analysis

Harden authoritative DNS resolver 🔒🛡️ (#91)

Felix Wotschofskye11d9f05602c
diff --git a/lib/resolvers/authoritative.test.ts b/lib/resolvers/authoritative.test.ts
new file mode 100644
index 0000000..08a3b43
--- /dev/null
+++ b/lib/resolvers/authoritative.test.ts
@@ -0,0 +1,1102 @@
+// @vitest-environment node
+import type { Answer, DecodedPacket } from 'dns-packet';
+import { describe, expect, it, vi } from 'vitest';
+
+import { UserFacingError } from '../user-facing-error';
+import {
+ AuthoritativeResolver,
+ type AuthoritativeTcpTransport,
+ type AuthoritativeUdpTransport,
+ isMatchingDnsResponse,
+} from './authoritative';
+import type { RecordType } from './base';
+
+const response = (
+ domain: string,
+ type: RecordType,
+ rcode: string,
+ answers: Answer[] = [],
+): DecodedPacket =>
+ ({
+ type: 'response',
+ id: 42,
+ flags: 0,
+ questions: [{ name: domain, type }],
+ answers,
+ authorities: [],
+ additionals: [],
+ rcode,
+ // The resolver only reads the fields set above; the flag_* booleans a real
+ // decode carries are filled in per-test where a test depends on them.
+ }) as unknown as DecodedPacket;
+
+describe('AuthoritativeResolver transport policy', () => {
+ it('tries the next nameserver after a retryable DNS rcode', async () => {
+ const udpTransport = vi.fn<AuthoritativeUdpTransport>(
+ async ({ domain, recordType, nameserver }) =>
+ nameserver === '192.0.2.1'
+ ? response(domain, recordType, 'SERVFAIL')
+ : response(domain, recordType, 'NOERROR', [
+ {
+ name: domain,
+ type: 'A',
+ ttl: 300,
+ data: '203.0.113.10',
+ },
+ ]),
+ );
+ const resolver = new AuthoritativeResolver({
+ udpTransport,
+ rootServers: async () => ['192.0.2.1', '192.0.2.2'],
+ });
+
+ await expect(
+ resolver.resolveRecordType('example.com', 'A'),
+ ).resolves.toEqual(
+ expect.objectContaining({
+ records: [expect.objectContaining({ data: '203.0.113.10' })],
+ }),
+ );
+ expect(
+ udpTransport.mock.calls.map(([request]) => request.nameserver),
+ ).toEqual(['192.0.2.1', '192.0.2.2']);
+ });
+
+ it('returns empty records when every nameserver refuses a plain query', async () => {
+ // Cloudflare authoritatives REFUSE direct RRSIG queries; that must not
+ // 500 the records page.
+ const udpTransport = vi.fn<AuthoritativeUdpTransport>(
+ async ({ domain, recordType }) => response(domain, recordType, 'REFUSED'),
+ );
+ const resolver = new AuthoritativeResolver({
+ udpTransport,
+ rootServers: async () => ['192.0.2.1', '192.0.2.2'],
+ });
+
+ await expect(
+ resolver.resolveRecordType('example.com', 'RRSIG'),
+ ).resolves.toEqual(expect.objectContaining({ records: [] }));
+ });
+
+ it('skips a lame empty response and accepts an authoritative sibling', async () => {
+ const udpTransport = vi.fn<AuthoritativeUdpTransport>(
+ async ({ domain, recordType, nameserver }) =>
+ nameserver === '192.0.2.1'
+ ? // Empty, not authoritative, no referral: a lame server, not
+ // proof of NODATA.
+ response(domain, recordType, 'NOERROR')
+ : ({
+ ...response(domain, recordType, 'NOERROR', [
+ { name: domain, type: 'A', ttl: 300, data: '203.0.113.10' },
+ ]),
+ flag_aa: true,
+ } as DecodedPacket),
+ );
+ const resolver = new AuthoritativeResolver({
+ udpTransport,
+ rootServers: async () => ['192.0.2.1', '192.0.2.2'],
+ });
+
+ await expect(
+ resolver.resolveRecordType('example.com', 'A'),
+ ).resolves.toEqual(
+ expect.objectContaining({
+ records: [expect.objectContaining({ data: '203.0.113.10' })],
+ }),
+ );
+ });
+
+ it('accepts an authoritative empty answer as NODATA', async () => {
+ const udpTransport = vi.fn<AuthoritativeUdpTransport>(
+ async ({ domain, recordType }) =>
+ ({
+ ...response(domain, recordType, 'NOERROR'),
+ flag_aa: true,
+ }) as DecodedPacket,
+ );
+ const resolver = new AuthoritativeResolver({
+ udpTransport,
+ rootServers: async () => ['192.0.2.1'],
+ });
+
+ await expect(
+ resolver.resolveRecordType('example.com', 'A'),
+ ).resolves.toEqual(expect.objectContaining({ records: [] }));
+ expect(udpTransport).toHaveBeenCalledTimes(1);
+ });
+
+ it('surfaces all-REFUSED plain non-RRSIG queries as retryable failures', async () => {
+ // The REFUSED-as-empty tolerance exists for RRSIG browsing only; a domain
+ // whose nameservers refuse ordinary lookups must not render "no records".
+ const udpTransport = vi.fn<AuthoritativeUdpTransport>(
+ async ({ domain, recordType }) => response(domain, recordType, 'REFUSED'),
+ );
+ const resolver = new AuthoritativeResolver({
+ udpTransport,
+ rootServers: async () => ['192.0.2.1', '192.0.2.2'],
+ });
+
+ await expect(
+ resolver.resolveRecordType('example.com', 'A'),
+ ).rejects.toBeInstanceOf(UserFacingError);
+ });
+
+ it('keeps answers whose owner name differs from the query only by case', async () => {
+ const udpTransport = vi.fn<AuthoritativeUdpTransport>(
+ async ({ domain, recordType }) =>
+ response(domain, recordType, 'NOERROR', [
+ { name: 'Example.COM', type: 'A', ttl: 300, data: '203.0.113.10' },
+ ]),
+ );
+ const resolver = new AuthoritativeResolver({
+ udpTransport,
+ rootServers: async () => ['192.0.2.1'],
+ });
+
+ await expect(
+ resolver.resolveRecordType('example.com', 'A'),
+ ).resolves.toEqual(
+ expect.objectContaining({
+ records: [expect.objectContaining({ data: '203.0.113.10' })],
+ }),
+ );
+ });
+
+ it('stops trying fallback nameservers once the deadline is spent', async () => {
+ const udpTransport = vi.fn<AuthoritativeUdpTransport>(
+ async ({ domain, recordType }) =>
+ response(domain, recordType, 'SERVFAIL'),
+ );
+ const resolver = new AuthoritativeResolver({
+ udpTransport,
+ rootServers: async () => ['192.0.2.1', '192.0.2.2', '192.0.2.3'],
+ fallbackDeadlineMs: 0,
+ });
+
+ await expect(
+ resolver.resolveRecordType('example.com', 'A'),
+ ).rejects.toBeInstanceOf(UserFacingError);
+ // Deadline of 0: only the first candidate is attempted.
+ expect(
+ new Set(udpTransport.mock.calls.map(([request]) => request.nameserver)),
+ ).toEqual(new Set(['192.0.2.1']));
+ });
+
+ it('surfaces all-SERVFAIL RRSIG queries as retryable failures', async () => {
+ // The all-REFUSED tolerance is rcode-specific: SERVFAIL means the servers
+ // are broken, not that they decline RRSIG browsing by policy.
+ const udpTransport = vi.fn<AuthoritativeUdpTransport>(
+ async ({ domain, recordType }) =>
+ response(domain, recordType, 'SERVFAIL'),
+ );
+ const resolver = new AuthoritativeResolver({
+ udpTransport,
+ rootServers: async () => ['192.0.2.1', '192.0.2.2'],
+ });
+
+ await expect(
+ resolver.resolveRecordType('example.com', 'RRSIG'),
+ ).rejects.toBeInstanceOf(UserFacingError);
+ });
+
+ it('skips a non-authoritative response whose answers are all unrelated', async () => {
+ const udpTransport = vi.fn<AuthoritativeUdpTransport>(
+ async ({ domain, recordType, nameserver }) =>
+ nameserver === '192.0.2.1'
+ ? // Unrelated answer, not authoritative, no referral: as lame as an
+ // empty response -- it must not read as NODATA.
+ response(domain, recordType, 'NOERROR', [
+ {
+ name: 'unrelated.example.net',
+ type: 'A',
+ ttl: 300,
+ data: '8.8.8.8',
+ },
+ ])
+ : ({
+ ...response(domain, recordType, 'NOERROR', [
+ { name: domain, type: 'A', ttl: 300, data: '203.0.113.10' },
+ ]),
+ flag_aa: true,
+ } as DecodedPacket),
+ );
+ const resolver = new AuthoritativeResolver({
+ udpTransport,
+ rootServers: async () => ['192.0.2.1', '192.0.2.2'],
+ });
+
+ await expect(
+ resolver.resolveRecordType('example.com', 'A'),
+ ).resolves.toEqual(
+ expect.objectContaining({
+ records: [expect.objectContaining({ data: '203.0.113.10' })],
+ }),
+ );
+ });
+
+ it('treats a non-authoritative reply whose only redirect is a stray A as lame', async () => {
+ // An A record in additionals without any NS delegates nothing; accepting
+ // the reply would dead-end in "Bad redirects" instead of trying siblings.
+ const udpTransport = vi.fn<AuthoritativeUdpTransport>(
+ async ({ domain, recordType, nameserver }) =>
+ nameserver === '192.0.2.1'
+ ? ({
+ ...response(domain, recordType, 'NOERROR'),
+ additionals: [
+ {
+ name: 'unrelated.example.net',
+ type: 'A',
+ ttl: 300,
+ data: '8.8.8.8',
+ },
+ ],
+ } as DecodedPacket)
+ : ({
+ ...response(domain, recordType, 'NOERROR', [
+ { name: domain, type: 'A', ttl: 300, data: '203.0.113.10' },
+ ]),
+ flag_aa: true,
+ } as DecodedPacket),
+ );
+ const resolver = new AuthoritativeResolver({
+ udpTransport,
+ rootServers: async () => ['192.0.2.1', '192.0.2.2'],
+ });
+
+ await expect(
+ resolver.resolveRecordType('example.com', 'A'),
+ ).resolves.toEqual(
+ expect.objectContaining({
+ records: [expect.objectContaining({ data: '203.0.113.10' })],
+ }),
+ );
+ });
+
+ it('treats an upward referral as lame and tries the sibling', async () => {
+ // Classic lame-delegation symptom: a misconfigured server "refers" the
+ // query back to the root instead of answering for its zone.
+ const udpTransport = vi.fn<AuthoritativeUdpTransport>(
+ async ({ domain, recordType, nameserver }) =>
+ nameserver === '192.0.2.1'
+ ? ({
+ ...response(domain, recordType, 'NOERROR'),
+ authorities: [
+ { name: '.', type: 'NS', ttl: 300, data: 'a.root-servers.net' },
+ ],
+ } as DecodedPacket)
+ : ({
+ ...response(domain, recordType, 'NOERROR', [
+ { name: domain, type: 'A', ttl: 300, data: '203.0.113.10' },
+ ]),
+ flag_aa: true,
+ } as DecodedPacket),
+ );
+ const resolver = new AuthoritativeResolver({
+ udpTransport,
+ rootServers: async () => ['192.0.2.1', '192.0.2.2'],
+ });
+
+ await expect(
+ resolver.resolveRecordType('example.com', 'A'),
+ ).resolves.toEqual(
+ expect.objectContaining({
+ records: [expect.objectContaining({ data: '203.0.113.10' })],
+ }),
+ );
+ });
+
+ it('classifies a non-AA reply with only an out-of-bailiwick delegation as lame', async () => {
+ // No in-bailiwick NS, so this is not a referral we can follow; it is lame
+ // and the sibling is tried. (The glue for the foreign zone must never be
+ // contacted.)
+ const udpTransport = vi.fn<AuthoritativeUdpTransport>(
+ async ({ domain, recordType, nameserver }) =>
+ nameserver === '192.0.2.1'
+ ? ({
+ ...response(domain, recordType, 'NOERROR'),
+ authorities: [
+ { name: 'evil.org', type: 'NS', ttl: 300, data: 'ns.evil.org' },
+ ],
+ additionals: [
+ { name: 'ns.evil.org', type: 'A', ttl: 300, data: '6.6.6.6' },
+ ],
+ } as DecodedPacket)
+ : ({
+ ...response(domain, recordType, 'NOERROR', [
+ { name: domain, type: 'A', ttl: 300, data: '203.0.113.10' },
+ ]),
+ flag_aa: true,
+ } as DecodedPacket),
+ );
+ const resolver = new AuthoritativeResolver({
+ udpTransport,
+ rootServers: async () => ['192.0.2.1', '192.0.2.2'],
+ });
+
+ const result = await resolver.resolveRecordType('example.com', 'A');
+
+ expect(result.records[0]?.data).toBe('203.0.113.10');
+ expect(
+ udpTransport.mock.calls.map(([request]) => request.nameserver),
+ ).not.toContain('6.6.6.6');
+ });
+
+ it('follows only in-bailiwick public glue from a mixed referral', async () => {
+ // An accepted referral (in-bailiwick NS present) that also carries an
+ // out-of-bailiwick delegation, its glue, and a private-IP glue for the
+ // real NS. The walk must follow only 8.8.8.8 and touch none of the traps.
+ const udpTransport = vi.fn<AuthoritativeUdpTransport>(
+ async ({ domain, recordType, nameserver }) =>
+ nameserver === '192.0.2.1'
+ ? ({
+ ...response(domain, recordType, 'NOERROR'),
+ authorities: [
+ {
+ name: 'example.com',
+ type: 'NS',
+ ttl: 300,
+ data: 'ns1.example.net',
+ },
+ { name: 'evil.org', type: 'NS', ttl: 300, data: 'ns.evil.org' },
+ ],
+ // Traps first: if a filter regressed, the recursive walk would
+ // contact the trap before 8.8.8.8 (the mock answers from any
+ // server) and trip the not.toContain assertions. With 8.8.8.8
+ // ordered first the test would pass on loop order alone.
+ additionals: [
+ {
+ name: 'ns1.example.net',
+ type: 'A',
+ ttl: 300,
+ data: '10.0.0.1',
+ },
+ { name: 'ns.evil.org', type: 'A', ttl: 300, data: '6.6.6.6' },
+ {
+ name: 'ns1.example.net',
+ type: 'A',
+ ttl: 300,
+ data: '8.8.8.8',
+ },
+ ],
+ } as DecodedPacket)
+ : ({
+ ...response(domain, recordType, 'NOERROR', [
+ { name: domain, type: 'A', ttl: 300, data: '203.0.113.10' },
+ ]),
+ flag_aa: true,
+ } as DecodedPacket),
+ );
+ const resolver = new AuthoritativeResolver({
+ udpTransport,
+ rootServers: async () => ['192.0.2.1'],
+ });
+
+ const result = await resolver.resolveRecordType('www.example.com', 'A');
+
+ expect(result.records[0]?.data).toBe('203.0.113.10');
+ const contacted = udpTransport.mock.calls.map(
+ ([request]) => request.nameserver,
+ );
+ expect(contacted).toContain('8.8.8.8');
+ expect(contacted).not.toContain('10.0.0.1');
+ expect(contacted).not.toContain('6.6.6.6');
+ });
+
+ it('rejects a glueless NS that resolves to a private IP', async () => {
+ // SSRF guard: the delegated NS hostname is attacker-controlled and here
+ // resolves to an RFC1918 address; the resolver must never send to it.
+ const udpTransport = vi.fn<AuthoritativeUdpTransport>(async (request) => {
+ const { domain, recordType, nameserver } = request;
+ if (domain === 'ns.example.net') {
+ return response(domain, recordType, 'NOERROR', [
+ { name: domain, type: 'A', ttl: 300, data: '10.0.0.1' },
+ ]);
+ }
+ if (nameserver === '192.0.2.1') {
+ return {
+ ...response(domain, recordType, 'NOERROR'),
+ authorities: [
+ {
+ name: 'example.com',
+ type: 'NS',
+ ttl: 300,
+ data: 'ns.example.net',
+ },
+ ],
+ } as DecodedPacket;
+ }
+ return response(domain, recordType, 'SERVFAIL');
+ });
+ const resolver = new AuthoritativeResolver({
+ udpTransport,
+ rootServers: async () => ['192.0.2.1'],
+ });
+
+ await expect(
+ resolver.resolveRecordType('www.example.com', 'A'),
+ ).rejects.toThrow();
+ expect(
+ udpTransport.mock.calls.map(([request]) => request.nameserver),
+ ).not.toContain('10.0.0.1');
+ });
+
+ it('tries a healthy sibling when a candidate referral fails to resolve', async () => {
+ // The first root hands out a referral whose only nameserver is dead. That
+ // must not abort the lookup -- the sibling root answers authoritatively.
+ const udpTransport = vi.fn<AuthoritativeUdpTransport>(
+ async ({ domain, recordType, nameserver }) => {
+ if (nameserver === '192.0.2.1') {
+ return {
+ ...response(domain, recordType, 'NOERROR'),
+ authorities: [
+ {
+ name: 'example.com',
+ type: 'NS',
+ ttl: 300,
+ data: 'ns1.example.net',
+ },
+ ],
+ additionals: [
+ { name: 'ns1.example.net', type: 'A', ttl: 300, data: '8.8.8.8' },
+ ],
+ } as DecodedPacket;
+ }
+ if (nameserver === '8.8.8.8') {
+ return response(domain, recordType, 'SERVFAIL');
+ }
+ // 192.0.2.2, the healthy sibling root.
+ return {
+ ...response(domain, recordType, 'NOERROR', [
+ { name: domain, type: 'A', ttl: 300, data: '203.0.113.10' },
+ ]),
+ flag_aa: true,
+ } as DecodedPacket;
+ },
+ );
+ const resolver = new AuthoritativeResolver({
+ udpTransport,
+ rootServers: async () => ['192.0.2.1', '192.0.2.2'],
+ });
+
+ const result = await resolver.resolveRecordType('www.example.com', 'A');
+
+ expect(result.records[0]?.data).toBe('203.0.113.10');
+ expect(
+ udpTransport.mock.calls.map(([request]) => request.nameserver),
+ ).toContain('192.0.2.2');
+ });
+
+ it('falls back to a deferred answer when a later referral fails', async () => {
+ // First root: a non-authoritative answer (deferred). Second root: an
+ // in-bailiwick referral that then fails. The deferred answer must win
+ // over failing the lookup.
+ const udpTransport = vi.fn<AuthoritativeUdpTransport>(
+ async ({ domain, recordType, nameserver }) => {
+ if (nameserver === '192.0.2.1') {
+ return response(domain, recordType, 'NOERROR', [
+ { name: domain, type: 'A', ttl: 300, data: '203.0.113.10' },
+ ]);
+ }
+ if (nameserver === '192.0.2.2') {
+ return {
+ ...response(domain, recordType, 'NOERROR'),
+ authorities: [
+ {
+ name: 'example.com',
+ type: 'NS',
+ ttl: 300,
+ data: 'ns1.example.net',
+ },
+ ],
+ additionals: [
+ { name: 'ns1.example.net', type: 'A', ttl: 300, data: '8.8.8.8' },
+ ],
+ } as DecodedPacket;
+ }
+ // 8.8.8.8, the dead delegated server.
+ return response(domain, recordType, 'SERVFAIL');
+ },
+ );
+ const resolver = new AuthoritativeResolver({
+ udpTransport,
+ rootServers: async () => ['192.0.2.1', '192.0.2.2'],
+ });
+
+ const result = await resolver.resolveRecordType('www.example.com', 'A');
+
+ expect(result.records[0]?.data).toBe('203.0.113.10');
+ });
+
+ it('dedupes duplicate glue so a distinct healthy address survives the cap', async () => {
+ // Four colocated NS hostnames share one dead IP; a fifth carries a
+ // healthy address. Without dedup the cap of 4 retains only duplicates
+ // and drops the healthy one.
+ const udpTransport = vi.fn<AuthoritativeUdpTransport>(
+ async ({ domain, recordType, nameserver }) => {
+ if (nameserver === '192.0.2.1') {
+ return {
+ ...response(domain, recordType, 'NOERROR'),
+ authorities: [1, 2, 3, 4, 5].map((i) => ({
+ name: 'example.com',
+ type: 'NS',
+ ttl: 300,
+ data: `ns${i}.example.net`,
+ })),
+ additionals: [
+ { name: 'ns1.example.net', type: 'A', ttl: 300, data: '9.9.9.9' },
+ { name: 'ns2.example.net', type: 'A', ttl: 300, data: '9.9.9.9' },
+ { name: 'ns3.example.net', type: 'A', ttl: 300, data: '9.9.9.9' },
+ { name: 'ns4.example.net', type: 'A', ttl: 300, data: '9.9.9.9' },
+ { name: 'ns5.example.net', type: 'A', ttl: 300, data: '8.8.8.8' },
+ ],
+ } as DecodedPacket;
+ }
+ if (nameserver === '9.9.9.9') {
+ return response(domain, recordType, 'SERVFAIL');
+ }
+ // 8.8.8.8, the distinct healthy server.
+ return {
+ ...response(domain, recordType, 'NOERROR', [
+ { name: domain, type: 'A', ttl: 300, data: '203.0.113.10' },
+ ]),
+ flag_aa: true,
+ } as DecodedPacket;
+ },
+ );
+ const resolver = new AuthoritativeResolver({
+ udpTransport,
+ rootServers: async () => ['192.0.2.1'],
+ });
+
+ const result = await resolver.resolveRecordType('www.example.com', 'A');
+
+ expect(result.records[0]?.data).toBe('203.0.113.10');
+ expect(
+ udpTransport.mock.calls.map(([request]) => request.nameserver),
+ ).toContain('8.8.8.8');
+ });
+
+ it('retries with sibling nameservers that resolved after the race', async () => {
+ const udpTransport = vi.fn<AuthoritativeUdpTransport>(async (request) => {
+ const { domain, recordType, nameserver } = request;
+ if (domain === 'ns-fast.example.net') {
+ return response(domain, recordType, 'NOERROR', [
+ { name: domain, type: 'A', ttl: 300, data: '8.8.8.8' },
+ ]);
+ }
+ if (domain === 'ns-slow.example.net') {
+ await new Promise((resolveSleep) => setTimeout(resolveSleep, 50));
+ return response(domain, recordType, 'NOERROR', [
+ { name: domain, type: 'A', ttl: 300, data: '9.9.9.9' },
+ ]);
+ }
+ if (nameserver === '192.0.2.1') {
+ return {
+ ...response(domain, recordType, 'NOERROR'),
+ authorities: [
+ {
+ name: 'example.com',
+ type: 'NS',
+ ttl: 300,
+ data: 'ns-fast.example.net',
+ },
+ {
+ name: 'example.com',
+ type: 'NS',
+ ttl: 300,
+ data: 'ns-slow.example.net',
+ },
+ ],
+ } as DecodedPacket;
+ }
+ if (nameserver === '8.8.8.8') {
+ // The winner's server fails instantly, while the sibling NS lookup
+ // is still in flight -- the retry must wait for it.
+ return response(domain, recordType, 'SERVFAIL');
+ }
+ return {
+ ...response(domain, recordType, 'NOERROR', [
+ { name: domain, type: 'A', ttl: 300, data: '203.0.113.14' },
+ ]),
+ flag_aa: true,
+ } as DecodedPacket;
+ });
+ const resolver = new AuthoritativeResolver({
+ udpTransport,
+ rootServers: async () => ['192.0.2.1'],
+ });
+
+ const result = await resolver.resolveRecordType('www.example.com', 'A');
+
+ expect(result.records[0]?.data).toBe('203.0.113.14');
+ });
+
+ it('bounds total queries against a zone that forks glueless delegations', async () => {
+ // A crafted zone can answer every glueless delegation with four fresh NS
+ // names; without a walk-wide query budget the tree grows 4^depth.
+ let seq = 0;
+ const udpTransport = vi.fn<AuthoritativeUdpTransport>(
+ async ({ domain, recordType }) =>
+ ({
+ ...response(domain, recordType, 'NOERROR'),
+ authorities: [1, 2, 3, 4].map((i) => ({
+ name: domain,
+ type: 'NS',
+ ttl: 300,
+ data: `ns${i}-${seq++}.example.net`,
+ })),
+ }) as DecodedPacket,
+ );
+ const resolver = new AuthoritativeResolver({
+ udpTransport,
+ rootServers: async () => ['192.0.2.1'],
+ });
+
+ await expect(
+ resolver.resolveRecordType('www.example.com', 'A'),
+ ).rejects.toBeInstanceOf(Error);
+ expect(udpTransport.mock.calls.length).toBeLessThanOrEqual(50);
+ });
+
+ it('prefers an authoritative sibling over a non-authoritative answer', async () => {
+ // An open recursive listed in the NS set answers without AA; its data
+ // must not mask the healthy authoritative sibling.
+ const udpTransport = vi.fn<AuthoritativeUdpTransport>(
+ async ({ domain, recordType, nameserver }) =>
+ nameserver === '192.0.2.1'
+ ? response(domain, recordType, 'NOERROR', [
+ { name: domain, type: 'A', ttl: 300, data: '198.51.100.99' },
+ ])
+ : ({
+ ...response(domain, recordType, 'NOERROR', [
+ { name: domain, type: 'A', ttl: 300, data: '203.0.113.10' },
+ ]),
+ flag_aa: true,
+ } as DecodedPacket),
+ );
+ const resolver = new AuthoritativeResolver({
+ udpTransport,
+ rootServers: async () => ['192.0.2.1', '192.0.2.2'],
+ });
+
+ await expect(
+ resolver.resolveRecordType('example.com', 'A'),
+ ).resolves.toEqual(
+ expect.objectContaining({
+ records: [expect.objectContaining({ data: '203.0.113.10' })],
+ }),
+ );
+ expect(
+ udpTransport.mock.calls.map(([request]) => request.nameserver),
+ ).toEqual(['192.0.2.1', '192.0.2.2']);
+ });
+
+ it('falls back to a non-authoritative answer when no candidate does better', async () => {
+ const udpTransport = vi.fn<AuthoritativeUdpTransport>(
+ async ({ domain, recordType, nameserver }) =>
+ nameserver === '192.0.2.1'
+ ? response(domain, recordType, 'NOERROR', [
+ { name: domain, type: 'A', ttl: 300, data: '203.0.113.10' },
+ ])
+ : response(domain, recordType, 'SERVFAIL'),
+ );
+ const resolver = new AuthoritativeResolver({
+ udpTransport,
+ rootServers: async () => ['192.0.2.1', '192.0.2.2'],
+ });
+
+ await expect(
+ resolver.resolveRecordType('example.com', 'A'),
+ ).resolves.toEqual(
+ expect.objectContaining({
+ records: [expect.objectContaining({ data: '203.0.113.10' })],
+ }),
+ );
+ });
+
+ it('shares the fallback deadline across referral steps', async () => {
+ const udpTransport = vi.fn<AuthoritativeUdpTransport>(
+ async ({ domain, recordType, nameserver }) => {
+ if (nameserver === '192.0.2.1') {
+ // Slow referral: spends the whole walk deadline before handing out
+ // the two child addresses.
+ await new Promise((resolveSleep) => setTimeout(resolveSleep, 250));
+ return {
+ ...response(domain, recordType, 'NOERROR'),
+ authorities: [
+ {
+ name: 'example.com',
+ type: 'NS',
+ ttl: 300,
+ data: 'ns1.example.net',
+ },
+ ],
+ additionals: [
+ { name: 'ns1.example.net', type: 'A', ttl: 300, data: '8.8.8.8' },
+ { name: 'ns1.example.net', type: 'A', ttl: 300, data: '9.9.9.9' },
+ ],
+ } as DecodedPacket;
+ }
+ return nameserver === '8.8.8.8'
+ ? response(domain, recordType, 'SERVFAIL')
+ : ({
+ ...response(domain, recordType, 'NOERROR', [
+ { name: domain, type: 'A', ttl: 300, data: '203.0.113.10' },
+ ]),
+ flag_aa: true,
+ } as DecodedPacket);
+ },
+ );
+ const resolver = new AuthoritativeResolver({
+ udpTransport,
+ rootServers: async () => ['192.0.2.1'],
+ fallbackDeadlineMs: 100,
+ });
+
+ // A per-step deadline would reset after the referral and reach 9.9.9.9;
+ // the walk-wide deadline must not.
+ await expect(
+ resolver.resolveRecordType('www.example.com', 'A'),
+ ).rejects.toBeInstanceOf(UserFacingError);
+ expect(
+ udpTransport.mock.calls.map(([request]) => request.nameserver),
+ ).not.toContain('9.9.9.9');
+ });
+
+ it('retries a truncated UDP answer over TCP', async () => {
+ const udpTransport = vi.fn<AuthoritativeUdpTransport>(
+ async ({ domain, recordType }) =>
+ ({
+ ...response(domain, recordType, 'NOERROR'),
+ flag_tc: true,
+ }) as DecodedPacket,
+ );
+ const tcpTransport = vi.fn<AuthoritativeTcpTransport>(
+ async ({ domain, recordType }) =>
+ response(domain, recordType, 'NOERROR', [
+ {
+ name: domain,
+ type: 'A',
+ ttl: 300,
+ data: '203.0.113.11',
+ },
+ ]),
+ );
+ const resolver = new AuthoritativeResolver({
+ udpTransport,
+ tcpTransport,
+ rootServers: async () => ['192.0.2.1'],
+ });
+
+ const result = await resolver.resolveRecordType('example.com', 'A');
+
+ expect(result.records[0]?.data).toBe('203.0.113.11');
+ expect(udpTransport).toHaveBeenCalledOnce();
+ expect(tcpTransport).toHaveBeenCalledOnce();
+ });
+
+ it('follows a referral whose answer section holds only unrelated records', async () => {
+ // Some servers promote glue into the answer section; nothing there is
+ // owned by the queried name, so it must be treated as a referral, not
+ // as an authoritative empty answer.
+ const udpTransport = vi.fn<AuthoritativeUdpTransport>(
+ async ({ domain, recordType, nameserver }) =>
+ nameserver === '192.0.2.1'
+ ? ({
+ ...response(domain, recordType, 'NOERROR', [
+ {
+ name: 'ns1.example.net',
+ type: 'A',
+ ttl: 300,
+ data: '8.8.8.8',
+ },
+ ]),
+ authorities: [
+ {
+ name: 'example.com',
+ type: 'NS',
+ ttl: 300,
+ data: 'ns1.example.net',
+ },
+ ],
+ additionals: [
+ {
+ name: 'ns1.example.net',
+ type: 'A',
+ ttl: 300,
+ data: '8.8.8.8',
+ },
+ ],
+ } as DecodedPacket)
+ : response(domain, recordType, 'NOERROR', [
+ { name: domain, type: 'A', ttl: 300, data: '203.0.113.13' },
+ ]),
+ );
+ const resolver = new AuthoritativeResolver({
+ udpTransport,
+ rootServers: async () => ['192.0.2.1'],
+ });
+
+ const result = await resolver.resolveRecordType('www.example.com', 'A');
+
+ expect(result.records[0]?.data).toBe('203.0.113.13');
+ });
+
+ it('follows a glueless referral even when a sibling NS lookup fails', async () => {
+ const udpTransport = vi.fn<AuthoritativeUdpTransport>(async (request) => {
+ const { domain, recordType, nameserver } = request;
+ if (domain === 'ns-dead.example.net') throw new Error('timeout');
+ if (domain === 'ns-live.example.net') {
+ return response(domain, recordType, 'NOERROR', [
+ { name: domain, type: 'A', ttl: 300, data: '8.8.8.8' },
+ ]);
+ }
+ return nameserver === '192.0.2.1'
+ ? ({
+ ...response(domain, recordType, 'NOERROR'),
+ authorities: [
+ {
+ name: 'example.com',
+ type: 'NS',
+ ttl: 300,
+ data: 'ns-dead.example.net',
+ },
+ {
+ name: 'example.com',
+ type: 'NS',
+ ttl: 300,
+ data: 'ns-live.example.net',
+ },
+ ],
+ } as DecodedPacket)
+ : response(domain, recordType, 'NOERROR', [
+ { name: domain, type: 'A', ttl: 300, data: '203.0.113.14' },
+ ]);
+ });
+ const resolver = new AuthoritativeResolver({
+ udpTransport,
+ rootServers: async () => ['192.0.2.1'],
+ });
+
+ const result = await resolver.resolveRecordType('www.example.com', 'A');
+
+ expect(result.records[0]?.data).toBe('203.0.113.14');
+ });
+
+ it('follows matching public glue from a referral', async () => {
+ const udpTransport = vi.fn<AuthoritativeUdpTransport>(
+ async ({ domain, recordType, nameserver }) =>
+ nameserver === '192.0.2.1'
+ ? ({
+ ...response(domain, recordType, 'NOERROR'),
+ authorities: [
+ {
+ name: 'example.com',
+ type: 'NS',
+ ttl: 300,
+ data: 'ns1.example.net',
+ },
+ ],
+ additionals: [
+ {
+ name: 'ns1.example.net',
+ type: 'A',
+ ttl: 300,
+ data: '8.8.8.8',
+ },
+ ],
+ } as DecodedPacket)
+ : response(domain, recordType, 'NOERROR', [
+ {
+ name: domain,
+ type: 'A',
+ ttl: 300,
+ data: '203.0.113.12',
+ },
+ ]),
+ );
+ const resolver = new AuthoritativeResolver({
+ udpTransport,
+ rootServers: async () => ['192.0.2.1'],
+ });
+
+ const result = await resolver.resolveRecordType('www.example.com', 'A');
+
+ expect(result.records[0]?.data).toBe('203.0.113.12');
+ expect(
+ udpTransport.mock.calls.map(([request]) => request.nameserver),
+ ).toEqual(['192.0.2.1', '8.8.8.8']);
+ });
+});
+
+describe('AuthoritativeResolver delegation cache', () => {
+ const referral = (
+ domain: string,
+ recordType: RecordType,
+ glueIp: string,
+ ): DecodedPacket =>
+ ({
+ ...response(domain, recordType, 'NOERROR'),
+ authorities: [
+ { name: 'example.com', type: 'NS', ttl: 300, data: 'ns1.example.net' },
+ ],
+ additionals: [
+ { name: 'ns1.example.net', type: 'A', ttl: 300, data: glueIp },
+ ],
+ }) as DecodedPacket;
+
+ it('starts later lookups at a cached delegation instead of the root', async () => {
+ const udpTransport = vi.fn<AuthoritativeUdpTransport>(
+ async ({ domain, recordType, nameserver }) =>
+ nameserver === '192.0.2.1'
+ ? referral(domain, recordType, '8.8.8.8')
+ : ({
+ ...response(domain, recordType, 'NOERROR', [
+ {
+ name: domain,
+ type: recordType,
+ ttl: 300,
+ data: recordType === 'A' ? '203.0.113.10' : '2001:db8::1',
+ } as Answer,
+ ]),
+ flag_aa: true,
+ } as DecodedPacket),
+ );
+ const resolver = new AuthoritativeResolver({
+ udpTransport,
+ rootServers: async () => ['192.0.2.1'],
+ });
+
+ await resolver.resolveRecordType('www.example.com', 'A');
+ const result = await resolver.resolveRecordType('www.example.com', 'AAAA');
+
+ expect(result.records[0]?.data).toBe('2001:db8::1');
+ expect(
+ udpTransport.mock.calls.filter(
+ ([request]) => request.nameserver === '192.0.2.1',
+ ),
+ ).toHaveLength(1);
+ });
+
+ it('re-walks from the root when every cached delegation server fails', async () => {
+ let referrals = 0;
+ const udpTransport = vi.fn<AuthoritativeUdpTransport>(
+ async ({ domain, recordType, nameserver }) => {
+ if (nameserver === '192.0.2.1') {
+ referrals += 1;
+ // The delegation moved between the two lookups: the re-walk finds
+ // a different (healthy) nameserver.
+ return referral(
+ domain,
+ recordType,
+ referrals === 1 ? '8.8.8.8' : '9.9.9.9',
+ );
+ }
+ if (nameserver === '8.8.8.8') {
+ return recordType === 'A'
+ ? ({
+ ...response(domain, recordType, 'NOERROR', [
+ { name: domain, type: 'A', ttl: 300, data: '203.0.113.10' },
+ ]),
+ flag_aa: true,
+ } as DecodedPacket)
+ : response(domain, recordType, 'SERVFAIL');
+ }
+ return {
+ ...response(domain, recordType, 'NOERROR', [
+ { name: domain, type: 'AAAA', ttl: 300, data: '2001:db8::1' },
+ ]),
+ flag_aa: true,
+ } as DecodedPacket;
+ },
+ );
+ const resolver = new AuthoritativeResolver({
+ udpTransport,
+ rootServers: async () => ['192.0.2.1'],
+ });
+
+ await resolver.resolveRecordType('www.example.com', 'A');
+ const result = await resolver.resolveRecordType('www.example.com', 'AAAA');
+
+ expect(result.records[0]?.data).toBe('2001:db8::1');
+ expect(referrals).toBe(2);
+ });
+
+ it('re-walks past a cached server that answers without authority', async () => {
+ // A cached delegation whose server has gone non-authoritative (a moved
+ // delegation, or a shared recursor that still answers) must not have its
+ // stale, non-AA answer adopted -- the fresh root walk finds the healthy
+ // server, and that must win over the deferred lastResort answer.
+ let rootReferrals = 0;
+ const udpTransport = vi.fn<AuthoritativeUdpTransport>(
+ async ({ domain, recordType, nameserver }) => {
+ if (nameserver === '192.0.2.1') {
+ rootReferrals += 1;
+ const [nsName, glue] =
+ rootReferrals === 1
+ ? ['ns1.example.net', '8.8.8.8']
+ : ['ns2.example.net', '9.9.9.9'];
+ return {
+ ...response(domain, recordType, 'NOERROR'),
+ authorities: [
+ { name: 'example.com', type: 'NS', ttl: 300, data: nsName },
+ ],
+ additionals: [{ name: nsName, type: 'A', ttl: 300, data: glue }],
+ } as DecodedPacket;
+ }
+ if (nameserver === '8.8.8.8') {
+ return recordType === 'A'
+ ? ({
+ ...response(domain, recordType, 'NOERROR', [
+ { name: domain, type: 'A', ttl: 300, data: '203.0.113.10' },
+ ]),
+ flag_aa: true,
+ } as DecodedPacket)
+ : // Non-authoritative, stale MX -- deferred as lastResort.
+ response(domain, recordType, 'NOERROR', [
+ {
+ name: domain,
+ type: 'MX',
+ ttl: 300,
+ data: { preference: 10, exchange: 'stale.example.com' },
+ },
+ ]);
+ }
+ // 9.9.9.9: the current authoritative server the re-walk discovers.
+ return {
+ ...response(domain, recordType, 'NOERROR', [
+ {
+ name: domain,
+ type: 'MX',
+ ttl: 300,
+ data: { preference: 20, exchange: 'fresh.example.com' },
+ },
+ ]),
+ flag_aa: true,
+ } as DecodedPacket;
+ },
+ );
+ const resolver = new AuthoritativeResolver({
+ udpTransport,
+ rootServers: async () => ['192.0.2.1'],
+ });
+
+ await resolver.resolveRecordType('www.example.com', 'A');
+ const result = await resolver.resolveRecordType('www.example.com', 'MX');
+
+ expect(result.records[0]?.data).toBe('20 fresh.example.com');
+ });
+});
+
+describe('isMatchingDnsResponse', () => {
+ const packet = response('example.com', 'A', 'NOERROR');
+
+ it('requires the transaction ID and question to match', () => {
+ expect(isMatchingDnsResponse(packet, 42, 'example.com', 'A')).toBe(true);
+ expect(isMatchingDnsResponse(packet, 43, 'example.com', 'A')).toBe(false);
+ expect(isMatchingDnsResponse(packet, 42, 'other.example', 'A')).toBe(false);
+ expect(isMatchingDnsResponse(packet, 42, 'example.com', 'AAAA')).toBe(
+ false,
+ );
+ });
+});
diff --git a/lib/resolvers/authoritative.ts b/lib/resolvers/authoritative.ts
index a29be14..6147ce9 100644
--- a/lib/resolvers/authoritative.ts
+++ b/lib/resolvers/authoritative.ts
@@ -21,24 +21,147 @@ import {
} from './base';
import { isPublicIp } from './ip-filter';
+type RawAnswer = Extract<Answer, { type: RecordType }>;
+
+const canonicalDnsName = (name: string): string =>
+ name.replace(/\.$/, '').toLowerCase();
+
+// A legitimate referral delegates a zone the queried name lives under.
+// Anything else -- an upward referral to the root ('' is never a match) or
+// NS records for a foreign zone -- must not steer the walk.
+const isInBailiwick = (wantName: string, zone: string): boolean =>
+ wantName === zone || wantName.endsWith(`.${zone}`);
+
+type CandidateVerdict =
+ | { kind: 'rcode-error'; rcode: string }
+ | { kind: 'deferred' } // non-authoritative, but owns the queried name
+ | { kind: 'lame' } // non-authoritative, no owned answer, no referral
+ | { kind: 'usable' }; // authoritative, or an in-bailiwick referral to follow
+
+// Classify a candidate nameserver's response, without touching walk state.
+// A non-authoritative response can't end the walk (RFC 2308 negative answers
+// and real data come from the AA server); accepting one would let a single
+// misconfigured candidate mask healthy siblings. One that still owns the
+// queried name -- e.g. an open recursive listed in the NS set -- is deferred
+// as a last resort: worse than a real answer, better than failing the lookup.
+// One with neither owned answers nor an in-bailiwick NS referral is simply
+// lame (a stray A in additionals delegates nothing and is not a referral).
+const classifyCandidateResponse = (
+ packet: Packet,
+ wantName: string,
+): CandidateVerdict => {
+ const rcode = packet.rcode;
+ if (rcode !== undefined && rcode !== 'NOERROR' && rcode !== 'NXDOMAIN') {
+ return { kind: 'rcode-error', rcode };
+ }
+ // flag_aa only exists on decoded packets; encode-side Packet lacks it.
+ if ((packet as DecodedPacket).flag_aa) return { kind: 'usable' };
+ const ownsAnswer = packet.answers?.some(
+ (answer) => canonicalDnsName(answer.name) === wantName,
+ );
+ if (ownsAnswer) return { kind: 'deferred' };
+ const hasReferral = [
+ ...(packet.authorities ?? []),
+ ...(packet.additionals ?? []),
+ ].some(
+ (record) =>
+ record.type === 'NS' &&
+ isInBailiwick(wantName, canonicalDnsName(record.name)),
+ );
+ return hasReferral ? { kind: 'usable' } : { kind: 'lame' };
+};
+
type DnsResponse = {
packet: Packet;
protocol: 'udp' | 'tcp';
truncated: boolean;
};
+export type AuthoritativeRequest = {
+ domain: string;
+ recordType: RecordType;
+ nameserver: string;
+};
+
+export type AuthoritativeUdpTransport = (
+ request: AuthoritativeRequest,
+) => Promise<DecodedPacket>;
+
+export type AuthoritativeTcpTransport = (
+ request: AuthoritativeRequest,
+) => Promise<Packet>;
+
+export type AuthoritativeResolverOptions = {
+ udpTransport?: AuthoritativeUdpTransport;
+ tcpTransport?: AuthoritativeTcpTransport;
+ rootServers?: () => Promise<string[]>;
+ // Time budget for trying fallback nameservers, shared across the whole
+ // walk (see fetchRecordsRaw). Injectable for tests.
+ fallbackDeadlineMs?: number;
+};
+
+export const isMatchingDnsResponse = (
+ packet: Packet,
+ id: number,
+ domain: string,
+ recordType: RecordType,
+): boolean =>
+ packet.type === 'response' &&
+ packet.id === id &&
+ Boolean(
+ packet.questions?.some(
+ (question) =>
+ question.type === recordType &&
+ canonicalDnsName(question.name) === canonicalDnsName(domain),
+ ),
+ );
+
type FetchRecordsParams = {
domain: string;
recordType: RecordType;
- nameserver?: string;
+ nameservers?: string[];
trace?: string[];
depth?: number;
+ deadlineAt?: number;
+ budget?: { remaining: number };
};
export class AuthoritativeResolver extends DnsResolver {
private static readonly MAX_RECURSION_DEPTH = 20;
+ // Caps candidate nameserver attempts for one walk, like BIND's
+ // max-recursion-queries: the depth cap alone still lets a crafted zone
+ // answer every glueless delegation with 4 fresh NS names and fork
+ // 4^depth sub-walks. One attempt costs up to 4 UDP tries plus a TCP
+ // fallback each (see requestLoader/sendRequest), so this also caps the
+ // walk's packet ceiling at ~8x this value. Far above any honest
+ // lookup's needs (a deep all-glueless walk stays under ~30).
+ private static readonly MAX_CANDIDATES_PER_WALK = 50;
+ // Must exceed one candidate's full retry budget (4 attempts x 3s = ~12s):
+ // a single blackholed first server has to leave room to reach a healthy
+ // fallback, while all-blackholed candidates stay bounded (~2 budgets).
+ private static readonly FALLBACK_DEADLINE_MS = 15_000;
+
+ public constructor(
+ private readonly options: AuthoritativeResolverOptions = {},
+ ) {
+ super();
+ }
- private async getRootServers() {
+ // One fetch+parse of the root hints per resolver instance; the walk calls
+ // getRootServers on every recursion step. A failed attempt is not cached.
+ private rootServersPromise?: Promise<string[]>;
+
+ private getRootServers(): Promise<string[]> {
+ const loadRootServers =
+ this.options.rootServers ?? (() => this.fetchRootServers());
+ this.rootServersPromise ??= loadRootServers().catch((error) => {
+ this.rootServersPromise = undefined;
+ throw error;
+ });
+ return this.rootServersPromise;
+ }
+
+ private async fetchRootServers() {
let response: Response;
try {
response = await fetch('https://www.internic.net/domain/named.root', {
@@ -141,15 +264,16 @@ export class AuthoritativeResolver extends DnsResolver {
}
}
- private async sendUdpRequest(
- domain: string,
- recordType: RecordType,
- nameserver: string,
- ) {
+ private async sendUdpRequest({
+ domain,
+ recordType,
+ nameserver,
+ }: AuthoritativeRequest) {
+ const id = Math.floor(Math.random() * 65535);
const packetBuffer = dnsPacket.encode({
type: 'query',
// Randomize ID to avoid response mismatch
- id: Math.floor(Math.random() * 65535),
+ id,
questions: [{ type: recordType, name: domain } as Question],
});
@@ -173,9 +297,17 @@ export class AuthoritativeResolver extends DnsResolver {
);
}, 3000);
- socket.on('message', (message: Buffer) => {
+ socket.on('message', (message: Buffer, remote) => {
+ if (remote.address !== nameserver || remote.port !== 53) return;
+ let packet: DecodedPacket;
+ try {
+ packet = dnsPacket.decode(message);
+ } catch {
+ return;
+ }
+ if (!isMatchingDnsResponse(packet, id, domain, recordType)) return;
cleanup();
- resolve(dnsPacket.decode(message));
+ resolve(packet);
});
socket.on('error', (error) => {
cleanup();
@@ -186,14 +318,15 @@ export class AuthoritativeResolver extends DnsResolver {
});
}
- private async sendTcpRequest(
- domain: string,
- recordType: RecordType,
- nameserver: string,
- ) {
+ private async sendTcpRequest({
+ domain,
+ recordType,
+ nameserver,
+ }: AuthoritativeRequest) {
+ const id = Math.floor(Math.random() * 65535);
const packetBuffer = dnsPacket.streamEncode({
type: 'query',
- id: Math.floor(Math.random() * 65535),
+ id,
questions: [{ type: recordType, name: domain } as Question],
});
@@ -227,8 +360,14 @@ export class AuthoritativeResolver extends DnsResolver {
if (buf.length >= 2) {
const msgLen = buf.readUInt16BE(0);
if (buf.length >= 2 + msgLen) {
+ const packet = dnsPacket.streamDecode(buf);
+ if (!isMatchingDnsResponse(packet, id, domain, recordType)) {
+ cleanup();
+ reject(new Error('DNS response did not match the TCP query'));
+ return;
+ }
cleanup();
- resolve(dnsPacket.streamDecode(buf));
+ resolve(packet);
}
}
});
@@ -240,179 +379,559 @@ export class AuthoritativeResolver extends DnsResolver {
}
private async sendRequest(
- domain: string,
- recordType: RecordType,
- nameserver: string,
- ) {
+ request: AuthoritativeRequest,
+ ): Promise<DnsResponse> {
// DNS queries are first attempted over UDP per convention. However, UDP
// responses are limited to 512 bytes (RFC 1035). When the answer exceeds
// that limit the server truncates the response and sets the TC flag,
// signaling the client to retry over TCP where the full response (up to
// 64 KB) can be delivered.
- const udpResponse = await this.sendUdpRequest(
- domain,
- recordType,
- nameserver,
- );
+ const udpResponse = this.options.udpTransport
+ ? await this.options.udpTransport(request)
+ : await this.sendUdpRequest(request);
if (udpResponse.flag_tc) {
- const packet = await this.sendTcpRequest(domain, recordType, nameserver);
+ const packet = this.options.tcpTransport
+ ? await this.options.tcpTransport(request)
+ : await this.sendTcpRequest(request);
return { packet, protocol: 'tcp', truncated: true };
}
return { packet: udpResponse, protocol: 'udp', truncated: false };
}
private requestLoader = new DataLoader<
- {
- domain: string;
- type: RecordType;
- nameserver: string;
- },
+ AuthoritativeRequest,
DnsResponse,
string
>(
async (keys) =>
Promise.all(
- keys.map(async ({ domain, type, nameserver }) =>
- retry(() => this.sendRequest(domain, type, nameserver), 3),
- ),
+ keys.map(async (request) => {
+ try {
+ return await retry(() => this.sendRequest(request), 3);
+ } catch (error) {
+ return error instanceof Error
+ ? error
+ : new Error('DNS request failed');
+ }
+ }),
),
{
cacheKeyFn: (key) => JSON.stringify(key),
},
);
- private async fetchRecords({
+ // Zone cut -> public nameserver IPs learned from referrals during this
+ // instance's walks. Later queries for names under an already-discovered zone
+ // start there instead of re-walking from the root -- the DataLoader can't
+ // dedupe those shared hops because its key includes the final query name.
+ // First writer wins and only suffixes of the queried name are cached, so a
+ // deeper (less-trusted) server can't overwrite entries learned from the
+ // servers above it.
+ private delegationCache = new Map<string, string[]>();
+
+ private cacheDelegation(zoneCut: string, domain: string, ips: string[]) {
+ const zone = canonicalDnsName(zoneCut);
+ const name = canonicalDnsName(domain);
+ if (this.delegationCache.has(zone)) return;
+ if (name !== zone && !name.endsWith(`.${zone}`)) return;
+ this.delegationCache.set(zone, ips);
+ }
+
+ private getCachedDelegation(
+ domain: string,
+ recordType: RecordType,
+ ): { zone: string; ips: string[] } | undefined {
+ const labels = canonicalDnsName(domain).split('.').filter(Boolean);
+ // DS records live in the parent zone: a child's own servers answer a DS
+ // query for their apex with NODATA, which would falsely read as "no DS".
+ // Skip the exact-name entry and start at the parent.
+ const start = recordType === 'DS' ? 1 : 0;
+ for (let i = start; i < labels.length; i++) {
+ const zone = labels.slice(i).join('.');
+ const ips = this.delegationCache.get(zone);
+ if (ips) return { zone, ips };
+ }
+ return undefined;
+ }
+
+ private async fetchRecordsRaw({
domain,
recordType,
- nameserver,
+ nameservers,
trace = [],
depth = 0,
- }: FetchRecordsParams): Promise<ResolverResponse> {
+ // The deadline and query budget span the whole walk -- referrals and
+ // glueless sub-lookups inherit both -- so each delegation level can't
+ // stack a fresh allowance.
+ deadlineAt = Date.now() +
+ (this.options.fallbackDeadlineMs ??
+ AuthoritativeResolver.FALLBACK_DEADLINE_MS),
+ budget = { remaining: AuthoritativeResolver.MAX_CANDIDATES_PER_WALK },
+ }: FetchRecordsParams): Promise<{
+ answers: RawAnswer[];
+ trace: string[];
+ }> {
if (depth > AuthoritativeResolver.MAX_RECURSION_DEPTH) {
throw new Error(
`Max recursion depth exceeded while resolving ${domain} (type ${recordType})`,
);
}
- const rootServers = await this.getRootServers();
+ const cached = nameservers?.length
+ ? undefined
+ : this.getCachedDelegation(domain, recordType);
+ const candidateNameservers =
+ nameservers && nameservers.length
+ ? nameservers
+ : (cached?.ips ?? (await this.getRootServers()).slice(0, 4));
+ const wantName = canonicalDnsName(domain);
+ let lastResort: { result: DnsResponse; candidate: string } | null = null;
+ const failedNameservers: string[] = [];
+ let refusedCount = 0;
+
+ // The trace prefix any accepted response shares: the failures skipped to
+ // reach it, plus a note when its UDP answer was truncated and retried over
+ // TCP. Both the in-loop accept and the post-loop lastResort adoption use it.
+ const buildAcceptedTrace = (candidate: string, truncated: boolean) => {
+ const accepted = [...trace];
+ if (failedNameservers.length) {
+ accepted.push(
+ `${recordType} ${domain} -> skipped failed nameservers: ${failedNameservers.join('; ')}`,
+ );
+ }
+ if (truncated) {
+ accepted.push(
+ `${recordType} ${domain} @ ${candidate} (udp) -> answer truncated, retry over tcp`,
+ );
+ }
+ return accepted;
+ };
+
+ // A blackholed network makes every candidate burn its full retry budget
+ // (4 attempts x 3s); serializing that across 4 fallback servers would
+ // take ~48s. The first candidate always gets its full budget -- a step
+ // reached with the deadline spent still makes progress -- and further
+ // ones only start while the deadline allows, so fast failures (REFUSED,
+ // quick rejects) still reach every server.
+ // ponytail: past the deadline the ceiling is depth x one retry budget;
+ // the platform request timeout is the backstop for adversarial chains.
+ for (const candidate of candidateNameservers) {
+ if (budget.remaining <= 0) {
+ failedNameservers.push(
+ `${candidate}: skipped, candidate budget exhausted`,
+ );
+ break;
+ }
+ if (failedNameservers.length > 0 && Date.now() >= deadlineAt) {
+ failedNameservers.push(
+ `${candidate}: skipped, fallback deadline exceeded`,
+ );
+ break;
+ }
+ budget.remaining--;
+ const loaderKey = {
+ domain,
+ recordType,
+ nameserver: candidate,
+ };
+ let result: DnsResponse;
+ try {
+ result = await this.requestLoader.load(loaderKey);
+ } catch (error) {
+ // DataLoader caches rejections; clear the key so a transient failure
+ // doesn't poison every later identical query in this walk.
+ this.requestLoader.clear(loaderKey);
+ failedNameservers.push(
+ `${candidate}: ${error instanceof Error ? error.message : 'request failed'}`,
+ );
+ continue;
+ }
+ const verdict = classifyCandidateResponse(result.packet, wantName);
+ if (verdict.kind === 'rcode-error') {
+ failedNameservers.push(`${candidate}: DNS ${verdict.rcode}`);
+ if (verdict.rcode === 'REFUSED') refusedCount++;
+ continue;
+ }
+ if (verdict.kind === 'deferred') {
+ lastResort ??= { result, candidate };
+ failedNameservers.push(
+ `${candidate}: non-authoritative answer, deferred`,
+ );
+ continue;
+ }
+ if (verdict.kind === 'lame') {
+ failedNameservers.push(
+ `${candidate}: lame response (no relevant answer, not authoritative)`,
+ );
+ continue;
+ }
+ // Usable: an authoritative answer/NODATA, or an in-bailiwick referral.
+ // Process it fully -- a terminal answer or authoritative NODATA returns,
+ // a referral is followed. If following the referral fails, a sibling
+ // candidate may delegate differently, so record the failure and try the
+ // next one rather than aborting (a broken referral must not mask a
+ // healthy sibling).
+ const acceptedTrace = buildAcceptedTrace(candidate, result.truncated);
+ try {
+ return await this.resolveAcceptedResponse({
+ packet: result.packet,
+ protocol: result.protocol,
+ candidate,
+ domain,
+ recordType,
+ wantName,
+ trace: acceptedTrace,
+ depth,
+ deadlineAt,
+ budget,
+ });
+ } catch (error) {
+ failedNameservers.push(
+ `${candidate}: referral failed (${error instanceof Error ? error.message : 'request failed'})`,
+ );
+ continue;
+ }
+ }
- const usedNameserver = nameserver || rootServers[0]; // TODO Use fallback nameservers
- const {
- packet: response,
- protocol,
- truncated,
- } = await this.requestLoader.load({
- domain,
- type: recordType,
- nameserver: usedNameserver,
- });
+ // No candidate produced a terminal answer or a followable referral.
+ if (cached) {
+ // The cached delegation was the only candidate set and may simply be
+ // stale (e.g. rate-limited or replaced mid-request); drop it and
+ // re-walk from the root once instead of failing the lookup. This takes
+ // priority over any non-authoritative lastResort answer -- adopting a
+ // deferred answer from the stale cached server would mask the healthy
+ // authoritative server the fresh root walk finds.
+ this.delegationCache.delete(cached.zone);
+ return this.fetchRecordsRaw({
+ domain,
+ recordType,
+ trace: [
+ ...trace,
+ `${recordType} ${domain} -> cached delegation ${cached.zone} failed (${failedNameservers.join('; ')}), re-walking from root`,
+ ],
+ depth: depth + 1,
+ deadlineAt,
+ budget,
+ });
+ }
- if (truncated) {
- trace = [
- ...trace,
- `${recordType} ${domain} @ ${usedNameserver} (udp) -> answer truncated, retry over tcp`,
- ];
+ if (lastResort) {
+ // No candidate answered authoritatively; the deferred answer is better
+ // than failing the lookup. It carries an owned answer, so
+ // resolveAcceptedResponse returns it as a terminal answer.
+ const lastResortTrace = buildAcceptedTrace(
+ lastResort.candidate,
+ lastResort.result.truncated,
+ );
+ lastResortTrace.push(
+ `${recordType} ${domain} @ ${lastResort.candidate} -> accepted non-authoritative answer, no better candidate`,
+ );
+ return this.resolveAcceptedResponse({
+ packet: lastResort.result.packet,
+ protocol: lastResort.result.protocol,
+ candidate: lastResort.candidate,
+ domain,
+ recordType,
+ wantName,
+ trace: lastResortTrace,
+ depth,
+ deadlineAt,
+ budget,
+ });
}
- if (response.answers?.length) {
- const filteredAnswers = response.answers.filter(
- (answer) => answer.name === domain && answer.type === recordType,
- ) as Extract<Answer, { type: RecordType }>[];
-
- const records: RawRecord[] =
- filteredAnswers?.map((answer) => ({
- name: answer.name,
- type: answer.type,
- TTL: 'ttl' in answer ? answer.ttl || 0 : 0,
- data: this.recordToString(answer),
- })) || [];
-
- const fullTrace = [
- ...trace,
- `${recordType} ${domain} @ ${usedNameserver} (${protocol}) -> answer: ${filteredAnswers.map(this.recordToString).join(', ')}`,
- ];
-
- return { records, trace: fullTrace };
+ // Some authoritatives REFUSE direct RRSIG browsing (e.g. Cloudflare).
+ // Tolerate that one definitive policy response for RRSIG queries only,
+ // and only when every attempted server returned it. Ordinary lookups,
+ // SERVFAIL/FORMERR/NOTIMP, and mixed transport failures remain
+ // retryable errors rather than masquerading as an empty RRset.
+ const allRefused = refusedCount === candidateNameservers.length;
+ if (allRefused && recordType === 'RRSIG') {
+ return {
+ answers: [],
+ trace: [
+ ...trace,
+ `${recordType} ${domain} -> all nameservers returned an error: ${failedNameservers.join('; ')}`,
+ ],
+ };
+ }
+ throw new UserFacingError(
+ {
+ title: 'Authoritative DNS servers did not answer',
+ description:
+ 'Every available authoritative nameserver failed or returned a retryable DNS error. Please try again shortly.',
+ retryable: true,
+ },
+ {
+ cause: new Error(
+ `All nameservers failed for ${domain} ${recordType}: ${failedNameservers.join('; ')}`,
+ ),
+ },
+ );
+ }
+
+ // Turn a usable response (authoritative, or an in-bailiwick referral) into a
+ // final answer: return its terminal records, return an authoritative NODATA,
+ // or follow its referral. Throws when a referral cannot be followed so the
+ // caller can try the next sibling candidate.
+ private async resolveAcceptedResponse({
+ packet,
+ protocol,
+ candidate,
+ domain,
+ recordType,
+ wantName,
+ trace,
+ depth,
+ deadlineAt,
+ budget,
+ }: {
+ packet: Packet;
+ protocol: DnsResponse['protocol'];
+ candidate: string;
+ domain: string;
+ recordType: RecordType;
+ wantName: string;
+ trace: string[];
+ depth: number;
+ deadlineAt: number;
+ budget: { remaining: number };
+ }): Promise<{ answers: RawAnswer[]; trace: string[] }> {
+ // Only records owned by the queried name (any type, e.g. a CNAME alias)
+ // make this a terminal answer. An answer section carrying nothing but
+ // unrelated records (e.g. glue promoted into it by a quirky server) must
+ // not read as an authoritative empty answer -- it falls through to the
+ // referral handling below instead.
+ // Owner names are case-insensitive; zones may echo them in a different
+ // case than the query, and a case-mismatched drop here would misreport
+ // a signed RRset as unsigned.
+ if (
+ packet.answers?.some(
+ (answer) => canonicalDnsName(answer.name) === wantName,
+ )
+ ) {
+ const filteredAnswers = packet.answers.filter(
+ (answer) =>
+ canonicalDnsName(answer.name) === wantName &&
+ answer.type === recordType,
+ ) as RawAnswer[];
+
+ return {
+ answers: filteredAnswers,
+ trace: [
+ ...trace,
+ `${recordType} ${domain} @ ${candidate} (${protocol}) -> answer: ${filteredAnswers.map(this.recordToString).join(', ')}`,
+ ],
+ };
}
// We must validate referrals before following them: an attacker controlling
// a delegated zone can otherwise point our recursive query at loopback or
- // RFC1918 addresses and turn this resolver into an SSRF primitive.
+ // RFC1918 addresses and turn this resolver into an SSRF primitive. Only
+ // in-bailiwick NS records count as a referral at all: an upward referral
+ // (a lame server pointing back at the root) or NS records for a foreign
+ // zone plus their glue must not steer the walk.
const redirects = [
- ...(response.authorities || []),
- ...(response.additionals || []),
- ].filter(
+ ...(packet.authorities || []),
+ ...(packet.additionals || []),
+ ];
+ const nsRedirects = redirects.filter(
(answer): answer is StringAnswer =>
- answer.type === 'A' || answer.type === 'NS',
+ answer.type === 'NS' &&
+ isInBailiwick(wantName, canonicalDnsName(answer.name)),
);
- if (redirects.length) {
- // Only trust glue A records that match a delegated NS hostname
- // (in-bailiwick) and resolve to a publicly routable IP address.
+ if (nsRedirects.length) {
+ // Trust a glue A record only if it names one of this referral's
+ // delegated NS hostnames and points at a publicly routable IP.
+ // We deliberately accept out-of-bailiwick glue (an NS host not under
+ // the delegated zone): a from-the-root resolver needs it to bootstrap
+ // -- root glue for the gTLD servers (a.gtld-servers.net is not under
+ // "com") and the third-party DNS the majority of zones use
+ // (ns-1.awsdns-01.org for example.com) are both out of bailiwick, and
+ // rejecting them would force an unresolvable circular walk. isPublicIp
+ // is the real SSRF boundary here; an attacker who could inject glue
+ // already controls the zone whose resolution it would steer.
const delegatedNsNames = new Set(
- redirects
- .filter((r) => r.type === 'NS')
- .map((r) => r.data.toLowerCase()),
+ nsRedirects.map((r) => canonicalDnsName(r.data)),
);
const aRedirects = redirects.filter(
- (redirect) =>
+ (redirect): redirect is StringAnswer =>
redirect.type === 'A' &&
- delegatedNsNames.has(redirect.name.toLowerCase()) &&
+ delegatedNsNames.has(canonicalDnsName(redirect.name)) &&
isPublicIp(redirect.data),
);
if (aRedirects.length) {
- return this.fetchRecords({
+ // Cap like the sibling NS-resolution/root paths: each candidate costs
+ // up to 3 retries x 3s, and the glue set is attacker-influenced.
+ // Dedupe before the cap so four colocated NS hostnames sharing one
+ // (failing) IP can't crowd out a distinct healthy address.
+ const addresses = [
+ ...new Set(aRedirects.map((redirect) => redirect.data)),
+ ].slice(0, 4);
+ this.cacheDelegation(nsRedirects[0].name, domain, addresses);
+ return this.fetchRecordsRaw({
domain,
recordType,
- nameserver: aRedirects[0].data,
+ nameservers: addresses,
trace: [
...trace,
- `${recordType} ${domain} @ ${usedNameserver} (${protocol}) -> redirect to ${aRedirects.map((r) => r.data).join(', ')}`,
+ `${recordType} ${domain} @ ${candidate} (${protocol}) -> redirect to ${aRedirects.map((r) => r.data).join(', ')}`,
],
depth: depth + 1,
+ deadlineAt,
+ budget,
});
}
- const nsRedirects = redirects.filter(
- (redirect) => redirect.type === 'NS',
- );
- if (nsRedirects.length) {
- const { records: aRecords, trace: subTrace } = await this.fetchRecords({
- domain: nsRedirects[0].data,
- recordType: 'A',
- depth: depth + 1,
- });
+ // No usable glue: resolve the delegated NS hostnames ourselves.
+ return this.followReferralViaNsLookup({
+ nsRedirects,
+ domain,
+ recordType,
+ candidate,
+ protocol,
+ trace,
+ depth,
+ deadlineAt,
+ budget,
+ });
+ }
- // The resolved NS address is attacker-controlled (they own the zone
- // and can set any A record); filter to public IPs before using it.
- const publicARecords = aRecords.filter((r) => isPublicIp(r.data));
- if (!publicARecords.length) {
- throw new Error(`Bad redirects for ${domain}`);
- }
+ return { answers: [], trace };
+ }
- return this.fetchRecords({
- domain,
- recordType,
- nameserver: publicARecords[0].data,
- trace: [
- ...trace,
- `${recordType} ${domain} @ ${usedNameserver} (${protocol}) -> redirect to ${nsRedirects.map((r) => r.data).join(', ')}`,
- ...subTrace,
- ],
+ // Follow a glueless referral: resolve the delegated NS hostnames to public
+ // IPs and continue the walk there. Throws when none resolve, so the caller
+ // can fall through to the next sibling candidate.
+ private async followReferralViaNsLookup({
+ nsRedirects,
+ domain,
+ recordType,
+ candidate,
+ protocol,
+ trace,
+ depth,
+ deadlineAt,
+ budget,
+ }: {
+ nsRedirects: StringAnswer[];
+ domain: string;
+ recordType: RecordType;
+ candidate: string;
+ protocol: DnsResponse['protocol'];
+ trace: string[];
+ depth: number;
+ deadlineAt: number;
+ budget: { remaining: number };
+ }): Promise<{ answers: RawAnswer[]; trace: string[] }> {
+ const subTrace: string[] = [];
+ // Resolve the candidate NS hostnames concurrently and proceed with
+ // the first usable result: done serially (or awaited jointly), a
+ // dead sibling would stall the walk for its full retry/fallback
+ // budget even after a usable address had already been found.
+ // The resolved NS address is attacker-controlled (they own the zone
+ // and can set any A record); filter to public IPs before using it.
+ // Every finished lookup pushes its addresses before resolving, so
+ // when the race below ends, all siblings that were at least as fast
+ // as the winner are already collected as fallbacks.
+ const resolvedSets: string[][] = [];
+ const lookups = nsRedirects.slice(0, 4).map(async (ns) => {
+ try {
+ const resolved = await this.fetchRecordsRaw({
+ domain: ns.data,
+ recordType: 'A',
depth: depth + 1,
+ deadlineAt,
+ budget,
});
+ subTrace.push(...resolved.trace);
+ // resolved.answers are all A records (filtered by type), so
+ // recordToString yields the bare IP string for each.
+ const ips = resolved.answers
+ .map((a) => this.recordToString(a))
+ .filter((ip) => isPublicIp(ip));
+ if (!ips.length) throw new Error(`no public address (${ns.data})`);
+ resolvedSets.push(ips);
+ return ips;
+ } catch (error) {
+ subTrace.push(
+ `A ${ns.data} -> failed: ${
+ error instanceof Error ? error.message : 'request failed'
+ }`,
+ );
+ throw error;
}
-
+ });
+ try {
+ // Proceed as soon as any lookup yields a usable address -- a dead
+ // sibling must not stall the walk once one is available.
+ await Promise.any(lookups);
+ } catch {
throw new Error(`Bad redirects for ${domain}`);
}
-
- return { records: [], trace };
+ const tried = [...new Set(resolvedSets.flat())].slice(0, 4);
+
+ this.cacheDelegation(nsRedirects[0].name, domain, tried);
+ const redirectTrace = [
+ ...trace,
+ `${recordType} ${domain} @ ${candidate} (${protocol}) -> redirect to ${nsRedirects.map((r) => r.data).join(', ')}`,
+ ...subTrace,
+ ];
+ try {
+ return await this.fetchRecordsRaw({
+ domain,
+ recordType,
+ nameservers: tried,
+ trace: redirectTrace,
+ depth: depth + 1,
+ deadlineAt,
+ budget,
+ });
+ } catch (error) {
+ // Sibling NS lookups are still usable failover: the race above only
+ // existed to avoid stalling while a usable address was in hand, and
+ // that address just failed. Wait for the stragglers (each bounded by
+ // the walk deadline), retry once with any addresses the first attempt
+ // didn't see, and let them replace the dead cache entry.
+ await Promise.allSettled(lookups);
+ const late = [...new Set(resolvedSets.flat())]
+ .filter((ip) => !tried.includes(ip))
+ .slice(0, 4);
+ if (!late.length) throw error;
+ this.delegationCache.delete(canonicalDnsName(nsRedirects[0].name));
+ this.cacheDelegation(nsRedirects[0].name, domain, late);
+ return this.fetchRecordsRaw({
+ domain,
+ recordType,
+ nameservers: late,
+ trace: [
+ ...redirectTrace,
+ `${recordType} ${domain} -> retrying with late sibling nameservers: ${late.join(', ')}`,
+ ],
+ depth: depth + 1,
+ deadlineAt,
+ budget,
+ });
+ }
}
public async resolveRecordType(
domain: string,
recordType: RecordType,
): Promise<ResolverResponse> {
- return this.fetchRecords({ domain, recordType });
+ const { answers, trace } = await this.fetchRecordsRaw({
+ domain,
+ recordType,
+ });
+
+ const records: RawRecord[] = answers.map((answer) => ({
+ name: answer.name,
+ type: answer.type,
+ TTL: 'ttl' in answer ? answer.ttl || 0 : 0,
+ data: this.recordToString(answer),
+ }));
+
+ return { records, trace };
}
}
diff --git a/types/dns-packet-augment.d.ts b/types/dns-packet-augment.d.ts
new file mode 100644
index 0000000..5aa90aa
--- /dev/null
+++ b/types/dns-packet-augment.d.ts
@@ -0,0 +1,8 @@
+import 'dns-packet';
+
+declare module 'dns-packet' {
+ interface Packet {
+ // dns-packet decodes the response code (e.g. 'NXDOMAIN') but @types/dns-packet omits it.
+ rcode?: string;
+ }
+}