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

package/dist/services/GitHubAPIClient.js

@@ -0,0 +1,167 @@
+"use strict";
+/**
+ * GitHub API Client
+ *
+ * Wrapper for GitHub API calls with automatic token injection,
+ * retry logic, and error handling.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GitHubAPIClient = void 0;
+const error_utils_1 = require("../utils/error-utils");
+/**
+ * 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
+ */
+class GitHubAPIClient {
+    /**
+     * 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, authService, baseUrl = "https://api.github.com") {
+        this.maxRetries = 3;
+        this.retryDelayMs = 1000;
+        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(method, endpoint, data, retryCount = 0) {
+        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(method, endpoint, data, retryCount + 1);
+                }
+            }
+            // Handle non-OK responses
+            if (!response.ok) {
+                const errorBody = await response.text();
+                const error = 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;
+        }
+        catch (error) {
+            // 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(method, endpoint, data, retryCount + 1);
+            }
+            // Transform error to standardized format
+            throw (0, error_utils_1.handleGitHubAPIError)(error);
+        }
+    }
+    /**
+     * Get repositories accessible by this installation
+     *
+     * @returns Array of repositories
+     */
+    async getRepositories() {
+        const response = await this.request("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, repo) {
+        return this.request("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, repo, path) {
+        return this.request("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, repo, params) {
+        return this.request("POST", `/repos/${owner}/${repo}/issues`, params);
+    }
+    /**
+     * Sleep utility for retry delays
+     *
+     * @param ms - Milliseconds to sleep
+     * @private
+     */
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+    /**
+     * Determine if error should trigger retry
+     *
+     * @param error - Error to check
+     * @returns true if should retry
+     * @private
+     */
+    shouldRetry(error) {
+        // 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;
+    }
+}
+exports.GitHubAPIClient = GitHubAPIClient;

package/dist/services/GitHubAuthService.d.ts

@@ -0,0 +1,85 @@
+/**
+ * GitHub Authentication Service
+ *
+ * Handles GitHub App authentication including JWT generation and
+ * installation token exchange with automatic caching.
+ */
+/**
+ * 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 declare class GitHubAuthService {
+    private appId;
+    private privateKey;
+    private baseUrl;
+    private tokenCache;
+    private tokenCacheTTL;
+    /**
+     * 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, tokenCacheTTL?: number);
+    /**
+     * 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;
+    /**
+     * 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
+     */
+    getInstallationToken(installationId: number): Promise<string>;
+    /**
+     * 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 exchangeJWTForInstallationToken;
+    /**
+     * Clear token cache
+     *
+     * Removes all cached installation tokens. Useful for testing,
+     * forcing token refresh, or plugin shutdown.
+     */
+    clearTokenCache(): void;
+    /**
+     * Delete specific installation token from cache
+     *
+     * @param installationId - GitHub installation ID
+     */
+    deleteInstallationToken(installationId: number): void;
+}

package/dist/services/GitHubAuthService.js

@@ -0,0 +1,160 @@
+"use strict";
+/**
+ * GitHub Authentication Service
+ *
+ * Handles GitHub App authentication including JWT generation and
+ * installation token exchange with automatic caching.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GitHubAuthService = void 0;
+const jwt_utils_1 = require("../utils/jwt-utils");
+const token_cache_utils_1 = require("../utils/token-cache-utils");
+const error_utils_1 = require("../utils/error-utils");
+/**
+ * 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
+ */
+class GitHubAuthService {
+    /**
+     * 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, privateKeyBase64, baseUrl = "https://api.github.com", tokenCacheTTL = 3300) {
+        // Decode base64 private key to PEM format
+        let privateKey;
+        try {
+            privateKey = Buffer.from(privateKeyBase64, 'base64').toString('utf-8');
+        }
+        catch (error) {
+            throw (0, error_utils_1.createGitHubAppError)(error_utils_1.GitHubAppErrorCodes.INVALID_PRIVATE_KEY, `Failed to decode base64 private key: ${error.message}`);
+        }
+        // Validate private key format after decoding
+        (0, error_utils_1.validatePrivateKey)(privateKey);
+        this.appId = appId;
+        this.privateKey = privateKey;
+        this.baseUrl = baseUrl;
+        this.tokenCache = new token_cache_utils_1.TokenCache();
+        this.tokenCacheTTL = tokenCacheTTL;
+        // Test JWT signing on startup to catch key errors early
+        try {
+            this.generateAppJWT();
+        }
+        catch (error) {
+            throw (0, error_utils_1.createGitHubAppError)(error_utils_1.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() {
+        try {
+            return (0, jwt_utils_1.generateJWT)(this.appId, this.privateKey);
+        }
+        catch (error) {
+            throw (0, error_utils_1.createGitHubAppError)(error_utils_1.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) {
+        // 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) {
+            throw (0, error_utils_1.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
+     */
+    async exchangeJWTForInstallationToken(installationId, jwt) {
+        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 = new Error(`GitHub API request failed: ${response.statusText}`);
+            error.status = response.status;
+            error.message = errorBody;
+            throw error;
+        }
+        const data = await response.json();
+        return data;
+    }
+    /**
+     * Clear token cache
+     *
+     * Removes all cached installation tokens. Useful for testing,
+     * forcing token refresh, or plugin shutdown.
+     */
+    clearTokenCache() {
+        this.tokenCache.clearCache();
+    }
+    /**
+     * Delete specific installation token from cache
+     *
+     * @param installationId - GitHub installation ID
+     */
+    deleteInstallationToken(installationId) {
+        this.tokenCache.deleteToken(installationId);
+    }
+}
+exports.GitHubAuthService = GitHubAuthService;

package/dist/services/WebhookValidator.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Webhook Validator Service
+ *
+ * Validates GitHub webhook signatures and parses webhook payloads.
+ */
+/// <reference types="node" />
+/// <reference types="node" />
+/**
+ * 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 declare class WebhookValidator {
+    private secret;
+    /**
+     * Create Webhook Validator
+     *
+     * @param secret - Webhook secret configured in GitHub App
+     */
+    constructor(secret: string);
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+}

