From aebfee3cde1cbed4796ce5158fd0bd37ecefed7f Mon Sep 17 00:00:00 2001 From: Josh Winters Date: Sun, 15 Nov 2026 01:50:43 -0500 Subject: [PATCH 1/5] Let setup finish when the hosted service cannot be reached Setup signed in to the hosted service before it saved the profile, so `quickstart`, `keygen --setup` and `setup` all failed with "fetch failed" on a machine with no route to it: a sandbox with restricted egress, a CI job, a laptop offline. Capture and recall are local-first and already worked for a profile with no session, so nothing else needed the sign-in at that moment. When the service is unreachable (no route, refused connection, timeout), setup now saves the profile with no session and reports `registration: deferred`. The client signs in on its first hosted request, as it already does when a session expires. A response that refuses the sign-in, or a challenge that fails validation, still fails setup. Also documents the local-only profile (`--api-base http://127.0.0.1:0`), which existed and was used by tests but appeared in no help or README text. --- README.md | 13 +++++ src/runtime/cli.ts | 1 + src/runtime/cli/core.ts | 9 +++- src/runtime/cli/quickstart.ts | 6 ++- src/runtime/local-runtime.ts | 28 +++++++++-- tests/runtime/offline-setup.test.ts | 77 +++++++++++++++++++++++++++++ 6 files changed, 127 insertions(+), 7 deletions(-) create mode 100644 tests/runtime/offline-setup.test.ts diff --git a/README.md b/README.md index 98c8896..cc3246c 100644 --- a/README.md +++ b/README.md @@ -166,6 +166,19 @@ that profile. Other hosts retain a mode-off notice and administrative diagnostic without injecting recalled memory. Use `crosshead workspace remove` to detach a project. +### Without a connection + +Setup does not need the hosted service to be reachable. If `crosshead.sh` +cannot be reached (a sandbox with restricted egress, a CI job, a laptop +offline), the profile is still created and setup prints `registration: +deferred`. Capture and recall work locally at once, and the profile signs in +on its first successful request. A response from the service that refuses the +sign-in still fails setup. + +For a profile that never contacts a hosted service, pass +`--api-base http://127.0.0.1:0`. Hot memory, hooks and handoff capsules work; +hosted recall, sync between machines and billing do not. + Local-only checkpoints are stored per profile. A legacy flat store remains readable for its sole existing local-only profile, whose identity is pinned before creating another profile. If several profiles already shared an unowned diff --git a/src/runtime/cli.ts b/src/runtime/cli.ts index fcf66fe..be48b6a 100644 --- a/src/runtime/cli.ts +++ b/src/runtime/cli.ts @@ -300,6 +300,7 @@ export const runOnlyBotsCtlCli = async ( capabilityHelpLine, "crosshead keygen [--json]", "crosshead keygen --setup --profile --api-base [--home ] [--memory-mode assist] [--workspace-scope repo|workspace|global] [--json]", + " (--api-base http://127.0.0.1:0 creates a local-only profile; an unreachable service defers sign-in instead of failing setup)", "crosshead setup --profile --api-base --npub --nsec [--memory-mode assist]", "crosshead start [--home ] [--port ]", "crosshead stop [--home ]", diff --git a/src/runtime/cli/core.ts b/src/runtime/cli/core.ts index 6168c7c..5e28043 100644 --- a/src/runtime/cli/core.ts +++ b/src/runtime/cli/core.ts @@ -131,9 +131,14 @@ export const setupProfileFromCli = async (argv: string[]): Promise => { npub: String(flags.npub ?? ""), nsec: String(flags.nsec ?? ""), }); - return `Configured runtime profile ${profile.name} for ${profile.npub}`; + return [`Configured runtime profile ${profile.name} for ${profile.npub}`, ...registrationDeferredLines(profile)].join("\n"); }; +const registrationDeferredLines = (profile: { apiBase: string; registrationDeferred?: true }): string[] => + profile.registrationDeferred + ? [`registration: deferred; ${profile.apiBase} could not be reached. Local capture and recall work now, and the profile signs in on its first successful request.`] + : []; + export const keygenFromCli = async (argv: string[]): Promise => { const { flags } = parseArgs(argv); const identity = generateRuntimeIdentity(); @@ -161,6 +166,7 @@ export const keygenFromCli = async (argv: string[]): Promise => { memoryMode: profile.memoryMode, workspaceScope: profile.workspaceScope, secureStoreMode: profile.secureStoreMode, + ...(profile.registrationDeferred ? { registrationDeferred: true } : {}), }; return flags.json ? JSON.stringify(result, null, 2) @@ -171,6 +177,7 @@ export const keygenFromCli = async (argv: string[]): Promise => { `memory_mode: ${profile.memoryMode}`, `workspace_scope: ${profile.workspaceScope}`, `secure_store: ${profile.secureStoreMode}`, + ...registrationDeferredLines(profile), ].join("\n"); }; diff --git a/src/runtime/cli/quickstart.ts b/src/runtime/cli/quickstart.ts index 56c0d5c..89b1692 100644 --- a/src/runtime/cli/quickstart.ts +++ b/src/runtime/cli/quickstart.ts @@ -210,11 +210,13 @@ export const quickstartFromCli = async (argv: string[], paths: QuickstartCliPath throw new Error("quickstart requires --api-base when the selected profile does not exist"); } const profileOutput = await keygenFromCli([...profileArgs, "--setup", "--json"]); - const parsed = JSON.parse(profileOutput) as { npub?: string; apiBase?: string }; + const parsed = JSON.parse(profileOutput) as { npub?: string; apiBase?: string; registrationDeferred?: boolean }; steps.push({ id: "profile", ok: true, - detail: `configured ${profileName} for ${parsed.apiBase ?? apiBase} with generated runtime identity ${parsed.npub ?? "unknown"}`, + detail: `configured ${profileName} for ${parsed.apiBase ?? apiBase} with generated runtime identity ${parsed.npub ?? "unknown"}${ + parsed.registrationDeferred ? "; the service could not be reached, so sign-in is deferred until it can (local capture and recall work now)" : "" + }`, }); } else { steps.push({ diff --git a/src/runtime/local-runtime.ts b/src/runtime/local-runtime.ts index e6a4ee9..d2d73f2 100644 --- a/src/runtime/local-runtime.ts +++ b/src/runtime/local-runtime.ts @@ -28,7 +28,7 @@ import * as tar from "tar"; import { OperatorRuntimePolicyBroker, type OperatorWorkspaceManifest } from "./operator-policy"; import { HOSTED_PI_CONTROLLER_ADAPTER, HOSTED_PI_CONTROLLER_MANIFEST, hostedControllerProcessIsLive, type HostedControllerProcess } from "./hosted-pi-controller-manifest"; import { acquireRuntimeDaemonOwnership, daemonOwnerIsLive, probeRuntimeDaemonHealth, readDaemonOwnershipState, type RuntimeDaemonOwnership } from "./daemon-ownership"; -import { HostedOnlyBotsClient, type HostedSession } from "./hosted-client"; +import { HostedOnlyBotsClient, HostedOnlyBotsRequestError, type HostedSession } from "./hosted-client"; import { isLocalOnlyRuntimeProfile, preserveLegacyLocalHotOwner, readLocalHotMemory } from "./local-hot-memory"; import { searchHotCheckpoints } from "./hot-continuity"; import { @@ -1285,7 +1285,19 @@ export const uninstallRuntimeCore = async (home?: string): Promise => { } }; -export const setupRuntimeProfile = async (options: SetupRuntimeProfileOptions): Promise => { +/** + * True when the hosted service could not be reached at all: no route, DNS failure, refused + * connection or timeout. An HTTP answer, or a challenge that fails validation, is the service + * (or something posing as it) responding, and is never treated as "offline". + */ +const hostedServiceUnreachable = (error: unknown): boolean => + error instanceof Error && !(error instanceof HostedOnlyBotsRequestError) && + (error.name === "TimeoutError" || error.name === "AbortError" || (error.name === "TypeError" && /fetch failed/i.test(error.message))); + +/** The saved profile, plus whether sign-in with the hosted service was put off because it was unreachable. */ +export type SetupRuntimeProfileResult = RuntimeProfile & { registrationDeferred?: true }; + +export const setupRuntimeProfile = async (options: SetupRuntimeProfileOptions): Promise => { try { const decodedNpub = nip19.decode(options.npub); const decodedNsec = nip19.decode(options.nsec); @@ -1306,6 +1318,9 @@ export const setupRuntimeProfile = async (options: SetupRuntimeProfileOptions): if (options.createOnly && loadProfile(paths, options.profileName)) throw new Error(`Profile ${options.profileName} already exists`); const secret = loadSecret(paths, options.profileName); const localOnlyProfile = isLocalOnlyRuntimeProfile({ apiBase: options.apiBase }); + // Capture and recall are local-first, so a machine with no route to the service (a sandbox, a + // CI job, a laptop offline) can still be set up. The client signs in on its first hosted request. + let registrationDeferred = false; const session = localOnlyProfile ? null : await new HostedOnlyBotsClient({ @@ -1313,7 +1328,11 @@ export const setupRuntimeProfile = async (options: SetupRuntimeProfileOptions): npub: options.npub, nsec: options.nsec, session: secret?.session ?? null, - }).ensureSession(); + }).ensureSession().catch((error: unknown) => { + if (!hostedServiceUnreachable(error)) throw error; + registrationDeferred = true; + return null; + }); const profile: RuntimeProfile = { name: options.profileName, @@ -1353,8 +1372,9 @@ export const setupRuntimeProfile = async (options: SetupRuntimeProfileOptions): npub: profile.npub, apiBase: profile.apiBase, memoryMode: profile.memoryMode, + ...(registrationDeferred ? { registrationDeferred: true } : {}), }); - return profile; + return registrationDeferred ? { ...profile, registrationDeferred: true } : profile; }; const installManagedAdapter = async ( diff --git a/tests/runtime/offline-setup.test.ts b/tests/runtime/offline-setup.test.ts new file mode 100644 index 0000000..1fa8513 --- /dev/null +++ b/tests/runtime/offline-setup.test.ts @@ -0,0 +1,77 @@ +import { existsSync, mkdtempSync, rmSync } from "node:fs"; +import os from "node:os"; +import path from "node:path"; + +import { generateSecretKey, getPublicKey, nip19 } from "nostr-tools"; +import { afterEach, describe, expect, it, vi } from "vitest"; + +import { keygenFromCli } from "../../src/runtime/cli/core"; +import { setupRuntimeProfile } from "../../src/runtime/local-runtime"; +import { loadProfile, loadSecret, resolveRuntimePaths } from "../../src/runtime/runtime-persistence"; + +const homes: string[] = []; +afterEach(() => { + vi.unstubAllGlobals(); + homes.splice(0).forEach((home) => rmSync(home, { recursive: true, force: true })); +}); + +const newHome = (): string => { + const home = mkdtempSync(path.join(os.tmpdir(), "crosshead-offline-setup-")); + homes.push(home); + return home; +}; +const identity = () => { + const secret = generateSecretKey(); + return { nsec: nip19.nsecEncode(secret), npub: nip19.npubEncode(getPublicKey(secret)) }; +}; +// What Node's fetch throws when there is no route to the host. +const unreachable = () => vi.fn().mockRejectedValue(new TypeError("fetch failed")); + +describe("setup when the hosted service cannot be reached", () => { + it("creates the profile and defers sign-in", async () => { + const home = newHome(); + const key = identity(); + const fetchMock = unreachable(); + vi.stubGlobal("fetch", fetchMock); + + const profile = await setupRuntimeProfile({ home, profileName: "default", apiBase: "https://crosshead.sh", ...key, makeDefault: true }); + + expect(fetchMock).toHaveBeenCalled(); + expect(profile.registrationDeferred).toBe(true); + const paths = resolveRuntimePaths(home); + const saved = loadProfile(paths, "default"); + expect(saved).toMatchObject({ npub: key.npub, apiBase: "https://crosshead.sh" }); + // The flag describes this run; it is not part of the stored profile. + expect(saved).not.toHaveProperty("registrationDeferred"); + expect(loadSecret(paths, "default")).toMatchObject({ nsec: key.nsec, session: null }); + }); + + it("tells the operator in the keygen output", async () => { + const home = newHome(); + vi.stubGlobal("fetch", unreachable()); + const text = await keygenFromCli(["--setup", "--home", home, "--profile", "default", "--api-base", "https://crosshead.sh"]); + expect(text).toContain("registration: deferred"); + const json = JSON.parse(await keygenFromCli(["--setup", "--home", newHome(), "--profile", "default", "--api-base", "https://crosshead.sh", "--json"])); + expect(json.registrationDeferred).toBe(true); + }); + + it("still fails when the service answers and refuses the sign-in", async () => { + const home = newHome(); + vi.stubGlobal("fetch", vi.fn().mockResolvedValue(new Response( + JSON.stringify({ error: { code: "forbidden", message: "registration closed" } }), + { status: 403, headers: { "content-type": "application/json" } } + ))); + await expect(setupRuntimeProfile({ home, profileName: "default", apiBase: "https://crosshead.sh", ...identity(), makeDefault: true })) + .rejects.toThrow(); + expect(existsSync(path.join(home, "config", "profiles", "default.json"))).toBe(false); + expect(loadProfile(resolveRuntimePaths(home), "default")).toBeNull(); + }); + + it("does not report a deferral for a local-only profile", async () => { + const fetchMock = unreachable(); + vi.stubGlobal("fetch", fetchMock); + const profile = await setupRuntimeProfile({ home: newHome(), profileName: "default", apiBase: "http://127.0.0.1:0", ...identity(), makeDefault: true }); + expect(profile.registrationDeferred).toBeUndefined(); + expect(fetchMock).not.toHaveBeenCalled(); + }); +}); From d43619e0dc9b49acecd67ecc14ecd65dbd46eb1e Mon Sep 17 00:00:00 2001 From: Josh Winters Date: Sun, 15 Nov 2026 14:14:57 -0500 Subject: [PATCH 2/5] Defer setup only for real network failures and say so on every path Classify sign-in failures by the fetch error's cause code: refused, unreachable, reset and timed-out connections defer; redirects, certificate and proxy errors, and an unknown host name (except crosshead.sh) fail setup. The deferral line names the network error, guided project setup now reports it, and doctor says when a profile has never signed in and why the sign-in failed. --- README.md | 11 +++- src/runtime/cli/core.ts | 6 +- src/runtime/cli/workspace.ts | 13 ++-- src/runtime/local-runtime.ts | 55 +++++++++++++--- src/runtime/runtime-status.ts | 13 +++- tests/runtime/offline-setup.test.ts | 99 +++++++++++++++++++++++++++-- 6 files changed, 171 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index cc3246c..98e40c3 100644 --- a/README.md +++ b/README.md @@ -171,9 +171,14 @@ project. Setup does not need the hosted service to be reachable. If `crosshead.sh` cannot be reached (a sandbox with restricted egress, a CI job, a laptop offline), the profile is still created and setup prints `registration: -deferred`. Capture and recall work locally at once, and the profile signs in -on its first successful request. A response from the service that refuses the -sign-in still fails setup. +deferred` with the network error. Capture and recall work locally at once, and +the profile tries to sign in on its next hosted request. That sign-in can still +be refused; `crosshead doctor` reports a profile that has never signed in and +why. + +Setup still fails when the problem is the address rather than the network: a +response that refuses the sign-in, a redirect, a certificate error, or (for any +`--api-base` other than `crosshead.sh`) a host name that does not exist. For a profile that never contacts a hosted service, pass `--api-base http://127.0.0.1:0`. Hot memory, hooks and handoff capsules work; diff --git a/src/runtime/cli/core.ts b/src/runtime/cli/core.ts index 5e28043..80aaee9 100644 --- a/src/runtime/cli/core.ts +++ b/src/runtime/cli/core.ts @@ -134,9 +134,9 @@ export const setupProfileFromCli = async (argv: string[]): Promise => { return [`Configured runtime profile ${profile.name} for ${profile.npub}`, ...registrationDeferredLines(profile)].join("\n"); }; -const registrationDeferredLines = (profile: { apiBase: string; registrationDeferred?: true }): string[] => +export const registrationDeferredLines = (profile: { apiBase: string; registrationDeferred?: boolean; registrationDeferredReason?: string }): string[] => profile.registrationDeferred - ? [`registration: deferred; ${profile.apiBase} could not be reached. Local capture and recall work now, and the profile signs in on its first successful request.`] + ? [`registration: deferred; ${profile.apiBase} could not be reached${profile.registrationDeferredReason ? ` (${profile.registrationDeferredReason})` : ""}. Local capture and recall work now, and the profile signs in on its first successful request; crosshead doctor shows whether it has.`] : []; export const keygenFromCli = async (argv: string[]): Promise => { @@ -166,7 +166,7 @@ export const keygenFromCli = async (argv: string[]): Promise => { memoryMode: profile.memoryMode, workspaceScope: profile.workspaceScope, secureStoreMode: profile.secureStoreMode, - ...(profile.registrationDeferred ? { registrationDeferred: true } : {}), + ...(profile.registrationDeferred ? { registrationDeferred: true, registrationDeferredReason: profile.registrationDeferredReason ?? null } : {}), }; return flags.json ? JSON.stringify(result, null, 2) diff --git a/src/runtime/cli/workspace.ts b/src/runtime/cli/workspace.ts index 2130689..242f1c8 100644 --- a/src/runtime/cli/workspace.ts +++ b/src/runtime/cli/workspace.ts @@ -11,7 +11,7 @@ import { import { isRuntimeProfileName } from "../runtime-env"; import { uninstallCodexFromCli } from "../codex-adapter"; import { uninstallClaudeCodeFromCli } from "../claude-code-adapter"; -import { installCoreFromCli, keygenFromCli } from "./core"; +import { installCoreFromCli, keygenFromCli, registrationDeferredLines } from "./core"; import { ensureQuickstartDaemon, type QuickstartCliPaths } from "./quickstart"; type Flags = Record; @@ -228,6 +228,7 @@ export const scopedQuickstartFromCli = async (flags: Flags, scripts: QuickstartC return flags.json ? JSON.stringify({ applied: false, ...preview }, null, 2) : runtimePlan + profilePlan + describePlan(preview); } if (flow && !await flow.confirm(runtimePlan + profilePlan + describePlan(preview))) return "Setup cancelled."; + const deferred: Array<{ profile: string; apiBase: string; reason: string | null }> = []; const daemon = await withWorkspaceSetupLock(paths, async () => { assertWorkspacePlanCurrent(plan); if (names.some((name) => profileSnapshot(paths, name) !== profilesBefore.get(name))) { @@ -240,8 +241,9 @@ export const scopedQuickstartFromCli = async (flags: Flags, scripts: QuickstartC await installCoreFromCli([...args, "--channel", channel], scripts.cliScriptPath, scripts.daemonScriptPath); } for (const name of newProfiles) { - await keygenFromCli([...args, "--setup", "--profile", name, "--api-base", apiBase!, "--memory-mode", mode, - "--workspace-scope", "repo", "--no-default", "--create-only", "--json"]); + const created = JSON.parse(await keygenFromCli([...args, "--setup", "--profile", name, "--api-base", apiBase!, "--memory-mode", mode, + "--workspace-scope", "repo", "--no-default", "--create-only", "--json"])) as { registrationDeferred?: boolean; registrationDeferredReason?: string | null }; + if (created.registrationDeferred) deferred.push({ profile: name, apiBase: apiBase!, reason: created.registrationDeferredReason ?? null }); } applyWorkspaceHookPlan(plan); const result = enabled(flags, "no-start") ? null : await ensureQuickstartDaemon({ @@ -252,9 +254,12 @@ export const scopedQuickstartFromCli = async (flags: Flags, scripts: QuickstartC const inspection = inspectWorkspaceHooks(options.home); const checks = scope === "project" ? [...new Set(targets.map((target) => workspaceProjectRoot(target.directory)))] : [process.cwd()]; return flags.json - ? JSON.stringify({ command: "quickstart", applied: true, home: paths.home, profiles: names, daemon, ...inspection }, null, 2) + ? JSON.stringify({ command: "quickstart", applied: true, home: paths.home, profiles: names, daemon, ...inspection, + ...(deferred.length > 0 ? { registrationDeferred: deferred } : {}) }, null, 2) : [ "Crosshead setup complete.", + ...deferred.flatMap((entry) => registrationDeferredLines({ apiBase: entry.apiBase, registrationDeferred: true, registrationDeferredReason: entry.reason ?? undefined }) + .map((line) => `${entry.profile} ${line}`)), ...(daemon ? [daemon.detail] : []), formatWorkspaceHookInspection(inspection), ...checks.map((root) => `Verify from a fresh session with crosshead workspace check --workspace-root ${shellQuote(root)}${options.home ? ` --home ${shellQuote(paths.home)}` : ""}`), diff --git a/src/runtime/local-runtime.ts b/src/runtime/local-runtime.ts index d2d73f2..4ac8ab4 100644 --- a/src/runtime/local-runtime.ts +++ b/src/runtime/local-runtime.ts @@ -1285,17 +1285,49 @@ export const uninstallRuntimeCore = async (home?: string): Promise => { } }; +// Node's fetch reports nearly every transport failure as TypeError("fetch failed") and puts the +// real reason in `cause` (sometimes an AggregateError, one entry per address tried). Only these +// codes mean "no route to the service right now". A redirect, a certificate problem or a proxy +// error means something answered, or the address is wrong, and setup must say so instead. +const NETWORK_UNREACHABLE_CODES = new Set([ + "ECONNREFUSED", "ENETUNREACH", "EHOSTUNREACH", "ENETDOWN", "EHOSTDOWN", "ETIMEDOUT", "ECONNRESET", + "EAI_AGAIN", "EPIPE", "UND_ERR_CONNECT_TIMEOUT", "UND_ERR_SOCKET", +]); +const DEFAULT_HOSTED_HOSTS = new Set(["crosshead.sh", "www.crosshead.sh"]); + +const fetchCauseCodes = (error: unknown, depth = 0): string[] => { + if (!error || typeof error !== "object" || depth > 4) return []; + const record = error as { code?: unknown; cause?: unknown; errors?: unknown }; + return [ + ...(typeof record.code === "string" ? [record.code] : []), + ...fetchCauseCodes(record.cause, depth + 1), + ...(Array.isArray(record.errors) ? record.errors.flatMap((entry) => fetchCauseCodes(entry, depth + 1)) : []), + ]; +}; + /** - * True when the hosted service could not be reached at all: no route, DNS failure, refused - * connection or timeout. An HTTP answer, or a challenge that fails validation, is the service - * (or something posing as it) responding, and is never treated as "offline". + * Why the hosted service could not be reached at all, or null when the failure is something + * setup must report: an HTTP answer, a failed challenge, a redirect, a certificate or proxy + * error, or a host name that does not exist. A name that does not resolve is treated as offline + * only for the default service, where it means DNS is unavailable rather than a typo. */ -const hostedServiceUnreachable = (error: unknown): boolean => - error instanceof Error && !(error instanceof HostedOnlyBotsRequestError) && - (error.name === "TimeoutError" || error.name === "AbortError" || (error.name === "TypeError" && /fetch failed/i.test(error.message))); +export const hostedServiceUnreachableReason = (error: unknown, apiBase: string): string | null => { + if (!(error instanceof Error) || error instanceof HostedOnlyBotsRequestError) return null; + if (error.name === "TimeoutError" || error.name === "AbortError") return "timed out"; + if (error.name !== "TypeError" || !/fetch failed/i.test(error.message)) return null; + const codes = fetchCauseCodes(error.cause); + const unreachable = codes.find((code) => NETWORK_UNREACHABLE_CODES.has(code)); + if (unreachable) return unreachable; + if (codes.includes("ENOTFOUND")) { + let host = ""; + try { host = new URL(apiBase).hostname; } catch { /* an invalid URL fails elsewhere */ } + return DEFAULT_HOSTED_HOSTS.has(host) ? "ENOTFOUND" : null; + } + return null; +}; /** The saved profile, plus whether sign-in with the hosted service was put off because it was unreachable. */ -export type SetupRuntimeProfileResult = RuntimeProfile & { registrationDeferred?: true }; +export type SetupRuntimeProfileResult = RuntimeProfile & { registrationDeferred?: true; registrationDeferredReason?: string }; export const setupRuntimeProfile = async (options: SetupRuntimeProfileOptions): Promise => { try { @@ -1321,6 +1353,7 @@ export const setupRuntimeProfile = async (options: SetupRuntimeProfileOptions): // Capture and recall are local-first, so a machine with no route to the service (a sandbox, a // CI job, a laptop offline) can still be set up. The client signs in on its first hosted request. let registrationDeferred = false; + let registrationDeferredReason: string | undefined; const session = localOnlyProfile ? null : await new HostedOnlyBotsClient({ @@ -1329,8 +1362,10 @@ export const setupRuntimeProfile = async (options: SetupRuntimeProfileOptions): nsec: options.nsec, session: secret?.session ?? null, }).ensureSession().catch((error: unknown) => { - if (!hostedServiceUnreachable(error)) throw error; + const reason = hostedServiceUnreachableReason(error, options.apiBase); + if (reason === null) throw error; registrationDeferred = true; + registrationDeferredReason = reason; return null; }); @@ -1372,9 +1407,9 @@ export const setupRuntimeProfile = async (options: SetupRuntimeProfileOptions): npub: profile.npub, apiBase: profile.apiBase, memoryMode: profile.memoryMode, - ...(registrationDeferred ? { registrationDeferred: true } : {}), + ...(registrationDeferred ? { registrationDeferred: true, registrationDeferredReason } : {}), }); - return registrationDeferred ? { ...profile, registrationDeferred: true } : profile; + return registrationDeferred ? { ...profile, registrationDeferred: true, registrationDeferredReason } : profile; }; const installManagedAdapter = async ( diff --git a/src/runtime/runtime-status.ts b/src/runtime/runtime-status.ts index 6fd0f94..416ff01 100644 --- a/src/runtime/runtime-status.ts +++ b/src/runtime/runtime-status.ts @@ -553,6 +553,7 @@ export const buildDoctorReport = async (paths: RuntimePaths, profileName?: strin }); let authValid = false; + let signInError: string | null = null; if (secret) { try { const session = await hosted.ensureSession(); @@ -561,14 +562,22 @@ export const buildDoctorReport = async (paths: RuntimePaths, profileName?: strin session, }); authValid = isSessionFresh(session); - } catch { + } catch (error) { authValid = false; + signInError = error instanceof Error ? error.message.slice(0, 200) : String(error).slice(0, 200); } } + // A profile set up while the service was unreachable has never held a session. Say so, + // rather than reporting an expiry that never happened. + const neverSignedIn = Boolean(secret) && !secret?.session; checks.push({ id: "auth", ok: authValid, - message: authValid ? "Hosted auth session is valid." : "Hosted auth session is missing or expired.", + message: authValid + ? "Hosted auth session is valid." + : neverSignedIn + ? `This profile has not signed in to ${selectedProfile.apiBase} yet${signInError ? `; sign-in failed: ${signInError}` : ""}.` + : `Hosted auth session is missing or expired${signInError ? `; sign-in failed: ${signInError}` : ""}.`, }); } catch { checks.push({ id: "auth", ok: false, message: "Profile credentials are missing or invalid." }); diff --git a/tests/runtime/offline-setup.test.ts b/tests/runtime/offline-setup.test.ts index 1fa8513..376622a 100644 --- a/tests/runtime/offline-setup.test.ts +++ b/tests/runtime/offline-setup.test.ts @@ -1,4 +1,6 @@ -import { existsSync, mkdtempSync, rmSync } from "node:fs"; +import { spawnSync } from "node:child_process"; +import { existsSync, mkdirSync, mkdtempSync, realpathSync, rmSync } from "node:fs"; +import { createServer } from "node:net"; import os from "node:os"; import path from "node:path"; @@ -6,8 +8,10 @@ import { generateSecretKey, getPublicKey, nip19 } from "nostr-tools"; import { afterEach, describe, expect, it, vi } from "vitest"; import { keygenFromCli } from "../../src/runtime/cli/core"; -import { setupRuntimeProfile } from "../../src/runtime/local-runtime"; +import { HostedOnlyBotsRequestError } from "../../src/runtime/hosted-client"; +import { hostedServiceUnreachableReason, setupRuntimeProfile } from "../../src/runtime/local-runtime"; import { loadProfile, loadSecret, resolveRuntimePaths } from "../../src/runtime/runtime-persistence"; +import { buildRuntimeDoctorDirect } from "../../src/runtime/runtime-status"; const homes: string[] = []; afterEach(() => { @@ -24,8 +28,10 @@ const identity = () => { const secret = generateSecretKey(); return { nsec: nip19.nsecEncode(secret), npub: nip19.npubEncode(getPublicKey(secret)) }; }; -// What Node's fetch throws when there is no route to the host. -const unreachable = () => vi.fn().mockRejectedValue(new TypeError("fetch failed")); +// What Node's fetch throws when the connection is refused: the reason is in `cause`. +const unreachable = () => vi.fn().mockRejectedValue( + new TypeError("fetch failed", { cause: Object.assign(new Error("connect ECONNREFUSED 127.0.0.1:443"), { code: "ECONNREFUSED" }) }) +); describe("setup when the hosted service cannot be reached", () => { it("creates the profile and defers sign-in", async () => { @@ -74,4 +80,89 @@ describe("setup when the hosted service cannot be reached", () => { expect(profile.registrationDeferred).toBeUndefined(); expect(fetchMock).not.toHaveBeenCalled(); }); + + it("fails instead of deferring when the address is wrong rather than unreachable", async () => { + const typo = new TypeError("fetch failed", { cause: Object.assign(new Error("getaddrinfo ENOTFOUND crossheed.sh"), { code: "ENOTFOUND" }) }); + vi.stubGlobal("fetch", vi.fn().mockRejectedValue(typo)); + const home = newHome(); + await expect(setupRuntimeProfile({ home, profileName: "default", apiBase: "https://crossheed.sh", ...identity(), makeDefault: true })) + .rejects.toThrow("fetch failed"); + expect(loadProfile(resolveRuntimePaths(home), "default")).toBeNull(); + }); +}); + +describe("doctor after a deferred setup", () => { + it("says the profile has never signed in, and why the sign-in failed", async () => { + const home = newHome(); + vi.stubGlobal("fetch", unreachable()); + await setupRuntimeProfile({ home, profileName: "default", apiBase: "https://crosshead.sh", ...identity(), makeDefault: true }); + // The service is reachable now but refuses the registration. A fresh Response per call: doctor pings first. + vi.stubGlobal("fetch", vi.fn().mockImplementation(async () => new Response( + JSON.stringify({ error: { code: "forbidden", message: "registration closed" } }), + { status: 403, headers: { "content-type": "application/json" } } + ))); + const auth = (await buildRuntimeDoctorDirect(home, "default")).checks.find((check) => check.id === "auth"); + expect(auth?.ok).toBe(false); + expect(auth?.message).toContain("has not signed in to https://crosshead.sh yet"); + expect(auth?.message).toContain("registration closed"); + }); +}); + +describe("classifying hosted sign-in failures", () => { + const failed = (cause: unknown) => new TypeError("fetch failed", { cause }); + const coded = (code: string) => Object.assign(new Error(code), { code }); + + it("defers only for failures that mean no route to the service", () => { + expect(hostedServiceUnreachableReason(failed(coded("ECONNREFUSED")), "https://api.example.test")).toBe("ECONNREFUSED"); + expect(hostedServiceUnreachableReason(failed(new AggregateError([coded("ENETUNREACH"), coded("EHOSTUNREACH")])), "https://crosshead.sh")).toBe("ENETUNREACH"); + expect(hostedServiceUnreachableReason(failed(coded("UND_ERR_CONNECT_TIMEOUT")), "https://crosshead.sh")).toBe("UND_ERR_CONNECT_TIMEOUT"); + expect(hostedServiceUnreachableReason(Object.assign(new Error("timed out"), { name: "TimeoutError" }), "https://crosshead.sh")).toBe("timed out"); + // DNS failing for the default service means DNS is unavailable; for any other host it is more likely a typo. + expect(hostedServiceUnreachableReason(failed(coded("ENOTFOUND")), "https://crosshead.sh")).toBe("ENOTFOUND"); + expect(hostedServiceUnreachableReason(failed(coded("ENOTFOUND")), "https://crossheed.sh")).toBeNull(); + }); + + it("reports redirects, certificate errors, HTTP answers and unexplained failures", () => { + expect(hostedServiceUnreachableReason(failed(new Error("unexpected redirect")), "https://crosshead.sh")).toBeNull(); + expect(hostedServiceUnreachableReason(failed(coded("CERT_HAS_EXPIRED")), "https://crosshead.sh")).toBeNull(); + expect(hostedServiceUnreachableReason(failed(coded("ERR_TLS_CERT_ALTNAME_INVALID")), "https://crosshead.sh")).toBeNull(); + expect(hostedServiceUnreachableReason(failed(undefined), "https://crosshead.sh")).toBeNull(); + expect(hostedServiceUnreachableReason(new HostedOnlyBotsRequestError({ message: "nope", status: 503 }), "https://crosshead.sh")).toBeNull(); + expect(hostedServiceUnreachableReason(new Error("Invalid challenge"), "https://crosshead.sh")).toBeNull(); + }); +}); + +describe("guided project setup with no connection", () => { + const cliScript = path.resolve(__dirname, "../../dist/runtime/cli.js"); + + // A port that was free a moment ago, so a connection to it is refused. (Fetch blocks low ports + // such as 1 outright with "bad port", which is rightly not treated as offline.) + const closedPort = () => new Promise((resolve) => { + const server = createServer().listen(0, "127.0.0.1", () => { + const { port } = server.address() as { port: number }; + server.close(() => resolve(port)); + }); + }); + + it("reports the deferred sign-in instead of only 'setup complete', using Node's real refused-connection error", async () => { + const apiBase = `http://127.0.0.1:${await closedPort()}`; + const root = realpathSync(newHome()); + const home = path.join(root, "runtime"); + const project = path.join(root, "project"); + mkdirSync(project, { recursive: true }); + expect(spawnSync("git", ["init", "-q", project]).status).toBe(0); + mkdirSync(path.join(root, "codex"), { recursive: true }); + mkdirSync(path.join(root, "claude"), { recursive: true }); + // Nothing listens on port 1, so the connection is refused immediately. + const run = spawnSync(process.execPath, [ + cliScript, "quickstart", "--scope", "project", "--adapter", "both", "--workspace-root", project, "--profile", "work", + "--api-base", apiBase, "--no-start", "--codex-home", path.join(root, "codex"), "--claude-home", path.join(root, "claude"), + "--home", home, + ], { env: { PATH: process.env.PATH, CROSSHEAD_HOOK_AUTOSTART: "0" }, encoding: "utf8", timeout: 20000 }); + expect(run.status, run.stderr || run.stdout).toBe(0); + expect(run.stdout).toContain("Crosshead setup complete."); + expect(run.stdout).toContain("work registration: deferred"); + expect(run.stdout).toContain("ECONNREFUSED"); + expect(loadProfile(resolveRuntimePaths(home), "work")).toMatchObject({ apiBase }); + }, 30_000); }); From b4bd68b50aa1d46384ee1d5b941faece3a02486f Mon Sep 17 00:00:00 2001 From: Josh Winters Date: Sun, 15 Nov 2026 14:26:41 -0500 Subject: [PATCH 3/5] Defer setup when an egress proxy refuses the tunnel; name the cause otherwise An allowlisting proxy (the sandbox case that prompted the change) reports UND_ERR_ABORTED 'Proxy response (403) !== 200 when HTTP Tunneling'; treat it as unreachable. When setup does fail on a fetch error, say which: the cause code and message plus a hint to check --api-base. Doctor no longer reports hosted reach or sign-in failures for a local-only profile. --- src/runtime/local-runtime.ts | 39 ++++++++++++++++++++++------- src/runtime/runtime-status.ts | 6 ++++- tests/runtime/offline-setup.test.ts | 28 +++++++++++++++++++-- 3 files changed, 61 insertions(+), 12 deletions(-) diff --git a/src/runtime/local-runtime.ts b/src/runtime/local-runtime.ts index 4ac8ab4..5260185 100644 --- a/src/runtime/local-runtime.ts +++ b/src/runtime/local-runtime.ts @@ -1295,29 +1295,44 @@ const NETWORK_UNREACHABLE_CODES = new Set([ ]); const DEFAULT_HOSTED_HOSTS = new Set(["crosshead.sh", "www.crosshead.sh"]); -const fetchCauseCodes = (error: unknown, depth = 0): string[] => { +type FetchCause = { code: string | null; message: string }; +const fetchCauses = (error: unknown, depth = 0): FetchCause[] => { if (!error || typeof error !== "object" || depth > 4) return []; - const record = error as { code?: unknown; cause?: unknown; errors?: unknown }; + const record = error as { code?: unknown; message?: unknown; cause?: unknown; errors?: unknown }; return [ - ...(typeof record.code === "string" ? [record.code] : []), - ...fetchCauseCodes(record.cause, depth + 1), - ...(Array.isArray(record.errors) ? record.errors.flatMap((entry) => fetchCauseCodes(entry, depth + 1)) : []), + { code: typeof record.code === "string" ? record.code : null, message: typeof record.message === "string" ? record.message : "" }, + ...fetchCauses(record.cause, depth + 1), + ...(Array.isArray(record.errors) ? record.errors.flatMap((entry) => fetchCauses(entry, depth + 1)) : []), ]; }; +// An egress proxy that refuses the tunnel (a sandbox allowlist, a corporate proxy) is the network +// saying "not from here", the same as a refused connection. +const PROXY_REFUSAL = /Proxy response \((\d{3})\) !== 200 when HTTP Tunneling/; + +/** A one-line description of why a fetch failed, for error messages: the deepest specific cause. */ +export const describeFetchFailure = (error: unknown): string => { + const causes = error instanceof Error ? fetchCauses(error.cause) : []; + const specific = causes.filter((cause) => cause.code || cause.message).at(-1); + if (!specific) return error instanceof Error ? error.message : String(error); + return [specific.code, specific.message].filter(Boolean).join(": ").slice(0, 200); +}; /** * Why the hosted service could not be reached at all, or null when the failure is something - * setup must report: an HTTP answer, a failed challenge, a redirect, a certificate or proxy - * error, or a host name that does not exist. A name that does not resolve is treated as offline + * setup must report: an HTTP answer, a failed challenge, a redirect, a certificate error, or a + * host name that does not exist. A proxy that refuses the tunnel counts as unreachable. A name that does not resolve is treated as offline * only for the default service, where it means DNS is unavailable rather than a typo. */ export const hostedServiceUnreachableReason = (error: unknown, apiBase: string): string | null => { if (!(error instanceof Error) || error instanceof HostedOnlyBotsRequestError) return null; if (error.name === "TimeoutError" || error.name === "AbortError") return "timed out"; if (error.name !== "TypeError" || !/fetch failed/i.test(error.message)) return null; - const codes = fetchCauseCodes(error.cause); + const causes = fetchCauses(error.cause); + const codes = causes.flatMap((cause) => (cause.code ? [cause.code] : [])); const unreachable = codes.find((code) => NETWORK_UNREACHABLE_CODES.has(code)); if (unreachable) return unreachable; + const proxy = causes.map((cause) => PROXY_REFUSAL.exec(cause.message)).find(Boolean); + if (proxy) return `proxy refused the connection (HTTP ${proxy[1]})`; if (codes.includes("ENOTFOUND")) { let host = ""; try { host = new URL(apiBase).hostname; } catch { /* an invalid URL fails elsewhere */ } @@ -1363,7 +1378,13 @@ export const setupRuntimeProfile = async (options: SetupRuntimeProfileOptions): session: secret?.session ?? null, }).ensureSession().catch((error: unknown) => { const reason = hostedServiceUnreachableReason(error, options.apiBase); - if (reason === null) throw error; + if (reason === null) { + // Name the real cause: a bare "fetch failed" hides a typo in --api-base or a certificate problem. + if (error instanceof TypeError && /fetch failed/i.test(error.message)) { + throw new Error(`Could not sign in to ${options.apiBase}: ${describeFetchFailure(error)}. Check --api-base.`, { cause: error }); + } + throw error; + } registrationDeferred = true; registrationDeferredReason = reason; return null; diff --git a/src/runtime/runtime-status.ts b/src/runtime/runtime-status.ts index 416ff01..4a20072 100644 --- a/src/runtime/runtime-status.ts +++ b/src/runtime/runtime-status.ts @@ -536,7 +536,11 @@ export const buildDoctorReport = async (paths: RuntimePaths, profileName?: strin checks.push({ id: "profile", ok: !selectedName || profileValid, message: !selectedName ? "No profile configured yet." : profileValid ? `Profile ${selectedName} is valid.` : existsSync(profileFile(paths, selectedName)) ? `Profile ${selectedName} is invalid; restore its configuration.` : `Profile ${selectedName} is missing.` }); - if (selectedProfile && profileValid) { + if (selectedProfile && profileValid && isLocalOnlyRuntimeProfile(selectedProfile)) { + // A local-only profile never contacts a hosted service, so there is nothing to reach or sign in to. + checks.push({ id: "api_base", ok: true, message: "Local-only profile; no hosted service is used." }); + checks.push({ id: "auth", ok: true, message: "Local-only profile; hosted sign-in is not used." }); + } else if (selectedProfile && profileValid) { try { const secret = loadSecret(paths, selectedProfile.name); const hosted = new HostedOnlyBotsClient({ diff --git a/tests/runtime/offline-setup.test.ts b/tests/runtime/offline-setup.test.ts index 376622a..befdb56 100644 --- a/tests/runtime/offline-setup.test.ts +++ b/tests/runtime/offline-setup.test.ts @@ -9,7 +9,7 @@ import { afterEach, describe, expect, it, vi } from "vitest"; import { keygenFromCli } from "../../src/runtime/cli/core"; import { HostedOnlyBotsRequestError } from "../../src/runtime/hosted-client"; -import { hostedServiceUnreachableReason, setupRuntimeProfile } from "../../src/runtime/local-runtime"; +import { describeFetchFailure, hostedServiceUnreachableReason, setupRuntimeProfile } from "../../src/runtime/local-runtime"; import { loadProfile, loadSecret, resolveRuntimePaths } from "../../src/runtime/runtime-persistence"; import { buildRuntimeDoctorDirect } from "../../src/runtime/runtime-status"; @@ -86,7 +86,7 @@ describe("setup when the hosted service cannot be reached", () => { vi.stubGlobal("fetch", vi.fn().mockRejectedValue(typo)); const home = newHome(); await expect(setupRuntimeProfile({ home, profileName: "default", apiBase: "https://crossheed.sh", ...identity(), makeDefault: true })) - .rejects.toThrow("fetch failed"); + .rejects.toThrow("Could not sign in to https://crossheed.sh: ENOTFOUND: getaddrinfo ENOTFOUND crossheed.sh. Check --api-base."); expect(loadProfile(resolveRuntimePaths(home), "default")).toBeNull(); }); }); @@ -108,6 +108,19 @@ describe("doctor after a deferred setup", () => { }); }); +describe("doctor on a local-only profile", () => { + it("does not report a missing sign-in", async () => { + const home = newHome(); + const fetchMock = unreachable(); + vi.stubGlobal("fetch", fetchMock); + await setupRuntimeProfile({ home, profileName: "default", apiBase: "http://127.0.0.1:0", ...identity(), makeDefault: true }); + const checks = (await buildRuntimeDoctorDirect(home, "default")).checks; + expect(checks.find((check) => check.id === "auth")).toMatchObject({ ok: true, message: expect.stringContaining("Local-only") }); + expect(checks.find((check) => check.id === "api_base")?.ok).toBe(true); + expect(fetchMock).not.toHaveBeenCalled(); + }); +}); + describe("classifying hosted sign-in failures", () => { const failed = (cause: unknown) => new TypeError("fetch failed", { cause }); const coded = (code: string) => Object.assign(new Error(code), { code }); @@ -120,6 +133,17 @@ describe("classifying hosted sign-in failures", () => { // DNS failing for the default service means DNS is unavailable; for any other host it is more likely a typo. expect(hostedServiceUnreachableReason(failed(coded("ENOTFOUND")), "https://crosshead.sh")).toBe("ENOTFOUND"); expect(hostedServiceUnreachableReason(failed(coded("ENOTFOUND")), "https://crossheed.sh")).toBeNull(); + // An allowlisting egress proxy refusing the tunnel, exactly as Node 26 reports it. + const proxyRefusal = failed(Object.assign(new Error("Request was cancelled."), { + cause: Object.assign(new Error("Proxy response (403) !== 200 when HTTP Tunneling"), { code: "UND_ERR_ABORTED" }), + })); + expect(hostedServiceUnreachableReason(proxyRefusal, "https://crosshead.sh")).toBe("proxy refused the connection (HTTP 403)"); + }); + + it("names the underlying cause of a fetch failure", () => { + expect(describeFetchFailure(failed(coded("CERT_HAS_EXPIRED")))).toBe("CERT_HAS_EXPIRED: CERT_HAS_EXPIRED"); + expect(describeFetchFailure(failed(new Error("unexpected redirect")))).toBe("unexpected redirect"); + expect(describeFetchFailure(failed(undefined))).toBe("fetch failed"); }); it("reports redirects, certificate errors, HTTP answers and unexplained failures", () => { From 04ebe14e64e907acbf67b99a4dd9ce0a17fe2115 Mon Sep 17 00:00:00 2001 From: Josh Winters Date: Sun, 15 Nov 2026 14:55:12 -0500 Subject: [PATCH 4/5] Tighten which sign-in failures defer setup; consistent deferral output Defer also for sandbox connect() denials (EPERM, EACCES) and EAI_FAIL / EADDRNOTAVAIL. Fail instead of deferring for a refused loopback address, a listener that drops the connection (UND_ERR_SOCKET), and proxy responses other than 403. Errors name the cause once, mention HTTPS_PROXY for proxy failures, and explain a 404 from a non-Crosshead address. Doctor reports a network failure's cause and an HTTP failure's status and code only, never server-chosen text, and no longer claims a profile whose session was cleared has never signed in. keygen, quickstart and guided setup now all report registrationDeferred: true with registrationDeferredReason. The CLI test runs the real CLI with fetch stubbed before load. --- README.md | 9 ++++- src/runtime/cli/quickstart.ts | 9 ++++- src/runtime/cli/workspace.ts | 3 +- src/runtime/hosted-client.ts | 23 ++++++++++++ src/runtime/local-runtime.ts | 51 ++++++++++---------------- src/runtime/runtime-status.ts | 11 ++++-- tests/runtime/offline-setup.test.ts | 57 +++++++++++++++++------------ 7 files changed, 100 insertions(+), 63 deletions(-) diff --git a/README.md b/README.md index 98e40c3..7d0bd5a 100644 --- a/README.md +++ b/README.md @@ -177,8 +177,13 @@ be refused; `crosshead doctor` reports a profile that has never signed in and why. Setup still fails when the problem is the address rather than the network: a -response that refuses the sign-in, a redirect, a certificate error, or (for any -`--api-base` other than `crosshead.sh`) a host name that does not exist. +response that refuses the sign-in, a redirect, a certificate error, a refused +connection to this machine (`localhost`, `127.0.0.1`), a proxy asking for +credentials or failing upstream, or (for any `--api-base` other than +`crosshead.sh`) a host name that does not exist. A proxy that refuses the +destination (HTTP 403) counts as unreachable. A proxy that intercepts TLS and +answers with its own page or certificate is not recognised and fails setup; +use the local-only profile below in that case. For a profile that never contacts a hosted service, pass `--api-base http://127.0.0.1:0`. Hot memory, hooks and handoff capsules work; diff --git a/src/runtime/cli/quickstart.ts b/src/runtime/cli/quickstart.ts index 89b1692..55a0684 100644 --- a/src/runtime/cli/quickstart.ts +++ b/src/runtime/cli/quickstart.ts @@ -205,17 +205,21 @@ export const quickstartFromCli = async (argv: string[], paths: QuickstartCliPath const config = loadRuntimeConfig(runtimePaths); const existingProfile = loadProfile(runtimePaths, profileName); + let registration: { registrationDeferred: true; registrationDeferredReason: string | null } | null = null; if (!existingProfile) { if (!apiBase) { throw new Error("quickstart requires --api-base when the selected profile does not exist"); } const profileOutput = await keygenFromCli([...profileArgs, "--setup", "--json"]); - const parsed = JSON.parse(profileOutput) as { npub?: string; apiBase?: string; registrationDeferred?: boolean }; + const parsed = JSON.parse(profileOutput) as { npub?: string; apiBase?: string; registrationDeferred?: boolean; registrationDeferredReason?: string | null }; + if (parsed.registrationDeferred) registration = { registrationDeferred: true, registrationDeferredReason: parsed.registrationDeferredReason ?? null }; steps.push({ id: "profile", ok: true, detail: `configured ${profileName} for ${parsed.apiBase ?? apiBase} with generated runtime identity ${parsed.npub ?? "unknown"}${ - parsed.registrationDeferred ? "; the service could not be reached, so sign-in is deferred until it can (local capture and recall work now)" : "" + parsed.registrationDeferred + ? `; the service could not be reached${parsed.registrationDeferredReason ? ` (${parsed.registrationDeferredReason})` : ""}, so sign-in is deferred until it can (local capture and recall work now)` + : "" }`, }); } else { @@ -307,6 +311,7 @@ export const quickstartFromCli = async (argv: string[], paths: QuickstartCliPath firstValueCommand: `crosshead memory hot --home ${runtimePaths.home} --profile ${profileName}`, billingCommand: `crosshead billing status --home ${runtimePaths.home} --profile ${profileName}`, paymentBoundary: "Agents may create/show checkout links or invoices, but a human must submit payment.", + ...(registration ?? {}), }; return flags.json ? JSON.stringify(result, null, 2) : formatQuickstart(result); }; diff --git a/src/runtime/cli/workspace.ts b/src/runtime/cli/workspace.ts index 242f1c8..84f4866 100644 --- a/src/runtime/cli/workspace.ts +++ b/src/runtime/cli/workspace.ts @@ -255,7 +255,8 @@ export const scopedQuickstartFromCli = async (flags: Flags, scripts: QuickstartC const checks = scope === "project" ? [...new Set(targets.map((target) => workspaceProjectRoot(target.directory)))] : [process.cwd()]; return flags.json ? JSON.stringify({ command: "quickstart", applied: true, home: paths.home, profiles: names, daemon, ...inspection, - ...(deferred.length > 0 ? { registrationDeferred: deferred } : {}) }, null, 2) + // Same fields as keygen and quickstart; one entry per profile created here. + ...(deferred.length > 0 ? { registrationDeferred: true, registrationDeferredReason: deferred[0]!.reason, registrationDeferredProfiles: deferred } : {}) }, null, 2) : [ "Crosshead setup complete.", ...deferred.flatMap((entry) => registrationDeferredLines({ apiBase: entry.apiBase, registrationDeferred: true, registrationDeferredReason: entry.reason ?? undefined }) diff --git a/src/runtime/hosted-client.ts b/src/runtime/hosted-client.ts index a5fe35d..9977748 100644 --- a/src/runtime/hosted-client.ts +++ b/src/runtime/hosted-client.ts @@ -246,6 +246,29 @@ export class HostedOnlyBotsRequestError extends Error { } } +export type FetchCause = { code: string | null; message: string }; +export const fetchCauses = (error: unknown, depth = 0): FetchCause[] => { + if (!error || typeof error !== "object" || depth > 4) return []; + const record = error as { code?: unknown; message?: unknown; cause?: unknown; errors?: unknown }; + return [ + { code: typeof record.code === "string" ? record.code : null, message: typeof record.message === "string" ? record.message : "" }, + ...fetchCauses(record.cause, depth + 1), + ...(Array.isArray(record.errors) ? record.errors.flatMap((entry) => fetchCauses(entry, depth + 1)) : []), + ]; +}; +// An egress proxy that refuses the tunnel (a sandbox allowlist, a corporate proxy) is the network +// saying "not from here", the same as a refused connection. +export const PROXY_REFUSAL = /Proxy response \((\d{3})\) !== 200 when HTTP Tunneling/; + +/** A one-line description of why a fetch failed, for error messages: the deepest specific cause. */ +export const describeFetchFailure = (error: unknown): string => { + const causes = error instanceof Error ? fetchCauses(error.cause) : []; + const specific = causes.filter((cause) => cause.code || cause.message).at(-1); + if (!specific) return error instanceof Error ? error.message : String(error); + const message = specific.code && specific.message.includes(specific.code) ? specific.message : [specific.code, specific.message].filter(Boolean).join(": "); + return message.slice(0, 200); +}; + /** * Classify a failed hosted request for local diagnostics without copying its * message, URL, headers or body: a timeout, an HTTP status/code, or an error name. diff --git a/src/runtime/local-runtime.ts b/src/runtime/local-runtime.ts index 5260185..27f9eb0 100644 --- a/src/runtime/local-runtime.ts +++ b/src/runtime/local-runtime.ts @@ -28,7 +28,8 @@ import * as tar from "tar"; import { OperatorRuntimePolicyBroker, type OperatorWorkspaceManifest } from "./operator-policy"; import { HOSTED_PI_CONTROLLER_ADAPTER, HOSTED_PI_CONTROLLER_MANIFEST, hostedControllerProcessIsLive, type HostedControllerProcess } from "./hosted-pi-controller-manifest"; import { acquireRuntimeDaemonOwnership, daemonOwnerIsLive, probeRuntimeDaemonHealth, readDaemonOwnershipState, type RuntimeDaemonOwnership } from "./daemon-ownership"; -import { HostedOnlyBotsClient, HostedOnlyBotsRequestError, type HostedSession } from "./hosted-client"; +import { describeFetchFailure, fetchCauses, HostedOnlyBotsClient, HostedOnlyBotsRequestError, PROXY_REFUSAL, type HostedSession } from "./hosted-client"; +export { describeFetchFailure } from "./hosted-client"; import { isLocalOnlyRuntimeProfile, preserveLegacyLocalHotOwner, readLocalHotMemory } from "./local-hot-memory"; import { searchHotCheckpoints } from "./hot-continuity"; import { @@ -1291,32 +1292,12 @@ export const uninstallRuntimeCore = async (home?: string): Promise => { // error means something answered, or the address is wrong, and setup must say so instead. const NETWORK_UNREACHABLE_CODES = new Set([ "ECONNREFUSED", "ENETUNREACH", "EHOSTUNREACH", "ENETDOWN", "EHOSTDOWN", "ETIMEDOUT", "ECONNRESET", - "EAI_AGAIN", "EPIPE", "UND_ERR_CONNECT_TIMEOUT", "UND_ERR_SOCKET", + "EAI_AGAIN", "EAI_FAIL", "EADDRNOTAVAIL", "EPIPE", "UND_ERR_CONNECT_TIMEOUT", + // Sandboxes (macOS seatbelt, Linux seccomp) deny connect() itself with these. + "EPERM", "EACCES", ]); const DEFAULT_HOSTED_HOSTS = new Set(["crosshead.sh", "www.crosshead.sh"]); -type FetchCause = { code: string | null; message: string }; -const fetchCauses = (error: unknown, depth = 0): FetchCause[] => { - if (!error || typeof error !== "object" || depth > 4) return []; - const record = error as { code?: unknown; message?: unknown; cause?: unknown; errors?: unknown }; - return [ - { code: typeof record.code === "string" ? record.code : null, message: typeof record.message === "string" ? record.message : "" }, - ...fetchCauses(record.cause, depth + 1), - ...(Array.isArray(record.errors) ? record.errors.flatMap((entry) => fetchCauses(entry, depth + 1)) : []), - ]; -}; -// An egress proxy that refuses the tunnel (a sandbox allowlist, a corporate proxy) is the network -// saying "not from here", the same as a refused connection. -const PROXY_REFUSAL = /Proxy response \((\d{3})\) !== 200 when HTTP Tunneling/; - -/** A one-line description of why a fetch failed, for error messages: the deepest specific cause. */ -export const describeFetchFailure = (error: unknown): string => { - const causes = error instanceof Error ? fetchCauses(error.cause) : []; - const specific = causes.filter((cause) => cause.code || cause.message).at(-1); - if (!specific) return error instanceof Error ? error.message : String(error); - return [specific.code, specific.message].filter(Boolean).join(": ").slice(0, 200); -}; - /** * Why the hosted service could not be reached at all, or null when the failure is something * setup must report: an HTTP answer, a failed challenge, a redirect, a certificate error, or a @@ -1329,15 +1310,17 @@ export const hostedServiceUnreachableReason = (error: unknown, apiBase: string): if (error.name !== "TypeError" || !/fetch failed/i.test(error.message)) return null; const causes = fetchCauses(error.cause); const codes = causes.flatMap((cause) => (cause.code ? [cause.code] : [])); - const unreachable = codes.find((code) => NETWORK_UNREACHABLE_CODES.has(code)); + let host = ""; + try { host = new URL(apiBase).hostname; } catch { /* an invalid URL fails elsewhere */ } + // Nothing listening on this machine is a wrong port or a stopped local server, not being offline. + const loopback = /^(localhost|127(\.\d{1,3}){3}|\[?::1\]?)$/i.test(host); + const unreachable = codes.find((code) => NETWORK_UNREACHABLE_CODES.has(code) && !(loopback && code === "ECONNREFUSED")); if (unreachable) return unreachable; + // Only a proxy that forbids the destination means "not from here". 407 is missing proxy + // credentials and 502/504 usually a host the proxy could not resolve: both need fixing, not waiting. const proxy = causes.map((cause) => PROXY_REFUSAL.exec(cause.message)).find(Boolean); - if (proxy) return `proxy refused the connection (HTTP ${proxy[1]})`; - if (codes.includes("ENOTFOUND")) { - let host = ""; - try { host = new URL(apiBase).hostname; } catch { /* an invalid URL fails elsewhere */ } - return DEFAULT_HOSTED_HOSTS.has(host) ? "ENOTFOUND" : null; - } + if (proxy?.[1] === "403") return "proxy refused the connection (HTTP 403)"; + if (codes.includes("ENOTFOUND")) return DEFAULT_HOSTED_HOSTS.has(host) ? "ENOTFOUND" : null; return null; }; @@ -1381,7 +1364,11 @@ export const setupRuntimeProfile = async (options: SetupRuntimeProfileOptions): if (reason === null) { // Name the real cause: a bare "fetch failed" hides a typo in --api-base or a certificate problem. if (error instanceof TypeError && /fetch failed/i.test(error.message)) { - throw new Error(`Could not sign in to ${options.apiBase}: ${describeFetchFailure(error)}. Check --api-base.`, { cause: error }); + throw new Error(`Could not sign in to ${options.apiBase}: ${describeFetchFailure(error)}. Check --api-base${ + /Proxy response/.test(describeFetchFailure(error)) ? " and the HTTPS_PROXY settings" : ""}.`, { cause: error }); + } + if (error instanceof HostedOnlyBotsRequestError && error.status === 404) { + throw new Error(`Could not sign in to ${options.apiBase}: it answered 404, so it is probably not a Crosshead service. Check --api-base.`, { cause: error }); } throw error; } diff --git a/src/runtime/runtime-status.ts b/src/runtime/runtime-status.ts index 4a20072..ac8d4f4 100644 --- a/src/runtime/runtime-status.ts +++ b/src/runtime/runtime-status.ts @@ -5,7 +5,7 @@ import { existsSync } from "fs"; import path from "path"; import { daemonOwnerIsLive, probeRuntimeDaemonHealth, readDaemonOwnershipState } from "./daemon-ownership"; -import { HostedOnlyBotsClient, type HostedSession } from "./hosted-client"; +import { describeFetchFailure, describeHostedFailure, HostedOnlyBotsClient, type HostedSession } from "./hosted-client"; import { readRuntimeDreamReviewHudSnapshot, readRuntimeInboxHudSnapshot, @@ -568,7 +568,12 @@ export const buildDoctorReport = async (paths: RuntimePaths, profileName?: strin authValid = isSessionFresh(session); } catch (error) { authValid = false; - signInError = error instanceof Error ? error.message.slice(0, 200) : String(error).slice(0, 200); + // The cause for a network failure; for an HTTP answer only the status and code, never + // text the server chose (see describeHostedFailure). + const hosted = describeHostedFailure(error); + signInError = error instanceof TypeError && /fetch failed/i.test(error.message) + ? describeFetchFailure(error) + : hosted.errorClass === "http" ? `HTTP ${hosted.status}${hosted.code ? ` ${hosted.code}` : ""}` : String(hosted.errorClass); } } // A profile set up while the service was unreachable has never held a session. Say so, @@ -580,7 +585,7 @@ export const buildDoctorReport = async (paths: RuntimePaths, profileName?: strin message: authValid ? "Hosted auth session is valid." : neverSignedIn - ? `This profile has not signed in to ${selectedProfile.apiBase} yet${signInError ? `; sign-in failed: ${signInError}` : ""}.` + ? `This profile has no session with ${selectedProfile.apiBase}: it has not signed in yet, or its session was cleared${signInError ? `; sign-in failed: ${signInError}` : ""}.` : `Hosted auth session is missing or expired${signInError ? `; sign-in failed: ${signInError}` : ""}.`, }); } catch { diff --git a/tests/runtime/offline-setup.test.ts b/tests/runtime/offline-setup.test.ts index befdb56..76fa211 100644 --- a/tests/runtime/offline-setup.test.ts +++ b/tests/runtime/offline-setup.test.ts @@ -1,6 +1,5 @@ import { spawnSync } from "node:child_process"; -import { existsSync, mkdirSync, mkdtempSync, realpathSync, rmSync } from "node:fs"; -import { createServer } from "node:net"; +import { existsSync, mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs"; import os from "node:os"; import path from "node:path"; @@ -86,7 +85,7 @@ describe("setup when the hosted service cannot be reached", () => { vi.stubGlobal("fetch", vi.fn().mockRejectedValue(typo)); const home = newHome(); await expect(setupRuntimeProfile({ home, profileName: "default", apiBase: "https://crossheed.sh", ...identity(), makeDefault: true })) - .rejects.toThrow("Could not sign in to https://crossheed.sh: ENOTFOUND: getaddrinfo ENOTFOUND crossheed.sh. Check --api-base."); + .rejects.toThrow("Could not sign in to https://crossheed.sh: getaddrinfo ENOTFOUND crossheed.sh. Check --api-base."); expect(loadProfile(resolveRuntimePaths(home), "default")).toBeNull(); }); }); @@ -103,8 +102,10 @@ describe("doctor after a deferred setup", () => { ))); const auth = (await buildRuntimeDoctorDirect(home, "default")).checks.find((check) => check.id === "auth"); expect(auth?.ok).toBe(false); - expect(auth?.message).toContain("has not signed in to https://crosshead.sh yet"); - expect(auth?.message).toContain("registration closed"); + expect(auth?.message).toContain("has no session with https://crosshead.sh"); + // Status and code only: text chosen by the server is not copied into local output. + expect(auth?.message).toContain("sign-in failed: HTTP 403 forbidden"); + expect(auth?.message).not.toContain("registration closed"); }); }); @@ -138,10 +139,14 @@ describe("classifying hosted sign-in failures", () => { cause: Object.assign(new Error("Proxy response (403) !== 200 when HTTP Tunneling"), { code: "UND_ERR_ABORTED" }), })); expect(hostedServiceUnreachableReason(proxyRefusal, "https://crosshead.sh")).toBe("proxy refused the connection (HTTP 403)"); + // A sandbox that denies connect() itself. + expect(hostedServiceUnreachableReason(failed(coded("EPERM")), "https://crosshead.sh")).toBe("EPERM"); + expect(hostedServiceUnreachableReason(failed(coded("EADDRNOTAVAIL")), "https://crosshead.sh")).toBe("EADDRNOTAVAIL"); }); it("names the underlying cause of a fetch failure", () => { - expect(describeFetchFailure(failed(coded("CERT_HAS_EXPIRED")))).toBe("CERT_HAS_EXPIRED: CERT_HAS_EXPIRED"); + expect(describeFetchFailure(failed(Object.assign(new Error("certificate has expired"), { code: "CERT_HAS_EXPIRED" })))).toBe("CERT_HAS_EXPIRED: certificate has expired"); + expect(describeFetchFailure(failed(Object.assign(new Error("getaddrinfo ENOTFOUND x.test"), { code: "ENOTFOUND" })))).toBe("getaddrinfo ENOTFOUND x.test"); expect(describeFetchFailure(failed(new Error("unexpected redirect")))).toBe("unexpected redirect"); expect(describeFetchFailure(failed(undefined))).toBe("fetch failed"); }); @@ -151,6 +156,14 @@ describe("classifying hosted sign-in failures", () => { expect(hostedServiceUnreachableReason(failed(coded("CERT_HAS_EXPIRED")), "https://crosshead.sh")).toBeNull(); expect(hostedServiceUnreachableReason(failed(coded("ERR_TLS_CERT_ALTNAME_INVALID")), "https://crosshead.sh")).toBeNull(); expect(hostedServiceUnreachableReason(failed(undefined), "https://crosshead.sh")).toBeNull(); + // Nothing listening on this machine is a wrong port or a stopped local server. + expect(hostedServiceUnreachableReason(failed(coded("ECONNREFUSED")), "http://127.0.0.1:8788")).toBeNull(); + expect(hostedServiceUnreachableReason(failed(coded("ECONNREFUSED")), "http://localhost:8788")).toBeNull(); + // A listener that accepts and drops the connection answered; so did a proxy asking for credentials or failing upstream. + expect(hostedServiceUnreachableReason(failed(coded("UND_ERR_SOCKET")), "https://crosshead.sh")).toBeNull(); + for (const status of ["407", "502", "504"]) { + expect(hostedServiceUnreachableReason(failed(new Error(`Proxy response (${status}) !== 200 when HTTP Tunneling`)), "https://crosshead.sh")).toBeNull(); + } expect(hostedServiceUnreachableReason(new HostedOnlyBotsRequestError({ message: "nope", status: 503 }), "https://crosshead.sh")).toBeNull(); expect(hostedServiceUnreachableReason(new Error("Invalid challenge"), "https://crosshead.sh")).toBeNull(); }); @@ -158,18 +171,9 @@ describe("classifying hosted sign-in failures", () => { describe("guided project setup with no connection", () => { const cliScript = path.resolve(__dirname, "../../dist/runtime/cli.js"); + // npm test builds dist first; a stale build would test old code. - // A port that was free a moment ago, so a connection to it is refused. (Fetch blocks low ports - // such as 1 outright with "bad port", which is rightly not treated as offline.) - const closedPort = () => new Promise((resolve) => { - const server = createServer().listen(0, "127.0.0.1", () => { - const { port } = server.address() as { port: number }; - server.close(() => resolve(port)); - }); - }); - - it("reports the deferred sign-in instead of only 'setup complete', using Node's real refused-connection error", async () => { - const apiBase = `http://127.0.0.1:${await closedPort()}`; + it("reports the deferred sign-in instead of only 'setup complete', in text and JSON", () => { const root = realpathSync(newHome()); const home = path.join(root, "runtime"); const project = path.join(root, "project"); @@ -177,16 +181,23 @@ describe("guided project setup with no connection", () => { expect(spawnSync("git", ["init", "-q", project]).status).toBe(0); mkdirSync(path.join(root, "codex"), { recursive: true }); mkdirSync(path.join(root, "claude"), { recursive: true }); - // Nothing listens on port 1, so the connection is refused immediately. - const run = spawnSync(process.execPath, [ - cliScript, "quickstart", "--scope", "project", "--adapter", "both", "--workspace-root", project, "--profile", "work", - "--api-base", apiBase, "--no-start", "--codex-home", path.join(root, "codex"), "--claude-home", path.join(root, "claude"), - "--home", home, + // The real CLI, with fetch replaced before it loads so no request leaves the machine: every + // connection is refused the way Node reports it when there is no route to the service. + const stub = path.join(root, "offline-fetch.mjs"); + writeFileSync(stub, `globalThis.fetch = async () => { throw new TypeError("fetch failed", { cause: Object.assign(new Error("connect ECONNREFUSED 203.0.113.1:443"), { code: "ECONNREFUSED" }) }); };\n`); + const quickstart = (profile: string, ...extra: string[]) => spawnSync(process.execPath, [ + "--import", stub, cliScript, "quickstart", "--scope", "project", "--adapter", "both", "--workspace-root", project, "--profile", profile, + "--api-base", "https://crosshead.sh", "--no-start", "--codex-home", path.join(root, "codex"), "--claude-home", path.join(root, "claude"), + "--home", home, ...extra, ], { env: { PATH: process.env.PATH, CROSSHEAD_HOOK_AUTOSTART: "0" }, encoding: "utf8", timeout: 20000 }); + const run = quickstart("work"); expect(run.status, run.stderr || run.stdout).toBe(0); expect(run.stdout).toContain("Crosshead setup complete."); expect(run.stdout).toContain("work registration: deferred"); expect(run.stdout).toContain("ECONNREFUSED"); - expect(loadProfile(resolveRuntimePaths(home), "work")).toMatchObject({ apiBase }); + const json = quickstart("second", "--json"); + expect(json.status, json.stderr || json.stdout).toBe(0); + expect(JSON.parse(json.stdout)).toMatchObject({ registrationDeferred: true, registrationDeferredReason: "ECONNREFUSED" }); + expect(loadProfile(resolveRuntimePaths(home), "work")).toMatchObject({ apiBase: "https://crosshead.sh" }); }, 30_000); }); From 69640e98c8298b9b545d6536a05842e6f0723492 Mon Sep 17 00:00:00 2001 From: Josh Winters Date: Sun, 15 Nov 2026 15:09:33 -0500 Subject: [PATCH 5/5] Never echo remote text in setup or doctor errors; never defer for loopback Fetch failures are described by error code (with a short label), undici's own fixed messages, or a proxy status only: free-text causes can carry text chosen by the other end, such as names in a mismatched TLS certificate. Any failure to reach a loopback address (localhost, *.localhost, 127/8, 0.0.0.0, ::1), including a timeout, fails setup instead of deferring. The 404 explanation keeps HostedOnlyBotsRequestError so --json still reports the status and code. setup gains --json with the deferral fields; plain quickstart text says 'registration: deferred'. README notes that Node uses HTTPS_PROXY only with NODE_USE_ENV_PROXY=1. --- README.md | 6 ++-- src/runtime/cli/core.ts | 6 ++++ src/runtime/cli/quickstart.ts | 2 +- src/runtime/hosted-client.ts | 35 ++++++++++++++++--- src/runtime/local-runtime.ts | 22 +++++++----- src/runtime/runtime-status.ts | 3 +- tests/runtime/offline-setup.test.ts | 54 ++++++++++++++++++++++++++--- 7 files changed, 106 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index 7d0bd5a..90f1dc7 100644 --- a/README.md +++ b/README.md @@ -171,7 +171,8 @@ project. Setup does not need the hosted service to be reachable. If `crosshead.sh` cannot be reached (a sandbox with restricted egress, a CI job, a laptop offline), the profile is still created and setup prints `registration: -deferred` with the network error. Capture and recall work locally at once, and +deferred` with the network error (`--json` output carries +`registrationDeferred` and `registrationDeferredReason`). Capture and recall work locally at once, and the profile tries to sign in on its next hosted request. That sign-in can still be refused; `crosshead doctor` reports a profile that has never signed in and why. @@ -181,7 +182,8 @@ response that refuses the sign-in, a redirect, a certificate error, a refused connection to this machine (`localhost`, `127.0.0.1`), a proxy asking for credentials or failing upstream, or (for any `--api-base` other than `crosshead.sh`) a host name that does not exist. A proxy that refuses the -destination (HTTP 403) counts as unreachable. A proxy that intercepts TLS and +destination (HTTP 403) counts as unreachable; Node uses `HTTPS_PROXY` only when +`NODE_USE_ENV_PROXY=1` is set, and otherwise connects directly. A proxy that intercepts TLS and answers with its own page or certificate is not recognised and fails setup; use the local-only profile below in that case. diff --git a/src/runtime/cli/core.ts b/src/runtime/cli/core.ts index 80aaee9..3cbae19 100644 --- a/src/runtime/cli/core.ts +++ b/src/runtime/cli/core.ts @@ -131,6 +131,12 @@ export const setupProfileFromCli = async (argv: string[]): Promise => { npub: String(flags.npub ?? ""), nsec: String(flags.nsec ?? ""), }); + if (flags.json) { + return JSON.stringify({ + profile: profile.name, npub: profile.npub, apiBase: profile.apiBase, memoryMode: profile.memoryMode, + ...(profile.registrationDeferred ? { registrationDeferred: true, registrationDeferredReason: profile.registrationDeferredReason ?? null } : {}), + }, null, 2); + } return [`Configured runtime profile ${profile.name} for ${profile.npub}`, ...registrationDeferredLines(profile)].join("\n"); }; diff --git a/src/runtime/cli/quickstart.ts b/src/runtime/cli/quickstart.ts index 55a0684..cfbbba6 100644 --- a/src/runtime/cli/quickstart.ts +++ b/src/runtime/cli/quickstart.ts @@ -218,7 +218,7 @@ export const quickstartFromCli = async (argv: string[], paths: QuickstartCliPath ok: true, detail: `configured ${profileName} for ${parsed.apiBase ?? apiBase} with generated runtime identity ${parsed.npub ?? "unknown"}${ parsed.registrationDeferred - ? `; the service could not be reached${parsed.registrationDeferredReason ? ` (${parsed.registrationDeferredReason})` : ""}, so sign-in is deferred until it can (local capture and recall work now)` + ? `; registration: deferred, the service could not be reached${parsed.registrationDeferredReason ? ` (${parsed.registrationDeferredReason})` : ""}; local capture and recall work now and sign-in happens on the next hosted request` : "" }`, }); diff --git a/src/runtime/hosted-client.ts b/src/runtime/hosted-client.ts index 9977748..049ccc6 100644 --- a/src/runtime/hosted-client.ts +++ b/src/runtime/hosted-client.ts @@ -260,13 +260,38 @@ export const fetchCauses = (error: unknown, depth = 0): FetchCause[] => { // saying "not from here", the same as a refused connection. export const PROXY_REFUSAL = /Proxy response \((\d{3})\) !== 200 when HTTP Tunneling/; -/** A one-line description of why a fetch failed, for error messages: the deepest specific cause. */ +const FETCH_CODE_LABELS: Record = { + ENOTFOUND: "host name not found", + EAI_AGAIN: "DNS lookup unavailable", + EAI_FAIL: "DNS lookup failed", + ECONNREFUSED: "connection refused", + ECONNRESET: "connection reset", + ETIMEDOUT: "connection timed out", + UND_ERR_CONNECT_TIMEOUT: "connection timed out", + ENETUNREACH: "network unreachable", + EHOSTUNREACH: "host unreachable", + EPERM: "connection not permitted", + EACCES: "connection not permitted", + UND_ERR_SOCKET: "connection closed by the other side", +}; +// Fixed strings that undici itself produces; anything else may carry text from the other end. +const FIXED_FETCH_MESSAGES = new Set(["unexpected redirect", "bad port"]); +const SAFE_FETCH_CODE = /^[A-Z][A-Z0-9_]{1,63}$/; + +/** + * A one-line, locally safe description of why a fetch failed. Only error codes, undici's own + * fixed messages and a proxy's status are used: free-text cause messages can carry text chosen by + * the remote end (for example the names in a mismatched TLS certificate). + */ export const describeFetchFailure = (error: unknown): string => { + if (error instanceof Error && (error.name === "TimeoutError" || error.name === "AbortError")) return "timed out"; const causes = error instanceof Error ? fetchCauses(error.cause) : []; - const specific = causes.filter((cause) => cause.code || cause.message).at(-1); - if (!specific) return error instanceof Error ? error.message : String(error); - const message = specific.code && specific.message.includes(specific.code) ? specific.message : [specific.code, specific.message].filter(Boolean).join(": "); - return message.slice(0, 200); + const proxy = causes.map((cause) => PROXY_REFUSAL.exec(cause.message)).find(Boolean); + if (proxy) return `proxy answered HTTP ${proxy[1]}`; + const code = causes.map((cause) => cause.code).filter((value): value is string => Boolean(value && SAFE_FETCH_CODE.test(value))).at(-1); + if (code) return FETCH_CODE_LABELS[code] ? `${FETCH_CODE_LABELS[code]} (${code})` : code; + const fixed = causes.map((cause) => cause.message.trim()).find((message) => FIXED_FETCH_MESSAGES.has(message)); + return fixed ?? "network request failed"; }; /** diff --git a/src/runtime/local-runtime.ts b/src/runtime/local-runtime.ts index 27f9eb0..c52b8d4 100644 --- a/src/runtime/local-runtime.ts +++ b/src/runtime/local-runtime.ts @@ -1306,15 +1306,16 @@ const DEFAULT_HOSTED_HOSTS = new Set(["crosshead.sh", "www.crosshead.sh"]); */ export const hostedServiceUnreachableReason = (error: unknown, apiBase: string): string | null => { if (!(error instanceof Error) || error instanceof HostedOnlyBotsRequestError) return null; + let host = ""; + try { host = new URL(apiBase).hostname; } catch { /* an invalid URL fails elsewhere */ } + // This machine cannot be "offline" from itself: any failure to reach a loopback address, + // including a timeout, is a wrong port or a stopped or hung local server, which setup must report. + if (/^(localhost\.?|.+\.localhost\.?|127(\.\d{1,3}){3}|0\.0\.0\.0|\[::1?\]|\[::ffff:7f[0-9a-f]{2}:[0-9a-f]{1,4}\])$/i.test(host)) return null; if (error.name === "TimeoutError" || error.name === "AbortError") return "timed out"; if (error.name !== "TypeError" || !/fetch failed/i.test(error.message)) return null; const causes = fetchCauses(error.cause); const codes = causes.flatMap((cause) => (cause.code ? [cause.code] : [])); - let host = ""; - try { host = new URL(apiBase).hostname; } catch { /* an invalid URL fails elsewhere */ } - // Nothing listening on this machine is a wrong port or a stopped local server, not being offline. - const loopback = /^(localhost|127(\.\d{1,3}){3}|\[?::1\]?)$/i.test(host); - const unreachable = codes.find((code) => NETWORK_UNREACHABLE_CODES.has(code) && !(loopback && code === "ECONNREFUSED")); + const unreachable = codes.find((code) => NETWORK_UNREACHABLE_CODES.has(code)); if (unreachable) return unreachable; // Only a proxy that forbids the destination means "not from here". 407 is missing proxy // credentials and 502/504 usually a host the proxy could not resolve: both need fixing, not waiting. @@ -1364,11 +1365,16 @@ export const setupRuntimeProfile = async (options: SetupRuntimeProfileOptions): if (reason === null) { // Name the real cause: a bare "fetch failed" hides a typo in --api-base or a certificate problem. if (error instanceof TypeError && /fetch failed/i.test(error.message)) { - throw new Error(`Could not sign in to ${options.apiBase}: ${describeFetchFailure(error)}. Check --api-base${ - /Proxy response/.test(describeFetchFailure(error)) ? " and the HTTPS_PROXY settings" : ""}.`, { cause: error }); + const reason = describeFetchFailure(error); + throw new Error(`Could not sign in to ${options.apiBase}: ${reason}. Check --api-base${ + reason.startsWith("proxy") ? " and the proxy settings (HTTPS_PROXY, NODE_USE_ENV_PROXY)" : ""}.`, { cause: error }); } if (error instanceof HostedOnlyBotsRequestError && error.status === 404) { - throw new Error(`Could not sign in to ${options.apiBase}: it answered 404, so it is probably not a Crosshead service. Check --api-base.`, { cause: error }); + // Keep the type, status and code: --json error output reports them. + throw new HostedOnlyBotsRequestError({ + message: `Could not sign in to ${options.apiBase}: it answered 404, so it is probably not a Crosshead service. Check --api-base.`, + status: error.status, code: error.code, details: error.details, retryAfterMs: error.retryAfterMs, + }); } throw error; } diff --git a/src/runtime/runtime-status.ts b/src/runtime/runtime-status.ts index ac8d4f4..0dca14e 100644 --- a/src/runtime/runtime-status.ts +++ b/src/runtime/runtime-status.ts @@ -573,7 +573,8 @@ export const buildDoctorReport = async (paths: RuntimePaths, profileName?: strin const hosted = describeHostedFailure(error); signInError = error instanceof TypeError && /fetch failed/i.test(error.message) ? describeFetchFailure(error) - : hosted.errorClass === "http" ? `HTTP ${hosted.status}${hosted.code ? ` ${hosted.code}` : ""}` : String(hosted.errorClass); + : hosted.errorClass === "http" ? `HTTP ${hosted.status}${hosted.code ? ` ${hosted.code}` : ""}` + : hosted.errorClass === "Error" ? "the service's sign-in challenge could not be used" : String(hosted.errorClass); } } // A profile set up while the service was unreachable has never held a session. Say so, diff --git a/tests/runtime/offline-setup.test.ts b/tests/runtime/offline-setup.test.ts index 76fa211..95c895c 100644 --- a/tests/runtime/offline-setup.test.ts +++ b/tests/runtime/offline-setup.test.ts @@ -6,7 +6,7 @@ import path from "node:path"; import { generateSecretKey, getPublicKey, nip19 } from "nostr-tools"; import { afterEach, describe, expect, it, vi } from "vitest"; -import { keygenFromCli } from "../../src/runtime/cli/core"; +import { keygenFromCli, setupProfileFromCli } from "../../src/runtime/cli/core"; import { HostedOnlyBotsRequestError } from "../../src/runtime/hosted-client"; import { describeFetchFailure, hostedServiceUnreachableReason, setupRuntimeProfile } from "../../src/runtime/local-runtime"; import { loadProfile, loadSecret, resolveRuntimePaths } from "../../src/runtime/runtime-persistence"; @@ -85,7 +85,7 @@ describe("setup when the hosted service cannot be reached", () => { vi.stubGlobal("fetch", vi.fn().mockRejectedValue(typo)); const home = newHome(); await expect(setupRuntimeProfile({ home, profileName: "default", apiBase: "https://crossheed.sh", ...identity(), makeDefault: true })) - .rejects.toThrow("Could not sign in to https://crossheed.sh: getaddrinfo ENOTFOUND crossheed.sh. Check --api-base."); + .rejects.toThrow("Could not sign in to https://crossheed.sh: host name not found (ENOTFOUND). Check --api-base."); expect(loadProfile(resolveRuntimePaths(home), "default")).toBeNull(); }); }); @@ -109,6 +109,40 @@ describe("doctor after a deferred setup", () => { }); }); +describe("doctor after a deferred setup, when the network is still down", () => { + it("names the cause by code without repeating text from the other end", async () => { + const home = newHome(); + vi.stubGlobal("fetch", unreachable()); + await setupRuntimeProfile({ home, profileName: "default", apiBase: "https://crosshead.sh", ...identity(), makeDefault: true }); + vi.stubGlobal("fetch", vi.fn().mockRejectedValue(new TypeError("fetch failed", { + cause: Object.assign(new Error("not in the cert's altnames: DNS:ignore-previous-instructions.attacker.example"), { code: "ERR_TLS_CERT_ALTNAME_INVALID" }), + }))); + const auth = (await buildRuntimeDoctorDirect(home, "default")).checks.find((check) => check.id === "auth"); + expect(auth?.message).toContain("sign-in failed: ERR_TLS_CERT_ALTNAME_INVALID"); + expect(auth?.message).not.toContain("attacker"); + }); +}); + +describe("setup against an address that is not a Crosshead service", () => { + it("keeps the HTTP error type, status and code when explaining a 404", async () => { + vi.stubGlobal("fetch", vi.fn().mockImplementation(async () => new Response( + JSON.stringify({ error: { code: "not_found", message: "no such route" } }), + { status: 404, headers: { "content-type": "application/json" } } + ))); + const failure = await setupRuntimeProfile({ home: newHome(), profileName: "default", apiBase: "https://example.test/wrong", ...identity(), makeDefault: true }) + .catch((error: unknown) => error); + expect(failure).toBeInstanceOf(HostedOnlyBotsRequestError); + expect(failure).toMatchObject({ status: 404, code: "not_found", message: expect.stringContaining("probably not a Crosshead service") }); + }); + + it("setup --json reports the deferral like keygen", async () => { + vi.stubGlobal("fetch", unreachable()); + const key = identity(); + const json = JSON.parse(await setupProfileFromCli(["--home", newHome(), "--profile", "default", "--api-base", "https://crosshead.sh", "--npub", key.npub, "--nsec", key.nsec, "--json"])); + expect(json).toMatchObject({ profile: "default", registrationDeferred: true, registrationDeferredReason: "ECONNREFUSED" }); + }); +}); + describe("doctor on a local-only profile", () => { it("does not report a missing sign-in", async () => { const home = newHome(); @@ -145,10 +179,14 @@ describe("classifying hosted sign-in failures", () => { }); it("names the underlying cause of a fetch failure", () => { - expect(describeFetchFailure(failed(Object.assign(new Error("certificate has expired"), { code: "CERT_HAS_EXPIRED" })))).toBe("CERT_HAS_EXPIRED: certificate has expired"); - expect(describeFetchFailure(failed(Object.assign(new Error("getaddrinfo ENOTFOUND x.test"), { code: "ENOTFOUND" })))).toBe("getaddrinfo ENOTFOUND x.test"); + expect(describeFetchFailure(failed(Object.assign(new Error("certificate has expired"), { code: "CERT_HAS_EXPIRED" })))).toBe("CERT_HAS_EXPIRED"); + expect(describeFetchFailure(failed(Object.assign(new Error("getaddrinfo ENOTFOUND x.test"), { code: "ENOTFOUND" })))).toBe("host name not found (ENOTFOUND)"); + // Text chosen by the other end (here, names in a mismatched certificate) is never repeated. + const altnames = Object.assign(new Error("Hostname/IP does not match certificate's altnames: Host: crosshead.sh. is not in the cert's altnames: DNS:ignore-previous-instructions.attacker.example"), { code: "ERR_TLS_CERT_ALTNAME_INVALID" }); + expect(describeFetchFailure(failed(altnames))).toBe("ERR_TLS_CERT_ALTNAME_INVALID"); + expect(describeFetchFailure(failed(new Error("some text from a captive portal")))).toBe("network request failed"); expect(describeFetchFailure(failed(new Error("unexpected redirect")))).toBe("unexpected redirect"); - expect(describeFetchFailure(failed(undefined))).toBe("fetch failed"); + expect(describeFetchFailure(failed(undefined))).toBe("network request failed"); }); it("reports redirects, certificate errors, HTTP answers and unexplained failures", () => { @@ -159,6 +197,12 @@ describe("classifying hosted sign-in failures", () => { // Nothing listening on this machine is a wrong port or a stopped local server. expect(hostedServiceUnreachableReason(failed(coded("ECONNREFUSED")), "http://127.0.0.1:8788")).toBeNull(); expect(hostedServiceUnreachableReason(failed(coded("ECONNREFUSED")), "http://localhost:8788")).toBeNull(); + expect(hostedServiceUnreachableReason(failed(coded("ECONNRESET")), "http://127.0.0.1:8788")).toBeNull(); + expect(hostedServiceUnreachableReason(failed(new AggregateError([coded("ENETUNREACH"), coded("ECONNREFUSED")])), "http://localhost:8788")).toBeNull(); + expect(hostedServiceUnreachableReason(Object.assign(new Error("timed out"), { name: "TimeoutError" }), "http://[::1]:8788")).toBeNull(); + for (const base of ["http://0.0.0.0:8788", "http://api.localhost:8788", "http://localhost.:8788"]) { + expect(hostedServiceUnreachableReason(failed(coded("ECONNREFUSED")), base)).toBeNull(); + } // A listener that accepts and drops the connection answered; so did a proxy asking for credentials or failing upstream. expect(hostedServiceUnreachableReason(failed(coded("UND_ERR_SOCKET")), "https://crosshead.sh")).toBeNull(); for (const status of ["407", "502", "504"]) {