Design mailboxes as records, not as one more secret
The console offers a single mail.password pointing at one SMTP mailbox, which is nowhere near enough for five sending addresses. A mailbox is address, display name, username and password; five of them as registry entries would be twenty secrets named mail.support.username, and the question of which mail sends from which address would still have no home. Send-only stays usable because every message carries Reply-To on its own mailbox, so a customer's reply lands in a mailbox someone reads. That is what makes IMAP unnecessary rather than merely deferred. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>feat/mailboxes
nexxo
parent
edaceb9597
commit
743ba96d13
|
|
@ -0,0 +1,246 @@
|
||||||
|
# Spec — Postfächer und Absender
|
||||||
|
|
||||||
|
**Datum:** 2026-07-27
|
||||||
|
**Status:** entworfen, noch nicht umgesetzt
|
||||||
|
**Umfang:** **nur senden.** Empfangen (IMAP, Zuordnung eingehender Antworten) ist
|
||||||
|
ausdrücklich nicht Teil davon — siehe §10.
|
||||||
|
**Verwandt:** `docs/superpowers/specs/2026-07-27-operator-identity-design.md`
|
||||||
|
(eigenes Vorhaben, keine Abhängigkeit in beide Richtungen)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Ziel
|
||||||
|
|
||||||
|
CluPilot verschickt aus mehreren Adressen — `no-reply`, `office`, `support`,
|
||||||
|
`info`, `billing`. Heute gibt es dafür **eine** Stelle: das Geheimnis
|
||||||
|
`mail.password` in der Zugangsdaten-Registry, das auf
|
||||||
|
`mail.mailers.smtp.password` zeigt. Ein einziges Passwort für einen einzigen
|
||||||
|
Absender.
|
||||||
|
|
||||||
|
Das Vorhaben gibt jedem Postfach einen eigenen Datensatz, macht in der Konsole
|
||||||
|
einstellbar, welche Mail aus welchem Postfach geht, und stellt sicher, dass eine
|
||||||
|
Antwort des Kunden dort ankommt, wo sie jemand liest.
|
||||||
|
|
||||||
|
### Warum das nicht in die Registry passt
|
||||||
|
|
||||||
|
`SecretVault::REGISTRY` bildet **einen Schlüssel auf einen Config-Pfad** ab. Ein
|
||||||
|
Postfach ist Adresse, Anzeigename, Benutzer und Passwort. Fünf Postfächer als
|
||||||
|
Registry-Einträge wären zwanzig Einzelgeheimnisse mit Namen wie
|
||||||
|
`mail.support.username` — die Seite wäre voll und trotzdem unbedienbar, und die
|
||||||
|
Zuordnung „welche Mail aus welchem Postfach" hätte immer noch keinen Ort.
|
||||||
|
|
||||||
|
### Geerbte Regeln
|
||||||
|
|
||||||
|
`SecretVault` hat drei ausformulierte Regeln. Sie gelten hier unverändert:
|
||||||
|
|
||||||
|
1. **Kuratiert, nie beliebig.** Die Liste der *Zwecke* ist fest; die Postfächer
|
||||||
|
sind Daten, aber ihre Form ist es nicht.
|
||||||
|
2. **Eigener Schlüssel.** Postfach-Passwörter werden mit `SECRETS_KEY`
|
||||||
|
verschlüsselt, **nicht** mit `APP_KEY`. Ein APP_KEY-Wechsel ist gewöhnliche
|
||||||
|
Wartung und darf den Mailversand nicht unbrauchbar machen.
|
||||||
|
3. **Beim Benutzen lesen, nie beim Booten überlagern.** Ein Overlay kostet auf
|
||||||
|
jeder Anfrage eine Abfrage und lässt langlaufende Queue-Worker für immer das
|
||||||
|
halten, was beim Start galt.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Ausgangsbefund
|
||||||
|
|
||||||
|
| Befund | Beleg |
|
||||||
|
|---|---|
|
||||||
|
| Genau **ein** Mail-Geheimnis | `SecretVault::REGISTRY` → `mail.password` → `mail.mailers.smtp.password` |
|
||||||
|
| Ein Server, ein Postfach | `.env`: `MAIL_HOST=mail.thinkidoo.com`, `MAIL_PORT=587`, `MAIL_SCHEME=tls`, `MAIL_USERNAME=no-reply@clupilot.com` |
|
||||||
|
| Es wird derzeit **nicht** verschickt | `MAIL_MAILER=log` |
|
||||||
|
| Absender-Vorgabe zeigt ins Leere | `MAIL_FROM_ADDRESS=hello@clupilot.local` — diese Adresse existiert nicht |
|
||||||
|
| Drei Mails vorhanden, keine setzt `from` | `MaintenanceAnnouncementMail`, `MaintenanceCancelledMail`, `CloudReady` — alle nehmen den globalen Absender |
|
||||||
|
| Alle Postfächer auf einem Server | entschieden 2026-07-27 |
|
||||||
|
|
||||||
|
> **Nebenbefund:** Das SMTP-Passwort steht im Klartext in `.env`. Das ist bei
|
||||||
|
> Laravel normal und `.env` ist gitignored — aber sobald es im Vault liegt,
|
||||||
|
> gehört es dort weg, und ein Wechsel bei der Gelegenheit ist billig.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Datenform
|
||||||
|
|
||||||
|
### Server — einmal, in den Einstellungen
|
||||||
|
|
||||||
|
`mail.host`, `mail.port`, `mail.encryption` über `App\Support\Settings`. Ein
|
||||||
|
Server, eine Stelle. Wenn sich der Anbieter ändert, ändert sich **eine** Karte,
|
||||||
|
nicht fünf Datensätze.
|
||||||
|
|
||||||
|
### Tabelle `mailboxes`
|
||||||
|
|
||||||
|
| Spalte | Zweck |
|
||||||
|
|---|---|
|
||||||
|
| `id`, `uuid` | Schlüssel; `uuid` für URLs |
|
||||||
|
| `key` (unique) | `no-reply`, `office`, `support`, `info`, `billing` — der Name, unter dem ein Zweck darauf zeigt |
|
||||||
|
| `address` | die Absenderadresse |
|
||||||
|
| `display_name` | „CluPilot Support" |
|
||||||
|
| `username` | SMTP-Benutzer; leer = `address` |
|
||||||
|
| `password` | verschlüsselt mit `SECRETS_KEY` |
|
||||||
|
| `no_reply` (bool) | unterdrückt `Reply-To`, siehe §5 |
|
||||||
|
| `active` (bool) | ein Postfach abschalten, ohne es zu löschen |
|
||||||
|
| `last_verified_at` | wann der Testversand zuletzt geklappt hat |
|
||||||
|
| `timestamps` | |
|
||||||
|
|
||||||
|
`key` ist frei wählbar — die fünf sind Startwerte, keine Schranke. Was **nicht**
|
||||||
|
frei ist, ist die Liste der Zwecke.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Zuordnung: welche Mail aus welchem Postfach
|
||||||
|
|
||||||
|
Eine kuratierte Liste von Zwecken, je Zweck ein Postfach:
|
||||||
|
|
||||||
|
| Zweck | Was daraus geht | Vorgabe |
|
||||||
|
|---|---|---|
|
||||||
|
| `maintenance` | Wartung angekündigt / abgesagt | `no-reply` |
|
||||||
|
| `provisioning` | Cloud bereit, Bestellbestätigung | `no-reply` |
|
||||||
|
| `support` | Antworten auf Support-Anfragen | `support` |
|
||||||
|
| `billing` | Rechnungen, Zahlungserinnerungen | `billing` |
|
||||||
|
| `system` | alles ohne eigenen Zweck | `no-reply` |
|
||||||
|
|
||||||
|
- Einstellbar in der Konsole, ein Auswahlfeld je Zeile.
|
||||||
|
- **`system` ist der Rückfall**, und zwar per Definition statt per Schalter: ein
|
||||||
|
Zweck ohne belegtes Postfach benutzt das Postfach von `system`. Damit gibt es
|
||||||
|
kein zweites Feld „welches ist das Standardpostfach", das der Zuordnung
|
||||||
|
widersprechen könnte — der Rückfall *ist* eine Zeile der Zuordnungstabelle und
|
||||||
|
wird dort gepflegt wie jede andere.
|
||||||
|
- `system` selbst darf nicht leer bleiben: die Konsole verweigert das Speichern
|
||||||
|
mit leerem `system`-Postfach, denn das ist der eine Fall, für den es keinen
|
||||||
|
Rückfall mehr gibt.
|
||||||
|
- **Die Zweckliste ist Code, nicht Daten.** Ein Zweck ohne Absender wäre sonst
|
||||||
|
nur zur Laufzeit zu bemerken — an einer Mail, die nicht ankam.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. `Reply-To` — das, was Nur-Senden brauchbar macht
|
||||||
|
|
||||||
|
Jede Mail bekommt `From` **und** `Reply-To` auf die Adresse ihres Postfachs.
|
||||||
|
|
||||||
|
Ohne das wäre „nur senden" eine Sackgasse: der Kunde antwortet auf eine
|
||||||
|
Support-Antwort und die Antwort verschwindet. Mit `Reply-To` landet sie im
|
||||||
|
echten `support@`-Postfach, das im gewöhnlichen Mailprogramm gelesen wird — das
|
||||||
|
ist der Grund, warum Empfangen (IMAP) hier **nicht** gebraucht wird.
|
||||||
|
|
||||||
|
**Ausnahme:** Postfächer mit `no_reply = true` bekommen **kein** `Reply-To`.
|
||||||
|
Ein „no-reply", auf das man antworten kann, ist eine Lüge im Absender.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. Versand zur Laufzeit
|
||||||
|
|
||||||
|
- `App\Services\Mail\MailboxResolver` löst *Zweck → Postfach* auf und baut den
|
||||||
|
Symfony-Transport **beim Versenden**. Nichts wird beim Booten in die Config
|
||||||
|
geschrieben (Regel 3).
|
||||||
|
- Die drei vorhandenen Mailables bekommen ihren Zweck: `MaintenanceAnnouncementMail`
|
||||||
|
und `MaintenanceCancelledMail` → `maintenance`, `CloudReady` → `provisioning`.
|
||||||
|
- **Auf dev wird weiterhin nur protokolliert.** `MAIL_MAILER=log` bleibt für
|
||||||
|
gewöhnliche Mails wirksam, damit ein Seeder-Lauf oder ein Test mit echten
|
||||||
|
Adressen niemandem eine Wartungsankündigung schickt. Entschieden 2026-07-27.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 7. Testversand, der wirklich sendet
|
||||||
|
|
||||||
|
Pro Postfach ein Knopf: echte SMTP-Verbindung mit **diesen** Zugangsdaten, an
|
||||||
|
eine eingetippte Adresse.
|
||||||
|
|
||||||
|
- **Er geht am `MAIL_MAILER=log` vorbei.** Täte er das nicht, meldete er auf dev
|
||||||
|
Erfolg, während er in eine Logdatei schreibt — ein Test, der die
|
||||||
|
Implementierung nachrechnet statt sie zu prüfen. Genau der Fehler aus
|
||||||
|
Handoff §2.2, nur an anderer Stelle.
|
||||||
|
- Die Oberfläche sagt, dass wirklich verschickt wird.
|
||||||
|
- Schlägt es fehl, steht der SMTP-Fehler **wörtlich** da — nicht „Fehler beim
|
||||||
|
Senden". Bei falschen Zugangsdaten ist der Serversatz die ganze Diagnose.
|
||||||
|
- Erfolg setzt `last_verified_at`; die Liste zeigt „zuletzt bestätigt".
|
||||||
|
|
||||||
|
> Damit ist die Testknopf-Bedingung der Registry erfüllt: es gibt einen echten
|
||||||
|
> Test, also ist der Knopf gerechtfertigt. Ein Knopf, der still etwas anderes
|
||||||
|
> prüft, wäre schlechter als keiner.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 8. Konsole
|
||||||
|
|
||||||
|
- Eigene Seite `admin.mail`, Navigationsgruppe **System** neben Zugangsdaten,
|
||||||
|
eingetragen in `app/Support/Navigation.php` — der **einen** Quelle.
|
||||||
|
- Neue Berechtigung **`mail.manage`**, nicht `secrets.manage`: wer den
|
||||||
|
Support-Absender pflegt, braucht keinen Zugriff auf Stripe- und DNS-Schlüssel.
|
||||||
|
Rollen: `Owner`, `Admin` bekommen sie; `Support` ebenfalls.
|
||||||
|
- Aufbau: Server-Karte oben, Postfachliste darunter, Zuordnungstabelle zuletzt.
|
||||||
|
- **Bearbeiten im Modal (R20).** Die Zuordnungstabelle ist ein einzelnes
|
||||||
|
Auswahlfeld je Zeile — R20s ausdrückliche Ausnahme, kein Modal.
|
||||||
|
- Passwörter werden nie wieder angezeigt, gleiche Formulierung wie bei den
|
||||||
|
Zugangsdaten („Wird verschlüsselt gespeichert und nie wieder vollständig
|
||||||
|
angezeigt.").
|
||||||
|
- Alle Zeiten über `->local()` (R19), Icons neben dem Text (R18).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 9. Übernahme
|
||||||
|
|
||||||
|
1. Die fünf Postfächer werden als Zeilen angelegt — leer, aber sichtbar, damit
|
||||||
|
die Seite zeigt, was erwartet wird.
|
||||||
|
2. Die vorhandenen `MAIL_*` aus `.env` füllen die Server-Karte und das
|
||||||
|
`no-reply`-Postfach. Es bricht nichts.
|
||||||
|
3. **`mail.password` verlässt die Registry.** Ein gespeicherter Wert wandert
|
||||||
|
vorher ins `no-reply`-Postfach. Die Karte verschwindet, weil sie **ersetzt**
|
||||||
|
ist — nicht, weil sie versteckt wird.
|
||||||
|
4. `MAIL_FROM_ADDRESS`/`MAIL_FROM_NAME` verlieren ihre Rolle; das Standardpostfach
|
||||||
|
übernimmt sie. Die Werte bleiben als Rückfall stehen, solange kein Postfach
|
||||||
|
eingerichtet ist.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 10. Abgrenzung
|
||||||
|
|
||||||
|
- **Kein Empfangen.** Kein IMAP, keine Zuordnung eingehender Antworten, keine
|
||||||
|
Anhänge. `Reply-To` (§5) macht das für den Support-Fall entbehrlich.
|
||||||
|
- **Keine E-Mail-Vorlagen.** Bestellbestätigung und Störungsmeldung sind im
|
||||||
|
Handoff §3.2 vereinbart, brauchen aber erst diesen Unterbau. Eigenes Vorhaben.
|
||||||
|
- **Keine Support-Warteschlange.** Sie wird durch dieses Vorhaben *möglich*
|
||||||
|
(Handoff §3.1, Punkt 2), ist aber nicht darin enthalten.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 11. Tests
|
||||||
|
|
||||||
|
- Zweck → Postfach, inklusive Rückfall auf das Standardpostfach.
|
||||||
|
- Passwort ist mit `SECRETS_KEY` verschlüsselt, **nicht** mit `APP_KEY`; ein
|
||||||
|
APP_KEY-Wechsel lässt den Versand unberührt.
|
||||||
|
- Ein gespeichertes Passwort wird nie an die Oberfläche zurückgegeben.
|
||||||
|
- `system` lässt sich nicht leer speichern; jeder andere Zweck darf leer bleiben
|
||||||
|
und fällt dann auf `system` zurück.
|
||||||
|
- `Reply-To` gesetzt für `support`, **fehlt** bei `no_reply = true`.
|
||||||
|
- Die drei vorhandenen Mailables tragen ihren Zweck und den richtigen Absender.
|
||||||
|
- Testversand benutzt den Transport des Postfachs, **nicht** den Log-Mailer —
|
||||||
|
geprüft am Transport, nicht am Rückgabewert.
|
||||||
|
- Gewöhnlicher Versand respektiert `MAIL_MAILER=log` auf dev.
|
||||||
|
- Nichts wird beim Booten in `config('mail')` geschrieben (Regel 3).
|
||||||
|
- `mail.manage` schützt die Seite; `secrets.manage` allein genügt nicht.
|
||||||
|
- R18/R19/R20 auf der neuen Seite.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 12. Reihenfolge
|
||||||
|
|
||||||
|
| Phase | Inhalt |
|
||||||
|
|---|---|
|
||||||
|
| 1 | Tabelle, Modell, Verschlüsselung, Übernahme aus `.env`, `mail.password` aus der Registry |
|
||||||
|
| 2 | `MailboxResolver`, Zwecke, `Reply-To`, die drei Mailables umstellen |
|
||||||
|
| 3 | Konsolen-Seite, `mail.manage`, Navigation, Bearbeiten im Modal |
|
||||||
|
| 4 | Testversand am Log-Mailer vorbei, `last_verified_at`, wörtliche Fehlermeldung |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 13. Risiken
|
||||||
|
|
||||||
|
| Risiko | Gegenmaßnahme |
|
||||||
|
|---|---|
|
||||||
|
| Ein falsch gesetzter Absender fällt erst auf, wenn eine Mail nicht ankommt | Zweckliste ist Code; ein unbelegter Zweck fällt auf das Standardpostfach zurück statt zu scheitern; Testversand pro Postfach |
|
||||||
|
| Queue-Worker halten alte Zugangsdaten | Auflösung beim Versenden, nicht beim Booten (Regel 3) — als Test festgeschrieben |
|
||||||
|
| `SECRETS_KEY` fehlt | Der Vault behandelt das bereits: Speichern ist dann abgeschaltet und die Konsole sagt es, statt Zugangsdaten im Klartext abzulegen. Gleiches Verhalten für Postfächer. |
|
||||||
|
| Versehentlicher Echtversand auf dev | `MAIL_MAILER=log` bleibt wirksam; nur der Testknopf sendet, und er sagt es |
|
||||||
|
| Vorhandenes SMTP-Passwort liegt im Klartext in `.env` | Nach der Übernahme aus `.env` entfernen; Passwortwechsel empfohlen |
|
||||||
Loading…
Reference in New Issue