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

package/spec/services.spec.ts

@@ -0,0 +1,108 @@
+/**
+ * Services Test Suite
+ *
+ * Tests for GitHubAuthService, GitHubAPIClient, and WebhookValidator
+ */
+
+import { GitHubAuthService } from "../src/services/GitHubAuthService";
+import { GitHubAPIClient } from "../src/services/GitHubAPIClient";
+import { WebhookValidator } from "../src/services/WebhookValidator";
+import crypto from "crypto";
+
+describe("Services", () => {
+    // Test private key (PKCS#1 format, Base64 encoded)
+    const testPrivateKeyBase64 =
+        "LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQpNSUlFb2dJQkFBS0NBUUVBcTZ1Ykh3d1BET1FNMitHaHJZUlN3OEs2UytKcXAzem5YRGFITU1JZzg5WTZ1MUcyClZibm9TNjA4RjYwNnVSWGt1WUx2MUh6aHRLczJaOU9MaGh0YW1aV05hZVVEVlZPY2hzQ21MbDVNaCt6MTFLd2gKSG8wcU1NOUxxTHNOL3RYZDJZMDE0TkVhQ2hEZjdEMjUxLzFEWFh4WkNJTGk2NHROYm03SXh3U3J3bDlzeFBJRApPQzZrZU50UEEybGEydEFmNlc0OUJ2MVlxcDBLYnhObnBkeG90SkZsMEZBRjRYeUJSeWF6Mi9VWTN0S1BybjcyCnF6Ti9QMDN4RzhkMlZPU3hpZ3grOWJ0cndFazhRSE5qUGxiR0s1dzI3NU9vMHF2NFhjVTIvUzNsMS9JLzVxeG8KQW1haEJJN0ZoWThxQWRWd0hheGN3NGRkR1VHMzhmSXl0RlhKRlFJREFRQUJBb0lCQUFrQngzRkJFamNVYmdKSgpXOUM5VFJSZFRxWDFtcS92OHptWTJNMzdtWHdCcFBJNERzOS9vZ3I2YTFrNHF3aVQ5L3l0dklTVENzcU9ZeHZlCmN3Y1Z2MUtva0pOYVF5c0NhSWQvYXhpcXRPdzZ5QWtoQU5uWUFUc3ZYU0pjc2hiSlJNc0p5Q1prQWpBK0EybWoKTVhGK0piOHRhNFJ4VFpPYkt2UmMxcWJ1ZlU2RTJpQXY1aDNHcGhjL2RrSTJhRkJyQ29vdndhbjIzUlo0aXVuQgpKZGpxQXZaeFFremlrNy9OeEZUZjJMYUk4L2VqaGhGNlU4aXBuYU84VUNhS2FsMHUwSG9IVmd1eFR6UTRFSjhmCmh0QUdKYi8wRyswZ2xNK3ZHa3hxdHhDUXNhMnBKdmlHaTIwOWFSS3NIYnlZVG05amFnRk9SR2hIZERzY05DWUoKMFdQK20rOENnWUVBNHdVU0dHY0ZpZXJoZEdTTVovTFF6OTlBWWpaSVczR09YRUpEcG1vYmhPMzZXVEluM1hESwpPVDdpdHBWQlptSWxHQXROdTJ5clZEeFRqM3BrQVBIWDRhckwvUUx1Y3hDckZldFROODhubEJ5N2lIUkh1UjA0CkprU0RCL0EwVW9STXlOUzhqTG9JblErUS9VZUVwY1k4ejN6cUdFaVhXMUJLZlVFRjVXZmVEbWNDZ1lFQXdaVzcKeVRCNXRQbExGR0d3Yk5VMWphc1ZRb0pZWGo2MHR3TTU0SktjZElNVmFYS1RLOSt6cGcydjc5aTVzTHNIOG50TApXQ0hOSDlyandiaHRHMmZOT0FweWtnY1pjTHg2VUR3R1RYM3R1NC9NMld3YnFNL0crOTAvL1NYSSttQzVvYTRZCnp1Y1NZeGxyeWxrMlp6ZzRTN005VzBKQTNDNjFQeERSaXNXakJ5TUNnWUFseVFaR0FYK3VnT1dkbGM2NHpuVnEKNCtHM2R3bDhEdDUvQkpoMTdscytPTTNlWXJhMzZMbi81VE9lNkNER2hiZGUxU0xPK3p0WS9lRjZsQWhwRDllNgp1ODdRQWRqbVZmUGo1aE1ueXRidmxBaXlvWWYraTVwNDVCWmJEK1BsaUJldnBaanNZMXBqcWQrY0NIZFBrRHMyCjNiZW82d3dtS3FyN1JnTlJONFNDS1FLQmdCOGk0MEpYM3F1Q0VWWms1QWlOUG9EYnpKNlc4bm11SWtqeFp1UzkKRUJjWllsOUVnM0ZpR0xZVHE0R3JYU3FVMnBGZ3pWeU9penlkYTFha1FFQlJNTXZidWxQTWVvWU1lcXZmQzdCNQpHYnk2UTF1UkxOMjVGYXM3Q2VqQXBCUEpiUElaVzNvajVtdzBFWWRKVkJ2RUNpSDY0VnFGVElOZHE5OUo2RG9tCjBiTDdBb0dBRW9hUk9tUVpVMHJ6UUhXNUkxWnRIM0hKZDk1YTBPSFNlTVdNYllaeE9ST1ZMNWdQckhQSFRzU2YKbTNpWmNLaFgvdXRleEdjWm1zN0M4U3M5NWp4TzRiV3pBcDYxVU1aU3dVYStYNTRUNHkwNUxWRXRUOG5TdVRySwpxV1dMOGVDNXJGMktIYjJ3UFV3Vm1mUEc4SWlMS1FkUHR2b1ZzRGM2dU95NURSdkpzV0k9Ci0tLS0tRU5EIFJTQSBQUklWQVRFIEtFWS0tLS0t";
+
+    describe("GitHubAuthService", () => {
+        it("should generate valid GitHub App JWT", () => {
+            const appId = "123456";
+            const baseUrl = "https://api.github.com";
+
+            const authService = new GitHubAuthService(appId, testPrivateKeyBase64, baseUrl);
+            const jwt = authService.generateAppJWT();
+
+            expect(jwt).toBeTruthy();
+            expect(typeof jwt).toBe("string");
+            expect(jwt.split(".").length).toBe(3); // JWT has 3 parts
+        });
+
+        it("should throw error with invalid private key", () => {
+            const appId = "123456";
+            const invalidKey = "not a valid key";
+            const baseUrl = "https://api.github.com";
+
+            expect(() => {
+                new GitHubAuthService(appId, invalidKey, baseUrl);
+            }).toThrow();
+        });
+
+        // Note: Testing token exchange requires mocking GitHub API
+        // This is skipped in favor of integration tests
+    });
+
+    describe("GitHubAPIClient", () => {
+        it("should initialize with installation ID and auth service", () => {
+            const appId = "123456";
+            const installationId = 12345;
+            const authService = new GitHubAuthService(appId, testPrivateKeyBase64, "https://api.github.com");
+
+            const apiClient = new GitHubAPIClient(installationId, authService);
+
+            expect(apiClient).toBeTruthy();
+        });
+
+        // Note: Testing actual API calls requires mocking GitHub API
+        // These are tested in integration tests instead
+    });
+
+    describe("WebhookValidator", () => {
+        const secret = "test-webhook-secret";
+        const validator = new WebhookValidator(secret);
+
+        it("should validate signature and parse payload correctly", () => {
+            const payload = JSON.stringify({
+                action: "opened",
+                installation: { id: 12345 },
+            });
+
+            // Generate valid signature
+            const signature = "sha256=" + crypto.createHmac("sha256", secret).update(payload).digest("hex");
+
+            const result = validator.validateSignature(payload, signature);
+
+            expect(result).toBe(true);
+        });
+
+        it("should reject invalid signature", () => {
+            const payload = JSON.stringify({ action: "opened" });
+            const invalidSignature = "sha256=invalid_signature_here";
+
+            const result = validator.validateSignature(payload, invalidSignature);
+
+            expect(result).toBe(false);
+        });
+
+        it("should parse webhook payload correctly", () => {
+            const payload = JSON.stringify({
+                action: "opened",
+                installation: { id: 12345 },
+                repository: { name: "test-repo" },
+            });
+
+            const parsed = validator.parsePayload(payload);
+
+            expect(parsed).toBeTruthy();
+            expect(parsed.action).toBe("opened");
+            expect(parsed.installation?.id).toBe(12345);
+        });
+
+        it("should handle malformed JSON gracefully", () => {
+            const invalidJson = "{ this is not valid json }";
+
+            expect(() => {
+                validator.parsePayload(invalidJson);
+            }).toThrow();
+        });
+    });
+});

