Security & Architecture

1. What runs where

Thumbdesk has three components, each with a specific role:

Host agent

A Rust program you install on your own machine. It runs the terminal sessions, shares the screen when you ask, reads system stats, serves files, and talks to your phone directly. It runs as the user who installed it and makes outbound connections, so you do not need to open inbound ports for remote access. On a Mac it is Thumbdesk.app with a menu-bar item; on Windows and Linux it adds a tray icon.

Mobile app

The iOS and Android app. It holds a per-device Ed25519 key pair, can lock behind Face ID, Touch ID or a fingerprint, and shows the terminal, the screen, files and charts.

Our backend

A coordination server for sign-in, pairing, presence, alerts, lightweight stats and WebRTC signaling. It is also a relay for terminal traffic while WebRTC is starting or unavailable. The protections for each connection mode are described in section 6.

2. Control plane and data plane

The control plane (phone ↔ backend ↔ host, over HTTPS and WSS) carries accounts, pairing, session lifecycle, presence and the WebRTC handshake. The data plane (phone ↔ host, over WebRTC secured with DTLS) carries terminal input and output, screen sharing, file transfers and full live stats. Lightweight background stats also go to the backend, for presence, alerts and history.

Once the handshake completes, WebRTC traffic flows between your phone and your machine over authenticated DTLS, either directly or through a TURN relay that forwards encrypted packets. The server-relay connection mode is described in section 6.

3. Opening a session, step by step

Tapping a host starts a handshake in which both ends verify each other’s long-term Ed25519 keys, the ones pinned at pairing, before the data channel carries anything. The message names below are the real signal types.

In steps 6 to 9, each side signs its SDP, which contains its DTLS certificate fingerprint, with its long-term Ed25519 key, plus a fresh nonce and timestamp, and the other side checks that signature against the key it pinned at pairing. This binds the connection to the paired devices: substituting a certificate causes verification to fail before the WebRTC channel opens.

To open quickly, a terminal can start on the signaling relay and move to the WebRTC channel as soon as it is up. While it is on the relay, the terminal shows an amber SIGNALING badge.

4. Pairing and device identity

Pairing the host agent establishes device trust with a QR code displayed on your machine. You do not need to configure a password or SSH key for this connection.

• The QR carries the host’s public key itself, so your phone pins the host identity from something shown on the machine, not from a field the backend relays. The app marks a host as verified only when its key came from a scanned QR. The claim token in the QR is single-use and expires in minutes.
• Each host keeps its own list of trusted devices, with per-device permissions. A new phone gets access only after it is approved.
• Lost a phone? Revoke it from another signed-in device, or with thumbdesk devices revoke on the host. New connections through the backend are refused as soon as the revocation is saved; a direct channel that was already open closes when the host next syncs its trusted devices, within five minutes by default. Pairings and revocations are written to the audit log.

5. Encryption details

Identity

Long-term Ed25519 key pairs on both ends, one per host and one per phone, pinned against each other at pairing.

Handshake

Every SDP is Ed25519-signed with a fresh nonce and timestamp. The signature covers the DTLS certificate fingerprint, so the transport key is bound to the pinned identity. Stale or replayed handshakes are rejected.

Data plane

WebRTC data channels and media over DTLS, the standard WebRTC transport encryption.

Sealed signaling

File operations and agent chat sent over the signaling connection are sealed with ChaCha20-Poly1305, using a key the phone and host agree with an ephemeral X25519 exchange and HKDF-SHA256. The backend relays them without being able to read them. Terminal frames on the signaling relay are not sealed this way (section 6).

TURN credentials

Short-lived and issued per account. TURN forwards DTLS ciphertext it cannot read.

6. Connection modes

Thumbdesk supports direct WebRTC, TURN-relayed WebRTC and a signaling relay. The available path depends on your network. A terminal can start on the signaling relay while WebRTC connects, then move to WebRTC when it is ready.

TURN keeps end-to-end encryption intact. A TURN server forwards the same DTLS ciphertext. It can observe that two endpoints are talking (addresses, timing, volume) but cannot read terminal bytes, the screen or file contents. The app shows an amber RELAY tag when TURN is in use.

Signaling relay. While WebRTC connects or is unavailable, terminal input and output can travel through our servers over TLS. This path is encrypted in transit, but not end to end: our servers can read terminal traffic while forwarding it. We do not store that traffic. Frames from the phone are Ed25519-signed and replay-checked. The terminal indicates this connection with a SIGNALING badge.

Screen sharing uses direct or TURN-relayed WebRTC only. If the network blocks both paths, screen sharing is unavailable.

Agent chat passes through the relay sealed end to end with current host agents. With an older host agent, messages may use TLS only and be readable by our servers in transit. The app labels these connections “Not end-to-end encrypted”. Updating the host agent enables end-to-end encryption.

Files use WebRTC when available, and file operations over signaling are sealed as described in section 5. If that key exchange fails, the app can use TLS only, and then file paths, folder listings and small file operations could be read by our servers. Large transfers require WebRTC.

7. Data handled by our backend

Account and service records

• Your account email and how you sign in.
• Host metadata: hostname, platform, agent version, online or offline.
• Session lifecycle records (a session between device X and host Y started and ended), never their contents.
• Lightweight stats for presence, alerts and history: CPU, memory, disk, swap, load, network, temperature and OS details, with selected numeric series kept for charts. Process lists, command lines and logged-in users are never part of these.
• The alert rules you set, and push notification tokens.
• Audit events: sign-ins, pairings, device approvals and revocations, behind rate-limited sign-in codes and rotating refresh tokens.
• Byte counts of relayed traffic, never its contents.

The backend also handles app usage and diagnostics as described in the privacy policy. Content processed in transit depends on the connection mode in section 6; terminal input and output are not stored.

Content protected between your devices

• Terminal input and output on direct and TURN paths, including scrollback and command history.
• The shared screen, its sound, and your pointer and keyboard input.
• Large file transfers, which require WebRTC, and file operations sealed between your devices.
• Agent chat with current host agents, sealed end to end even on the relay.
• Process lists, command lines and logged-in users: the live process view streams peer to peer and is never stored by us.

8. SSH hosts

A machine added as a plain SSH host has no Thumbdesk agent. The phone connects to it directly over SSH, so the traffic is SSH’s own encryption between your phone and that server, and our backend is not involved. The address, username, password or private key are stored only on your phone, in its secure storage. The first connection shows the server’s host-key fingerprint for you to compare and pins it; if the key ever changes, the app stops and asks before trusting the new one.

9. Secrets at rest

• On the host: the agent’s Ed25519 private key and long-lived refresh token live in the OS keychain (macOS Keychain, Windows Credential Manager, Linux Secret Service). On headless machines without a keyring they fall back to a file readable only by its owner under ~/.thumbdesk/. Short-lived access tokens sit in state.json, with the same permissions.
• On the phone: device keys and tokens live in the platform’s secure storage (iOS Keychain, Android Keystore), and the app can lock behind biometrics whenever it is opened. A device-key backup can only be exported after biometric authentication, encrypted with a password you choose (AES-256-GCM, Argon2id).
• Host audit log: the agent keeps a local audit trail of sessions, device approvals and sensitive operations, metadata only and never terminal contents, which you can read in the app.

10. Verify what you install

Published checksums and signatures let you verify that an installed binary matches an official release.

• Every release is published with a SHA-256 checksum and a keyless cosign (Sigstore) signature tied to our release workflow. The install script, curl -fsSL https://thumbdesk.com/install.sh | bash, is short and readable: it checks the checksum, and the signature when cosign is installed (it warns you if it is not).
• thumbdesk update verifies the checksum and the cosign signature before it replaces anything, plus Apple’s Developer ID signature on a Mac. The Mac app is notarized by Apple.
• Removing it is one command: thumbdesk uninstall stops the agent, removes the service, revokes its token on our side, and deletes its local state, keys and binaries.

11. Security scope and limitations

These considerations help you choose which devices to trust and how to use Thumbdesk on your network.

• Device permissions. A device approved for shell access operates with your host account’s permissions, including sudo where available and screen control where allowed. Use biometric lock, review trusted devices and revoke access when a device is lost or no longer needed.
• Service availability. Sign-in, pairing and new agent connections require our backend. An outage can prevent new sessions from starting. You retain local access to your machines and can uninstall the agent at any time.
• Network metadata. Relays can observe endpoint addresses, connection times and traffic volume. Content protection varies by connection mode, as explained in section 6.
• Unattended access. An approved device can open sessions without a new confirmation on the host. Access is managed through device approval, biometric lock, revocation and the audit log. The first screen share may also require approval at the machine.
• Security review. The host agent is proprietary software. The design has been reviewed internally; an independent security audit has not yet been commissioned.

12. Reporting a vulnerability

Found something? Email support@thumbdesk.com with “Security” in the subject, and ask for a PGP key in your first message if the report is sensitive. We read every report, reply within five business days, and will credit you in the fix notes if you want. Please give us a reasonable window, typically 90 days, to ship a fix before you publish.