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

package/dist/handlers/InstallationCallback.js

@@ -0,0 +1,248 @@
+"use strict";
+/**
+ * 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=...
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Route = void 0;
+const flink_1 = require("@flink-app/flink");
+const error_utils_1 = require("../utils/error-utils");
+const state_utils_1 = require("../utils/state-utils");
+/**
+ * Route configuration
+ * Registered programmatically by the plugin if registerRoutes is enabled
+ */
+exports.Route = {
+    path: "/github-app/callback",
+    method: flink_1.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 }) => {
+    const { installation_id, setup_action, state, code } = req.query;
+    try {
+        // Validate required parameters
+        if (!installation_id || !setup_action || !state) {
+            return (0, flink_1.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 = (0, error_utils_1.createGitHubAppError)(error_utils_1.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 (0, flink_1.badRequest)(error.message);
+        }
+        // Validate state parameter using constant-time comparison (CSRF protection)
+        if (!(0, state_utils_1.validateState)(state, session.state)) {
+            const error = (0, error_utils_1.createGitHubAppError)(error_utils_1.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 (0, flink_1.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) {
+            flink_1.log.error("GitHub App onInstallationSuccess callback failed:", error);
+            const callbackError = (0, error_utils_1.createGitHubAppError)(error_utils_1.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 (0, flink_1.internalServerError)("Installation failed. Please try again.");
+        }
+        // Extract userId and redirectUrl from callback result
+        const { userId, redirectUrl } = callbackResult;
+        if (!userId) {
+            return (0, flink_1.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) => ({
+                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) {
+        flink_1.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) {
+                flink_1.log.error("onInstallationError callback failed:", callbackError);
+            }
+        }
+        return (0, flink_1.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, jwt, baseUrl = "https://api.github.com") {
+    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, jwt, baseUrl = "https://api.github.com") {
+    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 = 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 = await reposResponse.json();
+    return data.repositories || [];
+}
+exports.default = InstallationCallback;

package/dist/handlers/UninstallHandler.d.ts

@@ -0,0 +1,37 @@
+/**
+ * GitHub App Uninstall Handler
+ *
+ * Manually uninstalls a GitHub App installation by:
+ * 1. Extracting userId from request (app-defined authentication)
+ * 2. Verifying user owns the installation
+ * 3. Deleting installation from database
+ * 4. Clearing cached installation token
+ * 5. Returning 204 No Content
+ *
+ * Route: DELETE /github-app/installation/:installationId
+ *
+ * Note: This is an optional handler for manual uninstallation.
+ * Apps should also handle the 'installation.deleted' webhook event
+ * for automatic cleanup when users uninstall via GitHub UI.
+ */
+import { Handler, RouteProps } from "@flink-app/flink";
+/**
+ * Path parameters for the handler
+ */
+interface PathParams {
+    installationId: string;
+    [key: string]: string;
+}
+/**
+ * Route configuration
+ * Registered programmatically by the plugin if registerRoutes is enabled
+ */
+export declare const Route: RouteProps;
+/**
+ * GitHub App Uninstall Handler
+ *
+ * Allows users to manually uninstall a GitHub App from their account.
+ * The application must provide userId extraction logic (via JWT, session, etc.)
+ */
+declare const UninstallHandler: Handler<any, any, any, PathParams>;
+export default UninstallHandler;

package/dist/handlers/UninstallHandler.js

@@ -0,0 +1,153 @@
+"use strict";
+/**
+ * GitHub App Uninstall Handler
+ *
+ * Manually uninstalls a GitHub App installation by:
+ * 1. Extracting userId from request (app-defined authentication)
+ * 2. Verifying user owns the installation
+ * 3. Deleting installation from database
+ * 4. Clearing cached installation token
+ * 5. Returning 204 No Content
+ *
+ * Route: DELETE /github-app/installation/:installationId
+ *
+ * Note: This is an optional handler for manual uninstallation.
+ * Apps should also handle the 'installation.deleted' webhook event
+ * for automatic cleanup when users uninstall via GitHub UI.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Route = void 0;
+const flink_1 = require("@flink-app/flink");
+/**
+ * Route configuration
+ * Registered programmatically by the plugin if registerRoutes is enabled
+ */
+exports.Route = {
+    path: "/github-app/installation/:installationId",
+    method: flink_1.HttpMethod.delete,
+};
+/**
+ * GitHub App Uninstall Handler
+ *
+ * Allows users to manually uninstall a GitHub App from their account.
+ * The application must provide userId extraction logic (via JWT, session, etc.)
+ */
+const UninstallHandler = async ({ ctx, req }) => {
+    try {
+        const { installationId } = req.params;
+        const installationIdNum = parseInt(installationId, 10);
+        if (isNaN(installationIdNum)) {
+            return {
+                status: 400,
+                data: { error: "Invalid installation ID" },
+            };
+        }
+        // Extract userId from request
+        // This is app-defined and can work with any authentication system
+        // Examples:
+        // - JWT Auth Plugin: ctx.auth?.tokenData?.userId
+        // - Session-based: req.session?.userId
+        // - Custom header: req.headers['x-user-id']
+        //
+        // For now, we'll look for userId in multiple common places
+        const userId = extractUserId(req, ctx);
+        if (!userId) {
+            return {
+                status: 401,
+                data: { error: "Authentication required" },
+            };
+        }
+        // Find the installation
+        const installation = await ctx.repos.githubInstallationRepo.findByInstallationId(installationIdNum);
+        if (!installation) {
+            return {
+                status: 404,
+                data: { error: "Installation not found" },
+            };
+        }
+        // Verify user owns the installation
+        if (installation.userId !== userId) {
+            flink_1.log.warn("User attempted to delete installation they don't own", {
+                userId,
+                installationId: installationIdNum,
+                ownerId: installation.userId,
+            });
+            return {
+                status: 403,
+                data: { error: "You do not have permission to delete this installation" },
+            };
+        }
+        // Delete installation from database
+        const deletedCount = await ctx.repos.githubInstallationRepo.deleteByInstallationId(installationIdNum);
+        if (deletedCount === 0) {
+            flink_1.log.error("Failed to delete installation from database", {
+                installationId: installationIdNum,
+            });
+            return {
+                status: 500,
+                data: { error: "Failed to delete installation" },
+            };
+        }
+        // Clear cached installation token
+        ctx.plugins.githubApp.authService.deleteInstallationToken(installationIdNum);
+        flink_1.log.info("GitHub App installation deleted", {
+            userId,
+            installationId: installationIdNum,
+        });
+        // Return 204 No Content
+        return {
+            status: 204,
+            data: {},
+        };
+    }
+    catch (error) {
+        flink_1.log.error("Error deleting GitHub App installation", {
+            error: error.message,
+        });
+        return {
+            status: 500,
+            data: { error: "Failed to delete installation" },
+        };
+    }
+};
+/**
+ * Extract userId from request
+ *
+ * This helper function attempts to extract userId from various common
+ * authentication patterns. Applications can customize this logic based
+ * on their authentication system.
+ *
+ * @param req - Express request object
+ * @param ctx - Flink context
+ * @returns userId if found, undefined otherwise
+ */
+function extractUserId(req, ctx) {
+    // Option 1: JWT Auth Plugin (if available)
+    if (ctx.auth?.tokenData?.userId) {
+        return ctx.auth.tokenData.userId;
+    }
+    // Option 2: Custom user property on request (set by custom middleware)
+    if (req.user?.id) {
+        return req.user.id;
+    }
+    if (req.user?.userId) {
+        return req.user.userId;
+    }
+    if (req.user?._id) {
+        return req.user._id;
+    }
+    // Option 3: Session-based authentication
+    if (req.session?.userId) {
+        return req.session.userId;
+    }
+    // Option 4: Custom header
+    if (req.headers["x-user-id"]) {
+        return req.headers["x-user-id"];
+    }
+    // Option 5: Query parameter (less secure, use with caution)
+    if (req.query?.user_id) {
+        return req.query.user_id;
+    }
+    return undefined;
+}
+exports.default = UninstallHandler;

package/dist/handlers/WebhookHandler.d.ts

@@ -0,0 +1,54 @@
+/**
+ * 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, RouteProps } 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 declare const Route: RouteProps;
+/**
+ * GitHub App Webhook Handler
+ *
+ * Validates webhook signatures and processes GitHub webhook events.
+ */
+declare const WebhookHandler: ({ ctx, req }: {
+    ctx: WebhookHandlerContext;
+    req: any;
+}) => Promise<{
+    status: number;
+    data: {
+        error: string;
+        received?: undefined;
+    };
+} | {
+    status: number;
+    data: {
+        received: boolean;
+        error?: undefined;
+    };
+} | {
+    status: number;
+    data: {
+        received: boolean;
+        error: string;
+    };
+}>;
+export default WebhookHandler;

package/dist/handlers/WebhookHandler.js

@@ -0,0 +1,157 @@
+"use strict";
+/**
+ * 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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Route = void 0;
+const flink_1 = require("@flink-app/flink");
+/**
+ * Route configuration
+ * Registered programmatically by the plugin if registerRoutes is enabled
+ */
+exports.Route = {
+    path: "/github-app/webhook",
+    method: flink_1.HttpMethod.post,
+};
+/**
+ * GitHub App Webhook Handler
+ *
+ * Validates webhook signatures and processes GitHub webhook events.
+ */
+const WebhookHandler = async ({ ctx, req }) => {
+    try {
+        // Extract headers
+        const signature = req.headers["x-hub-signature-256"];
+        const event = req.headers["x-github-event"];
+        const deliveryId = req.headers["x-github-delivery"];
+        // 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) {
+            flink_1.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) {
+            flink_1.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);
+        flink_1.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) {
+                // Don't fail the webhook if logging fails
+                flink_1.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) {
+                // Log the error but still return 200 to GitHub to prevent retries
+                flink_1.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) {
+        flink_1.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" },
+        };
+    }
+};
+exports.default = WebhookHandler;

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * GitHub App Plugin for Flink Framework
+ *
+ * Provides GitHub App integration with:
+ * - Installation management
+ * - JWT-based authentication
+ * - Webhook handling with signature validation
+ * - API client wrapper
+ */
+export { githubAppPlugin } from './GitHubAppPlugin';
+export type { GitHubAppPluginOptions, InstallationSuccessParams, InstallationSuccessResponse, InstallationErrorParams, InstallationErrorResponse, WebhookEventParams } from './GitHubAppPluginOptions';
+export type { GitHubAppPluginContext } from './GitHubAppPluginContext';
+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';
+export { GitHubAPIClient, type Repository, type Content, type Issue, type CreateIssueParams } from './services/GitHubAPIClient';
+export { GitHubAuthService } from './services/GitHubAuthService';
+export { GitHubAppErrorCodes } from './utils/error-utils';