Cookie Helper

模型写的

背景主张方法设置结果分析局限

Cookie Helper 管理 cookie：设置、解析、删除普通与签名 cookie

The Cookie Helper provides an easy interface to manage cookies, enabling developers to set, parse, and delete cookies seamlessly.The Cookie Helper provides an easy interface to manage cookies, enabling developers to set, parse, and delete cookies seamlessly.Cookie Helper 管理 cookie,支持无缝设置、解析和删除它封装 cookie 处理,让开发者无需手动操作响应头Cookie Helper 管理 cookie,支持无缝设置、解析和删除Cookie Helper

Import

import { Hono } from 'hono'
import {
  deleteCookie,
  getCookie,
  getSignedCookie,
  setCookie,
  setSignedCookie,
  generateCookie,
  generateSignedCookie,
} from 'hono/cookie'

Usage

Regular cookies

app.get('/cookie', (c) => {
  setCookie(c, 'cookie_name', 'cookie_value')
  const yummyCookie = getCookie(c, 'cookie_name')
  deleteCookie(c, 'cookie_name')
  const allCookies = getCookie(c)
  // ...
})

Signed cookies

签名 cookie 需 await，因为 WebCrypto HMAC SHA-256 签名是异步的

NOTE: Setting and retrieving signed cookies returns a Promise due to the async nature of the WebCrypto API, which is used to create HMAC SHA-256 signatures.NOTE: Setting and retrieving signed cookies returns a Promise due to the async nature of the WebCrypto API, which is used to create HMAC SHA-256 signatures.签名 cookie 操作因 WebCrypto 异步而返回 Promise HMAC SHA-256 签名通过异步 WebCrypto API 生成签名 cookie 操作因 WebCrypto 异步而返回 Promise签名 cookie

app.get('/signed-cookie', (c) => {
  const secret = 'secret' // make sure it's a large enough string to be secure

  await setSignedCookie(c, 'cookie_name0', 'cookie_value', secret)
  const fortuneCookie = await getSignedCookie(
    c,
    secret,
    'cookie_name0'
  )
  deleteCookie(c, 'cookie_name0')
  // `getSignedCookie` will return `false` for a specified cookie if its signature fails verification
  const allSignedCookies = await getSignedCookie(c, secret)
  // ...
})

Note

getSignedCookie distinguishes two cases. A cookie that has a signature but fails verification returns false. A cookie that does not have a valid signature format is treated as not being a signed cookie at all and returns undefined — the same as when the cookie is not present. This rule applies both when retrieving a single cookie by name and when retrieving all signed cookies. Since both false and undefined are falsy, if (!value) handles both cases.Since both false and undefined are falsy, if (! value) handles both cases.签名错误返回 false,格式无效返回 undefined 两者都为假值,因此 if (!value) 可同时处理验证失败与缺失签名错误返回 false,格式无效返回 undefined签名错误

generateCookie 和 generateSignedCookie 只生成 cookie 字符串,不设置响应头

generateCookie and generateSignedCookie functions allow you to create cookie strings directly without setting them in the response headers.generateCookie and generateSignedCookie functions allow you to create cookie strings directly without setting them in the response headers.generateCookie 和 generateSignedCookie 直接生成 cookie 字符串它们不设置响应头,生成的字符串需手动写入generateCookie 和 generateSignedCookie 直接生成 cookie 字符串cookie 字符串

`generateCookie`

// Basic cookie generation
const cookie = generateCookie('delicious_cookie', 'macha')
// Returns: 'delicious_cookie=macha; Path=/'

// Cookie with options
const cookie = generateCookie('delicious_cookie', 'macha', {
  path: '/',
  secure: true,
  httpOnly: true,
  domain: 'example.com',
})

`generateSignedCookie`

generateSignedCookie 接收 secret 并可选设置 cookie 选项

// Basic signed cookie generation
const signedCookie = await generateSignedCookie(
  'delicious_cookie',
  'macha',
  'secret chocolate chips'
)

// Signed cookie with options
const signedCookie = await generateSignedCookie(
  'delicious_cookie',
  'macha',
  'secret chocolate chips',
  {
    path: '/',
    secure: true,
    httpOnly: true,
  }
)

Note: Unlike setCookie and setSignedCookie, these functions only generate the cookie strings. You need to manually set them in headers if needed.Note: Unlike setCookie and setSignedCookie, these functions only generate the cookie strings. You need to manually set them in headers if needed.这些函数只生成 cookie 字符串,不设置响应头你需要自己把生成的字符串写入响应头这些函数只生成 cookie 字符串,不设置响应头cookie 字符串

Options

`setCookie` & `setSignedCookie`

setCookie 和 setSignedCookie 接受 domain、expires、httpOnly、maxAge、path 等选项

domain: string
expires: Date
httpOnly: boolean
maxAge: number
path: string
secure: boolean
sameSite: 'Strict' | 'Lax' | 'None'
priority: 'Low' | 'Medium' | 'High'
prefix: secure | 'host'
partitioned: boolean

Example:Example:setCookie 和 setSignedCookie 接受多个 cookie 选项 path、secure、domain、maxAge、expires、sameSite 等选项通过对象传入setCookie 和 setSignedCookie 接受多个 cookie 选项cookie 选项

// Regular cookies
setCookie(c, 'great_cookie', 'banana', {
  path: '/',
  secure: true,
  domain: 'example.com',
  httpOnly: true,
  maxAge: 1000,
  expires: new Date(Date.UTC(2000, 11, 24, 10, 30, 59, 900)),
  sameSite: 'Strict',
})

