llmt-cli 0.2.0__py3-none-any.whl

llmt/telemetry/collect.py

@@ -0,0 +1,252 @@
+"""Read torrents from a BitTorrent client for a telemetry heartbeat.
+
+Additive, read-only wrappers over the frozen ``clients.py`` adapters (mirrors
+the doctor sources). The CRITICAL correctness requirement is HYBRID KEYING
+(H3): qBittorrent 4.6 keys a hybrid (v1+v2) torrent by its TRUNCATED v2
+infohash. A v1-only report silently credits nothing. We therefore read BOTH
+``infohash_v1`` and ``infohash_v2`` and send BOTH, so the server matches
+whichever it keyed on.
+
+Only infohashes / name / state / progress ever leave the machine. Local file
+paths (``content_path``/``files``) are collected solely to answer possession
+challenges locally and are NEVER put on the wire.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from dataclasses import dataclass, field
+from typing import Optional
+
+import requests
+
+from ..clients import ClientError, QBittorrentClient, TransmissionClient
+
+_HEX40_RE = re.compile(r"^[0-9a-f]{40}$")
+_HEX64_RE = re.compile(r"^[0-9a-f]{64}$")
+
+#: The frozen wire state vocabulary (contract (b)1).
+WIRE_STATES = ("seeding", "downloading", "stalled", "paused", "error")
+
+#: Bound on files enumerated per torrent when resolving local content (defence
+#: against a pathological content dir); mirrors doctor's MAX_LAYOUT_WALK.
+MAX_CONTENT_FILES = 256
+
+#: Bound on a torrent name from an untrusted local client (anti-OOM).
+MAX_NAME_LEN = 1024
+
+# qBittorrent raw state -> frozen wire state. Unmapped -> "stalled" (never
+# fabricates "seeding"): honest "present but not clearly progressing".
+_QBT_STATE = {
+    "uploading": "seeding", "forcedUP": "seeding",
+    "stalledUP": "stalled", "stalledDL": "stalled",
+    "queuedUP": "stalled", "queuedDL": "stalled",
+    "pausedUP": "paused", "pausedDL": "paused",
+    "stoppedUP": "paused", "stoppedDL": "paused",
+    "downloading": "downloading", "forcedDL": "downloading",
+    "metaDL": "downloading", "forcedMetaDL": "downloading",
+    "allocating": "downloading", "checkingUP": "downloading",
+    "checkingDL": "downloading", "checkingResumeData": "downloading",
+    "moving": "downloading",
+    "error": "error", "missingFiles": "error",
+}
+
+# Transmission status int -> frozen wire state.
+_TR_STATE = {0: "paused", 1: "downloading", 2: "downloading",
+             3: "stalled", 4: "downloading", 5: "stalled", 6: "seeding"}
+
+
+@dataclass
+class CollectedTorrent:
+    """One torrent as observed locally. ``content_path``/``local_files`` are
+    for LOCAL challenge resolution only and are never serialized to the wire."""
+    infohash_v1: Optional[str]
+    infohash_v2: Optional[str]
+    name: Optional[str]
+    state: str
+    progress: float
+    content_path: str = ""
+    save_path: str = ""
+    local_files: list = field(default_factory=list)
+
+    def has_key(self) -> bool:
+        return bool(self.infohash_v1 or self.infohash_v2 or self.name)
+
+
+def _bounded_name(value: object) -> Optional[str]:
+    if not isinstance(value, str):
+        return None
+    return value[:MAX_NAME_LEN]
+
+
+def _hex(value: object, *, length: int) -> Optional[str]:
+    if not isinstance(value, str):
+        return None
+    v = value.strip().lower()
+    if length == 40 and _HEX40_RE.match(v):
+        return v
+    if length == 64 and _HEX64_RE.match(v):
+        return v
+    return None
+
+
+def _clamp_progress(value: object) -> float:
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        return 0.0
+    p = float(value)
+    if p < 0.0:
+        return 0.0
+    if p > 1.0:
+        return 1.0
+    return p
+
+
+def _local_files(content_path: str, cap: int = MAX_CONTENT_FILES) -> list:
+    """Enumerate regular files under ``content_path`` (a local path). Symlinks
+    are never followed. Returns [] if the path is not present locally."""
+    if not content_path:
+        return []
+    try:
+        if os.path.islink(content_path):
+            return []
+        if os.path.isfile(content_path):
+            return [content_path]
+        if not os.path.isdir(content_path):
+            return []
+    except OSError:
+        return []
+    out: list = []
+    for dirpath, dirnames, filenames in os.walk(content_path, followlinks=False):
+        for fn in sorted(filenames):
+            fp = os.path.join(dirpath, fn)
+            try:
+                if os.path.islink(fp) or not os.path.isfile(fp):
+                    continue
+            except OSError:
+                continue
+            out.append(fp)
+            if len(out) >= cap:
+                return out
+    return out
+
+
+# --------------------------------------------------------------------------- #
+# qBittorrent
+# --------------------------------------------------------------------------- #
+
+class QbtTelemetrySource:
+    kind = "qbittorrent"
+
+    def __init__(self, client: QBittorrentClient):
+        self.client = client
+
+    def _get(self, path: str, params: Optional[dict] = None):
+        c = self.client
+        r = c.session.get(f"{c.url}{path}", params=params or {},
+                          headers=c._headers(), timeout=c.timeout)
+        if r.status_code != 200:
+            raise ClientError(f"qBittorrent GET {path} failed "
+                              f"(HTTP {r.status_code}).")
+        return r
+
+    def collect(self, max_torrents: Optional[int] = None) -> list:
+        self.client._login()
+        rows = self._get("/api/v2/torrents/info").json()
+        if not isinstance(rows, list):
+            return []
+        out: list = []
+        for t in rows:
+            if not isinstance(t, dict):
+                continue
+            # Cap DURING collection: a hostile client returning 10^6 rows must
+            # not trigger 10^6 os.walk()s or unbounded memory. Stop at the cap.
+            if max_torrents is not None and len(out) >= max_torrents:
+                break
+            out.append(self._one(t))
+        return out
+
+    def _one(self, t: dict) -> CollectedTorrent:
+        # Prefer the explicit v1/v2 fields (qBt 4.4+). Both are populated for a
+        # HYBRID torrent -> we report BOTH (the H3 fix). Fall back to the legacy
+        # `hash` (client key) only if neither explicit field is a valid hex.
+        v1 = _hex(t.get("infohash_v1"), length=40)
+        v2 = _hex(t.get("infohash_v2"), length=64)
+        if v1 is None and v2 is None:
+            legacy = _hex(t.get("hash"), length=40) or _hex(t.get("hash"),
+                                                            length=64)
+            if legacy and len(legacy) == 40:
+                v1 = legacy
+            elif legacy:
+                v2 = legacy
+        raw = t.get("state") if isinstance(t.get("state"), str) else ""
+        content_path = str(t.get("content_path") or "")
+        save_path = str(t.get("save_path") or "")
+        return CollectedTorrent(
+            infohash_v1=v1, infohash_v2=v2,
+            name=_bounded_name(t.get("name")),
+            state=_QBT_STATE.get(raw, "stalled"),
+            progress=_clamp_progress(t.get("progress")),
+            content_path=content_path, save_path=save_path,
+            local_files=_local_files(content_path),
+        )
+
+
+# --------------------------------------------------------------------------- #
+# Transmission
+# --------------------------------------------------------------------------- #
+
+class TransmissionTelemetrySource:
+    kind = "transmission"
+
+    _FIELDS = ["name", "hashString", "status", "error", "errorString",
+               "percentDone", "downloadDir", "files"]
+
+    def __init__(self, client: TransmissionClient):
+        self.client = client
+
+    def collect(self, max_torrents: Optional[int] = None) -> list:
+        args = self.client._rpc("torrent-get", {"fields": self._FIELDS}) \
+            .get("arguments") or {}
+        tor = args.get("torrents") or []
+        out: list = []
+        for t in tor:
+            if not isinstance(t, dict):
+                continue
+            if max_torrents is not None and len(out) >= max_torrents:
+                break
+            out.append(self._one(t))
+        return out
+
+    def _one(self, t: dict) -> CollectedTorrent:
+        # Transmission exposes the v1 infohash as `hashString`. It does not
+        # surface a v2 infohash over the standard RPC, so v2 stays None (we
+        # never fabricate one); the name is still sent as a match key.
+        v1 = _hex(t.get("hashString"), length=40)
+        status = t.get("status")
+        state = _TR_STATE.get(status, "stalled") if isinstance(status, int) \
+            else "stalled"
+        err = t.get("error")
+        if isinstance(err, int) and err != 0:
+            state = "error"
+        name = str(t.get("name") or "")[:MAX_NAME_LEN]
+        ddir = str(t.get("downloadDir") or "")
+        content_path = os.path.join(ddir, name) if (ddir and name) else ""
+        return CollectedTorrent(
+            infohash_v1=v1, infohash_v2=None,
+            name=(name or None),
+            state=state,
+            progress=_clamp_progress(t.get("percentDone")),
+            content_path=content_path, save_path=ddir,
+            local_files=_local_files(content_path),
+        )
+
+
+def build_source(client):
+    """Wrap a frozen client adapter in a read-only telemetry source, or return
+    None when no client is configured (a Fallback/None selection)."""
+    if isinstance(client, QBittorrentClient):
+        return QbtTelemetrySource(client)
+    if isinstance(client, TransmissionClient):
+        return TransmissionTelemetrySource(client)
+    return None

llmt/telemetry/config.py

@@ -0,0 +1,237 @@
+"""Telemetry config + token storage under the llmt home dir.
+
+Precedent: the existing CLI has no config file (see docs/PERMISSIONS.md); this
+module introduces the first one, kept under ``~/.llmt/`` (overridable with the
+``LLMT_HOME`` env var, which the test-suite uses to stay hermetic). All keys
+live under a single ``telemetry`` table with the frozen defaults below.
+
+The token is stored in its OWN file (never in config.json), mode 0600, and is
+never logged or printed back after it is saved.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import stat
+import sys
+from typing import Any, Optional
+
+# --------------------------------------------------------------------------- #
+# Frozen defaults (WP-14.4-T contract). Every value is config-driven.
+# --------------------------------------------------------------------------- #
+
+#: Site base (NOT the /api base): the agent namespace is endpoint + /agent/v1.
+DEFAULT_ENDPOINT = "https://llmtorrents.com"
+DEFAULT_INTERVAL_MINUTES = 15
+DEFAULT_MAX_TORRENTS = 500
+DEFAULT_TOKEN_FILENAME = "agent-token"
+DEFAULT_CHALLENGE_CHUNK = 1 * 1024 * 1024  # 1 MiB streaming read for range hashing
+DEFAULT_MAX_RETRY_AFTER = 3600  # clamp a hostile 429 retry_after (seconds)
+
+TELEMETRY_DEFAULTS: dict[str, Any] = {
+    "enabled": False,
+    "endpoint": DEFAULT_ENDPOINT,
+    "interval_minutes": DEFAULT_INTERVAL_MINUTES,
+    "max_torrents_per_heartbeat": DEFAULT_MAX_TORRENTS,
+    "token_path": None,  # None -> <home>/agent-token (resolved lazily)
+    "challenge_chunk_size": DEFAULT_CHALLENGE_CHUNK,
+    "max_retry_after_seconds": DEFAULT_MAX_RETRY_AFTER,
+    "report_artifacts": True,
+    "last_beat": None,
+}
+
+
+def llmt_home() -> str:
+    """Resolve the llmt home dir. ``LLMT_HOME`` overrides (tests use this)."""
+    override = os.environ.get("LLMT_HOME")
+    if override:
+        return os.path.abspath(os.path.expanduser(override))
+    return os.path.join(os.path.expanduser("~"), ".llmt")
+
+
+def config_path() -> str:
+    return os.path.join(llmt_home(), "config.json")
+
+
+def _ensure_home() -> str:
+    home = llmt_home()
+    os.makedirs(home, exist_ok=True)
+    try:
+        os.chmod(home, 0o700)
+    except OSError:
+        pass
+    return home
+
+
+# --------------------------------------------------------------------------- #
+# Config load / save (JSON; stdlib only, py3.9-safe)
+# --------------------------------------------------------------------------- #
+
+def load_config() -> dict[str, Any]:
+    """Return the full config dict with telemetry defaults merged in.
+
+    A missing or unreadable/corrupt config file yields defaults (never fatal).
+    """
+    cfg: dict[str, Any] = {}
+    try:
+        with open(config_path(), "r", encoding="utf-8") as fh:
+            loaded = json.load(fh)
+        if isinstance(loaded, dict):
+            cfg = loaded
+    except (OSError, ValueError):
+        cfg = {}
+    tele = cfg.get("telemetry")
+    merged = dict(TELEMETRY_DEFAULTS)
+    if isinstance(tele, dict):
+        for k, v in tele.items():
+            merged[k] = v
+    # Env overrides (never persisted): endpoint only, following the api-base
+    # precedent of --api-base / LLMT_API_BASE.
+    env_ep = os.environ.get("LLMT_TELEMETRY_ENDPOINT")
+    if env_ep:
+        merged["endpoint"] = env_ep
+    cfg["telemetry"] = merged
+    return cfg
+
+
+def save_config(cfg: dict[str, Any]) -> None:
+    _ensure_home()
+    path = config_path()
+    tmp = path + ".tmp"
+    # Never persist an env-only endpoint override back to disk.
+    to_write = dict(cfg)
+    tele = dict(to_write.get("telemetry") or {})
+    if os.environ.get("LLMT_TELEMETRY_ENDPOINT") and \
+            tele.get("endpoint") == os.environ["LLMT_TELEMETRY_ENDPOINT"]:
+        # Restore whatever was on disk (or the default) rather than pinning env.
+        tele["endpoint"] = _disk_endpoint()
+    to_write["telemetry"] = tele
+    with open(tmp, "w", encoding="utf-8") as fh:
+        json.dump(to_write, fh, indent=2, sort_keys=True)
+    os.replace(tmp, path)
+    try:
+        os.chmod(path, 0o600)
+    except OSError:
+        pass
+
+
+def _disk_endpoint() -> str:
+    try:
+        with open(config_path(), "r", encoding="utf-8") as fh:
+            loaded = json.load(fh)
+        ep = (loaded.get("telemetry") or {}).get("endpoint")
+        if isinstance(ep, str) and ep:
+            return ep
+    except (OSError, ValueError, AttributeError):
+        pass
+    return DEFAULT_ENDPOINT
+
+
+def telemetry_cfg() -> dict[str, Any]:
+    return load_config()["telemetry"]
+
+
+def set_enabled(enabled: bool) -> None:
+    cfg = load_config()
+    cfg["telemetry"]["enabled"] = bool(enabled)
+    save_config(cfg)
+
+
+def record_last_beat(result: dict[str, Any]) -> None:
+    cfg = load_config()
+    cfg["telemetry"]["last_beat"] = result
+    save_config(cfg)
+
+
+# --------------------------------------------------------------------------- #
+# Token storage (own file, 0600, never logged / never printed)
+# --------------------------------------------------------------------------- #
+
+def token_path(cfg: Optional[dict[str, Any]] = None) -> str:
+    tele = (cfg or load_config())["telemetry"]
+    tp = tele.get("token_path")
+    if isinstance(tp, str) and tp:
+        return os.path.abspath(os.path.expanduser(tp))
+    return os.path.join(llmt_home(), DEFAULT_TOKEN_FILENAME)
+
+
+def save_token(token: str, cfg: Optional[dict[str, Any]] = None) -> str:
+    """Persist the token to its file with mode 0600. Returns the path.
+
+    Uses O_CREAT|O_WRONLY|O_TRUNC with mode 0600 so the secret is never briefly
+    world-readable between create and chmod.
+    """
+    token = (token or "").strip()
+    if not token:
+        raise ValueError("refusing to store an empty telemetry token")
+    _ensure_home()
+    path = token_path(cfg)
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    fd = os.open(path, os.O_CREAT | os.O_WRONLY | os.O_TRUNC, 0o600)
+    try:
+        os.write(fd, token.encode("utf-8"))
+    finally:
+        os.close(fd)
+    try:
+        os.chmod(path, 0o600)  # tighten even if the file pre-existed
+    except OSError:
+        pass
+    return path
+
+
+def _enforce_token_mode(path: str) -> None:
+    """The token file must be 0600 on READ as well as write (contract). A
+    pre-existing loose-perm file is repaired to 0600 (with a one-line stderr
+    warning); if it cannot be tightened, refuse to use it."""
+    try:
+        st = os.stat(path)
+    except OSError:
+        return
+    if stat.S_IMODE(st.st_mode) & 0o077:
+        try:
+            os.chmod(path, 0o600)
+        except OSError as exc:
+            from .errors import TelemetryConfigError
+            raise TelemetryConfigError(
+                f"telemetry token file {path} has insecure permissions and "
+                f"could not be tightened to 0600: {exc}. Fix it "
+                f"(chmod 600) or re-run `llmt telemetry enable`.") from exc
+        print(f"warning: tightened telemetry token file {path} to mode 0600 "
+              f"(it was group/world-accessible).", file=sys.stderr)
+
+
+def load_token(cfg: Optional[dict[str, Any]] = None) -> Optional[str]:
+    path = token_path(cfg)
+    if not os.path.exists(path):
+        return None
+    _enforce_token_mode(path)  # verify/repair 0600 before reading the secret
+    try:
+        with open(path, "r", encoding="utf-8") as fh:
+            tok = fh.read().strip()
+        return tok or None
+    except OSError:
+        return None
+
+
+def token_present(cfg: Optional[dict[str, Any]] = None) -> bool:
+    # Presence only (does not trigger perm-repair / raise) so `status` is safe.
+    return os.path.exists(token_path(cfg))
+
+
+def delete_token(cfg: Optional[dict[str, Any]] = None) -> bool:
+    """Remove the stored token. Returns True if a file was deleted, False if
+    none existed. A real removal failure is NEVER swallowed (it would falsely
+    report the token as gone while it persists) — it raises so the caller can
+    report it and exit non-zero."""
+    path = token_path(cfg)
+    try:
+        os.remove(path)
+        return True
+    except FileNotFoundError:
+        return False
+    except OSError as exc:
+        from .errors import TelemetryConfigError
+        raise TelemetryConfigError(
+            f"could not delete telemetry token file {path}: {exc}. "
+            f"The token may still be present — remove it manually.") from exc

