improvements: address feedback

backend/src/services/app-connection/app-connection-dal.ts

@@ -5,7 +5,7 @@ import { ormify } from "@app/lib/knex";
 export type TAppConnectionDALFactory = ReturnType<typeof appConnectionDALFactory>;
 
 export const appConnectionDALFactory = (db: TDbClient) => {
-  const appConnection = ormify(db, TableName.AppConnection);
+  const appConnectionOrm = ormify(db, TableName.AppConnection);
 
-  return { ...appConnection };
+  return { ...appConnectionOrm };
 };

backend/src/services/app-connection/app-connection-enums.ts

@@ -0,0 +1,4 @@
+export enum AppConnection {
+  GitHub = "github",
+  AWS = "aws"
+}

backend/src/services/app-connection/app-connection-fns.ts

@@ -1,10 +1,20 @@
-import { AppConnection, AppConnectionListItem, TAppConnection, TAppConnectionConfig } from "@app/lib/app-connections";
-import { getAwsAppConnectionListItem, validateAwsConnectionCredentials } from "@app/lib/app-connections/aws";
-import { getGitHubConnectionListItem, validateGitHubConnectionCredentials } from "@app/lib/app-connections/github";
+import {
+  AwsConnectionMethod,
+  getAwsAppConnectionListItem,
+  validateAwsConnectionCredentials
+} from "src/services/app-connection/aws";
+import {
+  getGitHubConnectionListItem,
+  GitHubConnectionMethod,
+  validateGitHubConnectionCredentials
+} from "src/services/app-connection/github";
+
+import { AppConnection } from "@app/services/app-connection/app-connection-enums";
 import { TAppConnectionServiceFactoryDep } from "@app/services/app-connection/app-connection-service";
+import { TAppConnection, TAppConnectionConfig } from "@app/services/app-connection/app-connection-types";
 import { KmsDataKey } from "@app/services/kms/kms-types";
 
-export const listAppConnectionOptions = (): (AppConnectionListItem & Record<string, unknown>)[] => {
+export const listAppConnectionOptions = () => {
   return [getAwsAppConnectionListItem(), getGitHubConnectionListItem()].sort((a, b) => a.name.localeCompare(b.name));
 };
 
@@ -65,3 +75,19 @@ export const validateAppConnectionCredentials = async (
       throw new Error(`Unhandled App Connection ${app}`);
   }
 };
+
+export const getAppConnectionMethodName = (method: TAppConnection["method"]) => {
+  switch (method) {
+    case GitHubConnectionMethod.App:
+      return "GitHub App";
+    case GitHubConnectionMethod.OAuth:
+      return "OAuth";
+    case AwsConnectionMethod.AccessKey:
+      return "Access Key";
+    case AwsConnectionMethod.AssumeRole:
+      return "Assume Role";
+    default:
+      // eslint-disable-next-line @typescript-eslint/restrict-template-expressions
+      throw new Error(`Unhandled App Connection Method: ${method}`);
+  }
+};

backend/src/services/app-connection/app-connection-maps.ts

@@ -0,0 +1,6 @@
+import { AppConnection } from "./app-connection-enums";
+
+export const APP_CONNECTION_NAME_MAP: Record<AppConnection, string> = {
+  [AppConnection.AWS]: "AWS",
+  [AppConnection.GitHub]: "GitHub"
+};

backend/src/services/app-connection/app-connection-schemas.ts

@@ -1,7 +1,35 @@
+import { z } from "zod";
+
 import { AppConnectionsSchema } from "@app/db/schemas/app-connections";
+import { AppConnections } from "@app/lib/api-docs";
+import { slugSchema } from "@app/server/lib/schemas";
+
+import { AppConnection } from "./app-connection-enums";
 
 export const BaseAppConnectionSchema = AppConnectionsSchema.omit({
   encryptedCredentials: true,
   app: true,
   method: true
 });
+
+export const GenericCreateAppConnectionFieldsSchema = (app: AppConnection) =>
+  z.object({
+    name: slugSchema({ field: "name" }).describe(AppConnections.CREATE(app).name),
+    description: z
+      .string()
+      .trim()
+      .max(256, "Description cannot exceed 256 characters")
+      .nullish()
+      .describe(AppConnections.CREATE(app).description)
+  });
+
+export const GenericUpdateAppConnectionFieldsSchema = (app: AppConnection) =>
+  z.object({
+    name: slugSchema({ field: "name" }).describe(AppConnections.UPDATE(app).name).optional(),
+    description: z
+      .string()
+      .trim()
+      .max(256, "Description cannot exceed 256 characters")
+      .nullish()
+      .describe(AppConnections.UPDATE(app).description)
+  });

