fix(security): finish the bearer-token design and cache role mappings (review 2026-10-21 05/U1, 05/P1)

- ManagementAuthenticator accepts Authorization: Bearer <jwt> alongside Basic on
  /management, the audit REST endpoints and the debug-stream hub. Tokens are
  validated locally (HS256 only, alg=none rejected, issuer/audience, lifetime with
  30 s skew); roles and site scope inside a valid token are authoritative for its
  lifetime, so a bearer call costs no LDAP bind and no role re-map.
- /auth/token returns expires_in + management_bearer:true, carries username, display
  name, roles and permitted sites, and answers 404 under DisableLogin.
- CLI exchanges credentials once per process (in-memory CliTokenStore), sends Bearer,
  re-exchanges once on 401 then falls back to Basic; older/login-disabled servers are
  Basic-only; bad credentials are not retried with Basic. Debug stream uses the token
  via AccessTokenProvider. SCADABRIDGE_AUTH_MODE=basic opts out.
- StartupValidator fails a Central boot on a JwtSigningKey under 32 UTF-8 bytes;
  fixed the false 'fail-fast at construction' comment. Removed the dead
  RefreshToken/RecordActivity/ShouldRefresh/IsIdleTimedOut members and the inert
  JwtRefreshThresholdMinutes; JwtExpiryMinutes now documented as the bearer lifetime
  (validated > 0).
- RoleMapper reads through a process-wide RoleMappingCache (RoleMappingCacheSeconds,
  default 30 s): one refresh loads the table plus every Deployer mapping's scope
  rules, Invalidate() drops it (generation-guarded against in-flight refreshes).
- Component-Security.md / Component-CLI.md / CLI README describe the real model
  (cookie claims ticket, bearer for CLI) instead of a cookie-embedded JWT.

src/ZB.MOM.WW.ScadaBridge.CLI/ManagementHttpClient.cs

@@ -1,12 +1,52 @@
+using System.Net;
 using System.Net.Http.Headers;
 using System.Text;
 using System.Text.Json;
 
 namespace ZB.MOM.WW.ScadaBridge.CLI;
 
+/// <summary>
+/// HTTP client for the central management surfaces (<c>POST /management</c>, the audit REST
+/// endpoints). Authenticates with a bearer token exchanged once per process at
+/// <c>POST /auth/token</c>, falling back to HTTP Basic when the server does not offer bearer
+/// tokens (review 2026-10-21 05/U1, 05/P1).
+/// </summary>
+/// <remarks>
+/// <para>
+/// <b>Bearer flow.</b> The first call a process makes for a given URL + credential pair posts
+/// the credentials to <c>/auth/token</c> (one LDAP bind) and keeps the returned JWT in memory
+/// (<see cref="CliTokenStore"/>; never persisted or logged). Every later call — from this or any
+/// other client instance in the same process — sends <c>Authorization: Bearer</c>, which the
+/// server validates without LDAP. A token nearing expiry is re-exchanged. A bearer call
+/// answered <c>401</c> re-exchanges once (unless the token was minted for that very call) and,
+/// if still refused, retries with Basic.
+/// </para>
+/// <para>
+/// <b>Basic fallback.</b> A server whose <c>/auth/token</c> is absent (404/405), disabled
+/// (login-disabled deployment, 404) or does not advertise <c>management_bearer: true</c> (an
+/// older server, whose tokens no management surface accepts) is remembered as Basic-only for
+/// the rest of the process. A transient exchange failure (5xx) uses Basic for that call only.
+/// Bad credentials (<c>401</c>) and a throttle lockout (<c>429</c>) from the exchange are
+/// returned as-is — retrying them with Basic would only add a second failed bind against the
+/// login throttle.
+/// </para>
+/// <para>
+/// <c>SCADABRIDGE_AUTH_MODE=basic</c> disables the exchange (Basic on every call).
+/// </para>
+/// </remarks>
 public class ManagementHttpClient : IDisposable
 {
+    /// <summary>Environment variable selecting the auth mode: <c>token</c> (default) or <c>basic</c>.</summary>
+    public const string AuthModeEnvVar = "SCADABRIDGE_AUTH_MODE";
+
+    /// <summary>Re-exchange a token this long before its stated expiry.</summary>
+    internal static readonly TimeSpan TokenRefreshMargin = TimeSpan.FromSeconds(60);
+
     private readonly HttpClient _httpClient;
+    private readonly AuthenticationHeaderValue _basic;
+    private readonly string _username;
+    private readonly string _password;
+    private readonly CliTokenStore.Session? _session;
 
     /// <summary>
     /// Default bound on the CONNECT phase only (30 s) — how long a TCP/TLS
@@ -81,10 +121,19 @@ public class ManagementHttpClient : IDisposable
             {
                 Timeout = Timeout.InfiniteTimeSpan
             },
-            baseUrl, username, password)
+            baseUrl, username, password,
+            IsBasicAuthModeForced() ? null : CliTokenStore.Shared)
     {
     }
 
