gssh-agent 1.0.0

package/idea.md

@@ -0,0 +1,271 @@
+# gssh 需求文档
+
+## 1. 项目概述
+
+gssh 是一个供 Agent 使用的 SSH Session 管理工具。通过 Go 语言实现，支持：
+
+- 多个 SSH Session 并发管理
+- 命令执行与结果透传
+- TCP 流量转发
+- 断联自动重连
+- 被连接机器零配置（普通 SSH 即可）
+
+## 2. 整体架构
+
+### 2.1 Client-Server 模式
+
+```
+┌─────────────────┐      IPC       ┌─────────────────┐
+│   gssh CLI      │ ───────────▶  │   gssh daemon   │
+│   (Agent)       │   JSON/RPC    │   (后台进程)     │
+└─────────────────┘                └────────┬────────┘
+                                           │
+                                    ┌──────▼──────┐
+                                    │  Session    │
+                                    │  Manager    │
+                                    └──────┬──────┘
+                                           │
+                              ┌────────────┼────────────┐
+                              ▼            ▼            ▼
+                        ┌──────────┐ ┌──────────┐ ┌──────────┐
+                        │ Session 1│ │ Session 2│ │ Session n│
+                        │ (SSH)    │ │ (SSH)    │ │ (SSH)    │
+                        └──────────┘ └──────────┘ └──────────┘
+```
+
+### 2.2 组件职责
+
+| 组件 | 职责 |
+|------|------|
+| **gssh daemon** | 后台进程，管理所有 SSH session，处理重连 |
+| **gssh CLI** | Agent 的接口工具，通过 Unix socket 与 daemon 通信 |
+| **Session Manager** | 管理多个 SSH 连接，维护状态，处理断联重连 |
+| **SSH Client** | 封装 SSH 连接逻辑，支持 Key/密码/键盘交互认证 |
+| **Port Forwarder** | 处理 TCP 流量转发 |
+
+## 3. 功能需求
+
+### 3.1 连接管理
+
+- [x] 建立 SSH 连接，创建新 session
+- [x] 断开指定 session
+- [x] 手动重连指定 session
+- [x] 列出所有 session（显示 ID、主机、状态）
+- [x] 切换默认 session
+
+### 3.2 命令执行
+
+- [x] 在指定 session 执行命令
+- [x] 在默认 session 执行命令
+- [x] 返回 stdout + stderr
+- [x] 返回命令退出码
+
+### 3.3 端口转发
+
+- [x] 本地端口转发（-l: local -> remote）
+- [ ] 远程端口转发（-R: remote -> local）
+- [x] 列出所有转发
+- [x] 关闭指定转发
+
+### 3.4 重连机制
+
+- [x] 检测连接断开
+- [x] 立即自动重连
+- [ ] 重连成功后恢复端口转发
+
+### 3.5 认证支持
+
+- [x] SSH Key 认证
+- [x] 密码认证
+- [x] 键盘交互认证
+
+### 3.6 被连接机器要求
+
+- 标准 SSH 服务
+- 可用 SSH 账号
+- **零配置**，无需安装任何 agent
+
+## 4. 命令行接口
+
+### 4.1 连接管理命令
+
+```bash
+# 建立新 session
+gssh connect -u user -h host [-p port] [-i key_path] [-P password]
+
+# 断开指定 session
+gssh disconnect [-s session_id]
+
+# 重连指定 session
+gssh reconnect [-s session_id]
+
+# 列出所有 session
+gssh list
+
+# 切换默认 session
+gssh use <session_id>
+```
+
+### 4.2 命令执行命令
+
+```bash
+# 在默认 session 执行命令
+gssh exec "ls -la"
+
+# 在指定 session 执行命令
+gssh exec -s <session_id> "ls"
+```
+
+### 4.3 端口转发命令
+
+```bash
+# 本地端口转发：本地 8080 -> 远程 80
+gssh forward -l 8080 -r 80
+
+# 远程端口转发：远程 9000 -> 本地 9000
+gssh forward -R 9000 -r 9000
+
+# 列出所有转发
+gssh forwards
+
+# 关闭指定转发
+gssh forward-close <id>
+```
+
+## 5. 通信协议
+
+- **daemon <-> CLI**: 通过 Unix socket (`/tmp/gssh.sock`) 通信
+- **协议格式**: JSON-RPC 2.0
+- **认证**: 使用 Unix socket 权限控制
+
+## 6. Session 状态
+
+```go
+type Session struct {
+    ID      string    // session ID (UUID)
+    Host    string    // 主机地址
+    User    string    // 用户名
+    Port    int       // 端口
+    Status  string    // connected, disconnected, reconnecting
+    KeyPath string    // SSH 密钥路径
+}
+```
+
+## 7. 输出格式
+
+### 7.1 list 命令输出示例
+
+```
+ID                                      HOST              USER    STATUS
+8d89a0a0-ab03-4a1a-a818-101c6b2f6155  139.196.175.163  admin1  connected
+```
+
+### 7.2 exec 命令输出格式
+
+```json
+{
+    "stdout": "...",
+    "stderr": "...",
+    "exit_code": 0
+}
+```
+
+### 7.3 forwards 命令输出示例
+
+```
+ID    LOCAL    REMOTE    TYPE
+1     8080     80        local
+2     9000     9000       remote
+```
+
+## 8. 使用示例
+
+### 8.1 密码认证连接
+
+```bash
+# 启动 daemon
+gssh daemon &
+
+# 连接 SSH
+gssh connect -u admin1 -h 139.196.175.163 -p 7080 -P 1234
+
+# 执行命令
+gssh exec "ls -la"
+```
+
+### 8.2 密钥认证连接
+
+```bash
+gssh connect -u admin1 -h 139.196.175.163 -p 7080 -i ~/.ssh/id_rsa
+```
+
+### 8.3 Session 管理
+
+```bash
+# 列出所有 session
+gssh list
+
+# 切换默认 session
+gssh use <session_id>
+
+# 断开 session
+gssh disconnect -s <session_id>
+
+# 重连 session
+gssh reconnect -s <session_id>
+```
+
+## 9. 项目结构
+
+```
+gssh/
+├── cmd/
+│   ├── daemon/main.go       # daemon 主程序
+│   └── gssh/main.go        # CLI 主程序
+├── internal/
+│   ├── client/
+│   │   ├── ssh.go          # SSH 客户端封装
+│   │   └── ssh_test.go     # SSH 客户端测试
+│   ├── portforward/
+│   │   └── forwarder.go    # 端口转发实现
+│   ├── protocol/
+│   │   ├── types.go        # 协议类型定义
+│   │   └── types_test.go   # 协议类型测试
+│   └── session/
+│       ├── manager.go       # Session 管理器
+│       └── manager_test.go  # Session 管理器测试
+├── pkg/
+│   └── rpc/
+│       └── handler.go       # RPC 处理器
+├── go.mod
+└── .gitignore
+```
+
+## 10. 测试结果
+
+### 单元测试
+
+```
+=== RUN   TestExpandPath                          PASS
+=== RUN   TestNewAuthMethodsFromKeyPath           PASS
+=== RUN   TestSessionJSON                         PASS
+=== RUN   TestExecResultJSON                      PASS
+=== RUN   TestForwardJSON                         PASS
+=== RUN   TestNewManager                          PASS
+=== RUN   TestManagerList                         PASS
+=== RUN   TestManagerUse                          PASS
+=== RUN   TestManagerGetDefaultID                 PASS
+=== RUN   TestManagerListForwards                 PASS
+```
+
+### 功能测试（密码认证）
+
+| 测试项 | 结果 |
+|--------|------|
+| 连接 SSH | ✅ 通过 |
+| 列出 session | ✅ 通过 |
+| 执行命令（默认 session） | ✅ 通过 |
+| 执行命令（指定 session ID） | ✅ 通过 |
+| 断开 session | ✅ 通过 |
+| 重连 session | ✅ 通过 |
+| 重连后执行命令 | ✅ 通过 |

