@cmssy/next 0.2.3 → 0.2.4

package/dist/index.cjs

@@ -1231,11 +1231,67 @@ function createCmssyOrdersRoute(config) {
     }
   };
 }
+var CmssyWebhookError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "CmssyWebhookError";
+  }
+};
+var DEFAULT_TOLERANCE_SECONDS = 300;
+function parseSignatureHeader(header) {
+  let timestamp = null;
+  let signature = null;
+  for (const part of header.split(",")) {
+    const idx = part.indexOf("=");
+    if (idx === -1) continue;
+    const key = part.slice(0, idx).trim();
+    const value = part.slice(idx + 1).trim();
+    if (key === "t") timestamp = Number(value);
+    else if (key === "v1") signature = value;
+  }
+  if (timestamp === null || !Number.isFinite(timestamp) || !signature) {
+    throw new CmssyWebhookError("Malformed X-Cmssy-Signature header");
+  }
+  return { timestamp, signature };
+}
+function timingSafeHexEqual(expectedHex, providedHex) {
+  const expected = Buffer.from(expectedHex, "hex");
+  const provided = Buffer.from(providedHex, "hex");
+  if (expected.length !== provided.length) return false;
+  return crypto$1.timingSafeEqual(expected, provided);
+}
+function verifyCmssyWebhook(options) {
+  const { body, signatureHeader, secret } = options;
+  if (!signatureHeader) {
+    throw new CmssyWebhookError("Missing X-Cmssy-Signature header");
+  }
+  if (!secret) {
+    throw new CmssyWebhookError("Missing webhook secret");
+  }
+  const { timestamp, signature } = parseSignatureHeader(signatureHeader);
+  const toleranceMs = (options.toleranceSeconds ?? DEFAULT_TOLERANCE_SECONDS) * 1e3;
+  const now = options.now ?? Date.now();
+  if (Math.abs(now - timestamp) > toleranceMs) {
+    throw new CmssyWebhookError("Webhook timestamp outside tolerance");
+  }
+  const expected = crypto$1.createHmac("sha256", secret).update(`${timestamp}.${body}`).digest("hex");
+  if (!timingSafeHexEqual(expected, signature)) {
+    throw new CmssyWebhookError("Webhook signature mismatch");
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(body);
+  } catch {
+    throw new CmssyWebhookError("Webhook body is not valid JSON");
+  }
+  return parsed;
+}
 
 exports.CMSSY_CART_COOKIE = CMSSY_CART_COOKIE;
 exports.CMSSY_EDIT_HEADER = CMSSY_EDIT_HEADER;
 exports.CMSSY_LOCALE_HEADER = CMSSY_LOCALE_HEADER;
 exports.CMSSY_SESSION_COOKIE = CMSSY_SESSION_COOKIE;
+exports.CmssyWebhookError = CmssyWebhookError;
 exports.SESSION_MAX_AGE_SECONDS = SESSION_MAX_AGE_SECONDS;
 exports.applyCmssyCsp = applyCmssyCsp;
 exports.assertAuthConfig = assertAuthConfig;
@@ -1259,3 +1315,4 @@ exports.openSession = openSession;
 exports.sealSession = sealSession;
 exports.sessionCookieOptions = sessionCookieOptions;
 exports.splitCmssyLocale = splitCmssyLocale;
+exports.verifyCmssyWebhook = verifyCmssyWebhook;

package/dist/index.d.cts

@@ -160,4 +160,66 @@ interface MyOrdersResult {
     hasMore: boolean;
 }
 
