Plan 1 of 2: the BYOD Wi-Fi access model

Six TDD tasks covering the back-end half of the approved spec: the live-authorization
quota scope, dropping network presence as an eviction trigger, the role allow-list
with `default` removed, the IP-derived device resolver, randomized-address
detection, and the reconciler.

Split from the UI deliberately. Plan 1 leaves the portal correct and safe while
still being configured through the existing mappings CRUD, so it is worth shipping
on its own; Plan 2 covers the settings screen, the denial-page coaching copy and
the Wi-Fi Devices page.

Three things the self-review caught and the plan now handles:

  · the resolver had no retry, so a device that had only just associated — and so
    had no IP in UniFi's table yet — would have been told it was not connected at
    the exact moment it was connecting;
  · nothing captured the device fingerprint, which the report-only device-type
    decision depends on. The reconciler now does it, and only ever fills in: an
    unfingerprinted client must not blank a type already recorded, or the answer
    is lost every time the device happens to be quiet;
  · one task's test needed a method a later task introduced, and the first draft
    said to leave it red. Under subagent-driven execution a fresh agent per task
    would have seen red and tried to fix it, so the test now uses the parameter
    flow that exists at that point and the later task migrates it.

Also records what NOT to do: do not schedule the reconciler (it calls
unauthorizeGuest against a live controller that nothing here has been tested
against), do not register the unifi app, and do not touch disconnectSession.

composer.json

@@ -1,7 +1,7 @@
 {
     "name": "dashboard/unifi",
     "description": "UniFi network management, WiFi stats, and captive portal authentication for the Dashboard platform",
-    "version": "1.10.0",
+    "version": "1.13.4",
     "type": "library",
     "license": "MIT",
     "autoload": {
@@ -16,6 +16,8 @@
             ]
         },
         "dashboard": {
+            "tier": "optional",
+            "stability": "stable",
             "nav_folder": {
                 "label": "Unifi Network",
                 "icon": "wifi",
@@ -33,7 +35,8 @@
                 { "key": "unifi.stats",    "label": "View Network Stats",  "description": "View WiFi dashboards, AP stats, and client lists" },
                 { "key": "unifi.manage",   "label": "Manage Network",      "description": "Reboot APs, manage SSIDs, change WiFi passwords" },
                 { "key": "unifi.auth",     "label": "Manage Portal Auth",  "description": "Configure captive portal, VLAN mappings, MAC allowlist" },
-                { "key": "unifi.settings", "label": "Network Settings",    "description": "Configure UniFi controller connection" }
+                { "key": "unifi.settings", "label": "Network Settings",    "description": "Configure UniFi controller connection" },
+                { "key": "unifi.guest_wifi", "label": "View Guest Wi-Fi Password", "description": "See the guest network name, its current rotating password, and the join QR code on the home page. Grants no other network access." }
             ]
         }
     },

database/migrations/2026_06_12_000001_add_role_and_default_to_unifi_page_grants.php

@@ -0,0 +1,62 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Schema;
+
+/**
+ * Brings unifi_page_grants to parity with adm_access_grants /
+ * directory_access_grants: widens grantee_type to include 'default' and
+ * 'role', allows a NULL grantee_id (used by the per-page default row),
+ * and adds a can_view column. The default row's can_view carries the
+ * deny/allow fallback for users not matched by a more specific grant
+ * (deny by default — no row means deny).
+ *
+ * Existing user/group rows keep working: adding can_view with a default
+ * of true backfills them as explicit allow grants.
+ */
+return new class extends Migration
+{
+    public function up(): void
+    {
+        if (! Schema::hasTable('unifi_page_grants')) return;
+
+        // Widen the enum and allow NULL grantee_id (default rows). MySQL
+        // enum changes require raw DDL.
+        DB::statement("ALTER TABLE unifi_page_grants MODIFY grantee_type ENUM('default','user','group','role') NOT NULL");
+        DB::statement("ALTER TABLE unifi_page_grants MODIFY grantee_id BIGINT UNSIGNED NULL");
+
+        if (! Schema::hasColumn('unifi_page_grants', 'can_view')) {
+            Schema::table('unifi_page_grants', function (Blueprint $table) {
+                $table->boolean('can_view')->default(true)->after('grantee_id');
+            });
+
+            // Belt and braces: make sure every pre-existing user/group row
+            // is an explicit allow grant.
+            DB::table('unifi_page_grants')->update(['can_view' => true]);
+        }
+
+        // The unique index on (nav_item_id, grantee_type, grantee_id)
+        // already exists from the create migration
+        // ('unifi_page_grants_unique') and still applies — grantee_id is
+        // NULL for default rows, and MySQL treats NULLs as distinct, so
+        // app code enforces one default row per nav_item.
+    }
+
+    public function down(): void
+    {
+        if (! Schema::hasTable('unifi_page_grants')) return;
+
+        if (Schema::hasColumn('unifi_page_grants', 'can_view')) {
+            Schema::table('unifi_page_grants', function (Blueprint $table) {
+                $table->dropColumn('can_view');
+            });
+        }
+
+        DB::table('unifi_page_grants')->whereIn('grantee_type', ['default', 'role'])->delete();
+
+        DB::statement("ALTER TABLE unifi_page_grants MODIFY grantee_type ENUM('user','group') NOT NULL");
+        DB::statement("ALTER TABLE unifi_page_grants MODIFY grantee_id BIGINT UNSIGNED NOT NULL");
+    }
+};

docs/superpowers/specs/2026-08-21-byod-wifi-portal-hardening-design.md

