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

package/src/schemas/GitHubInstallation.ts

@@ -0,0 +1,28 @@
+/**
+ * GitHub App installation data linked to a user.
+ * Stores which repositories the user granted access to and installation metadata.
+ */
+export default interface GitHubInstallation {
+    _id?: string;
+    userId: string;
+    installationId: number;
+    accountId: number;
+    accountLogin: string;
+    accountType: 'User' | 'Organization';
+    avatarUrl?: string;
+    repositories: {
+        id: number;
+        name: string;
+        fullName: string;
+        private: boolean;
+    }[];
+    permissions: Record<string, string>;
+    events: string[];
+    suspendedAt?: Date;
+    suspendedBy?: {
+        id: number;
+        login: string;
+    };
+    createdAt: Date;
+    updatedAt: Date;
+}

package/src/schemas/InstallationCallbackRequest.ts

@@ -0,0 +1,10 @@
+/**
+ * Query parameters received from GitHub after app installation.
+ */
+export default interface InstallationCallbackRequest {
+    installation_id: string;
+    setup_action: 'install' | 'update' | 'request';
+    state: string;
+    code?: string;
+    [key: string]: string | undefined;
+}

package/src/schemas/WebhookEvent.ts

@@ -0,0 +1,16 @@
+/**
+ * Optional webhook event logging for debugging and auditing.
+ * Only stored if logWebhookEvents config option is enabled.
+ */
+export default interface WebhookEvent {
+    _id?: string;
+    installationId: number;
+    event: string;
+    action?: string;
+    deliveryId: string;
+    payload: Record<string, any>;
+    processed: boolean;
+    processedAt?: Date;
+    error?: string;
+    createdAt: Date;
+}

package/src/schemas/WebhookPayload.ts

@@ -0,0 +1,35 @@
+/**
+ * Generic webhook event payload structure from GitHub.
+ * Contains common fields; specific events may have additional fields.
+ */
+export default interface WebhookPayload {
+    action?: string;
+    installation?: {
+        id: number;
+        account: {
+            id: number;
+            login: string;
+            type: 'User' | 'Organization';
+            avatar_url?: string;
+        };
+    };
+    repositories?: {
+        id: number;
+        name: string;
+        full_name: string;
+        private: boolean;
+    }[];
+    repository?: {
+        id: number;
+        name: string;
+        full_name: string;
+        private: boolean;
+        owner: {
+            login: string;
+        };
+    };
+    sender?: {
+        id: number;
+        login: string;
+    };
+}

package/src/services/GitHubAPIClient.ts

