@flink-app/oidc-plugin 0.13.0

package/src/schemas/OidcConnection.ts

@@ -0,0 +1,80 @@
+/**
+ * OIDC connection linking a user to an IdP
+ *
+ * Persistent record of the user's connection to an OIDC provider.
+ * Stores the mapping between the app's user and the IdP's subject identifier.
+ * Optionally stores encrypted OAuth tokens if storeTokens is enabled.
+ */
+export default interface OidcConnection {
+    /**
+     * MongoDB document ID
+     */
+    _id?: string;
+
+    /**
+     * Application user ID
+     * References the user in your app's user collection
+     */
+    userId: string;
+
+    /**
+     * OIDC provider name (e.g., "acme", "contoso")
+     */
+    provider: string;
+
+    /**
+     * OIDC subject identifier from the IdP
+     * The 'sub' claim from the ID token - unique per user per IdP
+     */
+    subject: string;
+
+    /**
+     * OIDC issuer identifier
+     * The 'iss' claim from the ID token - identifies the IdP
+     */
+    issuer: string;
+
+    /**
+     * User's email from the IdP
+     * Optional - for reference and display
+     */
+    email?: string;
+
+    /**
+     * Encrypted access token (if storeTokens enabled)
+     * Used to call IdP APIs on behalf of the user
+     */
+    accessToken?: string;
+
+    /**
+     * Encrypted refresh token (if storeTokens enabled)
+     * Used to obtain new access tokens
+     */
+    refreshToken?: string;
+
+    /**
+     * Encrypted ID token (if storeTokens enabled)
+     * The JWT containing user claims
+     */
+    idToken?: string;
+
+    /**
+     * Space-separated list of granted scopes
+     */
+    scope?: string;
+
+    /**
+     * Access token expiration time
+     */
+    expiresAt?: Date;
+
+    /**
+     * Connection creation timestamp
+     */
+    createdAt: Date;
+
+    /**
+     * Last update timestamp
+     */
+    updatedAt: Date;
+}

package/src/schemas/OidcProfile.ts

@@ -0,0 +1,79 @@
+/**
+ * Normalized user profile from OIDC ID token and UserInfo endpoint
+ *
+ * This is the standardized profile format passed to the onAuthSuccess callback.
+ * Maps OIDC standard claims to a consistent profile structure.
+ */
+export default interface OidcProfile {
+    /**
+     * Subject identifier - unique user ID from the IdP
+     * OIDC standard claim: 'sub'
+     */
+    id: string;
+
+    /**
+     * User's email address
+     * OIDC standard claim: 'email'
+     */
+    email: string;
+
+    /**
+     * Whether the email has been verified by the IdP
+     * OIDC standard claim: 'email_verified'
+     */
+    emailVerified?: boolean;
+
+    /**
+     * User's full name
+     * OIDC standard claim: 'name'
+     */
+    name?: string;
+
+    /**
+     * User's given name (first name)
+     * OIDC standard claim: 'given_name'
+     */
+    givenName?: string;
+
+    /**
+     * User's family name (last name)
+     * OIDC standard claim: 'family_name'
+     */
+    familyName?: string;
+
+    /**
+     * User's middle name
+     * OIDC standard claim: 'middle_name'
+     */
+    middleName?: string;
+
+    /**
+     * User's preferred username
+     * OIDC standard claim: 'preferred_username'
+     */
+    username?: string;
+
+    /**
+     * URL of the user's profile picture
+     * OIDC standard claim: 'picture'
+     */
+    picture?: string;
+
+    /**
+     * User's phone number
+     * OIDC standard claim: 'phone_number'
+     */
+    phoneNumber?: string;
+
+    /**
+     * Whether the phone number has been verified
+     * OIDC standard claim: 'phone_number_verified'
+     */
+    phoneNumberVerified?: boolean;
+
+    /**
+     * Raw OIDC claims from ID token and UserInfo
+     * Contains all claims returned by the IdP
+     */
+    raw: Record<string, any>;
+}

package/src/schemas/OidcSession.ts

