@carts1024/velo-sdk 0.1.0-alpha.1

package/src/webhooks.test.ts

@@ -0,0 +1,185 @@
+import crypto from "crypto";
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { Velo } from "./client.ts";
+import { VeloWebhookSignatureVerificationError } from "./errors.ts";
+import { verifyWebhookSignature } from "./webhooks.ts";
+
+function generateTestSignatureHeader(payload: string, secret: string, timestamp: number): string {
+  const signaturePayload = `${timestamp}.${payload}`;
+  const hmac = crypto.createHmac("sha256", secret);
+  hmac.update(signaturePayload);
+  const hash = hmac.digest("hex");
+  return `t=${timestamp},v1=${hash}`;
+}
+
+test("verifyWebhookSignature parses valid signature and payload", async () => {
+  const secret = "whsec_testsecret12345";
+  const payload = JSON.stringify({
+    id: "evt_123",
+    type: "payment.succeeded",
+    test: true,
+    sentAt: new Date().toISOString(),
+    project: {
+      id: "proj_123",
+      registryProjectId: "reg_123",
+      name: "Test Project",
+      slug: "test-project",
+    },
+    paymentIntent: {
+      id: "pi_123",
+      amount: "10.00",
+      asset: "USDC",
+      receiverAddress: "GBA...",
+      merchantName: "Merchant Name",
+      description: "Test description",
+      status: "paid",
+      createdAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+    },
+  });
+  const timestamp = Math.floor(Date.now() / 1000);
+  const signatureHeader = generateTestSignatureHeader(payload, secret, timestamp);
+
+  // Directly calling verifyWebhookSignature helper
+  const event = await verifyWebhookSignature({
+    payload,
+    signature: signatureHeader,
+    secret,
+  });
+
+  assert.equal(event.id, "evt_123");
+  assert.equal(event.type, "payment.succeeded");
+  assert.equal(event.test, true);
+  if (event.type === "payment.succeeded") {
+    assert.equal(event.paymentIntent.id, "pi_123");
+    assert.equal(event.paymentIntent.amount, "10.00");
+  } else {
+    assert.fail("Event type should be payment.succeeded");
+  }
+
+  // Testing Velo static verification
+  const staticEvent = await Velo.webhooks.verify({
+    payload,
+    signature: signatureHeader,
+    secret,
+  });
+  assert.equal(staticEvent.id, "evt_123");
+
+  // Testing Velo instance verification
+  const velo = new Velo({ apiKey: "test-key" });
+  const instanceEvent = await velo.webhooks.verify({
+    payload,
+    signature: signatureHeader,
+    secret,
+  });
+  assert.equal(instanceEvent.id, "evt_123");
+});
+
+test("verifyWebhookSignature rejects missing signature header", async () => {
+  const secret = "whsec_testsecret12345";
+  const payload = JSON.stringify({ type: "payment.succeeded" });
+
+  await assert.rejects(
+    () => verifyWebhookSignature({ payload, signature: null, secret }),
+    (err: unknown) => {
+      assert.equal(err instanceof VeloWebhookSignatureVerificationError, true);
+      assert.equal(
+        (err as VeloWebhookSignatureVerificationError).message,
+        "Missing signature header",
+      );
+      return true;
+    },
+  );
+});
+
+test("verifyWebhookSignature rejects malformed headers", async () => {
+  const secret = "whsec_testsecret12345";
+  const payload = JSON.stringify({ type: "payment.succeeded" });
+
+  await assert.rejects(
+    () => verifyWebhookSignature({ payload, signature: "invalid-header", secret }),
+    (err: unknown) => {
+      assert.equal(err instanceof VeloWebhookSignatureVerificationError, true);
+      assert.equal(
+        (err as VeloWebhookSignatureVerificationError).message,
+        "Invalid signature header format",
+      );
+      return true;
+    },
+  );
+
+  await assert.rejects(
+    () => verifyWebhookSignature({ payload, signature: "t=123", secret }),
+    (err: unknown) => {
+      assert.equal(err instanceof VeloWebhookSignatureVerificationError, true);
+      assert.equal(
+        (err as VeloWebhookSignatureVerificationError).message,
+        "Invalid signature header format",
+      );
+      return true;
+    },
+  );
+});
+
+test("verifyWebhookSignature rejects expired timestamps", async () => {
+  const secret = "whsec_testsecret12345";
+  const payload = JSON.stringify({ type: "payment.succeeded" });
+  const timestamp = Math.floor(Date.now() / 1000) - 600; // 10 minutes ago (tolerance default is 5 mins)
+  const signatureHeader = generateTestSignatureHeader(payload, secret, timestamp);
+
+  await assert.rejects(
+    () => verifyWebhookSignature({ payload, signature: signatureHeader, secret }),
+    (err: unknown) => {
+      assert.equal(err instanceof VeloWebhookSignatureVerificationError, true);
+      assert.match((err as VeloWebhookSignatureVerificationError).message, /timestamp expired/);
+      return true;
+    },
+  );
+});
+
+test("verifyWebhookSignature rejects future timestamps", async () => {
+  const secret = "whsec_testsecret12345";
+  const payload = JSON.stringify({ type: "payment.succeeded" });
+  const timestamp = Math.floor(Date.now() / 1000) + 600; // 10 minutes in the future
+  const signatureHeader = generateTestSignatureHeader(payload, secret, timestamp);
+
+  await assert.rejects(
+    () => verifyWebhookSignature({ payload, signature: signatureHeader, secret }),
+    (err: unknown) => {
+      assert.equal(err instanceof VeloWebhookSignatureVerificationError, true);
+      assert.match((err as VeloWebhookSignatureVerificationError).message, /timestamp expired/);
+      return true;
+    },
+  );
+});
+
+test("verifyWebhookSignature rejects signature mismatch", async () => {
+  const secret = "whsec_testsecret12345";
+  const payload = JSON.stringify({ type: "payment.succeeded" });
+  const timestamp = Math.floor(Date.now() / 1000);
+  const signatureHeader = generateTestSignatureHeader(payload, secret, timestamp);
+
+  // Mismatched secret
+  await assert.rejects(
+    () =>
+      verifyWebhookSignature({ payload, signature: signatureHeader, secret: "whsec_wrongsecret" }),
+    (err: unknown) => {
+      assert.equal(err instanceof VeloWebhookSignatureVerificationError, true);
+      assert.equal((err as VeloWebhookSignatureVerificationError).message, "Signature mismatch");
+      return true;
+    },
+  );
+
+  // Mismatched payload (tampering)
+  await assert.rejects(
+    () =>
+      verifyWebhookSignature({ payload: payload + "altered", signature: signatureHeader, secret }),
+    (err: unknown) => {
+      assert.equal(err instanceof VeloWebhookSignatureVerificationError, true);
+      assert.equal((err as VeloWebhookSignatureVerificationError).message, "Signature mismatch");
+      return true;
+    },
+  );
+});