@@ -0,0 +1,288 @@
+# Registered guest / BYOD Wi-Fi — hardening the captive portal
+
+**Date:** 2026-08-21
+**Repos:** `central-unifi` (most of it), `dashboard-shell` (tests, one Vue page)
+**Status:** design approved, no implementation plan yet
+
+---
+
+## Why this document is short on new features
+
+Nearly everything asked for already exists in `central-unifi` v1.13.4 and has for
+some time. The request was "design registered guest Wi-Fi"; the finding is that
+the feature is largely built, partly broken in ways that only show up under real
+use, and **currently unreachable**. So this is a hardening spec, not a greenfield
+one.
+
+### What already works
+
+| Requirement | Where it lives |
+|---|---|
+| Captive portal + Google auth | `PortalController::captiveCallback`, `/portal/wifi/callback`; the shell's OAuth has already authenticated the user by then |
+| Per-cohort device limits | `unifi_vlan_mappings.max_devices` |
+| Per-cohort VLAN | `unifi_vlan_mappings.vlan_id` |
+| Session length | `unifi_vlan_mappings.session_minutes` (validated 1..525600) |
+| Self-service eviction | `Unifi/PortalDenied` page lists the user's devices with `can_disconnect`, plus `unifi.portal.self-disconnect` |
+| Admin eviction | `unifi.portal.sessions.disconnect` behind `app.access:unifi` + `permission:unifi.auth` |
+| Device fingerprint capture | `CaptureSnapshots` already writes `dev_cat` and `os_name` per MAC into `unifi_client_snapshots` |
+
+Eviction authorisation is already correct and is **not** being changed:
+`disconnectSession()` does `kickClient` + `unauthorizeGuest` and authorises
+owner-or-`unifi.auth` inside the action, so a student can free their own slot and
+nobody else's.
+
+### The answer to "must users re-do the portal every time?"
+
+No, and the mechanism is already wired. `authorizeGuest($mac, $minutes)` sends
+UniFi `cmd: authorize-guest` with a **minutes** value taken from
+`session_minutes`. UniFi holds that MAC as authorized for the whole window and
+does not redirect it again. Set the window to a term and a student signs in once
+a term.
+
+The portal is not the obstacle. **MAC randomization is** — see decision 2.
+
+---
+
+## Decisions
+
+| # | Decision | Rationale |
+|---|---|---|
+| 1 | Harden and finish the existing portal rather than redesign | 80% exists and the schema shape is right; the defects are in accounting and trust, not structure |
+| 2 | Detect a randomized MAC and coach the user; keep manual eviction | Manual choice is the stated requirement and already built; randomization is detectable, so the confusing case can be explained rather than hidden |
+| 3 | Derive the MAC from the request's source IP and verify AP association; ignore `?mac=` | Closes the ownership hole by construction — the caller never gets to name a MAC |
+| 4 | Add `role` as a `match_type` | Quotas were asked for per role; roles are the platform's own authority and need no external sync |
+| 5 | One Wi-Fi Devices page grouped by person; no profile card | Matches the requirement exactly; keeps `/admin/users` as the one directory |
+| 6 | Device type is **reported, not enforced**, for now | Whether `dev_cat` is populated in this environment is unverified; enforcing on unvalidated data can lock out the wrong people |
+| 7 | **Explicit allow-list only** — no `default` mapping | No Wi-Fi unless an admin has added that role and set an amount. A `default` row silently grants everyone, which is the opposite of the requirement |
+| 8 | Roles are chosen from a dropdown; session length entered in days | A free-text role slug that matches nothing fails silently — it presents as "this student has no Wi-Fi" with no error anywhere to explain it |
+
+---
+
+## A. What consumes a device slot
+
+### The defect
+
+A slot is currently freed when `isClientConnected($mac)` is false. That conflates
+**connected right now** with **authorized**, and they are different facts. Two
+leaks follow, in opposite directions, and both get worse the longer
+`session_minutes` is — which is exactly the direction this design pushes it.
+
+**Leak 1 — offline treated as unauthorized.** A phone leaves the building. Its
+session row is marked inactive, freeing a slot, while UniFi still holds the MAC
+authorized for the rest of its window. The user authorizes a second device. Two
+devices are now on the network against a one-device quota, and one of them is an
+orphan nothing tracks.
+
+**Leak 2 — `expires_at` is written and never read.** No scheduled job expires
+sessions. A row stays `is_active` long after UniFi stopped honouring it, so the
+user is refused by slots that do not exist.
+
+They compound: the same student can be simultaneously over-provisioned on the
+network and locked out of the portal.
+
+### The model
+
+- A slot is consumed by a **live authorization**: `is_active AND expires_at > now()`.
+  Presence on the network is irrelevant to the count.
+- A slot is freed by exactly three things: eviction (user or admin), expiry, or the
+  reconciler finding UniFi no longer holds it.
+- `isClientConnected()` is **no longer an eviction trigger**. It becomes a display
+  value only — "connected" / "away" on the admin page.
+- Quota resolution gains `role`. Precedence stays `sort_order`, so a mapping for
+  `staff` above one for `parent` gives a staff-parent 4 devices.
+
+---
+
+## B. Identifying the device
+
+### Flow
+
+1. UniFi redirects the device to `/portal/wifi/callback?ap=<ap_mac>&ssid=…&url=…`.
+2. Google auth via the shell — unchanged.
+3. Resolve the device **server-side**: match the request's client IP against
+   UniFi's live client table (`getActiveClients()`, on `ip`) to obtain the real
+   MAC, its `ap_mac`, and its authorization state.
+4. Require that the resolved client's `ap_mac` equals the `ap` in the redirect —
+   the device must be on the AP that sent it here.
+5. `?mac=` is **ignored**: not validated, not used. It is read for one purpose —
+   if present and disagreeing with the derived MAC, log it. That disagreement is
+   somebody attempting to authorize a device they do not own, and today nothing
+   would notice.
+6. Check the locally-administered bit on the **derived** MAC. Record it on the
+   session; it is what triggers the coaching copy on the denial page.
+
+This replaces the hole the original author documented and declined to guess at:
+every identifying value was request-supplied, so any signed-in account could
+authorize somebody else's MAC up to `max_devices`.
+
+### Failure modes, deliberately closed
+
+- **IP matches no client** → refuse.
+- **IP resolves to the proxy** → refuse, and report it distinctly (see below).
+- **AP mismatch** → refuse.
+- **Client not in the table yet** (associated, pre-DHCP) → retry twice at ~750ms,
+  then show "still connecting, try again" rather than a hard error. Bounded on
+  purpose: this runs inside a web request, and a longer wait would hold a worker
+  per connecting device at exactly the moment a class of them arrives at once.
+
+### The operational risk this creates
+
+Failing closed means it can fail closed **for everyone**. If `TrustProxies` is
+not correct for Traefik, every request resolves to the proxy, no client ever
+matches, and nobody can get on the Wi-Fi — a worse outage than the vulnerability
+being fixed.
+
+Mitigation: the resolver distinguishes "no client matched this IP" from "this IP
+is the proxy", and the second is surfaced as a health line on the Wi-Fi Devices
+page. The failure becomes one glance to diagnose instead of a mystery. This is
+also the single most important thing to verify against the live controller.
+
+### MAC randomization
+
+Normally stable per SSID, so it does not break the design. When it does rotate,
+the device looks new: it consumes a slot and the user is asked to evict what
+appears to be the same phone. With `max_devices: 1` this is the likeliest support
+call.
+
+Handling: when the derived MAC is randomized **and** the user is at limit, the
+denial page leads with an explanation — the device is using a private Wi-Fi
+address, which is why it looks new — followed by the iOS and Android steps to
+turn it off for this network, then the normal eviction list. Detection is the
+locally-administered bit; no guessing.
+
+---
+
+## C. Persistence, and the reconciler
+
+`session_minutes` is the lever for "no portal on every connection". Default to a
+term (~120 days) rather than a year, so lost or handed-down devices age out.
+
+A scheduled reconciler (following `CaptureSnapshots` and the `unifi_cron_runs`
+pattern) does three jobs:
+
+1. **Expire** rows past `expires_at` — fixes leak 2.
+2. **Reconcile both directions** — revoke UniFi authorizations with no live row
+   (the orphans leak 1 produced), and expire rows UniFi no longer holds.
+3. **Capture device type** onto the session from the client record — the
+   report-only fingerprint data for decision 6.
+
+Job 2 also heals controller-side loss: if UniFi forgets an authorization while our
+row is still live and in-window (upgrade, restore), the reconciler re-authorizes
+it. The user is not bounced to the portal for something that was not their doing.
+
+Windows are **fixed, not sliding** — a device's authorization ends when it ends,
+so "one term" means one term.
+
+---
+
+## C2. Settings: who gets Wi-Fi, and how much
+
+Access is an **explicit allow-list**. A person gets Wi-Fi only if one of their
+roles has been added here with an amount. No role added means no Wi-Fi, and that
+is the intended answer rather than a gap to be filled by a catch-all.
+
+Consequences, stated so nobody re-adds the hole later:
+
+- **`default` is removed from the available match types.** A `default` row matches
+  everybody, so its existence makes the allow-list advisory. `resolveMapping()`
+  already returns null when nothing matches, and null already produces the
+  "No WiFi access configured for your account." denial — so deny-by-default is
+  the behaviour once the catch-all cannot be created.
+- Safe to remove now: **there are zero rows in `unifi_vlan_mappings` in any
+  environment**, so nothing is being revoked from anyone. Doing this later, after
+  a school had leaned on a catch-all, would cut off every unmapped person at once.
+- `email_domain`, `group` and `ou` stay available — they are narrow matches, not
+  catch-alls, and removing working options is not part of this.
+
+### The settings screen
+
+Extends the existing Portal settings page rather than adding another one. Per row:
+
+| Field | Control | Why |
+|---|---|---|
+| Role | **dropdown of real seeded roles** | Free text is the defect. `match_value` is a string compared exactly, so `Student` or `studnet` matches nobody and the failure surfaces as a pupil with no Wi-Fi and nothing logged. The dropdown makes an unmatchable value impossible to enter. |
+| Devices | number, 1..50 | The quota. Column is already bounded. |
+| Session length | **days, with presets** (a week / a month / a term / a year) | `session_minutes` stays the stored unit, but a term is 172,800 minutes and nobody should type that. Same reasoning as presenting cron schedules as presets rather than raw strings. |
+| VLAN | existing select | **Still required** — the network needs to know where to put the device, and this was not in the original request, so it is called out rather than quietly dropped. |
+| Order | existing `sort_order` | Precedence for multi-role people: staff above parent gives a staff-parent 4. |
+
+Roles already in the system and available to add: staff, student, parent,
+oncall-staff, coach, alumni, applicant, board-member, contact, homeschool,
+homeschool-parent, homeschool-student, open-house, tuition-payee, forms-payer.
+
+## D. The Wi-Fi Devices page
+
+New page under Unifi, gated on the existing `unifi.auth`, grouped by person.
+
+- **Person row:** name, role, quota usage ("staff · 2 of 4").
+- **Device rows:** hostname, device type (reported), MAC in `font-mono` as a
+  technical id, a "private address" marker when randomized, AP, SSID, authorized
+  at, expires at, and connected/away — display only.
+- **Per-device disconnect** as a `.btn-icon-danger` row action behind the shared
+  confirm modal. Never a native `confirm()`.
+- Search, plus a filter for over-quota people.
+- The portal health line from section B.
+
+Follows the house table and empty-state conventions in the shell's `CLAUDE.md`.
+
+---
+
+## E. Testing
+
+### Covered here, with `Http::fake()` for the controller
+
+- Both quota leaks, one regression test each: an offline device keeps its slot; an
+  expired row stops consuming one.
+- `role` matching, and `sort_order` precedence including the staff-parent case.
+- The reconciler in both directions, including the re-authorize-on-controller-loss
+  path.
+- Randomized-MAC bit detection, both values.
+- Resolver fail-closed paths: no client match, IP resolves to the proxy, AP
+  mismatch, client not yet in the table.
+- That `?mac=` is ignored, and that a disagreement is logged.
+- Authorization-not-connectivity: a slot survives the device going away.
+
+Plus a browser pass over the denial page (including the randomized-MAC copy),
+self-service eviction, and the admin page — UI behaviour changes, so the
+before-push browser rule applies.
+
+### NOT provable without the live controller
+
+- The actual parameters UniFi's redirect sends.
+- Whether `dev_cat` is populated for these clients — `unifi_client_snapshots` has
+  zero rows on dev, so there is no evidence either way.
+- Whether `TrustProxies` yields the true client IP through Traefik.
+
+These need a supervised session against real hardware, in the same spirit as the
+Bosch cutover. The third is the one that gates release: it is the difference
+between a closed hole and nobody getting online.
+
+---
+
+## F. Rollout
+
+1. **Register the app.** Every route here 404s today, because `unifi` has no
+   `dashboard_apps` row and `app.access:unifi` aborts 404 when the lookup misses.
+   Nothing in this spec is reachable until that is resolved. Note `central-unifi`
+   declares `stability: stable`, so unlike On-Call this is a gap rather than a
+   decision — **and it is still an open question, not settled by this document.**
+2. Verify the three hardware-dependent items above against the live controller.
+3. Configure mappings: `role` → student (1 device) and staff (4 devices), with
+   `sort_order` set so multi-role people land deliberately.
+4. Pilot with staff, then students.
+
+---
+
+## Explicitly out of scope
+
+- **Enforcing** a no-phones rule. Decision 6 is report-only until the fingerprint
+  data is shown to be trustworthy. When it is, enforcement belongs in the
+  reconciler (authorize, then sweep), because UniFi's fingerprint is derived from
+  observed traffic and is not available at the moment of authorization.
+- MAC OUI as a device-type signal. A randomized MAC has no real OUI, so this
+  would fail on phones — its intended target — while working on the school
+  laptops that should not be blocked.
+- Blocking on the portal's User-Agent. Defeated by one "Request Desktop Site" tap.
+- Tethering. A blocked phone can share a laptop's connection and vice versa; no
+  design here addresses that, and none is proposed.
+- Any change to `disconnectSession`, which is already correct.

