taler-android

Android apps for GNU Taler (wallet, PoS, cashier)
Log | Files | Refs | README | LICENSE

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]