egg-cookies

Version:

cookies module for egg

83 lines (57 loc) • 7.04 kB

Markdown

# egg-cookies@2 [![NPM version][npm-image]][npm-url] [![build status][ci-image]][ci-url] [![Test coverage][codecov-image]][codecov-url] [![npm download][download-image]][download-url] [npm-image]: https://img.shields.io/npm/v/egg-cookies/release-2.x.svg?style=flat-square [npm-url]: https://npmjs.org/package/egg-cookies/v/release-2.x [ci-image]: https://github.com/eggjs/egg-cookies/actions/workflows/nodejs-2.x.yml/badge.svg [ci-url]: https://github.com/eggjs/egg-cookies/actions/workflows/nodejs-2.x.yml [codecov-image]: https://codecov.io/gh/eggjs/egg-cookies/branch/2.x/graph/badge.svg [codecov-url]: https://codecov.io/gh/eggjs/egg-cookies/tree/2.x [download-image]: https://img.shields.io/npm/dm/egg-cookies.svg?style=flat-square [download-url]: https://npmjs.org/package/egg-cookies/v/release-2.x 为 egg 提供 cookie 操作的封装。 ```js ctx.cookies = new Cookies(ctx, keys[, defaultCookieOptions]); ctx.cookies.get('key', 'value', options); ctx.cookies.set('key', 'value', options); ``` ## 初始化初始化时需要传递 Array 类型的keys 参数，否则无法使用 cookies 的 `signed` 和 `encrypt` 功能。每次设置或读取 signed cookie 或者 encrypt cookie 的时候，会用 keys 进行加密。每次加密都通过 keys 数组的第一个 key 进行加密，解密会从先到后逐个 key 尝试解密。读取 signed cookie 时，如果发现不是用第一个 key 进行加密时，会更新签名为第一个 key 加密的值。读取 encrypt cookie 时不会进行更新操作。 ### `defaultCookieOptions` 全局默认配置： - autoChips - `Boolean` 是否开启 [CHIPS](https://developers.google.com/privacy-sandbox/3pcd/chips#security_design) 的自动适配方案，会自动给 Cookie 新增一个 `_CHIPS-` 为前缀的分区 Cookie，优先读取非分区 Cookie，读取失败则尝试读取 `_CHIPS-` 前缀的同名 Cookie 适配三方 Cookie 禁止逻辑。一旦 `cookies.set` 设置 `partitioned=true`，那么会强制忽略 `autoChips` 参数。 ## 设置 cookie 通过 `cookies.set(key, value, options)` 的方式来设置一个 cookie。其中 options 支持的参数有： - path - `String` cookie 的有效路径，默认为 `/`。 - domain - `String` cookie 的有效域名范围，默认为 `undefined`。 - expires - `Date` cookie 的失效时间。 - maxAge - `Number` cookie 的最大有效时间，如果设置了 maxAge，将会覆盖 expires 的值。 - secure - `Boolean` 是否只在加密信道中传输，注意，如果请求为 http 时，不允许设置为 `true`，https 时自动设置为 `true`。 - partitioned - `Boolean` 是否设置独立分区状态（[CHIPS](https://developers.google.com/privacy-sandbox/3pcd/chips)）的 Cookie。注意，只有 `secure` 为 `true` 的时候此配置才会生效。 - removeUnpartitioned - `Boolean` 是否删除非独立分区状态的同名 cookie。注意，只有 `partitioned` 为 `true` 的时候此配置才会生效。 - httpOnly - `Boolean` 如果设置为 `true`，则浏览器中不允许读取这个 cookie 的值。 - overwrite - `Boolean` 如果设置为 `true`，在一个请求上重复写入同一个 key 将覆盖前一次写入的值，默认为 `false`。 - signed - `Boolean` 是否需要对 cookie 进行签名，需要配合 get 时传递 signed 参数，此时前端无法篡改这个 cookie，默认为 `true`。 - encrypt - `Boolean` 是否需要对 cookie 进行加密，需要配合 get 时传递 encrypt 参数，此时前端无法读到真实的 cookie 值，默认为 `false`。 - priority - `String` 表示 cookie 优先级的字符串，可以设置为 `'low'`, `'medium'`, `'high'`，默认为 `undefined`。[A Retention Priority Attribute for HTTP Cookies](https://datatracker.ietf.org/doc/html/draft-west-cookie-priority) ## 读取 cookie 通过 `cookies.get(key, value, options)` 的方式来读取一个 cookie。其中 options 支持的参数有： - signed - `Boolean` 是否需要对 cookie 进行验签，需要配合 set 时传递 signed 参数，此时前端无法篡改这个 cookie，默认为 true。 - encrypt - `Boolean` 是否需要对 cookie 进行解密，需要配合 set 时传递 encrypt 参数，此时前端无法读到真实的 cookie 值，默认为 false。 ## 删除 cookie 通过 `cookie.set(key, null)` 来删除一个 cookie。如果传递了 `signed` 参数，签名也会被删除。 ## License [MIT](LICENSE)  ## 贡献者 |[<img src="https://avatars.githubusercontent.com/u/156269?v=4" width="100px;"/> fengmk2](https://github.com/fengmk2) |[<img src="https://avatars.githubusercontent.com/u/985607?v=4" width="100px;"/> dead-horse](https://github.com/dead-horse) |[<img src="https://avatars.githubusercontent.com/u/32174276?v=4" width="100px;"/> semantic-release-bot](https://github.com/semantic-release-bot) |[<img src="https://avatars.githubusercontent.com/u/227713?v=4" width="100px;"/> atian25](https://github.com/atian25) |[<img src="https://avatars.githubusercontent.com/u/5856440?v=4" width="100px;"/> whxaxes](https://github.com/whxaxes) |[<img src="https://avatars.githubusercontent.com/u/5102113?v=4" width="100px;"/> xyeric](https://github.com/xyeric) | | :---: | :---: | :---: | :---: | :---: | :---: | |[<img src="https://avatars.githubusercontent.com/u/3939959?v=4" width="100px;"/> jedmeng](https://github.com/jedmeng) |[<img src="https://avatars.githubusercontent.com/u/17005098?v=4" width="100px;"/> Junyan](https://github.com/Junyan) |[<img src="https://avatars.githubusercontent.com/u/12657964?v=4" width="100px;"/> beliefgp](https://github.com/beliefgp) |[<img src="https://avatars.githubusercontent.com/u/52845048?v=4" width="100px;"/> snapre](https://github.com/snapre) |[<img src="https://avatars.githubusercontent.com/u/360661?v=4" width="100px;"/> popomore](https://github.com/popomore) |[<img src="https://avatars.githubusercontent.com/u/22520131?v=4" width="100px;"/> tang-xy](https://github.com/tang-xy) | [<img src="https://avatars.githubusercontent.com/u/1276859?v=4" width="100px;"/> ziyunfei](https://github.com/ziyunfei) |[<img src="https://avatars.githubusercontent.com/u/12656301?v=4" width="100px;"/> brizer](https://github.com/brizer) |[<img src="https://avatars.githubusercontent.com/u/7692708?v=4" width="100px;"/> xuezier](https://github.com/xuezier) |[<img src="https://avatars.githubusercontent.com/u/16103358?v=4" width="100px;"/> onlylovermb](https://github.com/onlylovermb) [git-contributor 说明](https://github.com/xudafeng/git-contributor)，自动生成时间：`Mon Feb 19 2024 17:41:40 GMT+0800`。