@nm-logger/logger 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Virtual Employee
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights  
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell     
+copies of the Software, and to permit persons to whom the Software is        
+furnished to do so, subject to the following conditions:                     
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.                              
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR    
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,      
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE   
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER       
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,236 @@
+# @ve/logger
+
+Daily JSON logger for Node.js / Express APIs with:
+
+- S3 upload + queue + daily rotation  
+- Correlation IDs (with `X-Correlation-ID` header)  
+- External API logging (Axios)  
+- Sensitive field masking (password, token, otp, etc.)  
+
+---
+
+## Installation
+
+After you publish the package to npm:
+
+```bash
+npm install @ve/logger
+```
+
+---
+
+## Log Format
+
+Each log line in `daily_logs.json` is a JSON object:
+
+```json
+{
+  "url": "/api/v1/attendance/get",
+  "body": "{\"month\":\"2025-12\"}",
+  "params": "{\"params\":{},\"query\":{}}",
+  "type": "get",
+  "error": "",
+  "date": "2025-12-05 12:24:00",
+  "employee_id": "TAKK122",
+  "correlation_id": "cid-abcd1234-17f5d3c9a"
+}
+```
+
+Fields:
+
+- `url` – `req.originalUrl`
+- `body` – stringified (and masked) `req.body`
+- `params` – stringified (and masked) object `{ params: req.params, query: req.query }`
+- `type` – last segment of the URL (e.g. `/api/v1/attendance/get` → `"get"`)
+- `error` – error message if any
+- `date` – `YYYY-MM-DD HH:mm:ss`
+- `employee_id` – from argument or `req.user.employee_id / emp_code / id`
+- `correlation_id` – unique per request chain (also added as `X-Correlation-ID` header)
+
+---
+
+## Basic Usage
+
+### 1. Create the logger
+
+```js
+const Logger = require("@ve/logger");
+
+const logger = new Logger(
+  {
+    accessKeyId: process.env.AWS_KEY,
+    secretAccessKey: process.env.AWS_SECRET,
+    region: "ap-south-1",
+    bucket: "your-log-bucket-name"
+  },
+  {
+    baseDir: "logs",        // optional, default "logs"
+    watchIntervalMs: 60000, // optional, default 60s
+    maskFields: ["aadhaar", "panNumber"] // extra fields to mask
+  }
+);
+```
+
+### 2. Log every request + set correlation ID header
+
+```js
+app.use(logger.requestLoggerMiddleware());
+```
+
+### 3. Log errors via Express error middleware
+
+```js
+// your routes above...
+
+app.use(logger.expressMiddleware()); // or logger.expressErrorMiddleware()
+```
+
+### 4. Manual logging in routes
+
+```js
+app.post("/api/v1/attendance/get", async (req, res) => {
+  try {
+    // ... your logic, external APIs etc ...
+
+    await logger.logRequest(req, req.user?.employee_id);
+    res.json({ success: true });
+  } catch (err) {
+    await logger.logError(err, req, req.user?.employee_id);
+    res.status(500).json({ error: err.message });
+  }
+});
+```
+
+---
+
+## External API logging with Axios
+
+```js
+const axios = require("axios");
+
+// Attach once at startup
+logger.attachAxiosLogger(axios);
+
+app.get("/api/v1/some-data", async (req, res) => {
+  try {
+    const response = await axios.get("https://api.example.com/data", {
+      headers: {
+        "X-Correlation-ID": req.correlationId,          // propagated
+        "X-Employee-ID": req.user?.employee_id || ""    // optional
+      },
+      params: {
+        id: 123
+      }
+    });
+
+    res.json(response.data);
+  } catch (err) {
+    await logger.logError(err, req, req.user?.employee_id);
+    res.status(500).json({ error: err.message });
+  }
+});
+```
+
+This will produce external log lines like:
+
+```json
+{
+  "url": "https://api.example.com/data",
+  "body": "{}",
+  "params": "{\"id\":123}",
+  "type": "external_api",
+  "error": "",
+  "date": "2025-12-05 12:24:00",
+  "employee_id": "TAKK122",
+  "correlation_id": "cid-abcd1234-17f5d3c9a"
+}
+```
+
+---
+
+## Sensitive Data Masking
+
+Built-in masked keys (case-insensitive, partial match):
+
+- password, pass  
+- token, secret  
+- otp  
+- auth, authorization  
+- apiKey, api_key  
+- session  
+- ssn  
+
+Plus anything you pass in `maskFields` option.
+
+Any object like:
+
+```json
+{
+  "password": "MyPass123",
+  "otp": "111222",
+  "aadhaar": "9999-8888-7777",
+  "email": "user@example.com"
+}
+```
+
+will be logged as:
+
+```json
+{
+  "password": "*****",
+  "otp": "*****",
+  "aadhaar": "*****",
+  "email": "user@example.com"
+}
+```
+
+---
+
+## S3 Upload Behavior
+
+- Logs are stored locally under:
+  - `logs/YYYY/MM/DD/daily_logs.json`
+- A watcher runs every `watchIntervalMs` (default 60 seconds)
+  - When the date changes (e.g., from `2025-12-05` to `2025-12-06`),
+  - The logger uploads the **previous day's** log file to S3:
+
+Example S3 key:
+
+```txt
+2025/12/05/daily_logs.json
+```
+
+So final S3 path:
+
+```txt
+s3://<bucket>/<year>/<month>/<day>/daily_logs.json
+```
+
+---
+
+## TypeScript Usage
+
+```ts
+import Logger, { S3Config, LoggerOptions } from "@ve/logger";
+
+const s3config: S3Config = {
+  accessKeyId: process.env.AWS_KEY!,
+  secretAccessKey: process.env.AWS_SECRET!,
+  region: "ap-south-1",
+  bucket: "your-log-bucket"
+};
+
+const options: LoggerOptions = {
+  baseDir: "logs",
+  watchIntervalMs: 60000,
+  maskFields: ["aadhaar", "pan"]
+};
+
+const logger = new Logger(s3config, options);
+```
+
+---
+
+## License
+
+MIT

