feat(mail): plaintext loopback IMAP so the gateway bypasses Mailu's front

Mailu's front (nginx mail proxy) pre-authenticates against Mailu's user DB before
proxying to Dovecot, which rejects the Dovecot master-user login <addr>*gateway.
The gateway must reach Dovecot directly. The imap container has no TLS cert (only
the front does), so the bypass is plaintext over loopback — the master password
never leaves the host.

- mailbox: IMAPConfig.Plaintext dials with DialInsecure (loopback only).
- main.go: mailClientFor sets Plaintext from AGENTBBS_MAIL_IMAP_PLAINTEXT.
- override.example: add the unbound resolver (admin needs DNSSEC), webmail image
  fix (2024.06 uses mailu/webmail), and publish Dovecot 143 on 127.0.0.1:14143.
- docs/mail.md: document the front-bypass, the dovecot.conf master passdb (Mailu
  includes that exact filename), and the 644 master-users perms (640 = temp_fail).

Co-Authored-By: Claude Opus 4.8 <[email protected]>

Author: ralyodio

cmd/agentbbs/main.go

@@ -1355,6 +1355,11 @@ func (a *app) mailClientFor(su store.User) (*mailbox.Client, error) {
 		SMTPAddr: env("AGENTBBS_MAIL_SMTP_ADDR", "127.0.0.1:25"),
 		Username: login,
 		Password: os.Getenv("AGENTBBS_MAIL_MASTER_PASS"),
+		// Mailu's front nginx pre-authenticates against its user DB before
+		// proxying, which rejects the "<addr>*master" master login. The gateway
+		// therefore talks to Dovecot directly over loopback (plaintext, on-host)
+		// when AGENTBBS_MAIL_IMAP_PLAINTEXT=1. See docs/mail.md.
+		Plaintext: os.Getenv("AGENTBBS_MAIL_IMAP_PLAINTEXT") == "1",
 		// SMTPUser/SMTPPass left empty: submit via the trusted local relay.
 	}
 	tr, err := mailbox.NewIMAPTransport(cfg)

deploy/mailu/docker-compose.override.yml.example

@@ -1,14 +1,36 @@
 # docker-compose.override.yml — copy to docker-compose.override.yml (gitignored).
-#
-# The base docker-compose.yml does not declare a network, so Docker would assign
-# the project's default bridge an arbitrary subnet. Mailu trusts SUBNET (from
-# mailu.env) as its internal network for service-to-service auth and relaying, so
-# the real network subnet MUST equal SUBNET or internal auth/relay breaks. This
-# override pins the default network to the same subnet you set as SUBNET in
-# mailu.env (default 192.168.203.0/24). Compose loads this file automatically.
+# Compose loads this file automatically. It carries three fixes the trimmed base
+# compose needs; see docs/mail.md for the full rationale.
 networks:
   default:
     driver: bridge
     ipam:
       config:
+        # Mailu trusts SUBNET (mailu.env) as its internal network for
+        # service-to-service auth/relay; the real network MUST match it.
         - subnet: 192.168.203.0/24
+services:
+  # Mailu requires a DNSSEC-validating resolver or admin won't start.
+  resolver:
+    image: ghcr.io/mailu/unbound:2024.06
+    env_file: mailu.env
+    restart: always
+    networks:
+      default:
+        ipv4_address: 192.168.203.254
+  front:    { dns: [192.168.203.254], depends_on: [resolver] }
+  admin:    { dns: [192.168.203.254], depends_on: [resolver] }
+  imap:
+    dns: [192.168.203.254]
+    depends_on: [resolver]
+    # Publish Dovecot directly on loopback so the agentbbs gateway can use the
+    # master-user login (the front's nginx auth proxy rejects "<addr>*master").
+    # Plaintext is fine: the connection never leaves the host.
+    ports: ["127.0.0.1:14143:143"]
+  smtp:     { dns: [192.168.203.254], depends_on: [resolver] }
+  antispam: { dns: [192.168.203.254], depends_on: [resolver] }
+  # In Mailu 2024.06 the webmail image is "webmail" (not "roundcube:2024.06").
+  webmail:
+    image: ghcr.io/mailu/webmail:2024.06
+    dns: [192.168.203.254]
+    depends_on: [resolver]

docs/mail.md

