@flink-app/oauth-plugin 0.12.1-alpha.35 → 0.12.1-alpha.37

package/dist/OAuthPlugin.js

@@ -1,4 +1,27 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
@@ -8,6 +31,8 @@ const flink_1 = require("@flink-app/flink");
 const OAuthSessionRepo_1 = __importDefault(require("./repos/OAuthSessionRepo"));
 const OAuthConnectionRepo_1 = __importDefault(require("./repos/OAuthConnectionRepo"));
 const encryption_utils_1 = require("./utils/encryption-utils");
+const InitiateOAuth = __importStar(require("./handlers/InitiateOAuth"));
+const CallbackOAuth = __importStar(require("./handlers/CallbackOAuth"));
 /**
  * OAuth Plugin Factory Function
  *
@@ -139,10 +164,12 @@ function oauthPlugin(options) {
             const sessionTTL = options.sessionTTL || 600; // Default 10 minutes
             await db.collection(sessionsCollectionName).createIndex({ createdAt: 1 }, { expireAfterSeconds: sessionTTL });
             flink_1.log.info(`OAuth Plugin: Created TTL index on ${sessionsCollectionName} with ${sessionTTL}s expiration`);
-            // Register handlers for each configured provider
-            // Note: Handlers will be registered dynamically
-            // This requires handlers to be imported, but we'll handle that in the handler files
-            // For now, we'll skip handler registration and implement it when handlers are ready
+            // Register OAuth handlers
+            // Only register handlers if registerRoutes is enabled (default: true)
+            if (options.registerRoutes !== false) {
+                flinkApp.addHandler(InitiateOAuth);
+                flinkApp.addHandler(CallbackOAuth);
+            }
             flink_1.log.info(`OAuth Plugin initialized with providers: ${configuredProviders.join(", ")}`);
         }
         catch (error) {

package/dist/OAuthPluginOptions.d.ts

@@ -108,4 +108,10 @@ export interface OAuthPluginOptions {
      * Recommended: Use a dedicated encryption key from environment variables
      */
     encryptionKey?: string;
+    /**
+     * Whether to register OAuth routes automatically
+     * If false, you must manually handle OAuth flow
+     * Default: true
+     */
+    registerRoutes?: boolean;
 }

package/dist/handlers/CallbackOAuth.d.ts

@@ -0,0 +1,37 @@
+/**
+ * OAuth Callback Handler
+ *
+ * Handles the OAuth 2.0 callback from the provider by:
+ * 1. Validating the state parameter to prevent CSRF attacks
+ * 2. Exchanging the authorization code for an access token
+ * 3. Fetching the user profile from the provider
+ * 4. Calling the onAuthSuccess callback to create/link user and generate JWT token
+ * 5. Optionally storing the OAuth connection (if storeTokens enabled)
+ * 6. Returning the JWT token to the client (via JSON or redirect)
+ *
+ * Route: GET /oauth/:provider/callback?code=...&state=...&response_type=json
+ */
+import { GetHandler, RouteProps } from "@flink-app/flink";
+import CallbackRequest from "../schemas/CallbackRequest";
+/**
+ * Path parameters for the handler
+ */
+interface PathParams {
+    provider: string;
+    [key: string]: string;
+}
+/**
+ * Route configuration
+ * Note: This handler is registered programmatically by the plugin
+ * with dynamic provider parameter support
+ */
+export declare const Route: RouteProps;
+/**
+ * OAuth Callback Handler
+ *
+ * Completes the OAuth flow by exchanging the authorization code for tokens,
+ * fetching user profile, calling the app's onAuthSuccess callback to generate
+ * JWT token, and returning the token to the client.
+ */
+declare const CallbackOAuth: GetHandler<any, any, PathParams, CallbackRequest>;
+export default CallbackOAuth;

package/dist/handlers/CallbackOAuth.js