src/Console/RotatePasswords.php

@@ -80,17 +80,17 @@ class RotatePasswords extends Command
                 $newPass = $passwords[array_rand($passwords)];
                 try {
                     if (str_starts_with((string) $ppsk->unifi_id, 'emb_')) {
-                        // Embedded PPSK: update inside the parent WLAN object.
-                        // Match by name (most reliable) — falls back to
-                        // passphrase if name is missing.
+                        // Embedded PPSK: update inside the parent WLAN object,
+                        // matched by name (synthetic id changes with the
+                        // passphrase, so it's not a stable matcher).
                         $unifi->updateEmbeddedPpsk($ppsk->wlan_id, $ppsk->x_passphrase, $newPass, $ppsk->name);
                         $newUid = 'emb_' . substr(hash('sha256', $ppsk->wlan_id . ':' . $newPass), 0, 32);
                         $ppsk->update(['x_passphrase' => $newPass, 'unifi_id' => $newUid]);
 
-                        // Sibling WLANs (same SSID name on a different band):
-                        // rotate the matching-name PPSK in each so the
-                        // SSID's 2.4/5GHz halves stay in sync.
-                        foreach ($unifi->getWlanSiblings($ppsk->wlan_id) as $siblingWlanId) {
+                        // Update every grouped sibling (user-defined SSID
+                        // groups take precedence; same-name fallback for
+                        // installs that haven't grouped manually).
+                        foreach ($unifi->getGroupedWlans($ppsk->wlan_id) as $siblingWlanId) {
                             $sibling = UnifiPpsk::where('wlan_id', $siblingWlanId)
                                 ->where('name', $ppsk->name)
                                 ->where('state', 'active')
@@ -104,10 +104,37 @@ class RotatePasswords extends Command
                                     ]);
                                 }
                             } catch (\Throwable $e) {
+                                if (str_contains($e->getMessage(), 'not found')) {
+                                    \Illuminate\Support\Facades\Log::info('unifi.ppsk_sibling_skipped', [
+                                        'sibling_wlan' => $siblingWlanId,
+                                        'ppsk_name'    => $ppsk->name,
+                                    ]);
+                                    continue;
+                                }
                                 $this->error("Sibling rotate failed for wlan {$siblingWlanId}: {$e->getMessage()}");
                                 $failedPpsks[] = ['name' => $ppsk->name . ' (sibling wlan ' . $siblingWlanId . ')', 'error' => $e->getMessage()];
                             }
                         }
