dsh-zen-remote 2.2.9 → 2.3.1

package/src/wizard/status.ts

@@ -0,0 +1,180 @@
+/**
+ * Wizard status projection (GW-1): declared ingress config + observed
+ * runtime facts → one sanitized JSON shape the browser may see.
+ *
+ * This module is the SECURITY BOUNDARY for everything the wizard surfaces
+ * on `GET /_dsh/zen-remote/admin/wizard/status`. The two properties it must
+ * hold, regardless of what the callers hand it:
+ *
+ *   1. No secret material. The Cloudflare API token and the cloudflared
+ *      tunnel token never enter this module — the runtime side reports only
+ *      `*Configured` booleans (the files live 0600 under
+ *      `<DSH_HOME>/zen-remote-ingress/`, and their contents stay there).
+ *   2. No file paths. The runtime side knows where binaries, token files
+ *      and the Caddyfile live; the projection carries none of it — every
+ *      output field is built from a whitelist below, and input objects are
+ *      never spread through.
+ *
+ * Pure logic on purpose: zero imports, so the check scripts and the tests
+ * can drive it through Node's strip-only type stripping, and the wizard
+ * routes can call it per request without re-resolving anything.
+ *
+ * Every input is coerced defensively. The declared side normally arrives
+ * from `resolveConfig(...).values` (already legal), but the projection is
+ * also the last line of defense for the wire: an off-enum mode answers
+ * `'off'`, a junk port answers the 443 default, a non-string domain answers
+ * `''` — same transparency discipline as the config resolver, applied at
+ * the rendering edge.
+ */
+
+/** The ingress modes `resolveConfig` can legally produce. */
+export const WIZARD_INGRESS_MODES = ['off', 'caddy', 'external', 'cloudflared'] as const
+
+export type WizardIngressMode = (typeof WIZARD_INGRESS_MODES)[number]
+
+/**
+ * The declared slice of the resolved config. Loose (`unknown`) on purpose:
+ * the projection is what guarantees the wire shape, not the caller's typing.
+ */
+export interface WizardDeclaredInput {
+  ingressMode?: unknown
+  ingressDomain?: unknown
+  ingressHttpsPort?: unknown
+  ingressPublicUrl?: unknown
+}
+
+/**
+ * One probe / verification memory the wizard back-end keeps. Only these
+ * three fields are recognized; everything else on the record (URLs probed,
+ * error details, headers) is dropped at the boundary.
+ */
+export interface WizardRecordInput {
+  result?: unknown
+  deviceId?: unknown
+  at?: unknown
+}
+
+/**
+ * The gateway's own detection of an untrusted reverse proxy (GW-5): the
+ * socket peer of the last request that carried proxy headers from an IP
+ * outside `trustedProxies` — almost certainly the user's own proxy, and
+ * the one IP the trust-proxy flow offers to add. Whitelist-projected like
+ * everything else.
+ */
+export interface WizardForwardedSourceInput {
+  ip?: unknown
+  at?: unknown
+}
+
+/**
+ * Runtime facts the wizard back-end observes live. Everything is optional —
+ * a composition that has not started any ingress process simply omits the
+ * fields. Token presence is reported as booleans only; port as the gateway
+ * child's ACTUAL listening port (it may differ from the configured one).
+ */
+export interface WizardRuntimeInput {
+  cfTokenConfigured?: unknown
+  tunnelTokenConfigured?: unknown
+  caddyRunning?: unknown
+  cloudflaredRunning?: unknown
+  gatewayActualPort?: unknown
+  lanAddress?: unknown
+  lastHostProbe?: WizardRecordInput | null
+  lastExternalVerification?: WizardRecordInput | null
+  lastForwardedSource?: WizardForwardedSourceInput | null
+}
+
+/** One projected probe / verification memory, or null when there is none. */
+export interface WizardStatusRecord {
+  result: string
+  deviceId: string | null
+  at: number | null
+}
+
+/** One projected untrusted-proxy detection, or null when none is pending. */
+export interface WizardStatusForwardedSource {
+  ip: string
+  at: number
+}
+
+/** The full sanitized status the wizard status route answers with. */
+export interface WizardStatus {
+  ok: true
+  mode: WizardIngressMode
+  domain: string
+  httpsPort: number
+  publicUrl: string
+  cfTokenConfigured: boolean
+  tunnelTokenConfigured: boolean
+  caddyRunning: boolean
+  cloudflaredRunning: boolean
+  gatewayActualPort: number | null
+  lanAddress?: string
+  lastHostProbe: WizardStatusRecord | null
+  lastExternalVerification: WizardStatusRecord | null
+  lastForwardedSource: WizardStatusForwardedSource | null
+}
+
+function modeOf(value: unknown): WizardIngressMode {
+  return typeof value === 'string' && (WIZARD_INGRESS_MODES as readonly string[]).includes(value)
+    ? (value as WizardIngressMode)
+    : 'off'
+}
+
+function stringOf(value: unknown): string {
+  return typeof value === 'string' ? value : ''
+}
+
+function portOf(value: unknown): number | null {
+  return typeof value === 'number' && Number.isInteger(value) && value >= 1 && value <= 65535 ? value : null
+}
+
+/**
+ * Project one probe / verification memory down to its three wire fields.
+ * A record without a string `result` is not a memory — it answers null, so
+ * a corrupt runtime entry can never render as a half-valid verdict.
+ */
+function recordOf(input: WizardRecordInput | null | undefined): WizardStatusRecord | null {
+  if (input === null || input === undefined || typeof input !== 'object') return null
+  const { result, deviceId, at } = input
+  if (typeof result !== 'string' || result === '') return null
+  return {
+    result,
+    deviceId: typeof deviceId === 'string' && deviceId !== '' ? deviceId : null,
+    at: typeof at === 'number' && Number.isFinite(at) ? at : null,
+  }
+}
+
+/** Project one untrusted-proxy detection down to its two wire fields. */
+function forwardedSourceOf(input: WizardForwardedSourceInput | null | undefined): WizardStatusForwardedSource | null {
+  if (input === null || input === undefined || typeof input !== 'object') return null
+  const { ip, at } = input
+  if (typeof ip !== 'string' || ip === '') return null
+  if (typeof at !== 'number' || !Number.isFinite(at)) return null
+  return { ip, at }
+}
+
+/**
+ * Build the sanitized wizard status. Both arguments are optional so a
+ * composition can answer before anything is configured; the all-empty
+ * answer is the honest "wizard not started" state (`mode: 'off'`, no ports,
+ * no tokens configured, no memories).
+ */
+export function projectWizardStatus(declared: WizardDeclaredInput = {}, runtime: WizardRuntimeInput = {}): WizardStatus {
+  return {
+    ok: true,
+    mode: modeOf(declared.ingressMode),
+    domain: stringOf(declared.ingressDomain),
+    httpsPort: portOf(declared.ingressHttpsPort) ?? 443,
+    publicUrl: stringOf(declared.ingressPublicUrl),
+    cfTokenConfigured: runtime.cfTokenConfigured === true,
+    tunnelTokenConfigured: runtime.tunnelTokenConfigured === true,
+    caddyRunning: runtime.caddyRunning === true,
+    cloudflaredRunning: runtime.cloudflaredRunning === true,
+    gatewayActualPort: portOf(runtime.gatewayActualPort),
+    ...(typeof runtime.lanAddress === 'string' && runtime.lanAddress !== '' ? { lanAddress: runtime.lanAddress } : {}),
+    lastHostProbe: recordOf(runtime.lastHostProbe),
+    lastExternalVerification: recordOf(runtime.lastExternalVerification),
+    lastForwardedSource: forwardedSourceOf(runtime.lastForwardedSource),
+  }
+}

