open-remote-ssh: SSH接続レイヤーをssh2ライブラリからssh CLI方式に置き換える

[j4rviscmd]

概要

open-remote-ssh の SSH 接続レイヤーを ssh2 Node.js ライブラリから OS の ssh CLI バイナリ spawn 方式に置き換え、Microsoft Remote-SSH 相当の堅牢性と認証互換性を実現する。

背景・動機

フィジビリティ調査結果

Microsoft Remote-SSH (ms-vscode-remote.remote-ssh) は以下の理由で Coderm では利用不可：

1. ライセンス制約: プロプライエタリライセンスにより VS Code fork での使用が明確に禁止
2. ソース非公開: microsoft/vscode-remote-release は issue tracker のみ。ソースコードは非公開
3. 技術的非互換: Microsoft CDN にCodermのcommitハッシュに対応するサーバーバイナリが存在しない

現在の open-remote-ssh の制約

open-remote-ssh は ssh2 Node.js ライブラリを使用しており、以下の制約がある：

項目	ssh CLI (Remote-SSH)	ssh2 ライブラリ (open-remote-ssh)
FIDO2/YubiKey (ed25519-sk)	○	×
Kerberos/GSSAPI	○	×
SSH config 完全互換	○ (OS ssh が解釈)	△ (自前パース)
ControlMaster 多重化	○	×
再接続の堅牢性	高い	低い
Match ディレクティブ	○	△
セキュリティ更新追従	OS ssh 更新で自動	npm パッケージ依存

実装計画

Phase 1: SSH CLI でコマンド実行 (MVP)

効果: FIDO2/Kerberos 対応即時解禁、SSH config 完全互換

• SSHCli クラス新規実装
  • ControlMaster ソケット管理 (-o ControlMaster=auto -o ControlPath=...)
  • exec() メソッド: ControlMaster 経由のコマンド実行
  • SSH config の解釈を OS ssh に完全委譲
• serverSetup.ts の installCodeServer() を ssh CLI 経由に変更
• SSH_ASKPASS 環境変数による VS Code パスワード入力 UI 連携

Phase 2: SSH CLI でポートフォワーディング

効果: 再接続の堅牢性向上

• ssh -L でローカルポートフォワード
• ControlMaster 共有による高速・並列転送
• ソケットパス対応 (-L /path/to/socket:...)

Phase 3: ssh2 ライブラリ完全除去

効果: 依存削減、保守コスト削減

• ssh2, socks, simple-socks 依存削除
• SSHConnection クラス → SSHCli クラスに完全置換
• ProxyJump は ssh CLI に委譲（自前実装削除）
• 認証ハンドラー (getSSHAuthHandler) 全削除

Phase 4: 自動ポート検知 (オプション)

効果: Remote-SSH 相当の UX

• リモートの ss -tlnp 定期ポーリング
• 新規リスニングポート検知→自動フォワード提案

技術的設計

class SSHCli {
  private controlPath: string;
  
  constructor(private host: string, private options: SSHCliOptions) {
    this.controlPath = `/tmp/coderm-ssh-${host}-${randomId}`;
  }

  async connect(): Promise<void> {
    spawn("ssh", [
      "-o", "ControlMaster=auto",
      "-o", `ControlPath=${this.controlPath}`,
      "-o", "ControlPersist=600",
      "-N", this.host
    ]);
  }

  async exec(command: string): Promise<ExecResult> {
    return spawn("ssh", [
      "-o", `ControlPath=${this.controlPath}`,
      this.host, command
    ]);
  }

  async forward(localPort: number, remotePort: number): Promise<void> {
    spawn("ssh", [
      "-o", `ControlPath=${this.controlPath}`,
      "-L", `${localPort}:127.0.0.1:${remotePort}`,
      "-N", this.host
    ]);
  }
}

リスクと対策

