fix(payments): harden Comgate first-checkout and renumber migration

Extract resolveComgateCheckoutIdentity so first-purchase webhooks resolve
the user from payment_checkout_sessions (migration 0010). Fail closed if
the pending session cannot be persisted at checkout. Align docs/tests for
past_due on payment.failed and renumber settings migration to 0056 to
avoid colliding with 0045_native_clients.

Co-authored-by: Jakub Doboš <kubo6472@users.noreply.github.com>

Author: cursoragent

…grations/0045_gopay_payment_settings.sql …grations/0056_gopay_payment_settings.sqlpackages/api/migrations/0045_gopay_payment_settings.sql renamed to packages/api/migrations/0056_gopay_payment_settings.sql packages/api/migrations/0045_gopay_payment_settings.sql renamed to packages/api/migrations/0056_gopay_payment_settings.sql

@@ -206,6 +206,69 @@ function normalizePlanType(planType: string): PlanType {
   return 'monthly';
 }
 
+/**
+ * Resolve the paying user for a Comgate webhook when no subscription row exists yet
+ * (first checkout). Relies on `payment_checkout_sessions` from migration
+ * `0010_gocardless_payments.sql` — written at checkout creation with
+ * `checkout_token = refId` and `provider_checkout_id = transId`.
+ */
+export async function resolveComgateCheckoutIdentity(
+  db: {
+    prepare: (sql: string) => {
+      bind: (...args: unknown[]) => {
+        first: () => Promise<{ id?: unknown; user_id?: unknown; plan_type?: unknown } | null>;
+      };
+    };
+  },
+  opts: { subscriptionId: string; purchaseId: string },
+): Promise<{
+  userId: string;
+  planType: PlanType;
+  pendingSessionId: string | null;
+  fromPendingSession: boolean;
+} | null> {
+  const subscriptionId = String(opts.subscriptionId ?? '').trim();
+  const purchaseId = String(opts.purchaseId ?? '').trim();
+  if (!subscriptionId && !purchaseId) return null;
+
+  const existing = await db
+    .prepare(
+      `SELECT user_id, plan_type FROM subscriptions
+       WHERE provider = 'comgate' AND (provider_subscription_id = ? OR purchase_id = ?)
+       LIMIT 1`,
+    )
+    .bind(subscriptionId, purchaseId || subscriptionId)
+    .first();
+
+  if (existing?.user_id) {
+    return {
+      userId: String(existing.user_id).trim(),
+      planType: normalizePlanType(String(existing.plan_type ?? 'monthly')),
+      pendingSessionId: null,
+      fromPendingSession: false,
+    };
+  }
+
+  const pending = await db
+    .prepare(
+      `SELECT id, user_id, plan_type FROM payment_checkout_sessions
+       WHERE provider = 'comgate' AND status = 'pending'
+         AND (checkout_token = ? OR provider_checkout_id = ?)
+       LIMIT 1`,
+    )
+    .bind(purchaseId || subscriptionId, subscriptionId || purchaseId)
+    .first();
+
+  if (!pending?.user_id) return null;
+
+  return {
+    userId: String(pending.user_id).trim(),
+    planType: normalizePlanType(String(pending.plan_type ?? 'monthly')),
+    pendingSessionId: String(pending.id ?? '').trim() || null,
+    fromPendingSession: true,
+  };
+}
+
 async function upsertSubscriptionRow(
   db: any,
   params: {
@@ -1204,19 +1267,30 @@ export async function handleCheckout(request: any, env: any, corsHeaders: any) {
     }
     if (session.checkoutUrl) {
       if (apiProvider === 'comgate') {
+        // Comgate cannot carry free-form metadata on the payment object. Persist a
+        // pending payment_checkout_sessions row (table from migration 0010) so the
+        // webhook can resolve userId/planType on first purchase.
         const refId = String(session.metadata?.refId ?? '').trim();
         const orderId = String(session.orderId ?? '').trim();
-        if (refId && orderId) {
-          await db
-            .prepare(
-              `INSERT INTO payment_checkout_sessions (
-                id, user_id, provider, plan_type, checkout_token, provider_checkout_id, status,
-                created_at, updated_at
-              ) VALUES (?, ?, 'comgate', ?, ?, ?, 'pending', CURRENT_TIMESTAMP, CURRENT_TIMESTAMP)`,
-            )
-            .bind(crypto.randomUUID(), user.sub, planType, refId, orderId)
-            .run();
+        if (!refId || !orderId) {
+          return jsonResponse(
+            {
+              error: 'Failed to create checkout session',
+              code: 'checkout_session_persist_failed',
+            },
+            502,
+            corsHeaders,
+          );
         }
+        await db
+          .prepare(
+            `INSERT INTO payment_checkout_sessions (
+              id, user_id, provider, plan_type, checkout_token, provider_checkout_id, status,
+              created_at, updated_at
+            ) VALUES (?, ?, 'comgate', ?, ?, ?, 'pending', CURRENT_TIMESTAMP, CURRENT_TIMESTAMP)`,
+          )
+          .bind(crypto.randomUUID(), user.sub, planType, refId, orderId)
+          .run();
       }
       return jsonResponse(
         {
@@ -1616,11 +1690,6 @@ export async function handleGoPayWebhook(request: any, env: any, corsHeaders: an
   }
 }
 
-/**
- * POST /api/payments/webhook/comgate — NO auth (Comgate calls this)
- * Notifications include `secret` for verification; status is re-verified via API.
- * Must reply `code=0&message=OK`.
- */
 /**
  * POST /api/payments/webhook/comgate — NO auth (Comgate calls this)
  * Notifications include `secret` for verification; status is re-verified via API.
@@ -1669,47 +1738,23 @@ export async function handleComgateWebhook(request: any, env: any, corsHeaders:
           headers: { 'Content-Type': 'application/x-www-form-urlencoded', ...corsHeaders },
         });
       }
-      const existing = await db
-        .prepare(
-          `SELECT user_id, plan_type FROM subscriptions
-           WHERE provider = 'comgate' AND (provider_subscription_id = ? OR purchase_id = ?)
-           LIMIT 1`,
-        )
-        .bind(subscriptionId, purchaseId || subscriptionId)
-        .first();
-
-      let userId = String(existing?.user_id ?? '').trim();
-      let planType = normalizePlanType(String(existing?.plan_type ?? 'monthly'));
-      let pendingSessionId: string | null = null;
 
-      if (!userId) {
-        const pending = await db
-          .prepare(
-            `SELECT id, user_id, plan_type FROM payment_checkout_sessions
-             WHERE provider = 'comgate' AND status = 'pending'
-               AND (checkout_token = ? OR provider_checkout_id = ?)
-             LIMIT 1`,
-          )
-          .bind(purchaseId || subscriptionId, subscriptionId)
-          .first();
-        if (pending?.user_id) {
-          userId = String(pending.user_id).trim();
-          planType = normalizePlanType(String(pending.plan_type ?? planType));
-          pendingSessionId = String(pending.id ?? '').trim() || null;
-        }
-      }
+      const identity = await resolveComgateCheckoutIdentity(db, {
+        subscriptionId,
+        purchaseId,
+      });
 
-      if (userId) {
+      if (identity?.userId) {
         await upsertSubscriptionRow(db, {
-          userId,
-          planType,
+          userId: identity.userId,
+          planType: identity.planType,
           status: 'active',
           provider: 'comgate',
           providerSubscriptionId: subscriptionId,
-          providerCustomerId: userId,
-          currentPeriodEnd: periodEndIsoForPlan(planType),
+          providerCustomerId: identity.userId,
+          currentPeriodEnd: periodEndIsoForPlan(identity.planType),
         });
-        if (pendingSessionId) {
+        if (identity.fromPendingSession && identity.pendingSessionId) {
           await db
             .prepare(
               `UPDATE payment_checkout_sessions
@@ -1719,17 +1764,27 @@ export async function handleComgateWebhook(request: any, env: any, corsHeaders:
                    updated_at = CURRENT_TIMESTAMP
                WHERE id = ? AND status = 'pending'`,
             )
-            .bind(subscriptionId, pendingSessionId)
+            .bind(subscriptionId, identity.pendingSessionId)
             .run();
         }
         try {
-          await syncSubscriptionNewsletter(db, userId, 'active', env);
+          await syncSubscriptionNewsletter(db, identity.userId, 'active', env);
         } catch (brevoErr) {
-          console.error('[comgate webhook] newsletter sync failed', { userId, err: brevoErr });
+          console.error('[comgate webhook] newsletter sync failed', {
+            userId: identity.userId,
+            err: brevoErr,
+          });
         }
+      } else {
+        console.warn('[comgate webhook] checkout completed without resolvable user', {
+          subscriptionId,
+          purchaseId,
+        });
       }
     }
 
+    // Match GoPay / Stripe: failed renewals enter a grace period (past_due), not
+    // immediate cancellation.
     if (event.type === 'payment.failed') {
       if (subscriptionId) {
         const existing = await db

packages/api/src/paymentProcessor.ts

@@ -0,0 +1,173 @@
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import { resolveComgateCheckoutIdentity } from '../src/paymentProcessor.js';
+
+type Row = Record<string, unknown>;
+
+class FakeDb {
+  subscriptions: Row[];
+  sessions: Row[];
+  lastSql = '';
+  lastArgs: unknown[] = [];
+
+  constructor(opts?: { subscriptions?: Row[]; sessions?: Row[] }) {
+    this.subscriptions = opts?.subscriptions ?? [];
+    this.sessions = opts?.sessions ?? [];
+  }
+
+  prepare(sql: string) {
+    const db = this;
+    return {
+      bind(...args: unknown[]) {
+        db.lastSql = sql;
+        db.lastArgs = args;
+        return this;
+      },
+      async first(): Promise<Row | null> {
+        if (sql.includes('FROM subscriptions') && sql.includes("provider = 'comgate'")) {
+          const [subscriptionId, purchaseId] = db.lastArgs as [string, string];
+          return (
+            db.subscriptions.find(
+              (row) =>
+                row.provider_subscription_id === subscriptionId ||
+                row.purchase_id === purchaseId ||
+                row.purchase_id === subscriptionId,
+            ) ?? null
+          );
+        }
+        if (sql.includes('FROM payment_checkout_sessions')) {
+          const [tokenOrPurchase, checkoutId] = db.lastArgs as [string, string];
+          return (
+            db.sessions.find(
+              (row) =>
+                row.provider === 'comgate' &&
+                row.status === 'pending' &&
+                (row.checkout_token === tokenOrPurchase ||
+                  row.provider_checkout_id === checkoutId ||
+                  row.provider_checkout_id === tokenOrPurchase),
+            ) ?? null
+          );
+        }
+        return null;
+      },
+    };
+  }
+}
+
+describe('resolveComgateCheckoutIdentity', () => {
+  it('returns null when neither subscription nor pending session exists (first-checkout bug regression)', async () => {
+    const db = new FakeDb();
+    const result = await resolveComgateCheckoutIdentity(db, {
+      subscriptionId: 'AB12-CD34-EF56',
+      purchaseId: 'vmp-user1-1',
+    });
+    assert.equal(result, null);
+  });
+
+  it('resolves first-time subscriber from pending payment_checkout_sessions by refId', async () => {
+    const db = new FakeDb({
+      sessions: [
+        {
+          id: 'sess-1',
+          provider: 'comgate',
+          status: 'pending',
+          checkout_token: 'vmp-user1-1',
+          provider_checkout_id: 'AB12-CD34-EF56',
+          user_id: 'user-1',
+          plan_type: 'yearly',
+        },
+      ],
+    });
+    const result = await resolveComgateCheckoutIdentity(db, {
+      subscriptionId: 'AB12-CD34-EF56',
+      purchaseId: 'vmp-user1-1',
+    });
+    assert.deepEqual(result, {
+      userId: 'user-1',
+      planType: 'yearly',
+      pendingSessionId: 'sess-1',
+      fromPendingSession: true,
+    });
+  });
+
+  it('resolves first-time subscriber from pending session by transId when refId missing', async () => {
+    const db = new FakeDb({
+      sessions: [
+        {
+          id: 'sess-2',
+          provider: 'comgate',
+          status: 'pending',
+          checkout_token: 'vmp-user2-9',
+          provider_checkout_id: 'ZZ99-YY88-XX77',
+          user_id: 'user-2',
+          plan_type: 'monthly',
+        },
+      ],
+    });
+    const result = await resolveComgateCheckoutIdentity(db, {
+      subscriptionId: 'ZZ99-YY88-XX77',
+      purchaseId: '',
+    });
+    assert.deepEqual(result, {
+      userId: 'user-2',
+      planType: 'monthly',
+      pendingSessionId: 'sess-2',
+      fromPendingSession: true,
+    });
+  });
+
+  it('prefers existing subscription row over pending session on renewals', async () => {
+    const db = new FakeDb({
+      subscriptions: [
+        {
+          user_id: 'user-renew',
+          plan_type: 'club',
+          provider_subscription_id: 'AB12-CD34-EF56',
+          purchase_id: 'vmp-user1-1',
+        },
+      ],
+      sessions: [
+        {
+          id: 'sess-stale',
+          provider: 'comgate',
+          status: 'pending',
+          checkout_token: 'vmp-user1-1',
+          provider_checkout_id: 'AB12-CD34-EF56',
+          user_id: 'should-not-win',
+          plan_type: 'monthly',
+        },
+      ],
+    });
+    const result = await resolveComgateCheckoutIdentity(db, {
+      subscriptionId: 'AB12-CD34-EF56',
+      purchaseId: 'vmp-user1-1',
+    });
+    assert.deepEqual(result, {
+      userId: 'user-renew',
+      planType: 'club',
+      pendingSessionId: null,
+      fromPendingSession: false,
+    });
+  });
+
+  it('ignores non-pending checkout sessions', async () => {
+    const db = new FakeDb({
+      sessions: [
+        {
+          id: 'sess-done',
+          provider: 'comgate',
+          status: 'completed',
+          checkout_token: 'vmp-user1-1',
+          provider_checkout_id: 'AB12-CD34-EF56',
+          user_id: 'user-1',
+          plan_type: 'monthly',
+        },
+      ],
+    });
+    const result = await resolveComgateCheckoutIdentity(db, {
+      subscriptionId: 'AB12-CD34-EF56',
+      purchaseId: 'vmp-user1-1',
+    });
+    assert.equal(result, null);
+  });
+});

packages/api/test/comgate-checkout-identity.test.ts

@@ -68,7 +68,7 @@ This draft therefore never promises native Apple/Google Pay; checkout always red
 
 ## Comgate draft behaviour
 
-1. **Checkout** — `POST /api/payments/payment` creates a Comgate payment with `initRecurring=true` and returns a `redirect` URL. A pending row in `payment_checkout_sessions` (keyed by `refId` / `transId`) stores the user and plan until the webhook fires.
+1. **Checkout** — `POST /api/payments/payment` creates a Comgate payment with `initRecurring=true` and returns a `redirect` URL. A pending row in `payment_checkout_sessions` (table from migration `0010_gocardless_payments.sql`; keyed by `refId` / `transId`) stores the user and plan until the webhook fires. Checkout fails closed if that row cannot be written.
 2. **Webhook** — Comgate sends **POST** callbacks with a `secret` field. The Worker verifies the secret, re-fetches status via `/v1.0/status`, and resolves the paying user from the pending checkout session (first purchase) or an existing subscription row (renewals).
 3. **Cancel** — `POST /v1.0/cancel` on the stored `provider_subscription_id` (Comgate `transId`).
 4. **Failed renewal** — maps to `past_due` (same grace-period policy as GoPay), not immediate cancellation.