dsh-mobile-ios 0.2.8 → 0.2.10

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.
@@ -22,7 +22,8 @@ import { execFile as nodeExecFile } from 'node:child_process';
22
22
  import { promisify } from 'node:util';
23
23
  import { fail } from './protocol.mjs';
24
24
  import { deriveSubdomain, isValidLabel } from './dns-label.mjs';
25
- import { dnsWarningFor, evaluateDnsAnswer, probeDns } from './dns-probe.mjs';
25
+ import { dnsWarningFor, evaluateDnsAnswer, probeDns, resolveNs } from './dns-probe.mjs';
26
+ import { cnameBelongsTo } from './zone-health.mjs';
26
27
 
27
28
  const execFileAsync = promisify(nodeExecFile);
28
29
  const CLI_TIMEOUT_MS = 45_000;
@@ -66,6 +67,26 @@ export function renderConfig({ tunnelId, credentialsFile, hostname, port }) {
66
67
  ].join('\n');
67
68
  }
68
69
 
70
+ /**
71
+ * zone 诊断结果的**展示副本**:只留结论与 NS 名字。
72
+ *
73
+ * zoneId / accountId 这类内部标识一律不落状态文件、不进面板——
74
+ * 面板只需要知道「归谁、对不对」,不需要也不该拿到账号坐标。
75
+ */
76
+ export function sanitizeZone(zone) {
77
+ if (!zone || typeof zone !== 'object') return null;
78
+ const list = (v) => (Array.isArray(v) ? v.map((x) => String(x).toLowerCase()).filter(Boolean).slice(0, 4) : []);
79
+ return {
80
+ code: zone.code || 'unknown',
81
+ status: zone.status || null,
82
+ expectedNs: list(zone.expectedNs),
83
+ publicNs: list(zone.publicNs),
84
+ zoneName: zone.zoneName || null,
85
+ accountName: zone.accountName || null,
86
+ checkedAt: new Date().toISOString(),
87
+ };
88
+ }
89
+
69
90
  export class LocalProvisioner {
70
91
  constructor({
71
92
  baseDomain = 'matrixboard.cn',
@@ -79,6 +100,11 @@ export class LocalProvisioner {
79
100
  run = null,
80
101
  // 可注入:测试里不该真发 DNS 查询(会等 NXDOMAIN 重试,还依赖外网)
81
102
  probe = null,
103
+ // 可注入:解析失败时进一步问「这个域名现在归哪个 Cloudflare 账号」。
104
+ // 不注入就不诊断(测试/离线场景保持零网络依赖);生产由 createProvisioner 注入。
105
+ zoneDiagnose = null,
106
+ // 可注入:开通前查这条 hostname 现在指向哪条隧道,避免多机互相覆盖。
107
+ ownerLookup = null,
82
108
  } = {}) {
83
109
  this.baseDomain = String(baseDomain).replace(/^\./, '').toLowerCase();
84
110
  this.prefix = prefix;
@@ -92,6 +118,9 @@ export class LocalProvisioner {
92
118
  // 可注入,测试里不必真起 cloudflared
93
119
  this.run = run || this.#exec;
94
120
  this.probe = probe || probeDns;
121
+ this.zoneDiagnose = zoneDiagnose;
122
+ this.ownerLookup = ownerLookup;
123
+ this._zone = null; // 最近一次 zone 诊断结论(不含凭据)
95
124
  }
96
125
 
97
126
  get kind() {
@@ -117,6 +146,43 @@ export class LocalProvisioner {
117
146
  return `在这台电脑的终端执行:${this.executable} tunnel login(浏览器里选 matrixboard.cn 授权)`;
118
147
  }
119
148
 
149
+ /** 公网当前 NS(查询失败就当没有:少一句提示不该让整条诊断崩掉)。 */
150
+ async #publicNs() {
151
+ try {
152
+ return await resolveNs(this.baseDomain);
153
+ } catch {
154
+ return [];
155
+ }
156
+ }
157
+
158
+ /**
159
+ * 解析自检 + (失败时)zone 归因。
160
+ *
161
+ * 只把「解析不到」当作需要归因的信号:解析成功时多问一次 Cloudflare 只是浪费
162
+ * 一次往返,而失败时那句笼统的「pending」正是把人带偏的根源——域名可能已经被
163
+ * 另一个 Cloudflare 账号接管(zone moved),改 NS、重装、重启都不可能修好。
164
+ */
165
+ async #evaluate(hostname, tunnelId) {
166
+ const verdict = evaluateDnsAnswer(await this.probe(hostname), tunnelId);
167
+ if (verdict.ok || typeof this.zoneDiagnose !== 'function') {
168
+ this._zone = null; // 通了就别留着上一次的故障结论
169
+ return { verdict, zone: null };
170
+ }
171
+ let zone = null;
172
+ try {
173
+ zone = sanitizeZone(await this.zoneDiagnose({
174
+ homeDir: this.homeDir,
175
+ baseDomain: this.baseDomain,
176
+ publicNs: await this.#publicNs(),
177
+ dnsOk: false,
178
+ }));
179
+ } catch {
180
+ zone = null; // 「不知道」比「猜一个」诚实
181
+ }
182
+ this._zone = zone;
183
+ return { verdict, zone };
184
+ }
185
+
120
186
  status() {
121
187
  const s = this.state;
122
188
  if (!s) return { kind: 'local', provisioned: false, hostname: null, url: null, tunnelId: null };
@@ -129,12 +195,49 @@ export class LocalProvisioner {
129
195
  port: s.port ?? null,
130
196
  // null = 还没验过(老状态文件);false = 验过但公网没有——面板必须提示,别让人扫码扫到空气
131
197
  dnsOk: s.dnsOk ?? null,
198
+ dnsCheckedAt: s.dnsCheckedAt ?? null,
199
+ // 失败原因归到 zone 层(moved / pending / ns-mismatch / unresolved),
200
+ // 面板据此给出**不同**的修法,而不是一律「等 NS 生效」。
201
+ zone: s.zone ?? this._zone ?? null,
132
202
  warning: dnsWarningFor(s),
133
203
  createdAt: s.createdAt ?? null,
134
204
  updatedAt: s.updatedAt ?? null,
135
205
  };
136
206
  }
137
207
 
208
+ /**
209
+ * 面板「重新检测解析」:强制重探一次并写回状态,不做任何缓存短路。
210
+ *
211
+ * 为什么必须有这条路:dnsOk=false 是持久化结论,而面板在 false 时禁用了
212
+ * 「开启远程」按钮——原来唯一的重探入口就在 ensure() 里,按钮一点就点不到,
213
+ * 于是 NS 改好了也永远停在「解析异常」,只能删状态文件才恢复(自锁死)。
214
+ */
215
+ async recheckDns() {
216
+ const s = this.state;
217
+ if (!s?.hostname) return { provisioned: false, ok: false, tampered: false, warning: null, publicNs: [], zone: null };
218
+ const { verdict, zone } = await this.#evaluate(s.hostname, s.tunnelId);
219
+ const next = {
220
+ ...s,
221
+ dnsOk: verdict.ok,
222
+ dnsTampered: verdict.tampered,
223
+ dnsCheckedAt: new Date().toISOString(),
224
+ zone,
225
+ };
226
+ this._state = next;
227
+ writeState(this.stateFile, next);
228
+ return {
229
+ provisioned: true,
230
+ hostname: next.hostname,
231
+ ok: Boolean(verdict.ok),
232
+ tampered: Boolean(verdict.tampered),
233
+ expected: verdict.expected ?? null,
234
+ target: verdict.target ?? null,
235
+ warning: dnsWarningFor(next),
236
+ checkedAt: next.dnsCheckedAt,
237
+ zone,
238
+ };
239
+ }
240
+
138
241
  async #exec(args) {
139
242
  const { stdout, stderr } = await execFileAsync(this.executable, args, {
140
243
  timeout: CLI_TIMEOUT_MS,
@@ -169,8 +272,14 @@ export class LocalProvisioner {
169
272
  if (!force && cached?.hostname && cached.port === port) {
170
273
  // 与 BaseProvisioner 同策略:没确认过就现场验一次(含防篡改评估)
171
274
  if (cached.dnsOk !== true) {
172
- const verdict = evaluateDnsAnswer(await this.probe(cached.hostname), cached.tunnelId);
173
- const next = { ...cached, dnsOk: verdict.ok, dnsTampered: verdict.tampered, dnsCheckedAt: new Date().toISOString() };
275
+ const { verdict, zone } = await this.#evaluate(cached.hostname, cached.tunnelId);
276
+ const next = {
277
+ ...cached,
278
+ dnsOk: verdict.ok,
279
+ dnsTampered: verdict.tampered,
280
+ dnsCheckedAt: new Date().toISOString(),
281
+ zone,
282
+ };
174
283
  this._state = next;
175
284
  writeState(this.stateFile, next);
176
285
  return {
@@ -180,6 +289,7 @@ export class LocalProvisioner {
180
289
  created: false,
181
290
  changed: false,
182
291
  dnsOk: next.dnsOk,
292
+ zone,
183
293
  warning: dnsWarningFor(next),
184
294
  };
185
295
  }
@@ -246,6 +356,25 @@ export class LocalProvisioner {
246
356
  });
247
357
  }
248
358
 
359
+ // 多机共用同一个 Cloudflare 账号时,`--overwrite-dns` 会**静默**把别人的地址抢走:
360
+ // A 机本来能用,B 机一开通 A 机就断,两边面板却都显示「成功」。
361
+ // 有凭据就先看这条 hostname 现在归谁,抢址直接报错,绝不静默覆盖。
362
+ if (typeof this.ownerLookup === 'function') {
363
+ let owner = null;
364
+ try {
365
+ owner = await this.ownerLookup({ homeDir: this.homeDir, baseDomain: this.baseDomain, hostname });
366
+ } catch {
367
+ owner = null; // 查不到归属时退回旧行为,别让诊断把开通卡死
368
+ }
369
+ if (owner && !cnameBelongsTo(owner, tunnelId)) {
370
+ this.log(`tunnel 拒绝覆盖 ${hostname}:当前指向 ${owner},本机隧道 ${tunnelId}`);
371
+ throw fail(4021, `固定地址 ${hostname} 已被另一条隧道占用`, {
372
+ detail: `该地址当前指向 ${owner}。通常是另一台电脑用了同一份安装标识(或状态文件被复制)。`
373
+ + '本机已停止覆盖它:请在那台设备上重新开通以换一个地址,或先删掉这条 DNS 记录再重试。',
374
+ });
375
+ }
376
+ }
377
+
249
378
  // --overwrite-dns:重复开通时把记录改到当前 tunnel,而不是报「已存在」
250
379
  try {
251
380
  await this.run(['tunnel', 'route', 'dns', '--overwrite-dns', label, hostname]);
@@ -260,10 +389,10 @@ export class LocalProvisioner {
260
389
  try { fs.chmodSync(this.configFile, 0o600); } catch { /* 已 0600 */ }
261
390
 
262
391
  const now = new Date().toISOString();
263
- // 开通即自检:DNS 写成功 ≠ 公网能解析(pending zone 就是这么骗人的);
392
+ // 开通即自检:DNS 写成功 ≠ 公网能解析(pending / moved zone 就是这么骗人的);
264
393
  // CNAME 被改指到别的隧道同样不放行(防劫持评估见 dns-probe.evaluateDnsAnswer)
265
- const verdict = evaluateDnsAnswer(await this.probe(hostname), tunnelId);
266
- const warning = dnsWarningFor({ dnsOk: verdict.ok, dnsTampered: verdict.tampered });
394
+ const { verdict, zone } = await this.#evaluate(hostname, tunnelId);
395
+ const warning = dnsWarningFor({ dnsOk: verdict.ok, dnsTampered: verdict.tampered, zone });
267
396
  if (verdict.tampered) {
268
397
  this.log(`tunnel 警告 固定地址解析被改指 ${hostname} → ${verdict.target}(期望 ${verdict.expected}),拒绝下发该地址`);
269
398
  } else if (verdict.ok) {
@@ -284,6 +413,7 @@ export class LocalProvisioner {
284
413
  dnsOk: verdict.ok,
285
414
  dnsTampered: verdict.tampered,
286
415
  dnsCheckedAt: now,
416
+ zone,
287
417
  createdAt: cached?.createdAt ?? now,
288
418
  updatedAt: now,
289
419
  };
@@ -297,6 +427,7 @@ export class LocalProvisioner {
297
427
  created,
298
428
  changed: Boolean(cached && cached.hostname !== hostname),
299
429
  dnsOk: verdict.ok,
430
+ zone,
300
431
  warning,
301
432
  };
302
433
  }
package/src/rest.mjs CHANGED
@@ -6,6 +6,8 @@ import { translateRecords } from './adapter/session-history.mjs';
6
6
  import { createRequire } from 'node:module';
7
7
  import { PLUGIN_VERSION } from './version.mjs';
8
8
  import { ensureCloudflared, resolveAsset } from './cloudflared-install.mjs';
9
+ import { selfUpdatePlugin } from './plugin-update.mjs';
10
+ import { resolveNs } from './dns-probe.mjs';
9
11
 
10
12
  // QR 编码(vendor:qrcode-generator 1.4.4,MIT,零依赖;见 lib/vendor/,
11
13
  // .cjs 后缀:包为 type:module,require 需显式 CommonJS)
@@ -98,6 +100,8 @@ const DESKTOP_CORS_PATHS = [
98
100
  /^\/mobile\/v1\/tunnel\/stop$/,
99
101
  /^\/mobile\/v1\/tunnel\/provision$/,
100
102
  /^\/mobile\/v1\/tunnel\/install-cloudflared$/,
103
+ /^\/mobile\/v1\/tunnel\/recheck-dns$/,
104
+ /^\/mobile\/v1\/plugin\/self-update$/,
101
105
  ];
102
106
 
103
107
  // 面板「插件版本」与更新检查的「当前版本」都取这里;必须与 npm 包版本同源。
@@ -220,9 +224,29 @@ export function createRestRouter({ core, pairing, host, tickets, config = {}, lo
220
224
  * · 进程 running 但没开通 → 只可能是 Quick Tunnel;
221
225
  * · 已开通但进程 stopped → 地址是固定的,但此刻连不上,二维码不能写它。
222
226
  */
227
+ // 「解析异常」曾经是死锁:dnsOk=false 被写进状态文件,面板据此禁用开启按钮,
228
+ // 而唯一的重探入口就在开启流程里——按钮点不到 → 永远不重探 → NS 改好了也不恢复。
229
+ // 这里补一层节流自愈:面板轮询 summary 时,若仍是 false 且距上次检查超过 60 秒,
230
+ // 后台重探一次(不阻塞响应)。用户改完 NS 最多等一分钟就会自己变好。
231
+ let dnsAutoRecheckAt = 0;
232
+ let dnsAutoRechecking = false;
233
+ const maybeAutoRecheckDns = (prov) => {
234
+ if (!prov || prov.dnsOk !== false) return;
235
+ if (typeof config.tunnelProvisioner?.recheckDns !== 'function') return;
236
+ const now = Date.now();
237
+ if (dnsAutoRechecking || now - dnsAutoRecheckAt < 60_000) return;
238
+ dnsAutoRecheckAt = now;
239
+ dnsAutoRechecking = true;
240
+ Promise.resolve()
241
+ .then(() => config.tunnelProvisioner.recheckDns())
242
+ .catch(() => { /* 探测失败保持原状态,不打扰用户 */ })
243
+ .finally(() => { dnsAutoRechecking = false; });
244
+ };
245
+
223
246
  const tunnelSnapshot = () => {
224
247
  const base = config.tunnel?.status?.() ?? { state: 'disabled', url: null, mode: 'disabled' };
225
248
  const prov = config.tunnelProvisioner?.status?.() ?? null;
249
+ maybeAutoRecheckDns(prov);
226
250
  return {
227
251
  ...base,
228
252
  mode: prov ? 'named' : (base.mode || 'quick'),
@@ -234,6 +258,10 @@ export function createRestRouter({ core, pairing, host, tickets, config = {}, lo
234
258
  // 域名在公网上解析得到吗。false 时地址虽在、扫码却连不上(zone pending / NS 没指过来),
235
259
  // 面板与二维码都要据此避开它,而不是让用户拿一个必然失败的地址去扫。
236
260
  dnsOk: prov?.dnsOk ?? null,
261
+ dnsCheckedAt: prov?.dnsCheckedAt ?? null,
262
+ // 解析失败的归因(moved / pending / ns-mismatch / unresolved):
263
+ // 面板据此给**不同**的修法,而不是一律「等 NS 生效」。
264
+ zone: prov?.zone ?? null,
237
265
  warning: prov?.warning ?? null,
238
266
  // 面板据此决定是否显示「自动安装 cloudflared」入口:仅在缺失且有官方构建时为 true。
239
267
  canAutoInstall: base.executable === 'missing' && !!resolveAsset({}),
@@ -515,6 +543,57 @@ export function createRestRouter({ core, pairing, host, tickets, config = {}, lo
515
543
  return send(ctx.res, 200, { ...result, status: tunnelSnapshot() }, DESKTOP_CORS);
516
544
  });
517
545
 
546
+ /**
547
+ * 重新检测固定域名的公网解析(面板「重新检测解析」按钮)。
548
+ *
549
+ * 存在的唯一理由:dnsOk=false 会持久化,而面板在 false 时曾禁用开启按钮——
550
+ * 用户把 NS 改对之后没有任何可点的入口让它再验一次。这条路把「自锁死」解开。
551
+ * 回环-only:探测会真发 DNS 查询,不该让外部触发。
552
+ */
553
+ route('POST', /^\/mobile\/v1\/tunnel\/recheck-dns$/, async (ctx) => {
554
+ loopbackOnly(ctx, '重新检测解析只允许在主机本机操作');
555
+ const prov = config.tunnelProvisioner;
556
+ if (!prov) throw fail(4021, '这台主机没有固定地址可检测', { method: 'tunnel.recheckDns' });
557
+ if (typeof prov.recheckDns !== 'function') throw fail(4021, '当前开通方式不支持重新检测', { method: 'tunnel.recheckDns' });
558
+ const started = Date.now();
559
+ const result = await prov.recheckDns();
560
+ log(`rest tunnel recheck-dns ok=${result.ok} tampered=${result.tampered} ${Date.now() - started}ms`);
561
+ // 把公网当前 NS 一并带回去:用户不需要理解 zone/pending,只要拿这串名字去注册商对照。
562
+ const baseDomain = prov.baseDomain
563
+ || String(result.hostname || '').split('.').slice(-2).join('.');
564
+ const publicNs = result.provisioned && baseDomain ? await resolveNs(baseDomain) : [];
565
+ return send(ctx.res, 200, {
566
+ ...result,
567
+ publicNs,
568
+ status: tunnelSnapshot(),
569
+ }, DESKTOP_CORS);
570
+ });
571
+
572
+ /**
573
+ * 插件自更新(不依赖宿主 pluginManager)。
574
+ *
575
+ * 为什么放在网关:dsh-app:// 页面里的复制/剪贴板能力不可靠,而「一键更新」缺了宿主
576
+ * API 就只剩复制包名一条路。这里由 Node 侧直接取 npm tarball、校验 shasum、
577
+ * 备份后覆盖安装目录,返回 restartRequired 让面板明确告知需要重启。
578
+ * 只允许装本插件自己(写死包名),不接受任意包/任意 URL。
579
+ */
580
+ route('POST', /^\/mobile\/v1\/plugin\/self-update$/, async (ctx) => {
581
+ loopbackOnly(ctx, '插件更新只允许在主机本机操作');
582
+ const body = await readJson(ctx.req);
583
+ const target = typeof body?.target === 'string' && /^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?$/.test(body.target)
584
+ ? body.target
585
+ : null;
586
+ let result;
587
+ try {
588
+ result = await selfUpdatePlugin({ target, log });
589
+ } catch (err) {
590
+ log(`rest plugin self-update 失败 ${err?.message || err}`);
591
+ throw fail(4500, err?.message || '插件更新失败', { code: 'SELF_UPDATE_FAILED' });
592
+ }
593
+ log(`rest plugin self-update ${result.from || '?'} → ${result.to} changed=${result.changed}`);
594
+ return send(ctx.res, 200, result, DESKTOP_CORS);
595
+ });
596
+
518
597
  // 诊断包(GW-9):一次拿到可直接粘贴给支持人员的东西。
519
598
  route('GET', /^\/mobile\/v1\/diag\/bundle$/, async (ctx) => {
520
599
  auth(ctx.req);
@@ -0,0 +1,251 @@
1
+ // zone-health.mjs — 「域名到底归谁、公网到底在服务哪一份 zone」
2
+ //
3
+ // 为什么需要这个模块:DNS 解析失败只是**症状**,原因是 zone 层面的事,而面板原来
4
+ // 一律解释成「zone 处于 pending」——这在真实世界里会把人带偏。
5
+ //
6
+ // Cloudflare 的 zone 有四种会让地址「开通成功但解析不到」的状态:
7
+ // · active 公网 NS 指向本账号、记录正常下发 —— 正常
8
+ // · pending 域名已加进本账号,但注册商 NS 还没指过来 —— 改 NS 即可
9
+ // · moved 域名已被**另一个 Cloudflare 账号**接管 —— 本账号写什么都无效,
10
+ // 公网 NS 是对方那一对(每个账号的 NS 对是固定的,所以能直接看出来)
11
+ // · 记录在某台机器上被 --overwrite-dns 改指到另一条隧道 —— 见 findDnsOwner()
12
+ //
13
+ // 本机 `cloudflared tunnel login` 生成的 cert.pem 里就带着 zoneID / accountID /
14
+ // 一份 zone 范围的 apiToken,因此**不需要额外凭据**就能只读地问清 zone 状态。
15
+ // 这里只做 GET,绝不写;token 只在函数内部流转,不进状态文件、不进日志。
16
+ //
17
+ // 另一条硬约束:所有失败都必须**降级为 null**(返回「不知道」),不能让一个
18
+ // 查不到状态的网络问题把本来能用的固定地址判死。
19
+
20
+ import crypto from 'node:crypto';
21
+ import fs from 'node:fs';
22
+ import os from 'node:os';
23
+ import path from 'node:path';
24
+
25
+ export const CF_API_BASE = 'https://api.cloudflare.com/client/v4';
26
+
27
+ /** zone 状态码 → 面板可读的一句话(短,塞得进 300px 宽的面板)。 */
28
+ export const ZONE_STATUS_HINT = {
29
+ active: '域名在 Cloudflare 已生效',
30
+ pending: '域名在本账号尚未生效(zone pending),公网 NS 没指向本账号',
31
+ moved: '域名已被另一个 Cloudflare 账号接管(zone moved),本账号写入的记录不再下发',
32
+ initializing: '域名正在本账号初始化(zone initializing)',
33
+ };
34
+
35
+ /** 诊断码 → 短提示。code 比 status 更适合面板:它已经带上了「NS 对不对」的结论。 */
36
+ export const ZONE_CODE_HINT = {
37
+ moved: '域名已被另一个 Cloudflare 账号接管,公网 NS 指向对方,本机写入的记录不会生效',
38
+ pending: '域名在本账号还没生效(zone pending):公网 NS 还没指向本账号分配的那一对',
39
+ 'ns-mismatch': '域名在本账号显示已生效,但公网 NS 与本账号分配的不一致',
40
+ unresolved: '域名在 Cloudflare 已生效,但公网仍解析不到这台主机的地址',
41
+ };
42
+
43
+ /**
44
+ * 读 cert.pem 里的 zone 身份。结构是 PEM 包一层 base64(JSON)。
45
+ * @returns {{ zoneId: string|null, accountId: string|null, apiToken: string|null }|null}
46
+ */
47
+ export function readZoneCert({ homeDir = os.homedir() } = {}) {
48
+ const file = path.join(homeDir, '.cloudflared', 'cert.pem');
49
+ let pem;
50
+ try {
51
+ pem = fs.readFileSync(file, 'utf8');
52
+ } catch {
53
+ return null;
54
+ }
55
+ try {
56
+ const b64 = pem.replace(/-----[^-]+-----/g, '').replace(/\s+/g, '');
57
+ const parsed = JSON.parse(Buffer.from(b64, 'base64').toString('utf8'));
58
+ return {
59
+ zoneId: parsed.zoneID || parsed.zoneId || null,
60
+ accountId: parsed.accountID || parsed.accountId || null,
61
+ apiToken: parsed.apiToken || null,
62
+ };
63
+ } catch {
64
+ return null;
65
+ }
66
+ }
67
+
68
+ async function cfGet(apiBase, apiToken, pathname, fetchImpl) {
69
+ const res = await fetchImpl(`${apiBase}${pathname}`, {
70
+ headers: { Authorization: `Bearer ${apiToken}` },
71
+ });
72
+ const text = await res.text();
73
+ let payload = null;
74
+ try {
75
+ payload = text ? JSON.parse(text) : null;
76
+ } catch {
77
+ return null;
78
+ }
79
+ if (!payload || payload.success !== true) return null;
80
+ return payload.result;
81
+ }
82
+
83
+ /**
84
+ * 查 zone 现状:状态 + **这个账号要求**的 NS 对 + 账号名。
85
+ * 任一环节失败都返回 null(未知 ≠ 异常)。
86
+ */
87
+ export async function fetchZoneHealth({
88
+ zoneId = null,
89
+ baseDomain,
90
+ apiToken,
91
+ fetchImpl = globalThis.fetch,
92
+ apiBase = CF_API_BASE,
93
+ accountId = null,
94
+ } = {}) {
95
+ if (!apiToken || typeof fetchImpl !== 'function') return null;
96
+ let zone = null;
97
+ try {
98
+ if (zoneId) {
99
+ zone = await cfGet(apiBase, apiToken, `/zones/${zoneId}`, fetchImpl);
100
+ }
101
+ // cert 里的 zoneID 可能属于旧 zone(重新接入后会换),名字查一遍更稳
102
+ if (!zone && baseDomain) {
103
+ const list = await cfGet(apiBase, apiToken, `/zones?name=${encodeURIComponent(baseDomain)}`, fetchImpl);
104
+ zone = Array.isArray(list) ? list.find((z) => z && z.name === baseDomain) || null : null;
105
+ }
106
+ } catch {
107
+ return null;
108
+ }
109
+ if (!zone) return null;
110
+
111
+ let accountName = null;
112
+ const acc = accountId || zone.account?.id || null;
113
+ if (acc) {
114
+ try {
115
+ const a = await cfGet(apiBase, apiToken, `/accounts/${acc}`, fetchImpl);
116
+ accountName = a?.name || null;
117
+ } catch {
118
+ /* 只是少一句「账号是谁」,不影响结论 */
119
+ }
120
+ }
121
+ return {
122
+ zoneId: zone.id || null,
123
+ zoneName: zone.name || baseDomain || null,
124
+ status: zone.status || null,
125
+ nameServers: (zone.name_servers || []).map((n) => String(n).toLowerCase().replace(/\.$/, '')).sort(),
126
+ accountId: acc,
127
+ accountName,
128
+ modifiedAt: zone.modified_on || null,
129
+ };
130
+ }
131
+
132
+ const norm = (list) => (Array.isArray(list) ? list : [])
133
+ .map((n) => String(n).toLowerCase().replace(/\.$/, ''))
134
+ .filter(Boolean)
135
+ .sort();
136
+
137
+ /**
138
+ * 把 zone 身份 + 公网 NS 合成为一个诊断码。
139
+ *
140
+ * 判据刻意简单:`moved` 是 Cloudflare 已经明确告诉我们「这域名不归你了」,
141
+ * 优先采信;`active` 时用 NS 交集兜底(NS 刚改完的过渡期两边都可能答话)。
142
+ */
143
+ export function classifyZone({ zone = null, publicNs = [], dnsOk = false } = {}) {
144
+ const expectedNs = norm(zone?.nameServers);
145
+ const publicNsNorm = norm(publicNs);
146
+ const status = zone?.status || null;
147
+ const base = { status, expectedNs, publicNs: publicNsNorm, zoneName: zone?.zoneName || null, accountName: zone?.accountName || null };
148
+
149
+ if (!zone) return { code: 'unknown', ...base };
150
+ if (status === 'moved') return { code: 'moved', ...base };
151
+ if (status === 'pending' || status === 'initializing') return { code: 'pending', ...base };
152
+ if (status === 'active') {
153
+ const overlap = publicNsNorm.some((n) => expectedNs.includes(n));
154
+ if (publicNsNorm.length && expectedNs.length && !overlap) return { code: 'ns-mismatch', ...base };
155
+ return { code: dnsOk ? 'ok' : 'unresolved', ...base };
156
+ }
157
+ return { code: 'unknown', ...base };
158
+ }
159
+
160
+ /** 诊断码 → 面板短提示(null 表示不必打扰用户)。 */
161
+ export function zoneHint(code) {
162
+ return ZONE_CODE_HINT[code] || null;
163
+ }
164
+
165
+ /**
166
+ * 完整诊断:读证书 → 查 zone → 若给了公网 NS 就一并归类。
167
+ * 任何一步不可用都退回 `{ code: 'unknown' }`,绝不抛。
168
+ */
169
+ export async function diagnoseZone({
170
+ homeDir = os.homedir(),
171
+ baseDomain,
172
+ publicNs = [],
173
+ dnsOk = false,
174
+ zoneId = null,
175
+ apiToken = null,
176
+ accountId = null,
177
+ fetchImpl = globalThis.fetch,
178
+ apiBase = CF_API_BASE,
179
+ } = {}) {
180
+ const cert = apiToken ? null : readZoneCert({ homeDir });
181
+ const health = await fetchZoneHealth({
182
+ zoneId: zoneId || cert?.zoneId || null,
183
+ accountId: accountId || cert?.accountId || null,
184
+ baseDomain,
185
+ apiToken: apiToken || cert?.apiToken || null,
186
+ fetchImpl,
187
+ apiBase,
188
+ });
189
+ if (!health) return { code: 'unknown', status: null, expectedNs: [], publicNs: norm(publicNs), zoneName: null, accountName: null };
190
+ const verdict = classifyZone({ zone: health, publicNs, dnsOk });
191
+ return {
192
+ ...verdict,
193
+ zoneId: health.zoneId,
194
+ accountId: health.accountId,
195
+ modifiedAt: health.modifiedAt,
196
+ };
197
+ }
198
+
199
+ /**
200
+ * 这条 hostname 现在的 CNAME 指向哪条隧道?
201
+ *
202
+ * 用途:多台机器共用一个 Cloudflare 账号时,`cloudflared tunnel route dns
203
+ * --overwrite-dns` 会**静默**把别人的地址抢过来——A 机好好的,B 机一开通 A 机就断,
204
+ * 而且两边面板都显示「成功」。开通前先看一眼归属,能避免这种互相踩踏。
205
+ *
206
+ * @returns {string|null} 小写 CNAME 目标;无记录返回 null;查不到(无凭据/断网)也返回 null
207
+ */
208
+ export async function findDnsOwner({
209
+ homeDir = os.homedir(),
210
+ baseDomain,
211
+ hostname,
212
+ fetchImpl = globalThis.fetch,
213
+ apiBase = CF_API_BASE,
214
+ zoneId = null,
215
+ apiToken = null,
216
+ } = {}) {
217
+ const cert = apiToken ? null : readZoneCert({ homeDir });
218
+ const token = apiToken || cert?.apiToken || null;
219
+ if (!token || !hostname) return null;
220
+ try {
221
+ let zid = zoneId || null;
222
+ if (!zid && baseDomain) {
223
+ const list = await cfGet(apiBase, token, `/zones?name=${encodeURIComponent(baseDomain)}`, fetchImpl);
224
+ zid = Array.isArray(list) ? list.find((z) => z && z.name === baseDomain)?.id || null : null;
225
+ }
226
+ if (!zid) return null;
227
+ const records = await cfGet(
228
+ apiBase,
229
+ token,
230
+ `/zones/${zid}/dns_records?type=CNAME&name=${encodeURIComponent(hostname)}`,
231
+ fetchImpl,
232
+ );
233
+ const hit = Array.isArray(records) ? records[0] : null;
234
+ return hit?.content ? String(hit.content).toLowerCase().replace(/\.$/, '') : null;
235
+ } catch {
236
+ return null;
237
+ }
238
+ }
239
+
240
+ /** 这条 CNAME 目标是不是"本机隧道":只比较 UUID 前缀,容忍 cfdargotunnel.com 结尾差异。 */
241
+ export function cnameBelongsTo(content, tunnelId) {
242
+ if (!content || !tunnelId) return false;
243
+ return String(content).toLowerCase().startsWith(String(tunnelId).toLowerCase());
244
+ }
245
+
246
+ /** 稳定摘要,用于把「同一份 zone」与「另一份 zone」区分开(不写 ID,只做等值比较)。 */
247
+ export function zoneFingerprint(zone) {
248
+ const src = `${zone?.accountId || ''}|${zone?.zoneId || ''}|${zone?.zoneName || ''}`;
249
+ if (!src.replace(/\|/g, '')) return null;
250
+ return crypto.createHash('sha256').update(src).digest('hex').slice(0, 12);
251
+ }