@@ -0,0 +1,52 @@
+/**
+ * OIDC session stored during the authorization flow
+ *
+ * Temporary session that exists only during the OAuth/OIDC flow (typically 10 minutes).
+ * Used for CSRF protection (state), PKCE (codeVerifier), and replay protection (nonce).
+ */
+export default interface OidcSession {
+    /**
+     * MongoDB document ID
+     */
+    _id?: string;
+
+    /**
+     * Unique session identifier
+     */
+    sessionId: string;
+
+    /**
+     * CSRF protection token
+     * Random value used to prevent cross-site request forgery attacks
+     */
+    state: string;
+
+    /**
+     * PKCE code verifier
+     * Secret value used to prove the client initiated the authorization request
+     */
+    codeVerifier: string;
+
+    /**
+     * Nonce for ID token validation
+     * Random value used to prevent replay attacks on the ID token
+     */
+    nonce: string;
+
+    /**
+     * Provider name (e.g., "acme", "contoso")
+     */
+    provider: string;
+
+    /**
+     * URL to redirect to after successful authentication
+     * Can be overridden by the client via query parameter
+     */
+    redirectUri: string;
+
+    /**
+     * Session creation timestamp
+     * MongoDB TTL index will automatically delete expired sessions
+     */
+    createdAt: Date;
+}

package/src/schemas/OidcTokenSet.ts

@@ -0,0 +1,47 @@
+/**
+ * OIDC token set returned from the token endpoint
+ *
+ * Contains the tokens issued by the IdP after successful authorization.
+ */
+export default interface OidcTokenSet {
+    /**
+     * Access token for calling IdP APIs
+     * Used to access protected resources at the IdP
+     */
+    accessToken: string;
+
+    /**
+     * ID token (JWT) containing user claims
+     * This is the core OIDC token that contains user identity information
+     */
+    idToken: string;
+
+    /**
+     * Refresh token for obtaining new access tokens
+     * Optional - only if IdP supports and grants refresh tokens
+     */
+    refreshToken?: string;
+
+    /**
+     * Token type (usually "Bearer")
+     */
+    tokenType: string;
+
+    /**
+     * Expiration time in seconds
+     * How many seconds until the access token expires
+     */
+    expiresIn?: number;
+
+    /**
+     * Scope granted by the IdP
+     * Space-separated list of scopes
+     */
+    scope?: string;
+
+    /**
+     * All claims from the ID token
+     * Parsed and validated JWT claims
+     */
+    claims: Record<string, any>;
+}

package/src/utils/claims-mapper.ts

