Merge pull request #224 from btcpayserver/btcmaps-v1-directory-only

PluginBuilder.Tests/BtcMapsServiceTests.cs

@@ -0,0 +1,233 @@
+using System.Net.Http;
+using Microsoft.Extensions.Configuration;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Logging.Abstractions;
+using PluginBuilder.APIModels;
+using PluginBuilder.Services;
+using Xunit;
+
+namespace PluginBuilder.Tests;
+
+public class BtcMapsServiceTests
+{
+    private sealed class StubHttpClientFactory : IHttpClientFactory
+    {
+        public HttpClient CreateClient(string name) => new HttpClient();
+    }
+
+    private static BtcMapsService MakeService() =>
+        new BtcMapsService(
+            configuration: new ConfigurationBuilder().Build(),
+            httpClientFactory: new StubHttpClientFactory(),
+            logger: NullLogger<BtcMapsService>.Instance);
+
+    private static BtcMapsSubmitRequest MakeValid() => new()
+    {
+        Name = "Good Shop",
+        Url = "https://goodshop.example",
+        Description = "A very good shop.",
+        Type = "merchants"
+    };
+
+    [Fact]
+    public void Validate_AcceptsMinimalDirectoryRequest()
+    {
+        Assert.Empty(MakeService().Validate(MakeValid()));
+    }
+
+    [Fact]
+    public void Validate_RejectsMissingName()
+    {
+        var req = MakeValid();
+        req.Name = null;
+        Assert.Contains(MakeService().Validate(req), e => e.Path == nameof(BtcMapsSubmitRequest.Name));
+    }
+
+    [Fact]
+    public void Validate_RejectsOverlongName()
+    {
+        var req = MakeValid();
+        req.Name = new string('x', 201);
+        Assert.Contains(MakeService().Validate(req), e => e.Path == nameof(BtcMapsSubmitRequest.Name));
+    }
+
+    [Fact]
+    public void Validate_RejectsNonHttpsUrl()
+    {
+        var req = MakeValid();
+        req.Url = "http://plain.example";
+        Assert.Contains(MakeService().Validate(req), e => e.Path == nameof(BtcMapsSubmitRequest.Url));
+    }
+
+    [Fact]
+    public void Validate_RejectsMissingDescription()
+    {
+        var req = MakeValid();
+        req.Description = null;
+        Assert.Contains(MakeService().Validate(req), e => e.Path == nameof(BtcMapsSubmitRequest.Description));
+    }
+
+    [Fact]
+    public void Validate_RejectsOverlongDescription()
+    {
+        var req = MakeValid();
+        req.Description = new string('x', 1001);
+        Assert.Contains(MakeService().Validate(req), e => e.Path == nameof(BtcMapsSubmitRequest.Description));
+    }
+
+    [Fact]
+    public void Validate_RejectsMissingType()
+    {
+        var req = MakeValid();
+        req.Type = null;
+        Assert.Contains(MakeService().Validate(req), e => e.Path == nameof(BtcMapsSubmitRequest.Type));
+    }
+
+    [Fact]
+    public void Validate_RejectsInvalidType()
+    {
+        var req = MakeValid();
+        req.Type = "shops";
+        Assert.Contains(MakeService().Validate(req), e => e.Path == nameof(BtcMapsSubmitRequest.Type));
+    }
+
+    [Fact]
+    public void Validate_RejectsInvalidMerchantSubType()
+    {
+        var req = MakeValid();
+        req.SubType = "not-a-real-subtype";
+        Assert.Contains(MakeService().Validate(req), e => e.Path == nameof(BtcMapsSubmitRequest.SubType));
+    }
+
+    [Fact]
+    public void Validate_AcceptsValidMerchantSubType()
+    {
+        var req = MakeValid();
+        req.SubType = "books";
+        Assert.Empty(MakeService().Validate(req));
+    }
+
+    [Fact]
+    public void Validate_AcceptsIsoAlpha2Country()
+    {
+        var req = MakeValid();
+        req.Country = "DE";
+        Assert.Empty(MakeService().Validate(req));
+    }
+
+    [Fact]
+    public void Validate_AcceptsGlobalCountry()
+    {
+        var req = MakeValid();
+        req.Country = "GLOBAL";
+        Assert.Empty(MakeService().Validate(req));
+    }
+
+    [Fact]
+    public void Validate_RejectsLowerCaseCountry()
+    {
+        var req = MakeValid();
+        req.Country = "de";
+        Assert.Contains(MakeService().Validate(req), e => e.Path == nameof(BtcMapsSubmitRequest.Country));
+    }
+
+    [Fact]
+    public void Validate_RejectsThreeLetterCountry()
+    {
+        var req = MakeValid();
+        req.Country = "DEU";
+        Assert.Contains(MakeService().Validate(req), e => e.Path == nameof(BtcMapsSubmitRequest.Country));
+    }
+
+    [Fact]
+    public void Validate_RejectsNonAssignedTwoLetterCountry()
+    {
+        // ZZ is reserved / not assigned in ISO 3166-1, so the validator must
+        // reject it even though it passes the length + casing check.
+        var req = MakeValid();
+        req.Country = "ZZ";
+        Assert.Contains(MakeService().Validate(req), e => e.Path == nameof(BtcMapsSubmitRequest.Country));
+    }
+
+    [Fact]
+    public void Validate_AcceptsOnionHttpsUrl()
+    {
+        var req = MakeValid();
+        req.OnionUrl = "https://abc123.onion";
+        Assert.Empty(MakeService().Validate(req));
+    }
+
+    [Fact]
+    public void Validate_AcceptsOnionHttpUrl()
+    {
+        // Onion v3 addresses are commonly served over http (Tor provides the transport
+        // encryption); the validator allows http on a .onion host explicitly.
+        var req = MakeValid();
+        req.OnionUrl = "http://abc123.onion";
+        Assert.Empty(MakeService().Validate(req));
+    }
+
+    [Fact]
+    public void Validate_RejectsNonOnionOnionUrl()
+    {
+        var req = MakeValid();
+        req.OnionUrl = "https://example.com";
+        Assert.Contains(MakeService().Validate(req), e => e.Path == nameof(BtcMapsSubmitRequest.OnionUrl));
+    }
+
+    [Fact]
+    public void NormalizeUrl_LowercasesSchemeAndHostOnly()
+    {
+        // Scheme + host are case-insensitive (DNS + RFC); path + query are not, so
+        // they must be preserved verbatim. Trailing slash is stripped only when the
+        // path is non-root.
+        Assert.Equal("https://example.com/", BtcMapsService.NormalizeUrl("HTTPS://Example.com/"));
+        Assert.Equal("https://example.com/", BtcMapsService.NormalizeUrl("  https://example.com  "));
+    }
+
+    [Fact]
+    public void NormalizeUrl_PreservesPathCase()
+    {
+        Assert.Equal("https://example.com/Foo/Bar",
+            BtcMapsService.NormalizeUrl("HTTPS://Example.com/Foo/Bar/"));
+    }
+
+    [Fact]
+    public void NormalizeUrl_PreservesQueryCase()
+    {
+        Assert.Equal("https://example.com/path?ID=ABC",
+            BtcMapsService.NormalizeUrl("https://EXAMPLE.com/path?ID=ABC"));
+    }
+
+    [Fact]
+    public void BuildBranchName_DeterministicForSameUrl()
+    {
+        var a = BtcMapsService.BuildBranchName("Good Shop", "https://example.com/foo");
+        var b = BtcMapsService.BuildBranchName("Good Shop", "https://example.com/foo");
+        Assert.Equal(a, b);
+        Assert.StartsWith("btcmaps/good-shop-", a);
+    }
+
+    [Fact]
+    public void BuildBranchName_DiffersForDifferentUrls()
+    {
+        var a = BtcMapsService.BuildBranchName("Good Shop", "https://example.com/foo");
+        var b = BtcMapsService.BuildBranchName("Good Shop", "https://example.com/bar");
+        Assert.NotEqual(a, b);
+    }
+
+    [Fact]
+    public void Slugify_ProducesUrlSafeSegment()
+    {
+        Assert.Equal("good-shop", BtcMapsService.Slugify("Good Shop!"));
+        Assert.Equal("merchant", BtcMapsService.Slugify("!!!"));
+    }
+
+    [Fact]
+    public void Slugify_CapsLengthAtFortyChars()
+    {
+        var input = new string('a', 80);
+        var slug = BtcMapsService.Slugify(input);
+        Assert.True(slug.Length <= 40);
+    }
+}

