fix: add match_field=from|to to restore recipient-primary OTP matching

the clean lib matched senders by From only; the original imap_tool.py matched primarily by TO (the per-user alias the code was sent to) with a HEADER FROM forwarded fallback. added match_field="from"|"to" to retrieve_otp: "from" (default) is byte-identical to current behavior, "to" searches TO primary and accepts a forwarded From match, restoring the alias flow. server query + client-side predicate both honor it. bump to v0.1.2.

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

README.md

@@ -11,16 +11,16 @@ 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@v0.1.1
+aiomail @ git+ssh://git@git.rethinkstudios.io/rethink-public/aiomail.git@v0.1.2
 # OAuth token providers (Microsoft / Google) need the extra:
-aiomail[oauth] @ git+ssh://git@git.rethinkstudios.io/rethink-public/aiomail.git@v0.1.1
+aiomail[oauth] @ git+ssh://git@git.rethinkstudios.io/rethink-public/aiomail.git@v0.1.2
 ```
 
 Direct:
 
 ```bash
-pip install "aiomail @ git+ssh://git@git.rethinkstudios.io/rethink-public/aiomail.git@v0.1.1"
-pip install "aiomail[oauth] @ git+ssh://git@git.rethinkstudios.io/rethink-public/aiomail.git@v0.1.1"
+pip install "aiomail @ git+ssh://git@git.rethinkstudios.io/rethink-public/aiomail.git@v0.1.2"
+pip install "aiomail[oauth] @ git+ssh://git@git.rethinkstudios.io/rethink-public/aiomail.git@v0.1.2"
 ```
 
 Requires `aioimaplib` and `beautifulsoup4` (pulled transitively). The `oauth`

ledger.md

@@ -0,0 +1,25 @@
+# aiomail — ledger
+
+## v0.1.2
+
+- **fidelity capability (non-breaking):** added `match_field="from"|"to"` to
+  `retrieve_otp`. `"from"` (default) is the current behavior, byte-identical — matches
+  the sender address. `"to"` matches the recipient address (the per-user alias the code
+  was sent to) primary, and additionally accepts a forwarded match on the From header,
+  restoring the original `imap_tool.py` recipient-primary matching for alias flows. The
+  server query builds `TO "..."` (vs `FROM "..."`) and the client-side predicate checks
+  the To header (with the From fallback) accordingly.
+
+## v0.1.1
+
+- **XOAUTH2 token is str, not bytes:** aioimaplib f-string-interpolates the token into
+  the SASL string, so a bytes token injected a `b'...'` repr and broke every login.
+  Dropped the `.encode()`. (A false CLAUDE.md "bytes required" note had propagated this.)
+- tolerant SEARCH parse (skip non-numeric tokens instead of crashing the whole search).
+- `connect()` logs out the IMAP object on a failed attempt (was a socket leak); moved the
+  `asyncio` import in `oauth.py` to module top.
+
+## v0.1.0
+
+- initial: async IMAP one-time-code retrieval; password + XOAUTH2 auth, dynamic
+  sender/subject/code matching via flexible match specs.

pyproject.toml

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

src/aiomail/__init__.py

@@ -29,4 +29,4 @@ __all__ = [
     "DEFAULT_FOLDERS",
 ]
 
-__version__ = "0.1.1"
+__version__ = "0.1.2"

src/aiomail/retrieve.py

@@ -20,16 +20,18 @@ log = logging.getLogger(__name__)
 DEFAULT_FOLDERS: Sequence[str] = ("INBOX", "Junk", "Spam", "Archive", "All Mail")
 
 
-def _server_query(sender: MatchSpec, subject: MatchSpec) -> str:
+def _server_query(sender: MatchSpec, subject: MatchSpec, match_field: str = "from") -> str:
     """build a narrowing IMAP query from plain-string specs only
 
-    only plain strings translate to server-side FROM/SUBJECT filters; regex and
-    callable specs fall back to ALL and are filtered client-side, so dynamic
-    matching always works even when the server cannot express it.
+    only plain strings translate to server-side filters; regex and callable specs
+    fall back to ALL and are filtered client-side, so dynamic matching always works
+    even when the server cannot express it. `match_field` selects which header the
+    `sender` spec searches: "from" filters by the sender address (default), "to"
+    filters by the recipient address (the per-user alias the code was sent to).
     """
     parts: List[str] = []
     if isinstance(sender, str):
-        parts.append(f'FROM "{sender}"')
+        parts.append(f'TO "{sender}"' if match_field == "to" else f'FROM "{sender}"')
     if isinstance(subject, str):
         parts.append(f'SUBJECT "{subject}"')
     return f"({' '.join(parts)})" if parts else "ALL"
@@ -52,6 +54,7 @@ async def retrieve_otp(
     *,
     sender: MatchSpec = None,
     subject: MatchSpec = None,
+    match_field: str = "from",
     folders: Optional[Iterable[str]] = None,
     patterns: Sequence[Union[str, Pattern]] = DEFAULT_PATTERNS,
     lengths: Iterable[int] = DEFAULT_LENGTHS,
@@ -64,14 +67,18 @@ async def retrieve_otp(
 ) -> Optional[str]:
     """return the newest OTP matching the filters, or None
 
-    sender/subject accept a substring, a compiled regex, or a callable. folders,
-    patterns, code lengths, max age and retry behavior are all tunable. set
-    `max_age=None` to disable the freshness check.
+    sender/subject accept a substring, a compiled regex, or a callable. `match_field`
+    selects which header the `sender` spec is matched against: "from" (default)
+    matches the sender address; "to" matches the recipient address (the per-user
+    alias the code was sent to) and additionally accepts a forwarded match on the
+    From header, so a forwarded code still resolves. folders, patterns, code lengths,
+    max age and retry behavior are all tunable. set `max_age=None` to disable the
+    freshness check.
     """
     folders = list(folders) if folders is not None else list(DEFAULT_FOLDERS)
     sender_ok = as_predicate(sender)
     subject_ok = as_predicate(subject)
-    query = _server_query(sender, subject)
+    query = _server_query(sender, subject, match_field)
 
     for attempt in range(retries + 1):
         for folder in folders:
@@ -91,7 +98,12 @@ async def retrieve_otp(
 
                 from_hdr = message.get("From", "")
                 subj_hdr = message.get("Subject", "")
-                if not sender_ok(from_hdr) or not subject_ok(subj_hdr):
+                if match_field == "to":
+                    to_hdr = message.get("To", "")
+                    matched = sender_ok(to_hdr) or sender_ok(from_hdr)
+                else:
+                    matched = sender_ok(from_hdr)
+                if not matched or not subject_ok(subj_hdr):
                     continue
 
                 code = extract_code(message, patterns=patterns, lengths=lengths)