Merge pull request #203 from salesforce/feat/special-use-domains

Add explanation and more special-use domains

lib/permuteDomain.js

@@ -33,15 +33,27 @@ const pubsuffix = require("./pubsuffix-psl");
 
 // Gives the permutation of all possible domainMatch()es of a given domain. The
 // array is in shortest-to-longest order.  Handy for indexing.
-const SPECIAL_USE_DOMAINS = ["local"]; // RFC 6761
+
+// RFC 6761
+const SPECIAL_USE_DOMAINS = [
+  "local",
+  "example",
+  "invalid",
+  "localhost",
+  "test"
+];
+
 function permuteDomain(domain, allowSpecialUseDomain) {
   let pubSuf = null;
   if (allowSpecialUseDomain) {
     const domainParts = domain.split(".");
-    if (SPECIAL_USE_DOMAINS.includes(domainParts[domainParts.length - 1])) {
-      pubSuf = `${domainParts[domainParts.length - 2]}.${
-        domainParts[domainParts.length - 1]
-      }`;
+    // If the right-most label in the name is a special-use domain (e.g. bananas.apple.localhost),
+    // then don't use PSL. This is because most special-use domains are not listed on PSL.
+    const topLevelDomain = domainParts[domainParts.length - 1];
+    if (SPECIAL_USE_DOMAINS.includes(topLevelDomain)) {
+      const secondLevelDomain = domainParts[domainParts.length - 2];
+      // In aforementioned example, the eTLD/pubSuf will be apple.localhost
+      pubSuf = `${secondLevelDomain}.${topLevelDomain}`;
     } else {
       pubSuf = pubsuffix.getPublicSuffix(domain);
     }