Security

vmuxAgent threat model — what hardware-backed signing protects, and what it does not.

What this protects

The headline guarantee of the vmuxAgent + RemoteSignerPhone pair is simple: your authoritative SSH private keys never live on your Mac. They are generated and stored in the iPhone's Secure Enclave, which is a hardware security module distinct from the rest of the iPhone's processor. The keys cannot be exported, backed up, copied, or read out — not by an attacker, not by Apple, not by you. Every signature using one of those keys is a hardware operation that requires user presence, attested by Face ID or Touch ID.

This means an attacker with full root on your Mac cannot exfiltrate your SSH keys. They cannot use them offline. They cannot use them online without you approving each signature on the phone — and the phone's prompt names the source device, so you would notice the wrong machine asking.

Threat model

Threat	Outcome
Mac is stolen, attacker has full disk access	Attacker gets cached public keys only. No private material exists on the Mac to recover.
Mac is compromised by malware running as your user	Attacker can reach the agent socket and request signatures. Each signature requires Face ID on your iPhone. Attacker cannot sign anything without a live, approved prompt.
Mac is compromised but iPhone is off / out of range	Signatures fail. APNs wake gives one notification on the iPhone; if you don't tap it, no signature happens.
Network attacker on your Wi-Fi sniffs the local link	MPC traffic is encrypted (`encryptionPreference: .required`). Sign requests, public-key lists, and certificates are not visible in plaintext on the wire.
Network attacker between Mac and APNs	APNs wake pushes carry no key material. They are JWT-authenticated using a private p8 key on the Mac and signed by Apple's edge in transit. The push only triggers wake; it does not authorize signing.
iPhone is stolen	Face ID protects the Secure Enclave. After 5 failed biometrics, the phone falls back to passcode. With neither, keys cannot be used. Erase the device remotely via Find My to evacuate the cached pairing state.
Both Mac and iPhone are stolen, attacker knows your phone passcode	This is the worst case. The attacker can sign with your keys until you can revoke. Treat your phone passcode like a master credential and rotate keys on the phone if both devices are lost together.
Attacker spoofs another iPhone offering the `vmuxsigner` service	The Mac would invite the spoofed peer. But the spoofed peer doesn't hold your private keys; it can only return failures or invalid signatures, which the SSH handshake on the remote server rejects.
Insider on the LAN tries to add a second pairing	Each pairing event is visible on the iPhone (which displays the source Mac's name). Decline pair attempts you don't recognize.
`~/.ssh/vmux-agent.sock` accessible to other users	Mode `0600` (owner read/write). Other Unix users on the Mac cannot read or write the socket.

What this does not protect

Other processes running as your user. Anything running under your macOS account can connect to ~/.ssh/vmux-agent.sock and request signatures. macOS does not have a per-process authentication scheme for Unix sockets. Mitigation: each signature still produces a Face ID prompt that names the source Mac (and, for some clients, the destination host), so unauthorized signing is visible.
Approving the wrong prompt. If you reflexively tap "Approve" on every notification, biometric protection becomes a rubber stamp. Read the prompt; it shows the source device and the operation kind.
Compromised iPhone OS. A jailbroken or otherwise modified iOS could in theory bypass the biometric gate. Keep your iPhone updated and don't install profiles from untrusted sources.
Forwarded agents. When you ssh -A to a host, anyone with root on that host can use your forwarded agent for the duration of your session, with one biometric prompt per signature on your phone. Only forward to hosts you control. See SSH CLI integration for the full caveat.
Network exposure of public keys. Public keys are not secret, but they are distinguishing — anyone who sees one can identify "you" across services. The MPC link is encrypted, but the iPhone's APNs traffic and any servers you SSH into see your public key in the clear (this is normal SSH behavior).
The session certificate window. During the validity window of a session certificate (default 8 hours), any process running as you can sign with the ephemeral key without prompting the phone. This is the trade-off for not biometric-prompting on every keystroke. Choose a shorter validity if you want a tighter window.

Cryptographic specifics

Component	Algorithm	Notes
Phone-held SSH keys (Secure Enclave)	`ecdsa-sha2-nistp256` (P-256)	Only algorithm Secure Enclave hardware supports
Phone-held SSH keys (non-Enclave)	Whatever the phone-side identity store generates — typically `ssh-ed25519`	Up to the user
Mac ephemeral session keypair	P-256	Generated freshly on each pair, never persisted
Session certificate	OpenSSH user certificate	Signed by the iPhone-resident CA
MPC transport	TLS-equivalent (Apple-managed) with `encryptionPreference: .required`	Per-pair session keys
APNs wake push	Apple Push Notification Service, JWT-signed with ES256	The `.p8` private key is on the Mac
Socket file permissions	`0600`	Owner read/write only
Sign request expiry	60 seconds	Requests older than this are rejected by the phone
Session certificate validity	28800 seconds (8 hours) default	Configurable per request

The APNs key on the Mac (~/.ssh/vmux-apns.p8 or ~/.config/vmux/apns-key.p8) authorizes wake-push delivery only. It does not sign SSH challenges, does not authenticate the agent socket, and is unrelated to the iPhone's Secure Enclave keys. If the file is deleted, wake pushes stop working but signing continues to work whenever the iPhone is already reachable.

Operational guidance

Scenario	Recommendation
You travel with your Mac and iPhone	Both devices should have a strong passcode and biometric. App Lock on the iPhone (in RemoteSignerPhone) adds another biometric gate before signing.
You want unattended SSH for an hour	Use a session certificate. The window is short; the certificate expires automatically; and the underlying phone-held key is not exposed.
You leave the Mac for a meeting	Lock the Mac (Cmd+Ctrl+Q). The agent socket is still there but biometric prompts on the phone still gate signing. Rapid sign attempts while you're away will pile up notifications, which surfaces the abuse.
You lose the iPhone	Use Find My to erase. The Mac is now disarmed — `ssh-add -l` will show cached public keys, but no signing succeeds. Rotate keys on the replacement phone and update `authorized_keys` everywhere.
You share a Mac with another user	The agent socket is owner-private; the other user cannot use vmuxAgent. They can run their own vmuxAgent and pair to their own phone.

What lives where

A complete inventory of sensitive material:

File / data	Location	Sensitive?
SSH private keys	iPhone Secure Enclave	Cannot be exported
Session-cert ephemeral private key	Mac process memory	Lives only as long as the certificate
Cached public keys	macOS user defaults	Public material; no secrecy concern
Last known iPhone device token	macOS user defaults	Lets the Mac send wake pushes; not a credential by itself
APNs auth key (`vmux-apns.p8`)	`~/.ssh/` or `~/.config/vmux/`	Allows sending wake pushes; should be `0600`
MPC pairing state	Apple-managed system database	Not user-visible
Agent socket	`~/.ssh/vmux-agent.sock`	Owner-only by file permission
Logs	macOS unified log under subsystem `app.vmux.agent`	Connection events; no key material

Vmux family security — App Lock, Secure Enclave keys, encrypted backups across all apps.
SSH CLI integration — agent forwarding caveats.
Keys and certificates — session-cert lifecycle and trade-offs.
RemoteSignerPhone — phone-side identity and approval policy.