feat(auth.apikeys): IApiKeyStoreMigrator abstraction — SQLite implements it, DI registers it via TryAdd so a provider registered first wins; ApiKeyAdminCommands accepts the interface (old ctor kept)

Claude-Session: https://claude.ai/code/session_013L3XdmVii9i5sY4FChU8pB
2026-09-02 14:06:14 -04:00
parent 300094e792
commit 3f11704d10
6 changed files with 85 additions and 10 deletions
@@ -78,3 +78,16 @@ public interface IApiKeyAuditStore
    Task AppendAsync(ApiKeyAuditEntry entry, CancellationToken ct);
    Task<IReadOnlyList<ApiKeyAuditEntry>> ListRecentAsync(int limit, CancellationToken ct);
 }
+
+/// <summary>
+/// Creates or upgrades the API-key store schema to the version this build supports. Each store
+/// provider (SQLite, SQL Server) supplies one; hosts run it at startup and before admin commands.
+/// Implementations must be idempotent and safe to run concurrently from several nodes.
+/// </summary>
+public interface IApiKeyStoreMigrator
+{
+    /// <summary>Migrates the store schema.</summary>
+    /// <param name="ct">A token to cancel the operation.</param>
+    /// <returns>A task that completes when the schema is current.</returns>
+    Task MigrateAsync(CancellationToken ct);
+}
@@ -33,10 +33,15 @@ public sealed class ApiKeyAdminCommands
    private readonly IApiKeyAdminStore _adminStore;
    private readonly IApiKeyAuditStore _auditStore;
    private readonly IApiKeyPepperProvider _pepperProvider;
-    private readonly SqliteAuthStoreMigrator _migrator;
+    private readonly IApiKeyStoreMigrator _migrator;
    private readonly TimeProvider _clock;

-    /// <summary>Creates the command set over the supplied stores and options.</summary>
+    /// <summary>
+    /// Creates the command set over the supplied stores and options.
+    /// Retained for existing consumers (MxAccessGateway, HistorianGateway, ScadaBridge) that
+    /// construct this type against the concrete SQLite migrator; forwards to the
+    /// <see cref="IApiKeyStoreMigrator"/> overload.
+    /// </summary>
    /// <param name="options">API-key options (token prefix, store path, ...).</param>
    /// <param name="adminStore">Mutating store (create / revoke / rotate / delete / list).</param>
    /// <param name="auditStore">Append-only audit store wired into every mutating verb.</param>
@@ -50,6 +55,25 @@ public sealed class ApiKeyAdminCommands
        IApiKeyPepperProvider pepperProvider,
        SqliteAuthStoreMigrator migrator,
        TimeProvider? clock = null)
+        : this(options, adminStore, auditStore, pepperProvider, (IApiKeyStoreMigrator)migrator, clock)
+    {
+    }
+
+    /// <summary>Creates the command set over the supplied stores and options.</summary>
+    /// <param name="options">API-key options (token prefix, store path, ...).</param>
+    /// <param name="adminStore">Mutating store (create / revoke / rotate / delete / list).</param>
+    /// <param name="auditStore">Append-only audit store wired into every mutating verb.</param>
+    /// <param name="pepperProvider">Resolves the pepper used to hash secrets.</param>
+    /// <param name="migrator">Schema migrator used by <see cref="InitDbAsync"/> — whichever store
+    /// provider's implementation (SQLite, SQL Server, ...) DI has registered.</param>
+    /// <param name="clock">Optional clock; defaults to <see cref="TimeProvider.System"/>.</param>
+    public ApiKeyAdminCommands(
+        ApiKeyOptions options,
+        IApiKeyAdminStore adminStore,
+        IApiKeyAuditStore auditStore,
+        IApiKeyPepperProvider pepperProvider,
+        IApiKeyStoreMigrator migrator,
+        TimeProvider? clock = null)
    {
        ArgumentNullException.ThrowIfNull(options);
        ArgumentNullException.ThrowIfNull(adminStore);
@@ -1,17 +1,18 @@
 using Microsoft.Extensions.Hosting;
 using Microsoft.Extensions.Options;
 using ZB.MOM.WW.Auth.Abstractions.ApiKeys;
-using ZB.MOM.WW.Auth.ApiKeys.Sqlite;

 namespace ZB.MOM.WW.Auth.ApiKeys.DependencyInjection;

 /// <summary>
-/// Runs the API-key SQLite schema migration at application startup when
-/// <see cref="ApiKeyOptions.RunMigrationsOnStartup"/> is <see langword="true"/>.
-/// The migration is idempotent, so repeated restarts are safe.
+/// Runs the registered <see cref="IApiKeyStoreMigrator"/> at application startup when
+/// <see cref="ApiKeyOptions.RunMigrationsOnStartup"/> is <see langword="true"/>. The migrator
+/// registered in DI is whichever store provider's implementation won the <c>TryAdd</c> race —
+/// SQLite by default, or a provider package (e.g. SQL Server) registered before
+/// <c>AddZbApiKeyAuth</c>. The migration is idempotent, so repeated restarts are safe.
 /// </summary>
 internal sealed class ApiKeyMigrationHostedService(
-    SqliteAuthStoreMigrator migrator,
+    IApiKeyStoreMigrator migrator,
    IOptions<ApiKeyOptions> options) : IHostedService
 {
    /// <inheritdoc />
@@ -61,10 +61,12 @@ public static class ApiKeyServiceCollectionExtensions
                sp.GetRequiredService<IApiKeyStore>(),
                sp.GetRequiredService<IApiKeyPepperProvider>()));

