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.

infrastructure/docker-compose/configs/stalwart/config.toml

@@ -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

infrastructure/docker-compose/docker-compose.yml

@@ -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

services/platform-api/src/ingest/action-map.ts

@@ -41,3 +41,38 @@ export function mapAuthentikAction(raw: string): MappedAction {
     }
   )
 }
+
+// Stalwart event categories (from the [webhook] subscription list). Stalwart
+// uses dot-notation event types (auth.failure, account.created, …). Some
+// Stalwart releases also emit snake_case; we normalize both before lookup
+// so we don't have two map entries per action.
+const STALWART_MAP: Record<string, MappedAction> = {
+  'auth.success':              { action: 'stalwart.auth_success',         outcome: 'success', resourceType: 'user' },
+  'auth.failure':              { action: 'stalwart.auth_failed',          outcome: 'failure', resourceType: 'user' },
+  'auth.banned':               { action: 'stalwart.auth_banned',          outcome: 'failure', resourceType: 'user' },
+  'account.created':           { action: 'stalwart.account_created',      outcome: 'success', resourceType: 'user' },
+  'account.deleted':           { action: 'stalwart.account_deleted',      outcome: 'success', resourceType: 'user' },
+  'account.password-changed':  { action: 'stalwart.password_changed',     outcome: 'success', resourceType: 'user' },
+  'message.received':          { action: 'stalwart.mail_received',        outcome: 'success', resourceType: 'system' },
+  'message.delivered':         { action: 'stalwart.mail_delivered',       outcome: 'success', resourceType: 'system' },
+  'message.failed':            { action: 'stalwart.mail_failed',          outcome: 'failure', resourceType: 'system' },
+  'message.rejected':          { action: 'stalwart.mail_rejected',        outcome: 'failure', resourceType: 'system' },
+  'policy.rejection':          { action: 'stalwart.policy_rejection',     outcome: 'failure', resourceType: 'system' },
+  'dkim.failure':              { action: 'stalwart.dkim_failure',         outcome: 'failure', resourceType: 'system' },
+  'dmarc.failure':             { action: 'stalwart.dmarc_failure',        outcome: 'failure', resourceType: 'system' },
+  'spam.detected':             { action: 'stalwart.spam_detected',        outcome: 'failure', resourceType: 'system' },
+}
+
+export function mapStalwartAction(raw: string): MappedAction {
+  // Stalwart's event types sometimes show up as 'auth-failure' (kebab) or
+  // 'auth_failure' (snake) depending on version; collapse to the canonical
+  // dotted form before lookup.
+  const normalized = raw.replace(/[-_]/g, (m) => (m === '-' ? '.' : '.'))
+  return (
+    STALWART_MAP[raw] ??
+    STALWART_MAP[normalized] ?? {
+      action: `stalwart.${raw.replace(/[.\-]/g, '_')}`,
+      outcome: 'success',
+    }
+  )
+}

services/platform-api/src/ingest/ingest.module.ts

@@ -8,10 +8,12 @@ import {
 } from '../schemas/ingest-cursor.schema.js'
 import { Tenant, TenantSchema } from '../schemas/tenant.schema.js'
 import { AuthentikIngest } from './authentik.ingest.js'
+import { StalwartWebhookController } from './stalwart-webhook.controller.js'
 
-// Workers that pull audit events from external systems (Authentik today,
-// Stalwart + OCIS later) and forward them to AuditService. Each worker owns
-// its own cursor in the ingest_cursors collection so restarts resume cleanly.
+// Workers + endpoints that bring audit events from external systems into
+// AuditService. Authentik = polling worker (pull). Stalwart = webhook
+// endpoint (push). OCIS lands next as a file-tail worker (Phase 2 chunk 3).
+// Each integration owns its own cursor / dedup story.
 @Module({
   imports: [
     AuditModule,
@@ -21,6 +23,7 @@ import { AuthentikIngest } from './authentik.ingest.js'
       { name: Tenant.name, schema: TenantSchema },
     ]),
   ],
+  controllers: [StalwartWebhookController],
   providers: [AuthentikIngest],
 })
 export class IngestModule {}

services/platform-api/src/ingest/stalwart-webhook.controller.ts

