@miosa/sdk 1.2.4 → 1.2.5

package/src/resources/webhooks.ts

@@ -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,63 +106,73 @@ function idempotencyKey(key?: string): string {
   return key ?? randomUUID();
 }
 
-function bodyBuffer(body: Buffer | Uint8Array | string): Buffer {
-  if (Buffer.isBuffer(body)) return body;
-  if (typeof body === "string") return Buffer.from(body, "utf8");
-  return Buffer.from(body);
+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 the `Miosa-Signature` webhook header.
+ * Verify a MIOSA webhook signature header.
  *
- * Header format: `t=<unix_seconds>,v1=<hex_hmac>`.
- * Signed payload: `<timestamp>.<raw_body>`.
+ * Header format: `t=<unix_seconds>,v1=<hex_hmac_sha256>`.
  */
 export function verifySignature(
-  body: Buffer | Uint8Array | string,
+  body: string | Buffer | Uint8Array,
   header: string,
   secret: string,
-  toleranceSec = 300,
+  options: WebhookSignatureVerifyOptions = {},
 ): boolean {
-  const parts = Object.fromEntries(
-    header
-      .split(",")
-      .map((chunk) => chunk.split("=", 2))
-      .filter(([key, value]) => key && value),
-  );
-
-  const timestamp = parts.t;
-  const received = parts.v1;
-  if (!timestamp || !received || !secret) return false;
-
-  const unixSeconds = Number(timestamp);
-  if (!Number.isFinite(unixSeconds)) return false;
+  const parsed = parseSignatureHeader(header);
+  if (!parsed) return false;
 
-  const ageSec = Math.abs(Date.now() / 1000 - unixSeconds);
-  if (ageSec > toleranceSec) {
-    throw new Error("webhook timestamp too old");
+  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 rawBody = bodyBuffer(body);
-  const signed = Buffer.concat([Buffer.from(`${timestamp}.`), rawBody]);
-  const expected = createHmac("sha256", secret).update(signed).digest("hex");
-
-  try {
-    return timingSafeEqual(
-      Buffer.from(expected, "utf8"),
-      Buffer.from(received, "utf8"),
-    );
-  } catch {
-    return false;
-  }
+  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 {
-  constructor(private readonly http: HttpClient) {}
-
   static verifySignature = verifySignature;
+  static verify_signature = verifySignature;
+
+  constructor(private readonly http: HttpClient) {}
 
   async list(params: WebhookListParams = {}): Promise<WebhookData[]> {
     const query = stripUndefined({ ...params }) as Record<

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. The domain is the
-   * tenant's white-label `preview_domain` (server-provided) — never hardcode it.
+   * URL-safe identifier used in preview URLs:
+   * `https://{port}-{slug}.sandbox.{preview_domain}`.
+   * Falls back to the computer id when no slug is assigned.
    */
   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>` (server-provided). */
+  /** Public ingress root, e.g. `https://<slug>.sandbox.<preview_domain>`. */
   sandbox_url?: string;
-  /** Tenant's white-label preview/base domain (e.g. `cliniciq.com`). Use to build preview URLs. */
+  /** Tenant's white-label preview/base domain, e.g. `cliniciq.com`. */
   preview_domain?: string;
   /** KasmVNC URL for desktop templates. */
   desktop_url?: string;

package/src/resources/docker-deploy.test.ts

@@ -1,102 +0,0 @@
-import { beforeEach, describe, expect, it, vi } from "vitest";
-import type { HttpClient } from "../http.js";
-import { DockerDeploy } from "./docker-deploy.js";
-
-const mockGet = vi.fn();
-const mockPost = vi.fn();
-
-function makeHttp(): HttpClient {
-  const http = {} as HttpClient;
-  http.get = mockGet;
-  http.post = mockPost;
-  return http;
-}
-
-beforeEach(() => {
-  vi.clearAllMocks();
-});
-
-describe("DockerDeploy", () => {
-  it("lists Docker Deploy hosts by workspace", async () => {
-    mockGet.mockResolvedValue({
-      data: [
-        {
-          id: "ddh_123",
-          tenant_id: "ten_123",
-          workspace_id: "ws_123",
-          status: "bootstrapping",
-          appliance_status: "starting",
-          size: "medium",
-          region: "us",
-        },
-      ],
-    });
-
-    const hosts = await new DockerDeploy(makeHttp()).listHosts({
-      workspaceId: "ws_123",
-    });
-
-    expect(mockGet).toHaveBeenCalledWith("/docker-deploy/hosts", {
-      workspace_id: "ws_123",
-    });
-    expect(hosts[0]?.id).toBe("ddh_123");
-  });
-
-  it("ensures a workspace Docker Deploy host", async () => {
-    mockPost.mockResolvedValue({
-      host: {
-        id: "ddh_123",
-        tenant_id: "ten_123",
-        workspace_id: "ws_123",
-        status: "pending",
-        appliance_status: "not_installed",
-        size: "medium",
-        region: "us",
-      },
-      queued: true,
-    });
-
-    const result = await new DockerDeploy(makeHttp()).ensureHost({
-      workspaceId: "ws_123",
-    });
-
-    expect(mockPost).toHaveBeenCalledWith("/docker-deploy/hosts/ensure", {
-      workspace_id: "ws_123",
-    });
-    expect(result.queued).toBe(true);
-    expect(result.host.status).toBe("pending");
-  });
-
-  it("lists Docker Deploy templates", async () => {
-    mockGet.mockResolvedValue({
-      data: [
-        {
-          id: "nextjs-app",
-          name: "Next.js app",
-          description: "App router starter",
-        },
-      ],
-    });
-
-    const templates = await new DockerDeploy(makeHttp()).listTemplates();
-
-    expect(mockGet).toHaveBeenCalledWith("/docker-deploy/templates");
-    expect(templates[0]?.id).toBe("nextjs-app");
-  });
-
-  it("gets a Docker Deploy template", async () => {
-    mockGet.mockResolvedValue({
-      template: {
-        id: "compose-full-stack",
-        name: "Compose full stack",
-      },
-    });
-
-    const template = await new DockerDeploy(makeHttp()).getTemplate("compose-full-stack");
-
-    expect(mockGet).toHaveBeenCalledWith(
-      "/docker-deploy/templates/compose-full-stack",
-    );
-    expect(template.id).toBe("compose-full-stack");
-  });
-});

package/src/resources/docker-deploy.ts

@@ -1,183 +0,0 @@
-import type { HttpClient } from "../http.js";
-
-export type DockerDeployHostId = string & {
-  readonly __brand: "DockerDeployHostId";
-};
-
-export type DockerDeployHostStatus =
-  | "pending"
-  | "provisioning"
-  | "bootstrapping"
-  | "active"
-  | "degraded"
-  | "suspended"
-  | "retired"
-  | "error";
-
-export type DockerDeployApplianceStatus =
-  | "not_installed"
-  | "installing"
-  | "starting"
-  | "healthy"
-  | "unhealthy"
-  | "unknown";
-
-export interface DockerDeployHostData {
-  id: DockerDeployHostId;
-  tenant_id: string;
-  workspace_id: string;
-  external_workspace_id?: string | null;
-  computer_id?: string | null;
-  fleet_node_id?: string | null;
-  status: DockerDeployHostStatus;
-  size: string;
-  region: string;
-  portal_domain?: string | null;
-  runtime_base_url?: string | null;
-  agent_base_url?: string | null;
-  appliance_image?: string | null;
-  appliance_version?: string | null;
-  appliance_status: DockerDeployApplianceStatus;
-  agent_last_seen_at?: string | null;
-  metadata?: Record<string, unknown>;
-  created_at?: string;
-  updated_at?: string;
-}
-
-export interface DockerDeployHostListParams {
-  workspace_id?: string;
-  workspaceId?: string;
-}
-
-export interface DockerDeployHostEnsureParams {
-  workspace_id?: string;
-  workspaceId?: string;
-  external_workspace_id?: string;
-  externalWorkspaceId?: string;
-}
-
-export interface DockerDeployHostListResponse {
-  data?: DockerDeployHostData[];
-  hosts?: DockerDeployHostData[];
-}
-
-export interface DockerDeployHostResponse {
-  data?: DockerDeployHostData;
-  host?: DockerDeployHostData;
-  queued?: boolean;
-}
-
-export interface DockerDeployTemplate {
-  id: string;
-  name: string;
-  description?: string;
-  category?: string;
-  runtime?: string;
-  tags?: string[];
-  metadata?: Record<string, unknown>;
-  [key: string]: unknown;
-}
-
-export interface DockerDeployTemplateListResponse {
-  data?: DockerDeployTemplate[];
-  templates?: DockerDeployTemplate[];
-}
-
-export interface DockerDeployTemplateResponse {
-  data?: DockerDeployTemplate;
-  template?: DockerDeployTemplate;
-}
-
-function workspaceId(params?: DockerDeployHostListParams): string | undefined {
-  return params?.workspace_id ?? params?.workspaceId;
-}
-
-function ensureBody(params: DockerDeployHostEnsureParams): Record<string, string> {
-  const body: Record<string, string> = {};
-  const id = params.workspace_id ?? params.workspaceId;
-  const externalId = params.external_workspace_id ?? params.externalWorkspaceId;
-  if (id) body.workspace_id = id;
-  if (externalId) body.external_workspace_id = externalId;
-  return body;
-}
-
-function unwrapHost(response: DockerDeployHostResponse): DockerDeployHostData {
-  const host = response.data ?? response.host;
-  if (!host) {
-    throw new Error("Docker Deploy host response was empty.");
-  }
-  return host;
-}
-
-function unwrapTemplates(response: DockerDeployTemplateListResponse): DockerDeployTemplate[] {
-  return response.data ?? response.templates ?? [];
-}
-
-function unwrapTemplate(response: DockerDeployTemplateResponse): DockerDeployTemplate {
-  const template = response.data ?? response.template;
-  if (!template) {
-    throw new Error("Docker Deploy template response was empty.");
-  }
-  return template;
-}
-
-export class DockerDeploy {
-  constructor(private readonly http: HttpClient) {}
-
-  /**
-   * List Docker Deploy appliance hosts scoped to the current tenant.
-   *
-   * Pass a workspace ID to inspect the dedicated always-on appliance machine
-   * for one white-label workspace.
-   */
-  async listHosts(
-    params: DockerDeployHostListParams = {},
-  ): Promise<DockerDeployHostData[]> {
-    const res = await this.http.get<DockerDeployHostListResponse>(
-      "/docker-deploy/hosts",
-      { workspace_id: workspaceId(params) },
-    );
-    return res.data ?? res.hosts ?? [];
-  }
-
-  /**
-   * Ensure a workspace has its dedicated Docker Deploy appliance host.
-   *
-   * The host may still be `pending`, `provisioning`, or `bootstrapping` after
-   * this call. Treat `status === "active"` and `appliance_status === "healthy"`
-   * as the ready condition before sending app/container traffic to it.
-   */
-  async ensureHost(
-    params: DockerDeployHostEnsureParams = {},
-  ): Promise<{ host: DockerDeployHostData; queued: boolean }> {
-    const res = await this.http.post<DockerDeployHostResponse>(
-      "/docker-deploy/hosts/ensure",
-      ensureBody(params),
-    );
-    return { host: unwrapHost(res), queued: res.queued ?? false };
-  }
-
-  /** Fetch one Docker Deploy host by ID. */
-  async getHost(hostId: string): Promise<DockerDeployHostData> {
-    const res = await this.http.get<DockerDeployHostResponse>(
-      `/docker-deploy/hosts/${hostId}`,
-    );
-    return unwrapHost(res);
-  }
-
-  /** List Docker Deploy starter templates. */
-  async listTemplates(): Promise<DockerDeployTemplate[]> {
-    const res = await this.http.get<DockerDeployTemplateListResponse>(
-      "/docker-deploy/templates",
-    );
-    return unwrapTemplates(res);
-  }
-
-  /** Fetch one Docker Deploy starter template by ID. */
-  async getTemplate(templateId: string): Promise<DockerDeployTemplate> {
-    const res = await this.http.get<DockerDeployTemplateResponse>(
-      `/docker-deploy/templates/${encodeURIComponent(templateId)}`,
-    );
-    return unwrapTemplate(res);
-  }
-}