@flink-app/oidc-plugin 1.0.0

package/dist/OidcPluginOptions.d.ts

@@ -0,0 +1,267 @@
+import OidcProfile from "./schemas/OidcProfile";
+import OidcTokenSet from "./schemas/OidcTokenSet";
+import { OidcProviderConfig } from "./OidcProviderConfig";
+/**
+ * OIDC error information passed to onAuthError callback
+ */
+export interface OidcError {
+    /**
+     * Error code (e.g., "invalid_state", "access_denied", "token_exchange_failed")
+     */
+    code: string;
+    /**
+     * Human-readable error message
+     */
+    message: string;
+    /**
+     * Additional error details for debugging
+     */
+    details?: any;
+}
+/**
+ * Response from onAuthSuccess callback
+ * Must include JWT token generated by the application via jwt-auth-plugin
+ */
+export interface AuthSuccessCallbackResponse {
+    /**
+     * User object from your application
+     * Should include _id field for connection storage
+     */
+    user: any;
+    /**
+     * JWT token for your application (not the OIDC tokens!)
+     * Generated using ctx.plugins.jwtAuth.createToken()
+     */
+    token: string;
+    /**
+     * Optional redirect URL after authentication
+     * Plugin will append #token=... to this URL
+     */
+    redirectUrl?: string;
+}
+/**
+ * Response from onAuthError callback
+ */
+export interface AuthErrorCallbackResponse {
+    /**
+     * Optional redirect URL for error page
+     * e.g., "/login?error=authentication_failed"
+     */
+    redirectUrl?: string;
+}
+/**
+ * Configuration options for OIDC Plugin with JWT integration
+ *
+ * The plugin depends on @flink-app/jwt-auth-plugin being installed and configured.
+ * 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 {
+    /**
+     * OIDC provider configurations
+     * Key = provider name (used in URLs: /oidc/{provider}/initiate)
+     * Value = provider configuration
+     *
+     * At least one provider must be configured.
+     *
+     * Example:
+     * {
+     *   acme: {
+     *     issuer: "https://idp.acme.com",
+     *     clientId: "...",
+     *     clientSecret: "...",
+     *     callbackUrl: "https://myapp.com/oidc/acme/callback",
+     *     discoveryUrl: "https://idp.acme.com/.well-known/openid-configuration"
+     *   },
+     *   contoso: {
+     *     issuer: "https://login.contoso.com",
+     *     clientId: "...",
+     *     clientSecret: "...",
+     *     callbackUrl: "https://myapp.com/oidc/contoso/callback"
+     *   }
+     * }
+     */
+    providers: Record<string, OidcProviderConfig>;
+    /**
+     * Whether to store OIDC tokens for future API access
+     * If false, tokens are discarded after authentication (auth-only mode)
+     * If true, encrypted tokens are stored in MongoDB for later use
+     *
+     * Default: false
+     *
+     * Set to true if you need to:
+     * - Call IdP APIs on behalf of users
+     * - Access user's resources at the IdP
+     * - Use refresh tokens to maintain long-term access
+     */
+    storeTokens?: boolean;
+    /**
+     * Callback invoked after successful OIDC authentication
+     *
+     * Application responsibilities:
+     * 1. Find or create user based on OIDC profile (JIT provisioning)
+     * 2. Link OIDC provider to user account
+     * 3. Generate JWT token using ctx.plugins.jwtAuth.createToken(payload, roles)
+     * 4. Return user object, JWT token, and optional redirect URL
+     *
+     * @param params - OIDC profile, claims, provider name, and tokens (if storeTokens enabled)
+     * @param ctx - Flink context with access to repos and plugins (including jwtAuth)
+     * @returns User object, JWT token, and optional redirect URL
+     *
+     * Example:
+     * ```typescript
+     * onAuthSuccess: async ({ profile, claims, provider }, ctx) => {
+     *   // Find user by OIDC subject + issuer
+     *   let user = await ctx.repos.userRepo.getOne({
+     *     'oidcConnections.subject': claims.sub,
+     *     'oidcConnections.issuer': claims.iss
+     *   });
+     *
+     *   if (!user) {
+     *     // JIT provisioning - create new user
+     *     user = await ctx.repos.userRepo.create({
+     *       email: claims.email,
+     *       name: claims.name,
+     *       oidcConnections: [{
+     *         issuer: claims.iss,
+     *         subject: claims.sub,
+     *         provider
+     *       }]
+     *     });
+     *   }
+     *
+     *   // Generate JWT token
+     *   const token = await ctx.plugins.jwtAuth.createToken(
+     *     { userId: user._id, email: user.email },
+     *     ['user']
+     *   );
+     *
+     *   return {
+     *     user,
+     *     token,
+     *     redirectUrl: '/dashboard'
+     *   };
+     * }
+     * ```
+     */
+    onAuthSuccess: (params: {
+        /**
+         * Normalized user profile from OIDC claims
+         */
+        profile: OidcProfile;
+        /**
+         * Raw OIDC claims from ID token
+         * Contains all standard and custom claims
+         */
+        claims: Record<string, any>;
+        /**
+         * Provider name (e.g., "acme", "contoso")
+         */
+        provider: string;
+        /**
+         * OIDC tokens (only if storeTokens: true)
+         * Includes accessToken, idToken, refreshToken
+         */
+        tokens?: OidcTokenSet;
+    }, ctx: any) => Promise<AuthSuccessCallbackResponse>;
+    /**
+     * Callback invoked on OIDC authentication errors
+     *
+     * Application responsibilities:
+     * - Log error for debugging
+     * - Optionally provide redirect URL for error page
+     *
+     * @param params - Error information and provider name
+     * @returns Optional redirect URL for error page
+     *
+     * Example:
+     * ```typescript
+     * onAuthError: async ({ error, provider }) => {
+     *   console.error(`OIDC error for ${provider}:`, error);
+     *
+     *   if (error.code === 'access_denied') {
+     *     return {
+     *       redirectUrl: '/login?error=user_cancelled'
+     *     };
+     *   }
+     *
+     *   return {
+     *     redirectUrl: '/login?error=authentication_failed'
+     *   };
+     * }
+     * ```
+     */
+    onAuthError?: (params: {
+        error: OidcError;
+        provider: string;
+    }) => Promise<AuthErrorCallbackResponse>;
+    /**
+     * Dynamic provider loader callback
+     *
+     * Called when a provider is accessed but not in the static providers config.
+     * Allows loading provider configurations from database at runtime.
+     *
+     * Use this for multi-tenant scenarios where each organization has different IdPs.
+     *
+     * @param providerName - Name of the provider to load
+     * @returns Provider configuration or null if not found
+     *
+     * Example:
+     * ```typescript
+     * providerLoader: async (providerName) => {
+     *   const config = await ctx.repos.oidcProviderRepo.getByName(providerName);
+     *   if (!config || !config.enabled) {
+     *     return null;
+     *   }
+     *   return {
+     *     issuer: config.issuer,
+     *     clientId: config.clientId,
+     *     clientSecret: decryptSecret(config.clientSecret),
+     *     callbackUrl: config.callbackUrl,
+     *     discoveryUrl: config.discoveryUrl,
+     *     scope: config.scope
+     *   };
+     * }
+     * ```
+     */
+    providerLoader?: (providerName: string) => Promise<OidcProviderConfig | null>;
+    /**
+     * Custom collection name for OIDC sessions
+     * Default: 'oidc_sessions'
+     */
+    sessionsCollectionName?: string;
+    /**
+     * Custom collection name for OIDC connections (if storeTokens enabled)
+     * Default: 'oidc_connections'
+     */
+    connectionsCollectionName?: string;
+    /**
+     * Session TTL in seconds
+     * Sessions are automatically cleaned up after this duration
+     * Default: 600 (10 minutes)
+     *
+     * This is the maximum time a user has to complete the OIDC flow
+     * (from /initiate to /callback). Increase if users need more time.
+     */
+    sessionTTL?: number;
+    /**
+     * Encryption key for encrypting stored OIDC tokens
+     * If not provided, will be derived from first configured provider's client secret
+     *
+     * Recommended: Use a dedicated encryption key from environment variables
+     * Must be at least 32 characters
+     *
+     * Example: process.env.OIDC_ENCRYPTION_KEY
+     */
+    encryptionKey?: string;
+    /**
+     * Whether to register OIDC routes automatically
+     * If false, you must manually handle OIDC flow
+     * Default: true
+     *
+     * Set to false if you want to implement custom route handling
+     * or use a custom URL structure.
+     */
+    registerRoutes?: boolean;
+}
+//# sourceMappingURL=OidcPluginOptions.d.ts.map

