mitigator 1.0.0

package/LICENSE.md

@@ -0,0 +1,15 @@
+# ISC License
+
+Copyright (c) 2026, Mohamed
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,355 @@
+# 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
+
+```bash
+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:
+>
+> ```typescript
+> 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`.
+
+```typescript
+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.
+
+```typescript
+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.
+
+```typescript
+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.
+
+```typescript
+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.
+
+```typescript
+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.
+
+```typescript
+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.
+
+```typescript
+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.
+
+```typescript
+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
+
+```typescript
+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
+
+```typescript
+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
+
+```typescript
+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
+
+```typescript
+// 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
+
+```bash
+# 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.
+
+```typescript
+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.
+
+```typescript
+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](LICENSE) for details.

package/dist/bin/mitigator-audit.cjs

@@ -0,0 +1,187 @@
+#!/usr/bin/env node
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/bin/mitigator-audit.ts
+var mitigator_audit_exports = {};
+__export(mitigator_audit_exports, {
+  main: () => main,
+  runAudit: () => runAudit
+});
+module.exports = __toCommonJS(mitigator_audit_exports);
+var import_node_fs = require("fs");
+var import_node_path = require("path");
+
+// src/validate/index.ts
+var import_node_crypto = require("crypto");
+var https = __toESM(require("https"), 1);
+var SECRET_PATTERNS = [
+  /AKIA[0-9A-Z]{16}/,
+  /-----BEGIN (RSA|OPENSSH|EC|PGP) PRIVATE KEY-----/,
+  /ghp_[a-zA-Z0-9]{36}/,
+  /sk_live_[a-zA-Z0-9]{24}/
+];
+var scanForSecrets = (input) => {
+  if (typeof input === "string") {
+    return SECRET_PATTERNS.some((pattern) => pattern.test(input));
+  }
+  if (typeof input === "object" && input !== null) {
+    return Object.values(input).some(scanForSecrets);
+  }
+  return false;
+};
+
+// src/bin/mitigator-audit.ts
+var findFiles = (dir, fileList = []) => {
+  try {
+    const files = (0, import_node_fs.readdirSync)(dir);
+    for (const file of files) {
+      if (file === "node_modules" || file === ".git" || file === "dist" || file === "coverage")
+        continue;
+      const filePath = (0, import_node_path.join)(dir, file);
+      const stat = (0, import_node_fs.statSync)(filePath);
+      if (stat.isDirectory()) {
+        findFiles(filePath, fileList);
+      } else {
+        const ext = (0, import_node_path.extname)(file);
+        if ([".js", ".ts", ".json", ".env", ".yml", ".yaml"].includes(ext)) {
+          fileList.push(filePath);
+        }
+      }
+    }
+  } catch {
+  }
+  return fileList;
+};
+var auditFile = (filePath) => {
+  const result = { filePath, vulnerabilities: [] };
+  try {
+    const content = (0, import_node_fs.readFileSync)(filePath, "utf8");
+    const ext = (0, import_node_path.extname)(filePath);
+    if (ext !== ".json") {
+      const lines = content.split(/\r?\n/);
+      lines.forEach((line, idx) => {
+        if (scanForSecrets(line)) {
+          result.vulnerabilities.push({
+            type: "Hardcoded Secret",
+            severity: "HIGH",
+            message: `Potential plaintext API key or credential leak detected.`,
+            line: idx + 1
+          });
+        }
+      });
+    }
+    if (ext === ".js" || ext === ".ts") {
+      const traversalRegex = /fs\.(readFileSync|writeFileSync|readFile|writeFile)\(.*req\.(query|body|params)\./;
+      if (traversalRegex.test(content)) {
+        result.vulnerabilities.push({
+          type: "Potential Path Traversal",
+          severity: "HIGH",
+          message: "Direct user input passed to a file system operation without path lock validation."
+        });
+      }
+      if (content.includes("Object.assign(") || content.includes("JSON.parse(")) {
+        if (!content.includes("safeMerge") && !content.includes("safeJson") && !content.includes("lockdownPrototypes")) {
+          result.vulnerabilities.push({
+            type: "Prototype Pollution Risk",
+            severity: "MEDIUM",
+            message: "Raw JSON parsing or object assignment used without Prototype Pollution defense."
+          });
+        }
+      }
+      if (content.includes("express()") && !content.includes("presets.expressMiddleware") && !content.includes("helmet")) {
+        result.vulnerabilities.push({
+          type: "Missing Security Headers",
+          severity: "MEDIUM",
+          message: "Express application instance created but no security middleware preset detected."
+        });
+      }
+    }
+  } catch {
+  }
+  return result;
+};
+var runAudit = (targetDir = ".") => {
+  const files = findFiles(targetDir);
+  const results = [];
+  for (const file of files) {
+    const res = auditFile(file);
+    if (res.vulnerabilities.length > 0) {
+      results.push(res);
+    }
+  }
+  return results;
+};
+var main = () => {
+  const args = process.argv.slice(2);
+  const target = args[0] || ".";
+  console.log(
+    `\u{1F6E1}\uFE0F  Mitigator Security Audit: Scanning [${target}] for vulnerabilities and configuration drifts...
+`
+  );
+  const results = runAudit(target);
+  let totalHigh = 0;
+  let totalMedium = 0;
+  if (results.length === 0) {
+    console.log("\u2705 No security vulnerabilities or drifts found. Keep up the high standard!");
+    process.exit(0);
+  }
+  results.forEach((res) => {
+    console.log(`\u{1F4C2} File: ${res.filePath}`);
+    res.vulnerabilities.forEach((vuln) => {
+      const color = vuln.severity === "HIGH" ? "\x1B[31m[HIGH]\x1B[0m" : "\x1B[33m[MEDIUM]\x1B[0m";
+      if (vuln.severity === "HIGH") totalHigh++;
+      if (vuln.severity === "MEDIUM") totalMedium++;
+      const lineStr = vuln.line ? ` (line ${vuln.line})` : "";
+      console.log(`  ${color} ${vuln.type}: ${vuln.message}${lineStr}`);
+    });
+    console.log("");
+  });
+  console.log(
+    `\u{1F4CA} Audit Summary: Found ${totalHigh} HIGH and ${totalMedium} MEDIUM severity alerts.`
+  );
+  if (totalHigh > 0) {
+    console.log(
+      "\x1B[31m\u274C Audit Failed: Critical vulnerabilities must be resolved before merging.\x1B[0m"
+    );
+    process.exit(1);
+  } else {
+    console.log("\x1B[32m\u26A0\uFE0F  Audit Passed with warnings.\x1B[0m");
+    process.exit(0);
+  }
+};
+if (typeof require !== "undefined" && require.main === module || process.argv[1] && (process.argv[1].endsWith("mitigator-audit") || process.argv[1].endsWith("mitigator-audit.js") || process.argv[1].endsWith("mitigator-audit.ts"))) {
+  main();
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  main,
+  runAudit
+});
+//# sourceMappingURL=mitigator-audit.cjs.map

