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.
- whatferry/__init__.py +7 -0
- whatferry/adb.py +336 -0
- whatferry/android.py +173 -0
- whatferry/android_writer.py +107 -0
- whatferry/backup_writer.py +426 -0
- whatferry/cli.py +586 -0
- whatferry/compat.py +172 -0
- whatferry/convert.py +489 -0
- whatferry/ios.py +302 -0
- whatferry/ios_backup.py +251 -0
- whatferry/iphone.py +313 -0
- whatferry/preview.py +239 -0
- whatferry/restore.py +75 -0
- whatferry/schema.py +249 -0
- whatferry/schemas/CHANGES.md +54 -0
- whatferry/schemas/android/778707c93e75c22c.json +13142 -0
- whatferry/schemas/ios/3ca296bd35e652d3.json +1627 -0
- whatferry/sqlite_summary.py +90 -0
- whatferry/to_android.py +457 -0
- whatferry/ui/__init__.py +1 -0
- whatferry/ui/server.py +352 -0
- whatferry/ui/static/ar-PdUTw834.js +1 -0
- whatferry/ui/static/bn-B2AYIo7N.js +1 -0
- whatferry/ui/static/de-C3RQ3ckb.js +1 -0
- whatferry/ui/static/es-DqKB4dTx.js +1 -0
- whatferry/ui/static/fa-Djdjr8u_.js +1 -0
- whatferry/ui/static/fr-oAun1kF3.js +1 -0
- whatferry/ui/static/geist-cyrillic-ext-wght-normal-DjL33-gN.woff2 +0 -0
- whatferry/ui/static/geist-cyrillic-wght-normal-BEAKL7Jp.woff2 +0 -0
- whatferry/ui/static/geist-latin-ext-wght-normal-DC-KSUi6.woff2 +0 -0
- whatferry/ui/static/geist-latin-wght-normal-BgDaEnEv.woff2 +0 -0
- whatferry/ui/static/geist-vietnamese-wght-normal-6IgcOCM7.woff2 +0 -0
- whatferry/ui/static/he-Cwsem8NY.js +1 -0
- whatferry/ui/static/hi-DuwkLPZ2.js +1 -0
- whatferry/ui/static/icon.svg +6 -0
- whatferry/ui/static/id-rkeenv-I.js +1 -0
- whatferry/ui/static/index-BAKNHQPa.css +2 -0
- whatferry/ui/static/index-Dmv0Fr7V.js +50 -0
- whatferry/ui/static/index.html +16 -0
- whatferry/ui/static/it-DjkMV3-3.js +1 -0
- whatferry/ui/static/ms-XjB2Ih3s.js +1 -0
- whatferry/ui/static/nl-siipj1n_.js +1 -0
- whatferry/ui/static/pl-D2cnciFi.js +1 -0
- whatferry/ui/static/pt-CZE-dXu0.js +1 -0
- whatferry/ui/static/ro-DEUvUIDB.js +1 -0
- whatferry/ui/static/tr-DzamloQB.js +1 -0
- whatferry/ui/static/uk-BftZvIO3.js +1 -0
- whatferry/ui/static/ur-D4eBHhUR.js +1 -0
- whatferry/ui/static/zh-Hant-DTYHSMpc.js +1 -0
- whatferry/ui/static/zh-s_mV-S3N.js +1 -0
- whatferry/ui/wizard.py +805 -0
- whatferry/workdir.py +170 -0
- whatferry-1.0.0.dist-info/METADATA +449 -0
- whatferry-1.0.0.dist-info/RECORD +57 -0
- whatferry-1.0.0.dist-info/WHEEL +4 -0
- whatferry-1.0.0.dist-info/entry_points.txt +3 -0
- whatferry-1.0.0.dist-info/licenses/LICENSE +674 -0
whatferry/__init__.py
ADDED
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
|