@@ -0,0 +1,201 @@
+"use strict";
+/**
+ * OAuth Callback Handler
+ *
+ * Handles the OAuth 2.0 callback from the provider by:
+ * 1. Validating the state parameter to prevent CSRF attacks
+ * 2. Exchanging the authorization code for an access token
+ * 3. Fetching the user profile from the provider
+ * 4. Calling the onAuthSuccess callback to create/link user and generate JWT token
+ * 5. Optionally storing the OAuth connection (if storeTokens enabled)
+ * 6. Returning the JWT token to the client (via JSON or redirect)
+ *
+ * Route: GET /oauth/:provider/callback?code=...&state=...&response_type=json
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Route = void 0;
+const flink_1 = require("@flink-app/flink");
+const state_utils_1 = require("../utils/state-utils");
+const ProviderRegistry_1 = require("../providers/ProviderRegistry");
+const token_response_utils_1 = require("../utils/token-response-utils");
+const encryption_utils_1 = require("../utils/encryption-utils");
+const error_utils_1 = require("../utils/error-utils");
+/**
+ * Route configuration
+ * Note: This handler is registered programmatically by the plugin
+ * with dynamic provider parameter support
+ */
+exports.Route = {
+    path: "/oauth/:provider/callback",
+    method: flink_1.HttpMethod.get,
+};
+/**
+ * OAuth Callback Handler
+ *
+ * Completes the OAuth flow by exchanging the authorization code for tokens,
+ * fetching user profile, calling the app's onAuthSuccess callback to generate
+ * JWT token, and returning the token to the client.
+ */
+const CallbackOAuth = async ({ ctx, req }) => {
+    const { provider } = req.params;
+    const { code, state, error: oauthError, response_type } = req.query;
+    try {
+        // Validate provider and response_type
+        (0, error_utils_1.validateProvider)(provider);
+        (0, error_utils_1.validateResponseType)(response_type);
+        // Check for OAuth provider errors (e.g., user denied access)
+        if (oauthError) {
+            const error = (0, error_utils_1.handleProviderError)({ error: oauthError });
+            // Call onAuthError callback if provided
+            const { options } = ctx.plugins.oauth;
+            if (options.onAuthError) {
+                const errorResult = await options.onAuthError({
+                    error,
+                    provider: provider,
+                });
+                if (errorResult.redirectUrl) {
+                    return {
+                        status: 302,
+                        headers: { Location: errorResult.redirectUrl },
+                        data: {},
+                    };
+                }
+            }
+            return (0, flink_1.badRequest)(error.message);
+        }
+        // Validate required parameters
+        if (!code || !state) {
+            throw (0, error_utils_1.createOAuthError)(error_utils_1.OAuthErrorCodes.MISSING_CODE, "Missing authorization code or state parameter", { hasCode: !!code, hasState: !!state });
+        }
+        // Find OAuth session by state
+        const session = await ctx.repos.oauthSessionRepo.getOne({ state });
+        if (!session) {
+            throw (0, error_utils_1.createOAuthError)(error_utils_1.OAuthErrorCodes.SESSION_EXPIRED, "OAuth session not found or expired. Please try logging in again.", { state });
+        }
+        // Validate state parameter (CSRF protection)
+        if (!(0, state_utils_1.validateState)(state, session.state)) {
+            throw (0, error_utils_1.createOAuthError)(error_utils_1.OAuthErrorCodes.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.oauthSessionRepo.deleteBySessionId(session.sessionId);
+        // Get plugin options and provider config
+        const { options } = ctx.plugins.oauth;
+        const providerConfig = options.providers[provider];
+        if (!providerConfig) {
+            throw (0, error_utils_1.createOAuthError)(error_utils_1.OAuthErrorCodes.INVALID_PROVIDER, `Provider "${provider}" is not configured`, { provider });
+        }
+        // Exchange authorization code for access token
+        const oauthProvider = (0, ProviderRegistry_1.getProvider)(provider, providerConfig);
+        const tokens = await oauthProvider.exchangeCodeForToken({
+            code,
+            redirectUri: providerConfig.callbackUrl,
+        });
+        // Fetch user profile from provider
+        const profile = await oauthProvider.getUserProfile(tokens.accessToken);
+        // Call onAuthSuccess callback to create/link user and generate JWT token
+        const authSuccessParams = {
+            profile,
+            provider: provider,
+            ...(options.storeTokens ? { tokens } : {}),
+        };
+        let authResult;
+        try {
+            authResult = await options.onAuthSuccess(authSuccessParams, ctx);
+        }
+        catch (error) {
+            // Handle JWT generation or user creation errors
+            flink_1.log.error("OAuth onAuthSuccess callback failed:", error);
+            const oauthError = (0, error_utils_1.createOAuthError)(error_utils_1.OAuthErrorCodes.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: oauthError,
+                    provider: provider,
+                });
+                if (errorResult.redirectUrl) {
+                    return {
+                        status: 302,
+                        headers: { Location: errorResult.redirectUrl },
+                        data: {},
+                    };
+                }
+            }
+            return (0, flink_1.internalServerError)("Authentication failed. Please try again.");
+        }
+        // Extract user and JWT token from callback result
+        const { user, token, redirectUrl } = authResult;
+        if (!token) {
+            throw (0, error_utils_1.createOAuthError)(error_utils_1.OAuthErrorCodes.JWT_GENERATION_FAILED, "No authentication token returned from callback", { hasUser: !!user });
+        }
+        // Store OAuth connection if token storage is enabled
+        if (options.storeTokens && user && user._id) {
+            const encryptionSecret = providerConfig.clientSecret;
+            // Encrypt tokens before storing
+            const encryptedAccessToken = (0, encryption_utils_1.encryptToken)(tokens.accessToken, encryptionSecret);
+            const encryptedRefreshToken = tokens.refreshToken ? (0, encryption_utils_1.encryptToken)(tokens.refreshToken, encryptionSecret) : undefined;
+            // Calculate token expiration
+            const expiresAt = tokens.expiresIn ? new Date(Date.now() + tokens.expiresIn * 1000) : undefined;
+            // Create or update OAuth connection
+            const existingConnection = await ctx.repos.oauthConnectionRepo.findByUserAndProvider(user._id, provider);
+            if (existingConnection) {
+                await ctx.repos.oauthConnectionRepo.updateOne(existingConnection._id, {
+                    accessToken: encryptedAccessToken,
+                    refreshToken: encryptedRefreshToken,
+                    scope: tokens.scope || "",
+                    expiresAt,
+                    updatedAt: new Date(),
+                });
+            }
+            else {
+                await ctx.repos.oauthConnectionRepo.create({
+                    userId: user._id,
+                    provider: provider,
+                    providerId: profile.id,
+                    accessToken: encryptedAccessToken,
+                    refreshToken: encryptedRefreshToken,
+                    scope: tokens.scope || "",
+                    expiresAt,
+                    createdAt: new Date(),
+                    updatedAt: new Date(),
+                });
+            }
+        }
+        // Return JWT token in requested format
+        return (0, token_response_utils_1.formatTokenResponse)(token, user, redirectUrl || session.redirectUri, response_type);
+    }
+    catch (error) {
+        flink_1.log.error("OAuth callback error:", error);
+        // Handle OAuth-specific errors
+        if (error.code && Object.values(error_utils_1.OAuthErrorCodes).includes(error.code)) {
+            // Call onAuthError callback if provided
+            const { options } = ctx.plugins.oauth;
+            if (options.onAuthError) {
+                try {
+                    const errorResult = await options.onAuthError({
+                        error,
+                        provider: provider,
+                    });
+                    if (errorResult.redirectUrl) {
+                        return {
+                            status: 302,
+                            headers: { Location: errorResult.redirectUrl },
+                            data: {},
+                        };
+                    }
+                }
+                catch (callbackError) {
+                    flink_1.log.error("onAuthError callback failed:", callbackError);
+                }
+            }
+            return (0, flink_1.badRequest)(error.message);
+        }
+        // Handle provider errors
+        const mappedError = (0, error_utils_1.handleProviderError)(error);
+        return (0, flink_1.internalServerError)(mappedError.message);
+    }
+};
+exports.default = CallbackOAuth;

