@transloadit/convex 0.0.2 → 0.0.4

package/src/component/apiUtils.test.ts

@@ -1,10 +1,14 @@
 import { createHmac } from "node:crypto";
-import { describe, expect, test } from "vitest";
+import { describe, expect, test, vi } from "vitest";
 import {
   buildTransloaditParams,
+  buildWebhookQueueArgs,
+  handleWebhookRequest,
+  parseAndVerifyTransloaditWebhook,
+  parseTransloaditWebhook,
   signTransloaditParams,
   verifyWebhookSignature,
-} from "./apiUtils.js";
+} from "./apiUtils.ts";
 
 describe("apiUtils", () => {
   test("buildTransloaditParams requires templateId or steps", () => {
@@ -45,4 +49,193 @@ describe("apiUtils", () => {
 
     expect(verified).toBe(true);
   });
+
+  test("parseTransloaditWebhook returns payload and signature", async () => {
+    const payload = { ok: "ASSEMBLY_COMPLETED", assembly_id: "asm_123" };
+    const formData = new FormData();
+    formData.append("transloadit", JSON.stringify(payload));
+    formData.append("signature", "sha384:abc");
+
+    const request = new Request("http://localhost", {
+      method: "POST",
+      body: formData,
+    });
+
+    const result = await parseTransloaditWebhook(request);
+    expect(result.payload).toEqual(payload);
+    expect(result.rawBody).toBe(JSON.stringify(payload));
+    expect(result.signature).toBe("sha384:abc");
+  });
+
+  test("parseTransloaditWebhook throws on missing payload", async () => {
+    const request = new Request("http://localhost", {
+      method: "POST",
+      body: new FormData(),
+    });
+
+    await expect(parseTransloaditWebhook(request)).rejects.toThrow(
+      "Missing transloadit payload",
+    );
+  });
+
+  test("parseAndVerifyTransloaditWebhook verifies signature", async () => {
+    const payload = { ok: "ASSEMBLY_COMPLETED", assembly_id: "asm_123" };
+    const rawBody = JSON.stringify(payload);
+    const secret = "webhook-secret";
+    const digest = createHmac("sha384", secret).update(rawBody).digest("hex");
+    const formData = new FormData();
+    formData.append("transloadit", rawBody);
+    formData.append("signature", `sha384:${digest}`);
+
+    const request = new Request("http://localhost", {
+      method: "POST",
+      body: formData,
+    });
+
+    const parsed = await parseAndVerifyTransloaditWebhook(request, {
+      authSecret: secret,
+    });
+
+    expect(parsed.payload).toEqual(payload);
+    expect(parsed.verified).toBe(true);
+  });
+
+  test("parseAndVerifyTransloaditWebhook rejects invalid signature", async () => {
+    const payload = { ok: "ASSEMBLY_COMPLETED", assembly_id: "asm_123" };
+    const formData = new FormData();
+    formData.append("transloadit", JSON.stringify(payload));
+    formData.append("signature", "sha384:bad");
+
+    const request = new Request("http://localhost", {
+      method: "POST",
+      body: formData,
+    });
+
+    await expect(
+      parseAndVerifyTransloaditWebhook(request, {
+        authSecret: "secret",
+      }),
+    ).rejects.toThrow("Invalid Transloadit webhook signature");
+  });
+
+  test("buildWebhookQueueArgs returns webhook payload args", async () => {
+    const payload = { ok: "ASSEMBLY_COMPLETED", assembly_id: "asm_123" };
+    const rawBody = JSON.stringify(payload);
+    const secret = "webhook-secret";
+    const digest = createHmac("sha384", secret).update(rawBody).digest("hex");
+    const formData = new FormData();
+    formData.append("transloadit", rawBody);
+    formData.append("signature", `sha384:${digest}`);
+
+    const request = new Request("http://localhost", {
+      method: "POST",
+      body: formData,
+    });
+
+    const args = await buildWebhookQueueArgs(request, { authSecret: secret });
+    expect(args.payload).toEqual(payload);
+    expect(args.rawBody).toBe(rawBody);
+    expect(args.signature).toBe(`sha384:${digest}`);
+  });
+
+  test("buildWebhookQueueArgs can skip verification", async () => {
+    const payload = { ok: "ASSEMBLY_COMPLETED", assembly_id: "asm_123" };
+    const rawBody = JSON.stringify(payload);
+    const formData = new FormData();
+    formData.append("transloadit", rawBody);
+
+    const request = new Request("http://localhost", {
+      method: "POST",
+      body: formData,
+    });
+
+    const args = await buildWebhookQueueArgs(request, {
+      authSecret: "secret",
+      requireSignature: false,
+    });
+    expect(args.payload).toEqual(payload);
+    expect(args.rawBody).toBe(rawBody);
+    expect(args.signature).toBeUndefined();
+  });
+
+  test("handleWebhookRequest queues webhook by default", async () => {
+    const payload = { ok: "ASSEMBLY_COMPLETED", assembly_id: "asm_123" };
+    const rawBody = JSON.stringify(payload);
+    const formData = new FormData();
+    formData.append("transloadit", rawBody);
+    formData.append("signature", "sha384:abc");
+
+    const request = new Request("http://localhost", {
+      method: "POST",
+      body: formData,
+    });
+    const runAction = vi.fn().mockResolvedValue(null);
+
+    const response = await handleWebhookRequest(request, {
+      runAction,
+    });
+
+    expect(runAction).toHaveBeenCalledWith({
+      payload,
+      rawBody,
+      signature: "sha384:abc",
+    });
+    expect(response.status).toBe(202);
+  });
+
+  test("handleWebhookRequest supports sync mode with verification", async () => {
+    const payload = { ok: "ASSEMBLY_COMPLETED", assembly_id: "asm_123" };
+    const rawBody = JSON.stringify(payload);
+    const secret = "webhook-secret";
+    const digest = createHmac("sha384", secret).update(rawBody).digest("hex");
+    const formData = new FormData();
+    formData.append("transloadit", rawBody);
+    formData.append("signature", `sha384:${digest}`);
+
+    const request = new Request("http://localhost", {
+      method: "POST",
+      body: formData,
+    });
+    const runAction = vi.fn().mockResolvedValue(null);
+
+    const response = await handleWebhookRequest(request, {
+      mode: "sync",
+      runAction,
+      requireSignature: true,
+      authSecret: secret,
+    });
+
+    expect(runAction).toHaveBeenCalledWith({
+      payload,
+      rawBody,
+      signature: `sha384:${digest}`,
+    });
+    expect(response.status).toBe(204);
+  });
+
+  test("handleWebhookRequest honors a custom response status", async () => {
+    const payload = { ok: "ASSEMBLY_COMPLETED", assembly_id: "asm_123" };
+    const rawBody = JSON.stringify(payload);
+    const formData = new FormData();
+    formData.append("transloadit", rawBody);
+    formData.append("signature", "sha384:abc");
+
+    const request = new Request("http://localhost", {
+      method: "POST",
+      body: formData,
+    });
+    const runAction = vi.fn().mockResolvedValue(null);
+
+    const response = await handleWebhookRequest(request, {
+      runAction,
+      responseStatus: 299,
+    });
+
+    expect(runAction).toHaveBeenCalledWith({
+      payload,
+      rawBody,
+      signature: "sha384:abc",
+    });
+    expect(response.status).toBe(299);
+  });
 });

package/src/component/apiUtils.ts

@@ -1,3 +1,8 @@
+import { signParams, verifyWebhookSignature } from "@transloadit/utils";
+import type { AssemblyStatusResults } from "@transloadit/zod/v3/assemblyStatus";
+import type { AssemblyInstructionsInput } from "@transloadit/zod/v3/template";
+import { transloaditError } from "../shared/errors.ts";
+
 export interface TransloaditAuthConfig {
   authKey: string;
   authSecret: string;
@@ -6,8 +11,8 @@ export interface TransloaditAuthConfig {
 export interface BuildParamsOptions {
   authKey: string;
   templateId?: string;
-  steps?: Record<string, unknown>;
-  fields?: Record<string, unknown>;
+  steps?: AssemblyInstructionsInput["steps"];
+  fields?: AssemblyInstructionsInput["fields"];
   notifyUrl?: string;
   numExpectedUploadFiles?: number;
   expires?: string;
@@ -23,7 +28,10 @@ export function buildTransloaditParams(
   options: BuildParamsOptions,
 ): BuildParamsResult {
   if (!options.templateId && !options.steps) {
-    throw new Error("Provide either templateId or steps to create an Assembly");
+    throw transloaditError(
+      "createAssembly",
+      "Provide either templateId or steps to create an Assembly",
+    );
   }
 
   const auth: Record<string, string> = {
@@ -59,90 +67,140 @@ export function buildTransloaditParams(
   };
 }
 
-async function hmacHex(
-  algorithm: "SHA-384" | "SHA-1",
-  key: string,
-  data: string,
-): Promise<string> {
-  if (globalThis.crypto?.subtle) {
-    const encoder = new TextEncoder();
-    const cryptoKey = await globalThis.crypto.subtle.importKey(
-      "raw",
-      encoder.encode(key),
-      { name: "HMAC", hash: { name: algorithm } },
-      false,
-      ["sign"],
-    );
-    const signature = await globalThis.crypto.subtle.sign(
-      "HMAC",
-      cryptoKey,
-      encoder.encode(data),
-    );
-    const bytes = new Uint8Array(signature);
-    return Array.from(bytes)
-      .map((byte) => byte.toString(16).padStart(2, "0"))
-      .join("");
-  }
-
-  const { createHmac } = await import("node:crypto");
-  return createHmac(algorithm.replace("-", "").toLowerCase(), key)
-    .update(data)
-    .digest("hex");
-}
-
 export async function signTransloaditParams(
   paramsString: string,
   authSecret: string,
 ): Promise<string> {
-  const signature = await hmacHex("SHA-384", authSecret, paramsString);
-  return `sha384:${signature}`;
+  return signParams(paramsString, authSecret, "sha384");
 }
 
-function safeCompare(a: string, b: string): boolean {
-  if (a.length !== b.length) return false;
-  let mismatch = 0;
-  for (let i = 0; i < a.length; i += 1) {
-    mismatch |= a.charCodeAt(i) ^ b.charCodeAt(i);
+export type ParsedWebhookRequest = {
+  payload: unknown;
+  rawBody: string;
+  signature?: string;
+};
+
+export type VerifiedWebhookRequest = ParsedWebhookRequest & {
+  verified: boolean;
+};
+
+export async function parseTransloaditWebhook(
+  request: Request,
+): Promise<ParsedWebhookRequest> {
+  const formData = await request.formData();
+  const rawPayload = formData.get("transloadit");
+  const signature = formData.get("signature");
+
+  if (typeof rawPayload !== "string") {
+    throw transloaditError("webhook", "Missing transloadit payload");
   }
-  return mismatch === 0;
+
+  return {
+    payload: JSON.parse(rawPayload),
+    rawBody: rawPayload,
+    signature: typeof signature === "string" ? signature : undefined,
+  };
 }
 
-export async function verifyWebhookSignature(options: {
-  rawBody: string;
-  signatureHeader?: string;
-  authSecret: string;
-}): Promise<boolean> {
-  if (!options.signatureHeader) return false;
+export async function parseAndVerifyTransloaditWebhook(
+  request: Request,
+  options: {
+    authSecret: string;
+    requireSignature?: boolean;
+  },
+): Promise<VerifiedWebhookRequest> {
+  const parsed = await parseTransloaditWebhook(request);
+  const authSecret = options.authSecret;
+  if (!authSecret) {
+    throw transloaditError(
+      "webhook",
+      "Missing authSecret for webhook verification",
+    );
+  }
+  const verified = await verifyWebhookSignature({
+    rawBody: parsed.rawBody,
+    signatureHeader: parsed.signature,
+    authSecret,
+  });
+
+  if (options.requireSignature ?? true) {
+    if (!verified) {
+      throw transloaditError(
+        "webhook",
+        "Invalid Transloadit webhook signature",
+      );
+    }
+  }
 
-  const signatureHeader = options.signatureHeader.trim();
-  if (!signatureHeader) return false;
+  return { ...parsed, verified };
+}
 
-  const [prefix, sig] = signatureHeader.includes(":")
-    ? (signatureHeader.split(":") as [string, string])
-    : ["sha1", signatureHeader];
+export async function buildWebhookQueueArgs(
+  request: Request,
+  options: {
+    authSecret: string;
+    requireSignature?: boolean;
+  },
+): Promise<ParsedWebhookRequest> {
+  if (options.requireSignature === false) {
+    return parseTransloaditWebhook(request);
+  }
 
-  const normalized = prefix.toLowerCase();
-  const algorithm = normalized === "sha384" ? "SHA-384" : "SHA-1";
+  const parsed = await parseAndVerifyTransloaditWebhook(request, options);
+  return {
+    payload: parsed.payload,
+    rawBody: parsed.rawBody,
+    signature: parsed.signature,
+  };
+}
 
-  if (normalized !== "sha384" && normalized !== "sha1") {
-    return false;
-  }
+export type WebhookActionArgs = {
+  payload: unknown;
+  rawBody?: string;
+  signature?: string;
+};
 
-  const expected = await hmacHex(
-    algorithm,
-    options.authSecret,
-    options.rawBody,
-  );
-  return safeCompare(expected, sig);
+export async function handleWebhookRequest(
+  request: Request,
+  options: {
+    mode?: "queue" | "sync";
+    runAction: (args: WebhookActionArgs) => Promise<unknown>;
+    requireSignature?: boolean;
+    authSecret?: string;
+    responseStatus?: number;
+  },
+): Promise<Response> {
+  const mode = options.mode ?? "queue";
+  const requireSignature = options.requireSignature ?? false;
+
+  const parsed = requireSignature
+    ? await parseAndVerifyTransloaditWebhook(request, {
+        authSecret: options.authSecret ?? "",
+        requireSignature: true,
+      })
+    : await parseTransloaditWebhook(request);
+
+  await options.runAction({
+    payload: parsed.payload,
+    rawBody: parsed.rawBody,
+    signature: parsed.signature,
+  });
+
+  const status = options.responseStatus ?? (mode === "sync" ? 204 : 202);
+  return new Response(null, { status });
 }
 
+export { verifyWebhookSignature };
+
+export type AssemblyResult = AssemblyStatusResults[string][number];
+
 export type AssemblyResultRecord = {
   stepName: string;
-  result: Record<string, unknown>;
+  result: AssemblyResult;
 };
 
 export function flattenResults(
-  results: Record<string, Array<Record<string, unknown>>> | undefined,
+  results: AssemblyStatusResults | undefined,
 ): AssemblyResultRecord[] {
   if (!results) return [];
   const output: AssemblyResultRecord[] = [];