From 723b14e660737887c454b8e8300ac38bb390841f Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Tue, 17 Mar 2026 12:04:53 +0000
Subject: [PATCH] docs: update QR code login documentation with scanner and TTL
 details

Co-authored-by: christianlouis <361235+christianlouis@users.noreply.github.com>
---
 docs/AuthenticationSetup.md | 11 +++++++----
 docs/MobileApp.md           | 19 +++++++++++++++++--
 2 files changed, 24 insertions(+), 6 deletions(-)

diff --git a/docs/AuthenticationSetup.md b/docs/AuthenticationSetup.md
index 2c9e15a9..c77f48b3 100644
--- a/docs/AuthenticationSetup.md
+++ b/docs/AuthenticationSetup.md
@@ -190,20 +190,23 @@ QR code login allows users to authenticate a mobile device by scanning a QR code
 ### How It Works
 
 1. The authenticated web user opens the **QR Login** page and a challenge QR code is displayed.
-2. The mobile app scans the QR code and calls the claim endpoint.
-3. An API token is issued for the mobile device and the web UI is notified via polling.
+2. The user opens the DocuElevate mobile app and taps **Scan QR Code to Login**, which opens the device camera.
+3. The mobile app scans the QR code. The QR code contains both the challenge token and the server URL (`docuelevate://qr-login?token=...&server=...`), so there is no need to enter the server URL manually.
+4. An API token is issued for the mobile device and the web UI is notified via polling.
+
+> **Note:** The countdown timer on the web page uses server-relative time (TTL in seconds) rather than absolute timestamps, so it works correctly even when the client's clock is not in sync with the server.
 
 ### Configuration
 
 | Variable | Description | Default |
 |----------|-------------|---------|
-| `QR_LOGIN_CHALLENGE_TTL_SECONDS` | How long a QR challenge is valid | `120` |
+| `QR_LOGIN_CHALLENGE_TTL_SECONDS` | How long a QR challenge is valid (seconds) | `120` |
 
 ### API Endpoints
 
 | Method | Path | Description |
 |--------|------|-------------|
-| `POST` | `/api/qr-auth/challenge` | Create a new QR login challenge |
+| `POST` | `/api/qr-auth/challenge` | Create a new QR login challenge (returns `ttl_seconds` for client countdown) |
 | `GET` | `/api/qr-auth/challenge/{id}/status` | Poll the status of a challenge |
 | `POST` | `/api/qr-auth/claim` | Claim a challenge from a mobile device |
 
diff --git a/docs/MobileApp.md b/docs/MobileApp.md
index 77df917f..8b8e6f79 100644
--- a/docs/MobileApp.md
+++ b/docs/MobileApp.md
@@ -8,6 +8,7 @@ DocuElevate includes a native mobile application for iOS and Android built with
 |---------|-----|---------|
 | SSO login (OAuth2) | ✅ | ✅ |
 | Local / basic auth login | ✅ | ✅ |
+| QR code login (scan from web) | ✅ | ✅ |
 | Auto-generated API token | ✅ | ✅ |
 | Camera capture → upload | ✅ | ✅ |
 | File picker upload | ✅ | ✅ |
@@ -112,6 +113,18 @@ When developing with **Expo Go** the app does not have the `docuelevate://` cust
 
 No extra configuration is needed — just run `npx expo start` and scan the QR code with the **Expo Go** app.
 
+### QR Code Login Flow
+
+As an alternative to SSO, users can log in by scanning a QR code displayed in the web UI:
+
+1. The authenticated web user navigates to **Profile → Security & Sessions → Log in on mobile via QR code**.
+2. A QR code is displayed containing a deep link: `docuelevate://qr-login?token=<challenge_token>&server=<server_url>`.
+3. In the mobile app, the user taps **Scan QR Code to Login**, which opens the device camera.
+4. The app scans the QR code, extracts both the server URL and the challenge token, and calls `POST /api/qr-auth/claim`.
+5. An API token is issued and stored securely — no need to enter the server URL manually.
+
+> **Note:** The QR code already contains the server URL, so users do not need to type it in when using QR login.
+
 ### Auto-generated Mobile Token
 
 When the mobile app completes login it automatically creates a named API token (`"Mobile App – <device name>"`) via `POST /api/mobile/generate-token`.  This token:
@@ -286,7 +299,8 @@ mobile/
 │   ├── (auth)/                  # Unauthenticated route group
 │   │   ├── _layout.tsx          # Stack navigator (headerless)
 │   │   ├── index.tsx            # Welcome screen
-│   │   └── login.tsx            # Login screen
+│   │   ├── login.tsx            # Login screen
+│   │   └── qr-scanner.tsx       # QR code scanner screen
 │   └── (tabs)/                  # Authenticated route group
 │       ├── _layout.tsx          # Tab navigator
 │       ├── index.tsx            # Upload screen (default tab)
@@ -303,7 +317,8 @@ mobile/
     ├── hooks/
     │   └── usePushNotifications.ts  # Push token registration
     ├── screens/
-    │   ├── LoginScreen.tsx      # Server URL + SSO button
+    │   ├── LoginScreen.tsx      # Server URL + SSO button + QR code scanner
+    │   ├── QRScannerScreen.tsx  # Camera-based QR code scanner for login
     │   ├── UploadScreen.tsx     # Camera capture + photo library + file picker
     │   ├── FilesScreen.tsx      # Processed document list
     │   └── ProfileScreen.tsx    # User profile + sign out