Documentation / zerotal / session / CookieDriver
Class: CookieDriver
Defined in: packages/session/src/drivers/CookieDriver.ts:106
Cookie-based session driver.
Stores the session ID and all data in a single encrypted cookie:
base64url( IV ‖ GCM tag ‖ AES-256-GCM ciphertext of JSON({id, data}) ),
the same primitive (and layout) as Crypt in @zerotal/core, keyed off this
driver's secret via SHA-256.
AES-256-GCM is authenticated encryption, so this replaces the previous sign-only (HMAC) format with a strict upgrade:
- Confidential — session contents are no longer client-readable. Signed base64 could be decoded by anyone holding the cookie (user IDs, flash data, anything a controller put in the session).
- Authenticated — tampered or truncated cookies fail decryption; there is no separate signature to compare, hence no comparison to get wrong.
Backward compatibility: cookies written by the old signed-only format fail to decrypt and are treated as an absent session (a fresh one is started) — the standard practice when rotating cookie formats or keys.
Size: the serialized cookie must stay within the 4096-byte browser limit;
saveSession throws SessionCookieOverflowError instead of emitting
a cookie the browser would truncate or drop.
Implements
Constructors
Constructor
new CookieDriver(
secret,cookieName?,maxAge?,secure?,absoluteMaxAge?):CookieDriver
Defined in: packages/session/src/drivers/CookieDriver.ts:122
Parameters
secret
string
Signing/encryption secret. A base64:-prefixed value is
base64-decoded first (same rule as core Crypt). Must be non-empty.
cookieName?
string = "session"
Name of the session cookie. Defaults to "session".
maxAge?
number = 86_400
Idle lifetime in seconds, applied as both the cookie Max-Age and the
envelope's exp. Sliding: refreshed on every save. Defaults to 86400 (24h).
secure?
boolean = false
Set the Secure flag on the cookie. Defaults to false.
absoluteMaxAge?
number = DEFAULT_ABSOLUTE_MAX_AGE
Hard lifetime in seconds from first issue, regardless of
activity. Defaults to 14 days. Pass 0 to disable (not recommended — a cookie
session has no server-side record to revoke, so this is its only forced end).
Returns
CookieDriver
Throws
SessionSecretMissingError when secret is empty.
Properties
cookieName
readonlycookieName:string="session"
Defined in: packages/session/src/drivers/CookieDriver.ts:124
Name of the session cookie. Defaults to "session".
Methods
loadFromRequest()
loadFromRequest(
request):Promise<SessionPayload>
Defined in: packages/session/src/drivers/CookieDriver.ts:151
Decrypt the session cookie into a SessionPayload. Any failure — missing cookie, tampering, truncation, a rotated secret, an expired envelope, or a legacy signed-only cookie — yields a fresh session rather than an error.
Expiry is enforced here, on the server, not left to the browser's Max-Age. A cookie
session has no server-side record, so the envelope's own exp and iat are the only
thing standing between a captured cookie and an indefinitely valid credential; a client
that simply keeps replaying the cookie past its Max-Age gets nothing.
Parameters
request
Request
Request whose session cookie is read.
Returns
Promise<SessionPayload>
Implementation of
saveSession()
saveSession(
id,data,response):Promise<void>
Defined in: packages/session/src/drivers/CookieDriver.ts:198
Encrypt { id, data, iat, exp } and append it as the session cookie.
exp slides forward by maxAge on every save; iat is carried through from the
original issue (see SESSION_ISSUED_AT_KEY) so refreshing cannot extend the
session past absoluteMaxAge.
Parameters
id
string
data
Record<string, unknown>
response
Response
Returns
Promise<void>
Throws
SessionCookieOverflowError when the serialized cookie exceeds the 4096-byte browser limit.