Contactmodule: token- en inzendroute met spamafhandeling, idempotentie en retentietaak

Nieuwe module SlpModularCms.Modules.Contact met eigen DbContext en migratie InitialCreate. GET contact-messages/token en POST contact-messages zijn publiek ([PublicSiteEndpoint]), geven bij echte inzendingen, spam en herhalingen hetzelfde 202 en slaan spam apart op (30 dagen, dagplafond). Standaard staat de module uit (Contact:Enabled=false, 404 met lege body, geen databasetoegang) totdat de rate limiting per client op de basisbranch staat; de rate-limit-sleutel zit in een enkele functie zodat dat later een regel wijzigen is. Mail zit achter een seam (nog een no-op).

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-10 13:07:27 +01:00
co-authored by Claude Sonnet 5.5
parent 0f6f5475a1
commit 7748bbe9c9
37 changed files with 3266 additions and 9 deletions
@@ -5,7 +5,7 @@
- **Feature Slug**: contact-forms-module
- **Project Type**: Brownfield
- **Start Date**: 2026-11-09
- **Current Stage**: CONSTRUCTION - CMS-U3 Code Generation Part 1 (plan awaiting approval by Redesign - SLS)
- **Current Stage**: CONSTRUCTION - CMS-U3 built and committed (awaiting review); next CMS-U3b plan, then CMS-U4
- **Branch**: feature/contact-forms-module (worktree ..SlpModularCms-contact-forms, from master d9cc539; main checkout stays on feature/identity-email-notifications — never switch it)
## Workspace State
@@ -0,0 +1,55 @@
# CMS-U3 contact-core: code summary
## What it delivers
New module `SlpModularCms.Modules.Contact` (+ `.Contact.Tests`), referenced by `Api.SlpSoftware` only.
Public routes (both anonymous, `[PublicSiteEndpoint]`, reachable while the CMS is off):
- `GET /api/v1/contact-messages/token` -> `{ token, minSeconds, captcha }` (`captcha` is null unless enabled; the secret is never returned). Rate limit policy `contact-token`.
- `POST /api/v1/contact-messages` with header `Idempotency-Key: <guid>` and body `{ name, email, subject, message, hpCheck, token, captchaToken? }` -> `202 { "status": "received" }` for genuine messages, spam and replays alike. Policy `contact-form`. Errors: `400` (`errors` per field with codes `required|tooLong|invalid|expired`, also `idempotencyKey` and `body`), `413` (problem+json), `429` (Retry-After, problem+json), `404` empty body while the form is closed.
Behaviour: validation (limits 100/254/100/2000, e-mail regex, control characters rejected, fields trimmed) -> replay check (same key within 24 h answers 202 without a second row; a rejected request does not use up its key) -> token (forged, other-site, garbage and expired all answer `errors.token=["expired"]`: no oracle) -> classification: too-young token (< `MinSeconds`), filled `hpCheck`, or a rejected captcha is spam -> store (genuine: `New`, mail `Pending`, retention 12 months; spam: `Spam`, mail `NotApplicable`, 30 days, per-site daily cap 200 beyond which it is answered but not stored) -> after commit the mail seam `IContactMailSender` (no-op until the mail unit: result `Skipped`, message stays `Pending`). A mail problem never fails the request. Daily retention job removes expired messages and idempotency records older than 24 h. Site id comes from configuration, never from the request; no IP address is stored.
## RELEASE CONDITION (unchanged, now enforced in code)
On the base branch the rate-limit policies are shared buckets (no per-client key, no forwarded-header handling). The contact routes therefore stay **closed** (`Contact:Enabled=false`, 404 with empty body, no database access, retention job idle) until the per-client partitioning from the ASF branch is on the base branch. Do not enable on a public host before that.
## Gate design (two layers, per the later decision)
Route filter `ContactRouteFilter` asks `IContactFormGate.IsOpenAsync`. Today the only layer is `HostFlagContactFormGate` (`Contact:Enabled`). CMS-U4 adds the CMS-controlled switch (`/api/v1/contact-settings`) as a second layer by replacing the registration with a composite gate; the filter is not touched. The form is active only if every layer is open; otherwise 404 empty body (the website shows its mailto fallback).
## REBASE CHECKLIST (after the ASF merge)
1. `src/SlpModularCms.Modules.Contact/Services/ContactSeams.cs`, class `ContactRateLimitPartition`: change the single line `public static string KeyFor(HttpContext context) => GlobalKey;` to `public static string KeyFor(HttpContext context) => ClientPartitionKey.For(context);` (add the ASF `using`). Remove the `GlobalKey` constant if it is no longer used.
2. `src/SlpModularCms.Modules.Contact.Tests/ContactRetentionAndPartitionTests.cs`, test `OnTheBaseBranch_EveryCallerSharesOneBucket`: replace it with "two different client addresses give two different keys" (the same two addresses are already in the test).
3. Make sure `ForwardedHeaders:KnownProxies` is configured on the host (environment).
4. Regenerate/verify migrations only if a snapshot conflicts (Contact has its own context and history, so none is expected). Re-run all test projects.
5. Only then set `Contact:Enabled=true` on the host (environment or appsettings of that host).
## `Contact:*` configuration (keys and defaults; `Api.SlpSoftware/appsettings.json` carries them)
| Key | Default | Notes |
|---|---|---|
| `Contact:Enabled` | `false` | host switch / release condition |
| `Contact:SiteId` | `slpsoftware` in appsettings; `default` if unset | stored on rows, bound into the token purpose; never from a request |
| `Contact:MinSeconds` | `3` | returned to the client as `minSeconds`; faster = spam |
| `Contact:TokenLifetimeMinutes` | `120` | |
| `Contact:RetentionMonths` | `12` | per row at insert; no retroactive change |
| `Contact:SpamRetentionDays` | `30` | |
| `Contact:MaxSpamRowsPerDay` | `200` | per site per UTC day |
| `Contact:MaxBodyBytes` | `16384` | 413 beyond |
| `Contact:ProblemTypeBase` | none -> `about:blank` | base for the validation problem `type` (`{base}/validation`) |
| `Contact:Captcha:Enabled` | `false` | |
| `Contact:Captcha:Provider` / `SiteKey` | none | returned in the token response when enabled |
| `Contact:Captcha:Secret` | none | env / secrets manager only, never committed |
| `RateLimiting:ContactForm:PermitLimit` / `WindowSeconds` | `5` / `600` | |
| `RateLimiting:ContactToken:PermitLimit` / `WindowSeconds` | `20` / `600` | |
## Deviations from the contract / design (for SLS to adopt)
- The honeypot JSON name is fixed `hpCheck` (no `Contact:HoneypotField`): the payload shape is a contract matter; the site's DOM name is free. A missing `hpCheck` key counts as empty (lenient) instead of a `required` error, so a real client that omits it is not rejected and a bot learns no field name from an error.
- Unbindable bodies (malformed JSON, wrong types) answer `400` with `errors.body=["invalid"]` in the same problem shape (the controller is deliberately not an `[ApiController]`).
- Validation problem `type` is configurable (`Contact:ProblemTypeBase`), default `about:blank` (approved).
## Privacy / logging
Only the outcome (`Genuine|Spam|SpamNotStored|Replay`) and the site id are logged; mail failures are logged by exception type only. Tests prove that no name, e-mail, subject, message, captcha token, Idempotency-Key or token appears in any log entry (genuine, spam, replay, invalid, forged token, mail exception with personal data in its message, database exception). Sentry: request bodies are never captured (`MaxRequestBodySize=None`) and the existing scrubber nulls `Request.Data`. Note: like for every endpoint, a Sentry error event carries the caller's IP address (`SendDefaultPii`); nothing from the form body is in it.
## Verification (real output)
Build 0 errors. Contact.Tests 113 passed (unit and pipeline), Core 205, Availability 95 (route table now allows exactly GetOfferings + GetToken + Submit), Offerings 86, Identity 37, Master 57, Api.Tests 4 — all against a temporary MariaDB (removed afterwards). Pipeline tests start the real SlpSoftware host: disabled -> both routes 404 empty and the contact tables do not even exist (the module never touched the database; the retention tick changes nothing); enabled -> token 200, valid POST 202 stored once, replay 202 without a second row, honeypot 202 identical body but stored as Spam, 400 shapes, 413, malformed bodies without echo, 429 with Retry-After for both policies, routes reachable while the CMS is disabled (and `/offerings/categories` 503), migration applied on a real MariaDB with a unique (site, key) constraint, retention job deletes expired rows. Each pipeline fixture creates and drops its own database.
## Running the tests
The `Pipeline` tests need `ConnectionStrings__DefaultConnection` pointing at a MariaDB/MySQL server on which databases may be created (same requirement as `Api.Tests`). Unit tests only: `dotnet test --filter "FullyQualifiedName!~Pipeline"`.
@@ -36,14 +36,14 @@ On master the rate-limit policies are global buckets (no per-client partition ke
`Enabled=false`, `SiteId`, `MinSeconds=3`, `TokenLifetimeMinutes=120`, `RetentionMonths=12`, `SpamRetentionDays=30`, `MaxSpamRowsPerDay=200`, `MaxBodyBytes=16384`, `HoneypotField=hpCheck`, `Captcha:{Enabled=false,Provider,SiteKey,Secret}`; `RateLimiting:ContactForm` (5/600), `RateLimiting:ContactToken` (20/600). Recipient/sender e-mail addresses are not part of U3 (U5, env-only for ASF). `appsettings.json` of `Api.SlpSoftware` gets the section with `Enabled=false`; no addresses, no secrets.
## Steps
- [ ] **Step 1 — Projects**: create `SlpModularCms.Modules.Contact` and `.Contact.Tests` (net10.0, same package set as Offerings/Offerings.Tests), add to `SlpModularCms.sln` (Application/Modules and Tests/Modules folders), reference from `Api.SlpSoftware`; no other project reference changes.
- [ ] **Step 2 — Options, entities, DbContext, migration `InitialCreate`** (generated with dotnet ef; applied to a real MariaDB for verification).
- [ ] **Step 3 — Pure logic**: `ContactValidator`, `ContactTokenService` (clock abstraction `TimeProvider`), spam classification, options validation.
- [ ] **Step 4 — Services + repository**: submission pipeline, idempotency, spam cap, `ICaptchaVerifier`/`IContactMailSender` seams, retention service.
- [ ] **Step 5 — Controller + wiring**: routes, `[PublicSiteEndpoint]`, rate-limit policies via `ContactRateLimitPartition`, size limit, `Contact:Enabled` 404 filter, module registration; add the two actions to `AllowedPublicActions` in `PublicSiteEndpointGateTests` (and the module assembly to its reflection list).
- [ ] **Step 6 — Tests** (xUnit; PBT partial per D7): validator (examples + property tests: trimming idempotence, length boundaries 100/254/2000 inclusive, any control character in name/email/subject rejected, valid addresses accepted); token (round trip, expiry, too young, tampered, other site purpose) as properties/round-trips; submission service (genuine, honeypot, too fast, captcha reject, cap reached, idempotent replay, rejected-not-stored, mail seam called after commit only for genuine); retention service; endpoints via `WebApplicationFactory`-free controller + service tests plus a **real-pipeline test** (Api.SlpSoftware host against the temporary MariaDB) for: disabled => 404, enabled => token + POST 202, replay 202 without a second row, invalid => 400 shape, 413, 429 with Retry-After, and routes stay reachable with the CMS disabled; no-PII log test; route-table additions; `ContactRateLimitPartition` constant-key test (see above); migration applied on a real MariaDB (tables + unique index on idempotency).
- [ ] **Step 7 — Verification (automatic)**: solution build; all test projects; Api.Tests and the new real-pipeline test with a temporary MariaDB container (removed afterwards); real output reported.
- [ ] **Step 8 — Docs/commit**: summary incl. release condition and the rebase checklist (swap the partition function; set `Contact:Enabled` per host); one commit; no push.
- [x] **Step 1 — Projects**: create `SlpModularCms.Modules.Contact` and `.Contact.Tests` (net10.0, same package set as Offerings/Offerings.Tests), add to `SlpModularCms.sln` (Application/Modules and Tests/Modules folders), reference from `Api.SlpSoftware`; no other project reference changes.
- [x] **Step 2 — Options, entities, DbContext, migration `InitialCreate`** (generated with dotnet ef; applied to a real MariaDB for verification).
- [x] **Step 3 — Pure logic**: `ContactValidator`, `ContactTokenService` (clock abstraction `TimeProvider`), spam classification, options validation.
- [x] **Step 4 — Services + repository**: submission pipeline, idempotency, spam cap, `ICaptchaVerifier`/`IContactMailSender` seams, retention service.
- [x] **Step 5 — Controller + wiring**: routes, `[PublicSiteEndpoint]`, rate-limit policies via `ContactRateLimitPartition`, size limit, `Contact:Enabled` 404 filter, module registration; add the two actions to `AllowedPublicActions` in `PublicSiteEndpointGateTests` (and the module assembly to its reflection list).
- [x] **Step 6 — Tests** (xUnit; PBT partial per D7): validator (examples + property tests: trimming idempotence, length boundaries 100/254/2000 inclusive, any control character in name/email/subject rejected, valid addresses accepted); token (round trip, expiry, too young, tampered, other site purpose) as properties/round-trips; submission service (genuine, honeypot, too fast, captcha reject, cap reached, idempotent replay, rejected-not-stored, mail seam called after commit only for genuine); retention service; endpoints via `WebApplicationFactory`-free controller + service tests plus a **real-pipeline test** (Api.SlpSoftware host against the temporary MariaDB) for: disabled => 404, enabled => token + POST 202, replay 202 without a second row, invalid => 400 shape, 413, 429 with Retry-After, and routes stay reachable with the CMS disabled; no-PII log test; route-table additions; `ContactRateLimitPartition` constant-key test (see above); migration applied on a real MariaDB (tables + unique index on idempotency).
- [x] **Step 7 — Verification (automatic)**: solution build; all test projects; Api.Tests and the new real-pipeline test with a temporary MariaDB container (removed afterwards); real output reported.
- [x] **Step 8 — Docs/commit**: summary incl. release condition and the rebase checklist (swap the partition function; set `Contact:Enabled` per host); one commit; no push.
## Explicitly NOT touched
`AddCmsRateLimiting`/Core hosting files, `AvailabilityMiddleware`, Email, Identity, ASF-owned areas, host Program.cs, frontend, the Andrea host. No admin endpoints (CMS-U4), no mail sending (CMS-U5), no OpenAPI export (CMS-U3b).