los-bootstrap 0.9.0__py3-none-any.whl

los_bootstrap/__init__.py

@@ -0,0 +1,3 @@
+"""los-bootstrap: CLI-first post-install assistant for LineageOS."""
+
+__version__ = "0.9.0"

los_bootstrap/adb.py

@@ -0,0 +1,160 @@
+"""Thin, testable wrapper around the `adb` binary.
+
+All ADB IO funnels through `Adb`. Tests inject a fake `runner` so no real
+`adb` is required. Read-only methods are always available. Mutating
+methods (`install_apk`, `setting_put`) are used by the Phase 2 applier
+and only ever run after the user passes `--confirm`.
+"""
+
+from __future__ import annotations
+
+import shlex
+import shutil
+import subprocess
+from dataclasses import dataclass
+from typing import Callable, Optional, Sequence
+
+
+CommandRunner = Callable[[Sequence[str]], "AdbResult"]
+
+
+class AdbNotFoundError(RuntimeError):
+    """Raised when the `adb` binary cannot be located on PATH."""
+
+
+class AdbCommandError(RuntimeError):
+    """Raised when an `adb` invocation exits non-zero."""
+
+
+@dataclass(frozen=True)
+class AdbResult:
+    returncode: int
+    stdout: str
+    stderr: str
+
+
+@dataclass(frozen=True)
+class AdbDevice:
+    serial: str
+    state: str  # "device", "unauthorized", "offline", ...
+
+    @property
+    def ready(self) -> bool:
+        return self.state == "device"
+
+
+def _default_runner(argv: Sequence[str]) -> AdbResult:
+    if shutil.which(argv[0]) is None:
+        raise AdbNotFoundError(f"`{argv[0]}` not found on PATH")
+    proc = subprocess.run(argv, capture_output=True, text=True, check=False)
+    return AdbResult(proc.returncode, proc.stdout, proc.stderr)
+
+
+class Adb:
+    """Wrapper around `adb`. Inject `runner` in tests."""
+
+    def __init__(
+        self,
+        serial: Optional[str] = None,
+        runner: Optional[CommandRunner] = None,
+        binary: str = "adb",
+    ) -> None:
+        self.serial = serial
+        self.binary = binary
+        self._run = runner or _default_runner
+
+    def _argv(self, *args: str) -> list[str]:
+        argv = [self.binary]
+        if self.serial:
+            argv += ["-s", self.serial]
+        argv += list(args)
+        return argv
+
+    def raw(self, *args: str) -> AdbResult:
+        return self._run(self._argv(*args))
+
+    def shell(self, command: str) -> str:
+        result = self.raw("shell", command)
+        if result.returncode != 0:
+            raise AdbCommandError(
+                f"adb shell `{command}` failed: {result.stderr.strip()}"
+            )
+        return result.stdout
+
+    def list_devices(self) -> list[AdbDevice]:
+        result = self.raw("devices")
+        if result.returncode != 0:
+            raise AdbCommandError(f"adb devices failed: {result.stderr.strip()}")
+        return parse_devices(result.stdout)
+
+    def getprop(self, key: str) -> str:
+        return self.shell(f"getprop {key}").strip()
+
+    def package_installed(self, package: str) -> bool:
+        # `pm list packages <pkg>` returns lines of form `package:<name>`.
+        out = self.shell(f"pm list packages {package}")
+        for line in out.splitlines():
+            if line.strip() == f"package:{package}":
+                return True
+        return False
+
+    def setting_get(self, namespace: str, key: str) -> str:
+        """Return the current value of `settings get <namespace> <key>`.
+
+        The `settings` CLI prints `null` when a key is unset; we
+        normalize that to an empty string for easier comparison.
+        """
+        out = self.shell(f"settings get {namespace} {key}").strip()
+        return "" if out == "null" else out
+
+    def install_apk(self, apk_path: str, replace: bool = True) -> str:
+        """Install an APK from a local path. Mutating; applier-only."""
+        args = ["install"]
+        if replace:
+            args.append("-r")
+        args.append(apk_path)
+        result = self.raw(*args)
+        if result.returncode != 0:
+            raise AdbCommandError(
+                f"adb install {apk_path} failed: "
+                f"{(result.stderr or result.stdout).strip()}"
+            )
+        return result.stdout
+
+    def setting_put(self, namespace: str, key: str, value: str) -> None:
+        """Run `settings put <namespace> <key> <value>`. Mutating."""
+        self.shell(
+            f"settings put {namespace} {key} {shlex.quote(value)}"
+        )
+
+    def reboot(self, target: Optional[str] = None) -> None:
+        """Reboot device, optionally to 'bootloader' or 'recovery'. Mutating."""
+        args = ["reboot"]
+        if target:
+            args.append(target)
+        result = self.raw(*args)
+        if result.returncode != 0:
+            raise AdbCommandError(f"adb reboot failed: {result.stderr.strip()}")
+
+    def sideload(self, zip_path: str) -> str:
+        """Run `adb sideload <zip>`. Device must be in recovery sideload mode. Mutating."""
+        result = self.raw("sideload", zip_path)
+        if result.returncode != 0:
+            raise AdbCommandError(
+                f"adb sideload {zip_path} failed: "
+                f"{(result.stderr or result.stdout).strip()}"
+            )
+        return result.stdout
+
+
+def parse_devices(stdout: str) -> list[AdbDevice]:
+    """Parse the output of `adb devices`."""
+    devices: list[AdbDevice] = []
+    for line in stdout.splitlines():
+        line = line.strip()
+        if not line or line.startswith("List of devices"):
+            continue
+        parts = line.split()
+        if len(parts) >= 2:
+            devices.append(AdbDevice(serial=parts[0], state=parts[1]))
+    return devices

