@lasting-beauty/chat-hub 0.1.0-beta.1

package/cli/external-verification.mjs

@@ -0,0 +1,219 @@
+import { lookup } from 'node:dns/promises';
+import net, { isIP } from 'node:net';
+
+const protectedPorts = [4310, 8080];
+
+export async function verifyExternalDeployment({
+  domain,
+  publicHost = domain,
+  publicScheme = 'https',
+  origin,
+  resolveAddresses = defaultResolveAddresses,
+  probePort = defaultProbePort,
+  fetchImpl = fetch,
+  environment = process.env,
+  now = Date.now(),
+} = {}) {
+  if (!isValidEndpoint(publicHost, publicScheme)) throw new Error('外部验收公网入口无效');
+  if (origin !== undefined && isIP(origin) === 0) {
+    throw new Error('--origin 必须是明确的 IPv4 或 IPv6 地址');
+  }
+  const checks = [];
+  let resolvedAddresses = [];
+
+  if (publicScheme === 'https') {
+    await record(checks, 'tls-validation-enabled', 'Node.js 未关闭 TLS 证书校验', () => {
+      if (environment.NODE_TLS_REJECT_UNAUTHORIZED === '0') {
+        throw new Error('NODE_TLS_REJECT_UNAUTHORIZED=0 会使公网证书验收失真');
+      }
+      return 'enabled';
+    });
+  }
+
+  if (publicScheme === 'https' && isIP(publicHost) === 0) {
+    await record(checks, 'dns-resolution', '公网域名可以解析', async () => {
+      resolvedAddresses = [...new Set(await resolveAddresses(publicHost))];
+      if (resolvedAddresses.length === 0) throw new Error('域名没有 A/AAAA 解析结果');
+      if (resolvedAddresses.length > 16) throw new Error('域名解析地址超过 16 个，拒绝无界探测');
+      if (resolvedAddresses.some((address) => isIP(address) === 0)) {
+        throw new Error('DNS 解析器返回了无效 IP 地址');
+      }
+      return resolvedAddresses;
+    });
+  } else {
+    resolvedAddresses = [publicHost];
+  }
+
+  if (publicScheme === 'https') {
+    await record(checks, 'http-redirect', '公网 HTTP 强制跳转到同域 HTTPS', async () => {
+      const response = await fetchWithTimeout(fetchImpl, `http://${publicHost}/api/health`, {
+        redirect: 'manual',
+      });
+      const location = response.headers.get('location');
+      if (![301, 302, 307, 308].includes(response.status)) {
+        throw new Error(`预期重定向，实际 HTTP ${response.status}`);
+      }
+      if (!location?.startsWith(`https://${publicHost}/`)) {
+        throw new Error('重定向目标不是同域 HTTPS');
+      }
+      return { status: response.status, location };
+    });
+  }
+
+  await record(
+    checks,
+    publicScheme === 'https' ? 'public-https-health' : 'public-http-health',
+    publicScheme === 'https'
+      ? '公网 HTTPS、证书和健康接口有效'
+      : '公网 HTTP 健康接口有效（传输未加密）',
+    async () => {
+      const response = await fetchWithTimeout(
+        fetchImpl,
+        `${publicScheme}://${publicHost}/api/health`,
+      );
+      const body = await readJson(response);
+      if (!response.ok || body?.ok !== true || body.data?.status !== 'ready') {
+        throw new Error(`公网健康接口异常：HTTP ${response.status}`);
+      }
+      return { status: response.status, application: body.data.status };
+    },
+  );
+
+  await record(checks, 'public-session-config', '公网管理员会话配置有效', async () => {
+    const response = await fetchWithTimeout(
+      fetchImpl,
+      `${publicScheme}://${publicHost}/api/session/config`,
+    );
+    const body = await readJson(response);
+    if (
+      !response.ok ||
+      body?.ok !== true ||
+      body.data?.mode !== 'admin' ||
+      typeof body.data.initialized !== 'boolean'
+    ) {
+      throw new Error(`管理员会话配置异常：HTTP ${response.status}`);
+    }
+    return {
+      status: response.status,
+      mode: body.data.mode,
+      initialized: body.data.initialized,
+    };
+  });
+
+  const targets = origin ? [origin] : resolvedAddresses;
+  for (const port of protectedPorts) {
+    await record(
+      checks,
+      `protected-port-${port}`,
+      `内部端口 ${port} 无法从验收网络建立 TCP 连接`,
+      async () => {
+        if (targets.length === 0) throw new Error('没有可探测的目标地址');
+        const outcomes = await Promise.all(
+          targets.map(async (target) => ({ target, ...(await probePort(target, port)) })),
+        );
+        const exposed = outcomes.find((outcome) => outcome.connected);
+        if (exposed) throw new Error(`${exposed.target}:${port} 可以从外部连接`);
+        return outcomes;
+      },
+    );
+  }
+
+  const failed = checks.filter((check) => check.status === 'fail').length;
+  return {
+    command: 'verify-external',
+    domain: publicHost,
+    publicHost,
+    publicScheme,
+    probeTargets: targets,
+    originOverride: origin ?? null,
+    checkedAt: new Date(now).toISOString(),
+    passed: failed === 0,
+    summary: { total: checks.length, passed: checks.length - failed, failed },
+    checks,
+    boundary:
+      '结果只覆盖运行本命令的当前网络到 probeTargets 的可达性；若域名经过 CDN/代理，请用 --origin 指定 ECS 公网 IP 再验收。',
+  };
+}
+
+function isValidEndpoint(publicHost, publicScheme) {
+  if (publicScheme === 'https') return isPublicDomain(publicHost) || isIP(publicHost) === 4;
+  return publicScheme === 'http' && isIP(publicHost) === 4;
+}
+
+async function defaultResolveAddresses(domain) {
+  const records = await lookup(domain, { all: true, verbatim: true });
+  return records.map((record) => record.address);
+}
+
+function defaultProbePort(host, port) {
+  return new Promise((resolvePromise) => {
+    const socket = net.createConnection({ host, port });
+    let settled = false;
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      socket.destroy();
+      resolvePromise(result);
+    };
+    socket.setTimeout(4_000);
+    socket.once('connect', () => finish({ connected: true, outcome: 'connected' }));
+    socket.once('timeout', () => finish({ connected: false, outcome: 'timeout' }));
+    socket.once('error', (error) =>
+      finish({
+        connected: false,
+        outcome: typeof error?.code === 'string' ? error.code : 'connection_error',
+      }),
+    );
+  });
+}
+
+async function fetchWithTimeout(fetchImpl, url, options = {}) {
+  return fetchImpl(url, {
+    ...options,
+    signal: AbortSignal.timeout(10_000),
+  });
+}
+
+async function readJson(response) {
+  const text = await response.text();
+  if (text.length > 64 * 1024) throw new Error('验收接口响应超过 64 KiB');
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new Error('验收接口未返回有效 JSON');
+  }
+}
+
+async function record(checks, id, description, operation) {
+  try {
+    const evidence = await operation();
+    checks.push({ id, description, status: 'pass', evidence });
+  } catch (error) {
+    checks.push({
+      id,
+      description,
+      status: 'fail',
+      error: safeError(error),
+    });
+  }
+}
+
+function isPublicDomain(domain) {
+  return (
+    typeof domain === 'string' &&
+    domain.length <= 253 &&
+    domain.includes('.') &&
+    /^[a-z0-9.-]+$/.test(domain) &&
+    !domain
+      .split('.')
+      .some(
+        (label) => !label || label.length > 63 || label.startsWith('-') || label.endsWith('-'),
+      ) &&
+    !/^\d+(?:\.\d+){3}$/.test(domain)
+  );
+}
+
+function safeError(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  return message.replace(/[\r\n]+/g, ' ').slice(0, 500);
+}

