rdsh-gateway 0.3.0 → 0.5.0

package/dist/e2ee-key-store.d.ts

@@ -0,0 +1,5 @@
+import type { KeyPair } from "./e2ee.ts";
+/** 密钥文件路径（可注入 dir 便于测试）。 */
+export declare function e2eeKeyFilePath(dir?: string): string;
+/** 加载或生成 host E2EE 静态密钥对（一次生成，持久化复用；损坏则重新生成）。 */
+export declare function loadOrCreateE2eeKeyPair(dir?: string): KeyPair;

package/dist/e2ee-key-store.js

@@ -0,0 +1,42 @@
+/**
+ * e2ee-key-store.ts — host 端 E2EE 静态密钥对持久化（~/.rdsh/e2ee-key.json，0600）。
+ *
+ * 一次生成、跨 hub 复用（host 身份与 join 到哪个 hub 无关）；指纹（公钥）在 join 注册时
+ * 上送 hub，供 portal「添加主机」pin 展示。
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { generateKeyPair, deserializeKeyPair, serializeKeyPair } from "./e2ee.js";
+const RDSH_DIR = join(homedir(), ".rdsh");
+const KEY_FILE_NAME = "e2ee-key.json";
+/** 密钥文件路径（可注入 dir 便于测试）。 */
+export function e2eeKeyFilePath(dir = RDSH_DIR) {
+    return join(dir, KEY_FILE_NAME);
+}
+/** 加载或生成 host E2EE 静态密钥对（一次生成，持久化复用；损坏则重新生成）。 */
+export function loadOrCreateE2eeKeyPair(dir = RDSH_DIR) {
+    const p = e2eeKeyFilePath(dir);
+    try {
+        if (existsSync(p)) {
+            const j = JSON.parse(readFileSync(p, "utf8"));
+            if (typeof j.publicRaw === "string" && typeof j.privateRaw === "string") {
+                return deserializeKeyPair(j.publicRaw, j.privateRaw);
+            }
+        }
+    }
+    catch {
+        /* 损坏 → 重新生成 */
+    }
+    const kp = generateKeyPair();
+    const s = serializeKeyPair(kp);
+    try {
+        mkdirSync(dirname(p), { recursive: true, mode: 0o700 });
+        writeFileSync(p, JSON.stringify(s), { mode: 0o600 });
+    }
+    catch {
+        /* 写失败 → 用内存密钥（下次重启指纹会变，属异常场景） */
+    }
+    return kp;
+}
+//# sourceMappingURL=e2ee-key-store.js.map

package/dist/e2ee.d.ts

@@ -0,0 +1,45 @@
+import type { KeyObject } from "node:crypto";
+export declare const PROTOCOL_LABEL: Buffer<ArrayBuffer>;
+export interface KeyPair {
+    privateKey: KeyObject;
+    publicRaw: Buffer;
+}
+export interface E2eeKeys {
+    /** initiator（浏览器）→ responder（host）方向密钥 */
+    initiatorToResponder: Buffer;
+    /** responder（host）→ initiator（浏览器）方向密钥 */
+    responderToInitiator: Buffer;
+}
+/** 生成 X25519 密钥对。 */
+export declare function generateKeyPair(): KeyPair;
+export declare function publicToRaw(pub: KeyObject): Buffer;
+export declare function publicFromRaw(raw: Buffer): KeyObject;
+export declare function privateFromRaw(raw: Buffer): KeyObject;
+/** 持久化：raw 私钥 + 公钥（base64url 字符串）。 */
+export declare function serializeKeyPair(kp: KeyPair): {
+    publicRaw: string;
+    privateRaw: string;
+};
+export declare function deserializeKeyPair(publicRaw: string, privateRaw: string): KeyPair;
+/** X25519 共享密钥（32B）。 */
+export declare function ecdh(privateKey: KeyObject, theirPublicRaw: Buffer): Buffer;
+/** HKDF 派生双向密钥。 */
+export declare function deriveKeys(sharedSecret: Buffer): E2eeKeys;
+/** 指纹（pinning 展示）：SHA-256 前 8 字节 hex 分组。 */
+export declare function fingerprint(publicRaw: Buffer): string;
+/** 发起方（浏览器）：临时密钥 × host 静态公钥 → 会话密钥；返回要发送的临时公钥。 */
+export declare function initiatorHandshake(responderStaticPublicRaw: Buffer): {
+    ephemeralPublicRaw: Buffer;
+    keys: E2eeKeys;
+};
+/** 响应方（host）：静态私钥 × 收到的发起方临时公钥 → 会话密钥。 */
+export declare function responderHandshake(staticKeyPair: KeyPair, initiatorEphemeralPublicRaw: Buffer): E2eeKeys;
+/** AES-256-GCM 包：[12B nonce][ciphertext][16B tag]。显式 nonce（每方向独立计数，防错）。 */
+export declare class Aead {
+    private readonly key;
+    private counter;
+    constructor(key: Buffer);
+    encrypt(plaintext: Buffer, aad: Buffer): Buffer;
+    decrypt(packet: Buffer, aad: Buffer): Buffer;
+    private nextNonce;
+}

