- commit
- dbf8e485bf330405a8bafa56b313514ee438b892
- parent
- 86a73fd79ade9de2918e7123d32d288f9bd3da13
- author
- Dami <dami.etoile@gmail.com>
| D | openspec/ | 57 | ------------------------------ |
| D | openspec/ | 50 | -------------------------- |
| D | openspec/ | 34 | ------------------ |
| D | openspec/ | 34 | ------------------ |
| D | openspec/ | 0 | |
| D | openspec/ | 32 | ----------------- |
| D | openspec/ | 39 | --------------------- |
| D | openspec/ | 38 | -------------------- |
| D | openspec/ | 53 | ---------------------------- |
@@ -1,57 +0,0 @@
1-# Design: Viability-testing MVP2-3-## Architecture decision4-5-Use Tauri as a thin UI shell and put all risky integrations in Rust. The UI should call explicit commands such as `detect_yubikey`, `authenticate_token`, `load_pairing`, `connect_host`, `start_remote_control`, and `disconnect`.6-7-## YubiKey investigation plan8-9-Test modes in this order unless early evidence changes the ranking:10-11-1. HMAC-SHA1 challenge-response: attractive for deterministic secret derivation, but may have tooling and setup constraints.12-2. PIV: strong private-key boundary and mature tooling, but less direct for storing arbitrary peer data.13-3. CTAP2/FIDO2 extensions: useful if native support provides better cross-platform behavior than browser WebAuthn PRF, but API maturity must be verified.14-15-The MVP should not assume the final token mode until the spike proves:16-17-- user-presence/PIN behavior,18-- crate availability and maintenance,19-- OS permission requirements,20-- ability to store, read, derive, or unlock pairing material,21-- failure behavior when the token is absent or wrong.22-23-## Pairing material model24-25-Candidate model:26-27-- Remote host identity: stored as a small token-readable blob or token-unlocked local encrypted blob.28-- Client authentication identity: derived from challenge-response or backed by a token private key.29-- Local cache: allowed only for non-secret metadata unless a spec change explicitly permits encrypted caching.30-31-If YubiKey storage proves too constrained, the fallback is a local encrypted pairing file whose decrypting key is token-derived.32-33-## Iroh protocol model34-35-Start with one custom ALPN/protocol for diagnostics, then split streams as needed:36-37-- auth/handshake,38-- control events,39-- frame transport,40-- diagnostics/logs.41-42-The host must verify that the connecting client presents the expected token-bound identity, not merely that it knows a node ID.43-44-## Remote-control spike model45-46-Do not start with perfect remote desktop. Start with the smallest loop that proves the integration boundary:47-48-1. Host sends synthetic frames or a captured low-resolution screen frame stream.49-2. Client renders frames in the Tauri webview.50-3. Client sends pointer/keyboard events.51-4. Host logs or applies input events depending on OS permissions.52-53-Then replace synthetic/capture/log paths with real capture and injection one OS at a time.54-55-## Evidence artifacts56-57-Create `docs/evidence/` entries during implementation. Each entry should include commands run, platform, crate versions, result, and exact blockers.@@ -1,50 +0,0 @@
1-# Change: Validate Tauri + YubiKey + Iroh MVP2-3-## Summary4-5-Create the first evidence-producing MVP path for Keyhome: a native Tauri app authenticates with a YubiKey, obtains or unlocks pairing material, starts a native Iroh endpoint, dials a host agent, and proves a minimal remote-control loop.6-7-## Motivation8-9-The architecture is plausible but has four hard risks that must be tested before product build-out:10-11-1. Native YubiKey APIs differ by mode, OS, permissions, and crate maturity.12-2. Storing or deriving Iroh identity/addressing material from a YubiKey may require a different token mode than the original idea assumes.13-3. Iroh's native Rust stack is likely suitable, but the protocol binding and identity story need a concrete spike.14-4. Remote desktop capture/input injection is OS-permission-heavy and may dominate MVP complexity.15-16-## Scope17-18-This change plans the MVP viability work. It does not require polished UI or production security hardening.19-20-In scope:21-22-- Tauri app scaffold with Rust commands for auth/connect diagnostics.23-- YubiKey mode comparison spike: HMAC-SHA1 challenge-response, PIV, and/or CTAP2 where practical.24-- Pairing-data design for host node identity and client authentication material.25-- Native Iroh client and host-agent connectivity proof.26-- Minimal remote-control proof: frame stream plus pointer/keyboard event path, even if initially local-only.27-- Evidence log documenting supported platforms, crate choices, blockers, and latency observations.28-29-Out of scope:30-31-- SaaS account model.32-- Production pairing ceremony UX.33-- Installer signing, auto-update, and full permission onboarding.34-- Multi-host management beyond one paired host.35-36-## Dependencies37-38-- Baseline specs: `yubikey-identity`, `iroh-session`, `remote-control`.39-- Hardware: at least one YubiKey with the modes being tested.40-- Host OS permissions for capture/input injection.41-42-## Success criteria43-44-The MVP is viable if it can demonstrate, on at least one developer machine pair or loopback setup:45-46-1. YubiKey-gated auth succeeds through the Tauri backend.47-2. Pairing material is read, derived, or unlocked only after the verification step.48-3. Iroh client and host establish an authenticated protocol channel.49-4. The client renders host frames and sends input events over that channel.50-5. The repo contains exact commands and evidence for what worked and what failed.@@ -1,34 +0,0 @@
1-## ADDED Requirements2-3-### Requirement: Evidence-producing MVP workflow4-The system SHALL provide a viability workflow that records whether each high-risk integration works under real execution.5-6-#### Scenario: Spike succeeds7-- **GIVEN** a viability spike is run8-- **WHEN** the spike demonstrates the intended behavior9-- **THEN** the result is recorded with platform, command, dependency versions, and observed output.10-11-#### Scenario: Spike fails12-- **GIVEN** a viability spike is run13-- **WHEN** the spike fails or is blocked14-- **THEN** the blocker is recorded with exact error output15-- **AND** the next proposed alternative is documented.16-17-### Requirement: Minimal end-to-end remote-control proof18-The system SHALL define a minimal end-to-end proof that starts after YubiKey verification and ends with rendered frames plus forwarded input over Iroh.19-20-#### Scenario: End-to-end proof runs21-- **GIVEN** a supported YubiKey and paired host agent are available22-- **WHEN** the user authenticates and starts the MVP session23-- **THEN** the client establishes an authenticated Iroh channel24-- **AND** renders host-provided frames25-- **AND** forwards at least one pointer or keyboard event to the host.26-27-### Requirement: Viability gate decision28-The system SHALL produce a review decision after the MVP spikes complete.29-30-#### Scenario: Review gate is reached31-- **GIVEN** hardware auth, Iroh, and remote-control spikes have recorded evidence32-- **WHEN** the MVP review is performed33-- **THEN** the project records whether to proceed, pivot the token/auth mode, or stop34-- **AND** identifies the highest remaining technical risk.@@ -1,34 +0,0 @@
1-# Tasks2-3-## 1. Research and spike setup4-5-- [x] 1.1 Compare Rust YubiKey/CTAP/PIV crates and document candidate APIs.6-- [x] 1.2 Scaffold minimal Tauri app with backend commands and a diagnostics UI.7-- [x] 1.3 Add an evidence log template under `docs/evidence/`.8-9-## 2. Hardware authentication viability10-11-- [x] 2.1 Implement token detection spike.12-- [x] 2.2 Implement one verification path requiring touch or PIN.13-- [x] 2.3 Prove pairing material can be read, derived, or unlocked after verification.14-- [x] 2.4 Document failed token modes with exact errors and OS requirements.15-16-## 3. Iroh viability17-18-- [x] 3.1 Implement native Iroh endpoint creation in the backend.19-- [x] 3.2 Implement a minimal host agent with a stable node identity.20-- [x] 3.3 Dial the host from authenticated pairing material.21-- [x] 3.4 Add a diagnostic request/response protocol over the Iroh channel.22-23-## 4. Remote-control viability24-25-- [x] 4.1 Stream synthetic or captured frames from host to client.26-- [x] 4.2 Render frames in the Tauri UI.27-- [x] 4.3 Send pointer and keyboard events from client to host.28-- [ ] 4.4 Measure rough latency and CPU for the MVP path.29-30-## 5. Review gate31-32-- [x] 5.1 Update OpenSpec tasks and evidence docs with actual results.33-- [x] 5.2 Decide whether the MVP should proceed, pivot token mode, or stop.34-- [x] 5.3 Validate OpenSpec artifacts with `openspec validate --all --strict`.No content changes.
@@ -1,32 +0,0 @@
1-# Project: Keyhome2-3-## Purpose4-5-Keyhome explores a hardware-key-gated remote-control app for reaching a user's own machine. The intended user flow is: launch native app, plug in YubiKey, tap or enter PIN if required, read/derive the remote identity from the token, connect over Iroh, and control the remote desktop.6-7-## Scope8-9-In scope:10-11-- Tauri client with Rust backend.12-- Native YubiKey integration.13-- Native Iroh node and authenticated peer protocol.14-- Host agent needed for screen capture and input injection.15-- MVP viability spikes and measurements.16-17-Out of scope for the initial MVP:18-19-- Browser-only WebAuthn PRF implementation.20-- Multi-user SaaS account management.21-- Polished installers and auto-update infrastructure.22-- Enterprise device management.23-24-## Requirements style25-26-- Specs define observable behavior.27-- Change specs use delta headers.28-- MVP work must include evidence-producing tasks, not only scaffolding.29-30-## Current priority31-32-Plan and validate the first viability-testing MVP before implementation.@@ -1,39 +0,0 @@
1-# Iroh Session2-3-## Purpose4-5-Define Keyhome's peer-to-peer session establishment over native Iroh after hardware-backed local authentication.6-7-## Requirements8-9-### Requirement: Native Iroh endpoint10-The system SHALL run a native Iroh endpoint in the Rust backend rather than routing the MVP session through browser networking APIs.11-12-#### Scenario: Client starts networking13-- **GIVEN** hardware authentication has succeeded14-- **WHEN** the backend prepares a connection15-- **THEN** it initializes a native Iroh endpoint16-- **AND** exposes connection progress to the UI.17-18-### Requirement: Authenticated host dialing19-The system SHALL dial only the host identity obtained from the authenticated pairing material.20-21-#### Scenario: Paired host is dialed22-- **GIVEN** authenticated pairing material contains a remote host identifier23-- **WHEN** the user connects24-- **THEN** the backend dials that host over Iroh25-- **AND** binds the session to the authenticated client identity.26-27-#### Scenario: Host identity mismatch28-- **GIVEN** the backend receives a response from a peer whose identity does not match the pairing material29-- **WHEN** session establishment is evaluated30-- **THEN** the backend rejects the session31-- **AND** the UI reports an authentication or pairing mismatch.32-33-### Requirement: Protocol separation34-The system SHALL use an application protocol that separates authentication, control input, video frames, and diagnostics well enough to test each path independently.35-36-#### Scenario: Diagnostics without remote control37-- **GIVEN** the client has authenticated to the host38-- **WHEN** the user runs a connectivity diagnostic39-- **THEN** the system can verify Iroh reachability and protocol negotiation without starting desktop streaming.@@ -1,38 +0,0 @@
1-# Remote Control2-3-## Purpose4-5-Define the observable behavior for controlling a paired host after Keyhome establishes an authenticated Iroh session.6-7-## Requirements8-9-### Requirement: Host-mediated screen stream10-The system SHALL receive desktop frames from a host agent over the authenticated session.11-12-#### Scenario: Stream starts13-- **GIVEN** the client has an authenticated session to the host agent14-- **WHEN** remote control starts15-- **THEN** the host agent sends desktop frames16-- **AND** the client renders the stream in the app UI.17-18-### Requirement: Input forwarding19-The system SHALL forward keyboard and pointer input from the client UI to the host agent only while a remote-control session is active.20-21-#### Scenario: Pointer input during active session22-- **GIVEN** a remote-control session is active23-- **WHEN** the user moves or clicks inside the remote-control surface24-- **THEN** the client forwards normalized pointer events to the host agent.25-26-#### Scenario: Input after disconnect27-- **GIVEN** a remote-control session has ended28-- **WHEN** the user types or clicks in the client UI29-- **THEN** no remote input events are sent to the host.30-31-### Requirement: Local safety controls32-The system SHALL provide visible session state and a local disconnect control during remote control.33-34-#### Scenario: User disconnects35-- **GIVEN** a remote-control session is active36-- **WHEN** the user activates disconnect37-- **THEN** the client terminates the remote-control protocol streams38-- **AND** the UI returns to a non-controlling state.@@ -1,53 +0,0 @@
1-# YubiKey Identity2-3-## Purpose4-5-Define how Keyhome uses a YubiKey as the local hardware authority for unlocking remote-control access and retrieving or deriving connection identity material.6-7-## Requirements8-9-### Requirement: Hardware presence gate10-The system SHALL require a supported YubiKey to be present before initiating a protected remote-control session.11-12-#### Scenario: No token is present13-- **GIVEN** the Keyhome client is open14-- **AND** no supported YubiKey is available to the backend15-- **WHEN** the user attempts to connect16-- **THEN** the client reports that hardware authentication is required17-- **AND** no Iroh session is dialed.18-19-#### Scenario: Token is inserted20-- **GIVEN** the Keyhome client is waiting for hardware authentication21-- **WHEN** a supported YubiKey becomes available22-- **THEN** the backend detects the token23-- **AND** the UI can prompt the user for the next required action.24-25-### Requirement: User-presence or PIN verification26-The system SHALL require the YubiKey flow's configured verification step before releasing any session-unlocking result.27-28-#### Scenario: Touch is required29-- **GIVEN** the selected YubiKey mode requires touch30-- **WHEN** the backend starts authentication31-- **THEN** the user is prompted to touch the token32-- **AND** the session-unlocking result is unavailable until the touch succeeds.33-34-#### Scenario: PIN is required35-- **GIVEN** the selected YubiKey mode requires a PIN36-- **WHEN** the backend starts authentication37-- **THEN** the UI requests the PIN through a local prompt38-- **AND** the backend does not persist the PIN after the attempt.39-40-### Requirement: Token-bound connection material41-The system SHALL obtain the remote peer addressing and client authentication material from token-bound data or from data decryptable only after successful token verification.42-43-#### Scenario: Paired machine data exists44-- **GIVEN** the YubiKey contains or unlocks pairing data for a host machine45-- **WHEN** hardware authentication succeeds46-- **THEN** the backend obtains the remote Iroh node identifier or equivalent dial material47-- **AND** obtains client-side session identity material needed to authenticate to that host.48-49-#### Scenario: Pairing data is missing50-- **GIVEN** the YubiKey does not contain or unlock host pairing data51-- **WHEN** hardware authentication succeeds52-- **THEN** the client reports that setup is required53-- **AND** no remote-control session is attempted.