Add anonymous playback with an optional Spotify-style preview cap

New Playback:AllowAnonymousListening / Playback:AnonymousFragmentSeconds
settings control whether a request without a session can stream at all,
and if so, whether it's limited to a fragment instead of the full track:

- GET /tracks/{id}/stream and GET /youtube/tracks/{videoId}/stream no
  longer require authorization outright; the handlers gate on the config
  instead, so both keep working exactly as before when it's off (the
  default).
- The fragment cap is enforced by the Streaming Gateway, not the client:
  the stream ticket now carries an optional maxBytes claim (computed from
  AnonymousFragmentSeconds and the transcoder's known bitrate), and
  TicketValidationMiddleware clamps the Range it forwards to SeaweedFS to
  stay under it — synthesizing one if the request didn't send one, and
  answering 416 outright if the requested range starts past the cap.
- A YouTube track that hasn't been provisioned server-side yet streams
  straight from YouTube's CDN, bypassing the Gateway entirely — there's no
  way to cap that, so an anonymous request for one is refused (409) instead
  of silently handing out an uncapped stream.
- ListeningHistory has a non-nullable UserId, so anonymous plays simply
  don't get recorded rather than trying to force a row through the FK.

Also fixes a real, pre-existing bug this surfaced: the AppSettings.Development.json
of the Api, Worker, and StreamingGateway all pointed StreamTicket/Workers
paths at "../../deploy/..." — one directory short of deploy/'s actual
location at the repo root relative to each project's own folder. Docker
never hit this (it mounts an absolute /keys path), so it had apparently
never been exercised via `dotnet run` before.

backend/Tests/Musify.Application.Tests/Services/TrackStreamIssuerTests.cs

@@ -1,4 +1,5 @@
 using Microsoft.EntityFrameworkCore;
+using Musify.Application.Configuration;
 using Musify.Application.Contracts;
 using Musify.Application.Services;
 using Musify.Application.Tests.TestSupport;
@@ -11,13 +12,17 @@ namespace Musify.Application.Tests.Services
     {
         private readonly IStreamTicketService ticketService = Substitute.For<IStreamTicketService>();
 
-        private TrackStreamIssuer CreateIssuer() => new(
-            Database, ticketService, TestConfigurations.Track(), TestConfigurations.StreamGateway("https://stream.musify.test/"));
+        private TrackStreamIssuer CreateIssuer(PlaybackConfiguration? playback = null) => new(
+            Database,
+            ticketService,
+            TestConfigurations.Track(),
+            TestConfigurations.StreamGateway("https://stream.musify.test/"),
+            playback ?? TestConfigurations.Playback());
 
         [Fact]
         public async Task IssueAsync_BuildsManifestUrlAndRecordsListeningHistory()
         {
-            ticketService.IssueTicket(7, Arg.Any<string>()).Returns(new StreamTicket("signed-token", 120));
+            ticketService.IssueTicket(7, Arg.Any<string>(), Arg.Any<long?>()).Returns(new StreamTicket("signed-token", 120));
             var owner = TestEntities.User(7);
             var track = TestEntities.LocalTrack(owner);
             await SeedAsync(owner, track);
@@ -38,14 +43,57 @@ namespace Musify.Application.Tests.Services
         [Fact]
         public async Task IssueAsync_PassesTheProcessedAudioKeyPrefixToTheTicketService()
         {
-            ticketService.IssueTicket(Arg.Any<long>(), Arg.Any<string>()).Returns(new StreamTicket("token", 60));
+            ticketService.IssueTicket(Arg.Any<long?>(), Arg.Any<string>(), Arg.Any<long?>()).Returns(new StreamTicket("token", 60));
             var owner = TestEntities.User(1);
             var track = TestEntities.LocalTrack(owner);
             await SeedAsync(owner, track);
 
             await CreateIssuer().IssueAsync(track.Id, "folder-42", userId: 1, TestContext.Current.CancellationToken);
 
-            ticketService.Received(1).IssueTicket(1, "Tracks/ProcessedAudios/folder-42/");
+            ticketService.Received(1).IssueTicket(1, "Tracks/ProcessedAudios/folder-42/", null);
+        }
+
+        [Fact]
+        public async Task IssueAsync_AnonymousUser_SkipsListeningHistoryAndNeverThrows()
+        {
+            ticketService.IssueTicket(Arg.Any<long?>(), Arg.Any<string>(), Arg.Any<long?>()).Returns(new StreamTicket("token", 60));
+            var owner = TestEntities.User(1);
+            var track = TestEntities.LocalTrack(owner);
+            await SeedAsync(owner, track);
+
+            var response = await CreateIssuer(TestConfigurations.Playback(allowAnonymousListening: true))
+                .IssueAsync(track.Id, "folder-42", userId: null, TestContext.Current.CancellationToken);
+
+            Assert.Equal("token", response.Ticket);
+            Assert.Empty(await Database.ListeningHistories.ToListAsync(TestContext.Current.CancellationToken));
+        }
+
+        [Fact]
+        public async Task IssueAsync_AnonymousUserWithFragmentConfigured_PassesTheByteCapToTheTicketService()
+        {
+            ticketService.IssueTicket(Arg.Any<long?>(), Arg.Any<string>(), Arg.Any<long?>()).Returns(new StreamTicket("token", 60));
+            var owner = TestEntities.User(1);
+            var track = TestEntities.LocalTrack(owner);
+            await SeedAsync(owner, track);
+
+            var playback = TestConfigurations.Playback(allowAnonymousListening: true, anonymousFragmentSeconds: 30);
+            await CreateIssuer(playback).IssueAsync(track.Id, "folder-42", userId: null, TestContext.Current.CancellationToken);
+
+            ticketService.Received(1).IssueTicket(null, "Tracks/ProcessedAudios/folder-42/", 30L * playback.EstimatedAudioBytesPerSecond);
+        }
+
+        [Fact]
+        public async Task IssueAsync_AuthenticatedUser_IgnoresTheAnonymousFragmentCap()
+        {
+            ticketService.IssueTicket(Arg.Any<long?>(), Arg.Any<string>(), Arg.Any<long?>()).Returns(new StreamTicket("token", 60));
+            var owner = TestEntities.User(1);
+            var track = TestEntities.LocalTrack(owner);
+            await SeedAsync(owner, track);
+
+            var playback = TestConfigurations.Playback(allowAnonymousListening: true, anonymousFragmentSeconds: 30);
+            await CreateIssuer(playback).IssueAsync(track.Id, "folder-42", userId: 1, TestContext.Current.CancellationToken);
+
+            ticketService.Received(1).IssueTicket(1, "Tracks/ProcessedAudios/folder-42/", null);
         }
     }
 }

backend/Tests/Musify.Application.Tests/TestSupport/TestConfigurations.cs

@@ -17,5 +17,8 @@ namespace Musify.Application.Tests.TestSupport
 
         public static StreamGatewayConfiguration StreamGateway(string publicBaseUrl = "https://stream.musify.test") =>
             new() { PublicBaseUrl = publicBaseUrl };
+
+        public static PlaybackConfiguration Playback(bool allowAnonymousListening = false, int anonymousFragmentSeconds = 0) =>
+            new() { AllowAnonymousListening = allowAnonymousListening, AnonymousFragmentSeconds = anonymousFragmentSeconds };
     }
 }

backend/Tests/Musify.Application.Tests/Tracks/GetTrackStreamQueryHandlerTests.cs

@@ -1,5 +1,6 @@
 using ErrorOr;
 using Microsoft.EntityFrameworkCore;
+using Musify.Application.Configuration;
 using Musify.Application.Contracts;
 using Musify.Application.Services;
 using Musify.Application.Tests.TestSupport;
@@ -13,17 +14,18 @@ namespace Musify.Application.Tests.Tracks
     {
         private readonly IStreamTicketService ticketService = Substitute.For<IStreamTicketService>();
 
-        private GetTrackStreamQueryHandler CreateHandler()
+        private GetTrackStreamQueryHandler CreateHandler(PlaybackConfiguration? playback = null)
         {
-            ticketService.IssueTicket(Arg.Any<long>(), Arg.Any<string>()).Returns(new StreamTicket("ticket-token", 60));
+            ticketService.IssueTicket(Arg.Any<long?>(), Arg.Any<string>(), Arg.Any<long?>()).Returns(new StreamTicket("ticket-token", 60));
 
             var issuer = new TrackStreamIssuer(
                 Database,
                 ticketService,
                 TestConfigurations.Track(),
-                TestConfigurations.StreamGateway("https://stream.musify.test"));
+                TestConfigurations.StreamGateway("https://stream.musify.test"),
+                playback ?? TestConfigurations.Playback());
 
-            return new GetTrackStreamQueryHandler(Database, issuer, NoOpLogger<GetTrackStreamQueryHandler>());
+            return new GetTrackStreamQueryHandler(Database, issuer, playback ?? TestConfigurations.Playback(), NoOpLogger<GetTrackStreamQueryHandler>());
         }
 
         [Fact]
