feat(altcha): IAltchaDifficultyAdvisor for per-request PoW complexity

Adds an abstraction over the CreateChallengeRequest.complexity field
(already present in the proto since the original altcha module landed),
letting applications scale PoW difficulty per request based on actor
signals — repeat-offender counters, threat-intel headers, reputation
scores — without leaking those concerns into the gRPC provider.

  - new IAltchaDifficultyAdvisor in Svrnty.CQRS.Altcha.Abstractions:
    Task<uint?> GetComplexityAsync(...). null means "use the upstream
    service's configured default."

  - NullAltchaDifficultyAdvisor in Svrnty.CQRS.Altcha is the no-op
    fallback registered by AddSvrntyAltcha() via TryAddSingleton, so
    applications can replace it without ordering constraints.

  - AltchaGrpcChallengeProvider now resolves the advisor and sets
    CreateChallengeRequest.Complexity when the advisor returns a value.
    The Altcha server clamps to its configured min/max, so callers
    don't need to enforce bounds here.

No breaking changes to existing consumers — the no-op default keeps
behaviour identical when no advisor is registered.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Svrnty.CQRS.Altcha.Abstractions/IAltchaDifficultyAdvisor.cs

@@ -0,0 +1,27 @@
+namespace Svrnty.CQRS.Altcha.Abstractions;
+
+/// <summary>
+/// Resolves a per-request PoW complexity (search-space upper bound) for the
+/// next Altcha challenge the server will mint. Implementations may consult
+/// per-actor signals — repeat-offender counters, threat-intel headers,
+/// reputation scores — to scale difficulty up for suspicious actors while
+/// keeping the baseline cheap for everyone else.
+/// </summary>
+/// <remarks>
+/// The framework ships a no-op <see cref="IAltchaDifficultyAdvisor"/> that
+/// always returns <c>null</c>, meaning "use the upstream service's configured
+/// default complexity." Applications opt into adaptive difficulty by
+/// replacing the registration with their own implementation; consult request
+/// context via <see cref="Microsoft.AspNetCore.Http.IHttpContextAccessor"/>
+/// or scoped DI.
+/// </remarks>
+public interface IAltchaDifficultyAdvisor
+{
+    /// <summary>
+    /// Returns the desired <c>maxNumber</c> (PoW search-space upper bound)
+    /// for the next challenge, or <c>null</c> to defer to the upstream
+    /// service default. The Altcha server clamps to its configured min/max,
+    /// so callers don't need to enforce bounds here.
+    /// </summary>
+    Task<uint?> GetComplexityAsync(CancellationToken cancellationToken = default);
+}

Svrnty.CQRS.Altcha.Grpc/AltchaGrpcChallengeProvider.cs

