Skip to content

docs(readme): correct the TLSA claims and restructure for reading - #33

Merged
andris9 merged 1 commit into
masterfrom
docs/readme-accuracy-refactor
Aug 15, 2026
Merged

docs(readme): correct the TLSA claims and restructure for reading#33
andris9 merged 1 commit into
masterfrom
docs/readme-accuracy-refactor

Conversation

@andris9

@andris9 andris9 commented Aug 15, 2026

Copy link
Copy Markdown
Member

Summary

Documentation only. Corrects three claims that no longer match the code, and restructures the parts that had grown into walls of prose.

The TLSA resolver was documented as something it is not

dane.resolveTlsa was presented as a compatibility shim for old Node. That stopped being true when the floor moved to 22.19.0: native dns.resolveTlsa landed in 22.15.0, so every supported version has it, lib/dane.js already prefers it automatically, and the option is never required.

Verified against real DANE-enabled hosts with nothing configured:

mx1.forwardemail.net  -> 2 TLSA record(s) via the native resolver
mail.ietf.org         -> 1 TLSA record(s) via the native resolver

The section also promised "for Node.js versions without native TLSA support", a situation that can no longer arise, and its example passed an undefined customResolveTlsa, so copying it produced a ReferenceError. The same undefined identifier had been pasted into the DNSSEC and MTA-STS examples, where it was noise either way.

The option still has a real purpose, just not that one: routing TLSA lookups through a resolver of your own, usually to obtain the DNSSEC validation Node cannot yet report. It is documented as that now, with a resolver actually written out, and the examples that never needed it no longer carry it.

Two further mismatches

The local address precedence was backwards. The docs said the family-specific options take precedence over localAddress. updateLocalAddressForTarget does the opposite, confirmed by running it: with localAddress: '192.0.2.1' and localAddressIPv4: '198.51.100.1' against an IPv4 host, the connection binds 192.0.2.1. localAddress wins whenever it matches the family of the host; the specific options fill in only when it is unset or the host is the other family.

The Node requirement sat inside the DANE section although it applies to the whole package. It is stated once at the top now, and the three-row version table is gone because it had collapsed to "every supported version".

Restructure

Option lists that had grown into paragraphs are tables. Address validation, which had become five dense blocks, is a section of its own with a table per tier: always refused, blockLocalAddresses, blockReservedNetworks, and the IPv6 forms that carry an IPv4 address. Lists of CIDRs are far easier to scan in a table than in a sentence.

Notes and warnings use GitHub alerts. The two that can actually cost someone a security property are no longer prose buried mid-paragraph:

  • a warning that rejectUnauthorized must be false or a self-signed DANE-EE certificate is rejected by PKIX before the verifier ever runs
  • a caution that connectHook receives the same options object used to open the socket, so a hook rewriting options.host connects wherever it says

Checks

All nine internal anchors resolve, prettier and lint clean, no code touched.

The custom TLSA resolver was documented as a compatibility shim for old Node,
which stopped being true when the floor moved to 22.19.0: native dns.resolveTlsa
landed in 22.15.0, so every supported version has it and the option is never
required. The section promised "for Node.js versions without native TLSA support",
described a situation that can no longer arise, and its example passed an
undefined customResolveTlsa, so anyone copying it got a ReferenceError. The same
undefined identifier had been pasted into the DNSSEC and MTA-STS examples, where
it was noise either way.

The option does still have a purpose, just not that one: routing TLSA lookups
through a resolver of your own, usually to get DNSSEC validation that Node cannot
yet report. It is documented as that now, with a resolver actually written out,
and the examples that never needed it no longer carry it.

Two other things did not match the code. The family-specific local address options
were described as taking precedence over localAddress, where in fact localAddress
wins whenever it matches the family of the host and the specific ones only fill in
otherwise. The Node requirement sat inside the DANE section although it applies to
the whole package, and is now stated once at the top.

The rest is structure. Option lists that had grown into paragraphs of prose are
tables; the address validation rules, which had become five dense blocks, are a
section of their own with a table per tier. Notes and warnings use GitHub alerts,
so the two things that can actually cost someone a security property, that
rejectUnauthorized must be off for DANE-EE to reach the verifier and that
connectHook can rewrite the host after validation, are no longer prose in the
middle of a paragraph.
@andris9
andris9 merged commit b0e51d1 into master Aug 15, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant