wayray/docs/ai/adr/013-smartphone-proximity-token.md

ADR-013: Smartphone as Proximity Token

Status

Accepted

Context

SunRay's session mobility was driven by smart card insertion/removal. WayRay supports pluggable tokens (ADR-004). A smartphone is the one device users always carry. If the phone can act as a proximity token, we get automatic session follow without any explicit action -- walk up to a terminal, your desktop appears; walk away, it suspends.

This maps directly to SunRay's smart card semantics:

• Smart card insert → phone enters proximity range
• Smart card remove → phone leaves proximity range

But better: no physical insertion, works from your pocket.

Technology Options

BLE (Bluetooth Low Energy) -- Recommended

The phone runs a small companion app that broadcasts a BLE advertisement containing a session token. The WayRay client has a BLE receiver that detects nearby phones.

How BLE beacons work:

• Phone advertises a BLE beacon with a service UUID specific to WayRay
• The advertisement payload contains an encrypted session token (≤31 bytes in legacy advertising, ≤255 bytes in extended)
• The client scans for WayRay beacons and reads the token
• RSSI (signal strength) determines proximity -- configurable threshold
• When RSSI drops below threshold (user walked away), trigger disconnect

Advantages:

• Always-on: phone advertises in background, no user action needed
• Works from pocket (no need to pull phone out)
• Range tunable via RSSI threshold (1-10 meters typical)
• Low power: BLE advertising uses ~1-5% battery per day
• Universal: every modern smartphone has BLE
• Works through walls at close range (meeting rooms)

BLE Token Flow:

Phone (companion app):
  1. User authenticates in app once (OIDC, biometric, etc.)
  2. App receives signed session token from IdP/server
  3. App begins BLE advertising:
     Service UUID: WayRay-specific
     Payload: encrypted(token_id + timestamp + HMAC)
  4. Rotates payload periodically (replay prevention)

WayRay Client (BLE scanner):
  1. Continuously scans for WayRay service UUID
  2. Detects beacon → reads token → validates HMAC + timestamp
  3. If new token in range: trigger session attach
  4. If token leaves range (RSSI below threshold for N seconds):
     trigger session detach
  5. If multiple tokens: nearest (highest RSSI) wins

NFC -- Complementary (and Charging Pad Mode)

Phone tap on NFC reader for explicit authentication:

• Quick deliberate action (tap to connect)
• Works as fallback when BLE is disabled
• Can trigger initial token provisioning
• Very short range (~4cm) -- no proximity tracking, clean binary signal

Wireless charging pad as card reader: In high-security or dense office deployments, the client's NFC reader can be embedded in (or placed next to) a Qi wireless charging pad. The phone on the pad is simultaneously charging and authenticating -- exactly mimicking a smart card in a reader slot. NFC provides the crisp insert/remove semantics (present = attached, lifted = detached) without RSSI ambiguity. The companion app responds to NFC with the session token via HCE (Host Card Emulation on Android) or Core NFC (iOS).

Combined NFC + BLE mode: For deployments that want both:

• NFC: immediate attach when phone placed on pad (desk-distance, deliberate)
• BLE: sustained heartbeat confirming phone is still present (survives brief NFC interrupts)
• NFC absence + BLE absence: detach (phone physically removed from area)

This gives precise control -- some offices want centimeter-range "phone on pad" behavior, others want meter-range "phone in pocket" behavior. Same TokenProvider trait, deployment configuration picks the mode:

# /etc/wayray/token.toml

[proximity]
# "ble" = walk-up proximity (meter range)
# "nfc" = charging pad / tap (centimeter range)
# "ble+nfc" = NFC for attach, BLE for heartbeat
# "ble|nfc" = either can attach independently
mode = "nfc"

[ble]
rssi_threshold = -70    # dBm
attach_delay = 2        # seconds
detach_delay = 10       # seconds

[nfc]
# No thresholds needed -- NFC is binary (present/absent)
detach_delay = 3        # seconds grace period for brief lifts

UWB (Ultra-Wideband) -- Future

Precise distance measurement (10cm accuracy):

• iPhone U1/U2 chip, some Samsung/Google phones
• Could enable "desk assignment" -- know exactly which terminal you're closest to
• Not yet universal enough to depend on
• Consider as enhancement when hardware penetration increases

WiFi Proximity (mDNS) -- Fallback

Phone app announces presence on local network:

• Works without BLE hardware on client
• Coarse proximity (same VLAN/subnet)
• Higher latency (mDNS discovery takes seconds)
• Can't distinguish between terminals in the same room
• Useful as a fallback when BLE isn't available

Decision

BLE as primary proximity mechanism, NFC as explicit-action complement, WiFi/mDNS as software-only fallback.

