@flink-app/oidc-plugin 2.0.0-alpha.78 → 2.0.0-alpha.80

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @flink-app/oidc-plugin
 
+## 2.0.0-alpha.80
+
+### Patch Changes
+
+-   Add flink.oidc named logger with debug instrumentation across init, provider resolution, and auth flow
+    -   @flink-app/flink@2.0.0-alpha.80
+    -   @flink-app/jwt-auth-plugin@2.0.0-alpha.80
+
+## 2.0.0-alpha.79
+
+### Patch Changes
+
+-   Expose redirectUri from session in onAuthSuccess and onAuthError callbacks, enabling multi-client redirect decisions
+    -   @flink-app/flink@2.0.0-alpha.79
+    -   @flink-app/jwt-auth-plugin@2.0.0-alpha.79
+
 ## 2.0.0-alpha.78
 
 ### Patch Changes

package/dist/OidcPlugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"OidcPlugin.d.ts","sourceRoot":"","sources":["../src/OidcPlugin.ts"],"names":[],"mappings":"AAAA,OAAO,EAAY,WAAW,EAAO,MAAM,kBAAkB,CAAC;AAE9D,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAWxD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwEG;AACH,wBAAgB,UAAU,CAAC,IAAI,GAAG,GAAG,EAAE,OAAO,EAAE,iBAAiB,CAAC,IAAI,CAAC,GAAG,WAAW,CAmNpF"}
+{"version":3,"file":"OidcPlugin.d.ts","sourceRoot":"","sources":["../src/OidcPlugin.ts"],"names":[],"mappings":"AAAA,OAAO,EAAY,WAAW,EAAO,MAAM,kBAAkB,CAAC;AAG9D,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAWxD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwEG;AACH,wBAAgB,UAAU,CAAC,IAAI,GAAG,GAAG,EAAE,OAAO,EAAE,iBAAiB,CAAC,IAAI,CAAC,GAAG,WAAW,CA2OpF"}

package/dist/OidcPlugin.js

@@ -28,6 +28,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.oidcPlugin = oidcPlugin;
 const flink_1 = require("@flink-app/flink");
+const log_1 = require("./log");
 const OidcSessionRepo_1 = __importDefault(require("./repos/OidcSessionRepo"));
 const OidcConnectionRepo_1 = __importDefault(require("./repos/OidcConnectionRepo"));
 const encryption_utils_1 = require("./utils/encryption-utils");
@@ -135,6 +136,7 @@ function oidcPlugin(options) {
                     `(authorizationEndpoint, tokenEndpoint, jwksUri)`);
             }
         }
