Mark-VIII/docs/specs/2026-08-11-pineapple-ui-clone-design.md

Pineapple UI Clone — Design Spec

• Date: 2026-08-11
• Status: Approved (pending written-spec review)
• Owner: Hak5 WiFi Pineapple Pager expansion project
• Supercedes look of: www/ assets shipped in 2026-08-10-pager-webui-design.md

1. Goal

Restyle the Pager WebUI (http://172.16.52.1:8080/) to be a faithful clone of the stock Hak5 WiFi Pineapple UI (http://172.16.42.1:1471/), so an operator used to one interface can use the other without re-learning navigation, terminology, or interaction patterns.

Scope is cosmetic + navigation only, plus one small read-only backend endpoint (GET /api/pineap/aps, §3.5). Auth/session mechanics and the payload packaging pipeline are unchanged.

Verified on-device (2026-08-11): the Pager's Go daemon on :1471 exposes only api_ping, login, payload-portal, loot, and WS endpoints — it has no /api/pineap/* surface. All PineAP/Recon/Logging/Settings endpoints in the current server.py are implemented by pager-webui itself via hak5cmd, uci, iwinfo, and recon.db. (Note: the old UI at 172.16.42.1:1471 and the new Pager at 172.16.52.1 are separate devices.)

2. Research Basis (live UIs, captured 2026-08-11)

Old UI (:1471) — stock Angular 8 / Angular Material SPA

• Hash routes: #/Login, #/Setup, #/Dashboard, #/Campaigns (/reports), #/Recon (/handshakes), #/PineAP (/open, /clients, /filtering, /enterprise, /aps, /impersonation), #/Settings (/networking, /wifi, /developer, /advanced, /led, /help), #/Logging (/system), #/Modules.
• Login: full-screen flat gray #9c9c9c; centered white elevated card (mat-elevation-z20): "WiFi Pineapple" h2, pineapple logo PNG (148px), Username + Password fields, raised "Login" button (spinner while busy), inline red error text; Cloud C2 error variant.
• Shell: 64px toolbar (#424242, Material mat-toolbar) with logo + "WiFi Pineapple"; content offset margin-left: 90px; icon rail sidenav (min-width:60px, #f3f3f3; dark #3a3a3a, hover #a9a9a9 / dark #545454): Dashboard, Campaigns, PineAP ("PineAP Suite"), Recon, Logging, Modules ("Modules & Packages"), Settings; active entry border-right:3px solid #1976d2; entry dividers; bottom "Open Menu" chevron toggles expanded rail; module entries are drag-reorderable (out of scope). Content background #fafafa; Roboto/Helvetica/sans-serif font stack.
• Views use horizontal mat-tab navigation with a blue ink bar for each multi-page section (PineAP, Recon, Logging, Settings, Campaigns).
• Dashboard: status cards (Clients, Handshakes Captured, Disk Usage, …) + Chart.js line chart (clients over time) + "Connected Clients" table (Deauthenticate) + "Captured WPA Handshakes" table.
• Extras: keyboard shortcuts (D/C/R/P/M, Backquote = terminal), light/dark theme (stored in localStorage), notification center, corner "flash indicator" toasts, ASCII pineapple (='.'=).
• Auth: POST /api/login {username, password} → {token}; stored in localStorage <base>_authToken + AUTH_<ServerId> cookie; device password for user root.

New UI (:8080) — vanilla JS SPA (current source of truth)

• GitHub-dark theme (#0d1117 bg, #161b22 panels, teal #00d4aa accent, Segoe UI); password-only login; flat text rail (Dashboard, PineAP, Recon, Handshakes, Payloads, Logs, Settings); single-page sections; bottom-docked xterm panel; WS live updates + 5s polling fallback; bottom-right toasts.
• Backend: pure-socket HTTP/JSON/WS on 0.0.0.0:8080 (device python3-light); auth via AUTH_<serverid> HttpOnly cookie validated against the daemon; terminal connects directly to daemon WS on :1471.

Feature mapping (old IA → current Pager capabilities)

Old tab	Clone behaviour
Dashboard	status cards + Chart.js chart + Connected Clients + Handshakes tables
Campaigns	visible tab, single "not supported on the Pager" empty-state card
PineAP → Open	PineAP settings toggles (mimic/advertise/probes/handshakes/random MAC/WiGLE) + bands
PineAP → Clients	connected clients + kick
PineAP → Filtering	client (MAC) + SSID allow/deny/off filters
PineAP → APs	new read-only endpoint GET /api/pineap/aps: iwinfo <mon-iface> scan table (BSSID/SSID/Channel/Signal/Encryption)
PineAP → Impersonation	SSID pool add/clear + Start/Stop/Collect
PineAP → Enterprise	omitted (not supported on Pager)
Recon → Overview	scans list + new/stop/refresh + scan detail
Recon → Handshakes	loot files: download zip / archive / delete
Logging → Overview	system + PineAP logs
Logging → System	system log with level filter (Error/Warning/Informational)
Modules & Packages	payload portal (search + list + Install/Remove)
Settings	general info, hostname, NTP, password, WebUI prefs (poll interval, theme)

3. Design

3.1 Architecture

No build step; same vanilla-JS file layout. New/vendored files under www/:

• assets/logo.png + favicon — copied from old UI assets/icons/logo.png.
• js/chart.min.js — vendored Chart.js from old UI (no CDN on device).
• js/icons.js — inline SVG icon set lifted from the old Angular bundle (dashboard grid, campaigns, pineap, recon, logging, modules, settings, chevron).
• js/themes.css or CSS custom properties — light/dark token sets.
• css/app.css — rewritten around Material light tokens.
• js/views.js — restructured to old IA with sub-views + mat-tab-style bars.
• js/app.js — routing (incl. sub-routes), keyboard shortcuts, theme toggle, terminal wiring, flash-style toasts.
• index.html — old-style shell markup (login card, toolbar, icon rail, content, terminal panel).

Roboto: vendor .woff2 from the device if present (:1471/assets/ fonts); otherwise the existing Roboto, Helvetica Neue, sans-serif stack falls back to system fonts.

3.2 Design tokens (light default, dark optional)

• Light: content #fafafa; cards #fff with subtle elevation/shadow; toolbar
  • rail #424242; rail hover #a9a9a9; active border #1976d2; primary #1976d2 / #1e88e5; danger #d32f2f; ok #7cb342; warn #f9a825; text #212121 / muted #686868; ink bar + focus #1976d2.
• Dark (mirrors old theme): rail #3a3a3a, hover #545454, surfaces #303030, cards #424242.
• Theme selected via <html class="dark"> driven by localStorage; toggle in Settings (and honored on all pages).

3.3 Shell

• Toolbar (64px, #424242): logo + "WiFi Pineapple" brand (left); right: muted live status "BAT % · CLIENTS n", Terminal button.
• Icon rail (60px): 7 entries, 24px inline SVG + label (label hidden while collapsed, title tooltip shown), dividers between groups, active = 3px blue right border. Bottom "Open Menu" chevron expands to ~200px with labels; state persisted in localStorage (mirrors old sideNavState).
• Content (#fafafa): page header + horizontal tab bar (where applicable)
  • white cards; existing .section/.tbl/.badge/.row/.toggle classes restyled to the light theme.
• Terminal: stays bottom-docked (new behaviour) but restyled to the old look; kept docked intentionally (matches current Pager UX and spec v1).
• Toasts: corner "flash indicator" style (old look), same API.

3.4 Login

Password-only (per user decision; username fixed root). Full-screen gray #9c9c9c; centered white elevated card: logo, "WiFi Pineapple" h2, single Password field (placeholder "Password"), raised primary Login button with busy spinner, inline red error text on failure. Posts to the existing /api/login endpoint via PagerAPI.login('root', pw) — no backend change.

3.5 Views (per mapping table)

Each multi-page section renders a mat-tab-style horizontal bar (blue ink bar) with tab items; deep-linkable via hash routes #/pineap/clients etc. Placeholder Campaigns uses the old empty-state card.

PineAP → APs requires one new backend route. Add to server.py: GET /api/pineap/aps → runs iwinfo <iface> scan over the monitor interfaces listed by /api/status and returns rows {bssid, ssid, channel, signal, encryption} (read-only, no root action, same exposure class as the existing /api/status). A unit test covers the parser with a canned iwinfo capture.

3.6 Data flow

Unchanged: PagerAPI (fetch wrapper), Live WS + 5s poll fallback, Live.onTick drives the dashboard chart's rolling series (e.g. last 60 samples of clients + handshakes). Theme and rail state live in localStorage. The single new route is GET /api/pineap/aps (§3.5).

3.7 Error handling

Unchanged: failed API calls surface via toasts; login failure shows inline red text; WS down → poll fallback (existing logic untouched).

4. Testing

• Manual on-device smoke pass per spec v1 §8: every page in background and foreground modes, login/logout, terminal I/O, reboot persistence.
• Visual parity checklist: login card, toolbar, rail expand/collapse + active indicator, each tab bar, table/card styling, dark theme.
• Asset checks: logo.png, favicon, chart.min.js, Roboto (if vendored) all serve from :8080; verify with curl.
• Existing Python unittest suite (API-level) must remain green; add a test for the new iwinfo scan parser.
• Deploy via scripts/deploy.ps1 (existing pipeline); payload zip must include the new/vendored assets.

5. Out of scope

• Campaigns functionality, Cloud C2, Enterprise SSIDs, LED/Network/Developer Settings sub-pages, module drag-reorder, notification center, :1471 takeover.