dsh-zen-remote 2.2.9 → 2.3.2

package/src/wizard/probe.ts

@@ -0,0 +1,161 @@
+/**
+ * hostPath probe (GW-8): the server machine walks its OWN public URL and
+ * classifies what answers, so the wizard can say something sharper than
+ * "it didn't work" — the pairing page showing up means TLS + proxying to
+ * the gateway both work; the admin surface answering 200 means the proxy
+ * is DROPPING the forwarded headers the gateway trusts; a redirect smells
+ * like Cloudflare Access or a proxy rewriting to a login page.
+ *
+ * Split exactly as the ticket asks: the two `classify*Response` functions
+ * are pure (the check scripts can drive them), `probeHostPath` owns the
+ * fetch I/O — `redirect: 'manual'` so a proxy's 3xx is SEEN, never
+ * followed — with the URL admission reusing client-pairing's
+ * `normalizeServerUrl` (https anywhere; plain http only for the explicit
+ * private-network allowances) and a 10 s ceiling per request.
+ */
+
+import { normalizeServerUrl } from '../client-pairing.js'
+
+/** What answered on `GET <publicUrl>/`. */
+export type RootClassification =
+  | 'gateway-pairing-page'
+  | 'unexpected-401'
+  | 'unexpected-200'
+  | 'redirect'
+  | 'unexpected'
+
+/** What answered on `GET <publicUrl>/lan-gate/admin`. */
+export type AdminClassification =
+  | 'gateway-admin-403'
+  | 'admin-exposed'
+  | 'proxy-403'
+  | 'unexpected'
+
+/**
+ * `GET /`: the ONE right answer is the gateway's pairing page — 401,
+ * text/html, carrying the claim-endpoint marker the page's own script
+ * posts to. A 200 means the URL belongs to something else entirely.
+ */
+export function classifyRootResponse(status: number, contentType: string, body: string): RootClassification {
+  if (status === 401) {
+    if (contentType.includes('text/html') && body.includes('/lan-gate/pair/claim')) return 'gateway-pairing-page'
+    return 'unexpected-401'
+  }
+  if (status >= 200 && status < 300) return 'unexpected-200'
+  if (status >= 300 && status < 400) return 'redirect'
+  return 'unexpected'
+}
+
+/**
+ * `GET /lan-gate/admin`: right is the gateway's own 403 JSON — a public
+ * visitor must not get in. 200 + HTML is the DANGEROUS shape: something
+ * answered with a page, meaning the proxy forwarded without the
+ * forwarded headers and the gateway's local-only wall never saw a
+ * proxied request (the admin page leaked). 403 + HTML smells like
+ * Cloudflare Access interposing its own login.
+ */
+export function classifyAdminResponse(status: number, contentType: string, body: string): AdminClassification {
+  const isHtml = contentType.includes('text/html')
+  if (status === 403) {
+    if (isHtml) return 'proxy-403'
+    if (contentType.includes('application/json')) {
+      try {
+        const parsed: unknown = JSON.parse(body)
+        if (parsed !== null && typeof parsed === 'object' && (parsed as { ok?: unknown }).ok === false) {
+          return 'gateway-admin-403'
+        }
+      } catch {
+        // JSON-shaped header with a non-JSON body: not our gateway's answer.
+      }
+    }
+    return 'unexpected'
+  }
+  if (status >= 200 && status < 300 && isHtml) return 'admin-exposed'
+  return 'unexpected'
+}
+
+export interface HostPathReached {
+  kind: 'reached'
+  root: RootClassification
+  admin: AdminClassification
+  /** Wall-clock cost of both requests, milliseconds. */
+  ms: number
+}
+
+export interface HostPathUnreachable {
+  kind: 'unreachable'
+  /** `invalid-url` / `insecure-http` — the URL never stood a chance;
+   * `timeout` — the 10 s ceiling fired; `network` — DNS, refused, reset. */
+  reason: 'invalid-url' | 'insecure-http' | 'timeout' | 'network'
+  detail?: string
+  ms: number
+}
+
+export type HostPathOutcome = HostPathReached | HostPathUnreachable
+
+export interface ProbeOptions {
+  fetchImpl?: typeof fetch
+  /** Per-request ceiling. Default 10 000 ms (the ticket's value). */
+  timeoutMs?: number
+  /** Clock for the `ms` measurement (tests). */
+  now?: () => number
+}
+
+/** One manual-redirect GET, classified. Sends a browser-shaped `Accept:
+ * text/html` (never `application/json`, which tells `lan-gate-server.cjs`
+ * the caller is an XHR/API client and makes `GET /` answer 401 JSON
+ * `{"ok":false,"reason":"unpaired"}` instead of the HTML pairing page;
+ * `/lan-gate/admin` answers 403 JSON regardless of `Accept`). */
+async function probeOnce(
+  fetchImpl: typeof fetch,
+  url: string,
+  timeoutMs: number,
+): Promise<{ status: number; contentType: string; body: string }> {
+  const response = await fetchImpl(url, {
+    redirect: 'manual',
+    signal: AbortSignal.timeout(timeoutMs),
+    headers: { Accept: 'text/html' },
+  })
+  const body = await response.text()
+  return { status: response.status, contentType: String(response.headers.get('content-type') ?? ''), body }
+}
+
+/**
+ * Probe the machine's public URL from here: both the root path and the
+ * admin surface, never following a redirect. The two requests run
+ * concurrently; the answer carries both classifications and the elapsed
+ * time. Every failure mode is a VALUE (`kind: 'unreachable'`), never a
+ * throw — the wizard routes render whichever verdict arrived.
+ */
+export async function probeHostPath(publicUrl: unknown, options: ProbeOptions = {}): Promise<HostPathOutcome> {
+  const started = (options.now ?? Date.now)()
+  const elapsed = () => (options.now ?? Date.now)() - started
+  // Same admission the client pairing uses: https anywhere, plain http
+  // only into the explicit private-network allowances.
+  const normalized = normalizeServerUrl(typeof publicUrl === 'string' ? publicUrl : '')
+  if (!normalized.ok) {
+    return { kind: 'unreachable', reason: normalized.reason === 'insecure-http' ? 'insecure-http' : 'invalid-url', ms: 0 }
+  }
+  const fetchImpl = options.fetchImpl ?? fetch
+  const timeoutMs = options.timeoutMs ?? 10_000
+  try {
+    const [root, admin] = await Promise.all([
+      probeOnce(fetchImpl, `${normalized.url}/`, timeoutMs),
+      probeOnce(fetchImpl, `${normalized.url}/lan-gate/admin`, timeoutMs),
+    ])
+    return {
+      kind: 'reached',
+      root: classifyRootResponse(root.status, root.contentType, root.body),
+      admin: classifyAdminResponse(admin.status, admin.contentType, admin.body),
+      ms: elapsed(),
+    }
+  } catch (error) {
+    const name = (error as Error)?.name
+    return {
+      kind: 'unreachable',
+      reason: name === 'TimeoutError' || name === 'AbortError' ? 'timeout' : 'network',
+      detail: String((error as Error)?.message ?? error),
+      ms: elapsed(),
+    }
+  }
+}