+        log_1.oidcLog.debug(`Provider "${providerName}" config:`, `issuer=${providerConfig.issuer}`, `clientId=${providerConfig.clientId}`, `clientSecret=${(0, log_1.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) {
         throw new Error("OIDC Plugin: onAuthSuccess callback is required");
@@ -147,8 +149,12 @@ function oidcPlugin(options) {
         if (providerWithSecret) {
             encryptionKey = providers[providerWithSecret].clientSecret;
             flink_1.log.warn("OIDC Plugin: No encryption key provided, deriving from client secret. " + "For better security, provide a dedicated encryptionKey in options.");
+            log_1.oidcLog.debug(`Encryption key derived from provider "${providerWithSecret}" clientSecret`);
         }
     }
+    else {
+        log_1.oidcLog.debug(`Encryption key: ${(0, log_1.maskSecret)(encryptionKey)} (explicit)`);
+    }
     // Encryption key is required when storing tokens
     if (options.storeTokens) {
         if (!encryptionKey || encryptionKey.length < 32) {
@@ -181,6 +187,7 @@ function oidcPlugin(options) {
             // Initialize repositories
             const sessionsCollectionName = options.sessionsCollectionName || "oidc_sessions";
             const connectionsCollectionName = options.connectionsCollectionName || "oidc_connections";
+            log_1.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_1.default(sessionsCollectionName, db);
             connectionRepo = new OidcConnectionRepo_1.default(connectionsCollectionName, db);
             flinkApp.addRepo("oidcSessionRepo", sessionRepo);

package/dist/OidcPluginOptions.d.ts

@@ -158,6 +158,16 @@ export interface OidcPluginOptions<TCtx = any> {
          * Provider name (e.g., "acme", "contoso")
          */
         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;
         /**
          * OIDC tokens (only if storeTokens: true)
          * Includes accessToken, idToken, refreshToken
@@ -194,6 +204,12 @@ export interface OidcPluginOptions<TCtx = any> {
     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;
     }) => Promise<AuthErrorCallbackResponse>;
     /**
      * Dynamic provider loader callback

package/dist/OidcPluginOptions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"OidcPluginOptions.d.ts","sourceRoot":"","sources":["../src/OidcPluginOptions.ts"],"names":[],"mappings":"AAAA,OAAO,WAAW,MAAM,uBAAuB,CAAC;AAChD,OAAO,YAAY,MAAM,wBAAwB,CAAC;AAClD,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE1D;;GAEG;AACH,MAAM,WAAW,SAAS;IACtB;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,OAAO,CAAC,EAAE,GAAG,CAAC;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,2BAA2B;IACxC;;;OAGG;IACH,IAAI,EAAE,GAAG,CAAC;IAEV;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACtC;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB,CAAC,IAAI,GAAG,GAAG;IACzC;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;IAE/C;;;;;;;;;;;OAWG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IAEtB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgDG;IACH,aAAa,EAAE,CACX,MAAM,EAAE;QACJ;;WAEG;QACH,OAAO,EAAE,WAAW,CAAC;QAErB;;;WAGG;QACH,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QAE5B;;WAEG;QACH,QAAQ,EAAE,MAAM,CAAC;QAEjB;;;WAGG;QACH,MAAM,CAAC,EAAE,YAAY,CAAC;KACzB,EACD,GAAG,EAAE,IAAI,KACR,OAAO,CAAC,2BAA2B,CAAC,CAAC;IAE1C;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE;QAAE,KAAK,EAAE,SAAS,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,yBAAyB,CAAC,CAAC;IAErG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,cAAc,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,KAAK,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAAC;IAEzF;;;OAGG;IACH,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAEhC;;;OAGG;IACH,yBAAyB,CAAC,EAAE,MAAM,CAAC;IAEnC;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;;;;;;;;OAUG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC5B"}
+{"version":3,"file":"OidcPluginOptions.d.ts","sourceRoot":"","sources":["../src/OidcPluginOptions.ts"],"names":[],"mappings":"AAAA,OAAO,WAAW,MAAM,uBAAuB,CAAC;AAChD,OAAO,YAAY,MAAM,wBAAwB,CAAC;AAClD,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE1D;;GAEG;AACH,MAAM,WAAW,SAAS;IACtB;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,OAAO,CAAC,EAAE,GAAG,CAAC;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,2BAA2B;IACxC;;;OAGG;IACH,IAAI,EAAE,GAAG,CAAC;IAEV;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACtC;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB,CAAC,IAAI,GAAG,GAAG;IACzC;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;IAE/C;;;;;;;;;;;OAWG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IAEtB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgDG;IACH,aAAa,EAAE,CACX,MAAM,EAAE;QACJ;;WAEG;QACH,OAAO,EAAE,WAAW,CAAC;QAErB;;;WAGG;QACH,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QAE5B;;WAEG;QACH,QAAQ,EAAE,MAAM,CAAC;QAEjB;;;;;;;;WAQG;QACH,WAAW,EAAE,MAAM,CAAC;QAEpB;;;WAGG;QACH,MAAM,CAAC,EAAE,YAAY,CAAC;KACzB,EACD,GAAG,EAAE,IAAI,KACR,OAAO,CAAC,2BAA2B,CAAC,CAAC;IAE1C;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE;QACnB,KAAK,EAAE,SAAS,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;QACjB;;;;WAIG;QACH,WAAW,CAAC,EAAE,MAAM,CAAC;KACxB,KAAK,OAAO,CAAC,yBAAyB,CAAC,CAAC;IAEzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,cAAc,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,KAAK,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAAC;IAEzF;;;OAGG;IACH,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAEhC;;;OAGG;IACH,yBAAyB,CAAC,EAAE,MAAM,CAAC;IAEnC;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;;;;;;;;OAUG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC5B"}

package/dist/handlers/CallbackOidc.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CallbackOidc.d.ts","sourceRoot":"","sources":["../../src/handlers/CallbackOidc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,UAAU,EAAc,UAAU,EAAwC,MAAM,kBAAkB,CAAC;AAC5G,OAAO,eAAe,MAAM,4BAA4B,CAAC;AAMzD;;GAEG;AACH,UAAU,UAAU;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;CACzB;AAED;;;GAGG;AACH,eAAO,MAAM,KAAK,EAAE,UAGnB,CAAC;AAEF;;;;;;GAMG;AACH,QAAA,MAAM,YAAY,EAAE,UAAU,CAAC,GAAG,EAAE,GAAG,EAAE,UAAU,EAAE,eAAe,CAgNnE,CAAC;AAEF,eAAe,YAAY,CAAC"}
+{"version":3,"file":"CallbackOidc.d.ts","sourceRoot":"","sources":["../../src/handlers/CallbackOidc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,UAAU,EAAc,UAAU,EAAwC,MAAM,kBAAkB,CAAC;AAC5G,OAAO,eAAe,MAAM,4BAA4B,CAAC;AAOzD;;GAEG;AACH,UAAU,UAAU;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;CACzB;AAED;;;GAGG;AACH,eAAO,MAAM,KAAK,EAAE,UAGnB,CAAC;AAEF;;;;;;GAMG;AACH,QAAA,MAAM,YAAY,EAAE,UAAU,CAAC,GAAG,EAAE,GAAG,EAAE,UAAU,EAAE,eAAe,CA4PnE,CAAC;AAEF,eAAe,YAAY,CAAC"}

package/dist/handlers/CallbackOidc.js

@@ -20,6 +20,7 @@ const state_utils_1 = require("../utils/state-utils");
 const response_utils_1 = require("../utils/response-utils");
 const encryption_utils_1 = require("../utils/encryption-utils");
 const error_utils_1 = require("../utils/error-utils");
+const log_1 = require("../log");
 /**
  * Route configuration
  * This handler is registered programmatically by the plugin
@@ -38,19 +39,32 @@ exports.Route = {
 const CallbackOidc = async ({ ctx, req }) => {
     const { provider } = req.params;
     const { code, state, error: oidcError, error_description, response_type } = req.query;
+    // Track session outside try/catch so redirectUri is available in error handling
+    let sessionRedirectUri;
     try {
         // Validate provider and response_type
         (0, error_utils_1.validateProvider)(provider);
         (0, error_utils_1.validateResponseType)(response_type);
+        log_1.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) {
+            log_1.oidcLog.debug(`Callback: IdP returned error="${oidcError}" description="${error_description || ""}"`);
             const error = (0, error_utils_1.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;
+                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,
                 });
                 if (errorResult.redirectUrl) {
                     return {
@@ -72,16 +86,21 @@ const CallbackOidc = async ({ ctx, req }) => {
         // Find OIDC session by state
         const session = await ctx.repos.oidcSessionRepo.getByState(state);
         if (!session) {
+            log_1.oidcLog.debug(`Callback: no session found for state (may be expired)`);
             throw (0, error_utils_1.createOidcError)(error_utils_1.OidcErrorCodes.SESSION_EXPIRED, "OIDC session not found or expired. Please try logging in again.", { state });
         }
+        log_1.oidcLog.debug(`Callback: session found sessionId=${session.sessionId} provider="${session.provider}" redirectUri="${session.redirectUri}"`);
         // Validate state parameter (CSRF protection)
         if (!(0, state_utils_1.validateState)(state, session.state)) {
             throw (0, error_utils_1.createOidcError)(error_utils_1.OidcErrorCodes.INVALID_STATE, "Invalid state parameter. Possible CSRF attack detected.", {
                 providedState: state.substring(0, 10) + "...",
             });
         }
+        // Track redirectUri for error handling
+        sessionRedirectUri = session.redirectUri;
         // Delete session immediately after validation (one-time use)
         await ctx.repos.oidcSessionRepo.deleteBySessionId(session.sessionId);
+        log_1.oidcLog.debug(`Callback: state validated, session deleted (one-time use)`);
         // Get plugin options
         const { options } = ctx.plugins.oidc;
         // Get provider instance
@@ -91,19 +110,25 @@ const CallbackOidc = async ({ ctx, req }) => {
         }
         const oidcProvider = await providerRegistry.getProvider(provider);
         // Exchange authorization code for tokens with PKCE validation
+        log_1.oidcLog.debug(`Callback: exchanging authorization code for tokens`);
         const tokenSet = await oidcProvider.exchangeCodeForToken({
             code,
             codeVerifier: session.codeVerifier,
             state: session.state,
             nonce: session.nonce,
         });
+        log_1.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 UserInfo
+        log_1.oidcLog.debug(`Callback: building user profile`);
         const profile = await oidcProvider.buildProfile(tokenSet, true);
+        log_1.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
+        log_1.oidcLog.debug(`Callback: calling onAuthSuccess`);
         const authSuccessParams = {
             profile,
             claims: tokenSet.claims,
             provider,
+            redirectUri: session.redirectUri,
             ...(options.storeTokens ? { tokens: tokenSet } : {}),
         };
         let authResult;
@@ -121,6 +146,7 @@ const CallbackOidc = async ({ ctx, req }) => {
                 const errorResult = await options.onAuthError({
                     error: oidcError,
                     provider,
+                    redirectUri: session.redirectUri,
                 });
                 if (errorResult.redirectUrl) {
                     return {
@@ -132,6 +158,7 @@ const CallbackOidc = async ({ ctx, req }) => {
             }
             return (0, flink_1.internalServerError)("Authentication failed. Please try again.");
         }
+        log_1.oidcLog.debug(`Callback: onAuthSuccess completed`);
         // Extract user and JWT token from callback result
         const { user, token, redirectUrl } = authResult;
         if (!token) {
@@ -182,8 +209,10 @@ const CallbackOidc = async ({ ctx, req }) => {
                 }
             }
         }
+        const finalRedirectUrl = redirectUrl || session.redirectUri;
+        log_1.oidcLog.debug(`Callback: auth complete, responding via ${response_type === "json" ? "JSON" : `redirect to "${finalRedirectUrl}"`}`);
         // Return JWT token in requested format
-        return (0, response_utils_1.formatTokenResponse)(token, user, redirectUrl || session.redirectUri, response_type);
+        return (0, response_utils_1.formatTokenResponse)(token, user, finalRedirectUrl, response_type);
     }
     catch (error) {
         flink_1.log.error("OIDC callback error:", error);
@@ -196,6 +225,7 @@ const CallbackOidc = async ({ ctx, req }) => {
                     const errorResult = await options.onAuthError({
                         error,
                         provider,
+                        redirectUri: sessionRedirectUri,
                     });
                     if (errorResult.redirectUrl) {
                         return {

package/dist/handlers/InitiateOidc.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"InitiateOidc.d.ts","sourceRoot":"","sources":["../../src/handlers/InitiateOidc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,UAAU,EAAc,UAAU,EAAmC,MAAM,kBAAkB,CAAC;AACvG,OAAO,eAAe,MAAM,4BAA4B,CAAC;AAKzD;;GAEG;AACH,UAAU,UAAU;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;CACzB;AAED;;;GAGG;AACH,eAAO,MAAM,KAAK,EAAE,UAGnB,CAAC;AAEF;;;;;GAKG;AACH,QAAA,MAAM,YAAY,EAAE,UAAU,CAAC,GAAG,EAAE,GAAG,EAAE,UAAU,EAAE,eAAe,CAiEnE,CAAC;AAEF,eAAe,YAAY,CAAC"}
+{"version":3,"file":"InitiateOidc.d.ts","sourceRoot":"","sources":["../../src/handlers/InitiateOidc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,UAAU,EAAc,UAAU,EAAmC,MAAM,kBAAkB,CAAC;AACvG,OAAO,eAAe,MAAM,4BAA4B,CAAC;AAMzD;;GAEG;AACH,UAAU,UAAU;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;CACzB;AAED;;;GAGG;AACH,eAAO,MAAM,KAAK,EAAE,UAGnB,CAAC;AAEF;;;;;GAKG;AACH,QAAA,MAAM,YAAY,EAAE,UAAU,CAAC,GAAG,EAAE,GAAG,EAAE,UAAU,EAAE,eAAe,CAyEnE,CAAC;AAEF,eAAe,YAAY,CAAC"}

package/dist/handlers/InitiateOidc.js

@@ -17,6 +17,7 @@ const flink_1 = require("@flink-app/flink");
 const state_utils_1 = require("../utils/state-utils");
 const error_utils_1 = require("../utils/error-utils");
 const openid_client_1 = require("openid-client");
+const log_1 = require("../log");
 /**
  * Route configuration
  * This handler is registered programmatically by the plugin
@@ -37,6 +38,7 @@ const InitiateOidc = async ({ ctx, req }) => {
     try {
         // Validate provider name format
         (0, error_utils_1.validateProvider)(provider);
+        log_1.oidcLog.debug(`Initiate: provider="${provider}" redirectUri="${redirectUri || "(not set)"}"`);
         // Get provider registry from context
         const providerRegistry = ctx.oidcProviderRegistry;
         if (!providerRegistry) {
@@ -49,6 +51,7 @@ const InitiateOidc = async ({ ctx, req }) => {
         // 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`;
+        log_1.oidcLog.debug(`Initiate: resolved redirectUri="${finalRedirectUri}" (source: ${redirectUri ? "query param" : staticProviderConfig?.callbackUrl ? "provider config" : "auto-detected"})`);
         // Generate cryptographically secure parameters
         const state = (0, state_utils_1.generateState)();
         const sessionId = (0, state_utils_1.generateSessionId)();
@@ -64,12 +67,14 @@ const InitiateOidc = async ({ ctx, req }) => {
             redirectUri: finalRedirectUri,
             createdAt: new Date(),
         });
