Cookie ヘルパー

Cookie ヘルパーは、Cookie を管理するための簡単なインターフェースを提供し、開発者がシームレスに Cookie を設定、解析、削除できるようにします。

インポート

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

使用方法

注記: 署名付きCookieの設定と取得は、HMAC SHA-256署名を作成するために使用されるWebCrypto APIの非同期性質のため、Promiseを返します。

const app = new Hono()

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

app.get('/signed-cookie', async (c) => {
  const secret = 'secret ingredient'
  // `getSignedCookie` will return `false` for a specified cookie if the signature was tampered with or is invalid
  const allSignedCookies = await getSignedCookie(c, secret)
  const fortuneCookie = await getSignedCookie(
    c,
    secret,
    'fortune_cookie'
  )
  // ...
  const anotherSecret = 'secret chocolate chips'
  await setSignedCookie(c, 'great_cookie', 'blueberry', anotherSecret)
  deleteCookie(c, 'great_cookie')
  //
})

オプション

setCookie & setSignedCookie

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

例

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

• path: string
• secure: boolean
• domain: string

例

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

deleteCookie は削除された値を返します。

const deletedCookie = deleteCookie(c, 'delicious_cookie')

__Secure- および __Host- プレフィックス

Cookie ヘルパーは、Cookie 名の __Secure- および __Host- プレフィックスをサポートしています。

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

また、Cookie を設定する際にプレフィックスを指定する場合は、prefix オプションに値を指定してください。

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

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

ベストプラクティスの遵守

新しいCookie RFC（別名cookie-bis）とCHIPSには、開発者が従うべきCookie設定に関するいくつかのベストプラクティスが含まれています。

• RFC6265bis-13
  • Max-Age/Expires 制限
  • __Host-/__Secure- プレフィックス制限
• CHIPS-01
  • Partitioned 制限

Honoはベストプラクティスに従っています。Cookieヘルパーは、以下の条件下でCookieを解析するときにエラーをスローします。

• Cookie名が__Secure-で始まるが、secureオプションが設定されていない場合。
• Cookie名が__Host-で始まるが、secureオプションが設定されていない場合。
• Cookie名が__Host-で始まるが、pathが/でない場合。
• Cookie名が__Host-で始まるが、domainが設定されている場合。
• maxAgeオプションの値が400日より大きい場合。
• expiresオプションの値が現在時刻から400日後である場合。