@flink-app/github-app-plugin 0.12.1-alpha.45 → 0.12.1-alpha.47

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@flink-app/github-app-plugin",
-    "version": "0.12.1-alpha.45",
+    "version": "0.12.1-alpha.47",
     "description": "Flink plugin for GitHub App integration with installation management and webhook handling",
     "scripts": {
         "test": "node --preserve-symlinks -r ts-node/register -- node_modules/jasmine/bin/jasmine --config=./spec/support/jasmine.json",
@@ -23,8 +23,8 @@
         "jsonwebtoken": "^9.0.2"
     },
     "devDependencies": {
-        "@flink-app/flink": "^0.12.1-alpha.45",
-        "@flink-app/test-utils": "^0.12.1-alpha.45",
+        "@flink-app/flink": "^0.12.1-alpha.47",
+        "@flink-app/test-utils": "^0.12.1-alpha.47",
         "@types/jasmine": "^3.7.1",
         "@types/jsonwebtoken": "^9.0.5",
         "@types/node": "22.13.10",
@@ -37,5 +37,5 @@
         "tsc-watch": "^4.2.9",
         "typescript": "5.4.5"
     },
-    "gitHead": "af426a157217c110ac9c7beb48e2e746968bec33"
+    "gitHead": "a98a0af7f11e4a97f68da4d0d67677df7d2a2749"
 }

package/dist/handlers/InitiateInstallation.d.ts

@@ -1,32 +0,0 @@
-/**
- * GitHub App Installation Initiation Handler
- *
- * Initiates the GitHub App installation flow by:
- * 1. Generating a cryptographically secure state parameter for CSRF protection
- * 2. Creating an installation session to track the flow
- * 3. Building GitHub's installation URL with state parameter
- * 4. Redirecting the user to GitHub for app installation
- *
- * Route: GET /github-app/install?user_id={optional_user_id}
- */
-import { GetHandler, RouteProps } from "@flink-app/flink";
-/**
- * Query parameters for the handler
- */
-interface QueryParams {
-    user_id?: string;
-    [key: string]: any;
-}
-/**
- * Route configuration
- * Registered programmatically by the plugin if registerRoutes is enabled
- */
-export declare const Route: RouteProps;
-/**
- * GitHub App Installation Initiation Handler
- *
- * Starts the installation flow by generating CSRF state, creating a session,
- * and redirecting to GitHub's app installation page.
- */
-declare const InitiateInstallation: GetHandler<any, any, any, QueryParams>;
-export default InitiateInstallation;

package/dist/handlers/InitiateInstallation.js

@@ -1,66 +0,0 @@
-"use strict";
-/**
- * GitHub App Installation Initiation Handler
- *
- * Initiates the GitHub App installation flow by:
- * 1. Generating a cryptographically secure state parameter for CSRF protection
- * 2. Creating an installation session to track the flow
- * 3. Building GitHub's installation URL with state parameter
- * 4. Redirecting the user to GitHub for app installation
- *
- * Route: GET /github-app/install?user_id={optional_user_id}
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Route = void 0;
-const flink_1 = require("@flink-app/flink");
-const state_utils_1 = require("../utils/state-utils");
-/**
- * Route configuration
- * Registered programmatically by the plugin if registerRoutes is enabled
- */
-exports.Route = {
-    path: "/github-app/install",
-    method: flink_1.HttpMethod.get,
-};
-/**
- * GitHub App Installation Initiation Handler
- *
- * Starts the installation flow by generating CSRF state, creating a session,
- * and redirecting to GitHub's app installation page.
- */
-const InitiateInstallation = async ({ ctx, req }) => {
-    const { user_id } = req.query;
-    try {
-        // Get plugin options
-        const { options } = ctx.plugins.githubApp;
-        // Validate that appSlug is configured
-        if (!options.appSlug) {
-            return (0, flink_1.badRequest)("GitHub App slug is not configured. Please set appSlug in plugin options.");
-        }
-        // Generate cryptographically secure state and session ID
-        const state = (0, state_utils_1.generateState)();
-        const sessionId = (0, state_utils_1.generateSessionId)();
-        // Store session for state validation in callback
-        await ctx.repos.githubAppSessionRepo.create({
-            sessionId,
-            state,
-            userId: user_id,
-            createdAt: new Date(),
-        });
-        // Build GitHub installation URL
-        const installationUrl = `https://github.com/apps/${options.appSlug}/installations/new?state=${state}`;
-        // Redirect user to GitHub's app installation page
-        return {
-            status: 302,
-            headers: {
-                Location: installationUrl,
-            },
-            data: {},
-        };
-    }
-    catch (error) {
-        // Handle unexpected errors
-        return (0, flink_1.internalServerError)(error.message || "Failed to initiate GitHub App installation");
-    }
-};
-exports.default = InitiateInstallation;

