Security
A paired phone with control access can do what you can do at your keyboard, so the bridge is built to let in only the phones you pair, and to keep everything in between unable to read or change what flows. This page summarises our own review; it is not an independent audit.
What protects a connection
- End-to-end TLS pinned to your computer. The bridge makes its own certificate. The phone learns its exact SHA-256 fingerprint from the QR code you scan (or checks it against the computer during nearby pairing) and accepts no other: no certificate authority, no “trust anyway”. Current apps require TLS 1.3.
- A credential per device. Pairing gives each phone a random 256-bit token; the bridge stores only its hash. Each device is read-only or may control terminals, and revoking it cuts it off at once, live sessions included.
- Explicit control. Typing needs a control lease for that pane, checked against the program currently running in it. Keystrokes are never replayed after a dropped connection, and a command whose delivery is uncertain is never resent automatically.
- Relays carry ciphertext only. Through a relay, the phone’s TLS still ends at your computer. Each phone has its own relay credential, and relayed connections are never treated as your local network.
- Certificate renewal keeps pairings. Thirty days before the certificate expires, the bridge makes a successor and signs its fingerprint with the current key. Phones that connect before the switch verify that and move over; others pair again.
- Private state. The certificate key, configuration and device database live in a folder only your user can read. Logs record lifecycle events, not tokens, invitations, prompts or file contents.
- A local-only console. The web console listens on 127.0.0.1, admits a browser only through a one-time link your account creates, and checks Host, Origin and a CSRF token on every change.
Who can see what
| If this is compromised… | …it can | …it cannot |
|---|---|---|
| Your Wi-Fi, VPN or a relay (and any proxy or CDN in front of it) | See when you connect and how much data flows; drop or slow connections | Read terminals, files or prompts, or type anything: it has no device token and fails the certificate pin |
| The relay’s phone secret | Knock on the bridge’s front door: health checks and pairing, which still needs a fresh one-time code | Use the phone API without a paired device |
| The relay’s bridge secret | Pretend to be your computer to the relay, knocking the real one off | Fool phones: they reject anything without your computer’s certificate |
| A phone or its device token | Whatever that device’s access allows; with control, the same as a shell as you | Outlast a revoke: revoke lost phones from the computer |
| Your user account on the computer | Everything, as with SSH | Nothing extra: the bridge runs as you |
- Your Wi-Fi, VPN or a relay (and any proxy or CDN in front of it)…it can: See when you connect and how much data flows; drop or slow connections…it cannot: Read terminals, files or prompts, or type anything: it has no device token and fails the certificate pin
- The relay’s phone secret…it can: Knock on the bridge’s front door: health checks and pairing, which still needs a fresh one-time code…it cannot: Use the phone API without a paired device
- The relay’s bridge secret…it can: Pretend to be your computer to the relay, knocking the real one off…it cannot: Fool phones: they reject anything without your computer’s certificate
- A phone or its device token…it can: Whatever that device’s access allows; with control, the same as a shell as you…it cannot: Outlast a revoke: revoke lost phones from the computer
- Your user account on the computer…it can: Everything, as with SSH…it cannot: Nothing extra: the bridge runs as you
Compared with SSH
Encryption and server authentication are comparable. SSH and TLS both use modern authenticated encryption with forward secrecy. On first contact, pinning is arguably stricter than typical SSH use: SSH asks you to accept an unknown host key, which most people do without checking, while the phone gets the exact fingerprint from a QR code you scan in person.
Where SSH is ahead
- Client keys. SSH keys never leave the device and can live in hardware. Our device token is a bearer secret sent, inside the pinned TLS, with each request. Hardware-bound device keys are planned.
- Maturity. OpenSSH has decades of scrutiny. The bridge is new code and has not been independently audited.
Where this is ahead
- Scope. Read-only devices exist; an SSH login is usually all or nothing.
- Explicit control. Typing needs a lease tied to the pane’s program and is never replayed.
- Revocation. One command or click per device, which also ends its live sessions.
- No open port. With the relay, the computer accepts no inbound connection, and the relay refuses anyone without a credential before our protocol is reachable.
For confidentiality and integrity, the relay path is about as strong as SSH, because it rests on standard TLS with an exact certificate pin, not on the relay.
Known limits
- Device tokens are bearer secrets; device-bound keys are planned.
- Bridges still accept TLS 1.2 from older app versions.
- A relay accepts its shared phone secret until you start it with
--personal-only(older pairings and the Android app use it). - Nearby pairing trusts the local network for the first contact; compare the fingerprint, or pair by QR code on networks you don’t trust.
- A reverse proxy on the same computer makes remote connections look local; leave nearby discovery off in that setup.
Good practice
- Pair only your own devices, and give control only where you need it.
- Keep phones locked, and revoke a lost phone from the computer straight away.
- Treat pairing QR codes, invitations and relay profiles as secrets.
- Try workspace creation, splits and closing panes in a throwaway project first.
- Keep the bridge updated.
Report a problem
Please report security problems privately to [email protected] rather than in a public issue. The bridge’s source is on GitHub.
