@eggjs/security 4.0.0

package/src/lib/helper/spath.ts

@@ -0,0 +1,27 @@
+/**
+ * File Inclusion
+ */
+
+import type { BaseContextClass } from '@eggjs/core';
+
+export default function pathFilter(this: BaseContextClass, path: string) {
+  if (typeof path !== 'string') return path;
+
+  const pathSource = path;
+
+  while (path.indexOf('%') !== -1) {
+    try {
+      path = decodeURIComponent(path);
+    } catch (e) {
+      if (process.env.NODE_ENV !== 'production') {
+        // Not a PROD env, logging with a warning.
+        this.ctx.coreLogger.warn('[@eggjs/security/lib/helper/spath] : decode file path %j failed.', path);
+      }
+      break;
+    }
+  }
+  if (path.indexOf('..') !== -1 || path[0] === '/') {
+    return null;
+  }
+  return pathSource;
+}

package/src/lib/helper/surl.ts

@@ -0,0 +1,35 @@
+import type { BaseContextClass } from '@eggjs/core';
+
+const escapeMap: Record<string, string> = {
+  '"': '&quot;',
+  '<': '&lt;',
+  '>': '&gt;',
+  '\'': '&#x27;',
+};
+
+export default function surl(this: BaseContextClass, val: string) {
+  // Just get the converted the protocolWhiteList in `Set` mode,
+  // Avoid conversions in `foreach`
+  const protocolWhiteListSet = this.app.config.security.__protocolWhiteListSet!;
+
+  if (typeof val !== 'string') {
+    return val;
+  }
+
+  // only test on absolute path
+  if (val[0] !== '/') {
+    const arr = val.split('://', 2);
+    const protocol = arr.length > 1 ? arr[0].toLowerCase() : '';
+    if (protocol === '' || !protocolWhiteListSet.has(protocol)) {
+      if (this.app.config.env === 'local') {
+        this.ctx.coreLogger.warn('[@eggjs/security/surl] url: %j, protocol: %j, ' +
+          'protocol is empty or not in white list, convert to empty string', val, protocol);
+      }
+      return '';
+    }
+  }
+
+  return val.replace(/["'<>]/g, ch => {
+    return escapeMap[ch];
+  });
+}

package/src/lib/middlewares/csp.ts

@@ -0,0 +1,70 @@
+import extend from 'extend';
+import type { Context, Next } from '@eggjs/core';
+import { checkIfIgnore } from '../utils.js';
+import type { SecurityConfig } from '../../types.js';
+
+const HEADER = [
+  'x-content-security-policy',
+  'content-security-policy',
+];
+const REPORT_ONLY_HEADER = [
+  'x-content-security-policy-report-only',
+  'content-security-policy-report-only',
+];
+
+// Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1)
+const MSIE_REGEXP = / MSIE /i;
+
+export default (options: SecurityConfig['csp']) => {
+  return async function csp(ctx: Context, next: Next) {
+    await next();
+
+    const opts = {
+      ...options,
+      ...ctx.securityOptions.csp,
+    };
+    if (checkIfIgnore(opts, ctx)) return;
+
+    let finalHeader;
+    const matchedOption = extend(true, {}, opts.policy);
+    const bufArray = [];
+
+    const headers = opts.reportOnly ? REPORT_ONLY_HEADER : HEADER;
+    if (opts.supportIE && MSIE_REGEXP.test(ctx.get('user-agent'))) {
+      finalHeader = headers[0];
+    } else {
+      finalHeader = headers[1];
+    }
+
+    for (const key in matchedOption) {
+      const value = matchedOption[key];
+      // Other arrays are splitted into strings EXCEPT `sandbox`
+      // https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/sandbox
+      if (key === 'sandbox' && value === true) {
+        bufArray.push(key);
+      } else {
+        let values = (Array.isArray(value) ? value : [ value ]) as string[];
+        if (key === 'script-src') {
+          const hasNonce = values.some(function(val) {
+            return val.indexOf('nonce-') !== -1;
+          });
+
+          if (!hasNonce) {
+            values.push('\'nonce-' + ctx.nonce + '\'');
+          }
+        }
+
+        values = values.map(function(d) {
+          if (d.startsWith('.')) {
+            d = '*' + d;
+          }
+          return d;
+        });
+        bufArray.push(key + ' ' + values.join(' '));
+      }
+    }
+    const headerString = bufArray.join(';');
+    ctx.set(finalHeader, headerString);
+    ctx.set('x-csp-nonce', ctx.nonce);
+  };
+};

