feat(audit): tamper-evident audit log for security/financial actions with admin query API

app.js

@@ -47,6 +47,7 @@ import payoutRoutes from "./src/routes/payoutRoutes.js";
 import uploadRoutes from "./src/routes/uploadRoutes.js";
 import jobsRoutes from "./src/routes/jobsRoutes.js";
 import wellKnownRoutes from "./src/routes/wellKnownRoutes.js";
+import auditRoutes from "./src/routes/admin/auditRoutes.js";
 
 handleUncaughtException();
 validateEnv();
@@ -188,6 +189,7 @@ app.use("/api/stellar/donation", stellarDonationRoutes);
 app.use("/api/payouts", payoutRoutes);
 app.use("/api/uploads", uploadRoutes);
 app.use("/admin/jobs", jobsRoutes);
+app.use("/api/admin/audit", auditRoutes);
 
 // ======================
 // ERROR HANDLING

package.json

@@ -8,7 +8,8 @@
     "dev": "nodemon server.js",
     "seed": "node src/scripts/seedDatabase.js",
     "test-redis": "node test-redis.js",
-    "payouts:audit": "node src/scripts/auditPayouts.js"
+    "payouts:audit": "node src/scripts/auditPayouts.js",
+    "worker:ingest": "node src/workers/runIngestionWorker.js"
   },
   "keywords": [],
   "author": "zeemscript",

server.js

