@fuzdev/fuz_app 0.1.0

package/dist/auth/session_cookie.d.ts

@@ -0,0 +1,158 @@
+/**
+ * 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).
+ *
+ * @module
+ */
+import type { Keyring } from './keyring.js';
+/** Cookie max age in seconds (30 days — aligned with AUTH_SESSION_LIFETIME_MS). */
+export declare const SESSION_AGE_MAX: number;
+/**
+ * Cookie options for session cookies.
+ */
+export interface SessionCookieOptions {
+    path: string;
+    httpOnly: boolean;
+    secure: boolean;
+    sameSite: 'strict' | 'lax' | 'none';
+    maxAge: number;
+}
+/**
+ * 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
+ */
+export declare const SESSION_COOKIE_OPTIONS: SessionCookieOptions;
+/**
+ * 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).
+ *
+ * @example
+ * ```ts
+ * // 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;
+ *   },
+ * };
+ * ```
+ */
+export interface SessionOptions<TIdentity> {
+    cookie_name: string;
+    /** Hono context variable name for the identity. */
+    context_key: string;
+    max_age?: number;
+    cookie_options?: Partial<SessionCookieOptions>;
+    /** Encode identity into the cookie payload (before the `:expires_at` suffix). */
+    encode_identity: (identity: TIdentity) => string;
+    /** Decode identity from cookie payload. Return null if invalid. */
+    decode_identity: (payload: string) => TIdentity | null;
+}
+/**
+ * Result of parsing a signed session cookie.
+ */
+export interface ParsedSession<TIdentity> {
+    /** The decoded identity. */
+    identity: TIdentity;
+    /** True if verified with a non-primary key (needs re-signing). */
+    should_refresh_signature: boolean;
+    /** Index of the key that verified the signature. */
+    key_index: number;
+}
+/**
+ * Parse a signed session cookie value.
+ *
+ * The signed value format is `${encode(identity)}:${expires_at}`.
+ * Tries all keys in order to support key rotation.
+ *
+ * @param signed_value - the raw cookie value (signed)
+ * @param keyring - key ring for verification
+ * @param options - session configuration with decode logic
+ * @param now_seconds - current time in seconds (for testing)
+ * @returns `ParsedSession` if valid, null if invalid/expired, undefined if empty/missing
+ */
+export declare const parse_session: <TIdentity>(signed_value: string | undefined, keyring: Keyring, options: SessionOptions<TIdentity>, now_seconds?: number) => Promise<ParsedSession<TIdentity> | null | undefined>;
+/**
+ * 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.
+ *
+ * @param keyring - key ring for signing
+ * @param identity - the identity to encode
+ * @param options - session configuration with encode logic
+ * @param now_seconds - current time in seconds (for testing)
+ * @returns signed cookie value string
+ */
+export declare const create_session_cookie_value: <TIdentity>(keyring: Keyring, identity: TIdentity, options: SessionOptions<TIdentity>, now_seconds?: number) => Promise<string>;
+/**
+ * Result of processing a session cookie.
+ */
+export interface ProcessSessionResult<TIdentity> {
+    /** Whether the session is valid. */
+    valid: boolean;
+    /** Action the adapter should take. */
+    action: 'none' | 'clear' | 'refresh';
+    /** New signed value when action is 'refresh'. */
+    new_signed_value?: string;
+    /** The decoded identity if the cookie was valid. */
+    identity?: TIdentity;
+}
+/**
+ * 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.
+ *
+ * @param cookie_name - cookie name (e.g. `'tx_session'`, `'visiones_session'`)
+ * @returns a `SessionOptions<string>` ready for use with session middleware
+ */
+export declare const create_session_config: (cookie_name: string) => SessionOptions<string>;
+/** Canonical session config for fuz_app auth. */
+export declare const fuz_session_config: SessionOptions<string>;
+/**
+ * Process a session cookie and determine what action to take.
+ *
+ * @param signed_value - the raw cookie value (may be undefined)
+ * @param keyring - key ring for verification and signing
+ * @param options - session configuration
+ * @param now_seconds - current time in seconds (for testing)
+ * @returns result with validity and action to take
+ */
+export declare const process_session_cookie: <TIdentity>(signed_value: string | undefined, keyring: Keyring, options: SessionOptions<TIdentity>, now_seconds?: number) => Promise<ProcessSessionResult<TIdentity>>;
+//# sourceMappingURL=session_cookie.d.ts.map

