security: persist HIPAA audit log to MongoDB (W1 #6)

createAuditLog() only console.logged with a "in a real HIPAA
deployment we would persist this here" comment, and the API-access
capture point was a TODO. For a HIPAA-framed project, an audit trail
that vanishes on process exit is the most load-bearing gap in the repo.

- Add the AuditLog Mongoose model: action/userId/address/requestId/
  ip/userAgent/details/timestamp, immutable (no updatedAt), with
  compound indexes on (userId, timestamp), (address, timestamp),
  (action, timestamp).
- Add auditLogService.write(): fire-and-forget, swallows its own
  errors so a DB hiccup never crashes request handling.
- Wire createAuditLog() and the res.end API-access hook to it.

Retention/tamper-evidence remain documented limitations — see
SECURITY.md.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: EPW80

server/middleware/hipaaCompliance.js

@@ -2,6 +2,7 @@
 import { createError } from "../errors/index.js";
 import crypto from "crypto";
 import validation from "../validation/index.js";
+import auditLogService from "../services/auditLogService.js";
 
 // Function to create an audit log entry
 const createAuditLog = async (action, details = {}) => {
@@ -12,9 +13,13 @@ const createAuditLog = async (action, details = {}) => {
       ...details,
     };
 
-    // In a real HIPAA deployment we would persist this to a tamper-evident
-    // audit store here. For now just log it.
-    console.log(`[HIPAA AUDIT] ${action}:`, auditEntry);
+    // Persist to MongoDB. auditLogService.write() swallows its own errors, so
+    // a DB hiccup will never throw here.
+    await auditLogService.write(action, auditEntry);
+
+    if (process.env.NODE_ENV !== "production") {
+      console.log(`[HIPAA AUDIT] ${action}:`, auditEntry);
+    }
 
     return true;
   } catch (error) {
@@ -115,7 +120,8 @@ const hipaaCompliance = {
         );
       }
 
-      // TODO: persist every API access to a real audit store.
+      // Persist every API access. Fire-and-forget — res.end must not block.
+      auditLogService.write("API_ACCESS", auditEntry);
 
       // Call the original end method
       originalEnd.apply(res, arguments);

server/models/AuditLog.js

@@ -0,0 +1,50 @@
+import mongoose from "mongoose";
+
+const auditLogSchema = new mongoose.Schema(
+  {
+    action: {
+      type: String,
+      required: true,
+      index: true,
+    },
+    userId: {
+      type: String,
+      index: true,
+    },
+    address: {
+      type: String,
+      lowercase: true,
+      trim: true,
+      index: true,
+    },
+    requestId: {
+      type: String,
+    },
+    ipAddress: {
+      type: String,
+    },
+    userAgent: {
+      type: String,
+    },
+    details: {
+      type: mongoose.Schema.Types.Mixed,
+    },
+    timestamp: {
+      type: Date,
+      default: Date.now,
+      index: true,
+    },
+  },
+  {
+    // Audit logs are immutable — no updatedAt needed.
+    timestamps: false,
+  }
+);
+
+// Compound indexes for the most common query patterns.
+auditLogSchema.index({ userId: 1, timestamp: -1 });
+auditLogSchema.index({ address: 1, timestamp: -1 });
+auditLogSchema.index({ action: 1, timestamp: -1 });
+
+const AuditLog = mongoose.model("AuditLog", auditLogSchema);
+export default AuditLog;

server/services/auditLogService.js

@@ -0,0 +1,23 @@
+import AuditLog from "../models/AuditLog.js";
+import { logger } from "../config/loggerConfig.js";
+
+// Audit failures must NEVER crash the application. Every write is fire-and-
+// forget from the caller's perspective; errors are logged but not rethrown.
+async function write(action, details = {}) {
+  try {
+    await AuditLog.create({
+      action,
+      userId: details.userId,
+      address: details.address,
+      requestId: details.requestId,
+      ipAddress: details.ipAddress || details.ip,
+      userAgent: details.userAgent,
+      details,
+      timestamp: details.timestamp ? new Date(details.timestamp) : new Date(),
+    });
+  } catch (err) {
+    logger.error("Audit log write failed", { action, error: err.message });
+  }
+}
+
+export default { write };