package/internal/client/ssh.go

@@ -0,0 +1,143 @@
+package client
+
+import (
+	"fmt"
+	"net"
+	"os"
+	"os/user"
+	"path/filepath"
+
+	"golang.org/x/crypto/ssh"
+)
+
+// SSHClient encapsulates SSH connection logic
+type SSHClient struct {
+	Client *ssh.Client
+}
+
+// KeyboardInteractiveHandler handles keyboard-interactive authentication
+type KeyboardInteractiveHandler struct {
+	Password string
+}
+
+// Challenge implements ssh.KeyboardInteractiveChallenge
+func (k *KeyboardInteractiveHandler) Challenge(name, instruction string, questions []string, echoes []bool) ([]string, error) {
+	answers := make([]string, len(questions))
+	for i := range questions {
+		answers[i] = k.Password
+	}
+	return answers, nil
+}
+
+// NewSSHClient creates a new SSH client
+func NewSSHClient(user, host string, port int, authMethods ...ssh.AuthMethod) (*SSHClient, error) {
+	config := &ssh.ClientConfig{
+		User:            user,
+		Auth:            authMethods,
+		HostKeyCallback: ssh.InsecureIgnoreHostKey(),
+	}
+
+	addr := fmt.Sprintf("%s:%d", host, port)
+	client, err := ssh.Dial("tcp", addr, config)
+	if err != nil {
+		return nil, fmt.Errorf("failed to connect to %s: %w", addr, err)
+	}
+
+	return &SSHClient{Client: client}, nil
+}
+
+// NewAuthMethodsFromKeyPath creates SSH auth methods from a key file
+func NewAuthMethodsFromKeyPath(keyPath string) ([]ssh.AuthMethod, error) {
+	keyPath = expandPath(keyPath)
+
+	key, err := os.ReadFile(keyPath)
+	if err != nil {
+		return nil, fmt.Errorf("unable to read private key: %w", err)
+	}
+
+	signer, err := ssh.ParsePrivateKey(key)
+	if err != nil {
+		return nil, fmt.Errorf("unable to parse private key: %w", err)
+	}
+
+	return []ssh.AuthMethod{ssh.PublicKeys(signer)}, nil
+}
+
+// NewAuthMethodFromPassword creates SSH auth method from password
+func NewAuthMethodFromPassword(password string) ssh.AuthMethod {
+	return ssh.Password(password)
+}
+
+// NewAuthMethodFromKeyboardInteractive creates keyboard-interactive auth
+func NewAuthMethodFromKeyboardInteractive(password string) ssh.AuthMethod {
+	handler := &KeyboardInteractiveHandler{Password: password}
+	return ssh.KeyboardInteractive(handler.Challenge)
+}
+
+// Connect establishes an SSH connection
+func Connect(user, host string, port int, password, keyPath string) (*SSHClient, error) {
+	var authMethods []ssh.AuthMethod
+
+	if keyPath != "" {
+		methods, err := NewAuthMethodsFromKeyPath(keyPath)
+		if err != nil {
+			return nil, err
+		}
+		authMethods = append(authMethods, methods...)
+	}
+
+	if password != "" {
+		// Try both password and keyboard-interactive
+		authMethods = append(authMethods, NewAuthMethodFromPassword(password))
+		authMethods = append(authMethods, NewAuthMethodFromKeyboardInteractive(password))
+	}
+
+	// If no auth methods, return error
+	if len(authMethods) == 0 {
+		return nil, fmt.Errorf("no authentication method provided")
+	}
+
+	return NewSSHClient(user, host, port, authMethods...)
+}
+
+// Exec executes a command on the remote host
+func (c *SSHClient) Exec(cmd string) (string, string, int, error) {
+	session, err := c.Client.NewSession()
+	if err != nil {
+		return "", "", 0, fmt.Errorf("failed to create session: %w", err)
+	}
+	defer session.Close()
+
+	output, err := session.CombinedOutput(cmd)
+	if err != nil {
+		exitErr, ok := err.(*ssh.ExitError)
+		if ok {
+			return string(output), "", exitErr.ExitStatus(), nil
+		}
+		return string(output), "", 0, err
+	}
+
+	return string(output), "", 0, nil
+}
+
+// Close closes the SSH connection
+func (c *SSHClient) Close() error {
+	return c.Client.Close()
+}
+
+// LocalForward creates a local port forward (localhost -> remote)
+func (c *SSHClient) LocalForward(localPort, remotePort int) (net.Listener, error) {
+	return c.Client.Listen("tcp", fmt.Sprintf("localhost:%d", localPort))
+}
+
+// expandPath expands ~ to home directory
+func expandPath(path string) string {
+	if len(path) > 0 && path[0] == '~' {
+		usr, err := user.Current()
+		if err != nil {
+			return path
+		}
+		return filepath.Join(usr.HomeDir, path[1:])
+	}
+	return path
+}

