@eggjs/security 4.0.0 → 5.0.0-beta.15

package/src/app/extend/response.ts

@@ -1,95 +0,0 @@
-import { Response as KoaResponse } from '@eggjs/core';
-import SecurityContext from './context.js';
-
-const unsafeRedirect = KoaResponse.prototype.redirect;
-
-export default class SecurityResponse extends KoaResponse {
-  declare ctx: SecurityContext;
-
-  /**
-   * This is an unsafe redirection, and we WON'T check if the
-   * destination url is safe or not.
-   * Please DO NOT use this method unless in some very special cases,
-   * otherwise there may be security vulnerabilities.
-   *
-   * @function Response#unsafeRedirect
-   * @param {String} url URL to forward
-   * @example
-   * ```js
-   * ctx.response.unsafeRedirect('http://www.domain.com');
-   * ctx.unsafeRedirect('http://www.domain.com');
-   * ```
-   */
-  unsafeRedirect(url: string, alt?: string) {
-    unsafeRedirect.call(this, url, alt);
-  }
-
-  // app.response.unsafeRedirect = app.response.redirect;
-  // delegate(app.context, 'response').method('unsafeRedirect');
-  /**
-   * A safe redirection, and we'll check if the URL is in
-   * a safe domain or not.
-   * We've overridden the default Koa's implementation by adding a
-   * white list as the filter for that.
-   *
-   * @function Response#redirect
-   * @param {String} url URL to forward
-   * @example
-   * ```js
-   * ctx.response.redirect('/login');
-   * ctx.redirect('/login');
-   * ```
-   */
-  redirect(url: string, alt?: string) {
-    url = (url || '/').trim();
-
-    // Process with `//`
-    if (url[0] === '/' && url[1] === '/') {
-      url = '/';
-    }
-
-    // if begin with '/', it means an internal jump
-    if (url[0] === '/' && url[1] !== '\\') {
-      this.unsafeRedirect(url, alt);
-      return;
-    }
-
-    let urlObject: URL;
-    try {
-      urlObject = new URL(url);
-    } catch {
-      url = '/';
-      this.unsafeRedirect(url);
-      return;
-    }
-
-    const domainWhiteList = this.app.config.security.domainWhiteList;
-    if (urlObject.protocol !== 'http:' && urlObject.protocol !== 'https:') {
-      url = '/';
-    } else if (!urlObject.hostname) {
-      url = '/';
-    } else {
-      if (domainWhiteList && domainWhiteList.length !== 0) {
-        if (!this.ctx.isSafeDomain(urlObject.hostname)) {
-          const message = `a security problem has been detected for url "${url}", redirection is prohibited.`;
-          if (process.env.NODE_ENV === 'production') {
-            this.app.coreLogger.warn('[@eggjs/security/response/redirect] %s', message);
-            url = '/';
-          } else {
-            // Exception will be thrown out in a non-PROD env.
-            return this.ctx.throw(500, message);
-          }
-        }
-      }
-    }
-    this.unsafeRedirect(url);
-  }
-}
-
-declare module '@eggjs/core' {
-  // add Response overrides types
-  interface Response {
-    unsafeRedirect(url: string, alt?: string): void;
-    redirect(url: string, alt?: string): void;
-  }
-}

package/src/app/middleware/securities.ts

