Mark-VIII/docs/specs/2026-08-10-pager-webui-design.md

# Pager WebUI — Design Spec (v1)

- **Date:** 2026-08-10
- **Status:** Approved (pending written-spec review)
- **Owner:** Hak5 WiFi Pineapple Pager expansion project

## 1. Goal

Build a Mark VII-style web management UI that runs **on the WiFi Pineapple Pager**
itself, with core-parity featureset (Dashboard, PineAP, Recon, Handshakes/Loot,
Payloads, Logs, Settings, and a bottom-docked terminal), packaged as a
Payload-Portal-installable payload and deployed over SSH/SCP.

The UI is reached at `http://172.16.52.1:8080/` (verified free on the device).

## 2. Verified Research Basis (live devices)

### Pager (172.16.52.1)
- MediaTek MT76x8 SoC, OpenWRT-based `Pineapple Pager 24.10.1`
  (`ramips/mt76x8`, `mipsel_24kc`, Linux 6.6.86).
- Full root SSH (`root` + device password). `opkg` available.
- Persistent 4GB MMC: `/root` -> `/mmc/root`; payloads live under
  `/root/payloads/`, loot under `/root/loot/`.
- Tools present: `python3` (3.11.14), `sqlite3`, `iwinfo`, `hostapd_cli`,
  `ubus`, `uci`, `curl`, `nc`, `wget`.
- Firmware is U-Boot **signed** — firmware modification is out of scope; no
  stock files are touched.

### Hak5 daemon (`/pineapple/pineapple`, Go)
- HTTP API on `:1471` and an unauthenticated Unix socket `/tmp/api.sock`
  serving the same router.
- Auth: `POST /api/login` (`{"username":"root","password":...}`) returns
  `{"token": ...}`. Requests authorize with
  `Authorization: Bearer <token>` or the `AUTH_<serverid>` cookie
  (serverid from `/api/api_ping`, e.g. `001337AEE050`).
- Existing API used by the stock Virtual Pager:
  `api_ping`, `login`, `payloads/portal/{index,refresh,updates,<key>/install,<key>/remove}`,
  `loot/archive`, `loot/zip`, `files/zip/root/loot/handshakes`,
  `terminal/openWs` (WS), `pager/input/keys.ws` (WS), `pager/display/screen.ws` (WS).
- Terminal WS `/api/terminal/openWs`: plain-text WebSocket (keystrokes in,
  output out). Requires the `AUTH_*` cookie (verified 401 without, 101 with).
  Accepts cross-origin handshakes. Cookies are host-scoped and **port-agnostic**,
  and the `:8080` page and `:1471` host are the same site, so a cookie set for
  host `172.16.52.1` is sent on the WS handshake from the `:8080` page. The
  docked terminal therefore connects **directly** to the daemon WS; a
  server-side relay is the documented fallback.

### Control channel (payload interface)
- `/usr/bin/hak5cmd` (C++, protobuf client to the daemon). 49 symlinks provide
  every PineAP operation, e.g.:
  `PINEAPPLE_SSID_POOL_{ADD,ADD_FILE,START,STOP,LIST,DELETE,CLEAR,COLLECT_START,COLLECT_STOP}`,
  `PINEAPPLE_NETWORK_FILTER_{MODE,ADD,ADD_FILE,DELETE,LIST,CLEAR}`,
  `PINEAPPLE_DEVICE_FILTER_{MODE,ADD,ADD_FILE,DELETE,LIST,CLEAR}`,
  `PINEAPPLE_MIMIC_{ENABLE,DISABLE}`,
  `PINEAPPLE_DEAUTH_CLIENT`, `PINEAPPLE_EXAMINE_{BSSID,CHANNEL,RESET}`,
  `PINEAPPLE_HOPPING_{START,STOP}`, `PINEAPPLE_SET_BANDS`,
  `PINEAPPLE_RECON_NEW`, `PINEAPPLE_LOOT_ARCHIVE`.
- Verified: commands run from CLI over SSH (read-only ones confirmed).

### Recon data
- SQLite `/root/recon/recon.db`: tables `scan`, `wifi_device`, `ssid`,
  `handshake`, `hostap_chalresp`, `hostap_basic`, `hostap_client`,
  `hostap_handshake`.

### PineAP config
- UCI file `/etc/config/pineapd` (sections: `pineapd`, `hostapd`,
  `ssidpool`, `ssid_filter`, `mac_filter`, `interface wlan0mon/wlan1mon/wlan2mon`).
- Reload trigger exists (`/etc/init.d/pineapd reload`, `pineap_reload`).

### Precedents (payloads already on device)
- `nautilus` (`user/remote_access/nautilus`): web UI payload with init script
  (`nautilus.init`, START=99, procd), python3 proxy, foreground/background run
  modes, `PAYLOAD_GET_CONFIG` persistence.
- `virtual_pager_enhancer`: uhttpd+CGI on port 4040 (init script pattern).

### Mark VII blueprint
- 113 `/api/*` endpoints extracted from its Angular bundle:
  dashboard, `pineap/*` (clients, kick, deauth, filters, handshakes, settings,
  ssids, summary), `recon/*` (scans, start/stop/status, tags), logging, settings/
  networking, modules, device, terminal (xterm.js bottom-docked panel).

