Security and Privacy

Authentication, Registration, and Password Recovery

1. User Login

SaludVital shall provide a login page where users can authenticate using their registered email address and password.

The login page shall include:

• Email address field.
• Password field.
• Login button.
• "Forgot your password?" link.
• Registration link with the message "Don't have an account? Sign up."

After successful authentication, the system shall identify the user's role and redirect the user to the appropriate interface:

• Administrator dashboard.
• Doctor dashboard.
• Patient dashboard.

The system shall validate credentials and permissions before granting access to protected functionality. Invalid credentials shall produce an appropriate error message in Spanish without revealing sensitive account information.

2. Password Recovery

SaludVital shall provide a password recovery process for users who cannot access their accounts.

The recovery workflow shall be:

1. The user selects "Forgot your password?" on the login page.
2. The system displays a form requesting the user's email address.
3. The form provides two buttons: "Cancel" and "Send email".
4. When the user selects "Send email", the system sends a password recovery code to the registered email address, subject to account and security policies.
5. The user enters the received code on the verification page.
6. The system verifies the code.
7. If the code is valid and has not expired, the system allows the user to set a new password and confirm it.
8. If the code is invalid or expired, the system informs the user that verification failed and provides an option to request another code.
9. The user may return to the login page or cancel the recovery process.

The system shall protect recovery codes against unauthorized use. Codes shall expire, have appropriate usage limits, and be invalidated after successful use. The system shall not store recovery codes as plain text.

The recovery process shall provide appropriate feedback in Spanish without unnecessarily disclosing whether an email address is registered.

3. Patient Registration

SaludVital shall provide a registration form for new patients.

The registration form shall include the following fields:

• First name.
• Last name.
• Email address.
• Phone number.
• Date of birth.
• Document type.
• Document number.
• Residential department.
• Residential city or municipality.
• Password.
• Confirm password.

The form shall include a "Create account" button.

Before creating an account, the system shall:

• Validate all required fields.
• Validate the email address and required document information.
• Verify that the password meets the established security requirements.
• Confirm that the password and password confirmation match.
• Prevent duplicate accounts according to the configured unique identifiers.
• Store passwords using a secure password-hashing mechanism.
• Associate the new account with the patient role through the application's authorization rules.

After successful registration, the system shall provide confirmation in Spanish and guide the patient to the appropriate next step.

4. Account and Role Management

SaludVital shall distinguish between a patient record and a web login account.

A patient may be registered in the SaludVital database without having web login credentials. This distinction supports the WhatsApp appointment workflow, where an existing patient may request an appointment without signing in to the web application.

The system shall recognize three primary roles:

• Patient.
• Doctor.
• Administrator.

Users shall only access functionality permitted by their assigned roles and permissions.

Public registration shall not allow users to assign themselves the doctor or administrator role. Those roles shall be assigned through authorized administrative processes.

5. Security Requirements

• Authentication shall use the registered email address and password.
• Passwords shall never be stored in plain text.
• Authentication tokens shall expire according to the configured JWT policy.
• Protected operations shall enforce role-based authorization on the backend.
• Password recovery codes shall be time-limited and protected against reuse.
• Registration and recovery forms shall validate user input.
• Sensitive account and personal information shall be protected from unauthorized access.
• Authentication and recovery responses shall be displayed in Spanish.
• The implementation shall be covered by appropriate unit, integration, and security tests.

6. Related Documentation

• Product Vision and Scope.
• Functional Requirements.
• Stakeholders and User Roles.
• Database Design.
• Testing Strategy.

Shared Login and Role-Based Access

1. Single Login Entry Point

SaludVital shall provide a single login page for all three primary user roles: Patient, Doctor, and Administrator.

All users shall authenticate using their registered email address and password.

The login form shall not allow users to select or assign their own role. The system shall determine the user's role from the validated account information stored in the database.

2. Role-Based Redirection

After successful authentication, the backend shall identify the authenticated user's role and redirect the user to the appropriate interface:

• Patient: Patient dashboard.
• Doctor: Doctor dashboard.
• Administrator: Administration dashboard.

The backend shall enforce role-based authorization for all protected operations. Hiding a page or menu item shall not replace server-side permission checks.

3. Patient Account Registration

Patients may create their own accounts through the public registration form, subject to the defined registration validation rules.

Patient registration shall assign the Patient role through the application's trusted registration process. Users shall not be able to assign themselves the Doctor or Administrator role.

4. Doctor Account Creation

Doctors shall not register themselves through the public registration form.

An authorized administrator shall create and manage doctor records through the administration module.

Doctor login credentials shall be provisioned through an authorized account creation process. The doctor shall use the shared login page to access the system.

5. Administrator Account Creation

Administrator accounts shall be created or provisioned through an authorized administrative process.

The public registration form shall not allow a user to create an Administrator account or assign themselves the Administrator role.

6. Account and Role Validation

The system shall verify that the account exists, the credentials are valid, and the account is permitted to access the application.

The system shall enforce the permissions associated with the authenticated role on the backend.

Unauthorized access attempts shall be rejected and handled securely.