Complete Phase 4: security hardening, player/playlist/admin UI, docs

Security:
- New internal/netguard package: podcast feed/enclosure fetching now
  refuses to dial non-public IPs (loopback/RFC1918/link-local/cloud
  metadata/CGNAT), validated per-connection including across redirects,
  closing an SSRF gap where a malicious or compromised feed URL could
  probe the server's internal network. Configurable via
  VIBESONIC_PODCASTS_ALLOW_PRIVATE_NETWORKS for intentional LAN feeds.
- Podcast episode downloads capped at 4GB (was unbounded, disk-exhaustion risk)
- Cover art decoding now rejects images above a 40-megapixel budget
  before full decode (decompression-bomb guard)
- HTTP server sets ReadHeaderTimeout (slowloris hardening)
- Admin folder-scan redirect now validated as same-site instead of
  trusting the raw Referer header (open-redirect fix)
- Legacy Subsonic token/salt auth now uses a constant-time comparison

Web UI completion:
- Persistent player: shuffle and repeat (off/all/one) controls, wired
  into queue advance/prev logic and persisted like other player state
- Admin user-permissions form: adminRole toggle (with a guard against
  demoting the last remaining admin) and per-user music-folder access
  checkboxes, backed by existing schema/enforcement that was previously
  unreachable from the UI
- Playlist M3U8 import/export

Docs: added docs/client-compatibility.md (honest tracking template —
no client testing has been performed), docs/deployment.md,
docs/security.md, docs/backup.md; refreshed README and cross-links;
added a footnote in docs/subsonic-compatibility.md distinguishing
spec-standard from VibeSonic-original OpenSubsonic extensions.

Also added Go fuzz tests for the external-auth CIDR/IP parser and the
LRC lyrics parser.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014r98AtcBbevpscWLsfwVvv

web/static/css/app.css

@@ -262,6 +262,10 @@ body {
   font-size: 1.4rem;
 }
 
+.vs-player-btn.active {
+  color: var(--bs-primary);
+}
+
 .vs-player-timeline {
   display: flex;
   align-items: center;

web/static/js/app.js

@@ -26,9 +26,20 @@
     this.ui = ui;
     this.queue = [];
     this.index = -1;
+    this.shuffle = false;
+    this.repeat = "off"; // "off" | "all" | "one"
+    this.shuffleOrder = []; // permutation of queue indices; shufflePos points into it
+    this.shufflePos = -1;
+    try {
+      this.shuffle = localStorage.getItem("vs-shuffle") === "1";
+      var storedRepeat = localStorage.getItem("vs-repeat");
+      if (storedRepeat === "all" || storedRepeat === "one") this.repeat = storedRepeat;
+    } catch (e) {
+      /* storage may be unavailable (private browsing); state just won't persist */
+    }
     this.audio.addEventListener("timeupdate", this._onTimeUpdate.bind(this));
     this.audio.addEventListener("loadedmetadata", this._onTimeUpdate.bind(this));
-    this.audio.addEventListener("ended", this.next.bind(this));
+    this.audio.addEventListener("ended", this._onEnded.bind(this));
     this.audio.addEventListener("play", this._syncPlayIcon.bind(this));
     this.audio.addEventListener("pause", this._syncPlayIcon.bind(this));
   }
@@ -36,10 +47,68 @@
   VibeSonicPlayer.prototype.playQueue = function (songs, startIndex) {
     this.queue = songs;
     this.index = startIndex || 0;
+    this._reshuffle();
     this._loadCurrent();
     this.audio.play().catch(function () {});
   };
 
