@cubis/foundry 0.3.83 → 0.3.84

package/workflows/skills/sanitize-pii/references/redaction-strategies.md

@@ -1,252 +0,0 @@
-# Redaction Strategies Reference
-
-## Overview
-
-Redaction removes or replaces PII values so the data cannot identify individuals. The right strategy depends on whether redaction must be reversible, whether data utility must be preserved, and what compliance requirements apply.
-
-## Redaction Types
-
-| Type | Description | Reversible | Data Utility | Use Case |
-|------|------------|-----------|-------------|----------|
-| Destructive | Replace with fixed token | No | None | Logs, error messages |
-| Deterministic | Same input always produces same output | No (but consistent) | Referential | Analytics, testing |
-| Format-preserving | Output matches input format | Optional | High | Staging databases |
-| Tokenization | Replace with random token, store mapping | Yes (with vault) | None (without vault) | Payment processing |
-| Partial masking | Reveal some characters | No | Partial | Display (card ending 4242) |
-
-## Implementation Patterns
-
-### Destructive Redaction (Logs)
-
-```javascript
-// Log sanitizer middleware
-const REDACTION_RULES = [
-  { name: 'email', pattern: /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b/g, replacement: '[REDACTED:email]' },
-  { name: 'ssn', pattern: /\b\d{3}-\d{2}-\d{4}\b/g, replacement: '[REDACTED:ssn]' },
-  { name: 'credit_card', pattern: /\b\d{4}[\s-]?\d{4}[\s-]?\d{4}[\s-]?\d{4}\b/g, replacement: '[REDACTED:card]' },
-  { name: 'phone', pattern: /(\+\d{1,3}\s?)?\(?\d{3}\)?[\s.-]?\d{3}[\s.-]?\d{4}/g, replacement: '[REDACTED:phone]' },
-  { name: 'ip', pattern: /\b\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}\b/g, replacement: '[REDACTED:ip]' },
-];
-
-function sanitizeLogMessage(message) {
-  let sanitized = message;
-  for (const rule of REDACTION_RULES) {
-    sanitized = sanitized.replace(rule.pattern, rule.replacement);
-  }
-  return sanitized;
-}
-
-// Integrate with logging library
-const winston = require('winston');
-const sanitizeFormat = winston.format((info) => {
-  info.message = sanitizeLogMessage(info.message);
-  return info;
-});
-
-const logger = winston.createLogger({
-  format: winston.format.combine(
-    sanitizeFormat(),
-    winston.format.json()
-  ),
-  transports: [new winston.transports.Console()],
-});
-```
-
-### Deterministic Redaction (Analytics)
-
-Same input always produces the same pseudonym, enabling joins and aggregation.
-
-```python
-import hashlib
-import hmac
-
-REDACTION_KEY = os.environ['REDACTION_HMAC_KEY']
-
-def deterministic_redact(value, pii_type):
-    """Same input always produces same output for consistent references."""
-    tag = hmac.new(
-        REDACTION_KEY.encode(),
-        f"{pii_type}:{value}".encode(),
-        hashlib.sha256
-    ).hexdigest()[:16]
-    return f"[{pii_type}:{tag}]"
-
-# Usage
-email = "sarah@example.com"
-redacted = deterministic_redact(email, "email")
-# Always returns: [email:a7b3c9d1e5f2g8h4]
-# Can join records by this pseudonym without knowing the real email
-```
-
-### Format-Preserving Redaction (Staging)
-
-Output looks like real data and passes format validation.
-
-```python
-from faker import Faker
-import hashlib
-
-fake = Faker()
-
-def format_preserving_redact(value, pii_type, seed_salt):
-    """Replace PII with realistic fake data, deterministically."""
-    seed = int(hashlib.sha256(f"{seed_salt}:{value}".encode()).hexdigest()[:8], 16)
-    fake.seed_instance(seed)
-
-    if pii_type == 'email':
-        return f"{fake.user_name()}@masked.example.com"
-    elif pii_type == 'name':
-        return fake.name()
-    elif pii_type == 'phone':
-        return fake.phone_number()
-    elif pii_type == 'address':
-        return fake.address()
-    elif pii_type == 'ssn':
-        return f"{fake.random_int(100,999)}-{fake.random_int(10,99)}-{fake.random_int(1000,9999)}"
-    elif pii_type == 'credit_card':
-        return fake.credit_card_number()
-    elif pii_type == 'date_of_birth':
-        return fake.date_of_birth(minimum_age=18, maximum_age=80).isoformat()
-    else:
-        return f"[REDACTED:{pii_type}]"
-```
-
-### Tokenization (Payment Processing)
-
-Replace sensitive data with a random token; store the mapping in a secure vault.
-
-```python
-class TokenVault:
-    def __init__(self, vault_client):
-        self.vault = vault_client
-
-    def tokenize(self, value, data_type):
-        """Replace value with a random token, store mapping in vault."""
-        token = f"tok_{secrets.token_hex(16)}"
-        self.vault.write(
-            f"tokens/data/{token}",
-            original=value,
-            data_type=data_type,
-            created_at=datetime.utcnow().isoformat()
-        )
-        return token
-
-    def detokenize(self, token):
-        """Retrieve original value (requires vault access + authorization)."""
-        secret = self.vault.read(f"tokens/data/{token}")
-        return secret['data']['original']
-```
-
-### Partial Masking (Display)
-
-```javascript
-function partialMask(value, type) {
-  switch (type) {
-    case 'email':
-      const [local, domain] = value.split('@');
-      return `${local[0]}***@${domain}`;
-      // sarah@example.com → s***@example.com
-
-    case 'phone':
-      return value.replace(/\d(?=\d{4})/g, '*');
-      // +1 (555) 123-4567 → +* (***) ***-4567
-
-    case 'credit_card':
-      return `**** **** **** ${value.slice(-4)}`;
-      // 4111111111111111 → **** **** **** 1111
-
-    case 'ssn':
-      return `***-**-${value.slice(-4)}`;
-      // 123-45-6789 → ***-**-6789
-
-    default:
-      return '[MASKED]';
-  }
-}
-```
-
-## Structured Logging with Built-in Redaction
-
-### PII-Aware Logger
-
-```javascript
-class PIIAwareLogger {
-  constructor(sensitiveFields) {
-    this.sensitiveFields = new Set(sensitiveFields);
-  }
-
-  sanitizeObject(obj) {
-    const sanitized = {};
-    for (const [key, value] of Object.entries(obj)) {
-      if (this.sensitiveFields.has(key.toLowerCase())) {
-        sanitized[key] = '[REDACTED]';
-      } else if (typeof value === 'object' && value !== null) {
-        sanitized[key] = this.sanitizeObject(value);
-      } else {
-        sanitized[key] = value;
-      }
-    }
-    return sanitized;
-  }
-
-  log(level, message, context = {}) {
-    const sanitizedContext = this.sanitizeObject(context);
-    console.log(JSON.stringify({
-      level,
-      message,
-      ...sanitizedContext,
-      timestamp: new Date().toISOString(),
-    }));
-  }
-}
-
-const logger = new PIIAwareLogger([
-  'email', 'password', 'ssn', 'credit_card', 'phone',
-  'date_of_birth', 'address', 'name', 'first_name', 'last_name',
-  'card_number', 'cvv', 'national_id', 'passport',
-]);
-
-// Usage — PII fields are automatically redacted
-logger.log('info', 'User created', {
-  user_id: 123,
-  email: 'sarah@example.com',  // → [REDACTED]
-  plan: 'premium',
-});
-```
-
-## Redaction Validation
-
-### Testing Redaction Effectiveness
-
-```python
-def test_redaction_completeness():
-    """Assert that no real PII appears in redacted output."""
-    real_emails = load_production_emails()  # Hashed for comparison
-    redacted_data = load_redacted_dataset()
-
-    for record in redacted_data:
-        for field_value in record.values():
-            if isinstance(field_value, str):
-                # Check no real email pattern exists
-                assert not re.search(r'@(gmail|yahoo|outlook|company)', field_value), \
-                    f"Possible real email in redacted data: {field_value}"
-
-                # Check no SSN pattern exists
-                assert not re.search(r'\b\d{3}-\d{2}-\d{4}\b', field_value), \
-                    f"Possible SSN in redacted data: {field_value}"
-
-                # Check against known production values
-                hashed = hashlib.sha256(field_value.encode()).hexdigest()
-                assert hashed not in real_emails, \
-                    f"Production PII found in redacted data"
-```
-
-## Performance Considerations
-
-| Strategy | Throughput | Memory | Latency |
-|----------|-----------|--------|---------|
-| Regex replacement | Very high | Low | < 1ms per record |
-| NLP-based detection | Low | High | 50-200ms per record |
-| Format-preserving encryption | High | Low | < 5ms per record |
-| Tokenization (with vault) | Medium | Low | 10-50ms per record (network) |
-| Deterministic HMAC | Very high | Low | < 1ms per record |