@@ -64,5 +66,35 @@ namespace Musify.Application.Tests.Tracks
 
             Assert.Equal(ErrorType.Conflict, result.FirstError.Type);
         }
+
+        [Fact]
+        public async Task Handle_AnonymousUser_AnonymousListeningDisabled_ReturnsUnauthorized()
+        {
+            var owner = TestEntities.User();
+            var track = TestEntities.LocalTrack(owner);
+            await SeedAsync(owner, track);
+
+            var handler = CreateHandler(TestConfigurations.Playback(allowAnonymousListening: false));
+
+            var result = await handler.Handle(new GetTrackStreamQuery(track.Id, UserId: null), TestContext.Current.CancellationToken);
+
+            Assert.Equal(ErrorType.Unauthorized, result.FirstError.Type);
+        }
+
+        [Fact]
+        public async Task Handle_AnonymousUser_AnonymousListeningEnabled_IssuesTicketWithoutRecordingHistory()
+        {
+            var owner = TestEntities.User();
+            var track = TestEntities.LocalTrack(owner);
+            await SeedAsync(owner, track);
+
+            var handler = CreateHandler(TestConfigurations.Playback(allowAnonymousListening: true));
+
+            var result = await handler.Handle(new GetTrackStreamQuery(track.Id, UserId: null), TestContext.Current.CancellationToken);
+
+            Assert.False(result.IsError);
+            Assert.Equal("ticket-token", result.Value.Ticket);
+            Assert.Empty(await Database.ListeningHistories.ToListAsync(TestContext.Current.CancellationToken));
+        }
     }
 }

backend/Tests/Musify.Application.Tests/YouTube/ResolveYouTubeTrackStreamCommandHandlerTests.cs

@@ -1,4 +1,6 @@
+using ErrorOr;
 using Microsoft.EntityFrameworkCore;
+using Musify.Application.Configuration;
 using Musify.Application.Contracts;
 using Musify.Application.Services;
 using Musify.Application.Tests.TestSupport;
@@ -14,21 +16,22 @@ namespace Musify.Application.Tests.YouTube
         private readonly IYouTubeMusicService youTubeMusicService = Substitute.For<IYouTubeMusicService>();
         private readonly IStreamTicketService ticketService = Substitute.For<IStreamTicketService>();
 
-        private ResolveYouTubeTrackStreamCommandHandler CreateHandler()
+        private ResolveYouTubeTrackStreamCommandHandler CreateHandler(PlaybackConfiguration? playback = null)
         {
+            playback ??= TestConfigurations.Playback();
             var provisioner = new YouTubeTrackProvisioner(
                 Database, youTubeMusicService, TestConfigurations.Track(), NoOpLogger<YouTubeTrackProvisioner>());
             var issuer = new TrackStreamIssuer(
-                Database, ticketService, TestConfigurations.Track(), TestConfigurations.StreamGateway());
+                Database, ticketService, TestConfigurations.Track(), TestConfigurations.StreamGateway(), playback);
 
             return new ResolveYouTubeTrackStreamCommandHandler(
-                Database, youTubeMusicService, provisioner, issuer, NoOpLogger<ResolveYouTubeTrackStreamCommandHandler>());
+                Database, youTubeMusicService, provisioner, issuer, playback, NoOpLogger<ResolveYouTubeTrackStreamCommandHandler>());
         }
 
         [Fact]
         public async Task Handle_AlreadyProcessedTrack_IssuesServerStreamWithoutCallingYouTubeForAudio()
         {
-            ticketService.IssueTicket(Arg.Any<long>(), Arg.Any<string>()).Returns(new StreamTicket("token", 60));
+            ticketService.IssueTicket(Arg.Any<long?>(), Arg.Any<string>(), Arg.Any<long?>()).Returns(new StreamTicket("token", 60));
 
             var user = TestEntities.User(1);
             var track = TestEntities.ExternalTrack(externalId: "abc123");
@@ -62,5 +65,61 @@ namespace Musify.Application.Tests.YouTube
             var history = Assert.Single(await Database.ListeningHistories.ToListAsync(TestContext.Current.CancellationToken));
             Assert.Equal(42, history.UserId);
         }