package/dist/handlers/InstallationCallback.d.ts

@@ -1,36 +0,0 @@
-/**
- * GitHub App Installation Callback Handler
- *
- * Handles the callback from GitHub after app installation by:
- * 1. Validating the state parameter to prevent CSRF attacks
- * 2. Fetching installation details from GitHub API
- * 3. Calling the onInstallationSuccess callback to link installation to user
- * 4. Storing the installation in the database
- * 5. Redirecting to the application
- *
- * Route: GET /github-app/callback?installation_id=...&setup_action=...&state=...
- */
-import { RouteProps } from "@flink-app/flink";
-import { GitHubAppInternalContext } from "../GitHubAppInternalContext";
-/**
- * Route configuration
- * Registered programmatically by the plugin if registerRoutes is enabled
- */
-export declare const Route: RouteProps;
-/**
- * GitHub App Installation Callback Handler
- *
- * Completes the installation flow by validating state, fetching installation
- * details, calling the app's callback, and storing the installation.
- */
-declare const InstallationCallback: ({ ctx, req }: {
-    ctx: GitHubAppInternalContext;
-    req: any;
-}) => Promise<import("@flink-app/flink").FlinkResponse<undefined> | {
-    status: number;
-    headers: {
-        Location: string;
-    };
-    data: {};
-}>;
-export default InstallationCallback;

package/dist/handlers/InstallationCallback.js