-export { CMSSY_CART_COOKIE, CMSSY_EDIT_HEADER, CMSSY_LOCALE_HEADER, CMSSY_SESSION_COOKIE, type CmssyAuthConfig, type CmssyAuthMiddleware, type CmssyAuthRouteHandlers, type CmssyCartRouteHandlers, type CmssyCspOptions, type CmssyDraftRouteConfig, type CmssyEditorProps, type CmssyNextConfig, type CmssyOrdersRouteHandlers, type CmssySessionPayload, type CmssySessionUser, type CreateCmssyPageOptions, type FetchProductOptions, type FetchProductsOptions, type MyOrdersResult, SESSION_MAX_AGE_SECONDS, type SessionCookieOptions, applyCmssyCsp, assertAuthConfig, cmssyCspHeaders, createCmssyAuthMiddleware, createCmssyAuthRoute, createCmssyCartRoute, createCmssyOrdersRoute, createCmssyPage, createDraftRoute, fetchProduct, fetchProducts, getCmssyAccessToken, getCmssyLocale, getCmssyUser, isAccessExpired, isCmssyEditMode, isCmssyEditRequest, localeForPathname, openSession, sealSession, sessionCookieOptions, splitCmssyLocale };
+/**
+ * Verify + parse an inbound cmssy webhook (CMS-693 / CMS-694).
+ *
+ * cmssy signs each delivery with HMAC-SHA256 over `${timestamp}.${body}`
+ * and sends the result in the `X-Cmssy-Signature: t=<ms>,v1=<hex>`
+ * header, plus a unique `X-Cmssy-Webhook-Id`. This helper recomputes the
+ * signature (timing-safe compare), rejects stale timestamps to bound
+ * replay, and returns the typed event.
+ *
+ * IMPORTANT: pass the RAW request body string (e.g. `await req.text()`),
+ * never a re-serialized object - the signed bytes must match exactly.
+ */
+/** Serialized order carried in an order.* webhook (mirrors the backend). */
+interface CmssyWebhookOrder {
+    id: string;
+    workspaceId: string;
+    displayStatus: string;
+    paymentStatus: string;
+    fulfillmentStatus: string;
+    total: number;
+    currency: string;
+    customerId: string | null;
+    customerEmail: string;
+    paymentProvider: string | null;
+    paymentReference: string | null;
+    refundedAmount: number;
+    createdAt: string;
+    updatedAt: string;
+}
+interface CmssyWebhookEvent {
+    /** Delivery id - also sent in X-Cmssy-Webhook-Id; dedup on it. */
+    id: string;
+    /** e.g. "order.paid", "order.refunded". */
+    event: string;
+    createdAt: string;
+    data: {
+        workspaceId: string;
+        order: CmssyWebhookOrder;
+    };
+}
+interface VerifyCmssyWebhookOptions {
+    /** Raw request body string (NOT parsed JSON). */
+    body: string;
+    /** The `X-Cmssy-Signature` header value, or null if absent. */
+    signatureHeader: string | null;
+    /** The endpoint's signing secret. */
+    secret: string;
+    /** Max age of the signed timestamp, in seconds. Default 300 (5 min). */
+    toleranceSeconds?: number;
+    /** Override the current time (ms) - for tests. */
+    now?: number;
+}
+declare class CmssyWebhookError extends Error {
+    constructor(message: string);
+}
+/**
+ * Verify the signature + freshness and return the parsed event. Throws
+ * `CmssyWebhookError` on any failure (missing/malformed header, bad
+ * signature, stale timestamp, invalid JSON) - catch it and respond 400.
+ */
+declare function verifyCmssyWebhook(options: VerifyCmssyWebhookOptions): CmssyWebhookEvent;
+
+export { CMSSY_CART_COOKIE, CMSSY_EDIT_HEADER, CMSSY_LOCALE_HEADER, CMSSY_SESSION_COOKIE, type CmssyAuthConfig, type CmssyAuthMiddleware, type CmssyAuthRouteHandlers, type CmssyCartRouteHandlers, type CmssyCspOptions, type CmssyDraftRouteConfig, type CmssyEditorProps, type CmssyNextConfig, type CmssyOrdersRouteHandlers, type CmssySessionPayload, type CmssySessionUser, CmssyWebhookError, type CmssyWebhookEvent, type CmssyWebhookOrder, type CreateCmssyPageOptions, type FetchProductOptions, type FetchProductsOptions, type MyOrdersResult, SESSION_MAX_AGE_SECONDS, type SessionCookieOptions, type VerifyCmssyWebhookOptions, applyCmssyCsp, assertAuthConfig, cmssyCspHeaders, createCmssyAuthMiddleware, createCmssyAuthRoute, createCmssyCartRoute, createCmssyOrdersRoute, createCmssyPage, createDraftRoute, fetchProduct, fetchProducts, getCmssyAccessToken, getCmssyLocale, getCmssyUser, isAccessExpired, isCmssyEditMode, isCmssyEditRequest, localeForPathname, openSession, sealSession, sessionCookieOptions, splitCmssyLocale, verifyCmssyWebhook };

package/dist/index.d.ts

@@ -160,4 +160,66 @@ interface MyOrdersResult {
     hasMore: boolean;
 }
 
