Add persistent PIN pairing system

anbeckham · anbeckham · commit 2119a64e2cfa · 2025-12-25T11:39:52.000-06:00
- Generate persistent PIN at server startup (valid for server lifetime)
- Display PIN on desktop Status tab alongside URL with copy/refresh buttons
- Add /api/pair/verify-direct endpoint for session-less PIN verification
- Remove redundant "Enter Server URL" button from web landing page
- Update web PIN entry to use direct verification flow

Fixes pairing UX issues when navigating directly to server URL.
diff --git a/crates/linglide-auth/src/lib.rs b/crates/linglide-auth/src/lib.rs
@@ -39,7 +39,8 @@ pub mod storage;
 
 pub use device::{Device, DeviceId, DeviceInfo, DeviceType};
 pub use pairing::{
-    hash_token, PairingError, PairingManager, PairingResult, PairingStartResponse,
-    PairingVerifyRequest, PairingVerifyResponse, QrCodeData, PIN_VALIDITY_SECONDS,
+    hash_token, DirectVerifyRequest, PairingError, PairingManager, PairingResult,
+    PairingStartResponse, PairingVerifyRequest, PairingVerifyResponse, PersistentPinResponse,
+    QrCodeData, PIN_VALIDITY_SECONDS,
 };
 pub use storage::{DeviceStorage, StorageError, StorageResult};
diff --git a/crates/linglide-auth/src/pairing.rs b/crates/linglide-auth/src/pairing.rs
@@ -105,6 +105,25 @@ pub struct PairingVerifyResponse {
     pub token: String,
 }
 
+/// Request to verify PIN directly (without session)
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct DirectVerifyRequest {
+    /// The PIN entered by user
+    pub pin: String,
+    /// Device name provided by client
+    pub device_name: String,
+    /// Device type hint
+    #[serde(default)]
+    pub device_type: Option<String>,
+}
+
+/// Response containing the persistent PIN
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct PersistentPinResponse {
+    /// The 6-digit PIN
+    pub pin: String,
+}
+
 /// QR code data structure
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct QrCodeData {
@@ -132,6 +151,8 @@ pub struct PairingManager {
     server_url: String,
     /// Certificate fingerprint for QR codes
     cert_fingerprint: Option<String>,
+    /// Persistent PIN for direct entry (valid for server lifetime)
+    persistent_pin: Arc<RwLock<String>>,
 }
 
 impl PairingManager {
@@ -142,6 +163,7 @@ impl PairingManager {
             storage,
             server_url,
             cert_fingerprint: None,
+            persistent_pin: Arc::new(RwLock::new(generate_pin())),
         }
     }
 
@@ -156,6 +178,7 @@ impl PairingManager {
             storage,
             server_url,
             cert_fingerprint: fingerprint,
+            persistent_pin: Arc::new(RwLock::new(generate_pin())),
         }
     }
 
@@ -164,6 +187,57 @@ impl PairingManager {
         self.cert_fingerprint = fingerprint;
     }
 
+    /// Get the persistent PIN (valid for entire server lifetime)
+    pub async fn get_persistent_pin(&self) -> String {
+        self.persistent_pin.read().await.clone()
+    }
+
+    /// Regenerate the persistent PIN
+    pub async fn refresh_persistent_pin(&self) -> String {
+        let mut pin = self.persistent_pin.write().await;
+        *pin = generate_pin();
+        info!("Persistent PIN refreshed");
+        pin.clone()
+    }
+
+    /// Verify PIN directly without requiring a session
+    /// This is for direct PIN entry when user navigates to the URL
+    pub async fn verify_persistent_pin(
+        &self,
+        request: DirectVerifyRequest,
+    ) -> PairingResult<PairingVerifyResponse> {
+        let persistent = self.persistent_pin.read().await;
+
+        if *persistent != request.pin {
+            warn!("Invalid persistent PIN attempt");
+            return Err(PairingError::InvalidPin);
+        }
+
+        // Generate auth token
+        let token = generate_token();
+        let token_hash = hash_token(&token);
+
+        // Create device
+        let device_type = request
+            .device_type
+            .as_deref()
+            .and_then(|s| s.parse().ok())
+            .unwrap_or(DeviceType::Unknown);
+
+        let device = Device::new(request.device_name, device_type, token_hash);
+        let device_id = device.id.to_string();
+
+        // Save device
+        self.storage.save_device(device).await?;
+
+        info!(
+            "Device {} paired successfully via persistent PIN",
+            device_id
+        );
+
+        Ok(PairingVerifyResponse { device_id, token })
+    }
+
     /// Start a new pairing session
     pub async fn start_pairing(&self) -> PairingStartResponse {
         let session = PairingSession::new();
@@ -295,6 +369,13 @@ impl PairingManager {
     }
 }
 
