@hostwebhook/node 1.6.2 → 1.6.3

package/README.md

@@ -14,7 +14,7 @@ Requires Node.js 18+.
 
 ## Verify Webhook Signatures
 
-HostWebhook signs every delivery with HMAC-SHA256. Use these helpers to verify authenticity and prevent replay attacks.
+HostWebhook signs every delivery with HMAC-SHA256. Use these helpers to verify authenticity and to reject stale signatures (see [What is signed](#what-is-signed)).
 
 ### Express
 
@@ -86,7 +86,9 @@ try {
 }
 ```
 
-Options: `verify(payload, headers, secret, { maxAgeSec: 300 })` — default 300s (5 min). Set `0` to disable replay protection.
+Options: `verify(payload, headers, secret, { maxAgeSec: 300 })` — default 300s (5 min). Set `0` to disable the age check.
+
+`verify` and the middlewares refuse an empty signing secret (an unset environment variable is the usual cause): with an empty key anyone can compute a valid signature.
 
 ## Send Webhooks
 
@@ -259,6 +261,13 @@ X-HostWebhook-Signature: t=<timestamp_ms>,v1=<hmac_hex>
 
 HMAC computed as: `HMAC-SHA256(secret, "${timestamp}.${rawBody}")`
 
+### What is signed
+
+The signature covers **only the timestamp and the raw body**. In particular:
+
+- The other `X-HostWebhook-*` headers — the event id, the attempt number and every `chain-*` header — are **not signed**. Anyone who can reach your endpoint can add or change them, so use them as hints (for example to deduplicate), never as proof.
+- The timestamp limits how **old** a signature may be (`maxAgeSec`). It does not stop the same signed request from being sent again inside that window: to reject duplicates, remember the event ids you already processed.
+
 ## Support
 
 Found a bug or have a feature request? [Report an issue](https://www.hostwebhook.com/#issues) on our website.

package/dist/index.d.mts

@@ -16,16 +16,28 @@ interface VerifyOptions {
  *
  * The HMAC is computed as: HMAC-SHA256(secret, `${timestamp}.${rawBody}`)
  *
+ * What is signed: ONLY the timestamp and the raw body. The other
+ * `X-HostWebhook-*` headers (event id, attempt, chain-*) are NOT covered by the
+ * signature: anyone who can reach your endpoint can add or change them. Do not
+ * make security decisions from them. And the timestamp only limits how OLD a
+ * signature may be (`maxAgeSec`); it does not stop the same signed request from
+ * being replayed inside that window. To reject duplicates, remember the event
+ * id of what you already processed.
+ *
  * @param payload - The raw request body (string or Buffer)
  * @param headers - The request headers object
  * @param secret  - Your signing secret (e.g. `whsec_...`)
  * @param options - Optional configuration
- * @throws {VerificationError} If the signature is missing, malformed, expired, or invalid
+ * @throws {VerificationError} If the secret is empty, or the signature is missing, malformed, expired, or invalid
  */
 declare function verify(payload: string | Buffer, headers: Record<string, string | string[] | undefined>, secret: string, options?: VerifyOptions): void;
 
 /**
  * Typed representation of HostWebhook delivery headers.
+ *
+ * ⚠️ Only `timestamp` and the body are covered by the signature. The event id,
+ * the attempt number and every `chain*` field come from headers that are NOT
+ * signed: treat them as hints (for example to deduplicate), never as proof.
  */
 interface WebhookHeaders {
     /** Unique event ID (`X-HostWebhook-Event-Id`) */

package/dist/index.d.ts

@@ -16,16 +16,28 @@ interface VerifyOptions {
  *
  * The HMAC is computed as: HMAC-SHA256(secret, `${timestamp}.${rawBody}`)
  *
+ * What is signed: ONLY the timestamp and the raw body. The other
+ * `X-HostWebhook-*` headers (event id, attempt, chain-*) are NOT covered by the
+ * signature: anyone who can reach your endpoint can add or change them. Do not
+ * make security decisions from them. And the timestamp only limits how OLD a
+ * signature may be (`maxAgeSec`); it does not stop the same signed request from
+ * being replayed inside that window. To reject duplicates, remember the event
+ * id of what you already processed.
+ *
  * @param payload - The raw request body (string or Buffer)
  * @param headers - The request headers object
  * @param secret  - Your signing secret (e.g. `whsec_...`)
  * @param options - Optional configuration
- * @throws {VerificationError} If the signature is missing, malformed, expired, or invalid
+ * @throws {VerificationError} If the secret is empty, or the signature is missing, malformed, expired, or invalid
  */
 declare function verify(payload: string | Buffer, headers: Record<string, string | string[] | undefined>, secret: string, options?: VerifyOptions): void;
 
 /**
  * Typed representation of HostWebhook delivery headers.
+ *
+ * ⚠️ Only `timestamp` and the body are covered by the signature. The event id,
+ * the attempt number and every `chain*` field come from headers that are NOT
+ * signed: treat them as hints (for example to deduplicate), never as proof.
  */
 interface WebhookHeaders {
     /** Unique event ID (`X-HostWebhook-Event-Id`) */

package/dist/index.js

@@ -49,7 +49,15 @@ var VerificationError = class extends Error {
     this.name = "VerificationError";
   }
 };
+function exigirUnSecreto(secret) {
+  if (typeof secret !== "string" || secret.trim() === "") {
+    throw new VerificationError(
+      "The signing secret is empty. Set the signing secret of your endpoint (whsec_\u2026) before verifying"
+    );
+  }
+}
 function verify(payload, headers, secret, options) {
+  exigirUnSecreto(secret);
   const sigHeader = getHeader(headers, "x-hostwebhook-signature");
   if (!sigHeader) {
     throw new VerificationError("Missing X-HostWebhook-Signature header");
@@ -159,6 +167,7 @@ function parseHeaders(headers) {
 
 // src/middleware.ts
 function expressMiddleware(secret, options) {
+  exigirUnSecreto(secret);
   return (req, res, next) => {
     try {
       verify(req.body, req.headers, secret, options);
@@ -173,6 +182,7 @@ function expressMiddleware(secret, options) {
   };
 }
 function createNestGuard(secret, options) {
+  exigirUnSecreto(secret);
   return class HostWebhookGuard {
     canActivate(context) {
       const req = context.switchToHttp().getRequest();
@@ -182,6 +192,7 @@ function createNestGuard(secret, options) {
   };
 }
 function fastifyHook(secret, options) {
+  exigirUnSecreto(secret);
   return (req, _reply, done) => {
     try {
       verify(req.body, req.headers, secret, options);
@@ -410,7 +421,7 @@ doSend_fn = async function(token, payload, options) {
   }
   const headers = {
     "Content-Type": options?.contentType ?? "application/json",
-    "User-Agent": `HostWebhook-SDK/${"1.6.2"}`,
+    "User-Agent": `HostWebhook-SDK/${"1.6.3"}`,
     "X-HostWebhook-Sent-At": (/* @__PURE__ */ new Date()).toISOString(),
     ...tz ? { "X-HostWebhook-Timezone": tz } : {},
     ...__privateGet(this, _defaultHeaders),

package/dist/index.mjs

@@ -15,7 +15,15 @@ var VerificationError = class extends Error {
     this.name = "VerificationError";
   }
 };
+function exigirUnSecreto(secret) {
+  if (typeof secret !== "string" || secret.trim() === "") {
+    throw new VerificationError(
+      "The signing secret is empty. Set the signing secret of your endpoint (whsec_\u2026) before verifying"
+    );
+  }
+}
 function verify(payload, headers, secret, options) {
+  exigirUnSecreto(secret);
   const sigHeader = getHeader(headers, "x-hostwebhook-signature");
   if (!sigHeader) {
     throw new VerificationError("Missing X-HostWebhook-Signature header");
@@ -125,6 +133,7 @@ function parseHeaders(headers) {
 
 // src/middleware.ts
 function expressMiddleware(secret, options) {
+  exigirUnSecreto(secret);
   return (req, res, next) => {
     try {
       verify(req.body, req.headers, secret, options);
@@ -139,6 +148,7 @@ function expressMiddleware(secret, options) {
   };
 }
 function createNestGuard(secret, options) {
+  exigirUnSecreto(secret);
   return class HostWebhookGuard {
     canActivate(context) {
       const req = context.switchToHttp().getRequest();
@@ -148,6 +158,7 @@ function createNestGuard(secret, options) {
   };
 }
 function fastifyHook(secret, options) {
+  exigirUnSecreto(secret);
   return (req, _reply, done) => {
     try {
       verify(req.body, req.headers, secret, options);
@@ -376,7 +387,7 @@ doSend_fn = async function(token, payload, options) {
   }
   const headers = {
     "Content-Type": options?.contentType ?? "application/json",
-    "User-Agent": `HostWebhook-SDK/${"1.6.2"}`,
+    "User-Agent": `HostWebhook-SDK/${"1.6.3"}`,
     "X-HostWebhook-Sent-At": (/* @__PURE__ */ new Date()).toISOString(),
     ...tz ? { "X-HostWebhook-Timezone": tz } : {},
     ...__privateGet(this, _defaultHeaders),

package/llms.txt

@@ -80,7 +80,7 @@ try {
 ```
 
 verify(payload, headers, secret, options?) — throws VerificationError if invalid.
-VerifyOptions: { maxAgeSec?: number } — default 300 (5 min). Set 0 to disable replay protection.
+VerifyOptions: { maxAgeSec?: number } — default 300 (5 min). Set 0 to disable the age check. The signature covers only the timestamp and the raw body: the event-id, attempt and chain-* headers are NOT signed, and the timestamp does not stop a replay inside the window (deduplicate by event id). An empty signing secret is refused.
 
 ## Send Webhooks (sending through HostWebhook)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hostwebhook/node",
-  "version": "1.6.2",
+  "version": "1.6.3",
   "description": "Official HostWebhook SDK — verify signatures, parse headers, and send webhooks",
   "main": "dist/index.js",
   "module": "dist/index.mjs",