Ronni Baslund
7bec940e7f
Push-based ingest for mail-server events. Adds POST /ingest/stalwart/webhook
with HMAC-SHA-256 verification, maps each event into the audit collection
under source='stalwart'.
services/platform-api/src/ingest/stalwart-webhook.controller.ts:
- Public endpoint (no JwtAuthGuard — Stalwart can't carry a JWT). Each
request is signed with STALWART_WEBHOOK_SECRET; bad signature → 401
via timingSafeEqual.
- Body: { events: [{ id, type, createdAt, data }, ... ] }. Defensive
parsing because Stalwart's payload shape has shifted across v0.16
minors — we walk what looks like a list of events and let unknown
types fall through to mapStalwartAction's catch-all.
- Per-event recordOne: action via mapStalwartAction(), actor from
data.email/account/username, IP from data.ip or X-Forwarded-For,
targetName from data.account/email/address/to, full payload kept
in metadata. externalId = evt.id so the (source, externalId)
unique index dedups re-deliveries.
action-map.ts: 14 known Stalwart event types →
stalwart.{auth_failed, auth_success, auth_banned, account_created,
account_deleted, password_changed, mail_received, mail_delivered,
mail_failed, mail_rejected, policy_rejection, dkim_failure,
dmarc_failure, spam_detected}. Snake/kebab forms normalized.
infrastructure/docker-compose:
- .env: new STALWART_WEBHOOK_SECRET shared by both containers
- docker-compose.yml: env var injected into both stalwart + platform-api
- configs/stalwart/config.toml: [webhook."audit-ingest"] block
pointing at platform-api:3001/ingest/stalwart/webhook with
signature-key = $env{STALWART_WEBHOOK_SECRET} and the 11 event
types we map.
Verified end-to-end on the receiver:
- Manual HMAC-signed POST → 200 {"received":2}, both events in Mongo
with the right action verbs (stalwart.auth_failed, stalwart.account_created),
actor/IP/externalId populated.
- Replay of the same payload → still {"received":1} but Mongo count
stays the same (dedup index works).
- X-Signature: deadbeef → 401, no row written.
Known unknown: I couldn't fully confirm Stalwart v0.16 honors the TOML
webhook config without trial-and-error on the auth event types and key
name (config.toml uses signature-key; some Stalwart builds want plain
'key'). The receiver is correct regardless — when Stalwart fires, the
events will land. If they don't, the easiest fix is to configure the
webhook from Stalwart's web admin UI at https://mail.dezky.local
instead of via TOML.
117 lines
6.3 KiB
TOML
117 lines
6.3 KiB
TOML
# Stalwart Mail Server — Local Development Configuration
|
|
#
|
|
# This is a minimal config for local dev. Production config will have:
|
|
# - Real TLS certs (Let's Encrypt)
|
|
# - DKIM signing with real keys
|
|
# - SPF/DMARC enforcement
|
|
# - Rspamd integration
|
|
# - Hetzner Object Storage for blob storage
|
|
#
|
|
# Reference: https://stalw.art/docs
|
|
|
|
[server]
|
|
hostname = "mail.dezky.local"
|
|
|
|
[server.listener]
|
|
"smtp" = { bind = "[::]:25", protocol = "smtp" }
|
|
"submission" = { bind = "[::]:587", protocol = "smtp", tls.implicit = false }
|
|
"submissions" = { bind = "[::]:465", protocol = "smtp", tls.implicit = true }
|
|
"imap" = { bind = "[::]:143", protocol = "imap", tls.implicit = false }
|
|
"imaps" = { bind = "[::]:993", protocol = "imap", tls.implicit = true }
|
|
"sieve" = { bind = "[::]:4190", protocol = "managesieve" }
|
|
"http" = { bind = "[::]:8080", protocol = "http" }
|
|
|
|
# ─────────────────────────────────────────────────────────────────
|
|
# Storage — RocksDB embedded for local dev (single-binary simplicity)
|
|
# Production will use PostgreSQL backend
|
|
# ─────────────────────────────────────────────────────────────────
|
|
[store."rocksdb"]
|
|
type = "rocksdb"
|
|
path = "/opt/stalwart/data"
|
|
compression = "lz4"
|
|
|
|
[storage]
|
|
data = "rocksdb"
|
|
fts = "rocksdb"
|
|
blob = "rocksdb"
|
|
lookup = "rocksdb"
|
|
directory = "internal"
|
|
|
|
# ─────────────────────────────────────────────────────────────────
|
|
# Directory — internal user store for local dev
|
|
# Production will wire OIDC to Authentik
|
|
# ─────────────────────────────────────────────────────────────────
|
|
[directory."internal"]
|
|
type = "internal"
|
|
store = "rocksdb"
|
|
|
|
# ─────────────────────────────────────────────────────────────────
|
|
# TLS — Self-signed in dev, Traefik terminates the public-facing HTTPS
|
|
# ─────────────────────────────────────────────────────────────────
|
|
[certificate."default"]
|
|
cert = "%{file:/opt/stalwart/etc/tls/cert.pem}%"
|
|
private-key = "%{file:/opt/stalwart/etc/tls/key.pem}%"
|
|
default = true
|
|
|
|
# ─────────────────────────────────────────────────────────────────
|
|
# Authentication for local development
|
|
# ─────────────────────────────────────────────────────────────────
|
|
[authentication]
|
|
fallback-admin.user = "admin"
|
|
fallback-admin.secret = "$env{STALWART_ADMIN_PASSWORD}"
|
|
|
|
# ─────────────────────────────────────────────────────────────────
|
|
# Resolver — use the Docker DNS for local dev
|
|
# ─────────────────────────────────────────────────────────────────
|
|
[resolver]
|
|
type = "system"
|
|
preserve-intermediates = true
|
|
concurrency = 2
|
|
|
|
# ─────────────────────────────────────────────────────────────────
|
|
# Logging
|
|
# ─────────────────────────────────────────────────────────────────
|
|
[tracer."stdout"]
|
|
type = "stdout"
|
|
level = "info"
|
|
ansi = false
|
|
enable = true
|
|
|
|
# ─────────────────────────────────────────────────────────────────
|
|
# Spam filtering — disabled in dev (no Rspamd configured)
|
|
# Production: integrate Rspamd via milter
|
|
# ─────────────────────────────────────────────────────────────────
|
|
[spam-filter]
|
|
enable = false
|
|
|
|
# ─────────────────────────────────────────────────────────────────
|
|
# Audit webhook — push security-relevant events to platform-api so the
|
|
# operator's /audit timeline reflects mail-server activity (failed auth,
|
|
# new accounts, policy/DKIM rejections). Signed via HMAC-SHA-256 with
|
|
# STALWART_WEBHOOK_SECRET (a shared env between this container and the
|
|
# platform-api container).
|
|
# ─────────────────────────────────────────────────────────────────
|
|
[webhook."audit-ingest"]
|
|
url = "http://platform-api:3001/ingest/stalwart/webhook"
|
|
signature-key = "$env{STALWART_WEBHOOK_SECRET}"
|
|
events = [
|
|
"auth.success",
|
|
"auth.failure",
|
|
"auth.banned",
|
|
"account.created",
|
|
"account.deleted",
|
|
"account.password-changed",
|
|
"message.rejected",
|
|
"policy.rejection",
|
|
"dkim.failure",
|
|
"dmarc.failure",
|
|
"spam.detected",
|
|
]
|
|
throttle = "1s"
|
|
|
|
# ─────────────────────────────────────────────────────────────────
|
|
# Local development hint:
|
|
# After first boot, create your first mailbox by visiting
|
|
# https://mail.dezky.local and using admin credentials.
|
|
# ─────────────────────────────────────────────────────────────────
|