+    /// <summary>
+    /// True when <see cref="AuthModeEnvVar"/> is <c>basic</c>, which disables the token
+    /// exchange for the process.
+    /// </summary>
+    /// <returns>Whether HTTP Basic is forced on every call.</returns>
+    internal static bool IsBasicAuthModeForced() =>
+        string.Equals(Environment.GetEnvironmentVariable(AuthModeEnvVar)?.Trim(), "basic", StringComparison.OrdinalIgnoreCase);
+
     /// <summary>
     /// Test-only constructor that accepts a pre-built <see cref="HttpClient"/> (typically
     /// over a stub <see cref="HttpMessageHandler"/>) so the request/response handling can
@@ -94,16 +143,217 @@ public class ManagementHttpClient : IDisposable
     /// <param name="baseUrl">The base URL for the management API.</param>
     /// <param name="username">The username for HTTP Basic authentication.</param>
     /// <param name="password">The password for HTTP Basic authentication.</param>
-    internal ManagementHttpClient(HttpClient httpClient, string baseUrl, string username, string password)
+    /// <param name="tokenStore">
+    /// Bearer-token store to exchange credentials through; <see langword="null"/> (the default)
+    /// sends HTTP Basic on every call, which keeps stub-handler tests to a single request.
+    /// </param>
+    internal ManagementHttpClient(HttpClient httpClient, string baseUrl, string username, string password, CliTokenStore? tokenStore = null)
     {
         _httpClient = httpClient;
         // Test seam: exposes the constructed HttpClient's effective Timeout
         // without requiring reflection.
         EffectiveTimeout = httpClient.Timeout;
         _httpClient.BaseAddress = new Uri(baseUrl.TrimEnd('/') + "/");
-        var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{username}:{password}"));
-        _httpClient.DefaultRequestHeaders.Authorization =
-            new AuthenticationHeaderValue("Basic", credentials);
+        _username = username;
+        _password = password;
+        _basic = new AuthenticationHeaderValue(
+            "Basic", Convert.ToBase64String(Encoding.UTF8.GetBytes($"{username}:{password}")));
+        _session = tokenStore?.For(baseUrl, username, password);
+    }
+
+    /// <summary>The HTTP Basic credential value (base64 <c>user:password</c>), for the debug-stream hub fallback.</summary>
+    internal string BasicCredentials => _basic.Parameter!;
+
+    /// <summary>Outcome of <see cref="TryGetBearerTokenAsync"/>.</summary>
+    /// <param name="Token">The bearer token, or <see langword="null"/> when the caller should use Basic.</param>
+    /// <param name="Failure">A credential/throttle failure from the exchange that must be reported, not retried with Basic.</param>
+    internal readonly record struct BearerResult(string? Token, ManagementResponse? Failure);
+
+    /// <summary>
+    /// Returns a usable bearer token for this client's credentials, exchanging at
+    /// <c>/auth/token</c> if none is cached — used by the debug-stream hub, which cannot replay a
+    /// rejected handshake. <see cref="BearerResult.Token"/> is null when the caller should fall
+    /// back to Basic; <see cref="BearerResult.Failure"/> is set for bad credentials or a lockout.
+    /// </summary>
+    /// <param name="cancellationToken">Cancels the exchange.</param>
+    /// <returns>The token, a fall-back-to-Basic signal, or a failure to report.</returns>
+    internal async Task<BearerResult> TryGetBearerTokenAsync(CancellationToken cancellationToken)
+    {
+        var auth = await AcquireAuthAsync(forceExchange: false, cancellationToken).ConfigureAwait(false);
+        if (auth.Failure is not null)
+        {
+            var failure = await ToManagementResponseAsync(auth.Failure, cancellationToken).ConfigureAwait(false);
+            auth.Failure.Dispose();
+            return new BearerResult(null, failure);
+        }
+
+        return new BearerResult(auth.Header.Scheme == "Bearer" ? auth.Header.Parameter : null, null);
+    }
+
+    private readonly record struct AuthChoice(AuthenticationHeaderValue Header, bool FreshlyMinted, HttpResponseMessage? Failure);
+
+    /// <summary>
+    /// Picks the Authorization header for the next request: the cached bearer token, a freshly
+    /// exchanged one, or Basic. A non-null <see cref="AuthChoice.Failure"/> is the exchange's own
+    /// 401/429 response, to be surfaced to the caller as-is.
+    /// </summary>
+    private async Task<AuthChoice> AcquireAuthAsync(bool forceExchange, CancellationToken ct)
+    {
+        var session = _session;
+        if (session is null || session.BasicOnly)
+            return new AuthChoice(_basic, false, null);
+
+        try
+        {
+            await session.Gate.WaitAsync(ct).ConfigureAwait(false);
+        }
+        catch (OperationCanceledException ex) when (ex is not TaskCanceledException)
+        {
+            // Callers map TaskCanceledException to their TIMEOUT result, as for the send itself.
+            throw new TaskCanceledException(ex.Message, ex, ct);
+        }
+
+        try
+        {
+            if (session.BasicOnly)
+                return new AuthChoice(_basic, false, null);
+            if (!forceExchange && session.HasUsableToken(DateTimeOffset.UtcNow))
+                return new AuthChoice(new AuthenticationHeaderValue("Bearer", session.Token), false, null);
+
+            session.Token = null;
+            using var form = new FormUrlEncodedContent(
+            [
+                new KeyValuePair<string, string>("username", _username),
+                new KeyValuePair<string, string>("password", _password),
+            ]);
+            var response = await _httpClient.PostAsync("auth/token", form, ct).ConfigureAwait(false);
+
+            if (response.StatusCode is HttpStatusCode.Unauthorized or HttpStatusCode.TooManyRequests)
+                return new AuthChoice(_basic, false, response);
+
+            using (response)
+            {
+                if (response.StatusCode is HttpStatusCode.NotFound or HttpStatusCode.MethodNotAllowed)
+                {
+                    session.BasicOnly = true;
+                    return new AuthChoice(_basic, false, null);
+                }
+
+                if (!response.IsSuccessStatusCode)
+                    return new AuthChoice(_basic, false, null); // transient: Basic for this call only
+
+                var body = await response.Content.ReadAsStringAsync(ct).ConfigureAwait(false);
+                if (!TryParseToken(body, out var token, out var lifetime))
+                {
+                    // An older server: /auth/token exists but no management surface takes its tokens.
+                    session.BasicOnly = true;
+                    return new AuthChoice(_basic, false, null);
+                }
+
+                session.Token = token;
+                var margin = lifetime > TokenRefreshMargin * 2 ? TokenRefreshMargin : TimeSpan.Zero;
+                session.RefreshAfter = DateTimeOffset.UtcNow + lifetime - margin;
+                return new AuthChoice(new AuthenticationHeaderValue("Bearer", token), true, null);
+            }
+        }
+        finally
+        {
+            session.Gate.Release();
+        }
+    }
+
+    private static bool TryParseToken(string body, out string token, out TimeSpan lifetime)
+    {
+        token = string.Empty;
+        lifetime = TimeSpan.FromMinutes(15);
+        try
+        {
+            using var doc = JsonDocument.Parse(body);
+            var root = doc.RootElement;
+            if (root.ValueKind != JsonValueKind.Object
+                || !root.TryGetProperty("management_bearer", out var bearer) || bearer.ValueKind != JsonValueKind.True
+                || !root.TryGetProperty("access_token", out var accessToken) || accessToken.ValueKind != JsonValueKind.String
+                || string.IsNullOrWhiteSpace(accessToken.GetString()))
+            {
+                return false;
+            }
+
+            token = accessToken.GetString()!;
+            if (root.TryGetProperty("expires_in", out var expiresIn) && expiresIn.TryGetInt32(out var seconds) && seconds > 0)
+                lifetime = TimeSpan.FromSeconds(seconds);
+            return true;
+        }
+        catch (JsonException)
+        {
+            return false;
+        }
+    }
+
+    /// <summary>
+    /// Sends a request built by <paramref name="buildRequest"/> with the chosen credentials,
+    /// applying the bearer refresh-once-then-Basic policy on a 401.
+    /// </summary>
+    private async Task<HttpResponseMessage> SendAuthenticatedAsync(
+        Func<HttpRequestMessage> buildRequest, HttpCompletionOption completion, CancellationToken ct)
+    {
+        var auth = await AcquireAuthAsync(forceExchange: false, ct).ConfigureAwait(false);
+        if (auth.Failure is not null)
+            return auth.Failure;
+
+        var response = await SendWithAsync(buildRequest, auth.Header, completion, ct).ConfigureAwait(false);
+        if (response.StatusCode != HttpStatusCode.Unauthorized || auth.Header.Scheme != "Bearer")
+            return response;
+
+        // The server refused our bearer token. A token cached from an earlier call may simply be
+        // stale (expired, signing key rotated): re-exchange once and retry.
+        if (!auth.FreshlyMinted)
+        {
+            response.Dispose();
+            auth = await AcquireAuthAsync(forceExchange: true, ct).ConfigureAwait(false);
+            if (auth.Failure is not null)
+                return auth.Failure;
+            response = await SendWithAsync(buildRequest, auth.Header, completion, ct).ConfigureAwait(false);
+            if (response.StatusCode != HttpStatusCode.Unauthorized || auth.Header.Scheme != "Bearer")
+                return response;
+        }
+
+        // A token minted moments ago is still refused (e.g. the node that answered does not share
+        // the signing key): fall back to Basic and stop exchanging for this process.
+        response.Dispose();
+        response = await SendWithAsync(buildRequest, _basic, completion, ct).ConfigureAwait(false);
+        if (response.StatusCode != HttpStatusCode.Unauthorized && _session is not null)
+            _session.BasicOnly = true;
+        return response;
+    }
+
+    private Task<HttpResponseMessage> SendWithAsync(
+        Func<HttpRequestMessage> buildRequest, AuthenticationHeaderValue header, HttpCompletionOption completion, CancellationToken ct)
+    {
+        var request = buildRequest();
+        request.Headers.Authorization = header;
+        return _httpClient.SendAsync(request, completion, ct);
+    }
+
+    private static async Task<ManagementResponse> ToManagementResponseAsync(HttpResponseMessage response, CancellationToken ct)
+    {
+        var responseBody = await response.Content.ReadAsStringAsync(ct).ConfigureAwait(false);
+        if (response.IsSuccessStatusCode)
+            return new ManagementResponse((int)response.StatusCode, responseBody, null, null);
+
+        string? error;
+        string? code = null;
+        try
+        {
+            using var doc = JsonDocument.Parse(responseBody);
+            error = doc.RootElement.TryGetProperty("error", out var e) ? e.GetString() : responseBody;
+            code = doc.RootElement.TryGetProperty("code", out var c) ? c.GetString() : null;
+        }
+        catch
+        {
+            error = responseBody;
+        }
+
+        return new ManagementResponse((int)response.StatusCode, null, error, code);
     }
 
     /// <summary>