リスク	対策
Windows で ssh CLI なし	Windows OpenSSH プリチェック、なければ ssh2 フォールバック
ControlMaster が macOS/Linux のみ	Windows は ControlMaster 非対応のためフォールバック必要
認証プロンプト	SSH_ASKPASS で VS Code UI に接続
ssh stdout/stderr パース	バージョン差異に対応するエラーハンドリング

優先度

Phase 1 だけで最大の価値（全認証方式対応）が得られるため、まず Phase 1 を実装。

対象リポジトリ

• https://github.com/j4rviscmd/open-remote-ssh (フォーク版)

[j4rviscmd]

Phase 2 完了: ssh2ライブラリの完全除去

PR: j4rviscmd/open-remote-ssh#5 (merged)

実施内容

• ssh2, ssh2-streams, simple-socks, socks を完全削除
• 全プラットフォームでOS sshバイナリを使用（Remote-SSH踏襲）
• macOS/Linux: ControlMaster多重化
• Windows: ssh.exe 直接spawn（ControlMasterなし）
• remote.SSH.path 設定追加（カスタムsshバイナリパス）
• バンドルサイズ: ~800KB → ~161KB

---

Remote-SSH vs open-remote-ssh 機能差異まとめ

同等の機能（実装済み）

• OS sshバイナリ使用 (ControlMaster / direct spawn)
• SSH_ASKPASS連携
• FIDO2/ed25519-sk, GSSAPI/Kerberos
• ProxyJump/ProxyCommand (OpenSSH処理)
• Agent転送
• サーバー自動ダウンロード/インストール
• カスタムサーバーURL/インストールパス
• Socketリスニングモード
• 再接続ループ (TemporarilyNotAvailable)
• SSH Targetsツリービュー、接続履歴
• ManagedResolvedAuthority

未実装の機能差異

優先度	機能	説明
高	ポートフォワーディング（ローカル/リモート）	リモートサービスへのlocalhost経由アクセス
高	ポート自動検出・提案	リモートで新規listenポートを検出して通知
高	Ports UIパネル統合	VSCode tunnels API連携
中	showLoginTerminal	接続時のSSHログをターミナルに表示
中	Kill Remote Server コマンド	リモートサーバープロセスの終了
低	SOCKS動的フォワーディング	-D オプション相当
低	x11フォワーディング	GUI転送（まれな用途）
低	localServerDownload	オフライン環境向けサーバーDL
低	lockfilesInTmp	マルチユーザー環境向け
低	maxReconnectionAttempts	再接続回数制限（現在は3時間固定）

次のアクション

上記の未実装機能を優先度順に対応予定。

[j4rviscmd]

SSH Reconnection テスト結果 (PR j4rviscmd/open-remote-ssh#6)

テスト環境

• Mac (192.168.0.158) → Raspberry Pi (192.168.0.50:22)
• Coderm + open-remote-ssh (master: commit 8eceda3)
• ネットワーク切断方法: raspi上でiptables INPUT/OUTPUTルールをsystemd-runで適用・解除

結果

テスト	切断時間	結果	動作詳細
Short outage	10秒	PASS	エクスプローラーのローディング表示のみ。ダイアログなし。TCP再送で透過的に復帰
Medium outage	30秒	PASS	VSCode KeepAlive timeout (20秒) 後に再接続ループ起動。「Setting up SSH Host raspi...」トースト表示後に自動復帰

動作フロー (30秒テスト)

1. ~20秒: VSCode PersistentConnectionのKeepAlive timeout到達、切断検知
2. 再接続ループ起動: makeConnection() コールバックが呼ばれる
3. ネットワーク復帰後: isAlive() → false → reconnect() → SSH再確立
4. 「Setting up SSH Host raspi...」トースト → 自動復帰完了

GCP Workstationsシナリオへの適用

• 10秒程度のネットワーク障害: 完全に透過的に復帰（ユーザー操作不要）
• 30秒程度の障害: 自動復帰成功（トースト表示のみ）

未テスト

• 5分以上の切断（ControlMaster死亡ケース: ServerAliveInterval=60 × ServerAliveCountMax=4 = 240秒）
• Windows環境（ControlMasterなし、boolean flagベース）