@fuzdev/fuz_app 0.55.0 → 0.57.0

package/dist/auth/self_service_role_actions.js

@@ -2,19 +2,24 @@
  * Unified self-service role toggle RPC action.
  *
  * One static `request_response` action — `self_service_role_set` — that
- * takes `{role, enabled}` and toggles a global permit on the caller for an
+ * takes `{role, enabled}` and toggles a global role_grant on the caller for an
  * allowlisted role. Idempotent in both directions: re-enabling an
  * already-held role returns `changed: false`; disabling a role the caller
  * doesn't hold returns `changed: false`.
  *
- * The factory takes an `eligible_roles` allowlist (validated against the
- * supplied `roles.role_options` at factory time so typos surface at startup
- * instead of at first call). Roles outside the allowlist are rejected
- * with `forbidden` + reason `role_not_self_service_eligible`.
+ * Eligibility is derived by default from `RoleSpec.grant_paths` —
+ * every role whose `grant_paths` includes `'self_service'`
+ * (`GRANT_PATH_SELF_SERVICE`) is eligible. The factory accepts an
+ * optional `eligible_roles` override (validated against the supplied
+ * `roles.role_specs` at factory time so typos surface at startup
+ * instead of at first call) for deployments that want to lock the
+ * surface down further than the role spec declares. Roles outside
+ * the eligible set are rejected with `forbidden` + reason
+ * `role_not_self_service_eligible`.
  *
  * Audit metadata carries `self_service: true` so admin reviewers can
- * distinguish self-toggled permits from admin grants/offers. The
- * `permit_grant` / `permit_revoke` metadata schemas declare
+ * distinguish self-toggled role_grants from admin grants/offers. The
+ * `role_grant_create` / `role_grant_revoke` metadata schemas declare
  * `self_service: z.boolean().optional()` explicitly, so the field is
  * part of the documented schema surface and is round-trip-validated by
  * `query_audit_log`.
@@ -22,7 +27,7 @@
  * Static method name — `role` lives in the input, not the method name —
  * so the spec is codegen-compatible (`satisfies RequestResponseActionSpec`)
  * and the surface stays constant as consumers add eligible roles. Mirrors
- * the existing `permit_offer_create({role})` precedent rather than
+ * the existing `role_grant_offer_create({role})` precedent rather than
  * generating per-role methods.
  *
  * Specs and schemas live in `auth/self_service_role_action_specs.ts` so
@@ -31,28 +36,33 @@
  *
  * @module
  */
-import { rpc_actor_action } from '../actions/action_rpc.js';
+import { rpc_action } from '../actions/action_rpc.js';
 import { jsonrpc_errors } from '../http/jsonrpc_errors.js';
-import { query_grant_permit, query_revoke_permit } from './permit_queries.js';
-import { audit_log_fire_and_forget } from './audit_log_queries.js';
-import { is_permit_active } from './account_schema.js';
+import { BUILTIN_ROLE_SPECS_BY_NAME, list_roles_with_grant_path, } from './role_schema.js';
+import { GRANT_PATH_SELF_SERVICE } from './grant_path_schema.js';
+import { query_create_role_grant, query_revoke_role_grant } from './role_grant_queries.js';
+import { is_role_grant_active } from './account_schema.js';
 import { has_scoped_role } from './request_context.js';
 import { ERROR_ROLE_NOT_SELF_SERVICE_ELIGIBLE, self_service_role_set_action_spec, } from './self_service_role_action_specs.js';
 /**
  * Build the unified self-service role toggle RPC action.
  *
- * @param deps - `SelfServiceRoleActionDeps` slice of `AppDeps` (`log`, `on_audit_event`, optional `audit_log_config`)
- * @param options - eligible-role allowlist plus optional role schema for typo-checking
+ * @param deps - `RouteFactoryDeps` (`log`, `audit`, …); `audit.emit` writes
+ *   audit rows via the captured pool. The bound emitter encapsulates
+ *   `on_audit_event` fan-out and the optional `AuditLogConfig`.
+ * @param options - optional eligible-role override plus optional role schema for default-eligibility derivation
  * @returns the `RpcAction` array to spread into a `create_rpc_endpoint` call
- * @throws Error at factory time if any `eligible_roles` entry is missing from `options.roles.role_options`
+ * @throws Error at factory time if any `eligible_roles` entry is missing from `options.roles.role_specs`
  */
-export const create_self_service_role_actions = (deps, options) => {
-    const eligible = new Set(options.eligible_roles);
-    if (options.roles) {
-        const role_options = options.roles.role_options;
+export const create_self_service_role_actions = (deps, options = {}) => {
+    const role_specs = options.roles?.role_specs ?? BUILTIN_ROLE_SPECS_BY_NAME;
+    const eligible = options.eligible_roles
+        ? new Set(options.eligible_roles)
+        : new Set(list_roles_with_grant_path(role_specs, GRANT_PATH_SELF_SERVICE));
+    if (options.eligible_roles && options.roles) {
         for (const r of eligible) {
-            if (!role_options.has(r)) {
-                throw new Error(`create_self_service_role_actions: eligible_roles entry "${r}" is not registered in roles.role_options — typo or missing call to create_role_schema`);
+            if (!role_specs.has(r)) {
+                throw new Error(`create_self_service_role_actions: eligible_roles entry "${r}" is not registered in roles.role_specs — typo or missing call to create_role_schema`);
             }
         }
     }
@@ -67,69 +77,69 @@ export const create_self_service_role_actions = (deps, options) => {
         const auth = ctx.auth;
         reject_if_ineligible(input.role);
         if (input.enabled) {
-            // Pre-check for idempotent re-grant. `query_grant_permit` is itself
-            // idempotent (returns the existing permit instead of inserting), but
+            // Pre-check for idempotent re-grant. `query_create_role_grant` is itself
+            // idempotent (returns the existing role_grant instead of inserting), but
             // it doesn't signal "already existed" vs "newly inserted" — so we
-            // peek first. Reads from the in-memory `auth.permits` snapshot
+            // peek first. Reads from the in-memory `auth.role_grants` snapshot
             // (no DB roundtrip). The TOCTOU window is benign for self-service:
-            // two concurrent grants both observe "no permit", both call
-            // `query_grant_permit`, and one collapses onto the other inside the
+            // two concurrent grants both observe "no role_grant", both call
+            // `query_create_role_grant`, and one collapses onto the other inside the
             // query's `ON CONFLICT DO NOTHING`. Worst case both responses report
-            // `changed: true`; the DB still ends up with exactly one permit.
+            // `changed: true`; the DB still ends up with exactly one role_grant.
             if (has_scoped_role(auth, input.role, null)) {
                 return { ok: true, enabled: true, changed: false };
             }
-            const permit = await query_grant_permit(ctx, {
+            const role_grant = await query_create_role_grant(ctx, {
                 actor_id: auth.actor.id,
                 role: input.role,
                 scope_id: null,
                 expires_at: null,
                 granted_by: auth.actor.id,
             });
-            // `permit_grant` is the canonical actor-bound-subject event —
+            // `role_grant_create` is the canonical actor-bound-subject event —
             // populate both target columns even on self-service so the
-            // "always populated for permit_grant" rule holds uniformly
+            // "always populated for role_grant_create" rule holds uniformly
             // regardless of who initiated the grant. On self-service the
             // grantor and grantee are the same identity; admin direct-grant
             // (separate code path) populates the same columns with the
             // grantee actor.
-            void audit_log_fire_and_forget(ctx, {
-                event_type: 'permit_grant',
+            deps.audit.emit(ctx, {
+                event_type: 'role_grant_create',
                 actor_id: auth.actor.id,
                 account_id: auth.account.id,
                 target_account_id: auth.account.id,
                 target_actor_id: auth.actor.id,
                 ip: ctx.client_ip,
                 metadata: {
-                    role: permit.role,
-                    permit_id: permit.id,
-                    scope_id: permit.scope_id,
+                    role: role_grant.role,
+                    role_grant_id: role_grant.id,
+                    scope_id: role_grant.scope_id,
                     self_service: true,
                 },
-            }, deps);
+            });
             return { ok: true, enabled: true, changed: true };
         }
-        // Find an active global permit for this (actor, role) in the in-memory
-        // `auth.permits` snapshot. No DB roundtrip — same correctness-equivalent
+        // Find an active global role_grant for this (actor, role) in the in-memory
+        // `auth.role_grants` snapshot. No DB roundtrip — same correctness-equivalent
         // pattern as `has_scoped_role` above (race window is between predicate
-        // and `query_revoke_permit`'s actual UPDATE, not between predicate and
+        // and `query_revoke_role_grant`'s actual UPDATE, not between predicate and
         // middleware load).
         const now = new Date();
-        const target = auth.permits.find((p) => p.role === input.role && p.scope_id === null && is_permit_active(p, now));
+        const target = auth.role_grants.find((p) => p.role === input.role && p.scope_id === null && is_role_grant_active(p, now));
         if (!target) {
             return { ok: true, enabled: false, changed: false };
         }
-        const result = await query_revoke_permit(ctx, target.id, auth.actor.id, auth.actor.id);
+        const result = await query_revoke_role_grant(ctx, target.id, auth.actor.id, auth.actor.id);
         if (!result) {
             // Raced with another revoker — treat as already revoked.
             return { ok: true, enabled: false, changed: false };
         }
-        // Same actor-bound rule as the grant branch — `permit_revoke`
+        // Same actor-bound rule as the grant branch — `role_grant_revoke`
         // always populates both target columns even on self-service so
         // forensic queries that filter on `target_actor_id IS NOT NULL`
-        // don't silently miss self-toggled permits.
-        void audit_log_fire_and_forget(ctx, {
-            event_type: 'permit_revoke',
+        // don't silently miss self-toggled role_grants.
+        deps.audit.emit(ctx, {
+            event_type: 'role_grant_revoke',
             actor_id: auth.actor.id,
             account_id: auth.account.id,
             target_account_id: auth.account.id,
@@ -137,12 +147,12 @@ export const create_self_service_role_actions = (deps, options) => {
             ip: ctx.client_ip,
             metadata: {
                 role: result.role,
-                permit_id: result.id,
+                role_grant_id: result.id,
                 scope_id: result.scope_id,
                 self_service: true,
             },
-        }, deps);
+        });
         return { ok: true, enabled: false, changed: true };
     };
-    return [rpc_actor_action(self_service_role_set_action_spec, handler)];
+    return [rpc_action(self_service_role_set_action_spec, handler)];
 };

package/dist/auth/session_cookie.d.ts

@@ -12,6 +12,14 @@
 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;
+/**
+ * Threshold (seconds) at which `process_session_cookie` re-signs a still-valid
+ * cookie to extend its embedded expiration. Mirrors the DB-side
+ * `AUTH_SESSION_EXTEND_THRESHOLD_MS` so a continuously-active user's cookie
+ * stays in sync with their server-side session lifetime. Set
+ * `SessionOptions.refresh_threshold_seconds = 0` to disable.
+ */
+export declare const SESSION_REFRESH_THRESHOLD_S: number;
 /**
  * Cookie options for session cookies.
  */
@@ -47,9 +55,9 @@ export declare const SESSION_COOKIE_OPTIONS: SessionCookieOptions;
  *
  * @example
  * ```ts
- * // tx: 3-part format (admin:session_id)
- * const tx_config: SessionOptions<string> = {
- *   cookie_name: 'tx_session',
+ * // zap: 3-part format (admin:session_id)
+ * const zap_config: SessionOptions<string> = {
+ *   cookie_name: 'zap_session',
  *   context_key: 'auth_session_id',
  *   encode_identity: (session_id) => `admin:${session_id}`,
  *   decode_identity: (payload) => {
@@ -75,8 +83,23 @@ export interface SessionOptions<TIdentity> {
     cookie_name: string;
     /** Hono context variable name for the identity. */
     context_key: string;
+    /**
+     * 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.
+     */
     max_age?: number;
-    cookie_options?: Partial<SessionCookieOptions>;
+    /**
+     * 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.
+     */
+    refresh_threshold_seconds?: number;
+    cookie_options?: Partial<Omit<SessionCookieOptions, 'maxAge'>>;
     /** 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. */
@@ -90,6 +113,14 @@ export interface ParsedSession<TIdentity> {
     identity: TIdentity;
     /** True if verified with a non-primary key (needs re-signing). */
     should_refresh_signature: boolean;
+    /**
+     * True if the embedded `expires_at` is within
+     * `options.refresh_threshold_seconds` of `now`. Signals that the cookie is
+     * valid but should be re-signed to extend its lifetime — mirrors
+     * `query_session_touch`'s DB-side extension so the cookie and server
+     * session don't drift. Always false when the threshold is `0`.
+     */
+    should_refresh_expiration: boolean;
     /** Index of the key that verified the signature. */
     key_index: number;
 }
@@ -97,7 +128,9 @@ export interface ParsedSession<TIdentity> {
  * Parse a signed session cookie value.
  *
  * The signed value format is `${encode(identity)}:${expires_at}`.
- * Tries all keys in order to support key rotation.
+ * Tries all keys in order to support key rotation. The result's
+ * `should_refresh_expiration` flag fires when the cookie is within
+ * `options.refresh_threshold_seconds` of `expires_at`.
  *
  * @param signed_value - the raw cookie value (signed)
  * @param keyring - key ring for verification
@@ -139,7 +172,7 @@ export interface ProcessSessionResult<TIdentity> {
  * 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'`)
+ * @param cookie_name - cookie name (e.g. `'zap_session'`, `'visiones_session'`)
  * @returns a `SessionOptions<string>` ready for use with session middleware
  */
 export declare const create_session_config: (cookie_name: string) => SessionOptions<string>;
@@ -148,6 +181,10 @@ export declare const fuz_session_config: SessionOptions<string>;
 /**
  * Process a session cookie and determine what action to take.
  *
+ * `action: 'refresh'` fires on key rotation **or** impending expiration
+ * (within `options.refresh_threshold_seconds`); both produce a freshly-signed
+ * `new_signed_value`.
+ *
  * @param signed_value - the raw cookie value (may be undefined)
  * @param keyring - key ring for verification and signing
  * @param options - session configuration

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

@@ -1 +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"}
+{"version":3,"file":"session_cookie.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/session_cookie.ts"],"names":[],"mappings":"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"}

package/dist/auth/session_cookie.js

@@ -11,8 +11,18 @@
  */
 /** Cookie max age in seconds (30 days — aligned with AUTH_SESSION_LIFETIME_MS). */
 export const SESSION_AGE_MAX = 60 * 60 * 24 * 30;
+/**
+ * Threshold (seconds) at which `process_session_cookie` re-signs a still-valid
+ * cookie to extend its embedded expiration. Mirrors the DB-side
+ * `AUTH_SESSION_EXTEND_THRESHOLD_MS` so a continuously-active user's cookie
+ * stays in sync with their server-side session lifetime. Set
+ * `SessionOptions.refresh_threshold_seconds = 0` to disable.
+ */
+export const SESSION_REFRESH_THRESHOLD_S = 60 * 60 * 24;
 /** Separator between identity payload and expires_at in signed value. */
 const VALUE_SEPARATOR = ':';
+/** Strict integer matcher for the embedded `expires_at` field. */
+const EXPIRES_AT_INTEGER_RE = /^\d+$/;
 /**
  * Default cookie options for session cookies.
  *
@@ -32,7 +42,9 @@ export const SESSION_COOKIE_OPTIONS = {
  * Parse a signed session cookie value.
  *
  * The signed value format is `${encode(identity)}:${expires_at}`.
- * Tries all keys in order to support key rotation.
+ * Tries all keys in order to support key rotation. The result's
+ * `should_refresh_expiration` flag fires when the cookie is within
+ * `options.refresh_threshold_seconds` of `expires_at`.
  *
  * @param signed_value - the raw cookie value (signed)
  * @param keyring - key ring for verification
@@ -55,6 +67,11 @@ export const parse_session = async (signed_value, keyring, options, now_seconds)
     const identity = options.decode_identity(identity_payload);
     if (identity === null)
         return null;
+    // Strict integer match — `parseInt` would accept `'123abc'` as `123` and
+    // `' 123'` as `123`. HMAC integrity makes such a tampered value
+    // theoretical, but stricter parsing closes the gap as defense-in-depth.
+    if (!EXPIRES_AT_INTEGER_RE.test(expires_at_str))
+        return null;
     const expires_at = parseInt(expires_at_str, 10);
     if (!Number.isFinite(expires_at))
         return null;
@@ -62,9 +79,12 @@ export const parse_session = async (signed_value, keyring, options, now_seconds)
     const now = now_seconds ?? Math.floor(Date.now() / 1000);
     if (expires_at <= now)
         return null;
+    const refresh_threshold = options.refresh_threshold_seconds ?? SESSION_REFRESH_THRESHOLD_S;
+    const should_refresh_expiration = refresh_threshold > 0 && expires_at - now <= refresh_threshold;
     return {
         identity,
         should_refresh_signature: result.key_index > 0,
+        should_refresh_expiration,
         key_index: result.key_index,
     };
 };
@@ -94,7 +114,7 @@ export const create_session_cookie_value = async (keyring, identity, options, no
  * 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'`)
+ * @param cookie_name - cookie name (e.g. `'zap_session'`, `'visiones_session'`)
  * @returns a `SessionOptions<string>` ready for use with session middleware
  */
 export const create_session_config = (cookie_name) => ({
@@ -108,6 +128,10 @@ export const fuz_session_config = create_session_config('fuz_session');
 /**
  * Process a session cookie and determine what action to take.
  *
+ * `action: 'refresh'` fires on key rotation **or** impending expiration
+ * (within `options.refresh_threshold_seconds`); both produce a freshly-signed
+ * `new_signed_value`.
+ *
  * @param signed_value - the raw cookie value (may be undefined)
  * @param keyring - key ring for verification and signing
  * @param options - session configuration
@@ -125,9 +149,11 @@ export const process_session_cookie = async (signed_value, keyring, options, now
         // Invalid cookie - should be cleared
         return { valid: false, action: 'clear' };
     }
-    // Valid session
-    if (parsed.should_refresh_signature) {
-        // Re-sign with current key (extends expiration)
+    // Valid session — re-sign if the verifying key isn't primary OR if the
+    // embedded expiration is approaching the threshold. The latter mirrors
+    // `query_session_touch`'s DB-side extension so a continuously-active user's
+    // cookie doesn't hard-expire while their server session is still alive.
+    if (parsed.should_refresh_signature || parsed.should_refresh_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 };
     }

package/dist/auth/session_middleware.d.ts

@@ -1,19 +1,26 @@
 /**
- * Hono session middleware using generic session management.
- *
- * Thin wrapper that gets/sets cookies and delegates to session processing.
+ * Hono session boundary — cookie I/O, request-time middleware, and the
+ * session-creation helper shared by login / signup / bootstrap.
  *
  * @module
  */
 import type { Context, MiddlewareHandler } from 'hono';
 import type { Keyring } from './keyring.js';
 import { type SessionOptions } from './session_cookie.js';
+import type { QueryDeps } from '../db/query_deps.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.
+ *
+ * `options.max_age` is the single source of truth for cookie lifetime: it
+ * drives both the embedded `expires_at` (via `create_session_cookie_value`)
+ * and the cookie's HTTP `Max-Age` attribute set here. Falls back to
+ * `SESSION_COOKIE_OPTIONS.maxAge` (= `SESSION_AGE_MAX`) when unset.
+ * `options.cookie_options` cannot carry `maxAge` (omitted in the type) so
+ * the two values can't drift.
  */
 export declare const set_session_cookie: <T>(c: Context, value: string, options: SessionOptions<T>) => void;
 /**
@@ -31,4 +38,31 @@ export declare const clear_session_cookie: <T>(c: Context, options: SessionOptio
  * @mutates Hono context - sets `options.context_key` and may refresh or clear the session cookie
  */
 export declare const create_session_middleware: <TIdentity>(keyring: Keyring, options: SessionOptions<TIdentity>) => MiddlewareHandler;
+/**
+ * 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, signup, and bootstrap — generates a token, hashes it,
+ * persists the session row, optionally enforces a per-account session limit,
+ * and sets the signed cookie.
+ *
+ * @mutates `auth_session` table - inserts the new session row (and evicts older rows when `max_sessions` is set)
+ */
+export declare const create_session_and_set_cookie: (options: CreateSessionAndSetCookieOptions) => Promise<void>;
 //# sourceMappingURL=session_middleware.d.ts.map

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

@@ -1 +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;;;;;;;;;GASG;AACH,eAAO,MAAM,yBAAyB,GAAI,SAAS,EAClD,SAAS,OAAO,EAChB,SAAS,cAAc,CAAC,SAAS,CAAC,KAChC,iBAgBF,CAAC"}
+{"version":3,"file":"session_middleware.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/session_middleware.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;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,EAKnB,MAAM,qBAAqB,CAAC;AAQ7B,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,qBAAqB,CAAC;AAEnD;;GAEG;AACH,eAAO,MAAM,kBAAkB,GAAI,CAAC,EACnC,GAAG,OAAO,EACV,SAAS,cAAc,CAAC,CAAC,CAAC,KACxB,MAAM,GAAG,SAEX,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB,GAAI,CAAC,EACnC,GAAG,OAAO,EACV,OAAO,MAAM,EACb,SAAS,cAAc,CAAC,CAAC,CAAC,KACxB,IAOF,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,oBAAoB,GAAI,CAAC,EAAE,GAAG,OAAO,EAAE,SAAS,cAAc,CAAC,CAAC,CAAC,KAAG,IAMhF,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,yBAAyB,GAAI,SAAS,EAClD,SAAS,OAAO,EAChB,SAAS,cAAc,CAAC,SAAS,CAAC,KAChC,iBAgBF,CAAC;AAEF;;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;;;;;;;;GAQG;AACH,eAAO,MAAM,6BAA6B,GACzC,SAAS,gCAAgC,KACvC,OAAO,CAAC,IAAI,CAad,CAAC"}

package/dist/auth/session_middleware.js

@@ -1,12 +1,12 @@
 /**
- * Hono session middleware using generic session management.
- *
- * Thin wrapper that gets/sets cookies and delegates to session processing.
+ * Hono session boundary — cookie I/O, request-time middleware, and the
+ * session-creation helper shared by login / signup / bootstrap.
  *
  * @module
  */
 import { getCookie, setCookie, deleteCookie } from 'hono/cookie';
-import { SESSION_COOKIE_OPTIONS, process_session_cookie, } from './session_cookie.js';
+import { SESSION_COOKIE_OPTIONS, process_session_cookie, create_session_cookie_value, } from './session_cookie.js';
+import { generate_session_token, hash_session_token, AUTH_SESSION_LIFETIME_MS, query_create_session, query_session_enforce_limit, } from './session_queries.js';
 /**
  * Read the session cookie value from a request.
  */
@@ -15,15 +15,20 @@ export const get_session_cookie = (c, options) => {
 };
 /**
  * Set the session cookie on a response.
+ *
+ * `options.max_age` is the single source of truth for cookie lifetime: it
+ * drives both the embedded `expires_at` (via `create_session_cookie_value`)
+ * and the cookie's HTTP `Max-Age` attribute set here. Falls back to
+ * `SESSION_COOKIE_OPTIONS.maxAge` (= `SESSION_AGE_MAX`) when unset.
+ * `options.cookie_options` cannot carry `maxAge` (omitted in the type) so
+ * the two values can't drift.
  */
 export const set_session_cookie = (c, value, options) => {
     const cookie_options = {
         ...SESSION_COOKIE_OPTIONS,
         ...options.cookie_options,
+        maxAge: options.max_age ?? SESSION_COOKIE_OPTIONS.maxAge,
     };
-    if (options.max_age !== undefined) {
-        cookie_options.maxAge = options.max_age;
-    }
     setCookie(c, options.cookie_name, value, cookie_options);
 };
 /**
@@ -61,3 +66,24 @@ export const create_session_middleware = (keyring, options) => {
         await next();
     };
 };
+/**
+ * Create an auth session and set the session cookie on the response.
+ *
+ * Shared by login, signup, and bootstrap — generates a token, hashes it,
+ * persists the session row, optionally enforces a per-account session limit,
+ * and sets the signed cookie.
+ *
+ * @mutates `auth_session` table - inserts the new session row (and evicts older rows when `max_sessions` is set)
+ */
+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/signup_routes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"signup_routes.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/signup_routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAStB,OAAO,EAAkB,KAAK,SAAS,EAAC,MAAM,uBAAuB,CAAC;AAEtE,OAAO,EAA+B,KAAK,WAAW,EAAC,MAAM,oBAAoB,CAAC;AAClF,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,WAAW,CAAC;AAQhD,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,0BAA0B,CAAC;AAE1D,OAAO,KAAK,EAAC,uBAAuB,EAAC,MAAM,qBAAqB,CAAC;AAEjE;;GAEG;AACH,MAAM,WAAW,kBAAmB,SAAQ,uBAAuB;IAClE,6FAA6F;IAC7F,2BAA2B,EAAE,WAAW,GAAG,IAAI,CAAC;IAChD,yFAAyF;IACzF,YAAY,EAAE,WAAW,CAAC;CAC1B;AAID,0FAA0F;AAC1F,eAAO,MAAM,WAAW;;;;kBAItB,CAAC;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEtD,8EAA8E;AAC9E,eAAO,MAAM,YAAY;;kBAEvB,CAAC;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAExD;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,GACrC,MAAM,gBAAgB,EACtB,SAAS,kBAAkB,KACzB,KAAK,CAAC,SAAS,CA2HjB,CAAC"}
+{"version":3,"file":"signup_routes.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/signup_routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAStB,OAAO,EAAkB,KAAK,SAAS,EAAC,MAAM,uBAAuB,CAAC;AAEtE,OAAO,EAA+B,KAAK,WAAW,EAAC,MAAM,oBAAoB,CAAC;AAClF,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,WAAW,CAAC;AAOhD,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,0BAA0B,CAAC;AAE1D,OAAO,KAAK,EAAC,uBAAuB,EAAC,MAAM,qBAAqB,CAAC;AAEjE;;GAEG;AACH,MAAM,WAAW,kBAAmB,SAAQ,uBAAuB;IAClE,6FAA6F;IAC7F,2BAA2B,EAAE,WAAW,GAAG,IAAI,CAAC;IAChD,yFAAyF;IACzF,YAAY,EAAE,WAAW,CAAC;CAC1B;AAID,0FAA0F;AAC1F,eAAO,MAAM,WAAW;;;;kBAItB,CAAC;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEtD,8EAA8E;AAC9E,eAAO,MAAM,YAAY;;kBAEvB,CAAC;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAExD;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,GACrC,MAAM,gBAAgB,EACtB,SAAS,kBAAkB,KACzB,KAAK,CAAC,SAAS,CAmJjB,CAAC"}