+        log_1.oidcLog.debug(`Initiate: session created sessionId=${sessionId}`);
         // Build authorization URL with PKCE and nonce
         const authorizationUrl = await oidcProvider.getAuthorizationUrl({
             state,
             codeVerifier,
             nonce,
         });
+        log_1.oidcLog.debug(`Initiate: redirecting to IdP authorization URL`);
         // Redirect user to provider's authorization page
         return {
             status: 302,

package/dist/log.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Named logger for the OIDC plugin.
+ *
+ * Enables independent log level control via flink.config.js:
+ * ```js
+ * module.exports = {
+ *   logging: {
+ *     components: {
+ *       "flink.oidc": "debug"
+ *     }
+ *   }
+ * };
+ * ```
+ *
+ * Or at runtime:
+ * ```ts
+ * FlinkLogFactory.setComponentLevel("flink.oidc", "debug");
+ * ```
+ */
+export declare const oidcLog: import("@flink-app/flink").ComponentLogger;
+/**
+ * Mask a secret value for safe logging.
+ * Shows the first 4 characters followed by **** to help identify which secret
+ * is in use without exposing the full value.
+ */
+export declare function maskSecret(value: string | undefined): string;
+//# sourceMappingURL=log.d.ts.map

package/dist/log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"log.d.ts","sourceRoot":"","sources":["../src/log.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,OAAO,4CAA6C,CAAC;AAElE;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAI5D"}

package/dist/log.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.oidcLog = void 0;
+exports.maskSecret = maskSecret;
+const flink_1 = require("@flink-app/flink");
+/**
+ * Named logger for the OIDC plugin.
+ *
+ * Enables independent log level control via flink.config.js:
+ * ```js
+ * module.exports = {
+ *   logging: {
+ *     components: {
+ *       "flink.oidc": "debug"
+ *     }
+ *   }
+ * };
+ * ```
+ *
+ * Or at runtime:
+ * ```ts
+ * FlinkLogFactory.setComponentLevel("flink.oidc", "debug");
+ * ```
+ */
+exports.oidcLog = flink_1.FlinkLogFactory.createLogger("flink.oidc");
+/**
+ * Mask a secret value for safe logging.
+ * Shows the first 4 characters followed by **** to help identify which secret
+ * is in use without exposing the full value.
+ */
+function maskSecret(value) {
+    if (!value)
+        return "(not set)";
+    if (value.length <= 4)
+        return "****";
+    return `${value.slice(0, 4)}****`;
+}

package/dist/providers/ProviderRegistry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ProviderRegistry.d.ts","sourceRoot":"","sources":["../../src/providers/ProviderRegistry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAG3D;;;;;;;;GAQG;AACH,qBAAa,gBAAgB;IACzB,OAAO,CAAC,eAAe,CAAqC;IAC5D,OAAO,CAAC,iBAAiB,CAAwC;IACjE,OAAO,CAAC,cAAc,CAAC,CAAyE;IAChG,OAAO,CAAC,GAAG,CAAM;gBAGb,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,EACnD,cAAc,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,KAAK,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,EACvF,GAAG,CAAC,EAAE,GAAG;IAOb;;;;;;;;;;;;;OAaG;IACG,WAAW,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAgC9D;;;;;OAKG;IACH,WAAW,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO;IAI1C;;;;;;;OAOG;IACH,UAAU,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI;IAQvC;;;;OAIG;IACH,gBAAgB,IAAI,MAAM,EAAE;CAG/B"}
+{"version":3,"file":"ProviderRegistry.d.ts","sourceRoot":"","sources":["../../src/providers/ProviderRegistry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAI3D;;;;;;;;GAQG;AACH,qBAAa,gBAAgB;IACzB,OAAO,CAAC,eAAe,CAAqC;IAC5D,OAAO,CAAC,iBAAiB,CAAwC;IACjE,OAAO,CAAC,cAAc,CAAC,CAAyE;IAChG,OAAO,CAAC,GAAG,CAAM;gBAGb,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,EACnD,cAAc,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,KAAK,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,EACvF,GAAG,CAAC,EAAE,GAAG;IAOb;;;;;;;;;;;;;OAaG;IACG,WAAW,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAiD9D;;;;;OAKG;IACH,WAAW,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO;IAI1C;;;;;;;OAOG;IACH,UAAU,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI;IAQvC;;;;OAIG;IACH,gBAAgB,IAAI,MAAM,EAAE;CAG/B"}

package/dist/providers/ProviderRegistry.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ProviderRegistry = void 0;
 const OidcProvider_1 = require("./OidcProvider");
 const error_utils_1 = require("../utils/error-utils");
+const log_1 = require("../log");
 /**
  * Provider registry for managing OIDC provider instances
  *
@@ -37,23 +38,31 @@ class ProviderRegistry {
         // Check cache first
         const cachedProvider = this.providerInstances.get(providerName);
         if (cachedProvider) {
+            log_1.oidcLog.debug(`Provider "${providerName}": using cached instance`);
             return cachedProvider;
         }
         // Try static configuration
         let config = this.staticProviders[providerName] || null;
+        let configSource = "static";
         // Try dynamic loader if not in static config
         if (!config && this.providerLoader) {
+            log_1.oidcLog.debug(`Provider "${providerName}": not in static config, invoking providerLoader`);
             config = await this.providerLoader(providerName, this.ctx);
+            configSource = "dynamic";
         }
         if (!config) {
+            log_1.oidcLog.debug(`Provider "${providerName}": not found (static=[${Object.keys(this.staticProviders).join(", ")}], loader=${!!this.providerLoader})`);
             throw (0, error_utils_1.createOidcError)(error_utils_1.OidcErrorCodes.PROVIDER_NOT_CONFIGURED, `OIDC provider '${providerName}' is not configured`, {
                 providerName,
                 availableProviders: Object.keys(this.staticProviders),
             });
         }
+        log_1.oidcLog.debug(`Provider "${providerName}" resolved via ${configSource}:`, `issuer=${config.issuer}`, `clientId=${config.clientId}`, `clientSecret=${(0, log_1.maskSecret)(config.clientSecret)}`, `callbackUrl=${config.callbackUrl}`, config.discoveryUrl ? `discoveryUrl=${config.discoveryUrl}` : `authorizationEndpoint=${config.authorizationEndpoint}`, `scope=${(config.scope || ["openid", "email", "profile"]).join(" ")}`);
         // Create and initialize provider
+        log_1.oidcLog.debug(`Provider "${providerName}": initializing OIDC client`);
         const provider = new OidcProvider_1.OidcProvider(config);
         await provider.initialize();
+        log_1.oidcLog.debug(`Provider "${providerName}": initialized successfully`);
         // Cache the instance
         this.providerInstances.set(providerName, provider);
         return provider;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flink-app/oidc-plugin",
-  "version": "2.0.0-alpha.78",
+  "version": "2.0.0-alpha.80",
   "description": "Flink plugin for OIDC authentication with generic IdP support",
   "author": "joel@frost.se",
   "license": "MIT",
@@ -11,10 +11,10 @@
   },
   "dependencies": {
     "openid-client": "^5.7.0",
-    "@flink-app/jwt-auth-plugin": "2.0.0-alpha.78"
+    "@flink-app/jwt-auth-plugin": "2.0.0-alpha.80"
   },
   "peerDependencies": {
-    "@flink-app/flink": ">=2.0.0-alpha.78",
+    "@flink-app/flink": ">=2.0.0-alpha.80",
     "mongodb": "^6.15.0"
   },
   "peerDependenciesMeta": {
@@ -27,9 +27,9 @@
     "@types/node": "22.13.10",
     "ts-node": "^10.9.2",
     "tsc-watch": "^4.2.9",
-    "@flink-app/jwt-auth-plugin": "2.0.0-alpha.78",
-    "@flink-app/test-utils": "2.0.0-alpha.78",
-    "@flink-app/flink": "2.0.0-alpha.78"
+    "@flink-app/jwt-auth-plugin": "2.0.0-alpha.80",
+    "@flink-app/test-utils": "2.0.0-alpha.80",
+    "@flink-app/flink": "2.0.0-alpha.80"
   },
   "scripts": {
     "test": "jasmine-ts --config=./spec/support/jasmine.json",

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";
@@ -117,6 +118,17 @@ export function oidcPlugin<TCtx = any>(options: OidcPluginOptions<TCtx>): FlinkP
                 );
             }
         }
+
+        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) {
@@ -133,7 +145,10 @@ export function oidcPlugin<TCtx = any>(options: OidcPluginOptions<TCtx>): FlinkP
             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)`);
     }
 
     // Encryption key is required when storing tokens
@@ -175,6 +190,16 @@ export function oidcPlugin<TCtx = any>(options: OidcPluginOptions<TCtx>): FlinkP
             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);
 

package/src/OidcPluginOptions.ts

@@ -172,6 +172,17 @@ export interface OidcPluginOptions<TCtx = any> {
              */
             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;
+
             /**
              * OIDC tokens (only if storeTokens: true)
              * Includes accessToken, idToken, refreshToken
@@ -208,7 +219,16 @@ export interface OidcPluginOptions<TCtx = any> {
      * }
      * ```
      */
-    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;
+    }) => Promise<AuthErrorCallbackResponse>;
 
     /**
      * Dynamic provider loader callback

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,37 @@ 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 is available in error handling
+    let sessionRedirectUri: string | undefined;
+
     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;
+                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,
                 });
 
                 if (errorResult.redirectUrl) {
@@ -89,9 +106,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 +119,12 @@ const CallbackOidc: GetHandler<any, any, PathParams, CallbackRequest> = async ({
             });
         }
 
+        // Track redirectUri for error handling
+        sessionRedirectUri = session.redirectUri;
+
         // 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;
@@ -114,6 +138,7 @@ const CallbackOidc: GetHandler<any, any, PathParams, CallbackRequest> = async ({
         const oidcProvider = await providerRegistry.getProvider(provider);
 
         // Exchange authorization code for tokens with PKCE validation
+        oidcLog.debug(`Callback: exchanging authorization code for tokens`);
         const tokenSet = await oidcProvider.exchangeCodeForToken({
             code,
             codeVerifier: session.codeVerifier,
@@ -121,14 +146,27 @@ const CallbackOidc: GetHandler<any, any, PathParams, CallbackRequest> = async ({
             nonce: session.nonce,
         });
 
+        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 UserInfo
+        oidcLog.debug(`Callback: building user profile`);
         const profile = await oidcProvider.buildProfile(tokenSet, 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
+        oidcLog.debug(`Callback: calling onAuthSuccess`);
         const authSuccessParams = {
             profile,
             claims: tokenSet.claims,
             provider,
+            redirectUri: session.redirectUri,
             ...(options.storeTokens ? { tokens: tokenSet } : {}),
         };
 
@@ -148,6 +186,7 @@ const CallbackOidc: GetHandler<any, any, PathParams, CallbackRequest> = async ({
                 const errorResult = await options.onAuthError({
                     error: oidcError,
                     provider,
+                    redirectUri: session.redirectUri,
                 });
 
                 if (errorResult.redirectUrl) {
@@ -162,6 +201,8 @@ const CallbackOidc: GetHandler<any, any, PathParams, CallbackRequest> = async ({
             return internalServerError("Authentication failed. Please try again.");
         }
 
+        oidcLog.debug(`Callback: onAuthSuccess completed`);
+
         // Extract user and JWT token from callback result
         const { user, token, redirectUrl } = authResult;
 
@@ -217,8 +258,11 @@ 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}"`}`);
+
         // Return JWT token in requested format
-        return formatTokenResponse(token, user, redirectUrl || session.redirectUri, response_type);
+        return formatTokenResponse(token, user, finalRedirectUrl, response_type);
     } catch (error: any) {
         log.error("OIDC callback error:", error);
 
@@ -231,6 +275,7 @@ const CallbackOidc: GetHandler<any, any, PathParams, CallbackRequest> = async ({
                     const errorResult = await options.onAuthError({
                         error,
                         provider,
+                        redirectUri: sessionRedirectUri,
                     });
 
                     if (errorResult.redirectUrl) {

package/src/handlers/InitiateOidc.ts

@@ -16,6 +16,7 @@ import InitiateRequest from "../schemas/InitiateRequest";
 import { generateState, generateSessionId, generateNonce } from "../utils/state-utils";
 import { validateProvider, createOidcError, OidcErrorCodes } from "../utils/error-utils";
 import { generators } from "openid-client";
+import { oidcLog } from "../log";
 
 /**
  * Path parameters for the handler
@@ -48,6 +49,8 @@ const InitiateOidc: GetHandler<any, any, PathParams, InitiateRequest> = async ({
         // Validate provider name format
         validateProvider(provider);
 
+        oidcLog.debug(`Initiate: provider="${provider}" redirectUri="${redirectUri || "(not set)"}"`);
+
         // Get provider registry from context
         const providerRegistry = (ctx as any).oidcProviderRegistry;
         if (!providerRegistry) {
@@ -64,6 +67,8 @@ const InitiateOidc: GetHandler<any, any, PathParams, InitiateRequest> = async ({
         const staticProviderConfig = options.providers?.[provider];
         const finalRedirectUri = redirectUri || staticProviderConfig?.callbackUrl || `${req.protocol}://${req.get("host")}/oidc/${provider}/callback`;
 
+        oidcLog.debug(`Initiate: resolved redirectUri="${finalRedirectUri}" (source: ${redirectUri ? "query param" : staticProviderConfig?.callbackUrl ? "provider config" : "auto-detected"})`);
+
         // Generate cryptographically secure parameters
         const state = generateState();
         const sessionId = generateSessionId();
@@ -81,6 +86,8 @@ const InitiateOidc: GetHandler<any, any, PathParams, InitiateRequest> = async ({
             createdAt: new Date(),
         });
 
+        oidcLog.debug(`Initiate: session created sessionId=${sessionId}`);
+
         // Build authorization URL with PKCE and nonce
         const authorizationUrl = await oidcProvider.getAuthorizationUrl({
             state,
@@ -88,6 +95,8 @@ const InitiateOidc: GetHandler<any, any, PathParams, InitiateRequest> = async ({
             nonce,
         });
 
+        oidcLog.debug(`Initiate: redirecting to IdP authorization URL`);
+
         // Redirect user to provider's authorization page
         return {
             status: 302,

package/src/log.ts

@@ -0,0 +1,33 @@
+import { FlinkLogFactory } from "@flink-app/flink";
+
+/**
+ * Named logger for the OIDC plugin.
+ *
+ * Enables independent log level control via flink.config.js:
+ * ```js
+ * module.exports = {
+ *   logging: {
+ *     components: {
+ *       "flink.oidc": "debug"
+ *     }
+ *   }
+ * };
+ * ```
+ *
+ * Or at runtime:
+ * ```ts
+ * FlinkLogFactory.setComponentLevel("flink.oidc", "debug");
+ * ```
+ */
+export const oidcLog = FlinkLogFactory.createLogger("flink.oidc");
+
+/**
+ * Mask a secret value for safe logging.
+ * Shows the first 4 characters followed by **** to help identify which secret
+ * is in use without exposing the full value.
+ */
+export function maskSecret(value: string | undefined): string {
+    if (!value) return "(not set)";
+    if (value.length <= 4) return "****";
+    return `${value.slice(0, 4)}****`;
+}

