mobster-cli 0.4.3__py3-none-any.whl

mobile_agent/wireless/probe.py

@@ -0,0 +1,322 @@
+"""`mobster wifi probe`: the owner's probe (SPEC §3.7, owner test plan items 1-4), whose result decides the release."""
+
+import os
+import signal
+import socket
+import subprocess
+import time
+from functools import partial
+from pathlib import Path
+
+from ..devices import wda_url
+from ..transport import request_once
+from . import devicectl, exposure, network
+from .relay import Relay, check_target
+
+OK, WARN, FAIL, INFO = "ok", "warn", "fail", "info"
+START_WAIT = 120.0
+
+
+def http_status(port, timeout=3.0):
+    """WebDriverAgent's /status through 127.0.0.1:``port``: its JSON value, or None."""
+    try:
+        value = request_once(wda_url(port), "GET", "/status", timeout=timeout).get("value")
+    except Exception:
+        return None
+    return value if isinstance(value, dict) else None
+
+
+def stream_answers(port, timeout=3.0):
+    """Whether the MJPEG port behind 127.0.0.1:``port`` sends anything back to a request."""
+    try:
+        with socket.create_connection(("127.0.0.1", port), timeout) as sock:
+            sock.sendall(b"GET / HTTP/1.1\r\nHost: 127.0.0.1\r\n\r\n")
+            return bool(sock.recv(1))
+    except OSError:
+        return False
+
+
+def usbmux_network(udid, runner=None):
+    """Whether ``idevice_id -n`` (read-only) lists the phone over the network: True, False, or None (no tool)."""
+    from ..mac_tools import tool
+    listing = tool("idevice_id")
+    if not listing:
+        return None
+    output = (runner or partial(network.read_output, timeout=5))([listing, "-n"])
+    if output is None:
+        return None
+    return udid.upper() in {line.strip().upper() for line in output.splitlines() if line.strip()}
+
+
+# It binds only 127.0.0.1, never enters a passcode, and changes nothing on the phone but --start's own helper.
+class Probe:
+    """One probe of one phone. ``steps``: [{"key", "state", "title", "detail"}]; ``fields``: what CoreDevice said."""
+
+    def __init__(self, *, udid, name, slot_port=None, data_dir=None, start=False, manager=None, out=None,
+                 network_check=None):
+        self.udid, self.name, self.slot_port = udid, name, slot_port
+        self.network_check = network_check
+        self.data_dir, self.start, self.manager = data_dir, start, manager
+        self.out = out
+        self.steps, self.fields, self.peer, self.address = [], {}, None, None
+
+    def step(self, key, state, title, detail=""):
+        item = {"key": key, "state": state, "title": title, "detail": detail}
+        self.steps.append(item)
+        if self.out is not None:
+            self.out(item)
+        return item
+
+    @property
+    def ok(self):
+        needed = {"coredevice", "tunnel", "wda", "lan"}
+        states = {item["key"]: item["state"] for item in self.steps}
+        return needed <= set(states) and all(states[key] == OK for key in needed)
+
+    def public(self):
+        return {"device": {"udid": self.udid, "name": self.name}, "ok": self.ok, "steps": self.steps,
+                "fields": self.fields, "tunnelAddress": self.address}
+
+    # -- the steps --------------------------------------------------------------------------------------------------
+
+    def run(self, usb_attached):
+        usb = usb_attached(self.udid)
+        self.step("usb", INFO, "USB", {True: "plugged in: unplug it to probe Wi-Fi", False: "not plugged in",
+                                       None: "couldn't tell"}[usb])
+        self._network()
+        if not self._coredevice():
+            return self
+        if not self._tunnel():
+            return self
+        self._readers()
+        wda = self._wda()
+        if not wda and self.start:
+            if self._launch():
+                wda = self._wda()
+        self._app_relay()
+        self._lan()
+        self._usbmux()
+        return self
+
+    def _network(self):
+        from .words import NETWORK_PROBLEMS, problem
+        try:
+            result = (self.network_check or network.peer_check)()
+        except Exception:  # noqa: BLE001
+            result = {"state": "unknown"}
+        state = result.get("state")
+        code = NETWORK_PROBLEMS.get(state)
+        if code:
+            found = problem(code, self.name)
+            self.step("network", WARN, "This Mac's network", f"{found['message']} {found['fix']}")
+        elif state == "ok":
+            self.step("network", OK, "This Mac's network", f"devices on it can see each other "
+                                                           f"({result.get('interface')})")
+        else:
+            self.step("network", INFO, "This Mac's network", {"offline": "this Mac isn't on a network"}.get(
+                state, "couldn't tell whether devices on it can see each other"))
+
+    def _coredevice(self):
+        try:
+            peers = devicectl.list_devices()
+        except devicectl.DevicectlError as error:
+            self.step("coredevice", FAIL, "CoreDevice", str(error))
+            return False
+        self.peer = peers.get(self.udid.upper())
+        if self.peer is None:
+            self.step("coredevice", FAIL, "CoreDevice", "doesn't list this iPhone at all. Pair it with the cable in "
+                                                        "Setup, then try again.")
+            return False
+        self.fields = dict(self.peer.fields)
+        seen = ", ".join(f"{key}={value}" for key, value in sorted(self.fields.items())
+                         if not isinstance(value, list)) or "no connection fields"
+        self.step("fields", INFO, "Fields CoreDevice reports", seen)
+        if self.peer.wired:
+            self.step("coredevice", WARN, "CoreDevice", "sees it on USB (transportType wired). Unplug it and probe "
+                                                        "again.")
+            return False
+        if not self.peer.network:
+            self.step("coredevice", FAIL, "CoreDevice", f"doesn't see it over the network (transportType "
+                                                        f"{self.peer.transport or 'missing'}). Turn on Wi-Fi with "
+                                                        "`mobster wifi on` with the cable, keep the phone unlocked "
+                                                        "and on the same Wi-Fi as this Mac.")
+            return False
+        self.step("coredevice", OK, "CoreDevice", "sees it over the network (transportType localNetwork"
+                  + (f", iOS {self.peer.os_version}" if self.peer.os_version else "") + ")")
+        return True
+
+    def _tunnel(self):
+        peer = self.peer
+        if peer.tunnel != "up":
+            try:
+                found = devicectl.bring_up(self.udid)
+                peer = found.get(self.udid.upper()) or peer
+                if peer.tunnel != "up":
+                    peer = devicectl.list_devices().get(self.udid.upper()) or peer
+            except devicectl.DevicectlError as error:
+                self.step("tunnel", FAIL, "Encrypted tunnel", f"couldn't be brought up: {error}")
+                return False
+        self.peer = peer
+        self.fields = dict(peer.fields) or self.fields
+        if peer.tunnel != "up":
+            self.step("tunnel", FAIL, "Encrypted tunnel", f"not up (tunnelState {peer.tunnel_state or 'missing'})")
+            return False
+        try:
+            address = check_target(peer.address)
+        except ValueError:
+            self.step("tunnel", FAIL, "Encrypted tunnel", f"up, but its address ({peer.address or 'missing'}) isn't "
+                                                          "an fd00::/8 tunnel address, so Mobster won't use it")
+            return False
+        interface, problem = network.tunnel_route(address)
+        if problem:
+            self.step("tunnel", FAIL, "Encrypted tunnel", f"up, but {problem}, so Mobster won't use it")
+            return False
+        self.address = address
+        self.step("tunnel", OK, "Encrypted tunnel", f"up, the phone's end is {address} (through {interface})")
+        return True
+
+    def _readers(self):
+        lines, clear = [], True
+        for name, understood in (("lockState", self._lock_line), ("apps", self._apps_line)):
+            try:
+                document = devicectl.run_json(["device", "info", name, "--device", self.udid], devicectl.APPS_TIMEOUT)
+                result = document.get("result") if isinstance(document, dict) else None
+                keys = ", ".join(sorted(result)) if isinstance(result, dict) else "no result"
+                line = understood(document)
+            except (devicectl.DevicectlError, RuntimeError) as error:
+                line, keys = str(error), "none"
+            if line is None:
+                clear = False
+                line = "unreadable"
+            lines.append(f"{name}: {line} (fields: {keys})")
+        self.step("readers", INFO if clear else WARN, "Reads through CoreDevice", "; ".join(lines))
+
+    @staticmethod
+    def _lock_line(document):
+        locked = devicectl.lock_state(document)
+        return None if locked is None else "locked" if locked else "unlocked"
+
+    @staticmethod
+    def _apps_line(document):
+        try:
+            return (
+                f"{len(devicectl.parse_apps(document))} user apps, {len(devicectl.parse_apps(document, 'system'))} "
+                "Apple apps")
+        except devicectl.DevicectlError:
+            return None
+
+    def _wda(self):
+        """WebDriverAgent on the tunnel address, through a relay on 127.0.0.1 (any free port)."""
+        relay = Relay(self.address, [(0, 8100), (0, 9100)], name="wifi-probe")
+        try:
+            relay.start()
+        except OSError as error:
+            self.step("wda", FAIL, "WebDriverAgent over the tunnel", f"the probe's relay couldn't start: {error}")
+            return False
+        try:
+            api, video = relay.ports
+            status = http_status(api)
+            if status is None:
+                self.step("wda", WARN, "WebDriverAgent over the tunnel",
+                          "doesn't answer on [tunnel]:8100 (yet). Start Mobster's helper over Wi-Fi: the Mac app "
+                          "with Wi-Fi for iPhones on, or this probe with --start.")
+                return False
+            ready = status.get("ready") is True
+            streams = stream_answers(video)
+            self.step("wda", OK if ready else WARN, "WebDriverAgent over the tunnel",
+                      f"/status answers through 127.0.0.1 ({'ready' if ready else 'not ready'}); video port "
+                      f"{'answers' if streams else 'does not answer'}")
+            return ready
+        finally:
+            relay.stop()
+
+    def _launch(self):
+        """--start: launch Mobster's helper over Wi-Fi for this probe, and wait for it."""
+        from ..device_manager import wifi_runner_command
+        from ..mac_tools import tool
+        from . import xctestrun
+        manager = self.manager
+        if manager is None or not manager.built():
+            self.step("runner", FAIL, "Mobster's helper over Wi-Fi", "isn't built for this iPhone. Set it up with "
+                                                                     "the cable first.")
+            return False
+        xcodebuild = tool("xcodebuild")
+        if not xcodebuild:
+            self.step("runner", FAIL, "Mobster's helper over Wi-Fi", "Xcode isn't installed or set up")
+            return False
+        try:
+            plan = xctestrun.write(manager.derived / "Build" / "Products", manager.derived / xctestrun.FOLDER,
+                                   self.address)
+        except (LookupError, ValueError) as error:
+            self.step("runner", FAIL, "Mobster's helper over Wi-Fi", str(error))
+            return False
+        log_path = Path(manager.logs) / "wifi-probe.log"
+        log_path.parent.mkdir(parents=True, exist_ok=True)
+        with open(log_path, "ab") as log:
+            process = subprocess.Popen(wifi_runner_command(xcodebuild, plan, self.udid), stdout=log,
+                                       stderr=subprocess.STDOUT, stdin=subprocess.DEVNULL, start_new_session=True,
+                                       env=manager.runner_env())
+        self._process = process
+        relay = Relay(self.address, [(0, 8100)], name="wifi-probe")
+        relay.start()
+        try:
+            deadline = time.monotonic() + START_WAIT
+            while time.monotonic() < deadline and process.poll() is None:
+                if (http_status(relay.ports[0], timeout=2) or {}).get("ready") is True:
+                    self.step("runner", OK, "Mobster's helper over Wi-Fi",
+                              f"started with USE_IP={self.address} (log: {log_path.name})")
+                    return True
+                time.sleep(2)
+        finally:
+            relay.stop()
+        self.step("runner", FAIL, "Mobster's helper over Wi-Fi",
+                  f"didn't answer within {int(START_WAIT)} s. See {log_path} for xcodebuild's output.")
+        return False
+
+    def stop_launched(self):
+        process = getattr(self, "_process", None)
+        if process is None or process.poll() is not None:
+            return
+        for sig in (signal.SIGTERM, signal.SIGKILL):
+            try:
+                os.killpg(process.pid, sig)
+                process.wait(timeout=5)
+                return
+            except (ProcessLookupError, PermissionError):
+                return
+            except subprocess.TimeoutExpired:
+                continue
+
+    def _app_relay(self):
+        if not self.slot_port:
+            return
+        status = http_status(self.slot_port, timeout=2)
+        self.step("app_relay", INFO, "The Mac app's relay",
+                  f"127.0.0.1:{self.slot_port} " + ("answers" if status is not None else "doesn't answer (fine when "
+                                                                                       "the app isn't running it)"))
+
+    def _lan(self):
+        names = list(self.peer.hostnames) if self.peer is not None else []
+        addresses, hits = exposure.exposed(names)
+        if hits:
+            self.step("lan", FAIL, "The phone's Wi-Fi address",
+                      "WebDriverAgent ANSWERS on " + ", ".join(hits) + ". Mobster stops a helper that does this "
+                      "when it starts it. Turn Wi-Fi off for this phone (`mobster wifi off`) and report this.")
+        elif addresses:
+            self.step("lan", OK, "The phone's Wi-Fi address",
+                      f"{', '.join(addresses)}: 8100 and 9100 don't answer (also check from another machine)")
+        else:
+            self.step("lan", WARN, "The phone's Wi-Fi address",
+                      "couldn't be found. From another machine on the same Wi-Fi, check that `nc -vz <the phone's "
+                      "Wi-Fi address> 8100` and 9100 fail.")
+
+    def _usbmux(self):
+        listed = usbmux_network(self.udid)
+        self.step("usbmux", INFO, "usbmuxd over the network",
+                  {True: "lists the phone (evidence only; Mobster never uses it for WebDriverAgent)",
+                   False: "doesn't list the phone", None: "couldn't tell (idevice_id is missing)"}[listed])
+
+
+def describe(item):
+    glyph = {OK: "✓", WARN: "!", FAIL: "✗", INFO: "·"}[item["state"]]
+    return f"  {glyph} {item['title']:<32} {item['detail']}"

