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

package/dist/GitHubAppPlugin.js

@@ -0,0 +1,367 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.githubAppPlugin = void 0;
+const flink_1 = require("@flink-app/flink");
+const GitHubAppSessionRepo_1 = __importDefault(require("./repos/GitHubAppSessionRepo"));
+const GitHubInstallationRepo_1 = __importDefault(require("./repos/GitHubInstallationRepo"));
+const GitHubWebhookEventRepo_1 = __importDefault(require("./repos/GitHubWebhookEventRepo"));
+const GitHubAuthService_1 = require("./services/GitHubAuthService");
+const GitHubAPIClient_1 = require("./services/GitHubAPIClient");
+const WebhookValidator_1 = require("./services/WebhookValidator");
+const error_utils_1 = require("./utils/error-utils");
+const state_utils_1 = require("./utils/state-utils");
+const InstallationCallback = __importStar(require("./handlers/InstallationCallback"));
+const WebhookHandler = __importStar(require("./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
+ *         }
+ *       }
+ *     })
+ *   ]
+ * });
+ * ```
+ */
+function githubAppPlugin(options) {
+    // 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;
+    let authService;
+    let webhookValidator;
+    let sessionRepo;
+    let installationRepo;
+    let webhookEventRepo;
+    /**
+     * Plugin initialization
+     */
+    async function init(app, db) {
+        flink_1.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_1.GitHubAuthService(options.appId, options.privateKey, baseUrl, tokenCacheTTL);
+                flink_1.log.info("GitHub App Plugin: Successfully validated private key and generated test JWT");
+            }
+            catch (error) {
+                flink_1.log.error("GitHub App Plugin: Failed to initialize auth service", error);
+                throw error;
+            }
+            // Initialize WebhookValidator
+            webhookValidator = new WebhookValidator_1.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_1.default(flinkApp.ctx, db, sessionsCollectionName);
+            installationRepo = new GitHubInstallationRepo_1.default(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_1.default(flinkApp.ctx, db, webhookEventsCollectionName);
+                flinkApp.addRepo("githubWebhookEventRepo", webhookEventRepo);
+                flink_1.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 });
+            flink_1.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 });
+                flink_1.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);
+                flink_1.log.info("GitHub App Plugin: Registered handlers (callback and webhook)");
+            }
+            else {
+                flink_1.log.info("GitHub App Plugin: Skipped handler registration (routes disabled)");
+            }
+            flink_1.log.info(`GitHub App Plugin initialized successfully`);
+            flink_1.log.info(`  - App ID: ${options.appId}`);
+            flink_1.log.info(`  - Base URL: ${baseUrl}`);
+            flink_1.log.info(`  - Token Cache TTL: ${tokenCacheTTL}s`);
+            flink_1.log.info(`  - Session TTL: ${sessionTTL}s`);
+            flink_1.log.info(`  - Routes Registered: ${registerRoutes}`);
+            flink_1.log.info(`  - Webhook Logging: ${logWebhookEvents}`);
+        }
+        catch (error) {
+            flink_1.log.error("Failed to initialize GitHub App Plugin:", error);
+            throw error;
+        }
+    }
+    /**
+     * Initiates GitHub App installation flow
+     */
+    async function initiateInstallation(params) {
+        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 = (0, state_utils_1.generateState)();
+        const sessionId = (0, state_utils_1.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}`;
+        flink_1.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) {
+        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) {
+                flink_1.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);
+            flink_1.log.info("GitHub App uninstalled", { userId: params.userId, installationId: params.installationId });
+            return { success: true };
+        }
+        catch (error) {
+            flink_1.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) {
+        if (!authService) {
+            throw new Error("GitHub App Plugin: Plugin not initialized");
+        }
+        return new GitHubAPIClient_1.GitHubAPIClient(installationId, authService, baseUrl);
+    }
+    /**
+     * Get installation for a user (returns first installation)
+     */
+    async function getInstallation(userId) {
+        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) {
+        if (!installationRepo) {
+            throw new Error("GitHub App Plugin: Plugin not initialized");
+        }
+        return installationRepo.findByUserId(userId);
+    }
+    /**
+     * Delete installation
+     */
+    async function deleteInstallation(userId, installationId) {
+        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 (0, error_utils_1.createGitHubAppError)(error_utils_1.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);
+        flink_1.log.info(`GitHub App Plugin: Deleted installation ${installationId} for user ${userId}`);
+    }
+    /**
+     * Check if user has access to specific repository
+     */
+    async function hasRepositoryAccess(userId, owner, repo) {
+        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) {
+        if (!authService) {
+            throw new Error("GitHub App Plugin: Plugin not initialized");
+        }
+        return authService.getInstallationToken(installationId);
+    }
+    /**
+     * Clear token cache
+     */
+    function clearTokenCache() {
+        if (!authService) {
+            throw new Error("GitHub App Plugin: Plugin not initialized");
+        }
+        authService.clearTokenCache();
+        flink_1.log.info("GitHub App Plugin: Cleared token cache");
+    }
+    /**
+     * Plugin context exposed via ctx.plugins.githubApp
+     */
+    const pluginCtx = {
+        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,
+    };
+}
+exports.githubAppPlugin = githubAppPlugin;