package/dist/OidcPluginOptions.d.ts.map

@@ -0,0 +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"}

package/dist/OidcPluginOptions.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/OidcProviderConfig.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Configuration for a single OIDC provider
+ *
+ * Supports both OIDC discovery and manual endpoint configuration.
+ */
+export interface OidcProviderConfig {
+    /**
+     * OIDC issuer URL
+     * e.g., "https://idp.acme.com" or "https://login.microsoftonline.com/{tenant}/v2.0"
+     * Used to validate the 'iss' claim in ID tokens
+     */
+    issuer: string;
+    /**
+     * OAuth 2.0 client ID
+     * Provided by the IdP when you register your application
+     */
+    clientId: string;
+    /**
+     * OAuth 2.0 client secret
+     * Provided by the IdP - keep this secure!
+     */
+    clientSecret: string;
+    /**
+     * Callback URL for OAuth redirect
+     * Must match the redirect URI registered with the IdP
+     * e.g., "https://myapp.com/oidc/acme/callback"
+     */
+    callbackUrl: string;
+    /**
+     * OAuth 2.0 scopes to request
+     * Default: ["openid", "email", "profile"]
+     * "openid" is required for OIDC
+     */
+    scope?: string[];
+    /**
+     * OIDC discovery URL for automatic configuration
+     * e.g., "https://idp.acme.com/.well-known/openid-configuration"
+     * If provided, endpoints will be auto-discovered
+     * If not provided, must specify manual endpoints below
+     */
+    discoveryUrl?: string;
+    /**
+     * Manual endpoint configuration (if not using discovery)
+     */
+    /**
+     * Authorization endpoint URL
+     * e.g., "https://idp.acme.com/authorize"
+     * Required if discoveryUrl not provided
+     */
+    authorizationEndpoint?: string;
+    /**
+     * Token endpoint URL
+     * e.g., "https://idp.acme.com/token"
+     * Required if discoveryUrl not provided
+     */
+    tokenEndpoint?: string;
+    /**
+     * UserInfo endpoint URL
+     * e.g., "https://idp.acme.com/userinfo"
+     * Optional - if not provided, only ID token claims will be used
+     */
+    userinfoEndpoint?: string;
+    /**
+     * JWKS (JSON Web Key Set) endpoint URL
+     * e.g., "https://idp.acme.com/.well-known/jwks.json"
+     * Required for ID token signature validation
+     * Required if discoveryUrl not provided
+     */
+    jwksUri?: string;
+    /**
+     * Additional custom claims to extract from ID token
+     * Map of app field names to OIDC claim paths
+     * e.g., { "department": "custom:department", "role": "custom:role" }
+     */
+    claimMapping?: Record<string, string>;
+}
+//# sourceMappingURL=OidcProviderConfig.d.ts.map

