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

package/src/handlers/InstallationCallback.ts

@@ -0,0 +1,292 @@
+/**
+ * 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/handlers/WebhookHandler.ts

@@ -0,0 +1,179 @@
+/**
+ * GitHub App Webhook Handler
+ *
+ * Processes GitHub webhook events by:
+ * 1. Validating the webhook signature using HMAC-SHA256
+ * 2. Parsing the webhook payload
+ * 3. Optionally logging the event to the database
+ * 4. Calling the onWebhookEvent callback for processing
+ * 5. Returning 200 OK to GitHub
+ *
+ * Route: POST /github-app/webhook
+ */
+
+import { FlinkContext, HttpMethod, RouteProps, log } from "@flink-app/flink";
+import { GitHubAppPluginContext } from "../GitHubAppPluginContext";
+
+/**
+ * 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 WebhookHandlerContext = FlinkContext<GitHubAppPluginContext>;
+
+/**
+ * Route configuration
+ * Registered programmatically by the plugin if registerRoutes is enabled
+ */
+export const Route: RouteProps = {
+    path: "/github-app/webhook",
+    method: HttpMethod.post,
+};
+
+/**
+ * GitHub App Webhook Handler
+ *
+ * Validates webhook signatures and processes GitHub webhook events.
+ */
+const WebhookHandler = async ({ ctx, req }: { ctx: WebhookHandlerContext; req: any }) => {
+    try {
+        // Extract headers
+        const signature = req.headers["x-hub-signature-256"] as string;
+        const event = req.headers["x-github-event"] as string;
+        const deliveryId = req.headers["x-github-delivery"] as string;
+
+        // Get raw request body
+        // In Express, if you use express.json(), the raw body is lost
+        // We need to access the raw body for signature validation
+        const rawBody = typeof req.body === "string" ? req.body : JSON.stringify(req.body);
+
+        // Validate webhook signature using constant-time comparison
+        const { webhookValidator, options } = ctx.plugins.githubApp;
+
+        const isValid = webhookValidator.validateSignature(rawBody, signature);
+
+        if (!isValid) {
+            log.warn("GitHub webhook signature validation failed", {
+                event,
+                deliveryId,
+                hasSignature: !!signature,
+            });
+
+            return {
+                status: 401,
+                data: { error: "Invalid webhook signature" },
+            };
+        }
+
+        // Parse webhook payload
+        let payload;
+        try {
+            payload = webhookValidator.parsePayload(rawBody);
+        } catch (error: any) {
+            log.error("Failed to parse webhook payload", {
+                event,
+                deliveryId,
+                error: error.message,
+            });
+
+            return {
+                status: 400,
+                data: { error: "Invalid webhook payload" },
+            };
+        }
+
+        // Extract event data
+        const action = payload.action;
+        const installationId = webhookValidator.extractInstallationId(payload);
+
+        log.info("GitHub webhook received", {
+            event,
+            action,
+            installationId,
+            deliveryId,
+        });
+
+        // Optionally log webhook event to database
+        if (options.logWebhookEvents && ctx.repos.githubWebhookEventRepo) {
+            try {
+                await ctx.repos.githubWebhookEventRepo.create({
+                    installationId: installationId || 0,
+                    event,
+                    action,
+                    deliveryId,
+                    payload,
+                    processed: false,
+                    createdAt: new Date(),
+                });
+            } catch (error: any) {
+                // Don't fail the webhook if logging fails
+                log.error("Failed to log webhook event to database", {
+                    event,
+                    deliveryId,
+                    error: error.message,
+                });
+            }
+        }
+
+        // Call onWebhookEvent callback if provided
+        if (options.onWebhookEvent && installationId) {
+            try {
+                await options.onWebhookEvent(
+                    {
+                        event,
+                        action,
+                        payload,
+                        installationId,
+                        deliveryId,
+                    },
+                    ctx
+                );
+            } catch (error: any) {
+                // Log the error but still return 200 to GitHub to prevent retries
+                log.error("Error in onWebhookEvent callback", {
+                    event,
+                    action,
+                    installationId,
+                    deliveryId,
+                    error: error.message,
+                });
+
+                // Update webhook event log if enabled
+                if (options.logWebhookEvents && ctx.repos.githubWebhookEventRepo) {
+                    try {
+                        const webhookEvent = await ctx.repos.githubWebhookEventRepo.getOne({ deliveryId });
+                        if (webhookEvent && webhookEvent._id) {
+                            await ctx.repos.githubWebhookEventRepo.updateOne(webhookEvent._id, {
+                                processed: true,
+                                processedAt: new Date(),
+                                error: error.message,
+                            });
+                        }
+                    } catch (updateError) {
+                        // Ignore errors updating the log
+                    }
+                }
+            }
+        }
+
+        // Return 200 OK to GitHub to acknowledge receipt
+        return {
+            status: 200,
+            data: { received: true },
+        };
+    } catch (error: any) {
+        log.error("Unexpected error in webhook handler", {
+            error: error.message,
+        });
+
+        // Still return 200 to GitHub to prevent infinite retries
+        // The error is logged for debugging
+        return {
+            status: 200,
+            data: { received: true, error: "Internal processing error" },
+        };
+    }
+};
+
+export default WebhookHandler;

