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

package/src/utils/error-utils.ts

@@ -0,0 +1,148 @@
+/**
+ * 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 const GitHubAppErrorCodes = {
+    // Installation Flow Errors
+    INVALID_STATE: "invalid-state",
+    SESSION_EXPIRED: "session-expired",
+    INSTALLATION_NOT_FOUND: "installation-not-found",
+
+    // Authentication Errors
+    INVALID_PRIVATE_KEY: "invalid-private-key",
+    JWT_SIGNING_FAILED: "jwt-signing-failed",
+    TOKEN_EXCHANGE_FAILED: "token-exchange-failed",
+
+    // Webhook Errors
+    WEBHOOK_SIGNATURE_INVALID: "webhook-signature-invalid",
+    WEBHOOK_PAYLOAD_INVALID: "webhook-payload-invalid",
+
+    // Access Errors
+    REPOSITORY_NOT_ACCESSIBLE: "repository-not-accessible",
+    INSTALLATION_SUSPENDED: "installation-suspended",
+    INSTALLATION_NOT_OWNED: "installation-not-owned",
+
+    // API Errors
+    API_RATE_LIMIT: "api-rate-limit",
+    NETWORK_ERROR: "network-error",
+    SERVER_ERROR: "server-error",
+} as const;
+
+/**
+ * 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 function createGitHubAppError(code: string, message: string, details?: any): GitHubAppError {
+    return {
+        code,
+        message,
+        details,
+    };
+}
+
+/**
+ * Validate private key format
+ *
+ * @param privateKey - Private key to validate
+ * @returns true if valid
+ * @throws GitHubAppError if invalid
+ */
+export function validatePrivateKey(privateKey: string): boolean {
+    if (!privateKey || typeof privateKey !== "string") {
+        throw createGitHubAppError(GitHubAppErrorCodes.INVALID_PRIVATE_KEY, "Private key is required and must be a string", {
+            provided: typeof privateKey,
+        });
+    }
+
+    if (!privateKey.includes("BEGIN") || !privateKey.includes("PRIVATE KEY")) {
+        throw createGitHubAppError(GitHubAppErrorCodes.INVALID_PRIVATE_KEY, "Private key must be in PEM format (PKCS#1 or PKCS#8)", {
+            hint: "Expected format: -----BEGIN RSA PRIVATE KEY----- or -----BEGIN PRIVATE KEY-----",
+        });
+    }
+
+    return true;
+}
+
+/**
+ * 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 function handleGitHubAPIError(error: any): GitHubAppError {
+    // Handle network errors
+    if (error.code === "ENOTFOUND" || error.code === "ECONNREFUSED" || error.code === "ETIMEDOUT") {
+        return createGitHubAppError(GitHubAppErrorCodes.NETWORK_ERROR, "Unable to connect to GitHub API. Please check your connection and try again.", {
+            networkError: error.code,
+        });
+    }
+
+    // Handle rate limit errors
+    if (error.status === 403 && error.message?.includes("rate limit")) {
+        return createGitHubAppError(GitHubAppErrorCodes.API_RATE_LIMIT, "GitHub API rate limit exceeded. Please try again later.", {
+            status: error.status,
+        });
+    }
+
+    // Handle installation suspended
+    if (error.status === 403 && error.message?.includes("suspended")) {
+        return createGitHubAppError(
+            GitHubAppErrorCodes.INSTALLATION_SUSPENDED,
+            "This GitHub App installation has been suspended. Please contact the repository owner.",
+            {
+                status: error.status,
+            }
+        );
+    }
+
+    // Handle installation not found
+    if (error.status === 404) {
+        return createGitHubAppError(GitHubAppErrorCodes.INSTALLATION_NOT_FOUND, "GitHub App installation not found.", {
+            status: error.status,
+        });
+    }
+
+    // Handle unauthorized (invalid JWT or token)
+    if (error.status === 401) {
+        return createGitHubAppError(GitHubAppErrorCodes.TOKEN_EXCHANGE_FAILED, "Failed to authenticate with GitHub. Please try reinstalling the app.", {
+            status: error.status,
+        });
+    }
+
+    // Generic error fallback
+    return createGitHubAppError(GitHubAppErrorCodes.SERVER_ERROR, "An unexpected error occurred with GitHub API. Please try again.", {
+        originalError: error.message || "Unknown error",
+        status: error.status,
+    });
+}

package/src/utils/jwt-utils.ts

@@ -0,0 +1,64 @@
+/**
+ * JWT Utilities for GitHub App Authentication
+ *
+ * Provides JWT generation with RS256 algorithm for GitHub App authentication.
+ * Supports both PKCS#1 and PKCS#8 private key formats.
+ */
+
+import jwt from "jsonwebtoken";
+
+/**
+ * Detect PEM format (PKCS#1 or PKCS#8)
+ *
+ * GitHub Apps can use either PKCS#1 (BEGIN RSA PRIVATE KEY) or
+ * PKCS#8 (BEGIN PRIVATE KEY) format. This function auto-detects
+ * the format for proper handling.
+ *
+ * @param privateKey - PEM-encoded private key
+ * @returns Format type: 'pkcs1' or 'pkcs8'
+ * @throws Error if format is not recognized
+ */
+export function detectPEMFormat(privateKey: string): "pkcs1" | "pkcs8" {
+    if (privateKey.includes("BEGIN RSA PRIVATE KEY")) {
+        return "pkcs1";
+    } else if (privateKey.includes("BEGIN PRIVATE KEY")) {
+        return "pkcs8";
+    }
+
+    throw new Error("Invalid PEM format. Expected PKCS#1 (BEGIN RSA PRIVATE KEY) or PKCS#8 (BEGIN PRIVATE KEY).");
+}
+
+/**
+ * Generate GitHub App JWT
+ *
+ * Creates a JWT signed with the GitHub App's private key using RS256 algorithm.
+ * The JWT is valid for 10 minutes (600 seconds) as per GitHub's requirements.
+ *
+ * JWT Payload:
+ * - iat: Issued at timestamp (now)
+ * - exp: Expiration timestamp (now + 600 seconds)
+ * - iss: GitHub App ID
+ *
+ * @param appId - GitHub App ID
+ * @param privateKey - PEM-encoded RSA private key (PKCS#1 or PKCS#8)
+ * @returns Signed JWT token
+ * @throws Error if key is invalid or signing fails
+ */
+export function generateJWT(appId: string, privateKey: string): string {
+    // Validate private key format
+    detectPEMFormat(privateKey);
+
+    const now = Math.floor(Date.now() / 1000);
+
+    const payload = {
+        iat: now,
+        exp: now + 600, // 10 minutes from now
+        iss: appId,
+    };
+
+    try {
+        return jwt.sign(payload, privateKey, { algorithm: "RS256" });
+    } catch (error: any) {
+        throw new Error(`Failed to sign JWT: ${error.message}`);
+    }
+}

