fix(referrals): enforce Kilo Pass referral rules

Author: jeanduplessis

apps/web/src/app/api/cron/kilo-pass-expire-referral-rewards/route.ts

@@ -0,0 +1,35 @@
+import { NextResponse } from 'next/server';
+
+import { CRON_SECRET } from '@/lib/config.server';
+import { expirePendingKiloPassReferralRewards } from '@/lib/impact/kilo-pass-referrals';
+import { sentryLogger } from '@/lib/utils.server';
+
+if (!CRON_SECRET) {
+  throw new Error('CRON_SECRET is not configured in environment variables');
+}
+
+export async function GET(request: Request) {
+  const authHeader = request.headers.get('authorization');
+  const expectedAuth = `Bearer ${CRON_SECRET}`;
+  if (authHeader !== expectedAuth) {
+    sentryLogger(
+      'cron',
+      'warning'
+    )(
+      'SECURITY: Invalid CRON job authorization attempt: ' +
+        (authHeader ? 'Invalid authorization header' : 'Missing authorization header')
+    );
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+  }
+
+  const summary = await expirePendingKiloPassReferralRewards();
+
+  return NextResponse.json(
+    {
+      success: true,
+      summary,
+      timestamp: new Date().toISOString(),
+    },
+    { status: 200 }
+  );
+}

apps/web/src/lib/impact/advocate.test.ts

@@ -198,6 +198,35 @@ describe('impact advocate', () => {
     );
   });
 
+  it('rejects Kilo Pass Advocate config that reuses KiloClaw program or widget IDs', async () => {
+    process.env.IMPACT_ADVOCATE_ACCOUNT_SID = 'fallback-account';
+    process.env.IMPACT_ADVOCATE_AUTH_TOKEN = 'fallback-secret';
+    process.env.IMPACT_ADVOCATE_PROGRAM_ID = '51699';
+    process.env.IMPACT_ADVOCATE_TENANT_ALIAS = 'fallback-tenant';
+    process.env.IMPACT_ADVOCATE_WIDGET_ID = 'p/51699/w/referrerWidget';
+    process.env.IMPACT_ADVOCATE_KILO_PASS_ACCOUNT_SID = 'kilo-pass-account';
+    process.env.IMPACT_ADVOCATE_KILO_PASS_AUTH_TOKEN = 'kilo-pass-secret';
+    process.env.IMPACT_ADVOCATE_KILO_PASS_TENANT_ALIAS = 'kilo-pass-tenant';
+
+    const scope = { product: 'kilo_pass' as const };
+
+    process.env.IMPACT_ADVOCATE_KILO_PASS_PROGRAM_ID = '51699';
+    process.env.IMPACT_ADVOCATE_KILO_PASS_WIDGET_ID = 'p/52766/w/referrerWidget';
+    jest.resetModules();
+    let advocate = await import('@/lib/impact/advocate');
+    expect(advocate.isImpactAdvocateConfigured(scope)).toBe(false);
+    expect(advocate.getImpactAdvocateProgramId(scope)).toBeNull();
+    expect(advocate.getImpactAdvocateWidgetId(scope)).toBeNull();
+
+    process.env.IMPACT_ADVOCATE_KILO_PASS_PROGRAM_ID = '52766';
+    process.env.IMPACT_ADVOCATE_KILO_PASS_WIDGET_ID = 'p/51699/w/referrerWidget';
+    jest.resetModules();
+    advocate = await import('@/lib/impact/advocate');
+    expect(advocate.isImpactAdvocateConfigured(scope)).toBe(false);
+    expect(advocate.getImpactAdvocateProgramId(scope)).toBeNull();
+    expect(advocate.getImpactAdvocateWidgetId(scope)).toBeNull();
+  });
+
   it('logs debug data without tokens, credentials, authorization headers, cookie values, or email identities', async () => {
     process.env.IMPACT_ADVOCATE_PROGRAM_ID = '51699';
     process.env.IMPACT_ADVOCATE_TENANT_ALIAS = 'tenant-alias';

apps/web/src/lib/impact/advocate.ts

@@ -232,6 +232,45 @@ function getImpactAdvocateWidgetPath(widgetId: string, programId: string): strin
   return `p/${trimmedWidgetId}/w/${IMPACT_ADVOCATE_WIDGET_NAME}`;
 }
 
+function getKiloClawAdvocateIdentifiersForComparison(): {
+  programIds: Set<string>;
+  widgetIds: Set<string>;
+} {
+  const programIds = new Set(
+    [
+      configuredValue(IMPACT_ADVOCATE_KILOCLAW_PROGRAM_ID),
+      configuredValue(IMPACT_ADVOCATE_PROGRAM_ID),
+      IMPACT_ADVOCATE_DEFAULT_PROGRAM_ID,
+    ].filter(Boolean)
+  );
+  const widgetIds = new Set<string>();
+  for (const programId of programIds) {
+    widgetIds.add(getImpactAdvocateWidgetPath('', programId));
+  }
+  for (const rawWidgetId of [
+    configuredValue(IMPACT_ADVOCATE_KILOCLAW_WIDGET_ID),
+    configuredValue(IMPACT_ADVOCATE_WIDGET_ID),
+    IMPACT_ADVOCATE_DEFAULT_WIDGET_ID,
+  ].filter(Boolean)) {
+    for (const programId of programIds) {
+      widgetIds.add(getImpactAdvocateWidgetPath(rawWidgetId, programId));
+    }
+  }
+
+  return { programIds, widgetIds };
+}
+
+function kiloPassAdvocateConfigReusesKiloClawIdentifiers(params: {
+  programId: string;
+  widgetId: string;
+}): boolean {
+  const kiloClawIdentifiers = getKiloClawAdvocateIdentifiersForComparison();
+  return (
+    kiloClawIdentifiers.programIds.has(params.programId) ||
+    kiloClawIdentifiers.widgetIds.has(params.widgetId)
+  );
+}
+
 function getImpactAdvocateConfig(scope?: ImpactAdvocateConfigScope): ImpactAdvocateConfig | null {
   const programKey = resolveImpactAdvocateProgramKey(scope);
 
@@ -265,6 +304,14 @@ function getImpactAdvocateConfig(scope?: ImpactAdvocateConfigScope): ImpactAdvoc
         }
       : null;
 
+  const requiresExplicitScopedProgramAndWidget = programKey === ImpactAdvocateProgramKey.KiloPass;
+  if (
+    requiresExplicitScopedProgramAndWidget &&
+    (!scopedValues.programId || !scopedValues.widgetId)
+  ) {
+    return null;
+  }
+
   const accountSid = scopedValues.accountSid || fallbackValues?.accountSid || '';
   const authToken = scopedValues.authToken || fallbackValues?.authToken || '';
   const tenantAlias = scopedValues.tenantAlias || fallbackValues?.tenantAlias || '';
@@ -276,6 +323,13 @@ function getImpactAdvocateConfig(scope?: ImpactAdvocateConfigScope): ImpactAdvoc
     return null;
   }
 