-export { CMSSY_CART_COOKIE, CMSSY_EDIT_HEADER, CMSSY_LOCALE_HEADER, CMSSY_SESSION_COOKIE, type CmssyAuthConfig, type CmssyAuthMiddleware, type CmssyAuthRouteHandlers, type CmssyCartRouteHandlers, type CmssyCspOptions, type CmssyDraftRouteConfig, type CmssyEditorProps, type CmssyNextConfig, type CmssyOrdersRouteHandlers, type CmssySessionPayload, type CmssySessionUser, type CreateCmssyPageOptions, type FetchProductOptions, type FetchProductsOptions, type MyOrdersResult, SESSION_MAX_AGE_SECONDS, type SessionCookieOptions, applyCmssyCsp, assertAuthConfig, cmssyCspHeaders, createCmssyAuthMiddleware, createCmssyAuthRoute, createCmssyCartRoute, createCmssyOrdersRoute, createCmssyPage, createDraftRoute, fetchProduct, fetchProducts, getCmssyAccessToken, getCmssyLocale, getCmssyUser, isAccessExpired, isCmssyEditMode, isCmssyEditRequest, localeForPathname, openSession, sealSession, sessionCookieOptions, splitCmssyLocale };
+/**
+ * Verify + parse an inbound cmssy webhook (CMS-693 / CMS-694).
+ *
+ * cmssy signs each delivery with HMAC-SHA256 over `${timestamp}.${body}`
+ * and sends the result in the `X-Cmssy-Signature: t=<ms>,v1=<hex>`
+ * header, plus a unique `X-Cmssy-Webhook-Id`. This helper recomputes the
+ * signature (timing-safe compare), rejects stale timestamps to bound
+ * replay, and returns the typed event.
+ *
+ * IMPORTANT: pass the RAW request body string (e.g. `await req.text()`),
+ * never a re-serialized object - the signed bytes must match exactly.
+ */
+/** Serialized order carried in an order.* webhook (mirrors the backend). */
+interface CmssyWebhookOrder {
+    id: string;
+    workspaceId: string;
+    displayStatus: string;
+    paymentStatus: string;
+    fulfillmentStatus: string;
+    total: number;
+    currency: string;
+    customerId: string | null;
+    customerEmail: string;
+    paymentProvider: string | null;
+    paymentReference: string | null;
+    refundedAmount: number;
+    createdAt: string;
+    updatedAt: string;
+}
+interface CmssyWebhookEvent {
+    /** Delivery id - also sent in X-Cmssy-Webhook-Id; dedup on it. */
+    id: string;
+    /** e.g. "order.paid", "order.refunded". */
+    event: string;
+    createdAt: string;
+    data: {
+        workspaceId: string;
+        order: CmssyWebhookOrder;
+    };
+}
+interface VerifyCmssyWebhookOptions {
+    /** Raw request body string (NOT parsed JSON). */
+    body: string;
+    /** The `X-Cmssy-Signature` header value, or null if absent. */
+    signatureHeader: string | null;
+    /** The endpoint's signing secret. */
+    secret: string;
+    /** Max age of the signed timestamp, in seconds. Default 300 (5 min). */
+    toleranceSeconds?: number;
+    /** Override the current time (ms) - for tests. */
+    now?: number;
+}
+declare class CmssyWebhookError extends Error {
+    constructor(message: string);
+}
+/**
+ * Verify the signature + freshness and return the parsed event. Throws
+ * `CmssyWebhookError` on any failure (missing/malformed header, bad
+ * signature, stale timestamp, invalid JSON) - catch it and respond 400.
+ */
+declare function verifyCmssyWebhook(options: VerifyCmssyWebhookOptions): CmssyWebhookEvent;
+
+export { CMSSY_CART_COOKIE, CMSSY_EDIT_HEADER, CMSSY_LOCALE_HEADER, CMSSY_SESSION_COOKIE, type CmssyAuthConfig, type CmssyAuthMiddleware, type CmssyAuthRouteHandlers, type CmssyCartRouteHandlers, type CmssyCspOptions, type CmssyDraftRouteConfig, type CmssyEditorProps, type CmssyNextConfig, type CmssyOrdersRouteHandlers, type CmssySessionPayload, type CmssySessionUser, CmssyWebhookError, type CmssyWebhookEvent, type CmssyWebhookOrder, type CreateCmssyPageOptions, type FetchProductOptions, type FetchProductsOptions, type MyOrdersResult, SESSION_MAX_AGE_SECONDS, type SessionCookieOptions, type VerifyCmssyWebhookOptions, applyCmssyCsp, assertAuthConfig, cmssyCspHeaders, createCmssyAuthMiddleware, createCmssyAuthRoute, createCmssyCartRoute, createCmssyOrdersRoute, createCmssyPage, createDraftRoute, fetchProduct, fetchProducts, getCmssyAccessToken, getCmssyLocale, getCmssyUser, isAccessExpired, isCmssyEditMode, isCmssyEditRequest, localeForPathname, openSession, sealSession, sessionCookieOptions, splitCmssyLocale, verifyCmssyWebhook };

package/dist/index.js

@@ -2,7 +2,7 @@ import { draftMode, headers, cookies } from 'next/headers';
 import { notFound, redirect } from 'next/navigation';
 import { resolveSiteLocales, splitLocaleFromPath, fetchPage, resolveForms, CmssyServerPage, resolveWorkspaceId, graphqlRequest } from '@cmssy/react';
 import { jsx } from 'react/jsx-runtime';