+
+                        // Verify that the new passphrase actually applied
+                        // on every grouped WLAN. UniFi can 200 an update
+                        // that doesn't stick (cluster sync race, etc).
+                        // Anything we expected to rotate that didn't is a
+                        // failure — surface it in the cron log.
+                        $allWlanIds = array_merge([$ppsk->wlan_id], $unifi->getGroupedWlans($ppsk->wlan_id));
+                        foreach ($allWlanIds as $checkWlanId) {
+                            $result = $unifi->verifyEmbeddedPpsk($checkWlanId, $ppsk->name, $newPass);
+                            if ($result['ok']) continue;
+
+                            // 'not_found' on a sibling = PPSK isn't on that band — ignore
+                            // (consistent with the skip in the update loop).
+                            if ($result['reason'] === 'not_found' && $checkWlanId !== $ppsk->wlan_id) continue;
+
+                            $failedPpsks[] = [
+                                'name'   => $ppsk->name . ' (verify wlan ' . $checkWlanId . ')',
+                                'error'  => 'verification ' . $result['reason'] . ($result['error'] ?? null ? ': ' . $result['error'] : ''),
+                            ];
+                        }
                     } else {
                         $unifi->updatePpsk($ppsk->unifi_id, ['x_passphrase' => $newPass]);
                         $ppsk->update(['x_passphrase' => $newPass]);

src/Http/Controllers/GuestCardController.php

@@ -0,0 +1,124 @@
+<?php
+
+namespace Dashboard\Unifi\Http\Controllers;
+
+use App\Models\Setting;
+use App\Models\User;
+use Illuminate\Http\Request;
+use Illuminate\Routing\Controller;
+
+/**
+ * The "Guest Wi-Fi" dashboard home card: network name, the current
+ * rotating password, and a QR code that re-generates when the password
+ * changes. The password is the rotation engine's last-applied value
+ * (unifi.password_rotation.last_password), so the card tracks whatever
+ * unifi:rotate-passwords sets. The card polls data() so it updates
+ * without a page reload.
+ */
+class GuestCardController extends Controller
+{
+    /**
+     * Is this card set up enough to ever appear?
+     *
+     * The three things payload() needs, asked as one question, so the permission
+     * screens can say "granted, but not configured yet" instead of leaving
+     * somebody staring at a home page wondering what they got wrong. The
+     * operator granted this key to two groups in production and saw nothing
+     * (2026-08-17); the card was simply never switched on.
+     *
+     * Note the third clause: last_password is written ONLY by
+     * unifi:rotate-passwords, so a school that sets a static guest password by
+     * hand and never rotates has no card and no obvious reason why.
+     */
+    public static function configured(): bool
+    {
+        return (bool) Setting::get('unifi.guest_card.enabled')
+            && trim((string) Setting::get('unifi.guest_card.ssid', '')) !== ''
+            && filled(Setting::get('unifi.password_rotation.last_password'));
+    }
+
+    /** Payload shared by the card resolver and the poll endpoint. */
+    public static function payload(): ?array
+    {
+        if (! Setting::get('unifi.guest_card.enabled')) {
+            return null;
+        }
+
+        $password = Setting::get('unifi.password_rotation.last_password');
+        $ssid = trim((string) Setting::get('unifi.guest_card.ssid', ''));
+        if (! $password || $ssid === '') {
+            return null;   // nothing meaningful to show yet
+        }
+
+        $freq = Setting::get('unifi.password_rotation.frequency', 'weekly');
+
+        return [
+            'title'      => trim((string) Setting::get('unifi.guest_card.title', '')) ?: 'Guest Wi-Fi',
+            'ssid'       => $ssid,
+            'password'   => $password,
+            'rotated_at' => Setting::get('unifi.password_rotation.last_rotated_at'),
+            // WPA/WPA2 join string a phone camera understands. Special
+            // chars in SSID/password must be backslash-escaped per the
+            // Wi-Fi QR spec.
+            'qr'         => self::wifiQrString($ssid, $password),
+            'frequency'  => in_array($freq, ['daily', 'weekly'], true) ? $freq : 'weekly',
+        ];
+    }
+
+    /** The dashboard card this endpoint feeds — must match UnifiServiceProvider. */
+    private const CARD_KEY = 'unifi.guest_wifi';
+
+    /**
+     * SECURITY: authorize against the card's own visibility.
+     *
+     * This was `web,auth` only, and the route comment claimed "card visibility is
+     * grant-gated by the shell" — but that gate is PRESENTATION only
+     * (DashboardController decides which cards to render). The endpoint itself was
+     * unchecked, so any signed-in account — every student and parent included —
+     * could fetch the live guest Wi-Fi password by requesting the URL directly.
+     *
+     * The endpoint enforces what the comment always claimed: you may poll it iff
+     * you may see the card. Still asked as the CARD gate — via the registry, which
+     * now answers from the card's permission (unifi.guest_wifi) instead of the
+     * retired dashboard_card_grants table. Asking the registry rather than naming
+     * the key here is deliberate: the endpoint and the home page cannot drift.
+     * Super admins pass, as everywhere else (keysFor handles that).
+     */
+    public function data(Request $request)
+    {
+        $user = $request->user();
+        abort_unless($user, 403);
+
+        abort_unless(
+            app(\App\Support\DashboardCardRegistry::class)->visibleTo($user, self::CARD_KEY),
+            403,
+        );
+
+        return response()->json(self::payload() ?? ['title' => null]);
+    }
+
+    /**
+     * Card registry resolver.
+     *
+     * Re-checks the permission the registry already gated on, the way bosch's and
+     * signinout's resolvers do. Redundant on the home-page path and deliberately
+     * kept: renderFor() renders whatever key list it is handed, and the payload
+     * here is a live credential — the one card where "the caller asked the right
+     * question" is not a good enough reason to hand it over.
+     */
+    public static function resolve(User $user): ?array
+    {
+        if (! $user->can('unifi.guest_wifi')) {
+            return null;
+        }
+
+        return self::payload();
+    }
+
+    private static function wifiQrString(string $ssid, string $password): string
+    {
+        $esc = fn (string $v) => preg_replace('/([\\\\;,:"])/', '\\\\$1', $v);
+
+        return sprintf('WIFI:T:WPA;S:%s;P:%s;;', $esc($ssid), $esc($password));
+    }
+}

src/Http/Controllers/PortalController.php

@@ -36,7 +36,11 @@ class PortalController extends Controller
             'match_value'     => 'required|string|max:255',
             'vlan_id'         => 'required|integer|min:1|max:4094',
             'max_devices'     => 'required|integer|min:1|max:50',
-            'session_minutes' => 'required|integer|min:1',
+            // Bounded by the column that stores it: unifi_vlan_mappings.session_minutes
+            // is unsignedInteger, so an unbounded value reached the INSERT and raised
+            // SQLSTATE 22003 — a 500 where a validation error belongs (central-unifi#5).
+            // 525600 minutes is a year, far more session than anyone will ever grant.
+            'session_minutes' => 'required|integer|min:1|max:525600',
         ]);
         $data['sort_order'] = VlanMapping::max('sort_order') + 1;
         VlanMapping::create($data);
@@ -51,7 +55,11 @@ class PortalController extends Controller
             'match_value'     => 'required|string|max:255',
             'vlan_id'         => 'required|integer|min:1|max:4094',
             'max_devices'     => 'required|integer|min:1|max:50',
-            'session_minutes' => 'required|integer|min:1',
+            // Bounded by the column that stores it: unifi_vlan_mappings.session_minutes
+            // is unsignedInteger, so an unbounded value reached the INSERT and raised
+            // SQLSTATE 22003 — a 500 where a validation error belongs (central-unifi#5).
+            // 525600 minutes is a year, far more session than anyone will ever grant.
+            'session_minutes' => 'required|integer|min:1|max:525600',
         ]);
         $mapping->update($data);
         return back()->with('success', 'Mapping updated.');
@@ -87,6 +95,35 @@ class PortalController extends Controller
 
     // ── Captive portal callback (called by UniFi external portal redirect) ───
 
+    /**
+     * A redirect target that cannot be turned into a phishing or script payload.
+     *
+     * Accepts only absolute http/https URLs and site-relative paths. Rejects
+     * javascript:/data:/vbscript: schemes, and protocol-relative "//host" values which
+     * redirect() would happily send off-site. Anything rejected falls back to the
+     * dashboard rather than erroring — the guest is already online at this point, so a
+     * bad `url` parameter should not look like a failed login.
+     */
+    private function safeRedirectTarget(?string $url): string
+    {
+        $url = trim((string) $url);
+
+        if ($url === '' || str_starts_with($url, '//')) {
+            return '/';
+        }
+
+        // Site-relative is always fine.
+        if (str_starts_with($url, '/')) {
+            return $url;
+        }
+
+        $scheme = strtolower((string) parse_url($url, PHP_URL_SCHEME));
+
+        return in_array($scheme, ['http', 'https'], true) && parse_url($url, PHP_URL_HOST)
+            ? $url
+            : '/';
+    }
+
     public function captiveCallback(Request $request, UnifiApiClient $unifi)
     {
         // UniFi redirects guest to this URL with ?id=<ap_mac>&ap=<ap_mac>&t=<timestamp>&url=<original_url>&ssid=<ssid>
@@ -104,6 +141,23 @@ class PortalController extends Controller
             return response('Missing MAC address', 400);
         }
 
+        // SECURITY: everything identifying the device is request-supplied, and this
+        // endpoint WRITES network state (authorizeGuest puts a MAC on the mapped VLAN).
+        // Before this check any signed-in account — a student, a parent — could call
+        //   GET /portal/wifi/callback?mac=<someone else's MAC>&url=…
+        // and admit a device they do not own, up to max_devices.
+        //
+        // A well-formed MAC is the floor, not a fix: it stops the parameter being used
+        // to smuggle junk into authorizeGuest and into the PortalSession row, but it
+        // cannot prove the caller owns the device. Properly binding it needs the AP
+        // handshake — UniFi can sign the redirect, or we ask the controller whether this
+        // MAC is CURRENTLY associated to $apMac before admitting it. Both need testing
+        // against real hardware, so they are deliberately not guessed at here.
+        $clientMac = str_replace('-', ':', $clientMac);
+        if (! preg_match('/^([0-9a-f]{2}:){5}[0-9a-f]{2}$/', $clientMac)) {
+            return response('Malformed MAC address', 400);
+        }
+
         // Find the VLAN mapping for this user's group/OU
         $mapping = $this->resolveMapping($user);
         if (! $mapping) {
@@ -161,9 +215,16 @@ class PortalController extends Controller
             'expires_at'       => now()->addMinutes($minutes),
         ]);
 
-        // Redirect to the original URL the user was trying to reach
-        $redirectUrl = $request->input('url', '/');
-        return redirect($redirectUrl);
+        // Redirect to the original URL the user was trying to reach.
+        //
+        // SECURITY: this was `redirect($request->input('url', '/'))` — an unvalidated
+        // open redirect on an authenticated route, i.e. a phishing primitive wearing
+        // this school's domain. The whole point of a captive portal is to send someone
+        // to an ARBITRARY external site they were already trying to reach, so an
+        // allowlist is not available; what is available is refusing anything that is
+        // not a plain http(s) URL, which blocks javascript:, data: and protocol-relative
+        // //evil.example payloads.
+        return redirect($this->safeRedirectTarget($request->input('url')));
     }
 
     public function disconnectSession(Request $request, PortalSession $session, UnifiApiClient $unifi)

src/Http/Controllers/StatsController.php