package/workflows/skills/stripe-integration/SKILL.md

@@ -1,88 +0,0 @@
----
-name: stripe-integration
-description: "Use when building Stripe payment integrations: checkout sessions, subscriptions, webhook handling, idempotent API calls, fraud prevention, and end-to-end payment testing with Stripe CLI."
-license: MIT
-metadata:
-  author: cubis-foundry
-  version: "3.0"
-compatibility: Claude Code, Codex, GitHub Copilot
----
-
-# Stripe Integration
-
-## Purpose
-
-Guide the design and implementation of production-grade Stripe payment integrations covering one-time checkout sessions, recurring subscriptions with lifecycle management, secure webhook processing, idempotent server-side calls, and comprehensive test coverage using Stripe test mode and CLI tooling.
-
-## When to Use
-
-- Building a new Stripe Checkout or Payment Intent flow from scratch.
-- Adding subscription billing with plan upgrades, downgrades, and cancellations.
-- Implementing webhook endpoints that handle payment and subscription events.
-- Securing payment flows with idempotency keys, signature verification, and fraud prevention.
-- Writing integration tests against Stripe test mode or Stripe CLI fixtures.
-- Debugging failed payments, subscription state mismatches, or webhook delivery issues.
-
-## Instructions
-
-1. **Select the integration pattern before writing code** because Stripe offers hosted Checkout, embedded Payment Element, and raw Payment Intents, each with different PCI compliance burden and UI control tradeoffs. Default to hosted Checkout unless custom UI is required.
-
-2. **Create products and prices in Stripe Dashboard or via API before building flows** because all checkout sessions and subscriptions reference price IDs, and defining them upfront avoids runtime price creation that is harder to audit.
-
-3. **Generate checkout sessions server-side with explicit line items and metadata** because the server is the trust boundary for amounts, currency, and tax behavior. Never let the client dictate pricing.
-
-4. **Attach idempotency keys to every mutating Stripe API call** because network retries without idempotency can create duplicate charges, subscriptions, or refunds. Use a deterministic key derived from the business operation (e.g., `order:{orderId}:checkout`).
-
-5. **Store the Stripe customer ID in your database at creation time** because every subsequent operation (checkout, subscription, invoice, portal) requires the customer reference, and re-creating customers produces orphaned records.
-
-6. **Implement webhook signature verification on every incoming event** because unsigned webhooks can be forged by any attacker who discovers the endpoint URL. Use `stripe.webhooks.constructEvent` with the raw body and endpoint secret.
-
-7. **Return HTTP 200 from webhook handlers immediately, then process asynchronously** because Stripe retries delivery if it does not receive a 2xx within a timeout, and long-running synchronous processing causes duplicate delivery.
-
-8. **Handle webhook events idempotently by checking event ID or object version** because Stripe may deliver the same event multiple times during retries and endpoint recovery. Deduplicate by storing processed event IDs.
-
-9. **Sync subscription status exclusively through webhooks, not polling** because webhooks deliver state changes in near-real-time and avoid the latency, rate-limit pressure, and cost of periodic API calls.
-
-10. **Implement dunning logic for failed subscription payments** because Stripe retries automatically, but your application must notify users, display payment update prompts, and enforce grace periods before access revocation.
-
-11. **Use Stripe Customer Portal for self-service billing management** because building plan change, payment method update, and invoice history UI from scratch is error-prone and duplicates functionality Stripe provides.
-
-12. **Configure Stripe Radar rules for fraud prevention** because automated fraud detection with configurable risk thresholds, velocity checks, and block lists reduces chargebacks without manual review overhead.
-
-13. **Test every payment flow with Stripe test card numbers and Stripe CLI** because test mode isolates your integration from real money, and `stripe trigger` plus `stripe listen --forward-to` reproduce webhook sequences locally without deploying.
-
-14. **Separate API keys by environment and never commit them to source control** because leaked live keys grant full access to your Stripe account. Use environment variables and restrict live keys to production deployments.
-
-15. **Handle SCA and 3D Secure flows by using Payment Intents with `requires_action` status** because European regulations mandate Strong Customer Authentication, and payment flows that skip it will see elevated decline rates.
-
-16. **Log Stripe request IDs alongside your internal operation IDs** because Stripe support requires request IDs to investigate issues, and correlating them with your operations accelerates debugging.
-
-## Output Format
-
-```
-## Integration Architecture
-[Checkout/subscription/payment flow diagram and pattern choice rationale]
-
-## Implementation
-[Server and client code with idempotency, error handling, and type safety]
-
-## Webhook Setup
-[Events to subscribe, signature verification, idempotent processing logic]
-
-## Testing Plan
-[Test card numbers, Stripe CLI commands, edge case scenarios]
-```
-
-## References
-
-| File                          | Load when                                                                                     |
-| ----------------------------- | --------------------------------------------------------------------------------------------- |
-| `references/payment-flows.md` | Building checkout sessions, redirect flows, or embedded payment forms.                       |
-| `references/subscription-lifecycle.md` | Implementing recurring billing, plan changes, trials, dunning, and customer portal flows. |
-| `references/webhook-handling.md` | Setting up webhook endpoints, handling events, and debugging delivery behavior.           |
-
-## Examples
-
-- "Set up Stripe Checkout for a SaaS app with monthly and annual subscription plans."
-- "Implement a webhook handler for subscription lifecycle events with idempotent processing."
-- "Add Stripe Customer Portal for self-service billing with plan upgrade and downgrade support."

