network-infra-utility 0.3.0 → 0.6.0

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

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+require "base64"
+require "openssl"
+require "yaml"
+require "securerandom"
+require "fileutils"
+
+module NetworkInfraUtility
+  module SSH
+    module Security
+      # 凭据加密存储，AES-256-GCM。
+      # 对应需求 FR-SEC-001。
+      #
+      # 加密参数（HLD §5.2.7 / ADR-004）：
+      #   算法        AES-256-GCM
+      #   KDF         PBKDF2-HMAC-SHA256
+      #   迭代次数    100,000
+      #   Salt 长度   32 字节（每条凭据独立随机）
+      #   Key 长度    32 字节
+      #   Nonce 长度  12 字节（GCM nonce，每次加密随机）
+      #   Auth Tag    GCM 生成，存于 tag 字段
+      #
+      # vault.yml 每条记录格式：
+      #   <key>:
+      #     salt:   <Base64>
+      #     nonce:  <Base64>
+      #     tag:    <Base64>
+      #     data:   <Base64>
+      #
+      # LLD §7.7 修正：
+      #   - @cache 不在多线程访问（V1.0 主线程唯一），但为 V2.0 batch 预留 @cache_mutex
+        #   - resolve_credentials 不直接修改传入的 spec，返回新 hash
+      class Vault
+        PBKDF2_ITERATIONS = 100_000
+        SALT_LENGTH       = 32
+        KEY_LENGTH        = 32    # AES-256
+        NONCE_LENGTH      = 12    # GCM nonce
+        REF_PREFIX        = "~vault:"
+
+        attr_reader :store_path
+
+        # @param master_password [String] 主密码（不落盘，仅内存）
+        # @param store_path [String] vault.yml 路径
+        def initialize(master_password, store_path = nil)
+          raise ArgumentError, "Master password cannot be empty" if master_password.nil? || master_password.empty?
+
+          @master_password = master_password
+          @store_path = store_path || default_store_path
+          @cache = {}
+          @cache_mutex = Mutex.new # V2.0 batch 预留
+        end
+
+        # 加密凭据并存储到 vault.yml。
+        # @param key [String] 凭据标识，如 "sess_001_pass"
+        # @param value [String] 明文凭据
+        def store(key, value)
+          salt = SecureRandom.random_bytes(SALT_LENGTH)
+          derived_key = derive_key(@master_password, salt)
+          nonce = SecureRandom.random_bytes(NONCE_LENGTH)
+
+          cipher = OpenSSL::Cipher::AES.new(256, :GCM)
+          cipher.encrypt
+          cipher.key = derived_key
+          cipher.iv = nonce
+          encrypted = cipher.update(value) + cipher.final
+          tag = cipher.auth_tag
+
+          entry = {
+            "salt"  => Base64.strict_encode64(salt),
+            "nonce" => Base64.strict_encode64(nonce),
+            "tag"   => Base64.strict_encode64(tag),
+            "data"  => Base64.strict_encode64(encrypted)
+          }
+          write_to_store(key, entry)
+          @cache_mutex.synchronize { @cache[key] = value }
+        end
+
+        # 读取并解密凭据。
+        # @param key [String] 凭据标识
+        # @return [String, nil] 明文凭据，不存在返回 nil
+        def load(key)
+          cached = @cache_mutex.synchronize { @cache[key] }
+          return cached if cached
+
+          entry = read_from_store(key)
+          return nil unless entry
+
+          plaintext = decrypt_entry(entry)
+          @cache_mutex.synchronize { @cache[key] = plaintext }
+          plaintext
+        end
+
+        # 删除凭据
+        # @param key [String] 凭据标识
+        def delete(key)
+          store = load_store
+          store.delete(key)
+          write_store(store)
+          @cache_mutex.synchronize { @cache.delete(key) }
+        end
+
+        # 列出全部凭据标识
+        # @return [Array<String>]
+        def keys
+          load_store.keys.map(&:to_s)
+        end
+
+        # 在连接规格中解析凭据引用。
+        # spec 中值为 "~vault:<key>" 的字段会被替换为解密后的明文。
+        # LLD §7.7 修正：返回新 hash，不修改入参。
+        # @param spec [Hash] 连接规格
+        # @return [Hash] 新的连接规格，凭据引用已解析为明文
+        def resolve_credentials(spec)
+          spec.each_with_object({}) do |(k, v), result|
+            result[k] = resolve_value(v)
+          end
+        end
+
+        # 检查凭据标识是否是 vault 引用
+        # @param str [String]
+        # @return [Boolean]
+        def vault_ref?(str)
+          str.is_a?(String) && str.start_with?(REF_PREFIX)
+        end
+
+        private
+
+        # 递归解析 spec 中的 vault 引用（处理嵌套 hash 和数组）
+        def resolve_value(v)
+          case v
+          when String
+            v.start_with?(REF_PREFIX) ? load(v.sub(REF_PREFIX, "")) : v
+          when Hash
+            v.transform_values { |val| resolve_value(val) }
+          when Array
+            v.map { |val| resolve_value(val) }
+          else
+            v
+          end
+        end
+
+        def derive_key(password, salt)
+          OpenSSL::PKCS5.pbkdf2_hmac(password, salt, PBKDF2_ITERATIONS, KEY_LENGTH, "sha256")
+        end
+
+        def decrypt_entry(entry)
+          salt = Base64.strict_decode64(entry["salt"])
+          nonce = Base64.strict_decode64(entry["nonce"])
+          tag = Base64.strict_decode64(entry["tag"])
+          encrypted = Base64.strict_decode64(entry["data"])
+
+          derived_key = derive_key(@master_password, salt)
+
+          cipher = OpenSSL::Cipher::AES.new(256, :GCM)
+          cipher.decrypt
+          cipher.key = derived_key
+          cipher.iv = nonce
+          cipher.auth_tag = tag
+
+          cipher.update(encrypted) + cipher.final
+        end
+
+        def write_to_store(key, entry)
+          store = load_store
+          store[key] = entry
+          write_store(store)
+        end
+
+        def read_from_store(key)
+          load_store[key]
+        end
+
+        def load_store
+          return {} unless File.exist?(@store_path)
+
+          # 使用字符串 key 而非 Symbol：safe_load 不允许 Symbol，
+          # 消除 permitted_classes: [Symbol] 带来的反序列化攻击面。
+          # 写入端 write_store 也已改为字符串 key。
+          YAML.safe_load(File.read(@store_path)) || {}
+        end
+
+        def write_store(store)
+          FileUtils.mkdir_p(File.dirname(@store_path))
+          File.write(@store_path, YAML.dump(store))
+          set_file_permissions
+        end
+
+        def default_store_path
+          File.join(Dir.home, ".network-infra-utility", "vault.yml")
+        end
+
+        def set_file_permissions
+          path = @store_path
+          if Gem.win_platform?
+            # Windows: ACL 限制当前用户读写
+            # 使用 ENV.fetch 避免注入：icacls 的用户名参数不转义特殊字符会导致命令注入
+            user = ENV["USERNAME"] || ENV["USER"] || ""
+            # 白名单校验用户名（Windows 用户名仅允许字母、数字、连字符、下划线和点）
+            unless user.match(/\A[A-Za-z0-9._-]+\z/)
+              raise SecurityError, "Invalid username for ACL: #{user.inspect}"
+            end
+            system("icacls", path, "/inheritance:r", "/grant:r", "#{user}:F")
+          else
+            File.chmod(0o600, path)
+          end
+        end
+      end
+    end
+  end
+end

