tlgr-cli 2.0.1__py3-none-any.whl

tlgr/core/identity.py

@@ -0,0 +1,127 @@
+"""The strings tlgr sends in `initConnection`, and why they are honest.
+
+Telegram shows `device_model` / `system_version` / `app_version` in
+Settings → Devices. Two rules govern what goes there:
+
+* **Never an official app's identity.** Borrowing an official `api_id` or
+  spoofing `device_model` to obtain official-app behaviour is a ToS violation
+  that gets accounts banned (§1.2). tlgr says what it is.
+* **Stable across restarts.** Telethon's defaults are derived from
+  `platform.uname()` at each start; anything that varies (a container
+  hostname, a kernel patch level) makes the Devices entry churn, and a user
+  who checks their sessions sees a new "device" every reboot. The resolved
+  strings are therefore written once to `identity.json` and reused.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import locale
+import platform
+import time
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+from tlgr.core.paths import TlgrPaths, write_private
+
+__all__ = ["Identity", "load_identity"]
+
+
+@dataclass(frozen=True)
+class Identity:
+    device_model: str
+    system_version: str
+    app_version: str
+    lang_code: str
+    system_lang_code: str
+
+    def params(self) -> dict[str, int]:
+        """`initConnection.params` — the tz offset official clients send."""
+        return {"tz_offset": -time.timezone if not time.daylight else -time.altzone}
+
+
+def _derive_device_model() -> str:
+    node = platform.node().split(".")[0] or "unknown-host"
+    machine = platform.machine() or "unknown"
+    return f"{node} ({machine})"[:64]
+
+
+def _derive_system_version() -> str:
+    system = platform.system()
+    if system == "Darwin":
+        release = platform.mac_ver()[0] or platform.release()
+        return f"macOS {release}"[:64]
+    if system == "Linux":
+        # `platform.freedesktop_os_release()` needs 3.10+ and is absent in a
+        # bare container; the kernel release is always there.
+        try:
+            info = platform.freedesktop_os_release()
+            name = info.get("PRETTY_NAME") or info.get("NAME") or "Linux"
+        except (OSError, AttributeError):
+            name = "Linux"
+        return f"{name} ({platform.release()})"[:64]
+    return f"{system} {platform.release()}"[:64]
+
+
+def _derive_lang() -> tuple[str, str]:
+    try:
+        code = (locale.getlocale()[0] or "").split("_")[0].lower()
+    except (ValueError, TypeError):  # pragma: no cover - locale is odd on some CI images
+        code = ""
+    lang = code if len(code) == 2 else "en"
+    return lang, lang
+
+
+def load_identity(
+    base: Path | None = None,
+    *,
+    device_model: str = "",
+    system_version: str = "",
+    lang_code: str = "",
+    system_lang_code: str = "",
+    app_version: str = "",
+) -> Identity:
+    """Resolve the identity, preferring config, then the cache, then the OS.
+
+    The cache is written the first time so that the value survives an OS
+    upgrade: what matters to the Devices list is that the string does not
+    change, not that it stays accurate to the patch level.
+    """
+    from tlgr import __version__
+
+    paths = TlgrPaths(base)
+    cached: dict[str, str] = {}
+    if paths.identity.exists():
+        try:
+            loaded = json.loads(paths.identity.read_text())
+            if isinstance(loaded, dict):
+                cached = {str(k): str(v) for k, v in loaded.items()}
+        except (OSError, json.JSONDecodeError):
+            cached = {}
+
+    derived_lang, derived_system_lang = _derive_lang()
+    if not app_version:
+        try:
+            import telethon
+
+            app_version = f"tlgr {__version__} (Telethon {telethon.__version__})"
+        except Exception:  # pragma: no cover - telethon is a hard dependency
+            app_version = f"tlgr {__version__}"
+
+    identity = Identity(
+        device_model=device_model or cached.get("device_model") or _derive_device_model(),
+        system_version=system_version or cached.get("system_version") or _derive_system_version(),
+        app_version=app_version,
+        lang_code=lang_code or cached.get("lang_code") or derived_lang,
+        system_lang_code=(
+            system_lang_code or cached.get("system_lang_code") or derived_system_lang
+        ),
+    )
+
+    if cached != asdict(identity):
+        # A read-only home must not stop a login; the identity is then
+        # re-derived next time, which is stable anyway on a stable machine.
+        with contextlib.suppress(OSError):
+            write_private(paths.identity, json.dumps(asdict(identity), indent=2))
+    return identity

tlgr/core/launchd.py

@@ -0,0 +1,122 @@
+"""macOS LaunchAgent management for the tlgr daemon (§6.12).
+
+`KeepAlive.SuccessfulExit = false` means "restart it unless it exited 0",
+which is only safe if the daemon never exits 0 on its own. It did: the idle
+monitor stopped it after thirty minutes, launchd saw a clean exit, and the
+daemon never came back — jobs silently stopped and the webhook silently
+unsubscribed until someone noticed. That is COR-39.
+
+Two changes close it. The plist passes `--base`, and the daemon forces
+`idle_timeout` to 0 whenever a supervisor owns it, so the clean exit that
+launchd will not restart cannot happen. And a manually started second daemon
+exits 0 with "already running" rather than 1, so `KeepAlive` does not turn a
+duplicate start into a respawn loop.
+
+The `ExecStart` also runs `tlgr.daemon.main`, not `tlgr.daemon.server`; the
+latter still works as an alias, and an already-installed v1 plist keeps
+running until it is reinstalled.
+"""
+
+from __future__ import annotations
+
+import os
+import plistlib
+import subprocess
+import sys
+from pathlib import Path
+
+SERVICE_LABEL = "dev.tlgr.daemon"
+PLIST_PATH = Path.home() / "Library" / "LaunchAgents" / f"{SERVICE_LABEL}.plist"
+
+
+def _python_executable() -> str:
+    """Return the absolute path to the current Python interpreter."""
+    return sys.executable
+
+
+def _build_plist(base: Path, log_dir: Path) -> dict:
+    log_dir.mkdir(parents=True, exist_ok=True, mode=0o700)
+    return {
+        "Label": SERVICE_LABEL,
+        "ProgramArguments": [
+            _python_executable(),
+            "-m",
+            "tlgr.daemon.main",
+            "--base",
+            str(base),
+            "--foreground",
+        ],
+        "RunAtLoad": True,
+        "KeepAlive": {"SuccessfulExit": False},
+        "ThrottleInterval": 30,
+        # Tells the daemon a supervisor owns it, which forces idle_timeout to
+        # 0 — the other half of the COR-39 fix.
+        "EnvironmentVariables": {"XPC_SERVICE_NAME": SERVICE_LABEL},
+        "StandardOutPath": str(log_dir / "daemon.log"),
+        "StandardErrorPath": str(log_dir / "daemon.log"),
+    }
+
+
+def is_installed() -> bool:
+    return PLIST_PATH.exists()
+
+
+def is_loaded() -> bool:
+    result = subprocess.run(
+        ["launchctl", "print", f"gui/{os.getuid()}/{SERVICE_LABEL}"],
+        capture_output=True,
+    )
+    return result.returncode == 0
+
+
+def install(base: Path, log_dir: Path) -> Path:
+    """Write the plist and load it into launchd. Returns the plist path."""
+    if is_loaded():
+        unload()
+
+    PLIST_PATH.parent.mkdir(parents=True, exist_ok=True)
+    plist_data = _build_plist(base, log_dir)
+    with open(PLIST_PATH, "wb") as f:
+        plistlib.dump(plist_data, f)
+
+    _load()
+    return PLIST_PATH
+
+
+def uninstall() -> bool:
+    """Unload and remove the plist. Returns True if anything was removed."""
+    removed = False
+    if is_loaded():
+        unload()
+        removed = True
+    if PLIST_PATH.exists():
+        PLIST_PATH.unlink()
+        removed = True
+    return removed
+
+
+def _load() -> None:
+    subprocess.run(
+        ["launchctl", "bootstrap", f"gui/{os.getuid()}", str(PLIST_PATH)],
+        check=True,
+    )
+
+
+def unload() -> None:
+    subprocess.run(
+        ["launchctl", "bootout", f"gui/{os.getuid()}/{SERVICE_LABEL}"],
+        capture_output=True,
+    )
+
+
+def kickstart() -> None:
+    """Force-(re)start the service via launchctl."""
+    subprocess.run(
+        [
+            "launchctl",
+            "kickstart",
+            "-k",
+            f"gui/{os.getuid()}/{SERVICE_LABEL}",
+        ],
+        check=True,
+    )

tlgr/core/logging.py

@@ -0,0 +1,194 @@
+"""Structured, rotating, redacted logs — configured exactly once.
+
+Three v1 problems die here:
+
+* **SEC-05/06.** The daemon logged message text, phone numbers and webhook
+  tokens at INFO into a 0644 file that grew without bound. Logs are now JSON
+  lines in a 0600 rotating file, and every record passes a redaction filter.
+* **COR-40.** `logging.basicConfig` was called with two handlers and then
+  called again by another entry point, so lines were duplicated and the file
+  handler was attached twice. `setup_logging()` is idempotent: it owns the
+  root logger's handlers and replaces them.
+* Redaction is an **allow-list**. A blocklist of patterns over free-form
+  message text is not a control — one Persian message with a phone number
+  spelled in Eastern Arabic digits defeats it. Only the fields named in
+  `SAFE_FIELDS` survive into the record's `extra`; everything else is dropped,
+  and the message itself is scrubbed of the few high-value literals that do
+  have a reliable shape (tokens, auth keys, `access_hash`).
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import logging
+import logging.handlers
+import os
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+__all__ = [
+    "SAFE_FIELDS",
+    "PrivateRotatingFileHandler",
+    "RedactionFilter",
+    "setup_logging",
+]
+
+#: The only keys allowed out of a log record's structured payload.
+SAFE_FIELDS = frozenset(
+    {
+        "account",
+        "op",
+        "request_id",
+        "elapsed_ms",
+        "status",
+        "code",
+        "exit_code",
+        "state",
+        "reason",
+        "seq",
+        "chat_id",
+        "peer_id",
+        "count",
+        "attempt",
+        "pid",
+        "uid",
+        "path",
+        "method",
+        "rate_class",
+        "wait_seconds",
+        "event_type",
+        "delivery_id",
+        "alias",
+        "version",
+        "protocol",
+    }
+)
+
+_REDACTIONS: tuple[tuple[re.Pattern[str], str], ...] = (
+    (
+        re.compile(r"(?i)\b(auth_?key|api_?hash|access_?hash|file_?reference)\b\s*[=:]\s*\S+"),
+        r"\1=<redacted>",
+    ),
+    (re.compile(r"(?i)\b(token|secret|password|passwd)\b\s*[=:]\s*\S+"), r"\1=<redacted>"),
+    (re.compile(r"(?i)\bBearer\s+[A-Za-z0-9._\-]+"), "Bearer <redacted>"),
+    (re.compile(r"\+\d[\d\s\-()]{6,}\d"), "<phone>"),
+)
+
+_PLACEHOLDER = "<redacted>"
+
+
+class RedactionFilter(logging.Filter):
+    """Scrub a record in place. Never disabled by `--verbose`."""
+
+    def __init__(self, enabled: bool = True) -> None:
+        super().__init__()
+        self.enabled = enabled
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        if not self.enabled:
+            return True
+        try:
+            message = record.getMessage()
+        except Exception:  # pragma: no cover - a broken %-format is not our problem
+            return True
+        for pattern, replacement in _REDACTIONS:
+            message = pattern.sub(replacement, message)
+        record.msg = message
+        record.args = ()
+        return True
+
+
+class PrivateRotatingFileHandler(logging.handlers.RotatingFileHandler):
+    """A rotating handler whose files are 0600 — including after a rollover.
+
+    `RotatingFileHandler` reopens the log through `open()`, which applies the
+    process umask. A daemon started from a shell with a permissive umask, or
+    one whose parent widened it, therefore ends up with a world-readable log
+    the first time it rotates — and a tlgr log names accounts, chats and
+    peers. Chmod-ing on every open is cheap and closes the window.
+    """
+
+    def _open(self) -> Any:
+        stream = super()._open()
+        with contextlib.suppress(OSError):
+            os.chmod(self.baseFilename, 0o600)
+        return stream
+
+    def doRollover(self) -> None:
+        super().doRollover()
+        for index in range(1, self.backupCount + 1):
+            with contextlib.suppress(OSError):
+                os.chmod(f"{self.baseFilename}.{index}", 0o600)
+
+
+class JsonFormatter(logging.Formatter):
+    """One JSON object per line, with only allow-listed extras."""
+
+    def format(self, record: logging.LogRecord) -> str:
+        payload: dict[str, Any] = {
+            "ts": self.formatTime(record, "%Y-%m-%dT%H:%M:%S%z"),
+            "level": record.levelname.lower(),
+            "logger": record.name,
+            "msg": record.getMessage(),
+        }
+        for key, value in record.__dict__.items():
+            if key in SAFE_FIELDS and value is not None:
+                payload[key] = value
+        if record.exc_info:
+            payload["exc"] = self.formatException(record.exc_info)
+        return json.dumps(payload, ensure_ascii=False, default=str)
+
+
+def setup_logging(
+    log_file: Path | None,
+    *,
+    level: str = "info",
+    stderr: bool = False,
+    redact: bool = True,
+    max_bytes: int = 8 * 1024 * 1024,
+    backups: int = 5,
+) -> logging.Logger:
+    """Install the daemon's logging configuration, replacing anything present.
+
+    Returns the root logger. Passing `log_file=None` gives stderr only, which
+    is what `--foreground` in a test wants.
+    """
+    root = logging.getLogger()
+    for handler in list(root.handlers):
+        root.removeHandler(handler)
+        with contextlib.suppress(Exception):  # pragma: no cover
+            handler.close()
+
+    root.setLevel(getattr(logging, level.upper(), logging.INFO))
+    redaction = RedactionFilter(redact)
+
+    if log_file is not None:
+        log_file.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+        # Create the file privately *before* the handler opens it: the handler
+        # would otherwise create it with the process umask, and a daemon whose
+        # umask was widened by its parent would leave a readable log.
+        if not log_file.exists():
+            log_file.touch(mode=0o600)
+        else:
+            with contextlib.suppress(OSError):  # pragma: no cover
+                os.chmod(log_file, 0o600)
+        file_handler = PrivateRotatingFileHandler(
+            str(log_file), maxBytes=max_bytes, backupCount=backups, encoding="utf-8"
+        )
+        file_handler.setFormatter(JsonFormatter())
+        file_handler.addFilter(redaction)
+        root.addHandler(file_handler)
+
+    if stderr or log_file is None:
+        stream = logging.StreamHandler(sys.stderr)
+        stream.setFormatter(logging.Formatter("%(asctime)s %(levelname)s %(name)s: %(message)s"))
+        stream.addFilter(redaction)
+        root.addHandler(stream)
+
+    # aiohttp's access log is off (SEC-05); its client session warnings are not
+    # interesting at INFO either.
+    logging.getLogger("aiohttp.access").disabled = True
+    return root

