ersatztv/docs/decisions/records/security/iptv-access-token-transport.md

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

key	title	status	since	supersedes	superseded-by	rule	signals	mechanics
security.iptv-access-token-transport	2026-07-23 — access_token transport hardening: percent-encode in M3U/HLS, redact from logs, no-store on tokened manifests (#421, #559)	active	2026-07-23	none	none	The `/iptv` `?access_token=` value is percent-encoded (`Uri.EscapeDataString`) everywhere it is interpolated into an M3U/HLS/XMLTV URL (XMLTV additionally XML-escapes the encoded value), so a structural character can't malform the manifest or guide; Serilog logs a scrubbed request path (`access_token` → `***` via `IncludeQueryInRequestPath = false` + a `RequestPathScrubbed` enricher), so a 5xx/Debug `/iptv` request never writes the token; and every dynamic token-bearing `/iptv` manifest (`channels.m3u`, `xmltv.xml`, the HLS multi-variant/media playlists) returns `Cache-Control: private, no-store`.	access_token quote-safety, url-tvg breakout, M3U attribute escaping, XMLTV icon src encoding, request-log token redaction, no-store manifest, token replay from logs/cache · paths: `ErsatzTV.Core/Iptv/ChannelPlaylist.cs`, `ErsatzTV/Controllers/IptvController.cs`, `ErsatzTV.Application/Channels/Queries/GetChannelGuideHandler.cs`, `ErsatzTV/Middleware/RequestLogScrubber.cs`, `ErsatzTV/Startup.cs`, `ErsatzTV.Core/FFmpeg/FFmpegLibraryProcessService.cs` · issues: #421, #559, #552, #376	`ChannelPlaylistAccessTokenTests`; `RequestLogScrubberTests`; `IptvControllerCacheHeaderTests`

Resolves the "deferred hardening" bullet under security.iptv-browser-token (#552). The shared ?access_token= transport had three pre-existing weaknesses that #552's short-lived browser token only bounded (not fixed); they predate #552 because Jellyfin and the M3U playlist already pass access_token in /iptv URLs.

• Percent-encode the token in M3U/HLS URLs (#421). ChannelPlaylist.ToM3U interpolates the token into quoted M3U attributes (url-tvg="...", tvg-logo="...") and bare stream URLs; IptvController.AccessTokenQuery and the internal segmenter URL (FFmpegLibraryProcessService.WrapSegmenter) do the same. A token containing a " could terminate a quoted attribute early, and an & could split the query — for strict parsers. The value is a URL query parameter, so the correct fix is percent-encoding (Uri.EscapeDataString) at each interpolation site; ASP.NET decodes Request.Query, so the round-trip is lossless and validation is unchanged. For a normal base64url JWT this is a no-op (every character is RFC 3986 unreserved), so the M3U goldens are byte-identical. This is the M3U analogue of #376's XMLTV SecurityElement.Escape fix — #376 correctly did not apply to M3U (M3U is not XML), which is why #421 was split out. The XMLTV twin (GetChannelGuideHandler) is fixed the same way for symmetry: the token there lands in a URL query value inside an XML attribute, so it now percent-encodes then XML-escapes (SecurityElement.Escape(Uri.EscapeDataString(token))) — #376's XML-escape alone guarded XML well-formedness but not URL correctness, so a token with & would still truncate the query after the consumer XML-unescapes the attribute.
• Redact the token from request logs (#559). UseSerilogRequestLogging had IncludeQueryInRequestPath = true, and the ex != null / StatusCode > 499 branches log at Error regardless of path — so a 5xx on a tokened /iptv URL wrote the replayable, globally-scoped token to the log under default settings. Fix: IncludeQueryInRequestPath = false (built-in RequestPath is now path-only) plus a RequestPathScrubbed diagnostic-context property — built by RequestLogScrubber.ScrubbedPath, which rebuilds the query with the access_token value masked to *** and everything else (e.g. mode=segmenter) preserved for debugging — that the message template references in place of {RequestPath}. A distinct property name is required because Serilog appends its own RequestPath after enriched properties, so reusing the name would let the built-in value win. Load-bearing residual: this scrubs only UseSerilogRequestLogging. ASP.NET's own Microsoft.AspNetCore.Hosting.Diagnostics "Request starting" line logs the raw query (token and all) at Information; it is suppressed today solely by the "Microsoft": "Warning" override in appsettings.json, which is not reachable from the runtime logging-settings UI (the HttpLevelSwitch overrides only Serilog.AspNetCore.RequestLoggingMiddleware). Keep that override — lowering Microsoft to Information/Debug for routing/auth debugging re-leaks the token. A category-agnostic scrub filter is the follow-up if that override is ever relaxed.
• no-store on token-bearing dynamic manifests (#559). channels.m3u, xmltv.xml, and the HLS multi-variant/media playlists embed the caller's token in their body/URLs but set no cache headers, so a browser or intermediary could cache the token-bearing manifest. Each now returns Cache-Control: private, no-store. This covers the Jellyfin-facing M3U/XMLTV as well as the #552 HLS preview manifests — all three share the same cache-replay risk — and does not affect Jellyfin, which refetches the playlist/guide on its own schedule regardless of HTTP cache headers. The .ts live streams and the ungated HLS segments (served by UseStaticFiles at /iptv/session, outside ConditionalIptvAuthorizeFilter) carry no token and are unchanged.