+
+        [Fact]
+        public async Task Handle_AnonymousUser_AnonymousListeningDisabled_ReturnsUnauthorized()
+        {
+            var handler = CreateHandler(TestConfigurations.Playback(allowAnonymousListening: false));
+
+            var result = await handler.Handle(new ResolveYouTubeTrackStreamCommand("abc123", UserId: null), TestContext.Current.CancellationToken);
+
+            Assert.Equal(ErrorType.Unauthorized, result.FirstError.Type);
+            await youTubeMusicService.DidNotReceiveWithAnyArgs().GetAudioStreamAsync(default!, TestContext.Current.CancellationToken);
+        }
+
+        [Fact]
+        public async Task Handle_AnonymousUser_AlreadyProcessedTrack_IssuesServerStreamWithoutRecordingHistory()
+        {
+            ticketService.IssueTicket(Arg.Any<long?>(), Arg.Any<string>(), Arg.Any<long?>()).Returns(new StreamTicket("token", 60));
+            var track = TestEntities.ExternalTrack(externalId: "abc123");
+            await SeedAsync(track);
+
+            var handler = CreateHandler(TestConfigurations.Playback(allowAnonymousListening: true));
+
+            var result = await handler.Handle(new ResolveYouTubeTrackStreamCommand("abc123", UserId: null), TestContext.Current.CancellationToken);
+
+            Assert.False(result.IsError);
+            Assert.Equal(YouTubeStreamMode.Server, result.Value.Mode);
+            Assert.Empty(await Database.ListeningHistories.ToListAsync(TestContext.Current.CancellationToken));
+        }
+
+        [Fact]
+        public async Task Handle_AnonymousUser_FragmentCapConfigured_UnprovisionedTrack_ReturnsConflictWithoutCallingYouTube()
+        {
+            var handler = CreateHandler(TestConfigurations.Playback(allowAnonymousListening: true, anonymousFragmentSeconds: 30));
+
+            var result = await handler.Handle(new ResolveYouTubeTrackStreamCommand("not-provisioned-yet", UserId: null), TestContext.Current.CancellationToken);
+
+            Assert.Equal(ErrorType.Conflict, result.FirstError.Type);
+            await youTubeMusicService.DidNotReceiveWithAnyArgs().GetAudioStreamAsync(default!, TestContext.Current.CancellationToken);
+        }
+
+        [Fact]
+        public async Task Handle_AnonymousUser_NoFragmentCap_UnprovisionedTrack_FallsBackToDirectYouTubeStream()
+        {
+            youTubeMusicService.GetAudioStreamAsync("new-video", Arg.Any<CancellationToken>())
+                .Returns(new YouTubeStreamInfo("https://youtube.example/stream", 300));
+            youTubeMusicService.GetSongAsync("new-video", Arg.Any<CancellationToken>())
+                .Returns(new YouTubeSongResult("new-video", "Title", "Artist", "Album", 200, "https://img/thumb.jpg", false, []));
+            youTubeMusicService.ResolveArtworkUrl(Arg.Any<string>()).Returns(callInfo => callInfo.Arg<string>());
+
+            var handler = CreateHandler(TestConfigurations.Playback(allowAnonymousListening: true, anonymousFragmentSeconds: 0));
+
+            var result = await handler.Handle(new ResolveYouTubeTrackStreamCommand("new-video", UserId: null), TestContext.Current.CancellationToken);
+
+            Assert.False(result.IsError);
+            Assert.Equal(YouTubeStreamMode.YouTube, result.Value.Mode);
+            Assert.Empty(await Database.ListeningHistories.ToListAsync(TestContext.Current.CancellationToken));
+        }
     }
 }

backend/Tests/Musify.Infrastructure.Tests/Services/StreamTicketServiceTests.cs

@@ -45,6 +45,43 @@ namespace Musify.Infrastructure.Tests.Services
             Assert.Contains("media-gateway", jwt.Audiences);
         }
 
