Installation • Usage • API • Security • Contributing

🚀 Features

• 🔒 Security-First: Comprehensive detection of malicious patterns and exploits
• 📘 TypeScript Native: Full TypeScript support with strict typing
• 🌐 Universal Compatibility: Works with ESM (import) and CommonJS (require)
• ⚡ Zero Dependencies: Lightweight with no external dependencies
• 🎛️ Highly Configurable: Customizable thresholds and detection rules
• 🧪 Battle-Tested: Extensive test suite with 100% code coverage
• 📦 Production Ready: Used in production environments
• 🚫 Privacy Focused: No data collection or external API calls
• 🔐 Security-key login: create login auth using teka teki ('clue: change raw to hash') ['code implementation will be shown in WhatsApp Channel']

📦 Installation

npm install guranteed-security

yarn add guranteed-security

pnpm add guranteed-security

🛡️ Security Features

| Attack Vector | Detection | Description | |---------------|-----------|-------------| | Text Bombing | ✅ | Detects messages with extreme text length | | Invisible Character Abuse | ✅ | Identifies high density invisible Unicode attacks | | Mention Bombing | ✅ | Catches excessive user mention exploitation | | Protocol Exploitation | ✅ | Detects unusual WhatsApp protocol message types | | Media Abuse | ✅ | Identifies files with unrealistic properties | | Button/List Flooding | ✅ | Prevents UI flooding with excessive elements | | Pairing Code Injection | ✅ | Blocks fake WebSocket URL injection attempts | | Annotation Abuse | ✅ | Detects oversized video annotation payloads | | External Ad Exploitation | ✅ | Prevents external ad reply abuse |

🎯 Quick Start

ESM (ES Modules)

import { generateOneTimeToken, verifyOneTimeToken } from 'guranteed-security'

// Generate Token
const { raw, meta } = generateOneTimeToken()
console.log('Token:', raw)
console.log('Meta:', meta)

/*
📌 Token akan disimpan dalam folder "Rexxzy-security-code" sebagai hash SHA256
dan hanya bisa digunakan 1x (One-Time Token). Token akan otomatis expire setelah 1 jam (default TTL).
*/

// ✅ Verifikasi Token
const isValid = verifyOneTimeToken(raw)
console.log('Valid?', isValid)

// ❌ Token hanya bisa digunakan sekali
const reuse = verifyOneTimeToken(raw)
console.log('Reuse (should be false):', reuse)

import { analyzeMessage } from 'guranteed-security';

const message = {
  conversation: "Hello, this is a normal message"
};

const result = analyzeMessage(message);
console.log(result); // { isMalicious: false, reason: null }

CommonJS

const { analyzeMessage } = require('guranteed-security');

const suspiciousMessage = {
  conversation: "A".repeat(30000) // Extremely long text
};

const result = analyzeMessage(suspiciousMessage);
console.log(result); // { isMalicious: true, reason: "Extreme text length" }

With Custom Configuration

import { analyzeMessage, type AnalysisOptions } from 'guranteed-security';

const options: AnalysisOptions = {
  maxTextLength: 10000,
  maxMentionCount: 50,
  maxButtonCount: 10
};

const result = analyzeMessage(message, options);

📚 API Reference

analyzeMessage(message, options?)

Analyzes a WhatsApp message for potentially malicious content.

Parameters:

• message: WhatsAppMessage | null | undefined - The WhatsApp message object to analyze
• options?: AnalysisOptions - Optional configuration for analysis thresholds

Returns:

• AnalysisResult - Analysis result with malicious status and reason

Types

AnalysisResult

interface AnalysisResult {
  isMalicious: boolean;    // Whether the message is detected as malicious
  reason: string | null;   // Specific reason for detection (null if not malicious)
}

AnalysisOptions

interface AnalysisOptions {
  maxTextLength?: number;                    // Max text length (default: 25000)
  maxInvisibleCharCount?: number;            // Max invisible chars (default: 5000)
  maxInvisibleCharRatio?: number;            // Max invisible char ratio (default: 0.5)
  maxMentionCount?: number;                  // Max mentions (default: 1000)
  maxAlbumItems?: number;                    // Max album items (default: 50)
  maxMediaDuration?: number;                 // Max media duration in seconds (default: 3600)
  maxFileSize?: number;                      // Max file size in bytes (default: 2GB)
  maxPageCount?: number;                     // Max document pages (default: 1000000)
  maxExternalAdReplyLength?: number;         // Max ad reply length (default: 5000)
  maxParamsJsonLength?: number;              // Max params JSON length (default: 10000)
  maxVideoAnnotationAuthorLength?: number;   // Max annotation author length (default: 5000)
  maxListRows?: number;                      // Max list rows (default: 1000)
  maxButtonCount?: number;                   // Max buttons (default: 100)
  maxLocationCommentLength?: number;         // Max location comment (default: 5000)
  maxContactDisplayNameLength?: number;      // Max contact name (default: 5000)
  maxLiveLocationSequenceNumber?: number;    // Max live location sequence (default: 999999999)
  maxProductImageCount?: number;             // Max product images (default: 100)
  maxOrderItemCount?: number;                // Max order items (default: 1000)
}

WhatsAppMessage

