network-infra-utility 0.2.0 → 0.5.0

data/service/ssh/lib/network_infra_utility/ssh/ipc/router.rb

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+
+require "json"
+require "securerandom"
+require "thread"
+require_relative "errors"
+require_relative "transport"
+
+module NetworkInfraUtility
+  module SSH
+    module IPC
+      # JSON-RPC 2.0 路由器：请求-响应配对、推送分发、订阅注册/注销。
+      # 取代 HLD 的 IPC::Client，修正 E8（订阅泄漏）。
+      class Router
+        PROTOCOL_VER = "1.0"
+
+        attr_reader :transport, :server_capabilities
+
+        def initialize(transport)
+          @transport = transport
+          @id_mutex = Mutex.new
+          @next_id = 0
+          @pending = {}              # id => [Queue, deadline]
+          @pending_mutex = Mutex.new
+          @subscriptions = {}        # method => { sid => Proc }
+          @subscriptions_mutex = Mutex.new
+          @reverse_handlers = {}     # method => Proc (Erlang→Ruby 带 id 的反向 RPC)
+          @reverse_mutex = Mutex.new
+          @closed = false
+          @disconnect_callbacks = []
+          @disconnect_mutex = Mutex.new
+          @reader_thread = nil
+          @server_capabilities = []
+        end
+
+        # 连接到引擎并完成 hello 握手
+        def connect(endpoint, auth_token:, client_id:)
+          @transport.connect(endpoint)
+          start_reader_thread
+          resp = call("hello", {
+            auth_token: auth_token,
+            ver: PROTOCOL_VER,
+            client_id: client_id
+          }, timeout_ms: 10_000)
+          @server_capabilities = resp[:capabilities] || []
+          resp
+        end
+
+        # 注册连接断开回调
+        # 回调签名: ->(reason) { }
+        def on_disconnect(&block)
+          @disconnect_mutex.synchronize do
+            @disconnect_callbacks << block
+          end
+        end
+
+        # 同步 RPC 调用
+        def call(method, params = {}, timeout_ms: 30_000)
+          ensure_open
+          id = next_id
+          q = Queue.new
+          register_pending(id, q, timeout_ms)
+          @transport.send(jsonrpc: "2.0", id: id, method: method, params: params)
+          msg = q.pop(timeout: timeout_ms / 1000.0)
+          raise RPCTimeout, method unless msg
+          raise RPCError.new(msg[:error]) if msg[:error]
+
+          msg[:result]
+        ensure
+          unregister_pending(id) if id
+        end
+
+        # 订阅推送，返回 subscription_id 用于注销（修正 E8）
+        def subscribe(method, &block)
+          sid = SecureRandom.hex(8)
+          @subscriptions_mutex.synchronize do
+            (@subscriptions[method] ||= {})[sid] = block
+          end
+          sid
+        end
+
+        # 注销订阅
+        def unsubscribe(method, sid)
+          @subscriptions_mutex.synchronize do
+            @subscriptions[method]&.delete(sid)
+          end
+        end
+
+        # 注册反向 RPC 处理器（Erlang→Ruby 带 id 的请求，如 hostkey.resolve）
+        def on_reverse_rpc(method, &block)
+          @reverse_mutex.synchronize do
+            @reverse_handlers[method] = block
+          end
+        end
+
+        # 回复反向 RPC（给 Erlang 发 result）
+        def reply_reverse(id, result)
+          @transport.send(jsonrpc: "2.0", id: id, result: result)
+        end
+
+        def close
+          @closed = true
+          @reader_thread&.kill
+          @transport.close
+        end
+
+        def closed?
+          @closed
+        end
+
+        private
+
+        def ensure_open
+          raise ConnectionLost, "Router closed" if @closed
+        end
+
+        def start_reader_thread
+          @reader_thread = Thread.new do
+            @transport.each_frame do |frame|
+              msg = JSON.parse(frame, symbolize_names: true)
+              on_message(msg)
+            end
+            # EOF reached — 正常关闭
+            handle_disconnect("connection closed (EOF)")
+          rescue StandardError => e
+            handle_disconnect("reader thread error: #{e.message}")
+          end
+        end
+
+        # 引擎断连时调用：通知所有回调并清空 pending 队列，
+        # 避免调用方阻塞至 30s 超时（修正 reader thread 异常不通知 @pending 的缺陷）
+        def handle_disconnect(reason)
+          @closed = true
+
+          # 1. 通知所有断连回调
+          callbacks = @disconnect_mutex.synchronize do
+            @disconnect_callbacks.dup
+          end
+          callbacks.each { |cb| cb.call(reason) }
+
+          # 2. 清空 @pending，给每个等待的 Queue 推入 nil（触发 RPCTimeout）
+          pending = @pending_mutex.synchronize do
+            old = @pending
+            @pending = {}
+            old
+          end
+          pending.each_value { |queue, _deadline| queue << nil }
+        end
+
+        # 由 reader thread 调用
+        def on_message(msg)
+          if msg[:id]
+            if msg[:method]
+              # Erlang→Ruby 的反向 RPC（带 id 和 method）
+              handle_reverse_rpc(msg)
+            else
+              # 对我方请求的响应
+              dispatch_response(msg)
+            end
+          elsif msg[:method]
+            # 推送 notification
+            dispatch_push(msg[:method], msg[:params])
+          end
+        end
+
+        def dispatch_response(msg)
+          entry = @pending_mutex.synchronize { @pending.delete(msg[:id]) }
+          return unless entry
+
+          queue, _deadline = entry
+          queue << msg
+        end
+
+        def dispatch_push(method, params)
+          callbacks = @subscriptions_mutex.synchronize do
+            @subscriptions[method]&.values&.dup
+          end
+          callbacks&.each { |cb| cb.call(params) }
+        end
+
+        def handle_reverse_rpc(msg)
+          handler = @reverse_mutex.synchronize { @reverse_handlers[msg[:method]] }
+          if handler
+            begin
+              result = handler.call(msg[:params])
+              reply_reverse(msg[:id], result)
+            rescue StandardError => e
+              @transport.send(jsonrpc: "2.0", id: msg[:id],
+                              error: { code: -32603, message: e.message })
+            end
+          else
+            @transport.send(jsonrpc: "2.0", id: msg[:id],
+                            error: { code: -32601, message: "No handler for #{msg[:method]}" })
+          end
+        end
+
+        def next_id
+          @id_mutex.synchronize { @next_id += 1 }
+        end
+
+        def register_pending(id, queue, timeout_ms)
+          deadline = Time.now + timeout_ms / 1000.0
+          @pending_mutex.synchronize { @pending[id] = [queue, deadline] }
+        end
+
+        def unregister_pending(id)
+          @pending_mutex.synchronize { @pending.delete(id) }
+        end
+      end
+    end
+  end
+end