-import { createHash, timingSafeEqual } from 'crypto';
+import { createHmac, createHash, timingSafeEqual } from 'crypto';
 import { EncryptJWT, jwtDecrypt } from 'jose';
 import { NextResponse } from 'next/server';
 
@@ -1229,5 +1229,60 @@ function createCmssyOrdersRoute(config) {
     }
   };
 }
+var CmssyWebhookError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "CmssyWebhookError";
+  }
+};
+var DEFAULT_TOLERANCE_SECONDS = 300;
+function parseSignatureHeader(header) {
+  let timestamp = null;
+  let signature = null;
+  for (const part of header.split(",")) {
+    const idx = part.indexOf("=");
+    if (idx === -1) continue;
+    const key = part.slice(0, idx).trim();
+    const value = part.slice(idx + 1).trim();
+    if (key === "t") timestamp = Number(value);
+    else if (key === "v1") signature = value;
+  }
+  if (timestamp === null || !Number.isFinite(timestamp) || !signature) {
+    throw new CmssyWebhookError("Malformed X-Cmssy-Signature header");
+  }
+  return { timestamp, signature };
+}
+function timingSafeHexEqual(expectedHex, providedHex) {
+  const expected = Buffer.from(expectedHex, "hex");
+  const provided = Buffer.from(providedHex, "hex");
+  if (expected.length !== provided.length) return false;
+  return timingSafeEqual(expected, provided);
+}
+function verifyCmssyWebhook(options) {
+  const { body, signatureHeader, secret } = options;
+  if (!signatureHeader) {
+    throw new CmssyWebhookError("Missing X-Cmssy-Signature header");
+  }
+  if (!secret) {
+    throw new CmssyWebhookError("Missing webhook secret");
+  }
+  const { timestamp, signature } = parseSignatureHeader(signatureHeader);
+  const toleranceMs = (options.toleranceSeconds ?? DEFAULT_TOLERANCE_SECONDS) * 1e3;
+  const now = options.now ?? Date.now();
+  if (Math.abs(now - timestamp) > toleranceMs) {
+    throw new CmssyWebhookError("Webhook timestamp outside tolerance");
+  }
+  const expected = createHmac("sha256", secret).update(`${timestamp}.${body}`).digest("hex");
+  if (!timingSafeHexEqual(expected, signature)) {
+    throw new CmssyWebhookError("Webhook signature mismatch");
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(body);
+  } catch {
+    throw new CmssyWebhookError("Webhook body is not valid JSON");
+  }
+  return parsed;
+}
 
-export { CMSSY_CART_COOKIE, CMSSY_EDIT_HEADER, CMSSY_LOCALE_HEADER, CMSSY_SESSION_COOKIE, SESSION_MAX_AGE_SECONDS, applyCmssyCsp, assertAuthConfig, cmssyCspHeaders, createCmssyAuthMiddleware, createCmssyAuthRoute, createCmssyCartRoute, createCmssyOrdersRoute, createCmssyPage, createDraftRoute, fetchProduct, fetchProducts, getCmssyAccessToken, getCmssyLocale, getCmssyUser, isAccessExpired, isCmssyEditMode, isCmssyEditRequest, localeForPathname, openSession, sealSession, sessionCookieOptions, splitCmssyLocale };
+export { CMSSY_CART_COOKIE, CMSSY_EDIT_HEADER, CMSSY_LOCALE_HEADER, CMSSY_SESSION_COOKIE, CmssyWebhookError, SESSION_MAX_AGE_SECONDS, applyCmssyCsp, assertAuthConfig, cmssyCspHeaders, createCmssyAuthMiddleware, createCmssyAuthRoute, createCmssyCartRoute, createCmssyOrdersRoute, createCmssyPage, createDraftRoute, fetchProduct, fetchProducts, getCmssyAccessToken, getCmssyLocale, getCmssyUser, isAccessExpired, isCmssyEditMode, isCmssyEditRequest, localeForPathname, openSession, sealSession, sessionCookieOptions, splitCmssyLocale, verifyCmssyWebhook };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cmssy/next",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "Next.js App Router bindings for cmssy headless sites (createCmssyPage + draft preview)",
   "keywords": [
     "cmssy",
@@ -36,7 +36,7 @@
     "dist"
   ],
   "peerDependencies": {
-    "@cmssy/react": "^0.2.3",
+    "@cmssy/react": "^0.2.4",
     "next": ">=15",
     "react": "^18.2.0 || ^19.0.0",
     "react-dom": "^18.2.0 || ^19.0.0"
@@ -49,7 +49,7 @@
     "tsup": "^8.3.0",
     "typescript": "^5.6.0",
     "vitest": "^2.1.0",
-    "@cmssy/react": "0.2.3"
+    "@cmssy/react": "0.2.4"
   },
   "dependencies": {
     "jose": "^6.2.3"