package/dist/OidcProviderConfig.d.ts.map

@@ -0,0 +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"}

package/dist/OidcProviderConfig.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/handlers/CallbackOidc.d.ts

@@ -0,0 +1,38 @@
+/**
+ * OIDC Callback Handler
+ *
+ * Handles the OIDC callback from the provider by:
+ * 1. Validating the state parameter to prevent CSRF attacks
+ * 2. Exchanging the authorization code for tokens (with PKCE validation)
+ * 3. Validating the ID token (signature, claims, nonce)
+ * 4. Fetching user profile from ID token and UserInfo endpoint
+ * 5. Calling the onAuthSuccess callback to create/link user and generate JWT token
+ * 6. Optionally storing the OIDC connection (if storeTokens enabled)
+ * 7. Returning the JWT token to the client (via JSON or redirect)
+ *
+ * Route: GET /oidc/:provider/callback?code=...&state=...&response_type=json
+ */
+import { GetHandler, RouteProps } from "@flink-app/flink";
+import CallbackRequest from "../schemas/CallbackRequest";
+/**
+ * Path parameters for the handler
+ */
+interface PathParams {
+    provider: string;
+    [key: string]: string;
+}
+/**
+ * Route configuration
+ * This handler is registered programmatically by the plugin
+ */
+export declare const Route: RouteProps;
+/**
+ * OIDC Callback Handler
+ *
+ * Completes the OIDC flow by exchanging the authorization code for tokens,
+ * validating the ID token, building user profile, calling the app's onAuthSuccess
+ * callback to generate JWT token, and returning the token to the client.
+ */
+declare const CallbackOidc: GetHandler<any, any, PathParams, CallbackRequest>;
+export default CallbackOidc;
+//# sourceMappingURL=CallbackOidc.d.ts.map

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

