feat(dns): accept a promise-based custom DNS resolver

[andris9]

Summary

Adds dnsOptions.resolveRecords, a DNS resolver that returns the records instead of taking a callback. The existing dnsOptions.resolve keeps working unchanged.

Why

resolve was the only way to supply a resolver, and it carries two warts. It takes a callback, which the library promisifies straight back into a promise since everything inside has been async/await for a while. And it omits the record type entirely for A lookups, calling resolve(domain, callback) rather than resolve(domain, type, callback), so every implementation has to handle two arities.

resolveRecords is the same job without either. It receives a domain and an explicit record type, A lookups included, and returns the records:

const connection = await mxConnect({
    target: 'user@example.com',
    dnsOptions: {
        async resolveRecords(domain, type) {
            return myResolver.lookup(domain, type);
        }
    }
});

Returning the records directly is as valid as returning a promise, since awaiting covers both, so a cache-backed resolver does not have to pretend to be asynchronous. A synchronous throw becomes a rejection for the same reason.

resolve keeps working exactly as before, arity quirk included. When both are set resolveRecords wins and the callback is never consulted, so a deployment can migrate one option at a time.

Naming

Named resolveAsync at first and renamed on review, before it shipped, so nothing released is affected. "Async" named the wrong axis: both options are asynchronous, and the suffixed one is ironically the only one allowed to answer synchronously. It also collided with the meaning the suffix already carries here, where resolveTlsaAsync is an internally promisified callback while the public promise-based options, dane.resolveTlsa and dane.checkDnssecSecure, take no suffix at all. resolveRecords follows those and says what the function does.

Two security fixes found in review

A mistyped resolver no longer silently falls back to system DNS. The typeof guard added with the new option turned what used to be a loud per-lookup throw into a quiet fallback. For an MTA that deliberately configures a resolver, a DNSSEC-validating one for instance, a typo would have sent mail through a resolver nobody chose with nothing to notice. Both options are now refused up front with a TypeError naming the offender; unset or null still falls through.

The MTA-STS policy filter now only trusts a real array. It called .filter on whatever the resolver returned, so an answer supplying its own filter method chose what survived validation, and mailauth connects to whatever comes back. This was the only unvalidated address the review could get near a socket. Verified directly: a duck-typed {length: 1, filter: () => ['127.0.0.1']} previously reached https.request with host 127.0.0.1 and now produces zero requests, while the delivery still completes over the legitimate MX. Covered by a regression test.

Review evidence

The security review found no HIGH or MEDIUM issues in the resolver work itself, backed by:

• 600 hostile validation cases, 40 addresses across 5 resolution routes and 3 resolver forms, with zero connections to a blocked address, zero escapes past the connect hook, and zero parity mismatches between resolver forms
• 91 error-semantics combinations, confirming ENOTFOUND/ENODATA still falls through while a hard failure surfaces as temporary, identically on both paths, so an attacker who can cause SERVFAIL cannot steer resolution to a fallback they control
• 93 hostile return values, with zero unhandled rejections, zero uncaught exceptions and nothing reaching a socket

The simplify review also caught that one of the new tests was vacuous, asserting only that a resolver came back, which every branch satisfies. It now pins the behaviour and fails when the guard is weakened.

Tests and docs

206 unit and 7 integration tests pass; coverage 99.59% lines, 95.60% branches, 100% functions. README gains a Custom DNS resolver section covering both forms, how to report a lookup failure, precedence, the new refusal, and a note that TLSA lookups bypass dnsOptions entirely and need dane.resolveTlsa.