Multi Tool Bot

A privacy-conscious PHP Telegram bot with authenticated Telegram Mini Apps, bounded file utilities, AI Chat and Agent Mode in bot chat, and an isolated managed hosted-clone system.

Public-source notice: This repository is intentionally sanitized. It contains no production credentials, deployment URLs, bot handles, admin identities, provider keys, runtime records, uploaded files, or platform-specific 7zz binary. Start with config.example.php; never commit config.php.

What it provides

• Telegram bot chat — AI Chat, Agent Mode, photo reading, Tool Hub navigation, history controls, Help, Privacy Policy, and Terms.
• Telegram Mini Apps — archive extraction for ZIP-based containers and .7z, arbitrary file encryption/decryption, account controls, and owner-only administration.
• Managed hosted clones — a creator connects a BotFather bot they control and supplies an independent provider key. Clones have separate webhooks, state, history, temporary storage, and owner settings.
• Safety boundaries — signed Telegram Web App authentication, HTTPS-only sensitive submission, encrypted credential vaults, webhook-secret verification, strict rate/size/time limits, expiring downloads, tenant isolation, and fail-closed storage behavior.
• No image generation or editing — photo reading produces text only, using a creator-configured provider key where enabled.

Feature boundaries

Surface	Available capabilities
Primary bot chat	AI Chat, Agent Mode, bounded history, photo reading, Tool Hub and legal navigation
Primary Tool Hub	Archive extraction, file encryption/decryption, account, owner administration, clone builder
Clone bot chat	AI Chat, Agent Mode, bounded history, photo reading after its owner configures a key
Clone Tool Hub	Archive/file-security tools, account and clone-owner settings
Mini App AI	Deliberately in maintenance mode in this source branch; it does not call a provider or load Mini App AI history

Requirements

• PHP 8.1+ (CI covers 8.1, 8.2, and 8.3)
• HTTPS-enabled web server with PHP-FPM or equivalent
• PHP extensions: curl, openssl, json, and zip; mbstring is recommended
• proc_open permitted only for the guarded 7-Zip adapter, if .7z support is enabled
• A Telegram bot created through @BotFather
• A provider key configured through the owner-only interface when AI/photo reading is desired
• A supported 7-Zip CLI binary for .7z extraction; see bin/README.md

Quick start

git clone https://github.com/blazenxt/multi-tool-bot.git
cd multi-tool-bot
cp config.example.php config.php
cp unzipper/config.example.php unzipper/config.php  # only if enabling the optional legacy endpoint

1. Edit config.php with a new BotFather token, a long random server secret, your HTTPS Mini App URL, your bot username, and your own administrator IDs.
2. Keep config.php outside version control and deny direct web access at both the web-server and filesystem layers.
3. Install 7zz if you need .7z support. Do not download or commit an unverified binary.
4. Deploy the source under an HTTPS virtual host. Preserve the included access-control rules or recreate their equivalent for Nginx.
5. Configure the primary bot webhook and Mini App URLs through BotFather/Telegram using your own deployment URL.
6. Configure clones/cleanup.php as an hourly PHP CLI cron. Never expose or invoke it as an HTTP job.

Read the full deployment guide in docs/DEPLOYMENT.md.

Configuration

config.example.php documents every required value. Important values include:

• bot_token — primary BotFather token; never commit it.
• secret — stable random server secret used to protect encrypted local records.
• mini_app_url — exact HTTPS path to miniapp, for example https://example.com/path/to/miniapp.
• bot_username — your primary bot handle without @.
• admin_user_ids and platform_admin_id — your own Telegram numeric IDs; public source contains no administrator identity.

An empty allowed_chats array keeps the primary Mini Apps open to valid signed Telegram users. Add IDs only if you intend to restrict the installation.

Managed-clone model

Managed clones are intentionally not copies of the primary bot’s authority or data.

• Creators submit their own BotFather token only in a signed Telegram Mini App session over HTTPS.
• Clone tokens and provider keys are stored encrypted at rest and never returned through public APIs.
• Each clone uses its own webhook secret, rate state, 30-day history, temporary files, provider settings, and owner controls.
• The primary bot’s token, provider quota, admin identity, conversations, files, profile data, and host access are never inherited by clones.
• A clone starts without a provider key. AI Chat and photo reading stay unavailable until its owner configures an independent key.
• Platform moderation exposes only minimal public clone metadata and can suspend a clone fail-closed.

See docs/ARCHITECTURE.md for boundaries and component responsibilities.

Security posture

This project is designed for constrained hosted use, not unrestricted execution:

• sensitive forms are POST-only, HTTPS-only, and disabled until signed Telegram Web App data is present;
• direct helper files are denied by web-server rules;
• Mini App file/archive actions are authenticated and bounded by file size, entry count, storage, time, and rolling request limits;
• 7-Zip uses a fixed command shape and bounded process lifetime;
• Agent Mode uses reviewed fixed tools rather than arbitrary shell, filesystem, URL, or network execution;
• provider-backed AI does not offer image generation or editing;
• runtime state, credentials, uploaded files, and generated archives are excluded from Git.

No codebase is automatically secure in every hosting environment. Review the deployment guide and SECURITY.md before handling real user data.

Development checks

composer run lint
composer run secret-scan

The repository CI runs the same PHP syntax and credential-pattern checks on supported PHP versions. Add behavior tests for any feature or security-boundary change.

Contributing

Contributions are welcome. Please read CONTRIBUTING.md, keep changes scoped, and never attach credentials, production data, Telegram initData, chat histories, or user files to issues or pull requests.

License

Released under the MIT License.