Orientation Arc
Routing Algorithms
Rendering and JSX
Runtime Adapters
Middleware Ecosystem
Developer Helpers
System Utilities
The following files were used as context for generating this wiki page:
Cookie handling in Hono is designed around web standards, providing a unified mechanism for parsing, serializing, and securing HTTP cookies across diverse serverless environments. By abstracting the complexities of the Set-Cookie header and cookie parsing, it allows developers to manage stateful interactions without worrying about low-level string manipulation or RFC-compliant parsing.
At its core, the subsystem balances ease of use with robust security requirements. It handles standard cookie parsing while offering specialized utilities for signed cookies, which ensure data integrity via HMAC-SHA256 signatures. This ensures that cookie values can be verified on the server side to detect tampering, a critical requirement for session and authentication management.
The architecture is built to be environment-agnostic. Because Hono aims to run on platforms ranging from Cloudflare Workers to AWS Lambda, the cookie utilities rely on the standard Web Crypto API (crypto.subtle) for signing operations and standard header management for persistence. This ensures that high-level abstractions remain performant and compliant with the security expectations of modern web applications.
The core parsing logic is implemented in src/utils/cookie.ts. The parse function handles incoming Cookie headers by splitting the string on semicolons and processing each key-value pair.
A key design choice here is the use of a "fast-path" for lookups. If a name is provided to parse, the implementation checks for its existence before fully iterating over the pairs, returning an empty object if the target key is absent.
// Fast-path: return immediately if the demanded-key is not in the cookie string
if (name && cookie.indexOf(name) === -1) {
return {}
}Sources: src/utils/cookie.ts:103-106
Validation is strict. The code enforces name validity through a regular expression that checks for alphanumeric and specific special characters, and value validation via a regex that restricts characters to the ASCII range 32-126 (excluding forbidden ones like double quotes).
Tip
The parser automatically unquotes values if they are enclosed in double quotes, providing seamless compatibility with varied client implementations.
Sources: src/utils/cookie.ts:125-127
Cookie serialization is handled by _serialize, which constructs the header string based on the provided CookieOptions. This includes attributes such as Domain, Path, Max-Age, and Secure.
To prevent tampering, serializeSigned (and parseSigned) facilitates HMAC-based signing. The mechanism:
CryptoKey using crypto.subtle.importKey with the HMAC SHA-256 algorithm.value.signature).const makeSignature = async (value: string, secret: string | BufferSource): Promise<string> => {
const key = await getCryptoKey(secret)
const signature = await crypto.subtle.sign(algorithm.name, key, new TextEncoder().encode(value))
return btoa(String.fromCharCode(...new Uint8Array(signature)))
}Sources: src/utils/cookie.ts:44-49
The system enforces RFC 6265bis recommendations for cookie prefixes, specifically __Secure- and __Host-. The _serialize function contains explicit guards to ensure these attributes are handled correctly.
If these invariants are not met, the code throws an explicit Error, preventing the creation of insecure cookies in sensitive contexts.
if (name.startsWith('__Host-')) {
if (!opt.secure) {
throw new Error('__Host- Cookie must have Secure attributes')
}
// ... check path and domain
}Sources: src/utils/cookie.ts:179-192
Different serverless adapters need different ways to set and get cookies. For example, AWS Lambda provides cookies in an event object for V2, while ALB might use multiValueHeaders. The adapter/aws-lambda implementation provides a setCookies mechanism that detects if getSetCookie() is available on the Headers object.
this.setCookies(_event: E, res: Response, result: APIGatewayProxyResult) {
if (res.headers.has('set-cookie')) {
const cookies = res.headers.getSetCookie
? res.headers.getSetCookie()
: Array.from(res.headers.entries())
.filter(([k]) => k === 'set-cookie')
.map(([, v]) => v)
// ...
}
}This ensures that regardless of whether the platform supports the standard getSetCookie() API (common in modern runtimes), the handler can extract multiple cookies accurately.
The helper/cookie module acts as the public-facing API for Hono applications. It provides high-level methods to interact with the Context.
import { setCookie, getCookie } from 'hono/cookie'
app.get('/set', (c) => {
setCookie(c, 'flavor', 'chocolate', { httpOnly: true, secure: true })
return c.text('cookie set')
})Sources: src/helper/cookie/index.ts:99-102
The helper layer handles the injection of the Set-Cookie header into the response, using { append: true } to ensure multiple cookies can be set in a single response cycle.