#MoonSSH — MoonBit SSH 客户端库

• 协议层完全 MoonBit 原创
• 密码学原语通过 FFI 复用系统 OpenSSL libcrypto，不重复造轮子
• TCP 传输层使用 socket FFI：
  • Windows：Winsock socket FFI（不依赖 MSVC）
  • POSIX（Linux / macOS）：POSIX socket FFI

#1. 项目状态

#2. 架构

┌─────────────────────────────────────────────────────────┐
│  cmd/{password,key,sftp,forwarding,output}/             │
│                       ── CLI 入口（按认证方式/场景分命令）│
└────────────────────────┬────────────────────────────────┘
                         │  @src.Client / @src.SftpClient
┌────────────────────────▼────────────────────────────────┐
│  src/ssh_client.mbt       ── 顶层 API                   │
│   • ConnectOptions        ── 连接选项（含 verifier）     │
│   • Client::connect       ── Banner 交换                │
│   • Client::kex           ── 密钥协商                    │
│   • Client::auth_password ── 密码认证                    │
│   • Client::auth_publickey── 公钥认证（two-step）        │
│   • Client::auth_keyboard_interactive ── kbd-int 认证   │
│   • Client::auth_auto     ── 自动回退认证                │
│   • Client::open_session  ── 打开 session 通道           │
│   • Client::exec          ── 命令执行（stdout,stderr）   │
│   • Client::shell         ── shell 通道                 │
│   • Client::forward_local_port  ── 本地转发 (-L)       │
│   • Client::forward_remote_port ── 远程转发 (-R)       │
│   • Client::forward_socks5      ── SOCKS5 代理 (-D)    │
│   • Client::cancel_remote_forward  ── 取消远程转发     │
│   • Client::close         ── 清理                       │
└────────────────────────┬────────────────────────────────┘
                         │
   ┌─────────────────────┼─────────────────────┐
   │                     │                     │
┌──▼────────┐   ┌────────▼─────┐   ┌───────────▼──┐
│ packet.mbt│   │  kex.mbt     │   │  auth.mbt    │
│  • length │   │  • KexContext│   │  • AuthContext│
│  • padding│   │  • 状态机    │   │  • password  │
│  • MAC    │   │  • 算法协商  │   │  • publickey │
└─────┬─────┘   └──────┬──────┘   │  • kbd-int   │
      │                │          └──────┬───────┘
      │                │                 │
      │     ┌──────────▼──────────┐      │
      │     │  channel.mbt        │      │
      │     │  • session / exec   │      │
      │     │  • shell / pty-req  │      │
      │     │  • subsystem (sftp) │      │
      │     │  • window adjust    │      │
      │     │  • stdout/stderr    │      │
      │     └──────────┬──────────┘      │
      │                │                 │
      │     ┌──────────▼──────────┐      │
      │     │  sftp.mbt           │      │
      │     │  • SFTP v3 协议     │      │
      │     │  • 文件传输         │      │
      │     │  • 目录管理         │      │
      │     └──────────┬──────────┘      │
      │                │                 │
      │     ┌──────────▼──────────┐      │
      │     │  known_hosts.mbt    │      │
      │     │  • 通配符匹配       │      │
      │     │  • base64 编解码    │      │
      │     └──────────┬──────────┘      │
      │                │                 │
      │     ┌──────────▼──────────┐      │
      │     │  log.mbt            │      │
      │     │  • debug / hex_dump │      │
      │     └─────────────────────┘      │
      │                                  │
