@cstar.help/js 0.14.0 → 0.15.0

package/dist/quickhelp/index.js

@@ -35,7 +35,7 @@ function normalizeArgs(messageOrStatus, maybeBody, defaults) {
     }
   };
 }
-var CStarError = class extends Error {
+var CStarErrorImpl = class extends Error {
   constructor(messageOrStatus, body) {
     const { statusCode, body: resolved } = normalizeArgs(messageOrStatus, body);
     super(resolved.message);
@@ -48,7 +48,7 @@ var CStarError = class extends Error {
     this.statusCode = statusCode;
   }
 };
-var CStarAuthenticationError = class extends CStarError {
+var CStarAuthenticationErrorImpl = class extends CStarErrorImpl {
   constructor(messageOrStatus, body) {
     const { statusCode, body: resolved } = normalizeArgs(messageOrStatus, body, {
       type: ErrorType.AUTHENTICATION_ERROR,
@@ -59,7 +59,7 @@ var CStarAuthenticationError = class extends CStarError {
     this.name = "CStarAuthenticationError";
   }
 };
-var CStarRateLimitError = class extends CStarError {
+var CStarRateLimitErrorImpl = class extends CStarErrorImpl {
   constructor(messageOrStatus, body, retryAfter) {
     const { statusCode, body: resolved } = normalizeArgs(messageOrStatus, body, {
       type: ErrorType.RATE_LIMIT_ERROR,
@@ -71,7 +71,7 @@ var CStarRateLimitError = class extends CStarError {
     this.retryAfter = retryAfter ?? 60;
   }
 };
-var CStarNotFoundError = class extends CStarError {
+var CStarNotFoundErrorImpl = class extends CStarErrorImpl {
   constructor(messageOrStatus, body) {
     const { statusCode, body: resolved } = normalizeArgs(messageOrStatus, body, {
       type: ErrorType.NOT_FOUND_ERROR,
@@ -82,7 +82,7 @@ var CStarNotFoundError = class extends CStarError {
     this.name = "CStarNotFoundError";
   }
 };
-var CStarValidationError = class extends CStarError {
+var CStarValidationErrorImpl = class extends CStarErrorImpl {
   constructor(messageOrStatus, body) {
     const { statusCode, body: resolved } = normalizeArgs(messageOrStatus, body, {
       type: ErrorType.INVALID_REQUEST_ERROR,
@@ -93,7 +93,7 @@ var CStarValidationError = class extends CStarError {
     this.name = "CStarValidationError";
   }
 };
-var CStarPermissionError = class extends CStarError {
+var CStarPermissionErrorImpl = class extends CStarErrorImpl {
   constructor(messageOrStatus, body) {
     const { statusCode, body: resolved } = normalizeArgs(messageOrStatus, body, {
       type: ErrorType.PERMISSION_ERROR,
@@ -104,7 +104,7 @@ var CStarPermissionError = class extends CStarError {
     this.name = "CStarPermissionError";
   }
 };
-var CStarConflictError = class extends CStarError {
+var CStarConflictErrorImpl = class extends CStarErrorImpl {
   constructor(messageOrStatus, body) {
     const { statusCode, body: resolved } = normalizeArgs(messageOrStatus, body, {
       type: ErrorType.CONFLICT_ERROR,
@@ -115,7 +115,7 @@ var CStarConflictError = class extends CStarError {
     this.name = "CStarConflictError";
   }
 };
-var CStarServerError = class extends CStarError {
+var CStarServerErrorImpl = class extends CStarErrorImpl {
   constructor(messageOrStatus, body) {
     const { statusCode, body: resolved } = normalizeArgs(messageOrStatus, body, {
       type: ErrorType.SERVER_ERROR,
@@ -126,7 +126,7 @@ var CStarServerError = class extends CStarError {
     this.name = "CStarServerError";
   }
 };
-var CStarFeatureDisabledError = class extends CStarError {
+var CStarFeatureDisabledErrorImpl = class extends CStarErrorImpl {
   constructor(messageOrStatus, body) {
     const { statusCode, body: resolved } = normalizeArgs(messageOrStatus, body, {
       type: ErrorType.FEATURE_NOT_CONFIGURED,
@@ -139,6 +139,82 @@ var CStarFeatureDisabledError = class extends CStarError {
     this.enableUrl = resolved.enable_url ?? "";
   }
 };
+var CStarRealtimeUnavailableErrorImpl = class extends CStarErrorImpl {
+  constructor(message) {
+    const resolved = message ?? "EventSource is not available in this environment. Real-time subscriptions only work in the browser. Move the call to a client-only path (`useEffect` / `onMount`), or pass an `eventSource` polyfill via the realtime options. See https://cstar.help/developers/sdk/realtime#ssr";
+    super(0, {
+      type: ErrorType.API_ERROR,
+      code: "realtime_unavailable",
+      message: resolved,
+      doc_url: "https://cstar.help/developers/sdk/realtime#ssr"
+    });
+    this.name = "CStarRealtimeUnavailableError";
+  }
+};
+var REGISTRY_KEY = /* @__PURE__ */ Symbol.for("@cstar.help/js/errors/v1");
+var globalSlot = globalThis;
+var registry = globalSlot[REGISTRY_KEY] ?? (globalSlot[REGISTRY_KEY] = {
+  CStarError: CStarErrorImpl,
+  CStarAuthenticationError: CStarAuthenticationErrorImpl,
+  CStarRateLimitError: CStarRateLimitErrorImpl,
+  CStarNotFoundError: CStarNotFoundErrorImpl,
+  CStarValidationError: CStarValidationErrorImpl,
+  CStarPermissionError: CStarPermissionErrorImpl,
+  CStarConflictError: CStarConflictErrorImpl,
+  CStarServerError: CStarServerErrorImpl,
+  CStarFeatureDisabledError: CStarFeatureDisabledErrorImpl,
+  CStarRealtimeUnavailableError: CStarRealtimeUnavailableErrorImpl
+});
+var CStarError = registry.CStarError;
+var CStarAuthenticationError = registry.CStarAuthenticationError;
+var CStarRateLimitError = registry.CStarRateLimitError;
+var CStarNotFoundError = registry.CStarNotFoundError;
+var CStarValidationError = registry.CStarValidationError;
+var CStarPermissionError = registry.CStarPermissionError;
+var CStarConflictError = registry.CStarConflictError;
+var CStarServerError = registry.CStarServerError;
+var CStarFeatureDisabledError = registry.CStarFeatureDisabledError;
+var CStarRealtimeUnavailableError = registry.CStarRealtimeUnavailableError;
+function parsePublicError(status, body, fallbackMessage) {
+  const obj = body && typeof body === "object" ? body : null;
+  const errVal = obj?.error;
+  let message = fallbackMessage;
+  let structured = null;
+  if (typeof errVal === "string") {
+    message = errVal;
+  } else if (errVal && typeof errVal === "object") {
+    const e = errVal;
+    if (typeof e.message === "string") message = e.message;
+    structured = {
+      type: typeof e.type === "string" ? e.type : ErrorType.API_ERROR,
+      code: typeof e.code === "string" ? e.code : "api_error",
+      message,
+      param: typeof e.param === "string" ? e.param : void 0,
+      doc_url: typeof e.doc_url === "string" ? e.doc_url : DEFAULT_DOC_URL,
+      request_id: typeof e.request_id === "string" ? e.request_id : void 0,
+      feature: typeof e.feature === "string" ? e.feature : void 0,
+      enable_url: typeof e.enable_url === "string" ? e.enable_url : void 0
+    };
+  } else if (typeof obj?.message === "string") {
+    message = obj.message;
+  }
+  const errorBody = structured ?? {
+    type: ErrorType.API_ERROR,
+    code: status >= 500 ? "server_error" : "request_failed",
+    message,
+    doc_url: DEFAULT_DOC_URL
+  };
+  return parseError(status, { error: errorBody });
+}
+var STATUS_TO_CLASS = {
+  400: CStarValidationError,
+  401: CStarAuthenticationError,
+  403: CStarPermissionError,
+  404: CStarNotFoundError,
+  409: CStarConflictError,
+  422: CStarValidationError,
+  429: CStarRateLimitError
+};
 var TYPE_TO_CLASS = {
   [ErrorType.AUTHENTICATION_ERROR]: CStarAuthenticationError,
   [ErrorType.PERMISSION_ERROR]: CStarPermissionError,
@@ -149,6 +225,27 @@ var TYPE_TO_CLASS = {
   [ErrorType.SERVER_ERROR]: CStarServerError,
   [ErrorType.FEATURE_NOT_CONFIGURED]: CStarFeatureDisabledError
 };
+function parseError(statusCode, body, retryAfter) {
+  const errorBody = body?.error ?? {
+    type: ErrorType.API_ERROR,
+    code: "unknown_error",
+    message: `Request failed with status ${statusCode}`,
+    doc_url: DEFAULT_DOC_URL
+  };
+  if (statusCode === 429) {
+    return new CStarRateLimitError(statusCode, errorBody, retryAfter ?? 60);
+  }
+  const StatusCls = STATUS_TO_CLASS[statusCode];
+  if (StatusCls) {
+    return new StatusCls(statusCode, errorBody);
+  }
+  const TypeCls = TYPE_TO_CLASS[errorBody.type];
+  if (TypeCls) {
+    return new TypeCls(statusCode, errorBody);
+  }
+  if (statusCode >= 500) return new CStarServerError(statusCode, errorBody);
+  return new CStarError(statusCode, errorBody);
+}
 
 // src/quickhelp/index.ts
 var DEFAULT_BASE_URL = "https://www.cstar.help";
@@ -282,6 +379,19 @@ function parseRetryAfter(header) {
   return Number.isFinite(n) && n > 0 ? n : void 0;
 }
 export {
+  CStarAuthenticationError,
+  CStarConflictError,
+  CStarError,
+  CStarFeatureDisabledError,
+  CStarNotFoundError,
+  CStarPermissionError,
+  CStarRateLimitError,
+  CStarRealtimeUnavailableError,
+  CStarServerError,
+  CStarValidationError,
+  ErrorType,
   QuickHelpClient,
-  QuickHelpError
+  QuickHelpError,
+  parseError,
+  parsePublicError
 };

package/dist/webhook/index.cjs

@@ -20,19 +20,55 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/webhook/index.ts
 var webhook_exports = {};
 __export(webhook_exports, {
+  DEFAULT_TOLERANCE_SECONDS: () => DEFAULT_TOLERANCE_SECONDS,
   WebhookSignatureVerificationError: () => WebhookSignatureVerificationError,
   constructEventAsync: () => constructEventAsync,
+  signPayloadStripeAsync: () => signPayloadStripeAsync,
   verifySignatureAsync: () => verifySignatureAsync
 });
 module.exports = __toCommonJS(webhook_exports);
+var DEFAULT_TOLERANCE_SECONDS = 300;
 var WebhookSignatureVerificationError = class extends Error {
   constructor(message) {
     super(message);
     this.name = "WebhookSignatureVerificationError";
   }
 };
-async function constructEventAsync(rawBody, signature, secret) {
-  const valid = await verifySignatureAsync(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 };
+}
+async function signPayloadStripeAsync(rawBody, secret) {
+  const ts = Math.floor(Date.now() / 1e3);
+  const encoder = new TextEncoder();
+  const key = await crypto.subtle.importKey(
+    "raw",
+    encoder.encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  );
+  const sigBytes = await crypto.subtle.sign("HMAC", key, encoder.encode(`${ts}.${rawBody}`));
+  const hex = Array.from(new Uint8Array(sigBytes)).map((b) => b.toString(16).padStart(2, "0")).join("");
+  return `t=${ts},v1=${hex}`;
+}
+async function constructEventAsync(rawBody, signature, secret, options) {
+  const valid = await verifySignatureAsync(rawBody, signature, secret, options);
   if (!valid) {
     throw new WebhookSignatureVerificationError(
       "Webhook signature verification failed. Ensure you are using the raw request body and the correct endpoint secret."
@@ -40,7 +76,7 @@ async function constructEventAsync(rawBody, signature, secret) {
   }
   return JSON.parse(rawBody);
 }
-async function verifySignatureAsync(rawBody, signature, secret) {
+async function hmacHex(material, secret) {
   const encoder = new TextEncoder();
   const key = await crypto.subtle.importKey(
     "raw",
@@ -49,18 +85,38 @@ async function verifySignatureAsync(rawBody, signature, secret) {
     false,
     ["sign"]
   );
-  const sig = await crypto.subtle.sign("HMAC", key, encoder.encode(rawBody));
-  const expected = "sha256=" + Array.from(new Uint8Array(sig)).map((b) => b.toString(16).padStart(2, "0")).join("");
-  if (signature.length !== expected.length) return false;
+  const sig = await crypto.subtle.sign("HMAC", key, encoder.encode(material));
+  return Array.from(new Uint8Array(sig)).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+function constantTimeEqual(a, b) {
+  if (a.length !== b.length) return false;
   let result = 0;
-  for (let i = 0; i < signature.length; i++) {
-    result |= signature.charCodeAt(i) ^ expected.charCodeAt(i);
+  for (let i = 0; i < a.length; i++) {
+    result |= a.charCodeAt(i) ^ b.charCodeAt(i);
   }
   return result === 0;
 }
+async function verifySignatureAsync(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 = await hmacHex(`${stripe.timestamp}.${rawBody}`, secret);
+    for (const candidate of stripe.v1) {
+      if (constantTimeEqual(candidate, expected2)) return true;
+    }
+    return false;
+  }
+  const expected = "sha256=" + await hmacHex(rawBody, secret);
+  return constantTimeEqual(signature, expected);
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  DEFAULT_TOLERANCE_SECONDS,
   WebhookSignatureVerificationError,
   constructEventAsync,
+  signPayloadStripeAsync,
   verifySignatureAsync
 });

package/dist/webhook/index.d.cts

@@ -412,10 +412,27 @@ 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>` using Web Crypto.
+ * The HMAC is computed over `${ts}.${rawBody}`. Used by the cStar server
+ * dispatcher and `cstar listen --forward-to`.
+ */
+declare function signPayloadStripeAsync(rawBody: string, secret: string): Promise<string>;
 /**
  * Verify a webhook signature and parse the event.
  *
@@ -427,14 +444,21 @@ 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 constructEventAsync(rawBody: string, signature: string, secret: string): Promise<WebhookEvent>;
+declare function constructEventAsync(rawBody: string, signature: string, secret: string, options?: VerifyOptions): Promise<WebhookEvent>;
 /**
  * Verify an HMAC-SHA256 signature using the Web Crypto API.
+ *
+ * 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` only, no timestamp). Use
+ * `options.tolerance` to override the default 300s replay window.
+ *
  * Constant-time comparison to prevent timing attacks.
  */
-declare function verifySignatureAsync(rawBody: string, signature: string, secret: string): Promise<boolean>;
+declare function verifySignatureAsync(rawBody: string, signature: string, secret: string, options?: VerifyOptions): Promise<boolean>;
 
-export { type WebhookEvent, WebhookSignatureVerificationError, constructEventAsync, verifySignatureAsync };
+export { DEFAULT_TOLERANCE_SECONDS, type VerifyOptions, type WebhookEvent, WebhookSignatureVerificationError, constructEventAsync, signPayloadStripeAsync, verifySignatureAsync };

package/dist/webhook/index.d.ts

@@ -412,10 +412,27 @@ 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>` using Web Crypto.
+ * The HMAC is computed over `${ts}.${rawBody}`. Used by the cStar server
+ * dispatcher and `cstar listen --forward-to`.
+ */
+declare function signPayloadStripeAsync(rawBody: string, secret: string): Promise<string>;
 /**
  * Verify a webhook signature and parse the event.
  *
@@ -427,14 +444,21 @@ 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 constructEventAsync(rawBody: string, signature: string, secret: string): Promise<WebhookEvent>;
+declare function constructEventAsync(rawBody: string, signature: string, secret: string, options?: VerifyOptions): Promise<WebhookEvent>;
 /**
  * Verify an HMAC-SHA256 signature using the Web Crypto API.
+ *
+ * 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` only, no timestamp). Use
+ * `options.tolerance` to override the default 300s replay window.
+ *
  * Constant-time comparison to prevent timing attacks.
  */
-declare function verifySignatureAsync(rawBody: string, signature: string, secret: string): Promise<boolean>;
+declare function verifySignatureAsync(rawBody: string, signature: string, secret: string, options?: VerifyOptions): Promise<boolean>;
 
-export { type WebhookEvent, WebhookSignatureVerificationError, constructEventAsync, verifySignatureAsync };
+export { DEFAULT_TOLERANCE_SECONDS, type VerifyOptions, type WebhookEvent, WebhookSignatureVerificationError, constructEventAsync, signPayloadStripeAsync, verifySignatureAsync };

package/dist/webhook/index.js

@@ -1,12 +1,46 @@
 // src/webhook/index.ts
+var DEFAULT_TOLERANCE_SECONDS = 300;
 var WebhookSignatureVerificationError = class extends Error {
   constructor(message) {
     super(message);
     this.name = "WebhookSignatureVerificationError";
   }
 };
-async function constructEventAsync(rawBody, signature, secret) {
-  const valid = await verifySignatureAsync(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 };
+}
+async function signPayloadStripeAsync(rawBody, secret) {
+  const ts = Math.floor(Date.now() / 1e3);
+  const encoder = new TextEncoder();
+  const key = await crypto.subtle.importKey(
+    "raw",
+    encoder.encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  );
+  const sigBytes = await crypto.subtle.sign("HMAC", key, encoder.encode(`${ts}.${rawBody}`));
+  const hex = Array.from(new Uint8Array(sigBytes)).map((b) => b.toString(16).padStart(2, "0")).join("");
+  return `t=${ts},v1=${hex}`;
+}
+async function constructEventAsync(rawBody, signature, secret, options) {
+  const valid = await verifySignatureAsync(rawBody, signature, secret, options);
   if (!valid) {
     throw new WebhookSignatureVerificationError(
       "Webhook signature verification failed. Ensure you are using the raw request body and the correct endpoint secret."
@@ -14,7 +48,7 @@ async function constructEventAsync(rawBody, signature, secret) {
   }
   return JSON.parse(rawBody);
 }
-async function verifySignatureAsync(rawBody, signature, secret) {
+async function hmacHex(material, secret) {
   const encoder = new TextEncoder();
   const key = await crypto.subtle.importKey(
     "raw",
@@ -23,17 +57,37 @@ async function verifySignatureAsync(rawBody, signature, secret) {
     false,
     ["sign"]
   );
-  const sig = await crypto.subtle.sign("HMAC", key, encoder.encode(rawBody));
-  const expected = "sha256=" + Array.from(new Uint8Array(sig)).map((b) => b.toString(16).padStart(2, "0")).join("");
-  if (signature.length !== expected.length) return false;
+  const sig = await crypto.subtle.sign("HMAC", key, encoder.encode(material));
+  return Array.from(new Uint8Array(sig)).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+function constantTimeEqual(a, b) {
+  if (a.length !== b.length) return false;
   let result = 0;
-  for (let i = 0; i < signature.length; i++) {
-    result |= signature.charCodeAt(i) ^ expected.charCodeAt(i);
+  for (let i = 0; i < a.length; i++) {
+    result |= a.charCodeAt(i) ^ b.charCodeAt(i);
   }
   return result === 0;
 }
+async function verifySignatureAsync(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 = await hmacHex(`${stripe.timestamp}.${rawBody}`, secret);
+    for (const candidate of stripe.v1) {
+      if (constantTimeEqual(candidate, expected2)) return true;
+    }
+    return false;
+  }
+  const expected = "sha256=" + await hmacHex(rawBody, secret);
+  return constantTimeEqual(signature, expected);
+}
 export {
+  DEFAULT_TOLERANCE_SECONDS,
   WebhookSignatureVerificationError,
   constructEventAsync,
+  signPayloadStripeAsync,
   verifySignatureAsync
 };

package/dist/webhook/node.cjs

@@ -20,14 +20,17 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/webhook/node.ts
 var node_exports = {};
 __export(node_exports, {
+  DEFAULT_TOLERANCE_SECONDS: () => DEFAULT_TOLERANCE_SECONDS,
   WebhookSignatureVerificationError: () => WebhookSignatureVerificationError,
   constructEvent: () => constructEvent,
+  signPayloadStripe: () => signPayloadStripe,
   verifySignature: () => verifySignature
 });
 module.exports = __toCommonJS(node_exports);
 var import_node_crypto = require("crypto");
 
 // src/webhook/index.ts
+var DEFAULT_TOLERANCE_SECONDS = 300;
 var WebhookSignatureVerificationError = class extends Error {
   constructor(message) {
     super(message);
@@ -36,22 +39,67 @@ 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 (0, import_node_crypto.timingSafeEqual)(Buffer.from(a), Buffer.from(b));
+  } catch {
+    return false;
+  }
+}
+function signPayloadStripe(rawBody, secret) {
+  const ts = Math.floor(Date.now() / 1e3);
+  const sig = (0, import_node_crypto.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 = (0, import_node_crypto.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=" + (0, import_node_crypto.createHmac)("sha256", secret).update(rawBody).digest("hex");
-  if (signature.length !== expected.length) return false;
-  return (0, import_node_crypto.timingSafeEqual)(Buffer.from(signature), Buffer.from(expected));
+  return constantTimeEqualHex(signature, expected);
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  DEFAULT_TOLERANCE_SECONDS,
   WebhookSignatureVerificationError,
   constructEvent,
+  signPayloadStripe,
   verifySignature
 });

package/dist/webhook/node.d.cts

@@ -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 };