From 07e287f3c4560b5d6a4fcf960b7296c285fc6e2a Mon Sep 17 00:00:00 2001
From: Benjamin Michaelis <git@relay.benjamin.michaelis.net>
Date: Wed, 13 May 2026 21:13:11 -0700
Subject: [PATCH 1/9] security: fix rate limiter partition key, trusted proxy
 config, and misleading 429 captcha signal

F3: Replace Identity.Name (mutable display name) with ClaimTypes.NameIdentifier
(stable user ID) as the ChatEndpoint rate limiter partition key, matching the
partition strategy used by the global and MCP rate limiters.

F4: Replace unconditional KnownProxies/KnownIPNetworks.Clear() with a
config-driven trusted-proxy allowlist (ForwardedHeaders:TrustedProxyCidrs).
When no CIDRs are configured the behaviour is unchanged (all forwarded headers
trusted), but production deployments can now lock this down to their Azure
Container Apps ingress CIDR to prevent X-Forwarded-For spoofing and
IP-based rate-limit bypass.

F7: Remove requiresCaptcha=true from the 429 rate-limit response body.
The hCaptcha infrastructure exists (ICaptchaService, CaptchaOptions) but
chat requests do not yet validate the CaptchaResponse token server-side,
so advertising the field as a gate control was misleading. Updated the
CaptchaResponse comment to clarify its pending integration status.
---
 .../Controllers/ChatMessageRequest.cs         |  2 +-
 EssentialCSharp.Web/Program.cs                | 55 +++++++++++--------
 EssentialCSharp.Web/appsettings.json          |  3 +
 3 files changed, 37 insertions(+), 23 deletions(-)

diff --git a/EssentialCSharp.Web/Controllers/ChatMessageRequest.cs b/EssentialCSharp.Web/Controllers/ChatMessageRequest.cs
index c797febd..817cbecc 100644
--- a/EssentialCSharp.Web/Controllers/ChatMessageRequest.cs
+++ b/EssentialCSharp.Web/Controllers/ChatMessageRequest.cs
@@ -10,5 +10,5 @@ public class ChatMessageRequest
     [StringLength(200)]
     public string? PreviousResponseId { get; set; }
     public bool EnableContextualSearch { get; set; } = true;
-    public string? CaptchaResponse { get; set; } // For future captcha implementation
+    public string? CaptchaResponse { get; set; } // hCaptcha token; validated server-side when chat captcha enforcement is wired up
 }
diff --git a/EssentialCSharp.Web/Program.cs b/EssentialCSharp.Web/Program.cs
index 10829c7a..9855f83d 100644
--- a/EssentialCSharp.Web/Program.cs
+++ b/EssentialCSharp.Web/Program.cs
@@ -112,11 +112,23 @@ private static void Main(string[] args)
             options.ForwardedHeaders =
                 ForwardedHeaders.XForwardedFor | ForwardedHeaders.XForwardedProto;
 
-            // Only loopback proxies are allowed by default.
-            // Clear that restriction because forwarders are enabled by explicit 
-            // configuration.
             options.KnownIPNetworks.Clear();
             options.KnownProxies.Clear();
+
+            // Restrict trusted proxy sources to configured CIDRs.
+            // SECURITY: Set ForwardedHeaders:TrustedProxyCidrs in production to your
+            // load-balancer IP range (e.g., the Azure Container Apps ingress CIDR) to
+            // prevent X-Forwarded-For spoofing. Without this, any client can fabricate
+            // a forwarded IP and bypass IP-partitioned rate limits.
+            var trustedCidrs = builder.Configuration
+                .GetSection("ForwardedHeaders:TrustedProxyCidrs")
+                .Get<string[]>() ?? [];
+
+            foreach (var cidr in trustedCidrs)
+            {
+                if (System.Net.IPNetwork.TryParse(cidr, out var network))
+                    options.KnownIPNetworks.Add(network);
+            }
         });
 
         ConfigurationManager configuration = builder.Configuration;
@@ -326,7 +338,7 @@ private static void Main(string[] args)
             {
                 // Partitioned per-user (when authenticated) or per-IP (anonymous)
                 var partitionKey = httpContext.User.Identity?.IsAuthenticated == true
-                    ? $"chat-user:{httpContext.User.Identity.Name ?? "unknown-user"}"
+                    ? $"chat-user:{httpContext.User.FindFirstValue(ClaimTypes.NameIdentifier) ?? "unknown-user"}"
                     : $"chat-ip:{httpContext.Connection.RemoteIpAddress?.ToString() ?? "unknown-ip"}";
 
                 return RateLimitPartition.GetFixedWindowLimiter(
@@ -363,7 +375,6 @@ private static void Main(string[] args)
                     Dictionary<string, object> errorResponse = new()
                     {
                         ["error"] = "Rate limit exceeded. Please wait before sending another message.",
-                        ["requiresCaptcha"] = true,
                         ["statusCode"] = 429
                     };
                     if (retryAfterSeconds is int retryAfter)
@@ -511,7 +522,7 @@ await McpJsonRpcResponseWriter.WriteErrorAsync(
         }
         app.UseStaticFiles();
 
-        app.UseRouting();
+        app.UseRouting();
 
         app.UseWhen(
             context => context.Request.Path.StartsWithSegments("/mcp"),
@@ -542,10 +553,10 @@ await McpJsonRpcResponseWriter.WriteErrorAsync(
                 await next(context);
             }));
 
-        app.UseRateLimiter();
-
-        app.UseAuthorization();
-        app.UseOutputCache();
+        app.UseRateLimiter();
+
+        app.UseAuthorization();
+        app.UseOutputCache();
 
         app.UseMiddleware<ReferralMiddleware>();
 
@@ -584,13 +595,13 @@ await McpJsonRpcResponseWriter.WriteErrorAsync(
         try
         {
             SitemapXmlHelpers.EnsureSitemapHealthy(siteMappingService.SiteMappings.ToList());
-            LogSitemapValidationSucceeded(logger);
-        }
-        catch (Exception ex)
-        {
-            LogSitemapValidationFailed(logger, ex);
-            // Continue startup even if sitemap validation fails
-        }
+            LogSitemapValidationSucceeded(logger);
+        }
+        catch (Exception ex)
+        {
+            LogSitemapValidationFailed(logger, ex);
+            // Continue startup even if sitemap validation fails
+        }
 
         app.Run();
     }
@@ -604,11 +615,11 @@ private static bool IsMcpTransportRequest(HttpRequest request) =>
     [LoggerMessage(Level = LogLevel.Error, Message = "Unhandled exception on {Path}")]
     private static partial void LogUnhandledException(ILogger<Program> logger, Exception? exception, PathString path);
 
-    [LoggerMessage(Level = LogLevel.Information, Message = "Sitemap validation completed successfully during application startup")]
-    private static partial void LogSitemapValidationSucceeded(ILogger<Program> logger);
-
-    [LoggerMessage(Level = LogLevel.Error, Message = "Failed to validate sitemap during application startup")]
-    private static partial void LogSitemapValidationFailed(ILogger<Program> logger, Exception exception);
+    [LoggerMessage(Level = LogLevel.Information, Message = "Sitemap validation completed successfully during application startup")]
+    private static partial void LogSitemapValidationSucceeded(ILogger<Program> logger);
+
+    [LoggerMessage(Level = LogLevel.Error, Message = "Failed to validate sitemap during application startup")]
+    private static partial void LogSitemapValidationFailed(ILogger<Program> logger, Exception exception);
 
     [LoggerMessage(Level = LogLevel.Warning, Message = "Ignoring invalid TryDotNet origin in CSP: {Origin}")]
     private static partial void LogIgnoringInvalidTryDotNetOrigin(ILogger logger, string origin);
