diff --git a/aidlc-docs/features/contact-feature/contact-feature-prereqs.md b/aidlc-docs/features/contact-feature/contact-feature-prereqs.md new file mode 100644 index 0000000..7c3f630 --- /dev/null +++ b/aidlc-docs/features/contact-feature/contact-feature-prereqs.md @@ -0,0 +1,24 @@ +# Contact feature - prerequisites (read before building) + +Status: not started. Written 2026-11-09 so a new session finds what was decided in conversations. Not part of the identity-email-notifications release. + +## 1. Decision (Bryan): availability statuses block the CMS only, never the public site +- Both the master status and the instance's own status (disabled / maintenance) block **CMS actions only**: changing data or settings, and the admin. +- **Public routes must never answer 503**: public offerings, contact token, contact submit, `System/capabilities` for guests, `Availability/status`. +- The maintenance status stays queryable (open `GET /api/v1/Availability/status`), so the front-end decides what to do with it. +- A status that also switches the public site off may come later. Not now. +- Admin routes are never exempted. + +## 2. Current gate and proposed change +- **Now** (`AvailabilityMiddleware`): everything under `/api/` is gated except a bypass list (`Availability/status`, `Auth/`, `Setup/status`, `master/`, `SlaveStatus`, `/health`). A verified Owner/Administrator token passes. Master status is checked first, then the own status; both answer 503. Since 85d0f6a an *expired* token on a blocked route answers 401 so the app refreshes its session. +- **Proposed**: keep deny-by-default and mark public routes explicitly as open. Preferred: a marker attribute (e.g. `[PublicSiteEndpoint]`, defined in Core) read from endpoint metadata - needs the middleware to run after routing; fallback: a second prefix list next to the bypass list. A forgotten or new admin route then stays closed. +- **Tests affected** (Availability.Tests, roughly 6-10): `AvailabilityGateScopeTests` (move public paths from "still blocked" to "open", add a negative check that admin routes stay blocked), `AvailabilityMiddlewareMasterGateTests` and `AvailabilityMiddlewareTests` (public route stays 200 under master-down, Disabled and Maintenance). With the attribute approach add a test that lists all public actions so none is added silently. +- No migration. Behaviour change: public offerings no longer 503 on a disabled CMS. + +## 3. Evidence that this is needed +`GET /api/v1/System/capabilities` returns 503 to a guest while the CMS is off (ASF test journal, 2026-11-09 ~23:33 local; the gate logs "Request blocked by master gate"). The login page reads it, so a guest on a disabled CMS sees failed requests. + +## 4. Deferred items (decide with Bryan, not part of the release) +- Own rate-limit policy for `Setup/status` (e.g. 60/min): it now shares the `refresh` policy (20 per 60 s per client IP), and one admin page load costs two permits. +- Judge the admin token only when a request would really be blocked: today every gated API call evaluates it, so any normal User call logs a "bypass rejected" security event (log noise). +- A visible error state with a "Reload" button as a safety net for the admin app, and a fetch timeout in the API client (a hanging request currently means an endless spinner; start-up retries can also wait up to ~45 s on a 429 with Retry-After).