package/src/wizard/proxy-snippets.ts

@@ -0,0 +1,128 @@
+/**
+ * Reverse-proxy configuration snippets (GW-5, 路 B) — for the user who
+ * ALREADY runs their own proxy, the wizard hands out copy-paste material
+ * instead of managing a process. Everything here is pure text generation:
+ * every interpolated value passes a charset gate (the domain through
+ * config.ts's `hostOf`, the upstream host likewise, the port in [1,
+ * 65535]), so a hostile form value cannot smuggle a directive into
+ * anyone's nginx.
+ *
+ * The upstream port is the gateway's ACTUAL port — the caller reads it
+ * from the running gateway (it may have retried past the configured one),
+ * never from config.
+ */
+
+import { hostOf } from '../config.js'
+
+export type SnippetResult =
+  | { ok: true; text: string }
+  | { ok: false; error: 'bad-domain' | 'bad-upstream-host' | 'bad-upstream-port' }
+
+export interface SnippetInput {
+  /** Public domain the proxy terminates TLS for (bare hostname). */
+  domain: unknown
+  /** Where the gateway listens — a hostname or IP literal (e.g. the
+   * loopback default). */
+  upstreamHost: unknown
+  /** The gateway's ACTUAL port. */
+  upstreamPort: unknown
+}
+
+/** Integers in [1, 65535] only. */
+function portOf(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isInteger(value) && value >= 1 && value <= 65535 ? value : undefined
+}
+
+function validatedParts(input: SnippetInput): { domain: string; upstream: string; port: number } | { error: SnippetResult & { ok: false } } {
+  const domain = hostOf(input.domain)
+  if (domain === undefined) return { error: { ok: false, error: 'bad-domain' } }
+  const upstream = hostOf(input.upstreamHost)
+  if (upstream === undefined) return { error: { ok: false, error: 'bad-upstream-host' } }
+  const port = portOf(input.upstreamPort)
+  if (port === undefined) return { error: { ok: false, error: 'bad-upstream-port' } }
+  return { domain, upstream, port }
+}
+
+/**
+ * nginx: a complete server block. The WebSocket upgrade map sits outside
+ * the server (http-level context) — the snippet says so in a comment, the
+ * user pastes it into the http/server scope their setup offers. Long
+ * idle tunnels need the 3600s read/send timeouts, uploads the 128m
+ * client body cap, and streaming the buffering switch — all three are
+ * the shapes DSH's relay traffic actually needs.
+ */
+export function nginxSnippet(input: SnippetInput): SnippetResult {
+  const parts = validatedParts(input)
+  if ('error' in parts) return parts.error
+  const { domain, upstream, port } = parts
+  const text = [
+    '# 这段放在 http {} 层（若已有同名 map 则跳过）',
+    'map $http_upgrade $connection_upgrade {',
+    '    default upgrade;',
+    "    ''      close;",
+    '}',
+    '',
+    'server {',
+    '    listen 443 ssl;',
+    `    server_name ${domain};`,
+    '',
+    '    location / {',
+    `        proxy_pass http://${upstream}:${port};`,
+    '        proxy_http_version 1.1;',
+    '        proxy_set_header Upgrade $http_upgrade;',
+    '        proxy_set_header Connection $connection_upgrade;',
+    '        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_buffering off;',
+    '        client_max_body_size 128m;',
+    '        proxy_read_timeout 3600s;',
+    '        proxy_send_timeout 3600s;',
+    '    }',
+    '}',
+    '',
+  ].join('\n')
+  return { ok: true, text }
+}
+
+/**
+ * Caddy (user-operated, not the wizard-managed one): the site block is
+ * one `reverse_proxy` line — Caddy routes the rest itself.
+ */
+export function caddySnippet(input: SnippetInput): SnippetResult {
+  const parts = validatedParts(input)
+  if ('error' in parts) return parts.error
+  const { domain, upstream, port } = parts
+  const text = [
+    `${domain} {`,
+    `    reverse_proxy ${upstream}:${port}`,
+    '}',
+    '',
+  ].join('\n')
+  return { ok: true, text }
+}
+
+export type StepsResult =
+  | { ok: true; steps: string[] }
+  | { ok: false; error: 'bad-upstream-host' | 'bad-upstream-port' }
+
+/**
+ * Lucky (Web 服务反代) three steps: listen 443, proxy to the upstream,
+ * flip the catch-all switch. Text only — Lucky has no config file format
+ * to generate.
+ */
+export function luckySteps(input: { upstreamHost: unknown; upstreamPort: unknown }): StepsResult {
+  const upstream = hostOf(input.upstreamHost)
+  if (upstream === undefined) return { ok: false, error: 'bad-upstream-host' }
+  const port = portOf(input.upstreamPort)
+  if (port === undefined) return { ok: false, error: 'bad-upstream-port' }
+  return {
+    ok: true,
+    steps: [
+      '在 Lucky 的「Web 服务」里新建一条规则，监听 443 端口，绑定你的域名。',
+      `后端（反代目标）填 http://${upstream}:${port}，开启 WebSocket 支持。`,
+      '打开「万事大吉」开关（放行全部路径），保存即可生效。',
+    ],
+  }
+}