@@ -22,6 +22,19 @@ const server = app.listen(PORT, () => {
 
 startJobs().catch((err) => logger.error(err, "Background job startup failed"));
 
+// Start payment ingestion worker if enabled
+let stopIngestionWorker;
+if (process.env.INGESTION_WORKER_ENABLED === "true") {
+  import("./src/workers/paymentIngestionWorker.js").then(
+    ({ startIngestionWorker, stopIngestionWorker: stopFn }) => {
+      stopIngestionWorker = stopFn;
+      startIngestionWorker().catch((err) =>
+        logger.error(err, "Ingestion worker startup failed")
+      );
+    }
+  );
+}
+
 // Graceful shutdown
 const gracefulShutdown = async (signal) => {
   logger.info(`${signal} received. Starting graceful shutdown...`);
@@ -31,6 +44,10 @@ const gracefulShutdown = async (signal) => {
 
     await stopJobs();
 
+    if (stopIngestionWorker) {
+      await stopIngestionWorker();
+    }
+
     // Close Redis connection
     await closeRedis();
 

src/config/validateEnv.js

@@ -47,6 +47,8 @@ const optionalEnvVars = [
   "ORG_TWITTER",
   "ORG_GITHUB",
   "SIGNING_KEY",
+  "INGESTION_WORKER_ENABLED",
+  "INGESTION_POLL_INTERVAL_MS",
 ];
 
 export const validateEnv = () => {

src/controllers/authController.js

@@ -8,6 +8,8 @@ import sendMail from "../../services/emails/sendMail.js";
 import { generatedOtp } from "../routes/emailRoutes.js";
 import logger from "../config/logger.js";
 import { enqueue } from "../jobs/queue.js";
+import { recordAudit } from "../services/audit/auditService.js";
+import { AUDIT_ACTIONS } from "../models/AuditLog.js";
 import { generateOtp, hashOtp, verifyOtp } from "../utils/otp.js";
 
 import { catchAsync, APIError } from "../middlewares/errorHandler.js";
@@ -111,6 +113,15 @@ export const registerUser = catchAsync(async (req, res, next) => {
   const existing = await User.findOne({ email });
   if (existing) {
     logger.warn(`❌ Registration failed - Email already exists: ${email}`);
+    recordAudit({
+      action:     AUDIT_ACTIONS.AUTH_REGISTER_FAILURE,
+      actor:      null,
+      req,
+      targetType: "User",
+      targetId:   email,
+      status:     "failure",
+      metadata:   { email, reason: "email_already_exists" },
+    });
     return next(new APIError("Email already exists", 400));
   }
 
@@ -137,6 +148,16 @@ export const registerUser = catchAsync(async (req, res, next) => {
 
   logger.info(`✅ User registered successfully: ${email} (ID: ${user._id})`);
 
+  recordAudit({
+    action:     AUDIT_ACTIONS.AUTH_REGISTER_SUCCESS,
+    actor:      user._id,
+    req,
+    targetType: "User",
+    targetId:   user._id.toString(),
+    status:     "success",
+    metadata:   { email, assignedRole, name },
+  });
+
   // Generate session and tokens
   const { accessToken, refreshToken } = await createSessionAndTokens(user, req, res);
 
@@ -169,13 +190,31 @@ export const loginUser = catchAsync(async (req, res, next) => {
   const user = await User.findOne({ email }).select("+password");
   if (!user) {
     logger.warn(`❌ Login failed - User not found: ${email}`);
+    recordAudit({
+      action:     AUDIT_ACTIONS.AUTH_LOGIN_FAILURE,
+      actor:      null,
+      req,
+      targetType: "User",
+      targetId:   email,
+      status:     "failure",
+      metadata:   { email, reason: "user_not_found" },
+    });
     return next(new APIError("Invalid credentials", 401));
   }
 
   // Verify password
   const isPasswordCorrect = await bcrypt.compare(password, user.password);
   if (!isPasswordCorrect) {
     logger.warn(`❌ Login failed - Incorrect password: ${email}`);
+    recordAudit({
+      action:     AUDIT_ACTIONS.AUTH_LOGIN_FAILURE,
+      actor:      user._id,
+      req,
+      targetType: "User",
+      targetId:   user._id.toString(),
+      status:     "failure",
+      metadata:   { email, reason: "invalid_password" },
+    });
     return next(new APIError("Invalid credentials", 401));
   }
 
@@ -188,6 +227,16 @@ export const loginUser = catchAsync(async (req, res, next) => {
 
   logger.info(`✅ Login successful: ${email} (ID: ${user._id})`);
 
+  recordAudit({
+    action:     AUDIT_ACTIONS.AUTH_LOGIN_SUCCESS,
+    actor:      user._id,
+    req,
+    targetType: "User",
+    targetId:   user._id.toString(),
+    status:     "success",
+    metadata:   { email, role: user.role },
+  });
+
   res.status(200).json({
     success: true,
     message: "Login successful",
@@ -251,6 +300,16 @@ export const requestPasswordReset = async (req, res) => {
       await user.save();
     }
 
+    recordAudit({
+      action:     AUDIT_ACTIONS.AUTH_PASSWORD_RESET_REQUEST,
+      actor:      user._id,
+      req,
+      targetType: "User",
+      targetId:   user._id.toString(),
+      status:     "success",
+      metadata:   { email },
+    });
+
     res.status(200).json({
       success: true,
       message:
@@ -303,6 +362,17 @@ export const resetPassword = async (req, res) => {
     await user.save();
 
     logger.info("✅ Password reset successful for:", email);
+
+    recordAudit({
+      action:     AUDIT_ACTIONS.AUTH_PASSWORD_RESET_COMPLETE,
+      actor:      user._id,
+      req,
+      targetType: "User",
+      targetId:   user._id.toString(),
+      status:     "success",
+      metadata:   { email },
+    });
+
     res.status(200).json({
       success: true,
       message:
@@ -484,6 +554,16 @@ export const logoutUser = catchAsync(async (req, res, next) => {
     );
   }
 
+  recordAudit({
+    action:     AUDIT_ACTIONS.AUTH_LOGOUT,
+    actor:      req.user?._id ?? null,
+    req,
+    targetType: "User",
+    targetId:   req.user?._id?.toString() ?? null,
+    status:     "success",
+    metadata:   null,
+  });
+
   const isProd = process.env.NODE_ENV === "production";
   res.clearCookie("refreshToken", {
     httpOnly: true,

src/controllers/stellar/paymentController.js

@@ -23,6 +23,7 @@ import {
 import { getAssetConfig, isAssetSupported, getSupportedCodes } from "../../config/assets.js";
 import * as StellarSdk from "@stellar/stellar-sdk";
 import { recordSaleEarnings } from "../../services/payoutService.js";
+import { grantItemAccess } from "../../services/stellar/reconciliationService.js";
 import { enqueue } from "../../jobs/queue.js";
 import logger from "../../config/logger.js";
 import {
@@ -31,6 +32,8 @@ import {
   paymentsConfirmed,
   paymentsFailed,
 } from "../../config/metrics.js";
+import { recordAudit } from "../../services/audit/auditService.js";
+import { AUDIT_ACTIONS } from "../../models/AuditLog.js";
 
 /**
  * Resolve the item, its creator, and the settlement destination wallet for a
@@ -519,6 +522,23 @@ export const initializePayment = async (req, res) => {
       `Payment initialized: ${transaction._id} for ${itemType} ${itemId}`
     );
 
+    recordAudit({
+      action:     AUDIT_ACTIONS.PAYMENT_INITIALIZE,
+      actor:      buyerId,
+      req,
+      targetType: "Transaction",
+      targetId:   transaction._id.toString(),
+      status:     "success",
+      metadata:   {
+        transactionId:  transaction._id.toString(),
+        itemType,
+        itemId,
+        itemTitle:      item.title,
+        amount:         item.price.toString(),
+        settlementMode,
+      },
+    });
+
     res.status(200).json({
       success: true,
       transactionId: transaction._id,
@@ -683,6 +703,20 @@ export const submitPayment = async (req, res) => {
         `Transaction ${transactionId} verification failed: ${verification.reason}`
       );
 
+      recordAudit({
+        action:     AUDIT_ACTIONS.PAYMENT_SUBMIT_FAILED,
+        actor:      buyerId,
+        req,
+        targetType: "Transaction",
+        targetId:   transactionId,
+        status:     "failure",
+        metadata:   {
+          transactionId,
+          stellarTxHash: result.hash,
+          failureReason:  `On-chain verification failed: ${verification.reason}`,
+        },
+      });
+
       return res.status(400).json({
         success: false,
         message: "Payment could not be verified on the Stellar network",
@@ -699,33 +733,13 @@ export const submitPayment = async (req, res) => {
 
     await recordSaleEarnings(transaction, { session });
 
-    const buyer = await User.findById(buyerId).session(session);
-
-    if (transaction.itemType === "book") {
-      buyer.purchasedBooks.push({
-        bookId: transaction.itemId,
-        purchaseDate: new Date(),
-      });
-      if (buyer.stat) {
-        buyer.stat.booksRead = (buyer.stat.booksRead || 0) + 1;
-      }
-    } else {
-      buyer.purchasedCourses.push({
-        courseId: transaction.itemId,
-        purchaseDate: new Date(),
-      });
-      if (buyer.stat) {
-        buyer.stat.coursesEnrolled = (buyer.stat.coursesEnrolled || 0) + 1;
-      }
-
-      await Course.findByIdAndUpdate(
-        transaction.itemId,
-        { $addToSet: { enrolledUsers: buyerId } },
-        { session }
-      );
-    }
-
-    await buyer.save({ session });
+    // Grant access to the purchased item (shared with ingestion worker)
+    await grantItemAccess({
+      buyerId,
+      itemType: transaction.itemType,
+      itemId: transaction.itemId,
+      session,
+    });
     try {
       await enqueue(
         "generateReceipt",
@@ -752,6 +766,24 @@ export const submitPayment = async (req, res) => {
       `Payment successful: ${transactionId}, Stellar TX: ${result.hash}`
     );
 
+    recordAudit({
+      action:     AUDIT_ACTIONS.PAYMENT_SUBMIT_CONFIRMED,
+      actor:      buyerId,
+      req,
+      targetType: "Transaction",
+      targetId:   transactionId,
+      status:     "success",
+      metadata:   {
+        transactionId,
+        stellarTxHash:  result.hash,
+        stellarLedger:  result.ledger,
+        amount:         transaction.amount,
+        itemType:       transaction.itemType,
+        itemId:         transaction.itemId.toString(),
+        settlementMode: transaction.settlement,
+      },
+    });
+
     res.status(200).json({
       success: true,
       message: "Payment successful!",
@@ -912,6 +944,22 @@ export const cancelTransaction = async (req, res) => {
 
     logger.info(`Transaction ${transactionId} cancelled by user ${userId}`);
 
+    recordAudit({
+      action:     AUDIT_ACTIONS.PAYMENT_CANCEL,
+      actor:      userId,
+      req,
+      targetType: "Transaction",
+      targetId:   transactionId,
+      status:     "success",
+      metadata:   {
+        transactionId,
+        itemType:  transaction.itemType,
+        itemId:    transaction.itemId?.toString(),
+        amount:    transaction.amount,
+        failureReason: "Cancelled by user",
+      },
+    });
+
     res.status(200).json({
       success: true,
       message: "Transaction cancelled",

src/controllers/stellar/reconciliationController.js

@@ -0,0 +1,18 @@
+import { getReconciliationStatus } from "../../services/stellar/reconciliationService.js";
+import logger from "../../config/logger.js";
+
+export const reconciliationStatus = async (req, res) => {
+  try {
+    const status = await getReconciliationStatus();
+    res.status(200).json({
+      success: true,
+      ...status,
+    });
+  } catch (error) {
+    logger.error("Get reconciliation status error:", error);
+    res.status(500).json({
+      success: false,
+      message: "Failed to fetch reconciliation status",
+    });
+  }
+};