3xui-api-client 3.0.1 → 3.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "3xui-api-client",
-  "version": "3.0.1",
+  "version": "3.1.0",
   "description": "A Node.js client library for 3x-ui panel API with built-in credential generation, session management, and web integration support",
   "main": "index.js",
   "types": "index.d.ts",
@@ -12,13 +12,8 @@
     }
   },
   "scripts": {
-    "test": "node test/main-test.js",
+    "test": "echo \"No automated tests configured. Tests require a live panel environment.\"",
     "test:jest": "jest",
-    "test:manual": "node test/main-test.js",
-    "test:main": "node test/main-test.js",
-    "test:login": "node test/login-test.js",
-    "test:inbounds": "node test/inbounds-test.js",
-    "test:create": "node test/create-inbound-test.js",
     "lint": "eslint index.js src/",
     "prepublishOnly": "echo 'Skipping tests for publishing'"
   },
@@ -93,7 +88,8 @@
     "dotenv": "^16.5.0",
     "jest": "^29.7.0",
     "eslint": "^9.0.0",
-    "@eslint/js": "^9.0.0"
+    "@eslint/js": "^9.0.0",
+    "chai": "^4.3.4"
   },
   "jest": {
     "testEnvironment": "node",

package/src/generators/CredentialGenerator.js

@@ -101,25 +101,30 @@ class CredentialGenerator {
         return keyBytes.toString('base64');
     }
 
+    /**
+     * Generate a Curve25519 (X25519) key pair using Node's crypto module
+     * @returns {{privateKeyBytes: Buffer, publicKeyBytes: Buffer}} Raw 32-byte key pair
+     */
+    static _generateX25519KeyPair() {
+        const { publicKey, privateKey } = crypto.generateKeyPairSync('x25519');
+        const privateJwk = privateKey.export({ format: 'jwk' });
+        const publicJwk = publicKey.export({ format: 'jwk' });
+
+        return {
+            privateKeyBytes: Buffer.from(privateJwk.d, 'base64url'),
+            publicKeyBytes: Buffer.from(publicJwk.x, 'base64url')
+        };
+    }
+
     /**
      * Generate WireGuard key pair
      * @returns {Object} Object containing private and public keys
      */
     static generateWireGuardKeys() {
-        // Generate 32 random bytes for private key
-        const privateKeyBytes = crypto.randomBytes(32);
-
-        // Clamp the private key (standard WireGuard key clamping)
-        privateKeyBytes[0] &= 248;
-        privateKeyBytes[31] &= 127;
-        privateKeyBytes[31] |= 64;
+        // WireGuard uses Curve25519 (X25519) key pairs encoded as standard base64
+        const { privateKeyBytes, publicKeyBytes } = this._generateX25519KeyPair();
 
         const privateKey = privateKeyBytes.toString('base64');
-
-        // For the public key, we would normally use Curve25519 scalar multiplication
-        // This is a simplified implementation - in production, use a proper crypto library
-        // like noble-curves or libsodium for accurate public key derivation
-        const publicKeyBytes = crypto.randomBytes(32); // Placeholder
         const publicKey = publicKeyBytes.toString('base64');
 
         return {
@@ -140,13 +145,11 @@ class CredentialGenerator {
      * @returns {Object} Object containing private and public keys
      */
     static generateRealityKeys() {
-        // Reality uses X25519 key exchange
-        const privateKeyBytes = crypto.randomBytes(32);
-        const privateKey = privateKeyBytes.toString('base64').replace(/\//g, '_').replace(/\+/g, '-');
+        // Reality uses X25519 key exchange, keys encoded as base64url without padding
+        const { privateKeyBytes, publicKeyBytes } = this._generateX25519KeyPair();
 
-        // Public key derivation (simplified - use proper X25519 in production)
-        const publicKeyBytes = crypto.randomBytes(32);
-        const publicKey = publicKeyBytes.toString('base64').replace(/\//g, '_').replace(/\+/g, '-');
+        const privateKey = privateKeyBytes.toString('base64url');
+        const publicKey = publicKeyBytes.toString('base64url');
 
         return {
             privateKey,

package/src/session/SessionManager.js

@@ -34,6 +34,13 @@ class SessionStore {
 /**
  * Built-in memory session store (default)
  * Recommended for development and single-instance deployments
+ *
+ * Security note: session cookies are stored as plain JavaScript objects in
+ * process memory — unencrypted. The cookie grants full admin access to the
+ * 3x-ui panel and should be treated as a high-value secret. In shared or
+ * multi-tenant Node.js processes a heap dump or memory inspection can expose
+ * a live session. For production workloads consider a Redis or Database store
+ * protected by appropriate infrastructure-level access controls.
  */
 class MemorySessionStore extends SessionStore {
     constructor() {
@@ -175,6 +182,14 @@ class RedisSessionStore extends SessionStore {
 /**
  * Database session store adapter
  * Works with any SQL database through a provided database client
+ *
+ * Security note: session data (including the 3x-ui admin cookie) is
+ * persisted as `session_data TEXT` — unencrypted. Anyone with read access
+ * to the session table can extract a live admin-equivalent credential.
+ * Restrict table access with the least-privilege DB user possible, and
+ * consider enabling encryption at rest for the database. The session key
+ * column (sha256 hash) also allows correlation of rows to specific
+ * panels/users — see generateSessionKey() for details.
  */
 class DatabaseSessionStore extends SessionStore {
     constructor(database, options = {}) {
@@ -365,7 +380,15 @@ class SessionManager {
     }
 
     /**
-     * Generate session key for a server
+     * Generate a deterministic cache key for a given panel + username pair.
+     *
+     * The key is sha256(baseURL:username) — intentionally predictable so that
+     * the same panel session can be looked up across restarts. It is NOT a
+     * security secret: anyone with read access to the session store can
+     * correlate rows back to a specific panel/user. Treat the *value* stored
+     * under this key (the session cookie) as the sensitive material that must
+     * be protected at the infrastructure level (access control, encryption at
+     * rest, etc.), not the key itself.
      */
     generateSessionKey(baseURL, username) {
         const hash = crypto

package/src/utils/ByteConversion.js

@@ -0,0 +1,132 @@
+/**
+ * Byte Conversion Utilities
+ *
+ * Converts bandwidth/storage values to bytes for consistent handling
+ * in the 3x-ui API which expects all data limits in bytes internally.
+ */
+
+const UNITS = {
+    B: 1,
+    KB: 1024,
+    MB: 1024 ** 2,
+    GB: 1024 ** 3,
+    TB: 1024 ** 4
+};
+
+/**
+ * Convert gigabytes to bytes
+ * @param {number} gb - Gigabytes value
+ * @returns {number} Value in bytes
+ */
+function gbToBytes(gb) {
+    if (typeof gb !== 'number' || gb < 0) {
+        throw new Error(`Invalid GB value: ${gb}. Must be a non-negative number.`);
+    }
+    return gb * UNITS.GB;
+}
+
+/**
+ * Convert bytes to gigabytes
+ * @param {number} bytes - Bytes value
+ * @returns {number} Value in gigabytes
+ */
+function bytesToGb(bytes) {
+    if (typeof bytes !== 'number' || bytes < 0) {
+        throw new Error(`Invalid byte value: ${bytes}. Must be a non-negative number.`);
+    }
+    return bytes / UNITS.GB;
+}
+
+/**
+ * Format bytes to human-readable format
+ * @param {number} bytes - Bytes value
+ * @param {number} decimals - Decimal places (default: 2)
+ * @returns {string} Formatted string like "1.5 GB"
+ */
+function formatBytes(bytes, decimals = 2) {
+    if (typeof bytes !== 'number' || bytes < 0) {
+        return '0 B';
+    }
+
+    const units = ['B', 'KB', 'MB', 'GB', 'TB'];
+    let size = bytes;
+    let unitIndex = 0;
+
+    while (size >= 1024 && unitIndex < units.length - 1) {
+        size /= 1024;
+        unitIndex++;
+    }
+
+    return `${size.toFixed(decimals)} ${units[unitIndex]}`;
+}
+
+/**
+ * Safely convert totalGB option to bytes with warning for suspiciously small values
+ * @param {number|undefined} totalGbValue - The totalGB value from options
+ * @returns {number} Value in bytes (0 if undefined/null)
+ */
+function sanitizeTotalGb(totalGbValue) {
+    if (totalGbValue === undefined || totalGbValue === null) {
+        return 0;
+    }
+
+    if (typeof totalGbValue !== 'number') {
+        throw new Error(`Invalid totalGB value: ${totalGbValue}. Must be a number.`);
+    }
+
+    // Warn if the value looks suspiciously small (likely a user error)
+    if (totalGbValue > 0 && totalGbValue < 1) {
+        console.warn(
+            '⚠️  WARNING: totalGB is set to ' + totalGbValue + '. ' +
+            'This will be converted to ' + gbToBytes(totalGbValue) + ' bytes. ' +
+            'If you meant ' + totalGbValue + ' gigabytes, this is correct. ' +
+            'If you meant something else, please check your value.'
+        );
+    }
+
+    return gbToBytes(totalGbValue);
+}
+
+/**
+ * Process options object to convert all bandwidth-related fields to bytes
+ * Converts: totalGB → totalGB (in bytes)
+ * @param {Object} options - Options object
+ * @returns {Object} New object with converted values
+ */
+function convertBandwidthFields(options) {
+    if (!options || typeof options !== 'object') {
+        return options;
+    }
+
+    const converted = { ...options };
+
+    // Convert totalGB if present
+    if (converted.totalGB !== undefined && converted.totalGB !== null) {
+        converted.totalGB = sanitizeTotalGb(converted.totalGB);
+    }
+
+    return converted;
+}
+
+/**
+ * Process array of options objects for bulk operations
+ * @param {Array<Object>} optionsArray - Array of option objects
+ * @returns {Array<Object>} New array with converted values
+ */
+function convertBandwidthFieldsBulk(optionsArray) {
+    if (!Array.isArray(optionsArray)) {
+        return optionsArray;
+    }
+
+    return optionsArray.map(convertBandwidthFields);
+}
+
+module.exports = {
+    gbToBytes,
+    bytesToGb,
+    formatBytes,
+    sanitizeTotalGb,
+    convertBandwidthFields,
+    convertBandwidthFieldsBulk,
+    UNITS
+};