+  if (
+    programKey === ImpactAdvocateProgramKey.KiloPass &&
+    kiloPassAdvocateConfigReusesKiloClawIdentifiers({ programId, widgetId })
+  ) {
+    return null;
+  }
+
   return {
     accountSid,
     authToken,

apps/web/src/lib/impact/kilo-pass-referrals.test.ts

@@ -30,6 +30,7 @@ import { cleanupDbForTest, db } from '@/lib/drizzle';
 import type { isImpactConfigured, sendImpactConversionPayload } from '@/lib/impact';
 import type { isImpactAdvocateConfigured } from '@/lib/impact/advocate';
 import {
+  expirePendingKiloPassReferralRewards,
   markPersonalKiloPassReferralPaymentAdverse,
   processPersonalKiloPassStripePaidConversion,
 } from '@/lib/impact/kilo-pass-referrals';
@@ -393,6 +394,50 @@ describe('Kilo Pass Impact referral conversions', () => {
     );
   });
 
+  test('missing or expired attribution suppresses affiliate SALE reporting', async () => {
+    const noTouchReferee = await insertTestUser({ created_at: '2026-01-02T00:00:00.000Z' });
+    const noTouchSubscriptionId = await insertKiloPassSubscription({
+      userId: noTouchReferee.id,
+    });
+
+    const noTouchDisposition = await processInvoice({
+      refereeId: noTouchReferee.id,
+      subscriptionId: noTouchSubscriptionId,
+    });
+
+    expect(noTouchDisposition).toEqual(
+      expect.objectContaining({
+        shouldEnqueueAffiliateSale: false,
+        winningTouchType: ImpactReferralWinningTouchType.None,
+        disqualificationReason: 'referral_no_valid_attribution',
+      })
+    );
+
+    await cleanupDbForTest();
+    const expiredTouchReferee = await insertTestUser({ created_at: '2026-01-02T00:00:00.000Z' });
+    await insertTouch({
+      userId: expiredTouchReferee.id,
+      type: 'affiliate',
+      touchedAt: '2025-12-01T00:00:00.000Z',
+    });
+    const expiredTouchSubscriptionId = await insertKiloPassSubscription({
+      userId: expiredTouchReferee.id,
+    });
+
+    const expiredTouchDisposition = await processInvoice({
+      refereeId: expiredTouchReferee.id,
+      subscriptionId: expiredTouchSubscriptionId,
+    });
+
+    expect(expiredTouchDisposition).toEqual(
+      expect.objectContaining({
+        shouldEnqueueAffiliateSale: false,
+        winningTouchType: ImpactReferralWinningTouchType.None,
+        disqualificationReason: 'referral_no_valid_attribution',
+      })
+    );
+  });
+
   test('only referral attribution grants double-sided pending rewards', async () => {
     const referrer = await insertTestUser({ created_at: '2025-12-01T00:00:00.000Z' });
     const referee = await insertTestUser({ created_at: '2026-01-02T00:00:00.000Z' });
@@ -593,6 +638,54 @@ describe('Kilo Pass Impact referral conversions', () => {
     expect(await db.select().from(impact_referral_rewards)).toHaveLength(2);
   });
 
+  test('expires stale pending and earned Kilo Pass referral rewards independently of issuance', async () => {
+    const { rewardIds } = await seedKiloPassReferralRewardsForAdversePayment({
+      statuses: [ImpactReferralRewardStatus.Pending, ImpactReferralRewardStatus.Earned],
+    });
+    await db
+      .update(impact_referral_rewards)
+      .set({ expires_at: '2026-01-02T00:00:00.000Z' })
+      .where(eq(impact_referral_rewards.id, rewardIds[0] ?? ''));
+    await db
+      .update(impact_referral_rewards)
+      .set({ expires_at: '2026-01-02T00:00:00.000Z' })
+      .where(eq(impact_referral_rewards.id, rewardIds[1] ?? ''));
+
+    const firstSummary = await expirePendingKiloPassReferralRewards({
+      now: new Date('2026-01-03T00:00:00.000Z'),
+    });
+    const retrySummary = await expirePendingKiloPassReferralRewards({
+      now: new Date('2026-01-03T00:00:00.000Z'),
+    });
+
+    expect(firstSummary).toEqual({ expiredRewards: 2 });
+    expect(retrySummary).toEqual({ expiredRewards: 0 });
+    const rewards = await db
+      .select({
+        status: impact_referral_rewards.status,
+        reviewReason: impact_referral_rewards.review_reason,
+        reversedAt: impact_referral_rewards.reversed_at,
+      })
+      .from(impact_referral_rewards);
+    expect(
+      rewards.map(reward => ({
+        ...reward,
+        reversedAt: new Date(reward.reversedAt ?? '').toISOString(),
+      }))
+    ).toEqual([
+      {
+        status: ImpactReferralRewardStatus.Expired,
+        reviewReason: 'expired_kilo_pass_referral_reward',
+        reversedAt: '2026-01-03T00:00:00.000Z',
+      },
+      {
+        status: ImpactReferralRewardStatus.Expired,
+        reviewReason: 'expired_kilo_pass_referral_reward',
+        reversedAt: '2026-01-03T00:00:00.000Z',
+      },
+    ]);
+  });
+
   test('adverse Stripe payment cancels pending and earned Kilo Pass referral rewards idempotently', async () => {
     const { invoiceId, conversionId } = await seedKiloPassReferralRewardsForAdversePayment({
       statuses: [ImpactReferralRewardStatus.Pending, ImpactReferralRewardStatus.Earned],

apps/web/src/lib/impact/kilo-pass-referrals.ts

@@ -1,7 +1,7 @@
 import 'server-only';
 
 import { addMonths } from 'date-fns';
-import { and, asc, count, eq, inArray, lte, ne, sql } from 'drizzle-orm';
+import { and, asc, count, eq, inArray, isNull, lte, ne, sql } from 'drizzle-orm';
 
 import { db, type DrizzleTransaction } from '@/lib/drizzle';
 import {
@@ -63,6 +63,10 @@ export type KiloPassAdverseReferralPaymentSummary = {
   reviewRequiredRewards: number;
 };
 
+export type KiloPassReferralRewardExpirationSummary = {
+  expiredRewards: number;
+};
+
 const KILO_PASS_REFERRER_REWARD_CAP = 5;
 const KILO_PASS_REFERRAL_REWARD_PERCENT = 0.5;
 const SIGNUP_REFERRAL_TOUCH_CAPTURE_GRACE_MS = 10 * 60 * 1000;
@@ -298,7 +302,41 @@ function getRewardAmountUsd(sourceTier: KiloPassTier): number {
 }
 
 function shouldPreserveAffiliateSale(winningTouchType: string): boolean {
-  return winningTouchType !== ImpactReferralWinningTouchType.Referral;
+  return winningTouchType === ImpactReferralWinningTouchType.Affiliate;
+}
+
+export async function expirePendingKiloPassReferralRewards(params?: {
+  now?: Date;
+  database?: DatabaseClient;
+}): Promise<KiloPassReferralRewardExpirationSummary> {
+  const now = params?.now ?? new Date();
+  const database = params?.database ?? db;
+  const nowIso = now.toISOString();
+
+  const expiredRewards = await database
+    .update(impact_referral_rewards)
+    .set({
+      status: ImpactReferralRewardStatus.Expired,
+      reversed_at: nowIso,
+      review_reason: 'expired_kilo_pass_referral_reward',
+    })
+    .where(
+      and(
+        eq(impact_referral_rewards.product, ImpactReferralProduct.KiloPass),
+        eq(impact_referral_rewards.reward_kind, ImpactReferralRewardKind.KiloPassBonus),
+        inArray(impact_referral_rewards.status, [
+          ImpactReferralRewardStatus.Pending,
+          ImpactReferralRewardStatus.Earned,
+        ]),
+        isNull(impact_referral_rewards.applied_at),
+        isNull(impact_referral_rewards.consumed_kilo_pass_issuance_id),
+        sql`${impact_referral_rewards.expires_at} IS NOT NULL`,
+        lte(impact_referral_rewards.expires_at, nowIso)
+      )
+    )
+    .returning({ id: impact_referral_rewards.id });
+
+  return { expiredRewards: expiredRewards.length };
 }
 
 export async function markPersonalKiloPassReferralPaymentAdverse(params: {
@@ -503,7 +541,7 @@ export async function processPersonalKiloPassStripePaidConversion(params: {
         .returning({ id: impact_referral_conversions.id });
 
       return {
-        shouldEnqueueAffiliateSale: true,
+        shouldEnqueueAffiliateSale: false,
         winningTouchType: ImpactReferralWinningTouchType.None,
         conversionId: conversion?.id ?? null,
         disqualificationReason: referralDisqualificationReason('no_valid_attribution'),

apps/web/src/routers/kilo-pass-router.test.ts

@@ -3106,6 +3106,39 @@ describe('kiloPassRouter', () => {
         })
       );
     });
+
+    it('does not count expired pending rewards as pending future rewards', async () => {
+      const user = await insertTestUser({
+        google_user_email: 'kilo-pass-referral-expired-pending@example.com',
+      });
+
+      await insertKiloPassReferralReward({
+        beneficiaryUserId: user.id,
+        role: ImpactReferralBeneficiaryRole.Referrer,
+        status: ImpactReferralRewardStatus.Pending,
+        rewardAmountUsd: 24.5,
+        sourceTier: KiloPassTier.Tier49,
+        earnedAt: '2025-01-01T00:00:00.000Z',
+        expiresAt: '2025-12-31T00:00:00.000Z',
+      });
+
+      const caller = await createCallerForUser(user.id);
+      const result = await caller.kiloPass.getReferralRewardSummary();
+
+      expect(result.totals).toEqual(
+        expect.objectContaining({
+          totalRewards: 1,
+          pendingRewards: 0,
+          pendingRewardAmountUsd: 0,
+        })
+      );
+      expect(result.rewards[0]).toEqual(
+        expect.objectContaining({
+          status: ImpactReferralRewardStatus.Pending,
+          expiresAt: '2025-12-31T00:00:00.000Z',
+        })
+      );
+    });
   });
 
   describe('createCheckoutSession', () => {

apps/web/src/routers/kilo-pass-router.ts

@@ -915,9 +915,12 @@ export const kiloPassRouter = createTRPCRouter({
         reviewReason: row.reviewReason,
       }));
 
-      const pendingRewards = rewards.filter(reward =>
-        KILO_PASS_PENDING_REFERRAL_REWARD_STATUSES.has(reward.status)
-      );
+      const nowMs = Date.now();
+      const pendingRewards = rewards.filter(reward => {
+        if (!KILO_PASS_PENDING_REFERRAL_REWARD_STATUSES.has(reward.status)) return false;
+        if (!reward.expiresAt) return true;
+        return new Date(reward.expiresAt).getTime() > nowMs;
+      });
       const appliedRewards = rewards.filter(
         reward => reward.status === ImpactReferralRewardStatus.Applied
       );

apps/web/vercel.json

@@ -28,6 +28,10 @@
       "path": "/api/cron/kilo-pass-store-subscription-reconcile",
       "schedule": "*/15 * * * *"
     },
+    {
+      "path": "/api/cron/kilo-pass-expire-referral-rewards",
+      "schedule": "0 * * * *"
+    },
     {
       "path": "/api/cron/deployment-threat-scan",
       "schedule": "*/5 * * * *"