feat(2): Q4.9 mailu — recipe_meta + health + 3 functional (create-mailbox/imap-login/mail-flow); P4 N/A deferred

mailu (full email stack). TLS_FLAVOR=notls avoids certdumper/ACME dep (cc-ci file-provider cert);
MAIL_DOMAIN/HOSTNAMES=run domain; TRAEFIK_STACK_NAME for the letsencrypt-volume mount. P2 vacuous (no
corpus). P3: test_mailbox (flask mailu user create + config-export read-back), test_imap_login
(mailbox authenticates over dovecot IMAP:143), test_mail_flow (SMTP submission send → IMAP retrieve,
auth to avoid greylisting). P4 N/A (no backupbot label) — DEFERRED.md + PARITY.md, Adversary §7.1
sign-off pending. Smoke-validated: 8 services converge, mail ports 25/587/143/993 host-open, flask CLI.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

tests/mailu/functional/_mailu.py

@@ -0,0 +1,45 @@
+"""Shared mailu helpers — headless mailbox provisioning via the admin container's `flask mailu` CLI.
+
+mailu's admin container ships the management CLI (`flask mailu domain|user|alias|config-export ...`),
+the canonical headless way to provision mail objects. We exec it via the harness (service="admin").
+The primary MAIL_DOMAIN is auto-created at boot; `flask mailu domain ... || true` is idempotent.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "..", "..", "runner"))
+from harness import lifecycle  # noqa: E402
+
+
+def flask_mailu(domain: str, shell_cmd: str) -> str:
+    """Run a `flask mailu ...` shell command in the admin container; return stdout."""
+    return lifecycle.exec_in_app(domain, ["sh", "-c", shell_cmd], service="admin")
+
+
+def ensure_domain(domain: str, mail_domain: str) -> None:
+    # idempotent: the primary domain is auto-created; tolerate "already exists"
+    flask_mailu(domain, f"flask mailu domain {mail_domain} || true")
+
+
+def create_user(domain: str, local: str, mail_domain: str, password: str) -> str:
+    email = f"{local}@{mail_domain}"
+    flask_mailu(domain, f"flask mailu user {local} {mail_domain} '{password}'")
+    return email
+
+
+def config_export(domain: str) -> dict:
+    """`flask mailu config-export --json` → parsed dict (keys: domain/user/alias/relay)."""
+    out = flask_mailu(domain, "flask mailu config-export --json")
+    # Be robust to any leading banner: extract the JSON object.
+    start = out.find("{")
+    end = out.rfind("}")
+    assert start != -1 and end != -1, f"config-export produced no JSON: {out[:200]!r}"
+    return json.loads(out[start : end + 1])
+
+
+def user_emails(cfg: dict) -> list[str]:
+    return [u.get("email") for u in cfg.get("user", [])]

tests/mailu/functional/test_health_check.py

@@ -0,0 +1,21 @@
+"""mailu — health/readiness functional test (Phase 2).
+
+SOURCE: no recipe-maintainer corpus exists for mailu (P2 vacuous — see PARITY.md). The nginx front
+serves `/` (301 → /webmail) once the stack is up; this is the canonical "is mailu serving" signal.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "..", "..", "runner"))
+from harness import http as harness_http  # noqa: E402
+
+
+def test_mailu_front_serves(live_app):
+    url = f"https://{live_app}/"
+    status, _ = harness_http.retry_http_get(
+        url, expect_status=(200, 301, 302), max_wait=120, interval=5
+    )
+    assert status in (200, 301, 302), f"GET {url} HTTP {status} (mailu front not serving)"

tests/mailu/functional/test_imap_login.py

@@ -0,0 +1,49 @@
+"""mailu — recipe-specific functional test #2 (Phase 2 P3, distinctive: working IMAP mailbox).
+
+Beyond "the row exists in config" (test_mailbox), this proves the provisioned mailbox is a REAL,
+usable IMAP account: it authenticates against dovecot over IMAP (port 143, host-published) and can
+SELECT its INBOX. That exercises mailu's actual mail-account stack (admin provisioning → dovecot auth
+backend), not just the admin DB. notls deploy → plain IMAP on 143. Hard assertion, non-vacuous: wrong
+credentials / a non-working account fail the login.
+"""
+
+from __future__ import annotations
+
+import imaplib
+import os
+import sys
+import time
+import uuid
+
+sys.path.insert(0, os.path.dirname(__file__))
+import _mailu  # noqa: E402
+
+
+def test_created_mailbox_authenticates_over_imap(live_app):
+    mail_domain = live_app
+    local = "ccci-imap-" + uuid.uuid4().hex[:8]
+    password = "CcCi-" + uuid.uuid4().hex[:16] + "-Aa1!"
+    _mailu.ensure_domain(live_app, mail_domain)
+    email = _mailu.create_user(live_app, local, mail_domain, password)
+
+    # The account may take a moment to be usable by dovecot after admin provisioning; retry login.
+    deadline = time.time() + 90
+    last_err = None
+    while time.time() < deadline:
+        try:
+            imap = imaplib.IMAP4("127.0.0.1", 143)
+            try:
+                imap.login(email, password)
+                typ, _ = imap.select("INBOX")
+                assert typ == "OK", f"IMAP SELECT INBOX returned {typ} for {email}"
+                imap.logout()
+                return  # authenticated + selected INBOX → working mailbox
+            finally:
+                try:
+                    imap.shutdown()
+                except Exception:  # noqa: BLE001
+                    pass
+        except (imaplib.IMAP4.error, OSError) as e:  # noqa: PERF203
+            last_err = e
+            time.sleep(5)
+    raise AssertionError(f"created mailbox {email} could not authenticate over IMAP:143 — {last_err}")

