# Onairos Account Linking Flow

## Overview

This document describes the process for linking a user's account with Onairos, either through the Onairos app (preferred) or through the embedded Universal Onboarding flow.

```mermaid
flowchart TD
    A[User clicks Onairos button] --> B{FaceID check}
    B -->|Success and credentials exist| C[Show Onairos overlay]
    B -->|Success but no credentials| D{Can launch Onairos app?}
    
    D -->|Yes| E[Launch Onairos app via deep link]
    E --> F[Receive callback with credentials]
    F --> G[Store credentials securely]
    
    D -->|No| H[Generate IDFV hash]
    H --> I[Show Universal Onboarding]
    I --> J{User connects valuable platform or any platform}
    J -->|Yes| K[Prompt for PIN creation]
    K --> L[FaceID verification]
    L --> M[Store credentials in secure enclave]
    M --> N[Load profile - Show loading screen]
    N --> O[Optional: Email registration]
    O --> P[Close overlay and return API data]
```

## Detailed Steps

1. **Initial Authentication Check**
   - When the user clicks the Onairos button, the app performs a FaceID check
   - If credentials are stored and valid, show the normal Onairos overlay
   - If no credentials exist, proceed to account linking

2. **Preferred Method: Onairos App Authentication**
   - The system attempts to launch the Onairos app via deep link
   - In the Onairos app, the user can select which data to share
   - Upon approval, the Onairos app returns to the host app via deep link callback
   - Credentials are stored securely using biometric protection

3. **Fallback Method: In-App Onboarding**
   - If the Onairos app cannot be launched, generate a unique hash from the device IDFV
   - Present the Universal Onboarding screen
   - Guide the user to connect:
     - The valuable platform (if specified) or
     - At least one data platform of their choice
   - After connecting platform(s), prompt for PIN creation
   - Verify with FaceID
   - Store the credentials in the secure enclave
   - Show loading screen while profile is created
   - **Optional Email Registration**: During loading, user can create an Onairos account by entering their email
   - When complete, close the overlay and return API data to the host app

## Security Considerations

- Credentials are always stored in the secure enclave
- All authentication requires biometric verification (FaceID/TouchID)
- PINs must meet strong security requirements
- Communication with Onairos servers is encrypted
- Email registration is secure and validated

## OAuth Implementation

### Simplified OAuth Authorization

The OAuth implementation has been streamlined using a unified API endpoint approach:

```mermaid
sequenceDiagram
    participant App as App
    participant OAuth as OAuth WebView
    participant API as Onairos API
    participant Platform as Social Platform
    
    App->>API: Request OAuth data (platform, appId, redirect)
    API-->>App: Return accountName
    App->>OAuth: Show WebView with api2.onairos.uk/{account}/authorize
    OAuth->>Platform: Redirect to platform login
    Platform-->>OAuth: Return with auth code
    OAuth->>API: Send auth code
    API-->>OAuth: Confirm connection
    OAuth-->>App: Return success
```

### Key Features

1. **Unified Endpoint**: All platforms use the same API endpoint format: `api2.onairos.uk/{account}/authorize`
2. **Sleek WebView**: A minimalist WebView with loading indicator and security messaging
3. **Consistent Callbacks**: All platforms use `onairos://` as the callback URL pattern
4. **Error Handling**: Improved error handling and user feedback

### WebView Design

The OAuth WebView follows these design principles:
- Clean white background without distractions
- Subtle top loading indicator
- Simple header with platform name
- Security message at the bottom
- Easy navigation controls

### Supported Platforms

- **YouTube**: OAuth through YouTube API
- **Instagram**: OAuth through Instagram Graph API
- **Pinterest**: OAuth through Pinterest API
- **Reddit**: OAuth through Reddit API

## Technical Implementation

- The PIN is stored securely using: `_channel.invokeMethod('storeCredentials', {'username': hashedId, 'userPin': userPin})`
- API data is obtained from the Onairos backend and passed to the host application
- Deep linking is handled through the system URL scheme
- Email registration uses `api2.onairos.uk/mobile/account-created` endpoint
