localvault 1.6.2 → 1.8.0

data/lib/localvault/input_validation.rb

@@ -0,0 +1,80 @@
+module LocalVault
+  module InputValidation
+    class InvalidInput < StandardError; end
+
+    SEGMENT_PATTERN = /\A[A-Za-z_][A-Za-z0-9_]*\z/
+    VAULT_PATTERN = /\A[A-Za-z0-9][A-Za-z0-9_-]{0,63}\z/
+    PROFILES = %w[aws].freeze
+
+    module_function
+
+    def selector!(value)
+      string!(value, "selector")
+      reject_delimiters!(value, "selector")
+      parts = value.split(".", -1)
+      valid = parts.length == 1 ? segment?(parts.first) :
+        parts.length == 2 && segment?(parts.first) && (segment?(parts.last) || parts.last == "*")
+      raise InvalidInput, "selector must be KEY, GROUP.KEY, or GROUP.*" unless valid
+
+      value
+    end
+
+    def mapping!(source, target)
+      selector!(source)
+      raise InvalidInput, "mapping source must be an exact key" if source.end_with?(".*")
+      string!(target, "mapping target")
+      reject_delimiters!(target, "mapping target")
+      raise InvalidInput, "mapping target must be an environment variable name" unless segment?(target)
+
+      [source, target]
+    end
+
+    def project!(value)
+      string!(value, "project")
+      reject_delimiters!(value, "project")
+      raise InvalidInput, "project must be one key segment" unless segment?(value)
+
+      value
+    end
+
+    def vault_name!(value)
+      string!(value, "vault")
+      raise InvalidInput, "vault must be a valid vault name" unless value.match?(VAULT_PATTERN)
+
+      value
+    end
+
+    def argv!(value)
+      unless value.is_a?(Array) && !value.empty? &&
+          value.all? { |token| token.is_a?(String) && !token.empty? && !token.include?("\0") }
+        raise InvalidInput, "command must be a non-empty array of non-empty NUL-free strings"
+      end
+
+      value
+    end
+
+    def profile!(value)
+      string!(value, "profile")
+      raise InvalidInput, "profile must be one of: #{PROFILES.join(", ")}" unless PROFILES.include?(value)
+
+      value
+    end
+
+    def segment?(value)
+      value.is_a?(String) && value.match?(SEGMENT_PATTERN)
+    end
+
+    def string!(value, label)
+      raise InvalidInput, "#{label} must be a non-empty string" unless value.is_a?(String) && !value.empty?
+      raise InvalidInput, "#{label} must not contain NUL bytes" if value.include?("\0")
+    end
+
+    def reject_delimiters!(value, label)
+      if value.include?(",") || value.include?("=")
+        raise InvalidInput, "#{label} must not contain commas or equals signs"
+      end
+    end
+
+    private_class_method :string!, :reject_delimiters!
+  end
+end

data/lib/localvault/key_lookup.rb

@@ -0,0 +1,30 @@
+module LocalVault
+  module KeyLookup
+    Result = Struct.new(:key, :value, :matches, keyword_init: true) do
+      def exact?
+        !value.nil?
+      end
+
+      def single_match?
+        matches.size == 1
+      end
+
+      def multiple_matches?
+        matches.size > 1
+      end
+    end
+
+    def self.lookup(vault, key)
+      value = vault.get(key)
+      return Result.new(key: key, value: value, matches: []) unless value.nil?
+
+      matches = candidates(vault, key)
+      Result.new(key: key, value: nil, matches: matches)
+    end
+
+    def self.candidates(vault, key)
+      query = key.to_s.downcase
+      vault.list.select { |candidate| candidate.downcase.include?(query) }.sort
+    end
+  end
+end

data/lib/localvault/mcp/exec_command_builder.rb

