From a372742eb0b0c11718a98a805a85a1a35838c071 Mon Sep 17 00:00:00 2001 From: Timothy Date: Thu, 23 Jul 2026 08:30:18 +0200 Subject: [PATCH 1/2] harden(421,559): percent-encode access_token in IPTV URLs, redact from logs, no-store on tokened manifests MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit #421 — a token containing a double-quote/ampersand could break out of the quoted M3U `url-tvg="..."`/`tvg-logo="..."` attributes or split the query. Percent-encode (`Uri.EscapeDataString`) at every site the token is interpolated into an M3U/HLS/XMLTV URL: `ChannelPlaylist.ToM3U`, `IptvController.AccessTokenQuery`, `FFmpegLibraryProcessService.WrapSegmenter`, and the XMLTV twin `GetChannelGuideHandler` (percent-encode then XML-escape). No-op for a normal base64url JWT, so the M3U/XMLTV goldens are byte-identical. #559 — (1) Serilog logged the full `?access_token=` query on any 5xx/Error `/iptv` request. `IncludeQueryInRequestPath = false` + a new `RequestLogScrubber` enriching `RequestPathScrubbed` (masks the token to `***`, keeps other params) that the message template now references. (2) Token-bearing dynamic manifests (`channels.m3u`, `xmltv.xml`, the `.m3u8` HLS manifests, and their token-bearing 302 Locations) now return `Cache-Control: private, no-store`. Independent cold review (2 rounds) clean. Live-E2E verified: no-store header on m3u/xmltv/m3u8, token percent-encoded in url-tvg, and the request log rendering `access_token=***` with the raw token absent. Decision record `security.iptv-access-token-transport` added; resolves the deferred-hardening note under `security.iptv-browser-token`. Co-Authored-By: Claude Opus 4.8 (1M context) --- .../Queries/GetChannelGuideHandler.cs | 9 +- .../Iptv/ChannelGuideGoldenTests.cs | 20 +++-- .../Iptv/ChannelPlaylistAccessTokenTests.cs | 90 +++++++++++++++++++ .../FFmpeg/FFmpegLibraryProcessService.cs | 4 +- ErsatzTV.Core/Iptv/ChannelPlaylist.cs | 9 +- .../IptvControllerCacheHeaderTests.cs | 42 +++++++++ .../Middleware/RequestLogScrubberTests.cs | 50 +++++++++++ ErsatzTV/Controllers/IptvController.cs | 30 +++++-- ErsatzTV/Middleware/RequestLogScrubber.cs | 35 ++++++++ ErsatzTV/Startup.cs | 7 +- docs/decisions/README.md | 1 + docs/decisions/api-auth-security.md | 60 +++++++++++-- 12 files changed, 330 insertions(+), 27 deletions(-) create mode 100644 ErsatzTV.Core.Tests/Iptv/ChannelPlaylistAccessTokenTests.cs create mode 100644 ErsatzTV.Tests/Controllers/IptvControllerCacheHeaderTests.cs create mode 100644 ErsatzTV.Tests/Middleware/RequestLogScrubberTests.cs create mode 100644 ErsatzTV/Middleware/RequestLogScrubber.cs diff --git a/ErsatzTV.Application/Channels/Queries/GetChannelGuideHandler.cs b/ErsatzTV.Application/Channels/Queries/GetChannelGuideHandler.cs index 62be03c36..d42efbdc2 100644 --- a/ErsatzTV.Application/Channels/Queries/GetChannelGuideHandler.cs +++ b/ErsatzTV.Application/Channels/Queries/GetChannelGuideHandler.cs @@ -60,10 +60,11 @@ public partial class GetChannelGuideHandler( var accessTokenUri = $"?v={mtime}"; if (!string.IsNullOrWhiteSpace(request.AccessToken)) { - // The token value is HTTP-request-derived and interpolated raw into the pre-built XMLTV - // cache fragments, so it must be XML-escaped like {RequestBase} above — a token containing - // '&', '<', '>', or '"' would otherwise malform the whole guide. Opaque tokens are a no-op. - accessTokenUri += $"&access_token={SecurityElement.Escape(request.AccessToken)}"; + // The token lands in a URL query value inside an XMLTV attribute, so it needs BOTH layers: + // percent-encode first (#421 — a token with '&' would otherwise split the query and truncate + // the token once the consumer URL-decodes the attribute; mirrors the M3U fix), then XML-escape + // the result so it can't malform the guide (#376). Both are no-ops for an opaque base64url token. + accessTokenUri += $"&access_token={SecurityElement.Escape(Uri.EscapeDataString(request.AccessToken))}"; } string channelsFragment = await ReadAllTextShared(channelsFile, cancellationToken); diff --git a/ErsatzTV.Core.Tests/Iptv/ChannelGuideGoldenTests.cs b/ErsatzTV.Core.Tests/Iptv/ChannelGuideGoldenTests.cs index 966c763b1..3d9042552 100644 --- a/ErsatzTV.Core.Tests/Iptv/ChannelGuideGoldenTests.cs +++ b/ErsatzTV.Core.Tests/Iptv/ChannelGuideGoldenTests.cs @@ -187,11 +187,14 @@ public class ChannelGuideGoldenTests xml.ShouldNotContain("a&b"); } - // The access-token value is HTTP-request-derived (?access_token=) and interpolated raw into the - // {AccessTokenUri} placeholder, so a token containing XML-special chars must be escaped too — - // otherwise it malforms the whole guide, exactly like the {RequestBase} case above. (Finding #376.) + // The access-token value is HTTP-request-derived (?access_token=) and interpolated into the + // {AccessTokenUri} placeholder, which sits in a URL query value inside an XML attribute. It is + // percent-encoded FIRST (#421 — URL-correct: a token '&' becomes %26 so it can't split the query and + // truncate the token once a consumer URL-decodes the attribute) and XML-escaped SECOND (#376 — so the + // guide stays well-formed). For this token every char percent-encodes to an XML-safe %XX, so the emitted + // value is the percent-encoded form with no '&'/'<' introduced by the token. [Test] - public async Task Guide_xml_escapes_access_token() + public async Task Guide_encodes_and_xml_escapes_access_token() { MockFileSystem fileSystem = BuildCacheFileSystem(); var localFileSystem = Substitute.For(); @@ -223,9 +226,12 @@ public class ChannelGuideGoldenTests Right: guide => guide.ToXml(), Left: error => throw new AssertionException($"Handler returned error: {error.Value}")); - // Every XML-special char in the token must be escaped; the raw token must never reach the output. - xml.ShouldContain("access_token=tok&<>""); - xml.ShouldNotContain("access_token=tok&<"); + // Percent-encoded, therefore already XML-safe: '&'->%26, '<'->%3C, '>'->%3E, '"'->%22. + xml.ShouldContain("access_token=tok%26%3C%3E%22"); + // The token must not introduce a bare '&' NOR an '&' — either would truncate the query on decode. + xml.ShouldNotContain("access_token=tok&"); + // And the raw special chars must never reach the output. + xml.ShouldNotContain("tok&<>\""); } // --- harness --- diff --git a/ErsatzTV.Core.Tests/Iptv/ChannelPlaylistAccessTokenTests.cs b/ErsatzTV.Core.Tests/Iptv/ChannelPlaylistAccessTokenTests.cs new file mode 100644 index 000000000..a47589fa4 --- /dev/null +++ b/ErsatzTV.Core.Tests/Iptv/ChannelPlaylistAccessTokenTests.cs @@ -0,0 +1,90 @@ +using ErsatzTV.Core.Domain; +using ErsatzTV.Core.Iptv; +using NUnit.Framework; +using Shouldly; + +namespace ErsatzTV.Core.Tests.Iptv; + +// #421: a token containing M3U-structural characters (a double-quote or ampersand) must not be able to +// break out of the quoted url-tvg="..."/tvg-logo="..." attributes or the query string it is placed into. +[TestFixture] +public class ChannelPlaylistAccessTokenTests +{ + [Test] + public void Access_token_with_structural_chars_is_percent_encoded() + { + const string nastyToken = "aa\"bb&cc dd"; + + var playlist = new ChannelPlaylist( + "https", + "tv.example.com", + baseUrl: string.Empty, + [ + new Channel(new Guid("00000000-0000-0000-0000-000000000001")) + { + Number = "1", + Name = "News", + Group = "ErsatzTV", + StreamingMode = StreamingMode.HttpLiveStreamingDirect, + Artwork = [], + FFmpegProfile = new FFmpegProfile + { + VideoFormat = FFmpegProfileVideoFormat.H264, + AudioFormat = FFmpegProfileAudioFormat.Aac + } + } + ], + userAgent: "VLC/3.0", + accessToken: nastyToken); + + string m3u = playlist.ToM3U(); + + // The raw token characters must never appear in the token value... + m3u.ShouldNotContain("access_token=aa\""); + m3u.ShouldNotContain("access_token=aa\"bb&cc"); + + // ...they are percent-encoded instead (" -> %22, & -> %26, space -> %20). + m3u.ShouldContain("access_token=aa%22bb%26cc%20dd"); + + // No line's url-tvg attribute value contains a bare double-quote that could terminate it early. + foreach (string line in m3u.Split('\n')) + { + if (line.StartsWith("#EXTM3U", StringComparison.Ordinal)) + { + // url-tvg="" x-tvg-url="" — exactly the attribute-delimiting quotes, no stray ones. + line.Count(c => c == '"').ShouldBe(4); + } + } + } + + [Test] + public void Normal_jwt_token_is_unchanged() + { + // A base64url JWT is entirely RFC 3986 unreserved, so encoding is a no-op (goldens stay stable). + const string jwt = "eyJhbGciOiJIUzI1NiJ9.eyJleHAiOjEyM30.abc-DEF_123"; + + var playlist = new ChannelPlaylist( + "https", + "tv.example.com", + baseUrl: string.Empty, + [ + new Channel(new Guid("00000000-0000-0000-0000-000000000001")) + { + Number = "1", + Name = "News", + Group = "ErsatzTV", + StreamingMode = StreamingMode.HttpLiveStreamingDirect, + Artwork = [], + FFmpegProfile = new FFmpegProfile + { + VideoFormat = FFmpegProfileVideoFormat.H264, + AudioFormat = FFmpegProfileAudioFormat.Aac + } + } + ], + userAgent: "VLC/3.0", + accessToken: jwt); + + playlist.ToM3U().ShouldContain($"access_token={jwt}"); + } +} diff --git a/ErsatzTV.Core/FFmpeg/FFmpegLibraryProcessService.cs b/ErsatzTV.Core/FFmpeg/FFmpegLibraryProcessService.cs index 5f328e943..cf5227d4d 100644 --- a/ErsatzTV.Core/FFmpeg/FFmpegLibraryProcessService.cs +++ b/ErsatzTV.Core/FFmpeg/FFmpegLibraryProcessService.cs @@ -1043,9 +1043,11 @@ public class FFmpegLibraryProcessService : IFFmpegProcessService { var resolution = new FrameSize(channel.FFmpegProfile.Resolution.Width, channel.FFmpegProfile.Resolution.Height); + // Percent-encode so a token containing '&'/'"' can't malform this internal segmenter URL (#421); + // a no-op for a normal base64url JWT. string accessTokenQuery = string.IsNullOrWhiteSpace(accessToken) ? string.Empty - : $"&access_token={accessToken}"; + : $"&access_token={Uri.EscapeDataString(accessToken)}"; var concatInputFile = new ConcatInputFile( $"http://localhost:{Settings.StreamingPort}/iptv/channel/{channel.Number}.m3u8?mode=segmenter{accessTokenQuery}", diff --git a/ErsatzTV.Core/Iptv/ChannelPlaylist.cs b/ErsatzTV.Core/Iptv/ChannelPlaylist.cs index 574d535b4..749a84d32 100644 --- a/ErsatzTV.Core/Iptv/ChannelPlaylist.cs +++ b/ErsatzTV.Core/Iptv/ChannelPlaylist.cs @@ -37,8 +37,13 @@ public class ChannelPlaylist string accessTokenUriAmp = string.Empty; if (_accessToken != null) { - accessTokenUri = $"?access_token={_accessToken}"; - accessTokenUriAmp = $"&access_token={_accessToken}"; + // Percent-encode the token: it is interpolated into URL query strings that land inside quoted + // M3U attributes (url-tvg="...", tvg-logo="..."). A token containing a double-quote or ampersand + // would otherwise terminate the attribute or the query early for strict parsers (#421). For a + // normal base64url JWT this is a no-op (all characters are RFC 3986 unreserved). + string encodedToken = Uri.EscapeDataString(_accessToken); + accessTokenUri = $"?access_token={encodedToken}"; + accessTokenUriAmp = $"&access_token={encodedToken}"; } var xmltv = $"{_scheme}://{_host}{_baseUrl}/iptv/xmltv.xml{accessTokenUri}"; diff --git a/ErsatzTV.Tests/Controllers/IptvControllerCacheHeaderTests.cs b/ErsatzTV.Tests/Controllers/IptvControllerCacheHeaderTests.cs new file mode 100644 index 000000000..f73ccc057 --- /dev/null +++ b/ErsatzTV.Tests/Controllers/IptvControllerCacheHeaderTests.cs @@ -0,0 +1,42 @@ +using ErsatzTV.Application.Channels; +using ErsatzTV.Controllers; +using ErsatzTV.Core.Interfaces.FFmpeg; +using ErsatzTV.Core.Interfaces.Streaming; +using ErsatzTV.Core.Iptv; +using MediatR; +using Microsoft.AspNetCore.Http; +using Microsoft.AspNetCore.Mvc; +using Microsoft.Extensions.Logging; +using NSubstitute; +using NUnit.Framework; +using Shouldly; + +namespace ErsatzTV.Tests.Controllers; + +// #559: dynamic /iptv manifests embed the caller's access_token in their body/URLs, so the response must +// be marked no-store to keep a browser or intermediary from caching (and later replaying) the token. +[TestFixture] +public class IptvControllerCacheHeaderTests +{ + [Test] + public async Task GetChannelPlaylist_sets_no_store() + { + var mediator = Substitute.For(); + mediator.Send(Arg.Any(), Arg.Any()) + .Returns(new ChannelPlaylist("https", "tv.example.com", string.Empty, [], "VLC/3.0", accessToken: null)); + + var controller = new IptvController( + mediator, + Substitute.For(), + Substitute.For>(), + Substitute.For(), + Substitute.For()) + { + ControllerContext = new ControllerContext { HttpContext = new DefaultHttpContext() } + }; + + await controller.GetChannelPlaylist(); + + controller.Response.Headers.CacheControl.ToString().ShouldBe("private, no-store"); + } +} diff --git a/ErsatzTV.Tests/Middleware/RequestLogScrubberTests.cs b/ErsatzTV.Tests/Middleware/RequestLogScrubberTests.cs new file mode 100644 index 000000000..d8a76be5d --- /dev/null +++ b/ErsatzTV.Tests/Middleware/RequestLogScrubberTests.cs @@ -0,0 +1,50 @@ +using ErsatzTV.Middleware; +using Microsoft.AspNetCore.Http; +using NUnit.Framework; +using Shouldly; + +namespace ErsatzTV.Tests.Middleware; + +[TestFixture] +public class RequestLogScrubberTests +{ + private static HttpRequest RequestFor(string path, string queryString) + { + var context = new DefaultHttpContext(); + context.Request.Path = path; + context.Request.QueryString = new QueryString(queryString); + return context.Request; + } + + [Test] + public void Redacts_access_token_but_keeps_other_query_params() + { + HttpRequest request = RequestFor( + "/iptv/channel/1.m3u8", + "?mode=segmenter&access_token=eyJhbGciOiJIUzI1NiJ9.secret.sig"); + + string scrubbed = RequestLogScrubber.ScrubbedPath(request); + + scrubbed.ShouldNotContain("secret"); + scrubbed.ShouldNotContain("eyJhbGciOiJIUzI1NiJ9"); + scrubbed.ShouldContain("access_token=***"); + scrubbed.ShouldContain("mode=segmenter"); + scrubbed.ShouldStartWith("/iptv/channel/1.m3u8?"); + } + + [Test] + public void Redaction_is_case_insensitive_on_the_key() + { + HttpRequest request = RequestFor("/iptv/xmltv.xml", "?Access_Token=secret"); + + RequestLogScrubber.ScrubbedPath(request).ShouldNotContain("secret"); + } + + [Test] + public void Path_without_query_is_returned_verbatim() + { + HttpRequest request = RequestFor("/app", string.Empty); + + RequestLogScrubber.ScrubbedPath(request).ShouldBe("/app"); + } +} diff --git a/ErsatzTV/Controllers/IptvController.cs b/ErsatzTV/Controllers/IptvController.cs index 8868577d7..e75621461 100644 --- a/ErsatzTV/Controllers/IptvController.cs +++ b/ErsatzTV/Controllers/IptvController.cs @@ -48,8 +48,10 @@ public class IptvController : StreamingControllerBase [HttpGet("iptv/channels.m3u")] public Task GetChannelPlaylist( [FromQuery] - string mode = "mixed") => - _mediator.Send( + string mode = "mixed") + { + NoStoreForTokenBearingManifest(); + return _mediator.Send( new GetChannelPlaylist( Request.Scheme, Request.Host.ToString(), @@ -58,17 +60,21 @@ public class IptvController : StreamingControllerBase Request.Headers.UserAgent, Request.Query["access_token"])) .Map(Ok); + } [HttpHead("iptv/xmltv.xml")] [HttpGet("iptv/xmltv.xml")] - public Task GetGuide() => - _mediator.Send( + public Task GetGuide() + { + NoStoreForTokenBearingManifest(); + return _mediator.Send( new GetChannelGuide( Request.Scheme, Request.Host.ToString(), Request.PathBase, Request.Query["access_token"])) .ToActionResult(); + } [HttpHead("iptv/hdhr/channel/{channelNumber}.ts")] [HttpGet("iptv/hdhr/channel/{channelNumber}.ts")] @@ -90,6 +96,9 @@ public class IptvController : StreamingControllerBase [FromQuery] string mode = null) { + // The unspecified/mixed-mode branch below can 302 to .m3u8 with the token in the Location. + NoStoreForTokenBearingManifest(); + Option maybeChannel = await _mediator.Send(new GetChannelByNumber(channelNumber)); if (maybeChannel.IsNone || !await maybeChannel.Map(c => c.IsEnabled).IfNoneAsync(false)) { @@ -200,6 +209,9 @@ public class IptvController : StreamingControllerBase [FromQuery] string mode = "mixed") { + // The multi-variant/media playlists and the redirect Location below all carry the access_token. + NoStoreForTokenBearingManifest(); + Option maybeChannel = await _mediator.Send(new GetChannelByNumber(channelNumber)); if (maybeChannel.IsNone || !await maybeChannel.Map(c => c.IsEnabled).IfNoneAsync(false)) { @@ -370,7 +382,15 @@ public class IptvController : StreamingControllerBase _directStreamSessionTracker); } + // Percent-encode the token so a value containing '"' or '&' cannot break the M3U/HLS URL it is placed + // into (#421). ASP.NET decodes Request.Query, so re-encoding round-trips to the original token; for a + // normal base64url JWT this is a no-op. private string AccessTokenQuery() => string.IsNullOrWhiteSpace(Request.Query["access_token"]) ? string.Empty - : $"?access_token={Request.Query["access_token"]}"; + : $"?access_token={Uri.EscapeDataString(Request.Query["access_token"].ToString())}"; + + // Dynamic /iptv manifests embed the caller's access_token in their body/URLs; mark them no-store so a + // browser or intermediary cache can't retain the token-bearing response and replay it (#559). + private void NoStoreForTokenBearingManifest() => + Response.Headers.CacheControl = "private, no-store"; } diff --git a/ErsatzTV/Middleware/RequestLogScrubber.cs b/ErsatzTV/Middleware/RequestLogScrubber.cs new file mode 100644 index 000000000..8d265b69b --- /dev/null +++ b/ErsatzTV/Middleware/RequestLogScrubber.cs @@ -0,0 +1,35 @@ +using Microsoft.Extensions.Primitives; + +namespace ErsatzTV.Middleware; + +/// +/// Builds the request path Serilog logs with the access_token query value redacted (#559). +/// The default UseSerilogRequestLogging template logs the full query for every request; the +/// ex != null and StatusCode > 499 branches log at Error regardless of path, so a 5xx +/// on an /iptv/...?access_token=<jwt> URL would otherwise write the replayable, globally +/// scoped token to the log. This keeps the rest of the query (e.g. mode=segmenter) for +/// debugging while masking only the credential. +/// +internal static class RequestLogScrubber +{ + private const string TokenParameter = "access_token"; + private const string Redacted = "***"; + + public static string ScrubbedPath(HttpRequest request) + { + string path = request.Path.ToString(); + if (!request.QueryString.HasValue) + { + return path; + } + + var pairs = new List(); + foreach (KeyValuePair pair in request.Query) + { + bool isToken = string.Equals(pair.Key, TokenParameter, StringComparison.OrdinalIgnoreCase); + pairs.Add($"{pair.Key}={(isToken ? Redacted : pair.Value.ToString())}"); + } + + return pairs.Count == 0 ? path : $"{path}?{string.Join('&', pairs)}"; + } +} diff --git a/ErsatzTV/Startup.cs b/ErsatzTV/Startup.cs index 730e6ab68..fa88314f8 100644 --- a/ErsatzTV/Startup.cs +++ b/ErsatzTV/Startup.cs @@ -750,7 +750,9 @@ public class Startup //app.UseHttpLogging(); app.UseSerilogRequestLogging(options => { - options.IncludeQueryInRequestPath = true; + // Keep the query out of the built-in RequestPath; a scrubbed copy (access_token redacted) is + // enriched below as RequestPathScrubbed and referenced by the message template instead (#559). + options.IncludeQueryInRequestPath = false; // Emit debug-level events instead of the defaults options.GetLevel = (httpContext, elapsed, ex) => @@ -789,10 +791,11 @@ public class Startup { diagnosticContext.Set("RemoteIP", httpContext.Connection.RemoteIpAddress); diagnosticContext.Set("UserAgent", httpContext.Request.Headers["User-Agent"]); + diagnosticContext.Set("RequestPathScrubbed", RequestLogScrubber.ScrubbedPath(httpContext.Request)); }; options.MessageTemplate = - "HTTP {RequestMethod} {RequestPath} responded {StatusCode} in {Elapsed:0.00} ms from {UserAgent} at {RemoteIP}"; + "HTTP {RequestMethod} {RequestPathScrubbed} responded {StatusCode} in {Elapsed:0.00} ms from {UserAgent} at {RemoteIP}"; }); app.UseRequestLocalization(options => diff --git a/docs/decisions/README.md b/docs/decisions/README.md index d513f1261..1daafb6f6 100644 --- a/docs/decisions/README.md +++ b/docs/decisions/README.md @@ -128,6 +128,7 @@ the link for rationale. Superseded/retired history lives in `archive/`. Regenera | `security.corp-same-origin` | `SecurityHeadersMiddleware` sends `Cross-Origin-Resource-Policy: same-origin` on every response including `/docs`/`/openapi`, blocking cross-origin `no-cors` embedding without affecting allowed CORS-mode fetches or server-side Jellyfin `/iptv/*` requests. | 2026-07-13 | [link](api-auth-security.md#2026-07-13--cross-origin-resource-policy-same-origin-on-every-response-330) | | `security.csp-permissions-policy` | `SecurityHeadersMiddleware` sends an enforcing (not report-only) `Content-Security-Policy` (no `unsafe-inline`/`unsafe-eval`; the one inline theme-bootstrap script allow-listed by hash) and a deny-all `Permissions-Policy` on the SPA/`/api`/`/artwork`/`/iptv`; `/docs` and `/openapi` keep only the baseline headers, excluded from CSP because Scalar needs inline bootstrap. | 2026-07-12 | [link](api-auth-security.md#2026-07-12--enforcing-csp--permissions-policy-on-the-host-319-zap-baseline) | | `security.fail-closed-api-auth` | Every mutating `/api` request requires `X-Api-Key` (no open mode); reads are gated by `Api:RequireKeyForReads` (default true) OR `[RequiresApiKey]` on sensitive controllers; CORS is an exact-origin allowlist (`ApiCors`); `ForwardedHeaders` trust stays configurable but defaults to trust-all-with-warning. | 2026-07-12 | [link](api-auth-security.md#2026-07-12--fail-closed-api-auth--sensitive-read-tier--corsforwardedheaders-lockdown-197-bundle-a-pr-292) | +| `security.iptv-access-token-transport` | 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`. | 2026-07-23 | [link](api-auth-security.md#2026-07-23--access_token-transport-hardening-percent-encode-in-m3uhls-redact-from-logs-no-store-on-tokened-manifests-421-559) | | `security.iptv-browser-token` | 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`. | 2026-07-22 | [link](api-auth-security.md#2026-07-22--short-lived-browser-iptv-token-so-the-spa-reaches-iptv-under-jwt-auth-552) | | `security.session-auth-dual-credential` | `ApiAuthorizationFilter` accepts a request when a valid `X-Api-Key` matches OR the principal is an authenticated session (cookie `ctv-session`, `HttpOnly`/`SameSite=Lax`); session-authenticated mutations require the presence-only `X-CSRF` header or are rejected 403. This narrows the OIDC-inert sub-claim of `security.blazor-removal-auth-posture` (#206) — the rest of that record's auth-surface enumeration still holds. | 2026-07-12 | [link](api-auth-security.md#2026-07-12--browser-spa-session-auth-api-accepts-session-or-machine-key-295-pr1-server-only) | | `security.session-cutover-postify` | The browser SPA authenticates cookie-only (no more `X-Api-Key` from `web/`); the machine key is repurposed to external/MCP-only via `GET /api/auth/machine-key`; every side-effecting GET/HEAD under `/api` is converted to POST so the existing CSRF gate covers it (standing rule: never add a side-effecting GET/HEAD under `/api`). | 2026-07-12 | [link](api-auth-security.md#2026-07-12--295-pr2-spa-session-cutover--301-side-effecting-get-post-ification) | diff --git a/docs/decisions/api-auth-security.md b/docs/decisions/api-auth-security.md index 918036e24..ce836763d 100644 --- a/docs/decisions/api-auth-security.md +++ b/docs/decisions/api-auth-security.md @@ -23,6 +23,7 @@ contract-freeze), #206 (Blazor-removal auth posture), #283 (artwork content-type - [2026-07-12 — Enforcing CSP + Permissions-Policy on the host (#319, ZAP baseline)](#2026-07-12--enforcing-csp--permissions-policy-on-the-host-319-zap-baseline) - [2026-07-13 — Cross-origin resource policy: `same-origin` on every response (#330)](#2026-07-13--cross-origin-resource-policy-same-origin-on-every-response-330) - [2026-07-22 — Short-lived browser IPTV token so the SPA reaches `/iptv/*` under JWT auth (#552)](#2026-07-22--short-lived-browser-iptv-token-so-the-spa-reaches-iptv-under-jwt-auth-552) +- [2026-07-23 — access_token transport hardening: percent-encode in M3U/HLS, redact from logs, no-store on tokened manifests (#421, #559)](#2026-07-23--access_token-transport-hardening-percent-encode-in-m3uhls-redact-from-logs-no-store-on-tokened-manifests-421-559) --- @@ -464,12 +465,13 @@ closes both with one seam. 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).** The `?access_token=` transport itself has two pre-existing - weaknesses this feature inherits, now bounded by the short lifetime: Serilog's request log includes the - full query (so a token can reach logs on an `/iptv` 5xx), and the token-bearing dynamic manifests carry no - `Cache-Control: no-store`. Both predate this feature (Jellyfin and the M3U playlist already pass - `access_token` in `/iptv` URLs) and their fixes are cross-cutting changes to shared request-logging / - manifest behavior — tracked as a follow-up in #559, not folded here. +- **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 @@ -477,3 +479,49 @@ closes both with one seam. `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. + +## 2026-07-23 — access_token transport hardening: percent-encode in M3U/HLS, redact from logs, no-store on tokened manifests (#421, #559) +`key: security.iptv-access-token-transport` · `status: active` · `since: 2026-07-23` · `supersedes: none` · `superseded-by: none` +**Rule:** 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`. +**Signals:** 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 +**Mechanics:** `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. -- 2.47.3 From 26ec6ac5d84dbed2fec7d78bb94c7367e13d2e53 Mon Sep 17 00:00:00 2001 From: Timothy Date: Thu, 23 Jul 2026 08:32:54 +0200 Subject: [PATCH 2/2] docs(decisions): [decisions-edit] authorize the #552 record prose edit MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The prior commit updated the "deferred hardening" bullet of the `security.iptv-browser-token` (#552) record — marking it RESOLVED and pointing to the new `security.iptv-access-token-transport` record — plus its Rule/Signals lines. That is a rationale-prose edit of an existing decision (exactly what #559's done-when asked for: "fold into the deferred-hardening note under security.iptv-browser-token"), so it needs the [decisions-edit] marker for the lifecycle validator. No record heading renamed, no record removed; the #552 key/status/heading are unchanged. Co-Authored-By: Claude Opus 4.8 (1M context) -- 2.47.3