@sourceregistry/sveltekit-oidc 2.0.2 → 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)`

package/dist/server/index.js

@@ -381,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);
@@ -494,16 +494,16 @@ export function createOIDC(options) {
             createdAt: now,
             refreshedAt: now
         };
-        await options.beforeSessionPersist?.({
+        const persistedSession = (await options.beforeSessionPersist?.({
             session,
             reason: 'login',
             event: event,
             tokenResponse
-        });
+        })) ?? session;
         const existingSession = stateCookie.prompt === 'none' ? await readPersistedSession(event.cookies) : null;
-        await writePersistedSession(event.cookies, session, existingSession?.id);
+        await writePersistedSession(event.cookies, persistedSession, existingSession?.id);
         return {
-            session,
+            session: persistedSession,
             returnTo: stateCookie.returnTo
         };
     }

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sourceregistry/sveltekit-oidc",
-  "version": "2.0.2",
+  "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",