@@ -0,0 +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"}

package/dist/handlers/CallbackOidc.js

@@ -0,0 +1,219 @@
+"use strict";
+/**
+ * OIDC Callback Handler
+ *
+ * Handles the OIDC callback from the provider by:
+ * 1. Validating the state parameter to prevent CSRF attacks
+ * 2. Exchanging the authorization code for tokens (with PKCE validation)
+ * 3. Validating the ID token (signature, claims, nonce)
+ * 4. Fetching user profile from ID token and UserInfo endpoint
+ * 5. Calling the onAuthSuccess callback to create/link user and generate JWT token
+ * 6. Optionally storing the OIDC connection (if storeTokens enabled)
+ * 7. Returning the JWT token to the client (via JSON or redirect)
+ *
+ * Route: GET /oidc/:provider/callback?code=...&state=...&response_type=json
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Route = void 0;
+const flink_1 = require("@flink-app/flink");
+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");
+/**
+ * Route configuration
+ * This handler is registered programmatically by the plugin
+ */
+exports.Route = {
+    path: "/oidc/:provider/callback",
+    method: flink_1.HttpMethod.get,
+};
+/**
+ * OIDC Callback Handler
+ *
+ * Completes the OIDC flow by exchanging the authorization code for tokens,
+ * validating the ID token, building user profile, calling the app's onAuthSuccess
+ * callback to generate JWT token, and returning the token to the client.
+ */
+const CallbackOidc = async ({ ctx, req }) => {
+    const { provider } = req.params;
+    const { code, state, error: oidcError, error_description, response_type } = req.query;
+    try {
+        // Validate provider and response_type
+        (0, error_utils_1.validateProvider)(provider);
+        (0, error_utils_1.validateResponseType)(response_type);
+        // Check for OIDC provider errors (e.g., user denied access)
+        if (oidcError) {
+            const error = (0, error_utils_1.handleProviderError)({ error: oidcError, error_description });
+            // Call onAuthError callback if provided
+            const { options } = ctx.plugins.oidc;
+            if (options.onAuthError) {
+                const errorResult = await options.onAuthError({
+                    error,
+                    provider,
+                });
+                if (errorResult.redirectUrl) {
+                    return {
+                        status: 302,
+                        headers: { Location: errorResult.redirectUrl },
+                        data: {},
+                    };
+                }
+            }
+            return (0, flink_1.badRequest)(error.message);
+        }
+        // Validate required parameters
+        if (!code || !state) {
+            throw (0, error_utils_1.createOidcError)(error_utils_1.OidcErrorCodes.MISSING_CODE, "Missing authorization code or state parameter", {
+                hasCode: !!code,
+                hasState: !!state,
+            });
+        }
+        // Find OIDC session by state
+        const session = await ctx.repos.oidcSessionRepo.getByState(state);
+        if (!session) {
+            throw (0, error_utils_1.createOidcError)(error_utils_1.OidcErrorCodes.SESSION_EXPIRED, "OIDC session not found or expired. Please try logging in again.", { state });
+        }
+        // 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) + "...",
+            });
+        }
+        // Delete session immediately after validation (one-time use)
+        await ctx.repos.oidcSessionRepo.deleteBySessionId(session.sessionId);
+        // Get plugin options
+        const { options } = ctx.plugins.oidc;
+        // Get provider instance
+        const providerRegistry = ctx.oidcProviderRegistry;
+        if (!providerRegistry) {
+            throw (0, error_utils_1.createOidcError)(error_utils_1.OidcErrorCodes.PROVIDER_NOT_CONFIGURED, "OIDC plugin not properly initialized");
+        }
+        const oidcProvider = await providerRegistry.getProvider(provider);
+        // Exchange authorization code for tokens with PKCE validation
+        const tokenSet = await oidcProvider.exchangeCodeForToken({
+            code,
+            codeVerifier: session.codeVerifier,
+            state: session.state,
+            nonce: session.nonce,
+        });
+        // Build user profile from ID token and UserInfo
+        const profile = await oidcProvider.buildProfile(tokenSet, true);
+        // Call onAuthSuccess callback to create/link user and generate JWT token
+        const authSuccessParams = {
+            profile,
+            claims: tokenSet.claims,
+            provider,
+            ...(options.storeTokens ? { tokens: tokenSet } : {}),
+        };
+        let authResult;
+        try {
+            authResult = await options.onAuthSuccess(authSuccessParams, ctx);
+        }
+        catch (error) {
+            // Handle JWT generation or user creation errors
+            flink_1.log.error("OIDC onAuthSuccess callback failed:", error);
+            const oidcError = (0, error_utils_1.createOidcError)(error_utils_1.OidcErrorCodes.JWT_GENERATION_FAILED, "Failed to complete authentication. Please try again.", {
+                originalError: error.message,
+            });
+            // Call onAuthError callback if provided
+            if (options.onAuthError) {
+                const errorResult = await options.onAuthError({
+                    error: oidcError,
+                    provider,
+                });
+                if (errorResult.redirectUrl) {
+                    return {
+                        status: 302,
+                        headers: { Location: errorResult.redirectUrl },
+                        data: {},
+                    };
+                }
+            }
+            return (0, flink_1.internalServerError)("Authentication failed. Please try again.");
+        }
+        // Extract user and JWT token from callback result
+        const { user, token, redirectUrl } = authResult;
+        if (!token) {
+            throw (0, error_utils_1.createOidcError)(error_utils_1.OidcErrorCodes.JWT_GENERATION_FAILED, "No authentication token returned from callback", { hasUser: !!user });
+        }
+        // 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 encryptionSecret = options.encryptionKey || staticProviderConfig?.clientSecret;
+            if (!encryptionSecret) {
+                flink_1.log.warn("No encryption secret available, tokens will not be stored");
+            }
+            else {
+                // Encrypt tokens before storing
+                const encryptedAccessToken = (0, encryption_utils_1.encryptToken)(tokenSet.accessToken, encryptionSecret);
+                const encryptedIdToken = (0, encryption_utils_1.encryptToken)(tokenSet.idToken, encryptionSecret);
+                const encryptedRefreshToken = tokenSet.refreshToken ? (0, encryption_utils_1.encryptToken)(tokenSet.refreshToken, encryptionSecret) : undefined;
+                // Calculate token expiration
+                const expiresAt = tokenSet.expiresIn ? new Date(Date.now() + tokenSet.expiresIn * 1000) : undefined;
+                // Create or update OIDC connection
+                const existingConnection = await ctx.repos.oidcConnectionRepo.findByUserAndProvider(user._id, provider);
+                if (existingConnection) {
+                    await ctx.repos.oidcConnectionRepo.updateOne(existingConnection._id, {
+                        accessToken: encryptedAccessToken,
+                        idToken: encryptedIdToken,
+                        refreshToken: encryptedRefreshToken,
+                        scope: tokenSet.scope || "",
+                        expiresAt,
+                        updatedAt: new Date(),
+                    });
+                }
+                else {
+                    await ctx.repos.oidcConnectionRepo.create({
+                        userId: user._id,
+                        provider,
+                        subject: tokenSet.claims.sub,
+                        issuer: tokenSet.claims.iss,
+                        email: profile.email,
+                        accessToken: encryptedAccessToken,
+                        idToken: encryptedIdToken,
+                        refreshToken: encryptedRefreshToken,
+                        scope: tokenSet.scope || "",
+                        expiresAt,
+                        createdAt: new Date(),
+                        updatedAt: new Date(),
+                    });
+                }
+            }
+        }
+        // Return JWT token in requested format
+        return (0, response_utils_1.formatTokenResponse)(token, user, redirectUrl || session.redirectUri, response_type);
+    }
+    catch (error) {
+        flink_1.log.error("OIDC callback error:", error);
+        // Handle OIDC-specific errors
+        if (error.code && Object.values(error_utils_1.OidcErrorCodes).includes(error.code)) {
+            // Call onAuthError callback if provided
+            const { options } = ctx.plugins.oidc;
+            if (options.onAuthError) {
+                try {
+                    const errorResult = await options.onAuthError({
+                        error,
+                        provider,
+                    });
+                    if (errorResult.redirectUrl) {
+                        return {
+                            status: 302,
+                            headers: { Location: errorResult.redirectUrl },
+                            data: {},
+                        };
+                    }
+                }
+                catch (callbackError) {
+                    flink_1.log.error("onAuthError callback failed:", callbackError);
+                }
+            }
+            return (0, flink_1.badRequest)(error.message);
+        }
+        // Handle provider errors
+        const mappedError = (0, error_utils_1.handleProviderError)(error);
+        return (0, flink_1.internalServerError)(mappedError.message);
+    }
+};
+exports.default = CallbackOidc;

