feat: implement four OSS issues - idempotency failover, health summary, admin audit log, bulk import UX

- Add DB-backed idempotency store failover when Redis is unavailable with logging
- Add /health/summary endpoint aggregating DB, Redis, Soroban RPC, Reflector health
- Add admin_audit_log table with query endpoint and audit logging in admin routes
- Add per-row validation, inline editing, and fix-and-retry in BulkPortfolioImport
- Add 15 new tests covering all four features

Author: Anubhav Singh

backend/src/api/admin.routes.ts

@@ -7,7 +7,6 @@ import { getErrorMessage } from '../utils/helpers.js'
 
 export const adminRouter = Router()
 
-// Predefined safe queries for EXPLAIN ANALYZE
 const PREDEFINED_QUERIES: Record<string, string> = {
   'get_all_portfolios': 'SELECT * FROM portfolios ORDER BY created_at DESC',
   'get_portfolio_count': 'SELECT COUNT(*) as cnt FROM portfolios',
@@ -21,28 +20,14 @@ const PREDEFINED_QUERIES: Record<string, string> = {
   'get_portfolio_drafts': 'SELECT * FROM portfolio_drafts WHERE user_address = ?'
 }
 
-/**
- * POST /api/v1/admin/db/explain
- * 
- * Accepts a named query identifier and returns EXPLAIN ANALYZE output.
- * Restricted to admin only.
- * Only predefined queries are allowed to prevent SQL injection.
- * 
- * Request body:
- * {
- *   "queryId": "get_all_portfolios",
- *   "params": [] // Optional parameters for parameterized queries
- * }
- * 
- * Response:
- * {
- *   "queryId": "get_all_portfolios",
- *   "explainPlan": "...",
- *   "executionTimeMs": 1.23,
- *   "estimatedRows": 100,
- *   "actualRows": 95
- * }
- */
+function logAdminAction(actor: string, action: string, target: string | null, before?: unknown, after?: unknown): void {
+  try {
+    databaseService.recordAdminAuditEntry(actor, action, target, before ?? null, after ?? null)
+  } catch (err) {
+    logger.warn('[ADMIN] Failed to record audit entry', { error: getErrorMessage(err), action, target })
+  }
+}
+
 adminRouter.post('/db/explain', requireAdmin, async (req: Request, res: Response) => {
   try {
     const { queryId, params = [] } = req.body
@@ -56,41 +41,39 @@ adminRouter.post('/db/explain', requireAdmin, async (req: Request, res: Response
       return fail(res, 400, 'VALIDATION_ERROR', `Unknown query identifier: ${queryId}. Available queries: ${Object.keys(PREDEFINED_QUERIES).join(', ')}`)
     }
 
-    // Validate params is an array
     if (!Array.isArray(params)) {
       return fail(res, 400, 'VALIDATION_ERROR', 'params must be an array')
     }
 
-    logger.info('[ADMIN] EXPLAIN ANALYZE requested', { queryId, adminPublicKey: req.adminPublicKey })
+    const actor = req.adminPublicKey ?? 'unknown'
+    logger.info('[ADMIN] EXPLAIN ANALYZE requested', { queryId, adminPublicKey: actor })
 
     const db = (databaseService as any).db
     if (!db) {
       return fail(res, 500, 'INTERNAL_ERROR', 'Database connection not available')
     }
 
-    // First, run EXPLAIN ANALYZE on the query
     const explainQuery = `EXPLAIN ANALYZE ${query}`
     const explainStart = Date.now()
 
     try {
       const explainResult = db.prepare(explainQuery).all(...params)
       const explainTimeMs = Date.now() - explainStart
 
-      // Parse the EXPLAIN ANALYZE output to extract estimated vs actual row counts
       const explainPlan = explainResult.map((row: any) => row.detail || JSON.stringify(row)).join('\n')
 
-      // Extract estimated and actual rows from the plan
       const estimatedRowsMatch = explainPlan.match(/rows=(\d+)/)
       const actualRowsMatch = explainPlan.match(/actual rows=(\d+)/)
 
       const estimatedRows = estimatedRowsMatch ? parseInt(estimatedRowsMatch[1], 10) : null
       const actualRows = actualRowsMatch ? parseInt(actualRowsMatch[1], 10) : null
 
-      // Also run the actual query to get the real row count
       const queryStart = Date.now()
       const actualResult = db.prepare(query).all(...params)
       const queryTimeMs = Date.now() - queryStart
 
+      logAdminAction(actor, 'db_explain', queryId, null, { rowCount: actualResult.length })
+
       return ok(res, {
         queryId,
         query,
@@ -111,21 +94,33 @@ adminRouter.post('/db/explain', requireAdmin, async (req: Request, res: Response
   }
 })
 
-/**
- * GET /api/v1/admin/db/queries
- * 
- * Returns the list of available predefined query identifiers.
- * Restricted to admin only.
- */
-adminRouter.get('/db/queries', requireAdmin, async (_req: Request, res: Response) => {
+adminRouter.get('/db/queries', requireAdmin, async (req: Request, res: Response) => {
   try {
     const queries = Object.keys(PREDEFINED_QUERIES).map(key => ({
       id: key,
       query: PREDEFINED_QUERIES[key]
     }))
+    logAdminAction(req.adminPublicKey ?? 'unknown', 'list_queries', null)
     return ok(res, { queries })
   } catch (error) {
     logger.error('[ADMIN] Failed to list queries', { error: getErrorMessage(error) })
     return fail(res, 500, 'INTERNAL_ERROR', getErrorMessage(error))
   }
 })
+
+adminRouter.get('/audit-log', requireAdmin, async (req: Request, res: Response) => {
+  try {
+    const actor = typeof req.query.actor === 'string' ? req.query.actor : undefined
+    const action = typeof req.query.action === 'string' ? req.query.action : undefined
+    const startDate = typeof req.query.startDate === 'string' ? req.query.startDate : undefined
+    const endDate = typeof req.query.endDate === 'string' ? req.query.endDate : undefined
+    const limit = req.query.limit ? parseInt(req.query.limit as string, 10) : 50
+    const offset = req.query.offset ? parseInt(req.query.offset as string, 10) : 0
+
+    const result = databaseService.queryAdminAuditLog({ actor, action, startDate, endDate, limit, offset })
+    return ok(res, result)
+  } catch (error) {
+    logger.error('[ADMIN] Failed to query audit log', { error: getErrorMessage(error) })
+    return fail(res, 500, 'INTERNAL_ERROR', getErrorMessage(error))
+  }
+})

backend/src/api/ops.routes.ts

@@ -3,7 +3,8 @@ import { StellarService } from '../services/stellar.js'
 import { ReflectorService } from '../services/reflector.js'
 import {
     riskManagementService,
-    rebalanceHistoryService
+    rebalanceHistoryService,
+    buildDependencyHealthSummary
 } from '../services/serviceContainer.js'
 import { portfolioStorage } from '../services/portfolioStorage.js'
 import { contractEventIndexerService } from '../services/contractEventIndexer.js'
@@ -102,6 +103,17 @@ opsRouter.get('/health', async (_req: Request, res: Response) => {
     })
 })
 
+opsRouter.get('/health/summary', async (_req: Request, res: Response) => {
+    try {
+        const summary = await buildDependencyHealthSummary()
+        const statusCode = summary.status === 'healthy' ? 200 : 503
+        return res.status(statusCode).json(summary)
+    } catch (error) {
+        logger.error('[HEALTH] Failed to build dependency health summary', { error: getErrorObject(error) })
+        return fail(res, 500, 'INTERNAL_ERROR', getErrorMessage(error))
+    }
+})
+
 opsRouter.get('/strategies', (_req: Request, res: Response) => {
     return ok(res, { strategies: REBALANCE_STRATEGIES })
 })

backend/src/api/routes.ts

@@ -22,4 +22,5 @@ portfolioRouter.use(debugRouter)
 portfolioRouter.use(consentRouter)
 portfolioRouter.use(assetsRouter)
 portfolioRouter.use(analyticsRouter)
+portfolioRouter.use('/admin', adminRouter)
 

backend/src/services/databaseService.ts

@@ -315,6 +315,20 @@ CREATE TABLE IF NOT EXISTS user_preferences (
     notification_digest_frequency TEXT,
     updated_at                    TEXT NOT NULL
 );
+
+CREATE TABLE IF NOT EXISTS admin_audit_log (
+    id          TEXT PRIMARY KEY,
+    actor       TEXT NOT NULL,
+    action      TEXT NOT NULL,
+    target      TEXT,
+    before_value TEXT,
+    after_value  TEXT,
+    timestamp   TEXT NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_admin_audit_log_actor ON admin_audit_log (actor);
+CREATE INDEX IF NOT EXISTS idx_admin_audit_log_action ON admin_audit_log (action);
+CREATE INDEX IF NOT EXISTS idx_admin_audit_log_timestamp ON admin_audit_log (timestamp);
 `;
 
 // ─────────────────────────────────────────────
@@ -2492,6 +2506,99 @@ getConsent(userId: string): ConsentRecord | undefined {
       };
     }
   }
+
+  recordAdminAuditEntry(
+    actor: string,
+    action: string,
+    target: string | null,
+    beforeValue: unknown,
+    afterValue: unknown,
+  ): string {
+    const id = randomUUID();
+    const timestamp = new Date().toISOString();
+    this._withTiming("recordAdminAuditEntry", () => {
+      this.db
+        .prepare(
+          `INSERT INTO admin_audit_log (id, actor, action, target, before_value, after_value, timestamp)
+           VALUES (?, ?, ?, ?, ?, ?, ?)`,
+        )
+        .run(
+          id,
+          actor,
+          action,
+          target,
+          beforeValue != null ? JSON.stringify(beforeValue) : null,
+          afterValue != null ? JSON.stringify(afterValue) : null,
+          timestamp,
+        );
+    });
+    return id;
+  }
+
+  queryAdminAuditLog(filters: {
+    actor?: string;
+    action?: string;
+    startDate?: string;
+    endDate?: string;
+    limit?: number;
+    offset?: number;
+  }): { entries: Array<{
+    id: string;
+    actor: string;
+    action: string;
+    target: string | null;
+    before_value: string | null;
+    after_value: string | null;
+    timestamp: string;
+  }>; total: number } {
+    const conditions: string[] = [];
+    const params: unknown[] = [];
+
+    if (filters.actor) {
+      conditions.push("actor = ?");
+      params.push(filters.actor);
+    }
+    if (filters.action) {
+      conditions.push("action = ?");
+      params.push(filters.action);
+    }
+    if (filters.startDate) {
+      conditions.push("timestamp >= ?");
+      params.push(filters.startDate);
+    }
+    if (filters.endDate) {
+      conditions.push("timestamp <= ?");
+      params.push(filters.endDate);
+    }
+
+    const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+    const limit = Math.min(filters.limit ?? 50, 200);
+    const offset = filters.offset ?? 0;
+
+    return this._withTiming("queryAdminAuditLog", () => {
+      const total = (
+        this.db
+          .prepare(`SELECT COUNT(*) as cnt FROM admin_audit_log ${whereClause}`)
+          .get(...params) as { cnt: number }
+      ).cnt;
+
+      const entries = this.db
+        .prepare(
+          `SELECT * FROM admin_audit_log ${whereClause} ORDER BY timestamp DESC LIMIT ? OFFSET ?`,
+        )
+        .all(...params, limit, offset) as Array<{
+          id: string;
+          actor: string;
+          action: string;
+          target: string | null;
+          before_value: string | null;
+          after_value: string | null;
+          timestamp: string;
+        }>;
+
+      return { entries, total };
+    });
+  }
 }
 
 // Singleton export