feat: let QA send real email, guarded by a recipient allowlist (#87)

QA has never been able to send mail. The compose file set no SMTP variables and the mailer skips sending when it finds none, which was deliberate — a QA run must not be able to email a real customer if a fixture ever holds a real address. The cost is that four customer-facing flows have never been exercised anywhere but production: verification, password reset, favorite-sold alerts, and the cart-reminder cron that already has a known silent failure mode.

MAIL_ALLOWLIST replaces the blanket mute. Unset means unrestricted, which is production and must stay so. Set means only matching recipients are delivered to; anything else is skipped with a [mail-blocked] warning naming the address and subject. An entry is either a full address, which also covers its plus-suffixed variants, or @domain for every mailbox there — plus-addressing is how these tests get written, and nobody should have to edit an allowlist to invent a new suffix mid-run.

The guard sits in the mailer, not at the four call sites, so every sender is covered by construction and a fifth added later cannot bypass it by forgetting. It skips rather than throws: three callers already swallow send failures into a log, so throwing would mostly be caught anyway while risking a 500 on the signup path. The flow under test finishes and the log says why no mail arrived, which is exactly what was missing when QA was simply muted.

Two details are load-bearing enough to state. Comparison is exact equality on both halves of the address rather than a suffix test, so a lookalike domain ending in an allowed one cannot get through — there is a test for that specifically. And a present-but-empty value refuses everyone rather than allowing everyone: writing MAIL_ALLOWLIST= expresses an intent to restrict, and reading it as "no restriction" would turn a typo into an outbound mail incident.

This inverts the failure mode, so the allowlist is hardcoded in docker-compose.qa.yml rather than read from a stack variable. The safety property must not depend on remembering to set something in Portainer, where an omission would mean unrestricted sending from an environment full of fixtures. The comment says removing the line disables the restriction rather than the mail.

QA points at Brevo, reusing the existing account rather than a separate QA sender — a deliberate choice that puts QA volume behind production's sending reputation and quota, acceptable for now. Host, port and secure are pinned in the compose because the mailer's fallbacks are Gmail's and Brevo needs 587 with STARTTLS; that mismatch fails at send time rather than at boot, which is #64's territory.

Verified: 12 new unit tests on the matching function, which is where a mistake would actually be dangerous — 98 unit and 144 integration passing, lint 0 errors and 8 warnings unchanged, and the compose renders the expected values under docker compose config.

Refs #87
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

docker-compose.qa.yml

@@ -34,6 +34,9 @@
 #                     production stack's variables here does nothing silently.
 #   PUBLIC_URL      — the QA hostname, e.g.
 #                     https://qa-redefined-designs.bermudalamb.synology.me
+#   QA_SMTP_USER    — Brevo SMTP login. Named QA_ for the same reason as the
+#   QA_SMTP_PASSWORD  database password: pasting production's variables in here
+#   QA_SMTP_FROM      must not silently work.
 
 services:
   redefined-designs-qa:
@@ -63,10 +66,35 @@ services:
       # PAYPAL_ENV=sandbox — never the live ones.
       - DEMO_MODE=true
 
-      # No SMTP configuration either. The mailer degrades gracefully when
-      # unconfigured: it logs a warning and skips sending. That is the desired
-      # behaviour here — a QA run must not be able to email real customers if
-      # a fixture ever contains a real address.
+      # SMTP *is* configured here, unlike PayPal above, because the four mail
+      # flows — verification, password reset, favorite-sold alerts and the
+      # cart-reminder cron — cannot be regression tested without it. See #87.
+      #
+      # Host, port and secure are not secrets and are pinned here rather than
+      # inherited: the mailer's fallbacks are Gmail's (smtp.gmail.com, 465,
+      # TLS) and Brevo needs 587 with STARTTLS, which is why SMTP_SECURE is
+      # false. Getting these wrong fails at send time, not at boot.
+      - SMTP_HOST=smtp-relay.brevo.com
+      - SMTP_PORT=587
+      - SMTP_SECURE=false
+      - SMTP_USER=${QA_SMTP_USER}
+      - SMTP_PASSWORD=${QA_SMTP_PASSWORD}
+      - SMTP_FROM=${QA_SMTP_FROM}
+
+      # What keeps a QA run from emailing a real customer now that it *can*
+      # send. Only these recipients are ever delivered to; anything else is
+      # skipped with a [mail-blocked] warning naming the address.
+      #
+      # Hardcoded rather than read from a stack variable, deliberately. This is
+      # the entire safety property, and it must not depend on somebody
+      # remembering to set something in Portainer — an unset variable would
+      # mean unrestricted sending from an environment full of test fixtures.
+      #
+      # An entry covers its plus-suffixed variants, so `+whatever` addresses
+      # work without editing this. Removing the line does NOT disable mail; it
+      # disables the restriction. Production is a separate stack that does not
+      # read this file, which is why it is unrestricted and correct to be.
+      - MAIL_ALLOWLIST=thomlamb@gmail.com
       - SITE_CURRENCY=USD
       - RESERVATION_MINUTES=15
       - PUBLIC_URL=${PUBLIC_URL}