# alerts

## Purpose

Delivers user-facing notifications for events the rule engine has flagged. Provides Web Push (VAPID) delivery to registered browsers and phones, PIN hashing/verification for arm/disarm flows, and a smart-profile matcher that selects recipients based on household state and time-of-day windows. Every alert attempt is logged through `vigilar.alerts` logger; the main supervisor attaches a dedicated syslog handler to that logger so alerts leave an OS-level audit trail.

## Key files

- `vigilar/alerts/sender.py` — `send_alert`, `build_notification`, VAPID Web Push dispatcher; reads `push_subscriptions` and writes `alert_log`
- `vigilar/alerts/profiles.py` — smart alert profile matcher (household state + time windows)
- `vigilar/alerts/pin.py` — PBKDF2-SHA256 PIN hashing and constant-time verification

## MQTT topics

**Subscribes:** none directly. `alerts` is not a standalone subsystem process; it is invoked synchronously from the events processor when a rule action fires.
**Publishes:** No MQTT publishers found at time of writing. The events processor publishes `vigilar/system/alert` on behalf of alert actions.

## Database tables

- `alert_log` — one row per delivery attempt (channel + status + error)
- `push_subscriptions` — VAPID Web Push subscriptions, read to fan out a notification; stale entries are removed via `delete_push_subscription`

## Depends on

- `events` — `send_alert` is called from `EventProcessor._execute_action` for `alert_all` / `push_and_record`
- `storage` — reads `push_subscriptions`, writes `alert_log`

## Consumed by

- Phones and browsers — receive Web Push notifications via VAPID
- `web` — the `system` blueprint manages push subscription registration and PIN verification

## Notes

The `vigilar.alerts` logger gets a syslog handler installed by the supervisor (`vigilar/main.py`) so that every alert emission is mirrored into the host's syslog as an out-of-band audit trail, independent of SQLite. PIN verification uses `hmac.compare_digest` to avoid timing leaks. The smart-profile matcher honours `household_state` and HH:MM time windows (including windows that wrap past midnight).