@@ -36,6 +36,7 @@ class StatsController extends Controller
             if ($wanIp && str_starts_with($wanIp, '127.')) $wanIp = $gw['connect_request_ip'] ?? null;
 
             return response()->json([
+                'available' => true,
                 'status'  => $wan['status'] ?? 'unknown',
                 'tx_rate' => $wan['tx_bytes-r'] ?? 0,
                 'rx_rate' => $wan['rx_bytes-r'] ?? 0,
@@ -44,7 +45,19 @@ class StatsController extends Controller
                 'latency' => $wan['latency'] ?? $gw['wan1']['latency'] ?? null,
             ]);
         } catch (\Throwable $e) {
-            return response()->json(['status' => 'error'], 500);
+            // The UniFi controller is unreachable. Degrade gracefully: return 200 with a
+            // friendly "unavailable" payload so the dashboard widget shows an unavailable
+            // state instead of the poll silently failing on a 500.
+            return response()->json([
+                'available' => false,
+                'status'  => 'unavailable',
+                'message' => 'UniFi controller is unreachable.',
+                'tx_rate' => 0,
+                'rx_rate' => 0,
+                'isp'     => null,
+                'wan_ip'  => null,
+                'latency' => null,
+            ]);
         }
     }
 
@@ -296,12 +309,21 @@ class StatsController extends Controller
                 ->values();
 
             return response()->json([
+                'available'  => true,
                 'labels'     => $series['labels'],
                 'traffic_rx' => $rx,
                 'traffic_tx' => $tx,
             ]);
         } catch (\Throwable $e) {
-            return response()->json(['error' => $e->getMessage()], 500);
+            // UniFi controller unreachable — degrade gracefully (200 with empty series)
+            // so the chart shows an empty/unavailable state rather than erroring on a 500.
+            return response()->json([
+                'available'  => false,
+                'message'    => 'UniFi controller is unreachable.',
+                'labels'     => [],
+                'traffic_rx' => [],
+                'traffic_tx' => [],
+            ]);
         }
     }
 

src/Http/Controllers/UnifiPagesAccessController.php

@@ -1,141 +0,0 @@
-<?php
-
-namespace Dashboard\Unifi\Http\Controllers;
-
-use App\Models\DashboardApp;
-use App\Models\Group;
-use App\Models\NavItem;
-use App\Models\User;
-use Dashboard\Unifi\Models\UnifiPageGrant;
-use Illuminate\Http\Request;
-use Illuminate\Routing\Controller;
-use Illuminate\Support\Facades\DB;
-
-/**
- * Super-admin-only endpoints for managing per-page access on unifi
- * pages. Pages here = nav_items where app_id = unifi's DashboardApp row.
- */
-class UnifiPagesAccessController extends Controller
-{
-    public function index()
-    {
-        $app = DashboardApp::where('slug', 'unifi')->first();
-        if (! $app) {
-            return response()->json(['pages' => [], 'users' => [], 'groups' => []]);
-        }
-
-        $pages = NavItem::where('app_id', $app->id)
-            ->where('is_folder', false)
-            ->whereNotNull('route_name')
-            ->orderBy('sort_order')
-            ->get(['id', 'label', 'route_name']);
-
-        $grants = UnifiPageGrant::whereIn('nav_item_id', $pages->pluck('id'))
-            ->get()
-            ->groupBy('nav_item_id');
-
-        // Only return users that ALREADY have grants. The full users list
-        // can be enormous (thousands of rows); the operator adds more via
-        // the searchUsers endpoint as needed.
-        $grantedUserIds = $grants->flatten(1)->where('grantee_type', 'user')->pluck('grantee_id')->unique();
-        $users = User::whereIn('id', $grantedUserIds)->orderBy('name')->get(['id', 'name', 'email']);
-
-        // Groups: always include super-admin groups (locked-on across all
-        // pages) plus any group with at least one grant. Other groups are
-        // added via searchGroups.
-        $grantedGroupIds = $grants->flatten(1)->where('grantee_type', 'group')->pluck('grantee_id')->unique();
-        $groups = Group::where(function ($q) use ($grantedGroupIds) {
-            $q->where('is_super', true)
-              ->orWhereIn('id', $grantedGroupIds);
-        })->orderBy('name')->get(['id', 'name', 'is_super']);
-
-        return response()->json([
-            'pages' => $pages->map(fn ($p) => [
-                'id'         => $p->id,
-                'label'      => $p->label,
-                'route_name' => $p->route_name,
-                'user_ids'   => $grants->get($p->id, collect())->where('grantee_type', 'user')->pluck('grantee_id')->all(),
-                'group_ids'  => $grants->get($p->id, collect())->where('grantee_type', 'group')->pluck('grantee_id')->all(),
-            ])->values(),
-            'users'  => $users,
-            'groups' => $groups,
-        ]);
-    }
-
-    /**
-     * Typeahead-style search for users to add to the access matrix.
-     * Returns up to 20 matches against name or email. Empty query returns
-     * an empty array — caller must enter at least 2 chars.
-     */
-    public function searchUsers(Request $request)
-    {
-        $q = trim((string) $request->query('q', ''));
-        if (strlen($q) < 2) {
-            return response()->json(['users' => []]);
-        }
-
-        $users = User::where(function ($w) use ($q) {
-            $w->where('name',  'like', '%' . $q . '%')
-              ->orWhere('email', 'like', '%' . $q . '%');
-        })
-            ->orderBy('name')
-            ->limit(20)
-            ->get(['id', 'name', 'email']);
-
-        return response()->json(['users' => $users]);
-    }
-
-    /**
-     * Typeahead-style search for groups to add to the access matrix.
-     * Excludes super-admin groups (they're already in the matrix and
-     * locked-on across every page).
-     */
-    public function searchGroups(Request $request)
-    {
-        $q = trim((string) $request->query('q', ''));
-        if (strlen($q) < 2) {
-            return response()->json(['groups' => []]);
-        }
-
-        $groups = Group::where('name', 'like', '%' . $q . '%')
-            ->where(function ($w) { $w->where('is_super', false)->orWhereNull('is_super'); })
-            ->orderBy('name')
-            ->limit(20)
-            ->get(['id', 'name', 'is_super']);
-
-        return response()->json(['groups' => $groups]);
-    }
-
-    public function update(Request $request, NavItem $navItem)
-    {
-        $app = DashboardApp::where('slug', 'unifi')->first();
-        if (! $app || $navItem->app_id !== $app->id) {
-            return response()->json(['error' => 'Not a unifi page.'], 422);
-        }
-
-        $data = $request->validate([
-            'user_ids'    => 'present|array',
-            'user_ids.*'  => 'integer|exists:users,id',
-            'group_ids'   => 'present|array',
-            'group_ids.*' => 'integer|exists:groups,id',
-        ]);
-
-        $grantedBy = $request->user()?->id;
-
-        DB::transaction(function () use ($navItem, $data, $grantedBy) {
-            UnifiPageGrant::where('nav_item_id', $navItem->id)->delete();
-
-            $rows = [];
-            $now  = now();
-            foreach ($data['user_ids']  as $uid) {
-                $rows[] = ['nav_item_id' => $navItem->id, 'grantee_type' => 'user',  'grantee_id' => $uid, 'granted_by_user_id' => $grantedBy, 'created_at' => $now, 'updated_at' => $now];
-            }
-            foreach ($data['group_ids'] as $gid) {
-                $rows[] = ['nav_item_id' => $navItem->id, 'grantee_type' => 'group', 'grantee_id' => $gid, 'granted_by_user_id' => $grantedBy, 'created_at' => $now, 'updated_at' => $now];
-            }
-            if ($rows) UnifiPageGrant::insert($rows);
-        });
-
-        return response()->json(['ok' => true]);
-    }
-}

src/Http/Controllers/UnifiSettingsController.php

