Security

Security model

• Mutual TLS 1.3

  Both client and server authenticate with ed25519 certificates. The connection uses TLS 1.3 with X25519 key exchange for forward secrecy.

• ed25519 identity keys

  Each peer generates an ed25519 keypair with bridgesessions keygen. The private key stays on the client; servers authorize the public key.

• Trust on first use (TOFU)

  Server certificates are pinned on first connect and verified thereafter. No certificate authority infrastructure is required.

• Authorized keys

  Servers store permitted client public keys in ~/.bridgesessions/authorized_keys, one hex-encoded ed25519 public key per line.

• TCP-only transport

  v1 uses TLS over TCP port 19949. No UDP, no QUIC, no hole punching — firewall traversal is simple and predictable.

• Session isolation

  Session names are scoped by authenticated client public key. Two clients with different keys can use the same name without collision.

Authentication flow

1. Client loads ~/.bridgesessions/id_ed25519.pem
2. Client resolves server via DNS A/AAAA and dials TCP 19949
3. TLS 1.3 handshake with ed25519 client certificate
4. Server verifies client pubkey against ~/.bridgesessions/authorized_keys
5. Client verifies server certificate against pinned TOFU record
6. Attach{session_name} is processed and the PTY session begins

For automated bootstrapping, use the one-time pairing workflow: bridgesessions pair --server=<host> --bootstrap-token=<code>.

Vulnerability disclosure

Found a security issue? Please follow the disclosure process in the repository's SECURITY.md.