tldts-core 7.1.2 → 7.2.1

package/src/factory.ts

@@ -8,6 +8,7 @@ import getDomain from './domain';
 import getDomainWithoutSuffix from './domain-without-suffix';
 import extractHostname from './extract-hostname';
 import isIp from './is-ip';
+import isSpecialUse from './is-special-use';
 import isValidHostname from './is-valid';
 import { IPublicSuffix, ISuffixLookupOptions } from './lookup/interface';
 import { IOptions, setDefaults } from './options';
@@ -15,9 +16,10 @@ import getSubdomain from './subdomain';
 
 export interface IResult {
   // `hostname` is either a registered name (including but not limited to a
-  // hostname), or an IP address. IPv4 addresses must be in dot-decimal
-  // notation, and IPv6 addresses must be enclosed in brackets ([]). This is
-  // directly extracted from the input URL.
+  // hostname), or an IP address, directly extracted from the input URL. IPv4
+  // addresses are in dot-decimal notation. IPv6 is returned without its
+  // surrounding brackets; both bracketed (in URLs, e.g. `http://[::1]/`) and
+  // bare unbracketed (e.g. `2a01:e35::1`) IPv6 literals are accepted.
   hostname: string | null;
 
   // Is `hostname` an IP? (IPv4 or IPv6)
@@ -32,6 +34,13 @@ export interface IResult {
   // Specifies if `publicSuffix` comes from the ICANN or PRIVATE section of the list
   isIcann: boolean | null;
   isPrivate: boolean | null;
+
+  // Is `hostname` a special-use domain from the IANA registry (RFC 6761 et al.:
+  // e.g. `localhost`, `*.test`, `*.local`, `*.onion`, `home.arpa`)? `isIcann`/
+  // `isPrivate` do not identify these (most are not in the Public Suffix List;
+  // the few that are appear as ordinary ICANN suffixes). `null` unless the
+  // `detectSpecialUse` option is enabled (see is-special-use.ts).
+  isSpecialUse: boolean | null;
 }
 
 export function getEmptyResult(): IResult {
@@ -42,6 +51,7 @@ export function getEmptyResult(): IResult {
     isIcann: null,
     isIp: null,
     isPrivate: null,
+    isSpecialUse: null,
     publicSuffix: null,
     subdomain: null,
   };
@@ -54,6 +64,7 @@ export function resetResult(result: IResult): void {
   result.isIcann = null;
   result.isIp = null;
   result.isPrivate = null;
+  result.isSpecialUse = null;
   result.publicSuffix = null;
   result.subdomain = null;
 }
@@ -143,6 +154,14 @@ export function parseImpl(
     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 === FLAG.ALL && options.detectSpecialUse) {
+    result.isSpecialUse = isSpecialUse(result.hostname);
+  }
+
   // Extract public suffix
   suffixLookup(result.hostname, options, result);
   if (step === FLAG.PUBLIC_SUFFIX || result.publicSuffix === null) {

package/src/is-special-use.ts

@@ -0,0 +1,65 @@
+/**
+ * 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: readonly string[] = [
+  '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`.
+ */
+export default function isSpecialUse(hostname: string): boolean {
+  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;
+}

package/src/options.ts

@@ -2,6 +2,10 @@ export interface IOptions {
   allowIcannDomains: boolean;
   allowPrivateDomains: boolean;
   detectIp: boolean;
+  // Detect RFC 6761 / IANA special-use domains and expose the result as
+  // `isSpecialUse` on `parse()`. Off by default so the common path stays
+  // allocation-free with no extra work; enable it to populate the field.
+  detectSpecialUse: boolean;
   extractHostname: boolean;
   mixedInputs: boolean;
   validHosts: string[] | null;
@@ -12,6 +16,7 @@ function setDefaultsImpl({
   allowIcannDomains = true,
   allowPrivateDomains = false,
   detectIp = true,
+  detectSpecialUse = false,
   extractHostname = true,
   mixedInputs = true,
   validHosts = null,
@@ -21,6 +26,7 @@ function setDefaultsImpl({
     allowIcannDomains,
     allowPrivateDomains,
     detectIp,
+    detectSpecialUse,
     extractHostname,
     mixedInputs,
     validHosts,