fix(webapp): verify GitHub App installation ownership

GitHub App installation callbacks now verify that the authenticated
installing user can access the installation before linking it to an
account.

Mono-RevId: c59ade6435294a39335d1b85cc881a0afd1d1452

Author: carderne

.server-changes/verify-github-app-installation-ownership.md

@@ -0,0 +1,6 @@
+---
+area: webapp
+type: fix
+---
+
+GitHub App installations are now linked only after the installing GitHub user authorizes the App and is verified to have access to the installation.

apps/webapp/app/env.server.ts

@@ -51,18 +51,32 @@ const GithubAppEnvSchema = z.preprocess(
     }
     return obj;
   },
-  z.discriminatedUnion("GITHUB_APP_ENABLED", [
-    z.object({
-      GITHUB_APP_ENABLED: z.literal("1"),
-      GITHUB_APP_ID: z.string(),
-      GITHUB_APP_PRIVATE_KEY: z.string(),
-      GITHUB_APP_WEBHOOK_SECRET: z.string(),
-      GITHUB_APP_SLUG: z.string(),
-    }),
-    z.object({
-      GITHUB_APP_ENABLED: z.literal("0"),
-    }),
-  ])
+  z
+    .discriminatedUnion("GITHUB_APP_ENABLED", [
+      z.object({
+        GITHUB_APP_ENABLED: z.literal("1"),
+        GITHUB_APP_ID: z.string(),
+        GITHUB_APP_PRIVATE_KEY: z.string(),
+        GITHUB_APP_WEBHOOK_SECRET: z.string(),
+        GITHUB_APP_SLUG: z.string(),
+        GITHUB_APP_CLIENT_ID: z.string().min(1).optional(),
+        GITHUB_APP_CLIENT_SECRET: z.string().min(1).optional(),
+      }),
+      z.object({
+        GITHUB_APP_ENABLED: z.literal("0"),
+      }),
+    ])
+    .superRefine((value, ctx) => {
+      if (
+        value.GITHUB_APP_ENABLED === "1" &&
+        Boolean(value.GITHUB_APP_CLIENT_ID) !== Boolean(value.GITHUB_APP_CLIENT_SECRET)
+      ) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: "GITHUB_APP_CLIENT_ID and GITHUB_APP_CLIENT_SECRET must be configured together",
+        });
+      }
+    })
 );
 
 // eventually we can make all S2 env vars required once the S2 OSS version is out

apps/webapp/app/routes/_app.github.callback/route.tsx

@@ -15,20 +15,33 @@ import { sanitizeRedirectPath } from "~/utils";
 const QuerySchema = z.discriminatedUnion("setup_action", [
   z.object({
     setup_action: z.literal("install"),
-    installation_id: z.coerce.number(),
-    state: z.string(),
+    installation_id: z.coerce.number().int().positive().safe(),
+    state: z.string().min(1),
+    code: z.string().min(1),
   }),
   z.object({
     setup_action: z.literal("update"),
-    installation_id: z.coerce.number(),
-    state: z.string(),
+    installation_id: z.coerce.number().int().positive().safe(),
+    state: z.string().min(1),
   }),
   z.object({
     setup_action: z.literal("request"),
-    state: z.string(),
+    state: z.string().min(1),
   }),
 ]);
 