llmt/telemetry/consent.py

@@ -0,0 +1,57 @@
+"""The exact, user-visible consent statement for telemetry (DR-27).
+
+``llmt telemetry enable`` prints this and requires explicit confirmation
+(interactive y/N, or ``--yes`` for scripts) before any token is stored or any
+heartbeat is ever sent. It states EXACTLY what is sent and what is NEVER sent.
+"""
+
+from __future__ import annotations
+
+#: What a heartbeat / challenge answer contains — enumerated for the user.
+SENDS = [
+    "For each torrent your client is seeding/downloading: its BitTorrent "
+    "infohash(es) (v1 and/or v2), the torrent name, its state "
+    "(seeding/downloading/stalled/paused/error) and progress (0..1).",
+    "The SHA-256 of artifacts you are seeding (the same public digests the "
+    "catalog already publishes).",
+    "When the server issues a possession challenge: the SHA-256 of a "
+    "server-chosen byte range of one artifact file (salt || bytes), proving "
+    "you hold the bytes without uploading them.",
+    "Your telemetry token, as an Authorization: Bearer header.",
+]
+
+#: What is NEVER sent — the privacy floor.
+NEVER = [
+    "Local file paths, filenames, or directory listings.",
+    "Anything from `llmt scan` (scan roots, scanned paths, or scan results).",
+    "Hardware, OS, network, username, or any machine fingerprint.",
+    "The raw contents of your files (only fixed-size range hashes leave).",
+]
+
+STATEMENT_VERSION = 1
+
+
+def consent_text() -> str:
+    out = [
+        "llmt telemetry — explicit opt-in consent",
+        "=" * 40,
+        "",
+        "Telemetry is OFF by default. Enabling it lets the LLM Torrents site "
+        "credit you for the artifacts you seed. It is fully revocable at any "
+        "time with `llmt telemetry disable` (which also deletes the stored "
+        "token).",
+        "",
+        "WHAT IS SENT (only while enabled, only to your configured endpoint):",
+    ]
+    for s in SENDS:
+        out.append(f"  * {s}")
+    out.append("")
+    out.append("WHAT IS NEVER SENT:")
+    for s in NEVER:
+        out.append(f"  * {s}")
+    out.append("")
+    out.append("View or delete the data the site holds about you on the "
+               "website (Account -> Telemetry); the CLI only sends and can "
+               "stop sending — it cannot delete server-side history.")
+    out.append("")
+    return "\n".join(out)

