@qpjoy/tunnel-cli 0.1.2 → 0.1.4

package/README.md

@@ -1,6 +1,7 @@
 # @qpjoy/tunnel-cli
 
-Global CLI wrapper for the QPJoy Linux `mihomo-client` server script.
+Global CLI wrapper for the QPJoy Linux `mihomo-client` server script and
+cross-platform headless HDO mesh enrollment.
 
 ```bash
 npm i -g @qpjoy/tunnel-cli
@@ -8,8 +9,62 @@ qp-tunnel-cli help
 ```
 
 The package ships the existing `scripts/mihomo-client.sh` file in the npm
-tarball. It does not reimplement the Linux systemd, proxy, SSH, daemon, or TUN
-orchestration in Node.
+tarball. It also depends on `@qpjoy/electron-core-wireguard`, which resolves the
+matching platform engine package such as darwin-arm64, linux-x64, or win32-x64.
+The core WireGuard package is consumed as-is; this CLI does not modify its HDO
+plugin behavior.
+
+## HDO Mesh Enrollment
+
+For macOS, Windows, or a headless Linux machine such as an Internal/company
+server, enroll into the HDO mesh without installing Electron:
+
+```bash
+npm i -g @qpjoy/tunnel-cli
+HDO_PASSWORD='<password>' qp-tunnel-cli hdo enroll \
+  --server-url 'https://domestic.example.com' \
+  --username 'internal-i' \
+  --device-id internal-i \
+  --label 'Internal I'
+```
+
+On Linux, run the same command through `sudo -E` because it writes
+`/etc/wireguard` and enables `wg-quick@hdo-internal`:
+
+```bash
+HDO_PASSWORD='<password>' sudo -E qp-tunnel-cli hdo enroll \
+  --server-url 'https://domestic.example.com' \
+  --username 'internal-i'
+```
+
+The command:
+
+- logs in with username/password, or uses `--token` when provided
+- uses `@qpjoy/electron-core-wireguard` to find/install the platform WireGuard engine
+- registers the machine as an HDO device
+- downloads the HDO manifest from `electron-server`
+- writes a local WireGuard config
+- stores local HDO state and refresh credentials
+- starts a system-level tunnel at boot
+
+Useful follow-up commands:
+
+```bash
+qp-tunnel-cli hdo status
+qp-tunnel-cli hdo refresh
+qp-tunnel-cli hdo down
+```
+
+Platform behavior:
+
+- Linux: writes `/etc/wireguard/hdo-internal.conf` and enables `wg-quick@hdo-internal`
+- macOS: installs a LaunchDaemon and may prompt for an administrator password
+- Windows: installs a WireGuard tunnel service and may show a UAC prompt
+
+Current MVP authentication accepts either username/password or the same bearer
+token used by the HDO API. Production enrollment should move to short-lived
+enrollment tokens and durable service tokens so external systems do not need to
+handle user session JWTs.
 
 ## Server Usage
 

package/README.setup.md

