@eggjs/cookies 3.0.0

package/src/cookie.ts

@@ -0,0 +1,160 @@
+import assert from 'node:assert';
+
+/**
+ * RegExp to match field-content in RFC 7230 sec 3.2
+ *
+ * field-content = field-vchar [ 1*( SP / HTAB ) field-vchar ]
+ * field-vchar   = VCHAR / obs-text
+ * obs-text      = %x80-FF
+ */
+const fieldContentRegExp = /^[\u0009\u0020-\u007e\u0080-\u00ff]+$/; // eslint-disable-line no-control-regex
+
+/**
+* RegExp to match Same-Site cookie attribute value.
+* https://en.wikipedia.org/wiki/HTTP_cookie#SameSite_cookie
+*/
+const sameSiteRegExp = /^(?:none|lax|strict)$/i;
+
+/**
+ * RegExp to match Priority cookie attribute value.
+ */
+const PRIORITY_REGEXP = /^(?:low|medium|high)$/i;
+
+export interface CookieSetOptions {
+  /**
+   * The path for the cookie to be set in
+   */
+  path?: string | null;
+  /**
+   * The domain for the cookie
+   */
+  domain?: string | (() => string);
+  /**
+   * Is overridable
+   */
+  overwrite?: boolean;
+  /**
+   * Is the same site
+   */
+  sameSite?: string | boolean;
+  /**
+   * Encrypt the cookie's value or not
+   */
+  encrypt?: boolean;
+  /**
+   * Max age for browsers
+   */
+  maxAge?: number;
+  /**
+   * Expire time
+   */
+  expires?: Date;
+  /**
+  * Is for http only
+  */
+  httpOnly?: boolean;
+  /**
+  * Encrypt the cookie's value or not
+  */
+  secure?: boolean;
+  /**
+   * Is it signed or not.
+   */
+  signed?: boolean | number;
+  /**
+   * Is it partitioned or not.
+   */
+  partitioned?: boolean;
+  /**
+   * Remove unpartitioned same name cookie or not.
+   */
+  removeUnpartitioned?: boolean;
+  /**
+   * The cookie priority.
+   */
+  priority?: 'low' | 'medium' | 'high' | 'LOW' | 'MEDIUM' | 'HIGH';
+}
+
+export class Cookie {
+  name: string;
+  value: string;
+  readonly attrs: CookieSetOptions;
+
+  constructor(name: string, value?: string | null, attrs?: CookieSetOptions) {
+    assert(fieldContentRegExp.test(name), 'argument name is invalid');
+    assert(!value || fieldContentRegExp.test(value), 'argument value is invalid');
+    this.name = name;
+    this.value = value ?? '';
+    this.attrs = mergeDefaultAttrs(attrs);
+    assert(!this.attrs.path || fieldContentRegExp.test(this.attrs.path),
+      'argument option path is invalid');
+    if (typeof this.attrs.domain === 'function') {
+      this.attrs.domain = this.attrs.domain();
+    }
+    assert(!this.attrs.domain || fieldContentRegExp.test(this.attrs.domain),
+      'argument option domain is invalid');
+    assert(!this.attrs.sameSite || this.attrs.sameSite === true || sameSiteRegExp.test(this.attrs.sameSite),
+      'argument option sameSite is invalid');
+    assert(!this.attrs.priority || PRIORITY_REGEXP.test(this.attrs.priority),
+      'argument option priority is invalid');
+    if (!value) {
+      this.attrs.expires = new Date(0);
+      // make sure maxAge is empty
+      this.attrs.maxAge = undefined;
+    }
+  }
+
+  toString() {
+    return this.name + '=' + this.value;
+  }
+
+  toHeader() {
+    let header = this.toString();
+    const attrs = this.attrs;
+    if (attrs.path) {
+      header += '; path=' + attrs.path;
+    }
+    const maxAge = typeof attrs.maxAge === 'string' ? parseInt(attrs.maxAge, 10) : attrs.maxAge;
+    // ignore 0, `session` and other invalid maxAge
+    if (maxAge) {
+      header += '; max-age=' + Math.round(maxAge / 1000);
+      attrs.expires = new Date(Date.now() + maxAge);
+    }
+    if (attrs.expires) {
+      header += '; expires=' + attrs.expires.toUTCString();
+    }
+    if (attrs.domain) {
+      header += '; domain=' + attrs.domain;
+    }
+    if (attrs.priority) {
+      header += '; priority=' + attrs.priority.toLowerCase();
+    }
+    if (attrs.sameSite) {
+      header += '; samesite=' + (attrs.sameSite === true ? 'strict' : attrs.sameSite.toLowerCase());
+    }
+    if (attrs.secure) {
+      header += '; secure';
+    }
+    if (attrs.httpOnly) {
+      header += '; httponly';
+    }
+    if (attrs.partitioned) {
+      header += '; partitioned';
+    }
+    return header;
+  }
+}
+
+function mergeDefaultAttrs(attrs?: CookieSetOptions) {
+  const merged = {
+    path: '/',
+    httpOnly: true,
+    secure: false,
+    overwrite: false,
+    sameSite: false,
+    partitioned: false,
+    priority: undefined,
+    ...attrs,
+  };
+  return merged;
+}

