fix(security): CORS allowlist, URL scheme guard, state perms, ZIP slip, mirror docs

Phase 3 security audit follow-up. Medium and low-severity hardenings
plus a deferred-work plan for the cross-repo stream-token rollout.

Stream server CORS: replace the wildcard Access-Control-Allow-Origin
with an allowlist that echoes back only torrentclaw.com,
app.torrentclaw.com, the local Next dev port (3030 — matches the web
repo package.json) and any extras the operator adds via the new
downloads.cors_extra_origins TOML key. A Vary: Origin header is now
emitted whenever the request carries an Origin header so an
intermediate cache cannot serve a stale ACAO to a different origin.

URL scheme guard: openBrowser and OpenPlayer refuse any URL that is
not http(s). Combined with passing the URL after "--" wherever the
launched helper supports it (open, mpv, vlc, cvlc), this stops a
leading "-" from being parsed as a switch by the spawned process.

State file permissions: WriteState now writes 0o600 so the agent ID,
PID and counters cannot be enumerated by another local user on a
shared host. Matches the existing config file mode.

ZIP slip defense-in-depth: extractZip extracts the safety check into
safeZipPath, which canonicalises the entry name (normalising
backslashes to "/"), rejects "..", "../" prefix and "/../" interior
components, and verifies the final destination stays inside destDir
before opening any file.

Mirror fallback: documented the design for multi-provider
mirrors.json hosting in the comment block on DefaultStaticFallbackURLs
and added a follow-up note about signing it with the same ed25519
release key. The list is kept at one provider until the second host
is provisioned and added to torrentclaw-web's STATIC_FALLBACKS.

Deferred work: a new plan document Docs/plans/security-stream-token.md
covers the per-task stream token (Phase 2.2 of the original audit)
which requires coordinated web + CLI work and ships separately.

internal/engine/stream_player.go

@@ -4,14 +4,23 @@ import (
 	"fmt"
 	"os/exec"
 	"runtime"
+	"strings"
 )
 
 // OpenPlayer attempts to open a media player with the given stream URL.
 // Returns the player name and the running command.
 // If override is set, it uses that command directly.