package/dist/auth/session_cookie.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session_cookie.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/session_cookie.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,cAAc,CAAC;AAE1C,mFAAmF;AACnF,eAAO,MAAM,eAAe,QAAoB,CAAC;AAKjD;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,EAAE,OAAO,CAAC;IAChB,QAAQ,EAAE,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAC;IACpC,MAAM,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB,EAAE,oBAMpC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,MAAM,WAAW,cAAc,CAAC,SAAS;IACxC,WAAW,EAAE,MAAM,CAAC;IACpB,mDAAmD;IACnD,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,OAAO,CAAC,oBAAoB,CAAC,CAAC;IAC/C,iFAAiF;IACjF,eAAe,EAAE,CAAC,QAAQ,EAAE,SAAS,KAAK,MAAM,CAAC;IACjD,mEAAmE;IACnE,eAAe,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,SAAS,GAAG,IAAI,CAAC;CACvD;AAED;;GAEG;AACH,MAAM,WAAW,aAAa,CAAC,SAAS;IACvC,4BAA4B;IAC5B,QAAQ,EAAE,SAAS,CAAC;IACpB,kEAAkE;IAClE,wBAAwB,EAAE,OAAO,CAAC;IAClC,oDAAoD;IACpD,SAAS,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,aAAa,GAAU,SAAS,EAC5C,cAAc,MAAM,GAAG,SAAS,EAChC,SAAS,OAAO,EAChB,SAAS,cAAc,CAAC,SAAS,CAAC,EAClC,cAAc,MAAM,KAClB,OAAO,CAAC,aAAa,CAAC,SAAS,CAAC,GAAG,IAAI,GAAG,SAAS,CA4BrD,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,2BAA2B,GAAU,SAAS,EAC1D,SAAS,OAAO,EAChB,UAAU,SAAS,EACnB,SAAS,cAAc,CAAC,SAAS,CAAC,EAClC,cAAc,MAAM,KAClB,OAAO,CAAC,MAAM,CAMhB,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,oBAAoB,CAAC,SAAS;IAC9C,oCAAoC;IACpC,KAAK,EAAE,OAAO,CAAC;IACf,sCAAsC;IACtC,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC;IACrC,iDAAiD;IACjD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,oDAAoD;IACpD,QAAQ,CAAC,EAAE,SAAS,CAAC;CACrB;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,qBAAqB,GAAI,aAAa,MAAM,KAAG,cAAc,CAAC,MAAM,CAK/E,CAAC;AAEH,iDAAiD;AACjD,eAAO,MAAM,kBAAkB,EAAE,cAAc,CAAC,MAAM,CAAwC,CAAC;AAE/F;;;;;;;;GAQG;AAEH,eAAO,MAAM,sBAAsB,GAAU,SAAS,EACrD,cAAc,MAAM,GAAG,SAAS,EAChC,SAAS,OAAO,EAChB,SAAS,cAAc,CAAC,SAAS,CAAC,EAClC,cAAc,MAAM,KAClB,OAAO,CAAC,oBAAoB,CAAC,SAAS,CAAC,CA4BzC,CAAC"}

package/dist/auth/session_cookie.js

