@flink-app/oidc-plugin 0.14.3 → 2.0.0-alpha.100

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) {
@@ -61,9 +64,19 @@ const InitiateOidc: GetHandler<any, any, PathParams, InitiateRequest> = async ({
         const { options } = ctx.plugins.oidc;
 
         // Determine redirect URI (use provided or default to callback URL)
-        const staticProviderConfig = options.providers[provider];
+        const staticProviderConfig = options.providers?.[provider];
         const finalRedirectUri = redirectUri || staticProviderConfig?.callbackUrl || `${req.protocol}://${req.get("host")}/oidc/${provider}/callback`;
 
+        // Collect meta.* query params as opaque metadata (prefix stripped)
+        const metadata: Record<string, string> = {};
+        for (const [key, value] of Object.entries(req.query)) {
+            if (key.startsWith("meta.") && typeof value === "string") {
+                metadata[key.slice(5)] = value;
+            }
+        }
+
+        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();
@@ -78,9 +91,12 @@ const InitiateOidc: GetHandler<any, any, PathParams, InitiateRequest> = async ({
             nonce,
             provider,
             redirectUri: finalRedirectUri,
+            metadata,
             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 +104,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/index.ts

@@ -34,5 +34,5 @@ export { ProviderRegistry } from "./providers/ProviderRegistry";
 export { generateState, generateSessionId, generateNonce, validateState } from "./utils/state-utils";
 export { encryptToken, decryptToken, validateEncryptionSecret } from "./utils/encryption-utils";
 export { mapClaimsToProfile, extractCustomClaims } from "./utils/claims-mapper";
-export { formatTokenResponse } from "./utils/response-utils";
+export { formatTokenResponse, TokenDeliveryMode } from "./utils/response-utils";
 export { createOidcError, validateProvider, handleProviderError, OidcErrorCodes } from "./utils/error-utils";

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

@@ -1,9 +1,10 @@
-import { Issuer, Client, generators, TokenSet, UserinfoResponse } from "openid-client";
+import { Issuer, Client, ClientMetadata, generators, TokenSet, UserinfoResponse } from "openid-client";
 import { OidcProviderConfig } from "../OidcProviderConfig";
 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
@@ -17,7 +18,7 @@ import { createOidcError, OidcErrorCodes } from "../utils/error-utils";
  * - Claims mapping to profile
  */
 export class OidcProvider {
-    private config: OidcProviderConfig;
+    public readonly config: OidcProviderConfig;
     private issuer: Issuer<Client> | null = null;
     private client: Client | null = null;
     private initialized: boolean = false;
@@ -42,7 +43,19 @@ 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}`
+                );
+                oidcLog.trace(
+                    `Provider "${this.config.issuer}": raw discovery metadata from ${this.config.discoveryUrl}`,
+                    this.issuer.metadata
+                );
             }
             // Option 2: Manual configuration
             else {
@@ -65,12 +78,23 @@ export class OidcProvider {
             }
 
             // Create OIDC client
-            this.client = new this.issuer.Client({
+            const clientMetadata: ClientMetadata = {
                 client_id: this.config.clientId,
-                client_secret: this.config.clientSecret,
                 redirect_uris: [this.config.callbackUrl],
                 response_types: ["code"],
-            });
+            };
+
+            if (this.config.clientSecret) {
+                clientMetadata.client_secret = this.config.clientSecret;
+                clientMetadata.token_endpoint_auth_method =
+                    this.config.tokenEndpointAuthMethod || "client_secret_basic";
+            } else {
+                // Public client (PKCE-only) — openid-client requires this to skip client authentication
+                clientMetadata.token_endpoint_auth_method =
+                    this.config.tokenEndpointAuthMethod || "none";
+            }
+
+            this.client = new this.issuer.Client(clientMetadata);
 
             this.initialized = true;
         } catch (error: any) {
@@ -129,8 +153,14 @@ export class OidcProvider {
                 }
             );
 
+            // Raw response from the token endpoint (includes access_token, id_token,
+            // refresh_token, token_type, expires_at, scope, and any non-standard fields
+            // returned by the IdP). Trace-level because it contains secrets.
+            oidcLog.trace(`Provider "${this.config.issuer}": raw token endpoint response`, { ...tokenSet });
+
             // Extract claims from ID token (already validated by openid-client)
             const claims = tokenSet.claims();
+            oidcLog.trace(`Provider "${this.config.issuer}": extracted claims from ID token`, claims);
 
             return {
                 accessToken: tokenSet.access_token!,
@@ -142,6 +172,15 @@ export class OidcProvider {
                 claims,
             };
         } catch (error: any) {
+            // openid-client attaches the raw IdP error response on OPError.
+            oidcLog.trace(`Provider "${this.config.issuer}": raw token exchange error`, {
+                name: error.name,
+                message: error.message,
+                error: error.error,
+                error_description: error.error_description,
+                error_uri: error.error_uri,
+                response: error.response?.body ?? error.response,
+            });
             throw createOidcError(OidcErrorCodes.TOKEN_EXCHANGE_FAILED, `Token exchange failed: ${error.message}`, {
                 originalError: error.message,
                 errorCode: error.error,
@@ -163,8 +202,17 @@ export class OidcProvider {
 
         try {
             const userinfo = await this.client!.userinfo(accessToken);
+            // Raw response from the UserInfo endpoint, before any mapping/merging.
+            oidcLog.trace(`Provider "${this.config.issuer}": raw UserInfo endpoint response`, userinfo);
             return userinfo;
         } catch (error: any) {
+            oidcLog.trace(`Provider "${this.config.issuer}": raw UserInfo error`, {
+                name: error.name,
+                message: error.message,
+                error: error.error,
+                error_description: error.error_description,
+                response: error.response?.body ?? error.response,
+            });
             throw createOidcError(OidcErrorCodes.USERINFO_FAILED, `UserInfo request failed: ${error.message}`, {
                 originalError: error.message,
             });
@@ -185,14 +233,17 @@ export class OidcProvider {
         let claims = { ...tokenSet.claims };
 
         // Optionally fetch additional claims from UserInfo endpoint
-        if (includeUserInfo && this.config.userinfoEndpoint) {
+        // Check both manual config and discovered endpoint (via OIDC discovery)
+        const userinfoUrl = this.config.userinfoEndpoint || this.issuer?.metadata?.userinfo_endpoint;
+
+        if (includeUserInfo && userinfoUrl) {
             try {
                 const userinfo = await this.getUserInfo(tokenSet.accessToken);
                 // Merge UserInfo claims with ID token claims
                 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 ${userinfoUrl}, using ID token claims only:`, error);
             }
         }
 
@@ -200,10 +251,12 @@ export class OidcProvider {
         if (this.config.claimMapping) {
             const customClaims = extractCustomClaims(claims, this.config.claimMapping);
             claims = { ...claims, ...customClaims };
+            oidcLog.trace(`Provider "${this.config.issuer}": applied custom claim mapping`, claims);
         }
 
         // Map to normalized profile
         const profile = mapClaimsToProfile(claims);
+        oidcLog.trace(`Provider "${this.config.issuer}": built final profile`, profile);
 
         return profile;
     }

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
@@ -14,14 +15,17 @@ import { createOidcError, OidcErrorCodes } from "../utils/error-utils";
 export class ProviderRegistry {
     private staticProviders: Record<string, OidcProviderConfig>;
     private providerInstances: Map<string, OidcProvider> = new Map();
-    private providerLoader?: (providerName: string) => Promise<OidcProviderConfig | null>;
+    private providerLoader?: (providerName: string, ctx: any) => Promise<OidcProviderConfig | null>;
+    private ctx: any;
 
     constructor(
         staticProviders: Record<string, OidcProviderConfig>,
-        providerLoader?: (providerName: string) => Promise<OidcProviderConfig | null>
+        providerLoader?: (providerName: string, ctx: any) => Promise<OidcProviderConfig | null>,
+        ctx?: any
     ) {
         this.staticProviders = staticProviders;
         this.providerLoader = providerLoader;
+        this.ctx = ctx;
     }
 
     /**
@@ -42,24 +46,39 @@ 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) {
-            config = await this.providerLoader(providerName);
+            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
         const provider = new OidcProvider(config);
         await provider.initialize();

package/src/schemas/CallbackRequest.ts

@@ -3,7 +3,7 @@
  *
  * GET /oidc/:provider/callback?code=...&state=...&response_type=json
  */
-export default interface CallbackRequest {
+type CallbackRequest = Record<string, string | string[]> & {
     /**
      * Authorization code from the IdP
      * Required for successful authentication
@@ -34,8 +34,6 @@ export default interface CallbackRequest {
      */
     response_type?: "json";
 
-    /**
-     * Index signature for Flink Query type compatibility
-     */
-    [key: string]: string | string[] | undefined;
-}
+};
+
+export default CallbackRequest;

package/src/schemas/InitiateRequest.ts

@@ -3,15 +3,12 @@
  *
  * GET /oidc/:provider/initiate?redirectUri=...
  */
-export default interface InitiateRequest {
+type InitiateRequest = Record<string, string | string[]> & {
     /**
      * Optional redirect URI after successful authentication
      * If not provided, uses the default callbackUrl from provider config
      */
     redirectUri?: string;
+};
 
-    /**
-     * Index signature for Flink Query type compatibility
-     */
-    [key: string]: string | string[] | undefined;
-}
+export default InitiateRequest;

package/src/schemas/OidcSession.ts

@@ -44,6 +44,12 @@ export default interface OidcSession {
      */
     redirectUri: string;
 
+    /**
+     * Arbitrary metadata collected from meta.* query parameters on initiate
+     * Passed through to onAuthSuccess and onAuthError callbacks unchanged
+     */
+    metadata?: Record<string, string>;
+
     /**
      * Session creation timestamp
      * MongoDB TTL index will automatically delete expired sessions

package/src/utils/response-utils.ts

@@ -1,20 +1,38 @@
+/**
+ * Controls how the JWT token is delivered back to the client on the
+ * post-callback redirect.
+ *
+ * - "fragment": appends `#token=...` to the redirectUrl. Best for web
+ *   browsers — URL fragments are not sent to the server in HTTP requests
+ *   and are only accessible to client-side JavaScript.
+ * - "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.
+ */
+export type TokenDeliveryMode = "fragment" | "query";
+
 /**
  * Format token response for the client
  *
  * Supports two response formats:
  * 1. JSON response (for API clients)
- * 2. Redirect with token in URL fragment (for web browsers)
- *
- * URL fragments are used for security - they are NOT sent to the server
- * in HTTP requests and are only accessible to client-side JavaScript.
+ * 2. Redirect with token in URL fragment or query (for web/native clients)
  *
  * @param token - JWT token for the application
  * @param user - User object
  * @param redirectUrl - URL to redirect to
  * @param responseType - "json" or undefined (redirect)
+ * @param tokenDelivery - How to attach the token on redirect. Defaults to "fragment".
  * @returns Flink response object
  */
-export function formatTokenResponse(token: string, user: any, redirectUrl: string, responseType?: "json"): any {
+export function formatTokenResponse(
+    token: string,
+    user: any,
+    redirectUrl: string,
+    responseType?: "json",
+    tokenDelivery: TokenDeliveryMode = "fragment"
+): any {
     // JSON response for API clients
     if (responseType === "json") {
         return {
@@ -25,11 +43,8 @@ export function formatTokenResponse(token: string, user: any, redirectUrl: strin
         };
     }
 
-    // Redirect response for web browsers
-    // Token is in URL fragment (#token=...) for security
-    const separator = redirectUrl.includes("#") ? "&" : "#";
-    const tokenFragment = `token=${encodeURIComponent(token)}`;
-    const finalUrl = `${redirectUrl}${separator}${tokenFragment}`;
+    const tokenParam = `token=${encodeURIComponent(token)}`;
+    const finalUrl = appendToken(redirectUrl, tokenParam, tokenDelivery);
 
     return {
         status: 302,
@@ -39,3 +54,31 @@ export function formatTokenResponse(token: string, user: any, redirectUrl: strin
         data: {},
     };
 }
+
+/**
+ * Append a token parameter to a URL using the specified delivery mode.
+ *
+ * For "query" mode, any existing `#fragment` on the URL is preserved: the
+ * query parameter is spliced in *before* the fragment so the final URL is
+ * still well-formed.
+ *
+ * For "fragment" mode, a second token on an existing fragment is joined
+ * with `&` (same as the old behavior).
+ */
+function appendToken(redirectUrl: string, tokenParam: string, mode: TokenDeliveryMode): string {
+    if (mode === "query") {
+        const hashIdx = redirectUrl.indexOf("#");
+        if (hashIdx >= 0) {
+            const base = redirectUrl.slice(0, hashIdx);
+            const frag = redirectUrl.slice(hashIdx);
+            const sep = base.includes("?") ? "&" : "?";
+            return `${base}${sep}${tokenParam}${frag}`;
+        }
+        const sep = redirectUrl.includes("?") ? "&" : "?";
+        return `${redirectUrl}${sep}${tokenParam}`;
+    }
+
+    // fragment (default)
+    const sep = redirectUrl.includes("#") ? "&" : "#";
+    return `${redirectUrl}${sep}${tokenParam}`;
+}