tgcaptcha-solver 0.1.0__tar.gz

tgcaptcha_solver-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 drshta0
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tgcaptcha_solver-0.1.0/PKG-INFO

@@ -0,0 +1,387 @@
+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)