@@ -0,0 +1,135 @@
+/**
+ * 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).
+ *
+ * @module
+ */
+/** Cookie max age in seconds (30 days — aligned with AUTH_SESSION_LIFETIME_MS). */
+export const SESSION_AGE_MAX = 60 * 60 * 24 * 30;
+/** Separator between identity payload and expires_at in signed value. */
+const VALUE_SEPARATOR = ':';
+/**
+ * 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
+ */
+export const SESSION_COOKIE_OPTIONS = {
+    path: '/',
+    httpOnly: true,
+    secure: true,
+    sameSite: 'strict',
+    maxAge: SESSION_AGE_MAX,
+};
+/**
+ * Parse a signed session cookie value.
+ *
+ * The signed value format is `${encode(identity)}:${expires_at}`.
+ * Tries all keys in order to support key rotation.
+ *
+ * @param signed_value - the raw cookie value (signed)
+ * @param keyring - key ring for verification
+ * @param options - session configuration with decode logic
+ * @param now_seconds - current time in seconds (for testing)
+ * @returns `ParsedSession` if valid, null if invalid/expired, undefined if empty/missing
+ */
+export const parse_session = async (signed_value, keyring, options, now_seconds) => {
+    if (!signed_value)
+        return undefined;
+    const result = await keyring.verify(signed_value);
+    if (!result)
+        return null;
+    // Split on the last VALUE_SEPARATOR to get identity_payload and expires_at
+    const last_sep = result.value.lastIndexOf(VALUE_SEPARATOR);
+    if (last_sep === -1)
+        return null;
+    const identity_payload = result.value.slice(0, last_sep);
+    const expires_at_str = result.value.slice(last_sep + 1);
+    const identity = options.decode_identity(identity_payload);
+    if (identity === null)
+        return null;
+    const expires_at = parseInt(expires_at_str, 10);
+    if (!Number.isFinite(expires_at))
+        return null;
+    // Check expiration
+    const now = now_seconds ?? Math.floor(Date.now() / 1000);
+    if (expires_at <= now)
+        return null;
+    return {
+        identity,
+        should_refresh_signature: result.key_index > 0,
+        key_index: result.key_index,
+    };
+};
+/**
+ * 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.
+ *
+ * @param keyring - key ring for signing
+ * @param identity - the identity to encode
+ * @param options - session configuration with encode logic
+ * @param now_seconds - current time in seconds (for testing)
+ * @returns signed cookie value string
+ */
+export const create_session_cookie_value = async (keyring, identity, options, now_seconds) => {
+    const max_age = options.max_age ?? SESSION_AGE_MAX;
+    const now = now_seconds ?? Math.floor(Date.now() / 1000);
+    const expires_at = now + max_age;
+    const value = `${options.encode_identity(identity)}${VALUE_SEPARATOR}${expires_at}`;
+    return keyring.sign(value);
+};
+/**
+ * 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.
+ *
+ * @param cookie_name - cookie name (e.g. `'tx_session'`, `'visiones_session'`)
+ * @returns a `SessionOptions<string>` ready for use with session middleware
+ */
+export const create_session_config = (cookie_name) => ({
+    cookie_name,
+    context_key: 'auth_session_id',
+    encode_identity: (session_id) => session_id,
+    decode_identity: (payload) => payload || null,
+});
+/** Canonical session config for fuz_app auth. */
+export const fuz_session_config = create_session_config('fuz_session');
+/**
+ * Process a session cookie and determine what action to take.
+ *
+ * @param signed_value - the raw cookie value (may be undefined)
+ * @param keyring - key ring for verification and signing
+ * @param options - session configuration
+ * @param now_seconds - current time in seconds (for testing)
+ * @returns result with validity and action to take
+ */
+export const process_session_cookie = async (signed_value, keyring, options, now_seconds) => {
+    const now = now_seconds ?? Math.floor(Date.now() / 1000);
+    const parsed = await parse_session(signed_value, keyring, options, now);
+    if (parsed === undefined) {
+        // No cookie present
+        return { valid: false, action: 'none' };
+    }
+    if (parsed === null) {
+        // Invalid cookie - should be cleared
+        return { valid: false, action: 'clear' };
+    }
+    // Valid session
+    if (parsed.should_refresh_signature) {
+        // Re-sign with current key (extends expiration)
+        const new_signed_value = await create_session_cookie_value(keyring, parsed.identity, options, now);
+        return { valid: true, action: 'refresh', new_signed_value, identity: parsed.identity };
+    }
+    return { valid: true, action: 'none', identity: parsed.identity };
+};

