[ADR-168] Wire JWT Bearer auth via Cognito; add CognitoTokenService and auth API tests

- CompiledLayoutService: add JWT Bearer authentication backed by AWS Cognito.
  GET /layouts/compiled/active now requires a valid bearer token; GET /health
  remains unauthenticated. The sub claim is extracted as userId.
  CognitoSettings reads Authority and Audience from appsettings/env vars.

- Client app: add BackendSettings, ICognitoTokenService, CognitoTokenService.
  CognitoTokenService acquires and caches tokens via the OAuth2 Client Credentials
  flow (lazy acquire, 60-second expiry buffer). Log messages in range 1600-1699.

- API tests: add TestJwtAuthority (local OIDC/JWKS server) so auth can be tested
  end-to-end without a real Cognito user pool. ServiceFixture now starts the
  authority first and configures Cognito__Authority on the service process.
  CommonSteps updated to use Reqnroll context injection (ServiceContext) for
  shared fixture state. AuthenticationEndpoints.feature covers 401 for no-auth
  and expired tokens, 200 for valid JWT, and unauthenticated /health access.

- Docs: _doc_Auth.md documents Cognito setup for local dev, client credentials
  config, editor Authorization Code flow, and the test JWT authority pattern.

https://claude.ai/code/session_01LLWQBraEp7n7uLVy7M4PFp

Author: claude

Directory.Packages.props

@@ -30,6 +30,8 @@
     <PackageVersion Include="Microsoft.VisualStudio.Threading" Version="17.14.15" />
   </ItemGroup>
   <ItemGroup Label="Test-Only Packages">
+    <!-- JWT token creation for API integration tests -->
+    <PackageVersion Include="System.IdentityModel.Tokens.Jwt" Version="8.9.0" />
     <!-- Test Frameworks -->
     <PackageVersion Include="MSTest" Version="3.1.1" />
     <PackageVersion Include="MSTest.TestAdapter" Version="3.1.1" />

docker-compose.yml

@@ -10,6 +10,10 @@ services:
     environment:
       - ASPNETCORE_ENVIRONMENT=Development
       - ASPNETCORE_URLS=http://+:8080
+      # Set Cognito dev user pool values here or via a .env file.
+      # See _doc_Auth.md for Cognito dev user pool setup instructions.
+      - Cognito__Authority=${COGNITO_AUTHORITY:-}
+      - Cognito__Audience=${COGNITO_AUDIENCE:-}
     networks:
       - backend
 

src/AdaptiveRemote.App/AppHostBuilderExtensions.cs

@@ -15,6 +15,7 @@ public static IHostBuilder ConfigureApp(this IHostBuilder hostBuilder)
             .AddTiVoSupport()
             .AddConversationSystem()
             .AddSystemWrapperServices()
+            .AddBackendSupport()
             .OptionallyAddTestHookEndpoint();
 
     public static IHostBuilder ConfigureAppSettings(this IHostBuilder hostBuilder, string[] args)

src/AdaptiveRemote.App/Configuration/BackendHostBuilderExtensions.cs

@@ -0,0 +1,20 @@
+using AdaptiveRemote.Services.Backend;
+using Microsoft.Extensions.Configuration;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Hosting;
+
+namespace AdaptiveRemote.Configuration;
+
+internal static class BackendHostBuilderExtensions
+{
+    public static IHostBuilder AddBackendSupport(this IHostBuilder builder)
+        => builder.ConfigureServices((context, services) =>
+            services.AddBackendServices(context.Configuration));
+
+    private static IServiceCollection AddBackendServices(
+        this IServiceCollection services,
+        IConfiguration configuration)
+        => services
+            .Configure<BackendSettings>(configuration.GetSection(SettingsKeys.Backend))
+            .AddSingleton<ICognitoTokenService, CognitoTokenService>();
+}

src/AdaptiveRemote.App/Configuration/SettingsKeys.cs

@@ -41,4 +41,9 @@ internal class SettingsKeys
     /// Configuration section for <see cref="Services.Broadlink.IRDataSettings"/> IR command payloads.
     /// </summary>
     public const string IRData = "irdata";
+
+    /// <summary>
+    /// Configuration section for <see cref="Services.Backend.BackendSettings"/> backend service settings.
+    /// </summary>
+    public const string Backend = "backend";
 }

src/AdaptiveRemote.App/Logging/MessageLogger.cs

@@ -346,4 +346,15 @@ public MessageLogger(ILogger logger)
 
     [LoggerMessage(EventId = 1516, Level = LogLevel.Information, Message = "Registering test service {ServiceName} implementing {ContractType} in DI container")]
     public partial void TestEndpointHooksService_RegisteringTestServiceInDI(string serviceName, string contractType);
