@pandait.tech/payment-nuvei 0.4.1 → 1.0.0

package/README.md

@@ -110,6 +110,33 @@ export const POST = createChargeHandler({
 
 Apply the same pattern to the remaining handlers — each one is documented inline with its own `XHandlerDeps` interface.
 
+### Securing the webhook (important)
+
+Paymentez/Nuvei DMNs (webhooks) are **not signed**, so the webhook endpoint must be protected with a shared secret — otherwise anyone who knows an `orderId` could POST a fake "paid" notification.
+
+1. Set a secret and pass it to the handler (or via `NUVEI_WEBHOOK_SECRET`):
+
+   ```ts
+   export const POST = createWebhookHandler({
+     firebase: { db: dbAdmin, auth: authAdmin },
+     email: { sendPaymentConfirmation, sendPaymentPending },
+     webhookSecret: process.env.NUVEI_WEBHOOK_SECRET,
+     onPaymentSucceeded: async (order) => { /* enrollment, fulfillment, ... */ },
+   });
+   ```
+
+2. In the **Nuvei dashboard**, configure your DMN/callback URL with the secret as a query param:
+
+   ```
+   https://your-shop.com/api/webhooks/nuvei?key=YOUR_SECRET
+   ```
+
+   (The secret is also accepted as the `x-webhook-key` header.)
+
+Requests without a matching key get `401` and are not processed (constant-time compared). If `webhookSecret` is **unset**, the handler still processes but logs a loud warning — treat that as not-production-ready.
+
+> `onPaymentSucceeded` fires once, on the transition into `paid` (idempotent across Nuvei's webhook retries).
+
 ## Hosting & deployment (3DS callback + Nuvei egress)
 
 This package is **hosting-agnostic by design** — the payment logic doesn't care where it runs. But two parts of the Nuvei flow may need to run *outside your app's request edge* depending on **where you host**, because of how the host's infrastructure (not this package) handles certain traffic:
@@ -285,7 +312,22 @@ The handlers read/write a single `orders` collection (plus `promotions` for coup
 
 Public, supported entry points: the package root (SDK), `./handlers`, `./adapters`, `./payment-links`, `./ui`, and `./ui/styles.css`. Everything else (e.g. internal `http.ts`) is private and may change without notice.
 
-Pre-1.0 the package follows semver with the caveat that **minor versions may make small breaking changes to handler `*HandlerDeps` interfaces** as the design settles. From **1.0.0** onward the public API is frozen under semver. See `CHANGELOG.md`.
+**As of `1.0.0` the public API is frozen under semver** — breaking changes to the
+exported factories, their `*HandlerDeps` interfaces, the SDK functions, or the UI
+component props require a major version bump. See `CHANGELOG.md`.
+
+Design notes consumers should know:
+
+- **Order shape is generic.** `MinimalOrder` extends `Record<string, unknown>` and
+  declares only fields the package itself reads/writes. Your business-specific
+  order fields are yours to read off the order inside your callbacks
+  (`onPaymentSucceeded`, `validateCustomOrder`, `getRetryUrl`) — narrow them there.
+- **Payment links are primitives only.** The package ships token/expiry/price-bound
+  helpers; the payment-link *document shape* (what it points to) is yours to define.
+- **The webhook secret is optional but strongly recommended.** It's left optional so
+  the package never forces a specific webhook-URL scheme, but an unconfigured
+  webhook is forgeable — always set `webhookSecret` in production (see "Securing the
+  webhook" above).
 
 ## Migration from `pauhenriques-website`
 

package/dist/handlers/index.cjs

@@ -1,7 +1,7 @@
 'use strict';
 
-var firestore = require('firebase-admin/firestore');
 var crypto = require('crypto');
+var firestore = require('firebase-admin/firestore');
 var zod = require('zod');
 
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
@@ -16,6 +16,15 @@ function json(data, init) {
   }
   return new Response(JSON.stringify(data), { ...init, headers });
 }
+function timingSafeEqualStr(a, b) {
+  const ab = Buffer.from(a, "utf8");
+  const bb = Buffer.from(b, "utf8");
+  if (ab.length !== bb.length) {
+    crypto__default.default.timingSafeEqual(ab, ab);
+    return false;
+  }
+  return crypto__default.default.timingSafeEqual(ab, bb);
+}
 function getCookie(request, name) {
   const header = request.headers.get("cookie");
   if (!header) return void 0;
@@ -694,8 +703,20 @@ function extractCres(payload) {
 function createWebhookHandler(deps) {
   const logger = deps.logger ?? console;
   const { db } = deps.firebase;
+  const expectedSecret = deps.webhookSecret ?? process.env.NUVEI_WEBHOOK_SECRET;
   return async function POST(request) {
     try {
+      if (expectedSecret) {
+        const provided = new URL(request.url).searchParams.get("key") ?? request.headers.get("x-webhook-key") ?? "";
+        if (!timingSafeEqualStr(provided, expectedSecret)) {
+          logger.warn("[webhook] rejected: missing/invalid webhook secret");
+          return json({ error: "Unauthorized" }, { status: 401 });
+        }
+      } else {
+        logger.warn(
+          "[webhook] NUVEI_WEBHOOK_SECRET is not configured \u2014 this endpoint is UNAUTHENTICATED and forgeable. Set a secret (deps.webhookSecret or env) and append it to your DMN URL as ?key=... before going to production."
+        );
+      }
       const payload = await request.json();
       logger.log("[webhook] Full payload:", JSON.stringify(payload));
       const { transaction } = payload;