+        [Fact]
+        public void IssueTicket_AnonymousUser_OmitsTheSubClaim()
+        {
+            using var service = CreateService();
+
+            var ticket = service.IssueTicket(userId: null, keyPrefix: "Tracks/ProcessedAudios/abc/");
+
+            var handler = new JsonWebTokenHandler();
+            var jwt = handler.ReadJsonWebToken(ticket.Token);
+            Assert.DoesNotContain(jwt.Claims, c => c.Type == "sub");
+            Assert.Equal("Tracks/ProcessedAudios/abc/", jwt.GetClaim("prefix").Value);
+        }
+
+        [Fact]
+        public void IssueTicket_WithMaxBytes_IncludesTheMaxBytesClaim()
+        {
+            using var service = CreateService();
+
+            var ticket = service.IssueTicket(userId: null, keyPrefix: "Tracks/ProcessedAudios/abc/", maxBytes: 480_000);
+
+            var handler = new JsonWebTokenHandler();
+            var jwt = handler.ReadJsonWebToken(ticket.Token);
+            Assert.Equal("480000", jwt.GetClaim("maxBytes").Value);
+        }
+
+        [Fact]
+        public void IssueTicket_WithoutMaxBytes_OmitsTheMaxBytesClaim()
+        {
+            using var service = CreateService();
+
+            var ticket = service.IssueTicket(userId: 1, keyPrefix: "Tracks/ProcessedAudios/abc/");
+
+            var handler = new JsonWebTokenHandler();
+            var jwt = handler.ReadJsonWebToken(ticket.Token);
+            Assert.DoesNotContain(jwt.Claims, c => c.Type == "maxBytes");
+        }
+
         [Fact]
         public async Task IssueTicket_TokenValidatesAgainstTheMatchingPublicKey()
         {

backend/Tests/Musify.StreamingGateway.Tests/Authentication/TicketValidatorTests.cs

@@ -33,15 +33,19 @@ namespace Musify.StreamingGateway.Tests.Authentication
         }));
 
         private string IssueToken(string prefix = "Tracks/ProcessedAudios/abc/", string issuer = Issuer, string audience = Audience,
-            DateTime? expires = null, DateTime? notBefore = null)
+            DateTime? expires = null, DateTime? notBefore = null, long? maxBytes = null)
         {
+            var claims = new Dictionary<string, object> { ["prefix"] = prefix };
+            if (maxBytes is not null)
+                claims["maxBytes"] = maxBytes.Value.ToString();
+
             var descriptor = new SecurityTokenDescriptor
             {
                 Issuer = issuer,
                 Audience = audience,
                 NotBefore = notBefore ?? DateTime.UtcNow.AddMinutes(-1),
                 Expires = expires ?? DateTime.UtcNow.AddMinutes(5),
-                Claims = new Dictionary<string, object> { ["prefix"] = prefix },
+                Claims = claims,
                 SigningCredentials = new SigningCredentials(new RsaSecurityKey(rsa), SecurityAlgorithms.RsaSha256),
             };
             return tokenHandler.CreateToken(descriptor);
@@ -52,62 +56,76 @@ namespace Musify.StreamingGateway.Tests.Authentication
         {
             var token = IssueToken(prefix: "Tracks/ProcessedAudios/xyz/");
 
-            var prefix = await CreateValidator().ValidateTicketAsync(token);
+            var result = await CreateValidator().ValidateTicketAsync(token);
 
-            Assert.Equal("Tracks/ProcessedAudios/xyz/", prefix);
+            Assert.True(result.IsValid);
+            Assert.Equal("Tracks/ProcessedAudios/xyz/", result.Prefix);
+            Assert.Null(result.MaxBytes);
+        }
+
+        [Fact]
+        public async Task ValidateTicketAsync_TokenWithMaxBytesClaim_ReturnsIt()
+        {
+            var token = IssueToken(maxBytes: 480_000);
+
+            var result = await CreateValidator().ValidateTicketAsync(token);
+
+            Assert.True(result.IsValid);
+            Assert.Equal(480_000, result.MaxBytes);
         }
 
         [Theory]
         [InlineData(null)]
         [InlineData("")]
         [InlineData("   ")]
-        public async Task ValidateTicketAsync_BlankToken_ReturnsEmptyString(string? token)
+        public async Task ValidateTicketAsync_BlankToken_ReturnsInvalid(string? token)
         {
-            var prefix = await CreateValidator().ValidateTicketAsync(token);
+            var result = await CreateValidator().ValidateTicketAsync(token);
 
-            Assert.Equal(string.Empty, prefix);
+            Assert.False(result.IsValid);
+            Assert.Equal(string.Empty, result.Prefix);
         }
 
         [Fact]
-        public async Task ValidateTicketAsync_MalformedToken_ReturnsEmptyString()
+        public async Task ValidateTicketAsync_MalformedToken_ReturnsInvalid()
         {
-            var prefix = await CreateValidator().ValidateTicketAsync("not-a-real-jwt");
+            var result = await CreateValidator().ValidateTicketAsync("not-a-real-jwt");
 
-            Assert.Equal(string.Empty, prefix);
+            Assert.False(result.IsValid);
         }
 
         [Fact]
-        public async Task ValidateTicketAsync_ExpiredToken_ReturnsEmptyString()
+        public async Task ValidateTicketAsync_ExpiredToken_ReturnsInvalid()
         {
             var token = IssueToken(expires: DateTime.UtcNow.AddMinutes(-40), notBefore: DateTime.UtcNow.AddMinutes(-50));
 
-            var prefix = await CreateValidator().ValidateTicketAsync(token);
+            var result = await CreateValidator().ValidateTicketAsync(token);
 
-            Assert.Equal(string.Empty, prefix);
+            Assert.False(result.IsValid);
         }
 
         [Fact]
-        public async Task ValidateTicketAsync_WrongIssuer_ReturnsEmptyString()
+        public async Task ValidateTicketAsync_WrongIssuer_ReturnsInvalid()
         {
             var token = IssueToken(issuer: "someone-else");
 
-            var prefix = await CreateValidator().ValidateTicketAsync(token);
+            var result = await CreateValidator().ValidateTicketAsync(token);
 
-            Assert.Equal(string.Empty, prefix);
+            Assert.False(result.IsValid);
         }
 
         [Fact]
-        public async Task ValidateTicketAsync_WrongAudience_ReturnsEmptyString()
+        public async Task ValidateTicketAsync_WrongAudience_ReturnsInvalid()
         {
             var token = IssueToken(audience: "someone-else");
 
-            var prefix = await CreateValidator().ValidateTicketAsync(token);
+            var result = await CreateValidator().ValidateTicketAsync(token);
 
-            Assert.Equal(string.Empty, prefix);
+            Assert.False(result.IsValid);
         }
 
         [Fact]
-        public async Task ValidateTicketAsync_SignedWithADifferentKey_ReturnsEmptyString()
+        public async Task ValidateTicketAsync_SignedWithADifferentKey_ReturnsInvalid()
         {
             using var otherKey = RSA.Create(2048);
             var descriptor = new SecurityTokenDescriptor
@@ -121,13 +139,13 @@ namespace Musify.StreamingGateway.Tests.Authentication
             };
             var token = tokenHandler.CreateToken(descriptor);
 
-            var prefix = await CreateValidator().ValidateTicketAsync(token);
+            var result = await CreateValidator().ValidateTicketAsync(token);
 
-            Assert.Equal(string.Empty, prefix);
+            Assert.False(result.IsValid);
         }
 
         [Fact]
