# 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()`.