tldts 7.1.1 → 7.2.0

package/README.md

@@ -93,6 +93,10 @@ your inputs.
   validateHostname: boolean;
   // Perform IP address detection (default: true).
   detectIp: boolean;
+  // Detect IANA special-use domains (RFC 6761 et al.) and expose the result as
+  // `isSpecialUse` (default: false). Off by default so the common path does no
+  // extra work; the field stays `null` unless this is enabled.
+  detectSpecialUse: boolean;
   // Assume that both URLs and hostnames can be given as input (default: true)
   // If set to `false` we assume only URLs will be given as input, which
   // speed-ups processing.
@@ -181,6 +185,21 @@ tldts.parse('tldts@emailprovider.co.uk'); // email
 | `isIcann`             | `bool` | Does TLD come from ICANN part of the list       |
 | `isPrivate`           | `bool` | Does TLD come from Private part of the list     |
 | `isIP`                | `bool` | Is `hostname` an IP address?                    |
+| `isSpecialUse`        | `bool` | Is `hostname` an IANA special-use domain?       |
+
+## Special-use domains (RFC 6761 / IANA)
+
+Set `{ detectSpecialUse: true }` to flag reserved special-use names such as `localhost`, `*.test`, `*.local`, `*.onion`, and `home.arpa` via the `isSpecialUse` result field. `isIcann`/`isPrivate` don't identify these: most aren't in the Public Suffix List, and the few that are (e.g. `onion`, `home.arpa`) appear there as ordinary ICANN suffixes. The field is `null` unless the option is enabled, so the default path does no extra work:
+
+```js
+parse('http://printer.local/', { detectSpecialUse: true });
+// { ...
+//   isSpecialUse: true,
+//   publicSuffix: 'local',
+//   subdomain: '' }
+```
+
+The list tracks the IANA [Special-Use Domain Names](https://www.iana.org/assignments/special-use-domain-names/) registry.
 
 ## Single purpose methods
 

package/dist/cjs/index.js

@@ -447,7 +447,7 @@ function isProbablyIpv6(hostname) {
         }
         else if (!(((code >= 48 && code <= 57) || // 0-9
             (code >= 97 && code <= 102) || // a-f
-            (code >= 65 && code <= 90)) // A-F
+            (code >= 65 && code <= 70)) // A-F (RFC 4291 §2.2: an IPv6 hextet is hex digits only)
         )) {
             return false;
         }
@@ -463,6 +463,68 @@ function isIp(hostname) {
     return isProbablyIpv6(hostname) || isProbablyIpv4(hostname);
 }
 
