feat: add webhook signing and verification helper to sdk

docs/webhooks.md

@@ -0,0 +1,21 @@
+# Webhook Signature Verification
+
+Stellar Pay signs webhook payloads using HMAC-SHA256 and includes the result in the `x-stellarpay-signature` header.
+
+## How it works
+
+1. Payload is converted to a string
+2. HMAC-SHA256 is generated using the merchant secret
+3. Signature is sent in `x-stellarpay-signature` header
+
+## Verification Example
+
+```ts
+import { verifyWebhookSignature } from '@stellar-pay/sdk-js';
+
+const isValid = verifyWebhookSignature(rawBody, merchantSecret, signatureHeader);
+
+if (!isValid) {
+  throw new Error('Invalid webhook signature');
+}
+```

packages/sdk-js/package.json

@@ -13,6 +13,7 @@
     "lint": "eslint \"src/**/*.ts\""
   },
   "devDependencies": {
+    "@types/node": "^22.10.0",
     "tsup": "^8.0.0",
     "typescript": "^5.0.0"
   }

packages/sdk-js/src/index.ts

@@ -0,0 +1 @@
+export * from './webhook-signature';

packages/sdk-js/src/webhook-signature.ts

@@ -0,0 +1,27 @@
+import { createHmac, timingSafeEqual } from 'node:crypto';
+
+/**
+ * Generate HMAC-SHA256 signature for webhook payload
+ */
+export function signWebhookPayload(payload: string, secret: string): string {
+  return createHmac('sha256', secret).update(payload, 'utf8').digest('hex');
+}
+
+/**
+ * Verify webhook signature securely
+ */
+export function verifyWebhookSignature(
+  payload: string,
+  secret: string,
+  signature: string,
+): boolean {
+  if (!signature) return false;
+
+  const expected = signWebhookPayload(payload, secret);
+
+  if (expected.length !== signature.length) {
+    return false;
+  }
+
+  return timingSafeEqual(Buffer.from(expected, 'utf8'), Buffer.from(signature, 'utf8'));
+}