Patient Portal — Administrator Guide

Documentation Index

Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt

Use this file to discover all available pages before exploring further.

​

Overview

​

Portal Architecture

​

Authentication Flow

1. Patient registers with email matching their pm_patients record
2. Supabase Auth creates identity; pf_profiles.portal_patient_id links to patient
3. Login creates an audit row in pm_portal_sessions (append-only)
4. Account lockout triggers after 5 consecutive failed attempts

​

Data Isolation

• RLS: pm_portal_has_org_access() and pm_portal_visible_patient_ids() (SECURITY DEFINER)
• Application: usePortalPatientId() hook scopes all portal queries
• Double enforcement: Both layers must pass for data access

​

Proxy Authorization

​

Granting Proxy Access

1. Navigate to the patient’s record in PM
2. Add a proxy entry in pm_portal_users with:
   • proxy_for_patient_id: The patient being represented
   • proxy_relationship: parent, legal_guardian, healthcare_decision_maker, or other
   • proxy_expires_at: Expiration date (required)

​

Revoking Proxy Access

​

Proxy Rules

• Proxy access is always time-limited
• Expired proxies return no data (enforced at RLS and application layers)
• A user can be a proxy for multiple patients
• Proxy audit trail is maintained in pm_portal_sessions

​

Session Management

​

Audit Trail

• portal_user_id, ip_address, user_agent, created_at
• Sessions are append-only — no UPDATE or DELETE allowed
• revoked_at is set on sign-out

​

Account Lockout

• After 5 failed login attempts, pm_portal_users.status is set to locked
• Staff can unlock by updating the status back to active
• Lockout does not affect the Supabase Auth account itself

​

Security Configuration

​

MFA

• Patients can self-enroll in TOTP MFA via the portal Security page
• pm_portal_users.mfa_enabled flag tracks enrollment status
• Supabase Auth handles TOTP factor management natively
• Backup codes are displayed once during enrollment

​

Rate Limiting

• Portal login attempts are tracked per-user
• No IP-based rate limiting at the application layer (rely on Supabase Auth and infrastructure-level protections)

​

Feature Integration Summary

​

SUD Consent & Clinical Records (CL-11)

• The portal checks for active Part 2 consent via cl_check_sud_consent RPC
• Without consent, SUD-related data (e.g., risk level) is suppressed from the portal view
• Non-SUD clinical data (medications, treatment goals) remains accessible per the 21st Century Cures Act
• A consent restriction banner is shown to the patient
• This is enforced at both the RLS layer (database) and the application layer (useConsentCheck)

​

Troubleshooting

​

Database Tables

​

Permissions