## 3. Repo Layout

Dev workspace: `C:\Users\root\Documents\Pineapple\pager-webui\`

```
pager-webui\
├── payload\user\general\pager-webui\
│   ├── _hak5_manifest.json
│   ├── payload.sh                      # run-mode installer (nautilus pattern)
│   ├── pagerwebui.init                 # OpenWRT init template (START=99, procd, respawn)
│   ├── server.py                       # Python3 stdlib HTTP+WS+JSON API backend (:8080)
│   └── www\                            # vanilla JS SPA + xterm.js bundle
├── scripts\
│   ├── deploy.ps1                      # build portal zip + SCP/install to Pager
│   └── dev.ps1                         # local dev server w/ proxy to Pager
├── docs\specs\                         # design specs
└── README.md
```

## 4. Packaging & Deployment

- **Payload format** mirrors `nautilus` exactly: self-contained directory
  `user/general/pager-webui/` with `payload.sh`, `pagerwebui.init`, `server.py`,
  `www/`.
- **Sideload (v1 delivery):** `scripts/deploy.ps1` builds a portal-format zip
  (`payload-<b64>.zip`) and installs it to
  `/root/payloads/user/general/pager-webui/` on the Pager over SCP. The payload
  then appears in the on-device Payloads menu and the Virtual Pager's portal
  view — installable like any Payload Portal payload.
- **Future portal distribution:** packaging is drop-in ready for a PR to
  `hak5/wifipineapplepager-payloads`; the build script generates the manifest
  `time` / `last_hash` / `zip` fields.

### `payload.sh` run flow (nautilus pattern)

1. If `/etc/init.d/pagerwebui` exists and `running`:
   show URL `http://172.16.52.1:8080/`, offer
   `CONFIRMATION_DIALOG "Stop service?"`; on confirm -> `stop`, `disable`,
   remove init script; exit.
2. Read `PAYLOAD_GET_CONFIG pager_webui auto_mode` / `run_mode`. If
   `auto_mode=true`, skip prompt (background if `run_mode=background`, else
   foreground).
3. Else `CONFIRMATION_DIALOG "Run as background service?"`:
   - **Yes -> background:** `cp pagerwebui.init /etc/init.d/pagerwebui`,
     `chmod +x`, `enable`, `start` (procd runs `python3 server.py`, respawns on
     crash). Boot-persistent via rc.d symlinks.
   - **No -> foreground:** spawn `python3 server.py` with
     `/tmp/pagerwebui.pid`, show URL, loop `WAIT_FOR_INPUT` until B/Escape,
     `trap cleanup` kills the server and removes the pid file.
4. Guard: python3 is present on current firmware; init script fails gracefully
   if missing.

- **Uninstall:** the stop path above, plus deleting the payload directory
  (portal semantics).
- **Boot persistence:** rc.d symlinks (overlay). Survives reboots and firmware
  upgrades; after a firmware upgrade (which wipes overlay) re-run the payload to
  re-enable — same caveat as nautilus. Foreground mode needs no persistence.

## 5. Backend (`server.py`)

Python 3.11 stdlib only (`http.server`, `sqlite3`, `subprocess`, `json`,
`socketserver`, hand-rolled minimal RFC6455 for the live-update WS). Binds
`0.0.0.0:8080`. Single origin serves the SPA and the API.

| Endpoint | Method | Implementation |
|---|---|---|
| `/api/login` | POST | validate via daemon `:1471/api/login`; on success return token and `Set-Cookie: AUTH_<serverid>` (host `172.16.52.1`, no `Domain`, `Path=/`, `HttpOnly`, `SameSite=Lax`) so docked terminal + loot downloads on `:1471` are authorized cross-port |
| `/api/api_ping` | GET | serverid + version (mirror daemon) |
| `/api/status` | GET | battery/power via sysfs, WiFi/interfaces via `iwinfo` + `ip`, firmware/daemon versions, disk via `df`, uptime |
| `/api/pineap/settings` | GET/POST | read/write UCI `/etc/config/pineapd` (mimic, collect probes, advertise, collect handshakes, random MAC, wigle, bands) + `pineap_reload` |
| `/api/pineap/ssids` | GET/POST | SSID pool read/write via `hak5cmd` |
| `/api/pineap/ssidpool/{start,stop,collect_start,collect_stop}` | POST | via `hak5cmd` |
| `/api/pineap/filters/client` | GET/POST | device filter mode + list via `hak5cmd` |
| `/api/pineap/filters/ssid` | GET/POST | network filter mode + list via `hak5cmd` |
| `/api/pineap/clients` | GET | associated clients via `iwinfo assoclist` / `hostapd_cli` on `wlan0open`/`wlan0wpa`/`wlan0mgmt` |
| `/api/pineap/clients/kick` | POST | deauth via `hak5cmd` + auto-add to deny filter (Mark VII behavior) |
| `/api/pineap/deauth/client` | POST | `PINEAPPLE_DEAUTH_CLIENT` |
| `/api/recon/{start,stop}` | POST | `hak5cmd` `RECON_NEW` / stop |
| `/api/recon/scans` | GET | scans list from `recon.db` |
| `/api/recon/scans/<id>` | GET | APs/clients/handshakes for a scan from `recon.db` |
| `/api/pineap/handshakes` | GET/DELETE | list/delete `/root/loot/handshakes` |
| `/api/loot/zip` | GET | zip download (wraps daemon `:1471` with cookie) |
| `/api/loot/archive` | POST | wraps daemon `:1471` |
| `/api/payloads/index`, `/api/payloads/install`, `/api/payloads/remove`, `/api/payloads/refresh` | GET/POST | wrap daemon portal endpoints |
| `/api/logging/system` | GET | `logread` (filtered, tail) |
| `/api/logging/pineap` | GET | pineapd/daemon log sources |
| `/api/device` | GET | hostname, MACs, model |
| `/api/settings/hostname` | GET/POST | `uci` network hostname |
| `/api/settings/password` | POST | change the device root password via BusyBox `passwd` stdin |
| `/api/settings/ntp` | GET/POST | UCI `system` `timeserver` (enabled + servers) + restart `sysntpd` |
| `/api/ws` | WS | live push: status/clients/recon deltas every ~2s |
| `/api/terminal/openWs` | WS | same path on our origin; client connects direct to daemon `ws://172.16.52.1:1471/api/terminal/openWs` (cookie-authed). Fallback: server relays |