package/dist/bin/mitigator-audit.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/bin/mitigator-audit.ts","../../src/validate/index.ts"],"sourcesContent":["#!/usr/bin/env node\nimport { readFileSync, readdirSync, statSync } from 'node:fs';\nimport { join, extname } from 'node:path';\nimport { scanForSecrets } from '../validate/index.js';\n\ninterface AuditResult {\n  filePath: string;\n  vulnerabilities: {\n    type: string;\n    severity: 'HIGH' | 'MEDIUM' | 'LOW';\n    message: string;\n    line?: number;\n  }[];\n}\n\nconst findFiles = (dir: string, fileList: string[] = []): string[] => {\n  try {\n    const files = readdirSync(dir);\n    for (const file of files) {\n      if (file === 'node_modules' || file === '.git' || file === 'dist' || file === 'coverage')\n        continue;\n      const filePath = join(dir, file);\n      const stat = statSync(filePath);\n      if (stat.isDirectory()) {\n        findFiles(filePath, fileList);\n      } else {\n        const ext = extname(file);\n        if (['.js', '.ts', '.json', '.env', '.yml', '.yaml'].includes(ext)) {\n          fileList.push(filePath);\n        }\n      }\n    }\n  } catch {}\n  return fileList;\n};\n\nconst auditFile = (filePath: string): AuditResult => {\n  const result: AuditResult = { filePath, vulnerabilities: [] };\n  try {\n    const content = readFileSync(filePath, 'utf8');\n    const ext = extname(filePath);\n\n    // 1. Plaintext Secret Scanning\n    if (ext !== '.json') {\n      const lines = content.split(/\\r?\\n/);\n      lines.forEach((line, idx) => {\n        if (scanForSecrets(line)) {\n          result.vulnerabilities.push({\n            type: 'Hardcoded Secret',\n            severity: 'HIGH',\n            message: `Potential plaintext API key or credential leak detected.`,\n            line: idx + 1,\n          });\n        }\n      });\n    }\n\n    // 2. Dangerous File Sync / Path Traversal\n    if (ext === '.js' || ext === '.ts') {\n      const traversalRegex =\n        /fs\\.(readFileSync|writeFileSync|readFile|writeFile)\\(.*req\\.(query|body|params)\\./;\n      if (traversalRegex.test(content)) {\n        result.vulnerabilities.push({\n          type: 'Potential Path Traversal',\n          severity: 'HIGH',\n          message:\n            'Direct user input passed to a file system operation without path lock validation.',\n        });\n      }\n\n      // 3. Unsafe Merging without prototype check\n      if (content.includes('Object.assign(') || content.includes('JSON.parse(')) {\n        if (\n          !content.includes('safeMerge') &&\n          !content.includes('safeJson') &&\n          !content.includes('lockdownPrototypes')\n        ) {\n          result.vulnerabilities.push({\n            type: 'Prototype Pollution Risk',\n            severity: 'MEDIUM',\n            message:\n              'Raw JSON parsing or object assignment used without Prototype Pollution defense.',\n          });\n        }\n      }\n\n      // 4. Missing secure headers in standard http/express setups\n      if (\n        content.includes('express()') &&\n        !content.includes('presets.expressMiddleware') &&\n        !content.includes('helmet')\n      ) {\n        result.vulnerabilities.push({\n          type: 'Missing Security Headers',\n          severity: 'MEDIUM',\n          message:\n            'Express application instance created but no security middleware preset detected.',\n        });\n      }\n    }\n  } catch {}\n  return result;\n};\n\nexport const runAudit = (targetDir: string = '.'): AuditResult[] => {\n  const files = findFiles(targetDir);\n  const results: AuditResult[] = [];\n  for (const file of files) {\n    const res = auditFile(file);\n    if (res.vulnerabilities.length > 0) {\n      results.push(res);\n    }\n  }\n  return results;\n};\n\n// Main Execution\nexport const main = () => {\n  const args = process.argv.slice(2);\n  const target = args[0] || '.';\n  console.log(\n    `🛡️  Mitigator Security Audit: Scanning [${target}] for vulnerabilities and configuration drifts...\\n`,\n  );\n\n  const results = runAudit(target);\n  let totalHigh = 0;\n  let totalMedium = 0;\n\n  if (results.length === 0) {\n    console.log('✅ No security vulnerabilities or drifts found. Keep up the high standard!');\n    process.exit(0);\n  }\n\n  results.forEach((res) => {\n    console.log(`📂 File: ${res.filePath}`);\n    res.vulnerabilities.forEach((vuln) => {\n      const color = vuln.severity === 'HIGH' ? '\\x1b[31m[HIGH]\\x1b[0m' : '\\x1b[33m[MEDIUM]\\x1b[0m';\n      if (vuln.severity === 'HIGH') totalHigh++;\n      if (vuln.severity === 'MEDIUM') totalMedium++;\n      const lineStr = vuln.line ? ` (line ${vuln.line})` : '';\n      console.log(`  ${color} ${vuln.type}: ${vuln.message}${lineStr}`);\n    });\n    console.log('');\n  });\n\n  console.log(\n    `📊 Audit Summary: Found ${totalHigh} HIGH and ${totalMedium} MEDIUM severity alerts.`,\n  );\n  if (totalHigh > 0) {\n    console.log(\n      '\\x1b[31m❌ Audit Failed: Critical vulnerabilities must be resolved before merging.\\x1b[0m',\n    );\n    process.exit(1);\n  } else {\n    console.log('\\x1b[32m⚠️  Audit Passed with warnings.\\x1b[0m');\n    process.exit(0);\n  }\n};\n\n// Only execute when run directly\n/* v8 ignore next 11 */\nif (\n  (typeof require !== 'undefined' && require.main === module) ||\n  (process.argv[1] &&\n    (process.argv[1].endsWith('mitigator-audit') ||\n      process.argv[1].endsWith('mitigator-audit.js') ||\n      process.argv[1].endsWith('mitigator-audit.ts')))\n) {\n  main();\n}\n","import { createHash } from 'node:crypto';\nimport * as https from 'node:https';\n\n/**\n * Result returned by `checkPwnedPassword`.\n * Always resolves (never rejects) to preserve fail-open availability semantics.\n */\nexport interface CheckPwnedResult {\n  /** Number of times this password appeared in known data breaches. 0 if not found. */\n  count: number;\n  /**\n   * Whether the HIBP API was reachable during this check.\n   * If `false`, the result is inconclusive — the password may or may not be compromised.\n   * Callers should treat `apiAvailable: false` as a signal to retry or log a warning.\n   */\n  apiAvailable: boolean;\n}\n\n/**\n * Checks if a password has been leaked in a data breach using the Have I Been Pwned (HIBP) API.\n * Uses k-Anonymity (sending only the first 5 characters of the SHA-1 hash) to ensure\n * the password is never exposed to the API.\n *\n * Always resolves — never rejects. If the API is unreachable, `apiAvailable` will be `false`\n * and `count` will be `0` (inconclusive). Callers should check `apiAvailable` before\n * treating a zero count as \"password is clean\".\n *\n * @param password The password to check.\n * @returns {Promise<CheckPwnedResult>} Structured result with breach count and API availability.\n *\n * @example\n * const { count, apiAvailable } = await checkPwnedPassword('hunter2');\n * if (!apiAvailable) logger.warn('HIBP API unreachable — skipping pwned check');\n * else if (count > 0) throw new Error('Password found in data breaches');\n */\nexport const checkPwnedPassword = (password: string): Promise<CheckPwnedResult> => {\n  return new Promise((resolve) => {\n    const hash = createHash('sha1').update(password).digest('hex').toUpperCase();\n    const prefix = hash.slice(0, 5);\n    const suffix = hash.slice(5);\n\n    https\n      .get(`https://api.pwnedpasswords.com/range/${prefix}`, (res) => {\n        let data = '';\n        res.on('data', (chunk) => (data += chunk));\n        res.on('end', () => {\n          const lines = data.split('\\n');\n          for (const line of lines) {\n            const [hashSuffix, count] = line.split(':');\n            if (hashSuffix === suffix) {\n              return resolve({ count: Number.parseInt(count.trim()), apiAvailable: true });\n            }\n          }\n          resolve({ count: 0, apiAvailable: true });\n        });\n      })\n      .on('error', (err) => {\n        // Fail-open: don't block authentication when HIBP is unreachable.\n        // apiAvailable: false lets the caller decide how to handle the degraded state.\n        console.error('Mitigator: HIBP API connection error.', err);\n        resolve({ count: 0, apiAvailable: false });\n      });\n  });\n};\n\n/**\n * Patterns for secrets.\n */\nexport const SECRET_PATTERNS = [\n  /AKIA[0-9A-Z]{16}/,\n  /-----BEGIN (RSA|OPENSSH|EC|PGP) PRIVATE KEY-----/,\n  /ghp_[a-zA-Z0-9]{36}/,\n  /sk_live_[a-zA-Z0-9]{24}/,\n];\n\n/**\n * Scans for secrets.\n */\nexport const scanForSecrets = (input: any): boolean => {\n  if (typeof input === 'string') {\n    return SECRET_PATTERNS.some((pattern) => pattern.test(input));\n  }\n  if (typeof input === 'object' && input !== null) {\n    return Object.values(input).some(scanForSecrets);\n  }\n  return false;\n};\n\n/**\n * Weak password check.\n */\nexport const isWeakPassword = (password: string): boolean => {\n  if (password.length < 8) return true;\n  const hasLower = /[a-z]/.test(password);\n  const hasUpper = /[A-Z]/.test(password);\n  const hasNumber = /\\d/.test(password);\n  const hasSpecial = /[^a-zA-Z0-9]/.test(password);\n  const types = [hasLower, hasUpper, hasNumber, hasSpecial].filter(Boolean).length;\n  if (types < 2) return true;\n  const common = ['password', '123456', 'qwerty', 'admin123', 'password123', '12345678'];\n  if (common.includes(password.toLowerCase())) return true;\n  return false;\n};\n\n/**\n * Schema types.\n */\nexport type Schema = {\n  [key: string]: 'string' | 'number' | 'boolean' | 'object' | 'array';\n};\n\n/**\n * Type validation.\n */\nexport const isType = (val: any, type: Schema[keyof Schema]): boolean => {\n  if (type === 'array') return Array.isArray(val);\n  return typeof val === type && val !== null;\n};\n\n/**\n * Schema enforcement.\n */\nexport const enforceSchema = <T extends Record<string, any>>(\n  data: any,\n  schema: Schema,\n): T | null => {\n  if (typeof data !== 'object' || data === null || Array.isArray(data)) return null;\n  const result: any = {};\n  for (const key of Object.keys(schema)) {\n    const expectedType = schema[key];\n    const value = data[key];\n    if (value === undefined || !isType(value, expectedType)) return null;\n    result[key] = value;\n  }\n  return result;\n};\n\n/**\n * Email validation.\n */\nexport const isEmail = (input: string): boolean => {\n  return /^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$/.test(\n    input,\n  );\n};\n\n/**\n * Injection pattern detection (Heuristic).\n * Detects common SQL, NoSQL, and Command Injection payloads.\n */\nexport const hasInjectionPattern = (input: string): boolean => {\n  if (typeof input !== 'string') return false;\n\n  const dangerousPatterns = [\n    // SQL Injection\n    /(\\b(SELECT|INSERT|UPDATE|DELETE|DROP|ALTER|CREATE|EXEC|UNION|ALL|ANY|SOME)\\b.*\\b(FROM|INTO|SET|TABLE|DATABASE)\\b)/i,\n    /'\\s*OR\\s+'?1'?\\s*=\\s*'?1/i,\n    /\"\\s*OR\\s+\"?1\"?\\s*=\\s*\"?1/i,\n    /--\\s*$/,\n    /;\\s*(WAITFOR|DELAY|SLEEP)/i,\n    /;\\s*(EXEC|EXECUTE)\\b/i,\n    // NoSQL Injection\n    /\\$(where|gt|lt|gte|lte|ne|in|nin|regex|expr|eq)/i,\n    /\\{\\s*\\$ne\\s*:/i,\n    // Command Injection\n    /(;|\\||&&|\\|\\||`|\\$)\\s*(cat|ls|pwd|whoami|id|echo|bash|sh|ping|curl|wget)/i,\n  ];\n  return dangerousPatterns.some((pattern) => pattern.test(input));\n};\n"],"mappings":"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","names":[]}

package/dist/bin/mitigator-audit.d.cts

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+interface AuditResult {
+    filePath: string;
+    vulnerabilities: {
+        type: string;
+        severity: 'HIGH' | 'MEDIUM' | 'LOW';
+        message: string;
+        line?: number;
+    }[];
+}
+declare const runAudit: (targetDir?: string) => AuditResult[];
+declare const main: () => never;
+
+export { main, runAudit };

package/dist/bin/mitigator-audit.d.ts

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+interface AuditResult {
+    filePath: string;
+    vulnerabilities: {
+        type: string;
+        severity: 'HIGH' | 'MEDIUM' | 'LOW';
+        message: string;
+        line?: number;
+    }[];
+}
+declare const runAudit: (targetDir?: string) => AuditResult[];
+declare const main: () => never;
+
+export { main, runAudit };