@@ -0,0 +1,77 @@
+require "shellwords"
+require_relative "../input_validation"
+
+module LocalVault
+  module MCP
+    class ExecCommandBuilder
+      def initialize(command:, vault: nil, project: nil, only: nil, except: nil, map: nil, profile: nil)
+        @command = command
+        @vault = vault
+        @project = project
+        @only = only
+        @except = except
+        @map = map
+        @profile = profile
+      end
+
+      def build
+        validate!
+        argv = ["localvault", "exec"]
+        append(argv, "-v", @vault)
+        append(argv, "--project", @project)
+        append(argv, "--only", serialize_selectors(@only))
+        append(argv, "--except", serialize_selectors(@except))
+        append(argv, "--map", serialize_map)
+        append(argv, "--profile", @profile)
+        argv.concat(["--", *@command])
+
+        {
+          "command" => Shellwords.join(argv),
+          "exposes_plaintext" => false,
+          "executes_command" => false,
+          "next_action" => "Run this command through your normal shell tool."
+        }.freeze
+      end
+
+      private
+
+      def validate!
+        InputValidation.argv!(@command)
+        InputValidation.vault_name!(@vault) if @vault
+        InputValidation.project!(@project) if @project
+        InputValidation.profile!(@profile) if @profile
+        validate_selectors!(@only, "only")
+        validate_selectors!(@except, "except")
+        validate_map!
+      end
+
+      def validate_selectors!(selectors, label)
+        return if selectors.nil?
+        unless selectors.is_a?(Array) && !selectors.empty?
+          raise InputValidation::InvalidInput, "#{label} must be a non-empty array of selectors"
+        end
+        selectors.each { |selector| InputValidation.selector!(selector) }
+      end
+
+      def validate_map!
+        return if @map.nil?
+        unless @map.is_a?(Hash) && !@map.empty?
+          raise InputValidation::InvalidInput, "map must be a non-empty object"
+        end
+        @map.each { |source, target| InputValidation.mapping!(source, target) }
+      end
+
+      def append(argv, flag, value)
+        argv.concat([flag, value]) if value
+      end
+
+      def serialize_selectors(selectors)
+        selectors&.join(",")
+      end
+
+      def serialize_map
+        @map&.sort_by { |source, _target| source }&.map { |source, target| "#{source}=#{target}" }&.join(",")
+      end
+    end
+  end
+end

data/lib/localvault/mcp/server.rb

@@ -6,6 +6,7 @@ require_relative "../config"
 require_relative "../store"
 require_relative "../vault"
 require_relative "../session_cache"
+require_relative "../vault_resolver"
 require_relative "tools"
 
 module LocalVault
@@ -16,10 +17,8 @@ module LocalVault
       # @param input [IO] input stream for JSON-RPC messages (default: $stdin)
       # @param output [IO] output stream for JSON-RPC responses (default: $stdout)
       def initialize(input: $stdin, output: $stdout)
-        @input        = input
-        @output       = output
-        @vault_cache  = {}  # name => Vault — lazily populated per-call
-        @session_vault = load_session_vault  # LOCALVAULT_SESSION fast-path
+        @input  = input
+        @output = output
       end
 
       # Start the MCP server loop, reading JSON-RPC messages line-by-line.
@@ -29,7 +28,7 @@ module LocalVault
       #
       # @return [void]
       def start
-        unlocked = unlocked_vault_names
+        unlocked = VaultResolver.unlocked_vault_names
         label = unlocked.empty? ? "no unlocked vaults (run: localvault show)" : "vaults=#{unlocked.join(', ')}"
         $stderr.puts "[localvault-mcp] started  v#{LocalVault::VERSION}  #{label}"
         $stderr.flush
@@ -73,7 +72,10 @@ module LocalVault
           success_response(id, {
             "protocolVersion" => "2025-11-25",
             "capabilities"    => { "tools" => {} },
-            "serverInfo"      => { "name" => "localvault", "version" => LocalVault::VERSION }
+            "serverInfo"      => { "name" => "localvault", "version" => LocalVault::VERSION },
+            "instructions"    => "Do not retrieve plaintext secrets for commands, API calls, evaluation, or configuration. " \
+                                 "Call list_secrets to discover names, then localvault_build_exec to construct process-scoped injection. " \
+                                 "Use get_secret with allow_plaintext: true only when the user task explicitly requires the value itself."
           })
         when "tools/list"
           success_response(id, { "tools" => Tools::DEFINITIONS })
