NovaVantage Backend Reference

Purpose

Detects scanners and automated attacks by trapping requests to known exploit paths before they reach any real route handler. Applied globally via LoggerModule.configure — runs first, before CorrelationMiddleware.

Behavior

Compares req.path.toLowerCase() against the HONEYPOT_PATHS set (e.g. /.env, /.git, /wp-admin, /phpmyadmin, /actuator). On match: logs a warn with tags HONEYPOT_HIT, SECURITY, plus honeypotPath, ip, userAgent, method. Responds 404 with { success: false, data: null, error: 'Not Found' }. Does not call next() — request ends here.

Steps (in order)

1. IP: reads x-forwarded-for first segment, else req.socket.remoteAddress.
2. Sets CLS: ip, userAgent, route (originalUrl), method.
3. Geo: GeoIpService.lookup(ip) → sets geoCountry, geoCity, geoFlag.
4. JWT: If Authorization: Bearer present — verifies with JWT_SECRET. On success sets userId, studentId, isGhostAdmin. On failure: silent (no throw).
5. Entity IDs: EntityContextService.extract(req) → sets entityIds on CLS if non-empty.
6. Calls next().

Fields extracted from JWT payload

Resolution logic

Uses geoip-lite (offline DB). Normalizes IPv4-mapped IPv6 addresses (::ffff:x). Private IPs return { country: 'LOCAL', city: 'localhost', flag: '🏠' }. Public IPs return ISO country, city, and a flag emoji derived from regional indicator codepoints.

Fields on the CLS store

Log levels & methods

Automatic context merging

Every write() call builds LogContext via getContext() and passes it to Winston. This means correlationId, userId, geo, route and all CLS fields are merged automatically — you never need to pass them manually when logging inside a request.

Transports (all attached to main logger)

Behavior

Skips non-HTTP contexts. On first request: calls BootBannerService.recordFirstRequest() to record TTFR on the deployment fingerprint.

AllExceptionsFilter (500+)

Catches everything for HTTP. Status from HttpException or 500. If status ≥ 500: logger.fatal with tags UNHANDLED_EXCEPTION, FATAL, stack, path, method. Response: { success: false, data: null, error: message }.

DomainExceptionFilter (4xx — "Shadow")

Catches only HttpException. For status 400–499: logger.warn with 👻 [SHADOW], tags SHADOW_EXCEPTION, full stack. Implements "shadow tracking" — client errors are tracked without treating them as server crashes.

Frontend log ingestion pipeline

1. Validates payload via Zod (clientLogPayloadSchema): level, message (1–2000 chars), optional stack, context, rrwebEvents (max 500).
2. PiiRedactorService.redact(payload) on full payload.
3. Logs via NovaLogger at appropriate level with tags CLIENT_LOG.
4. If rrwebEvents non-empty and userId set: stores session via RrwebSessionService (in-memory Map, max 500 sessions).
5. Returns { correlationId: "client-{Date.now()}", replayUrl }.

Services

Slash Commands

Schema — collection: audit_logs

Indexes

actor.id + createdAt · action + createdAt · TTL on createdAt (expireAfterSeconds: 7,776,000)

How it works

Call recordRequest() to increment a per-minute counter. The @Cron(EVERY_MINUTE) checkPulse method: rolls the minute bucket, skips if fewer than 10 buckets, computes baseline as average of all buckets, compares latest minute to baseline.

If deviation > 40%: logs 📈 SPIKE or 📉 DROP with tag PULSE_ANOMALY. Keeps up to 1440 snapshots (~24h) in history.

dispatch(alert) flow

1. Key = alert.errorSignature ?? alert.title.
2. rateLimiter.shouldAlert(signature) — if false, muted.
3. If severity === CRITICAL: stateSnapshot.capture('fatal').
4. Expand ALL channels → Discord + Email + Monday.
5. Parallel Promise.allSettled: Resend (email), Monday.com.

Alert Rate Limiter

Per signature: within 60 seconds, if more than 3 alerts → mute for another 60s. muteSignature(sig, 3_600_000) used by Discord's "Mute 1hr" button.

Error Signature deduplication

ErrorSignatureService.evaluate(error): strips line numbers + node_modules frames, SHA-256 hex slice(0,16). New errors → escalate to ALL channels. Known errors → Discord only.

PiiRedactorService

Recursively walks objects (max depth 10). Keys matching PII_SENSITIVE_KEYS (case-insensitive) → [REDACTED]. Strings: regex replace for email, phone, IPv4 patterns → [REDACTED]. Strings > 5120 bytes truncated first. Used automatically by ClientBridgeService and GdprSanitizerService.

PayloadTruncatorService

Deep truncation: max depth 8, strings 5120 chars, arrays max 50 items, objects max 100 keys, Buffer summarized. Not auto-applied to every Winston log — call manually when logging large objects.

trackApiCost(userId, service, estimatedCost)

Rolling hourly bucket per user. Logs each track with tag COST_TRACKED. If hourly total > $10 USD: logs 💸 [FINANCIAL_ALERT]. Call from code that wraps OpenAI / Resend / etc. with estimated USD cost.

recordUserError(userId)

Keeps timestamps in a 2-minute (120,000ms) sliding window. If count ≥ 5 errors and not yet alerted: logs 😤 [FRUSTRATION]. Resets alerted when count drops back below threshold. Call from shadow filter or auth failure handler.

Daily OpenAI analysis

Requires OPENAI_API_KEY env var. Every day at 06:00: loads 100 recent audit docs via AuditService.getRecent(100), builds a text summary of actions + metadata snippets, calls OpenAI gpt-4o-mini with a DevOps-style system prompt. Logs result as system with tag 🔮 [PREDICTIVE_WARNING].

recordFailedAuth(ip, userId?)

5-minute sliding window per IP. Each failure logs 🛡️ [SECURITY]. At ≥ 5 failures: logs 🚨 brute-force style error. Call from your auth failure path.

API

Behavior

isGhostAdmin() reads CLS isGhostAdmin (from JWT ghostMode). activateForCurrentRequest() sets CLS flag manually. DiscordFeedService.sendLog drops messages when isGhostAdmin is true — reduces noise for admin ghost actions.

scrubExpiredPii (cron)

Finds audit docs with createdAt older than 14 days (batch 1000). Redacts metadata via PiiRedactorService, then updateOne.

purgeUserData(userId)

deleteMany on actor.id. Returns count. Logs purge action for audit trail.

API

reportState(serviceName, newState, reason?)

On state change, pushes to history (max 500 entries). Logs: OPEN as ⚡ [CIRCUIT_OPEN], HALF_OPEN as 🔄, CLOSED as ✅. Methods: getState, getHistory, getAllStates for diagnostics. Call from your resilience layer (e.g. opossum).

capture(reason?)

Reasons: 'fatal' (default) | 'health-check' | 'diagnostic'. Captures: heap used/total (MB), RSS, external, uptime (s), PID, Node version, NODE_ENV, active handle count, CPU user/system (ms). Logs as system level with distinct message per reason.