"use strict"; /** * Shared SSH connection pool helpers. * * Background (issue #1204): "Copy Tab" on an MFA-protected host used to open a * brand-new SSH connection, forcing the user through a second MFA prompt. Like * Tabby's session-multiplexing, we instead open an additional shell *channel* * on the already-authenticated connection. The SSH protocol natively supports * many session channels over one transport, so no re-authentication is needed. * * Multiplexing means several terminal sessions can share one ssh2 `Client` * (`conn`) and one underlying jump-host chain. The transport must only be torn * down once the *last* of those sessions goes away — closing a single channel * (or even the channel of the session that originally opened the connection) * must not kill the siblings. We model that with a small reference-counted * descriptor shared by every session on the same connection, mirroring Tabby's * ref()/unref()/destroy() lifecycle. * * The same `sessions` Map is shared by sshBridge and terminalBridge (see * registerBridges.cjs), so the session objects — and the `connRef` descriptor * attached here — are visible to both. That lets terminalBridge's closeSession * and sshBridge's own connection event handlers funnel teardown through the * same release path. */ /** * Attach a fresh reference-counted connection descriptor to the session that * established the connection. Called once, for the "owner" session, right after * its shell channel opens. * * @param {object} session - the owner session object stored in the sessions Map * @param {object} conn - the ssh2 Client for the established connection * @param {Array} chainConnections - jump-host connections that must be ended * together with the transport (owned by the connection, not any one channel) * @returns {{ count: number, conn: object, chainConnections: Array }} descriptor */ function createConnectionRef(session, conn, chainConnections) { const connRef = { count: 1, conn, chainConnections: Array.isArray(chainConnections) ? chainConnections : [], }; session.connRef = connRef; return connRef; } /** * Register an additional session (a reused channel) against an existing * connection descriptor, incrementing its reference count. * * @param {object} session - the new session sharing the connection * @param {{ count: number }} connRef - descriptor from createConnectionRef */ function acquireConnectionRef(session, connRef) { if (!connRef) return; connRef.count += 1; session.connRef = connRef; } /** * Release this session's hold on its shared connection. * * Decrements the reference count. When it reaches zero (the last channel is * gone) the underlying transport and any jump-host chain connections are torn * down. The caller remains responsible for closing this session's own shell * stream/channel; this only governs the *shared* transport. * * Safe to call multiple times for the same session — the descriptor is detached * after the first release so a later duplicate call is a no-op (important * because both a stream "close" event and an explicit closeSession can fire). * * @param {object} session - the session being torn down * @returns {boolean} true if the shared transport was ended by this call */ function releaseConnectionRef(session) { const connRef = session && session.connRef; if (!connRef) return false; // Detach immediately so re-entrant / duplicate releases for the same session // cannot double-decrement the shared counter. session.connRef = null; connRef.count -= 1; if (connRef.count > 0) { return false; } try { connRef.conn?.end(); } catch { /* connection may already be gone */ } for (const c of connRef.chainConnections) { try { c?.end(); } catch { /* ignore */ } } // Drop references so the descriptor doesn't pin connections after teardown. connRef.chainConnections = []; connRef.conn = null; return true; } /** * Find a live, fully-connected session whose authenticated SSH connection can * host an additional shell channel. Used to satisfy a reuse request from a * duplicated tab. * * Returns null when the source session is gone, has no usable connection, is * not an interactive SSH shell session (e.g. SFTP-only or local sessions), or * authenticated to a *different* target than the one now requested, so the * caller can safely fall back to establishing a fresh connection. * * The target check matters because a saved host can be edited after the source * tab connected; the duplicate would then carry the new hostname/port/username * while the source connection still points at the old machine. Reusing it would * silently run commands on the wrong host, so we require an exact endpoint match. * * @param {Map} sessions - the shared sessions Map * @param {string} sourceSessionId - id of the session to reuse * @param {{ hostname: string, port?: number, username?: string }} [requestedTarget] * the endpoint the duplicate wants to connect to; when provided, the source's * recorded endpoint must match it * @returns {object|null} the reusable source session, or null */ function findReusableSession(sessions, sourceSessionId, requestedTarget) { if (!sessions || !sourceSessionId) return null; const source = sessions.get(sourceSessionId); if (!source) return null; // Must be an interactive SSH shell session with a connection we own a // reference to. `stream` + `connRef` are only set for shell sessions started // through startSession.cjs; SFTP/exec-only or local/telnet/serial sessions // won't have both, so they're skipped. if (!source.conn || !source.stream || !source.connRef) return null; // ssh2 Client exposes no public "is connected" flag; rely on the descriptor // still being attached (it is nulled out on teardown) plus a non-destroyed // underlying socket when ssh2 exposes one. const sock = source.conn._sock; if (sock && sock.destroyed) return null; if (requestedTarget) { const ep = source._reuseEndpoint; // No recorded endpoint -> can't prove it's the same target, so don't reuse. if (!ep) return null; const sameHost = ep.hostname === (requestedTarget.hostname || ''); const samePort = (ep.port || 22) === (requestedTarget.port || 22); const sameUser = (ep.username || 'root') === (requestedTarget.username || 'root'); if (!sameHost || !samePort || !sameUser) return null; } return source; } module.exports = { createConnectionRef, acquireConnectionRef, releaseConnectionRef, findReusableSession, };