-        // Migrator: singleton, constructed from the already-registered connection factory.
-        // Needed before any store operations so the schema exists.
+        // Migrator: the SQLite implementation is the default; a provider package that registers
+        // IApiKeyStoreMigrator (and the three stores) BEFORE this call displaces it — that is the
+        // whole mechanism by which AddZbApiKeyAuthSqlServer swaps the backend.
        services.TryAddSingleton(sp =>
            new SqliteAuthStoreMigrator(sp.GetRequiredService<AuthSqliteConnectionFactory>()));
+        services.TryAddSingleton<IApiKeyStoreMigrator>(sp => sp.GetRequiredService<SqliteAuthStoreMigrator>());

        // Hosted service that runs migrations on startup when ApiKeyOptions.RunMigrationsOnStartup.
        services.AddHostedService<ApiKeyMigrationHostedService>();
@@ -1,5 +1,6 @@
 using System.Globalization;
 using Microsoft.Data.Sqlite;
+using ZB.MOM.WW.Auth.Abstractions.ApiKeys;

 namespace ZB.MOM.WW.Auth.ApiKeys.Sqlite;

@@ -11,7 +12,7 @@ public sealed class AuthStoreMigrationException(string message) : InvalidOperati
 /// is safe to run repeatedly. Refuses to run against a database whose on-disk version
 /// is newer than this build supports.
 /// </summary>
-public sealed class SqliteAuthStoreMigrator(AuthSqliteConnectionFactory connectionFactory)
+public sealed class SqliteAuthStoreMigrator(AuthSqliteConnectionFactory connectionFactory) : IApiKeyStoreMigrator
 {
    /// <summary>Applies the schema migration to the auth store.</summary>
    /// <param name="cancellationToken">Cancellation token.</param>
@@ -5,6 +5,7 @@ using Microsoft.Extensions.Hosting;
 using Microsoft.Extensions.Options;
 using ZB.MOM.WW.Auth.Abstractions.ApiKeys;
 using ZB.MOM.WW.Auth.ApiKeys.DependencyInjection;
+using ZB.MOM.WW.Auth.ApiKeys.Sqlite;

 namespace ZB.MOM.WW.Auth.ApiKeys.Tests;

@@ -197,4 +198,37 @@ public class ApiKeyServiceCollectionExtensionsTests
                File.Delete(sqlitePath);
        }
    }
+
+    [Fact]
+    public void AddZbApiKeyAuth_RegistersSqliteMigratorAsIApiKeyStoreMigrator()
+    {
+        IConfiguration config = BuildConfiguration(TempSqlitePath());
+        var services = new ServiceCollection();
+
+        services.AddZbApiKeyAuth(config, ApiKeySection);
+
+        using ServiceProvider sp = services.BuildServiceProvider();
+
+        Assert.IsType<SqliteAuthStoreMigrator>(sp.GetRequiredService<IApiKeyStoreMigrator>());
+        Assert.Same(sp.GetRequiredService<SqliteAuthStoreMigrator>(), sp.GetRequiredService<IApiKeyStoreMigrator>());
+    }
+
+    [Fact]
+    public void AddZbApiKeyAuth_LeavesPreRegisteredMigratorInPlace()
+    {
+        var services = new ServiceCollection();
+        var fake = new FakeMigrator();
+        services.AddSingleton<IApiKeyStoreMigrator>(fake);
+
+        services.AddZbApiKeyAuth(BuildConfiguration(TempSqlitePath()), ApiKeySection);
+
+        using ServiceProvider sp = services.BuildServiceProvider();
+
+        Assert.Same(fake, sp.GetRequiredService<IApiKeyStoreMigrator>());
+    }
+
+    private sealed class FakeMigrator : IApiKeyStoreMigrator
+    {
+        public Task MigrateAsync(CancellationToken ct) => Task.CompletedTask;
+    }
 }