# Notifications and audit

## Notification channels

Administrators configure channels entirely in the UI:

- SMTP email;
- generic HTTPS webhook;
- Discord webhook.

Channel secrets are encrypted and write-only. A test action sends a clearly marked test message and reports a redacted result.

The main application reads the 32-byte authenticated-encryption key from
`DOGAMA_MASTER_KEY_FILE`. Without that external key, audit remains available
but channel configuration and delivery are disabled. Generic and Discord
webhooks require HTTPS; resolution, redirects and every resolved address reject
loopback, private, link-local, multicast and unspecified networks. Generic
webhooks carry `X-DoGaMa-Event-ID`, `X-DoGaMa-Timestamp` and, when a signing
secret is configured, an HMAC-SHA256 `X-DoGaMa-Signature`.

## Events and filtering

Suggested configurable events:

- backup, restore or import failed/completed;
- update failed/completed;
- instance entered error/degraded or crash-loop protection;
- low/critical disk space;
- installation request submitted/approved/refused;
- module disabled after repeated failures;
- security-sensitive repeated authentication failure.

Default notifications favor failures and required action. Normal health polls and metric refreshes never notify.

Deliveries are queued after the originating transaction, use bounded exponential retry and cannot fail the lifecycle operation. Payloads contain display names and operation IDs, not secrets, raw credentials or large logs. Generic webhook requests are signed and include a timestamp and event ID for receiver deduplication.

Webhook URL validation blocks loopback, private/link-local/metadata destinations by default, validates every redirect and resists DNS rebinding. An explicit future private-webhook feature would need a separately reviewed allowlist.

## Light audit trail

The audit trail answers: who performed an important action, on what instance, when and with what outcome. It is not technical logging or monitoring.

Audit:

- successful login and repeated/blocked login failures;
- instance create/adopt/delete and manual start/stop/restart;
- configuration, resource, port, storage or module binding changes;
- manual backup, restore, import and export;
- update and rollback;
- user, membership and permission changes;
- kick/ban/unban and announcement actions;
- catalog/template/module trust or activation changes;
- notification and security-policy changes.

Do not audit:

- page views;
- metrics/player/status polling;
- normal readiness probes;
- each ordinary scheduled-job tick;
- successful recurring notification delivery unless operationally needed.

Entries are compact and use allow-listed structured summaries. Player IDs may be hashed or minimized where full identifiers are unnecessary. Never include secret values, HTTP authorization headers, imported content or module raw responses.

## Retention

Audit retention defaults to 30 days and is globally administrator-configurable. An optional maximum count prevents unbounded growth. Purge runs daily and records one aggregate audit event, not an event per deleted row. Unlimited retention requires an explicit warning and displays database usage. Administrators may manually purge by date with confirmation.

The V1 bounds are 0–3650 retention days and 0–1,000,000 entries; zero means
unlimited. The viewer returns at most 200 entries per request and supports time,
actor, instance, action and outcome filters through the administration API.

Technical application logs go to stdout/stderr and use Docker log rotation. Their level and retention are separate from SQLite audit policy.