@miosa/sdk 1.2.1 → 1.2.2

package/src/resources/webhooks.ts

@@ -2,7 +2,7 @@
  * Webhooks resource — tenant outgoing event delivery.
  */
 
-import { randomUUID } from "node:crypto";
+import { createHmac, randomUUID, timingSafeEqual } from "node:crypto";
 
 import type { HttpClient } from "../http.js";
 
@@ -66,6 +66,11 @@ export interface WebhookUpdateParams {
   [key: string]: unknown;
 }
 
+export interface WebhookSignatureVerifyOptions {
+  /** Maximum age for the webhook timestamp in seconds. Defaults to 300. */
+  toleranceSeconds?: number;
+}
+
 // ── Helpers ───────────────────────────────────────────────────────────────────
 
 function unwrap<T>(payload: unknown): T {
@@ -101,9 +106,72 @@ function idempotencyKey(key?: string): string {
   return key ?? randomUUID();
 }
 
+function parseSignatureHeader(header: string): {
+  timestamp: number;
+  signatures: string[];
+} | null {
+  const parts = header.split(",").map((part) => part.trim());
+  let timestamp: number | null = null;
+  const signatures: string[] = [];
+
+  for (const part of parts) {
+    const [key, value] = part.split("=", 2);
+    if (!key || !value) continue;
+    if (key === "t") {
+      const parsed = Number(value);
+      if (Number.isFinite(parsed)) timestamp = parsed;
+    } else if (key === "v1") {
+      signatures.push(value);
+    }
+  }
+
+  if (timestamp == null || signatures.length === 0) return null;
+  return { timestamp, signatures };
+}
+
+/**
+ * Verify a MIOSA webhook signature header.
+ *
+ * Header format: `t=<unix_seconds>,v1=<hex_hmac_sha256>`.
+ */
+export function verifySignature(
+  body: string | Buffer | Uint8Array,
+  header: string,
+  secret: string,
+  options: WebhookSignatureVerifyOptions = {},
+): boolean {
+  const parsed = parseSignatureHeader(header);
+  if (!parsed) return false;
+
+  const toleranceSeconds = options.toleranceSeconds ?? 300;
+  const ageSeconds = Math.abs(Math.floor(Date.now() / 1000) - parsed.timestamp);
+  if (ageSeconds > toleranceSeconds) {
+    throw new Error("Webhook signature timestamp is too old");
+  }
+
+  const bodyBuffer = Buffer.isBuffer(body) ? body : Buffer.from(body);
+  const signedPayload = Buffer.concat([
+    Buffer.from(`${parsed.timestamp}.`),
+    bodyBuffer,
+  ]);
+  const expected = createHmac("sha256", secret)
+    .update(signedPayload)
+    .digest("hex");
+  const expectedBuffer = Buffer.from(expected, "hex");
+
+  return parsed.signatures.some((signature) => {
+    const actualBuffer = Buffer.from(signature, "hex");
+    if (actualBuffer.length !== expectedBuffer.length) return false;
+    return timingSafeEqual(actualBuffer, expectedBuffer);
+  });
+}
+
 // ── Main resource ─────────────────────────────────────────────────────────────
 
 export class Webhooks {
+  static verifySignature = verifySignature;
+  static verify_signature = verifySignature;
+
   constructor(private readonly http: HttpClient) {}
 
   async list(params: WebhookListParams = {}): Promise<WebhookData[]> {

package/src/types.ts

@@ -78,9 +78,9 @@ export interface ComputerData {
   id: ComputerId;
   name: string;
   /**
-   * URL-safe identifier used in preview URLs:
-   * `https://{port}-{slug}.sandbox.{preview_domain}`.
-   * Falls back to the computer id when no slug is assigned.
+   * URL-safe identifier used in preview URLs: `https://{port}-{slug}.sandbox.{preview_domain}`.
+   * Falls back to the computer id when no slug is assigned. The domain is the
+   * tenant's white-label `preview_domain` (server-provided) — never hardcode it.
    */
   slug: string;
   status: ComputerStatus;
@@ -91,9 +91,9 @@ export interface ComputerData {
   metadata: Record<string, string>;
   /** Controls who can access the HTTP preview URL. Defaults to `"public"`. */
   visibility: ComputerVisibility;
-  /** Public ingress root, e.g. `https://<slug>.sandbox.<preview_domain>`. */
+  /** Public ingress root, e.g. `https://<slug>.sandbox.<preview_domain>` (server-provided). */
   sandbox_url?: string;
-  /** Tenant's white-label preview/base domain, e.g. `cliniciq.com`. */
+  /** Tenant's white-label preview/base domain (e.g. `cliniciq.com`). Use to build preview URLs. */
   preview_domain?: string;
   /** KasmVNC URL for desktop templates. */
   desktop_url?: string;