dsh-plugin-remote-connect-beta 0.1.0-beta.1

package/lib/core/serversetup.js

@@ -0,0 +1,133 @@
+/**
+ * 服务器侧安装器生成：把《任务书》里"6 项交付"折叠成**一个可审查、幂等、可卸载的脚本**。
+ *
+ * 为什么是"生成脚本"而不是"插件去改用户的服务器"：
+ *  * 用户的服务器是他的生产机，插件不该直接动它；
+ *  * 脚本可以 `--dry-run` 先看、可以 `probe` 只探测、可以 `uninstall` 撤销；
+ *  * 所有写入都落在"本脚本独占的文件"里（conf.d 一个文件 + sshd drop-in + deploy hook），
+ *    因此幂等 = 覆盖写，卸载 = 删文件。
+ *
+ * 生成前对所有插入 bash 的取值做**严格校验**：域名/用户名/路径都会被拼进脚本，
+ * 不校验就等于把命令行参数当代码执行。
+ *
+ * @module dsh-plugin-remote-connect-beta/core/serversetup
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const TEMPLATE_PATH = path.join(
+  path.dirname(fileURLToPath(import.meta.url)),
+  'assets',
+  'server-setup.sh.tpl',
+)
+
+const HOSTNAME_PATTERN = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$/i
+const USERNAME_PATTERN = /^[a-z_][a-z0-9_-]{0,31}$/
+const PATH_PATTERN = /^\/[A-Za-z0-9._/-]+$/
+
+/**
+ * 校验并归一化生成参数。
+ * @param {object} options
+ * @returns {{ values: Record<string,string>, problems: string[] }}
+ */
+export function resolveServerSetupValues(options) {
+  const problems = []
+  const domain = String(options.domain ?? '')
+  if (!HOSTNAME_PATTERN.test(domain)) problems.push('domain 必须是合法主机名（例如 dsh.example.com）')
+
+  const tunnelUser = String(options.tunnelUser ?? 'dshtunnel')
+  if (!USERNAME_PATTERN.test(tunnelUser)) problems.push('tunnel-user 必须是合法 Linux 用户名')
+
+  const authUser = String(options.authUser ?? 'dsh')
+  if (!USERNAME_PATTERN.test(authUser)) problems.push('auth-user 必须是合法 Linux 用户名')
+
+  const remotePort = Number(options.remotePort ?? 8788)
+  if (!Number.isSafeInteger(remotePort) || remotePort < 1 || remotePort > 65535) {
+    problems.push('remote-port 必须是 1–65535 的整数')
+  }
+
+  const paths = {
+    AUTH_FILE: String(options.authFile ?? '/etc/nginx/.htpasswd-dsh-remote'),
+    WEBROOT: String(options.webroot ?? '/var/www/html'),
+    NGINX_CONF: String(options.nginxConf ?? '/etc/nginx/conf.d/dsh-remote.conf'),
+    SSHD_DROPIN: String(options.sshdDropin ?? '/etc/ssh/sshd_config.d/60-dsh-remote.conf'),
+    DEPLOY_HOOK: String(options.deployHook ?? '/etc/letsencrypt/renewal-hooks/deploy/10-reload-web.sh'),
+  }
+  for (const [key, value] of Object.entries(paths)) {
+    if (!PATH_PATTERN.test(value)) problems.push(key + ' 必须是绝对路径且不含引号/空格/变量')
+  }
+
+  return {
+    problems,
+    values: {
+      DOMAIN: domain,
+      REMOTE_PORT: String(remotePort),
+      TUNNEL_USER: tunnelUser,
+      AUTH_USER: authUser,
+      ...paths,
+    },
+  }
+}
+
+/**
+ * 生成服务器安装脚本全文。
+ * @param {object} options 见 resolveServerSetupValues
+ * @returns {string}
+ * @throws {Error} 参数不合法时抛出（生成物会被执行，宁可不生成）
+ */
+export function buildServerSetupScript(options) {
+  const { values, problems } = resolveServerSetupValues(options)
+  if (problems.length > 0) {
+    throw new Error('服务器安装脚本参数不合法：' + problems.join('；'))
+  }
+  const template = fs.readFileSync(TEMPLATE_PATH, 'utf8')
+  let out = template
+  for (const [key, value] of Object.entries(values)) {
+    out = out.split('{{' + key + '}}').join(value)
+  }
+  const leftover = /\{\{[A-Z_]+\}\}/.exec(out)
+  if (leftover !== null) throw new Error('服务器安装脚本模板占位符未替换：' + leftover[0])
+  if (!out.endsWith('\n')) out += '\n'
+  return out
+}
+
+/**
+ * 生成**独立**的卸载脚本（不依赖安装脚本还在不在服务器上）。
+ * @param {object} options 见 resolveServerSetupValues
+ * @returns {string}
+ */
+export function buildServerUninstallScript(options) {
+  const { values, problems } = resolveServerSetupValues(options)
+  if (problems.length > 0) {
+    throw new Error('卸载脚本参数不合法：' + problems.join('；'))
+  }
+  return [
+    '#!/usr/bin/env bash',
+    '# dsh-remote 服务器侧卸载（由 dsh-plugin-remote-connect-beta 生成）',
+    '#   sudo bash server-uninstall.sh [--purge-user]',
+    '# 只删除本方案自己创建的文件；不动你的 nginx/sshd 主配置、不动 DNS、不动 Basic Auth 口令文件。',
+    'set -euo pipefail',
+    '',
+    'TUNNEL_USER="' + values.TUNNEL_USER + '"',
+    'NGINX_CONF="' + values.NGINX_CONF + '"',
+    'SSHD_DROPIN="' + values.SSHD_DROPIN + '"',
+    'DEPLOY_HOOK="' + values.DEPLOY_HOOK + '"',
+    'PURGE=0',
+    '[ "${1:-}" = "--purge-user" ] && PURGE=1',
+    '',
+    '[ "$(id -u)" = "0" ] || { echo "✖ 需要 root"; exit 1; }',
+    'for f in "$NGINX_CONF" "$SSHD_DROPIN" "$DEPLOY_HOOK"; do',
+    '  if [ -f "$f" ]; then rm -f "$f"; echo "已删除 $f"; else echo "不存在，跳过 $f"; fi',
+    'done',
+    'if command -v nginx >/dev/null 2>&1; then nginx -t && systemctl reload nginx || true; fi',
+    'if command -v sshd >/dev/null 2>&1; then sshd -t && systemctl reload ssh || true; fi',
+    'if [ "$PURGE" = "1" ]; then',
+    '  if id "$TUNNEL_USER" >/dev/null 2>&1; then userdel -r "$TUNNEL_USER"; echo "已删除账号 $TUNNEL_USER"; fi',
+    'else',
+    '  echo "保留隧道账号 $TUNNEL_USER（加 --purge-user 可一并删除）"',
+    'fi',
+    'echo "完成。DNS 记录与 Basic Auth 口令文件未动（可能被其它服务共用）。"',
+    '',
+  ].join('\n')
+}

