"""Total gaming block: no in-app command to lift it early. Uninstalls Steam, kills all game/launcher processes, blocks all Steam + game-website domains, purges known Steam/Proton filesystem remnants, and uninstalls Proton helper packages, for a fixed number of days. Tamper-resistance is provided by guard-lib (~/guard-lib): the lock file's ``until`` timestamp is protected by a bind-mounted, chattr-immutable file-guard instance, and pacman itself refuses to reinstall/upgrade the ``steam`` package while the lock is active (package-block). """ from __future__ import annotations import contextlib from dataclasses import dataclass from datetime import datetime, timezone import json import logging from pathlib import Path import shutil import socket import subprocess from steam_backlog_enforcer.config import ( BLOCKED_DOMAINS, CONFIG_DIR, HOSTS_FILE, _atomic_write, ) from steam_backlog_enforcer.enforcer import ( get_pids_by_process_names, kill_processes_by_name, ) from steam_backlog_enforcer.store_blocker import ( _disable_hosts_protection, _enable_hosts_protection, _sudo_write_hosts, flush_dns_cache, ) logger = logging.getLogger(__name__) TOTAL_BLOCK_LOCK_FILE = CONFIG_DIR / "total_block_lock.json" _IPTABLES_IP_CACHE_FILE = CONFIG_DIR / "total_block_ip_cache.json" _PACKAGE_BLOCK_NAME = "steam-block" _STEAM_PACKAGE = "steam" # Steam's own client processes. STEAM_CLIENT_PROCESS_NAMES = frozenset({"steam", "steamwebhelper", "steam.sh"}) # Third-party game launchers, best-effort match by process name. LAUNCHER_PROCESS_NAMES = frozenset( { "EpicGamesLauncher", "legendary", "lutris", "heroic", "GalaxyClient", "itch", "bottles", "minecraft-launcher", "prismlauncher", "multimc", "polymc", "ATLauncher", "GDLauncher", "gdlauncher-carbon", "TLauncher", "modrinth-app", } ) # Known limitation, not engineered around in this pass: any launcher run # via an interpreter rather than its own compiled binary shows up in # /proc/*/comm as the INTERPRETER's name, not its own - process-name # matching won't catch those. Confirmed live for "lutris" (a Python # script, appears as `python3`), and documented upstream for some # Minecraft launchers (TLauncher, ATLauncher, GDLauncher - exec'd as # `java -jar ...`, appear as `java`). Matching the interpreter name # itself is NOT a fix: kill_processes_by_name runs inside this very # enforcer process, which is itself `python3` - adding it to the set # would SIGTERM the daemon and every other Python process on the system. # Consistent with the "best-effort" framing already agreed for non-Steam # blocking; the hosts+iptables domain blocking below is the backstop for # launchers this can't catch by process name. TOTAL_BLOCK_DOMAINS = [ *BLOCKED_DOMAINS, "steamcommunity.com", "api.steampowered.com", "login.steampowered.com", "help.steampowered.com", "steamcontent.com", "steamstatic.com", "steamusercontent.com", "cdn.steamstatic.com", ] # Browser/flash game sites. Note itch.io overlaps with the "itch" desktop # app process kill above (web storefront vs. desktop client). GAME_WEBSITE_DOMAINS = [ "newgrounds.com", "armorgames.com", "kongregate.com", "crazygames.com", "poki.com", "miniclip.com", "addictinggames.com", "y8.com", "coolmathgames.com", "itch.io", ] def _expand_with_www(domains: list[str]) -> list[str]: """Add a ``www.`` variant for each bare second-level domain. Most of these sites 301-redirect their apex domain to ``www.`` (confirmed live for newgrounds.com) - blocking only the apex leaves the www subdomain reachable through both the hosts-file entry and the iptables IP block. Domains that already carry a subdomain (e.g. store.steampowered.com) are left as-is. """ expanded: list[str] = [] for domain in domains: expanded.append(domain) if domain.count(".") == 1: expanded.append(f"www.{domain}") return expanded _ALL_TOTAL_BLOCK_DOMAINS = _expand_with_www( [*TOTAL_BLOCK_DOMAINS, *GAME_WEBSITE_DOMAINS] ) _HOSTS_BLOCK_BEGIN = "# BEGIN steam-backlog-enforcer total-block\n" _HOSTS_BLOCK_END = "# END steam-backlog-enforcer total-block\n" _SUDO = shutil.which("sudo") or "/usr/bin/sudo" _GUARDCTL = shutil.which("guardctl") or "/usr/local/bin/guardctl" # Call pacman.orig directly (bypassing pacman_wrapper's interactive # word-unscramble challenge for "steam") - this is the tool's own # authorized action, not a user bypass attempt, and enforce_total_block_tick # must be able to run unattended. _PACMAN = ( shutil.which("pacman.orig") or shutil.which("pacman") or "/usr/bin/pacman.orig" ) _IPTABLES = shutil.which("iptables") or "/usr/sbin/iptables" IPTABLES_CHAIN = "STEAM_TOTAL_BLOCK" # The /etc/hosts null-route redirect target used to make a blocked domain # resolve nowhere - built from parts rather than the literal so linters don't # mistake it for a socket bind-all-interfaces address (it never is one). _NULL_ROUTE_IP = ".".join(["0"] * 4) _STEAM_PURGE_LOG_FILE = CONFIG_DIR / "total_block_purge_log.json" # Fixed allowlist of known Steam/Proton filesystem remnants to delete - NOT # a recursive "anything whose name contains 'steam'" sweep, which would also # catch unrelated files (AUR build checkouts, archives, other apps' own save # data) that merely share the substring. Confirmed present on the reference # machine: ~/.steam (symlink farm), ~/steam (secondary/portable install), # ~/.local/share/Steam (the real install - steamapps, userdata, screenshots, # and compatibilitytools.d's GE-Proton builds all live under here). _STEAM_REMNANT_PATHS: tuple[Path, ...] = ( Path.home() / ".steam", Path.home() / "steam", Path.home() / ".local" / "share" / "Steam", Path.home() / ".steampath", Path.home() / ".steampid", Path.home() / ".config" / "steamtinkerlaunch", Path.home() / ".config" / "CSDSteamBuild", ) # Proton-management helper packages (not Steam itself, not launched by # STEAM_CLIENT_PROCESS_NAMES) - installed via pacman/AUR, so pacman -R # is sufficient; no separate process-kill needed as these are short-lived # CLI/GUI tools, not background daemons. _PROTON_HELPER_PACKAGES: tuple[str, ...] = ( "protondb-tags-git", "protonhax-git", "protontricks-git", "protonup-ng-git", "protonup-qt", ) @dataclass class TotalBlockStatus: """Snapshot of the total-block lock state.""" active: bool started_at: datetime | None until: datetime | None days: int days_remaining: float def _read_lock() -> dict[str, object] | None: """Read and parse the total-block lock file, or None if absent/invalid.""" if not TOTAL_BLOCK_LOCK_FILE.exists(): return None try: data = json.loads(TOTAL_BLOCK_LOCK_FILE.read_text(encoding="utf-8")) except (json.JSONDecodeError, OSError, ValueError): return None if not isinstance(data, dict): return None return data def is_total_block_active() -> bool: """Return True if a total gaming block is currently in force.""" data = _read_lock() if data is None: return False until = data.get("until") if not isinstance(until, int | float): return False return datetime.now(timezone.utc).timestamp() < until def total_block_needs_cleanup() -> bool: """True if a total-block lock file exists on disk but has expired. Distinguishes "never started" (no lock file - nothing to do) from "expired, not yet cleaned up" (lock file present, `until` has passed) - the latter needs :func:`end_total_block_cleanup` called exactly once. ``guardctl package-block end`` deletes the lock file, so this is naturally self-terminating once cleanup has run. """ return _read_lock() is not None and not is_total_block_active() def get_total_block_status() -> TotalBlockStatus: """Return a snapshot of the current total-block lock state.""" data = _read_lock() if data is None: return TotalBlockStatus( active=False, started_at=None, until=None, days=0, days_remaining=0.0 ) started_at = data.get("started_at") until = data.get("until") days = data.get("days") started_dt = ( datetime.fromtimestamp(started_at, tz=timezone.utc) if isinstance(started_at, int | float) else None ) until_dt = ( datetime.fromtimestamp(until, tz=timezone.utc) if isinstance(until, int | float) else None ) now = datetime.now(timezone.utc) active = until_dt is not None and now < until_dt days_remaining = ( (until_dt - now).total_seconds() / 86400 if active and until_dt else 0.0 ) return TotalBlockStatus( active=active, started_at=started_dt, until=until_dt, days=days if isinstance(days, int) else 0, days_remaining=max(0.0, days_remaining), ) # ────────────────────────────────────────────────────────────── # Process killing + launcher package removal # ────────────────────────────────────────────────────────────── def _pacman_owner(path: str) -> str | None: """Return the pacman package name that owns *path*, or None.""" result = subprocess.run( [_PACMAN, "-Qo", path], capture_output=True, text=True, timeout=10, check=False, ) if result.returncode != 0: return None marker = " is owned by " if marker not in result.stdout: return None tail = result.stdout.split(marker, 1)[1].strip() return tail.split()[0] if tail else None def _uninstall_package(package: str) -> bool: """Remove *package* via pacman. Returns True on success or if absent.""" try: result = subprocess.run( [_SUDO, _PACMAN, "-R", "--noconfirm", package], capture_output=True, text=True, timeout=120, check=False, ) except (OSError, subprocess.SubprocessError): logger.exception("Failed to run pacman -R %s", package) return False if result.returncode == 0: return True if "target not found" in (result.stderr or "").lower(): return True logger.error( "pacman -R %s failed (rc=%d): %s", package, result.returncode, result.stderr[-500:] if result.stderr else "", ) return False def _kill_and_uninstall_launchers() -> list[tuple[int, str]]: """Kill running third-party launchers and uninstall their pacman package. Resolves each PID's ``/proc//exe`` target *before* sending SIGTERM, since the symlink stops resolving once the process has exited. Package removal is best-effort: launchers installed outside pacman (flatpak, AppImage, a wine prefix) simply have no owning package and are just killed again next tick, same as before this existed. """ pids = get_pids_by_process_names(LAUNCHER_PROCESS_NAMES) exe_paths: dict[int, str] = {} for pid in pids: with contextlib.suppress(OSError): exe_paths[pid] = str(Path(f"/proc/{pid}/exe").resolve(strict=True)) killed = kill_processes_by_name(LAUNCHER_PROCESS_NAMES) packages: set[str] = set() for pid, _name in killed: exe_path = exe_paths.get(pid) if exe_path is not None: package = _pacman_owner(exe_path) if package is not None: packages.add(package) for package in packages: if not _uninstall_package(package): logger.warning( "Total block: failed to uninstall launcher package %s", package ) return killed def _kill_steam_and_launchers() -> list[tuple[int, str]]: """Kill Steam client and known third-party launcher processes.""" steam_killed = kill_processes_by_name(STEAM_CLIENT_PROCESS_NAMES) launcher_killed = _kill_and_uninstall_launchers() return steam_killed + launcher_killed # ────────────────────────────────────────────────────────────── # Steam package removal # ────────────────────────────────────────────────────────────── def _is_package_installed(package: str) -> bool: """Return True if *package* is currently installed via pacman.""" result = subprocess.run( [_PACMAN, "-Qi", package], capture_output=True, timeout=10, check=False, ) return result.returncode == 0 def _is_steam_installed() -> bool: """Return True if the ``steam`` pacman package is currently installed.""" return _is_package_installed(_STEAM_PACKAGE) def _uninstall_steam_package() -> bool: """Remove the ``steam`` pacman package. Returns True on success or if it was already absent. """ return _uninstall_package(_STEAM_PACKAGE) def _uninstall_proton_helpers() -> list[str]: """Uninstall known Proton-management helper packages that are present. Returns the subset of :data:`_PROTON_HELPER_PACKAGES` that were actually installed and successfully removed (for logging), not the full fixed list. """ removed: list[str] = [] for package in _PROTON_HELPER_PACKAGES: if not _is_package_installed(package): continue if _uninstall_package(package): removed.append(package) else: logger.warning("Total block: failed to uninstall proton helper %s", package) return removed def _remove_steam_remnants() -> list[str]: """Delete the curated Steam/Proton filesystem remnants that exist. Symlinks are unlinked directly rather than following them into :func:`shutil.rmtree`, since e.g. ``~/.steampath`` -> a file inside ``~/.steam``, which this same pass may already have removed. """ removed: list[str] = [] for path in _STEAM_REMNANT_PATHS: if not (path.is_symlink() or path.exists()): continue try: if path.is_symlink() or path.is_file(): path.unlink() else: shutil.rmtree(path) except OSError: logger.exception("Failed to remove steam remnant %s", path) continue removed.append(str(path)) return removed def _log_steam_purge(removed_paths: list[str], removed_packages: list[str]) -> None: """Append a timestamped record of a Steam/Proton purge to disk. A no-op when nothing was actually removed, so the log only grows on ticks that did real work (this runs every enforce tick while the block is active - see :func:`enforce_total_block_tick`). """ if not removed_paths and not removed_packages: return try: existing = json.loads(_STEAM_PURGE_LOG_FILE.read_text(encoding="utf-8")) if not isinstance(existing, list): existing = [] except (OSError, json.JSONDecodeError, ValueError): existing = [] existing.append( { "timestamp": datetime.now(timezone.utc).isoformat(), "removed_paths": removed_paths, "removed_packages": removed_packages, } ) _atomic_write(_STEAM_PURGE_LOG_FILE, json.dumps(existing, indent=2) + "\n") def _purge_steam_and_proton() -> None: """Remove curated Steam/Proton filesystem remnants and helper packages. Best-effort and re-run every enforce tick, same as the Steam-package reappearance check: a stat() per fixed path and a ``pacman -Qi`` per helper package are cheap even when there is nothing left to do. """ removed_paths = _remove_steam_remnants() removed_packages = _uninstall_proton_helpers() if removed_paths or removed_packages: logger.info( "Total block: purged steam path(s) %s, proton package(s) %s", removed_paths, removed_packages, ) _log_steam_purge(removed_paths, removed_packages) # ────────────────────────────────────────────────────────────── # Domain blocking (hosts + iptables) - separate from store_blocker's own # BLOCKED_DOMAINS/STEAM_ENFORCER state, so ending the total block never # touches normal config.block_store entries. # ────────────────────────────────────────────────────────────── def _apply_total_block_hosts() -> bool: """Append the total-block domain block to /etc/hosts, if not present.""" try: content = HOSTS_FILE.read_text(encoding="utf-8") except OSError: logger.exception("Failed to read /etc/hosts") return False if _HOSTS_BLOCK_BEGIN in content: return True block_lines = [_HOSTS_BLOCK_BEGIN] block_lines += [ f"{_NULL_ROUTE_IP} {domain}\n" for domain in _ALL_TOTAL_BLOCK_DOMAINS ] block_lines.append(_HOSTS_BLOCK_END) new_content = content if content.endswith("\n") else content + "\n" new_content += "".join(block_lines) try: _disable_hosts_protection() _sudo_write_hosts(new_content) except (OSError, subprocess.SubprocessError): logger.exception("Failed to write total-block hosts entries") return False finally: _enable_hosts_protection() return True def _remove_total_block_hosts() -> bool: """Remove the total-block domain block from /etc/hosts, if present.""" try: content = HOSTS_FILE.read_text(encoding="utf-8") except OSError: logger.exception("Failed to read /etc/hosts") return False if _HOSTS_BLOCK_BEGIN not in content: return True start = content.index(_HOSTS_BLOCK_BEGIN) end_marker_at = content.index(_HOSTS_BLOCK_END, start) end = end_marker_at + len(_HOSTS_BLOCK_END) new_content = content[:start] + content[end:] try: _disable_hosts_protection() _sudo_write_hosts(new_content) except (OSError, subprocess.SubprocessError): logger.exception("Failed to remove total-block hosts entries") return False finally: _enable_hosts_protection() return True def _load_cached_ips() -> set[str]: """Return the accumulated set of previously-resolved total-block IPs.""" if not _IPTABLES_IP_CACHE_FILE.exists(): return set() try: data = json.loads(_IPTABLES_IP_CACHE_FILE.read_text(encoding="utf-8")) except (json.JSONDecodeError, OSError, ValueError): return set() if not isinstance(data, list): return set() return {str(ip) for ip in data} def _save_cached_ips(ips: set[str]) -> None: """Persist the accumulated total-block IP set to disk.""" _atomic_write(_IPTABLES_IP_CACHE_FILE, json.dumps(sorted(ips)) + "\n") def _iptables_chain_intact(expected_ips: set[str]) -> bool: """Cheap check for whether the chain and its OUTPUT hook are intact. One `-S` + one `-C` call (two forks), versus the ~30 forks a full rebuild costs - this is what keeps :func:`_apply_total_block_iptables` from re-resolving DNS and re-forking a subprocess per IP on every 3-second enforce tick. """ listing = subprocess.run( [_SUDO, _IPTABLES, "-S", IPTABLES_CHAIN], capture_output=True, text=True, timeout=5, check=False, ) if listing.returncode != 0: return False current_ips: set[str] = set() for line in listing.stdout.splitlines(): parts = line.split() if "-d" in parts: idx = parts.index("-d") if idx + 1 < len(parts): current_ips.add(parts[idx + 1].split("/")[0]) if not expected_ips.issubset(current_ips): return False hook = subprocess.run( [_SUDO, _IPTABLES, "-C", "OUTPUT", "-j", IPTABLES_CHAIN], capture_output=True, timeout=5, check=False, ) return hook.returncode == 0 def _apply_total_block_iptables() -> bool: """Ensure the total-block iptables chain blocks the known domain IPs. Resolves domains and (re)builds the chain only when a cheap check (:func:`_iptables_chain_intact`) shows it's actually needed - an already-intact chain returns immediately. This matters for two reasons: re-resolving via DNS every enforce tick (every 3s) would otherwise fork ~30 subprocesses/tick indefinitely for a multi-day block, and once /etc/hosts's entries take effect, these same domains resolve to 0.0.0.0 locally, which would collapse a from-scratch rebuild to that one trivial address and silently drop the real upstream IPs blocked on the first, pre-hosts-block resolution - resolving only when actually needed keeps the accumulated IP cache from growing unboundedly too. Callers MUST call this before :func:`_apply_total_block_hosts` the first time (see :func:`start_total_block`): once the hosts entries are in place, DNS resolution for every blocked domain returns 0.0.0.0 right here on this machine, and no real upstream IP is ever learned. """ cached = _load_cached_ips() if cached and _iptables_chain_intact(cached): return True resolved_ips: set[str] = set() try: subprocess.run( [_SUDO, _IPTABLES, "-N", IPTABLES_CHAIN], capture_output=True, timeout=5, check=False, ) subprocess.run( [_SUDO, _IPTABLES, "-F", IPTABLES_CHAIN], capture_output=True, timeout=5, check=True, ) for domain in _ALL_TOTAL_BLOCK_DOMAINS: with contextlib.suppress(socket.gaierror): for _, _, _, _, addr in socket.getaddrinfo(domain, 443, socket.AF_INET): resolved_ips.add(str(addr[0])) blocked_ips = (cached | resolved_ips) - {_NULL_ROUTE_IP} _save_cached_ips(blocked_ips) for ip in blocked_ips: subprocess.run( [_SUDO, _IPTABLES, "-A", IPTABLES_CHAIN, "-d", ip, "-j", "DROP"], capture_output=True, timeout=5, check=True, ) result = subprocess.run( [_SUDO, _IPTABLES, "-C", "OUTPUT", "-j", IPTABLES_CHAIN], capture_output=True, timeout=5, check=False, ) if result.returncode != 0: subprocess.run( [_SUDO, _IPTABLES, "-I", "OUTPUT", "-j", IPTABLES_CHAIN], capture_output=True, timeout=5, check=True, ) except (OSError, subprocess.SubprocessError): logger.exception("Failed to apply total-block iptables rules") return False else: logger.info( "Total block: %d domain IP(s) blocked via iptables.", len(blocked_ips) ) return True def _remove_total_block_iptables() -> bool: """Remove the total-block iptables chain and its OUTPUT hook.""" try: subprocess.run( [_SUDO, _IPTABLES, "-D", "OUTPUT", "-j", IPTABLES_CHAIN], capture_output=True, timeout=5, check=False, ) subprocess.run( [_SUDO, _IPTABLES, "-F", IPTABLES_CHAIN], capture_output=True, timeout=5, check=False, ) subprocess.run( [_SUDO, _IPTABLES, "-X", IPTABLES_CHAIN], capture_output=True, timeout=5, check=False, ) except (OSError, subprocess.SubprocessError): logger.exception("Failed to remove total-block iptables rules") return False else: _IPTABLES_IP_CACHE_FILE.unlink(missing_ok=True) return True # ────────────────────────────────────────────────────────────── # Public lifecycle API # ────────────────────────────────────────────────────────────── def start_total_block(days: int) -> bool: """Start a total gaming block for *days* days. Registers the package-block lock (bind-mounted, tamper-resistant) via guard-lib first - that is the actual enforcement mechanism and must succeed for the block to be considered active. Killing processes, uninstalling Steam, and applying domain blocks are best-effort follow-up steps (logged on failure, re-attempted every enforce tick via :func:`enforce_total_block_tick`), since none of them being instantly perfect should prevent the lock itself from engaging. Returns: True if the package-block lock was successfully registered. """ result = subprocess.run( [ _SUDO, _GUARDCTL, "package-block", "start", _PACKAGE_BLOCK_NAME, "--package", _STEAM_PACKAGE, "--lock-file", str(TOTAL_BLOCK_LOCK_FILE), "--days", str(days), "--bind-mount", ], capture_output=True, text=True, timeout=30, check=False, ) if result.returncode != 0: logger.error("Failed to start package-block lock: %s", result.stderr) return False killed = _kill_steam_and_launchers() if killed: logger.info("Total block: killed %d process(es): %s", len(killed), killed) if not _uninstall_steam_package(): logger.warning("Total block: failed to uninstall steam (will retry each tick)") _purge_steam_and_proton() # iptables MUST be applied before hosts: it resolves real upstream IPs, # and once the hosts block is written, local resolution for these same # domains collapses to 0.0.0.0 (see _apply_total_block_iptables). if not _apply_total_block_iptables(): logger.warning("Total block: failed to apply iptables rules") if not _apply_total_block_hosts(): logger.warning("Total block: failed to apply hosts entries") flush_dns_cache() return True def enforce_total_block_tick() -> None: """Re-assert the total block. Called every enforce-loop iteration while :func:`is_total_block_active` is True. """ _kill_steam_and_launchers() if _is_steam_installed(): logger.warning("Steam reappeared during total block - removing again") _uninstall_steam_package() _purge_steam_and_proton() _apply_total_block_iptables() _apply_total_block_hosts() def end_total_block_cleanup() -> None: """Clean up after the total-block lock has naturally expired. Ends the package-block lock (guard-lib), removes total-block-specific hosts/iptables entries, leaving normal ``config.block_store`` state untouched. Does *not* reinstall Steam or restore killed processes - the user is free to reinstall/relaunch once the block has expired. """ result = subprocess.run( [_SUDO, _GUARDCTL, "package-block", "end", _PACKAGE_BLOCK_NAME], capture_output=True, text=True, timeout=30, check=False, ) if result.returncode != 0: logger.warning( "package-block end failed (may already be ended): %s", result.stderr ) if not _remove_total_block_hosts(): logger.warning("Failed to remove total-block hosts entries") if not _remove_total_block_iptables(): logger.warning("Failed to remove total-block iptables rules") flush_dns_cache() logger.info("Total gaming block ended - normal enforcement resumes.")