@@ -85,7 +87,7 @@ module LocalVault
             return error_response(id, -32602, "Unknown tool: #{tool_name}")
           end
 
-          result = Tools.call(tool_name, arguments, method(:vault_for))
+          result = Tools.call(tool_name, arguments, method(:vault_for), method(:vault_status))
           success_response(id, result)
         else
           error_response(id, -32601, "Method not found: #{method}")
@@ -99,70 +101,11 @@ module LocalVault
       # Resolve vault by name, lazily — tries session token, then Keychain.
       # Returns nil if vault is not unlocked.
       def vault_for(name = nil)
-        # No specific vault requested: session vault takes priority over default
-        if name.nil? && @session_vault
-          @vault_cache[@session_vault.name] ||= @session_vault
-          return @session_vault
-        end
-
-        vault_name = name || default_vault_name
-
-        return @vault_cache[vault_name] if @vault_cache.key?(vault_name)
-
-        # Fast-path: LOCALVAULT_SESSION matches by name
-        if @session_vault && @session_vault.name == vault_name
-          @vault_cache[vault_name] = @session_vault
-          return @session_vault
-        end
-
-        # Keychain lookup
-        if (master_key = SessionCache.get(vault_name))
-          vault = Vault.new(name: vault_name, master_key: master_key)
-          vault.all  # verify decryption
-          @vault_cache[vault_name] = vault
-          return vault
-        end
-
-        nil
-      rescue Crypto::DecryptionError
-        nil
-      end
-
-      def default_vault_name
-        ENV["LOCALVAULT_VAULT"] || Config.default_vault
-      end
-
-      # Parse LOCALVAULT_SESSION on startup (single-vault legacy path).
-      def load_session_vault
-        token = ENV["LOCALVAULT_SESSION"]
-        return nil unless token
-
-        decoded     = Base64.strict_decode64(token)
-        vault_name, key_b64 = decoded.split(":", 2)
-        return nil unless vault_name && key_b64
-
-        master_key = Base64.strict_decode64(key_b64)
-        vault = Vault.new(name: vault_name, master_key: master_key)
-        vault.all  # verify decryption
-        vault
-      rescue ArgumentError, Crypto::DecryptionError
-        nil
+        VaultResolver.resolve(name).vault
       end
 
-      # List vault names that are currently unlocked (for the startup log).
-      def unlocked_vault_names
-        names = []
-
-        # From LOCALVAULT_SESSION
-        names << @session_vault.name if @session_vault
-
-        # From Keychain — check all known vaults
-        Store.list_vaults.each do |n|
-          next if names.include?(n)
-          names << n if SessionCache.get(n)
-        end
-
-        names
+      def vault_status(name = nil)
+        VaultResolver.status(name)
       end
 
       def success_response(id, result)

data/lib/localvault/mcp/tools.rb

@@ -1,4 +1,7 @@
 require "json"
+require_relative "../key_lookup"
+require_relative "../version"
+require_relative "exec_command_builder"
 
 module LocalVault
   module MCP