package/dist/auth/session_lifecycle.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Session lifecycle — creation and cookie management shared across login and bootstrap flows.
+ *
+ * @module
+ */
+import type { Context } from 'hono';
+import type { Keyring } from './keyring.js';
+import { type SessionOptions } from './session_cookie.js';
+import type { QueryDeps } from '../db/query_deps.js';
+/**
+ * Options for `create_session_and_set_cookie`.
+ */
+export interface CreateSessionAndSetCookieOptions {
+    /** Keyring for cookie signing. */
+    keyring: Keyring;
+    /** Query deps (needs db for session creation). */
+    deps: QueryDeps;
+    /** Hono context for setting the cookie. */
+    c: Context;
+    /** The account to create a session for. */
+    account_id: string;
+    /** Session cookie configuration. */
+    session_options: SessionOptions<string>;
+    /** Per-account session cap (`null` to skip enforcement). */
+    max_sessions?: number | null;
+}
+/**
+ * Create an auth session and set the session cookie on the response.
+ *
+ * Shared by login and bootstrap — generates a token, hashes it, persists
+ * the session row, optionally enforces a per-account session limit, and
+ * sets the signed cookie.
+ */
+export declare const create_session_and_set_cookie: (options: CreateSessionAndSetCookieOptions) => Promise<void>;
+//# sourceMappingURL=session_lifecycle.d.ts.map

package/dist/auth/session_lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session_lifecycle.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/session_lifecycle.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,MAAM,CAAC;AAElC,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,cAAc,CAAC;AAC1C,OAAO,EAA8B,KAAK,cAAc,EAAC,MAAM,qBAAqB,CAAC;AASrF,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,qBAAqB,CAAC;AAEnD;;GAEG;AACH,MAAM,WAAW,gCAAgC;IAChD,kCAAkC;IAClC,OAAO,EAAE,OAAO,CAAC;IACjB,kDAAkD;IAClD,IAAI,EAAE,SAAS,CAAC;IAChB,2CAA2C;IAC3C,CAAC,EAAE,OAAO,CAAC;IACX,2CAA2C;IAC3C,UAAU,EAAE,MAAM,CAAC;IACnB,oCAAoC;IACpC,eAAe,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC;IACxC,4DAA4D;IAC5D,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED;;;;;;GAMG;AACH,eAAO,MAAM,6BAA6B,GACzC,SAAS,gCAAgC,KACvC,OAAO,CAAC,IAAI,CAad,CAAC"}

package/dist/auth/session_lifecycle.js

@@ -0,0 +1,27 @@
+/**
+ * Session lifecycle — creation and cookie management shared across login and bootstrap flows.
+ *
+ * @module
+ */
+import { create_session_cookie_value } from './session_cookie.js';
+import { set_session_cookie } from './session_middleware.js';
+import { generate_session_token, hash_session_token, AUTH_SESSION_LIFETIME_MS, query_create_session, query_session_enforce_limit, } from './session_queries.js';
+/**
+ * Create an auth session and set the session cookie on the response.
+ *
+ * Shared by login and bootstrap — generates a token, hashes it, persists
+ * the session row, optionally enforces a per-account session limit, and
+ * sets the signed cookie.
+ */
+export const create_session_and_set_cookie = async (options) => {
+    const { keyring, deps, c, account_id, session_options, max_sessions } = options;
+    const session_token = generate_session_token();
+    const token_hash = hash_session_token(session_token);
+    const expires_at = new Date(Date.now() + AUTH_SESSION_LIFETIME_MS);
+    await query_create_session(deps, token_hash, account_id, expires_at);
+    if (max_sessions != null) {
+        await query_session_enforce_limit(deps, account_id, max_sessions);
+    }
+    const cookie_value = await create_session_cookie_value(keyring, session_token, session_options);
+    set_session_cookie(c, cookie_value, session_options);
+};

package/dist/auth/session_middleware.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Hono session middleware using generic session management.
+ *
+ * Thin wrapper that gets/sets cookies and delegates to session processing.
+ *
+ * @module
+ */
+import type { Context, MiddlewareHandler } from 'hono';
+import type { Keyring } from './keyring.js';
+import { type SessionOptions } from './session_cookie.js';
+/**
+ * Read the session cookie value from a request.
+ */
+export declare const get_session_cookie: <T>(c: Context, options: SessionOptions<T>) => string | undefined;
+/**
+ * Set the session cookie on a response.
+ */
+export declare const set_session_cookie: <T>(c: Context, value: string, options: SessionOptions<T>) => void;
+/**
+ * Clear the session cookie on a response.
+ */
+export declare const clear_session_cookie: <T>(c: Context, options: SessionOptions<T>) => void;
+/**
+ * Create session middleware that parses cookies and sets identity on context.
+ *
+ * Always sets the identity on context (null when invalid/missing) for type-safe reads.
+ * Uses `options.context_key` as the Hono context variable name.
+ *
+ * @param keyring - key ring for cookie verification
+ * @param options - session configuration
+ */
+export declare const create_session_middleware: <TIdentity>(keyring: Keyring, options: SessionOptions<TIdentity>) => MiddlewareHandler;
+//# sourceMappingURL=session_middleware.d.ts.map