package/spec/support/jasmine.json

@@ -0,0 +1,7 @@
+{
+  "spec_dir": "spec",
+  "spec_files": ["**/*[sS]pec.ts"],
+  "helpers": ["helpers/**/*.ts"],
+  "stopSpecOnExpectationFailure": false,
+  "random": true
+}

package/src/GitHubAppPlugin.ts

@@ -0,0 +1,411 @@
+import { FlinkApp, FlinkPlugin, log } from "@flink-app/flink";
+import { Db } from "mongodb";
+import { GitHubAppPluginOptions } from "./GitHubAppPluginOptions";
+import { GitHubAppPluginContext } from "./GitHubAppPluginContext";
+import GitHubAppSessionRepo from "./repos/GitHubAppSessionRepo";
+import GitHubInstallationRepo from "./repos/GitHubInstallationRepo";
+import GitHubWebhookEventRepo from "./repos/GitHubWebhookEventRepo";
+import { GitHubAuthService } from "./services/GitHubAuthService";
+import { GitHubAPIClient } from "./services/GitHubAPIClient";
+import { WebhookValidator } from "./services/WebhookValidator";
+import GitHubInstallation from "./schemas/GitHubInstallation";
+import { createGitHubAppError, GitHubAppErrorCodes } from "./utils/error-utils";
+import { generateState, generateSessionId } from "./utils/state-utils";
+import * as InstallationCallback from "./handlers/InstallationCallback";
+import * as WebhookHandler from "./handlers/WebhookHandler";
+
+/**
+ * GitHub App Plugin Factory Function
+ *
+ * Creates a Flink plugin for GitHub App integration with:
+ * - Installation management
+ * - JWT-based authentication with private key signing
+ * - Installation access token management with automatic refresh and caching
+ * - Webhook integration with signature validation
+ * - GitHub API client wrapper
+ *
+ * @param options - GitHub App plugin configuration options
+ * @returns FlinkPlugin instance
+ *
+ * @example
+ * ```typescript
+ * import { githubAppPlugin } from '@flink-app/github-app-plugin';
+ *
+ * const app = new FlinkApp({
+ *   plugins: [
+ *     githubAppPlugin({
+ *       appId: process.env.GITHUB_APP_ID!,
+ *       privateKey: process.env.GITHUB_APP_PRIVATE_KEY!,
+ *       webhookSecret: process.env.GITHUB_WEBHOOK_SECRET!,
+ *       clientId: process.env.GITHUB_APP_CLIENT_ID!,
+ *       clientSecret: process.env.GITHUB_APP_CLIENT_SECRET!,
+ *       onInstallationSuccess: async ({ installationId, repositories, account }, ctx) => {
+ *         const userId = getLoggedInUserId(req); // App-defined function
+ *         return {
+ *           userId,
+ *           redirectUrl: '/dashboard/repos'
+ *         };
+ *       },
+ *       onWebhookEvent: async ({ event, payload, installationId }, ctx) => {
+ *         if (event === 'push') {
+ *           // Process push event
+ *         }
+ *       }
+ *     })
+ *   ]
+ * });
+ * ```
+ */
+export function githubAppPlugin(options: GitHubAppPluginOptions): FlinkPlugin {
+    // Validate required options
+    if (!options.appId) {
+        throw new Error("GitHub App Plugin: appId is required");
+    }
+    if (!options.privateKey) {
+        throw new Error("GitHub App Plugin: privateKey is required");
+    }
+    if (!options.webhookSecret) {
+        throw new Error("GitHub App Plugin: webhookSecret is required");
+    }
+    if (!options.clientId) {
+        throw new Error("GitHub App Plugin: clientId is required");
+    }
+    if (!options.clientSecret) {
+        throw new Error("GitHub App Plugin: clientSecret is required");
+    }
+    if (!options.onInstallationSuccess) {
+        throw new Error("GitHub App Plugin: onInstallationSuccess callback is required");
+    }
+
+    // Determine configuration defaults
+    const baseUrl = options.baseUrl || "https://api.github.com";
+    const tokenCacheTTL = options.tokenCacheTTL || 3300; // 55 minutes
+    const sessionTTL = options.sessionTTL || 600; // 10 minutes
+    const registerRoutes = options.registerRoutes !== false; // default true
+    const logWebhookEvents = options.logWebhookEvents || false; // default false
+
+    let flinkApp: FlinkApp<any>;
+    let authService: GitHubAuthService;
+    let webhookValidator: WebhookValidator;
+    let sessionRepo: GitHubAppSessionRepo;
+    let installationRepo: GitHubInstallationRepo;
+    let webhookEventRepo: GitHubWebhookEventRepo | undefined;
+
+    /**
+     * Plugin initialization
+     */
+    async function init(app: FlinkApp<any>, db?: Db) {
+        log.info("Initializing GitHub App Plugin...");
+
+        flinkApp = app;
+
+        try {
+            if (!db) {
+                throw new Error("GitHub App Plugin: Database connection is required");
+            }
+
+            // Initialize GitHubAuthService with private key validation
+            // This will throw early if the private key is invalid
+            try {
+                authService = new GitHubAuthService(options.appId, options.privateKey, baseUrl, tokenCacheTTL);
+                log.info("GitHub App Plugin: Successfully validated private key and generated test JWT");
+            } catch (error: any) {
+                log.error("GitHub App Plugin: Failed to initialize auth service", error);
+                throw error;
+            }
+
+            // Initialize WebhookValidator
+            webhookValidator = new WebhookValidator(options.webhookSecret);
+
+            // Initialize repositories
+            const sessionsCollectionName = options.sessionsCollectionName || "github_app_sessions";
+            const installationsCollectionName = options.installationsCollectionName || "github_installations";
+            const webhookEventsCollectionName = options.webhookEventsCollectionName || "github_webhook_events";
+
+            sessionRepo = new GitHubAppSessionRepo(flinkApp.ctx, db, sessionsCollectionName);
+            installationRepo = new GitHubInstallationRepo(flinkApp.ctx, db, installationsCollectionName);
+
+            // Add repositories to FlinkApp
+            flinkApp.addRepo("githubAppSessionRepo", sessionRepo);
+            flinkApp.addRepo("githubInstallationRepo", installationRepo);
+
+            // Conditionally initialize webhook event repo if logging is enabled
+            if (logWebhookEvents) {
+                webhookEventRepo = new GitHubWebhookEventRepo(flinkApp.ctx, db, webhookEventsCollectionName);
+                flinkApp.addRepo("githubWebhookEventRepo", webhookEventRepo);
+                log.info(`GitHub App Plugin: Webhook event logging enabled (collection: ${webhookEventsCollectionName})`);
+            }
+
+            // Create TTL indexes
+            // Sessions TTL index for automatic cleanup
+            await db.collection(sessionsCollectionName).createIndex({ createdAt: 1 }, { expireAfterSeconds: sessionTTL });
+            log.info(`GitHub App Plugin: Created TTL index on ${sessionsCollectionName} with ${sessionTTL}s expiration`);
+
+            // Webhook events TTL index if logging enabled
+            if (logWebhookEvents && webhookEventsCollectionName) {
+                // Optional TTL for webhook events (default: 30 days)
+                const webhookEventTTL = 30 * 24 * 60 * 60; // 30 days in seconds
+                await db.collection(webhookEventsCollectionName).createIndex({ createdAt: 1 }, { expireAfterSeconds: webhookEventTTL });
+                log.info(`GitHub App Plugin: Created TTL index on ${webhookEventsCollectionName} with ${webhookEventTTL}s expiration`);
+            }
+
+            // Conditionally register handlers (only GitHub-required handlers)
+            if (registerRoutes) {
+                flinkApp.addHandler(InstallationCallback);
+                flinkApp.addHandler(WebhookHandler);
+                log.info("GitHub App Plugin: Registered handlers (callback and webhook)");
+            } else {
+                log.info("GitHub App Plugin: Skipped handler registration (routes disabled)");
+            }
+
+            log.info(`GitHub App Plugin initialized successfully`);
+            log.info(`  - App ID: ${options.appId}`);
+            log.info(`  - Base URL: ${baseUrl}`);
+            log.info(`  - Token Cache TTL: ${tokenCacheTTL}s`);
+            log.info(`  - Session TTL: ${sessionTTL}s`);
+            log.info(`  - Routes Registered: ${registerRoutes}`);
+            log.info(`  - Webhook Logging: ${logWebhookEvents}`);
+        } catch (error) {
+            log.error("Failed to initialize GitHub App Plugin:", error);
+            throw error;
+        }
+    }
+
+    /**
+     * Initiates GitHub App installation flow
+     */
+    async function initiateInstallation(params: {
+        userId: string;
+        redirectUrl?: string;
+        metadata?: Record<string, any>;
+    }): Promise<{
+        redirectUrl: string;
+        state: string;
+        sessionId: string;
+    }> {
+        if (!sessionRepo) {
+            throw new Error("GitHub App Plugin: Plugin not initialized");
+        }
+
+        // Validate that appSlug is configured
+        if (!options.appSlug) {
+            throw new Error("GitHub App Plugin: appSlug is required for installation flow. Please set appSlug in plugin options.");
+        }
+
+        // Generate cryptographically secure state and session ID
+        const state = generateState();
+        const sessionId = generateSessionId();
+
+        // Store session for state validation in callback
+        await sessionRepo.create({
+            sessionId,
+            state,
+            userId: params.userId,
+            metadata: params.metadata || {},
+            createdAt: new Date(),
+        });
+
+        // Build GitHub installation URL
+        const installationUrl = `https://github.com/apps/${options.appSlug}/installations/new?state=${state}`;
+
+        log.info("GitHub App installation initiated", { userId: params.userId, sessionId });
+
+        return {
+            redirectUrl: installationUrl,
+            state,
+            sessionId,
+        };
+    }
+
+    /**
+     * Uninstalls GitHub App for a user
+     */
+    async function uninstall(params: {
+        userId: string;
+        installationId: number;
+    }): Promise<{
+        success: boolean;
+        error?: string;
+    }> {
+        if (!installationRepo || !authService) {
+            throw new Error("GitHub App Plugin: Plugin not initialized");
+        }
+
+        try {
+            // Find installation
+            const installation = await installationRepo.findByUserAndInstallationId(params.userId, params.installationId);
+
+            if (!installation) {
+                return { success: false, error: "installation-not-found" };
+            }
+
+            // Verify ownership
+            if (installation.userId !== params.userId) {
+                log.warn("User attempted to uninstall installation they don't own", {
+                    userId: params.userId,
+                    installationId: params.installationId,
+                    ownerId: installation.userId,
+                });
+                return { success: false, error: "installation-not-owned" };
+            }
+
+            // Delete from database
+            await installationRepo.deleteByInstallationId(params.installationId);
+
+            // Clear token cache
+            authService.deleteInstallationToken(params.installationId);
+
+            log.info("GitHub App uninstalled", { userId: params.userId, installationId: params.installationId });
+
+            return { success: true };
+        } catch (error: any) {
+            log.error("Failed to uninstall GitHub App", {
+                userId: params.userId,
+                installationId: params.installationId,
+                error: error.message,
+            });
+            return { success: false, error: "uninstall-failed" };
+        }
+    }
+
+    /**
+     * Get GitHub API client for an installation
+     */
+    async function getClient(installationId: number): Promise<GitHubAPIClient> {
+        if (!authService) {
+            throw new Error("GitHub App Plugin: Plugin not initialized");
+        }
+
+        return new GitHubAPIClient(installationId, authService, baseUrl);
+    }
+
+    /**
+     * Get installation for a user (returns first installation)
+     */
+    async function getInstallation(userId: string): Promise<GitHubInstallation | null> {
+        if (!installationRepo) {
+            throw new Error("GitHub App Plugin: Plugin not initialized");
+        }
+
+        const installations = await installationRepo.findByUserId(userId);
+        return installations.length > 0 ? installations[0] : null;
+    }
+
+    /**
+     * Get all installations for a user
+     */
+    async function getInstallations(userId: string): Promise<GitHubInstallation[]> {
+        if (!installationRepo) {
+            throw new Error("GitHub App Plugin: Plugin not initialized");
+        }
+
+        return installationRepo.findByUserId(userId);
+    }
+
+    /**
+     * Delete installation
+     */
+    async function deleteInstallation(userId: string, installationId: number): Promise<void> {
+        if (!installationRepo || !authService) {
+            throw new Error("GitHub App Plugin: Plugin not initialized");
+        }
+
+        // Verify user owns the installation
+        const installation = await installationRepo.findByUserAndInstallationId(userId, installationId);
+        if (!installation) {
+            throw createGitHubAppError(
+                GitHubAppErrorCodes.INSTALLATION_NOT_OWNED,
+                "Installation not found or not owned by user",
+                { userId, installationId }
+            );
+        }
+
+        // Delete from database
+        await installationRepo.deleteByInstallationId(installationId);
+
+        // Clear token cache for this installation
+        authService.deleteInstallationToken(installationId);
+
+        log.info(`GitHub App Plugin: Deleted installation ${installationId} for user ${userId}`);
+    }
+
+    /**
+     * Check if user has access to specific repository
+     */
+    async function hasRepositoryAccess(userId: string, owner: string, repo: string): Promise<boolean> {
+        if (!installationRepo) {
+            throw new Error("GitHub App Plugin: Plugin not initialized");
+        }
+
+        const installations = await installationRepo.findByUserId(userId);
+
+        // Check if any installation has access to the repository
+        for (const installation of installations) {
+            // Skip suspended installations
+            if (installation.suspendedAt) {
+                continue;
+            }
+
+            // Check repositories array
+            const hasAccess = installation.repositories.some(
+                (r) => r.fullName.toLowerCase() === `${owner}/${repo}`.toLowerCase()
+            );
+
+            if (hasAccess) {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
+    /**
+     * Get installation access token (for advanced usage)
+     */
+    async function getInstallationToken(installationId: number): Promise<string> {
+        if (!authService) {
+            throw new Error("GitHub App Plugin: Plugin not initialized");
+        }
+
+        return authService.getInstallationToken(installationId);
+    }
+
+    /**
+     * Clear token cache
+     */
+    function clearTokenCache(): void {
+        if (!authService) {
+            throw new Error("GitHub App Plugin: Plugin not initialized");
+        }
+
+        authService.clearTokenCache();
+        log.info("GitHub App Plugin: Cleared token cache");
+    }
+
+    /**
+     * Plugin context exposed via ctx.plugins.githubApp
+     */
+    const pluginCtx: GitHubAppPluginContext["githubApp"] = {
+        initiateInstallation,
+        uninstall,
+        getClient,
+        getInstallation,
+        getInstallations,
+        deleteInstallation,
+        hasRepositoryAccess,
+        getInstallationToken,
+        clearTokenCache,
+        options: Object.freeze({ ...options }),
+        get authService() { return authService; },
+        get webhookValidator() { return webhookValidator; },
+    };
+
+    return {
+        id: "githubApp",
+        db: {
+            useHostDb: true,
+        },
+        ctx: pluginCtx,
+        init,
+    };
+}