Metadata-Version: 2.4
Name: tgcaptcha-solver
Version: 0.1.0
Summary: Telegram captcha solver for Rose, GroupHelp, Shieldy and SOSO group-join bots, with a strict safety policy.
Author: drshta0
License: MIT
Project-URL: Homepage, https://github.com/drshta0/tgcaptcha-solver
Project-URL: Repository, https://github.com/drshta0/tgcaptcha-solver
Project-URL: Issues, https://github.com/drshta0/tgcaptcha-solver/issues
Project-URL: Changelog, https://github.com/drshta0/tgcaptcha-solver/blob/main/CHANGELOG.md
Project-URL: Documentation, https://github.com/drshta0/tgcaptcha-solver/blob/main/docs/USAGE.md
Keywords: telegram,captcha,captcha-solver,telegram-captcha,telethon,userbot,missrose,rose-bot,grouphelp,shieldy,ocr,automation
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Communications :: Chat
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: client
Requires-Dist: aiohttp>=3.9; extra == "client"
Provides-Extra: executor
Requires-Dist: telethon>=1.36; extra == "executor"
Requires-Dist: aiohttp>=3.9; extra == "executor"
Provides-Extra: kurigram
Requires-Dist: kurigram>=2.0; extra == "kurigram"
Requires-Dist: aiohttp>=3.9; extra == "kurigram"
Provides-Extra: telethon
Requires-Dist: telethon>=1.36; extra == "telethon"
Requires-Dist: aiohttp>=3.9; extra == "telethon"
Provides-Extra: hydrogram
Requires-Dist: hydrogram>=0.2; extra == "hydrogram"
Requires-Dist: aiohttp>=3.9; extra == "hydrogram"
Provides-Extra: tdlib
Requires-Dist: aiotdlib<0.28,>=0.27.6; extra == "tdlib"
Requires-Dist: aiohttp>=3.9; extra == "tdlib"
Provides-Extra: server
Requires-Dist: fastapi>=0.110; extra == "server"
Requires-Dist: uvicorn>=0.29; extra == "server"
Requires-Dist: PyYAML>=6.0; extra == "server"
Requires-Dist: Pillow>=10.0; extra == "server"
Provides-Extra: ocr
Requires-Dist: ddddocr>=1.4; extra == "ocr"
Provides-Extra: test
Requires-Dist: aiohttp>=3.9; extra == "test"
Requires-Dist: fastapi>=0.110; extra == "test"
Requires-Dist: uvicorn>=0.29; extra == "test"
Requires-Dist: PyYAML>=6.0; extra == "test"
Requires-Dist: Pillow>=10.0; extra == "test"
Provides-Extra: all
Requires-Dist: aiohttp>=3.9; extra == "all"
Requires-Dist: telethon>=1.36; extra == "all"
Requires-Dist: fastapi>=0.110; extra == "all"
Requires-Dist: uvicorn>=0.29; extra == "all"
Requires-Dist: PyYAML>=6.0; extra == "all"
Requires-Dist: Pillow>=10.0; extra == "all"
Dynamic: license-file

<p align="center">
  <img src="https://raw.githubusercontent.com/drshta0/tgcaptcha-solver/main/docs/media/banner.svg" width="100%" alt="tgcaptcha: open-source Telegram captcha solver for Rose, GroupHelp, Shieldy and SOSO" />
</p>

<p align="center">
  <a href="#install"><img src="https://img.shields.io/badge/python-3.10%2B-2aabee?style=flat-square" alt="Python 3.10+" /></a>
  <a href="#install"><img src="https://img.shields.io/badge/core%20deps-0-3fb950?style=flat-square" alt="Zero core dependencies" /></a>
  <a href="#tests"><img src="https://img.shields.io/badge/tests-384%20offline-3fb950?style=flat-square" alt="384 offline checks" /></a>
  <a href="https://github.com/drshta0/tgcaptcha-solver/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-8b949e?style=flat-square" alt="MIT" /></a>
</p>

<p align="center">
  <a href="#install">Install</a> &nbsp;·&nbsp;
  <a href="#quickstart">Quickstart</a> &nbsp;·&nbsp;
  <a href="#works-with">Works with</a> &nbsp;·&nbsp;
  <a href="#all-solvers">Solvers</a> &nbsp;·&nbsp;
  <a href="#safety">Safety</a> &nbsp;·&nbsp;
  <a href="https://github.com/drshta0/tgcaptcha-solver/blob/main/docs/USAGE.md">Docs</a> &nbsp;·&nbsp;
  <a href="https://github.com/drshta0/tgcaptcha-solver/blob/main/CONTRIBUTING.md">Contributing</a>
</p>

