29 lines
2.0 KiB
Markdown
29 lines
2.0 KiB
Markdown
# Join Token Analytics & Alerting (SEC-GT-02)
|
||
|
||
## Data Sources
|
||
- Table `event_join_token_events` captures successes, failures, rate-limit hits, and uploads per join token.
|
||
- Each row records route, device id, IP, HTTP status, and context for post-incident drill downs.
|
||
- Logged automatically from `EventPublicController` for `/api/v1/events/*` and `/api/v1/gallery/*`.
|
||
|
||
- Super Admin: Event resource → “Join Link / QR” modal now summarises total successes/failures, rate-limit hits, 24h volume, and last activity timestamp per token.
|
||
- Tenant Admin: identical modal surface so operators can monitor invite health.
|
||
|
||
## Alert Thresholds (initial)
|
||
- **Rate limit spike**: >25 `token_rate_limited` entries for a token within 10 minutes → flag in monitoring (Grafana/Prometheus TODO).
|
||
- **Failure ratio**: failure_count / success_count > 0.5 over rolling hour triggers warning for support follow-up.
|
||
- **Inactivity**: tokens without access for >30 days should be reviewed; scheduled report TBD.
|
||
|
||
Rate-limiter knobs (see `.env.example`):
|
||
- `JOIN_TOKEN_FAILURE_LIMIT` / `JOIN_TOKEN_FAILURE_DECAY` — repeated invalid attempts before temporary block (default 10 tries per 5 min).
|
||
- `JOIN_TOKEN_ACCESS_LIMIT` / `JOIN_TOKEN_ACCESS_DECAY` — successful request ceiling per token/IP (default 120 req per minute).
|
||
- `JOIN_TOKEN_DOWNLOAD_LIMIT` / `JOIN_TOKEN_DOWNLOAD_DECAY` — download ceiling per token/IP (default 60 downloads per minute).
|
||
|
||
## Follow-up Tasks
|
||
1. Wire aggregated metrics into Grafana once metrics pipeline is ready (synthetic monitors pending SEC-GT-03).
|
||
2. Implement scheduled command to email tenants a weekly digest of token activity and stale tokens.
|
||
3. Consider anonymising device identifiers before long-term retention (privacy review).
|
||
|
||
## Runbook Notes
|
||
- Analytics table may grow quickly for high-traffic events; plan nightly prune job (keep 90 days).
|
||
- Use `php artisan tinker` to inspect token activity: `EventJoinTokenEvent::where('event_join_token_id', $id)->latest()->limit(20)->get()`.
|