Proximity State Machine

                          BLE beacon detected
                          (RSSI > threshold)
    [No Phone] ─────────────────────────────────> [Detected]
                                                      │
                                                      │ stable for
                                                      │ T_attach seconds
                                                      v
                    ┌──────────────────────────── [Attached]
                    │                                  │
                    │  BLE beacon returns              │ RSSI < threshold
                    │  (RSSI > threshold)              │ for T_detach seconds
                    │                                  v
                    └──────────────────────────── [Detaching]
                                                      │
                                                      │ timeout expires
                                                      v
                                                 [Detached]
                                                      │
                                                      │ (session suspends)
                                                      v
                                                 [No Phone]

Timers prevent flapping:

• T_attach: delay before attaching (default: 2 seconds). Prevents drive-by session grabs when walking past a terminal.
• T_detach: delay before detaching (default: 10 seconds). Prevents session drop when phone briefly loses signal (body shielding, phone rotates in pocket).
• Both configurable per-deployment.

Security Considerations

Replay attacks: Token payload includes a timestamp and HMAC. Client rejects tokens older than N seconds. Phone rotates payload every 30 seconds.

Relay attacks: An attacker could relay the BLE signal from a distant phone to a nearby client. Mitigations:

• Token payload includes a challenge-response nonce (requires phone app to respond)
• RSSI-based distance bounding (relayed signals have abnormal RSSI patterns)
• Optional: require NFC tap for initial session attachment, BLE only for persistence
• For high-security deployments: disable BLE proximity, use smart card only

Token theft: If someone clones the BLE advertisement, they get the session token. Mitigations:

• Token rotation (new token every 30s, phone signs each one)
• Mutual authentication: client challenges phone via BLE GATT connection
• Binding token to phone's hardware attestation key (Android SafetyNet / iOS DeviceCheck)

Multi-phone scenarios: When multiple phones are near a terminal:

• Highest RSSI wins (closest phone)
• If tie: first-arrived wins
• Explicit NFC tap overrides BLE proximity (deliberate action beats passive detection)

Hardware Requirements

Client side:

• BLE 4.0+ receiver (USB dongle or built-in)
• Optional: NFC reader (USB)
• Commodity hardware: USB BLE dongles cost ~$5-10

Phone side:

• Companion app (Android + iOS)
• BLE 4.0+ (every phone since ~2013)
• Background execution permission for BLE advertising

Implementation as Auth Plugin

struct BleProximityPlugin {
    scanner: BleScanner,
    known_tokens: HashMap<TokenId, ProximityState>,
    rssi_threshold: i8,     // e.g., -70 dBm
    attach_delay: Duration, // e.g., 2 seconds
    detach_delay: Duration, // e.g., 10 seconds
}

impl TokenProvider for BleProximityPlugin {
    fn watch(&self) -> TokenEventStream {
        // Emits:
        // TokenInserted(token_id) -- phone entered proximity
        // TokenRemoved(token_id)  -- phone left proximity
    }
}

This implements the same TokenProvider trait as smart cards (ADR-004). The session management layer doesn't know or care whether the token came from a smart card slot or a BLE beacon.

Companion App Scope

The phone app is intentionally minimal:

1. One-time setup: authenticate with IdP (OIDC), receive signing key
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:      <signature>

Platform:

• Android: foreground service with BLE advertising
• iOS: Core Bluetooth peripheral mode (works in background with limitations)
• Could be a PWA using Web Bluetooth (limited background support)

Rationale

• Zero-friction session mobility: walk up, session appears. Walk away, session suspends. No card to insert, no button to press, no QR to scan.
• Users already carry phones: unlike smart cards which are an additional device to manage and can be forgotten
• Maps to SunRay semantics: insert/remove maps to enter/leave proximity. Same session management, different physical mechanism.
• Pluggable: implements TokenProvider trait. Composable with other token types. Smart card overrides BLE on explicit insertion.
• Tunable security/convenience tradeoff: high security deployments add NFC tap requirement or disable BLE entirely. Casual deployments use pure proximity.

Consequences

• Requires BLE hardware on client devices (USB dongle if not built-in)
• Must develop and maintain companion apps for Android and iOS
• BLE scanning has power implications on battery-powered clients
• RSSI is noisy and affected by environment (walls, bodies, interference). Threshold tuning is deployment-specific.
• iOS background BLE advertising has limitations (Apple throttles frequency)
• Must handle edge cases: phone in adjacent room, phone dies mid-session, multiple phones
• Privacy consideration: BLE beacons are detectable by nearby devices. Token payload must be encrypted so only WayRay clients can read the session token.