feat(audit): Stalwart webhook ingest endpoint (Phase 2 chunk 2)

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.
This commit is contained in:
Ronni Baslund
2026-05-24 20:21:29 +02:00
parent b1d717e466
commit 7bec940e7f
5 changed files with 211 additions and 3 deletions
@@ -84,6 +84,31 @@ enable = true
[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
@@ -209,6 +209,9 @@ services:
# generates a one-time-shown password at first boot and discards it after
# initial setup.
STALWART_RECOVERY_ADMIN: admin:${STALWART_ADMIN_PASSWORD}
# Shared HMAC secret for the audit webhook POSTed to platform-api.
# config.toml references this via %{env:STALWART_WEBHOOK_SECRET}%.
STALWART_WEBHOOK_SECRET: ${STALWART_WEBHOOK_SECRET}
volumes:
- stalwart_data:/opt/stalwart
- ./configs/stalwart/config.toml:/opt/stalwart/etc/config.toml:ro
@@ -451,6 +454,9 @@ services:
STALWART_API_URL: https://mail.dezky.local
STALWART_ADMIN_USER: admin
STALWART_ADMIN_PASSWORD: ${STALWART_ADMIN_PASSWORD}
# HMAC secret Stalwart signs its webhook POSTs with; we verify on
# /ingest/stalwart/webhook. Both ends read the same env var.
STALWART_WEBHOOK_SECRET: ${STALWART_WEBHOOK_SECRET}
OCIS_API_URL: https://files.dezky.local
# JWT validation against Authentik for portal-issued access tokens.
# Issuers are comma-separated — each Authentik OAuth provider issues tokens