Cookie ヘルパー

Cookie ヘルパーは、Cookie を簡単に管理できるインターフェースを提供し、設定、解析、削除を円滑に行えます。

インポート

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

使い方

通常の Cookie

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

注意：署名付き Cookie の設定と取得は Promise を返します。HMAC SHA-256 署名の生成に使う WebCrypto API が非同期であるためです。

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 は 2 つの場合を区別します。署名はあるものの検証に失敗した Cookie では false を返します。署名の形式が有効でない Cookie は署名付き Cookie ではないものとして扱い、Cookie が存在しない場合と同じく undefined を返します。この規則は、名前で 1 つの Cookie を取得する場合と、すべての署名付き Cookie を取得する場合の両方に適用されます。false と undefined はどちらも偽値なので、if (!value) で両方を処理できます。

Cookie の生成

generateCookie と generateSignedCookie 関数は、レスポンスヘッダーへの設定を行わずに、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

// 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 文字列の生成だけを行います。必要に応じて、ヘッダーへの設定は手動で行ってください。

オプション

setCookie & setSignedCookie

• 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

例：

// 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 を解析すると Error をスローします。

• Cookie 名が __Secure- で始まり、secure オプションが設定されていない。
• Cookie 名が __Host- で始まり、secure オプションが設定されていない。
• Cookie 名が __Host- で始まり、path が / ではない。
• Cookie 名が __Host- で始まり、domain が設定されている。
• maxAge オプションの値が 400 日を超えている。
• expires オプションの値が現在から 400 日を超えた日時である。