+/**
+ * Special-use domain names from the IANA "Special-Use Domain Names" registry:
+ * the authoritative list, created by RFC 6761 and maintained as new RFCs add to
+ * it: https://www.iana.org/assignments/special-use-domain-names/
+ * Snapshot: 2026-05-24. (RFC 6761 is not obsoleted; draft-hoffman-rfc6761bis
+ * proposes to retire its prose but keep this registry, so the registry is the
+ * source of truth; re-sync this list against it.)
+ *
+ * These names never correspond to a public registration, yet neither
+ * `isIcann` nor `isPrivate` marks one as special-use: most are absent from the
+ * Public Suffix List (so `a.test` looks like a registrable domain), and the
+ * few that are listed (`onion`, `home.arpa`) appear there as ordinary ICANN
+ * suffixes. `isSpecialUse` is the single signal that covers them all.
+ *
+ * Per the registry and RFC 6761 ("and any names falling within these domains"),
+ * the designation covers each listed name AND all of its sub-domains. DNS labels
+ * are case-insensitive (RFC 4343); `hostname` is expected to be already
+ * lower-cased and trailing-dot-stripped, as produced by `extractHostname`, the
+ * same normalization the Public-Suffix-List lookup relies on.
+ *
+ * Two groups of registry entries are intentionally excluded: the numeric
+ * reverse-DNS delegation zones (`10.in-addr.arpa`, the `*.ip6.arpa` ranges, …),
+ * which are reverse-DNS PTR zones rather than hostnames and whose parents
+ * (`in-addr.arpa`/`ip6.arpa`) are already in the Public Suffix List; and the
+ * deprecated `eap-noob.arpa` entry.
+ */
+const SPECIAL_USE_DOMAINS = [
+    'test', // RFC 6761
+    'localhost', // RFC 6761
+    'invalid', // RFC 6761
+    'example', // RFC 6761
+    'example.com', // RFC 6761
+    'example.net', // RFC 6761
+    'example.org', // RFC 6761
+    'local', // RFC 6762 (mDNS)
+    'onion', // RFC 7686 (Tor)
+    'alt', // RFC 9476
+    'home.arpa', // RFC 8375
+    'ipv4only.arpa', // RFC 8880
+    'resolver.arpa', // RFC 9462
+    'service.arpa', // RFC 9665
+    '6tisch.arpa', // RFC 9031
+    'eap.arpa', // RFC 9965
+];
+/**
+ * Return `true` if `hostname` is, or is a sub-domain of, a special-use domain
+ * (see the registry note above). Expects an already-normalized `hostname`.
+ */
+function isSpecialUse(hostname) {
+    for (const name of SPECIAL_USE_DOMAINS) {
+        // Match on a label boundary: `hostname` is either exactly `name` or ends
+        // with `.name` (so `latest` is not matched by `test`, nor `myexample.com`
+        // by `example.com`).
+        if (hostname.endsWith(name) &&
+            (hostname.length === name.length ||
+                hostname.charCodeAt(hostname.length - name.length - 1) === 46) /* '.' */) {
+            return true;
+        }
+    }
+    return false;
+}
+
 /**
  * Implements fast shallow verification of hostnames. This does not perform a
  * struct check on the content of labels (classes of Unicode characters, etc.)
@@ -529,11 +591,12 @@ function isValidHostname (hostname) {
         lastCharCode !== 45);
 }
 
-function setDefaultsImpl({ allowIcannDomains = true, allowPrivateDomains = false, detectIp = true, extractHostname = true, mixedInputs = true, validHosts = null, validateHostname = true, }) {
+function setDefaultsImpl({ allowIcannDomains = true, allowPrivateDomains = false, detectIp = true, detectSpecialUse = false, extractHostname = true, mixedInputs = true, validHosts = null, validateHostname = true, }) {
     return {
         allowIcannDomains,
         allowPrivateDomains,
         detectIp,
+        detectSpecialUse,
         extractHostname,
         mixedInputs,
         validHosts,
@@ -572,6 +635,7 @@ function getEmptyResult() {
         isIcann: null,
         isIp: null,
         isPrivate: null,
+        isSpecialUse: null,
         publicSuffix: null,
         subdomain: null,
     };
@@ -583,6 +647,7 @@ function resetResult(result) {
     result.isIcann = null;
     result.isIp = null;
     result.isPrivate = null;
+    result.isSpecialUse = null;
     result.publicSuffix = null;
     result.subdomain = null;
 }
@@ -642,6 +707,13 @@ function parseImpl(url, step, suffixLookup, partialOptions, result) {
     if (step === 0 /* FLAG.HOSTNAME */ || result.hostname === null) {
         return result;
     }
+    // Flag special-use domains, only when opted in (`detectSpecialUse`) and only
+    // for the full `parse()` result (FLAG.ALL). Computed here, before the
+    // public-suffix/domain early-returns below, so single-label names like
+    // `localhost` (which have no registrable domain) are still flagged.
+    if (step === 5 /* FLAG.ALL */ && options.detectSpecialUse) {
+        result.isSpecialUse = isSpecialUse(result.hostname);
+    }
     // Extract public suffix
     suffixLookup(result.hostname, options, result);
     if (step === 2 /* FLAG.PUBLIC_SUFFIX */ || result.publicSuffix === null) {