PluginBuilder/APIModels/BtcMapsSubmitRequest.cs

@@ -0,0 +1,15 @@
+namespace PluginBuilder.APIModels;
+
+public sealed class BtcMapsSubmitRequest
+{
+    public string? Name { get; set; }
+    public string? Url { get; set; }
+    public string? Description { get; set; }
+
+    public string? Type { get; set; }
+    public string? SubType { get; set; }
+    public string? Country { get; set; }
+    public string? Twitter { get; set; }
+    public string? Github { get; set; }
+    public string? OnionUrl { get; set; }
+}

PluginBuilder/APIModels/BtcMapsSubmitResponse.cs

@@ -0,0 +1,14 @@
+namespace PluginBuilder.APIModels;
+
+public sealed class BtcMapsSubmitResponse
+{
+    public BtcMapsDirectoryResult? Directory { get; set; }
+}
+
+public sealed class BtcMapsDirectoryResult
+{
+    public string? PrUrl { get; set; }
+    public int? PrNumber { get; set; }
+    public string? Branch { get; set; }
+    public string? Skipped { get; set; }
+}

PluginBuilder/Controllers/BtcMapsController.cs

@@ -0,0 +1,86 @@
+using Microsoft.AspNetCore.Authorization;
+using Microsoft.AspNetCore.Mvc;
+using Microsoft.AspNetCore.RateLimiting;
+using PluginBuilder.APIModels;
+using PluginBuilder.Services;
+
+namespace PluginBuilder.Controllers;
+
+[ApiController]
+[AllowAnonymous]
+[Route("~/apis/btcmaps/v1")]
+public sealed class BtcMapsController(
+    BtcMapsService btcMapsService,
+    ILogger<BtcMapsController> logger)
+    : ControllerBase
+{
+    [HttpGet("ping")]
+    public IActionResult Ping() => Ok(new { ok = true, service = "btcmaps", version = "v1" });
+
+    [HttpPost("submit")]
+    [EnableRateLimiting(Policies.BtcMapsSubmitRateLimit)]
+    public async Task<IActionResult> Submit(
+        [FromBody] BtcMapsSubmitRequest? request,
+        CancellationToken cancellationToken)
+    {
+        if (request is null)
+            return BadRequest(new { errors = new[] { new ValidationError("body", "Request body is required.") } });
+
+        var errors = btcMapsService.Validate(request);
+        if (errors.Count > 0)
+            return BadRequest(new { errors });
+
+        var correlationId = Guid.NewGuid().ToString("N");
+        BtcMapsDirectoryResult directory;
+
+        try
+        {
+            directory = await btcMapsService.SubmitToDirectoryAsync(request, cancellationToken);
+        }
+        catch (BtcMapsService.DirectoryTokenMissingException ex)
+        {
+            // Missing token is a server-side deployment / configuration outage,
+            // not a normal "skipped" outcome. Surface 503 so clients (and ops)
+            // can distinguish it from an accepted submission.
+            logger.LogError(ex, "BTCMaps directory submission rejected: token not configured (correlationId={CorrelationId})", correlationId);
+            return StatusCode(StatusCodes.Status503ServiceUnavailable, new
+            {
+                error = "directory-not-configured",
+                correlationId
+            });
+        }
+        catch (OperationCanceledException ex) when (cancellationToken.IsCancellationRequested)
+        {
+            // Caller cancelled (client disconnect, request abort). Rethrow so
+            // the pipeline drops the connection without producing a response
+            // body the client will never read.
+            logger.LogInformation(ex, "BTCMaps directory submission cancelled by caller (correlationId={CorrelationId})", correlationId);
+            throw;
+        }
+        catch (OperationCanceledException ex)
+        {
+            // OCE without caller cancellation = HttpClient.Timeout surfacing as
+            // TaskCanceledException. Treat as an upstream timeout, distinct
+            // from a generic 502 so ops + the plugin client can tell them apart.
+            logger.LogError(ex, "BTCMaps directory submission timed out upstream (correlationId={CorrelationId}) for {Name} ({Url})",
+                correlationId, request.Name, request.Url);
+            return StatusCode(StatusCodes.Status504GatewayTimeout, new
+            {
+                error = "directory-upstream-timeout",
+                correlationId
+            });
+        }
+        catch (Exception ex)
+        {
+            logger.LogError(ex, "BTCMaps directory submission failed (correlationId={CorrelationId}) for {Name} ({Url})",
+                correlationId, request.Name, request.Url);
+            return StatusCode(StatusCodes.Status502BadGateway, new
+            {
+                error = "directory-upstream-failed",
+                correlationId
+            });
+        }
+
+        return Ok(new BtcMapsSubmitResponse { Directory = directory });
+    }
+}

