mobster-cli 0.4.3__py3-none-any.whl

mobile_agent/phone_io/tunnel.py

@@ -0,0 +1,129 @@
+"""The camera roll over Apple's own encrypted tunnel to the iPhone, with no cable: pymobiledevice3's ``--native``.
+
+macOS keeps a tunnel to every iPhone it pairs with for development (``remoted``), over the cable or the local network.
+pymobiledevice3 reaches the iPhone's file service through it with ``--native``: no root, no Xcode, nothing on the
+phone. Mobster runs it as a separate program that you install yourself (``pipx install pymobiledevice3``,
+GPL-3.0-or-later), and never imports or bundles it. Without it this route says how to get it.
+
+What it reaches is the camera roll's files (/DCIM), as the cable does: originals, newest first by their number
+(IMG_0042 after IMG_0041, the way the iPhone names what it takes or receives). Each call opens the tunnel again,
+about 7 seconds on the test device (iPhone 15 Pro, 14 Oct 2026, measured over the cable's tunnel).
+"""
+
+import os
+import re
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+
+from . import PhoneIOError
+
+TOOL = "pymobiledevice3"
+NEEDS_TOOL = ("Mobster reaches the iPhone's camera roll without a cable through pymobiledevice3, which isn't on this "
+              "Mac.", "Install it with `pipx install pymobiledevice3`, then try again.")
+TIMEOUT_S = 90
+# remoted hadn't brought the tunnel up yet (seen 2 times in 3 on 14 Oct while another tool used the phone).
+TUNNEL_DOWN = re.compile(r"could not find remoted|RSD connection", re.I)
+MEDIA = re.compile(r"^/DCIM/(\d{3})[A-Z_]{0,12}/([A-Za-z_]*?)(\d+)?(?:_\d+)?\."
+                   r"(heic|heif|jpe?g|png|gif|mov|mp4|m4v|dng|webp)$",
+                   re.I)
+
+
+def tool():
+    """pymobiledevice3 on PATH, in pipx's folder (``PIPX_BIN_DIR``, else ~/.local/bin) or in Homebrew's; None when it
+    isn't installed. A copy inside a Python venv whose folder isn't on PATH isn't found."""
+    pipx = os.environ.get("PIPX_BIN_DIR", "").strip() or "~/.local/bin"
+    for candidate in (shutil.which(TOOL), os.path.join(os.path.expanduser(pipx), TOOL), "/opt/homebrew/bin/" + TOOL,
+                      "/usr/local/bin/" + TOOL):
+        if candidate and os.path.isfile(candidate) and os.access(candidate, os.X_OK):
+            return candidate
+    return None
+
+
+class TunnelRoll:
+    """The camera roll of the iPhone ``record`` (devices.py's shape) over Apple's tunnel."""
+
+    def __init__(self, record, runner=None, program=None):
+        self.record = record or {}
+        udid = str(self.record.get("udid") or "")
+        if self.record.get("kind") == "simulator" or not re.fullmatch(r"[0-9A-Fa-f-]{24,40}", udid):
+            raise PhoneIOError(f"“{self.name}” isn't an iPhone Mobster knows.", "usage")
+        self.udid, self._runner, self._program = udid, runner, program
+
+    @property
+    def name(self):
+        return self.record.get("name") or self.record.get("id") or "the iPhone"
+
+    def _run(self, *command, timeout=TIMEOUT_S):
+        """Reads only (a listing, a copy to the Mac), so a tunnel that wasn't up yet is tried once more."""
+        code, output = self._once(*command, timeout=timeout)
+        if code != 0 and TUNNEL_DOWN.search(output or ""):
+            code, output = self._once(*command, timeout=timeout)
+        return code, output
+
+    def _once(self, *command, timeout=TIMEOUT_S):
+        program = self._program or tool()
+        if not program and self._runner is None:
+            raise PhoneIOError(NEEDS_TOOL[0], "tools", NEEDS_TOOL[1])
+        argv = [program or TOOL, *command, "--native", "--udid", self.udid]
+        if self._runner is not None:
+            return self._runner(argv, timeout)
+        from ..native_helpers import require_devices
+        require_devices()
+        env = dict(os.environ, NO_COLOR="1", TERM="dumb", COLUMNS="200")
+        try:
+            done = subprocess.run(argv, capture_output=True, text=True, errors="replace", timeout=timeout,
+                                  stdin=subprocess.DEVNULL, env=env)
+        except subprocess.TimeoutExpired:
+            raise PhoneIOError(f"{self.name} didn't answer over the tunnel within {timeout} seconds.", "failed",
+                               "Keep it unlocked and on the same network as this Mac, then try again.") from None
+        except OSError as error:
+            raise PhoneIOError(f"pymobiledevice3 couldn't run ({type(error).__name__}).", "tools") from None
+        return done.returncode, (done.stdout or "") + (done.stderr or "")
+
+    def media(self):
+        """Every photo and video file under /DCIM: [remote paths], oldest first by folder and number."""
+        code, output = self._run("afc", "ls", "/DCIM", "--recursive")
+        if code != 0:
+            raise self._explain(output)
+        found = []
+        for line in output.splitlines():
+            path = line.strip()
+            match = MEDIA.match(path)
+            if match:
+                found.append((int(match.group(1)), int(match.group(3) or 0), path))
+        return [path for *_, path in sorted(found)]
+
+    def pull(self, folder, count=1):
+        """Copy the newest ``count`` files (1 to 20) into ``folder``."""
+        from .files import land
+        from .photos import MAX_PULL, PHOTO_TYPES, digest
+        count = max(1, min(int(count or 1), MAX_PULL))
+        wanted = list(reversed(self.media()))[:count]
+        folder = Path(folder).expanduser()
+        folder.mkdir(parents=True, exist_ok=True)
+        out = []
+        with tempfile.TemporaryDirectory(prefix="mobster-tunnel-", dir=folder) as scratch:
+            for remote in wanted:
+                name = remote.rsplit("/", 1)[-1]
+                code, output = self._run("afc", "pull", remote, scratch + "/", timeout=TIMEOUT_S + 300)
+                partial = Path(scratch) / name
+                if code != 0 or not partial.is_file():
+                    raise self._explain(output)
+                target = land(partial, folder, name)
+                out.append({"path": str(target), "name": target.name, "bytes": target.stat().st_size,
+                            "kind": PHOTO_TYPES.get(name.rsplit(".", 1)[-1].lower(), "photo"),
+                            "sha256": digest(target)})
+        return out
+
+    def _explain(self, output):
+        text = " ".join((output or "").split())
+        if re.search(r"NoDeviceConnected|not found|No device", text, re.I):
+            return PhoneIOError(f"macOS has no tunnel to {self.name} right now.", "no_device",
+                                "Pair it with this Mac once over the cable (Trust), keep it on the same Wi-Fi and "
+                                "unlocked, then try again.")
+        if re.search(r"PasswordProtected|locked|pair", text, re.I):
+            return PhoneIOError(f"{self.name} is locked or doesn't trust this Mac.", "locked",
+                                "Unlock it, then try again.")
+        return PhoneIOError(f"The tunnel to {self.name} failed{': ' + text[-160:] if text else ''}.", "failed")

