llmt-cli 0.2.0__py3-none-any.whl

llmt/telemetry/beat.py

@@ -0,0 +1,221 @@
+"""Heartbeat orchestration: collect -> build STRICT wire payload -> POST ->
+answer challenges. The single privacy chokepoint.
+
+``build_heartbeat_payload`` emits EXACTLY the frozen request fields and nothing
+else — no paths, no scan data, no machine info. The strict-payload test asserts
+this by inspecting the object this function returns.
+"""
+
+from __future__ import annotations
+
+import datetime
+from typing import Any, Callable, Optional
+
+from ..errors import RateLimitedError
+from . import config as tcfg
+from .artifacts import ArtifactLocator, Challenge, answer_challenge
+from .collect import CollectedTorrent
+from .errors import TelemetryConfigError, TelemetryConsentError
+from .wire import AgentClient
+
+AGENT_VERSION_FALLBACK = "0.0.0"
+
+#: EXACTLY the fields the frozen wire allows per torrent entry. Used by the
+#: strict-payload test as the allow-list.
+WIRE_TORRENT_FIELDS = frozenset(
+    {"infohash_v1", "infohash_v2", "name", "state", "progress", "artifacts"})
+
+
+def _now_iso() -> str:
+    return datetime.datetime.now(datetime.timezone.utc).replace(
+        microsecond=0).isoformat().replace("+00:00", "Z")
+
+
+def _torrent_entry(t: CollectedTorrent,
+                   artifacts: list) -> dict[str, Any]:
+    """Serialize ONE torrent to exactly the frozen wire fields. No path/scan
+    data can appear here — this is the privacy boundary."""
+    return {
+        "infohash_v1": t.infohash_v1,
+        "infohash_v2": t.infohash_v2,
+        "name": t.name,
+        "state": t.state,
+        "progress": float(t.progress),
+        "artifacts": [
+            {"sha256": a["sha256"], "complete": bool(a["complete"])}
+            for a in artifacts
+        ],
+    }
+
+
+def build_heartbeat_payload(
+    agent_version: str,
+    client_name: str,
+    client_version: Optional[str],
+    torrents: list,
+    artifact_resolver: Optional[Callable[[CollectedTorrent], list]] = None,
+    max_torrents: int = 500,
+) -> dict[str, Any]:
+    """Build the exact ``POST /agent/v1/heartbeats`` request body.
+
+    Only torrents with at least one match key (v1/v2/name) are included, capped
+    at ``max_torrents`` (contract: <=500).
+    """
+    entries: list = []
+    for t in torrents:
+        if not t.has_key():
+            continue
+        arts = artifact_resolver(t) if artifact_resolver is not None else []
+        entries.append(_torrent_entry(t, arts))
+        if len(entries) >= max_torrents:
+            break
+    return {
+        "agent_version": agent_version,
+        "client": {"name": client_name,
+                   "version": client_version if client_version else None},
+        "torrents": entries,
+    }
+
+
+def default_artifact_resolver(locator: ArtifactLocator):
+    """Resolve a torrent's artifact sha256s by hashing its local content files
+    (cached). ``complete`` reflects the honest possession signal: the client
+    reports the torrent as fully seeding. Files that cannot be hashed are
+    simply omitted (never fabricated)."""
+    def _resolve(t: CollectedTorrent) -> list:
+        complete = t.state == "seeding"
+        out: list = []
+        seen: set = set()
+        for fp in t.local_files:
+            sha = locator.sha256_of(fp)
+            if sha and sha not in seen:
+                seen.add(sha)
+                out.append({"sha256": sha, "complete": complete})
+        return out
+    return _resolve
+
+
+def run_beat(
+    *,
+    source,
+    agent_version: str,
+    max_torrents: Optional[int] = None,
+    client_factory: Optional[Callable[[], AgentClient]] = None,
+    report_artifacts: Optional[bool] = None,
+    chunk_size: Optional[int] = None,
+    locator: Optional[ArtifactLocator] = None,
+) -> dict[str, Any]:
+    """Run one heartbeat cycle. Raises TelemetryConsentError (NO network) when
+    telemetry is disabled, and TelemetryConfigError when no token is stored.
+
+    ``source`` is a collect.*TelemetrySource (or None); ``client_factory``
+    builds the AgentClient (injected in tests).
+    """
+    cfg = tcfg.load_config()
+    tele = cfg["telemetry"]
+    if not tele.get("enabled"):
+        raise TelemetryConsentError(
+            "telemetry is disabled; run `llmt telemetry enable` first. "
+            "(Nothing was sent.)")
+    token = tcfg.load_token(cfg)
+    if not token:
+        raise TelemetryConfigError(
+            "telemetry is enabled but no token is stored; run "
+            "`llmt telemetry enable` to store one.")
+    if source is None:
+        raise TelemetryConfigError(
+            "no torrent client configured; pass --qb-url/--tr-url or set "
+            "LLMT_QB_URL/LLMT_TR_URL so telemetry can read your torrents.")
+
+    max_torrents = int(max_torrents if max_torrents is not None
+                       else tele.get("max_torrents_per_heartbeat", 500))
+    if report_artifacts is None:
+        report_artifacts = bool(tele.get("report_artifacts", True))
+    if chunk_size is None:
+        chunk_size = int(tele.get("challenge_chunk_size",
+                                  tcfg.DEFAULT_CHALLENGE_CHUNK))
+
+    torrents = source.collect(max_torrents=max_torrents)
+    if locator is None:
+        locator = ArtifactLocator()
+    resolver = default_artifact_resolver(locator) if report_artifacts else None
+
+    client = (client_factory() if client_factory is not None
+              else AgentClient(tele["endpoint"], token))
+
+    payload = build_heartbeat_payload(
+        agent_version=agent_version,
+        client_name=getattr(source, "kind", "unknown"),
+        client_version=None,
+        torrents=torrents,
+        artifact_resolver=resolver,
+        max_torrents=max_torrents,
+    )
+
+    summary: dict[str, Any] = {
+        "at": _now_iso(),
+        "torrents_reported": len(payload["torrents"]),
+        "accepted": 0,
+        "unmatched": [],
+        "challenges": {"total": 0, "pass": 0, "fail": 0, "expired": 0,
+                       "already-used": 0, "unresolved": 0},
+        "ok": False,
+        "error": None,
+    }
+
+    try:
+        resp = client.heartbeat(payload)
+    except RateLimitedError as exc:
+        summary["error"] = f"rate-limited (retry after {exc.retry_after}s)" \
+            if exc.retry_after else "rate-limited"
+        summary["retry_after"] = exc.retry_after
+        tcfg.record_last_beat(_slim(summary))
+        raise
+
+    if isinstance(resp.get("accepted"), int):
+        summary["accepted"] = resp["accepted"]
+    um = resp.get("unmatched")
+    if isinstance(um, list):
+        summary["unmatched"] = [i for i in um if isinstance(i, int)]
+
+    # Answer challenges promptly, same run. Candidate files = every local file
+    # across the reported torrents.
+    candidate_paths: list = []
+    seen_paths: set = set()
+    for t in torrents:
+        for fp in t.local_files:
+            if fp not in seen_paths:
+                seen_paths.add(fp)
+                candidate_paths.append(fp)
+
+    for raw in (resp.get("challenges") or []):
+        ch = Challenge.parse(raw)
+        if ch is None:
+            continue
+        summary["challenges"]["total"] += 1
+        hash_hex = answer_challenge(ch, candidate_paths, locator, chunk_size)
+        if hash_hex is None:
+            # Cannot answer honestly (file absent/incomplete): submit nothing.
+            summary["challenges"]["unresolved"] += 1
+            continue
+        result = client.answer_challenge(ch.nonce, hash_hex)
+        bucket = result if result in summary["challenges"] else "fail"
+        summary["challenges"][bucket] += 1
+
+    locator.save()
+    summary["ok"] = True
+    tcfg.record_last_beat(_slim(summary))
+    return summary
+
+
+def _slim(summary: dict) -> dict:
+    ch = summary.get("challenges", {})
+    return {
+        "at": summary.get("at"),
+        "torrents_reported": summary.get("torrents_reported"),
+        "accepted": summary.get("accepted"),
+        "challenges_total": ch.get("total", 0),
+        "challenges_passed": ch.get("pass", 0),
+        "ok": summary.get("ok", False),
+        "error": summary.get("error"),
+    }

