Files
slp-modular-cms/aidlc-docs/features/contact-feature/contact-feature-prereqs.md
T

3.0 KiB

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).