@flink-app/oidc-plugin 1.0.0 → 2.0.0-alpha.101

package/spec/utils/response-utils.spec.ts

@@ -0,0 +1,85 @@
+/**
+ * Tests for formatTokenResponse — covers JSON mode, fragment mode (default,
+ * backwards compatible), and query mode (including the tricky case where
+ * the redirectUrl already carries a fragment that must be preserved).
+ */
+
+import { formatTokenResponse } from "../../src/utils/response-utils";
+
+describe("response-utils", () => {
+    describe("formatTokenResponse", () => {
+        const token = "jwt.token.value";
+        const user = { id: "u1", email: "a@b.c" };
+
+        describe("JSON mode", () => {
+            it("returns { data: { user, token } } when response_type=json", () => {
+                const result = formatTokenResponse(token, user, "https://app/cb", "json");
+                expect(result).toEqual({ data: { user, token } });
+            });
+
+            it("ignores tokenDelivery when response_type=json", () => {
+                const result = formatTokenResponse(token, user, "https://app/cb", "json", "query");
+                expect(result).toEqual({ data: { user, token } });
+            });
+        });
+
+        describe("fragment mode (default)", () => {
+            it("appends #token=... to a plain URL", () => {
+                const result = formatTokenResponse(token, user, "https://app/cb");
+                expect(result.status).toBe(302);
+                expect(result.headers.Location).toBe(`https://app/cb#token=${encodeURIComponent(token)}`);
+            });
+
+            it("uses & when the URL already has a fragment", () => {
+                const result = formatTokenResponse(token, user, "https://app/cb#foo=bar");
+                expect(result.headers.Location).toBe(`https://app/cb#foo=bar&token=${encodeURIComponent(token)}`);
+            });
+
+            it("preserves existing query string", () => {
+                const result = formatTokenResponse(token, user, "https://app/cb?next=/dashboard");
+                expect(result.headers.Location).toBe(`https://app/cb?next=/dashboard#token=${encodeURIComponent(token)}`);
+            });
+
+            it("URL-encodes tokens with special characters", () => {
+                const weird = "a b+c/d=e";
+                const result = formatTokenResponse(weird, user, "https://app/cb");
+                expect(result.headers.Location).toBe(`https://app/cb#token=${encodeURIComponent(weird)}`);
+            });
+
+            it("is the default when tokenDelivery is omitted", () => {
+                const implicit = formatTokenResponse(token, user, "https://app/cb");
+                const explicit = formatTokenResponse(token, user, "https://app/cb", undefined, "fragment");
+                expect(implicit.headers.Location).toBe(explicit.headers.Location);
+            });
+        });
+
+        describe("query mode", () => {
+            it("appends ?token=... to a plain URL", () => {
+                const result = formatTokenResponse(token, user, "myapp://cb", undefined, "query");
+                expect(result.status).toBe(302);
+                expect(result.headers.Location).toBe(`myapp://cb?token=${encodeURIComponent(token)}`);
+            });
+
+            it("uses & when the URL already has a query string", () => {
+                const result = formatTokenResponse(token, user, "myapp://cb?foo=1", undefined, "query");
+                expect(result.headers.Location).toBe(`myapp://cb?foo=1&token=${encodeURIComponent(token)}`);
+            });
+
+            it("splices the query param BEFORE an existing fragment", () => {
+                const result = formatTokenResponse(token, user, "myapp://cb#state=xyz", undefined, "query");
+                expect(result.headers.Location).toBe(`myapp://cb?token=${encodeURIComponent(token)}#state=xyz`);
+            });
+
+            it("splices with & before fragment when query already present", () => {
+                const result = formatTokenResponse(token, user, "myapp://cb?foo=1#bar", undefined, "query");
+                expect(result.headers.Location).toBe(`myapp://cb?foo=1&token=${encodeURIComponent(token)}#bar`);
+            });
+
+            it("URL-encodes tokens with special characters", () => {
+                const weird = "a b+c/d=e";
+                const result = formatTokenResponse(weird, user, "myapp://cb", undefined, "query");
+                expect(result.headers.Location).toBe(`myapp://cb?token=${encodeURIComponent(weird)}`);
+            });
+        });
+    });
+});

