@thierrynakoa/fire-flow 12.2.1 → 13.0.1

package/skills-library/ecommerce/pci-compliance-checklist.md

@@ -0,0 +1,192 @@
+# PCI DSS 4.0 Compliance Checklist for AI-Generated Code
+
+> Mandatory compliance gate for any payment-handling code. Non-compliance fines: $5,000–$100,000/month.
+
+**When to use:** Before deploying any code that processes, stores, or transmits payment data. This is a HARD GATE — payment features cannot ship without passing this checklist.
+**Stack:** Any web application handling payments (Node.js, Python, etc.)
+
+---
+
+## The Rule
+
+**AI-generated code must NEVER handle raw card data.** Period.
+
+The entire purpose of Stripe Elements, Stripe Checkout, and similar tokenization services is to keep card numbers off your servers. If your server never sees a card number, you're in the simplest PCI compliance tier (SAQ A or SAQ A-EP).
+
+The moment raw card data touches your server, you jump to SAQ D — the hardest compliance level, requiring quarterly scans, penetration testing, and extensive documentation.
+
+---
+
+## Scope Minimization Checklist
+
+### Tier 1: MUST Pass (Blockers)
+
+```
+□ NO raw card numbers in server code, logs, or database
+□ NO card data in URL parameters (GET requests)
+□ NO card data in error messages or stack traces
+□ NO card data in application logs (including debug mode)
+□ NO custom card input fields (use Stripe Elements iframe)
+□ NO card data stored in session/cookies
+□ Stripe.js loaded from js.stripe.com (not self-hosted)
+□ All payment pages served over HTTPS (no mixed content)
+□ API keys stored in environment variables (never in code)
+□ Secret keys never exposed to client-side code
+```
+
+### Tier 2: MUST Pass (Security)
+
+```
+□ Restricted API keys with minimal required permissions
+□ Webhook signature verification on all webhook endpoints
+□ CSRF protection on payment-related forms
+□ Rate limiting on payment API endpoints
+□ Input validation on all payment-related parameters
+□ Amount validation server-side (never trust client amounts)
+□ Currency validation (prevent currency confusion attacks)
+```
+
+### Tier 3: SHOULD Pass (Best Practices)
+
+```
+□ Logging of payment events (event ID and type only, no PCI data)
+□ Monitoring/alerting for failed payment attempts
+□ Idempotency keys on all payment mutations
+□ Graceful error handling (no raw Stripe errors to users)
+□ Content Security Policy headers allowing Stripe domains
+□ Subresource Integrity (SRI) on Stripe.js if applicable
+```
+
+---
+
+## Code Scanning Rules
+
+Run these checks against any AI-generated payment code:
+
+### Pattern 1: Card Number Detection
+
+```
+SCAN for: /\b\d{13,19}\b/ in any .js, .ts, .py, .env file
+SCAN for: card_number, cardNumber, cc_number, ccNumber in variable names
+SCAN for: "4242424242424242" in test files (acceptable ONLY in test config)
+ALERT if: Found in server-side code, logs, or database queries
+```
+
+### Pattern 2: Secret Key Exposure
+
+```
+SCAN for: sk_live_, sk_test_ in source code files (not .env)
+SCAN for: STRIPE_SECRET_KEY in client-side bundles
+SCAN for: API keys in git history (git log -p | grep sk_)
+ALERT if: Secret key found anywhere except .env or secrets manager
+```
+
+### Pattern 3: Raw Body Middleware
+
+```
+SCAN for: Webhook route handler
+CHECK: express.raw() or equivalent used on webhook route
+ALERT if: express.json() applied globally before webhook route
+REASON: JSON parsing destroys the raw body needed for signature verification
+```
+
+### Pattern 4: PCI Data in Logs
+
+```
+SCAN for: console.log, logger.info, logger.debug near payment code
+CHECK: No card data, CVV, expiry in logged objects
+SCAN for: JSON.stringify(req.body) in payment routes
+ALERT if: Full request body logged on payment endpoints
+```
+
+---
+
+## Compliant Architecture Pattern
+
+```
+┌─────────────────────────────────────────────┐
+│                  CLIENT                       │
+│                                               │
+│  ┌─────────────────────────────────────────┐ │
+│  │  Stripe Elements (iframe)                │ │
+│  │  Card data NEVER leaves this iframe      │ │
+│  │  → Tokenizes card → returns PaymentMethod│ │
+│  └─────────────────────────────────────────┘ │
+│           │ PaymentMethod ID (pm_xxx)         │
+│           ▼                                   │
+│  Your JavaScript (no card data here)          │
+│           │ pm_xxx + order details             │
+└───────────┼───────────────────────────────────┘
+            │ HTTPS POST
+┌───────────▼───────────────────────────────────┐
+│                  SERVER                        │
+│                                                │
+│  Receives: pm_xxx (token), amount, currency    │
+│  NEVER receives: card number, CVV, expiry      │
+│                                                │
+│  → Validates amount against database prices    │
+│  → Creates PaymentIntent with pm_xxx           │
+│  → Returns client_secret for confirmation      │
+│                                                │
+│  Webhook endpoint:                             │
+│  → Verifies signature (express.raw body)       │
+│  → Processes payment confirmation              │
+│  → Updates order status                        │
+└────────────────────────────────────────────────┘
+```
+
+---
+
+## Content Security Policy for Stripe
+
+```javascript
+// Required CSP headers for Stripe Elements
+const cspHeaders = {
+  'Content-Security-Policy': [
+    "default-src 'self'",
+    "script-src 'self' https://js.stripe.com",
+    "frame-src https://js.stripe.com https://hooks.stripe.com",
+    "connect-src 'self' https://api.stripe.com",
+    "img-src 'self' https://*.stripe.com",
+  ].join('; ')
+};
+```
+
+---
+
+## Common AI-Generated Violations
+
+| Violation | Why AI Does This | Fix |
+|-----------|-----------------|-----|
+| Custom `<input>` for card number | Seems simpler than Stripe Elements | Always use `CardElement` from @stripe/react-stripe-js |
+| Logging `req.body` on payment routes | Standard debugging pattern | Log only event ID and type |
+| `sk_test_*` in source code | Faster than env setup during prototyping | Set up .env from the start |
+| Storing card last-4 in user table | Seems useful for display | Retrieve from Stripe API on demand |
+| Amount from client `req.body.amount` | Trust client data pattern | Calculate from server-side price lookup |
+
+---
+
+## Compliance Declaration
+
+After verification, the responsible developer signs off:
+
+```
+I verify that this payment integration:
+- Never handles raw card data on our servers
+- Uses Stripe's hosted tokenization (Elements/Checkout)
+- Stores API keys only in environment variables
+- Validates all amounts server-side
+- Verifies webhook signatures
+- Logs no PCI-scoped data
+
+Signed: ________________  Date: ________
+```
+
+---
+
+## Sources
+
+- PCI Security Standards Council: "AI Principles — Securing the Use of AI in Payment Environments" (Spring 2025)
+- PCI SSC: "New Guidance — Integrating AI into PCI Assessments" (2025)
+- Stripe Documentation: Elements, Checkout, Webhooks
+- PCI DSS 4.0 Requirements (mandatory March 31, 2025)

