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

Author: BenjaminMichaelis

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

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

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>

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>

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,