┌─────▼──────────────────────────────────▼───────────────┐
│  src/socket/*   ── TCP 传输层（自实现 socket FFI）     │
│   • socket.mbt  ── Tcp::connect_to_host / write / …   │
│   • socket.c    ── Winsock2 / POSIX socket 实现       │
└────────────────────────┬────────────────────────────────┘
                         │
┌────────────────────────▼────────────────────────────────┐
│  src/crypto/*  ── 密码学原语（FFI 调 OpenSSL libcrypto）│
│  • digest / mac / cipher / pkey / kex / error          │
│  • openssl.c  ── dlopen libcrypto + EVP_* 包装         │
│  • openssl_loader.mbt / crypto_util.mbt                │
└────────────────────────┬────────────────────────────────┘
                         │  FFI
┌────────────────────────▼────────────────────────────────┐
│  libcrypto.so.3 / libcrypto.dylib / libcrypto-3-x64.dll │
└─────────────────────────────────────────────────────────┘

#2.1 协议状态机

                connect()
                  │
                  ▼
              [INIT] ───────► send_banner / recv_banner
                  │
                  ▼
              [KEXINIT] ◄──► KexContext::drive
                  │              │ KEXDH_INIT / KEX_ECDH_INIT
                  │              ▼
                  │          [KEXDH_REPLY / KEX_ECDH_REPLY]
                  │              │
                  │              ▼
                  │          [NEWKEYS] ──► 启用新密钥
                  ▼
              [AUTH] ◄──► AuthContext
                  │         • none 探测
                  │         • password / publickey / kbd-int
                  ▼
              [CHANNEL] ◄──► Channel::open_session
                  │              │ exec / shell
                  │              ▼
                  │          [DATA + EXIT-STATUS]
                  ▼
              [CLOSE]

#3. 项目结构

moonbit-ssh-client/
├── AGENTS.md                    项目开发规范
├── README.md
├── README.mbt.md                mooncakes.io 简介
├── LICENSE                      Apache-2.0
├── moon.mod                     模块清单
├── moon.pkg                     根包（仅导入子包）
├── ssh_client.mbt               根包占位
├── ssh_client_test.mbt          黑盒测试
├── ssh_client_wbtest.mbt        白盒测试
├── pkg.generated.mbti           根包生成接口
├── .cnb.yml                     CNB 开发环境配置（含 docker sshd 自启）
├── src/                         ★ 核心库
│   ├── moon.pkg                 子包：PaiGack/ssh_client/src
│   ├── pkg.generated.mbti       生成接口
│   ├── log.mbt                  调试输出（debug / hex_dump / 开关）
│   ├── ssh_client.mbt           顶层 API（ConnectOptions / Client）
│   ├── packet.mbt               包序列化（length/padding/payload/MAC）+ Reader/Writer
│   ├── kex.mbt                  KEXINIT 状态机、密钥派生
│   ├── auth.mbt                 用户认证（password / publickey / kbd-int / none）
│   ├── channel.mbt              通道（session/exec/shell/pty-req/subsystem，状态机 + stdout/stderr）
│   ├── sftp.mbt                 SFTP v3 协议（文件传输 / 目录管理）
│   ├── known_hosts.mbt          known_hosts 解析 + 通配符匹配
│   ├── socket/                  ★ TCP 传输层（自实现 FFI）
│   │   ├── moon.pkg
│   │   ├── pkg.generated.mbti
│   │   ├── socket.mbt           Tcp::connect_to_host / write / read_*
│   │   └── socket.c             Winsock2 / POSIX socket 实现 + TCP_NODELAY
│   └── crypto/                  ★ 密码学子包
│       ├── moon.pkg
│       ├── pkg.generated.mbti
│       ├── openssl.c            OpenSSL dlopen + EVP_* / BN_* 包装
│       ├── openssl_loader.mbt   动态加载 libcrypto
│       ├── crypto_util.mbt      RAND_bytes / ERR_*
│       ├── digest.mbt           SHA-1/256/384/512
│       ├── mac.mbt              HMAC-SHA-1 / HMAC-SHA-256
│       ├── cipher.mbt           AES-128-CTR
│       ├── pkey.mbt             RSA/Ed25519/DSA/ECDSA 签名/验证 + 加载 PEM/OpenSSH 私钥
│       ├── kex.mbt              DH Group14 + BigInt FFI（BN_*）
│       └── error.mbt            CryptoError
├── cmd/                         ★ CLI 入口（按认证方式/场景分多个子命令）
│   ├── output/                  Hello MoonBit 演示（println "Hello MoonBit!"）
│   ├── utils/                   CMD args 工具：tokenize / split_user_host / parse_forward_arg / parse_int
│   ├── password/                密码认证（auth_auto）
│   ├── key/                     Ed25519/RSA/ECDSA 公钥认证
│   ├── sftp/                    SFTP 文件传输客户端（ls/get/put/rm/mkdir/rmdir/stat）
│   └── forwarding/              端口转发（-L / -R / -D），三个独立 run-*.sh
├── docs/
│   ├── prd_000.md                       设计 PRD
│   ├── prd_001_ssh-key-types-support-plan.md   密钥类型扩展计划
│   ├── prd_002_sftp-support-plan.md     SFTP 实现计划
│   ├── prd_003_port-forwarding-plan.md         端口转发设计文档
│   └── crypto-replacement-plan.md       OpenSSL 替换为 MoonBit 原生实现的方案
└── scripts/
    └── ssh-server/              本地 docker sshd 脚本（每个认证方式独立）
        ├── .env                 密码（password="123456"）
        ├── .gitignore           忽略本地生成的密钥对
        ├── password.sh          密码认证 sshd（端口 1022→2222）
        ├── key-ed25519.sh       生成 ed25519 密钥 + 公钥认证 sshd（端口 2022→2222）
        ├── key-rsa.sh           生成 4096 位 rsa 密钥 + 公钥认证 sshd（端口 3022→2222）
        ├── key-ecdsa.sh         生成 ecdsa 密钥 + 公钥认证 sshd（端口 4022→2222）
        └── forwarding.sh        密码认证 sshd（端口 5022→2222，AllowTcpForwarding=yes）+ nginx(1080) 验证目标

#4. 快速开始

#4.1 前置依赖

# add C:\msys64\ucrt64\bin to PATH
pacman -S mingw-w64-ucrt-x86_64-gcc
pacman -S mingw-w64-ucrt-x86_64-openssl

apt-get install -y gcc libssl-dev

brew install gcc openssl

#4.2 启动测试 sshd

注意： 每次启动 key-*.sh 都会清空并重新生成同名密钥对（id_ed25519 / id_rsa / id_ecdsa）；生成位置在 scripts/ssh-server/ 内，已被 .gitignore 排除。

bash scripts/ssh-server/password.sh
# 在另一个终端：ssh admin@127.0.0.1 -p 1022  # 密码 123456

#4.3 构建与运行

1. source .env 注入 MSSH_HOST / MSSH_PORT / MSSH_USERNAME / MSSH_PASSWORD 等变量
2. export MOONBIT_CLI_ARGS="..."（CLI 参数通过环境变量传入 main，避免对 argv 解析的兼容问题）
3. moon clean && moon run . --target native（一次完成编译 + 运行）

#4.3.1 密码认证

# 前置：bash scripts/ssh-server/password.sh
cd cmd/password
./run.sh
# 内部：
#   source .env       # 注入 MSSH_HOST=127.0.0.1 MSSH_PORT=1022 MSSH_USERNAME=admin MSSH_PASSWORD=123456
#   export MOONBIT_CLI_ARGS="$MSSH_USERNAME@$MSSH_HOST --port $MSSH_PORT --exec 'uname -a' --password $MSSH_PASSWORD"
#   moon clean && moon run . --target native

export MOONBIT_CLI_ARGS="admin@127.0.0.1 --port 1022 --exec 'uname -a' --password 123456"
cd cmd/password
moon run . --target native

#4.3.2 公钥认证（Ed25519 / RSA / ECDSA）

# 前置：bash scripts/ssh-server/key-ed25519.sh   # 或 key-rsa.sh / key-ecdsa.sh
cd cmd/key
./run-ed25519.sh     # 默认 --key ${workspace}/scripts/ssh-server/id_ed25519
./run-rsa.sh         # 默认 --key ${workspace}/scripts/ssh-server/id_rsa
./run-ecdsa.sh       # 默认 --key ${workspace}/scripts/ssh-server/id_ecdsa
# 内部：
#   export MOONBIT_CLI_ARGS="$MSSH_USERNAME@$MSSH_HOST --port $MSSH_PORT --exec 'uname -a' --key ${workspace}/scripts/ssh-server/id_<alg>"
#   moon clean && moon run . --target native

#4.3.3 SFTP 文件传输

# 前置：bash scripts/ssh-server/password.sh
cd cmd/sftp
./run.sh
# 内部：
#   moon clean && moon build . --target native
#   export MOONBIT_CLI_ARGS="$MSSH_USERNAME@$MSSH_HOST --port $MSSH_PORT --password $MSSH_PASSWORD --command ls /"
#   ../../_build/native/debug/build/cmd/sftp/sftp.exe
#   …（依次 mkdir / ls / put / ls / get / stat / rm / rmdir / ls）

注意： 当前 cmd_get 把内容以 hex 预览打印到 stdout，并未真正写入本地文件；cmd_put 上传的是一个固定的演示字符串（Hello from MoonSSH SFTP client!）。

#4.3.4 端口转发

# 前置：bash scripts/ssh-server/forwarding.sh
#   （启动 sshd 5022→2222，并把 1080 端口绑定到 nginx 作为统一目标；
#    同时配置 AllowTcpForwarding=yes / GatewayPorts=yes / PermitOpen=any）
cd cmd/forwarding

# 1. 远程转发 (-R)：远端 8080 → SSH 隧道 → 本地 localhost:1080 (nginx)
./run-remote.sh
# 内部默认：
#   export MOONBIT_CLI_ARGS="$MSSH_USERNAME@$MSSH_HOST --port $MSSH_PORT -R 8080:localhost:1080 --password $MSSH_PASSWORD"
#   moon clean && moon run . --target native
# 验证（在 sshd 容器内）：
#   docker exec openssh-server_forwarding curl http://127.0.0.1:8080

# 2. 本地转发 (-L)：本地 2080 → SSH 隧道 → 远端 gateway:1080 (宿主机 nginx)
./run-local.sh
# 内部默认：
#   export MOONBIT_CLI_ARGS="$MSSH_USERNAME@$MSSH_HOST --port $MSSH_PORT -L 2080:$GATEWAY_IP:1080 --password $MSSH_PASSWORD"
# 验证（在宿主机）：
#   curl http://127.0.0.1:2080

# 3. SOCKS5 动态代理 (-D)：本地 SOCKS5:3080 → SSH 隧道 → 任意远端目标
./run-socks5.sh
# 内部默认：
#   export MOONBIT_CLI_ARGS="$MSSH_USERNAME@$MSSH_HOST --port $MSSH_PORT -D 3080 --password $MSSH_PASSWORD"
# 验证（在宿主机，通过 SOCKS5 访问远端 nginx）：
#   curl --socks5 127.0.0.1:3080 http://$GATEWAY_IP:1080

实现要点：

• 三种模式都共用一个 relay_data() 双向中继实现（select-style 轮询，避免阻塞任一方向）。
• SOCKS5 当前仅支持 IPv4（ATYP=0x01）与域名（ATYP=0x03），IPv6（ATYP=0x04）直接返回 0x08 并关闭。
• relay_data 内部把 channel 的 data_sink 切到 Socket(local_socket) 模式，绕开 Buffer 缓冲。
• 集成测试在 .github/workflows/integration.yml 中跑全：依次 run-remote.sh → run-local.sh → run-socks5.sh。

#5. 核心模块

#5.1 ConnectOptions

pub struct ConnectOptions {
  host : String
  port : Int
  user : String
  client_banner : String?                  // 默认 "SSH-2.0-MoonSSH_0.1.0"
  host_key_policy : HostKeyPolicy          // 默认 Strict, 无条目 -> 拒绝所有未知主机
  timeout_ms : Int                          // 默认 30_000
}

// 1. 严格模式：加载本地 known_hosts
let kh = read_known_hosts("~/.ssh/known_hosts")  // 调用方自己读
let opts = @src.ConnectOptions::new("example.com", 22, "alice")
  .with_strict_host_key_check(kh)

// 2. TOFU：首次询问用户
let opts2 = @src.ConnectOptions::new("new.host.com", 22, "alice")
  .with_trust_on_first_use("", (host, alg, key) => {
    let fp = fingerprint(alg, key)
    confirm("Trust \{host} (fp=\{fp})? [y/N]")
  })

// 3. 自定义校验（HSM / 外部 Trust Store）
let opts3 = @src.ConnectOptions::new("example.com", 22, "alice")
  .with_host_key_verifier((alg, key) => hsm.verify("ssh-host", alg, key))

// 4. 内网测试：跳过校验
let opts4 = @src.ConnectOptions::new("127.0.0.1", 2222, "test")
  .with_insecure_host_key()

#5.2 Client 顶层 API

#5.3 Channel

pub struct Channel {
  id : Int         // 本地 channel id
  peer_id : Int    // 服务端分配的 channel id
  state : ChannelState  // Closed / Opening / Open / ExecPending / EofReceived / Closing / Done
  channel_type : ChannelType  // Session / DirectTcpip(host, port) / ForwardedTcpip(host, port)
  data_sink : DataSink        // Buffer / Socket(Tcp)
  // ...
}

pub fn Channel::id(self) -> Int
pub fn Channel::peer_id(self) -> Int
pub fn Channel::state(self) -> ChannelState
pub fn Channel::is_open(self) -> Bool
pub fn Channel::exit_status(self) -> Int?

• Session — exec / shell / subsystem
• DirectTcpip(host, port) — 本地转发（-L），客户端发起
• ForwardedTcpip(host, port) — 远程转发（-R），服务端发起

#5.4 SftpClient

pub struct SftpClient {
  // 内部字段
  priv client : Client
  priv channel : Channel
  priv version : Int       // SFTP 协议版本，当前固定为 3
  priv mut request_id : Int
}

pub struct SftpAttrs {
  priv flags : Int
  size : Int?
  uid : Int?
  gid : Int?
  permissions : Int?
  atime : Int?
  mtime : Int?
}

pub struct SftpDirEntry {
  filename : String
  longname : String
  attrs : SftpAttrs
}

// 初始化
pub fn SftpClient::open(client : Client) -> SftpClient raise SshError

// 高层 API
pub fn SftpClient::read_file(path : String) -> Bytes raise SshError
pub fn SftpClient::write_file(path : String, data : Bytes, permissions : Int) -> Unit raise SshError
pub fn SftpClient::listdir(path : String) -> Array[SftpDirEntry] raise SshError

// 底层 API
pub fn SftpClient::readdir(path : String) -> Array[SftpDirEntry] raise SshError
pub fn SftpClient::read(handle : Bytes, offset : Int, length : Int) -> Bytes raise SshError
pub fn SftpClient::write(handle : Bytes, offset : Int, data : Bytes) -> Unit raise SshError
pub fn SftpClient::close_handle(handle : Bytes) -> Unit raise SshError
pub fn SftpClient::stat(path : String) -> SftpAttrs raise SshError
pub fn SftpClient::remove(path : String) -> Unit raise SshError
pub fn SftpClient::mkdir(path : String, permissions : Int) -> Unit raise SshError
pub fn SftpClient::rmdir(path : String) -> Unit raise SshError
pub fn SftpClient::rename(oldpath : String, newpath : String) -> Unit raise SshError
pub fn SftpClient::realpath(path : String) -> String raise SshError
pub fn SftpClient::close() -> Unit

当前限制： 文件大小按 32 位 Int 读取，超过 4 GiB 的文件会被截断；SftpAttrs 仅解析 SSH_FILEXFER_ATTR_SIZE / UIDGID / PERMISSIONS / ACCESSTIME / MODIFYTIME，未识别的 flags 字段被忽略。

#5.5 known_hosts

pub struct KnownHost {
  patterns : Array[String]
  key_alg : String
  key : Bytes
}

pub fn KnownHost::matches(self, host : String, port : Int) -> Bool
pub fn KnownHost::alg(self) -> String
pub fn KnownHost::key_bytes(self) -> Bytes

#6. 开发流程

#6.1 修改后必跑

moon fmt                          # 格式化
moon info                         # 更新 .mbti 接口
moon build --target native        # 编译
moon test --target native         # 测试

#6.2 覆盖率

moon coverage analyze > uncovered.log
# 目标：uncovered.log 中 packet / kex / auth 关键路径为空

#6.3 派生代码

• 原 Apache 2.0 版权头
• 命名空间调整记录（moonbitlang/async/socket → src/socket）

#7. 路线图

• shell 交互（stdin/stdout 转发）
• Client::exec_pty() 高层封装（build_channel_request_pty 已就绪）
• X11 转发（x11-req 全局请求 + x11 通道类型 + X11FakeCookie / MIT-MAGIC-COOKIE-1 协议）
• HMAC-SHA1 形式的 known_hosts 条目（|1|…）

#8. 跨平台注意

#9. 引用

• RFC 4251 — SSH Protocol Architecture
• RFC 4252 — SSH Authentication Protocol
• RFC 4253 — SSH Transport Layer Protocol
• RFC 4254 — SSH Connection Protocol（含 TCP/IP Forwarding §7）
• RFC 1928 — SOCKS Protocol Version 5
• RFC 4344 — SSH Transport Layer Encryption Modes
• RFC 5656 — SSH ECC Algorithm Integration
• RFC 6668 — SHA-2 Data Integrity Verification for SSH
• RFC 8332 — Use of RSA Keys with SHA-256/512
• OpenSSL EVP — 密码学 API
• draft-ietf-secsh-filexfer-02 — SSH File Transfer Protocol v3
• OpenSSH sftp-server - SFTP
• moonbitlang/async — 派生来源（Apache 2.0）

#10. License