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:
@@ -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
|
||||
|
||||
+55
@@ -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"`.
|
||||
+8
-8
@@ -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).
|
||||
|
||||
Reference in New Issue
Block a user