agent-log-viewer 1.0.0 → 1.0.1

package/bin/telegram-login-bridge.py

@@ -0,0 +1,253 @@
+#!/usr/bin/env python3
+"""Viewer-owned Telegram enrollment bridge (issue #1059).
+
+Runs from the same Telethon environment as the vendored connector
+(vendor/telegram-mcp) and speaks a small sanitized NDJSON protocol:
+
+  stdout events (one JSON object per line, nothing else ever printed here):
+    {"event": "qr", "url": "tg://login?token=...", "expiresAt": iso}
+    {"event": "password_required"}
+    {"event": "password_invalid"}
+    {"event": "verifying"}
+    {"event": "authorized", "session": "<string session>", "identity": {...}}
+    {"event": "health", "status": "connected"|"expired"|"error", ...}
+    {"event": "logout", "ok": bool, "code": str|None}
+    {"event": "failed", "code": "<sanitized code>"}
+
+  stdin control lines:
+    enroll:  {"password": "..."}          (only after password_required)
+    health:  {"session": "..."}           (first line)
+    logout:  {"session": "..."}           (first line)
+
+The session string crosses ONLY these pipes: it is never an argument, never an
+environment variable of this process, and never part of an error event. Every
+failure is reduced to a sanitized code — raw exception text stays off stdout.
+Telegram API credentials arrive as TELEGRAM_API_ID / TELEGRAM_API_HASH in the
+environment, exactly as the vendored connector expects.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import datetime
+import json
+import os
+import sys
+
+from telethon import TelegramClient
+from telethon.errors import (
+    AuthKeyDuplicatedError,
+    AuthKeyUnregisteredError,
+    PasswordHashInvalidError,
+    SessionPasswordNeededError,
+    SessionRevokedError,
+)
+from telethon.sessions import StringSession
+from telegram_mcp.singleton import SessionLock, session_identity
+
+# The whole enrollment self-terminates even if the supervisor dies: an orphaned
+# bridge holding a half-done QR login must not linger with a live connection.
+ENROLL_DEADLINE_S = 15 * 60
+CONNECT_TIMEOUT_S = 30
+
+DEVICE_MODEL = "Agent Log Viewer"
+SESSION_LOCK_GRACE_S = 20.0
+
+
+def emit(payload: dict) -> None:
+    print(json.dumps(payload, separators=(",", ":")), flush=True)
+
+
+def fail(code: str) -> None:
+    emit({"event": "failed", "code": code})
+
+
+def api_credentials() -> tuple[int, str]:
+    return int(os.environ["TELEGRAM_API_ID"]), os.environ["TELEGRAM_API_HASH"]
+
+
+def make_client(session: str | None) -> TelegramClient:
+    api_id, api_hash = api_credentials()
+    return TelegramClient(
+        StringSession(session),
+        api_id,
+        api_hash,
+        device_model=DEVICE_MODEL,
+        app_version="1.0",
+    )
+
+
+async def acquire_session_lock(client: TelegramClient) -> SessionLock:
+    """Share the connector's exact per-session exclusion boundary."""
+    lock = SessionLock("default", session_identity(client))
+    await asyncio.to_thread(lock.acquire, grace_seconds=SESSION_LOCK_GRACE_S)
+    return lock
+
+
+def identity_of(user) -> dict:
+    name = " ".join(part for part in [user.first_name, user.last_name] if part) or "Telegram account"
+    # The numeric account id (issue #1091): names and handles are the operator's
+    # to change at any moment, so the id is what "the same account" means to the
+    # report-run verifier. A string, because a Telegram id is a 64-bit integer.
+    # Read defensively: an authorization that produced an entity without an id
+    # is still an authorization, and losing the login over a grouping field
+    # would be a far worse failure than reporting no id.
+    account_id = getattr(user, "id", None)
+    return {
+        "name": name,
+        "username": user.username or None,
+        "id": str(account_id) if isinstance(account_id, int) else None,
+    }
+
+
+async def read_stdin_line() -> dict | None:
+    loop = asyncio.get_running_loop()
+    line = await loop.run_in_executor(None, sys.stdin.readline)
+    if not line:
+        return None
+    try:
+        parsed = json.loads(line)
+    except json.JSONDecodeError:
+        return None
+    return parsed if isinstance(parsed, dict) else None
+
+
+async def sign_in_with_password(client: TelegramClient) -> object | None:
+    """2FA loop: each invalid password is reported and another one awaited."""
+    emit({"event": "password_required"})
+    while True:
+        control = await read_stdin_line()
+        if control is None:
+            return None
+        entered = control.get("password")
+        if not isinstance(entered, str) or not entered:
+            continue
+        try:
+            return await client.sign_in(password=entered)
+        except PasswordHashInvalidError:
+            emit({"event": "password_invalid"})
+
+
+async def enroll() -> None:
+    client = make_client(None)
+    lock = None
+    await client.connect()
+    try:
+        qr = await client.qr_login()
+        user = None
+        while user is None:
+            expires_in = max(5.0, (qr.expires - datetime.datetime.now(datetime.timezone.utc)).total_seconds())
+            emit({"event": "qr", "url": qr.url, "expiresAt": qr.expires.isoformat()})
+            try:
+                user = await qr.wait(timeout=expires_in)
+            except asyncio.TimeoutError:
+                # Expired token: mint a fresh one and re-announce it.
+                await qr.recreate()
+            except SessionPasswordNeededError:
+                user = await sign_in_with_password(client)
+                if user is None:
+                    fail("canceled")
+                    return
+        emit({"event": "verifying"})
+        me = await client.get_me()
+        lock = await acquire_session_lock(client)
+        emit({
+            "event": "authorized",
+            "session": client.session.save(),
+            "identity": identity_of(me if me is not None else user),
+        })
+    finally:
+        await client.disconnect()
+        if lock is not None:
+            lock.release()
+
+
+async def health() -> None:
+    control = await read_stdin_line()
+    session = control.get("session") if control else None
+    if not isinstance(session, str) or not session:
+        emit({"event": "health", "status": "error", "code": "bridge_failed"})
+        return
+    client = make_client(session)
+    lock = None
+    try:
+        lock = await acquire_session_lock(client)
+        await asyncio.wait_for(client.connect(), timeout=CONNECT_TIMEOUT_S)
+        try:
+            if not await client.is_user_authorized():
+                emit({"event": "health", "status": "expired"})
+                return
+            me = await client.get_me()
+            if me is None:
+                emit({"event": "health", "status": "expired"})
+                return
+            emit({"event": "health", "status": "connected", "identity": identity_of(me)})
+        finally:
+            await client.disconnect()
+    except (AuthKeyUnregisteredError, AuthKeyDuplicatedError, SessionRevokedError):
+        emit({"event": "health", "status": "expired"})
+    except (asyncio.TimeoutError, ConnectionError, OSError):
+        emit({"event": "health", "status": "error", "code": "network_failed"})
+    except Exception:
+        emit({"event": "health", "status": "error", "code": "bridge_failed"})
+    finally:
+        if lock is not None:
+            lock.release()
+
+
+async def logout() -> None:
+    control = await read_stdin_line()
+    session = control.get("session") if control else None
+    if not isinstance(session, str) or not session:
+        emit({"event": "logout", "ok": False, "code": "bridge_failed"})
+        return
+    client = make_client(session)
+    lock = None
+    try:
+        lock = await acquire_session_lock(client)
+        await asyncio.wait_for(client.connect(), timeout=CONNECT_TIMEOUT_S)
+        ok = bool(await client.log_out())
+        emit({"event": "logout", "ok": ok, "code": None if ok else "logout_failed"})
+    except (AuthKeyUnregisteredError, AuthKeyDuplicatedError, SessionRevokedError):
+        # Telegram already considers the authorization gone: remote logout is done.
+        emit({"event": "logout", "ok": True, "code": None})
+    except (asyncio.TimeoutError, ConnectionError, OSError):
+        emit({"event": "logout", "ok": False, "code": "network_failed"})
+    except Exception:
+        emit({"event": "logout", "ok": False, "code": "bridge_failed"})
+    finally:
+        try:
+            await client.disconnect()
+        finally:
+            if lock is not None:
+                lock.release()
+
+
+async def run(command: str) -> None:
+    if command == "enroll":
+        try:
+            await asyncio.wait_for(enroll(), timeout=ENROLL_DEADLINE_S)
+        except asyncio.TimeoutError:
+            fail("timed_out")
+        except (ConnectionError, OSError):
+            fail("network_failed")
+        except Exception:
+            fail("bridge_failed")
+    elif command == "health":
+        await health()
+    elif command == "logout":
+        await logout()
+    else:
+        fail("bridge_failed")
+
+
+def main() -> None:
+    command = sys.argv[1] if len(sys.argv) > 1 else ""
+    if "TELEGRAM_API_ID" not in os.environ or "TELEGRAM_API_HASH" not in os.environ:
+        fail("credentials_missing")
+        sys.exit(1)
+    asyncio.run(run(command))
+
+
+if __name__ == "__main__":
+    main()

