Generic session management for cookie-based auth.
Parameterized on identity type via SessionOptions<TIdentity>.
Handles signing, expiration, and key rotation. Apps provide
encode/decode for their specific identity format.
Cookie value format: ${encode(identity)}:${expires_at} (signed with HMAC-SHA256).
11 declarations
auth/session_cookie.ts view source
(cookie_name: string): SessionOptions<string> Create a session config for raw session token identity.
The standard pattern: cookie stores the raw session token,
server hashes it (blake3) to look up the auth_session row.
Only the cookie_name varies per app.
cookie_namecookie name (e.g. 'tx_session', 'visiones_session')
stringSessionOptions<string> a SessionOptions<string> ready for use with session middleware
auth/session_cookie.ts view source
<TIdentity>(keyring: Keyring, identity: TIdentity, options: SessionOptions<TIdentity>, now_seconds?: number | undefined): Promise<string> Create a signed session cookie value.
Format: ${encode(identity)}:${expires_at} signed with HMAC-SHA256.
Embeds expiration in the signed value itself for defense-in-depth.
keyringkey ring for signing
identitythe identity to encode
TIdentityoptionssession configuration with encode logic
SessionOptions<TIdentity>now_seconds?current time in seconds (for testing)
number | undefinedPromise<string> signed cookie value string
auth/session_cookie.ts view source
SessionOptions<string> Canonical session config for fuz_app auth.
auth/session_cookie.ts view source
<TIdentity>(signed_value: string | undefined, keyring: Keyring, options: SessionOptions<TIdentity>, now_seconds?: number | undefined): Promise<ParsedSession<...> | null | undefined> Parse a signed session cookie value.
The signed value format is ${encode(identity)}:${expires_at}.
Tries all keys in order to support key rotation.
signed_valuethe raw cookie value (signed)
string | undefinedkeyringkey ring for verification
optionssession configuration with decode logic
SessionOptions<TIdentity>now_seconds?current time in seconds (for testing)
number | undefinedPromise<ParsedSession<TIdentity> | null | undefined> ParsedSession if valid, null if invalid/expired, undefined if empty/missing
auth/session_cookie.ts view source
ParsedSession<TIdentity> Result of parsing a signed session cookie.
TIdentityidentityThe decoded identity.
TIdentityshould_refresh_signatureTrue if verified with a non-primary key (needs re-signing).
booleankey_indexIndex of the key that verified the signature.
numberauth/session_cookie.ts view source
<TIdentity>(signed_value: string | undefined, keyring: Keyring, options: SessionOptions<TIdentity>, now_seconds?: number | undefined): Promise<ProcessSessionResult<TIdentity>> Process a session cookie and determine what action to take.
signed_valuethe raw cookie value (may be undefined)
string | undefinedkeyringkey ring for verification and signing
optionssession configuration
SessionOptions<TIdentity>now_seconds?current time in seconds (for testing)
number | undefinedPromise<ProcessSessionResult<TIdentity>> result with validity and action to take
auth/session_cookie.ts view source
ProcessSessionResult<TIdentity> Result of processing a session cookie.
TIdentityvalidWhether the session is valid.
booleanactionAction the adapter should take.
'none' | 'clear' | 'refresh'new_signed_valueNew signed value when action is 'refresh'.
stringidentityThe decoded identity if the cookie was valid.
TIdentityauth/session_cookie.ts view source
number Cookie max age in seconds (30 days — aligned with AUTH_SESSION_LIFETIME_MS).
auth/session_cookie.ts view source
SessionCookieOptions Default cookie options for session cookies.
Uses strict security settings:
- secure: true - Works on localhost in Chrome/Firefox (treated as secure context)
- sameSite: 'strict' - Prevents CSRF
- httpOnly: true - Prevents XSS access to cookie
auth/session_cookie.ts view source
SessionCookieOptions Cookie options for session cookies.
pathstringhttpOnlybooleansecurebooleansameSite'strict' | 'lax' | 'none'maxAgenumberauth/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).
TIdentity// tx: 3-part format (admin:session_id)
const tx_config: SessionOptions<string> = {
cookie_name: 'tx_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;
},
};
// visiones: 1-part format (account_id)
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;
},
};cookie_namestringcontext_keyHono context variable name for the identity.
stringmax_agenumbercookie_optionsPartial<SessionCookieOptions>encode_identityEncode identity into the cookie payload (before the :expires_at suffix).
(identity: TIdentity) => stringdecode_identityDecode identity from cookie payload. Return null if invalid.
(payload: string) => TIdentity | null