package/src/utils/state-utils.ts

@@ -0,0 +1,72 @@
+/**
+ * State Parameter Utilities for CSRF Protection
+ *
+ * Provides cryptographically secure state parameter generation
+ * and constant-time comparison for GitHub App installation CSRF protection.
+ *
+ * Reuses pattern from OAuth Plugin for consistency.
+ */
+
+import crypto from "crypto";
+
+/**
+ * Generate a cryptographically secure state parameter
+ *
+ * Creates a 32-byte random state parameter for CSRF protection
+ * in GitHub App installation flows. This state is stored in the session
+ * and must match when GitHub redirects back after installation.
+ *
+ * @returns Hex-encoded 32-byte random string (64 characters)
+ */
+export function generateState(): string {
+    return crypto.randomBytes(32).toString("hex");
+}
+
+/**
+ * Validate state parameter using constant-time comparison
+ *
+ * Compares the provided state with the stored state using a
+ * constant-time algorithm to prevent timing attacks.
+ *
+ * @param provided - State parameter from GitHub callback
+ * @param stored - State parameter stored in session
+ * @returns true if states match, false otherwise
+ */
+export function validateState(provided: string, stored: string): boolean {
+    if (!provided || !stored) {
+        return false;
+    }
+
+    // Ensure both strings are the same length to prevent timing attacks
+    if (provided.length !== stored.length) {
+        return false;
+    }
+
+    try {
+        // Use Node.js crypto.timingSafeEqual for constant-time comparison
+        const providedBuffer = Buffer.from(provided, "utf8");
+        const storedBuffer = Buffer.from(stored, "utf8");
+
+        // Both buffers must be same length for timingSafeEqual
+        if (providedBuffer.length !== storedBuffer.length) {
+            return false;
+        }
+
+        return crypto.timingSafeEqual(providedBuffer, storedBuffer);
+    } catch (error) {
+        // If comparison fails for any reason, return false
+        return false;
+    }
+}
+
+/**
+ * Generate a session ID for installation flow tracking
+ *
+ * Creates a unique session identifier for correlating installation
+ * initiation with callback.
+ *
+ * @returns Hex-encoded 16-byte random string (32 characters)
+ */
+export function generateSessionId(): string {
+    return crypto.randomBytes(16).toString("hex");
+}

package/src/utils/token-cache-utils.ts