@@ -1,10 +1,16 @@
 ```bash
-npm i -g @qpjoy/tunnel-cli@0.1.1
+npm i -g @qpjoy/tunnel-cli@0.1.4
+HDO_PASSWORD='...' qp-tunnel-cli hdo enroll --server-url 'https://domestic.example.com' --username internal-i
+
+qp-tunnel-cli install --url 'http://user:pass@host:3434/peer_xxx.mihomo.yaml'
 
 sudo qp-tunnel-cli install-script
 sudo qp-tunnel-cli upgrade-systemd
+sudo qp-tunnel-cli server-on
 
 sudo qp-tunnel-cli tun-off
 sudo qp-tunnel-cli server-on
 sudo qp-tunnel-cli status
-```
+
+qp-tunnel-cli curl google.com
+```

package/dist/hdo.d.ts

@@ -0,0 +1,6 @@
+interface HdoCliContext {
+    isRoot(): boolean;
+    sudoSelf(args: string[]): never;
+}
+export declare function runHdoCli(args: string[], ctx: HdoCliContext): Promise<void>;
+export {};

package/dist/hdo.js

@@ -0,0 +1,623 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runHdoCli = runHdoCli;
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const electron_core_wireguard_1 = require("@qpjoy/electron-core-wireguard");
+const defaultInterfaceName = 'hdo-internal';
+async function runHdoCli(args, ctx) {
+    const command = args[0] ?? 'help';
+    const rest = args.slice(1);
+    if (command === 'help' || command === '--help' || command === '-h') {
+        hdoHelp();
+        return;
+    }
+    if (process.platform === 'linux' && !ctx.isRoot()) {
+        ctx.sudoSelf(['hdo', ...args]);
+    }
+    switch (command) {
+        case 'enroll':
+        case 'refresh':
+            await enrollCommand(rest, command === 'refresh');
+            return;
+        case 'status':
+            statusCommand(parseStateFileArg(rest));
+            return;
+        case 'down':
+            await downCommand(parseStateFileArg(rest));
+            return;
+        default:
+            process.stderr.write(`Unknown hdo command: ${command}\n\n`);
+            hdoHelp();
+            process.exitCode = 1;
+    }
+}
+function hdoHelp() {
+    process.stdout.write(`QPJoy HDO CLI
+
+Usage:
+  qp-tunnel-cli hdo enroll --server-url URL --username USER [options]
+  qp-tunnel-cli hdo enroll --server-url URL --token TOKEN [options]
+  qp-tunnel-cli hdo refresh [--server-url URL] [--username USER]
+  qp-tunnel-cli hdo status
+  qp-tunnel-cli hdo down
+
+Enroll options:
+  --server-url URL       HDO/electron-server base URL
+  --username USER        Login username/email/phone
+  --password PASS        Login password. Prefer HDO_PASSWORD or --password-file
+  --password-file PATH   Read login password from a file
+  --token TOKEN          Existing bearer token for the HDO API
+  --token-file PATH      Read bearer token from a file
+  --device-id ID         Stable device id. Default: hdo-<platform>-<hostname>
+  --label LABEL          Device label. Default: <platform> <hostname>
+  --interface NAME       WireGuard interface/config name. Default: hdo-internal
+  --config-path PATH     WireGuard config path
+  --install-dir PATH     WireGuard engine install/cache directory
+  --state-file PATH      HDO client state file
+  --role ROLE            Metadata role. Default: internal
+  --rotate-key           Generate a new WireGuard keypair
+  --no-start             Write config without starting the system tunnel
+
+Environment:
+  HDO_SERVER_URL / QPJOY_HDO_SERVER_URL
+  HDO_USERNAME / QPJOY_HDO_USERNAME
+  HDO_PASSWORD / QPJOY_HDO_PASSWORD
+  HDO_TOKEN / QPJOY_HDO_TOKEN
+
+Examples:
+  qp-tunnel-cli hdo enroll \\
+    --server-url https://domestic.example.com \\
+    --username user@example.com
+
+  HDO_PASSWORD='...' qp-tunnel-cli hdo enroll \\
+    --server-url https://domestic.example.com \\
+    --username internal-i
+
+Notes:
+  Linux writes /etc/wireguard and enables wg-quick@<interface>.
+  macOS installs a LaunchDaemon and may prompt for an administrator password.
+  Windows installs a WireGuard tunnel service and may show a UAC prompt.
+`);
+}
+async function enrollCommand(args, refreshOnly) {
+    const options = parseEnrollOptions(args);
+    const stateFile = resolveStateFile(options.stateFile);
+    const previous = readState(stateFile);
+    const interfaceName = sanitizeInterfaceName(options.interfaceName || previous.interfaceName || defaultInterfaceName);
+    const configPath = resolveConfigPath(options.configPath || previous.configPath, interfaceName);
+    const installDir = resolveInstallDir(options.installDir || previous.installDir);
+    const serverUrl = normalizeBaseUrl(options.serverUrl ??
+        process.env.HDO_SERVER_URL ??
+        process.env.QPJOY_HDO_SERVER_URL ??
+        previous.serverUrl);
+    const username = options.username ??
+        process.env.HDO_USERNAME ??
+        process.env.QPJOY_HDO_USERNAME ??
+        previous.username;
+    if (!serverUrl) {
+        throw new Error('Missing --server-url or HDO_SERVER_URL.');
+    }
+    const auth = await resolveAuth(serverUrl, options, previous, username);
+    const deviceId = options.deviceId ||
+        previous.deviceId ||
+        `hdo-${process.platform}-${sanitizeId((0, node_os_1.hostname)())}`;
+    const label = options.label || previous.label || `${process.platform} ${(0, node_os_1.hostname)()}`;
+    const keys = resolveKeypair(options, previous, installDir);
+    const registered = await apiJson(serverUrl, auth.accessToken, '/api/v1/hdo/devices/register', {
+        method: 'POST',
+        body: {
+            id: deviceId,
+            label,
+            platform: `${process.platform}-${process.arch}`,
+            publicKey: keys.publicKey,
+            status: 'online',
+            metadata: {
+                source: '@qpjoy/tunnel-cli',
+                role: options.role,
+                hostname: (0, node_os_1.hostname)(),
+                wireGuard: {
+                    publicKey: keys.publicKey,
+                    interfaceName,
+                    updatedAt: new Date().toISOString(),
+                },
+            },
+        },
+    });
+    const manifest = await apiJson(serverUrl, auth.accessToken, `/api/v1/hdo/manifest/${encodeURIComponent(deviceId)}`, {
+        method: 'GET',
+    });
+    const runtime = hdoRuntimeFromManifest(manifest, registered, keys.privateKey);
+    writeWireGuardConfig(configPath, (0, electron_core_wireguard_1.renderHdoClientWireGuardConfig)({
+        privateKey: runtime.privateKey,
+        address: runtime.address,
+        domesticPublicKey: runtime.domesticPublicKey,
+        domesticEndpoint: runtime.domesticEndpoint,
+        allowedIps: runtime.allowedIps,
+        persistentKeepalive: 25,
+    }));
+    const now = new Date().toISOString();
+    writeState(stateFile, {
+        serverUrl,
+        bearerToken: auth.accessToken,
+        refreshToken: auth.refreshToken,
+        accessExpiresAt: auth.accessExpiresAt,
+        refreshExpiresAt: auth.refreshExpiresAt,
+        username: auth.username ?? username,
+        deviceId,
+        label,
+        interfaceName,
+        configPath,
+        installDir,
+        privateKey: keys.privateKey,
+        publicKey: keys.publicKey,
+        overlayIp: runtime.overlayIp,
+        lastManifestGeneration: runtime.generation,
+        enrolledAt: previous.enrolledAt || now,
+        updatedAt: now,
+    });
+    let startMessage = 'System tunnel not started (--no-start).';
+    if (options.start) {
+        startMessage = await startSystemTunnel(interfaceName, configPath, installDir);
+    }
+    process.stdout.write([
+        refreshOnly ? 'HDO config refreshed.' : 'HDO device enrolled.',
+        `Device: ${deviceId}`,
+        `Overlay IP: ${runtime.overlayIp}`,
+        `WireGuard config: ${configPath}`,
+        `State file: ${stateFile}`,
+        startMessage,
+        '',
+    ].join('\n'));
+}
+function statusCommand(stateFileInput) {
+    const stateFile = resolveStateFile(stateFileInput);
+    const state = readState(stateFile);
+    const interfaceName = sanitizeInterfaceName(state.interfaceName || defaultInterfaceName);
+    const configPath = resolveConfigPath(state.configPath, interfaceName);
+    const installDir = resolveInstallDir(state.installDir);
+    process.stdout.write(`State file: ${stateFile}\n`);
+    process.stdout.write(`Server URL: ${state.serverUrl || 'unset'}\n`);
+    process.stdout.write(`Device: ${state.deviceId || 'unset'}\n`);
+    process.stdout.write(`Overlay IP: ${state.overlayIp || 'unset'}\n`);
+    process.stdout.write(`WireGuard config: ${configPath}\n\n`);
+    if (process.platform === 'linux') {
+        inherit('systemctl', ['status', `wg-quick@${interfaceName}`, '--no-pager']);
+        process.stdout.write('\n');
+        inherit('wg', ['show', interfaceName]);
+        return;
+    }
+    const runtime = (0, electron_core_wireguard_1.resolveWireGuardConnectionRuntime)({
+        installDir,
+        allowSystemFallback: true,
+    });
+    if (process.platform === 'darwin') {
+        const daemon = (0, electron_core_wireguard_1.getDarwinWireGuardLaunchDaemonStatus)({ runtime, configPath });
+        process.stdout.write(`LaunchDaemon: ${daemon.loaded ? 'loaded' : 'not loaded'}; running=${daemon.running}\n`);
+        if (daemon.plistPath)
+            process.stdout.write(`plist: ${daemon.plistPath}\n`);
+    }
+    const tunnel = (0, electron_core_wireguard_1.getWireGuardTunnelStatus)({ runtime, configPath });
+    process.stdout.write(`WireGuard active: ${tunnel.active}\n`);
+    process.stdout.write(`Runtime: ${runtime.method}\n`);
+    if (tunnel.realInterfaceName)
+        process.stdout.write(`Interface: ${tunnel.realInterfaceName}\n`);
+    if (tunnel.peers.length)
+        process.stdout.write(`Peers: ${tunnel.peers.length}\n`);
+    if (tunnel.error)
+        process.stdout.write(`Status detail: ${tunnel.error}\n`);
+}
+async function downCommand(stateFileInput) {
+    const stateFile = resolveStateFile(stateFileInput);
+    const state = readState(stateFile);
+    const interfaceName = sanitizeInterfaceName(state.interfaceName || defaultInterfaceName);
+    const configPath = resolveConfigPath(state.configPath, interfaceName);
+    const installDir = resolveInstallDir(state.installDir);
+    if (process.platform === 'linux') {
+        inheritRequired('systemctl', ['disable', '--now', `wg-quick@${interfaceName}`]);
+        return;
+    }
+    const runtime = (0, electron_core_wireguard_1.resolveWireGuardConnectionRuntime)({
+        installDir,
+        allowSystemFallback: true,
+    });
+    if (process.platform === 'darwin') {
+        const result = await (0, electron_core_wireguard_1.uninstallDarwinWireGuardLaunchDaemon)({ runtime, configPath });
+        if (!result.ok)
+            throw new Error(result.message);
+        process.stdout.write(`${result.message}\n`);
+        return;
+    }
+    const result = await (0, electron_core_wireguard_1.setWireGuardTunnelState)({ runtime, configPath, action: 'down' });
+    if (!result.ok)
+        throw new Error(result.message);
+    process.stdout.write(`${result.message}\n`);
+}
+function parseEnrollOptions(args) {
+    const options = {
+        interfaceName: defaultInterfaceName,
+        role: 'internal',
+        start: true,
+        rotateKey: false,
+    };
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        const readValue = () => {
+            const value = args[index + 1];
+            if (!value)
+                throw new Error(`Missing value for ${arg}`);
+            index += 1;
+            return value;
+        };
+        switch (arg) {
+            case '--server-url':
+                options.serverUrl = readValue();
+                break;
+            case '--token':
+                options.token = readValue();
+                break;
+            case '--token-file':
+                options.tokenFile = readValue();
+                break;
+            case '--username':
+            case '--user':
+                options.username = readValue();
+                break;
+            case '--password':
+                options.password = readValue();
+                break;
+            case '--password-file':
+                options.passwordFile = readValue();
+                break;
+            case '--device-id':
+                options.deviceId = readValue();
+                break;
+            case '--label':
+                options.label = readValue();
+                break;
+            case '--interface':
+                options.interfaceName = readValue();
+                break;
+            case '--config-path':
+                options.configPath = readValue();
+                break;
+            case '--state-file':
+                options.stateFile = readValue();
+                break;
+            case '--install-dir':
+                options.installDir = readValue();
+                break;
+            case '--role':
+                options.role = readValue();
+                break;
+            case '--rotate-key':
+                options.rotateKey = true;
+                break;
+            case '--no-start':
+                options.start = false;
+                break;
+            default:
+                throw new Error(`Unknown hdo enroll option: ${arg}`);
+        }
+    }
+    return options;
+}
+function parseStateFileArg(args) {
+    let stateFile;
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === '--state-file') {
+            const value = args[index + 1];
+            if (!value)
+                throw new Error('Missing value for --state-file');
+            stateFile = value;
+            index += 1;
+        }
+        else {
+            throw new Error(`Unknown hdo option: ${arg}`);
+        }
+    }
+    return stateFile;
+}
+async function resolveAuth(serverUrl, options, previous, username) {
+    const token = resolveExplicitToken(options);
+    if (token) {
+        return {
+            accessToken: token,
+            refreshToken: previous.refreshToken,
+            accessExpiresAt: previous.accessExpiresAt,
+            refreshExpiresAt: previous.refreshExpiresAt,
+            username,
+        };
+    }
+    if (previous.refreshToken && !tokenExpired(previous.refreshExpiresAt)) {
+        try {
+            return await refreshAuth(serverUrl, previous.refreshToken, username ?? previous.username);
+        }
+        catch {
+            // Fall through to username/password login.
+        }
+    }
+    const identifier = username;
+    const password = resolvePassword(options);
+    if (identifier && password) {
+        return loginAuth(serverUrl, identifier, password);
+    }
+    if (previous.bearerToken && !tokenExpired(previous.accessExpiresAt)) {
+        return {
+            accessToken: previous.bearerToken,
+            refreshToken: previous.refreshToken,
+            accessExpiresAt: previous.accessExpiresAt,
+            refreshExpiresAt: previous.refreshExpiresAt,
+            username: username ?? previous.username,
+        };
+    }
+    if (!identifier) {
+        throw new Error('Missing --username, HDO_USERNAME, or --token.');
+    }
+    throw new Error('Missing --password, --password-file, or HDO_PASSWORD.');
+}
+function resolveExplicitToken(options) {
+    if (options.token)
+        return options.token;
+    if (options.tokenFile)
+        return (0, node_fs_1.readFileSync)((0, node_path_1.resolve)(options.tokenFile), 'utf8').trim();
+    return process.env.HDO_TOKEN ?? process.env.QPJOY_HDO_TOKEN;
+}
+function resolvePassword(options) {
+    if (options.password)
+        return options.password;
+    if (options.passwordFile)
+        return (0, node_fs_1.readFileSync)((0, node_path_1.resolve)(options.passwordFile), 'utf8').trim();
+    return process.env.HDO_PASSWORD ?? process.env.QPJOY_HDO_PASSWORD;
+}
+async function loginAuth(serverUrl, identifier, password) {
+    const raw = await apiJson(serverUrl, '', '/api/v1/auth/login', {
+        method: 'POST',
+        body: { identifier, password },
+        auth: false,
+    });
+    const root = requireRecord(raw, 'auth response');
+    const tokens = requireRecord(root.tokens, 'auth response tokens');
+    const accessToken = stringField(tokens.accessToken);
+    if (!accessToken)
+        throw new Error('Auth response did not include accessToken.');
+    return {
+        accessToken,
+        refreshToken: stringField(tokens.refreshToken) ?? undefined,
+        accessExpiresAt: stringField(tokens.accessExpiresAt) ?? undefined,
+        refreshExpiresAt: stringField(tokens.refreshExpiresAt) ?? undefined,
+        username: identifier,
+    };
+}
+async function refreshAuth(serverUrl, refreshToken, username) {
+    const raw = await apiJson(serverUrl, '', '/api/v1/auth/refresh', {
+        method: 'POST',
+        body: { refreshToken },
+        auth: false,
+    });
+    const root = requireRecord(raw, 'refresh response');
+    const accessToken = stringField(root.accessToken);
+    if (!accessToken)
+        throw new Error('Refresh response did not include accessToken.');
+    return {
+        accessToken,
+        refreshToken: stringField(root.refreshToken) ?? refreshToken,
+        accessExpiresAt: stringField(root.accessExpiresAt) ?? undefined,
+        refreshExpiresAt: stringField(root.refreshExpiresAt) ?? undefined,
+        username,
+    };
+}
+function resolveKeypair(options, previous, installDir) {
+    if (!options.rotateKey && previous.privateKey && previous.publicKey) {
+        return { privateKey: previous.privateKey, publicKey: previous.publicKey };
+    }
+    const runtime = (0, electron_core_wireguard_1.resolveWireGuardRuntime)({
+        installDir,
+        allowSystemFallback: true,
+    });
+    if (!runtime.command) {
+        throw new Error(runtime.error ?? 'WireGuard wg command unavailable.');
+    }
+    return (0, electron_core_wireguard_1.generateWireGuardKeyPairWithCli)(runtime.command);
+}
+async function startSystemTunnel(interfaceName, configPath, installDir) {
+    if (process.platform === 'linux') {
+        inheritRequired('systemctl', ['enable', `wg-quick@${interfaceName}`]);
+        inheritRequired('systemctl', ['restart', `wg-quick@${interfaceName}`]);
+        return `Enabled and restarted wg-quick@${interfaceName}.`;
+    }
+    const runtime = (0, electron_core_wireguard_1.resolveWireGuardConnectionRuntime)({
+        installDir,
+        allowSystemFallback: true,
+    });
+    if (process.platform === 'darwin') {
+        const result = await (0, electron_core_wireguard_1.installDarwinWireGuardLaunchDaemon)({ runtime, configPath });
+        if (!result.ok)
+            throw new Error(result.message);
+        return result.message;
+    }
+    if (process.platform === 'win32') {
+        const result = await (0, electron_core_wireguard_1.setWireGuardTunnelState)({ runtime, configPath, action: 'restart' });
+        if (!result.ok)
+            throw new Error(result.message);
+        return result.message;
+    }
+    throw new Error(`Unsupported platform for HDO system tunnel: ${process.platform}`);
+}
+function readState(path) {
+    if (!(0, node_fs_1.existsSync)(path))
+        return {};
+    const raw = (0, node_fs_1.readFileSync)(path, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (!isRecord(parsed))
+        return {};
+    return parsed;
+}
+function writeState(path, state) {
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(path), { recursive: true, mode: 0o700 });
+    (0, node_fs_1.writeFileSync)(path, JSON.stringify(state, null, 2) + '\n', { mode: 0o600 });
+    chmodSyncSafe(path, 0o600);
+}
+function writeWireGuardConfig(path, content) {
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(path), { recursive: true, mode: 0o700 });
+    (0, node_fs_1.writeFileSync)(path, content, { mode: 0o600 });
+    chmodSyncSafe(path, 0o600);
+}
+function hdoRuntimeFromManifest(manifest, registered, privateKey) {
+    const root = requireRecord(manifest, 'manifest');
+    const license = requireRecord(root.license, 'manifest.license');
+    if (license.active !== true) {
+        throw new Error('HDO mesh license is not active for this user/device.');
+    }
+    const wireGuard = requireRecord(root.wireGuard, 'manifest.wireGuard');
+    const client = requireRecord(wireGuard.client, 'manifest.wireGuard.client');
+    const domestic = requireRecord(wireGuard.domestic, 'manifest.wireGuard.domestic');
+    const overlayIp = stringField(client.overlayIp) ||
+        stringField(requireRecord(registered, 'registered device').overlayIp);
+    const domesticPublicKey = stringField(domestic.publicKey);
+    const domesticEndpoint = stringField(domestic.endpoint);
+    if (!overlayIp)
+        throw new Error('HDO manifest did not assign an overlay IP.');
+    if (!domesticPublicKey || !domesticEndpoint) {
+        throw new Error('HDO manifest is missing domestic WireGuard publicKey/endpoint.');
+    }
+    const routeCidrs = stringArray(wireGuard.routeCidrs);
+    const domesticOverlay = stringField(domestic.overlayIp);
+    const allowedIps = uniqueStrings([
+        ...routeCidrs,
+        ...(domesticOverlay ? [`${domesticOverlay}/32`] : []),
+    ]).filter((value) => value.includes('/'));
+    if (allowedIps.length === 0) {
+        throw new Error('HDO manifest did not include WireGuard AllowedIPs.');
+    }
+    return {
+        privateKey,
+        address: overlayIp.includes('/') ? overlayIp : `${overlayIp}/32`,
+        overlayIp: overlayIp.split('/')[0] || overlayIp,
+        domesticPublicKey,
+        domesticEndpoint,
+        allowedIps,
+        generation: numberField(root.generation),
+    };
+}
+async function apiJson(serverUrl, token, path, input) {
+    const headers = {};
+    if (input.auth !== false)
+        headers.authorization = `Bearer ${token}`;
+    if (input.body !== undefined)
+        headers['content-type'] = 'application/json';
+    const response = await fetch(`${serverUrl}${path}`, {
+        method: input.method,
+        headers,
+        body: input.body === undefined ? undefined : JSON.stringify(input.body),
+    });
+    const text = await response.text();
+    if (!response.ok) {
+        throw new Error(`HDO API ${input.method} ${path} failed: HTTP ${response.status} ${text}`);
+    }
+    return text ? JSON.parse(text) : null;
+}
+function resolveStateFile(input) {
+    return (0, node_path_1.resolve)(input || defaultStateFile());
+}
+function resolveConfigPath(input, interfaceName) {
+    return (0, node_path_1.resolve)(input || defaultConfigPath(interfaceName));
+}
+function resolveInstallDir(input) {
+    return (0, node_path_1.resolve)(input || defaultInstallDir());
+}
+function defaultStateFile() {
+    if (process.platform === 'linux')
+        return '/etc/qpjoy/hdo/client.json';
+    if (process.platform === 'win32')
+        return (0, node_path_1.join)(windowsUserDataDir(), 'client.json');
+    return (0, node_path_1.join)((0, node_os_1.homedir)(), '.qpjoy', 'hdo', 'client.json');
+}
+function defaultConfigPath(interfaceName) {
+    if (process.platform === 'linux')
+        return `/etc/wireguard/${interfaceName}.conf`;
+    if (process.platform === 'win32')
+        return (0, node_path_1.join)(windowsUserDataDir(), `${interfaceName}.conf`);
+    return (0, node_path_1.join)((0, node_os_1.homedir)(), '.qpjoy', 'hdo', `${interfaceName}.conf`);
+}
+function defaultInstallDir() {
+    if (process.platform === 'linux')
+        return '/usr/local/lib/qpjoy/hdo/bin';
+    if (process.platform === 'win32')
+        return (0, node_path_1.join)(windowsUserDataDir(), 'bin');
+    return (0, node_path_1.join)((0, node_os_1.homedir)(), '.qpjoy', 'hdo', 'bin');
+}
+function windowsUserDataDir() {
+    return (0, node_path_1.join)(process.env.LOCALAPPDATA || (0, node_path_1.join)((0, node_os_1.homedir)(), 'AppData', 'Local'), 'QPJoy', 'HDO');
+}
+function inherit(command, args) {
+    (0, node_child_process_1.spawnSync)(command, args, { stdio: 'inherit' });
+}
+function inheritRequired(command, args) {
+    const result = (0, node_child_process_1.spawnSync)(command, args, { stdio: 'inherit' });
+    assertSpawnOk(command, args, result);
+}
+function assertSpawnOk(command, args, result) {
+    if (result.error) {
+        throw new Error(`${command} failed: ${result.error.message}`);
+    }
+    if (result.status && result.status !== 0) {
+        const stderr = Buffer.isBuffer(result.stderr) ? result.stderr.toString('utf8') : result.stderr;
+        throw new Error(`${command} ${args.join(' ')} failed with exit ${result.status}${stderr ? `: ${stderr}` : ''}`);
+    }
+}
+function normalizeBaseUrl(value) {
+    if (!value)
+        return undefined;
+    return value.replace(/\/+$/, '');
+}
+function sanitizeInterfaceName(value) {
+    const safe = value.trim();
+    if (!/^[a-zA-Z0-9_.-]{1,64}$/.test(safe)) {
+        throw new Error(`Invalid WireGuard interface name: ${value}`);
+    }
+    return safe;
+}
+function sanitizeId(value) {
+    return value
+        .toLowerCase()
+        .replace(/[^a-z0-9._:-]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 80) || 'device';
+}
+function tokenExpired(value) {
+    if (!value)
+        return false;
+    const time = Date.parse(value);
+    return Number.isFinite(time) && Date.now() > time - 60_000;
+}
+function chmodSyncSafe(path, mode) {
+    if (process.platform === 'win32')
+        return;
+    (0, node_fs_1.chmodSync)(path, mode);
+}
+function requireRecord(value, label) {
+    if (!isRecord(value))
+        throw new Error(`${label} is not an object.`);
+    return value;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function stringField(value) {
+    return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+function numberField(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+function stringArray(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.map((item) => stringField(item)).filter((item) => Boolean(item));
+}
+function uniqueStrings(values) {
+    return [...new Set(values)];
+}

package/dist/index.js

@@ -5,6 +5,7 @@ const node_child_process_1 = require("node:child_process");
 const node_fs_1 = require("node:fs");
 const promises_1 = require("node:fs/promises");
 const node_path_1 = require("node:path");
+const hdo_1 = require("./hdo");
 const args = process.argv.slice(2);
 const packageRoot = (0, node_path_1.resolve)(__dirname, '..');
 const bundledClientScript = (0, node_path_1.resolve)(packageRoot, 'resources/mihomo-client.sh');
@@ -71,6 +72,7 @@ Usage:
   qp-tunnel-cli install-script [--target /usr/local/bin/mihomo-client]
   qp-tunnel-cli script-path
   qp-tunnel-cli client-help
+  qp-tunnel-cli hdo enroll --server-url https://domestic.example.com --username user
   qp-tunnel-cli <mihomo-client command> [options]
   qp-tunnel-cli -- <command> [args...]
   qp-tunnel-cli <command-path> [args...]
@@ -83,11 +85,13 @@ Common commands:
   qp-tunnel-cli tun-on
   qp-tunnel-cli tun-off
   qp-tunnel-cli update-subscription
+  qp-tunnel-cli hdo status
   qp-tunnel-cli uninstall --purge
   qp-tunnel-cli ./electron-server/scripts/manage.sh redeploy
 
-The npm package is a thin distributor for the Linux mihomo-client script. Client
-commands re-run through sudo when needed, then execute the bundled shell script.
+The npm package distributes the Linux mihomo-client script and a cross-platform
+HDO WireGuard enrollment command. Linux mihomo-client commands re-run through
+sudo when needed, then execute the bundled shell script.
 
 Unknown commands are executed with QPJoy proxy variables injected. Host commands
 receive HTTP_PROXY=http://127.0.0.1:<mixed-port>; Docker/Compose build contexts
@@ -97,6 +101,9 @@ QP_TUNNEL_CONTAINER_HTTP_PROXY=http://host.docker.internal:<mixed-port>.
 Install the script as a normal server command:
   sudo qp-tunnel-cli install-script
   sudo mihomo-client status
+
+Enroll this machine into an HDO mesh:
+  HDO_PASSWORD=... qp-tunnel-cli hdo enroll --server-url https://domestic.example.com --username user
 `);
 }
 function clientHelp() {
@@ -332,6 +339,11 @@ async function main() {
         installClientScript(args.slice(1));
         return;
     }
+    if (command === 'hdo' || command === 'hdo-enroll' || command === 'hdo-refresh') {
+        const hdoArgs = command === 'hdo' ? args.slice(1) : [command.replace(/^hdo-/, ''), ...args.slice(1)];
+        await (0, hdo_1.runHdoCli)(hdoArgs, { isRoot, sudoSelf });
+        return;
+    }
     const passthroughCommand = command === '--verbose' ? args[1] : command;
     if (passthroughCommand && clientCommands.has(passthroughCommand)) {
         runClientCommand(args);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@qpjoy/tunnel-cli",
-  "version": "0.1.2",
-  "description": "Global QPJoy Tunnel CLI for installing and running the Linux mihomo-client script.",
+  "version": "0.1.4",
+  "description": "Global QPJoy Tunnel CLI for mihomo-client and cross-platform HDO mesh enrollment.",
   "private": false,
   "type": "commonjs",
   "main": "dist/index.js",
@@ -21,6 +21,9 @@
   "publishConfig": {
     "access": "public"
   },
+  "dependencies": {
+    "@qpjoy/electron-core-wireguard": "^0.1.18"
+  },
   "devDependencies": {
     "@types/node": "^22.10.7"
   },