data/service/ssh/lib/network_infra_utility/ssh/ipc/transport.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require "json"
+require "socket"
+require "uri"
+require_relative "errors"
+
+module NetworkInfraUtility
+  module SSH
+    module IPC
+      # socket 读写与分帧。重连为 V2.0 功能。
+      # 纯 I/O 层，不做业务路由。
+      class Transport
+        attr_reader :endpoint, :connected
+
+        def initialize(endpoint = nil)
+          @endpoint = endpoint
+          @socket = nil
+          @write_mutex = Mutex.new
+          @connected = false
+        end
+
+        # 连接到端点（unix:path 或 tcp://host:port）
+        def connect(endpoint = @endpoint)
+          raise ArgumentError, "No endpoint" unless endpoint
+
+          @endpoint = endpoint
+          @socket = open_socket(endpoint)
+          @connected = true
+          self
+        end
+
+        # 在 reader thread 中循环调用，按 \n 分帧
+        def each_frame
+          raise ConnectionLost, "Not connected" unless @connected
+
+          buffer = +""
+          loop do
+            chunk = @socket.readpartial(65536)
+            buffer << chunk
+            while (idx = buffer.index("\n"))
+              yield buffer[0...idx]
+              buffer = buffer[(idx + 1)..]
+            end
+          end
+        rescue EOFError, Errno::ECONNRESET, Errno::EPIPE
+          @connected = false
+          nil
+        end
+
+        # 发送一条 JSON 消息（自动追加 \n）
+        def send(hash)
+          raise ConnectionLost, "Not connected" unless @connected
+
+          data = JSON.generate(hash) + "\n"
+          @write_mutex.synchronize { @socket.write(data) }
+        end
+        alias << send
+
+        def close
+          @connected = false
+          @socket&.close
+          @socket = nil
+        end
+
+        private
+
+        def open_socket(endpoint)
+          case endpoint
+          when /\Aunix:(.+)/
+            UNIXSocket.new(Regexp.last_match(1))
+          when /\Atcp:\/\/(.+):(\d+)/
+            TCPSocket.new(Regexp.last_match(1), Regexp.last_match(2).to_i)
+          else
+            raise ArgumentError, "Unknown endpoint format: #{endpoint}"
+          end
+        end
+      end
+    end
+  end
+end

