whatferry 1.0.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (57) hide show
  1. whatferry/__init__.py +7 -0
  2. whatferry/adb.py +336 -0
  3. whatferry/android.py +173 -0
  4. whatferry/android_writer.py +107 -0
  5. whatferry/backup_writer.py +426 -0
  6. whatferry/cli.py +586 -0
  7. whatferry/compat.py +172 -0
  8. whatferry/convert.py +489 -0
  9. whatferry/ios.py +302 -0
  10. whatferry/ios_backup.py +251 -0
  11. whatferry/iphone.py +313 -0
  12. whatferry/preview.py +239 -0
  13. whatferry/restore.py +75 -0
  14. whatferry/schema.py +249 -0
  15. whatferry/schemas/CHANGES.md +54 -0
  16. whatferry/schemas/android/778707c93e75c22c.json +13142 -0
  17. whatferry/schemas/ios/3ca296bd35e652d3.json +1627 -0
  18. whatferry/sqlite_summary.py +90 -0
  19. whatferry/to_android.py +457 -0
  20. whatferry/ui/__init__.py +1 -0
  21. whatferry/ui/server.py +352 -0
  22. whatferry/ui/static/ar-PdUTw834.js +1 -0
  23. whatferry/ui/static/bn-B2AYIo7N.js +1 -0
  24. whatferry/ui/static/de-C3RQ3ckb.js +1 -0
  25. whatferry/ui/static/es-DqKB4dTx.js +1 -0
  26. whatferry/ui/static/fa-Djdjr8u_.js +1 -0
  27. whatferry/ui/static/fr-oAun1kF3.js +1 -0
  28. whatferry/ui/static/geist-cyrillic-ext-wght-normal-DjL33-gN.woff2 +0 -0
  29. whatferry/ui/static/geist-cyrillic-wght-normal-BEAKL7Jp.woff2 +0 -0
  30. whatferry/ui/static/geist-latin-ext-wght-normal-DC-KSUi6.woff2 +0 -0
  31. whatferry/ui/static/geist-latin-wght-normal-BgDaEnEv.woff2 +0 -0
  32. whatferry/ui/static/geist-vietnamese-wght-normal-6IgcOCM7.woff2 +0 -0
  33. whatferry/ui/static/he-Cwsem8NY.js +1 -0
  34. whatferry/ui/static/hi-DuwkLPZ2.js +1 -0
  35. whatferry/ui/static/icon.svg +6 -0
  36. whatferry/ui/static/id-rkeenv-I.js +1 -0
  37. whatferry/ui/static/index-BAKNHQPa.css +2 -0
  38. whatferry/ui/static/index-Dmv0Fr7V.js +50 -0
  39. whatferry/ui/static/index.html +16 -0
  40. whatferry/ui/static/it-DjkMV3-3.js +1 -0
  41. whatferry/ui/static/ms-XjB2Ih3s.js +1 -0
  42. whatferry/ui/static/nl-siipj1n_.js +1 -0
  43. whatferry/ui/static/pl-D2cnciFi.js +1 -0
  44. whatferry/ui/static/pt-CZE-dXu0.js +1 -0
  45. whatferry/ui/static/ro-DEUvUIDB.js +1 -0
  46. whatferry/ui/static/tr-DzamloQB.js +1 -0
  47. whatferry/ui/static/uk-BftZvIO3.js +1 -0
  48. whatferry/ui/static/ur-D4eBHhUR.js +1 -0
  49. whatferry/ui/static/zh-Hant-DTYHSMpc.js +1 -0
  50. whatferry/ui/static/zh-s_mV-S3N.js +1 -0
  51. whatferry/ui/wizard.py +805 -0
  52. whatferry/workdir.py +170 -0
  53. whatferry-1.0.0.dist-info/METADATA +449 -0
  54. whatferry-1.0.0.dist-info/RECORD +57 -0
  55. whatferry-1.0.0.dist-info/WHEEL +4 -0
  56. whatferry-1.0.0.dist-info/entry_points.txt +3 -0
  57. whatferry-1.0.0.dist-info/licenses/LICENSE +674 -0