package/src/lib/middlewares/csrf.ts

@@ -0,0 +1,44 @@
+import { debuglog } from 'node:util';
+import type { Context, Next } from '@eggjs/core';
+import typeis from 'type-is';
+import { checkIfIgnore } from '../utils.js';
+import type { SecurityConfig } from '../../types.js';
+
+const debug = debuglog('@eggjs/security/lib/middlewares/csrf');
+
+export default (options: SecurityConfig['csrf']) => {
+  return function csrf(ctx: Context, next: Next) {
+    if (checkIfIgnore(options, ctx)) {
+      return next();
+    }
+
+    // ensure csrf token exists
+    if ([ 'any', 'all', 'ctoken' ].includes(options.type)) {
+      ctx.ensureCsrfSecret();
+    }
+
+    // supported requests
+    const method = ctx.method;
+    let isSupported = false;
+    for (const eachRule of options.supportedRequests) {
+      if (eachRule.path.test(ctx.path)) {
+        if (eachRule.methods.includes(method)) {
+          isSupported = true;
+          break;
+        }
+      }
+    }
+    if (!isSupported) {
+      return next();
+    }
+
+    if (options.ignoreJSON && typeis.is(ctx.get('content-type'), 'json')) {
+      return next();
+    }
+
+    const body = ctx.request.body;
+    debug('%s %s, got %j', ctx.method, ctx.url, body);
+    ctx.assertCsrf();
+    return next();
+  };
+};

package/src/lib/middlewares/dta.ts

@@ -0,0 +1,13 @@
+import type { Context, Next } from '@eggjs/core';
+import { isSafePath } from '../utils.js';
+
+// https://en.wikipedia.org/wiki/Directory_traversal_attack
+export default () => {
+  return function dta(ctx: Context, next: Next) {
+    const path = ctx.path;
+    if (!isSafePath(path, ctx)) {
+      ctx.throw(400);
+    }
+    return next();
+  };
+};

package/src/lib/middlewares/hsts.ts

@@ -0,0 +1,24 @@
+import type { Context, Next } from '@eggjs/core';
+import { checkIfIgnore } from '../utils.js';
+import type { SecurityConfig } from '../../types.js';
+
+// Set Strict-Transport-Security header
+export default (options: SecurityConfig['hsts']) => {
+  return async function hsts(ctx: Context, next: Next) {
+    await next();
+
+    const opts = {
+      ...options,
+      ...ctx.securityOptions.hsts,
+    };
+    if (checkIfIgnore(opts, ctx)) return;
+
+    let val = 'max-age=' + opts.maxAge;
+    // If opts.includeSubdomains is defined,
+    // the rule is also valid for all the sub domains of the website
+    if (opts.includeSubdomains) {
+      val += '; includeSubdomains';
+    }
+    ctx.set('strict-transport-security', val);
+  };
+};

package/src/lib/middlewares/index.ts

@@ -0,0 +1,23 @@
+import csp from './csp.js';
+import csrf from './csrf.js';
+import dta from './dta.js';
+import hsts from './hsts.js';
+import methodnoallow from './methodnoallow.js';
+import noopen from './noopen.js';
+import nosniff from './nosniff.js';
+import referrerPolicy from './referrerPolicy.js';
+import xframe from './xframe.js';
+import xssProtection from './xssProtection.js';
+
+export default {
+  csp,
+  csrf,
+  dta,
+  hsts,
+  methodnoallow,
+  noopen,
+  nosniff,
+  referrerPolicy,
+  xframe,
+  xssProtection,
+};

package/src/lib/middlewares/methodnoallow.ts

@@ -0,0 +1,23 @@
+import { METHODS } from 'node:http';
+import type { Context, Next } from '@eggjs/core';
+
+const METHODS_NOT_ALLOWED = [ 'TRACE', 'TRACK' ];
+const safeHttpMethodsMap: Record<string, boolean> = {};
+
+for (const method of METHODS) {
+  if (!METHODS_NOT_ALLOWED.includes(method)) {
+    safeHttpMethodsMap[method.toUpperCase()] = true;
+  }
+}
+
+// https://www.owasp.org/index.php/Cross_Site_Tracing
+// http://jsperf.com/find-by-map-with-find-by-array
+export default () => {
+  return function notAllow(ctx: Context, next: Next) {
+    // ctx.method is upper case
+    if (!safeHttpMethodsMap[ctx.method]) {
+      ctx.throw(405);
+    }
+    return next();
+  };
+};