package/workflows/skills/stripe-integration/evals/assertions.md

@@ -1,47 +0,0 @@
-# Stripe Integration Eval Assertions
-
-## Eval 1: Subscription Flow with Webhooks
-
-This eval tests the core Stripe subscription workflow: creating checkout sessions, handling lifecycle webhooks idempotently, and synchronizing subscription state to the application database.
-
-### Assertions
-
-| # | Type     | What it checks                                  | Why it matters                                                                                       |
-|---|----------|-------------------------------------------------|------------------------------------------------------------------------------------------------------|
-| 1 | contains | `stripe.checkout.sessions.create` — Server-side session creation | Checkout sessions must be created server-side to ensure the server controls pricing, currency, and tax. Client-initiated amounts are a security vulnerability. |
-| 2 | contains | `constructEvent` — Webhook signature verification | Every webhook must be verified with `stripe.webhooks.constructEvent` to prevent forged events from triggering fulfillment or state changes. |
-| 3 | contains | `customer.subscription` — Subscription lifecycle events | The handler must process subscription lifecycle events (created, updated, deleted) to keep application state in sync with Stripe's source of truth. |
-| 4 | contains | `idempotency` — Idempotent webhook processing   | Stripe may deliver the same event multiple times. Without idempotency checks, duplicate processing causes data corruption and double-fulfillment. |
-| 5 | contains | `stripe_customer_id` — Customer ID persistence  | The Stripe customer ID must be stored in the database to link Stripe objects (subscriptions, invoices, payments) back to application users. |
-
-### What a passing response looks like
-
-- A server route that creates Checkout Sessions with explicit price IDs, customer reference, and metadata.
-- Webhook endpoint that verifies signatures using `constructEvent` before processing any event.
-- Event handlers for `customer.subscription.created`, `updated`, and `deleted` that update database records.
-- Idempotency guard that checks processed event IDs or object versions before applying state changes.
-- Database schema with `stripe_customer_id` and `stripe_subscription_id` columns on the users or subscriptions table.
-
----
-
-## Eval 2: Checkout Session Implementation
-
-This eval tests the Checkout Session flow: creating sessions with line items and metadata, handling post-payment webhooks, and supporting multiple payment methods.
-
-### Assertions
-
-| # | Type     | What it checks                                  | Why it matters                                                                                       |
-|---|----------|-------------------------------------------------|------------------------------------------------------------------------------------------------------|
-| 1 | contains | `line_items` — Explicit line item configuration  | Checkout Sessions must define line items server-side with quantities and tax behavior. Omitting them causes checkout to display no items. |
-| 2 | contains | `success_url` — Post-checkout redirect           | Users must be redirected to a confirmation page after payment. Without success_url, Stripe has nowhere to send the user after checkout completes. |
-| 3 | contains | `metadata` — Session metadata attachment         | Metadata links the Stripe session to the internal order, enabling webhook handlers to correlate payment events with application records. |
-| 4 | contains | `checkout.session.completed` — Fulfillment webhook | Fulfillment must be triggered by the webhook, not the client redirect, because users may close the browser before the redirect completes. |
-| 5 | contains | `4242` — Test card numbers                       | Including test card numbers proves the implementation accounts for test mode verification, which is essential for development and CI testing. |
-
-### What a passing response looks like
-
-- API route that builds Checkout Session with line_items array, each containing price_data or price ID.
-- success_url and cancel_url configured with `{CHECKOUT_SESSION_ID}` template variable for order lookup.
-- Metadata attached to the session containing internal order ID and user ID.
-- Webhook handler for `checkout.session.completed` that marks the order as paid and triggers fulfillment.
-- Test section listing Stripe test card numbers (4242... for success, 4000... for various decline scenarios).

