fix(ppsk sync): match by name + salvage settings, prune dup tombstones

Every rotation changes an embedded PPSK's synthetic id (it's derived
from sha256(wlan_id : passphrase)). The ingest sync matched only by
unifi_id, so after rotation the row's id was "new" — the sync created
a fresh active row and marked the previous one held. Over multiple
rotations this accumulated: each rotation left a held tombstone, and
the rotate_password / schedule flags were stuck on the original
tombstone instead of transferring to the new active row.

Dev's GUEST PPSK had 3 rows after a few rotations: two held (with
rotate_password=true on the first), one active with rotate=false.
Future rotations would silently skip that PPSK because the active row
no longer had the rotate flag set.

Fix in three layers, all in WifiController::ppskIndex:

1. Match priority extended: unifi_id → name within wlan → held by
   passphrase. The name match means a passphrase change just updates
   the existing row in place. No more new-row creation per rotation.

2. Salvage step before pruning: for each active row, scan held
   tombstones with the same name and copy over rotate_password and
   schedule. Operator's rotation opt-in survives history.

3. Prune step: held rows with the same name as an active row in the
   same wlan are now hard-deleted (their settings were just salvaged,
   their data is stale). Keeps the WiFi modal clean instead of
   accumulating phantoms.

v1.10.2.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

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.8.1",
+    "version": "1.10.2",
     "type": "library",
     "license": "MIT",
     "autoload": {

src/Console/RotatePasswords.php

@@ -81,24 +81,22 @@ class RotatePasswords extends Command
                 try {
                     if (str_starts_with((string) $ppsk->unifi_id, 'emb_')) {
                         // Embedded PPSK: update inside the parent WLAN object.
-                        // Synthetic ID is derived from the new passphrase, so update it too.
-                        $unifi->updateEmbeddedPpsk($ppsk->wlan_id, $ppsk->x_passphrase, $newPass);
+                        // Match by name (most reliable) — falls back to
+                        // passphrase if name is missing.
+                        $unifi->updateEmbeddedPpsk($ppsk->wlan_id, $ppsk->x_passphrase, $newPass, $ppsk->name);
                         $newUid = 'emb_' . substr(hash('sha256', $ppsk->wlan_id . ':' . $newPass), 0, 32);
-                        $oldPass = $ppsk->x_passphrase;
                         $ppsk->update(['x_passphrase' => $newPass, 'unifi_id' => $newUid]);
 
                         // Sibling WLANs (same SSID name on a different band):
-                        // their embedded PPSK with the same name also needs
-                        // to rotate to the same new password so the SSID's
-                        // 2.4/5GHz halves stay in sync.
+                        // 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) {
                             $sibling = UnifiPpsk::where('wlan_id', $siblingWlanId)
                                 ->where('name', $ppsk->name)
                                 ->where('state', 'active')
                                 ->first();
-                            $siblingOldPass = $sibling?->x_passphrase ?? $oldPass;
                             try {
-                                $unifi->updateEmbeddedPpsk($siblingWlanId, $siblingOldPass, $newPass);
+                                $unifi->updateEmbeddedPpsk($siblingWlanId, $sibling?->x_passphrase, $newPass, $ppsk->name);
                                 if ($sibling) {
                                     $sibling->update([
                                         'x_passphrase' => $newPass,
@@ -106,6 +104,18 @@ class RotatePasswords extends Command
                                     ]);
                                 }
                             } catch (\Throwable $e) {
+                                // "Not found" in a sibling just means the
+                                // PPSK isn't mirrored on that band — totally
+                                // normal if GUEST was only configured on one
+                                // band. Skip quietly; don't poison the
+                                // run status.
+                                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()];
                             }

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')
@@ -293,9 +344,9 @@ class WifiController extends Controller
                 if (! empty($unifiUpdate)) {
                     if (str_starts_with($record->unifi_id, 'emb_') && isset($unifiUpdate['x_passphrase'])) {
                         // Embedded PPSK update path — modify the WLAN's embedded array.
+                        // Match by name (reliable across drift).
                         $newPass = $unifiUpdate['x_passphrase'];
-                        $oldPass = $record->x_passphrase;
-                        $unifi->updateEmbeddedPpsk($record->wlan_id, $oldPass, $newPass);
+                        $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
@@ -305,9 +356,8 @@ class WifiController extends Controller
                                 ->where('name', $record->name)
                                 ->where('state', 'active')
                                 ->first();
-                            $siblingOldPass = $sibling?->x_passphrase ?? $oldPass;
                             try {
-                                $unifi->updateEmbeddedPpsk($siblingWlanId, $siblingOldPass, $newPass);
+                                $unifi->updateEmbeddedPpsk($siblingWlanId, $sibling?->x_passphrase, $newPass, $record->name);
                                 if ($sibling) {
                                     $sibling->update([
                                         'x_passphrase' => $newPass,
@@ -315,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/Services/UnifiApiClient.php

@@ -538,7 +538,7 @@ class UnifiApiClient
      * no controller-side ID. Only changes the entry's passphrase; name
      * isn't separately addressable on embedded PPSKs.
      */
-    public function updateEmbeddedPpsk(string $wlanId, string $oldPassphrase, string $newPassphrase): array
+    public function updateEmbeddedPpsk(string $wlanId, ?string $oldPassphrase, string $newPassphrase, ?string $name = null): array
     {
         $wlanResp = $this->get("/rest/wlanconf/{$wlanId}");
         $wlan     = $wlanResp[0] ?? $wlanResp;
@@ -548,26 +548,50 @@ class UnifiApiClient
             throw new \RuntimeException('WLAN has no embedded PPSKs to update.');
         }
 
-        $matched = false;
-        foreach ($entries as &$e) {
-            $current = $e['x_passphrase'] ?? $e['password'] ?? $e['passphrase'] ?? null;
-            if ($current === $oldPassphrase) {
-                // Preserve whichever field name the controller is using.
-                if (array_key_exists('x_passphrase', $e))  $e['x_passphrase'] = $newPassphrase;
-                if (array_key_exists('password', $e))       $e['password']     = $newPassphrase;
-                if (array_key_exists('passphrase', $e))     $e['passphrase']   = $newPassphrase;
-                // If none of the above existed, default to password (most common on embedded).
-                if (! isset($e['x_passphrase']) && ! isset($e['password']) && ! isset($e['passphrase'])) {
-                    $e['password'] = $newPassphrase;
-                }
-                $matched = true;
-                break;
+        // 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)
+        $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;
+            if (array_key_exists('passphrase',   $e)) $e['passphrase']   = $newPassphrase;
+            if (! isset($e['x_passphrase']) && ! isset($e['password']) && ! isset($e['passphrase'])) {
+                $e['password'] = $newPassphrase;
             }
+        };
+
+        $matched = false;
+        if ($name !== null && $name !== '') {
+            foreach ($entries as &$e) {
+                $entryName = $e['name'] ?? $e['label'] ?? $e['username'] ?? $e['privatePskName'] ?? null;
+                if ($entryName === $name) {
+                    $applyUpdate($e);
+                    $matched = true;
+                    break;
+                }
+            }
+            unset($e);
+        }
+
+        if (! $matched && $oldPassphrase !== null && $oldPassphrase !== '') {
+            foreach ($entries as &$e) {
+                $current = $e['x_passphrase'] ?? $e['password'] ?? $e['passphrase'] ?? null;
+                if ($current === $oldPassphrase) {
+                    $applyUpdate($e);
+                    $matched = true;
+                    break;
+                }
+            }
+            unset($e);
         }
-        unset($e);
 
         if (! $matched) {
-            throw new \RuntimeException('Embedded PPSK not found by current passphrase.');
+            throw new \RuntimeException(
+                'Embedded PPSK not found' .
+                ($name !== null ? " by name \"{$name}\"" : '') .
+                ' or by current passphrase.'
+            );
         }
 
         // UniFi REST expects the full WLAN object on PUT — send what we