@pandait.tech/payment-nuvei 0.4.1 → 0.5.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:

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;