package/src/index.ts

@@ -0,0 +1,29 @@
+/**
+ * GitHub App Plugin for Flink Framework
+ *
+ * Provides GitHub App integration with:
+ * - Installation management
+ * - JWT-based authentication
+ * - Webhook handling with signature validation
+ * - API client wrapper
+ */
+
+// Plugin factory
+export { githubAppPlugin } from './GitHubAppPlugin';
+
+// Type exports
+export type { GitHubAppPluginOptions, InstallationSuccessParams, InstallationSuccessResponse, InstallationErrorParams, InstallationErrorResponse, WebhookEventParams } from './GitHubAppPluginOptions';
+export type { GitHubAppPluginContext } from './GitHubAppPluginContext';
+
+// Schema exports
+export type { default as GitHubInstallation } from './schemas/GitHubInstallation';
+export type { default as GitHubAppSession } from './schemas/GitHubAppSession';
+export type { default as WebhookEvent } from './schemas/WebhookEvent';
+export type { default as WebhookPayload } from './schemas/WebhookPayload';
+
+// Service exports (for advanced usage)
+export { GitHubAPIClient, type Repository, type Content, type Issue, type CreateIssueParams } from './services/GitHubAPIClient';
+export { GitHubAuthService } from './services/GitHubAuthService';
+
+// Error utilities
+export { GitHubAppErrorCodes } from './utils/error-utils';

package/src/repos/GitHubAppSessionRepo.ts

@@ -0,0 +1,36 @@
+import { FlinkRepo } from "@flink-app/flink";
+import { Db } from "mongodb";
+import GitHubAppSession from "../schemas/GitHubAppSession";
+
+/**
+ * Repository for managing temporary GitHub App installation sessions with TTL.
+ * Sessions are used during the installation flow to prevent CSRF attacks.
+ */
+class GitHubAppSessionRepo extends FlinkRepo<any, GitHubAppSession> {
+    constructor(ctx: any, db: Db, collectionName: string = "github_app_sessions") {
+        super(collectionName, db);
+        this.ctx = ctx;
+    }
+
+    /**
+     * Find a GitHub App session by its unique session ID.
+     * @param sessionId - The unique session identifier
+     * @returns The session if found, null otherwise
+     */
+    async findBySessionId(sessionId: string): Promise<GitHubAppSession | null> {
+        return this.getOne({ sessionId });
+    }
+
+    /**
+     * Delete a GitHub App session by its unique session ID.
+     * Used after the installation callback is processed to prevent session reuse.
+     * @param sessionId - The unique session identifier
+     * @returns The number of deleted sessions (0 or 1)
+     */
+    async deleteBySessionId(sessionId: string): Promise<number> {
+        const { deletedCount } = await this.collection.deleteOne({ sessionId });
+        return deletedCount || 0;
+    }
+}
+
+export default GitHubAppSessionRepo;

package/src/repos/GitHubInstallationRepo.ts