package/index.d.ts

@@ -0,0 +1,117 @@
+import * as express from "express";
+
+export interface S3Config {
+  accessKeyId: string;
+  secretAccessKey: string;
+  region: string;
+  bucket: string;
+}
+
+export interface LoggerOptions {
+  /**
+   * Local base directory where logs are stored.
+   * Default: "logs"
+   */
+  baseDir?: string;
+
+  /**
+   * Interval in milliseconds for the daily watcher to check for date change.
+   * Default: 60000 (1 minute)
+   */
+  watchIntervalMs?: number;
+
+  /**
+   * Extra field names to mask in logs (in addition to built-in ones like password, token, otp, etc.).
+   * Matching is case-insensitive and uses "includes".
+   */
+  maskFields?: string[];
+}
+
+export interface LogEntryShape {
+  url: string;
+  body: string;
+  params: string;
+  type: string;
+  error: string;
+  date: string;
+  employee_id: string;
+  correlation_id: string;
+}
+
+export interface ExternalApiLogOptions {
+  url?: string;
+  method?: string;
+  data?: any;
+  params?: any;
+  error?: string | null;
+  correlationId?: string;
+  employeeId?: string;
+}
+
+declare class Logger {
+  constructor(s3config?: S3Config, options?: LoggerOptions);
+
+  /**
+   * Log an error for a given request.
+   * The log will be appended to the daily JSON file.
+   */
+  logError(
+    err: any,
+    req?: express.Request,
+    employee_id?: string
+  ): Promise<void>;
+
+  /**
+   * Log a normal API request (no error).
+   */
+  logRequest(req: express.Request, employee_id?: string): Promise<void>;
+
+  /**
+   * Log an external API call (axios, etc.).
+   * Type will be "external_api".
+   */
+  logExternalApi(options: ExternalApiLogOptions): Promise<void>;
+
+  /**
+   * Express error-handling middleware.
+   * Use: app.use(logger.expressMiddleware());
+   * Also ensures X-Correlation-ID header is present.
+   */
+  expressMiddleware(): (
+    err: any,
+    req: express.Request,
+    res: express.Response,
+    next: express.NextFunction
+  ) => void;
+
+  /**
+   * Alias for expressMiddleware (for clarity).
+   */
+  expressErrorMiddleware(): (
+    err: any,
+    req: express.Request,
+    res: express.Response,
+    next: express.NextFunction
+  ) => void;
+
+  /**
+   * Express request-logging middleware (non-error).
+   * Also generates/propagates correlation ID and sets X-Correlation-ID header.
+   * Use near the top of your middleware chain.
+   */
+  requestLoggerMiddleware(): (
+    req: express.Request,
+    res: express.Response,
+    next: express.NextFunction
+  ) => void;
+
+  /**
+   * Attach axios interceptors to log external API calls.
+   * Usage:
+   *   const axios = require("axios");
+   *   logger.attachAxiosLogger(axios);
+   */
+  attachAxiosLogger(axiosInstance: any): void;
+}
+
+export = Logger;