package/dist/e2ee.js

@@ -0,0 +1,102 @@
+/**
+ * e2ee.ts — 内层 Noise NK（X25519 + HKDF-SHA256 + AES-256-GCM）Node 端（gateway 用）。
+ *
+ * 简化自 Noise NK 模式（host 静态密钥 + 浏览器临时密钥，浏览器靠 pin 认证 host）：
+ * - 共享密钥 = X25519(本端私钥, 对端公钥)
+ * - 派生 = HKDF-SHA256(ikm=ss, salt=PROTOCOL_LABEL, info="session") → 64B → [initiator→responder(32), responder→initiator(32)]
+ * - AEAD = AES-256-GCM，包格式 [12B nonce][ciphertext][16B tag]，显式 nonce + 每方向独立计数
+ *
+ * 注：为浏览器 WebCrypto 兼容选 AES-256-GCM（ChaCha20-Poly1305 在 WebCrypto 支持不普及）。
+ * 上线前建议与 Noise 规范 / 被审计库交叉复核（见 solution.md §6/§7）。
+ */
+import { generateKeyPairSync, createPublicKey, createPrivateKey, diffieHellman, hkdfSync, createCipheriv, createDecipheriv, createHash, } from "node:crypto";
+export const PROTOCOL_LABEL = Buffer.from("rdsh-e2ee-nk-v1");
+const NONCE_LEN = 12;
+const TAG_LEN = 16;
+const KEY_LEN = 32;
+/** X25519 PKCS8 DER 前缀（16B，后接 32B raw 私钥）。 */
+const PKCS8_X25519_PREFIX = Buffer.from("302e020100300506032b656e04220420", "hex");
+/** 生成 X25519 密钥对。 */
+export function generateKeyPair() {
+    const { publicKey, privateKey } = generateKeyPairSync("x25519");
+    return { privateKey, publicRaw: publicToRaw(publicKey) };
+}
+export function publicToRaw(pub) {
+    const jwk = pub.export({ format: "jwk" });
+    return Buffer.from(jwk.x, "base64url");
+}
+export function publicFromRaw(raw) {
+    return createPublicKey({ key: { kty: "OKP", crv: "X25519", x: raw.toString("base64url") }, format: "jwk" });
+}
+export function privateFromRaw(raw) {
+    return createPrivateKey({ key: Buffer.concat([PKCS8_X25519_PREFIX, raw]), format: "der", type: "pkcs8" });
+}
+/** 持久化：raw 私钥 + 公钥（base64url 字符串）。 */
+export function serializeKeyPair(kp) {
+    const jwk = kp.privateKey.export({ format: "jwk" });
+    return { publicRaw: kp.publicRaw.toString("base64url"), privateRaw: Buffer.from(jwk.d, "base64url").toString("base64url") };
+}
+export function deserializeKeyPair(publicRaw, privateRaw) {
+    return { privateKey: privateFromRaw(Buffer.from(privateRaw, "base64url")), publicRaw: Buffer.from(publicRaw, "base64url") };
+}
+/** X25519 共享密钥（32B）。 */
+export function ecdh(privateKey, theirPublicRaw) {
+    return diffieHellman({ privateKey, publicKey: publicFromRaw(theirPublicRaw) });
+}
+/** HKDF 派生双向密钥。 */
+export function deriveKeys(sharedSecret) {
+    const okm = Buffer.from(hkdfSync("sha256", sharedSecret, PROTOCOL_LABEL, Buffer.from("session"), 2 * KEY_LEN));
+    return {
+        initiatorToResponder: okm.subarray(0, KEY_LEN),
+        responderToInitiator: okm.subarray(KEY_LEN, 2 * KEY_LEN),
+    };
+}
+/** 指纹（pinning 展示）：SHA-256 前 8 字节 hex 分组。 */
+export function fingerprint(publicRaw) {
+    const h = createHash("sha256").update(publicRaw).digest("hex").slice(0, 16).toUpperCase();
+    return `${h.slice(0, 4)}-${h.slice(4, 8)}-${h.slice(8, 12)}-${h.slice(12, 16)}`;
+}
+/** 发起方（浏览器）：临时密钥 × host 静态公钥 → 会话密钥；返回要发送的临时公钥。 */
+export function initiatorHandshake(responderStaticPublicRaw) {
+    const eph = generateKeyPair();
+    const ss = ecdh(eph.privateKey, responderStaticPublicRaw);
+    return { ephemeralPublicRaw: eph.publicRaw, keys: deriveKeys(ss) };
+}
+/** 响应方（host）：静态私钥 × 收到的发起方临时公钥 → 会话密钥。 */
+export function responderHandshake(staticKeyPair, initiatorEphemeralPublicRaw) {
+    const ss = ecdh(staticKeyPair.privateKey, initiatorEphemeralPublicRaw);
+    return deriveKeys(ss);
+}
+/** AES-256-GCM 包：[12B nonce][ciphertext][16B tag]。显式 nonce（每方向独立计数，防错）。 */
+export class Aead {
+    key;
+    counter = 0n;
+    constructor(key) {
+        this.key = key;
+    }
+    encrypt(plaintext, aad) {
+        const nonce = this.nextNonce();
+        const cipher = createCipheriv("aes-256-gcm", this.key, nonce);
+        cipher.setAAD(aad);
+        const ct = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+        return Buffer.concat([nonce, ct, cipher.getAuthTag()]);
+    }
+    decrypt(packet, aad) {
+        if (packet.length < NONCE_LEN + TAG_LEN)
+            throw new Error("e2ee: packet too short");
+        const nonce = packet.subarray(0, NONCE_LEN);
+        const tag = packet.subarray(packet.length - TAG_LEN);
+        const ct = packet.subarray(NONCE_LEN, packet.length - TAG_LEN);
+        const decipher = createDecipheriv("aes-256-gcm", this.key, nonce);
+        decipher.setAAD(aad);
+        decipher.setAuthTag(tag);
+        return Buffer.concat([decipher.update(ct), decipher.final()]);
+    }
+    nextNonce() {
+        const n = Buffer.alloc(NONCE_LEN);
+        n.writeBigUInt64BE(this.counter, NONCE_LEN - 8);
+        this.counter += 1n;
+        return n;
+    }
+}
+//# sourceMappingURL=e2ee.js.map

package/dist/index.d.ts

@@ -24,6 +24,8 @@ export { loginPageHtml } from "./login-page.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, registerJoin, detectInsecure, selfRevoke } from "./join.ts";
-export type { JoinOptions, RegisterOutcome } 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

@@ -16,6 +16,7 @@ export { loadTls } from "./tls.js";
 export { loginPageHtml } from "./login-page.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, registerJoin, detectInsecure, selfRevoke } 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,3 +1,5 @@
+import type { ProxyTarget } from "./proxy.ts";
+import type { JoinLockRole } from "./lock.ts";
 export interface JoinOptions {
     hubUrl: string;
     /** join token（用户级，register 换 host token） */
@@ -10,10 +12,39 @@ export interface JoinOptions {
     /** 主机名（注册命名 / host.json） */
     name?: string;
 }
-/** 注册/接入结果：解析出的 host token + 是否需 insecure。 */
+/** 注册/接入结果：解析出的 host token + 是否需 insecure + 生效的主机名（缺省=机器 hostname）。 */
 export interface RegisterOutcome {
     token: string;
     insecure: boolean;
+    name: string;
+}
+/** 隧道状态机（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>;
@@ -21,4 +52,10 @@ export declare function detectInsecure(hubUrl: string): Promise<boolean>;
 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

@@ -5,14 +5,21 @@
  * → 帧循环（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";
+import { hostname as osHostname } from "node:os";
 import { WebSocket } from "ws";
-import { FrameParser, FRAME_TYPE, encodeFrame, jsonPayload, parseJsonPayload } from "rdsh-tunnel";
+import { FrameParser, FRAME_TYPE, encodeFrame, jsonPayload, parseJsonPayload, FLAG_E2E } from "rdsh-tunnel";
 import { findDsh, spawnDsh } from "./spawn-dsh.js";
 import { rewriteHeadersForDsh } from "./proxy.js";
 import { clearPersistedToken, persistToken, readPersistedToken } from "./token-store.js";
+import { acquireJoinLock, releaseJoinLock } from "./lock.js";
+import { responderHandshake, Aead } from "./e2ee.js";
+import { loadOrCreateE2eeKeyPair } from "./e2ee-key-store.js";
 /** 判断错误是否为 TLS 证书类错误（自签/过期/域名不匹配）。 */
 function isCertError(err) {
     const code = err?.code ?? "";
@@ -77,10 +84,13 @@ export async function selfRevoke(hubUrl, token, insecure) {
 /** 解析 host token（--token 注册 > 持久化复用）+ 自动检测证书；供 CLI 配置命令与 join() 复用。 */
 export async function registerJoin(opts) {
     const insecure = opts.insecure === true || (await detectInsecure(opts.hubUrl));
+    // 主机名缺省 = 机器 hostname（CLI / service install / 插件三条路径统一；--name 可覆盖）
+    const name = opts.name !== undefined && opts.name.trim() !== "" ? opts.name.trim() : osHostname();
     let token;
     if (opts.token !== undefined) {
         // --token = join token（或旧 host token）→ register 端点换 host token
-        const { hostToken } = await register(opts.hubUrl, opts.token, opts.name, insecure);
+        const e2eeKeyPair = loadOrCreateE2eeKeyPair();
+        const { hostToken } = await register(opts.hubUrl, opts.token, name, insecure, e2eeKeyPair.publicRaw.toString("base64url"));
         token = hostToken;
         persistToken(opts.hubUrl, token);
     }
@@ -96,11 +106,14 @@ export async function registerJoin(opts) {
             throw new Error("未接入：无持久化 session 且未提供 --token；先 `rdsh host join <hub>` 生成/粘贴 join token");
         }
     }
-    return { token, insecure };
+    return { token, insecure, name };
 }
 /** 调 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 } });
+async function register(hubUrl, joinToken, name, insecure, e2eePublicKey) {
+    const body = { token: joinToken, name };
+    if (e2eePublicKey !== undefined)
+        body.e2eePublicKey = e2eePublicKey;
+    const res = await hubRequest(hubUrl, "/api/hosts/register", { method: "POST", insecure, body });
     if (!res.ok) {
         const msg = res.body.error?.message ?? `HTTP ${res.status}`;
         throw new Error(`hub rejected register: ${msg}`);
@@ -111,206 +124,305 @@ async function register(hubUrl, joinToken, name, insecure) {
     }
     return { hostId: b.hostId, hostToken: b.hostToken };
 }
-export async function join(opts) {
+/**
+ * 启动 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 foundDsh = findDsh(opts.dshPath);
-    if (foundDsh === null) {
-        throw new Error("cannot find 'dsh' in PATH. Install DeepSeek Harness first, or pass --dsh <path>.");
+    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 dsh = await spawnDsh(foundDsh);
-    const target = { host: "127.0.0.1", port: dsh.port };
-    // 解析 host token（含证书自动检测 + 持久化）；进程重启后复用，避免重复配对。
-    const { token: initialToken, insecure } = await registerJoin(opts);
-    let token = initialToken;
-    console.log(`rdsh join: dsh web on 127.0.0.1:${dsh.port}`);
-    console.log(`rdsh join: connecting to ${opts.hubUrl}...`);
     const parser = new FrameParser();
-    /** http 流：streamId → 本地请求（写请求体 / 结束）。 */
-    const httpStreams = new Map();
-    /** ws 流：streamId → 本地 ws 客户端（DATA 帧 → upstream）。 */
-    const wsStreams = new Map();
     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(() => { });
-    function handleFrame(frame, client) {
-        switch (frame.type) {
-            case FRAME_TYPE.PING: {
-                client.send(encodeFrame(FRAME_TYPE.PONG, frame.streamId, frame.payload));
+    let currentClient;
+    /** 发送一个隧道帧（走当前隧道 WS；flags 由调用方在 encodeFrame 时给定）。 */
+    function sendTunnelFrame(frame) {
+        if (currentClient !== undefined && currentClient.readyState === currentClient.OPEN) {
+            currentClient.send(frame);
+        }
+    }
+    /** 内层帧分发器（plain 与 raw 共用）：OPEN http/ws + DATA → DSH 转发，响应帧经 `send` 回传。 */
+    function makeInnerDispatcher(send) {
+        const httpStreams = new Map();
+        const wsStreams = new Map();
+        function closeStream(streamId) {
+            const ws = wsStreams.get(streamId);
+            if (ws !== undefined) {
+                wsStreams.delete(streamId);
+                try {
+                    ws.upstream.terminate();
+                }
+                catch {
+                    /* 已关闭 */
+                }
                 return;
             }
-            case FRAME_TYPE.PONG:
+            const http = httpStreams.get(streamId);
+            if (http !== undefined) {
+                httpStreams.delete(streamId);
+                http.up.end();
+            }
+        }
+        function openWsStream(streamId, path, headers) {
+            const upstream = new WebSocket(`ws://${opts.target.host}:${opts.target.port}${path}`, {
+                headers: rewriteHeadersForDsh(headers, opts.target),
+            });
+            const queue = [];
+            wsStreams.set(streamId, { upstream, queue });
+            upstream.on("open", () => {
+                for (const q of queue)
+                    upstream.send(q, { binary: false });
+                queue.length = 0;
+            });
+            upstream.on("message", (data) => {
+                const buf = Array.isArray(data)
+                    ? Buffer.concat(data)
+                    : Buffer.isBuffer(data)
+                        ? data
+                        : Buffer.from(data);
+                send(encodeFrame(FRAME_TYPE.DATA, streamId, buf));
+            });
+            const cleanup = () => {
+                wsStreams.delete(streamId);
+                send(encodeFrame(FRAME_TYPE.CLOSE, streamId, jsonPayload({ code: 0 })));
+            };
+            upstream.on("close", cleanup);
+            upstream.on("error", cleanup);
+        }
+        function handleOpen(frame) {
+            let kind;
+            let method = "GET";
+            let path = "/";
+            let headers = {};
+            try {
+                const p = parseJsonPayload(frame);
+                kind = p.kind;
+                if (typeof p.method === "string")
+                    method = p.method;
+                if (typeof p.path === "string")
+                    path = p.path;
+                if (typeof p.headers === "object" && p.headers !== null)
+                    headers = p.headers;
+            }
+            catch {
+                send(encodeFrame(FRAME_TYPE.ERROR, frame.streamId, jsonPayload({ code: "BAD_OPEN", message: "malformed open" })));
                 return;
-            case FRAME_TYPE.OPEN: {
-                handleOpen(frame, client);
+            }
+            if (kind === "ws") {
+                openWsStream(frame.streamId, path, headers);
                 return;
             }
-            case FRAME_TYPE.DATA: {
-                const ws = wsStreams.get(frame.streamId);
-                if (ws !== undefined) {
-                    if (ws.upstream.readyState === ws.upstream.OPEN) {
-                        ws.upstream.send(frame.payload, { binary: false }); // DSH WS 为 text(JSON)，保持文本帧
-                    }
-                    else {
-                        ws.queue.push(frame.payload);
+            if (kind !== "http") {
+                send(encodeFrame(FRAME_TYPE.ERROR, frame.streamId, jsonPayload({ code: "BAD_OPEN", message: "unknown kind" })));
+                return;
+            }
+            const streamId = frame.streamId;
+            const up = httpRequest({
+                host: opts.target.host,
+                port: opts.target.port,
+                path,
+                method,
+                headers: rewriteHeadersForDsh(headers, opts.target),
+            }, (upRes) => {
+                send(encodeFrame(FRAME_TYPE.OPEN, streamId, jsonPayload({
+                    kind: "http",
+                    status: upRes.statusCode ?? 502,
+                    reason: upRes.statusMessage,
+                    headers: normalizeRespHeaders(upRes.headers),
+                })));
+                upRes.on("data", (chunk) => {
+                    send(encodeFrame(FRAME_TYPE.DATA, streamId, chunk));
+                });
+                upRes.on("end", () => {
+                    send(encodeFrame(FRAME_TYPE.CLOSE, streamId, jsonPayload({ code: 0 })));
+                    httpStreams.delete(streamId);
+                });
+                upRes.on("error", () => {
+                    send(encodeFrame(FRAME_TYPE.CLOSE, streamId, jsonPayload({ code: 502, message: "upstream error" })));
+                    httpStreams.delete(streamId);
+                });
+            });
+            up.on("error", () => {
+                send(encodeFrame(FRAME_TYPE.ERROR, streamId, jsonPayload({ code: "UPSTREAM_UNREACHABLE", message: "dsh not reachable" })));
+                httpStreams.delete(streamId);
+            });
+            httpStreams.set(streamId, { up });
+        }
+        function handleFrame(frame) {
+            switch (frame.type) {
+                case FRAME_TYPE.OPEN: {
+                    handleOpen(frame);
+                    return;
+                }
+                case FRAME_TYPE.DATA: {
+                    const ws = wsStreams.get(frame.streamId);
+                    if (ws !== undefined) {
+                        if (ws.upstream.readyState === ws.upstream.OPEN)
+                            ws.upstream.send(frame.payload, { binary: false }); // DSH WS 为 text(JSON)
+                        else
+                            ws.queue.push(frame.payload);
+                        return;
                     }
+                    const http = httpStreams.get(frame.streamId);
+                    if (http !== undefined)
+                        http.up.write(frame.payload);
                     return;
                 }
-                const http = httpStreams.get(frame.streamId);
-                if (http !== undefined)
-                    http.up.write(frame.payload);
-                return;
+                case FRAME_TYPE.CLOSE:
+                case FRAME_TYPE.ERROR: {
+                    closeStream(frame.streamId);
+                    return;
+                }
+                default:
+                    return;
             }
-            case FRAME_TYPE.CLOSE: {
-                closeStream(frame.streamId);
-                return;
+        }
+        function cleanup() {
+            for (const s of httpStreams.values()) {
+                try {
+                    s.up.destroy();
+                }
+                catch {
+                    /* 已断 */
+                }
             }
-            case FRAME_TYPE.ERROR: {
-                closeStream(frame.streamId);
-                return;
+            httpStreams.clear();
+            for (const s of wsStreams.values()) {
+                try {
+                    s.upstream.terminate();
+                }
+                catch {
+                    /* 已断 */
+                }
             }
-            default:
-                return;
+            wsStreams.clear();
         }
+        return { handleFrame, cleanup };
     }
-    function closeStream(streamId) {
-        const ws = wsStreams.get(streamId);
-        if (ws !== undefined) {
-            wsStreams.delete(streamId);
-            try {
-                ws.upstream.terminate();
-            }
-            catch {
-                /* 已关闭 */
+    const plainDispatcher = makeInnerDispatcher(sendTunnelFrame);
+    // host 端 E2EE 静态密钥对（持久化 ~/.rdsh/e2ee-key.json；join 注册时上送指纹）
+    const hostE2eeKeypair = loadOrCreateE2eeKeyPair();
+    const rawStreams = new Map();
+    function startRawStream(streamId) {
+        const inner = makeInnerDispatcher((frame) => {
+            const raw = rawStreams.get(streamId);
+            if (raw?.encryptor !== null && raw?.encryptor !== undefined) {
+                const ct = raw.encryptor.encrypt(frame, Buffer.alloc(0));
+                sendTunnelFrame(encodeFrame(FRAME_TYPE.DATA, streamId, ct, FLAG_E2E));
             }
-            return;
-        }
-        const http = httpStreams.get(streamId);
-        if (http !== undefined) {
-            httpStreams.delete(streamId);
-            http.up.end();
-        }
+        });
+        rawStreams.set(streamId, {
+            handshakeBuf: Buffer.alloc(0),
+            keys: null,
+            decryptor: null,
+            encryptor: null,
+            innerParser: new FrameParser(),
+            inner,
+        });
     }
-    function handleOpen(frame, client) {
-        let kind;
-        let method = "GET";
-        let path = "/";
-        let headers = {};
+    function handleRawData(streamId, state, chunk) {
         try {
-            const p = parseJsonPayload(frame);
-            kind = p.kind;
-            if (typeof p.method === "string")
-                method = p.method;
-            if (typeof p.path === "string")
-                path = p.path;
-            if (typeof p.headers === "object" && p.headers !== null)
-                headers = p.headers;
+            if (state.keys === null) {
+                // Noise 握手：缓冲到 32B（发起方临时公钥）→ 派生密钥
+                state.handshakeBuf = Buffer.concat([state.handshakeBuf, chunk]);
+                if (state.handshakeBuf.length < 32)
+                    return;
+                const ephPub = state.handshakeBuf.subarray(0, 32);
+                state.handshakeBuf = state.handshakeBuf.subarray(32);
+                state.keys = responderHandshake(hostE2eeKeypair, ephPub);
+                state.decryptor = new Aead(state.keys.initiatorToResponder);
+                state.encryptor = new Aead(state.keys.responderToInitiator);
+                if (state.handshakeBuf.length === 0)
+                    return;
+                chunk = state.handshakeBuf; // 剩余 = 首个密文分片
+                state.handshakeBuf = Buffer.alloc(0);
+            }
+            const dec = state.decryptor.decrypt(chunk, Buffer.alloc(0));
+            for (const f of state.innerParser.push(dec))
+                state.inner.handleFrame(f);
         }
         catch {
-            client.send(encodeFrame(FRAME_TYPE.ERROR, frame.streamId, jsonPayload({ code: "BAD_OPEN", message: "malformed open" })));
-            return;
+            // 解密失败（篡改/错序）→ 结束该 raw 流
+            rawStreams.delete(streamId);
+            sendTunnelFrame(encodeFrame(FRAME_TYPE.CLOSE, streamId, jsonPayload({ code: 1, message: "e2ee decrypt failed" })));
         }
-        if (kind === "ws") {
-            openWsStream(frame, client, path, headers);
-            return;
-        }
-        if (kind !== "http") {
-            client.send(encodeFrame(FRAME_TYPE.ERROR, frame.streamId, jsonPayload({ code: "BAD_OPEN", message: "unknown kind" })));
-            return;
-        }
-        const streamId = frame.streamId;
-        // http 转发：本地 dsh（loopback http）
-        const up = httpRequest({
-            host: target.host,
-            port: target.port,
-            path,
-            method,
-            headers: rewriteHeadersForDsh(headers, target),
-        }, (upRes) => {
-            client.send(encodeFrame(FRAME_TYPE.OPEN, streamId, jsonPayload({
-                kind: "http",
-                status: upRes.statusCode ?? 502,
-                reason: upRes.statusMessage,
-                headers: normalizeRespHeaders(upRes.headers),
-            })));
-            upRes.on("data", (chunk) => {
-                if (client.readyState === client.OPEN) {
-                    client.send(encodeFrame(FRAME_TYPE.DATA, streamId, chunk));
+    }
+    /** 隧道级帧分发：PING/PONG + OPEN（http/ws/raw）+ DATA/CLOSE/ERROR（plain 或 raw 路由）。 */
+    function handleFrame(frame) {
+        switch (frame.type) {
+            case FRAME_TYPE.PING: {
+                sendTunnelFrame(encodeFrame(FRAME_TYPE.PONG, frame.streamId, frame.payload));
+                return;
+            }
+            case FRAME_TYPE.PONG:
+                return;
+            case FRAME_TYPE.OPEN: {
+                let kind;
+                try {
+                    const p = parseJsonPayload(frame);
+                    kind = typeof p.kind === "string" ? p.kind : undefined;
                 }
-            });
-            upRes.on("end", () => {
-                if (client.readyState === client.OPEN) {
-                    client.send(encodeFrame(FRAME_TYPE.CLOSE, streamId, jsonPayload({ code: 0 })));
+                catch {
+                    /* 交给 plain dispatcher 报 BAD_OPEN */
                 }
-                httpStreams.delete(streamId);
-            });
-            upRes.on("error", () => {
-                if (client.readyState === client.OPEN) {
-                    client.send(encodeFrame(FRAME_TYPE.CLOSE, streamId, jsonPayload({ code: 502, message: "upstream error" })));
+                if (kind === "raw") {
+                    startRawStream(frame.streamId);
+                    return;
                 }
-                httpStreams.delete(streamId);
-            });
-        });
-        up.on("error", () => {
-            if (client.readyState === client.OPEN) {
-                client.send(encodeFrame(FRAME_TYPE.ERROR, streamId, jsonPayload({ code: "UPSTREAM_UNREACHABLE", message: "dsh not reachable" })));
+                plainDispatcher.handleFrame(frame);
+                return;
             }
-            httpStreams.delete(streamId);
-        });
-        httpStreams.set(streamId, { up });
-    }
-    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 queue = [];
-        wsStreams.set(streamId, { upstream, queue });
-        upstream.on("open", () => {
-            for (const q of queue)
-                upstream.send(q, { binary: false });
-            queue.length = 0;
-        });
-        upstream.on("message", (data, isBinary) => {
-            const buf = Array.isArray(data)
-                ? Buffer.concat(data)
-                : Buffer.isBuffer(data)
-                    ? data
-                    : Buffer.from(data);
-            if (client.readyState === client.OPEN) {
-                client.send(encodeFrame(FRAME_TYPE.DATA, streamId, buf));
+            case FRAME_TYPE.DATA: {
+                const raw = rawStreams.get(frame.streamId);
+                if (raw !== undefined) {
+                    handleRawData(frame.streamId, raw, frame.payload);
+                    return;
+                }
+                plainDispatcher.handleFrame(frame);
+                return;
             }
-        });
-        const cleanup = () => {
-            wsStreams.delete(streamId);
-            if (client.readyState === client.OPEN) {
-                client.send(encodeFrame(FRAME_TYPE.CLOSE, streamId, jsonPayload({ code: 0 })));
+            case FRAME_TYPE.CLOSE:
+            case FRAME_TYPE.ERROR: {
+                if (rawStreams.has(frame.streamId)) {
+                    rawStreams.delete(frame.streamId);
+                    return;
+                }
+                plainDispatcher.handleFrame(frame);
+                return;
             }
-        };
-        upstream.on("close", cleanup);
-        upstream.on("error", cleanup);
+            default:
+                return;
+        }
+    }
+    /** 清空本地 http/ws/raw 流 + heartbeat（断线/停止时）。 */
+    function cleanupStreams() {
+        if (heartbeat !== undefined) {
+            clearInterval(heartbeat);
+            heartbeat = undefined;
+        }
+        plainDispatcher.cleanup();
+        for (const raw of rawStreams.values())
+            raw.inner.cleanup();
+        rawStreams.clear();
     }
     function connect() {
         if (shuttingDown)
             return;
-        const url = `${hubWsBase}/tunnel?token=${encodeURIComponent(token)}`;
-        const client = new WebSocket(url, { rejectUnauthorized: !insecure });
+        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;
@@ -326,7 +438,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(() => {
@@ -352,42 +465,25 @@ export async function join(opts) {
                 return;
             }
             for (const frame of frames)
-                handleFrame(frame, client);
+                handleFrame(frame);
         });
         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) {
-                // token 被拒（吊销/删除）= 永久失败，无法自动恢复（已移除配对码重配）
-                // → 删旧 session + fail-fast，让 systemd/脚本拿到非零退出码与明确报错。
+                // token 被拒（吊销/删除）= 永久失败，无法自动恢复
+                // → 删旧 session + 释放锁 + 停（fail-fast），不重连。
                 clearPersistedToken(opts.hubUrl);
-                console.error("rdsh join: host token rejected by hub (revoked or removed); re-run `rdsh host join <hub>` with a new join token.");
-                void shutdown("", 1);
+                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 +497,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rdsh-gateway",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "rdsh host-side component: LAN auth gateway + outbound tunnel endpoint (spawns dsh web)",
   "license": "MIT",
   "type": "module",
@@ -21,7 +21,7 @@
   },
   "dependencies": {
     "ws": "^8.18.0",
-    "rdsh-tunnel": "0.1.0"
+    "rdsh-tunnel": "0.2.0"
   },
   "devDependencies": {
     "@types/ws": "^8.5.0"