package/src/lib/middlewares/noopen.ts

@@ -0,0 +1,18 @@
+import type { Context, Next } from '@eggjs/core';
+import { checkIfIgnore } from '../utils.js';
+import type { SecurityConfig } from '../../types.js';
+
+// @see http://blogs.msdn.com/b/ieinternals/archive/2009/06/30/internet-explorer-custom-http-headers.aspx
+export default (options: SecurityConfig['noopen']) => {
+  return async function noopen(ctx: Context, next: Next) {
+    await next();
+
+    const opts = {
+      ...options,
+      ...ctx.securityOptions.noopen,
+    };
+    if (checkIfIgnore(opts, ctx)) return;
+
+    ctx.set('x-download-options', 'noopen');
+  };
+};

package/src/lib/middlewares/nosniff.ts

@@ -0,0 +1,32 @@
+import type { Context, Next } from '@eggjs/core';
+import { checkIfIgnore } from '../utils.js';
+import type { SecurityConfig } from '../../types.js';
+
+// status codes for redirects
+// @see https://github.com/jshttp/statuses/blob/master/index.js#L33
+const RedirectStatus: Record<number, boolean> = {
+  300: true,
+  301: true,
+  302: true,
+  303: true,
+  305: true,
+  307: true,
+  308: true,
+};
+
+export default (options: SecurityConfig['nosniff']) => {
+  return async function nosniff(ctx: Context, next: Next) {
+    await next();
+
+    // ignore redirect response
+    if (RedirectStatus[ctx.status]) return;
+
+    const opts = {
+      ...options,
+      ...ctx.securityOptions.nosniff,
+    };
+    if (checkIfIgnore(opts, ctx)) return;
+
+    ctx.set('x-content-type-options', 'nosniff');
+  };
+};

package/src/lib/middlewares/referrerPolicy.ts

@@ -0,0 +1,39 @@
+import type { Context, Next } from '@eggjs/core';
+import { checkIfIgnore } from '../utils.js';
+import type { SecurityConfig } from '../../types.js';
+
+// https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Headers/Referrer-Policy
+const ALLOWED_POLICIES_ENUM = [
+  'no-referrer',
+  'no-referrer-when-downgrade',
+  'origin',
+  'origin-when-cross-origin',
+  'same-origin',
+  'strict-origin',
+  'strict-origin-when-cross-origin',
+  'unsafe-url',
+  '',
+];
+
+export default (options: SecurityConfig['referrerPolicy']) => {
+  return async function referrerPolicy(ctx: Context, next: Next) {
+    await next();
+
+    const opts = {
+      ...options,
+      // check refererPolicy for backward compatibility
+      // typo on the old version
+      // @see https://github.com/eggjs/security/blob/e3408408adec5f8d009d37f75126ed082481d0ac/lib/middlewares/referrerPolicy.js#L21C59-L21C72
+      ...(ctx.securityOptions as any).refererPolicy,
+      ...ctx.securityOptions.referrerPolicy,
+    };
+    if (checkIfIgnore(opts, ctx)) return;
+
+    const policy = opts.value;
+    if (!ALLOWED_POLICIES_ENUM.includes(policy)) {
+      throw new Error('"' + policy + '" is not available.');
+    }
+
+    ctx.set('referrer-policy', policy);
+  };
+};

package/src/lib/middlewares/xframe.ts

@@ -0,0 +1,20 @@
+import type { Context, Next } from '@eggjs/core';
+import { checkIfIgnore } from '../utils.js';
+import type { SecurityConfig } from '../../types.js';
+
+export default (options: SecurityConfig['xframe']) => {
+  return async function xframe(ctx: Context, next: Next) {
+    await next();
+
+    const opts = {
+      ...options,
+      ...ctx.securityOptions.xframe,
+    };
+    if (checkIfIgnore(opts, ctx)) return;
+
+    // DENY, SAMEORIGIN, ALLOW-FROM
+    // https://developer.mozilla.org/en-US/docs/HTTP/X-Frame-Options?redirectlocale=en-US&redirectslug=The_X-FRAME-OPTIONS_response_header
+    const value = opts.value || 'SAMEORIGIN';
+    ctx.set('x-frame-options', value);
+  };
+};

package/src/lib/middlewares/xssProtection.ts

