ekklesiaandClaude Opus 5
2b4f0afb72
`pnpm doctor` and `startApi` each read their own subset of the same environment variables, and the subsets had drifted. Doctor never read `S3_*` or module secrets at all, so a correctly configured installation was told its object storage was "not configured" and every module requiring a bucket or a secret was reported blocked -- while the runtime, from the identical environment, bound those buckets and ran the modules. Both executables now map the environment through one `loadHostConfiguration(env)` in Core, which takes the environment as an argument and never reads `process.env` itself. Validation stays with the existing per-domain validators, so each caller keeps its own failure behaviour: startup refuses a rejected value, Doctor reports it as a sanitized code. Doctor's storage option becomes raw input like its mail option, so a half-configured provider is reported as a blocking configuration failure instead of throwing before a report exists. The outbound-email check -- computed, counted toward the result, but absent from every rendered section -- is now printed, and the rendered set is asserted against a real report so a future check cannot go missing the same way. Co-Authored-By: Claude Opus 5 <[email protected]>
6.7 KiB
Outbound email
Ekklesia can send transactional email through a host-configured SMTP transport (ADR 0037).
Nothing in the platform sends email yet. This pass added the transport; email verification, password reset, and invitations are Phase 7C Pass 2. An installation with no SMTP configured is a complete, valid deployment — the platform starts and every existing feature works.
Configuring a relay
| variable | meaning |
|---|---|
EKKLESIA_SMTP_HOST |
A bare hostname or IP. Absent means this installation sends no email. Never a URL, port, or connection string. |
EKKLESIA_SMTP_PORT |
Optional; defaults to the conventional port for the security mode. |
EKKLESIA_SMTP_SECURITY |
implicit-tls, starttls (default), or plaintext. |
EKKLESIA_SMTP_USERNAME / EKKLESIA_SMTP_PASSWORD |
Optional as a pair. Half a pair is refused. |
EKKLESIA_SMTP_FROM_ADDRESS |
Required once a host is set. The only address this platform can send as. |
EKKLESIA_SMTP_FROM_NAME |
Optional display name. |
Security modes are explicit
A boolean plus a port is ambiguous — "connect in the clear and hope STARTTLS is offered" is a plaintext session waiting to happen. Naming the mode removes the ambiguity:
implicit-tls— TLS from the first byte, conventionally port 465.starttls— plaintext connect then a required upgrade, conventionally 587 (or 25 on a relay). If the server does not offer STARTTLS the send fails rather than continuing in the clear. This is the default and what most relays expect.plaintext— no TLS. Development and trusted local relays only; production refuses it.
Certificate verification is always on and there is no setting that turns it off.
Google Workspace SMTP Relay
The expected first production deployment, and a compatibility target rather than a dependency — no provider hostname appears anywhere in Ekklesia's code.
EKKLESIA_SMTP_HOST=<the relay host shown in Google Workspace Admin>
EKKLESIA_SMTP_PORT=587
EKKLESIA_SMTP_SECURITY=starttls
EKKLESIA_SMTP_FROM_ADDRESS=[email protected]
EKKLESIA_SMTP_FROM_NAME=Ekklesia
Whether that relay also needs EKKLESIA_SMTP_USERNAME and EKKLESIA_SMTP_PASSWORD depends entirely
on how the relay is authorized in Google Workspace Admin, which varies per deployment. Google
supports authorizing by source IP range, by SMTP authentication, or both, and the setting also
controls which envelope senders are accepted.
A Google relay does not accept mail anonymously from an arbitrary internet host. If the deployment relies on IP authorization, the server's egress address has to be registered, and a change of hosting provider or NAT address will break sending until it is updated.
The same variables address Microsoft 365, a transactional provider's SMTP endpoint, a local Postfix, or anything else that speaks the protocol. Switching between them is configuration, not code.
The sender is host-owned
There is deliberately no way for feature code to choose a sender. A message has no from field
at all; EKKLESIA_SMTP_FROM_ADDRESS is the only address this platform can send as. Letting features
pick a sender is how a platform acquires an impersonation primitive and ruins its own domain
reputation.
Deliverability is a deployment concern this repository cannot verify for you: publish SPF, DKIM, and DMARC records for the sending domain, and make sure the relay is authorized to send as that address.
Secrets
EKKLESIA_SMTP_PASSWORD is a deployment secret, handled like every other one
(ADR 0029): never stored in
PostgreSQL, never routed through module configuration, never returned by any route, never printed by
Doctor, and never included in an error. .env.example documents the variable and deliberately
carries no value.
What the transport does and does not promise
- One bounded attempt, no retry. A failure after the message data has gone out is ambiguous —
the server may have accepted it and only the acknowledgement was lost — so retrying would turn one
password-reset request into several emails.
sendresolving means the next hop accepted responsibility, not that anyone received anything. There is no outbox and no exactly-once guarantee. - Bounded connection, greeting, and socket timeouts. A silent server returns a structured
MAIL_PROVIDER_UNAVAILABLErather than hanging. - A tiny contract. One recipient or a small bounded list, a subject, text and/or HTML, and an optional reply-to. No attachments, headers, CC, BCC, templates, or bulk sending.
- Header injection is refused. Carriage returns, line feeds, and other control characters in addresses, display names, subjects, and reply-to values are rejected rather than stripped.
Diagnostics
pnpm doctor reports outbound-email.configuration as one of:
- skipped — no host configured. A complete deployment.
- pass — connected, and authenticated where credentials are set. It sent nothing.
- warning — configured but did not answer. A warning rather than a failure, because nothing depends on mail yet and some relays decline a connection that sends no message.
- failure — the settings are structurally invalid, reported as a sanitized code with no credential.
A successful probe proves the relay accepts this deployment. It does not prove a message would reach an inbox — that depends on the relay's authorization policy and the domain's DNS records.
Doctor reads the EKKLESIA_SMTP_* values through the same loadHostConfiguration the API
executable uses, so the relay it reports on is the relay the runtime would use. The check is
rendered in Doctor's own Outbound email section.
Logging
Transactional email carries verification links, reset links, and personal data. The transport logs nothing. Features built on it should log at most that a send was attempted, the provider's message id, and an error category — never a body, a subject, or a verification or reset link.
Testing
core/tests/mail-smtp.integration.test.ts runs a real in-process SMTP server (smtp-server) and
proves message delivery, the host-owned sender on the wire, authentication and its refusal, a
rejected mailbox, a refused connection, a silent server hitting its deadline, and a starttls
transport refusing to continue when the upgrade is not offered.
No test sends real email and no live credential exists in this repository or in CI.
Next
Phase 7C Pass 2 wires Better Auth's sendResetPassword and emailVerification.sendVerificationEmail
hooks — both currently unimplemented — to this transport. See
Identity.