package/dist/handlers/InitiateOAuth.d.ts

@@ -0,0 +1,35 @@
+/**
+ * OAuth Initiate Handler
+ *
+ * Initiates the OAuth 2.0 authorization code flow by:
+ * 1. Validating the provider is supported and configured
+ * 2. Generating a cryptographically secure state parameter for CSRF protection
+ * 3. Creating an OAuth session to track the flow
+ * 4. Building the provider's authorization URL
+ * 5. Redirecting the user to the provider for authorization
+ *
+ * Route: GET /oauth/:provider/initiate?redirectUri={optional_redirect_url}
+ */
+import { GetHandler, RouteProps } from "@flink-app/flink";
+import InitiateRequest from "../schemas/InitiateRequest";
+/**
+ * Path parameters for the handler
+ */
+interface PathParams {
+    provider: string;
+    [key: string]: string;
+}
+/**
+ * Route configuration
+ * Note: This handler is registered programmatically by the plugin
+ * with dynamic provider parameter support
+ */
+export declare const Route: RouteProps;
+/**
+ * OAuth Initiate Handler
+ *
+ * Starts the OAuth flow by generating state, creating a session,
+ * and redirecting to the OAuth provider's authorization URL.
+ */
+declare const InitiateOAuth: GetHandler<any, any, PathParams, InitiateRequest>;
+export default InitiateOAuth;

