@flink-app/oidc-plugin 1.0.0

package/src/OidcPlugin.ts

@@ -0,0 +1,290 @@
+import { FlinkApp, FlinkPlugin, log } from "@flink-app/flink";
+import { Db } from "mongodb";
+import { OidcPluginOptions } from "./OidcPluginOptions";
+import { OidcPluginContext } from "./OidcPluginContext";
+import { OidcInternalContext } from "./OidcInternalContext";
+import OidcSessionRepo from "./repos/OidcSessionRepo";
+import OidcConnectionRepo from "./repos/OidcConnectionRepo";
+import { encryptToken, decryptToken, validateEncryptionSecret } from "./utils/encryption-utils";
+import OidcConnection from "./schemas/OidcConnection";
+import { ProviderRegistry } from "./providers/ProviderRegistry";
+import * as InitiateOidc from "./handlers/InitiateOidc";
+import * as CallbackOidc from "./handlers/CallbackOidc";
+
+/**
+ * OIDC Plugin Factory Function
+ *
+ * Creates a Flink plugin for OIDC authentication with generic IdP support.
+ * Integrates with JWT Auth Plugin for token generation.
+ *
+ * @param options - OIDC plugin configuration options
+ * @returns FlinkPlugin instance
+ *
+ * @example
+ * ```typescript
+ * import { jwtAuthPlugin } from '@flink-app/jwt-auth-plugin';
+ * import { oidcPlugin } from '@flink-app/oidc-plugin';
+ *
+ * const app = new FlinkApp({
+ *   auth: jwtAuthPlugin({
+ *     secret: process.env.JWT_SECRET!,
+ *     getUser: async (tokenData) => {
+ *       return ctx.repos.userRepo.getById(tokenData.userId);
+ *     },
+ *     rolePermissions: {
+ *       user: ['read:own'],
+ *       admin: ['read:all', 'write:all']
+ *     }
+ *   }),
+ *
+ *   plugins: [
+ *     oidcPlugin({
+ *       providers: {
+ *         acme: {
+ *           issuer: 'https://idp.acme.com',
+ *           clientId: process.env.OIDC_CLIENT_ID!,
+ *           clientSecret: process.env.OIDC_CLIENT_SECRET!,
+ *           callbackUrl: 'https://myapp.com/oidc/acme/callback',
+ *           discoveryUrl: 'https://idp.acme.com/.well-known/openid-configuration'
+ *         }
+ *       },
+ *       onAuthSuccess: async ({ profile, claims, provider }, ctx) => {
+ *         // Find or create user (JIT provisioning)
+ *         let user = await ctx.repos.userRepo.getOne({
+ *           'oidcConnections.subject': claims.sub,
+ *           'oidcConnections.issuer': claims.iss
+ *         });
+ *
+ *         if (!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'
+ *         };
+ *       }
+ *     })
+ *   ]
+ * });
+ * ```
+ */
+export function oidcPlugin(options: OidcPluginOptions): FlinkPlugin {
+    // Validation
+    if (!options.providers || Object.keys(options.providers).length === 0) {
+        throw new Error("OIDC Plugin: At least one provider must be configured");
+    }
+
+    // Validate provider configurations
+    const configuredProviders = Object.keys(options.providers);
+    for (const providerName of configuredProviders) {
+        const providerConfig = options.providers[providerName];
+        if (!providerConfig) continue;
+
+        if (!providerConfig.issuer) {
+            throw new Error(`OIDC Plugin: ${providerName} issuer is required`);
+        }
+        if (!providerConfig.clientId) {
+            throw new Error(`OIDC Plugin: ${providerName} clientId is required`);
+        }
+        if (!providerConfig.clientSecret) {
+            throw new Error(`OIDC Plugin: ${providerName} clientSecret is required`);
+        }
+        if (!providerConfig.callbackUrl) {
+            throw new Error(`OIDC Plugin: ${providerName} callbackUrl is required`);
+        }
+
+        // Validate that either discoveryUrl or manual endpoints are provided
+        if (!providerConfig.discoveryUrl) {
+            if (!providerConfig.authorizationEndpoint || !providerConfig.tokenEndpoint || !providerConfig.jwksUri) {
+                throw new Error(
+                    `OIDC Plugin: ${providerName} must have either discoveryUrl or manual endpoints ` +
+                        `(authorizationEndpoint, tokenEndpoint, jwksUri)`
+                );
+            }
+        }
+    }
+
+    if (!options.onAuthSuccess) {
+        throw new Error("OIDC Plugin: onAuthSuccess callback is required");
+    }
+
+    // Determine encryption key
+    let encryptionKey = options.encryptionKey;
+    if (!encryptionKey) {
+        // Derive from first configured provider's client secret
+        const firstProvider = configuredProviders[0];
+        const firstProviderConfig = options.providers[firstProvider];
+        if (firstProviderConfig) {
+            encryptionKey = firstProviderConfig.clientSecret;
+            log.warn(
+                "OIDC Plugin: No encryption key provided, deriving from client secret. " + "For better security, provide a dedicated encryptionKey in options."
+            );
+        }
+    }
+
+    if (!encryptionKey || encryptionKey.length < 32) {
+        throw new Error("OIDC Plugin: Encryption key must be at least 32 characters");
+    }
+
+    // Validate encryption key
+    validateEncryptionSecret(encryptionKey);
+
+    let flinkApp: FlinkApp<OidcInternalContext>;
+    let sessionRepo: OidcSessionRepo;
+    let connectionRepo: OidcConnectionRepo;
+    let providerRegistry: ProviderRegistry;
+
+    /**
+     * Plugin initialization
+     */
+    async function init(app: FlinkApp<any>, db?: Db) {
+        log.info("Initializing OIDC Plugin...");
+
+        flinkApp = app as FlinkApp<OidcInternalContext>;
+
+        try {
+            if (!db) {
+                throw new Error("OIDC Plugin: Database connection is required");
+            }
+
+            // Initialize repositories
+            const sessionsCollectionName = options.sessionsCollectionName || "oidc_sessions";
+            const connectionsCollectionName = options.connectionsCollectionName || "oidc_connections";
+
+            sessionRepo = new OidcSessionRepo(sessionsCollectionName, db);
+            connectionRepo = new OidcConnectionRepo(connectionsCollectionName, db);
+
+            flinkApp.addRepo("oidcSessionRepo", sessionRepo as any);
+            flinkApp.addRepo("oidcConnectionRepo", connectionRepo as any);
+
+            // Create TTL index for session expiration
+            const sessionTTL = options.sessionTTL || 600; // Default 10 minutes
+            await db.collection(sessionsCollectionName).createIndex({ createdAt: 1 }, { expireAfterSeconds: sessionTTL });
+
+            log.info(`OIDC Plugin: Created TTL index on ${sessionsCollectionName} with ${sessionTTL}s expiration`);
+
+            // Initialize provider registry
+            providerRegistry = new ProviderRegistry(options.providers, options.providerLoader);
+
+            // Store provider registry in app context for handlers to access
+            (flinkApp.ctx as any).oidcProviderRegistry = providerRegistry;
+
+            // Register OIDC handlers
+            // Only register handlers if registerRoutes is enabled (default: true)
+            if (options.registerRoutes !== false) {
+                flinkApp.addHandler(InitiateOidc);
+                flinkApp.addHandler(CallbackOidc);
+            }
+
+            log.info(`OIDC Plugin initialized with providers: ${configuredProviders.join(", ")}`);
+        } catch (error) {
+            log.error("Failed to initialize OIDC Plugin:", error);
+            throw error;
+        }
+    }
+
+    /**
+     * Get OIDC connection for a user
+     */
+    async function getConnection(userId: string, provider: string): Promise<OidcConnection | null> {
+        if (!connectionRepo) {
+            throw new Error("OIDC Plugin: Plugin not initialized");
+        }
+
+        const connection = await connectionRepo.findByUserAndProvider(userId, provider);
+
+        if (!connection) {
+            return null;
+        }
+
+        // Decrypt tokens before returning
+        if (connection.accessToken && encryptionKey) {
+            connection.accessToken = decryptToken(connection.accessToken, encryptionKey);
+        }
+
+        if (connection.idToken && encryptionKey) {
+            connection.idToken = decryptToken(connection.idToken, encryptionKey);
+        }
+
+        if (connection.refreshToken && encryptionKey) {
+            connection.refreshToken = decryptToken(connection.refreshToken, encryptionKey);
+        }
+
+        return connection;
+    }
+
+    /**
+     * Get all OIDC connections for a user
+     */
+    async function getConnections(userId: string): Promise<OidcConnection[]> {
+        if (!connectionRepo) {
+            throw new Error("OIDC Plugin: Plugin not initialized");
+        }
+
+        const connections = await connectionRepo.findByUserId(userId);
+
+        // Decrypt tokens in each connection
+        return connections.map((connection) => {
+            if (connection.accessToken && encryptionKey) {
+                connection.accessToken = decryptToken(connection.accessToken, encryptionKey);
+            }
+
+            if (connection.idToken && encryptionKey) {
+                connection.idToken = decryptToken(connection.idToken, encryptionKey);
+            }
+
+            if (connection.refreshToken && encryptionKey) {
+                connection.refreshToken = decryptToken(connection.refreshToken, encryptionKey);
+            }
+
+            return connection;
+        });
+    }
+
+    /**
+     * Delete OIDC connection for a user
+     */
+    async function deleteConnection(userId: string, provider: string): Promise<void> {
+        if (!connectionRepo) {
+            throw new Error("OIDC Plugin: Plugin not initialized");
+        }
+
+        await connectionRepo.deleteByUserAndProvider(userId, provider);
+        log.info(`OIDC Plugin: Deleted ${provider} connection for user ${userId}`);
+    }
+
+    /**
+     * Plugin context exposed via ctx.plugins.oidc
+     */
+    const pluginCtx: OidcPluginContext["oidc"] = {
+        getConnection,
+        getConnections,
+        deleteConnection,
+        options: Object.freeze({ ...options }),
+    };
+
+    return {
+        id: "oidc",
+        db: {
+            useHostDb: true,
+        },
+        ctx: pluginCtx,
+        init,
+    };
+}

