iphone2android 0.1.0__py3-none-any.whl

iphone2android/__init__.py

@@ -0,0 +1,3 @@
+"""Move from an iPhone to an Android phone: messages, contacts, photos, apps and the home screen."""
+
+__version__ = "0.1.0"

iphone2android/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

iphone2android/android/adb.py

@@ -0,0 +1,45 @@
+"""A small adb wrapper.
+
+stdin is always closed. `adb shell` reads stdin, so inside a shell `while read` loop it would eat the
+rest of the list and only the first item would be processed.
+"""
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+
+
+class DeviceUnavailable(RuntimeError):
+    """adb could not reach the phone. Raised instead of returning empty output, which would read as "nothing installed"."""
+
+
+class Adb:
+    def __init__(self, serial: str | None = None, binary: str | None = None):
+        self.serial = serial
+        self.binary = binary or os.environ.get("IPHONE2ANDROID_ADB") or shutil.which("adb") or "adb"
+
+    def run(self, *args: str, timeout: float = 90) -> subprocess.CompletedProcess:
+        cmd = [self.binary] + (["-s", self.serial] if self.serial else []) + list(args)
+        return subprocess.run(cmd, capture_output=True, text=True, timeout=timeout, stdin=subprocess.DEVNULL)
+
+    def shell(self, cmd: str, timeout: float = 90) -> str:
+        try:
+            r = self.run("shell", cmd, timeout=timeout)
+        except subprocess.TimeoutExpired as e:
+            raise DeviceUnavailable(f"adb shell timed out after {timeout}s") from e
+        # adb's own failures start with "adb:" or "error:". A failing command on the phone does not.
+        if r.returncode != 0 and r.stderr.lstrip().startswith(("adb:", "error:")):
+            raise DeviceUnavailable(r.stderr.strip()[:200])
+        return r.stdout
+
+    def installed(self, package: str) -> bool:
+        return f"package:{package}\n" in self.shell(f"pm list packages {package}") + "\n"
+
+    def screen_size(self) -> tuple[int, int]:
+        """The size touches are measured in: the override size when one is set, else the physical size."""
+        out = self.shell("wm size").strip()
+        if "x" not in out:
+            raise DeviceUnavailable(f"cannot read the screen size: {out[:80]!r}")
+        w, h = out.splitlines()[-1].split(":")[-1].strip().split("x")
+        return int(w), int(h)

iphone2android/android/build.py

