tgcaptcha-solver 0.1.0__py3-none-any.whl

tgcaptcha/__init__.py

@@ -0,0 +1,29 @@
+"""
+tgcaptcha — solve Telegram group-join captchas with pluggable solvers.
+
+Two halves:
+  • the BRAIN (pure): solvers, declarative rules and the engine that picks
+    one — runs in the solver service, and as a fallback on the node;
+  • the HANDS (on the account's host): a `Runner` loop that turns a
+    challenge into a `Session`, asks for a decision, runs every action
+    past the safety policy, performs it through the framework-agnostic
+    `Hands` protocol (8 async methods), and loops (observe → act) until
+    done. Any Telegram framework can be an adapter — Telethon ships in
+    `tgcaptcha.executor`, the Pyrogram family in `tgcaptcha.adapters`;
+    anything else: `examples/diy_adapter.py`.
+
+New solvers and rules ship to the service only; nodes never restart for
+them. See README.md and docs/ADAPTERS.md.
+"""
+
+__version__ = "0.1.0"
+
+from tgcaptcha.engine import Engine  # noqa: F401
+from tgcaptcha.hands import Hands, PartialHands  # noqa: F401
+from tgcaptcha.model import (  # noqa: F401
+    Account, Button, Click, Decision, Done, FetchBio, FetchImage, JoinChannel,
+    Message, OpenDM, Performed, SendText, Session, SetBio, SetLastName, Wait)
+from tgcaptcha.policy import PolicyConfig, check  # noqa: F401
+from tgcaptcha.rules import RuleSet  # noqa: F401
+from tgcaptcha.runner import Runner  # noqa: F401
+from tgcaptcha.solvers import Solver  # noqa: F401

tgcaptcha/adapters/__init__.py