los_bootstrap/apply.py

@@ -0,0 +1,187 @@
+"""Execute a `Plan`.
+
+The applier only ever runs after the user passes `--confirm`. Each
+executable step is written to stdout before it runs so the user has a
+last chance to spot something they did not expect.
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+import tempfile
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional, TextIO
+
+from .adb import Adb, AdbCommandError
+from . import fetch
+from .fetch import FetchError
+from .plan import Plan, PlanStep, StepKind
+
+
+@dataclass
+class StepResult:
+    step: PlanStep
+    status: str  # "ok" | "skipped" | "manual" | "missing_apk" | "error"
+    detail: str = ""
+
+
+@dataclass
+class ApplyResult:
+    profile_name: str
+    results: list[StepResult] = field(default_factory=list)
+
+    def counts(self) -> dict[str, int]:
+        out: dict[str, int] = {}
+        for r in self.results:
+            out[r.status] = out.get(r.status, 0) + 1
+        return out
+
+    def had_errors(self) -> bool:
+        return any(r.status == "error" for r in self.results)
+
+
+def _extract_apk_path(command: str) -> Optional[Path]:
+    # `adb install -r /abs/path/to.apk` — pull out the last token.
+    m = re.match(r"^adb install(?:\s+-r)?\s+(.+)$", command)
+    if not m:
+        return None
+    return Path(m.group(1))
+
+
+def _extract_setting(command: str) -> Optional[tuple[str, str, str]]:
+    m = re.match(
+        r"^adb shell settings put (\w+) (\S+) (.+)$",
+        command,
+    )
+    if not m:
+        return None
+    return m.group(1), m.group(2), m.group(3)
+
+
+def apply_plan(
+    adb: Adb,
+    plan: Plan,
+    *,
+    dry_run: bool = False,
+    out: TextIO = sys.stdout,
+    apk_dir: Optional[Path] = None,
+) -> ApplyResult:
+    """Run the executable steps in `plan` against `adb`.
+
+    The caller is responsible for gating on `--confirm`. `dry_run`
+    prints the commands without running them. `apk_dir` is used as the
+    cache directory for downloaded APKs; a temp dir is created if needed.
+    """
+    result = ApplyResult(profile_name=plan.profile_name)
+    _dl_dir: Optional[Path] = apk_dir  # resolved on first download if still None
+
+    out.write(f"Applying profile: {plan.profile_name}\n")
+    if dry_run:
+        out.write("(dry run — no commands will be executed)\n")
+    out.write("\n")
+
+    for i, step in enumerate(plan.steps, 1):
+        prefix = f"[{i:2d}/{len(plan.steps)}]"
+
+        if step.kind == StepKind.SKIP:
+            out.write(f"{prefix} skip   : {step.summary}\n")
+            result.results.append(
+                StepResult(step=step, status="skipped", detail=step.skipped_reason or "")
+            )
+            continue
+
+        if step.kind == StepKind.MANUAL_INSTALL:
+            out.write(f"{prefix} manual : {step.summary}\n")
+            result.results.append(
+                StepResult(step=step, status="manual", detail="user must install via store")
+            )
+            continue
+
+        if step.kind == StepKind.INSTALL_APK:
+            if step.download_url:
+                if dry_run:
+                    out.write(f"{prefix} fetch  : {step.download_url} (dry run)\n")
+                    result.results.append(StepResult(step=step, status="ok", detail="dry-run"))
+                    continue
+                if _dl_dir is None:
+                    _dl_dir = Path(tempfile.mkdtemp())
+                    out.write(f"note: downloading APKs to {_dl_dir}\n")
+                out.write(f"{prefix} fetch  : {step.download_url}\n")
+                try:
+                    apk_path = fetch.download_apk(step.download_url, _dl_dir)
+                except FetchError as exc:
+                    out.write(f"        error  : {exc}\n")
+                    result.results.append(StepResult(step=step, status="error", detail=str(exc)))
+                    continue
+                out.write(f"        run    : adb install -r {apk_path}\n")
+                try:
+                    stdout = adb.install_apk(str(apk_path))
+                    result.results.append(StepResult(step=step, status="ok", detail=stdout.strip()))
+                except AdbCommandError as exc:
+                    out.write(f"        error  : {exc}\n")
+                    result.results.append(StepResult(step=step, status="error", detail=str(exc)))
+                continue
+
+            if step.missing_apk_path is not None or step.command is None:
+                out.write(
+                    f"{prefix} skip   : {step.summary} "
+                    f"(missing APK: {step.missing_apk_path})\n"
+                )
+                result.results.append(
+                    StepResult(
+                        step=step,
+                        status="missing_apk",
+                        detail=step.missing_apk_path or "no command",
+                    )
+                )
+                continue
+            apk_path = _extract_apk_path(step.command)
+            out.write(f"{prefix} run    : {step.command}\n")
+            if dry_run or apk_path is None:
+                result.results.append(
+                    StepResult(step=step, status="ok", detail="dry-run")
+                )
+                continue
+            try:
+                stdout = adb.install_apk(str(apk_path))
+                result.results.append(
+                    StepResult(step=step, status="ok", detail=stdout.strip())
+                )
+            except AdbCommandError as exc:
+                out.write(f"        error  : {exc}\n")
+                result.results.append(
+                    StepResult(step=step, status="error", detail=str(exc))
+                )
+            continue
+
+        if step.kind == StepKind.SET_SETTING:
+            if step.command is None:
+                continue
+            parsed = _extract_setting(step.command)
+            out.write(f"{prefix} run    : {step.command}\n")
+            if dry_run or parsed is None:
+                result.results.append(
+                    StepResult(step=step, status="ok", detail="dry-run")
+                )
+                continue
+            namespace, key, value = parsed
+            try:
+                adb.setting_put(namespace, key, value)
+                result.results.append(StepResult(step=step, status="ok"))
+            except AdbCommandError as exc:
+                out.write(f"        error  : {exc}\n")
+                result.results.append(
+                    StepResult(step=step, status="error", detail=str(exc))
+                )
+            continue
+
+    counts = result.counts()
+    out.write("\n")
+    out.write(
+        "Done: "
+        + ", ".join(f"{v} {k}" for k, v in sorted(counts.items()))
+        + ".\n"
+    )
+    return result

los_bootstrap/audit/__init__.py

@@ -0,0 +1,6 @@
+"""Audit module: read-only privacy/degoogle inspection."""
+
+from .models import AuditFinding, AuditReport, Severity
+from .checks import run_audit
+
+__all__ = ["AuditFinding", "AuditReport", "Severity", "run_audit"]

los_bootstrap/audit/checks.py

@@ -0,0 +1,226 @@
+"""Individual audit checks plus the orchestrator.
+
+Each check takes the `Adb` wrapper plus already-collected `DeviceFacts`
+and returns zero or more `AuditFinding`s. Checks must be read-only.
+"""
+
+from __future__ import annotations
+
+from typing import Callable, Iterable
+
+from ..adb import Adb
+from ..device import DeviceFacts
+from .models import AuditFinding, AuditReport, Severity
+
+
+# Packages we care about. Keep this list short and curated; long lists
+# rot fast and add noise. Phase 2 can move this to a YAML profile.
+GMS_PACKAGE = "com.google.android.gms"
+GSF_PACKAGE = "com.google.android.gsf"
+
+COMMON_GOOGLE_PACKAGES = (
+    "com.android.vending",            # Play Store
+    "com.google.android.apps.maps",   # Maps
+    "com.google.android.gm",          # Gmail
+    "com.google.android.youtube",     # YouTube
+    "com.google.android.inputmethod.latin",  # Gboard
+)
+
+
+CheckFn = Callable[[Adb, DeviceFacts], Iterable[AuditFinding]]
+
+
+def check_lineage_identity(_adb: Adb, facts: DeviceFacts) -> Iterable[AuditFinding]:
+    if facts.is_lineage:
+        yield AuditFinding(
+            check="rom.lineage",
+            title="LineageOS detected",
+            severity=Severity.INFO,
+            detail=f"ro.lineage.version = {facts.lineage_version!r}.",
+        )
+    else:
+        yield AuditFinding(
+            check="rom.lineage",
+            title="Not a LineageOS build",
+            severity=Severity.INFO,
+            detail=(
+                "No ro.lineage.version property found. los-bootstrap will "
+                "still work on AOSP-derived ROMs, but device-specific "
+                "guidance assumes LineageOS conventions."
+            ),
+        )
+
+
+def check_gms(adb: Adb, _facts: DeviceFacts) -> Iterable[AuditFinding]:
+    if adb.package_installed(GMS_PACKAGE):
+        yield AuditFinding(
+            check="gms.present",
+            title="Google Mobile Services is installed",
+            severity=Severity.WARN,
+            detail=(
+                f"{GMS_PACKAGE} is installed. This indicates a GApps build "
+                "or microG. If you intended a fully degoogled setup, "
+                "investigate which build was flashed."
+            ),
+            recommendation=(
+                "If unintended: reflash a vanilla LineageOS build. If this "
+                "is microG, ignore this finding."
+            ),
+        )
+    else:
+        yield AuditFinding(
+            check="gms.present",
+            title="No Google Mobile Services",
+            severity=Severity.OK,
+            detail=f"{GMS_PACKAGE} is not installed. Degoogled-friendly.",
+        )
+
+
+def check_gsf(adb: Adb, _facts: DeviceFacts) -> Iterable[AuditFinding]:
+    if adb.package_installed(GSF_PACKAGE):
+        yield AuditFinding(
+            check="gsf.present",
+            title="Google Services Framework is installed",
+            severity=Severity.WARN,
+            detail=f"{GSF_PACKAGE} is installed.",
+            recommendation="See GMS guidance — same root cause.",
+        )
+
+
+def check_common_google_packages(adb: Adb, _facts: DeviceFacts) -> Iterable[AuditFinding]:
+    found = [p for p in COMMON_GOOGLE_PACKAGES if adb.package_installed(p)]
+    if not found:
+        yield AuditFinding(
+            check="google.client_packages",
+            title="No common Google client packages installed",
+            severity=Severity.OK,
+            detail="None of the curated Google client packages were detected.",
+        )
+        return
+    yield AuditFinding(
+        check="google.client_packages",
+        title=f"{len(found)} Google client package(s) installed",
+        severity=Severity.WARN,
+        detail="Detected: " + ", ".join(found),
+        recommendation=(
+            "Consider replacements: F-Droid + Aurora Store, Organic Maps, "
+            "K-9 Mail / FairEmail, NewPipe / LibreTube, FlorisBoard / "
+            "HeliBoard."
+        ),
+    )
+
+
+def check_adb_tcp(_adb: Adb, facts: DeviceFacts) -> Iterable[AuditFinding]:
+    port = facts.adb_tcp_port
+    if port and port.strip() and port != "0":
+        yield AuditFinding(
+            check="adb.tcp",
+            title="ADB-over-network is enabled",
+            severity=Severity.HIGH,
+            detail=(
+                f"service.adb.tcp.port = {port!r}. The device is exposing "
+                "ADB on the network. Anyone on the same network can attempt "
+                "to connect."
+            ),
+            recommendation=(
+                "Disable wireless ADB in Developer options unless you "
+                "actively need it on a trusted network."
+            ),
+        )
+    else:
+        yield AuditFinding(
+            check="adb.tcp",
+            title="ADB-over-network is not enabled",
+            severity=Severity.OK,
+            detail="service.adb.tcp.port is unset.",
+        )
+
+
+def check_private_dns(adb: Adb, _facts: DeviceFacts) -> Iterable[AuditFinding]:
+    mode = adb.shell("settings get global private_dns_mode").strip()
+    specifier = adb.shell("settings get global private_dns_specifier").strip()
+    if mode in ("", "null", "off"):
+        yield AuditFinding(
+            check="dns.private",
+            title="Private DNS is off",
+            severity=Severity.WARN,
+            detail=(
+                f"global private_dns_mode = {mode!r}. DNS lookups go to "
+                "whatever the network hands you, in cleartext."
+            ),
+            recommendation=(
+                "Set Private DNS to a hostname (DoT) like dns.quad9.net "
+                "in Settings > Network > Private DNS."
+            ),
+        )
+        return
+    if mode == "opportunistic":
+        yield AuditFinding(
+            check="dns.private",
+            title="Private DNS is opportunistic",
+            severity=Severity.INFO,
+            detail=(
+                "Android will use DoT when the upstream resolver supports "
+                "it, otherwise fall back to cleartext."
+            ),
+        )
+        return
+    if mode == "hostname":
+        yield AuditFinding(
+            check="dns.private",
+            title="Private DNS is enforced (DoT)",
+            severity=Severity.OK,
+            detail=(
+                f"global private_dns_mode = 'hostname', specifier = "
+                f"{specifier or '(unset)'!r}."
+            ),
+        )
+        return
+    yield AuditFinding(
+        check="dns.private",
+        title=f"Private DNS in unknown mode {mode!r}",
+        severity=Severity.INFO,
+        detail="Unrecognised private_dns_mode value; not interpreting.",
+    )
+
+
+def check_screen_lock(adb: Adb, _facts: DeviceFacts) -> Iterable[AuditFinding]:
+    # `lockscreen.disabled` true means no lock at all on many AOSP ROMs.
+    raw = adb.shell("settings get secure lockscreen.disabled").strip()
+    disabled = raw == "1"
+    if disabled:
+        yield AuditFinding(
+            check="lockscreen.present",
+            title="Screen lock is disabled",
+            severity=Severity.HIGH,
+            detail="settings secure lockscreen.disabled = 1.",
+            recommendation=(
+                "Set a PIN, password, or passphrase. Without a screen lock, "
+                "device encryption keys at rest are weakened."
+            ),
+        )
+    else:
+        yield AuditFinding(
+            check="lockscreen.present",
+            title="Screen lock appears enabled",
+            severity=Severity.OK,
+            detail=f"settings secure lockscreen.disabled = {raw!r}.",
+        )
+
+
+CHECKS: tuple[CheckFn, ...] = (
+    check_lineage_identity,
+    check_gms,
+    check_gsf,
+    check_common_google_packages,
+    check_adb_tcp,
+    check_private_dns,
+    check_screen_lock,
+)
+
+
+def run_audit(adb: Adb, facts: DeviceFacts) -> AuditReport:
+    findings: list[AuditFinding] = []
+    for check in CHECKS:
+        findings.extend(check(adb, facts))
+    return AuditReport(findings=tuple(findings))

los_bootstrap/audit/models.py

@@ -0,0 +1,34 @@
+"""Data models for audit findings."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Optional
+
+
+class Severity(str, Enum):
+    INFO = "info"
+    OK = "ok"
+    WARN = "warn"
+    HIGH = "high"
+
+
+@dataclass(frozen=True)
+class AuditFinding:
+    check: str  # short id, e.g. "gms.present"
+    title: str  # human-readable
+    severity: Severity
+    detail: str  # one-paragraph explanation
+    recommendation: Optional[str] = None  # actionable hint for `recommend`
+
+
+@dataclass(frozen=True)
+class AuditReport:
+    findings: tuple[AuditFinding, ...] = field(default_factory=tuple)
+
+    def by_severity(self, sev: Severity) -> tuple[AuditFinding, ...]:
+        return tuple(f for f in self.findings if f.severity == sev)
+
+    def has_concerns(self) -> bool:
+        return any(f.severity in (Severity.WARN, Severity.HIGH) for f in self.findings)

