@qzsy/dsh-bridge 0.0.0-stage → 3.0.0

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)));
+  }
+}