imessage-chatdb 0.1.0__py3-none-any.whl

imessage_chatdb/__init__.py

@@ -0,0 +1,123 @@
+"""imessage-chatdb: a read-only, stdlib-only reader for Apple Messages ``chat.db``.
+
+The public surface of DESIGN.md section 4: :func:`open` / :class:`ChatDB`
+(section 4.1, 4.5), the schema (4.2), the pure functions and constants (4.3),
+the models (5), the errors (6.6) and the polling primitives (4.6).  The query
+functions that take a connection (section 4.4) live on their submodules
+(``imessage_chatdb.messages``, ``.attachments``, ``.chats``, ``.search``) and
+behind the same names on :class:`ChatDB`.
+
+One name is deliberately kept off ``__all__``: ``imessage_chatdb.open``
+exists (``imessage_chatdb.open(path)``) but is not exported, so
+``from imessage_chatdb import *`` never shadows the builtin.  The polling
+primitives live in ``imessage_chatdb.polling`` and are re-exported here, so
+``imessage_chatdb.watch`` *is* the ``watch()`` generator (also reachable as
+:meth:`ChatDB.watch`).
+
+Nothing here opens a database at import time.
+"""
+
+from __future__ import annotations
+
+from .connection import DEFAULT_CHATDB, open_connection
+from .dates import APPLE_EPOCH_OFFSET, apple_to_datetime, apple_to_unix, unix_to_apple
+from .db import ChatDB
+from .db import open as open
+from .errors import ChatDBAccessError, ChatDBBusy, ChatDBError, CursorAhead, SchemaError
+from .handles import address_key, is_email, is_group_style
+from .keyed_archive import KeyedArchive
+from .link_preview import (
+    LINK_BALLOON,
+    SKIP_IMG,
+    LinkPreview,
+    embedded_image,
+    embedded_images,
+    parse_link_preview,
+    sniff_image_mime,
+)
+from .models import (
+    Attachment,
+    Chat,
+    ChatMatch,
+    ChatSummary,
+    LiteMessage,
+    Message,
+    ReplyTarget,
+    SearchHit,
+)
+from .polling import Cursor, Event, poll_once, run_watch, watch
+from .reactions import Reaction, classify_reaction, parse_associated_guid
+from .schema import OPTIONAL, REQUIRED, Schema, build_message_select
+from .search import extract_urls, snippet
+from .services import Service, normalize_service, service_family
+from .typedstream import clean_text, effective_text, extract_text
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    # errors
+    "ChatDBError",
+    "ChatDBAccessError",
+    "ChatDBBusy",
+    "CursorAhead",
+    "SchemaError",
+    # opening (``open`` is an attribute, not an export: see the module docstring)
+    "DEFAULT_CHATDB",
+    "open_connection",
+    "ChatDB",
+    # schema
+    "Schema",
+    "REQUIRED",
+    "OPTIONAL",
+    "build_message_select",
+    # dates
+    "APPLE_EPOCH_OFFSET",
+    "apple_to_unix",
+    "unix_to_apple",
+    "apple_to_datetime",
+    # typedstream
+    "extract_text",
+    "effective_text",
+    "clean_text",
+    # keyed archive
+    "KeyedArchive",
+    # link preview
+    "LINK_BALLOON",
+    "SKIP_IMG",
+    "LinkPreview",
+    "parse_link_preview",
+    "embedded_images",
+    "embedded_image",
+    "sniff_image_mime",
+    # reactions
+    "Reaction",
+    "classify_reaction",
+    "parse_associated_guid",
+    # services
+    "Service",
+    "normalize_service",
+    "service_family",
+    # handles
+    "address_key",
+    "is_email",
+    "is_group_style",
+    # search helpers
+    "extract_urls",
+    "snippet",
+    # models
+    "Message",
+    "Attachment",
+    "ReplyTarget",
+    "LiteMessage",
+    "Chat",
+    "ChatSummary",
+    "ChatMatch",
+    "SearchHit",
+    # polling (``imessage_chatdb.polling``)
+    "Cursor",
+    "Event",
+    "poll_once",
+    "watch",
+    "run_watch",
+]

imessage_chatdb/__main__.py

@@ -0,0 +1,355 @@
+"""``python -m imessage_chatdb`` - a small JSON-lines command line (DESIGN.md section 4.7).
+
+Subcommands::
+
+    check                       open the database, print profile + max ROWID + "Full Disk Access OK"
+    tail [--since-rowid N] [--follow] [--limit N] [--interval S]
+    chats [--limit N]
+    search TEXT [--limit N]
+
+Every subcommand takes ``--db PATH`` (default ``~/Library/Messages/chat.db``).
+``tail``, ``chats`` and ``search`` print one JSON object per line from
+``Message.to_dict()`` / ``ChatSummary.to_dict()`` / ``SearchHit.to_dict()``;
+``check`` prints one JSON object describing the database.
+
+Privacy: ``tail``, ``chats`` and ``search`` print message content (text,
+handles, chat names) to stdout as JSON lines, so do not point them at a log
+file or a remote pipe; the library itself never logs or prints message
+content.  ``check`` prints only the path, profile and max ROWID.
+
+Exit codes: 0 success; 1 any other ``ChatDBError`` (busy, schema); 2 the
+database could not be opened (``ChatDBAccessError``: the message, which names
+the path and the interpreter binary that needs Full Disk Access, goes to
+stderr); 64 (``EX_USAGE``) a command-line usage error (unknown subcommand, bad
+flag or value -- argparse's default of 2 is *not* used, so a health probe that
+treats 2 as "Full Disk Access lost" cannot misfire on a typo); 130 interrupted.
+``--help`` exits 0.  A stdout closed early by its reader (``tail ... | head
+-1``) is not an error: output stops, nothing is printed about the broken pipe
+(stdout is pointed at ``os.devnull`` so the interpreter's shutdown flush cannot
+fail again) and the exit code is 0.
+
+The CLI is built on the module-level query functions rather than the
+``ChatDB`` facade so it stays a thin, dependency-free layer; it opens one
+connection per command (and one per polling round in ``--follow`` mode),
+exactly as the facade does.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sqlite3
+import sys
+import time
+from collections.abc import Callable, Sequence
+from typing import IO, Any, NoReturn
+
+from .chats import chats_by_activity
+from .connection import DEFAULT_CHATDB, open_connection
+from .errors import ChatDBAccessError, ChatDBBusy, ChatDBError
+from .messages import max_rowid, messages_after
+from .schema import Schema
+from .search import search as search_hits
+
+__all__ = ["UsageError", "build_parser", "main"]
+
+EXIT_OK = 0
+EXIT_ERROR = 1
+EXIT_ACCESS = 2
+EXIT_USAGE = 64  # sysexits.h EX_USAGE; distinct from EXIT_ACCESS on purpose
+EXIT_INTERRUPTED = 130
+
+DEFAULT_CHATS_LIMIT = 200
+DEFAULT_SEARCH_LIMIT = 30
+DEFAULT_FOLLOW_INTERVAL = 2.0
+
+#: Shown by ``--help`` (main, ``tail``, ``chats`` and ``search``): the only
+#: place the library prints message content (``chats`` prints handles and
+#: chat names, which count).
+PRIVACY_NOTE = (
+    "privacy: tail, chats and search print message content (text, handles, chat names) "
+    "to stdout as JSON lines; do not point them at a log file or a remote pipe."
+)
+
+
+class UsageError(SystemExit):
+    """A command-line usage error; ``code`` is :data:`EXIT_USAGE`.
+
+    Raised by the parser :func:`build_parser` returns in place of argparse's
+    ``SystemExit(2)`` so that exit code 2 stays reserved for "cannot open the
+    database".  ``usage`` is the parser's usage line and ``message`` the
+    explanation; :func:`main` writes both to its ``stderr`` stream.
+    """
+
+    def __init__(self, usage: str, message: str) -> None:
+        super().__init__(EXIT_USAGE)
+        self.usage = usage
+        self.message = message
+
+    def __str__(self) -> str:
+        return self.message
+
+
+class _Parser(argparse.ArgumentParser):
+    """``ArgumentParser`` whose errors raise :class:`UsageError` (code 64, not 2).
+
+    Subparsers are created with ``parser_class=type(self)`` by argparse, so
+    every subcommand's errors take the same path.
+    """
+
+    def error(self, message: str) -> NoReturn:
+        raise UsageError(self.format_usage(), f"{self.prog}: error: {message}")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """The argparse parser; ``--db`` is accepted after every subcommand.
+
+    Usage errors raise :class:`UsageError` (a ``SystemExit`` with code 64)
+    instead of exiting with argparse's 2; ``--help`` still exits 0.
+    """
+    common = _Parser(add_help=False)  # same class so subparsers accept it as a parent
+    common.add_argument(
+        "--db",
+        default=DEFAULT_CHATDB,
+        metavar="PATH",
+        help=f"path to chat.db (default: {DEFAULT_CHATDB})",
+    )
+
+    parser = _Parser(
+        prog="python -m imessage_chatdb",
+        description="Read-only JSON-lines access to an Apple Messages chat.db.",
+        epilog=PRIVACY_NOTE,
+    )
+    sub = parser.add_subparsers(dest="command", required=True, metavar="COMMAND")
+
+    sub.add_parser(
+        "check",
+        parents=[common],
+        help="open the database and report the schema profile and max ROWID",
+    )
+
+    tail = sub.add_parser(
+        "tail",
+        parents=[common],
+        help="print messages with ROWID > N (default: start at now, like watch())",
+        epilog=PRIVACY_NOTE,
+    )
+    tail.add_argument(
+        "--since-rowid",
+        type=int,
+        default=None,
+        metavar="N",
+        help="print messages with ROWID > N; omitted = start at MAX(ROWID) (no replay)",
+    )
+    tail.add_argument(
+        "--follow",
+        action="store_true",
+        help="keep polling for new messages until interrupted",
+    )
+    tail.add_argument(
+        "--limit",
+        type=int,
+        default=None,
+        metavar="N",
+        help="cap the number of messages printed in one round",
+    )
+    tail.add_argument(
+        "--interval",
+        type=float,
+        default=DEFAULT_FOLLOW_INTERVAL,
+        metavar="SECONDS",
+        help=f"seconds between polls with --follow (default: {DEFAULT_FOLLOW_INTERVAL})",
+    )
+
+    chats = sub.add_parser(
+        "chats",
+        parents=[common],
+        help="list chats, most recent activity first",
+        epilog=PRIVACY_NOTE,
+    )
+    chats.add_argument(
+        "--limit",
+        type=int,
+        default=DEFAULT_CHATS_LIMIT,
+        metavar="N",
+        help=f"maximum number of chats (default: {DEFAULT_CHATS_LIMIT})",
+    )
+
+    srch = sub.add_parser(
+        "search", parents=[common], help="search message text, newest first", epilog=PRIVACY_NOTE
+    )
+    srch.add_argument("text", metavar="TEXT", help="text to search for (case-insensitive)")
+    srch.add_argument(
+        "--limit",
+        type=int,
+        default=DEFAULT_SEARCH_LIMIT,
+        metavar="N",
+        help=f"maximum number of hits (default: {DEFAULT_SEARCH_LIMIT})",
+    )
+    return parser
+
+
+def _emit(out: IO[str], obj: dict[str, Any]) -> None:
+    out.write(json.dumps(obj, ensure_ascii=False))
+    out.write("\n")
+    out.flush()
+
+
+def _discard_further_output(out: IO[str]) -> None:
+    """After a ``BrokenPipeError`` on ``out``, point its descriptor at ``os.devnull``.
+
+    The reader of our stdout went away (``| head -1``).  Python flushes the
+    standard streams again at interpreter shutdown, which would raise a second
+    ``BrokenPipeError`` ("Exception ignored in ...") and turn the exit code
+    into 120; redirecting the descriptor first is the recipe from the
+    ``signal`` module documentation.  Only the stream that actually broke is
+    touched: an injected ``stdout`` without a descriptor (a test double, an
+    ``io.StringIO``) leaves the process's real stdout alone.
+    """
+    try:
+        fd = out.fileno()
+    except (AttributeError, OSError, ValueError):  # io.UnsupportedOperation is both
+        return
+    devnull = os.open(os.devnull, os.O_WRONLY)
+    try:
+        os.dup2(devnull, fd)
+    finally:
+        os.close(devnull)
+
+
+def _cmd_check(args: argparse.Namespace, out: IO[str]) -> int:
+    conn = open_connection(args.db)
+    try:
+        schema = Schema(conn)
+        schema.check()
+        top = max_rowid(conn)
+    finally:
+        conn.close()
+    _emit(
+        out,
+        {
+            "ok": True,
+            "path": args.db,
+            "profile": schema.profile,
+            "max_rowid": top,
+            "optional_missing": sorted(schema.optional_missing),
+            "message": "Full Disk Access OK",
+        },
+    )
+    return EXIT_OK
+
+
+def _tail_round(
+    db_path: str, since: int | None, limit: int | None, out: IO[str], err: IO[str]
+) -> int:
+    """One ``messages_after`` round on a fresh connection; returns the new cursor."""
+    conn = open_connection(db_path)
+    try:
+        schema = Schema(conn)
+        top = max_rowid(conn)
+        cursor = top if since is None else since
+        if cursor > top:
+            # The database was rebuilt (CursorAhead in watch terms); restart at now.
+            err.write(f"warning: rowid {cursor} is ahead of MAX(ROWID) {top}; restarting at now\n")
+            cursor = top
+        for m in messages_after(conn, schema, cursor, limit=limit):
+            _emit(out, m.to_dict())
+            cursor = m.rowid
+        return cursor
+    finally:
+        conn.close()
+
+
+def _cmd_tail(
+    args: argparse.Namespace, out: IO[str], err: IO[str], sleep: Callable[[float], None]
+) -> int:
+    since: int | None = args.since_rowid
+    if not args.follow:
+        _tail_round(args.db, since, args.limit, out, err)
+        return EXIT_OK
+    cursor = since
+    try:
+        while True:
+            try:
+                cursor = _tail_round(args.db, cursor, args.limit, out, err)
+            except ChatDBBusy:
+                pass  # retry next round, nothing advanced
+            sleep(args.interval)
+    except KeyboardInterrupt:
+        return EXIT_INTERRUPTED
+
+
+def _cmd_chats(args: argparse.Namespace, out: IO[str]) -> int:
+    conn = open_connection(args.db)
+    try:
+        for c in chats_by_activity(conn, limit=args.limit):
+            _emit(out, c.to_dict())
+    finally:
+        conn.close()
+    return EXIT_OK
+
+
+def _cmd_search(args: argparse.Namespace, out: IO[str]) -> int:
+    conn = open_connection(args.db)
+    try:
+        for hit in search_hits(conn, args.text, limit=args.limit):
+            _emit(out, hit.to_dict())
+    finally:
+        conn.close()
+    return EXIT_OK
+
+
+def main(
+    argv: Sequence[str] | None = None,
+    *,
+    stdout: IO[str] | None = None,
+    stderr: IO[str] | None = None,
+    sleep: Callable[[float], None] = time.sleep,
+) -> int:
+    """Run the CLI and return its exit code; it never raises ``SystemExit``.
+
+    ``stdout``/``stderr`` default to ``sys.stdout``/``sys.stderr``; ``sleep`` is
+    the pause between ``--follow`` rounds (injectable for tests).  A usage error
+    returns :data:`EXIT_USAGE` (64) with the usage line and explanation on
+    ``stderr``; ``--help`` prints to ``sys.stdout`` and returns 0.  A
+    ``BrokenPipeError`` from ``stdout`` (its reader closed the pipe) ends the
+    command with :data:`EXIT_OK` after redirecting the broken descriptor to
+    ``os.devnull``, so nothing is printed at shutdown.
+    """
+    out = sys.stdout if stdout is None else stdout
+    err = sys.stderr if stderr is None else stderr
+    try:
+        args = build_parser().parse_args(argv)
+    except UsageError as exc:
+        err.write(exc.usage)
+        err.write(f"{exc.message}\n")
+        return EXIT_USAGE
+    except SystemExit as exc:  # --help; argparse exits 0 after printing
+        return EXIT_OK if exc.code in (None, 0) else EXIT_USAGE
+    try:
+        if args.command == "check":
+            return _cmd_check(args, out)
+        if args.command == "tail":
+            return _cmd_tail(args, out, err, sleep)
+        if args.command == "chats":
+            return _cmd_chats(args, out)
+        if args.command == "search":
+            return _cmd_search(args, out)
+        raise AssertionError(f"unhandled command {args.command!r}")  # pragma: no cover
+    except ChatDBAccessError as exc:
+        err.write(f"error: {exc}\n")
+        return EXIT_ACCESS
+    except ChatDBError as exc:
+        err.write(f"error: {exc}\n")
+        return EXIT_ERROR
+    except sqlite3.Error as exc:
+        err.write(f"error: sqlite3: {exc}\n")
+        return EXIT_ERROR
+    except BrokenPipeError:
+        _discard_further_output(out)
+        return EXIT_OK
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

imessage_chatdb/attachments.py

@@ -0,0 +1,215 @@
+"""Attachment queries (DESIGN.md sections 4.4, 6.1, 8.4 attachments).
+
+Every function takes an open read-only ``sqlite3.Connection`` whose
+``row_factory`` is ``sqlite3.Row`` (what :func:`imessage_chatdb.open_connection`
+returns) and ends in ``fetchall()``.
+
+The default exclusion is the ``transfer_name`` suffix
+``.pluginPayloadAttachment`` (rich-link payload blobs that Messages renders as
+cards), **never** ``hide_attachment``: on a live database ``hide_attachment=1``
+also covers a handful of ordinary images that the relay surfaces today
+(section 2).  ``include_plugin_payloads=True`` turns the filter off.
+
+The two JSON-visible statements, ``ATTACHMENTS_FOR`` (no ``ORDER BY``: SQLite
+scan order) and ``CHAT_ATTACHMENTS`` (``ORDER BY m.date DESC``, ties in scan
+order), are executed as the verbatim ``sql.py`` constants with **only** extra
+result columns appended to the relay's select list (:func:`_widen`): the
+relay's columns come first under the relay's aliases, then ``a.ROWID AS
+att_rowid, a.*`` so the ``Attachment`` model can carry ``rowid``, ``filename``
+and the optional columns.  Every clause from ``FROM`` onward is byte-equal to
+the relay's, and the extra columns are all read from ``a`` by rowid, so the
+query plan (and therefore the implicit row order) is the relay's;
+``tests/test_attachments.py`` asserts both the text derivation and
+``EXPLAIN QUERY PLAN`` equality on every schema profile.  Optional
+``attachment`` columns (``uti``, ``total_bytes``, ``is_sticker``,
+``hide_attachment``) are read by name when present and are ``None`` otherwise,
+so no schema introspection query is needed.
+"""
+
+from __future__ import annotations
+
+import re
+import sqlite3
+from collections.abc import Iterable
+from typing import Any
+
+from .models import PLUGIN_PAYLOAD_SUFFIX, Attachment
+from .sql import ATTACHMENTS_FOR, CHAT_ATTACHMENTS, PAYLOAD_FOR, expand_in
+
+__all__ = [
+    "is_plugin_payload",
+    "attachments_for",
+    "attachment_by_guid",
+    "chat_attachments",
+    "payload_for",
+]
+
+#: The columns appended to the relay's select list so ``row_to_attachment``
+#: can build the model (``att_rowid`` explicit; ``a.*`` for everything else).
+WIDE_EXTRA_COLUMNS = "a.ROWID AS att_rowid, a.*"
+
+_FROM_CLAUSE = re.compile(r"\n\s+FROM ")
+
+
+def _widen(statement: str, extra: str = WIDE_EXTRA_COLUMNS) -> str:
+    """Append ``extra`` to the select list of a verbatim relay statement.
+
+    The statement text from its first ``FROM`` clause onward is returned
+    byte-for-byte; only ``, extra`` is inserted at the end of the select list.
+    """
+    m = _FROM_CLAUSE.search(statement)
+    if m is None:
+        raise ValueError("statement has no FROM clause on its own line")
+    return statement[: m.start()] + ", " + extra + statement[m.start() :]
+
+
+# The verbatim ATTACHMENTS_FOR + the extra columns.
+_ATTACHMENTS_FOR_WIDE = _widen(ATTACHMENTS_FOR)
+
+# The verbatim CHAT_ATTACHMENTS + the owning message's ROWID
+# and the extra columns; the ``ORDER BY m.date DESC`` is the relay's.
+_CHAT_ATTACHMENTS_WIDE = _widen(CHAT_ATTACHMENTS, "m.ROWID AS mid, " + WIDE_EXTRA_COLUMNS)
+
+# One attachment by guid, with the owning message when it has one (the verbatim
+# ATTACHMENT_BY_GUID reads only filename/mime/transfer_name).
+_ATTACHMENT_BY_GUID_WIDE = """SELECT maj.message_id AS mid, a.ROWID AS att_rowid, a.*
+            FROM attachment a
+            LEFT JOIN message_attachment_join maj ON maj.attachment_id = a.ROWID
+            WHERE a.guid = ?
+            ORDER BY maj.message_id LIMIT 1"""
+
+
+def is_plugin_payload(transfer_name: str | None) -> bool:
+    """The relay's filter: ``(transfer_name or "").endswith(".pluginPayloadAttachment")``."""
+    return (transfer_name or "").endswith(PLUGIN_PAYLOAD_SUFFIX)
+
+
+def _opt(r: sqlite3.Row, keys: set[str], name: str) -> Any:
+    """``r[name]`` when the row carries ``name``, else ``None`` (missing optional column)."""
+    return r[name] if name in keys else None
+
+
+def _opt_bool(r: sqlite3.Row, keys: set[str], name: str) -> bool | None:
+    v = _opt(r, keys, name)
+    return None if v is None else bool(v)
+
+
+def _opt_int(r: sqlite3.Row, keys: set[str], name: str) -> int | None:
+    v = _opt(r, keys, name)
+    return None if v is None else int(v)
+
+
+def _opt_str(r: sqlite3.Row, keys: set[str], name: str) -> str | None:
+    v = _opt(r, keys, name)
+    return None if v is None else str(v)
+
+
+def row_to_attachment(
+    r: sqlite3.Row, *, message_rowid: int, message_date: int | None
+) -> Attachment:
+    """Build an ``Attachment`` from a ``a.*`` row (plus ``att_rowid``).
+
+    ``is_sticker`` / ``hide_attachment`` become ``bool`` (``None`` when the
+    column is absent or NULL); ``total_bytes`` is an ``int`` or ``None``.
+    """
+    keys = set(r.keys())
+    return Attachment(
+        message_rowid=message_rowid,
+        rowid=int(r["att_rowid"]),
+        guid=str(r["guid"]),
+        mime_type=_opt_str(r, keys, "mime_type"),
+        transfer_name=_opt_str(r, keys, "transfer_name"),
+        filename=_opt_str(r, keys, "filename"),
+        uti=_opt_str(r, keys, "uti"),
+        total_bytes=_opt_int(r, keys, "total_bytes"),
+        is_sticker=_opt_bool(r, keys, "is_sticker"),
+        hide_attachment=_opt_bool(r, keys, "hide_attachment"),
+        message_date=message_date,
+    )
+
+
+def attachments_for(
+    conn: sqlite3.Connection,
+    rowids: Iterable[int],
+    *,
+    include_plugin_payloads: bool = False,
+) -> dict[int, list[Attachment]]:
+    """Attachments of the given message ROWIDs, keyed by message ROWID.
+
+    One ``IN`` query (no ``ORDER BY``, as the relay); no query at all when
+    ``rowids`` is empty.  Messages without attachments have no key.  Plugin
+    payload rows are skipped unless ``include_plugin_payloads``.
+    """
+    ids = list(dict.fromkeys(int(x) for x in rowids))
+    if not ids:
+        return {}
+    rows = conn.execute(expand_in(_ATTACHMENTS_FOR_WIDE, len(ids)), tuple(ids)).fetchall()
+    out: dict[int, list[Attachment]] = {}
+    for r in rows:
+        if not include_plugin_payloads and is_plugin_payload(r["transfer_name"]):
+            continue
+        mid = int(r["mid"])
+        out.setdefault(mid, []).append(row_to_attachment(r, message_rowid=mid, message_date=None))
+    return out
+
+
+def attachment_by_guid(conn: sqlite3.Connection, guid: str) -> Attachment | None:
+    """The attachment with ``guid``, or ``None``.
+
+    ``message_rowid`` is the lowest joined message ROWID, or ``0`` when the
+    attachment has no ``message_attachment_join`` row.  No plugin-payload
+    filter: a caller asking by guid wants that row.
+    """
+    rows = conn.execute(_ATTACHMENT_BY_GUID_WIDE, (guid,)).fetchall()
+    if not rows:
+        return None
+    r = rows[0]
+    mid = 0 if r["mid"] is None else int(r["mid"])
+    return row_to_attachment(r, message_rowid=mid, message_date=None)
+
+
+def chat_attachments(
+    conn: sqlite3.Connection,
+    chat_guid: str,
+    *,
+    include_plugin_payloads: bool = False,
+) -> list[Attachment]:
+    """Every attachment in the chat with ``chat_guid``, newest message first.
+
+    The verbatim ``CHAT_ATTACHMENTS`` statement: ``ORDER BY m.date DESC``.  Each
+    ``Attachment.message_date`` carries the owning message's raw Apple date.
+    """
+    rows = conn.execute(_CHAT_ATTACHMENTS_WIDE, (chat_guid,)).fetchall()
+    out: list[Attachment] = []
+    for r in rows:
+        if not include_plugin_payloads and is_plugin_payload(r["transfer_name"]):
+            continue
+        date = r["date"]
+        out.append(
+            row_to_attachment(
+                r,
+                message_rowid=int(r["mid"]),
+                message_date=None if date is None else int(date),
+            )
+        )
+    return out
+
+
+def payload_for(conn: sqlite3.Connection, rowid: int) -> bytes | None:
+    """Raw ``message.payload_data`` for ``rowid`` (``None`` when absent or NULL).
+
+    Also ``None`` when the schema has no ``payload_data`` column at all
+    (optional per section 4.2).
+    """
+    try:
+        rows = conn.execute(PAYLOAD_FOR, (rowid,)).fetchall()
+    except sqlite3.OperationalError as exc:
+        if "no such column" in str(exc).lower():
+            return None
+        raise
+    if not rows:
+        return None
+    data = rows[0][0]
+    if data is None:
+        return None
+    return bytes(data)