-        public async Task ValidateTicketAsync_MissingPrefixClaim_ReturnsEmptyString()
+        public async Task ValidateTicketAsync_MissingPrefixClaim_ReturnsInvalid()
         {
             var descriptor = new SecurityTokenDescriptor
             {
@@ -139,9 +157,9 @@ namespace Musify.StreamingGateway.Tests.Authentication
             };
             var token = tokenHandler.CreateToken(descriptor);
 
-            var prefix = await CreateValidator().ValidateTicketAsync(token);
+            var result = await CreateValidator().ValidateTicketAsync(token);
 
-            Assert.Equal(string.Empty, prefix);
+            Assert.False(result.IsValid);
         }
     }
 }

backend/Tests/Musify.StreamingGateway.Tests/Middleware/TicketValidationMiddlewareTests.cs

@@ -36,15 +36,22 @@ namespace Musify.StreamingGateway.Tests.Middleware
             File.Delete(publicKeyPath);
         }
 
-        private string IssueValidToken(string prefix = Prefix) => new JsonWebTokenHandler().CreateToken(new SecurityTokenDescriptor
+        private string IssueValidToken(string prefix = Prefix, long? maxBytes = null)
         {
-            Issuer = options.Issuer,
-            Audience = options.Audience,
-            NotBefore = DateTime.UtcNow.AddMinutes(-1),
-            Expires = DateTime.UtcNow.AddMinutes(5),
-            Claims = new Dictionary<string, object> { ["prefix"] = prefix },
-            SigningCredentials = new SigningCredentials(new RsaSecurityKey(rsa), SecurityAlgorithms.RsaSha256),
-        });
+            var claims = new Dictionary<string, object> { ["prefix"] = prefix };
+            if (maxBytes is not null)
+                claims["maxBytes"] = maxBytes.Value.ToString();
+
+            return new JsonWebTokenHandler().CreateToken(new SecurityTokenDescriptor
+            {
+                Issuer = options.Issuer,
+                Audience = options.Audience,
+                NotBefore = DateTime.UtcNow.AddMinutes(-1),
+                Expires = DateTime.UtcNow.AddMinutes(5),
+                Claims = claims,
+                SigningCredentials = new SigningCredentials(new RsaSecurityKey(rsa), SecurityAlgorithms.RsaSha256),
+            });
+        }
 
         private (TicketValidationMiddleware Middleware, Func<bool> WasNextCalled) CreateMiddleware()
         {
@@ -150,5 +157,64 @@ namespace Musify.StreamingGateway.Tests.Middleware
 
             Assert.True(wasNextCalled());
         }