llmt/telemetry/cmd.py

@@ -0,0 +1,358 @@
+"""``llmt telemetry`` subcommands: enable | disable | status | whoami | beat.
+
+Off-by-default, explicit opt-in (DR-27). ``enable`` prints the exact consent
+statement and requires confirmation (interactive y/N or ``--yes``). ``disable``
+stops sending and deletes the stored token. The token value is NEVER printed
+after it is saved and NEVER logged.
+"""
+
+from __future__ import annotations
+
+import getpass
+import os
+import sys
+import time
+from typing import Optional
+
+from .. import __version__
+from ..clients import (
+    QBittorrentClient, TransmissionClient, build_client,
+)
+from ..errors import LlmtError, RateLimitedError
+from ..output import emit_json, safe_text
+from . import beat as beatmod
+from . import collect as collectmod
+from . import config as tcfg
+from .consent import consent_text
+from .errors import (
+    TelemetryAuthError, TelemetryConfigError, TelemetryConsentError,
+    TelemetryScopeError,
+)
+from .wire import AgentClient, clamp_retry_after, looks_like_token
+
+
+# --------------------------------------------------------------------------- #
+# argparse wiring (called from cli.build_parser)
+# --------------------------------------------------------------------------- #
+
+def _add_client_args(sp) -> None:
+    sp.add_argument("--client",
+                    choices=["qbittorrent", "transmission", "none"],
+                    default=None,
+                    help="Torrent client to read (default: auto from "
+                         "--qb-url/--tr-url or LLMT_QB_URL/LLMT_TR_URL).")
+    sp.add_argument("--qb-url", default=None, help="qBittorrent WebUI URL "
+                    "(env LLMT_QB_URL).")
+    sp.add_argument("--qb-user", default=None, help="(env LLMT_QB_USER).")
+    sp.add_argument("--qb-pass", default=None, help="(env LLMT_QB_PASS).")
+    sp.add_argument("--tr-url", default=None, help="Transmission RPC URL "
+                    "(env LLMT_TR_URL).")
+    sp.add_argument("--tr-user", default=None, help="(env LLMT_TR_USER).")
+    sp.add_argument("--tr-pass", default=None, help="(env LLMT_TR_PASS).")
+
+
+def add_telemetry_args(sp) -> None:
+    sp.description = (
+        "Opt-in seeding telemetry (OFF by default). Sends only torrent "
+        "infohashes/names/states/progress + artifact SHA-256s + challenge "
+        "range hashes. Never sends paths or scan data. View/delete your "
+        "server-side data on the website (Account -> Telemetry).")
+    sub = sp.add_subparsers(dest="tele_action", required=True)
+
+    en = sub.add_parser("enable",
+                        help="Show the consent statement and opt in.")
+    en.add_argument("--token", default=None,
+                    help="Telemetry token from the website (env "
+                         "LLMT_AGENT_TOKEN). If omitted you are prompted.")
+    en.add_argument("--endpoint", default=None,
+                    help="Telemetry endpoint base (default: config / "
+                         f"{tcfg.DEFAULT_ENDPOINT}).")
+    en.add_argument("--yes", "-y", action="store_true",
+                    help="Confirm consent non-interactively (for scripts).")
+    en.set_defaults(func=cmd_enable)
+
+    di = sub.add_parser("disable",
+                        help="Stop sending and delete the stored token.")
+    di.set_defaults(func=cmd_disable)
+
+    st = sub.add_parser("status",
+                        help="Show consent state, token presence, last beat.")
+    st.add_argument("--json", action="store_true")
+    st.set_defaults(func=cmd_status)
+
+    wa = sub.add_parser("whoami",
+                        help="Show the identity behind the stored token "
+                             "(GET /agent/v1/me).")
+    wa.add_argument("--endpoint", default=None)
+    wa.add_argument("--json", action="store_true")
+    wa.set_defaults(func=cmd_whoami)
+
+    be = sub.add_parser("beat",
+                        help="Send one heartbeat (or --loop) and answer any "
+                             "possession challenges.")
+    _add_client_args(be)
+    be.add_argument("--endpoint", default=None)
+    be.add_argument("--interval", type=int, default=None,
+                    help="Loop interval in minutes (default: config "
+                         "telemetry.interval_minutes).")
+    be.add_argument("--loop", action="store_true",
+                    help="Keep beating on the interval cadence "
+                         "(cron/one-shot `beat` is the primary mode).")
+    grp = be.add_mutually_exclusive_group()
+    grp.add_argument("--report-artifacts", dest="report_artifacts",
+                     action="store_true", default=None,
+                     help="Include artifact SHA-256s (default: config).")
+    grp.add_argument("--no-report-artifacts", dest="report_artifacts",
+                     action="store_false",
+                     help="Omit artifact SHA-256s from heartbeats.")
+    be.add_argument("--json", action="store_true")
+    be.add_argument("--timeout", type=int, default=30)
+    be.set_defaults(func=cmd_beat)
+
+
+# --------------------------------------------------------------------------- #
+# helpers
+# --------------------------------------------------------------------------- #
+
+def _effective_endpoint(args) -> str:
+    ep = getattr(args, "endpoint", None)
+    if ep:
+        return ep
+    return tcfg.telemetry_cfg()["endpoint"]
+
+
+def _agent_client(args, *, timeout: int = 30) -> AgentClient:
+    token = tcfg.load_token()
+    if not token:
+        raise TelemetryConfigError(
+            "no telemetry token stored; run `llmt telemetry enable` first.")
+    return AgentClient(_effective_endpoint(args), token, timeout=timeout)
+
+
+def _confirmed(args) -> bool:
+    if getattr(args, "yes", False):
+        return True
+    if not sys.stdin.isatty():
+        return False
+    try:
+        ans = input("Enable telemetry and send heartbeats? [y/N] ").strip().lower()
+    except EOFError:
+        return False
+    return ans in ("y", "yes")
+
+
+# --------------------------------------------------------------------------- #
+# enable / disable
+# --------------------------------------------------------------------------- #
+
+def cmd_enable(args) -> int:
+    print(consent_text())
+    if not _confirmed(args):
+        print("Telemetry NOT enabled. Nothing was stored or sent.",
+              file=sys.stderr)
+        return 1
+
+    token = args.token or os.environ.get("LLMT_AGENT_TOKEN")
+    if not token:
+        if not sys.stdin.isatty():
+            raise TelemetryConfigError(
+                "no token provided; pass --token or set LLMT_AGENT_TOKEN "
+                "(cannot prompt without a TTY).")
+        token = getpass.getpass("Paste your telemetry token (input hidden): ")
+    token = (token or "").strip()
+    if not token:
+        raise TelemetryConfigError("empty token; nothing stored.")
+    if not looks_like_token(token):
+        print("warning: token does not look like an 'llmta_...' token; "
+              "storing it anyway (the server will reject it if invalid).",
+              file=sys.stderr)
+
+    cfg = tcfg.load_config()
+    if getattr(args, "endpoint", None):
+        cfg["telemetry"]["endpoint"] = args.endpoint
+    cfg["telemetry"]["enabled"] = True
+    tcfg.save_config(cfg)
+    path = tcfg.save_token(token, cfg)
+
+    print("Telemetry ENABLED.")
+    print(f"  token stored at {path} (mode 0600; never printed again)")
+    print(f"  endpoint: {cfg['telemetry']['endpoint']}")
+    print("  next: `llmt telemetry whoami` to confirm, then `llmt telemetry "
+          "beat` (or a cron job / --loop) to send heartbeats.")
+    print("  disable any time with `llmt telemetry disable`.")
+    return 0
+
+
+def cmd_disable(args) -> int:
+    # Stop sending first (consent off), then delete the token. A delete failure
+    # is reported honestly with a non-zero exit rather than silently claimed.
+    tcfg.set_enabled(False)
+    print("Telemetry DISABLED. No further heartbeats will be sent.")
+    try:
+        removed = tcfg.delete_token()
+    except TelemetryConfigError as exc:
+        print(f"  WARNING: {exc}", file=sys.stderr)
+        return exc.exit_code
+    print("  stored token deleted." if removed
+          else "  no stored token was present.")
+    print("  To also remove data the site already holds, use the website "
+          "(Account -> Telemetry).")
+    return 0
+
+
+# --------------------------------------------------------------------------- #
+# status
+# --------------------------------------------------------------------------- #
+
+def cmd_status(args) -> int:
+    tele = tcfg.telemetry_cfg()
+    present = tcfg.token_present()
+    info = {
+        "enabled": bool(tele.get("enabled")),
+        "token_present": present,
+        "endpoint": tele.get("endpoint"),
+        "interval_minutes": tele.get("interval_minutes"),
+        "max_torrents_per_heartbeat": tele.get("max_torrents_per_heartbeat"),
+        "report_artifacts": tele.get("report_artifacts"),
+        "token_path": tcfg.token_path(),
+        "last_beat": tele.get("last_beat"),
+    }
+    if getattr(args, "json", False):
+        emit_json(info)
+        return 0
+    print("llmt telemetry status")
+    print(f"  consent (enabled): {'yes' if info['enabled'] else 'no'}")
+    print(f"  token stored:      {'yes' if present else 'no'}")
+    print(f"  endpoint:          {info['endpoint']}")
+    print(f"  interval (min):    {info['interval_minutes']}")
+    print(f"  max torrents/beat: {info['max_torrents_per_heartbeat']}")
+    print(f"  report artifacts:  {info['report_artifacts']}")
+    lb = info["last_beat"]
+    if isinstance(lb, dict):
+        state = "ok" if lb.get("ok") else f"error: {lb.get('error')}"
+        print(f"  last beat:         {lb.get('at')} — {state}; "
+              f"reported {lb.get('torrents_reported')}, "
+              f"accepted {lb.get('accepted')}, "
+              f"challenges {lb.get('challenges_passed')}/"
+              f"{lb.get('challenges_total')} passed")
+    else:
+        print("  last beat:         (never)")
+    return 0
+
+
+# --------------------------------------------------------------------------- #
+# whoami
+# --------------------------------------------------------------------------- #
+
+def cmd_whoami(args) -> int:
+    if not tcfg.telemetry_cfg().get("enabled"):
+        # DR-27: no network while telemetry is disabled, even with a token.
+        raise TelemetryConsentError(
+            "telemetry is disabled; run `llmt telemetry enable` first. "
+            "(Nothing was sent.)")
+    client = _agent_client(args)
+    resp = client.me()
+    if getattr(args, "json", False):
+        emit_json(resp)
+        return 0
+    user = resp.get("user") if isinstance(resp.get("user"), dict) else {}
+    scopes = resp.get("scopes") if isinstance(resp.get("scopes"), list) else []
+    consent = resp.get("telemetry_consent")
+    print("llmt telemetry whoami")
+    print(f"  handle:  {safe_text(str(user.get('handle', '?')))}")
+    print(f"  user id: {user.get('id', '?')}")
+    print(f"  scopes:  {', '.join(safe_text(str(s)) for s in scopes) or '-'}")
+    print(f"  server-side telemetry consent: {consent}")
+    print("  View or delete the data the site holds on the website "
+          "(Account -> Telemetry).")
+    return 0
+
+
+# --------------------------------------------------------------------------- #
+# beat
+# --------------------------------------------------------------------------- #
+
+def _build_source(args):
+    client = build_client(args)
+    return collectmod.build_source(client)
+
+
+def _client_factory(args):
+    ep = _effective_endpoint(args)
+    timeout = getattr(args, "timeout", 30)
+
+    def _make() -> AgentClient:
+        token = tcfg.load_token()
+        if not token:
+            raise TelemetryConfigError(
+                "no telemetry token stored; run `llmt telemetry enable`.")
+        return AgentClient(ep, token, timeout=timeout)
+    return _make
+
+
+def _emit_beat(summary: dict, as_json: bool) -> None:
+    if as_json:
+        emit_json(summary)
+        return
+    ch = summary["challenges"]
+    print(f"heartbeat sent at {summary['at']}: reported "
+          f"{summary['torrents_reported']} torrent(s), server accepted "
+          f"{summary['accepted']}.")
+    if ch["total"]:
+        print(f"  challenges: {ch['total']} issued — {ch['pass']} pass, "
+              f"{ch['fail']} fail, {ch['expired']} expired, "
+              f"{ch['already-used']} already-used, "
+              f"{ch['unresolved']} unresolved (file absent/incomplete).")
+    else:
+        print("  challenges: none issued.")
+
+
+def cmd_beat(args) -> int:
+    source = _build_source(args)
+    factory = _client_factory(args)
+    as_json = getattr(args, "json", False)
+
+    def _one() -> dict:
+        return beatmod.run_beat(
+            source=source,
+            agent_version=__version__,
+            client_factory=factory,
+            report_artifacts=getattr(args, "report_artifacts", None),
+        )
+
+    if not getattr(args, "loop", False):
+        summary = _one()
+        _emit_beat(summary, as_json)
+        return 0
+
+    interval = args.interval if args.interval is not None else \
+        tcfg.telemetry_cfg().get("interval_minutes", 15)
+    interval = max(1, int(interval))
+    print(f"telemetry loop: beating every {interval} min "
+          f"(Ctrl-C to stop).", file=sys.stderr)
+    while True:
+        try:
+            summary = _one()
+            _emit_beat(summary, as_json)
+            sleep_s = interval * 60
+        except RateLimitedError as exc:
+            max_ra = int(tcfg.telemetry_cfg().get(
+                "max_retry_after_seconds", tcfg.DEFAULT_MAX_RETRY_AFTER))
+            ra = clamp_retry_after(exc.retry_after, max_ra)
+            sleep_s = ra if ra is not None else interval * 60
+            print(f"rate-limited; sleeping {sleep_s}s before next beat "
+                  f"(retry_after clamped to <= {max_ra}s).", file=sys.stderr)
+        except (TelemetryAuthError, TelemetryScopeError,
+                TelemetryConsentError, TelemetryConfigError) as exc:
+            # Non-transient: stop rather than hammer.
+            print(f"error: {exc}", file=sys.stderr)
+            return getattr(exc, "exit_code", 1)
+        except LlmtError as exc:
+            # Transient (network/timeout): report and keep the cadence.
+            print(f"beat error (will retry): {exc}", file=sys.stderr)
+            sleep_s = interval * 60
+        try:
+            time.sleep(sleep_s)
+        except KeyboardInterrupt:
+            print("\ntelemetry loop stopped.", file=sys.stderr)
+            return 0