wireguard-utils
Version:
A comprehensive TypeScript library for WireGuard utilities including key generation, IP management, config building, QR code generation, config parsing, validation, templates, routing, tunnel management, and security features using proper Curve25519 crypt
316 lines (315 loc) • 8.53 kB
TypeScript
/**
* WireGuard key pair interface
*/
export interface WireGuardKeyPair {
privateKey: string;
publicKey: string;
}
/**
* Network class type for IP generation
*/
export type NetworkClass = 'A' | 'B' | 'C';
/**
* DNS configuration for different use cases
*/
export interface DNSConfig {
primary: string;
secondary?: string;
description: string;
type: 'privacy' | 'performance' | 'security' | 'family' | 'custom';
}
/**
* Port management configuration
*/
export interface PortConfig {
port: number;
available: boolean;
inUse?: string;
}
/**
* Config template types
*/
export type ConfigTemplate = 'roadwarrior-server' | 'roadwarrior-client' | 'site-to-site' | 'mesh-node' | 'gateway' | 'split-tunnel';
/**
* Routing configuration
*/
export interface RoutingConfig {
allowedIPs: string[];
routes?: RouteEntry[];
defaultRoute?: boolean;
splitTunnel?: boolean;
}
/**
* Route entry for advanced routing
*/
export interface RouteEntry {
network: string;
gateway?: string;
metric?: number;
description?: string;
}
/**
* Tunnel management status
*/
export interface TunnelStatus {
name: string;
active: boolean;
interface?: string;
peers?: number;
lastHandshake?: Date;
}
/**
* Config validation result
*/
export interface ValidationResult {
valid: boolean;
errors: string[];
warnings: string[];
suggestions: string[];
}
/**
* Parsed WireGuard configuration
*/
export interface ParsedConfig {
interface: ParsedInterface;
peers: ParsedPeer[];
raw: string;
valid: boolean;
}
/**
* Parsed interface section
*/
export interface ParsedInterface {
privateKey?: string;
address?: string[];
listenPort?: number;
dns?: string[];
preSharedKey?: string;
postUp?: string[];
postDown?: string[];
table?: string;
mtu?: number;
}
/**
* Parsed peer section
*/
export interface ParsedPeer {
publicKey?: string;
allowedIPs?: string[];
endpoint?: string;
preSharedKey?: string;
persistentKeepalive?: number;
}
/**
* WireGuard interface configuration
*/
export interface WireGuardInterface {
privateKey: string;
address: string[];
listenPort?: number;
dns?: string[];
preSharedKey?: string;
}
/**
* WireGuard peer configuration
*/
export interface WireGuardPeer {
publicKey: string;
allowedIPs: string[];
endpoint?: string;
preSharedKey?: string;
persistentKeepalive?: number;
}
/**
* Complete WireGuard configuration
*/
export interface WireGuardConfig {
interface: WireGuardInterface;
peers: WireGuardPeer[];
}
/**
* Generate a WireGuard private key
* @returns Base64 encoded private key (32 bytes)
*/
export declare function generatePrivateKey(): string;
/**
* Derive a WireGuard public key from a private key
* Uses Curve25519 elliptic curve cryptography
* @param privateKeyStr Base64 encoded private key
* @returns Base64 encoded public key
*/
export declare function derivePublicKey(privateKeyStr: string): string;
/**
* Validate a WireGuard public key
* @param publicKey Base64 encoded public key to validate
* @returns true if valid, false otherwise
*/
export declare function validatePublicKey(publicKey: string): boolean;
/**
* Generate a random IP address within the specified network class
* @param networkClass The IP class ('A', 'B', or 'C')
* @returns Generated IP address as string
*/
export declare function generateIPInClass(networkClass: NetworkClass): string;
/**
* Generate a random IP address within the specified subnet (auto-detects network class)
* @param subnet Subnet in CIDR notation (e.g., '192.168.1.0/24')
* @returns Generated IP address as string
*/
export declare function generateIPInClass(subnet: string): string;
/**
* Generate a random IP address within the specified network class and subnet
* @param networkClass The IP class ('A', 'B', or 'C')
* @param subnet Subnet in CIDR notation (e.g., '192.168.1.0/24')
* @returns Generated IP address as string
*/
export declare function generateIPInClass(networkClass: NetworkClass, subnet: string): string;
/**
* Generate a WireGuard pre-shared key
* Pre-shared keys provide additional quantum resistance and security
* @returns Base64 encoded pre-shared key (32 bytes)
*/
export declare function generatePreSharedKey(): string;
/**
* Build a complete WireGuard configuration file from structured data
* @param config WireGuard configuration object
* @returns WireGuard configuration file as string
*/
export declare function buildWireGuardConfig(config: WireGuardConfig): string;
/**
* Generate a complete WireGuard key pair
* Uses proper Curve25519 cryptography for WireGuard compatibility
* @returns Object containing base64 encoded private and public keys
*/
export declare function generateWireguardKeyPair(): WireGuardKeyPair;
/**
* Generate a QR code for WireGuard configuration
* Mobile WireGuard apps can scan these QR codes to automatically import configs
* @param configText WireGuard configuration as string
* @param options QR code generation options
* @returns Base64 encoded PNG image of the QR code
*/
export declare function generateQRCode(configText: string, options?: {
errorCorrectionLevel?: 'L' | 'M' | 'Q' | 'H';
width?: number;
margin?: number;
}): Promise<string>;
/**
* DNS Configuration Helpers (Feature 6)
*/
/**
* Get predefined DNS configurations for different use cases
*/
export declare function getDNSConfigs(): Record<string, DNSConfig>;
/**
* Get DNS servers by type
*/
export declare function getDNSByType(type: DNSConfig['type']): DNSConfig[];
/**
* Config File Parser (Feature 7)
*/
/**
* Parse a WireGuard configuration file
*/
export declare function parseWireGuardConfig(configText: string): ParsedConfig;
/**
* Config Validation (Feature 8)
*/
/**
* Validate a WireGuard configuration
*/
export declare function validateWireGuardConfig(config: WireGuardConfig | string): ValidationResult;
/**
* Port Management (Feature 9)
*/
/**
* Check if a port is available for WireGuard
*/
export declare function checkPortAvailability(port: number): Promise<PortConfig>;
/**
* Find an available port in the WireGuard range
*/
export declare function findAvailablePort(startPort?: number, endPort?: number): Promise<number>;
/**
* Get recommended WireGuard ports
*/
export declare function getRecommendedPorts(): number[];
/**
* Key Rotation Utilities (Feature 10)
*/
/**
* Rotate keys for a WireGuard configuration
*/
export declare function rotateKeys(config: WireGuardConfig, rotatePSK?: boolean): {
newConfig: WireGuardConfig;
oldKeys: {
privateKey: string;
publicKey: string;
psk?: string;
};
newKeys: {
privateKey: string;
publicKey: string;
psk?: string;
};
};
/**
* Generate key rotation plan
*/
export declare function generateKeyRotationPlan(configs: WireGuardConfig[]): {
rotationOrder: number[];
timeline: string;
instructions: string[];
};
/**
* Config Templates (Feature 11)
*/
/**
* Generate configuration from template
*/
export declare function generateFromTemplate(template: ConfigTemplate, options?: {
serverIP?: string;
clientIP?: string;
serverEndpoint?: string;
dns?: string[];
port?: number;
}): WireGuardConfig;
/**
* Get available templates with descriptions
*/
export declare function getAvailableTemplates(): Record<ConfigTemplate, string>;
/**
* Advanced Routing Configuration (Feature 22)
*/
/**
* Generate advanced routing configuration
*/
export declare function generateAdvancedRouting(options: {
networks: string[];
defaultRoute?: boolean;
splitTunnel?: boolean;
customRoutes?: RouteEntry[];
}): RoutingConfig;
/**
* Generate split tunnel configuration
*/
export declare function generateSplitTunnelConfig(privateNetworks?: string[], customNetworks?: string[]): RoutingConfig;
/**
* WireGuard Tunnel Management
*/
/**
* Start a WireGuard tunnel
*/
export declare function startWireGuardTunnel(configPath: string, interfaceName?: string): Promise<TunnelStatus>;
/**
* Stop a WireGuard tunnel
*/
export declare function stopWireGuardTunnel(configPath: string, interfaceName?: string): Promise<TunnelStatus>;
/**
* Get WireGuard tunnel status
*/
export declare function getTunnelStatus(interfaceName?: string): Promise<TunnelStatus>;
/**
* List all active WireGuard tunnels
*/
export declare function listActiveTunnels(): Promise<TunnelStatus[]>;