package/dist/GitHubAppPluginContext.d.ts

@@ -0,0 +1,242 @@
+import { GitHubAPIClient } from "./services/GitHubAPIClient";
+import GitHubInstallation from "./schemas/GitHubInstallation";
+import { GitHubAppPluginOptions } from "./GitHubAppPluginOptions";
+import { GitHubAuthService } from "./services/GitHubAuthService";
+import { WebhookValidator } from "./services/WebhookValidator";
+/**
+ * Public context interface exposed via ctx.plugins.githubApp
+ *
+ * Provides methods for interacting with GitHub App installations,
+ * managing installation access, and creating authenticated API clients.
+ */
+export interface GitHubAppPluginContext {
+    githubApp: {
+        /**
+         * Initiates GitHub App installation flow
+         *
+         * Creates a session with CSRF protection and returns the installation URL.
+         * Call this from your own handler with your own auth logic.
+         *
+         * @param params - Installation parameters
+         * @param params.userId - Application user ID to link installation to
+         * @param params.redirectUrl - Optional URL to redirect to after installation (deprecated, use onInstallationSuccess callback)
+         * @param params.metadata - Optional metadata to store in session
+         * @returns Installation flow details
+         *
+         * @example
+         * ```typescript
+         * // In your custom handler
+         * export default async function InitiateGitHubInstall({ ctx }: GetHandlerParams) {
+         *   const userId = ctx.auth.tokenData.userId;
+         *
+         *   const { redirectUrl } = await ctx.plugins.githubApp.initiateInstallation({
+         *     userId,
+         *     metadata: { source: 'settings' }
+         *   });
+         *
+         *   return {
+         *     status: 302,
+         *     headers: { Location: redirectUrl }
+         *   };
+         * }
+         * ```
+         */
+        initiateInstallation(params: {
+            userId: string;
+            redirectUrl?: string;
+            metadata?: Record<string, any>;
+        }): Promise<{
+            redirectUrl: string;
+            state: string;
+            sessionId: string;
+        }>;
+        /**
+         * Uninstalls GitHub App for a user
+         *
+         * Removes installation from database and clears cached token.
+         * Call this from your own handler with your own auth logic.
+         *
+         * @param params - Uninstall parameters
+         * @param params.userId - Application user ID requesting uninstall
+         * @param params.installationId - GitHub installation ID to uninstall
+         * @returns Uninstall result
+         *
+         * @example
+         * ```typescript
+         * // In your custom handler
+         * export default async function UninstallGitHub({ ctx, params }: DeleteHandlerParams) {
+         *   const userId = ctx.auth.tokenData.userId;
+         *
+         *   const result = await ctx.plugins.githubApp.uninstall({
+         *     userId,
+         *     installationId: params.installationId
+         *   });
+         *
+         *   if (!result.success) {
+         *     return badRequest(result.error);
+         *   }
+         *
+         *   return { status: 204 };
+         * }
+         * ```
+         */
+        uninstall(params: {
+            userId: string;
+            installationId: number;
+        }): Promise<{
+            success: boolean;
+            error?: string;
+        }>;
+        /**
+         * Get GitHub API client for an installation
+         *
+         * Creates an authenticated API client with automatic token injection.
+         * The client handles token caching, refresh, and retry logic.
+         *
+         * @param installationId - GitHub installation ID
+         * @returns GitHub API client instance
+         *
+         * @example
+         * ```typescript
+         * const client = await ctx.plugins.githubApp.getClient(12345);
+         * const repos = await client.getRepositories();
+         * ```
+         */
+        getClient(installationId: number): Promise<GitHubAPIClient>;
+        /**
+         * Get installation for a user
+         *
+         * Returns the first installation found for the user.
+         * Use getInstallations() if a user may have multiple installations.
+         *
+         * @param userId - Application user ID
+         * @returns Installation if found, null otherwise
+         *
+         * @example
+         * ```typescript
+         * const installation = await ctx.plugins.githubApp.getInstallation('user-123');
+         * if (installation) {
+         *   console.log('Installed on:', installation.accountLogin);
+         * }
+         * ```
+         */
+        getInstallation(userId: string): Promise<GitHubInstallation | null>;
+        /**
+         * Get all installations for a user
+         *
+         * Returns all GitHub App installations linked to the user.
+         * Users can install the app on multiple accounts (personal + organizations).
+         *
+         * @param userId - Application user ID
+         * @returns Array of installations
+         *
+         * @example
+         * ```typescript
+         * const installations = await ctx.plugins.githubApp.getInstallations('user-123');
+         * installations.forEach(installation => {
+         *   console.log(`Installed on ${installation.accountLogin} (${installation.accountType})`);
+         * });
+         * ```
+         */
+        getInstallations(userId: string): Promise<GitHubInstallation[]>;
+        /**
+         * Delete installation
+         *
+         * Removes an installation from the database and clears its cached token.
+         * Verifies the user owns the installation before deletion.
+         *
+         * @param userId - Application user ID
+         * @param installationId - GitHub installation ID
+         * @throws Error if user doesn't own installation
+         *
+         * @example
+         * ```typescript
+         * await ctx.plugins.githubApp.deleteInstallation('user-123', 12345);
+         * ```
+         */
+        deleteInstallation(userId: string, installationId: number): Promise<void>;
+        /**
+         * Check if user has access to specific repository
+         *
+         * Verifies that the user has an installation with access to the
+         * specified repository. Useful for authorization checks.
+         *
+         * @param userId - Application user ID
+         * @param owner - Repository owner (username or org)
+         * @param repo - Repository name
+         * @returns true if user has access, false otherwise
+         *
+         * @example
+         * ```typescript
+         * const hasAccess = await ctx.plugins.githubApp.hasRepositoryAccess(
+         *   'user-123',
+         *   'facebook',
+         *   'react'
+         * );
+         *
+         * if (!hasAccess) {
+         *   return forbidden('You do not have access to this repository');
+         * }
+         * ```
+         */
+        hasRepositoryAccess(userId: string, owner: string, repo: string): Promise<boolean>;
+        /**
+         * Get installation access token (for advanced usage)
+         *
+         * Returns a raw installation access token. Tokens are cached
+         * and automatically refreshed when expired.
+         *
+         * Most users should use getClient() instead, which handles
+         * token injection automatically.
+         *
+         * @param installationId - GitHub installation ID
+         * @returns Installation access token
+         *
+         * @example
+         * ```typescript
+         * const token = await ctx.plugins.githubApp.getInstallationToken(12345);
+         * // Make custom API call with token
+         * ```
+         */
+        getInstallationToken(installationId: number): Promise<string>;
+        /**
+         * Clear token cache
+         *
+         * Removes all cached installation tokens. Next API call will
+         * fetch fresh tokens from GitHub.
+         *
+         * Useful for testing, forcing token refresh, or plugin shutdown.
+         *
+         * @example
+         * ```typescript
+         * ctx.plugins.githubApp.clearTokenCache();
+         * ```
+         */
+        clearTokenCache(): void;
+        /**
+         * Plugin configuration (read-only)
+         *
+         * Provides access to plugin options for custom logic.
+         * Object is frozen to prevent modifications.
+         */
+        options: Readonly<GitHubAppPluginOptions>;
+        /**
+         * GitHub Authentication Service
+         *
+         * @internal
+         * Used internally by plugin handlers. Most applications should not need to access this directly.
+         *
+         * Provides JWT generation and installation token management.
+         */
+        authService: GitHubAuthService;
+        /**
+         * Webhook Validator
+         *
+         * @internal
+         * Used internally by plugin handlers. Most applications should not need to access this directly.
+         *
+         * Validates webhook signatures and parses webhook payloads.
+         */
+        webhookValidator: WebhookValidator;
+    };
+}

package/dist/GitHubAppPluginContext.js

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