package/dist/handlers/InitiateOAuth.js

@@ -0,0 +1,83 @@
+"use strict";
+/**
+ * OAuth Initiate Handler
+ *
+ * Initiates the OAuth 2.0 authorization code flow by:
+ * 1. Validating the provider is supported and configured
+ * 2. Generating a cryptographically secure state parameter for CSRF protection
+ * 3. Creating an OAuth session to track the flow
+ * 4. Building the provider's authorization URL
+ * 5. Redirecting the user to the provider for authorization
+ *
+ * Route: GET /oauth/:provider/initiate?redirectUri={optional_redirect_url}
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Route = void 0;
+const flink_1 = require("@flink-app/flink");
+const state_utils_1 = require("../utils/state-utils");
+const ProviderRegistry_1 = require("../providers/ProviderRegistry");
+const error_utils_1 = require("../utils/error-utils");
+/**
+ * Route configuration
+ * Note: This handler is registered programmatically by the plugin
+ * with dynamic provider parameter support
+ */
+exports.Route = {
+    path: "/oauth/:provider/initiate",
+    method: flink_1.HttpMethod.get,
+};
+/**
+ * OAuth Initiate Handler
+ *
+ * Starts the OAuth flow by generating state, creating a session,
+ * and redirecting to the OAuth provider's authorization URL.
+ */
+const InitiateOAuth = async ({ ctx, req }) => {
+    const { provider } = req.params;
+    const { redirectUri } = req.query;
+    try {
+        // Validate provider is supported
+        (0, error_utils_1.validateProvider)(provider);
+        // Get plugin options and provider config
+        const { options } = ctx.plugins.oauth;
+        const providerConfig = options.providers[provider];
+        if (!providerConfig) {
+            throw (0, error_utils_1.createOAuthError)(error_utils_1.OAuthErrorCodes.INVALID_PROVIDER, `Provider "${provider}" is not configured`, { provider });
+        }
+        // Generate cryptographically secure state and session ID
+        const state = (0, state_utils_1.generateState)();
+        const sessionId = (0, state_utils_1.generateSessionId)();
+        // Store session for state validation in callback
+        await ctx.repos.oauthSessionRepo.create({
+            sessionId,
+            state,
+            provider: provider,
+            redirectUri: redirectUri || providerConfig.callbackUrl,
+            createdAt: new Date(),
+        });
+        // Get provider instance and build authorization URL
+        const oauthProvider = (0, ProviderRegistry_1.getProvider)(provider, providerConfig);
+        const authorizationUrl = oauthProvider.getAuthorizationUrl({
+            state,
+            redirectUri: providerConfig.callbackUrl,
+            scope: providerConfig.scope || [],
+        });
+        // Redirect user to provider's authorization page
+        return {
+            status: 302,
+            headers: {
+                Location: authorizationUrl,
+            },
+            data: {},
+        };
+    }
+    catch (error) {
+        // Handle validation errors
+        if (error.code && Object.values(error_utils_1.OAuthErrorCodes).includes(error.code)) {
+            return (0, flink_1.badRequest)(error.message);
+        }
+        // Handle unexpected errors
+        return (0, flink_1.internalServerError)(error.message || "Failed to initiate OAuth flow");
+    }
+};
+exports.default = InitiateOAuth;