package/src/providers/ProviderRegistry.ts

@@ -1,6 +1,7 @@
 import { OidcProvider } from "./OidcProvider";
 import { OidcProviderConfig } from "../OidcProviderConfig";
 import { createOidcError, OidcErrorCodes } from "../utils/error-utils";
+import { oidcLog, maskSecret } from "../log";
 
 /**
  * Provider registry for managing OIDC provider instances
@@ -45,27 +46,44 @@ export class ProviderRegistry {
         // Check cache first
         const cachedProvider = this.providerInstances.get(providerName);
         if (cachedProvider) {
+            oidcLog.debug(`Provider "${providerName}": using cached instance`);
             return cachedProvider;
         }
 
         // Try static configuration
         let config: OidcProviderConfig | null = this.staticProviders[providerName] || null;
+        let configSource = "static";
 
         // 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";
         }
 
         if (!config) {
+            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,
                 availableProviders: Object.keys(this.staticProviders),
             });
         }
 
+        oidcLog.debug(
+            `Provider "${providerName}" resolved via ${configSource}:`,
+            `issuer=${config.issuer}`,
+            `clientId=${config.clientId}`,
+            `clientSecret=${maskSecret(config.clientSecret)}`,
+            `callbackUrl=${config.callbackUrl}`,
+            config.discoveryUrl ? `discoveryUrl=${config.discoveryUrl}` : `authorizationEndpoint=${config.authorizationEndpoint}`,
+            `scope=${(config.scope || ["openid", "email", "profile"]).join(" ")}`
+        );
+
         // Create and initialize provider
+        oidcLog.debug(`Provider "${providerName}": initializing OIDC client`);
         const provider = new OidcProvider(config);
         await provider.initialize();
+        oidcLog.debug(`Provider "${providerName}": initialized successfully`);
 
         // Cache the instance
         this.providerInstances.set(providerName, provider);