@@ -0,0 +1,139 @@
+// Stalwart calls this endpoint whenever an event in its webhook subscription
+// list fires (auth failures, account creation, policy rejections, DKIM
+// failures, etc.). We don't authenticate via JWT here — Stalwart can't carry
+// one — instead each request is HMAC-SHA-256 signed with a secret shared via
+// the STALWART_WEBHOOK_SECRET env var. Bad signatures get a 401 and a debug
+// log line; valid ones are mapped and recorded into the audit collection.
+//
+// The handler is intentionally permissive about the body shape: Stalwart's
+// webhook payload schema has shifted between minor versions, so we read the
+// raw body (for HMAC), parse JSON loosely, walk anything that looks like a
+// list of events, and let unknown event types fall through to the
+// `stalwart.<type>` catch-all in the action map. Worst case: we record raw
+// events with a generic verb instead of dropping them.
+
+import {
+  Body,
+  Controller,
+  Headers,
+  Logger,
+  Post,
+  Req,
+  UnauthorizedException,
+} from '@nestjs/common'
+import { ConfigService } from '@nestjs/config'
+import { createHmac, timingSafeEqual } from 'node:crypto'
+import { clientIp } from '../auth/client-ip.js'
+import { AuditService } from '../audit/audit.service.js'
+import { mapStalwartAction } from './action-map.js'
+
+interface StalwartEvent {
+  // Stalwart sends `id` (uuid), `createdAt` (ISO), `type` (string), and
+  // a `data` blob whose shape depends on `type`. We don't bind tightly to it
+  // — anything we use is destructured defensively below.
+  id?: string
+  createdAt?: string
+  type?: string
+  data?: Record<string, unknown>
+}
+
+interface StalwartWebhookBody {
+  events?: StalwartEvent[]
+}
+
+@Controller('ingest/stalwart')
+export class StalwartWebhookController {
+  private readonly logger = new Logger(StalwartWebhookController.name)
+  private readonly secret: string
+
+  constructor(
+    private readonly audit: AuditService,
+    config: ConfigService,
+  ) {
+    this.secret = config.getOrThrow<string>('STALWART_WEBHOOK_SECRET')
+  }
+
+  @Post('webhook')
+  async receive(
+    @Body() body: StalwartWebhookBody,
+    @Headers('x-signature') signature: string | undefined,
+    @Req() req: Parameters<typeof clientIp>[0] & { rawBody?: Buffer | string },
+  ) {
+    // Stalwart sends `X-Signature: <hex-hmac-sha256>` on every webhook. If the
+    // body parser already consumed the stream, fall back to JSON-stringifying
+    // — Stalwart computes HMAC over the JSON it serializes, which matches
+    // what Fastify reconstructs from `body`.
+    const raw =
+      req.rawBody instanceof Buffer
+        ? req.rawBody.toString('utf8')
+        : typeof req.rawBody === 'string'
+          ? req.rawBody
+          : JSON.stringify(body ?? {})
+    if (!this.verifySignature(raw, signature)) {
+      this.logger.warn(`stalwart webhook: bad signature from ${clientIp(req)}`)
+      throw new UnauthorizedException('Invalid webhook signature')
+    }
+
+    const events = Array.isArray(body?.events) ? body.events : []
+    if (!events.length) {
+      this.logger.debug('stalwart webhook: payload had no events')
+      return { received: 0 }
+    }
+
+    const senderIp = clientIp(req)
+    let written = 0
+    for (const evt of events) {
+      if (!evt.type) continue
+      await this.recordOne(evt, senderIp)
+      written++
+    }
+    this.logger.log(`stalwart webhook: received ${written} event(s)`)
+    return { received: written }
+  }
+
+  private verifySignature(rawBody: string, header: string | undefined): boolean {
+    if (!header) return false
+    // Strip a `sha256=` prefix if Stalwart includes one (matches GitHub's
+    // convention some setups copy).
+    const provided = header.replace(/^sha256=/i, '').trim()
+    const expected = createHmac('sha256', this.secret).update(rawBody).digest('hex')
+    if (provided.length !== expected.length) return false
+    return timingSafeEqual(Buffer.from(provided, 'hex'), Buffer.from(expected, 'hex'))
+  }
+
+  private async recordOne(evt: StalwartEvent, senderIp: string | undefined): Promise<void> {
+    const mapped = mapStalwartAction(evt.type ?? 'unknown')
+    const data = evt.data ?? {}
+    const at = evt.createdAt ? new Date(evt.createdAt) : new Date()
+
+    // Common Stalwart data fields — present on most categories, missing on
+    // others. Pull what we can; let the rest land in metadata.
+    const actorEmail = pickString(data, ['email', 'username', 'account', 'remote-email', 'from'])
+    const tenantSlug = pickString(data, ['tenant', 'domain'])
+    const targetName = pickString(data, ['account', 'email', 'address', 'to', 'message-id'])
+    const ip = pickString(data, ['ip', 'remote-ip', 'source-ip']) ?? senderIp
+
+    await this.audit.record(
+      {
+        action: mapped.action,
+        outcome: mapped.outcome,
+        resourceType: mapped.resourceType,
+        resourceName: targetName ?? evt.type,
+        tenantSlug,
+        source: 'stalwart',
+        externalId: evt.id,
+        at,
+        metadata: { rawType: evt.type, data },
+      },
+      { email: actorEmail, ip },
+    )
+  }
+}
+
+function pickString(obj: Record<string, unknown>, keys: string[]): string | undefined {
+  for (const k of keys) {
+    const v = obj[k]
+    if (typeof v === 'string' && v.length) return v
+  }
+  return undefined
+}