@sourceregistry/sveltekit-oidc 2.1.0 → 3.0.0

package/README.md

@@ -27,61 +27,82 @@ npm install @sourceregistry/sveltekit-oidc
 import {createOIDC} from '@sourceregistry/sveltekit-oidc/server';
 
 type Identity = {
-	sub: string;
-	email?: string;
-	name?: string;
-	roles: string[];
-	permissions?: string[];
+    sub: string;
+    email?: string;
+    name?: string;
+    roles: string[];
+    permissions?: string[];
 };
 
 type RequestData = {
-	permissions: string[];
+    permissions: string[];
 };
 
 export const oidc = createOIDC<Identity, RequestData>({
-	issuer: 'https://identity.example.com',
-	clientId: process.env.OIDC_CLIENT_ID!,
-	clientSecret: process.env.OIDC_CLIENT_SECRET!,
-	clientAuthMethod: 'client_secret_basic',
-	cookieSecret: process.env.OIDC_COOKIE_SECRET!,
-	scope: ['openid', 'profile', 'email', 'offline_access'],
-
-	resolveIdentity: ({idTokenClaims, userInfo}) => ({
-		sub: idTokenClaims.sub,
-		email: userInfo?.email ?? idTokenClaims.email,
-		name: userInfo?.name ?? idTokenClaims.name,
-		roles: Array.isArray(userInfo?.roles ?? idTokenClaims.roles)
-			? ((userInfo?.roles ?? idTokenClaims.roles) as string[])
-			: []
-	}),
-
-	beforeSessionPersist: async ({session, reason}) => {
-		const identity = await synchronizeUser(session.identity, reason);
-		return {...session, identity};
-	},
-
-	loadRequestData: async ({session, event}) => ({
-		permissions: await loadPermissions(session.sub!, event)
-	}),
-
-	createPublicSession: ({base, data}) => ({
-		...base,
-		identity: {
-			...base.identity,
-			permissions: data?.permissions ?? []
-		}
-	})
+    issuer: 'https://identity.example.com',
+    clientId: process.env.OIDC_CLIENT_ID!,
+    clientSecret: process.env.OIDC_CLIENT_SECRET!,
+    clientAuthMethod: 'client_secret_basic',
+    cookieSecret: process.env.OIDC_COOKIE_SECRET!,
+    scope: ['openid', 'profile', 'email', 'offline_access'],
+
+    resolveIdentity: ({idTokenClaims, userInfo}) => ({
+        sub: idTokenClaims.sub,
+        email: userInfo?.email ?? idTokenClaims.email,
+        name: userInfo?.name ?? idTokenClaims.name,
+        roles: Array.isArray(userInfo?.roles ?? idTokenClaims.roles)
+            ? ((userInfo?.roles ?? idTokenClaims.roles) as string[])
+            : []
+    }),
+
+    beforeSessionPersist: async ({session, reason}) => {
+        const identity = await synchronizeUser(session.identity, reason);
+        return {...session, identity};
+    },
+
+    loadRequestData: async ({session, event}) => ({
+        permissions: await loadPermissions(session.sub!, event)
+    }),
+
+    createPublicSession: ({base, data}) => ({
+        ...base,
+        identity: {
+            ...base.identity,
+            permissions: data?.permissions ?? []
+        }
+    })
 });
 ```
 
+`cookieSecret` must contain at least 32 bytes of entropy. For example:
+
+```sh
+openssl rand -base64 32
+```
+
+Discovery and protocol endpoints must use HTTPS by default. Set `allowInsecureHttp: true` only for
+local development providers. `openid` is always included in the requested scope, and values in
+`extraParams` cannot replace security-sensitive authorization parameters such as `state`, `nonce`,
+PKCE, `redirect_uri`, or `client_id`.
+
+If the client registration fixes an ID-token signing algorithm, pin it explicitly:
+
+```ts
+idTokenSigningAlgorithms: ['RS256'],
+trustedIdTokenAudiences: ['https://api.example.com']
+```
+
+The client ID is always required in `aud`. `trustedIdTokenAudiences` permits only explicitly trusted
+additional audience values; it does not replace the client ID.
+
 The extension points have deliberately literal names:
 
-| Extension point        | When it runs                                                     | Persisted                                       |
-| ----------------------- | ----------------------------------------------------------------- | ------------------------------------------------ |
-| `resolveIdentity`      | After provider data is validated, on login and refresh          | Its result is persisted                         |
-| `beforeSessionPersist` | Immediately before a login or refreshed session is written      | Returned session replaces it; `void` keeps it   |
-| `loadRequestData`      | Once while `handle` builds an authenticated request context     | Never                                            |
-| `createPublicSession`  | When `getPublicSession` or `toPublicSession` projects a session | Never                                            |
+| Extension point        | When it runs                                                    | Persisted                                     |
+| ---------------------- | --------------------------------------------------------------- | --------------------------------------------- |
+| `resolveIdentity`      | After provider data is validated, on login and refresh          | Its result is persisted                       |
+| `beforeSessionPersist` | Immediately before a login or refreshed session is written      | Returned session replaces it; `void` keeps it |
+| `loadRequestData`      | Once while `handle` builds an authenticated request context     | Never                                         |
+| `createPublicSession`  | When `getPublicSession` or `toPublicSession` projects a session | Never                                         |
 
 Both login and refresh are explicit in the callback context. Returning a session from
 `beforeSessionPersist` is what makes it the right place to provision or enrich application data —
@@ -89,13 +110,13 @@ e.g. upserting a user row — before the very first session for that user is per
 
 ```ts
 beforeSessionPersist: async ({session, reason}) => {
-	if (reason !== 'login') return;
-	const user = await upsertUser(session.identity);
-	return {...session, identity: {...session.identity, ...user}};
+    if (reason !== 'login') return;
+    const user = await upsertUser(session.identity);
+    return {...session, identity: {...session.identity, ...user}};
 };
 ```
 
-`resolveIdentity` runs first and may only be able to *read* application data (the user may not
+`resolveIdentity` runs first and may only be able to _read_ application data (the user may not
 exist yet on a first login). `beforeSessionPersist` runs next, right before the write, so a session
 mutated or replaced there is the one every subsequent read of that session — including the result
 returned from `handleCallback`/`callbackHandler`'s `onsuccess` — actually sees.
@@ -125,11 +146,11 @@ import type {OIDCLocals} from '@sourceregistry/sveltekit-oidc/server';
 import type {oidc} from '$lib/server/auth';
 
 declare global {
-	namespace App {
-		interface Locals {
-			oidc?: OIDCLocals<typeof oidc>;
-		}
-	}
+    namespace App {
+        interface Locals {
+            oidc?: OIDCLocals<typeof oidc>;
+        }
+    }
 }
 
 export {};
@@ -210,6 +231,7 @@ sequenceDiagram
 `handle` (the SvelteKit hook) wraps every request outside of these four routes: it calls
 `getSession`, which transparently refreshes an expiring session — running `resolveIdentity` and
 `beforeSessionPersist` again with `reason: 'refresh'` — before exposing `event.locals.oidc`.
+
 - `getSession(event)`
 - `requireAuth(event)`
 - `clearSession(cookies)`
@@ -223,10 +245,10 @@ Load a token-free session for the browser:
 import {oidc} from '$lib/server/auth';
 
 export async function load(event) {
-	return {
-		session: oidc.toPublicSession(event.locals.oidc, event.depends),
-		sessionManagement: await oidc.getSessionManagementConfig()
-	};
+    return {
+        session: oidc.toPublicSession(event.locals.oidc, event.depends),
+        sessionManagement: await oidc.getSessionManagementConfig()
+    };
 }
 ```
 
