unarr/Docs/plans/security-stream-token.md

Phase 2.2 — Per-task stream token (deferred)

Status: deferred. Requires coordinated change in the web app (torrentclaw-web) and the CLI daemon. Pulled out of the Phase 2 security pass because the CLI-only fixes (UPnP opt-in, SSE caps, signed self-update) ship without web-side work; the stream-token work cannot.

Problem

/stream, /playlist.m3u and /hls/<sessionID>/... on the daemon HTTP server have no authentication. Today, anyone who can reach the listener and guesses (or learns) the taskID (for /stream) or sessionID (for /hls) can fetch the active file.

Mitigations already in place after Phase 1+2:

• sessionID is restricted to a safe regex and is a server-issued UUID v4 (122-bit entropy, not enumerable in practice).
• /health no longer leaks the active filename, taskID prefix or client IP to remote callers (loopback diagnostics preserved).
• UPnP is opt-in, so by default the daemon is not exposed to the public internet.
• The web client probes /health to pick LAN vs Tailscale.

Residual risk:

• On a shared LAN (open Wi-Fi, office network, dorm) any device can reach the listener and brute-force ?id=<taskID> against /stream. taskIDs are also UUIDs, so this is high entropy, but the URL may leak through browser history, sharing, screen capture or a passive logger and there is no second factor.
• A user who explicitly opts into UPnP exposes the same surface to the entire internet.

A per-task secret carried in the URL closes this without breaking the <video src> flow (the browser cannot attach Authorization headers to media elements, but it can append a query parameter).

Design

Both ends agree on a per-task secret token. The web generates it when the user requests streaming; the daemon receives the (taskID, token) pair and validates the token on every /stream and /hls/... request.

Web side (torrentclaw-web)

When the user clicks "Stream":

1. Generate streamToken = crypto.randomBytes(32).toString("hex") server-side (NOT browser, so it never lives in client storage longer than the page lifetime).
2. Persist (taskID, streamToken, expiresAt) in download_task (new columns or a sibling table). Token expires e.g. 6 h after issue or on explicit revoke.
3. Push the token to the daemon over the existing heartbeat / sync channel that already carries streamRequested. Add a streamToken field next to it. The daemon trusts that channel (it is authenticated agent ↔ origin).
4. Include the token in the stream URLs the API returns to the browser: http://<host>:<port>/stream?id=<taskID>&t=<streamToken> and the /hls/<sessionID> URLs gain ?t=<streamToken> too.

Files that will need to change:

• src/lib/services/agent.ts — extend the stream-request payload with streamToken.
• src/lib/db/schema.ts — column / table for the token.
• src/lib/services/stream-resolve.ts — append &t= to the URLs it builds.
• src/lib/stream-probe.ts — keep probing /health (no token), then append &t= to the winning stream URL before returning.
• src/middleware.ts — no CORS change required (browser still hits daemon directly).

CLI side

• internal/agent/types.go / internal/agent/sync.go — accept and store streamToken next to streamRequested.
• internal/agent/daemon.go — when the heartbeat reports a new active stream task, push the token into the stream server via a setter: streamSrv.SetTaskToken(taskID, token).
• internal/engine/stream_server.go:
  • New field tokens map[string]string guarded by mutex.
  • SetTaskToken(taskID, token) and ClearTaskToken(taskID).
  • handler (/stream) extracts ?id= and ?t=, checks the token with subtle.ConstantTimeCompare; 404 on mismatch.
  • hlsHandler (/hls/<sessionID>/...) needs an HLS-session → token mapping, since the path carries sessionID not taskID. Store the token on the HLSSession at start and validate per request.

Backwards compatibility

• The daemon must accept token-less requests for one minor version so a newer daemon can still serve an older web (and vice-versa). Gate the check on a config flag (require_stream_token, default false in the first release, default true in the next).
• The <video src> form supports query parameters, so the only user-visible change is the URL string.

Open questions to resolve before implementing

1. Token TTL. 6 h gives plenty of room for a movie + pause + resume; longer means the post-leak window is wider.
2. Where to store the token in download_task — same row, or a sibling download_stream_token table that we can rotate without writing to the task row.
3. Should /playlist.m3u (VLC) embed the token directly, or use a one-shot redeem URL? VLC URL ends up in history.
4. Token reuse across HLS reconnects — yes, scoped to the HLSSession, invalidated on Close().
5. Do we want a daemon flag --require-stream-token independent of config, for users to flip on quickly without editing TOML?

Effort estimate

• CLI: ~3 h
• Web: ~3 h
• Migration + rollout (config flag flip): 1 release cycle of soak.

Why not now

• Cross-repo coordination raises commit blast radius beyond what the Phase 2 security pass should carry.
• Web work needs DB migration + UI surfaces (the "stream link expired" path).
• Phase 2 hardenings ship value today without it; this is the defense-in-depth layer on top.