ersatztv/docs/decisions/records/security/iptv-browser-token.md

key, title, status, since, supersedes, superseded-by, rule, signals, mechanics

key	title	status	since	supersedes	superseded-by	rule	signals	mechanics
security.iptv-browser-token	2026-07-22 — Short-lived browser IPTV token so the SPA reaches `/iptv/*` under JWT auth (#552)	active	2026-07-22	none	none	Under a JWT-enabled deployment (`JWT:IssuerSigningKey` set), the browser SPA obtains a short-lived, globally-scoped `/iptv/*` access token from an authenticated `GET /api/v1/auth/iptv-token` and appends it as `?access_token=`; the endpoint answers 204 when JWT is disabled (nothing to mint). Lifetime defaults to 60 min, configurable via `JWT:BrowserTokenLifetimeMinutes`.	channel preview / playback-troubleshooting 401ing under JWT; `/iptv/*` not accepting `ctv-session`; minting a JWT for the browser · paths: `ErsatzTV/JwtHelper.cs`, `ErsatzTV/Controllers/Api/AuthController.cs`, `web/src/media/iptvToken.ts` · issues: #552, #60	`JwtHelper.GenerateBrowserToken()`; `AuthController.IptvToken`; `withIptvToken(url)` (SPA)

/iptv/* is gated by ConditionalIptvAuthorizeFilter only when JWT:IssuerSigningKey is configured, and the "jwt" scheme accepts only a bearer token or ?access_token= — not the SPA's ctv-session cookie (a distinct scheme). Nothing minted a JWT for the browser, so under JWT the #60 channel preview was declared Unavailable and the pre-existing playback-troubleshooting screen was latently broken. This closes both with one seam.

• Endpoint. GET /api/v1/auth/iptv-token on AuthController (already [SkipApiAuthorization] + self-checks the principal, like machine-key). Requires any authenticated session (401 otherwise); returns { token, expiresAt } when JwtHelper.IsEnabled, else 204 No Content — /iptv/* is open then, so there is nothing to append and the SPA plays the plain URL. Cache-Control: no-store. Excluded from the OpenAPI document (AuthController is [IgnoreApi], per the #295 F4 ruling — a browser-interactive credential is not something a generated client drives).
• A GET is correct here despite the "no side-effecting GET under /api" rule (api-conventions.md §9): minting a JWT writes no server state (stateless token, no DB row, no revocation list), so it is not a CSRF-relevant side effect, and same-origin policy already blocks a cross-site page from reading the credentialed response body — identical reasoning to the machine-key GET.
• Scope: global. The "jwt" scheme validates only signature + lifetime (no audience/channel claims), and the token is minted only to the already-authenticated admin who can reach every channel. Channel-scoping would mean adding claim-based auth to ConditionalIptvAuthorizeFilter and the streaming path — deferred until a non-admin preview audience exists.
• Lifetime: 60 min default, JWT:BrowserTokenLifetimeMinutes override, clamped to 24h. The token re-validates on every /iptv/* request, so lifetime is the max continuous watch before playback stalls; 60 min comfortably covers an operator verification session, an expired idle session just needs Retry (mints fresh), and a security-conscious operator can tighten it. A non-positive/unparseable value falls back to the default rather than minting an already-expired token; a value above 24h (a seconds-vs-minutes typo would otherwise mint a multi-year bearer token) is clamped down. Revocation is by short lifetime only — a stateless JWT has no per-token revocation; rotating JWT:IssuerSigningKey invalidates all tokens (the existing lever). The SPA's resetIptvTokenCache() (called on the preview panel's Retry and on each troubleshooting Play) makes a user-initiated retry re-mint, so a stale token or a stale "JWT disabled" latch from a since-reconfigured backend can't wedge a recovery attempt.
• Deferred hardening (broader than #552) — RESOLVED by security.iptv-access-token-transport (#421, #559). The ?access_token= transport itself had pre-existing weaknesses this feature inherited, then bounded by the short lifetime: Serilog's request log included the full query (so a token could reach logs on an /iptv 5xx), and the token-bearing dynamic manifests carried no Cache-Control: no-store. Both predate this feature (Jellyfin and the M3U playlist already pass access_token in /iptv URLs); their fixes were cross-cutting changes to shared request-logging / manifest behavior, tracked as a follow-up and now landed in the record below (which also adds the #421 M3U quote-safety encoding).
• Only the top-level manifest needs the token. The multi-variant playlist embeds access_token into its variant URL (IptvController.GetMultiVariantPlaylist), and HLS segments are served by UseStaticFiles at RequestPath=/iptv/session — outside ConditionalIptvAuthorizeFilter (which is a [ServiceFilter] on IptvController only) — so segment GETs are ungated regardless. The SPA's withIptvToken(url) appends the token to the one manifest URL (a no-op when JWT is off; caches the token in memory until shortly before expiry) and is used by both the channel-preview panel and the playback-troubleshooting screen.