+
+        [Fact]
+        public async Task InvokeAsync_TicketWithMaxBytes_NoRangeRequested_SynthesizesABoundedRange()
+        {
+            var (middleware, wasNextCalled) = CreateMiddleware();
+            var context = new DefaultHttpContext();
+            context.Request.Path = $"/media/{Prefix}/audio.m4a";
+            context.Request.QueryString = new QueryString($"?t={IssueValidToken(maxBytes: 480_000)}");
+
+            await middleware.InvokeAsync(context);
+
+            Assert.True(wasNextCalled());
+            Assert.Equal("bytes=0-479999", context.Request.Headers.Range.ToString());
+        }
+
+        [Fact]
+        public async Task InvokeAsync_TicketWithMaxBytes_RangeWithinCap_ClampsTheEndOnly()
+        {
+            var (middleware, wasNextCalled) = CreateMiddleware();
+            var context = new DefaultHttpContext();
+            context.Request.Path = $"/media/{Prefix}/audio.m4a";
+            context.Request.QueryString = new QueryString($"?t={IssueValidToken(maxBytes: 480_000)}");
+            context.Request.Headers.Range = "bytes=1000-";
+
+            await middleware.InvokeAsync(context);
+
+            Assert.True(wasNextCalled());
+            Assert.Equal("bytes=1000-479999", context.Request.Headers.Range.ToString());
+        }
+
+        [Fact]
+        public async Task InvokeAsync_TicketWithMaxBytes_RangeStartsAtOrPastTheCap_ReturnsRangeNotSatisfiable()
+        {
+            var (middleware, wasNextCalled) = CreateMiddleware();
+            var context = new DefaultHttpContext();
+            context.Request.Path = $"/media/{Prefix}/audio.m4a";
+            context.Request.QueryString = new QueryString($"?t={IssueValidToken(maxBytes: 480_000)}");
+            context.Request.Headers.Range = "bytes=480000-";
+
+            await middleware.InvokeAsync(context);
+
+            Assert.False(wasNextCalled());
+            Assert.Equal(StatusCodes.Status416RangeNotSatisfiable, context.Response.StatusCode);
+        }
+
+        [Fact]
+        public async Task InvokeAsync_TicketWithoutMaxBytes_LeavesTheRequestedRangeUntouched()
+        {
+            var (middleware, wasNextCalled) = CreateMiddleware();
+            var context = new DefaultHttpContext();
+            context.Request.Path = $"/media/{Prefix}/audio.m4a";
+            context.Request.QueryString = new QueryString($"?t={IssueValidToken()}");
+            context.Request.Headers.Range = "bytes=1000-2000";
+
+            await middleware.InvokeAsync(context);
+
+            Assert.True(wasNextCalled());
+            Assert.Equal("bytes=1000-2000", context.Request.Headers.Range.ToString());
+        }
     }
 }