Vincular un dispositivo nuevo

Este documento describe la arquitectura de la función que permite a los usuarios vincular su cuenta a un nuevo dispositivo, lo que se conoce como el proceso Vincular nuevo dispositivo.

Terminología 

Para entender este documento, aquí hay algunos términos clave:

import side: El dispositivo que importa la cuenta.
export side: El dispositivo que exporta la cuenta.
token: Un URI que identifica un dispositivo en la Tabla Hash Distribuida (DHT).

Máquina de Estado 

El “demonio” administra esta funcionalidad usando una máquina de estado-autómata.

La evolución del estado se comunica a los clientes, habilitando la visualización de la interfaz adecuada.

Actualmente, la máquina de estados es simétrica tanto para la `parte de importación “como para la “parte de exportación”, aunque, dependiendo de la parte, ciertos estados son inaccesibles.

Descripción general del Estado 

Estado	Nombre	Uso (parte)	Descripción
0	Init	Nada	Estado inicial.
1 de la Comisión	Token disponible	Solo importación	El “token” está disponible. Este es el URI que identifica el nuevo dispositivo en el DHT, que se muestra como texto o un código QR.
2 de la Comisión	Conectado	Exportar/Importar	Se está estableciendo una conexión punto a punto.
3 El	Autenticando	Exportar/Importar	Se está confirmando la identidad de la cuenta y la dirección del dispositivo.
4 El	En progreso	Exportar/Importar	Transición de Estado, se está transfiriendo el archivo de la cuenta.
5 El	Hecho	Exportar/Importar	Estado final. Representa el éxito o el fracaso.

Detalles 

La máquina de estados puede incluir información complementaria para fines de visualización, pasada como un map<String, String> “details`.

Detalles para `import side`

Estado	Nombre	Detalles
0	Init	No procede.
1 de la Comisión	Token disponible	`token`: Un URI de 59 caracteres con el prefijo `jami-auth://`.
2 de la Comisión	Conectado	Sin detalles.
3 El	Autenticando	`peer_id`: Jami ID de la cuenta importada. `auth_scheme`: `{"", "none", "password"}` (vacío si no está protegido). `auth_error`: `{"bad_password"}`.
4 El	En progreso	Sin detalles.
5 El	Hecho	`error`: `{"", "none", "network", "authentication"}` (vacío si no hay error).

Detalles para `export side`

Estado	Nombre	Detalles
0	Init	No procede.
1 de la Comisión	Token disponible	No procede.
2 de la Comisión	Conectado	Sin detalles.
3 El	Autenticando	`peer_address`: Dirección IP del dispositivo exportador.
4 El	En progreso	Sin detalles.
5 El	Hecho	`error`: `{"", "none", "network", "authentication"}` (vacío si no hay error).

API entre demonio y cliente.

API para `import side`

Nombre de la Señal	Dirección	Finalidad
`addAccount`	Saliente	Anuncia la intención de importar una cuenta. Debe incluir la clave `Account.archiveURL="jami-auth"`.
`provideAccountAuthentication`	Saliente	Proporciona una contraseña si es necesario y confirma la identidad de la cuenta importada.
`removeAccount`	Saliente	Cancela la operación.
`deviceAuthStateChanged`	Entrantes	Indica el nuevo estado y proporciona detalles.

API para `export side`

Nombre de la Señal	Dirección	Finalidad
`addDevice`	Saliente	Anuncia la intención de exportar una cuenta.
`confirmAddDevice`	Saliente	Confirma la dirección del dispositivo exportador.
`cancelAddDevice`	Saliente	Cancela la operación.
`addDeviceStateChanged`	Entrantes	Indica el nuevo estado y proporciona detalles.

Máquina de estado daemon 

        stateDiagram-v2
    state "Import Side" as Import {
        [*] --> Import_Init
        Import_Init --> Import_TokenAvailable: Generate token
        Import_TokenAvailable --> Import_Connecting: Peer detected
        Import_Connecting --> Import_Authenticating: Connection established
        Import_Authenticating --> Import_InProgress: Auth success
        Import_InProgress --> Import_Done: Transfer complete
        note right of Import_TokenAvailable
            Provides:
            - Authentication code
            - QR data
        end note
        note right of Import_Authenticating
            May require password
            auth_scheme: "", "none", "password"
        end note
        note right of Import_Done
            error: "", "none", "network", "authentication"
        end note
    }
    state "Export Side" as Export {
        [*] --> Export_Init
        Export_Init --> Export_Connecting: Token validated
        Export_Connecting --> Export_Authenticating: Connection established
        Export_Authenticating --> Export_InProgress: Auth success
        Export_InProgress --> Export_Done: Transfer complete
        note right of Export_Init
            Accepts:
            - Authentication code
            - QR data
        end note
        note right of Export_Authenticating
            Confirms peer address
        end note
    }