package/workflows/skills/stripe-integration/evals/evals.json

@@ -1,66 +0,0 @@
-[
-  {
-    "name": "subscription-flow-with-webhooks",
-    "description": "Validate that the skill produces a complete subscription flow with Stripe Checkout, webhook handling for lifecycle events, idempotent processing, and proper subscription status synchronization.",
-    "input": "Implement a SaaS subscription system with Stripe. Users choose between Basic ($10/mo) and Pro ($25/mo) plans. Use Stripe Checkout for the payment flow. Handle all subscription lifecycle webhooks (created, updated, deleted, past_due). Store subscription state in a PostgreSQL database. Ensure webhook handlers are idempotent and return 200 immediately.",
-    "assertions": [
-      {
-        "type": "contains",
-        "value": "stripe.checkout.sessions.create",
-        "description": "Must create Checkout Sessions server-side with explicit price IDs and customer references, never allowing the client to set amounts."
-      },
-      {
-        "type": "contains",
-        "value": "constructEvent",
-        "description": "Webhook handler must verify signatures using stripe.webhooks.constructEvent with the raw body and endpoint secret to prevent forged events."
-      },
-      {
-        "type": "contains",
-        "value": "customer.subscription",
-        "description": "Must handle subscription lifecycle events (customer.subscription.created, updated, deleted) to synchronize subscription state from Stripe to the database."
-      },
-      {
-        "type": "contains",
-        "value": "idempotency",
-        "description": "Must implement idempotent webhook processing by checking event IDs or object versions to prevent duplicate processing on retry delivery."
-      },
-      {
-        "type": "contains",
-        "value": "stripe_customer_id",
-        "description": "Must persist the Stripe customer ID in the application database to associate Stripe objects with application users across all operations."
-      }
-    ]
-  },
-  {
-    "name": "checkout-session-implementation",
-    "description": "Validate that the skill produces a secure Checkout Session implementation with proper configuration, success/cancel handling, metadata attachment, and post-payment fulfillment through webhooks.",
-    "input": "Build a Stripe Checkout integration for an e-commerce store using Next.js. Create an API route that generates Checkout Sessions for cart items. Include tax calculation with Stripe Tax. Attach order metadata to the session. Handle the checkout.session.completed webhook to fulfill the order. Support both card and Apple Pay/Google Pay payment methods. Include error handling and test card numbers for verification.",
-    "assertions": [
-      {
-        "type": "contains",
-        "value": "line_items",
-        "description": "Checkout Session must specify line_items with price_data or price IDs, quantities, and tax behavior for each cart item."
-      },
-      {
-        "type": "contains",
-        "value": "success_url",
-        "description": "Must configure success_url and cancel_url for post-checkout redirects, using session ID template variables for order confirmation pages."
-      },
-      {
-        "type": "contains",
-        "value": "metadata",
-        "description": "Must attach application-specific metadata (order ID, user ID) to the Checkout Session for correlating Stripe events with internal records."
-      },
-      {
-        "type": "contains",
-        "value": "checkout.session.completed",
-        "description": "Must handle the checkout.session.completed webhook event for order fulfillment, not relying solely on client-side redirect for confirmation."
-      },
-      {
-        "type": "contains",
-        "value": "4242",
-        "description": "Must include Stripe test card numbers (4242424242424242 for success) for testing the payment flow in development."
-      }
-    ]
-  }
-]