PluginBuilder/DataModels/HttpClientNames.cs

@@ -4,4 +4,5 @@ public static class HttpClientNames
 {
     public const string GitHub = nameof(GitHub);
     public const string GitLab = nameof(GitLab);
+    public const string BtcMapsDirectory = nameof(BtcMapsDirectory);
 }

PluginBuilder/Policies.cs

@@ -4,4 +4,5 @@ public class Policies
 {
     public const string OwnPlugin = "OwnPlugin";
     public const string PublicApiRateLimit = "PublicApiRateLimit";
+    public const string BtcMapsSubmitRateLimit = "BtcMapsSubmitRateLimit";
 }

PluginBuilder/Program.cs

@@ -211,6 +211,18 @@ public class Program
                 client.DefaultRequestHeaders.Authorization =
                     new AuthenticationHeaderValue("Bearer", token);
         });
+        services.AddHttpClient(HttpClientNames.BtcMapsDirectory, client =>
+        {
+            // Per-call timeout caps a single GitHub round-trip at 15s. The directory
+            // submission makes ~5-7 GitHub calls sequentially; with the default 100s
+            // timeout a hung remote could pin the request for ~10min and tie up a
+            // rate-limit slot. 15s per call keeps the worst case bounded.
+            client.BaseAddress = new Uri("https://api.github.com/");
+            client.DefaultRequestHeaders.Add("User-Agent", "PluginBuilder-BtcMaps/1.0");
+            client.DefaultRequestHeaders.Add("X-GitHub-Api-Version", "2022-11-28");
+            client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/vnd.github+json"));
+            client.Timeout = TimeSpan.FromSeconds(15);
+        });
         services.AddHttpClient(HttpClientNames.GitLab, client =>
         {
             client.BaseAddress = new Uri("https://gitlab.com/api/v4/");
@@ -241,6 +253,7 @@ public class Program
         });
         services.AddScoped<PluginOwnershipService>();
         services.AddScoped<VersionLifecycleService>();