package/skills-library/ecommerce/refund-chargeback-handling.md

@@ -0,0 +1,177 @@
+# Refund & Chargeback Handling
+
+> Partial refunds, refund authorization flows, chargeback dispute handling, and tax recalculation patterns.
+
+**When to use:** Implementing any refund capability in an e-commerce system. Critical for production systems processing real payments.
+**Stack:** Node.js/Express, Stripe, PostgreSQL/MySQL
+
+---
+
+## Refund Types
+
+| Type | Description | Use Case |
+|------|-------------|----------|
+| **Full refund** | Return entire payment amount | Order cancelled, wrong item shipped |
+| **Partial refund** | Return portion of payment | One item from multi-item order, damaged item |
+| **Store credit** | Issue credit instead of cash refund | Customer retention, faster processing |
+
+---
+
+## Refund API
+
+```javascript
+// Full refund
+router.post('/api/orders/:orderId/refund', requireAdmin, async (req, res) => {
+  const { reason, items, amount } = req.body;
+  const order = await getOrder(req.params.orderId);
+
+  if (!order) return res.status(404).json({ error: 'Order not found' });
+  if (!['confirmed', 'processing', 'shipped', 'delivered'].includes(order.status)) {
+    return res.status(400).json({ error: `Cannot refund order in ${order.status} status` });
+  }
+
+  // Calculate refund amount
+  let refundAmount;
+  if (amount) {
+    // Explicit amount (admin override)
+    refundAmount = Math.round(amount * 100); // cents
+  } else if (items && items.length > 0) {
+    // Partial refund: sum of selected items
+    refundAmount = items.reduce((sum, item) => {
+      const orderItem = order.items.find(i => i.id === item.id);
+      return sum + (orderItem.unit_price * item.quantity * 100);
+    }, 0);
+  } else {
+    // Full refund
+    refundAmount = Math.round(order.total * 100);
+  }
+
+  // Create Stripe refund
+  const refund = await stripe.refunds.create({
+    payment_intent: order.payment_intent_id,
+    amount: refundAmount,
+    reason: reason === 'duplicate' ? 'duplicate'
+          : reason === 'fraud' ? 'fraudulent'
+          : 'requested_by_customer',
+    metadata: { order_id: order.id, admin_id: req.user.id },
+  });
+
+  // Record refund
+  await db.query(
+    `INSERT INTO refunds (order_id, stripe_refund_id, amount, reason, status, created_by)
+     VALUES ($1, $2, $3, $4, $5, $6)`,
+    [order.id, refund.id, refundAmount / 100, reason, refund.status, req.user.id]
+  );
+
+  // Update order status if fully refunded
+  const totalRefunded = await getTotalRefunded(order.id);
+  if (totalRefunded >= order.total) {
+    await transitionOrder(order.id, 'refunded', { refund_id: refund.id });
+  }
+
+  // Restore inventory if items returned
+  if (items) {
+    for (const item of items) {
+      await restoreStock(item.product_id, item.variant_id, item.quantity);
+    }
+  }
+
+  res.json({
+    refund_id: refund.id,
+    amount: refundAmount / 100,
+    status: refund.status,
+    total_refunded: totalRefunded + refundAmount / 100,
+    order_total: order.total,
+  });
+});
+```
+
+---
+
+## Chargeback/Dispute Handling
+
+When a customer disputes a charge with their bank:
+
+```javascript
+// Webhook handler for disputes
+async function handleDisputeCreated(event) {
+  const dispute = event.data.object;
+
+  // Record dispute
+  await db.query(
+    `INSERT INTO disputes (stripe_dispute_id, payment_intent_id, amount, reason, status, evidence_due_by)
+     VALUES ($1, $2, $3, $4, $5, $6)`,
+    [dispute.id, dispute.payment_intent, dispute.amount / 100,
+     dispute.reason, dispute.status,
+     new Date(dispute.evidence_details.due_by * 1000)]
+  );
+
+  // Alert admin immediately
+  await sendAdminAlert({
+    type: 'DISPUTE_CREATED',
+    amount: dispute.amount / 100,
+    reason: dispute.reason,
+    due_by: new Date(dispute.evidence_details.due_by * 1000),
+    order: await getOrderByPaymentIntent(dispute.payment_intent),
+  });
+}
+
+// Submit evidence
+async function submitDisputeEvidence(disputeId) {
+  const dispute = await getDispute(disputeId);
+  const order = await getOrderByPaymentIntent(dispute.payment_intent_id);
+  const metadata = await getOrderFraudMetadata(order.id);
+
+  await stripe.disputes.update(dispute.stripe_dispute_id, {
+    evidence: {
+      customer_name: order.customer_name,
+      customer_email_address: order.customer_email,
+      product_description: order.items.map(i => i.name).join(', '),
+      billing_address: order.billing_address,
+      shipping_address: order.shipping_address,
+      shipping_tracking_number: order.tracking_number,
+      customer_purchase_ip: metadata.ip_address,
+      receipt: order.receipt_url,            // Stripe receipt URL
+      // Upload additional evidence files via Stripe File API
+    },
+  });
+}
+```
+
+---
+
+## Database Schema
+
+```sql
+CREATE TABLE refunds (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  order_id UUID NOT NULL REFERENCES orders(id),
+  stripe_refund_id VARCHAR(255),
+  amount DECIMAL(10,2) NOT NULL,
+  reason VARCHAR(100),
+  status VARCHAR(20) DEFAULT 'pending',
+  created_by UUID REFERENCES users(id),
+  created_at TIMESTAMP DEFAULT NOW()
+);
+
+CREATE TABLE disputes (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  stripe_dispute_id VARCHAR(255) UNIQUE,
+  payment_intent_id VARCHAR(255),
+  amount DECIMAL(10,2) NOT NULL,
+  reason VARCHAR(100),
+  status VARCHAR(30) DEFAULT 'needs_response',
+  evidence_due_by TIMESTAMP,
+  evidence_submitted_at TIMESTAMP,
+  outcome VARCHAR(20),  -- won | lost
+  created_at TIMESTAMP DEFAULT NOW()
+);
+```
+
+---
+
+## Sources
+
+- Internal gap analysis: GAP-ECOM-3 (Refund & Chargeback Handling)
+- Stripe API: Refunds and Disputes documentation (2025)
+- Stigg Engineering: Webhook best practices (2025)

