包详细信息

@eggjs/cookies

eggjs1.4kMIT3.1.0

cookies module for egg

自述文件

@eggjs/cookies

NPM version build status Test coverage npm download

为 egg 提供 cookie 操作的封装。

ctx.cookies = new Cookies(ctx, keys[, defaultCookieOptions]);

ctx.cookies.get('key', 'value', options);
ctx.cookies.set('key', 'value', options);

初始化

初始化时需要传递 Array 类型 的keys 参数,否则无法使用 cookies 的 signedencrypt 功能。

每次设置或读取 signed cookie 或者 encrypt cookie 的时候,会用 keys 进行加密。每次加密都通过 keys 数组的第一个 key 进行加密,解密会从先到后逐个 key 尝试解密。读取 signed cookie 时,如果发现不是用第一个 key 进行加密时,会更新签名为第一个 key 加密的值。读取 encrypt cookie 时不会进行更新操作。

defaultCookieOptions

全局默认配置:

  • autoChips - Boolean 是否开启 CHIPS 的自动适配方案, 会自动给 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)的 Cookie。注意,只有 securetrue 的时候此配置才会生效。
  • removeUnpartitioned - Boolean 是否删除非独立分区状态的同名 cookie。注意,只有 partitionedtrue 的时候此配置才会生效。
  • 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',默认为 undefinedA Retention Priority Attribute for HTTP Cookies

读取 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

Contributors

Contributors

Made with contributors-img.

更新日志

Changelog

3.1.0 (2024-12-26)

Features

3.0.1 (2024-07-06)

Bug Fixes

  • partitioned and autoChips should support different paths (#55) (50b1313)

3.0.0 (2024-06-23)

⚠ BREAKING CHANGES

  • drop Node.js < 18.19.0 support

part of https://github.com/eggjs/egg/issues/3644

Summary by CodeRabbit

  • New Features
  • Introduced comprehensive support for TypeScript in project configurations.
  • Added new cookie management functionalities, including setting, encryption, and validation.

    • Added support for Keygrip class for cryptographic operations.
  • Documentation

  • Updated package name in README files from egg-cookies to @eggjs/cookies.
  • Adjusted code snippets and URLs in documentation to reflect the new package name.

  • Tests

  • Enhanced test suite with additional test cases for cookie encryption, caching, and error handling.

    • Added new test files for Keygrip and cookie functionalities.
  • Chores

    • Updated .gitignore to include new patterns for ignoring files.
  • Improved CI workflow with updated Node.js versions and Codecov token integration.
  • Updated dependencies and scripts in package.json to align with the new package structure and TypeScript support.

Features

  • support cjs and esm both by tshy (#54) (12db545)

2.10.0 (2024-02-19)

Features

2.9.4 (2024-01-05)

Bug Fixes

  • disable autoChips if set cookie with partitioned (#51) (148c61c)

2.9.3 (2024-01-04)

Reverts

  • Revert "fix: only enable autoChips on cross-site request (#49)" (#50) (b0452dd), closes #49 #50

2.9.2 (2024-01-04)

Bug Fixes

  • only enable autoChips on cross-site request (#49) (665a335)

2.9.1 (2024-01-03)

Bug Fixes

  • use _CHIPS- prefix instead of __Host- (#48) (6b5e5be)

2.9.0 (2024-01-03)

Features

  • add autoChips to adaptation CHIPS mode (#47) (38d6408)

2.8.3 (2023-12-28)

Bug Fixes

  • should not set sameSite and CHIPS when secure = false (#45) (33395bf)

2.8.2 (2023-12-28)

Bug Fixes

  • support remove unpartitioned same name cookie first (#44) (b81f041)

2.8.1 (2023-12-27)

Bug Fixes

2.8.0 (2023-12-26)

Features

  • support set partitioned property on Chrome >= 114 (#42) (74325b8)

2.7.1 (2023-08-04)

Bug Fixes

2.7.0 (2023-08-04)

Features


2.6.1 / 2022-06-20

others

2.6.0 / 2022-06-20

features

2.5.0 / 2022-05-02

features

others

2.4.3 / 2022-04-29

fixes

2.4.2 / 2020-06-28

fixes

2.4.1 / 2020-06-28

fixes

2.4.0 / 2020-06-22

features

2.3.4 / 2020-06-12

fixes

2.3.3 / 2020-03-27

fixes

2.3.2 / 2020-02-19

fixes

2.3.1 / 2019-12-17

fixes

2.3.0 / 2019-12-06

features

others

2.2.7 / 2019-04-28

fixes

2.2.6 / 2018-09-07

  • fix: should still support 4, 6 (#16)

2.2.5 / 2018-09-07

  • chore(typings): Remove 'ctx' in EggCookie's declaration and add a missing unit test (#15)

2.2.4 / 2018-09-06

  • fix: public files && deps (#14)

2.2.3 / 2018-09-06

  • chore: adjust some dep && config (#13)
  • test: Add unit tests for ts (#12)
  • chore(typings): Extract 'EggCookies' for TypeScript intellisense (#11)

2.2.2 / 2017-12-14

fixes

others

2.2.1 / 2017-02-22

  • fix: emit on ctx.app (#5)

2.2.0 / 2017-02-21

  • feat: check cookie value's length (#4)
  • feat: support cookie.sameSite (#3)

2.1.0 / 2016-11-22

  • feat: cache keygrip (#2)

2.0.0 / 2016-11-22

  • refactor: rewrite keygrip and cookies for egg/koa (#1)
  • chore: add zh-CN readme

1.0.0 / 2016-07-15

  • init version