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>>,