dsh-zen-remote 2.3.11 → 2.4.1

package/src/state-store.ts

@@ -0,0 +1,428 @@
+/**
+ * The three-in-one state file (MS-1): `<DSH_HOME>/zen-remote-state.json`
+ * holds the server's own identity (`serverId`), the shared-session table
+ * (`sessions`) and the list of paired relay servers (`servers`) in ONE file,
+ * so the three writers — relay-server.ts's loadServerId, share-store.ts's
+ * persist, and the pairing operations below — can never clobber each other's
+ * top-level fields. Every write goes through {@link writeStateFile}, which
+ * reads the CURRENT file first and hands it to the updater: a share-table
+ * write preserves `serverId` and `servers`, an identity write preserves the
+ * table and the list.
+ *
+ * The file is 0600 on purpose: `servers` rows carry pairing tokens. The write
+ * is the same atomic tmp+rename dance the share table has always used, with
+ * an explicit chmod in front of the rename (writeFileSync's `mode` only
+ * applies at creation — a leftover `.tmp` from a crashed run would keep its
+ * old mode).
+ *
+ * Migration (MS-1): the pre-multi-server layout kept three separate files —
+ * `zen-remote-server.json` (the identity) and `zen-remote-shares.json` (the
+ * table) — and the plugin row carried the one paired server's address+token.
+ * {@link ensureStateMigrated} folds all three into the state file exactly
+ * once, deleting a legacy file only after its data landed on disk. The
+ * migration parts are also exported singly: relay-server.ts runs the identity
+ * one at its `loadServerId` entry and share-store.ts runs the table one at
+ * its startup load, so each writer is correct even when nothing else called
+ * the combined migration first.
+ *
+ * Pure module discipline: no clocks of its own (`Date.now` at the two call
+ * sites that need a timestamp), every read tolerant, nothing throws out of
+ * the migration helpers — a damaged file degrades to an empty state, never a
+ * dead plugin.
+ */
+
+import { randomBytes } from 'node:crypto'
+import { chmodSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { normalizeServerUrl } from './client-pairing.js'
+
+/** The one state file this module owns, always directly under DSH_HOME. */
+export const STATE_FILE_NAME = 'zen-remote-state.json'
+
+/** Pre-multi-server identity file, migrated into the state file and deleted. */
+export const LEGACY_SERVER_ID_FILE = 'zen-remote-server.json'
+
+/** Pre-multi-server share-table file, migrated into the state file and deleted. */
+export const LEGACY_SHARES_FILE = 'zen-remote-shares.json'
+
+/** How many relay servers one sub-client may keep paired at once (MS-2). */
+export const MAX_PAIRED_SERVERS = 8
+
+/** The 8-hex short server id shape (`randomBytes(4).toString('hex')`). */
+const SERVER_ID_PATTERN = /^[0-9a-f]{8}$/
+
+/** One row of the persisted share table (verbatim from share-store.ts). */
+export interface PersistedShareRow {
+  sharedAt: number
+  lastActivityAt: number
+}
+
+export interface PairedServerRecord {
+  /** Local stable entry id (8-hex, `randomBytes(4).toString('hex')`). */
+  id: string
+  /** The server address, normalized by `normalizeServerUrl`. */
+  serverUrl: string
+  /** The device pairing token — sensitive, 0600 on disk, NEVER echoed into
+   * any state response that leaves the process. */
+  token: string
+  /** The server's 8-hex id as of the last completed handshake; unset until
+   * the first one succeeds. */
+  serverId?: string
+  /** The server's display name as of the last completed handshake. */
+  serverName?: string
+  /** This device's id on that server, as the pairing registered it. */
+  deviceId?: string
+  /** This device's name in that server's table, as last confirmed. */
+  deviceName?: string
+  /** When the pairing was first added (epoch ms) — decides the merged
+   * sidebar order and the -1/-2 numbering of duplicate display names. */
+  createdAt: number
+}
+
+export interface ZenRemoteStateFile {
+  version: 1
+  serverId?: string
+  sessions?: Record<string, PersistedShareRow>
+  servers?: PairedServerRecord[]
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function isFiniteNumber(value: unknown): value is number {
+  return typeof value === 'number' && Number.isFinite(value)
+}
+
+/** The one legal shape of a persisted server id (relay-server.ts mints it). */
+export function isLegalServerId(value: unknown): value is string {
+  return typeof value === 'string' && SERVER_ID_PATTERN.test(value)
+}
+
+/**
+ * Read and parse the state file. A missing file is the normal first run; a
+ * damaged file reads as empty — quarantined as `<file>.corrupt-<now>` UNLESS
+ * it still carries a migration source (a legal `serverId`, the one shape the
+ * migration paths know how to rescue): renaming that away would silently
+ * reset the server identity on the next load, so the file stays put and the
+ * salvageable field rides along in the returned state.
+ * Never throws.
+ */
+export function readStateFile(filePath: string): ZenRemoteStateFile {
+  let raw: string | null = null
+  try {
+    raw = readFileSync(filePath, 'utf8')
+  } catch {
+    return { version: 1 }
+  }
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(raw)
+  } catch {
+    parsed = undefined
+  }
+  if (isPlainObject(parsed) && parsed.version === 1) {
+    const state: ZenRemoteStateFile = { version: 1 }
+    if (isLegalServerId(parsed.serverId)) state.serverId = parsed.serverId
+    // Row-level validity is each consumer's business (share-store validates
+    // rows, listPairedServers validates records) — a legal container with a
+    // bad field just drops the field here.
+    if (isPlainObject(parsed.sessions)) state.sessions = parsed.sessions as Record<string, PersistedShareRow>
+    if (Array.isArray(parsed.servers)) state.servers = parsed.servers as PairedServerRecord[]
+    return state
+  }
+  // Not a legal version:1 container. Salvage a bare legal serverId (the
+  // identity is the one thing a shape-less state file can still be carrying);
+  // anything else gets quarantined with its content preserved.
+  if (isPlainObject(parsed) && isLegalServerId(parsed.serverId)) {
+    return { version: 1, serverId: parsed.serverId }
+  }
+  try {
+    renameSync(filePath, `${filePath}.corrupt-${Date.now()}`)
+  } catch {
+    // Keep the empty state either way; startup must not fail here.
+  }
+  return { version: 1 }
+}
+
+/**
+ * The one write door: read the CURRENT file, let `updater` produce the next
+ * state from it, then atomically replace the file (tmp at 0600, best-effort
+ * chmod, rename). Belt AND braces: the braces are the updaters in this module
+ * spreading `current` explicitly; the belt is the merge below — an updater
+ * that names only the field it owns must never erase the top-level fields it
+ * did not name (the partial-updater shape caught in the MS-phase1 review). A
+ * field the updater explicitly sets to `undefined` still goes away, so
+ * removal stays expressible. The result is normalized to the four known
+ * top-level fields before it reaches disk. Throws on I/O failure; callers
+ * decide what that means (share-store records it, loadServerId degrades, the
+ * migration helpers swallow it).
+ */
+export function writeStateFile(filePath: string, updater: (current: ZenRemoteStateFile) => ZenRemoteStateFile): void {
+  const current = readStateFile(filePath)
+  const next = updater(current)
+  const safe: ZenRemoteStateFile = isPlainObject(next) ? (next as ZenRemoteStateFile) : { version: 1 }
+  const merged = { ...current, ...safe, version: 1 as const }
+  const out: ZenRemoteStateFile = { version: 1 }
+  if (isLegalServerId(merged.serverId)) out.serverId = merged.serverId
+  if (isPlainObject(merged.sessions)) out.sessions = merged.sessions
+  if (Array.isArray(merged.servers)) out.servers = merged.servers
+  mkdirSync(dirname(filePath), { recursive: true })
+  writeFileSync(`${filePath}.tmp`, JSON.stringify(out), { mode: 0o600 })
+  // writeFileSync's mode only applies at creation; a leftover tmp from a
+  // crashed run keeps its old mode, so the rename must not trust it.
+  try {
+    chmodSync(`${filePath}.tmp`, 0o600)
+  } catch {
+    // Best effort — the fresh-file mode above already covers the common path.
+  }
+  renameSync(`${filePath}.tmp`, filePath)
+}
+
+/**
+ * Move a legacy `zen-remote-server.json` identity into the state file — but
+ * only when the state file has no legal identity of its own yet. The legacy
+ * file is deleted only after the write succeeded; a failed write leaves both
+ * files alone so the next start can try again. Never throws.
+ */
+export function ensureServerIdMigrated(stateFile: string): void {
+  try {
+    const state = readStateFile(stateFile)
+    if (state.serverId !== undefined) return
+    const legacyFile = join(dirname(stateFile), LEGACY_SERVER_ID_FILE)
+    let legacyId: string | undefined
+    try {
+      const parsed: unknown = JSON.parse(readFileSync(legacyFile, 'utf8'))
+      const id = (parsed as { serverId?: unknown } | null)?.serverId
+      if (typeof id === 'string' && SERVER_ID_PATTERN.test(id)) legacyId = id
+    } catch {
+      return
+    }
+    if (legacyId === undefined) return
+    writeStateFile(stateFile, (current) => ({ ...current, version: 1, serverId: legacyId }))
+    try {
+      unlinkSync(legacyFile)
+    } catch {
+      // Already gone is fine — the data is in the state file now.
+    }
+  } catch {
+    // Best effort: an unwritable home keeps its legacy files for next time.
+  }
+}
+
+/** Share-store's row validity, mirrored here so migrated rows load cleanly. */
+const MAX_ID_LENGTH = 200
+
+/**
+ * Move a legacy `zen-remote-shares.json` table into the state file — but only
+ * when the state file carries no sessions yet. Legal rows only; the legacy
+ * file is deleted only after the write succeeded. Never throws.
+ */
+export function ensureSharesMigrated(stateFile: string): void {
+  try {
+    const state = readStateFile(stateFile)
+    if (state.sessions !== undefined) return
+    const legacyFile = join(dirname(stateFile), LEGACY_SHARES_FILE)
+    let rows: Record<string, PersistedShareRow> | undefined
+    try {
+      const parsed: unknown = JSON.parse(readFileSync(legacyFile, 'utf8'))
+      if (isPlainObject(parsed) && parsed.version === 1 && isPlainObject(parsed.sessions)) {
+        const out: Record<string, PersistedShareRow> = Object.create(null)
+        for (const [id, value] of Object.entries(parsed.sessions)) {
+          if (typeof id !== 'string' || id === '' || id.length > MAX_ID_LENGTH || !isPlainObject(value)) continue
+          const { sharedAt, lastActivityAt } = value
+          if (!isFiniteNumber(sharedAt) || !isFiniteNumber(lastActivityAt)) continue
+          out[id] = { sharedAt, lastActivityAt }
+        }
+        rows = out
+      }
+    } catch {
+      return
+    }
+    if (rows === undefined) return
+    writeStateFile(stateFile, (current) => ({ ...current, version: 1, sessions: rows }))
+    try {
+      unlinkSync(legacyFile)
+    } catch {
+      // Already gone is fine — the data is in the state file now.
+    }
+  } catch {
+    // Best effort: an unwritable home keeps its legacy files for next time.
+  }
+}
+
+function newPairedServerRecord(serverUrl: string, token: string, now?: number, deviceId?: string, deviceName?: string): PairedServerRecord {
+  return {
+    id: randomBytes(4).toString('hex'),
+    serverUrl,
+    token,
+    createdAt: now ?? Date.now(),
+    ...(deviceId !== undefined ? { deviceId } : {}),
+    ...(deviceName !== undefined ? { deviceName } : {}),
+  }
+}
+
+/** Validate one raw persisted record; anything hostile drops out of the list. */
+function normalizeRecord(value: unknown): PairedServerRecord | undefined {
+  if (!isPlainObject(value)) return undefined
+  const { id, serverUrl, token, createdAt } = value
+  if (typeof id !== 'string' || id === '' || id.length > 64) return undefined
+  if (typeof serverUrl !== 'string' || serverUrl === '') return undefined
+  if (typeof token !== 'string') return undefined
+  if (!isFiniteNumber(createdAt)) return undefined
+  const record: PairedServerRecord = { id, serverUrl, token, createdAt }
+  if (isLegalServerId(value.serverId)) record.serverId = value.serverId
+  if (typeof value.serverName === 'string' && value.serverName !== '') record.serverName = value.serverName
+  if (typeof value.deviceId === 'string' && value.deviceId !== '') record.deviceId = value.deviceId
+  if (typeof value.deviceName === 'string' && value.deviceName !== '') record.deviceName = value.deviceName
+  return record
+}
+
+/**
+ * The paired-servers list, in file (pairing) order, as validated copies.
+ * Invalid rows are skipped — one hostile record must not hide the rest.
+ */
+export function listPairedServers(filePath: string): PairedServerRecord[] {
+  const state = readStateFile(filePath)
+  if (!Array.isArray(state.servers)) return []
+  const records: PairedServerRecord[] = []
+  for (const value of state.servers) {
+    const record = normalizeRecord(value)
+    if (record !== undefined) records.push(record)
+  }
+  return records
+}
+
+/** What {@link upsertPairedServer} answers. */
+export type UpsertPairingResult =
+  | { ok: true; record: PairedServerRecord; replaced: boolean }
+  | { ok: false; code: 'invalid-url' | 'limit-reached' }
+
+/**
+ * Add or re-pair one server. A NEW address appends (refused past
+ * {@link MAX_PAIRED_SERVERS}); an EXISTING address updates in place — same
+ * entry id, same position, same `createdAt`, fresh token and device fields —
+ * which is why the cap never blocks a re-pair.
+ */
+export function upsertPairedServer(
+  filePath: string,
+  input: { serverUrl: string; token: string; deviceId?: string; deviceName?: string; now?: number },
+): UpsertPairingResult {
+  const normalized = normalizeServerUrl(input.serverUrl)
+  if (!normalized.ok) return { ok: false, code: 'invalid-url' }
+  const deviceId = typeof input.deviceId === 'string' && input.deviceId !== '' ? input.deviceId : undefined
+  const deviceName = typeof input.deviceName === 'string' && input.deviceName !== '' ? input.deviceName : undefined
+  const token = typeof input.token === 'string' ? input.token : ''
+  const records = listPairedServers(filePath)
+  const existingIndex = records.findIndex((record) => record.serverUrl === normalized.url)
+  if (existingIndex !== -1) {
+    const updated: PairedServerRecord = {
+      ...records[existingIndex],
+      token,
+      ...(deviceId !== undefined ? { deviceId } : {}),
+      ...(deviceName !== undefined ? { deviceName } : {}),
+    }
+    const nextServers = [...records]
+    nextServers[existingIndex] = updated
+    writeStateFile(filePath, (current) => ({ ...current, version: 1, servers: nextServers }))
+    return { ok: true, record: updated, replaced: true }
+  }
+  if (records.length >= MAX_PAIRED_SERVERS) return { ok: false, code: 'limit-reached' }
+  const created = newPairedServerRecord(normalized.url, token, input.now, deviceId, deviceName)
+  writeStateFile(filePath, (current) => ({ ...current, version: 1, servers: [...records, created] }))
+  return { ok: true, record: created, replaced: false }
+}
+
+/**
+ * Fold one completed handshake into the record: `serverId`, `serverName` and
+ * (when the server speaks it) `deviceName`. The second dedupe layer lives
+ * here too: a DIFFERENT entry already carrying the same `serverId` is a stale
+ * duplicate (the same server re-paired under a new address) — it is removed
+ * from the list and reported in `removedEntryIds`, the handshaking entry
+ * kept. A non-8-hex `serverId` is not recorded and dedupes nothing.
+ */
+export function recordServerHandshake(
+  filePath: string,
+  entryId: string,
+  handshake: { serverId: string; serverName: string; deviceName?: string },
+): { removedEntryIds: string[] } {
+  if (!isLegalServerId(handshake.serverId)) return { removedEntryIds: [] }
+  const records = listPairedServers(filePath)
+  if (!records.some((record) => record.id === entryId)) return { removedEntryIds: [] }
+  const removed: string[] = []
+  const nextServers: PairedServerRecord[] = []
+  for (const record of records) {
+    if (record.id === entryId) {
+      nextServers.push({
+        ...record,
+        serverId: handshake.serverId,
+        ...(typeof handshake.serverName === 'string' && handshake.serverName !== '' ? { serverName: handshake.serverName } : {}),
+        ...(typeof handshake.deviceName === 'string' && handshake.deviceName !== '' ? { deviceName: handshake.deviceName } : {}),
+      })
+      continue
+    }
+    if (record.serverId === handshake.serverId) {
+      removed.push(record.id)
+      continue
+    }
+    nextServers.push(record)
+  }
+  writeStateFile(filePath, (current) => ({ ...current, version: 1, servers: nextServers }))
+  return { removedEntryIds: removed }
+}
+
+/** Remove one entry by id; true when it was actually on the list. */
+export function removePairedServer(filePath: string, entryId: string): boolean {
+  const records = listPairedServers(filePath)
+  const next = records.filter((record) => record.id !== entryId)
+  if (next.length === records.length) return false
+  writeStateFile(filePath, (current) => ({ ...current, version: 1, servers: next }))
+  return true
+}
+
+/** Empty the list; answers how many records went away. */
+export function clearPairedServers(filePath: string): number {
+  const records = listPairedServers(filePath)
+  if (records.length === 0) return 0
+  writeStateFile(filePath, (current) => ({ ...current, version: 1, servers: [] }))
+  return records.length
+}
+
+/**
+ * The third migration: the pre-multi-server row carried exactly one server's
+ * address and pairing token. When the state file has no paired servers yet,
+ * they become `servers[0]`; the address must pass the claim route's
+ * normalizer and the token must be a non-empty string, or nothing is written.
+ * Runs at most once in practice — a non-empty list is never re-migrated.
+ */
+export function migrateLegacyClientIntoServers(
+  filePath: string,
+  legacyClient: { serverUrl?: unknown; deviceToken?: unknown },
+): void {
+  if (listPairedServers(filePath).length > 0) return
+  const serverUrl = typeof legacyClient?.serverUrl === 'string' ? legacyClient.serverUrl : undefined
+  const token = typeof legacyClient?.deviceToken === 'string' ? legacyClient.deviceToken : undefined
+  if (serverUrl === undefined || token === undefined || token.trim() === '') return
+  const normalized = normalizeServerUrl(serverUrl)
+  if (!normalized.ok) return
+  writeStateFile(filePath, (current) => ({ ...current, version: 1, servers: [newPairedServerRecord(normalized.url, token)] }))
+}
+
+/**
+ * The combined one-shot migration for a DSH home: identity, share table and
+ * (when handed the row's legacy client credentials) the paired-servers seed.
+ * Best effort end to end — any failure leaves the files as they are for the
+ * next start.
+ */
+export function ensureStateMigrated(home: string, legacyClient?: { serverUrl?: unknown; deviceToken?: unknown }): void {
+  const stateFile = join(home, STATE_FILE_NAME)
+  ensureServerIdMigrated(stateFile)
+  ensureSharesMigrated(stateFile)
+  if (legacyClient !== undefined) {
+    try {
+      migrateLegacyClientIntoServers(stateFile, legacyClient)
+    } catch {
+      // Best effort — the legacy row credentials stay where they are.
+    }
+  }
+}

package/src/upload-limits.ts

@@ -67,3 +67,19 @@ export const DEFAULT_MAX_UPLOAD_BYTES = 20 * 1024 * 1024
  * like any other oversized read.
  */
 export const MAX_INVOKE_BODY_BYTES = 32 * 1024 * 1024
+
+/**
+ * Cap for ONE forwarded `/api/file` media answer (P55-2): the sub-client's
+ * fetch-route wrap pulls a remote session's inline image / media file
+ * through `workspaceFiles/readBytes` and answers the browser's native
+ * `<img>` request with the bytes. Deliberately TIGHTER than the host's own
+ * `maxImageBytes` default (50 MiB, RT dsh-attachment-local
+ * DEFAULT_MAX_IMAGE_BYTES): every forwarded byte rides the relay's JSON
+ * channel base64-encoded (~1.33×), so 50 MiB would move ~67 MiB through the
+ * link — 20 MiB answers everything a reply body realistically embeds and
+ * fails fast past it. NOT related to {@link DEFAULT_MAX_UPLOAD_BYTES}
+ * (which sizes the phone composer's uploads); the equal value is
+ * coincidence, kept as one definition here only so the drift scanner sees
+ * every MiB-scale ceiling exactly once.
+ */
+export const MAX_FILE_MEDIA_BYTES = 20 * 1024 * 1024

package/src/virtual-id.ts

@@ -35,10 +35,67 @@ export const VIRTUAL_ID_PREFIX = 'zr~'
  */
 export const VIRTUAL_GROUP_NAME_MARK = '\u2060'
 
+/** MS-4: the two zero-width code points the serverId rides on inside a
+ * virtual group NAME — ZERO WIDTH SPACE encodes bit 0, ZERO WIDTH
+ * NON-JOINER bit 1. Invisible everywhere, and neither can appear in a
+ * server id's own visible text, so the window between the two marks is
+ * unambiguous. */
+const ZERO_BIT = '\u200b'
+const ONE_BIT = '\u200c'
+const SERVER_ID_BITS = 32
+
 /** The server id half: exactly the 8 lowercase hex chars relay-server.ts
  * mints (`randomBytes(4).toString('hex')`). */
 const SERVER_ID_PATTERN = /^[0-9a-f]{8}$/
 
+/**
+ * MS-4: the invisible prefix a REMOTE model-menu group heading carries
+ * before its server name (merge-streams.ts mergeModelCatalogs). The full
+ * form is `${MARK}${32 zero-width bits}${MARK}` — the 32 bits of the
+ * 8-hex serverId (MSB first per nibble), ZERO_BIT for 0 and ONE_BIT for 1
+ * — so the browser half can tell WHICH server a remote model group came
+ * from (effects/model-group-side.ts classifies per-server hiding from
+ * heading text alone). A serverId that is not 8 lowercase hex (the format
+ * every real handshake carries) degrades to the bare legacy mark: the
+ * heading stays a marked remote heading, just without a decodable server.
+ */
+export function encodeServerIdZeroWidth(serverId: unknown): string {
+  if (typeof serverId !== 'string' || !SERVER_ID_PATTERN.test(serverId)) return VIRTUAL_GROUP_NAME_MARK
+  let bits = ''
+  for (const nibble of serverId) {
+    for (const bit of Number.parseInt(nibble, 16).toString(2).padStart(4, '0')) {
+      bits += bit === '0' ? ZERO_BIT : ONE_BIT
+    }
+  }
+  return `${VIRTUAL_GROUP_NAME_MARK}${bits}${VIRTUAL_GROUP_NAME_MARK}`
+}
+
+/**
+ * MS-4: read the server id back out of one group heading, or `undefined`.
+ * Strict like every decoder here: the text must start with the mark, the
+ * window right after it must be exactly 32 zero-width bits closed by the
+ * terminator mark — anything else (the legacy bare-mark heading, visible
+ * text, a short or long bit run, a missing terminator) answers
+ * `undefined`, which the classifier reads as "remote, server unknown".
+ */
+export function decodeServerIdZeroWidth(headingText: unknown): string | undefined {
+  if (typeof headingText !== 'string' || !headingText.startsWith(VIRTUAL_GROUP_NAME_MARK)) return undefined
+  const rest = headingText.slice(VIRTUAL_GROUP_NAME_MARK.length)
+  if (rest.length < SERVER_ID_BITS + 1 || rest[SERVER_ID_BITS] !== VIRTUAL_GROUP_NAME_MARK) return undefined
+  let hex = ''
+  for (let i = 0; i < SERVER_ID_BITS; i += 4) {
+    let nibble = 0
+    for (let bit = 0; bit < 4; bit++) {
+      const bitChar = rest[i + bit]
+      if (bitChar === ZERO_BIT) nibble = nibble << 1
+      else if (bitChar === ONE_BIT) nibble = (nibble << 1) | 1
+      else return undefined
+    }
+    hex += nibble.toString(16)
+  }
+  return hex
+}
+
 /** The two halves {@link fromVirtual} recovers from a virtual id. */
 export interface VirtualIdParts {
   serverId: string

package/src/wizard/probe.ts

@@ -14,6 +14,8 @@
  * private-network allowances) and a 10 s ceiling per request.
  */
 
+import http from 'node:http'
+import https from 'node:https'
 import { normalizeServerUrl } from '../client-pairing.js'
 
 /** What answered on `GET <publicUrl>/`. */
@@ -106,11 +108,61 @@ export interface ProbeOptions {
  * 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 probeOnceDirect(
+  url: string,
+  timeoutMs: number,
+): Promise<{ status: number; contentType: string; body: string }> {
+  const parsed = new URL(url)
+  const mod = parsed.protocol === 'https:' ? https : http
+  return await new Promise((resolve, reject) => {
+    const req = mod.request(
+      parsed,
+      {
+        method: 'GET',
+        headers: { Accept: 'text/html' },
+        agent: false,
+      },
+      (res) => {
+        const chunks: Buffer[] = []
+        res.on('data', (chunk: Buffer | Uint8Array) => {
+          chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk))
+        })
+        res.on('end', () => {
+          clearTimeout(timer)
+          resolve({
+            status: res.statusCode ?? 0,
+            contentType: String(res.headers['content-type'] ?? ''),
+            body: Buffer.concat(chunks).toString('utf8'),
+          })
+        })
+        res.on('error', (err) => {
+          clearTimeout(timer)
+          reject(err)
+        })
+      },
+    )
+    const timer = setTimeout(() => {
+      const timeoutError = new Error('The operation was aborted due to timeout')
+      timeoutError.name = 'TimeoutError'
+      req.destroy(timeoutError)
+    }, timeoutMs)
+    if (typeof timer.unref === 'function') timer.unref()
+    req.on('error', (err) => {
+      clearTimeout(timer)
+      reject(err)
+    })
+    req.end()
+  })
+}
+
 async function probeOnce(
-  fetchImpl: typeof fetch,
+  fetchImpl: typeof fetch | undefined,
   url: string,
   timeoutMs: number,
 ): Promise<{ status: number; contentType: string; body: string }> {
+  if (fetchImpl === undefined) {
+    return await probeOnceDirect(url, timeoutMs)
+  }
   const response = await fetchImpl(url, {
     redirect: 'manual',
     signal: AbortSignal.timeout(timeoutMs),
@@ -136,7 +188,7 @@ export async function probeHostPath(publicUrl: unknown, options: ProbeOptions =
   if (!normalized.ok) {
     return { kind: 'unreachable', reason: normalized.reason === 'insecure-http' ? 'insecure-http' : 'invalid-url', ms: 0 }
   }
-  const fetchImpl = options.fetchImpl ?? fetch
+  const fetchImpl = options.fetchImpl
   const timeoutMs = options.timeoutMs ?? 10_000
   try {
     const [root, admin] = await Promise.all([

package/src/wizard/proxy-snippets.ts

@@ -26,6 +26,8 @@ export interface SnippetInput {
   upstreamHost: unknown
   /** The gateway's ACTUAL port. */
   upstreamPort: unknown
+  /** Language of the header comment (`'zh'` default, `'en'` English). */
+  lang?: 'zh' | 'en' | undefined
 }
 
 /** Integers in [1, 65535] only. */
@@ -56,8 +58,11 @@ export function nginxSnippet(input: SnippetInput): SnippetResult {
   const parts = validatedParts(input)
   if ('error' in parts) return parts.error
   const { domain, upstream, port } = parts
+  const headerComment = input.lang === 'en'
+    ? '# Place this in the http {} block (skip if you already have this map)'
+    : '# 这段放在 http {} 层（若已有同名 map 则跳过）'
   const text = [
-    '# 这段放在 http {} 层（若已有同名 map 则跳过）',
+    headerComment,
     'map $http_upgrade $connection_upgrade {',
     '    default upgrade;',
     "    ''      close;",
@@ -113,11 +118,21 @@ export type StepsResult =
  * flip the catch-all switch. Text only — Lucky has no config file format
  * to generate.
  */
-export function luckySteps(input: { upstreamHost: unknown; upstreamPort: unknown }): StepsResult {
+export function luckySteps(input: { upstreamHost: unknown; upstreamPort: unknown; lang?: 'zh' | 'en' | undefined }): 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' }
+  if (input.lang === 'en') {
+    return {
+      ok: true,
+      steps: [
+        'In Lucky "Web Service", create a new rule listening on port 443 and bind your domain.',
+        `Set the backend (reverse proxy target) to http://${upstream}:${port} and enable WebSocket support.`,
+        'Turn on the catch-all switch to allow all paths, then save.',
+      ],
+    }
+  }
   return {
     ok: true,
     steps: [