feat(merch): harden checkout API for production readiness

Add CORS allowlist, checkout rate limits, async Stripe webhook fulfilment
with retries, order status by session, shop post-payment polling, API v2.1.0
OpenAPI updates, and expanded merch tests.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: earlution

.env.example

@@ -26,5 +26,10 @@ MERCH_ARTWORK_BASE_URL=
 # MERCH_S3_ACCESS_KEY=
 # MERCH_S3_SECRET_KEY=
 
+# Merch hardening
+# MERCH_CORS_ORIGINS=https://6axiscompass.uk,https://www.6axiscompass.uk
+# MERCH_CHECKOUT_RATE_LIMIT=20
+# MERCH_FULFIL_RETRIES=3
+# MERCH_AUTO_REFUND_ON_FAILURE=false
+
 # Static shop build (npm run build)
-# MERCH_API_BASE=https://your-api-host

API.md

@@ -2,6 +2,7 @@
 
 | Version | Date | Changes |
 |---------|------|---------|
+| 2.1.0 | 2026-05-22 | **Merch API:** `POST /api/checkout/session`, `POST /api/webhooks/stripe`, `GET /api/merch/prices`, `GET /api/orders/*`, chart `background` / `labelMerch`. |
 | 2.0.2 | 2026-05-22 | **Spatial inversion (app v3.6.0):** default spatial charts use no rim inversion; `register: structural` inverts `Governance` + `Class` only. |
 | 2.0.1 | 2026-05-20 | **Spatial radar (app v3.1.0):** `POST /api/chart` default `layout: spatial` (OQ5); `orientation: spatial`; `invertedAxes`; pedagogical OQ2 via `layout: pedagogical`. |
 | 2.0.0 | 2026-05-20 | **Public read API (Phase 1):** `GET /api/actors`, `GET /api/actors/:slug`, `POST /api/chart`, `GET /api/axes`, `GET /api/openapi.json` unauthenticated when `API_PUBLIC_READ=true` (default). Rate limit on chart. Optional legacy Bearer on read. `GET /api/health` adds `apiVersion`, `publicRead`. |
