@sourceregistry/sveltekit-oidc 1.3.1 → 1.5.0

package/README.md

@@ -12,17 +12,14 @@ OIDC authentication helpers for SvelteKit with:
 ## Install
 
 ```sh
-npm install sveltekit-oidc
+npm install @sourceregistry/sveltekit-oidc
 ```
 
 ## Server Setup
 
 ```ts
 // src/lib/server/auth.ts
-import {
-	createInMemoryBackChannelLogoutStore,
-	createOIDC
-} from 'sveltekit-oidc/server';
+import { createOIDC } from '@sourceregistry/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'
 	}
@@ -121,7 +104,7 @@ export async function load(event) {
 
 ```html
 <script lang="ts">
-	import { OIDCContext } from 'sveltekit-oidc';
+	import { OIDCContext } from '@sourceregistry/sveltekit-oidc';
 	let { data } = $props();
 </script>
 
@@ -139,7 +122,7 @@ export async function load(event) {
 ```html
 <!-- src/lib/Account.svelte -->
 <script lang="ts">
-	import { useOIDC } from 'sveltekit-oidc';
+	import { useOIDC } from '@sourceregistry/sveltekit-oidc';
 
 	const oidc = useOIDC();
 </script>
@@ -183,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 '@sourceregistry/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>;
 		}
 	}
 }
@@ -203,14 +184,14 @@ 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.
 
-`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:
+`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)`, the type flows through automatically:
 
 ```html
 <!-- src/routes/+layout.svelte -->
 <script lang="ts">
-	import { OIDCContext } from 'sveltekit-oidc';
+	import { OIDCContext } from '@sourceregistry/sveltekit-oidc';
 	let { data, children } = $props();
 </script>
 
@@ -222,14 +203,13 @@ Now `event.locals.oidc?.claims?.roles` is `string[]` and `?.tenant` is `string |
 ```html
 <!-- src/lib/Account.svelte -->
 <script lang="ts">
-	import { useOIDC } from 'sveltekit-oidc';
-	import type { AppClaims } from '../../app.d.ts';
+	import { useOIDC } from '@sourceregistry/sveltekit-oidc';
 
-	const oidc = useOIDC<AppClaims>();
+	const auth = useOIDC(); // TClaims inferred from App.Locals.oidc
 </script>
 
-{#if oidc.isAuthenticated}
-	<p>Roles: {oidc.claims?.roles.join(', ')}</p>
+{#if auth.isAuthenticated}
+	<p>Roles: {auth.claims?.roles.join(', ')}</p>
 {/if}
 ```
 
@@ -241,8 +221,9 @@ Backend apps commonly stash application-specific data on the session itself (e.g
 
 ```ts
 // src/lib/server/auth.ts
-import { createOIDC, type OIDCSession } from 'sveltekit-oidc/server';
+import { createOIDC, type OIDCSession, type OIDCUserClaims } from '@sourceregistry/sveltekit-oidc/server';
 
+type AppClaims = OIDCUserClaims & { tenant?: string };
 type AppSession = OIDCSession<AppClaims> & {
 	tenantId: string;
 	permissions: string[];
@@ -261,20 +242,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 '@sourceregistry/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>;
 		}
 	}
 }
@@ -284,6 +262,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 in non-Svelte code (utility functions, API helpers, etc.):
+
+```ts
+import type { OIDCInferClaims, OIDCInferSession } from '@sourceregistry/sveltekit-oidc/server';
+import type { 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
@@ -309,4 +297,4 @@ Set these environment variables to enable it:
 - Use `transformClaims`, `transformUser`, and `transformSession` to project provider-specific claims into your own session shape.
 - `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/context.d.ts

@@ -1,4 +1,7 @@
-import type { OIDCDiscoveryDocument, OIDCPublicSession, OIDCUserClaims } from '../server/index.js';
+import type { OIDCDiscoveryDocument, OIDCHandleLocals, OIDCPublicSession, OIDCUserClaims } from '../server/index.js';
+type LocalsClaims = App.Locals extends {
+    oidc?: OIDCHandleLocals<infer C, any>;
+} ? C : OIDCUserClaims;
 export type OIDCClientContextValue<TClaims extends OIDCUserClaims = OIDCUserClaims> = {
     isAuthenticated: boolean;
     session: OIDCPublicSession<TClaims> | null;
@@ -12,5 +15,6 @@ export type OIDCClientContextValue<TClaims extends OIDCUserClaims = OIDCUserClai
     revalidate: () => Promise<void>;
 };
 export declare function setOIDCContext<TClaims extends OIDCUserClaims = OIDCUserClaims>(value: OIDCClientContextValue<TClaims>): OIDCClientContextValue<TClaims>;
-export declare function getOIDCContext<TClaims extends OIDCUserClaims = OIDCUserClaims>(): OIDCClientContextValue<TClaims>;
-export declare function useOIDC<TClaims extends OIDCUserClaims = OIDCUserClaims>(): OIDCClientContextValue<TClaims>;
+export declare function getOIDCContext<TClaims extends OIDCUserClaims = LocalsClaims>(): OIDCClientContextValue<TClaims>;
+export declare function useOIDC<TClaims extends OIDCUserClaims = LocalsClaims>(): OIDCClientContextValue<TClaims>;
+export {};

package/dist/client/index.d.ts

@@ -1,3 +1,3 @@
 export { default as OIDCContext } from './OIDCContext.svelte';
 export { getOIDCContext, useOIDC } from './context.js';
-export type { OIDCPublicSession, OIDCSessionManagementConfig, OIDCUserClaims } from '../server/index.js';
+export type { OIDCInferClaims, OIDCInferSession, OIDCLocals, OIDCPublicSession, OIDCSessionManagementConfig, OIDCUserClaims } from '../server/index.js';

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,6 +1,6 @@
 {
   "name": "@sourceregistry/sveltekit-oidc",
-  "version": "1.3.1",
+  "version": "1.5.0",
   "description": "OIDC authentication helpers for SvelteKit applications",
   "license": "Apache-2.0",
   "scripts": {