@flink-app/oidc-plugin 1.0.0

package/src/providers/OidcProvider.ts

@@ -0,0 +1,237 @@
+import { Issuer, Client, generators, TokenSet, UserinfoResponse } from "openid-client";
+import { OidcProviderConfig } from "../OidcProviderConfig";
+import OidcProfile from "../schemas/OidcProfile";
+import OidcTokenSet from "../schemas/OidcTokenSet";
+import { mapClaimsToProfile, extractCustomClaims } from "../utils/claims-mapper";
+import { createOidcError, OidcErrorCodes } from "../utils/error-utils";
+
+/**
+ * Generic OIDC Provider implementation using openid-client
+ *
+ * Supports both OIDC discovery and manual configuration.
+ * Handles the complete OIDC flow including:
+ * - Authorization URL generation with PKCE
+ * - Token exchange (code → tokens)
+ * - ID token validation
+ * - UserInfo endpoint fetching
+ * - Claims mapping to profile
+ */
+export class OidcProvider {
+    private config: OidcProviderConfig;
+    private issuer: Issuer<Client> | null = null;
+    private client: Client | null = null;
+    private initialized: boolean = false;
+
+    constructor(config: OidcProviderConfig) {
+        this.config = config;
+    }
+
+    /**
+     * Initialize the provider by discovering or creating the OIDC client
+     *
+     * Uses OIDC discovery if discoveryUrl is provided, otherwise uses
+     * manual endpoint configuration.
+     *
+     * This is async and should be called before using the provider.
+     */
+    async initialize(): Promise<void> {
+        if (this.initialized) {
+            return;
+        }
+
+        try {
+            // Option 1: OIDC Discovery
+            if (this.config.discoveryUrl) {
+                this.issuer = await Issuer.discover(this.config.discoveryUrl);
+            }
+            // Option 2: Manual configuration
+            else {
+                // Validate required endpoints for manual config
+                if (!this.config.authorizationEndpoint || !this.config.tokenEndpoint || !this.config.jwksUri) {
+                    throw createOidcError(
+                        OidcErrorCodes.PROVIDER_NOT_CONFIGURED,
+                        "Provider must have either discoveryUrl or manual endpoints (authorizationEndpoint, tokenEndpoint, jwksUri)",
+                        { provider: this.config.issuer }
+                    );
+                }
+
+                this.issuer = new Issuer({
+                    issuer: this.config.issuer,
+                    authorization_endpoint: this.config.authorizationEndpoint,
+                    token_endpoint: this.config.tokenEndpoint,
+                    userinfo_endpoint: this.config.userinfoEndpoint,
+                    jwks_uri: this.config.jwksUri,
+                });
+            }
+
+            // Create OIDC client
+            this.client = new this.issuer.Client({
+                client_id: this.config.clientId,
+                client_secret: this.config.clientSecret,
+                redirect_uris: [this.config.callbackUrl],
+                response_types: ["code"],
+            });
+
+            this.initialized = true;
+        } catch (error: any) {
+            throw createOidcError(OidcErrorCodes.DISCOVERY_FAILED, `Failed to initialize OIDC provider: ${error.message}`, {
+                issuer: this.config.issuer,
+                originalError: error.message,
+            });
+        }
+    }
+
+    /**
+     * Generate authorization URL with PKCE and nonce
+     *
+     * @param params - Authorization parameters
+     * @returns Authorization URL to redirect user to
+     */
+    async getAuthorizationUrl(params: { state: string; codeVerifier: string; nonce: string }): Promise<string> {
+        await this.ensureInitialized();
+
+        const codeChallenge = generators.codeChallenge(params.codeVerifier);
+        const scope = this.config.scope?.join(" ") || "openid email profile";
+
+        const authUrl = this.client!.authorizationUrl({
+            scope,
+            state: params.state,
+            code_challenge: codeChallenge,
+            code_challenge_method: "S256",
+            nonce: params.nonce,
+        });
+
+        return authUrl;
+    }
+
+    /**
+     * Exchange authorization code for tokens
+     *
+     * Performs the OAuth 2.0 token exchange and validates the ID token.
+     *
+     * @param params - Token exchange parameters
+     * @returns Token set with access token, ID token, and claims
+     */
+    async exchangeCodeForToken(params: { code: string; codeVerifier: string; state: string; nonce: string }): Promise<OidcTokenSet> {
+        await this.ensureInitialized();
+
+        try {
+            const tokenSet: TokenSet = await this.client!.callback(
+                this.config.callbackUrl,
+                {
+                    code: params.code,
+                    state: params.state,
+                },
+                {
+                    code_verifier: params.codeVerifier,
+                    state: params.state,
+                    nonce: params.nonce,
+                }
+            );
+
+            // Extract claims from ID token (already validated by openid-client)
+            const claims = tokenSet.claims();
+
+            return {
+                accessToken: tokenSet.access_token!,
+                idToken: tokenSet.id_token!,
+                refreshToken: tokenSet.refresh_token,
+                tokenType: tokenSet.token_type || "Bearer",
+                expiresIn: tokenSet.expires_in,
+                scope: tokenSet.scope,
+                claims,
+            };
+        } catch (error: any) {
+            throw createOidcError(OidcErrorCodes.TOKEN_EXCHANGE_FAILED, `Token exchange failed: ${error.message}`, {
+                originalError: error.message,
+                errorCode: error.error,
+            });
+        }
+    }
+
+    /**
+     * Get user profile from UserInfo endpoint
+     *
+     * Fetches additional user claims from the UserInfo endpoint.
+     * Merges with claims from ID token.
+     *
+     * @param accessToken - Access token from token exchange
+     * @returns UserInfo response
+     */
+    async getUserInfo(accessToken: string): Promise<UserinfoResponse> {
+        await this.ensureInitialized();
+
+        try {
+            const userinfo = await this.client!.userinfo(accessToken);
+            return userinfo;
+        } catch (error: any) {
+            throw createOidcError(OidcErrorCodes.USERINFO_FAILED, `UserInfo request failed: ${error.message}`, {
+                originalError: error.message,
+            });
+        }
+    }
+
+    /**
+     * Build complete user profile from tokens
+     *
+     * Combines claims from ID token and UserInfo endpoint,
+     * applies custom claim mapping, and returns normalized profile.
+     *
+     * @param tokenSet - Token set from exchange
+     * @param includeUserInfo - Whether to fetch UserInfo endpoint
+     * @returns Normalized user profile
+     */
+    async buildProfile(tokenSet: OidcTokenSet, includeUserInfo: boolean = true): Promise<OidcProfile> {
+        let claims = { ...tokenSet.claims };
+
+        // Optionally fetch additional claims from UserInfo endpoint
+        if (includeUserInfo && this.config.userinfoEndpoint) {
+            try {
+                const userinfo = await this.getUserInfo(tokenSet.accessToken);
+                // Merge UserInfo claims with ID token claims
+                claims = { ...claims, ...userinfo };
+            } catch (error) {
+                // UserInfo is optional - continue with ID token claims only
+                console.warn("Failed to fetch UserInfo, using ID token claims only:", error);
+            }
+        }
+
+        // Apply custom claim mapping if configured
+        if (this.config.claimMapping) {
+            const customClaims = extractCustomClaims(claims, this.config.claimMapping);
+            claims = { ...claims, ...customClaims };
+        }
+
+        // Map to normalized profile
+        const profile = mapClaimsToProfile(claims);
+
+        return profile;
+    }
+
+    /**
+     * Ensure provider is initialized before use
+     *
+     * @throws Error if not initialized
+     */
+    private async ensureInitialized(): Promise<void> {
+        if (!this.initialized) {
+            await this.initialize();
+        }
+
+        if (!this.client) {
+            throw createOidcError(OidcErrorCodes.PROVIDER_NOT_CONFIGURED, "OIDC client not initialized");
+        }
+    }
+
+    /**
+     * Get issuer metadata (after initialization)
+     *
+     * @returns Issuer metadata
+     */
+    getIssuerMetadata(): any {
+        if (!this.issuer) {
+            throw createOidcError(OidcErrorCodes.PROVIDER_NOT_CONFIGURED, "Provider not initialized");
+        }
+        return this.issuer.metadata;
+    }
+}