mobile_agent/wireless/register.py

@@ -0,0 +1,8 @@
+"""Wi-Fi's routes and transport monitor, and nothing a task sees: a task runs the same on the cable and on Wi-Fi."""
+
+
+def register(api):
+    """``api`` is mobile_agent.harness_api."""
+    from . import api as routes
+    routes.register_routes()
+    api.register_service(routes.start_service, routes.close_service)

mobile_agent/wireless/relay.py

@@ -0,0 +1,179 @@
+"""The local relay for a phone on Wi-Fi (SPEC §3.7 item 4): 127.0.0.1-only forwarders to the phone's tunnel."""
+
+import ipaddress
+import socket
+import threading
+
+from ..devices import LOOPBACK
+
+TUNNEL_NETWORK = ipaddress.IPv6Network("fd00::/8")
+NOT_AVAILABLE = "Wi-Fi isn't available for this iPhone yet."
+CONNECT_TIMEOUT = 5.0
+MAX_CONNECTIONS = 64
+BUFFER = 65536
+
+
+# Only the phone's end of the CoreDevice tunnel: the relay never carries WebDriverAgent over the plain LAN.
+def check_target(address):
+    if not isinstance(address, str) or not address.strip() or "%" in address:
+        raise ValueError(NOT_AVAILABLE)
+    try:
+        parsed = ipaddress.ip_address(address.strip().strip("[]"))
+    except ValueError:
+        raise ValueError(NOT_AVAILABLE) from None
+    if not isinstance(parsed, ipaddress.IPv6Address) or parsed.ipv4_mapped is not None or parsed not in TUNNEL_NETWORK:
+        raise ValueError(NOT_AVAILABLE)
+    return parsed.compressed
+
+
+def require_tunnel(address, through=None):
+    target = check_target(address)
+    if through is None:
+        from .network import through_tunnel as through
+    if not through(target):
+        raise ValueError(NOT_AVAILABLE)
+    return target
+
+
+class Relay:
+    """Forwards 127.0.0.1:<local> to [target]:<remote> for each ``(local, remote)`` pair, until ``stop``."""
+
+    def __init__(self, target, pairs, *, connect_timeout=CONNECT_TIMEOUT, name="wifi-relay"):
+        self.target = check_target(target)
+        self.pairs = []
+        for local, remote in pairs:
+            if not all(isinstance(port, int) and not isinstance(port, bool) for port in (local, remote)) \
+                    or not 0 <= local <= 65535 or not 1 <= remote <= 65535:
+                raise ValueError("A relay forwards a port number to a port number")
+            self.pairs.append((local, remote))
+        if not self.pairs:
+            raise ValueError("A relay needs at least one port")
+        self.connect_timeout = connect_timeout
+        self.name = name
+        self.listeners = []
+        self.connections = set()
+        self.slots = threading.BoundedSemaphore(MAX_CONNECTIONS)
+        self.lock = threading.Lock()
+        self.stopping = threading.Event()
+
+    @property
+    def running(self):
+        return bool(self.listeners) and not self.stopping.is_set()
+
+    @property
+    def ports(self):
+        """The local ports, in the order of ``pairs`` (after ``start``)."""
+        return [listener.getsockname()[1] for listener, _ in self.listeners]
+
+    def start(self):
+        """Listen on every local port, or none: OSError (a port in use) leaves nothing open."""
+        if self.running:
+            return self
+        self.stopping.clear()
+        opened = []
+        try:
+            for local, remote in self.pairs:
+                listener = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+                opened.append((listener, remote))
+                listener.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+                listener.bind((LOOPBACK, local))
+                listener.listen(16)
+        except OSError:
+            for listener, _ in opened:
+                listener.close()
+            raise
+        self.listeners = opened
+        for listener, remote in opened:
+            threading.Thread(target=self._accept, args=(listener, remote), daemon=True,
+                             name=f"mobster-{self.name}-{listener.getsockname()[1]}").start()
+        return self
+
+    def stop(self):
+        self.stopping.set()
+        for listener, _ in self.listeners:
+            try:
+                listener.close()
+            except OSError:
+                pass
+        with self.lock:
+            live = list(self.connections)
+            self.connections.clear()
+        for sock in live:
+            _close(sock)
+
+    # -- forwarding ------------------------------------------------------------------------------------------------
+
+    def _accept(self, listener, remote):
+        while not self.stopping.is_set():
+            try:
+                client, _ = listener.accept()
+            except OSError:
+                return
+            if not self.slots.acquire(blocking=False):
+                _close(client)
+                continue
+            with self.lock:
+                if self.stopping.is_set():
+                    self.slots.release()
+                    _close(client)
+                    continue
+                # Count and track clients before upstream connects: a missing
+                # tunnel must not leave unbounded pending threads or sockets.
+                self.connections.add(client)
+            threading.Thread(target=self._serve, args=(client, remote), daemon=True,
+                             name=f"mobster-{self.name}-conn").start()
+
+    def _serve(self, client, remote):
+        upstream = None
+        try:
+            try:
+                upstream = socket.create_connection((self.target, remote), timeout=self.connect_timeout)
+            except OSError:
+                return
+            with self.lock:
+                if self.stopping.is_set():
+                    return
+                upstream.settimeout(None)
+                client.settimeout(None)
+                self.connections.add(upstream)
+            other = threading.Thread(target=self._pump, args=(upstream, client), daemon=True,
+                                     name=f"mobster-{self.name}-pump")
+            other.start()
+            self._pump(client, upstream)
+            other.join()
+        finally:
+            with self.lock:
+                self.connections.discard(client)
+                self.connections.discard(upstream)
+            _close(client)
+            if upstream is not None:
+                _close(upstream)
+            self.slots.release()
+
+    def _pump(self, source, target):
+        """Copy ``source`` to ``target`` until ``source`` ends; then end ``target``'s sending side."""
+        try:
+            while True:
+                data = source.recv(BUFFER)
+                if not data:
+                    break
+                target.sendall(data)
+        except OSError:
+            _close(source)
+            _close(target)
+            return
+        try:
+            target.shutdown(socket.SHUT_WR)
+        except OSError:
+            pass
+
+
+def _close(sock):
+    try:
+        sock.shutdown(socket.SHUT_RDWR)
+    except OSError:
+        pass
+    try:
+        sock.close()
+    except OSError:
+        pass