@@ -0,0 +1,17 @@
+import type { Context, Next } from '@eggjs/core';
+import { checkIfIgnore } from '../utils.js';
+import type { SecurityConfig } from '../../types.js';
+
+export default (options: SecurityConfig['xssProtection']) => {
+  return async function xssProtection(ctx: Context, next: Next) {
+    await next();
+
+    const opts = {
+      ...options,
+      ...ctx.securityOptions.xssProtection,
+    };
+    if (checkIfIgnore(opts, ctx)) return;
+
+    ctx.set('x-xss-protection', opts.value);
+  };
+};

package/src/lib/utils.ts

@@ -0,0 +1,208 @@
+import { normalize } from 'node:path';
+import matcher from 'matcher';
+import IP from '@eggjs/ip';
+import { Context } from '@eggjs/core';
+import type { PathMatchingFun } from 'egg-path-matching';
+import { SecurityConfig } from '../types.js';
+
+/**
+ * Check whether a domain is in the safe domain white list or not.
+ * @param {String} domain The inputted domain.
+ * @param {Array<string>} whiteList The white list for domain.
+ * @return {Boolean} If the `domain` is in the white list, return true; otherwise false.
+ */
+export function isSafeDomain(domain: string, whiteList: string[]): boolean {
+  // domain must be string, otherwise return false
+  if (typeof domain !== 'string') return false;
+  // Ignore case sensitive first
+  domain = domain.toLowerCase();
+  // add prefix `.`, because all domains in white list start with `.`
+  const hostname = '.' + domain;
+
+  return whiteList.some(rule => {
+    // Check whether we've got '*' as a wild character symbol
+    if (rule.includes('*')) {
+      return matcher.isMatch(domain, rule);
+    }
+    // If domain is an absolute path such as `http://...`
+    // We can directly check whether it directly equals to `domain`
+    // And we don't need to cope with `endWith`.
+    if (domain === rule) return true;
+    // ensure wwweggjs.com not match eggjs.com
+    if (!/^\./.test(rule)) rule = `.${rule}`;
+    return hostname.endsWith(rule);
+  });
+}
+
+export function isSafePath(path: string, ctx: Context) {
+  path = '.' + path;
+  if (path.includes('%')) {
+    try {
+      path = decodeURIComponent(path);
+    } catch (e) {
+      if (ctx.app.config.env === 'local' || ctx.app.config.env === 'unittest') {
+        // not under production environment, output log
+        ctx.coreLogger.warn('[@eggjs/security: dta global block] : decode file path %j failed.', path);
+      }
+    }
+  }
+  const normalizePath = normalize(path);
+  return !(normalizePath.startsWith('../') || normalizePath.startsWith('..\\'));
+}
+
+export function checkIfIgnore(opts: { enable: boolean; matching?: PathMatchingFun; }, ctx: Context) {
+  // check opts.enable first
+  if (!opts.enable) return true;
+  return !opts.matching?.(ctx);
+}
+
+const IP_RE = /^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$/;
+const topDomains: Record<string, number> = {};
+[
+  '.net.cn', '.gov.cn', '.org.cn', '.com.cn',
+].forEach(item => {
+  topDomains[item] = 2 - item.split('.').length;
+});
+
+export function getCookieDomain(hostname: string) {
+  // TODO(fengmk2): support ipv6
+  if (IP_RE.test(hostname)) {
+    return hostname;
+  }
+  // app.test.domain.com => .test.domain.com
+  // app.stable.domain.com => .domain.com
+  // app.domain.com => .domain.com
+  // domain=.domain.com;
+  const splits = hostname.split('.');
+  let index = -2;
+
+  // only when `*.test.*.com` set `.test.*.com`
+  if (splits.length >= 4 && splits[splits.length - 3] === 'test') {
+    index = -3;
+  }
+  let domain = getDomain(splits, index);
+  if (topDomains[domain]) {
+    // app.foo.org.cn => .foo.org.cn
+    domain = getDomain(splits, index + topDomains[domain]);
+  }
+  return domain;
+}
+
+function getDomain(splits: string[], index: number) {
+  return '.' + splits.slice(index).join('.');
+}
+
+export function merge(origin: Record<string, any>, opts?: Record<string, any>) {
+  if (!opts) {
+    return origin;
+  }
+  const res: Record<string, any> = {};
+
+  const originKeys = Object.keys(origin);
+  for (let i = 0; i < originKeys.length; i++) {
+    const key = originKeys[i];
+    res[key] = origin[key];
+  }
+
+  const keys = Object.keys(opts);
+  for (let i = 0; i < keys.length; i++) {
+    const key = keys[i];
+    res[key] = opts[key];
+  }
+  return res;
+}
+
+export function preprocessConfig(config: SecurityConfig) {
+  // transfer ssrf.ipBlackList to ssrf.checkAddress
+  // ssrf.ipExceptionList can easily pick out unwanted ips from ipBlackList
+  // checkAddress has higher priority than ipBlackList
+  const ssrf = config.ssrf;
+  if (ssrf && ssrf.ipBlackList && !ssrf.checkAddress) {
+    const blackList = ssrf.ipBlackList.map(getContains);
+    const exceptionList = (ssrf.ipExceptionList || []).map(getContains);
+    const hostnameExceptionList = ssrf.hostnameExceptionList;
+    ssrf.checkAddress = (ipAddresses, _family, hostname) => {
+      // Check white hostname first
+      if (hostname && hostnameExceptionList) {
+        if (hostnameExceptionList.includes(hostname)) {
+          return true;
+        }
+      }
+      // ipAddresses will be array address on Node.js >= 20
+      // [
+      //   { address: '220.181.125.241', family: 4 },
+      //   { address: '240e:964:ea02:b00:3::3ec', family: 6 }
+      // ]
+      if (!Array.isArray(ipAddresses)) {
+        ipAddresses = [ ipAddresses ];
+      }
+      for (const ipAddress of ipAddresses) {
+        let address: string;
+        if (typeof ipAddress === 'string') {
+          address = ipAddress;
+        } else {
+          // FIXME: should support ipv6
+          if (ipAddress.family === 6) {
+            continue;
+          }
+          address = ipAddress.address;
+        }
+        // check white list first
+        for (const exception of exceptionList) {
+          if (exception(address)) {
+            return true;
+          }
+        }
+        // check black list
+        for (const contains of blackList) {
+          if (contains(address)) {
+            return false;
+          }
+        }
+      }
+      // default allow
+      return true;
+    };
+  }
+
+  // Make sure that `whiteList` or `protocolWhiteList` is case insensitive
+  config.domainWhiteList = config.domainWhiteList || [];
+  config.domainWhiteList = config.domainWhiteList.map((domain: string) => domain.toLowerCase());
+
+  config.protocolWhiteList = config.protocolWhiteList || [];
+  config.protocolWhiteList = config.protocolWhiteList.map((protocol: string) => protocol.toLowerCase());
+
+  // Make sure refererWhiteList is case insensitive
+  if (config.csrf && config.csrf.refererWhiteList) {
+    config.csrf.refererWhiteList = config.csrf.refererWhiteList.map((ref: string) => ref.toLowerCase());
+  }
+
+  // Directly converted to Set collection by a private property (not documented),
+  // And we NO LONGER need to do conversion in `foreach` again and again in `lib/helper/surl.ts`.
+  const protocolWhiteListSet = new Set(config.protocolWhiteList);
+  protocolWhiteListSet.add('http');
+  protocolWhiteListSet.add('https');
+  protocolWhiteListSet.add('file');
+  protocolWhiteListSet.add('data');
+
+  Object.defineProperty(config, '__protocolWhiteListSet', {
+    value: protocolWhiteListSet,
+    enumerable: false,
+  });
+}
+
+export function getFromUrl(url: string, prop?: string): string | null {
+  try {
+    const parsed = new URL(url);
+    return prop ? Reflect.get(parsed, prop) : parsed;
+  } catch {
+    return null;
+  }
+}
+
+function getContains(ip: string) {
+  if (IP.isV4Format(ip) || IP.isV6Format(ip)) {
+    return (address: string) => address === ip;
+  }
+  return IP.cidrSubnet(ip).contains;
+}

package/src/types.ts

@@ -0,0 +1,16 @@
+import './app/extend/application.js';
+import './app/extend/context.js';
+import type {
+  SecurityConfig,
+  SecurityHelperConfig,
+} from './config/config.default.js';
+
+export type * from './config/config.default.js';
+
+declare module '@eggjs/core' {
+  // add EggAppConfig overrides types
+  interface EggAppConfig {
+    security: SecurityConfig;
+    helper: SecurityHelperConfig;
+  }
+}

package/src/typings/index.d.ts

@@ -0,0 +1,4 @@
+// make sure to import egg typings and let typescript know about it
+// @see https://github.com/whxaxes/blog/issues/11
+// and https://www.typescriptlang.org/docs/handbook/declaration-merging.html
+import 'egg';