package/src/cookies.ts

@@ -0,0 +1,311 @@
+import assert from 'node:assert';
+import { base64decode, base64encode } from 'utility';
+import { isSameSiteNoneCompatible } from 'should-send-same-site-none';
+import { Keygrip } from './keygrip.js';
+import { Cookie, CookieSetOptions } from './cookie.js';
+import { CookieError } from './error.js';
+
+const keyCache = new Map<string[], Keygrip>();
+
+export interface DefaultCookieOptions extends CookieSetOptions {
+  /**
+   * Auto get and set `_CHIPS-` prefix cookie to adaptation CHIPS mode (The default value is false).
+   */
+  autoChips?: boolean;
+}
+
+export interface CookieGetOptions {
+  /**
+   * Whether to sign or not (The default value is true).
+   */
+  signed?: boolean;
+  /**
+   * Encrypt the cookie's value or not (The default value is false).
+   */
+  encrypt?: boolean;
+}
+
+/**
+ * cookies for egg
+ * extend pillarjs/cookies, add encrypt and decrypt
+ */
+export class Cookies {
+  readonly #keysArray: string[];
+  #keys: Keygrip;
+  readonly #defaultCookieOptions?: DefaultCookieOptions;
+  readonly #autoChips?: boolean;
+  readonly ctx: Record<string, any>;
+  readonly app: Record<string, any>;
+  readonly secure: boolean;
+  #parseChromiumResult?: ParseChromiumResult;
+
+  constructor(ctx: Record<string, any>, keys: string[], defaultCookieOptions?: DefaultCookieOptions) {
+    this.#keysArray = keys;
+    // default cookie options
+    this.#defaultCookieOptions = defaultCookieOptions;
+    this.#autoChips = defaultCookieOptions?.autoChips;
+    this.ctx = ctx;
+    this.secure = this.ctx.secure;
+    this.app = ctx.app;
+  }
+
+  get keys() {
+    if (!this.#keys) {
+      assert(Array.isArray(this.#keysArray), '.keys required for encrypt/sign cookies');
+      const cache = keyCache.get(this.#keysArray);
+      if (cache) {
+        this.#keys = cache;
+      } else {
+        this.#keys = new Keygrip(this.#keysArray);
+        keyCache.set(this.#keysArray, this.#keys);
+      }
+    }
+    return this.#keys;
+  }
+
+  /**
+   * get cookie value by name
+   * @param  {String} name - cookie's name
+   * @param  {Object} opts - cookies' options
+   *            - {Boolean} signed - default to true
+   *            - {Boolean} encrypt - default to false
+   * @return {String} value - cookie's value
+   */
+  get(name: string, opts: CookieGetOptions = {}): string | undefined {
+    let value = this._get(name, opts);
+    if (value === undefined && this.#autoChips) {
+      // try to read _CHIPS-${name} prefix cookie
+      value = this._get(this.#formatChipsCookieName(name), opts);
+    }
+    return value;
+  }
+
+  _get(name: string, opts: CookieGetOptions) {
+    const signed = computeSigned(opts);
+    const header: string = this.ctx.get('cookie');
+    if (!header) return;
+
+    const match = header.match(getPattern(name));
+    if (!match) return;
+
+    let value = match[1];
+    if (!opts.encrypt && !signed) return value;
+
+    // signed
+    if (signed) {
+      const sigName = name + '.sig';
+      const sigValue = this.get(sigName, { signed: false });
+      if (!sigValue) return;
+
+      const raw = name + '=' + value;
+      const index = this.keys.verify(raw, sigValue);
+      if (index < 0) {
+        // can not match any key, remove ${name}.sig
+        this.set(sigName, null, { path: '/', signed: false, overwrite: true });
+        return;
+      }
+      if (index > 0) {
+        // not signed by the first key, update sigValue
+        this.set(sigName, this.keys.sign(raw), { signed: false, overwrite: true });
+      }
+      return value;
+    }
+
+    // encrypt
+    value = base64decode(value, true, 'buffer') as string;
+    const res = this.keys.decrypt(value);
+    return res ? res.value.toString() : undefined;
+  }
+
+  set(name: string, value: string | null, opts?: CookieSetOptions) {
+    opts = {
+      ...this.#defaultCookieOptions,
+      ...opts,
+    };
+    const signed = computeSigned(opts);
+    value = value || '';
+    if (!this.secure && opts.secure) {
+      throw new CookieError('Cannot send secure cookie over unencrypted connection');
+    }
+
+    let headers: string[] = this.ctx.response.get('set-cookie') || [];
+    if (!Array.isArray(headers)) {
+      headers = [ headers ];
+    }
+
+    // encrypt
+    if (opts.encrypt) {
+      value = value && base64encode(this.keys.encrypt(value), true);
+    }
+
+    // http://browsercookielimits.squawky.net/
+    if (value.length > 4093) {
+      this.app.emit('cookieLimitExceed', { name, value, ctx: this.ctx });
+    }
+
+    // https://github.com/linsight/should-send-same-site-none
+    // fixed SameSite=None: Known Incompatible Clients
+    const userAgent: string | undefined = this.ctx.get('user-agent');
+    let isSameSiteNone = false;
+    // disable autoChips if partitioned enable
+    let autoChips = !opts.partitioned && this.#autoChips;
+    if (opts.sameSite && typeof opts.sameSite === 'string' && opts.sameSite.toLowerCase() === 'none') {
+      isSameSiteNone = true;
+      if (opts.secure === false || !this.secure || (userAgent && !this.isSameSiteNoneCompatible(userAgent))) {
+        // Non-secure context or Incompatible clients, don't send SameSite=None property
+        opts.sameSite = false;
+        isSameSiteNone = false;
+      }
+    }
+    if (autoChips || opts.partitioned) {
+      // allow to set partitioned: secure=true and sameSite=none and chrome >= 118
+      if (!isSameSiteNone || opts.secure === false || !this.secure || (userAgent && !this.isPartitionedCompatible(userAgent))) {
+        // Non-secure context or Incompatible clients, don't send partitioned property
+        autoChips = false;
+        opts.partitioned = false;
+      }
+    }
+
+    // remove unpartitioned same name cookie first
+    if (opts.partitioned && opts.removeUnpartitioned) {
+      const overwrite = opts.overwrite;
+      if (overwrite) {
+        opts.overwrite = false;
+        headers = ignoreCookiesByName(headers, name);
+      }
+      const removeCookieOpts = Object.assign({}, opts, {
+        partitioned: false,
+      });
+      const removeUnpartitionedCookie = new Cookie(name, '', removeCookieOpts);
+      // if user not set secure, reset secure to ctx.secure
+      if (opts.secure === undefined) {
+        removeUnpartitionedCookie.attrs.secure = this.secure;
+      }
+
+      headers = pushCookie(headers, removeUnpartitionedCookie);
+      // signed
+      if (signed) {
+        removeUnpartitionedCookie.name += '.sig';
+        headers = ignoreCookiesByName(headers, removeUnpartitionedCookie.name);
+        headers = pushCookie(headers, removeUnpartitionedCookie);
+      }
+    } else if (autoChips) {
+      // add _CHIPS-${name} prefix cookie
+      const newCookieName = this.#formatChipsCookieName(name);
+      const newCookieOpts = {
+        ...opts,
+        partitioned: true,
+      };
+      const newPartitionedCookie = new Cookie(newCookieName, value, newCookieOpts);
+      // if user not set secure, reset secure to ctx.secure
+      if (opts.secure === undefined) newPartitionedCookie.attrs.secure = this.secure;
+
+      headers = pushCookie(headers, newPartitionedCookie);
+      // signed
+      if (signed) {
+        newPartitionedCookie.value = value && this.keys.sign(newPartitionedCookie.toString());
+        newPartitionedCookie.name += '.sig';
+        headers = ignoreCookiesByName(headers, newPartitionedCookie.name);
+        headers = pushCookie(headers, newPartitionedCookie);
+      }
+    }
+
+    const cookie = new Cookie(name, value, opts);
+    // if user not set secure, reset secure to ctx.secure
+    if (opts.secure === undefined) {
+      cookie.attrs.secure = this.secure;
+    }
+    headers = pushCookie(headers, cookie);
+
+    // signed
+    if (signed) {
+      cookie.value = value && this.keys.sign(cookie.toString());
+      cookie.name += '.sig';
+      headers = pushCookie(headers, cookie);
+    }
+
+    this.ctx.set('set-cookie', headers);
+    return this;
+  }
+
+  #formatChipsCookieName(name: string) {
+    return `_CHIPS-${name}`;
+  }
+
+  #parseChromiumAndMajorVersion(userAgent: string) {
+    if (!this.#parseChromiumResult) {
+      this.#parseChromiumResult = parseChromiumAndMajorVersion(userAgent);
+    }
+    return this.#parseChromiumResult;
+  }
+
+  isSameSiteNoneCompatible(userAgent: string) {
+    // Chrome >= 80.0.0.0
+    const result = this.#parseChromiumAndMajorVersion(userAgent);
+    if (result.chromium) {
+      return result.majorVersion >= 80;
+    }
+    return isSameSiteNoneCompatible(userAgent);
+  }
+
+  isPartitionedCompatible(userAgent: string) {
+    // support: Chrome >= 114.0.0.0
+    // default enable: Chrome >= 118.0.0.0
+    // https://developers.google.com/privacy-sandbox/3pcd/chips
+    const result = this.#parseChromiumAndMajorVersion(userAgent);
+    if (result.chromium) {
+      return result.majorVersion >= 118;
+    }
+    return false;
+  }
+}
+
+interface ParseChromiumResult {
+  chromium: boolean;
+  majorVersion: number;
+}
+
+// https://github.com/linsight/should-send-same-site-none/blob/master/index.js#L86
+function parseChromiumAndMajorVersion(userAgent: string): ParseChromiumResult {
+  const m = /Chrom[^ /]{1,100}\/(\d{1,100}?)\./.exec(userAgent);
+  if (!m) {
+    return { chromium: false, majorVersion: 0 };
+  }
+  // Extract digits from first capturing group.
+  return { chromium: true, majorVersion: parseInt(m[1]) };
+}
+
+const _patternCache = new Map<string, RegExp>();
+function getPattern(name: string) {
+  const cache = _patternCache.get(name);
+  if (cache) {
+    return cache;
+  }
+  const reg = new RegExp(
+    '(?:^|;) *' +
+    name.replace(/[-[\]{}()*+?.,\\^$|#\s]/g, '\\$&') +
+    '=([^;]*)',
+  );
+  _patternCache.set(name, reg);
+  return reg;
+}
+
+function computeSigned(opts: { encrypt?: boolean; signed?: boolean | number }) {
+  // encrypt default to false, signed default to true.
+  // disable singed when encrypt is true.
+  if (opts.encrypt) return false;
+  return opts.signed !== false;
+}
+
+function pushCookie(cookies: string[], cookie: Cookie) {
+  if (cookie.attrs.overwrite) {
+    cookies = ignoreCookiesByName(cookies, cookie.name);
+  }
+  cookies.push(cookie.toHeader());
+  return cookies;
+}
+
+function ignoreCookiesByName(cookies: string[], name: string) {
+  const prefix = `${name}=`;
+  return cookies.filter(c => !c.startsWith(prefix));
+}

package/src/error.ts

@@ -0,0 +1,6 @@
+export class CookieError extends Error {
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = this.constructor.name;
+  }
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from './cookies.js';
+export * from './cookie.js';
+export * from './error.js';
+export * from './keygrip.js';

package/src/keygrip.ts

@@ -0,0 +1,129 @@
+import { debuglog } from 'node:util';
+import crypto, { type Cipher } from 'node:crypto';
+import assert from 'node:assert';
+
+const debug = debuglog('@eggjs/cookies:keygrip');
+
+const KEY_LEN = 32;
+const IV_SIZE = 16;
+const passwordCache = new Map();
+
+const replacer: Record<string, string> = {
+  '/': '_',
+  '+': '-',
+  '=': '',
+};
+
+function constantTimeCompare(a: Buffer, b: Buffer) {
+  if (a.length !== b.length) {
+    return false;
+  }
+  return crypto.timingSafeEqual(a, b);
+}
+
+// patch from https://github.com/crypto-utils/keygrip
+
+export class Keygrip {
+  readonly #keys: string[];
+  readonly #hash = 'sha256';
+  readonly #cipher = 'aes-256-cbc';
+
+  constructor(keys: string[]) {
+    assert(Array.isArray(keys) && keys.length > 0, 'keys must be provided and should be an array');
+    this.#keys = keys;
+  }
+
+  // encrypt a message
+  encrypt(data: string, key?: string) {
+    key = key || this.#keys[0];
+    const password = keyToPassword(key);
+    const cipher = crypto.createCipheriv(this.#cipher, password.key, password.iv);
+    return crypt(cipher, data);
+  }
+
+  // decrypt a single message
+  // returns false on bad decrypts
+  decrypt(data: string | Buffer): { value: Buffer, index: number } | false {
+    // decrypt every key
+    const keys = this.#keys;
+    for (let i = 0; i < keys.length; i++) {
+      const value = this.#decryptByKey(data, keys[i]);
+      if (value !== false) {
+        return { value, index: i };
+      }
+    }
+    return false;
+  }
+
+  #decryptByKey(data: string | Buffer, key: string) {
+    try {
+      const password = keyToPassword(key);
+      const cipher = crypto.createDecipheriv(this.#cipher, password.key, password.iv);
+      return crypt(cipher, data);
+    } catch (err: any) {
+      debug('crypt error: %s', err);
+      return false;
+    }
+  }
+
+  sign(data: string | Buffer, key?: string) {
+    // default to the first key
+    key = key || this.#keys[0];
+
+    // url safe base64
+    return crypto
+      .createHmac(this.#hash, key)
+      .update(data)
+      .digest('base64')
+      .replace(/\/|\+|=/g, x => {
+        return replacer[x];
+      });
+  }
+
+  verify(data: string, digest: string) {
+    const keys = this.#keys;
+    for (let i = 0; i < keys.length; i++) {
+      const key = keys[i];
+      if (constantTimeCompare(Buffer.from(digest), Buffer.from(this.sign(data, key)))) {
+        debug('data %s match key %s, index: %d', data, key, i);
+        return i;
+      }
+    }
+    return -1;
+  }
+}
+
+function crypt(cipher: Cipher, data: string | Buffer) {
+  const text = Buffer.isBuffer(data) ? cipher.update(data) : cipher.update(data, 'utf-8');
+  const pad = cipher.final();
+  return Buffer.concat([ text, pad ]);
+}
+
+function keyToPassword(key: string) {
+  if (passwordCache.has(key)) {
+    return passwordCache.get(key);
+  }
+
+  // Simulate EVP_BytesToKey.
+  // see https://github.com/nodejs/help/issues/1673#issuecomment-503222925
+  const bytes = Buffer.alloc(KEY_LEN + IV_SIZE);
+  let lastHash = null,
+    nBytes = 0;
+  while (nBytes < bytes.length) {
+    const hash = crypto.createHash('md5');
+    if (lastHash) hash.update(lastHash);
+    hash.update(key);
+    lastHash = hash.digest();
+    lastHash.copy(bytes, nBytes);
+    nBytes += lastHash.length;
+  }
+
+  // Use these for decryption.
+  const password = {
+    key: bytes.subarray(0, KEY_LEN),
+    iv: bytes.subarray(KEY_LEN, bytes.length),
+  };
+
+  passwordCache.set(key, password);
+  return password;
+}