@@ -0,0 +1,244 @@
+/**
+ * GitHub API Client
+ *
+ * Wrapper for GitHub API calls with automatic token injection,
+ * retry logic, and error handling.
+ */
+
+import { GitHubAuthService } from "./GitHubAuthService";
+import { createGitHubAppError, GitHubAppErrorCodes, handleGitHubAPIError } from "../utils/error-utils";
+
+/**
+ * Repository data structure
+ */
+export interface Repository {
+    id: number;
+    name: string;
+    full_name: string;
+    private: boolean;
+    owner: {
+        login: string;
+        id: number;
+    };
+    html_url: string;
+    description?: string;
+}
+
+/**
+ * Content data structure
+ */
+export interface Content {
+    name: string;
+    path: string;
+    sha: string;
+    size: number;
+    url: string;
+    html_url: string;
+    git_url: string;
+    download_url?: string;
+    type: "file" | "dir" | "symlink" | "submodule";
+}
+
+/**
+ * Issue data structure
+ */
+export interface Issue {
+    id: number;
+    number: number;
+    title: string;
+    body?: string;
+    state: "open" | "closed";
+    html_url: string;
+    user: {
+        login: string;
+        id: number;
+    };
+    created_at: string;
+    updated_at: string;
+}
+
+/**
+ * Create issue parameters
+ */
+export interface CreateIssueParams {
+    title: string;
+    body?: string;
+    assignees?: string[];
+    labels?: string[];
+}
+
+/**
+ * GitHub API Client
+ *
+ * Provides wrapper methods for common GitHub API operations with:
+ * - Automatic token injection
+ * - Retry logic with exponential backoff for rate limits
+ * - Error handling and transformation
+ */
+export class GitHubAPIClient {
+    private installationId: number;
+    private authService: GitHubAuthService;
+    private baseUrl: string;
+    private maxRetries: number = 3;
+    private retryDelayMs: number = 1000;
+
+    /**
+     * Create GitHub API Client
+     *
+     * @param installationId - GitHub installation ID
+     * @param authService - GitHub Auth Service instance
+     * @param baseUrl - GitHub API base URL (default: https://api.github.com)
+     */
+    constructor(installationId: number, authService: GitHubAuthService, baseUrl: string = "https://api.github.com") {
+        this.installationId = installationId;
+        this.authService = authService;
+        this.baseUrl = baseUrl;
+    }
+
+    /**
+     * Generic API request method with automatic token injection
+     *
+     * @param method - HTTP method (GET, POST, PUT, DELETE)
+     * @param endpoint - API endpoint (e.g., "/repos/owner/repo")
+     * @param data - Request body data (for POST, PUT)
+     * @param retryCount - Current retry attempt (internal use)
+     * @returns Response data
+     * @throws Error if request fails after retries
+     */
+    async request<T = any>(method: "GET" | "POST" | "PUT" | "DELETE", endpoint: string, data?: any, retryCount: number = 0): Promise<T> {
+        try {
+            // Get installation token (cached or fresh)
+            const token = await this.authService.getInstallationToken(this.installationId);
+
+            // Build full URL
+            const url = endpoint.startsWith("http") ? endpoint : `${this.baseUrl}${endpoint}`;
+
+            // Make request
+            const response = await fetch(url, {
+                method,
+                headers: {
+                    Authorization: `Bearer ${token}`,
+                    Accept: "application/vnd.github+json",
+                    "User-Agent": "Flink-GitHub-App-Plugin",
+                    ...(data ? { "Content-Type": "application/json" } : {}),
+                },
+                ...(data ? { body: JSON.stringify(data) } : {}),
+            });
+
+            // Handle rate limiting with retry
+            if (response.status === 403) {
+                const rateLimitRemaining = response.headers.get("x-ratelimit-remaining");
+                if (rateLimitRemaining === "0" && retryCount < this.maxRetries) {
+                    // Calculate exponential backoff delay
+                    const delay = this.retryDelayMs * Math.pow(2, retryCount);
+                    await this.sleep(delay);
+                    return this.request<T>(method, endpoint, data, retryCount + 1);
+                }
+            }
+
+            // Handle non-OK responses
+            if (!response.ok) {
+                const errorBody = await response.text();
+                const error: any = new Error(`GitHub API request failed: ${response.statusText}`);
+                error.status = response.status;
+                error.message = errorBody;
+                throw error;
+            }
+
+            // Parse and return response
+            const responseData = await response.json();
+            return responseData as T;
+        } catch (error: any) {
+            // If we can retry, do so
+            if (this.shouldRetry(error) && retryCount < this.maxRetries) {
+                const delay = this.retryDelayMs * Math.pow(2, retryCount);
+                await this.sleep(delay);
+                return this.request<T>(method, endpoint, data, retryCount + 1);
+            }
+
+            // Transform error to standardized format
+            throw handleGitHubAPIError(error);
+        }
+    }
+
+    /**
+     * Get repositories accessible by this installation
+     *
+     * @returns Array of repositories
+     */
+    async getRepositories(): Promise<Repository[]> {
+        const response = await this.request<{ repositories: Repository[] }>("GET", "/installation/repositories");
+        return response.repositories;
+    }
+
+    /**
+     * Get repository details
+     *
+     * @param owner - Repository owner (user or org)
+     * @param repo - Repository name
+     * @returns Repository details
+     */
+    async getRepository(owner: string, repo: string): Promise<Repository> {
+        return this.request<Repository>("GET", `/repos/${owner}/${repo}`);
+    }
+
+    /**
+     * Get repository contents
+     *
+     * @param owner - Repository owner
+     * @param repo - Repository name
+     * @param path - File or directory path
+     * @returns Content array (for directories) or single content (for files)
+     */
+    async getContents(owner: string, repo: string, path: string): Promise<Content | Content[]> {
+        return this.request<Content | Content[]>("GET", `/repos/${owner}/${repo}/contents/${path}`);
+    }
+
+    /**
+     * Create an issue
+     *
+     * @param owner - Repository owner
+     * @param repo - Repository name
+     * @param params - Issue creation parameters
+     * @returns Created issue
+     */
+    async createIssue(owner: string, repo: string, params: CreateIssueParams): Promise<Issue> {
+        return this.request<Issue>("POST", `/repos/${owner}/${repo}/issues`, params);
+    }
+
+    /**
+     * Sleep utility for retry delays
+     *
+     * @param ms - Milliseconds to sleep
+     * @private
+     */
+    private sleep(ms: number): Promise<void> {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+
+    /**
+     * Determine if error should trigger retry
+     *
+     * @param error - Error to check
+     * @returns true if should retry
+     * @private
+     */
+    private shouldRetry(error: any): boolean {
+        // Retry on network errors
+        if (error.code === "ENOTFOUND" || error.code === "ECONNREFUSED" || error.code === "ETIMEDOUT") {
+            return true;
+        }
+
+        // Retry on rate limit (403)
+        if (error.status === 403) {
+            return true;
+        }
+
+        // Retry on server errors (500, 502, 503, 504)
+        if (error.status >= 500 && error.status < 600) {
+            return true;
+        }
+
+        return false;
+    }
+}

package/src/services/GitHubAuthService.ts

@@ -0,0 +1,188 @@
+/**
+ * GitHub Authentication Service
+ *
+ * Handles GitHub App authentication including JWT generation and
+ * installation token exchange with automatic caching.
+ */
+
+import { generateJWT } from "../utils/jwt-utils";
+import { TokenCache } from "../utils/token-cache-utils";
+import { validatePrivateKey, createGitHubAppError, GitHubAppErrorCodes, handleGitHubAPIError } from "../utils/error-utils";
+
+/**
+ * Installation token response from GitHub API
+ */
+interface InstallationTokenResponse {
+    token: string;
+    expires_at: string;
+    permissions?: Record<string, string>;
+    repository_selection?: string;
+}
+
+/**
+ * GitHub Authentication Service
+ *
+ * Manages GitHub App authentication flow:
+ * 1. Generate GitHub App JWT using private key
+ * 2. Exchange JWT for installation access token
+ * 3. Cache installation tokens with automatic expiration
+ * 4. Automatically refresh expired tokens
+ */
+export class GitHubAuthService {
+    private appId: string;
+    private privateKey: string;
+    private baseUrl: string;
+    private tokenCache: TokenCache;
+    private tokenCacheTTL: number;
+
+    /**
+     * Create GitHub Auth Service
+     *
+     * @param appId - GitHub App ID
+     * @param privateKeyBase64 - Base64 encoded RSA private key (will be decoded to PEM format, PKCS#1 or PKCS#8)
+     * @param baseUrl - GitHub API base URL (default: https://api.github.com)
+     * @param tokenCacheTTL - Token cache TTL in seconds (default: 3300 = 55 minutes)
+     * @throws Error if private key is invalid or cannot be decoded
+     */
+    constructor(appId: string, privateKeyBase64: string, baseUrl: string = "https://api.github.com", tokenCacheTTL: number = 3300) {
+        // Decode base64 private key to PEM format
+        let privateKey: string;
+        try {
+            privateKey = Buffer.from(privateKeyBase64, 'base64').toString('utf-8');
+        } catch (error: any) {
+            throw createGitHubAppError(
+                GitHubAppErrorCodes.INVALID_PRIVATE_KEY,
+                `Failed to decode base64 private key: ${error.message}`
+            );
+        }
+
+        // Validate private key format after decoding
+        validatePrivateKey(privateKey);
+
+        this.appId = appId;
+        this.privateKey = privateKey;
+        this.baseUrl = baseUrl;
+        this.tokenCache = new TokenCache();
+        this.tokenCacheTTL = tokenCacheTTL;
+
+        // Test JWT signing on startup to catch key errors early
+        try {
+            this.generateAppJWT();
+        } catch (error: any) {
+            throw createGitHubAppError(GitHubAppErrorCodes.JWT_SIGNING_FAILED, "Failed to sign JWT with provided private key. Please verify the key format.", {
+                error: error.message,
+            });
+        }
+    }
+
+    /**
+     * Generate GitHub App JWT
+     *
+     * Creates a JWT signed with the app's private key. The JWT is valid
+     * for 10 minutes and is used to authenticate as the GitHub App itself.
+     *
+     * @returns Signed JWT token
+     * @throws Error if JWT signing fails
+     */
+    generateAppJWT(): string {
+        try {
+            return generateJWT(this.appId, this.privateKey);
+        } catch (error: any) {
+            throw createGitHubAppError(GitHubAppErrorCodes.JWT_SIGNING_FAILED, "Failed to generate GitHub App JWT", { error: error.message });
+        }
+    }
+
+    /**
+     * Get installation access token
+     *
+     * Retrieves an installation access token for the specified installation.
+     * Tokens are automatically cached and refreshed when expired.
+     *
+     * Flow:
+     * 1. Check cache for valid token
+     * 2. If not cached or expired, generate GitHub App JWT
+     * 3. Exchange JWT for installation token via GitHub API
+     * 4. Cache the new token
+     * 5. Return token
+     *
+     * @param installationId - GitHub installation ID
+     * @returns Installation access token
+     * @throws Error if token exchange fails
+     */
+    async getInstallationToken(installationId: number): Promise<string> {
+        // Check cache first
+        const cachedToken = this.tokenCache.getToken(installationId);
+        if (cachedToken) {
+            return cachedToken;
+        }
+
+        // Generate GitHub App JWT
+        const jwt = this.generateAppJWT();
+
+        // Exchange JWT for installation token
+        try {
+            const response = await this.exchangeJWTForInstallationToken(installationId, jwt);
+
+            // Cache the token
+            this.tokenCache.setToken(installationId, response.token, this.tokenCacheTTL);
+
+            return response.token;
+        } catch (error: any) {
+            throw handleGitHubAPIError(error);
+        }
+    }
+
+    /**
+     * Exchange GitHub App JWT for installation access token
+     *
+     * Calls GitHub API to exchange the app JWT for an installation-specific
+     * access token that can be used to make API calls on behalf of the installation.
+     *
+     * @param installationId - GitHub installation ID
+     * @param jwt - GitHub App JWT
+     * @returns Installation token response
+     * @private
+     */
+    private async exchangeJWTForInstallationToken(installationId: number, jwt: string): Promise<InstallationTokenResponse> {
+        const url = `${this.baseUrl}/app/installations/${installationId}/access_tokens`;
+
+        const response = await fetch(url, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${jwt}`,
+                Accept: "application/vnd.github+json",
+                "User-Agent": "Flink-GitHub-App-Plugin",
+            },
+        });
+
+        if (!response.ok) {
+            const errorBody = await response.text();
+            const error: any = new Error(`GitHub API request failed: ${response.statusText}`);
+            error.status = response.status;
+            error.message = errorBody;
+            throw error;
+        }
+
+        const data = await response.json();
+        return data as InstallationTokenResponse;
+    }
+
+    /**
+     * Clear token cache
+     *
+     * Removes all cached installation tokens. Useful for testing,
+     * forcing token refresh, or plugin shutdown.
+     */
+    clearTokenCache(): void {
+        this.tokenCache.clearCache();
+    }
+
+    /**
+     * Delete specific installation token from cache
+     *
+     * @param installationId - GitHub installation ID
+     */
+    deleteInstallationToken(installationId: number): void {
+        this.tokenCache.deleteToken(installationId);
+    }
+}

package/src/services/WebhookValidator.ts

@@ -0,0 +1,159 @@
+/**
+ * Webhook Validator Service
+ *
+ * Validates GitHub webhook signatures and parses webhook payloads.
+ */
+
+import { validateWebhookSignature } from "../utils/webhook-signature-utils";
+import { createGitHubAppError, GitHubAppErrorCodes } from "../utils/error-utils";
+
+/**
+ * Parsed webhook payload data
+ */
+export interface WebhookPayload {
+    action?: string;
+    installation?: {
+        id: number;
+        [key: string]: any;
+    };
+    [key: string]: any;
+}
+
+/**
+ * Webhook validation result
+ */
+export interface WebhookValidationResult {
+    isValid: boolean;
+    payload?: WebhookPayload;
+    error?: string;
+}
+
+/**
+ * Webhook Validator
+ *
+ * Handles webhook signature validation and payload parsing for GitHub webhooks.
+ * Uses constant-time comparison to prevent timing attacks.
+ */
+export class WebhookValidator {
+    private secret: string;
+
+    /**
+     * Create Webhook Validator
+     *
+     * @param secret - Webhook secret configured in GitHub App
+     */
+    constructor(secret: string) {
+        if (!secret || typeof secret !== "string") {
+            throw createGitHubAppError(
+                GitHubAppErrorCodes.WEBHOOK_SIGNATURE_INVALID,
+                "Webhook secret is required and must be a string"
+            );
+        }
+
+        this.secret = secret;
+    }
+
+    /**
+     * Validate webhook signature
+     *
+     * Verifies the X-Hub-Signature-256 header using HMAC-SHA256 with
+     * constant-time comparison to prevent timing attacks.
+     *
+     * @param rawBody - Raw request body (string or Buffer)
+     * @param signature - X-Hub-Signature-256 header value
+     * @returns true if signature is valid, false otherwise
+     */
+    validateSignature(rawBody: string | Buffer, signature: string): boolean {
+        if (!rawBody || !signature) {
+            return false;
+        }
+
+        return validateWebhookSignature(rawBody, signature, this.secret);
+    }
+
+    /**
+     * Parse webhook payload
+     *
+     * Parses the JSON payload from a webhook request.
+     * Extracts common fields like action and installationId.
+     *
+     * @param body - Raw request body (string)
+     * @returns Parsed webhook payload
+     * @throws Error if payload is malformed JSON
+     */
+    parsePayload(body: string): WebhookPayload {
+        try {
+            const payload = JSON.parse(body);
+            return payload as WebhookPayload;
+        } catch (error: any) {
+            throw createGitHubAppError(
+                GitHubAppErrorCodes.WEBHOOK_PAYLOAD_INVALID,
+                "Failed to parse webhook payload as JSON",
+                { error: error.message }
+            );
+        }
+    }
+
+    /**
+     * Extract event type from payload
+     *
+     * Gets the event type from the parsed payload.
+     * For installation webhooks, this is typically found in the 'action' field.
+     *
+     * @param payload - Parsed webhook payload
+     * @returns Event type (e.g., 'created', 'deleted')
+     */
+    extractEventType(payload: WebhookPayload): string | undefined {
+        return payload.action;
+    }
+
+    /**
+     * Extract installation ID from payload
+     *
+     * Gets the installation ID from the parsed payload.
+     *
+     * @param payload - Parsed webhook payload
+     * @returns Installation ID, or undefined if not present
+     */
+    extractInstallationId(payload: WebhookPayload): number | undefined {
+        return payload.installation?.id;
+    }
+
+    /**
+     * Validate and parse webhook in one step
+     *
+     * Convenience method that validates signature and parses payload
+     * in a single call.
+     *
+     * @param rawBody - Raw request body
+     * @param signature - X-Hub-Signature-256 header
+     * @returns Validation result with parsed payload if valid
+     */
+    validateAndParse(rawBody: string | Buffer, signature: string): WebhookValidationResult {
+        // Validate signature first
+        const isValid = this.validateSignature(rawBody, signature);
+
+        if (!isValid) {
+            return {
+                isValid: false,
+                error: "Invalid webhook signature",
+            };
+        }
+
+        // Parse payload
+        try {
+            const bodyString = typeof rawBody === "string" ? rawBody : rawBody.toString("utf8");
+            const payload = this.parsePayload(bodyString);
+
+            return {
+                isValid: true,
+                payload,
+            };
+        } catch (error: any) {
+            return {
+                isValid: false,
+                error: error.message || "Failed to parse webhook payload",
+            };
+        }
+    }
+}