- commit
- 735879286de45fdf8689fb8404fab764a258d324
- parent
- 1b0e04dd5052eb712e5fb5a5f88bac6e0cee12c4
- author
- dami etoile <dami.etoile@gmail.com>
| M | README.md | 151 | ++++++++++++++++++------------ |
@@ -1,86 +1,113 @@
11 # keyhome22 3-A native remote desktop app secured by FIDO2 hardware keys. Plug in a Google Titan or YubiKey, tap it, and connect to your home machine over an end-to-end encrypted Iroh tunnel. No passwords, no addresses shared — the key derives the Iroh identity.3+A native remote desktop app secured by FIDO2 hardware keys. Plug in a Google Titan or YubiKey, tap it, and connect to your machine over an end-to-end encrypted Iroh tunnel. No passwords, no addresses — the key derives the identity.44 5-## Status5+## What is it?66 7-Early prototype. Core functionality works (identity derivation, streaming, input). Current frame rate is ~28 fps with ffmpeg+NVENC (was ~1–2 fps with xcap+openh264 software encoding). The bottleneck has moved from host-side encoding to network/relay throughput and client-side decode.7+Keyhome is a Tauri v2 desktop app (Rust backend, vanilla JS frontend) that lets you remote into your machine using a FIDO2 security key as the sole authentication factor. The key produces a `hmac-secret` that becomes the 32-byte seed for an Iroh P2P endpoint. Both host and client derive the same identity from the same key — no address sharing, no passwords, no relay configuration.88 9-Codec and encoder backend are configurable in the info panel — H.264, H.265, and AV1 are all supported, with backends for NVENC, VAAPI, QSV, AMF, VideoToolbox, and software. The frontend uses WebCodecs for hardware-accelerated decode of all three codecs.9+Screen capture and encoding run through an ffmpeg subprocess with hardware acceleration (NVENC, VAAPI, QSV, AMF, VideoToolbox) up to 60fps. The client decodes via WebCodecs with hardware acceleration for H.264, H.265, and AV1. A software fallback (xcap + openh264) is available if ffmpeg isn't installed.1010 11-## How it works11+## Why use it?1212 13-You plug in a FIDO2 security key (Google Titan, YubiKey) and tap it. The key produces a `hmac-secret` that becomes the 32-byte seed for an Iroh `SecretKey`. Both the host and client derive the same Iroh node ID from the same key — no addresses are exchanged, no passwords are stored.13+- **No addresses to share.** The FIDO2 key derives the Iroh peer identity. Both sides get the same node ID from the same key.14+- **End-to-end encrypted.** Iroh handles the transport with built-in E2EE. The key never leaves the hardware token.15+- **Hardware-accelerated video.** ffmpeg handles capture + encode with your GPU. WebCodecs handles decode on the client. Up to 60fps.16+- **Cross-platform.** Linux, macOS, Windows. Auto-detects the best encoder for your hardware.17+- **No cloud, no account.** Peer-to-peer via Iroh relay. No third-party services.18+- **Single binary.** Tauri bundles everything except ffmpeg (system dependency).1419 15-1. **One-time registration.** Tap the key → `hmac-secret` → 32 bytes → OS keyring.16-2. **Host starts.** Read from keyring → Iroh `SecretKey` → `Endpoint`.17-3. **Client connects.** Tap the key → derive the host's node ID → dial via relay.20+## Install1821 19-The connection is end-to-end encrypted by Iroh. The key never leaves the hardware token; only the derived secret is persisted in the OS keyring.22+### Prerequisites2023 21-## Architecture24+- **Rust 1.85+** — [install](https://rustup.rs)25+- **ffmpeg** — screen capture + hardware encoding26+- **FIDO2 security key** — Google Titan or YubiKey2227 28+### Linux (Ubuntu/Debian)29+30+```bash31+sudo apt install -y ffmpeg libwebkit2gtk-4.1-dev build-essential curl wget file \32+ libxdo-dev libssl-dev libayatana-appindicator3-dev librsvg2-dev \33+ libudev-dev libusb-1.0-0-dev pkg-config libwayland-dev libpipewire-0.3-dev libgbm-dev34+35+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh36+source "$HOME/.cargo/env"37+38+git clone https://github.com/FelineStateMachine/keyhome.git39+cd keyhome40+cargo tauri dev41+```42+43+On NVIDIA, set `WEBKIT_DISABLE_DMABUF_RENDERER=1` before running.44+45+### macOS46+47+```bash48+brew install ffmpeg49+cargo install tauri-cli --version "^2"50+git clone https://github.com/FelineStateMachine/keyhome.git51+cd keyhome52+cargo tauri dev2353 ```24-+--------------------------- keyhome (Tauri v2) ---------------------------+25-| |26-| Frontend (vanilla JS, no npm) |27-| - connection state, video canvas, input capture |28-| - WebCodecs decode (H.264/H.265/AV1, hardware-accelerated) |29-| |30-| Tauri IPC |31-| |32-| Rust backend |33-| - FIDO2 CTAP via ctap-hid-fido2 - Screen capture+encode: ffmpeg |34-| - Iroh Endpoint (P2P, relay, E2EE) (NVENC/VAAPI/QSV/AMF/VT) |35-| - OS keyring for identity - Fallback: xcap + openh264 |36-| - Input injection via enigo - Codec: H.264/H.265/AV1 |37-| |38-+----------------------------------+--------------------------------------+39- |40- | Iroh (E2EE, relay-assisted)41- v42-+------------------------------ Host -------------------------------------+43-| - Iroh Endpoint (identity from keyring) |44-| - ffmpeg screen capture → H.264/H.265/AV1 encode (hardware) |45-| - Fallback: xcap capture → openh264 software encode |46-| - enigo mouse/keyboard injection |47-+-------------------------------------------------------------------------+54+55+Grant **Accessibility** and **Screen Recording** permissions in System Settings > Privacy & Security.56+57+### Windows58+59+```powershell60+choco install ffmpeg61+cargo install tauri-cli --version "^2"62+git clone https://github.com/FelineStateMachine/keyhome.git63+cd keyhome64+cargo tauri dev4865 ```4966 50-| Layer | Crate / Tool |67+### Prebuilt binaries68+69+Download from the [releases page](https://github.com/FelineStateMachine/keyhome/releases).70+71+### Usage72+73+1. **Register** (one-time per machine) — click register, tap your key. Creates a resident credential.74+2. **Host** — click host. The app starts listening on an Iroh endpoint derived from your key.75+3. **Connect** — on another machine, click connect, tap the same key. The screen appears, input is forwarded.76+77+Keyboard shortcuts: type your PIN, then press `c` (connect), `r` (register), or `h` (host).78+79+Full setup details: [docs/SETUP.md](docs/SETUP.md)80+81+## Docs82+83+| Document | Description |84+|---|---|85+| [Setup Guide](docs/SETUP.md) | Platform-specific install, dependencies, usage, architecture, protocol |86+| [Architecture](docs/SETUP.md#architecture) | Transport, encoder backends, wire protocol, connection tracking |87+| [Spikes](docs/SETUP.md#spikes-evidence) | Seven viability spikes with pass/fail evidence |88+| [Agent Guide](AGENTS.md) | Development context for AI agents working on the codebase |89+| [FIDO2 HID Evidence](docs/evidence/2026-06-23-ctap-hid-fido2-titan-communication.md) | ctap-hid-fido2 communication with Google Titan |90+| [HMAC → Iroh Derivation](docs/evidence/2026-06-23-hmac-iroh-derivation.md) | Titan hmac-secret → Iroh SecretKey proof |91+| [Iroh Native Ping](docs/evidence/2026-06-23-iroh-native-ping.md) | Iroh connectivity between native endpoints |92+| [YubiKey HMAC Detection](docs/evidence/2026-06-23-yubikey-hmac-detection.md) | YubiKey HMAC-secret detection |93+| [FIDO2 HID vs hidraw](docs/evidence/2026-06-23-fido2-hid-raw-hidraw.md) | HID vs hidraw approach comparison |94+95+## Tech stack96+97+| Layer | Technology |5198 |---|---|5299 | App shell | Tauri v2 |53-| Backend | Rust |54-| P2P transport | Iroh (relay-assisted, end-to-end encrypted) |100+| Backend | Rust (edition 2024) |101+| P2P transport | Iroh 1.0 (relay-assisted, E2EE) |55102 | Hardware auth | FIDO2 CTAP via `ctap-hid-fido2` |56-| Screen capture + encoding | `ffmpeg` subprocess (NVENC/VAAPI/QSV/AMF/VideoToolbox) |57-| Fallback capture + encoding | `xcap` + `openh264` (software) |58-| Video codecs | H.264, H.265, AV1 (configurable) |59-| Client-side decode | WebCodecs (hardware-accelerated, all three codecs) |103+| Capture + encode | ffmpeg subprocess (NVENC/VAAPI/QSV/AMF/VideoToolbox) |104+| Fallback capture | `xcap` + `openh264` (software) |105+| Codecs | H.264, H.265, AV1 (configurable) |106+| Client decode | WebCodecs (hardware-accelerated, all three codecs) |60107 | Input injection | `enigo` |61108 | Identity storage | OS keyring |62109 | Frontend | Vanilla JS (no npm, no build step) |63110 64-## Spikes65-66-Seven spikes were completed as viability evidence. They live in `spikes/`.67-68-| # | Spike | What it proved |69-|---|---|---|70-| 1 | `001-iroh-native-ping` | Iroh connectivity between two native endpoints |71-| 2 | `002-yubikey-hmac-detection` | YubiKey HMAC-Secret detection and invocation |72-| 3 | `003-fido2-hid-enumeration` | FIDO2 HID device enumeration via `ctap-hid-fido2` |73-| 4 | `004-hmac-iroh-derivation` | HMAC-Secret → Iroh `SecretKey` derivation |74-| 5 | `005-frame-stream` | Frame streaming over Iroh |75-| 6 | `006-input-injection` | Mouse/keyboard injection via `enigo` |76-| 7 | `007-titan-no-copy` | Titan key derives identity without copying secrets off-device |77-78-## Requirements79-80-- **OS:** Linux, macOS, or Windows81-- **Hardware:** A FIDO2 security key (Google Titan, YubiKey)82-- **System dependencies:** See [docs/SETUP.md](docs/SETUP.md)83-84111 ## License85112 86113 MIT