Your phone types into your Mac. Who else can?
Grenade lets a phone type into terminals on your Mac. That is remote control by design, so the question is who else can get in. This page answers it for three people: someone on your Wi‑Fi, whoever runs the relay, and someone holding your phone. Where it says Mac, the same holds for a Linux computer running Grenade.
What protects it.
The Mac's key
Each Mac has a long-term X25519 key. The phone pins its public half when it pairs. Every connection, on Wi‑Fi and through a relay, starts with a handshake only the holder of that key can complete, then carries frames sealed with ChaCha20-Poly1305 under keys made fresh for that connection.
The token
Pairing gives the phone a random token. It travels only inside the encrypted channel, and it works until the pairing ends:
grenade unpair on the Mac, Unpair on the phone, or 90 days without the phone being seen.The QR code
It carries the Mac's key and a one-time secret of 128 random bits, straight from the Mac's screen to the phone's camera. So pairing trusts no network, and works through a relay. It lasts two minutes and works once.
The typed code
Six digits, two minutes, five tries, one use. Four more digits tie the code to the Mac's key, so the phone can tell the Mac in front of it from something posing as it before it sends anything.
The pause
Every fifth wrong code, typed or scanned, on Wi‑Fi or through a relay, pauses pairing on the Mac: a minute, then ten, then an hour, then a day. Someone guessing gets at most 20 tries on the first day and 5 a day after, and the Mac tells you each time. Nobody can end a pause early, you included.
Someone on the same Wi‑Fi
On your Wi‑Fi the phone talks to the Mac directly, with the same end-to-end encryption as through a relay.
Can
- See that a phone and a Mac are talking, how much, and when.
- Learn the Mac's name, its public key, its Grenade version and its relay's address, which the Mac announces so a phone can find it. None of these opens a connection.
- Block or drop the traffic. Nothing on a shared network prevents that.
- Hold up pairing while you have a code on screen, by typing wrong codes on purpose: pairing then pauses for up to a day, for you too. Phones already paired keep working.
Cannot
- Read a screen, a prompt or anything typed.
- Take over a session: they have no token, and cannot open the channel a token travels in.
- Pose as the Mac to a paired phone: the handshake fails without the Mac's key.
- Pair a phone of their own without the code or the QR code on your Mac's screen.
Whoever runs the relay
Away from your Wi‑Fi, the phone and the Mac talk through a relay that forwards bytes it cannot read. That is true of the one we run and of one you host yourself.
Can
- See each Mac's name, a random relay id, its public and local IP addresses, and when it is online.
- See each phone's IP address, and the size and timing of what passes.
- Refuse or drop connections, or say a Mac is offline when it is not.
Cannot
- Read screens, prompts, session names, attachments, the pictures a finished turn made, or tokens, or an API key you gave Grenade for Talk.
- Pose as the Mac: it does not have the Mac's key.
- Pair a phone, or change the key a phone pinned.
- Let an unpaired phone back in: the Mac no longer holds its token, and refuses it.
Someone holding your phone
A paired phone can type into your terminals. That is a shell on your Mac, so the phone's own lock matters, and the Mac can always end the pairing.
Can
- With the phone unlocked and the app open: everything the app can do. Read every session, type into any of them, start new ones in any folder.
- With the phone's passcode: get past the app's lock, which accepts the passcode where Face ID fails.
- If you use Talk: talk on your account with that provider, through the Mac, and replace or remove the API key there. All of it ends when you unpair the phone.
- See the pictures a session's turn made (the boards it saved, the screenshots it took or was shown, what you sent it), as the small copies the Mac kept, and remove any from highlights on every device.
Cannot
- Do anything with a locked phone: on an iPhone the key and the token are in the Keychain, unreadable until it is unlocked, and they do not move to another device in a backup.
- Open the app on an unlocked phone you handed over, while the app's lock is on: it asks for Face ID, Touch ID or the passcode when it opens and after a minute in the background, and shows nothing until then.
- Read an API key for Talk. It is kept on the Mac, shown masked, and never sent to a phone: the phone gets a pass that lasts minutes (iPhone app 1.0.53 or later; earlier versions kept the key in the Keychain).
- Keep access once you run
grenade unpair <phone>on the Mac: the token is deleted and its open connections close at once, on Wi‑Fi and through the relay. - Use a phone that was never found: one that has not been seen for 90 days is unpaired by itself.
What Grenade does not defend against.
Someone with your Mac user account
~/.grenade holds the Mac's key, the tokens and any API keys you gave Grenade for Talk, readable only by you. Whoever can read it can pose as the Mac and as every paired phone, and use those keys. A process running as you can already type into your terminals.Someone watching the Mac's screen while you pair
The code on the screen is the proof of being at the Mac. It lasts two minutes and works once.
Traffic analysis
Sizes and timing show when an agent is working, even though nothing can be read.
The agents themselves
Grenade carries what you type to the agent. What the agent may then do is the agent's own permission system.
Reporting a problem.
Open an issue on grenade-cli on GitHub. If the problem lets someone into another person's Mac or lets them read a session, report it privately instead: only the maintainers can read it.
What Grenade collects, and what it does not, is in the privacy policy. Running the relay yourself is in Self-host a relay.