tunnelmate-cli 1.0.0__py3-none-any.whl

tunnelmate/bot/telegram_bot.py

@@ -0,0 +1,767 @@
+"""Telegram Bot management interface for TunnelMate."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+import sys
+from typing import Optional
+import telegram.error
+from telegram.request import HTTPXRequest
+from telegram import (
+    InlineKeyboardButton,
+    InlineKeyboardMarkup,
+    Update,
+)
+from telegram.constants import ParseMode
+from telegram.ext import (
+    Application,
+    ApplicationBuilder,
+    CallbackQueryHandler,
+    CommandHandler,
+    ContextTypes,
+    MessageHandler,
+    filters,
+)
+
+from tunnelmate.client.ipc_client import TunnelMateClient
+from tunnelmate.config import Settings, load_settings
+from tunnelmate.core.models import HealthStatus, Tunnel, TunnelProtocol, TunnelStatus
+from tunnelmate.daemon.protocol import IPCRequest, IPCResponse
+from tunnelmate.db.repository import Repository
+from tunnelmate.exceptions import DaemonConnectionError, TunnelMateError
+
+logger = logging.getLogger("tunnelmate.bot")
+
+
+class TunnelMateBot:
+    """Telegram Bot Controller providing menu-based remote tunnel management."""
+
+    def __init__(self, settings: Optional[Settings] = None):
+        self.settings = settings or load_settings()
+        self.repo = Repository(self.settings.resolved_db_path)
+        self.client = TunnelMateClient(self.settings)
+        self.app: Optional[Application] = None
+        self._background_tasks: list[asyncio.Task] = []
+
+    def is_admin(self, user_id: int) -> bool:
+        """Check if user has administrative rights."""
+        if user_id in self.settings.admin_chat_ids:
+            return True
+        sub = self.repo.get_subscriber(user_id)
+        return bool(sub and sub.is_admin and sub.is_authenticated)
+
+    # --- UI Keyboards ---
+
+    def _main_menu_keyboard(self, user_id: int) -> InlineKeyboardMarkup:
+        is_adm = self.is_admin(user_id)
+        keyboard = [
+            [
+                InlineKeyboardButton("📋 Tunnels List", callback_data="menu:list"),
+                InlineKeyboardButton("🔄 Refresh", callback_data="menu:refresh"),
+            ]
+        ]
+        if is_adm:
+            keyboard.append([
+                InlineKeyboardButton("➕ Create Tunnel", callback_data="menu:create_hint"),
+                InlineKeyboardButton("📊 Daemon Stats", callback_data="menu:stats"),
+            ])
+        keyboard.append([
+            InlineKeyboardButton("🔔 Notifications", callback_data="menu:notify_settings"),
+            InlineKeyboardButton("❓ Help", callback_data="menu:help"),
+        ])
+        return InlineKeyboardMarkup(keyboard)
+
+    def _tunnels_list_keyboard(self, tunnels: list[Tunnel]) -> InlineKeyboardMarkup:
+        keyboard = []
+        for t in tunnels:
+            icon = "🟢" if t.status == TunnelStatus.RUNNING else "🔴"
+            btn_text = f"{icon} {t.name} (:{t.target_port})"
+            keyboard.append([InlineKeyboardButton(btn_text, callback_data=f"tun:{t.id}")])
+
+        keyboard.append([
+            InlineKeyboardButton("🔄 Refresh", callback_data="menu:list"),
+            InlineKeyboardButton("🔙 Back to Main Menu", callback_data="menu:main"),
+        ])
+        return InlineKeyboardMarkup(keyboard)
+
+    def _tunnel_action_keyboard(self, tunnel: Tunnel, is_adm: bool) -> InlineKeyboardMarkup:
+        keyboard = []
+
+        if is_adm:
+            if tunnel.status == TunnelStatus.RUNNING:
+                keyboard.append([
+                    InlineKeyboardButton("⏹️ Stop", callback_data=f"act:stop:{tunnel.id}"),
+                    InlineKeyboardButton("🔄 Restart", callback_data=f"act:restart:{tunnel.id}"),
+                ])
+            else:
+                keyboard.append([
+                    InlineKeyboardButton("▶️ Start", callback_data=f"act:start:{tunnel.id}"),
+                ])
+
+        row_link = [InlineKeyboardButton("🔗 Latest Link", callback_data=f"act:link:{tunnel.id}")]
+        if tunnel.current_url and tunnel.status == TunnelStatus.RUNNING:
+            row_link.append(InlineKeyboardButton("🌐 Open", url=tunnel.current_url))
+        keyboard.append(row_link)
+
+        if is_adm:
+            keyboard.append([
+                InlineKeyboardButton("🩺 Health Check", callback_data=f"act:health:{tunnel.id}"),
+                InlineKeyboardButton("✏️ Change Port", callback_data=f"act:port_hint:{tunnel.id}"),
+            ])
+            keyboard.append([
+                InlineKeyboardButton("🗑️ Delete", callback_data=f"act:delete:{tunnel.id}"),
+            ])
+
+        keyboard.append([
+            InlineKeyboardButton("🔙 Back to Tunnels", callback_data="menu:list"),
+        ])
+        return InlineKeyboardMarkup(keyboard)
+
+    # --- Command Handlers ---
+
+    async def cmd_start(self, update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+        """Handle /start command and render initial dashboard."""
+        if not update.effective_user or not update.effective_message:
+            return
+
+        user = update.effective_user
+        sub = self.repo.get_or_create_subscriber(
+            chat_id=user.id,
+            username=user.username,
+            first_name=user.first_name,
+            is_admin=(user.id in self.settings.admin_chat_ids),
+        )
+
+        is_adm = self.is_admin(user.id)
+        admin_badge = "👑 <b>Administrator</b>" if is_adm else "👤 <b>Subscriber</b>"
+
+        text = (
+            f"⚡ <b>TunnelMate Control Hub</b>\n\n"
+            f"Welcome, {user.first_name}!\n"
+            f"Access Level: {admin_badge}\n\n"
+        )
+
+        if not is_adm and self.settings.has_admin_password():
+            text += "🔒 <i>To unlock admin controls, authenticate using:</i>\n<code>/login &lt;password&gt;</code>\n\n"
+
+        try:
+            tunnels = await asyncio.to_thread(self.client.list_tunnels)
+            running = sum(1 for t in tunnels if t.status == TunnelStatus.RUNNING)
+            text += f"📊 <b>Active Tunnels:</b> {running} / {len(tunnels)}\n"
+        except Exception:
+            text += "⚠️ <i>(Daemon is offline or starting...)</i>\n"
+
+        text += "Select an option below to manage tunnels:"
+
+        await update.effective_message.reply_text(
+            text,
+            reply_markup=self._main_menu_keyboard(user.id),
+            parse_mode=ParseMode.HTML,
+        )
+
+    async def cmd_login(self, update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+        """Handle /login <password> authentication."""
+        if not update.effective_user or not update.effective_message:
+            return
+
+        # Attempt to delete password message for privacy
+        try:
+            await update.effective_message.delete()
+        except Exception:
+            pass
+
+        if not context.args:
+            await update.effective_chat.send_message("❌ Usage: <code>/login &lt;password&gt;</code>", parse_mode=ParseMode.HTML)
+            return
+
+        entered = " ".join(context.args).strip()
+        if self.settings.verify_admin_password(entered):
+            sub = self.repo.get_or_create_subscriber(update.effective_user.id)
+            sub.is_admin = True
+            sub.is_authenticated = True
+            self.repo.update_subscriber(sub)
+
+            await update.effective_chat.send_message(
+                "✅ <b>Authentication successful!</b>\nYou now have full administrator access.",
+                reply_markup=self._main_menu_keyboard(update.effective_user.id),
+                parse_mode=ParseMode.HTML,
+            )
+        else:
+            await update.effective_chat.send_message("❌ <b>Invalid password.</b> Access denied.", parse_mode=ParseMode.HTML)
+
+    async def cmd_logout(self, update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+        """Handle /logout to clear admin session."""
+        if not update.effective_user:
+            return
+        sub = self.repo.get_subscriber(update.effective_user.id)
+        if sub and update.effective_user.id not in self.settings.admin_chat_ids:
+            sub.is_authenticated = False
+            self.repo.update_subscriber(sub)
+        await update.effective_chat.send_message("👋 Logged out of administrator session.")
+
+    async def cmd_create(self, update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+        """Handle /create <name> <port> [protocol]."""
+        if not update.effective_user or not self.is_admin(update.effective_user.id):
+            await update.effective_chat.send_message("⛔ Administrator access required.")
+            return
+
+        if not context.args or len(context.args) < 2:
+            await update.effective_chat.send_message(
+                "❌ Usage: <code>/create &lt;name&gt; &lt;port&gt; [protocol]</code>\n"
+                "Example: <code>/create my-app 8080 http</code>",
+                parse_mode=ParseMode.HTML,
+            )
+            return
+
+        name = context.args[0]
+        try:
+            port = int(context.args[1])
+        except ValueError:
+            await update.effective_chat.send_message("❌ Port must be an integer between 1 and 65535.")
+            return
+
+        proto = context.args[2].lower() if len(context.args) > 2 else "http"
+
+        try:
+            tun = await asyncio.to_thread(
+                self.client.create_tunnel,
+                name=name,
+                port=port,
+                protocol=proto,
+            )
+            await update.effective_chat.send_message(
+                f"✅ Tunnel <b>{tun.name}</b> created forwarding to <code>{tun.target_url}</code>!\n"
+                f"You can now start it from the menu.",
+                reply_markup=self._tunnel_action_keyboard(tun, True),
+                parse_mode=ParseMode.HTML,
+            )
+        except Exception as e:
+            await update.effective_chat.send_message(f"❌ Error creating tunnel: {e}")
+
+    async def cmd_port(self, update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+        """Handle /port <name> <new_port>."""
+        if not update.effective_user or not self.is_admin(update.effective_user.id):
+            await update.effective_chat.send_message("⛔ Administrator access required.")
+            return
+
+        if not context.args or len(context.args) < 2:
+            await update.effective_chat.send_message("❌ Usage: <code>/port &lt;tunnel_name&gt; &lt;new_port&gt;</code>", parse_mode=ParseMode.HTML)
+            return
+
+        name = context.args[0]
+        try:
+            new_port = int(context.args[1])
+        except ValueError:
+            await update.effective_chat.send_message("❌ Invalid port number.")
+            return
+
+        try:
+            tun = await asyncio.to_thread(self.client.change_port, name, new_port)
+            url_text = f"\n🔗 <b>New URL:</b> {tun.current_url}" if tun.current_url else ""
+            await update.effective_chat.send_message(
+                f"✅ Port for tunnel <b>{tun.name}</b> updated to <b>{new_port}</b>!{url_text}",
+                reply_markup=self._tunnel_action_keyboard(tun, True),
+                parse_mode=ParseMode.HTML,
+            )
+        except Exception as e:
+            await update.effective_chat.send_message(f"❌ Failed to update port: {e}")
+
+    # --- Callback Query Handlers ---
+
+    async def handle_callback_query(self, update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+        """Process inline button clicks."""
+        query = update.callback_query
+        if not query or not query.data or not update.effective_user:
+            return
+
+        try:
+            await query.answer()
+        except Exception:
+            pass
+
+        data = query.data
+        user_id = update.effective_user.id
+        is_adm = self.is_admin(user_id)
+
+        try:
+            if data == "menu:main":
+                await query.edit_message_text(
+                    "⚡ <b>TunnelMate Control Hub</b>\nSelect an option below:",
+                    reply_markup=self._main_menu_keyboard(user_id),
+                    parse_mode=ParseMode.HTML,
+                )
+
+            elif data == "menu:refresh":
+                tunnels = await asyncio.to_thread(self.client.list_tunnels)
+                running = sum(1 for t in tunnels if t.status == TunnelStatus.RUNNING)
+                await query.edit_message_text(
+                    f"⚡ <b>TunnelMate Control Hub</b> (Refreshed)\n"
+                    f"📊 <b>Active Tunnels:</b> {running} / {len(tunnels)}\n\n"
+                    f"Select an option below:",
+                    reply_markup=self._main_menu_keyboard(user_id),
+                    parse_mode=ParseMode.HTML,
+                )
+
+            elif data == "menu:list":
+                tunnels = await asyncio.to_thread(self.client.list_tunnels)
+                if not tunnels:
+                    await query.edit_message_text(
+                        "📋 <b>Tunnels List</b>\n\nNo tunnels created yet. Create one with /create or via CLI.",
+                        reply_markup=self._main_menu_keyboard(user_id),
+                        parse_mode=ParseMode.HTML,
+                    )
+                else:
+                    await query.edit_message_text(
+                        f"📋 <b>Registered Tunnels ({len(tunnels)})</b>\nClick a tunnel to view controls:",
+                        reply_markup=self._tunnels_list_keyboard(tunnels),
+                        parse_mode=ParseMode.HTML,
+                    )
+
+            elif data == "menu:create_hint":
+                await query.edit_message_text(
+                    "➕ <b>Create New Quick Tunnel</b>\n\n"
+                    "Send command in chat:\n"
+                    "<code>/create &lt;name&gt; &lt;port&gt; [protocol]</code>\n\n"
+                    "Example:\n<code>/create dev-api 8080 http</code>",
+                    reply_markup=InlineKeyboardMarkup([[
+                        InlineKeyboardButton("🔙 Back", callback_data="menu:main")
+                    ]]),
+                    parse_mode=ParseMode.HTML,
+                )
+
+            elif data == "menu:stats":
+                stats = await asyncio.to_thread(self.client.get_stats)
+                msg = (
+                    "📊 <b>Daemon Performance Stats</b>\n\n"
+                    f"• <b>PID:</b> {stats.get('pid')}\n"
+                    f"• <b>Uptime:</b> {stats.get('uptime_seconds')}s\n"
+                    f"• <b>Total Tunnels:</b> {stats.get('total_tunnels')}\n"
+                    f"• <b>Active Tunnels:</b> {stats.get('running_tunnels')}\n"
+                )
+                await query.edit_message_text(
+                    msg,
+                    reply_markup=InlineKeyboardMarkup([[
+                        InlineKeyboardButton("🔙 Back", callback_data="menu:main")
+                    ]]),
+                    parse_mode=ParseMode.HTML,
+                )
+
+            elif data == "menu:notify_settings":
+                sub = self.repo.get_or_create_subscriber(user_id)
+                new_state = not sub.notify_on_url_change
+                sub.notify_on_url_change = new_state
+                sub.notify_on_status_change = new_state
+                self.repo.update_subscriber(sub)
+
+                state_str = "🔔 <b>ENABLED</b>" if new_state else "🔕 <b>DISABLED</b>"
+                await query.edit_message_text(
+                    f"Notification preferences updated:\n"
+                    f"Alerts are now: {state_str}\n\n"
+                    f"You will receive instant alerts when tunnels start, change links, or recover.",
+                    reply_markup=InlineKeyboardMarkup([[
+                        InlineKeyboardButton("Toggle Again", callback_data="menu:notify_settings"),
+                        InlineKeyboardButton("🔙 Back", callback_data="menu:main"),
+                    ]]),
+                    parse_mode=ParseMode.HTML,
+                )
+
+            elif data == "menu:help":
+                help_text = (
+                    "❓ <b>TunnelMate Help & Commands</b>\n\n"
+                    "• <code>/start</code> - Open main interactive menu\n"
+                    "• <code>/login &lt;password&gt;</code> - Authenticate as Admin\n"
+                    "• <code>/create &lt;name&gt; &lt;port&gt;</code> - Create new tunnel\n"
+                    "• <code>/port &lt;name&gt; &lt;new_port&gt;</code> - Change target port\n"
+                    "• <code>/logout</code> - Exit admin session\n"
+                )
+                await query.edit_message_text(
+                    help_text,
+                    reply_markup=InlineKeyboardMarkup([[
+                        InlineKeyboardButton("🔙 Back", callback_data="menu:main")
+                    ]]),
+                    parse_mode=ParseMode.HTML,
+                )
+
+            elif data.startswith("tun:"):
+                tunnel_id = data.split(":", 1)[1]
+                tunnel = await asyncio.to_thread(self.client.get_tunnel, tunnel_id)
+                if not tunnel:
+                    await query.edit_message_text("❌ Tunnel not found.", reply_markup=self._main_menu_keyboard(user_id))
+                    return
+
+                msg = (
+                    f"⚡ <b>Tunnel:</b> <code>{tunnel.name}</code>\n"
+                    f"• <b>Status:</b> {'🟢 RUNNING' if tunnel.status == TunnelStatus.RUNNING else '🔴 STOPPED'}\n"
+                    f"• <b>Target:</b> <code>{tunnel.target_url}</code>\n"
+                    f"• <b>Auto-Restart:</b> {'Enabled' if tunnel.auto_restart else 'Disabled'}\n"
+                    f"• <b>PID:</b> {tunnel.pid or 'None'}\n\n"
+                )
+                if tunnel.current_url and tunnel.status == TunnelStatus.RUNNING:
+                    msg += f"🔗 <b>Public URL:</b>\n{tunnel.current_url}\n"
+                else:
+                    msg += "🔗 <i>Public URL not currently active.</i>\n"
+
+                await query.edit_message_text(
+                    msg,
+                    reply_markup=self._tunnel_action_keyboard(tunnel, is_adm),
+                    parse_mode=ParseMode.HTML,
+                )
+
+            elif data.startswith("act:"):
+                _, action, tunnel_id = data.split(":", 2)
+                tunnel = await asyncio.to_thread(self.client.get_tunnel, tunnel_id)
+                if not tunnel:
+                    await query.answer("Tunnel not found!", show_alert=True)
+                    return
+
+                if action in ("start", "stop", "restart", "delete") and not is_adm:
+                    await query.answer("⛔ Admin access required!", show_alert=True)
+                    return
+
+                if action == "link":
+                    if tunnel.current_url and tunnel.status == TunnelStatus.RUNNING:
+                        text = (
+                            f"🌐 <b>Quick Tunnel URL for {tunnel.name}:</b>\n\n"
+                            f"<code>{tunnel.current_url}</code>\n\n"
+                            f"🎯 Forwarding to: <code>{tunnel.target_url}</code>"
+                        )
+                        if tunnel.protocol in (TunnelProtocol.TCP, TunnelProtocol.TLS) or tunnel.target_port == 22:
+                            host = tunnel.current_url.replace("https://", "").replace("http://", "").strip("/")
+                            text += (
+                                f"\n\n💡 <b>Direct SSH Command:</b>\n"
+                                f"<code>tunnelmate-ssh user@{host}</code>\n"
+                                f"<i>(Or: <code>tunnelmate ssh user@{host}</code>)</i>\n"
+                            )
+                        btn = InlineKeyboardMarkup([
+                            [InlineKeyboardButton("🌐 Open in Browser", url=tunnel.current_url)],
+                            [InlineKeyboardButton("🔙 Back to Tunnel", callback_data=f"tun:{tunnel.id}")],
+                        ])
+                        await query.edit_message_text(text, reply_markup=btn, parse_mode=ParseMode.HTML)
+                    else:
+                        await query.answer("Tunnel is not currently running!", show_alert=True)
+
+                elif action == "start":
+                    await query.edit_message_text(f"⏳ Starting tunnel <b>{tunnel.name}</b>...", parse_mode=ParseMode.HTML)
+                    started = await asyncio.to_thread(self.client.start_tunnel, tunnel.id)
+                    await query.edit_message_text(
+                        f"✅ Tunnel <b>{started.name}</b> is now RUNNING!\n\n"
+                        f"🔗 <b>URL:</b> {started.current_url or 'Acquired'}",
+                        reply_markup=self._tunnel_action_keyboard(started, is_adm),
+                        parse_mode=ParseMode.HTML,
+                    )
+
+                elif action == "stop":
+                    await query.edit_message_text(f"⏳ Stopping tunnel <b>{tunnel.name}</b>...", parse_mode=ParseMode.HTML)
+                    stopped = await asyncio.to_thread(self.client.stop_tunnel, tunnel.id)
+                    await query.edit_message_text(
+                        f"🛑 Tunnel <b>{stopped.name}</b> has been stopped.",
+                        reply_markup=self._tunnel_action_keyboard(stopped, is_adm),
+                        parse_mode=ParseMode.HTML,
+                    )
+
+                elif action == "restart":
+                    await query.edit_message_text(f"🔄 Restarting tunnel <b>{tunnel.name}</b>...", parse_mode=ParseMode.HTML)
+                    restarted = await asyncio.to_thread(self.client.restart_tunnel, tunnel.id)
+                    await query.edit_message_text(
+                        f"✅ Tunnel <b>{restarted.name}</b> restarted!\n\n"
+                        f"🔗 <b>New URL:</b> {restarted.current_url}",
+                        reply_markup=self._tunnel_action_keyboard(restarted, is_adm),
+                        parse_mode=ParseMode.HTML,
+                    )
+
+                elif action == "health":
+                    health, details = await asyncio.to_thread(self.client.check_health, tunnel.id)
+                    h_icon = "🟢" if health == HealthStatus.HEALTHY else "🔴"
+                    msg = (
+                        f"🩺 <b>Health Diagnostic: {tunnel.name}</b>\n\n"
+                        f"• <b>Status:</b> {h_icon} {health.value.upper()}\n"
+                        f"• <b>Diagnosis:</b> {details.get('message')}\n"
+                        f"• <b>Local Port Open:</b> {'Yes' if details.get('local_port_open') else 'No'}\n"
+                    )
+                    await query.edit_message_text(
+                        msg,
+                        reply_markup=self._tunnel_action_keyboard(tunnel, is_adm),
+                        parse_mode=ParseMode.HTML,
+                    )
+
+                elif action == "port_hint":
+                    await query.edit_message_text(
+                        f"✏️ <b>Change Port for {tunnel.name}</b>\n\n"
+                        f"Current Port: <code>{tunnel.target_port}</code>\n\n"
+                        f"Send command in chat:\n"
+                        f"<code>/port {tunnel.name} &lt;new_port&gt;</code>\n"
+                        f"Example: <code>/port {tunnel.name} 9000</code>",
+                        reply_markup=InlineKeyboardMarkup([[
+                            InlineKeyboardButton("🔙 Back", callback_data=f"tun:{tunnel.id}")
+                        ]]),
+                        parse_mode=ParseMode.HTML,
+                    )
+
+                elif action == "delete":
+                    deleted = await asyncio.to_thread(self.client.delete_tunnel, tunnel.id)
+                    if deleted:
+                        await query.edit_message_text(
+                            f"🗑️ Tunnel <b>{tunnel.name}</b> deleted successfully.",
+                            reply_markup=self._main_menu_keyboard(user_id),
+                            parse_mode=ParseMode.HTML,
+                        )
+
+        except telegram.error.BadRequest as e:
+            if "Message is not modified" in str(e):
+                pass
+            else:
+                logger.warning("Telegram BadRequest: %s", e)
+        except (telegram.error.NetworkError, telegram.error.TimedOut) as e:
+            logger.warning("Transient network error during callback query: %s", e)
+        except Exception as e:
+            logger.error("Error handling callback: %s", e, exc_info=True)
+            try:
+                await query.answer(f"Error: {e}", show_alert=True)
+            except Exception:
+                pass
+
+    # --- Live Subscriber Event Broadcast Loop ---
+
+    async def _event_listener_loop(self) -> None:
+        """Connect to daemon IPC socket, subscribe to events, and broadcast to Telegram users."""
+        use_unix = (sys.platform != "win32") and (not self.settings.use_tcp_ipc)
+
+        while True:
+            try:
+                if use_unix:
+                    reader, writer = await asyncio.open_unix_connection(
+                        path=str(self.settings.resolved_socket_path)
+                    )
+                else:
+                    reader, writer = await asyncio.open_connection(
+                        host=self.settings.tcp_ipc_host,
+                        port=self.settings.tcp_ipc_port,
+                    )
+
+                # Send subscribe request
+                req = IPCRequest(id="bot-sub", action="subscribe_events")
+                writer.write(req.to_line())
+                await writer.drain()
+
+                # Read ack
+                await reader.readline()
+
+                logger.info("Telegram Bot successfully subscribed to daemon events.")
+
+                while True:
+                    line_bytes = await reader.readline()
+                    if not line_bytes:
+                        break
+
+                    line = line_bytes.decode("utf-8").strip()
+                    if not line:
+                        continue
+
+                    try:
+                        import json
+                        raw = json.loads(line)
+                        if raw.get("type") == "event":
+                            await self._broadcast_event(raw.get("event"), raw.get("tunnel_id"), raw.get("data", {}))
+                    except Exception as e:
+                        logger.error("Error processing event line: %s", e)
+
+            except (asyncio.CancelledError, KeyboardInterrupt):
+                break
+            except Exception as e:
+                logger.debug("Daemon IPC not yet available for event listener: %s. Retrying in 5s...", e)
+                await asyncio.sleep(5.0)
+
+    async def _broadcast_event(self, event_type: str, tunnel_id: str, data: dict) -> None:
+        """Send notification to registered subscribers."""
+        if not self.app:
+            return
+
+        name = data.get("tunnel_name", tunnel_id)
+        url = data.get("url")
+
+        msg = ""
+        btn = None
+
+        if event_type == "url_assigned" and url:
+            msg = (
+                f"⚡ <b>Quick Tunnel Online!</b>\n\n"
+                f"Tunnel: <b>{name}</b>\n"
+                f"🔗 <b>New URL:</b>\n{url}\n"
+            )
+            btn = InlineKeyboardMarkup([[InlineKeyboardButton("🌐 Open in Browser", url=url)]])
+
+        elif event_type == "crashed":
+            msg = f"⚠️ <b>Tunnel Alert:</b> '{name}' crashed! Attempting automatic recovery..."
+
+        elif event_type == "recovered" and url:
+            msg = (
+                f"✅ <b>Tunnel Recovered!</b>\n\n"
+                f"Tunnel: <b>{name}</b>\n"
+                f"🔗 <b>Restored URL:</b>\n{url}\n"
+            )
+            btn = InlineKeyboardMarkup([[InlineKeyboardButton("🌐 Open in Browser", url=url)]])
+
+        elif event_type == "stopped":
+            msg = f"🛑 <b>Tunnel Stopped:</b> '{name}' was stopped."
+
+        if not msg:
+            return
+
+        # Fetch active subscribers from SQLite
+        subscribers = await asyncio.to_thread(self.repo.list_subscribers, only_active=True)
+        for sub in subscribers:
+            try:
+                await self.app.bot.send_message(
+                    chat_id=sub.chat_id,
+                    text=msg,
+                    reply_markup=btn,
+                    parse_mode=ParseMode.HTML,
+                )
+            except Exception as e:
+                logger.debug("Failed sending broadcast to chat_id %d: %s", sub.chat_id, e)
+
+    async def error_handler(self, update: object, context: ContextTypes.DEFAULT_TYPE) -> None:
+        """Handle errors caused by Updates."""
+        err = context.error
+        if isinstance(err, (telegram.error.NetworkError, telegram.error.TimedOut)):
+            logger.warning("Transient network issue with Telegram API: %s", err)
+            return
+        if isinstance(err, telegram.error.BadRequest) and "Message is not modified" in str(err):
+            return
+        logger.error("Unhandled exception in Telegram bot: %s", err, exc_info=err)
+
+    def _write_pid(self) -> None:
+        """Write current PID to bot.pid."""
+        pid_file = self.settings.bot_pid_path
+        pid_file.parent.mkdir(parents=True, exist_ok=True)
+        with open(pid_file, "w", encoding="utf-8") as f:
+            f.write(str(os.getpid()))
+
+    def _remove_pid(self) -> None:
+        """Clean up bot.pid on termination."""
+        pid_file = self.settings.bot_pid_path
+        if pid_file.exists():
+            try:
+                pid_file.unlink()
+            except OSError:
+                pass
+
+    @classmethod
+    def get_running_pid(cls, settings: Optional[Settings] = None) -> Optional[int]:
+        """Check if bot process is currently running by PID."""
+        st = settings or load_settings()
+        pid_file = st.bot_pid_path
+        if not pid_file.exists():
+            return None
+        try:
+            pid = int(pid_file.read_text().strip())
+            os.kill(pid, 0)
+            return pid
+        except (ValueError, OSError, ProcessLookupError):
+            return None
+
+    @classmethod
+    def fetch_recent_chats(cls, token: Optional[str], exclude_chat_ids: Optional[set[int]] = None) -> list[dict]:
+        """Fetch unrecorded recent users from Telegram getUpdates API."""
+        if not token:
+            return []
+        import httpx
+        exclude = exclude_chat_ids or set()
+        recent = []
+        seen = set(exclude)
+        try:
+            with httpx.Client(timeout=5.0) as http_client:
+                resp = http_client.get(f"https://api.telegram.org/bot{token}/getUpdates")
+                if resp.status_code == 200:
+                    data = resp.json()
+                    for upd in data.get("result", []):
+                        msg = upd.get("message") or upd.get("callback_query", {}).get("message") or {}
+                        chat = msg.get("chat") or upd.get("callback_query", {}).get("from") or {}
+                        c_id = chat.get("id")
+                        if c_id and c_id not in seen:
+                            seen.add(c_id)
+                            first_name = chat.get("first_name", "")
+                            username = chat.get("username")
+                            recent.append({
+                                "chat_id": c_id,
+                                "name": first_name or "Unknown",
+                                "username": f"@{username}" if username else "—",
+                                "notify": "—",
+                                "created": "Telegram Updates",
+                            })
+        except Exception:
+            pass
+        return recent
+
+    async def start(self) -> None:
+        """Build and run Telegram bot application."""
+        token = self.settings.telegram_bot_token
+        if not token:
+            logger.error("Telegram bot token not configured! Set via 'tunnelmate bot set-token <token>'.")
+            return
+
+        self._write_pid()
+
+        request_config = HTTPXRequest(
+            connection_pool_size=8,
+            read_timeout=30.0,
+            write_timeout=20.0,
+            connect_timeout=20.0,
+            pool_timeout=15.0,
+        )
+        self.app = (
+            ApplicationBuilder()
+            .token(token)
+            .request(request_config)
+            .build()
+        )
+        self.app.add_error_handler(self.error_handler)
+
+        # Register handlers
+        self.app.add_handler(CommandHandler("start", self.cmd_start))
+        self.app.add_handler(CommandHandler("login", self.cmd_login))
+        self.app.add_handler(CommandHandler("logout", self.cmd_logout))
+        self.app.add_handler(CommandHandler("create", self.cmd_create))
+        self.app.add_handler(CommandHandler("port", self.cmd_port))
+        self.app.add_handler(CallbackQueryHandler(self.handle_callback_query))
+
+        # Launch event listener background task
+        task = asyncio.create_task(self._event_listener_loop())
+        self._background_tasks.append(task)
+
+        logger.info("TunnelMate Telegram Bot initialized (PID: %d). Starting polling...", os.getpid())
+        await self.app.initialize()
+        await self.app.start()
+        await self.app.updater.start_polling()
+
+        try:
+            while True:
+                await asyncio.sleep(1.0)
+        finally:
+            if self.app.updater:
+                await self.app.updater.stop()
+            await self.app.stop()
+            await self.app.shutdown()
+            for t in self._background_tasks:
+                t.cancel()
+            self._remove_pid()
+
+
+def run_telegram_bot() -> None:
+    """Entry point to launch the Telegram bot process."""
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+    )
+    bot = TunnelMateBot()
+    try:
+        asyncio.run(bot.start())
+    except KeyboardInterrupt:
+        pass
+
+
+if __name__ == "__main__":
+    run_telegram_bot()
+