iri-shield 1.2.3 → 1.2.4

package/README.md

@@ -1,6 +1,6 @@
 # iri-shield
 
-[![npm version](https://img.shields.io/badge/npm-v1.2.2-blue.svg)](https://www.npmjs.com/package/iri-shield)
+[![npm version](https://img.shields.io/badge/npm-v1.2.4-blue.svg)](https://www.npmjs.com/package/iri-shield)
 [![License: MIT](https://img.shields.io/badge/License-MIT-emerald.svg)](https://opensource.org/licenses/MIT)
 [![Node.js](https://img.shields.io/badge/node-%3E%3D22.0.0-purple.svg)](https://nodejs.org)
 [![Security](https://img.shields.io/badge/security-risk--scoring-orange.svg)](#explainable-risk-scoring)
@@ -402,10 +402,13 @@ dashboard: {
   path: '/iri-shield',
   username: process.env.SHIELD_ADMIN_USER,
   password: process.env.SHIELD_ADMIN_PASSWORD,
+  sessionSecret: process.env.IRI_SHIELD_DASHBOARD_SECRET || process.env.SESSION_SECRET,
   refreshMs: 60 * 1000
 }
 ```
 
+Set a stable `sessionSecret` on serverless hosts. Otherwise old deployments that used a random per-instance dashboard token could intermittently return `401 Unauthorized` from dashboard API calls after a cold start or instance switch.
+
 ### Production Configuration
 
 ```js
@@ -443,7 +446,8 @@ const shield = createShield({
     enabled: true,
     path: '/iri-shield',
     username: process.env.SHIELD_ADMIN_USER,
-    password: process.env.SHIELD_ADMIN_PASSWORD
+    password: process.env.SHIELD_ADMIN_PASSWORD,
+    sessionSecret: process.env.IRI_SHIELD_DASHBOARD_SECRET || process.env.SESSION_SECRET || process.env.JWT_SECRET
   }
 });
 
@@ -476,6 +480,15 @@ storage: {
 
 This avoids filesystem initialization errors and is suitable for testing the middleware, dashboard, detection rules, and API behaviour.
 
+For persistent Vercel dashboard history, use MongoDB:
+
+```js
+storage: {
+  mode: 'mongodb',
+  mongoUrl: process.env.IRI_MONGO_URL
+}
+```
+
 If you explicitly want SQLite for a short-lived demo, use `/tmp`:
 
 ```js
@@ -515,7 +528,7 @@ const shield = createShield({
   trustProxy: true,
 
   storage: {
-    mode: process.env.IRI_STORAGE_MODE || 'memory',
+    mode: process.env.IRI_STORAGE_MODE || (process.env.IRI_MONGO_URL ? 'mongodb' : 'memory'),
     sqliteFile: process.env.IRI_SQLITE_FILE || '/tmp/iri-shield.sqlite',
     mongoUrl: process.env.IRI_MONGO_URL
   },
@@ -530,6 +543,7 @@ const shield = createShield({
     path: '/iri-shield',
     username: process.env.SHIELD_ADMIN_USER,
     password: process.env.SHIELD_ADMIN_PASSWORD,
+    sessionSecret: process.env.IRI_SHIELD_DASHBOARD_SECRET || process.env.SESSION_SECRET || process.env.JWT_SECRET,
     refreshMs: 60 * 1000
   }
 });
@@ -564,6 +578,7 @@ NODE_ENV=production
 APP_NAME=my-api
 SHIELD_ADMIN_USER=admin
 SHIELD_ADMIN_PASSWORD=replace-with-a-strong-secret
+IRI_SHIELD_DASHBOARD_SECRET=replace-with-a-long-random-session-secret
 IRI_STORAGE_MODE=memory
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "iri-shield",
-  "version": "1.2.3",
+  "version": "1.2.4",
   "description": "Enterprise Express.js security middleware — explainable risk scoring, multi-signal identity profiling, behavioural anomaly detection, attack correlation, sensitive-data redaction, and dashboard monitoring.",
   "keywords": [
     "iri-shield",

package/src/dashboard.js

@@ -1,7 +1,7 @@
 'use strict';
 
 const express = require('express');
-const { randomBytes, timingSafeEqual } = require('crypto');
+const { createHmac, timingSafeEqual } = require('crypto');
 
 function createDashboardRouter({ storage, config }) {
   const router = express.Router();
@@ -46,60 +46,66 @@ function createDashboardRouter({ storage, config }) {
   // API endpoints
   // =========================================================================
 
-  router.get('/api/stats', (req, res) => {
-    res.json({ ...storage.getStats(), config: publicConfig(config) });
+  router.use('/api/', (_req, res, next) => {
+    res.setHeader('Cache-Control', 'no-store');
+    next();
   });
 
+  router.get('/api/stats', asyncRoute(async (req, res) => {
+    const stats = await callStorage(storage, 'getStats');
+    res.json({ ...stats, config: publicConfig(config) });
+  }));
+
   // Paginated events
-  router.get('/api/events', (req, res) => {
+  router.get('/api/events', asyncRoute(async (req, res) => {
     const page = Math.max(1, parseInt(req.query.page) || 1);
     const perPage = Math.min(100, Math.max(5, parseInt(req.query.perPage) || 20));
     const riskLevel = req.query.riskLevel || null;
     if (typeof storage.getEvents === 'function') {
-      res.json(storage.getEvents({ page, perPage, riskLevel }));
+      res.json(await callStorage(storage, 'getEvents', { page, perPage, riskLevel }));
     } else {
       const events = (storage.events || []).filter((e) => !riskLevel || e.riskLevel === riskLevel);
       res.json(paginateArray(events, page, perPage));
     }
-  });
+  }));
 
   // Paginated clients
-  router.get('/api/clients', (req, res) => {
+  router.get('/api/clients', asyncRoute(async (req, res) => {
     const page = Math.max(1, parseInt(req.query.page) || 1);
     const perPage = Math.min(100, Math.max(5, parseInt(req.query.perPage) || 20));
     if (typeof storage.getClients === 'function') {
-      res.json(storage.getClients({ page, perPage }));
+      res.json(await callStorage(storage, 'getClients', { page, perPage }));
     } else {
       const clients = Array.from((storage.clients || new Map()).values()).sort(
         (a, b) => b.requestCount - a.requestCount
       );
       res.json(paginateArray(clients, page, perPage));
     }
-  });
+  }));
 
   // Paginated blocked IPs with status filter
-  router.get('/api/blocked', (req, res) => {
+  router.get('/api/blocked', asyncRoute(async (req, res) => {
     const page = Math.max(1, parseInt(req.query.page) || 1);
     const perPage = Math.min(100, Math.max(5, parseInt(req.query.perPage) || 20));
     const status = req.query.status || 'all';
     if (typeof storage.getBlockedIps === 'function') {
-      res.json(storage.getBlockedIps({ page, perPage, status }));
+      res.json(await callStorage(storage, 'getBlockedIps', { page, perPage, status }));
     } else {
-      res.json(storage.getBlockedIps({ page, perPage, status }));
+      res.json(await callStorage(storage, 'getBlockedIps', { page, perPage, status }));
     }
-  });
+  }));
 
   // Paginated alerts
-  router.get('/api/alerts', (req, res) => {
+  router.get('/api/alerts', asyncRoute(async (req, res) => {
     const page = Math.max(1, parseInt(req.query.page) || 1);
     const perPage = Math.min(100, Math.max(5, parseInt(req.query.perPage) || 20));
     const dismissed = req.query.dismissed === 'true';
     if (typeof storage.getAlerts === 'function') {
-      res.json(storage.getAlerts({ page, perPage, dismissed }));
+      res.json(await callStorage(storage, 'getAlerts', { page, perPage, dismissed }));
     } else {
       res.json(paginateArray([], page, perPage));
     }
-  });
+  }));
 
   // Unblock / Delete Block for an IP
   router.post('/api/unblock', (req, res) => {
@@ -711,6 +717,27 @@ function formatThreatLabel(name) {
   return cleaned.length > 12 ? cleaned.slice(0, 11) + '..' : cleaned;
 }
 
+async function apiJson(url, options) {
+  const res = await fetch(url, Object.assign({ cache: 'no-store' }, options || {}));
+  if (res.status === 401) {
+    window.location.href = BASE + '/login';
+    throw new Error('Dashboard session expired');
+  }
+  let data = {};
+  try { data = await res.json(); } catch (_) { /* non-json response */ }
+  if (!res.ok) throw new Error(data.error || ('Request failed with status ' + res.status));
+  return data;
+}
+
+function normalizePageData(pageData) {
+  const data = pageData && typeof pageData === 'object' ? pageData : {};
+  const total = Number.isFinite(Number(data.total)) ? Number(data.total) : 0;
+  const perPage = Number.isFinite(Number(data.perPage)) && Number(data.perPage) > 0 ? Number(data.perPage) : 20;
+  const totalPages = Math.max(1, Number.isFinite(Number(data.totalPages)) ? Number(data.totalPages) : Math.ceil(total / perPage) || 1);
+  const page = Math.max(1, Math.min(Number.isFinite(Number(data.page)) ? Number(data.page) : 1, totalPages));
+  return { ...data, data: Array.isArray(data.data) ? data.data : [], total, perPage, totalPages, page };
+}
+
 // -------------------------------------------------------------------------
 // Navigation & Panel Memory
 // -------------------------------------------------------------------------
@@ -826,13 +853,13 @@ async function doToggleBlock(ip, shouldBlock, reason = 'manual_action', duration
 
   try {
     if (shouldBlock) {
-      await fetch(BASE + '/api/block', {
+      await apiJson(BASE + '/api/block', {
         method: 'POST',
         headers: { 'content-type': 'application/json' },
         body: JSON.stringify({ ip, reason: reason || 'manual_action', durationMs })
       });
     } else {
-      await fetch(BASE + '/api/unblock', {
+      await apiJson(BASE + '/api/unblock', {
         method: 'POST',
         headers: { 'content-type': 'application/json' },
         body: JSON.stringify({ ip })
@@ -858,8 +885,7 @@ async function doToggleBlock(ip, shouldBlock, reason = 'manual_action', duration
 
 async function loadStats() {
   try {
-    const res = await fetch(BASE + '/api/stats');
-    const data = await res.json();
+    const data = await apiJson(BASE + '/api/stats');
 
     refreshMs = Number(data.config?.dashboard?.refreshMs || refreshMs);
     document.getElementById('refreshLabel').textContent = Math.round(refreshMs / 1000) + 's';
@@ -954,8 +980,7 @@ async function loadEvents(page) {
   const risk = document.getElementById('eventRiskFilter')?.value || '';
   try {
     const url = BASE + '/api/events?page=' + currentPage.events + '&perPage=20' + (risk ? '&riskLevel=' + risk : '');
-    const res = await fetch(url);
-    const data = await res.json();
+    const data = normalizePageData(await apiJson(url));
     rawEventsData = data.data || [];
     const tbody = document.getElementById('eventRows');
     if (!rawEventsData.length) {
@@ -1103,8 +1128,7 @@ function toggleEventDetail(id) {
 async function loadClients(page) {
   currentPage.clients = page || currentPage.clients;
   try {
-    const res = await fetch(BASE + '/api/clients?page=' + currentPage.clients + '&perPage=20');
-    const data = await res.json();
+    const data = normalizePageData(await apiJson(BASE + '/api/clients?page=' + currentPage.clients + '&perPage=20'));
     const tbody = document.getElementById('clientRows');
     if (!data.data?.length) {
       tbody.innerHTML = '<tr><td class="px-4 py-4 text-gray-400 text-center" colspan="9">No clients recorded</td></tr>';
@@ -1137,8 +1161,7 @@ async function loadBlocked(page) {
   currentPage.blocked = page || currentPage.blocked;
   const status = document.getElementById('blockedStatusFilter')?.value || 'all';
   try {
-    const res = await fetch(BASE + '/api/blocked?page=' + currentPage.blocked + '&perPage=20&status=' + status);
-    const data = await res.json();
+    const data = normalizePageData(await apiJson(BASE + '/api/blocked?page=' + currentPage.blocked + '&perPage=20&status=' + status));
     const tbody = document.getElementById('blockedRows');
     if (!data.data?.length) {
       tbody.innerHTML = '<tr><td class="px-4 py-4 text-gray-400 text-center" colspan="8">No IP addresses recorded in blocklist</td></tr>';
@@ -1183,7 +1206,7 @@ async function loadBlocked(page) {
 async function doDeleteBlock(ip) {
   if (!confirm('Permanently remove IP ' + ip + ' from block history?')) return;
   try {
-    await fetch(BASE + '/api/unblock', {
+    await apiJson(BASE + '/api/unblock', {
       method: 'POST',
       headers: { 'content-type': 'application/json' },
       body: JSON.stringify({ ip })
@@ -1202,8 +1225,7 @@ async function doDeleteBlock(ip) {
 async function loadAlerts(page) {
   currentPage.alerts = page || currentPage.alerts;
   try {
-    const res = await fetch(BASE + '/api/alerts?page=' + currentPage.alerts + '&perPage=20');
-    const data = await res.json();
+    const data = normalizePageData(await apiJson(BASE + '/api/alerts?page=' + currentPage.alerts + '&perPage=20'));
     const tbody = document.getElementById('alertRows');
     if (!data.data?.length) {
       tbody.innerHTML = '<tr><td class="px-4 py-4 text-gray-400 text-center" colspan="8">No active alerts</td></tr>';
@@ -1231,7 +1253,7 @@ async function loadAlerts(page) {
 
 async function doDismiss(clientId) {
   try {
-    await fetch(BASE + '/api/alerts/' + encodeURIComponent(clientId) + '/dismiss', { method: 'POST' });
+    await apiJson(BASE + '/api/alerts/' + encodeURIComponent(clientId) + '/dismiss', { method: 'POST' });
     loadAlerts(currentPage.alerts);
     loadStats();
   } catch(e) { console.error('Dismiss error', e); }
@@ -1261,8 +1283,7 @@ async function submitBlock() {
 
 async function loadSettings() {
   try {
-    const res = await fetch(BASE + '/api/settings');
-    const data = await res.json();
+    const data = await apiJson(BASE + '/api/settings');
     if (data.security) selectMode(data.security);
   } catch(e) { console.error('Load settings error', e); }
 }
@@ -1283,12 +1304,11 @@ document.getElementById('settingsForm').addEventListener('submit', async functio
   if (modeEl) payload.security = modeEl.value;
 
   try {
-    const res = await fetch(BASE + '/api/settings', {
+    const updated = await apiJson(BASE + '/api/settings', {
       method: 'POST',
       headers: { 'content-type': 'application/json' },
       body: JSON.stringify(payload)
     });
-    const updated = await res.json();
     if (updated.security) selectMode(updated.security);
 
     const msg = document.getElementById('settingsMsg');
@@ -1376,9 +1396,15 @@ function renderChart(rows) {
 // -------------------------------------------------------------------------
 
 function renderPagination(containerId, pageData, loadFn) {
+  pageData = normalizePageData(pageData);
   const container = document.getElementById(containerId);
-  if (!container || pageData.totalPages <= 1) {
-    if (container) container.innerHTML = '';
+  if (!container) return;
+  if (pageData.total === 0) {
+    container.innerHTML = '<div class="text-xs text-gray-500 font-medium">Showing <strong>0</strong> records</div>';
+    return;
+  }
+  if (pageData.totalPages <= 1) {
+    container.innerHTML = \`<div class="text-xs text-gray-500 font-medium">Showing <strong>1-\${fmt.format(pageData.total)}</strong> of <strong>\${fmt.format(pageData.total)}</strong> records</div>\`;
     return;
   }
   const { page, totalPages, total, perPage } = pageData;
@@ -1561,7 +1587,15 @@ function iconAlert()   { return '<svg class="w-5 h-5 text-blue-600" fill="none"
 function dashboardAuth(options = {}) {
   const username = options.username || 'admin';
   const password = options.password || 'admin';
-  const token = randomBytes(32).toString('hex');
+  const sessionSecret =
+    options.sessionSecret ||
+    process.env.IRI_SHIELD_DASHBOARD_SECRET ||
+    process.env.SESSION_SECRET ||
+    process.env.JWT_SECRET ||
+    `${username}:${password}`;
+  const token = createHmac('sha256', String(sessionSecret))
+    .update(`iri-shield-dashboard:${username}:${password}`)
+    .digest('hex');
   return {
     token,
     canLogin(inputUser, inputPass) {
@@ -1573,6 +1607,20 @@ function dashboardAuth(options = {}) {
   };
 }
 
+function asyncRoute(handler) {
+  return function routeHandler(req, res, next) {
+    Promise.resolve(handler(req, res, next)).catch(next);
+  };
+}
+
+async function callStorage(storage, method, ...args) {
+  if (storage.ready && typeof storage.ready.then === 'function') {
+    await storage.ready;
+  }
+  const result = storage[method](...args);
+  return result && typeof result.then === 'function' ? await result : result;
+}
+
 function applyDashboardSettings(config, body) {
   const numberFields = [
     ['rateLimit.max', 1, 100000],
@@ -1626,6 +1674,7 @@ function applyDashboardSettings(config, body) {
 function publicConfig(config) {
   const copy = JSON.parse(JSON.stringify(config));
   if (copy.dashboard?.password) copy.dashboard.password = '';
+  if (copy.dashboard?.sessionSecret) copy.dashboard.sessionSecret = '';
   return copy;
 }
 

package/src/index.js

@@ -651,6 +651,7 @@ function mergeInto(target, patch) {
 function sanitizeConfig(config) {
   const copy = JSON.parse(JSON.stringify(config));
   if (copy.dashboard && copy.dashboard.password) copy.dashboard.password = '';
+  if (copy.dashboard && copy.dashboard.sessionSecret) copy.dashboard.sessionSecret = '';
   return copy;
 }
 

package/src/mongodb-storage.js

@@ -19,8 +19,8 @@ class MongoStorage extends MemoryStorage {
     this.db = null;
     this._cols = {};
 
-    // Start connection asynchronously — does not block constructor
-    this._connect();
+    // Start connection asynchronously — does not block constructor.
+    this.ready = this._connect();
   }
 
   async _connect() {
@@ -47,8 +47,8 @@ class MongoStorage extends MemoryStorage {
       // Initialize collections and TTL indexes
       await this._initCollections();
 
-      // Load persistent blocks into memory
-      await this._loadPersistentBlocks();
+      // Warm the in-memory dashboard cache after cold starts.
+      await this._loadAllPersistentData();
 
       console.log('[iri-shield] MongoDB connected:', this.mongoUrl);
     } catch (err) {
@@ -86,6 +86,14 @@ class MongoStorage extends MemoryStorage {
     this._cols = { requests, events, clients, blocks, alerts };
   }
 
+  async _loadAllPersistentData() {
+    await this._loadPersistentBlocks();
+    await this._loadPersistentClients();
+    await this._loadPersistentAlerts();
+    await this._loadPersistentEvents();
+    await this._loadPersistentRequests();
+  }
+
   async _loadPersistentBlocks() {
     if (!this.connected) return;
     try {
@@ -104,6 +112,86 @@ class MongoStorage extends MemoryStorage {
     } catch { /* ignore */ }
   }
 
+  async _loadPersistentClients() {
+    if (!this.connected) return;
+    try {
+      const rows = await this._cols.clients.find({}).sort({ requestCount: -1 }).limit(this.maxClients).toArray();
+      for (const row of rows) {
+        if (row.clientId) this.clients.set(row.clientId, stripMongoId(row));
+      }
+    } catch { /* ignore */ }
+  }
+
+  async _loadPersistentAlerts() {
+    if (!this.connected) return;
+    try {
+      const rows = await this._cols.alerts.find({}).sort({ lastAlertAt: -1 }).limit(this.maxClients).toArray();
+      for (const row of rows) {
+        if (row.clientId) this.alerts.set(row.clientId, stripMongoId(row));
+      }
+    } catch { /* ignore */ }
+  }
+
+  async _loadPersistentEvents() {
+    if (!this.connected) return;
+    try {
+      const rows = await this._cols.events.find({}).sort({ timestamp: -1, createdAt: -1 }).limit(this.maxEvents).toArray();
+      this.events = rows.map(stripMongoId);
+      this.threatDistribution = new Map();
+      for (const event of this.events) {
+        const threat = event.threat || 'unknown';
+        this.threatDistribution.set(threat, (this.threatDistribution.get(threat) || 0) + 1);
+      }
+    } catch { /* ignore */ }
+  }
+
+  async _loadPersistentRequests() {
+    if (!this.connected) return;
+    try {
+      const rows = await this._cols.requests.find({}).sort({ createdAt: -1 }).limit(this.maxRequests).toArray();
+      this.requests = rows.map(stripMongoId);
+      const totals = await this._cols.requests.aggregate([
+        {
+          $group: {
+            _id: null,
+            totalRequests: { $sum: 1 },
+            blockedRequests: { $sum: { $cond: ['$blocked', 1, 0] } },
+            totalLatencyMs: { $sum: { $ifNull: ['$durationMs', 0] } }
+          }
+        }
+      ]).next();
+      this.totalRequests = totals?.totalRequests || this.requests.length;
+      this.blockedRequests = totals?.blockedRequests || 0;
+      this.totalLatencyMs = totals?.totalLatencyMs || 0;
+
+      const endpoints = await this._cols.requests.aggregate([
+        {
+          $group: {
+            _id: { method: '$method', endpoint: '$endpoint' },
+            count: { $sum: 1 },
+            errors: { $sum: { $cond: [{ $gte: ['$statusCode', 400] }, 1, 0] } },
+            avgLatencyMs: { $avg: '$durationMs' }
+          }
+        },
+        { $sort: { count: -1 } },
+        { $limit: 20 }
+      ]).toArray();
+
+      this.endpointStats = new Map();
+      for (const row of endpoints) {
+        const method = row._id?.method || 'GET';
+        const endpoint = row._id?.endpoint || '/';
+        this.endpointStats.set(`${method} ${endpoint}`, {
+          method,
+          endpoint,
+          count: row.count || 0,
+          errors: row.errors || 0,
+          avgLatencyMs: row.avgLatencyMs || 0
+        });
+      }
+    } catch { /* ignore */ }
+  }
+
   // ---------------------------------------------------------------------------
   // Helpers
   // ---------------------------------------------------------------------------
@@ -120,9 +208,11 @@ class MongoStorage extends MemoryStorage {
 
   recordRequest(request) {
     super.recordRequest(request);
+    const timestamp = new Date().toISOString();
     this._safe(() =>
       this._cols.requests.insertOne({
         ...request,
+        timestamp,
         createdAt: new Date(),
         blocked: Boolean(request.blocked)
       })
@@ -220,6 +310,62 @@ class MongoStorage extends MemoryStorage {
     return result;
   }
 
+  async getEvents({ page = 1, perPage = 20, riskLevel = null } = {}) {
+    if (!this.connected) return super.getEvents({ page, perPage, riskLevel });
+    await this.ready;
+    if (!this.connected) return super.getEvents({ page, perPage, riskLevel });
+    try {
+      const filter = riskLevel ? { riskLevel } : {};
+      const total = await this._cols.events.countDocuments(filter);
+      const data = await this._cols.events
+        .find(filter)
+        .sort({ timestamp: -1, createdAt: -1 })
+        .skip((Math.max(1, page) - 1) * perPage)
+        .limit(perPage)
+        .toArray();
+      return paginateMongo(data, total, page, perPage);
+    } catch {
+      return super.getEvents({ page, perPage, riskLevel });
+    }
+  }
+
+  async getClients({ page = 1, perPage = 20 } = {}) {
+    if (!this.connected) return super.getClients({ page, perPage });
+    await this.ready;
+    if (!this.connected) return super.getClients({ page, perPage });
+    try {
+      const total = await this._cols.clients.countDocuments({});
+      const data = await this._cols.clients
+        .find({})
+        .sort({ requestCount: -1, lastSeenAt: -1 })
+        .skip((Math.max(1, page) - 1) * perPage)
+        .limit(perPage)
+        .toArray();
+      return paginateMongo(data, total, page, perPage);
+    } catch {
+      return super.getClients({ page, perPage });
+    }
+  }
+
+  async getAlerts({ page = 1, perPage = 20, dismissed = false } = {}) {
+    if (!this.connected) return super.getAlerts({ page, perPage, dismissed });
+    await this.ready;
+    if (!this.connected) return super.getAlerts({ page, perPage, dismissed });
+    try {
+      const filter = { dismissed: Boolean(dismissed) };
+      const total = await this._cols.alerts.countDocuments(filter);
+      const data = await this._cols.alerts
+        .find(filter)
+        .sort({ lastAlertAt: -1, updatedAt: -1 })
+        .skip((Math.max(1, page) - 1) * perPage)
+        .limit(perPage)
+        .toArray();
+      return paginateMongo(data, total, page, perPage);
+    } catch {
+      return super.getAlerts({ page, perPage, dismissed });
+    }
+  }
+
   // ---------------------------------------------------------------------------
   // Stats
   // ---------------------------------------------------------------------------
@@ -235,3 +381,21 @@ class MongoStorage extends MemoryStorage {
 }
 
 module.exports = { MongoStorage };
+
+function stripMongoId(row) {
+  if (!row) return row;
+  const { _id, ...rest } = row;
+  return rest;
+}
+
+function paginateMongo(rows, total, page, perPage) {
+  const totalPages = Math.ceil(total / perPage) || 1;
+  const safePage = Math.max(1, Math.min(page, totalPages));
+  return {
+    data: rows.map(stripMongoId),
+    total,
+    page: safePage,
+    perPage,
+    totalPages
+  };
+}