@duke-dsh-plugins/dsh-remote-control 0.0.0-stage → 1.1.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +88 -3
- package/client.js +747 -0
- package/cordis.patch.yml +12 -0
- package/icon.svg +20 -0
- package/index.js +731 -0
- package/lib/config.mjs +270 -0
- package/lib/host-bridge.mjs +2848 -0
- package/lib/images.mjs +458 -0
- package/lib/pairing.mjs +266 -0
- package/lib/protocol.mjs +390 -0
- package/lib/push.mjs +229 -0
- package/lib/qr.mjs +439 -0
- package/lib/relay-client.mjs +741 -0
- package/lib/relay-supervisor.mjs +798 -0
- package/locale/en.json +6 -0
- package/locale/zh.json +6 -0
- package/package.json +75 -6
- package/typert.host.js +243 -0
- package/vendor/relay/server.js +777 -0
package/lib/config.mjs
ADDED
|
@@ -0,0 +1,270 @@
|
|
|
1
|
+
// lib/config.mjs — 插件自有 config.json 的读写与默认值(契约 §3.1 / §6)。
|
|
2
|
+
//
|
|
3
|
+
// 存放位置:<DSH_HOME || ~/.dsh>/remote-control/config.json
|
|
4
|
+
// (与 dsh-agent-approval 同一范式:放在 DSH_HOME 下,不在 profile 的
|
|
5
|
+
// node_modules 里,重装/升级插件不丢配对信息。)
|
|
6
|
+
//
|
|
7
|
+
// 首次加载时若无 channel/secret 则随机生成并落盘(契约 §3.1):
|
|
8
|
+
// - channel:16 位 base32(字母表 A-Z2-7,满足中继 ^[A-Z2-7]{16,64}$)
|
|
9
|
+
// - secret :base64url 编码的 24 字节随机(32 字符,≥32 字符要求)
|
|
10
|
+
import { randomBytes } from "node:crypto";
|
|
11
|
+
import { mkdirSync, readFileSync, writeFileSync, renameSync } from "node:fs";
|
|
12
|
+
import { homedir } from "node:os";
|
|
13
|
+
import { dirname, join } from "node:path";
|
|
14
|
+
|
|
15
|
+
/** 中继 channel 合法字母表(RFC 4648 base32,满足中继的 ^[A-Z2-7]{16,64}$)。 */
|
|
16
|
+
const CHANNEL_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
|
|
17
|
+
const CHANNEL_LEN = 16;
|
|
18
|
+
const SECRET_BYTES = 24; // base64url 后 32 字符
|
|
19
|
+
|
|
20
|
+
/** 审批/提问拦截的默认与钳制边界(毫秒)。 */
|
|
21
|
+
export const DEFAULT_APPROVAL_TIMEOUT_MS = 120_000;
|
|
22
|
+
export const MIN_APPROVAL_TIMEOUT_MS = 10_000;
|
|
23
|
+
export const MAX_APPROVAL_TIMEOUT_MS = 600_000;
|
|
24
|
+
|
|
25
|
+
/** assistant.delta 按会话合并节流:每秒最多 8 条(契约 §5.2)。 */
|
|
26
|
+
export const ASSISTANT_THROTTLE_PER_SEC = 8;
|
|
27
|
+
|
|
28
|
+
/**
|
|
29
|
+
* v1.1.3 会话纪元的出厂默认值(契约 §3.4.1)。
|
|
30
|
+
* self —— 本端自己的纪元号(每开一条新连接 +1,跨进程重启单调递增)
|
|
31
|
+
* peer —— 已接受的对端最高纪元(回退检测的锚点)
|
|
32
|
+
* peerSid —— 已钉扎的对端连接实例 id(8 位十六进制)
|
|
33
|
+
*/
|
|
34
|
+
export function defaultEpoch() {
|
|
35
|
+
return { self: 0, peer: 0, peerSid: "" };
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
/**
|
|
39
|
+
* 规范化 epoch 字段:老配置没有该字段 → 补默认值;坏值 → 回落默认值。
|
|
40
|
+
* @param {unknown} raw
|
|
41
|
+
* @returns {{self:number, peer:number, peerSid:string}}
|
|
42
|
+
*/
|
|
43
|
+
export function normalizeEpoch(raw) {
|
|
44
|
+
const out = defaultEpoch();
|
|
45
|
+
if (raw !== null && typeof raw === "object") {
|
|
46
|
+
const r = /** @type {Record<string, unknown>} */ (raw);
|
|
47
|
+
if (Number.isInteger(r.self) && /** @type {number} */ (r.self) >= 0) out.self = /** @type {number} */ (r.self);
|
|
48
|
+
if (Number.isInteger(r.peer) && /** @type {number} */ (r.peer) >= 0) out.peer = /** @type {number} */ (r.peer);
|
|
49
|
+
if (typeof r.peerSid === "string" && /^[0-9a-f]{8}$/i.test(r.peerSid)) out.peerSid = r.peerSid;
|
|
50
|
+
}
|
|
51
|
+
return out;
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
export function dataDir() {
|
|
55
|
+
return join(process.env.DSH_HOME || join(homedir(), ".dsh"), "remote-control");
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
export function configFile() {
|
|
59
|
+
return join(dataDir(), "config.json");
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
/** 生成 16 位 base32 channel。 */
|
|
63
|
+
export function generateChannel() {
|
|
64
|
+
const buf = randomBytes(CHANNEL_LEN);
|
|
65
|
+
let out = "";
|
|
66
|
+
for (let i = 0; i < CHANNEL_LEN; i++) out += CHANNEL_ALPHABET[buf[i] % CHANNEL_ALPHABET.length];
|
|
67
|
+
return out;
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
/** 生成 base64url secret(24 字节 → 32 字符)。 */
|
|
71
|
+
export function generateSecret() {
|
|
72
|
+
return randomBytes(SECRET_BYTES).toString("base64url");
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
/** 出厂默认配置(契约 §6 配置项 + §5.5 开关)。 */
|
|
76
|
+
export function defaultConfig() {
|
|
77
|
+
return {
|
|
78
|
+
/** 总开关:false 时完全不连接中继、不拦截任何请求。 */
|
|
79
|
+
enabled: true,
|
|
80
|
+
/** 中继地址,如 wss://relay.example.com/ws;空串 = 未配置,插件空转。 */
|
|
81
|
+
relayUrl: "",
|
|
82
|
+
/** v1.1.1:是否由插件托管本机中继进程(随插件启动/停止)。false = 保持旧行为(外部自己起)。 */
|
|
83
|
+
autoStartRelay: true,
|
|
84
|
+
/** 中继自身鉴权 token(可选,部署方配置 RELAY_TOKEN 时填写)。 */
|
|
85
|
+
relayToken: "",
|
|
86
|
+
/**
|
|
87
|
+
* v1.1.3:中继 TLS(契约 §3.4.2)——托管的本机中继起 **wss://** 时的
|
|
88
|
+
* 证书链 / 私钥**文件路径**。两个都填才启用;只填一个 → 中继启动即失败
|
|
89
|
+
* (绝不静默降级成明文)。留空 = 明文 ws://(默认,局域网部署够用)。
|
|
90
|
+
*/
|
|
91
|
+
relayTlsCert: "",
|
|
92
|
+
relayTlsKey: "",
|
|
93
|
+
/** 配对 channel / secret(首次启动生成;手机端配对页输入同样值)。 */
|
|
94
|
+
channel: "",
|
|
95
|
+
secret: "",
|
|
96
|
+
/** 配对是否隐藏(设置页「隐藏配对」):true 时界面不展示二维码。 */
|
|
97
|
+
hidden: false,
|
|
98
|
+
/**
|
|
99
|
+
* v1.1.3 会话纪元(契约 §3.4.1):抗重放的持久化锚点。
|
|
100
|
+
* 自纪元每开一条新连接 +1(**先落盘再使用**);对端纪元/钉扎 sid 用于回退检测。
|
|
101
|
+
*/
|
|
102
|
+
epoch: defaultEpoch(),
|
|
103
|
+
/** approval.request / question.request 拦截开关(契约 §5.5)。 */
|
|
104
|
+
interceptApprovals: true,
|
|
105
|
+
interceptQuestions: true,
|
|
106
|
+
/** 手机应答等待超时(毫秒),超时 next() 放行给桌面答案器。 */
|
|
107
|
+
approvalTimeoutMs: DEFAULT_APPROVAL_TIMEOUT_MS,
|
|
108
|
+
/** Push Kit 旁路(契约 §6);未配置 = enabled false,优雅降级。 */
|
|
109
|
+
push: {
|
|
110
|
+
enabled: false,
|
|
111
|
+
appId: "",
|
|
112
|
+
clientId: "",
|
|
113
|
+
clientSecret: "",
|
|
114
|
+
/** 通知渠道 id(HarmonyOS 通知渠道)。 */
|
|
115
|
+
channelId: "",
|
|
116
|
+
/** 可选推送 topic。 */
|
|
117
|
+
topic: "",
|
|
118
|
+
/** turn.end 是否推送(默认推送完成通知)。 */
|
|
119
|
+
notifyTurnEnd: true,
|
|
120
|
+
},
|
|
121
|
+
};
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
/** 深合并(只合并已知的对象字段,未知字段保留默认行为)。 */
|
|
125
|
+
function mergeKnown(base, over) {
|
|
126
|
+
const out = { ...base };
|
|
127
|
+
for (const k of Object.keys(base)) {
|
|
128
|
+
if (over === null || typeof over !== "object" || !(k in over)) continue;
|
|
129
|
+
if (base[k] !== null && typeof base[k] === "object" && !Array.isArray(base[k])) {
|
|
130
|
+
out[k] = mergeKnown(base[k], over[k]);
|
|
131
|
+
} else if (over[k] !== undefined) {
|
|
132
|
+
out[k] = over[k];
|
|
133
|
+
}
|
|
134
|
+
}
|
|
135
|
+
return out;
|
|
136
|
+
}
|
|
137
|
+
|
|
138
|
+
/** 超时钳制到 [MIN, MAX]。 */
|
|
139
|
+
export function clampApprovalTimeout(ms) {
|
|
140
|
+
const n = Number(ms);
|
|
141
|
+
if (!Number.isFinite(n)) return DEFAULT_APPROVAL_TIMEOUT_MS;
|
|
142
|
+
return Math.min(MAX_APPROVAL_TIMEOUT_MS, Math.max(MIN_APPROVAL_TIMEOUT_MS, Math.floor(n)));
|
|
143
|
+
}
|
|
144
|
+
|
|
145
|
+
/**
|
|
146
|
+
* 加载配置;channel/secret 缺失时生成并持久化(首次启动生成,契约 §3.1)。
|
|
147
|
+
* 文件损坏不抛出:退回默认 + 重新生成身份(损坏的旧文件被覆盖前先备份)。
|
|
148
|
+
* @returns {{config: any, generated: boolean, repaired: boolean, path: string}}
|
|
149
|
+
*/
|
|
150
|
+
export function loadConfig() {
|
|
151
|
+
const path = configFile();
|
|
152
|
+
let raw = null;
|
|
153
|
+
let existed = false;
|
|
154
|
+
try {
|
|
155
|
+
raw = JSON.parse(readFileSync(path, "utf8"));
|
|
156
|
+
existed = true;
|
|
157
|
+
} catch (e) {
|
|
158
|
+
if (e && e.code !== "ENOENT") {
|
|
159
|
+
// 文件存在但读坏/解析坏 → 备份后重置
|
|
160
|
+
try {
|
|
161
|
+
renameSync(path, path + ".corrupt-" + Date.now());
|
|
162
|
+
} catch {
|
|
163
|
+
/* 备份失败也不阻塞 */
|
|
164
|
+
}
|
|
165
|
+
}
|
|
166
|
+
}
|
|
167
|
+
let config = mergeKnown(defaultConfig(), raw && typeof raw === "object" ? raw : {});
|
|
168
|
+
config.approvalTimeoutMs = clampApprovalTimeout(config.approvalTimeoutMs);
|
|
169
|
+
// v1.1.3:老配置没有 epoch 字段 → 补默认值(迁移,§3.4.1)。
|
|
170
|
+
config.epoch = normalizeEpoch(config.epoch);
|
|
171
|
+
let generated = false;
|
|
172
|
+
let repaired = false;
|
|
173
|
+
if (typeof config.channel !== "string" || !/^[A-Z2-7]{16,64}$/.test(config.channel)) {
|
|
174
|
+
config.channel = generateChannel();
|
|
175
|
+
generated = true;
|
|
176
|
+
repaired = existed;
|
|
177
|
+
}
|
|
178
|
+
if (typeof config.secret !== "string" || config.secret.length < 32) {
|
|
179
|
+
config.secret = generateSecret();
|
|
180
|
+
generated = true;
|
|
181
|
+
repaired = existed;
|
|
182
|
+
}
|
|
183
|
+
if (generated) saveConfig(config);
|
|
184
|
+
return { config, generated, repaired, path };
|
|
185
|
+
}
|
|
186
|
+
|
|
187
|
+
/**
|
|
188
|
+
* 原子写回配置(tmp + rename,避免半写文件)。
|
|
189
|
+
* 任何失败抛给调用方决定;上层应吞错并只记日志——配置写失败绝不阻断运行。
|
|
190
|
+
*
|
|
191
|
+
* **纪元只由专用写入器维护**(bumpSelfEpoch / savePeerEpoch:读-改-写、只动 epoch 字段)。
|
|
192
|
+
* 这里的快照可能陈旧(例如设置页改了中继地址后回写整份配置)→ 一律沿用盘上最新纪元,
|
|
193
|
+
* 避免自增纪元被回退覆盖(纪元复用 = 重放窗口)。
|
|
194
|
+
*/
|
|
195
|
+
export function saveConfig(config) {
|
|
196
|
+
const path = configFile();
|
|
197
|
+
mkdirSync(dirname(path), { recursive: true });
|
|
198
|
+
const out = { ...config };
|
|
199
|
+
out.epoch = readEpoch();
|
|
200
|
+
const tmp = path + ".tmp";
|
|
201
|
+
writeFileSync(tmp, JSON.stringify(out, null, 2), "utf8");
|
|
202
|
+
renameSync(tmp, path);
|
|
203
|
+
return path;
|
|
204
|
+
}
|
|
205
|
+
|
|
206
|
+
/**
|
|
207
|
+
* 读盘上的纪元状态(契约 §3.4.1)。文件缺失/读坏 → 出厂默认值。
|
|
208
|
+
* @returns {{self:number, peer:number, peerSid:string}}
|
|
209
|
+
*/
|
|
210
|
+
export function readEpoch() {
|
|
211
|
+
try {
|
|
212
|
+
const raw = JSON.parse(readFileSync(configFile(), "utf8"));
|
|
213
|
+
return normalizeEpoch(raw && raw.epoch);
|
|
214
|
+
} catch {
|
|
215
|
+
return defaultEpoch();
|
|
216
|
+
}
|
|
217
|
+
}
|
|
218
|
+
|
|
219
|
+
/**
|
|
220
|
+
* 读盘纪元(严格版):文件读坏/缺失时**抛错**——
|
|
221
|
+
* 纪元读不出来就不能安全地自增(宁可不开链路,也不复用纪元)。
|
|
222
|
+
* @returns {{self:number, peer:number, peerSid:string}}
|
|
223
|
+
*/
|
|
224
|
+
function readEpochStrict() {
|
|
225
|
+
const raw = JSON.parse(readFileSync(configFile(), "utf8"));
|
|
226
|
+
if (raw === null || typeof raw !== "object") throw new Error("config.json is not an object");
|
|
227
|
+
return normalizeEpoch(raw.epoch);
|
|
228
|
+
}
|
|
229
|
+
|
|
230
|
+
/**
|
|
231
|
+
* 只改 epoch 字段的原子写(读-改-写;**不动**其它配置字段)。
|
|
232
|
+
* 文件读坏时抛错——绝不覆盖可能仍带着配对身份的文件。
|
|
233
|
+
* @param {{self:number, peer:number, peerSid:string}} epoch
|
|
234
|
+
*/
|
|
235
|
+
function writeEpochToDisk(epoch) {
|
|
236
|
+
const path = configFile();
|
|
237
|
+
const raw = JSON.parse(readFileSync(path, "utf8"));
|
|
238
|
+
if (raw === null || typeof raw !== "object") throw new Error("config.json is not an object");
|
|
239
|
+
raw.epoch = epoch;
|
|
240
|
+
mkdirSync(dirname(path), { recursive: true });
|
|
241
|
+
const tmp = path + ".tmp";
|
|
242
|
+
writeFileSync(tmp, JSON.stringify(raw, null, 2), "utf8");
|
|
243
|
+
renameSync(tmp, path);
|
|
244
|
+
return path;
|
|
245
|
+
}
|
|
246
|
+
|
|
247
|
+
/**
|
|
248
|
+
* 自纪元 +1 并**先落盘再返回**(契约 §3.4.1:崩溃也不能复用纪元)。
|
|
249
|
+
* 落盘失败抛错——调用方必须拒绝开链路(带病上线 = 重放窗口)。
|
|
250
|
+
* @returns {number} 新的自纪元号
|
|
251
|
+
*/
|
|
252
|
+
export function bumpSelfEpoch() {
|
|
253
|
+
const epoch = readEpochStrict();
|
|
254
|
+
epoch.self += 1;
|
|
255
|
+
writeEpochToDisk(epoch);
|
|
256
|
+
return epoch.self;
|
|
257
|
+
}
|
|
258
|
+
|
|
259
|
+
/**
|
|
260
|
+
* 持久化「已接受的对端纪元 + 钉扎的 sid」(回退检测的锚点,跨重启有效)。
|
|
261
|
+
* @param {number} peer 对端纪元号
|
|
262
|
+
* @param {string} peerSid 对端连接实例 id(8 位十六进制)
|
|
263
|
+
*/
|
|
264
|
+
export function savePeerEpoch(peer, peerSid) {
|
|
265
|
+
const epoch = readEpochStrict();
|
|
266
|
+
epoch.peer = peer;
|
|
267
|
+
epoch.peerSid = peerSid;
|
|
268
|
+
writeEpochToDisk(epoch);
|
|
269
|
+
return epoch;
|
|
270
|
+
}
|