@flink-app/github-app-plugin 0.12.1-alpha.38 → 0.12.1-alpha.40

package/src/services/InstallationService.ts

@@ -0,0 +1,302 @@
+/**
+ * Installation Service
+ *
+ * Handles GitHub App installation completion flow including:
+ * - State validation (CSRF protection)
+ * - Fetching installation details from GitHub API
+ * - Storing installation in database
+ */
+
+import { log } from "@flink-app/flink";
+import { GitHubAuthService } from "./GitHubAuthService";
+import GitHubAppSessionRepo from "../repos/GitHubAppSessionRepo";
+import GitHubInstallationRepo from "../repos/GitHubInstallationRepo";
+import GitHubInstallation from "../schemas/GitHubInstallation";
+import { createGitHubAppError, GitHubAppErrorCodes, handleGitHubAPIError } from "../utils/error-utils";
+import { validateState } from "../utils/state-utils";
+
+/**
+ * Installation details from GitHub API
+ */
+interface GitHubInstallationDetails {
+    id: number;
+    account: {
+        id: number;
+        login: string;
+        type: "User" | "Organization";
+        avatar_url?: string;
+    };
+    permissions?: Record<string, string>;
+    events?: string[];
+}
+
+/**
+ * Repository details from GitHub API
+ */
+interface GitHubRepository {
+    id: number;
+    name: string;
+    full_name: string;
+    private: boolean;
+}
+
+/**
+ * Result of completing installation
+ */
+export interface CompleteInstallationResult {
+    success: boolean;
+    installation?: GitHubInstallation;
+    error?: {
+        code: string;
+        message: string;
+        details?: any;
+    };
+}
+
+/**
+ * Installation Service
+ *
+ * Provides methods for completing GitHub App installation flow.
+ * Host applications call these methods from their own handlers with
+ * their own authentication and authorization logic.
+ */
+export class InstallationService {
+    constructor(
+        private authService: GitHubAuthService,
+        private sessionRepo: GitHubAppSessionRepo,
+        private installationRepo: GitHubInstallationRepo,
+        private baseUrl: string = "https://api.github.com"
+    ) {}
+
+    /**
+     * Complete GitHub App installation
+     *
+     * This method handles all the boilerplate of:
+     * 1. Validating the state parameter (CSRF protection)
+     * 2. Fetching installation details from GitHub API
+     * 3. Storing the installation in database
+     *
+     * The host application should:
+     * - Check if user is authenticated
+     * - Parse query parameters from the callback URL
+     * - Call this method with userId
+     * - Handle the response and redirect
+     *
+     * @param params - Installation completion parameters
+     * @param params.installationId - GitHub installation ID from query params
+     * @param params.state - State parameter from query params (CSRF protection)
+     * @param params.userId - Application user ID (from auth system)
+     * @returns Result with installation details or error
+     *
+     * @example
+     * ```typescript
+     * // In your custom handler
+     * export default async function GitHubCallback({ ctx, req }: GetHandlerParams) {
+     *   // 1. Check authentication (your way)
+     *   if (!ctx.auth?.tokenData?.userId) {
+     *     return unauthorized('Please log in first');
+     *   }
+     *
+     *   // 2. Parse query params
+     *   const { installation_id, state } = req.query;
+     *
+     *   // 3. Complete installation
+     *   const result = await ctx.plugins.githubApp.completeInstallation({
+     *     installationId: parseInt(installation_id),
+     *     state,
+     *     userId: ctx.auth.tokenData.userId
+     *   });
+     *
+     *   // 4. Handle response (your way)
+     *   if (!result.success) {
+     *     return redirect(`/error?code=${result.error.code}`);
+     *   }
+     *
+     *   return redirect('/dashboard/github');
+     * }
+     * ```
+     */
+    async completeInstallation(params: {
+        installationId: number;
+        state: string;
+        userId: string;
+    }): Promise<CompleteInstallationResult> {
+        const { installationId, state, userId } = params;
+
+        try {
+            // 1. Find session by state
+            const session = await this.sessionRepo.getOne({ state });
+
+            if (!session) {
+                return {
+                    success: false,
+                    error: {
+                        code: GitHubAppErrorCodes.SESSION_EXPIRED,
+                        message: "Installation session not found or expired. Please try again.",
+                        details: { state: state.substring(0, 10) + "..." },
+                    },
+                };
+            }
+
+            // 2. Validate state parameter (CSRF protection)
+            if (!validateState(state, session.state)) {
+                return {
+                    success: false,
+                    error: {
+                        code: GitHubAppErrorCodes.INVALID_STATE,
+                        message: "Invalid state parameter. Possible CSRF attack detected.",
+                        details: { providedState: state.substring(0, 10) + "..." },
+                    },
+                };
+            }
+
+            // 3. Delete session immediately after validation (one-time use)
+            await this.sessionRepo.deleteBySessionId(session.sessionId);
+
+            // 4. Generate GitHub App JWT
+            const jwt = this.authService.generateAppJWT();
+
+            // 5. Fetch installation details from GitHub API
+            const installationDetails = await this.fetchInstallationDetails(installationId, jwt);
+
+            // 6. Fetch repositories accessible by this installation
+            const repositories = await this.fetchInstallationRepositories(installationId, jwt);
+
+            // 7. Store installation in database
+            const installation = await this.installationRepo.create({
+                userId,
+                installationId,
+                accountId: installationDetails.account.id,
+                accountLogin: installationDetails.account.login,
+                accountType: installationDetails.account.type,
+                avatarUrl: installationDetails.account.avatar_url,
+                repositories: repositories.map((repo) => ({
+                    id: repo.id,
+                    name: repo.name,
+                    fullName: repo.full_name,
+                    private: repo.private,
+                })),
+                permissions: installationDetails.permissions || {},
+                events: installationDetails.events || [],
+                createdAt: new Date(),
+                updatedAt: new Date(),
+            });
+
+            log.info("GitHub App installation completed", {
+                userId,
+                installationId,
+                accountLogin: installationDetails.account.login,
+                repositoryCount: repositories.length,
+            });
+
+            return {
+                success: true,
+                installation,
+            };
+        } catch (error: any) {
+            log.error("GitHub App installation completion failed", {
+                userId,
+                installationId,
+                error: error.message,
+            });
+
+            return {
+                success: false,
+                error: {
+                    code: error.code || GitHubAppErrorCodes.SERVER_ERROR,
+                    message: error.message || "Installation completion failed. Please try again.",
+                    details: error.details,
+                },
+            };
+        }
+    }
+
+    /**
+     * Fetch installation details from GitHub API
+     *
+     * @param installationId - GitHub installation ID
+     * @param jwt - GitHub App JWT
+     * @returns Installation details
+     * @private
+     */
+    private async fetchInstallationDetails(installationId: number, jwt: string): Promise<GitHubInstallationDetails> {
+        const url = `${this.baseUrl}/app/installations/${installationId}`;
+
+        const response = await fetch(url, {
+            method: "GET",
+            headers: {
+                Authorization: `Bearer ${jwt}`,
+                Accept: "application/vnd.github+json",
+                "User-Agent": "Flink-GitHub-App-Plugin",
+            },
+        });
+
+        if (!response.ok) {
+            const errorBody = await response.text();
+            throw createGitHubAppError(
+                GitHubAppErrorCodes.SERVER_ERROR,
+                `Failed to fetch installation details: ${response.statusText}`,
+                { status: response.status, body: errorBody }
+            );
+        }
+
+        return (await response.json()) as GitHubInstallationDetails;
+    }
+
+    /**
+     * Fetch repositories accessible by installation
+     *
+     * @param installationId - GitHub installation ID
+     * @param jwt - GitHub App JWT
+     * @returns Array of repositories
+     * @private
+     */
+    private async fetchInstallationRepositories(installationId: number, jwt: string): Promise<GitHubRepository[]> {
+        const url = `${this.baseUrl}/installation/repositories`;
+
+        // First get an installation token
+        const tokenUrl = `${this.baseUrl}/app/installations/${installationId}/access_tokens`;
+        const tokenResponse = await fetch(tokenUrl, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${jwt}`,
+                Accept: "application/vnd.github+json",
+                "User-Agent": "Flink-GitHub-App-Plugin",
+            },
+        });
+
+        if (!tokenResponse.ok) {
+            const errorBody = await tokenResponse.text();
+            throw createGitHubAppError(
+                GitHubAppErrorCodes.TOKEN_EXCHANGE_FAILED,
+                `Failed to get installation token: ${tokenResponse.statusText}`,
+                { status: tokenResponse.status, body: errorBody }
+            );
+        }
+
+        const tokenData: any = await tokenResponse.json();
+        const token = tokenData.token;
+
+        // Now fetch repositories with the installation token
+        const reposResponse = await fetch(url, {
+            method: "GET",
+            headers: {
+                Authorization: `Bearer ${token}`,
+                Accept: "application/vnd.github+json",
+                "User-Agent": "Flink-GitHub-App-Plugin",
+            },
+        });
+
+        if (!reposResponse.ok) {
+            const errorBody = await reposResponse.text();
+            throw createGitHubAppError(
+                GitHubAppErrorCodes.SERVER_ERROR,
+                `Failed to fetch repositories: ${reposResponse.statusText}`,
+                { status: reposResponse.status, body: errorBody }
+            );
+        }
+
+        const data: any = await reposResponse.json();
+        return data.repositories || [];
+    }
+}

package/src/handlers/InstallationCallback.ts

@@ -1,292 +0,0 @@
-/**
- * GitHub App Installation Callback Handler
- *
- * Handles the callback from GitHub after app installation by:
- * 1. Validating the state parameter to prevent CSRF attacks
- * 2. Fetching installation details from GitHub API
- * 3. Calling the onInstallationSuccess callback to link installation to user
- * 4. Storing the installation in the database
- * 5. Redirecting to the application
- *
- * Route: GET /github-app/callback?installation_id=...&setup_action=...&state=...
- */
-
-import { badRequest, HttpMethod, internalServerError, log, RouteProps } from "@flink-app/flink";
-import { createGitHubAppError, GitHubAppErrorCodes } from "../utils/error-utils";
-import { validateState } from "../utils/state-utils";
-
-/**
- * Context with GitHub App Plugin
- *
- * Note: Using 'any' for simplicity. In a real-world scenario, you'd want to properly
- * type the context with both FlinkContext and GitHubAppPluginContext including the repos.
- */
-type InstallationCallbackContext = any;
-
-/**
- * Route configuration
- * Registered programmatically by the plugin if registerRoutes is enabled
- */
-export const Route: RouteProps = {
-    path: "/github-app/callback",
-    method: HttpMethod.get,
-};
-
-/**
- * GitHub App Installation Callback Handler
- *
- * Completes the installation flow by validating state, fetching installation
- * details, calling the app's callback, and storing the installation.
- */
-const InstallationCallback = async ({ ctx, req }: { ctx: InstallationCallbackContext; req: any }) => {
-    const { installation_id, setup_action, state, code } = req.query;
-
-    try {
-        // Validate required parameters
-        if (!installation_id || !setup_action || !state) {
-            return badRequest("Missing required parameters: installation_id, setup_action, or state");
-        }
-
-        // Find installation session by state
-        const session = await ctx.repos.githubAppSessionRepo.getOne({ state });
-
-        if (!session) {
-            const error = createGitHubAppError(GitHubAppErrorCodes.SESSION_EXPIRED, "Installation session not found or expired. Please try again.", {
-                state: state.substring(0, 10) + "...",
-            });
-
-            // Call onInstallationError callback if provided
-            const { options } = ctx.plugins.githubApp;
-            if (options.onInstallationError) {
-                const errorResult = await options.onInstallationError({ error, installationId: installation_id });
-                if (errorResult.redirectUrl) {
-                    return {
-                        status: 302,
-                        headers: { Location: errorResult.redirectUrl },
-                        data: {},
-                    };
-                }
-            }
-
-            return badRequest(error.message);
-        }
-
-        // Validate state parameter using constant-time comparison (CSRF protection)
-        if (!validateState(state, session.state)) {
-            const error = createGitHubAppError(GitHubAppErrorCodes.INVALID_STATE, "Invalid state parameter. Possible CSRF attack detected.", {
-                providedState: state.substring(0, 10) + "...",
-            });
-
-            // Call onInstallationError callback if provided
-            const { options } = ctx.plugins.githubApp;
-            if (options.onInstallationError) {
-                const errorResult = await options.onInstallationError({ error, installationId: installation_id });
-                if (errorResult.redirectUrl) {
-                    return {
-                        status: 302,
-                        headers: { Location: errorResult.redirectUrl },
-                        data: {},
-                    };
-                }
-            }
-
-            return badRequest(error.message);
-        }
-
-        // Delete session immediately after validation (one-time use)
-        await ctx.repos.githubAppSessionRepo.deleteBySessionId(session.sessionId);
-
-        // Get plugin options and auth service
-        const { options, authService } = ctx.plugins.githubApp;
-
-        // Generate GitHub App JWT
-        const jwt = authService.generateAppJWT();
-
-        // Fetch installation details from GitHub API
-        const installationIdNum = parseInt(installation_id, 10);
-        const installationDetails = await fetchInstallationDetails(installationIdNum, jwt, options.baseUrl);
-
-        // Fetch repositories accessible by this installation
-        const repositories = await fetchInstallationRepositories(installationIdNum, jwt, options.baseUrl);
-
-        // Call onInstallationSuccess callback to get userId and redirect URL
-        let callbackResult;
-        try {
-            callbackResult = await options.onInstallationSuccess(
-                {
-                    installationId: installationIdNum,
-                    setupAction: setup_action,
-                    account: installationDetails.account,
-                    repositories: repositories,
-                    permissions: installationDetails.permissions || {},
-                    events: installationDetails.events || [],
-                },
-                ctx
-            );
-        } catch (error: any) {
-            log.error("GitHub App onInstallationSuccess callback failed:", error);
-
-            const callbackError = createGitHubAppError(GitHubAppErrorCodes.SERVER_ERROR, "Failed to complete installation. Please try again.", {
-                originalError: error.message,
-            });
-
-            // Call onInstallationError callback if provided
-            if (options.onInstallationError) {
-                const errorResult = await options.onInstallationError({
-                    error: callbackError,
-                    installationId: installation_id,
-                });
-                if (errorResult.redirectUrl) {
-                    return {
-                        status: 302,
-                        headers: { Location: errorResult.redirectUrl },
-                        data: {},
-                    };
-                }
-            }
-
-            return internalServerError("Installation failed. Please try again.");
-        }
-
-        // Extract userId and redirectUrl from callback result
-        const { userId, redirectUrl } = callbackResult;
-
-        if (!userId) {
-            return badRequest("onInstallationSuccess callback must return userId");
-        }
-
-        // Store installation in database
-        await ctx.repos.githubInstallationRepo.create({
-            userId,
-            installationId: installationIdNum,
-            accountId: installationDetails.account.id,
-            accountLogin: installationDetails.account.login,
-            accountType: installationDetails.account.type,
-            avatarUrl: installationDetails.account.avatar_url,
-            repositories: repositories.map((repo: any) => ({
-                id: repo.id,
-                name: repo.name,
-                fullName: repo.full_name,
-                private: repo.private,
-            })),
-            permissions: installationDetails.permissions || {},
-            events: installationDetails.events || [],
-            createdAt: new Date(),
-            updatedAt: new Date(),
-        });
-
-        // Redirect to app using callback's redirectUrl or default to root
-        const finalRedirectUrl = redirectUrl || "/";
-
-        return {
-            status: 302,
-            headers: {
-                Location: finalRedirectUrl,
-            },
-            data: {},
-        };
-    } catch (error: any) {
-        log.error("GitHub App installation callback error:", error);
-
-        // Call onInstallationError callback if provided
-        const { options } = ctx.plugins.githubApp;
-        if (options.onInstallationError) {
-            try {
-                const errorResult = await options.onInstallationError({
-                    error: error,
-                    installationId: installation_id,
-                });
-                if (errorResult.redirectUrl) {
-                    return {
-                        status: 302,
-                        headers: { Location: errorResult.redirectUrl },
-                        data: {},
-                    };
-                }
-            } catch (callbackError) {
-                log.error("onInstallationError callback failed:", callbackError);
-            }
-        }
-
-        return internalServerError(error.message || "Installation callback failed. Please try again.");
-    }
-};
-
-/**
- * Fetch installation details from GitHub API
- *
- * @param installationId - GitHub installation ID
- * @param jwt - GitHub App JWT
- * @param baseUrl - GitHub API base URL
- * @returns Installation details
- */
-async function fetchInstallationDetails(installationId: number, jwt: string, baseUrl: string = "https://api.github.com"): Promise<any> {
-    const url = `${baseUrl}/app/installations/${installationId}`;
-
-    const response = await fetch(url, {
-        method: "GET",
-        headers: {
-            Authorization: `Bearer ${jwt}`,
-            Accept: "application/vnd.github+json",
-            "User-Agent": "Flink-GitHub-App-Plugin",
-        },
-    });
-
-    if (!response.ok) {
-        const errorBody = await response.text();
-        throw new Error(`Failed to fetch installation details: ${response.statusText} - ${errorBody}`);
-    }
-
-    return await response.json();
-}
-
-/**
- * Fetch repositories accessible by installation
- *
- * @param installationId - GitHub installation ID
- * @param jwt - GitHub App JWT
- * @param baseUrl - GitHub API base URL
- * @returns Array of repositories
- */
-async function fetchInstallationRepositories(installationId: number, jwt: string, baseUrl: string = "https://api.github.com"): Promise<any[]> {
-    const url = `${baseUrl}/installation/repositories`;
-
-    // First get an installation token
-    const tokenUrl = `${baseUrl}/app/installations/${installationId}/access_tokens`;
-    const tokenResponse = await fetch(tokenUrl, {
-        method: "POST",
-        headers: {
-            Authorization: `Bearer ${jwt}`,
-            Accept: "application/vnd.github+json",
-            "User-Agent": "Flink-GitHub-App-Plugin",
-        },
-    });
-
-    if (!tokenResponse.ok) {
-        const errorBody = await tokenResponse.text();
-        throw new Error(`Failed to get installation token: ${tokenResponse.statusText} - ${errorBody}`);
-    }
-
-    const tokenData: any = await tokenResponse.json();
-    const token = tokenData.token;
-
-    // Now fetch repositories with the installation token
-    const reposResponse = await fetch(url, {
-        method: "GET",
-        headers: {
-            Authorization: `Bearer ${token}`,
-            Accept: "application/vnd.github+json",
-            "User-Agent": "Flink-GitHub-App-Plugin",
-        },
-    });
-
-    if (!reposResponse.ok) {
-        const errorBody = await reposResponse.text();
-        throw new Error(`Failed to fetch repositories: ${reposResponse.statusText} - ${errorBody}`);
-    }
-
-    const data: any = await reposResponse.json();
-    return data.repositories || [];
-}
-
-export default InstallationCallback;

package/src/schemas/InstallationCallbackRequest.ts

@@ -1,10 +0,0 @@
-/**
- * Query parameters received from GitHub after app installation.
- */
-export default interface InstallationCallbackRequest {
-    installation_id: string;
-    setup_action: 'install' | 'update' | 'request';
-    state: string;
-    code?: string;
-    [key: string]: string | undefined;
-}