feat(server): POST /api/cast/stream-token + secret bootstrap (UPnP slice 2/6)

Adds the client-facing endpoint that issues a signed stream URL for the current track. Authenticated via the standard session cookie. Returns {token, exp, url} where url is a fully-formed stream URL the client passes verbatim to a UPnP / Sonos device's AVTransport.SetAVTransportURI call. expSeconds clamped to [60, 86400]; default 21600 (6h) - long enough to play through any typical track without re-minting mid-playback. MINSTREL_STREAM_SECRET is loaded from env var with a per-machine fallback persisted at <Storage.DataDir>/stream_secret (auto-generated on first boot via 64 random bytes, base64-url-encoded, 0600). The file-based fallback is operator-machine-scoped runtime state, not a user-facing setting - chosen over a DB column to avoid a migration and keep the secret out of cross-instance restores. Operator can override at any time via the env var; default path requires zero config. Tests cover happy-path token issuance + URL formatting, bad-UUID rejection, unauthenticated rejection, the expSeconds clamp at all boundaries, secret env override, auto-gen + file persistence at 0600, second-boot reuse of the persisted file, and rejection of a malformed env value. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-06-03 11:46:57 -04:00
parent 236637fcd3
commit e774097fd8
7 changed files with 429 additions and 2 deletions
@@ -28,7 +28,7 @@ import (
 // Mount attaches /api/* handlers to r. Public endpoints (login) are outside
 // RequireUser; everything else is gated by the middleware. The events writer
 // is shared with the Subsonic mount so /rest/scrobble feeds the same store.
-func Mount(r chi.Router, pool *pgxpool.Pool, logger *slog.Logger, events *playevents.Writer, recCfg config.RecommendationConfig, lidarrCfg *lidarrconfig.Service, lidarrReqs *lidarrrequests.Service, lidarrQuar *lidarrquarantine.Service, tracksSvc *tracks.Service, playlistsSvc *playlists.Service, coverEnricher *coverart.Enricher, coverSettings *coverart.SettingsService, scanner *library.Scanner, scanCfg library.RunScanConfig, scheduler *library.Scheduler, dataDir string, sender mailer.Sender, bus *eventbus.Bus, playlistScheduler *playlists.Scheduler) {
+func Mount(r chi.Router, pool *pgxpool.Pool, logger *slog.Logger, events *playevents.Writer, recCfg config.RecommendationConfig, lidarrCfg *lidarrconfig.Service, lidarrReqs *lidarrrequests.Service, lidarrQuar *lidarrquarantine.Service, tracksSvc *tracks.Service, playlistsSvc *playlists.Service, coverEnricher *coverart.Enricher, coverSettings *coverart.SettingsService, scanner *library.Scanner, scanCfg library.RunScanConfig, scheduler *library.Scheduler, dataDir string, sender mailer.Sender, bus *eventbus.Bus, playlistScheduler *playlists.Scheduler, streamSecret []byte) {
 	rng := rand.New(rand.NewSource(rand.Int63()))
 	h := &handlers{
 		pool: pool, logger: logger, events: events, recCfg: recCfg,
@@ -47,6 +47,7 @@ func Mount(r chi.Router, pool *pgxpool.Pool, logger *slog.Logger, events *playev
 		mailer:            sender,
 		eventbus:          bus,
 		playlistScheduler: playlistScheduler,
+		streamSecret:      streamSecret,
 	}

 	r.Route("/api", func(api chi.Router) {
@@ -97,6 +98,11 @@ func Mount(r chi.Router, pool *pgxpool.Pool, logger *slog.Logger, events *playev
 			authed.Get("/home/index", h.handleGetHomeIndex)
 			authed.Post("/events", h.handleEvents)
 			authed.Get("/events/stream", h.handleEventsStream)
+			// UPnP / Sonos cast slice: issue a short-lived HMAC stream URL
+			// the speaker can fetch without the user's session. See the
+			// design at
+			// docs/superpowers/specs/2026-06-03-android-output-picker-upnp-design.md.
+			authed.Post("/cast/stream-token", h.handleCastStreamToken)
 			authed.Post("/likes/tracks/{id}", h.handleLikeTrack)
 			authed.Delete("/likes/tracks/{id}", h.handleUnlikeTrack)
 			authed.Post("/likes/albums/{id}", h.handleLikeAlbum)
@@ -0,0 +1,83 @@
+package api
+
+import (
+	"net/http"
+	"strconv"
+	"time"
+
+	"git.fabledsword.com/bvandeusen/minstrel/internal/apierror"
+)
+
+const (
+	castTokenMinExpSeconds = 60
+	castTokenMaxExpSeconds = 86400 // 24h
+	castTokenDefaultExp    = 21600 // 6h
+)
+
+type castTokenRequest struct {
+	TrackID    string `json:"trackId"`
+	ExpSeconds int    `json:"expSeconds,omitempty"`
+}
+
+type castTokenResponse struct {
+	Token string `json:"token"`
+	Exp   int64  `json:"exp"`
+	URL   string `json:"url"`
+}
+
+// handleCastStreamToken issues a short-lived HMAC stream token for the
+// given trackId. Authenticated via the standard session cookie / bearer.
+//
+// The returned URL is a fully-formed stream URL (token + exp embedded
+// as query params) that the client passes verbatim to a UPnP / Sonos
+// device's AVTransport.SetAVTransportURI call — those devices cannot
+// carry the user's session, so the signed query string is the only way
+// they can fetch the bytes.
+//
+// expSeconds is clamped to [60, 86400]; default 21600 (6h) — long enough
+// to play through any typical track without re-minting mid-playback.
+//
+// Part of the output-picker UPnP slice. See
+// docs/superpowers/specs/2026-06-03-android-output-picker-upnp-design.md.
+func (h *handlers) handleCastStreamToken(w http.ResponseWriter, r *http.Request) {
+	if _, ok := requireUser(w, r); !ok {
+		return
+	}
+	var req castTokenRequest
+	if !decodeBody(w, r, &req) {
+		return
+	}
+	trackUUID, ok := parseUUID(req.TrackID)
+	if !ok || !trackUUID.Valid {
+		writeErr(w, apierror.BadRequest("invalid_track_id", "trackId must be a UUID"))
+		return
+	}
+	expSec := clampExpSeconds(req.ExpSeconds)
+	exp := time.Now().Add(time.Duration(expSec) * time.Second).Unix()
+	token := SignStreamToken(h.streamSecret, req.TrackID, exp)
+
+	scheme := "http"
+	if r.TLS != nil {
+		scheme = "https"
+	}
+	url := scheme + "://" + r.Host + "/api/tracks/" + req.TrackID +
+		"/stream?token=" + token + "&exp=" + strconv.FormatInt(exp, 10)
+
+	writeJSON(w, http.StatusOK, castTokenResponse{Token: token, Exp: exp, URL: url})
+}
+
+// clampExpSeconds applies the [60, 86400] window with a 6h default for
+// non-positive inputs. Extracted so it doesn't bloat the handler's
+// detekt-equivalent line count and so the test can exercise edges directly.
+func clampExpSeconds(v int) int {
+	if v <= 0 {
+		return castTokenDefaultExp
+	}
+	if v < castTokenMinExpSeconds {
+		return castTokenMinExpSeconds
+	}
+	if v > castTokenMaxExpSeconds {
+		return castTokenMaxExpSeconds
+	}
+	return v
+}
@@ -0,0 +1,152 @@
+package api
+
+import (
+	"bytes"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+	"time"
+)
+
+const testTrackUUID = "11111111-1111-1111-1111-111111111111"
+
+func TestCastStreamToken_HappyPath(t *testing.T) {
+	h, pool := testHandlers(t)
+	user := seedUser(t, pool, "alice", "hunter2", false)
+	h.streamSecret = []byte("cast-token-test-secret")
+
+	body, err := json.Marshal(castTokenRequest{
+		TrackID:    testTrackUUID,
+		ExpSeconds: 3600,
+	})
+	if err != nil {
+		t.Fatalf("marshal: %v", err)
+	}
+	req := httptest.NewRequest(http.MethodPost, "/api/cast/stream-token", bytes.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	req = withUser(req, user)
+	w := httptest.NewRecorder()
+
+	h.handleCastStreamToken(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("status = %d, want 200; body=%s", w.Code, w.Body.String())
+	}
+	var resp castTokenResponse
+	if err := json.NewDecoder(w.Body).Decode(&resp); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	if resp.Token == "" || resp.Exp == 0 || resp.URL == "" {
+		t.Fatalf("empty fields in response: %+v", resp)
+	}
+	if !strings.Contains(resp.URL, "token="+resp.Token) {
+		t.Fatalf("URL missing token query: %s", resp.URL)
+	}
+	if !strings.Contains(resp.URL, "/api/tracks/"+testTrackUUID+"/stream") {
+		t.Fatalf("URL missing stream path: %s", resp.URL)
+	}
+	if !VerifyStreamToken(h.streamSecret, testTrackUUID, resp.Exp, resp.Token) {
+		t.Fatal("returned token does not verify")
+	}
+}
+
+func TestCastStreamToken_RejectsBadUUID(t *testing.T) {
+	h, pool := testHandlers(t)
+	user := seedUser(t, pool, "alice", "hunter2", false)
+	h.streamSecret = []byte("cast-token-test-secret")
+
+	body, err := json.Marshal(castTokenRequest{TrackID: "not-a-uuid"})
+	if err != nil {
+		t.Fatalf("marshal: %v", err)
+	}
+	req := httptest.NewRequest(http.MethodPost, "/api/cast/stream-token", bytes.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	req = withUser(req, user)
+	w := httptest.NewRecorder()
+
+	h.handleCastStreamToken(w, req)
+
+	if w.Code != http.StatusBadRequest {
+		t.Fatalf("status = %d, want 400; body=%s", w.Code, w.Body.String())
+	}
+}
+
+func TestCastStreamToken_RejectsUnauthenticated(t *testing.T) {
+	h, _ := testHandlers(t)
+	h.streamSecret = []byte("cast-token-test-secret")
+
+	body, err := json.Marshal(castTokenRequest{TrackID: testTrackUUID})
+	if err != nil {
+		t.Fatalf("marshal: %v", err)
+	}
+	req := httptest.NewRequest(http.MethodPost, "/api/cast/stream-token", bytes.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	// NO withUser — handler must reject via requireUser.
+	w := httptest.NewRecorder()
+
+	h.handleCastStreamToken(w, req)
+
+	if w.Code != http.StatusUnauthorized {
+		t.Fatalf("status = %d, want 401; body=%s", w.Code, w.Body.String())
+	}
+}
+
+func TestCastStreamToken_ClampsExpSeconds(t *testing.T) {
+	h, pool := testHandlers(t)
+	user := seedUser(t, pool, "alice", "hunter2", false)
+	h.streamSecret = []byte("cast-token-test-secret")
+
+	// Request 1 second (below min 60), expect clamp to 60s.
+	body, err := json.Marshal(castTokenRequest{
+		TrackID:    testTrackUUID,
+		ExpSeconds: 1,
+	})
+	if err != nil {
+		t.Fatalf("marshal: %v", err)
+	}
+	before := time.Now().Unix()
+	req := httptest.NewRequest(http.MethodPost, "/api/cast/stream-token", bytes.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	req = withUser(req, user)
+	w := httptest.NewRecorder()
+
+	h.handleCastStreamToken(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("status = %d, want 200; body=%s", w.Code, w.Body.String())
+	}
+	var resp castTokenResponse
+	if err := json.NewDecoder(w.Body).Decode(&resp); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	// Allow a small jitter window around the clamp target (60s).
+	delta := resp.Exp - before
+	if delta < 55 || delta > 70 {
+		t.Fatalf("expected ~60s expiry after clamp, got delta=%ds", delta)
+	}
+}
+
+func TestClampExpSeconds(t *testing.T) {
+	cases := []struct {
+		name string
+		in   int
+		want int
+	}{
+		{"zero defaults to 6h", 0, castTokenDefaultExp},
+		{"negative defaults to 6h", -1, castTokenDefaultExp},
+		{"below min clamps up", 30, castTokenMinExpSeconds},
+		{"exact min passes through", castTokenMinExpSeconds, castTokenMinExpSeconds},
+		{"mid-range passes through", 3600, 3600},
+		{"exact max passes through", castTokenMaxExpSeconds, castTokenMaxExpSeconds},
+		{"above max clamps down", castTokenMaxExpSeconds + 1, castTokenMaxExpSeconds},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			if got := clampExpSeconds(tc.in); got != tc.want {
+				t.Fatalf("clampExpSeconds(%d) = %d, want %d", tc.in, got, tc.want)
+			}
+		})
+	}
+}