package/src/providers/ProviderRegistry.ts

@@ -0,0 +1,107 @@
+import { OidcProvider } from "./OidcProvider";
+import { OidcProviderConfig } from "../OidcProviderConfig";
+import { createOidcError, OidcErrorCodes } from "../utils/error-utils";
+
+/**
+ * Provider registry for managing OIDC provider instances
+ *
+ * Handles:
+ * - Static provider configuration
+ * - Dynamic provider loading from database
+ * - Provider instance caching
+ * - Lazy initialization
+ */
+export class ProviderRegistry {
+    private staticProviders: Record<string, OidcProviderConfig>;
+    private providerInstances: Map<string, OidcProvider> = new Map();
+    private providerLoader?: (providerName: string) => Promise<OidcProviderConfig | null>;
+
+    constructor(
+        staticProviders: Record<string, OidcProviderConfig>,
+        providerLoader?: (providerName: string) => Promise<OidcProviderConfig | null>
+    ) {
+        this.staticProviders = staticProviders;
+        this.providerLoader = providerLoader;
+    }
+
+    /**
+     * Get provider instance by name
+     *
+     * Looks up provider in the following order:
+     * 1. Cached instance
+     * 2. Static configuration
+     * 3. Dynamic loader (if configured)
+     *
+     * Providers are lazy-initialized on first use and cached.
+     *
+     * @param providerName - Provider identifier
+     * @returns Initialized OIDC provider instance
+     * @throws Error if provider not found or initialization fails
+     */
+    async getProvider(providerName: string): Promise<OidcProvider> {
+        // Check cache first
+        const cachedProvider = this.providerInstances.get(providerName);
+        if (cachedProvider) {
+            return cachedProvider;
+        }
+
+        // Try static configuration
+        let config: OidcProviderConfig | null = this.staticProviders[providerName] || null;
+
+        // Try dynamic loader if not in static config
+        if (!config && this.providerLoader) {
+            config = await this.providerLoader(providerName);
+        }
+
+        if (!config) {
+            throw createOidcError(OidcErrorCodes.PROVIDER_NOT_CONFIGURED, `OIDC provider '${providerName}' is not configured`, {
+                providerName,
+                availableProviders: Object.keys(this.staticProviders),
+            });
+        }
+
+        // Create and initialize provider
+        const provider = new OidcProvider(config);
+        await provider.initialize();
+
+        // Cache the instance
+        this.providerInstances.set(providerName, provider);
+
+        return provider;
+    }
+
+    /**
+     * Check if provider exists in static configuration or can be loaded dynamically
+     *
+     * @param providerName - Provider identifier
+     * @returns true if provider exists, false otherwise
+     */
+    hasProvider(providerName: string): boolean {
+        return providerName in this.staticProviders || !!this.providerLoader;
+    }
+
+    /**
+     * Clear provider cache
+     *
+     * Forces re-initialization of providers on next access.
+     * Useful when provider configurations change.
+     *
+     * @param providerName - Optional provider to clear (clears all if not specified)
+     */
+    clearCache(providerName?: string): void {
+        if (providerName) {
+            this.providerInstances.delete(providerName);
+        } else {
+            this.providerInstances.clear();
+        }
+    }
+
+    /**
+     * Get list of configured provider names
+     *
+     * @returns Array of provider names from static configuration
+     */
+    getProviderNames(): string[] {
+        return Object.keys(this.staticProviders);
+    }
+}

