Merge pull request #7610 from TChukwuleta/ft/manifest-redirect-bcp47
What changed, and why it matters
This commit hardens how BTCPay Server downloads translation files from GitHub. It adds checks so the app only fetches files from the project's own trusted GitHub organization, blocks automatic web redirects, and supports a new optional redirect field in the manifest only if it also stays within that trusted organization. It also adds a new BCP47 language identifier field. The changes are defensive: they close paths where a malicious or compromised manifest could trick the server into downloading files from an attacker's site.
No immediate action required; this is a hardening patch. Reviewers should verify that the trusted-org check correctly handles all URL canonicalization edge cases (e.g., percent-encoded separators, case variations, userinfo, non-standard ports) and that the manifest redirect cannot be used to chain to an untrusted host. Consider whether the trusted path prefix should also enforce a specific repository name.
Security signals we found
Server-side request forgery (SSRF) protection added: URI host/path validation before outbound fetch
Automatic HTTP redirects disabled for translation update client
Manifest redirect field introduced with same-origin/org trust validation
Language pack file paths resolved relative to manifest URI and validated against trusted prefix
Path traversal and URL-encoded dot-segment payloads rejected in tests
HTTP-to-HTTPS downgrade and lookalike hostnames rejected in tests
SHA-256 integrity check on downloaded language packs already existed and is retained
Evidence from the diff
The patch modifies the translation plugin’s update service. Previously it used a fixed base URL and the default HttpClient. Now it: (1) registers a named HttpClient with AllowAutoRedirect=false to prevent automatic HTTP redirects; (2) validates every URI against a trusted host/path prefix (raw.githubusercontent.com/btcpayserver/); (3) supports a Redirect field in the root manifest but validates the redirect target the same way; (4) resolves language pack files relative to the manifest URI and validates them; (5) parses the manifest as a byte stream to handle UTF-8 BOM; (6) adds a Bcp47 property to manifest entries. Tests cover path traversal, encoded dot-segments, scheme/downgrade, and host-subdomain injection attempts.
Changed components
BTCPayServer/Plugins/Translations/LanguagePackUpdateService.csBTCPayServer/Plugins/Translations/TranslationsPlugin.csBTCPayServer.Tests/LanguageServiceTests.csInspect captured patch +223 / −39
### BTCPayServer.Tests/LanguageServiceTests.cs
@@ -13,6 +13,7 @@
using Dapper;
using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.Caching.Memory;
+using Microsoft.Extensions.DependencyInjection;
using Microsoft.Playwright;
using Newtonsoft.Json.Linq;
using static Microsoft.Playwright.Assertions;
@@ -33,7 +34,11 @@ private class RealHttpClientFactory : IHttpClientFactory
private sealed class TestHttpClientFactory(HttpMessageHandler handler) : IHttpClientFactory
{
- public HttpClient CreateClient(string name) => new(handler, false);
+ public HttpClient CreateClient(string name)
+ {
+ Assert.Equal(LanguagePackUpdateService.HttpClientName, name);
+ return new HttpClient(handler, false);
+ }
}
public LanguageServiceTests(ITestOutputHelper helper) : base(helper)
@@ -44,7 +49,7 @@ private static LanguagePackUpdateService CreateLanguageService(HttpMessageHandle
new(new TestHttpClientFactory(handler), new MemoryCache(new MemoryCacheOptions()));
[Fact(Timeout = TestTimeout)]
- [Trait("Unit", "Unit")]
+ [Trait("Fast", "Fast")]
public async Task LanguagePackUpdateService_ParsesManifestEntries()
{
var handler = new TestHttpMessageHandler();
@@ -54,6 +59,7 @@ public async Task LanguagePackUpdateService_ParsesManifestEntries()
"Languages": [
{
"Name": "French",
+ "Bcp47": "fr-FR",
"Native": "Francais",
"File": "translations/french.json",
"Sha": "sha-fr",
@@ -78,6 +84,7 @@ public async Task LanguagePackUpdateService_ParsesManifestEntries()
Assert.Equal(2, languages.Length);
var french = languages.Single(l => l.Name == "French");
+ Assert.Equal("fr-FR", french.Bcp47);
Assert.Equal("Francais", french.Native);
Assert.Equal("alice", french.MaintainerHandle);
Assert.Equal("https://github.com/alice", french.MaintainerUrl);
@@ -92,6 +99,158 @@ public async Task LanguagePackUpdateService_ParsesManifestEntries()
Assert.Null(german.Updated);
}
+ [Fact(Timeout = TestTimeout)]
+ [Trait("Fast", "Fast")]
+ public async Task LanguagePackUpdateService_ParsesManifestWithUtf8Bom()
+ {
+ var handler = new TestHttpMessageHandler();
+ handler.Register(ManifestUrl, () => new HttpResponseMessage(HttpStatusCode.OK)
+ {
+ Content = new ByteArrayContent(Encoding.UTF8.GetPreamble()
+ .Concat(Encoding.UTF8.GetBytes("{\"Languages\":[]}")).ToArray())
+ });
+
+ var service = CreateLanguageService(handler);
+ Assert.Empty(await service.GetManifestLanguages());
+ }
+
+ [Theory(Timeout = TestTimeout)]
+ [Trait("Fast", "Fast")]
+ [InlineData("../../../evil-org/repo/main/pack.json")]
+ [InlineData("%2e%2e/%2e%2e/%2e%2e/evil-org/repo/main/pack.json")]
+ [InlineData("https://evil.example/pack.json")]
+ [InlineData("//evil.example/pack.json")]
+ public async Task LanguagePackUpdateService_RejectsPackOutsideTrustedOrg(string file)
+ {
+ var requests = 0;
+ var handler = new TestHttpMessageHandler(request =>
+ {
+ requests++;
+ Assert.Equal(ManifestUrl, request.RequestUri!.AbsoluteUri);
+ return TestHttpMessageHandler.JsonResponse(
+ $$"""{ "Languages": [{ "Name": "French", "File": "{{file}}", "Sha": "unused" }] }""");
+ });
+
+ var service = CreateLanguageService(handler);
+ await Assert.ThrowsAsync<InvalidOperationException>(() => service.FetchLanguagePackFromRepository("French"));
+ Assert.Equal(1, requests);
+ }
+
+ [Fact(Timeout = TestTimeout)]
+ [Trait("Fast", "Fast")]
+ public void LanguagePackUpdateService_ClientDisablesAutomaticRedirects()
+ {
+ var services = new ServiceCollection();
+ services.AddLogging();
+ new TranslationsPlugin().Execute(services);
+ using var provider = services.BuildServiceProvider();
+ var handler = provider.GetRequiredService<IHttpMessageHandlerFactory>().CreateHandler(LanguagePackUpdateService.HttpClientName);
+ while (handler is DelegatingHandler delegatingHandler)
+ handler = delegatingHandler.InnerHandler!;
+
+ Assert.False(Assert.IsType<HttpClientHandler>(handler).AllowAutoRedirect);
+ }
+
+ [Fact(Timeout = TestTimeout)]
+ [Trait("Fast", "Fast")]
+ public async Task LanguagePackUpdateService_ParsesBcp47()
+ {
+ var handler = new TestHttpMessageHandler();
+ handler.Register(ManifestUrl, () => TestHttpMessageHandler.JsonResponse(
+ """
+ {
+ "Languages": [
+ {
+ "Name": "French",
+ "Bcp47": "fr-FR",
+ "File": "translations/french.json",
+ "Sha": "sha-fr"
+ }
+ ]
+ }
+ """));
+ var service = CreateLanguageService(handler);
+ var languages = await service.GetManifestLanguages();
+ var french = Assert.Single(languages);
+ Assert.Equal("fr-FR", french.Bcp47);
+ }
+
+ [Fact(Timeout = TestTimeout)]
+ [Trait("Fast", "Fast")]
+ public async Task LanguagePackUpdateService_FollowsTrustedRedirect()
+ {
+ const string body = "{\"Hello\":\"Bonjour\"}";
+ var expectedSha = Convert.ToHexString(System.Security.Cryptography.SHA256.HashData(Encoding.UTF8.GetBytes(body)));
+ const string redirectManifestUrl = "https://raw.githubusercontent.com/btcpayserver/btcpayserver-translations/main/manifest.json";
+ const string redirectBase = "https://raw.githubusercontent.com/btcpayserver/btcpayserver-translations/main/";
+ var handler = new TestHttpMessageHandler();
+ handler.Register(ManifestUrl, () => TestHttpMessageHandler.JsonResponse(
+ $$"""{ "Languages": [], "Redirect": "{{redirectManifestUrl}}" }"""));
+ handler.Register(redirectManifestUrl, () => TestHttpMessageHandler.JsonResponse(
+ $$"""
+ {
+ "Languages": [
+ {
+ "Name": "French",
+ "Code": "fr",
+ "Bcp47": "fr-FR",
+ "File": "translations/french.json",
+ "Sha": "{{expectedSha}}"
+ }
+ ]
+ }
+ """));
+ handler.Register(redirectBase + "translations/french.json", () => TestHttpMessageHandler.JsonResponse(body));
+
+ var service = CreateLanguageService(handler);
+ var languages = await service.GetManifestLanguages();
+ var french = Assert.Single(languages);
+ Assert.Equal("fr-FR", french.Bcp47);
+ var (translationsJson, version, rtl) = await service.FetchLanguagePackFromRepository("French");
+ Assert.Equal(expectedSha, version, ignoreCase: true);
+ Assert.False(rtl);
+ Assert.Equal("Bonjour", JObject.Parse(translationsJson)["Hello"]?.ToString());
+ }
+
+ [Fact(Timeout = TestTimeout)]
+ [Trait("Fast", "Fast")]
+ public async Task LanguagePackUpdateService_ThrowsOnRedirectOutsideTrustedOrg()
+ {
+ var handler = new TestHttpMessageHandler();
+ handler.Register(ManifestUrl, () => TestHttpMessageHandler.JsonResponse(
+ """
+ {
+ "Languages": [],
+ "Redirect": "https://raw.githubusercontent.com/evil-org/btcpayserver-translator/main/manifest.json"
+ }
+ """));
+ var service = CreateLanguageService(handler);
+ await Assert.ThrowsAsync<InvalidOperationException>(() => service.GetManifestLanguages());
+ }
+
+ [Theory(Timeout = TestTimeout)]
+ [Trait("Fast", "Fast")]
+ [InlineData("https://raw.githubusercontent.com/btcpayserver/../evil-org/repo/main/manifest.json")]
+ [InlineData("https://raw.githubusercontent.com/btcpayserver/%2e%2e/evil-org/repo/main/manifest.json")]
+ [InlineData("http://raw.githubusercontent.com/btcpayserver/translations/main/manifest.json")]
+ [InlineData("https://raw.githubusercontent.com.evil.example/btcpayserver/translations/main/manifest.json")]
+ public async Task LanguagePackUpdateService_RejectsRedirectThatEscapesTrustedOrg(string redirect)
+ {
+ var handler = new TestHttpMessageHandler();
+ var fetchedElsewhere = false;
+ handler.Register(ManifestUrl, () => TestHttpMessageHandler.JsonResponse(
+ $$"""{ "Languages": [], "Redirect": "{{redirect}}" }"""));
+ // Where the dot-segment variants would resolve to if they were followed.
+ handler.Register("https://raw.githubusercontent.com/evil-org/repo/main/manifest.json", () =>
+ {
+ fetchedElsewhere = true;
+ return TestHttpMessageHandler.JsonResponse("""{ "Languages": [] }""");
+ });
+ var service = CreateLanguageService(handler);
+ await Assert.ThrowsAsync<InvalidOperationException>(() => service.GetManifestLanguages());
+ Assert.False(fetchedElsewhere);
+ }
+
[Fact(Timeout = TestTimeout)]
[Trait("Integration", "Integration")]
public async Task LanguagePackUpdateService_ParsesRtlFlag()
@@ -118,7 +277,7 @@ public async Task LanguagePackUpdateService_FetchReturnsRtlFromManifest()
}
[Fact(Timeout = TestTimeout)]
- [Trait("Unit", "Unit")]
+ [Trait("Fast", "Fast")]
public async Task LanguagePackUpdateService_PropagatesExceptionOnMalformedManifest()
{
var handler = new TestHttpMessageHandler();
@@ -130,7 +289,7 @@ public async Task LanguagePackUpdateService_PropagatesExceptionOnMalformedManife
}
[Fact(Timeout = TestTimeout)]
- [Trait("Unit", "Unit")]
+ [Trait("Fast", "Fast")]
public async Task LanguagePackUpdateService_ThrowsOnMissingLanguagesKey()
{
var handler = new TestHttpMessageHandler();
@@ -142,7 +301,7 @@ public async Task LanguagePackUpdateService_ThrowsOnMissingLanguagesKey()
}
[Fact(Timeout = TestTimeout)]
- [Trait("Unit", "Unit")]
+ [Trait("Fast", "Fast")]
public async Task LanguagePackUpdateService_ThrowsArgumentExceptionForUnknownLanguage()
{
var handler = new TestHttpMessageHandler();
@@ -155,7 +314,7 @@ await Assert.ThrowsAsync<ArgumentException>(
}
[Fact(Timeout = TestTimeout)]
- [Trait("Unit", "Unit")]
+ [Trait("Fast", "Fast")]
public async Task LanguagePackUpdateService_ThrowsWhenManifestFails()
{
var handler = new TestHttpMessageHandler();
@@ -169,7 +328,7 @@ public async Task LanguagePackUpdateService_ThrowsWhenManifestFails()
}
[Fact(Timeout = TestTimeout)]
- [Trait("Unit", "Unit")]
+ [Trait("Fast", "Fast")]
public async Task LanguagePackUpdateService_FetchesLanguagePackFromManifest()
{
const string body = "{\"Hello\":\"Bonjour\"}";
@@ -201,7 +360,7 @@ public async Task LanguagePackUpdateService_FetchesLanguagePackFromManifest()
}
[Fact(Timeout = TestTimeout)]
- [Trait("Unit", "Unit")]
+ [Trait("Fast", "Fast")]
public async Task LanguagePackUpdateService_RejectsLanguagePackOnShaMismatch()
{
const string body = "{\"Hello\":\"Bonjour\"}";
@@ -230,7 +389,7 @@ public async Task LanguagePackUpdateService_RejectsLanguagePackOnShaMismatch()
}
[Fact(Timeout = TestTimeout)]
- [Trait("Unit", "Unit")]
+ [Trait("Fast", "Fast")]
public async Task LanguagePackUpdateService_UsesUpdateCacheUntilInvalidated()
{
var handler = new TestHttpMessageHandler();
### BTCPayServer/Plugins/Translations/LanguagePackUpdateService.cs
@@ -1,6 +1,7 @@
#nullable enable
using System;
using System.Globalization;
+using System.IO;
using System.Linq;
using System.Net.Http;
using System.Security.Cryptography;
@@ -22,7 +23,8 @@ public record LanguageManifestEntry(
DateTimeOffset? Updated,
string File,
string Sha,
- bool Rtl)
+ bool Rtl,
+ string? Bcp47)
{
internal static LanguageManifestEntry FromDto(ManifestLanguageDto dto)
{
@@ -39,7 +41,8 @@ internal static LanguageManifestEntry FromDto(ManifestLanguageDto dto)
updated,
dto.File ?? string.Empty,
dto.Sha ?? string.Empty,
- dto.Rtl ?? false);
+ dto.Rtl ?? false,
+ dto.Bcp47);
}
private static (string? Handle, string? Url) SplitMaintainer(string? raw)
@@ -57,43 +60,66 @@ internal record ManifestLanguageDto(
string? Updated,
string? File,
string? Sha,
- bool? Rtl);
+ bool? Rtl,
+ string? Bcp47);
- internal record ManifestRootDto(ManifestLanguageDto[]? Languages);
+ internal record ManifestRootDto(ManifestLanguageDto[]? Languages, string? Redirect);
+ private sealed record ManifestSnapshot(LanguageManifestEntry[] Entries, Uri ManifestUri);
private const string ManifestCacheKey = "translations.manifest";
- private const string ManifestUrl = "https://raw.githubusercontent.com/btcpayserver/btcpayserver-translator/main/manifest.json";
- private const string RawBaseUrl = "https://raw.githubusercontent.com/btcpayserver/btcpayserver-translator/main/";
+ public const string HttpClientName = "BTCPayServer.Plugins.Translations";
private static readonly TimeSpan CacheLifetime = TimeSpan.FromHours(1);
- private async Task<LanguageManifestEntry[]> GetEntries()
+ private async Task<ManifestSnapshot> GetSnapshot()
{
- if (memoryCache.TryGetValue(ManifestCacheKey, out LanguageManifestEntry[]? cached) && cached is not null)
+ if (memoryCache.TryGetValue(ManifestCacheKey, out ManifestSnapshot? cached) && cached is not null)
return cached;
- using var httpClient = httpClientFactory.CreateClient();
- httpClient.Timeout = TimeSpan.FromSeconds(30);
- var json = await httpClient.GetStringAsync(ManifestUrl);
+ var manifestUri = new Uri("https://raw.githubusercontent.com/btcpayserver/btcpayserver-translator/main/manifest.json");
+ var root = ParseManifest(await GetTrusted(manifestUri));
+ if (!string.IsNullOrEmpty(root.Redirect))
+ {
+ if (!Uri.TryCreate(root.Redirect, UriKind.Absolute, out manifestUri))
+ throw new InvalidOperationException($"Manifest redirect '{root.Redirect}' is not an absolute URI.");
+
+ root = ParseManifest(await GetTrusted(manifestUri));
+ }
+ var entries = root.Languages!.Select(LanguageManifestEntry.FromDto)
+ .Where(e => !string.IsNullOrEmpty(e.Name)).ToArray();
- var root = JsonConvert.DeserializeObject<ManifestRootDto>(json);
- if (root?.Languages is null)
- throw new InvalidOperationException("Manifest is missing the 'Languages' array.");
+ var snapshot = new ManifestSnapshot(entries, manifestUri);
+ memoryCache.Set(ManifestCacheKey, snapshot, CacheLifetime);
+ return snapshot;
+ }
- var entries = root.Languages
- .Select(LanguageManifestEntry.FromDto)
- .Where(e => !string.IsNullOrEmpty(e.Name))
- .ToArray();
+ private static ManifestRootDto ParseManifest(byte[] body)
+ {
+ using var stream = new MemoryStream(body);
+ using var reader = new StreamReader(stream);
+ return JsonConvert.DeserializeObject<ManifestRootDto>(reader.ReadToEnd()) is { Languages: not null } root
+ ? root : throw new InvalidOperationException("Manifest is missing the 'Languages' array.");
+ }
- memoryCache.Set(ManifestCacheKey, entries, CacheLifetime);
- return entries;
+ private async Task<byte[]> GetTrusted(Uri uri)
+ {
+ if (uri.Scheme != Uri.UriSchemeHttps
+ || !string.Equals(uri.Host, "raw.githubusercontent.com", StringComparison.OrdinalIgnoreCase)
+ || !uri.AbsolutePath.StartsWith("/btcpayserver/", StringComparison.OrdinalIgnoreCase))
+ throw new InvalidOperationException($"'{uri}' is outside the trusted repository.");
+
+ using var client = httpClientFactory.CreateClient(HttpClientName);
+ client.Timeout = TimeSpan.FromSeconds(30);
+ using var response = await client.GetAsync(uri);
+ response.EnsureSuccessStatusCode();
+ return await response.Content.ReadAsByteArrayAsync();
}
- public Task<LanguageManifestEntry[]> GetManifestLanguages() => GetEntries();
+ public async Task<LanguageManifestEntry[]> GetManifestLanguages() => (await GetSnapshot()).Entries;
public async Task<(string translationsJson, string version, bool rtl)> FetchLanguagePackFromRepository(string language)
{
- var entries = await GetEntries();
- var entry = entries.FirstOrDefault(e =>
+ var snapshot = await GetSnapshot();
+ var entry = snapshot.Entries.FirstOrDefault(e =>
string.Equals(e.Name, language, StringComparison.OrdinalIgnoreCase))
?? throw new ArgumentException($"Language '{language}' was not found in the manifest.", nameof(language));
@@ -102,10 +128,7 @@ private async Task<LanguageManifestEntry[]> GetEntries()
if (string.IsNullOrEmpty(entry.Sha))
throw new InvalidOperationException("Manifest entry is missing the 'Sha' field.");
- using var httpClient = httpClientFactory.CreateClient();
- httpClient.Timeout = TimeSpan.FromSeconds(30);
- var translationsBytes = await httpClient.GetByteArrayAsync(RawBaseUrl + entry.File);
-
+ var translationsBytes = await GetTrusted(new Uri(snapshot.ManifestUri, entry.File));
var actualSha = Convert.ToHexString(SHA256.HashData(translationsBytes));
if (!string.Equals(actualSha, entry.Sha, StringComparison.OrdinalIgnoreCase))
throw new InvalidOperationException(
@@ -135,9 +158,8 @@ private async Task<bool> CheckForLanguagePackUpdate(string language, JObject met
{
try
{
- var entries = await GetEntries();
- var entry = entries.FirstOrDefault(e =>
- string.Equals(e.Name, language, StringComparison.OrdinalIgnoreCase));
+ var snapshot = await GetSnapshot();
+ var entry = snapshot.Entries.FirstOrDefault(e => string.Equals(e.Name, language, StringComparison.OrdinalIgnoreCase));
if (entry is null || string.IsNullOrEmpty(entry.Sha))
return false;
### BTCPayServer/Plugins/Translations/TranslationsPlugin.cs
@@ -1,3 +1,4 @@
+using System.Net.Http;
using BTCPayServer.Abstractions.Extensions;
using BTCPayServer.Abstractions.Models;
using BTCPayServer.Client;
@@ -26,6 +27,8 @@ public override void Execute(IServiceCollection services)
services.TryAddSingleton<LocalizerService>();
services.TryAddSingleton<LanguagePackUpdateService>();
services.AddStartupTask<LoadTranslationsStartupTask>();
+ services.AddHttpClient(LanguagePackUpdateService.HttpClientName)
+ .ConfigurePrimaryHttpMessageHandler(() => new HttpClientHandler { AllowAutoRedirect = false });
services.TryAddSingleton<IStringLocalizer>(o => o.GetRequiredService<IStringLocalizerFactory>().Create("", ""));
services.AddStaticSearch(new ActionResultItemViewModel()Why this scored 59/100
Community notes
Notes can correct, qualify, or add evidence to the AI analysis. Every note shown here has been validated by a human moderator.
The AI analysis stands alone for now. Submit a note if you can add evidence or important context.