# Springboard - Primary (Contact) email change

The purpose of this change is to allow user to change a primary point of contact. All previously registered code / pubKey remain connected to the email that was a primary email at the moment those code were created.

Basic requirements:
- user should be able to change the email via UI
- user needs to confirm new email address via email
- if user does not have access to new email, their account should be able to roll-back to their existing email
- only someone with access to the account can confirm the email change (i.e. if the new email belongs to a different person, they can't click the link to confirm the change)
- Until the email change is completed, your current/old email continues to be valid

Technical constraints
- User's current Springboard session gets invalidated when the email is changed
- We can't identify which sessions are invalid, if multiple sessions are open

## Email Challenge

The UX complexity of the email challenge happens because:
- You have to have a valid springboard credential in your browser to trigger the email change. I.e. you have to currently be logged in)
- As soon as you trigger the change, the existing credential and all related browser sessions will be invalid.
- We have no way of knowing which sessions are valid and closing invalid tabs.

Option A (Recommended):
1. Send the email change with a code
2. User logs into springboard
3. We detect an outstanding change request and show an option for inputting code
4. User inputs code and confirms
5. Email is switched and user logged out or receives new login

Option B:
1. Send user email with challenge link
2. User clicks link **while they are logged into Springboard**
3. New session is opened and email is automatically switched
Note: the old session that was open in #2 is now invalid but we can't close it.

## Proposed Solution (Option A)

The basic flow of our solution is shown below. The standard login flow is included at the beginning for context.

Participant Inbox
Participant Springboard
Participant HBS
Note over Springboard: Login to Springboard
Springboard-->HBS: Request login credentials
HBS-->Inbox: Send challenge
Inbox-->HBS: Confirm login
HBS-->Springboard: Return login credentials
Note over Springboard: ...
Note over Springboard: Step 1. Edit email
Note over Springboard: Step 2. Confirm change
Springboard-->HBS: Submit edit request
HBS-->Springboard: Response
Note over HBS: Generate email-change-token
HBS-->Inbox: Send challenge with token
Note over Inbox: Step 3: User reads code
Note over Springboard: Step 4: User inputs code
Springboard-->HBS: Submit token
HBS-->Springboard: Return new login credentials

Where the challenge steps are complex and need to be considered further.

### Interim State
- The account email never in an interim state. The old email is valid until the email switch is complete
- The email-change-token is tracked separately
- All active tokens become invalid once the email is changed
- We propose a maximum number of active tokens (3?) to prevent spamming. Each token expires after 5 minutes.

## User Steps Details

### Step 1: User clicks on the edit icon


- Email gets replaced with an input
- Two buttons next to the input (confirm / reject)
- User can input a new email
- Reject click - revert the change and replace the input with email

### Step 2: User clicks confirm

- Validate if the provided value is an email
- Make http request to `change-email-request` endpoint that creates a unique code and sends a 4/6 char code via email

#### `change-email-request` handling

`200 success`
- user stays logged in
- a temporary overlay is shown with information "Check your email"
- overlay disappears after X seconds
- Springboard includes a place to input confirmation code

`403 error - too many active email change requests`
`409 conflict - new email exists in our database` - What is this?


***Q (Celestial): I think we should use an overlay instead of modal to be consistent, users already know that modal and know that they should check their email in that case. I would change the message though to***

### Step 3: Email is received

### Step 4: Input code from email
- http request - `change-email` - verifies the unique code and updates the user's email address
- HBS sends new JWT with updated springboard credentials

#### `change-email` responses

`200 success`
`401 unauthorized - code expired`
`500` unable to generate JWT?

***Q (Celestial): What should be the message in that case (email change failed)?***

--------
# Old notes

Proposed solution:

***NOTE: Disregard Step 5 on the drawing, it was updated in the meantime. A proper Step 5 is explained below in the text.***


Step 1: Primary Contact email with edit icon enabled