llmt/telemetry/errors.py

@@ -0,0 +1,41 @@
+"""Typed telemetry errors — telemetry-local so ``errors.py`` stays untouched.
+
+All subclass :class:`llmt.errors.LlmtError` so ``cli.main`` prints one clean
+line and exits non-zero (never a traceback). 429 rate-limiting deliberately
+REUSES the existing :class:`llmt.errors.RateLimitedError` (exit 5) so the CLI's
+single Retry-After path handles it identically to the read API.
+"""
+
+from __future__ import annotations
+
+from ..errors import LlmtError
+
+
+class TelemetryError(LlmtError):
+    """Base for telemetry failures that are not one of the specific kinds."""
+
+    exit_code = 20
+
+
+class TelemetryConsentError(TelemetryError):
+    """Telemetry is disabled / no consent — NEVER touches the network."""
+
+    exit_code = 20
+
+
+class TelemetryConfigError(TelemetryError):
+    """Missing token / bad endpoint / unusable local config."""
+
+    exit_code = 23
+
+
+class TelemetryAuthError(TelemetryError):
+    """401 — missing/unknown/revoked token."""
+
+    exit_code = 21
+
+
+class TelemetryScopeError(TelemetryError):
+    """403 — the token lacks the ``telemetry:write`` scope."""
+
+    exit_code = 22