@@ -0,0 +1,114 @@
+import OidcProfile from "../schemas/OidcProfile";
+
+/**
+ * Map OIDC claims to normalized profile
+ *
+ * Extracts standard OIDC claims from the ID token and UserInfo response
+ * and maps them to a consistent profile structure.
+ *
+ * Standard OIDC claims reference:
+ * https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims
+ *
+ * @param claims - OIDC claims from ID token and/or UserInfo endpoint
+ * @returns Normalized user profile
+ */
+export function mapClaimsToProfile(claims: Record<string, any>): OidcProfile {
+    return {
+        // Required - subject identifier (unique user ID)
+        id: claims.sub,
+
+        // Email
+        email: claims.email,
+        emailVerified: claims.email_verified,
+
+        // Name fields
+        name: claims.name,
+        givenName: claims.given_name,
+        familyName: claims.family_name,
+        middleName: claims.middle_name,
+
+        // Username
+        username: claims.preferred_username || claims.username,
+
+        // Picture
+        picture: claims.picture,
+
+        // Phone
+        phoneNumber: claims.phone_number,
+        phoneNumberVerified: claims.phone_number_verified,
+
+        // Keep all raw claims for custom access
+        raw: claims,
+    };
+}
+
+/**
+ * Extract custom claims using claim mapping configuration
+ *
+ * Allows extracting custom claims from the ID token using dot notation.
+ * Supports nested claim paths.
+ *
+ * @param claims - OIDC claims from ID token
+ * @param claimMapping - Map of field names to claim paths
+ * @returns Object with extracted custom claims
+ *
+ * Example:
+ * ```typescript
+ * const claims = {
+ *   sub: '123',
+ *   email: 'user@example.com',
+ *   'custom:department': 'Engineering',
+ *   'custom:role': 'Admin',
+ *   groups: ['engineers', 'admins']
+ * };
+ *
+ * const mapping = {
+ *   department: 'custom:department',
+ *   role: 'custom:role',
+ *   groups: 'groups'
+ * };
+ *
+ * const custom = extractCustomClaims(claims, mapping);
+ * // { department: 'Engineering', role: 'Admin', groups: ['engineers', 'admins'] }
+ * ```
+ */
+export function extractCustomClaims(claims: Record<string, any>, claimMapping: Record<string, string>): Record<string, any> {
+    const customClaims: Record<string, any> = {};
+
+    for (const [fieldName, claimPath] of Object.entries(claimMapping)) {
+        const value = getClaimByPath(claims, claimPath);
+        if (value !== undefined) {
+            customClaims[fieldName] = value;
+        }
+    }
+
+    return customClaims;
+}
+
+/**
+ * Get claim value by path (supports dot notation)
+ *
+ * @param claims - Claims object
+ * @param path - Claim path (e.g., "custom:department" or "address.street_address")
+ * @returns Claim value or undefined if not found
+ */
+function getClaimByPath(claims: Record<string, any>, path: string): any {
+    // Handle direct access first (for paths with colons like "custom:department")
+    if (path in claims) {
+        return claims[path];
+    }
+
+    // Handle nested paths with dot notation
+    const parts = path.split(".");
+    let value: any = claims;
+
+    for (const part of parts) {
+        if (value && typeof value === "object" && part in value) {
+            value = value[part];
+        } else {
+            return undefined;
+        }
+    }
+
+    return value;
+}

package/src/utils/encryption-utils.ts

@@ -0,0 +1,92 @@
+import { createCipheriv, createDecipheriv, randomBytes, createHash } from "crypto";
+
+const ALGORITHM = "aes-256-gcm";
+const IV_LENGTH = 16;
+const AUTH_TAG_LENGTH = 16;
+const SALT_LENGTH = 32;
+
+/**
+ * Derive a 32-byte encryption key from a secret
+ *
+ * Uses SHA-256 to create a consistent key length from any secret.
+ *
+ * @param secret - Secret string (e.g., client secret)
+ * @returns 32-byte key suitable for AES-256
+ */
+function deriveKey(secret: string): Buffer {
+    return createHash("sha256").update(secret).digest();
+}
+
+/**
+ * Validate encryption secret meets minimum requirements
+ *
+ * @param secret - Secret to validate
+ * @throws Error if secret is invalid
+ */
+export function validateEncryptionSecret(secret: string): void {
+    if (!secret) {
+        throw new Error("Encryption secret is required");
+    }
+
+    if (secret.length < 32) {
+        throw new Error("Encryption secret must be at least 32 characters");
+    }
+}
+
+/**
+ * Encrypt a token using AES-256-GCM
+ *
+ * Uses Galois/Counter Mode (GCM) which provides both confidentiality
+ * and authenticity (prevents tampering).
+ *
+ * Format: iv:authTag:encryptedData (all hex-encoded)
+ *
+ * @param token - Plain text token to encrypt
+ * @param secret - Encryption secret (at least 32 characters)
+ * @returns Encrypted token with IV and auth tag
+ */
+export function encryptToken(token: string, secret: string): string {
+    const key = deriveKey(secret);
+    const iv = randomBytes(IV_LENGTH);
+    const cipher = createCipheriv(ALGORITHM, key, iv);
+
+    let encrypted = cipher.update(token, "utf8", "hex");
+    encrypted += cipher.final("hex");
+
+    const authTag = cipher.getAuthTag();
+
+    // Format: iv:authTag:encryptedData
+    return `${iv.toString("hex")}:${authTag.toString("hex")}:${encrypted}`;
+}
+
+/**
+ * Decrypt a token using AES-256-GCM
+ *
+ * Validates the auth tag to ensure the data hasn't been tampered with.
+ *
+ * @param encryptedToken - Encrypted token from encryptToken()
+ * @param secret - Encryption secret used during encryption
+ * @returns Decrypted plain text token
+ * @throws Error if decryption fails or auth tag is invalid
+ */
+export function decryptToken(encryptedToken: string, secret: string): string {
+    const parts = encryptedToken.split(":");
+
+    if (parts.length !== 3) {
+        throw new Error("Invalid encrypted token format");
+    }
+
+    const [ivHex, authTagHex, encryptedData] = parts;
+
+    const key = deriveKey(secret);
+    const iv = Buffer.from(ivHex, "hex");
+    const authTag = Buffer.from(authTagHex, "hex");
+
+    const decipher = createDecipheriv(ALGORITHM, key, iv);
+    decipher.setAuthTag(authTag);
+
+    let decrypted = decipher.update(encryptedData, "hex", "utf8");
+    decrypted += decipher.final("utf8");
+
+    return decrypted;
+}

