@rstreamlabs/tunnels 3.2.0 → 3.2.1

package/README.md

@@ -190,7 +190,8 @@ For a receiving backend, verify the signature before touching the JSON payload
 and use the event id as the idempotency key.
 
 ```ts
-import { RstreamWebhookResource, type WebhookEvent } from "@rstreamlabs/tunnels";
+import { RstreamWebhookResource } from "@rstreamlabs/tunnels";
+import { type WebhookEvent } from "@rstreamlabs/tunnels";
 
 const webhooks = new RstreamWebhookResource();
 
@@ -225,18 +226,55 @@ export async function receiveWebhook(request: Request) {
   const rawBody = Buffer.from(await request.arrayBuffer());
   const signature = request.headers.get("rstream-signature");
   if (!signature) throw new Error("Missing webhook signature.");
-
   const event = await webhooks.event(
     rawBody,
     signature,
     process.env.WEBHOOK_SECRET!,
   );
   if (!event.id) throw new Error("Missing webhook event id.");
-
   await handleLifecycleEvent(event);
 }
 ```
 
+For local receiver tests, the SDK exposes the same signing primitives used by
+the CLI and Engine dispatcher:
+
+```ts
+import { buildWebhookHeaders } from "@rstreamlabs/tunnels";
+import { generateWebhookSigningSecret } from "@rstreamlabs/tunnels";
+import { type WebhookEvent } from "@rstreamlabs/tunnels";
+
+const secret = generateWebhookSigningSecret();
+const event: WebhookEvent & { id: string } = {
+  id: "evt_test",
+  type: "tunnel.created",
+  created_at: new Date().toISOString(),
+  object: {
+    id: "tunnel_test",
+    labels: {
+      device: "device_123",
+    },
+  },
+};
+const body = JSON.stringify(event);
+const headers = buildWebhookHeaders(body, event, secret, {
+  deliveryId: "del_test",
+  webhookId: "we_test",
+});
+
+await fetch("http://localhost:3000/api/rstream/webhook", {
+  body,
+  headers: {
+    "content-type": "application/json",
+    ...headers,
+  },
+  method: "POST",
+});
+```
+
+`rstream events --webhook` uses the same request body and header contract when
+forwarding live local events to a receiver.
+
 ## WebTTY Helpers
 
 Use `parseWebTTYServers()` to derive WebTTY server metadata from tunnel

package/dist/index.d.mts

@@ -2967,8 +2967,26 @@ type WebhookEvent = z.infer<typeof webhookEventsSchema>;
 type ProjectLogEvent = z.infer<typeof projectLogEventsSchema>;
 type Event = z.infer<typeof eventSchema>;
 
