feat: Managed bypass tokens

API/Controller/Account/LoginV2.cs

@@ -4,9 +4,13 @@
 using Asp.Versioning;
 using Microsoft.AspNetCore.RateLimiting;
 using OpenShock.Common.Errors;
+using OpenShock.Common.Extensions;
+using OpenShock.Common.Models;
 using OpenShock.Common.Problems;
+using OpenShock.API.Errors;
 using OpenShock.API.Models.Response;
 using OpenShock.API.Services.Turnstile;
+using OpenShock.Common.OpenShockDb;
 
 using OpenShock.Internal.Common.Problems;
 
@@ -47,6 +51,11 @@ public async Task<IActionResult> LoginV2(
                 oauthOnly => Problem(AccountError.AccountOAuthOnly)
             );
         }
+
+        // Admin accounts must never be authenticated through a bypassed flow — the bypass exists for
+        // automated tests, not as a credential-less back door to a privileged account.
+        if (HttpContext.IsBypassed(BypassTokenType.Turnstile) && account.Roles.Contains(RoleType.Admin))
+            return Problem(TurnstileError.InvalidTurnstile);
 
         await CreateSession(account.Id, cookieDomain);
 

API/Controller/Account/PasswordResetInitiateV2.cs

@@ -5,6 +5,8 @@
 using OpenShock.API.Models.Requests;
 using OpenShock.API.Services.Turnstile;
 using OpenShock.Common.Errors;
+using OpenShock.Common.Extensions;
+using OpenShock.Common.Models;
 using OpenShock.Common.Problems;
 
 using OpenShock.Internal.Common.Problems;
