fix: captcha dev bypass and HTTP/2 connection header

- ChatController: inject IOptions<CaptchaOptions>; skip captcha check entirely when SiteKey is not configured (local dev without hCaptcha secrets)
- ChatController: wrap CaptchaService.VerifyAsync in try-catch to fail-open on InvalidOperationException (missing SecretKey)
- ChatController: remove Response.Headers.Connection = keep-alive (invalid in HTTP/2, generated ASP.NET warnings)
- chat-module.js: getFreshCaptchaToken returns null (not throws) when HCAPTCHA_SITE_KEY is falsy
- chat-module.js: fetchChatStream omits captchaToken from body when null so server bypass fires correctly

feat: add hCaptcha test keys for local development

Use official hCaptcha test keypair (https://docs.hcaptcha.com/#integration-testing-test-keys)
in appsettings.Development.json so all devs get working captcha out of the box without
configuring secrets. Test keys always pass silently  no challenge is shown.

- SiteKey:   10000000-ffff-ffff-ffff-000000000001
- SecretKey: 0x0000000000000000000000000000000000000000

These are public constants from hCaptcha docs; committing them is intentional and safe.
Production keys must be set via 'aspire secret set' and will override these defaults.

fix: remove unsafe captcha bypass

Now that appsettings.Development.json has official hCaptcha test keys,
the 'skip when SiteKey not configured' bypass is both unnecessary and dangerous
 a misconfigured production deploy would silently allow all requests.

- ChatController: remove IOptions<CaptchaOptions> injection and SiteKey bypass block
- ChatController: remove try-catch around VerifyAsync (InvalidOperationException from
  missing SecretKey should surface as 500, not be silently swallowed with fail-open)
- chat-module.js: remove null-return bypass in getFreshCaptchaToken
- chat-module.js: restore direct captchaToken in fetchChatStream body

If hCaptcha is misconfigured in production:
  server: throws InvalidOperationException -> 500 (loud, ops must fix)
  client: throws 'Captcha is not configured.' -> shows error to user (not silent)

Author: BenjaminMichaelis

EssentialCSharp.Web/Controllers/ChatController.cs

@@ -1,5 +1,6 @@
 using System.Text.Json;
 using EssentialCSharp.Chat.Common.Services;
+using EssentialCSharp.Web.Services;
 using Microsoft.AspNetCore.Authorization;
 using Microsoft.AspNetCore.Mvc;
 using Microsoft.AspNetCore.RateLimiting;
@@ -13,17 +14,22 @@ namespace EssentialCSharp.Web.Controllers;
 public class ChatController : ControllerBase
 {
     private readonly IAIChatService _AiChatService;
+    private readonly ICaptchaService _CaptchaService;
     private readonly ILogger<ChatController> _Logger;
 
-    public ChatController(ILogger<ChatController> logger, IAIChatService aiChatService)
+    public ChatController(ILogger<ChatController> logger, IAIChatService aiChatService, ICaptchaService captchaService)
     {
         _AiChatService = aiChatService;
+        _CaptchaService = captchaService;
         _Logger = logger;
     }
 
     [HttpPost("message")]
     public async Task<IActionResult> SendMessage([FromBody] ChatMessageRequest request, CancellationToken cancellationToken = default)
     {
+        var (captchaOk, captchaError) = await VerifyCaptchaAsync(request.CaptchaToken, cancellationToken);
+        if (!captchaOk) return captchaError!;
+
         request.Message = request.Message.Trim();
         if (string.IsNullOrEmpty(request.Message))
             return BadRequest(new { error = "Message cannot be empty." });
@@ -49,6 +55,18 @@ public async Task<IActionResult> SendMessage([FromBody] ChatMessageRequest reque
     [HttpPost("stream")]
     public async Task StreamMessage([FromBody] ChatMessageRequest request, CancellationToken cancellationToken = default)
     {
+        // Captcha and input validation must happen before SSE headers are set,
+        // so we can still return a proper HTTP status code on failure.
+        var (captchaOk, captchaError) = await VerifyCaptchaAsync(request.CaptchaToken, cancellationToken);
+        if (!captchaOk)
+        {
+            Response.StatusCode = captchaError is ObjectResult obj ? obj.StatusCode ?? 403 : 403;
+            await Response.WriteAsJsonAsync(
+                captchaError is ObjectResult { Value: not null } r ? r.Value : new { error = "Captcha verification failed." },
+                CancellationToken.None);
+            return;
+        }
+
         request.Message = request.Message.Trim();
         if (string.IsNullOrEmpty(request.Message))
         {
@@ -63,7 +81,6 @@ public async Task StreamMessage([FromBody] ChatMessageRequest request, Cancellat
 
         Response.ContentType = "text/event-stream";
         Response.Headers.CacheControl = "no-cache";
-        Response.Headers.Connection = "keep-alive";
 
         try
         {
@@ -113,4 +130,32 @@ public async Task StreamMessage([FromBody] ChatMessageRequest request, Cancellat
             catch { /* client already disconnected */ }
         }
     }
+
+    /// <summary>
+    /// Verifies the hCaptcha token. Fails-open on service outage (returns success with warning)
+    /// since the endpoint is already protected by [Authorize] and rate limiting.
+    /// </summary>
+    private async Task<(bool Success, IActionResult? Error)> VerifyCaptchaAsync(
+        string? captchaToken, CancellationToken cancellationToken)
+    {
+        if (string.IsNullOrWhiteSpace(captchaToken))
+            return (false, StatusCode(StatusCodes.Status403Forbidden,
+                new { error = "Captcha verification required.", errorCode = "captcha_required", retryable = true }));
+
+        var remoteIp = HttpContext.Connection.RemoteIpAddress?.ToString();
+        var result = await _CaptchaService.VerifyAsync(captchaToken, remoteIp, cancellationToken);
+
+        if (result is null)
+        {
+            // hCaptcha service is unreachable — fail-open since [Authorize] + rate limiting still protect the endpoint.
+            _Logger.LogWarning("hCaptcha service unavailable for user {User} — allowing request", User.Identity?.Name);
+            return (true, null);
+        }
+
+        if (!result.Success)
+            return (false, StatusCode(StatusCodes.Status403Forbidden,
+                new { error = "Captcha verification failed.", errorCode = "captcha_failed", retryable = true }));
+
+        return (true, null);
+    }
 }

EssentialCSharp.Web/Controllers/ChatMessageRequest.cs

@@ -10,5 +10,7 @@ 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
+
+    [StringLength(4096)]
+    public string? CaptchaToken { get; set; }
 }

EssentialCSharp.Web/Views/Shared/_Layout.cshtml

@@ -192,3 +192,4 @@
     <script src="~/dist/assets/site-shell.js" type="module" asp-append-version="true"></script>
 </body>
 </html>
+

EssentialCSharp.Web/appsettings.Development.json

@@ -11,5 +11,9 @@
   },
   "SiteSettings": {
     "BaseUrl": "https://localhost:7184"
+  },
+  "HCaptcha": {
+    "SiteKey": "10000000-ffff-ffff-ffff-000000000001",
+    "SecretKey": "0x0000000000000000000000000000000000000000"
   }
 }

EssentialCSharp.Web/wwwroot/js/chat-module.js

@@ -16,6 +16,12 @@ export function useChatWidget() {
     const chatInputField = ref(null);
     const lastResponseId = ref(null);
 
+    // hCaptcha invisible widget state
+    const captchaContainerEl = ref(null);
+    let captchaWidgetId = null;
+    let captchaResolve = null;
+    let captchaReject = null;
+
     // Load chat history from localStorage on initialization
     function loadChatHistory() {
         try {
@@ -109,6 +115,67 @@ export function useChatWidget() {
     }
 
     // Remove captcha callback functions as they're no longer needed for chat
+
+    // hCaptcha invisible widget — programmatic callbacks (not string-based data-callback attributes)
+    function onCaptchaSuccess(token) {
+        if (captchaResolve) {
+            captchaResolve(token);
+            captchaResolve = null;
+            captchaReject = null;
+        }
+    }
+
+    function onCaptchaExpired() {
+        if (captchaReject) {
+            captchaReject(new Error('Captcha expired'));
+            captchaResolve = null;
+            captchaReject = null;
+        }
+    }
+
+    function onCaptchaError() {
+        if (captchaReject) {
+            captchaReject(new Error('Captcha error'));
+            captchaResolve = null;
+            captchaReject = null;
+        }
+    }
+
+    async function ensureCaptchaWidget() {
+        if (!window.HCAPTCHA_SITE_KEY) throw new Error('Captcha is not configured.');
+        await nextTick();
+        if (!window.hcaptcha?.render) throw new Error('Captcha script is not ready.');
+        if (captchaWidgetId !== null) return;
+
+        captchaWidgetId = window.hcaptcha.render(captchaContainerEl.value, {
+            sitekey: window.HCAPTCHA_SITE_KEY,
+            size: 'invisible',
+            callback: onCaptchaSuccess,
+            'expired-callback': onCaptchaExpired,
+            'error-callback': onCaptchaError
+        });
+    }
+
+    async function getFreshCaptchaToken() {
+        await ensureCaptchaWidget();
+
+        return await new Promise((resolve, reject) => {
+            captchaResolve = resolve;
+            captchaReject = reject;
+
+            window.hcaptcha.reset(captchaWidgetId);
+            window.hcaptcha.execute(captchaWidgetId);
+
+            // Safety timeout — should not normally be reached
+            setTimeout(() => {
+                if (captchaReject) {
+                    captchaReject(new Error('Captcha timed out'));
+                    captchaResolve = null;
+                    captchaReject = null;
+                }
+            }, 15000);
+        });
+    }
     // The captcha service can still be used elsewhere in the application
 
     function scrollToBottom() {
@@ -182,7 +249,24 @@ export function useChatWidget() {
             saveChatHistory();
             return;
         }
-        
+
+        // Acquire captcha token BEFORE mutating UI state — so if captcha fails the user
+        // message is still in the input and nothing is incorrectly shown in the chat history.
+        let captchaToken;
+        try {
+            captchaToken = await getFreshCaptchaToken();
+        } catch (captchaErr) {
+            console.warn('Captcha acquisition failed:', captchaErr);
+            chatMessages.value.push({
+                role: 'error',
+                errorType: 'captcha-error',
+                content: 'Security verification failed. Please refresh the page and try again.',
+                timestamp: new Date().toISOString()
+            });
+            saveChatHistory();
+            return;
+        }
+
         chatInput.value = '';
 
         // Add user message
@@ -191,6 +275,7 @@ export function useChatWidget() {
             content: userMessage,
             timestamp: new Date().toISOString()
         });
+        const userMessageIndex = chatMessages.value.length - 1;
 
         // Save immediately after adding user message
         saveChatHistory();
@@ -207,25 +292,37 @@ export function useChatWidget() {
 
         let reader = null;
         try {
-            const requestBody = {
-                message: userMessage,
-                enableContextualSearch: true,
-                previousResponseId: lastResponseId.value
-            };
-
-            const response = await fetch('/api/chat/stream', {
-                method: 'POST',
-                headers: {
-                    'Content-Type': 'application/json',
-                },
-                body: JSON.stringify(requestBody)
-            });
+            const response = await fetchChatStream(userMessage, captchaToken);
 
             if (!response.ok) {
                 if (response.status === 401) {
                     throw new Error('Authentication required');
+                } else if (response.status === 403) {
+                    // Captcha failed — try once more with a fresh token
+                    let errorData = {};
+                    try { errorData = await response.json(); } catch (_) {}
+
+                    if (errorData.retryable) {
+                        let retryToken;
+                        try {
+                            retryToken = await getFreshCaptchaToken();
+                        } catch (_) {
+                            throw new Error('captcha-failed');
+                        }
+
+                        const retryResponse = await fetchChatStream(userMessage, retryToken);
+                        if (!retryResponse.ok) {
+                            // Remove optimistic user message and restore input
+                            chatMessages.value.splice(userMessageIndex, 1);
+                            chatInput.value = userMessage;
+                            throw new Error('captcha-failed');
+                        }
+                        // Use retry response for the rest of the streaming flow
+                        reader = retryResponse.body.getReader();
+                    } else {
+                        throw new Error('captcha-failed');
+                    }
                 } else if (response.status === 429) {
-                    // Handle rate limiting - simple error message without captcha
                     let errorData;
                     try {
                         errorData = await response.json();
@@ -237,19 +334,16 @@ export function useChatWidget() {
                     }
 
                     const retryAfter = errorData.retryAfter || 60;
-                    const errorMessage = `Rate limit exceeded. Please wait ${Math.ceil(retryAfter)} seconds before sending another message.`;
-                    
-                    throw new Error(errorMessage);
+                    throw new Error(`Rate limit exceeded. Please wait ${Math.ceil(retryAfter)} seconds before sending another message.`);
                 } else if (response.status === 400) {
-                    // Handle validation errors
                     const errorData = await response.json();
                     throw new Error(errorData.error || 'Bad request');
                 }
                 throw new Error(`HTTP error! status: ${response.status}`);
             }
 
             // Handle streaming response
-            reader = response.body.getReader();
+            if (!reader) reader = response.body.getReader();
             const decoder = new TextDecoder();
             let assistantMessage = '';
             let assistantMessageIndex = -1;
@@ -321,6 +415,9 @@ export function useChatWidget() {
             if (error.name === 'AbortError') {
                 errorMessage = 'Request was cancelled. Please try again.';
                 errorType = 'error';
+            } else if (error.message === 'captcha-failed') {
+                errorMessage = 'Security verification failed. Please try again.';
+                errorType = 'captcha-error';
             } else if (error.message?.includes('Authentication required')) {
                 errorMessage = 'You must be logged in to use the chat feature. Please log in and try again.';
                 errorType = 'auth-error';
@@ -365,6 +462,19 @@ export function useChatWidget() {
         }
     }
 
+    function fetchChatStream(message, captchaToken) {
+        return fetch('/api/chat/stream', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                message,
+                enableContextualSearch: true,
+                previousResponseId: lastResponseId.value,
+                captchaToken
+            })
+        });
+    }
+
     // Clean up old chat sessions (keep only last 7 days)
     function cleanupOldSessions() {
         try {
@@ -396,6 +506,7 @@ export function useChatWidget() {
         isTyping,
         chatMessagesEl,
         chatInputField,
+        captchaContainerEl,
 
         // Methods
         openChatDialog,