@sourceregistry/sveltekit-oidc 2.0.1 → 2.1.0

package/README.md

@@ -56,7 +56,8 @@ export const oidc = createOIDC<Identity, RequestData>({
 	}),
 
 	beforeSessionPersist: async ({session, reason}) => {
-		await synchronizeUser(session.identity, reason);
+		const identity = await synchronizeUser(session.identity, reason);
+		return {...session, identity};
 	},
 
 	loadRequestData: async ({session, event}) => ({
@@ -75,23 +76,30 @@ export const oidc = createOIDC<Identity, RequestData>({
 
 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      | Side effects only       |
-| `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:
+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 —
+e.g. upserting a user row — before the very first session for that user is persisted:
 
 ```ts
 beforeSessionPersist: async ({session, reason}) => {
-	if (reason === 'login') {
-		await recordLogin(session.identity);
-	}
+	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
+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.
+
 ## SvelteKit hook
 
 ```ts
@@ -159,6 +167,49 @@ The underlying operations are also available directly when a route needs custom
 - `handleCallback(event)`
 - `logout(event, options)`
 - `handleBackChannelLogout(event)`
+
+### Request flow
+
+```mermaid
+sequenceDiagram
+    participant Browser
+    participant login as loginHandler
+    participant callback as callbackHandler
+    participant logout as logoutHandler
+    participant bcl as backChannelLogoutHandler
+    participant OP as OpenID Provider
+
+    Browser->>login: GET /auth/login
+    login->>login: create PKCE pair, state, nonce
+    login-->>Browser: 302 redirect to OP authorize endpoint
+    Browser->>OP: authenticate
+    OP-->>Browser: 302 redirect with code & state
+
+    Browser->>callback: GET /auth/callback?code&state
+    callback->>OP: POST token endpoint (exchange code)
+    OP-->>callback: id_token, access_token, refresh_token
+    callback->>OP: verify id_token against JWKS
+    callback->>OP: GET userinfo endpoint (optional)
+    callback->>callback: resolveIdentity(idTokenClaims, userInfo)
+    callback->>callback: beforeSessionPersist(session, reason:'login')
+    Note over callback: a returned session here replaces<br/>what gets persisted and returned
+    callback->>callback: write session (cookie or sessionStore)
+    callback-->>Browser: onsuccess(event, result) or 302 redirect
+
+    Browser->>logout: POST /auth/logout
+    logout->>logout: clear persisted session
+    logout-->>Browser: 302 redirect to OP end_session endpoint or local page
+
+    OP->>bcl: POST /auth/backchannel-logout (logout_token)
+    bcl->>OP: verify logout_token against JWKS
+    bcl->>bcl: backChannelLogoutStore.revoke(sid/sub)
+    bcl-->>OP: 200 OK
+    Note over bcl: next getSession()/requireAuth() call<br/>for that sid/sub treats the session as revoked
+```
+
+`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)`
@@ -211,6 +262,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.
 
+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
+End-User clears it. Applications using the standard `loginHandler()` and `callbackHandler()` routes do
+not need an additional endpoint.
+
 ## Session stores
 
 Without `sessionStore`, the encrypted session is stored in the cookie. For server-side sessions:

package/dist/client/OIDCContext.svelte

@@ -7,11 +7,11 @@
 
 <script lang="ts" generics="TIdentity extends OIDCUserClaims = OIDCUserClaims">
     import {beforeNavigate, invalidate, invalidateAll} from '$app/navigation';
-    import {tick} from 'svelte';
+    import {onDestroy, tick} from 'svelte';
     import type {Snippet} from 'svelte';
 
     import {setOIDCContext} from './context.js';
-    import {classifySessionMonitorMessage} from './session-monitor.js';
+    import {classifySessionMonitorEvent} from './session-monitor.js';
 
     type RedirectMode = 'login' | 'logout' | 'reload' | 'none';
 
@@ -51,7 +51,10 @@
         children?: Snippet;
     } = $props();
 
-    let iframe = $state<HTMLIFrameElement | undefined>(undefined);
+    let sessionIframe = $state<HTMLIFrameElement | undefined>(undefined);
+    let silentReauthenticationIframe = $state<HTMLIFrameElement | undefined>(undefined);
+    let silentReauthenticationUrl = $state<string | undefined>(undefined);
+    let silentReauthenticationTimeout: number | undefined;
     let status = $state<'authenticated' | 'unauthenticated' | 'expired' | 'revoked'>('unauthenticated');
     let revalidating = $state(false);
     let handledUnauthenticated = $state(false);
@@ -113,8 +116,14 @@
         }
     });
 
-    function buildLoginUrl(returnTo = `${window.location.pathname}${window.location.search}`) {
-        return `${resolvedLoginPath}?returnTo=${encodeURIComponent(returnTo)}`;
+    function buildLoginUrl(
+        returnTo = `${window.location.pathname}${window.location.search}`,
+        prompt?: 'none'
+    ) {
+        const url = new URL(resolvedLoginPath, window.location.href);
+        url.searchParams.set('returnTo', returnTo);
+        if (prompt) url.searchParams.set('prompt', prompt);
+        return `${url.pathname}${url.search}${url.hash}`;
     }
 
     async function logout(clearSessionOnly = false) {
@@ -204,6 +213,58 @@
         login();
     }
 
+    async function finishSilentReauthentication(result: 'authenticated' | 'logged_out') {
+        if (silentReauthenticationTimeout) {
+            window.clearTimeout(silentReauthenticationTimeout);
+            silentReauthenticationTimeout = undefined;
+        }
+        silentReauthenticationUrl = undefined;
+        await revalidate();
+        await tick();
+
+        if (result === 'authenticated' && session?.isAuthenticated) {
+            status = 'authenticated';
+            debug('silent_reauthentication_completed', {sub: session.sub});
+            return;
+        }
+
+        status = 'revoked';
+        debug('silent_reauthentication_logged_out');
+        await handleRedirect(redirectOnRevoked);
+    }
+
+    function startSilentReauthentication() {
+        if (silentReauthenticationUrl) return;
+
+        debug('silent_reauthentication_started');
+        silentReauthenticationUrl = buildLoginUrl(
+            `${window.location.pathname}${window.location.search}`,
+            'none'
+        );
+        silentReauthenticationTimeout = window.setTimeout(() => {
+            debug('silent_reauthentication_timed_out');
+            void logout(true).then(() => finishSilentReauthentication('logged_out'));
+        }, 30_000);
+    }
+
+    function handleSilentReauthenticationLoad() {
+        if (!silentReauthenticationUrl || !silentReauthenticationIframe?.contentWindow) return;
+
+        try {
+            const documentElement = silentReauthenticationIframe.contentWindow.document.documentElement;
+            const result = documentElement.dataset.oidcSilentReauth;
+            if (result === 'authenticated' || result === 'logged_out') {
+                void finishSilentReauthentication(result);
+            }
+        } catch {
+            // The authorization request is currently displaying the cross-origin OP document.
+        }
+    }
+
+    onDestroy(() => {
+        if (silentReauthenticationTimeout) window.clearTimeout(silentReauthenticationTimeout);
+    });
+
     $effect(() => {
         const isAuthenticated = Boolean(session?.isAuthenticated);
         // Suppress authenticated→unauthenticated transition while a revalidation is
@@ -285,25 +346,21 @@
     });
 
     $effect(() => {
-        if (!canMonitorIframe || !iframeUrl || !iframe) {
+        if (!canMonitorIframe || !iframeUrl || !sessionIframe) {
             return;
         }
 
         const targetOrigin = new URL(iframeUrl).origin;
         const poll = window.setInterval(() => {
-            if (!iframe?.contentWindow || !session?.sessionState) {
+            if (!sessionIframe?.contentWindow || !session?.sessionState) {
                 return;
             }
 
-            iframe.contentWindow.postMessage(`${config.clientId} ${session.sessionState}`, targetOrigin);
+            sessionIframe.contentWindow.postMessage(`${config.clientId} ${session.sessionState}`, targetOrigin);
         }, checkSessionIntervalMs);
 
         const onMessage = (event: MessageEvent) => {
-            if (event.origin !== targetOrigin) {
-                return;
-            }
-
-            const result = classifySessionMonitorMessage(event.data);
+            const result = classifySessionMonitorEvent(event, targetOrigin, sessionIframe?.contentWindow);
             if (result === 'error') {
                 // `error` means the OP could not determine session state (for example,
                 // transient storage or network denial). It is not proof of revocation.
@@ -312,8 +369,7 @@
             }
             if (result === 'changed') {
                 debug('iframe_session_event', {result, origin: event.origin});
-                status = 'revoked';
-                void logout(true).then(() => handleRedirect(redirectOnRevoked));
+                startSilentReauthentication();
             }
         };
 
@@ -328,7 +384,8 @@
 
 {#if canMonitorIframe && iframeUrl}
     <iframe
-            bind:this={iframe}
+            id="oidc-session-monitor"
+            bind:this={sessionIframe}
             title="OIDC session monitor"
             src={iframeUrl}
             hidden
@@ -336,4 +393,15 @@
     ></iframe>
 {/if}
 
+{#if silentReauthenticationUrl}
+    <iframe
+            bind:this={silentReauthenticationIframe}
+            title="OIDC silent re-authentication"
+            src={silentReauthenticationUrl}
+            onload={handleSilentReauthenticationLoad}
+            hidden
+            aria-hidden="true"
+    ></iframe>
+{/if}
+
 {@render children?.()}

package/dist/client/session-monitor.d.ts

@@ -1,2 +1,3 @@
 export type OIDCSessionMonitorMessage = 'changed' | 'unchanged' | 'error' | 'ignored';
 export declare function classifySessionMonitorMessage(data: unknown): OIDCSessionMonitorMessage;
+export declare function classifySessionMonitorEvent(event: Pick<MessageEvent, 'data' | 'origin' | 'source'>, expectedOrigin: string, expectedSource: unknown): OIDCSessionMonitorMessage;

package/dist/client/session-monitor.js

@@ -1,3 +1,9 @@
 export function classifySessionMonitorMessage(data) {
     return data === 'changed' || data === 'unchanged' || data === 'error' ? data : 'ignored';
 }
+export function classifySessionMonitorEvent(event, expectedOrigin, expectedSource) {
+    if (event.origin !== expectedOrigin || !expectedSource || event.source !== expectedSource) {
+        return 'ignored';
+    }
+    return classifySessionMonitorMessage(event.data);
+}

package/dist/server/index.js

@@ -8,6 +8,21 @@ import { absoluteUrl, base64UrlEncode, buildCookieOptions, collectGroups, create
 import { createInMemoryBackChannelLogoutStore, createInMemorySessionStore } from './store.js';
 export { createInMemoryBackChannelLogoutStore, createInMemorySessionStore } from './store.js';
 const OIDC_SESSION_REVALIDATION_DEPENDENCY = 'oidc:session';
+const LOGIN_PROMPTS = new Set([
+    'login',
+    'consent',
+    'none',
+    'select_account'
+]);
+function silentReauthenticationResponse(status) {
+    return new Response(`<!doctype html><html lang="en" data-oidc-silent-reauth="${status}"><head><meta charset="utf-8"><title>OIDC session check</title></head><body></body></html>`, {
+        headers: {
+            'Content-Type': 'text/html; charset=utf-8',
+            'Cache-Control': 'no-store',
+            'Content-Security-Policy': "default-src 'none'; frame-ancestors 'self'"
+        }
+    });
+}
 function buildLogger(logger) {
     const noop = () => { };
     if (logger === false)
@@ -366,19 +381,19 @@ export function createOIDC(options) {
                 tokens: normalizeTokens(tokenResponse, defaultScope, session.tokens),
                 refreshedAt: Math.floor(Date.now() / 1000)
             };
-            await options.beforeSessionPersist?.({
+            const persistedSession = (await options.beforeSessionPersist?.({
                 session: nextSession,
                 reason: 'refresh',
                 event,
                 tokenResponse
-            });
-            await writePersistedSession(cookies, nextSession, persisted?.id);
+            })) ?? nextSession;
+            await writePersistedSession(cookies, persistedSession, persisted?.id);
             log.debug('OIDC session tokens refreshed', {
-                expiresAt: nextSession.tokens.expiresAt,
-                refreshExpiresAt: nextSession.tokens.refreshExpiresAt,
-                hasRefreshToken: Boolean(nextSession.tokens.refreshToken)
+                expiresAt: persistedSession.tokens.expiresAt,
+                refreshExpiresAt: persistedSession.tokens.refreshExpiresAt,
+                hasRefreshToken: Boolean(persistedSession.tokens.refreshToken)
             });
-            return nextSession;
+            return persistedSession;
         }
         catch (err) {
             log.error('Token refresh failed — clearing session', err);
@@ -395,11 +410,14 @@ export function createOIDC(options) {
         const state = base64UrlEncode(randomBytes(24));
         const nonce = base64UrlEncode(randomBytes(24));
         const returnTo = internalRedirectPath(event, loginOptions.returnTo ?? options.defaultLoginRedirect, '/');
+        const existingSession = loginOptions.prompt === 'none' ? await readPersistedSession(event.cookies) : null;
         cookieStore.writeState(event.cookies, {
             state,
             nonce,
             codeVerifier: pkce.verifier,
             returnTo,
+            prompt: loginOptions.prompt,
+            originalSub: existingSession?.session.sub,
             createdAt: Math.floor(Date.now() / 1000)
         });
         const redirectUri = absoluteUrl(event, redirectPath);
@@ -418,6 +436,9 @@ export function createOIDC(options) {
         if (loginOptions.prompt) {
             authorizationUrl.searchParams.set('prompt', loginOptions.prompt);
         }
+        if (loginOptions.prompt === 'none' && existingSession?.session.tokens.idToken) {
+            authorizationUrl.searchParams.set('id_token_hint', existingSession.session.tokens.idToken);
+        }
         for (const [key, value] of Object.entries(loginOptions.extraParams ?? {})) {
             authorizationUrl.searchParams.set(key, value);
         }
@@ -448,6 +469,9 @@ export function createOIDC(options) {
             });
         }
         const idTokenClaims = await validateIdToken(tokenResponse.id_token, stateCookie.nonce);
+        if (stateCookie.prompt === 'none' && stateCookie.originalSub && idTokenClaims.sub !== stateCookie.originalSub) {
+            throw error(401, { message: 'Silent re-authentication returned a different End-User' });
+        }
         const userInfo = options.fetchUserInfo === false
             ? undefined
             : await fetchUserInfo(tokenResponse.access_token).catch(() => undefined);
@@ -470,15 +494,16 @@ export function createOIDC(options) {
             createdAt: now,
             refreshedAt: now
         };
-        await options.beforeSessionPersist?.({
+        const persistedSession = (await options.beforeSessionPersist?.({
             session,
             reason: 'login',
             event: event,
             tokenResponse
-        });
-        await writePersistedSession(event.cookies, session);
+        })) ?? session;
+        const existingSession = stateCookie.prompt === 'none' ? await readPersistedSession(event.cookies) : null;
+        await writePersistedSession(event.cookies, persistedSession, existingSession?.id);
         return {
-            session,
+            session: persistedSession,
             returnTo: stateCookie.returnTo
         };
     }
@@ -566,19 +591,36 @@ export function createOIDC(options) {
     function loginHandler(defaults = {}) {
         return async (event) => {
             const returnTo = event.url.searchParams.get('returnTo') ?? defaults.returnTo;
-            return signIn(event, { ...defaults, returnTo });
+            const requestedPrompt = event.url.searchParams.get('prompt');
+            const prompt = requestedPrompt && LOGIN_PROMPTS.has(requestedPrompt)
+                ? requestedPrompt
+                : defaults.prompt;
+            return signIn(event, { ...defaults, returnTo, prompt });
         };
     }
     function callbackHandler(handlerOptions = {}) {
         return async (event) => {
+            const stateCookie = cookieStore.readState(event.cookies);
+            const callbackState = event.url.searchParams.get('state');
+            const isSilentReauthentication = Boolean(stateCookie?.prompt === 'none' && callbackState && callbackState === stateCookie.state);
             try {
                 const result = await handleCallback(event);
+                if (isSilentReauthentication) {
+                    return silentReauthenticationResponse('authenticated');
+                }
                 const response = await handlerOptions.onsuccess?.(event, result);
                 if (response)
                     return response;
                 throw redirect(302, internalRedirectPath(event, handlerOptions.redirectTo ?? result.returnTo, '/'));
             }
             catch (err) {
+                if (isSilentReauthentication) {
+                    cookieStore.clearState(event.cookies);
+                    const persisted = await readPersistedSession(event.cookies);
+                    await clearPersistedSession(event.cookies, persisted?.id);
+                    log.debug('Silent OIDC re-authentication failed — clearing local session');
+                    return silentReauthenticationResponse('logged_out');
+                }
                 const response = await handlerOptions.onfailure?.(event, err);
                 if (response) {
                     return response;

package/dist/server/types.d.ts

@@ -181,13 +181,19 @@ export type OIDCOptions<TIdentity extends OIDCUserClaims = OIDCUserClaims, TRequ
         userInfo?: OIDCUserClaims;
         reason: OIDCSessionReason;
     }) => MaybePromise<TIdentity>;
-    /** Runs immediately before a login or refreshed session is persisted. */
+    /**
+     * Runs immediately before a login or refreshed session is persisted.
+     * Returning a session replaces the one that gets persisted and handed back to the
+     * caller (`handleCallback`'s result, `getSession`'s result); returning `void` keeps it
+     * unchanged. Use this to enrich or provision application data — e.g. upsert a user row —
+     * before the session is written, rather than after via a route's own callback hook.
+     */
     beforeSessionPersist?: (context: {
         session: OIDCSession<TIdentity>;
         reason: OIDCSessionReason;
         event?: MinimalRequestEvent;
         tokenResponse: OIDCTokenResponse;
-    }) => MaybePromise<void>;
+    }) => MaybePromise<OIDCSession<TIdentity> | void>;
     /**
      * Loads application-owned data once for each authenticated request handled by
      * `handle`. The result is exposed as `event.locals.oidc.data` and is never
@@ -244,6 +250,8 @@ export type OIDCStateCookie = {
     nonce: string;
     codeVerifier: string;
     returnTo: string;
+    prompt?: OIDCLoginOptions['prompt'];
+    originalSub?: string;
     createdAt: number;
 };
 export type MinimalRequestEvent = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sourceregistry/sveltekit-oidc",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "description": "OIDC authentication helpers for SvelteKit applications",
   "license": "Apache-2.0",
   "scripts": {
@@ -62,18 +62,18 @@
     "@sveltejs/kit": "^2.63.1",
     "@sveltejs/package": "^2.5.8",
     "@sveltejs/vite-plugin-svelte": "^7.1.2",
-    "@types/node": "^25.9.2",
+    "@types/node": "^26.2.0",
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/git": "^10.0.1",
-    "publint": "^0.3.21",
+    "publint": "^0.3.23",
     "svelte": "^5.56.3",
-    "svelte-check": "^4.6.0",
+    "svelte-check": "^4.7.5",
     "typescript": "^6.0.3",
-    "vite": "^8.0.16",
+    "vite": "^8.2.1",
     "@vitest/coverage-v8": "^4.1.8",
-    "vitest": "^4.1.8",
+    "vitest": "^4.1.10",
     "@sourceregistry/semantic-release-jsr": "^1.1.1",
-    "typedoc": "^0.28.19"
+    "typedoc": "^0.28.20"
   },
   "keywords": [
     "sveltekit",