feat(pair): initial release of Hermes Pair with Windows GUI and Linux terminal QR onboarding

2026-08-24 10:45:58 +07:00 · 2026-08-24 10:45:58 +07:00 · 2929a35261
commit 2929a35261
16 changed files with 1942 additions and 0 deletions
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@ -0,0 +1,76 @@
 name: Build and Test
 on:
  push:
    branches: [ "main", "master" ]
  pull_request:
    branches: [ "main", "master" ]
 env:
  CARGO_TERM_COLOR: always
 jobs:
  check-and-test:
    name: Test & Build (${{ matrix.os }})
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false
      matrix:
        include:
          - os: windows-latest
            artifact_name: HermesPair-windows-x64.exe
            binary_path: target/release/hermes-pair.exe
            upload_name: HermesPair-windows-x64
          - os: ubuntu-latest
            artifact_name: hermes-pair-linux-x64
            binary_path: target/release/hermes-pair
            upload_name: hermes-pair-linux-x64
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
      - name: Set up Rust toolchain
        uses: dtolnay/rust-toolchain@stable
        with:
          components: clippy, rustfmt
      - name: Install Linux GUI Dependencies
        if: matrix.os == 'ubuntu-latest'
        run: |
          sudo apt-get update
          sudo apt-get install -y libxcb-render0-dev libxcb-shape0-dev libxcb-xfixes0-dev libxkbcommon-dev libssl-dev libgtk-3-dev
      - name: Rust Cache
        uses: Swatinem/rust-cache@v2
      - name: Check code formatting
        run: cargo fmt --check
      - name: Clippy lints
        run: cargo clippy --all-targets -- -D warnings
      - name: Run unit & contract tests
        run: cargo test --verbose
      - name: Build release binary
        run: cargo build --release
      - name: Prepare Windows artifact
        if: matrix.os == 'windows-latest'
        run: |
          mkdir dist
          cp target/release/hermes-pair.exe dist/HermesPair-windows-x64.exe
      - name: Prepare Linux artifact
        if: matrix.os == 'ubuntu-latest'
        run: |
          mkdir dist
          cp target/release/hermes-pair dist/hermes-pair-linux-x64
          chmod +x dist/hermes-pair-linux-x64
      - name: Upload Build Artifact
        uses: actions/upload-artifact@v4
        with:
          name: ${{ matrix.upload_name }}
          path: dist/*
--- a/.gitignore
+++ b/.gitignore
@ -0,0 +1,5 @@
 /target/
 Cargo.lock
 dist/
 .idea/
 *.exe
--- a/Cargo.toml
+++ b/Cargo.toml
@ -0,0 +1,34 @@
 [package]
 name = "hermes-pair"
 version = "0.1.0"
 edition = "2021"
 authors = ["ochenstarik-ui"]
 description = "Fast, secure QR onboarding helper for Hermes Agent"
 [lib]
 name = "hermes_pair"
 path = "src/lib.rs"
 [[bin]]
 name = "hermes-pair"
 path = "src/main.rs"
 [dependencies]
 tokio = { version = "1.43", features = ["full"] }
 reqwest = { version = "0.12", default-features = false, features = ["json", "rustls-tls"] }
 serde = { version = "1.0", features = ["derive"] }
 serde_json = "1.0"
 qrcode = { version = "0.14", default-features = false }
 image = { version = "0.25", default-features = false, features = ["png"] }
 rand = "0.8"
 uuid = { version = "1.13", features = ["v4", "serde"] }
 dirs = "6.0"
 clap = { version = "4.5", features = ["derive"] }
 eframe = { version = "0.31", default-features = false, features = ["default_fonts", "glow", "wayland", "x11"] }
 base64 = "0.22"
 if-addrs = "0.13"
 chrono = { version = "0.4", features = ["serde"] }
 url = { version = "2.5", features = ["serde"] }
 [dev-dependencies]
 tokio = { version = "1.43", features = ["full"] }
--- a/README.md
+++ b/README.md
@ -0,0 +1,198 @@
 # Hermes Pair (`hermes-pair`)
 [![Build and Test](https://github.com/ochenstarik-ui/hermes-pair/actions/workflows/build.yml/badge.svg)](https://github.com/ochenstarik-ui/hermes-pair/actions/workflows/build.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 Fast, lightweight, cross-platform pairing helper for **Hermes Agent** and the **Hermes Android App**.
 `hermes-pair` bridges your host computer (running Hermes) with the mobile companion app by generating high-contrast QR codes and standard pairing URIs (`hermes://pair?data=...`) containing host network information, authentication state, and cryptographically secure random nonces.
 ---
 ## Features
 - 🖥️ **Native GUI & Terminal UI Modes**: Runs as a lightweight native GUI window (`eframe`/`egui`) on desktop or an interactive/single-shot ANSI terminal interface on headless servers.
 - 🔍 **Smart Network Interface Discovery**: Automatically discovers and prioritizes physical LAN interfaces (`192.168.x.x`, `10.x.x.x`, `172.16-31.x.x`) and Tailscale overlays (`100.x.x.x`), while filtering out loopback and link-local adapters.
 - ⚡ **Real-Time Hermes Status Probing**: Connects to `http://127.0.0.1:<port>/api/status` and `http://<lan_ip>:<port>/api/status` to detect whether Hermes is active, verify version and auth requirements, and warn if Hermes is mistakenly bound only to loopback (`127.0.0.1`).
 - 🛡️ **Built-in Security Safeguards**:
  - Automatically warns if Hermes is exposed over LAN without authentication.
  - Generates single-use, 16-byte cryptographically secure random nonces.
  - Enforces configurable TTL expiry (default: 120 seconds).
  - Validates payload structure, versioning, and UUID integrity.
 - 💾 **Persistent Host Identity**: Manages a persistent UUIDv4 `host_id` saved atomically to `%APPDATA%\HermesPair\config.json` (Windows) or `~/.config/hermes-pair/config.json` (Linux).
 ---
 ## Pairing Protocol Specification (`v1`)
 The generated QR code encodes a custom URI:
 ```text
 hermes://pair?data=<BASE64URL_ENCODED_JSON>
 ```
 ### Decoded JSON Payload (`PairingPayloadV1`)
 ```json
 {
  "v": 1,
  "type": "hermes-pair",
  "host_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "name": "Gaming-PC",
  "host": "192.168.1.34",
  "port": 9119,
  "scheme": "http",
  "expires_at": 1756012800,
  "nonce": "k7a_QW9jRz1M..."
 }
 ```
 | Field | Type | Description |
 |---|---|---|
 | `v` | `u32` | Protocol schema version (`1`). |
 | `type` | `string` | Payload identifier (`hermes-pair`). |
 | `host_id` | `string` | Persistent UUIDv4 identifying the host machine. |
 | `name` | `string` | Human-readable computer or host display name. |
 | `host` | `string` | Reachable IPv4 address or hostname for the mobile client. |
 | `port` | `u16` | HTTP port on which Hermes Agent is listening (e.g. `9119`). |
 | `scheme` | `string` | Connection scheme (`http` or `https`). |
 | `expires_at` | `u64` | Unix epoch timestamp (seconds) after which this payload is rejected. |
 | `nonce` | `string` | 16 cryptographically random bytes, Base64URL-encoded. |
 ---
 ## Installation & Build
 ### Prerequisites
 - [Rust](https://rustup.rs/) 1.80+ (tested on Rust 1.98.0)
 ### Building from Source
 ```bash
 # Clone the repository
 git clone https://github.com/ochenstarik-ui/hermes-pair.git
 cd hermes-pair
 # Run tests
 cargo test
 # Build release binary
 cargo build --release
 ```
 Release binaries are produced at:
 - **Windows**: `target/release/hermes-pair.exe`
 - **Linux**: `target/release/hermes-pair`
 ---
 ## Usage
 ### 1. Native GUI Mode (Default)
 Simply execute `hermes-pair` without flags to open the native desktop window:
 ```bash
 hermes-pair
 ```
 #### GUI Controls:
 - **Status Badge**: Shows Hermes connectivity (Running, Offline, Loopback Only) and auth status.
 - **Network Interface Dropdown**: Switch between Wi-Fi, Ethernet, Tailscale, or virtual adapters.
 - **[ 🔄 Regenerate QR ]**: Generates a new payload with a fresh nonce and resets the countdown.
 - **[ 📋 Copy Link ]**: Copies `hermes://pair?data=...` directly to the system clipboard.
 - **[ 🔄 Check ]**: Retries probing the Hermes status endpoint immediately.
 ### 2. Interactive Terminal UI Mode
 For remote SSH sessions or terminals without a display server:
 ```bash
 hermes-pair --terminal
 # or short flag:
 hermes-pair -t
 ```
 Output:
 ```text
 Hermes: Running (v1.2.0, Auth: Required)
 Host: Gaming-PC
 Address: http://192.168.1.34:9119
 Host ID: 7b31d044...
 Expires in: 01:58
 ██████████████████████████████
 ██          ██  ██          ██
 ██  ██████  ██  ██  ██████  ██
 ██  ██████  ██  ██  ██████  ██
 ██          ██  ██          ██
 ██████████████████████████████
 ...
 Pairing Link: hermes://pair?data=eyJ2Ijox...
 ```
 ### 3. Headless / Single-Shot Script Mode
 To print the QR code once to stdout (useful for automation, provisioning scripts, or terminal output piping):
 ```bash
 hermes-pair qr
 # or
 hermes-pair --no-gui
 ```
 ### 4. Command Line Options
 ```text
 Usage: hermes-pair [OPTIONS] [COMMAND]
 Commands:
  qr    Output QR code once to stdout and exit
  help  Print this message or the help of the given subcommand(s)
 Options:
  -t, --terminal               Run interactive terminal mode with periodic refresh
      --no-gui                 Print QR once to stdout and exit (headless/script mode)
      --port <PORT>            Port of Hermes Agent [default: 9119]
      --hermes-url <URL>       Hermes status API URL (e.g. http://127.0.0.1:9119)
  -i, --interface <INTERFACE>  Specific network interface name or IPv4 address to advertise
      --ttl <TTL>              Pairing QR validity TTL in seconds [default: 120]
  -h, --help                   Print help
  -V, --version                Print version
 ```
 ---
 ## Configuration & Storage
 `hermes-pair` generates a persistent `host_id` on first launch and stores it in JSON format:
 - **Windows**: `%APPDATA%\HermesPair\config.json`
 - **Linux / macOS**: `~/.config/hermes-pair/config.json`
 Example configuration:
 ```json
 {
  "host_id": "7b31d044-cf64-4e78-9df2-bb58a8f5e1a1",
  "display_name": "Studio-Workstation"
 }
 ```
 ---
 ## Troubleshooting & Warnings
 ### Warning: Loopback Only
 If Hermes is started with default `127.0.0.1` binding, other devices on the LAN cannot connect.
 Start Hermes binding to all interfaces:
 ```bash
 hermes serve --host 0.0.0.0 --port 9119
 ```
 ### Warning: Unauthenticated Network Access
 If Hermes has no authentication configured, any device on your local network could access the API. Consider enabling token or password authentication for production usage.
 ---
 ## License
 Licensed under the [MIT License](LICENSE).
--- a/src/app.rs
+++ b/src/app.rs
@ -0,0 +1,380 @@
 use crate::config::AppConfig;
 use crate::hermes::{HermesProbeClient, ProbeState};
 use crate::identity::{get_display_name, get_host_id};
 use crate::models::{NetworkInterfaceInfo, PairingPayloadV1};
 use crate::network::discover_network_interfaces;
 use crate::pairing::{create_pairing_payload, encode_pairing_uri};
 use crate::qr::render_egui_image;
 use eframe::egui::{self, Color32, RichText, TextureHandle, Vec2};
 use std::net::Ipv4Addr;
 use std::sync::mpsc::{channel, Receiver, Sender};
 use std::time::{Duration, Instant};
 pub struct HermesPairApp {
    config: AppConfig,
    port: u16,
    ttl: u64,
    interfaces: Vec<NetworkInterfaceInfo>,
    selected_iface_index: usize,
    current_payload: PairingPayloadV1,
    current_uri: String,
    generated_at: Instant,
    qr_texture: Option<TextureHandle>,
    probe_state: ProbeState,
    probe_tx: Sender<ProbeState>,
    probe_rx: Receiver<ProbeState>,
    is_probing: bool,
    copied_banner_timer: Option<Instant>,
 }
 impl HermesPairApp {
    pub fn new(
        cc: &eframe::CreationContext<'_>,
        config: AppConfig,
        port: u16,
        explicit_interface: Option<String>,
        ttl: u64,
    ) -> Self {
        let mut interfaces = discover_network_interfaces().unwrap_or_default();
        if interfaces.is_empty() {
            interfaces.push(NetworkInterfaceInfo {
                name: "Loopback".to_string(),
                ip: Ipv4Addr::new(127, 0, 0, 1),
                is_loopback: true,
                is_virtual: false,
            });
        }
        let mut selected_iface_index = 0;
        if let Some(ref target) = explicit_interface {
            let lower = target.to_lowercase();
            if let Some(idx) = interfaces.iter().position(|i| {
                i.name.to_lowercase().contains(&lower) || i.ip.to_string() == *target
            }) {
                selected_iface_index = idx;
            }
        }
        let host_ip = interfaces[selected_iface_index].ip;
        let host_id = get_host_id(&config);
        let display_name = get_display_name(&config);
        let current_payload = create_pairing_payload(
            host_id,
            display_name,
            host_ip.to_string(),
            port,
            "http".to_string(),
            ttl,
        );
        let current_uri = encode_pairing_uri(&current_payload);
        let qr_texture = Self::build_qr_texture(&cc.egui_ctx, &current_uri);
        let (probe_tx, probe_rx) = channel();
        let mut app = Self {
            config,
            port,
            ttl,
            interfaces,
            selected_iface_index,
            current_payload,
            current_uri,
            generated_at: Instant::now(),
            qr_texture,
            probe_state: ProbeState::Offline("Initial probe running...".to_string()),
            probe_tx,
            probe_rx,
            is_probing: false,
            copied_banner_timer: None,
        };
        app.trigger_probe();
        app
    }
    fn build_qr_texture(ctx: &egui::Context, uri: &str) -> Option<TextureHandle> {
        match render_egui_image(uri, 8) {
            Ok(img) => Some(ctx.load_texture("qr_code", img, egui::TextureOptions::NEAREST)),
            Err(e) => {
                eprintln!("Failed to generate QR texture: {}", e);
                None
            }
        }
    }
    fn regenerate_payload(&mut self, ctx: &egui::Context) {
        let host_ip = self.selected_ip();
        let host_id = get_host_id(&self.config);
        let display_name = get_display_name(&self.config);
        self.current_payload = create_pairing_payload(
            host_id,
            display_name,
            host_ip.to_string(),
            self.port,
            "http".to_string(),
            self.ttl,
        );
        self.current_uri = encode_pairing_uri(&self.current_payload);
        self.generated_at = Instant::now();
        self.qr_texture = Self::build_qr_texture(ctx, &self.current_uri);
    }
    fn selected_ip(&self) -> Ipv4Addr {
        self.interfaces
            .get(self.selected_iface_index)
            .map(|i| i.ip)
            .unwrap_or_else(|| Ipv4Addr::new(127, 0, 0, 1))
    }
    fn trigger_probe(&mut self) {
        if self.is_probing {
            return;
        }
        self.is_probing = true;
        let port = self.port;
        let lan_ip = self.selected_ip();
        let tx = self.probe_tx.clone();
        std::thread::spawn(move || {
            let rt = tokio::runtime::Builder::new_current_thread()
                .enable_all()
                .build();
            if let Ok(rt) = rt {
                rt.block_on(async {
                    let client = HermesProbeClient::new();
                    let res = client.probe(port, Some(lan_ip)).await;
                    let _ = tx.send(res);
                });
            }
        });
    }
    fn refresh_interfaces(&mut self) {
        if let Ok(new_ifaces) = discover_network_interfaces() {
            if !new_ifaces.is_empty() {
                self.interfaces = new_ifaces;
                if self.selected_iface_index >= self.interfaces.len() {
                    self.selected_iface_index = 0;
                }
            }
        }
    }
 }
 impl eframe::App for HermesPairApp {
    fn update(&mut self, ctx: &egui::Context, _frame: &mut eframe::Frame) {
        // Poll background probe channel
        while let Ok(state) = self.probe_rx.try_recv() {
            self.probe_state = state;
            self.is_probing = false;
        }
        // Request repaint every 500ms for smooth timer update
        ctx.request_repaint_after(Duration::from_millis(500));
        let elapsed = self.generated_at.elapsed().as_secs();
        let remaining = self.ttl.saturating_sub(elapsed);
        let is_expired = remaining == 0;
        egui::CentralPanel::default().show(ctx, |ui| {
            ui.spacing_mut().item_spacing = Vec2::new(8.0, 8.0);
            // Title and Hermes Status Header
            ui.vertical_centered(|ui| {
                ui.heading(RichText::new("Hermes Pair").size(22.0).strong());
            });
            ui.add_space(4.0);
            // Status Card
            egui::Frame::group(ui.style())
                .inner_margin(8.0)
                .show(ui, |ui| {
                    ui.horizontal(|ui| {
                        match &self.probe_state {
                            ProbeState::Online(resp) => {
                                ui.colored_label(Color32::from_rgb(46, 204, 113), "● Running");
                                let ver = resp.version.as_deref().unwrap_or("unknown");
                                ui.label(format!("v{}", ver));
                                if resp.auth_required {
                                    ui.colored_label(Color32::from_rgb(52, 152, 219), "[Auth: Required]");
                                } else {
                                    ui.colored_label(Color32::from_rgb(230, 126, 34), "[Auth: None]");
                                }
                            }
                            ProbeState::LoopbackOnly { .. } => {
                                ui.colored_label(Color32::from_rgb(241, 196, 15), "● Loopback Only");
                            }
                            ProbeState::Offline(err) => {
                                ui.colored_label(Color32::from_rgb(231, 76, 60), "● Offline");
                                ui.label(RichText::new(err).size(11.0).italics());
                            }
                        }
                        ui.with_layout(egui::Layout::right_to_left(egui::Align::Center), |ui| {
                            if ui.button("🔄 Check").clicked() {
                                self.trigger_probe();
                            }
                        });
                    });
                });
            // Warning Banners
            if let ProbeState::LoopbackOnly { .. } = &self.probe_state {
                ui.add_space(2.0);
                egui::Frame::NONE
                    .fill(Color32::from_rgb(60, 45, 10))
                    .stroke(egui::Stroke::new(1.0_f32, Color32::from_rgb(241, 196, 15)))
                    .inner_margin(8.0)
                    .corner_radius(4.0)
                    .show(ui, |ui| {
                        ui.horizontal(|ui| {
                            ui.label(RichText::new("⚠️").size(16.0));
                            ui.label(
                                RichText::new(format!(
                                    "Hermes is currently only reachable from this computer (127.0.0.1).\n\
                                     Start Hermes with LAN-accessible bind:\n\
                                     hermes serve --host 0.0.0.0 --port {}",
                                    self.port
                                ))
                                .size(11.5)
                                .color(Color32::from_rgb(241, 196, 15)),
                            );
                        });
                    });
            }
            if let ProbeState::Online(resp) = &self.probe_state {
                if !resp.auth_required {
                    ui.add_space(2.0);
                    egui::Frame::NONE
                        .fill(Color32::from_rgb(50, 25, 20))
                        .stroke(egui::Stroke::new(1.0_f32, Color32::from_rgb(230, 126, 34)))
                        .inner_margin(8.0)
                        .corner_radius(4.0)
                        .show(ui, |ui| {
                            ui.label(
                                RichText::new(
                                    "⚠️ Warning: Hermes is reachable over the network without authentication. \
                                     Do not expose beyond a trusted LAN.",
                                )
                                .size(11.5)
                                .color(Color32::from_rgb(230, 126, 34)),
                            );
                        });
                }
            }
            ui.add_space(4.0);
            // Network Interface Selector
            ui.horizontal(|ui| {
                ui.label("Network Interface:");
                let current_label = if let Some(iface) = self.interfaces.get(self.selected_iface_index) {
                    format!("{} ({})", iface.name, iface.ip)
                } else {
                    "None".to_string()
                };
                let prev_idx = self.selected_iface_index;
                egui::ComboBox::from_id_salt("interface_select")
                    .selected_text(current_label)
                    .show_ui(ui, |ui| {
                        for (idx, iface) in self.interfaces.iter().enumerate() {
                            let tag = if iface.is_virtual {
                                "[Virt]"
                            } else if iface.ip.is_private() {
                                "[LAN]"
                            } else {
                                ""
                            };
                            let label = format!("{} ({}) {}", iface.name, iface.ip, tag);
                            ui.selectable_value(&mut self.selected_iface_index, idx, label);
                        }
                    });
                if prev_idx != self.selected_iface_index {
                    self.regenerate_payload(ctx);
                    self.trigger_probe();
                }
            });
            // Address display
            ui.horizontal(|ui| {
                ui.label(RichText::new("Target Address:").strong());
                ui.monospace(format!("http://{}:{}", self.selected_ip(), self.port));
            });
            ui.add_space(4.0);
            // Center QR Code
            ui.vertical_centered(|ui| {
                if let Some(ref texture) = self.qr_texture {
                    ui.image((texture.id(), Vec2::new(260.0, 260.0)));
                } else {
                    ui.label("Failed to load QR code");
                }
                ui.add_space(6.0);
                // Expiry timer
                if is_expired {
                    ui.label(
                        RichText::new("⚠️ QR Code Expired")
                            .color(Color32::from_rgb(231, 76, 60))
                            .strong(),
                    );
                } else {
                    let mins = remaining / 60;
                    let secs = remaining % 60;
                    ui.label(
                        RichText::new(format!("Expires in {:02}:{:02}", mins, secs))
                            .size(13.0)
                            .color(Color32::LIGHT_GRAY),
                    );
                }
            });
            ui.add_space(6.0);
            // Action Buttons
            ui.horizontal(|ui| {
                ui.columns(2, |cols| {
                    if cols[0].button("🔄 Regenerate QR").clicked() {
                        self.refresh_interfaces();
                        self.regenerate_payload(ctx);
                        self.trigger_probe();
                    }
                    if cols[1].button("📋 Copy Link").clicked() {
                        ctx.copy_text(self.current_uri.clone());
                        self.copied_banner_timer = Some(Instant::now());
                    }
                });
            });
            // Copied banner notification
            if let Some(timer) = self.copied_banner_timer {
                if timer.elapsed().as_secs() < 2 {
                    ui.vertical_centered(|ui| {
                        ui.label(
                            RichText::new("✓ Pairing link copied to clipboard!")
                                .color(Color32::from_rgb(46, 204, 113))
                                .size(12.0),
                        );
                    });
                } else {
                    self.copied_banner_timer = None;
                }
            }
        });
    }
 }
--- a/src/cli.rs
+++ b/src/cli.rs
@ -0,0 +1,249 @@
 use crate::config::AppConfig;
 use crate::hermes::{HermesProbeClient, ProbeState};
 use crate::identity::{get_display_name, get_host_id};
 use crate::models::NetworkInterfaceInfo;
 use crate::network::discover_network_interfaces;
 use crate::pairing::{create_pairing_payload, encode_pairing_uri};
 use crate::qr::render_terminal_qr;
 use clap::{Args, Parser, Subcommand};
 use std::net::Ipv4Addr;
 use std::str::FromStr;
 use std::time::Duration;
 use tokio::time::sleep;
 #[derive(Parser, Debug, Clone)]
 #[command(
    name = "hermes-pair",
    version = "0.1.0",
    author = "ochenstarik-ui",
    about = "Fast, secure QR onboarding helper for Hermes Agent"
 )]
 pub struct CliArgs {
    /// Run interactive terminal mode with periodic refresh
    #[arg(long, short = 't')]
    pub terminal: bool,
    /// Print QR once to stdout and exit (headless/script mode)
    #[arg(long = "no-gui")]
    pub no_gui: bool,
    /// Port of Hermes Agent (default 9119)
    #[arg(long, default_value = "9119")]
    pub port: u16,
    /// Hermes status API URL (e.g. http://127.0.0.1:9119)
    #[arg(long = "hermes-url")]
    pub hermes_url: Option<String>,
    /// Specific network interface name or IPv4 address to advertise
    #[arg(long, short = 'i')]
    pub interface: Option<String>,
    /// Pairing QR validity TTL in seconds (default 120)
    #[arg(long, default_value = "120")]
    pub ttl: u64,
    #[command(subcommand)]
    pub command: Option<CliCommand>,
 }
 #[derive(Subcommand, Debug, Clone)]
 pub enum CliCommand {
    /// Output QR code once to stdout and exit
    Qr(QrArgs),
 }
 #[derive(Args, Debug, Clone)]
 pub struct QrArgs {
    /// Port of Hermes Agent
    #[arg(long)]
    pub port: Option<u16>,
    /// Specific network interface name or IPv4 address
    #[arg(long, short = 'i')]
    pub interface: Option<String>,
    /// Pairing QR validity TTL in seconds
    #[arg(long)]
    pub ttl: Option<u64>,
 }
 /// Resolves the selected IPv4 address based on user input or automatic interface detection.
 pub fn resolve_selected_ip(
    explicit_interface: Option<&str>,
    interfaces: &[NetworkInterfaceInfo],
 ) -> (String, Ipv4Addr) {
    if let Some(target) = explicit_interface {
        if let Ok(ip) = Ipv4Addr::from_str(target) {
            return (format!("Manual ({})", ip), ip);
        }
        let lower = target.to_lowercase();
        if let Some(matched) = interfaces.iter().find(|i| {
            i.name.to_lowercase().contains(&lower) || i.ip.to_string() == target
        }) {
            return (matched.name.clone(), matched.ip);
        }
    }
    if let Some(first) = interfaces.first() {
        return (first.name.clone(), first.ip);
    }
    ("Loopback".to_string(), Ipv4Addr::new(127, 0, 0, 1))
 }
 /// Runs single-shot terminal output mode.
 pub async fn run_once(
    config: &AppConfig,
    port: u16,
    explicit_interface: Option<&str>,
    ttl: u64,
 ) -> Result<(), Box<dyn std::error::Error>> {
    let interfaces = discover_network_interfaces().unwrap_or_default();
    let (_iface_name, host_ip) = resolve_selected_ip(explicit_interface, &interfaces);
    let client = HermesProbeClient::new();
    let probe_state = client.probe(port, Some(host_ip)).await;
    let host_id = get_host_id(config);
    let display_name = get_display_name(config);
    let scheme = "http".to_string();
    let payload = create_pairing_payload(
        host_id.clone(),
        display_name.clone(),
        host_ip.to_string(),
        port,
        scheme,
        ttl,
    );
    let uri = encode_pairing_uri(&payload);
    let qr_rendered = render_terminal_qr(&uri).map_err(|e| format!("QR Render Error: {}", e))?;
    // Format Hermes status line
    match &probe_state {
        ProbeState::Online(status) => {
            let ver = status.version.as_deref().unwrap_or("unknown");
            let auth = if status.auth_required {
                "Required"
            } else {
                "None"
            };
            println!("Hermes: Running (v{}, Auth: {})", ver, auth);
        }
        ProbeState::LoopbackOnly { lan_error, .. } => {
            println!("Hermes: Running locally (127.0.0.1), but LAN unreachable: {}", lan_error);
            println!("⚠️  Warning: Hermes is bound to loopback only. Start Hermes with --host 0.0.0.0");
        }
        ProbeState::Offline(err) => {
            println!("Hermes: Offline ({})", err);
        }
    }
    let short_id = if host_id.len() >= 8 {
        format!("{}...", &host_id[..8])
    } else {
        host_id.clone()
    };
    println!("Host: {}", display_name);
    println!("Address: http://{}:{}", host_ip, port);
    println!("Host ID: {}", short_id);
    println!("Expires in: {:02}:{:02}", ttl / 60, ttl % 60);
    println!("\n{}", qr_rendered);
    println!("Pairing Link: {}", uri);
    Ok(())
 }
 /// Runs interactive terminal UI mode that updates in a loop.
 pub async fn run_terminal_loop(
    config: &AppConfig,
    port: u16,
    explicit_interface: Option<&str>,
    ttl: u64,
 ) -> Result<(), Box<dyn std::error::Error>> {
    let mut last_generated_at = std::time::Instant::now();
    let mut current_payload = {
        let interfaces = discover_network_interfaces().unwrap_or_default();
        let (_iface_name, host_ip) = resolve_selected_ip(explicit_interface, &interfaces);
        create_pairing_payload(
            get_host_id(config),
            get_display_name(config),
            host_ip.to_string(),
            port,
            "http".to_string(),
            ttl,
        )
    };
    let client = HermesProbeClient::new();
    loop {
        let now = std::time::Instant::now();
        let elapsed = now.duration_since(last_generated_at).as_secs();
        let interfaces = discover_network_interfaces().unwrap_or_default();
        let (_iface_name, host_ip) = resolve_selected_ip(explicit_interface, &interfaces);
        // Regenerate if expired
        if elapsed >= ttl {
            current_payload = create_pairing_payload(
                get_host_id(config),
                get_display_name(config),
                host_ip.to_string(),
                port,
                "http".to_string(),
                ttl,
            );
            last_generated_at = std::time::Instant::now();
        }
        let remaining = ttl.saturating_sub(now.duration_since(last_generated_at).as_secs());
        let probe_state = client.probe(port, Some(host_ip)).await;
        let uri = encode_pairing_uri(&current_payload);
        let qr_rendered = render_terminal_qr(&uri).unwrap_or_default();
        // Clear terminal screen (cross-platform ANSI)
        print!("\x1B[2J\x1B[1;1H");
        match &probe_state {
            ProbeState::Online(status) => {
                let ver = status.version.as_deref().unwrap_or("unknown");
                let auth = if status.auth_required {
                    "Required"
                } else {
                    "None"
                };
                println!("Hermes: Running (v{}, Auth: {})", ver, auth);
            }
            ProbeState::LoopbackOnly { lan_error, .. } => {
                println!("Hermes: Loopback Only (127.0.0.1) [LAN Error: {}]", lan_error);
                println!("⚠️  Run Hermes with: hermes serve --host 0.0.0.0 --port {}", port);
            }
            ProbeState::Offline(err) => {
                println!("Hermes: Offline ({})", err);
            }
        }
        let host_id = &current_payload.host_id;
        let short_id = if host_id.len() >= 8 {
            format!("{}...", &host_id[..8])
        } else {
            host_id.clone()
        };
        println!("Host: {}", current_payload.name);
        println!("Address: http://{}:{}", current_payload.host, current_payload.port);
        println!("Host ID: {}", short_id);
        println!("Expires in: {:02}:{:02}", remaining / 60, remaining % 60);
        println!("\n{}", qr_rendered);
        println!("Pairing Link: {}", uri);
        println!("\nPress Ctrl+C to exit.");
        sleep(Duration::from_secs(1)).await;
    }
 }
--- a/src/config.rs
+++ b/src/config.rs
@ -0,0 +1,108 @@
 use serde::{Deserialize, Serialize};
 use std::fs;
 use std::path::{Path, PathBuf};
 use uuid::Uuid;
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
 pub struct AppConfig {
    pub host_id: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub display_name: Option<String>,
 }
 impl Default for AppConfig {
    fn default() -> Self {
        Self {
            host_id: Uuid::new_v4().to_string(),
            display_name: None,
        }
    }
 }
 /// Resolves configuration path according to platform conventions:
 /// - Windows: `%APPDATA%\HermesPair\config.json`
 /// - Linux/Unix: `~/.config/hermes-pair/config.json`
 pub fn get_config_path() -> PathBuf {
    #[cfg(target_os = "windows")]
    {
        if let Ok(appdata) = std::env::var("APPDATA") {
            return PathBuf::from(appdata).join("HermesPair").join("config.json");
        }
        if let Some(config_dir) = dirs::config_dir() {
            return config_dir.join("HermesPair").join("config.json");
        }
        PathBuf::from("config.json")
    }
    #[cfg(not(target_os = "windows"))]
    {
        if let Ok(xdg) = std::env::var("XDG_CONFIG_HOME") {
            return PathBuf::from(xdg).join("hermes-pair").join("config.json");
        }
        if let Some(config_dir) = dirs::config_dir() {
            return config_dir.join("hermes-pair").join("config.json");
        }
        if let Some(home_dir) = dirs::home_dir() {
            return home_dir.join(".config").join("hermes-pair").join("config.json");
        }
        PathBuf::from("config.json")
    }
 }
 /// Saves the configuration atomically by writing to a temporary file and renaming it.
 pub fn save_config_to_path(config: &AppConfig, path: &Path) -> Result<(), std::io::Error> {
    if let Some(parent) = path.parent() {
        fs::create_dir_all(parent)?;
    }
    let json_bytes = serde_json::to_vec_pretty(config)
        .map_err(|e| std::io::Error::new(std::io::ErrorKind::InvalidData, e))?;
    let tmp_file_name = format!(
        "{}.tmp.{}",
        path.file_name().and_then(|n| n.to_str()).unwrap_or("config"),
        Uuid::new_v4()
    );
    let tmp_path = match path.parent() {
        Some(p) => p.join(tmp_file_name),
        None => PathBuf::from(tmp_file_name),
    };
    fs::write(&tmp_path, json_bytes)?;
    // On Windows and Unix, fs::rename replaces the destination atomically if in the same directory.
    if let Err(_err) = fs::rename(&tmp_path, path) {
        // Fallback in case rename fails due to cross-platform replacement edge cases
        let _ = fs::remove_file(path);
        if let Err(fallback_err) = fs::rename(&tmp_path, path) {
            let _ = fs::remove_file(&tmp_path);
            return Err(fallback_err.into());
        }
    }
    Ok(())
 }
 /// Loads an existing config or generates a new one with a persistent UUIDv4 `host_id` and saves it.
 pub fn load_or_create_config_from_path(path: &Path) -> Result<AppConfig, std::io::Error> {
    if path.exists() {
        let content = fs::read_to_string(path)?;
        if let Ok(mut config) = serde_json::from_str::<AppConfig>(&content) {
            if config.host_id.trim().is_empty() {
                config.host_id = Uuid::new_v4().to_string();
                save_config_to_path(&config, path)?;
            }
            return Ok(config);
        }
    }
    let new_config = AppConfig::default();
    save_config_to_path(&new_config, path)?;
    Ok(new_config)
 }
 /// Convenience function to load or create configuration at the default system location.
 pub fn load_or_create_config() -> Result<AppConfig, std::io::Error> {
    let path = get_config_path();
    load_or_create_config_from_path(&path)
 }
--- a/src/hermes.rs
+++ b/src/hermes.rs
@ -0,0 +1,117 @@
 use crate::models::HermesStatusResponse;
 use std::net::Ipv4Addr;
 use std::time::Duration;
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum ProbeState {
    Online(HermesStatusResponse),
    LoopbackOnly {
        local_status: HermesStatusResponse,
        lan_error: String,
    },
    Offline(String),
 }
 impl ProbeState {
    pub fn is_online(&self) -> bool {
        matches!(self, ProbeState::Online(_))
    }
    pub fn is_loopback_only(&self) -> bool {
        matches!(self, ProbeState::LoopbackOnly { .. })
    }
    pub fn status_response(&self) -> Option<&HermesStatusResponse> {
        match self {
            ProbeState::Online(ref resp) => Some(resp),
            ProbeState::LoopbackOnly {
                ref local_status, ..
            } => Some(local_status),
            ProbeState::Offline(_) => None,
        }
    }
 }
 #[derive(Clone)]
 pub struct HermesProbeClient {
    client: reqwest::Client,
 }
 impl Default for HermesProbeClient {
    fn default() -> Self {
        Self::new()
    }
 }
 impl HermesProbeClient {
    pub fn new() -> Self {
        let client = reqwest::Client::builder()
            .timeout(Duration::from_secs(2))
            .build()
            .unwrap_or_else(|_| reqwest::Client::new());
        Self { client }
    }
    pub async fn fetch_status(&self, base_url: &str) -> Result<HermesStatusResponse, String> {
        let url = if base_url.ends_with('/') {
            format!("{}api/status", base_url)
        } else {
            format!("{}/api/status", base_url)
        };
        let response = self
            .client
            .get(&url)
            .send()
            .await
            .map_err(|e| format!("Connection error: {}", e))?;
        if !response.status().is_success() {
            return Err(format!("HTTP status {}", response.status()));
        }
        let body = response
            .json::<HermesStatusResponse>()
            .await
            .map_err(|e| format!("Failed to parse status response: {}", e))?;
        Ok(body)
    }
    pub async fn probe(&self, port: u16, lan_ip: Option<Ipv4Addr>) -> ProbeState {
        let local_url = format!("http://127.0.0.1:{}", port);
        let local_result = self.fetch_status(&local_url).await;
        match (local_result, lan_ip) {
            (Ok(local_status), Some(lan)) => {
                let lan_url = format!("http://{}:{}", lan, port);
                match self.fetch_status(&lan_url).await {
                    Ok(lan_status) => ProbeState::Online(lan_status),
                    Err(lan_err) => ProbeState::LoopbackOnly {
                        local_status,
                        lan_error: lan_err,
                    },
                }
            }
            (Ok(local_status), None) => ProbeState::Online(local_status),
            (Err(local_err), Some(lan)) => {
                let lan_url = format!("http://{}:{}", lan, port);
                match self.fetch_status(&lan_url).await {
                    Ok(lan_status) => ProbeState::Online(lan_status),
                    Err(_) => ProbeState::Offline(local_err),
                }
            }
            (Err(local_err), None) => ProbeState::Offline(local_err),
        }
    }
 }
 pub async fn probe_hermes_status(base_url: &str) -> Result<HermesStatusResponse, String> {
    let client = HermesProbeClient::new();
    client.fetch_status(base_url).await
 }
 pub async fn probe_hermes(port: u16, lan_ip: Option<Ipv4Addr>) -> ProbeState {
    let client = HermesProbeClient::new();
    client.probe(port, lan_ip).await
 }
--- a/src/identity.rs
+++ b/src/identity.rs
@ -0,0 +1,54 @@
 use crate::config::AppConfig;
 /// Returns the persistent host_id from configuration.
 pub fn get_host_id(config: &AppConfig) -> String {
    config.host_id.clone()
 }
 /// Detects the system hostname from environment variables or sensible fallbacks.
 pub fn detect_system_hostname() -> String {
    if let Ok(name) = std::env::var("COMPUTERNAME") {
        let trimmed = name.trim();
        if !trimmed.is_empty() {
            return trimmed.to_string();
        }
    }
    if let Ok(name) = std::env::var("HOSTNAME") {
        let trimmed = name.trim();
        if !trimmed.is_empty() {
            return trimmed.to_string();
        }
    }
    if let Ok(name) = std::env::var("HOST") {
        let trimmed = name.trim();
        if !trimmed.is_empty() {
            return trimmed.to_string();
        }
    }
    // Try reading /etc/hostname on Unix
    #[cfg(unix)]
    {
        if let Ok(name) = std::fs::read_to_string("/etc/hostname") {
            let trimmed = name.trim();
            if !trimmed.is_empty() {
                return trimmed.to_string();
            }
        }
    }
    "Hermes-Host".to_string()
 }
 /// Returns the configured display name, or the detected system hostname if not set.
 pub fn get_display_name(config: &AppConfig) -> String {
    if let Some(ref name) = config.display_name {
        let trimmed = name.trim();
        if !trimmed.is_empty() {
            return trimmed.to_string();
        }
    }
    detect_system_hostname()
 }
--- a/src/lib.rs
+++ b/src/lib.rs
@ -0,0 +1,9 @@
 pub mod app;
 pub mod cli;
 pub mod config;
 pub mod hermes;
 pub mod identity;
 pub mod models;
 pub mod network;
 pub mod pairing;
 pub mod qr;
--- a/src/main.rs
+++ b/src/main.rs
@ -0,0 +1,62 @@
 use clap::Parser;
 use eframe::egui::Vec2;
 use hermes_pair::app::HermesPairApp;
 use hermes_pair::cli::{run_once, run_terminal_loop, CliArgs, CliCommand};
 use hermes_pair::config::load_or_create_config;
 #[tokio::main]
 async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let args = CliArgs::parse();
    let config = load_or_create_config()?;
    if let Some(CliCommand::Qr(qr_args)) = &args.command {
        let port = qr_args.port.unwrap_or(args.port);
        let iface = qr_args.interface.as_deref().or(args.interface.as_deref());
        let ttl = qr_args.ttl.unwrap_or(args.ttl);
        return run_once(&config, port, iface, ttl).await;
    }
    if args.no_gui {
        return run_once(&config, args.port, args.interface.as_deref(), args.ttl).await;
    }
    if args.terminal {
        return run_terminal_loop(&config, args.port, args.interface.as_deref(), args.ttl).await;
    }
    // Launch GUI
    let native_options = eframe::NativeOptions {
        viewport: eframe::egui::ViewportBuilder::default()
            .with_inner_size(Vec2::new(420.0, 620.0))
            .with_min_inner_size(Vec2::new(380.0, 520.0))
            .with_title("Hermes Pair"),
        ..Default::default()
    };
    let config_clone = config.clone();
    let port = args.port;
    let iface = args.interface.clone();
    let ttl = args.ttl;
    let res = eframe::run_native(
        "Hermes Pair",
        native_options,
        Box::new(move |cc| {
            Ok(Box::new(HermesPairApp::new(
                cc,
                config_clone,
                port,
                iface,
                ttl,
            )))
        }),
    );
    if let Err(e) = res {
        eprintln!("Failed to launch GUI: {}", e);
        eprintln!("Falling back to terminal mode...");
        return run_terminal_loop(&config, args.port, args.interface.as_deref(), args.ttl).await;
    }
    Ok(())
 }
--- a/src/models.rs
+++ b/src/models.rs
@ -0,0 +1,38 @@
 use serde::{Deserialize, Serialize};
 use std::net::Ipv4Addr;
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
 pub struct PairingPayloadV1 {
    pub v: u32, // 1
    #[serde(rename = "type")]
    pub payload_type: String, // "hermes-pair"
    pub host_id: String, // UUIDv4 string
    pub name: String, // Display name / computer name
    pub host: String, // Reachable IPv4 or hostname
    pub port: u16, // Port (e.g. 9119)
    pub scheme: String, // "http" or "https"
    pub expires_at: u64, // Unix timestamp in seconds
    pub nonce: String, // Base64URL-encoded cryptographically secure random 16 bytes
 }
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Default)]
 pub struct HermesStatusResponse {
    #[serde(default)]
    pub status: String,
    #[serde(rename = "authRequired", default)]
    pub auth_required: bool,
    #[serde(rename = "authProviders", default)]
    pub auth_providers: Vec<String>,
    #[serde(rename = "authFlows", default)]
    pub auth_flows: Vec<String>,
    #[serde(default)]
    pub version: Option<String>,
 }
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct NetworkInterfaceInfo {
    pub name: String,
    pub ip: Ipv4Addr,
    pub is_loopback: bool,
    pub is_virtual: bool,
 }
--- a/src/network.rs
+++ b/src/network.rs
@ -0,0 +1,86 @@
 pub use crate::models::NetworkInterfaceInfo;
 use std::net::Ipv4Addr;
 pub fn is_loopback(ip: &Ipv4Addr) -> bool {
    ip.is_loopback() || ip.octets()[0] == 127
 }
 pub fn is_link_local(ip: &Ipv4Addr) -> bool {
    let octets = ip.octets();
    octets[0] == 169 && octets[1] == 254
 }
 pub fn is_tailscale_ip(ip: &Ipv4Addr) -> bool {
    let octets = ip.octets();
    // CGNAT range 100.64.0.0/10 commonly used by Tailscale / WireGuard overlays
    octets[0] == 100 && (octets[1] >= 64 && octets[1] <= 127)
 }
 pub fn is_virtual_adapter(name: &str) -> bool {
    let lower = name.to_lowercase();
    lower.contains("docker")
        || lower.contains("veth")
        || lower.contains("virbr")
        || lower.contains("vbox")
        || lower.contains("vmnet")
        || lower.contains("hyper-v")
        || lower.contains("wsl")
        || lower.contains("vethernet")
        || lower.contains("virtual")
        || lower.contains("tap")
        || lower.contains("tun")
 }
 fn interface_priority(info: &NetworkInterfaceInfo) -> u32 {
    let is_priv = info.ip.is_private();
    let is_ts = is_tailscale_ip(&info.ip);
    match (info.is_virtual, is_priv, is_ts) {
        (false, true, _) => 100,      // Physical LAN (192.168.x.x, 10.x.x.x, 172.16-31.x.x)
        (false, false, true) => 80,   // Tailscale / Overlay
        (false, false, false) => 60,  // Other physical (e.g. public or custom)
        (true, true, _) => 40,        // Virtual LAN (e.g. WSL, Hyper-V virtual switch)
        (true, false, true) => 30,    // Virtual Tailscale
        (true, false, false) => 20,   // Other virtual
    }
 }
 pub fn filter_and_sort_interfaces(
    interfaces: impl IntoIterator<Item = NetworkInterfaceInfo>,
 ) -> Vec<NetworkInterfaceInfo> {
    let mut filtered: Vec<NetworkInterfaceInfo> = interfaces
        .into_iter()
        .filter(|iface| !iface.is_loopback && !is_loopback(&iface.ip) && !is_link_local(&iface.ip))
        .collect();
    filtered.sort_by(|a, b| {
        let prio_a = interface_priority(a);
        let prio_b = interface_priority(b);
        prio_b
            .cmp(&prio_a)
            .then_with(|| a.name.cmp(&b.name))
            .then_with(|| a.ip.cmp(&b.ip))
    });
    filtered
 }
 pub fn discover_network_interfaces() -> Result<Vec<NetworkInterfaceInfo>, std::io::Error> {
    let if_addrs_list = if_addrs::get_if_addrs()?;
    let mut raw_interfaces = Vec::new();
    for iface in if_addrs_list {
        if let if_addrs::IfAddr::V4(ref v4_addr) = iface.addr {
            let is_virt = is_virtual_adapter(&iface.name);
            let loopback = iface.is_loopback() || is_loopback(&v4_addr.ip);
            raw_interfaces.push(NetworkInterfaceInfo {
                name: iface.name,
                ip: v4_addr.ip,
                is_loopback: loopback,
                is_virtual: is_virt,
            });
        }
    }
    Ok(filter_and_sort_interfaces(raw_interfaces))
 }
--- a/src/pairing.rs
+++ b/src/pairing.rs
@ -0,0 +1,167 @@
 pub use crate::models::PairingPayloadV1;
 use base64::engine::general_purpose::{STANDARD, URL_SAFE, URL_SAFE_NO_PAD};
 use base64::Engine;
 use rand::RngCore;
 use std::fmt;
 use std::time::{SystemTime, UNIX_EPOCH};
 use url::Url;
 use uuid::Uuid;
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum PairingError {
    InvalidUriScheme(String),
    InvalidUriFormat(String),
    MissingDataParameter,
    Base64DecodeError(String),
    JsonDecodeError(String),
    UnsupportedVersion(u32),
    InvalidPayloadType(String),
    InvalidHostId(String),
    EmptyHost,
    InvalidPort(u16),
    PayloadExpired { expires_at: u64, now: u64 },
 }
 impl fmt::Display for PairingError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            PairingError::InvalidUriScheme(s) => write!(f, "Invalid URI scheme '{}', expected 'hermes'", s),
            PairingError::InvalidUriFormat(s) => write!(f, "Invalid pairing URI format: {}", s),
            PairingError::MissingDataParameter => write!(f, "Missing 'data' query parameter in pairing URI"),
            PairingError::Base64DecodeError(e) => write!(f, "Failed to decode Base64URL payload: {}", e),
            PairingError::JsonDecodeError(e) => write!(f, "Failed to parse JSON payload: {}", e),
            PairingError::UnsupportedVersion(v) => write!(f, "Unsupported payload version {}, expected 1", v),
            PairingError::InvalidPayloadType(t) => write!(f, "Invalid payload type '{}', expected 'hermes-pair'", t),
            PairingError::InvalidHostId(id) => write!(f, "Invalid host UUID: '{}'", id),
            PairingError::EmptyHost => write!(f, "Host address cannot be empty"),
            PairingError::InvalidPort(p) => write!(f, "Invalid port number: {}", p),
            PairingError::PayloadExpired { expires_at, now } => {
                write!(f, "Pairing payload expired at timestamp {} (current time: {})", expires_at, now)
            }
        }
    }
 }
 impl std::error::Error for PairingError {}
 pub fn current_unix_timestamp() -> u64 {
    SystemTime::now()
        .duration_since(UNIX_EPOCH)
        .unwrap_or_default()
        .as_secs()
 }
 pub fn generate_nonce() -> String {
    let mut bytes = [0u8; 16];
    rand::thread_rng().fill_bytes(&mut bytes);
    URL_SAFE_NO_PAD.encode(bytes)
 }
 pub fn create_pairing_payload(
    host_id: String,
    name: String,
    host: String,
    port: u16,
    scheme: String,
    ttl_seconds: u64,
 ) -> PairingPayloadV1 {
    let now = current_unix_timestamp();
    let expires_at = now + ttl_seconds;
    let nonce = generate_nonce();
    PairingPayloadV1 {
        v: 1,
        payload_type: "hermes-pair".to_string(),
        host_id,
        name,
        host,
        port,
        scheme,
        expires_at,
        nonce,
    }
 }
 pub fn encode_pairing_uri(payload: &PairingPayloadV1) -> String {
    let json = serde_json::to_string(payload).expect("Serialization of PairingPayloadV1 should never fail");
    let encoded = URL_SAFE_NO_PAD.encode(json.as_bytes());
    format!("hermes://pair?data={}", encoded)
 }
 pub fn decode_pairing_uri_at_time(uri: &str, current_time: u64) -> Result<PairingPayloadV1, PairingError> {
    let data_str = if let Ok(url) = Url::parse(uri) {
        if url.scheme() != "hermes" {
            return Err(PairingError::InvalidUriScheme(url.scheme().to_string()));
        }
        let host = url.host_str().unwrap_or_default();
        if host != "pair" && url.path() != "pair" && url.path() != "/pair" {
            return Err(PairingError::InvalidUriFormat(uri.to_string()));
        }
        url.query_pairs()
            .find(|(k, _)| k == "data")
            .map(|(_, v)| v.into_owned())
            .ok_or(PairingError::MissingDataParameter)?
    } else {
        // Fallback simple parsing for custom hermes:// URIs
        if !uri.starts_with("hermes://") && !uri.starts_with("hermes:") {
            return Err(PairingError::InvalidUriScheme("unknown".to_string()));
        }
        let query_part = uri.split_once('?').map(|x| x.1).ok_or(PairingError::MissingDataParameter)?;
        let mut found = None;
        for pair in query_part.split('&') {
            if let Some((k, v)) = pair.split_once('=') {
                if k == "data" {
                    found = Some(v.to_string());
                    break;
                }
            }
        }
        found.ok_or(PairingError::MissingDataParameter)?
    };
    // Decode Base64 (supporting URL_SAFE_NO_PAD, URL_SAFE, and STANDARD)
    let decoded_bytes = URL_SAFE_NO_PAD
        .decode(data_str.as_bytes())
        .or_else(|_| URL_SAFE.decode(data_str.as_bytes()))
        .or_else(|_| STANDARD.decode(data_str.as_bytes()))
        .map_err(|e| PairingError::Base64DecodeError(e.to_string()))?;
    let payload: PairingPayloadV1 = serde_json::from_slice(&decoded_bytes)
        .map_err(|e| PairingError::JsonDecodeError(e.to_string()))?;
    // Validations
    if payload.v != 1 {
        return Err(PairingError::UnsupportedVersion(payload.v));
    }
    if payload.payload_type != "hermes-pair" {
        return Err(PairingError::InvalidPayloadType(payload.payload_type));
    }
    if Uuid::parse_str(&payload.host_id).is_err() {
        return Err(PairingError::InvalidHostId(payload.host_id));
    }
    if payload.host.trim().is_empty() {
        return Err(PairingError::EmptyHost);
    }
    if payload.port == 0 {
        return Err(PairingError::InvalidPort(payload.port));
    }
    if payload.expires_at <= current_time {
        return Err(PairingError::PayloadExpired {
            expires_at: payload.expires_at,
            now: current_time,
        });
    }
    Ok(payload)
 }
 pub fn decode_pairing_uri(uri: &str) -> Result<PairingPayloadV1, PairingError> {
    let now = current_unix_timestamp();
    decode_pairing_uri_at_time(uri, now)
 }
--- a/src/qr.rs
+++ b/src/qr.rs
@ -0,0 +1,102 @@
 use eframe::egui::{Color32, ColorImage};
 use qrcode::{Color, QrCode};
 pub type QrError = qrcode::types::QrError;
 /// Generates a 2D boolean matrix of QR modules (true = dark, false = light) including a quiet zone.
 pub fn generate_qr_matrix(data: &str) -> Result<Vec<Vec<bool>>, QrError> {
    let code = QrCode::new(data.as_bytes())?;
    let colors = code.to_colors();
    let width = code.width();
    let quiet_zone = 2;
    let total_size = width + quiet_zone * 2;
    let mut matrix = vec![vec![false; total_size]; total_size];
    for y in 0..width {
        for x in 0..width {
            let is_dark = colors[y * width + x] == Color::Dark;
            matrix[y + quiet_zone][x + quiet_zone] = is_dark;
        }
    }
    Ok(matrix)
 }
 /// Renders a terminal-friendly QR code using Unicode full blocks and ANSI colors.
 pub fn render_terminal_qr(data: &str) -> Result<String, QrError> {
    let code = QrCode::new(data.as_bytes())?;
    let colors = code.to_colors();
    let width = code.width();
    let quiet_zone = 2;
    let total_size = width + quiet_zone * 2;
    let mut out = String::new();
    // Render using ANSI inverted / double-width blocks for standard aspect ratio
    // Dark modules: "██", Light modules: "  "
    for y in 0..total_size {
        for x in 0..total_size {
            let is_dark = if x >= quiet_zone && x < quiet_zone + width && y >= quiet_zone && y < quiet_zone + width {
                let qx = x - quiet_zone;
                let qy = y - quiet_zone;
                colors[qy * width + qx] == Color::Dark
            } else {
                false
            };
            if is_dark {
                out.push_str("██");
            } else {
                out.push_str("  ");
            }
        }
        out.push('\n');
    }
    Ok(out)
 }
 /// Renders a high-contrast ColorImage for egui rendering with a quiet zone and configurable scale.
 pub fn render_egui_image(data: &str, scale: usize) -> Result<ColorImage, QrError> {
    let code = QrCode::new(data.as_bytes())?;
    let colors = code.to_colors();
    let width = code.width();
    let quiet_zone = 3;
    let total_modules = width + quiet_zone * 2;
    let scale = scale.max(1);
    let image_width = total_modules * scale;
    let image_height = total_modules * scale;
    let mut pixels = Vec::with_capacity(image_width * image_height);
    for my in 0..total_modules {
        for _sy in 0..scale {
            for mx in 0..total_modules {
                let is_dark = if mx >= quiet_zone && mx < quiet_zone + width && my >= quiet_zone && my < quiet_zone + width {
                    let qx = mx - quiet_zone;
                    let qy = my - quiet_zone;
                    colors[qy * width + qx] == Color::Dark
                } else {
                    false
                };
                let color = if is_dark {
                    Color32::from_rgb(18, 18, 20)
                } else {
                    Color32::from_rgb(255, 255, 255)
                };
                for _sx in 0..scale {
                    pixels.push(color);
                }
            }
        }
    }
    Ok(ColorImage {
        size: [image_width, image_height],
        pixels,
    })
 }
--- a/tests/unit_and_contract_tests.rs
+++ b/tests/unit_and_contract_tests.rs
@ -0,0 +1,257 @@
 use base64::engine::general_purpose::URL_SAFE_NO_PAD;
 use base64::Engine;
 use hermes_pair::config::load_or_create_config_from_path;
 use hermes_pair::hermes::HermesProbeClient;
 use hermes_pair::models::{NetworkInterfaceInfo, PairingPayloadV1};
 use hermes_pair::network::filter_and_sort_interfaces;
 use hermes_pair::pairing::{
    create_pairing_payload, decode_pairing_uri, decode_pairing_uri_at_time, encode_pairing_uri,
    PairingError,
 };
 use std::net::Ipv4Addr;
 use std::path::PathBuf;
 use tokio::io::{AsyncReadExt, AsyncWriteExt};
 use tokio::net::TcpListener;
 use uuid::Uuid;
 #[test]
 fn test_config_persistence() {
    let tmp_dir = std::env::temp_dir();
    let config_path: PathBuf = tmp_dir.join(format!("hermes_test_config_{}.json", Uuid::new_v4()));
    // Ensure clean state
    let _ = std::fs::remove_file(&config_path);
    // First load -> generates new config and persists it
    let config1 = load_or_create_config_from_path(&config_path).expect("Should create new config");
    assert!(!config1.host_id.is_empty());
    assert!(Uuid::parse_str(&config1.host_id).is_ok());
    // Second load -> loads existing config and keeps same host_id
    let config2 = load_or_create_config_from_path(&config_path).expect("Should load existing config");
    assert_eq!(config1.host_id, config2.host_id);
    // Clean up
    let _ = std::fs::remove_file(&config_path);
 }
 #[test]
 fn test_pairing_payload_serde() {
    let host_id = Uuid::new_v4().to_string();
    let payload = PairingPayloadV1 {
        v: 1,
        payload_type: "hermes-pair".to_string(),
        host_id: host_id.clone(),
        name: "Test-Rig".to_string(),
        host: "192.168.1.100".to_string(),
        port: 9119,
        scheme: "http".to_string(),
        expires_at: 1800000000,
        nonce: "test_nonce_1234".to_string(),
    };
    let json = serde_json::to_string(&payload).expect("Serialization failed");
    let deserialized: PairingPayloadV1 = serde_json::from_str(&json).expect("Deserialization failed");
    assert_eq!(payload, deserialized);
    // Verify Base64URL round-trip
    let b64 = URL_SAFE_NO_PAD.encode(json.as_bytes());
    let decoded_bytes = URL_SAFE_NO_PAD.decode(b64.as_bytes()).expect("B64 decode failed");
    let from_b64: PairingPayloadV1 = serde_json::from_slice(&decoded_bytes).expect("JSON from b64 failed");
    assert_eq!(payload, from_b64);
 }
 #[test]
 fn test_pairing_uri_encoding_and_validation() {
    let host_id = Uuid::new_v4().to_string();
    let payload = create_pairing_payload(
        host_id.clone(),
        "Studio-PC".to_string(),
        "192.168.0.50".to_string(),
        9119,
        "http".to_string(),
        300,
    );
    let uri = encode_pairing_uri(&payload);
    assert!(uri.starts_with("hermes://pair?data="));
    let decoded = decode_pairing_uri(&uri).expect("Decoding valid pairing URI must succeed");
    assert_eq!(decoded.v, 1);
    assert_eq!(decoded.payload_type, "hermes-pair");
    assert_eq!(decoded.host_id, host_id);
    assert_eq!(decoded.name, "Studio-PC");
    assert_eq!(decoded.host, "192.168.0.50");
    assert_eq!(decoded.port, 9119);
    assert_eq!(decoded.scheme, "http");
 }
 #[test]
 fn test_expired_payload_rejection() {
    let host_id = Uuid::new_v4().to_string();
    let payload = PairingPayloadV1 {
        v: 1,
        payload_type: "hermes-pair".to_string(),
        host_id,
        name: "Old-Node".to_string(),
        host: "10.0.0.5".to_string(),
        port: 9119,
        scheme: "http".to_string(),
        expires_at: 1000,
        nonce: "test_nonce".to_string(),
    };
    let uri = encode_pairing_uri(&payload);
    let result = decode_pairing_uri_at_time(&uri, 2000);
    match result {
        Err(PairingError::PayloadExpired { expires_at, now }) => {
            assert_eq!(expires_at, 1000);
            assert_eq!(now, 2000);
        }
        other => panic!("Expected PayloadExpired error, got {:?}", other),
    }
 }
 #[test]
 fn test_invalid_version_rejection() {
    let host_id = Uuid::new_v4().to_string();
    let payload = PairingPayloadV1 {
        v: 2, // Unsupported version
        payload_type: "hermes-pair".to_string(),
        host_id,
        name: "Future-Node".to_string(),
        host: "10.0.0.5".to_string(),
        port: 9119,
        scheme: "http".to_string(),
        expires_at: 3000000000,
        nonce: "test_nonce".to_string(),
    };
    let uri = encode_pairing_uri(&payload);
    let result = decode_pairing_uri_at_time(&uri, 10000);
    match result {
        Err(PairingError::UnsupportedVersion(v)) => {
            assert_eq!(v, 2);
        }
        other => panic!("Expected UnsupportedVersion error, got {:?}", other),
    }
 }
 #[test]
 fn test_invalid_port_rejection() {
    let host_id = Uuid::new_v4().to_string();
    let payload = PairingPayloadV1 {
        v: 1,
        payload_type: "hermes-pair".to_string(),
        host_id,
        name: "Invalid-Port-Node".to_string(),
        host: "192.168.1.1".to_string(),
        port: 0, // Port 0 is invalid
        scheme: "http".to_string(),
        expires_at: 3000000000,
        nonce: "test_nonce".to_string(),
    };
    let uri = encode_pairing_uri(&payload);
    let result = decode_pairing_uri_at_time(&uri, 10000);
    match result {
        Err(PairingError::InvalidPort(p)) => {
            assert_eq!(p, 0);
        }
        other => panic!("Expected InvalidPort error, got {:?}", other),
    }
 }
 #[test]
 fn test_network_interface_filtering() {
    let test_interfaces = vec![
        NetworkInterfaceInfo {
            name: "lo".to_string(),
            ip: Ipv4Addr::new(127, 0, 0, 1),
            is_loopback: true,
            is_virtual: false,
        },
        NetworkInterfaceInfo {
            name: "link-local".to_string(),
            ip: Ipv4Addr::new(169, 254, 10, 20),
            is_loopback: false,
            is_virtual: false,
        },
        NetworkInterfaceInfo {
            name: "docker0".to_string(),
            ip: Ipv4Addr::new(172, 17, 0, 1),
            is_loopback: false,
            is_virtual: true,
        },
        NetworkInterfaceInfo {
            name: "tailscale0".to_string(),
            ip: Ipv4Addr::new(100, 80, 5, 6),
            is_loopback: false,
            is_virtual: false,
        },
        NetworkInterfaceInfo {
            name: "eth0".to_string(),
            ip: Ipv4Addr::new(192, 168, 1, 10),
            is_loopback: false,
            is_virtual: false,
        },
    ];
    let sorted = filter_and_sort_interfaces(test_interfaces);
    // Loopback and link-local must be eliminated
    assert!(!sorted.iter().any(|i| i.is_loopback || i.ip == Ipv4Addr::new(127, 0, 0, 1)));
    assert!(!sorted.iter().any(|i| i.ip == Ipv4Addr::new(169, 254, 10, 20)));
    // Order: Physical LAN (eth0 192.168.1.10) -> Tailscale (100.80.5.6) -> Virtual LAN (docker0 172.17.0.1)
    assert_eq!(sorted.len(), 3);
    assert_eq!(sorted[0].name, "eth0");
    assert_eq!(sorted[1].name, "tailscale0");
    assert_eq!(sorted[2].name, "docker0");
 }
 #[tokio::test]
 async fn test_mock_hermes_probe() {
    let listener = TcpListener::bind("127.0.0.1:0").await.expect("Failed to bind mock listener");
    let port = listener.local_addr().unwrap().port();
    let server_task = tokio::spawn(async move {
        if let Ok((mut socket, _)) = listener.accept().await {
            let mut buf = [0u8; 1024];
            let _ = socket.read(&mut buf).await;
            let response_body = serde_json::json!({
                "status": "running",
                "authRequired": true,
                "authProviders": ["bearer", "oauth2"],
                "authFlows": ["token"],
                "version": "1.2.0"
            })
            .to_string();
            let response = format!(
                "HTTP/1.1 200 OK\r\nContent-Type: application/json\r\nContent-Length: {}\r\nConnection: close\r\n\r\n{}",
                response_body.len(),
                response_body
            );
            let _ = socket.write_all(response.as_bytes()).await;
        }
    });
    let client = HermesProbeClient::new();
    let base_url = format!("http://127.0.0.1:{}", port);
    let status_res = client.fetch_status(&base_url).await;
    assert!(status_res.is_ok(), "Probe should succeed against mock server");
    let status = status_res.unwrap();
    assert_eq!(status.status, "running");
    assert!(status.auth_required);
    assert_eq!(status.auth_providers, vec!["bearer".to_string(), "oauth2".to_string()]);
    assert_eq!(status.auth_flows, vec!["token".to_string()]);
    assert_eq!(status.version, Some("1.2.0".to_string()));
    let _ = server_task.await;
 }