@anonympins/fingerprint 0.7.1 → 0.7.3

package/CHANGELOG.md

@@ -1,9 +1,34 @@
+## Version 0.7.3
+
+- 🛡️ **Scoring Corrections & Anti-Spoofing Fixes**:
+  - **TLS Spoofing Score Fix**: Resolved false positive detections where legitimate Chrome browsers were erroneously flagged as spoofed (`tlsSpoofingScore`), improving GREASE cipher/extension inspection and ALPN protocol validation.
+  - **Threat Intelligence Rework (`threatIntelScore`)**: Overhauled the threat intelligence scoring mechanism, refining the correlation between low-level TCP RTT and application-layer transit discrepancies while streamlining federated ZKP blacklist checks.
+- 🌐 **Cross-Language Score Parity**:
+  - Resolved calculation discrepancies and harmonized scoring formulas across Node.js, PHP, and Java implementations to guarantee deterministic and identical results across all runtimes.
+  - Fixed all known scoring edge cases primarily affecting the Node.js module.
+- 🔌 **WordPress Plugin Hardening & Compliance**:
+  - **Full WordPress Plugin Check Compliance**: Resolved all errors, warnings, and notices reported by the official WordPress Plugin Check tool, ensuring strict adherence to WordPress coding and security standards.
+- 👥 **Contributors**:
+  - Contributed by @anonympins.
+
+## Version 0.7.2
+
+- 🔌 **WordPress Plugin Enhancements**:
+  - 🌐 **Full Internationalization (i18n)**: The WordPress plugin is now fully translated into French (fr_FR) and German (de_DE), providing a native experience for administrators in those languages.
+  - 🐛 **HTTP Fallback Fix**: Resolved a critical issue where challenges would fail on non-HTTPS (HTTP) sites. The system now transparently falls back to a secure server-side validation mechanism when the browser's `crypto.subtle` API is unavailable, ensuring functionality in all environments.
+- 🛡️ **Security & Bot Detection Hardening**:
+  - 🔐 **Obfuscated Client Script (`fingerprint.client.obfuscated.js`)**: Introduced a new build step that generates a heavily obfuscated version of the client-side library. This makes reverse-engineering of the fingerprinting and behavioral analysis logic significantly more difficult for attackers.
+  - 🤖 **Default Bot Whitelist**: The engine now applies a comprehensive default whitelist for major search engine crawlers (Googlebot, Bingbot, Yandex, etc.) out-of-the-box. This ensures zero-configuration SEO compatibility and prevents legitimate bots from being challenged.
+  - 📡 **Updated Googlebot IPs**: The list of official Googlebot IP ranges has been updated to ensure the latest crawlers are correctly identified and allowed.
+- 🔧 **Developer Experience & Debugging**:
+  - 📝 **Reverse DNS Logging**: Added detailed logging to the bot verification workflow. This provides clear insights into the reverse and forward DNS lookup process, making it easier to debug whitelisting and identify spoofing attempts.
+
 ## Version 0.7.1
 
-- 🔌 **Native WordPress Plugin Integration (`fingerprint-wordpress`)**:
-  - Full official WordPress plugin integration (`fingerprint-wordpress.php`) without external runtime dependencies, leveraging `$wpdb` through a dedicated `WpDbStore` adapter.
+- 🔌 **Native WordPress Plugin Integration (`fingerprint-anti-bot`)**:
+  - Full official WordPress plugin integration (`fingerprint-anti-bot.php`) without external runtime dependencies, leveraging `$wpdb` through a dedicated `WpDbStore` adapter.
   - Automatic SQL cache table provisioning and periodic cleanup of expired tickets via WP-Cron (`fingerprint_prune_expired_entries`).
-  - Automated packaging script (`package.php`) generating a ready-to-deploy ZIP archive (`fingerprint-wordpress.zip`).
+  - Automated packaging script (`package.php`) generating a ready-to-deploy ZIP archive (`fingerprint-anti-bot.zip`).
   - Cross-environment honeypot tripwires: immediately detects and drops automated scanners probing for non-WordPress entrypoints (Laravel, Symfony, Django, Spring Boot `/actuator`, phpMyAdmin, `.env`, `.git`).
   - Admin dashboard security notice if running over unencrypted HTTP (warning about modern browsers disabling native `crypto.subtle` APIs in insecure contexts).
 - 🔬 **JavaScript Prototype Tampering Detection (`detectTamperedPrototypes`)**:

package/README.md

@@ -91,7 +91,7 @@ In your **pom.xml**, add :
 <dependency>
     <groupId>com.anonympins</groupId>
     <artifactId>fingerprint-engine</artifactId>
-    <version>0.7.1</version>
+    <version>0.7.3</version>
 </dependency>
 ```
 ## Documentation

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anonympins/fingerprint",
-  "version": "0.7.1",
+  "version": "0.7.3",
   "description": "Advanced anti-bot library for Node.js using multi-layer fingerprinting (JA3, client-side, headers), behavioral analysis, and adaptive Proof-of-Work (PoW) challenges to mitigate scraping, scalping, and automated threats.",
   "main": "index.js",
   "type": "module",

package/src/js/fingerprint.js

@@ -20,6 +20,7 @@ import {
     modPow,
     hashNetwork,
     normalizeReferer,
+    isLoopbackIp,
     isPrivateIp,
     parseUserAgent,
     safeJsonStringify
@@ -2666,9 +2667,6 @@ export function getTlsSpoofingScore(context, getTlsFingerprintFn = getTlsFingerp
 
     // Check for known spoofed/suspicious JA4 fingerprints
     const spoofedJa4s = [
-        't13d1516h2_8daaf6152771_390237aa04be', // Chrome classique (curl-impersonate / tls-client)
-        't13d1413h2_bc66258908f0_bc2531da1615', // Firefox statique (curl-impersonate-ff / curl_cffi)
-        't13d1515h2_8daaf6152771_a729e2f67de4', // Safari statique (curl-impersonate-safari / tls-client)
         't13d1516h2_8daaf6152771_4be0df930c2c', // Alternatif Chrome (tls-client Go)
         't12d1516h2_8daaf6152771_390237aa04be', // Chrome usurpé dégradé en TLS 1.2
         't13d1516h2_e822d36d892d_93ec3f0b2f5b'  // Scraping bot OpenSSL customisé
@@ -3162,6 +3160,9 @@ function decaySubnetData(subnetData, now) {
  * @param {number} finalScore The final suspicion score.
  */
 async function updateSubnetMetrics(context, deviceId, finalScore) {
+    if (!context.clientIp || isLoopbackIp(context.clientIp)) {
+        return;
+    }
     const subnet = getIpSubnet(context.clientIp);
     if (!subnet) return;
 
@@ -3194,7 +3195,8 @@ async function updateSubnetMetrics(context, deviceId, finalScore) {
 
     // Utilisation d'un identifiant d'appareil stable (fingerprint matériel) plutôt que l'ID de cookie volatil
     const currentDeviceHash = getCompositeDeviceHash(context);
-    const stableFpId = cyrb53(extractStablePart(currentDeviceHash)).toString();
+    const stablePart = extractStablePart(currentDeviceHash);
+    const stableFpId = stablePart ? cyrb53(stablePart).toString() : (deviceId || cyrb53(currentDeviceHash).toString());
 
     const currentDeviceContributions = subnetData.highScoreDevices[stableFpId] || 0;
     if (currentDeviceContributions < 1) {
@@ -3212,7 +3214,9 @@ async function updateSubnetMetrics(context, deviceId, finalScore) {
 
     const userAgent = context.headers?.['user-agent'] || '';
 
-    if (finalScore >= 70) {
+    // Ne pas enregistrer une IP en attaquant si le score élevé provient uniquement d'un seul appareil isolé
+    const isConfirmedClusterAttack = (subnetData.deviceIds.length > 1 && finalScore >= 70) || finalScore >= 95;
+    if (isConfirmedClusterAttack) {
         const existingAttacker = subnetData.attackerIps.find(a => a.ip === context.clientIp);
         if (existingAttacker) {
             existingAttacker.lastSeen = now;
@@ -3272,6 +3276,9 @@ export function calculateAnalogInconsistencyScore(consistencyScore, inflectionPo
  * @returns {Promise<{subnetScore: number}>}
  */
 async function getSubnetScore(context, deviceId = '', securityConfig = null) {
+    if (!context.clientIp || isLoopbackIp(context.clientIp)) {
+        return { subnetScore: 0.0 };
+    }
     if (typeof deviceId === 'object' && deviceId !== null && !securityConfig) {
         securityConfig = deviceId;
     }
@@ -3299,7 +3306,7 @@ async function getSubnetScore(context, deviceId = '', securityConfig = null) {
     }
     let uaCount = subnetData.uas ? subnetData.uas.length : 1;
 
-    if (deviceCount === 0) {
+    if (deviceCount <= 1 && highScoreCount <= 1) {
         return { subnetScore: 0.0 };
     }
 
@@ -3948,7 +3955,7 @@ export const getSuspicionVector = async (context, securityConfig) => {
         _ // store.set result
       ] = await Promise.all([
         getBehavioralIndicators(context, deviceData), // This modifies deviceData, so it must be done before saving deviceData
-        getThreatIntelScore(context, zkpY), // NOUVEAU: Score de Threat Intelligence Fédéré
+        getThreatIntelScore(context, zkpY, securityConfig), // NOUVEAU: Score de Threat Intelligence Fédéré
         getTlsSpoofingScore(context),
         getSubnetScore(context, deviceId, securityConfig),
         getIpReputationScore(clientIp),
@@ -4383,15 +4390,27 @@ function parseGraphQLQuery(body) {
  * @param {string} zkpY - The 'y' component of the ZKP proof (public key).
  * @returns {Promise<{threatIntelScore: number}>}
  */
-async function getThreatIntelScore(context, zkpY) {
-    let score = 0;
+async function getThreatIntelScore(context, zkpY, threatIntelConfig = {}) {
+    let score = 0.0;
+    const signals = [];
+
+    // 1. Détection déterministe : Clé publique ZKP bannie par consensus fédéré
     if (zkpY) {
         const isBanned = await store.has(`banned-zkp-y:${zkpY}`);
         if (isBanned) {
-            score = 100;
+            score = 100.0;
+            signals.push({
+                ruleId: 'FEDERATED_ZKP_BANNED',
+                confidence: 1.0,
+                score: 100.0,
+                rationale: 'Cryptographic identity matched banned list consensus'
+            });
         }
     }
 
+    // 2. Détection physique : Modélisation continue du différentiel de transport (RTT TCP Edge vs Transit Applicatif)
+    // Rationale : Un RTT TCP de socket très faible (datacenter/edge CDN) couplé à un délai applicatif WAN élevé
+    // prouve l'interposition d'un relais/tunnel/proxy résidentiel entre le client réel et le point d'entrée.
     const tcpRttHeader = context.headers?.['x-tcp-rtt'] || context.headers?.['x-real-rtt'];
     const tcpRtt = tcpRttHeader ? parseInt(tcpRttHeader, 10) : null;
 
@@ -4399,24 +4418,40 @@ async function getThreatIntelScore(context, zkpY) {
     if (behaviorHeader) {
         try {
             const metrics = JSON.parse(behaviorHeader);
-            if (metrics && metrics.clientTimestamp && context.requestTimestamp) {
+            if (metrics && typeof metrics.clientTimestamp === 'number' && typeof context.requestTimestamp === 'number') {
                 const appLatency = context.requestTimestamp - metrics.clientTimestamp;
-                if (tcpRtt !== null && !isNaN(tcpRtt) && tcpRtt > 0) {
-                    const clientToProxyDelta = appLatency - tcpRtt;
-                    if (tcpRtt < 35 && clientToProxyDelta > 150) {
-                        score = Math.max(score, 85);
-                    }
-                } else {
-                    if (appLatency > 350) {
-                        score = Math.max(score, 40);
+
+                // Évaluation uniquement si la latence est mesurable et positive avec une mesure socket RTT valide
+                if (tcpRtt !== null && !isNaN(tcpRtt) && tcpRtt > 0 && appLatency > 0) {
+                    // Marge de tolérance contre le jitter réseau et le scheduling JS (Garbage Collector, event-loop)
+                    const jitterAllowance = 60.0;
+                    const effectiveRtt = Math.max(tcpRtt, 5.0);
+                    const tunnelDelta = appLatency - (tcpRtt + jitterAllowance);
+                    const divergenceRatio = appLatency / effectiveRtt;
+
+                    // Condition de disjonction : liaison edge ultra-proche (< 40ms) + transit applicatif au moins 3x supérieur
+                    if (tcpRtt <= 40 && divergenceRatio >= 3.0 && tunnelDelta > 0) {
+                        // Progression sigmoïdale continue calibrée sur la propagation optique intercontinentale (120ms)
+                        const scaling = 120.0;
+                        const ratioWeight = Math.min(1.0, (divergenceRatio - 3.0) / 5.0);
+                        const proxyScore = Math.min(95.0, 40.0 + 55.0 * Math.tanh(tunnelDelta / scaling) * ratioWeight);
+                        const finalProxyScore = Math.round(proxyScore * 10) / 10;
+
+                        score = Math.max(score, finalProxyScore);
+                        signals.push({
+                            ruleId: 'RESIDENTIAL_PROXY_RTT_DISCREPANCY',
+                            confidence: Math.round(ratioWeight * 100) / 100,
+                            score: finalProxyScore,
+                            rationale: `TCP RTT (${tcpRtt}ms) diverges from application transit (${appLatency}ms) with ratio ${divergenceRatio.toFixed(1)}:1`
+                        });
                     }
                 }
             }
         } catch (e) {
-            // Ignorer silencieusement
+            // Ignorer silencieusement les erreurs de parsing des métriques
         }
     }
-    return { threatIntelScore: score };
+    return { threatIntelScore: score, threatIntelSignals: signals };
 }
 
 export class FingerprintEngine {
@@ -4472,6 +4507,17 @@ export class FingerprintEngine {
         }
       }
     }
+
+    // If no security config is provided at all, create a base one.
+    if (!finalConfig) {
+        finalConfig = {};
+    }
+    // If the whitelist is not explicitly provided in the configuration,
+    // apply the default whitelist which includes common search engine bots.
+    if (!finalConfig.whitelist) {
+        finalConfig.whitelist = default_whitelist();
+    }
+
     this.securityConfig = finalConfig;
     this.isProduction = isProduction;
     this._allowlist = this._buildAllowlist();
@@ -4592,6 +4638,9 @@ export class FingerprintEngine {
             (suspicionVector.tcpAnomalyScore || 0) * (weights.tcpAnomalyScore || 0) +
             (suspicionVector.quicAnomalyScore || 0) * (weights.quicAnomalyScore || 0) + // NOUVEAU: QUIC Anomaly
             (suspicionVector.http2AnomalyScore || 0) * (weights.http2AnomalyScore || 0) + // NOUVEAU: HTTP/2 Anomaly
+            (suspicionVector.protocolAnomalyScore || 0) * (weights.protocolAnomalyScore || 0) +
+            (suspicionVector.cookieDroppingScore || 0) * (weights.cookieDroppingScore || 0) +
+            (suspicionVector.virtualizationScore || 0) * (weights.virtualizationScore || 0) +
             (suspicionVector.threatIntelScore || 0) * (weights.threatIntelScore || 0) + // NOUVEAU: QUIC Anomaly
             (suspicionVector.renderingAnomalyScore || 0) * (weights.renderingAnomalyScore || 0); // NOUVEAU: Rendering Anomaly
 
@@ -4670,7 +4719,8 @@ export class FingerprintEngine {
     return false;
   }
   _isIpInAllowlist(clientIp) {
-    return this._allowlist.check(clientIp);
+      const family = isIPv6(clientIp) ? 'ipv6' : 'ipv4';
+      return this._allowlist.check(clientIp, family);
   }
   /**
    * Checks if the request's host and path match an entry in the host+path allowlist.
@@ -4790,7 +4840,7 @@ export class FingerprintEngine {
     const { whitelist = [] } = this.securityConfig;
     const botRules = whitelist.filter(rule => rule.hostnameSuffix);
     if (botRules.length === 0) {
-      return false;
+      return null;
     }
 
     const { clientIp, headers } = requestContext;
@@ -4806,10 +4856,13 @@ export class FingerprintEngine {
       }
     });
     if (!matchedRule) {
-      return false;
+      return null;
     }
 
+    const botName = matchedRule.userAgent; // e.g., 'Googlebot'
+
     if (!canAttemptDns()) {
+      this._log(`[Bot Verification] DNS circuit breaker is open. Skipping check for ${botName}.`, { clientIp });
       return false;
     }
 
@@ -4817,9 +4870,11 @@ export class FingerprintEngine {
     const cachedStatus = await store.get(cacheKey);
 
     if (cachedStatus === 'verified') {
+      this._log(`[Bot Verification] PASSED (cached): ${botName}`, { clientIp });
       return true;
     }
     if (cachedStatus === 'failed') {
+      this._log(`[Bot Verification] FAILED (cached): ${botName}`, { clientIp });
       return false;
     }
 
@@ -4829,25 +4884,35 @@ export class FingerprintEngine {
       const validHostname = hostnames.find(h => h.endsWith(matchedRule.hostnameSuffix));
 
       if (!validHostname) {
+        this._log(`[Bot Verification] FAILED: Reverse DNS lookup for ${clientIp} did not yield a valid hostname ending in '${matchedRule.hostnameSuffix}'.`, { clientIp, resolvedHostnames: hostnames });
         await store.set(cacheKey, 'failed', 300); // Temporary negative caching (5 minutes)
         return false;
       }
 
+      this._log(`[Bot Verification] Reverse DNS OK for ${botName}.`, { clientIp, validHostname });
+
       // 2. Forward DNS lookup
     let addresses = [];
     try {
         addresses = await withTimeout(dns.resolve(validHostname), 500);
-    } catch (e) {}
+    } catch (e) {
+        this._log(`[Bot Verification] Forward DNS (A) lookup FAILED for ${validHostname}.`, { error: e.message });
+    }
     try {
         const ipv6 = await withTimeout(dns.resolve(validHostname, 'AAAA'), 500);
       addresses = addresses.concat(ipv6);
-    } catch (e) {}
+    } catch (e) {
+        this._log(`[Bot Verification] Forward DNS (AAAA) lookup FAILED for ${validHostname}.`, { error: e.message });
+    }
     if (addresses.includes(clientIp)) {
+        this._log(`[Bot Verification] PASSED: Forward DNS IP matches original IP for ${botName}.`, { clientIp, validHostname, resolvedIps: addresses });
         recordDnsSuccess();
         await store.set(cacheKey, 'verified', 86400); // Cache success for 24h (TTL in seconds)
         return true;
       }
+      this._log(`[Bot Verification] FAILED: IP mismatch for ${botName}. Original IP not in resolved addresses.`, { clientIp, validHostname, resolvedIps: addresses });
     } catch (error) {
+      this._log(`[Bot Verification] FAILED: DNS lookup error for ${botName}.`, { clientIp, error: error.message });
       recordDnsFailure();
       await store.set(cacheKey, 'failed', 300); // Temporary negative caching (5 minutes)
       return false;
@@ -4858,6 +4923,13 @@ export class FingerprintEngine {
   }
 
   async processRequest(requestContext) {
+      if (this.securityConfig?.reset) {
+          const subnet = getIpSubnet(requestContext.clientIp);
+          if (subnet) {
+              await store.delete(`subnet:${subnet}`);
+          }
+          await store.delete(`ip-reputation:${requestContext.clientIp}`);
+      }
       sanitizeProxyHeaders(requestContext, this.securityConfig);
 
       const { clientIp = "unknown", path, cookies = {}, query = {}, isStatic, graphqlOperationType, graphqlOperationName } = requestContext;
@@ -4965,15 +5037,15 @@ export class FingerprintEngine {
         }
     }
 
-    // Check if the request is from a verified, whitelisted bot (e.g., Googlebot)
-    if (await this._verifyWhitelistedBot(requestContext)) {
+    const botVerificationResult = await this._verifyWhitelistedBot(requestContext);
+    if (botVerificationResult === true) {
       const filterWhitelist = this.securityConfig.filterWhitelist || false;
       let bypassWhitelist = false;
       if (filterWhitelist === true) {
         bypassWhitelist = this._hasCertainAttack(requestContext);
       } else if (typeof filterWhitelist === 'number') {
         const res = await getScoreAndVector();
-        if (res.score > filterWhitelist) {
+        if (res.score > filterWhitelist) { // NOSONAR
           bypassWhitelist = true;
         }
       }
@@ -5013,6 +5085,11 @@ export class FingerprintEngine {
 
     // The engine now works with the context directly, no more rawReq dependency here.
     const suspicionVector = preCalculatedVector || await __internal.getSuspicionVector(requestContext, this.securityConfig);
+    if (botVerificationResult === false) {
+        // This means it claimed to be a bot but failed verification.
+        // This is a strong signal of spoofing.
+        suspicionVector.tlsSpoofingScore = Math.max(suspicionVector.tlsSpoofingScore || 0, 95);
+    }
     let finalScore = preCalculatedScore !== null ? preCalculatedScore : this.calculateFinalScore(suspicionVector);
 
     this._log('Suspicion vector calculated', { 

package/src/js/fingerprint.utils.js

@@ -157,6 +157,16 @@ export function hashNetwork(ip, prefix = 24) {
     }
     return hash.toString(16);
 }
+export function isLoopbackIp(ip) {
+    if (!ip || typeof ip !== 'string') return true;
+    let cleanIp = ip.trim().toLowerCase();
+    if (cleanIp.startsWith('::ffff:')) {
+        cleanIp = cleanIp.substring(7);
+    }
+    return cleanIp === '127.0.0.1' || cleanIp === '::1' || cleanIp === 'localhost' ||
+           cleanIp.startsWith('127.') || cleanIp === '0.0.0.0' || cleanIp === '::';
+}
+
 export function normalizeReferer(referer) {
     try {
         const url = new URL(referer);
@@ -167,11 +177,28 @@ export function normalizeReferer(referer) {
 }
 
 export function isPrivateIp(ip) {
-    // Check whether the IP address is private
-    const parts = ip.split('.');
-    if (parts.length !== 4) return false;
-    const first = parseInt(parts[0]);
-    return (first === 10) || (first === 172 && parseInt(parts[1]) >= 16 && parseInt(parts[1]) <= 31) || (first === 192 && parseInt(parts[1]) === 168);
+    if (!ip || typeof ip !== 'string') return false;
+    let cleanIp = ip.trim().toLowerCase();
+    if (cleanIp.startsWith('::ffff:')) {
+        cleanIp = cleanIp.substring(7);
+    }
+    if (cleanIp === '127.0.0.1' || cleanIp === '::1' || cleanIp === 'localhost' || cleanIp.startsWith('127.')) {
+        return true;
+    }
+    const parts = cleanIp.split('.');
+    if (parts.length === 4) {
+        const first = parseInt(parts[0], 10);
+        const second = parseInt(parts[1], 10);
+        if (first === 127 || first === 10 || first === 0) return true;
+        if (first === 172 && second >= 16 && second <= 31) return true;
+        if (first === 192 && second === 168) return true;
+        if (first === 169 && second === 254) return true;
+        if (first === 100 && second >= 64 && second <= 127) return true;
+    }
+    if (cleanIp.startsWith('fc') || cleanIp.startsWith('fd') || cleanIp.startsWith('fe80:')) {
+        return true;
+    }
+    return false;
 }
 // Utility parsing functions
 export function parseUserAgent(ua) {

package/src/js/tests/fingerprint.test.js

@@ -10,6 +10,8 @@ import * as fingerprint from '../fingerprint.js';
 vi.mock('import-meta-env', () => ({
     env: { NODE_ENV: 'test', POW_SECRET: 'fallback-dev-secret-32-chars-minimum' },
 }));
+// Mock the entire dns module
+vi.mock('node:dns/promises');
 // Mock readFileSync for custom challenge page tests
 vi.mock('node:fs', async () => {
     const actualFs = await vi.importActual('node:fs');
@@ -35,9 +37,8 @@ const {
 } = fingerprint;
 const { store, getRequestPatternScore, getDeviceHash } = __internal;
 const { getRenderingAnomalyScore } = __internal;
-let { getBehaviorScore, getClickVarianceScore } = __internal;
-// Mock the entire dns module
-vi.mock('node:dns/promises');
+let { getBehaviorScore, getClickVarianceScore } = __internal; // eslint-disable-line prefer-const
+
 
 describe('Fingerprint & PoW Security Suite', () => {
     test('cyrb53 should be deterministic', () => {
@@ -1758,12 +1759,98 @@ describe('Fingerprint & PoW Security Suite', () => {
             };
 
             const isVerified = await engine._verifyWhitelistedBot({ ...requestContext, fingerprint: {} });
-            expect(isVerified).toBe(false);
+            expect(isVerified).toBeNull();
             expect(consoleErrorSpy).toHaveBeenCalledWith(expect.stringContaining('[Fingerprint] Invalid regex in whitelist rule'));
             consoleErrorSpy.mockRestore();
         });
     });
 });
+describe('Googlebot Whitelisting (Node.js)', () => {
+    const inMemoryStore = {
+        _map: new Map(),
+        async get(key) { return this._map.get(key); },
+        async set(key, value) { this._map.set(key, value); },
+        async has(key) { return this._map.has(key); },
+        async delete(key) { this._map.delete(key); },
+    };
+
+    const securityConfig = {
+        weights: { headerAnomalyScore: 1.0, tlsSpoofingScore: 1.0 }, // Simple config for testing
+        thresholds: { low: 20, medium: 45, high: 75, block: 95 },
+        whitelist: [
+            { userAgent: 'Googlebot', hostnameSuffix: '.googlebot.com' }
+        ]
+    };
+
+    let engine;
+
+    beforeEach(() => {
+        inMemoryStore._map.clear();
+        configureStore(inMemoryStore);
+        vi.clearAllMocks(); // Clear mocks before each test
+        engine = new FingerprintEngine(securityConfig);
+    });
+
+    it('should correctly identify and allow a legitimate Googlebot request', async () => {
+        const googleIp = '::ffff:66.249.66.39'; // An IP from the official list
+        const googleHostname = 'crawl-66-249-66-39.googlebot.com';
+        const googleUa = 'Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)';
+
+        // Mock the DNS verification process
+        vi.mocked(dns.reverse).mockResolvedValue([googleHostname]);
+        vi.mocked(dns.resolve).mockResolvedValue([googleIp]);
+
+        const requestContext = {
+            clientIp: googleIp,
+            path: '/',
+            headers: { 'user-agent': googleUa },
+            isStatic: false,
+            cookies: {},
+            query: {},
+            body: null,
+            httpVersion: '1.1',
+            rawHeaders: ['user-agent', googleUa]
+        };
+
+        const decision = await engine.processRequest(requestContext);
+
+        expect(decision.action).toBe('next');
+        expect(decision.score).toBe(0);
+        expect(decision.vector.whitelisted).toBe(100);
+        expect(decision.vector.type).toBe('bot');
+
+        expect(dns.reverse).toHaveBeenCalledWith(googleIp);
+        expect(dns.resolve).toHaveBeenCalledWith(googleHostname);
+    });
+
+    it('should challenge or block a request spoofing a Googlebot User-Agent from a non-Google IP', async () => {
+        const fakeGoogleIp = '1.2.3.4';
+        const googleUa = 'Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)';
+
+        vi.mocked(dns.reverse).mockRejectedValue(new Error('Host not found'));
+
+        const requestContext = {
+            clientIp: fakeGoogleIp,
+            path: '/',
+            headers: { 'user-agent': googleUa, 'accept-language': 'en-US' },
+            isStatic: false,
+            cookies: {},
+            query: {},
+            body: null,
+            httpVersion: '1.1',
+            rawHeaders: ['user-agent', googleUa, 'accept-language', 'en-US']
+        };
+
+        const decision = await engine.processRequest(requestContext);
+
+        expect(decision.action).toBe('block');
+        expect(decision.score).toBeGreaterThan(0);
+        expect(decision.vector.whitelisted).toBeUndefined();
+
+        expect(dns.reverse).toHaveBeenCalledWith(fakeGoogleIp);
+        expect(dns.resolve).not.toHaveBeenCalled();
+    });
+});
 
 describe('TLS Session Resumption (Cookieless Identity)', () => {
     const inMemoryStore = {

package/src/js/tests/threatIntel.test.js

@@ -0,0 +1,76 @@
+import { beforeEach, describe, expect, it } from 'vitest';
+import { __internal, configureStore } from '../fingerprint.js';
+
+describe('Threat Intelligence - Rationale-Driven Defensive Logic', () => {
+    const inMemoryStore = {
+        _map: new Map(),
+        async get(key) { return this._map.get(key); },
+        async set(key, value) { this._map.set(key, value); },
+        async has(key) { return this._map.has(key); },
+        async delete(key) { this._map.delete(key); },
+    };
+
+    beforeEach(() => {
+        inMemoryStore._map.clear();
+        configureStore(inMemoryStore);
+    });
+
+    it('should assign a deterministic score of 100 with audit trace for banned ZKP public keys', async () => {
+        await inMemoryStore.set('banned-zkp-y:banned-key-999', true);
+
+        const context = { headers: {} };
+        const result = await __internal.getSuspicionVector(context, {
+            weights: { threatIntelScore: 1.0 },
+            thresholds: { low: 20 }
+        });
+
+        // Direct check via internal function with banned key
+        const threatResult = await __internal.store.has('banned-zkp-y:banned-key-999');
+        expect(threatResult).toBe(true);
+    });
+
+    it('should return score 0 for consistent local connections without proxy delay', async () => {
+        const reqTime = 1700000000000;
+        const context = {
+            requestTimestamp: reqTime,
+            headers: {
+                'x-tcp-rtt': '15',
+                'x-behavior-metrics': JSON.stringify({ clientTimestamp: reqTime - 25 })
+            }
+        };
+
+        const vector = await __internal.getSuspicionVector(context, { weights: { threatIntelScore: 1.0 } });
+        expect(vector.threatIntelScore).toBe(0.0);
+    });
+
+    it('should ignore mild JS event loop jitter and network lag without triggering false positives', async () => {
+        const reqTime = 1700000000000;
+        // App latency 65ms with a 20ms RTT falls well within the 60ms jitter tolerance window
+        const context = {
+            requestTimestamp: reqTime,
+            headers: {
+                'x-tcp-rtt': '20',
+                'x-behavior-metrics': JSON.stringify({ clientTimestamp: reqTime - 65 })
+            }
+        };
+
+        const vector = await __internal.getSuspicionVector(context, { weights: { threatIntelScore: 1.0 } });
+        expect(vector.threatIntelScore).toBe(0.0);
+    });
+
+    it('should smoothly calculate elevated suspicion when residential proxy tunneling is detected', async () => {
+        const reqTime = 1700000000000;
+        // Edge socket is 10ms (datacenter gateway), but application payload arrives with 280ms latency (WAN proxy hop)
+        const context = {
+            requestTimestamp: reqTime,
+            headers: {
+                'x-tcp-rtt': '10',
+                'x-behavior-metrics': JSON.stringify({ clientTimestamp: reqTime - 280 })
+            }
+        };
+
+        const vector = await __internal.getSuspicionVector(context, { weights: { threatIntelScore: 1.0 } });
+        expect(vector.threatIntelScore).toBeGreaterThan(70.0);
+        expect(vector.threatIntelScore).toBeLessThanOrEqual(95.0);
+    });
+});