oracles.py (19963B)
1 # This file is part of GNU Taler 2 # (C) 2026 Taler Systems S.A. 3 # 4 # GNU Taler is free software; you can redistribute it and/or modify it under the 5 # terms of the GNU General Public License as published by the Free Software 6 # Foundation; either version 3, or (at your option) any later version. 7 # 8 # GNU Taler is distributed in the hope that it will be useful, but WITHOUT ANY 9 # WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR 10 # A PARTICULAR PURPOSE. See the GNU General Public License for more details. 11 # 12 # You should have received a copy of the GNU General Public License along with 13 # GNU Taler; see the file COPYING. If not, see <http://www.gnu.org/licenses/> 14 """What counts as a failure. 15 16 An ordinary error is not a finding: the wallet is supposed to refuse a stale 17 order or a malformed URI, and say so. A finding is the app breaking its own 18 contract — a crash, an ANR, an error that wallet-core itself calls unexpected 19 or an invariant failure, a transaction that never leaves a pending state, or a 20 database that no longer opens. 21 """ 22 23 from __future__ import annotations 24 25 import hashlib 26 import json 27 import re 28 import time 29 from dataclasses import dataclass, field 30 from pathlib import Path 31 from typing import Iterable, Optional 32 33 from device import PKG, Device, Screen 34 35 # Error codes that mean "this should not have happened" rather than "your 36 # request was bad"; see wallet/src/main/java/net/taler/wallet/backend/ 37 # TalerErrorCode.kt. 38 INTERNAL_CODES = { 39 2, # GENERIC_CLIENT_INTERNAL_ERROR 40 56, # GENERIC_DB_INVARIANT_FAILURE 41 60, # GENERIC_INTERNAL_INVARIANT_FAILURE 42 7001, # WALLET_UNEXPECTED_EXCEPTION 43 7007, # WALLET_CORE_API_OPERATION_UNKNOWN 44 7047, # WALLET_TRANSACTION_PROTOCOL_VIOLATION 45 7048, # WALLET_CORE_API_BAD_REQUEST 46 } 47 48 CRASH_PATTERNS = ( 49 ("crash", re.compile(r"FATAL EXCEPTION")), 50 ("anr", re.compile(r"ANR in ")), 51 ("native-crash", re.compile(r"\*\*\* \*\*\* \*\*\*|signal \d+ \(SIG")), 52 ("core-internal", re.compile(r"(?i)unexpected exception|invariant (failure|violated)" 53 r"|unhandled (promise )?rejection|assertion failed")), 54 ("core-unreachable", re.compile(r"(?i)refusing to run a second wallet-core")), 55 ) 56 57 # The wallet's error bottom sheet always offers this; it is the cheapest marker 58 # that the screen on display is an error screen at all. 59 ERROR_SHEET_MARKER = re.compile(r"(?i)export error diagnostics") 60 # \bbug\b matters: without the word boundaries this matched the "debug" in 61 # the application id of every URI the wallet quoted back in an error message. 62 INTERNAL_TEXT = re.compile( 63 r"(?i)internal error|invariant|unexpected|assertion|\bbug\b" 64 r"|NullPointer|[A-Za-z]+Exception\b" 65 ) 66 67 68 # Kinds that describe the wallet behaving reasonably (refusing bad input, 69 # waiting for a counterparty) rather than a defect. 70 INFORMATIONAL = {"error-screen", "unfinished-transaction", "harness-crash"} 71 72 73 @dataclass(frozen=True) 74 class Finding: 75 kind: str 76 detail: str 77 evidence: str = "" 78 79 @property 80 def fingerprint(self) -> str: 81 """Dedup key: the same bug found twice should collapse to one entry.""" 82 # Strip ids, amounts, timestamps and addresses so that two instances of 83 # the same defect hash alike. 84 norm = re.sub(r"[0-9A-Z]{20,}", "<ID>", self.detail) 85 norm = re.sub(r"\b\d+\b", "#", norm) 86 norm = re.sub(r"0x[0-9a-f]+", "<ADDR>", norm) 87 return hashlib.sha256(f"{self.kind}|{norm}".encode()).hexdigest()[:16] 88 89 def __str__(self) -> str: 90 return f"[{self.kind}] {self.detail}" 91 92 93 def from_logcat(log: str, pkg: str = PKG) -> list[Finding]: 94 """Crashes, ANRs and wallet-core's own internal errors. 95 96 A crash is only the app's when the trace says so: `uiautomator dump` 97 itself dies with "UiAutomationService … already registered!" whenever two 98 dumps overlap, and that is the driver's problem, not the wallet's. 99 """ 100 out: list[Finding] = [] 101 lines = log.splitlines() 102 for kind, pattern in CRASH_PATTERNS: 103 for i, line in enumerate(lines): 104 if not pattern.search(line): 105 continue 106 # A stack trace's first frames identify the defect far better 107 # than the header line does. 108 context = "\n".join(lines[i:i + 12]) 109 if kind in ("crash", "native-crash") and pkg not in context: 110 out.append(Finding("harness-crash", 111 f"not the app: {line.strip()[:200]}", context)) 112 continue 113 out.append(Finding(kind, line.strip()[:400], context)) 114 for m in re.finditer(r'"code"\s*:\s*(\d+)', log): 115 code = int(m.group(1)) 116 if code in INTERNAL_CODES: 117 start = max(0, m.start() - 300) 118 out.append(Finding("internal-error-code", f"wallet-core returned code {code}", 119 log[start:m.end() + 300])) 120 return out 121 122 123 def from_screen(screen: Screen) -> list[Finding]: 124 """Error screens that look like a bug rather than a refusal.""" 125 texts = screen.texts() 126 joined = " | ".join(texts) 127 if not any(ERROR_SHEET_MARKER.search(t) for t in texts): 128 return [] 129 message = next((t for t in texts 130 if not ERROR_SHEET_MARKER.search(t) 131 and t.lower() not in ("error", "copy", "share", "close", 132 "drag handle", "close sheet")), "") 133 if INTERNAL_TEXT.search(joined): 134 return [Finding("internal-error-screen", message[:400] or joined[:400], joined)] 135 # A plain error sheet is recorded, but only as information: whether it is 136 # legitimate depends on what the scenario was trying to do. 137 return [Finding("error-screen", message[:400] or joined[:400], joined)] 138 139 140 # Text that should never reach a user. 141 SANITY_PATTERNS = ( 142 ("placeholder-leak", re.compile(r"%[0-9]+\$[sd]|%s\b|%d\b")), 143 ("null-leak", re.compile(r"(?<![A-Za-z])(null|undefined|NaN|Infinity)(?![A-Za-z])")), 144 ("exception-leak", re.compile(r"java\.lang\.|kotlin\.[A-Za-z]+Exception|" 145 r"[A-Za-z]+Exception:")), 146 # A word stuck to a number, like "UNKNOWN0.00" or "EUR1.00": a currency 147 # symbol that is a word, formatted as if it were a sign. 148 ("glued-currency", re.compile(r"(?:^|[\s:])[A-Z]{3,}\d+[.,]\d\d(?:$|\s)")), 149 ) 150 # Labels that legitimately contain such words: the developer-mode error sheet 151 # and the JSON viewer render raw wallet-core payloads, nulls and all. 152 SANITY_EXEMPT = re.compile( 153 r"(?i)export error diagnostics|show json|internal event log" 154 r'|^\s*[\{\[]|"\s*:' 155 ) 156 157 158 def screen_sanity(screen: Screen) -> list[Finding]: 159 """Rendering that is obviously wrong, whatever the screen is for. 160 161 An unsubstituted format string, a stray "null", a stack-trace class name or 162 a currency word glued to a number are all defects no matter which flow 163 produced them, and they are cheap to notice on every dump. 164 """ 165 out: list[Finding] = [] 166 for text in screen.texts(): 167 label = text.strip() 168 if not label or SANITY_EXEMPT.search(label): 169 continue 170 for kind, pattern in SANITY_PATTERNS: 171 if pattern.search(label): 172 out.append(Finding(kind, f"{label[:160]!r} on {screen.activity}", 173 " | ".join(screen.texts())[:800])) 174 break 175 return out 176 177 178 # A transaction that never happened cannot have cost a fee. The fee row on 179 # every credit screen is the difference between the raw and the effective 180 # amount, and an aborted or failed transaction has an effective amount of 181 # zero, so the difference becomes the whole amount. 182 DEAD_STATE = re.compile(r"(?i)was aborted|has failed|has expired|been abandoned") 183 184 185 def fee_on_a_dead_transaction(screen: Screen) -> list[Finding]: 186 """A fee shown on a transaction that did not happen.""" 187 texts = screen.texts() 188 if not any(DEAD_STATE.search(t) for t in texts): 189 return [] 190 if not any(t.strip().lower() == "fee" for t in texts): 191 return [] 192 return [Finding( 193 "fee-on-dead-transaction", 194 f"a fee is shown on a transaction that did not happen, on {screen.activity}", 195 " | ".join(texts)[:800], 196 )] 197 198 199 # A screen that states an absence -- no accounts, no contacts, nothing to send 200 # -- while the log says the query behind it failed. Found by hand first (see 201 # findings/a-failed-query-is-shown-as-an-empty-wallet.md); this is the general 202 # shape of it. 203 ABSENCE_CLAIM = re.compile( 204 r"(?i)^No [a-z ]*(accounts|contacts|transactions|payment services|" 205 r"methods|statements)|^No [a-z ]+ (yet|saved)[.!]?$" 206 ) 207 FAILED_QUERY = re.compile( 208 r'Error (?:retrieving )?(get|list)[A-Za-z]+' 209 r'|"operation"\s*:\s*"(get|list)[A-Za-z]+"' 210 ) 211 212 213 def absence_after_error(screen: Screen, log: Optional[str]) -> list[Finding]: 214 """An empty state shown while the query behind it was failing.""" 215 if not log: 216 return [] 217 claims = [t for t in screen.texts() if ABSENCE_CLAIM.search(t.strip())] 218 if not claims: 219 return [] 220 failures = [l for l in log.splitlines() 221 if FAILED_QUERY.search(l) and ('"error"' in l or "Error " in l)] 222 if not failures: 223 return [] 224 return [Finding( 225 "absence-after-error", 226 f"{claims[0][:80]!r} while a query was failing, on {screen.activity}", 227 "\n".join(failures[-3:])[:600] + "\n--\n" + " | ".join(screen.texts())[:400], 228 )] 229 230 231 # Amounts rendered both with and without their currency specification on the 232 # same screen: "5.00 EUR" beside "€4.88" reads like two currencies. 233 AMOUNT_UNSPECCED = re.compile(r"(?:^|\s)\d+[.,]\d\d\s+[A-Z]{3,}(?:$|\s)") 234 AMOUNT_SPECCED = re.compile(r"[€$£¥₹]\s?\d+(?:[.,]\d+)?") 235 236 237 def mixed_amount_notation(screen: Screen) -> list[Finding]: 238 """Two notations for money on one screen.""" 239 texts = screen.texts() 240 plain = [m.group(0).strip() for t in texts 241 for m in [AMOUNT_UNSPECCED.search(t)] if m] 242 symbol = [m.group(0).strip() for t in texts 243 for m in [AMOUNT_SPECCED.search(t)] if m] 244 if not (plain and symbol): 245 return [] 246 # The two notations are often in the *same* sentence ("transfer 5.00 EUR 247 # ... to receive EUR4.88"), so name the amounts rather than their nodes: 248 # quoting whole nodes made the finding read as the same text twice. 249 return [Finding( 250 "mixed-amount-notation", 251 f"{plain[0]!r} beside {symbol[0]!r} on {screen.activity}", 252 " | ".join(texts)[:700], 253 )] 254 255 256 def blank_screen(screen: Screen) -> list[Finding]: 257 """A screen with nothing to read and nothing to tap is a dead end.""" 258 if not screen.nodes: 259 return [Finding("empty-hierarchy", "no view hierarchy returned")] 260 if not screen.labelled() and not screen.tappable(): 261 return [Finding("blank-screen", f"{len(screen.nodes)} nodes, none labelled or tappable")] 262 return [] 263 264 265 # Retry counters above this mean wallet-core has given up repeatedly on the 266 # same operation. 267 STUCK_RETRIES = 4 268 269 270 def background_failures(dev: Device, keep_db_at: Optional[str] = None) -> list[Finding]: 271 """Operations failing where the UI never looks. 272 273 wallet-core keeps one `operation_retries` row per retried operation, with 274 the last error and a retry counter. A row with an error is a failure the 275 user may never be shown; an error with an internal code is a defect, and a 276 high retry counter is an operation that is not getting anywhere. 277 """ 278 import dbprobe 279 280 out: list[Finding] = [] 281 try: 282 db = dbprobe.pull(dev, Path(keep_db_at) if keep_db_at else None) 283 if not dbprobe.has_native_schema(db): 284 # A wallet on the legacy IndexedDB-emulation backend keeps its 285 # records in object_data, not in tables this oracle can read. 286 # That is a state the wallet can legitimately be in -- see 287 # db_migration_prompt -- so there is nothing to report rather than 288 # an oracle failure. 289 return [] 290 rows = dbprobe.rows(db, "select id, last_error, retry_info from operation_retries") 291 except Exception as e: 292 return [Finding("oracle-error", f"could not read the wallet database: {e}")] 293 for row in rows: 294 op = row["id"] 295 error = row["last_error"] 296 if error: 297 try: 298 info = json.loads(error) 299 except (json.JSONDecodeError, TypeError): 300 info = {} 301 code = info.get("code") 302 hint = str(info.get("hint") or info.get("message") or error)[:300] 303 kind = ("background-internal-error" if code in INTERNAL_CODES 304 else "background-error") 305 out.append(Finding(kind, f"{op}: code {code}: {hint}", error[:2000])) 306 try: 307 retries = json.loads(row["retry_info"] or "{}").get("retryCounter", 0) 308 except (json.JSONDecodeError, TypeError): 309 retries = 0 310 if retries >= STUCK_RETRIES: 311 out.append(Finding("stuck-operation", 312 f"{op}: retried {retries} times", str(dict(row))[:1000])) 313 return out 314 315 316 # Tables that record one long-running operation each, with the column that 317 # says when it finished. 318 OPERATION_TABLES = { 319 "withdrawal_groups": ("withdrawal_group_id", "timestamp_start", "timestamp_finish"), 320 "refresh_groups": ("refresh_group_id", "timestamp_created", "timestamp_finished"), 321 "deposit_groups": ("deposit_group_id", "timestamp_created", "timestamp_finished"), 322 } 323 324 325 def unfinished_transactions(dev: Device, older_than: int = 240) -> list[Finding]: 326 """Operations that started a while ago and never finished. 327 328 Advisory rather than damning: a suspended or aborted transaction is 329 legitimately unfinished, and so is one waiting for the bank. What makes it 330 worth printing is the pattern — the same operation unfinished across runs 331 that should have completed it. 332 """ 333 import dbprobe 334 335 out: list[Finding] = [] 336 try: 337 db = dbprobe.pull(dev) 338 except Exception as e: 339 return [Finding("oracle-error", f"could not read the wallet database: {e}")] 340 if not dbprobe.has_native_schema(db): 341 return [] 342 now_us = time.time() * 1_000_000 343 for table, (key, started, finished) in OPERATION_TABLES.items(): 344 try: 345 rows = dbprobe.rows( 346 db, f"select {key} as id, {started} as started, {finished} as finished, " 347 f"status from {table}") 348 except Exception: 349 continue 350 for row in rows: 351 if row["finished"]: 352 continue 353 start = row["started"] 354 if not isinstance(start, (int, float)): 355 continue 356 age = (now_us - float(start)) / 1_000_000 357 if age > older_than: 358 out.append(Finding( 359 "unfinished-transaction", 360 f"{table} {str(row['id'])[:24]} unfinished after {age:.0f}s " 361 f"(status {row['status']})", 362 str(dict(row))[:500], 363 )) 364 return out 365 366 367 # Lines that mean wallet-core refused or failed an operation the UI asked for. 368 # Deliberately narrow: any "E taler-wallet" line also matches background 369 # chatter that has nothing to do with the tap being judged. 370 TAIL_ERROR = re.compile( 371 r'"type"\s*:\s*"error"\s*,\s*"operation"' 372 r"|got \w+ error" 373 r"|FATAL EXCEPTION" 374 ) 375 376 377 LOGCAT_STAMP = re.compile(r"^(\d\d)-(\d\d) (\d\d):(\d\d):(\d\d)\.(\d+)") 378 379 380 def recent_lines(log: str, seconds: float = 6.0) -> list[str]: 381 """Log lines written within the last few seconds. 382 383 logcat has no "since my last read" option, so the timestamps are compared 384 against the wall clock. The device and the host share it closely enough 385 for a window this wide. 386 """ 387 now = time.localtime() 388 cutoff = time.time() - seconds 389 out = [] 390 for line in log.splitlines(): 391 m = LOGCAT_STAMP.match(line) 392 if not m: 393 continue 394 month, day, hour, minute, second = (int(m.group(i)) for i in range(1, 6)) 395 stamp = time.mktime((now.tm_year, month, day, hour, minute, second, 396 0, 0, now.tm_isdst)) 397 if stamp >= cutoff: 398 out.append(line) 399 return out 400 401 402 def silent_failure(dev: Device, label: str, before: str, after: str, 403 lines: int = 200) -> list[Finding]: 404 """A primary action that did nothing, while the log says it failed. 405 406 This is the shape of the first defect the simulator found: tapping "Treat 407 as global" sent a malformed request, wallet-core rejected it, and the user 408 saw nothing at all. Comparing the screen before and after a tap catches 409 the whole class. 410 """ 411 if before != after: 412 return [] 413 # Only the app's own screens: a random walk taps around in Chrome too, and 414 # "tapping 'Sign in' changed nothing" is not a finding about the wallet. 415 activity = dev.dump().activity 416 if activity and not activity.startswith(PKG): 417 return [] 418 tail = dev.adb("logcat", "-d", "-t", str(lines), check=False) 419 fresh = "\n".join(recent_lines(tail)) 420 errors = [ln for ln in fresh.splitlines() if TAIL_ERROR.search(ln)] 421 if not errors: 422 return [] 423 codes = sorted({int(m.group(1)) for m in re.finditer(r'"code"\s*:\s*(\d+)', fresh)}) 424 internal = [c for c in codes if c in INTERNAL_CODES] 425 kind = "silent-internal-failure" if internal else "silent-failure" 426 return [Finding( 427 kind, 428 f"tapping {label!r} changed nothing on screen while the log reported " 429 f"an error (codes {codes or 'none'})", 430 "\n".join(errors[-8:])[:2000], 431 )] 432 433 434 def db_intact(dev: Device, pkg: Optional[str] = None) -> list[Finding]: 435 """Ask sqlite whether the wallet database still checks out.""" 436 from device import PKG 437 pkg = pkg or PKG 438 out = dev.shell( 439 f"run-as {pkg} sqlite3 files/talerwalletdb.sqlite3 'PRAGMA integrity_check;'", 440 check=False, 441 ).strip() 442 if not out: 443 # No sqlite3 on the image, or no database yet: not a finding. 444 return [] 445 if out.splitlines()[-1].strip() != "ok": 446 return [Finding("db-corrupt", out[:400])] 447 return [] 448 449 450 @dataclass 451 class Session: 452 """Collects findings over an episode, deduplicated.""" 453 454 findings: dict[str, Finding] = field(default_factory=dict) 455 456 def add(self, found: Iterable[Finding]) -> list[Finding]: 457 fresh = [] 458 for f in found: 459 if f.fingerprint not in self.findings: 460 self.findings[f.fingerprint] = f 461 fresh.append(f) 462 return fresh 463 464 def check(self, dev: Device, screen: Optional[Screen] = None, 465 log: Optional[str] = None) -> list[Finding]: 466 found: list[Finding] = [] 467 # Screen oracles only apply to the app's own screens. A random walk 468 # leaves the wallet now and then -- a KYC link opens Chrome -- and 469 # Chrome's search suggestions are full of the words these oracles look 470 # for ("undefined behavior", "null"), which is 16 findings of pure 471 # noise in a 120-step walk. 472 if screen is not None and screen.activity and not screen.activity.startswith(PKG): 473 screen = None 474 if screen is not None: 475 found += from_screen(screen) 476 found += blank_screen(screen) 477 found += screen_sanity(screen) 478 found += fee_on_a_dead_transaction(screen) 479 found += mixed_amount_notation(screen) 480 if log is not None: 481 found += absence_after_error(screen, log) 482 if log is not None: 483 found += from_logcat(log) 484 return self.add(found) 485 486 def serious(self) -> list[Finding]: 487 """Everything except what only describes the wallet refusing or waiting.""" 488 return [f for f in self.findings.values() if f.kind not in INFORMATIONAL]