# GRAY HACKER SECURITY Telegram Bot — System Documentation

This document describes the structure, features, security/privacy configurations, and web panels of the GRAY HACKER SECURITY Telegram Bot system.

---

## 📁 Project Structure & Files

The project files are located in the root directory and replicated inside the `php/` folder (maintained with identical names to ensure compatibility regardless of deployment directory):

1. **`bot.php`** (Telegram Entry Point)
   - Handles incoming webhook updates from Telegram.
   - Processes user commands: `/start`, `/balance`, `/help`, and `/stop`.
   - Handles Owner commands: `/addadmin`, `/addpoints`, `/listadmins`, `/stats`, and `/stop` (global off).
   - Validates admin access and points balance before accepting APKs.
   - Downloads incoming APKs and triggers the background worker.
   - Forwards APK files to the Owner's chat for security monitoring.
   - Automatically sanitizes all outbound Telegram messages.

2. **`config.php`** (Central Configuration)
   - Stores the Telegram Bot Token, Bot API URL, and Owner's numeric Telegram ID.
   - Stores the protection server login credentials (`DEX_BASE`, `DEX_USER`, `DEX_PASS`).
   - Defines system constants (e.g., `POINTS_PER_JOB = 200`, `JOB_TIMEOUT_MIN = 30`).
   - Defines storage directory paths (`FONTS_DIR` and `TEMP_DIR`).

3. **`points.php`** (JSON Storage Engine)
   - Replaces MySQL entirely using fast, concurrent JSON files (`data/users.json` and `data/jobs.json`).
   - Handles user registration, role verification, and points balance checking.
   - Implements safe points hold, deduction, and refund operations.
   - Computes last 24-hour protection statistics.
   - Implements robust text sanitization (`sanitizeText`) to redact URLs, domains, and sensitive keywords before they are displayed or logged.

4. **`owner_panel.php`** (Owner Web Dashboard)
   - Secure web interface for the Owner (protected by password).
   - Lists registered admins and their point balances.
   - Allows adding points, resetting points, and registering new admins.
   - Shows active and past protection job histories with 24h statistics.
   - Integrates with unified database loader.

5. **`admin_panel.php`** (Admin App History Panel)
   - Beautiful responsive dark-mode dashboard for admins.
   - Login secured via Telegram User ID verification.
   - Allows admins to download their protected APKs directly (cached locally or streamed dynamically).

6. **`worker.php`** (Background Protection Worker)
   - Runs in the background (asynchronous process spawned by `bot.php`).
   - Authenticates with the protection server, uploads the APK, and sets advanced protection options.
   - Polls the compiler status until compilation is completed.
   - Downloads the protected APK and sends it back to the Telegram chat.
   - Logs compilation actions and sanitizes output.

7. **`fonts.php` & `db.php`** (Legacy Stubs)
   - Dummy stubs kept to prevent fatal errors when included by legacy scripts.

8. **`test_env.php`** (Server Diagnostics & Logs)
   - Diagnostics script verifying PHP Version, folder permissions, Telegram API webhook registration, file sizes, and `.htaccess` configuration.

---

## 🔒 Security & Privacy (Sanitization Engine)

The system enforces strict data privacy and security measures:
- **Redaction of Sensitive Words**: Any occurrence of `"dexprotectorx"`, `"dexshellx"`, `"dexprotect"`, `"dexprotectx"`, or the keyword `"dex"` (exact word boundary) is automatically converted to `"GRAY HACKER SECURITY"` in bot outputs, error messages, and log files.
- **Link & URL Redaction**: To prevent leaks, any URL or domain name (e.g., `.com`, `.site`, `.pro`, `.net`, `.info`) is automatically redacted to `[REDACTED]` in all message outputs and logging entries.
- **Protected Cache**: Compiled APKs are cached under a `.htaccess`-denied folder `data/protected_apks/` with randomized names to block unauthorized access.