package/dist/handlers/InitiateOidc.d.ts

@@ -0,0 +1,35 @@
+/**
+ * OIDC Initiate Handler
+ *
+ * Initiates the OIDC authorization code flow by:
+ * 1. Validating the provider is supported and configured
+ * 2. Generating cryptographically secure state, code_verifier, and nonce
+ * 3. Creating an OIDC session to track the flow
+ * 4. Building the provider's authorization URL with PKCE
+ * 5. Redirecting the user to the provider for authorization
+ *
+ * Route: GET /oidc/:provider/initiate?redirectUri={optional_redirect_url}
+ */
+import { GetHandler, RouteProps } from "@flink-app/flink";
+import InitiateRequest from "../schemas/InitiateRequest";
+/**
+ * Path parameters for the handler
+ */
+interface PathParams {
+    provider: string;
+    [key: string]: string;
+}
+/**
+ * Route configuration
+ * This handler is registered programmatically by the plugin
+ */
+export declare const Route: RouteProps;
+/**
+ * OIDC Initiate Handler
+ *
+ * Starts the OIDC flow by generating security parameters, creating a session,
+ * and redirecting to the OIDC provider's authorization URL.
+ */
+declare const InitiateOidc: GetHandler<any, any, PathParams, InitiateRequest>;
+export default InitiateOidc;
+//# sourceMappingURL=InitiateOidc.d.ts.map

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

@@ -0,0 +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"}