@alfe.ai/openclaw-telegram 0.0.1

package/python/bridge.py

@@ -0,0 +1,633 @@
+#!/usr/bin/env python3
+"""Local Telethon bridge for @alfe.ai/openclaw-telegram.
+
+The process speaks bounded JSONL over stdin/stdout. Telegram credentials and
+session data are read only from the owner-only state directory supplied by the
+Node plugin. Never print the session, API hash, phone, code, or password.
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import getpass
+import json
+import os
+import re
+import sys
+import tempfile
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+
+STATE_VERSION = 1
+MAX_COMMAND_BYTES = 1024 * 1024
+MAX_PENDING = 2_000
+MAX_RECENT = 2_000
+MAX_DIALOG_SCAN = 5_000
+MAX_TEXT_CHARS = 32_000
+API_HASH_RE = re.compile(r"^[0-9a-fA-F]{32}$")
+SAFE_METHODS = {
+    "status",
+    "list_dialogs",
+    "list_subscriptions",
+    "subscribe",
+    "unsubscribe",
+    "ack",
+    "shutdown",
+}
+
+
+def emit(payload: dict[str, Any]) -> None:
+    sys.stdout.write(json.dumps(payload, separators=(",", ":"), ensure_ascii=False) + "\n")
+    sys.stdout.flush()
+
+
+def fatal(code: str) -> None:
+    emit({"type": "fatal", "code": code})
+
+
+def ensure_private_dir(path: Path) -> None:
+    path.mkdir(parents=True, exist_ok=True, mode=0o700)
+    try:
+        path.chmod(0o700)
+    except OSError:
+        pass
+
+
+def atomic_json(path: Path, value: dict[str, Any]) -> None:
+    ensure_private_dir(path.parent)
+    descriptor, temporary = tempfile.mkstemp(prefix=f".{path.name}.", dir=path.parent)
+    try:
+        os.fchmod(descriptor, 0o600)
+        with os.fdopen(descriptor, "w", encoding="utf-8") as handle:
+            json.dump(value, handle, ensure_ascii=False, separators=(",", ":"))
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(temporary, path)
+        try:
+            path.chmod(0o600)
+        except OSError:
+            pass
+    except Exception:
+        try:
+            os.unlink(temporary)
+        except OSError:
+            pass
+        raise
+
+
+def read_json(path: Path) -> dict[str, Any]:
+    with path.open("r", encoding="utf-8") as handle:
+        value = json.load(handle)
+    if not isinstance(value, dict):
+        raise ValueError("invalid_json_object")
+    return value
+
+
+def load_config(state_dir: Path) -> tuple[int, str]:
+    value = read_json(state_dir / "config.json")
+    api_id = value.get("api_id")
+    api_hash = value.get("api_hash")
+    if not isinstance(api_id, int) or api_id <= 0:
+        raise ValueError("invalid_config")
+    if not isinstance(api_hash, str) or API_HASH_RE.fullmatch(api_hash) is None:
+        raise ValueError("invalid_config")
+    return api_id, api_hash
+
+
+def default_state() -> dict[str, Any]:
+    return {
+        "version": STATE_VERSION,
+        "subscriptions": {},
+        "pending": [],
+        "recent": [],
+    }
+
+
+def valid_chat_kind(value: Any) -> bool:
+    return value in {"private", "group", "channel"}
+
+
+def valid_pending_item(item: Any) -> bool:
+    if not isinstance(item, dict):
+        return False
+    required_strings = (
+        "deliveryId",
+        "messageId",
+        "chatId",
+        "chatTitle",
+        "chatKind",
+        "senderId",
+        "senderName",
+        "text",
+        "timestamp",
+    )
+    if any(not isinstance(item.get(key), str) for key in required_strings):
+        return False
+    if not valid_chat_kind(item.get("chatKind")):
+        return False
+    text = item.get("text")
+    if not text or len(text) > MAX_TEXT_CHARS:
+        return False
+    username = item.get("senderUsername")
+    return username is None or isinstance(username, str)
+
+
+def load_state(path: Path) -> dict[str, Any]:
+    try:
+        value = read_json(path)
+    except FileNotFoundError:
+        return default_state()
+    if value.get("version") != STATE_VERSION:
+        raise ValueError("invalid_state")
+    subscriptions = value.get("subscriptions")
+    pending = value.get("pending")
+    recent = value.get("recent")
+    if not isinstance(subscriptions, dict) or not isinstance(pending, list) or not isinstance(recent, list):
+        raise ValueError("invalid_state")
+    for key, subscription in subscriptions.items():
+        if not isinstance(key, str) or not isinstance(subscription, dict):
+            raise ValueError("invalid_state")
+        if subscription.get("chat_id") != key or not isinstance(subscription.get("title"), str):
+            raise ValueError("invalid_state")
+        if not valid_chat_kind(subscription.get("kind")):
+            raise ValueError("invalid_state")
+    if len(pending) > MAX_PENDING or len(recent) > MAX_RECENT:
+        raise ValueError("invalid_state")
+    if any(not valid_pending_item(item) for item in pending):
+        raise ValueError("invalid_state")
+    if any(not isinstance(item, str) for item in recent):
+        raise ValueError("invalid_state")
+    return value
+
+
+def entity_kind(dialog: Any) -> str:
+    if bool(getattr(dialog, "is_user", False)):
+        return "private"
+    if bool(getattr(dialog, "is_channel", False)) and not bool(getattr(dialog, "is_group", False)):
+        return "channel"
+    return "group"
+
+
+def display_name(entity: Any, fallback: str) -> str:
+    first = getattr(entity, "first_name", None)
+    last = getattr(entity, "last_name", None)
+    title = " ".join(part for part in (first, last) if isinstance(part, str) and part.strip())
+    if title:
+        return title[:256]
+    name = getattr(entity, "title", None)
+    if isinstance(name, str) and name.strip():
+        return name[:256]
+    username = getattr(entity, "username", None)
+    if isinstance(username, str) and username.strip():
+        return username[:256]
+    return fallback[:256]
+
+
+def iso_timestamp(value: Any) -> str:
+    if isinstance(value, datetime):
+        if value.tzinfo is None:
+            value = value.replace(tzinfo=timezone.utc)
+        return value.astimezone(timezone.utc).isoformat().replace("+00:00", "Z")
+    return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+class Bridge:
+    def __init__(self, state_dir: Path, client: Any, me: Any) -> None:
+        self.state_dir = state_dir
+        self.state_path = state_dir / "state.json"
+        self.state = load_state(self.state_path)
+        self.client = client
+        self.me = me
+        self.shutting_down = False
+        self.enqueue_lock = asyncio.Lock()
+        self.queue_full_reported = False
+
+    def save(self) -> None:
+        atomic_json(self.state_path, self.state)
+
+    async def handle_message(self, event: Any) -> None:
+        if bool(getattr(event, "out", False)):
+            return
+        chat_id_raw = getattr(event, "chat_id", None)
+        if chat_id_raw is None:
+            return
+        chat_id = str(chat_id_raw)
+        subscription = self.state["subscriptions"].get(chat_id)
+        if not isinstance(subscription, dict):
+            return
+        raw_text = getattr(event, "raw_text", "")
+        if not isinstance(raw_text, str) or not raw_text.strip():
+            return
+        text = raw_text.strip()[:MAX_TEXT_CHARS]
+        message = getattr(event, "message", None)
+        message_id = str(getattr(message, "id", ""))
+        if not message_id:
+            return
+        delivery_id = f"{chat_id}:{message_id}"
+
+        try:
+            sender = await event.get_sender()
+        except Exception:
+            sender = None
+        sender_id = str(getattr(event, "sender_id", "unknown"))
+        sender_name = display_name(sender, sender_id) if sender is not None else sender_id
+        sender_username = getattr(sender, "username", None) if sender is not None else None
+        item: dict[str, Any] = {
+            "deliveryId": delivery_id,
+            "messageId": message_id,
+            "chatId": chat_id,
+            "chatTitle": str(subscription["title"])[:256],
+            "chatKind": str(subscription["kind"]),
+            "senderId": sender_id[:128],
+            "senderName": sender_name,
+            "text": text,
+            "timestamp": iso_timestamp(getattr(message, "date", None)),
+        }
+        if isinstance(sender_username, str) and sender_username:
+            item["senderUsername"] = sender_username[:128]
+        async with self.enqueue_lock:
+            pending = self.state["pending"]
+            if len(pending) >= MAX_PENDING:
+                if not self.queue_full_reported:
+                    emit({"type": "health", "code": "pending_queue_full"})
+                    self.queue_full_reported = True
+                return
+            if self.shutting_down:
+                return
+            self.queue_full_reported = False
+            if chat_id not in self.state["subscriptions"]:
+                return
+            recent = self.state["recent"]
+            if delivery_id in recent or any(entry.get("deliveryId") == delivery_id for entry in pending):
+                return
+            pending.append(item)
+            self.save()
+            emit({"type": "event", "event": item})
+
+    async def list_dialogs(self, params: dict[str, Any]) -> dict[str, Any]:
+        offset = bounded_int(params.get("offset"), 0, MAX_DIALOG_SCAN, 0)
+        limit = bounded_int(params.get("limit"), 1, 100, 50)
+        query_raw = params.get("query")
+        query = query_raw.strip().lower() if isinstance(query_raw, str) else ""
+        kinds_raw = params.get("kinds")
+        kinds = set(kinds_raw) if isinstance(kinds_raw, list) else set()
+        if any(not valid_chat_kind(kind) for kind in kinds):
+            raise ValueError("invalid_kinds")
+
+        matched = 0
+        scanned = 0
+        dialogs: list[dict[str, Any]] = []
+        async for dialog in self.client.iter_dialogs():
+            scanned += 1
+            if scanned > MAX_DIALOG_SCAN:
+                break
+            kind = entity_kind(dialog)
+            if kinds and kind not in kinds:
+                continue
+            title = str(getattr(dialog, "name", "") or display_name(dialog.entity, str(dialog.id)))[:256]
+            username = getattr(dialog.entity, "username", None)
+            haystack = f"{title} {username or ''}".lower()
+            if query and query not in haystack:
+                continue
+            if matched < offset:
+                matched += 1
+                continue
+            if len(dialogs) >= limit:
+                break
+            chat_id = str(dialog.id)
+            item: dict[str, Any] = {
+                "chatId": chat_id,
+                "title": title,
+                "kind": kind,
+                "subscribed": chat_id in self.state["subscriptions"],
+                "unreadCount": max(0, int(getattr(dialog, "unread_count", 0) or 0)),
+            }
+            if isinstance(username, str) and username:
+                item["username"] = username[:128]
+            dialogs.append(item)
+            matched += 1
+        return {
+            "dialogs": dialogs,
+            "nextOffset": offset + len(dialogs) if len(dialogs) == limit else None,
+            "scanBoundReached": scanned > MAX_DIALOG_SCAN,
+        }
+
+    async def subscribe(self, params: dict[str, Any]) -> dict[str, Any]:
+        chat_id = required_chat_id(params.get("chatId"))
+        found = None
+        scanned = 0
+        async for dialog in self.client.iter_dialogs():
+            scanned += 1
+            if scanned > MAX_DIALOG_SCAN:
+                break
+            if str(dialog.id) == chat_id:
+                found = dialog
+                break
+        if found is None:
+            raise ValueError("chat_not_found")
+        title = str(getattr(found, "name", "") or display_name(found.entity, chat_id))[:256]
+        username = getattr(found.entity, "username", None)
+        subscription: dict[str, Any] = {
+            "chat_id": chat_id,
+            "title": title,
+            "kind": entity_kind(found),
+        }
+        if isinstance(username, str) and username:
+            subscription["username"] = username[:128]
+        self.state["subscriptions"][chat_id] = subscription
+        self.save()
+        return public_subscription(subscription)
+
+    def unsubscribe(self, params: dict[str, Any]) -> dict[str, Any]:
+        chat_id = required_chat_id(params.get("chatId"))
+        removed = self.state["subscriptions"].pop(chat_id, None)
+        pending = self.state["pending"]
+        retained = [item for item in pending if item.get("chatId") != chat_id]
+        dropped = len(retained) != len(pending)
+        if dropped:
+            self.state["pending"] = retained
+        if removed is not None or dropped:
+            self.save()
+        return {"chatId": chat_id, "removed": removed is not None}
+
+    def list_subscriptions(self, params: dict[str, Any]) -> dict[str, Any]:
+        offset = bounded_int(params.get("offset"), 0, MAX_DIALOG_SCAN, 0)
+        limit = bounded_int(params.get("limit"), 1, 100, 50)
+        subscriptions = [public_subscription(item) for item in self.state["subscriptions"].values()]
+        subscriptions.sort(key=lambda item: (item["title"].lower(), item["chatId"]))
+        page = subscriptions[offset:offset + limit]
+        next_offset = offset + len(page) if offset + len(page) < len(subscriptions) else None
+        return {
+            "subscriptions": page,
+            "nextOffset": next_offset,
+            "total": len(subscriptions),
+        }
+
+    def ack(self, params: dict[str, Any]) -> dict[str, Any]:
+        delivery_id = params.get("deliveryId")
+        if not isinstance(delivery_id, str) or not delivery_id or len(delivery_id) > 256:
+            raise ValueError("invalid_delivery_id")
+        pending = self.state["pending"]
+        next_pending = [item for item in pending if item.get("deliveryId") != delivery_id]
+        removed = len(next_pending) != len(pending)
+        if removed:
+            self.state["pending"] = next_pending
+            recent = self.state["recent"]
+            recent.append(delivery_id)
+            self.state["recent"] = recent[-MAX_RECENT:]
+            self.save()
+        return {"deliveryId": delivery_id, "acknowledged": removed}
+
+    def status(self) -> dict[str, Any]:
+        username = getattr(self.me, "username", None)
+        result: dict[str, Any] = {
+            "authorized": True,
+            "displayName": display_name(self.me, "Telegram user"),
+            "subscriptionCount": len(self.state["subscriptions"]),
+            "pendingCount": len(self.state["pending"]),
+            "deliveryMode": "read_only",
+        }
+        if isinstance(username, str) and username:
+            result["username"] = username[:128]
+        return result
+
+    async def command(self, method: str, params: dict[str, Any]) -> Any:
+        if method == "status":
+            return self.status()
+        if method == "list_dialogs":
+            return await self.list_dialogs(params)
+        if method == "list_subscriptions":
+            return self.list_subscriptions(params)
+        if method == "subscribe":
+            return await self.subscribe(params)
+        if method == "unsubscribe":
+            return self.unsubscribe(params)
+        if method == "ack":
+            return self.ack(params)
+        if method == "shutdown":
+            self.shutting_down = True
+            return {"stopping": True}
+        raise ValueError("unsupported_method")
+
+
+def public_subscription(value: dict[str, Any]) -> dict[str, Any]:
+    result = {
+        "chatId": str(value["chat_id"]),
+        "title": str(value["title"]),
+        "kind": str(value["kind"]),
+    }
+    username = value.get("username")
+    if isinstance(username, str) and username:
+        result["username"] = username
+    return result
+
+
+def bounded_int(value: Any, minimum: int, maximum: int, default: int) -> int:
+    if value is None:
+        return default
+    if isinstance(value, bool) or not isinstance(value, int) or value < minimum or value > maximum:
+        raise ValueError("invalid_number")
+    return value
+
+
+def required_chat_id(value: Any) -> str:
+    if not isinstance(value, str) or not value or len(value) > 128:
+        raise ValueError("invalid_chat_id")
+    if re.fullmatch(r"-?[0-9]+", value) is None:
+        raise ValueError("invalid_chat_id")
+    return value
+
+
+async def login(state_dir: Path) -> int:
+    try:
+        from telethon import TelegramClient
+    except ImportError:
+        print("Telethon runtime is missing. Run through the alfe-telegram command.", file=sys.stderr)
+        return 2
+
+    ensure_private_dir(state_dir)
+    try:
+        api_id = int(input("Telegram API ID (from my.telegram.org): ").strip())
+    except ValueError:
+        print("Invalid API ID.", file=sys.stderr)
+        return 2
+    api_hash = getpass.getpass("Telegram API hash: ").strip()
+    if api_id <= 0 or API_HASH_RE.fullmatch(api_hash) is None:
+        print("Invalid API ID or hash.", file=sys.stderr)
+        return 2
+    phone = input("Telegram phone number (international format): ").strip()
+    if not phone or len(phone) > 32:
+        print("Invalid phone number.", file=sys.stderr)
+        return 2
+
+    session_base = state_dir / "user"
+    client = TelegramClient(str(session_base), api_id, api_hash)
+    try:
+        await client.start(
+            phone=phone,
+            code_callback=lambda: getpass.getpass("Telegram login code: ").strip(),
+            password=lambda: getpass.getpass("Telegram 2FA password (if requested): "),
+        )
+        me = await client.get_me()
+        if me is None:
+            raise RuntimeError("authorization_failed")
+        atomic_json(state_dir / "config.json", {
+            "version": STATE_VERSION,
+            "api_id": api_id,
+            "api_hash": api_hash,
+        })
+        session_file = state_dir / "user.session"
+        if session_file.exists():
+            try:
+                session_file.chmod(0o600)
+            except OSError:
+                pass
+        print(f"Telegram login complete for {display_name(me, 'Telegram user')}.")
+        print("The session is stored only on this machine.")
+        return 0
+    except Exception:
+        print("Telegram login failed. Check the code, 2FA password, and API credentials.", file=sys.stderr)
+        return 1
+    finally:
+        await client.disconnect()
+
+
+async def logout(state_dir: Path) -> int:
+    try:
+        from telethon import TelegramClient
+    except ImportError:
+        print("Telethon runtime is missing. Run through the alfe-telegram command.", file=sys.stderr)
+        return 2
+    try:
+        api_id, api_hash = load_config(state_dir)
+    except FileNotFoundError:
+        print("No local Telegram login is configured.")
+        return 0
+    except Exception:
+        print("The local Telegram configuration is invalid.", file=sys.stderr)
+        return 2
+
+    client = TelegramClient(str(state_dir / "user"), api_id, api_hash)
+    try:
+        await client.connect()
+        if await client.is_user_authorized() and not await client.log_out():
+            raise RuntimeError("logout_failed")
+        for name in ("config.json", "state.json", "user.session", "user.session-journal"):
+            try:
+                (state_dir / name).unlink()
+            except FileNotFoundError:
+                pass
+        print("Telegram device session revoked and local connection state removed.")
+        return 0
+    except Exception:
+        print(
+            "Telegram logout failed. Retry with network access or revoke the session from Telegram Devices.",
+            file=sys.stderr,
+        )
+        return 1
+    finally:
+        if client.is_connected():
+            await client.disconnect()
+
+
+async def run_bridge(state_dir: Path) -> int:
+    try:
+        from telethon import TelegramClient, events
+    except ImportError:
+        fatal("runtime_missing")
+        return 2
+    try:
+        api_id, api_hash = load_config(state_dir)
+    except FileNotFoundError:
+        fatal("not_configured")
+        return 2
+    except Exception:
+        fatal("invalid_config")
+        return 2
+
+    client = TelegramClient(str(state_dir / "user"), api_id, api_hash)
+    try:
+        await client.connect()
+        if not await client.is_user_authorized():
+            fatal("not_authorized")
+            return 2
+        me = await client.get_me()
+        if me is None:
+            fatal("not_authorized")
+            return 2
+        bridge = Bridge(state_dir, client, me)
+    except ValueError:
+        fatal("invalid_state")
+        await client.disconnect()
+        return 2
+    except Exception:
+        fatal("connect_failed")
+        await client.disconnect()
+        return 1
+
+    client.add_event_handler(bridge.handle_message, events.NewMessage(incoming=True))
+    emit({"type": "ready"})
+    for item in list(bridge.state["pending"]):
+        emit({"type": "event", "event": item})
+
+    try:
+        while not bridge.shutting_down:
+            raw = await asyncio.to_thread(sys.stdin.buffer.readline, MAX_COMMAND_BYTES + 1)
+            if not raw:
+                break
+            if len(raw) > MAX_COMMAND_BYTES or not raw.endswith(b"\n"):
+                fatal("command_too_large")
+                break
+            request_id: Any = None
+            try:
+                decoded = json.loads(raw.decode("utf-8"))
+                if not isinstance(decoded, dict):
+                    raise ValueError("invalid_request")
+                request_id = decoded.get("id")
+                method = decoded.get("method")
+                params = decoded.get("params", {})
+                if not isinstance(request_id, str) or len(request_id) > 128:
+                    raise ValueError("invalid_request")
+                if not isinstance(method, str) or method not in SAFE_METHODS:
+                    raise ValueError("unsupported_method")
+                if not isinstance(params, dict):
+                    raise ValueError("invalid_params")
+                result = await bridge.command(method, params)
+                emit({"type": "response", "id": request_id, "ok": True, "result": result})
+            except ValueError as error:
+                code = str(error)
+                if re.fullmatch(r"[a-z0-9_]{1,64}", code) is None:
+                    code = "invalid_request"
+                if isinstance(request_id, str):
+                    emit({"type": "response", "id": request_id, "ok": False, "code": code})
+            except Exception:
+                if isinstance(request_id, str):
+                    emit({"type": "response", "id": request_id, "ok": False, "code": "command_failed"})
+    finally:
+        await client.disconnect()
+    return 0
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(add_help=True)
+    parser.add_argument("command", choices=["login", "logout", "run"])
+    parser.add_argument("--state-dir", required=True)
+    return parser.parse_args()
+
+
+def main() -> int:
+    args = parse_args()
+    state_dir = Path(args.state_dir).expanduser().resolve()
+    ensure_private_dir(state_dir)
+    if args.command == "login":
+        return asyncio.run(login(state_dir))
+    if args.command == "logout":
+        return asyncio.run(logout(state_dir))
+    return asyncio.run(run_bridge(state_dir))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())