@textbee/sdk 0.4.0 → 0.5.0

package/README.md

@@ -116,25 +116,50 @@ const { batch, messages } = await textbee.getSmsBatch(deviceId, smsBatchId)
 
 ## Verifying webhooks
 
-textbee signs each webhook delivery with HMAC-SHA256 and sends the hex digest in the `X-Signature` header. Pass the raw request body, not a re-serialized object, whenever your framework gives you access to it.
+textbee signs each webhook delivery with your signing secret and sends a timestamped signature in the `X-Textbee-Signature` header:
+
+```
+X-Textbee-Signature: t=1762300000,v1=5f2b...
+```
+
+`v1` is the hex HMAC-SHA256 of `<t>.<raw body>`. `verifyWebhookRequest` reads the signature header, checks `v1` against the raw body in constant time, and rejects the request when `t` is more than 300 seconds from now. The signed timestamp makes a captured delivery useless after that window.
+
+Verify the raw body exactly as received. A parsed and re-serialized body can differ by one byte and fail.
 
 ```js
-import { verifyWebhookSignature } from '@textbee/sdk'
+import express from 'express'
+import { verifyWebhookRequest } from '@textbee/sdk'
+
+const app = express()
 
 app.post('/webhooks/textbee', express.raw({ type: 'application/json' }), async (req, res) => {
-  const valid = await verifyWebhookSignature({
-    payload: req.body.toString('utf8'),
-    signature: req.get('x-signature'),
+  const valid = await verifyWebhookRequest({
+    payload: req.body, // a Buffer, from express.raw
+    headers: req.headers,
     signingSecret: process.env.TEXTBEE_WEBHOOK_SECRET,
   })
 
   if (!valid) return res.sendStatus(401)
 
   const event = JSON.parse(req.body.toString('utf8'))
+  // Retries carry the same idempotencyKey. Skip keys you have already handled.
   res.sendStatus(200)
 })
 ```
 
