@cstar.help/js 0.14.0 → 0.15.0

package/dist/webhook/node.d.ts

@@ -412,11 +412,28 @@ interface WebhookEvent<T extends WebhookEventType = WebhookEventType> {
     data: WebhookEventDataMap[T];
 }
 
+/** Default replay window for Stripe-style signatures: 5 minutes (300s). */
+declare const DEFAULT_TOLERANCE_SECONDS = 300;
+/** Options for signature verification — accepted by both verify and construct calls. */
+interface VerifyOptions {
+    /**
+     * Maximum age (in seconds) of a Stripe-style timestamp before the signature
+     * is rejected as expired. Defaults to {@link DEFAULT_TOLERANCE_SECONDS}.
+     * Ignored for legacy `sha256=<hex>` signatures (which carry no timestamp).
+     */
+    tolerance?: number;
+}
 /** Thrown when webhook signature verification fails. */
 declare class WebhookSignatureVerificationError extends Error {
     constructor(message: string);
 }
 
+/**
+ * Sign a payload in Stripe-style format `t=<unix>,v1=<hex>` (Node-only,
+ * synchronous). Used by the cStar server-side webhook dispatcher and
+ * `cstar listen --forward-to`. The HMAC is computed over `${ts}.${rawBody}`.
+ */
+declare function signPayloadStripe(rawBody: string, secret: string): string;
 /**
  * Verify a webhook signature and parse the event (synchronous, Node.js only).
  *
@@ -427,14 +444,20 @@ declare class WebhookSignatureVerificationError extends Error {
  * @param rawBody - Raw request body as a string (NOT parsed JSON)
  * @param signature - Value of the `X-Signature` header
  * @param secret - Your webhook endpoint's secret (`whsec_*`)
+ * @param options - Optional verifier options (e.g. replay tolerance)
  * @returns Parsed and verified webhook event
  * @throws {WebhookSignatureVerificationError} If verification fails
  */
-declare function constructEvent(rawBody: string, signature: string, secret: string): WebhookEvent;
+declare function constructEvent(rawBody: string, signature: string, secret: string, options?: VerifyOptions): WebhookEvent;
 /**
  * Verify an HMAC-SHA256 signature (synchronous, Node.js only).
- * Uses timing-safe comparison to prevent timing attacks.
+ *
+ * Accepts both the canonical Stripe-style format `t=<unix>,v1=<hex>` (signed
+ * over `${ts}.${rawBody}`, with replay-window enforcement) and the legacy
+ * `sha256=<hex>` format (signed over `rawBody`, no timestamp). Use
+ * `options.tolerance` to override the default 300s replay window. Uses
+ * timing-safe comparison.
  */
-declare function verifySignature(rawBody: string, signature: string, secret: string): boolean;
+declare function verifySignature(rawBody: string, signature: string, secret: string, options?: VerifyOptions): boolean;
 
-export { type WebhookEvent, WebhookSignatureVerificationError, constructEvent, verifySignature };
+export { DEFAULT_TOLERANCE_SECONDS, type VerifyOptions, type WebhookEvent, WebhookSignatureVerificationError, constructEvent, signPayloadStripe, verifySignature };

package/dist/webhook/node.js

@@ -2,6 +2,7 @@
 import { createHmac, timingSafeEqual } from "crypto";
 
 // src/webhook/index.ts
+var DEFAULT_TOLERANCE_SECONDS = 300;
 var WebhookSignatureVerificationError = class extends Error {
   constructor(message) {
     super(message);
@@ -10,21 +11,66 @@ var WebhookSignatureVerificationError = class extends Error {
 };
 
 // src/webhook/node.ts
-function constructEvent(rawBody, signature, secret) {
-  if (!verifySignature(rawBody, signature, secret)) {
+function parseStripeHeader(header) {
+  if (!header || header.startsWith("sha256=")) return null;
+  let timestamp = null;
+  const v1 = [];
+  for (const part of header.split(",")) {
+    const eq = part.indexOf("=");
+    if (eq === -1) continue;
+    const key = part.slice(0, eq).trim();
+    const value = part.slice(eq + 1).trim();
+    if (key === "t") {
+      const parsed = Number.parseInt(value, 10);
+      if (Number.isFinite(parsed)) timestamp = parsed;
+    } else if (key === "v1") {
+      v1.push(value);
+    }
+  }
+  if (timestamp === null || v1.length === 0) return null;
+  return { timestamp, v1 };
+}
+function constantTimeEqualHex(a, b) {
+  if (a.length !== b.length) return false;
+  try {
+    return timingSafeEqual(Buffer.from(a), Buffer.from(b));
+  } catch {
+    return false;
+  }
+}
+function signPayloadStripe(rawBody, secret) {
+  const ts = Math.floor(Date.now() / 1e3);
+  const sig = createHmac("sha256", secret).update(`${ts}.${rawBody}`).digest("hex");
+  return `t=${ts},v1=${sig}`;
+}
+function constructEvent(rawBody, signature, secret, options) {
+  if (!verifySignature(rawBody, signature, secret, options)) {
     throw new WebhookSignatureVerificationError(
       "Webhook signature verification failed. Ensure you are using the raw request body and the correct endpoint secret."
     );
   }
   return JSON.parse(rawBody);
 }
-function verifySignature(rawBody, signature, secret) {
+function verifySignature(rawBody, signature, secret, options) {
+  if (typeof signature !== "string" || signature.length === 0) return false;
+  const stripe = parseStripeHeader(signature);
+  if (stripe) {
+    const tolerance = options?.tolerance ?? DEFAULT_TOLERANCE_SECONDS;
+    const now = Math.floor(Date.now() / 1e3);
+    if (Math.abs(now - stripe.timestamp) > tolerance) return false;
+    const expected2 = createHmac("sha256", secret).update(`${stripe.timestamp}.${rawBody}`).digest("hex");
+    for (const candidate of stripe.v1) {
+      if (constantTimeEqualHex(candidate, expected2)) return true;
+    }
+    return false;
+  }
   const expected = "sha256=" + createHmac("sha256", secret).update(rawBody).digest("hex");
-  if (signature.length !== expected.length) return false;
-  return timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
+  return constantTimeEqualHex(signature, expected);
 }
 export {
+  DEFAULT_TOLERANCE_SECONDS,
   WebhookSignatureVerificationError,
   constructEvent,
+  signPayloadStripe,
   verifySignature
 };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@cstar.help/js",
-	"version": "0.14.0",
+	"version": "0.15.0",
 	"description": "Official TypeScript SDK for the cStar customer support platform",
 	"type": "module",
 	"main": "./dist/index.cjs",