+
+    // 1600–1699: CognitoTokenService
+
+    [LoggerMessage(EventId = 1600, Level = LogLevel.Information, Message = "Acquiring Cognito access token via Client Credentials flow")]
+    public partial void CognitoTokenService_AcquiringToken();
+
+    [LoggerMessage(EventId = 1601, Level = LogLevel.Information, Message = "Cognito access token acquired successfully")]
+    public partial void CognitoTokenService_TokenAcquired();
+
+    [LoggerMessage(EventId = 1602, Level = LogLevel.Error, Message = "Failed to acquire Cognito access token")]
+    public partial void CognitoTokenService_AcquireTokenFailed(Exception exception);
 }

src/AdaptiveRemote.App/Services/Backend/BackendSettings.cs

@@ -0,0 +1,52 @@
+namespace AdaptiveRemote.Services.Backend;
+
+/// <summary>
+/// Configuration for the AdaptiveRemote backend services.
+/// Maps to the "backend" section in appsettings.json.
+/// </summary>
+public class BackendSettings
+{
+    /// <summary>
+    /// Base URL of the backend API (e.g. https://api.adaptiveremote.example.com for
+    /// production, or http://localhost:8080 for local development).
+    /// </summary>
+    public string BaseUrl { get; set; } = string.Empty;
+
+    /// <summary>
+    /// Cognito OAuth2 client credentials for the client application.
+    /// </summary>
+    public CognitoClientSettings Cognito { get; set; } = new();
+}
+
+/// <summary>
+/// AWS Cognito Client Credentials flow settings for the client application.
+/// The client application authenticates as a machine client — no interactive login occurs.
+/// Sensitive values (ClientSecret) should be stored in user secrets or environment
+/// variables, not checked in to source control.
+/// </summary>
+public class CognitoClientSettings
+{
+    /// <summary>
+    /// The Cognito user pool authority URL, e.g.
+    /// https://cognito-idp.{region}.amazonaws.com/{userPoolId}
+    /// Used to discover the token endpoint via OIDC configuration.
+    /// </summary>
+    public string Authority { get; set; } = string.Empty;
+
+    /// <summary>
+    /// The OAuth2 client ID registered in the Cognito user pool for the client application.
+    /// </summary>
+    public string ClientId { get; set; } = string.Empty;
+
+    /// <summary>
+    /// The OAuth2 client secret. Store in user secrets or environment variables —
+    /// never commit to source control.
+    /// </summary>
+    public string ClientSecret { get; set; } = string.Empty;
+
+    /// <summary>
+    /// OAuth2 scope(s) to request, space-separated (e.g. "adaptiveremote/layouts.read").
+    /// Leave empty to omit the scope parameter.
+    /// </summary>
+    public string? Scope { get; set; }
+}

src/AdaptiveRemote.App/Services/Backend/CognitoTokenService.cs

