Metadata-Version: 2.4
Name: ghostwire
Version: 0.1.0
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Rust
Classifier: Topic :: System :: Networking
Classifier: Topic :: Security :: Cryptography
License-File: LICENSE
Summary: A local-first userspace mesh VPN: Noise-encrypted UDP tunnels, WireGuard-compatible config, zero servers required. Ships the Rust binary as a console script, ruff-style.
Keywords: vpn,wireguard,noise,mesh,tunnel,cli
Author: Makeph
License: MIT
Requires-Python: >=3.8
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://github.com/Makeph/ghostwire
Project-URL: Issues, https://github.com/Makeph/ghostwire/issues
Project-URL: Repository, https://github.com/Makeph/ghostwire

# ghostwire

[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) [![Rust](https://img.shields.io/badge/Rust-2021-orange.svg)](https://www.rust-lang.org/)

A local-first userspace mesh VPN you fully own.

ghostwire is a zero-server mesh VPN toolkit for building encrypted peer-to-peer tunnels from local config. It generates WireGuard-compatible Curve25519 keys, plans full-mesh node configs, exports `wg-quick` files, and includes a pure-UDP encrypted datapath that can be tested without admin privileges.

## Why

- Own your tunnel: no control-plane SaaS, accounts, or hosted coordinator.
- WireGuard-compatible keys: Curve25519 keys encoded as standard base64, compatible with `wg` key material.
- Vetted crypto: the Noise Protocol Framework via the `snow` crate, not hand-rolled primitives.
- Local-first config: your mesh lives in a local `ghostwire.toml`.
- Single static binary workflow: generate, inspect, export, self-test, and bring up from one CLI.

## How It Works

ghostwire speaks `Noise_IK_25519_ChaChaPoly_BLAKE2s`: Noise IK over Curve25519, ChaCha20-Poly1305, and BLAKE2s. The initiator already knows the responder's static public key, sends the first handshake datagram, and the responder replies with the second. After those two UDP datagrams, both peers have a Noise transport session.

The datapath is intentionally simple: one application packet is sealed as one Noise transport message and sent as one UDP datagram. All cryptography is delegated to `snow`.

Keys are 32-byte Curve25519 values rendered as standard base64, matching WireGuard's `wg genkey` / `wg pubkey` format. ghostwire can export `wg-quick` configs, including QR output for mobile import.

Real OS packet routing through TUN is optional and gated behind `--features tun`. That path needs admin/root privileges, and on Windows it requires `wintun.dll`. The pure-UDP crypto datapath works without privileges and is covered by `ghostwire selftest`.

## Install

From this repository:

```sh
cargo install --path .
```

Or build a release binary:

```sh
cargo build --release
```

For real TUN routing:

```sh
cargo build --release --features tun
```

## Quickstart

Verify the local encrypted datapath without needing a TUN device:

```sh
ghostwire selftest
```

Create a new local mesh config with three nodes:

```sh
ghostwire init --name home --subnet 10.42.0.0/24 --nodes laptop,vps,phone
```

Inspect the nodes, tunnel addresses, abbreviated public keys, endpoints, and which entries have local private keys:

```sh
ghostwire show
```

Export a WireGuard-compatible config for a node:

```sh
ghostwire export --node laptop
```

Export a QR code for mobile WireGuard import:

```sh
ghostwire export --node phone --qr        # scan into the WireGuard mobile app
```

Generate a fresh keypair:

```sh
ghostwire keygen
```

## Security

ghostwire uses `Noise_IK_25519_ChaChaPoly_BLAKE2s` through the `snow` crate. That gives it Curve25519 static identity keys, ephemeral keys for forward secrecy during session setup, ChaCha20-Poly1305 transport encryption, and BLAKE2s hashing. The crate does not implement its own crypto primitives.

Private keys are not logged through `Debug`; key debug output is redacted to a short fingerprint. `ghostwire.toml` contains private keys for local nodes and is intentionally gitignored.

Status: early. Audit before trusting ghostwire with anything critical.

## Roadmap

- Multi-peer demux with cookie/index handling like WireGuard.
- Roaming endpoints.
- Pre-shared symmetric key option.
- Windows service and systemd units.

## License

MIT