package/dist/auth/session_middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session_middleware.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/session_middleware.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAC,OAAO,EAAE,iBAAiB,EAAC,MAAM,MAAM,CAAC;AAGrD,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,cAAc,CAAC;AAC1C,OAAO,EACN,KAAK,cAAc,EAInB,MAAM,qBAAqB,CAAC;AAE7B;;GAEG;AACH,eAAO,MAAM,kBAAkB,GAAI,CAAC,EACnC,GAAG,OAAO,EACV,SAAS,cAAc,CAAC,CAAC,CAAC,KACxB,MAAM,GAAG,SAEX,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,kBAAkB,GAAI,CAAC,EACnC,GAAG,OAAO,EACV,OAAO,MAAM,EACb,SAAS,cAAc,CAAC,CAAC,CAAC,KACxB,IASF,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,oBAAoB,GAAI,CAAC,EAAE,GAAG,OAAO,EAAE,SAAS,cAAc,CAAC,CAAC,CAAC,KAAG,IAMhF,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,yBAAyB,GAAI,SAAS,EAClD,SAAS,OAAO,EAChB,SAAS,cAAc,CAAC,SAAS,CAAC,KAChC,iBAgBF,CAAC"}

package/dist/auth/session_middleware.js

@@ -0,0 +1,62 @@
+/**
+ * Hono session middleware using generic session management.
+ *
+ * Thin wrapper that gets/sets cookies and delegates to session processing.
+ *
+ * @module
+ */
+import { getCookie, setCookie, deleteCookie } from 'hono/cookie';
+import { SESSION_COOKIE_OPTIONS, process_session_cookie, } from './session_cookie.js';
+/**
+ * Read the session cookie value from a request.
+ */
+export const get_session_cookie = (c, options) => {
+    return getCookie(c, options.cookie_name);
+};
+/**
+ * Set the session cookie on a response.
+ */
+export const set_session_cookie = (c, value, options) => {
+    const cookie_options = {
+        ...SESSION_COOKIE_OPTIONS,
+        ...options.cookie_options,
+    };
+    if (options.max_age !== undefined) {
+        cookie_options.maxAge = options.max_age;
+    }
+    setCookie(c, options.cookie_name, value, cookie_options);
+};
+/**
+ * Clear the session cookie on a response.
+ */
+export const clear_session_cookie = (c, options) => {
+    const cookie_options = {
+        ...SESSION_COOKIE_OPTIONS,
+        ...options.cookie_options,
+    };
+    deleteCookie(c, options.cookie_name, cookie_options);
+};
+/**
+ * Create session middleware that parses cookies and sets identity on context.
+ *
+ * Always sets the identity on context (null when invalid/missing) for type-safe reads.
+ * Uses `options.context_key` as the Hono context variable name.
+ *
+ * @param keyring - key ring for cookie verification
+ * @param options - session configuration
+ */
+export const create_session_middleware = (keyring, options) => {
+    return async (c, next) => {
+        const signed_value = get_session_cookie(c, options);
+        const result = await process_session_cookie(signed_value, keyring, options);
+        // Always set identity (null when invalid/missing) for type-safe reads
+        c.set(options.context_key, result.identity ?? null);
+        if (result.action === 'clear') {
+            clear_session_cookie(c, options);
+        }
+        else if (result.action === 'refresh' && result.new_signed_value) {
+            set_session_cookie(c, result.new_signed_value, options);
+        }
+        await next();
+    };
+};