package/dist/schemas/CallbackRequest.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Query parameters for OAuth callback request
+ */
+export default interface CallbackRequest {
+    /**
+     * Authorization code from OAuth provider
+     */
+    code: string;
+    /**
+     * CSRF protection state parameter
+     */
+    state: string;
+    /**
+     * Optional error from OAuth provider
+     * Common values: access_denied, invalid_request, unauthorized_client, etc.
+     */
+    error?: string;
+    /**
+     * Human-readable error description (OAuth 2.0 standard)
+     */
+    error_description?: string;
+    /**
+     * URI with error information (OAuth 2.0 standard)
+     */
+    error_uri?: string;
+    /**
+     * Response type - 'json' returns JSON instead of redirect
+     */
+    response_type?: "json";
+    /**
+     * Granted scopes (provider-specific)
+     * May be sent by GitHub, Google, and other providers
+     */
+    scope?: string;
+    /**
+     * Google-specific: Index of the account selected by the user
+     */
+    authuser?: string;
+    /**
+     * Google-specific: Indicates which prompt was shown to the user
+     * Values: none, consent, select_account
+     */
+    prompt?: string;
+    /**
+     * Google-specific: Hosted domain of the user
+     */
+    hd?: string;
+    /**
+     * Session state or other provider-specific parameters
+     */
+    session_state?: string;
+    [key: string]: string | undefined;
+}

package/dist/schemas/CallbackRequest.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/schemas/InitiateRequest.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Query parameters for OAuth initiate request
+ */
+export default interface InitiateRequest {
+    /**
+     * Optional redirect URI to return to after OAuth flow completes
+     */
+    redirectUri?: string;
+    [key: string]: string | undefined;
+}

package/dist/schemas/InitiateRequest.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/utils/token-response-utils.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 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 declare function formatTokenResponse(token: string, user: any, redirectUrl?: string, responseType?: string): any;

package/dist/utils/token-response-utils.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatTokenResponse = void 0;
+/**
+ * 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
+ */
+function formatTokenResponse(token, user, redirectUrl, responseType) {
+    // 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,
+        },
+    };
+}
+exports.formatTokenResponse = formatTokenResponse;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@flink-app/oauth-plugin",
-    "version": "0.12.1-alpha.35",
+    "version": "0.12.1-alpha.37",
     "description": "Flink plugin for OAuth 2.0 authentication with GitHub and Google providers",
     "scripts": {
         "test": "node --preserve-symlinks -r ts-node/register -- node_modules/jasmine/bin/jasmine --config=./spec/support/jasmine.json",
@@ -34,5 +34,5 @@
         "tsc-watch": "^4.2.9",
         "typescript": "5.4.5"
     },
-    "gitHead": "f8e8c6565a9ca1dd3e5fdb4c2a791c99ae3ba51a"
+    "gitHead": "58f5ef1c6307ebda4b3ad6e75c29fd56345a2a54"
 }

package/spec/OAuthHandlers.spec.ts

@@ -12,135 +12,134 @@
  * critical OAuth flow scenarios.
  */
 
