From 243bd0edf5ddd6b0b1f21ba9207e2b26637c6aa2 Mon Sep 17 00:00:00 2001
From: emmanuelStack <dpelectricsz@gmail.com>
Date: Thu, 25 Jun 2026 17:48:53 +0100
Subject: [PATCH] feat(backend): add cryptographic signature verification to
 Audit Logger

---
 PULL_REQUEST_DESCRIPTION.md               | 53 +++++---------
 backend/src/services/auditService.js      | 56 +++++++++++++-
 backend/src/services/auditService.test.js | 89 ++++++++++++++++++++++-
 3 files changed, 158 insertions(+), 40 deletions(-)

diff --git a/PULL_REQUEST_DESCRIPTION.md b/PULL_REQUEST_DESCRIPTION.md
index bb77565d..6ba89187 100644
--- a/PULL_REQUEST_DESCRIPTION.md
+++ b/PULL_REQUEST_DESCRIPTION.md
@@ -1,50 +1,31 @@
 # Pull Request Description
 
 ## Title
-`feat(frontend): improve accessibility, enable optimistic user permissions, and enhance network status dashboard controls`
+`feat(backend): add cryptographic signature verification to Audit Logger`
 
 ## Overview
-This PR introduces frontend accessibility enhancements, state refactoring, and polished visual micro-interactions across the Pluto dashboard framework. It successfully addresses four frontend tasks (#821, #822, #823, and #824) while ensuring total system compile stability.
-
----
+This PR implements cryptographic signature verification and payload integrity checks for the Audit Logger module during log retrieval. It enhances the platform's security posture and tamper-evidence guarantees, fulfilling the backend system optimization requirements.
 
 ## Detailed Changes
 
-### 1. Network Status Indicator (`ApiHealthBadge.tsx`)
-* **Interactive Controls**: Refactored the container from a passive `div` to a semantic `<button>` to enable keyboard focus and manual rechecking.
-* **Optimistic Update**: Transitioning immediately to a `"loading"` state upon mouse click or Enter keypress for a responsive feedback loop, before initiating the real backend health endpoint check.
-* **Advanced Accessibility (Screen Readers & Keyboard)**:
-  - Added descriptive `aria-live="polite"` tags to report status updates to screen readers dynamically.
-  - Linked detailed status/degradation alerts using `aria-describedby` referencing the hover/focus tooltip.
-  - Formulated precise dynamic `aria-label` definitions announcing the connection quality.
-  - Enabled tooltips on tab focus using standard Tailwind `group-focus-visible` styles.
-
-### 2. Premium User Permissions Manager (`UserPermissionsManager.tsx` & `settings/page.tsx`)
-* **Premium Settings Panel**: Integrated a new high-fidelity **Permissions & Team** tab under merchant settings complete with clean user group icons and layout selectors.
-* **Optimistic State Actions & Rollbacks**:
-  - Implemented persistent browser storage (`localStorage`) synced with memory.
-  - Invites, role transitions, and member revoking are computed **optimistically**. Rows update instantly in the UI with state snapshots saved beforehand.
-  - In the event of a simulated API failure, the component runs automatic rollback procedures to revert the UI state cleanly and prompts the user via toast notifications.
-* **Dynamic Animations**: 
-  - Integrated Framer Motion's `<AnimatePresence>` to animate layout shifts, spring updates, and fade transitions during addition, removal, or filtering of rows.
-
-### 3. Dashboard Webpack Compile Fix (`dashboard/page.tsx`)
-* Corrected a pre-existing webpack path resolution error where `dashboard/page.tsx` attempted to load `WithdrawModal` instead of `WithdrawalModal`. The build compiles cleanly with no fatal errors or runtime blockages.
-
-### 4. Code Cleanup & Lints (`WalletSelector.tsx`)
-* Removed an unused `useMemo` React import that triggered pre-existing linter warnings.
+### 1. Database Query Enhancements (`backend/src/services/auditService.js`)
+* Updated the SQL SELECT query in `getAuditLogs` to retrieve necessary integrity fields: `merchant_id`, `status`, `payload_hash`, and `signature`.
+* Preserved index utilization by ordering by `timestamp DESC` and filtering on `merchant_id` to prevent performance degradation on large tables.
 
----
+### 2. Dual-Layer Log Integrity Verification (`backend/src/services/auditService.js`)
+* Implemented payload reconstruction logic distinguishing between login attempt events and regular administrative events.
+* Added deterministic SHA-256 hash comparison against the stored `payload_hash` to detect any field tampering.
+* Implemented HMAC-SHA256 signature verification via `verifyAuditSignature` using constant-time comparison to guard against timing attacks.
+* Exposes `hash_verified` and `signature_verified` flags for each log entry.
+* Logs warnings/errors if any tampering is detected (e.g. hash or signature mismatch).
 
-## Verification & Build Log
-* **ESLint Check**: Passed with `✔ No ESLint warnings or errors`.
-* **Next.js Production Compilation**: Verified via `pnpm run build` compiling `20/20` pages successfully with zero failures.
+### 3. Comprehensive Unit Testing (`backend/src/services/auditService.test.js`)
+* Added unit tests covering:
+  - Verification of matching payload hashes and signatures.
+  - Tamper detection with mismatching hashes and signatures.
+  - Graceful handling of legacy unsigned logs or missing environment secrets.
 
 ---
 
 ## Linked Issues
-
-Closes #821  
-Closes #822  
-Closes #823  
-Closes #824  
+Closes #769
diff --git a/backend/src/services/auditService.js b/backend/src/services/auditService.js
index 9452a68f..8666a7d9 100644
--- a/backend/src/services/auditService.js
+++ b/backend/src/services/auditService.js
@@ -7,6 +7,7 @@ import {
   sanitizeAuditValue,
   signAuditPayload,
   validateAuditAction,
+  verifyAuditSignature,
 } from "../lib/audit-security.js";
 import fs from "node:fs";
 import path from "node:path";
@@ -144,7 +145,7 @@ export const auditService = {
     // Single query: window function returns the full-table count alongside
     // each row, eliminating the separate COUNT(*) round-trip (issue #770).
     const result = await pool.query(
-      `SELECT id, action, field_changed, old_value, new_value, ip_address, user_agent, timestamp,
+      `SELECT id, merchant_id, action, status, field_changed, old_value, new_value, ip_address, user_agent, timestamp, payload_hash, signature,
               COUNT(*) OVER() AS total_count
        FROM audit_logs
        WHERE merchant_id = $1
@@ -154,8 +155,57 @@ export const auditService = {
     );
 
     const totalCount = result.rows.length > 0 ? parseInt(result.rows[0].total_count, 10) : 0;
-    // Strip the synthetic total_count column from each returned row
-    const logs = result.rows.map(({ total_count: _tc, ...row }) => row);
+    // Strip the synthetic total_count column from each returned row and verify integrity
+    const logs = result.rows.map(({ total_count: _tc, ...row }) => {
+      const isLogin = row.action === "login";
+      const payload = isLogin
+        ? {
+            merchant_id: row.merchant_id || merchantId || null,
+            action: row.action,
+            status: row.status || null,
+            ip_address: row.ip_address || null,
+            user_agent: row.user_agent || null,
+            event_type: "login_attempt",
+          }
+        : {
+            merchant_id: row.merchant_id || merchantId || null,
+            action: row.action,
+            field_changed: row.field_changed || null,
+            old_value: row.old_value || null,
+            new_value: row.new_value || null,
+            ip_address: row.ip_address || null,
+            user_agent: row.user_agent || null,
+          };
+
+      let hash_verified = null;
+      let signature_verified = null;
+
+      if (row.payload_hash) {
+        const calculatedHash = hashAuditPayload(payload);
+        hash_verified = calculatedHash === row.payload_hash;
+        if (!hash_verified) {
+          console.error(`[auditService] Audit log hash mismatch (tampering detected) for ID: ${row.id}`);
+        }
+      }
+
+      const hasSecret = !!process.env.AUDIT_LOG_SIGNING_SECRET;
+      if (row.signature && hasSecret) {
+        signature_verified = verifyAuditSignature(payload, row.signature);
+        if (!signature_verified) {
+          console.error(`[auditService] Audit log signature verification failed (tampering detected) for ID: ${row.id}`);
+        }
+      } else if (row.signature && !hasSecret) {
+        signature_verified = null;
+      } else if (!row.signature) {
+        signature_verified = null;
+      }
+
+      return {
+        ...row,
+        hash_verified,
+        signature_verified,
+      };
+    });
 
     return {
       logs,
diff --git a/backend/src/services/auditService.test.js b/backend/src/services/auditService.test.js
index 4834514a..b2b91372 100644
--- a/backend/src/services/auditService.test.js
+++ b/backend/src/services/auditService.test.js
@@ -1,13 +1,14 @@
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import fs from "node:fs";
 
-const { mockQuery, mockIsRetryablePoolError, mockConsumeRateLimit, mockHashPayload, mockSignPayload, mockValidateAuditAction } = vi.hoisted(() => ({
+const { mockQuery, mockIsRetryablePoolError, mockConsumeRateLimit, mockHashPayload, mockSignPayload, mockValidateAuditAction, mockVerifySignature } = vi.hoisted(() => ({
   mockQuery: vi.fn(),
   mockIsRetryablePoolError: vi.fn(),
   mockConsumeRateLimit: vi.fn(),
   mockHashPayload: vi.fn(),
   mockSignPayload: vi.fn(),
   mockValidateAuditAction: vi.fn(() => true),
+  mockVerifySignature: vi.fn(),
 }));
 
 vi.mock("../lib/db.js", () => ({
@@ -23,6 +24,7 @@ vi.mock("../lib/audit-security.js", () => ({
   sanitizeAuditValue: vi.fn((v) => v),
   signAuditPayload: mockSignPayload,
   validateAuditAction: mockValidateAuditAction,
+  verifyAuditSignature: mockVerifySignature,
 }));
 
 import { auditService, _resetSvcCircuitForTests } from "./auditService.js";
@@ -36,6 +38,7 @@ describe("auditService", () => {
     mockSignPayload.mockReset();
     mockValidateAuditAction.mockReset();
     mockValidateAuditAction.mockReturnValue(true);
+    mockVerifySignature.mockReset();
     _resetSvcCircuitForTests();
   });
 
@@ -162,6 +165,90 @@ describe("auditService", () => {
     expect(result.page).toBe(1);
   });
 
+  it("verifies matching payload hash and signature during retrieval", async () => {
+    process.env.AUDIT_LOG_SIGNING_SECRET = "test-secret";
+    mockQuery.mockResolvedValueOnce({
+      rows: [
+        {
+          id: "log-1",
+          merchant_id: "merchant-1",
+          action: "update",
+          field_changed: "email",
+          old_value: "a@b.com",
+          new_value: "c@d.com",
+          ip_address: "1.2.3.4",
+          user_agent: "ua",
+          timestamp: new Date(),
+          payload_hash: "calculated-hash",
+          signature: "valid-signature",
+          total_count: "1",
+        },
+      ],
+    });
+
+    mockHashPayload.mockReturnValue("calculated-hash");
+    mockVerifySignature.mockReturnValue(true);
+
+    const result = await auditService.getAuditLogs("merchant-1", 1, 10);
+    expect(result.logs[0].hash_verified).toBe(true);
+    expect(result.logs[0].signature_verified).toBe(true);
+  });
+
+  it("detects mismatching/tampered hash and signature during retrieval", async () => {
+    process.env.AUDIT_LOG_SIGNING_SECRET = "test-secret";
+    mockQuery.mockResolvedValueOnce({
+      rows: [
+        {
+          id: "log-2",
+          merchant_id: "merchant-1",
+          action: "update",
+          field_changed: "email",
+          old_value: "a@b.com",
+          new_value: "c@d.com",
+          ip_address: "1.2.3.4",
+          user_agent: "ua",
+          timestamp: new Date(),
+          payload_hash: "calculated-hash",
+          signature: "invalid-signature",
+          total_count: "1",
+        },
+      ],
+    });
+
+    mockHashPayload.mockReturnValue("different-hash");
+    mockVerifySignature.mockReturnValue(false);
+
+    const result = await auditService.getAuditLogs("merchant-1", 1, 10);
+    expect(result.logs[0].hash_verified).toBe(false);
+    expect(result.logs[0].signature_verified).toBe(false);
+  });
+
+  it("handles missing/null signatures or unset signing secret gracefully", async () => {
+    delete process.env.AUDIT_LOG_SIGNING_SECRET;
+    mockQuery.mockResolvedValueOnce({
+      rows: [
+        {
+          id: "log-3",
+          merchant_id: "merchant-1",
+          action: "update",
+          field_changed: "email",
+          old_value: "a@b.com",
+          new_value: "c@d.com",
+          ip_address: "1.2.3.4",
+          user_agent: "ua",
+          timestamp: new Date(),
+          payload_hash: null,
+          signature: null,
+          total_count: "1",
+        },
+      ],
+    });
+
+    const result = await auditService.getAuditLogs("merchant-1", 1, 10);
+    expect(result.logs[0].hash_verified).toBeNull();
+    expect(result.logs[0].signature_verified).toBeNull();
+  });
+
   // ── Action validation (issue #772) ────────────────────────────────────────
 
   it("drops logEvent calls with disallowed action values", async () => {