@@ -90,7 +90,8 @@ Set these on the agentbbs service (setup.sh §9e upserts the non-secret ones):
 |---|---|
 | `AGENTBBS_MAIL_ADDR_DOMAIN` | `bbs.profullstack.com` |
 | `AGENTBBS_MAIL_DOMAIN` | `mail.profullstack.com` |
-| `AGENTBBS_MAIL_IMAP_ADDR` | `mail.profullstack.com:993` |
+| `AGENTBBS_MAIL_IMAP_ADDR` | `127.0.0.1:14143` (Dovecot direct, loopback) |
+| `AGENTBBS_MAIL_IMAP_PLAINTEXT` | `1` (the loopback path is plaintext) |
 | `AGENTBBS_MAIL_SMTP_ADDR` | `127.0.0.1:25` |
 | `AGENTBBS_MAIL_ADMIN_URL` | `http://127.0.0.1:8080` |
 | `AGENTBBS_MAIL_API_TOKEN` | the Mailu `API_TOKEN` (secret) |
@@ -102,6 +103,33 @@ Without `AGENTBBS_MAIL_API_TOKEN` auto-provisioning is skipped (the address is
 still shown); without `AGENTBBS_MAIL_MASTER_PASS` the gateway can't open
 mailboxes.
 
+### Why the gateway talks to Dovecot directly (plaintext loopback)
+
+Mailu's **front** (nginx mail proxy) pre-authenticates every IMAP/SMTP login
+against Mailu's user DB before proxying to Dovecot — and it rejects the Dovecot
+master-user login form `<addr>*gateway`. So the gateway must reach **Dovecot
+directly**, bypassing the front. The `imap` container has no TLS cert (only the
+front does), so the bypass is plaintext over loopback — safe because the
+connection (and the master password) never leave the host. Wiring:
+
+- Publish Dovecot's IMAP on loopback (docker-compose.override.yml):
+  `imap.ports: ["127.0.0.1:14143:143"]`.
+- The Dovecot master user is defined in `data/overrides/dovecot/dovecot.conf`
+  (Mailu includes exactly that filename — *not* `*.conf`):
+
+  ```
+  auth_master_user_separator = *
+  passdb { driver = passwd-file; master = yes; args = /overrides/master-users }
+  ```
+
+  with `data/overrides/dovecot/master-users` holding `gateway:{SHA512-CRYPT}$6$…`
+  (the hash of `AGENTBBS_MAIL_MASTER_PASS`). The file must be **world-readable
+  (644)** — Dovecot reads it as a non-root user, and 640 root:root yields a
+  `temp_fail`. Do **not** add `result_success = continue` (that would also
+  require the target user's own password); the target mailbox comes from userdb.
+- Point the gateway at it: `AGENTBBS_MAIL_IMAP_ADDR=127.0.0.1:14143` +
+  `AGENTBBS_MAIL_IMAP_PLAINTEXT=1`.
+
 ## Sending mail from the BBS (verify codes + notifications)
 
 The join@ verification code and signup notifications use `internal/mail` (the

internal/mailbox/imap.go

@@ -24,6 +24,11 @@ type IMAPConfig struct {
 	// SMTPUser/SMTPPass default to Username/Password when empty.
 	SMTPUser string
 	SMTPPass string
+	// Plaintext dials IMAP without TLS. Used only for a co-located backend over
+	// loopback (the Mailu gateway hitting Dovecot directly on 127.0.0.1, bypassing
+	// the front's auth proxy so master-user login works) — the password never
+	// leaves the host. Never enable it for a remote server.
+	Plaintext bool
 }
 
 // imapTransport is a Transport backed by a single authenticated IMAP connection
@@ -38,7 +43,11 @@ type imapTransport struct {
 
 // NewIMAPTransport dials the IMAP server, logs in, and returns a Transport.
 func NewIMAPTransport(cfg IMAPConfig) (Transport, error) {
-	c, err := imapclient.DialTLS(cfg.IMAPAddr, nil)
+	dial := imapclient.DialTLS
+	if cfg.Plaintext {
+		dial = imapclient.DialInsecure
+	}
+	c, err := dial(cfg.IMAPAddr, nil)
 	if err != nil {
 		return nil, fmt.Errorf("imap dial %s: %w", cfg.IMAPAddr, err)
 	}