44 lines
4.8 KiB
Markdown
44 lines
4.8 KiB
Markdown
# Application Design: cms-api-foundation (consolidated)
|
|
|
|
Details: [components.md](components.md), [component-methods.md](component-methods.md), [services.md](services.md), [component-dependency.md](component-dependency.md).
|
|
|
|
## Summary
|
|
|
|
Andrea's site runs from a new client host, `SlpModularCms.Api.AndreaSlopFotografie`, in the CMS repo. The host serves the admin (`/admin`), the API (`/api/v1`) and the prerendered site (`/`) in one process. Additive changes to the shared host give it a prerendered-site mode with the hosting behaviour nginx provides today, and a third code-defined CSP policy, `StrictSite`. The admin gets a per-site theme and default language through build-time variables. The web repo gains a delivery job and an extended deployment check that doubles as the CSP drift guard.
|
|
|
|
## Design decisions
|
|
|
|
| # | Decision | Consequence |
|
|
|---|---|---|
|
|
| D1 | A site's modules = the module projects its client references (existing DLL mechanism). No config filter. | No new filter code. Andrea does not reference `Offerings`; adding the reference later switches it on. Requirements FR-2 updated accordingly. |
|
|
| D2 | New policy `StrictSite` in `CspPolicyCatalog`. | Admin `Strict` unchanged. Site CSP equals the current nginx one when the origin lists match. |
|
|
| D3 | CSP drift guard = exact-CSP assertion in the web repo's `verify-deployment.sh`. | Cross-repo coupling stays in one script; drift fails the web deploy. |
|
|
| D4 | Hosting parity for what the site relies on: canonical redirects, `404.html` with status 404, cache rules, text compression, per-environment `noindex` and `robots.txt`. | The host replaces nginx without changing SEO behaviour; test is not indexed. |
|
|
| D5 | Serving mode is code (`CmsHostOptions` in the client's `Program.cs`); environment-dependent settings are appsettings. | `SpaFallback` stays the default, so `Api` and `Api.SlpSoftware` do not change. |
|
|
| D6 | Theme = folder with CSS token overrides and assets, selected with `VITE_THEME`; default language with `VITE_DEFAULT_LANGUAGE`. | One admin source tree, one build per client; no theme API. |
|
|
| D7 | The brief lives in this repo and a copy is placed in the CMS repo's AIDLC folder. | The location inside the CMS workspace is agreed with the CMS session when handing over. |
|
|
| D8 | Reserved prefixes (`/admin`, `/api/v1`, `/health`) are never handled by the website middleware. | An unknown API path remains an API 404 instead of the site's 404 page. |
|
|
|
|
## Security Baseline compliance (design level)
|
|
|
|
| Rule | Status | Note |
|
|
|---|---|---|
|
|
| SECURITY-04 headers | Compliant by design | `StrictSite` carries a restrictive CSP (no `unsafe-inline` in `script-src`, no `unsafe-eval`); HSTS, nosniff, DENY and Referrer-Policy come from the existing header writer. To confirm in Functional Design: HSTS is emitted for the website path. `style-src 'unsafe-inline'` is the existing, documented exception (Chakra/Emotion runtime styles). |
|
|
| SECURITY-05 input validation | Compliant by design | The only new input is the request path: the resolver is total, rejects traversal and never leaves the website root. Property tests (PBT-03 invariants) planned. |
|
|
| SECURITY-08 access control | Compliant | The site is public by intent; `/admin` and `/api/v1` unchanged. |
|
|
| SECURITY-09 hardening | To verify | No directory listing (resolver serves files only); generic errors by the existing handler. The first-administrator setup endpoint on the new instance must be protected until the first admin exists (NFR/FR-11), assessed in NFR Requirements. |
|
|
| SECURITY-10 supply chain | Compliant | No new dependencies (built-in response compression); lock files stay committed. |
|
|
| SECURITY-11 secure design | Compliant | Security logic stays in dedicated catalog and header components. Misuse case: path traversal and cache poisoning through non-canonical URLs, handled by the resolver. Rate limiting stays on login. |
|
|
| SECURITY-13 integrity | Compliant | Delivery is by the pipelines; CSP drift guard added. |
|
|
| SECURITY-15 fail safe | Compliant | Unknown policy names fail startup; missing `404.html` falls back to a plain 404. |
|
|
| SECURITY-01, 02, 03, 06, 07, 14 | Deferred | Assessed in NFR Requirements and Infrastructure Design (database TLS, proxy access logs, deploy identity, network exposure, alerting). |
|
|
|
|
No blocking security findings at this stage.
|
|
|
|
## Open items for the next stages
|
|
|
|
- Which module projects the new host must reference at minimum (Identity and Availability dependency) is a Functional Design finding of the CMS session.
|
|
- Exact canonicalisation rules and the file-resolution order are Functional Design, derived from `web/config/canonicalUrls.ts` and the web's BR-HST rules.
|
|
- Whether the test host's existing reverse proxy (nginx on the Pi) stays in front of the CMS host (TLS, access logs) is decided in Infrastructure Design.
|
|
- Node/SSR remains undecided and is outside step 0 (requirements Q2).
|