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

package/dist/OidcPluginOptions.d.ts

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

package/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;IAC9B;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;IAE9C;;;;;;;;;;;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,GAAG,KACP,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;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,cAAc,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAAC;IAE9E;;;OAGG;IACH,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAEhC;;;OAGG;IACH,yBAAyB,CAAC,EAAE,MAAM,CAAC;IAEnC;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;;;;;;OAQG;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":"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"}

package/dist/OidcProviderConfig.d.ts

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

package/dist/OidcProviderConfig.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"OidcProviderConfig.d.ts","sourceRoot":"","sources":["../src/OidcProviderConfig.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IAC/B;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,YAAY,EAAE,MAAM,CAAC;IAErB;;;;OAIG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IAEjB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;OAEG;IAEH;;;;OAIG;IACH,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAE/B;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACzC"}
+{"version":3,"file":"OidcProviderConfig.d.ts","sourceRoot":"","sources":["../src/OidcProviderConfig.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IAC/B;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;;;;OAMG;IACH,uBAAuB,CAAC,EAAE,qBAAqB,GAAG,oBAAoB,GAAG,MAAM,CAAC;IAEhF;;;;OAIG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IAEjB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;OAEG;IAEH;;;;OAIG;IACH,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAE/B;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEtC;;;;;;;OAOG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;CACjC"}

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,CA4QnE,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,35 @@ 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 and metadata are available in error handling
+    let sessionRedirectUri;
+    let sessionMetadata = {};
     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;
+                sessionMetadata = errorSession?.metadata ?? {};
+                if (errorSession) {
+                    await ctx.repos.oidcSessionRepo.deleteBySessionId(errorSession.sessionId);
+                }
+            }
             // Call onAuthError callback if provided
             const { options } = ctx.plugins.oidc;
             if (options.onAuthError) {
                 const errorResult = await options.onAuthError({
                     error,
                     provider,
+                    redirectUri: sessionRedirectUri,
+                    metadata: sessionMetadata,
                 });
                 if (errorResult.redirectUrl) {
                     return {
@@ -72,16 +89,22 @@ 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 and metadata for error handling
+        sessionRedirectUri = session.redirectUri;
+        sessionMetadata = session.metadata ?? {};
         // Delete session immediately after validation (one-time use)
         await ctx.repos.oidcSessionRepo.deleteBySessionId(session.sessionId);
+        log_1.oidcLog.debug(`Callback: state validated, session deleted (one-time use)`);
         // Get plugin options
         const { options } = ctx.plugins.oidc;
         // Get provider instance
@@ -97,13 +120,17 @@ const CallbackOidc = async ({ ctx, req }) => {
             state: session.state,
             nonce: session.nonce,
         });
-        // Build user profile from ID token and UserInfo
-        const profile = await oidcProvider.buildProfile(tokenSet, true);
+        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 (optionally) UserInfo
+        const profile = await oidcProvider.buildProfile(tokenSet, oidcProvider.config.useUserInfoEndpoint ?? 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
         const authSuccessParams = {
             profile,
             claims: tokenSet.claims,
             provider,
+            redirectUri: session.redirectUri,
+            metadata: sessionMetadata,
             ...(options.storeTokens ? { tokens: tokenSet } : {}),
         };
         let authResult;
@@ -121,6 +148,8 @@ const CallbackOidc = async ({ ctx, req }) => {
                 const errorResult = await options.onAuthError({
                     error: oidcError,
                     provider,
+                    redirectUri: session.redirectUri,
+                    metadata: sessionMetadata,
                 });
                 if (errorResult.redirectUrl) {
                     return {
@@ -140,7 +169,7 @@ const CallbackOidc = async ({ ctx, req }) => {
         // Store OIDC connection if token storage is enabled
         if (options.storeTokens && user && user._id) {
             // Get encryption secret (use provider client secret or global encryption key)
-            const staticProviderConfig = options.providers[provider];
+            const staticProviderConfig = options.providers?.[provider];
             const encryptionSecret = options.encryptionKey || staticProviderConfig?.clientSecret;
             if (!encryptionSecret) {
                 flink_1.log.warn("No encryption secret available, tokens will not be stored");
@@ -155,7 +184,8 @@ const CallbackOidc = async ({ ctx, req }) => {
                 // Create or update OIDC connection
                 const existingConnection = await ctx.repos.oidcConnectionRepo.findByUserAndProvider(user._id, provider);
                 if (existingConnection) {
-                    await ctx.repos.oidcConnectionRepo.updateOne(existingConnection._id, {
+                    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,
                         refreshToken: encryptedRefreshToken,
@@ -165,6 +195,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,
@@ -182,8 +213,20 @@ 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}"`}`);
+        // Resolve token delivery mode: literal, function, or default "fragment".
+        // The plugin stays a dumb transport — the host app makes the policy decision.
+        const tokenDeliverySetting = options.tokenDelivery ?? "fragment";
+        const resolvedTokenDelivery = typeof tokenDeliverySetting === "function"
+            ? tokenDeliverySetting({
+                redirectUrl: finalRedirectUrl,
+                provider,
+                metadata: sessionMetadata,
+            })
+            : tokenDeliverySetting;
         // Return JWT token in requested format
-        return (0, response_utils_1.formatTokenResponse)(token, user, redirectUrl || session.redirectUri, response_type);
+        return (0, response_utils_1.formatTokenResponse)(token, user, finalRedirectUrl, response_type, resolvedTokenDelivery);
     }
     catch (error) {
         flink_1.log.error("OIDC callback error:", error);
@@ -196,6 +239,8 @@ const CallbackOidc = async ({ ctx, req }) => {
                     const errorResult = await options.onAuthError({
                         error,
                         provider,
+                        redirectUri: sessionRedirectUri,
+                        metadata: sessionMetadata,
                     });
                     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,CAkFnE,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) {
@@ -47,8 +49,16 @@ const InitiateOidc = async ({ ctx, req }) => {
         // Get plugin options
         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 = {};
+        for (const [key, value] of Object.entries(req.query)) {
+            if (key.startsWith("meta.") && typeof value === "string") {
+                metadata[key.slice(5)] = value;
+            }
+        }
+        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)();
@@ -62,14 +72,17 @@ const InitiateOidc = async ({ ctx, req }) => {
             nonce,
             provider,
             redirectUri: finalRedirectUri,
+            metadata,
             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/index.d.ts

@@ -22,6 +22,6 @@ 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";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAG1C,OAAO,EAAE,iBAAiB,EAAE,SAAS,EAAE,2BAA2B,EAAE,yBAAyB,EAAE,MAAM,qBAAqB,CAAC;AAC3H,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAG1D,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAGxD,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAC/D,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACjE,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAC/D,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,0BAA0B,CAAC;AACrE,OAAO,EAAE,OAAO,IAAI,eAAe,EAAE,MAAM,2BAA2B,CAAC;AACvE,OAAO,EAAE,OAAO,IAAI,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAGvE,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAGhE,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACrG,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AAChG,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAChF,OAAO,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAG1C,OAAO,EAAE,iBAAiB,EAAE,SAAS,EAAE,2BAA2B,EAAE,yBAAyB,EAAE,MAAM,qBAAqB,CAAC;AAC3H,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAG1D,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAGxD,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAC/D,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACjE,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAC/D,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,0BAA0B,CAAC;AACrE,OAAO,EAAE,OAAO,IAAI,eAAe,EAAE,MAAM,2BAA2B,CAAC;AACvE,OAAO,EAAE,OAAO,IAAI,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAGvE,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAGhE,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACrG,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AAChG,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAChF,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAChF,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC"}

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

@@ -14,7 +14,7 @@ import OidcTokenSet from "../schemas/OidcTokenSet";
  * - Claims mapping to profile
  */
 export declare class OidcProvider {
-    private config;
+    readonly config: OidcProviderConfig;
     private issuer;
     private client;
     private initialized;

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,EAAwC,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACvF,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;IA+CjC;;;;;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,SAAgB,MAAM,EAAE,kBAAkB,CAAC;IAC3C,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;IAsEjC;;;;;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;IAoD/H;;;;;;;;OAQG;IACG,WAAW,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAsBjE;;;;;;;;;OASG;IACG,YAAY,CAAC,QAAQ,EAAE,YAAY,EAAE,eAAe,GAAE,OAAc,GAAG,OAAO,CAAC,WAAW,CAAC;IAgCjG;;;;OAIG;YACW,iBAAiB;IAU/B;;;;OAIG;IACH,iBAAiB,IAAI,GAAG;CAM3B"}