@flink-app/oidc-plugin 2.0.0-alpha.117 → 2.0.0-alpha.118

package/src/OidcPluginOptions.ts

@@ -2,6 +2,8 @@ import OidcProfile from "./schemas/OidcProfile";
 import OidcTokenSet from "./schemas/OidcTokenSet";
 import { OidcProviderConfig } from "./OidcProviderConfig";
 import { TokenDeliveryMode } from "./utils/response-utils";
+import { AllowedRedirectUris } from "./utils/redirect-uri-utils";
+import { FlinkResponse } from "@flink-app/flink";
 
 /**
  * OIDC error information passed to onAuthError callback
@@ -24,10 +26,10 @@ export interface OidcError {
 }
 
 /**
- * Response from onAuthSuccess callback
- * Must include JWT token generated by the application via jwt-auth-plugin
+ * Default completion: the plugin delivers the JWT token generated by the application
+ * via jwt-auth-plugin, according to `tokenDelivery` (or as JSON for `?response_type=json`).
  */
-export interface AuthSuccessCallbackResponse {
+export interface AuthSuccessTokenResponse {
     /**
      * User object from your application
      * Should include _id field for connection storage
@@ -49,6 +51,60 @@ export interface AuthSuccessCallbackResponse {
     redirectUrl?: string;
 }
 
+/**
+ * Verbatim redirect completion: the plugin redirects to `redirectUrl` exactly as given,
+ * without attaching any token. Use when the application has already handed the session
+ * over some other way — a one-time code it put in the URL, a server-side session keyed
+ * by something in the URL, and so on.
+ *
+ * The URL is still subject to the `allowedRedirectUris` check.
+ */
+export interface AuthSuccessRedirectResponse {
+    /**
+     * User object from your application
+     * Should include _id field for connection storage
+     */
+    user: any;
+
+    /**
+     * URL to redirect to, used exactly as given (no token is spliced in)
+     */
+    redirectUrl: string;
+
+    /**
+     * Must not be set — a token means the default token completion instead
+     */
+    token?: undefined;
+}
+
+/**
+ * Custom completion: the application owns the entire HTTP response — anything a Flink
+ * handler may return, e.g. a redirect plus a `Set-Cookie` header, or a login envelope
+ * its clients already parse.
+ */
+export interface AuthSuccessCustomResponse {
+    /**
+     * User object from your application
+     * Should include _id field for connection storage
+     */
+    user: any;
+
+    /**
+     * The response to send, returned as-is by the callback handler
+     */
+    response: FlinkResponse;
+}
+
+/**
+ * Response from onAuthSuccess callback
+ *
+ * Three shapes are supported:
+ * 1. `{ user, token, redirectUrl? }` — the plugin delivers the token (default)
+ * 2. `{ user, redirectUrl }` — the plugin redirects verbatim, no token attached
+ * 3. `{ user, response }` — the application builds the whole response
+ */
+export type AuthSuccessCallbackResponse = AuthSuccessTokenResponse | AuthSuccessRedirectResponse | AuthSuccessCustomResponse;
+
 /**
  * Response from onAuthError callback
  */
@@ -58,6 +114,13 @@ export interface AuthErrorCallbackResponse {
      * e.g., "/login?error=authentication_failed"
      */
     redirectUrl?: string;
+
+    /**
+     * Optional complete response to send instead, returned as-is by the callback handler.
+     * Takes precedence over `redirectUrl`. Use for error completions the plugin cannot
+     * express, e.g. clearing a session cookie alongside the redirect.
+     */
+    response?: FlinkResponse;
 }
 
 /**
@@ -94,6 +157,41 @@ export interface OidcPluginOptions<TCtx = any> {
      */
     providers?: Record<string, OidcProviderConfig>;
 
+    /**
+     * Which `?redirectUri=` values the initiate endpoint accepts.
+     *
+     * The `redirectUri` decides where the JWT is delivered once the flow completes, and
+     * anyone can craft an initiate link — so without an allow-list a crafted link turns a
+     * legitimate login into token exfiltration. Set this on every deployment.
+     *
+     * Entries are matched as:
+     * - an exact URI (`https://app.example.com/login`), or
+     * - a bare origin (`https://app.example.com`, `myapp://cb`), which covers every path,
+     *   query and fragment below that origin.
+     *
+     * A predicate can be used for anything else.
+     *
+     * Always accepted regardless of the list:
+     * - relative paths (`/dashboard`) — they can only land on this app's own origin
+     * - the provider's own `callbackUrl` (the fallback when no `redirectUri` is passed)
+     *
+     * The same check is applied to a `redirectUrl` returned by `onAuthSuccess` /
+     * `onAuthError` when it differs from the one stored on the session, so echoing an
+     * attacker-supplied value back cannot bypass the list.
+     *
+     * Default: undefined — every redirectUri is accepted (logged as a warning at startup).
+     *
+     * Example:
+     * ```typescript
+     * allowedRedirectUris: [
+     *   "https://app.example.com",      // any path on this origin
+     *   "https://admin.example.com/auth-callback",
+     *   "myapp://oidc-callback"          // native app scheme
+     * ]
+     * ```
+     */
+    allowedRedirectUris?: AllowedRedirectUris;
+
     /**
      * Whether to store OIDC tokens for future API access
      * If false, tokens are discarded after authentication (auth-only mode)
@@ -117,6 +215,15 @@ export interface OidcPluginOptions<TCtx = any> {
      * 3. Generate JWT token using ctx.plugins.jwtAuth.createToken(payload, roles)
      * 4. Return user object, JWT token, and optional redirect URL
      *
+     * Applications that complete the login themselves can return one of two other shapes
+     * instead of a `token`:
+     * - `{ user, redirectUrl }` — the plugin redirects there verbatim, attaching nothing
+     *   (e.g. the URL carries a short-lived one-time code the client exchanges for a session)
+     * - `{ user, response }` — the application returns the whole HTTP response
+     *   (e.g. a redirect plus a `Set-Cookie` header)
+     *
+     * See {@link AuthSuccessCallbackResponse}.
+     *
      * @param params - OIDC profile, claims, provider name, and tokens (if storeTokens enabled)
      * @param ctx - Flink context with access to repos and plugins (including jwtAuth)
      * @returns User object, JWT token, and optional redirect URL
@@ -281,6 +388,28 @@ export interface OidcPluginOptions<TCtx = any> {
      */
     providerLoader?: (providerName: string, ctx: TCtx) => Promise<OidcProviderConfig | null>;
 
+    /**
+     * Seconds a resolved provider (static or from `providerLoader`) is reused before its
+     * config is loaded and OIDC discovery is run again.
+     *
+     * Default: 0 — cache for the life of the process (unchanged behaviour).
+     *
+     * Set this when provider configs live in a database and can change at runtime:
+     * without a TTL, editing an issuer, client id, client secret, scope or discovery URL
+     * only takes effect after a restart of every instance.
+     *
+     * Reloading happens lazily on the next request for that provider. If the reload
+     * fails (IdP unreachable, database hiccup), the previously cached instance keeps
+     * being used and the next attempt happens after another TTL — a discovery hiccup
+     * does not break logins that would otherwise work.
+     *
+     * For an immediate update on the instance handling the change, call
+     * `ctx.plugins.oidc.invalidateProvider(name)`; other instances converge within the TTL.
+     *
+     * Example: `providerCacheTtlSec: 300` (5 minutes)
+     */
+    providerCacheTtlSec?: number;
+
     /**
      * Custom collection name for OIDC sessions
      * Default: 'oidc_sessions'

package/src/handlers/CallbackOidc.ts

@@ -19,6 +19,7 @@ import { validateState } from "../utils/state-utils";
 import { formatTokenResponse } from "../utils/response-utils";
 import { encryptToken } from "../utils/encryption-utils";
 import { validateProvider, validateResponseType, createOidcError, OidcErrorCodes, handleProviderError } from "../utils/error-utils";
+import { isRedirectUriAllowed } from "../utils/redirect-uri-utils";
 import { oidcLog } from "../log";
 
 /**
@@ -53,6 +54,22 @@ const CallbackOidc: GetHandler<any, any, PathParams, CallbackRequest> = async ({
     let sessionRedirectUri: string | undefined;
     let sessionMetadata: Record<string, string> = {};
 
+    /**
+     * Apply the `allowedRedirectUris` allow-list to a redirect target built by the host
+     * (the `redirectUrl` returned by onAuthSuccess / onAuthError), so a host that echoes
+     * back an attacker-supplied value cannot bypass the list by accident.
+     *
+     * The redirectUri stored on the session was already validated at initiate time, as is
+     * the provider's own callbackUrl — both are always accepted here.
+     */
+    const isRedirectAllowed = (url: string, callbackUrl?: string): boolean => {
+        const { options } = ctx.plugins.oidc;
+        return isRedirectUriAllowed(url, provider, options.allowedRedirectUris, [
+            callbackUrl || options.providers?.[provider]?.callbackUrl,
+            sessionRedirectUri,
+        ]);
+    };
+
     try {
         // Validate provider and response_type
         validateProvider(provider);
@@ -85,16 +102,25 @@ const CallbackOidc: GetHandler<any, any, PathParams, CallbackRequest> = async ({
                     metadata: sessionMetadata,
                 });
 
+                if (errorResult.response) {
+                    oidcLog.debug("Callback: responding with host-built error response");
+                    return errorResult.response;
+                }
+
                 if (errorResult.redirectUrl) {
-                    return {
-                        status: 302,
-                        headers: { Location: errorResult.redirectUrl },
-                        data: {},
-                    };
+                    if (!isRedirectAllowed(errorResult.redirectUrl)) {
+                        log.error(`OIDC callback: onAuthError returned a redirectUrl that is not allowed, ignoring it: ${errorResult.redirectUrl}`);
+                    } else {
+                        return {
+                            status: 302,
+                            headers: { Location: errorResult.redirectUrl },
+                            data: {},
+                        };
+                    }
                 }
             }
 
-            return badRequest(error.message);
+            return badRequest(error.message, error.code);
         }
 
         // Validate required parameters
@@ -193,22 +219,37 @@ const CallbackOidc: GetHandler<any, any, PathParams, CallbackRequest> = async ({
                     metadata: sessionMetadata,
                 });
 
+                if (errorResult.response) {
+                    oidcLog.debug("Callback: responding with host-built error response");
+                    return errorResult.response;
+                }
+
                 if (errorResult.redirectUrl) {
-                    return {
-                        status: 302,
-                        headers: { Location: errorResult.redirectUrl },
-                        data: {},
-                    };
+                    if (!isRedirectAllowed(errorResult.redirectUrl)) {
+                        log.error(`OIDC callback: onAuthError returned a redirectUrl that is not allowed, ignoring it: ${errorResult.redirectUrl}`);
+                    } else {
+                        return {
+                            status: 302,
+                            headers: { Location: errorResult.redirectUrl },
+                            data: {},
+                        };
+                    }
                 }
             }
 
             return internalServerError("Authentication failed. Please try again.");
         }
 