@@ -1,248 +0,0 @@
-"use strict";
-/**
- * GitHub App Installation Callback Handler
- *
- * Handles the callback from GitHub after app installation by:
- * 1. Validating the state parameter to prevent CSRF attacks
- * 2. Fetching installation details from GitHub API
- * 3. Calling the onInstallationSuccess callback to link installation to user
- * 4. Storing the installation in the database
- * 5. Redirecting to the application
- *
- * Route: GET /github-app/callback?installation_id=...&setup_action=...&state=...
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Route = void 0;
-const flink_1 = require("@flink-app/flink");
-const error_utils_1 = require("../utils/error-utils");
-const state_utils_1 = require("../utils/state-utils");
-/**
- * Route configuration
- * Registered programmatically by the plugin if registerRoutes is enabled
- */
-exports.Route = {
-    path: "/github-app/callback",
-    method: flink_1.HttpMethod.get,
-};
-/**
- * GitHub App Installation Callback Handler
- *
- * Completes the installation flow by validating state, fetching installation
- * details, calling the app's callback, and storing the installation.
- */
-const InstallationCallback = async ({ ctx, req }) => {
-    const { installation_id, setup_action, state, code } = req.query;
-    try {
-        // Validate required parameters
-        if (!installation_id || !setup_action || !state) {
-            return (0, flink_1.badRequest)("Missing required parameters: installation_id, setup_action, or state");
-        }
-        // Find installation session by state
-        const session = await ctx.repos.githubAppSessionRepo.getOne({ state });
-        if (!session) {
-            const error = (0, error_utils_1.createGitHubAppError)(error_utils_1.GitHubAppErrorCodes.SESSION_EXPIRED, "Installation session not found or expired. Please try again.", {
-                state: state.substring(0, 10) + "...",
-            });
-            // Call onInstallationError callback if provided
-            const { options } = ctx.plugins.githubApp;
-            if (options.onInstallationError) {
-                const errorResult = await options.onInstallationError({ error, installationId: installation_id });
-                if (errorResult.redirectUrl) {
-                    return {
-                        status: 302,
-                        headers: { Location: errorResult.redirectUrl },
-                        data: {},
-                    };
-                }
-            }
-            return (0, flink_1.badRequest)(error.message);
-        }
-        // Validate state parameter using constant-time comparison (CSRF protection)
-        if (!(0, state_utils_1.validateState)(state, session.state)) {
-            const error = (0, error_utils_1.createGitHubAppError)(error_utils_1.GitHubAppErrorCodes.INVALID_STATE, "Invalid state parameter. Possible CSRF attack detected.", {
-                providedState: state.substring(0, 10) + "...",
-            });
-            // Call onInstallationError callback if provided
-            const { options } = ctx.plugins.githubApp;
-            if (options.onInstallationError) {
-                const errorResult = await options.onInstallationError({ error, installationId: installation_id });
-                if (errorResult.redirectUrl) {
-                    return {
-                        status: 302,
-                        headers: { Location: errorResult.redirectUrl },
-                        data: {},
-                    };
-                }
-            }
-            return (0, flink_1.badRequest)(error.message);
-        }
-        // Delete session immediately after validation (one-time use)
-        await ctx.repos.githubAppSessionRepo.deleteBySessionId(session.sessionId);
-        // Get plugin options and auth service
-        const { options, authService } = ctx.plugins.githubApp;
-        // Generate GitHub App JWT
-        const jwt = authService.generateAppJWT();
-        // Fetch installation details from GitHub API
-        const installationIdNum = parseInt(installation_id, 10);
-        const installationDetails = await fetchInstallationDetails(installationIdNum, jwt, options.baseUrl);
-        // Fetch repositories accessible by this installation
-        const repositories = await fetchInstallationRepositories(installationIdNum, jwt, options.baseUrl);
-        // Call onInstallationSuccess callback to get userId and redirect URL
-        let callbackResult;
-        try {
-            callbackResult = await options.onInstallationSuccess({
-                installationId: installationIdNum,
-                setupAction: setup_action,
-                account: installationDetails.account,
-                repositories: repositories,
-                permissions: installationDetails.permissions || {},
-                events: installationDetails.events || [],
-            }, ctx);
-        }
-        catch (error) {
-            flink_1.log.error("GitHub App onInstallationSuccess callback failed:", error);
-            const callbackError = (0, error_utils_1.createGitHubAppError)(error_utils_1.GitHubAppErrorCodes.SERVER_ERROR, "Failed to complete installation. Please try again.", {
-                originalError: error.message,
-            });
-            // Call onInstallationError callback if provided
-            if (options.onInstallationError) {
-                const errorResult = await options.onInstallationError({
-                    error: callbackError,
-                    installationId: installation_id,
-                });
-                if (errorResult.redirectUrl) {
-                    return {
-                        status: 302,
-                        headers: { Location: errorResult.redirectUrl },
-                        data: {},
-                    };
-                }
-            }
-            return (0, flink_1.internalServerError)("Installation failed. Please try again.");
-        }
-        // Extract userId and redirectUrl from callback result
-        const { userId, redirectUrl } = callbackResult;
-        if (!userId) {
-            return (0, flink_1.badRequest)("onInstallationSuccess callback must return userId");
-        }
-        // Store installation in database
-        await ctx.repos.githubInstallationRepo.create({
-            userId,
-            installationId: installationIdNum,
-            accountId: installationDetails.account.id,
-            accountLogin: installationDetails.account.login,
-            accountType: installationDetails.account.type,
-            avatarUrl: installationDetails.account.avatar_url,
-            repositories: repositories.map((repo) => ({
-                id: repo.id,
-                name: repo.name,
-                fullName: repo.full_name,
-                private: repo.private,
-            })),
-            permissions: installationDetails.permissions || {},
-            events: installationDetails.events || [],
-            createdAt: new Date(),
-            updatedAt: new Date(),
-        });
-        // Redirect to app using callback's redirectUrl or default to root
-        const finalRedirectUrl = redirectUrl || "/";
-        return {
-            status: 302,
-            headers: {
-                Location: finalRedirectUrl,
-            },
-            data: {},
-        };
-    }
-    catch (error) {
-        flink_1.log.error("GitHub App installation callback error:", error);
-        // Call onInstallationError callback if provided
-        const { options } = ctx.plugins.githubApp;
-        if (options.onInstallationError) {
-            try {
-                const errorResult = await options.onInstallationError({
-                    error: error,
-                    installationId: installation_id,
-                });
-                if (errorResult.redirectUrl) {
-                    return {
-                        status: 302,
-                        headers: { Location: errorResult.redirectUrl },
-                        data: {},
-                    };
-                }
-            }
-            catch (callbackError) {
-                flink_1.log.error("onInstallationError callback failed:", callbackError);
-            }
-        }
-        return (0, flink_1.internalServerError)(error.message || "Installation callback failed. Please try again.");
-    }
-};
-/**
- * Fetch installation details from GitHub API
- *
- * @param installationId - GitHub installation ID
- * @param jwt - GitHub App JWT
- * @param baseUrl - GitHub API base URL
- * @returns Installation details
- */
-async function fetchInstallationDetails(installationId, jwt, baseUrl = "https://api.github.com") {
-    const url = `${baseUrl}/app/installations/${installationId}`;
-    const response = await fetch(url, {
-        method: "GET",
-        headers: {
-            Authorization: `Bearer ${jwt}`,
-            Accept: "application/vnd.github+json",
-            "User-Agent": "Flink-GitHub-App-Plugin",
-        },
-    });
-    if (!response.ok) {
-        const errorBody = await response.text();
-        throw new Error(`Failed to fetch installation details: ${response.statusText} - ${errorBody}`);
-    }
-    return await response.json();
-}
-/**
- * Fetch repositories accessible by installation
- *
- * @param installationId - GitHub installation ID
- * @param jwt - GitHub App JWT
- * @param baseUrl - GitHub API base URL
- * @returns Array of repositories
- */
-async function fetchInstallationRepositories(installationId, jwt, baseUrl = "https://api.github.com") {
-    const url = `${baseUrl}/installation/repositories`;
-    // First get an installation token
-    const tokenUrl = `${baseUrl}/app/installations/${installationId}/access_tokens`;
-    const tokenResponse = await fetch(tokenUrl, {
-        method: "POST",
-        headers: {
-            Authorization: `Bearer ${jwt}`,
-            Accept: "application/vnd.github+json",
-            "User-Agent": "Flink-GitHub-App-Plugin",
-        },
-    });
-    if (!tokenResponse.ok) {
-        const errorBody = await tokenResponse.text();
-        throw new Error(`Failed to get installation token: ${tokenResponse.statusText} - ${errorBody}`);
-    }
-    const tokenData = await tokenResponse.json();
-    const token = tokenData.token;
-    // Now fetch repositories with the installation token
-    const reposResponse = await fetch(url, {
-        method: "GET",
-        headers: {
-            Authorization: `Bearer ${token}`,
-            Accept: "application/vnd.github+json",
-            "User-Agent": "Flink-GitHub-App-Plugin",
-        },
-    });
-    if (!reposResponse.ok) {
-        const errorBody = await reposResponse.text();
-        throw new Error(`Failed to fetch repositories: ${reposResponse.statusText} - ${errorBody}`);
-    }
-    const data = await reposResponse.json();
-    return data.repositories || [];
-}
-exports.default = InstallationCallback;