@@ -0,0 +1,25 @@
+"""
+Framework adapters. Each submodule turns one client family into the three
+things tgcaptcha needs: a `to_message` wire converter, a `Hands`
+implementation, and a `mount()` that wires the whole feed.
+
+Imports are lazy: `import tgcaptcha.adapters` never requires any client
+framework — the attribute access pulls the submodule in, and the submodule
+itself imports the framework only where it is actually unavoidable
+(`mount`). `to_message` and `PyrogramHands` are plain getattr code, so
+they run (and are tested) with no framework installed.
+"""
+
+from __future__ import annotations
+
+_LAZY = ("to_message", "PyrogramHands", "mount")
+
+
+def __getattr__(name: str):
+    if name in _LAZY:
+        from tgcaptcha.adapters import pyrogram as _pyro
+        return getattr(_pyro, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+__all__ = list(_LAZY)

tgcaptcha/adapters/pyrogram.py

@@ -0,0 +1,508 @@
+"""
+The Pyrogram-family adapter: pyrogram, kurigram, pyrofork, hydrogram —
+one API, one adapter. Turn a client into Hands + a message feed, and let
+the shared Runner (`tgcaptcha.runner`) own the loop. Semantics mirror
+`TelethonHands` in `tgcaptcha.executor` one for one.
+
+    brain = Brain("http://solver:8090", token=...)     # or Brain() = local
+    handle = mount(app, brain=brain, account=Account(me.id, me.username))
+    ...
+    handle.stop()
+
+`mount` is the 3-line UX (detect challenges, run sessions, serialize per
+chat); `PyrogramHands` and `to_message` are for hosts that drive the
+Runner themselves.
+
+This module never imports the framework at import time: `to_message` and
+`PyrogramHands` are pure getattr code over whatever objects they are
+handed (that is also what the offline tests exercise), and `mount` pulls
+the installed family in lazily — the family's root module is derived
+from the client object (`type(app).__module__`), so hydrogram mounts
+through the same code as pyrogram, kurigram and pyrofork. Method-name
+differences inside the family are probed at call time:
+  • bio write: kurigram ≥2.2 also exposes `set_profile_info`; every
+    family member has `update_profile(bio=...)`.
+  • edited group messages: kurigram routes edits to
+    `EditedMessageHandler` (classic pyrogram delivers them to
+    `MessageHandler`), so `mount` registers the edit handler only when
+    the installed family ships one.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import importlib
+import logging
+import time
+import uuid
+from typing import Any, Awaitable, Callable, Dict, Optional
+
+from tgcaptcha import text as T
+from tgcaptcha.client import Brain
+from tgcaptcha.hands import PartialHands
+from tgcaptcha.model import (Account, Button, Click, Message, SendText, Session)
+from tgcaptcha.policy import PolicyConfig
+from tgcaptcha.runner import InboxItem, Runner
+
+log = logging.getLogger("tgcaptcha.adapters.pyrogram")
+
+DelayFn = Callable[[str], float]
+
+
+def _wire_text(pmsg) -> str:
+    """Plain family text with text-mention entities folded back in as
+    ``[name](tg://user?id=N)`` links — the shape the corpus and
+    ``T.addressed`` expect. Real family messages carry mention-by-id as
+    an ENTITY whose plain `.text` loses ("Jybfghhd, press …"), so the
+    names_account check would refuse every real challenge; fakes that
+    already embed the markup pass through untouched (no entities →
+    text as-is). Entity offsets are UTF-16 code units in the family,
+    not python characters."""
+    text = getattr(pmsg, "text", None) or ""
+    ents = getattr(pmsg, "entities", None) or []
+    if not text:
+        # Photo/video challenges carry their text as a CAPTION: the
+        # family splits it onto `.caption` / `.caption_entities`
+        # (Telethon's `.text` covers both; the family's does not).
+        text = getattr(pmsg, "caption", None) or ""
+        ents = getattr(pmsg, "caption_entities", None) or ents
+    if not ents or not text:
+        return text
+
+    def u16_to_py(off: int) -> int:
+        n = 0
+        for i, ch in enumerate(text):
+            if n >= off:
+                return i
+            n += 2 if ord(ch) > 0xFFFF else 1
+        return len(text)
+
+    parts, pos = [], 0
+    for e in ents:
+        if "TEXT_MENTION" not in str(getattr(e, "type", "")):
+            continue
+        # pyrogram flattens the mentioned user to `user_id`; hydrogram
+        # keeps a `user` object instead. Read both.
+        uid = getattr(e, "user_id", None)
+        if uid is None:
+            uid = getattr(getattr(e, "user", None), "id", None)
+        if uid is None:
+            continue
+        s, t = u16_to_py(getattr(e, "offset", 0)), \
+            u16_to_py(getattr(e, "offset", 0) + getattr(e, "length", 0))
+        if s < pos or t <= s:
+            continue
+        parts += [text[pos:s], f"[{text[s:t]}](tg://user?id={uid})"]
+        pos = t
+    parts.append(text[pos:])
+    return "".join(parts)
+
+
+def to_message(pmsg, *, where: str = "group") -> Message:
+    """A pyrogram-family message as the wire model sees it. No RPC.
+    Works on `Message` and `EditedMessage` alike — everything is read
+    through getattr, so a message missing a field degrades, not crashes."""
+    rows = []
+    markup = getattr(pmsg, "reply_markup", None)
+    for row in (getattr(markup, "inline_keyboard", None) or []):
+        out = []
+        for b in row:
+            url = getattr(b, "url", None)
+            data = getattr(b, "callback_data", None)
+            kind = "callback" if data is not None else ("url" if url else "other")
+            out.append(Button(text=getattr(b, "text", "") or "", kind=kind,
+                              url=(url or None) and str(url)[:300]))
+        rows.append(out)
+    sender = getattr(pmsg, "from_user", None)
+    date = getattr(pmsg, "date", None)
+    return Message(
+        msg_id=getattr(pmsg, "id", None),
+        text=_wire_text(pmsg),
+        buttons=rows,
+        where=where,
+        sender_id=getattr(sender, "id", None),
+        sender_username=getattr(sender, "username", None),
+        from_me=bool(getattr(pmsg, "outgoing", False)),
+        edited=bool(getattr(pmsg, "edit_date", None)),
+        has_photo=bool(getattr(pmsg, "photo", None)),
+        date=date.timestamp() if hasattr(date, "timestamp") else None,
+    )
+
+
+def _family_root(app=None) -> str:
+    """Root module of the installed pyrogram-family package, derived from
+    the client object when one is at hand: a hydrogram Client's class
+    lives in `hydrogram`, a pyrogram / kurigram / pyrofork one in
+    `pyrogram`. The whole family shares one API, so only this name
+    differs. An unknown root that does not ship a `.handlers` module
+    falls back to classic pyrogram."""
+    if app is not None:
+        root = type(app).__module__.split(".", 1)[0]
+        if root != "pyrogram":
+            try:
+                importlib.import_module(f"{root}.handlers")
+                return root
+            except ImportError:
+                pass
+    return "pyrogram"
+
+
+def _flood_wait_cls(client=None):
+    """The installed family's FloodWait error, or None without a family."""
+    try:
+        errors = importlib.import_module(f"{_family_root(client)}.errors")
+        return errors.FloodWait
+    except ImportError:
+        return None
+
+
+class PyrogramHands(PartialHands):
+    """The Hands protocol over a pyrogram-family client. Constructed by
+    `mount`; usable directly by hosts that drive the Runner themselves."""
+
+    def __init__(self, client, *, label: str = "?",
+                 join_fn: Optional[Callable[[str], Awaitable[bool]]] = None,
+                 set_last_name_fn: Optional[Callable[[str], Awaitable[bool]]] = None,
+                 delete_sent_after_s: float = 60.0,
+                 inbox: Optional["asyncio.Queue[InboxItem]"] = None,
+                 dm_mount: Optional[Callable[[Any, Callable], None]] = None):
+        self.client = client
+        self.label = label
+        self.join_fn = join_fn
+        self.set_last_name_fn = set_last_name_fn
+        self.delete_sent_after_s = delete_sent_after_s
+        self.inbox = inbox
+        self.dm_mount = dm_mount
+        self._dm_peer: Dict[str, Any] = {}
+        self._seen: Dict[tuple, Any] = {}   # (where, msg_id) -> pmsg
+        self._bg: set = set()
+
+    def remember(self, where: str, pmsg) -> None:
+        self._seen[(where, pmsg.id)] = pmsg
+
+    def _find(self, action: Click):
+        where = getattr(action, "where", None)
+        return (self._seen.get((where, action.msg_id)) if where else
+                self._seen.get(("group", action.msg_id)) or
+                self._seen.get(("dm", action.msg_id)))
+
+    async def click(self, action, session, on_alert=None) -> bool:
+        pmsg = self._find(action)
+        if pmsg is None:
+            return False
+        # Click by LABEL on a FRESH copy of the message: gate bots
+        # re-render keyboards (Rose's text2 badges reshuffle rows), so the
+        # cached snapshot's row/col can point at a different key.
+        try:
+            fresh = await self.client.get_messages(
+                getattr(getattr(pmsg, "chat", None), "id", None), message_ids=pmsg.id)
+            if fresh is not None:
+                self._seen[(getattr(action, "where", None) or "group", pmsg.id)] = fresh
+                pmsg = fresh
+        except Exception:
+            pass
+        if action.label:
+            try:
+                resp = await pmsg.click(action.label)
+            except Exception:
+                resp = await pmsg.click(action.row, action.col)
+        else:
+            resp = await pmsg.click(action.row, action.col)
+        if on_alert is not None:
+            a = getattr(resp, "message", None) if resp is not None else None
+            if a:
+                on_alert(a)
+        return True
+
+    async def send_text(self, action: SendText, session: Session) -> Optional[Message]:
+        if action.where == "dm":
+            peer = self._dm_peer.get("peer")
+            if peer is None:
+                return None
+            sent = await self.client.send_message(peer, action.text)
+            where = "dm"
+        else:
+            chat = getattr(self, "_chat", None)
+            if chat is None:
+                chat = session.chat_id
+            sent = await self.client.send_message(
+                chat, action.text, reply_to_message_id=session.challenge.msg_id)
+            where = "group"
+            self._delete_later(chat, getattr(sent, "id", None))
+        m = to_message(sent, where=where)
+        m.from_me = True
+        return m
+
+    async def fetch_image(self, msg: Message, session: Session) -> Optional[bytes]:
+        pmsg = self._seen.get((msg.where or "group", msg.msg_id)) or \
+            self._seen.get(("group", msg.msg_id)) or self._seen.get(("dm", msg.msg_id))
+        if pmsg is None:
+            return None
+        # A fetch is observation, not a gate-bot-facing action, so a short
+        # bounded retry is safe here (the "no retry loops" rule exists to
+        # keep the bot from being poked repeatedly). Slow routes make the
+        # family's download_media return None intermittently; the file_id
+        # path is a second, independent route to the same bytes.
+        targets = [pmsg]
+        photo = getattr(pmsg, "photo", None)
+        if photo is not None and getattr(photo, "file_id", None):
+            targets.append(photo.file_id)
+        for attempt in range(2):
+            for t in targets:
+                try:
+                    blob = await self.client.download_media(t, in_memory=True)
+                except Exception as e:
+                    log.warning(f"[{self.label}] image download error "
+                                f"(attempt {attempt + 1}): {e}")
+                    blob = None
+                if blob is None:
+                    continue
+                # The family's in-memory download hands back a BytesIO
+                # positioned at the END (live-proven on hydrogram):
+                # .read() there yields b"" while the bytes exist — read
+                # via getvalue() first, fall back to read() for exotic
+                # buffer shapes.
+                data = (blob.getvalue() if hasattr(blob, "getvalue")
+                        else blob.read() if hasattr(blob, "read") else bytes(blob))
+                if data:
+                    return data
+            if attempt == 0:
+                await asyncio.sleep(1.0)
+        return None
+
+    async def fetch_bio(self, session: Session) -> str:
+        me = await self.client.get_chat("me")
+        return getattr(me, "bio", None) or ""
+
+    async def set_bio(self, text: str, session: Session) -> bool:
+        try:
+            # kurigram ≥2.2 grew set_profile_info; the whole family keeps
+            # update_profile(bio=...). An empty string CLEARS the bio.
+            fn = getattr(self.client, "set_profile_info", None) or self.client.update_profile
+            await fn(bio=text or "")
+        except Exception as e:
+            # Telegram allows only a few bio edits per hour. Never
+            # wait-and-retry from inside a session: surface the wait and
+            # let the decision flow end it.
+            flood = _flood_wait_cls(self.client)
+            if flood is not None and isinstance(e, flood):
+                wait_s = getattr(e, "value", None)
+                log.warning(f"[{self.label}] bio edit rate-limited (flood wait {wait_s}s)")
+                return f"flood:{wait_s}"
+            raise
+        return True
+
+    async def open_dm(self, bot_username: str, start_param: str, session: Session) -> bool:
+        # The gate bot's own id arrived with its message, so it is reached
+        # by id — no ResolveUsername spent. A bot it merely links to costs
+        # one resolve, by username.
+        if bot_username.lower() == (session.gate_bot or "") and session.challenge.sender_id:
+            peer = session.challenge.sender_id
+        else:
+            peer = bot_username
+        if not self._dm_peer and self.dm_mount is not None:
+            self.dm_mount(peer, lambda m: self.inbox and self.inbox.put_nowait(
+                ("dm", to_message(m, where="dm"))))
+        self._dm_peer["peer"] = peer
+        cmd = "/start" + (f" {start_param}" if start_param else "")
+        await self.client.send_message(peer, cmd)
+        return True
+
+    async def join_channel(self, ref: str, session: Session) -> bool:
+        if self.join_fn is None:
+            return False
+        return bool(await self.join_fn(ref))
+
+    async def set_last_name(self, value: str, session: Session) -> bool:
+        if self.set_last_name_fn is None:
+            return False
+        return bool(await self.set_last_name_fn(value))
+
+    # ── internals ─────────────────────────────────────────────────────────
+    def set_chat(self, chat) -> None:
+        self._chat = chat
+
+    def _delete_later(self, chat, msg_id) -> None:
+        if not self.delete_sent_after_s or not msg_id:
+            return
+
+        async def _go():
+            try:
+                await asyncio.sleep(self.delete_sent_after_s)
+                await self.client.delete_messages(chat, [msg_id])
+            except asyncio.CancelledError:
+                raise
+            except Exception:
+                pass
+        try:
+            t = asyncio.get_running_loop().create_task(_go())
+            self._bg.add(t)
+            t.add_done_callback(self._bg.discard)
+        except RuntimeError:
+            pass
+
+
+class _Mounted:
+    """What `mount` returns: the feed is live until `stop()`."""
+
+    def __init__(self, app, *, account, brain, runner, join_fn, set_last_name_fn,
+                 delete_sent_after_s, label):
+        self.app = app
+        self.account = account
+        self.brain = brain
+        self.runner = runner
+        self.label = label
+        self._join_fn = join_fn
+        self._set_last_name_fn = set_last_name_fn
+        self._delete_sent_after_s = delete_sent_after_s
+        self._running: Dict[int, dict] = {}   # chat_id -> session record
+        self._handlers = []
+
+    # ── the feed ──────────────────────────────────────────────────────────
+    async def on_group(self, client, pmsg) -> None:
+        chat_id = getattr(getattr(pmsg, "chat", None), "id", None)
+        rec = self._running.get(chat_id)
+        if rec is not None:
+            gate_id = rec["gate_id"]
+            if getattr(pmsg, "from_user", None) is not None and \
+                    getattr(pmsg.from_user, "id", None) == gate_id:
+                rec["hands"].remember("group", pmsg)
+                rec["inbox"].put_nowait(("group", to_message(pmsg, where="group")))
+            return
+        if not self._looks_like_challenge(pmsg):
+            return
+        await self._start(client, pmsg, chat_id)
+
+    @staticmethod
+    def _looks_like_challenge(pmsg) -> bool:
+        """The same demo heuristic as examples/telethon_executor.py: an
+        incoming bot message carrying an inline keyboard. Whether it NAMES
+        this account is a separate fact (`names_account`) — the policy
+        refuses to act on a challenge that does not."""
+        sender = getattr(pmsg, "from_user", None)
+        # The family's User field is `is_bot` (a live hydrogram session
+        # exposes ONLY that — no `.bot`); `bot` is read too so hosts with
+        # their own user shapes keep working.
+        if sender is None or not (getattr(sender, "is_bot", False)
+                                  or getattr(sender, "bot", False)):
+            return False
+        markup = getattr(pmsg, "reply_markup", None)
+        return bool(getattr(markup, "inline_keyboard", None))
+
+    async def _start(self, client, pmsg, chat_id) -> None:
+        if chat_id in self._running:      # one session per chat at a time
+            return
+        if self.account is None:
+            # Lazy: only a real challenge spends the get_me() RPC.
+            me = await client.get_me()
+            self.account = Account(getattr(me, "id", None),
+                                   getattr(me, "username", None))
+        m = to_message(pmsg, where="group")
+        ids, names = T.addressed(m.text)
+        named = (self.account.id in ids or
+                 (self.account.username or "").lower() in names)
+        inbox: "asyncio.Queue[InboxItem]" = asyncio.Queue()
+        hands = PyrogramHands(client, label=self.label, join_fn=self._join_fn,
+                              set_last_name_fn=self._set_last_name_fn,
+                              delete_sent_after_s=self._delete_sent_after_s,
+                              inbox=inbox)
+        hands.set_chat(chat_id)
+        hands.remember("group", pmsg)
+        session = Session(
+            session_id=uuid.uuid4().hex,
+            account=self.account,
+            challenge=m,
+            chat_id=chat_id,
+            chat_title=getattr(getattr(pmsg, "chat", None), "title", None),
+            names_account=named)
+        rec = {"inbox": inbox, "hands": hands, "gate_id": m.sender_id, "task": None,
+               "dm_handlers": []}
+
+        def dm_mount(peer, push):
+            # Same pattern as executor.py: the DM handlers are per-session
+            # and come off with the session. Imports follow the family the
+            # mounted client actually belongs to (pyrogram / hydrogram).
+            root = _family_root(self.app)
+            filters = importlib.import_module(f"{root}.filters")
+            handlers_mod = importlib.import_module(f"{root}.handlers")
+            MessageHandler = handlers_mod.MessageHandler
+
+            async def _cb(_client, dmsg):
+                push(dmsg)
+
+            h = MessageHandler(_cb, filters.chat(peer) & filters.incoming & ~filters.me)
+            self.app.add_handler(h)
+            rec["dm_handlers"].append(h)
+
+        hands.dm_mount = dm_mount
+        self._running[chat_id] = rec
+        rec["task"] = asyncio.get_running_loop().create_task(self._run(session, hands,
+                                                                       inbox, chat_id, rec))
+
+    async def _run(self, session, hands, inbox, chat_id, rec) -> None:
+        try:
+            out = await self.runner.run(session, hands, inbox)
+            log.info(f"[{self.label}] chat {chat_id}: {out['result']} — {out['reason']}")
+        finally:
+            for h in rec["dm_handlers"]:
+                try:
+                    self.app.remove_handler(h)
+                except Exception:
+                    pass
+            self._running.pop(chat_id, None)
+
+    # ── lifecycle ─────────────────────────────────────────────────────────
+    def stop(self) -> None:
+        """Remove every handler mount added. Running sessions finish on
+        their own (the Runner's deadline bounds them)."""
+        for h in self._handlers:
+            try:
+                self.app.remove_handler(h)
+            except Exception:
+                pass
+        self._handlers = []
+
+
+def mount(app, *, account: Optional[Account] = None, brain: Optional[Brain] = None,
+          delay_fn: Optional[DelayFn] = None,
+          join_fn: Optional[Callable[[str], Awaitable[bool]]] = None,
+          set_last_name_fn: Optional[Callable[[str], Awaitable[bool]]] = None,
+          policy: Optional[PolicyConfig] = None,
+          observe_s: float = 8.0, quiet_s: float = 2.0,
+          session_deadline_s: float = 300.0, delete_sent_after_s: float = 60.0,
+          label: str = "?") -> _Mounted:
+    """The 3-line UX: watch the account's groups for captcha challenges
+    and run one session per chat through the shared Runner.
+
+    `account` may be left None — it is fetched via `app.get_me()` lazily,
+    when the first challenge actually appears. `delay_fn` None means no
+    human pause, exactly as in the Telethon executor. join_fn /
+    set_last_name_fn unset → those actions are refused, never improvised.
+    """
+    root = _family_root(app)
+    filters = importlib.import_module(f"{root}.filters")
+    handlers_mod = importlib.import_module(f"{root}.handlers")
+    MessageHandler = handlers_mod.MessageHandler
+
+    b = brain or Brain()      # one Brain: Brain() = the local Engine only
+    mounted = _Mounted(
+        app, account=account, brain=b,
+        runner=Runner(b, policy=policy or PolicyConfig(),
+                      delay_fn=delay_fn, observe_s=observe_s, quiet_s=quiet_s,
+                      session_deadline_s=session_deadline_s, label=label),
+        join_fn=join_fn, set_last_name_fn=set_last_name_fn,
+        delete_sent_after_s=delete_sent_after_s, label=label)
+
+    # New group messages; edits ride along in classic pyrogram. kurigram
+    # splits edits into EditedMessageHandler, so register it when the
+    # installed family ships one — the callback and filter are identical.
+    flt = filters.incoming & filters.group & ~filters.me
+    handlers = [MessageHandler(mounted.on_group, flt)]
+    try:
+        handlers.append(handlers_mod.EditedMessageHandler(mounted.on_group, flt))
+    except AttributeError:
+        pass
+    for h in handlers:
+        app.add_handler(h)
+        mounted._handlers.append(h)
+    return mounted