Cookie 助手

¥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.

导入

¥Import

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

用法

¥Usage

常规 Cookie

¥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)
  // ...
})

签名 Cookie

¥Signed cookies

注意：由于 WebCrypto API 的异步特性，设置和检索签名的 cookie 会返回 Promise，该 API 用于创建 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.

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 the signature was tampered with or is invalid
  const allSignedCookies = await getSignedCookie(c, secret)
  // ...
})

Cookie 生成

¥Cookie Generation

generateCookie 和 generateSignedCookie 函数允许你直接创建 Cookie 字符串，而无需在响应头中设置它们。

¥generateCookie and generateSignedCookie functions allow you to create cookie strings directly without setting them in the response headers.

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

// 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,
  }
)

注意：与 setCookie 和 setSignedCookie 不同，这些函数仅生成 Cookie 字符串。如果需要，你需要在标题中手动设置它们。

¥Note: Unlike setCookie and setSignedCookie, these functions only generate the cookie strings. You need to manually set them in headers if needed.

选项

¥Options

setCookie & setSignedCookie

• domain:string

• expires:Date

• httpOnly:boolean

• maxAge:number

• 路径：string

  ¥path: string

• 安全：boolean

  ¥secure: boolean

• sameSite：'Strict' | 'Lax' | 'None'

• 优先级：'Low' | 'Medium' | 'High'

  ¥priority: 'Low' | 'Medium' | 'High'

• 前缀：secure | 'host'

  ¥prefix: secure | 'host'

• 分区：boolean

  ¥partitioned: boolean

示例：

¥Example:

// 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

• 路径：string

  ¥path: string

• 安全：boolean

  ¥secure: boolean

• domain:string

示例：

¥Example:

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

deleteCookie 返回已删除的值：

¥deleteCookie returns the deleted value:

const deletedCookie = deleteCookie(c, 'delicious_cookie')

__Secure- 和 __Host- 前缀

¥__Secure- and __Host- prefix

Cookie 助手支持 __Secure- 和 __Host- 作为 cookie 名称的前缀。

¥The Cookie helper supports __Secure- and __Host- prefix for cookies names.

如果要验证 cookie 名称是否有前缀，请指定前缀选项。

¥If you want to verify if the cookie name has a prefix, specify the prefix option.

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'
)

此外，如果你希望在设置 cookie 时指定前缀，请为前缀选项指定一个值。

¥Also, if you wish to specify a prefix when setting the cookie, specify a value for the prefix option.

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

新的 Cookie RFC（又名 cookie-bis）和 CHIPS 包含一些开发者应遵循的 Cookie 设置最佳实践。

¥A New Cookie RFC (a.k.a cookie-bis) and CHIPS include some best practices for Cookie settings that developers should follow.

• RFC6265bis-13

  • Max-Age/Expires 限制

    ¥Max-Age/Expires limitation

  • __Host-/__Secure- 前缀限制

    ¥__Host-/__Secure- prefix limitation

• CHIPS-01

  • Partitioned 限制

    ¥Partitioned limitation

Hono 遵循最佳实践。在以下条件下解析 cookie 时，cookie 助手将抛出 Error：

¥Hono is following the best practices. The cookie helper will throw an Error when parsing cookies under the following conditions:

• cookie 名称以 __Secure- 开头，但未设置 secure 选项。

  ¥The cookie name starts with __Secure-, but secure option is not set.

• cookie 名称以 __Host- 开头，但未设置 secure 选项。

  ¥The cookie name starts with __Host-, but secure option is not set.

• cookie 名称以 __Host- 开头，但 path 不是 /。

  ¥The cookie name starts with __Host-, but path is not /.

• cookie 名称以 __Host- 开头，但设置了 domain。

  ¥The cookie name starts with __Host-, but domain is set.

• maxAge 选项值大于 400 天。

  ¥The maxAge option value is greater than 400 days.

• expires 选项值比当前时间晚 400 天。

  ¥The expires option value is 400 days later than the current time.