@@ -0,0 +1,95 @@
+import { FlinkRepo } from "@flink-app/flink";
+import { Db } from "mongodb";
+import GitHubInstallation from "../schemas/GitHubInstallation";
+
+/**
+ * Repository for managing GitHub App installations.
+ * Stores installation-to-user mappings and repository access information.
+ */
+class GitHubInstallationRepo extends FlinkRepo<any, GitHubInstallation> {
+    constructor(ctx: any, db: Db, collectionName: string = "github_installations") {
+        super(collectionName, db);
+        this.ctx = ctx;
+    }
+
+    /**
+     * Find an installation by user ID and installation ID.
+     * @param userId - The application user ID
+     * @param installationId - The GitHub installation ID
+     * @returns The installation if found, null otherwise
+     */
+    async findByUserAndInstallationId(userId: string, installationId: number): Promise<GitHubInstallation | null> {
+        return this.getOne({ userId, installationId });
+    }
+
+    /**
+     * Find all installations for a specific user.
+     * @param userId - The application user ID
+     * @returns Array of installations for the user
+     */
+    async findByUserId(userId: string): Promise<GitHubInstallation[]> {
+        return this.findAll({ userId });
+    }
+
+    /**
+     * Find an installation by its GitHub installation ID.
+     * @param installationId - The GitHub installation ID
+     * @returns The installation if found, null otherwise
+     */
+    async findByInstallationId(installationId: number): Promise<GitHubInstallation | null> {
+        return this.getOne({ installationId });
+    }
+
+    /**
+     * Update the repositories list for an installation.
+     * @param installationId - The GitHub installation ID
+     * @param repositories - The new repositories list
+     * @returns The updated installation
+     */
+    async updateRepositories(installationId: number, repositories: GitHubInstallation["repositories"]): Promise<GitHubInstallation | null> {
+        const installation = await this.getOne({ installationId });
+        if (!installation) {
+            return null;
+        }
+
+        const updated = await this.updateOne(installation._id!, {
+            repositories,
+            updatedAt: new Date(),
+        });
+
+        return updated;
+    }
+
+    /**
+     * Suspend an installation.
+     * @param installationId - The GitHub installation ID
+     * @param suspendedBy - Information about who suspended the installation
+     * @returns The updated installation
+     */
+    async suspend(installationId: number, suspendedBy: { id: number; login: string }): Promise<GitHubInstallation | null> {
+        const installation = await this.getOne({ installationId });
+        if (!installation) {
+            return null;
+        }
+
+        const updated = await this.updateOne(installation._id!, {
+            suspendedAt: new Date(),
+            suspendedBy,
+            updatedAt: new Date(),
+        });
+
+        return updated;
+    }
+
+    /**
+     * Delete an installation by its GitHub installation ID.
+     * @param installationId - The GitHub installation ID
+     * @returns The number of deleted installations (0 or 1)
+     */
+    async deleteByInstallationId(installationId: number): Promise<number> {
+        const { deletedCount } = await this.collection.deleteOne({ installationId });
+        return deletedCount || 0;
+    }
+}
+
+export default GitHubInstallationRepo;

package/src/repos/GitHubWebhookEventRepo.ts

@@ -0,0 +1,48 @@
+import { FlinkRepo } from "@flink-app/flink";
+import { Db } from "mongodb";
+import WebhookEvent from "../schemas/WebhookEvent";
+
+/**
+ * Repository for managing GitHub webhook events.
+ * Only used if logWebhookEvents config option is enabled.
+ * Provides webhook event logging for debugging and auditing.
+ */
+class GitHubWebhookEventRepo extends FlinkRepo<any, WebhookEvent> {
+    constructor(ctx: any, db: Db, collectionName: string = "github_webhook_events") {
+        super(collectionName, db);
+        this.ctx = ctx;
+    }
+
+    /**
+     * Find all unprocessed webhook events.
+     * @returns Array of unprocessed events
+     */
+    async findUnprocessed(): Promise<WebhookEvent[]> {
+        return this.findAll({ processed: false });
+    }
+
+    /**
+     * Mark a webhook event as processed.
+     * @param eventId - The webhook event ID
+     * @returns The updated event
+     */
+    async markProcessed(eventId: string): Promise<WebhookEvent | null> {
+        const updated = await this.updateOne(eventId, {
+            processed: true,
+            processedAt: new Date(),
+        });
+
+        return updated;
+    }
+
+    /**
+     * Find all webhook events for a specific installation.
+     * @param installationId - The GitHub installation ID
+     * @returns Array of webhook events for the installation
+     */
+    async findByInstallationId(installationId: number): Promise<WebhookEvent[]> {
+        return this.findAll({ installationId });
+    }
+}
+
+export default GitHubWebhookEventRepo;

package/src/schemas/GitHubAppSession.ts

@@ -0,0 +1,13 @@
+/**
+ * Temporary session storage for GitHub App installation flow.
+ * Used for CSRF protection via state parameter.
+ * Sessions automatically expire after TTL (default 10 minutes).
+ */
+export default interface GitHubAppSession {
+    _id?: string;
+    sessionId: string;
+    state: string;
+    userId?: string;
+    metadata?: Record<string, any>;
+    createdAt: Date;
+}