diff --git a/EssentialCSharp.Web/appsettings.json b/EssentialCSharp.Web/appsettings.json
index fe9a4e35..3e73c768 100644
--- a/EssentialCSharp.Web/appsettings.json
+++ b/EssentialCSharp.Web/appsettings.json
@@ -2,6 +2,9 @@
   "ConnectionStrings": {
     "PostgresVectorStore": "your-postgres-connection-string-here"
   },
+  "ForwardedHeaders": {
+    "TrustedProxyCidrs": []
+  },
   "Logging": {
     "LogLevel": {
       "Default": "Warning",

From fa37d5f47cb263d9497b9a69d7a9496ac375f018 Mon Sep 17 00:00:00 2001
From: Benjamin Michaelis <git@relay.benjamin.michaelis.net>
Date: Wed, 13 May 2026 21:28:59 -0700
Subject: [PATCH 2/9] security: improve proxy warning to check resolved
 IOptions, unify unknown-user keys

- Replace raw config-length check with IOptions<ForwardedHeadersOptions> post-Build DI
  resolution so warning fires for both 'not configured' and 'all CIDRs failed to parse'
- Normalize ContentRateLimiterPolicy fallback to 'unknown-user' for consistency
---
 .../Controllers/ChatMessageRequest.cs           |  1 -
 EssentialCSharp.Web/Program.cs                  | 17 ++++++++++++++++-
 .../Services/ContentRateLimiterPolicy.cs        |  2 +-
 .../Services/McpRateLimiterPolicy.cs            |  1 -
 4 files changed, 17 insertions(+), 4 deletions(-)

diff --git a/EssentialCSharp.Web/Controllers/ChatMessageRequest.cs b/EssentialCSharp.Web/Controllers/ChatMessageRequest.cs
index 817cbecc..7cec84eb 100644
--- a/EssentialCSharp.Web/Controllers/ChatMessageRequest.cs
+++ b/EssentialCSharp.Web/Controllers/ChatMessageRequest.cs
@@ -10,5 +10,4 @@ public class ChatMessageRequest
     [StringLength(200)]
     public string? PreviousResponseId { get; set; }
     public bool EnableContextualSearch { get; set; } = true;
-    public string? CaptchaResponse { get; set; } // hCaptcha token; validated server-side when chat captcha enforcement is wired up
 }
diff --git a/EssentialCSharp.Web/Program.cs b/EssentialCSharp.Web/Program.cs
index 9855f83d..9c1237df 100644
--- a/EssentialCSharp.Web/Program.cs
+++ b/EssentialCSharp.Web/Program.cs
@@ -128,6 +128,8 @@ private static void Main(string[] args)
             {
                 if (System.Net.IPNetwork.TryParse(cidr, out var network))
                     options.KnownIPNetworks.Add(network);
+                else
+                    Console.Error.WriteLine($"[WARN] ForwardedHeaders:TrustedProxyCidrs: could not parse '{cidr}' as an IP network — entry skipped. Check your configuration.");
             }
         });
 
@@ -320,7 +322,7 @@ private static void Main(string[] args)
                     return RateLimitPartition.GetNoLimiter("mcp-transport");
 
                 var partitionKey = httpContext.User.Identity?.IsAuthenticated == true
