@eggjs/security 4.0.0

package/README.zh-CN.md

@@ -0,0 +1,441 @@
+# @eggjs/security
+
+[![NPM version][npm-image]][npm-url]
+[![Node.js CI](https://github.com/eggjs/security/actions/workflows/nodejs.yml/badge.svg)](https://github.com/eggjs/security/actions/workflows/nodejs.yml)
+[![Test coverage][codecov-image]][codecov-url]
+[![Known Vulnerabilities][snyk-image]][snyk-url]
+[![npm download][download-image]][download-url]
+[![Node.js Version](https://img.shields.io/node/v/eggjs/security.svg?style=flat)](https://nodejs.org/en/download/)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](https://makeapullrequest.com)
+![CodeRabbit Pull Request Reviews](https://img.shields.io/coderabbit/prs/github/eggjs/security)
+
+[npm-image]: https://img.shields.io/npm/v/@eggjs/security.svg?style=flat-square
+[npm-url]: https://npmjs.org/package/@eggjs/security
+[codecov-image]: https://codecov.io/gh/eggjs/security/branch/master/graph/badge.svg
+[codecov-url]: https://codecov.io/gh/eggjs/security
+[snyk-image]: https://snyk.io/test/npm/@eggjs/security/badge.svg?style=flat-square
+[snyk-url]: https://snyk.io/test/npm/@eggjs/security
+[download-image]: https://img.shields.io/npm/dm/@eggjs/security.svg?style=flat-square
+[download-url]: https://npmjs.org/package/@eggjs/security
+
+egg 内置的安全插件
+
+## 使用方式
+
+egg 默认开启此插件，所以无需配置。
+
+修改 `config/config.js` 文件修改配置
+
+```js
+exports.security = {
+  xframe: {
+    value: 'SAMEORIGIN',
+  },
+};
+```
+
+### 关闭安全防范
+
+如果你想关闭其中一些安全防范，直接设置该项的 `enable` 属性为 false 即可，如关闭 xfame 防范：
+
+```js
+exports.security = {
+  xframe: {
+    enable: false,
+  },
+};
+```
+
+### match 和 ignore
+
+如果只想开启针对某一路径，则配置 match 选项，例如只针对 `/example` 开启 csp
+
+```js
+exports.security = {
+  csp: {
+    match: '/example',
+    // match: /^\/api/, // support regexp
+    // match: ctx => ctx.path.startsWith('/api'), // support function
+    // match: [ ctx => ctx.path.startsWith('/api'), /^\/foo$/, '/bar'], // support Array
+    policy: {
+      //...
+    },
+  },
+};
+
+```
+
+如果需要针对某一路径忽略某安全选项，则配置 ignore 选项，例如针对 `/example` 关闭 xframe，以便合作商户能够嵌入我们的页面：
+
+```js
+exports.security = {
+  xframe: {
+    ignore: '/example',
+    // ignore: /^\/api/, // support regexp
+    // ignore: ctx => ctx.path.startsWith('/api'), // support function
+    // ignore: [ ctx => ctx.path.startsWith('/api'), /^\/foo$/, '/bar'], // support Array
+    // ...
+  },
+};
+
+```
+
+__注意：如果存在 match 则忽略 ignore。__
+
+## API
+
+### ctx.isSafeDomain(domain)
+
+是否为安全域名。安全域名在配置中配置，见 `ctx.redirect` 部分
+
+## 接口限制
+
+### csrf
+
+__使用__
+
+* `ctx.csrf` 获取 csrf token
+
+一般在 POST 表单时使用。
+
+页面渲染时，将 `ctx.csrf` 作为 form 隐藏域或 query string 渲染在页面上。(`_csrf` 作为 key)
+
+在提交表单时，带上 token 即可。
+
+#### 通过 formData 上传时使用 csrf
+
+浏览器端 html 代码:
+
+```html
+<form method="POST" action="/upload?_csrf={{ ctx.csrf | safe }}" enctype="multipart/form-data">
+  title: <input name="title" />
+  file: <input name="file" type="file" />
+  <button type="submit">上传</button>
+</form>
+```
+
+### ctoken
+
+ajax 防跨站攻击。
+
+__使用__
+
+在 ajax 请求时，以 `ctoken` 为 name 带上 ctoken 即可。
+
+ctoken 从 cookie 中获取
+
+__安全开发者约定__
+
+* `ctx.ctoken` 获取 ctoken 的逻辑。使用者不要调用，安全插件内部使用。
+* `ctx.setCTOKEN()` 设置 ctoken 的逻辑。使用者不要调用，安全插件内部使用。
+* `ctx.assertCTOKEN()` ctoken 校验逻辑。使用者不要调用，安全插件内部使用。
+* `ctx.setCTOKEN()`会将cookie设置到主域名下，主要考虑主域名下其他子域名对应的应用之间的互相调用。例如 A.xx.com 域种了 ctoken,会设置cookie到xx.com域上，在 B.xx.com 域的时候可以利用 ctoken 去请求，在 A 域 jsonp 请求 B 域的时候，B 域也可以验证 ctoken。
+
+可拓展实现。例如 ctoken token 存在什么 cookie，存什么字段等，都可以通过以上两个接口拓展。
+
+#### 配置项
+
+```js
+exports.security = {
+  csrf: {
+    type: 'ctoken',             // 可以是 ctoken / referer / all, 默认为 ctoken
+    useSession: false,          // 如果设为 true，secret 将存储在 session 中
+    ignoreJSON: false,          // 如果设为 true ，将忽略 json 请求
+    cookieName: 'csrfToken',    // csrf 的 token 在 cookie 中存储的 key 名称
+    sessionName: 'csrfToken',   // csrf 的 token 在 session 中存储的 key 名称
+    headerName: 'x-csrf-token', // csrf token 在 header 中的名称
+    bodyName: '_csrf',          // csrf token 在 body 中的名称
+    queryName: '_csrf',         // csrf token 在 query 中的名称
+    rotateWhenInvalid: false,   // csrf invalid 时刷新 token，用于同域名下多个业务 token 可能互相影响的情况
+    refererWhiteList: [],       // referer 白名单
+    supportedRequests: [        // 支持的 url path pattern 和方法，根据配置名单由上至下匹配 url path 正则，建议在自定义时配置 {path: /^\//, methods:['POST','PATCH','DELETE','PUT','CONNECT']} 为兜底规则
+      {path: /^\//, methods:['POST','PATCH','DELETE','PUT','CONNECT']},
+    ],
+  },
+}
+```
+
+注意，methods 可以为空， 如果将 supportedRequests 设置为`supportedRequests: [{path: /^\//, methods:[]}]`, 那么等效于关闭 csrf 防御。
+
+### safe redirect
+
+* `ctx.redirect(url)` 如果不在配置的白名单内，则禁止
+* `ctx.unsafeRedirect(url)` 不建议使用
+
+安全方案覆盖了默认的`ctx.redirect`方法，所有的跳转均会经过安全域名的判断。
+
+用户如果使用`ctx.redirect`方法，需要在应用的配置文件中做如下配置：
+
+```js
+exports.security = {
+  domainWhiteList:['.domain.com'],  // 安全白名单，以.开头
+};
+```
+
+若用户没有配置 `domainWhiteList` 或者 `domainWhiteList` 数组内为空，则默认会对所有跳转请求放行，即等同于`ctx.unsafeRedirect(url)`。同时域名和 url 检查时不区分大小写。
+
+### jsonp
+
+使用 [jsonp-body](https://github.com/node-modules/jsonp-body)，在 egg context 中实现，并不再 egg-security 中。
+
+防御内容：
+
+* callback函数名词最长50个字符限制
+* callback函数名只允许"[","]","a-zA-Z0123456789_", "$" "."，防止一般的 xss，utf-7 xss等攻击
+
+可定义配置：
+
+* callback 默认 `_callback`，可以改名
+* limit - 函数名 length 限制，默认 50
+
+## helper
+
+### .escape()
+
+对字符串进行 xss 过滤，安全性最高的过滤方式。
+
+```js
+const str = '><script>alert("abc") </script><';
+console.log(ctx.helper.escape(str));
+// => &gt;&lt;script&gt;alert(&quot;abc&quot;) &lt;/script&gt;&lt;
+```
+
+在 nunjucks 模板中，默认进行 escape，不需要显式调用。
+
+### .surl()
+
+url 过滤。
+
+用于在html标签中中要解析 url 的地方（比如 `<a href=""/><img src=""/>`），其他地方不允许使用。
+
+对模板中要输出的变量，加 `helper.surl($value)`。
+
+__特别需要注意的是在需要解析url的地方，surl 外面一定要加上双引号，否则就会导致XSS漏洞。__
+
+不使用 surl
+
+```html
+<a href="$value" />
+```
+
+output:
+
+```html
+<a href="http://www.domain.com<script>" />
+```
+
+使用 surl
+
+```html
+<a href="helper.surl($value)" />
+```
+
+output:
+
+```html
+<a href="http://www.domain.com&lt;script&gt;" />
+```
+
+### .sjs()
+
+用于在 js（包括 onload 等 event）中输出变量，会对变量中字符进行 JAVASCRIPT ENCODE，
+将所有非白名单字符转义为 `\x` 形式，防止xss攻击，也确保在 js 中输出的正确性。
+
+```js
+const foo = '"hello"';
+
+// 未使用 sjs
+console.log(`var foo = "${foo}";`);
+// => var foo = ""hello"";
+
+// 使用 sjs
+console.log(`var foo = "${this.helper.sjs(foo)}";`);
+// => var foo = "\\x22hello\\x22";
+```
+
+### .shtml()
+
+将富文本（包含 html 代码的文本）当成变量直接在模版里面输出时，需要用到 shtml 来处理。
+使用 shtml 可以输出 html 的 tag，同时执行 xss 的过滤动作，过滤掉非法的脚本。
+
+**由于是一个非常复杂的安全处理过程，对服务器处理性能一定影响，如果不是输出 HTML，请勿使用。**
+
+简单示例：
+
+```js
+// js
+const value = `<a href="http://www.domain.com">google</a><script>evilcode…</script>`;
+
+// 模板
+<html>
+<body>
+  ${helper.shtml($value)}
+</body>
+</html>
+// => <a href="http://www.domain.com">google</a>&lt;script&gt;evilcode…&lt;/script&gt;
+```
+
+shtml 在 [xss](https://github.com/leizongmin/js-xss/) 模块基础上增加了针对域名的过滤。
+
+* [默认规则](https://github.com/leizongmin/js-xss/blob/master/lib/default.js)
+* 自定义过滤项 <http://jsxss.com/zh/options.html>
+
+例如只支持 a 标签，且除了 title 其他属性都过滤掉：
+
+```javascript
+whiteList: {a: ['title']}
+```
+
+options:
+
+> `config.helper.shtml.domainWhiteList` 已过时，请使用 `config.security.domainWhiteList` 代替。
+
+注意，shtml 使用了严格的白名单机制，除了过滤掉 xss 风险的字符串外，
+在 [默认规则](https://github.com/leizongmin/js-xss/blob/master/lib/default.js) 外的 tag 和 attr 都会被过滤掉。
+
+例如 html 标签就不在白名单中，
+
+```js
+const html = '<html></html>';
+
+// html
+${helper.shtml($html)}
+
+// 输出空
+```
+
+常见的 `data-xx` 属性由于不在白名单中，所以都会被过滤。
+
+所以，一定要注意 shtml 的适用场景，一般是针对来自用户的富文本输入，切忌滥用，功能既受到限制，又会影响服务端性能。
+此类场景一般是论坛、评论系统等，即便是论坛等如果不支持 html 内容输入，也不要使用此 helper，直接使用 escape 即可。
+
+### .spath()
+
+如果把输入字符串用作 path 路径，需要使用 spath 进行安全检验。若路径不合法，返回 null。
+
+不合法的路径包括：
+
+* 使用 `..` 的相对路径
+* 使用 `/` 开头的绝对路径
+* 以及以上试图通过 url encode 试图绕过校验的结果字符串
+
+```js
+const foo = '/usr/local/bin';
+console.log(this.helper.spath(foo2));
+// => null
+```
+
+### .sjson()
+
+json转义
+
+在js中输出json，若未做转义，易被利用为xss漏洞。提供此宏做json encode，会遍历json中的key，将value的值中，所有非白名单字符转义为\x形式，防止xss攻击。同时保持json结构不变。
+若你有模板中输出一个json字符串给js应用的场景，请使用 `${this.helper.sjson(变量名)}`进行转义。
+
+__处理过程较复杂，性能损耗较大，尽量避免使用__
+
+实例:
+
+```js
+  <script>
+    window.locals = ${this.helper.sjson(locals)};
+  </script>
+```
+
+### .cliFilter()
+
+远程命令执行漏洞，用户通过浏览器提交执行命令，由于服务器端没有针对执行函数做过滤，导致可以执行命令，通常可导致入侵服务器。
+
+如果用户可控变量为命令中的参数。则直接使用安全包函数过滤。
+
+修复前：
+
+```js
+
+  cp.exec("bash /home/admin/ali-knowledge-graph-backend/initrun.sh " + port);
+
+```
+
+修复后：
+
+```js
+
+  cp.exec("bash /home/admin/ali-knowledge-graph-backend/initrun.sh " + this.helper.cliFilter(port));
+
+```
+
+如果因为业务需要，需要在参数中添加白名单之外的字符。可以将用户输入按照该字符分割，并使用过滤函数过滤每一段数据。
+
+如果用户可控变量为命令中的命令，则和开发协商修改功能或功能下线。
+
+### .escapeShellArg()
+
+命令行参数转义。给字符串增加一对单引号并且能引用或者转码任何已经存在的单引号， 这样以确保能够直接将一个字符串传入 shell 函数，并且还是确保安全的。
+
+```js
+const ip = '127.0.0.1 && cat /etc/passwd'
+const cmd = 'ping -c 1 ' + this.helper.escapeShellArg(ip);
+
+console.log(cmd);
+//ping -c 1 '127.0.0.1 && cat /etc/passwd'
+```
+
+### .escapeShellCmd()
+
+命令行转义，从输入的命令行中删除下列字符: ```#&;`|*?~<>^()[]{}$;'", 0x0A 和 0xFF```
+
+```js
+const ip = '127.0.0.1 && cat /etc/passwd'
+const cmd = 'ping -c 1 ' + this.helper.escapeShellCmd(ip);
+
+console.log(cmd);
+//ping -c 1 127.0.0.1  cat /etc/passwd
+```
+
+## Web 安全头
+
+### hsts Strict-Transport-Security
+
+默认开启，如果是 http 站点，需要关闭
+
+* maxAge 默认一年 `365 * 24 * 3600`
+* includeSubdomains 默认 false
+
+### csp
+
+默认关闭。需要开启的话，需要和安全工程师确定开启策略。
+
+* policy 策略
+
+### X-Download-Options:noopen
+
+默认开启，禁用IE下下载框Open按钮，防止 ie 下下载文件默认被打开 xss
+
+### X-Content-Type-Options:nosniff
+
+禁用 IE8 自动嗅探 mime 功能。例如：`text/plain` 却当成 `text/html` 渲染，特别当本站点服务内容未必可信的时候。
+
+### X-Frame-Options
+
+默认 SAMEORIGIN，只允许同域把本页面当作 iframe 嵌入。
+
+* value 默认值 `SAMEORIGIN`
+
+### X-XSS-Protection
+
+* close 默认值false，即设置为 `1; mode=block`
+
+## 其他
+
+* crossdomain.xml robots.txt 支持，默认都不加，系统可自行加，需要咨询项目安全工程师
+* 禁止 trace track 两种类型请求
+
+## License
+
+[MIT](LICENSE)
+
+## Contributors
+
+[![Contributors](https://contrib.rocks/image?repo=eggjs/security)](https://github.com/eggjs/security/graphs/contributors)
+
+Made with [contributors-img](https://contrib.rocks).

package/dist/commonjs/agent.d.ts

@@ -0,0 +1,6 @@
+import type { ILifecycleBoot, EggCore } from '@eggjs/core';
+export default class AgentBoot implements ILifecycleBoot {
+    private readonly agent;
+    constructor(agent: EggCore);
+    configWillLoad(): Promise<void>;
+}

package/dist/commonjs/agent.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const utils_js_1 = require("./lib/utils.js");
+class AgentBoot {
+    agent;
+    constructor(agent) {
+        this.agent = agent;
+    }
+    async configWillLoad() {
+        (0, utils_js_1.preprocessConfig)(this.agent.config.security);
+    }
+}
+exports.default = AgentBoot;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYWdlbnQuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvYWdlbnQudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6Ijs7QUFDQSw2Q0FBa0Q7QUFFbEQsTUFBcUIsU0FBUztJQUNYLEtBQUssQ0FBQztJQUV2QixZQUFZLEtBQWM7UUFDeEIsSUFBSSxDQUFDLEtBQUssR0FBRyxLQUFLLENBQUM7SUFDckIsQ0FBQztJQUVELEtBQUssQ0FBQyxjQUFjO1FBQ2xCLElBQUEsMkJBQWdCLEVBQUMsSUFBSSxDQUFDLEtBQUssQ0FBQyxNQUFNLENBQUMsUUFBUSxDQUFDLENBQUM7SUFDL0MsQ0FBQztDQUNGO0FBVkQsNEJBVUMifQ==

package/dist/commonjs/app/extend/agent.d.ts

@@ -0,0 +1,5 @@
+import { EggCore } from '@eggjs/core';
+import { type HttpClientRequestURL, type HttpClientOptions, type HttpClientResponse } from '../../lib/extend/safe_curl.js';
+export default class SecurityAgent extends EggCore {
+    safeCurl<T = any>(url: HttpClientRequestURL, options?: HttpClientOptions): Promise<HttpClientResponse<T>>;
+}

package/dist/commonjs/app/extend/agent.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@eggjs/core");
+const safe_curl_js_1 = require("../../lib/extend/safe_curl.js");
+class SecurityAgent extends core_1.EggCore {
+    async safeCurl(url, options) {
+        return await (0, safe_curl_js_1.safeCurlForApplication)(this, url, options);
+    }
+}
+exports.default = SecurityAgent;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYWdlbnQuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi8uLi9zcmMvYXBwL2V4dGVuZC9hZ2VudC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOztBQUFBLHNDQUFzQztBQUN0QyxnRUFLdUM7QUFFdkMsTUFBcUIsYUFBYyxTQUFRLGNBQU87SUFDaEQsS0FBSyxDQUFDLFFBQVEsQ0FDWixHQUF5QixFQUFFLE9BQTJCO1FBQ3RELE9BQU8sTUFBTSxJQUFBLHFDQUFzQixFQUFJLElBQUksRUFBRSxHQUFHLEVBQUUsT0FBTyxDQUFDLENBQUM7SUFDN0QsQ0FBQztDQUNGO0FBTEQsZ0NBS0MifQ==

package/dist/commonjs/app/extend/application.d.ts

@@ -0,0 +1,16 @@
+import { EggCore } from '@eggjs/core';
+import { type HttpClientRequestURL, type HttpClientOptions, type HttpClientResponse } from '../../lib/extend/safe_curl.js';
+export default class SecurityApplication extends EggCore {
+    injectCsrf(html: string): string;
+    injectNonce(html: string): string;
+    injectHijackingDefense(html: string): string;
+    safeCurl<T = any>(url: HttpClientRequestURL, options?: HttpClientOptions): Promise<HttpClientResponse<T>>;
+}
+declare module '@eggjs/core' {
+    interface EggCore {
+        injectCsrf(html: string): string;
+        injectNonce(html: string): string;
+        injectHijackingDefense(html: string): string;
+        safeCurl<T = any>(url: HttpClientRequestURL, options?: HttpClientOptions): Promise<HttpClientResponse<T>>;
+    }
+}

package/dist/commonjs/app/extend/application.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@eggjs/core");
+const safe_curl_js_1 = require("../../lib/extend/safe_curl.js");
+const INPUT_CSRF = '\r\n<input type="hidden" name="_csrf" value="{{ctx.csrf}}" /></form>';
+const INJECTION_DEFENSE = '<!--for injection--><!--</html>--><!--for injection-->';
+class SecurityApplication extends core_1.EggCore {
+    injectCsrf(html) {
+        html = html.replace(/(<form.*?>)([\s\S]*?)<\/form>/gi, (_, $1, $2) => {
+            const match = $2;
+            if (match.indexOf('name="_csrf"') !== -1 || match.indexOf('name=\'_csrf\'') !== -1) {
+                return $1 + match + '</form>';
+            }
+            return $1 + match + INPUT_CSRF;
+        });
+        return html;
+    }
+    injectNonce(html) {
+        html = html.replace(/<script(.*?)>([\s\S]*?)<\/script[^>]*?>/gi, (_, $1, $2) => {
+            if (!$1.includes('nonce=')) {
+                $1 += ' nonce="{{ctx.nonce}}"';
+            }
+            return '<script' + $1 + '>' + $2 + '</script>';
+        });
+        return html;
+    }
+    injectHijackingDefense(html) {
+        return INJECTION_DEFENSE + html + INJECTION_DEFENSE;
+    }
+    async safeCurl(url, options) {
+        return await (0, safe_curl_js_1.safeCurlForApplication)(this, url, options);
+    }
+}
+exports.default = SecurityApplication;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYXBwbGljYXRpb24uanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi8uLi9zcmMvYXBwL2V4dGVuZC9hcHBsaWNhdGlvbi50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOztBQUFBLHNDQUFzQztBQUN0QyxnRUFLdUM7QUFFdkMsTUFBTSxVQUFVLEdBQUcsc0VBQXNFLENBQUM7QUFDMUYsTUFBTSxpQkFBaUIsR0FBRyx3REFBd0QsQ0FBQztBQUVuRixNQUFxQixtQkFBb0IsU0FBUSxjQUFPO0lBQ3RELFVBQVUsQ0FBQyxJQUFZO1FBQ3JCLElBQUksR0FBRyxJQUFJLENBQUMsT0FBTyxDQUFDLGlDQUFpQyxFQUFFLENBQUMsQ0FBQyxFQUFFLEVBQUUsRUFBRSxFQUFFLEVBQUUsRUFBRTtZQUNuRSxNQUFNLEtBQUssR0FBRyxFQUFFLENBQUM7WUFDakIsSUFBSSxLQUFLLENBQUMsT0FBTyxDQUFDLGNBQWMsQ0FBQyxLQUFLLENBQUMsQ0FBQyxJQUFJLEtBQUssQ0FBQyxPQUFPLENBQUMsZ0JBQWdCLENBQUMsS0FBSyxDQUFDLENBQUMsRUFBRSxDQUFDO2dCQUNuRixPQUFPLEVBQUUsR0FBRyxLQUFLLEdBQUcsU0FBUyxDQUFDO1lBQ2hDLENBQUM7WUFDRCxPQUFPLEVBQUUsR0FBRyxLQUFLLEdBQUcsVUFBVSxDQUFDO1FBQ2pDLENBQUMsQ0FBQyxDQUFDO1FBQ0gsT0FBTyxJQUFJLENBQUM7SUFDZCxDQUFDO0lBRUQsV0FBVyxDQUFDLElBQVk7UUFDdEIsSUFBSSxHQUFHLElBQUksQ0FBQyxPQUFPLENBQUMsMkNBQTJDLEVBQUUsQ0FBQyxDQUFDLEVBQUUsRUFBRSxFQUFFLEVBQUUsRUFBRSxFQUFFO1lBQzdFLElBQUksQ0FBQyxFQUFFLENBQUMsUUFBUSxDQUFDLFFBQVEsQ0FBQyxFQUFFLENBQUM7Z0JBQzNCLEVBQUUsSUFBSSx3QkFBd0IsQ0FBQztZQUNqQyxDQUFDO1lBQ0QsT0FBTyxTQUFTLEdBQUcsRUFBRSxHQUFHLEdBQUcsR0FBRyxFQUFFLEdBQUcsV0FBVyxDQUFDO1FBQ2pELENBQUMsQ0FBQyxDQUFDO1FBQ0gsT0FBTyxJQUFJLENBQUM7SUFDZCxDQUFDO0lBRUQsc0JBQXNCLENBQUMsSUFBWTtRQUNqQyxPQUFPLGlCQUFpQixHQUFHLElBQUksR0FBRyxpQkFBaUIsQ0FBQztJQUN0RCxDQUFDO0lBRUQsS0FBSyxDQUFDLFFBQVEsQ0FDWixHQUF5QixFQUFFLE9BQTJCO1FBQ3RELE9BQU8sTUFBTSxJQUFBLHFDQUFzQixFQUFJLElBQUksRUFBRSxHQUFHLEVBQUUsT0FBTyxDQUFDLENBQUM7SUFDN0QsQ0FBQztDQUNGO0FBOUJELHNDQThCQyJ9

package/dist/commonjs/app/extend/context.d.ts

@@ -0,0 +1,68 @@
+import { Context } from '@eggjs/core';
+import type { HttpClientRequestURL, HttpClientOptions, HttpClientResponse } from '../../lib/extend/safe_curl.js';
+import { SecurityConfig, SecurityHelperConfig } from '../../types.js';
+declare const CSRF_SECRET: unique symbol;
+declare const LOG_CSRF_NOTICE: unique symbol;
+declare const INPUT_TOKEN: unique symbol;
+declare const CSRF_REFERER_CHECK: unique symbol;
+declare const CSRF_CTOKEN_CHECK: unique symbol;
+export default class SecurityContext extends Context {
+    get securityOptions(): Partial<SecurityConfig>;
+    /**
+     * Check whether the specific `domain` is in / matches the whiteList or not.
+     * @param {string} domain The assigned domain.
+     * @param {Array<string>} [customWhiteList] The custom white list for domain.
+     * @return {boolean} If the domain is in / matches the whiteList, return true;
+     * otherwise false.
+     */
+    isSafeDomain(domain: string, customWhiteList?: string[]): boolean;
+    get nonce(): string;
+    /**
+     * get csrf token, general use in template
+     * @return {String} csrf token
+     * @public
+     */
+    get csrf(): string;
+    /**
+     * get csrf secret from session or cookie
+     * @return {String} csrf secret
+     * @private
+     */
+    get [CSRF_SECRET](): string;
+    /**
+     * ensure csrf secret exists in session or cookie.
+     * @param {Boolean} [rotate] reset secret even if the secret exists
+     * @public
+     */
+    ensureCsrfSecret(rotate?: boolean): void;
+    get [INPUT_TOKEN](): string;
+    /**
+     * rotate csrf secret exists in session or cookie.
+     * must rotate the secret when user login
+     * @public
+     */
+    rotateCsrfSecret(): void;
+    /**
+     * assert csrf token/referer is present
+     * @public
+     */
+    assertCsrf(): void;
+    [CSRF_CTOKEN_CHECK](): "missing csrf token" | "invalid csrf token" | undefined;
+    [CSRF_REFERER_CHECK](): "missing csrf referer or origin" | "invalid csrf referer or origin" | undefined;
+    [LOG_CSRF_NOTICE](msg: string): void;
+    safeCurl<T = any>(url: HttpClientRequestURL, options?: HttpClientOptions): Promise<HttpClientResponse<T>>;
+    unsafeRedirect(url: string, alt?: string): void;
+}
+declare module '@eggjs/core' {
+    interface Context {
+        get securityOptions(): Partial<SecurityConfig & SecurityHelperConfig>;
+        isSafeDomain(domain: string, customWhiteList?: string[]): boolean;
+        get nonce(): string;
+        get csrf(): string;
+        ensureCsrfSecret(rotate?: boolean): void;
+        rotateCsrfSecret(): void;
+        assertCsrf(): void;
+        safeCurl<T = any>(url: HttpClientRequestURL, options?: HttpClientOptions): Promise<HttpClientResponse<T>>;
+    }
+}
+export {};