@qzsy/dsh-bridge 0.0.0-stage → 2.18.0

package/lib/restart-helper.mjs

@@ -0,0 +1,133 @@
+// 无托管器场景下的 DSH 重启助手（由 BridgeService.restartDsh 派生为独立进程）。
+//
+// 为什么需要它：旧进程调用 process.exit(0) 后，端口不会立刻释放；若新进程马上启动，
+// 很容易撞上 EADDRINUSE 然后无声退出（stdio 被 ignore 时连报错都看不到），
+// 结果就是"点了重启，dsh 再也没起来"。本助手按顺序做三件事并把过程写进日志：
+//   1. 等旧进程真正退出；
+//   2. 等端口释放（能连上说明还被占着）；
+//   3. 才派生新的 dsh，并在最长 120s 内确认端口可连接；失败则记日志并以非 0 退出。
+//
+// 用法（由 lib/index.js 组装 payload）：node restart-helper.mjs '<json>'
+import { spawn } from 'node:child_process';
+import { appendFileSync, openSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { connect } from 'node:net';
+
+const payload = JSON.parse(process.argv[2] ?? '{}');
+const {
+  pid, port, argv, cwd, execPath, logFile, childLog,
+  // 超时可注入（单测用），生产用默认值
+  waitTimeoutMs = 30_000,
+  readyTimeoutMs = 120_000,
+} = payload;
+const startedAt = Date.now();
+
+function log(message) {
+  try { appendFileSync(logFile, `[${new Date().toISOString()}] [helper] ${message}\n`); } catch { /* 日志不可写时忽略 */ }
+}
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+function processAlive(targetPid) {
+  try {
+    process.kill(targetPid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** 端口上是否有人在监听（能建立连接即视为被占用） */
+async function portAccepts(portNumber) {
+  return await new Promise((resolve) => {
+    let settled = false;
+    const done = (value) => { if (!settled) { settled = true; resolve(value); } };
+    let socket;
+    try {
+      socket = connect({ host: '127.0.0.1', port: portNumber });
+    } catch {
+      done(false);
+      return;
+    }
+    socket.setTimeout(1200);
+    socket.once('connect', () => { done(true); socket.destroy(); });
+    socket.once('timeout', () => { done(false); socket.destroy(); });
+    socket.once('error', () => { done(false); socket.destroy(); });
+  });
+}
+
+async function waitUntil(check, timeoutMs, label) {
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    if (await check()) return true;
+    if (Date.now() >= deadline) {
+      log(`等待超时：${label}（${timeoutMs}ms）`);
+      return false;
+    }
+    await sleep(400);
+  }
+}
+
+async function main() {
+  log(`启动：oldPid=${pid} port=${port} cwd=${cwd}`);
+
+  if (!(await waitUntil(() => !processAlive(pid), waitTimeoutMs, `旧进程 ${pid} 退出`))) {
+    log('旧进程仍在运行，放弃本次重启（不做任何破坏性动作）');
+    process.exit(2);
+  }
+  if (!(await waitUntil(async () => !(await portAccepts(port)), waitTimeoutMs, `端口 ${port} 释放`))) {
+    log(`端口 ${port} 仍被占用，放弃本次重启`);
+    process.exit(3);
+  }
+
+  let stdio = 'ignore';
+  try {
+    mkdirSync(dirname(childLog), { recursive: true });
+    stdio = openSync(childLog, 'a');
+  } catch { /* 打不开就用 ignore */ }
+
+  // spawn 的失败是异步 'error' 事件（例如 execPath 不存在 → ENOENT），只 try/catch 抓不到；
+  // 不挂监听会变成未捕获异常，而且父进程给助手设的是 stdio:'ignore' → 失败细节全部丢失。
+  // 这里挂监听并把原因写进日志，且**确认 spawn 成功后才**记录"已派生"。
+  const spawned = await new Promise((resolve) => {
+    let settled = false;
+    const settle = (value) => { if (!settled) { settled = true; resolve(value); } };
+    let child;
+    try {
+      const childEnv = { ...process.env };
+      if (process.platform !== 'win32') {
+        const execDir = dirname(execPath);
+        const defaultPaths = [execDir, '/usr/local/bin', '/usr/bin', '/bin'].filter(Boolean);
+        const existingPath = childEnv.PATH || '';
+        const missingPaths = defaultPaths.filter((p) => !existingPath.split(':').includes(p));
+        if (missingPaths.length > 0) {
+          childEnv.PATH = existingPath ? `${existingPath}:${missingPaths.join(':')}` : missingPaths.join(':');
+        }
+      }
+      child = spawn(execPath, argv, { cwd, env: childEnv, detached: true, stdio: ['ignore', stdio, stdio] });
+    } catch (err) {
+      log(`派生新 dsh 失败（同步异常）：${err?.message ?? err}`);
+      settle(null);
+      return;
+    }
+    child.once('error', (err) => {
+      log(`派生新 dsh 失败：${err?.message ?? err}`);
+      settle(null);
+    });
+    child.once('spawn', () => {
+      log(`已派生新 dsh：pid=${child.pid ?? '(未知)'}（输出见 ${childLog}）`);
+      settle(child);
+    });
+  });
+
+  if (!spawned) process.exit(4);
+  spawned.unref();
+
+  const up = await waitUntil(() => portAccepts(port), readyTimeoutMs, `新 dsh 监听 ${port}`);
+  log(up
+    ? `✅ 新 dsh 已就绪，耗时 ${Math.round((Date.now() - startedAt) / 1000)}s`
+    : `❌ 新 dsh 未能在 ${Math.round(readyTimeoutMs / 1000)}s 内就绪，请查看 ${childLog}`);
+  process.exit(up ? 0 : 1);
+}
+
+void main();

package/lib/saas/device-auth.mjs

@@ -0,0 +1,366 @@
+// DSH Bridge - SaaS 设备认证（设备码注册 + 短期设备令牌刷新）
+//
+// 契约见 docs/architecture/saas-tunnel.md §4/§7（字段名不可擅自改名）：
+//   POST /api/saas/device/code             → { code, expiresAt, verificationUrl }
+//   GET  /api/saas/device/code/:code       → { status: pending|approved|consumed|expired }
+//   POST /api/saas/device/code/:code/claim → { deviceId, secret, tunnel:{publicId,name} }
+//   POST /api/saas/device/token            → { token, expiresAt, tunnel, gateway:{url,path} }
+//
+// 本模块只负责 HTTP 与状态判定，不做落盘：deviceSecret 由调用方写进 config.json
+// （lib/index.js 的 updateConfig → writeConfig 固定 mode=0600，与现有配置落盘方式一致）。
+// 网络层用全局 fetch（Node 18+/Bun 内置），不引入新依赖。
+
+const DEFAULT_TIMEOUT_MS = 15_000;
+const DEFAULT_CLAIM_POLL_MS = 2000;
+const DEFAULT_CLAIM_TIMEOUT_MS = 10 * 60 * 1000;
+const SECRET_MASK = '••••••••';
+
+/** 设备认证失败：code 与契约里的 error.code 对齐，便于上层区分终态/可重试。 */
+export class SaasAuthError extends Error {
+  /**
+   * @param {string} message
+   * @param {{code?: string, status?: number, retryable?: boolean, terminal?: boolean, cause?: unknown}} [options]
+   */
+  constructor(message, { code = 'saas_auth_error', status = 0, retryable = false, terminal = false, cause } = {}) {
+    super(message, cause === undefined ? undefined : { cause });
+    this.name = 'SaasAuthError';
+    this.code = code;
+    this.status = status;
+    this.retryable = retryable;
+    this.terminal = terminal;
+  }
+}
+
+/**
+ * 归一化 SaaS 控制面基址：只接受 http(s)/ws(s)，ws(s) 转 http(s) 以便调用 /api/saas/*。
+ * 丢弃 query/hash；容忍用户直接粘贴网关连接地址（自动剥掉 `/_gw/connect` 后缀）。
+ *
+ * @param {unknown} value
+ * @returns {string} 形如 `https://tunnel.example.com`（无尾斜杠）
+ * @throws {SaasAuthError} 空值/非法 URL/非法协议
+ */
+export function normalizeSaasBaseUrl(value) {
+  const raw = String(value ?? '').trim();
+  if (!raw) throw new SaasAuthError('SaaS 网关地址不能为空', { code: 'bad_request', terminal: true });
+  let url;
+  try {
+    url = new URL(raw);
+  } catch {
+    throw new SaasAuthError('SaaS 网关地址不是合法 URL（示例：https://tunnel.example.com）', { code: 'bad_request', terminal: true });
+  }
+  if (url.protocol === 'ws:') url.protocol = 'http:';
+  else if (url.protocol === 'wss:') url.protocol = 'https:';
+  else if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+    throw new SaasAuthError('SaaS 网关地址只支持 http/https（也接受 ws/wss）', { code: 'bad_request', terminal: true });
+  }
+  url.search = '';
+  url.hash = '';
+  let pathname = url.pathname;
+  if (pathname.endsWith('/_gw/connect')) pathname = pathname.slice(0, -'/_gw/connect'.length);
+  url.pathname = pathname || '/';
+  let base = url.toString();
+  while (base.endsWith('/')) base = base.slice(0, -1);
+  return base;
+}
+
+/**
+ * 归一化 token 接口返回的网关连接信息。
+ * @param {{url?: string, path?: string}|null|undefined} gateway
+ * @returns {{url: string, path: string}|null}
+ */
+export function normalizeSaasGateway(gateway) {
+  if (!gateway || typeof gateway !== 'object') return null;
+  const rawUrl = String(gateway.url ?? '').trim();
+  if (!rawUrl) return null;
+  let url;
+  try {
+    url = new URL(rawUrl);
+  } catch {
+    throw new SaasAuthError('SaaS 网关连接地址不是合法 URL', { code: 'bad_request' });
+  }
+  if (!['http:', 'https:', 'ws:', 'wss:'].includes(url.protocol)) {
+    throw new SaasAuthError('SaaS 网关连接地址只支持 ws/wss/http/https', { code: 'bad_request' });
+  }
+  let path = String(gateway.path ?? '').trim() || '/_gw/connect';
+  if (!path.startsWith('/')) path = `/${path}`;
+  return { url: `${url.protocol}//${url.host}`, path };
+}
+
+/**
+ * 解析 expiresAt：兼容 ISO 字符串、epoch 秒（JWT exp）、epoch 毫秒。
+ * @param {unknown} value
+ * @returns {number|null} epoch 毫秒；无法解析返回 null
+ */
+export function parseSaasExpiresAt(value) {
+  if (value === null || value === undefined || value === '') return null;
+  const numeric = Number(value);
+  if (Number.isFinite(numeric) && numeric > 0) {
+    // 1e12 毫秒 ≈ 2001-09；小于它的正数按秒级时间戳解释
+    return numeric < 1e12 ? Math.round(numeric * 1000) : Math.round(numeric);
+  }
+  const parsed = Date.parse(String(value));
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+/**
+ * deviceSecret 面板回显掩码（永远不回传明文）。
+ * @param {unknown} secret
+ * @returns {string}
+ */
+export function maskDeviceSecret(secret) {
+  const raw = String(secret ?? '');
+  if (!raw) return '';
+  if (raw.length <= 8) return SECRET_MASK;
+  return `${SECRET_MASK}${raw.slice(-4)}`;
+}
+
+/**
+ * 生成 POST /api/saas/device/code 的 device 信息（契约字段）。
+ * @param {Record<string, unknown>} [info]
+ * @returns {{name: string, platform: string} & Record<string, string>}
+ */
+export function buildDeviceInfo(info = {}) {
+  /** @type {Record<string, string>} */
+  const out = {};
+  for (const key of ['name', 'platform', 'hostname', 'arch', 'pluginVersion', 'dshVersion']) {
+    const value = info?.[key];
+    if (value === undefined || value === null) continue;
+    const text = String(value).trim();
+    if (text) out[key] = text;
+  }
+  if (!out.name) out.name = out.hostname || 'DSH Bridge';
+  if (!out.platform) out.platform = 'unknown';
+  return out;
+}
+
+function statusToErrorCode(status) {
+  if (status === 401) return 'auth_failed';
+  if (status === 403) return 'auth_failed';
+  if (status === 404) return 'bad_request';
+  if (status === 409) return 'conflict';
+  if (status === 429) return 'rate_limited';
+  if (status >= 500) return 'server_error';
+  return 'bad_request';
+}
+
+/**
+ * 统一 JSON 请求：错误体 `{code,message}` 原样带出；网络/超时映射成可读错误。
+ * @private
+ */
+async function requestJson({ url, method = 'GET', body, fetchImpl = globalThis.fetch, signal, timeoutMs = DEFAULT_TIMEOUT_MS }) {
+  if (typeof fetchImpl !== 'function') {
+    throw new SaasAuthError('当前运行环境缺少 fetch，无法连接 SaaS 控制面', { code: 'bad_request', terminal: true });
+  }
+  if (signal?.aborted) throw new SaasAuthError('请求已取消', { code: 'cancelled' });
+
+  const controller = new AbortController();
+  const onAbort = () => controller.abort();
+  signal?.addEventListener?.('abort', onAbort, { once: true });
+  const timer = setTimeout(() => controller.abort(), Math.max(1, timeoutMs));
+  try {
+    const headers = { accept: 'application/json' };
+    if (body !== undefined) headers['content-type'] = 'application/json';
+    const res = await fetchImpl(url, {
+      method,
+      headers,
+      body: body === undefined ? undefined : JSON.stringify(body),
+      signal: controller.signal,
+    });
+    const text = await res.text().catch(() => '');
+    let data = null;
+    if (text) {
+      try { data = JSON.parse(text); } catch { data = null; }
+    }
+    if (!res.ok) {
+      const code = String(data?.code ?? data?.error?.code ?? statusToErrorCode(res.status));
+      const message = String(data?.message ?? data?.error?.message ?? `SaaS 控制面请求失败 (HTTP ${res.status})`);
+      throw new SaasAuthError(message, {
+        code,
+        status: res.status,
+        retryable: res.status === 429 || res.status >= 500,
+        terminal: res.status === 401 || res.status === 403 || res.status === 404,
+      });
+    }
+    return data;
+  } catch (err) {
+    if (err instanceof SaasAuthError) throw err;
+    if (controller.signal.aborted) {
+      if (signal?.aborted) throw new SaasAuthError('请求已取消', { code: 'cancelled' });
+      throw new SaasAuthError(`SaaS 控制面请求超时 (${Math.round(timeoutMs / 1000)}s)`, { code: 'timeout', retryable: true });
+    }
+    throw new SaasAuthError(`无法连接 SaaS 控制面: ${err?.message ?? err}`, { code: 'network_error', retryable: true, cause: err });
+  } finally {
+    clearTimeout(timer);
+    signal?.removeEventListener?.('abort', onAbort);
+  }
+}
+
+/**
+ * 申请设备码（第一步）。
+ * @param {{gatewayUrl: string, deviceInfo?: object, fetchImpl?: Function, signal?: AbortSignal, timeoutMs?: number}} options
+ * @returns {Promise<{code: string, expiresAt: string|null, expiresAtMs: number|null, verificationUrl: string}>}
+ */
+export async function requestDeviceCode({ gatewayUrl, deviceInfo, fetchImpl, signal, timeoutMs } = {}) {
+  const base = normalizeSaasBaseUrl(gatewayUrl);
+  const data = await requestJson({
+    url: `${base}/api/saas/device/code`,
+    method: 'POST',
+    body: buildDeviceInfo(deviceInfo),
+    fetchImpl,
+    signal,
+    timeoutMs,
+  });
+  if (!data?.code) {
+    throw new SaasAuthError('SaaS 控制面未返回设备码', { code: 'bad_request', terminal: true });
+  }
+  return {
+    code: String(data.code),
+    expiresAt: data.expiresAt ?? null,
+    expiresAtMs: parseSaasExpiresAt(data.expiresAt),
+    verificationUrl: String(data.verificationUrl ?? ''),
+  };
+}
+
+/**
+ * 查询设备码状态（轮询用）。
+ * @returns {Promise<{status: string, expiresAt: string|null, expiresAtMs: number|null}>}
+ */
+export async function fetchDeviceCodeStatus({ gatewayUrl, code, fetchImpl, signal, timeoutMs } = {}) {
+  const base = normalizeSaasBaseUrl(gatewayUrl);
+  const trimmed = String(code ?? '').trim();
+  if (!trimmed) throw new SaasAuthError('设备码不能为空', { code: 'bad_request' });
+  const data = await requestJson({
+    url: `${base}/api/saas/device/code/${encodeURIComponent(trimmed)}`,
+    fetchImpl,
+    signal,
+    timeoutMs,
+  });
+  return {
+    status: String(data?.status ?? 'pending'),
+    expiresAt: data?.expiresAt ?? null,
+    expiresAtMs: parseSaasExpiresAt(data?.expiresAt),
+  };
+}
+
+/**
+ * 领取一次性 deviceSecret（第三/四步）。
+ * @returns {Promise<{deviceId: string, secret: string, tunnel: {publicId: string, name: string}|null}>}
+ */
+export async function claimDeviceCode({ gatewayUrl, code, fetchImpl, signal, timeoutMs } = {}) {
+  const base = normalizeSaasBaseUrl(gatewayUrl);
+  const trimmed = String(code ?? '').trim();
+  if (!trimmed) throw new SaasAuthError('设备码不能为空', { code: 'bad_request' });
+  const data = await requestJson({
+    url: `${base}/api/saas/device/code/${encodeURIComponent(trimmed)}/claim`,
+    method: 'POST',
+    fetchImpl,
+    signal,
+    timeoutMs,
+  });
+  if (!data?.deviceId || !data?.secret) {
+    throw new SaasAuthError('设备码领取失败：控制面未返回设备凭证', { code: 'bad_request' });
+  }
+  return {
+    deviceId: String(data.deviceId),
+    secret: String(data.secret),
+    tunnel: normalizeTunnel(data.tunnel),
+  };
+}
+
+/**
+ * 用 deviceSecret 换短期 deviceToken（每次连接/临期前调用）。
+ * @returns {Promise<{token: string, expiresAt: string|null, expiresAtMs: number|null, tunnel: object|null, gateway: {url: string, path: string}|null}>}
+ */
+export async function refreshDeviceToken({ gatewayUrl, deviceId, secret, fetchImpl, signal, timeoutMs } = {}) {
+  const base = normalizeSaasBaseUrl(gatewayUrl);
+  const id = String(deviceId ?? '').trim();
+  const value = String(secret ?? '');
+  if (!id || !value) throw new SaasAuthError('设备尚未绑定：缺少 deviceId/deviceSecret', { code: 'auth_failed', terminal: true });
+  const data = await requestJson({
+    url: `${base}/api/saas/device/token`,
+    method: 'POST',
+    body: { deviceId: id, secret: value },
+    fetchImpl,
+    signal,
+    timeoutMs,
+  });
+  if (!data?.token) {
+    throw new SaasAuthError('SaaS 控制面未返回设备令牌', { code: 'bad_request' });
+  }
+  return {
+    token: String(data.token),
+    expiresAt: data.expiresAt ?? null,
+    expiresAtMs: parseSaasExpiresAt(data.expiresAt),
+    tunnel: normalizeTunnel(data.tunnel),
+    gateway: normalizeSaasGateway(data.gateway),
+  };
+}
+
+function normalizeTunnel(tunnel) {
+  if (!tunnel || typeof tunnel !== 'object') return null;
+  const publicId = String(tunnel.publicId ?? '').trim();
+  const name = String(tunnel.name ?? '').trim();
+  if (!publicId && !name) return null;
+  return { publicId, name };
+}
+
+function defaultSleep(ms) {
+  return new Promise((resolve) => {
+    const timer = setTimeout(resolve, ms);
+    // 后台设备码等待不应单独钉住宿主进程（DSH 自身还有其他句柄）；
+    // 也避免异常路径下轮询定时器把测试进程拖住。
+    timer.unref?.();
+  });
+}
+
+/**
+ * 轮询设备码直到 approved 并领取凭证（设备码注册流程的完整等待段）。
+ *
+ * @param {object} options
+ * @param {string} options.gatewayUrl
+ * @param {string} options.code
+ * @param {number} [options.intervalMs] 轮询间隔，默认 2s
+ * @param {number} [options.timeoutMs] 总超时，默认 10min
+ * @param {(status: string) => void} [options.onStatus] 每次状态变化回调（pending/approved/...）
+ * @param {Function} [options.fetchImpl]
+ * @param {AbortSignal} [options.signal]
+ * @param {(ms: number) => Promise<void>} [options.sleep] 测试注入
+ * @returns {Promise<{deviceId: string, secret: string, tunnel: object|null}>}
+ */
+export async function waitForDeviceClaim({
+  gatewayUrl,
+  code,
+  intervalMs = DEFAULT_CLAIM_POLL_MS,
+  timeoutMs = DEFAULT_CLAIM_TIMEOUT_MS,
+  onStatus,
+  fetchImpl,
+  signal,
+  sleep = defaultSleep,
+} = {}) {
+  const startedAt = Date.now();
+  const pollMs = Math.max(1, Number(intervalMs) || DEFAULT_CLAIM_POLL_MS);
+  const budgetMs = Math.max(1, Number(timeoutMs) || DEFAULT_CLAIM_TIMEOUT_MS);
+  let lastStatus = null;
+  for (;;) {
+    if (signal?.aborted) throw new SaasAuthError('设备码绑定已取消', { code: 'cancelled' });
+    const status = await fetchDeviceCodeStatus({ gatewayUrl, code, fetchImpl, signal });
+    if (status.status !== lastStatus) {
+      lastStatus = status.status;
+      try { onStatus?.(lastStatus); } catch {}
+    }
+    if (lastStatus === 'approved') {
+      return claimDeviceCode({ gatewayUrl, code, fetchImpl, signal });
+    }
+    if (lastStatus === 'consumed') {
+      throw new SaasAuthError('设备码已被使用，请重新生成', { code: 'code_consumed', terminal: true });
+    }
+    if (lastStatus === 'expired') {
+      throw new SaasAuthError('设备码已过期，请重新生成', { code: 'code_expired', terminal: true });
+    }
+    const elapsed = Date.now() - startedAt;
+    if (elapsed >= budgetMs) {
+      throw new SaasAuthError('设备码绑定超时，请重新生成', { code: 'code_timeout', terminal: true });
+    }
+    await sleep(Math.min(pollMs, Math.max(1, budgetMs - elapsed)));
+  }
+}