mobile_agent/phone_ready.py

@@ -0,0 +1,91 @@
+"""Whether a phone can take a queued post now: the lock, Photos access and Low Power Mode, read from Mobster's helper.
+
+Off unless ``MOBSTER_QUEUE_PREFLIGHT=1`` (``enabled``). With it on, the content queue (content_queue/runner.py)
+
+- keeps a due post ``ready`` while the phone is locked, or while the lock can't be read, instead of failing it;
+- refuses to start a queue, and fails a post before any file is sent, when Photos access is off or still unanswered on
+  the profile's phone, so no file waits the 60 s the first save would wait for an answer nobody gives;
+- warns when Low Power Mode is on, because it makes the phone lock itself after 30 seconds.
+
+Every read here is a sessionless GET the helper answers in milliseconds: ``/wda/locked`` (stock),
+``/mobster/photos/status`` and ``/mobster/power`` (wda.patches.PREFLIGHT_PATCHES, which the same flag adds to the
+helper). They take no lease and send no input. Nothing here keeps the phone awake,
+unlocks it or presses a Photos grant: a person answers those on the iPhone.
+A read that fails is "unknown", and unknown never counts as unlocked or as granted.
+"""
+
+import os
+
+from .phone_io import PhoneIOError
+from .phone_io.photos import STATUS_WORDS
+from .wda.timeouts import timeout_for
+
+ENV = "MOBSTER_QUEUE_PREFLIGHT"
+ON_WORDS = ("1", "true", "yes", "on")
+GRANTED = ("authorized", "limited")   # "limited" (Limit Access) is enough to add to Photos
+
+HOLD_LOCKED = "Waiting for the phone: it's locked."
+HOLD_UNREADABLE = "Waiting for the phone: Mobster can't tell whether it's locked."
+PHOTOS_UNREADABLE = ("Mobster couldn't read Photos access on {name}. Keep it unlocked and connected, and rebuild "
+                     "Mobster's helper in Setup if it was built before this check, then try again.")
+NOT_ASKED = ("Mobster hasn't asked {name} for Photos yet. In Setup, press Allow beside “Let Mobster add to Photos” and "
+             "answer on the iPhone (Limit Access is enough), then try again.")
+LOW_POWER = ("Low Power Mode is on for {name}, so it locks itself after 30 seconds. Turn it off in Settings › "
+             "Battery before {when}.")
+
+
+def enabled(env=None):
+    """Whether the queue's phone checks (and the helper routes they read) are on in this process."""
+    return str((os.environ if env is None else env).get(ENV, "")).strip().lower() in ON_WORDS
+
+
+def read(wda_url, path):
+    """The value of a sessionless GET ``path`` on the helper at ``wda_url``, or None when it didn't answer in time or
+    has no such route (a helper built before this check)."""
+    from .transport import read_kept
+    try:
+        return read_kept(wda_url, path, timeout=timeout_for("GET", path)).get("value")
+    except Exception:  # noqa: BLE001 - an unanswered phone is "unknown", never an error
+        return None
+
+
+def hold(wda_url):
+    """Why a post waits for the phone now, in a sentence, or None when the phone is unlocked. Locked and unknown both
+    hold: a phone Mobster can't read is never treated as unlocked."""
+    locked = read(wda_url, "/wda/locked")
+    if locked is False:
+        return None
+    return HOLD_LOCKED if locked is True else HOLD_UNREADABLE
+
+
+def photos_status(wda_url):
+    """The helper's Photos access for its phone: authorized, limited, denied, restricted or not_determined; None when
+    the helper didn't say (it isn't running, or was built without the check)."""
+    value = read(wda_url, "/mobster/photos/status")
+    status = value.get("status") if isinstance(value, dict) else None
+    return status if status in GRANTED or status in STATUS_WORDS else None
+
+
+def photos_refusal(wda_url, name):
+    """A PhoneIOError (code ``photos_denied``, ``photos_restricted``, ``photos_not_determined`` or
+    ``photos_unreadable``) when Mobster's helper can't add to Photos on this phone yet, else None. Denied and
+    restricted use the transfer's own words (photos.STATUS_WORDS); not asked yet points to Setup's Allow."""
+    status = photos_status(wda_url)
+    if status in GRANTED:
+        return None
+    if status in STATUS_WORDS:
+        words = NOT_ASKED if status == "not_determined" else STATUS_WORDS[status]
+        return PhoneIOError(words.format(name=name), "photos_" + status)
+    return PhoneIOError(PHOTOS_UNREADABLE.format(name=name), "photos_unreadable")
+
+
+def low_power(wda_url):
+    """True or False as the helper says Low Power Mode is, None when it can't say (a helper built before this check)."""
+    value = read(wda_url, "/mobster/power")
+    flag = value.get("lowPowerMode") if isinstance(value, dict) else None
+    return flag if isinstance(flag, bool) else None
+
+
+def low_power_warning(wda_url, name, when):
+    """The warning sentence when Low Power Mode is on, else None. ``when`` finishes "before ...": "the first post"."""
+    return LOW_POWER.format(name=name, when=when) if low_power(wda_url) is True else None