data/service/ssh/lib/network_infra_utility/ssh/session/history.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module NetworkInfraUtility
+  module SSH
+    module Session
+      # 最近连接列表与历史记录（FR-SESS-005）。
+      # 在内存中维护，可持久化到配置。
+      class History
+        MAX_ITEMS = 20
+
+        attr_reader :items, :pinned
+
+        def initialize
+          @items = []       # [Session] 按使用时间倒序
+          @pinned = {}      # conn_id => true
+        end
+
+        # 记录一次连接
+        def record(session)
+          @items.delete(session)
+          @items.unshift(session)
+          trim
+        end
+
+        # 置顶
+        def pin(conn_id)
+          @pinned[conn_id] = true
+        end
+
+        # 取消置顶
+        def unpin(conn_id)
+          @pinned.delete(conn_id)
+        end
+
+        # 获取最近列表（置顶在前）
+        def recent
+          pinned_sessions = @items.select { |s| @pinned[s.conn_id] }
+          unpinned = @items.reject { |s| @pinned[s.conn_id] }
+          pinned_sessions + unpinned
+        end
+
+        # 清除
+        def clear
+          @items.clear
+          @pinned.clear
+        end
+
+        private
+
+        def trim
+          @items = @items.first(MAX_ITEMS)
+        end
+      end
+    end
+  end
+end

