Security Model

Beam implements a zero-trust security architecture where no entity is trusted by default. All traffic is encrypted end-to-end, no data is collected, and your development environment remains completely private. This page explains the security properties, threat model, and best practices.

Zero-Trust Architecture

Traditional tunneling services require you to trust a central provider with your traffic. They see every request, can log everything, and could be compelled to hand over data. Beam takes a fundamentally different approach: there is no central service to trust.

When you use Beam, traffic flows directly between you and your clients—either locally (no network at all) or through the Tor network (encrypted and anonymized). No Beam-operated servers ever see your data. The only infrastructure involved is your machine and the decentralized Tor network.

This means there's no company that can:

Read your traffic or log your requests
Comply with subpoenas or government data requests
Shut down your tunnel or ban your account
Raise prices or change terms of service
Go out of business and take your tunnels offline

Encryption

Beam provides end-to-end encryption through multiple layers, ensuring your traffic remains confidential regardless of the network path it takes.

Local HTTPS (TLS 1.3)

When using the --https flag, Beam generates self-signed certificates and serves your local traffic over TLS 1.3:

Key Exchange: ECDHE with X25519 curve
Encryption: AES-256-GCM authenticated encryption
Forward Secrecy: New keys for each session; past traffic can't be decrypted

Tor Encryption (3 Layers)

When using Tor mode, traffic is encrypted in three layers, one for each relay:

Onion Routing: Each relay decrypts one layer, revealing only the next hop
Hidden Service Keys: Ed25519 for service identity, Curve25519 for sessions
Circuit Encryption: AES-CTR with fresh keys for each circuit

When using both HTTPS and Tor together, you get two independent layers of encryption—TLS inside Tor. This provides defense in depth even if one layer were somehow compromised.

Key Management

Cryptographic keys are central to Beam's security. Here's how they're generated, stored, and rotated:

Hidden Service Keys

Your .onion address is derived from an Ed25519 public key. These keys are:

Generated locally on first run using a cryptographically secure random number generator
Stored in ~/.beam/keys/ with filesystem permissions (600)
Never transmitted over the network except as part of the Tor protocol
Reused across sessions so you keep the same .onion address

Session Keys

For each tunnel session and connection:

Ephemeral keys are generated using Diffie-Hellman key exchange
Keys exist only in memory and are never persisted to disk
Tor circuits are rebuilt periodically (every ~10 minutes) with new keys
Compromise of session keys doesn't affect past traffic (forward secrecy)

TLS Certificates

For local HTTPS, Beam generates self-signed certificates:

Created on-demand for each domain you configure
Stored in ~/.beam/certs/
Valid for 1 year; regenerated automatically when expired
Your browser will show a warning since they're not CA-signed (expected for development)

Privacy Protection

Beam is designed with privacy as a core principle, not an afterthought:

No Data Collection

No analytics, telemetry, or usage tracking of any kind
No request logging—Beam doesn't store what URLs you access
No IP address collection—your location is never recorded
No "phone home" behavior—Beam doesn't contact any servers except for npm updates

IP Anonymization (Tor Mode)

Your real IP is hidden from clients connecting to your tunnel
Client IPs are hidden from you (mutual anonymity)
Network observers see only encrypted Tor traffic, not the content
Even Tor relays can't see both source and destination

Local-First Design

All processing happens on your machine
Configuration stored locally in ~/.beam/
No cloud accounts, subscriptions, or external dependencies
Works completely offline in local-only mode

Threat Model

Understanding what Beam protects against (and what it doesn't) helps you make informed decisions about when and how to use it.

Protected Threats

Network eavesdropping: Encrypted traffic can't be read by ISPs, network admins, or attackers on the same WiFi
Man-in-the-middle attacks: TLS and Tor cryptography prevent traffic interception and modification
IP address exposure: Tor mode hides your real IP from clients and observers
Traffic analysis: Tor's multi-hop routing makes it hard to correlate traffic patterns
Vendor surveillance: No central service sees your traffic or collects your data
Service disruption: No central point of failure; tunnels work as long as Tor does

Partial Protection

Timing attacks: Tor provides some protection against traffic timing analysis, but sophisticated adversaries with global network visibility may still correlate traffic patterns.
Application vulnerabilities: Beam secures the transport layer. If your application has security bugs (XSS, SQL injection, etc.), Beam doesn't protect against those.

Not Protected

Endpoint compromise: If your development machine is compromised by malware, encryption won't help—the attacker has access before encryption happens.
Social engineering: If you share your .onion URL publicly or with untrusted parties, they can access your tunnel. Treat .onion URLs like passwords.
Nation-state adversaries: Highly resourced adversaries with extensive surveillance capabilities may be able to deanonymize Tor users through advanced techniques. For most development use cases, this is not a realistic threat.

Security Best Practices

Follow these guidelines to get the most security benefit from Beam:

Keep Beam updated: Run npm update -g @byronwade/beamregularly to get security patches and bug fixes.
Use Tor for sensitive work: Enable --torwhen exposing services that handle sensitive data or when privacy matters.
Don't share .onion URLs publicly: Treat your .onion address like a password. Share only with trusted parties who need access.
Secure your local application: Beam secures the tunnel, but your application must handle authentication, authorization, and input validation properly.
Stop tunnels when not needed: Don't leave tunnels running indefinitely. Stop them when you're done to minimize attack surface.
Protect your keys: The ~/.beam/keys/directory contains your hidden service identity. Back it up securely if you need persistent .onion addresses.
Use for development only: Beam is designed for development and testing environments. For production deployments, use proper infrastructure with additional security layers.

Security Vulnerability Reporting

If you discover a security vulnerability in Beam, please report it responsibly:

Do NOT disclose the vulnerability publicly until it's been fixed
Open a private security advisory on GitHub or email the maintainer directly
Include steps to reproduce the vulnerability and potential impact assessment
We'll acknowledge receipt within 48 hours and work on a fix

Security researchers who responsibly disclose vulnerabilities will be credited in release notes (unless they prefer anonymity).