Contact: Friendly Captcha v2, opstartvalidatie, ASF-host met Contact-module en hosttests (CMS-U9)

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-10 23:06:23 +01:00
co-authored by Claude Sonnet 5.5
parent f43e00733a
commit 3275092401
20 changed files with 1052 additions and 21 deletions
@@ -0,0 +1,264 @@
using System.Net;
using System.Net.Http.Json;
using System.Text;
using System.Text.Json;
using System.Text.RegularExpressions;
using FluentAssertions;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc.Testing;
using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using SlpModularCms.Modules.Contact.Data;
using SlpModularCms.Modules.Contact.Data.Entities;
namespace SlpModularCms.Api.AndreaSlopFotografie.Tests;
/// <summary>
/// The real Andrea Slop Fotografie host with the Contact module, against a real MariaDB/MySQL (like the other
/// host tests: set <c>ConnectionStrings__DefaultConnection</c> to a server you may create databases on; every
/// factory uses its own throw-away database).
/// </summary>
public class AsfContactHostFactory : WebApplicationFactory<Program>
{
private readonly Dictionary<string, string?> _settings;
private readonly string _databaseName = "AsfContactHost_" + Guid.NewGuid().ToString("N")[..12];
/// <summary>When set, the pipeline sees this as the TCP peer (the reverse proxy) of every request.</summary>
public string? PeerAddress { get; init; }
public AsfContactHostFactory(Dictionary<string, string?>? settings = null) => _settings = settings ?? [];
private static string BaseConnectionString =>
Environment.GetEnvironmentVariable("ConnectionStrings__DefaultConnection")
?? throw new InvalidOperationException("Set ConnectionStrings__DefaultConnection to a MariaDB/MySQL server for the host tests.");
private string ConnectionString =>
Regex.IsMatch(BaseConnectionString, "Database=[^;]*", RegexOptions.IgnoreCase)
? Regex.Replace(BaseConnectionString, "Database=[^;]*", $"Database={_databaseName}", RegexOptions.IgnoreCase)
: $"{BaseConnectionString};Database={_databaseName}";
protected override void ConfigureWebHost(IWebHostBuilder builder)
{
builder.UseEnvironment("Development");
builder.ConfigureAppConfiguration((_, config) =>
{
var all = new Dictionary<string, string?>
{
["ConnectionStrings:DefaultConnection"] = ConnectionString,
["Availability:StatusCacheSeconds"] = "0",
};
foreach (var (key, value) in _settings) all[key] = value;
config.AddInMemoryCollection(all);
});
if (PeerAddress is not null)
{
// Stands in for the reverse proxy: the TCP peer of every request. Runs before the forwarded-headers step.
builder.ConfigureServices(services => services.AddTransient<IStartupFilter>(_ => new PeerFilter(PeerAddress)));
}
}
private sealed class PeerFilter(string address) : IStartupFilter
{
public Action<IApplicationBuilder> Configure(Action<IApplicationBuilder> next) => app =>
{
app.Use((context, nextMiddleware) =>
{
context.Connection.RemoteIpAddress = IPAddress.Parse(address);
return nextMiddleware();
});
next(app);
};
}
public async Task<T> WithDb<T>(Func<ContactDbContext, Task<T>> action)
{
await using var scope = Services.CreateAsyncScope();
return await action(scope.ServiceProvider.GetRequiredService<ContactDbContext>());
}
public async Task OpenCmsSwitchAsync()
{
_ = CreateClient(); // starts the host (migrates the contact tables)
await WithDb(async db =>
{
db.ContactSettings.Add(new ContactSettings { Enabled = true, UpdatedAt = DateTimeOffset.UtcNow, UpdatedByUserId = Guid.NewGuid() });
await db.SaveChangesAsync();
return 0;
});
}
protected override void Dispose(bool disposing)
{
if (disposing)
{
try
{
using var scope = Services.CreateScope();
scope.ServiceProvider.GetRequiredService<ContactDbContext>().Database.EnsureDeleted();
}
catch
{
// Best effort clean-up of the throw-away database.
}
}
base.Dispose(disposing);
}
}
/// <summary>The committed defaults, nothing overridden.</summary>
public sealed class AsfDefaultContactHostFactory() : AsfContactHostFactory(null);
internal static class ContactHttp
{
public const string Route = "/api/v1/contact-messages";
public static async Task<string> GetTokenAsync(HttpClient client, string? forwardedFor = null)
{
var request = new HttpRequestMessage(HttpMethod.Get, $"{Route}/token");
if (forwardedFor is not null) request.Headers.Add("X-Forwarded-For", forwardedFor);
var response = await client.SendAsync(request);
response.StatusCode.Should().Be(HttpStatusCode.OK);
using var json = JsonDocument.Parse(await response.Content.ReadAsStringAsync());
return json.RootElement.GetProperty("token").GetString()!;
}
public static Task<HttpResponseMessage> PostAsync(HttpClient client, string token, string name, string? forwardedFor = null)
{
var request = new HttpRequestMessage(HttpMethod.Post, Route)
{
Content = new StringContent(JsonSerializer.Serialize(new
{
name, email = "jan@example.nl", subject = "Portretfotografie", message = "Hallo", hpCheck = "", token,
}), Encoding.UTF8, "application/json"),
};
request.Headers.Add("Idempotency-Key", Guid.NewGuid().ToString());
if (forwardedFor is not null) request.Headers.Add("X-Forwarded-For", forwardedFor);
return client.SendAsync(request);
}
}
public class AsfContactDisabledByDefaultTests : IClassFixture<AsfDefaultContactHostFactory>
{
private readonly AsfDefaultContactHostFactory _factory;
public AsfContactDisabledByDefaultTests(AsfDefaultContactHostFactory factory) => _factory = factory;
[Fact]
public async Task TheCommittedDefaults_KeepTheContactModuleLoadedButClosed()
{
var client = _factory.CreateClient();
using var caps = JsonDocument.Parse(await client.GetStringAsync("/api/v1/System/capabilities"));
caps.RootElement.GetProperty("modules").EnumerateArray().Select(e => e.GetString()).Should().Contain("Contact");
var token = await client.GetAsync($"{ContactHttp.Route}/token");
token.StatusCode.Should().Be(HttpStatusCode.NotFound);
(await token.Content.ReadAsStringAsync()).Should().BeEmpty();
(await client.PostAsync(ContactHttp.Route, null)).StatusCode.Should().Be(HttpStatusCode.NotFound);
}
}
public class AsfContactGateTests : IClassFixture<AsfOpenContactHostFactory>
{
private readonly AsfOpenContactHostFactory _factory;
public AsfContactGateTests(AsfOpenContactHostFactory factory) => _factory = factory;
[Fact]
public async Task ThePublicContactRoutes_StayReachable_WhileTheCmsIsNotAvailable_ButTheManagementRoutesAreGated()
{
await _factory.OpenCmsSwitchAsync();
// Switch the CMS off through the availability state of the real database (status 1 = not available).
await _factory.WithDb(db => db.Database.ExecuteSqlRawAsync(
"INSERT INTO AvailabilityState (Id, Status, Message, LastUpdatedAt, UpdatedBy) VALUES (UUID(), 1, 'host test', NOW(), 'host test')"));
var client = _factory.CreateClient();
(await client.GetAsync($"{ContactHttp.Route}?pageSize=1")).StatusCode
.Should().Be(HttpStatusCode.ServiceUnavailable, "the gate really is closed for everything not marked public");
var token = await ContactHttp.GetTokenAsync(client);
var post = await ContactHttp.PostAsync(client, token, "ASF Gate");
post.StatusCode.Should().Be(HttpStatusCode.Accepted);
(await _factory.WithDb(db => db.ContactMessages.CountAsync(m => m.Name == "ASF Gate"))).Should().Be(1);
(await _factory.WithDb(db => db.ContactMessages.SingleAsync(m => m.Name == "ASF Gate"))).SiteId.Should().Be("andreaslop");
}
}
public sealed class AsfOpenContactHostFactory() : AsfContactHostFactory(new()
{
["Contact:Enabled"] = "true",
["Contact:MinSeconds"] = "0",
["RateLimiting:ContactForm:PermitLimit"] = "1000",
["RateLimiting:ContactToken:PermitLimit"] = "1000",
});
/// <summary>One form submission allowed per window: the buckets show who shares one.</summary>
public sealed class AsfBehindProxyWithKnownProxyFactory() : AsfContactHostFactory(new()
{
["Contact:Enabled"] = "true",
["Contact:MinSeconds"] = "0",
["RateLimiting:ContactForm:PermitLimit"] = "1",
["RateLimiting:ContactToken:PermitLimit"] = "1000",
});
public sealed class AsfBehindProxyWithoutKnownProxyFactory() : AsfContactHostFactory(new()
{
["Contact:Enabled"] = "true",
["Contact:MinSeconds"] = "0",
["RateLimiting:ContactForm:PermitLimit"] = "1",
["RateLimiting:ContactToken:PermitLimit"] = "1000",
});
public class AsfRateLimitBehindIisTests
{
[Fact]
public async Task WithTheProxyKnown_EachVisitorAddressHasItsOwnBucket()
{
// The proxy list is read while the host is being composed, before test configuration is applied, so (like in
// production) it comes from the environment: ForwardedHeaders__KnownProxies__0.
Environment.SetEnvironmentVariable("ForwardedHeaders__KnownProxies__0", "10.1.1.1");
try
{
await RunWithKnownProxyAsync();
}
finally
{
Environment.SetEnvironmentVariable("ForwardedHeaders__KnownProxies__0", null);
}
}
private static async Task RunWithKnownProxyAsync()
{
using var factory = new AsfBehindProxyWithKnownProxyFactory { PeerAddress = "10.1.1.1" };
await factory.OpenCmsSwitchAsync();
var client = factory.CreateClient();
var a1 = await ContactHttp.PostAsync(client, await ContactHttp.GetTokenAsync(client, "203.0.113.10"), "ASF A1", "203.0.113.10");
var a2 = await ContactHttp.PostAsync(client, await ContactHttp.GetTokenAsync(client, "203.0.113.10"), "ASF A2", "203.0.113.10");
var b1 = await ContactHttp.PostAsync(client, await ContactHttp.GetTokenAsync(client, "203.0.113.20"), "ASF B1", "203.0.113.20");
a1.StatusCode.Should().Be(HttpStatusCode.Accepted);
a2.StatusCode.Should().Be(HttpStatusCode.TooManyRequests, "the same visitor is limited");
b1.StatusCode.Should().Be(HttpStatusCode.Accepted, "another visitor has a bucket of their own");
}
[Fact]
public async Task WithoutKnownProxies_TheWholeSiteSharesOneBucket_WhichIsWhyItIsAReleaseCondition()
{
using var factory = new AsfBehindProxyWithoutKnownProxyFactory { PeerAddress = "10.1.1.1" };
await factory.OpenCmsSwitchAsync();
var client = factory.CreateClient();
var a = await ContactHttp.PostAsync(client, await ContactHttp.GetTokenAsync(client, "203.0.113.10"), "ASF Shared A", "203.0.113.10");
var b = await ContactHttp.PostAsync(client, await ContactHttp.GetTokenAsync(client, "203.0.113.20"), "ASF Shared B", "203.0.113.20");
a.StatusCode.Should().Be(HttpStatusCode.Accepted);
b.StatusCode.Should().Be(HttpStatusCode.TooManyRequests, "forwarded addresses are ignored without KnownProxies: everybody is the proxy");
}
}
@@ -66,6 +66,19 @@ public class HostConfigurationTests
config.GetSection("ForwardedHeaders:KnownProxies").Get<string[]>().Should().BeNullOrEmpty();
}
[Fact]
public void Contact_IsOffByDefault_ForTheRightSite_WithNoRecipientOrCaptchaSecretCommitted()
{
var config = Load();
config.GetValue<bool>("Contact:Enabled").Should().BeFalse();
config["Contact:SiteId"].Should().Be("andreaslop");
config.GetValue<bool>("Contact:Captcha:Enabled").Should().BeFalse();
config["Contact:RecipientEmail"].Should().BeNullOrEmpty("the address comes from the environment only");
config["Contact:Captcha:Secret"].Should().BeNullOrEmpty();
config["Contact:Captcha:SiteKey"].Should().BeNullOrEmpty();
}
[Fact]
public void Host_DoesNotReferenceMasterOrOfferingsModules()
{
@@ -18,14 +18,16 @@
</ItemGroup>
<!--
Deliberately Identity + Availability only: this client serves one prerendered website and its
admin. No Master (it is not a master/slave setup) and no Offerings (a SlpSoftware-specific
feature), so /api/v1/System/capabilities does not list them. Availability is kept because the
admin SPA reads the availability status.
Identity + Availability + Contact: this client serves one prerendered website and its admin.
No Master (it is not a master/slave setup) and no Offerings (a SlpSoftware-specific feature), so
/api/v1/System/capabilities does not list them. Availability is kept because the admin SPA reads
the availability status. Contact is the website's contact form; it stays completely inactive
(no routes, no database access) until Contact:Enabled=true, see Contact in appsettings.json.
-->
<ItemGroup>
<ProjectReference Include="..\SlpModularCms.Core\SlpModularCms.Core.csproj" />
<ProjectReference Include="..\SlpModularCms.Modules.Availability\SlpModularCms.Modules.Availability.csproj" />
<ProjectReference Include="..\SlpModularCms.Modules.Contact\SlpModularCms.Modules.Contact.csproj" />
<ProjectReference Include="..\SlpModularCms.Modules.Identity\SlpModularCms.Modules.Identity.csproj" />
</ItemGroup>
@@ -77,6 +77,24 @@
"Cors": {
"AllowedOrigins": []
},
// Contact form of the website. OFF: no routes, no database access, until it is released on purpose.
// Release conditions, in this order (see aidlc-docs/features/contact-forms-module/construction/phase-1-handoff.md):
// 1. ForwardedHeaders__KnownProxies__0 = the IP address of the reverse proxy (IIS). Without it every visitor
// reaches the API from the proxy's address and the whole site shares ONE rate-limit bucket.
// 2. Contact__RecipientEmail (environment variable only; no address belongs in this file) and working mail
// (Email__Smtp__*, App__PublicBaseUrl); the sender is the site's From address (Email:FromAddress or the
// value chosen in the site settings from Email:AllowedFromAddresses).
// 3. Captcha (recommended): Contact__Captcha__Enabled=true, Contact__Captcha__Provider=friendlycaptcha,
// Contact__Captcha__SiteKey, and the API key ONLY as the environment variable Contact__Captcha__Secret.
// 4. Contact__Enabled=true, then switch the form on in the admin (Berichten).
"Contact": {
"Enabled": false,
"SiteId": "andreaslop",
"MinSeconds": 3,
"Captcha": {
"Enabled": false
}
},
"RateLimiting": {
"Login": {
"PermitLimit": 5,
@@ -93,6 +111,18 @@
"OfferingsPublic": {
"PermitLimit": 120,
"WindowSeconds": 60
},
"ContactForm": {
"PermitLimit": 5,
"WindowSeconds": 600
},
"ContactToken": {
"PermitLimit": 20,
"WindowSeconds": 600
},
"ContactResend": {
"PermitLimit": 5,
"WindowSeconds": 600
}
},
"SecurityHeaders": {
@@ -107,6 +107,20 @@ public class ContactMailSenderTests
rig.Sent.TextBody.Should().Contain("regel2").And.Contain("Naam:");
}
[Fact]
public async Task ASubjectLabelWithSpecialCharacters_IsEncodedInTheBody_AndNeverReachesTheSubjectOrAHeader()
{
var rig = new Rig();
const string label = "Fotoshoot & <b>\"bruiloft\"</b> 'zomer'";
await rig.Build().SendAsync(Message(subject: label), CancellationToken.None);
rig.Sent!.Subject.Should().Be("Nieuw bericht via De Site");
rig.Sent.HtmlBody.Should().Contain("Fotoshoot &amp; &lt;b&gt;").And.NotContain("<b>\"bruiloft\"");
rig.Sent.TextBody.Should().Contain(" " + label);
rig.Sent.ReplyToAddress.Should().Be(Visitor);
}
[Fact]
public async Task English_UsesEnglishLabelsAndSubject()
{
@@ -0,0 +1,276 @@
using System.Net;
using System.Text;
using FluentAssertions;
using NSubstitute;
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Options;
using SlpModularCms.Modules.Contact.Config;
using SlpModularCms.Modules.Contact.Models;
using SlpModularCms.Modules.Contact.Services;
namespace SlpModularCms.Modules.Contact.Tests;
/// <summary>A stand-in for the provider: never touches the network. Records every request it receives.</summary>
public sealed class FakeCaptchaHandler(Func<HttpRequestMessage, CancellationToken, Task<HttpResponseMessage>> respond) : HttpMessageHandler
{
public List<(HttpRequestMessage Request, string Body)> Calls { get; } = [];
protected override async Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken cancellationToken)
{
var body = request.Content is null ? "" : await request.Content.ReadAsStringAsync(cancellationToken);
lock (Calls) Calls.Add((request, body));
return await respond(request, cancellationToken);
}
public static HttpResponseMessage Json(HttpStatusCode status, string json) =>
new(status) { Content = new StringContent(json, Encoding.UTF8, "application/json") };
public static FakeCaptchaHandler Always(HttpStatusCode status, string json) => new((_, _) => Task.FromResult(Json(status, json)));
}
public class FriendlyCaptchaVerifierTests
{
private const string Secret = "ZXQ-secret-key";
private const string SiteKey = "FCMZXQ-site";
private const string Token = "ZXQ-captcha-response";
private sealed class Factory(HttpMessageHandler handler) : IHttpClientFactory
{
public HttpClient CreateClient(string name) => new(handler, disposeHandler: false);
}
private readonly CapturingLoggerProvider _logs = new();
private FriendlyCaptchaVerifier Verifier(HttpMessageHandler handler, Action<ContactCaptchaOptions>? configure = null)
{
var captcha = new ContactCaptchaOptions
{
Enabled = true, Provider = "friendlycaptcha", SiteKey = SiteKey, Secret = Secret, TimeoutSeconds = 1,
};
configure?.Invoke(captcha);
return new FriendlyCaptchaVerifier(
new Factory(handler),
Options.Create(new ContactOptions { Enabled = true, Captcha = captcha }),
LoggerFactory.Create(b => b.AddProvider(_logs)).CreateLogger<FriendlyCaptchaVerifier>());
}
[Fact]
public async Task ASuccessfulAnswer_Passes_AndTheRequestIsExactlyWhatTheProviderExpects()
{
var handler = FakeCaptchaHandler.Always(HttpStatusCode.OK, """{"success":true,"data":{"event_id":"e"}}""");
(await Verifier(handler).VerifyAsync(Token, CancellationToken.None)).Should().BeTrue();
var (request, body) = handler.Calls.Should().ContainSingle().Subject;
request.Method.Should().Be(HttpMethod.Post);
request.RequestUri!.ToString().Should().Be("https://global.frcapi.com/api/v2/captcha/siteverify");
request.Headers.GetValues("X-API-Key").Should().ContainSingle().Which.Should().Be(Secret);
request.Content!.Headers.ContentType!.MediaType.Should().Be("application/json");
body.Should().Be($$"""{"response":"{{Token}}","sitekey":"{{SiteKey}}"}""");
}
[Fact]
public async Task TheEuEndpoint_IsUsedWhenConfigured()
{
var handler = FakeCaptchaHandler.Always(HttpStatusCode.OK, """{"success":true}""");
await Verifier(handler, c => c.VerifyUrl = "https://eu.frcapi.com/api/v2/captcha/siteverify")
.VerifyAsync(Token, CancellationToken.None);
handler.Calls.Single().Request.RequestUri!.Host.Should().Be("eu.frcapi.com");
}
[Theory]
[InlineData(HttpStatusCode.OK, """{"success":false,"error":{"error_code":"response_invalid","detail":"x"}}""")]
[InlineData(HttpStatusCode.OK, """{"success":false,"error":{"error_code":"response_duplicate"}}""")]
[InlineData(HttpStatusCode.OK, """{"success":false,"error":{"error_code":"response_timeout"}}""")]
[InlineData(HttpStatusCode.BadRequest, """{"success":false,"error":{"error_code":"response_missing"}}""")]
[InlineData(HttpStatusCode.BadRequest, """{"success":false,"error":{"error_code":"bad_request"}}""")]
[InlineData(HttpStatusCode.OK, "not json at all")]
[InlineData(HttpStatusCode.OK, "{}")]
public async Task ADefiniteNo_IsSpam(HttpStatusCode status, string json)
{
var handler = FakeCaptchaHandler.Always(status, json);
(await Verifier(handler).VerifyAsync(Token, CancellationToken.None)).Should().BeFalse();
}
[Theory]
[InlineData(HttpStatusCode.Unauthorized, """{"success":false,"error":{"error_code":"auth_invalid"}}""")]
[InlineData(HttpStatusCode.Forbidden, "")]
[InlineData(HttpStatusCode.BadRequest, """{"success":false,"error":{"error_code":"sitekey_invalid"}}""")]
public async Task OurOwnWrongKeyOrSiteKey_LetsTheVisitorThrough_AndLogsAnError(HttpStatusCode status, string json)
{
var handler = FakeCaptchaHandler.Always(status, json);
(await Verifier(handler).VerifyAsync(Token, CancellationToken.None)).Should().BeTrue();
_logs.Messages.Should().Contain(m => m.Contains("captcha_misconfigured"));
}
[Theory]
[InlineData(HttpStatusCode.InternalServerError)]
[InlineData(HttpStatusCode.BadGateway)]
[InlineData(HttpStatusCode.ServiceUnavailable)]
public async Task AProviderServerError_FailsOpen_WithAWarning(HttpStatusCode status)
{
var handler = FakeCaptchaHandler.Always(status, "");
(await Verifier(handler).VerifyAsync(Token, CancellationToken.None)).Should().BeTrue();
_logs.Messages.Should().Contain(m => m.Contains("captcha_unavailable"));
}
[Fact]
public async Task ATimeout_FailsOpen()
{
var handler = new FakeCaptchaHandler(async (_, ct) =>
{
await Task.Delay(TimeSpan.FromSeconds(30), ct);
return FakeCaptchaHandler.Json(HttpStatusCode.OK, """{"success":true}""");
});
var verdict = await Verifier(handler).VerifyAsync(Token, CancellationToken.None);
verdict.Should().BeTrue();
_logs.Messages.Should().Contain(m => m.Contains("captcha_unavailable") && m.Contains("timeout"));
}
[Fact]
public async Task ANetworkError_FailsOpen_AndTheLogHasNoUrlOrToken()
{
var handler = new FakeCaptchaHandler((_, _) => throw new HttpRequestException("cannot reach https://global.frcapi.com with " + Token));
(await Verifier(handler).VerifyAsync(Token, CancellationToken.None)).Should().BeTrue();
_logs.Messages.Should().NotContain(m => m.Contains(Token) || m.Contains("frcapi.com"));
}
[Fact]
public async Task ACallerCancellation_IsNotSwallowed()
{
var handler = new FakeCaptchaHandler(async (_, ct) =>
{
await Task.Delay(TimeSpan.FromSeconds(30), ct);
return FakeCaptchaHandler.Json(HttpStatusCode.OK, "{}");
});
using var cts = new CancellationTokenSource(TimeSpan.FromMilliseconds(50));
var act = async () => await Verifier(handler, c => c.TimeoutSeconds = 20).VerifyAsync(Token, cts.Token);
await act.Should().ThrowAsync<OperationCanceledException>();
}
[Theory]
[InlineData(null)]
[InlineData("")]
[InlineData(" ")]
public async Task AnEmptyToken_FailsWithoutCallingTheProvider(string? token)
{
var handler = FakeCaptchaHandler.Always(HttpStatusCode.OK, """{"success":true}""");
(await Verifier(handler).VerifyAsync(token, CancellationToken.None)).Should().BeFalse();
handler.Calls.Should().BeEmpty();
}
[Fact]
public async Task NeitherTheSecretNorTheTokenIsEverLogged()
{
foreach (var status in new[] { HttpStatusCode.OK, HttpStatusCode.Unauthorized, HttpStatusCode.InternalServerError })
{
await Verifier(FakeCaptchaHandler.Always(status, """{"success":false}""")).VerifyAsync(Token, CancellationToken.None);
}
_logs.Messages.Should().NotContain(m => m.Contains(Secret) || m.Contains(Token) || m.Contains(SiteKey));
}
}
public class ContactCaptchaOptionsTests
{
private static ContactCaptchaOptions Valid() => new()
{
Enabled = true, Provider = "friendlycaptcha", SiteKey = "FCM-site", Secret = "key",
};
[Fact]
public void WhileOff_NothingIsRequired() => new ContactCaptchaOptions().Problems().Should().BeEmpty();
[Fact]
public void ACompleteSetup_HasNoProblems() => Valid().Problems().Should().BeEmpty();
[Theory]
[InlineData("provider")]
[InlineData("sitekey")]
[InlineData("secret")]
[InlineData("url")]
[InlineData("timeout")]
public void EachMissingOrInvalidSetting_IsReportedByName_NeverByValue(string which)
{
var o = Valid();
switch (which)
{
case "provider": o.Provider = "other"; break;
case "sitekey": o.SiteKey = ""; break;
case "secret": o.Secret = null; break;
case "url": o.VerifyUrl = "http://insecure.example"; break;
default: o.TimeoutSeconds = 0; break;
}
var problems = o.Problems();
problems.Should().ContainSingle();
problems.Single().Should().Contain("Contact:Captcha:");
problems.Single().Should().NotContain("key").And.NotContain("insecure");
}
[Fact]
public void TheProviderNameIsCaseInsensitive()
{
var o = Valid();
o.Provider = "FriendlyCaptcha";
o.IsFriendlyCaptcha.Should().BeTrue();
}
}
public class CaptchaSubmissionRuleTests
{
[Fact]
public async Task WhileOn_AMissingToken_IsSpam_AndTheProviderIsNotAsked()
{
using var h = new SubmissionHarness(o => o.Captcha.Enabled = true);
var result = await h.Submit(SubmissionHarness.Request(h.MatureToken(), captcha: null));
result.Should().BeOfType<SubmissionResult.Received>();
(await h.Db.ContactMessages.ToListAsyncForTests()).Single().Status.Should().Be(Data.Entities.ContactMessageStatus.Spam);
await h.Captcha.DidNotReceiveWithAnyArgs().VerifyAsync(default, default);
}
[Fact]
public async Task WhileOn_APresentToken_GoesToTheProvider()
{
using var h = new SubmissionHarness(o => o.Captcha.Enabled = true);
await h.Submit(SubmissionHarness.Request(h.MatureToken(), captcha: "solved"));
await h.Captcha.Received(1).VerifyAsync("solved", Arg.Any<CancellationToken>());
(await h.Db.ContactMessages.ToListAsyncForTests()).Single().Status.Should().Be(Data.Entities.ContactMessageStatus.New);
}
[Fact]
public async Task WhileOff_NoTokenIsNeeded()
{
using var h = new SubmissionHarness();
await h.Submit(SubmissionHarness.Request(h.MatureToken()));
(await h.Db.ContactMessages.ToListAsyncForTests()).Single().Status.Should().Be(Data.Entities.ContactMessageStatus.New);
}
}
internal static class QueryExtensions
{
public static Task<List<T>> ToListAsyncForTests<T>(this IQueryable<T> source) =>
Microsoft.EntityFrameworkCore.EntityFrameworkQueryableExtensions.ToListAsync(source);
}
@@ -0,0 +1,181 @@
using System.Net;
using System.Text.Json;
using FluentAssertions;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.TestHost;
using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.DependencyInjection;
using SlpModularCms.Modules.Contact.Data.Entities;
using SlpModularCms.Modules.Contact.Services;
namespace SlpModularCms.Modules.Contact.Tests.Pipeline;
/// <summary>The real host with Friendly Captcha switched on and a fake provider (no network).</summary>
public sealed class CaptchaContactHostFactory() : ContactHostFactory(new()
{
["Contact:Enabled"] = "true",
["Contact:SiteId"] = "pipeline-site",
["Contact:MinSeconds"] = "0",
["Contact:Captcha:Enabled"] = "true",
["Contact:Captcha:Provider"] = "friendlycaptcha",
["Contact:Captcha:SiteKey"] = "FCMPIPELINEKEY",
["Contact:Captcha:Secret"] = "pipeline-secret-ZXQ",
["Contact:Captcha:VerifyUrl"] = "https://eu.frcapi.com/api/v2/captcha/siteverify",
["RateLimiting:ContactForm:PermitLimit"] = "1000",
["RateLimiting:ContactToken:PermitLimit"] = "1000",
})
{
/// <summary>What the fake provider answers next: status and JSON.</summary>
public volatile string Answer = """{"success":true}""";
public volatile int AnswerStatus = 200;
protected override bool OpenCmsSwitch => true;
protected override void ConfigureWebHost(IWebHostBuilder builder)
{
base.ConfigureWebHost(builder);
var handler = new FakeCaptchaHandler((_, _) =>
Task.FromResult(FakeCaptchaHandler.Json((HttpStatusCode)AnswerStatus, Answer)));
Handler = handler;
builder.ConfigureTestServices(services =>
services.AddHttpClient(FriendlyCaptchaVerifier.HttpClientName)
.ConfigurePrimaryHttpMessageHandler(() => handler));
}
public FakeCaptchaHandler Handler { get; private set; } = null!;
}
public class ContactCaptchaPipelineTests(CaptchaContactHostFactory factory) : IClassFixture<CaptchaContactHostFactory>
{
private static string Body(string token, string name, string? captchaToken, string subject = "website", string message = "Ik wil graag een offerte.") =>
JsonSerializer.Serialize(new
{
name, email = "jan@example.nl", subject, message, hpCheck = "", token, captchaToken,
});
private async Task<(HttpResponseMessage Response, ContactMessage Row)> SubmitAsync(string name, string? captchaToken, string subject = "website", string message = "Ik wil graag een offerte.")
{
var client = factory.CreateClient();
var token = await Http.GetTokenAsync(client);
var response = await Http.PostAsync(client, Body(token, name, captchaToken, subject, message));
var row = await factory.WithDb(db => db.ContactMessages.AsNoTracking().SingleAsync(m => m.Name == name));
return (response, row);
}
[Fact]
public async Task TheTokenResponse_AnnouncesTheProviderAndSiteKey_AndNothingElse()
{
var response = await factory.CreateClient().GetAsync($"{Http.Route}/token");
var text = await response.Content.ReadAsStringAsync();
using var json = JsonDocument.Parse(text);
var captcha = json.RootElement.GetProperty("captcha");
captcha.GetProperty("provider").GetString().Should().Be("friendlycaptcha");
captcha.GetProperty("siteKey").GetString().Should().Be("FCMPIPELINEKEY");
captcha.EnumerateObject().Should().HaveCount(2);
text.Should().NotContain("pipeline-secret-ZXQ").And.NotContain("frcapi.com");
}
[Fact]
public async Task AGoodAnswer_StoresAGenuineMessage_AndTheProviderGotTheKeyAndTheEuUrl()
{
factory.AnswerStatus = 200;
factory.Answer = """{"success":true}""";
var (response, row) = await SubmitAsync("Captcha Genuine", "solved-response");
response.StatusCode.Should().Be(HttpStatusCode.Accepted);
row.Status.Should().Be(ContactMessageStatus.New);
var (request, body) = factory.Handler.Calls.Last(c => c.Body.Contains("solved-response"));
request.RequestUri!.Host.Should().Be("eu.frcapi.com");
request.Headers.GetValues("X-API-Key").Single().Should().Be("pipeline-secret-ZXQ");
body.Should().Contain("FCMPIPELINEKEY");
}
[Fact]
public async Task ARejectedAnswer_IsSpam_WithTheSame202AndBodyAsAGenuineMessage()
{
factory.AnswerStatus = 200;
factory.Answer = """{"success":false,"error":{"error_code":"response_invalid"}}""";
var (spamResponse, spamRow) = await SubmitAsync("Captcha Spam", "bad-response");
factory.Answer = """{"success":true}""";
var (genuineResponse, _) = await SubmitAsync("Captcha Genuine Two", "good-response");
spamRow.Status.Should().Be(ContactMessageStatus.Spam);
spamRow.MailStatus.Should().Be(ContactMailStatus.NotApplicable);
spamResponse.StatusCode.Should().Be(HttpStatusCode.Accepted);
(await spamResponse.Content.ReadAsStringAsync()).Should().Be(await genuineResponse.Content.ReadAsStringAsync());
}
[Fact]
public async Task AMissingToken_IsSpam_Not400_AndTheProviderIsNotAsked()
{
var before = factory.Handler.Calls.Count;
var (response, row) = await SubmitAsync("Captcha Missing", null);
response.StatusCode.Should().Be(HttpStatusCode.Accepted);
row.Status.Should().Be(ContactMessageStatus.Spam);
factory.Handler.Calls.Count.Should().Be(before);
}
[Theory]
[InlineData(500)]
[InlineData(503)]
[InlineData(401)]
public async Task AProviderOutageOrOurWrongKey_FailsOpen_AndTheMessageIsGenuine(int status)
{
factory.AnswerStatus = status;
factory.Answer = "";
try
{
var (response, row) = await SubmitAsync($"Captcha Open {status}", "some-response");
response.StatusCode.Should().Be(HttpStatusCode.Accepted);
row.Status.Should().Be(ContactMessageStatus.New);
}
finally
{
factory.AnswerStatus = 200;
factory.Answer = """{"success":true}""";
}
}
[Fact]
public async Task ALabelWithSpecialCharacters_IsStoredAndListedAsTyped()
{
const string label = "Fotoshoot & <b>\"bruiloft\"</b> 'zomer'";
var (response, row) = await SubmitAsync("Captcha Label", "solved-response", subject: label, message: "Hallo <i>daar</i> & \"dag\"");
response.StatusCode.Should().Be(HttpStatusCode.Accepted);
row.Subject.Should().Be(label);
var admin = await Jwt.ClientWithRoleAsync(factory, "Administrator");
var list = await admin.GetStringAsync($"{Http.Route}?pageSize=100");
using var json = JsonDocument.Parse(list);
json.RootElement.GetProperty("items").EnumerateArray()
.Single(i => i.GetProperty("name").GetString() == "Captcha Label")
.GetProperty("subject").GetString().Should().Be(label);
}
}
public class CaptchaStartupTests
{
private sealed class MissingSecretFactory() : ContactHostFactory(new()
{
["Contact:Enabled"] = "true",
["Contact:Captcha:Enabled"] = "true",
["Contact:Captcha:Provider"] = "friendlycaptcha",
["Contact:Captcha:SiteKey"] = "FCMPIPELINEKEY",
});
[Fact]
public void ASwitchedOnCaptchaWithoutSecret_RefusesToStart_NamingTheSetting()
{
using var factory = new MissingSecretFactory();
var act = () => factory.CreateClient();
act.Should().Throw<Exception>()
.Where(e => e.ToString().Contains("Contact:Captcha:Secret") && !e.ToString().Contains("FCMPIPELINEKEY"));
}
}
@@ -73,12 +73,55 @@ public class ContactMailOptions
}
}
/// <summary>Start-up validation: only checks anything while the module and the captcha are switched on.</summary>
public sealed class ContactOptionsValidator : Microsoft.Extensions.Options.IValidateOptions<ContactOptions>
{
public Microsoft.Extensions.Options.ValidateOptionsResult Validate(string? name, ContactOptions options)
{
if (!options.Enabled) return Microsoft.Extensions.Options.ValidateOptionsResult.Success;
var problems = options.Captcha.Problems();
return problems.Count == 0
? Microsoft.Extensions.Options.ValidateOptionsResult.Success
: Microsoft.Extensions.Options.ValidateOptionsResult.Fail(problems);
}
}
public class ContactCaptchaOptions
{
public const string FriendlyCaptcha = "friendlycaptcha";
public const string DefaultVerifyUrl = "https://global.frcapi.com/api/v2/captcha/siteverify";
public bool Enabled { get; set; }
/// <summary>The captcha provider; the only supported value is <c>friendlycaptcha</c> (Friendly Captcha v2).</summary>
public string? Provider { get; set; }
/// <summary>Public site key; it is also sent to the browser in the token response.</summary>
public string? SiteKey { get; set; }
/// <summary>Server-side secret; supply it through the environment or a secrets manager, never committed.</summary>
/// <summary>Server-side API key; supply it through the environment (<c>Contact__Captcha__Secret</c>) or a secrets manager, never committed.</summary>
public string? Secret { get; set; }
/// <summary>Verify endpoint. Global by default; for the EU-only endpoint use <c>https://eu.frcapi.com/api/v2/captcha/siteverify</c>.</summary>
public string VerifyUrl { get; set; } = DefaultVerifyUrl;
/// <summary>A provider that does not answer within this time counts as passed (fail-open).</summary>
public int TimeoutSeconds { get; set; } = 3;
public bool IsFriendlyCaptcha =>
string.Equals(Provider?.Trim(), FriendlyCaptcha, StringComparison.OrdinalIgnoreCase);
/// <summary>The problems that stop the host from starting while the captcha is on (setting names only, never values).</summary>
public IReadOnlyList<string> Problems()
{
if (!Enabled) return [];
var problems = new List<string>();
if (!IsFriendlyCaptcha) problems.Add("Contact:Captcha:Provider must be 'friendlycaptcha'.");
if (string.IsNullOrWhiteSpace(SiteKey)) problems.Add("Contact:Captcha:SiteKey is required while the captcha is enabled.");
if (string.IsNullOrWhiteSpace(Secret)) problems.Add("Contact:Captcha:Secret is required while the captcha is enabled (environment variable Contact__Captcha__Secret).");
if (!Uri.TryCreate(VerifyUrl, UriKind.Absolute, out var uri) || uri.Scheme != Uri.UriSchemeHttps)
problems.Add("Contact:Captcha:VerifyUrl must be an absolute https URL.");
if (TimeoutSeconds is < 1 or > 30) problems.Add("Contact:Captcha:TimeoutSeconds must be between 1 and 30.");
return problems;
}
}
@@ -30,7 +30,10 @@ public class ContactModule : IModule
{
services.AddOptions<ContactOptions>()
.Configure<IConfiguration>((options, config) =>
config.GetSection(ContactOptions.SectionName).Bind(options));
config.GetSection(ContactOptions.SectionName).Bind(options))
.ValidateOnStart();
// A switched-on captcha with missing settings stops the host at start-up (setting names only, never a value).
services.AddSingleton<IValidateOptions<ContactOptions>, ContactOptionsValidator>();
services.AddDbContext<ContactDbContext>((serviceProvider, options) =>
{
@@ -43,7 +46,14 @@ public class ContactModule : IModule
services.AddScoped<IContactRepository, ContactRepository>();
services.AddScoped<IContactSubmissionService, ContactSubmissionService>();
services.AddSingleton<IContactTokenService, ContactTokenService>();
services.AddSingleton<ICaptchaVerifier, NullCaptchaVerifier>();
// Captcha: the provider is chosen by configuration; while it is off (or unset) everything passes.
services.AddHttpClient(FriendlyCaptchaVerifier.HttpClientName);
services.AddSingleton<FriendlyCaptchaVerifier>();
services.AddSingleton<NullCaptchaVerifier>();
services.AddSingleton<ICaptchaVerifier>(sp =>
sp.GetRequiredService<IOptions<ContactOptions>>().Value.Captcha is { Enabled: true, IsFriendlyCaptcha: true }
? sp.GetRequiredService<FriendlyCaptchaVerifier>()
: sp.GetRequiredService<NullCaptchaVerifier>());
// Mail: the request only stores and signals; the background service sends (and retries) with the host's mail pieces.
services.AddScoped<IContactMailSender, ContactMailSender>();
services.AddSingleton<IContactMailSignal, ContactMailSignal>();
@@ -37,8 +37,9 @@ public class ContactMessagesController(
public IActionResult GetToken()
{
var settings = options.Value;
var captcha = settings.Captcha is { Enabled: true } c && !string.IsNullOrWhiteSpace(c.Provider)
? new ContactCaptchaInfo(c.Provider!, c.SiteKey ?? string.Empty)
// Only a complete, supported captcha setup is announced; the secret and the verify URL are never part of a response.
var captcha = settings.Captcha is { Enabled: true, IsFriendlyCaptcha: true } c && !string.IsNullOrWhiteSpace(c.SiteKey)
? new ContactCaptchaInfo(ContactCaptchaOptions.FriendlyCaptcha, c.SiteKey!)
: null;
return Ok(new ContactTokenResponse(tokens.Issue(), settings.MinSeconds, captcha));
@@ -32,6 +32,7 @@ public sealed class ContactOpenApiDocumentTransformer : IOpenApiDocumentTransfor
if (document.Paths.TryGetValue(TokenPath, out var token) && token.Operations is not null
&& token.Operations.TryGetValue(HttpMethod.Get, out var getToken))
{
getToken.Description = "Returns a signed form token and the minimum number of seconds before a submission counts as human. 'captcha' is null while the captcha is off; otherwise it is { provider: \"friendlycaptcha\", siteKey } (Friendly Captcha v2), which the website widget needs. Nothing else about the captcha (secret, verify URL) is ever returned.";
getToken.Responses ??= [];
getToken.Responses["404"] = new OpenApiResponse { Description = "The contact form is closed on this site (the website shows its mailto fallback)." };
getToken.Responses["429"] = new OpenApiResponseReference("RateLimited", document);
@@ -126,6 +127,7 @@ public sealed class ContactOpenApiDocumentTransformer : IOpenApiDocumentTransfor
Schema = new OpenApiSchema { Type = JsonSchemaType.String, Format = "uuid" },
});
submit.Description = "Stores a message. While the captcha is on, 'captchaToken' (the widget response) is required: a missing, empty or rejected value is treated as spam and answered exactly like a genuine message (202, stored with status spam), never with a 400. A captcha provider that does not answer in time, or fails, lets the visitor through (fail-open).";
submit.Responses ??= [];
submit.Responses["400"] = new OpenApiResponseReference("Validation", document);
submit.Responses["404"] = new OpenApiResponse { Description = "The contact form is closed on this site (the website shows its mailto fallback)." };
@@ -90,7 +90,9 @@ public sealed class ContactSubmissionService(
// 4. Classify. A filled honeypot, a too-fast submission or a rejected captcha is spam.
var isSpam = tokenCheck == TokenCheck.TooYoung
|| !string.IsNullOrEmpty(request.HpCheck)
|| (o.Captcha.Enabled && !await captcha.VerifyAsync(request.CaptchaToken, cancellationToken));
|| (o.Captcha.Enabled
&& (string.IsNullOrWhiteSpace(request.CaptchaToken) // required while on: missing = spam, never a 400
|| !await captcha.VerifyAsync(request.CaptchaToken, cancellationToken)));
// 5. Store. Spam is kept for a short time (a real visitor may have tripped a check) but
// capped per day so a flood cannot fill the table.
@@ -0,0 +1,109 @@
using System.Net.Http.Json;
using System.Text.Json;
using System.Text.Json.Serialization;
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Options;
using SlpModularCms.Modules.Contact.Config;
namespace SlpModularCms.Modules.Contact.Services;
/// <summary>
/// Verifies a Friendly Captcha v2 response server-side (POST {VerifyUrl}, header <c>X-API-Key</c>, JSON
/// <c>{ response, sitekey }</c>). Only a definite negative answer counts as failed. Everything that is not the
/// visitor's fault (timeout, network error, 5xx, our own wrong key or site key) lets the visitor through and is logged
/// without personal data: the response token, the key and the secret are never logged.
/// </summary>
public sealed class FriendlyCaptchaVerifier(
IHttpClientFactory httpClients,
IOptions<ContactOptions> options,
ILogger<FriendlyCaptchaVerifier> logger) : ICaptchaVerifier
{
public const string HttpClientName = "contact-captcha";
public const string ApiKeyHeader = "X-API-Key";
private sealed record VerifyRequest(
[property: JsonPropertyName("response")] string Response,
[property: JsonPropertyName("sitekey")] string SiteKey);
private sealed class VerifyError
{
[JsonPropertyName("error_code")] public string? ErrorCode { get; set; }
}
private sealed class VerifyResponse
{
[JsonPropertyName("success")] public bool Success { get; set; }
[JsonPropertyName("error")] public VerifyError? Error { get; set; }
}
public async Task<bool> VerifyAsync(string? captchaToken, CancellationToken cancellationToken)
{
if (string.IsNullOrWhiteSpace(captchaToken))
{
return false;
}
var captcha = options.Value.Captcha;
using var timeout = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);
timeout.CancelAfter(TimeSpan.FromSeconds(Math.Clamp(captcha.TimeoutSeconds, 1, 30)));
try
{
using var request = new HttpRequestMessage(HttpMethod.Post, captcha.VerifyUrl)
{
Content = JsonContent.Create(new VerifyRequest(captchaToken, captcha.SiteKey ?? string.Empty)),
};
request.Headers.TryAddWithoutValidation(ApiKeyHeader, captcha.Secret);
using var response = await httpClients.CreateClient(HttpClientName).SendAsync(request, timeout.Token);
var status = (int)response.StatusCode;
VerifyResponse? body = null;
if (status < 500)
{
try
{
body = await response.Content.ReadFromJsonAsync<VerifyResponse>(timeout.Token);
}
catch (JsonException)
{
// Not JSON: judged by the status code below.
}
}
if (status >= 500)
{
logger.LogWarning("captcha_unavailable status={Status}; letting the visitor through", status);
return true;
}
// Our own configuration is wrong (API key or site key rejected): not the visitor's fault.
if (status is 401 or 403 || body?.Error?.ErrorCode == "sitekey_invalid")
{
logger.LogError("captcha_misconfigured status={Status} code={Code}; letting the visitor through",
status, body?.Error?.ErrorCode);
return true;
}
if (response.IsSuccessStatusCode && body is { Success: true })
{
return true;
}
// A definite no (wrong, expired or reused response, or a missing/bad request): spam.
return false;
}
catch (OperationCanceledException) when (!cancellationToken.IsCancellationRequested)
{
logger.LogWarning("captcha_unavailable reason=timeout; letting the visitor through");
return true;
}
catch (HttpRequestException ex)
{
// Type only: the message could quote the URL.
logger.LogWarning("captcha_unavailable reason=network exception={ExceptionType}; letting the visitor through",
ex.GetType().Name);
return true;
}
}
}