Merge pull request #2704 from trycompai/lewis/comp-background-checks

[dev] [carhartlewis] lewis/comp-background-checks

Author: carhartlewis

apps/api/.env.example

@@ -1,5 +1,7 @@
 BASE_URL="http://localhost:3333"
 BETTER_AUTH_URL="http://localhost:3000"
+NEXT_PUBLIC_APP_URL="http://localhost:3000"
+NODE_EXTRA_CA_CERTS=/etc/ssl/cert.pem
 PORT="3333"
 
 APP_AWS_BUCKET_NAME=
@@ -43,4 +45,11 @@ RESEND_API_KEY=
 RESEND_FROM_SYSTEM= # e.g., noreply@mail.trycomp.ai
 RESEND_FROM_DEFAULT= # e.g., hello@mail.trycomp.ai
 
-SECURITY_HUB_ROLE_ASSUMER_ARN=
+# Background checks
+BACKGROUND_CHECK_API_BASE_URL=https://glad-sturgeon-729.convex.site
+BACKGROUND_CHECK_API_KEY=
+BACKGROUND_CHECK_WEBHOOK_SECRET=
+BACKGROUND_WH_ENDPOINT=
+STRIPE_BACKGROUND_CHECK_PRICE_ID=price_1TRWckCkFWhKYvHIA1GLv1sO
+
+SECURITY_HUB_ROLE_ASSUMER_ARN=

apps/api/src/app.module.ts

@@ -52,6 +52,7 @@ import { StripeModule } from './stripe/stripe.module';
 import { AdminOrganizationsModule } from './admin-organizations/admin-organizations.module';
 import { AdminFeatureFlagsModule } from './admin-feature-flags/admin-feature-flags.module';
 import { TimelinesModule } from './timelines/timelines.module';
+import { BackgroundChecksModule } from './background-checks/background-checks.module';
 
 @Module({
   imports: [
@@ -113,6 +114,7 @@ import { TimelinesModule } from './timelines/timelines.module';
     SecretsModule,
     SecurityPenetrationTestsModule,
     StripeModule,
+    BackgroundChecksModule,
     AdminOrganizationsModule,
     AdminFeatureFlagsModule,
     TimelinesModule,

apps/api/src/attachments/upload-attachment.dto.ts

@@ -35,6 +35,7 @@ export class UploadAttachmentDto {
   })
   @IsString()
   @IsNotEmpty()
+  @MaxLength(134_217_728)
   @IsBase64()
   fileData: string;
 

apps/api/src/background-checks/background-check-billing.controller.ts

@@ -0,0 +1,70 @@
+import { Body, Controller, Get, HttpCode, Post, UseGuards } from '@nestjs/common';
+import { ApiOperation, ApiSecurity, ApiTags } from '@nestjs/swagger';
+import { OrganizationId } from '../auth/auth-context.decorator';
+import { HybridAuthGuard } from '../auth/hybrid-auth.guard';
+import { PermissionGuard } from '../auth/permission.guard';
+import { RequirePermission } from '../auth/require-permission.decorator';
+import { BackgroundCheckBillingService } from './background-check-billing.service';
+import {
+  BackgroundCheckBillingPortalDto,
+  BackgroundCheckSetupSessionDto,
+  BackgroundCheckSetupSuccessDto,
+} from './dto/background-check-billing.dto';
+
+@ApiTags('Background Check Billing')
+@Controller({ path: 'background-check-billing', version: '1' })
+@UseGuards(HybridAuthGuard, PermissionGuard)
+@ApiSecurity('apikey')
+export class BackgroundCheckBillingController {
+  constructor(private readonly billingService: BackgroundCheckBillingService) {}
+
+  @Get('status')
+  @RequirePermission('organization', 'read')
+  @ApiOperation({ summary: 'Get background check billing status' })
+  async getStatus(@OrganizationId() organizationId: string) {
+    return this.billingService.getStatus(organizationId);
+  }
+
+  @Post('setup-session')
+  @RequirePermission('organization', 'update')
+  @HttpCode(200)
+  @ApiOperation({ summary: 'Create a Stripe setup session for background checks' })
+  async setupSession(
+    @OrganizationId() organizationId: string,
+    @Body() body: BackgroundCheckSetupSessionDto,
+  ) {
+    return this.billingService.createSetupSession({
+      organizationId,
+      successUrl: body.successUrl,
+      cancelUrl: body.cancelUrl,
+    });
+  }
+
+  @Post('setup-success')
+  @RequirePermission('organization', 'update')
+  @HttpCode(200)
+  @ApiOperation({ summary: 'Handle successful background check billing setup' })
+  async setupSuccess(
+    @OrganizationId() organizationId: string,
+    @Body() body: BackgroundCheckSetupSuccessDto,
+  ) {
+    return this.billingService.handleSetupSuccess({
+      organizationId,
+      sessionId: body.sessionId,
+    });
+  }
+
+  @Post('portal')
+  @RequirePermission('organization', 'update')
+  @HttpCode(200)
+  @ApiOperation({ summary: 'Create a Stripe billing portal session' })
+  async portal(
+    @OrganizationId() organizationId: string,
+    @Body() body: BackgroundCheckBillingPortalDto,
+  ) {
+    return this.billingService.createBillingPortalSession({
+      organizationId,
+      returnUrl: body.returnUrl,
+    });
+  }
+}

apps/api/src/background-checks/background-check-billing.service.ts

@@ -0,0 +1,261 @@
+import {
+  BadRequestException,
+  Injectable,
+  NotFoundException,
+} from '@nestjs/common';
+import { db } from '@db';
+import { StripeService } from '../stripe/stripe.service';
+
+@Injectable()
+export class BackgroundCheckBillingService {
+  constructor(private readonly stripeService: StripeService) {}
+
+  async getStatus(organizationId: string): Promise<{
+    hasBilling: boolean;
+    hasPaymentMethod: boolean;
+    setupAt: Date | null;
+  }> {
+    const billing = await db.organizationBilling.findUnique({
+      where: { organizationId },
+      select: {
+        stripeCustomerId: true,
+        stripeBackgroundCheckPaymentMethodId: true,
+        backgroundCheckPaymentMethodSetupAt: true,
+      },
+    });
+
+    return {
+      hasBilling: !!billing,
+      hasPaymentMethod: !!billing?.stripeBackgroundCheckPaymentMethodId,
+      setupAt: billing?.backgroundCheckPaymentMethodSetupAt ?? null,
+    };
+  }
+
+  async createSetupSession({
+    organizationId,
+    successUrl,
+    cancelUrl,
+  }: {
+    organizationId: string;
+    successUrl: string;
+    cancelUrl: string;
+  }): Promise<{ url: string }> {
+    this.validateRedirectUrl(successUrl);
+    this.validateRedirectUrl(cancelUrl);
+
+    const stripe = this.stripeService.getClient();
+    const customerId = await this.findOrCreateCustomer(organizationId);
+    const price = await this.getBackgroundCheckPrice();
+
+    const session = await stripe.checkout.sessions.create({
+      mode: 'setup',
+      customer: customerId,
+      currency: price.currency,
+      success_url: successUrl,
+      cancel_url: cancelUrl,
+      metadata: {
+        organizationId,
+        source: 'comp-background-check',
+      },
+    });
+
+    if (!session.url) {
+      throw new BadRequestException('Failed to create Stripe Checkout session.');
+    }
+
+    return { url: session.url };
+  }
+
+  async handleSetupSuccess({
+    organizationId,
+    sessionId,
+  }: {
+    organizationId: string;
+    sessionId: string;
+  }): Promise<{ success: true }> {
+    const stripe = this.stripeService.getClient();
+    const session = await stripe.checkout.sessions.retrieve(sessionId, {
+      expand: ['setup_intent'],
+    });
+
+    if (session.status !== 'complete') {
+      throw new BadRequestException('Checkout session is not complete.');
+    }
+
+    if (session.metadata?.organizationId && session.metadata.organizationId !== organizationId) {
+      throw new BadRequestException('Checkout session does not belong to this organization.');
+    }
+
+    const stripeCustomerId = this.extractStripeId(session.customer);
+    if (!stripeCustomerId) {
+      throw new BadRequestException('Checkout session is missing a customer.');
+    }
+
+    await this.assertCustomerBelongsToOrganization({
+      organizationId,
+      stripeCustomerId,
+    });
+
+    const setupIntent = session.setup_intent;
+    if (!setupIntent || typeof setupIntent === 'string') {
+      throw new BadRequestException('Checkout session is missing a setup intent.');
+    }
+
+    const paymentMethodId = this.extractStripeId(setupIntent.payment_method);
+    if (!paymentMethodId) {
+      throw new BadRequestException('Setup intent is missing a payment method.');
+    }
+
+    await stripe.customers.update(stripeCustomerId, {
+      invoice_settings: {
+        default_payment_method: paymentMethodId,
+      },
+    });
+
+    await db.organizationBilling.upsert({
+      where: { organizationId },
+      create: {
+        organizationId,
+        stripeCustomerId,
+        stripeBackgroundCheckPaymentMethodId: paymentMethodId,
+        backgroundCheckPaymentMethodSetupAt: new Date(),
+      },
+      update: {
+        stripeCustomerId,
+        stripeBackgroundCheckPaymentMethodId: paymentMethodId,
+        backgroundCheckPaymentMethodSetupAt: new Date(),
+      },
+    });
+
+    return { success: true };
+  }
+
+  async createBillingPortalSession({
+    organizationId,
+    returnUrl,
+  }: {
+    organizationId: string;
+    returnUrl: string;
+  }): Promise<{ url: string }> {
+    this.validateRedirectUrl(returnUrl);
+
+    const stripe = this.stripeService.getClient();
+    const billing = await db.organizationBilling.findUnique({
+      where: { organizationId },
+      select: { stripeCustomerId: true },
+    });
+
+    if (!billing) {
+      throw new NotFoundException('No billing record found for this organization.');
+    }
+
+    const portalSession = await stripe.billingPortal.sessions.create({
+      customer: billing.stripeCustomerId,
+      return_url: returnUrl,
+    });
+
+    return { url: portalSession.url };
+  }
+
+  async findOrCreateCustomer(organizationId: string): Promise<string> {
+    const existingBilling = await db.organizationBilling.findUnique({
+      where: { organizationId },
+      select: { stripeCustomerId: true },
+    });
+
+    if (existingBilling) {
+      return existingBilling.stripeCustomerId;
+    }
+
+    const organization = await db.organization.findUnique({
+      where: { id: organizationId },
+      select: { name: true },
+    });
+
+    if (!organization) {
+      throw new NotFoundException('Organization not found.');
+    }
+
+    const stripe = this.stripeService.getClient();
+    const customer = await stripe.customers.create({
+      name: organization.name,
+      metadata: { organizationId },
+    });
+
+    await db.organizationBilling.create({
+      data: {
+        organizationId,
+        stripeCustomerId: customer.id,
+      },
+    });
+
+    return customer.id;
+  }
+
+  async getBackgroundCheckPrice(): Promise<{ id: string; unitAmount: number; currency: string }> {
+    const priceId = process.env.STRIPE_BACKGROUND_CHECK_PRICE_ID;
+    if (!priceId) {
+      throw new BadRequestException('Background check pricing is not configured. Contact support.');
+    }
+
+    const stripe = this.stripeService.getClient();
+    const price = await stripe.prices.retrieve(priceId);
+    if (price.unit_amount === null || price.unit_amount === undefined) {
+      throw new BadRequestException('Background check pricing is not configured. Contact support.');
+    }
+
+    return {
+      id: price.id,
+      unitAmount: price.unit_amount,
+      currency: price.currency,
+    };
+  }
+
+  private validateRedirectUrl(url: string): void {
+    const appUrl =
+      process.env.NEXT_PUBLIC_APP_URL || process.env.APP_URL || process.env.BETTER_AUTH_URL;
+    if (!appUrl) {
+      throw new BadRequestException('App URL is not configured on the server.');
+    }
+
+    let parsed: URL;
+    try {
+      parsed = new URL(url);
+    } catch {
+      throw new BadRequestException('Invalid redirect URL.');
+    }
+
+    if (parsed.origin !== new URL(appUrl).origin) {
+      throw new BadRequestException('Redirect URL must belong to the application origin.');
+    }
+  }
+
+  private extractStripeId(value: string | { id?: string } | null): string | null {
+    if (!value) return null;
+    if (typeof value === 'string') return value;
+    return value.id ?? null;
+  }
+
+  private async assertCustomerBelongsToOrganization({
+    organizationId,
+    stripeCustomerId,
+  }: {
+    organizationId: string;
+    stripeCustomerId: string;
+  }): Promise<void> {
+    const billing = await db.organizationBilling.findUnique({
+      where: { organizationId },
+      select: { stripeCustomerId: true },
+    });
+
+    if (billing?.stripeCustomerId === stripeCustomerId) {
+      return;
+    }
+
+    const stripe = this.stripeService.getClient();
+    const customer = await stripe.customers.retrieve(stripeCustomerId);
+    if (customer.deleted || customer.metadata?.organizationId !== organizationId) {
+      throw new BadRequestException('Checkout session does not belong to this organization.');
+    }
+  }
+}