bepago 1.0.0 → 1.1.0

package/README.md

@@ -62,7 +62,9 @@ await bp.payouts.balance();
 ### Verificar un webhook
 
 bePago firma cada webhook con `HMAC-SHA256` sobre `timestamp + body` usando el
-secreto del webhook. Verificá la firma antes de procesar el evento:
+secreto del webhook. `verify` chequea la firma **y la frescura del timestamp**
+(rechaza entregas fuera de ±5 minutos por defecto, configurable) y devuelve el
+evento ya parseado, con su `id`:
 
 ```js
 import BePago from 'bepago';
@@ -70,23 +72,32 @@ import BePago from 'bepago';
 const bp = BePago('sk_live_…');
 
 // En tu handler HTTP (body como string crudo, sin re-serializar):
-const timestamp = req.headers['x-timestamp'];
-const signature = req.headers['x-signature'];
-const rawBody = req.rawBody; // el cuerpo tal cual llegó
-
-const ok = bp.webhooks.verify(
-  'whsec_tu_secreto_de_webhook',
-  timestamp,
-  rawBody,
-  signature,
-);
-
-if (!ok) {
-  return res.status(400).send('firma inválida');
+let evt;
+try {
+  evt = bp.webhooks.verify('whsec_tu_secreto_de_webhook', {
+    id: req.headers['x-bepago-event-id'],
+    timestamp: req.headers['x-webhook-timestamp'],
+    signature: req.headers['x-webhook-signature'],
+    body: req.rawBody, // el cuerpo tal cual llegó, sin re-serializar
+  });
+} catch (e) {
+  return res.status(400).send('webhook inválido'); // firma o timestamp fuera de ventana
 }
 
-const evento = JSON.parse(rawBody);
-// procesar evento.type …
+// Anti-replay: cada evento trae un id ESTABLE entre reintentos. Guardá los ids
+// ya procesados y descartá los duplicados (los reintentos reenvían el mismo id
+// con un timestamp nuevo).
+if (await yaProcesado(evt.id)) return res.status(200).end();
+await marcarProcesado(evt.id);
+
+// procesar evt.event / evt.data …
+res.status(200).end();
+```
+
+Tolerancia configurable (ej. ±10 minutos):
+
+```js
+bp.webhooks.verify(secret, { id, timestamp, signature, body }, { toleranceSeconds: 600 });
 ```
 
 ## Documentación

package/index.mjs

@@ -70,9 +70,37 @@ export default function BePago(secret, opts = {}) {
       balance: () => request('GET', '/v1/balance'),
     },
     webhooks: {
-      verify: (webhookSecret, timestamp, body, signature) => {
-        const expected = createHmac('sha256', webhookSecret).update(timestamp + body, 'utf8').digest('hex');
-        return timingSafeEqual(Buffer.from(expected, 'hex'), Buffer.from(signature, 'hex'));
+      /**
+       * Verifica un webhook de bePago y devuelve el evento parseado.
+       *
+       * Chequea la firma HMAC y la FRESCURA del timestamp: por defecto rechaza
+       * entregas fuera de ±5 minutos (configurable con `toleranceSeconds`). Lanza
+       * si la firma no valida o el timestamp está fuera de la ventana.
+       *
+       * Expone `id` (header X-BePago-Event-Id, estable entre reintentos): guardá
+       * los ids ya procesados para descartar duplicados de forma idempotente.
+       *
+       *   const evt = bp.webhooks.verify(secret, {
+       *     id: req.headers['x-bepago-event-id'],
+       *     timestamp: req.headers['x-webhook-timestamp'],
+       *     signature: req.headers['x-webhook-signature'],
+       *     body: rawBody, // el cuerpo EXACTO recibido, sin reserializar
+       *   });
+       *   if (seen.has(evt.id)) return; // duplicado
+       *   seen.add(evt.id);
+       *
+       * @returns {{ id: string, event: string, livemode: boolean, data: object }}
+       */
+      verify(webhookSecret, { id, timestamp, body, signature }, opts = {}) {
+        const toleranceMs = (opts.toleranceSeconds ?? 300) * 1000;
+        const expected = createHmac('sha256', webhookSecret).update(String(timestamp) + body, 'utf8').digest('hex');
+        const a = Buffer.from(expected, 'hex');
+        const b = Buffer.from(String(signature ?? ''), 'hex');
+        if (a.length !== b.length || !timingSafeEqual(a, b)) throw new Error('bePago webhook: firma inválida');
+        const age = Math.abs(Date.now() - Number(timestamp));
+        if (!Number.isFinite(age) || age > toleranceMs) throw new Error('bePago webhook: timestamp fuera de la ventana permitida');
+        const payload = JSON.parse(body);
+        return { id: id ?? payload.id, event: payload.event, livemode: payload.livemode, data: payload.data };
       },
     },
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bepago",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "SDK oficial de bePago para Node.js (18+, sin dependencias)",
   "type": "module",
   "main": "index.mjs",