@sourceregistry/sveltekit-oidc 1.6.13 → 1.7.0

package/README.md

@@ -147,9 +147,19 @@ export async function load(event) {
 
 - local expiry redirects
 - `check_session_iframe` polling when the provider advertises it
-- periodic `invalidateAll()` revalidation so revoked server sessions are detected
+- targeted session revalidation when a token reaches its renewal window
+- optional periodic session revalidation when `revalidateIntervalMs` is explicitly configured
 - a client context for nested auth-aware components through `useOIDC()` / `getOIDCContext()`
 
+`oidc.getPublicSession(event)` automatically registers the `oidc:session` dependency used by
+`OIDCContext`, so the standard setup above does not re-run unrelated page loads. If you destructure
+the load event, pass both `cookies` and `depends`: `oidc.getPublicSession({cookies, depends})`.
+
+Periodic revalidation is disabled by default to avoid unnecessary page updates. Set
+`revalidateIntervalMs` to a positive interval only when you need polling in addition to token-expiry
+and provider session monitoring. Existing integrations that pass only `cookies` remain compatible;
+their expiry-driven revalidation falls back to `invalidateAll()`.
+
 Set `monitorSession={false}` when you want to keep the client context but leave remote session
 revocation checks to your server-side guard or another mechanism. This disables
 `check_session_iframe` polling without changing the provider metadata exposed through the context.

package/dist/client/OIDCContext.svelte

@@ -6,7 +6,7 @@
 </script>
 
 <script lang="ts" generics="TClaims extends OIDCUserClaims = OIDCUserClaims">
-    import {invalidateAll, beforeNavigate} from '$app/navigation';
+    import {beforeNavigate, invalidate, invalidateAll} from '$app/navigation';
     import {tick} from 'svelte';
     import type {Snippet} from 'svelte';
 
@@ -14,18 +14,24 @@
 
     type RedirectMode = 'login' | 'logout' | 'reload' | 'none';
 
+    type OIDCClientDebugEvent = {
+        type: string;
+        details?: Record<string, unknown>;
+    };
+
     let {
         session = null,
         config,
         loginPath,
-        logoutPath = '/auth/logout',
+        logoutPath,
         checkSessionIntervalMs = 5000,
         monitorSession = true,
-        revalidateIntervalMs = 30000,
+        revalidateIntervalMs = 0,
         renewalLeadTimeMs = 5000,
         redirectOnExpired = 'login',
         redirectOnRevoked = 'login',
         redirectIfUnauthenticated = false,
+        onDebug,
         children
     }: {
         session?: OIDCPublicSession<TClaims> | null;
@@ -39,6 +45,8 @@
         redirectOnExpired?: RedirectMode;
         redirectOnRevoked?: RedirectMode;
         redirectIfUnauthenticated?: boolean;
+        /** Receives token-safe lifecycle events for diagnosing session changes. */
+        onDebug?: (event: OIDCClientDebugEvent) => void;
         children?: Snippet;
     } = $props();
 
@@ -48,8 +56,13 @@
     let handledUnauthenticated = $state(false);
     let sessionExpiredDuringRevalidation = false;
 
+    function debug(type: string, details?: Record<string, unknown>) {
+        onDebug?.({type, details});
+    }
+
     const metadata = $derived(config.metadata);
     const resolvedLoginPath = $derived(loginPath ?? config.loginPath ?? '/auth/login');
+    const resolvedLogoutPath = $derived(logoutPath ?? config.logoutPath ?? '/auth/logout');
     const iframeUrl = $derived(
         config.metadata.check_session_iframe ?? config.checkSessionIframe ?? undefined
     );
@@ -73,6 +86,9 @@
         get groups() {
             return session?.groups ?? [];
         },
+        get issuer() {
+            return config.issuer;
+        },
         get metadata() {
             return metadata;
         },
@@ -93,6 +109,7 @@
     // Only intercept login redirects while a background revalidation is active.
     beforeNavigate(({to, cancel}) => {
         if (revalidating && to?.url.pathname.startsWith(resolvedLoginPath)) {
+            debug('revalidation_redirected_to_login', {pathname: to.url.pathname});
             cancel();
             sessionExpiredDuringRevalidation = true;
         }
@@ -104,10 +121,11 @@
 
     async function logout(clearSessionOnly = false) {
         if (clearSessionOnly) {
+            debug('local_session_logout_requested');
             // Session-monitor events must clear only this application's session.
             // Keep the flag in the URL because logoutHandler also supports callers
             // that do not send a form body.
-            const url = new URL(logoutPath, window.location.href);
+            const url = new URL(resolvedLogoutPath, window.location.href);
             url.searchParams.set('clearSessionOnly', '1');
 
             await fetch(url, {
@@ -122,20 +140,25 @@
         // session intact and allowing the app to immediately sign in again.
         const form = document.createElement('form');
         form.method = 'POST';
-        form.action = logoutPath;
+        form.action = resolvedLogoutPath;
         form.style.display = 'none';
         document.body.append(form);
         form.submit();
     }
 
     function login(returnTo?: string) {
+        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().
         window.location.href = buildLoginUrl(returnTo);
     }
 
     async function revalidate() {
-        if (revalidating) return;
+        if (revalidating) {
+            debug('revalidation_skipped_in_flight');
+            return;
+        }
+        debug('revalidation_started', {expiresAt: session?.expiresAt});
         revalidating = true;
 
         // If the server redirects to the login path during a background
@@ -144,14 +167,25 @@
         sessionExpiredDuringRevalidation = false;
 
         try {
-            await invalidateAll();
+            if (session?.revalidationDependency) {
+                debug('revalidation_dependency_invalidated', {
+                    dependency: session.revalidationDependency
+                });
+                await invalidate(session.revalidationDependency);
+            } else {
+                debug('revalidation_fallback_invalidated_all');
+                await invalidateAll();
+            }
         } finally {
             revalidating = false;
         }
 
         if (sessionExpiredDuringRevalidation) {
             status = 'expired';
+            debug('revalidation_session_expired');
             void handleRedirect(redirectOnExpired);
+        } else {
+            debug('revalidation_completed', {isAuthenticated: Boolean(session?.isAuthenticated), expiresAt: session?.expiresAt});
         }
     }
 
@@ -199,6 +233,7 @@
             session.expiresAt * 1000 <= Date.now()
         ) {
             status = 'expired';
+            debug('session_expired_after_failed_renewal', {expiresAt: session.expiresAt});
             void handleRedirect(redirectOnExpired);
             return;
         }
@@ -208,6 +243,7 @@
         const leadTimeMs = renewalAttemptedForExpiresAt === expiresAt ? 0 : renewalLeadTimeMs;
         const timeoutMs = Math.max(0, expiresAt * 1000 - Date.now() - leadTimeMs);
         const timer = window.setTimeout(async () => {
+            debug('token_renewal_due', {expiresAt});
             // Silent revalidate first — server's maybeRefreshSession will refresh
             // the token if a valid refresh_token exists. Only redirect if the
             // session comes back unauthenticated after that.
@@ -216,6 +252,7 @@
             await tick();
             if (!session?.isAuthenticated) {
                 status = 'expired';
+                debug('token_renewal_left_session_unauthenticated');
                 void handleRedirect(redirectOnExpired);
             }
         }, timeoutMs);
@@ -268,6 +305,7 @@
                 return;
             }
             if (event.data === 'changed' || event.data === 'error') {
+                debug('iframe_session_event', {result: event.data, origin: event.origin});
                 status = 'revoked';
                 void logout(true).then(() => handleRedirect(redirectOnRevoked));
             }

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

@@ -13,6 +13,11 @@ declare function $$render<TClaims extends OIDCUserClaims = OIDCUserClaims>(): {
         redirectOnExpired?: "none" | "login" | "logout" | "reload";
         redirectOnRevoked?: "none" | "login" | "logout" | "reload";
         redirectIfUnauthenticated?: boolean;
+        /** Receives token-safe lifecycle events for diagnosing session changes. */
+        onDebug?: (event: {
+            type: string;
+            details?: Record<string, unknown>;
+        }) => void;
         children?: Snippet;
     };
     exports: {};

package/dist/client/context.d.ts

@@ -8,6 +8,7 @@ export type OIDCClientContextValue<TClaims extends OIDCUserClaims = OIDCUserClai
     user: OIDCPublicSession<TClaims>['user'];
     claims: OIDCPublicSession<TClaims>['claims'];
     groups: OIDCPublicSession<TClaims>['groups'];
+    issuer: string;
     metadata?: Pick<OIDCDiscoveryDocument, 'issuer' | 'check_session_iframe' | 'end_session_endpoint' | 'backchannel_logout_supported' | 'backchannel_logout_session_supported'>;
     status: 'authenticated' | 'unauthenticated' | 'expired' | 'revoked';
     revalidating: boolean;

package/dist/server/index.js

@@ -7,6 +7,7 @@ import { isSessionExpired, normalizeTokens, shouldRefresh } from './session.js';
 import { absoluteUrl, base64UrlEncode, buildCookieOptions, collectGroups, createPKCEPair, internalRedirectPath, normalizeIssuer, normalizeScope, parseProviderError, toPublicSession, validateIdTokenClaims, validateUserInfoSubject } from './utils.js';
 import { createInMemoryBackChannelLogoutStore, createInMemorySessionStore } from './store.js';
 export { createInMemoryBackChannelLogoutStore, createInMemorySessionStore } from './store.js';
+const OIDC_SESSION_REVALIDATION_DEPENDENCY = 'oidc:session';
 function buildLogger(logger) {
     const noop = () => {
     };
@@ -46,6 +47,7 @@ export function createOIDC(options) {
     const stateCookieName = options.stateCookieName ?? 'oidc_auth_state';
     const defaultScope = normalizeScope(options.scope);
     const loginPath = options.loginPath ?? '/auth/login';
+    const logoutPath = options.logoutPath ?? '/auth/logout';
     const redirectPath = options.redirectPath ?? '/auth/callback';
     const clientAuthMethod = options.clientAuthMethod ?? (options.clientSecret ? 'client_secret_basic' : 'none');
     const fetchImpl = options.fetch ?? fetch;
@@ -59,10 +61,12 @@ export function createOIDC(options) {
         }
         const reference = cookieStore.readSessionReference(cookies);
         if (!reference?.id) {
+            log.debug('No OIDC session reference cookie is present');
             return null;
         }
         const session = await sessionStore.get(reference.id);
         if (!session) {
+            log.debug('OIDC session reference has no matching persisted session');
             cookieStore.clearSessionReference(cookies);
             return null;
         }
@@ -278,10 +282,24 @@ export function createOIDC(options) {
             return null;
         }
         if (isSessionExpired(session, sessionMaxAgeSeconds)) {
+            const now = Math.floor(Date.now() / 1000);
+            log.debug('OIDC session expired — clearing session', {
+                reason: session.createdAt + sessionMaxAgeSeconds <= now
+                    ? 'session_max_age'
+                    : 'access_token_expired_without_refresh_token',
+                createdAt: session.createdAt,
+                expiresAt: session.tokens.expiresAt,
+                refreshExpiresAt: session.tokens.refreshExpiresAt,
+                hasRefreshToken: Boolean(session.tokens.refreshToken)
+            });
             await clearPersistedSession(cookies, persisted?.id);
             return null;
         }
         if (await isRevoked(session)) {
+            log.debug('OIDC session was revoked by back-channel logout — clearing session', {
+                hasSid: Boolean(session.sid),
+                hasSubject: Boolean(session.sub)
+            });
             await clearPersistedSession(cookies, persisted?.id);
             return null;
         }
@@ -289,6 +307,10 @@ export function createOIDC(options) {
             return session;
         }
         try {
+            log.debug('Refreshing OIDC session tokens', {
+                expiresAt: session.tokens.expiresAt,
+                refreshExpiresAt: session.tokens.refreshExpiresAt
+            });
             const tokenResponse = await refreshTokens(session.tokens.refreshToken);
             const claims = tokenResponse.id_token
                 ? await validateIdToken(tokenResponse.id_token, session.nonce)
@@ -320,6 +342,11 @@ export function createOIDC(options) {
                 })
                 : nextSession;
             await writePersistedSession(cookies, finalSession, persisted?.id);
+            log.debug('OIDC session tokens refreshed', {
+                expiresAt: finalSession.tokens.expiresAt,
+                refreshExpiresAt: finalSession.tokens.refreshExpiresAt,
+                hasRefreshToken: Boolean(finalSession.tokens.refreshToken)
+            });
             return finalSession;
         }
         catch (err) {
@@ -329,7 +356,11 @@ export function createOIDC(options) {
         }
     }
     async function getSession(event) {
-        return maybeRefreshSession(event.cookies, await readPersistedSession(event.cookies));
+        const session = await maybeRefreshSession(event.cookies, await readPersistedSession(event.cookies));
+        if (!session || !options.enrichSession) {
+            return session;
+        }
+        return options.enrichSession(session, { event: event });
     }
     async function signIn(event, loginOptions = {}) {
         const metadata = await getMetadata();
@@ -440,6 +471,9 @@ export function createOIDC(options) {
         if (session?.tokens.idToken) {
             url.searchParams.set('id_token_hint', session.tokens.idToken);
         }
+        // The provider needs client context to validate the post-logout URI
+        // even when the local session (and therefore id_token_hint) is gone.
+        url.searchParams.set('client_id', options.clientId);
         url.searchParams.set('post_logout_redirect_uri', absoluteUrl(event, postLogoutRedirectPath));
         if (logoutOptions.state) {
             url.searchParams.set('state', logoutOptions.state);
@@ -530,9 +564,6 @@ export function createOIDC(options) {
     }
     function logoutHandler(defaults = {}) {
         return async (event) => {
-            if (event.request.method !== 'POST') {
-                throw error(405, { message: 'Logout requires POST' });
-            }
             const form = await event.request.formData().catch(() => null);
             const postLogoutRedirectUri = event.url.searchParams.get('postLogoutRedirectUri') ??
                 form?.get('postLogoutRedirectUri')?.toString() ??
@@ -570,7 +601,9 @@ export function createOIDC(options) {
         const metadata = await getMetadata();
         return {
             clientId: options.clientId,
+            issuer: metadata.issuer,
             loginPath,
+            logoutPath,
             redirectPath,
             metadata: {
                 issuer: metadata.issuer,
@@ -590,7 +623,13 @@ export function createOIDC(options) {
         hook,
         getMetadata,
         getSession,
-        getPublicSession: async (event) => toPublicSession(await getSession(event)),
+        getPublicSession: async (event) => {
+            event.depends?.(OIDC_SESSION_REVALIDATION_DEPENDENCY);
+            const session = toPublicSession(await getSession(event));
+            return session && event.depends
+                ? { ...session, revalidationDependency: OIDC_SESSION_REVALIDATION_DEPENDENCY }
+                : session;
+        },
         getSessionManagementConfig,
         login: signIn,
         logout: signOut,

package/dist/server/types.d.ts

@@ -82,6 +82,8 @@ export type OIDCPublicSession<TClaims extends OIDCUserClaims = OIDCUserClaims> =
     sessionState?: string;
     sid?: string;
     sub?: string;
+    /** SvelteKit dependency registered by getPublicSession for targeted client revalidation. */
+    revalidationDependency?: string;
 };
 export type OIDCBackChannelLogoutClaims = Record<string, unknown> & {
     iss: string;
@@ -126,7 +128,9 @@ export type OIDCSessionStore<TClaims extends OIDCUserClaims = OIDCUserClaims, TS
 };
 export type OIDCSessionManagementConfig = {
     clientId: string;
+    issuer: string;
     loginPath: string;
+    logoutPath: string;
     redirectPath: string;
     metadata: Pick<OIDCDiscoveryDocument, 'issuer' | 'check_session_iframe' | 'end_session_endpoint' | 'backchannel_logout_supported' | 'backchannel_logout_session_supported'>;
     checkSessionIframe?: string;
@@ -149,6 +153,7 @@ export type OIDCOptions<TClaims extends OIDCUserClaims = OIDCUserClaims, TSessio
     clientSecretJwt?: OIDCClientSecretJwtOptions;
     privateKeyJwt?: OIDCPrivateKeyJwtOptions;
     loginPath?: string;
+    logoutPath?: string;
     redirectPath?: string;
     postLogoutRedirectUri?: string;
     scope?: string | string[];
@@ -177,6 +182,18 @@ export type OIDCOptions<TClaims extends OIDCUserClaims = OIDCUserClaims, TSessio
         user?: TClaims;
         isRefresh: boolean;
     }) => MaybePromise<TSession>;
+    /**
+     * Runs on every `getSession` read (and therefore every `getPublicSession`,
+     * `hook()`-provided `requireAuth`, and the instance-level `requireAuth`) —
+     * unlike `transformSession`, which only fires on session creation and token
+     * refresh. Use this to keep data your app owns outside the token (e.g. roles
+     * or memberships stored in your own database) fresh without waiting for a
+     * refresh. Only invoked when a session is present; the result is not persisted
+     * back to the session store.
+     */
+    enrichSession?: (session: TSession, context: {
+        event?: MinimalRequestEvent;
+    }) => MaybePromise<TSession>;
     endpoints?: Partial<OIDCDiscoveryDocument>;
     logger?: OIDCLogger | false;
     /**
@@ -271,6 +288,7 @@ export type OIDCInstance<TClaims extends OIDCUserClaims = OIDCUserClaims, TSessi
     }) => Promise<TSession | null>;
     getPublicSession: (event: {
         cookies: Cookies;
+        depends?: (dependency: string) => void;
     }) => Promise<OIDCPublicSession<TClaims> | null>;
     getSessionManagementConfig: () => Promise<OIDCSessionManagementConfig>;
     login: (event: MinimalRequestEvent, loginOptions?: OIDCLoginOptions) => Promise<never>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sourceregistry/sveltekit-oidc",
-  "version": "1.6.13",
+  "version": "1.7.0",
   "description": "OIDC authentication helpers for SvelteKit applications",
   "license": "Apache-2.0",
   "scripts": {