x3ui-api 1.0.4 → 1.0.5

package/README.md

@@ -16,6 +16,7 @@ npm install x3ui-api
 - Protocol-specific builders with fluent API:
   - VLESS with Reality support
   - VMess with HTTP Upgrade support
+  - WireGuard support
 - Client management with fluent API
 - TypeScript support
 
@@ -161,6 +162,67 @@ async function createRealityInbound() {
 }
 ```
 
+### Creating a WireGuard Inbound
+
+The library provides a convenient builder pattern for creating WireGuard inbounds:
+
+```javascript
+const X3UIClient = require('x3ui-api');
+const wireguard = require('x3ui-api/src/protocols/wireguard');
+
+const client = new X3UIClient({
+  baseURL: 'http://your-x3ui-panel.com:54321'
+});
+
+async function createWireguardInbound() {
+  try {
+    await client.login('admin', 'password');
+    
+    // Create a WireGuard inbound builder
+    let builder = new wireguard.WireguardBuilder(client)
+      .setRemark('My WireGuard Inbound')
+      .setPort(51820) // WireGuard port, will auto-generate if not provided
+      .setMtu(1420);   // Optional, default is 1420
+    
+    // Keys are automatically generated, but you can set them manually if needed
+    // builder.setSecretKey('your-base64-encoded-secret-key');
+    
+    // Add a client
+    const clientBuilder = builder.addClient()
+      .setEmail('user@example.com')
+      .setTotalGB(100) // 100 GB traffic limit
+      .setExpiryTime(Date.now() + 30 * 24 * 60 * 60 * 1000); // 30 days
+    
+    // Generate key pair for the client (or you can set them manually)
+    clientBuilder.generateKeyPair();
+    
+    // Set allowed IPs (default is 10.0.0.2/32)
+    clientBuilder.setAllowedIPs(['10.0.0.2/32']);
+    
+    // Optionally generate a pre-shared key for additional security
+    clientBuilder.generatePresharedKey();
+    
+    // Build and add the inbound
+    const inbound = await builder.build();
+    const createdInbound = await client.addInbound(inbound);
+    
+    // Update the builder with the server-returned inbound to get all metrics and IDs
+    builder = new wireguard.WireguardBuilder(client, createdInbound);
+    
+    console.log('Inbound created:', createdInbound);
+    
+    // Get WireGuard configuration for the client
+    const config = builder.getClientConfig(0, 'your-server-ip.com');
+    console.log('Client configuration:');
+    console.log(config);
+  } catch (error) {
+    console.error('Error creating inbound:', error.message);
+  }
+}
+
+createWireguardInbound();
+```
+
 ### Real-World Example
 
 Here's a complete example showing how to create a VMess inbound and get the client link:
@@ -313,6 +375,44 @@ Methods:
 - `getClientLink(clientIndex, host)` - Get connection link for a client
 - `build()` - Build the final inbound config
 
+#### WireGuard Builder
+
+```javascript
+const wireguard = require('x3ui-api/src/protocols/wireguard');
+const builder = new wireguard.WireguardBuilder(client, options);
+```
+
+Methods:
+- `setPort(port)` - Set the port for the inbound
+- `setRemark(remark)` - Set the name/remark for the inbound
+- `setMtu(mtu)` - Set the MTU value (default: 1420)
+- `setSecretKey(secretKey)` - Set the server's secret key (automatically generates if not provided)
+- `setNoKernelTun(noKernelTun)` - Set whether to disable kernel TUN support
+- `setSniffing(enabled, destOverride, metadataOnly, routeOnly)` - Configure sniffing
+- `setListenIP(ip)` - Set listen IP address
+- `setExpiryTime(timestamp)` - Set inbound expiry time
+- `addClient(options)` - Add a new client to the inbound
+- `getClientLink(clientIndex, host, port)` - Get connection link for a client
+- `getClientConfig(clientIndex, host, port)` - Get WireGuard configuration file content for a client
+- `build()` - Build the final inbound config
+
+##### WireGuard Client Builder
+
+Methods:
+- `setPrivateKey(privateKey)` - Set client's private key
+- `setPublicKey(publicKey)` - Set client's public key
+- `setPreSharedKey(preSharedKey)` - Set pre-shared key for additional security
+- `setAllowedIPs(allowedIPs)` - Set allowed IP ranges (default: ['10.0.0.2/32'])
+- `setKeepAlive(keepAlive)` - Set keep-alive interval in seconds
+- `generateKeyPair()` - Generate a new key pair for the client
+- `generatePresharedKey()` - Generate a new pre-shared key
+- `setEmail(email)` - Set client email
+- `setTotalGB(gb)` - Set total traffic limit in GB
+- `setExpiryTime(timestamp)` - Set client expiry time
+- `setTgId(id)` - Set Telegram ID
+- `getLink(host, port)` - Get WireGuard configuration as text
+- `getConfigFile(host, port)` - Get WireGuard configuration file content
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "x3ui-api",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "description": "API client for x3ui panel",
   "main": "src/index.js",
   "types": "src/index.d.ts",

package/src/protocols/wireguard/WireguardBuilder.d.ts

@@ -0,0 +1,118 @@
+import WireguardClientBuilder from './WireguardClientBuilder';
+import {ClientSettings} from "../../index";
+
+/**
+ * WireguardBuilder class for creating and managing Wireguard server configurations.
+ * This builder provides a fluent interface for setting up Wireguard servers and managing clients.
+ */
+export default class WireguardBuilder {
+    /**
+     * Creates a new WireguardBuilder instance.
+     * @param client - The client connection or context to use for building the configuration
+     * @param options - Optional configuration parameters for the Wireguard server
+     */
+    constructor(client: any, options?: any);
+
+    /**
+     * Sets the port for the Wireguard server.
+     * @param port - The port number to listen on
+     * @returns The current builder instance for method chaining
+     */
+    setPort(port: number): this;
+    
+    /**
+     * Sets a descriptive remark for the Wireguard server.
+     * @param remark - The remark or name for this server
+     * @returns The current builder instance for method chaining
+     */
+    setRemark(remark: string): this;
+    
+    /**
+     * Sets the Maximum Transmission Unit (MTU) size.
+     * @param mtu - The MTU value in bytes
+     * @returns The current builder instance for method chaining
+     */
+    setMtu(mtu: number): this;
+    
+    /**
+     * Sets the server's private key.
+     * @param secretKey - The Wireguard private key in base64 format
+     * @returns The current builder instance for method chaining
+     */
+    setSecretKey(secretKey: string): this;
+    
+    /**
+     * Configures whether to use kernel TUN interface or userspace implementation.
+     * @param noKernelTun - If true, uses userspace implementation instead of kernel TUN
+     * @returns The current builder instance for method chaining
+     */
+    setNoKernelTun(noKernelTun: boolean): this;
+    
+    /**
+     * Configures traffic sniffing options.
+     * @param enabled - Whether sniffing is enabled
+     * @param destOverride - Array of protocols to override destination with sniffed value
+     * @param metadataOnly - If true, only sniffs metadata
+     * @param routeOnly - If true, only uses sniffed information for routing
+     * @returns The current builder instance for method chaining
+     */
+    setSniffing(enabled: boolean, destOverride?: string[], metadataOnly?: boolean, routeOnly?: boolean): this;
+    
+    /**
+     * Sets the IP address the server listens on.
+     * @param ip - The IP address to bind to
+     * @returns The current builder instance for method chaining
+     */
+    setListenIP(ip: string): this;
+    
+    /**
+     * Sets the expiration time for the server configuration.
+     * @param timestamp - Unix timestamp when the configuration expires
+     * @returns The current builder instance for method chaining
+     */
+    setExpiryTime(timestamp: number): this;
+    
+    /**
+     * Creates and adds a new client to this Wireguard server.
+     * @param options - Optional client settings
+     * @returns A new WireguardClientBuilder instance for configuring the client
+     */
+    addClient(options?: Partial<ClientSettings>): WireguardClientBuilder;
+    
+    /**
+     * Generates a connection link for a client.
+     * @param clientIndex - Index of the client (default: 0)
+     * @param host - Host address to use in the link (defaults to server address)
+     * @param port - Port to use in the link (defaults to server port)
+     * @returns A formatted connection link string
+     */
+    getClientLink(clientIndex?: number, host?: string, port?: number): string;
+    
+    /**
+     * Generates a configuration file for a client.
+     * @param clientIndex - Index of the client (default: 0)
+     * @param host - Host address to use in the config (defaults to server address)
+     * @param port - Port to use in the config (defaults to server port)
+     * @returns A formatted configuration file content as string
+     */
+    getClientConfig(clientIndex?: number, host?: string, port?: number): string;
+    
+    /**
+     * Generates a random port number for the Wireguard server.
+     * @returns A random port number
+     */
+    generateRandomPort(): number;
+    
+    /**
+     * Derives the public key from a given private key.
+     * @param secretKey - The Wireguard private key in base64 format
+     * @returns The corresponding public key in base64 format
+     */
+    derivePublicKey(secretKey: string): string;
+    
+    /**
+     * Builds and finalizes the Wireguard server configuration.
+     * @returns A Promise that resolves to the built configuration
+     */
+    build(): Promise<any>;
+}

package/src/protocols/wireguard/WireguardBuilder.js

@@ -0,0 +1,204 @@
+const keyUtils = require('./keyUtils');
+const WireguardClientBuilder = require('./WireguardClientBuilder');
+
+module.exports = class WireguardBuilder {
+    constructor(client, options = {}) {
+        this.client = client;
+        // Initialize from InboundConfig
+        this.id = options.id || undefined;
+        this.port = options.port || 0;
+        this.remark = options.remark || '';
+        this.listenIP = options.listen || '';
+        this.expiryTime = options.expiryTime || 0;
+        this.enable = true;
+        this.up = options.up || 0;
+        this.down = options.down || 0;
+        this.total = options.total || 0;
+
+        // Initialize WireGuard specific settings
+        const settings = typeof options.settings === 'string'
+            ? JSON.parse(options.settings)
+            : options.settings || {};
+
+        this.mtu = settings.mtu || 1420;
+        this.secretKey = settings.secretKey || '';
+        this.publicKey = ''; // Will be derived from secretKey
+        this.noKernelTun = settings.noKernelTun || false;
+
+        // Initialize sniffing
+        this.sniffing = options.sniffing || {
+            enabled: false,
+            destOverride: ['http', 'tls', 'quic', 'fakedns'],
+            metadataOnly: false,
+            routeOnly: false
+        };
+
+        // Initialize allocate
+        this.allocate = options.allocate || {
+            strategy: 'always',
+            refresh: 5,
+            concurrency: 3
+        };
+
+        // Initialize clients
+        this.clients = [];
+        
+        if (settings?.peers) {
+            settings.peers.forEach(peer => {
+                this.addClient(peer);
+            });
+        }
+
+        // If secretKey is provided, derive publicKey
+        if (this.secretKey) {
+            this.publicKey = keyUtils.derivePublicKey(this.secretKey);
+        }
+
+        // If no secretKey provided, generate one
+        if (!this.secretKey) {
+            let pair = keyUtils.generateKeyPair();
+            this.secretKey = pair.privateKey;
+            this.publicKey = pair.publicKey;
+        }
+    }
+
+    setPort(port) {
+        this.port = port;
+        return this;
+    }
+
+    setRemark(remark) {
+        this.remark = remark;
+        return this;
+    }
+
+    setMtu(mtu) {
+        this.mtu = mtu;
+        return this;
+    }
+
+    setSecretKey(secretKey) {
+        this.secretKey = secretKey;
+        this.publicKey = keyUtils.derivePublicKey(secretKey);
+        return this;
+    }
+
+    setNoKernelTun(noKernelTun) {
+        this.noKernelTun = noKernelTun;
+        return this;
+    }
+
+    setSniffing(enabled, destOverride = ['http', 'tls', 'quic', 'fakedns'], metadataOnly = false, routeOnly = false) {
+        this.sniffing = {
+            enabled,
+            destOverride,
+            metadataOnly,
+            routeOnly
+        };
+        return this;
+    }
+
+    setListenIP(ip) {
+        this.listenIP = ip;
+        return this;
+    }
+
+    setExpiryTime(timestamp) {
+        this.expiryTime = timestamp;
+        return this;
+    }
+
+    addClient(options = {}) {
+        const builder = new WireguardClientBuilder(this);
+        if (options.privateKey) builder.setPrivateKey(options.privateKey);
+        if (options.publicKey) builder.setPublicKey(options.publicKey);
+        if (options.preSharedKey) builder.setPreSharedKey(options.preSharedKey);
+        if (options.allowedIPs) builder.setAllowedIPs(options.allowedIPs);
+        if (options.keepAlive !== undefined) builder.setKeepAlive(options.keepAlive);
+        if (options.email) builder.setEmail(options.email);
+        if (options.totalGB) builder.setTotalGB(options.totalGB);
+        if (options.expiryTime) builder.setExpiryTime(options.expiryTime);
+        if (options.tgId) builder.setTgId(options.tgId);
+        
+        this.clients.push(builder);
+        return builder;
+    }
+
+    getClientLink(clientIndex = 0, host, port) {
+        if (clientIndex < 0 || clientIndex >= this.clients.length) {
+            throw new Error('Invalid client index');
+        }
+        const client = this.clients[clientIndex];
+        return client.getLink(host || this.listenIP || 'localhost', port || this.port);
+    }
+
+    getClientConfig(clientIndex = 0, host, port) {
+        if (clientIndex < 0 || clientIndex >= this.clients.length) {
+            throw new Error('Invalid client index');
+        }
+        const client = this.clients[clientIndex];
+        return client.getConfigFile(host || this.listenIP || 'localhost', port || this.port);
+    }
+
+    generateRandomPort() {
+        return Math.floor(Math.random() * (65535 - 1024) + 1024);
+    }
+
+    async build() {
+        if (!this.remark) {
+            throw new Error('Remark is required');
+        }
+
+        // If no port specified, find unused one
+        if (!this.port) {
+            const inbounds = await this.client.getInbounds();
+            const usedPorts = new Set(inbounds.map(i => i.port));
+            let port;
+            do {
+                port = this.generateRandomPort();
+            } while (usedPorts.has(port));
+            this.port = port;
+        }
+
+        // If no secretKey provided, generate one
+        if (!this.secretKey) {
+            this.secretKey = keyUtils.generatePrivateKey();
+            this.publicKey = keyUtils.derivePublicKey(this.secretKey);
+        }
+
+        // If no clients added, create one default client
+        if (this.clients.length === 0) {
+            this.addClient();
+        }
+
+        // Build all clients
+        const clientConfigs = await Promise.all(this.clients.map(builder => builder.build()));
+
+        // Create tag for inbound
+        const tag = `inbound-${this.port}`;
+
+        // Build the complete inbound configuration
+        return {
+            id: this.id,
+            up: this.up,
+            down: this.down,
+            total: this.total,
+            remark: this.remark,
+            enable: this.enable,
+            expiryTime: this.expiryTime,
+            listen: this.listenIP,
+            port: this.port,
+            protocol: 'wireguard',
+            settings: {
+                mtu: this.mtu,
+                secretKey: this.secretKey,
+                peers: clientConfigs,
+                noKernelTun: this.noKernelTun
+            },
+            streamSettings: {},
+            tag,
+            sniffing: this.sniffing,
+            allocate: this.allocate
+        };
+    }
+}

package/src/protocols/wireguard/WireguardClientBuilder.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Type definitions for WireguardClientBuilder
+ * Provides functionality for building WireGuard client configurations
+ */
+import ClientBuilder from '../../core/ClientBuilder';
+
+/**
+ * WireguardClientBuilder class for creating and managing WireGuard client configurations
+ * Extends the base ClientBuilder to provide WireGuard-specific functionality
+ */
+export default class WireguardClientBuilder extends ClientBuilder {
+    /**
+     * Creates a new WireguardClientBuilder instance
+     * @param parent - The parent object that owns this builder
+     * @param options - Optional client settings
+     */
+    constructor(parent: any, options?: any);
+
+    /**
+     * Sets the client's private key
+     * @param privateKey - The WireGuard private key in base64 format
+     * @returns The builder instance for method chaining
+     */
+    setPrivateKey(privateKey: string): this;
+    
+    /**
+     * Sets the server's public key
+     * @param publicKey - The WireGuard public key in base64 format
+     * @returns The builder instance for method chaining
+     */
+    setPublicKey(publicKey: string): this;
+    
+    /**
+     * Sets the pre-shared key for additional security
+     * @param preSharedKey - The pre-shared key in base64 format
+     * @returns The builder instance for method chaining
+     */
+    setPreSharedKey(preSharedKey: string): this;
+    
+    /**
+     * Sets the allowed IP addresses/ranges for routing through the tunnel
+     * @param allowedIPs - Array of IP addresses/ranges in CIDR notation
+     * @returns The builder instance for method chaining
+     */
+    setAllowedIPs(allowedIPs: string[]): this;
+    
+    /**
+     * Sets the persistent keepalive interval
+     * @param keepAlive - Interval in seconds between keepalive packets
+     * @returns The builder instance for method chaining
+     */
+    setKeepAlive(keepAlive: number): this;
+
+    /**
+     * Generates a random pre-shared key
+     * @returns The builder instance for method chaining
+     */
+    generatePresharedKey(): this;
+
+    /**
+     * Generates a new public/private key pair
+     * @returns The builder instance for method chaining
+     */
+    generateKeyPair(): this;
+
+    /**
+     * Builds and returns the complete WireGuard client configuration
+     * @returns The WireGuard client configuration object
+     */
+    build(): any;
+    
+    /**
+     * Generates a WireGuard connection URI/link for easy client configuration
+     * @param host - The server hostname or IP address
+     * @param port - The server port number
+     * @returns A WireGuard connection URI string
+     */
+    getLink(host: string, port: number): string;
+}

package/src/protocols/wireguard/WireguardClientBuilder.js

@@ -0,0 +1,88 @@
+const crypto = require("crypto");
+const keyUtils = require('./keyUtils');
+const ClientBuilder = require('./../../core/ClientBuilder');
+
+module.exports = class WireguardClientBuilder extends ClientBuilder {
+    constructor(parent, options) {
+        super(parent);
+        this.privateKey = options.privateKey || '';
+        this.publicKey = options.publicKey || '';
+        this.preSharedKey = options.preSharedKey || '';
+        this.allowedIPs = options.allowedIPs || ['10.0.0.2/32'];
+        this.keepAlive = options.keepAlive || 0;
+    }
+
+    setPrivateKey(privateKey) {
+        this.privateKey = privateKey;
+        return this;
+    }
+
+    setPublicKey(publicKey) {
+        this.publicKey = publicKey;
+        return this;
+    }
+
+    setPreSharedKey(preSharedKey) {
+        this.preSharedKey = preSharedKey;
+        return this;
+    }
+
+    setAllowedIPs(allowedIPs) {
+        this.allowedIPs = allowedIPs;
+        return this;
+    }
+
+    setKeepAlive(keepAlive) {
+        this.keepAlive = keepAlive;
+        return this;
+    }
+
+    generatePresharedKey() {
+        this.preSharedKey = keyUtils.generatePresharedKey();
+        return this;
+    }
+
+    generateKeyPair() {
+        const keyPair = keyUtils.generateKeyPair();
+        this.privateKey = keyPair.privateKey;
+        this.publicKey = keyPair.publicKey;
+        return this;
+    }
+
+    build() {
+        const baseConfig = super.build();
+        return {
+            ...baseConfig,
+            privateKey: this.privateKey || '',
+            publicKey: this.publicKey || '',
+            preSharedKey: this.preSharedKey || '',
+            allowedIPs: this.allowedIPs,
+            keepAlive: this.keepAlive
+        };
+    }
+
+    getLink(host, port) {
+        // Generate WireGuard client configuration
+        const serverPublicKey = this.parent.secretKey ? 
+            this.parent.publicKey : 
+            'MISSING_SERVER_PUBLIC_KEY';
+
+        const config = [
+            '[Interface]',
+            `PrivateKey = ${this.privateKey}`,
+            `Address = ${this.allowedIPs[0]}`,
+            'DNS = 1.1.1.1, 1.0.0.1',
+            `MTU = ${this.parent.mtu || 1420}`,
+            '',
+            `# ${this.parent.remark || 'WireGuard'}-${this.email || 'default'}`,
+            '[Peer]',
+            `PublicKey = ${serverPublicKey}`,
+            'AllowedIPs = 0.0.0.0/0, ::/0',
+            `Endpoint = ${host}:${port}`,
+            this.preSharedKey ? `PresharedKey = ${this.preSharedKey}` : '',
+        ].filter(Boolean).join('\n');
+
+        // Return the configuration as a data URI
+        return config;
+    }
+}