package/src/utils/error-utils.ts

@@ -0,0 +1,167 @@
+import { OidcError } from "../OidcPluginOptions";
+
+/**
+ * Standard OIDC error codes
+ */
+export const OidcErrorCodes = {
+    // Configuration errors
+    INVALID_PROVIDER: "invalid_provider",
+    PROVIDER_NOT_CONFIGURED: "provider_not_configured",
+    DISCOVERY_FAILED: "discovery_failed",
+
+    // Request validation errors
+    MISSING_CODE: "missing_code",
+    MISSING_STATE: "missing_state",
+    INVALID_STATE: "invalid_state",
+    INVALID_RESPONSE_TYPE: "invalid_response_type",
+
+    // Session errors
+    SESSION_NOT_FOUND: "session_not_found",
+    SESSION_EXPIRED: "session_expired",
+
+    // Token exchange errors
+    TOKEN_EXCHANGE_FAILED: "token_exchange_failed",
+    INVALID_TOKEN: "invalid_token",
+    ID_TOKEN_VALIDATION_FAILED: "id_token_validation_failed",
+
+    // User/Profile errors
+    USERINFO_FAILED: "userinfo_failed",
+    PROFILE_EXTRACTION_FAILED: "profile_extraction_failed",
+
+    // JWT generation errors
+    JWT_GENERATION_FAILED: "jwt_generation_failed",
+
+    // IdP errors (from authorization endpoint)
+    ACCESS_DENIED: "access_denied",
+    UNAUTHORIZED_CLIENT: "unauthorized_client",
+    INVALID_REQUEST: "invalid_request",
+    UNSUPPORTED_RESPONSE_TYPE: "unsupported_response_type",
+    INVALID_SCOPE: "invalid_scope",
+    SERVER_ERROR: "server_error",
+    TEMPORARILY_UNAVAILABLE: "temporarily_unavailable",
+} as const;
+
+/**
+ * Create a standardized OIDC error object
+ *
+ * @param code - Error code from OidcErrorCodes
+ * @param message - Human-readable error message
+ * @param details - Additional error details for debugging
+ * @returns OIDC error object
+ */
+export function createOidcError(code: string, message: string, details?: any): OidcError {
+    const error: OidcError = {
+        code,
+        message,
+    };
+
+    if (details) {
+        error.details = details;
+    }
+
+    // Make it throwable
+    const throwableError = new Error(message) as Error & OidcError;
+    throwableError.code = code;
+    throwableError.details = details;
+
+    return throwableError as any;
+}
+
+/**
+ * Validate provider name format
+ *
+ * Provider names must be alphanumeric with optional hyphens/underscores
+ * to ensure they work correctly in URLs.
+ *
+ * @param provider - Provider name to validate
+ * @throws OidcError if invalid
+ */
+export function validateProvider(provider: string): void {
+    if (!provider) {
+        throw createOidcError(OidcErrorCodes.INVALID_PROVIDER, "Provider name is required", { provider });
+    }
+
+    // Allow alphanumeric, hyphens, underscores
+    if (!/^[a-zA-Z0-9_-]+$/.test(provider)) {
+        throw createOidcError(OidcErrorCodes.INVALID_PROVIDER, "Provider name must be alphanumeric (hyphens and underscores allowed)", { provider });
+    }
+}
+
+/**
+ * Validate response type parameter
+ *
+ * @param responseType - Response type from query parameter
+ * @throws OidcError if invalid
+ */
+export function validateResponseType(responseType?: string): void {
+    if (responseType && responseType !== "json") {
+        throw createOidcError(OidcErrorCodes.INVALID_RESPONSE_TYPE, 'Invalid response_type. Must be "json" or omitted for redirect', {
+            responseType,
+        });
+    }
+}
+
+/**
+ * Map IdP error codes to user-friendly messages
+ *
+ * Maps OAuth 2.0 / OIDC error codes from the IdP to our standardized
+ * error format with helpful messages.
+ *
+ * @param error - Error object or string from IdP
+ * @returns Standardized OIDC error
+ */
+export function handleProviderError(error: any): OidcError {
+    const errorCode = typeof error === "string" ? error : error.error || error.code;
+    const errorDescription = error.error_description || error.message;
+
+    // Map common OAuth/OIDC errors
+    switch (errorCode) {
+        case "access_denied":
+            return createOidcError(OidcErrorCodes.ACCESS_DENIED, "User denied authorization", {
+                originalError: errorCode,
+                description: errorDescription,
+            });
+
+        case "unauthorized_client":
+            return createOidcError(OidcErrorCodes.UNAUTHORIZED_CLIENT, "Client not authorized for this request", {
+                originalError: errorCode,
+                description: errorDescription,
+            });
+
+        case "invalid_request":
+            return createOidcError(OidcErrorCodes.INVALID_REQUEST, "Invalid authorization request", {
+                originalError: errorCode,
+                description: errorDescription,
+            });
+
+        case "unsupported_response_type":
+            return createOidcError(OidcErrorCodes.UNSUPPORTED_RESPONSE_TYPE, "Response type not supported by IdP", {
+                originalError: errorCode,
+                description: errorDescription,
+            });
+
+        case "invalid_scope":
+            return createOidcError(OidcErrorCodes.INVALID_SCOPE, "Invalid or unsupported scope", {
+                originalError: errorCode,
+                description: errorDescription,
+            });
+
+        case "server_error":
+            return createOidcError(OidcErrorCodes.SERVER_ERROR, "IdP server error", {
+                originalError: errorCode,
+                description: errorDescription,
+            });
+
+        case "temporarily_unavailable":
+            return createOidcError(OidcErrorCodes.TEMPORARILY_UNAVAILABLE, "IdP temporarily unavailable", {
+                originalError: errorCode,
+                description: errorDescription,
+            });
+
+        default:
+            return createOidcError(OidcErrorCodes.SERVER_ERROR, errorDescription || "Unknown IdP error", {
+                originalError: errorCode,
+                description: errorDescription,
+            });
+    }
+}