-                    ? httpContext.User.FindFirst(ClaimTypes.NameIdentifier)?.Value ?? "unknown-user"
+                    ? httpContext.User.FindFirstValue(ClaimTypes.NameIdentifier) ?? "unknown-user"
                     : httpContext.Connection.RemoteIpAddress?.ToString() ?? "unknown-ip";
 
                 return RateLimitPartition.GetFixedWindowLimiter(
@@ -437,6 +439,16 @@ await context.HttpContext.Response.WriteAsync(
 
         WebApplication app = builder.Build();
 
+        // Warn if the effective trusted-proxy set is empty in non-Development — this fires for
+        // both "no CIDRs configured" and "all configured CIDRs failed to parse" cases, ensuring
+        // X-Forwarded-For spoofing protection (F4) is visibly inactive until properly configured.
+        if (!app.Environment.IsDevelopment())
+        {
+            var fwdOpts = app.Services.GetRequiredService<IOptions<ForwardedHeadersOptions>>().Value;
+            if (fwdOpts.KnownIPNetworks.Count == 0 && fwdOpts.KnownProxies.Count == 0)
+                LogTrustedProxyCidrsNotConfigured(app.Logger);
+        }
+
         // Configure the HTTP request pipeline.
         if (!app.Environment.IsDevelopment())
         {
@@ -623,4 +635,7 @@ private static bool IsMcpTransportRequest(HttpRequest request) =>
 
     [LoggerMessage(Level = LogLevel.Warning, Message = "Ignoring invalid TryDotNet origin in CSP: {Origin}")]
     private static partial void LogIgnoringInvalidTryDotNetOrigin(ILogger logger, string origin);
+
+    [LoggerMessage(Level = LogLevel.Warning, Message = "SECURITY: ForwardedHeaders:TrustedProxyCidrs is not configured. All X-Forwarded-For values are trusted, enabling IP spoofing against rate limits. Set this to your load-balancer CIDR (e.g., Azure Container Apps ingress range) to harden this endpoint.")]
+    private static partial void LogTrustedProxyCidrsNotConfigured(ILogger logger);
 }
diff --git a/EssentialCSharp.Web/Services/ContentRateLimiterPolicy.cs b/EssentialCSharp.Web/Services/ContentRateLimiterPolicy.cs
index a9b4d21e..0e125c56 100644
--- a/EssentialCSharp.Web/Services/ContentRateLimiterPolicy.cs
+++ b/EssentialCSharp.Web/Services/ContentRateLimiterPolicy.cs
@@ -26,7 +26,7 @@ public RateLimitPartition<string> GetPartition(HttpContext httpContext)
         // Use stable user ID (GUID) for authenticated users so the bucket survives
         // username changes and doesn't conflate login/logout with scraping.
         string partitionKey = isAuthenticated
-            ? $"user:{httpContext.User.FindFirstValue(ClaimTypes.NameIdentifier) ?? httpContext.User.Identity!.Name ?? "unknown"}"
+            ? $"user:{httpContext.User.FindFirstValue(ClaimTypes.NameIdentifier) ?? "unknown-user"}"
             : $"ip:{httpContext.Connection.RemoteIpAddress?.ToString() ?? "unknown-ip"}";
 
         int perMinuteLimit = isAuthenticated ? AuthenticatedPerMinute : AnonymousPerMinute;
diff --git a/EssentialCSharp.Web/Services/McpRateLimiterPolicy.cs b/EssentialCSharp.Web/Services/McpRateLimiterPolicy.cs
index 76438d0b..86eaa4e7 100644
--- a/EssentialCSharp.Web/Services/McpRateLimiterPolicy.cs
+++ b/EssentialCSharp.Web/Services/McpRateLimiterPolicy.cs
@@ -21,7 +21,6 @@ public RateLimitPartition<string> GetPartition(HttpContext httpContext)
         if (httpContext.User.Identity?.IsAuthenticated == true)
         {
             string userId = httpContext.User.FindFirstValue(ClaimTypes.NameIdentifier)
-                ?? httpContext.User.Identity?.Name
                 ?? "unknown-user";
 
             return RateLimitPartition.GetTokenBucketLimiter(

From 653055fd6693c2c24e6a4d142cfbd3e7e0af4ffa Mon Sep 17 00:00:00 2001
From: Benjamin Michaelis <git@relay.benjamin.michaelis.net>
Date: Wed, 13 May 2026 21:59:40 -0700
Subject: [PATCH 3/9] refactor: narrow sitemap catch clause to
 InvalidOperationException

EnsureSitemapHealthy only throws InvalidOperationException; using a
generic catch was overly broad. Addresses GitHub code quality feedback.
---
 EssentialCSharp.Web/Program.cs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/EssentialCSharp.Web/Program.cs b/EssentialCSharp.Web/Program.cs
index 9c1237df..183d778c 100644
--- a/EssentialCSharp.Web/Program.cs
+++ b/EssentialCSharp.Web/Program.cs
@@ -609,7 +609,7 @@ await McpJsonRpcResponseWriter.WriteErrorAsync(
             SitemapXmlHelpers.EnsureSitemapHealthy(siteMappingService.SiteMappings.ToList());
             LogSitemapValidationSucceeded(logger);
         }
-        catch (Exception ex)
+        catch (InvalidOperationException ex)
         {
             LogSitemapValidationFailed(logger, ex);
             // Continue startup even if sitemap validation fails

From 914fb94859a03459fd600d498d1ff07a0399d441 Mon Sep 17 00:00:00 2001
From: Benjamin Michaelis <git@relay.benjamin.michaelis.net>
Date: Wed, 13 May 2026 22:16:26 -0700
Subject: [PATCH 4/9] feat: implement hCaptcha validation on chat endpoints

Replaces the dead CaptchaResponse comment with a working implementation:

Server-side (ChatController):
- Inject ICaptchaService + IOptions<CaptchaOptions>
- Validate hCaptcha token before processing each message
- Graceful degradation: skipped when SecretKey is not configured (dev)
- Fail-open on hCaptcha outages to avoid blocking legitimate users
- Returns 403 + { errorCode: 'captcha_failed' } on invalid tokens

Client-side (chat-module.js / ChatWidget.vue):
- Invisible hCaptcha widget rendered outside v-if dialog so it persists
  across open/close cycles and only initializes once
- getCaptchaToken() wraps execute() in a Promise; resolves instantly for
  non-suspicious users (invisible mode)
- Token included as captchaResponse in every request body
- Widget reset after each send (success or failure) for a fresh token
- 403 responses mapped to captcha-error type in the UI
- hCaptcha legal disclosure shown in footer when captcha is configured

Layout:
- Expose window.HCAPTCHA_SITE_KEY from CaptchaOptions for the JS layer
---
 .../Controllers/ChatController.cs             | 42 +++++++++-
 .../Controllers/ChatMessageRequest.cs         |  6 ++
 .../Views/Shared/_Layout.cshtml               |  3 +
 .../src/components/ChatWidget.vue             | 20 +++++
 EssentialCSharp.Web/wwwroot/js/chat-module.js | 77 ++++++++++++++++++-
 5 files changed, 146 insertions(+), 2 deletions(-)

diff --git a/EssentialCSharp.Web/Controllers/ChatController.cs b/EssentialCSharp.Web/Controllers/ChatController.cs
index 0fcd8577..d1ae20bf 100644
--- a/EssentialCSharp.Web/Controllers/ChatController.cs
+++ b/EssentialCSharp.Web/Controllers/ChatController.cs
@@ -1,10 +1,12 @@
 using System.Security.Claims;
 using System.Text.Json;
 using EssentialCSharp.Chat.Common.Services;
+using EssentialCSharp.Web.Models;
 using EssentialCSharp.Web.Services;
 using Microsoft.AspNetCore.Authorization;
 using Microsoft.AspNetCore.Mvc;
 using Microsoft.AspNetCore.RateLimiting;
+using Microsoft.Extensions.Options;
 
 namespace EssentialCSharp.Web.Controllers;
 
@@ -17,15 +19,40 @@ public partial class ChatController : ControllerBase
 {
     private readonly AIChatService _AiChatService;
     private readonly ResponseIdValidationService _ResponseIdValidationService;
+    private readonly ICaptchaService _CaptchaService;
+    private readonly CaptchaOptions _CaptchaOptions;
     private readonly ILogger<ChatController> _Logger;
 
-    public ChatController(ILogger<ChatController> logger, AIChatService aiChatService, ResponseIdValidationService responseIdValidationService)
+    public ChatController(ILogger<ChatController> logger, AIChatService aiChatService,
+        ResponseIdValidationService responseIdValidationService,
+        ICaptchaService captchaService, IOptions<CaptchaOptions> captchaOptions)
     {
         _AiChatService = aiChatService;
         _ResponseIdValidationService = responseIdValidationService;
+        _CaptchaService = captchaService;
+        _CaptchaOptions = captchaOptions.Value;
         _Logger = logger;
     }
 
+    /// <summary>
+    /// Validates the hCaptcha token when captcha is configured.
+    /// Returns <c>true</c> when captcha is not configured (dev mode) or when the token is valid.
+    /// Fails open on hCaptcha service outages to avoid blocking legitimate users.
+    /// </summary>
+    private async Task<bool> IsCaptchaValidAsync(string? token, string? remoteIp, CancellationToken ct)
+    {
+        if (string.IsNullOrWhiteSpace(_CaptchaOptions.SecretKey))
+            return true; // captcha not configured — skip validation
+
+        HCaptchaResult? result = await _CaptchaService.VerifyAsync(token, remoteIp, ct);
+        if (result is null)
+        {
+            LogCaptchaServiceUnavailable(_Logger); // hCaptcha unreachable — fail open
+            return true;
+        }
+        return result.Success;
+    }
+
     [HttpPost("message")]
     public async Task<IActionResult> SendMessage([FromBody] ChatMessageRequest request, CancellationToken cancellationToken = default)
     {
@@ -37,6 +64,9 @@ public async Task<IActionResult> SendMessage([FromBody] ChatMessageRequest reque
         if (string.IsNullOrEmpty(userId))
             return Unauthorized();
 
+        if (!await IsCaptchaValidAsync(request.CaptchaResponse, HttpContext.Connection.RemoteIpAddress?.ToString(), cancellationToken))
+            return StatusCode(403, new { error = "Human verification required.", errorCode = "captcha_failed" });
+
         var previousResponseId = string.IsNullOrWhiteSpace(request.PreviousResponseId)
             ? null
             : request.PreviousResponseId.Trim();
@@ -87,6 +117,13 @@ public async Task StreamMessage([FromBody] ChatMessageRequest request, Cancellat
             return;
         }
 
+        if (!await IsCaptchaValidAsync(request.CaptchaResponse, HttpContext.Connection.RemoteIpAddress?.ToString(), cancellationToken))
+        {
+            Response.StatusCode = 403;
+            await Response.WriteAsJsonAsync(new { error = "Human verification required.", errorCode = "captcha_failed" }, CancellationToken.None);
+            return;
+        }
+
         var previousResponseId = string.IsNullOrWhiteSpace(request.PreviousResponseId)
             ? null
             : request.PreviousResponseId.Trim();
@@ -184,6 +221,9 @@ public async Task StreamMessage([FromBody] ChatMessageRequest request, Cancellat
         }
     }
 
+    [LoggerMessage(Level = LogLevel.Warning, Message = "hCaptcha service unavailable during chat request — failing open")]
+    private static partial void LogCaptchaServiceUnavailable(ILogger<ChatController> logger);
+
     [LoggerMessage(Level = LogLevel.Debug, Message = "Chat stream cancelled for user {User}")]
     private static partial void LogChatStreamCancelled(ILogger<ChatController> logger, string? user);
 
diff --git a/EssentialCSharp.Web/Controllers/ChatMessageRequest.cs b/EssentialCSharp.Web/Controllers/ChatMessageRequest.cs
index 7cec84eb..ca05d5ee 100644
--- a/EssentialCSharp.Web/Controllers/ChatMessageRequest.cs
+++ b/EssentialCSharp.Web/Controllers/ChatMessageRequest.cs
@@ -10,4 +10,10 @@ public class ChatMessageRequest
     [StringLength(200)]
     public string? PreviousResponseId { get; set; }
     public bool EnableContextualSearch { get; set; } = true;
+    /// <summary>
+    /// hCaptcha token obtained from the client-side invisible widget.
+    /// Required when <c>CaptchaOptions.SecretKey</c> is configured; ignored otherwise.
+    /// </summary>
+    [StringLength(2000)]
+    public string? CaptchaResponse { get; set; }
 }
diff --git a/EssentialCSharp.Web/Views/Shared/_Layout.cshtml b/EssentialCSharp.Web/Views/Shared/_Layout.cshtml
index 3f19ac18..02e649a9 100644
--- a/EssentialCSharp.Web/Views/Shared/_Layout.cshtml
+++ b/EssentialCSharp.Web/Views/Shared/_Layout.cshtml
@@ -6,9 +6,11 @@
 @using Microsoft.AspNetCore.Identity
 @using EssentialCSharp.Web.Areas.Identity.Data
 @using Microsoft.Extensions.Configuration
+@using Microsoft.Extensions.Options
 @inject ISiteMappingService _SiteMappings
 @inject SignInManager<EssentialCSharpWebUser> SignInManager
 @inject IConfiguration Configuration
+@inject IOptions<CaptchaOptions> _CaptchaOptions
 <!DOCTYPE html>
 <html lang="en">
 <head>
@@ -192,6 +194,7 @@
         window.TRYDOTNET_ORIGIN = @Json.Serialize(Configuration["TryDotNet:Origin"]);
         window.BUILD_LABEL = @Json.Serialize(buildLabel);
         window.ENABLE_CHAT_WIDGET = @Json.Serialize(!Context.Request.Path.StartsWithSegments("/Identity"));
+        window.HCAPTCHA_SITE_KEY = @Json.Serialize(_CaptchaOptions.Value.SiteKey);
     </script>
     <script src="~/dist/assets/site-shell.js" type="module" asp-append-version="true"></script>
 </body>
diff --git a/EssentialCSharp.Web/src/components/ChatWidget.vue b/EssentialCSharp.Web/src/components/ChatWidget.vue
index b7b0820f..ff74fc7a 100644
--- a/EssentialCSharp.Web/src/components/ChatWidget.vue
+++ b/EssentialCSharp.Web/src/components/ChatWidget.vue
@@ -11,6 +11,7 @@ const {
     isTyping,
     chatMessagesEl,
     chatInputField,
+    captchaSiteKey,
     openChatDialog,
     closeChatDialog,
     clearChatHistory,
@@ -23,6 +24,18 @@ const {
 
 <template>
     <div class="chat-widget">
+        <!--
+            Invisible hCaptcha container: lives outside the v-if dialog so the widget
+            persists across open/close cycles and only needs to be initialized once.
+            Renders only when captcha is configured (HCAPTCHA_SITE_KEY is non-null).
+        -->
+        <div
+            v-if="captchaSiteKey"
+            id="chat-captcha-container"
+            class="visually-hidden"
+            aria-hidden="true"
+        />
+
         <button
             class="chat-button elevation-6"
             :class="{ 'chat-button--active': showChatDialog }"
@@ -189,6 +202,13 @@ const {
                             Type your question and press Enter or click send. Maximum 500 characters.
                         </div>
                     </form>
+                    <!-- hCaptcha legal disclosure required for invisible mode -->
+                    <p v-if="captchaSiteKey" class="captcha-notice small text-muted mt-1">
+                        Protected by hCaptcha —
+                        <a href="https://www.hcaptcha.com/privacy" target="_blank" rel="noopener noreferrer">Privacy</a>
+                        &amp;
+                        <a href="https://www.hcaptcha.com/terms" target="_blank" rel="noopener noreferrer">Terms</a>
+                    </p>
                 </div>
             </div>
         </div>
diff --git a/EssentialCSharp.Web/wwwroot/js/chat-module.js b/EssentialCSharp.Web/wwwroot/js/chat-module.js
index cc436c25..02ffc904 100644
--- a/EssentialCSharp.Web/wwwroot/js/chat-module.js
+++ b/EssentialCSharp.Web/wwwroot/js/chat-module.js
@@ -6,11 +6,72 @@ import { ref, nextTick, watch, onMounted, onUnmounted } from "vue";
 const errorIconClassByType = {
     'rate-limit': 'fas fa-clock',
     'auth-error': 'fas fa-lock',
+    'captcha-error': 'fas fa-shield-alt',
     'validation-error': 'fas fa-exclamation-circle',
     'network-error': 'fas fa-wifi',
     'connection-error': 'fas fa-plug'
 };
 
+// hCaptcha integration — invisible widget renders once and is reused across messages.
+// When HCAPTCHA_SITE_KEY is null (dev / captcha not configured), all captcha calls are no-ops.
+const captchaSiteKey = window.HCAPTCHA_SITE_KEY || null;
+let captchaWidgetId = null;
+let captchaTokenResolve = null;
+let captchaTokenReject = null;
+
+function initCaptchaWidget() {
+    if (!captchaSiteKey) return;
+    // Guard: only render once (widget lives outside the v-if dialog overlay)
+    if (captchaWidgetId !== null) return;
+    const container = document.getElementById('chat-captcha-container');
+    if (!container) return;
+
+    window.EssentialCSharp.HCaptcha.whenHcaptchaReady(() => {
+        if (captchaWidgetId !== null) return; // double-check after async wait
+        captchaWidgetId = window.hcaptcha.render(container, {
+            sitekey: captchaSiteKey,
+            size: 'invisible',
+            callback: (token) => {
+                const resolve = captchaTokenResolve;
+                captchaTokenResolve = null;
+                captchaTokenReject = null;
+                resolve?.(token);
+            },
+            'expired-callback': () => {
+                const reject = captchaTokenReject;
+                captchaTokenResolve = null;
+                captchaTokenReject = null;
+                reject?.(new Error('captcha-expired'));
+            },
+            'error-callback': () => {
+                const reject = captchaTokenReject;
+                captchaTokenResolve = null;
+                captchaTokenReject = null;
+                reject?.(new Error('captcha-error'));
+            }
+        });
+    });
+}
+
+/**
+ * Returns a fresh hCaptcha token, or null if captcha is not configured.
+ * Resolves after the invisible challenge completes (typically instant for non-suspicious users).
+ */
+function getCaptchaToken() {
+    if (!captchaSiteKey || captchaWidgetId === null) return Promise.resolve(null);
+    return new Promise((resolve, reject) => {
+        captchaTokenResolve = resolve;
+        captchaTokenReject = reject;
+        window.hcaptcha.execute(captchaWidgetId);
+    });
+}
+
+function resetCaptchaWidget() {
+    if (captchaWidgetId !== null && typeof window.hcaptcha?.reset === 'function') {
+        window.hcaptcha.reset(captchaWidgetId);
+    }
+}
+
 export function useChatWidget() {
     // Authentication state
     const isAuthenticated = ref(window.IS_AUTHENTICATED || false);
@@ -109,6 +170,7 @@ export function useChatWidget() {
                 chatInputField.value.focus();
             }
             scrollToBottom();
+            initCaptchaWidget();
         });
     }
 
@@ -212,10 +274,14 @@ export function useChatWidget() {
 
         let reader = null;
         try {
+            // Obtain invisible hCaptcha token (null when captcha is not configured)
+            const captchaResponse = await getCaptchaToken();
+
             const requestBody = {
                 message: userMessage,
                 enableContextualSearch: true,
-                previousResponseId: lastResponseId.value
+                previousResponseId: lastResponseId.value,
+                captchaResponse: captchaResponse
             };
 
             const response = await fetch('/api/chat/stream', {
@@ -229,6 +295,8 @@ export function useChatWidget() {
             if (!response.ok) {
                 if (response.status === 401) {
                     throw new Error('Authentication required');
+                } else if (response.status === 403) {
+                    throw new Error('captcha-failed: Human verification failed. Please try again.');
                 } else if (response.status === 429) {
                     // Handle rate limiting - simple error message without captcha
                     let errorData;
@@ -330,6 +398,9 @@ export function useChatWidget() {
                 errorMessage = 'You must be logged in to use the chat feature. Please log in and try again.';
                 errorType = 'auth-error';
                 isAuthenticated.value = false; // Update auth state
+            } else if (error.message?.startsWith('captcha-')) {
+                errorMessage = 'Human verification failed. Please try again.';
+                errorType = 'captcha-error';
             } else if (error.message?.includes('Rate limit exceeded')) {
                 errorMessage = error.message; // Use the specific rate limit message with timing
                 errorType = 'rate-limit';
@@ -358,6 +429,9 @@ export function useChatWidget() {
                 }
             }
             
+            // Reset the captcha widget so a fresh token is obtained for the next message
+            resetCaptchaWidget();
+
             // Ensure typing indicator is hidden
             isTyping.value = false;
             
@@ -379,6 +453,7 @@ export function useChatWidget() {
         isTyping,
         chatMessagesEl,
         chatInputField,
+        captchaSiteKey,
 
         // Methods
         openChatDialog,

From d06b44063758b61ccb1a6b636ae329eb692f45d1 Mon Sep 17 00:00:00 2001
From: Benjamin Michaelis <git@relay.benjamin.michaelis.net>
Date: Wed, 13 May 2026 22:28:13 -0700
Subject: [PATCH 5/9] security: harden captcha integration after peer review

- Reject null/empty token server-side before making outbound hCaptcha call
- Add LogCaptchaValidationFailed [LoggerMessage] for observability on rejections
- Document fail-open policy with explicit rationale comment
- JS: add captchaPending flag to block concurrent getCaptchaToken() calls
- JS: wrap getCaptchaToken() in 15-second timeout race to prevent UI freeze
- JS: clearTimeout(timeoutId) in resolve/reject wrappers to prevent stale
  timer from corrupting state of subsequent calls
---
 .../Controllers/ChatController.cs             | 16 +++++++-
 EssentialCSharp.Web/wwwroot/js/chat-module.js | 38 +++++++++++++++++--
 2 files changed, 49 insertions(+), 5 deletions(-)

diff --git a/EssentialCSharp.Web/Controllers/ChatController.cs b/EssentialCSharp.Web/Controllers/ChatController.cs
index d1ae20bf..b489b58d 100644
--- a/EssentialCSharp.Web/Controllers/ChatController.cs
+++ b/EssentialCSharp.Web/Controllers/ChatController.cs
@@ -37,19 +37,28 @@ public ChatController(ILogger<ChatController> logger, AIChatService aiChatServic
     /// <summary>
     /// Validates the hCaptcha token when captcha is configured.
     /// Returns <c>true</c> when captcha is not configured (dev mode) or when the token is valid.
-    /// Fails open on hCaptcha service outages to avoid blocking legitimate users.
+    /// Fails open on hCaptcha service outages (null result) to avoid blocking legitimate users —
+    /// this is intentional given the existing [Authorize] + rate-limiting backstop.
     /// </summary>
     private async Task<bool> IsCaptchaValidAsync(string? token, string? remoteIp, CancellationToken ct)
     {
         if (string.IsNullOrWhiteSpace(_CaptchaOptions.SecretKey))
             return true; // captcha not configured — skip validation
 
+        if (string.IsNullOrWhiteSpace(token))
+            return false; // token required when captcha is configured — reject without an outbound call
+
         HCaptchaResult? result = await _CaptchaService.VerifyAsync(token, remoteIp, ct);
         if (result is null)
         {
-            LogCaptchaServiceUnavailable(_Logger); // hCaptcha unreachable — fail open
+            LogCaptchaServiceUnavailable(_Logger); // hCaptcha unreachable — fail open (intentional)
             return true;
         }
+
+        if (!result.Success)
+        {
+            LogCaptchaValidationFailed(_Logger, string.Join(',', result.ErrorCodes ?? []));
+        }
         return result.Success;
     }
 
@@ -224,6 +233,9 @@ public async Task StreamMessage([FromBody] ChatMessageRequest request, Cancellat
     [LoggerMessage(Level = LogLevel.Warning, Message = "hCaptcha service unavailable during chat request — failing open")]
     private static partial void LogCaptchaServiceUnavailable(ILogger<ChatController> logger);
 
+    [LoggerMessage(Level = LogLevel.Warning, Message = "hCaptcha validation failed for chat request — error codes: {ErrorCodes}")]
+    private static partial void LogCaptchaValidationFailed(ILogger<ChatController> logger, string errorCodes);
+
     [LoggerMessage(Level = LogLevel.Debug, Message = "Chat stream cancelled for user {User}")]
     private static partial void LogChatStreamCancelled(ILogger<ChatController> logger, string? user);
 
diff --git a/EssentialCSharp.Web/wwwroot/js/chat-module.js b/EssentialCSharp.Web/wwwroot/js/chat-module.js
index 02ffc904..c8e40053 100644
--- a/EssentialCSharp.Web/wwwroot/js/chat-module.js
+++ b/EssentialCSharp.Web/wwwroot/js/chat-module.js
@@ -18,6 +18,8 @@ const captchaSiteKey = window.HCAPTCHA_SITE_KEY || null;
 let captchaWidgetId = null;
 let captchaTokenResolve = null;
 let captchaTokenReject = null;
+let captchaPending = false; // prevents concurrent token requests overwriting promise callbacks
+const CAPTCHA_TIMEOUT_MS = 15_000;
 
 function initCaptchaWidget() {
     if (!captchaSiteKey) return;
@@ -56,17 +58,47 @@ function initCaptchaWidget() {
 /**
  * Returns a fresh hCaptcha token, or null if captcha is not configured.
  * Resolves after the invisible challenge completes (typically instant for non-suspicious users).
+ * Rejects with 'captcha-concurrent' if a token request is already in-flight.
+ * Rejects with 'captcha-timeout' if the widget does not respond within 15 seconds.
  */
 function getCaptchaToken() {
     if (!captchaSiteKey || captchaWidgetId === null) return Promise.resolve(null);
-    return new Promise((resolve, reject) => {
-        captchaTokenResolve = resolve;
-        captchaTokenReject = reject;
+    if (captchaPending) return Promise.reject(new Error('captcha-concurrent'));
+    captchaPending = true;
+
+    let timeoutId;
+
+    const tokenPromise = new Promise((resolve, reject) => {
+        captchaTokenResolve = (token) => {
+            captchaPending = false;
+            clearTimeout(timeoutId); // cancel lingering timer so it can't corrupt the next call
+            resolve(token);
+        };
+        captchaTokenReject  = (err) => {
+            captchaPending = false;
+            clearTimeout(timeoutId);
+            reject(err);
+        };
         window.hcaptcha.execute(captchaWidgetId);
     });
+
+    const timeoutPromise = new Promise((_, reject) => {
+        // timeoutId is assigned synchronously here, before captchaTokenResolve can fire
+        timeoutId = setTimeout(() => {
+            captchaPending = false;
+            captchaTokenResolve = null;
+            captchaTokenReject  = null;
+            reject(new Error('captcha-timeout'));
+        }, CAPTCHA_TIMEOUT_MS);
+    });
+
+    return Promise.race([tokenPromise, timeoutPromise]);
 }
 
 function resetCaptchaWidget() {
+    captchaPending = false;
+    captchaTokenResolve = null;
+    captchaTokenReject = null;
     if (captchaWidgetId !== null && typeof window.hcaptcha?.reset === 'function') {
         window.hcaptcha.reset(captchaWidgetId);
     }

From bf8390ace931fefed22e9679f4350dbd970ed7ca Mon Sep 17 00:00:00 2001
From: Benjamin Michaelis <git@relay.benjamin.michaelis.net>
Date: Thu, 14 May 2026 16:50:03 -0700
Subject: [PATCH 6/9] fix: wait for hCaptcha widget before executing token
 request

getCaptchaToken() was returning null immediately when captchaWidgetId === null
(hCaptcha script still loading), causing the server to reject with 403 for any
user who submitted a message before the widget finished rendering.

Fix: introduce captchaWidgetReady Promise that resolves once hcaptcha.render()
completes. getCaptchaToken() now chains onto it so early sends wait (up to the
15s timeout) rather than sending a null token.
---
 EssentialCSharp.Web/wwwroot/js/chat-module.js | 18 ++++++++++++++----
 1 file changed, 14 insertions(+), 4 deletions(-)

diff --git a/EssentialCSharp.Web/wwwroot/js/chat-module.js b/EssentialCSharp.Web/wwwroot/js/chat-module.js
index c8e40053..2ab338b8 100644
--- a/EssentialCSharp.Web/wwwroot/js/chat-module.js
+++ b/EssentialCSharp.Web/wwwroot/js/chat-module.js
@@ -21,6 +21,13 @@ let captchaTokenReject = null;
 let captchaPending = false; // prevents concurrent token requests overwriting promise callbacks
 const CAPTCHA_TIMEOUT_MS = 15_000;
 
+// Resolves once the widget has rendered. getCaptchaToken() awaits this so a user who
+// submits before hCaptcha finishes loading waits (up to 15 s) rather than getting a 403.
+let captchaWidgetReadyResolve = null;
+const captchaWidgetReady = captchaSiteKey
+    ? new Promise((resolve) => { captchaWidgetReadyResolve = resolve; })
+    : Promise.resolve();
+
 function initCaptchaWidget() {
     if (!captchaSiteKey) return;
     // Guard: only render once (widget lives outside the v-if dialog overlay)
@@ -52,23 +59,26 @@ function initCaptchaWidget() {
                 reject?.(new Error('captcha-error'));
             }
         });
+        captchaWidgetReadyResolve?.(); // unblock any getCaptchaToken() calls waiting for the widget
     });
 }
 
 /**
  * Returns a fresh hCaptcha token, or null if captcha is not configured.
- * Resolves after the invisible challenge completes (typically instant for non-suspicious users).
+ * Waits for the widget to finish rendering if it has not yet (handles slow script loads).
  * Rejects with 'captcha-concurrent' if a token request is already in-flight.
  * Rejects with 'captcha-timeout' if the widget does not respond within 15 seconds.
  */
 function getCaptchaToken() {
-    if (!captchaSiteKey || captchaWidgetId === null) return Promise.resolve(null);
+    if (!captchaSiteKey) return Promise.resolve(null);
     if (captchaPending) return Promise.reject(new Error('captcha-concurrent'));
     captchaPending = true;
 
     let timeoutId;
 
-    const tokenPromise = new Promise((resolve, reject) => {
+    // Chain onto captchaWidgetReady so calls made before the widget finishes loading
+    // wait rather than immediately returning null and causing a 403.
+    const tokenPromise = captchaWidgetReady.then(() => new Promise((resolve, reject) => {
         captchaTokenResolve = (token) => {
             captchaPending = false;
             clearTimeout(timeoutId); // cancel lingering timer so it can't corrupt the next call
@@ -80,7 +90,7 @@ function getCaptchaToken() {
             reject(err);
         };
         window.hcaptcha.execute(captchaWidgetId);
-    });
+    }));
 
     const timeoutPromise = new Promise((_, reject) => {
         // timeoutId is assigned synchronously here, before captchaTokenResolve can fire

From 5aa11e8517a1bb73445113782a26bb7292001280 Mon Sep 17 00:00:00 2001
From: Benjamin Michaelis <git@relay.benjamin.michaelis.net>
Date: Sat, 16 May 2026 21:26:30 -0700
Subject: [PATCH 7/9] fix: address PR review comments
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Fix misleading log message: 'failing open' -> 'failing closed (503)' in
  LogCaptchaServiceUnavailable (hCaptcha unavailable returns 503, not open)
- Remove dead ArgumentException/FormatException catch blocks from sitemap
  validation; EnsureSitemapHealthy only throws InvalidOperationException
- Remove duplicate top-level ForwardedHeaders section from appsettings.json
  (two keys at the same path; keep the one with both TrustedProxyCidrs and
  TrustedProxies)
- Fix captcha challenge timeout: start 90s timer after widget is ready, not
  before — previously script-load time ate into the challenge window; also
  increases from 15s to 90s to accommodate interactive challenges
---
 .../Controllers/ChatController.cs             |  2 +-
 EssentialCSharp.Web/Program.cs                | 10 ---
 EssentialCSharp.Web/appsettings.json          |  3 -
 EssentialCSharp.Web/wwwroot/js/chat-module.js | 69 ++++++++++---------
 4 files changed, 38 insertions(+), 46 deletions(-)

diff --git a/EssentialCSharp.Web/Controllers/ChatController.cs b/EssentialCSharp.Web/Controllers/ChatController.cs
index 41151c78..1d7d7185 100644
--- a/EssentialCSharp.Web/Controllers/ChatController.cs
+++ b/EssentialCSharp.Web/Controllers/ChatController.cs
@@ -290,7 +290,7 @@ public async Task StreamMessage([FromBody] ChatMessageRequest request, Cancellat
         }
     }
 
-    [LoggerMessage(Level = LogLevel.Warning, Message = "hCaptcha service unavailable during chat request — failing open")]
+    [LoggerMessage(Level = LogLevel.Warning, Message = "hCaptcha service unavailable during chat request — failing closed (503)")]
     private static partial void LogCaptchaServiceUnavailable(ILogger<ChatController> logger);
 
     [LoggerMessage(Level = LogLevel.Warning, Message = "hCaptcha validation failed for chat request — error codes: {ErrorCodes}")]
diff --git a/EssentialCSharp.Web/Program.cs b/EssentialCSharp.Web/Program.cs
index 76bfc32d..a981d084 100644
--- a/EssentialCSharp.Web/Program.cs
+++ b/EssentialCSharp.Web/Program.cs
@@ -616,16 +616,6 @@ await McpJsonRpcResponseWriter.WriteErrorAsync(
             LogSitemapValidationFailed(logger, ex);
             // Continue startup even if sitemap validation fails
         }
-        catch (ArgumentException ex)
-        {
-            LogSitemapValidationFailed(logger, ex);
-            // Continue startup even if sitemap validation fails
-        }
-        catch (FormatException ex)
-        {
-            LogSitemapValidationFailed(logger, ex);
-            // Continue startup even if sitemap validation fails
-        }
 
         app.Run();
     }
diff --git a/EssentialCSharp.Web/appsettings.json b/EssentialCSharp.Web/appsettings.json
index b3224e81..80ce5921 100644
--- a/EssentialCSharp.Web/appsettings.json
+++ b/EssentialCSharp.Web/appsettings.json
@@ -2,9 +2,6 @@
   "ConnectionStrings": {
     "PostgresVectorStore": "your-postgres-connection-string-here"
   },
-  "ForwardedHeaders": {
-    "TrustedProxyCidrs": []
-  },
   "Logging": {
     "LogLevel": {
       "Default": "Warning",
diff --git a/EssentialCSharp.Web/wwwroot/js/chat-module.js b/EssentialCSharp.Web/wwwroot/js/chat-module.js
index ae63607c..49fd375d 100644
--- a/EssentialCSharp.Web/wwwroot/js/chat-module.js
+++ b/EssentialCSharp.Web/wwwroot/js/chat-module.js
@@ -20,7 +20,7 @@ let captchaTokenResolve = null;
 let captchaTokenReject = null;
 let captchaPending = false; // prevents concurrent token requests overwriting promise callbacks
 let captchaRequestGeneration = 0;
-const CAPTCHA_TIMEOUT_MS = 15_000;
+const CAPTCHA_TIMEOUT_MS = 90_000;
 
 // Resolves once the widget has rendered. getCaptchaToken() awaits this so a user who
 // submits before hCaptcha finishes loading waits (up to 15 s) rather than getting a 403.
@@ -68,7 +68,8 @@ function initCaptchaWidget() {
  * Returns a fresh hCaptcha token, or null if captcha is not configured.
  * Waits for the widget to finish rendering if it has not yet (handles slow script loads).
  * Rejects with 'captcha-concurrent' if a token request is already in-flight.
- * Rejects with 'captcha-timeout' if the widget does not respond within 15 seconds.
+ * Rejects with 'captcha-timeout' if the challenge does not complete within 90 seconds
+ * after the widget is ready (the timer starts after widget load, not before).
  */
 function getCaptchaToken() {
     if (!captchaSiteKey) return Promise.resolve(null);
@@ -76,41 +77,45 @@ function getCaptchaToken() {
     captchaPending = true;
     const requestGeneration = ++captchaRequestGeneration;
 
-    let timeoutId;
-
     // Chain onto captchaWidgetReady so calls made before the widget finishes loading
     // wait rather than immediately returning null and causing a 403.
-    const tokenPromise = captchaWidgetReady.then(() => new Promise((resolve, reject) => {
+    // The challenge timeout starts only after the widget is ready so script-load time
+    // does not eat into the window available for completing an interactive challenge.
+    return captchaWidgetReady.then(() => {
         if (requestGeneration !== captchaRequestGeneration) {
-            reject(new Error('captcha-stale'));
-            return;
-        }
-        captchaTokenResolve = (token) => {
-            captchaPending = false;
-            clearTimeout(timeoutId); // cancel lingering timer so it can't corrupt the next call
-            resolve(token);
-        };
-        captchaTokenReject  = (err) => {
             captchaPending = false;
-            clearTimeout(timeoutId);
-            reject(err);
-        };
-        window.hcaptcha.execute(captchaWidgetId);
-    }));
-
-    const timeoutPromise = new Promise((_, reject) => {
-        // timeoutId is assigned synchronously here, before captchaTokenResolve can fire
-        timeoutId = setTimeout(() => {
-            if (requestGeneration !== captchaRequestGeneration) return;
-            captchaRequestGeneration++;
-            captchaPending = false;
-            captchaTokenResolve = null;
-            captchaTokenReject  = null;
-            reject(new Error('captcha-timeout'));
-        }, CAPTCHA_TIMEOUT_MS);
-    });
+            return Promise.reject(new Error('captcha-stale'));
+        }
+
+        let timeoutId;
 
-    return Promise.race([tokenPromise, timeoutPromise]);
+        const tokenPromise = new Promise((resolve, reject) => {
+            captchaTokenResolve = (token) => {
+                captchaPending = false;
+                clearTimeout(timeoutId); // cancel lingering timer so it can't corrupt the next call
+                resolve(token);
+            };
+            captchaTokenReject  = (err) => {
+                captchaPending = false;
+                clearTimeout(timeoutId);
+                reject(err);
+            };
+            window.hcaptcha.execute(captchaWidgetId);
+        });
+
+        const timeoutPromise = new Promise((_, reject) => {
+            timeoutId = setTimeout(() => {
+                if (requestGeneration !== captchaRequestGeneration) return;
+                captchaRequestGeneration++;
+                captchaPending = false;
+                captchaTokenResolve = null;
+                captchaTokenReject  = null;
+                reject(new Error('captcha-timeout'));
+            }, CAPTCHA_TIMEOUT_MS);
+        });
+
+        return Promise.race([tokenPromise, timeoutPromise]);
+    });
 }
 
 function resetCaptchaWidget() {

From b764b8df97254b2f1c896eba65166840b84fb903 Mon Sep 17 00:00:00 2001
From: Benjamin Michaelis <git@relay.benjamin.michaelis.net>
Date: Sat, 16 May 2026 22:50:32 -0700
Subject: [PATCH 8/9] simplify: remove captcha timeout in favour of hCaptcha
 callbacks

hCaptcha already fires error-callback and expired-callback in all failure
cases, so the manual setTimeout was redundant complexity. Removing it
simplifies getCaptchaToken() and avoids the arbitrary timeout value debate.
---
 EssentialCSharp.Web/wwwroot/js/chat-module.js | 27 +++----------------
 1 file changed, 3 insertions(+), 24 deletions(-)

diff --git a/EssentialCSharp.Web/wwwroot/js/chat-module.js b/EssentialCSharp.Web/wwwroot/js/chat-module.js
index 49fd375d..ee7048f4 100644
--- a/EssentialCSharp.Web/wwwroot/js/chat-module.js
+++ b/EssentialCSharp.Web/wwwroot/js/chat-module.js
@@ -20,7 +20,6 @@ let captchaTokenResolve = null;
 let captchaTokenReject = null;
 let captchaPending = false; // prevents concurrent token requests overwriting promise callbacks
 let captchaRequestGeneration = 0;
-const CAPTCHA_TIMEOUT_MS = 90_000;
 
 // Resolves once the widget has rendered. getCaptchaToken() awaits this so a user who
 // submits before hCaptcha finishes loading waits (up to 15 s) rather than getting a 403.
@@ -68,8 +67,7 @@ function initCaptchaWidget() {
  * Returns a fresh hCaptcha token, or null if captcha is not configured.
  * Waits for the widget to finish rendering if it has not yet (handles slow script loads).
  * Rejects with 'captcha-concurrent' if a token request is already in-flight.
- * Rejects with 'captcha-timeout' if the challenge does not complete within 90 seconds
- * after the widget is ready (the timer starts after widget load, not before).
+ * Rejects with 'captcha-expired' or 'captcha-error' via hCaptcha's own callbacks.
  */
 function getCaptchaToken() {
     if (!captchaSiteKey) return Promise.resolve(null);
@@ -79,42 +77,23 @@ function getCaptchaToken() {
 
     // Chain onto captchaWidgetReady so calls made before the widget finishes loading
     // wait rather than immediately returning null and causing a 403.
-    // The challenge timeout starts only after the widget is ready so script-load time
-    // does not eat into the window available for completing an interactive challenge.
     return captchaWidgetReady.then(() => {
         if (requestGeneration !== captchaRequestGeneration) {
             captchaPending = false;
             return Promise.reject(new Error('captcha-stale'));
         }
 
-        let timeoutId;
-
-        const tokenPromise = new Promise((resolve, reject) => {
+        return new Promise((resolve, reject) => {
             captchaTokenResolve = (token) => {
                 captchaPending = false;
-                clearTimeout(timeoutId); // cancel lingering timer so it can't corrupt the next call
                 resolve(token);
             };
-            captchaTokenReject  = (err) => {
+            captchaTokenReject = (err) => {
                 captchaPending = false;
-                clearTimeout(timeoutId);
                 reject(err);
             };
             window.hcaptcha.execute(captchaWidgetId);
         });
-
-        const timeoutPromise = new Promise((_, reject) => {
-            timeoutId = setTimeout(() => {
-                if (requestGeneration !== captchaRequestGeneration) return;
-                captchaRequestGeneration++;
-                captchaPending = false;
-                captchaTokenResolve = null;
-                captchaTokenReject  = null;
-                reject(new Error('captcha-timeout'));
-            }, CAPTCHA_TIMEOUT_MS);
-        });
-
-        return Promise.race([tokenPromise, timeoutPromise]);
     });
 }
 

From 48cd8fc208c857077ab2368f7d5f831220e310ff Mon Sep 17 00:00:00 2001
From: Benjamin Michaelis <git@relay.benjamin.michaelis.net>
Date: Sat, 16 May 2026 23:18:51 -0700
Subject: [PATCH 9/9] fix: address latest captcha review feedback

- Add bounded hCaptcha widget-ready wait (15s) to avoid indefinite pending
  chat requests when the third-party script is blocked or never loads
- Pass the request cancellation token into stream endpoint captcha error
  writes to stop writing to aborted responses on client disconnect
- Emit chat hCaptcha site key to the client only when both SecretKey and
  SiteKey are configured, keeping client/server captcha enablement aligned
---
 .../Controllers/ChatController.cs             |  4 ++--
 .../Views/Shared/_Layout.cshtml               |  6 +++++-
 EssentialCSharp.Web/wwwroot/js/chat-module.js | 21 ++++++++++++++++---
 3 files changed, 25 insertions(+), 6 deletions(-)

diff --git a/EssentialCSharp.Web/Controllers/ChatController.cs b/EssentialCSharp.Web/Controllers/ChatController.cs
index 1d7d7185..08f0d29a 100644
--- a/EssentialCSharp.Web/Controllers/ChatController.cs
+++ b/EssentialCSharp.Web/Controllers/ChatController.cs
@@ -134,13 +134,13 @@ public async Task StreamMessage([FromBody] ChatMessageRequest request, Cancellat
         if (captchaValid is null)
         {
             Response.StatusCode = 503;
-            await Response.WriteAsJsonAsync(new { error = "Human verification is temporarily unavailable. Please try again later.", errorCode = "captcha_unavailable" }, CancellationToken.None);
+            await Response.WriteAsJsonAsync(new { error = "Human verification is temporarily unavailable. Please try again later.", errorCode = "captcha_unavailable" }, cancellationToken);
             return;
         }
         if (!captchaValid.Value)
         {
             Response.StatusCode = 403;
-            await Response.WriteAsJsonAsync(new { error = "Human verification required.", errorCode = "captcha_failed" }, CancellationToken.None);
+            await Response.WriteAsJsonAsync(new { error = "Human verification required.", errorCode = "captcha_failed" }, cancellationToken);
             return;
         }
 
diff --git a/EssentialCSharp.Web/Views/Shared/_Layout.cshtml b/EssentialCSharp.Web/Views/Shared/_Layout.cshtml
index 02e649a9..816c6a6a 100644
--- a/EssentialCSharp.Web/Views/Shared/_Layout.cshtml
+++ b/EssentialCSharp.Web/Views/Shared/_Layout.cshtml
@@ -184,6 +184,10 @@
             var buildLabel = ReleaseDateAttribute.GetReleaseDate() is DateTime date
                 ? TimeZoneInfo.ConvertTimeFromUtc(date, TimeZoneInfo.FindSystemTimeZoneById("Pacific Standard Time")).ToString("d MMM, yyyy h:mm:ss tt", CultureInfo.InvariantCulture)
                 : null;
+            var chatCaptchaSiteKey = !string.IsNullOrWhiteSpace(_CaptchaOptions.Value.SecretKey)
+                && !string.IsNullOrWhiteSpace(_CaptchaOptions.Value.SiteKey)
+                ? _CaptchaOptions.Value.SiteKey
+                : null;
         }
         window.PERCENT_COMPLETE = @Json.Serialize(percentComplete);
         window.PREVIOUS_PAGE = @Json.Serialize(ViewBag.PreviousPage);
@@ -194,7 +198,7 @@
         window.TRYDOTNET_ORIGIN = @Json.Serialize(Configuration["TryDotNet:Origin"]);
         window.BUILD_LABEL = @Json.Serialize(buildLabel);
         window.ENABLE_CHAT_WIDGET = @Json.Serialize(!Context.Request.Path.StartsWithSegments("/Identity"));
-        window.HCAPTCHA_SITE_KEY = @Json.Serialize(_CaptchaOptions.Value.SiteKey);
+        window.HCAPTCHA_SITE_KEY = @Json.Serialize(chatCaptchaSiteKey);
     </script>
     <script src="~/dist/assets/site-shell.js" type="module" asp-append-version="true"></script>
 </body>
diff --git a/EssentialCSharp.Web/wwwroot/js/chat-module.js b/EssentialCSharp.Web/wwwroot/js/chat-module.js
index ee7048f4..fae834df 100644
--- a/EssentialCSharp.Web/wwwroot/js/chat-module.js
+++ b/EssentialCSharp.Web/wwwroot/js/chat-module.js
@@ -20,14 +20,25 @@ let captchaTokenResolve = null;
 let captchaTokenReject = null;
 let captchaPending = false; // prevents concurrent token requests overwriting promise callbacks
 let captchaRequestGeneration = 0;
+const CAPTCHA_WIDGET_READY_TIMEOUT_MS = 15_000;
 
-// Resolves once the widget has rendered. getCaptchaToken() awaits this so a user who
-// submits before hCaptcha finishes loading waits (up to 15 s) rather than getting a 403.
+// Resolves once the widget has rendered.
 let captchaWidgetReadyResolve = null;
 const captchaWidgetReady = captchaSiteKey
     ? new Promise((resolve) => { captchaWidgetReadyResolve = resolve; })
     : Promise.resolve();
 
+function awaitCaptchaWidgetReady() {
+    if (!captchaSiteKey) return Promise.resolve();
+    if (captchaWidgetId !== null) return Promise.resolve();
+
+    const timeoutPromise = new Promise((_, reject) => {
+        setTimeout(() => reject(new Error('captcha-unavailable')), CAPTCHA_WIDGET_READY_TIMEOUT_MS);
+    });
+
+    return Promise.race([captchaWidgetReady, timeoutPromise]);
+}
+
 function initCaptchaWidget() {
     if (!captchaSiteKey) return;
     // Guard: only render once (widget lives outside the v-if dialog overlay)
@@ -67,6 +78,7 @@ function initCaptchaWidget() {
  * Returns a fresh hCaptcha token, or null if captcha is not configured.
  * Waits for the widget to finish rendering if it has not yet (handles slow script loads).
  * Rejects with 'captcha-concurrent' if a token request is already in-flight.
+ * Rejects with 'captcha-unavailable' if the widget never becomes ready.
  * Rejects with 'captcha-expired' or 'captcha-error' via hCaptcha's own callbacks.
  */
 function getCaptchaToken() {
@@ -77,7 +89,7 @@ function getCaptchaToken() {
 
     // Chain onto captchaWidgetReady so calls made before the widget finishes loading
     // wait rather than immediately returning null and causing a 403.
-    return captchaWidgetReady.then(() => {
+    return awaitCaptchaWidgetReady().then(() => {
         if (requestGeneration !== captchaRequestGeneration) {
             captchaPending = false;
             return Promise.reject(new Error('captcha-stale'));
@@ -94,6 +106,9 @@ function getCaptchaToken() {
             };
             window.hcaptcha.execute(captchaWidgetId);
         });
+    }).catch((error) => {
+        captchaPending = false;
+        throw error;
     });
 }