data/service/ssh/lib/network_infra_utility/ssh/session/manager.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require_relative "session"
+require_relative "tree"
+require_relative "history"
+
+module NetworkInfraUtility
+  module SSH
+    module Session
+      # 会话管理器：维护全部活跃会话的生命周期。
+      # 对应需求 FR-SESS-001 ~ FR-SESS-006。
+      class Manager
+        include Enumerable
+
+        attr_reader :tree, :history
+
+        def initialize(client)
+          @client = client
+          @sessions = {}        # conn_id => Session
+          @tree = Tree.new
+          @history = History.new
+          setup_conn_closed_handler
+        end
+
+        # 从已有连接 ID 创建会话对象
+        def create(conn_id, spec, fingerprint = nil)
+          session = Session.new(@client, conn_id, spec, fingerprint)
+          @sessions[conn_id] = session
+          @history.record(session)
+          session
+        end
+
+        def get(conn_id)
+          @sessions[conn_id]
+        end
+
+        def disconnect(conn_id)
+          @sessions[conn_id]&.disconnect
+          @sessions.delete(conn_id)
+        end
+
+        def disconnect_all
+          @sessions.each_value(&:disconnect)
+          @sessions.clear
+        end
+
+        def each(&block)
+          @sessions.each_value(&block)
+        end
+
+        def count
+          @sessions.size
+        end
+
+        # 搜索会话（FR-SESS-004）
+        # @param query [String] 搜索关键词
+        # @param fields [Array<Symbol>] 搜索字段，默认 :name, :host, :ip, :tags
+        def search(query, fields = %i[name host ip tags])
+          query_lower = query.downcase
+          select do |s|
+            fields.any? do |f|
+              val = s.send(f)
+              if val.is_a?(Array)
+                val.any? { |v| v.to_s.downcase.include?(query_lower) }
+              else
+                val.to_s.downcase.include?(query_lower)
+              end
+            end
+          end
+        end
+
+        # 广播输入到多个会话（FR-TERM-008）
+        # @param conn_ids [Array<String>] 目标连接 ID
+        # @param text [String] 要发送的文本
+        def broadcast(conn_ids, text)
+          conn_ids.each { |id| @sessions[id]&.terminal&.send(text) }
+        end
+
+        private
+
+        # 监听 conn.closed 推送，清理会话
+        def setup_conn_closed_handler
+          @client.ipc.subscribe("conn.closed") do |params|
+            conn_id = params[:conn_id]
+            session = @sessions.delete(conn_id)
+            session&.on_closed(params[:reason])
+          end
+        end
+      end
+    end
+  end
+end

data/service/ssh/lib/network_infra_utility/ssh/session/session.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require_relative "../terminal/emulator"
+
+module NetworkInfraUtility
+  module SSH
+    module Session
+      # 单个 SSH 会话：封装终端、文件、端口转发等子能力。
+      class Session
+        attr_reader :session_id, :conn_id, :spec, :name, :host, :port, :user
+        attr_reader :fingerprint, :terminal, :file_manager, :port_forwards
+        attr_accessor :tags, :group, :status
+
+        STATUSES = %i[connecting authenticating connected disconnected error].freeze
+
+        def initialize(client, conn_id, spec, fingerprint = nil)
+          @client = client
+          @conn_id = conn_id
+          @session_id = "sess_#{SecureRandom.uuid.delete('-')}"
+          @spec = spec
+          @fingerprint = fingerprint
+          @name = spec[:name] || "#{spec[:user]}@#{spec[:host]}"
+          @host = spec[:host]
+          @port = spec[:port] || 22
+          @user = spec[:user]
+          @tags = spec[:tags] || []
+          @group = spec[:group]
+          @status = :connected
+          @terminal = nil
+          @file_manager = nil
+          @port_forwards = []
+          @coalesce = client.coalesce
+        end
+
+        # 打开终端通道
+        # @param term_type [String] 终端类型如 "xterm-256color"
+        # @param cols [Integer] 列数
+        # @param rows [Integer] 行数
+        def open_terminal(term_type: "xterm-256color", cols: 80, rows: 24)
+          raise "Terminal already open" if @terminal
+
+          resp = @client.ipc.call("channel.open", {
+            conn_id: @conn_id,
+            type: "shell",
+            term: term_type,
+            cols: cols,
+            rows: rows
+          })
+          ch_id = resp[:channel_id]
+          @terminal = Terminal::Emulator.new(@client, @conn_id, ch_id, cols, rows,
+                                              theme: @spec[:terminal]&.dig(:theme))
+          @coalesce&.register_channel(@conn_id, ch_id, @terminal)
+          @terminal
+        end
+
+        # 关闭终端
+        def close_terminal
+          return unless @terminal
+
+          @client.ipc.call("channel.close", { id: @terminal.channel_id })
+          @coalesce&.unregister_channel(@conn_id, @terminal.channel_id)
+          @terminal = nil
+        end
+
+        # 添加端口转发规则（FR-NET-001）
+        def add_port_forward(type, local_port, remote_host, remote_port)
+          resp = @client.ipc.call("portfwd.add", {
+            conn_id: @conn_id,
+            type: type.to_s,
+            local_port: local_port,
+            remote_host: remote_host,
+            remote_port: remote_port
+          })
+          rule_id = resp[:rule_id]
+          @port_forwards << {
+            id: rule_id, type: type, local_port: local_port,
+            remote_host: remote_host, remote_port: remote_port
+          }
+          rule_id
+        end
+
+        # 移除端口转发规则
+        def remove_port_forward(rule_id)
+          @client.ipc.call("portfwd.remove", { conn_id: @conn_id, rule_id: rule_id })
+          @port_forwards.reject! { |r| r[:id] == rule_id }
+        end
+
+        # 断开连接
+        def disconnect
+          close_terminal
+          @client.ipc.call("conn.disconnect", { id: @conn_id })
+          @status = :disconnected
+        end
+
+        def connected?
+          @status == :connected
+        end
+
+        # 连接被远端关闭时的回调
+        def on_closed(reason = nil)
+          @status = :disconnected
+          @terminal = nil
+          @file_manager = nil
+        end
+      end
+    end
+  end
+end

data/service/ssh/lib/network_infra_utility/ssh/session/tree.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module NetworkInfraUtility
+  module SSH
+    module Session
+      # 会话分组的树形管理（FR-SESS-002）。
+      # 支持 ≥ 5 层嵌套、拖拽移动、折叠/展开、分组级批量操作。
+      class Tree
+        attr_reader :root
+
+        Node = Struct.new(:id, :name, :parent, :children, :collapsed, keyword_init: true)
+
+        def initialize
+          @root = Node.new(id: "root", name: "Root", parent: nil, children: [], collapsed: false)
+          @nodes = { "root" => @root }
+        end
+
+        # 添加分组
+        def add_group(name, parent_id: "root")
+          id = "grp_#{SecureRandom.hex(4)}"
+          parent = @nodes[parent_id]
+          raise "Parent group not found: #{parent_id}" unless parent
+
+          node = Node.new(id: id, name: name, parent: parent, children: [], collapsed: false)
+          parent.children << node
+          @nodes[id] = node
+          id
+        end
+
+        # 删除分组（子分组递归删除）
+        def remove_group(group_id)
+          node = @nodes.delete(group_id)
+          return unless node
+
+          node.parent&.children&.delete(node)
+          node.children.each { |c| remove_group(c.id) }
+        end
+
+        # 重命名分组
+        def rename_group(group_id, new_name)
+          @nodes[group_id]&.name = new_name
+        end
+
+        # 折叠/展开
+        def toggle_collapse(group_id)
+          node = @nodes[group_id]
+          return unless node
+
+          node.collapsed = !node.collapsed
+        end
+
+        # 移动分组到新父节点
+        def move_group(group_id, new_parent_id)
+          node = @nodes[group_id]
+          new_parent = @nodes[new_parent_id]
+          return unless node && new_parent
+
+          node.parent&.children&.delete(node)
+          node.parent = new_parent
+          new_parent.children << node
+        end
+
+        # 查找分组
+        def find_group(group_id)
+          @nodes[group_id]
+        end
+
+        # 遍历所有分组（深度优先）
+        def each_group(&block)
+          traverse(@root, &block)
+        end
+
+        # 获取分组的完整路径名
+        def group_path(group_id)
+          parts = []
+          node = @nodes[group_id]
+          while node && node.id != "root"
+            parts.unshift(node.name)
+            node = node.parent
+          end
+          parts.join(" / ")
+        end
+
+        private
+
+        def traverse(node, &block)
+          block.call(node) unless node.id == "root"
+          node.children.each { |c| traverse(c, &block) }
+        end
+      end
+    end
+  end
+end