@@ -15,24 +18,70 @@ module LocalVault
       DEFINITIONS = [
         {
           "name" => "get_secret",
-          "description" => "Retrieve a secret value by key from a localvault vault",
+          "description" => "Reveal plaintext only when the task truly requires the value in model context. Prefer localvault_build_exec for commands, evaluations, and API calls.",
           "inputSchema" => {
             "type" => "object",
             "properties" => {
-              "key"   => { "type" => "string", "description" => "The secret key to retrieve" },
+              "key"   => { "type" => "string", "description" => "The exact secret key to reveal" },
+              "allow_plaintext" => { "type" => "boolean", "description" => "Must be true to acknowledge that plaintext will enter model context" },
               **VAULT_PARAM
             },
-            "required" => ["key"]
-          }
+            "required" => ["key", "allow_plaintext"]
+          },
+          "annotations" => { "readOnlyHint" => true, "openWorldHint" => false }
         },
         {
           "name" => "list_secrets",
-          "description" => "List all secret keys in a localvault vault",
+          "description" => "Discover secret names without values. After selecting names, use localvault_build_exec to inject them into a process.",
+          "inputSchema" => {
+            "type" => "object",
+            "properties" => {
+              "prefix" => { "type" => "string", "description" => "Only return keys starting with this prefix" },
+              "query" => { "type" => "string", "description" => "Case-insensitive substring filter for key names" },
+              **VAULT_PARAM
+            },
+            "required" => []
+          },
+          "annotations" => { "readOnlyHint" => true, "openWorldHint" => false }
+        },
+        {
+          "name" => "localvault_build_exec",
+          "description" => "Build, but never execute, a shell-safe localvault exec command that injects secrets directly into a subprocess without exposing values to the model.",
+          "inputSchema" => {
+            "type" => "object",
+            "properties" => {
+              "command" => { "type" => "array", "items" => { "type" => "string" }, "description" => "Command argv to run with injected secrets" },
+              "vault" => { "type" => "string", "description" => "Vault name" },
+              "project" => { "type" => "string", "description" => "Dot-notation project group to inject without a prefix" },
+              "only" => { "type" => "array", "items" => { "type" => "string" }, "description" => "Exact keys or GROUP.* selectors" },
+              "except" => { "type" => "array", "items" => { "type" => "string" }, "description" => "Selectors to exclude" },
+              "map" => { "type" => "object", "additionalProperties" => { "type" => "string" }, "description" => "Vault-key to environment-variable mappings" },
+              "profile" => { "type" => "string", "enum" => ["aws"], "description" => "Built-in mapping profile" }
+            },
+            "required" => ["command"]
+          },
+          "outputSchema" => {
+            "type" => "object",
+            "properties" => {
+              "command" => { "type" => "string" },
+              "exposes_plaintext" => { "type" => "boolean" },
+              "executes_command" => { "type" => "boolean" },
+              "next_action" => { "type" => "string" }
+            },
+            "required" => %w[command exposes_plaintext executes_command next_action],
+            "additionalProperties" => false
+          },
+          "annotations" => { "readOnlyHint" => true, "openWorldHint" => false }
+        },
+        {
+          "name" => "localvault_whoami",
+          "description" => "Show which localvault home, vault, and unlocked sessions the MCP server can see",
           "inputSchema" => {
             "type" => "object",
             "properties" => { **VAULT_PARAM },
             "required" => []
-          }
+          },
+          "annotations" => { "readOnlyHint" => true, "openWorldHint" => false }
         },
         {
           "name" => "set_secret",
@@ -45,6 +94,12 @@ module LocalVault
               **VAULT_PARAM
             },
             "required" => ["key", "value"]
+          },
+          "annotations" => {
+            "readOnlyHint" => false,
+            "destructiveHint" => true,
+            "idempotentHint" => false,
+            "openWorldHint" => false
           }
         },
         {
@@ -57,6 +112,12 @@ module LocalVault
               **VAULT_PARAM
             },
             "required" => ["key"]
+          },
+          "annotations" => {
+            "readOnlyHint" => false,
+            "destructiveHint" => true,
+            "idempotentHint" => true,
+            "openWorldHint" => false
           }
         }
       ].freeze
@@ -72,45 +133,87 @@ module LocalVault
       #   and returns a Vault instance or nil
       # @return [Hash] MCP content result with "content" array and optional "isError"
       # @raise [ArgumentError] if the tool name is unknown
-      def self.call(name, arguments, vault_resolver)
+      def self.call(name, arguments, vault_resolver, status_resolver = nil)
         unless DEFINITIONS.any? { |t| t["name"] == name }
           raise ArgumentError, "Unknown tool: #{name}"
         end
 
