fix(billing): serialize checkout admission

Author: icecrasher321

apps/sim/lib/auth/auth.ts

@@ -38,13 +38,20 @@ import {
 } from '@/lib/auth/constants'
 import { getSessionCookieCacheVersion } from '@/lib/auth/security-policy'
 import { clampExpiryForSession } from '@/lib/auth/session-policy'
+import { getActiveOrganizationId } from '@/lib/auth/session-response'
 import { guardSubscriptionPlanWrites } from '@/lib/auth/stripe-adapter-guard'
 import { sendPlanWelcomeEmail } from '@/lib/billing'
 import {
   assertPersonalCheckoutAllowed,
   authorizeSubscriptionReference,
   isPersonalCheckoutRequest,
 } from '@/lib/billing/authorization'
+import {
+  type CheckoutAdmissionClaim,
+  claimCheckoutAdmission,
+  releaseCheckoutAdmission,
+  resolveCheckoutReferenceId,
+} from '@/lib/billing/checkout-admission'
 import {
   getOrganizationIdForSubscriptionReference,
   syncSubscriptionPlan,
@@ -1008,13 +1015,39 @@ export const auth = betterAuth({
       if (isBillingEnabled && ctx.path === '/subscription/upgrade') {
         const session = await getSessionFromCtx(ctx)
         const sessionUserId = session?.user?.id
-        if (sessionUserId && isPersonalCheckoutRequest(ctx.body ?? {}, sessionUserId)) {
-          await assertPersonalCheckoutAllowed(sessionUserId)
+        if (sessionUserId) {
+          const requestBody = ctx.body ?? {}
+          const referenceId = resolveCheckoutReferenceId(
+            requestBody,
+            sessionUserId,
+            getActiveOrganizationId(session)
+          )
+          if (referenceId) {
+            const checkoutAdmissionClaim = await claimCheckoutAdmission(referenceId)
+            try {
+              if (isPersonalCheckoutRequest(requestBody, sessionUserId)) {
+                await assertPersonalCheckoutAllowed(sessionUserId)
+              }
+            } catch (error) {
+              await releaseCheckoutAdmission(checkoutAdmissionClaim)
+              throw error
+            }
+            return { context: { billingCheckoutAdmissionClaim: checkoutAdmissionClaim } }
+          }
         }
       }
 
       return
     }),
+    after: createAuthMiddleware(async (ctx) => {
+      if (!isBillingEnabled || ctx.path !== '/subscription/upgrade') return
+      const context = ctx.context as typeof ctx.context & {
+        billingCheckoutAdmissionClaim?: CheckoutAdmissionClaim
+      }
+      if (context.billingCheckoutAdmissionClaim) {
+        await releaseCheckoutAdmission(context.billingCheckoutAdmissionClaim)
+      }
+    }),
   },
   plugins: [
     ...(env.TURNSTILE_SECRET_KEY

apps/sim/lib/auth/stripe-adapter-guard.test.ts

@@ -160,18 +160,19 @@ describe('guardSubscriptionPlanWrites', () => {
     base.findOne.mockResolvedValueOnce(personalPro)
 
     const guarded = asAdapter(base)
-    const result = await guarded.update({
-      model: 'subscription',
-      where: [{ field: 'id', value: personalPro.id }] as never,
-      update: {
-        stripeSubscriptionId: 'sub_enterprise',
-        status: 'active',
-        periodEnd: new Date('2026-09-11T18:36:09Z'),
-        billingInterval: 'month',
-      },
-    })
+    await expect(
+      guarded.update({
+        model: 'subscription',
+        where: [{ field: 'id', value: personalPro.id }] as never,
+        update: {
+          stripeSubscriptionId: 'sub_enterprise',
+          status: 'active',
+          periodEnd: new Date('2026-09-11T18:36:09Z'),
+          billingInterval: 'month',
+        },
+      })
+    ).rejects.toThrow(/already bound to Stripe subscription sub_personal_pro/)
 
-    expect(result).toBeNull()
     expect(base.update).not.toHaveBeenCalled()
   })
 

apps/sim/lib/auth/stripe-adapter-guard.ts

@@ -86,17 +86,20 @@ function guardWriteSurface<TAdapter extends SubscriptionWriteSurface>(
         })
 
         if (row && attemptsStripeSubscriptionRebind(row, data.update)) {
+          const rejectedStripeSubscriptionId = (data.update as { stripeSubscriptionId: string })
+            .stripeSubscriptionId
           logger.error(
             'Blocked rebinding an existing subscription to a different Stripe subscription',
             {
               subscriptionId: row.id,
               referenceId: row.referenceId,
               currentStripeSubscriptionId: row.stripeSubscriptionId,
-              rejectedStripeSubscriptionId: (data.update as { stripeSubscriptionId: string })
-                .stripeSubscriptionId,
+              rejectedStripeSubscriptionId,
             }
           )
-          return null as never
+          throw new Error(
+            `Subscription ${row.id} is already bound to Stripe subscription ${row.stripeSubscriptionId}; refusing to bind ${rejectedStripeSubscriptionId}`
+          )
         }
 
         if (!hasNonOrgPlanWrite(data.update)) return adapter.update(data)

apps/sim/lib/billing/checkout-admission.test.ts

@@ -0,0 +1,109 @@
+/**
+ * @vitest-environment node
+ */
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const { mockAtomicallyClaim, mockRelease, mockIdempotencyService } = vi.hoisted(() => ({
+  mockAtomicallyClaim: vi.fn(),
+  mockRelease: vi.fn(),
+  mockIdempotencyService: vi.fn(),
+}))
+
+vi.mock('@/lib/core/idempotency/service', () => ({
+  IdempotencyService: class MockIdempotencyService {
+    constructor(options: unknown) {
+      mockIdempotencyService(options)
+    }
+
+    atomicallyClaim(...args: unknown[]) {
+      return mockAtomicallyClaim(...args)
+    }
+
+    release(...args: unknown[]) {
+      return mockRelease(...args)
+    }
+  },
+}))
+
+import {
+  claimCheckoutAdmission,
+  releaseCheckoutAdmission,
+  resolveCheckoutReferenceId,
+} from '@/lib/billing/checkout-admission'
+
+describe('checkout admission', () => {
+  beforeEach(() => {
+    mockAtomicallyClaim.mockReset()
+    mockRelease.mockReset()
+    mockRelease.mockResolvedValue(undefined)
+  })
+
+  it('uses durable, short-lived database claims', () => {
+    expect(mockIdempotencyService).toHaveBeenCalledWith({
+      namespace: 'billing-checkout-admission',
+      ttlSeconds: 120,
+      inProgressTtlSeconds: 120,
+      retryFailures: true,
+      storeResultBody: false,
+      forceStorage: 'database',
+    })
+  })
+
+  it('resolves explicit, organization, and personal references like Better Auth', () => {
+    expect(
+      resolveCheckoutReferenceId({ referenceId: 'org-explicit' }, 'user-1', 'org-active')
+    ).toBe('org-explicit')
+    expect(
+      resolveCheckoutReferenceId({ customerType: 'organization' }, 'user-1', 'org-active')
+    ).toBe('org-active')
+    expect(resolveCheckoutReferenceId({}, 'user-1', 'org-active')).toBe('user-1')
+  })
+
+  it('admits only one overlapping checkout for a billing reference', async () => {
+    mockAtomicallyClaim
+      .mockResolvedValueOnce({
+        claimed: true,
+        normalizedKey: 'billing-checkout-admission:stripe:org-1',
+        storageMethod: 'database',
+        claimToken: 'claim-1',
+      })
+      .mockResolvedValueOnce({
+        claimed: false,
+        normalizedKey: 'billing-checkout-admission:stripe:org-1',
+        storageMethod: 'database',
+        existingResult: { status: 'in-progress' },
+      })
+
+    const firstClaim = await claimCheckoutAdmission('org-1')
+    await expect(claimCheckoutAdmission('org-1')).rejects.toThrow(
+      /checkout is already being started/
+    )
+    expect(firstClaim.claimToken).toBe('claim-1')
+  })
+
+  it('releases only the claim owned by this request', async () => {
+    await releaseCheckoutAdmission({
+      normalizedKey: 'billing-checkout-admission:stripe:org-1',
+      storageMethod: 'database',
+      claimToken: 'claim-1',
+    })
+
+    expect(mockRelease).toHaveBeenCalledWith(
+      'billing-checkout-admission:stripe:org-1',
+      'database',
+      'claim-1'
+    )
+  })
+
+  it('does not replace a successful checkout response when release fails', async () => {
+    mockRelease.mockRejectedValueOnce(new Error('database unavailable'))
+
+    await expect(
+      releaseCheckoutAdmission({
+        normalizedKey: 'billing-checkout-admission:stripe:org-1',
+        storageMethod: 'database',
+        claimToken: 'claim-1',
+      })
+    ).resolves.toBeUndefined()
+  })
+})

apps/sim/lib/billing/checkout-admission.ts

@@ -0,0 +1,86 @@
+import { createLogger } from '@sim/logger'
+import { getErrorMessage } from '@sim/utils/errors'
+import { APIError } from 'better-auth/api'
+import { type AtomicClaimResult, IdempotencyService } from '@/lib/core/idempotency/service'
+
+const logger = createLogger('BillingCheckoutAdmission')
+
+const CHECKOUT_ADMISSION_LEASE_SECONDS = 2 * 60
+
+const checkoutAdmissionLeases = new IdempotencyService({
+  namespace: 'billing-checkout-admission',
+  ttlSeconds: CHECKOUT_ADMISSION_LEASE_SECONDS,
+  inProgressTtlSeconds: CHECKOUT_ADMISSION_LEASE_SECONDS,
+  retryFailures: true,
+  storeResultBody: false,
+  forceStorage: 'database',
+})
+
+export interface CheckoutAdmissionClaim {
+  normalizedKey: string
+  storageMethod: AtomicClaimResult['storageMethod']
+  claimToken: string
+}
+
+/**
+ * Resolves the billing reference using the same precedence as Better Auth's
+ * Stripe `referenceMiddleware`: an explicit reference wins, otherwise an
+ * organization checkout uses the active organization and a personal checkout
+ * uses the session user.
+ */
+export function resolveCheckoutReferenceId(
+  body: { referenceId?: unknown; customerType?: unknown },
+  sessionUserId: string,
+  activeOrganizationId: string | null
+): string | null {
+  if (body.referenceId) {
+    return typeof body.referenceId === 'string' ? body.referenceId : null
+  }
+  if (body.customerType === 'organization') return activeOrganizationId
+  return sessionUserId
+}
+
+/**
+ * Atomically reserves one in-flight checkout request per billing reference.
+ * The claim spans Better Auth's local-row preparation and Stripe Checkout
+ * creation, closing the window where two requests could both pass a read-only
+ * admission check before either one bound a subscription.
+ */
+export async function claimCheckoutAdmission(referenceId: string): Promise<CheckoutAdmissionClaim> {
+  const claim = await checkoutAdmissionLeases.atomicallyClaim('stripe', referenceId)
+  if (!claim.claimed) {
+    logger.warn('Blocking concurrent subscription checkout', { referenceId })
+    throw new APIError('CONFLICT', {
+      message:
+        'A subscription checkout is already being started. Please wait a moment and try again.',
+    })
+  }
+  if (!claim.claimToken) {
+    throw new Error('Checkout admission claim is missing its fencing token')
+  }
+  return {
+    normalizedKey: claim.normalizedKey,
+    storageMethod: claim.storageMethod,
+    claimToken: claim.claimToken,
+  }
+}
+
+/**
+ * Releases a checkout admission claim without masking the endpoint result.
+ * A failed release is bounded by the claim's short lease and remains visible
+ * in logs for operators.
+ */
+export async function releaseCheckoutAdmission(claim: CheckoutAdmissionClaim): Promise<void> {
+  try {
+    await checkoutAdmissionLeases.release(
+      claim.normalizedKey,
+      claim.storageMethod,
+      claim.claimToken
+    )
+  } catch (error) {
+    logger.warn('Failed to release checkout admission claim; lease will expire', {
+      normalizedKey: claim.normalizedKey,
+      error: getErrorMessage(error, 'Unknown error'),
+    })
+  }
+}