From 204c200bc9ce1e165f36b764f6219d7d5b38e85b Mon Sep 17 00:00:00 2001 From: Till Wegmueller Date: Sun, 29 Mar 2026 00:08:34 +0100 Subject: [PATCH] Add direct remote access scenario and token-based server routing When at a friend's or customer's site, the client connects directly to the user's own server over the internet -- no local server involved, no federation needed. The thin client is just a screen + network. - ADR-014: Add scenarios 4b/4c (friend's house, BYOD on-site), server selection UI, three-category taxonomy (direct remote, federation, sandboxing) - ADR-013: BLE beacon payload now includes server address so the phone tells any terminal where to find the user's desktop --- docs/ai/adr/013-smartphone-proximity-token.md | 19 ++++-- .../014-federation-and-foreign-surfaces.md | 68 ++++++++++++++++++- 2 files changed, 82 insertions(+), 5 deletions(-) diff --git a/docs/ai/adr/013-smartphone-proximity-token.md b/docs/ai/adr/013-smartphone-proximity-token.md index 327c60d..f5e0355 100644 --- a/docs/ai/adr/013-smartphone-proximity-token.md +++ b/docs/ai/adr/013-smartphone-proximity-token.md @@ -199,10 +199,21 @@ This implements the same `TokenProvider` trait as smart cards (ADR-004). The ses The phone app is intentionally minimal: 1. One-time setup: authenticate with IdP (OIDC), receive signing key -2. Background service: broadcast BLE beacon with rotating signed token -3. Optional: respond to GATT challenges for mutual auth -4. Optional: show notification when session attaches/detaches -5. No remote desktop functionality -- the phone is a **key**, not a viewer +2. Configure home server address (e.g., `home.wayray.example.com:4433`) +3. Background service: broadcast BLE beacon with rotating signed token +4. Optional: respond to GATT challenges for mutual auth +5. Optional: show notification when session attaches/detaches +6. No remote desktop functionality -- the phone is a **key**, not a viewer + +The BLE beacon payload includes the user's server address alongside the session token. When a WayRay client detects the phone, it knows both WHO the user is AND where their server lives. This enables direct remote access (ADR-014): sit at any terminal anywhere in the world, your phone tells it where to find your desktop. + +``` +BLE Payload (encrypted): + token_id: "abc123" + server: "home.wayray.example.com:4433" + timestamp: 1743206400 + hmac: +``` Platform: - Android: foreground service with BLE advertising diff --git a/docs/ai/adr/014-federation-and-foreign-surfaces.md b/docs/ai/adr/014-federation-and-foreign-surfaces.md index a944dbf..6366e7a 100644 --- a/docs/ai/adr/014-federation-and-foreign-surfaces.md +++ b/docs/ai/adr/014-federation-and-foreign-surfaces.md @@ -21,6 +21,66 @@ Company B publishes specific applications (e.g., an internal tool) that Company **Scenario 4: Cross-server apps within one org** A large organization runs WayRay servers in multiple departments. A user's session is on Server A but they need an app that's only licensed/installed on Server B. That app should appear in their desktop seamlessly. +### The Direct Remote Access Problem + +**Scenario 4b: At a friend's place** +You're at a friend's house. They have a WayRay terminal. You want YOUR desktop from YOUR server (at home, in the cloud, at the office). Your friend's infrastructure is not involved at all -- their terminal is just a screen, keyboard, and network connection. No federation needed, no server-to-server trust. The client connects directly to your server over the internet. + +**Scenario 4c: BYOD at a customer site** +You're working on-site at a customer. You sit at any available terminal (theirs, a shared kiosk, a conference room). You authenticate against your own company's server. Your desktop comes from your server over the internet. The customer's network is just a pipe. + +These are different from federation: no cooperation between servers is required. The WayRay client is truly stateless and server-agnostic -- it can connect to ANY WayRay server the user directs it to. + +#### Direct Remote Flow + +``` +┌──────────────┐ ┌──────────────────┐ +│ Friend's │ Internet / WAN │ Your WayRay │ +│ thin client │─────────────────────────────►│ server (home / │ +│ │ QUIC + TLS 1.3 │ cloud / office) │ +│ Your token │ │ │ +│ authenticates│◄─────────────────────────────│ Your session │ +│ against YOUR │ Display + Audio frames │ resumes │ +│ server │ │ │ +└──────────────┘ └──────────────────┘ + +Friend's WayRay server: not involved at all. +The client just needs network access to your server. +``` + +This requires: +1. **Multi-server client UI**: The greeter/client must let the user choose which server to connect to (not hardcoded to one server) +2. **Token routing**: The user's token (BLE, NFC, software) carries or is associated with a server address +3. **Internet-reachable servers**: The user's WayRay server must be accessible (direct, QUIC NAT traversal, or relay) +4. **No local server involvement**: The friend's/customer's WayRay server is completely bypassed + +#### Server Selection in the Client + +``` +┌─────────────────────────────────────────┐ +│ WayRay Client │ +│ │ +│ Connect to: │ +│ │ +│ ┌─ Recent ──────────────────────────┐ │ +│ │ ★ home.wayray.example.com │ │ +│ │ work.corpx.com │ │ +│ └───────────────────────────────────┘ │ +│ │ +│ ┌─ Local Server ────────────────────┐ │ +│ │ this-office.local (auto-discovered)│ +│ └───────────────────────────────────┘ │ +│ │ +│ ┌─ Custom ──────────────────────────┐ │ +│ │ [server address...............] │ │ +│ └───────────────────────────────────┘ │ +│ │ +│ [Connect] │ +└──────────────────────────────────────────┘ +``` + +Or with token-based routing: the BLE/NFC companion app stores the user's server address alongside the session token. When the phone is detected, the client knows both WHO the user is AND where their server lives. Fully automatic. + ### The Sandboxing Problem Even within a single session, not all apps should be equal: @@ -36,7 +96,13 @@ Multiple users' sessions run on the same server. Each session is isolated in a z ### The Common Thread -All seven scenarios are the same problem at different scales: +These scenarios fall into three categories: + +1. **Direct remote**: Client connects to user's own server, no local server involved (4b, 4c). Simplest -- just needs multi-server client UI and internet reachability. +2. **Federation**: Surfaces from one server appear in a session on another server (1, 2, 3, 4). Requires server-to-server trust. +3. **Sandboxing**: Surfaces from an isolated local environment appear alongside local windows (5, 6, 7). Requires local trust boundaries. + +Categories 2 and 3 share the same underlying mechanism -- foreign surface integration: ``` ┌─────────────────────────────────────────┐