Initial commit: Hermes skill xmpp-server-prosody

references/slidge-registration-and-avatar-gap.md

@@ -0,0 +1,78 @@
+# Slidgram (XMPP↔TG bridge): registration flow & avatar HTTP gap
+
+Companion to `slidge-telegram-bridge-nixg.md` (full bridge setup + SOCKS5).
+These are the two remaining user-facing/known-weak items, validated against
+slidgram 0.4.2.dev0 code inside the `icq-slidgram` container (2026-08-29)
+and the offline docs copy at `/opt/icq/docs/slidgram/`.
+
+## 1. Registration of a Telegram account through the bridge
+
+Two ways (per slidgram docs `user/registration.rst`); both target the component
+JID `telegram.nixg.ru` (no @, no local part):
+
+- **Method A — adhoc "Register" command** (Gajim / Movim / Cheogram / Converse
+  info card → Commands): opens a form.
+- **Method B — text message**: send `register` to `telegram.nixg.ru`; bridge
+  replies with the same form.
+
+Form fields (from `slidgram/gateway.py:validate`):
+- `phone` — international format, e.g. `+7...` (validated by `is_valid_phone_number`).
+- `api_id`, `api_hash` — user-provided from https://my.telegram.org/apps
+  (my.telegram.org is plain HTTP, reachable from RF in a normal browser — only
+  MTProto/telegram-asset traffic needs the tunnel). If the server env has
+  `API_ID`/`API_HASH` preset (slidgram/config.py), the form omits these fields.
+
+Flow under the hood:
+1. `Client.connect()` — if the session is already logged in, aborts early.
+2. `send_code(phone)` → stores `phone_code_hash`; user gets an SMS/code on
+   other TG clients. Timeout to enter it: `REGISTRATION_AUTH_CODE_TIMEOUT`
+   (default 60 s, config.py).
+3. `sign_in(phone, code_hash, code)`; if the account has 2FA, catches
+   `SessionPasswordNeeded` and asks for the password (`check_password`).
+
+After success: contacts appear in the XMPP roster as puppet JIDs
+`123456789@telegram.nixg.ru`; Telegram messages mirror into the XMPP dialog.
+All registration traffic runs over Pyrogram MTProto → `SLIDGRAM_PROXY` (SOCKS5) →
+works from RF. Check `docker logs icq-slidgram` for register/login/avatar/error.
+
+Constraints / gotchas:
+- **One phone number per server**: re-registering the same number →
+  "Someone is already using this phone number on this server".
+- 2FA password required if enabled; code entry is time-limited.
+- Converse web: adhoc command lives in the contact's info card; if the roster
+  isn't visible yet, the gateway JID can be added as a manual contact.
+
+## 2. Avatar download timeout — root cause (confirmed in code)
+
+Symptom: avatars/logo (e.g. `https://web.telegram.org/img/logo_share.png`) time
+out from RF; messaging is unaffected.
+
+- `slidge/core/gateway.py:399` creates `self.http = aiohttp.ClientSession()`
+  with **no proxy**; `slidge/db/avatar.py:112` (`self.http.get(url)`) downloads
+  URL-based avatars directly → blocked in RF.
+- MTProto side IS proxied: `slidgram/gateway.py:validate()` passes
+  `proxy=_proxy` (built from `SLIDGRAM_PROXY`) to the Pyrogram `Client`.
+- Contact photo avatars use Pyrogram `download_media()` via
+  `slidgram/telegram.py:download_avatar` (`AVATAR_DOWNLOAD_SLEEP=15` between
+  downloads) — proxied and working. The HTTP gap only hits URL-based avatars and
+  the component logo.
+
+Fix options (pick one when implementing):
+1. `aiohttp.ClientSession(trust_env=True)` + env `HTTP_PROXY/HTTPS_PROXY/ALL_PROXY`.
+   ⚠️ aiohttp supports SOCKS5 only through the extra `aiohttp-socks` package; a
+   plain HTTP proxy env var works if that proxy is RF-reachable (or points at
+   the tunnel's HTTP side).
+2. nginx reverse-proxy on bigbox rewriting `web.telegram.org` asset URLs through
+   the tunnel — no code changes in the container.
+3. Where the avatar is a Telegram file_id, rely on Pyrogram `download_media()`
+   (already proxied) and only proxy the remaining external URLs.
+
+## 3. Useful container paths (diagnostics)
+
+- `slidgram/telegram.py` — `Client(TelegramClient)` subclass, `download_avatar`,
+  `handle_flood` decorator around MTProto calls.
+- `slidgram/gateway.py` — `validate()` / `validate_two_factor_code()` registration.
+- `slidgram/config.py` — `API_ID`, `API_HASH`, `REGISTRATION_AUTH_CODE_TIMEOUT`,
+  `GROUP_HISTORY_MAXIMUM_MESSAGES`, `BIG_AVATARS`.
+- `slidge/core/gateway.py` — `__set_http()` at :399 (unproxied aiohttp session).
+- `slidge/db/avatar.py` — `CachedAvatar.__download` / `url_modified` (HTTP HEAD/GET).