package/src/protocols/wireguard/index.d.ts

@@ -0,0 +1,9 @@
+import WireguardBuilder from "./WireguardBuilder";
+import WireguardClientBuilder from "./WireguardClientBuilder";
+
+declare const _default: {
+    WireguardBuilder: typeof WireguardBuilder;
+    WireguardClientBuilder: typeof WireguardClientBuilder;
+};
+
+export default _default;

package/src/protocols/wireguard/index.js

@@ -0,0 +1,4 @@
+module.exports = {
+    WireguardBuilder: require('./WireguardBuilder'),
+    WireguardClientBuilder: require('./WireguardClientBuilder')
+}

package/src/protocols/wireguard/keyUtils.js

@@ -0,0 +1,95 @@
+/**
+ * WireGuard key utilities
+ * Pure JavaScript implementation of Curve25519 for WireGuard key generation
+ */
+
+const crypto = require('crypto');
+
+/**
+ * Generate a new WireGuard private key
+ * @returns {string} Base64-encoded private key
+ */
+function generatePrivateKey() {
+    const key = crypto.randomBytes(32);
+    return key.toString('base64');
+}
+
+/**
+ * Generate a new WireGuard pre-shared key
+ * @returns {string} Base64-encoded pre-shared key
+ */
+function generatePresharedKey() {
+    const key = crypto.randomBytes(32);
+    return key.toString('base64');
+}
+
+/**
+ * Derive a public key from a private key using Curve25519
+ * @param {string} privateKeyBase64 Base64-encoded private key
+ * @returns {string} Base64-encoded public key
+ */
+function derivePublicKey(privateKeyBase64) {
+    const privateKey = Buffer.from(privateKeyBase64, 'base64');
+    const publicKey = crypto.createPublicKey({
+        key: crypto.createPrivateKey({
+            key: Buffer.concat([
+                Buffer.from('302e020100300506032b656e04220420', 'hex'),
+                privateKey
+            ]),
+            format: 'der',
+            type: 'pkcs8'
+        }),
+        format: 'der',
+        type: 'spki'
+    }).export({ format: 'der', type: 'spki' });
+
+    // Extract the raw public key bytes
+    return publicKey.slice(-32).toString('base64');
+}
+
+/**
+ * Generate a new WireGuard key pair
+ * @returns {Object} Object containing privateKey and publicKey in base64 format
+ */
+function generateKeyPair() {
+    const privateKey = generatePrivateKey();
+    const publicKey = derivePublicKey(privateKey);
+    return { privateKey, publicKey };
+}
+
+/**
+ * Validate a WireGuard private key
+ * @param {string} privateKeyBase64 Base64-encoded private key
+ * @returns {boolean} True if valid, false otherwise
+ */
+function isValidPrivateKey(privateKeyBase64) {
+    try {
+        const buf = Buffer.from(privateKeyBase64, 'base64');
+        return buf.length === 32;
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Validate a WireGuard public key
+ * @param {string} publicKeyBase64 Base64-encoded public key
+ * @returns {boolean} True if valid, false otherwise
+ */
+function isValidPublicKey(publicKeyBase64) {
+    try {
+        const buf = Buffer.from(publicKeyBase64, 'base64');
+        return buf.length === 32;
+    } catch {
+        return false;
+    }
+}
+
+module.exports = {
+    generatePrivateKey,
+    generatePresharedKey,
+    derivePublicKey,
+    generateKeyPair,
+    isValidPrivateKey,
+    isValidPublicKey
+};