@@ -10,9 +10,10 @@ use Inertia\Inertia;
 
 class UnifiSettingsController extends Controller
 {
-    public function edit()
+    public function edit(?string $tab = null)
     {
         return Inertia::render('Unifi/Settings', [
+            'activeTab'              => $tab,
             'controllerUrl'          => Setting::get('unifi.controller_url', ''),
             'hasApiKey'              => (bool) Setting::get('unifi.api_key'),
             'site'                   => Setting::get('unifi.site', 'default'),
@@ -35,6 +36,9 @@ class UnifiSettingsController extends Controller
             'ppskSchedulingEnabled'   => (bool) Setting::get('unifi.ppsk_scheduling.enabled', false),
             'apiEnabled'              => (bool) Setting::get('unifi.api.enabled', false),
             'apiToken'                => Setting::get('unifi.api_token', null),
+            'guestCardEnabled'        => (bool) Setting::get('unifi.guest_card.enabled', false),
+            'guestCardSsid'           => Setting::get('unifi.guest_card.ssid', ''),
+            'guestCardTitle'          => Setting::get('unifi.guest_card.title', ''),
         ]);
     }
 
@@ -73,6 +77,9 @@ class UnifiSettingsController extends Controller
             'rotation_wordlist'       => 'nullable|string|max:20000',
             'ppsk_scheduling_enabled' => 'boolean',
             'api_enabled'             => 'boolean',
+            'guest_card_enabled'      => 'boolean',
+            'guest_card_ssid'         => 'nullable|string|max:100',
+            'guest_card_title'        => 'nullable|string|max:100',
         ]);
 
         Setting::set('unifi.controller_url', rtrim($request->controller_url, '/'));
@@ -100,6 +107,9 @@ class UnifiSettingsController extends Controller
         Setting::set('unifi.password_rotation.wordlist',    $request->input('rotation_wordlist', ''));
         Setting::set('unifi.ppsk_scheduling.enabled',        $request->boolean('ppsk_scheduling_enabled') ? '1' : '');
         Setting::set('unifi.api.enabled',                    $request->boolean('api_enabled')             ? '1' : '');
+        Setting::set('unifi.guest_card.enabled',             $request->boolean('guest_card_enabled')      ? '1' : '');
+        Setting::set('unifi.guest_card.ssid',                trim((string) $request->input('guest_card_ssid', '')));
+        Setting::set('unifi.guest_card.title',               trim((string) $request->input('guest_card_title', '')));
 
         \Illuminate\Support\Facades\Cache::forget('unifi:api_prefix:' . md5(rtrim($request->controller_url, '/')));
 

src/Http/Controllers/WifiController.php

@@ -149,8 +149,18 @@ class WifiController extends Controller
                     $name = $networksById[$nconfId]['name'] ?? null;
                 }
 
-                // Match by unifi_id, or by passphrase for a held embedded record re-appearing
+                // Match in priority order:
+                //   1. by current unifi_id (already-synced row)
+                //   2. by name within this wlan (catches rotation: passphrase
+                //      changed → synthetic id changed → row identity unchanged)
+                //   3. by passphrase among held rows (legacy fallback for
+                //      cases where name wasn't ingested)
                 $record = UnifiPpsk::where('unifi_id', $uid)->first()
+                       ?? ($name
+                            ? UnifiPpsk::where('wlan_id', $wlanId)->where('name', $name)
+                                ->orderByRaw("FIELD(state, 'active', 'held')")
+                                ->first()
+                            : null)
                        ?? UnifiPpsk::where('wlan_id', $wlanId)
                             ->where('x_passphrase', $pass)
                             ->where('state', 'held')
@@ -174,8 +184,8 @@ class WifiController extends Controller
                 }
             }
 
-            // Only mark as held when we have confirmed live IDs —
-            // never wipe on an empty API response (prevents false-holds on API failures)
+            // Mark non-matching active rows as held — but ONLY if there's no
+            // other active row with the same name we just reconnected.
             if (! empty($liveIds)) {
                 UnifiPpsk::where('wlan_id', $wlanId)
                     ->where('state', 'active')
@@ -184,6 +194,47 @@ class WifiController extends Controller
                     ->update(['state' => 'held', 'unifi_id' => null]);
             }
 
+            // For each active row, salvage any rotate_password / schedule
+            // settings from the held tombstones with the same name BEFORE
+            // we prune them. Otherwise a row that had rotate=on loses the
+            // flag every time a rotation changes its synthetic id.
+            $activeRows = UnifiPpsk::where('wlan_id', $wlanId)
+                ->where('state', 'active')
+                ->whereNotNull('name')
+                ->get();
+            foreach ($activeRows as $active) {
+                $heldWithSettings = UnifiPpsk::where('wlan_id', $wlanId)
+                    ->where('state', 'held')
+                    ->where('name', $active->name)
+                    ->where(fn ($q) => $q
+                        ->where('rotate_password', true)
+                        ->orWhereNotNull('schedule'))
+                    ->orderByDesc('updated_at')
+                    ->first();
+                if (! $heldWithSettings) continue;
+
+                $patch = [];
+                if ($heldWithSettings->rotate_password && ! $active->rotate_password) {
+                    $patch['rotate_password'] = true;
+                }
+                if ($heldWithSettings->schedule && ! $active->schedule) {
+                    $patch['schedule'] = $heldWithSettings->schedule;
+                }
+                if ($patch) $active->update($patch);
+            }
+
+            // Prune obsolete held rows: any held row whose name matches an
+            // active row in the same wlan is a stale tombstone — its
+            // settings have been salvaged above, and its data has been
+            // superseded by the active one.
+            $activeNames = $activeRows->pluck('name')->filter()->unique();
+            if ($activeNames->isNotEmpty()) {
+                UnifiPpsk::where('wlan_id', $wlanId)
+                    ->where('state', 'held')
+                    ->whereIn('name', $activeNames)
+                    ->delete();
+            }
+
             $dbRecords = UnifiPpsk::where('wlan_id', $wlanId)
                 ->orderByRaw("FIELD(state, 'active', 'held')")
                 ->orderBy('name')
@@ -298,9 +349,9 @@ class WifiController extends Controller
                         $unifi->updateEmbeddedPpsk($record->wlan_id, $record->x_passphrase, $newPass, $record->name);
                         $data['unifi_id'] = 'emb_' . substr(hash('sha256', $record->wlan_id . ':' . $newPass), 0, 32);
 