package/index.js

@@ -0,0 +1,4 @@
+const Logger = require("./src/Logger");
+
+module.exports = Logger;
+module.exports.Logger = Logger;

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@nm-logger/logger",
+  "version": "1.1.0",
+  "description": "Daily JSON logger with S3 upload queue, correlation IDs, external API logging, and sensitive field masking for Express-based APIs.",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "scripts": {
+    "test": "node -e \"console.log('no tests yet')\""
+  },
+  "keywords": [
+    "logger",
+    "logging",
+    "express",
+    "s3",
+    "aws",
+    "json-logger",
+    "daily-logs",
+    "correlation-id",
+    "axios",
+    "masking"
+  ],
+  "author": "Virtual Employee (https://virtualemployee.com)",
+  "homepage": "https://virtualemployee.com",
+  "license": "MIT",
+  "dependencies": {
+    "aws-sdk": "^2.1554.0",
+    "fs-extra": "^11.1.1"
+  },
+  "peerDependencies": {
+    "express": ">=4.0.0"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  }
+}

package/src/DailyWatcher.js

@@ -0,0 +1,53 @@
+const { getDatePath } = require("./utils");
+const path = require("path");
+const fs = require("fs-extra");
+
+class DailyWatcher {
+  constructor(baseDir, queue, s3Uploader, options = {}) {
+    this.baseDir = baseDir;
+    this.queue = queue;
+    this.s3Uploader = s3Uploader;
+    this.intervalMs = options.watchIntervalMs || 60_000; // default: 1 minute
+
+    this.lastDay = null;
+    this.startWatching();
+  }
+
+  startWatching() {
+    setInterval(() => {
+      const { Y, M, D } = getDatePath();
+      const currentDay = `${Y}-${M}-${D}`;
+
+      if (!this.lastDay) {
+        // First run, just set lastDay
+        this.lastDay = currentDay;
+        return;
+      }
+
+      if (this.lastDay !== currentDay) {
+        // Day changed → upload previous day's log
+        const lastDayPath = this.lastDay.replace(/-/g, "/");
+
+        const logFile = path.join(
+          this.baseDir,
+          lastDayPath,
+          "daily_logs.json"
+        );
+
+        if (fs.existsSync(logFile)) {
+          const s3Key = `${lastDayPath}/daily_logs.json`; // e.g. 2025/12/05/daily_logs.json
+
+          this.queue.add(async () => {
+            console.log("📤 Uploading previous day logs →", s3Key);
+            await this.s3Uploader.upload(logFile, s3Key);
+          });
+        }
+
+        // update lastDay to current
+        this.lastDay = currentDay;
+      }
+    }, this.intervalMs);
+  }
+}
+
+module.exports = DailyWatcher;

package/src/LogWriter.js

@@ -0,0 +1,29 @@
+const fs = require("fs-extra");
+const path = require("path");
+const { getDatePath, formatDate } = require("./utils");
+
+class LogWriter {
+  constructor(baseDir = "logs") {
+    this.baseDir = baseDir;
+  }
+
+  /**
+   * Writes a single log entry in the required JSON format
+   * and appends it as one line to daily_logs.json
+   */
+  async writeLog(log) {
+    const { Y, M, D } = getDatePath();
+    const logDir = path.join(this.baseDir, `${Y}/${M}/${D}`);
+    const logFile = path.join(logDir, "daily_logs.json");
+
+    await fs.ensureDir(logDir);
+
+    // Ensure date field is always set in required format
+    log.date = formatDate(new Date());
+
+    await fs.appendFile(logFile, JSON.stringify(log) + "\n");
+    return logFile;
+  }
+}
+
+module.exports = LogWriter;

package/src/Logger.js

