@kido/payment-stripeCopy Anchor Link

Architecture Paradigm: RFC Timing-Safe HMAC Webhook Verifier + 300s Replay Attack Guard + Idempotent Event Deduplication + Proration & Rollover Math + Non-Destructive Quota Soft-Locking.

💥 The Real-World Bottleneck (Why It Exists)Copy Anchor Link

In global SaaS platforms, handling recurring billing and subscriptions with Stripe introduces complex operational hazards:

1. Webhook Replay Attacks & Forged Invoices:
   • Parsing webhook payloads without cryptographic crypto.timingSafeEqual HMAC-SHA256 verification or timestamp tolerance checks leaves the platform vulnerable to timing attacks and replay attacks.
   • Attackers can re-send old invoice.payment_succeeded payloads to continuously extend paid subscriptions without paying.
2. Duplicate Processing & Out-of-Order Delivery:
   • Stripe guarantees at-least-once webhook delivery. In network retries, the same invoice event can be delivered 2–5 times. Without idempotency deduplication, customers are credited duplicate license seats or balance credits.
   • Furthermore, customer.subscription.deleted can arrive before customer.subscription.created due to network jitter, corrupting user subscription status.
3. Destructive Downgrades (The Accidental Data Loss Trap):
   • When a customer downgrades from Enterprise (100 team seats) to Pro (10 team seats), naïve billing handlers delete the excess 90 users from the database.
   • If the downgrade was accidental or temporary, customer data is irrevocably destroyed.

🏛️ 3-Tier Production Evolution LadderCopy Anchor Link

📐 Architecture & Data FlowCopy Anchor Link

📦 Architecture & Core API ExportsCopy Anchor Link

All capabilities are strictly isolated in packages/payment-stripe:

1. src/webhook.tsCopy Anchor Link

• StripeWebhookRouter: Centralized webhook dispatcher with event subscriptions (onSubscriptionCreated, onInvoicePaymentSucceeded, onInvoicePaymentFailed).
• verifyStripeWebhook(payload, signature, secret, tolerance): RFC-compliant HMAC-SHA256 signature verifier with crypto.timingSafeEqual and timestamp replay checks.
• InMemoryIdempotencyStore: Thread-safe in-memory cache preventing duplicate event execution.

2. src/proration.tsCopy Anchor Link

• calculateProration(options): Computes exact remaining period credits and upgraded plan costs down to the second.
• computeUnusedCredit(planAmount, daysRemaining, totalDays): Calculates unconsumed prepaid balance.

3. src/quota-reconciler.tsCopy Anchor Link

• PlanQuotaReconciler: Reconciles active customer resources against new plan quotas upon downgrade without deleting underlying records.
• softLockExcessResources(resources, allowedQuota): Marks excess entities as is_locked: true (read-only) rather than deleting them.

4. src/lifecycle.tsCopy Anchor Link

• SubscriptionStateMachine: Formal state transitions for subscriptions (trialing, active, past_due, canceled, unpaid).

5. src/checkout.ts & src/coupon.tsCopy Anchor Link

• buildCheckoutSessionParams(options): Generates validated parameters for Stripe Checkout sessions.
• validateSubscriptionCoupon(coupon, plan): Validates promotional discount rules and recurrence periods.

💻 Production Implementation & Code SnippetCopy Anchor Link

1. Webhook Router Setup (src/services/stripe-billing.ts)Copy Anchor Link

import {
  StripeWebhookRouter,
  PlanQuotaReconciler,
  calculateProration,
} from '@kido/payment-stripe';

// 1. Initialize Stripe Webhook Router with timing-safe HMAC & 300s replay guard
export const billingRouter = new StripeWebhookRouter({
  secret: process.env.STRIPE_WEBHOOK_SECRET || 'whsec_prod_secret',
  toleranceInSeconds: 300, // 5-minute replay attack defense
});

// 2. Handle Subscription Activation
billingRouter.onSubscriptionCreated(async (event) => {
  const sub = event.data.object;
  console.log(`[Stripe] New subscription activated: ${sub.id} for customer ${sub.customer}`);
  // Update organization plan status to 'ACTIVE'
});

// 3. Handle Payment Failure (Dunning cycle)
billingRouter.onInvoicePaymentFailed(async (event) => {
  const invoice = event.data.object;
  console.warn(`[Stripe Dunning] Payment failed for invoice ${invoice.id}. Dispatching retry notification.`);
});

// 4. Handle Plan Downgrade without deleting user projects
billingRouter.onSubscriptionUpdated(async (event) => {
  const sub = event.data.object;
  const newMaxProjects = 5; // Downgraded to 5 projects max
  const existingProjects = [
    { id: 'proj_1', name: 'Alpha' },
    { id: 'proj_2', name: 'Beta' },
    { id: 'proj_3', name: 'Gamma' },
    { id: 'proj_4', name: 'Delta' },
    { id: 'proj_5', name: 'Epsilon' },
    { id: 'proj_6', name: 'Zeta' }, // Excess project!
  ];

  // Soft-lock project 6 instead of deleting it
  const reconciled = PlanQuotaReconciler.reconcile(existingProjects, newMaxProjects);
  console.log(`[Stripe] Active: ${reconciled.active.length}, Soft-locked: ${reconciled.locked.length}`);
});

2. Webhook API Route Controller (src/app/api/stripe/webhook/route.ts)Copy Anchor Link

import { billingRouter } from '@/services/stripe-billing';

export async function POST(req: Request) {
  const rawBody = await req.text();
  const signature = req.headers.get('stripe-signature') || '';

  const result = await billingRouter.handleWebhook(rawBody, signature);

  if (!result.isValid) {
    return new Response(JSON.stringify({ error: result.error }), { status: 400 });
  }

  if (result.duplicate) {
    return new Response(JSON.stringify({ status: 'duplicate_ignored' }), { status: 200 });
  }

  return new Response(JSON.stringify({ status: 'success', eventId: result.event?.id }), { status: 200 });
}

⚡ Benchmark & Verified PerformanceCopy Anchor Link

Benchmarked with k6 simulating 50,000 webhook events:

🚀 Surgical Extraction & CLI InstallationCopy Anchor Link

npx @kido/cli add payment-stripe