package/src/OidcPlugin.ts

@@ -1,11 +1,12 @@
 import { FlinkApp, FlinkPlugin, log } from "@flink-app/flink";
+import { oidcLog, maskSecret } from "./log";
 import { Db } from "mongodb";
 import { OidcPluginOptions } from "./OidcPluginOptions";
 import { OidcPluginContext } from "./OidcPluginContext";
 import { OidcInternalContext } from "./OidcInternalContext";
 import OidcSessionRepo from "./repos/OidcSessionRepo";
 import OidcConnectionRepo from "./repos/OidcConnectionRepo";
-import { encryptToken, decryptToken, validateEncryptionSecret } from "./utils/encryption-utils";
+import { decryptToken, validateEncryptionSecret } from "./utils/encryption-utils";
 import OidcConnection from "./schemas/OidcConnection";
 import { ProviderRegistry } from "./providers/ProviderRegistry";
 import * as InitiateOidc from "./handlers/InitiateOidc";
@@ -84,16 +85,18 @@ import * as CallbackOidc from "./handlers/CallbackOidc";
  * });
  * ```
  */
-export function oidcPlugin(options: OidcPluginOptions): FlinkPlugin {
+export function oidcPlugin<TCtx = any>(options: OidcPluginOptions<TCtx>): FlinkPlugin {
     // Validation
-    if (!options.providers || Object.keys(options.providers).length === 0) {
-        throw new Error("OIDC Plugin: At least one provider must be configured");
+    const providers = options.providers || {};
+
+    if (Object.keys(providers).length === 0 && !options.providerLoader) {
+        throw new Error("OIDC Plugin: At least one provider must be configured, or providerLoader must be provided");
     }
 
     // Validate provider configurations
-    const configuredProviders = Object.keys(options.providers);
+    const configuredProviders = Object.keys(providers);
     for (const providerName of configuredProviders) {
-        const providerConfig = options.providers[providerName];
+        const providerConfig = providers[providerName];
         if (!providerConfig) continue;
 
         if (!providerConfig.issuer) {
@@ -102,9 +105,6 @@ export function oidcPlugin(options: OidcPluginOptions): FlinkPlugin {
         if (!providerConfig.clientId) {
             throw new Error(`OIDC Plugin: ${providerName} clientId is required`);
         }
-        if (!providerConfig.clientSecret) {
-            throw new Error(`OIDC Plugin: ${providerName} clientSecret is required`);
-        }
         if (!providerConfig.callbackUrl) {
             throw new Error(`OIDC Plugin: ${providerName} callbackUrl is required`);
         }
@@ -118,6 +118,17 @@ export function oidcPlugin(options: OidcPluginOptions): FlinkPlugin {
                 );
             }
         }
+
+        oidcLog.debug(
+            `Provider "${providerName}" config:`,
+            `issuer=${providerConfig.issuer}`,
+            `clientId=${providerConfig.clientId}`,
+            `clientSecret=${maskSecret(providerConfig.clientSecret)}`,
+            `callbackUrl=${providerConfig.callbackUrl}`,
+            providerConfig.discoveryUrl ? `discoveryUrl=${providerConfig.discoveryUrl}` : `authorizationEndpoint=${providerConfig.authorizationEndpoint} tokenEndpoint=${providerConfig.tokenEndpoint}`,
+            `scope=${(providerConfig.scope || ["openid", "email", "profile"]).join(" ")}`,
+            providerConfig.tokenEndpointAuthMethod ? `authMethod=${providerConfig.tokenEndpointAuthMethod}` : ""
+        );
     }
 
     if (!options.onAuthSuccess) {
@@ -127,24 +138,36 @@ export function oidcPlugin(options: OidcPluginOptions): FlinkPlugin {
     // Determine encryption key
     let encryptionKey = options.encryptionKey;
     if (!encryptionKey) {
-        // Derive from first configured provider's client secret
-        const firstProvider = configuredProviders[0];
-        const firstProviderConfig = options.providers[firstProvider];
-        if (firstProviderConfig) {
-            encryptionKey = firstProviderConfig.clientSecret;
+        // Derive from the first configured provider that has a client secret
+        const providerWithSecret = configuredProviders.find((name) => providers[name]?.clientSecret);
+        if (providerWithSecret) {
+            encryptionKey = providers[providerWithSecret].clientSecret;
             log.warn(
                 "OIDC Plugin: No encryption key provided, deriving from client secret. " + "For better security, provide a dedicated encryptionKey in options."
             );
+            oidcLog.debug(`Encryption key derived from provider "${providerWithSecret}" clientSecret`);
         }
+    } else {
+        oidcLog.debug(`Encryption key: ${maskSecret(encryptionKey)} (explicit)`);
     }
 
-    if (!encryptionKey || encryptionKey.length < 32) {
-        throw new Error("OIDC Plugin: Encryption key must be at least 32 characters");
+    // Encryption key is required when storing tokens
+    if (options.storeTokens) {
+        if (!encryptionKey || encryptionKey.length < 32) {
+            throw new Error(
+                "OIDC Plugin: Encryption key must be at least 32 characters. " +
+                    "Provide an explicit encryptionKey when using storeTokens with public clients (no clientSecret)."
+            );
+        }
+        validateEncryptionSecret(encryptionKey);
+    } else if (encryptionKey) {
+        // Validate if provided, even when not storing tokens (used for getConnection/getConnections)
+        if (encryptionKey.length < 32) {
+            throw new Error("OIDC Plugin: Encryption key must be at least 32 characters");
+        }
+        validateEncryptionSecret(encryptionKey);
     }
 
-    // Validate encryption key
-    validateEncryptionSecret(encryptionKey);
-
     let flinkApp: FlinkApp<OidcInternalContext>;
     let sessionRepo: OidcSessionRepo;
     let connectionRepo: OidcConnectionRepo;
@@ -167,6 +190,16 @@ export function oidcPlugin(options: OidcPluginOptions): FlinkPlugin {
             const sessionsCollectionName = options.sessionsCollectionName || "oidc_sessions";
             const connectionsCollectionName = options.connectionsCollectionName || "oidc_connections";
 
+            oidcLog.debug(
+                `Init: sessionsCollection=${sessionsCollectionName}`,
+                `connectionsCollection=${connectionsCollectionName}`,
+                `storeTokens=${!!options.storeTokens}`,
+                `sessionTTL=${options.sessionTTL ?? 600}s`,
+                `registerRoutes=${options.registerRoutes !== false}`,
+                configuredProviders.length > 0 ? `staticProviders=[${configuredProviders.join(", ")}]` : "staticProviders=[] (dynamic only)",
+                options.providerLoader ? "providerLoader=yes" : "providerLoader=no"
+            );
+
             sessionRepo = new OidcSessionRepo(sessionsCollectionName, db);
             connectionRepo = new OidcConnectionRepo(connectionsCollectionName, db);
 
@@ -180,7 +213,7 @@ export function oidcPlugin(options: OidcPluginOptions): FlinkPlugin {
             log.info(`OIDC Plugin: Created TTL index on ${sessionsCollectionName} with ${sessionTTL}s expiration`);
 
             // Initialize provider registry
-            providerRegistry = new ProviderRegistry(options.providers, options.providerLoader);
+            providerRegistry = new ProviderRegistry(providers, options.providerLoader, flinkApp.ctx);
 
             // Store provider registry in app context for handlers to access
             (flinkApp.ctx as any).oidcProviderRegistry = providerRegistry;
@@ -192,7 +225,7 @@ export function oidcPlugin(options: OidcPluginOptions): FlinkPlugin {
                 flinkApp.addHandler(CallbackOidc);
             }
 
-            log.info(`OIDC Plugin initialized with providers: ${configuredProviders.join(", ")}`);
+            log.info(`OIDC Plugin initialized${configuredProviders.length > 0 ? ` with providers: ${configuredProviders.join(", ")}` : " with dynamic provider loader"}`);
         } catch (error) {
             log.error("Failed to initialize OIDC Plugin:", error);
             throw error;

package/src/OidcPluginOptions.ts

@@ -1,6 +1,7 @@
 import OidcProfile from "./schemas/OidcProfile";
 import OidcTokenSet from "./schemas/OidcTokenSet";
 import { OidcProviderConfig } from "./OidcProviderConfig";
+import { TokenDeliveryMode } from "./utils/response-utils";
 
 /**
  * OIDC error information passed to onAuthError callback
@@ -41,7 +42,9 @@ export interface AuthSuccessCallbackResponse {
 
     /**
      * Optional redirect URL after authentication
-     * Plugin will append #token=... to this URL
+     *
+     * The plugin will attach the JWT token to this URL according to the
+     * top-level `tokenDelivery` option (fragment by default, or query).
      */
     redirectUrl?: string;
 }
@@ -64,7 +67,7 @@ export interface AuthErrorCallbackResponse {
  * The onAuthSuccess callback receives the Flink context as a second parameter,
  * allowing the application to generate JWT tokens using ctx.plugins.jwtAuth.createToken().
  */
-export interface OidcPluginOptions {
+export interface OidcPluginOptions<TCtx = any> {
     /**
      * OIDC provider configurations
      * Key = provider name (used in URLs: /oidc/{provider}/initiate)
@@ -89,7 +92,7 @@ export interface OidcPluginOptions {
      *   }
      * }
      */
-    providers: Record<string, OidcProviderConfig>;
+    providers?: Record<string, OidcProviderConfig>;
 
     /**
      * Whether to store OIDC tokens for future API access
@@ -120,7 +123,7 @@ export interface OidcPluginOptions {
      *
      * Example:
      * ```typescript
