# Live Monitoring — privacy & access

Admin module for presence, activity paths, optional geolocation trails, random screenshots, and live screen frames of **logged-in** users.

> **Not a compliance product.** Buyers are responsible for workplace monitoring law, employee notice, and retention in their jurisdiction.

---

## Access control (confirmed)

| Surface | Who | Gate |
|---------|-----|------|
| `/app/live-monitoring/*` | **Admin role only** (`role.admin`) | Requires `LIVE_MONITORING_ENABLED=true` **and** policy acceptance in Settings |
| `/app/live-monitoring/settings` | Admin | Env flag only (so admins can accept/revoke policy) |
| `/me/monitor/*` (agent) | Any authenticated user (own activity/captures only) | Env + policy; **404** when either is off |
| Apps launcher | Hidden when env disabled (`requires_config` + `admin_only`) | Module registry |

Staff roles (sales, HR, support, portal) **cannot** open the dashboard (403).

---

## Opt-in workflow (required)

Live Monitoring stays **off** on a fresh install. To enable:

1. Set `LIVE_MONITORING_ENABLED=true` in `.env`, then `php artisan config:clear`
2. Sign in as **admin** → open **Live Monitoring → Settings** (or `/app/live-monitoring/settings`)
3. Read the privacy notice and check **Accept policy & activate monitoring**
4. Captures, location trails, and agent routes activate only after step 3

To disable again: revoke policy in Settings, and/or set `LIVE_MONITORING_ENABLED=false`.

Public demos must keep the env flag **`false`** (never accept policy on a shared preview host).

---

## Privacy disclosure (buyers)

When enabled, Live Monitoring may capture:

- Current app / path / title and activity timestamps  
- Approximate location (when the browser reports it **and** the user consents)  
- Screenshots and live JPEG frames during an admin-started session  

**Requirements before enabling in production:**

1. Lawful basis and written company policy for workplace monitoring  
2. Clear notice to monitored staff where required  
3. Admin acceptance of the policy checkbox in **Live Monitoring → Settings**  
4. Limit retention (`capture_retention_days` + `live-monitoring:purge-captures` schedule)  
5. Keep screenshots off public demo hosts  

**Geolocation:** Login never captures GPS. Approximate location is requested only after Live Monitoring is fully active (`LIVE_MONITORING_ENABLED=true` **and** policy accepted) **and** the signed-in user clicks **Allow location** on the consent banner (or has previously consented). `/me/location` returns 404 when monitoring is inactive, and 403 without user consent.

Admins see a **Privacy & legal notice** banner on every Live Monitoring screen (text from `config/live_monitoring.php` → `policy_notice`).

Sensitive paths (password, payroll, bank, etc.) skip screenshot capture — see `sensitive_path_patterns` in config / Settings UI.

---

## Environment

```env
# false = module unavailable (404 + hidden from apps). true = unlock Settings so an admin can accept policy.
LIVE_MONITORING_ENABLED=false
```

| Host type | Recommended |
|-----------|-------------|
| Buyer production (with policy) | `true` + accept policy in Settings |
| Public Codester demo | **`false`** (required — see [DEMO_HOST.md](DEMO_HOST.md)) |
| Fresh install / local trial | **`false`** (product default) |

After changing: `php artisan config:clear` (or `config:cache` in production).

---

## Related

- [INSTALL.md](INSTALL.md) — install checklist  
- [CONFIGURATION.md](CONFIGURATION.md) — env table  
- [ROLES.md](ROLES.md) — admin vs staff  
- [DEMO_HOST.md](DEMO_HOST.md) — public preview must disable monitoring