From 0f6f5475a1f86e127dad753b57f15337c6cf9a2c Mon Sep 17 00:00:00 2001 From: Sluijsens Date: Mon, 9 Nov 2026 20:54:29 +0100 Subject: [PATCH] Docs: plan CMS-U3 (contact-core) met release-voorwaarde en partitioneringsaanpak Co-Authored-By: Claude Sonnet 5.5 --- .../contact-forms-module/aidlc-state.md | 2 +- .../features/contact-forms-module/audit.md | 12 ++++ ...ms-u3-contact-core-code-generation-plan.md | 57 +++++++++++++++++++ 3 files changed, 70 insertions(+), 1 deletion(-) create mode 100644 aidlc-docs/features/contact-forms-module/construction/plans/cms-u3-contact-core-code-generation-plan.md diff --git a/aidlc-docs/features/contact-forms-module/aidlc-state.md b/aidlc-docs/features/contact-forms-module/aidlc-state.md index 674a488..6671b79 100644 --- a/aidlc-docs/features/contact-forms-module/aidlc-state.md +++ b/aidlc-docs/features/contact-forms-module/aidlc-state.md @@ -5,7 +5,7 @@ - **Feature Slug**: contact-forms-module - **Project Type**: Brownfield - **Start Date**: 2026-11-09 -- **Current Stage**: CONSTRUCTION - CMS-U2 built and committed (awaiting review); next CMS-U3 plan +- **Current Stage**: CONSTRUCTION - CMS-U3 Code Generation Part 1 (plan awaiting approval by Redesign - SLS) - **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 diff --git a/aidlc-docs/features/contact-forms-module/audit.md b/aidlc-docs/features/contact-forms-module/audit.md index 6d15f96..390924f 100644 --- a/aidlc-docs/features/contact-forms-module/audit.md +++ b/aidlc-docs/features/contact-forms-module/audit.md @@ -95,3 +95,15 @@ **Context**: Code Generation Part 1. --- + +## CMS-U2 done, CMS-U3 plan + +**Timestamp**: 2026-11-09 + +**User Input**: "CMS-U2 goedgekeurd ... release-voorwaarde in summary en U3-plan; leg uit hoe ContactForm/ContactToken zich op master gedraagt en hoe dit na de rebase naar per-client schakelt; controleer dat 429 geen interne details lekt." (via Redesign - SLS) + +**AI Response**: U2 committed (9e8e8ef); U3 plan written with Contact:Enabled switch and single partition-key function; approval requested. + +**Context**: Code Generation Part 1. + +--- diff --git a/aidlc-docs/features/contact-forms-module/construction/plans/cms-u3-contact-core-code-generation-plan.md b/aidlc-docs/features/contact-forms-module/construction/plans/cms-u3-contact-core-code-generation-plan.md new file mode 100644 index 0000000..011584f --- /dev/null +++ b/aidlc-docs/features/contact-forms-module/construction/plans/cms-u3-contact-core-code-generation-plan.md @@ -0,0 +1,57 @@ +# Code Generation Plan — CMS-U3 contact-core + +Phase 1, base: current branch (master + CMS-U0/U1/U1b/U2). Inputs: contract v0.3.x (§ 2-5), requirements D2/D3/D5, application-design § 3-7 (admin routes superseded by unit-of-work: RESTful, no `/admin`), functional-design decisions below. Scope: the **public** contact endpoints and everything they need. Admin endpoints are CMS-U4, real mail is CMS-U5, OpenAPI export is split off as **CMS-U3b** (see end) to keep this unit reviewable. + +## RELEASE CONDITION (explicit, as agreed) +On master the rate-limit policies are global buckets (no per-client partition key, no ForwardedHeaders; both exist only on the ASF branch). A per-IP contact policy would then be one bucket for the whole site: five submissions would block everybody. **The contact routes must not be enabled on a public host until the per-client partitioning from the ASF branch is on the base branch.** This is enforced in code, not only documented: see `Contact:Enabled` below. + +## Rate limiting: how it behaves on master and how it switches after the rebase +- Policies `contact-form` (5 per 600 s), `contact-token` (20 per 600 s) and (CMS-U4) `contact-resend` (5 per 600 s) are registered **inside the Contact module** through `services.Configure(...)`, so the shared `AddCmsRateLimiting` file (also edited by the ASF branch) is not touched in this unit. +- Each policy is built with `RateLimitPartition.GetFixedWindowLimiter(partitionKey, ...)`, and the key comes from exactly one function in the module: `ContactRateLimitPartition.KeyFor(HttpContext)`. **On master it returns the constant `"global"`**, so the policies behave as one shared bucket per policy (the documented, known state — safe, because the routes are disabled by default on any host). +- **After the ASF merge and rebase**, switching to per-client is a one-line change in that single function: `return ClientPartitionKey.For(context);` (the ASF helper). No policy, controller or test is rewritten. A test pins the function: it currently asserts the constant, and the rebase commit changes that one assertion to "two different client addresses give two different keys". +- No own partitioning, forwarded-header parsing or IP handling is built here (would clash with the ASF implementation). + +## Safety switch +`Contact:Enabled` (default **false**). While false the module registers nothing active: the two contact routes answer **404** (an endpoint filter on the controller short-circuits before any work), no database access, no hosted service work (the retention job starts but does nothing), no key-ring use. Enabling is an explicit act per host (appsettings of the host or environment) and belongs to the release step after the rebase. Tests run with it enabled. The 404 body is empty (nothing revealed). The two routes still carry `[PublicSiteEndpoint]` so the gate behaviour is the same once enabled. + +## Components (see application-design § 3) +`Modules.Contact` + `Modules.Contact.Tests` (solution folders Application/Modules and Tests/Modules), referenced by `Api.SlpSoftware` only (the Andrea host is not on master; the reference follows in phase 2). +- `ContactModule : IModule` ("Contact"): options, DbContext (MySQL, `NonLockingMySQLHistoryRepository`, `Database.Migrate()` in `UseModule`, same as Offerings), services, rate-limit policies, hosted service. +- `ContactDbContext`: `ContactMessage`, `IdempotencyRecord`. Migration `InitialCreate`. Tables `ContactMessages`, `ContactIdempotency`. +- `ContactMessagesController` (`[Route("contact-messages")]`, class `[AllowAnonymous]` for the two public actions only; admin actions arrive in U4 with `AdminOnly`): `GET token` (`[PublicSiteEndpoint]`, policy `contact-token`), `POST` (`[PublicSiteEndpoint]`, policy `contact-form`, `RequestSizeLimit` from `Contact:MaxBodyBytes`). +- `ContactValidator` (pure), `ContactTokenService` (`IDataProtectionProvider`, purpose `SlpModularCms.Contact.Token.{siteId}`; keys already persist in the database via `AddCmsDataProtection`), `ContactSubmissionService`, `ICaptchaVerifier` + `NullCaptchaVerifier` (Friendly Captcha implementation comes later behind the same interface; fail-open), `IContactMailSender` + `NoOpContactMailSender` (real implementation in U5), `ContactRetentionService` (daily `BackgroundService`, pattern of `IntegrityCheckBackgroundService`), `ContactOptions` (`Contact:*`, validated), `ContactRateLimitPartition`. + +## Functional design decisions (fills the contract's gaps) +1. **Validation** (pure function, trims first): name 1-100, email 1-254 + regex `^[^\s@]+@[^\s@]+\.[^\s@]{2,}$`, subject 1-100 (opaque, never checked against offerings), message 1-2000; control characters rejected in name, email, subject (newlines are allowed in message); `hpCheck` key present; `token` required. Error codes `required|tooLong|invalid|expired`; field names as in the JSON; ProblemDetails with `errors` and status 400; the `type` URI is configurable (`Contact:ProblemTypeBase`, default none => `about:blank`) so no site domain is hard-coded in a module that two sites use (open point 2). +2. **Idempotency**: header `Idempotency-Key` required, GUID (`errors.idempotencyKey: required|invalid`). Key + site id unique. A replay within 24 h returns the stored status code (always 202 for accepted requests) without a second row. A replay of a request that was *rejected* with 400 is not stored (so the client can correct and resend with the same key). The record holds only key, site, created-at, status code. +3. **Token**: `GET token` returns `{ token, minSeconds, captcha }`; token payload = issue time + site id, protected with the purpose string, lifetime `Contact:TokenLifetimeMinutes` (120). Verification outcomes: valid / too young (below `MinSeconds`) / expired-or-invalid (forged, other site, garbage, too old). +4. **Submission pipeline**: size limit -> idempotency header -> validation -> token: invalid/expired => 400 `errors.token=["expired"]` (no oracle); too young or honeypot filled or captcha rejected => **spam path**; otherwise genuine path. Spam path: store with `Status=Spam`, `RetentionUntil=now+SpamRetentionDays`, never mailed, unless the per-site daily cap (`Contact:MaxSpamRowsPerDay`, default 200) is reached (then not stored); response is the identical 202 `{ "status": "received" }`. Genuine path: store `Status=New`, `MailStatus=Pending`, `RetentionUntil=now+RetentionMonths`, then call `IContactMailSender` **after commit** and only record the outcome (U3: no-op => stays `Pending`/`NotApplicable`; U5 adds sweep + retry). +5. **Captcha**: disabled by default; when enabled and the token is missing or rejected => spam path; verifier failure (timeout/5xx) => fail-open with a log line without PII. +6. **Retention job**: daily; deletes `ContactMessages` where `RetentionUntil < now` and `IdempotencyRecords` older than 24 h; logs counts only. +7. **Site id**: `Contact:SiteId`, default = host name from `Contact:SiteId` fallback `Environment.ApplicationName`; never from the request. +8. **Privacy/logging**: no IP stored; no name/email/message/body in any log, exception or Sentry event. Findings: Sentry is configured with `MaxRequestBodySize = None` and the `SentryEventScrubber`; the plan adds (a) request logging for these routes is off, (b) a log-capture test that submits a request carrying marker strings in all fields, forces an exception in the service and asserts none of the marker strings appears in any log entry or exception message, (c) a scrubber test that a Sentry event built from such an exception has no body/field values. Model-binding errors use the custom problem shape, never echo values. +9. **Security Baseline**: allow-list validation, bounded sizes, deny-by-default gate, generic 5xx (`UseExceptionHandler` already returns ProblemDetails), no secrets in config (captcha secret via env), no oracle on token errors. + +## Configuration (`Contact:` section; defaults as in application-design § 4) +`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. + +## 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). + +## CMS-U3b (proposed separate small unit, right after U3) +Exported OpenAPI document committed as `openapi/cms-api.v1.json` with a snapshot test (`UPDATE_OPENAPI=1` rewrites; drift fails the build) and an `IOpenApiDocumentTransformer` adding the contract's reusable responses (Validation/TooLarge/RateLimited). Separate because it needs the host-level test harness and touches how the document is produced, which is unrelated to the contact logic. + +## Open points for approval +1. `Contact:Enabled=false` default with 404 (my proposal to enforce the release condition in code). OK? +2. Validation problem `type`: configurable, default `about:blank` (instead of the contract's `https://slpsoftware.nl/problems/validation`, to avoid hard-coding a site domain in a module used by two sites). The frontend maps on `errors`, not on `type`. OK? +3. Split OpenAPI export into CMS-U3b. OK?