+        return error_result("Invalid arguments; expected object") unless arguments.is_a?(Hash)
+
         vault_name = arguments["vault"]
+        return whoami(status_resolver.call(vault_name)) if name == "localvault_whoami"
+        return build_exec(arguments) if name == "localvault_build_exec"
+        return required_argument_error("key") if name == "get_secret" && !present_string?(arguments["key"])
+        if name == "get_secret" && arguments["allow_plaintext"] != true
+          return error_result(
+            "Plaintext retrieval is blocked by default. For authentication or an external command, call " \
+            "localvault_build_exec instead. Retry get_secret with allow_plaintext=true only when the user " \
+            "explicitly needs the secret text or injection cannot complete the task."
+          )
+        end
+
         vault = vault_resolver.call(vault_name)
 
         unless vault
           hint = vault_name ? "localvault show -v #{vault_name}" : "localvault show"
-          return error_result("No unlocked vault session. Run: #{hint}")
+          return error_result("No unlocked vault session. Run `localvault mcp --check`, then unlock with: #{hint}")
         end
 
         case name
         when "get_secret"    then get_secret(arguments["key"], vault)
-        when "list_secrets"  then list_secrets(vault)
+        when "list_secrets"  then list_secrets(vault, prefix: arguments["prefix"], query: arguments["query"])
         when "set_secret"    then set_secret(arguments["key"], arguments["value"], vault)
         when "delete_secret" then delete_secret(arguments["key"], vault)
         end
+      rescue StandardError => e
+        error_result(e.message)
       end
 
       def self.get_secret(key, vault)
-        value = vault.get(key)
-        value.nil? ? error_result("Key '#{key}' not found") : text_result(value)
+        return required_argument_error("key") unless present_string?(key)
+
+        lookup = KeyLookup.lookup(vault, key)
+        return text_result(lookup.value) if lookup.exact?
+
+        if lookup.multiple_matches?
+          return error_result(candidate_message("Multiple keys match '#{key}'. Be more specific:", lookup.matches))
+        end
+
+        if lookup.single_match?
+          return error_result(candidate_message("Key '#{key}' not found. Did you mean:", lookup.matches))
+        end
+
+        error_result("Key '#{key}' not found")
       end
 
-      def self.list_secrets(vault)
+      def self.list_secrets(vault, prefix: nil, query: nil)
+        return string_argument_error("prefix") unless optional_string?(prefix)
+        return string_argument_error("query") unless optional_string?(query)
+
         keys = vault.list
-        keys.empty? ? text_result("No secrets stored") : text_result(keys.join("\n"))
+        keys = keys.select { |key| key.start_with?(prefix) } if prefix && !prefix.empty?
+        keys = keys.select { |key| key.downcase.include?(query.downcase) } if query && !query.empty?
+        result = keys.empty? ? text_result("No secrets stored") : text_result(keys.join("\n"))
+        result["content"] << {
+          "type" => "text",
+          "text" => "Next: call localvault_build_exec with command argv and optional only/project mappings. Do not copy secret values."
+        }
+        result
       end
 
       def self.set_secret(key, value, vault)
+        return required_argument_error("key") unless present_string?(key)
+        return required_argument_error("value") unless value.is_a?(String)
+
         vault.set(key, value)
         text_result("Stored #{key}")
-      rescue Vault::InvalidKeyName => e
-        error_result("Invalid key name: #{e.message}")
+      rescue Vault::InvalidKeyName, RuntimeError => e
+        error_result(e.message)
       end
 
       def self.delete_secret(key, vault)
+        return required_argument_error("key") unless present_string?(key)
+
         deleted = vault.delete(key)
         deleted.nil? ? error_result("Key '#{key}' not found") : text_result("Deleted #{key}")
       end
@@ -123,7 +226,60 @@ module LocalVault
         { "content" => [{ "type" => "text", "text" => text }], "isError" => true }
       end
 