mobile_agent/pinning.py

@@ -0,0 +1,158 @@
+"""Mobster's own servers, pinned to CA keys: a chain without one is refused with PinMismatch, never retried unpinned."""
+
+import base64
+import hashlib
+import http.client
+import ssl
+import urllib.request
+
+from . import tls
+
+# The hosts whose chain must include a pinned CA key.
+PINNED_HOSTS = frozenset({"mobster.dev", "www.mobster.dev", "api.mobster.dev", "remote.mobster.dev"})
+
+# base64 SHA-256 of each CA's DER SubjectPublicKeyInfo (RFC 7469's pin-sha256), checked live on 13 Oct 2026.
+PINS = {
+    # In use on 13 Oct 2026.
+    "LoMHBotttiDko50Gi13uXW71eIy7LAttI+rYT8wXF4w=": "Let's Encrypt YR1",
+    "fk6IOKit1ild5647BH06ujSIq5XbCgqlbYl6ANhhi88=": "ISRG Root YR",
+    "C5+lpZ7tcVwmwQIMcRtPbsQtWLABXhQzejna0wHFr8M=": "ISRG Root X1",
+    "kIdp6NNEd8wsugYyyIYFsi1ylMCED3hZbSR8ZFsa/A4=": "Google Trust Services WE1",
+    "mEflZT5enoR1FuXLgYYGqnVEoZvmf9c2bVBpiOjYQ0c=": "GTS Root R4",
+    # Backups.
+    "diGVwiVYbubAI3RW4hB9xU8e/CH2GnkuvVFZE8zmgzI=": "ISRG Root X2",
+    "sCkq5UWXjg+7mKu9lMhhYF5bGLsy7VI/UNW3tccdR7w=": "ISRG Root YE",
+    "hxqRlPTu1bMS/0DITB1SSu0vd4u/8l8TjPgfaAp63Gc=": "GTS Root R1",
+    "Vfd95BwDeSQo+NUYxVEEIlvkOlWY2SalKK1lPhzOx78=": "GTS Root R2",
+    "QXnt2YHvdHR3tJYmQIr0Paosp6t/nggsEGD4QJZ3Q0g=": "GTS Root R3",
+    "K89VOmb1cJAN3TK6bf4ezAbJGC1mLcG2Dh97dnwr3VQ=": "SSL.com TLS RSA Root CA 2022",
+    "G/ANXI8TwJTdF+AFBM8IiIUPEv0Gf6H5LA/b9guG4yE=": "SSL.com TLS ECC Root CA 2022",
+    "0cRTd+vc1hjNFlHcLgLCHXUeWqn80bNDH/bs9qMTSPo=": "SSL.com Root Certification Authority RSA",
+    "oyD01TTXvpfBro3QSZc1vIlcMjrdLTiL/M9mLCPX+Zo=": "SSL.com Root Certification Authority ECC",
+}
+
+
+class PinMismatch(ssl.SSLCertVerificationError):
+    """A pinned host's verified chain has no pinned CA key: something between this Mac and the server answered."""
+
+    def __init__(self, host):
+        self.host = host
+        # (errno, strerror): ssl errors print their strerror alone.
+        super().__init__(1, f"Mobster couldn't verify its server ({host}), so it didn't connect. Another app or this "
+                         "network may be intercepting secure connections. Try another network, or update Mobster.")
+
+
+def is_pinned(host):
+    return str(host or "").rstrip(".").lower() in PINNED_HOSTS
+
+
+def _der_element(data, at):
+    """(tag, start of contents, end of element) of the DER element at ``at``. ValueError on anything malformed."""
+    if at + 2 > len(data):
+        raise ValueError("truncated")
+    tag, length = data[at], data[at + 1]
+    at += 2
+    if length & 0x80:
+        count = length & 0x7F
+        if not 1 <= count <= 4 or at + count > len(data):
+            raise ValueError("bad length")
+        length = int.from_bytes(data[at:at + count], "big")
+        at += count
+    if at + length > len(data):
+        raise ValueError("truncated")
+    return tag, at, at + length
+
+
+def spki_der(certificate):
+    """The DER SubjectPublicKeyInfo of a DER certificate: tbsCertificate's seventh field (sixth without a version)."""
+    tag, body, _ = _der_element(certificate, 0)
+    if tag != 0x30:
+        raise ValueError("not a certificate")
+    tag, at, end = _der_element(certificate, body)
+    if tag != 0x30:
+        raise ValueError("no tbsCertificate")
+    tag, _, after = _der_element(certificate, at)
+    if tag == 0xA0:  # [0] version
+        at = after
+    for _ in range(5):  # serialNumber, signature, issuer, validity, subject
+        _, _, at = _der_element(certificate, at)
+    tag, _, after = _der_element(certificate, at)
+    if tag != 0x30 or after > end:
+        raise ValueError("no subjectPublicKeyInfo")
+    return certificate[at:after]
+
+
+def spki_pin(certificate):
+    """The pin-sha256 of a DER certificate's key."""
+    return base64.b64encode(hashlib.sha256(spki_der(certificate)).digest()).decode()
+
+
+def verified_chain(sock):
+    """The DER certificates OpenSSL verified for ``sock``, leaf first."""
+    method = getattr(sock, "get_verified_chain", None) or getattr(getattr(sock, "_sslobj", None),
+                                                                  "get_verified_chain", None)
+    if method is None:
+        return []
+    return [c if isinstance(c, bytes) else c.public_bytes(ssl._ssl.ENCODING_DER) for c in method() or []]
+
+
+def chain_is_pinned(chain):
+    for certificate in chain:
+        try:
+            if spki_pin(certificate) in PINS:
+                return True
+        except ValueError:
+            continue
+    return False
+
+
+def check_pins(sock, host):
+    """Raise PinMismatch when ``host`` is pinned and ``sock``'s verified chain has no pinned key or can't be read."""
+    if is_pinned(host) and not chain_is_pinned(verified_chain(sock)):
+        raise PinMismatch(host)
+
+
+def pinned_context():
+    """The verifying context Mobster's HTTPS uses: the default (certificate and hostname required), TLS 1.2 or later."""
+    tls.ensure_ca_bundle()
+    made = ssl.create_default_context()
+    made.minimum_version = ssl.TLSVersion.TLSv1_2
+    return made
+
+
+def wrap(sock, host):
+    """``sock`` wrapped in TLS for ``host``, with the pin checked before a byte is sent."""
+    secure = pinned_context().wrap_socket(sock, server_hostname=host)
+    try:
+        check_pins(secure, host)
+    except BaseException:
+        secure.close()
+        raise
+    return secure
+
+
+class PinnedHTTPSConnection(http.client.HTTPSConnection):
+    """HTTPSConnection that checks the pin of a pinned host after the handshake (through a proxy's tunnel too)."""
+
+    def __init__(self, host, port=None, *, context=None, **kwargs):
+        super().__init__(host, port, context=context or pinned_context(), **kwargs)
+
+    def connect(self):
+        super().connect()
+        try:
+            check_pins(self.sock, self._tunnel_host or self.host)
+        except BaseException:
+            self.close()
+            raise
+
+
+class PinnedHTTPSHandler(urllib.request.HTTPSHandler):
+    """urllib's HTTPS with PinnedHTTPSConnection: every hop of a redirect to a pinned host is checked."""
+
+    def https_open(self, req):
+        return self.do_open(PinnedHTTPSConnection, req, context=self._context)
+
+
+def opener():
+    """A urllib opener whose HTTPS checks pins (and verifies as usual everywhere else)."""
+    return urllib.request.build_opener(PinnedHTTPSHandler(context=pinned_context()))