backend/src/services/app-connection/app-connection-service.ts

@@ -3,21 +3,26 @@ import { ForbiddenError } from "@casl/ability";
 import { TLicenseServiceFactory } from "@app/ee/services/license/license-service";
 import { OrgPermissionActions, OrgPermissionSubjects } from "@app/ee/services/permission/org-permission";
 import { TPermissionServiceFactory } from "@app/ee/services/permission/permission-service";
-import {
-  AppConnection,
-  TAppConnection,
-  TAppConnectionConfig,
-  TCreateAppConnectionDTO,
-  TUpdateAppConnectionDTO
-} from "@app/lib/app-connections";
 import { BadRequestError, NotFoundError } from "@app/lib/errors";
-import { OrgServiceActor } from "@app/lib/types";
+import { DiscriminativePick, OrgServiceActor } from "@app/lib/types";
+import { AppConnection } from "@app/services/app-connection/app-connection-enums";
 import {
   decryptAppConnectionCredentials,
   encryptAppConnectionCredentials,
+  getAppConnectionMethodName,
   listAppConnectionOptions,
   validateAppConnectionCredentials
 } from "@app/services/app-connection/app-connection-fns";
+import { APP_CONNECTION_NAME_MAP } from "@app/services/app-connection/app-connection-maps";
+import {
+  TAppConnection,
+  TAppConnectionConfig,
+  TCreateAppConnectionDTO,
+  TUpdateAppConnectionDTO,
+  TValidateAppConnectionCredentials
+} from "@app/services/app-connection/app-connection-types";
+import { ValidateAwsConnectionCredentialsSchema } from "@app/services/app-connection/aws";
+import { ValidateGitHubConnectionCredentialsSchema } from "@app/services/app-connection/github";
 import { TKmsServiceFactory } from "@app/services/kms/kms-service";
 
 import { TAppConnectionDALFactory } from "./app-connection-dal";
