Zero-Trust Auth Routing
Overview
Ensure that unauthenticated users never see any authenticated UI (sidebar, topbar, app shell) before their session is confirmed. The auth gate runs at the earliest point in the component tree — before PppContainer mounts.
Open Questions
| # | Question | Ref | Proposed answer |
|---|---|---|---|
| — | No open questions. |
Acceptance Criteria
- ✅ On any page load or direct URL navigation, a session check runs before any authenticated UI renders
- ✅ While session check is in-flight: a single, full-screen branded loading state only (no sidebar, topbar, or app shell). Every boot/guard phase — top-level Suspense,
InternalAppsession pending,PppModules, and theAuthGuardedRouteroute-guard pending branch — renders the same unifiedAppLoadingScreencomponent, so there is no spinner-then-branded-screen "double loading" flash between phases (#8638). - ✅ No valid session: immediate redirect to
/loginwith zero flash of authenticated UI - ✅ Valid session: full app renders normally
- ✅ Redirect preserves originally requested URL (e.g.
?redirect=/settings/hospitals) so user lands there after login - ✅ Login page remains a public route (no gate)
- ✅ Applies on initial load, page refresh, and mid-session expiry
- ✅ No flash of authenticated content on any protected route when unauthenticated
- ✅ Backend tRPC procedures that are gated by a subscription tier (e.g. surgical logbook) enforce the account-type invariant server-side — UI-level redirects are defence-in-depth, not the security boundary. Logbook procedures require
accountAccess ∈ { 'ppp', 'cpdppp' }; CPD-only sessions receiveFORBIDDEN. - ✅ Frontend routes for premium features (
/logbook-case,/wba,/wellness,/appraisals,/retrospective,/timesheet) are wrapped in aRequirePppAccessguard so that CPD-only users deep-linking via URL/bookmark are redirected to/cpd-dashboardwith an "upgrade your plan" snackbar, instead of seeing an empty premium page. The guard allowsaccountAccess ∈ { 'ppp', 'cpdppp' }; every other value (including admin-only) is bounced. - ✅ The same PPP-tier guard (
requirePppAccessProcedure) is applied to every PPP-only router namespace —wellness.*,appraisalWorkflow.*,dashboard.wba.*,timesheets.*— so a CPD-only user who calls any of these procedures directly receivesFORBIDDENrather than data. CPD-tier procedures (cpd.*,cpdPlan.*,auth.*,payments.*,getCurrentUser) remain callable by both tiers. - ✅
hospitalStaff.*is gated byhospitalAdminProcedure(notrequirePppAccessProcedure). This is the stronger policy: the caller must be an admin (adminorsuper_admin) for the specific hospital whose staff they are querying, or a platform super admin. This scope-limited authorisation subsumes the subscription-tier check — a CPD-only user with no hospital-admin grant is already rejected before the PPP-tier guard would run, so stackingrequirePppAccessProcedureon top would be redundant and would risk breaking the support-admin path. The invariant under review (AC2) is "a CPD-only user cannot list another hospital's staff";hospitalAdminProcedureenforces that invariant directly via the hospital-scoped admin check (seeapi/backend-ppp/src/utils/hospitalAdminProcedure.ts).
Architecture
Before (problem)
App.tsx → InternalApp → PppContainer (shell renders unconditionally)
→ PppAppContainer (sidebar, topbar painted)
→ PppModules.tsx (auth check fires HERE — too late)After (fix)
App.tsx → InternalApp (auth gate HERE — before any shell mounts)
├── pending → <AppLoadingScreen /> branded full-screen (no shell)
├── unauthed → <Navigate to="/login?redirect=..." />
└── authed → SessionContext.Provider
→ PppContainer → PppAppContainer → PppModulesImplementation
| File | Change |
|---|---|
instances/ppp/src/InternalApp.tsx | Added session gate using authClient.getSession(). Renders full-screen spinner while pending, redirects to /login with ?redirect= param if no session. |
instances/ppp/src/contexts/SessionContext.tsx | New context signalling session confirmation to downstream providers. |
instances/ppp/src/contexts/UserContext.tsx | getCurrentUser query enabled: isSessionConfirmed — prevents spurious unauthenticated API calls. |
instances/ppp/src/slots/CoreAppContainerLogin/CoreAppContainerLogin.tsx | getPostAuthRedirectTarget() checks ?redirect= query param for post-login navigation. |
Open GitHub Issues
Open issues on label:feature:auth-zero-trust-routing — no open issues. Fetched at: 2026-10-13T07:29:49Z — live list on GitHub.
Change Log
| Date | Change | Reason |
|---|---|---|
| 2026-09-28 | Per-IP rate limits (tRPC limiter, external-approver code limits, Better Auth's built-in limiter) and audit / failed-login IP capture now resolve the client address from CF-Connecting-IP (set by the Cloudflare edge) with a TCP-socket-peer fallback, via one helper utils/clientIp.ts. X-Forwarded-For is no longer trusted (trust proxy is now false). No acceptance criterion changes. | #12533 — Security review of #12442 found trust proxy: true made req.ip the leftmost client-supplied X-Forwarded-For entry, so rotating that header bypassed every per-IP rate limit, including the sensitive tier on public magic-link procedures. |
| 2026-06-17 | Unified every boot/guard loading phase (top-level Suspense, InternalApp session-pending, PppModules, and the AuthGuardedRoute route-guard pending branch) onto a single branded AppLoadingScreen component. | #8758, #'#8638' — Eliminates the spinner-then-branded-screen "double loading" flash reported in UAT (#8638); the in-flight session-check AC now mandates one consistent branded screen across all phases. |
| 2026-04-28 | Demonstrates the fragment changelog pattern — first row authored as a fragment instead of an inline table edit. | #5273 — Stops cascading DIRTY across sibling PRs when multiple PRs land Change Log rows on the same spec. |
| 2026-03-31 | Initial implementation | #4360 — zero-trust auth routing |
| 2026-04-21 | Added backend account-type guard invariant for subscription-gated procedures; see api/backend-ppp/src/utils/requirePppAccessProcedure.ts | #4881 — CPD-only users could reach logbook tRPC endpoints directly; the UI redirect alone is not a security boundary |
| 2026-04-21 | activities.getByFilter now enforces enforceUserScope on the assessorId filter parameter, mirroring the existing userId/userScope guards. The WBA Received tab was gated by a frontend-only role check; any authenticated user could query another consultant's received WBAs via direct tRPC call. | #5027 — assessor-side WBA data leaked to unauthorised callers; UI role gate is not a security boundary |
| 2026-04-21 | Locked CPD plan status-guard covered by integration test + @regression @requires-backend @issue-4990 BDD scenario — verifies updateCpdPlan returns FORBIDDEN and the DB row is unmodified when a direct tRPC call bypasses the UI | #4990 — server-side status checks must be exercised, not merely UI-disabled |
| Date | Change | Reason |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| 2026-03-31 | Initial implementation | #4360 — zero-trust auth routing |
| 2026-04-21 | Added backend account-type guard invariant for subscription-gated procedures; see api/backend-ppp/src/utils/requirePppAccessProcedure.ts | #4881 — CPD-only users could reach logbook tRPC endpoints directly; the UI redirect alone is not a security boundary |
| 2026-04-21 | activities.getByFilter now enforces enforceUserScope on the assessorId filter parameter, mirroring the existing userId/userScope guards. The WBA Received tab was gated by a frontend-only role check; any authenticated user could query another consultant's received WBAs via direct tRPC call. | #5027 — assessor-side WBA data leaked to unauthorised callers; UI role gate is not a security boundary |
| 2026-04-21 | Locked CPD plan status-guard covered by integration test + @regression @requires-backend @issue-4990 BDD scenario — verifies updateCpdPlan returns FORBIDDEN and the DB row is unmodified when a direct tRPC call bypasses the UI | #4990 — server-side status checks must be exercised, not merely UI-disabled |