WireGuard Utils
A type-safe TypeScript library for managing WireGuard configuration files, peers, keys, client profiles, QR codes, and interfaces.
Features
- Parse and serialize WireGuard configuration files
- Atomic configuration writes with optional backups and
0600permissions - Peer CRUD with IPv4 and IPv6 address allocation
- Enable or disable peers without losing their configuration
- Generate key pairs, preshared keys, client profiles, and QR codes
- Start, stop, restart, save, and sync WireGuard interfaces
- Inspect live interface status, handshakes, endpoints, and transfer counters
- Detect and install WireGuard tools on supported platforms
- Safe command execution without shell interpolation
- ESM and CommonJS builds with TypeScript declarations
Requirements
- Node.js 20 or newer
- WireGuard tools for key and interface operations
- Root/sudo privileges for interface management
iptablesfor the NAT hooks generated byinitConf
Installation
npm install @kriper0nind/wg-utilsQuick Start
import {
addPeer,
generateClientConfig,
generateClientQRCode,
generateKeys,
initConf,
up,
} from "@kriper0nind/wg-utils"
const serverKeys = await generateKeys()
const clientKeys = await generateKeys()
await initConf("/etc/wireguard/wg0.conf", {
privateKey: serverKeys.privateKey,
ip: "10.0.0.1",
port: 51820,
dns: "1.1.1.1",
})
const peer = await addPeer("/etc/wireguard/wg0.conf", {
publicKey: clientKeys.publicKey,
persistentKeepalive: 25,
})
const clientConfig = generateClientConfig({
privateKey: clientKeys.privateKey,
clientAddress: peer.address,
serverPublicKey: serverKeys.publicKey,
serverEndpoint: "vpn.example.com:51820",
dns: "1.1.1.1",
persistentKeepalive: 25,
})
await generateClientQRCode(clientConfig, {
outputPath: "/tmp/client.png",
})
await up("wg0")Main APIs
Configuration
parse()/stringify()readConfig()/writeConfig()validateWireGuardConfig()getPeer()/listPeers()/listDisabledPeers()updatePeer()/setPeerEnabled()/removePeer()
Peers
addPeer()with automatic IPv4 or IPv6 allocationdeletePeer()with idempotent removalgetNextPeerAddress()
Keys
generateKeys()generatePresharedKey()getPubKey()/getPublicKey()isWireGuardKey()/assertWireGuardKey()
Clients
generateClientConfig()generateClientQRCode()
Interfaces
up()/down()/restart()isWgUp()/getInterfaceStatus()getLatestHandshake()syncConf()/saveConfig()
Installation
checkWg()/requireWg()installWg()getInstallInstructions()