@4884org/jumble

Version:

🛡️ Advanced bot detection & content protection component with 100ms optimized timing. Automatically detects bots and scrambles text content while obfuscating media to protect websites. Universal implementation works with React, Vue, Angular, Svelte.

github.com/4884org/jumble

4884org/jumble

261 lines (198 loc) • 9.46 kB

Markdown

<div align="center"> <h1 style="font-size: 4rem; font-weight: bold; margin: 0; padding: 20px 0; letter-spacing: 3px;"> 🛡️ JUMBLE </h1> <h3 style="margin: 0; color: #666; font-weight: 300;"> Advanced Bot Detection & Content Protection </h3> </div> <div align="center"> [![npm version](https://img.shields.io/npm/v/@4884org/jumble?style=flat-square&logo=npm&logoColor=white)](https://npmjs.com/package/@4884org/jumble) [![npm downloads](https://img.shields.io/npm/dm/@4884org/jumble?style=flat-square&logo=npm&logoColor=white)](https://npmjs.com/package/@4884org/jumble) [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg?style=flat-square)](https://opensource.org/licenses/MIT) </div> --- 🛡️ **Advanced Bot Detection & Content Protection** 🤖 Automatically detects bots and scrapers using sophisticated heuristics, then scrambles text content and obfuscates media to protect your website while maintaining full accessibility for human users. ## 🔍 **SEO-Safe Protection** ✅ **Smart bot detection that protects your content from scrapers while allowing search engines to index your site properly:** - ✅ **Google, Bing, Yahoo** → See real content for indexing - ✅ **Facebook, Twitter, LinkedIn** → See real content for social previews - ✅ **SEO tools** (SEMrush, Ahrefs) → See real content for analysis - ❌ **Scrapers & headless browsers** → See scrambled content - ❌ **AI training bots** → See scrambled content - ❌ **Content harvesters** → See obfuscated media **SEO protection is enabled by default** - no configuration needed! ## 📦 Installation ### NPM Installation Install via npm for maximum flexibility and version control: ```bash npm install @4884org/jumble ``` ### CDN Installation Quick setup via CDN for rapid prototyping: ```html <script type="module" src="https://unpkg.com/@4884org/jumble@latest/dist/jumble/jumble.esm.js"></script> ``` ## 🚀 Universal Usage Pattern (Works with Any Framework) **Add the loader script to `<head>`, `<jumble-head>` as the first element in `<body>`, and the critical CSS/class to `<html>`.** ```html <!DOCTYPE html> <html lang="en" class="jumble-init"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>Protected Content</title>  <style> html.jumble-init * { visibility: hidden !important; } </style>  <script type="module" src="https://unpkg.com/@4884org/jumble@latest/dist/jumble/jumble.esm.js"></script> </head> <body>  <jumble-head></jumble-head> <main> <h1>Your content will be protected automatically</h1> <p>This text will be scrambled for bots but readable for humans.</p> <img src="image.jpg" alt="This image will be hidden from bots"> <video src="video.mp4" controls></video> </main> </body> </html> ``` ## 🛠️ Framework Integration **This pattern works for React, Vue, Angular, Svelte, and static sites.** - Do **not** use `<jumble-head>` in any React/JSX/TSX/component file. - Do **not** add custom element type declarations for React/TypeScript. - Do **not** use `defineCustomElements()` in your app code unless you need advanced loader scenarios. - Just add the loader script and `<jumble-head>` to your main HTML file as above. **Your app content works as usual. Jumble protects it automatically.** ## ⚙️ Component Attributes Reference The `<jumble-head>` component accepts the following attributes for customization: | Attribute | Type | Default | Description | |-----------|------|---------|-------------| | allow-seo | boolean | true | Allow search engine bots to see real content for SEO. | | custom-allowlist | string[] | [] | Additional legitimate bot user agents to allow. | | custom-denylist | string[] | [] | Additional suspicious bot patterns to block. | ## 📋 **Component Attributes Reference** The `<jumble-head>` component accepts the following attributes for customization: | Attribute | Type | Default | Description | |-----------|------|---------|-------------| | `allow-seo` | `boolean` | `true` | Controls SEO protection mode. When `true`, legitimate search engines see real content. When `false`, ALL bots see scrambled content. | | `custom-allowlist` | `string[]` | `[]` | JSON array of additional bot patterns to allow (added to default search engines). Case-insensitive matching. | | `custom-denylist` | `string[]` | `[]` | JSON array of additional bot patterns to block (added to default malicious patterns). Case-insensitive matching. | ### **Basic Usage Examples** ```html  <jumble-head></jumble-head>  <jumble-head allow-seo="false"></jumble-head>  <jumble-head custom-allowlist='["mypartnerbot", "trustedapi"]'></jumble-head>  <jumble-head custom-denylist='["badbot", "evilscraper", "harvester"]'></jumble-head>  <jumble-head allow-seo="true" custom-allowlist='["partnerbot", "apiservice"]' custom-denylist='["maliciousbot", "scraper123"]'> </jumble-head> ``` ### **Attribute Details** #### `allow-seo` (boolean) - **Default:** `true` (SEO-safe mode) - **When `true`:** Legitimate search engines (Google, Bing, Facebook, etc.) see real content for indexing and social previews - **When `false`:** ALL bots see scrambled content (maximum protection but breaks SEO) ```html  <jumble-head allow-seo="true"></jumble-head>  <jumble-head allow-seo="false"></jumble-head> ``` #### `custom-allowlist` (string array) - **Default:** `[]` (empty array) - **Purpose:** Add specific bot patterns that should be allowed to see real content - **Format:** JSON array of strings (case-insensitive partial matching) - **Combined with:** Default legitimate search engines (Google, Bing, Facebook, etc.) ```html  <jumble-head custom-allowlist='["uptimerobot"]'></jumble-head>  <jumble-head custom-allowlist='["partnerapi", "trustedbot", "monitoring-service"]'></jumble-head> ``` #### `custom-denylist` (string array) - **Default:** `[]` (empty array) - **Purpose:** Add specific bot patterns that should be blocked and see scrambled content - **Format:** JSON array of strings (case-insensitive partial matching) - **Combined with:** Default malicious patterns (headless browsers, scrapers, AI training bots, etc.) ```html  <jumble-head custom-denylist='["badbot"]'></jumble-head>  <jumble-head custom-denylist='["scraper", "harvester", "malicious-bot", "content-stealer"]'></jumble-head> ``` ### **Real-World Configuration Examples** ```html  <jumble-head allow-seo="true" custom-allowlist='["shopify-monitor", "price-tracker"]' custom-denylist='["competitor-scraper", "price-spy"]'> </jumble-head>  <jumble-head allow-seo="true" custom-denylist='["content-scraper", "article-bot"]'> </jumble-head>  <jumble-head allow-seo="false" custom-allowlist='["internal-monitor"]'> </jumble-head>  <jumble-head></jumble-head> ``` ## 📚 **Built-in Bot Detection** ### **Default Legitimate Bots (Always Allowed with `allow-seo="true"`)** - **Search Engines:** Google, Bing, Yahoo, DuckDuckGo, Yandex, Baidu - **Social Media:** Facebook, Twitter, LinkedIn, WhatsApp, Telegram, Discord - **SEO Tools:** SEMrush, Ahrefs, Majestic, Moz, Screaming Frog - **Monitoring:** UptimeRobot, Pingdom, GTmetrix ### **Default Malicious Patterns (Always Blocked)** - **Automation Tools:** Selenium, Puppeteer, Playwright, PhantomJS - **Generic Scrapers:** headless, scraper, crawler, harvester, extractor - **AI Training Bots:** GPTBot, ClaudeBot, CCBot, meta-externalagent - **And 20+ more malicious patterns...** ## 🌍 Multi-Language Support Jumble intelligently handles different writing systems: - **Latin Characters (a-z, A-Z):** Scrambled to random lowercase letters - **Arabic Script (0x0600-0x06FF):** Scrambled to random Arabic characters - **CJK Ideographs (0x4E00-0x9FFF):** Scrambled to random Chinese characters - **Numbers (0-9):** Left unchanged for functionality - **Punctuation & Symbols:** Preserved to maintain readability structure - **Emojis:** Remain unchanged ## 🔧 Development ### Building ```bash npm run build ``` ### Testing ```bash npm test npm run test:e2e npm run test:coverage ``` ### Starting the dev server ```bash npm start ``` ## 📖 Additional Resources - **[Live Demo](https://4884org.github.io/jumble/)** - Interactive demonstration - **[NPM Package](https://www.npmjs.com/package/@4884org/jumble)** - Package details - **[GitHub Repository](https://github.com/4884org/jumble)** - Source code ## 📄 License MIT License - see LICENSE file for details.