mobster-cli 0.4.3__py3-none-any.whl

mobile_agent/team_signing/ledger.py

@@ -0,0 +1,105 @@
+"""The ledger of the writes Mobster makes to Apple: durable before a write is sent, and the reason a write whose outcome
+is unknown is never sent again.
+
+One JSON line per event in ``team-signing/ledger.jsonl`` (private, fsynced: journal.append_jsonl). ``begin`` writes
+the intent first and refuses when the same write's last event is an intent or an unknown outcome, or when it is
+already made. It records names, UDIDs, bundle ids and Apple's ids. It never records the API key, a token, a certificate
+signing request, a certificate or a profile.
+"""
+
+import fcntl
+import json
+import time
+from pathlib import Path
+
+from ..devkit import DevError
+from ..devkit.asc import UNKNOWN_FIX, WriteUnknown
+from ..journal import append_jsonl
+
+OPEN = ("intent", "unknown")
+MADE = ("done", "resolved_done")
+
+
+class LedgerError(DevError):
+    """The ledger can't be read, so no write is sent."""
+
+
+class Ledger:
+    def __init__(self, path, clock=time.time):
+        self.path, self.clock = Path(path), clock
+
+    def events(self):
+        try:
+            lines = self.path.read_text(encoding="utf-8").splitlines()
+        except FileNotFoundError:
+            return []
+        except OSError:
+            raise LedgerError(
+                "Mobster can't read its record of changes to App Store Connect, so it sent nothing.",
+                f"Check {self.path}.",
+            ) from None
+        try:
+            return [json.loads(line) for line in lines if line.strip()]
+        except ValueError:
+            raise LedgerError(
+                "Mobster's record of changes to App Store Connect is damaged, so it sent nothing.",
+                f"Move {self.path} aside to start a new one.",
+            ) from None
+
+    def last(self, digest):
+        found = [event for event in self.events() if event.get("digest") == digest]
+        return found[-1] if found else None
+
+    def _append(self, event):
+        append_jsonl(self.path, {**event, "at": round(self.clock(), 3)})
+
+    def _lock(self):
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        handle = open(self.path.with_suffix(".lock"), "a")
+        fcntl.flock(handle, fcntl.LOCK_EX)
+        return handle
+
+    def begin(self, write, digest, summary):
+        """Make the attempt durable. Raises (and sends nothing) when the last event for this write is an unknown
+        outcome or an attempt that never finished, or when it is already made."""
+        handle = self._lock()
+        try:
+            last = self.last(digest)
+            if last and last["event"] in OPEN:
+                raise WriteUnknown(
+                    f"An earlier try of {write.replace('_', ' ')} never finished, so it may have gone through.",
+                    UNKNOWN_FIX,
+                )
+            if last and last["event"] in MADE:
+                raise DevError(f"Mobster already made this change ({write.replace('_', ' ')}).")
+            self._append({"event": "intent", "write": write, "digest": digest, "summary": summary})
+        finally:
+            handle.close()
+
+    def end(self, digest, outcome, detail=None):
+        """How a write ended: done, rejected or unknown."""
+        self._append({"event": outcome, "digest": digest, "detail": detail or {}})
+
+    def unresolved(self):
+        """The writes whose outcome nobody knows: [{digest, write, summary}], oldest first."""
+        latest, intents = {}, {}
+        for event in self.events():
+            latest[event["digest"]] = event["event"]
+            if event["event"] == "intent":
+                intents[event["digest"]] = event
+        return [
+            {"digest": digest, "write": intents[digest]["write"], "summary": intents[digest]["summary"]}
+            for digest, state in latest.items()
+            if state in OPEN and digest in intents
+        ]
+
+    def resolve(self, digest, made):
+        """The person looked at Apple and says whether the change was made. Only an unresolved write can be resolved."""
+        handle = self._lock()
+        try:
+            last = self.last(digest)
+            if not last or last["event"] not in OPEN:
+                raise DevError("That change isn't waiting on you.")
+            self._append({"event": "resolved_done" if made else "resolved_not_done", "digest": digest})
+        finally:
+            handle.close()

mobile_agent/team_signing/prebuilt.py

@@ -0,0 +1,61 @@
+"""The unsigned helper runner Mobster signs: where it is, and whether it has the patches this Mobster has.
+
+A Mac without Xcode can't build the runner, so it signs one built elsewhere (once per Mobster release, with the pinned
+WebDriverAgent and ``wda_patches``). Three places, in this order: ``MOBSTER_PREBUILT_RUNNER`` (a folder holding
+``WebDriverAgentRunner-Runner.app`` and a ``patches.txt`` with its ``wda_patches.patch_digest()``), the Mac app's own
+copy in ``Contents/Resources/helper/``, and the runner an Xcode build on this Mac left in its derived-data folder
+(whose digest the build recorded). A runner built with other patches is never used: it lacks the edit that keeps the
+helper off the phone's network.
+
+Shipping the app's copy is a release step of its own; this module only reads it.
+"""
+
+import os
+from pathlib import Path
+
+from ..devkit import DevError
+from ..wda import patches as wda_patches
+
+NAME = "WebDriverAgentRunner-Runner.app"
+ENV = "MOBSTER_PREBUILT_RUNNER"
+APP_COPY = Path("/Applications/Mobster.app/Contents/Resources/helper")
+DERIVED = Path("Build/Products/Debug-iphoneos") / NAME
+
+
+def _digest_of(folder):
+    try:
+        return (Path(folder) / "patches.txt").read_text().strip()
+    except OSError:
+        return None
+
+
+def candidates(derived=None, built_patches=None, environ=None, app_copy=APP_COPY):
+    environ = os.environ if environ is None else environ
+    if environ.get(ENV):
+        folder = Path(environ[ENV]).expanduser()
+        yield folder / NAME, _digest_of(folder), "MOBSTER_PREBUILT_RUNNER"
+    yield Path(app_copy) / NAME, _digest_of(app_copy), "Mobster for Mac"
+    if derived is not None:
+        yield Path(derived) / DERIVED, built_patches, "this Mac's Xcode build"
+
+
+def locate(derived=None, built_patches=None, environ=None, app_copy=APP_COPY):
+    """(path, where) of a prebuilt runner with this Mobster's patches. DevError, with what to do, when there is none."""
+    wanted = wda_patches.patch_digest()
+    stale = None
+    for path, digest, where in candidates(derived, built_patches, environ, app_copy):
+        if not (path / "Info.plist").is_file():
+            continue
+        if digest == wanted:
+            return path, where
+        stale = where
+    if stale:
+        raise DevError(
+            f"The helper runner from {stale} was built with older patches than this Mobster has.",
+            "Update Mobster for Mac, which carries a matching helper.",
+        )
+    raise DevError(
+        "Mobster has no prebuilt helper to sign.",
+        "Update Mobster for Mac, which carries one, or point MOBSTER_PREBUILT_RUNNER at a folder with "
+        f"{NAME} and a patches.txt.",
+    )

mobile_agent/team_signing/resign.py

@@ -0,0 +1,256 @@
+"""Sign the helper's prebuilt runner on this Mac with ``codesign`` and the team's profile, and check that it verifies.
+
+Input: the unsigned or previously signed ``WebDriverAgentRunner-Runner.app`` (the prebuilt runner, or a copy Xcode
+built once), a development profile Apple made (``.mobileprovision``) and the identity in Mobster's signing keychain.
+Output: a signed copy, ready for pymobiledevice3 to install. The original is never changed.
+
+Only ``/usr/bin/codesign`` and ``/usr/bin/security`` run, with absolute paths, with ``DEVELOPER_DIR`` pointing nowhere,
+so ``xcodebuild`` and ``xcrun`` can't start: Xcode isn't needed and isn't invoked. Nothing changes how the phone looks
+to an app: the runner's contents are the ones it was built with.
+"""
+
+import datetime
+import hashlib
+import os
+import plistlib
+import re
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+
+from ..devkit import DevError
+
+CODESIGN = "/usr/bin/codesign"
+SECURITY = "/usr/bin/security"
+ALLOWED = frozenset({CODESIGN, SECURITY})
+ENV = {"PATH": "/usr/bin:/bin:/usr/sbin:/sbin", "DEVELOPER_DIR": "/var/empty", "HOME": str(Path.home())}
+RUNNER_NAME = "WebDriverAgentRunner-Runner.app"
+MIN_DAYS = 7  # a profile that ends sooner than this is refused: it would need replacing at once
+
+
+def _run(argv, timeout=120):
+    if argv[0] not in ALLOWED:
+        raise DevError(f"Mobster didn't run {argv[0]}: signing uses codesign and security only.")
+    try:
+        done = subprocess.run(argv, capture_output=True, text=True, timeout=timeout, env=ENV, stdin=subprocess.DEVNULL)
+    except (OSError, subprocess.SubprocessError) as error:
+        return 127, "", type(error).__name__
+    return done.returncode, done.stdout, done.stderr
+
+
+def decode_profile(path, run=None):
+    """The plist inside a ``.mobileprovision`` (a CMS envelope), as a dict. DevError when it can't be read."""
+    code, out, _ = (run or _run)([SECURITY, "cms", "-D", "-i", str(path)])
+    try:
+        profile = plistlib.loads(out.encode("utf-8")) if code == 0 and out else None
+    except Exception:  # noqa: BLE001 -- unreadable is the error below
+        profile = None
+    if not isinstance(profile, dict):
+        raise DevError("Mobster couldn't read the provisioning profile.", "Make the profile again.")
+    return profile
+
+
+def profile_facts(profile):
+    """{team, app_identifier, udids, certificates (SHA-1s), expires (epoch), uuid, name} from a decoded profile."""
+    entitlements = profile.get("Entitlements") or {}
+    teams = profile.get("TeamIdentifier") or []
+    expires = profile.get("ExpirationDate")
+    if isinstance(expires, datetime.datetime):
+        expires = (expires if expires.tzinfo else expires.replace(tzinfo=datetime.timezone.utc)).timestamp()
+    return {
+        "team": teams[0] if teams else None,
+        "app_identifier": entitlements.get("application-identifier"),
+        "udids": sorted(str(udid) for udid in profile.get("ProvisionedDevices") or ()),
+        "certificates": sorted(
+            hashlib.sha1(blob).hexdigest().upper()
+            for blob in profile.get("DeveloperCertificates") or ()
+            if isinstance(blob, bytes)
+        ),
+        "expires": expires,
+        "uuid": profile.get("UUID"),
+        "name": profile.get("Name"),
+        "get_task_allow": entitlements.get("get-task-allow") is True,
+    }
+
+
+def covers(app_identifier, team, bundle_id):
+    """Whether a profile's application-identifier (``TEAM.com.example.app`` or ``TEAM.*`` or ``TEAM.com.example.*``)
+    covers ``bundle_id`` for ``team``."""
+    if not isinstance(app_identifier, str) or not app_identifier.startswith(team + "."):
+        return False
+    pattern = app_identifier[len(team) + 1 :]
+    if pattern.endswith("*"):
+        return bundle_id.startswith(pattern[:-1])
+    return pattern == bundle_id
+
+
+def runner_bundle_id(app):
+    try:
+        info = plistlib.loads((Path(app) / "Info.plist").read_bytes())
+    except (OSError, ValueError, plistlib.InvalidFileException):
+        raise DevError(f"{Path(app).name} isn't an app bundle Mobster can read.") from None
+    identifier = info.get("CFBundleIdentifier")
+    if not isinstance(identifier, str) or not identifier:
+        raise DevError(f"{Path(app).name} has no bundle identifier.")
+    return identifier
+
+
+def entitlements_for(facts, bundle_id):
+    """What the signed runner is allowed: the four entitlements the runner has when Xcode signs it, limited to what the
+    profile grants."""
+    application = f"{facts['team']}.{bundle_id}"
+    out = {
+        "application-identifier": application,
+        "com.apple.developer.team-identifier": facts["team"],
+        "keychain-access-groups": [application],
+    }
+    if facts["get_task_allow"]:
+        out["get-task-allow"] = True
+    return out
+
+
+def code_objects(app):
+    """Everything that carries its own signature, innermost first: the frameworks and libraries inside the test bundle,
+    the test bundle, the app's own frameworks and libraries. The app itself is signed last, by the caller."""
+    app = Path(app)
+    objects = []
+    for plugin in sorted((app / "PlugIns").glob("*.xctest")) if (app / "PlugIns").is_dir() else ():
+        frameworks = plugin / "Frameworks"
+        if frameworks.is_dir():
+            objects += sorted(p for p in frameworks.iterdir() if p.suffix in (".framework", ".dylib"))
+        objects.append(plugin)
+    frameworks = app / "Frameworks"
+    if frameworks.is_dir():
+        objects += sorted(p for p in frameworks.iterdir() if p.suffix in (".framework", ".dylib"))
+    return objects
+
+
+def sign(source, profile_path, identity, keychain, destination, *, now=None, run=None, decode=None, bundle_id=None):
+    """Re-sign a copy of ``source`` into ``destination``/Runner.app and verify it.
+
+    ``identity`` is the signing certificate's SHA-1. ``bundle_id`` is the id the signed runner carries (default: the one
+    it has). DevError, with the fix, when the profile isn't this runner's, doesn't
+    list the certificate, is about to end, or the signature doesn't verify. Returns the signed runner's facts."""
+    run = run or _run
+    source, destination = Path(source), Path(destination)
+    if not (source / "Info.plist").exists():
+        raise DevError(f"There is no runner at {source}.", "Mobster needs the prebuilt helper runner to sign.")
+    facts = profile_facts((decode or decode_profile)(profile_path))
+    original = runner_bundle_id(source)
+    bundle_id = bundle_id or original
+    now = datetime.datetime.now(datetime.timezone.utc).timestamp() if now is None else now
+    if not facts["team"] or not covers(facts["app_identifier"], facts["team"], bundle_id):
+        raise DevError(f"The profile isn't for {bundle_id}.", "Make a profile for the helper's App ID and try again.")
+    if identity.upper() not in facts["certificates"]:
+        raise DevError(
+            "The profile doesn't list the signing certificate.", "Make the profile again with the certificate."
+        )
+    if not facts["expires"] or facts["expires"] < now + MIN_DAYS * 86400:
+        raise DevError("The profile ends in under a week.", "Make a new profile.")
+    if not facts["udids"]:
+        raise DevError("The profile lists no iPhone.", "Register the iPhone and make the profile again.")
+    destination.mkdir(parents=True, exist_ok=True)
+    signed = destination / "Runner.app"
+    shutil.rmtree(signed, ignore_errors=True)
+    shutil.copytree(source, signed, symlinks=True)
+    try:
+        (signed / "embedded.mobileprovision").unlink(missing_ok=True)
+        for dsym in signed.rglob("*.dSYM"):
+            shutil.rmtree(dsym, ignore_errors=True)
+        shutil.copyfile(profile_path, signed / "embedded.mobileprovision")
+        if bundle_id != original:
+            # One prebuilt runner serves every team: an App ID is unique across Apple's teams, so each team's runner
+            # carries its own id (signing.runner_bundle_id), set here before the signature seals the bundle.
+            info = plistlib.loads((signed / "Info.plist").read_bytes())
+            info["CFBundleIdentifier"] = bundle_id
+            (signed / "Info.plist").write_bytes(plistlib.dumps(info, fmt=plistlib.FMT_XML))
+        workspace = Path(tempfile.mkdtemp(prefix="mobster-sign-"))
+        try:
+            plist = workspace / "entitlements.plist"
+            plist.write_bytes(plistlib.dumps(entitlements_for(facts, bundle_id)))
+            base = [CODESIGN, "-f", "-s", identity, "--keychain", str(keychain), "--timestamp=none"]
+            for item in code_objects(signed):
+                _checked(run, [*base, str(item)], f"sign {item.name}")
+            _checked(
+                run,
+                [*base, "--entitlements", str(plist), "--generate-entitlement-der", str(signed)],
+                f"sign {signed.name}",
+            )
+        finally:
+            shutil.rmtree(workspace, ignore_errors=True)
+        verify(signed, facts, bundle_id, run)
+    except BaseException:
+        shutil.rmtree(signed, ignore_errors=True)
+        raise
+    return {
+        "path": str(signed),
+        "team": facts["team"],
+        "bundle_id": bundle_id,
+        "udids": facts["udids"],
+        "expires": facts["expires"],
+        "profile": facts["uuid"],
+        "profile_name": facts["name"],
+        "certificate": identity.upper(),
+    }
+
+
+def _checked(run, argv, what):
+    code, _, err = run(argv)
+    if code != 0:
+        line = next((line for line in reversed(err.splitlines()) if line.strip()), "")
+        raise DevError(
+            f"codesign couldn't {what}. {line[:200]}".strip(), "Unlock your Mac's login Keychain and sign again."
+        )
+
+
+def verify(app, facts, bundle_id, run=None):
+    """The signature holds all the way down, it names the team and the runner's bundle id, and the profile inside is
+    the one the signature was made with. DevError otherwise."""
+    run = run or _run
+    code, _, err = run([CODESIGN, "--verify", "--deep", "--strict", str(app)])
+    if code != 0:
+        raise DevError("The signed runner doesn't verify.", (err.strip().splitlines() or [""])[-1][:200])
+    code, _, err = run([CODESIGN, "-dvv", str(app)])
+    fields = dict(re.findall(r"^(Identifier|TeamIdentifier)=(.+)$", err, re.M))
+    if fields.get("TeamIdentifier") != facts["team"] or fields.get("Identifier") != bundle_id:
+        raise DevError("The signed runner names a different team or bundle id than its profile.")
+    code, out, _ = run([CODESIGN, "-d", "--entitlements", ":-", str(app)])
+    try:
+        granted = plistlib.loads(out.encode("utf-8"))
+    except Exception:  # noqa: BLE001
+        granted = {}
+    if granted.get("application-identifier") != f"{facts['team']}.{bundle_id}":
+        raise DevError("The signed runner's entitlements don't match its profile.")
+    embedded = Path(app) / "embedded.mobileprovision"
+    if not embedded.exists():
+        raise DevError("The signed runner has no profile inside.")
+
+
+def check(app, run=None, decode=None):
+    """Read a signed runner back (Path C's import, a later install): its profile's facts after the signature verifies.
+    DevError when the signature doesn't hold or the profile is gone."""
+    app = Path(app)
+    profile = app / "embedded.mobileprovision"
+    if not profile.exists():
+        raise DevError("That runner isn't signed with a profile.")
+    facts = profile_facts(decode(profile) if decode else decode_profile(profile, run))
+    verify(app, facts, runner_bundle_id(app), run)
+    return {**facts, "bundle_id": runner_bundle_id(app)}
+
+
+def tree_digest(app):
+    """A digest of a runner bundle's files and their modes, to see that an exported bundle arrived unchanged."""
+    digest = hashlib.sha256()
+    base = Path(app)
+    for path in sorted(base.rglob("*")):
+        relative = path.relative_to(base).as_posix()
+        if path.is_symlink():
+            digest.update(f"L {relative} {os.readlink(path)}\n".encode())
+        elif path.is_file():
+            digest.update(f"F {relative} {path.stat().st_mode & 0o111 != 0} ".encode())
+            with open(path, "rb") as stream:
+                for block in iter(lambda: stream.read(1 << 20), b""):
+                    digest.update(block)
+            digest.update(b"\n")
+    return digest.hexdigest()