+declare const WEBHOOK_SIGNATURE_HEADER = "rstream-signature";
+declare const WEBHOOK_EVENT_ID_HEADER = "rstream-event-id";
+declare const WEBHOOK_EVENT_TYPE_HEADER = "rstream-event-type";
+declare const WEBHOOK_ID_HEADER = "rstream-webhook-id";
+declare const WEBHOOK_DELIVERY_ID_HEADER = "rstream-delivery-id";
+type WebhookPayload = string | Buffer;
+type WebhookHeaders = Record<typeof WEBHOOK_SIGNATURE_HEADER | typeof WEBHOOK_EVENT_ID_HEADER | typeof WEBHOOK_EVENT_TYPE_HEADER | typeof WEBHOOK_ID_HEADER | typeof WEBHOOK_DELIVERY_ID_HEADER, string>;
+interface BuildWebhookHeadersOptions {
+    deliveryId: string;
+    timestamp?: Date | number;
+    webhookId: string;
+}
+declare function generateWebhookSigningSecret(): string;
+declare function signWebhookPayload(payload: WebhookPayload, secret: string, timestamp?: Date | number): string;
+declare function buildWebhookHeaders(payload: WebhookPayload, event: WebhookEvent, secret: string, options: BuildWebhookHeadersOptions): WebhookHeaders;
 declare class RstreamWebhookResource {
-    event(payload: string | Buffer, header: string | Buffer | Array<string>, secret: string, tolerance?: number, receivedAt?: number): Promise<WebhookEvent>;
+    event(payload: WebhookPayload, header: string | Buffer | Array<string>, secret: string, tolerance?: number, receivedAt?: number): Promise<WebhookEvent>;
+    generateSigningSecret(): string;
+    sign(payload: WebhookPayload, secret: string, timestamp?: Date | number): string;
+    headers(payload: WebhookPayload, event: WebhookEvent, secret: string, options: BuildWebhookHeadersOptions): WebhookHeaders;
 }
 
 interface RstreamTunnelsConfig {
@@ -3682,4 +3700,4 @@ declare const webttyServerSchema: z.ZodObject<{
 type WebTTYServer = z.infer<typeof webttyServerSchema>;
 declare function parseWebTTYServers(tunnels: Tunnel[]): WebTTYServer[];
 
-export { type Client, type ClientFilter, type CreateAPITURNCredentialsOptions, type CreateAPPTURNCredentialsOptions, type CreateAuthTokenFromClientCredentialsOptions, type CreatePATTURNCredentialsOptions, type CreateTURNCredentialsOptions, type Event, type InitialState, type ListClientsParams, type ListClientsResponse, type ListTunnelsParams, type ListTunnelsResponse, type ProjectLogEvent, type RstreamAuth, RstreamAuthResource, RstreamAuthResource as RstreamAuthRessource, RstreamTunnelsClient as RstreamClient, RstreamClientsResource, RstreamClientsResource as RstreamClientsRessource, RstreamTURNResource, RstreamTunnelsClient, type RstreamTunnelsConfig, RstreamTunnelsResource, RstreamTunnelsResource as RstreamTunnelsRessource, RstreamWebhookResource, RstreamWebhookResource as RstreamWebhookRessource, type StreamEndpoint, type StreamSummary, type StreamTLSInfo, type TURNCredentialMode, type TunnelFilter, RstreamTunnelsClient as Tunnels, type TunnelsResolutionConfig, Watch, type WatchConfig, type WatchWsEvents, type WebTTYServer, type WebhookEvent, type WsEvent, clientFilterSchema, clientSchema, createAPITURNCredentials, createAPPTURNCredentials, createAuthTokenFromClientCredentials, createPATTURNCredentials, createTURNCredentials, eventSchema, formatTunnelHost, listClientsParamsSchema, listClientsResponseSchema, listTunnelsParamsSchema, listTunnelsResponseSchema, normalizeEngineAddress, parseWebTTYServers, projectLogEventsSchema, resolveControlPlaneCredentials, resolveManagedTunnelsProject, resolveTunnelsAPIURL, resolveTunnelsCredentials, resolveTunnelsEngine, streamEndpointSchema, streamSummaryEventSchema, streamSummarySchema, streamTLSInfoSchema, tunnelFilterSchema, turnCredentialModeSchema, webhookEventsSchema, webttyServerSchema, wsEventsSchema };
+export { type BuildWebhookHeadersOptions, type Client, type ClientFilter, type CreateAPITURNCredentialsOptions, type CreateAPPTURNCredentialsOptions, type CreateAuthTokenFromClientCredentialsOptions, type CreatePATTURNCredentialsOptions, type CreateTURNCredentialsOptions, type Event, type InitialState, type ListClientsParams, type ListClientsResponse, type ListTunnelsParams, type ListTunnelsResponse, type ProjectLogEvent, type RstreamAuth, RstreamAuthResource, RstreamAuthResource as RstreamAuthRessource, RstreamTunnelsClient as RstreamClient, RstreamClientsResource, RstreamClientsResource as RstreamClientsRessource, RstreamTURNResource, RstreamTunnelsClient, type RstreamTunnelsConfig, RstreamTunnelsResource, RstreamTunnelsResource as RstreamTunnelsRessource, RstreamWebhookResource, RstreamWebhookResource as RstreamWebhookRessource, type StreamEndpoint, type StreamSummary, type StreamTLSInfo, type TURNCredentialMode, type TunnelFilter, RstreamTunnelsClient as Tunnels, type TunnelsResolutionConfig, WEBHOOK_DELIVERY_ID_HEADER, WEBHOOK_EVENT_ID_HEADER, WEBHOOK_EVENT_TYPE_HEADER, WEBHOOK_ID_HEADER, WEBHOOK_SIGNATURE_HEADER, Watch, type WatchConfig, type WatchWsEvents, type WebTTYServer, type WebhookEvent, type WebhookHeaders, type WebhookPayload, type WsEvent, buildWebhookHeaders, clientFilterSchema, clientSchema, createAPITURNCredentials, createAPPTURNCredentials, createAuthTokenFromClientCredentials, createPATTURNCredentials, createTURNCredentials, eventSchema, formatTunnelHost, generateWebhookSigningSecret, listClientsParamsSchema, listClientsResponseSchema, listTunnelsParamsSchema, listTunnelsResponseSchema, normalizeEngineAddress, parseWebTTYServers, projectLogEventsSchema, resolveControlPlaneCredentials, resolveManagedTunnelsProject, resolveTunnelsAPIURL, resolveTunnelsCredentials, resolveTunnelsEngine, signWebhookPayload, streamEndpointSchema, streamSummaryEventSchema, streamSummarySchema, streamTLSInfoSchema, tunnelFilterSchema, turnCredentialModeSchema, webhookEventsSchema, webttyServerSchema, wsEventsSchema };

package/dist/index.d.ts

@@ -2967,8 +2967,26 @@ type WebhookEvent = z.infer<typeof webhookEventsSchema>;
 type ProjectLogEvent = z.infer<typeof projectLogEventsSchema>;
 type Event = z.infer<typeof eventSchema>;
 
+declare const WEBHOOK_SIGNATURE_HEADER = "rstream-signature";
+declare const WEBHOOK_EVENT_ID_HEADER = "rstream-event-id";
+declare const WEBHOOK_EVENT_TYPE_HEADER = "rstream-event-type";
+declare const WEBHOOK_ID_HEADER = "rstream-webhook-id";
+declare const WEBHOOK_DELIVERY_ID_HEADER = "rstream-delivery-id";
+type WebhookPayload = string | Buffer;
+type WebhookHeaders = Record<typeof WEBHOOK_SIGNATURE_HEADER | typeof WEBHOOK_EVENT_ID_HEADER | typeof WEBHOOK_EVENT_TYPE_HEADER | typeof WEBHOOK_ID_HEADER | typeof WEBHOOK_DELIVERY_ID_HEADER, string>;
+interface BuildWebhookHeadersOptions {
+    deliveryId: string;
+    timestamp?: Date | number;
+    webhookId: string;
+}
+declare function generateWebhookSigningSecret(): string;
+declare function signWebhookPayload(payload: WebhookPayload, secret: string, timestamp?: Date | number): string;
+declare function buildWebhookHeaders(payload: WebhookPayload, event: WebhookEvent, secret: string, options: BuildWebhookHeadersOptions): WebhookHeaders;
 declare class RstreamWebhookResource {
-    event(payload: string | Buffer, header: string | Buffer | Array<string>, secret: string, tolerance?: number, receivedAt?: number): Promise<WebhookEvent>;
+    event(payload: WebhookPayload, header: string | Buffer | Array<string>, secret: string, tolerance?: number, receivedAt?: number): Promise<WebhookEvent>;
+    generateSigningSecret(): string;
+    sign(payload: WebhookPayload, secret: string, timestamp?: Date | number): string;
+    headers(payload: WebhookPayload, event: WebhookEvent, secret: string, options: BuildWebhookHeadersOptions): WebhookHeaders;
 }
 
 interface RstreamTunnelsConfig {
@@ -3682,4 +3700,4 @@ declare const webttyServerSchema: z.ZodObject<{
 type WebTTYServer = z.infer<typeof webttyServerSchema>;
 declare function parseWebTTYServers(tunnels: Tunnel[]): WebTTYServer[];
 
-export { type Client, type ClientFilter, type CreateAPITURNCredentialsOptions, type CreateAPPTURNCredentialsOptions, type CreateAuthTokenFromClientCredentialsOptions, type CreatePATTURNCredentialsOptions, type CreateTURNCredentialsOptions, type Event, type InitialState, type ListClientsParams, type ListClientsResponse, type ListTunnelsParams, type ListTunnelsResponse, type ProjectLogEvent, type RstreamAuth, RstreamAuthResource, RstreamAuthResource as RstreamAuthRessource, RstreamTunnelsClient as RstreamClient, RstreamClientsResource, RstreamClientsResource as RstreamClientsRessource, RstreamTURNResource, RstreamTunnelsClient, type RstreamTunnelsConfig, RstreamTunnelsResource, RstreamTunnelsResource as RstreamTunnelsRessource, RstreamWebhookResource, RstreamWebhookResource as RstreamWebhookRessource, type StreamEndpoint, type StreamSummary, type StreamTLSInfo, type TURNCredentialMode, type TunnelFilter, RstreamTunnelsClient as Tunnels, type TunnelsResolutionConfig, Watch, type WatchConfig, type WatchWsEvents, type WebTTYServer, type WebhookEvent, type WsEvent, clientFilterSchema, clientSchema, createAPITURNCredentials, createAPPTURNCredentials, createAuthTokenFromClientCredentials, createPATTURNCredentials, createTURNCredentials, eventSchema, formatTunnelHost, listClientsParamsSchema, listClientsResponseSchema, listTunnelsParamsSchema, listTunnelsResponseSchema, normalizeEngineAddress, parseWebTTYServers, projectLogEventsSchema, resolveControlPlaneCredentials, resolveManagedTunnelsProject, resolveTunnelsAPIURL, resolveTunnelsCredentials, resolveTunnelsEngine, streamEndpointSchema, streamSummaryEventSchema, streamSummarySchema, streamTLSInfoSchema, tunnelFilterSchema, turnCredentialModeSchema, webhookEventsSchema, webttyServerSchema, wsEventsSchema };
+export { type BuildWebhookHeadersOptions, type Client, type ClientFilter, type CreateAPITURNCredentialsOptions, type CreateAPPTURNCredentialsOptions, type CreateAuthTokenFromClientCredentialsOptions, type CreatePATTURNCredentialsOptions, type CreateTURNCredentialsOptions, type Event, type InitialState, type ListClientsParams, type ListClientsResponse, type ListTunnelsParams, type ListTunnelsResponse, type ProjectLogEvent, type RstreamAuth, RstreamAuthResource, RstreamAuthResource as RstreamAuthRessource, RstreamTunnelsClient as RstreamClient, RstreamClientsResource, RstreamClientsResource as RstreamClientsRessource, RstreamTURNResource, RstreamTunnelsClient, type RstreamTunnelsConfig, RstreamTunnelsResource, RstreamTunnelsResource as RstreamTunnelsRessource, RstreamWebhookResource, RstreamWebhookResource as RstreamWebhookRessource, type StreamEndpoint, type StreamSummary, type StreamTLSInfo, type TURNCredentialMode, type TunnelFilter, RstreamTunnelsClient as Tunnels, type TunnelsResolutionConfig, WEBHOOK_DELIVERY_ID_HEADER, WEBHOOK_EVENT_ID_HEADER, WEBHOOK_EVENT_TYPE_HEADER, WEBHOOK_ID_HEADER, WEBHOOK_SIGNATURE_HEADER, Watch, type WatchConfig, type WatchWsEvents, type WebTTYServer, type WebhookEvent, type WebhookHeaders, type WebhookPayload, type WsEvent, buildWebhookHeaders, clientFilterSchema, clientSchema, createAPITURNCredentials, createAPPTURNCredentials, createAuthTokenFromClientCredentials, createPATTURNCredentials, createTURNCredentials, eventSchema, formatTunnelHost, generateWebhookSigningSecret, listClientsParamsSchema, listClientsResponseSchema, listTunnelsParamsSchema, listTunnelsResponseSchema, normalizeEngineAddress, parseWebTTYServers, projectLogEventsSchema, resolveControlPlaneCredentials, resolveManagedTunnelsProject, resolveTunnelsAPIURL, resolveTunnelsCredentials, resolveTunnelsEngine, signWebhookPayload, streamEndpointSchema, streamSummaryEventSchema, streamSummarySchema, streamTLSInfoSchema, tunnelFilterSchema, turnCredentialModeSchema, webhookEventsSchema, webttyServerSchema, wsEventsSchema };

package/dist/index.js

@@ -42,7 +42,13 @@ __export(index_exports, {
   RstreamWebhookResource: () => RstreamWebhookResource,
   RstreamWebhookRessource: () => RstreamWebhookResource,
   Tunnels: () => RstreamTunnelsClient,
+  WEBHOOK_DELIVERY_ID_HEADER: () => WEBHOOK_DELIVERY_ID_HEADER,
+  WEBHOOK_EVENT_ID_HEADER: () => WEBHOOK_EVENT_ID_HEADER,
+  WEBHOOK_EVENT_TYPE_HEADER: () => WEBHOOK_EVENT_TYPE_HEADER,
+  WEBHOOK_ID_HEADER: () => WEBHOOK_ID_HEADER,
+  WEBHOOK_SIGNATURE_HEADER: () => WEBHOOK_SIGNATURE_HEADER,
   Watch: () => Watch,
+  buildWebhookHeaders: () => buildWebhookHeaders,
   clientFilterSchema: () => clientFilterSchema,
   clientSchema: () => clientSchema,
   createAPITURNCredentials: () => createAPITURNCredentials,
@@ -54,6 +60,7 @@ __export(index_exports, {
   engineOpenApiJson: () => engineOpenApiJson,
   eventSchema: () => eventSchema,
   formatTunnelHost: () => formatTunnelHost,
+  generateWebhookSigningSecret: () => generateWebhookSigningSecret,
   listClientsParamsSchema: () => listClientsParamsSchema,
   listClientsResponseSchema: () => listClientsResponseSchema,
   listTunnelsParamsSchema: () => listTunnelsParamsSchema,
@@ -66,6 +73,7 @@ __export(index_exports, {
   resolveTunnelsAPIURL: () => resolveTunnelsAPIURL,
   resolveTunnelsCredentials: () => resolveTunnelsCredentials,
   resolveTunnelsEngine: () => resolveTunnelsEngine,
+  signWebhookPayload: () => signWebhookPayload,
   streamEndpointSchema: () => streamEndpointSchema,
   streamSummaryEventSchema: () => streamSummaryEventSchema,
   streamSummarySchema: () => streamSummarySchema,
@@ -1477,9 +1485,18 @@ var RstreamTURNResource = class {
 
 // src/webhooks-resource.ts
 var import_crypto2 = __toESM(require("crypto"));
+var WEBHOOK_SIGNATURE_HEADER = "rstream-signature";
+var WEBHOOK_EVENT_ID_HEADER = "rstream-event-id";
+var WEBHOOK_EVENT_TYPE_HEADER = "rstream-event-type";
+var WEBHOOK_ID_HEADER = "rstream-webhook-id";
+var WEBHOOK_DELIVERY_ID_HEADER = "rstream-delivery-id";
 var SIGNATURE_HEX_BYTES = 32;
+var webhookSecretBytes = 32;
 var signatureHexSchema = /^[0-9a-fA-F]{64}$/;
 var timestampSchema = /^\d+$/;
+function payloadBuffer(payload) {
+  return Buffer.isBuffer(payload) ? payload : Buffer.from(payload);
+}
 function parseSignatureTimestamp(timestamp) {
   if (!timestampSchema.test(timestamp)) {
     throw new Error("Invalid signature timestamp");
@@ -1496,6 +1513,19 @@ function normalizeTolerance(tolerance) {
   }
   return tolerance;
 }
+function normalizeTimestamp(timestamp) {
+  if (timestamp === void 0) {
+    return Math.floor(Date.now() / 1e3);
+  }
+  const seconds = timestamp instanceof Date ? timestamp.getTime() / 1e3 : timestamp;
+  if (!Number.isFinite(seconds) || seconds < 0) {
+    throw new Error("Invalid webhook signature timestamp");
+  }
+  return Math.floor(seconds);
+}
+function signedPayload(timestamp, payload) {
+  return Buffer.concat([Buffer.from(`${timestamp}.`, "utf8"), payload]);
+}
 function readSignature(signature) {
   if (!signatureHexSchema.test(signature)) {
     return void 0;
@@ -1512,9 +1542,42 @@ function assertSecretConfigured(secret) {
     throw new Error("Webhook signing secret is required");
   }
 }
+function assertNonEmpty(value, label) {
+  const normalized = value.trim();
+  if (normalized.length === 0) {
+    throw new Error(`${label} is required`);
+  }
+  return normalized;
+}
+function generateWebhookSigningSecret() {
+  return `whsec_${import_crypto2.default.randomBytes(webhookSecretBytes).toString("base64url")}`;
+}
+function signWebhookPayload(payload, secret, timestamp) {
+  assertSecretConfigured(secret);
+  const timestampSeconds = normalizeTimestamp(timestamp).toString();
+  const signature = import_crypto2.default.createHmac("sha256", secret).update(signedPayload(timestampSeconds, payloadBuffer(payload))).digest("hex");
+  return `t=${timestampSeconds},v1=${signature}`;
+}
+function buildWebhookHeaders(payload, event, secret, options) {
+  const eventId = assertNonEmpty(event.id ?? "", "Webhook event id");
+  const eventType = assertNonEmpty(event.type, "Webhook event type");
+  const webhookId = assertNonEmpty(options.webhookId, "Webhook id");
+  const deliveryId = assertNonEmpty(options.deliveryId, "Webhook delivery id");
+  return {
+    [WEBHOOK_SIGNATURE_HEADER]: signWebhookPayload(
+      payload,
+      secret,
+      options.timestamp
+    ),
+    [WEBHOOK_EVENT_ID_HEADER]: eventId,
+    [WEBHOOK_EVENT_TYPE_HEADER]: eventType,
+    [WEBHOOK_ID_HEADER]: webhookId,
+    [WEBHOOK_DELIVERY_ID_HEADER]: deliveryId
+  };
+}
 var RstreamWebhookResource = class {
   async event(payload, header, secret, tolerance = 300, receivedAt = Date.now()) {
-    const payloadBuffer = Buffer.isBuffer(payload) ? payload : Buffer.from(payload);
+    const rawPayload = payloadBuffer(payload);
     const signatureHeader = Array.isArray(header) ? header[0] : header.toString();
     if (!signatureHeader) {
       throw new Error("No signature header");
@@ -1534,8 +1597,7 @@ var RstreamWebhookResource = class {
         `Webhook signature timestamp outside tolerance: ${now}, ${timestampNum}`
       );
     }
-    const signedPayload = `${timestamp}.${payloadBuffer.toString("utf8")}`;
-    const expectedSignature = import_crypto2.default.createHmac("sha256", secret).update(signedPayload).digest();
+    const expectedSignature = import_crypto2.default.createHmac("sha256", secret).update(signedPayload(timestamp, rawPayload)).digest();
     const signatureMatched = signatures.some(
       (signature) => signatureMatches(signature, expectedSignature)
     );
@@ -1543,9 +1605,7 @@ var RstreamWebhookResource = class {
       throw new Error("Signature verification failed");
     }
     try {
-      return webhookEventsSchema.parse(
-        JSON.parse(payloadBuffer.toString("utf8"))
-      );
+      return webhookEventsSchema.parse(JSON.parse(rawPayload.toString("utf8")));
     } catch (error) {
       throw new Error(
         `Failed to parse webhook payload: ${error instanceof Error ? error.message : String(error)}`,
@@ -1553,6 +1613,15 @@ var RstreamWebhookResource = class {
       );
     }
   }
+  generateSigningSecret() {
+    return generateWebhookSigningSecret();
+  }
+  sign(payload, secret, timestamp) {
+    return signWebhookPayload(payload, secret, timestamp);
+  }
+  headers(payload, event, secret, options) {
+    return buildWebhookHeaders(payload, event, secret, options);
+  }
 };
 
 // src/tunnels.ts
@@ -1985,7 +2054,13 @@ function parseWebTTYServers(tunnels) {
   RstreamWebhookResource,
   RstreamWebhookRessource,
   Tunnels,
+  WEBHOOK_DELIVERY_ID_HEADER,
+  WEBHOOK_EVENT_ID_HEADER,
+  WEBHOOK_EVENT_TYPE_HEADER,
+  WEBHOOK_ID_HEADER,
+  WEBHOOK_SIGNATURE_HEADER,
   Watch,
+  buildWebhookHeaders,
   clientFilterSchema,
   clientSchema,
   createAPITURNCredentials,
@@ -1997,6 +2072,7 @@ function parseWebTTYServers(tunnels) {
   engineOpenApiJson,
   eventSchema,
   formatTunnelHost,
+  generateWebhookSigningSecret,
   listClientsParamsSchema,
   listClientsResponseSchema,
   listTunnelsParamsSchema,
@@ -2009,6 +2085,7 @@ function parseWebTTYServers(tunnels) {
   resolveTunnelsAPIURL,
   resolveTunnelsCredentials,
   resolveTunnelsEngine,
+  signWebhookPayload,
   streamEndpointSchema,
   streamSummaryEventSchema,
   streamSummarySchema,

package/dist/index.mjs

@@ -730,9 +730,18 @@ var RstreamTURNResource = class {
 
 // src/webhooks-resource.ts
 import crypto2 from "crypto";
+var WEBHOOK_SIGNATURE_HEADER = "rstream-signature";
+var WEBHOOK_EVENT_ID_HEADER = "rstream-event-id";
+var WEBHOOK_EVENT_TYPE_HEADER = "rstream-event-type";
+var WEBHOOK_ID_HEADER = "rstream-webhook-id";
+var WEBHOOK_DELIVERY_ID_HEADER = "rstream-delivery-id";
 var SIGNATURE_HEX_BYTES = 32;
+var webhookSecretBytes = 32;
 var signatureHexSchema = /^[0-9a-fA-F]{64}$/;
 var timestampSchema = /^\d+$/;
+function payloadBuffer(payload) {
+  return Buffer.isBuffer(payload) ? payload : Buffer.from(payload);
+}
 function parseSignatureTimestamp(timestamp) {
   if (!timestampSchema.test(timestamp)) {
     throw new Error("Invalid signature timestamp");
@@ -749,6 +758,19 @@ function normalizeTolerance(tolerance) {
   }
   return tolerance;
 }
+function normalizeTimestamp(timestamp) {
+  if (timestamp === void 0) {
+    return Math.floor(Date.now() / 1e3);
+  }
+  const seconds = timestamp instanceof Date ? timestamp.getTime() / 1e3 : timestamp;
+  if (!Number.isFinite(seconds) || seconds < 0) {
+    throw new Error("Invalid webhook signature timestamp");
+  }
+  return Math.floor(seconds);
+}
+function signedPayload(timestamp, payload) {
+  return Buffer.concat([Buffer.from(`${timestamp}.`, "utf8"), payload]);
+}
 function readSignature(signature) {
   if (!signatureHexSchema.test(signature)) {
     return void 0;
@@ -765,9 +787,42 @@ function assertSecretConfigured(secret) {
     throw new Error("Webhook signing secret is required");
   }
 }
+function assertNonEmpty(value, label) {
+  const normalized = value.trim();
+  if (normalized.length === 0) {
+    throw new Error(`${label} is required`);
+  }
+  return normalized;
+}
+function generateWebhookSigningSecret() {
+  return `whsec_${crypto2.randomBytes(webhookSecretBytes).toString("base64url")}`;
+}
+function signWebhookPayload(payload, secret, timestamp) {
+  assertSecretConfigured(secret);
+  const timestampSeconds = normalizeTimestamp(timestamp).toString();
+  const signature = crypto2.createHmac("sha256", secret).update(signedPayload(timestampSeconds, payloadBuffer(payload))).digest("hex");
+  return `t=${timestampSeconds},v1=${signature}`;
+}
+function buildWebhookHeaders(payload, event, secret, options) {
+  const eventId = assertNonEmpty(event.id ?? "", "Webhook event id");
+  const eventType = assertNonEmpty(event.type, "Webhook event type");
+  const webhookId = assertNonEmpty(options.webhookId, "Webhook id");
+  const deliveryId = assertNonEmpty(options.deliveryId, "Webhook delivery id");
+  return {
+    [WEBHOOK_SIGNATURE_HEADER]: signWebhookPayload(
+      payload,
+      secret,
+      options.timestamp
+    ),
+    [WEBHOOK_EVENT_ID_HEADER]: eventId,
+    [WEBHOOK_EVENT_TYPE_HEADER]: eventType,
+    [WEBHOOK_ID_HEADER]: webhookId,
+    [WEBHOOK_DELIVERY_ID_HEADER]: deliveryId
+  };
+}
 var RstreamWebhookResource = class {
   async event(payload, header, secret, tolerance = 300, receivedAt = Date.now()) {
-    const payloadBuffer = Buffer.isBuffer(payload) ? payload : Buffer.from(payload);
+    const rawPayload = payloadBuffer(payload);
     const signatureHeader = Array.isArray(header) ? header[0] : header.toString();
     if (!signatureHeader) {
       throw new Error("No signature header");
@@ -787,8 +842,7 @@ var RstreamWebhookResource = class {
         `Webhook signature timestamp outside tolerance: ${now}, ${timestampNum}`
       );
     }
-    const signedPayload = `${timestamp}.${payloadBuffer.toString("utf8")}`;
-    const expectedSignature = crypto2.createHmac("sha256", secret).update(signedPayload).digest();
+    const expectedSignature = crypto2.createHmac("sha256", secret).update(signedPayload(timestamp, rawPayload)).digest();
     const signatureMatched = signatures.some(
       (signature) => signatureMatches(signature, expectedSignature)
     );
@@ -796,9 +850,7 @@ var RstreamWebhookResource = class {
       throw new Error("Signature verification failed");
     }
     try {
-      return webhookEventsSchema.parse(
-        JSON.parse(payloadBuffer.toString("utf8"))
-      );
+      return webhookEventsSchema.parse(JSON.parse(rawPayload.toString("utf8")));
     } catch (error) {
       throw new Error(
         `Failed to parse webhook payload: ${error instanceof Error ? error.message : String(error)}`,
@@ -806,6 +858,15 @@ var RstreamWebhookResource = class {
       );
     }
   }
+  generateSigningSecret() {
+    return generateWebhookSigningSecret();
+  }
+  sign(payload, secret, timestamp) {
+    return signWebhookPayload(payload, secret, timestamp);
+  }
+  headers(payload, event, secret, options) {
+    return buildWebhookHeaders(payload, event, secret, options);
+  }
 };
 
 // src/tunnels.ts
@@ -1237,7 +1298,13 @@ export {
   RstreamWebhookResource,
   RstreamWebhookResource as RstreamWebhookRessource,
   RstreamTunnelsClient as Tunnels,
+  WEBHOOK_DELIVERY_ID_HEADER,
+  WEBHOOK_EVENT_ID_HEADER,
+  WEBHOOK_EVENT_TYPE_HEADER,
+  WEBHOOK_ID_HEADER,
+  WEBHOOK_SIGNATURE_HEADER,
   Watch,
+  buildWebhookHeaders,
   clientFilterSchema,
   clientSchema,
   createAPITURNCredentials,
@@ -1249,6 +1316,7 @@ export {
   engineOpenApiJson,
   eventSchema,
   formatTunnelHost,
+  generateWebhookSigningSecret,
   listClientsParamsSchema,
   listClientsResponseSchema,
   listTunnelsParamsSchema,
@@ -1261,6 +1329,7 @@ export {
   resolveTunnelsAPIURL,
   resolveTunnelsCredentials,
   resolveTunnelsEngine,
+  signWebhookPayload,
   streamEndpointSchema,
   streamSummaryEventSchema,
   streamSummarySchema,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rstreamlabs/tunnels",
-  "version": "3.2.0",
+  "version": "3.2.1",
   "description": "JS/TS SDK for the rstream Engine API and tunnel runtime APIs.",
   "author": "@uartnet <hello@rstream.io>",
   "repository": {