@sourceregistry/sveltekit-oidc 2.0.2 → 3.0.0

package/dist/server/jwt.js

@@ -13,11 +13,17 @@ export async function fetchJson(url, init, fetchImpl = fetch) {
     return (await response.json());
 }
 export function asAuthorizationHeader(clientId, clientSecret) {
-    return `Basic ${Buffer.from(`${clientId}:${clientSecret}`).toString('base64')}`;
+    const encode = (value) => {
+        const encoded = new URLSearchParams({ value }).toString();
+        return encoded.slice('value='.length);
+    };
+    return `Basic ${Buffer.from(`${encode(clientId)}:${encode(clientSecret)}`).toString('base64')}`;
 }
 export async function createClientSecretJwtAssertion(options) {
     if (!options.clientSecret) {
-        throw error(500, { message: 'clientSecret is required for client_secret_jwt' });
+        throw error(500, {
+            message: 'clientSecret is required for client_secret_jwt'
+        });
     }
     const algorithm = options.algorithm ?? 'HS256';
     const now = Math.floor(Date.now() / 1000);
@@ -40,5 +46,9 @@ export async function createPrivateKeyJwtAssertion(options) {
         jti: base64UrlEncode(randomBytes(24)),
         iat: now,
         exp: now + (options.expiresInSeconds ?? 60)
-    }, options.privateKey, { alg: algorithm, typ: 'JWT', ...(options.keyId ? { kid: options.keyId } : {}) });
+    }, options.privateKey, {
+        alg: algorithm,
+        typ: 'JWT',
+        ...(options.keyId ? { kid: options.keyId } : {})
+    });
 }

package/dist/server/store.d.ts

@@ -1,3 +1,5 @@
 import type { OIDCBackChannelLogoutStore, OIDCSessionStore, OIDCUserClaims } from './types.js';
-export declare function createInMemoryBackChannelLogoutStore<TIdentity extends OIDCUserClaims = OIDCUserClaims>(): OIDCBackChannelLogoutStore<TIdentity>;
+export declare function createInMemoryBackChannelLogoutStore<TIdentity extends OIDCUserClaims = OIDCUserClaims>(options?: {
+    retentionSeconds?: number;
+}): OIDCBackChannelLogoutStore<TIdentity>;
 export declare function createInMemorySessionStore<TIdentity extends OIDCUserClaims = OIDCUserClaims>(): OIDCSessionStore<TIdentity>;

package/dist/server/store.js