tests/mailu/functional/test_mail_flow.py

@@ -0,0 +1,100 @@
+"""mailu — recipe-specific functional test #3 (Phase 2 P3, the characteristic end-to-end mail flow).
+
+Provision a mailbox, SEND a uniquely-marked message to it over SMTP, then RETRIEVE it over IMAP and
+assert the marker arrived. This is mailu's defining behaviour (it is a mail server): a full
+deliver→store→fetch round-trip across postfix + rspamd + dovecot — not an API/health stand-in.
+
+To avoid rspamd greylisting (which defers an unknown inbound sender's first attempt for minutes), we
+send via AUTHENTICATED submission as the user itself (authenticated mail is not greylisted). notls
+deploy → submission accepts AUTH on 587; we try 587 (STARTTLS-if-offered) then fall back to 25.
+Retrieval polls INBOX (and Junk, in case rspamd files it) for the marker.
+"""
+
+from __future__ import annotations
+
+import email.message
+import imaplib
+import os
+import smtplib
+import sys
+import time
+import uuid
+
+sys.path.insert(0, os.path.dirname(__file__))
+import _mailu  # noqa: E402
+
+
+def _send(addr_from: str, addr_to: str, password: str, marker: str) -> None:
+    msg = email.message.EmailMessage()
+    msg["From"] = addr_from
+    msg["To"] = addr_to
+    msg["Subject"] = marker
+    msg.set_content(f"cc-ci mail-flow test body {marker}")
+
+    last = None
+    # Authenticated submission on 587 (no greylist); fall back to plain 25 local delivery.
+    for port in (587, 25):
+        try:
+            smtp = smtplib.SMTP("127.0.0.1", port, timeout=30)
+            try:
+                smtp.ehlo()
+                if smtp.has_extn("starttls"):
+                    smtp.starttls()
+                    smtp.ehlo()
+                if smtp.has_extn("auth"):
+                    try:
+                        smtp.login(addr_from, password)
+                    except smtplib.SMTPException as e:  # noqa: PERF203
+                        last = e  # 25 may not offer/allow AUTH; local delivery still works
+                smtp.send_message(msg)
+                return
+            finally:
+                try:
+                    smtp.quit()
+                except Exception:  # noqa: BLE001
+                    pass
+        except (smtplib.SMTPException, OSError) as e:
+            last = e
+    raise AssertionError(f"could not send mail via SMTP 587/25: {last}")
+
+
+def _retrieve(email_addr: str, password: str, marker: str, timeout: int = 150) -> bool:
+    deadline = time.time() + timeout
+    while time.time() < deadline:
+        try:
+            imap = imaplib.IMAP4("127.0.0.1", 143)
+            try:
+                imap.login(email_addr, password)
+                for box in ("INBOX", "Junk"):
+                    typ, _ = imap.select(box)
+                    if typ != "OK":
+                        continue
+                    typ, data = imap.search(None, "SUBJECT", f'"{marker}"')
+                    if typ == "OK" and data and data[0].split():
+                        return True
+                imap.logout()
+            finally:
+                try:
+                    imap.shutdown()
+                except Exception:  # noqa: BLE001
+                    pass
+        except (imaplib.IMAP4.error, OSError):  # noqa: PERF203
+            pass
+        time.sleep(5)
+    return False
+
+
+def test_send_and_receive_mail(live_app):
+    mail_domain = live_app
+    local = "ccci-flow-" + uuid.uuid4().hex[:8]
+    password = "CcCi-" + uuid.uuid4().hex[:16] + "-Aa1!"
+    _mailu.ensure_domain(live_app, mail_domain)
+    email_addr = _mailu.create_user(live_app, local, mail_domain, password)
+
+    marker = "ccci-mailflow-" + uuid.uuid4().hex
+    _send(email_addr, email_addr, password, marker)
+
+    assert _retrieve(email_addr, password, marker), (
+        f"mail with marker {marker!r} was sent to {email_addr} but never arrived in INBOX/Junk "
+        f"over IMAP within the delivery window (postfix→rspamd→dovecot)"
+    )

tests/mailu/functional/test_mailbox.py

@@ -0,0 +1,29 @@
+"""mailu — recipe-specific functional test #1 (Phase 2 P3 §4.3 create-an-object + read-back).
+
+Create a mailbox (the characteristic mailu object) via the admin CLI, then read it back from the
+authoritative config export and assert it is present. Real create→persist→read-back, not health-only.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import uuid
+
+sys.path.insert(0, os.path.dirname(__file__))
+import _mailu  # noqa: E402
+
+
+def test_create_mailbox_and_read_back(live_app):
+    mail_domain = live_app  # recipe_meta sets MAIL_DOMAIN = the per-run domain
+    local = "ccci-" + uuid.uuid4().hex[:8]
+    password = "CcCi-" + uuid.uuid4().hex[:16] + "-Aa1!"
+
+    _mailu.ensure_domain(live_app, mail_domain)
+    email = _mailu.create_user(live_app, local, mail_domain, password)
+
+    cfg = _mailu.config_export(live_app)
+    emails = _mailu.user_emails(cfg)
+    assert email in emails, (
+        f"created mailbox {email} not present in mailu config-export users {emails}"
+    )