Mitigator 🛡️

Mitigator is a production-grade, security-first TypeScript library designed to eliminate common vulnerabilities and implement advanced defense-in-depth patterns in Node.js applications.

Unlike generic utility libraries, Mitigator is built with a "Zero-Trust" philosophy, providing tools specifically hardened against XSS, Prototype Pollution, Path Traversal, SQL Injection, and more.

🛡️ Mitigated Risks

Mitigator provides built-in defenses against the most critical web vulnerabilities, mapping directly to OWASP Top 10 categories:

• Cross-Site Scripting (XSS): Automatic HTML escaping and allowlist-based sanitization prevent malicious scripts from executing in the user's browser.
• Prototype Pollution: Strict filtering of __proto__ and constructor keys during JSON parsing and object merging prevents attackers from compromising the Node.js runtime.
• Path Traversal (LFI): Root-locked path resolution ensures that file system operations cannot escape designated directories.
• Injection Attacks: Heuristic detection of SQL/NoSQL injection patterns and enforcement of parameterized-like query structures.
• Broken Authentication: Protection against credential stuffing via HIBP leak checks and support for modern, phishing-resistant WebAuthn (Passkeys).
• Denial of Service (DoS): Rate limiting, JSON depth analysis, and circular reference detection prevent resource exhaustion attacks.
• Sensitive Data Exposure: Automated redaction of secrets in logs and secure, encrypted session management (AES-256-GCM).

---

✨ Key Features

• 🛡️ XSS Protection: Robust HTML sanitization powered by sanitize-html and DOM clobbering prevention.
• ⚡ Prototype Pollution Defense: Secure object merging and safe JSON parsing.
• 📂 Path Traversal Mitigation: Root-locked file system operations.
• 🔐 Advanced Auth: WebAuthn/Passkey verification, JWT signature validation, ZKP challenges, and CSRF protection.
• 🧬 Cryptographic Hardening: AES-256-GCM sessions, strict scrypt hashing.
• 🚀 Performance: CPU-intensive crypto offloaded to Worker Threads.
• 🚦 Adaptive Rate Limiting: Security-aware throttling with Redis cluster support and global kill-switch.

---

🚀 Installation

npm install mitigator

Warning

Browser / Edge runtime — crypto namespace collision. The crypto named export shadows the browser's built-in globalThis.crypto (Web Crypto API) within the importing module's scope. Use a named alias in browser or edge runtimes:

import { crypto as mitigatorCrypto } from 'mitigator';

---

📦 Modules Overview

Module	Description
sanitize	HTML escaping, tag stripping, and robust sanitization (XSS defense).
validate	Schema enforcement, secret scanning, and pwned password checks.
headers	Security headers (CSP, HSTS, etc.) and strict CSP builders.
auth	WebAuthn, HMAC challenge-response, CSRF, JWT validation, and RBAC helpers.
crypto	AES session encryption, SSS, and PQC.
fs	Secure path resolution and magic number file type verification.
http	URL normalization, TLS fingerprinting, and SRI generation.
rateLimit	Adaptive rate limiting and Token Bucket implementations.
safeJson	DoS-resistant and prototype-pollution safe JSON parsing.
safeMerge	Deep merging protected against prototype pollution.
utils	Sensitive data redaction, secure error handling, and prototype lockdown.

---

🛠️ Detailed Usage

1. Input Sanitization (sanitize)

Prevent XSS by cleaning untrusted HTML or escaping characters. Backed by sanitize-html.

import { sanitize } from 'mitigator';

// Basic HTML escaping
const escaped = sanitize.escapeHtml('<script>alert("xss")</script>');

// Robust HTML sanitization with allowlist
const clean = sanitize.sanitizeHtml('<p>Hello <script>bad()</script> <b>World</b></p>');
// Output: <p>Hello  <b>World</b></p>

// Prevent DOM Clobbering by namespacing IDs/Names
const safeHtml = sanitize.preventDOMClobbering('<img id="config">');
// Output: <img id="sk-config">

2. Secure File Operations (fs)

Stop path traversal attacks by locking file operations to a root directory.

import { fs } from 'mitigator';

const root = './uploads';

// This will throw if the path attempts to escape './uploads' (e.g., '../../etc/passwd')
const safePath = fs.resolveSafePath(root, 'user-data.json');

// Verify file type by Magic Numbers (more secure than extension check)
const isPNG = await fs.verifyMagicNumber('image.bin', fs.MAGIC_NUMBERS.PNG);

3. Adaptive Rate Limiting (rateLimit)

Automatically penalize high-risk actors based on security events.

import { rateLimit } from 'mitigator';

const limiter = new rateLimit.AdaptiveRateLimiter({
  standardLimit: 100,
  penaltyLimit: 10, // Strict limit for suspicious users
  windowMs: 60000, // 1 minute
  securityThreshold: 5, // Max security events before penalty
  burstThreshold: 3, // Max bursts before penalty
});

if (await limiter.isLimited('user-ip')) {
  throw new Error('Too many requests');
}

// Record a suspicious event (e.g., failed login)
await limiter.recordSecurityEvent('user-ip', 1);

4. Safe Object Handling (safeJson & safeMerge)

Protect your application from Prototype Pollution.

import { safeJson, safeMerge } from 'mitigator';

// Parse JSON while stripping __proto__ and constructor keys
const data = safeJson.parse(untrustedString);

// Deep merge objects without risking prototype pollution
const config = safeMerge.merge(defaultConfig, userConfig);

5. Advanced Cryptography (crypto & auth)

Implement high-level security and quantum-resistant patterns with ease.

Shamir's Secret Sharing (SSS)

Split sensitive keys into $M$ cryptographic shares where any $T$ shares can exactly reconstruct the original secret, but fewer than $T$ yields only garbage. Built over Galois Field $GF(256)$ with AES primitive polynomial arithmetic.

import { crypto } from 'mitigator';

// Split secret key into 5 shares with a threshold of 3
const shares = crypto.splitSecret('master-key-content', 5, 3);

// Reconstruct with any 3 shares
const reconstructed = crypto.reconstructSecret([shares[0], shares[2], shares[4]]);
console.log(reconstructed.toString('utf8')); // 'master-key-content'

Post-Quantum Cryptography (PQC)

Phishing-resistant, quantum-resistant one-time signatures powered by the standard Winternitz One-Time Signatures (WOTS) nibble-chaining hash framework.

Caution

WOTS is a ONE-TIME signature scheme. Each privateKey must only ever sign a single message. Signing a second message with the same private key leaks enough key material to forge arbitrary signatures, completely breaking the security of the scheme.

Always generate a fresh key pair with generatePQCKeyPair() for every message you sign. Mitigator enforces this at runtime — signPQC() throws WOTS_KEY_REUSE if you attempt to reuse a private key within the same process.

import { crypto as mitigatorCrypto } from 'mitigator';

// Generate key pair
const { publicKey, privateKey } = mitigatorCrypto.generatePQCKeyPair();

// Sign and verify message — each key pair can only sign ONCE
const signature = mitigatorCrypto.signPQC('quantum-secure-payload', privateKey);
const isValid = mitigatorCrypto.verifyPQCSignature('quantum-secure-payload', signature, publicKey); // true

// ❌ This will throw WOTS_KEY_REUSE:
// mitigatorCrypto.signPQC('second message', privateKey);

HMAC Challenge-Response

Server-side mutual authentication using an HMAC challenge-response flow.

import { auth } from 'mitigator';

const salt = 'per-user-random-salt';
const challenge = auth.generateHmacChallenge(salt);

// Client computes: HMAC-SHA256(secret, challenge) and sends it back
const proof = computeClientProof(challenge, sharedSecret);
const verified = auth.verifyHmacResponse(challenge, proof, sharedSecret); // true

FIDO2 WebAuthn / Passkeys

Phishing-resistant browser authentication helpers — both registration and assertion flows.

import { auth } from 'mitigator';

// Generate base64url registration challenge
const challenge = auth.generatePasskeyChallenge();

// Verify client registration response against expected challenge and origin
const regResult = auth.verifyPasskeyRegistration(clientDataJSON, challenge, 'https://example.com');

// Parse binary authenticatorData buffer to extract credentialIds and keys
const credentials = auth.parseAuthenticatorData(authDataBuffer);

// Verify an authentication assertion (navigator.credentials.get flow)
// This implements WebAuthn Level 2 §7.2 including replay attack protection.
const assertResult = auth.verifyPasskeyAssertion(
  clientDataJSON, // from browser response.clientDataJSON
  storedChallenge, // challenge you sent to the browser
  'https://example.com', // expected origin
  storedSignCount, // signCount from DB (pass 0 on first use)
  authDataBuffer, // from browser response.authenticatorData
  signatureBuffer, // from browser response.signature
  credentialPublicKeyPem, // public key stored during registration
);
if (!assertResult.verified) throw new Error(assertResult.error);
await db.updateSignCount(credentialId, assertResult.newSignCount!);

---

🏗️ Framework Integration

Mitigator comes with built-in presets for Express, Fastify, NestJS, and Next.js.

Express

import express from 'express';
import { presets } from 'mitigator';

const app = express();

// Global security middleware (Headers, Rate Limiting, Secret Scanning)
app.use(presets.expressMiddleware({ rateLimit: true, rateLimitMax: 100 }));

// Secure Logger Chain (Tamper-proof logs via cryptographic linking)
const logger = presets.createSecureLogger(console);
logger.info('User logged in', { userId: 123 });

// Global Secure Error Handler
app.use(presets.expressErrorHandler);

Fastify

import Fastify from 'fastify';
import { presets } from 'mitigator';

const fastify = Fastify();

// Register the security hook/plugin preset
fastify.register(presets.fastifyPlugin({ rateLimit: true, rateLimitMax: 100 }));

NestJS

import { Module, NestModule, MiddlewareConsumer } from '@nestjs/common';
import { presets } from 'mitigator';

@Module({})
export class AppModule implements NestModule {
  configure(consumer: MiddlewareConsumer) {
    // Configure rate limits
    presets.NestJsMitigatorMiddleware.configure({ rateLimit: true, rateLimitMax: 100 });

    // Apply globally
    consumer.apply(presets.NestJsMitigatorMiddleware).forRoutes('*');
  }
}

Next.js Edge Middleware

// middleware.ts
import { NextResponse } from 'next/server';
import { presets } from 'mitigator';

export function middleware(request) {
  const response = NextResponse.next();
  return presets.nextJsMiddleware(request, response);
}

---

🛡️ Automated Security Audit CLI

Mitigator features a recursive command-line security scanner (mitigator-audit) to check your configurations and files automatically in pre-commit hooks or CI/CD pipelines.

Usage

# Scan the current directory
npx mitigator-audit

# Scan a specific directory
npx mitigator-audit ./src

Checks Performed

• Hardcoded Secret Detection: Scans for high-entropy tokens and plain-text API credentials.
• Potential Path Traversal: Scans for raw user inputs mapped directly to file system operations.
• Prototype Pollution Risks: Scans for raw JSON.parse or Object.assign calls without Prototype Pollution filters.
• Header Drift Detection: Scans for express instances without security headers presets.

---

🧪 Safety & Best Practices

Prototype Lockdown

Prevent many prototype pollution attacks globally by freezing core prototypes. Warning: This may break some legacy libraries that modify built-ins.

import { utils } from 'mitigator';

utils.lockdownPrototypes(); // Freezes Object.prototype, Array.prototype, etc.

Memory Wiping

For extremely sensitive data (like decrypted keys), overwrite the buffer once finished.

import { utils } from 'mitigator';

const keyBuffer = Buffer.from('high-entropy-secret');
// ... use key ...
utils.wipeBuffer(keyBuffer); // Fills buffer with zeros

---

📜 License

ISC License - see LICENSE for details.