Utilitaire Cookie

L’utilitaire Cookie fournit une interface simple pour gérer les cookies et permet aux développeurs de les définir, de les analyser et de les supprimer facilement.

Importation

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

Utilisation

Cookies ordinaires

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

Cookies signés

REMARQUE : La définition et la récupération de cookies signés renvoient une Promise en raison de la nature asynchrone de l’API WebCrypto, utilisée pour créer les signatures HMAC SHA-256.

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 distingue deux cas. Un cookie doté d’une signature dont la vérification échoue renvoie false. Un cookie dont la signature n’a pas un format valide est considéré comme non signé et renvoie undefined, comme lorsque le cookie est absent. Cette règle s’applique aussi bien à la récupération d’un seul cookie par son nom qu’à celle de tous les cookies signés. Puisque false et undefined sont tous deux des valeurs falsy, if (!value) couvre les deux cas.

Génération de cookies

Les fonctions generateCookie et generateSignedCookie permettent de créer directement des chaînes de cookies sans les définir dans les en-têtes de réponse.

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

Remarque : Contrairement à setCookie et setSignedCookie, ces fonctions génèrent uniquement les chaînes de cookies. Vous devez les ajouter vous-même aux en-têtes si nécessaire.

Options

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

Exemple :

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

Exemple :

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

deleteCookie renvoie la valeur supprimée :

const deletedCookie = deleteCookie(c, 'delicious_cookie')

Préfixes __Secure- et __Host-

L’utilitaire Cookie prend en charge les préfixes __Secure- et __Host- pour les noms des cookies.

Pour vérifier si le nom du cookie possède un préfixe, spécifiez l’option de préfixe.

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

De même, pour spécifier un préfixe lors de la définition d’un cookie, donnez une valeur à l’option de préfixe.

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

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

Respect des bonnes pratiques

La nouvelle RFC sur les cookies (également appelée cookie-bis) et CHIPS incluent des bonnes pratiques de configuration des cookies que les développeurs devraient respecter.

• RFC6265bis-13
  • Limitation de Max-Age/Expires
  • Restrictions relatives aux préfixes __Host-/__Secure-
• CHIPS-01
  • Restriction relative à Partitioned

Hono respecte ces bonnes pratiques. L’utilitaire Cookie lève une Error lors de l’analyse des cookies dans les cas suivants :

• Le nom du cookie commence par __Secure-, mais l’option secure n’est pas définie.
• Le nom du cookie commence par __Host-, mais l’option secure n’est pas définie.
• Le nom du cookie commence par __Host-, mais path n’est pas /.
• Le nom du cookie commence par __Host-, mais domain est défini.
• La valeur de l’option maxAge dépasse 400 jours.
• La valeur de l’option expires est située plus de 400 jours après l’heure actuelle.