From b4ce6c10b55b747bec9af0417e49a14a8e6f7696 Mon Sep 17 00:00:00 2001 From: kisfenyo Date: Mon, 29 Jun 2026 10:32:56 +0200 Subject: [PATCH] =?UTF-8?q?docs:=20FINDING=20=E2=80=94=20app-email=20rollo?= =?UTF-8?q?ut=20mechanism=20gaps=20(calcom/nextcloud/immich)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.8 (1M context) --- .../FINDING-app-email-rollout-2026-06-29.md | 105 ++++++++++++++++++ 1 file changed, 105 insertions(+) create mode 100644 documentation/audits/FINDING-app-email-rollout-2026-06-29.md diff --git a/documentation/audits/FINDING-app-email-rollout-2026-06-29.md b/documentation/audits/FINDING-app-email-rollout-2026-06-29.md new file mode 100644 index 0000000..e2fb50e --- /dev/null +++ b/documentation/audits/FINDING-app-email-rollout-2026-06-29.md @@ -0,0 +1,105 @@ +# FINDING — app-email rollout: 3 apps reveal relay mechanism gaps + +**Date:** 2026-06-29 +**Context:** Rolling out the shipped app-email relay (controller v0.88.0 in-process shim + `smtp_mapping` +injection; hub v0.18.0 passthrough) to calcom, rallly, gitea, nextcloud (+ investigate immich). Per the task's +rule 4, an app that needs an injection feature the mechanism can't provide is **reported here, not hacked +around in the catalog**. + +**Outcome:** **gitea** and **rallly** wired cleanly (STARTTLS, both trust/accept the shim's self-signed cert). +**cal.com**, **nextcloud**, and **immich** each hit a real gap and are **left unwired** pending a mechanism +decision. The gaps cluster into three categories below. + +--- + +## The shipped mechanism (recap) + +The on-box shim offers `:2525` plaintext **with STARTTLS advertised** (self-signed cert) and `:2465` implicit +TLS (self-signed). The `smtp_mapping` injects, per app, a set of env vars: a single host/port/security-mode/ +**single From address**/optional name + fixed `extra` vars. Two app shapes work today: +- **Vaultwarden shape** — STARTTLS + an app flag to *accept the self-signed cert* (`SMTP_ACCEPT_INVALID_CERTS`). +- **Mealie shape** — plaintext, and the app's client does **not** opportunistically upgrade to STARTTLS. + +The gaps below are all cases that fit neither shape. + +--- + +## Gap 1 — Self-signed STARTTLS vs opportunistic-upgrade clients with no skip-verify + +**Affects: cal.com (hard), nextcloud (TLS half).** + +Nodemailer (cal.com, rallly) and Symfony Mailer (nextcloud) **opportunistically issue STARTTLS** whenever the +server advertises it — which our `:2525` listener always does — and then **validate the cert**. If the app has +no "accept invalid cert / reject-unauthorized=false" knob, the TLS handshake fails on the self-signed cert and +the send errors out (these clients do **not** fall back to plaintext). Mealie avoided this only because its +client never attempts STARTTLS. + +- **cal.com v4.8.7** — transport hard-codes `tls: { rejectUnauthorized: !isENVDev }`; in the production image + `NODE_ENV=production` ⇒ `rejectUnauthorized: true`, with **no env override** (and `NODE_TLS_REJECT_UNAUTHORIZED` + does not help — an explicit per-transport TLS option wins). `secure` is true only for port 465, so every other + port plaintext-connects then opportunistically STARTTLS-upgrades → self-signed failure; 2465 implicit-TLS also + fails the same cert check. **No env-only path exists.** + Source: `packages/lib/serverConfig.ts` @ v4.8.7. +- **nextcloud 31** — the official image's `smtp.config.php` exposes **no** `mail_smtpstreamoptions` / + `verify_peer=false`, so `SMTP_SECURE=tls|ssl` fail the self-signed cert with no override. `SMTP_SECURE=''` + (none) avoids *configured* TLS, but NC31's Symfony mailer may still auto-STARTTLS when the shim advertises it. + +**Fix options (controller mechanism — out of scope for the catalog):** +1. **A plaintext-only listener that does NOT advertise STARTTLS** (e.g. `:2526`), selectable per app via the + mapping (a `tls_mode: plain-only` hint). Opportunistic-upgrade clients then never try TLS → send succeeds. + Lowest-effort, highest-coverage fix. +2. **Issue the shim a cert from an internal CA and distribute that CA** into app trust stores. Heavier + (per-image trust injection), but lets apps use real STARTTLS without a skip flag. + +Recommendation: **option 1** (a non-advertising plaintext listener) — it directly unblocks cal.com and the +nextcloud TLS half, and is a small, contained shim change. + +## Gap 2 — Split From address (local-part + domain in separate env vars) + +**Affects: nextcloud.** + +The `smtp_mapping` `from_var` injects a **single** `@` value. Nextcloud's official image splits +the sender into **`MAIL_FROM_ADDRESS`** (local-part, e.g. `nextcloud`) **+ `MAIL_DOMAIN`** (`felhom.eu`). There +is no single From env var to target. (Hacking it via `extra` overriding `from_var` by append-order is fragile +and misleading — explicitly avoided.) + +**Fix (controller mechanism):** add an optional `from_domain_var` (+ keep `from_local`) so a mapping can set the +local-part and domain to two separate env keys. Small, additive change to `SMTPMapping` + the injector. + +## Gap 3 — No SMTP env vars at all (config-file / DB / admin-UI only) + +**Affects: immich.** + +immich v2.5.5 has **no SMTP environment variables**. Email is system config (Administration → Settings → +Notifications), stored in the DB, OR supplied via a JSON file pointed to by **`IMMICH_CONFIG_FILE`**: +```json +{ "notifications": { "smtp": { "enabled": true, "from": "immich@felhom.eu", + "transport": { "host": "felhom-controller", "port": 2525, "secure": false, "ignoreCert": true } } } } +``` +Note `ignoreCert: true` — immich *can* accept the self-signed shim cert, so the only blocker is the +**delivery mechanism**: env injection can't express this; the controller would need to **render + mount a +config file** (a new, larger capability) or the customer configures SMTP once in the admin UI. + +**Fix (separate, larger piece):** a "config-file injection for DB/file-configured apps" mechanism (render an +app-specific config file from catalog metadata + the relay settings, mount it, set the pointer env). immich, +and likely other DB-configured apps, would ride it. Until then immich is **manual admin-UI setup**. + +--- + +## Wired now (this rollout) + +| App | Shape | Self-signed handling | From | Env consumed | +|-----|-------|----------------------|------|--------------| +| **gitea 1.23.4** | STARTTLS (`smtp+starttls`) | `FORCE_TRUST_SERVER_CERT=true` | single `GITEA__mailer__FROM` | every boot | +| **rallly 3.11.2** | STARTTLS (`SMTP_SECURE=false`) | `SMTP_REJECT_UNAUTHORIZED=false` (v4) / default-off (v3) | single `NOREPLY_EMAIL` | every start | + +> **Side-finding (fixed):** the rallly template pinned `lukevella/rallly:3.12.1`, which **does not exist** (the +> 3.x line stops at 3.11.x; current is 4.x) — the template was undeployable. Corrected to `3.11.2` (nearest +> valid 3.x) so it deploys + can be email-tested. A later bump to 4.x is a separate decision (4.x renames the +> cert flag to `SMTP_REJECT_UNAUTHORIZED`, already in the mapping). + +## Remaining email-capable apps still unwired (future passes) + +ghost, outline, grafana, docmost, bookstack, n8n, paperless-ngx, gitea-actions notifications, … — each needs the +same per-app determination (env names + self-signed/opportunistic-TLS behavior + single/split From). Apps that +opportunistically STARTTLS without a skip flag will need **Gap-1 option 1** first.