+`payload` takes a string or bytes (`Buffer`, `Uint8Array`). `headers` takes Node's `req.headers`, a plain object, or a Fetch `Headers` object, and header names match in any case.
+
+Options:
+
+- `toleranceSeconds`: the largest allowed distance between `t` and now, in either direction. Defaults to `300`. Keep your server clock in sync (NTP).
+- `allowLegacy`: an explicit opt-in for old receivers. Off by default. When it is `true` and the signature header is absent, the request is checked against `X-Signature` instead, which has no replay protection.
+
+To check the signature header value yourself, call `verifyTimestampedWebhookSignature({ payload, signatureHeader, signingSecret })`. It takes the same `toleranceSeconds` option.
+
+Retries and duplicates: a failed delivery is retried with a fresh `t`, so each attempt passes the freshness check. Every payload carries an `idempotencyKey`. Store the keys you have processed and skip repeats.
+
+**Deprecated:** `verifyWebhookSignature` checks only `X-Signature`. It still works because textbee still sends that header, but it has no replay protection. See [textbee.dev/docs/webhooks](https://textbee.dev/docs/webhooks) for the upgrade steps.
+
 ## SMS utilities
 
 Pure helpers for working with SMS text and phone numbers. No API key, no network calls, and they are useful with any SMS provider, not just textbee. Import only what you need and the rest is tree-shaken away.

package/dist/index.cjs

@@ -28,6 +28,8 @@ __export(index_exports, {
   isValidE164: () => isValidE164,
   normalizePhoneNumber: () => normalizePhoneNumber,
   sanitizeForGsm7: () => sanitizeForGsm7,
+  verifyTimestampedWebhookSignature: () => verifyTimestampedWebhookSignature,
+  verifyWebhookRequest: () => verifyWebhookRequest,
   verifyWebhookSignature: () => verifyWebhookSignature
 });
 module.exports = __toCommonJS(index_exports);
@@ -48,7 +50,7 @@ var TextbeeError = class extends Error {
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.textbee.dev/api/v1";
-var CLIENT_ID = `textbee-js/${"0.4.0"}`;
+var CLIENT_ID = `textbee-js/${"0.5.0"}`;
 var Textbee = class {
   #apiKey;
   #baseUrl;
@@ -483,17 +485,115 @@ function normalizeCountryCode(value) {
 }
 
 // src/webhooks.ts
+var DEFAULT_TOLERANCE_SECONDS = 300;
+var encoder = new TextEncoder();
 async function verifyWebhookSignature(options) {
   const { payload, signature, signingSecret } = options;
   if (!signature || !signingSecret) {
     return false;
   }
   const body = typeof payload === "string" ? payload : JSON.stringify(payload);
-  const expected = await hmacSha256Hex(signingSecret, body);
+  const expected = await hmacSha256Hex(signingSecret, encoder.encode(body));
   return constantTimeEqual(expected, signature.toLowerCase());
 }
+async function verifyTimestampedWebhookSignature(options) {
+  const {
+    payload,
+    signatureHeader,
+    signingSecret,
+    toleranceSeconds = DEFAULT_TOLERANCE_SECONDS,
+    now = Math.floor(Date.now() / 1e3)
+  } = options;
+  const body = toBytes(payload);
+  if (!signatureHeader || !signingSecret || !body) {
+    return false;
+  }
+  const parsed = parseSignatureHeader(signatureHeader);
+  if (!parsed) {
+    return false;
+  }
+  if (!(Math.abs(now - Number(parsed.timestamp)) <= toleranceSeconds)) {
+    return false;
+  }
+  const prefix = encoder.encode(`${parsed.timestamp}.`);
+  const signed = new Uint8Array(prefix.length + body.length);
+  signed.set(prefix);
+  signed.set(body, prefix.length);
+  const expected = await hmacSha256Hex(signingSecret, signed);
+  let matched = false;
+  for (const candidate of parsed.signatures) {
+    if (constantTimeEqual(expected, candidate.toLowerCase())) {
+      matched = true;
+    }
+  }
+  return matched;
+}
+async function verifyWebhookRequest(options) {
+  const { payload, headers, signingSecret, toleranceSeconds, now, allowLegacy = false } = options;
+  const signatureHeader = getHeader(headers, "x-textbee-signature");
+  if (signatureHeader !== void 0) {
+    return verifyTimestampedWebhookSignature({
+      payload,
+      signatureHeader,
+      signingSecret,
+      toleranceSeconds,
+      now
+    });
+  }
+  if (!allowLegacy) {
+    return false;
+  }
+  const legacySignature = getHeader(headers, "x-signature");
+  const body = toBytes(payload);
+  if (!legacySignature || !signingSecret || !body) {
+    return false;
+  }
+  const expected = await hmacSha256Hex(signingSecret, body);
+  return constantTimeEqual(expected, legacySignature.toLowerCase());
+}
+function parseSignatureHeader(header) {
+  let timestamp;
+  const signatures = [];
+  for (const part of header.split(",")) {
+    const separator = part.indexOf("=");
+    if (separator === -1) {
+      continue;
+    }
+    const key = part.slice(0, separator).trim();
+    const value = part.slice(separator + 1).trim();
+    if (key === "t") {
+      if (timestamp !== void 0 || !/^\d+$/.test(value)) {
+        return null;
+      }
+      timestamp = value;
+    } else if (key === "v1" && value) {
+      signatures.push(value);
+    }
+  }
+  if (timestamp === void 0 || signatures.length === 0) {
+    return null;
+  }
+  return { timestamp, signatures };
+}
+function getHeader(headers, name) {
+  if (typeof headers.get === "function") {
+    return headers.get(name) ?? void 0;
+  }
+  const values = [];
+  for (const [key, value] of Object.entries(headers)) {
+    if (key.toLowerCase() === name && value !== void 0) {
+      values.push(...Array.isArray(value) ? value : [value]);
+    }
+  }
+  return values.length > 0 ? values.join(",") : void 0;
+}
+function toBytes(payload) {
+  if (typeof payload === "string") {
+    return encoder.encode(payload);
+  }
+  return payload instanceof Uint8Array ? payload : void 0;
+}
 async function hmacSha256Hex(secret, message) {
-  const encoder = new TextEncoder();
   const key = await crypto.subtle.importKey(
     "raw",
     encoder.encode(secret),
@@ -501,7 +601,7 @@ async function hmacSha256Hex(secret, message) {
     false,
     ["sign"]
   );
-  const digest = await crypto.subtle.sign("HMAC", key, encoder.encode(message));
+  const digest = await crypto.subtle.sign("HMAC", key, new Uint8Array(message));
   return Array.from(new Uint8Array(digest)).map((byte) => byte.toString(16).padStart(2, "0")).join("");
 }
 function constantTimeEqual(a, b) {
@@ -524,5 +624,7 @@ function constantTimeEqual(a, b) {
   isValidE164,
   normalizePhoneNumber,
   sanitizeForGsm7,
+  verifyTimestampedWebhookSignature,
+  verifyWebhookRequest,
   verifyWebhookSignature
 });

package/dist/index.d.cts

@@ -411,12 +411,67 @@ interface VerifyWebhookSignatureOptions {
     /** Signing secret shown with the webhook subscription in the dashboard. */
     signingSecret: string;
 }
+interface VerifyTimestampedWebhookSignatureOptions {
+    /** The raw request body, exactly as received. Do not parse and re-serialize it. */
+    payload: string | Uint8Array;
+    /** Value of the `X-Textbee-Signature` request header: `t=<unix seconds>,v1=<hex>`. */
+    signatureHeader: string | null | undefined;
+    /** Signing secret shown with the webhook subscription in the dashboard. */
+    signingSecret: string;
+    /** Maximum difference, in seconds, between the signed timestamp and now. Defaults to 300. */
+    toleranceSeconds?: number;
+    /** Current time in unix seconds. Defaults to the system clock. */
+    now?: number;
+}
+/** Request headers as a Fetch `Headers` object or a plain object such as Node's `req.headers`. */
+type WebhookRequestHeaders = {
+    get(name: string): string | null;
+} | Record<string, string | string[] | undefined>;
+interface VerifyWebhookRequestOptions {
+    /** The raw request body, exactly as received. Do not parse and re-serialize it. */
+    payload: string | Uint8Array;
+    /** The request headers. Names are matched case-insensitively. */
+    headers: WebhookRequestHeaders;
+    /** Signing secret shown with the webhook subscription in the dashboard. */
+    signingSecret: string;
+    /** Maximum difference, in seconds, between the signed timestamp and now. Defaults to 300. */
+    toleranceSeconds?: number;
+    /** Current time in unix seconds. Defaults to the system clock. */
+    now?: number;
+    /**
+     * Accept the `X-Signature` header when `X-Textbee-Signature` is absent.
+     * Off by default, because `X-Signature` has no replay protection. Turn it on
+     * only for old receivers that cannot read the signature header yet.
+     */
+    allowLegacy?: boolean;
+}
 /**
- * Check that a webhook really came from textbee.
+ * Check that a webhook really came from textbee, using the `X-Signature` header.
  *
  * textbee signs deliveries with HMAC-SHA256 over the request body and sends the
  * hex digest in the `X-Signature` header. Comparison is constant time.
+ *
+ * @deprecated This header has no timestamp, so a captured delivery can be
+ * replayed. textbee still sends it, so this keeps working. Use
+ * {@link verifyWebhookRequest} or {@link verifyTimestampedWebhookSignature}.
  */
 declare function verifyWebhookSignature(options: VerifyWebhookSignatureOptions): Promise<boolean>;
+/**
+ * Check the timestamped signature in the `X-Textbee-Signature` header.
+ *
+ * The header is `t=<unix seconds>,v1=<hex>`, where the hex value is
+ * HMAC-SHA256 over `<t>.<raw body>`. Any matching `v1` entry passes. Returns
+ * false when the header is malformed, no `v1` entry matches, or `t` is more
+ * than `toleranceSeconds` away from now in either direction.
+ */
+declare function verifyTimestampedWebhookSignature(options: VerifyTimestampedWebhookSignatureOptions): Promise<boolean>;
+/**
+ * Check that a webhook request came from textbee, from its headers.
+ *
+ * Verifies the timestamped signature in `X-Textbee-Signature`. When that
+ * header is absent and `allowLegacy` is true, falls back to `X-Signature`,
+ * which has no replay protection.
+ */
+declare function verifyWebhookRequest(options: VerifyWebhookRequestOptions): Promise<boolean>;
 
-export { type Device, type IterateMessagesOptions, type ListMessagesOptions, type Message, type MessageDevice, type MessageIssueEntry, type MessageIssueSource, type MessageList, type MessageListMeta, type NormalizePhoneNumberOptions, type SanitizeForGsm7Options, type SendSmsImmediateResponse, type SendSmsQueuedResponse, type SendSmsRequest, type SendSmsResponse, type SendSmsWarning, type Sms, type SmsBatch, type SmsBatchResult, type SmsEncoding, type SmsSegmentInfo, Textbee, TextbeeError, type TextbeeOptions, type VerifyWebhookSignatureOptions, type WebhookEvent, countSmsSegments, findNonGsm7Characters, getSmsEncoding, isValidE164, normalizePhoneNumber, sanitizeForGsm7, verifyWebhookSignature };
+export { type Device, type IterateMessagesOptions, type ListMessagesOptions, type Message, type MessageDevice, type MessageIssueEntry, type MessageIssueSource, type MessageList, type MessageListMeta, type NormalizePhoneNumberOptions, type SanitizeForGsm7Options, type SendSmsImmediateResponse, type SendSmsQueuedResponse, type SendSmsRequest, type SendSmsResponse, type SendSmsWarning, type Sms, type SmsBatch, type SmsBatchResult, type SmsEncoding, type SmsSegmentInfo, Textbee, TextbeeError, type TextbeeOptions, type VerifyTimestampedWebhookSignatureOptions, type VerifyWebhookRequestOptions, type VerifyWebhookSignatureOptions, type WebhookEvent, type WebhookRequestHeaders, countSmsSegments, findNonGsm7Characters, getSmsEncoding, isValidE164, normalizePhoneNumber, sanitizeForGsm7, verifyTimestampedWebhookSignature, verifyWebhookRequest, verifyWebhookSignature };

package/dist/index.d.ts

@@ -411,12 +411,67 @@ interface VerifyWebhookSignatureOptions {
     /** Signing secret shown with the webhook subscription in the dashboard. */
     signingSecret: string;
 }
+interface VerifyTimestampedWebhookSignatureOptions {
+    /** The raw request body, exactly as received. Do not parse and re-serialize it. */
+    payload: string | Uint8Array;
+    /** Value of the `X-Textbee-Signature` request header: `t=<unix seconds>,v1=<hex>`. */
+    signatureHeader: string | null | undefined;
+    /** Signing secret shown with the webhook subscription in the dashboard. */
+    signingSecret: string;
+    /** Maximum difference, in seconds, between the signed timestamp and now. Defaults to 300. */
+    toleranceSeconds?: number;
+    /** Current time in unix seconds. Defaults to the system clock. */
+    now?: number;
+}
+/** Request headers as a Fetch `Headers` object or a plain object such as Node's `req.headers`. */
+type WebhookRequestHeaders = {
+    get(name: string): string | null;
+} | Record<string, string | string[] | undefined>;
+interface VerifyWebhookRequestOptions {
+    /** The raw request body, exactly as received. Do not parse and re-serialize it. */
+    payload: string | Uint8Array;
+    /** The request headers. Names are matched case-insensitively. */
+    headers: WebhookRequestHeaders;
+    /** Signing secret shown with the webhook subscription in the dashboard. */
+    signingSecret: string;
+    /** Maximum difference, in seconds, between the signed timestamp and now. Defaults to 300. */
+    toleranceSeconds?: number;
+    /** Current time in unix seconds. Defaults to the system clock. */
+    now?: number;
+    /**
+     * Accept the `X-Signature` header when `X-Textbee-Signature` is absent.
+     * Off by default, because `X-Signature` has no replay protection. Turn it on
+     * only for old receivers that cannot read the signature header yet.
+     */
+    allowLegacy?: boolean;
+}
 /**
- * Check that a webhook really came from textbee.
+ * Check that a webhook really came from textbee, using the `X-Signature` header.
  *
  * textbee signs deliveries with HMAC-SHA256 over the request body and sends the
  * hex digest in the `X-Signature` header. Comparison is constant time.
+ *
+ * @deprecated This header has no timestamp, so a captured delivery can be
+ * replayed. textbee still sends it, so this keeps working. Use
+ * {@link verifyWebhookRequest} or {@link verifyTimestampedWebhookSignature}.
  */
 declare function verifyWebhookSignature(options: VerifyWebhookSignatureOptions): Promise<boolean>;
+/**
+ * Check the timestamped signature in the `X-Textbee-Signature` header.
+ *
+ * The header is `t=<unix seconds>,v1=<hex>`, where the hex value is
+ * HMAC-SHA256 over `<t>.<raw body>`. Any matching `v1` entry passes. Returns
+ * false when the header is malformed, no `v1` entry matches, or `t` is more
+ * than `toleranceSeconds` away from now in either direction.
+ */
+declare function verifyTimestampedWebhookSignature(options: VerifyTimestampedWebhookSignatureOptions): Promise<boolean>;
+/**
+ * Check that a webhook request came from textbee, from its headers.
+ *
+ * Verifies the timestamped signature in `X-Textbee-Signature`. When that
+ * header is absent and `allowLegacy` is true, falls back to `X-Signature`,
+ * which has no replay protection.
+ */
+declare function verifyWebhookRequest(options: VerifyWebhookRequestOptions): Promise<boolean>;
 
-export { type Device, type IterateMessagesOptions, type ListMessagesOptions, type Message, type MessageDevice, type MessageIssueEntry, type MessageIssueSource, type MessageList, type MessageListMeta, type NormalizePhoneNumberOptions, type SanitizeForGsm7Options, type SendSmsImmediateResponse, type SendSmsQueuedResponse, type SendSmsRequest, type SendSmsResponse, type SendSmsWarning, type Sms, type SmsBatch, type SmsBatchResult, type SmsEncoding, type SmsSegmentInfo, Textbee, TextbeeError, type TextbeeOptions, type VerifyWebhookSignatureOptions, type WebhookEvent, countSmsSegments, findNonGsm7Characters, getSmsEncoding, isValidE164, normalizePhoneNumber, sanitizeForGsm7, verifyWebhookSignature };
+export { type Device, type IterateMessagesOptions, type ListMessagesOptions, type Message, type MessageDevice, type MessageIssueEntry, type MessageIssueSource, type MessageList, type MessageListMeta, type NormalizePhoneNumberOptions, type SanitizeForGsm7Options, type SendSmsImmediateResponse, type SendSmsQueuedResponse, type SendSmsRequest, type SendSmsResponse, type SendSmsWarning, type Sms, type SmsBatch, type SmsBatchResult, type SmsEncoding, type SmsSegmentInfo, Textbee, TextbeeError, type TextbeeOptions, type VerifyTimestampedWebhookSignatureOptions, type VerifyWebhookRequestOptions, type VerifyWebhookSignatureOptions, type WebhookEvent, type WebhookRequestHeaders, countSmsSegments, findNonGsm7Characters, getSmsEncoding, isValidE164, normalizePhoneNumber, sanitizeForGsm7, verifyTimestampedWebhookSignature, verifyWebhookRequest, verifyWebhookSignature };

package/dist/index.js

@@ -14,7 +14,7 @@ var TextbeeError = class extends Error {
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.textbee.dev/api/v1";
-var CLIENT_ID = `textbee-js/${"0.4.0"}`;
+var CLIENT_ID = `textbee-js/${"0.5.0"}`;
 var Textbee = class {
   #apiKey;
   #baseUrl;
@@ -449,17 +449,115 @@ function normalizeCountryCode(value) {
 }
 
 // src/webhooks.ts
+var DEFAULT_TOLERANCE_SECONDS = 300;
+var encoder = new TextEncoder();
 async function verifyWebhookSignature(options) {
   const { payload, signature, signingSecret } = options;
   if (!signature || !signingSecret) {
     return false;
   }
   const body = typeof payload === "string" ? payload : JSON.stringify(payload);
-  const expected = await hmacSha256Hex(signingSecret, body);
+  const expected = await hmacSha256Hex(signingSecret, encoder.encode(body));
   return constantTimeEqual(expected, signature.toLowerCase());
 }
+async function verifyTimestampedWebhookSignature(options) {
+  const {
+    payload,
+    signatureHeader,
+    signingSecret,
+    toleranceSeconds = DEFAULT_TOLERANCE_SECONDS,
+    now = Math.floor(Date.now() / 1e3)
+  } = options;
+  const body = toBytes(payload);
+  if (!signatureHeader || !signingSecret || !body) {
+    return false;
+  }
+  const parsed = parseSignatureHeader(signatureHeader);
+  if (!parsed) {
+    return false;
+  }
+  if (!(Math.abs(now - Number(parsed.timestamp)) <= toleranceSeconds)) {
+    return false;
+  }
+  const prefix = encoder.encode(`${parsed.timestamp}.`);
+  const signed = new Uint8Array(prefix.length + body.length);
+  signed.set(prefix);
+  signed.set(body, prefix.length);
+  const expected = await hmacSha256Hex(signingSecret, signed);
+  let matched = false;
+  for (const candidate of parsed.signatures) {
+    if (constantTimeEqual(expected, candidate.toLowerCase())) {
+      matched = true;
+    }
+  }
+  return matched;
+}
+async function verifyWebhookRequest(options) {
+  const { payload, headers, signingSecret, toleranceSeconds, now, allowLegacy = false } = options;
+  const signatureHeader = getHeader(headers, "x-textbee-signature");
+  if (signatureHeader !== void 0) {
+    return verifyTimestampedWebhookSignature({
+      payload,
+      signatureHeader,
+      signingSecret,
+      toleranceSeconds,
+      now
+    });
+  }
+  if (!allowLegacy) {
+    return false;
+  }
+  const legacySignature = getHeader(headers, "x-signature");
+  const body = toBytes(payload);
+  if (!legacySignature || !signingSecret || !body) {
+    return false;
+  }
+  const expected = await hmacSha256Hex(signingSecret, body);
+  return constantTimeEqual(expected, legacySignature.toLowerCase());
+}
+function parseSignatureHeader(header) {
+  let timestamp;
+  const signatures = [];
+  for (const part of header.split(",")) {
+    const separator = part.indexOf("=");
+    if (separator === -1) {
+      continue;
+    }
+    const key = part.slice(0, separator).trim();
+    const value = part.slice(separator + 1).trim();
+    if (key === "t") {
+      if (timestamp !== void 0 || !/^\d+$/.test(value)) {
+        return null;
+      }
+      timestamp = value;
+    } else if (key === "v1" && value) {
+      signatures.push(value);
+    }
+  }
+  if (timestamp === void 0 || signatures.length === 0) {
+    return null;
+  }
+  return { timestamp, signatures };
+}
+function getHeader(headers, name) {
+  if (typeof headers.get === "function") {
+    return headers.get(name) ?? void 0;
+  }
+  const values = [];
+  for (const [key, value] of Object.entries(headers)) {
+    if (key.toLowerCase() === name && value !== void 0) {
+      values.push(...Array.isArray(value) ? value : [value]);
+    }
+  }
+  return values.length > 0 ? values.join(",") : void 0;
+}
+function toBytes(payload) {
+  if (typeof payload === "string") {
+    return encoder.encode(payload);
+  }
+  return payload instanceof Uint8Array ? payload : void 0;
+}
 async function hmacSha256Hex(secret, message) {
-  const encoder = new TextEncoder();
   const key = await crypto.subtle.importKey(
     "raw",
     encoder.encode(secret),
@@ -467,7 +565,7 @@ async function hmacSha256Hex(secret, message) {
     false,
     ["sign"]
   );
-  const digest = await crypto.subtle.sign("HMAC", key, encoder.encode(message));
+  const digest = await crypto.subtle.sign("HMAC", key, new Uint8Array(message));
   return Array.from(new Uint8Array(digest)).map((byte) => byte.toString(16).padStart(2, "0")).join("");
 }
 function constantTimeEqual(a, b) {
@@ -489,5 +587,7 @@ export {
   isValidE164,
   normalizePhoneNumber,
   sanitizeForGsm7,
+  verifyTimestampedWebhookSignature,
+  verifyWebhookRequest,
   verifyWebhookSignature
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@textbee/sdk",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Official JavaScript SDK for textbee.dev, the open source SMS gateway",
   "license": "MIT",
   "packageManager": "pnpm@9.14.2",