mobster-cli 0.4.3__py3-none-any.whl

mobile_agent/verify/wire.py

@@ -0,0 +1,392 @@
+"""Wire assertions in ``expect:``: what the app sent over the network and what it stored on disk.
+
+``request`` and ``no_request`` are judged on the requests the run's proxy saw (netproxy.py); ``storage`` on the app's
+container after the steps (wirestore.py). They run on a simulator, dark behind MOBSTER_EXPERIMENTAL_NETWORK=1. The
+evidence in a result is the matched request line or the storage diff, with secrets masked and bodies cut short."""
+
+import fnmatch
+import gzip
+import json
+import os
+import re
+import zlib
+from dataclasses import dataclass
+from typing import Any, Optional
+
+from .. import secret_filter
+from . import netstubs, wirestore
+from .assertions import AssertionResult, CheckError, Matcher, parse_matcher
+
+FLAG = "MOBSTER_EXPERIMENTAL_NETWORK"
+KINDS = ("request", "no_request", "storage")
+REQUEST_KEYS = ("method", "host", "path", "status", "body", "response")
+STORAGE_KEYS = ("file", "sqlite", "query", "changed", "contains", "equals", "at_least", "at_most")
+STATUS = re.compile(r"[1-5]xx")
+SHORTHAND = re.compile(r"(?:(?P<method>[A-Za-z]+)\s+)?(?P<host>[^/\s]+)?(?P<path>/\S*)?$")
+SECRET_HEADERS = re.compile(r"authorization|cookie|token|secret|api[-_]?key|session|password|signature", re.I)
+SHOWN_BODY = 200
+SHOWN_SEEN = 4
+OFF = (f"expect: request, no_request and storage are experimental. Set {FLAG}=1 to use them, or remove them from "
+       "the check.")
+
+
+def enabled(environ=None):
+    return (os.environ if environ is None else environ).get(FLAG) == "1"
+
+
+def is_wire(item):
+    return isinstance(item, dict) and any(kind in item for kind in KINDS)
+
+
+@dataclass(frozen=True)
+class WireAssertion:
+    kind: str
+    method: Optional[str] = None
+    host: Optional[str] = None
+    path: Optional[Matcher] = None
+    status: Any = None                  # a number, or "2xx"
+    body: Optional[Matcher] = None      # of the request's body
+    response: Optional[Matcher] = None  # of the response's body
+    file: Optional[str] = None
+    sqlite: Optional[str] = None
+    query: Optional[str] = None
+    changed: bool = True
+    contains: Optional[Matcher] = None
+    equals: Optional[int] = None
+    at_least: Optional[int] = None
+    at_most: Optional[int] = None
+    name: Optional[str] = None
+
+    def needs_open(self):
+        """Whether the proxy must open the host's https to judge this: a path, status or body is inside it."""
+        return bool(self.host) and self.kind != "storage" and bool(self.path or self.status or self.body
+                                                                    or self.response)
+
+    def render(self):
+        if self.kind == "storage":
+            target = f"file {self.file}" if self.file else f"sqlite {self.sqlite}"
+            if self.file:
+                said = "changed" if self.changed else "unchanged"
+                return f"storage {target} {said}" + (f' containing "{self.contains.render()}"' if self.contains else "")
+            bound = (f"== {self.equals}" if self.equals is not None else
+                     f">= {self.at_least}" if self.at_least is not None else f"<= {self.at_most}")
+            return f"storage {target} rows {bound}"
+        line = " ".join(part for part in (self.method, (self.host or "") + (self.path.render() if self.path else ""))
+                        if part) or "any request"
+        extra = "".join((f" -> {self.status}" if self.status else "",
+                         f" body {self.body.render()}" if self.body else "",
+                         f" response {self.response.render()}" if self.response else ""))
+        return f"{self.kind} {line}{extra}"
+
+    def to_dict(self):
+        out = {}
+        if self.kind == "storage":
+            for key in STORAGE_KEYS:
+                value = getattr(self, key)
+                if key == "changed":
+                    if self.file and not value:
+                        out[key] = False
+                elif value is not None:
+                    out[key] = value.raw if isinstance(value, Matcher) else value
+        else:
+            for key in REQUEST_KEYS:
+                value = getattr(self, key)
+                if value is not None:
+                    out[key] = value.raw if isinstance(value, Matcher) else value
+        result = {self.kind: out}
+        if self.name:
+            result["name"] = self.name
+        return result
+
+
+def _check_keys(body, allowed, where):
+    for key in body:
+        if key not in allowed:
+            raise CheckError(f"{where}.{key} isn't a setting. Use {', '.join(allowed)}.")
+
+
+def _shorthand(text, where):
+    found = SHORTHAND.match(text.strip())
+    if not text.strip() or found is None or not (found["host"] or found["path"]):
+        raise CheckError(f"{where} needs a method, host and path such as POST api.example.com/v1/cart, or a "
+                         "mapping.")
+    out = {}
+    method, host = found["method"], found["host"]
+    if method:
+        out["method"] = method
+    if host:
+        out["host"] = host
+    if found["path"]:
+        out["path"] = found["path"]
+    return out
+
+
+def _parse_one(obj, where):
+    kinds = [kind for kind in KINDS if kind in obj]
+    if len(kinds) != 1:
+        raise CheckError(f"{where} needs exactly one of {', '.join(KINDS)}; it has {', '.join(kinds)}")
+    kind = kinds[0]
+    _check_keys(obj, KINDS + ("name",), where)
+    body = obj[kind]
+    if isinstance(body, str) and kind != "storage":
+        body = _shorthand(body, f"{where}.{kind}")
+    if not isinstance(body, dict):
+        raise CheckError(f"{where}.{kind} must be a mapping such as "
+                         + ("{file: Library/Preferences/app.plist}." if kind == "storage"
+                            else "{method: POST, host: api.example.com, path: /v1/cart}."))
+    name = obj.get("name")
+    if name is not None and (not isinstance(name, str) or not name.strip() or len(name) > 120):
+        raise CheckError(f"{where}.name must be text of 1 to 120 characters")
+    fields = {"kind": kind, "name": name.strip() if name else None}
+    here = f"{where}.{kind}"
+    if kind == "storage":
+        fields.update(_parse_storage(body, here))
+    else:
+        fields.update(_parse_request(body, here))
+        if kind == "no_request" and (fields.get("status") or fields.get("response")):
+            raise CheckError(f"{here} takes no status or response: a request that never left has none.")
+    return WireAssertion(**fields)
+
+
+def _parse_request(body, where):
+    _check_keys(body, REQUEST_KEYS, where)
+    out = {}
+    if "method" in body:
+        method = body["method"]
+        if not isinstance(method, str) or method.upper() not in netstubs.METHODS:
+            raise CheckError(f"{where}.method must be one of {', '.join(netstubs.METHODS)}.")
+        out["method"] = method.upper()
+    if "host" in body:
+        out["host"] = netstubs._host(body["host"], f"{where}.host")
+    if "path" in body:
+        path = body["path"]
+        if isinstance(path, str) and not path.startswith(("/", "*")):
+            raise CheckError(f"{where}.path must start with /, such as /v1/cart or /v1/*, or be a /regex/.")
+        out["path"] = parse_matcher(path, f"{where}.path")
+    if "status" in body:
+        status = body["status"]
+        if isinstance(status, str) and STATUS.fullmatch(status):
+            out["status"] = status
+        elif isinstance(status, int) and not isinstance(status, bool) and 100 <= status <= 599:
+            out["status"] = status
+        else:
+            raise CheckError(f"{where}.status must be a number from 100 to 599 or a class such as 2xx.")
+    for key in ("body", "response"):
+        if key in body:
+            out[key] = parse_matcher(body[key], f"{where}.{key}")
+    if not out:
+        raise CheckError(f"{where} needs at least a method, host or path.")
+    return out
+
+
+def _parse_storage(body, where):
+    _check_keys(body, STORAGE_KEYS, where)
+    if ("file" in body) == ("sqlite" in body):
+        raise CheckError(f"{where} needs one of file (a path or glob under the app's container) or sqlite.")
+    out = {}
+    for key in ("file", "sqlite"):
+        if key in body:
+            value = body[key]
+            if not isinstance(value, str) or not value.strip() or value.startswith("/") or ".." in value.split("/"):
+                raise CheckError(f"{where}.{key} must be a path inside the app's container, such as "
+                                 "Library/Preferences/app.plist, without a leading / or ..")
+            out[key] = value.strip()
+    if "file" in body:
+        if set(body) - {"file", "changed", "contains"}:
+            raise CheckError(f"{where}: a file takes changed and contains only.")
+        if not isinstance(body.get("changed", True), bool):
+            raise CheckError(f"{where}.changed must be true or false.")
+        out["changed"] = body.get("changed", True)
+        if "contains" in body:
+            out["contains"] = parse_matcher(body["contains"], f"{where}.contains")
+    else:
+        query = body.get("query")
+        if not isinstance(query, str) or not wirestore.read_only_query(query):
+            raise CheckError(f"{where}.query must be one SELECT or WITH statement, such as "
+                             "SELECT 1 FROM cart WHERE sku = 'a1'.")
+        bounds = {key: body[key] for key in ("equals", "at_least", "at_most") if key in body}
+        if set(body) - {"sqlite", "query", *bounds} or len(bounds) != 1:
+            raise CheckError(f"{where}: a sqlite query needs exactly one of equals, at_least and at_most (rows).")
+        (key, number), = bounds.items()
+        if isinstance(number, bool) or not isinstance(number, int) or number < 0:
+            raise CheckError(f"{where}.{key} must be a whole number of at least 0.")
+        out.update(query=query.strip(), **{key: number})
+    return out
+
+
+def parse(expect):
+    """The wire assertions of a check file's ``expect`` list: () when it has none. Raises CheckError."""
+    found = [(index, item) for index, item in enumerate(expect or ()) if is_wire(item)]
+    if found and not enabled():
+        raise CheckError(OFF)
+    return tuple(_parse_one(item, f"expect[{index}]") for index, item in found)
+
+
+def watch_hosts(assertions):
+    """The hosts whose https the proxy must open, or None when no assertion reads the proxy."""
+    wire = [item for item in assertions if item.kind != "storage"]
+    return tuple(dict.fromkeys(item.host for item in wire if item.needs_open())) if wire else None
+
+
+# evidence
+
+def _mask_header(name, value):
+    return "••••••" if SECRET_HEADERS.search(name) else secret_filter.redact(value)
+
+
+def _text(raw, limit=SHOWN_BODY):
+    text = secret_filter.redact(raw.decode("utf-8", "replace").strip())
+    return text if len(text) <= limit else text[:limit] + f"… ({len(raw)} bytes)"
+
+
+def _response_body(raw):
+    """A captured response's body as bytes: de-chunked and inflated where it says so, else what was kept."""
+    head, _, body = raw.partition(b"\r\n\r\n")
+    lowered = head.lower()
+    if b"transfer-encoding: chunked" in lowered:
+        out, rest = b"", body
+        while rest:
+            size_line, _, rest = rest.partition(b"\r\n")
+            try:
+                size = int(size_line.split(b";")[0].strip() or b"0", 16)
+            except ValueError:
+                break
+            if not size:
+                break
+            out, rest = out + rest[:size], rest[size + 2:]
+        body = out
+    try:
+        if b"content-encoding: gzip" in lowered:
+            body = gzip.decompress(body)
+        elif b"content-encoding: deflate" in lowered:
+            body = zlib.decompress(body)
+    except (OSError, EOFError, zlib.error):
+        pass
+    return body
+
+
+def request_line(item):
+    """``POST api.example.com/v1/cart -> 200 at 4.2 s``: one request, safe to show."""
+    where = secret_filter.redact(f"{item['host']}{item.get('path', '')}")
+    status = f" -> {item['status']}" if item.get("status") else ""
+    return f"{item['method']} {where}{status} at {item['atMs'] / 1000:.1f} s"
+
+
+def evidence(item):
+    """The matched request for wire.json: its line, headers with secrets masked, and bodies cut short."""
+    return {"line": request_line(item),
+            "headers": [[name, _mask_header(name, value)] for name, value in item.get("headers", [])],
+            "body": _text(item["body"]) if item.get("body") else "",
+            "response": _text(_response_body(item["response"])) if item.get("response") else ""}
+
+
+# judging
+
+def _path_matches(matcher, path):
+    if matcher.is_regex:
+        return bool(matcher.pattern.search(path))
+    return fnmatch.fnmatchcase(path.split("?")[0], matcher.text) or fnmatch.fnmatchcase(path, matcher.text)
+
+
+def _status_matches(want, got):
+    if got is None:
+        return False
+    return got // 100 == int(want[0]) if isinstance(want, str) else got == want
+
+
+def request_matches(assertion, item):
+    if assertion.method and item["method"] != assertion.method:
+        return False
+    if assertion.host and not netstubs.host_matches(assertion.host, item["host"]):
+        return False
+    if assertion.path and not _path_matches(assertion.path, item.get("path", "")):
+        return False
+    if assertion.status and not _status_matches(assertion.status, item.get("status")):
+        return False
+    if assertion.body and not assertion.body.contains(item["body"].decode("utf-8", "replace")):
+        return False
+    return not assertion.response or assertion.response.contains(
+        _response_body(item["response"]).decode("utf-8", "replace"))
+
+
+def _opaque(rows):
+    """Connections the proxy relayed or refused without opening: they name a host and nothing more."""
+    return [{"method": row["method"], "host": row["host"], "path": "", "atMs": row["atMs"], "headers": [],
+             "body": b"", "status": None, "response": b"", "opaque": True}
+            for row in rows if row.get("via") in ("tunnel", "refused")]
+
+
+def _judge_request(assertion, captures, rows):
+    text = assertion.render()
+    hidden = _opaque(rows)
+    if assertion.kind == "request":
+        hits = [item for item in captures if request_matches(assertion, item)]
+        if hits:
+            first = hits[0]
+            return AssertionResult(True, text, request_line(first) + (f" and {len(hits) - 1} more"
+                                                                      if len(hits) > 1 else ""), (evidence(first),))
+        seen = ", ".join(request_line(item) for item in captures[:SHOWN_SEEN])
+        tunnels = sorted({item["host"] for item in hidden})
+        more = (f"; https to {', '.join(tunnels[:SHOWN_SEEN])} wasn't opened, so name the host to see its paths"
+                if tunnels and not assertion.host else "")
+        if not captures and not hidden:
+            return AssertionResult(False, text, "no request from the app reached the proxy" + more)
+        return AssertionResult(False, text, f"no request matched; saw {seen or 'none opened'}{more}")
+    hits = [item for item in (*captures, *hidden) if request_matches(assertion, item)]
+    if hits:
+        return AssertionResult(False, text, "left the app: " + request_line(hits[0]), (evidence(hits[0]),))
+    if not captures and not hidden:
+        return AssertionResult(False, text, "no request from the app reached the proxy, so Mobster can't tell "
+                                            "whether this one left")
+    undecided = [item for item in hidden if assertion.path or assertion.body]
+    if undecided:
+        hosts = ", ".join(sorted({item["host"] for item in undecided})[:SHOWN_SEEN])
+        return AssertionResult(False, text, f"https to {hosts} wasn't opened, so its paths are unknown; name the "
+                                            "host in this assertion")
+    return AssertionResult(True, text, f"none of {len(captures) + len(hidden)} requests matched")
+
+
+class Judge:
+    """One run's wire assertions: ``baseline`` before the flow, ``judge`` after it. Never raises."""
+
+    def __init__(self, assertions, *, run, udid, bundle, container=wirestore.container):
+        self.assertions = tuple(assertions)
+        self._find = lambda: container(run, udid, bundle)
+        self._before = {}
+        self.evidence = []
+
+    def baseline(self):
+        try:
+            root = self._find()
+        except wirestore.StoreError:
+            return
+        for index, item in enumerate(self.assertions):
+            if item.kind == "storage":
+                self._before[index] = wirestore.take(root, item)
+
+    def judge(self, net):
+        captures, rows = net.seen() if net is not None else ([], [])
+        out = []
+        root, problem = None, None
+        if any(item.kind == "storage" for item in self.assertions):
+            try:
+                root = self._find()
+            except wirestore.StoreError as error:
+                problem = str(error)
+        for index, item in enumerate(self.assertions):
+            if item.kind != "storage":
+                out.append(_judge_request(item, captures, rows) if net is not None else AssertionResult(
+                    False, item.render(), "the run had no proxy, so no request was seen"))
+            elif root is None:
+                out.append(AssertionResult(False, item.render(), problem))
+            else:
+                out.append(wirestore.judge(item, root, self._before.get(index)))
+        self.evidence = [{"assertion": item.render(), "ok": result.ok, "observed": result.observed,
+                          "matches": [dict(m) for m in result.matches]}
+                         for item, result in zip(self.assertions, out)]
+        return out
+
+    def write(self, directory):
+        if self.evidence:
+            with open(os.path.join(directory, "wire.json"), "w", encoding="utf-8") as handle:
+                json.dump(self.evidence, handle, indent=1, default=str)

mobile_agent/verify/wirestore.py

@@ -0,0 +1,176 @@
+"""``expect: storage``: what the app wrote under its own container, read on the Mac after the steps.
+
+A simulator's app container is a folder on this Mac, so nothing is pulled over a wire: ``take`` hashes the files an
+assertion names before the flow, ``judge`` compares them after, and a sqlite query runs on a copy so the app's
+database is never opened for writing. Evidence is a short diff or the first rows, with secrets masked."""
+
+import difflib
+import hashlib
+import json
+import plistlib
+import re
+import shutil
+import sqlite3
+import tempfile
+import time
+from pathlib import Path
+
+from .. import secret_filter
+from .assertions import AssertionResult
+
+FILES_LIMIT = 2000
+HASH_LIMIT = 16 << 20
+TEXT_LIMIT = 64 << 10
+DIFF_LINES = 8
+ROWS_SHOWN = 3
+QUERY_SECONDS = 5
+READ_ONLY = re.compile(r"\s*(select|with)\b", re.I)
+
+
+class StoreError(Exception):
+    pass
+
+
+def read_only_query(sql):
+    """One SELECT or WITH statement (the authorizer in ``rows`` refuses writes whatever this accepts)."""
+    body = sql.strip().rstrip(";").strip()
+    return bool(READ_ONLY.match(body)) and ";" not in body and len(body) <= 2000
+
+
+def container(run, udid, bundle):
+    """The app's data container on this Mac, from ``simctl get_app_container <udid> <bundle> data``."""
+    code, output = run(["get_app_container", udid, bundle, "data"])
+    path = Path(output.splitlines()[-1].strip()) if output.strip() else None
+    if code != 0 or path is None or not path.is_dir():
+        raise StoreError("Mobster couldn't find the app's container on the simulator"
+                         + (f" ({output.splitlines()[-1][:120]})" if output.strip() else "") + ".")
+    return path
+
+
+def _files(root, pattern):
+    """Files under ``root`` matching a glob, as {relative path: (size, sha256, text or None)}."""
+    found = {}
+    for path in sorted(root.glob(pattern)):
+        if len(found) >= FILES_LIMIT:
+            break
+        if not path.is_file() or path.is_symlink():
+            continue
+        size = path.stat().st_size
+        digest = hashlib.sha256()
+        with path.open("rb") as handle:
+            kept = handle.read(HASH_LIMIT)
+            digest.update(kept)
+        found[path.relative_to(root).as_posix()] = (size, digest.hexdigest(),
+                                                    _readable(path, kept) if size <= TEXT_LIMIT else None)
+    return found
+
+
+def _readable(path, raw):
+    """A file's content as text for a diff: a plist as JSON-like lines, text as is, anything else None."""
+    if raw[:6] == b"bplist" or raw[:5] == b"<?xml":
+        try:
+            return json.dumps(plistlib.loads(raw), indent=1, sort_keys=True, default=str)
+        except (plistlib.InvalidFileException, ValueError, OverflowError):
+            return None
+    try:
+        return raw.decode("utf-8")
+    except UnicodeDecodeError:
+        return None
+
+
+def take(root, assertion):
+    """What the assertion looks at before the flow: its files, or its query's row count."""
+    if assertion.file:
+        return {"files": _files(root, assertion.file)}
+    try:
+        return {"rows": len(rows(root, assertion))}
+    except StoreError:
+        return {"rows": None}
+
+
+def rows(root, assertion):
+    """The query's rows from a copy of the database (and its -wal and -shm), never the file itself."""
+    source = root / assertion.sqlite
+    if not source.is_file():
+        raise StoreError(f"{assertion.sqlite} isn't in the app's container.")
+    with tempfile.TemporaryDirectory(prefix="mobster-wire-") as scratch:
+        copy = Path(scratch, "db.sqlite")
+        shutil.copyfile(source, copy)
+        for suffix in ("-wal", "-shm"):
+            if Path(f"{source}{suffix}").is_file():
+                shutil.copyfile(f"{source}{suffix}", f"{copy}{suffix}")
+        deadline = time.monotonic() + QUERY_SECONDS
+        connection = sqlite3.connect(str(copy))
+        try:
+            connection.execute("PRAGMA query_only = ON")
+            connection.set_authorizer(lambda action, *_: sqlite3.SQLITE_OK if action in (
+                sqlite3.SQLITE_SELECT, sqlite3.SQLITE_READ, sqlite3.SQLITE_FUNCTION, sqlite3.SQLITE_RECURSIVE)
+                else sqlite3.SQLITE_DENY)
+            connection.set_progress_handler(lambda: int(time.monotonic() > deadline), 10000)
+            return connection.execute(assertion.query).fetchall()
+        except sqlite3.Error as error:
+            raise StoreError(f"the query on {assertion.sqlite} failed: {str(error)[:120]}.") from None
+        finally:
+            connection.close()
+
+
+def _show(text, limit=160):
+    text = secret_filter.redact(str(text))
+    return text if len(text) <= limit else text[:limit] + "…"
+
+
+def _diff(before, after):
+    old = (before[2] or "").splitlines() if before else []
+    new = (after[2] or "").splitlines() if after else []
+    if (before and before[2] is None) or (after and after[2] is None):
+        return f"{before[0] if before else 0} -> {after[0] if after else 0} bytes (not text)"
+    lines = [line for line in difflib.unified_diff(old, new, lineterm="", n=0) if line[:1] in "+-" and line[:3] not in
+             ("+++", "---")]
+    shown = "; ".join(_show(line, 80) for line in lines[:DIFF_LINES])
+    return shown + (f"; and {len(lines) - DIFF_LINES} more lines" if len(lines) > DIFF_LINES else "")
+
+
+def judge(assertion, root, before):
+    text = assertion.render()
+    if assertion.sqlite:
+        return _judge_rows(assertion, text, root, before)
+    after = _files(root, assertion.file)
+    if before is None:
+        return AssertionResult(False, text, "Mobster took no baseline before the flow, so it can't tell what changed")
+    old = before["files"]
+    moved = [(name, old.get(name), after.get(name)) for name in sorted({*old, *after})
+             if (old.get(name) or (0, ""))[1] != (after.get(name) or (0, ""))[1]]
+    if assertion.contains:
+        holds = [name for name, new in sorted(after.items()) if new[2] and assertion.contains.contains(new[2])]
+    if not assertion.changed:
+        if moved:
+            name, was, now = moved[0]
+            return AssertionResult(False, text, f"{name} changed: {_diff(was, now)}")
+        return AssertionResult(True, text, f"{len(after)} matching files unchanged" if after else
+                               "no file matches, so none changed")
+    if not moved:
+        return AssertionResult(False, text, f"none of {len(after)} matching files changed" if after
+                               else f"no file in the container matches {assertion.file}")
+    name, was, now = moved[0]
+    kind = "added" if was is None else "deleted" if now is None else "changed"
+    if assertion.contains and not holds:
+        return AssertionResult(False, text, f"{name} {kind}, but no matching file contains "
+                                            f'"{assertion.contains.render()}"')
+    return AssertionResult(True, text, f"{name} {kind}: {_diff(was, now)}" + (f" and {len(moved) - 1} more files"
+                                                                            if len(moved) > 1 else ""),
+                           ({"file": name, "diff": _diff(was, now)},))
+
+
+def _judge_rows(assertion, text, root, before):
+    try:
+        found = rows(root, assertion)
+    except StoreError as error:
+        return AssertionResult(False, text, str(error))
+    count = len(found)
+    ok = (count == assertion.equals if assertion.equals is not None
+          else count >= assertion.at_least if assertion.at_least is not None else count <= assertion.at_most)
+    was = (before or {}).get("rows")
+    shown = "; ".join(_show(row) for row in found[:ROWS_SHOWN])
+    observed = f"{count} rows" + (f" (was {was})" if was is not None else "") + (f": {shown}" if shown else "")
+    shown_rows = [[_show(cell) for cell in row] for row in found[:ROWS_SHOWN]]
+    return AssertionResult(ok, text, observed, ({"rows": shown_rows},))

mobile_agent/waiting/__init__.py

@@ -0,0 +1 @@
+"""Who's waiting on me: the people you left on read, with drafts you approve (Mobster for Mac)."""

mobile_agent/waiting/contacts.py

@@ -0,0 +1,73 @@
+"""Names for the people in Messages, from this Mac's own Contacts database, read-only."""
+
+import re
+import sqlite3
+from pathlib import Path
+from urllib.parse import quote
+
+ROOT = Path.home() / "Library" / "Application Support" / "AddressBook"
+MATCH_DIGITS = 10
+
+
+def database_paths(root=None):
+    base = Path(root) if root else ROOT
+    found = sorted(base.glob("Sources/*/AddressBook-v22.abcddb"))
+    top = base / "AddressBook-v22.abcddb"
+    return ([top] if top.is_file() else []) + found
+
+
+def digits(value):
+    return re.sub(r"\D", "", value or "")
+
+
+def phone_key(value):
+    """The last 10 digits of a phone number, or None when it has fewer than 7 digits."""
+    number = digits(value)
+    return number[-MATCH_DIGITS:] if len(number) >= 7 else None
+
+
+def _name(first, last, nick, org):
+    full = " ".join(part.strip() for part in (first, last) if part and part.strip())
+    return full or (nick or "").strip() or (org or "").strip() or None
+
+
+class ContactBook:
+    """Name lookup by handle. ``ContactBook.load(paths)``; an unreadable database is skipped."""
+
+    def __init__(self):
+        self.by_phone, self.by_email = {}, {}
+
+    @classmethod
+    def load(cls, paths=None):
+        book = cls()
+        for path in (database_paths() if paths is None else paths):
+            try:
+                book._read(path)
+            except sqlite3.Error:
+                continue
+        return book
+
+    def _read(self, path):
+        connection = sqlite3.connect(f"file:{quote(str(path))}?mode=ro", uri=True, timeout=3)
+        try:
+            connection.execute("PRAGMA query_only = ON")
+            names = {row[0]: _name(*row[1:]) for row in connection.execute(
+                "SELECT Z_PK, ZFIRSTNAME, ZLASTNAME, ZNICKNAME, ZORGANIZATION FROM ZABCDRECORD")}
+            for owner, number in connection.execute("SELECT ZOWNER, ZFULLNUMBER FROM ZABCDPHONENUMBER"):
+                key, name = phone_key(number), names.get(owner)
+                if key and name:
+                    self.by_phone.setdefault(key, name)
+            for owner, address in connection.execute("SELECT ZOWNER, ZADDRESS FROM ZABCDEMAILADDRESS"):
+                name = names.get(owner)
+                if address and name:
+                    self.by_email.setdefault(address.strip().lower(), name)
+        finally:
+            connection.close()
+
+    def name(self, handle):
+        """The contact's name for a Messages handle, or None."""
+        handle = (handle or "").strip()
+        if "@" in handle:
+            return self.by_email.get(handle.lower())
+        key = phone_key(handle)
+        return self.by_phone.get(key) if key else None