@@ -31,6 +36,11 @@ export type TAppConnectionServiceFactoryDep = {
 
 export type TAppConnectionServiceFactory = ReturnType<typeof appConnectionServiceFactory>;
 
+const VALIDATE_APP_CONNECTION_CREDENTIALS_MAP: Record<AppConnection, TValidateAppConnectionCredentials> = {
+  [AppConnection.AWS]: ValidateAwsConnectionCredentialsSchema,
+  [AppConnection.GitHub]: ValidateGitHubConnectionCredentialsSchema
+};
+
 export const appConnectionServiceFactory = ({
   appConnectionDAL,
   permissionService,
@@ -160,40 +170,53 @@ export const appConnectionServiceFactory = ({
 
     ForbiddenError.from(permission).throwUnlessCan(OrgPermissionActions.Create, OrgPermissionSubjects.AppConnections);
 
-    const isConflictingName = Boolean(
-      await appConnectionDAL.findOne({
-        name: params.name,
-        orgId: actor.orgId
-      })
-    );
+    const appConnection = await appConnectionDAL.transaction(async (tx) => {
+      const isConflictingName = Boolean(
+        await appConnectionDAL.findOne(
+          {
+            name: params.name,
+            orgId: actor.orgId
+          },
+          tx
+        )
+      );
 
-    if (isConflictingName)
-      throw new BadRequestError({
-        message: `An App Connection with the name "${params.name}" already exists`
+      if (isConflictingName)
+        throw new BadRequestError({
+          message: `An App Connection with the name "${params.name}" already exists`
+        });
+
+      const validatedCredentials = await validateAppConnectionCredentials({
+        app,
+        credentials,
+        method,
+        orgId: actor.orgId
+      } as TAppConnectionConfig);
+
+      const encryptedCredentials = await encryptAppConnectionCredentials({
+        credentials: validatedCredentials,
+        orgId: actor.orgId,
+        kmsService
       });
 
-    const validatedCredentials = await validateAppConnectionCredentials({
-      app,
-      credentials,
-      method,
-      orgId: actor.orgId
-    } as TAppConnectionConfig);
+      const connection = await appConnectionDAL.create(
+        {
+          orgId: actor.orgId,
+          encryptedCredentials,
+          method,
+          app,
+          ...params
+        },
+        tx
+      );
 
-    const encryptedCredentials = await encryptAppConnectionCredentials({
-      credentials: validatedCredentials,
-      orgId: actor.orgId,
-      kmsService
+      return {
+        ...connection,
+        credentials: validatedCredentials
+      };
     });
 
-    const appConnection = await appConnectionDAL.create({
-      orgId: actor.orgId,
-      encryptedCredentials,
-      method,
-      app,
-      ...params
-    });
-
-    return { ...appConnection, credentials: validatedCredentials };
+    return appConnection;
   };
 
   const updateAppConnection = async (
@@ -216,44 +239,69 @@ export const appConnectionServiceFactory = ({
 
     ForbiddenError.from(permission).throwUnlessCan(OrgPermissionActions.Edit, OrgPermissionSubjects.AppConnections);
 
-    if (params.name && appConnection.name !== params.name) {
-      const isConflictingName = Boolean(
-        await appConnectionDAL.findOne({
-          name: params.name,
-          orgId: appConnection.orgId
-        })
+    const updatedAppConnection = await appConnectionDAL.transaction(async (tx) => {
+      if (params.name && appConnection.name !== params.name) {
+        const isConflictingName = Boolean(
+          await appConnectionDAL.findOne(
+            {
+              name: params.name,
+              orgId: appConnection.orgId
+            },
+            tx
+          )
+        );
+
+        if (isConflictingName)
+          throw new BadRequestError({
+            message: `An App Connection with the name "${params.name}" already exists`
+          });
+      }
+
+      let encryptedCredentials: undefined | Buffer;
+
+      if (credentials) {
+        const { app, method } = appConnection as DiscriminativePick<TAppConnectionConfig, "app" | "method">;
+
+        if (
+          !VALIDATE_APP_CONNECTION_CREDENTIALS_MAP[app].safeParse({
+            method,
+            credentials
+          }).success
+        )
+          throw new BadRequestError({
+            message: `Invalid credential format for ${
+              APP_CONNECTION_NAME_MAP[app]
+            } Connection with method ${getAppConnectionMethodName(method)}`
+          });
+
+        const validatedCredentials = await validateAppConnectionCredentials({
+          app,
+          orgId: actor.orgId,
+          credentials,
+          method
+        } as TAppConnectionConfig);
+
+        if (!validatedCredentials)
+          throw new BadRequestError({ message: "Unable to validate connection - check credentials" });
+
+        encryptedCredentials = await encryptAppConnectionCredentials({
+          credentials: validatedCredentials,
+          orgId: actor.orgId,
+          kmsService
+        });
+      }
+
+      const updatedConnection = await appConnectionDAL.updateById(
+        connectionId,
+        {
+          orgId: actor.orgId,
+          encryptedCredentials,
+          ...params
+        },
+        tx
       );
 
-      if (isConflictingName)
-        throw new BadRequestError({
-          message: `An App Connection with the name "${params.name}" already exists`
-        });
-    }
-
-    let encryptedCredentials: undefined | Buffer;
-
-    if (credentials) {
-      const validatedCredentials = await validateAppConnectionCredentials({
-        app: appConnection.app,
-        credentials,
-        method: appConnection.method,
-        orgId: actor.orgId
-      } as TAppConnectionConfig);
-
-      if (!validatedCredentials)
-        throw new BadRequestError({ message: "Unable to validate connection - check credentials" });
-
-      encryptedCredentials = await encryptAppConnectionCredentials({
-        credentials: validatedCredentials,
-        orgId: actor.orgId,
-        kmsService
-      });
-    }
-
-    const updatedAppConnection = await appConnectionDAL.updateById(connectionId, {
-      orgId: actor.orgId,
-      encryptedCredentials,
-      ...params
+      return updatedConnection;
     });
 
     return {

backend/src/services/app-connection/app-connection-types.ts

@@ -0,0 +1,31 @@
+import {
+  TAwsConnection,
+  TAwsConnectionConfig,
+  TAwsConnectionInput,
+  TValidateAwsConnectionCredentials
+} from "@app/services/app-connection/aws";
+import {
+  TGitHubConnection,
+  TGitHubConnectionConfig,
+  TGitHubConnectionInput,
+  TValidateGitHubConnectionCredentials
+} from "@app/services/app-connection/github";
+
+export type TAppConnection = { id: string } & (TAwsConnection | TGitHubConnection);
+
+export type TAppConnectionInput = { id: string } & (TAwsConnectionInput | TGitHubConnectionInput);
+
+export type TCreateAppConnectionDTO = Pick<
+  TAppConnectionInput,
+  "credentials" | "method" | "name" | "app" | "description"
+>;
+
+export type TUpdateAppConnectionDTO = Partial<Omit<TCreateAppConnectionDTO, "method" | "app">> & {
+  connectionId: string;
+};
+
+export type TAppConnectionConfig = TAwsConnectionConfig | TGitHubConnectionConfig;
+
+export type TValidateAppConnectionCredentials =
+  | TValidateAwsConnectionCredentials
+  | TValidateGitHubConnectionCredentials;

backend/src/services/app-connection/aws/aws-connection-enums.ts

@@ -0,0 +1,4 @@
+export enum AwsConnectionMethod {
+  AssumeRole = "assume-role",
+  AccessKey = "access-key"
+}

backend/src/services/app-connection/aws/aws-connection-fns.ts

@@ -0,0 +1,105 @@
+import { AssumeRoleCommand, STSClient } from "@aws-sdk/client-sts";
+import AWS from "aws-sdk";
+import { randomUUID } from "crypto";
+
+import { getConfig } from "@app/lib/config/env";
+import { BadRequestError, InternalServerError } from "@app/lib/errors";
+import { AppConnection } from "@app/services/app-connection/app-connection-enums";
+
+import { AwsConnectionMethod } from "./aws-connection-enums";
+import { TAwsConnectionConfig } from "./aws-connection-types";
+
+export const getAwsAppConnectionListItem = () => {
+  const { INF_APP_CONNECTION_AWS_ACCESS_KEY_ID } = getConfig();
+
+  return {
+    name: "AWS" as const,
+    app: AppConnection.AWS as const,
+    methods: Object.values(AwsConnectionMethod) as [AwsConnectionMethod.AssumeRole, AwsConnectionMethod.AccessKey],
+    accessKeyId: INF_APP_CONNECTION_AWS_ACCESS_KEY_ID
+  };
+};
+
+export const getAwsConnectionConfig = async (appConnection: TAwsConnectionConfig, region = "us-east-1") => {
+  const appCfg = getConfig();
+
+  let accessKeyId: string;
+  let secretAccessKey: string;
+  let sessionToken: undefined | string;
+
+  const { method, credentials, orgId } = appConnection;
+
+  switch (method) {
+    case AwsConnectionMethod.AssumeRole: {
+      const client = new STSClient({
+        region,
+        credentials:
+          appCfg.INF_APP_CONNECTION_AWS_ACCESS_KEY_ID && appCfg.INF_APP_CONNECTION_AWS_SECRET_ACCESS_KEY
+            ? {
+                accessKeyId: appCfg.INF_APP_CONNECTION_AWS_ACCESS_KEY_ID,
+                secretAccessKey: appCfg.INF_APP_CONNECTION_AWS_SECRET_ACCESS_KEY
+              }
+            : undefined // if hosting on AWS
+      });
+
+      const command = new AssumeRoleCommand({
+        RoleArn: credentials.roleArn,
+        RoleSessionName: `infisical-app-connection-${randomUUID()}`,
+        DurationSeconds: 900, // 15 mins
+        ExternalId: orgId
+      });
+
+      const assumeRes = await client.send(command);
+
+      if (!assumeRes.Credentials?.AccessKeyId || !assumeRes.Credentials?.SecretAccessKey) {
+        throw new BadRequestError({ message: "Failed to assume role - verify credentials and role configuration" });
+      }
+
+      accessKeyId = assumeRes.Credentials.AccessKeyId;
+      secretAccessKey = assumeRes.Credentials.SecretAccessKey;
+      sessionToken = assumeRes.Credentials?.SessionToken;
+      break;
+    }
+    case AwsConnectionMethod.AccessKey: {
+      accessKeyId = credentials.accessKeyId;
+      secretAccessKey = credentials.secretAccessKey;
+      break;
+    }
+    default:
+      // eslint-disable-next-line @typescript-eslint/restrict-template-expressions
+      throw new InternalServerError({ message: `Unsupported AWS connection method: ${method}` });
+  }
+
+  return new AWS.Config({
+    region,
+    credentials: {
+      accessKeyId,
+      secretAccessKey,
+      sessionToken
+    }
+  });
+};
+
+export const validateAwsConnectionCredentials = async (appConnection: TAwsConnectionConfig) => {
+  const awsConfig = await getAwsConnectionConfig(appConnection);
+  const sts = new AWS.STS(awsConfig);
+  let resp: Awaited<ReturnType<ReturnType<typeof sts.getCallerIdentity>["promise"]>>;
+
+  try {
+    resp = await sts.getCallerIdentity().promise();
+  } catch (e: unknown) {
+    throw new BadRequestError({
+      message: `Unable to validate connection - verify credentials`
+    });
+  }
+
+  if (resp.$response.httpResponse.statusCode !== 200)
+    throw new InternalServerError({
+      message: `Unable to validate credentials: ${
+        resp.$response.error?.message ??
+        `AWS responded with a status code of ${resp.$response.httpResponse.statusCode}. Verify credentials and try again.`
+      }`
+    });
+
+  return appConnection.credentials;
+};

backend/src/services/app-connection/aws/aws-connection-schemas.ts

@@ -0,0 +1,82 @@
+import { z } from "zod";
+
+import { AppConnections } from "@app/lib/api-docs";
+import { AppConnection } from "@app/services/app-connection/app-connection-enums";
+import {
+  BaseAppConnectionSchema,
+  GenericCreateAppConnectionFieldsSchema,
+  GenericUpdateAppConnectionFieldsSchema
+} from "@app/services/app-connection/app-connection-schemas";
+
+import { AwsConnectionMethod } from "./aws-connection-enums";
+
+export const AwsConnectionAssumeRoleCredentialsSchema = z.object({
+  roleArn: z.string().trim().min(1, "Role ARN required")
+});
+
+export const AwsConnectionAccessTokenCredentialsSchema = z.object({
+  accessKeyId: z.string().trim().min(1, "Access Key ID required"),
+  secretAccessKey: z.string().trim().min(1, "Secret Access Key required")
+});
+
+const BaseAwsConnectionSchema = BaseAppConnectionSchema.extend({ app: z.literal(AppConnection.AWS) });
+
+export const AwsConnectionSchema = z.intersection(
+  BaseAwsConnectionSchema,
+  z.discriminatedUnion("method", [
+    z.object({
+      method: z.literal(AwsConnectionMethod.AssumeRole),
+      credentials: AwsConnectionAssumeRoleCredentialsSchema
+    }),
+    z.object({
+      method: z.literal(AwsConnectionMethod.AccessKey),
+      credentials: AwsConnectionAccessTokenCredentialsSchema
+    })
+  ])
+);
+
+export const SanitizedAwsConnectionSchema = z.discriminatedUnion("method", [
+  BaseAwsConnectionSchema.extend({
+    method: z.literal(AwsConnectionMethod.AssumeRole),
+    credentials: AwsConnectionAssumeRoleCredentialsSchema.omit({ roleArn: true })
+  }),
+  BaseAwsConnectionSchema.extend({
+    method: z.literal(AwsConnectionMethod.AccessKey),
+    credentials: AwsConnectionAccessTokenCredentialsSchema.omit({ secretAccessKey: true })
+  })
+]);
+
+export const ValidateAwsConnectionCredentialsSchema = z.discriminatedUnion("method", [
+  z.object({
+    method: z.literal(AwsConnectionMethod.AssumeRole).describe(AppConnections?.CREATE(AppConnection.AWS).method),
+    credentials: AwsConnectionAssumeRoleCredentialsSchema.describe(AppConnections.CREATE(AppConnection.AWS).credentials)
+  }),
+  z.object({
+    method: z.literal(AwsConnectionMethod.AccessKey).describe(AppConnections?.CREATE(AppConnection.AWS).method),
+    credentials: AwsConnectionAccessTokenCredentialsSchema.describe(
+      AppConnections.CREATE(AppConnection.AWS).credentials
+    )
+  })
+]);
+
+export const CreateAwsConnectionSchema = ValidateAwsConnectionCredentialsSchema.and(
+  GenericCreateAppConnectionFieldsSchema(AppConnection.AWS)
+);
+
+export const UpdateAwsConnectionSchema = z
+  .object({
+    credentials: z
+      .union([AwsConnectionAccessTokenCredentialsSchema, AwsConnectionAssumeRoleCredentialsSchema])
+      .optional()
+      .describe(AppConnections.UPDATE(AppConnection.AWS).credentials)
+  })
+  .and(GenericUpdateAppConnectionFieldsSchema(AppConnection.AWS));
+
+export const AwsConnectionListItemSchema = z.object({
+  name: z.literal("AWS"),
+  app: z.literal(AppConnection.AWS),
+  // the below is preferable but currently breaks mintlify
+  // methods: z.tuple([z.literal(AwsConnectionMethod.AssumeRole), z.literal(AwsConnectionMethod.AccessKey)]),
+  methods: z.nativeEnum(AwsConnectionMethod).array(),
+  accessKeyId: z.string().optional()
+});

backend/src/services/app-connection/aws/aws-connection-types.ts

@@ -0,0 +1,22 @@
+import { z } from "zod";
+
+import { DiscriminativePick } from "@app/lib/types";
+import { AppConnection } from "@app/services/app-connection/app-connection-enums";
+
+import {
+  AwsConnectionSchema,
+  CreateAwsConnectionSchema,
+  ValidateAwsConnectionCredentialsSchema
+} from "./aws-connection-schemas";
+
+export type TAwsConnection = z.infer<typeof AwsConnectionSchema>;
+
+export type TAwsConnectionInput = z.infer<typeof CreateAwsConnectionSchema> & {
+  app: AppConnection.AWS;
+};
+
+export type TValidateAwsConnectionCredentials = typeof ValidateAwsConnectionCredentialsSchema;
+
+export type TAwsConnectionConfig = DiscriminativePick<TAwsConnectionInput, "method" | "app" | "credentials"> & {
+  orgId: string;
+};

backend/src/services/app-connection/aws/index.ts

@@ -0,0 +1,4 @@
+export * from "./aws-connection-enums";
+export * from "./aws-connection-fns";
+export * from "./aws-connection-schemas";
+export * from "./aws-connection-types";

backend/src/services/app-connection/github/github-connection-enums.ts

@@ -0,0 +1,4 @@
+export enum GitHubConnectionMethod {
+  OAuth = "oauth",
+  App = "github-app"
+}

backend/src/services/app-connection/github/github-connection-fns.ts

@@ -0,0 +1,129 @@
+import { AxiosResponse } from "axios";
+
+import { getConfig } from "@app/lib/config/env";
+import { request } from "@app/lib/config/request";
+import { BadRequestError, ForbiddenRequestError, InternalServerError } from "@app/lib/errors";
+import { getAppConnectionMethodName } from "@app/services/app-connection/app-connection-fns";
+import { IntegrationUrls } from "@app/services/integration-auth/integration-list";
+
+import { AppConnection } from "../app-connection-enums";
+import { GitHubConnectionMethod } from "./github-connection-enums";
+import { TGitHubConnectionConfig } from "./github-connection-types";
+
+export const getGitHubConnectionListItem = () => {
+  const { INF_APP_CONNECTION_GITHUB_OAUTH_CLIENT_ID, INF_APP_CONNECTION_GITHUB_APP_SLUG } = getConfig();
+
+  return {
+    name: "GitHub" as const,
+    app: AppConnection.GitHub as const,
+    methods: Object.values(GitHubConnectionMethod) as [GitHubConnectionMethod.App, GitHubConnectionMethod.OAuth],
+    oauthClientId: INF_APP_CONNECTION_GITHUB_OAUTH_CLIENT_ID,
+    appClientSlug: INF_APP_CONNECTION_GITHUB_APP_SLUG
+  };
+};
+
+type TokenRespData = {
+  access_token: string;
+  scope: string;
+  token_type: string;
+};
+
+export const validateGitHubConnectionCredentials = async (config: TGitHubConnectionConfig) => {
+  const { credentials, method } = config;
+
+  const {
+    INF_APP_CONNECTION_GITHUB_OAUTH_CLIENT_ID,
+    INF_APP_CONNECTION_GITHUB_OAUTH_CLIENT_SECRET,
+    INF_APP_CONNECTION_GITHUB_APP_CLIENT_ID,
+    INF_APP_CONNECTION_GITHUB_APP_CLIENT_SECRET,
+    SITE_URL
+  } = getConfig();
+
+  const { clientId, clientSecret } =
+    method === GitHubConnectionMethod.App
+      ? {
+          clientId: INF_APP_CONNECTION_GITHUB_APP_CLIENT_ID,
+          clientSecret: INF_APP_CONNECTION_GITHUB_APP_CLIENT_SECRET
+        }
+      : // oauth
+        {
+          clientId: INF_APP_CONNECTION_GITHUB_OAUTH_CLIENT_ID,
+          clientSecret: INF_APP_CONNECTION_GITHUB_OAUTH_CLIENT_SECRET
+        };
+
+  if (!clientId || !clientSecret) {
+    throw new InternalServerError({
+      message: `GitHub ${getAppConnectionMethodName(method)} environment variables have not been configured`
+    });
+  }
+
+  let tokenResp: AxiosResponse<TokenRespData>;
+
+  try {
+    tokenResp = await request.get<TokenRespData>("https://github.com/login/oauth/access_token", {
+      params: {
+        client_id: clientId,
+        client_secret: clientSecret,
+        code: credentials.code,
+        redirect_uri: `${SITE_URL}/app-connections/github/oauth/callback`
+      },
+      headers: {
+        Accept: "application/json",
+        "Accept-Encoding": "application/json"
+      }
+    });
+  } catch (e: unknown) {
+    throw new BadRequestError({
+      message: `Unable to validate connection - verify credentials`
+    });
+  }
+
+  if (tokenResp.status !== 200) {
+    throw new BadRequestError({
+      message: `Unable to validate credentials: GitHub responded with a status code of ${tokenResp.status} (${tokenResp.statusText}). Verify credentials and try again.`
+    });
+  }
+
+  if (method === GitHubConnectionMethod.App) {
+    const installationsResp = await request.get<{
+      installations: {
+        id: number;
+        account: {
+          login: string;
+        };
+      }[];
+    }>(IntegrationUrls.GITHUB_USER_INSTALLATIONS, {
+      headers: {
+        Accept: "application/json",
+        Authorization: `Bearer ${tokenResp.data.access_token}`,
+        "Accept-Encoding": "application/json"
+      }
+    });
+
+    const matchingInstallation = installationsResp.data.installations.find(
+      (installation) => installation.id === +credentials.installationId
+    );
+
+    if (!matchingInstallation) {
+      throw new ForbiddenRequestError({
+        message: "User does not have access to the provided installation"
+      });
+    }
+  }
+
+  switch (method) {
+    case GitHubConnectionMethod.App:
+      return {
+        // access token not needed for GitHub App
+        installationId: credentials.installationId
+      };
+    case GitHubConnectionMethod.OAuth:
+      return {
+        accessToken: tokenResp.data.access_token
+      };
+    default:
+      throw new InternalServerError({
+        message: `Unhandled GitHub connection method: ${method as GitHubConnectionMethod}`
+      });
+  }
+};

backend/src/services/app-connection/github/github-connection-schemas.ts

@@ -0,0 +1,93 @@
+import { z } from "zod";
+
+import { AppConnections } from "@app/lib/api-docs";
+import { AppConnection } from "@app/services/app-connection/app-connection-enums";
+import {
+  BaseAppConnectionSchema,
+  GenericCreateAppConnectionFieldsSchema,
+  GenericUpdateAppConnectionFieldsSchema
+} from "@app/services/app-connection/app-connection-schemas";
+
+import { GitHubConnectionMethod } from "./github-connection-enums";
+
+export const GitHubConnectionOAuthInputCredentialsSchema = z.object({
+  code: z.string().trim().min(1, "OAuth code required")
+});
+
+export const GitHubConnectionAppInputCredentialsSchema = z.object({
+  code: z.string().trim().min(1, "GitHub App code required"),
+  installationId: z.string().min(1, "GitHub App Installation ID required")
+});
+
+export const GitHubConnectionOAuthOutputCredentialsSchema = z.object({
+  accessToken: z.string()
+});
+
+export const GitHubConnectionAppOutputCredentialsSchema = z.object({
+  installationId: z.string()
+});
+
+export const ValidateGitHubConnectionCredentialsSchema = z.discriminatedUnion("method", [
+  z.object({
+    method: z.literal(GitHubConnectionMethod.App).describe(AppConnections.CREATE(AppConnection.GitHub).method),
+    credentials: GitHubConnectionAppInputCredentialsSchema.describe(
+      AppConnections.CREATE(AppConnection.GitHub).credentials
+    )
+  }),
+  z.object({
+    method: z.literal(GitHubConnectionMethod.OAuth).describe(AppConnections.CREATE(AppConnection.GitHub).method),
+    credentials: GitHubConnectionOAuthInputCredentialsSchema.describe(
+      AppConnections.CREATE(AppConnection.GitHub).credentials
+    )
+  })
+]);
+
+export const CreateGitHubConnectionSchema = ValidateGitHubConnectionCredentialsSchema.and(
+  GenericCreateAppConnectionFieldsSchema(AppConnection.GitHub)
+);
+
+export const UpdateGitHubConnectionSchema = z
+  .object({
+    credentials: z
+      .union([GitHubConnectionAppInputCredentialsSchema, GitHubConnectionOAuthInputCredentialsSchema])
+      .optional()
+      .describe(AppConnections.UPDATE(AppConnection.GitHub).credentials)
+  })
+  .and(GenericUpdateAppConnectionFieldsSchema(AppConnection.GitHub));
+
+const BaseGitHubConnectionSchema = BaseAppConnectionSchema.extend({ app: z.literal(AppConnection.GitHub) });
+
+export const GitHubAppConnectionSchema = z.intersection(
+  BaseGitHubConnectionSchema,
+  z.discriminatedUnion("method", [
+    z.object({
+      method: z.literal(GitHubConnectionMethod.App),
+      credentials: GitHubConnectionAppOutputCredentialsSchema
+    }),
+    z.object({
+      method: z.literal(GitHubConnectionMethod.OAuth),
+      credentials: GitHubConnectionOAuthOutputCredentialsSchema
+    })
+  ])
+);
+
+export const SanitizedGitHubConnectionSchema = z.discriminatedUnion("method", [
+  BaseGitHubConnectionSchema.extend({
+    method: z.literal(GitHubConnectionMethod.App),
+    credentials: GitHubConnectionAppOutputCredentialsSchema.omit({ installationId: true })
+  }),
+  BaseGitHubConnectionSchema.extend({
+    method: z.literal(GitHubConnectionMethod.OAuth),
+    credentials: GitHubConnectionOAuthOutputCredentialsSchema.omit({ accessToken: true })
+  })
+]);
+
+export const GitHubConnectionListItemSchema = z.object({
+  name: z.literal("GitHub"),
+  app: z.literal(AppConnection.GitHub),
+  // the below is preferable but currently breaks mintlify
+  // methods: z.tuple([z.literal(GitHubConnectionMethod.GitHubApp), z.literal(GitHubConnectionMethod.OAuth)]),
+  methods: z.nativeEnum(GitHubConnectionMethod).array(),
+  oauthClientId: z.string().optional(),
+  appClientSlug: z.string().optional()
+});

backend/src/services/app-connection/github/github-connection-types.ts

@@ -0,0 +1,20 @@
+import { z } from "zod";
+
+import { DiscriminativePick } from "@app/lib/types";
+
+import { AppConnection } from "../app-connection-enums";
+import {
+  CreateGitHubConnectionSchema,
+  GitHubAppConnectionSchema,
+  ValidateGitHubConnectionCredentialsSchema
+} from "./github-connection-schemas";
+
+export type TGitHubConnection = z.infer<typeof GitHubAppConnectionSchema>;
+
+export type TGitHubConnectionInput = z.infer<typeof CreateGitHubConnectionSchema> & {
+  app: AppConnection.GitHub;
+};
+
+export type TValidateGitHubConnectionCredentials = typeof ValidateGitHubConnectionCredentialsSchema;
+
+export type TGitHubConnectionConfig = DiscriminativePick<TGitHubConnectionInput, "method" | "app" | "credentials">;

backend/src/services/app-connection/github/index.ts

@@ -0,0 +1,4 @@
+export * from "./github-connection-enums";
+export * from "./github-connection-fns";
+export * from "./github-connection-schemas";
+export * from "./github-connection-types";