package/src/repos/OidcConnectionRepo.ts

@@ -0,0 +1,132 @@
+import { Collection, Db } from "mongodb";
+import OidcConnection from "../schemas/OidcConnection";
+
+/**
+ * Repository for OIDC connections
+ *
+ * Manages persistent connections between users and OIDC providers.
+ * Stores the mapping of app users to IdP subjects, and optionally
+ * stores encrypted tokens for API access.
+ */
+export default class OidcConnectionRepo {
+    private collection: Collection<OidcConnection>;
+
+    constructor(collectionName: string, db: Db) {
+        this.collection = db.collection<OidcConnection>(collectionName);
+    }
+
+    /**
+     * Create a new OIDC connection
+     *
+     * @param connection - Connection data
+     * @returns Created connection with _id
+     */
+    async create(connection: Omit<OidcConnection, "_id">): Promise<OidcConnection> {
+        const result = await this.collection.insertOne(connection as any);
+        return {
+            ...connection,
+            _id: result.insertedId.toString(),
+        };
+    }
+
+    /**
+     * Find connection by user ID and provider
+     *
+     * @param userId - Application user ID
+     * @param provider - Provider name
+     * @returns Connection or null if not found
+     */
+    async findByUserAndProvider(userId: string, provider: string): Promise<OidcConnection | null> {
+        const connection = await this.collection.findOne({ userId, provider });
+        if (!connection) {
+            return null;
+        }
+        return {
+            ...connection,
+            _id: connection._id?.toString(),
+        };
+    }
+
+    /**
+     * Find connection by subject and issuer
+     *
+     * Used to look up users by their IdP identity.
+     *
+     * @param subject - OIDC subject (sub claim)
+     * @param issuer - OIDC issuer (iss claim)
+     * @returns Connection or null if not found
+     */
+    async findBySubjectAndIssuer(subject: string, issuer: string): Promise<OidcConnection | null> {
+        const connection = await this.collection.findOne({ subject, issuer });
+        if (!connection) {
+            return null;
+        }
+        return {
+            ...connection,
+            _id: connection._id?.toString(),
+        };
+    }
+
+    /**
+     * Find all connections for a user
+     *
+     * @param userId - Application user ID
+     * @returns Array of connections
+     */
+    async findByUserId(userId: string): Promise<OidcConnection[]> {
+        const connections = await this.collection.find({ userId }).toArray();
+        return connections.map((conn) => ({
+            ...conn,
+            _id: conn._id?.toString(),
+        }));
+    }
+
+    /**
+     * Update connection
+     *
+     * Typically used to update tokens when they're refreshed.
+     *
+     * @param connectionId - Connection _id
+     * @param updates - Fields to update
+     */
+    async updateOne(connectionId: string, updates: Partial<OidcConnection>): Promise<void> {
+        await this.collection.updateOne({ _id: connectionId as any }, { $set: updates });
+    }
+
+    /**
+     * Delete connection by user and provider
+     *
+     * @param userId - Application user ID
+     * @param provider - Provider name
+     */
+    async deleteByUserAndProvider(userId: string, provider: string): Promise<void> {
+        await this.collection.deleteOne({ userId, provider });
+    }
+
+    /**
+     * Delete all connections for a user
+     *
+     * @param userId - Application user ID
+     */
+    async deleteByUserId(userId: string): Promise<number> {
+        const result = await this.collection.deleteMany({ userId });
+        return result.deletedCount;
+    }
+
+    /**
+     * Find one connection by query
+     *
+     * @param query - MongoDB query
+     * @returns Connection or null if not found
+     */
+    async getOne(query: Partial<OidcConnection>): Promise<OidcConnection | null> {
+        const connection = await this.collection.findOne(query as any);
+        if (!connection) {
+            return null;
+        }
+        return {
+            ...connection,
+            _id: connection._id?.toString(),
+        };
+    }
+}