package/dist/auth/session_queries.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Auth session database queries.
+ *
+ * Server-side sessions keyed by blake3 hash of the session token.
+ * The cookie contains the raw token; the database stores only the hash.
+ *
+ * @module
+ */
+import type { Logger } from '@fuzdev/fuz_util/log.js';
+import type { QueryDeps } from '../db/query_deps.js';
+import type { AuthSession } from './account_schema.js';
+/** Session lifetime in milliseconds (30 days). */
+export declare const AUTH_SESSION_LIFETIME_MS: number;
+/** Extend session when it has less than this remaining (1 day in ms). */
+export declare const AUTH_SESSION_EXTEND_THRESHOLD_MS: number;
+/**
+ * Hash a session token to its storage key using blake3.
+ *
+ * @param token - the raw session token
+ * @returns hex-encoded blake3 hash
+ */
+export declare const hash_session_token: (token: string) => string;
+/**
+ * Generate a cryptographically random session token.
+ *
+ * @returns a 32-byte base64url-encoded token
+ */
+export declare const generate_session_token: () => string;
+/**
+ * Create a new auth session.
+ *
+ * @param deps - query dependencies
+ * @param token_hash - blake3 hash of the session token (use `hash_session_token`)
+ * @param account_id - the account this session belongs to
+ * @param expires_at - when the session expires
+ */
+export declare const query_create_session: (deps: QueryDeps, token_hash: string, account_id: string, expires_at: Date) => Promise<void>;
+/**
+ * Get a session if it exists, is not expired, and has not been revoked.
+ *
+ * @param deps - query dependencies
+ * @param token_hash - blake3 hash of the session token
+ */
+export declare const query_session_get_valid: (deps: QueryDeps, token_hash: string) => Promise<AuthSession | undefined>;
+/**
+ * Update `last_seen_at` and optionally extend expiry for a session.
+ *
+ * Extends if less than `AUTH_SESSION_EXTEND_THRESHOLD_MS` remaining.
+ *
+ * @param deps - query dependencies
+ * @param token_hash - blake3 hash of the session token
+ */
+export declare const query_session_touch: (deps: QueryDeps, token_hash: string) => Promise<void>;
+/**
+ * Revoke (delete) a session by its token hash.
+ *
+ * No account_id constraint — caller must ensure the hash comes from a
+ * trusted source (e.g. the authenticated session cookie). For user-facing
+ * revocation of a specific session by ID, prefer `query_session_revoke_for_account`
+ * which includes an IDOR guard.
+ */
+export declare const query_session_revoke_by_hash: (deps: QueryDeps, token_hash: string) => Promise<void>;
+/**
+ * Revoke a session only if it belongs to the specified account.
+ *
+ * Prevents cross-account session revocation.
+ *
+ * @param deps - query dependencies
+ * @param token_hash - blake3 hash of the session token
+ * @param account_id - the account that must own the session
+ * @returns `true` if a session was revoked, `false` if not found or wrong account
+ */
+export declare const query_session_revoke_for_account: (deps: QueryDeps, token_hash: string, account_id: string) => Promise<boolean>;
+/**
+ * Revoke all sessions for an account.
+ *
+ * @returns the number of sessions revoked
+ */
+export declare const query_session_revoke_all_for_account: (deps: QueryDeps, account_id: string) => Promise<number>;
+/**
+ * List sessions for an account, newest first.
+ */
+export declare const query_session_list_for_account: (deps: QueryDeps, account_id: string, limit?: number) => Promise<Array<AuthSession>>;
+/**
+ * Enforce a per-account session limit by evicting the oldest sessions.
+ *
+ * Keeps the newest `max_sessions` sessions and deletes the rest.
+ *
+ * Race safety: this function must run inside a transaction alongside the
+ * INSERT that created the new session. All callers satisfy this requirement:
+ * - `POST /login` and `POST /tokens/create` use the default `transaction: true`
+ *   (framework-managed transaction wrapping in `apply_route_specs`)
+ * - `POST /bootstrap` and `POST /signup` manage their own transactions
+ *   and pass the transaction-scoped `deps` to `create_session_and_set_cookie`
+ *
+ * The transaction ensures the INSERT + enforce_limit pair is atomic —
+ * concurrent session creation cannot interleave between the two statements.
+ *
+ * @param deps - query dependencies (must be transaction-scoped)
+ * @param account_id - the account to enforce the limit for
+ * @param max_sessions - maximum number of sessions to keep
+ * @returns the number of sessions evicted
+ */
+export declare const query_session_enforce_limit: (deps: QueryDeps, account_id: string, max_sessions: number) => Promise<number>;
+/**
+ * List all active sessions across all accounts with usernames.
+ *
+ * @param deps - query dependencies
+ * @param limit - maximum entries to return
+ * @returns active sessions joined with account usernames, newest activity first
+ */
+export declare const query_session_list_all_active: (deps: QueryDeps, limit?: number) => Promise<Array<AuthSession & {
+    username: string;
+}>>;
+/**
+ * Delete expired sessions.
+ *
+ * @returns the number of sessions cleaned up
+ */
+export declare const query_session_cleanup_expired: (deps: QueryDeps) => Promise<number>;
+/**
+ * Touch a session without blocking the caller.
+ *
+ * Errors are logged to console — session touching never breaks request flows.
+ * Pass `pending_effects` (from `c.var.pending_effects`) to register
+ * the promise for test flushing.
+ *
+ * @param deps - query dependencies
+ * @param token_hash - blake3 hash of the session token
+ * @param pending_effects - optional array to register the effect for later awaiting
+ * @param log - the logger instance
+ * @returns the settled promise (callers may ignore it — fire-and-forget semantics preserved)
+ */
+export declare const session_touch_fire_and_forget: (deps: QueryDeps, token_hash: string, pending_effects: Array<Promise<void>> | undefined, log: Logger) => Promise<void>;
+//# sourceMappingURL=session_queries.d.ts.map