package/src/wizard/token-store.ts

@@ -0,0 +1,73 @@
+/**
+ * Wizard token storage (GW-13a): the secrets that must never enter the
+ * plugin row or any wire response live as 0600 files under
+ * `<DSH_HOME>/zen-remote-ingress/`, written through a temp-file rename so
+ * a crash mid-write can never leave a half token at the real path. The
+ * tunnel-token half lives in cloudflared.ts (it is the cloudflared
+ * process's own input); this module owns the shared Cloudflare API token.
+ *
+ * Reads answer presence or hand the raw string ONLY to in-process callers
+ * (the Caddy manager's env) — nothing here is ever logged or serialized
+ * into a response.
+ */
+
+import { mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { ingressDir } from './binary.js'
+
+/** `<DSH_HOME>/zen-remote-ingress/cf-api-token`. */
+export function cfTokenPath(dshHome: string): string {
+  return join(ingressDir(dshHome), 'cf-api-token')
+}
+
+/** Atomic 0600 write (temp sibling + rename), with a direct-write fallback
+ * on Windows if an existing file or antivirus scan refuses `renameSync` with
+ * EPERM/EACCES. */
+export function writeCfTokenFile(dshHome: string, token: string): string {
+  const finalPath = cfTokenPath(dshHome)
+  const partPath = `${finalPath}.part`
+  try {
+    mkdirSync(ingressDir(dshHome), { recursive: true })
+    writeFileSync(partPath, token, { mode: 0o600 })
+    try {
+      renameSync(partPath, finalPath)
+    } catch {
+      writeFileSync(finalPath, token, { mode: 0o600 })
+      rmSync(partPath, { force: true })
+    }
+  } catch (error) {
+    rmSync(partPath, { force: true })
+    throw error
+  }
+  return finalPath
+}
+
+/** The stored token, or undefined when absent/empty. Callers feed it to the
+ * Caddy manager's environment; it must never reach a response or a log. */
+export function readCfTokenFile(dshHome: string): string | undefined {
+  try {
+    const token = readRaw(dshHome)
+    return token.trim() === '' ? undefined : token
+  } catch {
+    return undefined
+  }
+}
+
+/** Whether a non-empty token file exists (the projection's boolean only). */
+export function cfTokenConfigured(dshHome: string): boolean {
+  try {
+    return statSync(cfTokenPath(dshHome)).isFile() && readRaw(dshHome).trim() !== ''
+  } catch {
+    return false
+  }
+}
+
+/** Delete the stored token (the DELETE route; callers stop the processes
+ * that consume it first). */
+export function deleteCfTokenFile(dshHome: string): void {
+  rmSync(cfTokenPath(dshHome), { force: true })
+}
+
+function readRaw(dshHome: string): string {
+  return readFileSync(cfTokenPath(dshHome), 'utf8')
+}

package/src/wizard/tunnel-orchestrator.ts

@@ -0,0 +1,197 @@
+/**
+ * Tunnel orchestration (GW-13b, 路 C's autopilot): one call drives the
+ * whole Cloudflare-side setup the design promises — zone/account lookup
+ * (through the ancestor-chain check), tunnel create-or-adopt, ingress
+ * configuration against the gateway's ACTUAL port, the proxied CNAME,
+ * and the cloudflared child.
+ *
+ * Rules the review and the design pin down:
+ *
+ *   - **已有同名隧道**：the first setup pass answers `tunnel-conflict`
+ *     with the same-name list; the UI lets the user pick one and re-runs
+ *     with `tunnelId`, which adopts the existing tunnel through the token
+ *     endpoint instead of creating anything.
+ *   - **模式切换**：starting the tunnel stops the managed Caddy first
+ *     (`stopCaddy`) — never two ingress processes at once.
+ *   - The connector token travels from the Cloudflare answer into the
+ *     0600 token file and the child's `--token-file`; it never reaches a
+ *     response or a log.
+ *   - Every failure is a VALUE with a stable `reason` the UI maps to
+ *     locale copy; CloudflareError codes map losslessly (`cf-*` → the
+ *     orchestration's own reasons), unknown ones degrade to `api`.
+ */
+
+import { hostOf } from '../config.js'
+import { createCloudflareApi, type CloudflareApi, type CloudflareTunnelSummary } from './cloudflare.js'
+import { writeTunnelTokenFile } from './cloudflared.js'
+
+/** The tunnel name the wizard mints and looks for. */
+export const TUNNEL_NAME = 'dsh-zen-remote'
+
+export interface TunnelOrchestratorOptions {
+  dshHome: string
+  /** The stored Cloudflare token (token-store); absent → `no-token`. */
+  readToken: () => string | undefined
+  /** The gateway's ACTUAL port (the ingress service target); may probe
+   * asynchronously (the wiring re-reads /lan-gate/status per setup). */
+  gatewayPort: () => number | Promise<number>
+  /** The client factory; injectable so the tests drive the orchestration
+   * against a scripted CloudflareApi without any HTTP. Defaults to
+   * createCloudflareApi over the injected fetch. */
+  apiFactory?: (token: string) => CloudflareApi
+  cloudflared: {
+    start: (input: { tunnelToken: string }) => Promise<{ ok: true } | { ok: false; error: string }>
+    /** 模式切换：starting the tunnel stops the managed Caddy first. */
+    stopCaddy: () => void
+  }
+  fetchImpl?: typeof fetch
+}
+
+export interface TunnelSetupInput {
+  /** The public domain (bare hostname; may be a subdomain of the zone). */
+  domain: string
+  /** Adopt this existing tunnel instead of creating one (the conflict path). */
+  tunnelId?: string
+}
+
+export type TunnelSetupResult =
+  | { ok: true; tunnelId: string; publicUrl: string; tokenFile: string }
+  | {
+    ok: false
+    reason: 'no-token' | 'bad-domain' | 'zone-not-found' | 'tunnel-conflict' | 'dns-conflict' | 'auth' | 'network' | 'api' | 'spawn-failed'
+    detail?: string
+    /** The same-name tunnels, for `tunnel-conflict`. */
+    existing?: CloudflareTunnelSummary[]
+    /** The manual-install page, for `spawn-failed`. */
+    installUrl?: string
+  }
+
+/** CloudflareError.code → the orchestration's reason vocabulary. */
+function mapCloudflareError(error: unknown): TunnelSetupResult & { ok: false } {
+  if (error !== null && typeof error === 'object' && 'code' in error) {
+    const code = (error as { code?: unknown }).code
+    const detail = (error as { message?: unknown }).message
+    if (code === 'cf-auth-failed') return { ok: false, reason: 'auth', detail: String(detail ?? '') }
+    if (code === 'cf-network') return { ok: false, reason: 'network', detail: String(detail ?? '') }
+    if (code === 'cf-zone-not-found') return { ok: false, reason: 'zone-not-found' }
+  }
+  return { ok: false, reason: 'api', detail: String((error as Error)?.message ?? error) }
+}
+
+/**
+ * Drive the whole tunnel setup. Throws nothing — every outcome is a value.
+ */
+export async function setupTunnel(options: TunnelOrchestratorOptions, input: TunnelSetupInput): Promise<TunnelSetupResult> {
+  const token = options.readToken()
+  if (token === undefined || token.trim() === '') return { ok: false, reason: 'no-token' }
+  const host = hostOf(input.domain)
+  if (host === undefined) return { ok: false, reason: 'bad-domain' }
+
+  const api: CloudflareApi = options.apiFactory !== undefined
+    ? options.apiFactory(token)
+    : createCloudflareApi({ token, fetchImpl: options.fetchImpl })
+
+  // Zone + account: the ancestor-chain check answers both in one verdict.
+  let zoneId: string
+  let accountId: string
+  try {
+    const check = await api.checkDomainOnCloudflare(host)
+    if (!check.onCloudflare || check.zoneId === null || check.accountId === null) {
+      return { ok: false, reason: 'zone-not-found' }
+    }
+    zoneId = check.zoneId
+    accountId = check.accountId
+  } catch (error) {
+    return mapCloudflareError(error)
+  }
+
+  // Tunnel: adopt the user's choice, or create a fresh one — but a fresh
+  // create refuses when same-name tunnels already exist (the UI offers the
+  // list; the re-run carries `tunnelId`).
+  let tunnelId: string
+  let tunnelToken: string
+  try {
+    if (input.tunnelId !== undefined && input.tunnelId !== '') {
+      tunnelId = input.tunnelId
+      tunnelToken = await api.getTunnelToken(accountId, tunnelId)
+    } else {
+      const existing = await api.listTunnels(accountId)
+      const sameName = existing.filter((tunnel) => tunnel.name === TUNNEL_NAME)
+      if (sameName.length > 0) return { ok: false, reason: 'tunnel-conflict', existing: sameName }
+      const created = await api.createTunnel(accountId, TUNNEL_NAME)
+      tunnelId = created.id
+      tunnelToken = created.token
+    }
+  } catch (error) {
+    return mapCloudflareError(error)
+  }
+
+  const gatewayPort = await options.gatewayPort()
+
+  // The ingress mapping: the public hostname serves the local gateway.
+  try {
+    await api.configureIngress(accountId, tunnelId, host, `http://127.0.0.1:${gatewayPort}`)
+  } catch (error) {
+    return mapCloudflareError(error)
+  }
+
+  // DNS idempotence next (GW-fix-4/M3): an existing CNAME for this name
+  // pointing at the SAME tunnel is a no-op; pointing elsewhere is a real
+  // conflict we refuse instead of silently overwriting.
+  try {
+    const existing = await api.listDnsRecords(zoneId, host)
+    const prior = existing.find((record) => record.name === host)
+    if (prior !== undefined) {
+      const expected = `${tunnelId}.cfargotunnel.com`
+      if (prior.content !== expected) {
+        return { ok: false, reason: 'dns-conflict', detail: prior.content }
+      }
+    } else {
+      await api.createDnsRecord(zoneId, host, `${tunnelId}.cfargotunnel.com`)
+    }
+  } catch (error) {
+    return mapCloudflareError(error)
+  }
+
+  // L1: the Cloudflare half is DONE — only now stop the managed Caddy and
+  // start the tunnel, so a failed API call leaves the old path untouched.
+  options.cloudflared.stopCaddy()
+
+  // Connector secret → 0600 file → child.
+  let tokenFile: string
+  try {
+    tokenFile = writeTunnelTokenFile(options.dshHome, tunnelToken)
+  } catch (error) {
+    return { ok: false, reason: 'spawn-failed', detail: String((error as Error)?.message ?? error) }
+  }
+  const started = await options.cloudflared.start({ tunnelToken })
+  if (!started.ok) {
+    return { ok: false, reason: 'spawn-failed', detail: started.error }
+  }
+  return { ok: true, tunnelId, publicUrl: `https://${host}`, tokenFile }
+}
+
+/**
+ * The check-domain probe the migration card's 重新检查 drives: does any
+ * ancestor of the domain name a zone on the token's accounts?
+ */
+export type TunnelCheckResult =
+  | { ok: true; onCloudflare: boolean; zoneId: string | null; accountId: string | null }
+  | { ok: false; reason: 'no-token' | 'bad-domain' | 'auth' | 'network' | 'api'; detail?: string }
+
+export async function checkDomainOnCloudflare(options: Pick<TunnelOrchestratorOptions, 'readToken' | 'fetchImpl' | 'apiFactory'>, domain: string): Promise<TunnelCheckResult> {
+  const token = options.readToken()
+  if (token === undefined || token.trim() === '') return { ok: false, reason: 'no-token' }
+  const host = hostOf(domain)
+  if (host === undefined) return { ok: false, reason: 'bad-domain' }
+  const api: CloudflareApi = options.apiFactory !== undefined
+    ? options.apiFactory(token)
+    : createCloudflareApi({ token, fetchImpl: options.fetchImpl })
+  try {
+    const check = await api.checkDomainOnCloudflare(host)
+    return { ok: true, onCloudflare: check.onCloudflare, zoneId: check.zoneId, accountId: check.accountId }
+  } catch (error) {
+    const mapped = mapCloudflareError(error)
+    return { ok: false, reason: mapped.reason === 'auth' ? 'auth' : mapped.reason === 'network' ? 'network' : 'api', detail: mapped.detail }
+  }
+}

package/src/wizard/verify.ts

@@ -0,0 +1,236 @@
+/**
+ * Final-verification orchestration (GW-9): the wizard's last mile, where
+ * 「完成」 means a real phone really paired through the real public URL —
+ * never a green light from internal checks alone (设计: 不做已联通的假绿灯).
+ *
+ * The flow, spread over two entry points the UI drives:
+ *
+ *   start({ publicUrl }): runtime ready? → walk the public URL
+ *   (GW-8's probe; BOTH the pairing page and the admin-403 shape must be
+ *   right) → snapshot the gateway's device ids (the baseline) → mint a WEB
+ *   pairing code → remember the session IN MEMORY and answer with the
+ *   code, the URL and the expiry. The code never touches the row config,
+ *   and minting it restarts nothing — trustedProxies changes are what
+ *   restart the gateway, and any such change invalidates the session
+ *   instead (the config fingerprint below).
+ *
+ *   check(): re-read the gateway status. A device id the baseline did not
+ *   have is a freshly paired phone; the gateway's lastWebClaim record must
+ *   name THAT device with secure === true (the proxy passed
+ *   X-Forwarded-Proto: https through, so the issued cookie carries the
+ *   Secure flag). All green → pass. The claim recorded an insecure cookie →
+ *   cookie-insecure. Past the code's expiry → code-expired. Anything else →
+ *   pending, keep polling.
+ *
+ * The session binds to a CONFIG FINGERPRINT (ingressMode, domain,
+ * httpsPort, publicUrl, the gateway's ACTUAL port, host, trustedProxies):
+ * any of those moving between start and check answers stale and discards
+ * the session, because the verification proved a URL that no longer exists.
+ * The session is deliberately memory-only — a row reload (which a
+ * trustedProxies change causes) builds a fresh manager and the session is
+ * gone, exactly the same verdict the fingerprint would have produced.
+ */
+
+import type { ZenRemoteConfig } from '../config.js'
+import { normalizeServerUrl } from '../client-pairing.js'
+import { probeHostPath, type HostPathOutcome } from './probe.js'
+
+export interface VerificationManagerOptions {
+  /** Loopback base of the gateway child, `http://127.0.0.1:<port>`. */
+  gatewayBase: string
+  /** Fresh resolved config values per call (volatile discipline). */
+  getValues: () => ZenRemoteConfig
+  /** The hostPath probe; injectable for tests (defaults to GW-8's real one). */
+  probe?: (publicUrl: string) => Promise<HostPathOutcome>
+  /** Whether the ingress processes are alive (Caddy / cloudflared). The
+   * wiring supplies this once the process managers are mounted; absent
+   * means "checked elsewhere" and only the gateway is probed. */
+  runtimeReady?: () => boolean | Promise<boolean>
+  fetchImpl?: typeof fetch
+  /** Per-gateway-call ceiling. Default 5000 ms. */
+  timeoutMs?: number
+  /** Clock (tests drive expiry). */
+  now?: () => number
+}
+
+export type VerificationStartResult =
+  | { ok: true; pairingCode: string; publicUrl: string; expiresAt: number }
+  | {
+    ok: false
+    reason: 'no-public-url' | 'bad-public-url' | 'runtime-not-ready' | 'gateway-unreachable' | 'probe-failed' | 'pair-refused'
+    /** The probe's classifications for `probe-failed`; the gateway's status
+     * code for `pair-refused`; the normalize failure reason for
+     * `bad-public-url`. */
+    detail?: unknown
+  }
+
+export type VerificationCheckResult =
+  | { result: 'not-started' }
+  | { result: 'stale' }
+  | { result: 'code-expired' }
+  | { result: 'pending' }
+  | { result: 'cookie-insecure'; deviceId: string }
+  | { result: 'pass'; deviceId: string; at: number }
+
+/** What the wizard reads off one gateway status answer. */
+interface GatewayStatusView {
+  deviceIds: string[]
+  port: number | null
+  lastWebClaim: { id: string; secure: boolean; at: number } | null
+}
+
+/**
+ * The config fingerprint a session binds to: any drift between start and
+ * check means the verified URL is no longer the deployed URL.
+ */
+export function verificationFingerprint(values: ZenRemoteConfig, gatewayPort: number | null): string {
+  return JSON.stringify({
+    ingressMode: values.ingressMode,
+    ingressDomain: values.ingressDomain,
+    ingressHttpsPort: values.ingressHttpsPort,
+    ingressPublicUrl: values.ingressPublicUrl,
+    gatewayPort,
+    host: values.host,
+    trustedProxies: values.trustedProxies,
+  })
+}
+
+interface VerificationSession {
+  publicUrl: string
+  code: string
+  expiresAt: number
+  /** Device ids the gateway already had when the code was minted. */
+  knownDeviceIds: ReadonlySet<string>
+  fingerprint: string
+}
+
+export interface VerificationManager {
+  start(input: { publicUrl: unknown; probeOnly?: boolean }): Promise<VerificationStartResult>
+  check(): Promise<VerificationCheckResult>
+  /** Whether a verification session is open (the route surfaces it for the
+   * UI's 「待外部验证」 state). */
+  hasSession(): boolean
+}
+
+export function createVerificationManager(options: VerificationManagerOptions): VerificationManager {
+  const fetchImpl = options.fetchImpl ?? fetch
+  const timeoutMs = options.timeoutMs ?? 5000
+  const now = options.now ?? Date.now
+  let session: VerificationSession | null = null
+
+  /** One loopback gateway call AS the local machine. Answer status+body or
+   * null on any failure — every caller degrades, none throws. */
+  const callGateway = async (method: 'GET' | 'POST', path: string, payload?: unknown): Promise<{ status: number; body: unknown } | null> => {
+    try {
+      const response = await fetchImpl(`${options.gatewayBase}${path}`, {
+        method,
+        headers: payload === undefined ? undefined : { 'Content-Type': 'application/json' },
+        ...(payload === undefined ? {} : { body: JSON.stringify(payload) }),
+        signal: AbortSignal.timeout(timeoutMs),
+      })
+      const body: unknown = await response.json()
+      return { status: response.status, body }
+    } catch {
+      return null
+    }
+  }
+
+  const readStatus = async (): Promise<GatewayStatusView | null> => {
+    const reply = await callGateway('GET', '/lan-gate/status')
+    if (reply === null || reply.status < 200 || reply.status >= 300) return null
+    const body = reply.body as { devices?: unknown; port?: unknown; lastWebClaim?: unknown }
+    if (body === null || typeof body !== 'object') return null
+    const deviceIds: string[] = Array.isArray(body.devices)
+      ? body.devices.map((device) => (device !== null && typeof device === 'object' ? (device as { id?: unknown }).id : undefined))
+          .filter((id): id is string => typeof id === 'string')
+      : []
+    const port = typeof body.port === 'number' ? body.port : null
+    const claim = body.lastWebClaim
+    const lastWebClaim = claim !== null && typeof claim === 'object'
+      ? {
+          id: typeof (claim as { id?: unknown }).id === 'string' ? (claim as { id: string }).id : '',
+          secure: (claim as { secure?: unknown }).secure === true,
+          at: typeof (claim as { at?: unknown }).at === 'number' ? (claim as { at: number }).at : 0,
+        }
+      : null
+    return { deviceIds, port, lastWebClaim }
+  }
+
+  return {
+    async start({ publicUrl, probeOnly }) {
+      if (typeof publicUrl !== 'string' || publicUrl.trim() === '') return { ok: false, reason: 'no-public-url' }
+      // Same admission as the probe: https anywhere, plain http only into
+      // the private-network allowances. The URL the phone will open must
+      // be one this machine is willing to verify at all.
+      const normalized = normalizeServerUrl(publicUrl)
+      if (!normalized.ok) return { ok: false, reason: 'bad-public-url', detail: normalized.reason }
+
+      if ((await options.runtimeReady?.()) === false) return { ok: false, reason: 'runtime-not-ready' }
+
+      const statusBefore = await readStatus()
+      if (statusBefore === null) return { ok: false, reason: 'gateway-unreachable' }
+
+      const outcome = await (options.probe ?? probeHostPath)(normalized.url)
+      if (outcome.kind !== 'reached' || outcome.root !== 'gateway-pairing-page' || outcome.admin !== 'gateway-admin-403') {
+        return { ok: false, reason: 'probe-failed', detail: outcome }
+      }
+
+      if (probeOnly === true) {
+        return { ok: true, pairingCode: '', publicUrl: normalized.url, expiresAt: 0 }
+      }
+
+      const pair = await callGateway('POST', '/lan-gate/pair', { role: 'web' })
+      const pairBody = pair?.body as { ok?: unknown; code?: unknown; expiresAt?: unknown } | undefined
+      if (pair === null || pair.status < 200 || pair.status >= 300 || pairBody?.ok !== true || typeof pairBody.code !== 'string' || typeof pairBody.expiresAt !== 'number') {
+        return { ok: false, reason: 'pair-refused', detail: pair === null ? null : pair.status }
+      }
+
+      session = {
+        publicUrl: normalized.url,
+        code: pairBody.code,
+        expiresAt: pairBody.expiresAt,
+        knownDeviceIds: new Set(statusBefore.deviceIds),
+        fingerprint: verificationFingerprint(options.getValues(), statusBefore.port),
+      }
+      return { ok: true, pairingCode: session.code, publicUrl: session.publicUrl, expiresAt: session.expiresAt }
+    },
+
+    async check() {
+      if (session === null) return { result: 'not-started' }
+      const status = await readStatus()
+      if (status === null) return { result: 'pending' }
+      // The verified URL must still BE the deployed URL: a config or
+      // gateway-port drift discards the session outright.
+      if (verificationFingerprint(options.getValues(), status.port) !== session.fingerprint) {
+        session = null
+        return { result: 'stale' }
+      }
+      // New devices first, expiry second: the claim itself proves the code
+      // was still valid when it was redeemed, so a poll that lands moments
+      // past the expiry must not swallow a pass.
+      const newcomers = status.deviceIds.filter((id) => !session!.knownDeviceIds.has(id))
+      if (newcomers.length > 0) {
+        const deviceId = newcomers[newcomers.length - 1]
+        const claim = status.lastWebClaim
+        if (claim !== null && claim.id === deviceId) {
+          const isHttps = session.publicUrl.startsWith('https://')
+          session = null
+          // Plain http:// LAN/Tailscale pairing does not sit behind a TLS
+          // reverse proxy and intentionally issues a non-Secure cookie.
+          if (isHttps && !claim.secure) return { result: 'cookie-insecure', deviceId }
+          return { result: 'pass', deviceId, at: claim.at }
+        }
+        // A claim record that has not surfaced (or names a different,
+        // later claim): keep polling rather than bless an unverified cookie.
+        return { result: 'pending' }
+      }
+      if (now() >= session.expiresAt) {
+        session = null
+        return { result: 'code-expired' }
+      }
+      return { result: 'pending' }
+    },
+
+    hasSession: () => session !== null,
+  }
+}