Merge pull request #7795 from tumutech/fix-api-key-permission-usage-analysis
What changed, and why it matters
This commit fixes a crash in BTCPay Server's admin page that shows how an API key has been used. The crash happened when an API key had permissions tied to more than one store. The fix also corrects how usage counts are recorded and displayed so store-specific permissions are counted separately instead of being lumped together. It is primarily a reliability/functional bug fix; there is no direct evidence it created or fixed a security vulnerability that an attacker could exploit.
Treat as a routine bug-fix merge. Reviewers may optionally verify that the new TryAggregateUsage matching logic cannot be confused by malformed permission strings, and confirm the upsert idempotency still behaves correctly under concurrency. No urgent security response is indicated by the diff alone.
Security signals we found
Fixes a UI crash in an administrative API-key usage page
Corrects aggregation of permission usage records when permissions are scoped to specific stores
Changes database upsert to persist full permission string including store scope
Adds backward-compatible parsing for legacy usage rows that stored only the policy
No authentication bypass, authorization bypass, injection, or secret disclosure visible in the diff
Evidence from the diff
The merge updates the API key ‘View Usage’ analysis feature. Previously, the controller built a dictionary keyed by the raw permission string, which could not distinguish store-scoped permissions and could throw or mis-report when multiple stores shared the same policy. The patch changes the repository to store the full permission string (policy + scope) on upsert, adds a TryAggregateUsage helper that matches usage records by policy and scope, and updates the view/test selectors. The tests simulate legacy rows where only the policy was stored and verify counts remain correct after migration-style reuse.
Changed components
BTCPayServer/Controllers/UIManageController.APIKeys.csBTCPayServer/Security/GreenField/APIKeyRepository.csBTCPayServer/Views/UIManage/APIKeyPermissionAnalysis.cshtmlBTCPayServer.Tests/ApiKeysTests.csInspect captured patch +128 / −48
### BTCPayServer.Tests/ApiKeysTests.cs
@@ -16,6 +16,7 @@
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Identity;
using Microsoft.AspNetCore.Mvc;
+using Microsoft.EntityFrameworkCore;
using Microsoft.Playwright;
using Newtonsoft.Json;
using Newtonsoft.Json.Linq;
@@ -391,49 +392,101 @@ public async Task CanViewApiKeyPermissionAnalysis()
await s.Page.Locator(".api-key-list__view-usage").ClickAsync();
- var cards = await s.Page.Locator(".display-6.fw-bold").AllTextContentsAsync();
- Assert.Equal("2", cards[0].Trim());
- Assert.Equal("0", cards[1].Trim());
- Assert.Equal("2", cards[2].Trim());
+ await Expect(s.Page.Locator(".api-key-analysis__total-count")).ToHaveTextAsync("2");
+ await Expect(s.Page.Locator(".api-key-analysis__used-count")).ToHaveTextAsync("0");
+ await Expect(s.Page.Locator(".api-key-analysis__unused-count")).ToHaveTextAsync("2");
- var allRows = s.Page.Locator("#all-permissions tbody tr");
- Assert.Equal(2, await allRows.CountAsync());
- var neverUsedBadges = s.Page.Locator("#all-permissions .badge:has-text('Never Used')");
- Assert.Equal(2, await neverUsedBadges.CountAsync());
+ var allRows = s.Page.Locator(".api-key-analysis__all-permissions tbody tr");
+ await Expect(allRows).ToHaveCountAsync(2);
+ await Expect(allRows.Locator(".badge")).ToHaveTextAsync(new[] { "Never Used", "Never Used" });
- await s.Page.Locator("#used-tab").ClickAsync();
- await s.Page.Locator("#used-permissions.show.active").WaitForAsync();
- Assert.Equal(0, await s.Page.Locator("#used-permissions tbody tr").CountAsync());
+ await s.Page.GetByRole(AriaRole.Tab, new() { Name = "Used (0)", Exact = true }).ClickAsync();
+ var usedRows = s.Page.Locator(".api-key-analysis__used-permissions tbody tr");
+ await Expect(usedRows).ToHaveCountAsync(0);
- await s.Page.Locator("#unused-tab").ClickAsync();
- await s.Page.Locator("#unused-permissions.show.active").WaitForAsync();
- var unusedRows = s.Page.Locator("#unused-permissions tbody tr");
- Assert.Equal(2, await unusedRows.CountAsync());
+ await s.Page.GetByRole(AriaRole.Tab, new() { Name = "Unused (2)", Exact = true }).ClickAsync();
+ var unusedRows = s.Page.Locator(".api-key-analysis__unused-permissions tbody tr");
+ await Expect(unusedRows).ToHaveCountAsync(2);
- var uri = new Uri(tester.PayTester.ServerUri, $"api/v1/stores/{user.StoreId}/invoices");
- var request = new HttpRequestMessage(HttpMethod.Get, uri);
- request.Headers.Authorization = new AuthenticationHeaderValue("token", apiKey);
- var response = await tester.PayTester.HttpClient.SendAsync(request);
- response.EnsureSuccessStatusCode();
+ var firstStoreId = user.StoreId;
+ await user.CreateStoreAsync();
+ var secondStoreId = user.StoreId;
+ var client = user.CreateClientFromAPIKey(apiKey);
+ await client.GetInvoices(firstStoreId);
+ await client.GetInvoices(secondStoreId);
+
+ var apiKeyRepo = tester.PayTester.GetService<APIKeyRepository>();
+ var selector = new APIKeyRepository.Selector.ByApiKey(apiKey);
+ // Usage is recorded asynchronously by the permission handler.
+ await TestUtils.EventuallyAsync(async () =>
+ Assert.Equal(2, (await apiKeyRepo.GetAPIPermissionUsageRecords(selector)).Sum(u => u.UsageCount)));
await s.Page.ReloadAsync();
- await s.Page.WaitForLoadStateAsync(LoadState.DOMContentLoaded);
+ await Expect(s.Page.Locator(".api-key-analysis__total-count")).ToHaveTextAsync("2");
+ await Expect(s.Page.Locator(".api-key-analysis__used-count")).ToHaveTextAsync("1");
+ await Expect(s.Page.Locator(".api-key-analysis__unused-count")).ToHaveTextAsync("1");
+ await s.Page.GetByRole(AriaRole.Tab, new() { Name = "Used (1)", Exact = true }).ClickAsync();
+ await Expect(usedRows).ToHaveCountAsync(1);
+ await Expect(usedRows.Locator("td").Nth(0)).ToHaveTextAsync(Policies.CanViewInvoices);
+ await Expect(usedRows.Locator("td").Nth(1)).ToHaveTextAsync("2");
+ await Expect(usedRows.Locator(".badge")).ToHaveTextAsync("Active");
+
+ await s.Page.GetByRole(AriaRole.Tab, new() { Name = "Unused (1)", Exact = true }).ClickAsync();
+ await Expect(unusedRows).ToHaveCountAsync(1);
+ await Expect(unusedRows.Locator("code")).ToHaveTextAsync(Policies.CanCreateInvoice);
+
+ // Older versions stored only the policy in the Permission column, duplicating it across stores.
+ var dbFactory = tester.PayTester.GetService<ApplicationDbContextFactory>();
+ await using (var context = dbFactory.CreateContext())
+ {
+ await context.ApiKeyPermissionUsages.Where(u => u.ApiKeyId == selector.GetId())
+ .ExecuteUpdateAsync(update => update.SetProperty(u => u.Permission, Policies.CanViewInvoices));
+ }
+ await s.Page.ReloadAsync();
+ await s.Page.GetByRole(AriaRole.Tab, new() { Name = "Used (1)", Exact = true }).ClickAsync();
+ await Expect(usedRows.Locator("td").Nth(1)).ToHaveTextAsync("2");
- cards = await s.Page.Locator(".display-6.fw-bold").AllTextContentsAsync();
- Assert.Equal("2", cards[0].Trim());
- Assert.Equal("1", cards[1].Trim());
- Assert.Equal("1", cards[2].Trim());
-
- await s.Page.Locator("#used-tab").ClickAsync();
- await s.Page.Locator("#used-permissions.show.active").WaitForAsync();
- var usedRows = s.Page.Locator("#used-permissions tbody tr");
- Assert.Equal(1, await usedRows.CountAsync());
- await s.Page.Locator("#used-permissions .badge.bg-success:has-text('Active')").WaitForAsync();
-
- await s.Page.Locator("#unused-tab").ClickAsync();
- await s.Page.Locator("#unused-permissions.show.active").WaitForAsync();
- unusedRows = s.Page.Locator("#unused-permissions tbody tr");
- Assert.Equal(1, await unusedRows.CountAsync());
+ // Reusing a legacy row updates its format without losing its previous count.
+ await client.GetInvoices(firstStoreId);
+ await TestUtils.EventuallyAsync(async () =>
+ {
+ var usages = await apiKeyRepo.GetAPIPermissionUsageRecords(selector);
+ Assert.Equal(3, usages.Sum(u => u.UsageCount));
+ Assert.Contains(usages, u => u.Permission == Permission.Create(Policies.CanViewInvoices, firstStoreId).ToString());
+ });
+ await s.Page.ReloadAsync();
+ await s.Page.GetByRole(AriaRole.Tab, new() { Name = "Used (1)", Exact = true }).ClickAsync();
+ await Expect(usedRows.Locator("td").Nth(1)).ToHaveTextAsync("3");
+
+ // Store-specific grants must show only their own usage, not the other store's count.
+ var firstGrant = Permission.Create(Policies.CanViewInvoices, firstStoreId).ToString();
+ var secondGrant = Permission.Create(Policies.CanViewInvoices, secondStoreId).ToString();
+ var scopedClient = await user.CreateClient(firstGrant, secondGrant, Policies.CanCreateInvoice);
+ await scopedClient.GetInvoices(firstStoreId);
+ await scopedClient.GetInvoices(firstStoreId);
+ await scopedClient.GetInvoices(secondStoreId);
+ var scopedSelector = new APIKeyRepository.Selector.ByApiKey(scopedClient.APIKey);
+ await TestUtils.EventuallyAsync(async () =>
+ Assert.Equal(3, (await apiKeyRepo.GetAPIPermissionUsageRecords(scopedSelector)).Sum(u => u.UsageCount)));
+
+ await s.GoToUrl($"api-keys/{scopedSelector.GetId()}/view-analysis", true);
+ await Expect(s.Page.Locator(".api-key-analysis__total-count")).ToHaveTextAsync("3");
+ await Expect(s.Page.Locator(".api-key-analysis__used-count")).ToHaveTextAsync("2");
+ await Expect(s.Page.Locator(".api-key-analysis__unused-count")).ToHaveTextAsync("1");
+ await s.Page.GetByRole(AriaRole.Tab, new() { Name = "Used (2)", Exact = true }).ClickAsync();
+ await Expect(usedRows).ToHaveCountAsync(2);
+ await Expect(usedRows.Filter(new() { HasText = firstGrant }).Locator("td").Nth(1)).ToHaveTextAsync("2");
+ await Expect(usedRows.Filter(new() { HasText = secondGrant }).Locator("td").Nth(1)).ToHaveTextAsync("1");
+
+ await using (var context = dbFactory.CreateContext())
+ {
+ await context.ApiKeyPermissionUsages.Where(u => u.ApiKeyId == scopedSelector.GetId())
+ .ExecuteUpdateAsync(update => update.SetProperty(u => u.Permission, Policies.CanViewInvoices));
+ }
+ await s.Page.ReloadAsync();
+ await s.Page.GetByRole(AriaRole.Tab, new() { Name = "Used (2)", Exact = true }).ClickAsync();
+ await Expect(usedRows.Filter(new() { HasText = firstGrant }).Locator("td").Nth(1)).ToHaveTextAsync("2");
+ await Expect(usedRows.Filter(new() { HasText = secondGrant }).Locator("td").Nth(1)).ToHaveTextAsync("1");
}
[Fact]
### BTCPayServer/Controllers/UIManageController.APIKeys.cs
@@ -40,21 +40,20 @@ public async Task<IActionResult> APIKeyPermissionAnalysis(string apiKeyId)
var allPermissions = key.GetBlob().Permissions;
var usageRecords = await _apiKeyRepository.GetAPIPermissionUsageRecords(id);
- var usageByPermission = usageRecords.ToDictionary(u => u.Permission, u => u);
var usedPermissions = new List<PermissionUsageViewModel>();
var unusedPermissions = new List<string>();
var allPermissionVMs = new List<PermissionViewModel>();
foreach (var permission in allPermissions)
{
- if (usageByPermission.TryGetValue(permission, out var usage))
+ if (APIKeyRepository.TryAggregateUsage(permission, usageRecords, out var usageCount, out var lastUsed))
{
var usageVM = new PermissionUsageViewModel
{
- Permission = usage.Permission,
- LastUsed = usage.LastUsed,
- UsageCount = usage.UsageCount
+ Permission = permission,
+ LastUsed = lastUsed,
+ UsageCount = usageCount
};
usedPermissions.Add(usageVM);
allPermissionVMs.Add(new PermissionViewModel { Permission = permission, Usage = usageVM });
### BTCPayServer/Security/GreenField/APIKeyRepository.cs
@@ -125,13 +125,14 @@ public async Task RecordPermissionUsage(Selector selector, Permission permission
VALUES (@Id, @ApiKeyId, @Permission, @LastUsed, 1)
ON CONFLICT (""Id"")
DO UPDATE SET
+ ""Permission"" = @Permission,
""LastUsed"" = @LastUsed,
""UsageCount"" = ""ApiKeyPermissionUsages"".""UsageCount"" + 1";
await context.Database.ExecuteSqlRawAsync(sql,
new NpgsqlParameter("@Id", $"{id}-{permission}"),
new NpgsqlParameter("@ApiKeyId", id),
- new NpgsqlParameter("@Permission", permission.Policy),
+ new NpgsqlParameter("@Permission", permission.ToString()),
new NpgsqlParameter("@LastUsed", DateTimeOffset.UtcNow));
}
@@ -143,6 +144,33 @@ public async Task<List<ApiKeyPermissionUsage>> GetAPIPermissionUsageRecords(Sele
return entity.Any() ? entity : new List<ApiKeyPermissionUsage>();
}
+ public static bool TryAggregateUsage(string grant, IEnumerable<ApiKeyPermissionUsage> usages, out int usageCount, out DateTimeOffset lastUsed)
+ {
+ usageCount = 0;
+ lastUsed = default;
+ if (!Permission.TryParse(grant, out var parsedGrant))
+ return false;
+
+ var matched = false;
+ foreach (var usage in usages)
+ {
+ var prefix = usage.ApiKeyId + "-";
+ var raw = usage.Id is not null && usage.Id.StartsWith(prefix, StringComparison.Ordinal)
+ ? usage.Id.Substring(prefix.Length)
+ : usage.Permission;
+ if (!Permission.TryParse(raw, out var recorded) || recorded.Policy != parsedGrant.Policy)
+ continue;
+ if (parsedGrant.Scope is not null && parsedGrant.Scope != recorded.Scope)
+ continue;
+
+ matched = true;
+ usageCount += usage.UsageCount;
+ if (usage.LastUsed > lastUsed)
+ lastUsed = usage.LastUsed;
+ }
+ return matched;
+ }
+
public class APIKeyQuery
{
public string[] UserId { get; set; }
### BTCPayServer/Views/UIManage/APIKeyPermissionAnalysis.cshtml
@@ -20,7 +20,7 @@
<span class="text-muted small" text-translate="true">Total Permissions</span>
<i class="bi bi-key fs-5 text-muted"></i>
</div>
- <div class="display-6 fw-bold mb-2">@Model.TotalPermissions</div>
+ <div class="display-6 fw-bold mb-2 api-key-analysis__total-count">@Model.TotalPermissions</div>
<div class="progress" style="height:4px">
<div class="progress-bar" style="width:100%"></div>
</div>
@@ -34,7 +34,7 @@
<span class="text-muted small" text-translate="true">Used Permissions</span>
<i class="bi bi-check-circle fs-5 text-muted"></i>
</div>
- <div class="display-6 fw-bold mb-1">@Model.UsedPermissions.Count</div>
+ <div class="display-6 fw-bold mb-1 api-key-analysis__used-count">@Model.UsedPermissions.Count</div>
<div class="small text-muted mb-2">@usedPermissionsPercentage% of total</div>
<div class="progress" style="height:4px">
<div class="progress-bar" style="width:@usedPermissionsPercentage%"></div>
@@ -49,7 +49,7 @@
<span class="text-muted small" text-translate="true">Unused Permissions</span>
<i class="bi bi-exclamation-circle fs-5 text-muted"></i>
</div>
- <div class="display-6 fw-bold mb-1">@Model.UnusedPermissions.Count</div>
+ <div class="display-6 fw-bold mb-1 api-key-analysis__unused-count">@Model.UnusedPermissions.Count</div>
<div class="small text-muted mb-2">@(100 - usedPermissionsPercentage)% of total</div>
<div class="progress" style="height:4px">
<div class="progress-bar" style="width:@(100 - usedPermissionsPercentage)%"></div>
@@ -82,7 +82,7 @@
<div class="card-body p-3">
<div class="tab-content" id="permissionTabContent">
- <div class="tab-pane fade show active" id="all-permissions" role="tabpanel">
+ <div class="tab-pane fade show active api-key-analysis__all-permissions" id="all-permissions" role="tabpanel">
@if (Model.AllPermissions.Any())
{
<table class="table table-hover mb-0">
@@ -150,7 +150,7 @@
}
</div>
- <div class="tab-pane fade" id="used-permissions" role="tabpanel">
+ <div class="tab-pane fade api-key-analysis__used-permissions" id="used-permissions" role="tabpanel">
@if (Model.UsedPermissions.Any())
{
<table class="table table-hover mb-0">
@@ -194,7 +194,7 @@
}
</div>
- <div class="tab-pane fade" id="unused-permissions" role="tabpanel">
+ <div class="tab-pane fade api-key-analysis__unused-permissions" id="unused-permissions" role="tabpanel">
@if (Model.UnusedPermissions.Any())
{
<table class="table table-hover mb-0">Why this scored 24/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.