package/src/webhooks.ts

@@ -0,0 +1,97 @@
+import type { WebhookEvent, VerifyWebhookParams } from "./types.ts";
+
+import { VeloWebhookSignatureVerificationError } from "./errors.ts";
+
+/**
+ * Verifies a Velo webhook signature using the Web Crypto API.
+ * This is fully compatible with both browser/Edge and Node.js environments.
+ * If signature verification fails, it throws a VeloWebhookSignatureVerificationError.
+ *
+ * @param params Object containing payload, signature, secret, and optional toleranceSeconds.
+ * @returns A promise resolving to the parsed and typed WebhookEvent.
+ * @throws {VeloWebhookSignatureVerificationError} If the verification fails.
+ */
+export async function verifyWebhookSignature(params: VerifyWebhookParams): Promise<WebhookEvent> {
+  const { payload, signature: signatureHeader, secret, toleranceSeconds = 300 } = params;
+
+  if (!signatureHeader) {
+    throw new VeloWebhookSignatureVerificationError("Missing signature header");
+  }
+
+  if (!secret) {
+    throw new VeloWebhookSignatureVerificationError("Missing webhook signing secret");
+  }
+
+  const parts = signatureHeader.split(",");
+  let timestampStr: string | undefined;
+  let signature: string | undefined;
+
+  for (const part of parts) {
+    const equalIndex = part.indexOf("=");
+    if (equalIndex === -1) continue;
+    const key = part.slice(0, equalIndex).trim();
+    const val = part.slice(equalIndex + 1).trim();
+
+    if (key === "t") timestampStr = val;
+    if (key === "v1") signature = val;
+  }
+
+  if (!timestampStr || !signature) {
+    throw new VeloWebhookSignatureVerificationError("Invalid signature header format");
+  }
+
+  const timestamp = parseInt(timestampStr, 10);
+  if (isNaN(timestamp)) {
+    throw new VeloWebhookSignatureVerificationError("Invalid timestamp in header");
+  }
+
+  // Check clock drift to prevent replay attacks
+  const now = Math.floor(Date.now() / 1000);
+  if (Math.abs(now - timestamp) > toleranceSeconds) {
+    throw new VeloWebhookSignatureVerificationError(
+      "Signature timestamp expired or from the future",
+    );
+  }
+
+  const signaturePayload = `${timestamp}.${payload}`;
+
+  try {
+    const encoder = new TextEncoder();
+    const secretKeyData = encoder.encode(secret);
+    const signaturePayloadData = encoder.encode(signaturePayload);
+
+    // Import secret key for HMAC SHA-256
+    const cryptoKey = await globalThis.crypto.subtle.importKey(
+      "raw",
+      secretKeyData,
+      { name: "HMAC", hash: "SHA-256" },
+      false,
+      ["sign"],
+    );
+
+    // Compute expected signature
+    const signatureBuffer = await globalThis.crypto.subtle.sign(
+      "HMAC",
+      cryptoKey,
+      signaturePayloadData,
+    );
+
+    // Convert to hexadecimal string
+    const hashArray = Array.from(new Uint8Array(signatureBuffer));
+    const expectedSignature = hashArray.map((b) => b.toString(16).padStart(2, "0")).join("");
+
+    if (signature !== expectedSignature) {
+      throw new VeloWebhookSignatureVerificationError("Signature mismatch");
+    }
+
+    const event = JSON.parse(payload) as WebhookEvent;
+
+    return event;
+  } catch (err: unknown) {
+    if (err instanceof VeloWebhookSignatureVerificationError) {
+      throw err;
+    }
+    const message = err instanceof Error ? err.message : String(err);
+    throw new VeloWebhookSignatureVerificationError(`Verification failed: ${message}`);
+  }
+}

package/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "@repo/typescript-config/base.json",
+  "compilerOptions": {
+    "allowImportingTsExtensions": true,
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "outDir": "dist"
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}