159 lines
21 KiB
Markdown
159 lines
21 KiB
Markdown
# Phase 1 handoff (CMS side) — for the frontend work
|
|
|
|
Branch `feature/contact-forms-module` (worktree `..\SlpModularCms-contact-forms`), base master `d9cc539`, phase 1 units CMS-U0, U1, U1b, U2, U3, U3b, U4 all committed (last commit `44f161a`). Nothing pushed, merged or deployed. Phase 2 (CMS-U5 mail + retry, CMS-U6 "Berichten" UI, CMS-U7 `PUT /availability/status`) waits for the merge of `feature/identity-email-notifications` and a rebase.
|
|
|
|
The machine-readable source for types is **`openapi/slpsoftware.v1.json`** (one file per host, named after the host; regenerate with `UPDATE_OPENAPI=1 dotnet test --filter OpenApiSnapshot`). Per-unit details: `construction/cms-u*/code/summary.md`.
|
|
|
|
All paths are under `/api/v1`. "Gate" = the availability gate: routes without the public marker answer 503 to visitors while the CMS is off or in maintenance; a verified Owner/Administrator always gets through. `401` = no/invalid login, `403` = logged in without `Administrator`/`Owner`. JSON is camelCase.
|
|
|
|
## 1. Routes
|
|
|
|
### Offerings (module `Offerings`)
|
|
| Method + path | Auth | Success | Other status codes |
|
|
|---|---|---|---|
|
|
| `GET /offerings` | public (marker, survives a closed gate); limiter `offerings-public` 120/60 s | `200` array of offerings | `429` |
|
|
| `POST /offerings` | AdminOnly | `201` + `Location: /api/v1/offerings/{id}` + offering | `400` (framework validation shape; bad `categoryId` = `errors.categoryId=["invalid"]`), `409` slug taken, `401`, `403`, `503` |
|
|
| `PUT /offerings/{id:guid}` | AdminOnly | `200` offering (full replace; omitting `categoryId` clears the category) | `400`, `404`, `409`, `401`, `403`, `503` |
|
|
| `DELETE /offerings/{id:guid}` | AdminOnly | `204` (soft delete) | `404`, `401`, `403`, `503` |
|
|
| `PUT /offerings/order` body `{ "orderedIds": [guid,...] }` | AdminOnly | `204` | `400` problem unless the list holds every existing offering exactly once, `401`, `403`, `503` |
|
|
|
|
Offering JSON: `{ id, slug, title, description, price, priceNote, features[], ctaLabel, featured, displayOrder, categoryId|null, category|null }`. `category` = the category **name** (a rename shows up at once; no response caching in the code); `categoryId` and `displayOrder` are additive fields the SLP site can ignore. Create/update body: `title, description, price, priceNote, features[], ctaLabel, featured, slug?, categoryId?` (`categoryId` must exist; `null` clears).
|
|
|
|
### Offering categories (CMS data, nothing seeded)
|
|
| Method + path | Auth | Success | Other |
|
|
|---|---|---|---|
|
|
| `GET /offerings/categories` | AdminOnly | `200` `[{ id, name, sortOrder, offeringCount }]` | `401`, `403`, `503` |
|
|
| `POST /offerings/categories` `{ name }` (1-100) | AdminOnly | `201` + Location + category | `400`, `409` name taken (case-insensitive) |
|
|
| `PUT /offerings/categories/{id:guid}` `{ name }` | AdminOnly | `200` category | `400`, `404`, `409` |
|
|
| `DELETE /offerings/categories/{id:guid}` | AdminOnly | `204` | `404`, `409` while live offerings use it |
|
|
|
|
### Contact — public (module `Contact`)
|
|
Both answer `404` with an **empty body** while the form is closed (host switch OR CMS switch off); the website then shows its mailto fallback. Both stay reachable when the CMS is disabled.
|
|
| Method + path | Auth | Success | Other |
|
|
|---|---|---|---|
|
|
| `GET /contact-messages/token` | public (marker); limiter `contact-token` 20/600 s | `200` `{ token, minSeconds, captcha: null \| { provider, siteKey } }` | `404` closed, `429` |
|
|
| `POST /contact-messages` headers `Idempotency-Key: <uuid>` (required), body `{ name, email, subject, message, hpCheck, token, captchaToken? }` | public (marker); limiter `contact-form` 5/600 s | `202` `{ "status": "received" }` — identical for genuine, spam and replay | `400` problem+json (`errors` per field), `404` closed, `413` problem (> 16384 bytes), `429` |
|
|
|
|
Limits: name 1-100, email 1-254 (regex `^[^\s@]+@[^\s@]+\.[^\s@]{2,}$`), subject 1-100 (opaque value chosen by the site), message 1-2000; all trimmed; control characters rejected (line breaks and tabs allowed in `message`). `hpCheck` is the honeypot, must be empty. `400` shape: `{ type, title, status, errors: { <field>: [code] } }`, codes `required | tooLong | invalid | expired`; fields `name, email, subject, message, token, idempotencyKey, body`. A forged, other-site or expired token is always `errors.token=["expired"]` (fetch a fresh token and retry once). Replays with the same key within 24 h get the same `202` without a second message; a `400` does not use up the key.
|
|
|
|
### Contact — management (AdminOnly; not public; behind the gate)
|
|
All answer `404` with an empty body while the **host** switch `Contact:Enabled` is off (the tables do not exist then). The CMS switch never closes them.
|
|
| Method + path | Success | Other |
|
|
|---|---|---|
|
|
| `GET /contact-messages?status=&page=&pageSize=` | `200` `{ items[{id,receivedAt,name,email,subject,status,mailStatus}], page, pageSize, totalCount, unreadCount }`; default list = `new`,`read`,`archived` (**no spam**), `status=spam` shows spam apart; `pageSize` 1-100 (default 25); `unreadCount` = `new` only, never spam | `400` (`errors.page/pageSize/status`), `401`, `403`, `404`, `503` |
|
|
| `GET /contact-messages/{id:guid}` | `200` detail (list fields + `message, mailAttempts, mailError, retentionUntil`) | `404` |
|
|
| `PATCH /contact-messages/{id:guid}` `{ "status": "new"\|"read"\|"archived" }` | `200` detail (on a spam message = "not spam": normal retention from now) | `400 errors.status=["invalid"]`, `404` |
|
|
| `DELETE /contact-messages/{id:guid}` | `204` (hard delete) | `404` |
|
|
| `POST /contact-messages/{id:guid}/resend` (limiter `contact-resend` 5/600 s) | `200` `{ mailStatus, mailAttempts, mailed }` (`mailed:false` until CMS-U5) | `404`, `409` spam message, `429` |
|
|
| `GET /contact-settings` | `200` `{ enabled, hostEnabled }` (`enabled` = CMS switch, default **false**) | `401`, `403`, `404`, `503` |
|
|
| `PUT /contact-settings` `{ "enabled": true\|false }` | `200` same shape | `400 errors.enabled=["invalid"]` for anything that is not a JSON boolean, `401`, `403`, `404`, `503` |
|
|
|
|
`status`: `new|read|archived|spam|converted`; `mailStatus`: `pending|sent|failed|notApplicable`.
|
|
|
|
### Unchanged but relevant
|
|
`PUT /availability/status` (AdminOnly; body `{ newStatus, reason }`; `200` with the updated resource in the GET shape, `409` master-controlled) replaced `POST /availability/admin/status` (CMS-U7, no alias; API and admin app must be released together). `GET /availability/status` stays public; the gate exempts it for GET/HEAD only.
|
|
|
|
## 2. `Contact:*` and related configuration keys (Api.SlpSoftware `appsettings.json`)
|
|
| Key | Default | Notes |
|
|
|---|---|---|
|
|
| `Contact:Enabled` | `false` | host switch; **release condition**, see § 3 |
|
|
| `Contact:SiteId` | `slpsoftware` (code default `default`) | stored on rows, in the token purpose; never from a request |
|
|
| `Contact:MinSeconds` | `3` | returned as `minSeconds`; faster = spam |
|
|
| `Contact:TokenLifetimeMinutes` | `120` | |
|
|
| `Contact:RetentionMonths` | `12` | fixed per row at insert |
|
|
| `Contact:SpamRetentionDays` | `30` | |
|
|
| `Contact:MaxSpamRowsPerDay` | `200` | per site per UTC day; beyond it spam is answered but not stored |
|
|
| `Contact:MaxBodyBytes` | `16384` | `413` beyond |
|
|
| `Contact:ProblemTypeBase` | none -> `about:blank` | `{base}/validation` when set |
|
|
| `Contact:Captcha:Enabled` | `false` | |
|
|
| `Contact:Captcha:Provider`, `:SiteKey` | none | returned in the token response when enabled |
|
|
| `Contact:Captcha:Secret` | none | environment / secrets manager only, never committed |
|
|
| `RateLimiting:ContactForm` | `5` / `600` | `PermitLimit` / `WindowSeconds` |
|
|
| `RateLimiting:ContactToken` | `20` / `600` | |
|
|
| `RateLimiting:ContactResend` | `5` / `600` | |
|
|
| (removed) | | `Offerings:Categories` no longer exists; categories are data |
|
|
|
|
CMS switch (not configuration): table `ContactSettings`, `PUT /contact-settings`, default off. Mail recipient/sender settings arrive with CMS-U5 (environment only, no addresses in committed config).
|
|
|
|
## 3. Release / rebase checklist (do in this order, after Bryan merges `feature/identity-email-notifications`)
|
|
1. Rebase `feature/contact-forms-module` onto the merged base. Expected conflicts: `AvailabilityMiddleware.cs` (one block), `AddCmsRateLimiting` (`OnRejected`), `appsettings` files, host composition, maybe EF snapshots (own contexts, so none expected; regenerate our migration only if a snapshot conflicts). Re-run all test projects.
|
|
2. **Per-client rate limiting**: in `Modules.Contact/Services/ContactSeams.cs`, class `ContactRateLimitPartition`, change `public static string KeyFor(HttpContext context) => GlobalKey;` to `=> ClientPartitionKey.For(context);` (add the ASF `using`; drop `GlobalKey` if unused). In `Contact.Tests/ContactRetentionAndPartitionTests.cs`, test `OnTheBaseBranch_EveryCallerSharesOneBucket` becomes "two different client addresses give two different keys". Until this is done every visitor shares one bucket per policy (5 form submissions per 10 minutes for the whole site), which is why the module is off by default.
|
|
3. `ForwardedHeaders:KnownProxies` configured on the host (environment).
|
|
4. Phase 2 units (CMS-U5 mail + retry job, CMS-U6 UI, CMS-U7) on the rebased branch; give the Andrea host the Contact module reference and its own `openapi/andreaslopfotografie.v1.json` when it is in scope.
|
|
5. Only then set **`Contact:Enabled=true`** on the host (environment or its appsettings).
|
|
6. Switch the **CMS switch** on: it is OFF by default, so Bryan must open the form himself (screen "Berichten" in CMS-U6, or `PUT /api/v1/contact-settings {"enabled":true}`). Until both switches are on the website shows its mailto fallback.
|
|
7. Nothing is deployed to production without Bryan; no push/merge/PR happened.
|
|
|
|
## 4. Known deviations from contract v0.3.x and design decisions to adopt
|
|
- **Admin routes** are RESTful on the resource (`/contact-messages`, `/offerings`, `/contact-settings`), no `admin` segment, per Bryan's decision; old `offerings/admin...` routes and move-up/move-down are gone (reorder via `PUT /offerings/order`).
|
|
- **One offering DTO** for everybody (`OfferingAdminDto` removed): adds `displayOrder`, `categoryId`; `category` is the name.
|
|
- **Categories are CMS data** (table + CRUD), not `Offerings:Categories`.
|
|
- **Honeypot** JSON name is fixed `hpCheck` (no configurable name); a **missing `hpCheck` counts as empty**.
|
|
- **Unbindable body** (malformed JSON, wrong types) -> `400` with `errors.body=["invalid"]` in the same problem shape (the contact controllers are deliberately not `[ApiController]`).
|
|
- **`Contact:ProblemTypeBase`** configurable, default `about:blank` (instead of a fixed URL).
|
|
- **Two-layer switch**: host `Contact:Enabled` and the CMS switch; both default off; `404` empty body when closed.
|
|
- **`GET /contact-settings`** returns the extra read-only `hostEnabled`.
|
|
- **Un-spam** (PATCH spam -> new/read/archived) extends retention to the normal period; **resend of spam = 409**.
|
|
- **Management routes answer `404`** while the host switch is off; **an Owner/Administrator passes the availability gate** while the CMS is disabled (existing design), visitors get `503`.
|
|
- **Mail**: stored first; the mail seam (`IContactMailSender`) is a no-op until CMS-U5, so messages stay `pending` and resend reports `mailed:false`.
|
|
- **Rate limits** are global buckets on this base until the checklist step 2 (documented, enforced by the default-off switches).
|
|
- **Privacy**: no IP address is stored; Sentry error events carry the caller's IP (`SendDefaultPii`) but never form content — mention error reporting in the privacy statement. Backups may keep deleted messages longer than the retention period — mention or shorten backup retention.
|
|
|
|
## 5. Tests and tooling worth knowing
|
|
- Pipeline tests (`Contact.Tests/Pipeline`, `Api.Tests`) need `ConnectionStrings__DefaultConnection` pointing at a MariaDB/MySQL server on which databases may be created (CI provides it: `.gitea/workflows/continuous_integration.yaml`). Each fixture creates and drops its own database. Unit tests only: `dotnet test --filter "FullyQualifiedName!~Pipeline"`.
|
|
- Frontend (`frontend/`): `pnpm lint`, `npx tsc -b`, `pnpm test` (278 tests at CMS-U1b). 15 pre-existing files under `features/offerings` fail `prettier --check` (tech debt, not touched).
|
|
- The admin frontend work of phase 1 is only the offerings part (new routes, `useMoveOffering` via `PUT /offerings/order`, categories dialog + select, query key `['offerings','list']`).
|
|
- Last test run (CMS-U4): Contact.Tests 223, Core 205, Availability 95, Offerings 86, Identity 37, Master 57, Api.Tests 4 — all green.
|
|
|
|
## 6. Rebase result (2026-11-10)
|
|
Rebased onto `origin/master` `e671078` (merge of PR #11: identity-email-notifications + andreaslop-site-hosting). Conflicts: `aidlc-docs/active-features.md` (kept master's table, appended our row), `AvailabilityMiddleware` (kept their `CheckAdmin` / expired-token 401 behaviour, our marker block before it), `AddCmsRateLimiting.OnRejected` (kept their Retry-After logic for sliding windows, added the `60 s` fallback for policies without a wait and the problem+json body), `SlpModularCms.sln` (took master's, re-added the two Contact projects). No EF snapshot conflict (own contexts). Checklist steps 1 and 2 are DONE: `ContactRateLimitPartition.KeyFor` now returns `ClientPartitionKey.For(context)` and its test asserts different buckets per address. Still open: step 3 (`ForwardedHeaders:KnownProxies` per host), step 5 (`Contact:Enabled=true`), step 6 (CMS switch). `GET /System/capabilities` now carries `[PublicSiteEndpoint]` (never 503; separate commit). The pipeline tests for the management routes log in with a real user (the host validates every access token against its user and security stamp).
|
|
|
|
## 7. CMS-U5 additions (contact mail)
|
|
- Recipient address: since CMS-U11 the **site setting wins over** the env var `Contact__RecipientEmail` (see section 9); the env var stays the default/fallback (SLP: environment only, like ASF). Optional `Contact__Mail__SweepSeconds|MaxAttempts|ClaimMinutes|BatchSize`, `Contact__Mail__BackoffMinutes__0..n`.
|
|
- Mail itself needs the host's normal `Email:*` configuration; without it messages stay `pending` with `mailError: "disabled"`.
|
|
- Detail: `nextMailAttemptAt`; resend: `mailError`. New migration `ContactMailClaim`.
|
|
|
|
|
|
## 8. CMS-U9 additions (Friendly Captcha v2 and the ASF host)
|
|
|
|
### Captcha contract (no wire change)
|
|
- `GET /contact-messages/token` -> `captcha: null` while off, otherwise `{ "provider": "friendlycaptcha", "siteKey": "<public site key>", "apiEndpoint": "global" | "eu" }`. `apiEndpoint` (additive, default `global`) is the widget's data region and follows `Contact:Captcha:Region`, so switching region needs no website rebuild. Nothing else about the captcha (API key, verify URL) is ever returned.
|
|
- `POST /contact-messages`: `captchaToken` = the widget's response string (the widget also puts it in the form field `frc-captcha-response`). While the captcha is on, a **missing, empty or rejected** value is treated as spam: answer `202 {"status":"received"}` identical to a genuine message, stored with status `spam` (never a 400, so a bot learns nothing). While the captcha is off the field is ignored.
|
|
- Verify (server side, Friendly Captcha **v2**): `POST https://global.frcapi.com/api/v2/captcha/siteverify` (EU-only: `https://eu.frcapi.com/api/v2/captcha/siteverify`), header `X-API-Key: <API key>`, JSON `{ "response": "...", "sitekey": "..." }`; `success:true` passes, `success:false` (HTTP 200 `response_invalid|response_timeout|response_duplicate`, or 400 `response_missing|bad_request`) = spam. Checked against developer.friendlycaptcha.com on 2026-11-10.
|
|
- **Fail-open**: timeout (default 3 s), network error and 5xx let the visitor through (warning `captcha_unavailable`, kind only). Our own wrong API key or site key (HTTP 401, or 400 with `error_code: sitekey_invalid`) also lets the visitor through but logs an **error** `captcha_misconfigured`. The response token, the API key and the site key are never logged.
|
|
|
|
### Configuration (per site)
|
|
| Key | Notes |
|
|
|---|---|
|
|
| `Contact:Captcha:Enabled` | default `false` |
|
|
| `Contact:Captcha:Provider` | `friendlycaptcha` (only supported value; case-insensitive) |
|
|
| `Contact:Captcha:SiteKey` | public; sent to the browser |
|
|
| `Contact__Captcha__Secret` | the API key; **environment variable / secrets manager only**, never committed |
|
|
| `Contact:Captcha:Region` | `global` (default) or `eu`; decides the verify host and the `apiEndpoint` announced to the widget. Unknown value = host refuses to start |
|
|
| `Contact:Captcha:VerifyUrl` | optional override, normally empty (derived from Region); if set it must be https **and match the Region's host** (`global.frcapi.com` / `eu.frcapi.com`), otherwise the host refuses to start |
|
|
| `Contact:Captcha:TimeoutSeconds` | default 3 (1-30) |
|
|
|
|
With `Contact:Enabled=true` and `Captcha:Enabled=true` the host **refuses to start** when provider, site key or secret is missing/invalid (the message names the setting only, never a value).
|
|
|
|
### Widget (website session) and CSP
|
|
- Widget: Friendly Captcha v2 SDK with `sitekey` = `siteKey` from the token response; for the EU endpoint the widget needs `apiEndpoint: "eu"` (`data-api-endpoint="eu"`). The response goes into `captchaToken`. Exact SDK package/events: to be verified by the website session against the SDK docs.
|
|
- **CSP** (decision: exact origins, no wildcard): the v2 widget renders in iframes and the provider's CSP guide requires `frame-src` for `*.frcapi.com`. New option `SecurityHeaders:AllowedSiteFrameOrigins` (StrictSite only; empty = header byte-identical to before; origins only, validated at start-up; the admin and relaxed policies never get it). ASF values (owner decision: main host plus two reserve hosts, exact, no wildcard): `SecurityHeaders__AllowedSiteFrameOrigins__0=https://global.frcapi.com`, `__1=https://global0.frcapi.com`, `__2=https://global1.frcapi.com`. On the switch to the EU region use `https://eu.frcapi.com`, `https://eu0.frcapi.com`, `https://eu1.frcapi.com` instead (together with `Contact__Captcha__Region=eu`). The resulting directive is `frame-src 'self' https://global.frcapi.com https://global0.frcapi.com https://global1.frcapi.com`. No `connect-src`/`script-src` additions are documented by the provider; a browser test with the real widget is still needed.
|
|
- Privacy (provider statements, v2 docs): "Friendly Captcha does not rely on user tracking or cookies for its protection service". **Region `global`**: the visitor's IP address can be processed outside the EU. **Region `eu`** (dedicated endpoint "hosted in Germany"; paid Advanced/Enterprise plan): "personal information (i.e. visitor IP addresses) never leave the EU". The site's privacy page must name the captcha provider, the processing of the visitor's IP address for the challenge, and which region is in use; commercial use needs a paid plan with the provider. For a test or a launch without a paid plan keep `Contact:Captcha:Enabled=false`.
|
|
|
|
### ASF host (`Api.AndreaSlopFotografie`)
|
|
- References `Modules.Contact`; section `Contact` in its `appsettings.json` (`Enabled:false`, `SiteId: andreaslop`), the three contact rate-limit policies. Capabilities now list `Contact`; the module does nothing and touches no database while `Contact:Enabled=false`.
|
|
- Release conditions (also in the comment of that section): `ForwardedHeaders__KnownProxies__0` = reverse proxy (IIS) address first (otherwise the whole site shares one bucket); `Contact__RecipientEmail` (env only); mail via `Email__Smtp__*`, `App__PublicBaseUrl`; sender = `Email:FromAddress` or the address chosen in the site settings from `Email:AllowedFromAddresses` (set by environment for ASF); captcha settings above; then `Contact__Enabled=true` and the admin switch (Berichten).
|
|
- Host tests (`Api.AndreaSlopFotografie.Tests/ContactHostTests.cs`, real MariaDB): closed by default; public routes stay reachable (200/202) while the availability gate is "not available" and the management routes answer 503; per-client buckets with a known proxy vs one shared bucket without.
|
|
|
|
## 9. CMS-U11 additions (recipient address from the site settings)
|
|
|
|
Order of precedence for the address contact mails are sent to: **site setting (CMS admin, Berichten) > `Contact__RecipientEmail` (environment) > none.** The setting changes without a restart (read on every send); an invalid stored value is ignored (falls back). Table `ContactSettings` gets a nullable `RecipientEmail` (migration `ContactSettingsRecipient`, additive).
|
|
|
|
| Method + path | Auth | Notes |
|
|
|---|---|---|
|
|
| `GET /contact-settings` | AdminOnly | now `{ enabled, hostEnabled, recipientEmail: string\|null, recipientSource: "setting"\|"config"\|"none" }`. `recipientEmail` is only the CMS setting; **the address from the environment is never returned** (source `config` = "set by the server configuration"). |
|
|
| `PUT /contact-settings/recipient` `{ "recipientEmail": string\|null }` | AdminOnly | `200` same shape as GET; `null`/blank clears the setting (back to the environment default); trimmed; `EmailAddressRules`; `400` problem+json `errors.recipientEmail = ["invalid"]` or `["tooLong"]` (> 254), never echoing the value; `401/403/404/503` as the other management routes. Not part of any public route or OpenAPI example. |
|
|
| `PUT /contact-settings` `{ enabled }` | AdminOnly | unchanged. |
|
|
|
|
Without any address (`recipientSource: "none"`) the host still starts and the form can still be switched on (warn, not block): messages are stored, the mail stays `pending` with `mailError: "recipient_not_configured"` (not counted as an attempt) and goes out by itself within seconds once an address is set (setting the address wakes the mail sender). The admin shows a warning banner on the switch card. Release condition for SLP/ASF: the address no longer has to be in the environment when it is set in the admin.
|