package/dist/handlers/UninstallHandler.d.ts

@@ -1,37 +0,0 @@
-/**
- * GitHub App Uninstall Handler
- *
- * Manually uninstalls a GitHub App installation by:
- * 1. Extracting userId from request (app-defined authentication)
- * 2. Verifying user owns the installation
- * 3. Deleting installation from database
- * 4. Clearing cached installation token
- * 5. Returning 204 No Content
- *
- * Route: DELETE /github-app/installation/:installationId
- *
- * Note: This is an optional handler for manual uninstallation.
- * Apps should also handle the 'installation.deleted' webhook event
- * for automatic cleanup when users uninstall via GitHub UI.
- */
-import { Handler, RouteProps } from "@flink-app/flink";
-/**
- * Path parameters for the handler
- */
-interface PathParams {
-    installationId: string;
-    [key: string]: string;
-}
-/**
- * Route configuration
- * Registered programmatically by the plugin if registerRoutes is enabled
- */
-export declare const Route: RouteProps;
-/**
- * GitHub App Uninstall Handler
- *
- * Allows users to manually uninstall a GitHub App from their account.
- * The application must provide userId extraction logic (via JWT, session, etc.)
- */
-declare const UninstallHandler: Handler<any, any, any, PathParams>;
-export default UninstallHandler;

package/dist/handlers/UninstallHandler.js