package/lib/core/snippets.js

@@ -0,0 +1,193 @@
+/**
+ * 服务器侧配置片段生成：用户拿到就能贴。
+ * 目标是把公网域名 → 服务器回环端口（ssh -R 的远端口）→ 本机代理 串起来，
+ * 并保证流式（SSE）与 WebSocket 可用。
+ *
+ * @module dsh-plugin-remote-connect-beta/core/snippets
+ */
+
+/** nginx 需要的 upgrade 映射（放 http 上下文）。 */
+export const NGINX_LOG_FORMAT = [
+  '# ?k= 是敏感凭据：请求行里的密钥绝不能落盘',
+  'log_format dsh_nokey \'$remote_addr - $remote_user [$time_local] "$request_method $uri" $status\';',
+].join('\n')
+
+export const NGINX_UPGRADE_MAP = [
+  'map $http_upgrade $connection_upgrade {',
+  '    default upgrade;',
+  "    ''      close;",
+  '}',
+].join('\n')
+
+/**
+ * 生成 nginx server block。
+ * @param {object} options
+ * @param {string} options.domain 公网域名，例如 dsh.example.com
+ * @param {number} [options.targetPort=8788] 服务器回环端口（与 ssh -R 的远端口一致）
+ * @param {string} [options.certPath] fullchain.pem 路径
+ * @param {string} [options.keyPath] privkey.pem 路径
+ * @param {string} [options.htpasswdPath='/etc/nginx/.htpasswd-dsh']
+ * @param {string} [options.authRealm='DSH']
+ * @param {number} [options.maxBodyMb=64] 放宽上传（Harness 会传图/附件）
+ * @param {boolean} [options.logRedaction=true] 用脱敏 format 单独记日志（避免 ?k= 落盘）
+ */
+export function nginxServerBlock(options) {
+  const domain = options.domain
+  const port = options.targetPort ?? 8788
+  const certPath = options.certPath ?? '/etc/letsencrypt/live/' + domain + '/fullchain.pem'
+  const keyPath = options.keyPath ?? '/etc/letsencrypt/live/' + domain + '/privkey.pem'
+  const htpasswdPath = options.htpasswdPath ?? '/etc/nginx/.htpasswd-dsh'
+  const realm = options.authRealm ?? 'DSH'
+  const maxBodyMb = options.maxBodyMb ?? 64
+  const logRedaction = options.logRedaction !== false
+  return [
+    '# ' + domain + ' —— DSH Harness 公网入口',
+    '# 1) upgrade map 与 log_format 放 http {} 上下文（conf.d/dsh-http.conf）',
+    '# 2) 刻意不提供 80 端口 server block：http→https 与 ACME challenge 由现有默认 server 承担；',
+    '#    另加精确 server_name 的 80 块会顶掉 /.well-known/acme-challenge/，导致签发/续期失败',
+    '',
+    'server {',
+    '    listen 443 ssl;',
+    '    listen [::]:443 ssl;',
+    '    http2 on;',
+    '    server_name ' + domain + ';',
+    '',
+    '    ssl_certificate     ' + certPath + ';',
+    '    ssl_certificate_key ' + keyPath + ';',
+    '',
+    '    # 第一道门：边缘口令',
+    '    auth_basic           "' + realm + '";',
+    '    auth_basic_user_file ' + htpasswdPath + ';',
+    '',
+    '    client_max_body_size ' + String(maxBodyMb) + 'm;',
+    '',
+    logRedaction ? '    # ?k= 是敏感凭据，禁止完整请求行落盘（access_log off 亦可）' : '    # 未启用脱敏时，?k= 会明文进入访问日志',
+    logRedaction ? '    access_log /var/log/nginx/dsh.access.log dsh_nokey;' : '    access_log /var/log/nginx/dsh.access.log;',
+    '',
+    '    location / {',
+    '        proxy_pass http://127.0.0.1:' + String(port) + ';',
+    '        proxy_http_version 1.1;',
+    '',
+    '        proxy_set_header Host              $host;',
+    '        proxy_set_header X-Real-IP         $remote_addr;',
+    '        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;',
+    '        proxy_set_header X-Forwarded-Proto $scheme;',
+    '        proxy_set_header Upgrade           $http_upgrade;',
+    '        proxy_set_header Connection        $connection_upgrade;',
+    '',
+    '        # ★ 关缓冲 + 放长超时：不关的话 Harness 的流式输出会卡死',
+    '        proxy_buffering         off;',
+    '        proxy_request_buffering off;',
+    '        proxy_read_timeout      3600s;',
+    '        proxy_send_timeout      3600s;',
+    '        proxy_connect_timeout   15s;',
+    '',
+    '        proxy_redirect off;',
+    '    }',
+    '}',
+    '',
+    '# 注意：这里刻意不提供 80 端口 server block —— 见文件头第 2 条。',
+  ].join('\n')
+}
+
+/**
+ * 生成 Caddy 配置片段（Caddy 自带证书与流式处理）。
+ * @param {object} options
+ * @param {string} options.domain
+ * @param {number} [options.targetPort=8788]
+ * @param {string} [options.basicAuthUser='dsh']
+ * @param {string} [options.basicAuthHash] caddy hash-password 的输出
+ * @param {number} [options.maxBodyMb=64]
+ */
+export function caddySite(options) {
+  const port = options.targetPort ?? 8788
+  const user = options.basicAuthUser ?? 'dsh'
+  const hash = options.basicAuthHash ?? '$2a$14$REPLACE_WITH_caddy_hash_password_OUTPUT'
+  const maxBodyMb = options.maxBodyMb ?? 64
+  return [
+    options.domain + ' {',
+    '    basic_auth {',
+    '        ' + user + ' ' + hash,
+    '    }',
+    '    reverse_proxy 127.0.0.1:' + String(port) + ' {',
+    '        flush_interval -1          # ★ 不缓冲，等价于 nginx 的 proxy_buffering off',
+    '    }',
+    '    request_body {',
+    '        max_size ' + String(maxBodyMb) + 'MB',
+    '    }',
+    '}',
+  ].join('\n')
+}
+
+/**
+ * authorized_keys 限制行：这把钥匙只能做转发，且只能监听指定回环端口。
+ * @param {string} publicKey 形如 "ssh-ed25519 AAAA... comment"
+ * @param {number} [targetPort=8788]
+ */
+export function authorizedKeysLine(publicKey, targetPort = 8788) {
+  const clean = publicKey.trim().replace(/\s+/g, ' ')
+  // remote-port-forwarding（而不是 port-forwarding）：我们只用 -R，
+  // 这样连"本地转发 -L"都不放开；`restrict` 先关掉一切，再逐项放开。
+  return 'restrict,remote-port-forwarding,permitlisten="127.0.0.1:' + String(targetPort) + '" ' + clean
+}
+
+/**
+ * Mac/客户端侧要跑的 ssh 反向隧道命令。
+ * @param {object} options
+ * @param {string} options.user 服务器上的专用账号
+ * @param {string} options.host 服务器地址（域名或 IP）
+ * @param {string} [options.keyPath] 私钥路径
+ * @param {number} [options.localPort=8788] 本机监听端口（代理的公网口）
+ * @param {number} [options.remotePort=8788] 服务器回环端口（与反代目标一致）
+ * @param {number} [options.port=22] 服务器 sshd 端口（非 22 时必须显式给出）
+ */
+export function sshTunnelCommand(options) {
+  const localPort = options.localPort ?? 8788
+  const remotePort = options.remotePort ?? 8788
+  const port = options.port ?? 22
+  const parts = [
+    'ssh -N -T',
+    ...(port === 22 ? [] : ['  -p ' + String(port)]),
+    '  -o ExitOnForwardFailure=yes',
+    '  -o ServerAliveInterval=30 -o ServerAliveCountMax=3',
+    '  -o StrictHostKeyChecking=yes',
+  ]
+  if (options.keyPath) parts.push('  -i ' + options.keyPath)
+  parts.push(
+    '  -R 127.0.0.1:' + String(remotePort) + ':127.0.0.1:' + String(localPort),
+    '  ' + options.user + '@' + options.host,
+  )
+  return parts.join(' \\\n')
+}
+
+/** 服务器一次性准备步骤（给用户照抄）。 */
+export function serverSetupSteps(options) {
+  const targetPort = options.targetPort ?? 8788
+  const user = options.user ?? 'dshtunnel'
+  return [
+    '在服务器上执行（Debian/Ubuntu 为例）：',
+    '',
+    '  # 1) 专用账号（不复用 root 或日常账号；隧道只用 -N -T，不需要登录 shell）',
+    '  sudo useradd -m -s /usr/sbin/nologin ' + user,
+    '  sudo -u ' + user + ' mkdir -p /home/' + user + '/.ssh',
+    '  sudo -u ' + user + ' chmod 700 /home/' + user + '/.ssh',
+    '',
+    '  # 2) 把下面这行 authorized_keys 限制写入（公钥用 dsh-remote keygen 生成）',
+    '  #    见 `dsh-remote keygen` 的输出',
+    '',
+    '  # 3) 确认 sshd 允许转发（被加固过的机器常被关掉）',
+    '  sudo sshd -T | grep -Ei "allowtcpforwarding|gatewayports"',
+    '  #    需要 allowtcpforwarding=yes（或 local,remote）；gatewayports 保持 no 即可',
+    '  #    建议同时设 ClientAliveInterval 30（长连接隧道更稳）',
+    '',
+    '  # 4) Basic Auth 口令文件',
+    '  sudo apt install -y apache2-utils',
+    '  sudo htpasswd -c /etc/nginx/.htpasswd-dsh dsh',
+    '',
+    '  # 5) 贴上 nginx 片段，然后',
+    '  sudo nginx -t && sudo systemctl reload nginx',
+    '',
+    '目标：服务器回环 ' + String(targetPort) + ' 端口 ← 由 Mac 的 ssh -R 提供，',
+    '      再由 nginx/Caddy 用 HTTPS + Basic Auth 暴露成公网域名。',
+  ].join('\n')
+}

