Add mobile login feature to architecture docs (#1347)

ARCHITECTURE.md

@@ -10,8 +10,6 @@ The basic premise is that the master password chosen by the user upon registrati
 - **Vault Data**: Your entire vault (passwords, usernames, notes, passkeys, email addresses, etc.) is fully encrypted client-side before being sent to the server. The server cannot decrypt any vault contents.
 - **Email Contents**: When emails are received by the server, their contents are immediately encrypted with your public key (from your vault) before being saved. Only you can decrypt and read these emails with your private key.
 
-*Note: email aliases are stored on the server as "claims" which are linked to internal user IDs for routing purposes.*
-
 This ensures that even if the AliasVault servers are compromised, vault contents and email messages remain secure and unreadable.
 
 ## Encryption algorithms
@@ -25,6 +23,7 @@ The following encryption algorithms and standards are used by AliasVault:
 ### Additional Features
 - [RSA-OAEP](#rsa-oaep) - Email encryption
 - [Passkeys (WebAuthn)](#passkeys-webauthn) - Passwordless authentication
+- [Login with Mobile](#login-with-mobile) - Unlock vault in web app / browser extension via mobile app
 
 Below is a detailed explanation of each encryption algorithm and standard.
 
@@ -138,3 +137,31 @@ All implementations follow the WebAuthn Level 2 specification and use:
 - Eliminates phishing risks through cryptographic domain binding
 
 More information about WebAuthn can be found on the [WebAuthn specification](https://www.w3.org/TR/webauthn-2/) page.
+
+### Login with Mobile
+AliasVault provides a secure "Login with Mobile" feature that allows users to unlock their vault on web browsers or browser extensions by scanning a QR code with their authenticated mobile app. This convenient authentication method maintains zero-knowledge security through hybrid encryption.
+
+#### Implementation Details
+The mobile login system combines RSA-2048 asymmetric encryption with AES-256-GCM symmetric encryption:
+
+1. **Initiation**: Browser/extension client generates an RSA-2048 key pair locally and sends the public key to the server, which returns a unique request ID displayed as a QR code.
+
+2. **Authorization**: Mobile app scans the QR code, encrypts the user's vault decryption key with the RSA public key, and sends it to the server.
+
+3. **Retrieval**: Browser client polls the server for completion. When ready, the server:
+   - Generates fresh JWT tokens for the session
+   - Creates a random AES-256 symmetric key
+   - Encrypts tokens and username with the symmetric key
+   - Encrypts the symmetric key with the client's RSA public key
+   - Returns encrypted data and immediately purges it from the database
+
+4. **Decryption**: Client uses its RSA private key to decrypt the symmetric key, then uses the symmetric key to decrypt tokens and username, and the RSA private key to decrypt the vault decryption key.
+
+#### Security Properties
+- **Zero-Knowledge**: Server never accesses the vault decryption key in plaintext
+- **One-Time Use**: Requests cannot be retrieved twice; data is immediately cleared after retrieval
+- **Automatic Expiration**: Unfulfilled requests expire after 2 minutes client-side (3 minutes server-side); fulfilled but unretrieved requests auto-delete within 24 hours
+- **MITM Protection**: Only the client with the RSA private key can decrypt the response
+- **Limited Attack Surface**: Short timeout window minimizes QR code interception risks
+
+More information about the mobile login flow can be found in the [Architecture Documentation](https://docs.aliasvault.net/architecture/#6-login-with-mobile).

docs/architecture/index.md

@@ -6,6 +6,18 @@ nav_order: 5
 ---
 
 # Architecture
+{: .no_toc }
+
+<details open markdown="block">
+  <summary>
+    Table of contents
+  </summary>
+  {: .text-delta }
+- TOC
+{:toc}
+</details>
+
+---
 
 AliasVault implements zero-knowledge encryption where sensitive user data never leaves the client device in unencrypted form. Below is a detailed explanation of how the system secures user data and communications.
 
@@ -13,8 +25,6 @@ AliasVault implements zero-knowledge encryption where sensitive user data never
 - **Vault Data** (usernames, passwords, notes, passkeys etc.) is fully encrypted client-side before being sent to the server. The server cannot decrypt any vault contents.
 - **Email Contents**: When emails are received by the server, their contents are immediately encrypted with your public key before being saved. Only you can decrypt and read them with your private key.
 
-*Note: email aliases are stored on the server as "claims" which are linked to internal user IDs for routing purposes.*
-
 ## Diagram
 The security architecture diagram below illustrates all encryption and authentication processes used in AliasVault to secure user data and communications.
 
@@ -76,7 +86,7 @@ You can also view the diagram in a browser-friendly HTML format: [AliasVault Sec
 
 > Note: The use of a symmetric key for email content encryption and asymmetric encryption for the symmetric key (hybrid encryption) is implemented due to RSA's limitations on encryption string length and for better performance.
 
-### 5. Passkey Authentication System
+### 5. Passkey Authentication
 
 AliasVault includes a virtual passkey authenticator that implements the WebAuthn Level 2 specification, allowing users to securely store and use passkeys for passwordless authentication across websites and services.
 
@@ -134,18 +144,55 @@ AliasVault includes a virtual passkey authenticator that implements the WebAuthn
     - PRF is supported via browser extension and iOS (0.24.0+)
         - Android support is pending due to limited Android API support
 
-## Security Benefits
-- Zero-knowledge encryption: entire vault is encrypted client-side before transmission
-- Email contents are encrypted with your public key immediately upon receipt by the server
-- Master password never leaves the client device
-- All sensitive operations (key derivation, encryption/decryption) happen locally
-- Server stores only encrypted vault data and encrypted email contents
-- Multi-layer hybrid encryption for emails provides secure communication
-- Optional 2FA adds an additional security layer
-- Use of established cryptographic standards (Argon2id, AES-256-GCM, RSA/OAEP)
-- Passkey private keys remain encrypted in vault at all times
-- Cross-platform passkey sync without compromising security
-- WebAuthn compliance eliminates phishing risks through domain binding
-- No personally identifiable information required for registration
+### 6. Login with Mobile
 
-This security architecture ensures that even if the server is compromised, vault contents and email messages remain secure and unreadable as all sensitive operations and keys remain strictly on the client side. Email aliases (stored on the server as "claims" for routing) are linked to internal user IDs, not real-world identities.
+AliasVault includes a secure "Login with Mobile" feature that allows users to unlock their vault on web browsers or browser extensions by scanning a QR code with their mobile app. This system provides a convenient authentication method while maintaining zero-knowledge security through end-to-end encryption.
+
+#### Security Architecture
+
+The mobile login system uses a hybrid encryption approach combining RSA asymmetric encryption and AES-256-GCM symmetric encryption to ensure that:
+- The server never has access to the user's decryption key in plaintext
+- Only the authorized client that initiated the request can decrypt the transmitted data
+- No sensitive data persists on the server after retrieval
+
+#### Authentication Flow
+
+1. **Initiation (Browser/Extension Client)**
+   - Client generates an RSA-2048 key pair locally
+   - Public key is sent to the server
+   - Server creates a unique request ID and stores the public key
+   - Client generates a QR code containing the request ID
+   - Private key is kept only in memory (never persisted to disk)
+
+2. **QR Code Scanning (Mobile App)**
+   - User scans the QR code with their authenticated mobile app
+   - Mobile app retrieves the public key from server
+   - Mobile app encrypts the user's vault decryption key using the RSA public key
+   - Encrypted decryption key is sent to server
+   - Server stores the encrypted decryption key and marks the request as fulfilled
+
+3. **Polling and Retrieval (Browser/Extension Client)**
+   - Client polls the server every few seconds
+   - Polling continues for up to 2 minutes (3-minute server-side timeout for buffer)
+   - When fulfilled, server:
+     - Generates a fresh JWT access token and refresh token for the user
+     - Creates a random 256-bit AES symmetric key
+     - Encrypts the JWT tokens and username using this symmetric key
+     - Encrypts the symmetric key itself using the client's RSA public key
+     - Returns all encrypted data in the response
+     - Immediately marks the request as retrieved and clears sensitive data from database
+
+4. **Decryption (Browser/Extension Client)**
+   - Client uses its RSA private key to decrypt the symmetric key
+   - Client uses the symmetric key to decrypt the JWT tokens and username
+   - Client uses the RSA private key to decrypt the vault decryption key
+   - Client can now unlock the vault using the decryption key and stores it in memory
+   - RSA private key is immediately purged from memory
+
+#### Security Properties
+
+- **Zero-Knowledge**: The server never has access to the vault decryption key in plaintext. It only temporarily stores the RSA-encrypted version.
+- **One-Time Use**: Once a mobile login request is retrieved by the client, it cannot be accessed again. The encrypted data is immediately cleared from the database.
+- **Automatic Expiration**: Fulfilled but unretrieved requests are automatically deleted by the server within 24 hours to prevent stale data accumulation.
+- **Man-in-the-Middle Protection**: The encryption scheme ensures that any eavesdroppers cannot intercept the decryption key. Only the local client that started the mobile login request has the private key for decryption.
+- **Short-Lived Requests**: The 3-minute timeout window limits the attack surface for QR code interception.