fix(audit): add config flags for IP/User-Agent capture (GDPR) (#3323)

* fix(audit): add config flags for IP/User-Agent capture (GDPR)

Closes #3320

* fix(audit): add toHaveBeenCalledTimes assertions, backward-compat test, and MIGRATIONS entry

- Add toHaveBeenCalledTimes(1) to all four GDPR flag tests
- Add test for undefined captureIp/captureUserAgent (backward compat)
- Document audit.captureIp and audit.captureUserAgent in MIGRATIONS.md

Author: PierreBrisorgueil

MIGRATIONS.md

@@ -4,6 +4,31 @@ Breaking changes and upgrade notes for downstream projects.
 
 ---
 
+## Audit GDPR Flags (2026-03-26)
+
+New config flags to control IP and User-Agent capture in audit logs for GDPR compliance.
+
+### Configuration
+
+Add to your audit config (e.g. `modules/audit/config/audit.development.config.js`):
+
+```js
+audit: {
+  captureIp: true,          // set false to stop storing client IP addresses
+  captureUserAgent: true,   // set false to stop storing User-Agent strings
+}
+```
+
+Both default to `true` (backward compatible). When set to `false`, the audit log stores an empty string instead of the real value.
+
+### Action for downstream
+
+1. Run `/update-stack` to pull the change
+2. Optionally set `captureIp: false` and/or `captureUserAgent: false` in your audit config for GDPR compliance
+3. No DB migration needed — existing entries are unaffected
+
+---
+
 ## Logging & Monitoring (2026-03-26)
 
 Structured logging, audit trail, Sentry error capture, and enriched health check.

modules/audit/config/audit.development.config.js

@@ -2,6 +2,8 @@ const config = {
   audit: {
     enabled: true,
     ttlDays: 90,
+    captureIp: true,
+    captureUserAgent: true,
   },
 };
 

modules/audit/services/audit.service.js

@@ -33,8 +33,8 @@ const log = async ({ action, req, targetType, targetId, metadata } = {}) => {
     const oid = req.organization?._id || req.organization?.id;
     if (uid) entry.userId = String(uid);
     if (oid) entry.orgId = String(oid);
-    entry.ip = req.ip || req.connection?.remoteAddress || '';
-    entry.userAgent = req.headers?.['user-agent'] || '';
+    entry.ip = config.audit?.captureIp !== false ? (req.ip || req.connection?.remoteAddress || '') : '';
+    entry.userAgent = config.audit?.captureUserAgent !== false ? (req.headers?.['user-agent'] || '') : '';
   }
 
   try {

modules/audit/tests/audit.service.unit.tests.js

@@ -14,11 +14,12 @@ jest.unstable_mockModule('../repositories/audit.repository.js', () => ({
   },
 }));
 
-// Mock config
+// Mock config (mutable so individual tests can override flags)
+const mockConfig = {
+  audit: { enabled: true, ttlDays: 90, captureIp: true, captureUserAgent: true },
+};
 jest.unstable_mockModule('../../../config/index.js', () => ({
-  default: {
-    audit: { enabled: true, ttlDays: 90 },
-  },
+  default: mockConfig,
 }));
 
 // Mock logger to avoid winston config dependency in unit tests
@@ -46,6 +47,8 @@ describe('AuditService unit tests:', () => {
 
   afterEach(() => {
     jest.restoreAllMocks();
+    // Reset config to defaults
+    mockConfig.audit = { enabled: true, ttlDays: 90, captureIp: true, captureUserAgent: true };
   });
 
   test('should log an audit entry with request context', async () => {
@@ -111,4 +114,51 @@ describe('AuditService unit tests:', () => {
     await AuditService.list({ action: undefined, userId }, 1, 10);
     expect(mockList).toHaveBeenCalledWith({ userId }, 1, 10);
   });
+
+  // GDPR config flag tests
+  test('should capture IP when captureIp is true (default)', async () => {
+    mockConfig.audit = { enabled: true, ttlDays: 90, captureIp: true, captureUserAgent: true };
+    const req = { ip: '10.0.0.1', headers: { 'user-agent': 'Bot/1.0' } };
+    await AuditService.log({ action: 'test.ip', req });
+    expect(mockCreate).toHaveBeenCalledTimes(1);
+    const arg = mockCreate.mock.calls[0][0];
+    expect(arg.ip).toBe('10.0.0.1');
+  });
+
+  test('should set IP to empty string when captureIp is false', async () => {
+    mockConfig.audit = { enabled: true, ttlDays: 90, captureIp: false, captureUserAgent: true };
+    const req = { ip: '10.0.0.1', headers: { 'user-agent': 'Bot/1.0' } };
+    await AuditService.log({ action: 'test.ip', req });
+    expect(mockCreate).toHaveBeenCalledTimes(1);
+    const arg = mockCreate.mock.calls[0][0];
+    expect(arg.ip).toBe('');
+  });
+
+  test('should capture User-Agent when captureUserAgent is true (default)', async () => {
+    mockConfig.audit = { enabled: true, ttlDays: 90, captureIp: true, captureUserAgent: true };
+    const req = { ip: '10.0.0.1', headers: { 'user-agent': 'Bot/1.0' } };
+    await AuditService.log({ action: 'test.ua', req });
+    expect(mockCreate).toHaveBeenCalledTimes(1);
+    const arg = mockCreate.mock.calls[0][0];
+    expect(arg.userAgent).toBe('Bot/1.0');
+  });
+
+  test('should set User-Agent to empty string when captureUserAgent is false', async () => {
+    mockConfig.audit = { enabled: true, ttlDays: 90, captureIp: true, captureUserAgent: false };
+    const req = { ip: '10.0.0.1', headers: { 'user-agent': 'Bot/1.0' } };
+    await AuditService.log({ action: 'test.ua', req });
+    expect(mockCreate).toHaveBeenCalledTimes(1);
+    const arg = mockCreate.mock.calls[0][0];
+    expect(arg.userAgent).toBe('');
+  });
+
+  test('should default to capturing IP and User-Agent when config keys are undefined', async () => {
+    mockConfig.audit = { enabled: true, ttlDays: 90 };
+    const req = { ip: '192.168.1.1', headers: { 'user-agent': 'DefaultBot/2.0' } };
+    await AuditService.log({ action: 'test.defaults', req });
+    expect(mockCreate).toHaveBeenCalledTimes(1);
+    const arg = mockCreate.mock.calls[0][0];
+    expect(arg.ip).toBe('192.168.1.1');
+    expect(arg.userAgent).toBe('DefaultBot/2.0');
+  });
 });