@flink-app/oauth-plugin 0.12.1-alpha.33

package/src/utils/error-utils.ts

@@ -0,0 +1,139 @@
+/**
+ * OAuth Error Interface and Utilities
+ *
+ * Provides standardized error handling for OAuth flows including
+ * user-friendly messages and error code mapping.
+ */
+
+/**
+ * Standardized OAuth error structure
+ */
+export interface OAuthError {
+    /** Error code for programmatic handling */
+    code: string;
+
+    /** User-friendly error message */
+    message: string;
+
+    /** Additional error details (for logging, not user display) */
+    details?: any;
+}
+
+/**
+ * OAuth error codes
+ */
+export const OAuthErrorCodes = {
+    INVALID_STATE: "invalid_state",
+    ACCESS_DENIED: "access_denied",
+    INVALID_GRANT: "invalid_grant",
+    NETWORK_ERROR: "network_error",
+    UNKNOWN_PROVIDER: "unknown_provider",
+    JWT_GENERATION_FAILED: "jwt_generation_failed",
+    INVALID_REQUEST: "invalid_request",
+    SERVER_ERROR: "server_error",
+    INVALID_PROVIDER: "invalid_provider",
+    SESSION_EXPIRED: "session_expired",
+    MISSING_CODE: "missing_code",
+} as const;
+
+/**
+ * Create a standardized OAuth error
+ *
+ * @param code - Error code from OAuthErrorCodes
+ * @param message - User-friendly error message
+ * @param details - Additional error details for logging
+ * @returns Standardized OAuthError object
+ */
+export function createOAuthError(code: string, message: string, details?: any): OAuthError {
+    return {
+        code,
+        message,
+        details,
+    };
+}
+
+/**
+ * Map provider-specific errors to standardized OAuth errors
+ *
+ * This function converts various error types from OAuth providers
+ * into user-friendly standardized errors while sanitizing sensitive data.
+ *
+ * @param error - Error from OAuth provider or internal error
+ * @returns Standardized OAuthError
+ */
+export function handleProviderError(error: any): OAuthError {
+    // Handle OAuth provider error responses
+    if (error.error) {
+        const errorCode = error.error;
+
+        switch (errorCode) {
+            case "access_denied":
+                return createOAuthError(OAuthErrorCodes.ACCESS_DENIED, "You denied access to your account. Please try again if you want to continue.", {
+                    providerError: errorCode,
+                });
+
+            case "invalid_grant":
+            case "invalid_code":
+                return createOAuthError(OAuthErrorCodes.INVALID_GRANT, "The authorization code has expired or is invalid. Please try logging in again.", {
+                    providerError: errorCode,
+                });
+
+            case "invalid_request":
+                return createOAuthError(OAuthErrorCodes.INVALID_REQUEST, "There was a problem with the authentication request. Please try again.", {
+                    providerError: errorCode,
+                });
+
+            default:
+                return createOAuthError(OAuthErrorCodes.SERVER_ERROR, "An error occurred during authentication. Please try again.", {
+                    providerError: errorCode,
+                });
+        }
+    }
+
+    // Handle network errors
+    if (error.code === "ENOTFOUND" || error.code === "ECONNREFUSED" || error.code === "ETIMEDOUT") {
+        return createOAuthError(OAuthErrorCodes.NETWORK_ERROR, "Unable to connect to the authentication service. Please check your connection and try again.", {
+            networkError: error.code,
+        });
+    }
+
+    // Handle JWT generation errors
+    if (error.message && error.message.includes("JWT")) {
+        return createOAuthError(OAuthErrorCodes.JWT_GENERATION_FAILED, "Failed to generate authentication token. Please try again.", {
+            originalError: error.message,
+        });
+    }
+
+    // Generic error fallback
+    return createOAuthError(OAuthErrorCodes.SERVER_ERROR, "An unexpected error occurred. Please try again.", {
+        originalError: error.message || "Unknown error",
+    });
+}
+
+/**
+ * Validate provider name
+ *
+ * @param provider - Provider name to validate
+ * @returns true if valid provider
+ * @throws OAuthError if invalid
+ */
+export function validateProvider(provider: string): provider is "github" | "google" {
+    if (provider !== "github" && provider !== "google") {
+        throw createOAuthError(OAuthErrorCodes.INVALID_PROVIDER, `Provider "${provider}" is not supported. Supported providers: github, google`, { provider });
+    }
+    return true;
+}
+
+/**
+ * Validate response_type parameter
+ *
+ * @param responseType - Response type to validate
+ * @returns true if valid
+ * @throws OAuthError if invalid
+ */
+export function validateResponseType(responseType?: string): boolean {
+    if (responseType && responseType !== "json") {
+        throw createOAuthError(OAuthErrorCodes.INVALID_REQUEST, `Invalid response_type "${responseType}". Supported values: json`, { responseType });
+    }
+    return true;
+}

