Neuer Chart: bulwark (JMAP-Webmail-Client fuer Stalwart) 1.0.0+up1.12.0 #89
No Assignees
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: jlab-cluster/helm-charts#89
Reference in new issue
Block a user
Ein Chart für Bulwark Webmail (
bulwarkmail/webmail), einen JMAP-Webmail-Client auf Next.js — Mail, Kalender, Kontakte und Dateien im Browser.Er ist der Begleiter zu
stalwart(#65). Upstream formuliert die Arbeitsteilung selbst: „Stalwart is the mail server: it holds the messages, speaks SMTP, and owns the accounts." Bulwark ist ausschließlich Client und hält keine Mail.| Dies ist noch kein freigegebener Plan. Fünf Entscheidungen unten sind offen und gehören vor der Umsetzung beantwortet.
Verifizierte Fakten
Gegen die GitHub-Releases, das
Dockerfileam Zweigmainund die Upstream-Dokumentation geprüft, nicht aus der Erinnerung:ghcr.io/bulwarkmail/webmail1.0.0+up1.12.0node:24-alpine, Next.js-Standalone-BuildUSER nextjs, uid/gid 1001 — läuft bereits als Nicht-RootEXPOSE 3000,PORT=3000,HOSTNAME=0.0.0.0CMD ["node", "server.js"]/api/health— „answers liveness probes for Docker and orchestrators. It returns healthy, degraded, or unhealthy along with uptime, version, and heap usage"Lobenswert am Abbild: Upstream entfernt
npmundnpxaus dem Laufzeit-Abbild und ruftapk upgradeim Build.Es ist nicht zustandslos — vier Verzeichnisse
Die Webseite sagt „Docker is the only requirement". Das Abbild legt aber vier beschreibbare Verzeichnisse unter
/app/dataan, und die Doku nennt für drei von ihnen, was darin liegt:/app/data/adminADMIN_CONFIG_DIRconfig.json,policy.json,admin.json(passwordHash only),plugin-config/,plugins/,themes/, and uploaded branding assets"/app/data/admin-stateADMIN_STATE_DIRadmin-state.json(login timestamps),audit.log, and the bootstrap setup token"/app/data/settingsSETTINGS_DATA_DIRSETTINGS_SYNC_ENABLED=true"/app/data/telemetryEin Chart ohne Volume verliert also die Admin-Konfiguration und das Audit-Protokoll bei jedem Neustart.
Drei Optionen sind beim Bauen festgebacken
„These are compiled into the bundle and cannot be changed at runtime … To change build-time variables with the published Docker image, rebuild with matching
--build-arg."NEXT_PUBLIC_BASE_PATH— ein Unterpfad wie/webmail. Der Chart kann Bulwark also nur an der Wurzel eines Hostnamens ausliefern, nicht unter einem Pfad.NEXT_PUBLIC_DEFAULT_LOCALE— Vorgabeen. Die Rückfall-Sprache der Oberfläche ist damit nicht durch den Chart änderbar; ein Besucher mit passendemAccept-Languagebekommt seine Sprache, alle anderen Englisch.NEXT_PUBLIC_PUSH_RELAY_URL— Vorgabehttps://notifications.relay.bulwarkmail.org. Web-Push läuft damit über den Relay des Anbieters, und das ist mit dem veröffentlichten Abbild nicht umstellbar. Bei einem Mailclient ist das eine Angabe, die invalues.yamlund auf die Wiki-Seite gehört, auch wenn der Chart sie nicht beeinflussen kann.Ein eigenes Abbild zu bauen ist der einzige Ausweg und liegt außerhalb dessen, was dieses Repository tut — dieselbe Grenze wie bei
garage(#81) undkeycloak(#83).Deklarativ geht, mit einer Vorrangfalle
Es gibt einen Einrichtungsassistenten beim ersten Start, der „chooses OAuth or password sign-in, generates a session secret and sets the admin password" und das Ergebnis nach
ADMIN_CONFIG_DIRschreibt. Er ist aber vermeidbar:JMAP_SERVER_URLschaltet ihn ab.Die Falle, und sie ist die unangenehmste Stelle dieses Charts: „A server URL saved by the wizard takes priority over the environment variable." Hat der Assistent also je gelaufen, gewinnt die Datei auf dem Volume über den Wert aus dem Chart — lautlos, und ein
helm upgrademit geänderter URL ändert dann nichts.Die Laufzeitvariablen
JMAP_SERVER_URLSESSION_SECRETopenssl rand -base64 32ADMIN_PASSWORDSTALWART_RECOVERY_ADMINbei #65STALWART_FEATUREStrueOAUTH_ENABLED,OAUTH_CLIENT_ID,OAUTH_ISSUER_URL,OAUTH_ONLYOAUTH_ONLYverbirgt das PasswortformularOAUTH_CLIENT_SECRET_FILEOAUTH_CLIENT_SECRET_FILEist erwähnenswert, weilgarage(#81) undkeycloak(#83) beide keine Dateiform kennen und wir dort auf Umgebungsvariablen ausgewichen sind. Hier geht der bessere Weg.Offene Entscheidungen
JMAP_SERVER_URLoder der Assistent? Deklarativ passt zu diesem Repository, aber die Vorrangfalle oben bleibt: wer den Assistenten einmal laufen lässt, entkoppelt den Chart lautlos./app/data. Eine PVC dort hält Konfiguration, Zustand und Audit-Protokoll zueinander konsistent — nach der Lehre aus #81 (Longhorn-Schnappschüsse sind je Volume atomar) spricht das für eine.SETTINGS_SYNC_ENABLEDverschlüsselt Nutzereinstellungen auf dem Volume und verlangtSESSION_SECRET. An heißt: Einstellungen folgen dem Nutzer, und das Volume trägt Nutzerdaten.OAUTH_ONLYwürde das Passwortformular ganz verbergen. Das verbindet die drei Charts und ist eine Betriebsentscheidung, keine Chart-Frage.ReadWriteOnceblockiert ein rollendes Update eines Deployments sich selbst — zwei Pods können das Volume nicht teilen. Die Konvention dieses Repositories verlangt für zustandsbehaftete Anwendungen ohnehin eine StatefulSet (bulwark.sfs.yaml).Am laufenden Dienst zu messen
/api/healthmit einem Code ungleich 200, wenn der Zustanddegradedoderunhealthyist? Das entscheidet, ob eine Probe darauf überhaupt scheitern kann. Tut sie es nicht, ist es die Gestalt von #218 und zuletzt von #83 — eine Probe, die immer grün ist. Vor dem Festlegen der Probes zu messen, nicht danach.readOnlyRootFilesystem: truemit/app/dataals Volume? Next.js im Standalone-Modus schreibt unter Umständen nach/tmpoder in einen Cache unter.next— welche emptyDirs nötig sind, ist zu messen.config.jsonwirklich überJMAP_SERVER_URL? Die Doku behauptet es; davon hängt ab, wie scharf die Warnung formuliert werden muss.OAUTH_CLIENT_SECRET_FILEbeim Start oder je Anfrage gelesen? Entscheidet, ob eine Geheimnis-Drehung einen Neustart braucht.CI-Verdrahtung
.github/workflows/publish-bulwark.yml— eine bestehende Hülle kopieren.bulwarkin diechart-name-Auswahlliste vonchange-app-version.yml.ci/bulwark/. Hier billig und aussagekräftig: es braucht keine Datenbank, einJMAP_SERVER_URLauf eine Attrappe genügt, und der Pod sollReadywerden.customManagers-Block inrenovate.json5. Zu messen statt anzunehmen: es gibt Vorab-Fassungen (1.11.0-beta.1bis.3), also ist per Dry-Run zu belegen, ob Renovate sie anbietet — beikeycloak(#83) war die vermutete Beschränkung am Ende unnötig, beigarage(#81) nötig.Nicht in diesem Chart
Der Stalwart-Server selbst (#65) und die OIDC-Client-Registrierung in Keycloak (#83) gehören in das abnehmende Bundle in
cluster-config, nicht hierher.Freigegebener Umsetzungsplan
Die fünf offenen Entscheidungen sind beantwortet: drei vom Betreuer, zwei folgen aus den Konventionen.
1. Deklarativ, der Assistent läuft nie
JMAP_SERVER_URLwird gesetzt und schaltet den Einrichtungsassistenten ab.SESSION_SECRETundADMIN_PASSWORDkommen aus einemOnePasswordItem.ADMIN_PASSWORDist dabei nicht optional, sondern der Grund für diese Richtung: ohne Angabe erzeugt Bulwark ein Zufallspasswort und schreibt es nach stdout — in Kubernetes also ins Pod-Protokoll, bei jedem Neustart ein neues. Dieselbe Gestalt wieSTALWART_RECOVERY_ADMINbei #65, und dieselbe Antwort.Die Vorrangfalle gehört prominent dokumentiert, nicht als Fußnote: „A server URL saved by the wizard takes priority over the environment variable." Wer die Admin-Oberfläche öffnet und dort eine Server-URL speichert, entkoppelt den Chart lautlos — ein
helm upgrademit geändertemJMAP_SERVER_URLändert danach nichts, und nichts in der Oberfläche sagt das.Verworfen:
ADMIN_CONFIG_DIRschreibgeschützt einhängen, um den Assistenten hart zu sperren. Die Admin-Oberfläche schreibt in dasselbe Verzeichnis (Policy, Themes, Branding, Plugins), ein schreibgeschütztes Einhängen würde sie also mitnehmen. Die Falle wird benannt, nicht verbaut.2. Einstellungs-Synchronisierung an
SETTINGS_SYNC_ENABLED=true,/app/data/settingsträgt verschlüsselte Einstellungen je Konto.Folge, die in
values.yaml,NOTES.txtund ins Wiki gehört: das Volume trägt damit Nutzerdaten, verschlüsselt mitSESSION_SECRET. Geht das Geheimnis verloren, sind sie unlesbar — auch aus einer intakten Sicherung. Das Geheimnis gehört deshalb genauso in die Sicherung wie das Volume, und das ist der Satz, der dort stehen muss: eine Sicherung des Volumes allein ist keine Sicherung.3. Anmeldung ausschließlich über OIDC
OAUTH_ENABLED=true,OAUTH_ONLY=true, Keycloak (#83) als Anbieter, das Geheimnis überOAUTH_CLIENT_SECRET_FILEaus einemOnePasswordItem— also als vertraulicher Client, was Keycloak problemlos kann, und über die Dateiform, die beigarage(#81) undkeycloak(#83) nicht existierte.Das Risiko ist benannt und wird in Kauf genommen: fällt Keycloak aus oder ist die OIDC-Konfiguration falsch, kommt niemand mehr an seine Mail, und das Passwortformular ist verborgen. Daraus folgen zwei Dinge, die der Chart tragen muss:
OAUTH_ONLYund ohne registrierten Client ist die erste Anmeldung unmöglich.NOTES.txtnennt die Reihenfolge.helm upgrademitOAUTH_ONLY=falsebringt das Passwortformular zurück. Das ist die einzige Tür, die nicht an Keycloak hängt — die Admin-Oberfläche hat ihr eigenes Passwort, gibt aber keinen Mailzugang. Ohne diesen Satz inNOTES.txtist eine Fehlkonfiguration ein Ausfall ohne sichtbaren Weg zurück.SESSION_SECRETist damit verpflichtend, nicht optional: sowohl die Einstellungs-Synchronisierung als auch die persistenten Sitzungen hängen daran.4. Eine PVC an
/app/dataAlle vier Verzeichnisse liegen darunter, Bulwark legt sie selbst an. Nach der Lehre aus #81 — Longhorn-Schnappschüsse sind je Volume atomar, nicht volumenübergreifend — hält eine PVC Konfiguration, Laufzeitzustand, Audit-Protokoll und Nutzereinstellungen zueinander konsistent. Getrennte Volumes könnten eine Sicherung erzeugen, in der das Protokoll Anmeldungen nennt, die die Konfiguration noch nicht kennt.
5. StatefulSet
bulwark.sfs.yaml. MitReadWriteOnceblockiert ein rollendes Deployment sich selbst, weil zwei Pods das Volume nicht teilen können; die Konvention dieses Repositories verlangt für zustandsbehaftete Anwendungen ohnehin eine StatefulSet.Was der Chart nicht ändern kann, und trotzdem benennen muss
Drei Optionen sind beim Bauen festgebacken. Zwei sind Unbequemlichkeiten, eine ist eine Offenlegung:
NEXT_PUBLIC_PUSH_RELAY_URL, Vorgabehttps://notifications.relay.bulwarkmail.org. Web-Push läuft über den Relay des Anbieters, und mit dem veröffentlichten Abbild ist das nicht umstellbar. Bei einem Mailclient gehört das invalues.yamlund auf die Wiki-Seite, auch wenn der Chart nichts dagegen tun kann.NEXT_PUBLIC_BASE_PATH— kein Unterpfad, der Ingress bedient die Wurzel eines Hostnamens.NEXT_PUBLIC_DEFAULT_LOCALE— Rückfall-Sprache bleibten.Umfang
Gebaut aus
template-chart/nach CLAUDE.md und dem Stilleitfaden: StatefulSet, eine PVC, Service, Ingress nach Konvention (ingress.domainundingress.clusterIssuerrequired ohne Vorgabe,classNameVorgabenginx, TLS-Secrettls-<release>-bulwark-ingress),OnePasswordItemfürSESSION_SECRET,ADMIN_PASSWORDund das OAuth-Geheimnis, drei Probes, berechnete Limits,replicasplusscaleDown, strengesvalues.schema.jsongegen die echten Bundle-Werte.Entsteht keine ConfigMap — die Konfiguration läuft über Umgebungsvariablen —, dann greift die
checksum/config-Regel (#82) nicht, und das muss ausdrücklich invalues.yamlstehen, sonst sieht es wie eine Auslassung aus.CI:
publish-bulwark.ymlaus einer bestehenden Hülle kopiert;bulwarkin diechart-name-Liste; Fixtures unterci/bulwark/mit einerJMAP_SERVER_URL-Attrappe und Dummy-Geheimnissen;customManagers-Block inrenovate.json5.Wiki im selben Durchgang: neue Seite
bulwark, Zeile inCharts(Zähler prüfen, nicht übernehmen), Eintrag in_Sidebar.md, und auf derstalwart-Seite ein Querverweis, weil die beiden nur zusammen nützlich sind.Am laufenden Dienst zu messen
/api/healthmit einem Code ungleich 200, wenn der Zustanddegradedoderunhealthyist? Es gibt nur diesen einen Endpunkt, nicht die Dreiteilung live/ready/started. Antwortet er immer mit 200 und nennt den Zustand nur im Rumpf, ist eine Probe darauf eine Probe, die nicht scheitern kann — die Gestalt von #218 und zuletzt von #83. Vor dem Festlegen der Probes zu messen, nicht danach, und wenn er nicht scheitern kann, gehört das als Grenze an den Wert geschrieben statt verschwiegen.readOnlyRootFilesystem: truemit/app/dataals Volume? Next.js im Standalone-Modus schreibt unter Umständen nach/tmpoder in einen Cache unter.next— welche emptyDirs nötig sind, ist zu messen.config.jsonwirklich überJMAP_SERVER_URL? Davon hängt ab, wie scharf die Warnung formuliert werden muss.OAUTH_CLIENT_SECRET_FILEbeim Start oder je Anfrage gelesen? Entscheidet, ob eine Geheimnis-Drehung einen Neustart braucht — und das gehört ins Wiki, weil es sonst beim ersten Wechsel überrascht.1.11.0-beta.1bis.3. Per Dry-Run zu belegen: beikeycloak(#83) war die vermutete Beschränkung am Ende unnötig, beigarage(#81) nötig. Keine Zeile schreiben, die nichts tut.Nicht in diesem Chart
Der Stalwart-Server selbst (#65) und die OIDC-Client-Registrierung in Keycloak (#83) gehören in das abnehmende Bundle in
cluster-config.Angehalten: drei sachliche Fehler, einer davon sicherheitsrelevant
Der Entwicklungsagent hat vor dem Festlegen der Probes gemessen, wie gefordert — und dabei im Quelltext am Tag
1.12.0drei Behauptungen widerlegt, auf denen der freigegebene Plan aufbaut. Eine davon betrifft den einzigen dokumentierten Ausweg aus einer Totalaussperrung. Es ist noch keine Zeile Chart geschrieben, weil alle dreivalues.yaml,NOTES.txtund den Traps-Abschnitt des Wikis verändern.Gemessen am entpackten Quell-Tarball
bulwarkmail/webmailTag1.12.0(nicht am Zweigmain, nicht aus der Dokumentation). Kein Laufzeitlauf — kein Docker in diesem Workspace.1. Der Ausweg aus der Aussperrung funktioniert so nicht
Der Plan nennt unter Punkt 3 genau eine Tür: „
helm upgrademitOAUTH_ONLY=falsebringt das Passwortformular zurück. Das ist die einzige Tür, die nicht an Keycloak hängt."Diese Tür kann verschlossen sein, und zwar genau dann, wenn man sie braucht.
Die Vorrangregel, die der Plan für die Server-URL benennt, ist nicht auf die Server-URL beschränkt. Sie ist das Verhalten jedes Wertes, den dieser Chart setzt.
lib/admin/config-manager.ts:56-88:this.adminConfigistconfig.jsonausADMIN_CONFIG_DIR, also von der PVC (config-manager.ts:35).oauthOnlyist ein gewöhnlicher Schlüssel dieser Tabelle —lib/admin/types.ts:236:und jeder Laufzeitkonsument liest ihn über
configManager.get, nicht überprocess.env:app/api/auth/session/route.ts:83— serverseitige Sperre des Passwort-Loginsapp/api/auth/verify/route.ts:52— dieselbe Sperreapp/api/config/route.ts:51— das, was die Login-Seite auswertetUnd geschrieben wird dieser Override von der Admin-Oberfläche, die nicht an Keycloak hängt und die man in einer Aussperrung als erstes aufsucht.
app/api/admin/oauth/setup/route.ts:216-221:Dazu
app/api/admin/config/route.ts:70— die Oberfläche darf jeden Schlüssel ausCONFIG_ENV_MAPals Override schreiben:Folge: Hat jemand die OAuth-Einrichtung der Admin-Oberfläche benutzt — der naheliegende Weg, und der Plan verbietet ihn nicht —, dann steht
oauthOnly: trueinconfig.jsonauf der PVC. Ab da istOAUTH_ONLY=falseaus dem Chart wirkungslos, einhelm upgradeändert nichts, undNOTES.txtwürde eine Anweisung tragen, die nachweislich nicht greift. Das ist dieselbe Falle, die der Plan korrekt fürJMAP_SERVER_URLbenennt — nur steht sie hier in der Rettungsanweisung selbst.Was stattdessen wirklich zurückführt
Beides im Quelltext belegt, beides unabhängig von Keycloak:
Override zurücknehmen statt ihn zu überschreiben: die Admin-Oberfläche hat ihr eigenes Passwort und kennt ein „revert" —
configManager.removeAdminOverride(config-manager.ts:148-152), freigelegt vomDELETE-Zweig inapp/api/admin/config/route.ts:165. Danach greift die Umgebung wieder.Die Überschreibung von vorn verhindern:
ADMIN_CONFIG_READONLY=truesperrt alle Schreibzugriffe auf das Konfigurationsverzeichnis auf Anwendungsebene (lib/admin/paths.ts:81-92,assertWritableinpaths.ts:124-126). Damit entsteht nie ein Override und die Chart-Werte sind dauerhaft maßgeblich.Das ist nicht das unter Punkt 1 verworfene schreibgeschützte Einhängen. Der Plan hat das
:ro-Mount verworfen, weil Policy, Themes, Branding und Plugins im gleichen Verzeichnis liegen — das Argument stimmt für das Mount.ADMIN_CONFIG_READONLYist ein anderer Mechanismus, kostet aber denselben Preis:assertWritableschützt auchsetPolicy(config-manager.ts:182) undmarkSetupComplete. Themes und Branding wären also ebenfalls eingefroren.Zu entscheiden (Betriebsentscheidung, nicht Chart-Frage):
NOTES.txtauf „Override in der Admin-Oberfläche zurücknehmen, sonstconfig.jsonauf der PVC bearbeiten" korrigieren — Chart bleibt wie geplant.adminConfigReadOnly(Vorgabefalse) einführen, derADMIN_CONFIG_READONLY=truesetzt. Macht die Chart-Werte maßgeblich und die Falle unmöglich, friert aber Policy/Themes/Branding ein.Ich habe (a) nicht einfach umgesetzt, weil (b) die Werte-Oberfläche des Charts verändert und damit nicht meine Entscheidung ist.
2.
/api/healthkann den Zustand nicht melden — die Messung, die zuerst kommen sollteAntwort: nein, der Endpunkt scheitert nicht an
degradedoderunhealthy.app/api/health/route.ts:status: 200zurück (Zeile 93-100), unabhängig vom ermittelten Zustand.healthygesetzt — Zeile 70:status: detailed ? status : 'healthy'.degradederscheint nur bei?detailed=trueund bestandenemcanSeeInstanceDetails(Zeile 51). Eine Kubernetes-Probe ist unangemeldet und sieht also nie etwas anderes alshealthy.503kommt ausschließlich aus demcatch, wenn das Sammeln der Diagnose selbst wirft (Zeile 102-112) — also wennprocess.memoryUsage()oderv8.getHeapStatistics()fehlschlägt. Praktisch nie.Das ist nicht meine Auslegung, upstream testet es so —
lib/__tests__/health-route.test.ts:61-62:Die Formulierung aus der Dokumentation im Issue-Rumpf („returns healthy, degraded, or unhealthy") ist für Probe-Zwecke also irreführend: der Zustand steht im Rumpf, nie im Code, und für die Probe nicht einmal im Rumpf.
Was eine Probe darauf trägt — und das ist mehr als bei #218: Sie prüft echt, dass der Node-Prozess lebt, der HTTP-Server annimmt, die Ereignisschleife nicht blockiert ist und Next.js routen kann. Ein OOM-Kill, ein Absturz, eine festsitzende Ereignisschleife fallen auf. Was sie nicht trägt: den gemeldeten Anwendungszustand und jede Aussage über Stalwart. Ist der Mailserver weg, ist
/api/healthgrün — Bulwark hält keine Mail und fragt den JMAP-Server für diesen Endpunkt nicht.Das gehört als Grenze an den Wert geschrieben, nicht verschwiegen. Mein Vorschlag, wenn du nichts anderes sagst: alle drei Probes auf
/api/health— Startup und Liveness sind damit sachlich korrekt bedient (Prozess lebt / ist hochgekommen), die Readiness trägt nur „nimmt HTTP an" und bekommt den Kommentar, dass sie die JMAP-Erreichbarkeit nicht abdeckt und auch nicht abdecken kann.HEAD /api/health(Zeile 118-124) ist dafür die billigste Form.Eine echte Readiness gegen Stalwart wäre
/api/setup/test-jmap, aber das ist eine Wizard-Route hinter dem Setup-Token und für eine Probe ungeeignet. Ich sehe keinen geeigneten Endpunkt.3. Der Push-Relay ist umstellbar — die geplante Offenlegung wäre falsch
Der Rumpf sagt, Web-Push laufe über den Relay des Anbieters und das sei „mit dem veröffentlichten Abbild nicht umstellbar", und der Plan macht daraus eine Pflicht-Offenlegung in
values.yamlund Wiki.Das trifft nicht zu.
lib/push-relays.ts:9-10zeigt, dass die Bau-Variable nur den eingebauten Vorgabe-Eintrag verschiebt:Der wirksame Relay kommt aber aus
policy.json—push-relays.ts:60-63:Der Anbieter-Relay ist also nur der Rückfall. Setzt ein Betreiber
pushRelayUrl, ist das die Vorgabe für alle; mitpushRelayUrlLocked: true(push-relays.ts:74,lib/admin/types.ts:155-156) sind die Nutzer darauf festgenagelt und können nichts anderes wählen.Die korrekte Aussage ist damit zweiteilig, und sie ist deutlich günstiger als die geplante: der Anbieter-Relay ist die Vorgabe und bleibt ohne eigenes Abbild in der Auswahlliste stehen, aber ein eigener Relay kann zur wirksamen Vorgabe gemacht und verbindlich gesetzt werden — über
policy.json, also die Admin-Oberfläche auf der PVC, nicht über einen Chart-Wert. Eine Offenlegung „nicht umstellbar" würde Betreibern eine Wahl absprechen, die sie haben.Dass es kein Chart-Wert ist, liegt daran, dass
policy.jsonkeine Umgebungsvariablen kennt — nachgesehen:pushRelayUrlsteht inSettingsPolicy(types.ts:154), nicht inCONFIG_ENV_MAP.4.
ADMIN_PASSWORD: die Begründung im Plan stimmt nicht, und der Wert ist einmaligZwei getrennte Punkte.
Kein Zufallspasswort nach stdout. Rumpf und Plan begründen
ADMIN_PASSWORDdamit, dass ohne Angabe „ein Zufallspasswort erzeugt und nach stdout geschrieben" werde — „dieselbe Gestalt wieSTALWART_RECOVERY_ADMINbei #65". Gemessen: ohneADMIN_PASSWORDwird die Admin-Oberfläche einfach abgeschaltet.lib/admin/password.ts:142-147:Ich habe
lib/adminundlib/setupnachrandomBytes, Passwortgenerierung undconsole.logdurchsucht: der einzige erzeugte Zufallswert ist das Bootstrap-Setup-Token (lib/setup/token.ts:54), und das wird in das Zustandsverzeichnis geschrieben und nie protokolliert. Es gibt also kein Leck ins Pod-Protokoll — die Gestalt von #65 liegt hier nicht vor.Die Entscheidung,
ADMIN_PASSWORDzu setzen, bleibt davon unberührt richtig (sonst keine Admin-Oberfläche — und nach Punkt 1 ist sie der Rettungsweg). Nur die Begründung gehört korrigiert, damit sie nicht als Präzedenz weiterwandert. Erwähnenswert ist die Gegenrichtung: ohneADMIN_PASSWORDgibt es auch keine Oberfläche, die Overrides schreiben und damit die Falle aus Punkt 1 auslösen kann.Der Wert wird genau einmal verbraucht.
initAdminPasswordkehrt zurück, sobaldadmin.jsonexistiert, und sieht die Umgebungsvariable dann nie wieder an (password.ts:125-140); beim ersten Start wird sie gehasht und persistiert (password.ts:149-153). Eine Drehung des Feldes im Tresor hat danach keine Wirkung — zurückgesetzt wird nur über die Oberfläche selbst oder durch Löschen vonadmin.jsonauf der PVC. Das gehört invalues.yaml,NOTES.txtund ins Wiki, zusammen mit der Falle aus Punkt 1, weil es dieselbe Ursache hat: der Zustand auf dem Volume schlägt den Chart.Was unabhängig davon schon gemessen ist
Die Falle aus #81 greift hier nicht. Bulwark prüft die Dateirechte nicht.
lib/read-file-env.tsist vollständig:Kein
statSync, keinmode & 0o077. Ein gemountetes Kubernetes-Secret mit Gruppen-Lesebit ist lesbar,fsGroupist unschädlich. Die Dateiform ist tragfähig — der Ausweg auf eine Umgebungsvariable wie beigarageist hier nicht nötig.Drehung des OAuth-Geheimnisses braucht keinen Neustart — mit einer Einschränkung, die der Chart bestimmt.
getGlobalClientSecret(lib/oauth/token-exchange.ts:55-65) ruftreadFileEnvbei jedem Token-Tausch auf, ohne Zwischenspeicher. Die Datei wird also je Anfrage gelesen. Damit das trägt, muss das Secret ohnesubPatheingehängt werden — einsubPath-Mount wird vom Kubelet nie aktualisiert, und dann bräuchte es doch einen Neustart. Das nehme ich so auf.SESSION_SECRETist zu Recht verpflichtend.app/api/config/route.ts:68schaltet die Synchronisierung still ab, wenn das Geheimnis fehlt:settingsSyncEnabled: configManager.get(...) && hasSessionSecret(). Ohne das Geheimnis wäreSETTINGS_SYNC_ENABLED=truewirkungslos — lautlos. Der Plan liegt hier richtig.Nebenbefund für die Sicherung, der sie verschärft:
app/api/admin/oauth/setup/route.ts:218schreibtoauthClientSecretim Klartext inconfig.jsonauf die PVC. Der Satz „eine Sicherung des Volumes allein ist keine Sicherung" bekommt damit eine Kehrseite, die genauso wichtig ist: eine Sicherung des Volumes kann das OAuth-Client-Geheimnis im Klartext enthalten. Das gehört in den Traps-Abschnitt.Es gibt auch
SESSION_SECRET_FILE(lib/admin/types.ts:277,lib/auth/session-secret.ts:22). Der Plan nennt nur die Dateiform für das OAuth-Geheimnis;SESSION_SECRETkönnte genauso aus einer Datei kommen und bliebe dann aus der Prozessumgebung heraus. Da das Secret für OAuth ohnehin eingehängt wird, ist es fast kostenlos.ADMIN_PASSWORDhat keine Dateiform. Ich setze das nicht eigenmächtig um — sag, ob du es willst.Bestätigt, unverändert gültig: uid/gid 1001 (
nextjs/nodejs,Dockerfile:42-43viaaddgroup --gid 1001/adduser --uid 1001), Port 3000,CMD ["node", "server.js"], die vier Verzeichnisse werden im Abbild angelegt und gechownt (Dockerfile:55),apk upgradeundnpm uninstall -g npmim Laufzeit-Abbild.JMAP_SERVER_URLschaltet den Assistenten tatsächlich ab:detectSetupStategibtenv-managedzurück (lib/setup/state.ts:24-28), undsetupCompletewird nur von der Wizard-Abschlussroute gesetzt — der Assistent läuft also nie. Plan-Punkt 1 trägt insoweit.Zu
readOnlyRootFilesystem(noch nicht abschließend):next.config.ts:51bautoutput: "standalone", undimages.unoptimizedgilt nur imisLite-Zweig (next.config.ts:54) — die Bildoptimierung ist im normalen Abbild also aktiv und schreibt ihren Zwischenspeicher nach/app/.next/cache. Ich erwarte daher emptyDirs für/tmpund/app/.next/cache. Das ist eine Ableitung aus dem Quelltext, keine Messung — den genauen Satz belegt erst der Install-Test in der CI, und ich werde ihn dort belegen statt behaupten.Renovate-Dry-Run: noch offen. Im Workspace ist keine Renovate-CLI vorhanden (
renovate,renovate-config-validatorbeide nicht gefunden). Die Vorab-Fassungen gibt es: Tags1.11.0-beta.1bis.3neben1.11.0…1.12.0, und die Tags tragen keinv-Präfix. Ich hole den Dry-Run übernpx renovatenach, sobald die Punkte oben entschieden sind, und schreibe das Ergebnis als Begründung an den Block — keine Zeile, die nichts tut.Stand
Kein Branch, kein Commit, keine PR. Nichts im Repository angefasst — nur gelesen. Es wartet auf deine Entscheidung zu:
adminConfigReadOnly. Das ist die eine Entscheidung, die den Chart selbst ändert./api/health, Readiness mit benannter Grenze) bestätigen oder ersetzen.ADMIN_PASSWORD-Begründung und Aufnahme der Einmaligkeit; ob die #65-Analogie aus dem Rumpf gestrichen wird.SESSION_SECRET_FILEstatt Umgebungsvariable — ja oder nein.Korrekturen am freigegebenen Plan — drei Fehler, einer davon in der Rettungsanweisung
Alle drei Befunde sind gegen den Quelltext am Tag 1.12.0 nachgeprüft und bestätigt. Der Plan wird an diesen Stellen korrigiert; die Entscheidungen des Betreuers (deklarativ, Synchronisierung an, nur OIDC) bleiben gültig.
Fehler 1 — der dokumentierte Ausweg aus der Aussperrung funktioniert nicht
Der Plan nannte genau eine Tür:
helm upgrademitOAUTH_ONLY=false. Die ist verschlossen, genau wenn man sie braucht.lib/admin/config-manager.ts, wörtlich:Und
oauthOnlyist so ein Schlüssel —lib/admin/types.ts:236:Der Override liegt in
config.jsonauf der PVC und wird von der Admin-Oberfläche geschrieben, die nicht an Keycloak hängt und die man in einer Aussperrung zuerst aufsucht. Wer dort die OAuth-Einrichtung benutzt hat, hatoauthOnly: trueauf dem Volume — ab da ist der Chart-Wert wirkungslos. Die Falle, die der Plan korrekt fürJMAP_SERVER_URLbenannte, steckte in der Rettung selbst.Der Ausweg, der wirklich zurückführt, und er hängt nicht an Keycloak: in der Admin-Oberfläche (eigenes Passwort) den Override entfernen —
removeAdminOverride,DELETEaufapp/api/admin/config/route.ts. Danach greift der Wert aus dem Chart. Das ist der Satz, der inNOTES.txtund ins Wiki gehört, und er ist der Grund, warum die Admin-Oberfläche erreichbar sein muss.Zusätzlich kommt ein Wert
adminConfigReadOnly(Vorgabefalse), derADMIN_CONFIG_READONLY=truesetzt. Damit kann die Oberfläche überhaupt keinen Override schreiben, der Chart bleibt autoritativ, undOAUTH_ONLY=falsewirkt immer. Der Preis gehört an den Wert, nicht in eine Fußnote: es friert auchsetPolicyein, also Policy, Themes, Branding — und nach Fehler 3 damit auch die einzige Möglichkeit, Web-Push auf einen eigenen Relay umzustellen. Darum Vorgabefalse: wer den strengeren Modus will, wählt ihn bewusst.Das Risiko der Nur-OIDC-Entscheidung ist damit wieder begrenzt, nur anders als ich geschrieben hatte: die Tür ist die Admin-Oberfläche, nicht
helm upgrade.Fehler 2 —
/api/healthkann nicht scheitern, und das war die verlangte Messungapp/api/health/route.ts, der Erfolgspfad:Eine Probe ist unangemeldet, bekommt also
detailed = false, und damit sowohl HTTP 200 als auch den Rumpfhealthy— unabhängig vom tatsächlichen Zustand. Upstream prüft das selbst so:lib/__tests__/health-route.test.tserwartetstatus 200beipayload.status === 'degraded'.503kommt nur aus demcatch, wennprocess.memoryUsage()selbst wirft.Es ist aber nicht die Gestalt von #218 und #83, und diese Unterscheidung gehört an den Wert statt in eine pauschale Warnung: die Probe trägt echt, dass der Prozess lebt, HTTP annimmt, die Ereignisschleife frei ist und Next.js routet — ein OOM-Kill, ein Absturz, eine festsitzende Schleife fallen damit auf. Sie trägt nicht den gemeldeten Zustand und keine Aussage über Stalwart: ist der Mailserver weg, ist
/api/healthgrün.Festgelegt: alle drei Probes auf
/api/health, alsHEAD(die billigste Form, die der Endpunkt anbietet), und die Grenze wörtlich an den Readiness-Wert geschrieben. Einen besseren Endpunkt gibt es nicht —/api/setup/test-jmapliegt hinter dem Setup-Token.Fehler 3 — der Push-Relay ist umstellbar, die geplante Offenlegung war falsch
lib/push-relays.ts: die Bau-Variable verschiebt nur den eingebauten Vorgabe-Eintrag. Der wirksame Relay kommt auspolicy.json—resolveDefaultRelayUrlnimmtpolicy.pushRelayUrl, wenn gültig, und der Anbieter-Relay ist der Rückfall; mitpushRelayUrlLocked: truesind die Nutzer darauf festgenagelt.Korrekt ist zweiteilig: der Anbieter-Relay ist die Vorgabe und bleibt ohne eigenes Abbild in der Auswahlliste — aber ein eigener Relay kann wirksame Vorgabe und verbindlich werden, über die Admin-Oberfläche, nicht über einen Chart-Wert (
pushRelayUrlsteht inSettingsPolicy, nicht inCONFIG_ENV_MAP). „Nicht umstellbar" hätte Betreibern eine Wahl abgesprochen, die sie haben.Fehler 4 —
ADMIN_PASSWORD: Begründung falsch, Wert ist einmaligOhne
ADMIN_PASSWORDwird kein Zufallspasswort erzeugt und nichts nach stdout geschrieben — die Admin-Oberfläche wird schlicht abgeschaltet (lib/admin/password.ts). Der einzige Zufallswert im Projekt ist das Bootstrap-Setup-Token, das ins Zustandsverzeichnis geschrieben und nie protokolliert wird. Die Analogie zuSTALWART_RECOVERY_ADMIN(#65) trägt hier nicht und wird aus dem Plan gestrichen.Die Entscheidung, es zu setzen, bleibt — mit einer besseren Begründung: nach Fehler 1 ist die Admin-Oberfläche der Rettungsweg. Sie abzuschalten heißt, sich die Tür zu nehmen.
Und der Wert ist einmalig:
initAdminPasswordkehrt zurück, sobaldadmin.jsonexistiert, und sieht die Variable nie wieder an. Eine Drehung des Tresorfeldes wirkt danach nicht; ein Reset läuft über die Oberfläche oder über das Löschen vonadmin.json. Gleiche Ursache wie Fehler 1: Volumenzustand schlägt Chart. Gehört ins Wiki.Was übernommen wird
SESSION_SECRET_FILEexistiert und wird genommen — ein Secret wird ohnehin eingehängt, die Dateiform kostet also nichts und hält das Geheimnis aus der Prozessumgebung.ADMIN_PASSWORDhat keine Dateiform und bleibt eine Umgebungsvariable.lib/read-file-env.tsistreadFileSyncplustry/catch, ohnestatSyncund ohnemode & 0o077. Das Gruppen-Lesebit ausfsGroupist unschädlich, die Dateiform ist tragfähig.lib/oauth/token-exchange.ts), eine Drehung wirkt also ohne Neustart — aber nur, wenn das Secret ohnesubPatheingehängt wird, weil das KubeletsubPath-Mounts nie aktualisiert.app/api/admin/oauth/setup/route.tsschreibtoauthClientSecretim Klartext inconfig.jsonauf die PVC. Eine Volumensicherung kann also das OAuth-Client-Geheimnis im Klartext enthalten. Das gehört neben den Satz, dass eine Sicherung ohneSESSION_SECRETkeine Sicherung ist.SESSION_SECRETist zu Recht verpflichtend:app/api/config/route.tsschaltet die Einstellungs-Synchronisierung lautlos ab, wenn es fehlt.Offen für den nächsten Durchgang
readOnlyRootFilesystemist abgeleitet, nicht gemessen:next.config.tsbautoutput: "standalone"undimages.unoptimizedgilt nur im Lite-Zweig, die Bildoptimierung ist also aktiv und schreibt nach/app/.next/cache. Erwartet werden emptyDirs für/tmpund diesen Pfad; den genauen Satz belegt der Install-Test.npx renovate. Belegt ist bisher nur: Vorab-Fassungen existieren (1.11.0-beta.1bis.3) und die Tags tragen keinv-Präfix.Umgesetzt in PR #90 — mit fünf Korrekturen, eine davon braucht deine Bestätigung
Der Chart ist gebaut, alle Checks sind grün, das Wiki ist im selben Durchgang gelandet (
996f8c0). PR trägtPart of #89, nichtFixes— der Grund steht unter Punkt 5.Alles unten ist am Quelltext am Tag
1.12.0gemessen. Die Befunde aus den Kommentaren 5342/5349 habe ich dabei alle unabhängig nachgeprüft und bestätigt (Vorrangordnung inconfig-manager.ts,oauthOnlyintypes.ts:236und seine drei Konsumenten,/api/healthmit hartem 200,push-relays.ts,password.ts,read-file-env.ts,token-exchange.ts,session-secret.ts). Nichts davon war falsch.1. Die Begründung für
telemetry: falsestimmt so nichtDer Plan behandelt das Abschalten als Abweichung von der Abbild-Vorgabe. Gemessen:
DEFAULTSinlib/telemetry/state.tsträgtconsent: 'off'— Telemetrie ist opt-in, und der Kommentar ininstrumentation.node.ts(„on by default") ist falsch. Was das Rendern der Variable wirklich bringt, ist die Sperre:effectiveConsent()nimmt die Umgebung über die Zustandsdatei, und Upstream blockiert die Oberfläche, solange der Override gesetzt ist.Folge für 5349: es gibt nicht zwei, sondern drei Ausnahmen von „der Volumenzustand schlägt den Chart" —
SESSION_SECRET(_FILE),ADMIN_PASSWORDundBULWARK_TELEMETRY.BULWARK_UPDATE_CHECKist übrigens genau umgekehrt (an, solange nicht abgeschaltet), die beiden Werte sind also nicht symmetrisch.2.
adminConfigReadOnlykostet mehr als 5349 beziffert5349 nennt einen Preis (
setPolicyfriert ein → Policy, Themes, Branding, Push-Relay). Es sind drei, alle aus demselbenassertWritable:removeAdminOverrideist ebenfalls bewacht. Einschalten entfernt einen bestehenden Override also nicht, sondern friert ihn fest — und nimmt im selben Zug die dokumentierte Reparatur weg. Eine behebbare Aussperrung wird damit zu einer dauerhaften.initAdminPasswordpersistiert überwriteConfigData, das mitassertWritable('save admin password')beginnt. Ohne vorhandeneadmin.jsonwirft das: der Start-Hook protokolliertAdmin dashboard init skipped, der erneute Versuch in/api/admin/authwirft wieder, und der Login-Endpunkt antwortet HTTP 500 — während der PodReadyist und Mail ausliefert.Die Entscheidung (Wert einführen, Vorgabe
false) bleibt richtig und ist jetzt besser begründet. Der vollständige Preis und die einzige gefahrlose Reihenfolge stehen am Wert und inNOTES.txt.3. Die OIDC-Redirect-URI trägt die Oberflächensprache
Sie lautet
https://<domain>/<locale>/auth/callback, wobei<locale>die Sprache ist, die der Browser des Besuchers aufgelöst hat — 27 Sprachen, und der Locale-Präfix ist in diesem Abbildnever, die Sprache steht also nicht in der sichtbaren URL. Upstreams eigener Admin-Helfer registriert deshalb eine URI pro Sprache (buildRedirectUris).Eine einzeln registrierte URI ist damit die wahrscheinlichste Ursache für eine scheiternde erste Anmeldung, und das stand nirgends.
NOTES.txtnennt jetzt den Wildcard und die vollständige Sprachliste.4. Die Registry veröffentlicht jede Fassung doppelt
Die frühere Notiz sagt, die Tags trügen kein
v-Präfix. Gemessen gegen die ghcr.io-Tag-API:1.12.0undv1.12.0existieren für dasselbe Abbild, beide Familien bis1.3.9zurück. Insgesamt 315 Tags in acht Formen (dazu-always, gleitende Minors,latest/main/dev, Commit-SHAs, die Betas, Attestierungen).Der Chart pinnt die suffixfreie Form. Renovate-Dry-Run, 44.138.0,
--platform=local --dry-run=lookup, gegen die echterenovate.json5dieses PRs:1.12.0→updates: [],warnings: []1.11.0→ genau zwei:1.11.2(patch),1.12.0(minor)1.10.0→ genau eine:1.12.0(minor)Kein Lauf bot eine Beta, ein
-always, einev-Form, einen gleitenden oder einen SHA-Tag an. Also keinversioningTemplate— wie bei keycloak, nicht wie bei garage. Die Zählung und die Begründung je Form stehen im Block.Ein Vorbehalt, der im Log sichtbar war und deshalb dort steht: ghcr.io lieferte anonym keinen
releaseTimestamp, weshalb Renovate beide Updates unterminimumReleaseAgealspendingChecks: truemarkierte. Ob die geteilte Instanz die Zeitstempel sieht, habe ich nicht geprüft — sie authentifiziert sich mitGITHUB_COM_TOKEN, dieser Lauf nicht. Falls nicht, betrifft es jeden ghcr.io-Chart hier gleichermaßen und ist keine Entscheidung über diesen.5.
HEADist mit einer Kubernetes-Probe nicht herstellbar — hier weiche ich ab5349 legt fest: „alle drei Probes auf
/api/health, als HEAD (die billigste Form, die der Endpunkt anbietet)".Das geht nicht. Der API-Typ ist
HTTPGetAction; er hat kein Methodenfeld, und das Kubelet sendet immer GET. Es gibt keinen Wert in einer Pod-Spezifikation, der das ändert. Die einzige Möglichkeit für ein HEAD wäre eineexec-Probe mit einem HTTP-Client — und dieses Abbild hat wedercurlnochwget(npmundnpxsind aus der Laufzeitschicht entfernt), es wäre also alle paar Sekunden ein neuer Node-Prozess gegen einen Endpunkt, dessen GET bereits billig ist.Der Chart verwendet GET. Sachlich ändert das nichts an deiner Begründung: der Handler gibt weiterhin hart 200 zurück, setzt den Rumpf für unangemeldete Aufrufer hart auf
healthy, und sagt nichts über Stalwart. GET ist sogar geringfügig tragfähiger als HEAD, weil seincatch-Zweig 503 liefern kann, wenn die Diagnose selbst wirft — HEAD gibt ein nacktes 200 zurück und rechnet gar nichts.Das ist die einzige Entscheidung, die ich geändert statt erfragt habe, und deshalb trägt der PR
Part of #89: einFixeswürde das Issue automatisch schließen und damit eine geänderte verbindliche Festlegung als abgenommen verbuchen. Sag Bescheid, wenn du es anders willst — dann ist dieexec-Probe der Weg, mit dem Preis oben.Dazu ein Befund, der nicht im Plan stand
bulwark.stalwartAdminAccesssteht auf Upstreamsauto, also unverändert — aber die Folge gehört benannt: mitautoerreicht jeder Stalwart-Admin/adminohne das Bulwark-Admin-Passwort. Und/administ genau die Stelle, die die Overrides schreibt und den Anmeldeweg sperren kann. Meist dieselbe Person, deshalb nicht geändert;passwordverengt die Tür auf den Tresor-Inhaber. Steht am Wert und auf der Wiki-Seite.Offen geblieben
1/1 Running, 0 Restarts), also hältreadOnlyRootFilesystem: truemit genau/tmpund/app/.next/cache. Was dauerhaft offen bleibt und auf der Wiki-Seite steht: ein überflüssiger emptyDir würde so nicht auffallen.optional: true, ein Tippfehler ergibt also eine fehlende Datei und einen gesunden Pod. Nuradmin-passwordscheitert laut.config.jsonexistiert in einem CI-Lauf nie.Nebenbefund außerhalb dieses Issues
Das Wiki listet in
Chartseine Seiteconvertx, für die es im Repository kein Chart-Verzeichnis gibt. Ich habe sie nicht gelöscht — ob der Chart weg, geplant oder umgezogen ist, ist eine Entscheidung und keine Dokumentationskorrektur — aber den Zähler auf der Seite habe ich neu gemessen statt fortgeschrieben und die Abweichung dort vermerkt.Wie OIDC zwischen Bulwark, Stalwart und Keycloak wirklich läuft
Nachgetragen, weil der Plan „Keycloak als Anbieter" sagt, ohne die Kette zu benennen — und weil ein falsch gesetztes Stück beim ersten Ausrollen mit einem 401 endet, dessen Ursache man nicht sieht. Alles unten ist am Quelltext gemessen: Bulwark am Tag
1.12.0, Stalwart am Zweigmain.Es gibt zwei Topologien, und nur eine ist SSO
Stalwart kann beide Rollen spielen, und das Registry-Schema trennt sie:
OidcDirectory— Stalwart als Token-Prüfer (Resource Server). Felder:issuerUrl,requireAudience,requireScopes,claimUsername,usernameDomain,claimName,claimGroups,memberTenantId.OidcProvider— Stalwart als eigener Autorisierungsserver, mitauthCodeExpiry,refreshTokenExpiry,idTokenExpiry,userCodeExpiry(Device-Flow), eigenemsignatureKeyund Client-Registrierung.Und Bulwark wählt stillschweigend zwischen beiden.
lib/oauth/token-exchange.ts:108-112:Ist
OAUTH_ISSUER_URLleer, holt Bulwark/.well-known/oauth-authorization-servervon Stalwart und benutzt Stalwart als Aussteller — der Nutzer meldet sich dann gegen Stalwarts eigenes Verzeichnis an, nicht gegen Keycloak. Das sieht aus wie OIDC, funktioniert, und ist kein SSO.OAUTH_ISSUER_URLmuss also ausdrücklich gesetzt sein.Die Kette, die gewollt ist — ein Flow, ein Token
Belegt an drei Stellen:
app/api/auth/sso/complete/route.tslegt nach dem Callbackaccess_token,refresh_tokenundid_tokenab, in einem „Per-account refresh-token cookie slot".lib/jmap/client.ts:1194schickt es bei jeder JMAP-Anfrage mit:const headers = { …, 'Authorization': this.authHeader }.updateAccessToken) und wiederholt die Anfrage.Es gibt also keinen zweiten Flow und keine Konto-Verknüpfung. Stalwart ist keine zweite Identität, sondern ein Resource Server; die Verbindung zwischen Person und Postfach entsteht über
claimUsername— der Claim ist die Verknüpfung, es gibt keinen Zustand, der sie speichern müsste.Ein zweiter Flow entsteht nur bei einem zweiten Konto (der Slot ist je Konto), bei der Handy-Kopplung (
app/api/auth/pair/*, das Bündel trägt Token, Token-Endpunkt und dieclient_idfür die späteren Erneuerungen) und bei abgelaufenem Refresh-Token (app/api/auth/reauth/sso/complete).Zum Prüfen braucht Stalwart kein Client-Secret
Häufiger Irrtum, und die Antwort erklärt gleich, warum das Feld fehlt.
crates/directory/src/backend/oidc/lookup.rs,get_key:Stalwart holt die öffentlichen Schlüssel aus dem Discovery-Dokument (fünf Minuten Cache) und prüft damit die Signatur. Ein Token zu holen braucht
client_id+client_secret— das ist Bulwarks Seite. Ein Token zu prüfen braucht nur den öffentlichen Schlüssel.Und das fehlende Secret-Feld ist eine Folge, keine Lücke:
authenticate_jwtweistHS256,HS384undHS512ab — genau die symmetrischen Verfahren, die ein gemeinsames Geheimnis bräuchten, und deren Annahme die klassische Algorithmus-Verwechslungslücke wäre. Für opake Token gilt dasselbe ohne Secret:authenticate_opaqueruftfetch_userinfo(token), der Token authentifiziert den Aufruf selbst.Die vier Stellen, an denen es scheitert
1.
OAUTH_ISSUER_URLleer → stillschweigend Stalwart-lokale Anmeldung statt SSO.2. Die Audience.
authenticate_jwtweist ein Token ausdrücklich ab, wennrequire_audgesetzt ist und das Token gar keinaudträgt:Keycloak legt in ein Access-Token standardmäßig keine brauchbare Audience — dafür braucht der Client einen Audience-Mapper. Das ist der häufigste Fehler dieser Kette.
Und das Symptom ist irreführend: weil der JMAP-Client auf 401 automatisch erneuert und wiederholt, zeigt sich eine falsche Audience nicht als Fehlermeldung, sondern als Schleife — Anmeldung klappt, Rücksprung klappt, dann dreht Erneuern-und-Wiederholen. Das verleitet dazu, es als „ich muss mein Konto noch verbinden" zu deuten.
3.
claimUsernamemuss das Postfach treffen. Ist Keycloakspreferred_usernamenurjustin, das Postfach aberjustin@domain, braucht esusernameDomain.4. Die Redirect-URI trägt die Sprache —
https://<domain>/<locale>/auth/callback, 27 Locales, und weil der Präfixneverist, steht sie nicht in der sichtbaren URL. Upstreams eigener Helfer registriert eine URI pro Sprache. Wahrscheinlichste Ursache einer scheiternden ersten Anmeldung.Ein OIDC-Directory nimmt nur Bearer — und was das bedeutet
lib/.../oidc/lookup.rs:23-44, das Ende derauthenticate-Funktion:Benutzername und Passwort gegen ein OIDC-Directory funktionieren nicht. Daraus folgt zweierlei:
Die Konfiguration, die aussperrt, ist OIDC als
DirectoryBootstrapanstelle vonInternal. Das Schema trennt die beiden Fälle:Internalist die Grundlage und keines der hinzufügbaren Verzeichnisse. Ein OIDC-Directory tritt also neben die internen Konten — Admin-Zugang und Passwort-Anmeldung bleiben, Bearer-Token kommen hinzu. Ersetzt manInternaldagegen durch OIDC, gibt es nirgends mehr ein Passwort, auch nicht für Stalwarts eigene Oberfläche.Und es bestätigt
OAUTH_ONLY: Bulwarks Client kenntauthMode === 'basic', also Passwort gegen Stalwart. Für ein Konto im OIDC-Directory kann dieser Weg nicht tragen — er bekäme „Unsupported credentials type". Ein sichtbares Passwortformular wäre dort eine Tür, die garantiert nicht aufgeht.Pflichtschritte vor der Installation, in
cluster-configOidcDirectoryin Stalwart:issuerUrlauf Keycloak,requireAudiencepassend zum Mapper,claimUsername(plususernameDomain, falls nötig) auf das Postfach abgebildet.Internalbleibt das Bootstrap-Verzeichnis.Mit
OAUTH_ONLYund ohne diese vier kommt niemand hinein.Nicht gemessen
Wie Stalwart ein Zugangsdatum einem Verzeichnis zuordnet, wenn mehrere existieren — der Reihe nach, oder über die Zugehörigkeit des Kontos. Dass
OidcDirectoryeinmemberTenantIdträgt, deutet auf Letzteres. Die Aussage „tritt daneben" folgt aus den Enum-Formen, nicht aus gelesenem Zuordnungscode. Das ist der eine Punkt, den ich vor dem Ausrollen belegen würde.Ebenfalls offen: der ganze Pfad ist in keinem CI-Lauf durchlaufen —
config.jsonentsteht dort nie, und ein Keycloak gibt es nicht. Die wichtigste Betriebseigenschaft dieses Charts ist damit unbelegt und kann es im Install-Test nicht werden.