rdsh-gateway 0.2.3 → 0.4.0

package/dist/config.d.ts

@@ -1,4 +1,5 @@
 export type AuthMode = "pair" | "password" | "none";
+export type HostMode = "lan" | "cloud" | "join";
 export interface TlsConfig {
     cert: string;
     key: string;
@@ -15,6 +16,8 @@ export interface AuthConfig {
     users: AuthUser[];
 }
 export interface RdshConfig {
+    /** 运行模式：lan/cloud = 独立服务；join = 出站隧道 */
+    mode: HostMode;
     host: string;
     port: number;
     sessionTtlSeconds: number;
@@ -23,11 +26,17 @@ export interface RdshConfig {
     allowFrom: string[];
     auth: AuthConfig;
     dshPath?: string;
+    /** join 模式字段 */
+    hub?: string;
+    name?: string;
+    insecure?: boolean;
 }
-export declare const DEFAULT_CONFIG_PATH: string;
-/** 解析配置文件路径（--config > $RDSH_CONFIG > 默认）。 */
+export declare const DEFAULT_HOST_CONFIG_PATH: string;
+/** 解析配置文件路径（--config > $RDSH_CONFIG > 默认 host.json）。 */
 export declare function resolveConfigPath(cliPath?: string, env?: NodeJS.ProcessEnv): string;
-/** 加载并校验配置；文件不存在时返回默认值。 */
+/** 原子写回配置（tmp + rename，0600）。 */
+export declare function saveConfig(path: string, config: RdshConfig): Promise<void>;
+/** 加载并校验配置；默认路径下文件不存在时尝试迁移旧 config.json，否则返回默认值。 */
 export declare function loadConfig(path: string): Promise<RdshConfig>;
 /** 校验并规范化任意输入（测试/CLI 覆盖复用）。 */
 export declare function normalizeConfig(raw: unknown, source?: string): RdshConfig;

package/dist/config.js

@@ -1,15 +1,20 @@
 /**
- * config.ts — 配置加载/默认/校验。持久配置唯一来源（~/.rdsh/config.json）。
+ * config.ts — host 配置加载/默认/校验/迁移。持久配置唯一来源（~/.rdsh/host.json，3 模式）。
  *
+ * 模式：`mode = "lan" | "cloud" | "join"`（lan/cloud = 独立服务；join = 出站隧道）。
  * 优先级：CLI 参数 > config 文件 > 默认值。
- * 路径：`--config <path>` > `$RDSH_CONFIG` > 默认 `~/.rdsh/config.json`。
+ * 路径：`--config <path>` > `$RDSH_CONFIG` > 默认 `~/.rdsh/host.json`。
+ * 迁移：默认路径下 host.json 不存在但旧 `~/.rdsh/config.json` 存在时，按 tls/auth.mode 推断 mode 并写回 host.json（原文件保留）。
  */
-import { readFile } from "node:fs/promises";
+import { readFile, writeFile, rename } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
-export const DEFAULT_CONFIG_PATH = join(homedir(), ".rdsh", "config.json");
+export const DEFAULT_HOST_CONFIG_PATH = join(homedir(), ".rdsh", "host.json");
+/** 旧版 serve 配置（迁移源，保留不删）。 */
+const LEGACY_CONFIG_PATH = join(homedir(), ".rdsh", "config.json");
 const DEFAULT_AUTH = { mode: "pair", version: 1, users: [] };
 const DEFAULTS = {
+    mode: "lan",
     host: "0.0.0.0",
     port: 8443,
     sessionTtlSeconds: 12 * 3600,
@@ -17,11 +22,17 @@ const DEFAULTS = {
     allowFrom: [],
     auth: DEFAULT_AUTH,
 };
-/** 解析配置文件路径（--config > $RDSH_CONFIG > 默认）。 */
+/** 解析配置文件路径（--config > $RDSH_CONFIG > 默认 host.json）。 */
 export function resolveConfigPath(cliPath, env = process.env) {
-    return cliPath ?? env.RDSH_CONFIG ?? DEFAULT_CONFIG_PATH;
+    return cliPath ?? env.RDSH_CONFIG ?? DEFAULT_HOST_CONFIG_PATH;
 }
-/** 加载并校验配置；文件不存在时返回默认值。 */
+/** 原子写回配置（tmp + rename，0600）。 */
+export async function saveConfig(path, config) {
+    const tmp = `${path}.tmp`;
+    await writeFile(tmp, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
+    await rename(tmp, path);
+}
+/** 加载并校验配置；默认路径下文件不存在时尝试迁移旧 config.json，否则返回默认值。 */
 export async function loadConfig(path) {
     let raw = {};
     try {
@@ -32,10 +43,29 @@ export async function loadConfig(path) {
         if (code !== "ENOENT") {
             throw new Error(`failed to read config ${path}: ${err.message}`);
         }
-        // ENOENT → 默认配置
+        // ENOENT：默认路径下迁移旧 config.json → host.json（幂等：写回含 mode 的规范化配置）
+        if (path === DEFAULT_HOST_CONFIG_PATH) {
+            const legacy = await readLegacyConfig();
+            if (legacy !== null) {
+                await writeFile(path, `${JSON.stringify(normalizeConfig(legacy, LEGACY_CONFIG_PATH), null, 2)}\n`, { mode: 0o600 });
+                raw = legacy;
+            }
+        }
     }
     return normalizeConfig(raw, path);
 }
+/** 读取旧 ~/.rdsh/config.json（不存在 → null；坏 JSON → 抛错）。 */
+async function readLegacyConfig() {
+    try {
+        return JSON.parse(await readFile(LEGACY_CONFIG_PATH, "utf8"));
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT")
+            return null;
+        throw new Error(`failed to read legacy config ${LEGACY_CONFIG_PATH}: ${err.message}`);
+    }
+}
 /** 校验并规范化任意输入（测试/CLI 覆盖复用）。 */
 export function normalizeConfig(raw, source = "config") {
     if (typeof raw !== "object" || raw === null) {
@@ -46,6 +76,18 @@ export function normalizeConfig(raw, source = "config") {
         ...DEFAULTS,
         auth: { ...DEFAULT_AUTH, users: [] },
     };
+    // ---- mode（三态；缺省按 tls/auth.mode 推断，兼容旧 config.json）----
+    if (cfg.mode !== undefined) {
+        if (cfg.mode !== "lan" && cfg.mode !== "cloud" && cfg.mode !== "join") {
+            throw new Error(`${source}: "mode" must be lan|cloud|join`);
+        }
+        out.mode = cfg.mode;
+    }
+    else {
+        const tls = cfg.tls;
+        const authMode = cfg.auth?.mode;
+        out.mode = tls !== undefined || authMode === "password" ? "cloud" : "lan";
+    }
     if (cfg.host !== undefined) {
         assertString(cfg.host, "host", source);
         out.host = cfg.host;
@@ -114,6 +156,20 @@ export function normalizeConfig(raw, source = "config") {
             });
         }
     }
+    // ---- join 字段 ----
+    if (cfg.hub !== undefined) {
+        assertString(cfg.hub, "hub", source);
+        out.hub = cfg.hub;
+    }
+    if (cfg.name !== undefined) {
+        assertString(cfg.name, "name", source);
+        out.name = cfg.name;
+    }
+    if (cfg.insecure !== undefined) {
+        if (typeof cfg.insecure !== "boolean")
+            throw new Error(`${source}: "insecure" must be boolean`);
+        out.insecure = cfg.insecure;
+    }
     if (cfg.dshPath !== undefined) {
         assertString(cfg.dshPath, "dshPath", source);
         out.dshPath = cfg.dshPath;

package/dist/index.d.ts

@@ -14,14 +14,18 @@ export { findDsh, spawnDsh } from "./spawn-dsh.ts";
 export type { SpawnedDsh } from "./spawn-dsh.ts";
 export { forwardHttp, createUpgradeProxy, rewriteHeadersForDsh } from "./proxy.ts";
 export type { ProxyTarget } from "./proxy.ts";
-export { loadConfig, normalizeConfig, resolveConfigPath, DEFAULT_CONFIG_PATH } from "./config.ts";
-export type { RdshConfig, AuthMode, AuthUser, AuthConfig, TlsConfig } from "./config.ts";
+export { loadConfig, normalizeConfig, resolveConfigPath, saveConfig, DEFAULT_HOST_CONFIG_PATH } from "./config.ts";
+export type { RdshConfig, AuthMode, AuthUser, AuthConfig, TlsConfig, HostMode } from "./config.ts";
 export { hashPassword, verifyPassword, UserManager } from "./auth.ts";
 export { ipInCidrs, parseCidr, ipToInt } from "./cidr.ts";
 export { loadTls } from "./tls.ts";
 export type { TlsMaterial } from "./tls.ts";
 export { loginPageHtml } from "./login-page.ts";
-export { installService, uninstallService, serviceStatus, systemdUnit, launchdPlist } from "./service.ts";
+export { installService, uninstallService, serviceStatus, systemdUnit, launchdPlist, SERVICE_NAME, JOIN_SERVICE_NAME, HOST_SERVICE_NAME, HUB_SERVICE_NAME } from "./service.ts";
+export type { ServiceSpec } from "./service.ts";
 export declare const NAME = "rdsh-gateway";
-export { join } from "./join.ts";
-export type { JoinOptions } from "./join.ts";
+export { join, startJoin, registerJoin, detectInsecure, selfRevoke } from "./join.ts";
+export type { JoinOptions, RegisterOutcome, JoinState, JoinHooks, StartJoinOptions, JoinHandle } from "./join.ts";
+export { readPersistedToken, clearPersistedToken } from "./token-store.ts";
+export { acquireJoinLock, releaseJoinLock, readJoinLock, JOIN_LOCK_PATH } from "./lock.ts";
+export type { JoinLock, JoinLockRole } from "./lock.ts";

package/dist/index.js

@@ -9,12 +9,14 @@ export { PairManager } from "./pair.js";
 export { startGateway } from "./server.js";
 export { findDsh, spawnDsh } from "./spawn-dsh.js";
 export { forwardHttp, createUpgradeProxy, rewriteHeadersForDsh } from "./proxy.js";
-export { loadConfig, normalizeConfig, resolveConfigPath, DEFAULT_CONFIG_PATH } from "./config.js";
+export { loadConfig, normalizeConfig, resolveConfigPath, saveConfig, DEFAULT_HOST_CONFIG_PATH } from "./config.js";
 export { hashPassword, verifyPassword, UserManager } from "./auth.js";
 export { ipInCidrs, parseCidr, ipToInt } from "./cidr.js";
 export { loadTls } from "./tls.js";
 export { loginPageHtml } from "./login-page.js";
-export { installService, uninstallService, serviceStatus, systemdUnit, launchdPlist } from "./service.js";
+export { installService, uninstallService, serviceStatus, systemdUnit, launchdPlist, SERVICE_NAME, JOIN_SERVICE_NAME, HOST_SERVICE_NAME, HUB_SERVICE_NAME } from "./service.js";
 export const NAME = "rdsh-gateway";
-export { join } from "./join.js";
+export { join, startJoin, registerJoin, detectInsecure, selfRevoke } from "./join.js";
+export { readPersistedToken, clearPersistedToken } from "./token-store.js";
+export { acquireJoinLock, releaseJoinLock, readJoinLock, JOIN_LOCK_PATH } from "./lock.js";
 //# sourceMappingURL=index.js.map

package/dist/join.d.ts

@@ -1,11 +1,60 @@
+import type { ProxyTarget } from "./proxy.ts";
+import type { JoinLockRole } from "./lock.ts";
 export interface JoinOptions {
     hubUrl: string;
-    /** 直填 host token（跳过配对码绑定流程） */
+    /** join token（用户级，register 换 host token） */
     token?: string;
     /** 清除持久化 token 并强制重新配对 */
     reset?: boolean;
     dshPath?: string;
-    /** 跳过 TLS 证书校验（自签 hub 用；正式证书无需） */
+    /** 跳过 TLS 证书校验（自签 hub 用；正式证书无需，缺省自动检测） */
     insecure?: boolean;
+    /** 主机名（注册命名 / host.json） */
+    name?: string;
 }
+/** 注册/接入结果：解析出的 host token + 是否需 insecure。 */
+export interface RegisterOutcome {
+    token: string;
+    insecure: boolean;
+}
+/** 隧道状态机（onState 事件值）。 */
+export type JoinState = "connecting" | "connected" | "reconnecting" | "rejected" | "stopped";
+/** join 核心事件钩子（插件面板实时状态 + 日志预留）。 */
+export interface JoinHooks {
+    onState?(state: JoinState, detail?: {
+        message?: string;
+        delayMs?: number;
+    }): void;
+    onLog?(level: "info" | "warn" | "error", message: string): void;
+}
+/** no-spawn、外部 target 的 join 隧道启动参数（CLI 与插件共用）。 */
+export interface StartJoinOptions {
+    hubUrl: string;
+    /** 已解析的 host token（registerJoin 结果） */
+    token: string;
+    insecure: boolean;
+    /** 转发目标（no-spawn：外部 dsh 的 loopback 地址） */
+    target: ProxyTarget;
+    /** pid 锁 role：cli / plugin */
+    role: JoinLockRole;
+    /** 锁文件路径（缺省 ~/.rdsh/join.lock；测试可注入临时路径） */
+    lockPath?: string;
+    hooks?: JoinHooks;
+}
+/** 可停止的 join 隧道句柄。 */
+export interface JoinHandle {
+    stop(): Promise<void>;
+}
+/** 探测 hub 是否需 insecure：以严格校验握手一次；证书错误 → true（需 insecure）。 */
+export declare function detectInsecure(hubUrl: string): Promise<boolean>;
+/** 调用 hub self-revoke 注销本机（host 持自己的 host token）。`rdsh host leave` 使用。 */
+export declare function selfRevoke(hubUrl: string, token: string, insecure: boolean): Promise<void>;
+/** 解析 host token（--token 注册 > 持久化复用）+ 自动检测证书；供 CLI 配置命令与 join() 复用。 */
+export declare function registerJoin(opts: JoinOptions): Promise<RegisterOutcome>;
+/**
+ * 启动 join 隧道（no-spawn）：转发到外部 `opts.target`，不 spawn dsh、不 process.exit。
+ * 获取 pid 锁（opts.role）；返回 `JoinHandle`，`stop()` 干净停止（关 WS/清 heartbeat/释放锁）。
+ */
+export declare function startJoin(opts: StartJoinOptions): JoinHandle;
+/** `rdsh host serve`（join 模式）的 CLI 封装：spawn dsh + 信号退出 + startJoin(role:cli)。 */
 export declare function join(opts: JoinOptions): Promise<void>;

package/dist/join.js

@@ -1,10 +1,13 @@
 /**
  * join.ts — `rdsh join <hub-url>`：出站隧道客户端（公网模式，M3）。
  *
- * 流程：spawn dsh（复用）→ 绑定（配对码轮询 或 --token 直填）→ WSS 隧道（?token=）
+ * 流程：spawn dsh（复用）→ 注册（join token → host token）→ WSS 隧道（?token=）
  * → 帧循环（OPEN http/ws → 本地 dsh 转发 → 响应帧回传）→ 断线指数退避重连。
  *
  * 安全：只出站（不监听任何入站端口）；hub 认证在层 1，gateway 侧只认隧道内来源。
+ *
+ * 06-dsh-plugin 重构（D13 钩子落地）：`join()`（CLI 形态，spawn dsh + 信号退出）
+ * 拆出 `startJoin()`（no-spawn、外部 target、可停止、onState/onLog）——插件复用。
  */
 import { request as httpRequest } from "node:http";
 import { request as httpsRequest } from "node:https";
@@ -13,36 +16,29 @@ import { FrameParser, FRAME_TYPE, encodeFrame, jsonPayload, parseJsonPayload } f
 import { findDsh, spawnDsh } from "./spawn-dsh.js";
 import { rewriteHeadersForDsh } from "./proxy.js";
 import { clearPersistedToken, persistToken, readPersistedToken } from "./token-store.js";
-const PENDING_POLL_MS = 5_000;
-const BIND_TIMEOUT_MS = 10 * 60 * 1000; // 配对码 10 分钟
-const HEARTBEAT_MS = 30_000;
-const RECONNECT_BASE_MS = 1_000;
-const RECONNECT_MAX_MS = 60_000;
-const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
-/** 绑定流程：POST /api/hosts/pending → 打印配对码 → 轮询取 host token。 */
-async function bind(hubUrl, insecure) {
-    const pendingRes = await hubRequest(hubUrl, "/api/hosts/pending", { method: "POST", insecure });
-    if (!pendingRes.ok) {
-        throw new Error(`hub rejected pending request: HTTP ${pendingRes.status}`);
+import { acquireJoinLock, releaseJoinLock } from "./lock.js";
+/** 判断错误是否为 TLS 证书类错误（自签/过期/域名不匹配）。 */
+function isCertError(err) {
+    const code = err?.code ?? "";
+    return (code.includes("CERT_") ||
+        code.includes("TLS") ||
+        code.includes("SELF_SIGNED") ||
+        code.includes("UNABLE_TO_VERIFY") ||
+        code.includes("DEPTH_ZERO"));
+}
+/** 探测 hub 是否需 insecure：以严格校验握手一次；证书错误 → true（需 insecure）。 */
+export async function detectInsecure(hubUrl) {
+    try {
+        await hubRequest(hubUrl, "/api/auth/login", { method: "GET", insecure: false });
+        return false; // TLS 握手成功
     }
-    const pending = pendingRes.body;
-    console.log(`rdsh join: pair code: ${pending.code}`);
-    console.log(`rdsh join: sign in to ${hubUrl} and enter this code (10 min) to bind this host.`);
-    console.log(`rdsh join: waiting for binding...`);
-    const deadline = Date.now() + BIND_TIMEOUT_MS;
-    while (Date.now() < deadline) {
-        await sleep(PENDING_POLL_MS);
-        const res = await hubRequest(hubUrl, `/api/hosts/pending/${pending.pendingId}`, { method: "GET", insecure });
-        if (!res.ok)
-            continue;
-        const body = res.body;
-        if (body.status === "bound" && typeof body.token === "string") {
-            console.log("rdsh join: bound — establishing tunnel...");
-            return body.token;
-        }
+    catch (err) {
+        return isCertError(err);
     }
-    throw new Error("binding timed out (10 min): re-run rdsh join to get a new code");
 }
+const HEARTBEAT_MS = 30_000;
+const RECONNECT_BASE_MS = 1_000;
+const RECONNECT_MAX_MS = 60_000;
 /** hub HTTP 调用（node:https 支持自签跳过校验 —— undici fetch 不受 NODE_TLS_REJECT_UNAUTHORIZED 影响）。 */
 function hubRequest(baseUrl, path, opts) {
     const url = new URL(baseUrl + path);
@@ -71,22 +67,26 @@ function hubRequest(baseUrl, path, opts) {
             res.on("error", reject);
         });
         req.on("error", reject);
-        req.end(opts.method === "POST" ? "{}" : undefined);
+        req.end(opts.method === "POST" ? JSON.stringify(opts.body ?? {}) : undefined);
     });
 }
-export async function join(opts) {
-    const hubWsBase = opts.hubUrl.replace(/^https/, "wss").replace(/^http/, "ws");
-    const foundDsh = findDsh(opts.dshPath);
-    if (foundDsh === null) {
-        throw new Error("cannot find 'dsh' in PATH. Install DeepSeek Harness first, or pass --dsh <path>.");
+/** 调用 hub self-revoke 注销本机（host 持自己的 host token）。`rdsh host leave` 使用。 */
+export async function selfRevoke(hubUrl, token, insecure) {
+    const res = await hubRequest(hubUrl, "/api/hosts/self-revoke", { method: "POST", insecure, body: { token } });
+    if (!res.ok) {
+        const msg = res.body.error?.message ?? `HTTP ${res.status}`;
+        throw new Error(`hub rejected self-revoke: ${msg}`);
     }
-    const dsh = await spawnDsh(foundDsh);
-    const target = { host: "127.0.0.1", port: dsh.port };
-    // token 来源优先级：--token 直填 > 持久化复用 > 配对码绑定（绑定成功后落盘）。
-    // 进程重启后复用已绑定 token，避免重复配对；被吊销时（401）自动回退重配对。
+}
+/** 解析 host token（--token 注册 > 持久化复用）+ 自动检测证书；供 CLI 配置命令与 join() 复用。 */
+export async function registerJoin(opts) {
+    const insecure = opts.insecure === true || (await detectInsecure(opts.hubUrl));
     let token;
     if (opts.token !== undefined) {
-        token = opts.token;
+        // --token = join token（或旧 host token）→ register 端点换 host token
+        const { hostToken } = await register(opts.hubUrl, opts.token, opts.name, insecure);
+        token = hostToken;
+        persistToken(opts.hubUrl, token);
     }
     else {
         if (opts.reset === true)
@@ -97,12 +97,41 @@ export async function join(opts) {
             console.log("rdsh join: reusing persisted host token");
         }
         else {
-            token = await bind(opts.hubUrl, opts.insecure === true);
-            persistToken(opts.hubUrl, token);
+            throw new Error("未接入：无持久化 session 且未提供 --token；先 `rdsh host join <hub>` 生成/粘贴 join token");
         }
     }
-    console.log(`rdsh join: dsh web on 127.0.0.1:${dsh.port}`);
-    console.log(`rdsh join: connecting to ${opts.hubUrl}...`);
+    return { token, insecure };
+}
+/** 调 register 端点：join token → host token（对旧 host token 幂等返回同一 token）。 */
+async function register(hubUrl, joinToken, name, insecure) {
+    const res = await hubRequest(hubUrl, "/api/hosts/register", { method: "POST", insecure, body: { token: joinToken, name } });
+    if (!res.ok) {
+        const msg = res.body.error?.message ?? `HTTP ${res.status}`;
+        throw new Error(`hub rejected register: ${msg}`);
+    }
+    const b = res.body;
+    if (typeof b.hostId !== "string" || typeof b.hostToken !== "string") {
+        throw new Error("hub register returned malformed response");
+    }
+    return { hostId: b.hostId, hostToken: b.hostToken };
+}
+/**
+ * 启动 join 隧道（no-spawn）：转发到外部 `opts.target`，不 spawn dsh、不 process.exit。
+ * 获取 pid 锁（opts.role）；返回 `JoinHandle`，`stop()` 干净停止（关 WS/清 heartbeat/释放锁）。
+ */
+export function startJoin(opts) {
+    const hubWsBase = opts.hubUrl.replace(/^https/, "wss").replace(/^http/, "ws");
+    const hooks = opts.hooks ?? {};
+    const log = (level, message) => {
+        hooks.onLog?.(level, message);
+    };
+    const setState = (state, detail) => {
+        hooks.onState?.(state, detail);
+    };
+    const lock = acquireJoinLock(opts.role, opts.lockPath);
+    if (!lock.ok) {
+        throw new Error(`join lock held by ${lock.heldBy.role} (pid ${lock.heldBy.pid}); stop it first`);
+    }
     const parser = new FrameParser();
     /** http 流：streamId → 本地请求（写请求体 / 结束）。 */
     const httpStreams = new Map();
@@ -111,23 +140,7 @@ export async function join(opts) {
     let shuttingDown = false;
     let reconnectDelay = RECONNECT_BASE_MS;
     let heartbeat;
-    const shutdown = async (signal, code = 0) => {
-        if (shuttingDown)
-            return;
-        shuttingDown = true;
-        if (signal !== "")
-            console.log(`\nrdsh: received ${signal}, shutting down...`);
-        if (heartbeat !== undefined)
-            clearInterval(heartbeat);
-        await dsh.stop();
-        process.exit(code);
-    };
-    process.on("SIGINT", () => void shutdown("SIGINT"));
-    process.on("SIGTERM", () => void shutdown("SIGTERM"));
-    process.on("SIGHUP", () => void shutdown("SIGHUP"));
-    // 常驻：进程靠信号退出（shutdown 里 process.exit）；防止函数返回后
-    // CLI 的 main().then(exit) 误退出服务进程
-    const keepAlive = new Promise(() => { });
+    let currentClient;
     function handleFrame(frame, client) {
         switch (frame.type) {
             case FRAME_TYPE.PING: {
@@ -216,11 +229,11 @@ export async function join(opts) {
         const streamId = frame.streamId;
         // http 转发：本地 dsh（loopback http）
         const up = httpRequest({
-            host: target.host,
-            port: target.port,
+            host: opts.target.host,
+            port: opts.target.port,
             path,
             method,
-            headers: rewriteHeadersForDsh(headers, target),
+            headers: rewriteHeadersForDsh(headers, opts.target),
         }, (upRes) => {
             client.send(encodeFrame(FRAME_TYPE.OPEN, streamId, jsonPayload({
                 kind: "http",
@@ -256,8 +269,8 @@ export async function join(opts) {
     }
     function openWsStream(frame, client, path, headers) {
         const streamId = frame.streamId;
-        const upstream = new WebSocket(`ws://${target.host}:${target.port}${path}`, {
-            headers: rewriteHeadersForDsh(headers, target),
+        const upstream = new WebSocket(`ws://${opts.target.host}:${opts.target.port}${path}`, {
+            headers: rewriteHeadersForDsh(headers, opts.target),
         });
         const queue = [];
         wsStreams.set(streamId, { upstream, queue });
@@ -285,28 +298,38 @@ export async function join(opts) {
         upstream.on("close", cleanup);
         upstream.on("error", cleanup);
     }
-    /** 持久化 token 被 hub 拒绝（吊销/重置）→ 删旧文件 → 重新配对 → 重连。 */
-    async function rebindAndReconnect() {
-        clearPersistedToken(opts.hubUrl);
-        console.log("rdsh join: host token rejected (revoked?) — re-pairing...");
-        try {
-            token = await bind(opts.hubUrl, opts.insecure === true);
-            persistToken(opts.hubUrl, token);
+    /** 清空本地 http/ws 流 + heartbeat（断线/停止时）。 */
+    function cleanupStreams() {
+        if (heartbeat !== undefined) {
+            clearInterval(heartbeat);
+            heartbeat = undefined;
         }
-        catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            console.error(`rdsh join: re-pairing failed (${msg}); retrying in ${RECONNECT_BASE_MS / 1000}s...`);
-            setTimeout(() => void rebindAndReconnect(), RECONNECT_BASE_MS);
-            return;
+        for (const s of httpStreams.values()) {
+            try {
+                s.up.destroy();
+            }
+            catch {
+                /* 已断 */
+            }
+        }
+        httpStreams.clear();
+        for (const s of wsStreams.values()) {
+            try {
+                s.upstream.terminate();
+            }
+            catch {
+                /* 已断 */
+            }
         }
-        reconnectDelay = RECONNECT_BASE_MS;
-        connect();
+        wsStreams.clear();
     }
     function connect() {
         if (shuttingDown)
             return;
-        const url = `${hubWsBase}/tunnel?token=${encodeURIComponent(token)}`;
-        const client = new WebSocket(url, { rejectUnauthorized: opts.insecure !== true });
+        const url = `${hubWsBase}/tunnel?token=${encodeURIComponent(opts.token)}`;
+        const client = new WebSocket(url, { rejectUnauthorized: !opts.insecure });
+        currentClient = client;
+        setState("connecting", { message: `connecting to ${opts.hubUrl}` });
         // 401/403 = token 被拒（吊销/不存在）。监听此事件后 ws 不再自动 abort，
         // 需手动 terminate → 触发 close → 决定「重配对」还是「普通重连」。
         let tokenRejected = false;
@@ -322,7 +345,8 @@ export async function join(opts) {
         });
         client.on("open", () => {
             reconnectDelay = RECONNECT_BASE_MS;
-            console.log("rdsh join: tunnel established (heartbeat 30s)");
+            setState("connected");
+            log("info", "tunnel established (heartbeat 30s)");
             if (heartbeat !== undefined)
                 clearInterval(heartbeat);
             heartbeat = setInterval(() => {
@@ -351,43 +375,22 @@ export async function join(opts) {
                 handleFrame(frame, client);
         });
         client.on("close", () => {
-            if (heartbeat !== undefined) {
-                clearInterval(heartbeat);
-                heartbeat = undefined;
-            }
-            for (const s of httpStreams.values()) {
-                try {
-                    s.up.destroy();
-                }
-                catch {
-                    /* 已断 */
-                }
-            }
-            httpStreams.clear();
-            for (const s of wsStreams.values()) {
-                try {
-                    s.upstream.terminate();
-                }
-                catch {
-                    /* 已断 */
-                }
-            }
-            wsStreams.clear();
+            cleanupStreams();
             if (shuttingDown)
                 return;
             if (tokenRejected) {
-                if (opts.token === undefined) {
-                    // 持久化 token 被拒 → 删旧文件 + 回退配对码
-                    void rebindAndReconnect();
-                    return;
-                }
-                // 显式 --token 被拒 = 永久失败（token 不会再变有效）→ fail-fast，
-                // 让脚本/systemd 拿到非零退出码与明确报错，而非静默无限重连
-                console.error("rdsh join: host token rejected by hub (revoked or removed); exiting.");
-                void shutdown("", 1);
+                // token 被拒（吊销/删除）= 永久失败，无法自动恢复
+                // → 删旧 session + 释放锁 + 停（fail-fast），不重连。
+                clearPersistedToken(opts.hubUrl);
+                const msg = "host token rejected by hub (revoked or removed); re-join with a new join token";
+                log("error", msg);
+                setState("rejected", { message: msg });
+                shuttingDown = true;
+                releaseJoinLock(opts.lockPath);
                 return;
             }
-            console.log(`rdsh join: tunnel lost — reconnecting in ${Math.round(reconnectDelay / 1000)}s...`);
+            setState("reconnecting", { delayMs: reconnectDelay });
+            log("info", `tunnel lost — reconnecting in ${Math.round(reconnectDelay / 1000)}s...`);
             setTimeout(connect, reconnectDelay + Math.random() * 500);
             reconnectDelay = Math.min(reconnectDelay * 2, RECONNECT_MAX_MS);
         });
@@ -401,7 +404,71 @@ export async function join(opts) {
         });
     }
     connect();
-    await keepAlive;
+    return {
+        async stop() {
+            if (shuttingDown)
+                return;
+            shuttingDown = true;
+            cleanupStreams();
+            if (currentClient !== undefined) {
+                try {
+                    currentClient.terminate();
+                }
+                catch {
+                    /* 已关闭 */
+                }
+            }
+            releaseJoinLock(opts.lockPath);
+            setState("stopped");
+        },
+    };
+}
+/** `rdsh host serve`（join 模式）的 CLI 封装：spawn dsh + 信号退出 + startJoin(role:cli)。 */
+export async function join(opts) {
+    const foundDsh = findDsh(opts.dshPath);
+    if (foundDsh === null) {
+        throw new Error("cannot find 'dsh' in PATH. Install DeepSeek Harness first, or pass --dsh <path>.");
+    }
+    const dsh = await spawnDsh(foundDsh);
+    const target = { host: "127.0.0.1", port: dsh.port };
+    // 解析 host token（含证书自动检测 + 持久化）；进程重启后复用，避免重复配对。
+    const { token, insecure } = await registerJoin(opts);
+    console.log(`rdsh join: dsh web on 127.0.0.1:${dsh.port}`);
+    console.log(`rdsh join: connecting to ${opts.hubUrl}...`);
+    const handle = startJoin({
+        hubUrl: opts.hubUrl,
+        token,
+        insecure,
+        target,
+        role: "cli",
+        hooks: {
+            onLog: (level, message) => {
+                (level === "error" ? console.error : console.log)(`rdsh join: ${message}`);
+            },
+            onState: (state, detail) => {
+                if (state === "rejected") {
+                    console.error(`rdsh join: ${detail?.message ?? "rejected"}`);
+                }
+            },
+        },
+    });
+    let shuttingDown = false;
+    const shutdown = async (signal, code = 0) => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        if (signal !== "")
+            console.log(`\nrdsh: received ${signal}, shutting down...`);
+        await handle.stop();
+        await dsh.stop();
+        process.exit(code);
+    };
+    process.on("SIGINT", () => void shutdown("SIGINT"));
+    process.on("SIGTERM", () => void shutdown("SIGTERM"));
+    process.on("SIGHUP", () => void shutdown("SIGHUP"));
+    // 常驻：进程靠信号退出（shutdown 里 process.exit）；防止函数返回后
+    // CLI 的 main().then(exit) 误退出服务进程
+    await new Promise(() => { });
 }
 function normalizeRespHeaders(headers) {
     const out = {};

package/dist/lock.d.ts

@@ -0,0 +1,24 @@
+export declare const JOIN_LOCK_PATH: string;
+export type JoinLockRole = "cli" | "plugin";
+export interface JoinLock {
+    pid: number;
+    role: JoinLockRole;
+}
+/**
+ * 读锁。不存在/损坏/过短 → null；pid 已死（stale）→ 清除文件并返回 null。
+ * 供面板「外部托管」态判定（role=cli）与 acquire 前检测复用。
+ */
+export declare function readJoinLock(path?: string): JoinLock | null;
+export type AcquireResult = {
+    ok: true;
+} | {
+    ok: false;
+    heldBy: JoinLock;
+};
+/**
+ * 获取锁：写入 `{pid: process.pid, role}`（目录 0700、文件 0600）。
+ * 已有**他人**（不同 pid）持有的活锁 → 拒绝（防同机双隧道）。
+ */
+export declare function acquireJoinLock(role: JoinLockRole, path?: string): AcquireResult;
+/** 释放锁：仅当锁是自己 pid 持有才删（不误删他人锁）。 */
+export declare function releaseJoinLock(path?: string): void;

package/dist/lock.js

@@ -0,0 +1,73 @@
+/**
+ * lock.ts — join pid 锁：CLI 与插件共享「单身份铁律」（同机单隧道，D5 档2）。
+ *
+ * 锁文件 `~/.rdsh/join.lock`（0600）记 `{pid, role}`；stale（pid 已死）自动视为无锁并清除。
+ * role = "cli"（rdsh CLI / systemd 服务持有）| "plugin"（dsh 插件持有）——面板据此显示「外部托管」。
+ */
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+const RDSH_DIR = join(homedir(), ".rdsh");
+export const JOIN_LOCK_PATH = join(RDSH_DIR, "join.lock");
+/** 探测 pid 是否存活：signal 0 不真正发信号；EPERM = 存活但无权限，ESRCH = 不存在。 */
+function isAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === "EPERM";
+    }
+}
+/**
+ * 读锁。不存在/损坏/过短 → null；pid 已死（stale）→ 清除文件并返回 null。
+ * 供面板「外部托管」态判定（role=cli）与 acquire 前检测复用。
+ */
+export function readJoinLock(path = JOIN_LOCK_PATH) {
+    try {
+        if (!existsSync(path))
+            return null;
+        const raw = JSON.parse(readFileSync(path, "utf8"));
+        if (typeof raw.pid !== "number" || (raw.role !== "cli" && raw.role !== "plugin"))
+            return null;
+        if (!isAlive(raw.pid)) {
+            try {
+                rmSync(path, { force: true });
+            }
+            catch {
+                /* 忽略 */
+            }
+            return null;
+        }
+        return { pid: raw.pid, role: raw.role };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 获取锁：写入 `{pid: process.pid, role}`（目录 0700、文件 0600）。
+ * 已有**他人**（不同 pid）持有的活锁 → 拒绝（防同机双隧道）。
+ */
+export function acquireJoinLock(role, path = JOIN_LOCK_PATH) {
+    const held = readJoinLock(path);
+    if (held !== null && held.pid !== process.pid) {
+        return { ok: false, heldBy: held };
+    }
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    writeFileSync(path, JSON.stringify({ pid: process.pid, role }), { mode: 0o600 });
+    return { ok: true };
+}
+/** 释放锁：仅当锁是自己 pid 持有才删（不误删他人锁）。 */
+export function releaseJoinLock(path = JOIN_LOCK_PATH) {
+    try {
+        const held = readJoinLock(path);
+        if (held !== null && held.pid === process.pid) {
+            rmSync(path, { force: true });
+        }
+    }
+    catch {
+        /* 忽略 */
+    }
+}
+//# sourceMappingURL=lock.js.map

package/dist/service.d.ts

@@ -1,11 +1,31 @@
+/** serve/hub 共用的服务名。 */
 export declare const SERVICE_NAME = "rdsh";
-/** systemd 用户级 unit 模板。subcommandArgs 默认 ["serve"]（hub 用 ["hub","serve"]）。 */
-export declare function systemdUnit(execStart: string, configPath: string, subcommandArgs?: string[]): string;
+/** join 的独立服务名（同机可与 hub 的 rdsh.service 并存）。 */
+export declare const JOIN_SERVICE_NAME = "rdsh-join";
+/** host 独立服务（lan/cloud）的独立服务名。 */
+export declare const HOST_SERVICE_NAME = "rdsh-host";
+/** hub 的独立服务名（与 host/join 区分，避免共用 rdsh.service）。 */
+export declare const HUB_SERVICE_NAME = "rdsh-hub";
+/** 服务化规格。 */
+export interface ServiceSpec {
+    /** 服务名（systemd unit 文件名 / launchd Label）。 */
+    name: string;
+    /** 命令参数（不含 --config）。如 ["serve"] / ["hub","serve"] / ["join",hubUrl,"--dsh",abs]。 */
+    args: string[];
+    /** 配置文件路径；提供则追加 `--config <path>`（serve/hub）。 */
+    configPath?: string;
+    /** 环境文件路径；提供则在 systemd unit 追加 `EnvironmentFile=-<path>`（launchd 暂不支持，忽略）。 */
+    envFile?: string;
+    /** 子进程（spawn dsh）所需的 PATH（nvm/自装 node 环境下补 node 目录，防 dsh shebang 127）。 */
+    pathEnv?: string;
+}
+/** systemd 用户级 unit 模板。 */
+export declare function systemdUnit(execStart: string, spec: ServiceSpec): string;
 /** launchd plist 模板。 */
-export declare function launchdPlist(execStart: string, configPath: string, subcommandArgs?: string[]): string;
-/** 安装并启动服务（用户级）。subcommandArgs 默认 ["serve"]（hub 用 ["hub","serve"]）。 */
-export declare function installService(configPath: string, subcommandArgs?: string[]): Promise<string>;
+export declare function launchdPlist(execStart: string, spec: ServiceSpec): string;
+/** 安装并启动服务（用户级）。 */
+export declare function installService(spec: ServiceSpec): Promise<string>;
 /** 服务状态。 */
-export declare function serviceStatus(): Promise<string>;
+export declare function serviceStatus(name?: string): Promise<string>;
 /** 停止并移除服务。 */
-export declare function uninstallService(): Promise<string>;
+export declare function uninstallService(name?: string): Promise<string>;

package/dist/service.js

@@ -4,6 +4,8 @@
  * 设计（roadmap M2）：不自带 fork 后台 —— 交给系统进程管理器托管 rdsh（连带其
  * spawn 的 dsh）；用户级安装（~/.config/systemd/user / ~/Library/LaunchAgents），
  * 无需 sudo；开机自启 + 崩溃重启（Restart=on-failure / KeepAlive）。
+ *
+ * 服务名：serve/hub 共用 "rdsh"；join 用 "rdsh-join"（同机可与 hub 并存，互不覆盖）。
  */
 import { mkdir, rm, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
@@ -11,27 +13,44 @@ import { join } from "node:path";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 const execFileP = promisify(execFile);
+/** serve/hub 共用的服务名。 */
 export const SERVICE_NAME = "rdsh";
+/** join 的独立服务名（同机可与 hub 的 rdsh.service 并存）。 */
+export const JOIN_SERVICE_NAME = "rdsh-join";
+/** host 独立服务（lan/cloud）的独立服务名。 */
+export const HOST_SERVICE_NAME = "rdsh-host";
+/** hub 的独立服务名（与 host/join 区分，避免共用 rdsh.service）。 */
+export const HUB_SERVICE_NAME = "rdsh-hub";
 const SYSTEMD_DIR = join(homedir(), ".config", "systemd", "user");
-const SYSTEMD_UNIT = join(SYSTEMD_DIR, "rdsh.service");
 const LAUNCHD_DIR = join(homedir(), "Library", "LaunchAgents");
-const LAUNCHD_PLIST = join(LAUNCHD_DIR, "com.rdsh.plist");
+function systemdUnitPath(name) {
+    return join(SYSTEMD_DIR, `${name}.service`);
+}
+function launchdPlistPath(name) {
+    return join(LAUNCHD_DIR, `com.${name}.plist`);
+}
 function isLinux() {
     return process.platform === "linux";
 }
-function serviceLogPath() {
-    return join(homedir(), ".rdsh", "service.log");
+/** 日志文件：rdsh → service.log（历史兼容）；其余按服务名（如 rdsh-join.log）。 */
+function serviceLogPath(name) {
+    return join(homedir(), ".rdsh", name === SERVICE_NAME ? "service.log" : `${name}.log`);
+}
+/** 命令参数（是否追加 --config）。 */
+function commandArgs(spec) {
+    return spec.configPath !== undefined ? [...spec.args, "--config", spec.configPath] : spec.args;
 }
-/** systemd 用户级 unit 模板。subcommandArgs 默认 ["serve"]（hub 用 ["hub","serve"]）。 */
-export function systemdUnit(execStart, configPath, subcommandArgs = ["serve"]) {
-    const args = [...subcommandArgs, "--config", configPath].join(" ");
+/** systemd 用户级 unit 模板。 */
+export function systemdUnit(execStart, spec) {
+    const envLine = spec.envFile !== undefined ? `EnvironmentFile=-${spec.envFile}\n` : "";
+    const pathLine = spec.pathEnv !== undefined ? `Environment=PATH=${spec.pathEnv}\n` : "";
     return `[Unit]
 Description=rdsh — remote access for DeepSeek Harness
 After=network.target
 
 [Service]
 Type=simple
-ExecStart=${execStart} ${args}
+${envLine}${pathLine}ExecStart=${execStart} ${commandArgs(spec).join(" ")}
 Restart=on-failure
 RestartSec=3
 
@@ -40,14 +59,22 @@ WantedBy=default.target
 `;
 }
 /** launchd plist 模板。 */
-export function launchdPlist(execStart, configPath, subcommandArgs = ["serve"]) {
-    const args = [...subcommandArgs, "--config", configPath].map((a) => `    <string>${a}</string>`).join("\n");
+export function launchdPlist(execStart, spec) {
+    const args = commandArgs(spec).map((a) => `    <string>${a}</string>`).join("\n");
+    const envBlock = spec.pathEnv !== undefined
+        ? `  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key>
+    <string>${spec.pathEnv}</string>
+  </dict>
+`
+        : "";
     return `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
 <dict>
   <key>Label</key>
-  <string>com.rdsh</string>
+  <string>com.${spec.name}</string>
   <key>ProgramArguments</key>
   <array>
     <string>${execStart}</string>
@@ -57,10 +84,10 @@ ${args}
   <true/>
   <key>KeepAlive</key>
   <true/>
-  <key>StandardOutPath</key>
-  <string>${serviceLogPath()}</string>
+${envBlock}  <key>StandardOutPath</key>
+  <string>${serviceLogPath(spec.name)}</string>
   <key>StandardErrorPath</key>
-  <string>${serviceLogPath()}</string>
+  <string>${serviceLogPath(spec.name)}</string>
 </dict>
 </plist>
 `;
@@ -74,26 +101,26 @@ async function run(cmd, args) {
         throw new Error(`${cmd} ${args.join(" ")} failed: ${err.message}`);
     }
 }
-/** 安装并启动服务（用户级）。subcommandArgs 默认 ["serve"]（hub 用 ["hub","serve"]）。 */
-export async function installService(configPath, subcommandArgs = ["serve"]) {
+/** 安装并启动服务（用户级）。 */
+export async function installService(spec) {
     const execStart = `${process.execPath} ${process.argv[1]}`;
     if (isLinux()) {
         await mkdir(SYSTEMD_DIR, { recursive: true });
-        await writeFile(SYSTEMD_UNIT, systemdUnit(execStart, configPath, subcommandArgs), { mode: 0o600 });
+        await writeFile(systemdUnitPath(spec.name), systemdUnit(execStart, spec), { mode: 0o600 });
         await run("systemctl", ["--user", "daemon-reload"]);
-        await run("systemctl", ["--user", "enable", "--now", SERVICE_NAME]);
-        return `installed systemd user unit: ${SYSTEMD_UNIT}`;
+        await run("systemctl", ["--user", "enable", "--now", spec.name]);
+        return `installed systemd user unit: ${systemdUnitPath(spec.name)}`;
     }
     await mkdir(LAUNCHD_DIR, { recursive: true });
-    await writeFile(LAUNCHD_PLIST, launchdPlist(execStart, configPath, subcommandArgs), { mode: 0o600 });
-    await run("launchctl", ["load", LAUNCHD_PLIST]);
-    return `installed launchd plist: ${LAUNCHD_PLIST}`;
+    await writeFile(launchdPlistPath(spec.name), launchdPlist(execStart, spec), { mode: 0o600 });
+    await run("launchctl", ["load", launchdPlistPath(spec.name)]);
+    return `installed launchd plist: ${launchdPlistPath(spec.name)}`;
 }
 /** 服务状态。 */
-export async function serviceStatus() {
+export async function serviceStatus(name = SERVICE_NAME) {
     if (isLinux()) {
         try {
-            const active = await run("systemctl", ["--user", "is-active", SERVICE_NAME]);
+            const active = await run("systemctl", ["--user", "is-active", name]);
             return `active: ${active}`;
         }
         catch {
@@ -101,7 +128,7 @@ export async function serviceStatus() {
         }
     }
     try {
-        await run("launchctl", ["print", "com.rdsh"]);
+        await run("launchctl", ["print", `com.${name}`]);
         return "active";
     }
     catch {
@@ -109,15 +136,15 @@ export async function serviceStatus() {
     }
 }
 /** 停止并移除服务。 */
-export async function uninstallService() {
+export async function uninstallService(name = SERVICE_NAME) {
     if (isLinux()) {
-        await run("systemctl", ["--user", "disable", "--now", SERVICE_NAME]).catch(() => undefined);
-        await rm(SYSTEMD_UNIT, { force: true });
+        await run("systemctl", ["--user", "disable", "--now", name]).catch(() => undefined);
+        await rm(systemdUnitPath(name), { force: true });
         await run("systemctl", ["--user", "daemon-reload"]).catch(() => undefined);
-        return `removed ${SYSTEMD_UNIT}`;
+        return `removed ${systemdUnitPath(name)}`;
     }
-    await run("launchctl", ["unload", LAUNCHD_PLIST]).catch(() => undefined);
-    await rm(LAUNCHD_PLIST, { force: true });
-    return `removed ${LAUNCHD_PLIST}`;
+    await run("launchctl", ["unload", launchdPlistPath(name)]).catch(() => undefined);
+    await rm(launchdPlistPath(name), { force: true });
+    return `removed ${launchdPlistPath(name)}`;
 }
 //# sourceMappingURL=service.js.map

package/dist/token-store.js

@@ -2,7 +2,7 @@
  * token-store.ts — `rdsh join` host token 持久化（~/.rdsh/join-<host>[-<port>].token，0600）。
  *
  * 目的：进程重启/崩溃恢复后复用已绑定的 host token，避免每次重新配对；
- * 被 hub 拒绝（吊销/重置）时由 join 删除该文件并回退到配对码流程。
+ * 被 hub 拒绝（吊销/重置）时由 join 删除该文件并提示重新接入（无自动重配）。
  *
  * 安全：明文 token 只落 gateway 本地（0600），hub 侧仍只存 SHA-256 摘要。
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rdsh-gateway",
-  "version": "0.2.3",
+  "version": "0.4.0",
   "description": "rdsh host-side component: LAN auth gateway + outbound tunnel endpoint (spawns dsh web)",
   "license": "MIT",
   "type": "module",