### Auth model
- All endpoints (except `/api/login`) require a valid session cookie set by
  `/api/login`.
- Token is never logged or stored server-side beyond the session check; the
  backend validates each request by checking the session cookie against the
  daemon's token (a lightweight session store in `/tmp/pagerwebui.session`).
- Commands are executed with argument lists (no shell string interpolation) to
  prevent injection.

## 6. Frontend (vanilla JS SPA)

- Static files in `www/`: `index.html`, `css/app.css`, `js/app.js` (or split
  modules), `js/xterm.js` + `js/xterm-fit.js` (bundled copies), `assets/`.
- Mark VII-style chrome: dark theme, top bar (logo, live status, **Terminal
  button**), nav rail, hash-based routing (`#/dashboard`, `#/pineap`,
  `#/recon`, `#/handshakes`, `#/payloads`, `#/logs`, `#/settings`).
- **Dashboard:** status cards + live counters (battery, clients, APs,
  handshakes) fed by `/api/ws`.
- **PineAP:** settings toggles (mimic/advertise/collect/handshakes/random MAC/
  wigle/bands), SSID pool CRUD + collect/start/stop, client & SSID filters
  (mode + list CRUD), client list with kick.
- **Recon:** scan list, AP/client tables from `recon.db`, start/stop buttons.
- **Handshakes/Loot:** list, download zip, delete, archive.
- **Payloads:** portal list + install/remove/refresh.
- **Logs:** system + pineap logs with tail/poll.
- **Settings:** hostname, NTP, password, webUI prefs (poll interval, accent),
  service status (background/foreground).
- **Terminal:** bottom-docked xterm panel toggled by the top-bar button (Mark
  VII parity). Connects `ws://172.16.52.1:1471/api/terminal/openWs`. Default
  80x24; resize behavior validated during implementation (daemon may ignore
  resize; fallback fixed size with xterm `fit` disabled).

## 7. Security & Resilience

- Auth: device password validated through the daemon; HttpOnly session cookie;
  no plaintext secret storage; state-changing endpoints all behind login.
- No stock files modified; no `opkg` changes; reversible via `payload.sh`
  stop/uninstall; factory reset / firmware recovery remain available.
- `server.py` failure modes: procd respawn in background mode; foreground mode
  cleans up on exit; `recon.db` opened read-only; subprocesses use arg lists.
- Binds `0.0.0.0:8080` (same exposure class as stock `:1471` / `:7681`).

## 8. Testing & Verification

- Windows dev loop: `scripts/dev.ps1` runs the SPA + API locally and proxies to
  the Pager.
- PowerShell-driven API tests against `:8080`: login, status, each read/write
  endpoint before frontend wiring.
- On-device smoke tests per page: status, pool CRUD, filter toggles, recon
  start/scan read, handshake listing, portal install/remove, terminal I/O,
  background vs foreground modes, reboot persistence.
- Recovery drill: uninstall, re-install, foreground-stop, firmware-upgrade
  caveat documented in README.

## 9. Out of Scope (v1)

- `:1471` takeover/redirect.
- Mark VII features without a Pager equivalent: Campaigns, Modules, Cloud C²,
  Enterprise/EAP pages.
- Physical-display screen mirror.
- Publishing a PR to the official payloads repo (packaging ready; submission
  later).

## 10. Open Risks (mitigated during implementation)

- Client-list source validation: `iwinfo assoclist` / `hostapd_cli` against the
  Pager's hostapd interfaces (`wlan0open`, `wlan0wpa`, `wlan0mgmt`).
- Minimal RFC6455 WebSocket server correctness.
- Daemon terminal resize support (fallback to fixed 80x24).