@flink-app/oidc-plugin 1.0.0

package/src/OidcProviderConfig.ts

@@ -0,0 +1,87 @@
+/**
+ * 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>;
+}

package/src/handlers/CallbackOidc.ts

@@ -0,0 +1,257 @@
+/**
+ * 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, HttpMethod, RouteProps, badRequest, internalServerError, log } from "@flink-app/flink";
+import CallbackRequest from "../schemas/CallbackRequest";
+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";
+
+/**
+ * Path parameters for the handler
+ */
+interface PathParams {
+    provider: string;
+    [key: string]: string;
+}
+
+/**
+ * Route configuration
+ * This handler is registered programmatically by the plugin
+ */
+export const Route: RouteProps = {
+    path: "/oidc/:provider/callback",
+    method: 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: GetHandler<any, any, PathParams, CallbackRequest> = async ({ ctx, req }) => {
+    const { provider } = req.params;
+    const { code, state, error: oidcError, error_description, response_type } = req.query;
+
+    try {
+        // Validate provider and response_type
+        validateProvider(provider);
+        validateResponseType(response_type);
+
+        // Check for OIDC provider errors (e.g., user denied access)
+        if (oidcError) {
+            const error = 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 badRequest(error.message);
+        }
+
+        // Validate required parameters
+        if (!code || !state) {
+            throw createOidcError(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 createOidcError(OidcErrorCodes.SESSION_EXPIRED, "OIDC session not found or expired. Please try logging in again.", { state });
+        }
+
+        // Validate state parameter (CSRF protection)
+        if (!validateState(state, session.state)) {
+            throw createOidcError(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 as any).oidcProviderRegistry;
+        if (!providerRegistry) {
+            throw createOidcError(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: any) {
+            // Handle JWT generation or user creation errors
+            log.error("OIDC onAuthSuccess callback failed:", error);
+
+            const oidcError = createOidcError(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 internalServerError("Authentication failed. Please try again.");
+        }
+
+        // Extract user and JWT token from callback result
+        const { user, token, redirectUrl } = authResult;
+
+        if (!token) {
+            throw createOidcError(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) {
+                log.warn("No encryption secret available, tokens will not be stored");
+            } else {
+                // Encrypt tokens before storing
+                const encryptedAccessToken = encryptToken(tokenSet.accessToken, encryptionSecret);
+                const encryptedIdToken = encryptToken(tokenSet.idToken, encryptionSecret);
+                const encryptedRefreshToken = tokenSet.refreshToken ? 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 formatTokenResponse(token, user, redirectUrl || session.redirectUri, response_type);
+    } catch (error: any) {
+        log.error("OIDC callback error:", error);
+
+        // Handle OIDC-specific errors
+        if (error.code && Object.values(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) {
+                    log.error("onAuthError callback failed:", callbackError);
+                }
+            }
+
+            return badRequest(error.message);
+        }
+
+        // Handle provider errors
+        const mappedError = handleProviderError(error);
+        return internalServerError(mappedError.message);
+    }
+};
+
+export default CallbackOidc;

package/src/handlers/InitiateOidc.ts

@@ -0,0 +1,110 @@
+/**
+ * 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, HttpMethod, RouteProps, badRequest, internalServerError } from "@flink-app/flink";
+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";
+
+/**
+ * Path parameters for the handler
+ */
+interface PathParams {
+    provider: string;
+    [key: string]: string;
+}
+
+/**
+ * Route configuration
+ * This handler is registered programmatically by the plugin
+ */
+export const Route: RouteProps = {
+    path: "/oidc/:provider/initiate",
+    method: HttpMethod.get,
+};
+
+/**
+ * OIDC Initiate Handler
+ *
+ * Starts the OIDC flow by generating security parameters, creating a session,
+ * and redirecting to the OIDC provider's authorization URL.
+ */
+const InitiateOidc: GetHandler<any, any, PathParams, InitiateRequest> = async ({ ctx, req }) => {
+    const { provider } = req.params;
+    const { redirectUri } = req.query;
+
+    try {
+        // Validate provider name format
+        validateProvider(provider);
+
+        // Get provider registry from context
+        const providerRegistry = (ctx as any).oidcProviderRegistry;
+        if (!providerRegistry) {
+            throw createOidcError(OidcErrorCodes.PROVIDER_NOT_CONFIGURED, "OIDC plugin not properly initialized");
+        }
+
+        // Get OIDC provider instance (loads dynamically if needed)
+        const oidcProvider = await providerRegistry.getProvider(provider);
+
+        // Get plugin options
+        const { options } = ctx.plugins.oidc;
+
+        // 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`;
+
+        // Generate cryptographically secure parameters
+        const state = generateState();
+        const sessionId = generateSessionId();
+        const nonce = generateNonce();
+        const codeVerifier = generators.codeVerifier();
+
+        // Store session for state validation in callback
+        await ctx.repos.oidcSessionRepo.create({
+            sessionId,
+            state,
+            codeVerifier,
+            nonce,
+            provider,
+            redirectUri: finalRedirectUri,
+            createdAt: new Date(),
+        });
+
+        // Build authorization URL with PKCE and nonce
+        const authorizationUrl = await oidcProvider.getAuthorizationUrl({
+            state,
+            codeVerifier,
+            nonce,
+        });
+
+        // Redirect user to provider's authorization page
+        return {
+            status: 302,
+            headers: {
+                Location: authorizationUrl,
+            },
+            data: {},
+        };
+    } catch (error: any) {
+        // Handle validation errors
+        if (error.code && Object.values(OidcErrorCodes).includes(error.code)) {
+            return badRequest(error.message);
+        }
+
+        // Handle unexpected errors
+        return internalServerError(error.message || "Failed to initiate OIDC flow");
+    }
+};
+
+export default InitiateOidc;

package/src/index.ts

@@ -0,0 +1,38 @@
+/**
+ * @flink-app/oidc-plugin
+ *
+ * OIDC authentication plugin for Flink Framework
+ *
+ * Provides OpenID Connect authentication with generic IdP support,
+ * JWT integration via jwt-auth-plugin, JIT user provisioning,
+ * and optional token storage for API access.
+ */
+
+// Main plugin factory
+export { oidcPlugin } from "./OidcPlugin";
+
+// Configuration types
+export { OidcPluginOptions, OidcError, AuthSuccessCallbackResponse, AuthErrorCallbackResponse } from "./OidcPluginOptions";
+export { OidcProviderConfig } from "./OidcProviderConfig";
+
+// Context types
+export { OidcPluginContext } from "./OidcPluginContext";
+
+// Schema types
+export { default as OidcProfile } from "./schemas/OidcProfile";
+export { default as OidcTokenSet } from "./schemas/OidcTokenSet";
+export { default as OidcSession } from "./schemas/OidcSession";
+export { default as OidcConnection } from "./schemas/OidcConnection";
+export { default as InitiateRequest } from "./schemas/InitiateRequest";
+export { default as CallbackRequest } from "./schemas/CallbackRequest";
+
+// Provider classes (for advanced usage)
+export { OidcProvider } from "./providers/OidcProvider";
+export { ProviderRegistry } from "./providers/ProviderRegistry";
+
+// Utility functions (for custom implementations)
+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 { createOidcError, validateProvider, handleProviderError, OidcErrorCodes } from "./utils/error-utils";