@@ -28,7 +29,7 @@ Production chart API hosting is maintainer-operated (not served from GitHub Page
 
 | Semver | What it tracks | Current |
 |--------|----------------|---------|
-| **API** (`apiVersion` in `/api/health`) | REST contract (auth zones, routes, limits) | **2.0.2** |
+| **API** (`apiVersion` in `/api/health`) | REST contract (auth zones, routes, limits) | **2.1.0** |
 | **App** (`version` in `/api/health`) | Compass package / Pages bundle | See `package.json` (e.g. **2.6.2**) |
 
 ---

api/lib/config.js

@@ -1,4 +1,4 @@
-export const API_VERSION = '2.0.2';
+export const API_VERSION = '2.1.0';
 
 /** Public read routes skip Bearer auth when true (default). Set API_PUBLIC_READ=false for legacy mode. */
 export function isPublicReadEnabled() {

api/lib/cors.js

@@ -1,8 +1,37 @@
 const PUBLIC_METHODS = 'GET, POST, OPTIONS';
 const PUBLIC_HEADERS = 'Content-Type, Authorization';
 
+function allowedOrigins() {
+  const raw = process.env.MERCH_CORS_ORIGINS || '';
+  if (!raw.trim()) return null;
+  return raw.split(',').map(s => s.trim()).filter(Boolean);
+}
+
+function requestOrigin(req) {
+  const origin = req.headers.origin;
+  if (origin) return origin;
+  const referer = req.headers.referer;
+  if (!referer) return null;
+  try {
+    return new URL(referer).origin;
+  } catch {
+    return null;
+  }
+}
+
 export function applyPublicCors(req, res) {
-  res.setHeader('Access-Control-Allow-Origin', '*');
+  const allowlist = allowedOrigins();
+  const origin = requestOrigin(req);
+
+  if (!allowlist) {
+    res.setHeader('Access-Control-Allow-Origin', '*');
+  } else if (origin && allowlist.includes(origin)) {
+    res.setHeader('Access-Control-Allow-Origin', origin);
+    res.setHeader('Vary', 'Origin');
+  } else if (origin) {
+    res.setHeader('Access-Control-Allow-Origin', 'null');
+  }
+
   res.setHeader('Access-Control-Allow-Methods', PUBLIC_METHODS);
   res.setHeader('Access-Control-Allow-Headers', PUBLIC_HEADERS);
 }
@@ -12,3 +41,11 @@ export function handleOptions(req, res) {
   res.statusCode = 204;
   res.end();
 }
+
+export function isCorsAllowed(req) {
+  const allowlist = allowedOrigins();
+  if (!allowlist) return true;
+  const origin = requestOrigin(req);
+  if (!origin) return true;
+  return allowlist.includes(origin);
+}

api/lib/merch-fulfilment-queue.js

@@ -0,0 +1,53 @@
+import { fulfilOrderFromStripeSession } from './merch-orders.js';
+import { refundPayment, isStripeConfigured } from './stripe-client.js';
+import { getOrderByStripeSession, updateOrder } from './order-store.js';
+
+const pending = new Set();
+
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+function maxRetries() {
+  return parseInt(process.env.MERCH_FULFIL_RETRIES || '3', 10);
+}
+
+function autoRefundEnabled() {
+  return process.env.MERCH_AUTO_REFUND_ON_FAILURE === 'true';
+}
+
+async function runFulfilmentWithRetry(session, attempt = 1) {
+  try {
+    await fulfilOrderFromStripeSession(session);
+  } catch (err) {
+    console.error(`Fulfilment attempt ${attempt} failed for session ${session.id}:`, err.message);
+    if (attempt < maxRetries()) {
+      await sleep(2000 * attempt);
+      return runFulfilmentWithRetry(session, attempt + 1);
+    }
+
+    if (autoRefundEnabled() && isStripeConfigured() && session.payment_intent) {
+      try {
+        await refundPayment(session.payment_intent);
+        const order = getOrderByStripeSession(session.id);
+        if (order) updateOrder(order.id, { status: 'refunded', error: err.message });
+        console.error(`Refunded payment ${session.payment_intent} after fulfilment failure`);
+      } catch (refundErr) {
+        console.error('Auto-refund failed:', refundErr.message);
+      }
+    }
+  }
+}
+
+export function scheduleFulfilment(session) {
+  if (!session?.id) return;
+  if (pending.has(session.id)) return;
+  pending.add(session.id);
+  setImmediate(() => {
+    runFulfilmentWithRetry(session).finally(() => pending.delete(session.id));
+  });
+}
+
+export function isFulfilmentPending(sessionId) {
+  return pending.has(sessionId);
+}

api/lib/merch-orders.js

@@ -48,7 +48,7 @@ export async function createMerchCheckoutSession(body) {
 
 export async function fulfilOrderFromStripeSession(session) {
   const existing = getOrderByStripeSession(session.id);
-  if (existing?.status === 'submitted' || existing?.status === 'fulfilled') {
+  if (['submitted', 'fulfilled', 'awaiting_printful', 'artwork_ready'].includes(existing?.status)) {
     return existing;
   }
 
@@ -129,6 +129,16 @@ export async function fulfilOrderFromStripeSession(session) {
 export function getPublicOrderStatus(orderId) {
   const order = getOrder(orderId);
   if (!order) return null;
+  return publicStatusFromOrder(order);
+}
+
+export function getPublicOrderStatusBySession(sessionId) {
+  const order = getOrderByStripeSession(sessionId);
+  if (!order) return null;
+  return publicStatusFromOrder(order);
+}
+
+function publicStatusFromOrder(order) {
   return {
     id: order.id,
     status: order.status,

api/lib/rate-limit.js

@@ -1,5 +1,6 @@
 const WINDOW_MS = 60_000;
-const MAX_PER_WINDOW = parseInt(process.env.API_CHART_RATE_LIMIT || '60', 10);
+const MAX_CHART = parseInt(process.env.API_CHART_RATE_LIMIT || '60', 10);
+const MAX_CHECKOUT = parseInt(process.env.MERCH_CHECKOUT_RATE_LIMIT || '20', 10);
 const buckets = new Map();
 
 function clientKey(req) {
@@ -8,16 +9,16 @@ function clientKey(req) {
   return req.socket?.remoteAddress || 'unknown';
 }
 
-export function checkChartRateLimit(req, res) {
-  const key = clientKey(req);
+function checkLimit(req, res, scope, max) {
+  const key = `${scope}:${clientKey(req)}`;
   const now = Date.now();
   let bucket = buckets.get(key);
   if (!bucket || now >= bucket.resetAt) {
     bucket = { count: 0, resetAt: now + WINDOW_MS };
     buckets.set(key, bucket);
   }
   bucket.count += 1;
-  if (bucket.count > MAX_PER_WINDOW) {
+  if (bucket.count > max) {
     const retryAfter = Math.ceil((bucket.resetAt - now) / 1000);
     res.statusCode = 429;
     res.setHeader('Content-Type', 'application/json');
@@ -27,3 +28,11 @@ export function checkChartRateLimit(req, res) {
   }
   return true;
 }
+
+export function checkChartRateLimit(req, res) {
+  return checkLimit(req, res, 'chart', MAX_CHART);
+}
+
+export function checkCheckoutRateLimit(req, res) {
+  return checkLimit(req, res, 'checkout', MAX_CHECKOUT);
+}

api/openapi-v2.0.0.json

@@ -2,8 +2,8 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Six-Axis Compass API",
-    "version": "2.0.0",
-    "description": "Public read API (unauthenticated by default). Private write under /api/admin/* requires ADMIN_SECRET (Phase 2)."
+    "version": "2.1.0",
+    "description": "Public read API (unauthenticated by default). Merch checkout routes added in v2.1.0."
   },
   "servers": [{ "url": "/" }],
   "paths": {
@@ -30,7 +30,20 @@
     "/api/chart": {
       "post": {
         "summary": "Render radar chart",
-        "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } } },
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "background": { "enum": ["white", "transparent", "dark"] },
+                  "labelMerch": { "type": "boolean" },
+                  "labelMode": { "enum": ["trigram", "full"] }
+                }
+              }
+            }
+          }
+        },
         "responses": {
           "200": { "description": "image/svg+xml or image/png" },
           "400": { "description": "Validation error" },
@@ -41,6 +54,44 @@
     "/api/axes": {
       "get": { "summary": "Canonical axes and pole labels", "responses": { "200": { "description": "Axis catalog" } } }
     },
+    "/api/merch/prices": {
+      "get": {
+        "summary": "Merch GBP prices from catalog",
+        "responses": { "200": { "description": "Price map keyed by product id" } }
+      }
+    },
+    "/api/checkout/session": {
+      "post": {
+        "summary": "Create Stripe Checkout session for merch order",
+        "responses": {
+          "200": { "description": "Checkout URL and order id" },
+          "400": { "description": "Validation error" },
+          "403": { "description": "CORS origin not allowed" },
+          "429": { "description": "Rate limited" },
+          "503": { "description": "Stripe not configured" }
+        }
+      }
+    },
+    "/api/orders/{orderId}": {
+      "get": {
+        "summary": "Public order status by internal order id",
+        "parameters": [{ "name": "orderId", "in": "path", "required": true, "schema": { "type": "string" } }],
+        "responses": { "200": { "description": "Order status" }, "404": { "description": "Not found" } }
+      }
+    },
+    "/api/orders/session/{sessionId}": {
+      "get": {
+        "summary": "Public order status by Stripe Checkout session id",
+        "parameters": [{ "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } }],
+        "responses": { "200": { "description": "Order status" }, "404": { "description": "Not found" } }
+      }
+    },
+    "/api/webhooks/stripe": {
+      "post": {
+        "summary": "Stripe webhook (checkout.session.completed)",
+        "responses": { "200": { "description": "Acknowledged" }, "400": { "description": "Invalid signature" } }
+      }
+    },
     "/api/openapi.json": {
       "get": { "summary": "OpenAPI document", "responses": { "200": { "description": "This document" } } }
     }

api/routes/checkout.js

@@ -1,7 +1,13 @@
 import { sendJSON } from '../lib/auth.js';
+import { isCorsAllowed } from '../lib/cors.js';
 import { createMerchCheckoutSession, isMerchEnabled } from '../lib/merch-orders.js';
 
 export async function handleCheckoutSession(req, res, body) {
+  if (!isCorsAllowed(req)) {
+    sendJSON(res, 403, { error: 'Origin not allowed' });
+    return;
+  }
+
   if (!isMerchEnabled()) {
     sendJSON(res, 503, {
       error: 'Merch checkout is not configured',

api/routes/orders.js

@@ -1,5 +1,5 @@
 import { sendJSON } from '../lib/auth.js';
-import { getPublicOrderStatus } from '../lib/merch-orders.js';
+import { getPublicOrderStatus, getPublicOrderStatusBySession } from '../lib/merch-orders.js';
 
 export async function handleOrderStatus(req, res, orderId) {
   const status = getPublicOrderStatus(orderId);
@@ -9,3 +9,12 @@ export async function handleOrderStatus(req, res, orderId) {
   }
   sendJSON(res, 200, status);
 }
+
+export async function handleOrderStatusBySession(req, res, sessionId) {
+  const status = getPublicOrderStatusBySession(sessionId);
+  if (!status) {
+    sendJSON(res, 404, { error: 'Order not found' });
+    return;
+  }
+  sendJSON(res, 200, status);
+}