tldts 7.1.2 → 7.2.1

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

@@ -291,29 +291,50 @@ function extractHostname(url, urlIsValidHostname) {
                         if (!allDigits) {
                             const special = getSpecialScheme(url, start, indexOfColon);
                             if (special === 0) {
-                                // No "://" anywhere on the cold path, so a non-special scheme has
-                                // no authority: opaque path, no host ("mailto:x", "foo:bar").
-                                return null;
-                            }
-                            isSpecial = true;
-                            start = indexOfColon + 1;
-                            if (special === 2) {
-                                // file (e.g. "file:\\host"): host only between "//" and next slash.
-                                let slashes = 0;
-                                while ((url.charCodeAt(start) === 47 ||
-                                    url.charCodeAt(start) === 92) &&
-                                    slashes < 2) {
-                                    start += 1;
-                                    slashes += 1;
+                                // No "://" anywhere on the cold path and not a special scheme.
+                                // A second ':' before the host's end marks a bare, unbracketed
+                                // IPv6 literal ("2a01:e35::1"): fall through and let the host
+                                // loop + isIp classify it. Without one this is an opaque path
+                                // with no host ("mailto:x", "foo:bar").
+                                let isBareIpv6 = false;
+                                for (let j = indexOfColon + 1; j < end; j += 1) {
+                                    const code = url.charCodeAt(j);
+                                    if (code === 47 ||
+                                        code === 92 ||
+                                        code === 63 ||
+                                        code === 35) {
+                                        break;
+                                    }
+                                    if (code === 58 /* ':' */) {
+                                        isBareIpv6 = true;
+                                        break;
+                                    }
                                 }
-                                if (slashes < 2) {
+                                if (!isBareIpv6) {
                                     return null;
                                 }
                             }
                             else {
-                                while (url.charCodeAt(start) === 47 ||
-                                    url.charCodeAt(start) === 92) {
-                                    start += 1;
+                                isSpecial = true;
+                                start = indexOfColon + 1;
+                                if (special === 2) {
+                                    // file (e.g. "file:\\host"): host only between "//" and next slash.
+                                    let slashes = 0;
+                                    while ((url.charCodeAt(start) === 47 ||
+                                        url.charCodeAt(start) === 92) &&
+                                        slashes < 2) {
+                                        start += 1;
+                                        slashes += 1;
+                                    }
+                                    if (slashes < 2) {
+                                        return null;
+                                    }
+                                }
+                                else {
+                                    while (url.charCodeAt(start) === 47 ||
+                                        url.charCodeAt(start) === 92) {
+                                        start += 1;
+                                    }
                                 }
                             }
                         }
@@ -323,11 +344,14 @@ function extractHostname(url, urlIsValidHostname) {
         }
         // Find the host's end: first '/', '?' or '#' (and '\' for special URLs,
         // which WHATWG treats like '/'). Track the last '@', ']' and ':' for
-        // userinfo, ipv6 and port; flag uppercase and a stray tab/newline. The loop
-        // is split on `code < 64` so common host characters take fewer comparisons.
+        // userinfo, ipv6 and port, plus the first ':' of the host (reset at each
+        // '@') to tell a bare IPv6 (>= 2 colons) from a host:port (exactly one);
+        // flag uppercase and a stray tab/newline. The loop is split on `code < 64`
+        // so common host characters take fewer comparisons.
         let indexOfIdentifier = -1;
         let indexOfClosingBracket = -1;
         let indexOfPort = -1;
+        let indexOfFirstColon = -1;
         let hasControl = false;
         for (let i = start; i < end; i += 1) {
             const code = url.charCodeAt(i);
@@ -337,6 +361,9 @@ function extractHostname(url, urlIsValidHostname) {
                     break;
                 }
                 else if (code === 58 /* ':' */) {
+                    if (indexOfFirstColon === -1) {
+                        indexOfFirstColon = i;
+                    }
                     indexOfPort = i;
                 }
                 else if (code === 9 || code === 10 || code === 13) {
@@ -349,6 +376,7 @@ function extractHostname(url, urlIsValidHostname) {
             }
             else if (code === 64 /* '@' */) {
                 indexOfIdentifier = i;
+                indexOfFirstColon = -1; // colons before '@' are userinfo, not the host
             }
             else if (code === 93 /* ']' */) {
                 indexOfClosingBracket = i;
@@ -374,7 +402,13 @@ function extractHostname(url, urlIsValidHostname) {
             }
             return null;
         }
-        else if (indexOfPort !== -1 && indexOfPort > start && indexOfPort < end) {
+        else if (indexOfPort !== -1 &&
+            indexOfPort > start &&
+            indexOfPort < end &&
+            // A host:port has exactly one ':' in the host (so its first ':' is its
+            // last); a bare, unbracketed IPv6 literal ("2a01:e35::1") has >= 2, so
+            // its first ':' precedes the last. Only the former has a ':port' to trim.
+            indexOfFirstColon === indexOfPort) {
             end = indexOfPort; // trim ':port'
         }
         // Empty authority ("http://", "file:///path", "//"); only reachable here via
@@ -463,6 +497,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 +625,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 +669,7 @@ function getEmptyResult() {
         isIcann: null,
         isIp: null,
         isPrivate: null,
+        isSpecialUse: null,
         publicSuffix: null,
         subdomain: null,
     };
@@ -583,6 +681,7 @@ function resetResult(result) {
     result.isIcann = null;
     result.isIp = null;
     result.isPrivate = null;
+    result.isSpecialUse = null;
     result.publicSuffix = null;
     result.subdomain = null;
 }
@@ -642,6 +741,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) {