mobile_agent/wireless/result.py

@@ -0,0 +1,87 @@
+
+import json
+import os
+import tempfile
+import time
+from pathlib import Path
+
+from .probe import FAIL, WARN
+
+FILE = "wifi-probe.json"
+NOT_RUN = {"state": "not_run", "at": None, "reason": None}
+KEEP = 20
+UNFINISHED = "The check stopped before it could tell. Run it again with the phone unplugged."
+
+
+def _path(data_dir):
+    return Path(data_dir) / FILE
+
+
+def _read(data_dir):
+    try:
+        value = json.loads(_path(data_dir).read_text())
+    except (OSError, ValueError):
+        return {}
+    return value if isinstance(value, dict) else {}
+
+
+def _clean(value):
+    if not isinstance(value, dict) or value.get("state") not in ("passed", "failed"):
+        return dict(NOT_RUN)
+    at, reason = value.get("at"), value.get("reason")
+    return {"state": value["state"], "at": at if isinstance(at, int) and not isinstance(at, bool) else None,
+            "reason": reason[:300] if isinstance(reason, str) and reason else None}
+
+
+def reason_of(steps):
+    """Why a probe did not pass, in the words of the step that failed (else warned): "<title>: <detail>"."""
+    for state in (FAIL, WARN):
+        step = next((item for item in steps if item.get("state") == state), None)
+        if step is not None:
+            detail = str(step.get("detail") or "").strip()
+            return f"{step.get('title')}: {detail}" if detail else str(step.get("title"))
+    return UNFINISHED
+
+
+def record(data_dir, udid, public, now=None):
+    steps = public.get("steps") or []
+    usb = next((item for item in steps if item.get("key") == "usb"), None)
+    # a probe made with the cable plugged in says nothing about Wi-Fi, so it isn't kept
+    if usb is not None and str(usb.get("detail", "")).startswith("plugged in"):
+        return None
+    entry = {"state": "passed", "at": None, "reason": None} if public.get("ok") else \
+        {"state": "failed", "at": None, "reason": reason_of(steps)}
+    entry["at"] = int((time.time() if now is None else now) * 1000)
+    kept = _read(data_dir)
+    kept[str(udid).upper()] = entry
+    for old in sorted(kept, key=lambda key: _clean(kept[key])["at"] or 0)[:-KEEP]:
+        del kept[old]
+    Path(data_dir).mkdir(parents=True, exist_ok=True)
+    handle, temp = tempfile.mkstemp(dir=str(data_dir), prefix=".wifi-probe-")
+    try:
+        with os.fdopen(handle, "w") as out:
+            json.dump(kept, out, separators=(",", ":"))
+        os.chmod(temp, 0o600)
+        os.replace(temp, _path(data_dir))
+    except OSError:
+        try:
+            os.unlink(temp)
+        except OSError:
+            pass
+        return None
+    return entry
+
+
+def get(data_dir, udid):
+    """``udid``'s last probe, or not_run."""
+    return _clean(_read(data_dir).get(str(udid).upper()))
+
+
+def latest(data_dir):
+    """This Mac's most recent probe of any phone, with the phone's udid; not_run when none was kept."""
+    kept = {udid: _clean(value) for udid, value in _read(data_dir).items()}
+    kept = {udid: value for udid, value in kept.items() if value["state"] != "not_run"}
+    if not kept:
+        return dict(NOT_RUN)
+    udid = max(kept, key=lambda key: kept[key]["at"] or 0)
+    return {**kept[udid], "udid": udid}

