# Keycard screens and flows

## Keycard specific screens

1. PIN Entry screen. The PIN is a 6 digit number. It can be retried up to 3 times after which the card is frozen and can be unfrozen with PUK. Used on authentication for most card interaction.
2. PUK Entry screen. The PUK is a 12 digit number. It can be retried up to 5 times after which the card is blocked and can only be reused with factory reset (removes all keys on card).
3. Pairing entry screen. The pairing code is an arbitrary string of any length (not empty). There isn't a retry counter. This screen can be part of any flow if the pairing is broken/missing and the pairing password is not the default one (currently we don't have a default one but we plan to introduce that)
4. PIN creation screen. When initializing the card or unfreezing the card with the PUK a new PIN must be created. Also, can be used when changing the PIN. As when choosing a password, the PIN should be entered twice for verification. In mobile this screen does not exist and the PIN entry screen is shown twice (with descriptive labels) instead.
5. PUK creation screen. Like PIN screen but for PUK. We don't prompt for a PUK during initialization and use a random one instead. The screen is only used when explicitly changing the PUK
6. Pairing creation screen. Like PIN screen but for pairing password. We don't prompt for a pairing password during initialization and use a random one instead (soon, we will use a default one instead). The screen is only used when explicitly changing the pairing password.
7. Connection screen. A prompt to insert the card. Should be only visible when no card is inserted/card has been removed. In mobile it is always visible when interacting with the card because the card is tapped and serves as a connection indicator and a cue to tap/remove the card.

## Flows

### Onboarding

The goal of onboarding is creating an account. Normally we offer two options: generating a new one or importing a mnemonic. With Keycard a third option to use an already personalized Keycard also exists.

The import mnemonic scenario is the same as without Keycard except that:

1. we must prompt to connect the card
2. if the card is uninitialized, we must show the PIN creation screen instead of the password creation screen; or
3. if the card is already initialized we must give the option factory reset the card. If this is selected, we go back to point 2, otherwise we do the pairing subflow and PIN subflow (both described in a later section).

The generate account scenario is modified in the same way as the import mnemonic one. However, if we want to take advantage of the card's secure random generation, card authentication (point 2 or 3 above) before showing the user a list of accounts to select from. This is because the card must initialized and paired to use it to generated the accounts

The third flow, which is specific to Keycard instead does not require the user to enter a mnemonic or select an account, since this is already on card. The full flow is

1. prompt to connect a card with an account
2. if the card has no account, error (go back to flow selection?)
3. pairing subflow
4. PIN subflow
5. Finish - the account is automatically logged in

### Backup

The user must be given a way to create a second card with the same account for backup purpose or to regain access to an account after losing the card or its credentials. This is the same as the import mnemonic scenario, except that card is always factory reset if it was already initialized (proper warning should be given) and that the inserted mnemonic is checked to correspond to the account you are trying to backup (giving an error during mnemonic entry if it doesn't match)

### Login

Login is the same as with regular account but the PIN subflow is executed instead of password entry. Also the backup flow must be accessible if the user lost the card and bought a new one

### Signing

Signing is the same as with regular account but the PIN subflow is executed instead of password entry

### Change PIN/PUK/Pairing

These three flows are very similar to each other. All 3 require

1. prompt connection
2. pairing subflow
3. PIN subflow (regardless of what we are changing, we only need the PIN)
4. creation of new PIN/PUK/pairing

### Account migration flow

Needed to migrate a regular account to Keycard. The flow is the same as the backup flow but can be triggered from a non-keycard account either from logged in or logged out state. The final result is that the account is converted to a Keycard account without losing chats/contacts/etc

### Pairing subflow

The pairing subflow is part of all interactions, but almost always will not show anything to the user. The flow is

1. Check if we already have a pairing
2. If not, try to pair with default password
3. If unsuccesful, show Pairing screen
4. Repeat pairing screen until succesful, on cancel the entire operation should be cancelled

### PIN subflow

This flow is also part of all flows and will always show at least a prompt

1. check if the PIN retry counter >= 0
2. if yes, show PIN prompt. If PIN correct finish, otherwise back to 1
3. if no, check if PUK retry counter >= 0
4. if yes, give the user the option to cancel, recover with PUK or perform a factory reset
5. if no, only give the chance to cancel or perform factory reset
6. if PUK is selected, prompt for both the new PIN and for the PUK. The card doesn't allow unblocking the PUK without also giving a new PIN in the same command so feedback will only be possible after inserting both. If PUK is correct finish, otherwise ask for the PUK again unless counter is = 0, in which case you go to 5.
7. if the user choses factory reset and we are in onboarding, finish and repeat the step that triggered the PIN subflow (it will not fall in the not-initialized case). If we are not in onboarding start the backup subflow before returning to the flow that triggered the PIN subflow