@pandait.tech/payment-nuvei 0.4.0 → 0.5.0

package/dist/handlers/index.d.cts

@@ -177,6 +177,19 @@ interface NuveiWebhookPayload {
 interface WebhookHandlerDeps {
     firebase: FirebaseDeps;
     email: Pick<EmailService, "sendPaymentConfirmation" | "sendPaymentPending">;
+    /**
+     * Shared secret used to authenticate the incoming webhook. Paymentez/Nuvei
+     * DMNs are NOT signed, so the only robust auth is a secret the merchant
+     * embeds in the DMN URL configured in the Nuvei dashboard, e.g.
+     * `https://shop.com/api/webhooks/nuvei?key=THE_SECRET` (also accepted as the
+     * `x-webhook-key` header). Falls back to `process.env.NUVEI_WEBHOOK_SECRET`.
+     *
+     * If set, requests without a matching key are rejected with 401. If unset,
+     * the handler logs a loud warning and processes anyway (the endpoint is then
+     * forgeable — anyone who knows an orderId could fake a "paid" notification).
+     * STRONGLY RECOMMENDED in production.
+     */
+    webhookSecret?: string;
     /** Optional post-success hook. Fires when the webhook transitions an order to "paid" (either via direct status_detail=3 or via verify BY_CRES). Used for enrollment, fulfillment triggers, paymentLink usage tracking, etc. */
     onPaymentSucceeded?: (order: MinimalOrder & {
         id: string;

package/dist/handlers/index.d.ts

@@ -177,6 +177,19 @@ interface NuveiWebhookPayload {
 interface WebhookHandlerDeps {
     firebase: FirebaseDeps;
     email: Pick<EmailService, "sendPaymentConfirmation" | "sendPaymentPending">;
+    /**
+     * Shared secret used to authenticate the incoming webhook. Paymentez/Nuvei
+     * DMNs are NOT signed, so the only robust auth is a secret the merchant
+     * embeds in the DMN URL configured in the Nuvei dashboard, e.g.
+     * `https://shop.com/api/webhooks/nuvei?key=THE_SECRET` (also accepted as the
+     * `x-webhook-key` header). Falls back to `process.env.NUVEI_WEBHOOK_SECRET`.
+     *
+     * If set, requests without a matching key are rejected with 401. If unset,
+     * the handler logs a loud warning and processes anyway (the endpoint is then
+     * forgeable — anyone who knows an orderId could fake a "paid" notification).
+     * STRONGLY RECOMMENDED in production.
+     */
+    webhookSecret?: string;
     /** Optional post-success hook. Fires when the webhook transitions an order to "paid" (either via direct status_detail=3 or via verify BY_CRES). Used for enrollment, fulfillment triggers, paymentLink usage tracking, etc. */
     onPaymentSucceeded?: (order: MinimalOrder & {
         id: string;

package/dist/handlers/index.js

@@ -1,5 +1,5 @@
-import { FieldValue } from 'firebase-admin/firestore';
 import crypto from 'crypto';
+import { FieldValue } from 'firebase-admin/firestore';
 import { z } from 'zod';
 
 // src/http.ts
@@ -10,6 +10,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.timingSafeEqual(ab, ab);
+    return false;
+  }
+  return crypto.timingSafeEqual(ab, bb);
+}
 function getCookie(request, name) {
   const header = request.headers.get("cookie");
   if (!header) return void 0;
@@ -688,8 +697,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;