// Signed cookies
await setSignedCookie(
  c,
  'fortune_cookie',
  'lots-of-money',
  'secret ingredient',
  {
    path: '/',
    secure: true,
    domain: 'example.com',
    httpOnly: true,
    maxAge: 1000,
    expires: new Date(Date.UTC(2000, 11, 24, 10, 30, 59, 900)),
    sameSite: 'Strict',
  }
)

`deleteCookie`

deleteCookie 接受 path、secure、domain 选项并返回被删除的值

path: string
secure: boolean
domain: string

Example:Example:deleteCookie 接受 path、secure 和 domain 选项这些选项需与设置 cookie 时一致,删除才会生效deleteCookie 接受 path、secure 和 domain 选项deleteCookie 选项

deleteCookie(c, 'banana', {
  path: '/',
  secure: true,
  domain: 'example.com',
})

deleteCookie returns the deleted value:deleteCookie returns the deleted value:deleteCookie 返回被删除的值被移除的 cookie 值会被返回,便于调用方查看deleteCookie 返回被删除的值被删除的值

const deletedCookie = deleteCookie(c, 'delicious_cookie')

`Secure-` and `Host-` prefix

prefix 选项校验并设置 __Secure- 和 __Host- 开头的 cookie 名

The Cookie helper supports __Secure- and __Host- prefixes for cookie names.The Cookie helper supports __Secure- and __Host- prefixes for cookie names.Cookie helper 支持 __Secure- 和 __Host- 名称前缀这些前缀对 cookie 的设置方式施加安全约束Cookie helper 支持 __Secure- 和 __Host- 名称前缀__Secure- 前缀

If you want to verify if the cookie name has a prefix, specify the prefix option.If you want to verify if the cookie name has a prefix, specify the prefix option.指定 prefix 选项即可校验 cookie 名称前缀读取时 getCookie 和 getSignedCookie 以额外参数传入前缀值指定 prefix 选项即可校验 cookie 名称前缀prefix 选项

const securePrefixCookie = getCookie(c, 'yummy_cookie', 'secure')
const hostPrefixCookie = getCookie(c, 'yummy_cookie', 'host')

const securePrefixSignedCookie = await getSignedCookie(
  c,
  secret,
  'fortune_cookie',
  'secure'
)
const hostPrefixSignedCookie = await getSignedCookie(
  c,
  secret,
  'fortune_cookie',
  'host'
)

Also, if you wish to specify a prefix when setting the cookie, specify a value for the prefix option.Also, if you wish to specify a prefix when setting the cookie, specify a value for the prefix option.设置带前缀 cookie 时需指定 prefix 选项传入 prefix secure 或 host 会为 cookie 名加上对应前缀设置带前缀 cookie 时需指定 prefix 选项prefix 选项

setCookie(c, 'delicious_cookie', 'macha', {
  prefix: 'secure', // or `host`
})

await setSignedCookie(
  c,
  'delicious_cookie',
  'macha',
  'secret choco chips',
  {
    prefix: 'secure', // or `host`
  }
)

Following the best practices

Hono 在违反 cookie 最佳实践(如 maxAge 过长)时抛错

A New Cookie RFC (a.k.a cookie-bis) and CHIPS include some best practices for Cookie settings that developers should follow.A New Cookie RFC (a.k.a cookie-bis) and CHIPS include some best practices for Cookie settings that developers should follow.新 Cookie RFC 和 CHIPS 定义了 cookie 最佳实践这些规范描述了开发者应遵循的安全设置新 Cookie RFC 和 CHIPS 定义了 cookie 最佳实践cookie 最佳实践

RFC6265bis-13
- Max-Age/Expires limitation
- __Host-/__Secure- prefix limitation
CHIPS-01
- Partitioned limitation

Hono is following the best practices. The cookie helper will throw an Error when parsing cookies under the following conditions:Hono is following the best practices. The cookie helper will throw an Error when parsing cookies under the following conditions:Hono 遵循最佳实践,解析违规时抛错在缺少 secure 或 maxAge 过大等所列条件下会抛出错误Hono 遵循最佳实践,解析违规时抛错Hono 遵循

The cookie name starts with __Secure-, but secure option is not set.
The cookie name starts with __Secure-, but secure option is not set.
__Secure- 名称未设 secure 选项会抛错带该前缀的 cookie 必须带 secure 属性
__Secure- 名称未设 secure 选项会抛错
__Secure- 名称
The cookie name starts with __Host-, but secure option is not set.
The cookie name starts with __Host-, but secure option is not set.
__Host- 名称未设 secure 选项会抛错带 host 前缀的 cookie 必须标记为 secure 才能通过
__Host- 名称未设 secure 选项会抛错
__Host- 名称
The cookie name starts with __Host-, but path is not /.
The cookie name starts with __Host-, but path is not /.
__Host- 名称 path 非 / 会抛错 __Host- 前缀要求 cookie 路径必须为 /
__Host- 名称 path 非 / 会抛错
__Host- path
The cookie name starts with __Host-, but domain is set.
The cookie name starts with __Host-, but domain is set.
__Host- 名称设置 domain 会抛错带 host 前缀的 cookie 不得带 domain 属性
__Host- 名称设置 domain 会抛错
__Host- domain
The maxAge option value is greater than 400 days.
The maxAge option value is greater than 400 days.
maxAge 大于 400 天会抛错 RFC 将 cookie 生命周期上限设为 400 天
maxAge 大于 400 天会抛错
maxAge 限制
The expires option value is 400 days later than the current time.
The expires option value is 400 days later than the current time.
expires 超过当前 400 天会抛错 expires 选项同样受 400 天生命周期上限约束
expires 超过当前 400 天会抛错
expires 限制

要点（模型写的）

Cookie Helper

Import

Usage

Regular cookies

Signed cookies

Cookie Generation

generateCookie

generateSignedCookie