interface WhatsAppMessage {
  conversation?: string;
  extendedTextMessage?: ExtendedTextMessage;
  imageMessage?: ImageMessage;
  videoMessage?: VideoMessage;
  audioMessage?: AudioMessage;
  documentMessage?: DocumentMessage;
  // ... other message types
}

🔍 Detection Examples

Text Length Abuse

const maliciousMessage = {
  conversation: "A".repeat(30000) // 30k characters
};

const result = analyzeMessage(maliciousMessage);
// { isMalicious: true, reason: "Extreme text length" }

Mention Bombing

const mentionBomb = {
  extendedTextMessage: {
    text: "Hello everyone!",
    contextInfo: {
      mentionedJid: new Array(1500).fill("[email protected]")
    }
  }
};

const result = analyzeMessage(mentionBomb);
// { isMalicious: true, reason: "Massive mention count" }

Media Property Abuse

const suspiciousMedia = {
  videoMessage: {
    seconds: 7200,        // 2 hours
    fileLength: "5000000000", // 5GB
    caption: "Normal video"
  }
};

const result = analyzeMessage(suspiciousMedia);
// { isMalicious: true, reason: "Bug: Media with unreasonable properties" }

Invisible Character Attack

const invisibleAttack = {
  conversation: '\u200b'.repeat(6000) + 'hidden payload'
};

const result = analyzeMessage(invisibleAttack);
// { isMalicious: true, reason: "High density of invisible characters" }

Button Flooding

const buttonFlood = {
  buttonsMessage: {
    buttons: new Array(150).fill({ buttonText: { displayText: "Click" } })
  }
};

const result = analyzeMessage(buttonFlood);
// { isMalicious: true, reason: "Bug: Message with excessive buttons" }

🏗️ Advanced Usage

Batch Analysis

const messages = [
  { conversation: "Hello" },
  { conversation: "A".repeat(30000) },
  { extendedTextMessage: { text: "Hi", contextInfo: { mentionedJid: ["[email protected]"] } } }
];

const results = messages.map(msg => ({
  message: msg,
  analysis: analyzeMessage(msg)
}));

const maliciousMessages = results.filter(r => r.analysis.isMalicious);
console.log(`Found ${maliciousMessages.length} malicious messages`);

Custom Security Profile

// High security profile
const strictOptions: AnalysisOptions = {
  maxTextLength: 5000,
  maxMentionCount: 10,
  maxButtonCount: 3,
  maxFileSize: 100000000, // 100MB
  maxMediaDuration: 300   // 5 minutes
};

// Relaxed profile for trusted environments
const relaxedOptions: AnalysisOptions = {
  maxTextLength: 50000,
  maxMentionCount: 5000,
  maxButtonCount: 500
};

const result = analyzeMessage(message, strictOptions);

Integration with Express.js

import express from 'express';
import { analyzeMessage } from 'guranteed-security';

const app = express();
app.use(express.json());

app.post('/webhook/whatsapp', (req, res) => {
  const { message } = req.body;
  
  const analysis = analyzeMessage(message);
  
  if (analysis.isMalicious) {
    console.log(`⚠️  Malicious message detected: ${analysis.reason}`);
    // Handle malicious message (log, block, notify, etc.)
    return res.status(400).json({ error: 'Message blocked', reason: analysis.reason });
  }
  
  // Process normal message
  res.json({ status: 'processed' });
});

⚡ Performance

• Memory efficient: ~2MB memory footprint
• Fast analysis: <1ms per message on average
• Scalable: Handles thousands of messages per second
• Non-blocking: Synchronous API with minimal CPU usage

🛠️ Development

Prerequisites

• Node.js ≥ 20.0.0
• npm, yarn, or pnpm

Available Scripts

npm run build       # Build for production (ESM + CJS)
npm test           # Run test suite
npm run test:watch # Run tests in watch mode
npm run test:cov   # Run tests with coverage
npm run lint       # Lint code
npm run lint:fix   # Fix linting issues
npm run clean      # Clean build artifacts

Project Structure

src/
├── __tests__/           # Test files
├── analyzer.ts          # Core analysis logic
├── securitytoken.ts         # Security bot token
├── types.ts            # TypeScript definitions
└── index.ts            # Main entry point

🔧 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Quick Contribution Steps

• provide further suggestions for the next update

Development Guidelines

• Write tests for all new features
• Maintain 100% code coverage
• Follow the existing code style
• Update documentation as needed
• Ensure TypeScript strict mode compliance

📋 Changelog

See CHANGELOG.md for a detailed history of changes.

🔒 Security

Reporting Vulnerabilities

If you discover a security vulnerability, please send an email to [email protected]. All security vulnerabilities will be promptly addressed.

Security Features

• No external dependencies - reduces attack surface
• No network calls - all analysis happens locally
• No data storage - messages are analyzed in memory only
• Stateless operation - no persistent state or caching

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• WhatsApp Web reverse engineering community
• Security researchers who identified these attack vectors
• Open source contributors and maintainers

Thank you to those who have provided support, inspiration and contributions directly or indirectly in the development of this project:

• Allah SWT
  For all His grace and ease.

• Parent
  For your continued love, prayers, and support.

• joo-devweb
  As an initial foundation and reference in the development of this system.

• RexxHayanasi (Me)
  The main developer of this project.

🏠 Homepage • 🐛 Report Bug • ✨ Request Feature

modified by RexxHayanasi using ♥️ for all