package/internal/client/ssh_test.go

@@ -0,0 +1,33 @@
+package client
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestExpandPath(t *testing.T) {
+	// Test normal path
+	path := "/tmp/test"
+	result := expandPath(path)
+	if result != path {
+		t.Errorf("expected %s, got %s", path, result)
+	}
+
+	// Test with tilde
+	home := os.Getenv("HOME")
+	path = "~/test"
+	result = expandPath(path)
+	expected := filepath.Join(home, "test")
+	if result != expected {
+		t.Errorf("expected %s, got %s", expected, result)
+	}
+}
+
+func TestNewAuthMethodsFromKeyPath(t *testing.T) {
+	// Test with non-existent key
+	_, err := NewAuthMethodsFromKeyPath("/nonexistent/key")
+	if err == nil {
+		t.Error("expected error for non-existent key")
+	}
+}

package/internal/portforward/forwarder.go

@@ -0,0 +1,187 @@
+package portforward
+
+import (
+	"fmt"
+	"io"
+	"net"
+	"sync"
+
+	"golang.org/x/crypto/ssh"
+)
+
+// Forwarder handles SSH port forwarding
+type Forwarder struct {
+	ID         string
+	Type       string // "local" or "remote"
+	LocalPort  int
+	RemotePort int
+
+	sshClient  *ssh.Client
+	listener   net.Listener
+	conns      map[net.Conn]bool
+	mu         sync.RWMutex
+	closed     bool
+	wg         sync.WaitGroup
+}
+
+// NewForwarder creates a new port forwarder
+func NewForwarder(sshClient *ssh.Client, forwardType string, localPort, remotePort int) (*Forwarder, error) {
+	f := &Forwarder{
+		Type:       forwardType,
+		LocalPort:  localPort,
+		RemotePort: remotePort,
+		sshClient:  sshClient,
+		conns:      make(map[net.Conn]bool),
+	}
+
+	if forwardType == "local" {
+		// Local port forward: localhost:localPort -> remote:remotePort
+		addr := fmt.Sprintf("localhost:%d", localPort)
+		listener, err := net.Listen("tcp", addr)
+		if err != nil {
+			return nil, fmt.Errorf("failed to listen on %s: %w", addr, err)
+		}
+		f.listener = listener
+	}
+
+	return f, nil
+}
+
+// Start starts the port forwarder
+func (f *Forwarder) Start() {
+	if f.Type == "local" {
+		f.startLocalForward()
+	} else {
+		f.startRemoteForward()
+	}
+}
+
+// startLocalForward handles local port forwarding
+func (f *Forwarder) startLocalForward() {
+	f.wg.Add(1)
+	go func() {
+		defer f.wg.Done()
+		for {
+			f.mu.RLock()
+			if f.closed {
+				f.mu.RUnlock()
+				return
+			}
+			f.mu.RUnlock()
+
+			conn, err := f.listener.Accept()
+			if err != nil {
+				f.mu.RLock()
+				closed := f.closed
+				f.mu.RUnlock()
+				if closed {
+					return
+				}
+				continue
+			}
+
+			f.mu.Lock()
+			f.conns[conn] = true
+			f.mu.Unlock()
+
+			go f.handleLocalConnection(conn)
+		}
+	}()
+}
+
+// handleLocalConnection handles a local connection
+func (f *Forwarder) handleLocalConnection(localConn net.Conn) {
+	defer func() {
+		localConn.Close()
+		f.mu.Lock()
+		delete(f.conns, localConn)
+		f.mu.Unlock()
+	}()
+
+	remoteAddr := fmt.Sprintf("localhost:%d", f.RemotePort)
+	remoteConn, err := f.sshClient.Dial("tcp", remoteAddr)
+	if err != nil {
+		return
+	}
+	defer remoteConn.Close()
+
+	// Bidirectional copy
+	done := make(chan struct{})
+	go func() {
+		io.Copy(remoteConn, localConn)
+		remoteConn.Close()
+		localConn.Close()
+		close(done)
+	}()
+
+	io.Copy(localConn, remoteConn)
+	<-done
+}
+
+// startRemoteForward handles remote port forwarding
+func (f *Forwarder) startRemoteForward() {
+	// Remote port forwarding: remote:remotePort -> localhost:localPort
+	f.wg.Add(1)
+	go func() {
+		defer f.wg.Done()
+
+		// Request the server to forward remote port
+		// This is a simplified implementation
+		for {
+			f.mu.RLock()
+			if f.closed {
+				f.mu.RUnlock()
+				return
+			}
+			f.mu.RUnlock()
+
+			// Wait for connections on remote side
+			// In practice, SSH server handles this
+			// This would need SSH channel forwarding
+		}
+	}()
+}
+
+// Close closes the port forwarder
+func (f *Forwarder) Close() {
+	f.mu.Lock()
+	if f.closed {
+		f.mu.Unlock()
+		return
+	}
+	f.closed = true
+	f.mu.Unlock()
+
+	if f.listener != nil {
+		f.listener.Close()
+	}
+
+	for conn := range f.conns {
+		conn.Close()
+	}
+
+	f.wg.Wait()
+}
+
+// Restart restarts the forwarder with a new SSH client
+func (f *Forwarder) Restart(sshClient *ssh.Client) {
+	f.mu.Lock()
+	f.sshClient = sshClient
+	f.closed = false
+	f.conns = make(map[net.Conn]bool)
+	f.mu.Unlock()
+
+	if f.listener != nil {
+		f.listener.Close()
+	}
+
+	// Create new listener
+	addr := fmt.Sprintf("localhost:%d", f.LocalPort)
+	listener, err := net.Listen("tcp", addr)
+	if err != nil {
+		return
+	}
+	f.listener = listener
+
+	f.Start()
+}