@@ -243,7 +265,13 @@ returns. `getPublicSession(event)` is available when the hook has not already lo
 	let { data, children } = $props();
 </script>
 
-<OIDCContext session={data.session} config={data.sessionManagement}>
+<OIDCContext
+	session={data.session}
+	config={data.sessionManagement}
+	idleTimeoutMs={30 * 60 * 1000}
+	idleWarningMs={60 * 1000}
+	heartbeatUrl="/auth/heartbeat"
+>
 	{@render children()}
 </OIDCContext>
 ```
@@ -262,6 +290,12 @@ returns. `getPublicSession(event)` is available when the hook has not already lo
 `OIDCContext` supports local expiry handling, targeted SvelteKit revalidation,
 `check_session_iframe` monitoring, and local or provider logout.
 
+Idle deadlines use absolute timestamps, synchronize activity across tabs, and remain correct after a
+tab or device resumes from sleep. The default idle action performs provider logout; set
+`redirectOnIdle="logout"` only when clearing the application session without ending the OP
+session is intentional. `heartbeatUrl` is application-owned and should be a same-origin,
+CSRF-protected endpoint that returns `401` or `403` when the session is no longer valid.
+
 When the OP iframe reports `changed`, the component first performs the Session Management 1.0
 `prompt=none` authorization check in a hidden iframe. The login handler supplies the current ID token
 as `id_token_hint`; a matching End-User refreshes the local session, while an OP error or a different
@@ -270,34 +304,56 @@ not need an additional endpoint.
 
 ## Session stores
 
-Without `sessionStore`, the encrypted session is stored in the cookie. For server-side sessions:
+Without `sessionStore`, the encrypted session is stored in the cookie. The default maximum serialized
+cookie size is 3800 bytes so oversized sessions fail explicitly instead of being silently truncated by
+a browser or proxy. Use a server-side store for large tokens or identities:
 
 ```ts
 import type {OIDCSessionStore} from '@sourceregistry/sveltekit-oidc/server';
 
 const sessionStore: OIDCSessionStore<Identity> = {
-	get: (id) => redis.get(`session:${id}`),
-	set: async (id, session) => {
-		await redis.set(`session:${id}`, session);
-	},
-	delete: async (id) => {
-		await redis.delete(`session:${id}`);
-	}
+    get: (id) => redis.get(`session:${id}`),
+    set: async (id, session) => {
+        await redis.set(`session:${id}`, session);
+    },
+    delete: async (id) => {
+        await redis.delete(`session:${id}`);
+    }
 };
 ```
 
 Use a shared `backChannelLogoutStore` when back-channel logout must work across multiple instances.
 The built-in `'memory'` stores are intended for local development or single-process deployments.
 
+Providers that rotate refresh tokens also need a distributed `refreshLock` in multi-instance
+deployments. The built-in promise coalescing prevents duplicate refreshes within one process; the
+lock must serialize the supplied operation by session ID across every application instance:
+
+```ts
+const refreshLock = {
+    runExclusive: <T>(sessionId: string, operation: () => Promise<T>) =>
+        redlock.using([`oidc-refresh:${sessionId}`], 10_000, operation)
+};
+```
+
 ## Security behavior
 
-- Authorization Code flow uses PKCE, state, and nonce.
-- ID tokens are verified against provider JWKS and require matching issuer, audience, nonce, `exp`, and `iat`.
+- Authorization Code flow uses PKCE, nonce, and an encrypted state value; each pending authorization
+  transaction has its own cookie, so concurrent logins in separate tabs do not overwrite each other.
+- Discovery metadata is bound to the configured issuer, and HTTPS is required unless explicitly
+  disabled for local development.
+- Initial ID tokens require matching issuer, client audience, nonce, `exp`, and `iat`. Refreshed ID
+  tokens may omit nonce as allowed by OIDC Core, but must preserve subject, audiences, authorized
+  party, and authentication time.
 - UserInfo `sub` must match the validated ID token subject.
 - Cookie sessions use authenticated encryption.
 - Return and post-logout redirect values are restricted to same-origin paths.
 - Local sessions have an eight-hour maximum lifetime by default.
-- Refresh is automatic while a valid refresh token is available.
+- Refresh is automatic while a valid refresh token is available and is coalesced per session within a
+  process.
+- Back-channel logout tokens require the logout event, `iat`, `exp`, `jti`, and exactly one or both of
+  `sid` and `sub`; `nonce` is rejected. Revocations expire and do not revoke later logins permanently.
+- Local session clearing does not depend on provider discovery being available.
 - Client authentication supports `none`, `client_secret_basic`, `client_secret_post`, `client_secret_jwt`, and `private_key_jwt`.
 
 Application code can normalize provider-specific data in `resolveIdentity`, but cannot replace the

package/dist/client/OIDCContext.svelte

@@ -11,9 +11,10 @@
     import type {Snippet} from 'svelte';
 
     import {setOIDCContext} from './context.js';
+	import {getIdlePhase, normalizeIdleDuration} from './idle.js';
     import {classifySessionMonitorEvent} from './session-monitor.js';
 
-    type RedirectMode = 'login' | 'logout' | 'reload' | 'none';
+	type RedirectMode = 'login' | 'logout' | 'provider-logout' | 'reload' | 'none';
 
     type OIDCClientDebugEvent = {
         type: string;
@@ -32,6 +33,14 @@
         redirectOnExpired = 'login',
         redirectOnRevoked = 'login',
         redirectIfUnauthenticated = false,
+        idleTimeoutMs = 0,
+		redirectOnIdle = 'provider-logout',
+        idleEvents = ['mousedown', 'mousemove', 'keydown', 'scroll', 'touchstart', 'wheel'],
+        idleActivityThrottleMs = 1000,
+        idleWarningMs = 0,
+        idleWarning,
+        heartbeatUrl,
+        heartbeatIntervalMs = 60_000,
         onDebug,
         children
     }: {
@@ -46,6 +55,30 @@
         redirectOnExpired?: RedirectMode;
         redirectOnRevoked?: RedirectMode;
         redirectIfUnauthenticated?: boolean;
+        /** Milliseconds of no user activity before forcing redirectOnIdle. 0 disables idle tracking. */
+        idleTimeoutMs?: number;
+        redirectOnIdle?: RedirectMode;
+        /** window events treated as activity; reset the idle timer, throttled by idleActivityThrottleMs. */
+        idleEvents?: string[];
+        idleActivityThrottleMs?: number;
+        /**
+         * How long before idleTimeoutMs to show idleWarning instead of redirecting immediately.
+         * 0 (default) skips the warning and redirects at idleTimeoutMs, same as before.
+         * Must be less than idleTimeoutMs.
+         */
+        idleWarningMs?: number;
+        /** Rendered while the idle warning is active. Passed secondsRemaining plus stayLoggedIn/logout callbacks. */
+        idleWarning?: Snippet<[{secondsRemaining: number; stayLoggedIn: () => void; logout: () => void}]>;
+        /**
+         * Server endpoint touched on activity to reset the *server-side* idle timer
+         * (e.g. the identity service's session_idle_timeout). Undefined disables this —
+         * revalidate()/stayLoggedIn() alone only reach the server when the access token
+         * is near expiry, so without this the server session can idle out independently
+         * of what this component shows.
+         */
+        heartbeatUrl?: string;
+        /** Minimum gap between heartbeat requests while active. Match the server's own touch throttle. */
+        heartbeatIntervalMs?: number;
         /** Receives token-safe lifecycle events for diagnosing session changes. */
         onDebug?: (event: OIDCClientDebugEvent) => void;
         children?: Snippet;
@@ -58,9 +91,13 @@
     let status = $state<'authenticated' | 'unauthenticated' | 'expired' | 'revoked'>('unauthenticated');
     let revalidating = $state(false);
     let handledUnauthenticated = $state(false);
+    let idleWarningVisible = $state(false);
+    let idleSecondsRemaining = $state(0);
+    let idleStayLoggedIn = () => {};
+    let idleLogoutNow = () => {};
     let sessionExpiredDuringRevalidation = false;
 
-    function debug(type: string, details?: Record<string, unknown>) {
+    function debug(type: string, details: Record<string, unknown> | undefined = undefined) {
         onDebug?.({type, details});
     }
 
@@ -73,6 +110,11 @@
     const canMonitorIframe = $derived(
         Boolean(monitorSession && session?.isAuthenticated && session?.sessionState && iframeUrl)
     );
+	const effectiveIdleTimeoutMs = $derived(normalizeIdleDuration(idleTimeoutMs));
+	const effectiveIdleWarningMs = $derived(normalizeIdleDuration(idleWarningMs));
+	const effectiveIdleActivityThrottleMs = $derived(normalizeIdleDuration(idleActivityThrottleMs, 1000));
+	const effectiveHeartbeatIntervalMs = $derived(normalizeIdleDuration(heartbeatIntervalMs, 60_000));
+	const idleActivityStorageKey = $derived(`sveltekit-oidc:activity:${config.issuer}:${config.clientId}`);
 
     const context = setOIDCContext<TIdentity>({
         get isAuthenticated() {
@@ -99,7 +141,7 @@
         get revalidating() {
             return revalidating;
         },
-        login: (returnTo?: string) => login(returnTo),
+        login: (returnTo: string | undefined = undefined) => login(returnTo),
         logout,
         revalidate
     });
@@ -118,7 +160,7 @@
 
     function buildLoginUrl(
         returnTo = `${window.location.pathname}${window.location.search}`,
-        prompt?: 'none'
+        prompt: 'none' | undefined = undefined
     ) {
         const url = new URL(resolvedLoginPath, window.location.href);
         url.searchParams.set('returnTo', returnTo);
@@ -153,7 +195,24 @@
         form.submit();
     }
 
-    function login(returnTo?: string) {
+	async function sendHeartbeat(): Promise<boolean> {
+		if (!heartbeatUrl) return true;
+        try {
+            const response = await fetch(heartbeatUrl, {method: 'POST', credentials: 'same-origin'});
+            if (!response.ok) {
+                debug('heartbeat_failed', {status: response.status});
+				if (response.status === 401 || response.status === 403) void handleRedirect('logout');
+				return false;
+            }
+            debug('heartbeat_sent');
+			return true;
+        } catch (err) {
+            debug('heartbeat_failed', {error: err instanceof Error ? err.message : String(err)});
+			return false;
+        }
+    }
+
+    function login(returnTo: string | undefined = undefined) {
         debug('login_redirect_requested', {returnTo: returnTo ?? `${window.location.pathname}${window.location.search}`});
         // loginPath is a plain +server.ts redirect endpoint, not a routable
         // page — use a full browser navigation, not SvelteKit's goto().
@@ -209,6 +268,10 @@
             window.location.reload();
             return;
         }
+		if (mode === 'provider-logout') {
+			await logout(false);
+			return;
+		}
 
         login();
     }
@@ -331,6 +394,147 @@
         return () => window.clearInterval(timer);
     });
 
+    $effect(() => {
+        if (!heartbeatUrl || !session?.isAuthenticated) {
+            return;
+        }
+
+        let lastHeartbeatAt = 0;
+		let heartbeatInFlight = false;
+
+        function onActivity() {
+            const now = Date.now();
+			if (heartbeatInFlight || now - lastHeartbeatAt < effectiveHeartbeatIntervalMs) return;
+            lastHeartbeatAt = now;
+			heartbeatInFlight = true;
+			void sendHeartbeat().finally(() => {
+				heartbeatInFlight = false;
+			});
+        }
+
+        for (const eventName of idleEvents) {
+            window.addEventListener(eventName, onActivity, {passive: true});
+        }
+
+        return () => {
+            for (const eventName of idleEvents) {
+                window.removeEventListener(eventName, onActivity);
+            }
+        };
+    });
+
+    $effect(() => {
+		if (!effectiveIdleTimeoutMs || !session?.isAuthenticated) {
+            idleWarningVisible = false;
+            return;
+        }
+
+		let timer: number | undefined;
+		let lastActivityAt = Date.now();
+		let lastLocalActivityAt = 0;
+		let logoutTriggered = false;
+		try {
+			const sharedActivity = Number(window.localStorage.getItem(idleActivityStorageKey));
+			if (Number.isFinite(sharedActivity)) lastActivityAt = Math.max(lastActivityAt, sharedActivity);
+		} catch {
+			// Storage can be denied in privacy modes; per-tab idle tracking still works.
+		}
+
+		function shareActivity(timestamp: number) {
+			try {
+				window.localStorage.setItem(idleActivityStorageKey, String(timestamp));
+			} catch {
+				// See storage-read fallback above.
+			}
+		}
+
+		function schedule() {
+			if (timer) window.clearTimeout(timer);
+			const phase = getIdlePhase(
+				lastActivityAt,
+				Date.now(),
+				effectiveIdleTimeoutMs,
+				effectiveIdleWarningMs
+			);
+			idleSecondsRemaining = phase.secondsRemaining;
+			if (phase.phase === 'idle') {
+				if (!logoutTriggered) {
+					logoutTriggered = true;
+					idleWarningVisible = false;
+					debug('idle_timeout_reached', {idleTimeoutMs: effectiveIdleTimeoutMs});
+					void handleRedirect(redirectOnIdle);
+				}
+				return;
+			}
+			if (phase.phase === 'warning' && !idleWarningVisible) {
+				idleWarningVisible = true;
+				debug('idle_warning_shown', {idleWarningMs: effectiveIdleWarningMs});
+			} else if (phase.phase === 'active') {
+				idleWarningVisible = false;
+			}
+			const untilTransition = Math.max(1, (phase.nextTransitionAt ?? Date.now() + 1000) - Date.now());
+			timer = window.setTimeout(schedule, phase.phase === 'warning' ? Math.min(1000, untilTransition) : untilTransition);
+		}
+
+        function onActivity() {
+            // Once the warning is up, passive activity (e.g. moving the mouse while
+            // reading the modal) must not silently dismiss it — only an explicit
+            // stayLoggedIn() response should reset the timer.
+            if (idleWarningVisible) return;
+            const now = Date.now();
+			if (now - lastLocalActivityAt < effectiveIdleActivityThrottleMs) return;
+			lastLocalActivityAt = now;
+            lastActivityAt = now;
+			shareActivity(now);
+			schedule();
+        }
+
+		function onSharedActivity(event: StorageEvent) {
+			if (event.key !== idleActivityStorageKey) return;
+			const timestamp = Number(event.newValue);
+			if (!Number.isFinite(timestamp) || timestamp <= lastActivityAt) return;
+			lastActivityAt = timestamp;
+			logoutTriggered = false;
+			schedule();
+		}
+
+		idleStayLoggedIn = () => {
+            debug('idle_warning_dismissed_stay_logged_in');
+			void (async () => {
+				if (!(await sendHeartbeat())) return;
+				await revalidate();
+				await tick();
+				if (!session?.isAuthenticated) return;
+				lastActivityAt = Date.now();
+				logoutTriggered = false;
+				shareActivity(lastActivityAt);
+				schedule();
+			})();
+        };
+        idleLogoutNow = () => {
+			if (timer) window.clearTimeout(timer);
+            idleWarningVisible = false;
+            void logout();
+        };
+
+		shareActivity(lastActivityAt);
+		schedule();
+        for (const eventName of idleEvents) {
+            window.addEventListener(eventName, onActivity, {passive: true});
+        }
+		window.addEventListener('storage', onSharedActivity);
+		document.addEventListener('visibilitychange', schedule);
+
+        return () => {
+			if (timer) window.clearTimeout(timer);
+            for (const eventName of idleEvents) {
+                window.removeEventListener(eventName, onActivity);
+            }
+			window.removeEventListener('storage', onSharedActivity);
+			document.removeEventListener('visibilitychange', schedule);
+        };
+    });
+
     $effect(() => {
         if (session?.isAuthenticated) {
             handledUnauthenticated = false;
@@ -404,4 +608,12 @@
     ></iframe>
 {/if}
 
+{#if idleWarningVisible && idleWarning}
+    {@render idleWarning({
+        secondsRemaining: idleSecondsRemaining,
+        stayLoggedIn: () => idleStayLoggedIn(),
+        logout: () => idleLogoutNow()
+    })}
+{/if}
+
 {@render children?.()}

package/dist/client/OIDCContext.svelte.d.ts

@@ -10,9 +10,37 @@ declare function $$render<TIdentity extends OIDCUserClaims = OIDCUserClaims>():
         monitorSession?: boolean;
         revalidateIntervalMs?: number;
         renewalLeadTimeMs?: number;
-        redirectOnExpired?: "login" | "none" | "logout" | "reload";
-        redirectOnRevoked?: "login" | "none" | "logout" | "reload";
+        redirectOnExpired?: "login" | "none" | "logout" | "provider-logout" | "reload";
+        redirectOnRevoked?: "login" | "none" | "logout" | "provider-logout" | "reload";
         redirectIfUnauthenticated?: boolean;
+        /** Milliseconds of no user activity before forcing redirectOnIdle. 0 disables idle tracking. */
+        idleTimeoutMs?: number;
+        redirectOnIdle?: "login" | "none" | "logout" | "provider-logout" | "reload";
+        /** window events treated as activity; reset the idle timer, throttled by idleActivityThrottleMs. */
+        idleEvents?: string[];
+        idleActivityThrottleMs?: number;
+        /**
+         * How long before idleTimeoutMs to show idleWarning instead of redirecting immediately.
+         * 0 (default) skips the warning and redirects at idleTimeoutMs, same as before.
+         * Must be less than idleTimeoutMs.
+         */
+        idleWarningMs?: number;
+        /** Rendered while the idle warning is active. Passed secondsRemaining plus stayLoggedIn/logout callbacks. */
+        idleWarning?: Snippet<[{
+            secondsRemaining: number;
+            stayLoggedIn: () => void;
+            logout: () => void;
+        }]>;
+        /**
+         * Server endpoint touched on activity to reset the *server-side* idle timer
+         * (e.g. the identity service's session_idle_timeout). Undefined disables this —
+         * revalidate()/stayLoggedIn() alone only reach the server when the access token
+         * is near expiry, so without this the server session can idle out independently
+         * of what this component shows.
+         */
+        heartbeatUrl?: string;
+        /** Minimum gap between heartbeat requests while active. Match the server's own touch throttle. */
+        heartbeatIntervalMs?: number;
         /** Receives token-safe lifecycle events for diagnosing session changes. */
         onDebug?: (event: {
             type: string;

package/dist/client/idle.d.ts

@@ -0,0 +1,7 @@
+export type IdlePhase = {
+    phase: 'active' | 'warning' | 'idle';
+    secondsRemaining: number;
+    nextTransitionAt?: number;
+};
+export declare function normalizeIdleDuration(value: number, fallback?: number): number;
+export declare function getIdlePhase(lastActivityAt: number, now: number, idleTimeoutMs: number, idleWarningMs: number): IdlePhase;

package/dist/client/idle.js

@@ -0,0 +1,22 @@
+export function normalizeIdleDuration(value, fallback = 0) {
+    return Number.isFinite(value) && value > 0 ? value : fallback;
+}
+export function getIdlePhase(lastActivityAt, now, idleTimeoutMs, idleWarningMs) {
+    const deadline = lastActivityAt + idleTimeoutMs;
+    if (now >= deadline)
+        return { phase: 'idle', secondsRemaining: 0 };
+    const warningMs = idleWarningMs > 0 && idleWarningMs < idleTimeoutMs ? idleWarningMs : 0;
+    const warningAt = deadline - warningMs;
+    if (warningMs && now >= warningAt) {
+        return {
+            phase: 'warning',
+            secondsRemaining: Math.max(0, Math.ceil((deadline - now) / 1000)),
+            nextTransitionAt: deadline
+        };
+    }
+    return {
+        phase: 'active',
+        secondsRemaining: Math.max(0, Math.ceil((deadline - now) / 1000)),
+        nextTransitionAt: warningMs ? warningAt : deadline
+    };
+}

package/dist/server/cookies.d.ts

@@ -1,2 +1,2 @@
 import type { CookieOptions, OIDCCookies, OIDCUserClaims } from './types.js';
-export declare function createOIDCCookieStore<TIdentity extends OIDCUserClaims = OIDCUserClaims>(cookieSecret: string, sessionCookieName: string, stateCookieName: string, cookieOptions: CookieOptions): OIDCCookies<TIdentity>;
+export declare function createOIDCCookieStore<TIdentity extends OIDCUserClaims = OIDCUserClaims>(cookieSecret: string, sessionCookieName: string, stateCookieName: string, cookieOptions: CookieOptions, stateMaxAgeSeconds: number, maxCookieSizeBytes: number): OIDCCookies<TIdentity>;