@sourceregistry/sveltekit-oidc 1.3.0 → 1.4.0

package/README.md

@@ -19,10 +19,7 @@ npm install sveltekit-oidc
 
 ```ts
 // src/lib/server/auth.ts
-import {
-	createInMemoryBackChannelLogoutStore,
-	createOIDC
-} from 'sveltekit-oidc/server';
+import { createOIDC } from 'sveltekit-oidc/server';
 
 export const oidc = createOIDC({
 	issuer: 'https://your-idp.example.com',
@@ -32,22 +29,8 @@ export const oidc = createOIDC({
 	clientAuthMethod: 'client_secret_basic',
 	loginPath: '/auth/login',
 	redirectPath: '/auth/callback',
-	scope: ['openid', 'profile', 'email', 'offline_access'],
-	clockSkewSeconds: 30,
-	fetchUserInfo: true,
-	backChannelLogoutStore: createInMemoryBackChannelLogoutStore(),
-	transformSession(session) {
-		return {
-			...session,
-			groups: session.groups,
-			user: session.user
-				? {
-						...session.user,
-						groups: session.groups
-					}
-				: session.user
-		};
-	},
+	scope: 'openid profile email offline_access',
+	backChannelLogoutStore: 'memory',
 	cookieOptions: {
 		secure: process.env.NODE_ENV === 'production'
 	}
@@ -129,6 +112,7 @@ export async function load(event) {
 	session={data.session}
 	config={data.sessionManagement}
 	logoutPath="/auth/logout"
+	monitorSession={false}
 	redirectIfUnauthenticated={false}
 >
 	<Account />
@@ -160,6 +144,10 @@ export async function load(event) {
 - periodic `invalidateAll()` revalidation so revoked server sessions are detected
 - a client context for nested auth-aware components through `useOIDC()` / `getOIDCContext()`
 
+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.
+
 ## Typed Custom Claims
 
 `createOIDC` infers a `TClaims` type from whatever `transformClaims` / `transformUser` / `transformSession` return, and threads it through the session, `event.locals.oidc`, `OIDCPublicSession`, and the client context — no casts needed.
@@ -178,19 +166,17 @@ export const oidc = createOIDC({
 });
 ```
 
-Extract the inferred type with `OIDCInferClaims` and apply it to `App.Locals` so `event.locals.oidc` is typed everywhere:
+Wire `App.Locals` so `event.locals.oidc` is fully typed everywhere — `OIDCLocals` infers everything directly from the instance:
 
 ```ts
 // src/app.d.ts
-import type { OIDCHandleLocals, OIDCInferClaims } from 'sveltekit-oidc/server';
+import type { OIDCLocals } from 'sveltekit-oidc/server';
 import { oidc } from '$lib/server/auth';
 
-export type AppClaims = OIDCInferClaims<typeof oidc>;
-
 declare global {
 	namespace App {
 		interface Locals {
-			oidc?: OIDCHandleLocals<AppClaims>;
+			oidc?: OIDCLocals<typeof oidc>;
 		}
 	}
 }
@@ -198,7 +184,16 @@ declare global {
 export {};
 ```
 
-Now `event.locals.oidc?.claims?.roles` is `string[]` and `?.tenant` is `string | undefined` in every hook, load function, and action.
+Now `event.locals.oidc?.claims?.roles` is `string[]` and `?.tenant` is `string | undefined` in every hook, load function, and action — no separate type aliases needed.
+
+When you need the claim type explicitly (e.g. in a Svelte component), use `OIDCInferClaims`:
+
+```ts
+import type { OIDCInferClaims } from 'sveltekit-oidc/server';
+import { oidc } from '$lib/server/auth';
+
+type AppClaims = OIDCInferClaims<typeof oidc>;
+```
 
 `OIDCContext` is a generic component, but Svelte doesn't support passing explicit type arguments in markup — `TClaims` is inferred from the `session` prop instead. Since `data.session` comes from `oidc.getPublicSession(event)`, it's already typed `OIDCPublicSession<AppClaims> | null`, so the inference flows through automatically:
 
@@ -256,20 +251,17 @@ export const oidc = createOIDC({
 });
 ```
 
-Extract the inferred type with `OIDCInferSession` and apply it alongside `OIDCInferClaims`:
+`app.d.ts` stays a one-liner — `OIDCLocals` picks up both `TClaims` and `TSession` from the instance:
 
 ```ts
 // src/app.d.ts
-import type { OIDCHandleLocals, OIDCInferClaims, OIDCInferSession } from 'sveltekit-oidc/server';
+import type { OIDCLocals } from 'sveltekit-oidc/server';
 import { oidc } from '$lib/server/auth';
 