package/bin/telegram-mcp-server.py

@@ -0,0 +1,106 @@
+#!/usr/bin/env python3
+"""Authenticated entrypoint for the packaged Telegram MCP connector."""
+
+import hashlib
+import hmac
+import os
+import re
+import sys
+
+
+TOKEN = os.environ.get("LLV_TELEGRAM_MCP_TOKEN", "")
+VENDOR_DIR = os.environ.get("LLV_TELEGRAM_VENDOR_DIR", "")
+EXCLUDED_TOOLS = [
+    name.strip()
+    for name in os.environ.get("LLV_TELEGRAM_EXCLUDED_TOOLS", "").split(",")
+    if name.strip()
+]
+if len(TOKEN) < 32 or not VENDOR_DIR:
+    raise SystemExit("authenticated Telegram MCP configuration is missing")
+
+sys.path.insert(0, VENDOR_DIR)
+
+from mcp.server.fastmcp import FastMCP  # noqa: E402
+
+
+class BearerAuthMiddleware:
+    def __init__(self, app, token: str):
+        self.app = app
+        self.expected = f"Bearer {token}".encode("utf-8")
+
+    async def __call__(self, scope, receive, send):
+        if scope.get("type") == "http":
+            headers = {key.lower(): value for key, value in scope.get("headers", [])}
+            if scope.get("path") == "/llv-telegram-proof" and scope.get("method") == "GET":
+                nonce = headers.get(b"x-llv-telegram-nonce", b"")
+                if not re.fullmatch(rb"[A-Za-z0-9_-]{43}", nonce):
+                    await send({"type": "http.response.start", "status": 400, "headers": []})
+                    await send({"type": "http.response.body", "body": b"Invalid nonce"})
+                    return
+                proof = hmac.new(TOKEN.encode("utf-8"), nonce, hashlib.sha256).hexdigest().encode("ascii")
+                await send({"type": "http.response.start", "status": 200, "headers": [(b"content-type", b"text/plain")]})
+                await send({"type": "http.response.body", "body": proof})
+                return
+            supplied = headers.get(b"authorization", b"")
+            if not hmac.compare_digest(supplied, self.expected):
+                await send({
+                    "type": "http.response.start",
+                    "status": 401,
+                    "headers": [
+                        (b"content-type", b"text/plain; charset=utf-8"),
+                        (b"www-authenticate", b"Bearer"),
+                    ],
+                })
+                await send({"type": "http.response.body", "body": b"Unauthorized"})
+                return
+        await self.app(scope, receive, send)
+
+
+_original_streamable_http_app = FastMCP.streamable_http_app
+
+
+def _authenticated_streamable_http_app(self):
+    return BearerAuthMiddleware(_original_streamable_http_app(self), TOKEN)
+
+
+FastMCP.streamable_http_app = _authenticated_streamable_http_app
+
+from telegram_mcp.runtime import mcp  # noqa: E402
+
+mcp._mcp_server.name = f"telegram-{hashlib.sha256(TOKEN.encode('utf-8')).hexdigest()}"
+
+from telegram_mcp.runner import main  # noqa: E402
+
+
+def _withhold_excluded_tools():
+    """Remove the tools this connector must not expose (issue #1091).
+
+    The Viewer runs this connector with the incoming event feed on, and the
+    feed CONSUMES settled bursts. A blocking wait tool that consumes the same
+    bursts would race it — whichever scans first takes one — so the Viewer
+    names those tools in LLV_TELEGRAM_EXCLUDED_TOOLS and they are dropped here,
+    leaving the feed the only consumer.
+
+    This lives in the Viewer's own entrypoint because upstream's
+    TELEGRAM_EXPOSED_TOOLS can only WIDEN a read-only surface with named write
+    tools, never narrow it, and the vendored tree stays byte-identical to the
+    pinned release. Importing the runner above already registered every tool,
+    so the surface is complete by the time it is pruned. An unknown name fails
+    the launch: after a vendor bump that renamed a consumer, silently exposing
+    it would be exactly the race this prevents.
+    """
+    if not EXCLUDED_TOOLS:
+        return
+    registered = {tool.name for tool in mcp._tool_manager.list_tools()}
+    unknown = sorted(set(EXCLUDED_TOOLS) - registered)
+    if unknown:
+        raise SystemExit(
+            f"cannot withhold unknown Telegram tool(s): {', '.join(unknown)}"
+        )
+    for name in EXCLUDED_TOOLS:
+        mcp._tool_manager.remove_tool(name)
+
+
+if __name__ == "__main__":
+    _withhold_excluded_tools()
+    main()