package/dist/services/WebhookValidator.js

@@ -0,0 +1,123 @@
+"use strict";
+/**
+ * Webhook Validator Service
+ *
+ * Validates GitHub webhook signatures and parses webhook payloads.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebhookValidator = void 0;
+const webhook_signature_utils_1 = require("../utils/webhook-signature-utils");
+const error_utils_1 = require("../utils/error-utils");
+/**
+ * Webhook Validator
+ *
+ * Handles webhook signature validation and payload parsing for GitHub webhooks.
+ * Uses constant-time comparison to prevent timing attacks.
+ */
+class WebhookValidator {
+    /**
+     * Create Webhook Validator
+     *
+     * @param secret - Webhook secret configured in GitHub App
+     */
+    constructor(secret) {
+        if (!secret || typeof secret !== "string") {
+            throw (0, error_utils_1.createGitHubAppError)(error_utils_1.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, signature) {
+        if (!rawBody || !signature) {
+            return false;
+        }
+        return (0, webhook_signature_utils_1.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) {
+        try {
+            const payload = JSON.parse(body);
+            return payload;
+        }
+        catch (error) {
+            throw (0, error_utils_1.createGitHubAppError)(error_utils_1.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) {
+        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) {
+        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, signature) {
+        // 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) {
+            return {
+                isValid: false,
+                error: error.message || "Failed to parse webhook payload",
+            };
+        }
+    }
+}
+exports.WebhookValidator = WebhookValidator;

package/dist/utils/error-utils.d.ts

@@ -0,0 +1,67 @@
+/**
+ * GitHub App Error Interface and Utilities
+ *
+ * Provides standardized error handling for GitHub App flows including
+ * user-friendly messages and error code mapping.
+ *
+ * Error codes use kebab-case for frontend translation consistency.
+ */
+/**
+ * Standardized GitHub App error structure
+ */
+export interface GitHubAppError {
+    /** Error code for programmatic handling (kebab-case) */
+    code: string;
+    /** User-friendly error message */
+    message: string;
+    /** Additional error details (for logging, not user display) */
+    details?: any;
+}
+/**
+ * GitHub App error codes
+ *
+ * All codes use kebab-case for frontend translation.
+ */
+export declare const GitHubAppErrorCodes: {
+    readonly INVALID_STATE: "invalid-state";
+    readonly SESSION_EXPIRED: "session-expired";
+    readonly INSTALLATION_NOT_FOUND: "installation-not-found";
+    readonly INVALID_PRIVATE_KEY: "invalid-private-key";
+    readonly JWT_SIGNING_FAILED: "jwt-signing-failed";
+    readonly TOKEN_EXCHANGE_FAILED: "token-exchange-failed";
+    readonly WEBHOOK_SIGNATURE_INVALID: "webhook-signature-invalid";
+    readonly WEBHOOK_PAYLOAD_INVALID: "webhook-payload-invalid";
+    readonly REPOSITORY_NOT_ACCESSIBLE: "repository-not-accessible";
+    readonly INSTALLATION_SUSPENDED: "installation-suspended";
+    readonly INSTALLATION_NOT_OWNED: "installation-not-owned";
+    readonly API_RATE_LIMIT: "api-rate-limit";
+    readonly NETWORK_ERROR: "network-error";
+    readonly SERVER_ERROR: "server-error";
+};
+/**
+ * Create a standardized GitHub App error
+ *
+ * @param code - Error code from GitHubAppErrorCodes
+ * @param message - User-friendly error message
+ * @param details - Additional error details for logging
+ * @returns Standardized GitHubAppError object
+ */
+export declare function createGitHubAppError(code: string, message: string, details?: any): GitHubAppError;
+/**
+ * Validate private key format
+ *
+ * @param privateKey - Private key to validate
+ * @returns true if valid
+ * @throws GitHubAppError if invalid
+ */
+export declare function validatePrivateKey(privateKey: string): boolean;
+/**
+ * Map GitHub API errors to standardized errors
+ *
+ * Converts GitHub API error responses into user-friendly
+ * standardized errors while sanitizing sensitive data.
+ *
+ * @param error - Error from GitHub API or internal error
+ * @returns Standardized GitHubAppError
+ */
+export declare function handleGitHubAPIError(error: any): GitHubAppError;