@@ -14,15 +14,18 @@ public sealed class AltchaGrpcChallengeProvider : IAltchaChallengeProvider
 {
     private readonly AltchaService.AltchaServiceClient _client;
     private readonly IOptions<AltchaGrpcOptions> _options;
+    private readonly IAltchaDifficultyAdvisor _advisor;
     private readonly ILogger<AltchaGrpcChallengeProvider> _logger;
 
     public AltchaGrpcChallengeProvider(
         AltchaService.AltchaServiceClient client,
         IOptions<AltchaGrpcOptions> options,
+        IAltchaDifficultyAdvisor advisor,
         ILogger<AltchaGrpcChallengeProvider> logger)
     {
         _client = client;
         _options = options;
+        _advisor = advisor;
         _logger = logger;
     }
 
@@ -32,10 +35,18 @@ public sealed class AltchaGrpcChallengeProvider : IAltchaChallengeProvider
         var metadata = await AltchaCallCredentials.BuildMetadataAsync(opts, cancellationToken);
         var deadline = DateTime.UtcNow.Add(opts.CallTimeout);
 
+        var request = new CreateChallengeRequest();
+        var advisedComplexity = await _advisor.GetComplexityAsync(cancellationToken);
+        if (advisedComplexity is uint complexity)
+        {
+            request.Complexity = complexity;
+            _logger.LogDebug("Altcha advisor requested complexity {Complexity}", complexity);
+        }
+
         try
         {
             var response = await _client.CreateChallengeAsync(
-                new CreateChallengeRequest(),
+                request,
                 headers: metadata,
                 deadline: deadline,
                 cancellationToken: cancellationToken);

Svrnty.CQRS.Altcha/NullAltchaDifficultyAdvisor.cs

@@ -0,0 +1,15 @@
+using Svrnty.CQRS.Altcha.Abstractions;
+
+namespace Svrnty.CQRS.Altcha;
+
+/// <summary>
+/// No-op fallback registered by <c>AddSvrntyAltcha()</c>. Always returns
+/// <c>null</c>, leaving complexity at the upstream Altcha service's
+/// configured default. Applications that want adaptive difficulty
+/// replace this registration with their own implementation.
+/// </summary>
+internal sealed class NullAltchaDifficultyAdvisor : IAltchaDifficultyAdvisor
+{
+    public Task<uint?> GetComplexityAsync(CancellationToken cancellationToken = default)
+        => Task.FromResult<uint?>(null);
+}

Svrnty.CQRS.Altcha/ServiceCollectionExtensions.cs

@@ -1,6 +1,7 @@
 using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Extensions.DependencyInjection.Extensions;
 using Svrnty.CQRS.Abstractions.Security;
+using Svrnty.CQRS.Altcha.Abstractions;
 
 namespace Svrnty.CQRS.Altcha;
 
@@ -9,22 +10,27 @@ public static class ServiceCollectionExtensions
     /// <summary>
     /// Registers <see cref="AltchaAuthorizationCheck"/> as both an
     /// <see cref="ICommandAuthorizationCheck"/> and an
-    /// <see cref="IQueryAuthorizationCheck"/>. The check is a no-op until
-    /// an <see cref="Svrnty.CQRS.Altcha.Abstractions.IAltchaVerifier"/>
-    /// implementation is also registered (typically via
-    /// <c>AddSvrntyAltchaGrpcVerifier(...)</c> from
-    /// <c>Svrnty.CQRS.Altcha.Grpc</c>).
+    /// <see cref="IQueryAuthorizationCheck"/>, plus a no-op
+    /// <see cref="IAltchaDifficultyAdvisor"/> that defers to the upstream
+    /// Altcha service's configured default complexity. Applications opt
+    /// into adaptive difficulty by registering their own
+    /// <see cref="IAltchaDifficultyAdvisor"/> before or after this call —
+    /// the <c>TryAdd</c> registration here yields to any existing one.
     /// </summary>
     /// <remarks>
-    /// Idempotent for the concrete check; the multi-instance interface
-    /// registrations are added unconditionally, so callers should invoke
-    /// this exactly once per application startup.
+    /// The check is a no-op until an
+    /// <see cref="IAltchaVerifier"/> implementation is also registered
+    /// (typically via <c>AddSvrntyAltchaGrpcVerifier(...)</c> from
+    /// <c>Svrnty.CQRS.Altcha.Grpc</c>). Idempotent for the concrete check;
+    /// the multi-instance interface registrations are added unconditionally,
+    /// so callers should invoke this exactly once per application startup.
     /// </remarks>
     public static IServiceCollection AddSvrntyAltcha(this IServiceCollection services)
     {
         services.TryAddSingleton<AltchaAuthorizationCheck>();
         services.AddSingleton<ICommandAuthorizationCheck>(sp => sp.GetRequiredService<AltchaAuthorizationCheck>());
         services.AddSingleton<IQueryAuthorizationCheck>(sp => sp.GetRequiredService<AltchaAuthorizationCheck>());
+        services.TryAddSingleton<IAltchaDifficultyAdvisor, NullAltchaDifficultyAdvisor>();
         return services;
     }
 }