-export type AppClaims = OIDCInferClaims<typeof oidc>;
-export type AppSession = OIDCInferSession<typeof oidc>;
-
 declare global {
 	namespace App {
 		interface Locals {
-			oidc?: OIDCHandleLocals<AppClaims, AppSession>;
+			oidc?: OIDCLocals<typeof oidc>;
 		}
 	}
 }
@@ -279,6 +271,16 @@ export {};
 
 Now `event.locals.oidc?.session?.tenantId` is `string` and `?.permissions` is `string[]` everywhere — and `oidc.requireAuth(event)` / `handleCallback`'s `onsuccess` resolve to `AppSession` directly.
 
+Use `OIDCInferClaims` / `OIDCInferSession` when you need the types explicitly:
+
+```ts
+import type { OIDCInferClaims, OIDCInferSession } from 'sveltekit-oidc/server';
+import { oidc } from '$lib/server/auth';
+
+type AppClaims = OIDCInferClaims<typeof oidc>;
+type AppSession = OIDCInferSession<typeof oidc>;
+```
+
 If `transformSession` is omitted, `TSession` defaults to `OIDCSession<TClaims>` — existing setups keep working unchanged.
 
 ## Example App
@@ -302,6 +304,6 @@ Set these environment variables to enable it:
 - The library validates `id_token` and `logout_token` values through `@sourceregistry/node-jwt` and provider JWKS metadata.
 - `groups` are normalized onto the session from `groups` and `roles` claims when present.
 - Use `transformClaims`, `transformUser`, and `transformSession` to project provider-specific claims into your own session shape.
-- `check_session_iframe` monitoring only runs when the provider advertises that endpoint and the session includes `session_state`.
+- `check_session_iframe` monitoring only runs when `monitorSession` is enabled, the provider advertises that endpoint, and the session includes `session_state`.
 - Refresh token handling is automatic when a valid refresh token is present.