package/internal/protocol/types.go

@@ -0,0 +1,90 @@
+package protocol
+
+import "encoding/json"
+
+// Session represents an SSH session
+type Session struct {
+	ID       string `json:"id"`
+	Host     string `json:"host"`
+	User     string `json:"user"`
+	Port     int    `json:"port"`
+	Status   string `json:"status"`
+	LastCmd  string `json:"last_cmd,omitempty"`
+	Password string `json:"-"`
+	KeyPath  string `json:"key_path,omitempty"`
+}
+
+// Forward represents a port forward
+type Forward struct {
+	ID     string `json:"id"`
+	Type   string `json:"type"` // "local" or "remote"
+	Local  int    `json:"local"`
+	Remote int    `json:"remote"`
+}
+
+// ExecResult represents command execution result
+type ExecResult struct {
+	Stdout   string `json:"stdout"`
+	Stderr   string `json:"stderr"`
+	ExitCode int    `json:"exit_code"`
+}
+
+// Request represents a JSON-RPC request
+type Request struct {
+	JSONRPC string          `json:"jsonrpc"`
+	Method  string          `json:"method"`
+	Params  json.RawMessage `json:"params,omitempty"`
+	ID      interface{}     `json:"id"`
+}
+
+// Response represents a JSON-RPC response
+type Response struct {
+	JSONRPC string      `json:"jsonrpc"`
+	Result  interface{} `json:"result,omitempty"`
+	Error   *Error      `json:"error,omitempty"`
+	ID      interface{} `json:"id"`
+}
+
+// Error represents a JSON-RPC error
+type Error struct {
+	Code    int         `json:"code"`
+	Message string      `json:"message"`
+	Data    interface{} `json:"data,omitempty"`
+}
+
+// Request params types
+type ConnectParams struct {
+	User     string `json:"user"`
+	Host     string `json:"host"`
+	Port     int    `json:"port"`
+	Password string `json:"password,omitempty"`
+	KeyPath  string `json:"key_path,omitempty"`
+}
+
+type DisconnectParams struct {
+	SessionID string `json:"session_id"`
+}
+
+type ReconnectParams struct {
+	SessionID string `json:"session_id"`
+}
+
+type ExecParams struct {
+	SessionID string `json:"session_id,omitempty"`
+	Command   string `json:"command"`
+}
+
+type ForwardParams struct {
+	SessionID string `json:"session_id,omitempty"`
+	Type      string `json:"type"` // "local" or "remote"
+	Local     int    `json:"local"`
+	Remote    int    `json:"remote"`
+}
+
+type ForwardCloseParams struct {
+	ForwardID string `json:"forward_id"`
+}
+
+type UseParams struct {
+	SessionID string `json:"session_id"`
+}