@devries-cameron20 / t3code Mirror · read-only / commits / a48d7c6cd0
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 23:30 UTC

fix(ssh): explain how to recover from failed host key checks (#23785)

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

Julius Marminge committed Nov 11, 2026 at 11:55 UTC a48d7c6cd0d1ba62f7cc9b3160f9d3c8b8eea575
4 files changed +114 -9
packages/ssh/src/command.test.ts
+60
@@ -1,9 +1,11 @@
1 import { assert, describe, it } from "@effect/vitest";
2 import * as NodeCrypto from "@effect/platform-node/NodeCrypto";
3 import * as NodeServices from "@effect/platform-node/NodeServices";
4 +import * as HostProcess from "@t3tools/shared/HostProcess";
5 import * as Effect from "effect/Effect";
6 import * as Layer from "effect/Layer";
7 import * as Result from "effect/Result";
8 +import * as Schema from "effect/Schema";
9 import * as Sink from "effect/Sink";
10 import * as Stream from "effect/Stream";
11 import { ChildProcess, ChildProcessSpawner } from "effect/process";
@@ -12,6 +14,7 @@ import { parseSshResolveOutput, remoteStateKey, runSshCommand } from "./command.
14 import { SshCommandError } from "./errors.ts";
15
16 const encoder = new TextEncoder();
17 +const isSshCommandError = Schema.is(SshCommandError);
18
19 const makeFailedProcess = (input: { readonly stdout: string; readonly stderr?: string }) => {
20 const stdoutStream = Stream.make(encoder.encode(input.stdout));
@@ -184,4 +187,61 @@ describe("ssh command", () => {
187 }
188 }).pipe(Effect.provide(layerProcess));
189 });
190 +
191 + const changedKeyStderr =
192 + "@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@\r\n" +
193 + "@ WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED! @\r\n" +
194 + " ssh-keygen -f '/home/me/.ssh/known_hosts' -R 'devbox'\r\n" +
195 + "Host key verification failed.\r\n";
196 +
197 + it.effect.each([
198 + {
199 + name: "quotes the terminal command for a POSIX shell",
200 + target: { alias: "my host", username: "o'brien" },
201 + platform: "linux",
202 + stderr: "Host key verification failed.\r\n",
203 + expected: ["`ssh 'o'\\''brien@my host'`"],
204 + },
205 + {
206 + name: "quotes the terminal command for a Windows shell",
207 + target: { alias: "my host", username: "me" },
208 + platform: "win32",
209 + stderr: "Host key verification failed.\r\n",
210 + expected: ['`ssh "me@my host"`'],
211 + },
212 + {
213 + name: "keeps an option-shaped alias out of the option list",
214 + target: { alias: "-oProxyCommand=false", username: null },
215 + platform: "linux",
216 + stderr: "Host key verification failed.\r\n",
217 + expected: ["`ssh -- -oProxyCommand=false`"],
218 + },
219 + {
220 + name: "tells the user to remove a changed host key first",
221 + target: { alias: "devbox", username: null },
222 + platform: "linux",
223 + stderr: changedKeyStderr,
224 + expected: ["has changed", "`ssh-keygen -R`", "`ssh devbox`", "-R 'devbox'"],
225 + },
226 + ] as const)("$name", ({ target, platform, stderr, expected }) => {
227 + const spawner = ChildProcessSpawner.make(() =>
228 + Effect.succeed(makeFailedProcess({ stdout: "", stderr })),
229 + );
230 + return runSshCommand({ ...target, hostname: "devbox", port: null }).pipe(
231 + Effect.flip,
232 + Effect.map((error) => {
233 + assert.isTrue(isSshCommandError(error));
234 + for (const text of expected) assert.include(error.message, text);
235 + if (isSshCommandError(error)) assert.equal(error.stderr, stderr);
236 + }),
237 + Effect.provideService(HostProcess.Platform, platform),
238 + Effect.provide(
239 + Layer.mergeAll(
240 + NodeServices.layer,
241 + NodeCrypto.layer,
242 + Layer.succeed(ChildProcessSpawner.ChildProcessSpawner, spawner),
243 + ),
244 + ),
245 + );
246 + });
247 });
packages/ssh/src/command.ts
+48 -5
@@ -147,6 +147,42 @@ function redactSshErrorOutput(output: string, keepTail = false): string {
147 : `${redacted.slice(0, MAX_SSH_ERROR_OUTPUT_LENGTH)}\n[truncated]`;
148 }
149
150 +export function shellSingleQuote(value: string): string {
151 + return `'${value.replaceAll("'", "'\\''")}'`;
152 +}
153 +
154 +const SAFE_SHELL_ARG = /^[\w@%+=:,./-]+$/u;
155 +
156 +// cmd.exe and PowerShell both read double quotes, but not POSIX single quotes.
157 +function terminalArg(value: string, platform: NodeJS.Platform): string {
158 + if (SAFE_SHELL_ARG.test(value)) return value;
159 + return platform === "win32" ? `"${value}"` : shellSingleQuote(value);
160 +}
161 +
162 +// ssh prints this for unknown and changed host keys when it cannot ask. The app
163 +// never answers host key prompts, so the user checks the fingerprint in a terminal.
164 +function hostKeyVerificationMessage(input: {
165 + readonly target: DesktopSshEnvironmentTarget;
166 + readonly hostSpec: string;
167 + readonly stderr: string;
168 + readonly platform: NodeJS.Platform;
169 +}): string | null {
170 + const { target, hostSpec, stderr, platform } = input;
171 + if (!stderr.includes("Host key verification failed")) return null;
172 + const command = [
173 + "ssh",
174 + ...(target.port !== null ? ["-p", String(target.port)] : []),
175 + ...(hostSpec.startsWith("-") ? ["--"] : []),
176 + hostSpec,
177 + ]
178 + .map((arg) => terminalArg(arg, platform))
179 + .join(" ");
180 + const guidance = stderr.includes("REMOTE HOST IDENTIFICATION HAS CHANGED")
181 + ? `The host key for ${hostSpec} has changed since it was trusted. Only if you expect this change, remove the old key with the \`ssh-keygen -R\` command in the output below, run \`${command}\` in a terminal, check that the new host key fingerprint is the one you expect, then try again.`
182 + : `SSH could not verify the host key for ${hostSpec}. Run \`${command}\` in a terminal, check that the host key fingerprint is the one you expect, then try again.`;
183 + return `${guidance}\n\n${stderr.trim()}`;
184 +}
185 +
186 function normalizeSshErrorMessage(input: {
187 readonly stdout?: string;
188 readonly stderr: string;
@@ -284,11 +320,18 @@ const runSshCommandInScope = Effect.fn("ssh/command.runSshCommand.inScope")(func
320 exitCode,
321 stdout: diagnosticStdout,
322 stderr,
287 - message: normalizeSshErrorMessage({
288 - stdout: diagnosticStdout,
289 - stderr,
290 - fallbackMessage: `SSH command failed for ${hostSpec} (exit ${exitCode}).`,
291 - }),
323 + message:
324 + hostKeyVerificationMessage({
325 + target,
326 + hostSpec,
327 + stderr,
328 + platform: yield* HostProcess.Platform,
329 + }) ??
330 + normalizeSshErrorMessage({
331 + stdout: diagnosticStdout,
332 + stderr,
333 + fallbackMessage: `SSH command failed for ${hostSpec} (exit ${exitCode}).`,
334 + }),
335 });
336 }
337
packages/ssh/src/tunnel.test.ts
+5
@@ -535,6 +535,11 @@ describe("ssh tunnel scripts", () => {
535 "julius@devbox: Permission denied (publickey,password).\n",
536 expectedPromptAttempts: [1],
537 },
538 + {
539 + name: "does not ask for a password when the host key cannot be verified",
540 + stderr: "Host key verification failed.\r\n",
541 + expectedPromptAttempts: [],
542 + },
543 {
544 name: "asks for a password when the server rejects every key",
545 stderr: "julius@devbox: Permission denied (publickey,password).\r\n",
packages/ssh/src/tunnel.ts
+1 -4
@@ -33,6 +33,7 @@ import {
33 resolveSshCommand,
34 resolveSshTarget,
35 runSshCommand,
36 + shellSingleQuote,
37 sshTargetLogFields,
38 targetConnectionKey,
39 } from "./command.ts";
@@ -230,10 +231,6 @@ function stripTrailingNewlines(value: string): string {
231 return value.replace(/\n+$/u, "");
232 }
233
233 -function shellSingleQuote(value: string): string {
234 - return `'${value.replaceAll("'", "'\\''")}'`;
235 -}
236 -
234 function applyScriptPlaceholders(
235 template: string,
236 replacements: Readonly<Record<string, string>>,