@sourceregistry/sveltekit-oidc 1.8.0 → 2.0.0

package/dist/server/types.d.ts

@@ -57,7 +57,8 @@ export type OIDCUserClaims = Record<string, unknown> & {
     nbf?: number;
     nonce?: string;
 };
-export type OIDCSession<TClaims extends OIDCUserClaims = OIDCUserClaims> = {
+export type OIDCSessionReason = 'login' | 'refresh';
+export type OIDCSession<TIdentity extends OIDCUserClaims = OIDCUserClaims> = {
     issuer: string;
     clientId: string;
     nonce?: string;
@@ -65,16 +66,19 @@ export type OIDCSession<TClaims extends OIDCUserClaims = OIDCUserClaims> = {
     sid?: string;
     sessionState?: string;
     groups: string[];
-    user?: TClaims;
-    claims?: TClaims;
+    /** Validated claims from the ID token. */
+    idTokenClaims: OIDCUserClaims;
+    /** Raw response from the UserInfo endpoint, when requested. */
+    userInfo?: OIDCUserClaims;
+    /** Application-facing identity resolved from the validated provider data. */
+    identity: TIdentity;
     tokens: OIDCSessionTokens;
     createdAt: number;
     refreshedAt: number;
 };
-export type OIDCPublicSession<TClaims extends OIDCUserClaims = OIDCUserClaims> = {
+export type OIDCPublicSession<TIdentity extends OIDCUserClaims = OIDCUserClaims> = {
     isAuthenticated: boolean;
-    user?: TClaims;
-    claims?: TClaims;
+    identity: TIdentity;
     groups: string[];
     scope: string[];
     expiresAt?: number;
@@ -82,7 +86,7 @@ export type OIDCPublicSession<TClaims extends OIDCUserClaims = OIDCUserClaims> =
     sessionState?: string;
     sid?: string;
     sub?: string;
-    /** SvelteKit dependency registered by getPublicSession for targeted client revalidation. */
+    /** SvelteKit dependency registered during public projection for targeted client revalidation. */
     revalidationDependency?: string;
 };
 export type OIDCBackChannelLogoutClaims = Record<string, unknown> & {
@@ -117,13 +121,13 @@ export type OIDCBackChannelLogoutRecord = {
     jti: string;
     iat: number;
 };
-export type OIDCBackChannelLogoutStore<TClaims extends OIDCUserClaims = OIDCUserClaims, TSession extends OIDCSession<TClaims> = OIDCSession<TClaims>> = {
+export type OIDCBackChannelLogoutStore<TIdentity extends OIDCUserClaims = OIDCUserClaims> = {
     revoke(record: OIDCBackChannelLogoutRecord): MaybePromise<void>;
-    isRevoked(session: TSession): MaybePromise<boolean>;
+    isRevoked(session: OIDCSession<TIdentity>): MaybePromise<boolean>;
 };
-export type OIDCSessionStore<TClaims extends OIDCUserClaims = OIDCUserClaims, TSession extends OIDCSession<TClaims> = OIDCSession<TClaims>> = {
-    get(sessionId: string): MaybePromise<TSession | null>;
-    set(sessionId: string, session: TSession): MaybePromise<void>;
+export type OIDCSessionStore<TIdentity extends OIDCUserClaims = OIDCUserClaims> = {
+    get(sessionId: string): MaybePromise<OIDCSession<TIdentity> | null>;
+    set(sessionId: string, session: OIDCSession<TIdentity>): MaybePromise<void>;
     delete(sessionId: string): MaybePromise<void>;
 };
 export type OIDCSessionManagementConfig = {
@@ -144,7 +148,7 @@ export type OIDCLogger = {
     warn?: (...args: unknown[]) => void;
     error?: (...args: unknown[]) => void;
 };
-export type OIDCOptions<TClaims extends OIDCUserClaims = OIDCUserClaims, TSession extends OIDCSession<TClaims> = OIDCSession<TClaims>> = {
+export type OIDCOptions<TIdentity extends OIDCUserClaims = OIDCUserClaims, TRequestData = undefined> = {
     issuer?: string;
     discoveryUrl?: string;
     clientId: string;
@@ -169,31 +173,39 @@ export type OIDCOptions<TClaims extends OIDCUserClaims = OIDCUserClaims, TSessio
     sessionMaxAgeSeconds?: number;
     defaultLoginRedirect?: string;
     defaultLogoutRedirect?: string;
-    sessionStore?: OIDCSessionStore<TClaims, TSession> | 'memory';
-    backChannelLogoutStore?: OIDCBackChannelLogoutStore<TClaims, TSession> | 'memory';
-    transformClaims?: (claims: OIDCUserClaims) => MaybePromise<TClaims>;
-    transformUser?: (user: OIDCUserClaims | undefined, context: {
-        claims?: TClaims;
-    }) => MaybePromise<TClaims | undefined>;
-    transformSession?: (session: OIDCSession<TClaims>, context: {
+    sessionStore?: OIDCSessionStore<TIdentity> | 'memory';
+    backChannelLogoutStore?: OIDCBackChannelLogoutStore<TIdentity> | 'memory';
+    /** Resolves application identity after provider data validation on login and refresh. */
+    resolveIdentity?: (context: {
+        idTokenClaims: OIDCUserClaims;
+        userInfo?: OIDCUserClaims;
+        reason: OIDCSessionReason;
+    }) => MaybePromise<TIdentity>;
+    /** Runs immediately before a login or refreshed session is persisted. */
+    beforeSessionPersist?: (context: {
+        session: OIDCSession<TIdentity>;
+        reason: OIDCSessionReason;
         event?: MinimalRequestEvent;
-        tokenResponse?: OIDCTokenResponse;
-        claims?: TClaims;
-        user?: TClaims;
-        isRefresh: boolean;
-    }) => MaybePromise<TSession>;
+        tokenResponse: OIDCTokenResponse;
+    }) => MaybePromise<void>;
     /**
-     * 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.
+     * Loads application-owned data once for each authenticated request handled by
+     * `handle`. The result is exposed as `event.locals.oidc.data` and is never
+     * persisted in the OIDC session.
      */
-    enrichSession?: (session: TSession, context: {
-        event?: MinimalRequestEvent;
-    }) => MaybePromise<TSession>;
+    loadRequestData?: (context: {
+        session: OIDCSession<TIdentity>;
+        event: MinimalRequestEvent;
+    }) => MaybePromise<TRequestData>;
+    /**
+     * Creates the browser-safe session from persisted authentication and
+     * request-only application data. Runs only when a public session is requested.
+     */
+    createPublicSession?: (context: {
+        session: OIDCSession<TIdentity>;
+        data: TRequestData | null;
+        base: OIDCPublicSession<TIdentity>;
+    }) => OIDCPublicSession<TIdentity>;
     endpoints?: Partial<OIDCDiscoveryDocument>;
     logger?: OIDCLogger | false;
     /**
@@ -215,16 +227,16 @@ export type OIDCLogoutOptions = {
     state?: string;
     clearSessionOnly?: boolean;
 };
-export type OIDCCallbackResult<TClaims extends OIDCUserClaims = OIDCUserClaims, TSession extends OIDCSession<TClaims> = OIDCSession<TClaims>> = {
-    session: TSession;
+export type OIDCCallbackResult<TIdentity extends OIDCUserClaims = OIDCUserClaims> = {
+    session: OIDCSession<TIdentity>;
     returnTo: string;
 };
-export type OIDCHandleLocals<TClaims extends OIDCUserClaims = OIDCUserClaims, TSession extends OIDCSession<TClaims> = OIDCSession<TClaims>> = {
+export type OIDCHandleLocals<TIdentity extends OIDCUserClaims = OIDCUserClaims, TRequestData = undefined> = {
     isAuthenticated: boolean;
-    session: TSession | null;
-    user?: TClaims;
-    claims?: TClaims;
-    requireAuth: () => Promise<TSession>;
+    session: OIDCSession<TIdentity> | null;
+    identity?: TIdentity;
+    data: TRequestData | null;
+    requireAuth: () => Promise<OIDCSession<TIdentity>>;
     clearSession: () => Promise<void>;
 };
 export type OIDCStateCookie = {
@@ -241,8 +253,8 @@ export type MinimalRequestEvent = {
     locals: App.Locals;
 };
 export type MinimalRequestHandler<T extends MinimalRequestEvent> = (event: T) => MaybePromise<Response>;
-export type OIDCCallbackHandlerOptions<TClaims extends OIDCUserClaims = OIDCUserClaims, TSession extends OIDCSession<TClaims> = OIDCSession<TClaims>> = {
-    onsuccess?: <T extends MinimalRequestEvent = RequestEvent>(event: T, result: OIDCCallbackResult<TClaims, TSession>) => MaybePromise<Response | void>;
+export type OIDCCallbackHandlerOptions<TIdentity extends OIDCUserClaims = OIDCUserClaims> = {
+    onsuccess?: <T extends MinimalRequestEvent = RequestEvent>(event: T, result: OIDCCallbackResult<TIdentity>) => MaybePromise<Response | void>;
     onfailure?: <T extends MinimalRequestEvent = RequestEvent>(event: T, err: unknown) => MaybePromise<Response | void>;
     redirectTo?: string;
 };
@@ -255,9 +267,9 @@ export type OIDCClientAssertionOptions = {
     clientId: string;
     clientSecret?: string;
 };
-export type OIDCCookies<TClaims extends OIDCUserClaims = OIDCUserClaims, TSession extends OIDCSession<TClaims> = OIDCSession<TClaims>> = {
-    readSession(cookies: Cookies): TSession | null;
-    writeSession(cookies: Cookies, session: TSession): void;
+export type OIDCCookies<TIdentity extends OIDCUserClaims = OIDCUserClaims> = {
+    readSession(cookies: Cookies): OIDCSession<TIdentity> | null;
+    writeSession(cookies: Cookies, session: OIDCSession<TIdentity>): void;
     clearSession(cookies: Cookies): void;
     readSessionReference(cookies: Cookies): {
         id: string;
@@ -270,35 +282,29 @@ export type OIDCCookies<TClaims extends OIDCUserClaims = OIDCUserClaims, TSessio
     writeState(cookies: Cookies, state: OIDCStateCookie): void;
     clearState(cookies: Cookies): void;
 };
-export type OIDCPersistedSession<TClaims extends OIDCUserClaims = OIDCUserClaims, TSession extends OIDCSession<TClaims> = OIDCSession<TClaims>> = {
+export type OIDCPersistedSession<TIdentity extends OIDCUserClaims = OIDCUserClaims> = {
     id?: string;
-    session: TSession;
+    session: OIDCSession<TIdentity>;
 };
-export type OIDCInstance<TClaims extends OIDCUserClaims = OIDCUserClaims, TSession extends OIDCSession<TClaims> = OIDCSession<TClaims>> = {
+export type OIDCInstance<TIdentity extends OIDCUserClaims = OIDCUserClaims, TRequestData = undefined> = {
     handle: Handle;
-    hook: (event: {
-        cookies: Cookies;
-        locals: App.Locals;
-    }) => Promise<{
-        oidc: OIDCHandleLocals<TClaims, TSession>;
-    }>;
+    createRequestContext: (event: MinimalRequestEvent) => Promise<OIDCHandleLocals<TIdentity, TRequestData>>;
     getMetadata: () => Promise<OIDCDiscoveryDocument>;
     getSession: (event: {
         cookies: Cookies;
-    }) => Promise<TSession | null>;
-    getPublicSession: (event: {
-        cookies: Cookies;
+    }) => Promise<OIDCSession<TIdentity> | null>;
+    getPublicSession: (event: MinimalRequestEvent & {
         depends?: (dependency: string) => void;
-    }) => Promise<OIDCPublicSession<TClaims> | null>;
-    /** Projects an already-loaded session without reading, refreshing, or enriching it again. */
-    toPublicSession: (session: TSession | null, depends?: (dependency: string) => void) => OIDCPublicSession<TClaims> | null;
+    }) => Promise<OIDCPublicSession<TIdentity> | null>;
+    /** Projects an already-loaded request context without repeating any server work. */
+    toPublicSession: (context: OIDCHandleLocals<TIdentity, TRequestData> | null | undefined, depends?: (dependency: string) => void) => OIDCPublicSession<TIdentity> | null;
     getSessionManagementConfig: () => Promise<OIDCSessionManagementConfig>;
     login: (event: MinimalRequestEvent, loginOptions?: OIDCLoginOptions) => Promise<never>;
     logout: (event: MinimalRequestEvent, logoutOptions?: OIDCLogoutOptions) => Promise<never>;
-    handleCallback: (event: MinimalRequestEvent) => Promise<OIDCCallbackResult<TClaims, TSession>>;
+    handleCallback: (event: MinimalRequestEvent) => Promise<OIDCCallbackResult<TIdentity>>;
     handleBackChannelLogout: (event: MinimalRequestEvent) => Promise<Response>;
     loginHandler: <T extends MinimalRequestEvent = RequestEvent>(defaults?: OIDCLoginOptions) => MinimalRequestHandler<T>;
-    callbackHandler: <T extends MinimalRequestEvent = RequestEvent>(handlerOptions?: OIDCCallbackHandlerOptions<TClaims, TSession>) => MinimalRequestHandler<T>;
+    callbackHandler: <T extends MinimalRequestEvent = RequestEvent>(handlerOptions?: OIDCCallbackHandlerOptions<TIdentity>) => MinimalRequestHandler<T>;
     logoutHandler: <T extends MinimalRequestEvent = RequestEvent>(defaults?: OIDCLogoutOptions) => MinimalRequestHandler<T>;
     backChannelLogoutHandler: <T extends MinimalRequestEvent = RequestEvent>() => MinimalRequestHandler<T>;
     createActions: (actionOptions?: OIDCActionOptions) => Readonly<{
@@ -308,9 +314,10 @@ export type OIDCInstance<TClaims extends OIDCUserClaims = OIDCUserClaims, TSessi
     requireAuth: (event: {
         cookies: Cookies;
         url: URL;
-    }, returnTo?: string) => Promise<TSession>;
+    }, returnTo?: string) => Promise<OIDCSession<TIdentity>>;
     clearSession: (cookies: Cookies) => Promise<void>;
 };
-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>>;
+export type OIDCInferIdentity<T> = T extends OIDCInstance<infer TIdentity, any> ? TIdentity : OIDCUserClaims;
+export type OIDCInferRequestData<T> = T extends OIDCInstance<any, infer TRequestData> ? TRequestData : undefined;
+export type OIDCInferSession<T> = OIDCSession<OIDCInferIdentity<T>>;
+export type OIDCLocals<T extends OIDCInstance<any, any>> = OIDCHandleLocals<OIDCInferIdentity<T>, OIDCInferRequestData<T>>;

package/dist/server/utils.d.ts

@@ -24,4 +24,4 @@ export declare function internalRedirectPath(event: {
 }, pathOrUrl: string | undefined, fallback?: string): string;
 export declare function validateIdTokenClaims(claims: OIDCUserClaims, nonce: string): void;
 export declare function validateUserInfoSubject(claims: OIDCUserClaims, user: OIDCUserClaims | undefined): void;
-export declare function toPublicSession<TClaims extends OIDCUserClaims = OIDCUserClaims>(session: OIDCSession<TClaims> | null): OIDCPublicSession<TClaims> | null;
+export declare function toPublicSession<TIdentity extends OIDCUserClaims = OIDCUserClaims>(session: OIDCSession<TIdentity> | null): OIDCPublicSession<TIdentity> | null;

package/dist/server/utils.js

@@ -57,10 +57,7 @@ function cookieEncryptionKey(secret) {
 export function serializeSignedCookie(payload, secret) {
     const iv = randomBytes(12);
     const cipher = createCipheriv('aes-256-gcm', cookieEncryptionKey(secret), iv);
-    const ciphertext = Buffer.concat([
-        cipher.update(JSON.stringify(payload), 'utf8'),
-        cipher.final()
-    ]);
+    const ciphertext = Buffer.concat([cipher.update(JSON.stringify(payload), 'utf8'), cipher.final()]);
     const tag = cipher.getAuthTag();
     return `v2.${iv.toString('base64url')}.${tag.toString('base64url')}.${ciphertext.toString('base64url')}`;
 }
@@ -74,10 +71,7 @@ export function parseSignedCookie(value, secret) {
         const [, iv, tag, ciphertext] = parts;
         const decipher = createDecipheriv('aes-256-gcm', cookieEncryptionKey(secret), Buffer.from(iv, 'base64url'));
         decipher.setAuthTag(Buffer.from(tag, 'base64url'));
-        const plaintext = Buffer.concat([
-            decipher.update(Buffer.from(ciphertext, 'base64url')),
-            decipher.final()
-        ]);
+        const plaintext = Buffer.concat([decipher.update(Buffer.from(ciphertext, 'base64url')), decipher.final()]);
         return JSON.parse(plaintext.toString('utf8'));
     }
     catch {
@@ -135,7 +129,9 @@ export function validateIdTokenClaims(claims, nonce) {
 }
 export function validateUserInfoSubject(claims, user) {
     if (user && user.sub !== claims.sub) {
-        throw error(401, { message: 'UserInfo subject does not match id_token subject' });
+        throw error(401, {
+            message: 'UserInfo subject does not match id_token subject'
+        });
     }
 }
 export function toPublicSession(session) {
@@ -143,8 +139,7 @@ export function toPublicSession(session) {
         return null;
     return {
         isAuthenticated: true,
-        user: session.user,
-        claims: session.claims,
+        identity: session.identity,
         groups: session.groups,
         scope: session.tokens.scope,
         expiresAt: session.tokens.expiresAt,

package/package.json

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