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.
Brings up Dezky's local development environment end-to-end:
Infrastructure (docker-compose):
- Traefik v3.7 reverse proxy with mkcert TLS (v3.2 couldn't speak Docker API 1.54)
- Postgres + Mongo + Redis with healthchecks and init script for per-service users
- Authentik 2025.10 (server + worker) as OIDC IdP
- Stalwart v0.16 mail server (image renamed from stalwartlabs/mail-server)
- OCIS 7.0 with PROXY_TLS=false and OCIS_CONFIG_DIR=/etc/ocis so init writes
where the server reads
- Collabora office, plus the portal + provisioning service stubs
- Docker network aliases on Traefik so containers resolve auth.dezky.local etc.
through the network (not host /etc/hosts)
- Docker socket mount parameterized for macOS Docker Desktop symlink path
Authentik provisioning (done via API after stack boot):
- ocis-provider (public client) + OCIS Files application
- dezky-portal provider (confidential) + Dezky Portal application
- Admin API token bound to akadmin manually since 2025.10's
AUTHENTIK_BOOTSTRAP_TOKEN env var doesn't auto-materialize a token row
Portal (apps/portal):
- Nuxt 3 with nuxt-oidc-auth 1.0.0-beta.11 against generic 'oidc' preset
- Global auth middleware; login at /auth/oidc/login redirects to Authentik
- Visual implementation of Claude Design 'Auth' canvas: AuthShell, NodeMark,
Auth* sub-components, design tokens as CSS custom properties
- Pages: auth/login, auth/expired, auth/disabled, index (post-login landing)
- mkcert root CA mounted into the portal so Node fetch trusts Authentik's
self-signed cert (NODE_EXTRA_CA_CERTS) — dev only
Docs:
- AUTHENTIK-SETUP.md updated with manual token bind + portal provider scripted
alternative
- NEXT-STEPS.md: Phase 1 and Phase 2 marked done with file locations and
dev-mode caveats
Dev-mode shortcuts that need to be revisited before prod:
- skipAccessTokenParsing on the OIDC config
- NODE_EXTRA_CA_CERTS mkcert mount
- Bootstrap password still the generated value in .env
- Authentik admin token (dezky-bootstrap-token) is non-expiring
Ronni Baslund