@@ -1,63 +0,0 @@
-import assert from 'node:assert';
-import compose from 'koa-compose';
-import { pathMatching } from 'egg-path-matching';
-import { EggCore, MiddlewareFunc } from '@eggjs/core';
-import securityMiddlewares from '../../lib/middlewares/index.js';
-import type { SecurityMiddlewareName } from '../../config/config.default.js';
-
-export default (_: unknown, app: EggCore) => {
-  const options = app.config.security;
-  const middlewares: MiddlewareFunc[] = [];
-  const defaultMiddlewares = typeof options.defaultMiddleware === 'string'
-    ? options.defaultMiddleware.split(',').map(m => m.trim()).filter(m => !!m) as SecurityMiddlewareName[]
-    : options.defaultMiddleware;
-
-  if (options.match || options.ignore) {
-    app.coreLogger.warn('[@eggjs/security/middleware/securities] Please set `match` or `ignore` on sub config');
-  }
-
-  // format csrf.cookieDomain
-  const originalCookieDomain = options.csrf.cookieDomain;
-  if (originalCookieDomain && typeof originalCookieDomain !== 'function') {
-    options.csrf.cookieDomain = () => originalCookieDomain;
-  }
-
-  defaultMiddlewares.forEach(middlewareName => {
-    const opt = Reflect.get(options, middlewareName) as any;
-    if (opt === false) {
-      app.coreLogger.warn('[egg-security] Please use `config.security.%s = { enable: false }` instead of `config.security.%s = false`', middlewareName, middlewareName);
-    }
-
-    assert(opt === false || typeof opt === 'object',
-      `config.security.${middlewareName} must be an object, or false(if you turn it off)`);
-
-    if (opt === false || opt && opt.enable === false) {
-      return;
-    }
-
-    if (middlewareName === 'csrf' && opt.useSession && !app.plugins.session) {
-      throw new Error('csrf.useSession enabled, but session plugin is disabled');
-    }
-
-    // use opt.match first (compatibility)
-    if (opt.match && opt.ignore) {
-      app.coreLogger.warn('[@eggjs/security/middleware/securities] `options.match` and `options.ignore` are both set, using `options.match`');
-      opt.ignore = undefined;
-    }
-    if (!opt.ignore && opt.blackUrls) {
-      app.deprecate('[@eggjs/security/middleware/securities] Please use `config.security.xframe.ignore` instead, `config.security.xframe.blackUrls` will be removed very soon');
-      opt.ignore = opt.blackUrls;
-    }
-    // set matching function to security middleware options
-    opt.matching = pathMatching(opt);
-
-    const createMiddleware = securityMiddlewares[middlewareName];
-    const fn = createMiddleware(opt);
-    middlewares.push(fn);
-    app.coreLogger.info('[@eggjs/security/middleware/securities] use %s middleware', middlewareName);
-  });
-
-  app.coreLogger.info('[@eggjs/security/middleware/securities] compose %d middlewares into one security middleware',
-    middlewares.length);
-  return compose(middlewares);
-};

package/src/app.ts

@@ -1,31 +0,0 @@
-import type { ILifecycleBoot, EggCore } from '@eggjs/core';
-import { preprocessConfig } from './lib/utils.js';
-import { SecurityConfig } from './config/config.default.js';
-
-export default class AgentBoot implements ILifecycleBoot {
-  private readonly app;
-
-  constructor(app: EggCore) {
-    this.app = app;
-  }
-
-  configWillLoad() {
-    const app = this.app;
-    app.config.coreMiddleware.push('securities');
-    // parse config and check if config is legal
-    const parsed = SecurityConfig.parse(app.config.security);
-    if (typeof app.config.security.csrf === 'boolean') {
-      // support old config: `config.security.csrf = false`
-      app.config.security.csrf = parsed.csrf;
-    }
-
-    if (app.config.security.csrf.enable) {
-      const { ignoreJSON } = app.config.security.csrf;
-      if (ignoreJSON) {
-        app.deprecate('[@eggjs/security/app] `config.security.csrf.ignoreJSON` is not safe now, please disable it.');
-      }
-    }
-
-    preprocessConfig(app.config.security);
-  }
-}

package/src/config/config.default.ts

@@ -1,379 +0,0 @@
-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

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

package/src/index.ts

@@ -1,12 +0,0 @@
-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

@@ -1,35 +0,0 @@
-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

@@ -1,20 +0,0 @@
-/**
- * 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

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

package/src/lib/helper/escapeShellArg.ts

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

package/src/lib/helper/escapeShellCmd.ts

@@ -1,16 +0,0 @@
-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

@@ -1,21 +0,0 @@
-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,
-};