@@ -0,0 +1,297 @@
+const LogWriter = require("./LogWriter");
+const Queue = require("./Queue");
+const S3Uploader = require("./S3Uploader");
+const DailyWatcher = require("./DailyWatcher");
+const {
+  getApiType,
+  maskSensitive,
+  generateCorrelationId
+} = require("./utils");
+
+class Logger {
+  constructor(s3config = {}, options = {}) {
+    this.baseDir = options.baseDir || "logs";
+
+    this.logWriter = new LogWriter(this.baseDir);
+    this.queue = new Queue();
+    this.s3Uploader = new S3Uploader(s3config);
+
+    // Extra fields user wants masked (e.g. ["aadhaar", "pan"])
+    this.extraMaskFields = (options.maskFields || []).map((f) =>
+      String(f).toLowerCase()
+    );
+
+    // Start daily watcher for S3 uploads
+    new DailyWatcher(this.baseDir, this.queue, this.s3Uploader, {
+      watchIntervalMs: options.watchIntervalMs
+    });
+  }
+
+  /**
+   * Mask any sensitive data using default + custom fields.
+   */
+  mask(value) {
+    return maskSensitive(value, this.extraMaskFields);
+  }
+
+  /**
+   * Build the base log entry with required shape.
+   * {
+   *   url, body, params, type, error, date (added by LogWriter), employee_id, correlation_id
+   * }
+   */
+  buildBaseLog(req, employee_id = "") {
+    const url = req?.originalUrl || "";
+    const bodySrc = req?.body || {};
+    const paramsObj = {
+      params: req?.params || {},
+      query: req?.query || {}
+    };
+
+    const maskedBody = this.mask(bodySrc);
+    const maskedParams = this.mask(paramsObj);
+
+    // derive correlation ID from request or headers
+    let correlationId =
+      req?.correlationId ||
+      (req?.headers &&
+        (req.headers["x-correlation-id"] || req.headers["X-Correlation-ID"])) ||
+      "";
+
+    return {
+      url,
+      body: JSON.stringify(maskedBody || {}),
+      params: JSON.stringify(maskedParams || {}),
+      type: getApiType(url),
+      error: "",
+      employee_id:
+        employee_id ||
+        (req &&
+          req.user &&
+          (req.user.employee_id || req.user.emp_code || req.user.id)) ||
+        "",
+      correlation_id: correlationId
+    };
+  }
+
+  /**
+   * Log an error (incoming API).
+   */
+  async logError(err, req, employee_id = "") {
+    const base = this.buildBaseLog(req || {}, employee_id);
+
+    const logData = {
+      ...base,
+      error: err && err.message ? err.message : String(err || "")
+    };
+
+    await this.logWriter.writeLog(logData);
+  }
+
+  /**
+   * Log a normal request (incoming API).
+   */
+  async logRequest(req, employee_id = "") {
+    const logData = this.buildBaseLog(req, employee_id);
+    await this.logWriter.writeLog(logData);
+  }
+
+  /**
+   * Log an external API call (axios, etc.).
+   * For external APIs, `type` is always "external_api".
+   */
+  async logExternalApi({
+    url,
+    method,
+    data,
+    params,
+    error,
+    correlationId,
+    employeeId
+  }) {
+    const maskedBody = this.mask(data || {});
+    const maskedParams = this.mask(params || {});
+
+    const logData = {
+      url: url || "",
+      body: JSON.stringify(maskedBody || {}),
+      params: JSON.stringify(maskedParams || {}),
+      type: "external_api",
+      error: error || "",
+      date: undefined, // set by LogWriter
+      employee_id: employeeId || "",
+      correlation_id: correlationId || ""
+    };
+
+    await this.logWriter.writeLog(logData);
+  }
+
+  /**
+   * Express error-handling middleware.
+   * Use: app.use(logger.expressMiddleware());
+   * Also ensures correlation ID is present and added to response header.
+   */
+  expressMiddleware() {
+    return (err, req, res, next) => {
+      try {
+        let correlationId =
+          req.correlationId ||
+          (req.headers &&
+            (req.headers["x-correlation-id"] ||
+              req.headers["X-Correlation-ID"])) ||
+          "";
+
+        if (!correlationId) {
+          correlationId = generateCorrelationId();
+          req.correlationId = correlationId;
+        }
+
+        if (res && !res.headersSent) {
+          res.setHeader("X-Correlation-ID", correlationId);
+        }
+
+        this.logError(err, req).catch((e) =>
+          console.error("Logger expressMiddleware error:", e)
+        );
+      } catch (e) {
+        console.error("Logger expressMiddleware outer error:", e);
+      }
+
+      next(err);
+    };
+  }
+
+  /**
+   * Alias for expressMiddleware (for clarity).
+   */
+  expressErrorMiddleware() {
+    return this.expressMiddleware();
+  }
+
+  /**
+   * Express request-logging middleware.
+   * - Generates or reuses correlation ID
+   * - Sets X-Correlation-ID header on response
+   * - Logs each incoming request
+   *
+   * Use near the top of middleware stack:
+   *   app.use(logger.requestLoggerMiddleware());
+   */
+  requestLoggerMiddleware() {
+    return (req, res, next) => {
+      try {
+        let correlationId =
+          req.headers["x-correlation-id"] ||
+          req.headers["X-Correlation-ID"] ||
+          req.correlationId;
+
+        if (!correlationId) {
+          correlationId = generateCorrelationId();
+        }
+
+        req.correlationId = correlationId;
+        res.setHeader("X-Correlation-ID", correlationId);
+
+        this.logRequest(req).catch((e) =>
+          console.error("Logger requestLoggerMiddleware error:", e)
+        );
+      } catch (e) {
+        console.error("Logger requestLoggerMiddleware outer error:", e);
+      }
+
+      next();
+    };
+  }
+
+  /**
+   * Attach axios interceptors to log EXTERNAL API calls.
+   *
+   * Usage:
+   *   const axios = require("axios");
+   *   logger.attachAxiosLogger(axios);
+   *
+   * In your route:
+   *   await axios.get("https://api.example.com", {
+   *     headers: {
+   *       "X-Correlation-ID": req.correlationId,
+   *       "X-Employee-ID": req.user?.employee_id
+   *     }
+   *   });
+   */
+  attachAxiosLogger(axiosInstance) {
+    if (!axiosInstance || !axiosInstance.interceptors) {
+      console.warn(
+        "[@ve/logger] attachAxiosLogger: provided axios instance is invalid"
+      );
+      return;
+    }
+
+    axiosInstance.interceptors.response.use(
+      (response) => {
+        try {
+          const cfg = response.config || {};
+          const headers = cfg.headers || {};
+
+          const correlationId =
+            headers["X-Correlation-ID"] ||
+            headers["x-correlation-id"] ||
+            "";
+
+          const employeeId =
+            headers["X-Employee-ID"] ||
+            headers["x-employee-id"] ||
+            "";
+
+          this.logExternalApi({
+            url: cfg.url,
+            method: cfg.method,
+            data: cfg.data,
+            params: cfg.params,
+            error: null,
+            correlationId,
+            employeeId
+          }).catch((e) =>
+            console.error("Logger axios success logExternalApi error:", e)
+          );
+        } catch (e) {
+          console.error("Logger axios response interceptor error:", e);
+        }
+        return response;
+      },
+      (error) => {
+        try {
+          const cfg = error.config || {};
+          const headers = cfg ? cfg.headers || {} : {};
+
+          const correlationId =
+            headers["X-Correlation-ID"] ||
+            headers["x-correlation-id"] ||
+            "";
+
+          const employeeId =
+            headers["X-Employee-ID"] ||
+            headers["x-employee-id"] ||
+            "";
+
+          this.logExternalApi({
+            url: cfg && cfg.url,
+            method: cfg && cfg.method,
+            data: cfg && cfg.data,
+            params: cfg && cfg.params,
+            error: error && error.message,
+            correlationId,
+            employeeId
+          }).catch((e) =>
+            console.error("Logger axios error logExternalApi error:", e)
+          );
+        } catch (e) {
+          console.error("Logger axios error interceptor outer error:", e);
+        }
+
+        return Promise.reject(error);
+      }
+    );
+  }
+}
+
+module.exports = Logger;