-     * onAuthSuccess: async ({ profile, claims, provider }, ctx) => {
+     * onAuthSuccess: async ({ profile, claims, provider, metadata }, ctx) => {
      *   // Find user by OIDC subject + issuer
      *   let user = await ctx.repos.userRepo.getOne({
      *     'oidcConnections.subject': claims.sub,
@@ -172,13 +175,35 @@ export interface OidcPluginOptions {
              */
             provider: string;
 
+            /**
+             * The redirectUri passed on the initiate request (stored in session)
+             * Use this to redirect back to the originating client application.
+             *
+             * Example:
+             * ```typescript
+             * return { user, token, redirectUrl: redirectUri || DEFAULT_REDIRECT_URL };
+             * ```
+             */
+            redirectUri: string;
+
+            /**
+             * Arbitrary metadata collected from meta.* query parameters on the initiate request.
+             * Opaque to the plugin — it only transports these values.
+             *
+             * Example: GET /oidc/acme/initiate?meta.intent=admin&meta.source=mobile
+             * Produces: { intent: "admin", source: "mobile" }
+             *
+             * Empty object ({}) if no meta.* params were provided.
+             */
+            metadata: Record<string, string>;
+
             /**
              * OIDC tokens (only if storeTokens: true)
              * Includes accessToken, idToken, refreshToken
              */
             tokens?: OidcTokenSet;
         },
-        ctx: any
+        ctx: TCtx
     ) => Promise<AuthSuccessCallbackResponse>;
 
     /**
@@ -208,7 +233,21 @@ export interface OidcPluginOptions {
      * }
      * ```
      */
-    onAuthError?: (params: { error: OidcError; provider: string }) => Promise<AuthErrorCallbackResponse>;
+    onAuthError?: (params: {
+        error: OidcError;
+        provider: string;
+        /**
+         * The redirectUri from the initiate request (if available)
+         * May be undefined for errors that occur before session lookup
+         * (e.g., IdP returns an error before we can retrieve the session)
+         */
+        redirectUri?: string;
+        /**
+         * Metadata from the initiate request (meta.* query params, prefix stripped).
+         * Empty object ({}) if no meta.* params were provided or session was not found.
+         */
+        metadata: Record<string, string>;
+    }) => Promise<AuthErrorCallbackResponse>;
 
     /**
      * Dynamic provider loader callback
@@ -219,11 +258,12 @@ export interface OidcPluginOptions {
      * Use this for multi-tenant scenarios where each organization has different IdPs.
      *
      * @param providerName - Name of the provider to load
+     * @param ctx - Flink context with access to repos and plugins
      * @returns Provider configuration or null if not found
      *
      * Example:
      * ```typescript
-     * providerLoader: async (providerName) => {
+     * providerLoader: async (providerName, ctx) => {
      *   const config = await ctx.repos.oidcProviderRepo.getByName(providerName);
      *   if (!config || !config.enabled) {
      *     return null;
@@ -239,7 +279,7 @@ export interface OidcPluginOptions {
      * }
      * ```
      */
-    providerLoader?: (providerName: string) => Promise<OidcProviderConfig | null>;
+    providerLoader?: (providerName: string, ctx: TCtx) => Promise<OidcProviderConfig | null>;
 
     /**
      * Custom collection name for OIDC sessions
@@ -265,7 +305,9 @@ export interface OidcPluginOptions {
 
     /**
      * Encryption key for encrypting stored OIDC tokens
-     * If not provided, will be derived from first configured provider's client secret
+     * If not provided, will be derived from the first configured provider's client secret
+     *
+     * Required when using storeTokens with public clients (no clientSecret).
      *
      * Recommended: Use a dedicated encryption key from environment variables
      * Must be at least 32 characters
@@ -274,6 +316,39 @@ export interface OidcPluginOptions {
      */
     encryptionKey?: string;
 
+    /**
+     * Controls how the JWT token is delivered back to the client on the
+     * post-callback redirect (ignored when the caller uses `?response_type=json`).
+     *
+     * - `"fragment"` (default): appends `#token=...` to the redirectUrl. Best
+     *   for web browsers — URL fragments are not sent to the server in HTTP
+     *   requests, which preserves a small but real security property.
+     * - `"query"`: appends `?token=...` (or `&token=...`). Required for native
+     *   mobile flows where the callback comes back via a custom URL scheme,
+     *   because iOS `ASWebAuthenticationSession` strips URL fragments before
+     *   delivering the URL to the app.
+     * - function: called once per callback to decide the delivery mode. Use
+     *   this when one app serves both web and native clients. The function
+     *   receives the resolved redirectUrl and the metadata bag from the
+     *   initiate request, so the host can route by URL scheme, by
+     *   `meta.intent`, or any other signal — the plugin makes no assumptions.
+     *
+     * Default: `"fragment"` (unchanged from prior versions).
+     *
+     * Example — route native (custom-scheme) clients to query, browsers to fragment:
+     * ```typescript
+     * tokenDelivery: ({ redirectUrl }) =>
+     *     /^https?:/i.test(redirectUrl) ? "fragment" : "query",
+     * ```
+     */
+    tokenDelivery?:
+        | TokenDeliveryMode
+        | ((params: {
+              redirectUrl: string;
+              provider: string;
+              metadata: Record<string, string>;
+          }) => TokenDeliveryMode);
+
     /**
      * Whether to register OIDC routes automatically
      * If false, you must manually handle OIDC flow

package/src/OidcProviderConfig.ts

@@ -20,8 +20,20 @@ export interface OidcProviderConfig {
     /**
      * OAuth 2.0 client secret
      * Provided by the IdP - keep this secure!
+     *
+     * Optional for public clients using PKCE-only authentication.
+     * When omitted, token_endpoint_auth_method defaults to "none".
      */
-    clientSecret: string;
+    clientSecret?: string;
+
+    /**
+     * Token endpoint authentication method
+     *
+     * - "client_secret_basic": HTTP Basic auth with client_id and client_secret (default when clientSecret is provided)
+     * - "client_secret_post": client_id and client_secret in POST body
+     * - "none": No client authentication (default when clientSecret is omitted, for public/PKCE-only clients)
+     */
+    tokenEndpointAuthMethod?: "client_secret_basic" | "client_secret_post" | "none";
 
     /**
      * Callback URL for OAuth redirect
@@ -84,4 +96,14 @@ export interface OidcProviderConfig {
      * e.g., { "department": "custom:department", "role": "custom:role" }
      */
     claimMapping?: Record<string, string>;
+
+    /**
+     * Whether to fetch additional claims from the UserInfo endpoint.
+     * Default: true
+     *
+     * Set to `false` for IdPs whose UserInfo endpoint is unreliable or
+     * returns no additional data beyond what's already in the ID token.
+     * When disabled, profiles are built from ID token claims only.
+     */
+    useUserInfoEndpoint?: boolean;
 }

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 { oidcLog } from "../log";
 
 /**
  * Path parameters for the handler
@@ -48,21 +49,40 @@ const CallbackOidc: GetHandler<any, any, PathParams, CallbackRequest> = async ({
     const { provider } = req.params;
     const { code, state, error: oidcError, error_description, response_type } = req.query;
 
+    // Track session outside try/catch so redirectUri and metadata are available in error handling
+    let sessionRedirectUri: string | undefined;
+    let sessionMetadata: Record<string, string> = {};
+
     try {
         // Validate provider and response_type
         validateProvider(provider);
         validateResponseType(response_type);
 
+        oidcLog.debug(`Callback: provider="${provider}" hasCode=${!!code} hasState=${!!state} responseType="${response_type || "redirect"}"`);
+
         // Check for OIDC provider errors (e.g., user denied access)
         if (oidcError) {
+            oidcLog.debug(`Callback: IdP returned error="${oidcError}" description="${error_description || ""}"`);
             const error = handleProviderError({ error: oidcError, error_description });
 
+            // Try to retrieve session redirectUri (state may be available even on IdP errors)
+            if (state) {
+                const errorSession = await ctx.repos.oidcSessionRepo.getByState(state);
+                sessionRedirectUri = errorSession?.redirectUri;
+                sessionMetadata = errorSession?.metadata ?? {};
+                if (errorSession) {
+                    await ctx.repos.oidcSessionRepo.deleteBySessionId(errorSession.sessionId);
+                }
+            }
+
             // Call onAuthError callback if provided
             const { options } = ctx.plugins.oidc;
             if (options.onAuthError) {
                 const errorResult = await options.onAuthError({
                     error,
                     provider,
+                    redirectUri: sessionRedirectUri,
+                    metadata: sessionMetadata,
                 });
 
                 if (errorResult.redirectUrl) {
@@ -89,9 +109,12 @@ const CallbackOidc: GetHandler<any, any, PathParams, CallbackRequest> = async ({
         const session = await ctx.repos.oidcSessionRepo.getByState(state);
 
         if (!session) {
+            oidcLog.debug(`Callback: no session found for state (may be expired)`);
             throw createOidcError(OidcErrorCodes.SESSION_EXPIRED, "OIDC session not found or expired. Please try logging in again.", { state });
         }
 
+        oidcLog.debug(`Callback: session found sessionId=${session.sessionId} provider="${session.provider}" redirectUri="${session.redirectUri}"`);
+
         // Validate state parameter (CSRF protection)
         if (!validateState(state, session.state)) {
             throw createOidcError(OidcErrorCodes.INVALID_STATE, "Invalid state parameter. Possible CSRF attack detected.", {
@@ -99,8 +122,13 @@ const CallbackOidc: GetHandler<any, any, PathParams, CallbackRequest> = async ({
             });
         }
 
+        // Track redirectUri and metadata for error handling
+        sessionRedirectUri = session.redirectUri;
+        sessionMetadata = session.metadata ?? {};
+
         // Delete session immediately after validation (one-time use)
         await ctx.repos.oidcSessionRepo.deleteBySessionId(session.sessionId);
+        oidcLog.debug(`Callback: state validated, session deleted (one-time use)`);
 
         // Get plugin options
         const { options } = ctx.plugins.oidc;
@@ -121,14 +149,26 @@ const CallbackOidc: GetHandler<any, any, PathParams, CallbackRequest> = async ({
             nonce: session.nonce,
         });
 
-        // Build user profile from ID token and UserInfo
-        const profile = await oidcProvider.buildProfile(tokenSet, true);
+        oidcLog.debug(
+            `Callback: token exchange successful`,
+            `sub="${tokenSet.claims.sub}"`,
+            `iss="${tokenSet.claims.iss}"`,
+            `email="${tokenSet.claims.email || "(none)"}"`,
+            `hasRefreshToken=${!!tokenSet.refreshToken}`,
+            `expiresIn=${tokenSet.expiresIn ?? "(none)"}s`
+        );
+
+        // Build user profile from ID token and (optionally) UserInfo
+        const profile = await oidcProvider.buildProfile(tokenSet, oidcProvider.config.useUserInfoEndpoint ?? true);
+        oidcLog.debug(`Callback: profile built id="${profile.id}" email="${profile.email || "(none)"}" name="${profile.name || "(none)"}"`);
 
         // Call onAuthSuccess callback to create/link user and generate JWT token
         const authSuccessParams = {
             profile,
             claims: tokenSet.claims,
             provider,
+            redirectUri: session.redirectUri,
+            metadata: sessionMetadata,
             ...(options.storeTokens ? { tokens: tokenSet } : {}),
         };
 
@@ -148,6 +188,8 @@ const CallbackOidc: GetHandler<any, any, PathParams, CallbackRequest> = async ({
                 const errorResult = await options.onAuthError({
                     error: oidcError,
                     provider,
+                    redirectUri: session.redirectUri,
+                    metadata: sessionMetadata,
                 });
 
                 if (errorResult.redirectUrl) {
@@ -172,7 +214,7 @@ const CallbackOidc: GetHandler<any, any, PathParams, CallbackRequest> = async ({
         // Store OIDC connection if token storage is enabled
         if (options.storeTokens && user && user._id) {
             // Get encryption secret (use provider client secret or global encryption key)
-            const staticProviderConfig = options.providers[provider];
+            const staticProviderConfig = options.providers?.[provider];
             const encryptionSecret = options.encryptionKey || staticProviderConfig?.clientSecret;
 
             if (!encryptionSecret) {
@@ -190,7 +232,8 @@ const CallbackOidc: GetHandler<any, any, PathParams, CallbackRequest> = async ({
                 const existingConnection = await ctx.repos.oidcConnectionRepo.findByUserAndProvider(user._id, provider);
 
                 if (existingConnection) {
-                    await ctx.repos.oidcConnectionRepo.updateOne(existingConnection._id!, {
+                    oidcLog.debug(`Callback: updating existing connection for userId=${user._id} provider="${provider}"`);
+                    await ctx.repos.oidcConnectionRepo.updateById(existingConnection._id!, {
                         accessToken: encryptedAccessToken,
                         idToken: encryptedIdToken,
                         refreshToken: encryptedRefreshToken,
@@ -199,6 +242,7 @@ const CallbackOidc: GetHandler<any, any, PathParams, CallbackRequest> = async ({
                         updatedAt: new Date(),
                     });
                 } else {
+                    oidcLog.debug(`Callback: creating new connection for userId=${user._id} provider="${provider}" subject="${tokenSet.claims.sub}"`);
                     await ctx.repos.oidcConnectionRepo.create({
                         userId: user._id,
                         provider,
@@ -217,8 +261,23 @@ const CallbackOidc: GetHandler<any, any, PathParams, CallbackRequest> = async ({
             }
         }
 
+        const finalRedirectUrl = redirectUrl || session.redirectUri;
+        oidcLog.debug(`Callback: auth complete, responding via ${response_type === "json" ? "JSON" : `redirect to "${finalRedirectUrl}"`}`);
+
+        // Resolve token delivery mode: literal, function, or default "fragment".
+        // The plugin stays a dumb transport — the host app makes the policy decision.
+        const tokenDeliverySetting = options.tokenDelivery ?? "fragment";
+        const resolvedTokenDelivery =
+            typeof tokenDeliverySetting === "function"
+                ? tokenDeliverySetting({
+                      redirectUrl: finalRedirectUrl,
+                      provider,
+                      metadata: sessionMetadata,
+                  })
+                : tokenDeliverySetting;
+
         // Return JWT token in requested format
-        return formatTokenResponse(token, user, redirectUrl || session.redirectUri, response_type);
+        return formatTokenResponse(token, user, finalRedirectUrl, response_type, resolvedTokenDelivery);
     } catch (error: any) {
         log.error("OIDC callback error:", error);
 
@@ -231,6 +290,8 @@ const CallbackOidc: GetHandler<any, any, PathParams, CallbackRequest> = async ({
                     const errorResult = await options.onAuthError({
                         error,
                         provider,
+                        redirectUri: sessionRedirectUri,
+                        metadata: sessionMetadata,
                     });
 
                     if (errorResult.redirectUrl) {