https://github.com/ilia-ae/wg-yubikey-manager

🚓🔓 macOS app for managing WireGuard VPN configurations with YubiKey authentication
https://github.com/ilia-ae/wg-yubikey-manager

2026 blog hardware-token macos swift vpn wireguard yubikey

Last synced: 28 days ago
JSON representation

🚓🔓 macOS app for managing WireGuard VPN configurations with YubiKey authentication

Host: GitHub
URL: https://github.com/ilia-ae/wg-yubikey-manager
Owner: ilia-ae
License: mit
Created: 2026-03-20T09:13:34.000Z (4 months ago)
Default Branch: main
Last Pushed: 2026-05-18T06:13:54.000Z (about 2 months ago)
Last Synced: 2026-05-18T07:54:34.024Z (about 2 months ago)
Topics: 2026, blog, hardware-token, macos, swift, vpn, wireguard, yubikey
Language: Go
Homepage: https://ilia.ae/en/blog/infosec/wireguard-yubikey-manager-hardware-backed-vpn-security/
Size: 191 KB
Stars: 0
Watchers: 0
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Security: SECURITY.md

Awesome Lists containing this project

README

# 🔐 WG YubiKey Manager

**Secure WireGuard VPN management with hardware-backed key storage on YubiKey**

[![Go](https://img.shields.io/badge/Go-1.25-00ADD8?style=flat-square&logo=go&logoColor=white)](https://go.dev/)
[![Wails](https://img.shields.io/badge/Wails-v3_alpha-DF0000?style=flat-square&logo=wails&logoColor=white)](https://v3alpha.wails.io/)
[![Svelte](https://img.shields.io/badge/Svelte-4.2-FF3E00?style=flat-square&logo=svelte&logoColor=white)](https://svelte.dev/)
[![Vite](https://img.shields.io/badge/Vite-5.4-646CFF?style=flat-square&logo=vite&logoColor=white)](https://vitejs.dev/)
[![Platform](https://img.shields.io/badge/platform-macOS%2012%2B-000000?style=flat-square&logo=apple&logoColor=white)](https://www.apple.com/macos/)
[![YubiKey](https://img.shields.io/badge/YubiKey-5%20Series-84BD00?style=flat-square&logo=yubico&logoColor=white)](https://www.yubico.com/)
[![License](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](LICENSE)

[**English**](README.md) | [**Русский**](README_RU.md)

WG YubiKey Manager

*A macOS native desktop application that combines WireGuard VPN tunnel management with YubiKey hardware security — your private keys never touch the disk.*

---

## ✨ Features

### 🔑 Hardware Key Security
- **YubiKey PIV Storage** — WireGuard private keys are encrypted and stored on YubiKey PIV slots (`5f0001`–`5f00ff`)
- **PIN-Protected Decryption** — keys are decrypted in-memory only at connection time using GPG + AES-256
- **Zero Disk Exposure** — private keys are never written to disk, only held in RAM during active sessions
- **Slot Registry** — automatic metadata management in YubiKey slot `5fc10f`

### 🌐 VPN Tunnel Management
- **One-Click Connect/Disconnect** — seamless WireGuard tunnel lifecycle management
- **Live Connection Stats** — real-time handshake, transfer (RX/TX), latency, peer info, uptime
- **Multi-Tunnel Support** — manage multiple WireGuard configurations from a single interface
- **Config Import** — paste or upload `.conf` files with automatic validation
- **Auto-Discovery** — scan YubiKey for stored configurations and sync to local state

### 🖥️ Native macOS Experience
- **Translucent Window** — native glassmorphism UI with dark/light theme support
- **Menu Bar Tray** — persistent status indicator (● connected / ◯ disconnected)
- **Privilege Escalation** — one-time sudoers setup via `osascript`, passwordless afterwards
- **macOS App Bundle** — distributable `.app` with proper `Info.plist` and icon

---

## 🏗️ Architecture

```
┌─────────────────────────────────────────────────────────────┐
│ WG YubiKey Manager │
├──────────────────────┬──────────────────────────────────────┤
│ Frontend (Svelte) │ Backend (Go) │
│ │ │
│ ┌────────────────┐ │ ┌──────────────────────────────┐ │
│ │ App.svelte │──┼──│ internal/app/app.go │ │
│ │ StatusBar │ │ │ ├── Connect / Disconnect │ │
│ │ TunnelList │ │ │ ├── Import / Delete │ │
│ │ TunnelCard │ │ │ └── GetStatus / emitStatus │ │
│ │ PinDialog │ │ ├──────────────────────────────┤ │
│ │ ImportDialog │ │ │ internal/yubikey/ │ │
│ │ TokenInfo │ │ │ ├── PIV slot read/write │ │
│ └────────────────┘ │ │ ├── GPG encrypt/decrypt │ │
│ │ │ └── Registry management │ │
│ Wails Runtime │ ├──────────────────────────────┤ │
│ (JS bindings) │ │ internal/wireguard/ │ │
│ │ │ ├── Config parsing (INI) │ │
│ │ │ └── Validation │ │
│ │ ├──────────────────────────────┤ │
│ │ │ internal/tunnel/ │ │
│ │ │ └── Active tunnel state │ │
│ │ ├──────────────────────────────┤ │
│ │ │ internal/privilege/ │ │
│ │ │ └── sudo + sudoers setup │ │
│ │ ├──────────────────────────────┤ │
│ │ │ internal/tray/ │ │
│ │ │ └── macOS NSStatusItem │ │
│ │ └──────────────────────────────┘ │
├──────────────────────┴──────────────────────────────────────┤
│ macOS (wireguard-go, wg, ykman, gpg) │
└─────────────────────────────────────────────────────────────┘
```

---

## 📋 Prerequisites

| Dependency | Version | Installation |
|---|---|---|
| **macOS** | 12.0+ (Monterey) | — |
| **Go** | 1.25+ | [go.dev/dl](https://go.dev/dl/) |
| **Node.js** | 18+ | `brew install node` |
| **YubiKey** | 5 Series (PIV) | [yubico.com](https://www.yubico.com/) |
| **ykman** | latest | `brew install ykman` |
| **GnuPG** | 2.x | `brew install gnupg` |
| **WireGuard** | latest | `brew install wireguard-go wireguard-tools` |
| **Wails CLI** | v3 alpha | `go install github.com/wailsapp/wails/v3/cmd/wails3@latest` |

### Quick Install (Homebrew)

```bash
brew install go node ykman gnupg wireguard-go wireguard-tools
go install github.com/wailsapp/wails/v3/cmd/wails3@latest
```

---

## 🚀 Getting Started

### Clone

```bash
git clone https://github.com/razqqm/wg-yubikey-manager.git
cd wg-yubikey-manager
```

### Development Mode

```bash
wails dev
```

This starts the app with hot-reload for both frontend and backend.

### Build

```bash
make build
```

Produces a binary at `build/wg-yubikey-manager`.

### Build macOS App Bundle

```bash
./build-app.sh
```

Creates `build/WG YubiKey Manager.app` — drag to `/Applications/` to install.

### Install

```bash
cp -r "build/WG YubiKey Manager.app" /Applications/
```

---

## 📖 Usage

### First Launch

1. **Insert your YubiKey** into a USB port
2. **Launch the app** — it will prompt once for admin password to install a sudoers rule
3. The menu bar shows ◯ (disconnected)

### Import a WireGuard Config

1. Click **Import** in the app
2. Paste your `.conf` file content or select a file
3. Enter a name for the tunnel
4. Enter your **YubiKey PIN** — the config is encrypted and stored on the YubiKey
5. The config is validated automatically before import

### Connect to a Tunnel

1. Click **Connect** on a tunnel card
2. Enter your **YubiKey PIN**
3. The app decrypts the key from YubiKey → sets up `wireguard-go` → configures routes and DNS
4. Menu bar changes to ● (connected) with tunnel name
5. Live stats appear: handshake time, transfer, latency, peer info

### Disconnect

Click **Disconnect** — the tunnel is torn down, routes removed, DNS resolver cleaned up.

### Sync from YubiKey

Click **Sync** — the app scans all PIV slots, discovers stored configs, rebuilds the registry, and syncs to local state. Useful when moving to a new machine.

---

## 📁 Project Structure

```
wg-yubikey-manager/
├── cmd/
│ └── wg-yubikey-manager/
│ └── main.go # Wails app initialization (480×640 window)
├── internal/
│ ├── app/
│ │ └── app.go # Core logic: Connect, Disconnect, Import, Stats
│ ├── config/
│ │ └── manager.go # JSON config persistence (~/.config/wg-yubikey-manager/)
│ ├── privilege/
│ │ └── escalation.go # Sudoers install + passwordless sudo execution
│ ├── tray/
│ │ ├── tray.go # Wails v3 SystemTray (pure Go)
│ │ └── dialogs.go # PIN dialog + error alerts (osascript)
│ ├── tunnel/
│ │ └── manager.go # Thread-safe active tunnel state (mutex-protected)
│ ├── wireguard/
│ │ └── wireguard.go # WireGuard INI parser + validator
│ └── yubikey/
│ └── manager.go # YubiKey PIV operations (ykman + gpg)
├── pkg/
│ └── models/
│ ├── tunnel.go # TunnelDefinition, TunnelInfo, AppStatus
│ ├── wireguard.go # WireGuardConfig, Interface, Peer
│ └── yubikey.go # YubiKeyInfo, KeySlot, TokenInfo
├── frontend/
│ ├── embed.go # Go embed for production assets
│ ├── index.html # HTML entry point
│ ├── package.json # Svelte + Vite dependencies
│ ├── vite.config.js # Vite + Svelte plugin
│ └── src/
│ ├── main.js # Svelte mount point
│ ├── App.svelte # Root component, state orchestration
│ ├── style.css # Design system (dark/light, glassmorphism)
│ └── components/
│ ├── StatusBar.svelte # YubiKey + tunnel status indicators
│ ├── TokenInfo.svelte # Slot usage, Sync/Import buttons
│ ├── TunnelList.svelte # Tunnel list with Add form
│ ├── TunnelCard.svelte # Tunnel card with live stats
│ ├── PinDialog.svelte # PIN entry modal (Enter/Esc)
│ └── ImportDialog.svelte # Config import (paste/upload + validation)
├── resources/ # App icon (appicon.icns)
├── build/ # Build output
├── go.mod # Go module (github.com/razqqm/wg-yubikey-manager)
├── wails.json # Wails framework configuration
├── Makefile # Build automation
└── build-app.sh # macOS .app bundle creator
```

---

## 🔒 Security Model

### Key Storage

```
┌────────────┐ GPG AES-256 ┌──────────────┐
│ WireGuard │ ──── encrypt(PIN) ──► │ YubiKey PIV │
│ .conf │ │ slot 5fXXXX │
└────────────┘ └──────────────┘
▲ │
│ at connect time │
└────── decrypt(PIN, in-memory) ─────┘
```

- **At Import**: Config is encrypted with GPG (AES-256, PIN as passphrase) and written to a YubiKey PIV data slot
- **At Connect**: Config is decrypted from YubiKey in-memory, parsed in Go, private key passed via stdin to `wg set`
- **Never on Disk**: Private keys exist only in RAM during the active session

### Privilege Escalation

1. On first launch, `EnsureSudoers()` installs `/etc/sudoers.d/wg-yubikey` via `osascript` (macOS auth dialog)
2. All subsequent privileged operations (`wireguard-go`, `wg`, `route`, DNS resolver) use `sudo -n` (no password)
3. YubiKey operations (`ykman`, `gpg`) run as the current user — no sudo needed

### Threat Model Considerations

| Threat | Mitigation |
|---|---|
| Key theft from disk | Keys never written to disk |
| Key extraction from memory | Keys cleared after tunnel setup |
| Unauthorized tunnel activation | YubiKey PIN required for every connection |
| Physical YubiKey theft | PIN protection (lockout after retries) |
| Privilege escalation abuse | Sudoers rule scoped to specific commands |

---

## ⚙️ Configuration

### Application Config

Stored in `~/.config/wg-yubikey-manager/`:

| File | Purpose |
|---|---|
| `tunnels.json` | Tunnel definitions (name ↔ YubiKey slot tag mapping) |

### YubiKey Layout

| Slot | Purpose |
|---|---|
| `5fc10f` | Registry — JSON array of `{name, tag}` pairs |
| `5f0001` – `5f00ff` | Encrypted WireGuard configs (up to 255 tunnels) |

### DNS Resolution

Per-tunnel DNS resolvers are created at `/etc/resolver/{tunnelName}` during connection and removed on disconnect.

---

## 🛠️ Development

### Makefile Targets

| Target | Description |
|---|---|
| `make frontend` | Build frontend only (npm install + npm run build) |
| `make build` | Full build (frontend + Go binary) |
| `make run` | Build and run |
| `make clean` | Remove build artifacts, node_modules, dist |
| `make test` | Run Go tests |
| `make lint` | Run golangci-lint |

### Tech Stack

| Layer | Technology |
|---|---|
| Backend | Go 1.25 |
| Frontend | Svelte 4, Vite 5 |
| Bridge | Wails v3 (WebView + Go service bindings) |
| Native UI | Cocoa via CGO (NSStatusItem) |
| Crypto | GnuPG (AES-256 symmetric) |
| Hardware | YubiKey PIV via `ykman` CLI |
| VPN | `wireguard-go` + `wg` CLI |

### Frontend API

The frontend communicates with the Go backend through Wails-generated bindings:

```javascript
// Connection
await window.go.app.App.Connect(tunnelName, pin)
await window.go.app.App.Disconnect()

// Status
const status = await window.go.app.App.GetStatus()

// Tunnel management
await window.go.app.App.AddTunnel(name, tag)
await window.go.app.App.RemoveTunnel(name)

// YubiKey operations
const tokenInfo = await window.go.app.App.LoadFromToken(pin)
await window.go.app.App.ImportConfig(pin, name, configText)
await window.go.app.App.DeleteFromToken(pin, name)
const slot = await window.go.app.App.GetNextFreeSlot(pin)

// Real-time events
window.runtime.EventsOn('status:update', (status) => { ... })
```

---

## 🤝 Contributing

Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

---

## 📜 License

This project is licensed under the MIT License — see the [LICENSE](LICENSE) file for details.

---

## 🙏 Acknowledgments

- [Wails](https://wails.io/) — Go + Web frontend framework
- [Svelte](https://svelte.dev/) — reactive UI compiler
- [WireGuard](https://www.wireguard.com/) — modern VPN protocol
- [Yubico](https://www.yubico.com/) — hardware security keys
- [GnuPG](https://gnupg.org/) — encryption toolkit

---

**Built with ❤️ for security-conscious VPN users**

*Your keys, your hardware, your control.*

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/ilia-ae/wg-yubikey-manager

Awesome Lists containing this project

README