-        // Extract user and JWT token from callback result
-        const { user, token, redirectUrl } = authResult;
+        // Extract the completion the host asked for. Three shapes are supported:
+        // 1. `token`     — the plugin delivers it (fragment/query/JSON)
+        // 2. `redirectUrl` without a token — redirect there verbatim, attaching nothing
+        // 3. `response`  — the host owns the whole HTTP response (Set-Cookie, custom envelope, ...)
+        const { user } = authResult;
+        const token = "token" in authResult ? authResult.token : undefined;
+        const redirectUrl = "redirectUrl" in authResult ? authResult.redirectUrl : undefined;
+        const hostResponse = "response" in authResult ? authResult.response : undefined;
 
-        if (!token) {
+        if (!token && !redirectUrl && !hostResponse) {
             throw createOidcError(OidcErrorCodes.JWT_GENERATION_FAILED, "No authentication token returned from callback", { hasUser: !!user });
         }
 
@@ -262,7 +303,46 @@ const CallbackOidc: GetHandler<any, any, PathParams, CallbackRequest> = async ({
             }
         }
 
+        // Shape 3: the host built the whole response — send it as-is
+        if (hostResponse) {
+            oidcLog.debug(`Callback: auth complete, responding with host-built response (status=${hostResponse.status ?? 200})`);
+            return hostResponse;
+        }
+
+        // Shape 2: verbatim redirect, nothing attached
+        if (!token) {
+            if (response_type === "json") {
+                throw createOidcError(
+                    OidcErrorCodes.INVALID_RESPONSE_TYPE,
+                    "The application completed the login without a token, so JSON mode is not available for this callback",
+                    { provider }
+                );
+            }
+
+            if (!isRedirectAllowed(redirectUrl!, oidcProvider.config?.callbackUrl)) {
+                log.error(`OIDC callback: onAuthSuccess returned a redirectUrl that is not allowed: ${redirectUrl}`);
+                throw createOidcError(OidcErrorCodes.INVALID_REDIRECT_URI, "The redirect URL is not allowed", { redirectUrl, provider });
+            }
+
+            oidcLog.debug(`Callback: auth complete, redirecting verbatim to "${redirectUrl}" (no token attached)`);
+
+            return {
+                status: 302,
+                headers: { Location: redirectUrl! },
+                data: {},
+            };
+        }
+
+        // Shape 1: the plugin delivers the token
         const finalRedirectUrl = redirectUrl || session.redirectUri;
+
+        // Only the redirect response can leak the token to a foreign origin — the JSON
+        // response never uses finalRedirectUrl, so it is not subject to the allow-list.
+        if (response_type !== "json" && !isRedirectAllowed(finalRedirectUrl, oidcProvider.config?.callbackUrl)) {
+            log.error(`OIDC callback: onAuthSuccess returned a redirectUrl that is not allowed: ${finalRedirectUrl}`);
+            throw createOidcError(OidcErrorCodes.INVALID_REDIRECT_URI, "The redirect URL is not allowed", { redirectUrl: finalRedirectUrl, provider });
+        }
+
         oidcLog.debug(`Callback: auth complete, responding via ${response_type === "json" ? "JSON" : `redirect to "${finalRedirectUrl}"`}`);
 
         // Resolve token delivery mode: literal, function, or default "fragment".
@@ -295,19 +375,28 @@ const CallbackOidc: GetHandler<any, any, PathParams, CallbackRequest> = async ({
                         metadata: sessionMetadata,
                     });
 
+                    if (errorResult.response) {
+                        oidcLog.debug("Callback: responding with host-built error response");
+                        return errorResult.response;
+                    }
+
                     if (errorResult.redirectUrl) {
-                        return {
-                            status: 302,
-                            headers: { Location: errorResult.redirectUrl },
-                            data: {},
-                        };
+                        if (!isRedirectAllowed(errorResult.redirectUrl)) {
+                            log.error(`OIDC callback: onAuthError returned a redirectUrl that is not allowed, ignoring it: ${errorResult.redirectUrl}`);
+                        } else {
+                            return {
+                                status: 302,
+                                headers: { Location: errorResult.redirectUrl },
+                                data: {},
+                            };
+                        }
                     }
                 } catch (callbackError) {
                     log.error("onAuthError callback failed:", callbackError);
                 }
             }
 