+  // _reshuffle rebuilds the shuffle order (a Fisher-Yates permutation of
+  // every queue index except the currently-playing one, which is pinned
+  // to the front) whenever the queue changes or shuffle is toggled on,
+  // so "next" has a fresh random order to draw from without immediately
+  // repeating the track that's already playing.
+  VibeSonicPlayer.prototype._reshuffle = function () {
+    var order = [];
+    for (var i = 0; i < this.queue.length; i++) {
+      if (i !== this.index) order.push(i);
+    }
+    for (var j = order.length - 1; j > 0; j--) {
+      var k = Math.floor(Math.random() * (j + 1));
+      var tmp = order[j];
+      order[j] = order[k];
+      order[k] = tmp;
+    }
+    order.unshift(this.index);
+    this.shuffleOrder = order;
+    this.shufflePos = 0;
+  };
+
+  VibeSonicPlayer.prototype.setShuffle = function (on) {
+    this.shuffle = on;
+    try {
+      localStorage.setItem("vs-shuffle", on ? "1" : "0");
+    } catch (e) {}
+    if (on) this._reshuffle();
+    if (this.ui.shuffleBtn) this.ui.shuffleBtn.classList.toggle("active", on);
+  };
+
+  VibeSonicPlayer.prototype.cycleRepeat = function () {
+    this.repeat = this.repeat === "off" ? "all" : this.repeat === "all" ? "one" : "off";
+    try {
+      localStorage.setItem("vs-repeat", this.repeat);
+    } catch (e) {}
+    this._syncRepeatButton();
+  };
+
+  VibeSonicPlayer.prototype._syncRepeatButton = function () {
+    var btn = this.ui.repeatBtn;
+    if (!btn) return;
+    btn.dataset.repeat = this.repeat;
+    btn.classList.toggle("active", this.repeat !== "off");
+    var icon = btn.querySelector("i");
+    if (icon) icon.className = this.repeat === "one" ? "bi bi-repeat-1" : "bi bi-repeat";
+    btn.title = this.repeat === "off" ? "Repeat: off" : this.repeat === "all" ? "Repeat: all" : "Repeat: one";
+  };
+
+  VibeSonicPlayer.prototype._onEnded = function () {
+    if (this.repeat === "one") {
+      this.audio.currentTime = 0;
+      this.audio.play().catch(function () {});
+      return;
+    }
+    this.next();
+  };
+
   VibeSonicPlayer.prototype._loadCurrent = function () {
     var song = this.queue[this.index];
     if (!song) return;
@@ -145,11 +214,25 @@
   };
 
   VibeSonicPlayer.prototype.next = function () {
-    if (this.index + 1 < this.queue.length) {
+    if (!this.queue.length) return;
+    if (this.shuffle) {
+      if (this.shufflePos + 1 < this.shuffleOrder.length) {
+        this.shufflePos++;
+      } else if (this.repeat === "all") {
+        this._reshuffle();
+      } else {
+        return;
+      }
+      this.index = this.shuffleOrder[this.shufflePos];
+    } else if (this.index + 1 < this.queue.length) {
       this.index++;
-      this._loadCurrent();
-      this.audio.play().catch(function () {});
+    } else if (this.repeat === "all") {
+      this.index = 0;
+    } else {
+      return;
     }
+    this._loadCurrent();
+    this.audio.play().catch(function () {});
   };
 
   VibeSonicPlayer.prototype.prev = function () {
@@ -157,11 +240,17 @@
       this.audio.currentTime = 0;
       return;
     }
-    if (this.index > 0) {
+    if (this.shuffle) {
+      if (this.shufflePos <= 0) return;
+      this.shufflePos--;
+      this.index = this.shuffleOrder[this.shufflePos];
+    } else if (this.index > 0) {
       this.index--;
-      this._loadCurrent();
-      this.audio.play().catch(function () {});
+    } else {
+      return;
     }
+    this._loadCurrent();
+    this.audio.play().catch(function () {});
   };
 
   VibeSonicPlayer.prototype.seekTo = function (fraction) {
@@ -241,8 +330,23 @@
       volumeSlider: document.getElementById("vs-volume"),
       starBtn: document.getElementById("vs-now-star"),
       lyricsPanel: document.getElementById("vs-lyrics-panel"),
+      shuffleBtn: document.getElementById("vs-shuffle-btn"),
+      repeatBtn: document.getElementById("vs-repeat-btn"),
     };
     var player = new VibeSonicPlayer(audio, ui);
+    player.setShuffle(player.shuffle);
+    player._syncRepeatButton();
+
+    if (ui.shuffleBtn) {
+      ui.shuffleBtn.addEventListener("click", function () {
+        player.setShuffle(!player.shuffle);
+      });
+    }
+    if (ui.repeatBtn) {
+      ui.repeatBtn.addEventListener("click", function () {
+        player.cycleRepeat();
+      });
+    }
 
     var lyricsBtn = document.getElementById("vs-lyrics-btn");
     if (lyricsBtn && ui.lyricsPanel) {

web/templates/admin_user_permissions.html

@@ -4,6 +4,10 @@
     <h2 class="h6">{{.Data.Username}}</h2>
     <form method="post" action="/admin/users/{{.Data.ID}}/permissions">
       {{template "csrf_field" .CSRFToken}}
+      <div class="form-check">
+        <input class="form-check-input" type="checkbox" name="admin" value="1" id="p_admin" {{if .Data.IsAdmin}}checked{{end}}>
+        <label class="form-check-label" for="p_admin"><strong>Administrator</strong></label>
+      </div>
       <div class="form-check">
         <input class="form-check-input" type="checkbox" name="settings" value="1" id="p_settings" {{if .Data.Permissions.Settings}}checked{{end}}>
         <label class="form-check-label" for="p_settings">Settings</label>
@@ -48,8 +52,21 @@
         <input class="form-check-input" type="checkbox" name="video_conversion" value="1" id="p_video" {{if .Data.Permissions.VideoConversion}}checked{{end}}>
         <label class="form-check-label" for="p_video">Video Conversion</label>
       </div>
-      <button type="submit" class="btn btn-primary btn-sm">Save</button>
-      <a href="/admin/users" class="btn btn-sm btn-outline-secondary">Cancel</a>
+      <hr>
+      <h3 class="h6">Music Folder Access</h3>
+      <p class="small text-body-secondary">Leave all unchecked for unrestricted access to every folder.</p>
+      {{range .Data.Folders}}
+      <div class="form-check">
+        <input class="form-check-input" type="checkbox" name="music_folders" value="{{.ID}}" id="f_{{.ID}}" {{if index $.Data.AllowedFolders .ID}}checked{{end}}>
+        <label class="form-check-label" for="f_{{.ID}}">{{.Name}}</label>
+      </div>
+      {{else}}
+      <p class="small text-body-secondary">No music folders configured.</p>
+      {{end}}
+      <div class="mt-3">
+        <button type="submit" class="btn btn-primary btn-sm">Save</button>
+        <a href="/admin/users" class="btn btn-sm btn-outline-secondary">Cancel</a>
+      </div>
     </form>
   </div>
 </div>

web/templates/partials/footer.html

@@ -24,9 +24,11 @@
   </div>
   <div class="vs-player-controls">
     <div class="vs-player-buttons">
+      <button id="vs-shuffle-btn" type="button" class="vs-player-btn" title="Shuffle"><i class="bi bi-shuffle"></i></button>
       <button id="vs-prev-btn" type="button" class="vs-player-btn" title="Previous (J)"><i class="bi bi-skip-start-fill"></i></button>
       <button id="vs-play-btn" type="button" class="vs-player-btn vs-play" title="Play/Pause (Space)"><i class="bi bi-play-fill"></i></button>
       <button id="vs-next-btn" type="button" class="vs-player-btn" title="Next (L)"><i class="bi bi-skip-end-fill"></i></button>
+      <button id="vs-repeat-btn" type="button" class="vs-player-btn" title="Repeat: off" data-repeat="off"><i class="bi bi-repeat"></i></button>
     </div>
     <div class="vs-player-timeline">
       <span id="vs-current-time" class="vs-player-time">0:00</span>

web/templates/playlist.html

@@ -4,12 +4,15 @@
     <h2 class="h5 mb-0">{{.Data.Playlist.Name}}</h2>
     {{if .Data.Playlist.Description}}<div class="text-secondary small">{{.Data.Playlist.Description}}</div>{{end}}
   </div>
-  {{if .Data.Owned}}
-  <form method="post" action="/playlists/{{.Data.Playlist.ID}}/delete" onsubmit="return confirm('Delete this playlist?');">
-    {{template "csrf_field" .CSRFToken}}
-    <button type="submit" class="btn btn-outline-danger btn-sm"><i class="bi bi-trash"></i> Delete</button>
-  </form>
-  {{end}}
+  <div class="d-flex gap-2">
+    <a href="/playlists/{{.Data.Playlist.ID}}/export" class="btn btn-outline-secondary btn-sm"><i class="bi bi-download"></i> Export M3U</a>
+    {{if .Data.Owned}}
+    <form method="post" action="/playlists/{{.Data.Playlist.ID}}/delete" onsubmit="return confirm('Delete this playlist?');">
+      {{template "csrf_field" .CSRFToken}}
+      <button type="submit" class="btn btn-outline-danger btn-sm"><i class="bi bi-trash"></i> Delete</button>
+    </form>
+    {{end}}
+  </div>
 </div>
 {{if .Data.Songs}}{{template "song_rows" .Data.Songs}}{{else}}<p class="text-secondary">This playlist is empty.</p>{{end}}
 {{template "footer" .}}{{end}}

web/templates/playlist_import.html

@@ -0,0 +1,12 @@
+{{define "playlist_import"}}{{template "header" .}}
+<h2 class="h5 mb-3">Import Playlist</h2>
+<form method="post" action="/playlists/import" enctype="multipart/form-data" class="mb-3" style="max-width: 480px;">
+  {{template "csrf_field" .CSRFToken}}
+  <div class="mb-2">
+    <input type="file" name="file" class="form-control" accept=".m3u,.m3u8,audio/x-mpegurl" required>
+  </div>
+  <button type="submit" class="btn btn-primary btn-sm"><i class="bi bi-upload"></i> Import</button>
+  <a href="/playlists" class="btn btn-outline-secondary btn-sm">Cancel</a>
+</form>
+<p class="text-secondary small">Accepts an M3U/M3U8 file. Tracks are matched by file path against your scanned music folders; a new playlist is created from the tracks that match.</p>
+{{template "footer" .}}{{end}}

web/templates/playlist_import_result.html

@@ -0,0 +1,9 @@
+{{define "playlist_import_result"}}{{template "header" .}}
+<h2 class="h5 mb-3">Import Complete</h2>
+<p>
+  Created playlist <a href="/playlists/{{.Data.Playlist.ID}}">{{.Data.Playlist.Name}}</a>
+  with <strong>{{.Data.Matched}}</strong> matched track{{if ne .Data.Matched 1}}s{{end}}
+  {{if .Data.Skipped}}({{.Data.Skipped}} entr{{if eq .Data.Skipped 1}}y{{else}}ies{{end}} could not be matched to a track in your library){{end}}.
+</p>
+<a href="/playlists/{{.Data.Playlist.ID}}" class="btn btn-primary btn-sm">View Playlist</a>
+{{template "footer" .}}{{end}}

web/templates/playlists.html

@@ -1,5 +1,5 @@
 {{define "playlists"}}{{template "header" .}}
-<form method="post" action="/playlists" class="row g-2 mb-4" style="max-width: 480px;">
+<form method="post" action="/playlists" class="row g-2 mb-2" style="max-width: 480px;">
   {{template "csrf_field" .CSRFToken}}
   <div class="col-8">
     <input type="text" name="name" class="form-control" placeholder="New playlist name" required>
@@ -8,6 +8,9 @@
     <button type="submit" class="btn btn-primary w-100"><i class="bi bi-plus-lg"></i> Create</button>
   </div>
 </form>
+<div class="mb-4">
+  <a href="/playlists/import" class="btn btn-outline-secondary btn-sm"><i class="bi bi-upload"></i> Import M3U</a>
+</div>
 
 {{if .Data}}
 <div class="list-group">