+//
+// The URL is required to be http(s) so a hostile-looking value (e.g. starting
+// with `--`) is not interpreted as a switch by mpv/vlc/xdg-open/open. The
+// `--` separator is also appended before the URL where the helper supports
+// it.
 func OpenPlayer(url, override string) (string, *exec.Cmd, error) {
+	if !isSafePlayerURL(url) {
+		return "", nil, fmt.Errorf("refusing to open non-http(s) URL")
+	}
 	if override != "" {
-		cmd := exec.Command(override, url)
+		cmd := exec.Command(override, "--", url)
 		if err := cmd.Start(); err != nil {
 			return override, nil, fmt.Errorf("start %s: %w", override, err)
 		}
@@ -20,7 +29,7 @@ func OpenPlayer(url, override string) (string, *exec.Cmd, error) {
 
 	// Try mpv first (best streaming support)
 	if path, err := exec.LookPath("mpv"); err == nil {
-		cmd := exec.Command(path, "--no-terminal", url)
+		cmd := exec.Command(path, "--no-terminal", "--", url)
 		if err := cmd.Start(); err == nil {
 			return "mpv", cmd, nil
 		}
@@ -28,7 +37,7 @@ func OpenPlayer(url, override string) (string, *exec.Cmd, error) {
 
 	// Try VLC
 	if path, err := exec.LookPath("vlc"); err == nil {
-		cmd := exec.Command(path, url)
+		cmd := exec.Command(path, "--", url)
 		if err := cmd.Start(); err == nil {
 			return "vlc", cmd, nil
 		}
@@ -36,7 +45,7 @@ func OpenPlayer(url, override string) (string, *exec.Cmd, error) {
 
 	// Try cvlc (VLC headless)
 	if path, err := exec.LookPath("cvlc"); err == nil {
-		cmd := exec.Command(path, url)
+		cmd := exec.Command(path, "--", url)
 		if err := cmd.Start(); err == nil {
 			return "vlc (headless)", cmd, nil
 		}
@@ -51,6 +60,9 @@ func OpenPlayer(url, override string) (string, *exec.Cmd, error) {
 }
 
 func openBrowser(url string) (string, *exec.Cmd, error) {
+	if !isSafePlayerURL(url) {
+		return "", nil, fmt.Errorf("refusing to open non-http(s) URL")
+	}
 	switch runtime.GOOS {
 	case "linux":
 		if path, err := exec.LookPath("xdg-open"); err == nil {
@@ -60,7 +72,7 @@ func openBrowser(url string) (string, *exec.Cmd, error) {
 			}
 		}
 	case "darwin":
-		cmd := exec.Command("/usr/bin/open", url)
+		cmd := exec.Command("/usr/bin/open", "--", url)
 		if err := cmd.Start(); err == nil {
 			return "browser", cmd, nil
 		}
@@ -72,3 +84,9 @@ func openBrowser(url string) (string, *exec.Cmd, error) {
 	}
 	return "", nil, fmt.Errorf("no browser opener found")
 }
+
+// isSafePlayerURL guards the helpers above against URLs that could be
+// interpreted as command-line switches by the launched player.
+func isSafePlayerURL(url string) bool {
+	return strings.HasPrefix(url, "http://") || strings.HasPrefix(url, "https://")
+}

internal/engine/stream_server.go

@@ -56,6 +56,12 @@ type StreamServer struct {
 	// would let any scanner enumerate active downloads. LAN and Tailscale
 	// access keep working without UPnP.
 	enableUPnP bool
+	// corsExtraOrigins are operator-configured origins added to the default
+	// allowlist defined in validate.go. Set before Listen().
+	corsExtraOrigins []string
+	// corsAllowlist is computed at Listen() time and treated as read-only
+	// thereafter so per-request reads need no locking.
+	corsAllowlist map[string]struct{}
 
 	hls *HLSSessionRegistry // HLS sessions served on /hls/<id>/...
 
@@ -86,12 +92,57 @@ func (ss *StreamServer) SetUPnPEnabled(enabled bool) {
 	ss.enableUPnP = enabled
 }
 
+// SetCORSAllowedOrigins replaces the operator-supplied extra origins. The
+// default allowlist (torrentclaw.com / app.torrentclaw.com / localhost dev
+// ports) is always merged in. Call before Listen().
+func (ss *StreamServer) SetCORSAllowedOrigins(origins []string) {
+	ss.corsExtraOrigins = origins
+}
+
+// writeCORSHeaders writes the per-origin CORS response headers when the
+// request carries an Origin header that matches the allowlist. Returns true
+// if the handler must short-circuit (preflight OPTIONS). Media-tag requests
+// (no Origin header) bypass this entirely.
+//
+// `Vary: Origin` is emitted whenever an Origin header is present (matched
+// or not) so any intermediate cache keys the response per-origin and a
+// later request with a different origin cannot be served a stale ACAO.
+func (ss *StreamServer) writeCORSHeaders(w http.ResponseWriter, r *http.Request, expose string) (preflight bool) {
+	origin := r.Header.Get("Origin")
+	if origin == "" {
+		return false
+	}
+	w.Header().Add("Vary", "Origin")
+	if _, ok := ss.corsAllowlist[origin]; !ok {
+		// Unknown origin — do not emit CORS headers so the browser blocks
+		// the response. Still return without short-circuiting so a non-CORS
+		// caller (e.g. curl) keeps working.
+		return false
+	}
+	w.Header().Set("Access-Control-Allow-Origin", origin)
+	w.Header().Set("Access-Control-Allow-Methods", "GET, HEAD, OPTIONS")
+	w.Header().Set("Access-Control-Allow-Headers", "Range")
+	if expose != "" {
+		w.Header().Set("Access-Control-Expose-Headers", expose)
+	}
+	if r.Method == http.MethodOptions {
+		w.WriteHeader(http.StatusNoContent)
+		return true
+	}
+	return false
+}
+
 // HLS returns the HLS session registry for this server. Daemon code uses it
 // to register a session when the backend asks for HLS playback.
 func (ss *StreamServer) HLS() *HLSSessionRegistry { return ss.hls }
 
 // Listen starts the HTTP server on the configured port. Call once at daemon startup.
 func (ss *StreamServer) Listen(ctx context.Context) error {
+	// Freeze the CORS allowlist before the first request can land. After
+	// this point the map is treated as read-only so handlers can probe it
+	// without locking.
+	ss.corsAllowlist = buildCORSAllowlist(ss.corsExtraOrigins)
+
 	mux := http.NewServeMux()
 	mux.HandleFunc("/stream", ss.handler)
 	mux.HandleFunc("/health", ss.healthHandler)
@@ -306,16 +357,8 @@ func (ss *StreamServer) HLSURLsJSON(sessionID string) string {
 func (ss *StreamServer) hlsHandler(w http.ResponseWriter, r *http.Request) {
 	ss.lastActivity.Store(time.Now().UnixNano())
 
-	// CORS for app.torrentclaw.com → 127.0.0.1/Tailscale daemon.
-	if origin := r.Header.Get("Origin"); origin != "" {
-		w.Header().Set("Access-Control-Allow-Origin", "*")
-		w.Header().Set("Access-Control-Allow-Methods", "GET, HEAD, OPTIONS")
-		w.Header().Set("Access-Control-Allow-Headers", "Range")
-		w.Header().Set("Access-Control-Expose-Headers", "Content-Length, Content-Range, Accept-Ranges")
-		if r.Method == http.MethodOptions {
-			w.WriteHeader(http.StatusNoContent)
-			return
-		}
+	if ss.writeCORSHeaders(w, r, "Content-Length, Content-Range, Accept-Ranges") {
+		return
 	}
 
 	rest := strings.TrimPrefix(r.URL.Path, "/hls/")
@@ -414,6 +457,9 @@ func (ss *StreamServer) serveSubtitlePlaylist(w http.ResponseWriter, r *http.Req
 //
 //	curl http://<tailscale-ip>:<port>/health
 func (ss *StreamServer) healthHandler(w http.ResponseWriter, r *http.Request) {
+	if ss.writeCORSHeaders(w, r, "") {
+		return
+	}
 	ss.mu.RLock()
 	provider := ss.provider
 	taskID := ss.taskID
@@ -470,15 +516,8 @@ func (ss *StreamServer) healthHandler(w http.ResponseWriter, r *http.Request) {
 // VLC fetches this playlist and applies the EXTVLCOPT directives automatically,
 // enabling automatic audio/subtitle track selection on all VLC platforms (desktop + mobile).
 func (ss *StreamServer) playlistHandler(w http.ResponseWriter, r *http.Request) {
-	// CORS — handle preflight before doing any work (consistent with handler)
-	if origin := r.Header.Get("Origin"); origin != "" {
-		w.Header().Set("Access-Control-Allow-Origin", "*")
-		w.Header().Set("Access-Control-Allow-Methods", "GET, HEAD, OPTIONS")
-		w.Header().Set("Access-Control-Allow-Headers", "Range")
-		if r.Method == http.MethodOptions {
-			w.WriteHeader(http.StatusNoContent)
-			return
-		}
+	if ss.writeCORSHeaders(w, r, "") {
+		return
 	}
 
 	q := r.URL.Query()
@@ -548,17 +587,8 @@ func (ss *StreamServer) handler(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	// CORS headers — only when browser sends Origin (HTTPS site → localhost)
-	if origin := r.Header.Get("Origin"); origin != "" {
-		w.Header().Set("Access-Control-Allow-Origin", "*")
-		w.Header().Set("Access-Control-Allow-Methods", "GET, HEAD, OPTIONS")
-		w.Header().Set("Access-Control-Allow-Headers", "Range")
-		w.Header().Set("Access-Control-Expose-Headers", "Content-Length, Content-Range, Accept-Ranges")
-
-		if r.Method == http.MethodOptions {
-			w.WriteHeader(http.StatusNoContent)
-			return
-		}
+	if ss.writeCORSHeaders(w, r, "Content-Length, Content-Range, Accept-Ranges") {
+		return
 	}
 
 	rawReader := provider.NewFileReader(r.Context())

internal/engine/stream_server_test.go

@@ -429,6 +429,71 @@ func TestStreamServer_Health_NonLoopback_NoLeak(t *testing.T) {
 	}
 }
 
+// TestStreamServer_CORS_Allowlist verifica que sólo los origenes en la
+// allowlist reciben Access-Control-Allow-Origin y que ningún otro origen
+// es eco-reflejado.
+func TestStreamServer_CORS_Allowlist(t *testing.T) {
+	srv := NewStreamServer(0)
+	ctx := context.Background()
+	if err := srv.Listen(ctx); err != nil {
+		t.Fatalf("Listen: %v", err)
+	}
+	defer srv.Shutdown(ctx)
+
+	cases := []struct {
+		origin    string
+		wantAllow bool
+	}{
+		{"https://app.torrentclaw.com", true},
+		{"https://torrentclaw.com", true},
+		{"http://localhost:3030", true},
+		{"http://127.0.0.1:3030", true},
+		{"https://evil.example", false},
+		{"null", false},
+		{"", false},
+	}
+	for _, tc := range cases {
+		t.Run(tc.origin, func(t *testing.T) {
+			rr := httptest.NewRecorder()
+			req := httptest.NewRequest(http.MethodOptions, "/health", nil)
+			if tc.origin != "" {
+				req.Header.Set("Origin", tc.origin)
+			}
+			srv.healthHandler(rr, req)
+			got := rr.Header().Get("Access-Control-Allow-Origin")
+			if tc.wantAllow {
+				if got != tc.origin {
+					t.Errorf("origin %q: ACAO = %q, want %q", tc.origin, got, tc.origin)
+				}
+			} else if got != "" {
+				t.Errorf("origin %q: ACAO leaked as %q, expected empty", tc.origin, got)
+			}
+		})
+	}
+}
+
+// TestStreamServer_CORS_ExtraOrigin verifica que SetCORSAllowedOrigins añade
+// origins al baseline sin removerlos.
+func TestStreamServer_CORS_ExtraOrigin(t *testing.T) {
+	srv := NewStreamServer(0)
+	srv.SetCORSAllowedOrigins([]string{"https://custom.example"})
+	ctx := context.Background()
+	if err := srv.Listen(ctx); err != nil {
+		t.Fatalf("Listen: %v", err)
+	}
+	defer srv.Shutdown(ctx)
+
+	for _, origin := range []string{"https://custom.example", "https://torrentclaw.com"} {
+		rr := httptest.NewRecorder()
+		req := httptest.NewRequest(http.MethodGet, "/health", nil)
+		req.Header.Set("Origin", origin)
+		srv.healthHandler(rr, req)
+		if got := rr.Header().Get("Access-Control-Allow-Origin"); got != origin {
+			t.Errorf("origin %q: ACAO = %q", origin, got)
+		}
+	}
+}
+
 // TestStreamServer_HLS_InvalidSessionID verifica que el hlsHandler rechaza
 // session IDs con caracteres ilegales devolviendo 404 (uniforme con sesión
 // inexistente) para no filtrar el formato aceptado a un attacker.

internal/engine/validate.go

@@ -10,3 +10,39 @@ import "regexp"
 // anything containing slashes, dots, or path separators is rejected so a
 // compromised or buggy server cannot escape hlsTmpDirRoot via os.MkdirAll.
 var validSessionID = regexp.MustCompile(`^[a-zA-Z0-9_-]{1,128}$`)
+
+// defaultCORSAllowedOrigins is the baseline of browser origins that may
+// XHR-probe `/health` and friends on the local daemon. Production hosts are
+// hardcoded; localhost on the dev port used by torrentclaw-web is included
+// so dev builds work without extra configuration. Operators may add more
+// origins via the [downloads] cors_extra_origins TOML key.
+//
+// The dev port matches `next dev -p 3030` in torrentclaw-web/package.json.
+// 127.0.0.1 is listed in addition to localhost because some browsers treat
+// them as distinct origins for CORS.
+//
+// Note: media tags (<video src>, <audio src>) do not send the Origin
+// header so they are not gated by CORS at all; this allowlist only
+// affects fetch()/XHR.
+var defaultCORSAllowedOrigins = []string{
+	"https://torrentclaw.com",
+	"https://app.torrentclaw.com",
+	"http://localhost:3030",
+	"http://127.0.0.1:3030",
+}
+
+// buildCORSAllowlist merges the default origins with any extras supplied by
+// the operator. Returned map is intended to be installed once at Listen()
+// and treated as read-only afterwards.
+func buildCORSAllowlist(extra []string) map[string]struct{} {
+	out := make(map[string]struct{}, len(defaultCORSAllowedOrigins)+len(extra))
+	for _, o := range defaultCORSAllowedOrigins {
+		out[o] = struct{}{}
+	}
+	for _, o := range extra {
+		if o != "" {
+			out[o] = struct{}{}
+		}
+	}
+	return out
+}