package/lib/core/tailscale.js

@@ -0,0 +1,158 @@
+/**
+ * tailscale funnel 后端：自己机器就是出口，服务器侧零交付。
+ *
+ * 为什么单独一个模块：
+ *  - `tailscale funnel --bg` 是**一次性配置命令**（配完就退出，由 tailscaled 常驻），
+ *    与 ssh / cloudflared 那种"长驻子进程"看护模型不同，需要单独处理启动、探测与撤销。
+ *  - argv 构造与输出解析都是纯函数，便于在没有 tailscale 的机器上测试。
+ *
+ * 用到的命令都只影响本机 tailscaled，不写任何系统服务、不改 sshd。
+ *
+ * @module dsh-plugin-remote-connect-beta/core/tailscale
+ */
+import { spawn } from 'node:child_process'
+
+/** funnel 默认对外暴露的 HTTPS 端口（由 tailscaled 提供证书）。 */
+export const DEFAULT_HTTPS_PORT = 443
+
+/**
+ * 建立 funnel 映射：把本机回环端口发布为 `https://<node>.<tailnet>.ts.net/`。
+ * @param {object} options
+ * @param {string} [options.path='tailscale']
+ * @param {number} options.localPort 本机回环端口
+ * @param {number} [options.httpsPort=443]
+ */
+export function funnelUpArgv(options) {
+  const httpsPort = options.httpsPort ?? DEFAULT_HTTPS_PORT
+  return [
+    options.path ?? 'tailscale',
+    'funnel',
+    '--bg',
+    '--https=' + String(httpsPort),
+    'http://127.0.0.1:' + String(options.localPort),
+  ]
+}
+
+/**
+ * 撤销 funnel 映射（只撤这一个 https 端口，不碰其它 serve 配置）。
+ * @param {object} options
+ * @param {string} [options.path='tailscale']
+ * @param {number} [options.httpsPort=443]
+ */
+export function funnelOffArgv(options = {}) {
+  const httpsPort = options.httpsPort ?? DEFAULT_HTTPS_PORT
+  return [options.path ?? 'tailscale', 'funnel', '--https=' + String(httpsPort), 'off']
+}
+
+/** `tailscale status --json`：拿本节点的 DNSName（funnel 对外域名）。 */
+export function statusArgv(options = {}) {
+  return [options.path ?? 'tailscale', 'status', '--json']
+}
+
+/** `tailscale funnel status`：给人看的当前 funnel 配置。 */
+export function funnelStatusArgv(options = {}) {
+  return [options.path ?? 'tailscale', 'funnel', 'status']
+}
+
+/**
+ * 从 `tailscale status --json` 输出里取本节点域名。
+ * @param {string} text
+ * @returns {{ host: string, url: string } | null} 解析不出时返回 null
+ */
+export function parseSelfDnsName(text) {
+  let parsed
+  try {
+    parsed = JSON.parse(text)
+  } catch {
+    return null
+  }
+  const name = parsed !== null && typeof parsed === 'object' ? parsed.Self?.DNSName : undefined
+  if (typeof name !== 'string' || name.trim() === '') return null
+  // DNSName 带结尾的点（FQDN），去掉才能拼 URL
+  const host = name.trim().replace(/\.$/, '')
+  if (!/^[A-Za-z0-9.-]+$/.test(host)) return null
+  return { host, url: 'https://' + host + '/' }
+}
+
+/**
+ * 把 tailscale 的报错收敛成几个可翻译的原因码。
+ * @param {string} text stderr / stdout
+ * @returns {'missing'|'loggedout'|'disabled'|'generic'}
+ */
+export function classifyFunnelError(text) {
+  const lower = String(text ?? '').toLowerCase()
+  if (lower.includes('enoent') || lower.includes('executable file not found') || lower.includes('command not found')) {
+    return 'missing'
+  }
+  if (lower.includes('logged out') || lower.includes('not logged in') || lower.includes('needs login')) return 'loggedout'
+  if (lower.includes('funnel is not enabled') || lower.includes('not enabled') || lower.includes('access denied')) {
+    return 'disabled'
+  }
+  return 'generic'
+}
+
+/**
+ * 跑一条一次性命令，收齐输出。
+ * @param {string[]} argv
+ * @param {object} [options]
+ * @param {number} [options.timeoutMs=10000]
+ * @param {typeof spawn} [options.spawnImpl]
+ * @returns {Promise<{ code: number|null, stdout: string, stderr: string, error?: string }>}
+ */
+export async function runOnce(argv, options = {}) {
+  const spawnImpl = options.spawnImpl ?? spawn
+  const timeoutMs = options.timeoutMs ?? 10000
+  return await new Promise((resolve) => {
+    let child
+    try {
+      child = spawnImpl(argv[0], argv.slice(1), { stdio: ['ignore', 'pipe', 'pipe'] })
+    } catch (error) {
+      resolve({ code: null, stdout: '', stderr: '', error: String(error?.message ?? error) })
+      return
+    }
+    let stdout = ''
+    let stderr = ''
+    let settled = false
+    const finish = (result) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      resolve(result)
+    }
+    const timer = setTimeout(() => {
+      try {
+        child.kill('SIGKILL')
+      } catch {
+        /* 已退出 */
+      }
+      finish({ code: null, stdout, stderr, error: 'timeout' })
+    }, timeoutMs)
+    child.stdout?.on('data', (chunk) => {
+      stdout = (stdout + chunk.toString('utf8')).slice(-8000)
+    })
+    child.stderr?.on('data', (chunk) => {
+      stderr = (stderr + chunk.toString('utf8')).slice(-8000)
+    })
+    child.on('error', (error) => finish({ code: null, stdout, stderr, error: String(error?.message ?? error) }))
+    child.on('exit', (code) => finish({ code, stdout, stderr }))
+  })
+}
+
+/**
+ * 读本节点对外地址（funnel 的域名来自节点名，不来自配置）。
+ * @param {object} [options]
+ * @param {string} [options.path]
+ * @param {typeof spawn} [options.spawnImpl]
+ * @returns {Promise<{ ok: boolean, host?: string, url?: string, detail?: string, reason?: string }>}
+ */
+export async function readSelfUrl(options = {}) {
+  const result = await runOnce(statusArgv({ path: options.path }), { spawnImpl: options.spawnImpl })
+  if (result.error !== undefined) return { ok: false, detail: result.error, reason: classifyFunnelError(result.error) }
+  if (result.code !== 0) {
+    const text = (result.stderr || result.stdout).trim()
+    return { ok: false, detail: text, reason: classifyFunnelError(text) }
+  }
+  const parsed = parseSelfDnsName(result.stdout)
+  if (parsed === null) return { ok: false, detail: 'no Self.DNSName in status output', reason: 'generic' }
+  return { ok: true, host: parsed.host, url: parsed.url }
+}