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

package/src/GitHubAppPluginContext.ts

@@ -0,0 +1,254 @@
+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/src/GitHubAppPluginOptions.ts

@@ -0,0 +1,412 @@
+/**
+ * Installation success callback parameters
+ *
+ * Provided to the onInstallationSuccess callback when a user successfully
+ * installs the GitHub App and grants access to repositories.
+ */
+export interface InstallationSuccessParams {
+    /** GitHub installation ID */
+    installationId: number;
+
+    /** GitHub account (user or organization) where app was installed */
+    account: {
+        /** Account ID on GitHub */
+        id: number;
+        /** Account username or organization name */
+        login: string;
+        /** Account type */
+        type: "User" | "Organization";
+        /** Profile picture URL */
+        avatarUrl?: string;
+    };
+
+    /** Repositories the user granted access to */
+    repositories: {
+        /** Repository ID on GitHub */
+        id: number;
+        /** Repository name (without owner) */
+        name: string;
+        /** Full repository name (owner/repo) */
+        fullName: string;
+        /** Whether repository is private */
+        private: boolean;
+    }[];
+
+    /** Permissions granted to the app (e.g., { contents: 'read', issues: 'write' }) */
+    permissions: Record<string, string>;
+
+    /** Webhook events the app is subscribed to */
+    events: string[];
+}
+
+/**
+ * Installation success callback response
+ *
+ * Return this from onInstallationSuccess to link the installation
+ * to a user in your application and redirect the user.
+ */
+export interface InstallationSuccessResponse {
+    /**
+     * User ID in your application to link this installation to
+     *
+     * The plugin stores this mapping to enable repository access checks.
+     * Get this from your authentication system (session, JWT, etc.)
+     */
+    userId: string;
+
+    /**
+     * Optional URL to redirect user after installation
+     *
+     * If not provided, a default success page will be shown.
+     * Use this to redirect users to your dashboard or specific page.
+     *
+     * @example "/dashboard/github"
+     * @example "/repos?installation=success"
+     */
+    redirectUrl?: string;
+}
+
+/**
+ * Installation error callback parameters
+ *
+ * Provided to the onInstallationError callback when installation fails.
+ */
+export interface InstallationErrorParams {
+    /** Error information */
+    error: {
+        /** Error code in kebab-case (e.g., 'invalid-state', 'session-expired') */
+        code: string;
+        /** User-friendly error message */
+        message: string;
+        /** Additional error details for debugging */
+        details?: any;
+    };
+
+    /** Installation ID if available (may be undefined if error occurred before installation) */
+    installationId?: number;
+}
+
+/**
+ * Installation error callback response
+ *
+ * Return this from onInstallationError to redirect the user
+ * to an error page or retry flow.
+ */
+export interface InstallationErrorResponse {
+    /**
+     * Optional URL to redirect user after error
+     *
+     * Use this to show error messages or allow retry.
+     *
+     * @example "/error?message=installation-failed"
+     * @example "/github/install?retry=true"
+     */
+    redirectUrl?: string;
+}
+
+/**
+ * Webhook event callback parameters
+ *
+ * Provided to the onWebhookEvent callback when a webhook event is received
+ * from GitHub. The plugin validates the webhook signature before calling this.
+ */
+export interface WebhookEventParams {
+    /**
+     * GitHub event type
+     *
+     * Common events: 'push', 'pull_request', 'issues', 'installation',
+     * 'pull_request_review', 'issue_comment', 'release', etc.
+     */
+    event: string;
+
+    /**
+     * Event action (if applicable)
+     *
+     * Examples: 'opened', 'closed', 'reopened', 'created', 'deleted', etc.
+     * Not all events have actions.
+     */
+    action?: string;
+
+    /**
+     * Full webhook payload from GitHub
+     *
+     * Structure varies by event type. See GitHub webhook documentation
+     * for payload schemas.
+     */
+    payload: Record<string, any>;
+
+    /** Installation ID that triggered the webhook */
+    installationId: number;
+
+    /**
+     * Unique delivery ID from GitHub (X-GitHub-Delivery header)
+     *
+     * Use this for debugging and tracking webhook deliveries.
+     */
+    deliveryId: string;
+}
+
+/**
+ * Configuration options for GitHub App Plugin
+ *
+ * Configure the plugin with your GitHub App credentials, callbacks,
+ * and optional settings for database, caching, and features.
+ *
+ * @example
+ * ```typescript
+ * githubAppPlugin({
+ *   // Required: GitHub App credentials
+ *   appId: process.env.GITHUB_APP_ID!,
+ *   privateKey: process.env.GITHUB_APP_PRIVATE_KEY_BASE64!, // Base64 encoded
+ *   webhookSecret: process.env.GITHUB_WEBHOOK_SECRET!,
+ *   clientId: process.env.GITHUB_APP_CLIENT_ID!,
+ *   clientSecret: process.env.GITHUB_APP_CLIENT_SECRET!,
+ *
+ *   // Required: Installation success callback
+ *   onInstallationSuccess: async ({ installationId, repositories }, ctx) => {
+ *     const userId = getUserId(ctx); // Your auth system
+ *     return { userId, redirectUrl: '/dashboard' };
+ *   },
+ *
+ *   // Optional: Handle webhook events
+ *   onWebhookEvent: async ({ event, payload }, ctx) => {
+ *     if (event === 'push') {
+ *       console.log('Push event received');
+ *     }
+ *   }
+ * })
+ * ```
+ */
+export interface GitHubAppPluginOptions {
+    // GitHub App Credentials (Required)
+
+    /**
+     * GitHub App ID
+     *
+     * Found in your GitHub App settings page.
+     *
+     * @example "123456"
+     */
+    appId: string;
+
+    /**
+     * GitHub App private key (Base64 encoded PEM format)
+     *
+     * Download the private key from GitHub App settings, then base64 encode it.
+     * This format plays nicely with environment variables (no line break issues).
+     * Supports both PKCS#1 and PKCS#8 formats (auto-detected after decoding).
+     *
+     * To encode your private key:
+     * ```bash
+     * # On macOS/Linux:
+     * base64 -i private-key.pem | tr -d '\n'
+     *
+     * # On Windows (PowerShell):
+     * [Convert]::ToBase64String([IO.File]::ReadAllBytes("private-key.pem"))
+     * ```
+     *
+     * @example "LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQpNSUlFcEFJQkFBS0..."
+     */
+    privateKey: string;
+
+    /**
+     * Webhook secret for signature validation
+     *
+     * Set in GitHub App settings. Used to validate webhook signatures
+     * using HMAC-SHA256. Generate a strong random string.
+     *
+     * @example "your-webhook-secret-here"
+     */
+    webhookSecret: string;
+
+    /**
+     * GitHub App client ID
+     *
+     * Found in your GitHub App settings page.
+     *
+     * @example "Iv1.abc123def456"
+     */
+    clientId: string;
+
+    /**
+     * GitHub App client secret
+     *
+     * Generate in GitHub App settings. Store in environment variables.
+     *
+     * @example "your-client-secret-here"
+     */
+    clientSecret: string;
+
+    // Optional Configuration
+
+    /**
+     * GitHub App slug (optional)
+     *
+     * Used in installation URL. Auto-detected if not provided.
+     * Found in your GitHub App settings page.
+     *
+     * @default Auto-detected from GitHub API
+     * @example "my-flink-app"
+     */
+    appSlug?: string;
+
+    /**
+     * GitHub API base URL (optional)
+     *
+     * Use for GitHub Enterprise Server installations.
+     * For github.com, use the default.
+     *
+     * @default "https://api.github.com"
+     * @example "https://github.mycompany.com/api/v3"
+     */
+    baseUrl?: string;
+
+    // Callbacks
+
+    /**
+     * Callback invoked after successful installation
+     *
+     * REQUIRED. Called when user completes GitHub App installation.
+     * Return userId to link installation and optional redirectUrl.
+     *
+     * @param params - Installation data from GitHub
+     * @param ctx - Flink context with repos and plugins
+     * @returns Object with userId and optional redirectUrl
+     *
+     * @throws Should not throw - errors are caught and passed to onInstallationError
+     *
+     * @example
+     * ```typescript
+     * async ({ installationId, repositories, account }, ctx) => {
+     *   const userId = ctx.auth?.tokenData?.userId || 'anonymous';
+     *   return {
+     *     userId,
+     *     redirectUrl: '/dashboard/github'
+     *   };
+     * }
+     * ```
+     */
+    onInstallationSuccess: (params: InstallationSuccessParams, ctx: any) => Promise<InstallationSuccessResponse>;
+
+    /**
+     * Callback invoked when installation fails (optional)
+     *
+     * Called when installation encounters an error (invalid state,
+     * expired session, GitHub API failure, etc.)
+     *
+     * @param params - Error information
+     * @returns Object with optional redirectUrl
+     *
+     * @example
+     * ```typescript
+     * async ({ error, installationId }) => {
+     *   console.error('Installation error:', error);
+     *   return {
+     *     redirectUrl: `/error?code=${error.code}`
+     *   };
+     * }
+     * ```
+     */
+    onInstallationError?: (params: InstallationErrorParams) => Promise<InstallationErrorResponse>;
+
+    /**
+     * Callback invoked when webhook event is received (optional)
+     *
+     * Called for each webhook event after signature validation.
+     * Process events asynchronously. Don't throw errors to prevent
+     * GitHub from retrying.
+     *
+     * @param params - Webhook event data
+     * @param ctx - Flink context with repos and plugins
+     *
+     * @example
+     * ```typescript
+     * async ({ event, action, payload, installationId }, ctx) => {
+     *   if (event === 'push') {
+     *     console.log('Push to', payload.repository.full_name);
+     *   }
+     *   if (event === 'pull_request' && action === 'opened') {
+     *     const client = await ctx.plugins.githubApp.getClient(installationId);
+     *     await client.createIssue(...);
+     *   }
+     * }
+     * ```
+     */
+    onWebhookEvent?: (params: WebhookEventParams, ctx: any) => Promise<void>;
+
+    // Database Configuration
+
+    /**
+     * MongoDB collection name for sessions (optional)
+     *
+     * Used for CSRF protection during installation flow.
+     *
+     * @default "github_app_sessions"
+     */
+    sessionsCollectionName?: string;
+
+    /**
+     * MongoDB collection name for installations (optional)
+     *
+     * Stores installation-to-user mappings and repository access info.
+     *
+     * @default "github_installations"
+     */
+    installationsCollectionName?: string;
+
+    /**
+     * MongoDB collection name for webhook events (optional)
+     *
+     * Only used if logWebhookEvents is enabled.
+     *
+     * @default "github_webhook_events"
+     */
+    webhookEventsCollectionName?: string;
+
+    // Cache Configuration
+
+    /**
+     * Installation token cache TTL in seconds (optional)
+     *
+     * How long to cache installation access tokens in memory.
+     * Tokens expire after 60 minutes. Set to 55 minutes (3300 seconds)
+     * for 5-minute safety margin.
+     *
+     * @default 3300 (55 minutes)
+     * @example 3000 (50 minutes)
+     */
+    tokenCacheTTL?: number;
+
+    /**
+     * Session TTL in seconds (optional)
+     *
+     * How long CSRF protection sessions are valid.
+     * Sessions are automatically deleted via MongoDB TTL index.
+     *
+     * @default 600 (10 minutes)
+     * @example 300 (5 minutes)
+     */
+    sessionTTL?: number;
+
+    // Feature Flags
+
+    /**
+     * Register HTTP handlers automatically (optional)
+     *
+     * If true, registers installation and webhook handlers.
+     * Set to false if you want to implement custom handlers.
+     *
+     * @default true
+     */
+    registerRoutes?: boolean;
+
+    /**
+     * Log webhook events to MongoDB (optional)
+     *
+     * If true, stores all webhook events in database for debugging.
+     * Useful for development but may consume storage in production.
+     *
+     * @default false
+     */
+    logWebhookEvents?: boolean;
+}