package/dist/auth/session_queries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session_queries.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/session_queries.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAGpD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,qBAAqB,CAAC;AACnD,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,qBAAqB,CAAC;AAErD,kDAAkD;AAClD,eAAO,MAAM,wBAAwB,QAA2B,CAAC;AAEjE,yEAAyE;AACzE,eAAO,MAAM,gCAAgC,QAAsB,CAAC;AAEpE;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,GAAI,OAAO,MAAM,KAAG,MAElD,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,QAAO,MAEzC,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,GAChC,MAAM,SAAS,EACf,YAAY,MAAM,EAClB,YAAY,MAAM,EAClB,YAAY,IAAI,KACd,OAAO,CAAC,IAAI,CAMd,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,GACnC,MAAM,SAAS,EACf,YAAY,MAAM,KAChB,OAAO,CAAC,WAAW,GAAG,SAAS,CAKjC,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,GAAU,MAAM,SAAS,EAAE,YAAY,MAAM,KAAG,OAAO,CAAC,IAAI,CAY3F,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,4BAA4B,GACxC,MAAM,SAAS,EACf,YAAY,MAAM,KAChB,OAAO,CAAC,IAAI,CAEd,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,gCAAgC,GAC5C,MAAM,SAAS,EACf,YAAY,MAAM,EAClB,YAAY,MAAM,KAChB,OAAO,CAAC,OAAO,CAMjB,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,oCAAoC,GAChD,MAAM,SAAS,EACf,YAAY,MAAM,KAChB,OAAO,CAAC,MAAM,CAMhB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,8BAA8B,GAC1C,MAAM,SAAS,EACf,YAAY,MAAM,EAClB,cAAU,KACR,OAAO,CAAC,KAAK,CAAC,WAAW,CAAC,CAK5B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,2BAA2B,GACvC,MAAM,SAAS,EACf,YAAY,MAAM,EAClB,cAAc,MAAM,KAClB,OAAO,CAAC,MAAM,CAYhB,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,6BAA6B,GACzC,MAAM,SAAS,EACf,cAAW,KACT,OAAO,CAAC,KAAK,CAAC,WAAW,GAAG;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAC,CAAC,CASjD,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,6BAA6B,GAAU,MAAM,SAAS,KAAG,OAAO,CAAC,MAAM,CAKnF,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,6BAA6B,GACzC,MAAM,SAAS,EACf,YAAY,MAAM,EAClB,iBAAiB,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,SAAS,EACjD,KAAK,MAAM,KACT,OAAO,CAAC,IAAI,CAMd,CAAC"}