+        services.AddSingleton<BtcMapsService>();
 
         services.AddRateLimiter(options =>
         {
@@ -266,6 +279,20 @@ public class Program
                     QueueLimit = 0
                 });
             });
+            options.AddPolicy(Policies.BtcMapsSubmitRateLimit, httpContext =>
+            {
+                // Per-source-IP fixed window: 5 submissions per 24h. Caps automation
+                // abuse of /apis/btcmaps/v1/submit without throttling honest single
+                // submissions from a merchant.
+                var clientIp = httpContext.Connection.RemoteIpAddress?.ToString() ?? "unknown";
+                return RateLimitPartition.GetFixedWindowLimiter(clientIp, _ => new FixedWindowRateLimiterOptions
+                {
+                    PermitLimit = 5,
+                    Window = TimeSpan.FromHours(24),
+                    QueueProcessingOrder = QueueProcessingOrder.OldestFirst,
+                    QueueLimit = 0
+                });
+            });
         });
 
         services.AddOutputCache(options =>

PluginBuilder/Services/BtcMapsService.cs

@@ -0,0 +1,502 @@
+using System.Globalization;
+using System.Net.Http.Headers;
+using System.Security.Cryptography;
+using System.Text;
+using System.Text.Encodings.Web;
+using System.Text.Json;
+using Microsoft.Extensions.Configuration;
+using PluginBuilder.APIModels;
+using PluginBuilder.DataModels;
+
+namespace PluginBuilder.Services;
+
+public sealed class BtcMapsService
+{
+    private const string DefaultDirectoryRepo = "btcpayserver/directory.btcpayserver.org";
+    private const string DefaultDirectoryMerchantsPath = "src/data/merchants.json";
+
+    private static readonly HashSet<string> ValidTypes = new(StringComparer.OrdinalIgnoreCase)
+    {
+        "merchants", "apps", "hosted-btcpay", "non-profits"
+    };
+
+    private static readonly HashSet<string> ValidMerchantSubTypes = new(StringComparer.OrdinalIgnoreCase)
+    {
+        "3d-printing", "adult", "appliances-furniture", "art", "books",
+        "cryptocurrency-paraphernalia", "domains-hosting-vpns", "education",
+        "electronics", "fashion", "food", "gambling", "gift-cards",
+        "health-household", "holiday-travel", "jewelry", "payment-services",
+        "pets", "services", "software-video-games", "sports", "tools"
+    };
+
+    // ISO 3166-1 alpha-2 codes derived from CultureInfo at startup. Cached because
+    // CultureInfo.GetCultures + RegionInfo enumeration is non-trivial and the set
+    // is stable for the process lifetime.
+    private static readonly HashSet<string> Iso3166Alpha2 = BuildIsoAlpha2Set();
+
+    private static HashSet<string> BuildIsoAlpha2Set()
+    {
+        var set = new HashSet<string>(StringComparer.Ordinal);
+        foreach (var culture in CultureInfo.GetCultures(CultureTypes.SpecificCultures))
+        {
+            try
+            {
+                var region = new RegionInfo(culture.Name);
+                if (region.TwoLetterISORegionName.Length == 2 &&
+                    region.TwoLetterISORegionName.All(c => c is >= 'A' and <= 'Z'))
+                {
+                    set.Add(region.TwoLetterISORegionName);
+                }
+            }
+            catch (ArgumentException)
+            {
+                // Some neutral cultures throw; skip.
+            }
+        }
+        return set;
+    }
+
+    private readonly IConfiguration _configuration;
+    private readonly IHttpClientFactory _httpClientFactory;
+    private readonly ILogger<BtcMapsService> _logger;
+
+    public BtcMapsService(
+        IConfiguration configuration,
+        IHttpClientFactory httpClientFactory,
+        ILogger<BtcMapsService> logger)
+    {
+        _configuration = configuration;
+        _httpClientFactory = httpClientFactory;
+        _logger = logger;
+    }
+
+    public sealed class DirectoryTokenMissingException : Exception
+    {
+        public DirectoryTokenMissingException() : base("BTCMAPS:DirectoryGithubToken is not configured.") { }
+    }
+
+    public IReadOnlyList<ValidationError> Validate(BtcMapsSubmitRequest request)
+    {
+        var errors = new List<ValidationError>();
+
+        var name = (request.Name ?? string.Empty).Trim();
+        if (string.IsNullOrEmpty(name) || name.Length > 200)
+            errors.Add(new ValidationError(nameof(request.Name), "Required, 1-200 characters."));
+
+        var url = (request.Url ?? string.Empty).Trim();
+        if (string.IsNullOrEmpty(url))
+            errors.Add(new ValidationError(nameof(request.Url), "Required."));
+        else if (!Uri.TryCreate(url, UriKind.Absolute, out var parsed) || parsed.Scheme != Uri.UriSchemeHttps)
+            errors.Add(new ValidationError(nameof(request.Url), "Must be a valid https:// URL."));
+
+        var description = (request.Description ?? string.Empty).Trim();
+        if (string.IsNullOrEmpty(description) || description.Length > 1000)
+            errors.Add(new ValidationError(nameof(request.Description), "Required, 1-1000 characters."));
+
+        var type = (request.Type ?? string.Empty).Trim();
+        if (string.IsNullOrEmpty(type) || !ValidTypes.Contains(type))
+            errors.Add(new ValidationError(nameof(request.Type),
+                $"Required. One of: {string.Join(", ", ValidTypes)}."));
+
+        if (!string.IsNullOrWhiteSpace(request.SubType))
+        {
+            var subType = request.SubType.Trim();
+            if (string.Equals(type, "merchants", StringComparison.OrdinalIgnoreCase) &&
+                !ValidMerchantSubTypes.Contains(subType))
+            {
+                errors.Add(new ValidationError(nameof(request.SubType),
+                    "Invalid merchant subtype."));
+            }
+        }
+
+        if (!string.IsNullOrWhiteSpace(request.Country))
+        {
+            var country = request.Country.Trim();
+            // GLOBAL is the directory's pseudonym for online-only / multi-region merchants.
+            // Everything else must be an actual ISO 3166-1 alpha-2 code.
+            if (country != "GLOBAL" && !Iso3166Alpha2.Contains(country))
+                errors.Add(new ValidationError(nameof(request.Country),
+                    "Must be ISO 3166-1 alpha-2 or GLOBAL."));
+        }
+
+        if (!string.IsNullOrWhiteSpace(request.OnionUrl))
+        {
+            if (!Uri.TryCreate(request.OnionUrl.Trim(), UriKind.Absolute, out var onionUri) ||
+                (onionUri.Scheme != Uri.UriSchemeHttp && onionUri.Scheme != Uri.UriSchemeHttps) ||
+                !onionUri.Host.EndsWith(".onion", StringComparison.OrdinalIgnoreCase))
+            {
+                errors.Add(new ValidationError(nameof(request.OnionUrl),
+                    "Must be an http(s) .onion URL."));
+            }
+        }
+
+        return errors;
+    }
+
+    public async Task<BtcMapsDirectoryResult> SubmitToDirectoryAsync(
+        BtcMapsSubmitRequest request,
+        CancellationToken cancellationToken = default)
+    {
+        var token = _configuration["BTCMAPS:DirectoryGithubToken"];
+        if (string.IsNullOrWhiteSpace(token))
+            throw new DirectoryTokenMissingException();
+
+        var repo = _configuration["BTCMAPS:DirectoryRepo"] ?? DefaultDirectoryRepo;
+        var merchantsPath = _configuration["BTCMAPS:DirectoryMerchantsPath"] ?? DefaultDirectoryMerchantsPath;
+
+        var client = _httpClientFactory.CreateClient(HttpClientNames.BtcMapsDirectory);
+        // Auth is per-call: the named-client registration sets BaseAddress + User-Agent
+        // + Accept + Timeout, but the BTCMAPS token is distinct from the global
+        // PluginBuilder GitHub token and must not be baked into the singleton handler.
+        using var authClient = new HttpRequestAuth(client, token);
+
+        var repoInfo = await GetJsonAsync(authClient, $"repos/{repo}", cancellationToken);
+        var defaultBranch = repoInfo.GetProperty("default_branch").GetString()
+            ?? throw new InvalidOperationException("default_branch missing");
+
+        var fileInfo = await GetJsonAsync(
+            authClient,
+            $"repos/{repo}/contents/{merchantsPath}?ref={Uri.EscapeDataString(defaultBranch)}",
+            cancellationToken);
+        var contentB64 = fileInfo.GetProperty("content").GetString() ?? string.Empty;
+        var fileSha = fileInfo.GetProperty("sha").GetString() ?? string.Empty;
+        var currentJson = Encoding.UTF8.GetString(Convert.FromBase64String(contentB64.Replace("\n", string.Empty)));
+
+        var merchants = JsonSerializer.Deserialize<List<JsonElement>>(currentJson)
+            ?? throw new InvalidOperationException("merchants.json must be a JSON array");
+
+        var normalizedUrl = NormalizeUrl(request.Url!);
+        foreach (var existing in merchants)
+        {
+            if (existing.TryGetProperty("url", out var existingUrl) &&
+                existingUrl.ValueKind == JsonValueKind.String &&
+                NormalizeUrl(existingUrl.GetString() ?? string.Empty) == normalizedUrl)
+            {
+                var existingName = existing.TryGetProperty("name", out var n) ? n.GetString() : "(unknown)";
+                return new BtcMapsDirectoryResult { Skipped = $"duplicate-url:{existingName}" };
+            }
+        }
+
+        // Deterministic branch name derived from the normalized URL. Two concurrent
+        // submissions of the same URL collide on the git/refs create instead of
+        // racing through preflight and opening duplicate PRs.
+        var branchName = BuildBranchName(request.Name!, normalizedUrl);
+        var marker = BuildUrlMarker(normalizedUrl);
+
+        var branchRef = await GetJsonAsync(
+            authClient,
+            $"repos/{repo}/git/ref/heads/{Uri.EscapeDataString(defaultBranch)}",
+            cancellationToken);
+        var baseSha = branchRef.GetProperty("object").GetProperty("sha").GetString()
+            ?? throw new InvalidOperationException("base sha missing");
+
+        var newEntry = BuildMerchantEntry(request);
+        var updated = merchants
+            .Select(e => (JsonElement?)e)
+            .Append(newEntry)
+            .OrderBy(e => e!.Value.TryGetProperty("name", out var n) ? n.GetString() : string.Empty,
+                StringComparer.OrdinalIgnoreCase)
+            .Select(e => e!.Value)
+            .ToList();
+
+        // Use UnsafeRelaxedJsonEscaping so non-ASCII codepoints and HTML-only "unsafe"
+        // chars (`&`, `'`, `<`, `>`) are written raw in the file, matching the upstream
+        // merchants.json convention. The default JavaScriptEncoder is HTML-safe and
+        // would re-encode every entry containing `'` or non-ASCII as `\uXXXX`, which
+        // shows up as a noisy full-file diff on every append.
+        var updatedJson = JsonSerializer.Serialize(updated, new JsonSerializerOptions
+        {
+            WriteIndented = true,
+            Encoder = JavaScriptEncoder.UnsafeRelaxedJsonEscaping
+        }) + "\n";
+
+        var refCreateResponse = await PostJsonAllowConflictAsync(
+            authClient,
+            $"repos/{repo}/git/refs",
+            new { @ref = $"refs/heads/{branchName}", sha = baseSha },
+            cancellationToken);
+        if (refCreateResponse.IsConflict)
+        {
+            // Branch already exists. Look up the open PR keyed by the URL marker;
+            // if one is open, return its details; otherwise this is a stuck-branch
+            // from a prior failed run and we cannot safely reuse it.
+            var openPrSearch = await GetJsonAsync(
+                authClient,
+                $"search/issues?q={Uri.EscapeDataString($"repo:{repo} is:pr is:open in:body \"{marker}\"")}",
+                cancellationToken);
+            if (openPrSearch.TryGetProperty("total_count", out var totalCount) && totalCount.GetInt32() > 0)
+            {
+                var firstItem = openPrSearch.GetProperty("items")[0];
+                return new BtcMapsDirectoryResult
+                {
+                    Skipped = "duplicate-open-pr",
+                    PrUrl = firstItem.TryGetProperty("html_url", out var h) ? h.GetString() : null,
+                    PrNumber = firstItem.TryGetProperty("number", out var n) ? n.GetInt32() : null
+                };
+            }
+            return new BtcMapsDirectoryResult { Skipped = "branch-exists-no-open-pr", Branch = branchName };
+        }
+
+        await PutJsonAsync(authClient, $"repos/{repo}/contents/{merchantsPath}",
+            new
+            {
+                message = $"Add {request.Name}",
+                content = Convert.ToBase64String(Encoding.UTF8.GetBytes(updatedJson)),
+                sha = fileSha,
+                branch = branchName
+            }, cancellationToken);
+
+        var prBody = BuildPrBody(request, marker);
+        var prResponse = await PostJsonAsync(authClient, $"repos/{repo}/pulls",
+            new
+            {
+                title = $"Add {request.Name}",
+                head = branchName,
+                @base = defaultBranch,
+                body = prBody
+            }, cancellationToken);
+
+        return new BtcMapsDirectoryResult
+        {
+            PrUrl = prResponse.GetProperty("html_url").GetString(),
+            PrNumber = prResponse.GetProperty("number").GetInt32(),
+            Branch = branchName
+        };
+    }
+
+    private static JsonElement BuildMerchantEntry(BtcMapsSubmitRequest request)
+    {
+        using var ms = new MemoryStream();
+        using (var w = new Utf8JsonWriter(ms, new JsonWriterOptions { Indented = false }))
+        {
+            w.WriteStartObject();
+            w.WriteString("name", request.Name!.Trim());
+            w.WriteString("url", request.Url!.Trim());
+            w.WriteString("description", request.Description!.Trim());
+            // type + subType are validated case-insensitively above
+            // (ValidTypes / ValidMerchantSubTypes use OrdinalIgnoreCase) but
+            // the upstream merchants.json convention is lowercase. Normalize
+            // on write so a submission of "Merchants" / "Books" lands as
+            // "merchants" / "books" in the file. Country uses a case-sensitive
+            // Ordinal set so the validator already rejects non-uppercase.
+            w.WriteString("type", request.Type!.Trim().ToLowerInvariant());
+            if (!string.IsNullOrWhiteSpace(request.SubType))
+                w.WriteString("subType", request.SubType.Trim().ToLowerInvariant());
+            if (!string.IsNullOrWhiteSpace(request.Country))
+                w.WriteString("country", request.Country.Trim());
+            if (!string.IsNullOrWhiteSpace(request.Twitter))
+            {
+                var t = request.Twitter.Trim();
+                w.WriteString("twitter", t.StartsWith("@") ? t : "@" + t);
+            }
+            if (!string.IsNullOrWhiteSpace(request.Github))
+                w.WriteString("github", request.Github.Trim());
+            if (!string.IsNullOrWhiteSpace(request.OnionUrl))
+                w.WriteString("onionUrl", request.OnionUrl.Trim());
+            w.WriteEndObject();
+        }
+        ms.Position = 0;
+        using var doc = JsonDocument.Parse(ms);
+        return doc.RootElement.Clone();
+    }
+
+    private static string BuildPrBody(BtcMapsSubmitRequest request, string urlMarker)
+    {
+        // User-supplied fields are wrapped in inline code spans so a doctored merchant
+        // name (e.g. `[click here](https://attacker.example)`) can't render as a clickable
+        // link in the maintainer-facing PR description. The URL is its own line and is
+        // displayed via a plain markdown link with a sanitized label so the maintainer
+        // sees the bare URL, not a renamed target.
+        var sb = new StringBuilder();
+        sb.AppendLine("Automated submission from the BTCPay Server plugin-builder `/apis/btcmaps/v1/submit` endpoint.");
+        sb.AppendLine();
+        sb.AppendLine($"- **Name:** {EscapeInlineCode(request.Name)}");
+        sb.AppendLine($"- **URL:** <{request.Url}>");
+        sb.AppendLine($"- **Type:** {EscapeInlineCode(request.Type)}{(string.IsNullOrWhiteSpace(request.SubType) ? string.Empty : " / " + EscapeInlineCode(request.SubType))}");
+        if (!string.IsNullOrWhiteSpace(request.Country)) sb.AppendLine($"- **Country:** {EscapeInlineCode(request.Country.Trim())}");
+        if (!string.IsNullOrWhiteSpace(request.Twitter))
+        {
+            // The Twitter handle is rendered inside an inline code span so a hostile
+            // value like `]( <evil-url> )` cannot escape into an active link. The
+            // maintainer can copy the handle and visit manually.
+            var raw = request.Twitter.Trim();
+            var handle = raw.StartsWith("@") ? raw[1..] : raw;
+            sb.AppendLine($"- **Twitter:** {EscapeInlineCode("@" + handle)}");
+        }
+        if (!string.IsNullOrWhiteSpace(request.Github)) sb.AppendLine($"- **GitHub:** {EscapeInlineCode(request.Github)}");
+        sb.AppendLine();
+        sb.AppendLine("**Description:**");
+        sb.AppendLine();
+        sb.AppendLine("```");
+        sb.AppendLine(request.Description?.Replace("```", "``​`") ?? string.Empty);
+        sb.AppendLine("```");
+        sb.AppendLine();
+        sb.AppendLine("_Please review before merge - this PR was opened programmatically by a BTCMap-plugin merchant submission, not by a maintainer._");
+        sb.AppendLine();
+        sb.AppendLine($"<!-- {urlMarker} -->");
+        return sb.ToString();
+    }
+
+    // Wrap user input as an inline code span. Use enough backticks to escape any
+    // backticks the input contains (CommonMark inline-code-fence rule).
+    private static string EscapeInlineCode(string? value)
+    {
+        var s = value ?? string.Empty;
+        if (s.Length == 0) return "``";
+        var longestRun = 0;
+        var current = 0;
+        foreach (var c in s)
+        {
+            if (c == '`') { current++; if (current > longestRun) longestRun = current; }
+            else current = 0;
+        }
+        var fence = new string('`', longestRun + 1);
+        // Pad with spaces if the value starts or ends with a backtick (CommonMark rule).
+        var needsPad = s.StartsWith("`") || s.EndsWith("`");
+        return needsPad ? $"{fence} {s} {fence}" : $"{fence}{s}{fence}";
+    }
+
+    private static string BuildUrlMarker(string normalizedUrl) =>
+        $"btcmaps-submit:url={normalizedUrl}";
+
+    public static string NormalizeUrl(string url)
+    {
+        // Normalize for duplicate detection without lying about case-sensitive parts.
+        // Scheme + host get lower-cased (DNS is case-insensitive, scheme is too); path
+        // and query are preserved as-is. Trailing slash is trimmed only when the path
+        // is the bare root, since /foo/ and /foo are sometimes distinct on real servers.
+        var trimmed = (url ?? string.Empty).Trim();
+        if (!Uri.TryCreate(trimmed, UriKind.Absolute, out var parsed))
+            return trimmed.TrimEnd('/');
+        var sb = new StringBuilder();
+        sb.Append(parsed.Scheme.ToLowerInvariant());
+        sb.Append("://");
+        sb.Append(parsed.Host.ToLowerInvariant());
+        if (!parsed.IsDefaultPort)
+        {
+            sb.Append(':');
+            sb.Append(parsed.Port);
+        }
+        var path = parsed.AbsolutePath;
+        if (path == "/")
+            sb.Append(path);
+        else
+            sb.Append(path.TrimEnd('/'));
+        if (!string.IsNullOrEmpty(parsed.Query))
+            sb.Append(parsed.Query);
+        return sb.ToString();
+    }
+
+    // Deterministic branch name from the normalized URL. Same URL always produces
+    // the same branch; second concurrent submission collides on the git/refs create
+    // and the controller surfaces the duplicate-open-PR shape.
+    public static string BuildBranchName(string name, string normalizedUrl)
+    {
+        var slug = Slugify(name);
+        var hash = SHA1.HashData(Encoding.UTF8.GetBytes(normalizedUrl));
+        var suffix = Convert.ToHexString(hash)[..8].ToLowerInvariant();
+        return $"btcmaps/{slug}-{suffix}";
+    }
+
+    public static string Slugify(string input)
+    {
+        var chars = new StringBuilder();
+        var lastWasDash = true;
+        foreach (var c in input.ToLowerInvariant())
+        {
+            if (c is >= 'a' and <= 'z' or >= '0' and <= '9')
+            {
+                chars.Append(c);
+                lastWasDash = false;
+            }
+            else if (!lastWasDash)
+            {
+                chars.Append('-');
+                lastWasDash = true;
+            }
+        }
+        var result = chars.ToString().Trim('-');
+        if (result.Length > 40) result = result[..40].TrimEnd('-');
+        return result.Length == 0 ? "merchant" : result;
+    }
+
+    // Lightweight wrapper that re-attaches the per-request Authorization header on
+    // each call. The named-client handler is reused (socket pool, factory rotation),
+    // but auth stays out of the singleton handler.
+    private sealed class HttpRequestAuth : IDisposable
+    {
+        public HttpClient Client { get; }
+        public string Token { get; }
+        public HttpRequestAuth(HttpClient client, string token) { Client = client; Token = token; }
+        public void Dispose() { /* HttpClient is owned by IHttpClientFactory; do not dispose */ }
+    }
+
+    private static HttpRequestMessage NewRequest(HttpMethod method, string path, string token)
+    {
+        var req = new HttpRequestMessage(method, path);
+        req.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
+        return req;
+    }
+
+    private static async Task<JsonElement> GetJsonAsync(HttpRequestAuth auth, string path, CancellationToken ct)
+    {
+        using var req = NewRequest(HttpMethod.Get, path, auth.Token);
+        using var response = await auth.Client.SendAsync(req, ct);
+        await EnsureSuccess(response, path, ct);
+        var text = await response.Content.ReadAsStringAsync(ct);
+        using var doc = JsonDocument.Parse(text);
+        return doc.RootElement.Clone();
+    }
+
+    private static async Task<JsonElement> PostJsonAsync(HttpRequestAuth auth, string path, object body, CancellationToken ct)
+    {
+        using var req = NewRequest(HttpMethod.Post, path, auth.Token);
+        req.Content = new StringContent(JsonSerializer.Serialize(body), Encoding.UTF8, "application/json");
+        using var response = await auth.Client.SendAsync(req, ct);
+        await EnsureSuccess(response, path, ct);
+        var text = await response.Content.ReadAsStringAsync(ct);
+        using var doc = JsonDocument.Parse(text);
+        return doc.RootElement.Clone();
+    }
+
+    private readonly record struct ConflictAware(JsonElement? Body, bool IsConflict);
+
+    private static async Task<ConflictAware> PostJsonAllowConflictAsync(HttpRequestAuth auth, string path, object body, CancellationToken ct)
+    {
+        using var req = NewRequest(HttpMethod.Post, path, auth.Token);
+        req.Content = new StringContent(JsonSerializer.Serialize(body), Encoding.UTF8, "application/json");
+        using var response = await auth.Client.SendAsync(req, ct);
+        if (response.StatusCode == System.Net.HttpStatusCode.UnprocessableEntity)
+        {
+            // GitHub returns 422 "Reference already exists" when the branch ref is
+            // pre-claimed by a concurrent or earlier submission. That's the idempotency
+            // signal we want; surface it.
+            var conflictText = await response.Content.ReadAsStringAsync(ct);
+            if (conflictText.Contains("Reference already exists", StringComparison.OrdinalIgnoreCase))
+                return new ConflictAware(null, true);
+            throw new HttpRequestException($"GitHub {(int)response.StatusCode} {path}: {conflictText}");
+        }
+        await EnsureSuccess(response, path, ct);
+        var text = await response.Content.ReadAsStringAsync(ct);
+        using var doc = JsonDocument.Parse(text);
+        return new ConflictAware(doc.RootElement.Clone(), false);
+    }
+
+    private static async Task<JsonElement> PutJsonAsync(HttpRequestAuth auth, string path, object body, CancellationToken ct)
+    {
+        using var req = NewRequest(HttpMethod.Put, path, auth.Token);
+        req.Content = new StringContent(JsonSerializer.Serialize(body), Encoding.UTF8, "application/json");
+        using var response = await auth.Client.SendAsync(req, ct);
+        await EnsureSuccess(response, path, ct);
+        var text = await response.Content.ReadAsStringAsync(ct);
+        using var doc = JsonDocument.Parse(text);
+        return doc.RootElement.Clone();
+    }
+
+    private static async Task EnsureSuccess(HttpResponseMessage response, string path, CancellationToken ct)
+    {
+        if (response.IsSuccessStatusCode) return;
+        var body = await response.Content.ReadAsStringAsync(ct);
+        throw new HttpRequestException($"GitHub {(int)response.StatusCode} {path}: {body}");
+    }
+}