refactor: drop the unreachable XOAUTH2 .authenticate fallback

T3-21: aioimaplib's IMAP4 always has .xoauth2 and never .authenticate, so the
fallback branch and its _sasl_xoauth2 helper could not run. call
mail.xoauth2 directly.

Signed-off-by: disqualifier <dev@disqualifier.me>

README.md

@@ -11,22 +11,22 @@ This reads codes from email; it does not generate them (that is `pyotp`'s job).
 `requirements.txt`:
 
 ```
-aiomail @ git+ssh://git@git.rethinkstudios.io/rethink-public/aiomail.git@v1.0.0
+aiomail @ git+ssh://git@git.rethinkstudios.io/rethink-public/aiomail.git@v1.2.0
 # OAuth token providers (Microsoft / Google) need the extra:
-aiomail[oauth] @ git+ssh://git@git.rethinkstudios.io/rethink-public/aiomail.git@v1.0.0
+aiomail[oauth] @ git+ssh://git@git.rethinkstudios.io/rethink-public/aiomail.git@v1.2.0
 ```
 
 Direct:
 
 ```bash
-pip install "aiomail @ git+ssh://git@git.rethinkstudios.io/rethink-public/aiomail.git@v1.0.0"
-pip install "aiomail[oauth] @ git+ssh://git@git.rethinkstudios.io/rethink-public/aiomail.git@v1.0.0"
+pip install "aiomail @ git+ssh://git@git.rethinkstudios.io/rethink-public/aiomail.git@v1.2.0"
+pip install "aiomail[oauth] @ git+ssh://git@git.rethinkstudios.io/rethink-public/aiomail.git@v1.2.0"
 ```
 
 Requires `aioimaplib` and `beautifulsoup4` (pulled transitively). The `oauth`
 extra adds `aiohttp` for the refresh-token providers.
 
-Drop the `@v1.0.0` suffix from the line above to install the latest unpinned.
+Drop the `@v1.2.0` suffix from the line above to install the latest unpinned.
 
 ## Password auth
 

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "aiomail"
-version = "1.1.0"
+version = "1.2.0"
 description = "async IMAP one-time-code retrieval with password/OAuth2 auth and dynamic matching"
 requires-python = ">=3.10"
 dependencies = [

src/aiomail/auth.py

@@ -1,5 +1,4 @@
 """authentication mechanisms for the IMAP client: `PasswordAuth` (LOGIN), `OAuth2Auth` (XOAUTH2)."""
-import base64
 import logging
 from typing import Awaitable, Callable, Optional, Protocol, Union, runtime_checkable
 
@@ -36,12 +35,6 @@ def _as_str(token) -> str:
     return token.decode() if isinstance(token, bytes) else token
 
 
-def _sasl_xoauth2(user: str, token: str) -> str:
-    """build the base64 XOAUTH2 SASL initial-response string"""
-    raw = f"user={user}\x01auth=Bearer {token}\x01\x01".encode()
-    return base64.b64encode(raw).decode()
-
-
 class OAuth2Auth:
     """XOAUTH2 auth: a static `token`, or a `token_provider` (sync/async callable) fetched fresh at connect time"""
 
@@ -71,18 +64,6 @@ class OAuth2Auth:
         token = await self._resolve_token()
         # mail.xoauth2(user, token) f-string-interpolates token, so it MUST be str -
         # bytes would interpolate the b'...' repr and corrupt the Bearer value.
-        xoauth2 = getattr(mail, "xoauth2", None)
-        if xoauth2 is not None:
-            result, data = await xoauth2(self.user, token)
-        elif hasattr(mail, "authenticate"):
-            # escape hatch for a non-aioimaplib client (aioimaplib's IMAP4 always
-            # has .xoauth2, never .authenticate); untested against any real driver
-            result, data = await mail.authenticate(
-                "XOAUTH2", lambda _: _sasl_xoauth2(self.user, token)
-            )
-        else:
-            raise RuntimeError(
-                "IMAP client exposes no XOAUTH2 entrypoint (no .xoauth2 or .authenticate)"
-            )
+        result, data = await mail.xoauth2(self.user, token)
         if result != "OK":
             raise RuntimeError(f"xoauth2 auth failed: {result} {data}")

src/aiomail/client.py

@@ -229,10 +229,16 @@ class IMAPClient:
         return sorted(set(ids), reverse=True)
 
     async def fetch(self, email_id: int, *, icloud: bool = False) -> Optional[email.message.Message]:
-        """fetch and parse a full message by id"""
+        """fetch and parse a full message by id without setting \\Seen
+
+        uses BODY.PEEK[]: RFC822 / BODY[] on a SELECTed mailbox set \\Seen as a side effect
+        (RFC 3501), so a fetched-then-rejected message would vanish from every later UNSEEN
+        search. only mark_seen() flags a message. `icloud` is kept for compatibility and is
+        now a no-op (BODY.PEEK[] already works there)
+        """
         if not await self.ensure_connection():
             return None
-        part = "(BODY[])" if icloud else "(RFC822)"
+        part = "(BODY.PEEK[])"
         try:
             if self.use_uid:
                 result, data = await self._mail.uid("fetch", str(email_id), part)

src/aiomail/extract.py

@@ -15,12 +15,13 @@ log = logging.getLogger(__name__)
 MatchSpec = Union[str, Pattern, Callable[[Optional[str]], bool], None]
 
 # patterns tried (in order) against the subject then each body part; the first
-# capturing group is the code, or the whole match if there are no groups
+# capturing group is the code, or the whole match if there are no groups. no bare
+# digit catch-all here - that is the `lengths` fallback, which runs only after every
+# text missed every pattern
 DEFAULT_PATTERNS: Sequence[Union[str, Pattern]] = (
     r"(\d{4,8})\s+is\s+your",
     r"your.{0,20}?code(?:\s+is)?[:\s]+(\d{4,8})",
     r"code(?:\s+is)?[:\s]+(\d{4,8})",
-    r"\b(\d{4,8})\b",
 )
 
 # default digit-run lengths to treat as a standalone code when no pattern hits
@@ -79,15 +80,12 @@ def _iter_text(message: email.message.Message) -> Iterator[str]:
         yield text
 
 
-def _scan(text: str, patterns: list[Pattern], lengths: set[int]) -> Optional[str]:
-    """run patterns then a standalone digit-run fallback over one block of text"""
+def _match(text: str, patterns: list[Pattern]) -> Optional[str]:
+    """first pattern hit in one block of text"""
     for pat in patterns:
         m = pat.search(text)
         if m:
             return m.group(1) if m.groups() else m.group(0)
-    for run in re.findall(r"\d+", text):
-        if len(run) in lengths:
-            return run
     return None
 
 
@@ -100,20 +98,21 @@ def extract_code(
     """extract a one-time code from a message, subject first then body parts
 
     `patterns` are regexes tried in order (first capturing group wins, else the whole
-    match); if none hit, a standalone digit run whose length is in `lengths` is returned.
+    match) over the subject and every body part; only if none hit anywhere is a
+    standalone digit run whose length is in `lengths` returned, from the same texts.
     """
     compiled = _compile(patterns)
     length_set = set(lengths)
+    texts = [decode_header_value(message.get("Subject", "") or ""), *_iter_text(message)]
 
-    subject = decode_header_value(message.get("Subject", "") or "")
-    hit = _scan(subject, compiled, length_set)
-    if hit:
-        return hit
-
-    for text in _iter_text(message):
-        hit = _scan(text, compiled, length_set)
+    for text in texts:
+        hit = _match(text, compiled)
         if hit:
             return hit
+    for text in texts:
+        for run in re.findall(r"\d+", text):
+            if len(run) in length_set:
+                return run
     return None
 
 

src/aiomail/retrieve.py

@@ -22,9 +22,12 @@ log = logging.getLogger(__name__)
 DEFAULT_FOLDERS: Sequence[str] = ("INBOX", "Junk", "Spam", "Archive", "All Mail")
 
 
-def _server_query(sender: MatchSpec, subject: MatchSpec, match_field: str = "from") -> str:
-    """build a narrowing IMAP query from plain-string specs, falling back to ALL for regex/callable specs"""
-    parts: List[str] = []
+def _server_query(sender: MatchSpec, subject: MatchSpec, match_field: str = "from", unseen: bool = False) -> str:
+    """build a narrowing IMAP query from plain-string specs (ALL when nothing narrows)
+
+    `unseen` adds UNSEEN so a code already consumed (marked seen) is never served again
+    """
+    parts: List[str] = ["UNSEEN"] if unseen else []
     if isinstance(sender, str):
         if match_field == "to":
             parts.append(f'OR TO "{sender}" FROM "{sender}"')
@@ -73,20 +76,20 @@ async def retrieve_otp(
     sender/subject accept a substring, a compiled regex, or a callable.
     `match_field="to"` matches the recipient address and additionally accepts a
     forwarded match on From. set `max_age=None` to disable the freshness check.
+    with `mark_seen=True` (default) only UNSEEN messages are searched, so a code is
+    returned once; `mark_seen=False` searches seen messages too.
     """
     folders = list(folders) if folders is not None else list(DEFAULT_FOLDERS)
     lengths = list(lengths)
     sender_ok = as_predicate(sender)
     subject_ok = as_predicate(subject)
-    query = _server_query(sender, subject, match_field)
+    query = _server_query(sender, subject, match_field, unseen=mark_seen)
 
     for attempt in range(retries + 1):
         for folder in folders:
             if not await client.select(folder):
                 continue
             ids = await client.search(query)
-            if not ids and query != "ALL":
-                ids = await client.search("ALL")
             if not ids:
                 continue