Support translation repository redirects and BCP 47 identifiers
What changed, and why it matters
This commit hardens how BTCPay Server downloads translation files from the internet. It adds checks so the server only fetches language packs and manifest redirects from the trusted btcpayserver GitHub organization, turns off automatic HTTP redirects, and handles UTF-8 text files that start with a special byte marker. The changes appear to be defensive security improvements rather than a fix for a known active attack.
Treat as a security-hardening change and include in the next release. Review whether the trusted-org check (raw.githubusercontent.com/btcpayserver/*) is sufficiently strict for your threat model, and confirm that any custom translation repositories are hosted under that exact path. No immediate emergency response is indicated by the diff alone.
Security signals we found
Server-side request forgery (SSRF) hardening: URI scheme, host, and path prefix are validated before outbound fetch
Open-redirect / HTTP redirect abuse mitigation: AllowAutoRedirect set to false on the translation HttpClient
Path traversal mitigation: pack file paths resolved as relative URIs and validated against trusted org prefix
Manifest redirect delegation added with same trust-boundary validation
BOM-aware manifest parsing added to avoid JSON parse failures on UTF-8 BOM
New test cases explicitly model attacker-controlled redirect and file values
Evidence from the diff
The patch modifies the translation update service to: (1) validate that manifest URIs and language pack file URIs stay within https://raw.githubusercontent.com/btcpayserver/*; (2) disable AllowAutoRedirect on the named HttpClient so an attacker cannot use an open redirect or 302 to pull content from an untrusted host; (3) resolve pack URIs relative to the manifest URI instead of concatenating against a fixed base string; (4) parse manifests with a BOM-aware StreamReader; and (5) add a Redirect field so manifests can delegate to another repository under the same trusted org. Unit tests cover path traversal, scheme/host escaping, and redirect validation.
Changed components
BTCPayServer.Plugins.Translations.LanguagePackUpdateServiceBTCPayServer.Plugins.Translations.TranslationsPluginBTCPayServer.Tests.LanguageServiceTestsInspect 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 60/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.