+/// Generate a 6-digit PIN
+fn generate_pin() -> String {
+    let mut rng = rand::thread_rng();
+    let pin: u32 = rng.gen_range(0..1_000_000);
+    format!("{:06}", pin)
+}
+
 /// Generate a secure random token
 fn generate_token() -> String {
     let mut rng = rand::thread_rng();
diff --git a/crates/linglide-desktop/src/app.rs b/crates/linglide-desktop/src/app.rs
@@ -74,11 +74,13 @@ impl LinGlideApp {
                 url,
                 fingerprint,
                 paired_devices,
+                pin,
             } => {
                 info!("Server started: {}", url);
                 self.server_status.running = true;
                 self.server_url = Some(url.clone());
                 self.server_status.url = Some(url);
+                self.server_status.pin = Some(pin);
                 self.cert_fingerprint = Some(fingerprint);
                 self.paired_devices = paired_devices.clone();
                 self.server_status.paired_device_count = paired_devices.len();
@@ -89,10 +91,15 @@ impl LinGlideApp {
                     let _ = self.bridge.command_tx.try_send(UiCommand::StartPairing);
                 }
             }
+            UiEvent::PinRefreshed { pin } => {
+                info!("PIN refreshed");
+                self.server_status.pin = Some(pin);
+            }
             UiEvent::ServerStopped => {
                 info!("Server stopped");
                 self.server_status.running = false;
                 self.server_status.url = None;
+                self.server_status.pin = None;
                 self.server_status.connected_devices.clear();
                 self.pairing_state = PairingState::default();
             }
diff --git a/crates/linglide-desktop/src/bridge.rs b/crates/linglide-desktop/src/bridge.rs
@@ -16,9 +16,12 @@ pub enum UiEvent {
         url: String,
         fingerprint: String,
         paired_devices: Vec<Device>,
+        pin: String,
     },
     /// Server stopped
     ServerStopped,
+    /// Persistent PIN was refreshed
+    PinRefreshed { pin: String },
     /// Server failed to start
     ServerError { message: String },
     /// New device connected
@@ -62,6 +65,8 @@ pub enum UiCommand {
     SetMdns { enabled: bool },
     /// Enable/disable USB/ADB forwarding
     SetUsb { enabled: bool },
+    /// Refresh the persistent PIN
+    RefreshPin,
     /// Shutdown the application
     Shutdown,
 }
@@ -71,6 +76,7 @@ pub enum UiCommand {
 pub struct ServerStatus {
     pub running: bool,
     pub url: Option<String>,
+    pub pin: Option<String>,
     pub connected_devices: Vec<Device>,
     pub paired_device_count: usize,
     pub mdns_active: bool,
diff --git a/crates/linglide-desktop/src/controller.rs b/crates/linglide-desktop/src/controller.rs
@@ -111,6 +111,9 @@ impl ServerController {
                 UiCommand::SetUsb { enabled: _ } => {
                     // Would need to restart server to change USB
                 }
+                UiCommand::RefreshPin => {
+                    self.refresh_pin().await;
+                }
                 UiCommand::Shutdown => {
                     info!("Shutdown requested");
                     self.stop_server().await;
@@ -192,6 +195,7 @@ impl ServerController {
         let ds_clone = device_storage.clone();
         let fp_clone = fingerprint.clone();
         let devices_clone = paired_devices.clone();
+        let persistent_pin = pairing_manager.get_persistent_pin().await;
         tokio::spawn(async move {
             if let Err(e) = run_server(
                 config,
@@ -204,6 +208,7 @@ impl ServerController {
                 fp_clone,
                 local_ip,
                 devices_clone,
+                persistent_pin,
             )
             .await
             {
@@ -248,6 +253,19 @@ impl ServerController {
             }
         }
     }
+
+    async fn refresh_pin(&mut self) {
+        if let Some(ref ctx) = self.context {
+            let ctx = ctx.read().await;
+            let new_pin = ctx.pairing_manager.refresh_persistent_pin().await;
+            let _ = self
+                .bridge
+                .event_tx
+                .send(UiEvent::PinRefreshed { pin: new_pin });
+        } else {
+            warn!("Cannot refresh PIN: server not running");
+        }
+    }
 }
 
 /// Get the local IP address
@@ -272,6 +290,7 @@ async fn run_server(
     fingerprint: String,
     local_ip: String,
     paired_devices: Vec<linglide_auth::device::Device>,
+    persistent_pin: String,
 ) -> Result<()> {
     let core_config = Config::new()
         .with_width(config.width)
@@ -335,6 +354,7 @@ async fn run_server(
         url: server_url.clone(),
         fingerprint: fingerprint.clone(),
         paired_devices,
+        pin: persistent_pin,
     });
 
     // Start mDNS if enabled
diff --git a/crates/linglide-desktop/src/windows/mod.rs b/crates/linglide-desktop/src/windows/mod.rs
@@ -292,6 +292,38 @@ impl MainWindow {
                         });
                     }
 
+                    if let Some(pin) = &status.pin {
+                        ui.add_space(8.0);
+                        ui.horizontal(|ui| {
+                            ui.label(
+                                RichText::new("PIN:")
+                                    .font(typography::body())
+                                    .color(colors::TEXT_SECONDARY),
+                            );
+                            ui.add_space(4.0);
+                            ui.label(
+                                RichText::new(pin)
+                                    .strong()
+                                    .color(colors::SUCCESS)
+                                    .monospace(),
+                            );
+                            if ui
+                                .small_button("\u{1F4CB}")
+                                .on_hover_text("Copy PIN")
+                                .clicked()
+                            {
+                                ui.output_mut(|o| o.copied_text = pin.clone());
+                            }
+                            if ui
+                                .small_button("\u{1F504}")
+                                .on_hover_text("Generate new PIN")
+                                .clicked()
+                            {
+                                let _ = command_tx.try_send(UiCommand::RefreshPin);
+                            }
+                        });
+                    }
+
                     ui.add_space(4.0);
                     ui.horizontal(|ui| {
                         ui.label(
diff --git a/crates/linglide-server/src/http.rs b/crates/linglide-server/src/http.rs
@@ -11,7 +11,8 @@ use axum::{
 };
 use image::ImageFormat;
 use linglide_auth::{
-    DeviceInfo, PairingStartResponse, PairingVerifyRequest, PairingVerifyResponse,
+    DeviceInfo, DirectVerifyRequest, PairingStartResponse, PairingVerifyRequest,
+    PairingVerifyResponse, PersistentPinResponse,
 };
 use linglide_discovery::DiscoveryInfo;
 use linglide_web::Assets;
@@ -37,6 +38,9 @@ pub fn create_router(state: Arc<AppState>) -> Router {
         // Pairing API
         .route("/api/pair/start", post(pair_start_handler))
         .route("/api/pair/verify", post(pair_verify_handler))
+        .route("/api/pair/verify-direct", post(pair_verify_direct_handler))
+        .route("/api/pair/pin", get(pair_pin_handler))
+        .route("/api/pair/pin/refresh", post(pair_pin_refresh_handler))
         .route("/api/pair/qr", get(pair_qr_handler))
         .route("/api/pair/status", get(pair_status_handler))
         // Device management API
@@ -119,6 +123,38 @@ async fn pair_verify_handler(
         .map_err(|e| (StatusCode::UNAUTHORIZED, e.to_string()))
 }
 
+/// Verify PIN directly without requiring a session
+///
+/// This is for direct PIN entry when users navigate to the server URL.
+/// Uses the persistent PIN that is valid for the server's lifetime.
+async fn pair_verify_direct_handler(
+    State(state): State<Arc<AppState>>,
+    Json(request): Json<DirectVerifyRequest>,
+) -> Result<Json<PairingVerifyResponse>, (StatusCode, String)> {
+    state
+        .pairing_manager
+        .verify_persistent_pin(request)
+        .await
+        .map(Json)
+        .map_err(|e| (StatusCode::UNAUTHORIZED, e.to_string()))
+}
+
+/// Get the persistent PIN
+///
+/// Returns the PIN that is valid for the server's lifetime.
+async fn pair_pin_handler(State(state): State<Arc<AppState>>) -> Json<PersistentPinResponse> {
+    let pin = state.pairing_manager.get_persistent_pin().await;
+    Json(PersistentPinResponse { pin })
+}
+
+/// Refresh (regenerate) the persistent PIN
+async fn pair_pin_refresh_handler(
+    State(state): State<Arc<AppState>>,
+) -> Json<PersistentPinResponse> {
+    let pin = state.pairing_manager.refresh_persistent_pin().await;
+    Json(PersistentPinResponse { pin })
+}
+
 /// Query parameters for QR code generation
 #[derive(Debug, Deserialize)]
 pub struct QrQuery {
diff --git a/crates/linglide-web/www/js/api.js b/crates/linglide-web/www/js/api.js
@@ -100,6 +100,25 @@ export class ApiClient {
         });
     }
 
+    /**
+     * Verify PIN directly without session (for persistent PIN)
+     * This is used when users navigate directly to the server URL and enter the PIN.
+     * @param {string} pin
+     * @param {string} deviceName
+     * @param {string} [deviceType]
+     * @returns {Promise<PairingVerifyResponse>}
+     */
+    async verifyPinDirect(pin, deviceName, deviceType = 'browser') {
+        return this.request('/api/pair/verify-direct', {
+            method: 'POST',
+            body: JSON.stringify({
+                pin,
+                device_name: deviceName,
+                device_type: deviceType
+            })
+        });
+    }
+
     /**
      * Get pairing session status
      * @param {string} sessionId
diff --git a/crates/linglide-web/www/js/app.js b/crates/linglide-web/www/js/app.js
diff --git a/crates/linglide-web/www/js/pairing/pairing-controller.js b/crates/linglide-web/www/js/pairing/pairing-controller.js