@@ -120,12 +370,15 @@ public class ManagementHttpClient : IDisposable
         var body = JsonSerializer.Serialize(new { command = commandName, payload },
             new JsonSerializerOptions { PropertyNamingPolicy = JsonNamingPolicy.CamelCase });
 
-        var content = new StringContent(body, Encoding.UTF8, "application/json");
-
         HttpResponseMessage httpResponse;
         try
         {
-            httpResponse = await _httpClient.PostAsync("management", content, cts.Token);
+            httpResponse = await SendAuthenticatedAsync(
+                () => new HttpRequestMessage(HttpMethod.Post, "management")
+                {
+                    Content = new StringContent(body, Encoding.UTF8, "application/json"),
+                },
+                HttpCompletionOption.ResponseContentRead, cts.Token);
         }
         catch (TaskCanceledException)
         {
@@ -165,7 +418,7 @@ public class ManagementHttpClient : IDisposable
     /// <c>/api/audit/query</c> endpoint) and returns the
     /// response body. Unlike <see cref="SendCommandAsync"/>, this does not wrap the call
     /// in the <c>POST /management</c> command envelope — the audit endpoints are plain
-    /// REST resources. Authentication (HTTP Basic) and the base address are shared.
+    /// REST resources. Authentication (bearer token or HTTP Basic) and the base address are shared.
     /// </summary>
     /// <param name="relativePath">Path relative to the base URL, with query string.</param>
     /// <param name="timeout">The request timeout.</param>
@@ -177,7 +430,9 @@ public class ManagementHttpClient : IDisposable
         HttpResponseMessage httpResponse;
         try
         {
-            httpResponse = await _httpClient.GetAsync(relativePath, cts.Token);
+            httpResponse = await SendAuthenticatedAsync(
+                () => new HttpRequestMessage(HttpMethod.Get, relativePath),
+                HttpCompletionOption.ResponseContentRead, cts.Token);
         }
         catch (TaskCanceledException)
         {
@@ -216,7 +471,7 @@ public class ManagementHttpClient : IDisposable
     /// maintenance endpoints) with a JSON body and returns the response. Unlike
     /// <see cref="SendCommandAsync"/>, this does not wrap the call in the
     /// <c>POST /management</c> command envelope — these are plain REST resources.
-    /// Authentication (HTTP Basic) and the base address are shared.
+    /// Authentication (bearer token or HTTP Basic) and the base address are shared.
     /// </summary>
     /// <param name="relativePath">Path relative to the base URL.</param>
     /// <param name="body">The JSON body to send, or <c>null</c> for an empty body.</param>
@@ -226,12 +481,15 @@ public class ManagementHttpClient : IDisposable
     {
         using var cts = new CancellationTokenSource(timeout);
 
-        var content = new StringContent(body ?? "{}", Encoding.UTF8, "application/json");
-
         HttpResponseMessage httpResponse;
         try
         {
-            httpResponse = await _httpClient.PostAsync(relativePath, content, cts.Token);
+            httpResponse = await SendAuthenticatedAsync(
+                () => new HttpRequestMessage(HttpMethod.Post, relativePath)
+                {
+                    Content = new StringContent(body ?? "{}", Encoding.UTF8, "application/json"),
+                },
+                HttpCompletionOption.ResponseContentRead, cts.Token);
         }
         catch (TaskCanceledException)
         {
@@ -276,7 +534,9 @@ public class ManagementHttpClient : IDisposable
     /// <param name="cancellationToken">A cancellation token that can be used to cancel the operation.</param>
     /// <returns>The raw HTTP response message for streaming.</returns>
     public async Task<HttpResponseMessage> SendGetStreamAsync(string relativePath, CancellationToken cancellationToken)
-        => await _httpClient.GetAsync(relativePath, HttpCompletionOption.ResponseHeadersRead, cancellationToken);
+        => await SendAuthenticatedAsync(
+            () => new HttpRequestMessage(HttpMethod.Get, relativePath),
+            HttpCompletionOption.ResponseHeadersRead, cancellationToken);
 
     /// <summary>
     /// Disposes the underlying HTTP client.