-      private_class_method :get_secret, :list_secrets, :set_secret, :delete_secret, :text_result, :error_result
+      def self.whoami(status)
+        structured = status.merge("version" => LocalVault::VERSION)
+        text = [
+          "LocalVault #{LocalVault::VERSION}",
+          "Home: #{structured["localvault_home"]}",
+          "Active vault: #{structured["active_vault"]} (#{structured["active_vault_source"]})",
+          "Active vault unlocked: #{structured["active_vault_unlocked"] ? "yes" : "no"}",
+          "Session vault: #{structured["session_vault"] || "-"}",
+          "Unlocked vaults: #{structured["unlocked_vaults"].empty? ? "-" : structured["unlocked_vaults"].join(", ")}"
+        ].join("\n")
+
+        text_result(text).merge("structuredContent" => structured)
+      end
+
+      def self.build_exec(arguments)
+        result = ExecCommandBuilder.new(
+          command: arguments["command"],
+          vault: arguments["vault"],
+          project: arguments["project"],
+          only: arguments["only"],
+          except: arguments["except"],
+          map: arguments["map"],
+          profile: arguments["profile"]
+        ).build
+        text_result(
+          "Built command (not executed):\n#{result["command"]}\n\n#{result["next_action"]}"
+        ).merge("structuredContent" => result)
+      rescue InputValidation::InvalidInput => e
+        error_result(e.message)
+      end
+
+      def self.candidate_message(header, matches)
+        ([header] + matches.map { |match| "  #{match}" }).join("\n")
+      end
+
+      def self.present_string?(value)
+        value.is_a?(String) && !value.empty?
+      end
+
+      def self.optional_string?(value)
+        value.nil? || value.is_a?(String)
+      end
+
+      def self.required_argument_error(name)
+        error_result("Missing required argument '#{name}'")
+      end
+
+      def self.string_argument_error(name)
+        error_result("Argument '#{name}' must be a string")
+      end
+
+      private_class_method :get_secret, :list_secrets, :set_secret, :delete_secret, :build_exec,
+        :text_result, :error_result, :whoami, :candidate_message,
+        :present_string?, :optional_string?, :required_argument_error, :string_argument_error
     end
   end
 end

data/lib/localvault/session_cache.rb

@@ -1,6 +1,6 @@
 require "base64"
 require "fileutils"
-require "shellwords"
+require "open3"
 
 module LocalVault
   # Caches derived master keys to avoid re-prompting passphrase on every command.
@@ -95,8 +95,11 @@ module LocalVault
 
     def self.keychain_get(vault_name)
       if macos?
-        out = `security find-generic-password -a #{Shellwords.escape(vault_name)} -s #{Shellwords.escape(KEYCHAIN_SERVICE)} -w 2>/dev/null`.chomp
-        return out if $?.success? && !out.empty?
+        out = run_command(
+          ["security", "find-generic-password", "-a", vault_name, "-s", KEYCHAIN_SERVICE, "-w"],
+          timeout: 2
+        )
+        return out unless out.nil? || out.empty?
       end
       # File fallback (Linux, or macOS when Keychain unavailable)
       file = session_file(vault_name)
@@ -143,5 +146,28 @@ module LocalVault
       FileUtils.rm_f(session_file(vault_name))
     end
 
+    def self.run_command(argv, timeout:)
+      output = nil
+      Open3.popen3(*argv) do |stdin, stdout, stderr, wait_thread|
+        stdin.close
+        unless wait_thread.join(timeout)
+          Process.kill("TERM", wait_thread.pid)
+          unless wait_thread.join(0.1)
+            Process.kill("KILL", wait_thread.pid)
+            wait_thread.join
+          end
+          return nil
+        end
+
+        output = stdout.read.chomp if wait_thread.value.success?
+        stderr.close
+      rescue Errno::ESRCH
+        return nil
+      end
+      output
+    rescue Errno::ENOENT
+      nil
+    end
+
   end
 end