package/src/Queue.js

@@ -0,0 +1,32 @@
+class Queue {
+  constructor() {
+    this.jobs = [];
+    this.processing = false;
+  }
+
+  add(job) {
+    this.jobs.push(job);
+    this.run();
+  }
+
+  async run() {
+    if (this.processing) return;
+
+    this.processing = true;
+
+    while (this.jobs.length) {
+      const job = this.jobs.shift();
+      try {
+        await job();
+      } catch (err) {
+        console.error("Queue job failed → re-added to queue:", err);
+        // Re-add the job for retry (very simple retry mechanism)
+        this.jobs.push(job);
+      }
+    }
+
+    this.processing = false;
+  }
+}
+
+module.exports = Queue;

package/src/S3Uploader.js

@@ -0,0 +1,28 @@
+const AWS = require("aws-sdk");
+const fs = require("fs");
+
+class S3Uploader {
+  constructor(config) {
+    this.s3 = new AWS.S3({
+      accessKeyId: config.accessKeyId,
+      secretAccessKey: config.secretAccessKey,
+      region: config.region
+    });
+
+    this.bucket = config.bucket;
+  }
+
+  async upload(filePath, s3Key) {
+    const fileData = fs.readFileSync(filePath);
+
+    return this.s3
+      .putObject({
+        Bucket: this.bucket,
+        Key: s3Key,
+        Body: fileData
+      })
+      .promise();
+  }
+}
+
+module.exports = S3Uploader;