@@ -1,153 +0,0 @@
-"use strict";
-/**
- * GitHub App Uninstall Handler
- *
- * Manually uninstalls a GitHub App installation by:
- * 1. Extracting userId from request (app-defined authentication)
- * 2. Verifying user owns the installation
- * 3. Deleting installation from database
- * 4. Clearing cached installation token
- * 5. Returning 204 No Content
- *
- * Route: DELETE /github-app/installation/:installationId
- *
- * Note: This is an optional handler for manual uninstallation.
- * Apps should also handle the 'installation.deleted' webhook event
- * for automatic cleanup when users uninstall via GitHub UI.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Route = void 0;
-const flink_1 = require("@flink-app/flink");
-/**
- * Route configuration
- * Registered programmatically by the plugin if registerRoutes is enabled
- */
-exports.Route = {
-    path: "/github-app/installation/:installationId",
-    method: flink_1.HttpMethod.delete,
-};
-/**
- * GitHub App Uninstall Handler
- *
- * Allows users to manually uninstall a GitHub App from their account.
- * The application must provide userId extraction logic (via JWT, session, etc.)
- */
-const UninstallHandler = async ({ ctx, req }) => {
-    try {
-        const { installationId } = req.params;
-        const installationIdNum = parseInt(installationId, 10);
-        if (isNaN(installationIdNum)) {
-            return {
-                status: 400,
-                data: { error: "Invalid installation ID" },
-            };
-        }
-        // Extract userId from request
-        // This is app-defined and can work with any authentication system
-        // Examples:
-        // - JWT Auth Plugin: ctx.auth?.tokenData?.userId
-        // - Session-based: req.session?.userId
-        // - Custom header: req.headers['x-user-id']
-        //
-        // For now, we'll look for userId in multiple common places
-        const userId = extractUserId(req, ctx);
-        if (!userId) {
-            return {
-                status: 401,
-                data: { error: "Authentication required" },
-            };
-        }
-        // Find the installation
-        const installation = await ctx.repos.githubInstallationRepo.findByInstallationId(installationIdNum);
-        if (!installation) {
-            return {
-                status: 404,
-                data: { error: "Installation not found" },
-            };
-        }
-        // Verify user owns the installation
-        if (installation.userId !== userId) {
-            flink_1.log.warn("User attempted to delete installation they don't own", {
-                userId,
-                installationId: installationIdNum,
-                ownerId: installation.userId,
-            });
-            return {
-                status: 403,
-                data: { error: "You do not have permission to delete this installation" },
-            };
-        }
-        // Delete installation from database
-        const deletedCount = await ctx.repos.githubInstallationRepo.deleteByInstallationId(installationIdNum);
-        if (deletedCount === 0) {
-            flink_1.log.error("Failed to delete installation from database", {
-                installationId: installationIdNum,
-            });
-            return {
-                status: 500,
-                data: { error: "Failed to delete installation" },
-            };
-        }
-        // Clear cached installation token
-        ctx.plugins.githubApp.authService.deleteInstallationToken(installationIdNum);
-        flink_1.log.info("GitHub App installation deleted", {
-            userId,
-            installationId: installationIdNum,
-        });
-        // Return 204 No Content
-        return {
-            status: 204,
-            data: {},
-        };
-    }
-    catch (error) {
-        flink_1.log.error("Error deleting GitHub App installation", {
-            error: error.message,
-        });
-        return {
-            status: 500,
-            data: { error: "Failed to delete installation" },
-        };
-    }
-};
-/**
- * Extract userId from request
- *
- * This helper function attempts to extract userId from various common
- * authentication patterns. Applications can customize this logic based
- * on their authentication system.
- *
- * @param req - Express request object
- * @param ctx - Flink context
- * @returns userId if found, undefined otherwise
- */
-function extractUserId(req, ctx) {
-    // Option 1: JWT Auth Plugin (if available)
-    if (ctx.auth?.tokenData?.userId) {
-        return ctx.auth.tokenData.userId;
-    }
-    // Option 2: Custom user property on request (set by custom middleware)
-    if (req.user?.id) {
-        return req.user.id;
-    }
-    if (req.user?.userId) {
-        return req.user.userId;
-    }
-    if (req.user?._id) {
-        return req.user._id;
-    }
-    // Option 3: Session-based authentication
-    if (req.session?.userId) {
-        return req.session.userId;
-    }
-    // Option 4: Custom header
-    if (req.headers["x-user-id"]) {
-        return req.headers["x-user-id"];
-    }
-    // Option 5: Query parameter (less secure, use with caution)
-    if (req.query?.user_id) {
-        return req.query.user_id;
-    }
-    return undefined;
-}
-exports.default = UninstallHandler;

package/dist/schemas/InstallationCallbackRequest.d.ts

@@ -1,10 +0,0 @@
-/**
- * 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/dist/schemas/InstallationCallbackRequest.js

@@ -1,2 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });