Antispam: mirror the engine in dev, and never file a contact as spam

Dev compose gains rspamd + redis-rspamd, matching production. The dev API and
worker run on the host rather than in the compose network, so the ports are
published on loopback and RSPAMD_URL points at 127.0.0.1 — documented in
.env.example.

Contacts now cap a verdict at "banner": mail from someone in the user's address
book is never moved to Junk. Capped rather than exempted, because the way this
fails in practice is a contact's account being compromised and spamming its own
address book — the warning still has value even when the move would be wrong.
An explicit deny rule still wins; that is the user overruling us deliberately.

The lookup reads the contacts plugin's table directly and forgives its absence:
no contacts plugin means no contacts to check, not an error. Addresses are
stored as the user typed them, so both sides are lower-cased rather than relying
on the jsonb containment index, and secondary addresses in the emails array
count as well as the primary. It runs only when the verdict would otherwise be a
move, so the common path pays nothing.

Also fixes a test that asserted stats degrade "without an engine" by relying on
no engine being present — true until this commit. It now simulates the absence.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018SqJYt7jD7oUEkoY68sBZo

plugins/webmail_plugin_antispam/webmail_plugin_antispam/hook.py

@@ -106,6 +106,19 @@ async def on_message_new(payload: dict[str, Any]) -> None:
                 action = policy.decide(
                     sender=sender, rules=rules, score=verdict.score, settings=settings
                 )
+                # Only ask the address book when the answer could change the
+                # outcome — i.e. when we are about to move the message. On the
+                # overwhelmingly common path (not spam) this costs nothing.
+                if action == "moved" and await policy.sender_in_contacts(
+                    user_id, sender
+                ):
+                    action = policy.decide(
+                        sender=sender,
+                        rules=rules,
+                        score=verdict.score,
+                        settings=settings,
+                        contact=True,
+                    )
 
     if action in ("moved", "deny_listed"):
         moved = await _SDK.actions.move_to_special(user_id, message_id, "junk")

plugins/webmail_plugin_antispam/webmail_plugin_antispam/migrations/versions/0001_init.py

@@ -72,7 +72,9 @@ def upgrade() -> None:
         "CREATE INDEX ix_plg_antispam_verdicts_user_action "
         "ON plg_antispam_verdicts (user_id, action)"
     )
-    op.execute("CREATE INDEX ix_plg_antispam_rules_user_kind ON plg_antispam_rules (user_id, kind)")
+    op.execute(
+        "CREATE INDEX ix_plg_antispam_rules_user_kind ON plg_antispam_rules (user_id, kind)"
+    )
 
     enable_rls("plg_antispam_settings")
     enable_rls("plg_antispam_rules")

plugins/webmail_plugin_antispam/webmail_plugin_antispam/policy.py

@@ -85,6 +85,41 @@ async def load_rules(user_id: uuid.UUID) -> dict[str, set[str]]:
     return out
 
 
+async def sender_in_contacts(user_id: uuid.UUID, email: str) -> bool:
+    """Is this sender in the user's address book?
+
+    Someone you have deliberately saved is not someone whose mail should vanish
+    into Junk — so a contact caps the verdict at a banner (see :func:`decide`).
+
+    Reads the contacts plugin's table directly. Cross-plugin, and deliberately
+    forgiving: if that plugin is not installed the table does not exist, which is
+    not an error here, just "no contacts to check". The addresses are stored as
+    the user typed them, so both sides are lower-cased rather than relying on the
+    jsonb containment index.
+    """
+    addr = (email or "").strip().lower()
+    if not addr:
+        return False
+    try:
+        async with _SDK.session(user_id) as s:
+            row = (
+                await s.execute(
+                    text(
+                        "SELECT 1 FROM plg_contacts_contacts "
+                        "WHERE user_id = :u AND ("
+                        "  lower(default_email) = :e "
+                        "  OR EXISTS (SELECT 1 FROM jsonb_array_elements(emails) AS x "
+                        "             WHERE lower(x->>'value') = :e)) "
+                        "LIMIT 1"
+                    ),
+                    {"u": str(user_id), "e": addr},
+                )
+            ).first()
+        return row is not None
+    except Exception:  # noqa: BLE001 - contacts plugin absent, or its schema moved
+        return False
+
+
 def matches(patterns: set[str], email: str) -> bool:
     """A pattern is either a whole address or ``@domain`` for everyone there."""
     addr = (email or "").strip().lower()
@@ -102,12 +137,19 @@ def decide(
     rules: dict[str, set[str]],
     score: float | None,
     settings: Settings,
+    contact: bool = False,
 ) -> str:
     """The §C.4 decision, in order. Returns the verdict action.
 
     Deny beats allow beats engine: an explicit user rule is a statement about a
     sender that no score should override. ``score is None`` means the engine
     could not be reached — fail open, deliver as ``none``.
+
+    ``contact`` (the sender is in the user's address book) caps the outcome at a
+    banner: their mail is never moved to Junk. Not silenced entirely, because the
+    way this goes wrong in practice is a contact's account being compromised and
+    spamming its own address book — the user still deserves the warning. An
+    explicit deny rule still wins: that is the user overruling us on purpose.
     """
     if matches(rules["deny"], sender):
         return "deny_listed"
@@ -116,7 +158,7 @@ def decide(
     if score is None:
         return "none"
     if score >= settings.move_threshold:
-        return "moved"
+        return "banner" if contact else "moved"
     if score >= settings.banner_threshold:
         return "banner"
     return "none"

plugins/webmail_plugin_antispam/webmail_plugin_antispam/router.py

@@ -49,17 +49,23 @@ async def get_settings(user_id: CurrentUserId) -> SettingsOut:
     )
 
 
-@router.patch("/settings", response_model=SettingsOut, dependencies=[Depends(require_csrf)])
+@router.patch(
+    "/settings", response_model=SettingsOut, dependencies=[Depends(require_csrf)]
+)
 async def patch_settings(body: SettingsIn, user_id: CurrentUserId) -> SettingsOut:
     current = await policy.load_settings(user_id)
     merged = {
         "enabled_accounts": (
-            current.enabled_accounts if body.enabled_accounts is None else body.enabled_accounts
+            current.enabled_accounts
+            if body.enabled_accounts is None
+            else body.enabled_accounts
         ),
         "move_threshold": body.move_threshold or current.move_threshold,
         "banner_threshold": body.banner_threshold or current.banner_threshold,
         "network_checks": (
-            current.network_checks if body.network_checks is None else body.network_checks
+            current.network_checks
+            if body.network_checks is None
+            else body.network_checks
         ),
         "learn_from_provider_junk": (
             current.learn_from_provider_junk
@@ -166,7 +172,9 @@ async def delete_rule(rule_id: uuid.UUID, user_id: CurrentUserId) -> dict[str, s
 
 
 @router.get("/verdict/{message_id}", response_model=VerdictOut | None)
-async def get_verdict(message_id: uuid.UUID, user_id: CurrentUserId) -> VerdictOut | None:
+async def get_verdict(
+    message_id: uuid.UUID, user_id: CurrentUserId
+) -> VerdictOut | None:
     """What the banner slot asks before deciding whether to render anything."""
     async with _SDK.session(user_id) as s:
         row = (
@@ -262,5 +270,7 @@ async def stats(user_id: CurrentUserId) -> StatsOut:
 @router.get("/ui/{filename}")
 async def bundle(filename: str) -> FileResponse:
     if filename not in _BUNDLES:
-        raise HTTPException(status_code=404, detail={"code": "not_found", "message": "no bundle"})
+        raise HTTPException(
+            status_code=404, detail={"code": "not_found", "message": "no bundle"}
+        )
     return FileResponse(_UI / filename, media_type="text/javascript")

plugins/webmail_plugin_antispam/webmail_plugin_antispam/rspamd.py

@@ -85,7 +85,9 @@ def _headers(user_key: str, network_checks: bool) -> dict[str, str]:
     }
 
 
-async def check(raw: bytes, *, user_key: str, network_checks: bool = False) -> Verdict | None:
+async def check(
+    raw: bytes, *, user_key: str, network_checks: bool = False
+) -> Verdict | None:
     """Score one raw RFC822 message. ``None`` means "could not classify"."""
     try:
         async with httpx.AsyncClient(timeout=TIMEOUT) as client: