Merge pull request #674 from Ajibose/test/webhook-signature-timing-safe-comparison

test(webhooks): add unit tests for verifyWebhookSignature timing-safe comparison

Author: Chucks1093

src/modules/webhooks/webhook-signature.utils.test.ts

@@ -0,0 +1,71 @@
+import crypto from 'crypto';
+import { verifyWebhookSignature } from './webhook-signature.utils';
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+const secret = 'test-webhook-signing-secret';
+const payload = Buffer.from(JSON.stringify({ event_type: 'buy', amount: '10' }));
+
+function computeValidHeader(): string {
+  const hex = crypto.createHmac('sha256', secret).update(payload).digest('hex');
+  return `sha256=${hex}`;
+}
+
+function flipHexChar(char: string): string {
+  return char === '0' ? '1' : '0';
+}
+
+// ── Tests ─────────────────────────────────────────────────────────────────────
+
+describe('verifyWebhookSignature', () => {
+  it('returns true for a valid signature', () => {
+    expect(verifyWebhookSignature(payload, computeValidHeader(), secret)).toBe(true);
+  });
+
+  it('returns false when the signature differs in the last character', () => {
+    const header = computeValidHeader();
+    const tampered =
+      header.slice(0, -1) + flipHexChar(header[header.length - 1]);
+
+    expect(verifyWebhookSignature(payload, tampered, secret)).toBe(false);
+  });
+
+  it('returns false when the signature differs in the first character', () => {
+    const header = computeValidHeader();
+    const prefix = 'sha256=';
+    const firstHexChar = header[prefix.length];
+    const tampered =
+      prefix + flipHexChar(firstHexChar) + header.slice(prefix.length + 1);
+
+    expect(verifyWebhookSignature(payload, tampered, secret)).toBe(false);
+  });
+
+  it('returns false without throwing when the signature is one character shorter than expected', () => {
+    const header = computeValidHeader();
+    const shortened = header.slice(0, -1);
+
+    expect(() => verifyWebhookSignature(payload, shortened, secret)).not.toThrow();
+    expect(verifyWebhookSignature(payload, shortened, secret)).toBe(false);
+  });
+
+  it('returns false without throwing when the signature is one character longer than expected', () => {
+    const header = computeValidHeader();
+    const lengthened = `${header}a`;
+
+    expect(() => verifyWebhookSignature(payload, lengthened, secret)).not.toThrow();
+    expect(verifyWebhookSignature(payload, lengthened, secret)).toBe(false);
+  });
+
+  it('returns false without throwing for a malformed header', () => {
+    expect(() =>
+      verifyWebhookSignature(payload, 'not-a-valid-header', secret)
+    ).not.toThrow();
+    expect(verifyWebhookSignature(payload, 'not-a-valid-header', secret)).toBe(
+      false
+    );
+  });
+
+  it('returns false for an empty header', () => {
+    expect(verifyWebhookSignature(payload, '', secret)).toBe(false);
+  });
+});

src/modules/webhooks/webhook-signature.utils.ts

@@ -0,0 +1,33 @@
+import crypto from 'crypto';
+
+const SIGNATURE_HEADER_PATTERN = /^sha256=([0-9a-f]+)$/i;
+
+/**
+ * Verifies an incoming webhook's `sha256=<hex>` HMAC signature header against
+ * the raw request payload using a constant-time comparison.
+ */
+export function verifyWebhookSignature(
+  payload: Buffer,
+  header: string,
+  secret: string
+): boolean {
+  if (!header) return false;
+
+  const match = SIGNATURE_HEADER_PATTERN.exec(header.trim());
+  if (!match) return false;
+
+  const providedSignature = match[1];
+  const expectedSignature = crypto
+    .createHmac('sha256', secret)
+    .update(payload)
+    .digest('hex');
+
+  const providedBuffer = Buffer.from(providedSignature, 'utf8');
+  const expectedBuffer = Buffer.from(expectedSignature, 'utf8');
+
+  if (providedBuffer.length !== expectedBuffer.length) {
+    return false;
+  }
+
+  return crypto.timingSafeEqual(providedBuffer, expectedBuffer);
+}