ekklesiaandClaude Opus 5
fa3021e49b
Ekklesia could authenticate people and pair devices but could not send a single message. Better Auth has been configured with emailAndPassword since ADR 0011 and neither of its mail hooks — sendResetPassword and emailVerification.sendVerificationEmail — was ever implemented, so email verification, password recovery, and invitations were all blocked on the same missing thing. That missing thing is a transport, not a Google Workspace integration. Email is now a host-provided infrastructure service with a provider seam, shaped exactly like object storage: feature code says "send this transactional message" and the provider owns the host, port, TLS, credentials, connection behaviour, and every transport error. No provider's hostname appears anywhere in Core, and a test asserts it. Google Workspace SMTP Relay is the expected first deployment and a compatibility target — the same variables address Microsoft 365, a transactional provider, or a local Postfix. The contract is deliberately tiny: one recipient or a small bounded list, a subject, text and/or HTML, an optional reply-to, and nothing else. There is no `from` field at all — the sender is host configuration, so no feature and no future module can choose who mail appears to come from, which is how a platform otherwise acquires an impersonation primitive. Control characters are refused rather than stripped in addresses, display names, subjects, and reply-to values; writing that rule down was not enough, because the first implementation trimmed an address before checking it and silently accepted a trailing carriage return until a test caught it. Security modes are named rather than inferred from a boolean and a port, which is genuinely ambiguous: `secure: false` on 587 means "connect in the clear and hope STARTTLS is offered". `starttls` sets requireTLS so a stripped upgrade fails the send instead of continuing in plaintext, production refuses `plaintext` outright, and certificate verification has no off switch. Credentials are optional as a pair, because a relay authorized by source IP has neither and requiring them would make the intended production arrangement unconfigurable; half a pair fails loudly. Connection, greeting, and socket timeouts are all explicit — the object-storage pass already showed what a network client on library defaults does to a request. Nothing retries: a failure after the message data has gone out is ambiguous, and retrying it turns one password-reset request into several emails, so this is a single bounded attempt and deliberately not an exactly-once promise. Email stays optional. An installation with no SMTP host is a complete deployment, nothing sends at startup, and constructing the transport opens no socket. There is no POST /api/v1/send-email and no route that touches the provider — an authenticated send endpoint is an open relay with extra steps. Modules get nothing either; services are added one at a time when something real needs one, and nothing does yet. Proven against a real in-process SMTP server rather than a mock: delivery with the host's sender on the wire, authentication and its sanitized refusal, a rejected mailbox distinguished from an outage, 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. Co-Authored-By: Claude Opus 5 <[email protected]>
80 lines
4.5 KiB
Bash
80 lines
4.5 KiB
Bash
# Local development only. Replace every credential outside a developer workstation.
|
|
|
|
# Required for a local workstation, and only ever correct there. Anything else — including an
|
|
# unset value — is validated as production, which requires certificate-verified PostgreSQL TLS
|
|
# (EKKLESIA_DATABASE_TLS_MODE defaults to verify-full) and rejects loopback/http identity origins.
|
|
# The plaintext loopback DATABASE_URL below is therefore only usable with this set.
|
|
NODE_ENV=development
|
|
|
|
POSTGRES_DB=ekklesia
|
|
POSTGRES_USER=ekklesia
|
|
POSTGRES_PASSWORD=ekklesia-development-only
|
|
POSTGRES_PORT=5432
|
|
DATABASE_URL=postgresql://ekklesia:[email protected]:5432/ekklesia
|
|
|
|
# Ekklesia's object-storage provider (ADR 0030). Absent S3_ENDPOINT means this installation has no
|
|
# object storage, which is a complete deployment: only a module that declares a logical bucket in its
|
|
# manifest is affected, and it is reported blocked rather than breaking anything. Production requires
|
|
# https, exactly as the database transport requires verified TLS.
|
|
#
|
|
# These are host infrastructure. No module ever sees them: a module names a logical bucket and the
|
|
# host resolves the binding.
|
|
S3_ACCESS_KEY=ekklesia-development
|
|
S3_SECRET_KEY=ekklesia-development-secret
|
|
S3_ENDPOINT=http://127.0.0.1:8333
|
|
S3_PORT=8333
|
|
S3_REGION=us-east-1
|
|
S3_FORCE_PATH_STYLE=true
|
|
# The origin a *browser* reaches object storage on, used only when signing temporary read URLs for
|
|
# direct delivery (ADR 0031). Leave it unset whenever S3_ENDPOINT is itself reachable from a browser,
|
|
# which is the case for this development stack: Compose publishes the service on loopback, so the
|
|
# endpoint above serves both roles and direct delivery works with no extra configuration.
|
|
#
|
|
# Set it when Core reaches storage by a name a browser cannot resolve — a Compose service name such
|
|
# as http://object-storage:8333, for instance — and browsers reach it through a public origin:
|
|
# S3_DELIVERY_ENDPOINT=https://storage.example.org
|
|
# It must be the origin the browser actually requests. An S3-compatible signature covers the request
|
|
# Host, so a URL signed for one origin cannot be rewritten to another afterwards; a reverse proxy in
|
|
# front of storage must therefore pass the original Host header through unchanged. The scheme is not
|
|
# signed, so terminating TLS at that proxy and forwarding plaintext to the service is fine.
|
|
# S3_DELIVERY_ENDPOINT=
|
|
# Namespaces every physical bucket this installation owns, so several Ekklesia-compatible deployments
|
|
# can share one S3-compatible service. Optional; defaults to "ekklesia".
|
|
S3_BUCKET_PREFIX=ekklesia
|
|
# Consumed only by the development Compose service's own bootstrap, never by Ekklesia's provider —
|
|
# physical buckets are derived from a module's manifest declaration, not configured here.
|
|
S3_BUCKET=ekklesia-development
|
|
|
|
# Ekklesia's outbound email transport (ADR 0037). Absent EKKLESIA_SMTP_HOST means this installation
|
|
# sends no email, which is a complete deployment: nothing in the platform sends any yet, and a
|
|
# future feature that needs to is told so rather than crashing.
|
|
#
|
|
# These are host infrastructure. No module ever sees them, and no feature chooses its own sender:
|
|
# the From address below is the only one this platform can send as.
|
|
#
|
|
# EKKLESIA_SMTP_HOST is a bare hostname — never a URL, a port, or a connection string.
|
|
# EKKLESIA_SMTP_SECURITY is exactly one of:
|
|
# implicit-tls TLS from the first byte, conventionally port 465
|
|
# starttls plaintext connect then a *required* upgrade, conventionally 587 (the default)
|
|
# plaintext no TLS at all; development only, and production refuses it outright
|
|
# EKKLESIA_SMTP_PORT is optional and defaults to the conventional port for the mode.
|
|
#
|
|
# Credentials are optional **as a pair**, because a relay authorized by source IP has neither.
|
|
# Setting one without the other is refused rather than silently connecting anonymously. Never commit
|
|
# a real password: this file is in every clone.
|
|
#
|
|
# A Google Workspace SMTP Relay deployment typically looks like:
|
|
# EKKLESIA_SMTP_HOST=<the relay host from Google Workspace Admin>
|
|
# EKKLESIA_SMTP_PORT=587
|
|
# EKKLESIA_SMTP_SECURITY=starttls
|
|
# [email protected]
|
|
# Whether it also needs a username and password depends on the relay's authorization setting in
|
|
# Google Workspace Admin, which varies per deployment. See docs/development/email.md.
|
|
# EKKLESIA_SMTP_HOST=
|
|
# EKKLESIA_SMTP_PORT=587
|
|
# EKKLESIA_SMTP_SECURITY=starttls
|
|
# EKKLESIA_SMTP_USERNAME=
|
|
# EKKLESIA_SMTP_PASSWORD=
|
|
# [email protected]
|
|
# EKKLESIA_SMTP_FROM_NAME=Ekklesia
|