Skip to content

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 0600 permissions
  • 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
  • iptables for the NAT hooks generated by initConf

Installation

npm install @kriper0nind/wg-utils

Quick 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 allocation
  • deletePeer() with idempotent removal
  • getNextPeerAddress()

Keys

  • generateKeys()
  • generatePresharedKey()
  • getPubKey() / getPublicKey()
  • isWireGuardKey() / assertWireGuardKey()

Clients

  • generateClientConfig()
  • generateClientQRCode()

Interfaces

  • up() / down() / restart()
  • isWgUp() / getInterfaceStatus()
  • getLatestHandshake()
  • syncConf() / saveConfig()

Installation

  • checkWg() / requireWg()
  • installWg()
  • getInstallInstructions()

Continue