package/workflows/skills/stripe-integration/examples/01-basic-usage.md

@@ -1,213 +0,0 @@
-# Example: Basic Stripe Checkout for a SaaS Product
-
-## Scenario
-
-A team is building a SaaS application that sells two subscription plans (Starter at $29/mo and Pro at $99/mo). They need a server-side Stripe Checkout integration that creates checkout sessions, redirects users to Stripe's hosted payment page, and handles the `checkout.session.completed` webhook to activate the subscription in the application database.
-
-## Prompt
-
-"Set up Stripe Checkout for our SaaS app. We have two plans: Starter ($29/mo) and Pro ($99/mo). Create the checkout session server-side with Next.js API routes, handle the success redirect, and process the checkout.session.completed webhook to activate the user's subscription."
-
-## Expected Output
-
-### Stripe Product Setup
-
-```typescript
-// lib/stripe.ts
-import Stripe from 'stripe';
-
-export const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
-  apiVersion: '2024-12-18.acacia',
-});
-
-export const PLANS = {
-  starter: {
-    priceId: process.env.STRIPE_STARTER_PRICE_ID!,
-    name: 'Starter',
-  },
-  pro: {
-    priceId: process.env.STRIPE_PRO_PRICE_ID!,
-    name: 'Pro',
-  },
-} as const;
-
-export type PlanKey = keyof typeof PLANS;
-```
-
-### Checkout Session Creation
-
-```typescript
-// app/api/checkout/route.ts
-import { NextRequest, NextResponse } from 'next/server';
-import { stripe, PLANS, PlanKey } from '@/lib/stripe';
-import { auth } from '@/lib/auth';
-import { db } from '@/lib/db';
-
-export async function POST(req: NextRequest) {
-  const session = await auth();
-  if (!session?.user) {
-    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
-  }
-
-  const { plan } = (await req.json()) as { plan: PlanKey };
-  if (!PLANS[plan]) {
-    return NextResponse.json({ error: 'Invalid plan' }, { status: 400 });
-  }
-
-  // Ensure user has a Stripe customer ID
-  let customerId = session.user.stripeCustomerId;
-  if (!customerId) {
-    const customer = await stripe.customers.create({
-      email: session.user.email,
-      metadata: { userId: session.user.id },
-    });
-    customerId = customer.id;
-    await db.user.update({
-      where: { id: session.user.id },
-      data: { stripeCustomerId: customerId },
-    });
-  }
-
-  const checkoutSession = await stripe.checkout.sessions.create(
-    {
-      customer: customerId,
-      mode: 'subscription',
-      line_items: [{ price: PLANS[plan].priceId, quantity: 1 }],
-      success_url: `${process.env.NEXT_PUBLIC_URL}/dashboard?checkout=success`,
-      cancel_url: `${process.env.NEXT_PUBLIC_URL}/pricing?checkout=cancelled`,
-      subscription_data: {
-        metadata: { userId: session.user.id, plan },
-      },
-    },
-    {
-      idempotencyKey: `checkout:${session.user.id}:${plan}:${Date.now()}`,
-    }
-  );
-
-  return NextResponse.json({ url: checkoutSession.url });
-}
-```
-
-### Webhook Handler
-
-```typescript
-// app/api/webhooks/stripe/route.ts
-import { NextRequest, NextResponse } from 'next/server';
-import { stripe } from '@/lib/stripe';
-import { db } from '@/lib/db';
-import { headers } from 'next/headers';
-
-export async function POST(req: NextRequest) {
-  const body = await req.text();
-  const headersList = await headers();
-  const signature = headersList.get('stripe-signature')!;
-
-  let event: Stripe.Event;
-  try {
-    event = stripe.webhooks.constructEvent(
-      body,
-      signature,
-      process.env.STRIPE_WEBHOOK_SECRET!
-    );
-  } catch (err) {
-    console.error('Webhook signature verification failed:', err);
-    return NextResponse.json({ error: 'Invalid signature' }, { status: 400 });
-  }
-
-  // Idempotency: skip already-processed events
-  const existing = await db.stripeEvent.findUnique({
-    where: { eventId: event.id },
-  });
-  if (existing) {
-    return NextResponse.json({ received: true });
-  }
-
-  if (event.type === 'checkout.session.completed') {
-    const session = event.data.object as Stripe.Checkout.Session;
-    const userId = session.subscription_data?.metadata?.userId
-      ?? session.metadata?.userId;
-
-    if (userId && session.subscription) {
-      await db.subscription.upsert({
-        where: { userId },
-        create: {
-          userId,
-          stripeSubscriptionId: session.subscription as string,
-          status: 'active',
-          plan: session.metadata?.plan ?? 'starter',
-        },
-        update: {
-          stripeSubscriptionId: session.subscription as string,
-          status: 'active',
-          plan: session.metadata?.plan ?? 'starter',
-        },
-      });
-    }
-  }
-
-  // Record event as processed
-  await db.stripeEvent.create({
-    data: { eventId: event.id, type: event.type },
-  });
-
-  return NextResponse.json({ received: true });
-}
-```
-
-### Client-Side Checkout Button
-
-```typescript
-// components/checkout-button.tsx
-'use client';
-
-import { useState } from 'react';
-import { PlanKey } from '@/lib/stripe';
-
-export function CheckoutButton({ plan }: { plan: PlanKey }) {
-  const [loading, setLoading] = useState(false);
-
-  const handleCheckout = async () => {
-    setLoading(true);
-    try {
-      const res = await fetch('/api/checkout', {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ plan }),
-      });
-      const { url } = await res.json();
-      if (url) window.location.href = url;
-    } finally {
-      setLoading(false);
-    }
-  };
-
-  return (
-    <button onClick={handleCheckout} disabled={loading}>
-      {loading ? 'Redirecting...' : 'Subscribe'}
-    </button>
-  );
-}
-```
-
-### Testing with Stripe CLI
-
-```bash
-# Forward webhooks to local dev server
-stripe listen --forward-to localhost:3000/api/webhooks/stripe
-
-# Trigger a checkout session completed event
-stripe trigger checkout.session.completed
-
-# Use test card numbers in Stripe Checkout:
-# Success:        4242 4242 4242 4242
-# Requires auth:  4000 0025 0000 3155
-# Declined:       4000 0000 0000 0002
-```
-
-## Key Decisions
-
-- **Stripe-hosted Checkout over embedded Payment Element** -- reduces PCI compliance burden to SAQ-A and eliminates custom payment form UI bugs.
-- **Customer ID stored at first checkout** -- avoids orphaned Stripe customers by creating and persisting the customer before the checkout session.
-- **Idempotency key on session creation** -- prevents duplicate checkout sessions if the user double-clicks the subscribe button.
-- **Webhook event deduplication** -- stores processed event IDs to handle Stripe's at-least-once delivery guarantee without duplicate subscription activations.
-- **Server-side plan validation** -- the plan and price ID are resolved server-side, so clients cannot manipulate pricing.