쿠키 헬퍼

쿠키 헬퍼는 개발자가 쿠키를 쉽게 관리할 수 있는 간편한 인터페이스를 제공한다. 쿠키 설정, 파싱, 삭제를 원활하게 처리할 수 있다.

Import

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

사용 방법

참고: 서명된 쿠키를 설정하고 가져오는 작업은 WebCrypto API를 사용해 HMAC SHA-256 서명을 생성하기 때문에 비동기적으로 처리된다. 따라서 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`는 서명이 변조되었거나 유효하지 않은 경우 특정 쿠키에 대해 `false`를 반환한다
  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'
• priority: 'Low' | 'Medium' | 'High'
• prefix: secure | 'host'
• partitioned: boolean

예제:

// 일반 쿠키
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',
})

// 서명된 쿠키
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 헬퍼는 쿠키 이름에 __Secure-와 __Host- 접두사를 지원한다.

쿠키 이름에 접두사가 있는지 확인하려면 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'
)

또한 쿠키를 설정할 때 접두사를 지정하려면 prefix 옵션에 값을 지정한다.

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

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

모범 사례 따르기

새로운 쿠키 RFC(cookie-bis)와 CHIPS는 개발자가 따라야 할 쿠키 설정에 대한 모범 사례를 포함한다.

• RFC6265bis-13
  • Max-Age/Expires 제한
  • __Host-/__Secure- 접두사 제한
• CHIPS-01
  • Partitioned 제한

Hono는 이러한 모범 사례를 따른다. 쿠키 헬퍼는 다음 조건에서 쿠키를 파싱할 때 Error를 발생시킨다:

• 쿠키 이름이 __Secure-로 시작하지만 secure 옵션이 설정되지 않은 경우
• 쿠키 이름이 __Host-로 시작하지만 secure 옵션이 설정되지 않은 경우
• 쿠키 이름이 __Host-로 시작하지만 path가 /가 아닌 경우
• 쿠키 이름이 __Host-로 시작하지만 domain이 설정된 경우
• maxAge 옵션 값이 400일을 초과하는 경우
• expires 옵션 값이 현재 시간으로부터 400일 이후인 경우