-                        // Also update sibling WLANs (banded SSID — same name
-                        // on 2.4 and 5GHz are separate wlanconf rows).
-                        foreach ($unifi->getWlanSiblings($record->wlan_id) as $siblingWlanId) {
+                        // Also update grouped WLAN siblings (user-defined
+                        // SSID groups, falling back to same-name).
+                        foreach ($unifi->getGroupedWlans($record->wlan_id) as $siblingWlanId) {
                             $sibling = UnifiPpsk::where('wlan_id', $siblingWlanId)
                                 ->where('name', $record->name)
                                 ->where('state', 'active')
@@ -314,7 +365,11 @@ class WifiController extends Controller
                                     ]);
                                 }
                             } catch (\Throwable $e) {
-                                \Illuminate\Support\Facades\Log::warning('unifi.ppsk_sibling_update_failed', [
+                                // PPSK absent on this band is fine — just
+                                // means it isn't mirrored. Anything else
+                                // gets warning-logged.
+                                $level = str_contains($e->getMessage(), 'not found') ? 'info' : 'warning';
+                                \Illuminate\Support\Facades\Log::log($level, 'unifi.ppsk_sibling_update', [
                                     'sibling_wlan' => $siblingWlanId,
                                     'error'        => $e->getMessage(),
                                 ]);

src/Models/UnifiPageGrant.php

@@ -1,58 +0,0 @@
-<?php
-
-namespace Dashboard\Unifi\Models;
-
-use App\Models\NavItem;
-use App\Models\User;
-use Illuminate\Database\Eloquent\Model;
-use Illuminate\Database\Eloquent\Relations\BelongsTo;
-
-class UnifiPageGrant extends Model
-{
-    protected $table = 'unifi_page_grants';
-
-    protected $fillable = [
-        'nav_item_id',
-        'grantee_type',
-        'grantee_id',
-        'granted_by_user_id',
-    ];
-
-    public function navItem(): BelongsTo
-    {
-        return $this->belongsTo(NavItem::class);
-    }
-
-    public function grantedBy(): BelongsTo
-    {
-        return $this->belongsTo(User::class, 'granted_by_user_id');
-    }
-
-    /**
-     * True iff $user is allowed to access $navItem under strict allowlist
-     * semantics:
-     *  * super-admins (the model-level flag) always pass
-     *  * otherwise the user must be a direct grantee, OR be in a group
-     *    that is a grantee
-     *
-     * A page with NO grants saved is only visible to super-admins —
-     * the admin must explicitly authorize everyone else via the
-     * Access tab.
-     */
-    public static function userCanAccess(User $user, NavItem $navItem): bool
-    {
-        if ($user->is_super_admin) return true;
-
-        $groupIds = $user->groups()->pluck('groups.id');
-
-        return static::where('nav_item_id', $navItem->id)
-            ->where(function ($q) use ($user, $groupIds) {
-                $q->where(function ($u) use ($user) {
-                    $u->where('grantee_type', 'user')->where('grantee_id', $user->id);
-                })->orWhere(function ($g) use ($groupIds) {
-                    $g->where('grantee_type', 'group')->whereIn('grantee_id', $groupIds);
-                });
-            })
-            ->exists();
-    }
-}

src/Services/UnifiApiClient.php

@@ -312,6 +312,88 @@ class UnifiApiClient
         return $this->put("/rest/wlanconf/{$wlanId}", $data);
     }
 
+    /**
+     * Find every other WLAN that should rotate/update together with this
+     * one. Authoritative source: the user-defined "SSID groups" setting
+     * (unifi.ssid_groups) from the WiFi Networks page, which lets the
+     * operator manually couple WLANs that may have different SSID names.
+     *
+     * Falls back to same-SSID-name siblings for installs that haven't
+     * configured groups yet.
+     *
+     * Returns an array of sibling wlan IDs (excludes $wlanId itself).
+     */
+    public function getGroupedWlans(string $wlanId): array
+    {
+        $groupsJson = Setting::get('unifi.ssid_groups', '{}');
+        $groups     = json_decode($groupsJson, true);
+        if (is_array($groups)) {
+            foreach ($groups as $wlanIds) {
+                if (! is_array($wlanIds)) continue;
+                if (in_array($wlanId, $wlanIds, true)) {
+                    return array_values(array_filter($wlanIds, fn ($id) => $id !== $wlanId));
+                }
+            }
+        }
+        return $this->getWlanSiblings($wlanId);
+    }
+
+    /**
+     * Verify an embedded PPSK has the expected passphrase right now.
+     * Used after an update to confirm the change actually applied —
+     * UniFi sometimes 200s an update that didn't stick (cluster sync
+     * race, hot-restart in progress, etc.).
+     *
+     * Returns ['ok' => true] on a clean match, or
+     * ['ok' => false, 'reason' => 'fetch_failed'|'not_found'|'mismatch']
+     * with optional 'error' on fetch failures.
+     */
+    public function verifyEmbeddedPpsk(string $wlanId, string $name, string $expectedPassphrase): array
+    {
+        try {
+            $entries = $this->getPpskEntries($wlanId);
+        } catch (\Throwable $e) {
+            return ['ok' => false, 'reason' => 'fetch_failed', 'error' => $e->getMessage()];
+        }
+
+        $networkconfId = $this->findNetworkconfIdByName($name);
+
+        foreach ($entries as $e) {
+            $entryName     = $e['name'] ?? $e['label'] ?? $e['username'] ?? $e['privatePskName'] ?? null;
+            $entryNetId    = $e['networkconf_id'] ?? null;
+            $entryMatches  = ($networkconfId !== null && $entryNetId === $networkconfId)
+                          || ($entryName !== null && $entryName === $name);
+            if (! $entryMatches) continue;
+
+            $entryPass = $e['x_passphrase'] ?? $e['password'] ?? $e['passphrase'] ?? null;
+            return $entryPass === $expectedPassphrase
+                ? ['ok' => true]
+                : ['ok' => false, 'reason' => 'mismatch'];
+        }
+        return ['ok' => false, 'reason' => 'not_found'];
+    }
+
+    /**
+     * Look up a networkconf (VLAN/network) by its display name. Embedded
+     * PPSKs on this controller use networkconf_id as their stable
+     * identifier — the human "name" the operator sees is actually the
+     * network's name.
+     */
+    private function findNetworkconfIdByName(string $name): ?string
+    {
+        try {
+            $networks = $this->getNetworkConfs();
+        } catch (\Throwable) {
+            return null;
+        }
+        foreach ($networks as $n) {
+            if (($n['name'] ?? null) === $name) {
+                return $n['_id'] ?? null;
+            }
+        }
+        return null;
+    }
+
     /**
      * Find sibling WLAN configs — same SSID name, different _id. UniFi
      * splits a "banded" SSID (band-steering disabled) into one wlanconf
@@ -548,10 +630,13 @@ class UnifiApiClient
             throw new \RuntimeException('WLAN has no embedded PPSKs to update.');
         }
 
-        // Match in this order — most reliable first:
-        //   1. by PPSK name (if provided) — survives passphrase drift
-        //      caused by manual edits or previous out-of-sync rotations.
-        //   2. by current passphrase (legacy)
+        // Embedded PPSKs on this controller don't carry a name field —
+        // the human label ("GUEST", "3DPrinters", …) is the *network's*
+        // name, and each entry references it via networkconf_id. So when
+        // the caller passes a name, first resolve it to a networkconf_id
+        // and match on that. Falls back to entry-level name (other
+        // controller versions DO put a name on the entry) and finally
+        // to current passphrase.
         $applyUpdate = function (array &$e) use ($newPassphrase) {
             if (array_key_exists('x_passphrase', $e)) $e['x_passphrase'] = $newPassphrase;
             if (array_key_exists('password',     $e)) $e['password']     = $newPassphrase;
@@ -561,8 +646,21 @@ class UnifiApiClient
             }
         };
 
+        $networkconfId = ($name !== null && $name !== '') ? $this->findNetworkconfIdByName($name) : null;
+
         $matched = false;
-        if ($name !== null && $name !== '') {
+        if ($networkconfId !== null) {
+            foreach ($entries as &$e) {
+                if (($e['networkconf_id'] ?? null) === $networkconfId) {
+                    $applyUpdate($e);
+                    $matched = true;
+                    break;
+                }
+            }
+            unset($e);
+        }
+
+        if (! $matched && $name !== null && $name !== '') {
             foreach ($entries as &$e) {
                 $entryName = $e['name'] ?? $e['label'] ?? $e['username'] ?? $e['privatePskName'] ?? null;
                 if ($entryName === $name) {
@@ -589,7 +687,7 @@ class UnifiApiClient
         if (! $matched) {
             throw new \RuntimeException(
                 'Embedded PPSK not found' .
-                ($name !== null ? " by name \"{$name}\"" : '') .
+                ($name !== null ? " for network \"{$name}\"" : '') .
                 ' or by current passphrase.'
             );
         }

src/Services/WebhookCheckService.php

@@ -181,7 +181,11 @@ class WebhookCheckService
             $prev     = DeviceState::where('device_mac', $mac)->first();
             if (! $prev) continue;
 
-            // Skip planned reboots — these are intentional, not alerts
+            // Skip planned reboots — these are intentional, not alerts.
+            // Two layers: a global suppression window set by RebootAllAps
+            // (Setting, survives any cache driver), plus the per-MAC
+            // cache keys for finer granularity.
+            if ($this->inGlobalRebootSuppression()) continue;
             if (Cache::has('unifi:planned_reboot:' . strtolower($mac))) continue;
 
             if ($comingOnline) {
@@ -509,6 +513,8 @@ class WebhookCheckService
     private function checkReboot($aps, array $filter): array
     {
         $alerts = [];
+        if ($this->inGlobalRebootSuppression()) return $alerts;
+
         foreach ($aps as $ap) {
             if (! empty($filter) && ! in_array($ap['mac'], $filter)) continue;
             if (Cache::has('unifi:planned_reboot:' . strtolower($ap['mac']))) continue;
@@ -584,6 +590,24 @@ class WebhookCheckService
         return self::buildPlatformPayload($url, $message, $fullPayload);
     }
 
+    /**
+     * Is a fleet reboot in progress right now? RebootAllAps stamps a
+     * suppression-until timestamp as a Setting; while that timestamp
+     * is in the future, we skip all device-offline / device-online /
+     * unexpected-reboot alerts to avoid flooding webhooks during the
+     * known maintenance window.
+     */
+    private function inGlobalRebootSuppression(): bool
+    {
+        $until = \App\Models\Setting::get('unifi.reboot_suppression_until');
+        if (! $until) return false;
+        try {
+            return \Carbon\Carbon::parse($until)->isFuture();
+        } catch (\Throwable) {
+            return false;
+        }
+    }
+
     /**
      * Public/static helper so the test-webhook endpoint produces the
      * same per-platform payload shape that real events do.

src/UnifiServiceProvider.php

@@ -2,11 +2,7 @@
 
 namespace Dashboard\Unifi;
 
-use App\Models\DashboardApp;
 use App\Models\NavItem;
-use Dashboard\Unifi\Models\UnifiPageGrant;
-use Illuminate\Routing\Events\RouteMatched;
-use Illuminate\Support\Facades\Event;
 use Illuminate\Support\ServiceProvider;
 
 class UnifiServiceProvider extends ServiceProvider
@@ -25,36 +21,45 @@ class UnifiServiceProvider extends ServiceProvider
         $this->loadRoutesFrom(__DIR__ . '/routes/unifi.php');
         $this->loadMigrationsFrom(__DIR__ . '/../database/migrations');
 
-        // Per-page access enforcement for unifi routes. If a unifi page has
-        // any UnifiPageGrant rows, only super-admins and granted users/
-        // groups can hit it; otherwise (no grants) it's open per the existing
-        // permission middleware. Super-admins always bypass.
-        Event::listen(RouteMatched::class, function (RouteMatched $event) {
-            $routeName = $event->route->getName();
-            if (! $routeName || ! str_starts_with($routeName, 'unifi.')) return;
-
-            $user = $event->request->user();
-            if (! $user || $user->is_super_admin) return;
-
+        // "/" home card: guest Wi-Fi network + current rotating password +
+        // QR (re-renders when the password changes). Self-hides until enabled
+        // and a password has been rotated.
+        //
+        // The ONE card in the platform that earned a NEW permission key rather
+        // than reusing one. It cannot be universal — the payload is a live
+        // credential, and publishing it to every student and parent is the exact
+        // hole GuestCardController::data was written to close. And no existing
+        // unifi key fits: unifi.stats is the network dashboards, unifi.settings is
+        // the controller connection, and handing the front desk either one to let
+        // them read a guest password would widen access, not reuse it. So the
+        // granularity goes in the catalogue (same move as the papercut/inventory
+        // split), and the key is grantable to non-unifi staff — which is the whole
+        // point of a home-page card.
+        //
+        // Declared in composer.json extra.dashboard.permissions, so the catalogue
+        // row appears when unifi is installed/updated — NOT seeded to any group.
         try {
-                $appId = DashboardApp::where('slug', 'unifi')->value('id');
-                $item  = NavItem::where('route_name', $routeName)
-                    ->where('app_id', $appId)
-                    ->first();
-                if (! $item) return;
-
-                if (! UnifiPageGrant::userCanAccess($user, $item)) {
-                    // 404 instead of 403 — don't leak that the page
-                    // exists. The Access tab is the only way in.
-                    abort(404);
-                }
+            app(\App\Support\DashboardCardRegistry::class)->register(
+                'unifi.guest_wifi',
+                'Guest Wi-Fi',
+                'UnifiGuestWifi',
+                fn (\App\Models\User $user) => \Dashboard\Unifi\Http\Controllers\GuestCardController::resolve($user),
+                'The guest network name, current password, and a join QR code — updates automatically when the password rotates.',
+                permission: 'unifi.guest_wifi',
+                // So the permission screens can say "granted, but not switched
+                // on yet" rather than leaving a grantee staring at a home page
+                // with nothing new on it.
+                configured: fn () => \Dashboard\Unifi\Http\Controllers\GuestCardController::configured(),
+            );
         } catch (\Throwable) {
-                // unifi_page_grants table may not exist yet on a fresh
-                // install before this snap-in's migrations have run —
-                // fail open in that narrow window.
+            // Older shell without the card registry — skip.
         }
-        });
 
+        // Tell the shell's nav sidebar which unifi nav items the user
+        // can see: pages whose required_permission the user holds through
+        // groups, plus pages granted via the Settings → Access tab. The
+        // shell also folds these grants back into User::can()/allPermissions
+        // so the route-level permission middleware passes for grantees.
         if ($this->app->runningInConsole()) {
             $this->commands([
                 Console\CheckWebhooks::class,
@@ -69,4 +74,26 @@ class UnifiServiceProvider extends ServiceProvider
             ], 'unifi-config');
         }
     }
+
+    /**
+     * Group + direct permissions only. Deliberately NOT allPermissions():
+     * the shell folds page-grant permissions back into allPermissions/can,
+     * so using it here would turn a single granted page into every page
+     * carrying the same permission.
+     */
+    public static function realPermissionKeysFor(\App\Models\User $user): \Illuminate\Support\Collection
+    {
+        if ($user->is_super_admin) {
+            return \App\Models\Permission::pluck('key');
+        }
+
+        $direct = $user->directPermissions()->get();
+
+        return \App\Models\Permission::whereHas('groups', fn ($q) => $q->whereIn('group_id', $user->groups()->pluck('groups.id')))
+            ->pluck('key')
+            ->merge($direct->where('granted', true)->pluck('permission_key'))
+            ->diff($direct->where('granted', false)->pluck('permission_key'))
+            ->unique()
+            ->values();
+    }
 }

src/routes/unifi.php

@@ -69,19 +69,12 @@ Route::middleware(['web', 'auth', 'app.access:unifi'])
         // ── Settings ─────────────────────────────────────────────────────────
         Route::middleware('permission:unifi.settings')->group(function () {
             Route::get('/settings',        [UnifiSettingsController::class, 'edit'])          ->name('settings');
+            Route::get('/settings/{tab}',  [UnifiSettingsController::class, 'edit'])
+                ->where('tab', 'connection|tasks|logs|access')->name('settings.tab');
             Route::post('/settings',       [UnifiSettingsController::class, 'update'])        ->name('settings.update');
             Route::post('/settings/test',  [UnifiSettingsController::class, 'testConnection'])->name('settings.test');
             Route::post('/settings/sites', [UnifiSettingsController::class, 'fetchSites'])    ->name('settings.sites');
 
-            // Page Access — super-admin only. Lists unifi pages and lets
-            // operators assign per-page user/group grants.
-            Route::middleware('super.admin')->group(function () {
-                Route::get('/settings/pages-access',                [UnifiPagesAccessController::class, 'index'])      ->name('settings.pages-access.index');
-                Route::get('/settings/pages-access/users/search',   [UnifiPagesAccessController::class, 'searchUsers'])->name('settings.pages-access.users.search');
-                Route::get('/settings/pages-access/groups/search',  [UnifiPagesAccessController::class, 'searchGroups'])->name('settings.pages-access.groups.search');
-                Route::put('/settings/pages-access/{navItem}',      [UnifiPagesAccessController::class, 'update'])     ->name('settings.pages-access.update');
-            });
-
             // Cron logs — read-only history of scheduled-task runs.
             Route::get('/settings/cron-logs', [UnifiCronLogsController::class, 'index'])->name('settings.cron-logs.index');
 
@@ -99,6 +92,15 @@ Route::middleware(['web', 'auth', 'app.access:unifi'])
         });
     });
 
