@eggjs/security 4.0.0

package/src/config/config.default.ts

@@ -0,0 +1,379 @@
+import z from 'zod';
+import { Context } from '@eggjs/core';
+
+const CSRFSupportRequestItem = z.object({
+  path: z.instanceof(RegExp),
+  methods: z.array(z.string()),
+});
+export type CSRFSupportRequestItem = z.infer<typeof CSRFSupportRequestItem>;
+
+export const LookupAddress = z.object({
+  address: z.string(),
+  family: z.number(),
+});
+export type LookupAddress = z.infer<typeof LookupAddress>;
+
+const LookupAddressAndStringArray = z.union([ z.string(), LookupAddress ]).array();
+const SSRFCheckAddressFunction = z.function()
+  .args(z.union([ z.string(), LookupAddress, LookupAddressAndStringArray ]), z.union([ z.number(), z.string() ]), z.string())
+  .returns(z.boolean());
+/**
+ * SSRF check address function
+ * `(address, family, hostname) => boolean`
+ */
+export type SSRFCheckAddressFunction = z.infer<typeof SSRFCheckAddressFunction>;
+
+export const SecurityMiddlewareName = z.enum([
+  'csrf',
+  'hsts',
+  'methodnoallow',
+  'noopen',
+  'nosniff',
+  'csp',
+  'xssProtection',
+  'xframe',
+  'dta',
+]);
+export type SecurityMiddlewareName = z.infer<typeof SecurityMiddlewareName>;
+
+/**
+ * (ctx) => boolean
+ */
+const IgnoreOrMatchHandler = z.function().args(z.instanceof(Context)).returns(z.boolean());
+export type IgnoreOrMatchHandler = z.infer<typeof IgnoreOrMatchHandler>;
+
+const IgnoreOrMatch = z.union([
+  z.string(), z.instanceof(RegExp), IgnoreOrMatchHandler,
+]);
+export type IgnoreOrMatch = z.infer<typeof IgnoreOrMatch>;
+
+const IgnoreOrMatchOption = z.union([ IgnoreOrMatch, IgnoreOrMatch.array() ]).optional();
+export type IgnoreOrMatchOption = z.infer<typeof IgnoreOrMatchOption>;
+
+/**
+ * security options
+ * @member Config#security
+ */
+export const SecurityConfig = z.object({
+  /**
+   * domain white list
+   *
+   * Default to `[]`
+   */
+  domainWhiteList: z.array(z.string()).default([]),
+  /**
+   * protocol white list
+   *
+   * Default to `[]`
+   */
+  protocolWhiteList: z.array(z.string()).default([]),
+  /**
+   * default open security middleware
+   *
+   * Default to `'csrf,hsts,methodnoallow,noopen,nosniff,csp,xssProtection,xframe,dta'`
+   */
+  defaultMiddleware: z.union([ z.string(), z.array(SecurityMiddlewareName) ])
+    .default(SecurityMiddlewareName.options),
+  /**
+   * whether defend csrf attack
+   */
+  csrf: z.preprocess(val => {
+    // transform old config, `csrf: false` to `csrf: { enable: false }`
+    if (typeof val === 'boolean') {
+      return { enable: val };
+    }
+    return val;
+  }, z.object({
+    match: IgnoreOrMatchOption,
+    ignore: IgnoreOrMatchOption,
+    /**
+     * Default to `true`
+     */
+    enable: z.boolean().default(true),
+    /**
+     * csrf token detect source type
+     *
+     * Default to `'ctoken'`
+     */
+    type: z.enum([ 'ctoken', 'referer', 'all', 'any' ]).default('ctoken'),
+    /**
+     * ignore json request
+     *
+     * Default to `false`
+     *
+     * @deprecated is not safe now, don't use it
+     */
+    ignoreJSON: z.boolean().default(false),
+    /**
+     * csrf token cookie name
+     *
+     * Default to `'csrfToken'`
+     */
+    cookieName: z.union([ z.string(), z.array(z.string()) ]).default('csrfToken'),
+    /**
+     * csrf token session name
+     *
+     * Default to `'csrfToken'`
+     */
+    sessionName: z.string().default('csrfToken'),
+    /**
+     * csrf token request header name
+     *
+     * Default to `'x-csrf-token'`
+     */
+    headerName: z.string().default('x-csrf-token'),
+    /**
+     * csrf token request body field name
+     *
+     * Default to `'_csrf'`
+     */
+    bodyName: z.union([ z.string(), z.array(z.string()) ]).default('_csrf'),
+    /**
+     * csrf token request query field name
+     *
+     * Default to `'_csrf'`
+     */
+    queryName: z.union([ z.string(), z.array(z.string()) ]).default('_csrf'),
+    /**
+     * rotate csrf token when it is invalid
+     *
+     * Default to `false`
+     */
+    rotateWhenInvalid: z.boolean().default(false),
+    /**
+     * These config works when using `'ctoken'` type
+     *
+     * Default to `false`
+     */
+    useSession: z.boolean().default(false),
+    /**
+     * csrf token cookie domain setting,
+     * can be `(ctx) => string` or `string`
+     *
+     * Default to `undefined`, auto set the cookie domain in the safe way
+     */
+    cookieDomain: z.union([
+      z.string(),
+      z.function()
+        .args(z.instanceof(Context))
+        .returns(z.string()),
+    ]).optional(),
+    /**
+     * csrf token check requests config
+     */
+    supportedRequests: z.array(CSRFSupportRequestItem)
+      .default([
+        { path: /^\//, methods: [ 'POST', 'PATCH', 'DELETE', 'PUT', 'CONNECT' ] },
+      ]),
+    /**
+     * referer or origin header white list.
+     * It only works when using `'referer'` type
+     *
+     * Default to `[]`
+     */
+    refererWhiteList: z.array(z.string()).default([]),
+    /**
+     * csrf token cookie options
+     *
+     * Default to `{
+     *   signed: false,
+     *   httpOnly: false,
+     *   overwrite: true,
+     * }`
+     */
+    cookieOptions: z.object({
+      signed: z.boolean(),
+      httpOnly: z.boolean(),
+      overwrite: z.boolean(),
+    }).default({
+      signed: false,
+      httpOnly: false,
+      overwrite: true,
+    }),
+  }).default({})),
+  /**
+   * whether enable X-Frame-Options response header
+   */
+  xframe: z.object({
+    match: IgnoreOrMatchOption,
+    ignore: IgnoreOrMatchOption,
+    /**
+     * Default to `true`
+     */
+    enable: z.boolean().default(true),
+    /**
+     * X-Frame-Options value, can be `'DENY'`, `'SAMEORIGIN'`, `'ALLOW-FROM https://example.com'`
+     *
+     * Default to `'SAMEORIGIN'`
+     */
+    value: z.string().default('SAMEORIGIN'),
+  }).default({}),
+  /**
+   * whether enable Strict-Transport-Security response header
+   */
+  hsts: z.object({
+    match: IgnoreOrMatchOption,
+    ignore: IgnoreOrMatchOption,
+    /**
+     * Default to `false`
+     */
+    enable: z.boolean().default(false),
+    /**
+     * Max age of Strict-Transport-Security in seconds
+     *
+     * Default to `365 * 24 * 3600`
+     */
+    maxAge: z.number().default(365 * 24 * 3600),
+    /**
+     * Whether include sub domains
+     *
+     * Default to `false`
+     */
+    includeSubdomains: z.boolean().default(false),
+  }).default({}),
+  /**
+   * whether enable Http Method filter
+   */
+  methodnoallow: z.object({
+    match: IgnoreOrMatchOption,
+    ignore: IgnoreOrMatchOption,
+    /**
+     * Default to `true`
+     */
+    enable: z.boolean().default(true),
+  }).default({}),
+  /**
+   * whether enable IE automatically download open
+   */
+  noopen: z.object({
+    match: IgnoreOrMatchOption,
+    ignore: IgnoreOrMatchOption,
+    /**
+     * Default to `true`
+     */
+    enable: z.boolean().default(true),
+  }).default({}),
+  /**
+   * whether enable IE8 automatically detect mime
+   */
+  nosniff: z.object({
+    match: IgnoreOrMatchOption,
+    ignore: IgnoreOrMatchOption,
+    /**
+     * Default to `true`
+     */
+    enable: z.boolean().default(true),
+  }).default({}),
+  /**
+   * whether enable IE8 XSS Filter
+   */
+  xssProtection: z.object({
+    match: IgnoreOrMatchOption,
+    ignore: IgnoreOrMatchOption,
+    /**
+     * Default to `true`
+     */
+    enable: z.boolean().default(true),
+    /**
+     * X-XSS-Protection response header value
+     *
+     * Default to `'1; mode=block'`
+     */
+    value: z.coerce.string().default('1; mode=block'),
+  }).default({}),
+  /**
+   * content security policy config
+   */
+  csp: z.object({
+    match: IgnoreOrMatchOption,
+    ignore: IgnoreOrMatchOption,
+    /**
+     * Default to `false`
+     */
+    enable: z.boolean().default(false),
+    // https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP#csp_overview
+    policy: z.record(z.union([ z.string(), z.array(z.string()), z.boolean() ])).default({}),
+    /**
+     * whether enable report only mode
+     * Default to `undefined`
+     */
+    reportOnly: z.boolean().optional(),
+    /**
+     * whether support IE
+     * Default to `undefined`
+     */
+    supportIE: z.boolean().optional(),
+  }).default({}),
+  /**
+   * whether enable referrer policy
+   * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referrer-Policy
+   */
+  referrerPolicy: z.object({
+    match: IgnoreOrMatchOption,
+    ignore: IgnoreOrMatchOption,
+    /**
+     * Default to `false`
+     */
+    enable: z.boolean().default(false),
+    /**
+     * referrer policy value
+     *
+     * Default to `'no-referrer-when-downgrade'`
+     */
+    value: z.string().default('no-referrer-when-downgrade'),
+  }).default({}),
+  /**
+   * whether enable auto avoid directory traversal attack
+   */
+  dta: z.object({
+    match: IgnoreOrMatchOption,
+    ignore: IgnoreOrMatchOption,
+    /**
+     * Default to `true`
+     */
+    enable: z.boolean().default(true),
+  }).default({}),
+  ssrf: z.object({
+    ipBlackList: z.array(z.string()).optional(),
+    ipExceptionList: z.array(z.string()).optional(),
+    hostnameExceptionList: z.array(z.string()).optional(),
+    checkAddress: SSRFCheckAddressFunction.optional(),
+  }).default({}),
+  match: z.union([ IgnoreOrMatch, IgnoreOrMatch.array() ]).optional(),
+  ignore: z.union([ IgnoreOrMatch, IgnoreOrMatch.array() ]).optional(),
+  __protocolWhiteListSet: z.set(z.string()).optional().readonly(),
+});
+export type SecurityConfig = z.infer<typeof SecurityConfig>;
+
+const SecurityHelperOnTagAttrHandler = z.function()
+  .args(z.string(), z.string(), z.string(), z.boolean())
+  .returns(z.union([ z.string(), z.void() ]));
+
+/**
+ * (tag: string, name: string, value: string, isWhiteAttr: boolean) => string | void
+ */
+export type SecurityHelperOnTagAttrHandler = z.infer<typeof SecurityHelperOnTagAttrHandler>;
+
+export const SecurityHelperConfig = z.object({
+  shtml: z.object({
+    /**
+     * tag attribute white list
+     */
+    whiteList: z.record(z.array(z.string())).optional(),
+    /**
+     * domain white list
+     * @deprecated use `config.security.domainWhiteList` instead
+     */
+    domainWhiteList: z.array(z.string()).optional(),
+    /**
+     * tag attribute handler
+     */
+    onTagAttr: SecurityHelperOnTagAttrHandler.optional(),
+  }).default({}),
+});
+export type SecurityHelperConfig = z.infer<typeof SecurityHelperConfig>;
+
+export default {
+  security: SecurityConfig.parse({}),
+  helper: SecurityHelperConfig.parse({}),
+};

package/src/config/config.local.ts

@@ -0,0 +1,9 @@
+import { SecurityConfig } from '../types.js';
+
+export default {
+  security: {
+    hsts: {
+      enable: false,
+    },
+  } as SecurityConfig,
+};

package/src/index.ts

@@ -0,0 +1,12 @@
+import './types.js';
+
+// module.exports = require('./app/middleware/securities');
+// module.exports.csp = require('./lib/middlewares/csp');
+// module.exports.csrf = require('./lib/middlewares/csrf');
+// module.exports.methodNoAllow = require('./lib/middlewares/methodnoallow');
+// module.exports.noopen = require('./lib/middlewares/noopen');
+// module.exports.nosniff = require('./lib/middlewares/nosniff');
+// module.exports.xssProtection = require('./lib/middlewares/xssProtection');
+// module.exports.xframe = require('./lib/middlewares/xframe');
+// module.exports.safeRedirect = require('./lib/safe_redirect');
+// module.exports.utils = require('./lib/utils');

package/src/lib/extend/safe_curl.ts

@@ -0,0 +1,35 @@
+import { EggCore } from '@eggjs/core';
+import type { SSRFCheckAddressFunction } from '../../types.js';
+
+const SSRF_HTTPCLIENT = Symbol('SSRF_HTTPCLIENT');
+
+type HttpClient = EggCore['HttpClient'];
+type HttpClientParameters = Parameters<HttpClient['prototype']['request']>;
+export type HttpClientRequestURL = HttpClientParameters[0];
+export type HttpClientOptions = HttpClientParameters[1] & { checkAddress?: SSRFCheckAddressFunction };
+export type HttpClientResponse<T = any> = Awaited<ReturnType<HttpClient['prototype']['request']>> & { data: T };
+
+/**
+ * safe curl with ssrf protection
+ */
+export async function safeCurlForApplication<T = any>(app: EggCore, url: HttpClientRequestURL, options: HttpClientOptions = {}) {
+  const ssrfConfig = app.config.security.ssrf;
+  if (ssrfConfig?.checkAddress) {
+    options.checkAddress = ssrfConfig.checkAddress;
+  } else {
+    app.logger.warn('[@eggjs/security] please configure `config.security.ssrf` first');
+  }
+
+  if (ssrfConfig?.checkAddress) {
+    let httpClient = app[SSRF_HTTPCLIENT] as ReturnType<EggCore['createHttpClient']>;
+    // use the new httpClient init with checkAddress
+    if (!httpClient) {
+      httpClient = app[SSRF_HTTPCLIENT] = app.createHttpClient({
+        checkAddress: ssrfConfig.checkAddress,
+      });
+    }
+    return await httpClient.request<T>(url, options);
+  }
+
+  return await app.curl<T>(url, options);
+}

package/src/lib/helper/cliFilter.ts

@@ -0,0 +1,20 @@
+/**
+ * remote command execution
+ */
+
+const BASIC_ALPHABETS = new Set('abcdefghijklmnopqrstuvwxyz1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ.-_'.split(''));
+
+export default function cliFilter(text: string) {
+  const str = '' + text;
+  let res = '';
+  let ascii;
+
+  for (let index = 0; index < str.length; index++) {
+    ascii = str[index];
+    if (BASIC_ALPHABETS.has(ascii)) {
+      res += ascii;
+    }
+  }
+
+  return res;
+}

package/src/lib/helper/escape.ts

@@ -0,0 +1,3 @@
+import escapeHTML from 'escape-html';
+
+export default escapeHTML;

package/src/lib/helper/escapeShellArg.ts

@@ -0,0 +1,4 @@
+export default function escapeShellArg(text: string) {
+  const str = '' + text;
+  return '\'' + str.replace(/\\/g, '\\\\').replace(/\'/g, '\\\'') + '\'';
+}

package/src/lib/helper/escapeShellCmd.ts

@@ -0,0 +1,16 @@
+const BASIC_ALPHABETS = new Set('#&;`|*?~<>^()[]{}$;\'",\x0A\xFF'.split(''));
+
+export default function escapeShellCmd(text: string) {
+  const str = '' + text;
+  let res = '';
+  let ascii;
+
+  for (let index = 0; index < str.length; index++) {
+    ascii = str[index];
+    if (!BASIC_ALPHABETS.has(ascii)) {
+      res += ascii;
+    }
+  }
+
+  return res;
+}

package/src/lib/helper/index.ts

@@ -0,0 +1,21 @@
+import cliFilter from './cliFilter.js';
+import escape from './escape.js';
+import escapeShellArg from './escapeShellArg.js';
+import escapeShellCmd from './escapeShellCmd.js';
+import shtml from './shtml.js';
+import sjs from './sjs.js';
+import sjson from './sjson.js';
+import spath from './spath.js';
+import surl from './surl.js';
+
+export default {
+  cliFilter,
+  escape,
+  escapeShellArg,
+  escapeShellCmd,
+  shtml,
+  sjs,
+  sjson,
+  spath,
+  surl,
+};

package/src/lib/helper/shtml.ts

@@ -0,0 +1,77 @@
+import type { BaseContextClass } from '@eggjs/core';
+import xss from 'xss';
+import { isSafeDomain, getFromUrl } from '../utils.js';
+import type { SecurityHelperOnTagAttrHandler } from '../../types.js';
+
+const BUILD_IN_ON_TAG_ATTR = Symbol('buildInOnTagAttr');
+
+// default rule: https://github.com/leizongmin/js-xss/blob/master/lib/default.js
+// add domain filter based on xss module
+// custom options http://jsxss.com/zh/options.html
+// eg: support a tag，filter attributes except for title : whiteList: {a: ['title']}
+export default function shtml(this: BaseContextClass, val: string) {
+  if (typeof val !== 'string') {
+    return val;
+  }
+
+  const securityOptions = this.ctx.securityOptions;
+  let buildInOnTagAttrHandler: SecurityHelperOnTagAttrHandler | undefined;
+  const shtmlConfig = {
+    ...this.app.config.helper.shtml,
+    ...securityOptions.shtml,
+    [BUILD_IN_ON_TAG_ATTR]: buildInOnTagAttrHandler,
+  };
+  const domainWhiteList = this.app.config.security.domainWhiteList;
+  const app = this.app;
+  // filter href and src attribute if not in domain white list
+  if (!shtmlConfig[BUILD_IN_ON_TAG_ATTR]) {
+    shtmlConfig[BUILD_IN_ON_TAG_ATTR] = (_tag, name, value, isWhiteAttr) => {
+      if (isWhiteAttr && (name === 'href' || name === 'src')) {
+        if (!value) {
+          return;
+        }
+
+        value = String(value);
+        if (value[0] === '/' || value[0] === '#') {
+          return;
+        }
+
+        const hostname = getFromUrl(value, 'hostname');
+        if (!hostname) {
+          return;
+        }
+
+        // If we don't have our hostname in the app.security.domainWhiteList,
+        // Just check for `shtmlConfig.domainWhiteList` and `ctx.whiteList`.
+        if (!isSafeDomain(hostname, domainWhiteList)) {
+          // Check for `shtmlConfig.domainWhiteList` first (duplicated now)
+          if (shtmlConfig.domainWhiteList && shtmlConfig.domainWhiteList.length > 0) {
+            app.deprecate('[@eggjs/security/lib/helper/shtml] `config.helper.shtml.domainWhiteList` has been deprecate. Please use `config.security.domainWhiteList` instead.');
+            if (!isSafeDomain(hostname, shtmlConfig.domainWhiteList)) {
+              return '';
+            }
+          } else {
+            return '';
+          }
+        }
+      }
+    };
+
+    // avoid overriding user configuration 'onTagAttr'
+    if (shtmlConfig.onTagAttr) {
+      const customOnTagAttrHandler = shtmlConfig.onTagAttr;
+      shtmlConfig.onTagAttr = function(tag, name, value, isWhiteAttr) {
+        const result = customOnTagAttrHandler.apply(this, [ tag, name, value, isWhiteAttr ]);
+        if (result !== undefined) {
+          return result;
+        }
+        // fallback to build-in handler
+        return shtmlConfig[BUILD_IN_ON_TAG_ATTR]!.apply(this, [ tag, name, value, isWhiteAttr ]);
+      };
+    } else {
+      shtmlConfig.onTagAttr = shtmlConfig[BUILD_IN_ON_TAG_ATTR];
+    }
+  }
+
+  return xss(val, shtmlConfig);
+}

package/src/lib/helper/sjs.ts

@@ -0,0 +1,57 @@
+/**
+ * Escape JavaScript to \xHH format
+ */
+
+// escape \x00-\x7f
+// except 0-9,A-Z,a-z(\x2f-\x3a \x40-\x5b \x60-\x7b)
+
+// eslint-disable-next-line
+const MATCH_VULNERABLE_REGEXP = /[\x00-\x2f\x3a-\x40\x5b-\x60\x7b-\x7f]/;
+// eslint-enable-next-line
+
+const BASIC_ALPHABETS = new Set('abcdefghijklmnopqrstuvwxyz1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ'.split(''));
+
+const map: Record<string, string> = {
+  '\t': '\\t',
+  '\n': '\\n',
+  '\r': '\\r',
+};
+
+export default function escapeJavaScript(text: string) {
+  const str = '' + text;
+  const match = MATCH_VULNERABLE_REGEXP.exec(str);
+
+  if (!match) {
+    return str;
+  }
+
+  let res = '';
+  let index = 0;
+  let lastIndex = 0;
+  let ascii;
+
+  for (index = match.index; index < str.length; index++) {
+    ascii = str[index];
+    if (BASIC_ALPHABETS.has(ascii)) {
+      continue;
+    } else {
+      if (map[ascii] === undefined) {
+        const code = ascii.charCodeAt(0);
+        if (code > 127) {
+          continue;
+        } else {
+          map[ascii] = '\\x' + code.toString(16);
+        }
+      }
+    }
+
+    if (lastIndex !== index) {
+      res += str.substring(lastIndex, index);
+    }
+
+    lastIndex = index + 1;
+    res += map[ascii];
+  }
+
+  return lastIndex !== index ? res + str.substring(lastIndex, index) : res;
+}

package/src/lib/helper/sjson.ts

@@ -0,0 +1,35 @@
+import sjs from './sjs.js';
+
+/**
+ * escape json
+ * for output json in script
+ */
+
+function sanitizeKey(obj: any) {
+  if (typeof obj !== 'object') return obj;
+  if (Array.isArray(obj)) return obj;
+  if (obj === null) return null;
+  if (typeof obj === 'boolean') return obj;
+  if (typeof obj === 'number') return obj;
+  if (Buffer.isBuffer(obj)) return obj.toString();
+
+  for (const k in obj) {
+    const escapedK = sjs(k);
+    if (escapedK !== k) {
+      obj[escapedK] = sanitizeKey(obj[k]);
+      obj[k] = undefined;
+    } else {
+      obj[k] = sanitizeKey(obj[k]);
+    }
+  }
+  return obj;
+}
+
+export default function jsonEscape(obj: any) {
+  return JSON.stringify(sanitizeKey(obj), (_k, v) => {
+    if (typeof v === 'string') {
+      return sjs(v);
+    }
+    return v;
+  });
+}