@@ -1,18 +1,38 @@
-export function createInMemoryBackChannelLogoutStore() {
-    const revokedBySid = new Set();
-    const revokedBySub = new Set();
+export function createInMemoryBackChannelLogoutStore(options = {}) {
+    const retentionSeconds = options.retentionSeconds ?? 60 * 60 * 8;
+    const revokedBySid = new Map();
+    const revokedBySub = new Map();
+    function remember(map, key, issuedAt) {
+        map.set(key, {
+            issuedAt,
+            removeAt: Math.floor(Date.now() / 1000) + retentionSeconds
+        });
+    }
+    function matches(map, key, sessionCreatedAt) {
+        if (!key)
+            return false;
+        const record = map.get(key);
+        if (!record)
+            return false;
+        if (record.removeAt <= Math.floor(Date.now() / 1000)) {
+            map.delete(key);
+            return false;
+        }
+        // A later login is a new session and must not inherit a subject-wide revocation.
+        return sessionCreatedAt <= record.issuedAt;
+    }
     return {
         async revoke(record) {
             if (record.sid) {
-                revokedBySid.add(`${record.issuer}:${record.clientId}:${record.sid}`);
+                remember(revokedBySid, `${record.issuer}:${record.clientId}:${record.sid}`, record.iat);
             }
             if (record.sub) {
-                revokedBySub.add(`${record.issuer}:${record.clientId}:${record.sub}`);
+                remember(revokedBySub, `${record.issuer}:${record.clientId}:${record.sub}`, record.iat);
             }
         },
         async isRevoked(session) {
-            return Boolean((session.sid && revokedBySid.has(`${session.issuer}:${session.clientId}:${session.sid}`)) ||
-                (session.sub && revokedBySub.has(`${session.issuer}:${session.clientId}:${session.sub}`)));
+            return Boolean(matches(revokedBySid, session.sid ? `${session.issuer}:${session.clientId}:${session.sid}` : undefined, session.createdAt) ||
+                matches(revokedBySub, session.sub ? `${session.issuer}:${session.clientId}:${session.sub}` : undefined, session.createdAt));
         }
     };
 }

package/dist/server/types.d.ts

@@ -56,6 +56,8 @@ export type OIDCUserClaims = Record<string, unknown> & {
     iat?: number;
     nbf?: number;
     nonce?: string;
+    azp?: string;
+    auth_time?: number;
 };
 export type OIDCSessionReason = 'login' | 'refresh';
 export type OIDCSession<TIdentity extends OIDCUserClaims = OIDCUserClaims> = {
@@ -93,6 +95,7 @@ export type OIDCBackChannelLogoutClaims = Record<string, unknown> & {
     iss: string;
     aud: string | string[];
     iat: number;
+    exp: number;
     jti: string;
     sub?: string;
     sid?: string;
@@ -125,6 +128,10 @@ export type OIDCBackChannelLogoutStore<TIdentity extends OIDCUserClaims = OIDCUs
     revoke(record: OIDCBackChannelLogoutRecord): MaybePromise<void>;
     isRevoked(session: OIDCSession<TIdentity>): MaybePromise<boolean>;
 };
+/** Optional distributed lock used to serialize refresh-token rotation across application instances. */
+export type OIDCRefreshLock = {
+    runExclusive<T>(key: string, task: () => Promise<T>): Promise<T>;
+};
 export type OIDCSessionStore<TIdentity extends OIDCUserClaims = OIDCUserClaims> = {
     get(sessionId: string): MaybePromise<OIDCSession<TIdentity> | null>;
     set(sessionId: string, session: OIDCSession<TIdentity>): MaybePromise<void>;
@@ -169,25 +176,57 @@ export type OIDCOptions<TIdentity extends OIDCUserClaims = OIDCUserClaims, TRequ
     cookieOptions?: Partial<CookieOptions>;
     clockSkewSeconds?: number;
     refreshToleranceSeconds?: number;
+    /** Accepted ID-token signing algorithms. Defaults to the provider metadata, or RS256 when absent. */
+    idTokenSigningAlgorithms?: SupportedAlgorithm[];
+    /** Additional audiences trusted in a multi-audience ID token. */
+    trustedIdTokenAudiences?: string[];
+    /** Permit non-HTTPS issuer and protocol endpoints for local development only. */
+    allowInsecureHttp?: boolean;
+    /** Maximum serialized cookie size before failing with guidance to use sessionStore. Defaults to 3800 bytes. */
+    maxCookieSizeBytes?: number;
     /** Maximum lifetime of a local browser session. Defaults to 8 hours. */
     sessionMaxAgeSeconds?: number;
+    /**
+     * Maximum lifetime of the short-lived cookie that carries CSRF state,
+     * the PKCE verifier, and the OIDC nonce across the redirect to the
+     * provider and back. Defaults to 10 minutes.
+     *
+     * If this expires (or the cookie is otherwise missing/mismatched, e.g.
+     * a second login started in another tab) before the browser returns
+     * from the provider, `handleCallback` restarts the login rather than
+     * failing outright - and the caller's original `returnTo` is *not*
+     * lost when that happens, since it also travels signed inside the
+     * `state` query parameter itself (see encodeOAuthState/decodeOAuthState
+     * in utils.ts), independent of this cookie's survival. Raising this
+     * value only reduces how often that restart happens; it is not
+     * required to fix a lost `returnTo`.
+     */
+    stateMaxAgeSeconds?: number;
     defaultLoginRedirect?: string;
     defaultLogoutRedirect?: string;
     sessionStore?: OIDCSessionStore<TIdentity> | 'memory';
     backChannelLogoutStore?: OIDCBackChannelLogoutStore<TIdentity> | 'memory';
+    /** Use a shared implementation in multi-instance deployments with rotating refresh tokens. */
+    refreshLock?: OIDCRefreshLock;
     /** 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. */
+    /**
+     * 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
@@ -240,6 +279,12 @@ export type OIDCHandleLocals<TIdentity extends OIDCUserClaims = OIDCUserClaims,
     clearSession: () => Promise<void>;
 };
 export type OIDCStateCookie = {
+    /**
+     * The bare anti-CSRF token, compared against the decoded `state` query
+     * parameter on callback - not the full value sent to the provider,
+     * which additionally carries an encrypted `returnTo` (see
+     * encodeOAuthState/decodeOAuthState in utils.ts).
+     */
     state: string;
     nonce: string;
     codeVerifier: string;
@@ -280,9 +325,9 @@ export type OIDCCookies<TIdentity extends OIDCUserClaims = OIDCUserClaims> = {
         id: string;
     }): void;
     clearSessionReference(cookies: Cookies): void;
-    readState(cookies: Cookies): OIDCStateCookie | null;
+    readState(cookies: Cookies, stateToken?: string | null): OIDCStateCookie | null;
     writeState(cookies: Cookies, state: OIDCStateCookie): void;
-    clearState(cookies: Cookies): void;
+    clearState(cookies: Cookies, stateToken?: string | null): void;
 };
 export type OIDCPersistedSession<TIdentity extends OIDCUserClaims = OIDCUserClaims> = {
     id?: string;

package/dist/server/utils.d.ts

@@ -10,6 +10,36 @@ 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;
 export declare function verifySignedValue(value: string, secret: string): string | null;
+/**
+ * Embeds an app-supplied `returnTo` destination directly in the OAuth
+ * `state` parameter sent to the authorization endpoint, encrypted and
+ * authenticated with the same cookie secret used everywhere else here.
+ *
+ * The encrypted payload keeps the destination confidential while allowing
+ * it to survive the authorization-server round trip. The random token is
+ * still compared with the matching transaction cookie by the callback.
+ */
+export declare function encodeOAuthState(token: string, returnTo: string | undefined, secret: string): string;
+/**
+ * Inverse of encodeOAuthState. Always returns whatever `token` it can parse
+ * out - including from a bare, pre-upgrade-format state with no embedded
+ * `returnTo`, so an in-flight login started before a version bump that adds
+ * this encoding keeps working - and a `returnTo` only when an encrypted
+ * payload authenticates successfully. Forged or corrupted current-format
+ * state values are rejected. The legacy signed suffix remains readable so
+ * an authorization request begun before an upgrade can finish.
+ *
+ * This does NOT authenticate the caller by itself - `token` still has to be
+ * compared against the value in the state cookie by callers, exactly as
+ * before. The `returnTo` recovered here is only ever used to decide where
+ * to send the browser next (see handleCallback's restart-on-mismatch path
+ * in index.ts); nothing security-sensitive is decided from it, so a
+ * same-origin-only destination recovered without the cookie is fine.
+ */
+export declare function decodeOAuthState(raw: string | null | undefined, secret: string): {
+    token: string | null;
+    returnTo?: string;
+};
 export declare function serializeSignedCookie(payload: unknown, secret: string): string;
 export declare function parseSignedCookie<T>(value: string | undefined, secret: string): T | null;
 export declare function buildCookieOptions(options?: Partial<CookieOptions>): CookieOptions;
@@ -22,6 +52,7 @@ export declare function absoluteUrl(event: {
 export declare function internalRedirectPath(event: {
     url: URL;
 }, pathOrUrl: string | undefined, fallback?: string): string;
-export declare function validateIdTokenClaims(claims: OIDCUserClaims, nonce: string): void;
+export declare function validateIdTokenClaims(claims: OIDCUserClaims, nonce: string | undefined, clientId?: string, trustedAudiences?: string[], requireNonce?: boolean): void;
+export declare function validateRefreshedIdTokenClaims(previous: OIDCUserClaims, claims: OIDCUserClaims): void;
 export declare function validateUserInfoSubject(claims: OIDCUserClaims, user: OIDCUserClaims | undefined): void;
 export declare function toPublicSession<TIdentity extends OIDCUserClaims = OIDCUserClaims>(session: OIDCSession<TIdentity> | null): OIDCPublicSession<TIdentity> | null;

package/dist/server/utils.js

@@ -15,8 +15,11 @@ export function normalizeIssuer(issuer) {
 export function normalizeScope(scope) {
     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'];
+    const arr = (typeof scope === 'string' ? scope.trim().split(/\s+/) : scope).filter(Boolean);
+    if (!arr.length)
+        return ['openid', 'profile', 'email'];
+    const unique = [...new Set(arr)];
+    return unique.includes('openid') ? unique : ['openid', ...unique];
 }
 export function normalizeStringArray(value) {
     if (!value)
@@ -51,6 +54,66 @@ export function verifySignedValue(value, secret) {
     }
     return payload;
 }
+/**
+ * Embeds an app-supplied `returnTo` destination directly in the OAuth
+ * `state` parameter sent to the authorization endpoint, encrypted and
+ * authenticated with the same cookie secret used everywhere else here.
+ *
+ * The encrypted payload keeps the destination confidential while allowing
+ * it to survive the authorization-server round trip. The random token is
+ * still compared with the matching transaction cookie by the callback.
+ */
+export function encodeOAuthState(token, returnTo, secret) {
+    if (!returnTo)
+        return token;
+    return `v3.${serializeSignedCookie({ token, returnTo }, secret)}`;
+}
+/**
+ * Inverse of encodeOAuthState. Always returns whatever `token` it can parse
+ * out - including from a bare, pre-upgrade-format state with no embedded
+ * `returnTo`, so an in-flight login started before a version bump that adds
+ * this encoding keeps working - and a `returnTo` only when an encrypted
+ * payload authenticates successfully. Forged or corrupted current-format
+ * state values are rejected. The legacy signed suffix remains readable so
+ * an authorization request begun before an upgrade can finish.
+ *
+ * This does NOT authenticate the caller by itself - `token` still has to be
+ * compared against the value in the state cookie by callers, exactly as
+ * before. The `returnTo` recovered here is only ever used to decide where
+ * to send the browser next (see handleCallback's restart-on-mismatch path
+ * in index.ts); nothing security-sensitive is decided from it, so a
+ * same-origin-only destination recovered without the cookie is fine.
+ */
+export function decodeOAuthState(raw, secret) {
+    if (!raw)
+        return { token: null };
+    if (raw.startsWith('v3.')) {
+        const decoded = parseSignedCookie(raw.slice(3), secret);
+        if (!decoded || typeof decoded.token !== 'string')
+            return { token: null };
+        return {
+            token: decoded.token,
+            ...(typeof decoded.returnTo === 'string' ? { returnTo: decoded.returnTo } : {})
+        };
+    }
+    const separator = raw.indexOf('.');
+    if (separator === -1)
+        return { token: raw };
+    const token = raw.slice(0, separator);
+    const signedReturnTo = raw.slice(separator + 1);
+    const encodedReturnTo = verifySignedValue(signedReturnTo, secret);
+    if (!encodedReturnTo)
+        return { token };
+    try {
+        return {
+            token,
+            returnTo: Buffer.from(encodedReturnTo, 'base64url').toString('utf8')
+        };
+    }
+    catch {
+        return { token };
+    }
+}
 function cookieEncryptionKey(secret) {
     return createHash('sha256').update(`sveltekit-oidc-cookie:${secret}`).digest();
 }
@@ -113,19 +176,49 @@ export function internalRedirectPath(event, pathOrUrl, fallback = '/') {
         return fallback;
     }
 }
-export function validateIdTokenClaims(claims, nonce) {
+export function validateIdTokenClaims(claims, nonce, clientId, trustedAudiences = [], requireNonce = true) {
     if (!Number.isFinite(claims.exp)) {
         throw error(401, { message: 'id_token expiration is required' });
     }
     if (!Number.isFinite(claims.iat)) {
         throw error(401, { message: 'id_token issued-at time is required' });
     }
-    if (claims.nonce !== nonce) {
+    if (requireNonce && claims.nonce !== nonce) {
         throw error(401, { message: 'Invalid id_token nonce' });
     }
     if (!claims.sub) {
         throw error(401, { message: 'id_token subject is required' });
     }
+    if (clientId) {
+        const audiences = Array.isArray(claims.aud) ? claims.aud : claims.aud ? [claims.aud] : [];
+        const trusted = new Set([clientId, ...trustedAudiences]);
+        if (!audiences.includes(clientId) || audiences.some((audience) => !trusted.has(audience))) {
+            throw error(401, { message: 'id_token contains an untrusted audience' });
+        }
+        if (claims.azp !== undefined && claims.azp !== clientId) {
+            throw error(401, { message: 'Invalid id_token authorized party' });
+        }
+    }
+}
+export function validateRefreshedIdTokenClaims(previous, claims) {
+    const normalizeAudience = (value) => (Array.isArray(value) ? [...value] : value === undefined ? [] : [value]).sort();
+    if (claims.sub !== previous.sub)
+        throw error(401, { message: 'Refreshed id_token subject changed' });
+    if (JSON.stringify(normalizeAudience(claims.aud)) !== JSON.stringify(normalizeAudience(previous.aud))) {
+        throw error(401, { message: 'Refreshed id_token audience changed' });
+    }
+    if (claims.azp !== previous.azp)
+        throw error(401, {
+            message: 'Refreshed id_token authorized party changed'
+        });
+    if (claims.auth_time !== undefined && claims.auth_time !== previous.auth_time) {
+        throw error(401, {
+            message: 'Refreshed id_token authentication time changed'
+        });
+    }
+    if (claims.nonce !== undefined && claims.nonce !== previous.nonce) {
+        throw error(401, { message: 'Invalid refreshed id_token nonce' });
+    }
 }
 export function validateUserInfoSubject(claims, user) {
     if (user && user.sub !== claims.sub) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sourceregistry/sveltekit-oidc",
-  "version": "2.0.2",
+  "version": "3.0.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",
@@ -84,7 +84,7 @@
     "oauth"
   ],
   "dependencies": {
-    "@sourceregistry/node-jwt": "^1.5.11"
+    "@sourceregistry/node-jwt": "^1.6.0"
   },
   "release": {
     "branches": [