@qzsy/dsh-bridge 0.0.0-stage → 3.0.0

package/lib/gate.js

@@ -0,0 +1,382 @@
+// 本地门禁代理：监听本机端口 → 转发到 DSH 本体，并注入 DSH 原生 loopback cookie。
+//
+// 来源分类（与 docs/research/dsh-bridge-protocol.md §5.1 L1 的安全语义一致）：
+//   1. 回环且非隧道（物理本机直连）→ 免认证，享有最高特权（可领取 adminToken）。
+//   2. 带合法 x-dsh-internal-tunnel 标记（由本插件的 SaaS 隧道客户端在本地注入，
+//      密钥为进程内随机值，公网无法伪造）→ 视为 SaaS 隧道路径；网关已完成设备鉴权，
+//      请求携带 x-saas-user 时记录账号身份。
+//   3. 其它来源（局域网直连 / 伪造标记）→ 必须携带本地口令会话，或通过 ?auth=<accessToken>
+//      换取会话 cookie；否则 401（JSON 或登录页）。
+//
+// /__qzsy_bridge__/loopback-token 只对第 1 类来源签发管理令牌；隧道来源一律 403。
+import { createServer, request } from 'node:http';
+import { connect as netConnect } from 'node:net';
+import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+import { getDshAuthCookie, mergeCookieHeader } from './dsh-cookie.js';
+import { verifyPassword } from './config.js';
+import { PLUGIN_ID } from './identity.js';
+
+export const AUTH_COOKIE = 'qzsy_bridge_auth';
+export const TUNNEL_HEADER = 'x-dsh-internal-tunnel';
+export const SAAS_USER_HEADER = 'x-saas-user';
+const SESSION_MAX_AGE_MS = 30 * 24 * 60 * 60 * 1000;
+const LOOPBACK_ADDRESSES = new Set(['127.0.0.1', '::1', '::ffff:127.0.0.1']);
+const HOP_BY_HOP = new Set(['connection', 'keep-alive', 'proxy-authenticate', 'proxy-authorization', 'te', 'trailer', 'transfer-encoding', 'upgrade']);
+
+function safeEqual(left, right) {
+  const a = Buffer.from(String(left ?? ''));
+  const b = Buffer.from(String(right ?? ''));
+  return a.length === b.length && a.length > 0 && timingSafeEqual(a, b);
+}
+
+function isLoopbackAddress(address) {
+  return LOOPBACK_ADDRESSES.has(String(address ?? ''));
+}
+
+function parseCookies(header) {
+  const out = {};
+  for (const part of String(header ?? '').split(';')) {
+    const index = part.indexOf('=');
+    if (index <= 0) continue;
+    out[part.slice(0, index).trim()] = part.slice(index + 1).trim();
+  }
+  return out;
+}
+
+function escapeHtml(value) {
+  return String(value ?? '')
+    .replaceAll('&', '&amp;')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+    .replaceAll("'", '&#39;');
+}
+
+function cleanHeaders(headers, { cookie, targetPort } = {}) {
+  const out = {};
+  for (const [name, value] of Object.entries(headers ?? {})) {
+    const lower = name.toLowerCase();
+    if (HOP_BY_HOP.has(lower) || lower === TUNNEL_HEADER || lower === SAAS_USER_HEADER) continue;
+    if (value === undefined) continue;
+    out[lower] = value;
+  }
+  if (targetPort) {
+    out.host = `127.0.0.1:${targetPort}`;
+    if (out.origin) out.origin = `http://127.0.0.1:${targetPort}`;
+  }
+  if (cookie) out.cookie = cookie;
+  return out;
+}
+
+export class GateProxy {
+  constructor({
+    targetPort,
+    port = 3092,
+    host = '0.0.0.0',
+    config = {},
+    internalSecret,
+    logger = console,
+    dshHome,
+    now = () => Date.now(),
+    adminToken,
+  } = {}) {
+    if (!targetPort) throw new Error('targetPort is required');
+    this.targetPort = Number(targetPort);
+    const numericPort = Number(port);
+    this.port = Number.isInteger(numericPort) && numericPort >= 0 ? numericPort : 3092;
+    this.host = host;
+    this.config = config;
+    this.internalSecret = String(internalSecret ?? '');
+    this.logger = logger;
+    this.dshHome = dshHome;
+    this.now = now;
+    this.adminToken = adminToken || `adm_${randomBytes(24).toString('base64url')}`;
+    this.server = null;
+    this.listeningPort = null;
+  }
+
+  /** 关闭会话签名：v1.<expiresAt>.<hmac(expiresAt)>；不落盘、无服务端会话表。 */
+  sessionToken(expiresAt = this.now() + SESSION_MAX_AGE_MS) {
+    const secret = this.config?.access?.sessionSecret;
+    if (!secret) return '';
+    const signature = createHmac('sha256', secret).update(String(expiresAt)).digest('base64url');
+    return `v1.${expiresAt}.${signature}`;
+  }
+
+  verifySession(token) {
+    const parts = String(token ?? '').split('.');
+    if (parts.length !== 3 || parts[0] !== 'v1') return false;
+    const expiresAt = Number(parts[1]);
+    if (!Number.isFinite(expiresAt) || expiresAt <= this.now()) return false;
+    return safeEqual(parts[2], this.sessionToken(expiresAt).split('.')[2]);
+  }
+
+  /** 来源分类：返回 { source: 'loopback'|'tunnel'|'remote', authenticated, saasUser }。 */
+  classify(req) {
+    const headers = req?.headers ?? {};
+    const marker = headers[TUNNEL_HEADER];
+    if (this.internalSecret && safeEqual(marker, this.internalSecret)) {
+      // 内部标记只证明"请求来自本插件的隧道客户端"，不等于访客已认证：
+      // 仍需本地口令会话 / ?auth= 令牌换来的会话 cookie。
+      const cookies = parseCookies(headers.cookie);
+      return {
+        source: 'tunnel',
+        authenticated: this.verifySession(cookies[AUTH_COOKIE]),
+        saasUser: String(headers[SAAS_USER_HEADER] ?? ''),
+      };
+    }
+    const address = req?.socket?.remoteAddress;
+    if (isLoopbackAddress(address)) {
+      return { source: 'loopback', authenticated: true, saasUser: '' };
+    }
+    const cookies = parseCookies(headers.cookie);
+    if (this.verifySession(cookies[AUTH_COOKIE])) {
+      return { source: 'remote', authenticated: true, saasUser: '' };
+    }
+    return { source: 'remote', authenticated: false, saasUser: '' };
+  }
+
+  /** 是否已设置本地访问口令（未设置时拒绝一切远程/隧道访客）。 */
+  passwordConfigured() {
+    return Boolean(this.config?.access?.passwordHash && this.config?.access?.passwordSalt);
+  }
+
+  /** RPC 管理鉴权：令牌只能由物理回环调用 /__qzsy_bridge__/loopback-token 取得。 */
+  verifyAdminToken(token) {
+    return safeEqual(token, this.adminToken);
+  }
+
+  /** 拼接给管理员看的远程入口（带固定访问令牌，首次打开后换 cookie）。 */
+  accessUrl(baseUrl) {
+    const token = this.config?.access?.token;
+    if (!baseUrl || !token) return String(baseUrl ?? '');
+    const url = new URL(String(baseUrl));
+    url.searchParams.set('auth', token);
+    return url.toString();
+  }
+
+  _setSessionCookie(res, expiresAt = this.now() + SESSION_MAX_AGE_MS) {
+    const token = this.sessionToken(expiresAt);
+    if (!token) return;
+    res.setHeader('set-cookie', `${AUTH_COOKIE}=${token}; Path=/; HttpOnly; SameSite=Lax; Max-Age=${Math.floor(SESSION_MAX_AGE_MS / 1000)}`);
+  }
+
+  _setupPage() {
+    return `<!doctype html><html lang="zh-CN"><meta charset="utf-8" />
+<title>DSH 远程隧道云 · 需要初始化</title>
+<style>body{font-family:system-ui,-apple-system,"Segoe UI",sans-serif;background:#0f1115;color:#e5e7eb;display:grid;place-items:center;min-height:100vh;margin:0}div{background:#171a21;padding:28px;border-radius:12px;width:min(92vw,420px);border:1px solid #2b303b}h1{font-size:17px;margin:0 0 12px}p{color:#9ca3af;font-size:13px;line-height:1.7;margin:6px 0}</style>
+<div><h1>尚未设置访问口令</h1><p>DSH 远程隧道云默认拒绝未认证的远程/隧道访客。</p><p>请先在<b>本机</b> DSH 设置页「远程访问」中设置访问口令，再把「带访问令牌的链接」发给需要访问的人。</p></div></html>`;
+  }
+
+  _corsHeaders(req) {
+    const origin = String(req?.headers?.origin ?? '');
+    if (!origin) return {};
+    try {
+      const parsed = new URL(origin);
+      const host = parsed.hostname;
+      if (origin === 'dsh-app://app' || host === '127.0.0.1' || host === 'localhost' || host === '::1') {
+        return { 'access-control-allow-origin': origin, vary: 'origin' };
+      }
+    } catch {}
+    return {};
+  }
+
+  _loginPage(path, message = '') {
+    return `<!doctype html><html lang="zh-CN"><meta charset="utf-8" />
+<title>DSH 远程隧道云 · 访问验证</title>
+<style>body{font-family:system-ui,-apple-system,"Segoe UI",sans-serif;background:#0f1115;color:#e5e7eb;display:grid;place-items:center;min-height:100vh;margin:0}form{background:#171a21;padding:28px;border-radius:12px;width:min(92vw,360px);border:1px solid #2b303b}h1{font-size:17px;margin:0 0 14px}p{color:#9ca3af;font-size:13px;line-height:1.6}input{width:100%;box-sizing:border-box;padding:10px;border-radius:8px;border:1px solid #333a46;background:#0f1115;color:inherit;margin:10px 0}button{width:100%;padding:10px;border:0;border-radius:8px;background:#4f6ef7;color:#fff;font-weight:600;cursor:pointer}.err{color:#f87171;font-size:12px;min-height:16px}</style>
+<form method="post" action="/__qzsy_bridge__/login?next=${encodeURIComponent(path)}"><h1>访问验证</h1><p>该入口需要本地访问口令。口令由插件在 DSH 设置页「远程访问」中设置。</p><input name="password" type="password" placeholder="访问口令" autofocus /><div class="err">${escapeHtml(message)}</div><button type="submit">进入</button></form></html>`;
+  }
+
+  async _readBody(req, limit = 64 * 1024) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of req) {
+      size += chunk.length;
+      if (size > limit) throw new Error('body too large');
+      chunks.push(chunk);
+    }
+    return Buffer.concat(chunks).toString('utf8');
+  }
+
+  async _handleLocal(req, res, verdict) {
+    const url = new URL(req.url ?? '/', 'http://localhost');
+    if (url.pathname === '/__qzsy_bridge__/loopback-token') {
+      if (verdict.source !== 'loopback') {
+        res.writeHead(403, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' });
+        res.end(JSON.stringify({ ok: false, error: 'Forbidden: loopback only' }));
+        return true;
+      }
+      res.writeHead(200, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store', ...this._corsHeaders(req) });
+      res.end(JSON.stringify({ ok: true, adminToken: this.adminToken }));
+      return true;
+    }
+    if (url.pathname === '/__qzsy_bridge__/login') {
+      if (req.method === 'GET') {
+        res.writeHead(200, { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store' });
+        res.end(this._loginPage(url.searchParams.get('next') || '/'));
+        return true;
+      }
+      if (req.method === 'POST') {
+        const body = await this._readBody(req);
+        const password = new URLSearchParams(body).get('password') ?? '';
+        if (!verifyPassword(password, this.config?.access ?? {})) {
+          res.writeHead(401, { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store' });
+          res.end(this._loginPage(url.searchParams.get('next') || '/', '口令不正确'));
+          return true;
+        }
+        this._setSessionCookie(res);
+        res.writeHead(302, { location: url.searchParams.get('next') || '/', 'cache-control': 'no-store' });
+        res.end();
+        return true;
+      }
+    }
+    return false;
+  }
+
+  _handleAuthToken(req, res, verdict) {
+    if (verdict.source === 'loopback') return false;
+    const url = new URL(req.url ?? '/', 'http://localhost');
+    const provided = url.searchParams.get('auth');
+    if (!provided || !safeEqual(provided, this.config?.access?.token)) return false;
+    url.searchParams.delete('auth');
+    this._setSessionCookie(res, this.now() + SESSION_MAX_AGE_MS);
+    res.writeHead(302, { location: (url.pathname || '/') + (url.search || ''), 'cache-control': 'no-store' });
+    res.end();
+    return true;
+  }
+
+  _upstreamCookie(req) {
+    const dshCookie = getDshAuthCookie(this.targetPort, { dshHome: this.dshHome, now: this.now() });
+    return mergeCookieHeader(req.headers.cookie, dshCookie);
+  }
+
+  _proxyHttp(req, res) {
+    const headers = cleanHeaders(req.headers, { cookie: this._upstreamCookie(req), targetPort: this.targetPort });
+    const upstream = request({
+      host: '127.0.0.1',
+      port: this.targetPort,
+      method: req.method,
+      path: req.url,
+      headers,
+    }, (upstreamRes) => {
+      const responseHeaders = {};
+      for (const [name, value] of Object.entries(upstreamRes.headers)) {
+        if (HOP_BY_HOP.has(name.toLowerCase())) continue;
+        responseHeaders[name] = value;
+      }
+      res.writeHead(upstreamRes.statusCode ?? 502, responseHeaders);
+      upstreamRes.pipe(res);
+    });
+    upstream.on('error', (err) => {
+      this.logger?.warn?.(`[${PLUGIN_ID}] upstream error: ${err?.message ?? err}`);
+      if (!res.headersSent) {
+        res.writeHead(502, { 'content-type': 'text/plain; charset=utf-8' });
+        res.end('Bad Gateway: DSH 本体不可达');
+      } else {
+        res.destroy();
+      }
+    });
+    req.pipe(upstream);
+  }
+
+  _proxyUpgrade(req, socket, head) {
+    const upstream = netConnect({ host: '127.0.0.1', port: this.targetPort }, () => {
+      // Upgrade 请求必须保留 connection/upgrade/sec-websocket-* 头，不能走普通请求的逐跳过滤
+      const headers = {};
+      for (const [name, value] of Object.entries(req.headers)) {
+        const lower = name.toLowerCase();
+        if (lower === TUNNEL_HEADER || lower === SAAS_USER_HEADER) continue;
+        if (value !== undefined) headers[lower] = value;
+      }
+      headers.host = `127.0.0.1:${this.targetPort}`;
+      headers.cookie = this._upstreamCookie(req);
+      const lines = [`${req.method} ${req.url} HTTP/1.1`];
+      for (const [name, value] of Object.entries(headers)) {
+        if (Array.isArray(value)) for (const item of value) lines.push(`${name}: ${item}`);
+        else lines.push(`${name}: ${value}`);
+      }
+      lines.push('', '');
+      upstream.write(lines.join('\r\n'));
+      if (head?.length) upstream.write(head);
+      upstream.pipe(socket);
+      socket.pipe(upstream);
+    });
+    upstream.on('error', () => {
+      try { socket.write('HTTP/1.1 502 Bad Gateway\r\ncontent-length: 0\r\n\r\n'); } catch {}
+      socket.destroy();
+    });
+    socket.on('error', () => upstream.destroy());
+  }
+
+  async _handle(req, res) {
+    const verdict = this.classify(req);
+    if (req.method === 'OPTIONS' && String(req.url ?? '').startsWith('/__qzsy_bridge__/')) {
+      res.writeHead(204, {
+        'access-control-allow-methods': 'GET, POST, OPTIONS',
+        'access-control-allow-headers': 'content-type',
+        'access-control-max-age': '600',
+        ...this._corsHeaders(req),
+      });
+      res.end();
+      return;
+    }
+    if (await this._handleLocal(req, res, verdict)) return;
+    if (this._handleAuthToken(req, res, verdict)) return;
+    if (!verdict.authenticated) {
+      const wantsJson = String(req.headers.accept ?? '').includes('application/json')
+        || String(req.url ?? '').startsWith('/api/');
+      const passwordSet = this.passwordConfigured();
+      if (wantsJson) {
+        res.writeHead(401, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' });
+        res.end(JSON.stringify({ ok: false, error: 'unauthorized', code: passwordSet ? 'access_required' : 'password_not_set' }));
+      } else {
+        res.writeHead(401, { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store' });
+        res.end(passwordSet ? this._loginPage(req.url ?? '/') : this._setupPage());
+      }
+      return;
+    }
+    this._proxyHttp(req, res);
+  }
+
+  async start() {
+    if (this.server) return this.listeningPort;
+    this.server = createServer((req, res) => {
+      this._handle(req, res).catch((err) => {
+        this.logger?.error?.(`[${PLUGIN_ID}] gate error: ${err?.stack ?? err}`);
+        if (!res.headersSent) res.writeHead(500, { 'content-type': 'text/plain' });
+        res.end('Internal Error');
+      });
+    });
+    this.server.on('upgrade', (req, socket, head) => {
+      const verdict = this.classify(req);
+      if (!verdict.authenticated) {
+        try { socket.write('HTTP/1.1 401 Unauthorized\r\ncontent-length: 0\r\n\r\n'); } catch {}
+        socket.destroy();
+        return;
+      }
+      this._proxyUpgrade(req, socket, head);
+    });
+    await new Promise((resolve, reject) => {
+      this.server.once('error', reject);
+      this.server.listen(this.port, this.host, () => {
+        this.server.off('error', reject);
+        this.listeningPort = this.server.address()?.port ?? this.port;
+        resolve();
+      });
+    });
+    this.logger?.info?.(`[${PLUGIN_ID}] gate listening on ${this.host}:${this.listeningPort} -> 127.0.0.1:${this.targetPort}`);
+    return this.listeningPort;
+  }
+
+  async stop() {
+    if (!this.server) return;
+    const server = this.server;
+    this.server = null;
+    // 已升级的 WebSocket 连接不会被常规 close 收敛，先强制断开避免宿主退出挂住
+    server.closeAllConnections?.();
+    await new Promise((resolve) => server.close(() => resolve()));
+  }
+}
+
+export { isLoopbackAddress };

package/lib/identity.js

@@ -0,0 +1,23 @@
+// 插件身份常量（Host 与浏览器客户端共享；纯 JS，不 import node:*）
+//
+// 所有注册键都带 qzsy 前缀，保证同一 DSH profile 内与任何其它插件不冲突。
+// 本插件是独立实现：不依赖、不包含上游 dsh-bridge 的代码。
+export const PLUGIN_ID = 'qzsy-dsh-bridge';
+export const PACKAGE_NAME = '@qzsy/dsh-bridge';
+export const DATA_DIR = 'qzsy-dsh-bridge';
+export const DEFAULT_PORT = 3092;
+export const DEFAULT_GATEWAY_URL = 'wss://dsh.b.nps.qzsyzn.com/_gw/connect';
+export const GATEWAY_PATH = '/_gw/connect';
+export const RPC_CHANNEL = `/${PLUGIN_ID}`;
+export const RPC_ENDPOINTS = Object.freeze({
+  getStatus: 'getStatus',
+  saveGateway: 'saveGateway',
+  requestDeviceCode: 'requestDeviceCode',
+  bindDevice: 'bindDevice',
+  unbindDevice: 'unbindDevice',
+  startTunnel: 'startTunnel',
+  stopTunnel: 'stopTunnel',
+  getAccessUrl: 'getAccessUrl',
+  setAccessPassword: 'setAccessPassword',
+  clearAccessPassword: 'clearAccessPassword',
+});