Security

BeamCLI is designed with security as a top priority. This guide explains how your terminal data is protected.

End-to-End Encryption

All terminal data is encrypted before leaving your machine. The relay server never sees your terminal content.

Encryption Algorithm

BeamCLI uses industry-standard cryptography:

Component	Algorithm
Key Exchange	X25519 (Curve25519 ECDH)
Encryption	XSalsa20-Poly1305
Library	TweetNaCl

How It Works

┌──────────────┐                    ┌──────────────┐
│     Host     │                    │    Viewer    │
└──────┬───────┘                    └───────┬──────┘
       │                                    │
       │ 1. Generate keypair                │
       │────────────────────────────────────│
       │                                    │
       │      2. Exchange public keys       │
       │<───────────────────────────────────│
       │                                    │
       │ 3. Derive shared secret (ECDH)     │
       │────────────────────────────────────│
       │                                    │
       │    4. Encrypt terminal data        │
       │───────[encrypted]─────────────────>│
       │                                    │
       │                    5. Decrypt data │
       │                                    │

Key Generation: Both host and viewer generate unique keypairs
Key Exchange: Public keys are exchanged through the relay
Shared Secret: Both parties compute the same shared secret using ECDH
Encryption: Terminal output is encrypted with the shared secret
Decryption: Only the intended recipient can decrypt

Zero-Knowledge Relay

The relay server:

Cannot read terminal content (encrypted end-to-end)
Cannot derive the shared secret (no private keys)
Only routes encrypted messages between participants

Session Codes

Session codes are designed for security and usability.

Format

5 characters
Base32 Crockford encoding (no confusing characters)
Case-insensitive

Security Properties

Property	Value
Entropy	~25 bits
Combinations	~33 million
Auto-expiration	Yes
Rate limiting	Yes

Best Practices

Share codes through secure channels (not public chat)
Codes expire when the host disconnects
Each session generates a new code

Ultra Safe Mode

For scenarios requiring maximum security, Ultra Safe Mode adds hardware key requirements.

Requirements

Hardware security key (YubiKey 5+, etc.)
PRF extension support (WebAuthn Level 2)

How It Works

Session Creation: Host starts with --ultra-safe flag
Passkey Authentication: Host authenticates with their security key
PRF Secret: A secret is derived from the passkey using PRF
Enhanced Key Derivation: Final encryption key = HKDF(ECDH_shared PRF_secret, salt)
Viewer Authentication: Viewers must authenticate with the same physical key

Security Benefits

Standard Mode:      encryption_key = ECDH(host_priv, viewer_pub)
Ultra Safe Mode:    encryption_key = HKDF(ECDH || PRF_secret, salt)

Threat	Standard	Ultra Safe
Session code leak	Encrypted data exposed	Still protected (need passkey)
Man-in-the-middle	Protected by ECDH	Double protection
Relay compromise	Cannot decrypt	Cannot decrypt

Data Handling

What Data Is Transmitted

Data	Encrypted	Stored
Terminal output	Yes	No
Terminal input	Yes	No
Session metadata	No	Temporarily
Public keys	No	Session duration

Data Retention

Terminal content: Never stored, streamed only
Session metadata: Deleted when session ends
User accounts: Stored until account deletion

OAuth Security

PKCE Protection

All OAuth flows use PKCE (Proof Key for Code Exchange) to protect against authorization code interception attacks:

Flow	PKCE Required
Web app login	Yes (S256)
CLI login	Yes (S256)
VS Code extension	Yes (S256)
OAuth (Google/GitHub)	Yes (S256)

PKCE ensures that even if an attacker intercepts the authorization code, they cannot exchange it for tokens without the original code_verifier.

Infrastructure Security

Server Security

All services run in private subnets (AWS VPC)
TLS 1.3 for all connections
No direct database access from internet
Secrets stored in AWS Secrets Manager
Redis connections encrypted in transit (TLS)

Network Security

Internet → CloudFront/ALB (HTTPS) → Private Subnet → Services
                                                   ↓
                                         RDS/Redis (encrypted)

Best Practices

For Hosts

Use read-only mode unless collaboration is needed
Enable Ultra Safe Mode for sensitive sessions
Share codes privately (direct message, not public channels)
End sessions when finished

For Viewers

Verify the host before connecting
Use a supported browser (Chrome, Firefox, Safari)
Don’t share access to active sessions

For Organizations

Require Ultra Safe Mode for production access
Use SSO integration for centralized auth
Monitor session logs for unusual activity

Reporting Security Issues

If you discover a security vulnerability:

Do not disclose publicly
Email security concerns to the repository maintainers
Include detailed reproduction steps
Allow time for a fix before disclosure

Compliance

BeamCLI’s security design supports:

GDPR: Data minimization, encryption at rest and transit
SOC 2: Access controls, encryption, logging
HIPAA: End-to-end encryption, audit trails (with enterprise features)

FAQ

Q: Can the server read my terminal? A: No. All terminal data is encrypted before transmission. The server only sees encrypted bytes.

Q: What if someone guesses my session code? A: They would only see encrypted data. Without the ECDH key exchange, decryption is impossible.

Q: Is the encryption audited? A: BeamCLI uses TweetNaCl, a well-audited cryptographic library.

Q: What data do you store? A: Only account information and session metadata. Terminal content is never stored.