localvault 1.7.0 → 1.8.1

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

@@ -72,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 })

data/lib/localvault/mcp/tools.rb

@@ -1,6 +1,7 @@
 require "json"
 require_relative "../key_lookup"
 require_relative "../version"
+require_relative "exec_command_builder"
 
 module LocalVault
   module MCP
@@ -17,19 +18,21 @@ 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" => {
@@ -38,7 +41,37 @@ module LocalVault
               **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",
@@ -47,7 +80,8 @@ module LocalVault
             "type" => "object",
             "properties" => { **VAULT_PARAM },
             "required" => []
-          }
+          },
+          "annotations" => { "readOnlyHint" => true, "openWorldHint" => false }
         },
         {
           "name" => "set_secret",
@@ -60,6 +94,12 @@ module LocalVault
               **VAULT_PARAM
             },
             "required" => ["key", "value"]
+          },
+          "annotations" => {
+            "readOnlyHint" => false,
+            "destructiveHint" => true,
+            "idempotentHint" => false,
+            "openWorldHint" => false
           }
         },
         {
@@ -72,6 +112,12 @@ module LocalVault
               **VAULT_PARAM
             },
             "required" => ["key"]
+          },
+          "annotations" => {
+            "readOnlyHint" => false,
+            "destructiveHint" => true,
+            "idempotentHint" => true,
+            "openWorldHint" => false
           }
         }
       ].freeze
@@ -96,12 +142,21 @@ module LocalVault
 
         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
@@ -138,7 +193,12 @@ module LocalVault
         keys = vault.list
         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?
-        keys.empty? ? text_result("No secrets stored") : text_result(keys.join("\n"))
+        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)
@@ -180,6 +240,23 @@ module LocalVault
         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
@@ -200,7 +277,7 @@ module LocalVault
         error_result("Argument '#{name}' must be a string")
       end
 
-      private_class_method :get_secret, :list_secrets, :set_secret, :delete_secret,
+      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

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

data/lib/localvault/stdin_secret_input.rb

@@ -0,0 +1,22 @@
+module LocalVault
+  class StdinSecretInput
+    class InteractiveInput < StandardError; end
+    class InvalidEncoding < StandardError; end
+
+    PIPE_EXAMPLE = %(printf '%s' "$SECRET" | localvault set KEY --stdin).freeze
+
+    def self.read(input = $stdin)
+      if input.respond_to?(:tty?) && input.tty?
+        raise InteractiveInput, "Refusing to read secret from interactive stdin. " \
+          "Pipe it instead: #{PIPE_EXAMPLE}"
+      end
+
+      input.binmode if input.respond_to?(:binmode)
+      value = input.read || ""
+      value = value.dup.force_encoding(Encoding::UTF_8)
+      raise InvalidEncoding, "Secret value must be valid UTF-8" unless value.valid_encoding?
+
+      value
+    end
+  end
+end

data/lib/localvault/vault_resolver.rb

@@ -33,6 +33,17 @@ module LocalVault
       }
     end
 
+    def self.readiness_status(name = nil)
+      result = resolve(name)
+      {
+        "localvault_home" => Config.root_path,
+        "active_vault" => result.active_vault,
+        "active_vault_source" => result.active_vault_source,
+        "session_vault" => result.session_vault,
+        "active_vault_unlocked" => !result.vault.nil?
+      }
+    end
+
     def self.active_vault_name(name = nil)
       return [name, "argument"] if name && !name.empty?
       return [ENV["LOCALVAULT_VAULT"], "env"] if ENV["LOCALVAULT_VAULT"] && !ENV["LOCALVAULT_VAULT"].empty?

data/lib/localvault/version.rb

@@ -1,3 +1,3 @@
 module LocalVault
-  VERSION = "1.7.0"
+  VERSION = "1.8.1"
 end

data/lib/localvault.rb

@@ -5,6 +5,7 @@ require_relative "localvault/store"
 require_relative "localvault/env_projection"
 require_relative "localvault/key_lookup"
 require_relative "localvault/vault_resolver"
+require_relative "localvault/stdin_secret_input"
 require_relative "localvault/vault"
 require_relative "localvault/identity"
 require_relative "localvault/share_crypto"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: localvault
 version: !ruby/object:Gem::Version
-  version: 1.7.0
+  version: 1.8.1
 platform: ruby
 authors:
 - Nauman Tariq
@@ -108,6 +108,7 @@ files:
 - lib/localvault.rb
 - lib/localvault/api_client.rb
 - lib/localvault/cli.rb
+- lib/localvault/cli/error_presenter.rb
 - lib/localvault/cli/keys.rb
 - lib/localvault/cli/sync.rb
 - lib/localvault/cli/team.rb
@@ -115,13 +116,17 @@ files:
 - lib/localvault/config.rb
 - lib/localvault/crypto.rb
 - lib/localvault/env_projection.rb
+- lib/localvault/group_catalog.rb
 - lib/localvault/identity.rb
+- lib/localvault/input_validation.rb
 - lib/localvault/key_lookup.rb
 - lib/localvault/key_slot.rb
+- lib/localvault/mcp/exec_command_builder.rb
 - lib/localvault/mcp/server.rb
 - lib/localvault/mcp/tools.rb
 - lib/localvault/session_cache.rb
 - lib/localvault/share_crypto.rb
+- lib/localvault/stdin_secret_input.rb
 - lib/localvault/store.rb
 - lib/localvault/sync_bundle.rb
 - lib/localvault/sync_state.rb