los_bootstrap/bootstrap.py

@@ -0,0 +1,33 @@
+"""Phase 1 bootstrap recommendations.
+
+Phase 1 is non-binding: we surface suggestions derived from audit
+findings. We do not install anything. Phase 2 turns this into an
+applyable plan.
+"""
+
+from __future__ import annotations
+
+from .audit.models import AuditReport, Severity
+
+
+GENERIC_TIPS: tuple[str, ...] = (
+    "Install F-Droid (https://f-droid.org) — verify the APK signature.",
+    "Install Aurora Store from F-Droid for proprietary apps without a Google account.",
+    "Set up a non-Google DNS (e.g. NextDNS, Quad9) under Settings > Network > Private DNS.",
+    "Set automatic time/timezone source to NITZ-only or NTP, not Google.",
+    "Disable connectivity check or point it at a non-Google endpoint if your ROM supports it.",
+)
+
+
+def recommendations(report: AuditReport) -> list[str]:
+    """Map findings to short, actionable suggestions."""
+    out: list[str] = []
+    seen: set[str] = set()
+    for finding in report.findings:
+        if finding.severity in (Severity.WARN, Severity.HIGH) and finding.recommendation:
+            if finding.check not in seen:
+                out.append(f"[{finding.severity.value}] {finding.title}: {finding.recommendation}")
+                seen.add(finding.check)
+    out.append("--- general tips ---")
+    out.extend(GENERIC_TIPS)
+    return out

los_bootstrap/camera/__init__.py

@@ -0,0 +1,35 @@
+"""Camera / GCam port profiles — Phase 5.
+
+Public surface:
+    CAMERA_PROFILES             — tuple of CameraProfile
+    find_camera_profile(str)    -> CameraProfile | None
+    render_profile_list()       -> str
+    render_profile(profile)     -> str
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from .models import CameraPort, CameraProfile, XmlConfig
+from .profiles import CAMERA_PROFILES
+from .report import render_profile, render_profile_list
+
+__all__ = [
+    "CAMERA_PROFILES",
+    "CameraPort",
+    "CameraProfile",
+    "XmlConfig",
+    "find_camera_profile",
+    "render_profile",
+    "render_profile_list",
+]
+
+
+def find_camera_profile(codename: str) -> Optional[CameraProfile]:
+    """Return the camera profile for the given device codename, or None."""
+    codename_lower = codename.lower()
+    for profile in CAMERA_PROFILES:
+        if profile.codename.lower() == codename_lower:
+            return profile
+    return None