mobile_agent/wireless/store.py

@@ -0,0 +1,85 @@
+"""Which phones may be reached over Wi-Fi: ``wifi: {enabled, enabledAt, via}`` per phone (SPEC §3.7). ``via`` says
+who turned on the phone's own switch (Connect via network); with Wi-Fi off it is kept only while that switch is one
+Mobster turned on and couldn't turn off yet, so a later `mobster wifi off` over the cable still can."""
+
+import time
+from pathlib import Path
+
+VIA = ("mobster", "xcode")
+OFF = {"enabled": False, "enabledAt": None, "via": None}
+
+
+def _clean(value):
+    if not isinstance(value, dict):
+        return dict(OFF)
+    via = value.get("via") if value.get("via") in VIA else None
+    if value.get("enabled") is not True:
+        return {**OFF, "via": via}
+    at = value.get("enabledAt")
+    return {"enabled": True, "enabledAt": at if isinstance(at, int) and not isinstance(at, bool) else None,
+            "via": via}
+
+
+def _primary(data_dir):
+    from ..cli_constants import DEFAULT_WDA_URL
+    from ..device_manager import DeviceManager
+    return DeviceManager(Path(data_dir), DEFAULT_WDA_URL)
+
+
+def _same(a, b):
+    return isinstance(a, str) and isinstance(b, str) and a.upper() == b.upper()
+
+
+def get(data_dir, udid):
+    """{"enabled", "enabledAt", "via"} for ``udid``; off when it isn't set up here or never was turned on."""
+    from ..devices import DeviceStore
+    entry = next((item for item in DeviceStore(data_dir).phones() if _same(item["udid"], udid)), None)
+    if entry is not None:
+        return _clean(entry.get("wifi"))
+    settings = _primary(data_dir).settings() if Path(data_dir, "device.json").exists() else {}
+    wifi = settings.get("wifi")
+    # the primary's entry keeps the UDID it belongs to, so choosing another primary phone never carries it over
+    if _same(settings.get("udid"), udid) and isinstance(wifi, dict) and _same(wifi.get("udid"), udid):
+        return _clean(wifi)
+    return dict(OFF)
+
+
+def enabled(data_dir, udid):
+    return get(data_dir, udid)["enabled"]
+
+
+def is_set_up(data_dir, udid):
+    """True when ``udid`` is the phone chosen in Setup or one added besides it."""
+    from ..devices import DeviceStore
+    if any(_same(item["udid"], udid) for item in DeviceStore(data_dir).phones()):
+        return True
+    return _same(_primary(data_dir).settings().get("udid"), udid)
+
+
+def put(data_dir, udid, on, via=None):
+    from ..devices import DeviceStore
+    if via is not None and via not in VIA:
+        raise ValueError("via is mobster or xcode")
+    value = ({"enabled": True, "enabledAt": round(time.time() * 1000), "via": via} if on else {**OFF, "via": via})
+    kept = on or via is not None
+    store = DeviceStore(data_dir)
+    if any(_same(item["udid"], udid) for item in store.phones()):
+        store.set_wifi(udid, value if kept else None)
+        return _clean(value)
+    manager = _primary(data_dir)
+    if not _same(manager.settings().get("udid"), udid):
+        raise LookupError("not_set_up")
+    manager.save_settings(wifi={**value, "udid": udid} if kept else None)
+    return _clean(value)
+
+
+def enabled_udids(data_dir):
+    """The UDIDs (upper case) with Wi-Fi on, of every phone set up here."""
+    from ..devices import DeviceStore
+    found = {item["udid"].upper() for item in DeviceStore(data_dir).phones() if _clean(item.get("wifi"))["enabled"]}
+    if Path(data_dir, "device.json").exists():
+        settings = _primary(data_dir).settings()
+        wifi = settings.get("wifi")
+        if isinstance(wifi, dict) and _same(settings.get("udid"), wifi.get("udid")) and _clean(wifi)["enabled"]:
+            found.add(settings["udid"].upper())
+    return found