@@ -0,0 +1,89 @@
+/**
+ * Token Cache Utilities
+ *
+ * In-memory cache for GitHub App installation access tokens.
+ * Tokens are cached with TTL to reduce GitHub API calls.
+ */
+
+/**
+ * Cache entry structure
+ */
+interface CacheEntry {
+    token: string;
+    expiresAt: number; // Unix timestamp in milliseconds
+}
+
+/**
+ * In-memory token cache
+ *
+ * Caches GitHub App installation access tokens with automatic expiration.
+ * Tokens are stored in memory only (never in database) for security.
+ */
+export class TokenCache {
+    private cache: Map<number, CacheEntry>;
+
+    constructor() {
+        this.cache = new Map();
+    }
+
+    /**
+     * Get cached token for an installation
+     *
+     * Returns the cached token if it exists and hasn't expired.
+     * Returns null if token is not cached or has expired.
+     *
+     * @param installationId - GitHub installation ID
+     * @returns Cached token or null if not found/expired
+     */
+    getToken(installationId: number): string | null {
+        const entry = this.cache.get(installationId);
+
+        if (!entry) {
+            return null;
+        }
+
+        // Check if token has expired
+        if (Date.now() >= entry.expiresAt) {
+            // Remove expired token from cache
+            this.cache.delete(installationId);
+            return null;
+        }
+
+        return entry.token;
+    }
+
+    /**
+     * Store token in cache with TTL
+     *
+     * @param installationId - GitHub installation ID
+     * @param token - Installation access token
+     * @param ttl - Time to live in seconds (default: 3300 = 55 minutes)
+     */
+    setToken(installationId: number, token: string, ttl: number = 3300): void {
+        const expiresAt = Date.now() + ttl * 1000; // Convert seconds to milliseconds
+
+        this.cache.set(installationId, {
+            token,
+            expiresAt,
+        });
+    }
+
+    /**
+     * Clear all cached tokens
+     *
+     * Removes all tokens from the cache. Useful for testing,
+     * plugin shutdown, or when forcing token refresh.
+     */
+    clearCache(): void {
+        this.cache.clear();
+    }
+
+    /**
+     * Remove specific installation token from cache
+     *
+     * @param installationId - GitHub installation ID
+     */
+    deleteToken(installationId: number): void {
+        this.cache.delete(installationId);
+    }
+}

package/src/utils/webhook-signature-utils.ts

@@ -0,0 +1,57 @@
+/**
+ * Webhook Signature Validation Utilities
+ *
+ * Validates GitHub webhook signatures using HMAC-SHA256 with
+ * constant-time comparison to prevent timing attacks.
+ */
+
+import crypto from "crypto";
+
+/**
+ * Validate GitHub webhook signature
+ *
+ * GitHub signs webhook payloads with HMAC-SHA256 using the webhook secret.
+ * The signature is sent in the X-Hub-Signature-256 header as "sha256=<hex>".
+ *
+ * This function uses constant-time comparison to prevent timing attacks.
+ *
+ * @param payload - Raw request body (string or Buffer)
+ * @param signature - X-Hub-Signature-256 header value
+ * @param secret - Webhook secret configured in GitHub App
+ * @returns true if signature is valid, false otherwise
+ */
+export function validateWebhookSignature(payload: string | Buffer, signature: string, secret: string): boolean {
+    if (!payload || !signature || !secret) {
+        return false;
+    }
+
+    // Ensure signature has correct format (sha256=<hex>)
+    if (!signature.startsWith("sha256=")) {
+        return false;
+    }
+
+    try {
+        // Extract hex signature (remove "sha256=" prefix)
+        const providedSignature = signature.substring(7);
+
+        // Compute expected signature
+        const hmac = crypto.createHmac("sha256", secret);
+        const payloadBuffer = typeof payload === "string" ? Buffer.from(payload, "utf8") : payload;
+        hmac.update(payloadBuffer);
+        const expectedSignature = hmac.digest("hex");
+
+        // Use constant-time comparison to prevent timing attacks
+        const providedBuffer = Buffer.from(providedSignature, "hex");
+        const expectedBuffer = Buffer.from(expectedSignature, "hex");
+
+        // Both buffers must be same length for timingSafeEqual
+        if (providedBuffer.length !== expectedBuffer.length) {
+            return false;
+        }
+
+        return crypto.timingSafeEqual(providedBuffer, expectedBuffer);
+    } catch (error) {
+        // If comparison fails for any reason, return false
+        return false;
+    }
+}

package/tsconfig.dist.json

@@ -0,0 +1,4 @@
+{
+  "extends": "./tsconfig",
+  "exclude": ["spec/**/*.ts"]
+}

package/tsconfig.json

@@ -0,0 +1,24 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "lib": ["ES2020"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "strict": true,
+    "forceConsistentCasingInFileNames": true,
+    "module": "commonjs",
+    "moduleResolution": "node",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": false,
+    "declaration": true,
+    "experimentalDecorators": true,
+    "checkJs": true,
+    "outDir": "dist",
+    "typeRoots": ["./node_modules/@types"]
+  },
+  "include": ["./src/*", "./spec/*"],
+  "exclude": ["./node_modules/*"]
+}