package/src/OidcPluginContext.ts

@@ -0,0 +1,76 @@
+import OidcConnection from "./schemas/OidcConnection";
+import { OidcPluginOptions } from "./OidcPluginOptions";
+
+/**
+ * OIDC Plugin context API exposed via ctx.plugins.oidc
+ *
+ * Provides methods to manage OIDC connections for users.
+ */
+export interface OidcPluginContext {
+    oidc: {
+        /**
+         * Get OIDC connection for a user and provider
+         *
+         * Returns the stored OIDC connection with decrypted tokens (if storeTokens enabled).
+         *
+         * @param userId - Application user ID
+         * @param provider - Provider name (e.g., "acme")
+         * @returns OIDC connection or null if not found
+         *
+         * Example:
+         * ```typescript
+         * const connection = await ctx.plugins.oidc.getConnection(user._id, 'acme');
+         * if (connection) {
+         *   console.log('User connected to:', connection.issuer);
+         *   console.log('Subject:', connection.subject);
+         *   if (connection.accessToken) {
+         *     // Use access token to call IdP APIs
+         *   }
+         * }
+         * ```
+         */
+        getConnection: (userId: string, provider: string) => Promise<OidcConnection | null>;
+
+        /**
+         * Get all OIDC connections for a user
+         *
+         * Returns all IdP connections for the user with decrypted tokens.
+         *
+         * @param userId - Application user ID
+         * @returns Array of OIDC connections
+         *
+         * Example:
+         * ```typescript
+         * const connections = await ctx.plugins.oidc.getConnections(user._id);
+         * console.log('User has', connections.length, 'IdP connections');
+         * connections.forEach(conn => {
+         *   console.log('- Provider:', conn.provider, 'Email:', conn.email);
+         * });
+         * ```
+         */
+        getConnections: (userId: string) => Promise<OidcConnection[]>;
+
+        /**
+         * Delete/unlink OIDC connection for a user
+         *
+         * Removes the connection between the user and the IdP.
+         * The user will need to re-authenticate with the IdP.
+         *
+         * @param userId - Application user ID
+         * @param provider - Provider name (e.g., "acme")
+         *
+         * Example:
+         * ```typescript
+         * // User wants to disconnect their Acme account
+         * await ctx.plugins.oidc.deleteConnection(user._id, 'acme');
+         * ```
+         */
+        deleteConnection: (userId: string, provider: string) => Promise<void>;
+
+        /**
+         * Plugin configuration options (read-only)
+         * Useful for checking plugin settings at runtime
+         */
+        options: Readonly<OidcPluginOptions>;
+    };
+}

package/src/OidcPluginOptions.ts

@@ -0,0 +1,286 @@
+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;
+}