tlgr/core/media.py

@@ -0,0 +1,134 @@
+"""Reading a media file's own metadata, without sending it anywhere.
+
+Lives in `core/` rather than in the daemon's file pipeline because the send
+path needs it too and `ops/` may not import `daemon/` (§2.2). It is also the
+one place that knows the difference between "this file has no duration" and
+"nothing on this machine can read a duration": a video sent with
+`duration=0, w=1, h=1` renders in every Telegram client as a 1x1 black
+rectangle, which is worse than sending it as a plain document.
+"""
+
+from __future__ import annotations
+
+import contextlib
+from pathlib import Path
+from typing import Any
+
+__all__ = ["infer_attributes", "probe", "probe_warnings"]
+
+
+def infer_attributes(path: Path) -> tuple[dict[str, Any], list[str]]:
+    """Best-effort media metadata, and the warnings for what could not be read.
+
+    A video sent with `duration=0, w=1, h=1` renders in every Telegram client
+    as a 1×1 black rectangle. That is worse than a plain document, so when
+    nothing can read the file the caller is *told* — the warning is the
+    feature, not the fallback.
+    """
+    facts: dict[str, Any] = {}
+    warnings: list[str] = []
+    suffix = path.suffix.lower()
+
+    if suffix in (".jpg", ".jpeg", ".png", ".webp", ".gif", ".bmp"):
+        try:
+            from PIL import Image
+
+            with Image.open(path) as image:
+                facts["width"], facts["height"] = image.size
+        except Exception:
+            warnings.append(
+                "install the [media] extra (pillow) for image dimensions; sending without them"
+            )
+        return facts, warnings
+
+    if suffix in (".mp4", ".mkv", ".mov", ".webm", ".mp3", ".m4a", ".ogg", ".oga", ".opus"):
+        probed = _ffprobe(path)
+        if probed:
+            facts.update(probed)
+            return facts, warnings
+        try:
+            from hachoir.metadata import extractMetadata
+            from hachoir.parser import createParser
+
+            parser = createParser(str(path))
+            if parser is not None:
+                with parser:
+                    meta = extractMetadata(parser)
+                if meta is not None:
+                    if meta.has("duration"):
+                        facts["duration"] = int(meta.get("duration").total_seconds())
+                    if meta.has("width"):
+                        facts["width"] = int(meta.get("width"))
+                    if meta.has("height"):
+                        facts["height"] = int(meta.get("height"))
+        except Exception:
+            pass
+        if not facts:
+            warnings.append(
+                "no ffprobe and no [media] extra: this file is sent without "
+                "duration or dimensions, which some clients render as a 1x1 "
+                "placeholder — pass --duration/--width/--height, or install them"
+            )
+    return facts, warnings
+
+
+def _ffprobe(path: Path) -> dict[str, Any]:
+    import json
+    import shutil
+    import subprocess
+
+    binary = shutil.which("ffprobe")
+    if not binary:
+        return {}
+    try:
+        output = subprocess.run(
+            [
+                binary,
+                "-v",
+                "quiet",
+                "-print_format",
+                "json",
+                "-show_format",
+                "-show_streams",
+                str(path),
+            ],
+            capture_output=True,
+            timeout=20,
+            check=False,
+        )
+        data = json.loads(output.stdout or b"{}")
+    except (OSError, ValueError, subprocess.SubprocessError):
+        return {}
+    facts: dict[str, Any] = {}
+    duration = (data.get("format") or {}).get("duration")
+    if duration:
+        with contextlib.suppress(ValueError, TypeError):
+            facts["duration"] = int(float(duration))
+    for stream in data.get("streams") or ():
+        if stream.get("codec_type") == "video":
+            facts["width"] = int(stream.get("width") or 0) or None
+            facts["height"] = int(stream.get("height") or 0) or None
+            break
+    return {k: v for k, v in facts.items() if v}
+
+
+def probe(path: Path) -> dict[str, Any]:
+    """The facts only, for a caller that reports its own warnings."""
+    return infer_attributes(path)[0]
+
+
+def probe_warnings(path: Path, *, voice: bool = False, video_note: bool = False) -> list[str]:
+    """The warnings only.
+
+    A voice note or a round video with no duration is the case that actually
+    hurts — the client draws an empty waveform and the message looks broken —
+    so it is called out separately rather than folded into the generic
+    "install ffprobe" line.
+    """
+    facts, warnings = infer_attributes(path)
+    if (voice or video_note) and not facts.get("duration"):
+        warnings.append(
+            "no duration could be read for this file; a voice note or round video "
+            "without one shows an empty waveform in every client"
+        )
+    return warnings