Cookie-Helfer

Der Cookie-Helfer bietet eine einfache Schnittstelle zur Verwaltung von Cookies, mit der Entwickler Cookies problemlos setzen, auslesen und löschen können.

Import

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

Verwendung

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

Signierte Cookies

HINWEIS: Das Setzen und Abrufen signierter Cookies gibt ein Promise zurück, da die WebCrypto-API zur Erstellung von HMAC-SHA-256-Signaturen asynchron arbeitet.

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 unterscheidet zwei Fälle. Ein Cookie, das eine Signatur hat, deren Prüfung aber fehlschlägt, liefert false. Ein Cookie ohne gültiges Signaturformat gilt nicht als signiertes Cookie und liefert undefined, genau wie ein nicht vorhandenes Cookie. Diese Regel gilt sowohl beim Abrufen eines einzelnen Cookies nach Namen als auch beim Abrufen aller signierten Cookies. Da sowohl false als auch undefined falsy sind, behandelt if (!value) beide Fälle.

Cookies erzeugen

Mit den Funktionen generateCookie und generateSignedCookie kannst du Cookie-Zeichenfolgen direkt erzeugen, ohne sie in den Antwort-Headern zu setzen.

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

Hinweis: Anders als setCookie und setSignedCookie erzeugen diese Funktionen nur die Cookie-Zeichenfolgen. Falls erforderlich, musst du sie selbst in den Headern setzen.

Optionen

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

Beispiel:

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

Beispiel:

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

deleteCookie gibt den gelöschten Wert zurück:

const deletedCookie = deleteCookie(c, 'delicious_cookie')

Präfixe __Secure- und __Host-

Der Cookie-Helfer unterstützt die Präfixe __Secure- und __Host- für Cookie-Namen.

Wenn du prüfen möchtest, ob der Cookie-Name ein Präfix hat, gib die Option prefix an.

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

Wenn du beim Setzen des Cookies ein Präfix angeben möchtest, lege ebenfalls einen Wert für die Option prefix fest.

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

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

Bewährte Vorgehensweisen einhalten

Ein neuer Cookie-RFC (auch cookie-bis genannt) und CHIPS enthalten bewährte Vorgehensweisen für Cookie-Einstellungen, die Entwickler beachten sollten.

• RFC6265bis-13
  • Beschränkung für Max-Age/Expires
  • Beschränkung für die Präfixe __Host-/__Secure-
• CHIPS-01
  • Beschränkung für Partitioned

Hono hält sich an diese bewährten Vorgehensweisen. Der Cookie-Helfer löst beim Auslesen von Cookies unter folgenden Bedingungen einen Error aus:

• Der Cookie-Name beginnt mit __Secure-, aber die Option secure ist nicht gesetzt.
• Der Cookie-Name beginnt mit __Host-, aber die Option secure ist nicht gesetzt.
• Der Cookie-Name beginnt mit __Host-, aber path ist nicht /.
• Der Cookie-Name beginnt mit __Host-, aber domain ist gesetzt.
• Der Wert der Option maxAge ist größer als 400 Tage.
• Der Wert der Option expires liegt mehr als 400 Tage nach dem aktuellen Zeitpunkt.