+// ── Guest Wi-Fi home-card poll. Authorises inside the controller against the
+// card's own visibility (unifi.guest_wifi) — it returns a live credential, so
+// `auth` alone is not a gate. Deliberately outside the permission groups above
+// because it's a home-page widget, not a unifi page: unifi.guest_wifi is
+// grantable to front-desk staff without any other network access. ──
+Route::middleware(['web', 'auth'])
+    ->get('/app/unifi/guest-card/data', [\Dashboard\Unifi\Http\Controllers\GuestCardController::class, 'data'])
+    ->name('unifi.guest-card.data');
+
 // ── Public API (token-protected) ──────────────────────────────────────────
 // External integrations (signage, kiosks) hit these without session auth.
 Route::prefix('api/unifi')->name('unifi.api.')->group(function () {
@@ -110,3 +112,21 @@ Route::prefix('api/unifi')->name('unifi.api.')->group(function () {
 Route::middleware(['web', 'auth'])
     ->get('/portal/wifi/callback', [PortalController::class, 'captiveCallback'])
     ->name('unifi.portal.callback');
+
+/*
+ * Let a user disconnect their OWN device from the captive-portal denial page.
+ *
+ * The admin route for this (unifi.portal.sessions.disconnect) sits behind
+ * `app.access:unifi` + `permission:unifi.auth`, so a student who is told "you
+ * already have 3 devices connected, disconnect one" was blocked by middleware
+ * before reaching the action — the page's `can_disconnect: true` was a promise
+ * the routing could not keep.
+ *
+ * Safe to expose with only `auth`: disconnectSession() already authorises
+ * owner-or-unifi.auth itself (`abort_if($session->user_id !== auth()->id() && !
+ * auth()->user()->can('unifi.auth'), 403)`), so a non-owner still gets 403. The
+ * admin route is left exactly as it was rather than loosened.
+ */
+Route::middleware(['web', 'auth'])
+    ->post('/portal/wifi/sessions/{session}/disconnect', [PortalController::class, 'disconnectSession'])
+    ->name('unifi.portal.self-disconnect');