package/src/utils.js

@@ -0,0 +1,111 @@
+// Build path segments for logs: YYYY/MM/DD
+exports.getDatePath = () => {
+  const now = new Date();
+  const Y = now.getFullYear();
+  const M = String(now.getMonth() + 1).padStart(2, "0");
+  const D = String(now.getDate()).padStart(2, "0");
+  return { Y, M, D };
+};
+
+// Format date as: 2025-12-05 12:24:00
+exports.formatDate = (d) => {
+  const pad = (n) => String(n).padStart(2, "0");
+
+  return (
+    d.getFullYear() +
+    "-" +
+    pad(d.getMonth() + 1) +
+    "-" +
+    pad(d.getDate()) +
+    " " +
+    pad(d.getHours()) +
+    ":" +
+    pad(d.getMinutes()) +
+    ":" +
+    pad(d.getSeconds())
+  );
+};
+
+// Extract last segment from URL, used as "type"
+// e.g. "/api/v1/attendance/get" → "get"
+exports.getApiType = (url) => {
+  if (!url) return "";
+  const segments = url.split("/").filter(Boolean);
+  return segments[segments.length - 1] || "";
+};
+
+// Default keys to mask (case-insensitive, "includes" match)
+const DEFAULT_MASK_KEYS = [
+  "password",
+  "pass",
+  "token",
+  "secret",
+  "otp",
+  "auth",
+  "authorization",
+  "apikey",
+  "api_key",
+  "session",
+  "ssn"
+];
+
+/**
+ * Deep mask of sensitive fields in any object/array.
+ * - Keys containing any of the mask keys are replaced with "*****"
+ * - Works recursively
+ * - If input is string, tries JSON.parse then masks
+ */
+exports.maskSensitive = (value, extraFields = []) => {
+  const allKeys = [
+    ...DEFAULT_MASK_KEYS,
+    ...(extraFields || [])
+  ].map((k) => String(k).toLowerCase());
+
+  const shouldMaskKey = (key) => {
+    const lower = String(key).toLowerCase();
+    return allKeys.some((mk) => lower.includes(mk));
+  };
+
+  const maskAny = (val) => {
+    if (val && typeof val === "object") {
+      if (Array.isArray(val)) {
+        return val.map(maskAny);
+      }
+      const out = {};
+      for (const [k, v] of Object.entries(val)) {
+        if (shouldMaskKey(k)) {
+          if (v === null || v === undefined) {
+            out[k] = v;
+          } else if (typeof v === "string" && v.length) {
+            out[k] = "*****";
+          } else {
+            out[k] = "*****";
+          }
+        } else {
+          out[k] = maskAny(v);
+        }
+      }
+      return out;
+    }
+    return val;
+  };
+
+  // If it's a string, try JSON.parse and mask
+  if (typeof value === "string") {
+    try {
+      const parsed = JSON.parse(value);
+      return maskAny(parsed);
+    } catch (_) {
+      return value;
+    }
+  }
+
+  return maskAny(value);
+};
+
+// Simple correlation ID generator
+exports.generateCorrelationId = () => {
+  const rand = Math.random().toString(16).slice(2, 10);
+  const ts = Date.now().toString(16);
+  return `cid-${rand}-${ts}`;
+};