whatferry/__init__.py ADDED
@@ -0,0 +1,7 @@
1
+ """whatferry: move WhatsApp chats between Android and iPhone, in either direction."""
2
+
3
+
4
+ def main() -> int:
5
+ from whatferry.cli import main
6
+
7
+ return main()
whatferry/adb.py ADDED
@@ -0,0 +1,336 @@
1
+ """Copy WhatsApp backups off, and a written one onto, an Android phone with adb (USB debugging).
2
+
3
+ Lists WhatsApp's backup files and pulls one; a pull is only allowed for a
4
+ path the same phone listed a moment before, so nothing here can be used to
5
+ read other files off the phone. The one write, `push`, only goes into one of
6
+ WhatsApp's own folders and never replaces a file already there.
7
+ """
8
+
9
+ import os
10
+ import re
11
+ import shlex
12
+ import shutil
13
+ import subprocess
14
+ import sys
15
+ from dataclasses import asdict, dataclass
16
+ from datetime import datetime
17
+ from pathlib import Path
18
+
19
+ # Where people get adb: Android Studio's SDK, the standalone platform-tools,
20
+ # package managers (on PATH), or mise's android-sdk.
21
+ SDK_FOLDERS = (
22
+ "~/Library/Android/sdk",
23
+ "~/Android/Sdk",
24
+ "~/AppData/Local/Android/Sdk",
25
+ )
26
+ MISE_SDKS = "~/.local/share/mise/installs/android-sdk"
27
+
28
+ # Every place WhatsApp and WhatsApp Business keep backups: per account on
29
+ # phones with more than one account (accounts/<n>/), the shared folder on
30
+ # phones with one, and the pre-Android 11 location.
31
+ BACKUP_GLOBS = (
32
+ "/sdcard/Android/media/com.whatsapp/WhatsApp/Databases/msgstore*",
33
+ "/sdcard/Android/media/com.whatsapp/WhatsApp/accounts/*/Databases/msgstore*",
34
+ "'/sdcard/Android/media/com.whatsapp.w4b/WhatsApp Business'/Databases/msgstore*",
35
+ "'/sdcard/Android/media/com.whatsapp.w4b/WhatsApp Business'/accounts/*/Databases/msgstore*",
36
+ "/sdcard/WhatsApp/Databases/msgstore*",
37
+ "'/sdcard/WhatsApp Business'/Databases/msgstore*",
38
+ )
39
+
40
+ TIMEOUT = 30
41
+ PULL_TIMEOUT = 600
42
+ # Copies over USB, and moves on the phone's storage, get this much longer
43
+ # per byte on top of PULL_TIMEOUT: a slow cable does about 5 MB/s.
44
+ SLOW_BYTES_PER_SECOND = 5_000_000
45
+
46
+
47
+ def _timeout_for(size: int) -> int:
48
+ return PULL_TIMEOUT + size // SLOW_BYTES_PER_SECOND
49
+
50
+ # A phone says what it can do in `adb devices`: only "device" can be used.
51
+ STATES = {
52
+ "device": "ready",
53
+ "unauthorized": "Unlock the phone and tap Allow on “Allow USB debugging?”.",
54
+ "offline": "The phone isn't answering: unplug it, plug it back in, and unlock it.",
55
+ "no permissions": "This computer isn't allowed to talk to the phone (on Linux, add a udev rule for Android).",
56
+ "authorizing": "Waiting for you to tap Allow on the phone.",
57
+ }
58
+
59
+
60
+ class AdbError(Exception):
61
+ pass
62
+
63
+
64
+ def find_adb(env=os.environ) -> Path | None:
65
+ """The first adb that runs: WHATFERRY_ADB, PATH, then the usual SDK folders.
66
+
67
+ Each candidate must answer `adb version`: a version-manager shim on PATH
68
+ can exist and still refuse to run outside its project.
69
+ """
70
+ exe = "adb.exe" if sys.platform == "win32" else "adb"
71
+ if env.get("WHATFERRY_ADB"):
72
+ return Path(env["WHATFERRY_ADB"]).expanduser()
73
+ candidates = [Path(p) for p in [shutil.which("adb")] if p]
74
+ candidates += [Path(env[v]) / "platform-tools" / exe
75
+ for v in ("ANDROID_HOME", "ANDROID_SDK_ROOT") if env.get(v)]
76
+ candidates += [Path(p).expanduser() / "platform-tools" / exe for p in SDK_FOLDERS]
77
+ if env.get("LOCALAPPDATA"):
78
+ candidates.append(Path(env["LOCALAPPDATA"]) / "Android" / "Sdk" / "platform-tools" / exe)
79
+ candidates += sorted(Path(MISE_SDKS).expanduser().glob(f"*/platform-tools/{exe}"), reverse=True)
80
+ return next((c for c in candidates if c.is_file() and _answers(c)), None)
81
+
82
+
83
+ def _answers(adb: Path) -> bool:
84
+ try:
85
+ result = subprocess.run([str(adb), "version"], capture_output=True, text=True, timeout=10)
86
+ except (OSError, subprocess.TimeoutExpired):
87
+ return False
88
+ return result.returncode == 0 and "Android Debug Bridge" in result.stdout
89
+
90
+
91
+ def _run(adb: Path, *args: str, timeout: int = TIMEOUT) -> subprocess.CompletedProcess:
92
+ try:
93
+ return subprocess.run([str(adb), *args], capture_output=True, text=True, timeout=timeout)
94
+ except FileNotFoundError:
95
+ raise AdbError(f"adb not found at {adb}") from None
96
+ except subprocess.TimeoutExpired:
97
+ raise AdbError("adb didn't answer in time: unplug the phone, plug it back in, and unlock it") from None
98
+
99
+
100
+ @dataclass
101
+ class Device:
102
+ serial: str
103
+ state: str
104
+ model: str | None
105
+ ready: bool
106
+ advice: str | None
107
+
108
+
109
+ def devices(adb: Path) -> list[Device]:
110
+ result = _run(adb, "devices", "-l")
111
+ if result.returncode != 0:
112
+ raise AdbError(f"adb couldn't list phones: {(result.stderr or result.stdout).strip() or 'no reason given'}")
113
+ out = result.stdout
114
+ found = []
115
+ for line in out.splitlines()[1:]:
116
+ if not line.strip() or line.startswith("*"):
117
+ continue
118
+ serial, _, rest = line.partition(" ")
119
+ rest = rest.strip()
120
+ state = next((s for s in STATES if rest.startswith(s)), rest.split(" ")[0] if rest else "unknown")
121
+ model = re.search(r"\bmodel:(\S+)", rest)
122
+ found.append(Device(
123
+ serial=serial.strip(), state=state,
124
+ model=model.group(1).replace("_", " ") if model else None,
125
+ ready=state == "device",
126
+ advice=None if state == "device" else STATES.get(state, f"adb says “{state}”."),
127
+ ))
128
+ return found
129
+
130
+
131
+ @dataclass
132
+ class PhoneBackup:
133
+ path: str
134
+ name: str
135
+ size: int
136
+ modified: str
137
+ app: str
138
+ account: str | None
139
+ kind: str
140
+ usable: bool
141
+ note: str | None
142
+
143
+ @property
144
+ def local_name(self) -> str:
145
+ app = "whatsapp-business" if self.app == "WhatsApp Business" else "whatsapp"
146
+ account = f"-account-{self.account}" if self.account else ""
147
+ return f"{app}{account}-{self.name}"
148
+
149
+
150
+ def _describe(path: str, size: int, mtime: int) -> PhoneBackup:
151
+ name = path.rsplit("/", 1)[-1]
152
+ account = re.search(r"/accounts/(\d+)/", path)
153
+ if name.endswith(".crypt15"):
154
+ kind, usable, note = "crypt15", True, None
155
+ elif re.search(r"\.crypt1[24]$", name):
156
+ kind, usable = name.rsplit(".", 1)[-1], False
157
+ note = ("Older encryption: its key only exists on a rooted phone. Turn on the 64-digit "
158
+ "encrypted backup and back up again to get a .crypt15 file.")
159
+ elif name.endswith(".db"):
160
+ kind, usable, note = "plain", True, None
161
+ else:
162
+ kind, usable, note = "other", False, "Not a WhatsApp chat backup."
163
+ if "increment" in name:
164
+ usable, note = False, "A partial (incremental) backup; use the full msgstore file."
165
+ return PhoneBackup(
166
+ path=path, name=name, size=size,
167
+ modified=datetime.fromtimestamp(mtime).astimezone().isoformat(timespec="seconds"),
168
+ app="WhatsApp Business" if "w4b" in path or "WhatsApp Business" in path else "WhatsApp",
169
+ account=account.group(1) if account else None,
170
+ kind=kind, usable=usable, note=note,
171
+ )
172
+
173
+
174
+ def phone_backups(adb: Path, serial: str) -> list[PhoneBackup]:
175
+ """Every WhatsApp chat backup on the phone, newest first."""
176
+ # stat on globs the phone's own shell expands; folders that don't exist
177
+ # just print nothing.
178
+ # `; true`: stat fails for globs that match nothing, which is fine; a
179
+ # failure of adb itself (the phone gone) still shows.
180
+ command = "stat -c '%s|%Y|%n' " + " ".join(BACKUP_GLOBS) + " 2>/dev/null; true"
181
+ result = _run(adb, "-s", serial, "shell", command)
182
+ if result.returncode != 0:
183
+ raise AdbError(f"the phone didn't answer: {(result.stderr or result.stdout).strip() or 'adb gave no reason'}")
184
+ out = result.stdout
185
+ found = []
186
+ for line in out.splitlines():
187
+ parts = line.strip().split("|", 2)
188
+ if len(parts) == 3 and parts[0].isdigit() and parts[1].isdigit():
189
+ found.append(_describe(parts[2], int(parts[0]), int(parts[1])))
190
+ # Usable first, then newest.
191
+ return sorted(found, key=lambda b: (b.usable, b.modified), reverse=True)
192
+
193
+
194
+ def default_destination() -> Path:
195
+ return Path.home() / "whatferry-android"
196
+
197
+
198
+ def pull(adb: Path, serial: str, remote: str, dest_folder: Path | None = None) -> Path:
199
+ """Copy one backup the phone just listed into a private folder."""
200
+ listed = {b.path: b for b in phone_backups(adb, serial)}
201
+ backup = listed.get(remote)
202
+ if backup is None:
203
+ raise AdbError("that file isn't one of the phone's WhatsApp backups (list them again)")
204
+ folder = dest_folder or default_destination()
205
+ folder.mkdir(mode=0o700, parents=True, exist_ok=True)
206
+ target = folder / backup.local_name
207
+ partial = folder / f".{backup.local_name}.part"
208
+ partial.unlink(missing_ok=True)
209
+ result = _run(adb, "-s", serial, "pull", remote, str(partial), timeout=_timeout_for(backup.size))
210
+ if result.returncode != 0 or not partial.exists():
211
+ partial.unlink(missing_ok=True)
212
+ raise AdbError(f"copying failed: {(result.stderr or result.stdout).strip() or 'adb gave no reason'}")
213
+ if (got := partial.stat().st_size) != backup.size:
214
+ partial.unlink()
215
+ raise AdbError(f"the copy is incomplete ({got} of {backup.size} bytes): let WhatsApp finish its backup, "
216
+ "then copy again")
217
+ partial.chmod(0o600)
218
+ os.replace(partial, target)
219
+ return target
220
+
221
+
222
+ WHATSAPP_ROOT = "/sdcard/Android/media/com.whatsapp/WhatsApp"
223
+
224
+
225
+ def whatsapp_folders(adb: Path, serial: str) -> list[str]:
226
+ """Where WhatsApp keeps an account's backup and media: the main folder, and accounts/<n>/ ones listed."""
227
+ found = {WHATSAPP_ROOT}
228
+ for backup in phone_backups(adb, serial):
229
+ if backup.path.startswith(f"{WHATSAPP_ROOT}/accounts/") and "/Databases/" in backup.path:
230
+ found.add(backup.path.split("/Databases/")[0])
231
+ return sorted(found)
232
+
233
+
234
+ def push(adb: Path, serial: str, root: str, folder: Path) -> dict:
235
+ """Copy a written WhatsApp/ folder onto the phone, into one of its WhatsApp folders.
236
+
237
+ Nothing on the phone is replaced: a backup already there is kept under a
238
+ new name (WhatsApp only restores msgstore.db.crypt15), and media files
239
+ are copied without overwriting any file of the same name. If a step
240
+ fails, what changed so far is undone where it can be, and the error says
241
+ what is left.
242
+ """
243
+ if root not in whatsapp_folders(adb, serial):
244
+ raise AdbError("that isn't one of the phone's WhatsApp folders (list them again)")
245
+ backup = folder / "Databases" / "msgstore.db.crypt15"
246
+ if not backup.is_file():
247
+ raise AdbError(f"{folder} has no Databases/msgstore.db.crypt15")
248
+ stamp = datetime.now().strftime("%Y%m%d-%H%M%S")
249
+ remote = f"{root}/Databases/msgstore.db.crypt15"
250
+ kept = f"{remote}.before-whatferry-{stamp}"
251
+ q = shlex.quote
252
+ _shell(adb, serial, f"mkdir -p {q(root + '/Databases')} {q(root + '/Media')}")
253
+ media = folder / "Media"
254
+ files = [p for p in media.rglob("*") if p.is_file()] if media.is_dir() else []
255
+ size = sum(p.stat().st_size for p in files)
256
+ staging = f"{root}/.whatferry-{stamp}"
257
+ phone_media = q(root + "/Media")
258
+ if files:
259
+ # Media first, into a staging folder: if the phone already has a file
260
+ # under one of these names, stop before anything on it has changed.
261
+ try:
262
+ _push(adb, serial, media, staging, _timeout_for(size))
263
+ clashes = _shell(adb, serial, f"cd {q(staging)} && find . -type f | while IFS= read -r f; do "
264
+ f"[ -e {phone_media}/\"$f\" ] && echo \"$f\"; done; true").splitlines()
265
+ except AdbError:
266
+ _remove_quietly(adb, serial, staging)
267
+ raise
268
+ if clashes:
269
+ _remove_quietly(adb, serial, staging)
270
+ raise AdbError(f"the phone already has {len(clashes)} file(s) under names the conversion uses "
271
+ f"(such as {clashes[0].removeprefix('./')}); nothing was changed")
272
+ # Then moved, not copied, into Media: the same storage, so each file
273
+ # is only renamed, however large the folder is.
274
+ try:
275
+ _shell(adb, serial, f"cd {q(staging)} && find . -type f | while IFS= read -r f; do "
276
+ f"mkdir -p {phone_media}/\"$(dirname \"$f\")\" && "
277
+ f"mv -n \"$f\" {phone_media}/\"$f\" || exit 1; done", timeout=_timeout_for(size))
278
+ except AdbError as e:
279
+ _remove_quietly(adb, serial, staging)
280
+ raise AdbError(f"{e} (some media files may already be in {root}/Media; "
281
+ "the phone's backup is unchanged)") from None
282
+ _remove_quietly(adb, serial, staging)
283
+ answer = _shell(adb, serial, f"if [ -e {q(remote)} ]; then mv {q(remote)} {q(kept)} && echo kept; fi")
284
+ try:
285
+ _push(adb, serial, backup, remote, _timeout_for(backup.stat().st_size))
286
+ except AdbError as e:
287
+ if "kept" not in answer:
288
+ raise
289
+ try:
290
+ _shell(adb, serial, f"rm -f {q(remote)} && mv {q(kept)} {q(remote)}")
291
+ except AdbError:
292
+ raise AdbError(f"{e} (the phone's own backup is kept as {kept}: "
293
+ "rename it back to msgstore.db.crypt15)") from None
294
+ raise AdbError(f"{e} (the phone's own backup is back in place)") from None
295
+ return {"root": root, "kept": kept if "kept" in answer else None, "media_files": len(files)}
296
+
297
+
298
+ def _remove_quietly(adb: Path, serial: str, remote: str) -> None:
299
+ try:
300
+ _shell(adb, serial, f"rm -rf {shlex.quote(remote)}")
301
+ except AdbError:
302
+ pass
303
+
304
+
305
+ def _shell(adb: Path, serial: str, command: str, timeout: int = TIMEOUT) -> str:
306
+ result = _run(adb, "-s", serial, "shell", command, timeout=timeout)
307
+ if result.returncode != 0:
308
+ raise AdbError(f"the phone refused: {(result.stderr or result.stdout).strip() or 'adb gave no reason'}")
309
+ return result.stdout
310
+
311
+
312
+ def _push(adb: Path, serial: str, local: Path, remote: str, timeout: int = PULL_TIMEOUT) -> None:
313
+ result = _run(adb, "-s", serial, "push", str(local), remote, timeout=timeout)
314
+ if result.returncode != 0:
315
+ raise AdbError(f"copying to the phone failed: {(result.stderr or result.stdout).strip() or 'adb gave no reason'}")
316
+
317
+
318
+ def status() -> dict:
319
+ """What the wizard shows: is adb there, which phones, which backups on each."""
320
+ adb = find_adb()
321
+ if adb is None:
322
+ return {"adb": None, "devices": []}
323
+ try:
324
+ phones = devices(adb)
325
+ except AdbError as e:
326
+ return {"adb": str(adb), "devices": [], "error": str(e)}
327
+ out = []
328
+ for phone in phones:
329
+ entry = asdict(phone)
330
+ if phone.ready:
331
+ try:
332
+ entry["backups"] = [asdict(b) | {"local_name": b.local_name} for b in phone_backups(adb, phone.serial)]
333
+ except AdbError as e:
334
+ entry["backups"], entry["error"] = [], str(e)
335
+ out.append(entry)
336
+ return {"adb": str(adb), "devices": out}
whatferry/android.py ADDED
@@ -0,0 +1,173 @@
1
+ """Read an Android WhatsApp backup: decrypt msgstore.db.crypt15 and describe it.
2
+
3
+ The backup must come from WhatsApp's end-to-end encrypted backup with the
4
+ 64-digit key option, so the key is known without root. A Java key file
5
+ pulled from a rooted phone (/data/data/com.whatsapp/files/key) works too.
6
+ """
7
+
8
+ import logging
9
+ import re
10
+ import zlib
11
+ from dataclasses import asdict, dataclass, field
12
+ from datetime import UTC, datetime
13
+ from pathlib import Path
14
+
15
+ from wa_crypt_tools.lib.db.db14 import Database14
16
+ from wa_crypt_tools.lib.db.dbfactory import DatabaseFactory
17
+ from wa_crypt_tools.lib.key.key15 import Key15
18
+ from wa_crypt_tools.lib.key.keyfactory import KeyFactory
19
+
20
+ from whatferry import sqlite_summary, workdir
21
+
22
+ # wa-crypt-tools logs freely, including a "your phone number ends with" line;
23
+ # whatferry reports what it needs itself. Even CRITICAL lines would reach
24
+ # stderr through Python's last-resort handler, so nothing gets through.
25
+ _library_log = logging.getLogger("wa_crypt_tools")
26
+ _library_log.setLevel(logging.CRITICAL + 1)
27
+ _library_log.addHandler(logging.NullHandler())
28
+ _library_log.propagate = False
29
+
30
+
31
+ class DecryptError(Exception):
32
+ pass
33
+
34
+
35
+ @dataclass
36
+ class BackupHeader:
37
+ app_version: str | None
38
+ number_ends_with: str | None
39
+
40
+
41
+ def parse_key(text: str):
42
+ """A Key15 from the 64-digit key, ignoring the spaces it is shown with."""
43
+ digits = re.sub(r"\s+", "", text).lower()
44
+ if not re.fullmatch(r"[0-9a-f]{64}", digits):
45
+ raise DecryptError("the key must be 64 hexadecimal characters (spaces are ignored)")
46
+ return KeyFactory.from_hex(digits)
47
+
48
+
49
+ def load_key(path: Path):
50
+ """A key from a file holding the 64-digit key, or a Java key file."""
51
+ raw = path.read_bytes()
52
+ try:
53
+ return parse_key(raw.decode("ascii"))
54
+ except (UnicodeDecodeError, DecryptError):
55
+ key = KeyFactory.from_file(path)
56
+ if key is None:
57
+ raise DecryptError(f"{path} is neither a 64-digit key nor a WhatsApp key file") from None
58
+ return key
59
+
60
+
61
+ def decrypt(encrypted: Path, key) -> tuple[bytes, BackupHeader]:
62
+ """The plain SQLite bytes of a crypt14 or crypt15 backup."""
63
+ with encrypted.open("rb") as f:
64
+ try:
65
+ db = DatabaseFactory.from_file(f)
66
+ except Exception as e:
67
+ raise DecryptError(f"{encrypted.name} is not a WhatsApp crypt14/15 backup: {e}") from e
68
+ if db is None:
69
+ raise DecryptError(f"{encrypted.name} is not a WhatsApp crypt14/15 backup")
70
+ if isinstance(db, Database14) and isinstance(key, Key15):
71
+ raise DecryptError(f"{encrypted.name} is a crypt14 backup: its key only exists on a rooted phone, "
72
+ "not as the 64-digit key. Turn on the end-to-end encrypted backup with the "
73
+ "64-digit key and back up again to get a .crypt15 file")
74
+ try:
75
+ payload = db.decrypt(key, f.read())
76
+ except Exception as e: # noqa: BLE001 - the library's own errors for a header it misread
77
+ raise DecryptError(f"{encrypted.name} couldn't be decrypted: {e}") from e
78
+ # The factory keeps the parsed header's info (BackupExpiry) in db.props;
79
+ # crypt12 backups have none.
80
+ props = getattr(db, "props", None)
81
+ info = props.get_proto() if props else None
82
+ header = BackupHeader(
83
+ app_version=(info.app_version or None) if info else None,
84
+ number_ends_with=(info.jidSuffix or None) if info else None,
85
+ )
86
+ # A wrong key still "decrypts", into noise: only a clean zlib stream
87
+ # holding a SQLite file proves the key matched.
88
+ inflater = zlib.decompressobj()
89
+ try:
90
+ plain = inflater.decompress(payload)
91
+ except zlib.error:
92
+ raise DecryptError("decryption failed: the key does not match this backup") from None
93
+ if not inflater.eof:
94
+ raise DecryptError("the backup is truncated (damaged or still being written)")
95
+ if not sqlite_summary.is_sqlite(plain):
96
+ raise DecryptError("decrypted data is not a SQLite database")
97
+ return plain, header
98
+
99
+
100
+ @dataclass
101
+ class Report:
102
+ source: str
103
+ header: BackupHeader | None
104
+ user_version: int
105
+ layout: str
106
+ counts: dict[str, int | None] = field(default_factory=dict)
107
+ jid_servers: dict[str, int] = field(default_factory=dict)
108
+ message_types: dict[int, int] = field(default_factory=dict)
109
+ first_message: str | None = None
110
+ last_message: str | None = None
111
+ tables: int = 0
112
+
113
+ def as_dict(self) -> dict:
114
+ return asdict(self)
115
+
116
+
117
+ # Tables the conversion will have to carry over, by what they hold.
118
+ COUNTED = {
119
+ "chats": "chat",
120
+ "messages": "message",
121
+ "media": "message_media",
122
+ "quoted replies": "message_quoted",
123
+ "reactions and other add-ons": "message_add_on",
124
+ "contact cards": "message_vcard",
125
+ "locations": "message_location",
126
+ "calls": "call_log",
127
+ "contacts and groups (jid)": "jid",
128
+ }
129
+
130
+
131
+ def describe(db_path: Path, *, source: str, header: BackupHeader | None) -> Report:
132
+ summary = sqlite_summary.summarise(db_path)
133
+ if summary.table("message"):
134
+ layout = "modern (message, chat, jid tables)"
135
+ elif summary.table("messages"):
136
+ layout = "legacy (single messages table): too old for whatferry, update WhatsApp and back up again"
137
+ else:
138
+ layout = "unrecognised: no message or messages table"
139
+ report = Report(source=source, header=header, user_version=summary.user_version,
140
+ layout=layout, tables=len(summary.tables))
141
+ report.counts = {label: summary.rows(table) for label, table in COUNTED.items()}
142
+ with sqlite_summary.open_read_only(db_path) as db:
143
+ if summary.table("jid"):
144
+ report.jid_servers = dict(db.execute(
145
+ "SELECT coalesce(server, '?'), count(*) FROM jid GROUP BY 1 ORDER BY 2 DESC"))
146
+ if summary.table("message"):
147
+ report.message_types = dict(db.execute(
148
+ "SELECT message_type, count(*) FROM message GROUP BY 1 ORDER BY 2 DESC"))
149
+ first, last = db.execute(
150
+ "SELECT min(timestamp), max(timestamp) FROM message WHERE timestamp > 0").fetchone()
151
+ report.first_message = _iso_from_millis(first)
152
+ report.last_message = _iso_from_millis(last)
153
+ return report
154
+
155
+
156
+ def _iso_from_millis(ms: int | None) -> str | None:
157
+ return datetime.fromtimestamp(ms / 1000, UTC).isoformat(timespec="seconds") if ms else None
158
+
159
+
160
+ def inspect(backup: Path, key) -> tuple[Report, Path]:
161
+ """Decrypt (or copy) the backup into a new run folder and describe it."""
162
+ run = workdir.new_run("android")
163
+ db_path = run / "msgstore.db"
164
+ header = None
165
+ if key is None:
166
+ data = backup.read_bytes()
167
+ if not sqlite_summary.is_sqlite(data):
168
+ raise DecryptError(f"{backup.name} is encrypted: give the key with --key-file")
169
+ else:
170
+ data, header = decrypt(backup, key)
171
+ workdir.write_private(db_path, data)
172
+ workdir.write_private(run / "schema.sql", sqlite_summary.schema_sql(db_path).encode())
173
+ return describe(db_path, source=backup.name, header=header), run
@@ -0,0 +1,107 @@
1
+ """Turn an iPhone -> Android conversion into a WhatsApp for Android backup.
2
+
3
+ The merged msgstore.db is encrypted the way WhatsApp's end-to-end encrypted
4
+ backup is (crypt15: AES-256-GCM under the 64-digit key, zlib inside), with
5
+ the original backup's header, so WhatsApp sees its own account and version.
6
+ A fresh random IV is drawn for every file: reusing the original's, as
7
+ wa-crypt-tools' own command line does by default, would put two different
8
+ plaintexts under one GCM nonce. The result is decrypted again and compared
9
+ byte for byte before it's handed back.
10
+
11
+ The output is a WhatsApp/ folder (Databases/msgstore.db.crypt15 and the
12
+ converted Media/), laid out as on the phone, ready to copy over.
13
+ """
14
+
15
+ import hashlib
16
+ import json
17
+ import os
18
+ import shutil
19
+ import zlib
20
+ from dataclasses import asdict, dataclass
21
+ from pathlib import Path
22
+
23
+ from wa_crypt_tools.lib.db.db15 import Database15
24
+ from wa_crypt_tools.lib.db.dbfactory import DatabaseFactory
25
+
26
+ from whatferry import android, workdir
27
+
28
+
29
+ class AndroidWriteError(Exception):
30
+ """The backup can't be written; the message says why."""
31
+
32
+
33
+ @dataclass
34
+ class WriteReport:
35
+ folder: str = ""
36
+ backup: str = ""
37
+ backup_bytes: int = 0
38
+ media_files: int = 0
39
+ verified: bool = False
40
+ # False when the same-source guard was skipped on request.
41
+ source_checked: bool = True
42
+
43
+ def as_dict(self) -> dict:
44
+ return asdict(self)
45
+
46
+
47
+ def check_same_source(reference: Path, key, convert_run: Path) -> None:
48
+ """Refuse an Android backup other than the one the conversion merged into."""
49
+ try:
50
+ made_from = json.loads((convert_run / "report.json").read_text())
51
+ except (OSError, ValueError):
52
+ raise AndroidWriteError(f"{convert_run} has no readable conversion report: convert again") from None
53
+ if made_from.get("direction") != "iphone-to-android":
54
+ raise AndroidWriteError(f"{convert_run} is an Android -> iPhone conversion")
55
+ if not made_from.get("source_sha256"):
56
+ raise AndroidWriteError("this conversion doesn't record which Android backup it was made from: convert again")
57
+ plain, _ = android.decrypt(reference, key)
58
+ if hashlib.sha256(plain).hexdigest() != made_from.get("source_sha256"):
59
+ raise AndroidWriteError("this Android backup isn't the one the conversion was made from: check the newest "
60
+ "Android backup again and convert again")
61
+
62
+
63
+ def write_backup(reference: Path, key, convert_run: Path, target: Path | None = None,
64
+ check_source: bool = True) -> tuple[WriteReport, Path]:
65
+ """Encrypt the converted msgstore.db like `reference`, and lay out the WhatsApp/ folder to copy to the phone."""
66
+ merged = convert_run / "files" / "msgstore.db"
67
+ if not merged.is_file():
68
+ raise AndroidWriteError(f"{convert_run} has no converted msgstore.db")
69
+ with reference.open("rb") as f:
70
+ try:
71
+ original = DatabaseFactory.from_file(f)
72
+ except Exception as e: # noqa: BLE001 - the library raises whatever its parser hits
73
+ raise AndroidWriteError(f"{reference.name} is not a WhatsApp backup: {e}") from e
74
+ if not isinstance(original, Database15):
75
+ raise AndroidWriteError("only the end-to-end encrypted backup (msgstore.db.crypt15, with the 64-digit key) "
76
+ "can be written back")
77
+ if check_source: # off only on request
78
+ check_same_source(reference, key, convert_run)
79
+
80
+ run = workdir.new_run("android-backup")
81
+ folder = target or run / "WhatsApp"
82
+ if folder.exists():
83
+ raise AndroidWriteError(f"{folder} already exists")
84
+ (folder / "Databases").mkdir(parents=True, mode=0o700)
85
+ plain = merged.read_bytes()
86
+ encrypted = Database15(key=key).encrypt(key, original.props, zlib.compress(plain, 1)) # fresh IV
87
+ out = folder / "Databases" / "msgstore.db.crypt15"
88
+ workdir.write_private(out, encrypted)
89
+
90
+ readback, _ = android.decrypt(out, key)
91
+ if readback != plain:
92
+ raise AndroidWriteError("the written backup doesn't decrypt to the converted database")
93
+
94
+ media = convert_run / "files" / "Media"
95
+ count = 0
96
+ for path in sorted(p for p in media.rglob("*") if p.is_file()) if media.is_dir() else []:
97
+ dest = folder / "Media" / path.relative_to(media)
98
+ dest.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
99
+ try:
100
+ os.link(path, dest) # no extra space
101
+ except OSError:
102
+ shutil.copy2(path, dest)
103
+ count += 1
104
+ report = WriteReport(folder=str(folder), backup=str(out), backup_bytes=len(encrypted), media_files=count,
105
+ verified=True, source_checked=check_source)
106
+ workdir.write_private(run / "write-report.json", json.dumps(report.as_dict(), indent=2).encode())
107
+ return report, folder