-- `event.locals.oidc` is attached by the hook and typed via `OIDCHandleLocals<TClaims>`; see [Typed Custom Claims](#typed-custom-claims) for wiring your own claim shapes through `app.d.ts`.
+- `event.locals.oidc` is attached by the hook; wire it in `app.d.ts` with `OIDCLocals<typeof oidc>` — see [Typed Custom Claims](#typed-custom-claims).

package/dist/client/OIDCContext.svelte

@@ -19,6 +19,7 @@
         loginPath,
         logoutPath = '/auth/logout',
         checkSessionIntervalMs = 5000,
+        monitorSession = true,
         revalidateIntervalMs = 30000,
         redirectOnExpired = 'login',
         redirectOnRevoked = 'login',
@@ -30,6 +31,7 @@
         loginPath?: string;
         logoutPath?: string;
         checkSessionIntervalMs?: number;
+        monitorSession?: boolean;
         revalidateIntervalMs?: number;
         redirectOnExpired?: RedirectMode;
         redirectOnRevoked?: RedirectMode;
@@ -47,7 +49,7 @@
         config.metadata.check_session_iframe ?? config.checkSessionIframe ?? undefined
     );
     const canMonitorIframe = $derived(
-        Boolean(session?.isAuthenticated && session?.sessionState && iframeUrl)
+        Boolean(monitorSession && session?.isAuthenticated && session?.sessionState && iframeUrl)
     );
 
     const context = setOIDCContext<TClaims>({

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

@@ -7,6 +7,7 @@ declare function $$render<TClaims extends OIDCUserClaims = OIDCUserClaims>(): {
         loginPath?: string;
         logoutPath?: string;
         checkSessionIntervalMs?: number;
+        monitorSession?: boolean;
         revalidateIntervalMs?: number;
         redirectOnExpired?: "none" | "login" | "logout" | "reload";
         redirectOnRevoked?: "none" | "login" | "logout" | "reload";

package/dist/server/index.js

@@ -6,7 +6,34 @@ import { asAuthorizationHeader, createClientSecretJwtAssertion, createPrivateKey
 import { normalizeTokens, shouldRefresh } from './session.js';
 import { absoluteUrl, base64UrlEncode, buildCookieOptions, collectGroups, createPKCEPair, normalizeIssuer, normalizeScope, parseProviderError, toPublicSession } from './utils.js';
 export { createInMemoryBackChannelLogoutStore, createInMemorySessionStore } from './store.js';
+import { createInMemoryBackChannelLogoutStore, createInMemorySessionStore } from './store.js';
+function buildLogger(logger) {
+    const noop = () => { };
+    if (logger === false)
+        return { debug: noop, info: noop, warn: noop, error: noop };
+    if (logger)
+        return {
+            debug: (...a) => logger.debug?.(...a),
+            info: (...a) => logger.info?.(...a),
+            warn: (...a) => logger.warn?.(...a),
+            error: (...a) => logger.error?.(...a),
+        };
+    const p = '[sveltekit-oidc]';
+    return {
+        debug: (...a) => console.debug(p, ...a),
+        info: (...a) => console.info(p, ...a),
+        warn: (...a) => console.warn(p, ...a),
+        error: (...a) => console.error(p, ...a),
+    };
+}
 export function createOIDC(options) {
+    const log = buildLogger(options.logger);
+    const sessionStore = options.sessionStore === 'memory'
+        ? createInMemorySessionStore()
+        : options.sessionStore;
+    const backChannelLogoutStore = options.backChannelLogoutStore === 'memory'
+        ? createInMemoryBackChannelLogoutStore()
+        : options.backChannelLogoutStore;
     const cookieOptions = buildCookieOptions(options.cookieOptions);
     const clockSkewSeconds = options.clockSkewSeconds ?? 30;
     const refreshToleranceSeconds = options.refreshToleranceSeconds ?? 30;
@@ -20,7 +47,7 @@ export function createOIDC(options) {
     let metadataPromise;
     let jwksPromise;
     async function readPersistedSession(cookies) {
-        if (!options.sessionStore) {
+        if (!sessionStore) {
             const session = cookieStore.readSession(cookies);
             return session ? { session } : null;
         }
@@ -28,7 +55,7 @@ export function createOIDC(options) {
         if (!reference?.id) {
             return null;
         }
-        const session = await options.sessionStore.get(reference.id);
+        const session = await sessionStore.get(reference.id);
         if (!session) {
             cookieStore.clearSessionReference(cookies);
             return null;
@@ -39,22 +66,22 @@ export function createOIDC(options) {
         };
     }
     async function writePersistedSession(cookies, session, sessionId) {
-        if (!options.sessionStore) {
+        if (!sessionStore) {
             cookieStore.writeSession(cookies, session);
             return;
         }
         const id = sessionId ?? base64UrlEncode(randomBytes(24));
-        await options.sessionStore.set(id, session);
+        await sessionStore.set(id, session);
         cookieStore.writeSessionReference(cookies, { id });
     }
     async function clearPersistedSession(cookies, sessionId) {
-        if (!options.sessionStore) {
+        if (!sessionStore) {
             cookieStore.clearSession(cookies);
             return;
         }
         const id = sessionId ?? cookieStore.readSessionReference(cookies)?.id;
         if (id) {
-            await options.sessionStore.delete(id);
+            await sessionStore.delete(id);
         }
         cookieStore.clearSessionReference(cookies);
     }
@@ -237,10 +264,10 @@ export function createOIDC(options) {
         });
     }
     async function isRevoked(session) {
-        if (!session || !options.backChannelLogoutStore) {
+        if (!session || !backChannelLogoutStore) {
             return false;
         }
-        return options.backChannelLogoutStore.isRevoked(session);
+        return backChannelLogoutStore.isRevoked(session);
     }
     async function maybeRefreshSession(event, persisted) {
         const session = persisted?.session ?? null;
@@ -285,7 +312,8 @@ export function createOIDC(options) {
             await writePersistedSession(event.cookies, finalSession, persisted?.id);
             return finalSession;
         }
-        catch {
+        catch (err) {
+            log.error('Token refresh failed — clearing session', err);
             await clearPersistedSession(event.cookies, persisted?.id);
             return null;
         }
@@ -337,7 +365,8 @@ export function createOIDC(options) {
         const code = event.url.searchParams.get('code');
         if (!stateCookie || !state || !code || stateCookie.state !== state) {
             cookieStore.clearState(event.cookies);
-            throw error(400, { message: 'Invalid or expired OIDC callback state' });
+            log.warn('Invalid or expired callback state — restarting login flow');
+            return signIn(event);
         }
         cookieStore.clearState(event.cookies);
         const tokenResponse = await exchangeCode({
@@ -415,7 +444,7 @@ export function createOIDC(options) {
         if (!metadata.backchannel_logout_supported) {
             throw error(400, { message: 'Provider does not advertise back-channel logout support' });
         }
-        if (!options.backChannelLogoutStore) {
+        if (!backChannelLogoutStore) {
             throw error(500, {
                 message: 'backChannelLogoutStore is required for back-channel logout with cookie sessions'
             });
@@ -426,7 +455,7 @@ export function createOIDC(options) {
             throw error(400, { message: 'logout_token is required' });
         }
         const claims = await validateBackChannelLogoutToken(logoutToken);
-        await options.backChannelLogoutStore.revoke({
+        await backChannelLogoutStore.revoke({
             issuer: claims.iss,
             clientId: options.clientId,
             sid: claims.sid,

package/dist/server/types.d.ts

@@ -133,6 +133,12 @@ export type OIDCSessionManagementConfig = {
     backChannelLogoutSupported: boolean;
     backChannelLogoutSessionSupported: boolean;
 };
+export type OIDCLogger = {
+    debug?: (...args: unknown[]) => void;
+    info?: (...args: unknown[]) => void;
+    warn?: (...args: unknown[]) => void;
+    error?: (...args: unknown[]) => void;
+};
 export type OIDCOptions<TClaims extends OIDCUserClaims = OIDCUserClaims, TSession extends OIDCSession<TClaims> = OIDCSession<TClaims>> = {
     issuer?: string;
     discoveryUrl?: string;
@@ -144,7 +150,7 @@ export type OIDCOptions<TClaims extends OIDCUserClaims = OIDCUserClaims, TSessio
     loginPath?: string;
     redirectPath?: string;
     postLogoutRedirectUri?: string;
-    scope?: string[];
+    scope?: string | string[];
     audience?: string;
     fetchUserInfo?: boolean;
     sessionCookieName?: string;
@@ -155,8 +161,8 @@ export type OIDCOptions<TClaims extends OIDCUserClaims = OIDCUserClaims, TSessio
     refreshToleranceSeconds?: number;
     defaultLoginRedirect?: string;
     defaultLogoutRedirect?: string;
-    sessionStore?: OIDCSessionStore<TClaims, TSession>;
-    backChannelLogoutStore?: OIDCBackChannelLogoutStore<TClaims, TSession>;
+    sessionStore?: OIDCSessionStore<TClaims, TSession> | 'memory';
+    backChannelLogoutStore?: OIDCBackChannelLogoutStore<TClaims, TSession> | 'memory';
     transformClaims?: (claims: OIDCUserClaims) => MaybePromise<TClaims>;
     transformUser?: (user: OIDCUserClaims | undefined, context: {
         claims?: TClaims;
@@ -169,11 +175,12 @@ export type OIDCOptions<TClaims extends OIDCUserClaims = OIDCUserClaims, TSessio
         isRefresh: boolean;
     }) => MaybePromise<TSession>;
     endpoints?: Partial<OIDCDiscoveryDocument>;
+    logger?: OIDCLogger | false;
 };
 export type OIDCLoginOptions = {
     returnTo?: string;
     prompt?: 'login' | 'consent' | 'none' | 'select_account';
-    scope?: string[];
+    scope?: string | string[];
     extraParams?: Record<string, string>;
 };
 export type OIDCLogoutOptions = {
@@ -256,3 +263,4 @@ export type OIDCInstance<TClaims extends OIDCUserClaims = OIDCUserClaims, TSessi
 };
 export type OIDCInferClaims<T> = T extends OIDCInstance<infer TClaims> ? TClaims : OIDCUserClaims;
 export type OIDCInferSession<T> = T extends OIDCInstance<infer _TClaims, infer TSession> ? TSession : OIDCSession<OIDCUserClaims>;
+export type OIDCLocals<T extends OIDCInstance<any, any>> = OIDCHandleLocals<OIDCInferClaims<T>, OIDCInferSession<T>>;

package/dist/server/utils.d.ts

@@ -6,7 +6,7 @@ export declare function createPKCEPair(length?: number): {
     challenge: string;
 };
 export declare function normalizeIssuer(issuer: string): string;
-export declare function normalizeScope(scope?: string[]): string[];
+export declare function normalizeScope(scope?: string | string[]): string[];
 export declare function normalizeStringArray(value: unknown): string[];
 export declare function collectGroups<TClaims extends OIDCUserClaims = OIDCUserClaims>(...sources: Array<TClaims | undefined>): string[];
 export declare function createSignedValue(value: string, secret: string): string;

package/dist/server/utils.js

@@ -13,7 +13,10 @@ export function normalizeIssuer(issuer) {
     return issuer.endsWith('/') ? issuer.slice(0, -1) : issuer;
 }
 export function normalizeScope(scope) {
-    return scope?.length ? [...new Set(scope)] : ['openid', 'profile', 'email'];
+    if (!scope)
+        return ['openid', 'profile', 'email'];
+    const arr = typeof scope === 'string' ? scope.trim().split(/\s+/) : scope;
+    return arr.length ? [...new Set(arr)] : ['openid', 'profile', 'email'];
 }
 export function normalizeStringArray(value) {
     if (!value)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sourceregistry/sveltekit-oidc",
-  "version": "1.3.0",
-  "description": "OIDC authentication helpers for SvelteKit applications.",
+  "version": "1.4.0",
+  "description": "OIDC authentication helpers for SvelteKit applications",
   "license": "Apache-2.0",
   "scripts": {
     "dev": "vite dev",