package/src/repos/OidcSessionRepo.ts

@@ -0,0 +1,99 @@
+import { Collection, Db } from "mongodb";
+import OidcSession from "../schemas/OidcSession";
+
+/**
+ * Repository for OIDC sessions
+ *
+ * Manages temporary sessions during the OIDC authorization flow.
+ * Sessions are automatically deleted by MongoDB TTL index after expiration.
+ */
+export default class OidcSessionRepo {
+    private collection: Collection<OidcSession>;
+
+    constructor(collectionName: string, db: Db) {
+        this.collection = db.collection<OidcSession>(collectionName);
+    }
+
+    /**
+     * Create a new OIDC session
+     *
+     * @param session - Session data
+     * @returns Created session with _id
+     */
+    async create(session: Omit<OidcSession, "_id">): Promise<OidcSession> {
+        const result = await this.collection.insertOne(session as any);
+        return {
+            ...session,
+            _id: result.insertedId.toString(),
+        };
+    }
+
+    /**
+     * Find session by state parameter
+     *
+     * Used during callback to validate the state and retrieve session data.
+     *
+     * @param state - State parameter from callback
+     * @returns Session or null if not found
+     */
+    async getByState(state: string): Promise<OidcSession | null> {
+        const session = await this.collection.findOne({ state });
+        if (!session) {
+            return null;
+        }
+        return {
+            ...session,
+            _id: session._id?.toString(),
+        };
+    }
+
+    /**
+     * Find one session by query
+     *
+     * @param query - MongoDB query
+     * @returns Session or null if not found
+     */
+    async getOne(query: Partial<OidcSession>): Promise<OidcSession | null> {
+        const session = await this.collection.findOne(query as any);
+        if (!session) {
+            return null;
+        }
+        return {
+            ...session,
+            _id: session._id?.toString(),
+        };
+    }
+
+    /**
+     * Delete session by session ID
+     *
+     * Sessions are one-time use - delete after successful validation.
+     *
+     * @param sessionId - Session identifier
+     */
+    async deleteBySessionId(sessionId: string): Promise<void> {
+        await this.collection.deleteOne({ sessionId });
+    }
+
+    /**
+     * Delete session by state
+     *
+     * @param state - State parameter
+     */
+    async deleteByState(state: string): Promise<void> {
+        await this.collection.deleteOne({ state });
+    }
+
+    /**
+     * Delete all expired sessions
+     *
+     * This is handled automatically by MongoDB TTL index,
+     * but can be called manually for testing or cleanup.
+     */
+    async deleteExpired(): Promise<number> {
+        const result = await this.collection.deleteMany({
+            createdAt: { $lt: new Date(Date.now() - 600000) }, // 10 minutes
+        });
+        return result.deletedCount;
+    }
+}

