Skip to content

Docs

Security model

Device identity, pairing proof, signed signaling, and authenticate-then-stream.

Nearshell’s security goal is direct: only the two devices you personally paired can control each other, and even a compromised server can neither impersonate an endpoint, tamper with content, nor see your screen.

Device identity

  • The Mac has a stable, non-editable device identity;
  • Each side holds a Curve25519 key pair; private keys live in the Keychain and never leave the device;
  • After pairing, each side pins the other’s public key.

Pairing: one-time QR + mutual HMAC proof

  1. The Mac generates a one-time invite with device name, model, and a one-time secret, shown as a QR / text code;
  2. The iPhone imports it, and both sides prove identity to each other via mutual HMAC over that one-time secret, pinning the peer’s public key;
  3. The Mac then destroys the one-time secret and uses signed signaling from there on.

The one-time secret is valid only within the pairing window and expires once the proof completes — it never lingers.

Signed signaling

Once the peer’s public key is pinned, every signaling message needed to connect (accept / offer / answer / candidate) is signed. Before processing, the peer verifies:

  • Session — belongs to the current session;
  • Endpoint identity — the signer is the peer you pinned;
  • Time window — within the allowed clock window (replay resistance);
  • Monotonic sequence — the sequence increases monotonically (anti-replay / anti-reorder injection);
  • Signature — the content digest and Curve25519 signature match.

Authenticate, then stream

A connection does not stream immediately. Only after a mutual challenge-response on the control channel — with both sides having proven their identity — does the connection enter streaming, and the screen is sent only after that. The peer must prove who it is before receiving any screen content.

End-to-end encryption

Screen, mouse-keyboard input, and terminal text travel over an end-to-end encrypted realtime channel. The signaling server only forwards signed setup messages and can neither read nor decrypt your content; even when a connection must be relayed through our TURN, the node forwards only ciphertext. See the Privacy section on the home page.

Bounds on input injection

  • The Mac injects mouse / keyboard input only after you grant Accessibility permission;
  • When a connection leaves streaming, it immediately releases any still-held mouse / keyboard keys to avoid stuck keys.