-import { FlinkApp } from '@flink-app/flink';
-import * as http from '@flink-app/test-utils';
-
-describe('OAuth Handlers', () => {
-  let app: FlinkApp<any>;
-  let testSessionId: string;
-  let testState: string;
-
-  beforeAll(async () => {
-    // Note: This is a placeholder test structure
-    // The actual FlinkApp setup with oauth plugin will be completed
-    // in Task Group 5 when the plugin is fully implemented
-
-    // For now, we're creating the test structure to validate
-    // the handler logic once the plugin integration is complete
-  });
-
-  afterAll(async () => {
-    if (app) {
-      await app.stop();
-    }
-  });
-
-  describe('InitiateOAuth Handler', () => {
-    it('should generate state, create session, and redirect to provider', async () => {
-      // Test that initiate handler:
-      // 1. Validates provider is configured
-      // 2. Generates cryptographically secure state parameter
-      // 3. Creates OAuth session with state
-      // 4. Returns 302 redirect to provider authorization URL
-
-      // This test will be implemented once plugin setup is complete
-      expect(true).toBe(true); // Placeholder
+import { FlinkApp } from "@flink-app/flink";
+import * as http from "@flink-app/test-utils";
+
+describe("OAuth Handlers", () => {
+    let app: FlinkApp<any>;
+    let testSessionId: string;
+    let testState: string;
+
+    beforeAll(async () => {
+        // Note: This is a placeholder test structure
+        // The actual FlinkApp setup with oauth plugin will be completed
+        // in Task Group 5 when the plugin is fully implemented
+        // For now, we're creating the test structure to validate
+        // the handler logic once the plugin integration is complete
     });
 
-    it('should reject unsupported provider', async () => {
-      // Test that initiate handler returns 400 for invalid provider
-
-      // This test will be implemented once plugin setup is complete
-      expect(true).toBe(true); // Placeholder
-    });
-  });
-
-  describe('CallbackOAuth Handler', () => {
-    it('should validate state, exchange code, and call onAuthSuccess with context', async () => {
-      // Test that callback handler:
-      // 1. Validates state parameter matches session
-      // 2. Exchanges authorization code for access token
-      // 3. Fetches user profile from provider
-      // 4. Calls onAuthSuccess callback with profile and context
-      // 5. Receives JWT token from callback
-
-      // This test will be implemented once plugin setup is complete
-      expect(true).toBe(true); // Placeholder
-    });
-
-    it('should receive JWT token from callback and return to client', async () => {
-      // Test that callback handler:
-      // 1. Receives JWT token from onAuthSuccess callback
-      // 2. Returns token in appropriate format (redirect by default)
-
-      // This test will be implemented once plugin setup is complete
-      expect(true).toBe(true); // Placeholder
+    afterAll(async () => {
+        if (app) {
+            await app.stop();
+        }
     });
 
-    it('should support response_type=json query parameter', async () => {
-      // Test that callback handler:
-      // 1. Detects response_type=json in query parameters
-      // 2. Returns JSON response with user and token
-      // 3. Does not redirect when response_type=json
+    describe("InitiateOAuth Handler", () => {
+        it("should generate state, create session, and redirect to provider", async () => {
+            // Test that initiate handler:
+            // 1. Validates provider is configured
+            // 2. Generates cryptographically secure state parameter
+            // 3. Creates OAuth session with state
+            // 4. Returns 302 redirect to provider authorization URL
 
-      // This test will be implemented once plugin setup is complete
-      expect(true).toBe(true); // Placeholder
-    });
+            // This test will be implemented once plugin setup is complete
+            expect(true).toBe(true); // Placeholder
+        });
 
-    it('should reject callback with invalid state parameter', async () => {
-      // Test that callback handler:
-      // 1. Detects state mismatch
-      // 2. Returns 400 error
-      // 3. Prevents CSRF attacks
+        it("should reject unsupported provider", async () => {
+            // Test that initiate handler returns 400 for invalid provider
 
-      // This test will be implemented once plugin setup is complete
-      expect(true).toBe(true); // Placeholder
+            // This test will be implemented once plugin setup is complete
+            expect(true).toBe(true); // Placeholder
+        });
     });
 
-    it('should reject callback with missing code parameter', async () => {
-      // Test that callback handler:
-      // 1. Detects missing authorization code
-      // 2. Returns 400 error with clear message
-
-      // This test will be implemented once plugin setup is complete
-      expect(true).toBe(true); // Placeholder
+    describe("CallbackOAuth Handler", () => {
+        it("should validate state, exchange code, and call onAuthSuccess with context", async () => {
+            // Test that callback handler:
+            // 1. Validates state parameter matches session
+            // 2. Exchanges authorization code for access token
+            // 3. Fetches user profile from provider
+            // 4. Calls onAuthSuccess callback with profile and context
+            // 5. Receives JWT token from callback
+
+            // This test will be implemented once plugin setup is complete
+            expect(true).toBe(true); // Placeholder
+        });
+
+        it("should receive JWT token from callback and return to client", async () => {
+            // Test that callback handler:
+            // 1. Receives JWT token from onAuthSuccess callback
+            // 2. Returns token in appropriate format (redirect by default)
+
+            // This test will be implemented once plugin setup is complete
+            expect(true).toBe(true); // Placeholder
+        });
+
+        it("should support response_type=json query parameter", async () => {
+            // Test that callback handler:
+            // 1. Detects response_type=json in query parameters
+            // 2. Returns JSON response with user and token
+            // 3. Does not redirect when response_type=json
+
+            // This test will be implemented once plugin setup is complete
+            expect(true).toBe(true); // Placeholder
+        });
+
+        it("should reject callback with invalid state parameter", async () => {
+            // Test that callback handler:
+            // 1. Detects state mismatch
+            // 2. Returns 400 error
+            // 3. Prevents CSRF attacks
+
+            // This test will be implemented once plugin setup is complete
+            expect(true).toBe(true); // Placeholder
+        });
+
+        it("should reject callback with missing code parameter", async () => {
+            // Test that callback handler:
+            // 1. Detects missing authorization code
+            // 2. Returns 400 error with clear message
+
+            // This test will be implemented once plugin setup is complete
+            expect(true).toBe(true); // Placeholder
+        });
+
+        it("should handle OAuth provider error (access_denied)", async () => {
+            // Test that callback handler:
+            // 1. Detects error parameter from provider
+            // 2. Maps error to user-friendly message
+            // 3. Calls onAuthError callback if provided
+
+            // This test will be implemented once plugin setup is complete
+            expect(true).toBe(true); // Placeholder
+        });
+
+        it("should handle expired or missing session", async () => {
+            // Test that callback handler:
+            // 1. Detects missing session for state
+            // 2. Returns appropriate error message
+            // 3. Suggests user try logging in again
+
+            // This test will be implemented once plugin setup is complete
+            expect(true).toBe(true); // Placeholder
+        });
+
+        it("should handle JWT generation failure gracefully", async () => {
+            // Test that callback handler:
+            // 1. Catches errors from onAuthSuccess callback
+            // 2. Logs error securely
+            // 3. Calls onAuthError callback if provided
+            // 4. Returns user-friendly error message
+
+            // This test will be implemented once plugin setup is complete
+            expect(true).toBe(true); // Placeholder
+        });
     });
 
-    it('should handle OAuth provider error (access_denied)', async () => {
-      // Test that callback handler:
-      // 1. Detects error parameter from provider
-      // 2. Maps error to user-friendly message
-      // 3. Calls onAuthError callback if provided
-
-      // This test will be implemented once plugin setup is complete
-      expect(true).toBe(true); // Placeholder
+    describe("OAuth Flow End-to-End", () => {
+        // Note: Full end-to-end tests with mock OAuth provider responses
+        // will be added in Task Group 7 by the testing-engineer
+        // These placeholder tests establish the test structure
     });
-
-    it('should handle expired or missing session', async () => {
-      // Test that callback handler:
-      // 1. Detects missing session for state
-      // 2. Returns appropriate error message
-      // 3. Suggests user try logging in again
-
-      // This test will be implemented once plugin setup is complete
-      expect(true).toBe(true); // Placeholder
-    });
-
-    it('should handle JWT generation failure gracefully', async () => {
-      // Test that callback handler:
-      // 1. Catches errors from onAuthSuccess callback
-      // 2. Logs error securely
-      // 3. Calls onAuthError callback if provided
-      // 4. Returns user-friendly error message
-
-      // This test will be implemented once plugin setup is complete
-      expect(true).toBe(true); // Placeholder
-    });
-  });
-
-  describe('OAuth Flow End-to-End', () => {
-    // Note: Full end-to-end tests with mock OAuth provider responses
-    // will be added in Task Group 7 by the testing-engineer
-    // These placeholder tests establish the test structure
-  });
 });

package/src/OAuthPlugin.ts

@@ -7,6 +7,8 @@ import OAuthSessionRepo from "./repos/OAuthSessionRepo";
 import OAuthConnectionRepo from "./repos/OAuthConnectionRepo";
 import { encryptToken, decryptToken, validateEncryptionSecret } from "./utils/encryption-utils";
 import OAuthConnection from "./schemas/OAuthConnection";
+import * as InitiateOAuth from "./handlers/InitiateOAuth";
+import * as CallbackOAuth from "./handlers/CallbackOAuth";
 
 /**
  * OAuth Plugin Factory Function
@@ -156,10 +158,12 @@ export function oauthPlugin(options: OAuthPluginOptions): FlinkPlugin {
 
             log.info(`OAuth Plugin: Created TTL index on ${sessionsCollectionName} with ${sessionTTL}s expiration`);
 
-            // Register handlers for each configured provider
-            // Note: Handlers will be registered dynamically
-            // This requires handlers to be imported, but we'll handle that in the handler files
-            // For now, we'll skip handler registration and implement it when handlers are ready
+            // Register OAuth handlers
+            // Only register handlers if registerRoutes is enabled (default: true)
+            if (options.registerRoutes !== false) {
+                flinkApp.addHandler(InitiateOAuth);
+                flinkApp.addHandler(CallbackOAuth);
+            }
 
             log.info(`OAuth Plugin initialized with providers: ${configuredProviders.join(", ")}`);
         } catch (error) {

package/src/OAuthPluginOptions.ts

@@ -119,4 +119,11 @@ export interface OAuthPluginOptions {
      * Recommended: Use a dedicated encryption key from environment variables
      */
     encryptionKey?: string;
+
+    /**
+     * Whether to register OAuth routes automatically
+     * If false, you must manually handle OAuth flow
+     * Default: true
+     */
+    registerRoutes?: boolean;
 }

package/src/handlers/CallbackOAuth.ts

@@ -12,7 +12,7 @@
  * Route: GET /oauth/:provider/callback?code=...&state=...&response_type=json
  */
 
-import { GetHandler, RouteProps, badRequest, internalServerError, log } from "@flink-app/flink";
+import { GetHandler, HttpMethod, RouteProps, badRequest, internalServerError, log } from "@flink-app/flink";
 import CallbackRequest from "../schemas/CallbackRequest";
 import { validateState } from "../utils/state-utils";
 import { getProvider } from "../providers/ProviderRegistry";
@@ -35,6 +35,7 @@ interface PathParams {
  */
 export const Route: RouteProps = {
     path: "/oauth/:provider/callback",
+    method: HttpMethod.get,
 };
 
 /**

package/src/handlers/InitiateOAuth.ts

@@ -11,7 +11,7 @@
  * Route: GET /oauth/:provider/initiate?redirectUri={optional_redirect_url}
  */
 
-import { GetHandler, RouteProps, badRequest, internalServerError } from "@flink-app/flink";
+import { GetHandler, HttpMethod, RouteProps, badRequest, internalServerError } from "@flink-app/flink";
 import InitiateRequest from "../schemas/InitiateRequest";
 import { generateState, generateSessionId } from "../utils/state-utils";
 import { getProvider } from "../providers/ProviderRegistry";
@@ -32,6 +32,7 @@ interface PathParams {
  */
 export const Route: RouteProps = {
     path: "/oauth/:provider/initiate",
+    method: HttpMethod.get,
 };
 
 /**