<br />

**tgcaptcha** is an open-source Telegram captcha solver. When your account
joins a group, bots like **Rose**, **GroupHelp**, **Shieldy** and **SOSO 守门**
post a captcha: press a button, solve a sum, read a picture. tgcaptcha reads
it, works out the answer, checks the action against a strict safety policy,
and replies after a human-length pause. It runs on any Telegram client
framework: adapters ship for Telethon, the Pyrogram family (pyrogram,
kurigram, pyrofork, hydrogram) and TDLib hosts via aiotdlib, and any
other framework needs about 60 lines — see
[docs/ADAPTERS.md](https://github.com/drshta0/tgcaptcha-solver/blob/main/docs/ADAPTERS.md).

<p align="center">
  <img src="https://raw.githubusercontent.com/drshta0/tgcaptcha-solver/main/docs/media/demo.svg" width="100%" alt="Animated demo: tgcaptcha solves GroupHelp, SOSO and Rose captchas, then refuses to click a scam wallet gate" />
</p>

## Works with

Replayed against 30 days of real challenges from each bot. "Handled" counts
solved challenges plus Rose welcome walls that are correctly skipped.

| Bot | What it asks | Handled | Real-account test |
|:--|:--|--:|:--|
| **Rose** `@MissRose_bot` | sum, word or letters in a distorted image, sent in DM | **99.8%** of 4,456 | ✅ all captcha modes |
| **GroupHelp** `@GroupHelpBot` | press "I'm not a bot" / "Unmute me" | **94.8%** of 2,525 | ✅ 3 of 3 passed |
| **Shieldy** `@shieldy_bot` | type the answer to a sum, or digits from an image | **97.3%** of 2,019 | |
| **SOSO 守门** and relatives | pick the answer to `6 + 5 = ?` | **99.6%** of 1,808 | |
| **Bio guards** `@group_protection_pro_bot` | remove the link from your bio, press Recheck | **100%** of 1,863 | ✅ end to end |
| **GroupHelp clones** (ghclone2 to 5, im_grouphelp) | same as GroupHelp | 80 to 100% | |
| **Rose clones** (missrose2, rose_rosebot) | same as Rose | 97 to 99.5% | |

The busiest gate bots in the data (nnai8688, nmnmfun, coolestbot) are all
above 99.5%. New clones usually work without changes, because solvers match
the shape of a challenge rather than the bot's name.

## Results

Measured by replaying 30 days of real traffic (167,198 challenges from 1,502
gate bots) through the same engine that runs live. No network needed.

| Outcome | Share | Challenges | Notes |
|:--|--:|--:|:--|
| Solved | **86.9%** | 145,252 | 15 built-in solvers |
| Ignored on purpose | 9.5% | 15,847 | scam buttons and welcome walls, never clicked |
| Unsolved | 3.6% | 6,099 | video or sticker captchas, images that were never captured |

Answer timing matters. A correct answer about 2 s after the challenge still got
accounts kicked. Waiting 8 to 22 s turned most of those kicks into passes.

## Install

Python 3.10 or newer. The distribution is `tgcaptcha-solver`; the import is
still `tgcaptcha`. The core (engine, rules, solvers, policy, replay) uses only
the standard library. Each side installs its own extras:

```bash
pip install -e ".[kurigram]"     # Pyrogram-family accounts (kurigram / pyrofork)
pip install -e ".[hydrogram]"    # hydrogram accounts (auto-detected family)
pip install -e ".[tdlib]"        # TDLib hosts via aiotdlib (Linux/macOS-arm wheels)
pip install -e ".[telethon]"     # Telethon accounts
pip install -e ".[server]"       # solver service: fastapi, uvicorn, yaml, pillow
pip install -e ".[client]"       # talk to the service from the account host: aiohttp
pip install -e ".[executor]"     # Telethon-side executor: telethon, aiohttp
pip install ddddocr              # optional OCR for the image solvers
```

`image_buttons` uses the `tesseract` binary. `rose_dm`, `image_text_pick` and
`image_digits_typed` use `ddddocr`. A solver skips itself when its OCR reader
is missing, so both are optional.

## 60-second setup (one account, no server)

The engine runs locally on your own machine — nothing to host, no token, no
config file. Mount it on your client and it watches every group you are in
for a captcha challenge that names you, solves it, and touches nothing else.

**Pyrogram family** (pyrogram, kurigram, pyrofork, hydrogram):

```python
from pyrogram import Client
from tgcaptcha.adapters import mount

app = Client("myaccount")
mount(app)
app.run()
```

**Telethon:**

```python
from telethon import TelegramClient
from tgcaptcha.executor import mount_telethon

client = TelegramClient("myaccount", api_id, api_hash)
mount_telethon(client)
await client.start()
```

**TDLib (aiotdlib):**

```python
from aiotdlib import Client
from tgcaptcha.adapters.tdlib import mount as mount_tdlib

client = Client(api_id, api_hash, database_encryption_key="...")
mount_tdlib(client)
await client.idle()
```

Linux and macOS-arm64 wheels bundle libtdjson (nothing to compile);
elsewhere TDLib must be built first. Upstream aiotdlib is frozen at
TDLib 1.8.46 — see [docs/ADAPTERS.md](https://github.com/drshta0/tgcaptcha-solver/blob/main/docs/ADAPTERS.md) for the
caveats, including the URL-button lane degradation.

**Any other framework:** implement nine async methods (click, send text,
send a sticker, fetch an image, read/write your bio, open a bot DM, join
a channel, set a last name) and feed them to the shared loop — template in
[`examples/diy_adapter.py`](https://github.com/drshta0/tgcaptcha-solver/blob/main/examples/diy_adapter.py), contract in
[docs/ADAPTERS.md](https://github.com/drshta0/tgcaptcha-solver/blob/main/docs/ADAPTERS.md). The safety policy runs inside the
loop on every action, so no adapter can click a trap button.

**Node.js (gramjs):** the same loop, policy and wire model ship as
TypeScript in [`node/`](https://github.com/drshta0/tgcaptcha-solver/blob/main/node/) — `npm i` there, then
`mount(client)` from `tgcaptcha-node`. The brain talks to your solver
service over the same `/v1/decide` protocol; the safety policy runs
in-process on the Node host, exactly as in Python. Parity with the
Python engine is pinned by golden vectors (1,888 policy verdicts, 12
runner transcripts, zero diffs) — see [`node/README.md`](https://github.com/drshta0/tgcaptcha-solver/blob/main/node/README.md).

Optional: pass `delay_fn` for a human-length pause before answering
(answering in ~2 s gets correct answers kicked), or host callbacks for
joins and last-name edits. Running several accounts is when the
optional solver service starts to pay off — see below.

## Quickstart

```python
from tgcaptcha import Account, Button, Engine, Message, Session

s = Session(
    session_id="demo",
    account=Account(123, "me", first_name="Alex"),
    challenge=Message(
        msg_id=1,
        text="Alex, **press the button** below within 1 Minute 👇🏻",
        buttons=[[Button("CLICK 👉🏻 I'm NOT a BOT 🤖")]],
        sender_id=42, sender_username="grouphelpbot",
    ),
    chat_title="Some Group",
    names_account=True,  # the challenge mentions this account
)

d = Engine().decide(s)
print(d.solver)   # verify_button
print(d.actions)  # [Click(label="CLICK 👉🏻 I'm NOT a BOT 🤖")]
```

That runs locally with no service and no config. The full setup (service,
executor, Telethon) is in [docs/USAGE.md](https://github.com/drshta0/tgcaptcha-solver/blob/main/docs/USAGE.md).

## All solvers

| Solver | Gate bots | Challenge | Tested |
|:--|:--|:--|:--|
| `math_buttons` | SOSO 守门 and relatives (64% of traffic), nmnmfun | `6 + 5 = ?` with answer buttons | unit, replay |
| `verify_button` | GroupHelp and 5 clones, Shieldy, long tail | one "I'm not a bot" button, 10 languages | unit, replay, live |
| `math_typed` | Shieldy, filesreply | `(10 + 1)`, type the answer | unit, replay, live |
| `rose_dm` | MissRose | image or text challenge in DM, OCR | unit, replay, live |
| `image_text_pick` | clean3robot family | sum in an image, pick the matching button | unit, live |
| `image_digits_typed` | MissRose typed, long tail | digits in an image, type them | unit, replay |
| `image_buttons` | misc image gates | image plus buttons (tesseract) | unit, replay |
| `bio_guard` | @group_protection_pro_bot | link in bio: clear, Recheck, restore | unit, replay, live |
| `profile_requirement` | profile-gate bots | set a last name, then unmute | unit, replay |
| `join_required` | join-gate bots | join the named channel, then verify | unit, replay |
| `qa_buttons` | Customize_Captcha_Bot, quiz gates | fixed question, pick the answer | unit, replay |
| `emoji_pick` | emigrants360 and similar | "click the button with 🍏" | unit, replay |
| `say_anything` | "write any message" gates | send a short plain message | unit, replay |
| `dm_flow` | deep-link verifiers | follow the link into the bot's DM | unit, replay |
| `rose_welcome_wall` | MissRose | welcome walls, ignored on purpose | unit, replay |

Each file in `tgcaptcha/solvers/` lists the gate bots it was built from.

## Safety

Every action a solver proposes goes through the policy on the account's own
machine before anything happens. No solver is trusted, local or remote.

- **No trap buttons.** Kick, ban, casino and wallet labels are blocked, and that
  check runs before any allow rule.
- **Only its own challenge.** It answers only challenges that mention this account.
- **Short plain text only.** No links, no mentions, no line breaks.
- **DMs only to the gate bot**, or to a bot the gate bot links to.
- **Joins only the channel the gate bot named.**
- **Profile edits only for bio-guard:** clear the bio once, then restore exactly
  what was there.
- **Bounded.** Steps and actions are capped. After that it gives up.

## How it works

```
 account host (Telethon)                     solver service
┌───────────────────────────────┐ session   ┌──────────────────────┐
│ Executor   observe, act       │ ────────▶ │ Engine               │
│ Policy     checks each action │ ◀──────── │   rules (YAML)       │
│ Engine     local fallback     │ decision  │   solvers (plugins)  │
└───────────────────────────────┘           └──────────────────────┘
```

- **Executor** (`executor.py`) turns a challenge into a `Session`, asks for a
  `Decision`, runs each allowed action, then watches the gate bot for a few
  seconds and repeats until done.
- **Policy** (`policy.py`) runs on the account's host and decides what is allowed.
- **Engine** (`engine.py`) tries rules first, then solvers, in order. It runs on
  the service and also on the host as a fallback, so solving continues if the
  service is down.

The executor can only do a fixed set of things (`model.py`): click, send text,
fetch image, fetch bio, open DM, join channel, set last name, set bio, wait,
done. New gate bots are handled by adding a rule or a solver.

## Adding a gate bot

Most bots need only a rule. The service reloads the rules file when it changes.
See [`rules.example.yaml`](https://github.com/drshta0/tgcaptcha-solver/blob/main/rules.example.yaml).

```yaml
- id: owlto-join
  match: {bots: [Owlto_BOT]}
  do: {click_label: "click\\s+to\\s+join"}

- id: filesreply
  match: {bots: [filesreply_bot], text: "直接发送答案"}
  do: {solver: math_typed}

- id: not-a-captcha
  match: {bots: [fun_message_scoring_bot]}
  do: {ignore: "quiz results"}
```

For harder cases (images, multi-step DM flows), write a solver: subclass
`tgcaptcha.solvers.Solver`, implement `decide(session)`, and put the file in the
service's `--plugins` folder (then `POST /v1/reload`). You can also publish it
under the `tgcaptcha.solvers` entry point. See
[`examples/custom_solver.py`](https://github.com/drshta0/tgcaptcha-solver/blob/main/examples/custom_solver.py).

## Testing a change on real traffic

```bash
python -m tgcaptcha.replay corpus.jsonl --rules new_rules.yaml --compare-to rules.yaml
```

This replays a stored corpus (JSON lines of sessions, or flat
`{bot, text, buttons, mode}` rows) and prints coverage per solver and per bot,
the most common challenges nothing answers, and every decision that changed
compared to the baseline. A change ships only if nothing that was solved
before stops being solved.

## Running the service

```bash
TGCAPTCHA_TOKEN=... python -m tgcaptcha.server --port 8090 \
    --rules rules.yaml --plugins plugins/ --report reports.jsonl
```

Endpoints: `GET /v1/health`, `POST /v1/decide`, `POST /v1/report`,
`POST /v1/reload`, all behind a Bearer token. The service keeps no state; the
host sends the whole session on every step.

On the account's host:

```python
from tgcaptcha import Account
from tgcaptcha.client import Brain
from tgcaptcha.executor import Executor

brain = Brain("http://solver:8090", token="...")  # Brain() runs locally only
ex = Executor(client, brain, account=Account(me.id, me.username),
              delay_fn=lambda text: random.uniform(8, 22))  # human pause
result = await ex.run(chat, challenge_msg, names_account=True)
```

## Tests

```bash
python -m tgcaptcha.tests.test_core
python -m tgcaptcha.tests.test_bio
python -m tgcaptcha.tests.test_image_digits
python -m tgcaptcha.tests.test_image_pick
```

384 checks, all offline. CI runs them on Python 3.10 and 3.12, along with an
import check that keeps the package standalone.

## Responsible use

For education and research. Automating Telegram accounts may break Telegram's
Terms of Service, and you are responsible for your own accounts. Don't use it
to spam, scrape, or abuse any platform. The policy never clicks casino, wallet
or ad buttons, and that won't change.

## License

[MIT](https://github.com/drshta0/tgcaptcha-solver/blob/main/LICENSE)
