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

Author: BenjaminMichaelis

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);
 

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);
     }