diff --git a/README.md b/README.md index 98c8896..90f1dc7 100644 --- a/README.md +++ b/README.md @@ -166,6 +166,31 @@ 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` 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. + +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, 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; 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. + +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..3cbae19 100644 --- a/src/runtime/cli/core.ts +++ b/src/runtime/cli/core.ts @@ -131,9 +131,20 @@ export const setupProfileFromCli = async (argv: string[]): Promise => { npub: String(flags.npub ?? ""), nsec: String(flags.nsec ?? ""), }); - return `Configured runtime profile ${profile.name} for ${profile.npub}`; + 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"); }; +export const registrationDeferredLines = (profile: { apiBase: string; registrationDeferred?: boolean; registrationDeferredReason?: string }): string[] => + profile.registrationDeferred + ? [`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 => { const { flags } = parseArgs(argv); const identity = generateRuntimeIdentity(); @@ -161,6 +172,7 @@ export const keygenFromCli = async (argv: string[]): Promise => { memoryMode: profile.memoryMode, workspaceScope: profile.workspaceScope, secureStoreMode: profile.secureStoreMode, + ...(profile.registrationDeferred ? { registrationDeferred: true, registrationDeferredReason: profile.registrationDeferredReason ?? null } : {}), }; return flags.json ? JSON.stringify(result, null, 2) @@ -171,6 +183,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..cfbbba6 100644 --- a/src/runtime/cli/quickstart.ts +++ b/src/runtime/cli/quickstart.ts @@ -205,16 +205,22 @@ 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 }; + 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"}`, + detail: `configured ${profileName} for ${parsed.apiBase ?? apiBase} with generated runtime identity ${parsed.npub ?? "unknown"}${ + parsed.registrationDeferred + ? `; 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` + : "" + }`, }); } else { steps.push({ @@ -305,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 2130689..84f4866 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,13 @@ 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, + // 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 }) + .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/hosted-client.ts b/src/runtime/hosted-client.ts index a5fe35d..049ccc6 100644 --- a/src/runtime/hosted-client.ts +++ b/src/runtime/hosted-client.ts @@ -246,6 +246,54 @@ 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/; + +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 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"; +}; + /** * 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 e6a4ee9..c52b8d4 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, 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 { @@ -1285,7 +1286,49 @@ export const uninstallRuntimeCore = async (home?: string): Promise => { } }; -export const setupRuntimeProfile = async (options: SetupRuntimeProfileOptions): 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", "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"]); + +/** + * 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 + * 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; + 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] : [])); + 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. + const proxy = causes.map((cause) => PROXY_REFUSAL.exec(cause.message)).find(Boolean); + 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; +}; + +/** The saved profile, plus whether sign-in with the hosted service was put off because it was unreachable. */ +export type SetupRuntimeProfileResult = RuntimeProfile & { registrationDeferred?: true; registrationDeferredReason?: string }; + +export const setupRuntimeProfile = async (options: SetupRuntimeProfileOptions): Promise => { try { const decodedNpub = nip19.decode(options.npub); const decodedNsec = nip19.decode(options.nsec); @@ -1306,6 +1349,10 @@ 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; + let registrationDeferredReason: string | undefined; const session = localOnlyProfile ? null : await new HostedOnlyBotsClient({ @@ -1313,7 +1360,28 @@ export const setupRuntimeProfile = async (options: SetupRuntimeProfileOptions): npub: options.npub, nsec: options.nsec, session: secret?.session ?? null, - }).ensureSession(); + }).ensureSession().catch((error: unknown) => { + const reason = hostedServiceUnreachableReason(error, options.apiBase); + 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)) { + 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) { + // 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; + } + registrationDeferred = true; + registrationDeferredReason = reason; + return null; + }); const profile: RuntimeProfile = { name: options.profileName, @@ -1353,8 +1421,9 @@ export const setupRuntimeProfile = async (options: SetupRuntimeProfileOptions): npub: profile.npub, apiBase: profile.apiBase, memoryMode: profile.memoryMode, + ...(registrationDeferred ? { registrationDeferred: true, registrationDeferredReason } : {}), }); - return 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..0dca14e 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, @@ -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({ @@ -553,6 +557,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 +566,28 @@ export const buildDoctorReport = async (paths: RuntimePaths, profileName?: strin session, }); authValid = isSessionFresh(session); - } catch { + } catch (error) { authValid = false; + // 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}` : ""}` + : 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, + // 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 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 { 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 new file mode 100644 index 0000000..95c895c --- /dev/null +++ b/tests/runtime/offline-setup.test.ts @@ -0,0 +1,247 @@ +import { spawnSync } from "node:child_process"; +import { existsSync, mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } 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, 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"; +import { buildRuntimeDoctorDirect } from "../../src/runtime/runtime-status"; + +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 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 () => { + 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(); + }); + + 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("Could not sign in to https://crossheed.sh: host name not found (ENOTFOUND). Check --api-base."); + 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 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"); + }); +}); + +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(); + 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 }); + + 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(); + // 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)"); + // 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(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("network request failed"); + }); + + 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(); + // 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"]) { + 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(); + }); +}); + +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. + + 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"); + 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 }); + // 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"); + 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); +});