feat(logging): Winston structured logging, AuditLog module, and Sentry integration (#3318)

* feat(logging): add Winston structured logging, AuditLog module, and Sentry integration

- Winston JSON logging with configurable levels + X-Request-ID middleware
- AuditLog module with model, service, routes, policy, controller, and tests
- Sentry SDK integration with request context enrichment
- Enriched health endpoint with version, uptime, and dependency checks
- Config: log.json, log.level, sentry.dsn/environment/enabled, audit.ttlDays/enabled

* fix(logging): address review feedback — validation, layer fixes, JSDoc

- Validate X-Request-ID header to prevent log injection
- Mount requestId middleware before pre-parser routes
- Add orgId morgan token for org-scoped request correlation
- Fix Sentry dynamic import to destructure default export
- Add Zod validation in AuditService.log before persisting
- Validate userId/orgId as ObjectId in Zod schemas
- Return 400 on invalid audit query params instead of silent fallback
- Guard deleteMany against empty/missing filter
- Move health endpoint DB logic to HomeService (layer separation)
- Use response envelope in health endpoint
- Move health test to home module tests
- Add JSDoc @returns and @param annotations

* refactor(audit): replace manual controller instrumentation with auto-capture middleware

Move audit logging from individual controller calls to a global Express
middleware that hooks into res.on('finish'), matching the existing
analytics middleware pattern. This removes AuditService imports from
auth, billing, and organizations controllers while preserving the same
audit coverage via automatic route-based action derivation.

* fix(audit): address CodeRabbit review — reject blank action, use Winston logger, add 503 test

- AuditQuery.action now uses .min(1) to reject empty/whitespace-only strings
- AuditService error paths use Winston logger instead of console.error
- Added integration test for degraded health (503) response path
- Mock logger in audit service unit tests to avoid winston config dependency

* fix(health): protect detailed response behind admin auth

Public /api/health returns only { status } for K8s probes.
Admin users (via JWT cookie) get full details: db, uptime, version, memory.
Uses passport optional auth pattern (custom callback, never rejects).

* fix(audit): improve JSDoc @returns type for list method

Document the paginated result shape {data, total, page, perPage} for better developer experience.

* fix(audit): move validation to repository, add JSDoc, restore config in tests

- Move Zod schema validation from service to repository layer (proper dependency direction)
- Add @returns to optionalAuth and route factory JSDoc in home.route.js
- Restore config.organizations.enabled in afterAll to prevent cross-test leak

Author: PierreBrisorgueil

config/defaults/development.config.js

@@ -50,7 +50,11 @@ const config = {
     // logging with Morgan - https://github.com/expressjs/morgan
     // Can specify one of 'combined', 'common', 'dev', 'short', 'tiny', 'custom'
     format: 'custom',
-    pattern: ':id :email :method :url :status :response-time ms - :res[content-length]', // only for custom format
+    pattern: ':requestId :id :email :method :url :status :response-time ms - :res[content-length]', // only for custom format
+    // Structured JSON output for Winston console transport (enable in production)
+    json: false,
+    // Winston log level: error, warn, info, http, verbose, debug, silly
+    level: 'info',
     fileLogger: {
       directoryPath: process.cwd(),
       fileName: 'app.log',
@@ -90,6 +94,11 @@ const config = {
   trust: {
     proxy: false,
   },
+  sentry: {
+    dsn: process.env.DEVKIT_NODE_sentry_dsn || '',
+    environment: process.env.DEVKIT_NODE_sentry_environment || 'development',
+    enabled: false,
+  },
   domain: '',
   cookie: {
     secure: false, // false in dev (HTTP localhost)

config/defaults/production.config.js

@@ -39,7 +39,14 @@ const config = {
   log: {
     format: 'custom',
     pattern:
-      ':id :email :remote-addr - :remote-user [:date[clf]] ":method :url HTTP/:http-version" :status :res[content-length] ":referrer" ":user-agent"', // only for custom format
+      ':requestId :id :email :remote-addr - :remote-user [:date[clf]] ":method :url HTTP/:http-version" :status :res[content-length] ":referrer" ":user-agent"', // only for custom format
+    json: true,
+    level: 'info',
+  },
+  sentry: {
+    dsn: process.env.DEVKIT_NODE_sentry_dsn || '',
+    environment: 'production',
+    enabled: !!process.env.DEVKIT_NODE_sentry_dsn,
   },
 };
 

config/defaults/test.config.js

@@ -9,6 +9,14 @@ const config = {
     uri: 'mongodb://127.0.0.1:27017/NodeTest',
     debug: false,
   },
+  audit: {
+    enabled: true,
+    ttlDays: 1,
+  },
+  sentry: {
+    dsn: '',
+    enabled: false,
+  },
   organizations: {
     enabled: false,
     domainMatching: false,

jest.config.js

@@ -43,6 +43,8 @@ export default {
     '!<rootDir>/modules/auth/auth.init.js',
     // Exclude analytics init glue — just calls AnalyticsService.init()
     '!<rootDir>/modules/analytics/analytics.init.js',
+    // Exclude audit init glue — just logs activation status
+    '!<rootDir>/modules/audit/audit.init.js',
     // Exclude dead code — never imported anywhere in the codebase
     '!<rootDir>/modules/users/services/users.data.service.js',
     // Exclude server bootstrap — startup orchestration, tested indirectly via integration tests
@@ -177,7 +179,7 @@ export default {
   // testLocationInResults: false,
 
   // The glob patterns Jest uses to detect test files
-  testMatch: ['<rootDir>/modules/*/tests/**/*.js'],
+  testMatch: ['<rootDir>/modules/*/tests/**/*.js', '<rootDir>/lib/**/tests/**/*.js'],
 
   // An array of regexp pattern strings that are matched against all test paths, matched tests are skipped
   testPathIgnorePatterns: ['/node_modules/'],

lib/app.js

@@ -10,6 +10,7 @@ import express from './services/express.js';
 import mongooseService from './services/mongoose.js';
 import migrations from './services/migrations.js';
 import AnalyticsService from '../modules/analytics/services/analytics.service.js';
+import SentryService from './services/sentry.js';
 
 // Establish an SQL server connection, instantiating all models and schemas
 // const startSequelize = () =>
@@ -70,6 +71,7 @@ const bootstrap = async () => {
   // }
 
   try {
+    await SentryService.init();
     db = await startMongoose();
     await migrations.run();
     app = await startExpress();
@@ -149,6 +151,7 @@ const shutdown = async (server) => {
   try {
     const value = await server;
     await AnalyticsService.shutdown();
+    await SentryService.shutdown();
     await mongooseService.disconnect();
     value.http.close((err) => {
       console.info(chalk.yellow('Server closed'));

lib/middlewares/policy.js

@@ -197,6 +197,7 @@ const deriveSubjectType = (routePath) => {
   if (routePath === '/api/billing/subscription') return 'BillingSubscription';
   if (routePath === '/api/billing/usage') return 'BillingUsage';
   if (routePath === '/api/billing/plans') return 'BillingPlans';
+  if (routePath.startsWith('/api/audit')) return 'AuditLog';
   if (routePath.startsWith('/api/tasks')) return 'Task';
   if (routePath.startsWith('/api/uploads')) return 'Upload';
   if (routePath.startsWith('/api/home')) return 'Home';

lib/middlewares/requestId.js

@@ -0,0 +1,32 @@
+/**
+ * Module dependencies
+ */
+import { randomUUID } from 'crypto';
+
+/**
+ * Validate that a request ID is safe for use in logs and headers.
+ * Accepts alphanumeric characters, dashes, and underscores up to 128 chars.
+ * @param {string} id - Candidate request ID
+ * @returns {boolean} true if the ID is valid
+ */
+const isValidRequestId = (id) => typeof id === 'string' && id.length <= 128 && /^[\w-]+$/.test(id);
+
+/**
+ * Express middleware that assigns a unique request ID to every incoming request.
+ * If the client sends a valid `X-Request-ID` header, that value is reused;
+ * otherwise a new UUID v4 is generated.  The ID is exposed as `req.id` and
+ * echoed back via the `X-Request-ID` response header for end-to-end tracing.
+ *
+ * @param {Object} req - Express request object
+ * @param {Object} res - Express response object
+ * @param {Function} next - Express next middleware function
+ */
+const requestId = (req, res, next) => {
+  const clientId = req.headers['x-request-id'];
+  const id = (clientId && isValidRequestId(clientId)) ? clientId : randomUUID();
+  req.id = id;
+  res.setHeader('X-Request-ID', id);
+  next();
+};
+
+export default requestId;

lib/middlewares/tests/requestId.unit.tests.js

@@ -0,0 +1,48 @@
+/**
+ * Module dependencies.
+ */
+import { jest, describe, test, expect, beforeEach } from '@jest/globals';
+import requestId from '../requestId.js';
+
+describe('requestId middleware unit tests:', () => {
+  let req;
+  let res;
+  let next;
+
+  beforeEach(() => {
+    req = { headers: {} };
+    res = {
+      _headers: {},
+      setHeader(key, value) {
+        this._headers[key] = value;
+      },
+    };
+    next = jest.fn();
+  });
+
+  test('should generate a UUID when no X-Request-ID header is present', () => {
+    requestId(req, res, next);
+
+    expect(req.id).toBeDefined();
+    expect(typeof req.id).toBe('string');
+    // UUID v4 format
+    expect(req.id).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/);
+    expect(res._headers['X-Request-ID']).toBe(req.id);
+    expect(next).toHaveBeenCalledTimes(1);
+  });
+
+  test('should reuse X-Request-ID from incoming request header', () => {
+    req.headers['x-request-id'] = 'custom-id-123';
+
+    requestId(req, res, next);
+
+    expect(req.id).toBe('custom-id-123');
+    expect(res._headers['X-Request-ID']).toBe('custom-id-123');
+    expect(next).toHaveBeenCalledTimes(1);
+  });
+
+  test('should call next exactly once', () => {
+    requestId(req, res, next);
+    expect(next).toHaveBeenCalledTimes(1);
+  });
+});

lib/services/express.js

@@ -19,6 +19,8 @@ import swaggerUi from 'swagger-ui-express';
 
 import config from '../../config/index.js';
 import logger from './logger.js';
+import requestId from '../middlewares/requestId.js';
+import sentry from './sentry.js';
 
 /**
  * Initialize Swagger
@@ -103,6 +105,8 @@ const initMiddleware = (app) => {
   if (_.has(config, 'log.format') && process.env.NODE_ENV !== 'test') {
     morgan.token('id', (req) => _.get(req, 'user.id') || 'Unknown id');
     morgan.token('email', (req) => _.get(req, 'user.email') || 'Unknown email');
+    morgan.token('requestId', (req) => req.id || '-');
+    morgan.token('orgId', (req) => _.get(req, 'organization.id') || _.get(req, 'organization._id', '-'));
     app.use(morgan(logger.getLogFormat(), logger.getMorganOptions()));
   }
   // Request body parsing middleware should be above methodOverride
@@ -208,6 +212,8 @@ const init = async () => {
   initSwagger(app);
   // Initialize local variables
   initLocalVariables(app);
+  // Assign a unique request ID before any route registration
+  app.use(requestId);
   // Initialize pre-parser routes (before body parsing and CSRF)
   await initPreParserRoutes(app);
   // Initialize Express middleware
@@ -224,6 +230,8 @@ const init = async () => {
   await initModulesServerPolicies(app);
   // Initialize modules server routes
   await initModulesServerRoutes(app);
+  // Mount Sentry error handler (must be after routes, before generic error handler)
+  sentry.setupExpressErrorHandler(app);
   // Initialize error routes
   initErrorRoutes(app);
   return app;

lib/services/logger.js

@@ -7,18 +7,28 @@ import config from '../../config/index.js';
 // list of valid formats for the logging
 const validFormats = ['combined', 'common', 'dev', 'short', 'tiny', 'custom'];
 
+// Determine log level from config (falls back to 'info')
+const logLevel = _.get(config, 'log.level', 'info');
+
+// Determine whether to use structured JSON output
+const useJson = _.get(config, 'log.json', false);
+
+// Build console transport format
+const consoleFormat = useJson
+  ? winston.format.combine(winston.format.timestamp(), winston.format.json())
+  : winston.format.combine(winston.format.colorize(), winston.format.simple());
+
 // Instantiating the default winston application logger with the Console
 // transport
 
 /* eslint new-cap: 0 */
 const logger = new winston.createLogger({
+  level: logLevel,
   transports: [
     new winston.transports.Console({
-      level: 'info',
-      colorize: true,
-      showLevel: true,
+      level: logLevel,
+      format: consoleFormat,
       handleExceptions: true,
-      humanReadableUnhandledException: true,
     }),
   ],
   exitOnError: false,