Trust & Security

Trust & Security#

What the threat model covers#

  • Authentication. Someone on your LAN cannot impersonate a paired controlled machine — the controller verifies the responder holds the X25519 private key corresponding to the public key recorded during pairing. Symmetric for the controlled side.

  • Confidentiality. Every protocol frame is ChaCha20-Poly1305 AEAD encrypted under per-direction session keys derived from a fresh Diffie-Hellman exchange in every connection.

  • Integrity. Same AEAD provides integrity; tampering or replay causes the connection to close.

  • Forward secrecy. Each connection uses fresh ephemeral keypairs; recording today’s traffic and stealing a long-lived key tomorrow does not let an attacker decrypt the recording.

What’s not in v1#

  • Internet-traversal. The protocol is LAN-only for now. Cross-network needs STUN/TURN or a relay — phase 2.

  • CA-signed TLS. Pairing uses out-of-band trust establishment (the code), not certificate authorities.

  • Multi-tenant accounts. Trust is per-machine, single-user.

Pairing-code strength#

The code is 6 digits — 10⁶ possibilities. opendesk stretches the code via PBKDF2-HMAC-SHA256 at 200 000 iterations before using it. At ~100 ms per derivation on a modern CPU, exhausting the space takes ~a CPU-month. Pairing only ever accepts one attempt and exits on success, so an online attacker has one shot per opendesk-js pair invocation.

Files written to disk#

Path

Mode

Contents

~/.opendesk/identity.key

0600

Raw 32-byte X25519 private key. Owner-only. Treat as a master secret.

~/.opendesk/trusted-peers.json

0600

[{public_key, name, paired_at, description, description_override, last_host, last_port}, ...]

~/.opendesk/audit/<YYYY-MM-DD>.jsonl

0600

Append-only audit log. One JSON object per line.

~/.opendesk/description.txt

0600

Broadcast description shown to controllers during discovery.

~/.opendesk/default-peer

0600

Persistent default peer name (written by opendesk-js peers default).

~/.opendesk/admin.sock

0600

Unix socket for CLI ↔ daemon IPC (Linux/macOS). Windows uses a localhost TCP port.

Next: CLI Reference →