+function loggableError(error: unknown) {
+  if (!(error instanceof Error)) {
+    return { name: "Unknown error" };
+  }
+
+  return {
+    name: error.name,
+    message: error.message,
+    status: "status" in error ? error.status : undefined,
+  };
+}
+
 export async function loader({ request }: LoaderFunctionArgs) {
   const url = new URL(request.url);
   const queryParams = Object.fromEntries(url.searchParams);
@@ -38,7 +51,8 @@ export async function loader({ request }: LoaderFunctionArgs) {
 
   if (!result.success) {
     logger.warn("GitHub App callback with invalid params", {
-      queryParams,
+      setupAction: url.searchParams.get("setup_action"),
+      parameterNames: [...url.searchParams.keys()],
     });
     return redirectWithErrorMessage("/", request, "Failed to install GitHub app");
   }
@@ -49,7 +63,9 @@ export async function loader({ request }: LoaderFunctionArgs) {
 
   if (!sessionResult.valid) {
     logger.error("GitHub App callback with invalid session", {
-      callbackData,
+      setupAction: callbackData.setup_action,
+      installationId:
+        callbackData.setup_action === "request" ? undefined : callbackData.installation_id,
       error: sessionResult.error,
     });
 
@@ -90,12 +106,19 @@ export async function loader({ request }: LoaderFunctionArgs) {
   switch (callbackData.setup_action) {
     case "install": {
       const [error] = await tryCatch(
-        linkGitHubAppInstallation(callbackData.installation_id, organizationId)
+        linkGitHubAppInstallation({
+          installationId: callbackData.installation_id,
+          organizationId,
+          installedByUserId: user.id,
+          oauthCode: callbackData.code,
+        })
       );
 
       if (error) {
         logger.error("Failed to link GitHub App installation", {
-          error,
+          installationId: callbackData.installation_id,
+          organizationId,
+          error: loggableError(error),
         });
         return consumingSession(
           await redirectWithErrorMessage(redirectTo, request, "Failed to install GitHub app")
@@ -114,7 +137,9 @@ export async function loader({ request }: LoaderFunctionArgs) {
 
       if (error) {
         logger.error("Failed to update GitHub App installation", {
-          error,
+          installationId: callbackData.installation_id,
+          organizationId,
+          error: loggableError(error),
         });
         return consumingSession(
           await redirectWithErrorMessage(redirectTo, request, "Failed to update GitHub App")
@@ -129,9 +154,7 @@ export async function loader({ request }: LoaderFunctionArgs) {
     case "request": {
       // This happens when a non-admin user requests installation
       // The installation_id won't be available until an admin approves
-      logger.info("GitHub App installation requested, awaiting approval", {
-        callbackData,
-      });
+      logger.info("GitHub App installation requested, awaiting approval");
 
       return redirectWithSuccessMessage(redirectTo, request, "GitHub App installation requested");
     }

apps/webapp/app/services/gitHub.server.ts

@@ -1,8 +1,20 @@
-import { App, type Octokit } from "octokit";
+import { App, Octokit } from "octokit";
 import { env } from "../env.server";
 import { prisma } from "~/db.server";
 import { logger } from "./logger.server";
 import { errAsync, fromPromise, okAsync, type ResultAsync } from "neverthrow";
+import { tryCatch } from "@trigger.dev/core/utils";
+import {
+  getAuthenticatedGitHubLogin,
+  verifyGitHubAppInstallationAccess,
+} from "./gitHubInstallationOwnership.server";
+
+function isGitHubAppUserOAuthConfigured(): boolean {
+  return (
+    env.GITHUB_APP_ENABLED === "1" &&
+    Boolean(env.GITHUB_APP_CLIENT_ID && env.GITHUB_APP_CLIENT_SECRET)
+  );
+}
 
 export const githubApp =
   env.GITHUB_APP_ENABLED === "1"
@@ -12,33 +24,82 @@ export const githubApp =
         webhooks: {
           secret: env.GITHUB_APP_WEBHOOK_SECRET,
         },
+        ...(env.GITHUB_APP_CLIENT_ID && env.GITHUB_APP_CLIENT_SECRET
+          ? {
+              oauth: {
+                clientId: env.GITHUB_APP_CLIENT_ID,
+                clientSecret: env.GITHUB_APP_CLIENT_SECRET,
+              },
+            }
+          : {}),
       })
     : null;
 
+async function withGitHubUserToken<T>(
+  oauthCode: string,
+  fn: (userOctokit: Octokit) => Promise<T>
+): Promise<T> {
+  if (!githubApp) {
+    throw new Error("GitHub App is not enabled");
+  }
+
+  const { authentication } = await githubApp.oauth.createToken({ code: oauthCode });
+
+  const [error, result] = await tryCatch(fn(new Octokit({ auth: authentication.token })));
+
+  const [revokeError] = await tryCatch(
+    githubApp.oauth.deleteToken({ token: authentication.token })
+  );
+  if (revokeError) {
+    logger.warn("Failed to revoke GitHub user token", {
+      error: revokeError instanceof Error ? revokeError.message : "Unknown error",
+    });
+  }
+
+  if (error) {
+    throw error;
+  }
+
+  return result;
+}
+
 /**
  * Links a GitHub App installation to a Trigger organization
  */
-export async function linkGitHubAppInstallation(
-  installationId: number,
-  organizationId: string
-): Promise<void> {
+export async function linkGitHubAppInstallation(params: {
+  installationId: number;
+  organizationId: string;
+  installedByUserId: string;
+  oauthCode: string;
+}): Promise<void> {
   if (!githubApp) {
     throw new Error("GitHub App is not enabled");
   }
 
-  const octokit = await githubApp.getInstallationOctokit(installationId);
+  if (!isGitHubAppUserOAuthConfigured()) {
+    throw new Error("GitHub App user authorization is not configured");
+  }
+
+  const installedBy = await withGitHubUserToken(params.oauthCode, async (userOctokit) => {
+    await verifyGitHubAppInstallationAccess(userOctokit, params.installationId);
+    return getAuthenticatedGitHubLogin(userOctokit);
+  });
+
+  const octokit = await githubApp.getInstallationOctokit(params.installationId);
   const { data: installation } = await octokit.rest.apps.getInstallation({
-    installation_id: installationId,
+    installation_id: params.installationId,
   });
 
-  const repositories = await fetchInstallationRepositories(octokit, installationId);
+  const repositories = await fetchInstallationRepositories(octokit, params.installationId);
 
   const repositorySelection = installation.repository_selection === "all" ? "ALL" : "SELECTED";
 
   await prisma.githubAppInstallation.create({
     data: {
-      appInstallationId: installationId,
-      organizationId,
+      appInstallationId: params.installationId,
+      organizationId: params.organizationId,
+      installedBy,
+      installedByUserId: params.installedByUserId,
       targetId: installation.target_id,
       targetType: installation.target_type,
       accountHandle: installation.account

apps/webapp/app/services/gitHubInstallationOwnership.server.ts

@@ -0,0 +1,44 @@
+import type { Octokit } from "octokit";
+
+const installationsPerPage = 100;
+
+type GitHubUserClient = Pick<Octokit, "request">;
+
+export async function verifyGitHubAppInstallationAccess(
+  userOctokit: GitHubUserClient,
+  installationId: number
+): Promise<void> {
+  let page = 1;
+
+  while (true) {
+    const { data } = await userOctokit.request("GET /user/installations", {
+      page,
+      per_page: installationsPerPage,
+    });
+
+    if (data.installations.some((installation) => installation.id === installationId)) {
+      return;
+    }
+
+    if (
+      data.installations.length < installationsPerPage ||
+      page * installationsPerPage >= data.total_count
+    ) {
+      break;
+    }
+
+    page++;
+  }
+
+  throw new Error("GitHub App installation is not accessible to the authenticated GitHub user");
+}
+
+export async function getAuthenticatedGitHubLogin(userOctokit: GitHubUserClient): Promise<string> {
+  const { data } = await userOctokit.request("GET /user");
+
+  if (!data.login) {
+    throw new Error("GitHub did not return a login for the authenticated user");
+  }
+
+  return data.login;
+}

apps/webapp/app/services/gitHubSession.server.ts

@@ -82,10 +82,7 @@ export async function validateGitHubAppInstallSession(
   }
 
   if (sessionState !== state) {
-    logger.warn("GitHub App installation state mismatch", {
-      expectedState: sessionState,
-      receivedState: state,
-    });
+    logger.warn("GitHub App installation state mismatch");
     return {
       valid: false,
       error: "state_mismatch",

apps/webapp/test/env.server.test.ts

@@ -81,4 +81,38 @@ describe("webapp environment secrets", () => {
 
     await expect(import("../app/env.server")).rejects.toThrow("SESSION_SECRET");
   });
+
+  it("requires GitHub App OAuth credentials to be configured together", async () => {
+    process.env = {
+      ...requiredEnv,
+      GITHUB_APP_ENABLED: "1",
+      GITHUB_APP_ID: "123",
+      GITHUB_APP_PRIVATE_KEY: "private-key",
+      GITHUB_APP_WEBHOOK_SECRET: "webhook-secret",
+      GITHUB_APP_SLUG: "test-app",
+      GITHUB_APP_CLIENT_ID: "client-id",
+    };
+
+    await expect(import("../app/env.server")).rejects.toThrow(
+      "GITHUB_APP_CLIENT_ID and GITHUB_APP_CLIENT_SECRET must be configured together"
+    );
+  });
+
+  it("accepts a complete GitHub App OAuth configuration", async () => {
+    process.env = {
+      ...requiredEnv,
+      GITHUB_APP_ENABLED: "1",
+      GITHUB_APP_ID: "123",
+      GITHUB_APP_PRIVATE_KEY: "private-key",
+      GITHUB_APP_WEBHOOK_SECRET: "webhook-secret",
+      GITHUB_APP_SLUG: "test-app",
+      GITHUB_APP_CLIENT_ID: "client-id",
+      GITHUB_APP_CLIENT_SECRET: "client-secret",
+    };
+
+    const { env } = await import("../app/env.server");
+
+    expect(env.GITHUB_APP_CLIENT_ID).toBe("client-id");
+    expect(env.GITHUB_APP_CLIENT_SECRET).toBe("client-secret");
+  });
 });