@@ -37,6 +39,17 @@ public async Task<IActionResult> PasswordResetInitiateV2([FromBody] PasswordRese
         var turnstileError = await VerifyTurnstileAsync(turnstileService, body.TurnstileResponse, cancellationToken);
         if (turnstileError is not null) return turnstileError;
 
+        // Admin accounts must never be reached through a bypassed flow - the bypass exists for
+        // automated tests, not as a way to send privileged reset mail without solving Turnstile.
+        // The lookup runs only on the bypass path, so the normal path keeps its timing profile, and
+        // the response stays the generic 200 so this does not become an admin-account oracle.
+        if (HttpContext.IsBypassed(BypassTokenType.Turnstile)
+            && await _accountService.IsPrivilegedEmailAsync(body.Email, cancellationToken))
+        {
+            _logger.LogWarning("Refused a bypassed password reset for a privileged account");
+            return Ok();
+        }
+
         await _accountService.CreatePasswordResetFlowAsync(body.Email);
 
         return Ok();

API/Controller/Tokens/ReportTokens.cs

@@ -9,6 +9,9 @@
 using Microsoft.AspNetCore.RateLimiting;
 using OpenShock.API.Errors;
 using OpenShock.API.Services.Turnstile;
+using OpenShock.Common.Extensions;
+using OpenShock.Common.Models;
+using OpenShock.Common.OpenShockDb;
 using OpenShock.Common.Services.Webhook;
 
 using OpenShock.Internal.Common.Utils;
@@ -49,6 +52,10 @@ public async Task<IActionResult> ReportTokens(
             return Problem(new OpenShockProblem("InternalServerError", "Internal Server Error", HttpStatusCode.InternalServerError));
         }
 
+        // Admin accounts must never authenticate through a bypassed flow.
+        if (HttpContext.IsBypassed(BypassTokenType.Turnstile) && CurrentUser.Roles.Contains(RoleType.Admin))
+            return Problem(TurnstileError.InvalidTurnstile);
+
         var reportId = Guid.CreateVersion7();
 
         int nAffected = 0;

API/Services/Account/AccountService.cs

@@ -157,6 +157,12 @@ public Task<bool> IsEmailRegisteredAsync(string email, CancellationToken cancell
         return _db.Users.AnyAsync(u => u.Email == email, cancellationToken);
     }
 
+    public Task<bool> IsPrivilegedEmailAsync(string email, CancellationToken cancellationToken = default)
+    {
+        email = email.ToLowerInvariant();
+        return _db.Users.AnyAsync(u => u.Email == email && u.Roles.Contains(RoleType.Admin), cancellationToken);
+    }
+
     public async Task<OneOf<Success<User>, AccountWithEmailOrUsernameExists>> CreateOAuthOnlyAccountAsync(
         string email,
         string username,

API/Services/Account/IAccountService.cs

@@ -38,6 +38,12 @@ public interface IAccountService
     /// </summary>
     Task<bool> IsEmailRegisteredAsync(string email, CancellationToken cancellationToken = default);
 
+    /// <summary>
+    /// True when the email belongs to an account holding a privileged role.
+    /// Used to keep bypassed flows away from admin accounts, not for authorization decisions.
+    /// </summary>
+    Task<bool> IsPrivilegedEmailAsync(string email, CancellationToken cancellationToken = default);
+
     /// <summary>
     /// 
     /// </summary>

API/Services/Turnstile/CloudflareTurnstileService.cs

@@ -2,6 +2,8 @@
 using OneOf;
 using OneOf.Types;
 using OpenShock.API.Options;
+using OpenShock.Common.Extensions;
+using BypassTokenType = OpenShock.Common.Models.BypassTokenType;
 
 namespace OpenShock.API.Services.Turnstile;
 
@@ -12,13 +14,20 @@ public sealed class CloudflareTurnstileService : ICloudflareTurnstileService
     private readonly HttpClient _httpClient;
     private readonly TurnstileOptions _options;
     private readonly IHostEnvironment _environment;
+    private readonly IHttpContextAccessor _httpContextAccessor;
     private readonly ILogger<CloudflareTurnstileService> _logger;
 
-    public CloudflareTurnstileService(HttpClient httpClient, TurnstileOptions options, IHostEnvironment environment, ILogger<CloudflareTurnstileService> logger)
+    public CloudflareTurnstileService(
+        HttpClient httpClient,
+        TurnstileOptions options,
+        IHostEnvironment environment,
+        IHttpContextAccessor httpContextAccessor,
+        ILogger<CloudflareTurnstileService> logger)
     {
         _httpClient = httpClient;
         _options = options;
         _environment = environment;
+        _httpContextAccessor = httpContextAccessor;
         _logger = logger;
     }
 
@@ -48,6 +57,11 @@ public async Task<OneOf<Success, Error<CloudflareTurnstileError[]>>> VerifyUserR
     {
         if (!_options.Enabled) return new Success();
 
+        // An admin-set bypass secret (matched against the TURNSTILE_BYPASS_TOKEN configuration property)
+        // counts as a Turnstile pass. The match was resolved upstream by BypassTokenMiddleware.
+        if (_httpContextAccessor.HttpContext?.IsBypassed(BypassTokenType.Turnstile) == true)
+            return new Success();
+
         if (string.IsNullOrEmpty(responseToken)) return CreateError(CloudflareTurnstileError.MissingResponse);
 
         if (_environment.IsDevelopment() && responseToken == "dev-bypass")

Common/Constants/AuthConstants.cs

@@ -6,6 +6,7 @@ public static class AuthConstants
     public const string UserSessionHeaderName = "OpenShockSession";
     public const string ApiTokenHeaderName = "OpenShockToken";
     public const string HubTokenHeaderName = "DeviceToken";
+    public const string BypassTokenHeaderName = "X-OpenShock-Bypass-Token";
 
     public const int GeneratedTokenLength = 32;
     public const int ApiTokenLength = 64;

Common/Extensions/HttpContextExtensions.cs

@@ -1,10 +1,47 @@
 using System.Diagnostics.CodeAnalysis;
+using Microsoft.AspNetCore.Http;
 using OpenShock.Common.Constants;
+using OpenShock.Common.Models;
 
 namespace OpenShock.Common.Extensions;
 
 public static class HttpContextExtensions
 {
+    private static readonly object BypassedTypesItemKey = new();
+
+    public static bool TryGetBypassTokenFromHeader(this HttpContext context, [NotNullWhen(true)] out string? token)
+    {
+        ArgumentNullException.ThrowIfNull(context);
+
+        if (context.Request.Headers.TryGetValue(AuthConstants.BypassTokenHeaderName, out var value) && !string.IsNullOrEmpty(value))
+        {
+            token = value!;
+            return true;
+        }
+
+        token = null;
+        return false;
+    }
+
+    /// <summary>
+    /// Stores the set of bypass types that the header matched. Called by the bypass middleware.
+    /// </summary>
+    public static void SetBypassedTypes(this HttpContext context, BypassTokenType types)
+    {
+        ArgumentNullException.ThrowIfNull(context);
+        context.Items[BypassedTypesItemKey] = types;
+    }
+
+    /// <summary>
+    /// Returns true if the request presented a bypass token that grants <paramref name="type"/>.
+    /// </summary>
+    public static bool IsBypassed(this HttpContext context, BypassTokenType type)
+    {
+        ArgumentNullException.ThrowIfNull(context);
+        if (!context.Items.TryGetValue(BypassedTypesItemKey, out var v) || v is not BypassTokenType set) return false;
+        return (set & type) == type;
+    }
+
     private static readonly string[] TokenHeaderNames = [
         AuthConstants.ApiTokenHeaderName,
         "Open-Shock-Token",

Common/Middleware/BypassTokenMiddleware.cs

@@ -0,0 +1,75 @@
+using System.Security.Cryptography;
+using System.Text;
+using OneOf.Types;
+using OpenShock.Common.Extensions;
+using OpenShock.Common.Models;
+using OpenShock.Common.Services.Configuration;
+using Microsoft.Extensions.Logging;
+
+namespace OpenShock.Common.Middleware;
+
+/// <summary>
+/// Resolves the <c>X-OpenShock-Bypass-Token</c> header by comparing it to admin-set configuration
+/// properties (<c>TURNSTILE_BYPASS_TOKEN</c>, <c>RATE_LIMIT_BYPASS_TOKEN</c>). The matched bypass
+/// flags are stored on <see cref="HttpContext.Items"/> so downstream guards (rate limiter selectors,
+/// turnstile service) can read them synchronously.
+///
+/// Runs before <c>UseRateLimiter</c>.
+/// </summary>
+public sealed class BypassTokenMiddleware
+{
+    public const string TurnstileConfigKey = "TURNSTILE_BYPASS_TOKEN";
+    public const string RateLimitConfigKey = "RATE_LIMIT_BYPASS_TOKEN";
+
+    private readonly RequestDelegate _next;
+
+    public BypassTokenMiddleware(RequestDelegate next)
+    {
+        _next = next;
+    }
+
+    public async Task InvokeAsync(HttpContext context, IConfigurationService config, ILogger<BypassTokenMiddleware> logger)
+    {
+        if (!context.TryGetBypassTokenFromHeader(out var presented))
+        {
+            await _next(context);
+            return;
+        }
+
+        var matched = BypassTokenType.None;
+
+        if (await MatchesAsync(config, TurnstileConfigKey, presented)) matched |= BypassTokenType.Turnstile;
+        if (await MatchesAsync(config, RateLimitConfigKey, presented)) matched |= BypassTokenType.RateLimit;
+
+        if (matched != BypassTokenType.None)
+        {
+            context.SetBypassedTypes(matched);
+
+            // A credential that switches off Turnstile and rate limiting should never be used without
+            // leaving a trace. Logged at warning so it stands out in a production log, and the token
+            // itself is never written - only which protections it disabled, and for what.
+            logger.LogWarning(
+                "Bypass token accepted for {Matched} on {Method} {Path} from {RemoteIp}",
+                matched, context.Request.Method, context.Request.Path, context.Connection.RemoteIpAddress);
+        }
+        else
+        {
+            // A presented-but-unmatched token is either a stale secret or someone probing for one.
+            logger.LogWarning(
+                "Bypass token presented but matched nothing on {Method} {Path} from {RemoteIp}",
+                context.Request.Method, context.Request.Path, context.Connection.RemoteIpAddress);
+        }
+
+        await _next(context);
+    }
+
+    private static async Task<bool> MatchesAsync(IConfigurationService config, string key, string presented)
+    {
+        var result = await config.TryGetStringAsync(key);
+        return result.TryPickT0(out var configured, out _)
+               && !string.IsNullOrEmpty(configured)
+               && CryptographicOperations.FixedTimeEquals(
+                   Encoding.UTF8.GetBytes(configured),
+                   Encoding.UTF8.GetBytes(presented));
+    }
+}

Common/Models/BypassTokenType.cs

@@ -0,0 +1,9 @@
+namespace OpenShock.Common.Models;
+
+[Flags]
+public enum BypassTokenType
+{
+    None = 0,
+    Turnstile = 1 << 0,
+    RateLimit = 1 << 1
+}

Common/OpenShockMiddlewareHelper.cs

@@ -3,6 +3,7 @@
 using Microsoft.EntityFrameworkCore;
 using Microsoft.Extensions.Diagnostics.HealthChecks;
 using OpenShock.Common.HealthChecks;
+using OpenShock.Common.Middleware;
 using OpenShock.Common.OpenShockDb;
 using OpenShock.Common.Options;
 using OpenShock.Common.Redis;
@@ -113,6 +114,10 @@ exception is null
         await redisConnection.CreateIndexAsync(typeof(DevicePair));
         await redisConnection.CreateIndexAsync(typeof(LcgNode));
 
+        // Resolve the X-OpenShock-Bypass-Token header (if present) before rate limiting so the
+        // rate limiter partition selectors can honor the bypass for this same request.
+        app.UseMiddleware<BypassTokenMiddleware>();
+
         app.UseRateLimiter();
 
         app.UseOpenTelemetryPrometheusScrapingEndpoint(context =>

Common/OpenShockServiceHelper.cs

@@ -266,6 +266,14 @@ public static IServiceCollection AddOpenShockServices(this IServiceCollection se
                 return;
             }
 
+            // If the request presented the configured RATE_LIMIT_BYPASS_TOKEN, skip every limiter on it.
+            // BypassTokenMiddleware (which runs before UseRateLimiter) has already set HttpContext.Items;
+            // selectors are sync and this is just a dictionary lookup.
+            static RateLimitPartition<string>? TryBypass(HttpContext ctx)
+                => ctx.IsBypassed(Models.BypassTokenType.RateLimit)
+                    ? RateLimitPartition.GetNoLimiter("bypass-ratelimit")
+                    : null;
+
             options.OnRejected = async (context, cancellationToken) =>
             {
                 var logger = context.HttpContext.RequestServices.GetRequiredService<ILoggerFactory>()
@@ -294,6 +302,8 @@ await context.HttpContext.Response.WriteAsync("Too Many Requests. Please try aga
             // Fixed window at 10k requests allows 20k bursts if burst occurs at window boundary
             options.GlobalLimiter = PartitionedRateLimiter.Create<HttpContext, string>(context =>
             {
+                if (TryBypass(context) is { } bypassPartition) return bypassPartition;
+
                 var user = context.User;
                 var userId = user.FindFirstValue(ClaimTypes.NameIdentifier);
                 if (string.IsNullOrEmpty(userId))
@@ -329,7 +339,9 @@ await context.HttpContext.Response.WriteAsync("Too Many Requests. Please try aga
             // Authentication endpoints limiter
             options.AddPolicy("auth", context =>
             {
-                var ip = context.GetRemoteIP();
+                if (TryBypass(context) is { } bypassPartition) return bypassPartition;
+
+                var ip = context.GetRemoteIP().ToString();
                 return RateLimitPartition.GetFixedWindowLimiter(ip, _ => new FixedWindowRateLimiterOptions
                 {
                     PermitLimit = 10,
@@ -338,7 +350,8 @@ await context.HttpContext.Response.WriteAsync("Too Many Requests. Please try aga
             });
 
             // Token reporting endpoint concurrency limiter
-            options.AddPolicy("token-reporting", _ =>
+            options.AddPolicy("token-reporting", context =>
+                TryBypass(context) ??
                 RateLimitPartition.GetConcurrencyLimiter("token-reporting", _ => new ConcurrencyLimiterOptions
                 {
                     PermitLimit = 5,
@@ -347,7 +360,8 @@ await context.HttpContext.Response.WriteAsync("Too Many Requests. Please try aga
                 }));
 
             // Log fetching endpoint concurrency limiter
-            options.AddPolicy("shocker-logs", _ =>
+            options.AddPolicy("shocker-logs", context =>
+                TryBypass(context) ??
                 RateLimitPartition.GetConcurrencyLimiter("shocker-logs", _ => new ConcurrencyLimiterOptions
                 {
                     PermitLimit = 10,