package/skills-library/ecommerce/shipping-carrier-integration.md

@@ -0,0 +1,218 @@
+# Shipping & Carrier Integration Patterns
+
+> Rate lookups, label generation, tracking sync, and returns handling for e-commerce fulfillment.
+
+**When to use:** Building any e-commerce system that ships physical products. Applies during the fulfillment phase of order processing.
+**Stack:** Node.js/Express, EasyPost or ShipStation API (recommended), or direct carrier APIs
+
+---
+
+## Architecture Decision: Direct vs Aggregator
+
+| Approach | Pros | Cons | Best For |
+|----------|------|------|----------|
+| **Direct carrier APIs** (FedEx, UPS, USPS) | Full control, no middleman fees | Each carrier = separate integration, different APIs | High volume, single carrier |
+| **Aggregator** (EasyPost, ShipStation, Shippo) | One API for all carriers, label generation, tracking | Monthly cost, slight markup on rates | Most e-commerce projects |
+
+**Recommendation:** Use an aggregator unless you have a specific reason not to. EasyPost is developer-friendly with a good free tier.
+
+---
+
+## EasyPost Integration (Recommended)
+
+```bash
+npm install @easypost/api
+```
+
+### Rate Shopping
+
+```javascript
+import EasyPost from '@easypost/api';
+const client = new EasyPost(process.env.EASYPOST_API_KEY);
+
+async function getRates(fromAddress, toAddress, parcel) {
+  const shipment = await client.Shipment.create({
+    from_address: {
+      street1: fromAddress.street,
+      city: fromAddress.city,
+      state: fromAddress.state,
+      zip: fromAddress.zip,
+      country: fromAddress.country || 'US',
+    },
+    to_address: {
+      street1: toAddress.street,
+      city: toAddress.city,
+      state: toAddress.state,
+      zip: toAddress.zip,
+      country: toAddress.country || 'US',
+    },
+    parcel: {
+      length: parcel.length,  // inches
+      width: parcel.width,
+      height: parcel.height,
+      weight: parcel.weight,  // ounces
+    },
+  });
+
+  // Return sorted rates
+  return shipment.rates
+    .map(rate => ({
+      id: rate.id,
+      carrier: rate.carrier,           // 'USPS', 'FedEx', 'UPS'
+      service: rate.service,           // 'Priority', 'Ground', 'Express'
+      rate: parseFloat(rate.rate),     // Dollar amount
+      est_delivery_days: rate.est_delivery_days,
+      delivery_date: rate.delivery_date,
+    }))
+    .sort((a, b) => a.rate - b.rate);
+}
+```
+
+### Buy Label
+
+```javascript
+async function buyShippingLabel(shipmentId, rateId) {
+  const shipment = await client.Shipment.retrieve(shipmentId);
+  const purchased = await shipment.buy(rateId);
+
+  return {
+    tracking_number: purchased.tracking_code,
+    tracking_url: purchased.tracker?.public_url,
+    label_url: purchased.postage_label.label_url,
+    label_format: purchased.postage_label.label_file_type, // 'PDF' or 'PNG'
+    carrier: purchased.selected_rate.carrier,
+    service: purchased.selected_rate.service,
+    cost: parseFloat(purchased.selected_rate.rate),
+  };
+}
+```
+
+### Track Package
+
+```javascript
+async function trackPackage(trackingNumber, carrier) {
+  const tracker = await client.Tracker.create({
+    tracking_code: trackingNumber,
+    carrier: carrier,
+  });
+
+  return {
+    status: tracker.status,                    // 'in_transit', 'delivered', etc.
+    est_delivery: tracker.est_delivery_date,
+    tracking_details: tracker.tracking_details.map(d => ({
+      status: d.status,
+      message: d.message,
+      datetime: d.datetime,
+      city: d.tracking_location?.city,
+      state: d.tracking_location?.state,
+    })),
+  };
+}
+```
+
+---
+
+## Shipping API Endpoints
+
+```javascript
+// POST /api/orders/:id/shipping/rates — Get available rates
+router.post('/orders/:id/shipping/rates', requireAuth, async (req, res) => {
+  const order = await getOrder(req.params.id);
+  const warehouse = await getWarehouseAddress();
+
+  const rates = await getRates(warehouse, order.shipping_address, {
+    length: 12, width: 8, height: 6,
+    weight: calculateOrderWeight(order.items),
+  });
+
+  res.json({ rates });
+});
+
+// POST /api/orders/:id/shipping/purchase — Buy label
+router.post('/orders/:id/shipping/purchase', requireAdmin, async (req, res) => {
+  const { rate_id, shipment_id } = req.body;
+
+  const label = await buyShippingLabel(shipment_id, rate_id);
+
+  await db.query(
+    `UPDATE orders SET
+       tracking_number = $1, tracking_url = $2,
+       shipping_label_url = $3, shipping_carrier = $4,
+       shipping_cost = $5, status = 'shipped', shipped_at = NOW()
+     WHERE id = $6`,
+    [label.tracking_number, label.tracking_url, label.label_url,
+     label.carrier, label.cost, req.params.id]
+  );
+
+  await sendShippingNotification(req.params.id, label);
+  res.json({ label });
+});
+
+// GET /api/orders/:id/tracking — Get tracking info
+router.get('/orders/:id/tracking', requireAuth, async (req, res) => {
+  const order = await getOrder(req.params.id);
+  if (!order.tracking_number) {
+    return res.json({ status: 'not_shipped' });
+  }
+
+  const tracking = await trackPackage(order.tracking_number, order.shipping_carrier);
+  res.json(tracking);
+});
+```
+
+---
+
+## Free Shipping Threshold
+
+```javascript
+function calculateShipping(subtotal, shippingRate) {
+  const FREE_SHIPPING_THRESHOLD = parseFloat(process.env.FREE_SHIPPING_THRESHOLD || '75');
+
+  if (subtotal >= FREE_SHIPPING_THRESHOLD) {
+    return { cost: 0, reason: 'free_shipping_threshold' };
+  }
+
+  return {
+    cost: shippingRate,
+    free_shipping_at: FREE_SHIPPING_THRESHOLD,
+    remaining: FREE_SHIPPING_THRESHOLD - subtotal,
+  };
+}
+```
+
+---
+
+## Return Labels
+
+```javascript
+async function createReturnLabel(orderId) {
+  const order = await getOrder(orderId);
+  const warehouse = await getWarehouseAddress();
+
+  // Reverse: customer → warehouse
+  const shipment = await client.Shipment.create({
+    from_address: order.shipping_address,
+    to_address: warehouse,
+    parcel: { length: 12, width: 8, height: 6, weight: 16 },
+    is_return: true,
+  });
+
+  // Buy cheapest option
+  const cheapest = shipment.rates.sort((a, b) => a.rate - b.rate)[0];
+  const label = await shipment.buy(cheapest.id);
+
+  return {
+    tracking_number: label.tracking_code,
+    label_url: label.postage_label.label_url,
+    cost: parseFloat(cheapest.rate),
+  };
+}
+```
+
+---
+
+## Sources
+
+- Internal gap analysis: GAP-ECOM-8 (Shipping & Carrier Integration)
+- EasyPost API Documentation (2025)
+- ShipStation API Documentation (2025)