Admin en bezoeker gebruiken dezelfde resource; alleen GET is anoniem, de rest vereist AdminOnly. OfferingAdminDto vervalt (displayOrder zit nu in OfferingDto), move-up/move-down zijn vervangen door de order-route die een onbekende of onvolledige lijst met 400 afwijst. De admin-frontend en alle tests zijn mee aangepast. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
6.9 KiB
6.9 KiB
Application Design (minimal) — contact-forms-module
Scope: component names, boundaries, configuration keys, and the few design points the contract leaves open. Behaviour and field-level detail stay in contract v0.3.1.
1. Repo findings that shape the design (master d9cc539)
- Modules are
IModuleclasses discovered via the host's project references (orchestrator.DiscoverModules()); a host gets a module by aProjectReferencein its.csproj. Phase 1 registers Contact inApi.SlpSoftwareonly;Api.AndreaSlopFotografiedoes not exist on master and gets the reference after the ASF merge (Phase 2). - Data Protection is already host-level:
AddCmsDataProtection()(CmsHost) persists keys in the database (ApplicationDbContext) with a fixed application discriminator. Contact therefore does not own a key ring; it only asksIDataProtectionProviderfor a protector with a per-site purpose string. (This replaces the plan wording "keyring in own DbContext".) - Controller convention:
[Route("offerings")]under the global/api/v1prefix, class-level[Authorize(Policy = "AdminOnly")], public actions[AllowAnonymous]+[EnableRateLimiting("<policy>")], admin actions underofferings/admin. Existing public limiter policy:offerings-public. /System/capabilitieslistsModuleOrchestrator.ModuleNames: a module namedContactappears automatically.AvailabilityMiddlewareis prefix-bypass based, with verified-admin-token bypass. Existing admin routes are not under a common/api/v1/admin/prefix (they are.../adminsuffixes or controllers such asUsers).
2. Deviation to confirm (admin route shape)
Contract § 6 writes /api/v1/admin/contact-messages. Repo convention is contact-messages/admin... (as offerings/admin). Proposal: follow the repo convention: GET /api/v1/contact-messages/admin, GET .../admin/{id}, PATCH .../admin/{id}, DELETE .../admin/{id}, POST .../admin/{id}/resend. The 503-regression test then iterates over all endpoints without [PublicSiteEndpoint] instead of relying on a prefix. Redesign - SLS to update the contract (or veto).
3. Components
| Component | Project | Responsibility |
|---|---|---|
PublicSiteEndpointAttribute |
Core (Availability) |
marker, AttributeTargets.Method; read via endpoint metadata |
| Availability check | Modules.Availability AvailabilityMiddleware |
minimal change: after the prefix bypass, context.GetEndpoint()?.Metadata.GetMetadata<PublicSiteEndpointAttribute>() != null => next (deny-by-default otherwise) |
| 429 handling | Core AddCmsRateLimiting OnRejected |
set Retry-After (from MetadataName.RetryAfter when available, else window), write application/problem+json; keep the security-event call |
| Offering category | Modules.Offerings | Offering.Category (nullable, max 100), DTOs/requests, ICategoryOptions (reads Offerings:Categories), validation in service |
ContactModule |
Modules.Contact | IModule "Contact"; registers DbContext (MySQL, same pattern), services, hosted services; Migrate() in UseModule |
ContactDbContext |
Modules.Contact | ContactMessages, IdempotencyRecords |
ContactMessagesController |
Modules.Contact | public token + submit ([PublicSiteEndpoint], [AllowAnonymous], limiter policies); admin actions AdminOnly (U4) |
ContactSubmissionService |
Modules.Contact | validate, classify (genuine/spam), idempotency, store, trigger mail |
ContactValidator |
Modules.Contact | pure function: input => {field: [codes]}; shared rules (trim, length, regex, control chars) |
ContactTokenService |
Modules.Contact | issue/verify via IDataProtector (purpose SlpModularCms.Contact.Token.{siteId}), ITimeProvider; verify result: valid / tooYoung / expired-or-invalid |
ICaptchaVerifier (+NullCaptchaVerifier, later Friendly Captcha impl) |
Modules.Contact | fail-open on provider failure, log without PII |
IContactMailSender (+NoOpContactMailSender) |
Modules.Contact | seam for mail; real implementation in Phase 2 (CMS-U5) |
ContactRetentionService |
Modules.Contact | daily BackgroundService: delete rows past retentionUntil and idempotency records > 24 h |
ContactSiteOptions |
Modules.Contact | Contact:* binding (validated on start; recipient/sender not required until mail is wired) |
| Log scrubbing | Core Observability | extra rule in SecurityEventProcessor/Sentry BeforeSend for the contact routes |
4. Configuration keys
| Key | Default | Notes |
|---|---|---|
Offerings:Categories |
[] |
per host; empty list => category must be null |
Contact:SiteId |
host name | derived from host config, never from the request; used in the token purpose and stored on rows |
Contact:MinSeconds |
3 | |
Contact:TokenLifetimeMinutes |
120 | |
Contact:RetentionMonths |
12 | per row at insert |
Contact:SpamRetentionDays |
30 | |
Contact:MaxSpamRowsPerDay |
200 | cap per site per day, then 202 without storing |
Contact:MaxBodyBytes |
16384 | |
Contact:HoneypotField |
hpCheck |
|
Contact:RecipientEmail, Contact:SenderEmail |
none | env-only for ASF; not committed (Phase 2) |
Contact:Captcha:Enabled/Provider/SiteKey/Secret |
false | secret via env/secrets |
RateLimiting:ContactForm |
5 / 600 s | per client IP |
RateLimiting:ContactToken |
20 / 600 s | per client IP |
RateLimiting:ContactResend |
5 / 600 s | admin resend |
5. Data
ContactMessage:Id(Guid),SiteId,ReceivedAt,Name,Email,Subject,Message,Status(New|Read|Archived|Spam|Converted),MailStatus(Pending|Sent|Failed|NotApplicable),MailError(code only),MailAttempts,NextMailAttemptAt,RetentionUntil. Indexes:(SiteId, Status, ReceivedAt),RetentionUntil. No IP.IdempotencyRecord:Key(Guid),SiteId,CreatedAt,StatusCode; unique index(SiteId, Key). No request content.Offering.Category:varchar(100)NULL.
6. OpenAPI export
- Committed file
openapi/cms-api.v1.jsonin the repo root. A test builds the document from the SlpSoftware host (AddOpenApi) and compares it to the file; setUPDATE_OPENAPI=1to rewrite it. Drift fails the build, socms-clientalways generates from a current file. - The contract's response components (
Validation,TooLarge,RateLimited,Problem) are declared through anIOpenApiDocumentTransformerso the exported shape matches contract § 8.
7. Cross-cutting decisions
- Identical 202 for genuine and spam: same code path up to the store step; spam differs only by
Status=SpamandRetentionUntil=+30d, and never triggers mail. - Invalid/forged/other-site/expired token =>
errors.token = ["expired"]; too-young token => silent spam path. - Logging: only status code, site id and outcome enum for these routes; request logging for them is disabled; a test asserts that a thrown exception's log entry holds no body or field value.
- Security Baseline is checked at each stage (anonymous endpoint, input limits, no oracle, secrets only via env, generic 5xx, headers).