tunnel-mcp 0.1.2 → 0.1.4

package/CHANGELOG.md

@@ -11,6 +11,50 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Nothing yet.
 
+## [0.1.4] - 2026-07-01
+
+### Fixed
+
+- **Guests no longer fail to join with `getaddrinfo ENOTFOUND …trycloudflare.com`.**
+  Root cause: a cloudflared quick tunnel prints its URL ~8–25s before the
+  per-tunnel DNS record propagates, and the old host-side reachability probe
+  looked the name up immediately — seeding an `NXDOMAIN` that the resolver
+  negative-cached for up to 30 minutes (the zone's SOA minimum), breaking the
+  guest's join even after the tunnel went live. The probe was the cause, not a
+  diagnostic.
+
+### Changed
+
+- **`tunnel_open` now gates the join link on real DNS readiness via DoH.** After
+  cloudflared reports the URL, the host polls liveness over IP-literal DoH
+  endpoints (`1.1.1.1`/`1.0.0.1`/`8.8.8.8`) — which never touch, and so never
+  poison, the system resolver — and only returns the link once the record
+  resolves (best-effort: it never blocks or hard-fails; after a budget it returns
+  the link anyway).
+- **The guest resolves system-first with a DoH fallback**, connecting by the
+  resolved IP while keeping SNI/Host = the hostname, so a guest whose resolver
+  lags or holds a stale negative cache still connects.
+- **Guest connection is now time-bounded** (handshake + overall connect deadline),
+  so a black-hole link fails fast with a clear error instead of hanging.
+- The `0.1.3` `TUNNEL_REACHABILITY` (and `0.1.2` `TUNNEL_SKIP_REACHABILITY_CHECK`)
+  environment variables are **no longer read** — they only ever relaxed the
+  now-deleted probe. New single knob: `TUNNEL_DOH=off` disables DoH for networks
+  that block it and where system DNS already works.
+
+## [0.1.3] - 2026-07-01
+
+### Changed
+
+- **`tunnel_open` no longer hard-fails when the host can't reach
+  `*.trycloudflare.com`.** Because this is a cross-network tool, only the guest's
+  network has to reach the link — so a host-side reachability-probe failure
+  (blocked DNS, or a proxy Node's `fetch` ignores) now **opens the tunnel anyway
+  and returns a `reachabilityWarning`** by default, instead of blocking a tunnel
+  that would have worked for the guest. Behavior is configurable via
+  `TUNNEL_REACHABILITY`: `warn` (default), `strict` (previous hard-fail), or
+  `off` (skip the probe). This replaces the `TUNNEL_SKIP_REACHABILITY_CHECK` flag
+  from 0.1.2, which is still honored as `off` for backward compatibility.
+
 ## [0.1.2] - 2026-07-01
 
 ### Added
@@ -80,7 +124,9 @@ install-skill` copies the `tunnel-etiquette` skill into `~/.claude/skills`
   declaring a fix "confirmed".
 - Test suite of 109 tests built with vitest, developed test-first (TDD).
 
-[Unreleased]: https://github.com/zachlikefolio/tunnel-mcp/compare/v0.1.2...HEAD
+[Unreleased]: https://github.com/zachlikefolio/tunnel-mcp/compare/v0.1.4...HEAD
+[0.1.4]: https://github.com/zachlikefolio/tunnel-mcp/compare/v0.1.3...v0.1.4
+[0.1.3]: https://github.com/zachlikefolio/tunnel-mcp/compare/v0.1.2...v0.1.3
 [0.1.2]: https://github.com/zachlikefolio/tunnel-mcp/compare/v0.1.1...v0.1.2
 [0.1.1]: https://github.com/zachlikefolio/tunnel-mcp/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/zachlikefolio/tunnel-mcp/releases/tag/v0.1.0

package/README.md

@@ -162,7 +162,7 @@ vulnerability.
 
 ```bash
 npm ci                  # install dependencies
-npm test                # run the test suite (136 tests, TDD)
+npm test                # run the test suite (159 tests, TDD)
 npm run build           # compile TypeScript
 npm run lint            # eslint
 npm run format:check    # prettier --check .
@@ -178,15 +178,18 @@ an interactive CLI — with no arguments it starts and waits for an MCP client t
 connect over stdin/stdout. That's working as intended. Register it with a client
 (above), or run `tunnel-mcp --help`.
 
-**`tunnel_open` fails with "never became reachable" / can't resolve
-`*.trycloudflare.com`.** cloudflared reaches Cloudflare's edge over its own
-protocol, but the public `*.trycloudflare.com` hostname still has to resolve via
-normal DNS — and some networks (corporate/filtered networks, and a few public
-DNS resolvers) block `trycloudflare.com`. Both you **and your guest** need to be
-able to resolve it. Check with `dig +short <random>.trycloudflare.com` or
-`curl -sI https://<the-url>`. If only your guest's network needs to reach the
-URL, set `TUNNEL_SKIP_REACHABILITY_CHECK=1` to open the tunnel without the
-host-side reachability probe.
+**Guest join fails with `getaddrinfo ENOTFOUND …trycloudflare.com`.** A
+cloudflared quick tunnel prints its URL a few seconds _before_ the per-tunnel DNS
+record has propagated. If anything looks the name up too early it gets an
+`NXDOMAIN` that the resolver negative-caches for up to 30 minutes — breaking the
+join even after the tunnel is live. `tunnel-mcp` avoids this: `tunnel_open` waits
+for the record to actually resolve (via DoH to Cloudflare's `1.1.1.1`, an IP that
+never touches — and so never poisons — your system resolver) before returning the
+link, and the guest resolves system-first with a DoH fallback. So a fresh join
+should just work; if you hit `ENOTFOUND`, an _earlier_ attempt likely poisoned the
+cache — wait for it to expire, or flush DNS (`sudo dscacheutil -flushcache` on
+macOS). Set `TUNNEL_DOH=off` only on networks that block DoH (`1.1.1.1`) and where
+system DNS already resolves `*.trycloudflare.com`.
 
 ## Roadmap / not yet supported
 

package/dist/cli.js

@@ -60,10 +60,12 @@ export function helpText(version = readVersion()) {
         `  --force, -f      Overwrite an existing install`,
         ``,
         `Environment:`,
-        `  TUNNEL_SKILLS_DIR                 Override the skills directory`,
-        `  TUNNEL_SKIP_SKILL_INSTALL=1       Skip the automatic skill install on npm install`,
-        `  TUNNEL_SKIP_REACHABILITY_CHECK=1  Open a tunnel even if this machine can't reach`,
-        `                                    *.trycloudflare.com (your guest still must)`,
+        `  TUNNEL_SKILLS_DIR            Override the skills directory`,
+        `  TUNNEL_SKIP_SKILL_INSTALL=1  Skip the automatic skill install on npm install`,
+        `  TUNNEL_DOH=off              Disable DoH — used to confirm the tunnel hostname is`,
+        `                              live before sharing the link, and as the guest's`,
+        `                              resolver fallback. Only disable on networks that block`,
+        `                              DoH (1.1.1.1) and where system DNS already works.`,
         ``,
         `Docs: https://github.com/zachlikefolio/tunnel-mcp`,
     ].join('\n');

package/dist/cloudflared/tunnelProcess.d.ts

@@ -1,3 +1,4 @@
+import { DohResult } from '../net/doh.js';
 export interface TunnelHandle {
     publicUrl: string;
     stop(): void;
@@ -5,20 +6,25 @@ export interface TunnelHandle {
 export interface StartOptions {
     timeoutMs?: number;
     extraArgs?: string[];
-    attempts?: number;
-    intervalMs?: number;
-    healthCheck?: (url: string) => Promise<boolean>;
-    probeTimeoutMs?: number;
-    skipHealthCheck?: boolean;
+    budgetMs?: number;
+    pollIntervalMs?: number;
+    initialDelayMs?: number;
+    resolveHost?: (host: string) => Promise<DohResult>;
+    dohEnabled?: boolean;
 }
 export declare function parsePublicUrl(line: string): string | null;
-export declare function describeProbeError(e: unknown): string;
-export declare function defaultHealthCheck(url: string): Promise<boolean>;
-export declare function unreachableMessage(url: string, attempts: number, lastReason?: string): string;
 /**
- * `extraArgs` exists for tests: it lets a fake binary (e.g. `node fake.mjs`) be
- * launched in place of `cloudflared tunnel --url ...`. Production passes none.
- * The URL is surfaced only after a health probe confirms the edge is reachable
- * (cloudflared prints the hostname before routing is live).
+ * Spawn `cloudflared tunnel --url ...` and resolve with the public URL — but
+ * only after a readiness gate confirms the per-tunnel DNS record has propagated.
+ *
+ * cloudflared prints the URL ~8–25s before the record exists. Looking the name
+ * up via the system resolver during that window returns NXDOMAIN and gets it
+ * negative-cached (SOA min 1800s), breaking the guest's join for up to 30 min.
+ * So the gate polls DoH over IP-literal endpoints (which never touch the system
+ * resolver, so they cannot poison anything). It is best-effort: it never blocks
+ * on "not live yet" or "DoH unavailable" — after the budget it returns the link
+ * optimistically (the guest's own DoH fallback is the safety net).
+ *
+ * `extraArgs` exists for tests: it launches a fake binary in place of cloudflared.
  */
 export declare function startCloudflared(binPath: string, localPort: number, opts?: StartOptions): Promise<TunnelHandle>;

package/dist/cloudflared/tunnelProcess.js

@@ -1,130 +1,55 @@
 import { spawn } from 'node:child_process';
-import { CLOUDFLARED_URL_TIMEOUT_MS, CLOUDFLARED_HEALTH_ATTEMPTS, CLOUDFLARED_HEALTH_INTERVAL_MS, } from '../config.js';
+import { CLOUDFLARED_URL_TIMEOUT_MS, READINESS_GATE_BUDGET_MS, READINESS_INITIAL_DELAY_MS, READINESS_POLL_INTERVAL_MS, } from '../config.js';
+import { dohResolve } from '../net/doh.js';
+import { envFlag } from '../env.js';
 const URL_RE = /https:\/\/[a-z0-9-]+\.trycloudflare\.com/;
-// Bounds a single probe so a black-hole connection (or a caller-supplied
-// healthCheck that hangs/throws) can't stall the health-check loop forever.
-const DEFAULT_PROBE_TIMEOUT_MS = 5000;
+const delay = (ms) => new Promise((r) => setTimeout(r, ms));
 export function parsePublicUrl(line) {
     const m = line.match(URL_RE);
     return m ? m[0] : null;
 }
-// undici (Node's global fetch) reports the real network error on `.cause`, e.g.
-// a DNS failure surfaces as `cause.code === 'ENOTFOUND'`. Pull that out so the
-// caller can tell "DNS can't resolve the host" apart from "edge not ready yet".
-export function describeProbeError(e) {
-    const err = e;
-    const code = err?.cause?.code;
-    if (code)
-        return err.cause?.message ? `${code}: ${err.cause.message}` : code;
-    if (err?.name === 'TimeoutError')
-        return 'probe timed out';
-    return err?.message || 'unknown error';
-}
-// Any HTTP response (even 404/502/426) means the Cloudflare edge is routing to
-// us. A thrown error carries why it failed (DNS, TLS, refused, timeout).
-async function reachabilityProbe(url, probeTimeoutMs) {
-    try {
-        await fetch(url, { method: 'GET', signal: AbortSignal.timeout(probeTimeoutMs) });
-        return { ok: true };
-    }
-    catch (e) {
-        return { ok: false, reason: describeProbeError(e) };
-    }
-}
-// Back-compat boolean probe (kept for external callers/tests).
-export async function defaultHealthCheck(url) {
-    return (await reachabilityProbe(url, DEFAULT_PROBE_TIMEOUT_MS)).ok;
-}
-// Builds the actionable "never became reachable" error. Names the host and,
-// when the failure looks like DNS resolution, points at *.trycloudflare.com
-// blocking — the single most common real-world cause. Always mentions the
-// escape hatch, since the guest's network (not the host's) is what must reach
-// the URL for messaging.
-export function unreachableMessage(url, attempts, lastReason) {
-    let host = url;
-    try {
-        host = new URL(url).host;
-    }
-    catch {
-        /* keep the raw url */
-    }
-    const dnsish = !!lastReason && /ENOTFOUND|EAI_AGAIN|getaddrinfo|\bdns\b/i.test(lastReason);
-    let msg = `cloudflared reported ${url} but it never became reachable from this machine after ${attempts} probe(s)`;
-    if (lastReason)
-        msg += ` (last error: ${lastReason})`;
-    msg += '.';
-    if (dnsish) {
-        msg +=
-            ` This machine can't resolve ${host} — your DNS or network may be blocking *.trycloudflare.com` +
-                ` (common on filtered/corporate networks and some public DNS resolvers). You and your guest both` +
-                ` need to be able to resolve it.`;
-    }
-    msg += ` If you're confident your guest's network can reach the URL, set TUNNEL_SKIP_REACHABILITY_CHECK=1 to open the tunnel anyway.`;
-    return msg;
-}
-// Races a single probe against a per-attempt timeout so that a caller-supplied
-// `check` that throws, rejects, or simply never resolves can never leave the
-// loop (and therefore the outer startCloudflared promise) hanging.
-function probeOnce(url, probe, probeTimeoutMs) {
-    return new Promise((resolve) => {
-        let settled = false;
-        const finish = (r) => {
-            if (!settled) {
-                settled = true;
-                resolve(r);
-            }
-        };
-        const timer = setTimeout(() => finish({ ok: false, reason: 'probe timed out' }), probeTimeoutMs);
-        Promise.resolve()
-            .then(() => probe(url))
-            .then((r) => {
-            clearTimeout(timer);
-            finish(r);
-        })
-            .catch((err) => {
-            clearTimeout(timer);
-            finish({ ok: false, reason: describeProbeError(err) });
-        });
-    });
-}
-async function waitHealthy(url, attempts, intervalMs, probe, probeTimeoutMs) {
-    let lastReason;
-    for (let i = 0; i < attempts; i++) {
-        const r = await probeOnce(url, probe, probeTimeoutMs);
-        if (r.ok)
-            return r;
-        lastReason = r.reason;
-        await new Promise((res) => setTimeout(res, intervalMs));
-    }
-    return { ok: false, reason: lastReason };
+function dohOn(explicit) {
+    return explicit ?? (process.env.TUNNEL_DOH === undefined || envFlag('TUNNEL_DOH'));
 }
 /**
- * `extraArgs` exists for tests: it lets a fake binary (e.g. `node fake.mjs`) be
- * launched in place of `cloudflared tunnel --url ...`. Production passes none.
- * The URL is surfaced only after a health probe confirms the edge is reachable
- * (cloudflared prints the hostname before routing is live).
+ * Spawn `cloudflared tunnel --url ...` and resolve with the public URL — but
+ * only after a readiness gate confirms the per-tunnel DNS record has propagated.
+ *
+ * cloudflared prints the URL ~8–25s before the record exists. Looking the name
+ * up via the system resolver during that window returns NXDOMAIN and gets it
+ * negative-cached (SOA min 1800s), breaking the guest's join for up to 30 min.
+ * So the gate polls DoH over IP-literal endpoints (which never touch the system
+ * resolver, so they cannot poison anything). It is best-effort: it never blocks
+ * on "not live yet" or "DoH unavailable" — after the budget it returns the link
+ * optimistically (the guest's own DoH fallback is the safety net).
+ *
+ * `extraArgs` exists for tests: it launches a fake binary in place of cloudflared.
  */
 export function startCloudflared(binPath, localPort, opts = {}) {
     const args = opts.extraArgs ?? ['tunnel', '--url', `http://localhost:${localPort}`];
     const timeoutMs = opts.timeoutMs ?? CLOUDFLARED_URL_TIMEOUT_MS;
-    const attempts = opts.attempts ?? CLOUDFLARED_HEALTH_ATTEMPTS;
-    const intervalMs = opts.intervalMs ?? CLOUDFLARED_HEALTH_INTERVAL_MS;
-    const probeTimeoutMs = opts.probeTimeoutMs ?? DEFAULT_PROBE_TIMEOUT_MS;
-    // A caller-supplied boolean healthCheck carries no failure reason; the default
-    // probe does. Adapt the former into a ProbeResult either way.
-    const custom = opts.healthCheck;
-    const probe = custom
-        ? async (u) => ({ ok: await custom(u) })
-        : (u) => reachabilityProbe(u, probeTimeoutMs);
+    const budgetMs = opts.budgetMs ?? READINESS_GATE_BUDGET_MS;
+    const pollIntervalMs = opts.pollIntervalMs ?? READINESS_POLL_INTERVAL_MS;
+    const initialDelayMs = opts.initialDelayMs ?? READINESS_INITIAL_DELAY_MS;
+    const resolveHost = opts.resolveHost ?? ((h) => dohResolve(h, 4));
+    const dohEnabled = dohOn(opts.dohEnabled);
     return new Promise((resolve, reject) => {
         const child = spawn(binPath, args, { stdio: ['ignore', 'pipe', 'pipe'] });
         let settled = false;
+        let gateStarted = false;
+        let exited = false;
         const stop = () => {
             try {
                 child.kill('SIGTERM');
             }
             catch {
-                /* gone */
+                /* already gone */
+            }
+        };
+        const succeed = (url) => {
+            if (!settled) {
+                settled = true;
+                resolve({ publicUrl: url, stop });
             }
         };
         const fail = (err) => {
@@ -136,36 +61,42 @@ export function startCloudflared(binPath, localPort, opts = {}) {
             }
         };
         const timer = setTimeout(() => fail(new Error('cloudflared did not report a URL in time')), timeoutMs);
+        const runGate = async (url, host) => {
+            if (!dohEnabled) {
+                await delay(pollIntervalMs); // brief settle; the guest's DoH fallback covers readiness
+                succeed(url);
+                return;
+            }
+            await delay(initialDelayMs);
+            const deadline = Date.now() + budgetMs;
+            while (!settled && !exited && Date.now() < deadline) {
+                const res = await resolveHost(host).catch(() => ({ klass: 'INDETERMINATE', addresses: [] }));
+                if (res.klass === 'RESOLVED') {
+                    succeed(url);
+                    return;
+                }
+                await delay(pollIntervalMs);
+            }
+            if (settled)
+                return;
+            if (exited) {
+                fail(new Error('cloudflared exited during readiness wait'));
+                return;
+            }
+            // Budget exhausted without a RESOLVED — hand out the link optimistically.
+            // No system-DNS lookup ever happened, so nothing was poisoned, and the
+            // guest resolves the name itself (system-first, DoH fallback).
+            succeed(url);
+        };
         const onData = (buf) => {
+            if (gateStarted)
+                return;
             for (const line of buf.toString().split('\n')) {
                 const url = parsePublicUrl(line);
-                if (url && !settled) {
-                    settled = true;
+                if (url) {
+                    gateStarted = true;
                     clearTimeout(timer);
-                    // Escape hatch: the reachability probe runs on the *host*, but only the
-                    // guest's network must reach the URL for messaging. A host on a filtered
-                    // network can opt to skip the probe and hand out the link regardless.
-                    if (opts.skipHealthCheck) {
-                        resolve({ publicUrl: url, stop });
-                        return;
-                    }
-                    waitHealthy(url, attempts, intervalMs, probe, probeTimeoutMs)
-                        .then((res) => {
-                        if (res.ok)
-                            resolve({ publicUrl: url, stop });
-                        else {
-                            stop();
-                            reject(new Error(unreachableMessage(url, attempts, res.reason)));
-                        }
-                    })
-                        .catch((err) => {
-                        // Should be unreachable (waitHealthy/probeOnce never reject), but
-                        // this guarantees the child is never orphaned and the outer
-                        // promise always settles, even on a future bug or surprise throw.
-                        stop();
-                        const reason = err instanceof Error ? err.message : String(err);
-                        reject(new Error(`cloudflared health check failed unexpectedly: ${reason}`));
-                    });
+                    void runGate(url, new URL(url).host);
                     return;
                 }
             }
@@ -173,6 +104,9 @@ export function startCloudflared(binPath, localPort, opts = {}) {
         child.stdout?.on('data', onData);
         child.stderr?.on('data', onData);
         child.on('error', (err) => fail(err));
-        child.on('exit', (code) => fail(new Error(`cloudflared exited (${code})`)));
+        child.on('exit', (code) => {
+            exited = true;
+            fail(new Error(`cloudflared exited (${code})`));
+        });
     });
 }

package/dist/config.d.ts

@@ -1,3 +1,4 @@
+import type { DohProvider } from './net/doh.js';
 export declare const TUNNEL_HOME: string;
 export declare const BIN_DIR: string;
 export declare const SESSIONS_DIR: string;
@@ -5,6 +6,14 @@ export declare const DEFAULT_LISTEN_TIMEOUT_MS = 60000;
 export declare const DEFAULT_IDLE_TEARDOWN_MS: number;
 export declare const DEFAULT_JOIN_LINK_TTL_MS: number;
 export declare const CLOUDFLARED_URL_TIMEOUT_MS = 30000;
-export declare const CLOUDFLARED_HEALTH_ATTEMPTS = 10;
-export declare const CLOUDFLARED_HEALTH_INTERVAL_MS = 1000;
 export declare const OPEN_RETRY_ATTEMPTS = 3;
+export declare const READINESS_GATE_BUDGET_MS = 60000;
+export declare const READINESS_INITIAL_DELAY_MS = 5000;
+export declare const READINESS_POLL_INTERVAL_MS = 1000;
+export declare const DOH_REQUEST_TIMEOUT_MS = 3000;
+export declare const DOH_PROVIDERS: DohProvider[];
+export declare const GUEST_HANDSHAKE_TIMEOUT_MS = 15000;
+export declare const GUEST_CONNECT_DEADLINE_MS = 20000;
+export declare const GUEST_SYS_LOOKUP_TIMEOUT_MS = 2000;
+export declare const DOH_GUEST_RETRIES = 3;
+export declare const DOH_GUEST_RETRY_DELAY_MS = 700;

package/dist/config.js

@@ -8,8 +8,41 @@ export const DEFAULT_IDLE_TEARDOWN_MS = 30 * 60_000;
 // Join links are single-use and expire after this window; a leaked link that
 // is never used (or is reused after the guest joined) can't admit anyone.
 export const DEFAULT_JOIN_LINK_TTL_MS = 10 * 60_000;
-// cloudflared startup robustness
+// cloudflared startup
 export const CLOUDFLARED_URL_TIMEOUT_MS = 30_000; // wait for the URL line
-export const CLOUDFLARED_HEALTH_ATTEMPTS = 10; // edge-reachability probes
-export const CLOUDFLARED_HEALTH_INTERVAL_MS = 1_000; // delay between probes
 export const OPEN_RETRY_ATTEMPTS = 3; // re-spawn attempts in session.open
+// Host readiness gate. cloudflared prints the quick-tunnel URL before the
+// per-tunnel DNS record has propagated (~8–25s). Any early lookup of the name
+// via the system resolver would be NXDOMAIN and get negative-cached for the
+// zone's SOA minimum (1800s), breaking the guest's join for up to 30 minutes.
+// So we confirm liveness via DoH to IP-literal endpoints (which never touch the
+// system resolver) before handing out the link.
+export const READINESS_GATE_BUDGET_MS = 60_000; // total wait for the record to go live
+export const READINESS_INITIAL_DELAY_MS = 5_000; // delay before the first poll (never faster than ~8s)
+export const READINESS_POLL_INTERVAL_MS = 1_000; // between DoH polls
+// DoH resolver
+export const DOH_REQUEST_TIMEOUT_MS = 3_000; // per-request (measured 40–110ms)
+export const DOH_PROVIDERS = [
+    {
+        name: 'cloudflare',
+        url: (h, t) => `https://1.1.1.1/dns-query?name=${encodeURIComponent(h)}&type=${t}`,
+        headers: { accept: 'application/dns-json' },
+    },
+    {
+        name: 'cloudflare2',
+        url: (h, t) => `https://1.0.0.1/dns-query?name=${encodeURIComponent(h)}&type=${t}`,
+        headers: { accept: 'application/dns-json' },
+    },
+    // dns.google's cert carries an 8.8.8.8 SAN; the JSON endpoint is /resolve
+    // (NOT /dns-query, which expects wire format). IP-literal, so no system DNS.
+    {
+        name: 'google',
+        url: (h, t) => `https://8.8.8.8/resolve?name=${encodeURIComponent(h)}&type=${t}`,
+    },
+];
+// Guest connection bounds (so a black-hole/lagging resolver can't hang the join)
+export const GUEST_HANDSHAKE_TIMEOUT_MS = 15_000; // ws handshake (DNS+TCP+TLS+upgrade)
+export const GUEST_CONNECT_DEADLINE_MS = 20_000; // overall connect+auth deadline (> handshake)
+export const GUEST_SYS_LOOKUP_TIMEOUT_MS = 2_000; // bound the system-first lookup before DoH fallback
+export const DOH_GUEST_RETRIES = 3; // DoH attempts in the guest fallback
+export const DOH_GUEST_RETRY_DELAY_MS = 700; // backoff between guest DoH attempts

package/dist/net/doh.d.ts

@@ -0,0 +1,16 @@
+export type DohClass = 'RESOLVED' | 'NXDOMAIN' | 'INDETERMINATE';
+export interface DohAddress {
+    address: string;
+    family: 4 | 6;
+}
+export interface DohResult {
+    klass: DohClass;
+    addresses: DohAddress[];
+}
+export interface DohProvider {
+    name: string;
+    url: (host: string, type: 'A' | 'AAAA') => string;
+    headers?: Record<string, string>;
+}
+export declare function dohQueryOnce(provider: DohProvider, host: string, family: 4 | 6, timeoutMs?: number, fetchImpl?: typeof fetch): Promise<DohResult>;
+export declare function dohResolve(host: string, family: 4 | 6, providers?: DohProvider[], timeoutMs?: number, fetchImpl?: typeof fetch): Promise<DohResult>;

package/dist/net/doh.js

@@ -0,0 +1,52 @@
+import { isIP } from 'node:net';
+import { DOH_PROVIDERS, DOH_REQUEST_TIMEOUT_MS } from '../config.js';
+// Query ONE provider for ONE record type over an IP-literal endpoint (so it can
+// never re-enter the system resolver). Never throws; classifies every failure.
+export async function dohQueryOnce(provider, host, family, timeoutMs = DOH_REQUEST_TIMEOUT_MS, fetchImpl = fetch) {
+    const type = family === 6 ? 'AAAA' : 'A';
+    const rrType = family === 6 ? 28 : 1;
+    try {
+        const r = await fetchImpl(provider.url(host, type), {
+            headers: { accept: 'application/dns-json', ...(provider.headers ?? {}) },
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        if (!r.ok)
+            return { klass: 'INDETERMINATE', addresses: [] };
+        let j;
+        try {
+            j = (await r.json()); // captive-portal HTML / non-JSON body → catch below
+        }
+        catch {
+            return { klass: 'INDETERMINATE', addresses: [] };
+        }
+        if (!j || typeof j.Status !== 'number')
+            return { klass: 'INDETERMINATE', addresses: [] };
+        if (j.Status === 3)
+            return { klass: 'NXDOMAIN', addresses: [] }; // not live yet → keep polling
+        if (j.Status !== 0)
+            return { klass: 'INDETERMINATE', addresses: [] }; // SERVFAIL(2) etc → unreachable-ish
+        const answers = Array.isArray(j.Answer) ? j.Answer : [];
+        const addresses = answers
+            .filter((a) => a.type === rrType && typeof a.data === 'string' && isIP(a.data) === family)
+            .map((a) => ({ address: a.data, family }));
+        if (!addresses.length)
+            return { klass: 'NXDOMAIN', addresses: [] }; // A-less / CNAME-only → not routable yet
+        return { klass: 'RESOLVED', addresses };
+    }
+    catch {
+        return { klass: 'INDETERMINATE', addresses: [] }; // refused/timeout/ENETUNREACH/TLS reset
+    }
+}
+// Try providers in order; first RESOLVED wins. Fold classes: any NXDOMAIN (and
+// no RESOLVED) → NXDOMAIN; otherwise INDETERMINATE (DoH itself unavailable).
+export async function dohResolve(host, family, providers = DOH_PROVIDERS, timeoutMs = DOH_REQUEST_TIMEOUT_MS, fetchImpl = fetch) {
+    let sawNx = false;
+    for (const p of providers) {
+        const res = await dohQueryOnce(p, host, family, timeoutMs, fetchImpl);
+        if (res.klass === 'RESOLVED')
+            return res;
+        if (res.klass === 'NXDOMAIN')
+            sawNx = true;
+    }
+    return { klass: sawNx ? 'NXDOMAIN' : 'INDETERMINATE', addresses: [] };
+}

package/dist/relay/guestClient.d.ts

@@ -2,13 +2,19 @@ import { EventEmitter } from 'node:events';
 import { JoinLink } from '../protocol/link.js';
 import { SessionLog } from '../log/sessionLog.js';
 import { WireMessage } from '../protocol/messages.js';
+export interface GuestNetOptions {
+    handshakeTimeoutMs?: number;
+    connectDeadlineMs?: number;
+    lookup?: unknown;
+}
 export declare class GuestClient extends EventEmitter {
     private link;
     private guestName;
     private log;
+    private netOpts;
     private ws?;
     private pending;
-    constructor(link: JoinLink, guestName: string, log: SessionLog);
+    constructor(link: JoinLink, guestName: string, log: SessionLog, netOpts?: GuestNetOptions);
     connect(sinceSeq?: number): Promise<{
         goal: string;
         peerName: string;

package/dist/relay/guestClient.js

@@ -2,23 +2,61 @@ import { EventEmitter } from 'node:events';
 import WebSocket from 'ws';
 import { respondChallenge } from '../protocol/crypto.js';
 import { encodeFrame, decodeFrame } from '../protocol/messages.js';
-import { DEFAULT_LISTEN_TIMEOUT_MS } from '../config.js';
+import { DEFAULT_LISTEN_TIMEOUT_MS, GUEST_HANDSHAKE_TIMEOUT_MS, GUEST_CONNECT_DEADLINE_MS, } from '../config.js';
+import { makeGuestLookup } from './guestLookup.js';
 export class GuestClient extends EventEmitter {
     link;
     guestName;
     log;
+    netOpts;
     ws;
     pending = new Map();
-    constructor(link, guestName, log) {
+    constructor(link, guestName, log, netOpts = {}) {
         super();
         this.link = link;
         this.guestName = guestName;
         this.log = log;
+        this.netOpts = netOpts;
     }
     connect(sinceSeq = 0) {
         return new Promise((resolve, reject) => {
-            const ws = new WebSocket(this.link.wsUrl);
+            const ws = new WebSocket(this.link.wsUrl, {
+                // Resolve system-first, DoH-fallback (bypasses a stale NXDOMAIN negative
+                // cache). ws keeps SNI/Host = the hostname, so returning a DoH IP here
+                // does not break TLS validation or Cloudflare routing.
+                lookup: this.netOpts.lookup ?? makeGuestLookup(),
+                handshakeTimeout: this.netOpts.handshakeTimeoutMs ?? GUEST_HANDSHAKE_TIMEOUT_MS,
+            });
             this.ws = ws;
+            // Overall connect+auth deadline: handshakeTimeout only bounds DNS+TCP+TLS+
+            // upgrade; the post-open challenge/auth round-trip is otherwise unbounded.
+            let settled = false;
+            const deadline = setTimeout(() => {
+                if (settled)
+                    return;
+                settled = true;
+                try {
+                    ws.terminate();
+                }
+                catch {
+                    /* already gone */
+                }
+                reject(new Error('timed out establishing tunnel'));
+            }, this.netOpts.connectDeadlineMs ?? GUEST_CONNECT_DEADLINE_MS);
+            const settleResolve = (v) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(deadline);
+                resolve(v);
+            };
+            const settleReject = (e) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(deadline);
+                reject(e);
+            };
             ws.on('message', (data) => {
                 let frame;
                 try {
@@ -38,10 +76,10 @@ export class GuestClient extends EventEmitter {
                 else if (frame.t === 'auth_ok') {
                     for (const m of frame.backlog)
                         this.log.record(m);
-                    resolve({ goal: frame.goal, peerName: frame.peerName });
+                    settleResolve({ goal: frame.goal, peerName: frame.peerName });
                 }
                 else if (frame.t === 'auth_fail') {
-                    reject(new Error(`auth failed: ${frame.reason}`));
+                    settleReject(new Error(`auth failed: ${frame.reason}`));
                     ws.close();
                 }
                 else if (frame.t === 'msg') {
@@ -56,7 +94,7 @@ export class GuestClient extends EventEmitter {
             });
             ws.on('close', () => this.failPending(new Error('tunnel disconnected')));
             ws.on('error', (err) => {
-                reject(err);
+                settleReject(err);
                 this.failPending(err);
             });
         });

package/dist/relay/guestLookup.d.ts

@@ -0,0 +1,26 @@
+import type { LookupOptions } from 'node:dns';
+import { dohResolve } from '../net/doh.js';
+type Addr = {
+    address: string;
+    family: number;
+};
+type LookupCallback = (err: NodeJS.ErrnoException | null, address?: string | Addr[], family?: number) => void;
+type SysLookup = (hostname: string, options: LookupOptions, callback: LookupCallback) => void;
+export interface GuestLookupOpts {
+    dohEnabled?: boolean;
+    doh?: typeof dohResolve;
+    sys?: SysLookup;
+    sysTimeoutMs?: number;
+    retries?: number;
+    retryDelayMs?: number;
+}
+export declare function dohEnabledByDefault(): boolean;
+/**
+ * A drop-in `dns.lookup` for the guest WebSocket. Tries the system resolver
+ * first (respects split-horizon/corp DNS, and is what most guests need), then —
+ * only on failure — falls back to DoH, so a guest whose resolver lags or holds a
+ * stale NXDOMAIN negative cache still connects. Returns only an address; ws/tls
+ * keep SNI/Host = the hostname, so returning a DoH IP does not break routing.
+ */
+export declare function makeGuestLookup(o?: GuestLookupOpts): (hostname: string, options: LookupOptions | number, callback: LookupCallback) => void;
+export {};

package/dist/relay/guestLookup.js

@@ -0,0 +1,80 @@
+import { lookup as sysLookup } from 'node:dns';
+import { dohResolve } from '../net/doh.js';
+import { envFlag } from '../env.js';
+import { GUEST_SYS_LOOKUP_TIMEOUT_MS, DOH_GUEST_RETRIES, DOH_GUEST_RETRY_DELAY_MS, } from '../config.js';
+// DoH fallback is ON by default; only an explicit off/0/false/no disables it.
+export function dohEnabledByDefault() {
+    return process.env.TUNNEL_DOH === undefined || envFlag('TUNNEL_DOH');
+}
+/**
+ * A drop-in `dns.lookup` for the guest WebSocket. Tries the system resolver
+ * first (respects split-horizon/corp DNS, and is what most guests need), then —
+ * only on failure — falls back to DoH, so a guest whose resolver lags or holds a
+ * stale NXDOMAIN negative cache still connects. Returns only an address; ws/tls
+ * keep SNI/Host = the hostname, so returning a DoH IP does not break routing.
+ */
+export function makeGuestLookup(o = {}) {
+    const dohEnabled = o.dohEnabled ?? dohEnabledByDefault();
+    const doh = o.doh ?? dohResolve;
+    const sys = o.sys ?? sysLookup;
+    const sysTimeoutMs = o.sysTimeoutMs ?? GUEST_SYS_LOOKUP_TIMEOUT_MS;
+    const retries = o.retries ?? DOH_GUEST_RETRIES;
+    const retryDelayMs = o.retryDelayMs ?? DOH_GUEST_RETRY_DELAY_MS;
+    return function guestLookup(hostname, options, callback) {
+        const opts = typeof options === 'number' ? { family: options } : (options ?? {});
+        const wantAll = opts.all === true;
+        const family = opts.family === 6 ? 6 : 4; // prefer A/IPv4; AAAA only when explicitly asked
+        let settled = false;
+        const done = (err, address, fam) => {
+            if (settled)
+                return;
+            settled = true;
+            callback(err, address, fam);
+        };
+        // Stage 1: system resolver first, bounded so a poisoned/lagging getaddrinfo
+        // can't stall for seconds before we fall back to DoH.
+        let sysSettled = false;
+        const sysTimer = setTimeout(() => {
+            if (!sysSettled) {
+                sysSettled = true;
+                goDoh(new Error('system lookup timed out'));
+            }
+        }, sysTimeoutMs);
+        sys(hostname, opts, (err, address, fam) => {
+            if (sysSettled)
+                return;
+            sysSettled = true;
+            clearTimeout(sysTimer);
+            const ok = !err && (wantAll ? Array.isArray(address) && address.length > 0 : !!address);
+            if (ok)
+                return done(null, address, fam);
+            goDoh(err ?? new Error(`getaddrinfo failed for ${hostname}`));
+        });
+        function goDoh(sysErr) {
+            if (!dohEnabled)
+                return fail(sysErr);
+            let attempt = 0;
+            const tryOnce = () => {
+                doh(hostname, family)
+                    .then((res) => {
+                    if (res.klass === 'RESOLVED') {
+                        if (wantAll)
+                            return done(null, res.addresses.map((a) => ({ address: a.address, family: a.family })));
+                        return done(null, res.addresses[0].address, res.addresses[0].family);
+                    }
+                    // NXDOMAIN (still propagating) or INDETERMINATE (DoH blocked): retry a few times.
+                    if (++attempt < retries)
+                        return void setTimeout(tryOnce, retryDelayMs);
+                    fail(sysErr);
+                })
+                    .catch(() => ++attempt < retries ? void setTimeout(tryOnce, retryDelayMs) : fail(sysErr));
+            };
+            tryOnce();
+        }
+        function fail(sysErr) {
+            const e = new Error(`could not resolve ${hostname}: system resolver failed (${sysErr.message}) and DoH (1.1.1.1/1.0.0.1/8.8.8.8) also failed`);
+            e.code = 'ENOTFOUND';
+            done(e, wantAll ? [] : '', family);
+        }
+    };
+}

package/dist/session.js

@@ -7,12 +7,9 @@ import { GuestClient } from './relay/guestClient.js';
 import { ensureCloudflared as realEnsure } from './cloudflared/provision.js';
 import { startCloudflared as realStart } from './cloudflared/tunnelProcess.js';
 import { DEFAULT_LISTEN_TIMEOUT_MS, DEFAULT_IDLE_TEARDOWN_MS, DEFAULT_JOIN_LINK_TTL_MS, OPEN_RETRY_ATTEMPTS, } from './config.js';
-import { envFlag } from './env.js';
 const DEFAULT_DEPS = {
     ensureCloudflared: realEnsure,
-    // Read the escape hatch per-call (not at module load) so it can be set right
-    // before opening a tunnel.
-    startCloudflared: (bin, port) => realStart(bin, port, envFlag('TUNNEL_SKIP_REACHABILITY_CHECK') ? { skipHealthCheck: true } : {}),
+    startCloudflared: (bin, port) => realStart(bin, port),
 };
 export class TunnelSession {
     deps;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tunnel-mcp",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Let two developers' Claude agents talk directly through an ephemeral, end-to-end-encrypted tunnel.",
   "type": "module",
   "bin": {