-            return badRequest(error.message);
+            return badRequest(error.message, error.code);
         }
 
         // Handle provider errors

package/src/handlers/InitiateOidc.ts

@@ -15,6 +15,7 @@ import { GetHandler, HttpMethod, RouteProps, badRequest, internalServerError } f
 import InitiateRequest from "../schemas/InitiateRequest";
 import { generateState, generateSessionId, generateNonce } from "../utils/state-utils";
 import { validateProvider, createOidcError, OidcErrorCodes } from "../utils/error-utils";
+import { isRedirectUriAllowed } from "../utils/redirect-uri-utils";
 import { generators } from "openid-client";
 import { oidcLog } from "../log";
 
@@ -65,7 +66,17 @@ const InitiateOidc: GetHandler<any, any, PathParams, InitiateRequest> = async ({
 
         // Determine redirect URI (use provided or default to callback URL)
         const staticProviderConfig = options.providers?.[provider];
-        const finalRedirectUri = redirectUri || staticProviderConfig?.callbackUrl || `${req.protocol}://${req.get("host")}/oidc/${provider}/callback`;
+        const callbackUrl = oidcProvider?.config?.callbackUrl || staticProviderConfig?.callbackUrl;
+
+        // The redirectUri decides where the JWT ends up, and the query param is
+        // attacker-controllable — validate it against the configured allow-list
+        // before anything is persisted.
+        if (redirectUri && !isRedirectUriAllowed(redirectUri, provider, options.allowedRedirectUris, [callbackUrl])) {
+            oidcLog.debug(`Initiate: rejected redirectUri="${redirectUri}" (not in allowedRedirectUris)`);
+            throw createOidcError(OidcErrorCodes.INVALID_REDIRECT_URI, "The provided redirectUri is not allowed", { redirectUri, provider });
+        }
+
+        const finalRedirectUri = redirectUri || callbackUrl || `${req.protocol}://${req.get("host")}/oidc/${provider}/callback`;
 
         // Collect meta.* query params as opaque metadata (prefix stripped)
         const metadata: Record<string, string> = {};
@@ -75,7 +86,7 @@ const InitiateOidc: GetHandler<any, any, PathParams, InitiateRequest> = async ({
             }
         }
 
-        oidcLog.debug(`Initiate: resolved redirectUri="${finalRedirectUri}" (source: ${redirectUri ? "query param" : staticProviderConfig?.callbackUrl ? "provider config" : "auto-detected"})`);
+        oidcLog.debug(`Initiate: resolved redirectUri="${finalRedirectUri}" (source: ${redirectUri ? "query param" : callbackUrl ? "provider config" : "auto-detected"})`);
 
         // Generate cryptographically secure parameters
         const state = generateState();
@@ -117,7 +128,7 @@ const InitiateOidc: GetHandler<any, any, PathParams, InitiateRequest> = async ({
     } catch (error: any) {
         // Handle validation errors
         if (error.code && Object.values(OidcErrorCodes).includes(error.code)) {
-            return badRequest(error.message);
+            return badRequest(error.message, error.code);
         }
 
         // Handle unexpected errors

package/src/index.ts

@@ -12,7 +12,15 @@
 export { oidcPlugin } from "./OidcPlugin";
 
 // Configuration types
-export { OidcPluginOptions, OidcError, AuthSuccessCallbackResponse, AuthErrorCallbackResponse } from "./OidcPluginOptions";
+export {
+    OidcPluginOptions,
+    OidcError,
+    AuthSuccessCallbackResponse,
+    AuthSuccessTokenResponse,
+    AuthSuccessRedirectResponse,
+    AuthSuccessCustomResponse,
+    AuthErrorCallbackResponse,
+} from "./OidcPluginOptions";
 export { OidcProviderConfig } from "./OidcProviderConfig";
 
 // Context types
@@ -35,4 +43,5 @@ export { generateState, generateSessionId, generateNonce, validateState } from "
 export { encryptToken, decryptToken, validateEncryptionSecret } from "./utils/encryption-utils";
 export { mapClaimsToProfile, extractCustomClaims } from "./utils/claims-mapper";
 export { formatTokenResponse, TokenDeliveryMode } from "./utils/response-utils";
+export { isRedirectUriAllowed, isRelativeRedirect, AllowedRedirectUris } from "./utils/redirect-uri-utils";
 export { createOidcError, validateProvider, handleProviderError, OidcErrorCodes } from "./utils/error-utils";

package/src/providers/ProviderRegistry.ts

@@ -2,6 +2,15 @@ import { OidcProvider } from "./OidcProvider";
 import { OidcProviderConfig } from "../OidcProviderConfig";
 import { createOidcError, OidcErrorCodes } from "../utils/error-utils";
 import { oidcLog, maskSecret } from "../log";
+import { log } from "@flink-app/flink";
+
+/**
+ * A cached provider instance along with the time its config was resolved
+ */
+interface CachedProvider {
+    provider: OidcProvider;
+    loadedAt: number;
+}
 
 /**
  * Provider registry for managing OIDC provider instances
@@ -9,34 +18,43 @@ import { oidcLog, maskSecret } from "../log";
  * Handles:
  * - Static provider configuration
  * - Dynamic provider loading from database
- * - Provider instance caching
+ * - Provider instance caching (optionally with a TTL)
  * - Lazy initialization
  */
 export class ProviderRegistry {
     private staticProviders: Record<string, OidcProviderConfig>;
-    private providerInstances: Map<string, OidcProvider> = new Map();
+    private providerInstances: Map<string, CachedProvider> = new Map();
     private providerLoader?: (providerName: string, ctx: any) => Promise<OidcProviderConfig | null>;
     private ctx: any;
+    private providerCacheTtlSec: number;
 
     constructor(
         staticProviders: Record<string, OidcProviderConfig>,
         providerLoader?: (providerName: string, ctx: any) => Promise<OidcProviderConfig | null>,
-        ctx?: any
+        ctx?: any,
+        providerCacheTtlSec: number = 0
     ) {
         this.staticProviders = staticProviders;
         this.providerLoader = providerLoader;
         this.ctx = ctx;
+        this.providerCacheTtlSec = providerCacheTtlSec;
     }
 
     /**
      * Get provider instance by name
      *
      * Looks up provider in the following order:
-     * 1. Cached instance
+     * 1. Cached instance (unless it is older than `providerCacheTtlSec`)
      * 2. Static configuration
      * 3. Dynamic loader (if configured)
      *
-     * Providers are lazy-initialized on first use and cached.
+     * Providers are lazy-initialized on first use and cached. With a cache TTL
+     * configured, an expired entry is reloaded on the next request — the config is
+     * resolved again (re-running `providerLoader`) and discovery is re-run.
+     *
+     * If reloading an expired entry fails, the previous instance keeps being used: a
+     * transient discovery or database hiccup should not break logins that would
+     * otherwise work. The next reload attempt happens after another TTL.
      *
      * @param providerName - Provider identifier
      * @returns Initialized OIDC provider instance
@@ -44,24 +62,27 @@ export class ProviderRegistry {
      */
     async getProvider(providerName: string): Promise<OidcProvider> {
         // Check cache first
-        const cachedProvider = this.providerInstances.get(providerName);
-        if (cachedProvider) {
+        const cached = this.providerInstances.get(providerName);
+        if (cached && !this.isExpired(cached)) {
             oidcLog.debug(`Provider "${providerName}": using cached instance`);
-            return cachedProvider;
+            return cached.provider;
         }
 
-        // Try static configuration
-        let config: OidcProviderConfig | null = this.staticProviders[providerName] || null;
-        let configSource = "static";
+        if (cached) {
+            oidcLog.debug(`Provider "${providerName}": cache entry older than ${this.providerCacheTtlSec}s, reloading`);
+        }
 
-        // Try dynamic loader if not in static config
-        if (!config && this.providerLoader) {
-            oidcLog.debug(`Provider "${providerName}": not in static config, invoking providerLoader`);
-            config = await this.providerLoader(providerName, this.ctx);
-            configSource = "dynamic";
+        // Resolve config (static config first, then the dynamic loader)
+        let config: OidcProviderConfig | null;
+        try {
+            config = await this.resolveConfig(providerName);
+        } catch (error: any) {
+            return this.keepCachedOnFailure(providerName, cached, "config could not be loaded", error);
         }
 
         if (!config) {
+            // Provider is genuinely gone (or never existed) — drop any cached instance
+            this.providerInstances.delete(providerName);
             oidcLog.debug(`Provider "${providerName}": not found (static=[${Object.keys(this.staticProviders).join(", ")}], loader=${!!this.providerLoader})`);
             throw createOidcError(OidcErrorCodes.PROVIDER_NOT_CONFIGURED, `OIDC provider '${providerName}' is not configured`, {
                 providerName,
@@ -70,7 +91,7 @@ export class ProviderRegistry {
         }
 
         oidcLog.debug(
-            `Provider "${providerName}" resolved via ${configSource}:`,
+            `Provider "${providerName}" resolved via ${providerName in this.staticProviders ? "static" : "dynamic"}:`,
             `issuer=${config.issuer}`,
             `clientId=${config.clientId}`,
             `clientSecret=${maskSecret(config.clientSecret)}`,
@@ -80,13 +101,63 @@ export class ProviderRegistry {
         );
 
         // Create and initialize provider
-        const provider = new OidcProvider(config);
-        await provider.initialize();
+        try {
+            const provider = new OidcProvider(config);
+            await provider.initialize();
 
-        // Cache the instance
-        this.providerInstances.set(providerName, provider);
+            // Cache the instance
+            this.providerInstances.set(providerName, { provider, loadedAt: Date.now() });
 
-        return provider;
+            return provider;
+        } catch (error: any) {
+            return this.keepCachedOnFailure(providerName, cached, "initialization failed", error);
+        }
+    }
+
+    /**
+     * Resolve provider config from static configuration or the dynamic loader
+     */
+    private async resolveConfig(providerName: string): Promise<OidcProviderConfig | null> {
+        const staticConfig = this.staticProviders[providerName];
+        if (staticConfig) {
+            return staticConfig;
+        }
+
+        if (this.providerLoader) {
+            oidcLog.debug(`Provider "${providerName}": not in static config, invoking providerLoader`);
+            return await this.providerLoader(providerName, this.ctx);
+        }
+
+        return null;
+    }
+
+    /**
+     * Whether a cache entry has outlived the configured TTL.
+     * A TTL of 0 (the default) means entries are cached for the life of the process.
+     */
+    private isExpired(cached: CachedProvider): boolean {
+        if (this.providerCacheTtlSec <= 0) {
+            return false;
+        }
+
+        return Date.now() - cached.loadedAt >= this.providerCacheTtlSec * 1000;
+    }
+
+    /**
+     * Keep serving a previously cached instance when a reload fails.
+     * Rethrows when there is nothing cached to fall back on.
+     */
+    private keepCachedOnFailure(providerName: string, cached: CachedProvider | undefined, reason: string, error: any): OidcProvider {
+        if (!cached) {
+            throw error;
+        }
+
+        log.warn(`OIDC Plugin: reload of provider "${providerName}" failed (${reason}), keeping the previously cached instance: ${error.message}`);
+
+        // Restart the TTL window so a persistent failure is not retried on every request
+        cached.loadedAt = Date.now();
+
+        return cached.provider;
     }
 
     /**
@@ -105,6 +176,8 @@ export class ProviderRegistry {
      * Forces re-initialization of providers on next access.
      * Useful when provider configurations change.
      *
+     * Exposed to applications as `ctx.plugins.oidc.invalidateProvider()`.
+     *
      * @param providerName - Optional provider to clear (clears all if not specified)
      */
     clearCache(providerName?: string): void {

package/src/utils/error-utils.ts

@@ -14,6 +14,7 @@ export const OidcErrorCodes = {
     MISSING_STATE: "missing_state",
     INVALID_STATE: "invalid_state",
     INVALID_RESPONSE_TYPE: "invalid_response_type",
+    INVALID_REDIRECT_URI: "invalid_redirect_uri",
 
     // Session errors
     SESSION_NOT_FOUND: "session_not_found",