Máquina de estado del cliente 

        stateDiagram-v2
    [*] --> Initial
    Initial --> ImportDevice: ImportFromDevice selected
    Initial --> ExportDevice: ExportToDevice selected
    state "Import Device" as ImportDevice {
        [*] --> Import_Init
        Import_Init --> Import_TokenAvailable: Token received
        Import_TokenAvailable --> Import_Connecting: Peer detected
        Import_Connecting --> Import_Authenticating: Connection established
        Import_Authenticating --> Import_InProgress: Auth success
        Import_InProgress --> Import_Done: Transfer complete
        Import_Authenticating --> Import_Error: Bad password
        Import_Connecting --> Import_Error: Connection failed
        Import_InProgress --> Import_Error: Transfer failed
        Import_Error --> [*]: Reset
        Import_Done --> [*]: Account ready
        note right of Import_TokenAvailable
            Display:
            - QR code
            - Authentication code
            - Copy button
        end note
        note right of Import_Authenticating
            Show password input if needed
        end note
    }
    state "Export Device" as ExportDevice {
        [*] --> Export_Init
        state Export_Init {
            [*] --> ShowInputOptions
            ShowInputOptions --> ScanQR: Camera selected
            ShowInputOptions --> ManualEntry: Manual selected
            ScanQR --> QRScanning: Start camera
            QRScanning --> TokenObtained: QR detected
            QRScanning --> ShowInputOptions: Cancel scan
            ManualEntry --> TokenObtained: Valid code entered
            ManualEntry --> ShowInputOptions: Cancel entry
        }
        Export_Init --> Export_Connecting: Token validated
        Export_Connecting --> Export_Authenticating: Connection established
        Export_Authenticating --> Export_InProgress: Auth provided
        Export_InProgress --> Export_Done: Transfer complete
        Export_Connecting --> Export_Error: Invalid token
        Export_Authenticating --> Export_Error: Auth failed
        Export_InProgress --> Export_Error: Transfer failed
        Export_Error --> [*]: Reset
        Export_Done --> [*]: Device added
        note right of Export_Init
            Input options:
            - QR scanner
            - Manual code entry
        end note
        note right of Export_Authenticating
            Confirm peer device
        end note
    }
    ImportDevice --> Initial: Back/Cancel
    ExportDevice --> Initial: Back/Cancel

Diagrama de secuencia completo (importación y exportación)

        sequenceDiagram
    box white Import Side
    participant IC as New Client
    participant ID as New Daemon
    end
    box white Export Side
    participant ED as Old Daemon
    participant EC as Old Client
    end
    %% Initial Setup
    IC->>ID: addAccount(archiveURL="jami-auth")
    activate ID
    ID-->>IC: deviceAuthStateChanged(state=TOKEN_AVAILABLE)
    Note over IC: Display QR code<br/>and auth token
    %% Export Side Initiation
    EC->>EC: User chooses to export
    EC->>EC: Scan QR/Enter token
    EC->>ED: addDevice(token)
    activate ED
    %% Connection Establishment
    ED->>ID: DHT connection request
    ID-->>IC: deviceAuthStateChanged(state=CONNECTING)
    ED-->>EC: addDeviceStateChanged(state=CONNECTING)
    %% Authentication Phase
    ID-->>IC: deviceAuthStateChanged(state=AUTHENTICATING,<br/>peer_id, auth_scheme)
    ED-->>EC: addDeviceStateChanged(state=AUTHENTICATING,<br/>peer_address)
    alt Account is password protected
        IC->>IC: Show password prompt
        IC->>ID: provideAccountAuthentication(password)
    end
    EC->>ED: confirmAddDevice()
    %% Transfer Phase
    ID-->>IC: deviceAuthStateChanged(state=IN_PROGRESS)
    ED-->>EC: addDeviceStateChanged(state=IN_PROGRESS)
    ED->>ID: Transfer account archive
    %% Completion
    ID-->>IC: deviceAuthStateChanged(state=DONE, error="")
    ED-->>EC: addDeviceStateChanged(state=DONE, error="")
    deactivate ID
    deactivate ED
    Note over IC,EC: Account successfully linked
    alt Error Scenarios
        ID-->>IC: deviceAuthStateChanged(state=DONE, error="network")
        ED-->>EC: addDeviceStateChanged(state=DONE, error="network")
        Note over IC,EC: Network error during transfer
        ID-->>IC: deviceAuthStateChanged(state=DONE, error="authentication")
        ED-->>EC: addDeviceStateChanged(state=DONE, error="authentication")
        Note over IC,EC: Authentication failed
    end
    %% Cancellation Scenarios
    rect rgb(240, 240, 240)
        Note over IC,EC: Optional Cancellation Flows
        IC->>ID: removeAccount()
        EC->>ED: cancelAddDevice()
    end