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

package/dist/utils/error-utils.js

@@ -0,0 +1,121 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleGitHubAPIError = exports.validatePrivateKey = exports.createGitHubAppError = exports.GitHubAppErrorCodes = void 0;
+/**
+ * GitHub App error codes
+ *
+ * All codes use kebab-case for frontend translation.
+ */
+exports.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",
+};
+/**
+ * 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
+ */
+function createGitHubAppError(code, message, details) {
+    return {
+        code,
+        message,
+        details,
+    };
+}
+exports.createGitHubAppError = createGitHubAppError;
+/**
+ * Validate private key format
+ *
+ * @param privateKey - Private key to validate
+ * @returns true if valid
+ * @throws GitHubAppError if invalid
+ */
+function validatePrivateKey(privateKey) {
+    if (!privateKey || typeof privateKey !== "string") {
+        throw createGitHubAppError(exports.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(exports.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;
+}
+exports.validatePrivateKey = validatePrivateKey;
+/**
+ * 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
+ */
+function handleGitHubAPIError(error) {
+    // Handle network errors
+    if (error.code === "ENOTFOUND" || error.code === "ECONNREFUSED" || error.code === "ETIMEDOUT") {
+        return createGitHubAppError(exports.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(exports.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(exports.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(exports.GitHubAppErrorCodes.INSTALLATION_NOT_FOUND, "GitHub App installation not found.", {
+            status: error.status,
+        });
+    }
+    // Handle unauthorized (invalid JWT or token)
+    if (error.status === 401) {
+        return createGitHubAppError(exports.GitHubAppErrorCodes.TOKEN_EXCHANGE_FAILED, "Failed to authenticate with GitHub. Please try reinstalling the app.", {
+            status: error.status,
+        });
+    }
+    // Generic error fallback
+    return createGitHubAppError(exports.GitHubAppErrorCodes.SERVER_ERROR, "An unexpected error occurred with GitHub API. Please try again.", {
+        originalError: error.message || "Unknown error",
+        status: error.status,
+    });
+}
+exports.handleGitHubAPIError = handleGitHubAPIError;

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

@@ -0,0 +1,35 @@
+/**
+ * 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.
+ */
+/**
+ * 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 declare function detectPEMFormat(privateKey: string): "pkcs1" | "pkcs8";
+/**
+ * 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 declare function generateJWT(appId: string, privateKey: string): string;

package/dist/utils/jwt-utils.js

@@ -0,0 +1,67 @@
+"use strict";
+/**
+ * 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.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateJWT = exports.detectPEMFormat = void 0;
+const jsonwebtoken_1 = __importDefault(require("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
+ */
+function detectPEMFormat(privateKey) {
+    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).");
+}
+exports.detectPEMFormat = detectPEMFormat;
+/**
+ * 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
+ */
+function generateJWT(appId, privateKey) {
+    // 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 jsonwebtoken_1.default.sign(payload, privateKey, { algorithm: "RS256" });
+    }
+    catch (error) {
+        throw new Error(`Failed to sign JWT: ${error.message}`);
+    }
+}
+exports.generateJWT = generateJWT;

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

@@ -0,0 +1,38 @@
+/**
+ * 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.
+ */
+/**
+ * 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 declare function generateState(): string;
+/**
+ * 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 declare function validateState(provided: string, stored: string): boolean;
+/**
+ * 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 declare function generateSessionId(): string;

package/dist/utils/state-utils.js

@@ -0,0 +1,74 @@
+"use strict";
+/**
+ * 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.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateSessionId = exports.validateState = exports.generateState = void 0;
+const crypto_1 = __importDefault(require("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)
+ */
+function generateState() {
+    return crypto_1.default.randomBytes(32).toString("hex");
+}
+exports.generateState = generateState;
+/**
+ * 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
+ */
+function validateState(provided, stored) {
+    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_1.default.timingSafeEqual(providedBuffer, storedBuffer);
+    }
+    catch (error) {
+        // If comparison fails for any reason, return false
+        return false;
+    }
+}
+exports.validateState = validateState;
+/**
+ * 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)
+ */
+function generateSessionId() {
+    return crypto_1.default.randomBytes(16).toString("hex");
+}
+exports.generateSessionId = generateSessionId;

package/dist/utils/token-cache-utils.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Token Cache Utilities
+ *
+ * In-memory cache for GitHub App installation access tokens.
+ * Tokens are cached with TTL to reduce GitHub API calls.
+ */
+/**
+ * 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 declare class TokenCache {
+    private cache;
+    constructor();
+    /**
+     * 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;
+    /**
+     * 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): void;
+    /**
+     * Clear all cached tokens
+     *
+     * Removes all tokens from the cache. Useful for testing,
+     * plugin shutdown, or when forcing token refresh.
+     */
+    clearCache(): void;
+    /**
+     * Remove specific installation token from cache
+     *
+     * @param installationId - GitHub installation ID
+     */
+    deleteToken(installationId: number): void;
+}

package/dist/utils/token-cache-utils.js

@@ -0,0 +1,74 @@
+"use strict";
+/**
+ * Token Cache Utilities
+ *
+ * In-memory cache for GitHub App installation access tokens.
+ * Tokens are cached with TTL to reduce GitHub API calls.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TokenCache = void 0;
+/**
+ * In-memory token cache
+ *
+ * Caches GitHub App installation access tokens with automatic expiration.
+ * Tokens are stored in memory only (never in database) for security.
+ */
+class TokenCache {
+    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) {
+        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, token, ttl = 3300) {
+        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() {
+        this.cache.clear();
+    }
+    /**
+     * Remove specific installation token from cache
+     *
+     * @param installationId - GitHub installation ID
+     */
+    deleteToken(installationId) {
+        this.cache.delete(installationId);
+    }
+}
+exports.TokenCache = TokenCache;

package/dist/utils/webhook-signature-utils.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Webhook Signature Validation Utilities
+ *
+ * Validates GitHub webhook signatures using HMAC-SHA256 with
+ * constant-time comparison to prevent timing attacks.
+ */
+/// <reference types="node" />
+/// <reference types="node" />
+/**
+ * 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 declare function validateWebhookSignature(payload: string | Buffer, signature: string, secret: string): boolean;

package/dist/utils/webhook-signature-utils.js

@@ -0,0 +1,57 @@
+"use strict";
+/**
+ * Webhook Signature Validation Utilities
+ *
+ * Validates GitHub webhook signatures using HMAC-SHA256 with
+ * constant-time comparison to prevent timing attacks.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateWebhookSignature = void 0;
+const crypto_1 = __importDefault(require("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
+ */
+function validateWebhookSignature(payload, signature, secret) {
+    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_1.default.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_1.default.timingSafeEqual(providedBuffer, expectedBuffer);
+    }
+    catch (error) {
+        // If comparison fails for any reason, return false
+        return false;
+    }
+}
+exports.validateWebhookSignature = validateWebhookSignature;