package/src/utils/state-utils.ts

@@ -0,0 +1,70 @@
+/**
+ * State Parameter Utilities for CSRF Protection
+ *
+ * Provides cryptographically secure state parameter generation
+ * and constant-time comparison for OAuth CSRF protection.
+ */
+
+import crypto from "crypto";
+
+/**
+ * Generate a cryptographically secure state parameter
+ *
+ * Creates a 32-byte random state parameter for CSRF protection
+ * in OAuth flows. This state is stored in the session and must
+ * match when the OAuth provider redirects back.
+ *
+ * @returns Hex-encoded 32-byte random string (64 characters)
+ */
+export function generateState(): string {
+    return crypto.randomBytes(32).toString("hex");
+}
+
+/**
+ * Validate state parameter using constant-time comparison
+ *
+ * Compares the provided state with the stored state using a
+ * constant-time algorithm to prevent timing attacks.
+ *
+ * @param provided - State parameter from OAuth provider callback
+ * @param stored - State parameter stored in session
+ * @returns true if states match, false otherwise
+ */
+export function validateState(provided: string, stored: string): boolean {
+    if (!provided || !stored) {
+        return false;
+    }
+
+    // Ensure both strings are the same length to prevent timing attacks
+    if (provided.length !== stored.length) {
+        return false;
+    }
+
+    try {
+        // Use Node.js crypto.timingSafeEqual for constant-time comparison
+        const providedBuffer = Buffer.from(provided, "utf8");
+        const storedBuffer = Buffer.from(stored, "utf8");
+
+        // Both buffers must be same length for timingSafeEqual
+        if (providedBuffer.length !== storedBuffer.length) {
+            return false;
+        }
+
+        return crypto.timingSafeEqual(providedBuffer, storedBuffer);
+    } catch (error) {
+        // If comparison fails for any reason, return false
+        return false;
+    }
+}
+
+/**
+ * Generate a session ID for OAuth flow tracking
+ *
+ * Creates a unique session identifier for correlating OAuth
+ * initiation with callback.
+ *
+ * @returns Hex-encoded random string
+ */
+export function generateSessionId(): string {
+    return crypto.randomBytes(16).toString("hex");
+}

package/src/utils/token-response-utils.ts

@@ -0,0 +1,49 @@
+/**
+ * Formats the OAuth callback response with JWT token.
+ * Supports multiple response formats:
+ * - JSON response with user and token
+ * - URL fragment redirect with token
+ * - Query parameter redirect with token
+ *
+ * @param token - JWT token to return
+ * @param user - User object to return
+ * @param redirectUrl - Optional redirect URL
+ * @param responseType - Response format ('json' or undefined for redirect)
+ * @returns Response object for Flink handler
+ */
+export function formatTokenResponse(token: string, user: any, redirectUrl?: string, responseType?: string): any {
+    // JSON response format
+    if (responseType === "json") {
+        return {
+            status: 200,
+            data: {
+                user,
+                token,
+            },
+        };
+    }
+
+    // Redirect format
+    if (redirectUrl) {
+        // Use URL fragment for better security (token not sent to server)
+        const separator = redirectUrl.includes("#") ? "&" : "#";
+        const fullRedirectUrl = `${redirectUrl}${separator}token=${encodeURIComponent(token)}`;
+
+        return {
+            status: 302,
+            headers: {
+                Location: fullRedirectUrl,
+            },
+            data: {},
+        };
+    }
+
+    // Default: return JSON if no redirect URL provided
+    return {
+        status: 200,
+        data: {
+            user,
+            token,
+        },
+    };
+}

package/src/utils/validation-utils.ts