package/src/schemas/CallbackRequest.ts

@@ -0,0 +1,41 @@
+/**
+ * Query parameters for the OIDC callback endpoint
+ *
+ * GET /oidc/:provider/callback?code=...&state=...&response_type=json
+ */
+export default interface CallbackRequest {
+    /**
+     * Authorization code from the IdP
+     * Required for successful authentication
+     */
+    code?: string;
+
+    /**
+     * State parameter for CSRF protection
+     * Must match the state stored in the session
+     */
+    state?: string;
+
+    /**
+     * Error code from the IdP (if authorization failed)
+     * e.g., "access_denied" if user cancelled
+     */
+    error?: string;
+
+    /**
+     * Human-readable error description from the IdP
+     */
+    error_description?: string;
+
+    /**
+     * Response format for the callback
+     * - "json": Return JSON response with user and token
+     * - undefined: Redirect to redirectUri with token in URL fragment
+     */
+    response_type?: "json";
+
+    /**
+     * Index signature for Flink Query type compatibility
+     */
+    [key: string]: string | string[] | undefined;
+}

package/src/schemas/InitiateRequest.ts

@@ -0,0 +1,17 @@
+/**
+ * Query parameters for the OIDC initiate endpoint
+ *
+ * GET /oidc/:provider/initiate?redirectUri=...
+ */
+export default interface InitiateRequest {
+    /**
+     * Optional redirect URI after successful authentication
+     * If not provided, uses the default callbackUrl from provider config
+     */
+    redirectUri?: string;
+
+    /**
+     * Index signature for Flink Query type compatibility
+     */
+    [key: string]: string | string[] | undefined;
+}