@flink-app/oidc-plugin 2.0.0-alpha.79 → 2.0.0-alpha.81

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @flink-app/oidc-plugin
 
+## 2.0.0-alpha.81
+
+### Patch Changes
+
+-   @flink-app/flink@2.0.0-alpha.81
+-   @flink-app/jwt-auth-plugin@2.0.0-alpha.81
+
+## 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

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/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,CAmOnE,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,CA8PnE,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
@@ -44,8 +45,10 @@ const CallbackOidc = async ({ ctx, req }) => {
         // 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) {
@@ -83,8 +86,10 @@ 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.", {
@@ -95,6 +100,7 @@ const CallbackOidc = async ({ ctx, req }) => {
         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
@@ -104,15 +110,20 @@ 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,
@@ -147,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) {
@@ -170,6 +182,7 @@ const CallbackOidc = async ({ ctx, req }) => {
                 // Create or update OIDC connection
                 const existingConnection = await ctx.repos.oidcConnectionRepo.findByUserAndProvider(user._id, provider);
                 if (existingConnection) {
+                    log_1.oidcLog.debug(`Callback: updating existing connection for userId=${user._id} provider="${provider}"`);
                     await ctx.repos.oidcConnectionRepo.updateById(existingConnection._id, {
                         accessToken: encryptedAccessToken,
                         idToken: encryptedIdToken,
@@ -180,6 +193,7 @@ const CallbackOidc = async ({ ctx, req }) => {
                     });
                 }
                 else {
+                    log_1.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,
@@ -197,8 +211,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);

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: ${authorizationUrl}`);
         // 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/OidcProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"OidcProvider.d.ts","sourceRoot":"","sources":["../../src/providers/OidcProvider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAwD,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACvG,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,WAAW,MAAM,wBAAwB,CAAC;AACjD,OAAO,YAAY,MAAM,yBAAyB,CAAC;AAInD;;;;;;;;;;GAUG;AACH,qBAAa,YAAY;IACrB,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,MAAM,CAA+B;IAC7C,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,WAAW,CAAkB;gBAEzB,MAAM,EAAE,kBAAkB;IAItC;;;;;;;OAOG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IA0DjC;;;;;OAKG;IACG,mBAAmB,CAAC,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAiB1G;;;;;;;OAOG;IACG,oBAAoB,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,YAAY,CAAC;IAqC/H;;;;;;;;OAQG;IACG,WAAW,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAajE;;;;;;;;;OASG;IACG,YAAY,CAAC,QAAQ,EAAE,YAAY,EAAE,eAAe,GAAE,OAAc,GAAG,OAAO,CAAC,WAAW,CAAC;IA2BjG;;;;OAIG;YACW,iBAAiB;IAU/B;;;;OAIG;IACH,iBAAiB,IAAI,GAAG;CAM3B"}
+{"version":3,"file":"OidcProvider.d.ts","sourceRoot":"","sources":["../../src/providers/OidcProvider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAwD,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACvG,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,WAAW,MAAM,wBAAwB,CAAC;AACjD,OAAO,YAAY,MAAM,yBAAyB,CAAC;AAKnD;;;;;;;;;;GAUG;AACH,qBAAa,YAAY;IACrB,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,MAAM,CAA+B;IAC7C,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,WAAW,CAAkB;gBAEzB,MAAM,EAAE,kBAAkB;IAItC;;;;;;;OAOG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAkEjC;;;;;OAKG;IACG,mBAAmB,CAAC,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAiB1G;;;;;;;OAOG;IACG,oBAAoB,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,YAAY,CAAC;IAqC/H;;;;;;;;OAQG;IACG,WAAW,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAajE;;;;;;;;;OASG;IACG,YAAY,CAAC,QAAQ,EAAE,YAAY,EAAE,eAAe,GAAE,OAAc,GAAG,OAAO,CAAC,WAAW,CAAC;IA2BjG;;;;OAIG;YACW,iBAAiB;IAU/B;;;;OAIG;IACH,iBAAiB,IAAI,GAAG;CAM3B"}

package/dist/providers/OidcProvider.js

@@ -4,6 +4,7 @@ exports.OidcProvider = void 0;
 const openid_client_1 = require("openid-client");
 const claims_mapper_1 = require("../utils/claims-mapper");
 const error_utils_1 = require("../utils/error-utils");
+const log_1 = require("../log");
 /**
  * Generic OIDC Provider implementation using openid-client
  *
@@ -37,7 +38,9 @@ class OidcProvider {
         try {
             // Option 1: OIDC Discovery
             if (this.config.discoveryUrl) {
+                log_1.oidcLog.debug(`Provider "${this.config.issuer}": discovering from ${this.config.discoveryUrl}`);
                 this.issuer = await openid_client_1.Issuer.discover(this.config.discoveryUrl);
+                log_1.oidcLog.debug(`Provider "${this.config.issuer}": discovery complete`, `authorization_endpoint=${this.issuer.metadata.authorization_endpoint}`, `token_endpoint=${this.issuer.metadata.token_endpoint}`, `userinfo_endpoint=${this.issuer.metadata.userinfo_endpoint ?? "(none)"}`, `jwks_uri=${this.issuer.metadata.jwks_uri}`);
             }
             // Option 2: Manual configuration
             else {
@@ -178,7 +181,7 @@ class OidcProvider {
             }
             catch (error) {
                 // UserInfo is optional - continue with ID token claims only
-                console.warn("Failed to fetch UserInfo, using ID token claims only:", error);
+                log_1.oidcLog.warn(`Failed to fetch UserInfo from ${this.config.userinfoEndpoint}, using ID token claims only:`, error);
             }
         }
         // Apply custom claim mapping if configured

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.79",
+  "version": "2.0.0-alpha.81",
   "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.79"
+    "@flink-app/jwt-auth-plugin": "2.0.0-alpha.81"
   },
   "peerDependencies": {
-    "@flink-app/flink": ">=2.0.0-alpha.79",
+    "@flink-app/flink": ">=2.0.0-alpha.81",
     "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.79",
-    "@flink-app/test-utils": "2.0.0-alpha.79",
-    "@flink-app/flink": "2.0.0-alpha.79"
+    "@flink-app/flink": "2.0.0-alpha.81",
+    "@flink-app/jwt-auth-plugin": "2.0.0-alpha.81",
+    "@flink-app/test-utils": "2.0.0-alpha.81"
   },
   "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/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
@@ -56,8 +57,11 @@ const CallbackOidc: GetHandler<any, any, PathParams, CallbackRequest> = async ({
         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)
@@ -102,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.", {
@@ -117,6 +124,7 @@ const CallbackOidc: GetHandler<any, any, PathParams, CallbackRequest> = async ({
 
         // 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;
@@ -130,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,
@@ -137,10 +146,22 @@ 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,
@@ -180,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;
 
@@ -208,6 +231,7 @@ const CallbackOidc: GetHandler<any, any, PathParams, CallbackRequest> = async ({
                 const existingConnection = await ctx.repos.oidcConnectionRepo.findByUserAndProvider(user._id, provider);
 
                 if (existingConnection) {
+                    oidcLog.debug(`Callback: updating existing connection for userId=${user._id} provider="${provider}"`);
                     await ctx.repos.oidcConnectionRepo.updateById(existingConnection._id!, {
                         accessToken: encryptedAccessToken,
                         idToken: encryptedIdToken,
@@ -217,6 +241,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,
@@ -235,8 +260,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);
 

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: ${authorizationUrl}`);
+
         // 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/OidcProvider.ts

@@ -4,6 +4,7 @@ import OidcProfile from "../schemas/OidcProfile";
 import OidcTokenSet from "../schemas/OidcTokenSet";
 import { mapClaimsToProfile, extractCustomClaims } from "../utils/claims-mapper";
 import { createOidcError, OidcErrorCodes } from "../utils/error-utils";
+import { oidcLog } from "../log";
 
 /**
  * Generic OIDC Provider implementation using openid-client
@@ -42,7 +43,15 @@ export class OidcProvider {
         try {
             // Option 1: OIDC Discovery
             if (this.config.discoveryUrl) {
+                oidcLog.debug(`Provider "${this.config.issuer}": discovering from ${this.config.discoveryUrl}`);
                 this.issuer = await Issuer.discover(this.config.discoveryUrl);
+                oidcLog.debug(
+                    `Provider "${this.config.issuer}": discovery complete`,
+                    `authorization_endpoint=${this.issuer.metadata.authorization_endpoint}`,
+                    `token_endpoint=${this.issuer.metadata.token_endpoint}`,
+                    `userinfo_endpoint=${this.issuer.metadata.userinfo_endpoint ?? "(none)"}`,
+                    `jwks_uri=${this.issuer.metadata.jwks_uri}`
+                );
             }
             // Option 2: Manual configuration
             else {
@@ -203,7 +212,7 @@ export class OidcProvider {
                 claims = { ...claims, ...userinfo };
             } catch (error) {
                 // UserInfo is optional - continue with ID token claims only
-                console.warn("Failed to fetch UserInfo, using ID token claims only:", error);
+                oidcLog.warn(`Failed to fetch UserInfo from ${this.config.userinfoEndpoint}, using ID token claims only:`, error);
             }
         }
 

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);