Skip to content

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 ​

#QuestionRefProposed 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, InternalApp session pending, PppModules, and the AuthGuardedRoute route-guard pending branch — renders the same unified AppLoadingScreen component, so there is no spinner-then-branded-screen "double loading" flash between phases (#8638).
  • ✅ No valid session: immediate redirect to /login with 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 receive FORBIDDEN.
  • ✅ Frontend routes for premium features (/logbook-case, /wba, /wellness, /appraisals, /retrospective, /timesheet) are wrapped in a RequirePppAccess guard so that CPD-only users deep-linking via URL/bookmark are redirected to /cpd-dashboard with an "upgrade your plan" snackbar, instead of seeing an empty premium page. The guard allows accountAccess ∈ { '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 receives FORBIDDEN rather than data. CPD-tier procedures (cpd.*, cpdPlan.*, auth.*, payments.*, getCurrentUser) remain callable by both tiers.
  • ✅ hospitalStaff.* is gated by hospitalAdminProcedure (not requirePppAccessProcedure). This is the stronger policy: the caller must be an admin (admin or super_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 stacking requirePppAccessProcedure on 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"; hospitalAdminProcedure enforces that invariant directly via the hospital-scoped admin check (see api/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 → PppModules
Implementation ​
FileChange
instances/ppp/src/InternalApp.tsxAdded 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.tsxNew context signalling session confirmation to downstream providers.
instances/ppp/src/contexts/UserContext.tsxgetCurrentUser query enabled: isSessionConfirmed — prevents spurious unauthenticated API calls.
instances/ppp/src/slots/CoreAppContainerLogin/CoreAppContainerLogin.tsxgetPostAuthRedirectTarget() 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 ​
DateChangeReason
2026-09-28Per-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-17Unified 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-28Demonstrates 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-31Initial implementation#4360 — zero-trust auth routing
2026-04-21Added 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-21activities.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-21Locked 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
DateChangeReason
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
2026-03-31Initial implementation#4360 — zero-trust auth routing
2026-04-21Added 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-21activities.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-21Locked 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

Internal documentation — org members only