@redsocs/spam-warden 1.2.3 → 1.3.1

package/README.md

@@ -6,151 +6,206 @@ Lightweight, universal JavaScript library for real-time spam detection and autom
 [![npm](https://img.shields.io/npm/v/%40redsocs%2Fspam-warden.svg)](https://www.npmjs.com/package/@redsocs/spam-warden)
 [![Sponsor](https://img.shields.io/badge/Sponsor-Buy%20Me%20a%20Coffee-ffdd00?style=flat&logo=buy-me-a-coffee&logoColor=black)](https://buymeacoffee.com/redsocs?new=1)
 
-# What is this?
+---
+
+## What is this?
+
+**SpamWarden.js** is a zero-dependency, universal engine that detects spam directly at the source. It is engineered specifically to combat the regional surge in gambling, loan, and "fast money" spam campaigns targeting public sector and enterprise platforms.
+
+By running natively in the browser, it intercepts malicious payloads before they ever reach your database, saving server resources, maintaining data integrity, and feeding sanitized threat intelligence directly into your SIEM.
+
+👉 **[Live Demo, Scanner & Script Generator](https://spam-warden-js-527b79.gitlab.io/)**
+
+---
+
+## 🛑 A Note on Honesty: Our War on Spammers (Old vs. New)
+
+Let’s be completely transparent about how this library has evolved.
+
+In our earlier versions, our absolute obsession with punishing casino and loan botnets led us to build something genuinely brutal. We deployed aggressive DOM scraping, intentional memory leaks, infinite `history.replaceState` loops, and hidden `debugger` traps. The goal was simple: crash their headless browsers and completely destroy their automated assets.
+
+**The problem?** If you build a script that behaves exactly like hostile malware, enterprise Static Application Security Testing (SAST) tools will flag it as hostile malware. Government and corporate scanners took one look at our aggressive heuristic scraping and thrown critical alerts for "stealth loader behavior" and "anti-analysis malware."
+
+**The Solution:** We had to grow up and build an enterprise-compliant architecture. We stripped out the browser-crashing loops, the wild DOM scraping, and the sketchy `atob` obfuscation.
+
+But we did not surrender. Instead of crashing their machines, we now target their operational costs. The new architecture replaces the brutal malware traps with a **Cryptographic Proof of Work (PoW) Tarpit**. It sails right past SAST compliance audits, but if a headless bot tries to bypass the UI and execute our decoy endpoints, it forces their CPU into a mathematical chokehold, burning their compute credits for every attack they attempt.
+
+---
+
+## What's Inside: The Hybrid Detection Engine
+
+SpamWarden doesn't just rely on one method. It processes input through a strict three-phase pipeline designed to be lightning-fast and mathematically invisible to security scanners (no `eval()`, no DOM injection).
 
-**SpamWarden.js** is a zero-dependency, universal engine that detects spam directly at the source. It uses a **Present-Only Naive Bayes** model (derived from Bernoulli Naive Bayes) trained specifically on Thai spam patterns (gambling, loans, "fast money" scams) and optimized with a dynamic, length-calibrated decision threshold to eliminate false positives on longer, clean text.
+### Phase 1: The "Lightcheck" (Zero-Math Blocking)
 
-By running natively, it allows you to **block spam before it ever hits your database**, saving server resources and keeping your data clean.
+Before waking up the heavy machine learning model, the engine does a microsecond sweep for hardcoded malicious intent.
 
-![SIEM Endpoint & Spam Block Demo](https://cdn.redsocs.com/assets/siem-endpoint-spamblock-demo.gif)
+- Instantly blocks isolated currency symbols (`$`, `€`, `£`, `฿`) often used in fast-money scams.
+- Instantly blocks known spam link shorteners and redirectors (`line[dot]me`, `bit[dot]ly`).
+- _Result: Zero CPU wasted on obvious bot blasts._
 
-# Live Demo & Scanner
+### Phase 2: The Thai-Optimized Tokenizer
 
-You can test the spam engine interactively, analyze your forms, and generate auto-blocking script configurations directly on our GitLab Pages site:
+Standard Western spam filters break text by spaces, which completely fails for the Thai language.
 
-👉 **[Live Demo & Generator](https://spam-warden-js-527b79.gitlab.io/)**
+- The engine sweeps through the input, stripping whitespace and generating **trigrams** (3-letter groups) and **quadgrams** (4-letter groups) for the entire string.
+- _Result: Mathematically forces space-less Thai words to reveal their hidden spam clusters._
 
-# Quickstart
+### Phase 3: Present-Only Naive Bayes (The Core)
+
+A modified Naive Bayes classifier trained exclusively on real-world spam samples.
+
+- **CPU Friendly:** It utilizes a `Set` to track _only_ the vocabulary features actually present in the user's text, calculating logarithmic probability exclusively for those matches rather than iterating over the entire 28,000+ word dictionary.
+- **Dynamic Thresholding:** To prevent false positives on genuinely long, detailed user comments, it applies a length-dependent threshold penalty: $5.5+0.49\times{N}$ (where N is the number of matched features). The longer the text, the harder the engine adjusts to remain fair.
+
+---
+
+## Security & Active Defense (SAST Compliant)
+
+SpamWarden utilizes a **Hostile Active Defense** architecture. It is built to pass enterprise audits while remaining an absolute nightmare for automated botnets.
+
+1. **The Phantom Core (Closure Isolation):** The real detection engine does _not_ exist on the global `window` object. It is sealed entirely inside an anonymous execution closure. It is technically impossible for an attacker's script to query, overwrite, or disable the core function via the browser console.
+2. **Polymorphic Ghost Tarpits (The Honeypot):** At execution, the script dynamically generates polymorphic decoy engines hidden behind believable frontend variable names (e.g., `window.aBcDeCache`). If a bot bypasses the UI and blindly executes these fakes, they are trapped in the bounded PoW `djb2` hash loop.
+3. **Brutal DOM Protection:** By utilizing Document-Level Capturing Phase listeners and Prototype Monkey-Patching, SpamWarden intercepts malicious submissions _before_ they reach the form element, defeating direct `document.forms[0].submit()` bypasses.
+4. **Anti-Tamper Lockout:** If a script attempts to strip the `data-sw-protect` targeting attributes off your HTML, a hidden internal `MutationObserver` instantly detects the tampering and permanently disables the form.
+
+---
+
+## Quickstart
 
 > [!IMPORTANT]
-> **Are you a Thai government agency or public sector website administrator?**
-> Get your free token configuration and drop-in script to protect your online portals from annoying gambling/loan ads and spam campaigns at [redsocs.com/spam-warden](https://redsocs.com/spam-warden).
+> **For Public Sector & Government Admins:** Get your free token configuration and drop-in script to protect your online portals at [redsocs.com/spam-warden](https://redsocs.com/spam-warden).
+
+---
 
 ### 1. Zero-Config Local Protection (No Telemetry)
 
-Add this script to your page with the `data-auto-protect` attribute. It will automatically find your most significant forms (using an intelligent heuristic: top 2 forms with >= 2 inputs) and block submission if spam is detected.
+Explicit opt-in protection. No data leaves the browser. Simply include the script and tag your inputs.
 
-By default, this mode also enables PII masking (DLP). To disable PII masking, add `data-sd="0"`.
+**Which file should you choose? (Pick ONLY ONE):**
+
+- `spamwarden.min.js`: The standard minified version. Best for general performance and faster browser parse times.
+- `spamwarden.min.ob.js`: The obfuscated version. It applies control-flow flattening and string encoding to aggressively penalize reverse-engineering attempts by malicious actors, at the cost of a slightly larger file size.
 
 ```html
-<script
-  src="https://cdn.redsocs.com/js/spamwarden.min.js"
-  data-auto-protect
-></script>
+<!-- ⚠️ IMPORTANT: Choose ONLY ONE of the scripts below. Do not include both! -->
+
+<!-- Option A: Standard Minified (Best Performance) -->
+<script src="https://cdn.redsocs.com/js/spamwarden.min.js"></script>
+
+<!-- Option B: Obfuscated (Maximum Security) -->
+<!-- <script src="https://cdn.redsocs.com/js/spamwarden.min.ob.js"></script> -->
+
+<form>
+  <!-- Just add data-sw-protect="true" to any field -->
+  <textarea name="comment" data-sw-protect="true"></textarea>
+  <button type="submit">Submit</button>
+</form>
 ```
 
-### 2. Enterprise Telemetry (SIEM Integration)
+---
+
+### 2. Enterprise Telemetry & DLP (SIEM Integration)
 
-If you need to report blocked spam payloads to a central SIEM/SOC, provide a Base64 configuration string via the `endpoint` parameter.
+Report blocked payloads to a central SOC, SIEM, or custom logging server. Use the `siems` attribute to define your receiving endpoint(s). You can provide a single URL or a comma-separated list of multiple URLs to broadcast the telemetry to several destinations simultaneously.
+
+Add `data-sd="1"` to enable built-in Data Loss Prevention (DLP), which automatically masks Credit Cards, Phone Numbers, and Emails (`[CARD_MASKED]`) before network transmission.
+
+**Single Endpoint:**
 
 ```html
-<script src="https://cdn.redsocs.com/js/spamwarden.min.js?endpoint=MHxzaWVtLnJlZHNvY3MuY29tL3Yx"></script>
+<script
+  src="https://cdn.redsocs.com/js/spamwarden.min.ob.js"
+  siems="siem.redsocs.com/v1"
+  data-sd="1"
+></script>
 ```
 
-_Note: The `endpoint` parameter is a Base64 encoded string of `sdFlag|siemEndpoint` (e.g., `0|siem.redsocs.com/v1`)._
+**Multiple Endpoints (Comma-separated):**
+
+```html
+<script
+  src="https://cdn.redsocs.com/js/spamwarden.min.ob.js"
+  siems="api-spam.siem.go.th/v1?token=[token],siem-logger.yourdomain.com/logs"
+  data-sd="1"
+></script>
+```
 
 ### 3. API Usage (Node Only)
 
 ```javascript
-const result = spamwarden.spamcheck(
-  "[Hello, this is a Thai casino & scam ads — and guess what? Your tax pays for my traffic.]",
+const sw = require("@redsocs/spam-warden");
+
+const result = sw.spamcheck(
+  "[Hello, this is a Thai casino & scam ads — guess what? Your tax pays for my traffic.]",
 );
+
 if (result.isSpam) {
   console.log("Blocked:", result.reason || "AI match");
   console.log("Confidence:", result.prob);
 }
 ```
 
-# Scope
-
-SpamWarden is designed for **interactive web elements**:
-
-- **Contact Forms:** Prevent bot and manual spam submissions.
-- **Comment Sections:** Real-time feedback for users before they post.
-- **Chat Inputs:** Instant filtering of malicious links and currency-heavy spam.
-- **Privacy-First Apps:** Since detection happens locally, user data doesn't leave the browser unless explicitly reported.
-
-# What's inside?
-
-- **Hybrid Detection Engine:**
-  - **Hard Rules:** Instant blocking for currency symbols (`$€£฿`) and known spam link patterns (`line[dot]me`, `bit[dot]ly`).
-  - **Thai-Optimized Tokenizer:** Extracts whitespace tokens, **trigrams**, and **quadgrams** to handle the space-less nature of the Thai language.
-  - **Present-Only NB Classifier:** A modified Naive Bayes model trained on real-world spam samples. It only evaluates present vocabulary features and utilizes a length-dependent threshold offset ($5.5 + 0.49 \times N$ matched features) to calibrate confidence and prevent false positives on longer clean texts.
-- **Telemetry System:** Optional auto-reporting of spam hits to `api.redsocs.com` for global threat intelligence.
-- **Auto-Interceptor:** Event listeners that hook into DOM forms to provide "Drop-in" protection.
-
-# Why this exists?
+---
 
-Traditional spam filters (like Akismet or ReCaptcha) often:
+## Scope & Backend Requirements
 
-1. Require a round-trip to a server (latency).
-2. Are expensive for high-volume sites.
-3. Over-collect user data (privacy concerns).
-4. Struggle with specific Thai-language spam patterns.
+SpamWarden is designed for **interactive web elements**: Contact Forms, Comment Sections, and Chat Inputs.
 
-**SpamWarden** exists to provide a **local, fast, and Thai-centric** alternative that stops spam at the source: the user's input field.
+> [!WARNING]
+> **Client-Side Limits:** All client-side code is inherently bypassable by a sufficiently motivated, manual human attacker. If you require absolute security, you **must** validate payloads on your backend.
+>
+> - **For WordPress:** Use our [SpamWarden WP Plugin](https://redsocs.com/spam-warden) to protect your server at the PHP layer.
+> - **For Custom Stacks (Node):** Grab this NPM package directly, bundle it internally, and run the `spamcheck()` function on your backend server before hitting your database.
 
-# Security & Active Defense
+---
 
-> [!WARNING]
-> **Honesty First:** All client-side code is inherently bypassable by a sufficiently motivated human. However, we have engineered this library to be an absolute nightmare for automated bots and script kiddies.
+## Local Simulation & Testing
 
-We do not rely solely on "Security through Obscurity." SpamWarden employs a **Hostile Active Defense** architecture:
+Spin up a local simulation server to test the DOM auto-blocking behavior and inspect SIEM telemetry payloads in real time:
 
-1. **The Ghost Tarpit (Honeypot):** We intentionally deploy a "Poison Pill" decoy. If a bot or attacker attempts to bypass or tamper with the script, they are redirected into this trap, which is designed to actively retaliate by crashing headless browsers (Puppeteer/Playwright) and wasting attacker compute credits.
-2. **Build-Time Randomization (The Moving Target):** The real machine-learning engine is hidden inside an isolated closure and bound to the DOM using a randomized cryptographic key generated during compilation. The internal execution path changes on every release, defeating static bypass scripts.
-3. **Brutal DOM Protection:** By utilizing Document-Level Capturing Phase listeners, Prototype Monkey-Patching, and MutationObservers, SpamWarden intercepts submissions before they reach the form element. This defeats trivial bypasses like form cloning or direct `document.forms[0].submit()` calls.
-4. **Aggressive Obfuscation:** The final distribution is run through proprietary, high-entropy obfuscation routines to protect the model weights and heavily penalize reverse engineering attempts.
+1. **Start the server**: `npm run test-server`
+2. **Open the test page** in your browser:
+   [http://localhost:3000/](https://www.google.com/search?q=http://localhost:3000/)
+3. **Submit a spam message** (e.g., including currency signs like `฿` or links like `line[dot]me`).
+4. **Observe the result**:
 
-If you require absolute, mathematically unbroken security, client-side protection will never be enough. You **must** validate payloads on your backend:
+- The form submission will be blocked on the page.
+- The terminal will display the defanged and sanitized telemetry payload sent to the SIEM receiver:
+
+```text
+🚨 [SIEM RECEIVER] Blocked Payload Received!
+================================================
+Endpoint: siem.gov-sec.go.th/v1?token=eGuec...
+URL:          h_tt_p://victim.go.th:3000/
+Rule Matched: currency_symbol
+Confidence:   100%
+PII Masked?   true
+Pasted?       false
+Actors:       [[at]TUNA_FISH]
+Sanitized:    "Win [CARD_MASKED] now! [at]TUNA_FISH"
+================================================
+```
 
-- **For WordPress:** Use our [SpamWarden WP Plugin](https://redsocs.com/spam-warden) to protect your server at the PHP layer (Paid).
-- **For Node.js/Custom Stacks:** Grab this NPM package directly, bundle it internally, and run the `spamcheck()` function on your backend server before hitting your database (Free).
+**_And if it no config or attribute script at `endpoint` this tool send nothing to the outside._**
 
-# Local Simulation & Testing
+---
 
-You can spin up a local simulation server to test the DOM auto-blocking behavior and inspect the SIEM telemetry payloads in real time:
+About
 
-1. **Start the simulation server**:
-   ```bash
-   npm run test-server
-   ```
-2. **Open the test page** in your browser:
-   [http://localhost:3000/](http://localhost:3000/)
-3. **Submit a spam message** (e.g., including currency signs like `฿` or links like `line[dot]me`).
-4. **Observe the result**:
-   - The form submission will be blocked on the page.
-   - The terminal will display the defanged and sanitized telemetry payload sent to the SIEM receiver:
-     ```text
-     🚨 [SIEM RECEIVER] Blocked Payload Received!
-     ================================================
-     Endpoint Token: MXxodHRwOi8vbG9jYWxob3N0OjMwMDAvdjEvdGVsZW1ldHJ5
-     URL:          h_tt_p://localhost:3000/
-     Rule Matched: currency_symbol
-     Confidence:   100%
-     PII Masked?   false
-     Pasted?       false
-     Actors:       []
-     Sanitized:    "Win [CARD_MASKED] now!"
-     ================================================
-     ```
-
-# About
-
-- **Version:** 1.1.11 (Engine v11.06)
+- **Version** 1.3.0 (Engine v11.06)
 - **Author:** [RedSocs](https://github.com/RedSocs)
 - **License:** MIT
-- **Model Origin:** Trained via [RedSocs/spam-labeler](https://github.com/RedSocs/spam-labeler)
-- **Inquiries & Enterprise Support:** [pichit[at]redsocs.com](mailto:pichit@redsocs.com)
+- **Inquiries & Enterprise Support:** [pichit[at]redsocs.com](https://www.google.com/search?q=mailto%3Apichit%40redsocs.com)
 - **Sponsor:** [Buy Me a Coffee](https://buymeacoffee.com/redsocs?new=1)
 
 ---
 
 ### Technical Specs
 
-| Property          | Value                     |
-| ----------------- | ------------------------- |
-| **Minified Size** | ~2.0 MB (including model) |
-| **Gzipped Size**  | **~341 KB**               |
-| **Dependencies**  | 0 (Vanilla JS)            |
-| **Vocabulary**    | 28106 features            |
+| Property            | Value                             |
+| ------------------- | --------------------------------- |
+| **Minified Size**   | ~2.0 MB (including model weights) |
+| **Gzipped Size**    | **~341 KB**                       |
+| **Dependencies**    | 0 (Vanilla JS)                    |
+| **Vocabulary**1.3.0 | 28,106 features                   |