package/src/utils/response-utils.ts

@@ -0,0 +1,41 @@
+/**
+ * Format token response for the client
+ *
+ * Supports two response formats:
+ * 1. JSON response (for API clients)
+ * 2. Redirect with token in URL fragment (for web browsers)
+ *
+ * URL fragments are used for security - they are NOT sent to the server
+ * in HTTP requests and are only accessible to client-side JavaScript.
+ *
+ * @param token - JWT token for the application
+ * @param user - User object
+ * @param redirectUrl - URL to redirect to
+ * @param responseType - "json" or undefined (redirect)
+ * @returns Flink response object
+ */
+export function formatTokenResponse(token: string, user: any, redirectUrl: string, responseType?: "json"): any {
+    // JSON response for API clients
+    if (responseType === "json") {
+        return {
+            data: {
+                user,
+                token,
+            },
+        };
+    }
+
+    // Redirect response for web browsers
+    // Token is in URL fragment (#token=...) for security
+    const separator = redirectUrl.includes("#") ? "&" : "#";
+    const tokenFragment = `token=${encodeURIComponent(token)}`;
+    const finalUrl = `${redirectUrl}${separator}${tokenFragment}`;
+
+    return {
+        status: 302,
+        headers: {
+            Location: finalUrl,
+        },
+        data: {},
+    };
+}