critical-wormhole-tools 0.1.0

Critical Wormhole Tools - Secure network utilities using Magic Wormhole code-based addressing

Critical Wormhole Tools

Secure network utilities using Magic Wormhole code-based addressing

---

What is Critical Wormhole Tools?

Critical Wormhole Tools (cwt / wh) brings the power of Magic Wormhole code-based addressing to everyday network utilities. Instead of dealing with IP addresses, port forwarding, and firewall rules, simply share a human-readable code like 7-guitar-sunset and connect securely from anywhere in the world.

┌─────────────────┐                              ┌─────────────────┐
│   Your Machine  │                              │  Remote Machine │
│                 │      "7-guitar-sunset"       │                 │
│   wh ssh ───────┼──────────────────────────────┼─────── wh listen│
│                 │     End-to-End Encrypted     │        --ssh    │
└─────────────────┘      NAT Traversal Built-in  └─────────────────┘

Key Features

• No IP addresses - Use memorable codes like 7-guitar-sunset
• No port forwarding - Works through NAT and firewalls automatically
• End-to-end encrypted - PAKE-based key agreement, no trusted third parties
• Cross-platform - Works on Linux, macOS, and Windows
• Familiar tools - Same interface as netcat, ssh, scp, sftp, curl, wget

---

Installation

Using pip (Recommended)

pip install critical-wormhole-tools

Using pipx (Isolated Environment)

pipx install critical-wormhole-tools

Using Homebrew (macOS/Linux)

brew tap bshuler/critical-wormhole
brew install critical-wormhole

Using Chocolatey (Windows)

choco install critical-wormhole-tools

From Source

git clone https://github.com/bshuler/critical-wormhole-tools.git
cd cwt
pip install -e ".[dev]"

---

Quick Start

1. Netcat (wh nc)

Machine A (Listen):

wh nc -l
# Output: Listening on code: 7-guitar-sunset

Machine B (Connect):

echo "Hello through the wormhole!" | wh nc 7-guitar-sunset

2. SSH (wh ssh)

Server (Listen):

wh listen --ssh
# Output: Listening on code: 3-castle-thunder
# SSH server ready

Client (Connect):

wh ssh 3-castle-thunder
# You're now in a shell on the remote machine!

3. File Transfer (wh scp)

Server:

wh listen --ssh
# Output: Listening on code: 5-river-mountain

Client - Download:

wh scp 5-river-mountain:/path/to/remote/file.txt ./local/

Client - Upload:

wh scp ./local/file.txt 5-river-mountain:/path/to/remote/

4. Interactive SFTP (wh sftp)

wh sftp 5-river-mountain
sftp> ls
sftp> get documents/report.pdf
sftp> put ./data.csv /home/user/
sftp> quit

5. HTTP Requests (wh curl)

Server (HTTP Proxy):

wh listen --http
# Output: Listening on code: 2-ocean-breeze

Client:

wh curl --code 2-ocean-breeze https://api.example.com/data
wh curl --code 2-ocean-breeze -X POST -d '{"key":"value"}' https://api.example.com/

6. File Download (wh wget)

wh wget --code 2-ocean-breeze https://example.com/large-file.zip

---

Commands Reference

Command	Description	Example
wh nc	Netcat-style bidirectional pipe	wh nc 7-guitar-sunset
wh nc -l	Listen for incoming connections	wh nc -l
wh listen	Multi-purpose listener daemon	wh listen --ssh
wh ssh	SSH client over wormhole	wh ssh 3-castle-thunder
wh scp	Secure copy files	wh scp code:/remote ./local
wh sftp	Interactive SFTP session	wh sftp 3-castle-thunder
wh curl	HTTP requests through proxy	wh curl --code X http://...
wh wget	Download files via HTTP proxy	wh wget --code X http://...

---

How It Works

Critical Wormhole Tools uses Magic Wormhole's Dilation protocol:

1. Code Exchange: Both parties enter the same code (e.g., 7-guitar-sunset)
2. PAKE Handshake: Password-Authenticated Key Exchange establishes shared secrets
3. Direct Connection: Attempts direct P2P connection with NAT traversal
4. Relay Fallback: If direct fails, uses relay server (data still encrypted)
5. Streaming: Dilated wormhole provides reliable, ordered, bidirectional streams

┌────────┐         ┌─────────────┐         ┌────────┐
│ Client │◄───────►│   Mailbox   │◄───────►│ Server │
│        │   Code  │   Server    │   Code  │        │
└───┬────┘         └─────────────┘         └────┬───┘
    │                                           │
    │              PAKE Key Exchange            │
    │◄─────────────────────────────────────────►│
    │                                           │
    │           Direct P2P (if possible)        │
    │◄═════════════════════════════════════════►│
    │          or via Transit Relay             │
    │         (still E2E encrypted)             │
    └───────────────────────────────────────────┘

---

Security

• PAKE (SPAKE2): No passwords transmitted, even to relay servers
• NaCl encryption: Industry-standard cryptographic primitives
• Forward secrecy: Each session uses unique keys
• No account required: Anonymous, decentralized by design
• Verifier display: Optional visual verification of connection

---

Use Cases

Remote Access Without VPN

Access your home server from anywhere without setting up port forwarding or dynamic DNS.

Quick File Sharing

Share files between machines without uploading to cloud services.

Pair Programming

Give a colleague SSH access to your development machine temporarily.

IoT Device Access

Connect to devices behind carrier-grade NAT.

Secure API Testing

Make HTTP requests to internal APIs through a trusted proxy.

---

Configuration

Environment Variables

Variable	Description	Default
WH_RELAY	Mailbox relay URL	ws://relay.magic-wormhole.io:4000/v1
WH_TRANSIT	Transit relay	tcp:transit.magic-wormhole.io:4001
WH_SSH_PASSWORD	SSH password (avoid prompts)	-

Custom Relay

For privacy or performance, run your own relay:

# Use custom relay
wh --relay ws://my-relay.example.com:4000/v1 nc -l

---

Development

Setup

git clone https://github.com/bshuler/critical-wormhole-tools.git
cd cwt
pip install -e ".[dev]"

Run Tests

# All tests
pytest

# Unit tests only (fast)
pytest tests/unit

# With coverage
pytest --cov=wh --cov-report=html

Code Quality

# Linting
ruff check src tests

# Type checking
mypy src

---

Roadmap

• Permanent Addresses: Static wormhole codes for persistent services
• Browser Extension: Browse wormhole-hosted sites in Chrome/Firefox
• Web Server Integration: Apache/Nginx/HAProxy wormhole modules
• wh ping: Network diagnostics through wormhole
• wh rsync: Efficient file synchronization
• wh proxy: SOCKS5 proxy through wormhole

See ROADMAP.md for detailed plans.

---

Contributing

Contributions are welcome! Please read our Contributing Guide first.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing)
5. Open a Pull Request

---

License

MIT License - see LICENSE for details.

---

Acknowledgments

• Magic Wormhole - The amazing protocol this is built on
• AsyncSSH - SSH implementation
• Twisted - Async networking framework

---

Connect securely. Share easily. No IP addresses required.

GitHub • PyPI • Issues • Discussions