Implement OpenSSH-style ProxyJump transport

[KaliszAd]

ProxyJump: reach hosts behind a bastion the way ssh -J does

This adds OpenSSH-compatible ProxyJump to JSch. The typical setup it is
written for: an internal network where only the bastion's SSH port is
reachable, and everything behind it is a pinhole away. With this change a
JSch application reaches those hosts with the same ssh_config an
administrator already uses with OpenSSH, and no code changes beyond
loading that config.

Host bastion
  HostName bastion.example.org
  User jump
  IdentityFile ~/.ssh/bastion_ed25519

Host db-1
  HostName 10.0.0.5
  User dba
  ProxyJump bastion

JSch jsch = new JSch();
jsch.setConfigRepository(OpenSSHConfig.parseFile("~/.ssh/config"));
Session session = jsch.getSession("db-1");   // routed through bastion
session.connect();

What is supported

• ProxyJump host, user@host:port, comma-separated chains
  (ProxyJump a,b,c), the ssh://user@host:port form including bracketed
  IPv6, and ProxyJump none.
• Each hop is an ordinary Session built from its own Host block, so a
  hop's HostName, User, IdentityFile, UserKnownHostsFile,
  StrictHostKeyChecking and ConnectTimeout all apply. As with ssh -J,
  only the first hop honours a ProxyJump of its own; later hops are
  reached through the previous one.
• Each hop carries the next connection in a direct-tcpip channel with a
  2 MiB window. Data passes through a bounded buffer owned by the proxy,
  not through a PipedInputStream, so read timeouts, EOF and back-pressure
  behave like a socket. SFTP through a hop runs at wire speed on a LAN.

Security properties

• Hop host keys are verified with the hop's own configuration. Host-key
  constraints an application sets explicitly on the target session (a
  HostKeyRepository, a stricter StrictHostKeyChecking, or
  server_host_key) are also applied to the hops, and a hop's own
  StrictHostKeyChecking is never weakened by the target's.
• Hops never receive the target's UserInfo or password. Prompts from a
  hop, for a bastion password or an unknown host key, go to a separate
  Session.setProxyJumpUserInfo(...) if the application sets one, and every
  prompt names the hop it is for. A stored password therefore cannot reach
  a bastion by accident.
• A password embedded in an ssh://user:password@host hop is rejected, and
  it is redacted in the error message.
• Configuration loops (a jumps via b, b via a) are detected by
  walking the config before any socket is opened, and the message names the
  loop. No thread-local or static state is involved.
• The whole chain shares one connect deadline, the largest ConnectTimeout
  on the path, so a silent hop cannot stretch the connect to the sum of all
  timeouts.

Programmatic use and hop sharing

• ProxyJump.through(Session hop) tunnels a session through a hop the
  application has connected itself; the hop stays open when the tunnelled
  session closes.
• ProxyJump.share(factory) returns a SharedHop that behaves like
  OpenSSH's ControlMaster without ControlPersist: the first session to
  connect opens the bastion, later sessions reuse it, the last one to
  disconnect closes it, and a later session opens a fresh one. close()
  shuts it at once. It is safe to use from several threads; the hop is
  connected outside the lock so close() never waits on a slow bastion.

ProxyJump.SharedHop bastion = ProxyJump.share(() -> jsch.getSession("bastion"));
Session a = jsch.getSession("dba", "10.0.0.5", 22);
a.setProxy(bastion.proxy());
Session b = jsch.getSession("dba", "10.0.0.6", 22);
b.setProxy(bastion.proxy());

Testing

• Unit tests cover parsing, loop detection, host-key policy propagation,
  credential isolation, the connect budget, the transport buffer
  (timeouts, EOF ordering, growth, a blocked writer released by close) and
  the shared hop's reference counting under concurrent use.
• ProxyJumpIT runs against the repository's sshd image with
  testcontainers: one- and two-hop chains from config, the shared hop
  opening and closing with its first and last session, and through().
• Beyond the repository: chains through OpenSSH 10.0 sshds, a Proxmox host
  as bastion in front of OpenSSH for Windows 9.5, a Windows host as a
  password-authenticated bastion, three-hop chains, 64 MB SFTP transfers
  through a hop, 20 concurrent sessions through one bastion, and soak runs
  of several hundred connects with no leaked threads, sockets or heap.
• The buffer and shared-hop concurrency had an independent adversarial
  review; its findings are folded into the last commits.

Notes for reviewers

• The earlier ThreadLocal for loop detection is gone, which addresses
  the concerns raised in the review threads.
• OpenSSH gives each hop its own ConnectTimeout; this implementation
  bounds the whole chain by the largest one. The Javadoc says so.
• Reconnecting the same Session object after disconnect() is not
  supported by JSch today; SharedHop therefore creates a fresh hop
  session when it reopens.
• Include and Match support for ssh_config is in a separate PR.
• Remaining SonarCloud hints ask for Java 16 instanceof patterns; the
  main code targets Java 8.

Development

• The initial implementation was heavily assisted by OpenAI ChatGPT 6.0 Sol with medium effort.
• Work continued using Anthropic Claude Opus 5.5 with medium effort and Fable 5.1 with high effort.
• Second opinions used mostly ChatGPT 6.0 Sol with high effort.

Followup PRs

• Support configuration Include
• Support tokens such as %d for the home directory in paths in the configuration

[norrisjeremy]

Doesn't using a ThreadLocal mean that a single thread can't open multiple independent JSch sessions that happen to go thru the same proxy host?
Or am I misunderstanding something?

[KaliszAd]

I am not super deep into the mechanics of Java, this is all ChatGPT 6.0-Sol/ medium assisted to scratch my itch and be able to use the library with epiccastle/bbssh or epiccastle/clojuressh for some configuration management work.

My understanding is the ThreadLocal tracks the destination alias target.org_host, not the jump host. Each connect() removes its entry in finally, so one thread can connect multiple sessions sequentially and keep them all open, including sessions using the same jump host.

The edge case is a nested, re-entrant connect() to the same destination alias before the first call returns. It's currently rejected as a possible ProxyJump cycle, even if the nested connection is independent.

[theit]

Be aware that with using ThreadLocals you potentially leak memory, especially when you don't cleanup correctly.

[norrisjeremy]

I don't think using a ThreadLocal is the correct mechanism to use for this.
As @theit points out it can be a memory leak.
Additionally, even if org_host tracks destination hosts, I think it would also prevent the same thread from opening multiple independent sessions to the same destination host.

[sonarqubecloud]

Quality Gate passed

Issues
4 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud