feat: 增强 starssh 的 agent forwarding 与 tcp/unix 转发能力

- 为 LoginInput 增加 ForwardSSHAgent 配置，并在 Exec/PTTY 会话创建时按需自动请求 agent forwarding - 新增 agent_forward 运行时，封装本地 ssh-agent 建连、转发注册、显式请求与 unavailable/denied 语义 - 自动 agent forwarding 改为 best-effort：本地 agent 不可用、转发被拒绝或初始化失败时不再打断会话创建 - 为 StarSSH 增加 closing 状态与 agent forwarder 生命周期回收，避免 Close 与会话创建并发时泄漏资源 - 扩展 ForwardRequest 为带网络归一化的转发模型，支持 tcp/tcp4/tcp6/unix 端点组合 - 新增本地/远端 tcp<->unix、unix<->unix 及 detached helper，补齐 streamlocal 场景下的常用 API - 将显式网络地址编码收口为 tcp4://、tcp6://、unix://，消除 tcp:22 一类值的解析歧义 - 为本地 unix listener 增加 stale socket 探测、复用与关闭清理，避免遗留 socket 导致重启失败 - 补充 agent forwarding、关闭竞态、remote unix forward、local unix forward、stale socket 复用与端点解析等回归测试
2026-04-26 20:27:10 +08:00
parent f20eb653ae
commit b29246a9c4
7 changed files with 1463 additions and 45 deletions
@@ -0,0 +1,151 @@
+package starssh
+
+import (
+	"errors"
+	"fmt"
+	"io"
+	"strings"
+	"time"
+
+	"golang.org/x/crypto/ssh"
+	sshagent "golang.org/x/crypto/ssh/agent"
+)
+
+var requestSSHAgentForwarding = func(session *ssh.Session) error {
+	return sshagent.RequestAgentForwarding(session)
+}
+
+var routeSSHAgentForwarding = func(client *ssh.Client, keyring sshagent.Agent) error {
+	return sshagent.ForwardToAgent(client, keyring)
+}
+
+var newSSHAgentForwarder = func(timeout time.Duration) (sshagent.Agent, io.Closer, error) {
+	conn, err := dialSSHAgent(timeout)
+	if err != nil {
+		return nil, nil, wrapSSHAgentForwardingUnavailable(err)
+	}
+	if conn == nil {
+		return nil, nil, wrapSSHAgentForwardingUnavailable(errors.New("empty agent connection"))
+	}
+	return sshagent.NewClient(conn), conn, nil
+}
+
+var errSSHAgentForwardingDenied = errors.New("ssh-agent forwarding request denied")
+var errSSHAgentForwardingUnavailable = errors.New("ssh-agent forwarding unavailable")
+
+func (s *StarSSH) RequestAgentForwarding(session *ssh.Session) error {
+	if s == nil {
+		return errors.New("ssh client is nil")
+	}
+	if session == nil {
+		return errors.New("ssh session is nil")
+	}
+	if err := s.ensureAgentForwarding(); err != nil {
+		return err
+	}
+	if err := requestSSHAgentForwarding(session); err != nil {
+		if isSSHAgentForwardingDeniedError(err) {
+			return fmt.Errorf("%w: %v", errSSHAgentForwardingDenied, err)
+		}
+		return err
+	}
+	return nil
+}
+
+func (s *StarSSH) maybeRequestAgentForwarding(session *ssh.Session) error {
+	if s == nil || !s.LoginInfo.ForwardSSHAgent {
+		return nil
+	}
+	err := s.RequestAgentForwarding(session)
+	if isSSHAgentForwardingDeniedError(err) || isSSHAgentForwardingUnavailableError(err) {
+		return nil
+	}
+	return err
+}
+
+func (s *StarSSH) ensureAgentForwarding() error {
+	if s == nil {
+		return errors.New("ssh client is nil")
+	}
+
+	s.agentForwardMu.Lock()
+	defer s.agentForwardMu.Unlock()
+
+	if s.agentForwarder != nil {
+		return nil
+	}
+
+	client, err := s.requireSSHClient()
+	if err != nil {
+		return err
+	}
+
+	keyring, closer, err := newSSHAgentForwarder(s.LoginInfo.Timeout)
+	if err != nil {
+		return wrapSSHAgentForwardingUnavailable(err)
+	}
+	if s.closing.Load() {
+		_ = closer.Close()
+		return errSSHClientClosing
+	}
+	if err := routeSSHAgentForwarding(client, keyring); err != nil {
+		_ = closer.Close()
+		return err
+	}
+	if !s.canAttachAgentForwarder(client) {
+		_ = closer.Close()
+		return errSSHClientClosing
+	}
+	s.agentForwarder = closer
+	return nil
+}
+
+func (s *StarSSH) takeAgentForwarder() io.Closer {
+	if s == nil {
+		return nil
+	}
+
+	s.agentForwardMu.Lock()
+	defer s.agentForwardMu.Unlock()
+
+	closer := s.agentForwarder
+	s.agentForwarder = nil
+	return closer
+}
+
+func isSSHAgentForwardingDeniedError(err error) bool {
+	if err == nil {
+		return false
+	}
+	if errors.Is(err, errSSHAgentForwardingDenied) {
+		return true
+	}
+	message := strings.ToLower(err.Error())
+	return strings.Contains(message, "forwarding request denied") ||
+		strings.Contains(message, "agent forwarding disabled")
+}
+
+func isSSHAgentForwardingUnavailableError(err error) bool {
+	if err == nil {
+		return false
+	}
+	if errors.Is(err, errSSHAgentForwardingUnavailable) {
+		return true
+	}
+	message := strings.ToLower(err.Error())
+	return strings.Contains(message, "ssh-agent forwarding unavailable") ||
+		strings.Contains(message, "ssh-agent unavailable")
+}
+
+func wrapSSHAgentForwardingUnavailable(err error) error {
+	if err == nil {
+		return nil
+	}
+	if errors.Is(err, errSSHAgentForwardingUnavailable) {
+		return err
+	}
+	if errors.Is(err, errSSHAgentUnavailable) {
+		return fmt.Errorf("%w: %w", errSSHAgentForwardingUnavailable, err)
+	}
+	return fmt.Errorf("%w: %v", errSSHAgentForwardingUnavailable, err)
+}