package/bin/telegram-session-reader.mjs

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { readValidatedTelegramSessionFiles } from "./telegram-session-validator.mjs";
+
+const result = readValidatedTelegramSessionFiles(process.argv[2] ?? "");
+if (result.status === "valid") process.stdout.write(result.connectorToken);
+else process.exitCode = 1;

package/bin/telegram-session-validator.mjs

@@ -0,0 +1,71 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * Validates the complete owner-only Telegram session pair. This module is
+ * shared by the Viewer session store and the packaged tmux token reader so
+ * both paths enforce the same directory, file, schema, and digest fence.
+ *
+ * @param {string} directory
+ * @returns {
+ *   | { status: "missing" }
+ *   | { status: "unsafe"; detail: string }
+ *   | { status: "valid"; sessionFile: { version: 1; credentialRef: string; sessionString: string; savedAt: string; connectorTokenSha256: string }; connectorToken: string }
+ * }
+ */
+export function readValidatedTelegramSessionFiles(directory) {
+  const expectedUid = typeof process.getuid === "function" ? process.getuid() : null;
+  let directoryStat;
+  try { directoryStat = fs.lstatSync(directory); }
+  catch (error) {
+    if (error?.code === "ENOENT") return { status: "missing" };
+    return { status: "unsafe", detail: "cannot inspect telegram directory" };
+  }
+  if (directoryStat.isSymbolicLink() || !directoryStat.isDirectory()) {
+    return { status: "unsafe", detail: "telegram directory is unsafe" };
+  }
+  if ((directoryStat.mode & 0o077) !== 0 || (expectedUid !== null && directoryStat.uid !== expectedUid)) {
+    return { status: "unsafe", detail: "telegram directory ownership or permissions are unsafe" };
+  }
+
+  const sessionPath = path.join(directory, "session.json");
+  const tokenPath = path.join(directory, "connector-token");
+  let sessionStat;
+  try { sessionStat = fs.lstatSync(sessionPath); }
+  catch (error) {
+    if (error?.code === "ENOENT") return { status: "missing" };
+    return { status: "unsafe", detail: "cannot inspect session file" };
+  }
+  if (sessionStat.isSymbolicLink() || !sessionStat.isFile() || (sessionStat.mode & 0o077) !== 0
+    || (expectedUid !== null && sessionStat.uid !== expectedUid)) {
+    return { status: "unsafe", detail: "session file ownership or permissions are unsafe" };
+  }
+
+  let sessionFile;
+  try { sessionFile = JSON.parse(fs.readFileSync(sessionPath, "utf8")); }
+  catch { return { status: "unsafe", detail: "session data is unreadable" }; }
+  if (!sessionFile || typeof sessionFile !== "object" || sessionFile.version !== 1
+    || typeof sessionFile.credentialRef !== "string"
+    || typeof sessionFile.sessionString !== "string" || !sessionFile.sessionString
+    || typeof sessionFile.savedAt !== "string"
+    || typeof sessionFile.connectorTokenSha256 !== "string") {
+    return { status: "unsafe", detail: "session data is invalid" };
+  }
+
+  let tokenStat;
+  try { tokenStat = fs.lstatSync(tokenPath); }
+  catch { return { status: "unsafe", detail: "connector token is missing or unreadable" }; }
+  if (tokenStat.isSymbolicLink() || !tokenStat.isFile() || (tokenStat.mode & 0o077) !== 0
+    || (expectedUid !== null && tokenStat.uid !== expectedUid)) {
+    return { status: "unsafe", detail: "connector token ownership or permissions are unsafe" };
+  }
+  let connectorToken;
+  try { connectorToken = fs.readFileSync(tokenPath, "utf8").trim(); }
+  catch { return { status: "unsafe", detail: "connector token is unreadable" }; }
+  const tokenHash = crypto.createHash("sha256").update(connectorToken).digest("hex");
+  if (!/^[A-Za-z0-9_-]{43}$/.test(connectorToken) || tokenHash !== sessionFile.connectorTokenSha256) {
+    return { status: "unsafe", detail: "connector token is invalid" };
+  }
+  return { status: "valid", sessionFile, connectorToken };
+}