@@ -0,0 +1,120 @@
+/**
+ * Input Validation Utilities
+ *
+ * Provides validation functions for OAuth handler inputs including
+ * provider names, query parameters, and redirect URIs.
+ */
+
+import { createOAuthError, OAuthErrorCodes } from "./error-utils";
+
+/**
+ * Validate provider parameter
+ *
+ * @param provider - Provider name from URL parameter
+ * @returns Validated provider name
+ * @throws OAuthError if invalid
+ */
+export function validateProvider(provider: string): "github" | "google" {
+    if (!provider) {
+        throw createOAuthError(OAuthErrorCodes.INVALID_PROVIDER, "Provider is required", { provider });
+    }
+
+    if (provider !== "github" && provider !== "google") {
+        throw createOAuthError(OAuthErrorCodes.INVALID_PROVIDER, 'Provider "' + provider + '" is not supported. Supported providers: github, google', {
+            provider,
+        });
+    }
+
+    return provider;
+}
+
+/**
+ * Validate response_type parameter
+ *
+ * @param responseType - Response type from query parameter
+ * @returns Validated response type or undefined
+ * @throws OAuthError if invalid
+ */
+export function validateResponseType(responseType?: string): string | undefined {
+    if (!responseType) {
+        return undefined;
+    }
+
+    if (responseType !== "json") {
+        throw createOAuthError(OAuthErrorCodes.INVALID_REQUEST, 'Invalid response_type "' + responseType + '". Supported values: json', { responseType });
+    }
+
+    return responseType;
+}
+
+/**
+ * Validate redirect URI format
+ *
+ * @param redirectUri - Redirect URI to validate
+ * @returns true if valid or undefined
+ * @throws OAuthError if invalid
+ */
+export function validateRedirectUri(redirectUri?: string): boolean {
+    if (!redirectUri) {
+        return true;
+    }
+
+    try {
+        const url = new URL(redirectUri);
+
+        // Check protocol
+        if (url.protocol !== "http:" && url.protocol !== "https:") {
+            throw createOAuthError(OAuthErrorCodes.INVALID_REQUEST, "Redirect URI must use HTTP or HTTPS protocol", { redirectUri });
+        }
+
+        return true;
+    } catch (error) {
+        if (error && typeof error === "object" && "code" in error) {
+            throw error;
+        }
+
+        throw createOAuthError(OAuthErrorCodes.INVALID_REQUEST, "Invalid redirect URI format", { redirectUri });
+    }
+}
+
+/**
+ * Validate state parameter exists
+ *
+ * @param state - State parameter from query
+ * @throws OAuthError if missing
+ */
+export function validateStateParam(state?: string): void {
+    if (!state) {
+        throw createOAuthError(OAuthErrorCodes.INVALID_STATE, "State parameter is required", { state });
+    }
+}
+
+/**
+ * Validate authorization code exists
+ *
+ * @param code - Authorization code from query
+ * @throws OAuthError if missing
+ */
+export function validateAuthCode(code?: string): void {
+    if (!code) {
+        throw createOAuthError(OAuthErrorCodes.MISSING_CODE, "Authorization code is required", { code });
+    }
+}
+
+/**
+ * Check for OAuth error in callback query parameters
+ *
+ * @param errorParam - Error parameter from OAuth provider
+ * @param errorDescription - Error description from OAuth provider
+ * @throws OAuthError if error present
+ */
+export function checkOAuthErrorParam(errorParam?: string, errorDescription?: string): void {
+    if (errorParam) {
+        const message = errorDescription || "Authentication failed";
+
+        throw createOAuthError(errorParam === "access_denied" ? OAuthErrorCodes.ACCESS_DENIED : OAuthErrorCodes.SERVER_ERROR, message, {
+            error: errorParam,
+            description: errorDescription,
+        });
+    }
+}

package/tsconfig.dist.json

@@ -0,0 +1,4 @@
+{
+  "extends": "./tsconfig",
+  "exclude": ["spec/**/*.ts"]
+}

package/tsconfig.json

@@ -0,0 +1,24 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "lib": ["ES2020"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "strict": true,
+    "forceConsistentCasingInFileNames": true,
+    "module": "commonjs",
+    "moduleResolution": "node",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": false,
+    "declaration": true,
+    "experimentalDecorators": true,
+    "checkJs": true,
+    "outDir": "dist",
+    "typeRoots": ["./node_modules/@types"]
+  },
+  "include": ["./src/*", "./spec/*"],
+  "exclude": ["./node_modules/*"]
+}