@@ -0,0 +1,134 @@
+using System.Net.Http;
+using System.Text.Json;
+using AdaptiveRemote.Logging;
+using Microsoft.Extensions.Logging;
+using Microsoft.Extensions.Options;
+
+namespace AdaptiveRemote.Services.Backend;
+
+/// <summary>
+/// Acquires and caches OAuth2 access tokens from AWS Cognito using the
+/// Client Credentials flow. Token refresh is lazy: the cached token is
+/// returned until it is within <see cref="ExpiryBuffer"/> of expiring,
+/// at which point a new token is acquired.
+/// </summary>
+internal sealed class CognitoTokenService : ICognitoTokenService, IDisposable
+{
+    // Refresh the token this many seconds before it actually expires.
+    private static readonly TimeSpan ExpiryBuffer = TimeSpan.FromSeconds(60);
+
+    private readonly BackendSettings _settings;
+    private readonly HttpClient _httpClient;
+    private readonly MessageLogger _log;
+
+    private string? _cachedToken;
+    private DateTimeOffset _tokenExpiry = DateTimeOffset.MinValue;
+    private string? _tokenEndpoint;
+    private readonly SemaphoreSlim _lock = new(1, 1);
+
+    public CognitoTokenService(
+        IOptions<BackendSettings> settings,
+        ILogger<CognitoTokenService> logger)
+    {
+        _settings = settings.Value;
+        _httpClient = new HttpClient();
+        _log = new MessageLogger(logger);
+    }
+
+    public async Task<string> GetAccessTokenAsync(CancellationToken cancellationToken)
+    {
+        await _lock.WaitAsync(cancellationToken);
+        try
+        {
+            if (_cachedToken is not null && DateTimeOffset.UtcNow < _tokenExpiry - ExpiryBuffer)
+            {
+                return _cachedToken;
+            }
+
+            _log.CognitoTokenService_AcquiringToken();
+            try
+            {
+                string endpoint = await GetTokenEndpointAsync(cancellationToken);
+                (_cachedToken, _tokenExpiry) = await AcquireTokenAsync(endpoint, cancellationToken);
+                _log.CognitoTokenService_TokenAcquired();
+                return _cachedToken;
+            }
+            catch (Exception ex)
+            {
+                _log.CognitoTokenService_AcquireTokenFailed(ex);
+                throw;
+            }
+        }
+        finally
+        {
+            _lock.Release();
+        }
+    }
+
+    private async Task<string> GetTokenEndpointAsync(CancellationToken cancellationToken)
+    {
+        if (_tokenEndpoint is not null)
+        {
+            return _tokenEndpoint;
+        }
+
+        CognitoClientSettings cognito = _settings.Cognito;
+        string discoveryUrl = $"{cognito.Authority.TrimEnd('/')}/.well-known/openid-configuration";
+
+        using HttpResponseMessage discoveryResponse =
+            await _httpClient.GetAsync(discoveryUrl, cancellationToken);
+
+        discoveryResponse.EnsureSuccessStatusCode();
+
+        string json = await discoveryResponse.Content.ReadAsStringAsync(cancellationToken);
+        using JsonDocument doc = JsonDocument.Parse(json);
+        _tokenEndpoint = doc.RootElement.GetProperty("token_endpoint").GetString()
+            ?? throw new InvalidOperationException(
+                "token_endpoint not found in OIDC discovery document");
+
+        return _tokenEndpoint;
+    }
+
+    private async Task<(string Token, DateTimeOffset Expiry)> AcquireTokenAsync(
+        string endpoint,
+        CancellationToken cancellationToken)
+    {
+        CognitoClientSettings cognito = _settings.Cognito;
+
+        List<KeyValuePair<string, string>> parameters =
+        [
+            new("grant_type", "client_credentials"),
+            new("client_id", cognito.ClientId),
+            new("client_secret", cognito.ClientSecret),
+        ];
+
+        if (!string.IsNullOrEmpty(cognito.Scope))
+        {
+            parameters.Add(new("scope", cognito.Scope));
+        }
+
+        using FormUrlEncodedContent content = new(parameters);
+        using HttpResponseMessage response =
+            await _httpClient.PostAsync(endpoint, content, cancellationToken);
+
+        response.EnsureSuccessStatusCode();
+
+        string json = await response.Content.ReadAsStringAsync(cancellationToken);
+        using JsonDocument doc = JsonDocument.Parse(json);
+
+        string accessToken = doc.RootElement.GetProperty("access_token").GetString()
+            ?? throw new InvalidOperationException("access_token not found in token response");
+
+        int expiresIn = doc.RootElement.TryGetProperty("expires_in", out JsonElement expiresInElement)
+            ? expiresInElement.GetInt32()
+            : 3600;
+
+        return (accessToken, DateTimeOffset.UtcNow.AddSeconds(expiresIn));
+    }
+
+    public void Dispose()
+    {
+        _httpClient.Dispose();
+        _lock.Dispose();
+    }
+}

src/AdaptiveRemote.App/Services/Backend/ICognitoTokenService.cs

@@ -0,0 +1,15 @@
+namespace AdaptiveRemote.Services.Backend;
+
+/// <summary>
+/// Acquires and caches OAuth2 access tokens from AWS Cognito using the
+/// Client Credentials flow. The client application calls this to obtain a
+/// bearer token before making requests to backend services.
+/// </summary>
+public interface ICognitoTokenService
+{
+    /// <summary>
+    /// Returns a valid access token, acquiring or refreshing it from Cognito
+    /// as needed. The returned token is safe to use as a Bearer token immediately.
+    /// </summary>
+    Task<string> GetAccessTokenAsync(CancellationToken cancellationToken);
+}

src/AdaptiveRemote.Backend.CompiledLayoutService/Configuration/CognitoSettings.cs

@@ -0,0 +1,19 @@
+namespace AdaptiveRemote.Backend.CompiledLayoutService.Configuration;
+
+/// <summary>
+/// Configuration for AWS Cognito JWT validation.
+/// Maps to the "Cognito" section in appsettings.json.
+/// </summary>
+public class CognitoSettings
+{
+    /// <summary>
+    /// The Cognito user pool authority URL, e.g.
+    /// https://cognito-idp.{region}.amazonaws.com/{userPoolId}
+    /// </summary>
+    public string Authority { get; set; } = string.Empty;
+
+    /// <summary>
+    /// The OAuth2 audience (app client ID). If empty, audience validation is skipped.
+    /// </summary>
+    public string? Audience { get; set; }
+}