@@ -0,0 +1,116 @@
+"""Build a home screen from a layout file, and put each page in order.
+
+    {"pages": [["Camera", "Photos", {"folder": "Social", "apps": ["WhatsApp", "Telegram"]}]],
+     "dock": ["Phone", "Messages", "Chrome"]}
+
+Each name is what to type in the app drawer search. Building never assumes where a drop landed: it
+reads the screen again after every drop and uses the real position. Progress is saved after every
+step, so an interrupted build continues where it stopped.
+
+Order is fixed afterwards by a selection sort that makes one swap and then reads the screen again.
+Several swaps from one reading do not converge, because every move shifts the grid. A swap that
+creates a folder by accident stops the sort.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+
+def _label(entry) -> str:
+    return f"Folder:{entry['folder']}" if isinstance(entry, dict) else entry
+
+
+class Builder:
+    def __init__(self, launcher, state_file: Path | None = None, log=print):
+        self.l = launcher
+        self.state_file = state_file
+        self.log = log
+        self.done: list[str] = []
+        if state_file and state_file.exists():
+            self.done = json.loads(state_file.read_text()).get("done", [])
+
+    def _mark(self, key: str) -> None:
+        self.done.append(key)
+        if self.state_file:
+            self.state_file.write_text(json.dumps({"done": self.done}))
+
+    def add(self, name: str, page: int, onto: tuple[int, int] | None = None):
+        """Drag an app from the drawer to the page (onto a position to merge). Returns where it landed."""
+        hit = self.l.drawer_search(name)
+        if not hit:
+            self.log(f"  not in the drawer: {name}")
+            return None
+        tx, ty = onto if onto else self.l.at(0.5, 0.71)
+        self.l.drag(hit.x, hit.y, tx, ty, 1800)
+        landed = [n for n in self.l.icons(page) if n.label == hit.label]
+        return landed[0] if landed else None
+
+    def build_page(self, page: int, entries: list) -> None:
+        for e in entries:
+            key = f"p{page}:{_label(e)}"
+            if key in self.done:
+                continue
+            if isinstance(e, str):
+                r = self.add(e, page)
+                self.log(f"  {e}: {'placed' if r else 'FAILED'}")
+            else:
+                self._build_folder(page, e["folder"], e["apps"])
+            self._mark(key)
+
+    def _build_folder(self, page: int, name: str, apps: list[str]) -> None:
+        if not apps:
+            return
+        before = {n.label for n in self.l.icons(page) if n.folder}
+        first = self.add(apps[0], page)
+        if not first:
+            self.log(f"  folder {name}: cannot place {apps[0]}")
+            return
+        if len(apps) == 1:
+            self.log(f"  folder {name} has one app, placed it loose")
+            return
+        self.add(apps[1], page, onto=(first.x, first.y))
+        new = [n for n in self.l.icons(page) if n.folder and n.label not in before]
+        if not new:
+            self.log(f"  folder {name}: no folder formed")
+            return
+        # Identify the new folder by being new, never by its auto-name (two can share one).
+        self.l.tap(new[0].x, new[0].y)
+        self.l.rename_open_folder(name)
+        for app in apps[2:]:
+            target = [n for n in self.l.icons(page) if n.label == f"Folder:{name}"]
+            if not target:
+                self.log(f"  folder {name}: lost it after renaming")
+                return
+            self.add(app, page, onto=(target[0].x, target[0].y))
+        self.log(f"  folder {name}: {len(apps)} apps")
+
+    def build(self, layout: dict) -> None:
+        for page, entries in enumerate(layout.get("pages", [])):
+            self.log(f"page {page + 1}")
+            self.build_page(page, entries)
+
+    def order(self, page: int, wanted: list[str]) -> bool:
+        """Selection sort with one swap per reading. Returns False when it had to stop."""
+        for i, label in enumerate(wanted):
+            items = self.l.icons(page)
+            names = [n.label for n in items]
+            if i >= len(items) or names[i] == label:
+                continue
+            if label not in names:
+                self.log(f"  {label} is not on page {page + 1}")
+                continue
+            folders = {n.label for n in items if n.folder}
+            j = names.index(label)
+            self.l.drag(items[j].x, items[j].y, items[i].x, items[i].y, 2000)
+            after = {n.label for n in self.l.icons(page) if n.folder}
+            if after - folders:
+                self.log(f"  stopped: the swap created a folder {sorted(after - folders)}")
+                return False
+        return True
+
+    def order_all(self, layout: dict) -> bool:
+        ok = True
+        for page, entries in enumerate(layout.get("pages", [])):
+            ok = self.order(page, [_label(e) for e in entries]) and ok
+        return ok

iphone2android/android/debloat.py

@@ -0,0 +1,48 @@
+"""Remove preinstalled apps for the current user, without root.
+
+`pm uninstall --user 0` keeps the app on the system partition, so it can come back with
+`cmd package install-existing <package>`. Some system parts refuse and are disabled instead.
+"""
+from __future__ import annotations
+
+from .adb import Adb
+
+# Never removed, whatever the list says.
+PROTECTED = {
+    "com.google.android.euicc",  # eSIM
+    "com.android.vending",  # Play Store
+    "com.google.android.gms",  # Play services
+    "com.android.phone",
+    "com.android.settings",
+    "com.android.systemui",
+    "com.google.android.dialer",
+    "com.android.dialer",
+    "com.google.android.apps.messaging",
+    "com.android.mms",
+    "com.android.launcher",
+}
+
+
+def remove(adb: Adb, packages: list[str], keep: set[str] = frozenset(), dry_run: bool = False) -> dict[str, str]:
+    out: dict[str, str] = {}
+    for pkg in packages:
+        if pkg in PROTECTED or pkg in keep:
+            out[pkg] = "kept"
+            continue
+        if not adb.installed(pkg):
+            out[pkg] = "absent"
+            continue
+        if dry_run:
+            out[pkg] = "would remove"
+            continue
+        r = adb.shell(f"pm uninstall --user 0 {pkg}")
+        if "Success" in r:
+            out[pkg] = "removed"
+            continue
+        r2 = adb.shell(f"pm disable-user --user 0 {pkg}")
+        out[pkg] = "disabled" if "disabled" in r2.lower() else f"failed: {r.strip()[:80]}"
+    return out
+
+
+def restore(adb: Adb, package: str) -> bool:
+    return "installed" in adb.shell(f"cmd package install-existing {package}").lower()

iphone2android/android/launcher.py

@@ -0,0 +1,134 @@
+"""Drive a stock home screen through its UI, which is the only way on locked-down launchers.
+
+On ColorOS (OPPO, OnePlus) the launcher database, its content provider and shortcut pinning are all
+closed to adb without root, so icons are moved the way a person moves them. Positions scale with
+the screen size. Tested on ColorOS 16 (Android 16). Other launchers need their own tuning.
+
+Rules learned the hard way:
+- Re-read the screen before every drag. The grid moves after each change.
+- Dropping an icon onto another makes a folder. Dropping onto a folder adds to it.
+- A folder is renamed by tapping its title, selecting all, typing and pressing BACK (not ENTER).
+- Icons cannot be dragged out of a folder. Long-press inside the open folder and choose Remove.
+"""
+from __future__ import annotations
+
+import time
+
+from . import ui
+from .adb import Adb
+
+
+class Launcher:
+    def __init__(self, adb: Adb, pause: float = 1.0):
+        self.adb = adb
+        self.pause = pause
+        self.w, self.h = adb.screen_size()
+
+    def _sleep(self, s: float) -> None:
+        time.sleep(s * self.pause)
+
+    # positions as fractions of the screen, measured on a 1264x2780 screen
+    def at(self, fx: float, fy: float) -> tuple[int, int]:
+        return int(self.w * fx), int(self.h * fy)
+
+    def dock_top(self) -> int:
+        return int(self.h * 0.845)
+
+    def in_dock(self, n: ui.Node) -> bool:
+        return n.y > self.dock_top()
+
+    def dump(self) -> list[ui.Node]:
+        return ui.dump(self.adb)
+
+    def home(self) -> None:
+        for _ in range(2):
+            self.adb.shell("input keyevent KEYCODE_HOME")
+            self._sleep(1.6)
+
+    def page_next(self) -> None:
+        (x1, y), (x2, _) = self.at(0.87, 0.58), self.at(0.16, 0.58)
+        # 250 ms. A slower swipe is read as a drag and does not change page.
+        self.adb.shell(f"input swipe {x1} {y} {x2} {y} 250")
+        self._sleep(1.8)
+
+    def goto(self, page: int) -> None:
+        self.home()  # HOME is page 0; swiping left from it opens the feed, not a page
+        for _ in range(page):
+            self.page_next()
+
+    def drag(self, x1: int, y1: int, x2: int, y2: int, ms: int = 600) -> None:
+        # About 600 ms merges reliably. A long hover opens the folder under the finger instead.
+        self.adb.shell(f"input draganddrop {x1} {y1} {x2} {y2} {ms}")
+        self._sleep(2.5)
+
+    def tap(self, x: int, y: int) -> None:
+        self.adb.shell(f"input tap {x} {y}")
+        self._sleep(1.8)
+
+    def icons(self, page: int) -> list[ui.Node]:
+        """Icons and folders on a page, in reading order, without the dock and the label nodes of folders."""
+        self.goto(page)
+        nodes = self.dump()
+        folder_names = {n.label for n in nodes if n.folder}
+        items = [n for n in nodes if n.clickable and n.cls in ("TextView", "FrameLayout")
+                 and not self.in_dock(n) and f"Folder:{n.label}" not in folder_names]
+        return sorted(items, key=lambda n: (n.y, n.x))
+
+    def drawer_search(self, term: str) -> ui.Node | None:
+        """Open the app drawer, search, and return the first result whose name contains the first word."""
+        self.home()
+        (x, y1), (_, y2) = self.at(0.5, 0.83), self.at(0.5, 0.32)
+        self.adb.shell(f"input swipe {x} {y1} {x} {y2} 300")
+        self._sleep(2.5)
+        nodes = self.dump()
+        field = [n for n in nodes if n.cls == "EditText"] or [n for n in nodes if n.label.lower().startswith("search")]
+        if not field:
+            return None
+        self.tap(field[0].x, field[0].y)
+        self.adb.shell("input keycombination 113 29")  # ctrl+a
+        self.adb.shell("input text " + term.replace(" ", "%s"))
+        self._sleep(2.2)
+        first = term.split()[0].lower()
+        for n in self.dump():
+            if n.cls == "TextView" and n.y < self.dock_top() and first in n.label.lower():
+                return n
+        return None
+
+    def rename_open_folder(self, name: str) -> bool:
+        field = [n for n in self.dump() if n.cls == "EditText"]
+        if not field:
+            return False
+        self.tap(field[0].x, field[0].y)
+        self.adb.shell("input keycombination 113 29")
+        self.adb.shell("input text " + name.replace(" ", "%s"))
+        self._sleep(1.2)
+        self.adb.shell("input keyevent KEYCODE_BACK")  # ENTER does not commit the name, BACK does
+        self._sleep(2.0)
+        return True
+
+    def long_press(self, x: int, y: int, seconds: float = 1.4) -> None:
+        # One shell, so the finger stays down for the whole gesture.
+        self.adb.shell(f"input motionevent DOWN {x} {y}; sleep {seconds}; input motionevent UP {x} {y}")
+        self._sleep(1.5)
+
+    def set_autofill(self, on: bool) -> str:
+        """Toggle Home screen settings > Icon autofill. Build with it off, then turn it on once to pack the grid."""
+        self.home()
+        self.long_press(*self.at(0.5, 0.54))
+        settings = [n for n in self.dump() if n.label == "Home screen settings" and n.clickable]
+        if not settings:
+            self.home()
+            return "not found"
+        self.tap(settings[0].x, settings[0].y)
+        nodes = self.dump()
+        row = [n for n in nodes if n.label == "Icon autofill"]
+        switch = [n for n in nodes if n.cls == "Switch" and row and abs(n.y - row[0].y) < 60]
+        state = "not found"
+        if switch:
+            current = switch[0].label.lower() == "on"
+            if current != on:
+                self.tap(switch[0].x, switch[0].y)
+            state = "on" if on else "off"
+        self.adb.shell("input keyevent KEYCODE_BACK")
+        self.home()
+        return state

iphone2android/android/play.py

@@ -0,0 +1,61 @@
+"""Play Store checks and installs.
+
+Guessed package names are often wrong (a bank's Android package rarely matches its iOS bundle id),
+so every mapping is checked against the live Play Store page before anything is installed.
+Installs are free apps only, by opening the store page and pressing Install, like a person would.
+"""
+from __future__ import annotations
+
+import time
+import urllib.error
+import urllib.request
+
+from .adb import Adb
+from .ui import find_button
+
+PLAY_URL = "https://play.google.com/store/apps/details?id={package}&hl=en"
+INSTALL_LABELS = {"Install", "Εγκατάσταση", "Instalar", "Installer", "Installieren", "Installa"}
+DONE_LABELS = {"Open", "Play", "Uninstall", "Update", "Άνοιγμα", "Abrir", "Ouvrir", "Öffnen", "Apri"}
+
+
+def listed(package: str, url: str = PLAY_URL, timeout: float = 15.0) -> bool | None:
+    """True when the Play Store has a page for the package, False when it does not, None on network errors."""
+    req = urllib.request.Request(url.format(package=package), headers={"user-agent": "Mozilla/5.0"})
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as r:
+            return r.status == 200
+    except urllib.error.HTTPError as e:
+        return False if e.code == 404 else None
+    except (urllib.error.URLError, TimeoutError):
+        return None
+
+
+def install(adb: Adb, package: str, log=print, wait_s: float = 240, poll_s: float = 6) -> str:
+    """Install one free app through the Play Store app. Returns installed, present, no-button or timeout."""
+    if adb.installed(package):
+        return "present"
+    # market:// can open an OEM store chooser, so the Play Store is named explicitly.
+    adb.run("shell", "am", "start", "-a", "android.intent.action.VIEW",
+            "-d", f"https://play.google.com/store/apps/details?id={package}", "-p", "com.android.vending")
+    button = None
+    for _ in range(10):  # the store page renders slowly under load
+        time.sleep(2.5)
+        button = find_button(adb, INSTALL_LABELS | DONE_LABELS)
+        if button:
+            break
+    if not button:
+        adb.shell("input keyevent KEYCODE_BACK")
+        return "no-button"
+    label, (x, y) = button
+    if label in DONE_LABELS:
+        adb.shell("input keyevent KEYCODE_BACK")
+        return "present"
+    adb.shell(f"input tap {x} {y}")
+    deadline = time.time() + wait_s
+    while time.time() < deadline:
+        time.sleep(poll_s)
+        if adb.installed(package):
+            adb.shell("input keyevent KEYCODE_BACK")
+            return "installed"
+    adb.shell("input keyevent KEYCODE_BACK")
+    return "timeout"

iphone2android/android/ui.py

@@ -0,0 +1,54 @@
+"""Read the phone's screen through uiautomator."""
+from __future__ import annotations
+
+import re
+import xml.etree.ElementTree as ET
+from dataclasses import dataclass
+
+from .adb import Adb
+
+
+@dataclass
+class Node:
+    label: str
+    x: int
+    y: int
+    cls: str
+    clickable: bool
+
+    @property
+    def folder(self) -> bool:
+        return self.label.startswith("Folder:")
+
+
+def _center(bounds: str) -> tuple[int, int]:
+    m = [int(v) for v in re.findall(r"-?\d+", bounds)]
+    return (m[0] + m[2]) // 2, (m[1] + m[3]) // 2
+
+
+def parse(xml: str) -> list[Node]:
+    try:
+        root = ET.fromstring(xml)
+    except ET.ParseError:
+        return []
+    out = []
+    for n in root.iter("node"):
+        label = (n.get("content-desc") or "").strip() or (n.get("text") or "").strip()
+        bounds = n.get("bounds", "")
+        if not label or not bounds:
+            continue
+        x, y = _center(bounds)
+        out.append(Node(label, x, y, n.get("class", "").split(".")[-1], n.get("clickable") == "true"))
+    return out
+
+
+def dump(adb: Adb) -> list[Node]:
+    adb.shell("uiautomator dump /sdcard/window.xml")
+    return parse(adb.shell("cat /sdcard/window.xml"))
+
+
+def find_button(adb: Adb, labels: set[str]):
+    for n in dump(adb):
+        if n.label in labels:
+            return n.label, (n.x, n.y)
+    return None

iphone2android/backup.py

@@ -0,0 +1,143 @@
+"""Open an encrypted iPhone backup made by Finder or iTunes, and copy files out of it.
+
+Backups live in ~/Library/Application Support/MobileSync/Backup/<UDID>/ on macOS and in
+%APPDATA%\\Apple Computer\\MobileSync\\Backup on Windows. Info.plist and Manifest.plist can be read
+without the password. Everything else needs the backup password.
+
+A file is named by its domain and its relative path. The same relative path can exist in several
+domains, so files are looked up in the decrypted manifest by both, and the manifest row is handed
+to the decryptor (it has no domain parameter).
+"""
+from __future__ import annotations
+
+import os
+import plistlib
+import shutil
+import sqlite3
+from collections import Counter, defaultdict
+from dataclasses import dataclass
+from pathlib import Path
+
+DEFAULT_ROOT = Path.home() / "Library/Application Support/MobileSync/Backup"
+
+# The files worth pulling, by what they are and where each can go on Android.
+KNOWN = [
+    ("HomeDomain", "Library/SMS/sms.db", "sms.db", "Messages", "SMS Backup & Restore XML"),
+    ("HomeDomain", "Library/CallHistoryDB/CallHistory.storedata", "CallHistory.storedata", "Call history", "SMS Backup & Restore XML"),
+    ("HomeDomain", "Library/AddressBook/AddressBook.sqlitedb", "AddressBook.sqlitedb", "Contacts", "vCard"),
+    ("HomeDomain", "Library/Calendar/Calendar.sqlitedb", "Calendar.sqlitedb", "Calendars", "ICS"),
+    ("HomeDomain", "Library/Safari/Bookmarks.db", "Safari_Bookmarks.db", "Safari bookmarks", "bookmarks HTML"),
+    ("AppDomainGroup-group.com.apple.notes", "NoteStore.sqlite", "NoteStore.sqlite", "Apple Notes", "read with an Apple Notes parser"),
+    ("AppDomainGroup-group.net.whatsapp.WhatsApp.shared", "ChatStorage.sqlite", "ChatStorage.sqlite", "WhatsApp chats", "a WhatsApp iOS-to-Android migrator"),
+    ("HomeDomain", "Library/SpringBoard/IconState.plist", "IconState.plist", "Home screen layout", "iphone2android layout"),
+]
+
+
+def backups(root: Path = DEFAULT_ROOT) -> list[dict]:
+    """Every backup under root, with what its Info.plist says (no password needed)."""
+    out = []
+    if not root.is_dir():
+        return out
+    for d in sorted(root.iterdir()):
+        info = d / "Info.plist"
+        if not info.is_file():
+            continue
+        with open(info, "rb") as f:
+            p = plistlib.load(f)
+        out.append({
+            "udid": d.name,
+            "name": p.get("Device Name", ""),
+            "model": p.get("Product Type", ""),
+            "ios": p.get("Product Version", ""),
+            "date": str(p.get("Last Backup Date", "")),
+            "apps": len(p.get("Installed Applications", []) or []),
+        })
+    return out
+
+
+def installed_apps(udid: str, root: Path = DEFAULT_ROOT) -> list[str]:
+    """Bundle ids of the apps installed when the backup was made (no password needed)."""
+    with open(root / udid / "Info.plist", "rb") as f:
+        return list(plistlib.load(f).get("Installed Applications", []) or [])
+
+
+@dataclass
+class Backup:
+    udid: str
+    impl: object  # the iOSbackup object
+    manifest: Path  # durable copy of the decrypted Manifest.db
+
+    def _row(self, domain: str, relative_path: str) -> dict | None:
+        con = sqlite3.connect(self.manifest)
+        con.row_factory = sqlite3.Row
+        try:
+            r = con.execute("SELECT * FROM Files WHERE domain=? AND relativePath=?", (domain, relative_path)).fetchone()
+        finally:
+            con.close()
+        return dict(r) if r else None
+
+    def rows(self, sql_where: str, params: tuple = ()) -> list[dict]:
+        con = sqlite3.connect(self.manifest)
+        con.row_factory = sqlite3.Row
+        try:
+            return [dict(r) for r in con.execute(f"SELECT * FROM Files WHERE {sql_where}", params)]
+        finally:
+            con.close()
+
+    def copy_entry(self, row: dict, target_folder: Path, target_name: str) -> Path:
+        entry = dict(row)
+        entry["manifest"] = entry.pop("file")  # the library wants the blob under this key
+        target_folder.mkdir(parents=True, exist_ok=True)
+        self.impl.getFileDecryptedCopy(manifestEntry=entry, targetName=target_name, targetFolder=str(target_folder))
+        return target_folder / target_name
+
+    def copy(self, domain: str, relative_path: str, target_folder: Path, target_name: str) -> Path | None:
+        row = self._row(domain, relative_path)
+        if not row:
+            return None
+        return self.copy_entry(row, target_folder, target_name)
+
+    def inventory(self) -> dict:
+        """Files and bytes per domain, read from the manifest's own size field."""
+        from iOSbackup import iOSbackup
+
+        files, size = Counter(), defaultdict(int)
+        for r in self.rows("flags=1"):
+            files[r["domain"]] += 1
+            try:
+                size[r["domain"]] += int(iOSbackup.getFileInfo(r["file"]).get("size") or 0)
+            except Exception:  # noqa: BLE001 - an unreadable blob only loses its size
+                pass
+        return {d: {"files": n, "bytes": size[d]} for d, n in files.most_common()}
+
+
+def open_backup(udid: str, password: str, workdir: Path, root: Path = DEFAULT_ROOT) -> Backup:
+    from iOSbackup import iOSbackup
+
+    impl = iOSbackup(udid=udid, cleartextpassword=password, backuproot=str(root))
+    workdir.mkdir(parents=True, exist_ok=True)
+    # The decrypted manifest lives in a temp folder that is cleaned up, so keep a copy.
+    durable = workdir / "Manifest.decrypted.db"
+    shutil.copyfile(impl.manifestDB, durable)
+    return Backup(udid=udid, impl=impl, manifest=durable)
+
+
+def password_from_env_or_prompt() -> str:
+    pw = os.environ.get("IPHONE_BACKUP_PASSWORD")
+    if pw:
+        return pw
+    import getpass
+
+    return getpass.getpass("Backup password: ")
+
+
+def extract_known(b: Backup, out: Path) -> list[tuple[str, str, Path | None]]:
+    """Copy every known database out. Returns (label, destination format, path or None)."""
+    got = []
+    for domain, rel, name, label, dest in KNOWN:
+        try:
+            p = b.copy(domain, rel, out, name)
+        except Exception:  # noqa: BLE001 - a file that fails to decrypt is reported as missing
+            p = None
+        got.append((label, dest, p))
+    return got