package/cli/ip-certificate.mjs

@@ -0,0 +1,331 @@
+import { randomUUID } from 'node:crypto';
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from 'node:fs';
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
+
+export const minimumCertbotVersion = Object.freeze({ major: 5, minor: 4, patch: 0 });
+export const ipCertificateAutomationPaths = Object.freeze({
+  webroot: '/var/lib/chat-hub/acme-webroot',
+  deployHook: '/usr/local/libexec/chat-hub-cert-renew-hook',
+  renewRunner: '/usr/local/libexec/chat-hub-cert-renew-runner',
+  service: '/etc/systemd/system/chat-hub-cert-renew.service',
+  timer: '/etc/systemd/system/chat-hub-cert-renew.timer',
+  result: '/var/lib/chat-hub/certificate-renewal.json',
+  publishedDirectory: '/etc/caddy/chat-hub-ip-tls',
+  publishedReleases: '/etc/caddy/chat-hub-ip-tls/releases',
+  publishedCurrent: '/etc/caddy/chat-hub-ip-tls/current',
+  publishedFullchain: '/etc/caddy/chat-hub-ip-tls/current/fullchain.pem',
+  publishedPrivateKey: '/etc/caddy/chat-hub-ip-tls/current/privkey.pem',
+});
+
+export function certbotVersionSupported(output) {
+  const match = String(output).match(/certbot\s+(\d+)\.(\d+)\.(\d+)/i);
+  if (!match) return false;
+  const current = match.slice(1).map(Number);
+  const minimum = Object.values(minimumCertbotVersion);
+  return (
+    current.some((value, index) => value > minimum[index]) ||
+    current.every((value, index) => value === minimum[index])
+  );
+}
+
+export function ipCertificatePaths(publicIp) {
+  assertPublicIpText(publicIp);
+  const lineage = `/etc/letsencrypt/live/${publicIp}`;
+  return {
+    lineage,
+    fullchain: `${lineage}/fullchain.pem`,
+    privateKey: `${lineage}/privkey.pem`,
+  };
+}
+
+export function certbotIssueArguments({ publicIp, email, staging = false }) {
+  assertPublicIpText(publicIp);
+  if (typeof email !== 'string' || !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
+    throw new Error('IP HTTPS 必须提供有效的证书到期联系邮箱');
+  }
+  return [
+    'certonly',
+    '--non-interactive',
+    '--agree-tos',
+    '--email',
+    email,
+    '--preferred-profile',
+    'shortlived',
+    '--webroot',
+    '--webroot-path',
+    ipCertificateAutomationPaths.webroot,
+    '--ip-address',
+    publicIp,
+    '--cert-name',
+    publicIp,
+    ...(staging ? ['--staging'] : []),
+  ];
+}
+
+export function ipCertificateChallengeCaddySite(publicIp) {
+  assertPublicIpText(publicIp);
+  return `http://${publicIp} {
+  handle /.well-known/acme-challenge/* {
+    root * ${ipCertificateAutomationPaths.webroot}
+    file_server
+  }
+  handle {
+    respond "Chat Hub HTTPS certificate is being prepared" 503
+  }
+  header -Server
+}
+`;
+}
+
+export function ipHttpsCaddySite(publicIp) {
+  return `http://${publicIp} {
+  handle /.well-known/acme-challenge/* {
+    root * ${ipCertificateAutomationPaths.webroot}
+    file_server
+  }
+  handle {
+    redir https://${publicIp}{uri} permanent
+  }
+  header -Server
+}
+
+https://${publicIp} {
+  tls ${ipCertificateAutomationPaths.publishedFullchain} ${ipCertificateAutomationPaths.publishedPrivateKey}
+  encode zstd gzip
+  reverse_proxy 127.0.0.1:8080 {
+    header_up Host {host}
+    header_up X-Forwarded-Proto https
+    header_up X-Forwarded-For {remote_host}
+  }
+  header {
+    -Server
+    X-Content-Type-Options nosniff
+    Referrer-Policy no-referrer
+    X-Frame-Options DENY
+  }
+}
+`;
+}
+
+export function stageIpCertificateChallenge({
+  publicIp,
+  rootDirectory = '/',
+  caddyfile = '/etc/caddy/Caddyfile',
+  caddySnippet = '/etc/caddy/chat-hub.caddy',
+}) {
+  assertPublicIpText(publicIp);
+  const outputPath = (path) => rootedPath(rootDirectory, path);
+  mkdirSync(outputPath(ipCertificateAutomationPaths.webroot), { recursive: true, mode: 0o755 });
+  mkdirSync(
+    outputPath(join(ipCertificateAutomationPaths.webroot, '.well-known', 'acme-challenge')),
+    { recursive: true, mode: 0o755 },
+  );
+  mkdirSync(dirname(outputPath(caddyfile)), { recursive: true, mode: 0o755 });
+  const importLine = `import ${caddySnippet}`;
+  const existingCaddyfile = existsSync(outputPath(caddyfile))
+    ? readFileSync(outputPath(caddyfile), 'utf8')
+    : '';
+  const nextCaddyfile = existingCaddyfile.split(/\r?\n/).some((line) => line.trim() === importLine)
+    ? existingCaddyfile
+    : `${existingCaddyfile}${existingCaddyfile && !existingCaddyfile.endsWith('\n') ? '\n' : ''}${importLine}\n`;
+  return stageFiles(
+    new Map([
+      [caddyfile, { content: nextCaddyfile, mode: 0o644 }],
+      [caddySnippet, { content: ipCertificateChallengeCaddySite(publicIp), mode: 0o644 }],
+    ]),
+    outputPath,
+  );
+}
+
+export function stageIpCertificateAutomation({
+  publicIp,
+  certbotPath,
+  caddyPath,
+  installPath,
+  nodePath,
+  rootDirectory = '/',
+}) {
+  assertPublicIpText(publicIp);
+  if (
+    [certbotPath, caddyPath, installPath, nodePath].some(
+      (path) => !isAbsolute(path) || /[\r\n\0]/.test(path),
+    )
+  ) {
+    throw new Error('证书工具路径必须是安全的绝对路径');
+  }
+  const outputPath = (path) => rootedPath(rootDirectory, path);
+  const certificate = ipCertificatePaths(publicIp);
+  for (const directory of [
+    dirname(ipCertificateAutomationPaths.deployHook),
+    dirname(ipCertificateAutomationPaths.service),
+    ipCertificateAutomationPaths.webroot,
+  ]) {
+    mkdirSync(outputPath(directory), { recursive: true, mode: 0o755 });
+  }
+  const hook = `#!/bin/sh
+set -eu
+${shellQuote(installPath)} -d -o root -g caddy -m 0750 ${shellQuote(ipCertificateAutomationPaths.publishedDirectory)}
+${shellQuote(installPath)} -d -o root -g caddy -m 0750 ${shellQuote(ipCertificateAutomationPaths.publishedReleases)}
+release_name="$(/usr/bin/date -u +%Y%m%dT%H%M%SZ).$$"
+release_dir=${shellQuote(ipCertificateAutomationPaths.publishedReleases)}/"$release_name"
+current_link=${shellQuote(ipCertificateAutomationPaths.publishedCurrent)}
+next_link="$current_link.next.$$"
+restore_link="$current_link.restore.$$"
+previous_target=""
+if [ -L "$current_link" ]; then
+  previous_target="$(/usr/bin/readlink "$current_link")"
+fi
+restore_current() {
+  if [ -n "$previous_target" ]; then
+    /usr/bin/ln -s "$previous_target" "$restore_link"
+    /usr/bin/mv -Tf "$restore_link" "$current_link"
+  else
+    /usr/bin/rm -f "$current_link"
+  fi
+}
+${shellQuote(installPath)} -d -o root -g caddy -m 0750 "$release_dir"
+${shellQuote(installPath)} -o root -g caddy -m 0640 ${shellQuote(certificate.fullchain)} "$release_dir/fullchain.pem"
+${shellQuote(installPath)} -o root -g caddy -m 0640 ${shellQuote(certificate.privateKey)} "$release_dir/privkey.pem"
+/usr/bin/ln -s "releases/$release_name" "$next_link"
+/usr/bin/mv -Tf "$next_link" "$current_link"
+if ! ${shellQuote(caddyPath)} validate --config /etc/caddy/Caddyfile --adapter caddyfile; then
+  restore_current
+  exit 1
+fi
+if ! /usr/bin/systemctl reload caddy.service; then
+  restore_current
+  /usr/bin/systemctl reload caddy.service || true
+  exit 1
+fi
+`;
+  const renewRunner = `#!/bin/sh
+set -eu
+status=failed
+write_result() {
+  ${shellQuote(nodePath)} -e 'const fs=require("node:fs");const [path,status]=process.argv.slice(1);const now=new Date().toISOString();const value=status==="running"?{status,startedAt:now}:{status,completedAt:now};const temporary=path+"."+process.pid+".tmp";fs.writeFileSync(temporary,JSON.stringify(value)+"\\n",{mode:0o600});fs.renameSync(temporary,path)' ${shellQuote(ipCertificateAutomationPaths.result)} "$1"
+}
+on_exit() {
+  exit_code=$?
+  trap - EXIT
+  if [ "$status" != succeeded ]; then
+    write_result failed || true
+  fi
+  exit "$exit_code"
+}
+trap on_exit EXIT
+write_result running
+${shellQuote(certbotPath)} renew --cert-name ${publicIp} --quiet --deploy-hook ${shellQuote(ipCertificateAutomationPaths.deployHook)}
+status=succeeded
+write_result succeeded
+trap - EXIT
+`;
+  const service = `[Unit]
+Description=Renew Chat Hub short-lived IP certificate
+After=network-online.target caddy.service
+Wants=network-online.target
+
+[Service]
+Type=oneshot
+ExecStart=${ipCertificateAutomationPaths.renewRunner}
+PrivateTmp=true
+ProtectHome=true
+ProtectSystem=full
+ReadWritePaths=/etc/letsencrypt ${ipCertificateAutomationPaths.webroot} /var/lib/chat-hub ${ipCertificateAutomationPaths.publishedDirectory}
+`;
+  const timer = `[Unit]
+Description=Renew Chat Hub short-lived IP certificate regularly
+
+[Timer]
+OnBootSec=15m
+OnUnitActiveSec=4h
+RandomizedDelaySec=15m
+Persistent=true
+Unit=chat-hub-cert-renew.service
+
+[Install]
+WantedBy=timers.target
+`;
+  return stageFiles(
+    new Map([
+      [ipCertificateAutomationPaths.deployHook, { content: hook, mode: 0o755 }],
+      [ipCertificateAutomationPaths.renewRunner, { content: renewRunner, mode: 0o755 }],
+      [ipCertificateAutomationPaths.service, { content: service, mode: 0o644 }],
+      [ipCertificateAutomationPaths.timer, { content: timer, mode: 0o644 }],
+    ]),
+    outputPath,
+  );
+}
+
+function stageFiles(files, outputPath) {
+  const previous = new Map();
+  try {
+    for (const [absolutePath, artifact] of files) {
+      const target = outputPath(absolutePath);
+      mkdirSync(dirname(target), { recursive: true, mode: 0o755 });
+      previous.set(
+        absolutePath,
+        existsSync(target)
+          ? { existed: true, content: readFileSync(target), mode: statSync(target).mode & 0o777 }
+          : { existed: false },
+      );
+      writeAtomic(target, artifact.content, artifact.mode);
+    }
+  } catch (error) {
+    restoreFiles(previous, outputPath);
+    throw error;
+  }
+  return {
+    outputPaths: [...files.keys()].map(outputPath),
+    rollback: () => restoreFiles(previous, outputPath),
+  };
+}
+
+function writeAtomic(path, content, mode) {
+  const temporary = `${path}.${randomUUID()}.tmp`;
+  writeFileSync(temporary, content, { mode });
+  chmodSync(temporary, mode);
+  renameSync(temporary, path);
+}
+
+function restoreFiles(previous, outputPath) {
+  for (const [absolutePath, state] of [...previous.entries()].reverse()) {
+    const target = outputPath(absolutePath);
+    if (!state.existed) {
+      if (existsSync(target)) unlinkSync(target);
+      continue;
+    }
+    writeFileSync(target, state.content, { mode: state.mode });
+    chmodSync(target, state.mode);
+  }
+}
+
+function rootedPath(rootDirectory, absolutePath) {
+  const root = resolve(rootDirectory);
+  if (!isAbsolute(rootDirectory) || !isAbsolute(absolutePath))
+    throw new Error('证书路径必须是绝对路径');
+  if (root === resolve('/')) return absolutePath;
+  const target = resolve(root, absolutePath.replace(/^[/\\]+/, ''));
+  const pathFromRoot = relative(root, target);
+  if (pathFromRoot.startsWith('..') || isAbsolute(pathFromRoot))
+    throw new Error('证书目标越出测试根目录');
+  return target;
+}
+
+function assertPublicIpText(value) {
+  if (typeof value !== 'string' || !/^\d{1,3}(?:\.\d{1,3}){3}$/.test(value)) {
+    throw new Error('IP 证书只接受已校验的公网 IPv4');
+  }
+}
+
+function shellQuote(value) {
+  return `'${String(value).replaceAll("'", `'"'"'`)}'`;
+}