Authentication
Dual authentication paths with cryptographic token validation
Local Email / Password
- Passwords hashed with bcrypt (cost factor 12) — never stored in plain text
- JWT access tokens signed with HS256; expire after 8 hours
- JWT refresh tokens expire after 7 days; single-use with rotation
- Token ID (
jti) stored in session table for revocation - Session includes device type, fingerprint, IP, and user agent
AWS Cognito SSO (PKCE)
- OAuth 2.0 Authorization Code + PKCE flow — no client secrets on the frontend
- RS256 JWT tokens verified against Cognito JWKS on every request
- Identity providers: Google Workspace, Microsoft Entra ID
- Post-authentication Lambda syncs
last_login_atto CareSphere - Post-confirmation Lambda creates user record (status
pendinguntil admin activates)
JWTAuthMiddleware, which validates the token, resolves the user's current role and facility, and sets PostgreSQL session variables (app.current_user_id, app.current_user_role, app.current_facility_id) before any query runs.Role Hierarchy & Permissions
Five user roles with progressively scoped access
| Role | Scope | Key Capabilities | PHI Access |
|---|---|---|---|
| superadmin | Platform-wide | Full system access; enterprise management; user lifecycle; system config | ALL |
| corporate | Enterprise-wide | Portfolio analytics; cross-facility reporting; compliance dashboard; staff & cert overview | AGGREGATE |
| admin | Single facility | Resident management; staff management; incident reports; facility configuration | FACILITY |
| staff | Assigned facility | Care notes; vitals; medications; activity logs; residents in their wing | WING/ASSIGNED |
| family | Linked residents only | View resident wellness; joy network; calendar; approved care updates | LINKED ONLY |
caresphere.user_roles table stores all assigned roles; the active role drives RLS context for each session.Row Level Security (RLS)
Database-enforced access boundaries — not just application logic
RLS is enabled on all PHI and medication tables. Policies evaluate session-local variables set by the middleware on every connection before returning any rows. Even a compromised application cannot read out-of-scope data — the database engine enforces isolation.
Facility Isolation
Resident PHI is scoped to app.current_facility_id. Staff users can never read residents from another facility, even if they know the resident's UUID.
Staff Self-Access
Staff PII (phi.staff_pii) is restricted to the staff member's own row unless the caller's role is corporate, admin, or superadmin.
Family Scoping
Family users can only read or receive notifications for residents explicitly linked in caresphere.family_resident_links with an active, non-expired link.
Corporate Visibility
Corporate users see aggregate data across all facilities within their enterprise but cannot drill into individual resident PHI — only summary and compliance views.
Break-Glass Access
Emergency access bypasses normal RLS with is_emergency_access = TRUE. The bypass is mandatory-audited: reason, accessing user, and timestamp are logged to audit.access_logs.
Medication Isolation
Medication records in the med schema follow the same facility isolation as PHI. Controlled substance logs additionally require the dual-witness flag before writes are accepted.
Session Management
Per-device session tracking with independent revocation
revoked_at in caresphere.sessions. Logout revokes the current session; admin can revoke all sessions for a user.is_mfa_enabled flag per user drives enforcement for high-privilege roles.