tough-cookie 0.13.0 → 2.0.0

package/lib/cookie.js

@@ -33,6 +33,9 @@ var net = require('net');
 var urlParse = require('url').parse;
 var pubsuffix = require('./pubsuffix');
 var Store = require('./store').Store;
+var MemoryCookieStore = require('./memstore').MemoryCookieStore;
+var pathMatch = require('./pathMatch').pathMatch;
+var VERSION = require('../package.json').version;
 
 var punycode;
 try {
@@ -43,17 +46,11 @@ try {
 
 var DATE_DELIM = /[\x09\x20-\x2F\x3B-\x40\x5B-\x60\x7B-\x7E]/;
 
-// From RFC2616 S2.2:
-var TOKEN = /[\x21\x23-\x26\x2A\x2B\x2D\x2E\x30-\x39\x41-\x5A\x5E-\x7A\x7C\x7E]/;
-
 // From RFC6265 S4.1.1
 // note that it excludes \x3B ";"
 var COOKIE_OCTET  = /[\x21\x23-\x2B\x2D-\x3A\x3C-\x5B\x5D-\x7E]/;
 var COOKIE_OCTETS = new RegExp('^'+COOKIE_OCTET.source+'$');
 
-// The name/key cannot be empty but the value can (S5.2):
-var COOKIE_PAIR_STRICT = new RegExp('^('+TOKEN.source+'+)=("?)('+COOKIE_OCTET.source+'*)\\2$');
-
 // Double quotes are part of the value (see: S4.1.1).
 // '\r', '\n' and '\0' should be treated as a terminator in the "relaxed" mode
 // (see: https://github.com/ChromiumWebApps/chromium/blob/b3d3b4da8bb94c1b2e061600df106d590fda3620/net/cookies/parsed_cookie.cc#L60)
@@ -61,11 +58,9 @@ var COOKIE_PAIR_STRICT = new RegExp('^('+TOKEN.source+'+)=("?)('+COOKIE_OCTET.so
 // (see: https://github.com/ChromiumWebApps/chromium/blob/b3d3b4da8bb94c1b2e061600df106d590fda3620/net/cookies/parsed_cookie.cc#L64)
 var COOKIE_PAIR = /^([^=;]+)\s*=\s*(("?)[^\n\r\0]*\3)/;
 
-// RFC6265 S4.1.1 defines extension-av as 'any CHAR except CTLs or ";"'
+// RFC6265 S4.1.1 defines path value as 'any CHAR except CTLs or ";"'
 // Note ';' is \x3B
-var NON_CTL_SEMICOLON = /[\x20-\x3A\x3C-\x7E]+/;
-var EXTENSION_AV = NON_CTL_SEMICOLON;
-var PATH_VALUE = NON_CTL_SEMICOLON;
+var PATH_VALUE = /[\x20-\x3A\x3C-\x7E]+/;
 
 // Used for checking whether or not there is a trailing semi-colon
 var TRAILING_SEMICOLON = /;+$/;
@@ -90,11 +85,9 @@ var YEAR = /^(\d{2}|\d{4})$/; // 2 to 4 digits
 var MAX_TIME = 2147483647000; // 31-bit max
 var MIN_TIME = 0; // 31-bit min
 
-var cookiesCreated = 0; // Number of cookies created in runtime
-
 
 // RFC6265 S5.1.1 date parser:
-function parseDate(str,strict) {
+function parseDate(str) {
   if (!str) {
     return;
   }
@@ -115,9 +108,6 @@ function parseDate(str,strict) {
   var month = null;
   var year = null;
 
-  var date = new Date();
-  date.setMilliseconds(0);
-
   for (var i=0; i<tokens.length; i++) {
     var token = tokens[i].trim();
     if (!token.length) {
@@ -208,7 +198,6 @@ function parseDate(str,strict) {
         if (year < 1601) {
           return; // 5. ... the year-value is less than 1601
         }
-        continue;
       }
     }
   }
@@ -325,52 +314,19 @@ function defaultPath(path) {
   return path.slice(0, rightSlash);
 }
 
-/*
- * "A request-path path-matches a given cookie-path if at least one of the
- * following conditions holds:"
- */
-function pathMatch(reqPath,cookiePath) {
-  // "o  The cookie-path and the request-path are identical."
-  if (cookiePath === reqPath) {
-    return true;
-  }
-
-  var idx = reqPath.indexOf(cookiePath);
-  if (idx === 0) {
-    // "o  The cookie-path is a prefix of the request-path, and the last
-    // character of the cookie-path is %x2F ("/")."
-    if (cookiePath.substr(-1) === "/") {
-      return true;
-    }
-
-    // " o  The cookie-path is a prefix of the request-path, and the first
-    // character of the request-path that is not included in the cookie- path
-    // is a %x2F ("/") character."
-    if (reqPath.substr(cookiePath.length,1) === "/") {
-      return true;
-    }
-  }
-
-  return false;
-}
 
-function parse(str, strict) {
+function parse(str) {
   str = str.trim();
 
   // S4.1.1 Trailing semi-colons are not part of the specification.
-  // If we are not in strict mode we remove the trailing semi-colons.
   var semiColonCheck = TRAILING_SEMICOLON.exec(str);
   if (semiColonCheck) {
-    if (strict) {
-      return;
-    }
     str = str.slice(0, semiColonCheck.index);
   }
 
   // We use a regex to parse the "name-value-pair" part of S5.2
   var firstSemi = str.indexOf(';'); // S5.2 step 1
-  var pairRx = strict ? COOKIE_PAIR_STRICT : COOKIE_PAIR;
-  var result = pairRx.exec(firstSemi === -1 ? str : str.substr(0,firstSemi));
+  var result = COOKIE_PAIR.exec(firstSemi === -1 ? str : str.substr(0,firstSemi));
 
   // Rx satisfies the "the name string is empty" and "lacks a %x3D ("=")"
   // constraints as well as trimming any whitespace.
@@ -379,10 +335,8 @@ function parse(str, strict) {
   }
 
   var c = new Cookie();
-  c.key = result[1]; // the regexp should trim() already
-  c.value = strict ? result[3] : result[2]; // [2] is quotes or empty-string in strict mode
-  c.key = c.key.trim();
-  c.value = c.value.trim();
+  c.key = result[1].trim();
+  c.value = result[2].trim();
 
   if (firstSemi === -1) {
     return c;
@@ -410,13 +364,9 @@ function parse(str, strict) {
   var cookie_avs = unparsed.split(/\s*;\s*/);
   while (cookie_avs.length) {
     var av = cookie_avs.shift();
-
-    if (strict && !EXTENSION_AV.test(av)) {
-      return;
-    }
-
     var av_sep = av.indexOf('=');
     var av_key, av_value;
+
     if (av_sep === -1) {
       av_key = av;
       av_value = null;
@@ -426,47 +376,51 @@ function parse(str, strict) {
     }
 
     av_key = av_key.trim().toLowerCase();
+
     if (av_value) {
       av_value = av_value.trim();
     }
 
     switch(av_key) {
     case 'expires': // S5.2.1
-      if (!av_value) {if(strict){return;}else{break;} }
-      var exp = parseDate(av_value,strict);
-      // "If the attribute-value failed to parse as a cookie date, ignore the
-      // cookie-av."
-      if (exp == null) { if(strict){return;}else{break;} }
-      c.expires = exp;
-      // over and underflow not realistically a concern: V8's getTime() seems to
-      // store something larger than a 32-bit time_t (even with 32-bit node)
+      if (av_value) {
+        var exp = parseDate(av_value);
+        // "If the attribute-value failed to parse as a cookie date, ignore the
+        // cookie-av."
+        if (exp) {
+          // over and underflow not realistically a concern: V8's getTime() seems to
+          // store something larger than a 32-bit time_t (even with 32-bit node)
+          c.expires = exp;
+        }
+      }
       break;
 
     case 'max-age': // S5.2.2
-      if (!av_value) { if(strict){return;}else{break;} }
-      // "If the first character of the attribute-value is not a DIGIT or a "-"
-      // character ...[or]... If the remainder of attribute-value contains a
-      // non-DIGIT character, ignore the cookie-av."
-      if (!/^-?[0-9]+$/.test(av_value)) { if(strict){return;}else{break;} }
-      var delta = parseInt(av_value,10);
-      if (strict && delta <= 0) {
-        return; // S4.1.1
+      if (av_value) {
+        // "If the first character of the attribute-value is not a DIGIT or a "-"
+        // character ...[or]... If the remainder of attribute-value contains a
+        // non-DIGIT character, ignore the cookie-av."
+        if (/^-?[0-9]+$/.test(av_value)) {
+          var delta = parseInt(av_value, 10);
+          // "If delta-seconds is less than or equal to zero (0), let expiry-time
+          // be the earliest representable date and time."
+          c.setMaxAge(delta);
+        }
       }
-      // "If delta-seconds is less than or equal to zero (0), let expiry-time
-      // be the earliest representable date and time."
-      c.setMaxAge(delta);
       break;
 
     case 'domain': // S5.2.3
       // "If the attribute-value is empty, the behavior is undefined.  However,
       // the user agent SHOULD ignore the cookie-av entirely."
-      if (!av_value) { if(strict){return;}else{break;} }
-      // S5.2.3 "Let cookie-domain be the attribute-value without the leading %x2E
-      // (".") character."
-      var domain = av_value.trim().replace(/^\./,'');
-      if (!domain) { if(strict){return;}else{break;} } // see "is empty" above
-      // "Convert the cookie-domain to lower case."
-      c.domain = domain.toLowerCase();
+      if (av_value) {
+        // S5.2.3 "Let cookie-domain be the attribute-value without the leading %x2E
+        // (".") character."
+        var domain = av_value.trim().replace(/^\./, '');
+        if (domain) {
+          // "Convert the cookie-domain to lower case."
+          c.domain = domain.toLowerCase();
+        }
+      }
       break;
 
     case 'path': // S5.2.4
@@ -480,11 +434,7 @@ function parse(str, strict) {
        * We'll represent the default-path as null since it depends on the
        * context of the parsing.
        */
-      if (!av_value || av_value.substr(0,1) != "/") {
-        c.path = null;
-        if(strict){return;}else{break;}
-      }
-      c.path = av_value;
+      c.path = av_value && av_value[0] === "/" ? av_value : null;
       break;
 
     case 'secure': // S5.2.5
@@ -493,12 +443,10 @@ function parse(str, strict) {
        * the user agent MUST append an attribute to the cookie-attribute-list
        * with an attribute-name of Secure and an empty attribute-value."
        */
-      if (av_value != null) { if(strict){return;} }
       c.secure = true;
       break;
 
     case 'httponly': // S5.2.6 -- effectively the same as 'secure'
-      if (av_value != null) { if(strict){return;} }
       c.httpOnly = true;
       break;
 
@@ -509,47 +457,60 @@ function parse(str, strict) {
     }
   }
 
-  // ensure a default date for sorting:
-  c.creation = new Date();
-  //NOTE: add runtime index for the cookieCompare() to resolve the situation when Date's precision is not enough .
-  //Store initial UTC time as well, so we will be able to determine if we need to fallback to the Date object.
-  c._creationRuntimeIdx = ++cookiesCreated;
-  c._initialCreationTime = c.creation.getTime();
   return c;
 }
 
+// avoid the V8 deoptimization monster!
+function jsonParse(str) {
+  var obj;
+  try {
+    obj = JSON.parse(str);
+  } catch (e) {
+    return e;
+  }
+  return obj;
+}
+
 function fromJSON(str) {
   if (!str) {
     return null;
   }
 
   var obj;
-  try {
-    obj = JSON.parse(str);
-  } catch (e) {
-    return null;
+  if (typeof str === 'string') {
+    obj = jsonParse(str);
+    if (obj instanceof Error) {
+      return null;
+    }
+  } else {
+    // assume it's an Object
+    obj = str;
   }
 
   var c = new Cookie();
-  for (var i=0; i<numCookieProperties; i++) {
-    var prop = cookieProperties[i];
-    if (obj[prop] == null) {
-      continue;
+  for (var i=0; i<Cookie.serializableProperties.length; i++) {
+    var prop = Cookie.serializableProperties[i];
+    if (obj[prop] === undefined ||
+        obj[prop] === Cookie.prototype[prop])
+    {
+      continue; // leave as prototype default
     }
+
     if (prop === 'expires' ||
         prop === 'creation' ||
         prop === 'lastAccessed')
     {
-      c[prop] = obj[prop] == "Infinity" ? "Infinity" : new Date(obj[prop]);
+      if (obj[prop] === null) {
+        c[prop] = null;
+      } else {
+        c[prop] = obj[prop] == "Infinity" ?
+          "Infinity" : new Date(obj[prop]);
+      }
     } else {
       c[prop] = obj[prop];
     }
   }
 
-
-  // ensure a default date for sorting:
-  c.creation = c.creation || new Date();
-
   return c;
 }
 
@@ -563,45 +524,28 @@ function fromJSON(str) {
  */
 
 function cookieCompare(a,b) {
+  var cmp = 0;
+
   // descending for length: b CMP a
-  var deltaLen = (b.path ? b.path.length : 0) - (a.path ? a.path.length : 0);
-  if (deltaLen !== 0) {
-    return deltaLen;
+  var aPathLen = a.path ? a.path.length : 0;
+  var bPathLen = b.path ? b.path.length : 0;
+  cmp = bPathLen - aPathLen;
+  if (cmp !== 0) {
+    return cmp;
   }
 
+  // ascending for time: a CMP b
   var aTime = a.creation ? a.creation.getTime() : MAX_TIME;
   var bTime = b.creation ? b.creation.getTime() : MAX_TIME;
-
-  // NOTE: if creation dates are equal and they were not modified from the outside,
-  // then use _creationRuntimeIdx for the comparison.
-  if(aTime === bTime && aTime === a._initialCreationTime && bTime === b._initialCreationTime) {
-    return a._creationRuntimeIdx - b._creationRuntimeIdx;
+  cmp = aTime - bTime;
+  if (cmp !== 0) {
+    return cmp;
   }
 
-  // ascending for time: a CMP b
-  return aTime - bTime;
-}
-
-// Gives the permutation of all possible domainMatch()es of a given domain. The
-// array is in shortest-to-longest order.  Handy for indexing.
-function permuteDomain(domain) {
-  var pubSuf = pubsuffix.getPublicSuffix(domain);
-  if (!pubSuf) {
-    return null;
-  }
-  if (pubSuf == domain) {
-    return [domain];
-  }
+  // break ties for the same millisecond (precision of JavaScript's clock)
+  cmp = a.creationIndex - b.creationIndex;
 
-  var prefix = domain.slice(0,-(pubSuf.length+1)); // ".example.com"
-  var parts = prefix.split('.').reverse();
-  var cur = pubSuf;
-  var permutations = [cur];
-  while (parts.length) {
-    cur = parts.shift()+'.'+cur;
-    permutations.push(cur);
-  }
-  return permutations;
+  return cmp;
 }
 
 // Gives the permutation of all possible pathMatch()es of a given path. The
@@ -627,20 +571,46 @@ function permutePath(path) {
 }
 
 function getCookieContext(url) {
-  return (url instanceof Object) ? url : urlParse(decodeURI(url));
+  if (url instanceof Object) {
+    return url;
+  }
+  // NOTE: decodeURI will throw on malformed URIs (see GH-32).
+  // Therefore, we will just skip decoding for such URIs.
+  try {
+    url = decodeURI(url);
+  }
+  catch(err) {
+    // Silently swallow error
+  }
+
+  return urlParse(url);
 }
 
-function Cookie (opts) {
-  if (typeof opts !== "object") {
-    return;
-  }
-  Object.keys(opts).forEach(function (key) {
-    if (Cookie.prototype.hasOwnProperty(key)) {
-      this[key] = opts[key] || Cookie.prototype[key];
+function Cookie(opts) {
+  opts = opts || {};
+
+  Object.keys(opts).forEach(function(prop) {
+    if (Cookie.prototype.hasOwnProperty(prop) &&
+        Cookie.prototype[prop] !== opts[prop] &&
+        prop.substr(0,1) !== '_')
+    {
+      this[prop] = opts[prop];
     }
-  }.bind(this));
+  }, this);
+
+  this.creation = this.creation || new Date();
+
+  // used to break creation ties in cookieCompare():
+  Object.defineProperty(this, 'creationIndex', {
+    configurable: false,
+    enumerable: false, // important for assert.deepEqual checks
+    writable: true,
+    value: ++Cookie.cookiesCreated
+  });
 }
 
+Cookie.cookiesCreated = 0; // incremented each time a cookie is created
+
 Cookie.parse = parse;
 Cookie.fromJSON = fromJSON;
 
@@ -660,17 +630,22 @@ Cookie.prototype.extensions = null;
 Cookie.prototype.hostOnly = null; // boolean when set
 Cookie.prototype.pathIsDefault = null; // boolean when set
 Cookie.prototype.creation = null; // Date when set; defaulted by Cookie.parse
-Cookie.prototype._initialCreationTime = null; // Used to determine if cookie.creation was modified
-Cookie.prototype._creationRuntimeIdx = null; // Runtime index of the created cookie, used in cookieCompare()
 Cookie.prototype.lastAccessed = null; // Date when set
+Object.defineProperty(Cookie.prototype, 'creationIndex', {
+  configurable: true,
+  enumerable: false,
+  writable: true,
+  value: 0
+});
 
-var cookieProperties = Object.freeze(Object.keys(Cookie.prototype).map(function(p) {
-  if (p instanceof Function) {
-    return;
-  }
-  return p;
-}));
-var numCookieProperties = cookieProperties.length;
+Cookie.serializableProperties = Object.keys(Cookie.prototype)
+  .filter(function(prop) {
+    return !(
+      Cookie.prototype[prop] instanceof Function ||
+      prop === 'creationIndex' ||
+      prop.substr(0,1) === '_'
+    );
+  });
 
 Cookie.prototype.inspect = function inspect() {
   var now = Date.now();
@@ -681,11 +656,51 @@ Cookie.prototype.inspect = function inspect() {
     '"';
 };
 
+Cookie.prototype.toJSON = function() {
+  var obj = {};
+
+  var props = Cookie.serializableProperties;
+  for (var i=0; i<props.length; i++) {
+    var prop = props[i];
+    if (this[prop] === Cookie.prototype[prop]) {
+      continue; // leave as prototype default
+    }
+
+    if (prop === 'expires' ||
+        prop === 'creation' ||
+        prop === 'lastAccessed')
+    {
+      if (this[prop] === null) {
+        obj[prop] = null;
+      } else {
+        obj[prop] = this[prop] == "Infinity" ? // intentionally not ===
+          "Infinity" : this[prop].toISOString();
+      }
+    } else if (prop === 'maxAge') {
+      if (this[prop] !== null) {
+        // again, intentionally not ===
+        obj[prop] = (this[prop] == Infinity || this[prop] == -Infinity) ?
+          this[prop].toString() : this[prop];
+      }
+    } else {
+      if (this[prop] !== Cookie.prototype[prop]) {
+        obj[prop] = this[prop];
+      }
+    }
+  }
+
+  return obj;
+};
+
+Cookie.prototype.clone = function() {
+  return fromJSON(this.toJSON());
+};
+
 Cookie.prototype.validate = function validate() {
   if (!COOKIE_OCTETS.test(this.value)) {
     return false;
   }
-  if (this.expires != Infinity && !(this.expires instanceof Date) && !parseDate(this.expires,true)) {
+  if (this.expires != Infinity && !(this.expires instanceof Date) && !parseDate(this.expires)) {
     return false;
   }
   if (this.maxAge != null && this.maxAge <= 0) {
@@ -805,7 +820,7 @@ Cookie.prototype.TTL = function TTL(now) {
 // elsewhere)
 Cookie.prototype.expiryTime = function expiryTime(now) {
   if (this.maxAge != null) {
-    var relativeTo = this.creation || now || new Date();
+    var relativeTo = now || this.creation || new Date();
     var age = (this.maxAge <= 0) ? -Infinity : this.maxAge*1000;
     return relativeTo.getTime() + age;
   }
@@ -843,16 +858,13 @@ Cookie.prototype.canonicalizedDomain = function canonicalizedDomain() {
   return canonicalDomain(this.domain);
 };
 
-
-var memstore;
 function CookieJar(store, rejectPublicSuffixes) {
   if (rejectPublicSuffixes != null) {
     this.rejectPublicSuffixes = rejectPublicSuffixes;
   }
 
   if (!store) {
-    memstore = memstore || require('./memstore');
-    store = new memstore.MemoryCookieStore();
+    store = new MemoryCookieStore();
   }
   this.store = store;
 }
@@ -873,7 +885,7 @@ CookieJar.prototype.setCookie = function(cookie, url, options, cb) {
 
   // S5.3 step 1
   if (!(cookie instanceof Cookie)) {
-    cookie = Cookie.parse(cookie, options.strict === true);
+    cookie = Cookie.parse(cookie);
   }
   if (!cookie) {
     err = new Error("Cookie failed to parse");
@@ -958,6 +970,7 @@ CookieJar.prototype.setCookie = function(cookie, url, options, cb) {
         return cb(options.ignoreError ? null : err);
       }
       cookie.creation = oldCookie.creation; // step 11.3
+      cookie.creationIndex = oldCookie.creationIndex; // preserve tie-breaker
       cookie.lastAccessed = now;
       // Step 11.4 (delete cookie) is implied by just setting the new one:
       store.updateCookie(oldCookie, cookie, next); // step 12
@@ -1104,6 +1117,151 @@ CookieJar.prototype.getSetCookieStrings = function(/*..., cb*/) {
   this.getCookies.apply(this,args);
 };
 
+CAN_BE_SYNC.push('serialize');
+CookieJar.prototype.serialize = function(cb) {
+  var type = this.store.constructor.name;
+  if (type === 'Object') {
+    type = null;
+  }
+
+  // update README.md "Serialization Format" if you change this, please!
+  var serialized = {
+    // The version of tough-cookie that serialized this jar. Generally a good
+    // practice since future versions can make data import decisions based on
+    // known past behavior. When/if this matters, use `semver`.
+    version: 'tough-cookie@'+VERSION,
+
+    // add the store type, to make humans happy:
+    storeType: type,
+
+    // CookieJar configuration:
+    rejectPublicSuffixes: !!this.rejectPublicSuffixes,
+
+    // this gets filled from getAllCookies:
+    cookies: []
+  };
+
+  if (!(this.store.getAllCookies &&
+        typeof this.store.getAllCookies === 'function'))
+  {
+    return cb(new Error('store does not support getAllCookies and cannot be serialized'));
+  }
+
+  this.store.getAllCookies(function(err,cookies) {
+    if (err) {
+      return cb(err);
+    }
+
+    serialized.cookies = cookies.map(function(cookie) {
+      // convert to serialized 'raw' cookies
+      cookie = (cookie instanceof Cookie) ? cookie.toJSON() : cookie;
+
+      // Remove the index so new ones get assigned during deserialization
+      delete cookie.creationIndex;
+
+      return cookie;
+    });
+
+    return cb(null, serialized);
+  });
+};
+
+// well-known name that JSON.stringify calls
+CookieJar.prototype.toJSON = function() {
+  return this.serializeSync();
+};
+
+// use the class method CookieJar.deserialize instead of calling this directly
+CAN_BE_SYNC.push('_importCookies');
+CookieJar.prototype._importCookies = function(serialized, cb) {
+  var jar = this;
+  var cookies = serialized.cookies;
+  if (!cookies || !Array.isArray(cookies)) {
+    return cb(new Error('serialized jar has no cookies array'));
+  }
+
+  function putNext(err) {
+    if (err) {
+      return cb(err);
+    }
+
+    if (!cookies.length) {
+      return cb(err, jar);
+    }
+
+    var cookie;
+    try {
+      cookie = fromJSON(cookies.shift());
+    } catch (e) {
+      return cb(e);
+    }
+
+    if (cookie === null) {
+      return putNext(null); // skip this cookie
+    }
+
+    jar.store.putCookie(cookie, putNext);
+  }
+
+  putNext();
+};
+
+CookieJar.deserialize = function(strOrObj, store, cb) {
+  if (arguments.length !== 3) {
+    // store is optional
+    cb = store;
+    store = null;
+  }
+
+  var serialized;
+  if (typeof strOrObj === 'string') {
+    serialized = jsonParse(strOrObj);
+    if (serialized instanceof Error) {
+      return cb(serialized);
+    }
+  } else {
+    serialized = strOrObj;
+  }
+
+  var jar = new CookieJar(store, serialized.rejectPublicSuffixes);
+  jar._importCookies(serialized, function(err) {
+    if (err) {
+      return cb(err);
+    }
+    cb(null, jar);
+  });
+};
+
+CookieJar.fromJSON = CookieJar.deserializeSync;
+CookieJar.deserializeSync = function(strOrObj, store) {
+  var serialized = typeof strOrObj === 'string' ?
+    JSON.parse(strOrObj) : strOrObj;
+  var jar = new CookieJar(store, serialized.rejectPublicSuffixes);
+
+  // catch this mistake early:
+  if (!jar.store.synchronous) {
+    throw new Error('CookieJar store is not synchronous; use async API instead.');
+  }
+
+  jar._importCookiesSync(serialized);
+  return jar;
+};
+
+CAN_BE_SYNC.push('clone');
+CookieJar.prototype.clone = function(newStore, cb) {
+  if (arguments.length === 1) {
+    cb = newStore;
+    newStore = null;
+  }
+
+  this.serialize(function(err,serialized) {
+    if (err) {
+      return cb(err);
+    }
+    CookieJar.deserialize(newStore, serialized, cb);
+  });
+};
+
 // Use a closure to provide a true imperative API for synchronous stores.
 function syncWrap(method) {
   return function() {
@@ -1135,6 +1293,7 @@ module.exports = {
   CookieJar: CookieJar,
   Cookie: Cookie,
   Store: Store,
+  MemoryCookieStore: MemoryCookieStore,
   parseDate: parseDate,
   formatDate: formatDate,
   parse: parse,
@@ -1144,7 +1303,7 @@ module.exports = {
   pathMatch: pathMatch,
   getPublicSuffix: pubsuffix.getPublicSuffix,
   cookieCompare: cookieCompare,
-  permuteDomain: permuteDomain,
+  permuteDomain: require('./permuteDomain').permuteDomain,
   permutePath: permutePath,
-  canonicalDomain: canonicalDomain,
+  canonicalDomain: canonicalDomain
 };