Files
Netcatty/electron/bridges/sshBridge/startSession.cjs
T
陈大猫 90b6569c7a fix(sftp): inherit encoding and accepted host identities for dedicated dials
Preserve PR #3875's original author commits and scoped TERM-SSHD transfer policy.
Copy persisted filename encoding into dedicated file connections. Capture only
host identities actually accepted by the terminal route, including jump hops,
and fail closed on later unverified changes without orphan host-key prompts.
Add first-trust, changed-key, route-scope and encoding regressions.
2026-10-23 16:30:42 +08:00

2992 lines
136 KiB
JavaScript

/* eslint-disable no-undef */
const { emitTerminalSessionData } = require("../emitTerminalSessionData.cjs");
const {
setBufferedOutputBytes,
shouldAcceptSessionOutput,
shouldProcessSessionOutput,
} = require("../terminalFlowAck.cjs");
const {
filterTerminalInterruptOutput,
takePendingInterruptOutputMeta,
} = require("../terminalInterruptOutputGate.cjs");
const {
logTerminalInterruptDrainDropSample,
logTerminalOutputDropSample,
} = require("../terminalInterruptDiagnostics.cjs");
const { runWhenProxyConnectionReady } = require("../proxyUtils.cjs");
const { getAttachHomeWebContentsId } = require("../terminalAttachRestore.cjs");
const { openBoundedSshShellCallback } = require("../boundedSshChannelOpen.cjs");
const { optionsForPeerSingleChannel } = require("../../../domain/singleChannelSshBanner.shared.cjs");
const { listInteractiveShellPids: listInteractiveShellPidsShared } = require("../sshInteractiveShells.cjs");
const {
shouldConfirmReusedShellLiveness,
resolveReusedShellLivenessMs,
waitForReusedShellLiveness,
} = require("../sshIdleParkPolicy.cjs");
const {
annotateMacLocalNetworkErrorMessage,
resolveFirstTcpEndpoint,
} = require("../macLocalNetworkAccess.cjs");
const {
buildRemoteShellExitPayload,
normalizeRemoteExitSignal,
} = require("./remoteShellExit.cjs");
const { looksLikeSkOpenSshMaterial } = require("../sshAuthHelper.cjs");
const SSH_TCP_CONNECT_TIMEOUT_MS = 20000;
const SSH_AUTH_READY_TIMEOUT_MS = 120000;
const MAX_SSH_CONNECTION_TIMEOUT_MS = 3600000;
const COPY_TAB_RATE_LIMIT_RETRY_TIMEOUT_MS = 30000;
function buildInteractiveShellOptions(options) {
const shellOptions = {};
// Hosts with singleChannelSsh (bastion/PAM) may drop the transport on
// CHANNEL_REQUEST env. Skip COLORTERM / caller env there.
if (!options.singleChannelSsh) {
shellOptions.env = {
COLORTERM: "truecolor",
...(options.env || {}),
};
}
return shellOptions;
}
/**
* In-flight headless "test connection" transports, keyed by sessionId. A test
* connection never enters the terminal `sessions` registry (it opens no shell),
* so a dedicated registry is needed so the renderer can cancel an in-flight
* dial. Entries are removed when the connection closes.
*/
const testConnectionTransports = new Map();
function registerTestConnectionTransport(sessionId, transport) {
testConnectionTransports.set(sessionId, transport);
}
function unregisterTestConnectionTransport(sessionId) {
testConnectionTransports.delete(sessionId);
}
function cancelTestConnection(sessionId) {
require("../keyboardInteractiveHandler.cjs").cancelRequestsForSession(sessionId);
require("../passphraseHandler.cjs").cancelPassphraseRequestsForSession(sessionId);
require("../hostKeyVerifier.cjs").cancelRequestsForSession(sessionId);
const transport = testConnectionTransports.get(sessionId);
if (!transport) return { success: false, error: "Test connection not found" };
const end = (item) => {
try { item?.end?.(); } catch { /* ignore */ }
try { item?.destroy?.(); } catch { /* ignore */ }
};
for (const chain of transport.chainConnections || []) end(chain);
end(transport.pendingConn);
end(transport.socket);
end(transport.conn);
return { success: true };
}
/**
* Fan out netcatty:exit to the primary contents plus any attach-home owner
* (AI observe popup rebind) so neither side is left stale.
*/
function safeSendSessionExit(ctx, primaryContents, sessionId, payload) {
const { safeSend, electronModule, sessions } = ctx;
const seen = new Set();
const sendTo = (contents) => {
if (!contents || typeof contents.id !== "number" || seen.has(contents.id)) return;
seen.add(contents.id);
try {
safeSend(contents, "netcatty:exit", payload);
} catch {
// ignore destroyed renderers
}
};
sendTo(primaryContents);
try {
const live = sessions?.get?.(sessionId);
if (typeof live?.webContentsId === "number") {
sendTo(electronModule?.webContents?.fromId?.(live.webContentsId));
}
} catch {
// ignore
}
try {
const homeId = getAttachHomeWebContentsId(sessionId);
if (typeof homeId === "number") {
sendTo(electronModule?.webContents?.fromId?.(homeId));
}
} catch {
// ignore
}
}
function normalizeSshConnectionTimeoutMs(value, fallback) {
return Number.isFinite(value) && value >= 1000 && value <= MAX_SSH_CONNECTION_TIMEOUT_MS
? Math.round(value)
: fallback;
}
function resolveSshConnectionTimeouts(options = {}) {
return {
tcpConnectTimeoutMs: normalizeSshConnectionTimeoutMs(
options.sshTcpConnectTimeoutMs,
SSH_TCP_CONNECT_TIMEOUT_MS,
),
authReadyTimeoutMs: normalizeSshConnectionTimeoutMs(
options.sshAuthReadyTimeoutMs,
SSH_AUTH_READY_TIMEOUT_MS,
),
};
}
function isSshAuthFailure(err) {
const message = err?.message?.toLowerCase() || "";
return err?.level === "client-authentication" ||
message.includes("all configured authentication methods failed") ||
message.includes("authentication failed") ||
message.includes("too many authentication failures") ||
/permission denied\s*\(/.test(message) ||
message.includes("no authentication methods available");
}
function userVisibleSshErrorMessage(err, options = {}) {
const firstHop = resolveFirstTcpEndpoint(options);
return annotateMacLocalNetworkErrorMessage(err?.message || String(err || ""), {
hostname: options.hostname || options.host,
firstHopHostname: firstHop.skipProbe ? "" : firstHop.hostname,
firstHopResolvedAddress: firstHop.skipProbe
? ""
: (options._macLocalNetworkResolvedFirstHop || options.firstHopResolvedAddress || ""),
skipProbe: firstHop.skipProbe === true,
});
}
function hasSelectedAgentIdentity(options) {
const hasInlinePublicKey = Array.isArray(options?.agentPublicKeys)
&& options.agentPublicKeys.some((key) => typeof key === "string" && key.trim().length > 0);
const hasReferencedIdentity = Array.isArray(options?.identityFilePaths)
&& options.identityFilePaths.some((filePath) => typeof filePath === "string" && filePath.trim().length > 0);
return hasInlinePublicKey || hasReferencedIdentity;
}
function shouldOfferAgentForLogin(options, connectOpts) {
const selectedMethod = options?.authMethod;
// Path/inline sk-* detection may set useFidoAgent after prepare; honor it for
// login auth even when the renderer still sent useSshAgent:false.
const forceFidoAgent = options?.useFidoAgent === true && selectedMethod !== "password";
const hasRestrictedSelectedAgent = selectedMethod === "key"
&& options?.useSshAgent === true
&& options?.identitiesOnly === true
&& hasSelectedAgentIdentity(options);
const isStrictMethod = selectedMethod === "password"
|| selectedMethod === "key"
|| selectedMethod === "certificate";
return (!isStrictMethod || hasRestrictedSelectedAgent || forceFidoAgent)
&& (options?.useSshAgent !== false || forceFidoAgent)
&& Boolean(connectOpts?.agent);
}
function shouldPrepareSystemAgentForLogin(options) {
if (options?.authMethod === "password" || options?.authMethod === "certificate") return false;
if (options?.authMethod !== "key") return true;
return options?.useSshAgent === true
&& options?.identitiesOnly === true
&& hasSelectedAgentIdentity(options);
}
function resolveUnlockedEncryptedKeysForAuth(options, strictAgentSelection) {
const selectedMethod = options?.authMethod;
const hasStrictMethod = selectedMethod === "password"
|| selectedMethod === "key"
|| selectedMethod === "certificate";
return strictAgentSelection || hasStrictMethod ? [] : (options?._unlockedEncryptedKeys || []);
}
function shouldPromoteCachedAuthMethod(authMethod, cachedMethod) {
if (!cachedMethod) return false;
if (authMethod === "auto") {
return cachedMethod === "agent" || cachedMethod.startsWith("publickey");
}
if (authMethod === "password" || authMethod === "key" || authMethod === "certificate") {
return false;
}
return true;
}
async function applyAgentForwarding(
options,
connectOpts,
resolveForwardingAgentSocket,
) {
if (!options?.agentForwarding) return connectOpts;
const alreadyResolved = Object.prototype.hasOwnProperty.call(
options,
"_resolvedForwardingAgentSocket",
);
const forwardingAgent = alreadyResolved
? options._resolvedForwardingAgentSocket
: await resolveForwardingAgentSocket(options.identityAgent, options);
if (forwardingAgent) {
connectOpts.agent = forwardingAgent;
connectOpts.agentForward = true;
}
return connectOpts;
}
async function prepareAgentForwardingOptions(options, resolveForwardingAgentSocket) {
if (!options?.agentForwarding) return options;
if (Object.prototype.hasOwnProperty.call(options, "_resolvedForwardingAgentSocket")) {
return {
...options,
forwardingAgentSocket: options._resolvedForwardingAgentSocket || "",
};
}
const forwardingAgent = await resolveForwardingAgentSocket(options.identityAgent, options);
return {
...options,
_resolvedForwardingAgentSocket: forwardingAgent || null,
forwardingAgentSocket: forwardingAgent || "",
};
}
/**
* Emit the one-shot outcome for a headless "test connection" attempt.
*
* A connection test authenticates (and, for Telnet, completes auto-login)
* and then tears down without ever opening a shell channel. There is no
* persistent terminal session to carry progress, so success/failure is
* reported through a dedicated `netcatty:test:result` event consumed by the
* host-editor test dialog. The same `netcatty:chain:progress`,
* `netcatty:host-key:verify`, `netcatty:keyboard-interactive`, and
* `netcatty:passphrase-auth-failed` channels keep flowing unchanged so the
* dialog reuses the terminal's progress/log/auth/host-key UI verbatim.
*/
function sendConnectionTestResult(sender, sessionId, ok, error) {
if (!sender || sender.isDestroyed?.()) return;
try {
sender.send("netcatty:test:result", {
sessionId,
ok: Boolean(ok),
...(error ? { error: String(error) } : {}),
});
} catch {
// Renderer was destroyed mid-send; nothing to do.
}
}
function createStartSessionApi(ctx) {
with (ctx) {
const listInteractiveShellPids = (conn) => listInteractiveShellPidsShared(conn, {
quoteShellArg,
});
const listInteractiveShellPidsResilient = async (conn, opts = {}) => {
const attempts = Math.max(1, Number(opts.attempts) || 1);
const backoffMs = Math.max(1, Number(opts.backoffMs) || 150);
const initialDelayMs = Math.max(0, Number(opts.initialDelayMs) || 0);
let last = { available: false, pids: [] };
for (let attempt = 0; attempt < attempts; attempt += 1) {
const delayMs = attempt === 0
? initialDelayMs
: backoffMs * attempt;
if (delayMs > 0) {
await new Promise((resolve) => setTimeout(resolve, delayMs));
}
last = await listInteractiveShellPids(conn);
if (last.available || !last.rateLimited) return last;
}
return last;
};
const ensureConcurrentJoinShellIdentity = async (connRef, options) => {
if (!connRef || options.skipShellPidDiscovery) return true;
const current = [...sessions.entries()].filter(([, candidate]) => (
candidate?.connRef === connRef
&& candidate?.stream
));
if (current.length === 0) return false;
if (current.every(([, candidate]) => candidate.shellPid)) return true;
if (current.length !== 1) return false;
const [[sessionId, candidate]] = current;
const discovery = await listInteractiveShellPids(connRef.conn);
const live = sessions.get(sessionId);
if (
discovery.available
&& discovery.pids.length === 1
&& live === candidate
&& live.connRef === connRef
&& live.stream === candidate.stream
&& !live.shellPid
) {
live.shellPid = String(discovery.pids[0]);
}
return Boolean(
live === candidate
&& live.connRef === connRef
&& live.stream === candidate.stream
&& live.shellPid
);
};
const waitForNewInteractiveShellPid = async (conn, previousPids, opts = {}) => {
const previous = new Set(previousPids);
const initialDelayMs = Math.max(0, Number(opts.initialDelayMs) || 0);
const backoffMs = Math.max(1, Number(opts.backoffMs) || 50);
if (initialDelayMs > 0) {
await new Promise((resolve) => setTimeout(resolve, initialDelayMs));
}
for (let attempt = 0; attempt < 5; attempt += 1) {
const discovery = await listInteractiveShellPids(conn);
if (!discovery.available) {
// Bastion rate limits can reject the post-open discovery exec just
// after a retried shell open. Back off and try again instead of
// permanently leaving the copied session without a shellPid.
if (discovery.rateLimited && attempt < 4) {
await new Promise((resolve) => setTimeout(resolve, backoffMs * (attempt + 1)));
continue;
}
return null;
}
const newPids = discovery.pids.filter((pid) => !previous.has(pid));
if (newPids.length === 1) return newPids[0];
if (newPids.length > 1) return null;
if (attempt < 4) {
await new Promise((resolve) => setTimeout(resolve, backoffMs * (attempt + 1)));
}
}
return null;
};
/**
* Wire up a freshly-opened shell channel (PTY stream) for a session:
* output buffering, ZMODEM handling, encoding, exit/close reporting and
* teardown. Shared by both the fresh-connection path and the connection
* reuse path (issue #1204) so duplicated tabs behave identically to the
* original tab once their channel is open.
*
* `isReused` only affects diagnostics/log labelling; lifecycle correctness
* is governed entirely by the reference-counted connection descriptor
* (sshConnectionPool.cjs). The stream "close"/transport handlers always
* release this session's hold via releaseConnectionRef, which tears the
* shared transport down only when the last channel is gone.
*/
function setupShellSession({
conn,
stream,
options,
sessionId,
event,
log,
detachX11Forwarding,
chainConnections,
isReused,
acceptedHostKeys = [],
}) {
const sessionOptions = optionsForPeerSingleChannel(options, conn);
const session = {
conn,
stream,
// Only the owning (fresh) session is responsible for the jump-host
// chain; reused channels share it via the connRef descriptor and must
// not carry their own copy (otherwise closing a reused tab would end
// the chain out from under its siblings).
chainConnections: isReused ? [] : chainConnections,
webContentsId: event.sender.id,
// Store connection info for MCP host discovery
hostname: options.host || options.hostname || '',
username: options.username || '',
label: options.label || '',
// Host file-transfer preference for session-backed SFTP/SCP opens
// (Catty/MCP/clipboard paste call openSftpForSession without protocol).
sftpFileProtocol: options.sftpFileProtocol || options.fileProtocol || 'auto',
systemManagerSudoPassword: typeof options.sudoAutofillPassword === 'string' && options.sudoAutofillPassword.length > 0
? options.sudoAutofillPassword
: undefined,
lastIdlePrompt: '',
lastIdlePromptAt: 0,
_promptTrackTail: '',
// SSH server identification string (the `software` part of
// `SSH-2.0-<software>`). ssh2 captures this during the header
// exchange and stores it on the client as `_remoteVer` — it
// is available by the time 'ready' fires, so the renderer can
// use it to detect network-device vendors without running any
// additional exec channels. See domain/host.ts
// `detectVendorFromSshVersion`.
remoteSshVersion: (conn && typeof conn._remoteVer === 'string') ? conn._remoteVer : '',
singleChannelSsh: sessionOptions.singleChannelSsh === true,
// The actual SSH target this connection authenticated to. Used to make
// sure a "Copy Tab" reuse opens its channel on a connection going to the
// *same* host — a saved host edited after the source connected must not
// silently run commands on the old machine (issue #1204 review).
_reuseEndpoint: normalizeEndpoint(buildConnectionReuseEndpoint(sessionOptions, {
agentForwarding: sessionOptions._actualAgentForwarding ?? sessionOptions.agentForwarding,
})),
// Only live SFTP borrowers may use the original password-less profile.
// Do not alias the pool: new terminals must still authenticate normally.
_sftpReuseEndpoint: options.sftpReuseOptions && !options.sftpReuseOptions.password
? normalizeEndpoint(buildConnectionReuseEndpoint(options.sftpReuseOptions))
: null,
cols: options.cols || 80,
rows: options.rows || 24,
};
const { claimSessionSlot } = require("../sessionBootEpoch.cjs");
const claim = claimSessionSlot(sessions, sessionId, session, options.bootEpoch);
if (!claim.ok) {
const supersededError = new Error("Connection superseded by a newer reconnect");
supersededError.code = "NETCATTY_BOOT_SUPERSEDED";
try { stream?.close?.(); } catch { /* ignore */ }
try { if (!isReused) conn?.end?.(); } catch { /* ignore */ }
throw supersededError;
}
if (session.singleChannelSsh) {
require("./sessionSftpDial.cjs").attachSessionSftpDial(session, options, {
sessions, sessionId, sender: event.sender, acceptedHostKeys,
openSftp: (...args) => require("../sftpBridge.cjs").openSftp(...args),
closeSftp: (...args) => require("../sftpBridge.cjs").closeSftp(...args),
});
}
openTerminalOutputSession?.(sessionId, event.sender);
// Attach the shared connection descriptor to this session. The caller owns
// the reference *count*: the fresh-connection path calls createConnectionRef
// after this returns; the reuse path calls acquireConnectionRef *before*
// issuing the async shell request (so the connection can't be released out
// from under a pending channel open). We only record the descriptor here.
if (options._connRef) {
session.connRef = options._connRef;
}
// Start real-time session log stream if configured. The token is stored
// on the session so the connection-level error/timeout/close handlers can
// stop the stream when they clean up the owner session directly.
let logStreamToken = null;
if (options.sessionLog?.enabled && options.sessionLog?.directory) {
logStreamToken = sessionLogStreamManager.startStream(sessionId, {
hostLabel: options.hostLabel || options.hostname || '',
hostname: options.hostname || '',
directory: options.sessionLog.directory,
format: options.sessionLog.format || 'txt',
timestampsEnabled: Boolean(options.sessionLog.timestampsEnabled),
startTime: Date.now(),
});
}
session._logStreamToken = logStreamToken;
// Coalesce shell output and deliver it to the renderer on the next
// event-loop turn (see ptyOutputBuffer) rather than on a fixed timer,
// so interactive echo isn't held back by the batch interval. A size
// cap still forces an immediate flush for bursts of output.
const {
bufferData,
flushPaced: flushBufferPaced,
takePendingEntry: takePendingBuffer,
discard: discardBuffer,
} = createPtyOutputBuffer((data, meta) => {
if (sessions.get(sessionId) !== session) return;
const contents = event.sender;
emitTerminalSessionData(contents, sessionId, data, {
session,
cols: session.cols,
rows: session.rows,
meta,
});
}, {
onPendingBytesChange: (bytes) => {
if (sessions.get(sessionId) === session) setBufferedOutputBytes(session, bytes);
},
shouldAcceptOutput: () => sessions.get(sessionId) === session && shouldAcceptSessionOutput(session),
});
session.flushPendingData = flushBufferPaced;
session.takePendingData = takePendingBuffer;
session.discardPendingData = discardBuffer;
const getCurrentSessionWebContents = () => {
const currentId = sessions.get(sessionId)?.webContentsId;
if (typeof currentId === "number") {
const current = electronModule?.webContents?.fromId?.(currentId);
if (current) return current;
}
return event.sender;
};
const getCurrentSessionWebContentsId = () =>
getCurrentSessionWebContents()?.id ?? event.sender.id;
const sshZmodemSentry = createZmodemSentry({
sessionId,
onData(buf) {
if (sessions.get(sessionId) !== session) return;
const decoder = getSessionDecoder(sessionId, "stdout");
const decoded = decoder.write(buf);
const output = filterTerminalInterruptOutput(session, decoded);
if (!output.accepted) {
logTerminalInterruptDrainDropSample(session, {
sessionId,
stream: "stdout",
droppedBytes: output.droppedBytes,
reason: output.reason,
accepted: false,
});
return;
}
if (output.droppedBytes > 0) {
logTerminalInterruptDrainDropSample(session, {
sessionId,
stream: "stdout",
droppedBytes: output.droppedBytes,
reason: output.reason,
accepted: true,
});
}
if (!output.data) return;
const outputMeta = takePendingInterruptOutputMeta(session);
trackSessionIdlePrompt(session, output.data);
bufferData(output.data, outputMeta);
sessionLogStreamManager.appendData(sessionId, output.data);
},
writeToRemote(buf) {
try { return stream.write(buf); } catch { return true; /* ignore */ }
},
waitForTransportDrain(drainOpts = {}) {
// ssh2 buffers up to its 2 MiB channel window before write() returns
// false. Watch writableLength progress so healthy slow links can take
// longer than one timeout window while a fully stalled peer is bounded.
return waitForWritableDrain(stream, {
...drainOpts,
progressIntervalMs: 1000,
// ssh2 keeps writableLength unchanged until one queued write fully
// completes, but shrinks _chunk on each channel-window adjustment.
// Include both so partial frame delivery counts as progress.
getProgressValue: () => (
(Number(stream.writableLength) || 0) + (stream._chunk?.length || 0)
),
});
},
// Upload progress tracks bytes the transport actually accepted instead
// of bytes queued (issue #3663): ssh2 keeps writableLength unchanged
// until one queued write fully completes but shrinks _chunk as the
// channel window opens, so summing both approximates the outstanding
// backlog while it drains. Without this, an rz progress bar freezes
// mid-file for as long as the channel window takes to flush.
getTransportPendingBytes() {
return (Number(stream.writableLength) || 0) + (stream._chunk?.length || 0);
},
interruptRemote() {
try { stream.signal?.("INT"); } catch { /* ignore */ }
},
probeReceiveConflicts(names, { signal } = {}) {
return probeReceiveConflicts(sessions.get(sessionId), names, { signal });
},
removeRemoteFiles(paths, { signal } = {}) {
return removeRemoteFiles(sessions.get(sessionId), paths, { signal });
},
restoreRemoteModes(entries, { signal } = {}) {
return restoreRemoteModes(sessions.get(sessionId), entries, { signal });
},
requestOverwriteDecision(filename, { signal } = {}) {
return new Promise((resolve) => {
const requestId = randomUUID();
let settled = false;
const cleanup = () => {
clearTimeout(timer);
try { signal?.removeEventListener("abort", onAbort); } catch { /* ignore */ }
zmodemOverwritePending.delete(requestId);
};
const finish = (decision) => {
if (settled) return;
settled = true;
cleanup();
resolve(decision);
};
const onAbort = () => finish({ action: "cancel", applyToRest: false });
const timer = setTimeout(() => {
finish({ action: "skip", applyToRest: false });
}, 120000);
zmodemOverwritePending.set(requestId, (payload) => finish({
action: payload.action,
applyToRest: !!payload.applyToRest,
}));
if (signal?.aborted) {
onAbort();
return;
}
signal?.addEventListener("abort", onAbort, { once: true });
safeSend(getCurrentSessionWebContents(), "netcatty:zmodem:overwrite-request", {
sessionId, requestId, filename,
});
});
},
getWebContents() {
return getCurrentSessionWebContents();
},
selectUploadFiles: selectZmodemUploadFiles
? () => selectZmodemUploadFiles(getCurrentSessionWebContentsId(), sessionId)
: undefined,
selectDownloadDirectory: selectZmodemDownloadDirectory
? () => selectZmodemDownloadDirectory(getCurrentSessionWebContentsId(), sessionId)
: undefined,
label: "SSH",
});
session.zmodemSentry = sshZmodemSentry;
stream.on("data", (data) => {
if (sessions.get(sessionId) !== session) return;
if (!shouldProcessSessionOutput(session, sshZmodemSentry)) {
logTerminalOutputDropSample(session, {
sessionId,
stream: "stdout",
bytes: Buffer.isBuffer(data) ? data.length : Buffer.byteLength(String(data)),
});
return;
}
if (session.blockUntargetedCwdProbe && session.pendingCwdRecoveryAfterUserCommand) {
session.pendingCwdRecoveryAfterUserCommand = false;
session.allowCwdRecovery = true;
}
// data is Buffer from ssh2 — feed raw bytes to ZMODEM sentry.
// In normal mode, sentry's onData callback handles decoding and buffering.
sshZmodemSentry.consume(data);
});
stream.stderr?.on("data", (data) => {
if (sessions.get(sessionId) !== session) return;
if (!shouldProcessSessionOutput(session)) {
logTerminalOutputDropSample(session, {
sessionId,
stream: "stderr",
bytes: Buffer.isBuffer(data) ? data.length : Buffer.byteLength(String(data)),
});
return;
}
// stderr is not used for ZMODEM — decode normally
const decoder = getSessionDecoder(sessionId, "stderr");
const decoded = decoder.write(data);
const output = filterTerminalInterruptOutput(session, decoded);
if (!output.accepted) {
logTerminalInterruptDrainDropSample(session, {
sessionId,
stream: "stderr",
droppedBytes: output.droppedBytes,
reason: output.reason,
accepted: false,
});
return;
}
if (output.droppedBytes > 0) {
logTerminalInterruptDrainDropSample(session, {
sessionId,
stream: "stderr",
droppedBytes: output.droppedBytes,
reason: output.reason,
accepted: true,
});
}
if (!output.data) return;
const outputMeta = takePendingInterruptOutputMeta(session);
bufferData(output.data, outputMeta);
sessionLogStreamManager.appendData(sessionId, output.data);
});
// Capture the real exit code from the remote process.
// "exit" fires when the remote shell/process exits normally;
// "close" fires whenever the channel closes (could be network drop).
// Only treat it as user-initiated exit if "exit" fired with a numeric
// code and no signal. Signal terminations (e.g. server kill, idle
// timeout) have code=null and signal set — those are not user exits
// and are reported as "signaled", not the reconnectable "closed".
// A third case exists: a remote that closes the channel without sending
// exit-status or exit-signal never fires "exit" at all (#3591). The
// initial values below stay null in that case and must not be reported
// as a real "code 0" — that reads like a clean, user-typed `exit`.
let streamExitCode = null;
let streamExitSignal = null;
let streamExited = false;
stream.on("exit", (code, signal) => {
log("shell exit", { sessionId, hostname: options.hostname, code, signal, reused: !!isReused });
streamExitCode = typeof code === "number" ? code : null;
streamExitSignal = normalizeRemoteExitSignal(signal);
streamExited = typeof code === "number" && !streamExitSignal;
// conn "close" can win the race against this channel's paced
// finalize. Stamp the signal so that path can still tell an
// administrative exit-signal from a transport drop.
if (streamExitSignal && sessions.get(sessionId) === session) {
session._remoteExitSignal = streamExitSignal;
}
if (streamExited && sessions.get(sessionId) === session) {
session._remoteExitCode = streamExitCode;
}
});
let closeFinalized = false;
stream.on("close", () => {
log("shell stream closed", {
sessionId,
hostname: options.hostname,
streamExitCode,
streamExitSignal,
streamExited,
reused: !!isReused,
transportError: sessions.get(sessionId)?._transportError,
});
const finalizeClose = () => {
if (closeFinalized) return;
closeFinalized = true;
sessionLogStreamManager.stopStream(sessionId, logStreamToken);
if (detachX11Forwarding) {
detachX11Forwarding();
detachX11Forwarding = null;
}
// Only send exit if session hasn't already been cleaned up by
// conn.once("close") — which fires before stream.on("close")
// in ssh2 when the transport drops.
const liveSession = sessions.get(sessionId);
if (liveSession === session) {
const contents = event.sender;
const transportError = liveSession?._transportError;
if (liveSession?.closed) {
// Explicit close already notified every attached renderer.
} else if (transportError) {
safeSendSessionExit({ safeSend, electronModule, sessions }, contents, sessionId, {
sessionId,
exitCode: 1,
error: transportError,
reason: "error",
_terminalSessionGeneration: liveSession?._terminalSessionGeneration,
});
} else {
// TMOUT auto-logout is a clean exit (numeric code, no signal) and
// is reported as "timeout" via the shell banner (#1062 / #977).
// An exit-signal is a separate administrative kick ("signaled").
// A channel close with neither exit-status nor exit-signal stays
// "closed" and must not be reported as code 0 (#3591).
const idleTimedOut = streamExited && looksLikeIdleAutoLogout(liveSession?._promptTrackTail);
const exitPayload = buildRemoteShellExitPayload({
sessionId,
generation: liveSession?._terminalSessionGeneration,
exitCode: streamExitCode,
exitSignal: streamExitSignal,
shellExited: streamExited,
idleTimedOut,
});
safeSendSessionExit({ safeSend, electronModule, sessions }, contents, sessionId, exitPayload);
}
liveSession?.zmodemSentry?.cancel();
// Release this channel's hold on the shared connection. The transport
// (and any jump-host chain) is only ended once the last channel is
// gone, so closing a reused tab — or the original tab while a copy is
// still open — leaves the siblings connected.
releaseConnectionRef(liveSession);
closeTerminalOutputSession?.(sessionId);
sessions.delete(sessionId);
sessionEncodings.delete(sessionId);
sessionDecoders.delete(sessionId);
}
};
flushBufferPaced(finalizeClose);
});
// Pre-seed encoding from host charset if it's a GB variant. Seed BOTH the
// output decoder (sessionEncodings) and the terminal input encoder
// (session.encoding, read by terminalBridge.writeToSession) so they agree
// from the first byte — otherwise a GB18030 host decoded output as GB18030
// while encoding keystrokes as UTF-8 until the user re-picked the encoding
// (issue #1216). The gate matches the renderer's two-value encoding state
// (Terminal.tsx) so behavior for other/arbitrary charsets is unchanged:
// the renderer pushes the effective encoding via setEncoding on attach,
// and that handler keeps both halves in sync.
const initialEncoding = normalizeTerminalEncoding(options.charset);
if (initialEncoding === "gb18030") {
sessionEncodings.set(sessionId, "gb18030");
session.encoding = "gb18030";
}
// Run startup command if specified. Encode it with the same charset the
// interactive input path uses (issue #1216) so a startup command with
// non-ASCII characters reaches a GB18030 host correctly too.
if (options.startupCommand) {
setTimeout(() => {
stream.write(encodeTerminalInput(`${options.startupCommand}\n`, session.encoding));
}, 300);
}
return session;
}
/**
* Open a new interactive shell channel on an already-authenticated SSH
* connection borrowed from `sourceSession`, instead of dialing a fresh
* connection. This is what makes "Copy Tab" skip a second MFA prompt
* (issue #1204): the SSH transport and its authentication are reused; only
* a new session channel is requested.
*
* Resolves with `{ sessionId }` on success. Throws on failure so the caller
* can fall back to a normal fresh connection.
*/
async function openReusedShellSerialized(
event,
options,
sourceSession,
sessionId,
log,
connRef,
refHolder,
reuseOpts = {},
) {
const cols = options.cols || 80;
const rows = options.rows || 24;
const sender = event.sender;
const conn = sourceSession.conn;
// Bastions (jumpHosts or direct targets) rate-limit rapid session channel
// opens ("channelOpen too offen"). Opening a discovery exec *before* the
// shell burns that budget and Copy Tab falls back to a fresh login
// (issue #2704). Open the shell first; discover shellPid afterwards.
const configuredBackoffMs = Number(options.sshChannelOpenRateLimitBackoffMs);
const discoveryBackoffMs = Number.isFinite(configuredBackoffMs) && configuredBackoffMs > 0
? configuredBackoffMs
: 150;
const shellPidsBeforeOpen = [...sessions.values()]
.filter((candidate) => candidate?.connRef === connRef && candidate.shellPid)
.map((candidate) => String(candidate.shellPid));
log("reusing existing connection for new shell channel", {
sessionId,
sourceSessionId: options.sourceSessionId,
hostname: options.hostname,
});
const sendProgress = (status, error) => {
if (!sender.isDestroyed()) {
sender.send("netcatty:chain:progress", {
sessionId, hop: 1, total: 1, label: options.hostname, status, error,
});
}
};
sendProgress('shell');
const shellOptions = buildInteractiveShellOptions(options);
// Pin the shared connection *before* issuing the async shell request.
// Otherwise, if the source tab is closed while conn.shell() is pending,
// releaseConnectionRef could drop the count to zero and end the connection
// out from under the channel we're opening. We hold a temporary session
// object as the ref holder, then hand the ref over to the real session
// once the channel opens. On any failure we release this hold so the count
// is restored.
return new Promise((resolve, reject) => {
let settled = false;
let onConnError = null;
let abortOpenedStream = null;
const retryAbortController = new AbortController();
const pendingBootSignal = options._passphraseSignal || null;
const abortRetryFromPendingBoot = () => {
retryAbortController.abort(
pendingBootSignal?.reason || new Error("SSH session start was cancelled"),
);
abortOpenedStream?.(
pendingBootSignal?.reason || new Error("SSH session start was cancelled"),
);
};
const cleanupConnectionGuard = () => {
if (onConnError) conn.removeListener("error", onConnError);
};
const cleanupPendingBootGuard = () => {
abortOpenedStream = null;
pendingBootSignal?.removeEventListener?.("abort", abortRetryFromPendingBoot);
};
const cleanupReuseGuards = () => {
cleanupConnectionGuard();
cleanupPendingBootGuard();
};
if (pendingBootSignal?.aborted) {
abortRetryFromPendingBoot();
} else {
pendingBootSignal?.addEventListener?.("abort", abortRetryFromPendingBoot, { once: true });
}
const failReuse = (err) => {
if (settled) return;
settled = true;
cleanupReuseGuards();
retryAbortController.abort(err);
// Release the hold we took up-front so the source's reference count is
// not leaked when we fall back to a fresh connection.
releaseConnectionRef(refHolder);
reject(err);
};
// If the borrowed connection dies before the channel opens, surface it
// as a normal failure so the caller's catch can fall back to a fresh
// connection. Removed once the channel opens so we don't leave a stray
// listener on the shared connection (the owner's own error handler stays
// responsible thereafter).
onConnError = (connErr) => {
failReuse(connErr);
};
conn.once("error", onConnError);
if (
connRef.allowShellReuse === false
|| Number(connRef.pendingAbandonedShellOpens) > 0
) {
conn.removeListener("error", onConnError);
failReuse(new Error("Transport is no longer reusable for shells"));
return;
}
try {
const rateLimitBackoffMs = Number(options.sshChannelOpenRateLimitBackoffMs);
openBoundedSshShellCallback(
conn,
{
term: "xterm-256color",
cols,
rows,
},
shellOptions,
(err, stream) => {
cleanupConnectionGuard();
if (settled) {
// Connection already failed; close any channel that still opened
// and drop the hold (failReuse already released, so guard with the
// settled check above means we only get here post-failure).
if (stream) { try { stream.close(); } catch { /* ignore */ } }
return;
}
if (err) {
log("reused shell open failed", { sessionId, hostname: options.hostname, error: err.message });
sendProgress('error', `Failed to open shell: ${err.message}`);
failReuse(err);
return;
}
if (connRef.allowShellReuse === false) {
if (stream) { try { stream.close(); } catch { /* ignore */ } }
failReuse(new Error("Transport is no longer reusable for shells"));
return;
}
sendProgress('connected');
abortOpenedStream = (abortError) => {
try { stream.close(); } catch { /* ignore */ }
failReuse(abortError);
};
if (pendingBootSignal?.aborted) {
abortOpenedStream(
pendingBootSignal.reason || new Error("SSH session start was cancelled"),
);
return;
}
const finishReusedShellOpen = (prefetchedChunks = []) => {
cleanupPendingBootGuard();
if (settled) {
if (stream) { try { stream.close(); } catch { /* ignore */ } }
return;
}
// Hand the up-front lease over to the real session without changing
// the lease count (transferConnectionRef). setupShellSession still
// records connRef; transfer rebinds _sshTransportLeaseId so a later
// releaseConnectionRef(session) returns the right lease.
try {
setupShellSession({
conn,
stream,
options: { ...options, _connRef: connRef },
sessionId,
event,
log,
detachX11Forwarding: null,
chainConnections: [],
isReused: true,
});
} catch (setupErr) {
// openBoundedSshShellCallback delivers this from a Promise .then
// without catching callback throws — reject via failReuse.
failReuse(setupErr);
return;
}
if (prefetchedChunks.length > 0) {
for (const chunk of prefetchedChunks) {
stream.emit("data", chunk);
}
}
const reconnectAfterLastShellClose =
consumePendingShellReconnectRisk(connRef);
const copiedSession = sessions.get(sessionId);
if (copiedSession && reconnectAfterLastShellClose) {
copiedSession.blockUntargetedCwdProbe = true;
copiedSession.parkedReconnectRisk = reconnectAfterLastShellClose;
}
if (copiedSession) {
if (typeof transferConnectionRef === "function") {
transferConnectionRef(refHolder, copiedSession);
} else {
// Legacy count model: detach holder without decrement.
refHolder.connRef = null;
}
} else {
refHolder.connRef = null;
}
void discoverCopiedShellPid(copiedSession).then((newShellPid) => {
// Bind PID only to the session this reuse opened. A higher
// bootEpoch reconnect may already own sessionId in the map.
const liveSession = sessions.get(sessionId);
if (liveSession && liveSession === copiedSession && newShellPid) {
liveSession.shellPid = newShellPid;
}
settled = true;
resolve({ sessionId });
});
};
const discoverCopiedShellPid = async (copiedSession) => {
if (options.skipShellPidDiscovery) return null;
const liveBaseline = () => [...sessions.values()]
.filter((candidate) => (
candidate?.connRef === connRef
&& candidate !== copiedSession
&& candidate.shellPid
))
.map((candidate) => String(candidate.shellPid));
const listUnassignedSiblings = () => [...sessions.values()].filter(
(candidate) => (
candidate?.connRef === connRef
&& candidate !== copiedSession
&& !candidate.shellPid
),
);
// Prefer PIDs already recorded on sibling tabs of this shared
// transport. Fall back to the pre-shell snapshot when the source
// closed before discovery runs but had a known shellPid.
let baseline = liveBaseline();
if (baseline.length === 0) {
baseline = shellPidsBeforeOpen;
}
// Also reconcile when some siblings are already tracked but the
// copy source (or another tab) still lacks shellPid — otherwise
// waitForNew sees multiple "new" PIDs and returns null.
const needsUntrackedReconcile = listUnassignedSiblings().length > 0;
const blockedEndpointSibling = !options.sourceSessionId
&& listUnassignedSiblings().some(
(candidate) => candidate.blockUntargetedCwdProbe === true,
);
// Idle-park reconnect after the last interactive shell closed:
// no sibling tabs share this transport, so post-open discovery
// cannot disambiguate anything. Skip the exec — bastions often
// tear down the interactive session when a second channel opens,
// racing start completion as
// "Terminal session closed before its output route opened" (#2923).
// Copy Tab (sourceSessionId) still needs discovery even when the
// source closes mid-open and leaves an empty baseline.
if (
baseline.length === 0
&& !options.sourceSessionId
&& (!needsUntrackedReconcile || blockedEndpointSibling)
) {
if (copiedSession && blockedEndpointSibling) {
copiedSession.blockUntargetedCwdProbe = true;
copiedSession.parkedReconnectRisk = {
oldShellPids: [],
hasUnknownOldShell: true,
};
}
return null;
}
if (baseline.length === 0 || needsUntrackedReconcile) {
const discovery = await listInteractiveShellPidsResilient(conn, {
initialDelayMs: discoveryBackoffMs,
attempts: 4,
backoffMs: discoveryBackoffMs,
});
if (!discovery.available && !discovery.rateLimited) {
// Discovery is permanently unavailable (not rate-limited).
return null;
}
if (discovery.available && discovery.pids.length > 0) {
const assignedPids = new Set(liveBaseline());
for (const pid of baseline) assignedPids.add(String(pid));
const unclaimed = discovery.pids.filter((pid) => !assignedPids.has(pid));
const unassignedSiblings = listUnassignedSiblings();
if (unclaimed.length === 1 && unassignedSiblings.length === 1) {
unassignedSiblings[0].shellPid = unclaimed[0];
baseline = liveBaseline();
} else if (unassignedSiblings.length === 0 && unclaimed.length === 1) {
// Sole unclaimed PID is ambiguous once the source tab is
// gone: the closing source process may still be listed
// while the copied shell has not appeared yet. Wait for a
// PID beyond that candidate; if none appears and the
// candidate remains the only unclaimed shell, it is the
// copy (source process already exited).
const candidatePid = String(unclaimed[0]);
const waited = await waitForNewInteractiveShellPid(conn, [candidatePid], {
initialDelayMs: discoveryBackoffMs,
backoffMs: discoveryBackoffMs,
});
if (waited) return waited;
const recheck = await listInteractiveShellPids(conn);
if (!recheck.available) return null;
const assigned = new Set(liveBaseline());
const remaining = recheck.pids
.map(String)
.filter((pid) => !assigned.has(pid));
if (remaining.length === 1) return remaining[0];
return null;
} else if (unassignedSiblings.length === 1 && unclaimed.length === 2) {
// Source never recorded shellPid (e.g. OSC 7 cwd skipped
// the probe), so the first post-open scan already lists
// both shared shells. Reintroducing a pre-open exec would
// burn bastion channel budget (#2704). Disambiguate by
// process age (etimes): login shells on one transport are
// created sequentially, so the copied shell is younger.
// Numeric PID order is not a timestamp and fails when the
// PID allocator wraps between source and copy.
const ages = discovery.ages || {};
const left = String(unclaimed[0]);
const right = String(unclaimed[1]);
const leftAge = ages[left];
const rightAge = ages[right];
if (
Number.isFinite(leftAge)
&& Number.isFinite(rightAge)
&& leftAge !== rightAge
) {
const older = leftAge > rightAge ? left : right;
const newer = older === left ? right : left;
unassignedSiblings[0].shellPid = older;
return newer;
}
// Ages tied (same etimes second) or unavailable: refuse
// numeric PID order — after wrap the lower PID can be the
// copy. Leave the pair unassigned and keep only already-
// tracked PIDs in the baseline so waitForNew can still
// claim the copy if one of the two later disappears.
baseline = [...assignedPids];
} else if (assignedPids.size > 0) {
baseline = [...assignedPids];
}
}
// Empty successful scans (shell not visible yet) must not
// abort — waitForNew retries until the new shell appears.
}
return waitForNewInteractiveShellPid(conn, baseline, {
// Brief pause after the shell channel so bastion rate limits
// have a chance to clear before the discovery exec.
initialDelayMs: discoveryBackoffMs,
backoffMs: discoveryBackoffMs,
});
};
// Decide at channel-open time, not when start() was queued.
// Copy Tab can lose its source shell while this open is still
// pinned; pendingShellReconnectRisk is recorded then (#2923).
const confirmReusedShellLiveness = reuseOpts.confirmReusedShellLiveness === true
|| shouldConfirmReusedShellLiveness({
state: connRef?.state,
pendingShellReconnectRisk: connRef?.pendingShellReconnectRisk,
remoteSshVersion: conn?._remoteVer,
});
if (!confirmReusedShellLiveness) {
finishReusedShellOpen();
return;
}
// Idle-park reconnect on an unknown / non-multiplex banner: the
// channel can open and then immediately exit 0 (齐治 TERM-SSHD,
// issue #2923). Fail reuse before setupShellSession so start()
// can discard the parked transport and dial fresh.
void waitForReusedShellLiveness(stream, {
settleMs: resolveReusedShellLivenessMs(options.sshReusedShellLivenessMs),
setTimeout,
clearTimeout,
}).then((liveness) => {
if (settled) {
if (stream) { try { stream.close(); } catch { /* ignore */ } }
return;
}
if (!liveness.alive) {
log("reused parked shell closed immediately, discarding transport", {
sessionId,
hostname: options.hostname,
reason: liveness.reason,
code: liveness.code,
transportId: connRef?.id,
});
if (connRef) {
connRef.allowIdlePark = false;
connRef.allowShellReuse = false;
if (typeof markEndpointNoIdlePark === "function") {
markEndpointNoIdlePark(connRef.endpoint || connRef.endpointKey);
}
}
try { stream.close(); } catch { /* ignore */ }
failReuse(new Error("Reused parked shell closed immediately"));
return;
}
finishReusedShellOpen(liveness.buffered);
}).catch((livenessErr) => {
failReuse(livenessErr);
});
},
{
...(Number.isFinite(rateLimitBackoffMs) && rateLimitBackoffMs > 0
? { rateLimitBackoffMs }
: {}),
...(options.sourceSessionId
? { rateLimitRetryTimeoutMs: COPY_TAB_RATE_LIMIT_RETRY_TIMEOUT_MS }
: {}),
signal: retryAbortController.signal,
// Cancelling one pending Copy Tab must not destroy the source
// tab's shared authenticated transport.
invalidateOnAbort: false,
onAbandonedOpen: () => {
connRef.pendingAbandonedShellOpens =
(Number(connRef.pendingAbandonedShellOpens) || 0) + 1;
},
onAbandonedOpenSettled: () => {
const pending = Math.max(
0,
(Number(connRef.pendingAbandonedShellOpens) || 0) - 1,
);
if (pending === 0) delete connRef.pendingAbandonedShellOpens;
else connRef.pendingAbandonedShellOpens = pending;
},
},
);
} catch (syncErr) {
// ssh2 can throw synchronously (e.g. "Not connected") if the borrowed
// transport dropped between findReusableSession and conn.shell(). Make
// sure we drop the listener and release the up-front ref so the count
// isn't leaked, then fall back to a fresh connection.
log("reused shell threw synchronously", { sessionId, hostname: options.hostname, error: syncErr?.message });
failReuse(syncErr);
}
});
}
function reuseShellSession(event, options, sourceSession, sessionId, log, reuseOpts = {}) {
const connRef = sourceSession.connRef;
const {
ensureConcurrentJoinIdentity = false,
...openReuseOpts
} = reuseOpts;
const refHolder = {};
// Pin while queued as well as while opening: the source tab may close
// before this copy reaches the front of the per-connection queue.
acquireConnectionRef(refHolder, connRef);
const previous = connRef.shellOpenQueue || Promise.resolve();
const operation = previous
.catch(() => {})
.then(async () => {
try {
if (
ensureConcurrentJoinIdentity
&& !await ensureConcurrentJoinShellIdentity(connRef, options)
) {
const error = new Error("Concurrent terminal shell identity is unavailable");
error.code = "SSH_CONCURRENT_SHELL_IDENTITY_UNSAFE";
throw error;
}
} catch (error) {
releaseConnectionRef(refHolder);
throw error;
}
return openReusedShellSerialized(
event,
options,
sourceSession,
sessionId,
log,
connRef,
refHolder,
openReuseOpts,
);
});
const tail = operation.then(() => undefined, () => undefined);
connRef.shellOpenQueue = tail;
return operation.finally(() => {
if (connRef.shellOpenQueue === tail) {
delete connRef.shellOpenQueue;
}
});
}
async function startSSHSession(event, options) {
const sessionId = options.sessionId || randomUUID();
// Per-attempt, main-process-only trust. Never accept a caller-provided
// list of supposedly verified keys for a dedicated transport.
const acceptedHostKeys = [];
const recordAcceptedHostKey = (info) => acceptedHostKeys.push({ ...info });
const monitorMode = options._monitorMode === true;
const testMode = options.testMode === true || monitorMode;
const sender = event.sender;
const log = createSshDiagnosticLogger(
!!options.sshDebugLogEnabled || process.env.NETCATTY_SSH_DEBUG === "1",
);
const sendConnectionReuseFallback = () => {
if (!sender.isDestroyed()) {
sender.send("netcatty:connection-reuse:fallback", {
sessionId,
sourceSessionId: options.sourceSessionId,
});
}
};
// Resolve forwarding before connection reuse so an agent-provider change
// (for example Bitwarden becoming available after unlock) cannot attach a
// new shell to a transport that still forwards the previous socket.
options = await prepareAgentForwardingOptions(options, getAvailableForwardingAgentSocket);
// Connection reuse (issue #1204): when a tab is duplicated we try to open
// a new shell channel on the source tab's already-authenticated
// connection. This skips key exchange + authentication entirely, so an
// MFA-protected host does not prompt for a second factor. Only applies to
// a live, interactive SSH shell source; anything else falls through to a
// normal fresh connection below.
//
// X11 forwarding is negotiated per shell channel using a fresh fake
// cookie wired up at connection time, so a reused channel would not carry
// X11. For X11 hosts we deliberately skip reuse and make a fresh
// connection so the duplicate keeps working X11 forwarding.
const reuseEndpoint = buildConnectionReuseEndpoint(options);
const allowTransportReuse = options.reuseTransport !== false;
// Copy/Split reuse is source-specific. If that source disappears or its
// channel cannot open, fall through to a fresh login instead of silently
// borrowing another live, idle, or in-flight transport for the endpoint.
const allowGeneralTransportReuse = allowTransportReuse && !options.sourceSessionId;
const sourceReuseState = options._sourceReuseState;
const canAttemptSourceReuse = Boolean(
allowTransportReuse
&& options.sourceSessionId
&& !options.singleChannelSsh
&& !options.x11Forwarding
&& (!sourceReuseState || sourceReuseState.attempted !== true),
);
if (canAttemptSourceReuse) {
if (sourceReuseState) sourceReuseState.attempted = true;
const sourceSession = findReusableSession(sessions, options.sourceSessionId, reuseEndpoint)
|| (sourceReuseState?.session
? findReusableSession(
new Map([[options.sourceSessionId, sourceReuseState.session]]),
options.sourceSessionId,
reuseEndpoint,
)
: null);
if (sourceSession) {
try {
return await reuseShellSession(event, options, sourceSession, sessionId, log);
} catch (reuseErr) {
if (options._passphraseSignal?.aborted) throw reuseErr;
log("connection reuse failed, falling back to fresh connection", {
sessionId,
sourceSessionId: options.sourceSessionId,
error: reuseErr?.message,
});
sendConnectionReuseFallback();
// Fall through to establish a fresh connection.
}
} else {
log("connection reuse requested but source not reusable, connecting fresh", {
sessionId,
sourceSessionId: options.sourceSessionId,
});
sendConnectionReuseFallback();
}
}
// Idle-park / endpoint reuse: after the last tab returns its lease the
// transport may still be warm. Open a new shell channel without re-auth.
if (allowGeneralTransportReuse && !options.x11Forwarding && typeof findTransportByEndpoint === "function") {
// Shell park reuse requires exact agentForwarding match so disabling
// ForwardAgent cannot reattach to a warm conn that still exposes the agent.
const parked = findTransportByEndpoint(reuseEndpoint, { kind: "shell" });
if (parked?.conn && (parked.state === "live" || parked.state === "idle")) {
try {
log("reusing parked or shared transport for new shell channel", {
sessionId,
hostname: options.hostname,
transportId: parked.id,
transportState: parked.state,
});
const confirmReusedShellLiveness = shouldConfirmReusedShellLiveness({
state: parked.state,
pendingShellReconnectRisk: parked.pendingShellReconnectRisk,
remoteSshVersion: parked.conn?._remoteVer,
});
return await reuseShellSession(
event,
options,
{
conn: parked.conn,
connRef: parked,
// openReusedShellSerialized only needs conn + connRef; stream is
// required by findReusableSession but we bypass that path here.
stream: {},
},
sessionId,
log,
{ confirmReusedShellLiveness },
);
} catch (parkErr) {
if (options._passphraseSignal?.aborted) {
throw options._passphraseSignal.reason instanceof Error
? options._passphraseSignal.reason
: parkErr;
}
log("parked transport reuse failed, falling back to fresh connection", {
sessionId,
hostname: options.hostname,
error: parkErr?.message,
});
// Fall through to a normal dial.
}
}
}
// Atomically reserve the physical dial before any asynchronous key,
// proxy, or jump-host preparation. A second terminal/SFTP/forward open
// for the same compatible endpoint can wait for this leader and then
// open its own channel on the authenticated transport.
let pendingDialCoordination = options._pendingDialState?.coordination || null;
if (
allowGeneralTransportReuse
&& !pendingDialCoordination
&& !options.x11Forwarding
&& typeof beginTransportDial === "function"
) {
const coordination = beginTransportDial(reuseEndpoint, { kind: "shell" });
if (coordination.role === "reuse" || coordination.role === "join") {
try {
const transport = coordination.role === "reuse"
? coordination.transport
: await waitForTransportDial(coordination);
return await reuseShellSession(
event,
options,
{ conn: transport.conn, connRef: transport, stream: {} },
sessionId,
log,
{
ensureConcurrentJoinIdentity: coordination.role === "join"
&& coordination._record?.kind === "shell",
},
);
} catch (coordinationErr) {
if (coordinationErr?.code === "SSH_CONCURRENT_SHELL_IDENTITY_UNSAFE") {
log("concurrent transport shell identity unavailable; connecting fresh", {
sessionId,
hostname: options.hostname,
});
} else {
if (options._passphraseSignal?.aborted) {
throw options._passphraseSignal.reason instanceof Error
? options._passphraseSignal.reason
: coordinationErr;
}
// A waiter must observe the leader's real failure instead of
// immediately starting a second authentication prompt. Existing
// transport reuse keeps its historical fresh-dial fallback.
if (coordination.role === "join") throw coordinationErr;
log("coordinated transport reuse failed, connecting fresh", {
sessionId,
hostname: options.hostname,
error: coordinationErr?.message,
});
}
}
} else {
pendingDialCoordination = coordination;
if (options._pendingDialState) {
options._pendingDialState.coordination = coordination;
}
}
}
if (options._passphraseSignal?.aborted) {
throw options._passphraseSignal.reason instanceof Error
? options._passphraseSignal.reason
: new Error("SSH session start was cancelled");
}
const cols = options.cols || 80;
const rows = options.rows || 24;
const sendProgress = (hop, total, label, status, error) => {
if (!sender.isDestroyed()) {
sender.send("netcatty:chain:progress", { sessionId, hop, total, label, status, error });
}
};
try {
const { tcpConnectTimeoutMs, authReadyTimeoutMs } = resolveSshConnectionTimeouts(options);
log("session starting", {
sessionId,
hostname: options.hostname,
port: options.port || 22,
username: options.username || "root",
hostLabel: options.hostLabel || options.label,
hasJumpHosts: (options.jumpHosts || []).length > 0,
hasProxy: !!options.proxy,
tcpConnectTimeoutMs,
authReadyTimeoutMs,
});
const conn = new SSHClient();
let chainConnections = [];
let connectionSocket = null;
// Register the test transport BEFORE the chain/proxy dial so an
// in-flight bastion/proxy attempt can be cancelled. `connectThroughChain`
// updates `pendingConn` and `chainConnections` via `options._tunnelRef`
// as each hop/proxy socket is established.
let testTransport = null;
if (testMode) {
testTransport = { conn, socket: null, pendingConn: null, chainConnections };
registerTestConnectionTransport(sessionId, testTransport);
}
// Determine if we have jump hosts
const jumpHosts = options.jumpHosts || [];
const hasJumpHosts = jumpHosts.length > 0;
const hasProxy = !!options.proxy;
const totalHops = jumpHosts.length + 1; // +1 for final target
// Build base connection options for final target
const keepalivePolicy = resolveConnectionKeepalivePolicy(options);
const connectOpts = {
host: options.hostname,
port: options.port || 22,
username: options.username || "root",
// `timeout` covers TCP dial silence; `readyTimeout` covers the full
// SSH handshake/auth flow so MFA still has enough time.
timeout: tcpConnectTimeoutMs,
// ssh2 starts readyTimeout before TCP connects. The auth-ready timer
// below starts explicitly from the connection event instead.
readyTimeout: 0,
// Resolved keepalive (caller decides whether host override or global
// applies). interval is in seconds; 0 means truly disabled, so
// countMax also goes to 0 to skip ssh2's dead-connection check.
keepaliveInterval: keepalivePolicy.keepaliveIntervalMs,
keepaliveCountMax: keepalivePolicy.keepaliveCountMax,
// Enable keyboard-interactive authentication (required for 2FA/MFA)
tryKeyboard: true,
algorithms: buildAlgorithms(options.legacyAlgorithms, {
skipEcdsaHostKey: options.skipEcdsaHostKey,
algorithmOverrides: options.algorithmOverrides,
}),
};
attachSshDebugLogger(connectOpts, log);
logSshAlgorithms("Target host", connectOpts.algorithms, {
hostname: options.hostname,
port: options.port || 22,
legacyAlgorithms: !!options.legacyAlgorithms,
skipEcdsaHostKey: !!options.skipEcdsaHostKey,
hasAlgorithmOverrides: !!options.algorithmOverrides,
}, log);
connectOpts.hostVerifier = hostKeyVerifier.createHostVerifier({
sender,
sessionId,
hostname: options.hostname,
port: options.port || 22,
knownHosts: options.knownHosts,
verifyHostKeys: options.verifyHostKeys,
bootEpoch: options.bootEpoch,
onAccepted: recordAcceptedHostKey,
});
// Authentication for final target
const hasCertificate = options.authMethod !== "password"
&& typeof options.certificate === "string"
&& options.certificate.trim().length > 0;
const isAutomaticAuth = options.authMethod === "auto";
const isSelectedKeyAuth = options.authMethod === "key" || options.authMethod === "certificate";
const effectivePassphrase = options.passphrase;
console.log("[SSH] Auth configuration:", {
hasCertificate,
keySource: options.keySource,
hasPublicKey: !!options.publicKey,
hasPrivateKey: !!options.privateKey,
hasPassword: !!options.password,
hasEffectivePassphrase: !!effectivePassphrase,
});
log("Auth configuration", {
hasCertificate,
keySource: options.keySource,
hasPublicKey: !!options.publicKey,
hasPrivateKey: !!options.privateKey,
});
let authAgent = null;
// FIDO2 sk-* handles cannot be used as ssh2 software privateKeys.
// Detect only from key material (public/private text), not path names —
// path heuristics false-positive soft keys like id_mask.
let isFidoSkAuth = looksLikeSkOpenSshMaterial(options.privateKey)
|| (Array.isArray(options.agentPublicKeys)
&& options.agentPublicKeys.some((key) => looksLikeSkOpenSshMaterial(key)))
|| options.useFidoAgent === true;
// Path-only IdentityFile / reference keys may omit inline material and
// still be sk-* on disk — peek before choosing software-key auth.
if (!isFidoSkAuth && options.authMethod !== "password"
&& Array.isArray(options.identityFilePaths)
&& options.identityFilePaths.length > 0) {
try {
const { identityFilesLookLikeSk } = require("../sshAuthHelper.cjs");
isFidoSkAuth = await identityFilesLookLikeSk(options.identityFilePaths);
} catch {
// ignore probe failures; fall through to soft-key path
}
}
const forceSystemAgentForFido = isFidoSkAuth && options.authMethod !== "password";
// Propagate detected FIDO state onto options so shouldOfferAgentForLogin
// (and later auth decisions) see the same agent intent as preparation.
// Path-only IdentityFile SK picks often arrive with useSshAgent:false.
if (forceSystemAgentForFido) {
options.useSshAgent = true;
options.useFidoAgent = true;
options.identitiesOnly = options.identitiesOnly === true
|| Boolean(
(Array.isArray(options.agentPublicKeys) && options.agentPublicKeys.length)
|| (Array.isArray(options.identityFilePaths) && options.identityFilePaths.length),
);
options.addKeysToAgent = options.addKeysToAgent || "yes";
options.loadIdentityFilesIntoAgent = true;
}
const systemAuthAgent = (shouldPrepareSystemAgentForLogin(options) || forceSystemAgentForFido)
? await prepareSystemSshAgentForAuth({
...options,
// Only force the agent path when the caller already opted in or the
// key material requires hardware signing (FIDO). Automatic/password
// modes reach here via shouldPrepareSystemAgentForLogin's opportunistic
// check too; forcing useSshAgent:true unconditionally would make a
// missing system agent a hard failure for every "auto" connection
// instead of the no-op prepareSystemSshAgentForAuth already provides
// via its own useSshAgent !== true guard.
useSshAgent: options.useSshAgent === true || forceSystemAgentForFido,
useFidoAgent: forceSystemAgentForFido || options.useFidoAgent === true,
// Prefer loading the sk handle; keep identitiesOnly when a public
// key selector is available.
identitiesOnly: options.identitiesOnly === true
|| (forceSystemAgentForFido && Boolean(
(Array.isArray(options.agentPublicKeys) && options.agentPublicKeys.length)
|| (Array.isArray(options.identityFilePaths) && options.identityFilePaths.length),
)),
addKeysToAgent: options.addKeysToAgent || (forceSystemAgentForFido ? "yes" : options.addKeysToAgent),
loadIdentityFilesIntoAgent: forceSystemAgentForFido || options.loadIdentityFilesIntoAgent,
resolveWebContents: () => {
try {
return sender && !sender.isDestroyed?.() ? sender : null;
} catch {
return null;
}
},
}, "[SSH]")
: null;
// Kick off the default-key scan now so it overlaps the identity-file /
// inline-key preparation below instead of running serially after it.
// findAllDefaultPrivateKeys swallows its own fs errors and never rejects,
// so leaving this promise briefly unawaited cannot surface an unhandled
// rejection even if the key prep throws first.
const defaultKeysPromise = findAllDefaultPrivateKeys();
const identityFile = options.authMethod !== "password" && !options.privateKey && !systemAuthAgent
? await loadFirstIdentityFileForAuth({
sender,
identityFilePaths: options.identityFilePaths,
hostname: options.hostname,
initialPassphrase: options.passphrase,
passphraseSignal: options._passphraseSignal,
sessionId,
bootEpoch: options.bootEpoch,
logPrefix: "[SSH]",
onPassphrasePromptShown: () => sendProgress(
totalHops, totalHops, options.hostname, "auth-attempt", "waiting for user input...",
),
onPassphrasePromptResolved: () => sendProgress(
totalHops, totalHops, options.hostname, "auth-attempt", "user responded",
),
onLoaded: (loaded) => {
log("Loaded identity file", { keyPath: loaded.keyPath, encrypted: !!loaded.passphrase });
},
onError: (err, keyPath) => {
log("Failed to read identity file", { keyPath, error: err.message });
},
})
: null;
const inlineKey = options.authMethod !== "password"
&& options.privateKey
&& !systemAuthAgent
&& !looksLikeSkOpenSshMaterial(options.privateKey)
? await preparePrivateKeyForAuth({
sender,
privateKey: options.privateKey,
keyId: options.keyId,
keyName: options.keyId || options.username,
hostname: options.hostname,
initialPassphrase: effectivePassphrase,
passphraseSignal: options._passphraseSignal,
sessionId,
bootEpoch: options.bootEpoch,
logPrefix: "[SSH]",
onPassphrasePromptShown: () => sendProgress(
totalHops, totalHops, options.hostname, "auth-attempt", "waiting for user input...",
),
onPassphrasePromptResolved: () => sendProgress(
totalHops, totalHops, options.hostname, "auth-attempt", "user responded",
),
})
: null;
const effectivePrivateKey = inlineKey?.privateKey || identityFile?.privateKey;
const effectiveIdentityPassphrase = inlineKey?.passphrase || identityFile?.passphrase;
if (systemAuthAgent) {
connectOpts.agent = systemAuthAgent;
require("../attachFidoAgentRelease.cjs").attachFidoAgentRelease(conn, systemAuthAgent);
}
// Soft-key certificates use NetcattyAgent local signing. FIDO SK + cert
// must keep the system/owned agent (hardware signs via ssh-sk-helper).
if (hasCertificate && !forceSystemAgentForFido) {
authAgent = new NetcattyAgent({
mode: "certificate",
webContents: event.sender,
meta: {
label: options.keyId || options.username || "",
certificate: options.certificate,
privateKey: effectivePrivateKey,
passphrase: effectiveIdentityPassphrase,
},
});
connectOpts.agent = authAgent;
} else if (effectivePrivateKey && !forceSystemAgentForFido) {
connectOpts.privateKey = effectivePrivateKey;
if (effectiveIdentityPassphrase) {
connectOpts.passphrase = effectiveIdentityPassphrase;
}
}
// Whitespace-only passwords are valid SSH secrets (issue #2036).
if (isPasswordProvided(options.password)) {
connectOpts.password = options.password;
}
// Default ~/.ssh keys are a fallback for hosts that have no explicit
// credentials. Password-only hosts must NOT silently fall back to local
// keys: jump-host / SFTP paths already honor that rule via
// buildAuthHandler (issue #266), and falling back only on the direct
// terminal path makes a wrong saved password look fine until ProxyJump
// or SFTP fails (issue #2079).
//
// The full list is scanned exactly once (kicked off above); its first
// entry is the preferred default key — identical to what a separate
// findDefaultPrivateKey() scan would return — so derive it here instead
// of walking ~/.ssh a second time. (Pinned by
// sshBridge.defaultKeyEquivalence.test.cjs.)
let usedDefaultKeyAsPrimary = false;
const discoveredDefaultKeys = await defaultKeysPromise;
const allDefaultKeys = isSelectedKeyAuth || options.authMethod === "password" || (systemAuthAgent && options.identitiesOnly)
? []
: discoveredDefaultKeys;
const defaultKeyInfo = allDefaultKeys[0] ?? null;
// Explicit password without a user-configured key/certificate/agent is
// password-only — same predicate buildAuthHandler uses for isPasswordOnly.
const isPasswordOnlyAuth =
options.authMethod === "password" || (
!isAutomaticAuth &&
isPasswordProvided(connectOpts.password) &&
!connectOpts.privateKey &&
!hasCertificate &&
!systemAuthAgent &&
!hasUserConfiguredKey(options)
);
if (defaultKeyInfo && !isPasswordOnlyAuth) {
log("Found default SSH key for fallback", { keyPath: defaultKeyInfo.keyPath, keyName: defaultKeyInfo.keyName });
} else if (defaultKeyInfo && isPasswordOnlyAuth) {
log("Skipping default SSH key fallback for password-only auth", {
keyPath: defaultKeyInfo.keyPath,
keyName: defaultKeyInfo.keyName,
});
}
// Use unlocked encrypted keys if provided (from retry after auth failure)
// These are passed via _unlockedEncryptedKeys from startSSHSessionWrapper
const unlockedEncryptedKeys = resolveUnlockedEncryptedKeysForAuth(
options,
Boolean(isSelectedKeyAuth || (systemAuthAgent && options.identitiesOnly)),
);
if (unlockedEncryptedKeys.length > 0) {
log("Using unlocked encrypted keys from retry", {
count: unlockedEncryptedKeys.length,
keyNames: unlockedEncryptedKeys.map(k => k.keyName)
});
}
// Automatic mode intentionally mirrors OpenSSH-style discovery even
// when a saved password exists: agent and default keys are tried first,
// then the password. Password-only mode never enters this path.
if (isAutomaticAuth && !connectOpts.agent && options.useSshAgent !== false) {
const automaticAgentSocket = await getAvailableAgentSocket();
if (automaticAgentSocket) {
connectOpts.agent = automaticAgentSocket;
log("Automatic auth found SSH agent", { agentSocket: automaticAgentSocket });
}
}
// If no primary auth method configured, try ssh-agent first, then ALL default keys.
// Skip default-key primaries when the user explicitly chose a key (inline or
// identityFilePaths) even if loading that key failed (issue #1614).
if (!connectOpts.privateKey && !connectOpts.password && !connectOpts.agent) {
// First, try to use ssh-agent if available (this is what regular SSH does)
const sshAgentSocket = options.useSshAgent !== false
? await getAvailableAgentSocket()
: null;
if (sshAgentSocket) {
log("No auth method configured, trying ssh-agent first", { agentSocket: sshAgentSocket });
connectOpts.agent = sshAgentSocket;
}
// Mark that we need to try all default keys (handled in authMethods below)
if (!hasUserConfiguredKey(options) && allDefaultKeys.length > 0) {
log("Will try all default SSH keys as fallback", { count: allDefaultKeys.length, keyNames: allDefaultKeys.map(k => k.keyName) });
// Set first key for connectOpts.privateKey (required for ssh2 to allow publickey auth)
connectOpts.privateKey = allDefaultKeys[0].privateKey;
usedDefaultKeyAsPrimary = true;
} else if (allDefaultKeys.length === 0) {
log("No default SSH key found in ~/.ssh directory");
}
}
log("Final auth configuration", {
hasPrivateKey: !!connectOpts.privateKey,
hasPassword: !!connectOpts.password,
hasAgent: !!connectOpts.agent,
hasDefaultKeyFallback: !!defaultKeyInfo && !isPasswordOnlyAuth,
isPasswordOnlyAuth,
});
// ssh2 uses connectOpts.agent for forwarding, but authHandler agent
// objects may select a different agent for login.
const loginAgent = connectOpts.agent;
// Agent forwarding
if (options.agentForwarding) {
await applyAgentForwarding(options, connectOpts, getAvailableForwardingAgentSocket);
if (!connectOpts.agentForward) {
log("Agent forwarding requested but no agent available, skipping");
}
}
// Build authentication handler with fallback support
// ssh2 authHandler can be a function that returns the next auth method to try
// Check if we have a cached successful auth method for this host
const cachedMethod = getCachedAuthMethod(connectOpts.username, options.hostname, options.port);
// Track which method succeeded for caching
let lastTriedMethod = null;
// Shared with keyboard-interactive auto-fill. A completed password or
// keyboard-interactive factor suppresses reuse of the saved host
// password for a later KI factor (EDR step-up). publickey partialSuccess
// still allows Password: auto-fill.
const authPhase = createAuthPhase();
if (authAgent) {
const order = ["none", "agent"];
if (options.requiresMfa && !options._skipPasswordMethod) {
order.push("keyboard-interactive");
}
if (connectOpts.password && !options._skipPasswordMethod) {
order.push("password");
}
// Default key fallback only when this is not password-only (issue #266 / #2079).
// Must also set connectOpts.privateKey for ssh2 to actually try publickey auth.
if (defaultKeyInfo && !hasUserConfiguredKey(options) && !isPasswordOnlyAuth) {
connectOpts.privateKey = defaultKeyInfo.privateKey;
order.push("publickey");
}
if (!order.includes("keyboard-interactive")) order.push("keyboard-interactive");
// Function form so authPhase.hadPartialSuccess updates for cert/agent
// first-factor + keyboard-interactive second-factor (#2150).
connectOpts.authHandler = createOrderedStringAuthHandler(
order,
authPhase,
undefined,
authAgent !== connectOpts.agent
? { username: connectOpts.username, agent: authAgent }
: undefined,
);
connectOpts._shouldRetryKeyboardInteractiveFirst = () => Boolean(authPhase.retryKeyboardInteractiveFirst);
log("Auth order (agent mode)", { order, skipPasswordMethod: !!options._skipPasswordMethod });
} else {
// Build dynamic auth handler for fallback support
const authMethods = [];
if (isAutomaticAuth) {
if (options.requiresMfa && !connectOpts.password && !options._skipPasswordMethod) {
authMethods.push({ type: "keyboard-interactive", id: "keyboard-interactive" });
}
if (shouldOfferAgentForLogin(options, { agent: loginAgent })) {
authMethods.push({ type: "agent", agent: loginAgent, id: "agent" });
}
if (connectOpts.privateKey && !usedDefaultKeyAsPrimary) {
authMethods.push({ type: "publickey", key: connectOpts.privateKey, passphrase: connectOpts.passphrase, id: "publickey-user" });
}
for (const keyInfo of allDefaultKeys) {
authMethods.push({
type: "publickey",
key: keyInfo.privateKey,
isDefault: true,
id: `publickey-default-${keyInfo.keyName}`
});
}
if (options.requiresMfa && connectOpts.password && !options._skipPasswordMethod) {
authMethods.push({ type: "keyboard-interactive", id: "keyboard-interactive" });
}
if (connectOpts.password && !options._skipPasswordMethod) {
authMethods.push({ type: "password", id: "password" });
}
} else {
// First try user-configured key if available (explicit user choice)
if (connectOpts.privateKey && !usedDefaultKeyAsPrimary) {
authMethods.push({ type: "publickey", key: connectOpts.privateKey, passphrase: connectOpts.passphrase, id: "publickey-user" });
}
// Then try agent if configured (try agent before password since it's usually faster)
if (shouldOfferAgentForLogin(options, { agent: loginAgent })) {
authMethods.push({ type: "agent", agent: loginAgent, id: "agent" });
}
// MFA/PAM hosts can reject the SSH "password" method while accepting
// the login password through keyboard-interactive.
if (options.requiresMfa && !options._skipPasswordMethod) {
authMethods.push({ type: "keyboard-interactive", id: "keyboard-interactive" });
}
// Then try password if available (explicit user choice).
if (connectOpts.password && !options._skipPasswordMethod) {
authMethods.push({ type: "password", id: "password" });
}
// Then try ALL default SSH keys as fallback (not just the first one!)
// Password-only hosts skip automatic default-key probing so terminal/SFTP/jump agree.
if (!isPasswordOnlyAuth && usedDefaultKeyAsPrimary && allDefaultKeys.length > 0) {
for (const keyInfo of allDefaultKeys) {
authMethods.push({
type: "publickey",
key: keyInfo.privateKey,
isDefault: true,
id: `publickey-default-${keyInfo.keyName}`
});
}
} else if (!isSelectedKeyAuth && defaultKeyInfo && !hasUserConfiguredKey(options) && !usedDefaultKeyAsPrimary) {
// Single default key fallback (when user has configured other non-password auth)
authMethods.push({ type: "publickey", key: defaultKeyInfo.privateKey, isDefault: true, id: "publickey-default" });
}
}
// Unlocked default keys remain eligible only for automatic and
// legacy fallback modes. Explicit modes must not probe unrelated keys.
for (const keyInfo of unlockedEncryptedKeys) {
authMethods.push({
type: "publickey",
key: keyInfo.privateKey,
passphrase: keyInfo.passphrase,
isDefault: true,
id: `publickey-encrypted-${keyInfo.keyName}`
});
}
// Keyboard-interactive as last resort, or already placed before password
// as last-resort fallback for multi-factor / EDR.
if (!authMethods.some((method) => method.type === "keyboard-interactive")) {
authMethods.push({ type: "keyboard-interactive", id: "keyboard-interactive" });
}
log("Auth methods configured", {
methods: authMethods.map(m => ({ type: m.type, id: m.id, isDefault: m.isDefault || false })),
cachedMethod,
usedDefaultKeyAsPrimary
});
// Reorder methods based on cached successful method
if (shouldPromoteCachedAuthMethod(options.authMethod, cachedMethod)) {
const cachedIndex = authMethods.findIndex(m => m.id === cachedMethod);
if (cachedIndex > 0) {
const [cachedAuthMethod] = authMethods.splice(cachedIndex, 1);
authMethods.unshift(cachedAuthMethod);
log("Reordered auth methods based on cache", {
methods: authMethods.map(m => m.id)
});
}
}
// Always use dynamic authHandler to ensure consistent "none" probing
// and auth method logging regardless of how many methods are configured
if (authMethods.length >= 1) {
// Track methods that have been attempted (to avoid re-trying on failure)
// This prevents reusing the same key when server requires multiple publickey auth steps
// and also prevents re-attempting failed methods
let attemptedMethodIds = new Set();
// Methods that contributed a successful factor; never retried.
const succeededMethodIds = new Set();
// Methods actually rejected by the server. Keep these blocked when
// a later factor makes previously unavailable methods eligible.
const failedMethodIds = new Set();
// Track the first successful method for caching (not the last one in multi-step flows)
let firstSuccessfulMethod = null;
// Track if we've gone through a partialSuccess flow (multi-step auth)
let hadPartialSuccess = false;
// Some EDR servers advertise keyboard-interactive next to password,
// then remove it after a rejected password request. The wrapper can
// recover by retrying once with the password method omitted so the
// login password flows through keyboard-interactive.
let passwordAttemptSawKeyboardInteractive = false;
let shouldRetryKeyboardInteractiveFirst = false;
connectOpts.authHandler = (methodsLeft, partialSuccess, callback) => {
log("authHandler called", { methodsLeft, partialSuccess, attemptedMethodIds: Array.from(attemptedMethodIds) });
// Log rejection of previous method
if (lastTriedMethod && !partialSuccess) {
sendProgress(totalHops, totalHops, options.hostname, 'auth-attempt', `${lastTriedMethod} rejected`);
if (
lastTriedMethod === "password" &&
passwordAttemptSawKeyboardInteractive &&
Array.isArray(methodsLeft) &&
!methodsLeft.includes("keyboard-interactive")
) {
shouldRetryKeyboardInteractiveFirst = true;
log("password rejection removed keyboard-interactive; scheduling KI-first retry", {
methodsLeft,
});
}
if (lastTriedMethod !== "none") {
failedMethodIds.add(lastTriedMethod);
}
}
// On the very first call (methodsLeft === null), try "none" auth.
// Per RFC 4252, the "none" request is how the client discovers which
// methods the server supports. It also allows passwordless login on
// embedded devices. This matches the behavior of OpenSSH and Tabby.
if (methodsLeft === null && !attemptedMethodIds.has("none")) {
attemptedMethodIds.add("none");
lastTriedMethod = "none";
sendProgress(totalHops, totalHops, options.hostname, 'auth-attempt', 'none (no credentials)');
return callback("none");
}
// methodsLeft can be null on first call (before server responds with available methods)
// Include "agent" for SSH agent-based auth (used with agentForwarding)
const availableMethods = methodsLeft || ["publickey", "password", "keyboard-interactive", "agent"];
// Handle partialSuccess case (e.g., password succeeded but server requires additional auth like MFA)
// When partialSuccess is true, we should try the remaining methods the server is asking for
if (partialSuccess && methodsLeft && methodsLeft.length > 0) {
hadPartialSuccess = true;
// password method id is "password"; key ids start with publickey-
const succeededType =
lastTriedMethod === "password"
? "password"
: lastTriedMethod === "agent"
? "agent"
: lastTriedMethod === "keyboard-interactive"
? "keyboard-interactive"
: "publickey";
markAuthPhasePartialSuccess(authPhase, succeededType);
// Record the first successful method (the one that triggered partialSuccess)
if (lastTriedMethod && !firstSuccessfulMethod) {
firstSuccessfulMethod = lastTriedMethod;
log("Recorded first successful method for caching", { method: firstSuccessfulMethod });
}
// Reconsider methods that were unavailable in the previous
// factor, but preserve credentials already rejected or used.
if (lastTriedMethod) {
succeededMethodIds.add(lastTriedMethod);
log("Recorded successful auth factor (partial success)", { method: lastTriedMethod });
}
attemptedMethodIds = new Set([...failedMethodIds, ...succeededMethodIds]);
// PAM/EDR can require two consecutive keyboard-interactive
// factors (login password, then a separate secondary password).
// A partial-success response explicitly advertising KI again is
// permission to repeat that method with a fresh server prompt.
// Keep keys/passwords de-duplicated, but do not suppress this
// second interactive factor (#2150).
if (
methodsLeft.includes("keyboard-interactive") &&
canRepeatKeyboardInteractive(authPhase, failedMethodIds)
) {
attemptedMethodIds.delete("keyboard-interactive");
}
log("Partial success - server requires additional auth", { methodsLeft, succeeded: Array.from(succeededMethodIds), attemptedMethodIds: Array.from(attemptedMethodIds) });
// Next-factor selection: prefer keyboard-interactive when the
// server still allows it (automatic KI fallback after any
// partial success). Otherwise walk authMethods in order.
const partialCandidates = [];
for (const matchingMethod of authMethods) {
if (attemptedMethodIds.has(matchingMethod.id)) continue;
const serverMethod =
matchingMethod.type === "agent" || matchingMethod.type === "publickey"
? "publickey"
: matchingMethod.type;
if (!methodsLeft.includes(serverMethod) && !methodsLeft.includes(matchingMethod.type)) {
continue;
}
partialCandidates.push(matchingMethod);
}
const preferredPartial =
partialCandidates.find((method) => method.type === "keyboard-interactive")
|| partialCandidates[0];
if (preferredPartial) {
const matchingMethod = preferredPartial;
const serverMethod =
matchingMethod.type === "agent" || matchingMethod.type === "publickey"
? "publickey"
: matchingMethod.type;
log("Found matching method for partial success", { serverMethod, matchingMethod: matchingMethod.id });
attemptedMethodIds.add(matchingMethod.id);
lastTriedMethod = matchingMethod.id;
if (matchingMethod.type === "keyboard-interactive") {
log("Trying keyboard-interactive auth (partial success)", { id: matchingMethod.id });
return callback("keyboard-interactive");
} else if (matchingMethod.type === "password") {
log("Trying password auth (partial success)", { id: matchingMethod.id });
return callback({
type: "password",
username: connectOpts.username,
password: connectOpts.password,
});
} else if (matchingMethod.type === "agent") {
const agentType = typeof matchingMethod.agent === "string" ? "path" : "NetcattyAgent";
log("Trying agent auth (partial success)", { id: matchingMethod.id, agentType });
return matchingMethod.agent === connectOpts.agent
? callback("agent")
: callback({
type: "agent",
username: connectOpts.username,
agent: matchingMethod.agent,
});
} else if (matchingMethod.type === "publickey") {
log("Trying publickey auth (partial success)", { id: matchingMethod.id });
return callback({
type: "publickey",
username: connectOpts.username,
key: matchingMethod.key,
passphrase: matchingMethod.passphrase,
});
}
}
// No matching method found for partial success
log("No matching method found for partial success requirements", { methodsLeft });
return callback(false);
}
for (const method of authMethods) {
// Skip methods that have already been attempted (e.g., during partial success handling)
if (attemptedMethodIds.has(method.id)) {
log("Skipping already attempted method", { method: method.id });
continue;
}
// Check if this method is still available on server
// Note: "agent" uses "publickey" as the underlying method type
const methodName = method.type === "password" ? "password" :
method.type === "publickey" ? "publickey" :
method.type === "agent" ? "publickey" : "keyboard-interactive";
if (!availableMethods.includes(methodName) && !availableMethods.includes(method.type)) {
log("Auth method not available on server, skipping", { method: method.id });
continue;
}
// Mark as attempted BEFORE returning
attemptedMethodIds.add(method.id);
lastTriedMethod = method.id;
if (method.type === "agent") {
// Only log safe identifier, not the full agent object which may contain private keys
const agentType = typeof method.agent === "string" ? "path" : "NetcattyAgent";
log("Trying agent auth", { id: method.id, agentType });
sendProgress(totalHops, totalHops, options.hostname, 'auth-attempt', 'SSH agent');
return method.agent === connectOpts.agent
? callback("agent")
: callback({
type: "agent",
username: connectOpts.username,
agent: method.agent,
});
} else if (method.type === "publickey") {
log("Trying publickey auth", { id: method.id, isDefault: method.isDefault || false });
const keyLabel = method.id.startsWith("publickey-default-")
? `key ${method.id.replace("publickey-default-", "")}`
: method.id.startsWith("publickey-encrypted-")
? `key ${method.id.replace("publickey-encrypted-", "")} (encrypted)`
: method.id === "publickey-user"
? "configured key"
: method.id;
sendProgress(totalHops, totalHops, options.hostname, 'auth-attempt', keyLabel);
return callback({
type: "publickey",
username: connectOpts.username,
key: method.key,
passphrase: method.passphrase,
});
} else if (method.type === "password") {
log("Trying password auth", { id: method.id });
sendProgress(totalHops, totalHops, options.hostname, 'auth-attempt', 'password');
passwordAttemptSawKeyboardInteractive = availableMethods.includes("keyboard-interactive");
return callback({
type: "password",
username: connectOpts.username,
password: connectOpts.password,
});
} else if (method.type === "keyboard-interactive") {
log("Trying keyboard-interactive auth", { id: method.id });
sendProgress(totalHops, totalHops, options.hostname, 'auth-attempt', 'keyboard-interactive');
// Return string instead of object - ssh2 requires a prompt function
// for keyboard-interactive objects. Returning the string lets ssh2
// use its default handling and trigger the keyboard-interactive event.
return callback("keyboard-interactive");
}
}
log("All auth methods exhausted");
sendProgress(totalHops, totalHops, options.hostname, 'auth-attempt', 'all methods exhausted');
return callback(false);
};
// Store method reference for success callback
// For multi-step auth (partialSuccess), cache the first successful method, not the last
// This ensures next connection starts with the correct first factor
connectOpts._lastTriedMethodRef = () => {
if (hadPartialSuccess && firstSuccessfulMethod) {
log("Using first successful method for cache (multi-step auth)", { firstSuccessfulMethod });
return firstSuccessfulMethod;
}
return lastTriedMethod;
};
connectOpts._shouldRetryKeyboardInteractiveFirst = () => shouldRetryKeyboardInteractiveFirst;
}
}
// Handle chain/proxy connections
if (hasJumpHosts) {
// Pass fetched keys to chain connection to avoid re-reading files
options._defaultKeys = discoveredDefaultKeys;
options._sshDiagnosticLogger = log;
if (testTransport) {
options._tunnelRef = testTransport;
options._connectionsRef = testTransport.chainConnections;
}
if (testMode) {
// A test has no terminal session in the renderer's session list, so
// jump-host keyboard-interactive/MFA prompts must use the external
// scope (same as the target host below); the terminal scope default
// in connectThroughChain would be rejected by the renderer queue.
options._keyboardInteractiveScope = "external";
}
const chainResult = await connectThroughChain(
event,
options,
jumpHosts,
options.hostname,
options.port || 22,
sessionId,
recordAcceptedHostKey
);
connectionSocket = chainResult.socket;
chainConnections = chainResult.connections;
connectOpts.sock = connectionSocket;
delete connectOpts.host;
delete connectOpts.port;
sendProgress(totalHops, totalHops, options.hostname, 'connecting');
} else if (hasProxy) {
sendProgress(1, 1, options.hostname, 'connecting');
connectionSocket = await createProxySocket(
options.proxy,
options.hostname,
options.port || 22,
{
timeoutMs: tcpConnectTimeoutMs,
...(testTransport
? { onSocket: (socket) => { testTransport.pendingConn = socket; } }
: {}),
}
);
connectOpts.sock = connectionSocket;
delete connectOpts.host;
delete connectOpts.port;
if (testTransport) {
testTransport.socket = connectionSocket;
testTransport.pendingConn = null;
}
} else {
// Direct connection (no jump hosts, no proxy)
sendProgress(1, 1, options.hostname, 'connecting');
}
return new Promise((resolve, reject) => {
const logPrefix = hasJumpHosts ? '[Chain]' : '[SSH]';
let settled = false;
const connectionStartedAt = Date.now();
let connectionStage = "connecting";
let authBanner = "";
let detachX11Forwarding = null;
// Reference-counted descriptor for this connection. Created when the
// shell channel opens; shared with any tabs that later reuse this
// connection (issue #1204). Tearing the transport down is funneled
// through releaseConnectionRef so the last channel — not whichever
// channel happens to close first — ends the connection + chain.
let connRef = null;
let authReadyTimer = null;
const clearAuthReadyTimer = () => {
if (authReadyTimer) {
clearTimeout(authReadyTimer);
authReadyTimer = null;
}
};
// Session-log stream token for THIS connection's owner channel,
// captured in the closure so the connection-level error/timeout/close
// handlers stop only this connection's stream. Reading it back off the
// session map would risk stopping a *newer* same-sessionId stream
// after a reconnect (the token guard from #916). Stays null until the
// owner shell opens.
let ownerLogStreamToken = null;
// End the shared transport directly when we fail *before* a session
// (and its connRef) exists; once connRef exists, teardown goes through
// releaseConnectionRef via the stream close handler instead.
const teardownTransport = () => {
if (connRef) return;
try { conn.end(); } catch { }
for (const c of chainConnections) {
try { c.end(); } catch { }
}
};
conn.once("connect", () => {
runWhenProxyConnectionReady(conn._sock, () => {
try { conn._sock?.setTimeout?.(0); } catch { }
clearAuthReadyTimer();
connectionStage = "tcp-connected";
authReadyTimer = setTimeout(() => conn.emit("timeout"), authReadyTimeoutMs);
authReadyTimer.unref?.();
log("target tcp connected", {
sessionId,
hostname: options.hostname,
elapsedMs: Date.now() - connectionStartedAt,
authReadyTimeoutMs,
});
sendProgress(totalHops, totalHops, options.hostname, 'tcp-connected');
enableSshNoDelay(conn);
});
});
if (connectOpts.sock) enableTcpNoDelay(connectOpts.sock);
conn.once("handshake", () => {
connectionStage = "handshake";
console.log(`${logPrefix} ${options.hostname} handshake complete`);
log("target handshake complete", {
sessionId,
hostname: options.hostname,
elapsedMs: Date.now() - connectionStartedAt,
});
sendProgress(totalHops, totalHops, options.hostname, 'authenticating');
});
conn.on("banner", (message) => {
authBanner = String(message || "").trim();
log("auth banner received", {
sessionId,
hostname: options.hostname,
length: authBanner.length,
});
});
conn.once("ready", () => {
clearAuthReadyTimer();
connectionStage = "ready";
console.log(`${logPrefix} ${options.hostname} ready`);
log("target ready", {
sessionId,
hostname: options.hostname,
elapsedMs: Date.now() - connectionStartedAt,
remoteSshVersion: (conn && typeof conn._remoteVer === 'string') ? conn._remoteVer : '',
});
// Cache the successful auth method
if (connectOpts._lastTriedMethodRef) {
const successMethod = connectOpts._lastTriedMethodRef();
if (successMethod) {
setCachedAuthMethod(connectOpts.username, options.hostname, options.port, successMethod);
}
}
sendProgress(totalHops, totalHops, options.hostname, 'authenticated');
if (testMode) {
// Headless connection test: authentication succeeded. Report the
// outcome and tear down without opening a shell channel. The
// auth-method cache write above is intentionally kept so a
// successful test warms the same cache a real connection uses.
clearAuthReadyTimer();
if (monitorMode) {
const { createTransport } = require("../sshConnectionPool.cjs");
connRef = createTransport({ conn, chainConnections, endpoint: reuseEndpoint });
unregisterTestConnectionTransport(sessionId);
settled = true;
resolve({ transport: connRef });
return;
}
sendConnectionTestResult(sender, sessionId, true);
settled = true;
try { conn.end(); } catch { /* ignore */ }
for (const c of chainConnections) {
try { c.end(); } catch { /* ignore */ }
}
resolve({ sessionId, testResult: "connected" });
return;
}
sendProgress(totalHops, totalHops, options.hostname, 'shell');
let establishedOwnerSession = null;
const sendTerminalMessage = (data) => {
const current = sessions.get(sessionId);
if (establishedOwnerSession && current !== establishedOwnerSession) return;
emitTerminalSessionData(event.sender, sessionId, data, {
...(establishedOwnerSession ? { session: establishedOwnerSession } : {}),
cols: current?.cols,
rows: current?.rows,
});
};
const x11FakeCookie = options.x11Forwarding
? crypto.randomBytes(16).toString("hex")
: null;
if (options.x11Forwarding) {
detachX11Forwarding = attachX11Forwarding(conn, {
display: options.x11Display,
fakeCookie: x11FakeCookie,
sendMessage: sendTerminalMessage,
});
}
const shellSessionOptions = optionsForPeerSingleChannel(options, conn);
const shellOptions = buildInteractiveShellOptions(shellSessionOptions);
if (shellSessionOptions.singleChannelSsh) {
log("skipping shell env for single-channel SSH", {
sessionId,
hostname: options.hostname,
});
}
if (options.x11Forwarding) {
shellOptions.x11 = {
protocol: "MIT-MAGIC-COOKIE-1",
cookie: x11FakeCookie,
screen: 0,
single: false,
};
}
openBoundedSshShellCallback(
conn,
{
term: "xterm-256color",
cols,
rows,
},
shellOptions,
(err, stream) => {
if (err) {
log("shell open failed", { sessionId, hostname: options.hostname, error: err.message });
if (detachX11Forwarding) detachX11Forwarding();
settled = true;
conn.end();
for (const c of chainConnections) {
try { c.end(); } catch { }
}
if (options.x11Forwarding && /x11/i.test(err.message || "")) {
sendTerminalMessage("\r\n[X11] Could not enable X11 forwarding. Make sure X11 forwarding is allowed on the server and xauth is installed.\r\n");
}
sendProgress(totalHops, totalHops, options.hostname, 'error', `Failed to open shell: ${err.message}`);
reject(err);
return;
}
sendProgress(totalHops, totalHops, options.hostname, 'connected');
// Create the shared reference-counted descriptor for this
// connection now that the owning channel is open, then wire the
// shell up through the shared helper.
let ownerSession;
try {
ownerSession = setupShellSession({
conn,
stream,
options: {
...shellSessionOptions,
_actualAgentForwarding: Boolean(connectOpts.agentForward),
},
sessionId,
event,
log,
detachX11Forwarding,
chainConnections,
isReused: false,
acceptedHostKeys,
});
} catch (setupErr) {
// Callback runs from openBoundedSshShellCallback's Promise
// .then without a catch — reject the owning start Promise.
if (detachX11Forwarding) {
try { detachX11Forwarding(); } catch { /* ignore */ }
}
settled = true;
reject(setupErr);
return;
}
establishedOwnerSession = ownerSession;
connRef = createConnectionRef(ownerSession, conn, chainConnections);
if (pendingDialCoordination) {
completeTransportDial(pendingDialCoordination, connRef);
}
// Capture this connection's log stream token in the closure so
// the connection-level handlers below stop the right stream even
// after a same-sessionId reconnect (#916).
ownerLogStreamToken = ownerSession._logStreamToken;
settled = true;
resolve({ sessionId });
}
);
});
conn.on("error", (err) => {
// ssh2 reports agent failures before trying the next auth method.
// Keep the connection and its authentication deadline alive.
if (err.level === "agent" && err.code !== "ERR_FIDO_CANCELLED") {
log("non-fatal agent auth error (will try next method)", {
sessionId,
hostname: options.hostname,
error: err.message,
});
return;
}
clearAuthReadyTimer();
// After the promise is settled, we can't reject again. But if the
// session was already established (resolved), we still need to notify
// the renderer about transport errors so the session shows as failed
// rather than silently closing.
// Don't send netcatty:exit here — the stream close handler will flush
// any buffered data first and then send exit with this error info.
if (settled) {
console.warn(`${logPrefix} ${options.hostname} post-settle error:`, err.message);
log("post-connect transport error", {
sessionId,
hostname: options.hostname,
error: err.message,
code: err.code,
level: err.level,
});
// Store the error so the close handler can include it in the exit event.
// ssh2 closes every channel when the transport errors, so each
// affected session (the owner and any reused siblings) gets the
// flag and reports the error via its own stream close handler.
const currentSession = sessions.get(sessionId);
const ownsCurrentSession = Boolean(connRef && currentSession?.connRef === connRef);
if (ownsCurrentSession) {
currentSession._transportError = err.message;
}
if (connRef) {
for (const sibling of sessions.values()) {
if (sibling !== currentSession && sibling.connRef === connRef) {
sibling._transportError = err.message;
}
}
}
return;
}
const contents = event.sender;
const isAuthError = isSshAuthFailure(err);
// Clear cached auth method on auth failure so next attempt tries all methods
if (isAuthError) {
if (
!options._skipPasswordMethod &&
connectOpts.password &&
connectOpts._shouldRetryKeyboardInteractiveFirst?.()
) {
err.retryKeyboardInteractiveFirst = true;
log("auth failure marked for KI-first retry", {
sessionId,
hostname: options.hostname,
});
}
clearCachedAuthMethod(connectOpts.username, options.hostname, options.port);
console.log(`${logPrefix} ${options.hostname} auth failed:`, err.message);
log("authentication failed", {
sessionId,
hostname: options.hostname,
error: err.message,
code: err.code,
level: err.level,
});
safeSend(contents, "netcatty:auth:failed", {
sessionId,
error: err.message,
hostname: options.hostname
});
} else {
console.error(`${logPrefix} ${options.hostname} error:`, err.message);
log("connection error", {
sessionId,
hostname: options.hostname,
error: err.message,
code: err.code,
level: err.level,
});
}
const visibleError = userVisibleSshErrorMessage(err, options);
sendProgress(totalHops, totalHops, options.hostname, 'error', visibleError);
const suppressPreShellAuthExit = Boolean(options._suppressPreShellAuthExit && isAuthError);
if (suppressPreShellAuthExit) {
log("suppressing pre-shell auth exit for wrapper-managed retry", {
sessionId,
hostname: options.hostname,
});
} else {
safeSendSessionExit({ safeSend, electronModule, sessions }, contents, sessionId, { sessionId, exitCode: 1, error: visibleError, reason: "error" });
}
sessionLogStreamManager.stopStream(sessionId, ownerLogStreamToken);
if (detachX11Forwarding) {
detachX11Forwarding();
detachX11Forwarding = null;
}
sessions.get(sessionId)?.zmodemSentry?.cancel();
closeTerminalOutputSession?.(sessionId);
sessions.delete(sessionId);
sessionEncodings.delete(sessionId);
sessionDecoders.delete(sessionId);
teardownTransport();
// Destroy the connection to prevent further socket errors from leaking
// as uncaught exceptions (e.g. ECONNRESET on embedded devices).
try { conn.destroy(); } catch { }
if (testMode && !monitorMode) {
sendConnectionTestResult(sender, sessionId, false, visibleError);
}
settled = true;
reject(err);
});
conn.once("timeout", () => {
clearAuthReadyTimer();
console.error(`${logPrefix} ${options.hostname} connection timeout`);
const err = new Error(`Connection timeout to ${options.hostname}`);
log("connection timeout", {
sessionId,
hostname: options.hostname,
error: err.message,
stage: connectionStage,
elapsedMs: Date.now() - connectionStartedAt,
tcpConnectTimeoutMs,
authReadyTimeoutMs,
});
const contents = event.sender;
sendProgress(totalHops, totalHops, options.hostname, 'error', err.message);
safeSendSessionExit({ safeSend, electronModule, sessions }, contents, sessionId, { sessionId, exitCode: 1, error: err.message, reason: "timeout" });
sessionLogStreamManager.stopStream(sessionId, ownerLogStreamToken);
sessions.get(sessionId)?.zmodemSentry?.cancel();
closeTerminalOutputSession?.(sessionId);
sessions.delete(sessionId);
sessionEncodings.delete(sessionId);
sessionDecoders.delete(sessionId);
teardownTransport();
try { conn.destroy(); } catch { }
if (testMode && !monitorMode) {
sendConnectionTestResult(sender, sessionId, false, err.message);
}
settled = true;
reject(err);
});
conn.once("close", () => {
clearAuthReadyTimer();
unregisterTestConnectionTransport(sessionId);
const contents = event.sender;
const currentSession = sessions.get(sessionId);
const ownsCurrentSession = Boolean(connRef && currentSession?.connRef === connRef);
log("connection closed", {
sessionId,
hostname: options.hostname,
settled,
staleForCurrentSession: Boolean(currentSession && !ownsCurrentSession),
transportError: ownsCurrentSession ? currentSession?._transportError : undefined,
});
if (!settled) {
sendProgress(totalHops, totalHops, options.hostname, 'error', `Connection to ${options.hostname} closed unexpectedly`);
}
// This handler owns teardown for the *owner* session only. ssh2
// fires conn "close" before the owner's stream "close" on a
// transport drop, so we clean the owner up here; the owner's stream
// close then no-ops because the session is already gone. Reused
// sibling channels each clean themselves up via their own stream
// "close" (ssh2 closes every channel when the transport drops).
if (ownsCurrentSession) {
const session = currentSession;
const transportError = session?._transportError;
if (transportError) {
// A transport error was recorded — report it as an error exit
safeSendSessionExit({ safeSend, electronModule, sessions }, contents, sessionId, {
sessionId,
exitCode: 1,
error: transportError,
reason: "error",
_terminalSessionGeneration: session?._terminalSessionGeneration,
});
} else if (normalizeRemoteExitSignal(session?._remoteExitSignal)) {
// The shell already reported an exit-signal. This connection
// close is the server finishing that administrative kick, not
// a transport flap — keep it out of the reconnect loop.
safeSendSessionExit({ safeSend, electronModule, sessions }, contents, sessionId, buildRemoteShellExitPayload({
sessionId,
generation: session?._terminalSessionGeneration,
exitSignal: session._remoteExitSignal,
shellExited: false,
idleTimedOut: false,
}));
} else {
// Preserve a shell status already received before transport
// close; otherwise do not invent a successful exit code.
const shellExited = typeof session?._remoteExitCode === "number";
safeSendSessionExit({ safeSend, electronModule, sessions }, contents, sessionId, buildRemoteShellExitPayload({
sessionId,
generation: session?._terminalSessionGeneration,
exitCode: session?._remoteExitCode,
shellExited,
idleTimedOut: shellExited && looksLikeIdleAutoLogout(session?._promptTrackTail),
}));
}
// Use this connection's captured token so a late close from an
// old transport can't stop a newer same-sessionId stream (#916).
sessionLogStreamManager.stopStream(sessionId, ownerLogStreamToken);
session?.zmodemSentry?.cancel();
// Release the owner's hold on the shared connection. The transport
// is already closing, but this decrements the reference count and,
// when it is the last holder, ends the jump-host chain. Reused
// siblings (if any) keep the count above zero until their own
// stream close handlers run.
releaseConnectionRef(session);
closeTerminalOutputSession?.(sessionId);
sessions.delete(sessionId);
sessionEncodings.delete(sessionId);
sessionDecoders.delete(sessionId);
} else {
// Owner already cleaned up (e.g. its stream closed first). Ensure
// this connection's log stream is stopped defensively, scoped by
// the captured token so a reconnect's fresh stream is left alone.
if (ownerLogStreamToken) {
sessionLogStreamManager.stopStream(sessionId, ownerLogStreamToken);
}
}
if (!settled) {
if (testMode && !monitorMode) {
sendConnectionTestResult(
sender,
sessionId,
false,
`Connection to ${options.hostname} closed unexpectedly`,
);
}
settled = true;
reject(new Error(`Connection to ${options.hostname} closed unexpectedly`));
}
});
// Handle keyboard-interactive authentication (2FA/MFA). Uses the shared
// factory so PAM-wrapped single-password prompts get auto-filled from
// the saved host password (#969) — same path the chain/SFTP/port-
// forwarding bridges go through.
conn.on("keyboard-interactive", createKeyboardInteractiveHandler({
sender,
sessionId,
hostId: options.hostId,
hostname: options.hostname,
password: options.password,
totp: options.totp,
logPrefix,
// A test has no terminal session registered in the renderer's
// session list, so the terminal-scoped keyboard-interactive queue
// would auto-reject the prompt. Use the external scope so the
// host-editor test dialog can still render password/2FA prompts.
scope: testMode ? "external" : "terminal",
allowSavePassword: !monitorMode,
bootEpoch: options.bootEpoch,
getAuthBanner: () => authBanner,
shouldSkipAutoFill: () => shouldSkipKiPasswordAutoFill(authPhase),
onAutoFill: (kind) => sendProgress(
totalHops, totalHops, options.hostname, 'auth-attempt',
kind === 'totp' ? 'using authenticator code' : 'using saved password',
),
onPromptShown: () => sendProgress(
totalHops, totalHops, options.hostname, 'auth-attempt', 'waiting for user input...',
),
onUserResponded: () => sendProgress(
totalHops, totalHops, options.hostname, 'auth-attempt', 'user responded',
),
}));
// Enable keyboard-interactive authentication in authHandler
// Note: If authHandler is a function (for fallback support), keyboard-interactive
// is already included in the auth methods list
if (Array.isArray(connectOpts.authHandler)) {
// Add keyboard-interactive after the existing methods
if (!connectOpts.authHandler.includes("keyboard-interactive")) {
connectOpts.authHandler.push("keyboard-interactive");
}
} else if (typeof connectOpts.authHandler !== "function") {
// Create authHandler with keyboard-interactive support
// This path is taken when usedDefaultKeyAsPrimary=true (only keyboard-interactive in authMethods)
// Using array format is more reliable - ssh2 uses connectOpts credentials directly
const authMethods = [];
// Try agent FIRST (this is what regular SSH does - it checks ssh-agent before key files)
if (loginAgent) authMethods.push("agent");
if (connectOpts.privateKey) authMethods.push("publickey");
if (connectOpts.password && !options._skipPasswordMethod) {
authMethods.push("password");
}
authMethods.push("keyboard-interactive");
const dedupedAuthMethods = Array.from(new Set(authMethods));
connectOpts.authHandler = createOrderedStringAuthHandler(
dedupedAuthMethods,
createAuthPhase(),
undefined,
loginAgent !== connectOpts.agent
? { username: connectOpts.username, agent: loginAgent }
: undefined,
);
log("Using simple array authHandler", {
authMethods: dedupedAuthMethods,
usedDefaultKeyAsPrimary,
});
}
// If authHandler is a function, it already handles keyboard-interactive
if (testMode && !monitorMode) {
// A connection test exercises the single configured credential,
// skipping the full agent / ~/.ssh key / method fallback chain.
// Password credentials still allow keyboard-interactive after
// "password" so PAM/2FA hosts (which reject the raw "password"
// method) are covered without re-prompting the user. Hosts marked
// `requiresMfa` and a configured TOTP secret always get
// keyboard-interactive, including key / certificate-only credentials
// where the server accepts the key as the first factor and then
// asks for an OTP (matching the terminal auth handler, which always
// appends keyboard-interactive).
const totpUri = typeof options.totp?.uri === "string" ? options.totp.uri : "";
const hasTotp = totpUri.length > 0 && !totpUri.startsWith("enc:v1:");
const order = [];
if (connectOpts.privateKey) {
order.push("publickey");
} else if (connectOpts.agent) {
order.push("agent");
}
if (connectOpts.password && !options.requiresMfa) {
order.push("password");
}
if (connectOpts.password || options.requiresMfa || hasTotp || order.length === 0) {
order.push("keyboard-interactive");
}
connectOpts.authHandler = order;
}
console.log(`${logPrefix} Connecting to ${options.hostname}...`);
log("connect options prepared", {
sessionId,
hostname: options.hostname,
port: options.port || 22,
hasSocket: !!connectOpts.sock,
hasProxy,
jumpHostCount: jumpHosts.length,
timeout: connectOpts.timeout,
readyTimeout: connectOpts.readyTimeout,
tryKeyboard: connectOpts.tryKeyboard,
hasPassword: !!connectOpts.password,
hasPrivateKey: !!connectOpts.privateKey,
hasAgent: !!connectOpts.agent,
authHandlerType: Array.isArray(connectOpts.authHandler) ? "array" : typeof connectOpts.authHandler,
authMethods: Array.isArray(connectOpts.authHandler)
? connectOpts.authHandler
: undefined,
});
conn.connect(connectOpts);
// The test transport was already registered before the dial; nothing
// to re-register here.
}).catch((err) => {
if (pendingDialCoordination && !options._deferPendingDialFailure) {
failTransportDial(pendingDialCoordination, err);
}
throw err;
});
} catch (err) {
if (pendingDialCoordination && !options._deferPendingDialFailure) {
failTransportDial(pendingDialCoordination, err);
}
console.error("[Chain] SSH chain connection error:", err.message);
const isAuthError = isSshAuthFailure(err);
const suppressPreShellAuthExit = Boolean(options._suppressPreShellAuthExit && isAuthError);
if (!suppressPreShellAuthExit) {
const contents = event.sender;
safeSendSessionExit(
{ safeSend, electronModule, sessions },
contents,
sessionId,
{ sessionId, exitCode: 1, error: userVisibleSshErrorMessage(err, options) },
);
}
if (testMode) {
unregisterTestConnectionTransport(sessionId);
sendConnectionTestResult(sender, sessionId, false, userVisibleSshErrorMessage(err, options));
}
throw err;
}
}
return { startSSHSession };
}
}
module.exports = {
SSH_AUTH_READY_TIMEOUT_MS,
SSH_TCP_CONNECT_TIMEOUT_MS,
createStartSessionApi,
resolveSshConnectionTimeouts,
shouldOfferAgentForLogin,
shouldPrepareSystemAgentForLogin,
resolveUnlockedEncryptedKeysForAuth,
shouldPromoteCachedAuthMethod,
applyAgentForwarding,
prepareAgentForwardingOptions,
sendConnectionTestResult,
cancelTestConnection,
};