data/service/ssh/lib/network_infra_utility/ssh/security/host_key.rb

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "base64"
+require "openssl"
+require "thread"
+require "fileutils"
+require "time"
+
+module NetworkInfraUtility
+  module SSH
+    module Security
+      # known_hosts 落盘 + 主机密钥裁决。
+      # 对应需求 FR-SEC-002。
+      #
+      # LLD E7 勘误修正：
+      #   Erlang 负责校验（OTP ssh 的 key_cb），
+      #   持久化由 Ruby 经 IPC 提供，Erlang 不落盘 known_hosts。
+      #
+      # 三条裁决路径（LLD §7.8）：
+      #   1. 未知主机 → prompt_user → accept 则存盘且返回 accept；reject 不存盘
+      #   2. 已存在且指纹匹配 → 直接 accept（无交互）
+      #   3. 已存在但指纹变更 → warn_host_key_changed + reject（无交互）
+      #
+      # IPC 双向变体：
+      #   hostkey.resolve 是 Erlang→Ruby 的同步请求（带 id），
+      #   Ruby 必须回一个同 id 的 result。
+      #   Erlang 侧 30s 超时后自动 reject。
+      class HostKey
+        # known_hosts.yml 记录格式：
+        #   <host>:<port>:
+        #     fingerprint: <SHA-256 base64>
+        #     added_at: <ISO8601>
+
+        RESOLVE_TIMEOUT = 30 # 秒，与 Erlang 侧一致
+
+        attr_reader :store_path, :entries
+
+        # @param store_path [String] known_hosts.yml 路径
+        def initialize(store_path)
+          @store_path = store_path
+          @entries = load
+          @save_mutex = Mutex.new
+          @prompt_callback = nil
+        end
+
+        # 设置用户交互回调（V1.0 默认 STDIN，V2.0 TUI 弹窗）
+        # 回调签名: ->(host, port, fingerprint) { :accept | :reject | :once }
+        # 注意：:once 仅由回调模式返回，CLI 默认模式（prompt_user）不支持 :once
+        def on_prompt(&block)
+          @prompt_callback = block
+        end
+
+        # 设置主机密钥变更告警回调
+        # 回调签名: ->(host, port, old_fp, new_fp) { }
+        def on_key_changed(&block)
+          @changed_callback = block
+        end
+
+        # 由 IPC 推送 hostkey.resolve 触发（LLD §7.8）
+        # @param host [String]
+        # @param port [Integer]
+        # @param fingerprint [String] SHA-256 base64 指纹
+        # @return [Hash] { action: "accept" | "reject" | "once" }
+        def resolve(host, port, fingerprint)
+          key = entry_key(host, port)
+
+          if @entries[key].nil?
+            # 路径1：未知主机
+            action = prompt_user(host, port, fingerprint)
+            if action == :accept || action == :once
+              @save_mutex.synchronize do
+                @entries[key] = {
+                  "fingerprint" => fingerprint,
+                  "added_at" => Time.now.iso8601
+                }
+                save
+              end
+            end
+            { action: action.to_s }
+          elsif @entries[key]["fingerprint"] == fingerprint
+            # 路径2：指纹匹配
+            { action: "accept" }
+          else
+            # 路径3：指纹变更
+            warn_host_key_changed(host, port, @entries[key]["fingerprint"], fingerprint)
+            { action: "reject" }
+          end
+        end
+
+        # 手动添加信任条目
+        # @param host [String]
+        # @param port [Integer]
+        # @param fingerprint [String]
+        def add(host, port, fingerprint)
+          key = entry_key(host, port)
+          @save_mutex.synchronize do
+            @entries[key] = {
+              "fingerprint" => fingerprint,
+              "added_at" => Time.now.iso8601
+            }
+            save
+          end
+        end
+
+        # 删除信任条目
+        # @param host [String]
+        # @param port [Integer]
+        def remove(host, port)
+          key = entry_key(host, port)
+          @save_mutex.synchronize do
+            @entries.delete(key)
+            save
+          end
+        end
+
+        # 查询条目
+        # @param host [String]
+        # @param port [Integer]
+        # @return [Hash, nil]
+        def get(host, port)
+          @entries[entry_key(host, port)]
+        end
+
+        # 列出全部条目
+        # @return [Array<Hash>]
+        def list
+          @entries.map do |key, val|
+            host, port = parse_entry_key(key)
+            { host: host, port: port, **val }
+          end
+        end
+
+        private
+
+        # 生成 known_hosts 条目 key
+        def entry_key(host, port)
+          "#{host}:#{port}"
+        end
+
+        def parse_entry_key(key)
+          # 从右侧按第一个冒号分割（host:port）
+          # IPv6 地址含多个冒号，但我们暂不支持 IPv6
+          idx = key.rindex(":")
+          if idx
+            host = key[0...idx]
+            port = key[(idx + 1)..].to_i
+            port = 22 if port == 0
+            [host, port]
+          else
+            [key, 22]
+          end
+        end
+
+        # V1.0 CLI：通过 STDIN 询问用户；V2.0 TUI 弹窗，超时 30s 默认 reject
+        def prompt_user(host, port, fingerprint)
+          if @prompt_callback
+            result = @prompt_callback.call(host, port, fingerprint)
+            return result == :accept ? :accept : (result == :once ? :once : :reject)
+          end
+
+          # 默认 CLI 交互
+          puts "首次连接 #{host}:#{port}，指纹 #{fingerprint}，是否信任？(y/N)"
+          line = STDIN.gets&.chomp
+          line =~ /^y/i ? :accept : :reject
+        end
+
+        def warn_host_key_changed(host, port, old_fp, new_fp)
+          if @changed_callback
+            @changed_callback.call(host, port, old_fp, new_fp)
+          else
+            warn "警告：主机 #{host}:#{port} 的密钥指纹已变更！"
+            warn "  旧指纹: #{old_fp}"
+            warn "  新指纹: #{new_fp}"
+            warn "  连接已被拒绝。如确认安全，请手动删除 known_hosts 条目后重连。"
+          end
+        end
+
+        def load
+          return {} unless File.exist?(@store_path)
+
+          # 使用字符串 key 而非 Symbol：safe_load 不允许 Symbol，
+          # 消除 permitted_classes: [Symbol] 带来的反序列化攻击面。
+          # 写入端 save 也已改为字符串 key。
+          YAML.safe_load(File.read(@store_path)) || {}
+        end
+
+        def save
+          FileUtils.mkdir_p(File.dirname(@store_path))
+          tmp = "#{@store_path}.tmp"
+          File.write(tmp, YAML.dump(@entries))
+          File.rename(tmp, @store_path)
+          set_file_permissions
+        end
+
+        def set_file_permissions
+          if Gem.win_platform?
+            user = ENV["USERNAME"] || ENV["USER"] || ""
+            # 白名单校验用户名，防止 icacls 命令注入
+            unless user.match(/\A[A-Za-z0-9._-]+\z/)
+              raise SecurityError, "Invalid username for ACL: #{user.inspect}"
+            end
+            system("icacls", @store_path, "/inheritance:r", "/grant:r", "#{user}:F")
+          else
+            File.chmod(0o600, @store_path)
+          end
+        end
+      end
+    end
+  end
+end