auth/session_cookie.ts view source
SessionOptions<TIdentity> Configuration for a session cookie format.
Apps provide encode/decode to control the identity portion
of the cookie payload.
The TIdentity type parameter determines the trust model:
- string (e.g. a session_id) — the cookie references a server-side session record,
enabling per-session revocation and metadata. Use when you need admin controls
like "revoke all sessions" or per-session audit trails.
- number (e.g. an account_id) — the cookie directly encodes the user identity,
requiring no server-side session state. Simpler, but individual sessions
can only be invalidated by rotating the signing key (which invalidates all sessions).
examples
const zap_config: SessionOptions<string> = {
cookie_name: 'zap_session',
context_key: 'auth_session_id',
encode_identity: (session_id) => `admin:${session_id}`,
decode_identity: (payload) => {
const parts = payload.split(':');
if (parts.length !== 2 || parts[0] !== 'admin') return null;
return parts[1] || null;
},
};
const visiones_config: SessionOptions<number> = {
cookie_name: 'session_id',
context_key: 'auth_session_id',
encode_identity: (id) => String(id),
decode_identity: (payload) => {
const n = parseInt(payload, 10);
return Number.isFinite(n) && n > 0 ? n : null;
},
};
context_key
Hono context variable name for the identity.
type string
max_age
Cookie lifetime in seconds. Single source of truth for both the embedded
expires_at (via create_session_cookie_value) and the cookie's HTTP
Max-Age attribute (via set_session_cookie). Defaults to
SESSION_AGE_MAX (30 days). The cookie_options slot intentionally
cannot carry maxAge so the two values can't drift.
type number
refresh_threshold_seconds
Threshold (seconds) for expiration-based cookie refresh. When a parsed
cookie's expires_at - now <= refresh_threshold_seconds,
process_session_cookie returns action: 'refresh' with a freshly-signed
value (extending the embedded expiration by max_age). Defaults to
SESSION_REFRESH_THRESHOLD_S (1 day). Set to 0 to disable.
type number
cookie_options
type Partial<Omit<SessionCookieOptions, 'maxAge'>>
encode_identity
Encode identity into the cookie payload (before the :expires_at suffix).
type (identity: TIdentity) => string
decode_identity
Decode identity from cookie payload. Return null if invalid.
type (payload: string) => TIdentity | null