# Notifications Hardening Guide

Last updated: 2025-11-25 (Docs Tasks Md.V · DOCS-NOTIFY-40-001)

## Threat model
- Tenant data isolation breaches (cross-tenant deliveries).
- Channel compromise (webhook leaks, OAuth token theft).
- Message tampering or replay.
- Flooding / notification storms.

## Controls
- **Tenant isolation**: every rule/channel/template includes `tenant`; APIs enforce `X-Stella-Tenant`. Mongo collections are filtered by tenant with indexes on `(tenant, id)`.
- **Secrets**: channels reference Authority `secretRef`; secrets never stored in Notify DB. Rotate via Authority and `:refresh-secret`.
- **Outbound allowlist**: restrict hosts/ports per tenant; defaults block public internet in air-gapped kits.
- **Signing**: webhook deliveries include `X-Stella-Signature` HMAC-SHA256 over body+nonce; receivers must reject stale timestamps (>5m) and verify signature.
- **Replay protection**: delivery ledger de-dupes on `(channel, bodyHash)` for 24h; escalation tokens are single-use DSSE-signed.
- **Rate limits/throttles**: per-rule and per-channel throttles; quiet hours for non-critical traffic.
- **Templates sandboxed**: no file/network access; helpers are pure and deterministic.
- **Logging/PII**: payloads redacted based on rule labels; logs avoid full body, store hashes instead.
- **Audit**: all admin actions (create/update/delete channel or rule) logged with actor, trace id, and diff.

## Deployment checklist
- [ ] Authority scopes `notify.viewer|operator|admin` configured; service accounts least-privilege.
- [ ] HTTPS everywhere; TLS 1.2+; HSTS on WebService front-door.
- [ ] Redis protected by auth and network policy; Mongo TLS + auth enabled.
- [ ] Outbound allowlists defined per environment; no wildcard `*`.
- [ ] Webhook receivers validate signatures and enforce host/IP allowlists.

## Incident playbook (channel compromise)
1) Disable affected channel via `PATCH /channels/{id}` (`enabled=false`).
2) Rotate secret in Authority; refresh channel secret.
3) Search ledger for deliveries to compromised endpoint and notify tenants if required.
4) Re-enable with new endpoint/secret after validation.

## Offline/air-gap notes
- Ship channel manifests and secrets via sealed bundles; keep hash manifest with signed checksum.
- Disable any channel type not supported in the enclave (e.g., external Slack) and use in-app or file-drop channels instead.