Merge pull request Junirezz#469 from UzyKhs/fix/440-442-443-445-backend-export-webhook-prisma-polling

Fix backend export, webhook verification, Prisma metrics, and polling tests

Author: Junirezz

backend/docs/WEBHOOK_SIGNATURES.md

@@ -0,0 +1,77 @@
+# Webhook Signature Verification
+
+YieldVault signs outbound webhook payloads with `HMAC-SHA256` whenever a webhook endpoint is configured with a secret.
+
+## Signature Contract
+
+- Header: `X-YieldVault-Signature`
+- Algorithm: `HMAC-SHA256`
+- Encoding: lowercase hexadecimal
+- Input: the exact JSON request body sent by YieldVault
+
+For a delivery body like:
+
+```json
+{
+  "eventType": "transaction.deposit.created",
+  "sentAt": "2026-05-26T00:00:00.000Z",
+  "payload": {
+    "transactionId": "tx_123",
+    "amount": "125.00",
+    "asset": "USDC",
+    "walletAddress": "G...",
+    "transactionHash": "0xabc",
+    "status": "pending",
+    "timestamp": "2026-05-26T00:00:00.000Z"
+  }
+}
+```
+
+Compute the signature from the raw body bytes using your shared secret:
+
+```ts
+import crypto from 'crypto';
+
+function verifyYieldVaultWebhook(rawBody: string, secret: string, providedSignature: string) {
+  const expectedSignature = crypto
+    .createHmac('sha256', secret)
+    .update(rawBody)
+    .digest('hex');
+
+  return crypto.timingSafeEqual(
+    Buffer.from(providedSignature, 'utf8'),
+    Buffer.from(expectedSignature, 'utf8'),
+  );
+}
+```
+
+## Test Endpoint
+
+Use `POST /webhooks/verify` before going live to confirm your secret produces the expected signature.
+
+Request body:
+
+```json
+{
+  "secret": "your-shared-secret",
+  "payload": {
+    "eventType": "transaction.deposit.created",
+    "payload": {
+      "transactionId": "tx_123"
+    }
+  },
+  "signature": "optional-signature-to-verify"
+}
+```
+
+Response body:
+
+```json
+{
+  "algorithm": "HMAC-SHA256",
+  "signature": "computed-hex-signature",
+  "verified": true
+}
+```
+
+If you omit `signature`, YieldVault returns the computed signature and sets `verified` to `null`.

backend/package-lock.json

@@ -32,11 +32,13 @@
     "@opentelemetry/sdk-node": "^0.218.0",
     "@opentelemetry/semantic-conventions": "^1.41.1",
     "@prisma/client": "^5.10.0",
+    "@prisma/instrumentation": "^7.8.0",
     "cors": "^2.8.6",
     "decimal.js": "^10.6.0",
     "dotenv": "^16.3.1",
     "express": "^4.18.2",
     "express-rate-limit": "^7.0.0",
+    "fast-check": "^4.8.0",
     "ioredis": "^5.10.1",
     "node-cache": "^5.1.2",
     "prom-client": "^15.1.3",

backend/package.json

@@ -25,16 +25,23 @@ describe('Admin backend features', () => {
         status: 200,
         text: async () => 'ok',
       } as Response);
+    const secret = 'super-secret-webhook-key';
 
     const webhookResponse = await request(app)
       .post('/admin/webhooks')
       .set(authHeader)
       .send({
         url: 'https://example.com/webhook',
         eventTypes: ['transaction.deposit.created'],
+        secret,
       });
 
     expect(webhookResponse.status).toBe(201);
+    expect(webhookResponse.body.endpoint.secret).toBeUndefined();
+    expect(webhookResponse.body.endpoint.hasSecret).toBe(true);
+
+    const previousAllowlistEnabled = process.env.ALLOWLIST_ENABLED;
+    process.env.ALLOWLIST_ENABLED = 'false';
 
     const depositResponse = await request(app)
       .post('/api/v1/vault/deposits')
@@ -44,6 +51,12 @@ describe('Admin backend features', () => {
         walletAddress: 'GABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz234567',
       });
 
+    if (typeof previousAllowlistEnabled === 'string') {
+      process.env.ALLOWLIST_ENABLED = previousAllowlistEnabled;
+    } else {
+      delete process.env.ALLOWLIST_ENABLED;
+    }
+
     expect(depositResponse.status).toBe(201);
 
     await new Promise((resolve) => setTimeout(resolve, 30));
@@ -55,10 +68,58 @@ describe('Admin backend features', () => {
     expect(deliveriesResponse.status).toBe(200);
     expect(deliveriesResponse.body.deliveries.length).toBeGreaterThan(0);
     expect(deliveriesResponse.body.deliveries[0].eventType).toBe('transaction.deposit.created');
+    expect(fetchMock).toHaveBeenCalledWith(
+      'https://example.com/webhook',
+      expect.objectContaining({
+        headers: expect.objectContaining({
+          'X-YieldVault-Signature': expect.any(String),
+        }),
+      }),
+    );
+
+    const listResponse = await request(app)
+      .get('/admin/webhooks')
+      .set(authHeader);
+
+    expect(listResponse.status).toBe(200);
+    expect(listResponse.body.endpoints[0].secret).toBeUndefined();
+    expect(listResponse.body.endpoints[0].hasSecret).toBe(true);
 
     fetchMock.mockRestore();
   });
 
+  it('verifies webhook signatures without exposing secrets', async () => {
+    const payload = {
+      eventType: 'transaction.deposit.created',
+      payload: {
+        transactionId: 'tx-verify-1',
+      },
+    };
+
+    const signatureResponse = await request(app)
+      .post('/webhooks/verify')
+      .send({
+        secret: 'verify-secret',
+        payload,
+      });
+
+    expect(signatureResponse.status).toBe(200);
+    expect(signatureResponse.body.algorithm).toBe('HMAC-SHA256');
+    expect(signatureResponse.body.signature).toHaveLength(64);
+    expect(signatureResponse.body.verified).toBeNull();
+
+    const verificationResponse = await request(app)
+      .post('/webhooks/verify')
+      .send({
+        secret: 'verify-secret',
+        payload,
+        signature: signatureResponse.body.signature,
+      });
+
+    expect(verificationResponse.status).toBe(200);
+    expect(verificationResponse.body.verified).toBe(true);
+  });
+
   it('returns audit logs for admin actions', async () => {
     const cacheStats = await request(app)
       .get('/admin/cache/stats')