localvault 1.6.2 → 1.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3fe9cdf4fe4857588507532f6478318a7b02cdc47487bbecbe7ce54715e69e33
-  data.tar.gz: 1be1af8d9476e1171895a0ba0677e206832de1386416cd5fb7e7060e7b8b85f5
+  metadata.gz: 2ff1cbda409eb9a922e301dfb73866fde96fa06dc7ace9e670df15ef587dd336
+  data.tar.gz: 8f1b78e9c49e3f6f99a37cd97bbca36054e75c15d99d126699beb61f00a07840
 SHA512:
-  metadata.gz: 500451ad18462b5380839eb06b031b83b3acb91872430855e07038896c392f9488934aaf1649bd311886890400aaef9c45a062d8503c6db0760a2927b56a1650
-  data.tar.gz: aa1aa1b764c2de50ab0c8fb425b14a77e05085f2224131c7f53dc1eaaccc9b80732f160716a1826ef479c0d9653e5451074ca585927a86630ef68a92f23b9b8c
+  metadata.gz: 35b625b3e4bd845ba5b5832016f4fd3f310b410e763c476a569c32920f8707317b007f00be9cbd441f704aeccf126d8c4d48646706cab7cc597d1e7fabc07d58
+  data.tar.gz: b509a7068ba88ea63e30ecb9c036c1b3b2d63d58da73cd0e2a812069f907ad8439d0ee1ae5d10d17ca7fb97595c0c420c02ab5f9fe151c96525f0c07b85c91d6

data/README.md

@@ -214,28 +214,30 @@ localvault remove @alice -v production --rotate
 
 ## MCP Server (AI Agents)
 
-Give AI agents safe secret access. Keys never appear in agent context or config files.
+Give AI agents controlled secret access without hardcoding credentials in MCP config. Exact `get_secret` calls can return secret values to the agent; fuzzy reads return candidate names only.
 
 ```bash
 # One-command install for Claude Code
 localvault install-mcp claude-code
-# Also supports: cursor, windsurf, zed
+# Also supports: cursor, windsurf
 
 # Unlock your vault for the session
 localvault unlock
 
 # MCP tools available to the agent:
-#   get_secret(key, vault?)      — read a secret
-#   list_secrets(vault?, prefix?) — list key names
+#   localvault_whoami             — diagnose active vault/session state
+#   get_secret(key, vault?)       — read an exact secret key
+#   list_secrets(vault?, prefix?, query?) — list/search key names
 #   set_secret(key, value, vault?) — store a secret
-#   delete_secret(key, vault?)   — remove a secret
+#   delete_secret(key, vault?)    — remove a secret
 ```
 
-**exec_action** — agent declares intent, LocalVault executes with secrets injected. The agent never sees the key:
+Command injection stays in the CLI. Use selectors, mappings, and profiles to keep subprocess envs scoped:
 
 ```bash
-localvault exec_action -- curl -s https://api.openai.com/v1/models \
-  -H "Authorization: Bearer $OPENAI_API_KEY"
+localvault exec --profile aws -- aws sts get-caller-identity
+localvault exec --only AWS_IAM.*,AWS_SES.* --except AWS_SES.smtp_password -- your-script
+localvault env --map AWS_IAM.access_key_id=AWS_ACCESS_KEY_ID
 ```
 
 ## Multi-Project Vaults
@@ -256,6 +258,10 @@ localvault show -p myapp -v work
 # Export one project
 eval $(localvault env -p myapp -v work)
 
+# Export all projects with project.key transformed to PROJECT__key
+localvault env -v work
+# → MYAPP__DATABASE_URL, API__DATABASE_URL
+
 # Bulk import
 localvault import .env --prefix myapp -v work
 ```
@@ -272,7 +278,7 @@ localvault get API_KEY
 localvault exec -- rails server
 ```
 
-Session lives in `LOCALVAULT_SESSION` — disappears when the terminal closes.
+Unlocking writes a derived key to `LOCALVAULT_SESSION` and also caches it with an 8-hour TTL in Keychain or LocalVault's file fallback so MCP and new terminals can reuse it until `localvault lock`.
 
 ## Security
 
@@ -324,7 +330,7 @@ localvault login --server https://vaulthost.example
 git clone https://github.com/inventlist/localvault.git
 cd localvault
 bundle install
-bundle exec rake test  # 463 tests, 918 assertions
+bundle exec rake test
 ```
 
 ## Used by

data/lib/localvault/cli.rb

@@ -2,7 +2,10 @@ require "thor"
 require "io/console"
 require "base64"
 require "lipgloss"
+require_relative "env_projection"
+require_relative "key_lookup"
 require_relative "session_cache"
+require_relative "vault_resolver"
 
 module LocalVault
   class CLI < Thor
@@ -146,28 +149,18 @@ module LocalVault
     DESC
     def get(key)
       vault = open_vault!
-      value = vault.get(key)
-
-      if value.nil?
-        # Fall back to case-insensitive substring match
-        all_keys = vault.list
-        matches  = all_keys.select { |k| k.downcase.include?(key.downcase) }
-
-        if matches.size == 1
-          value = vault.get(matches.first)
-          $stdout.puts value
-          return
-        elsif matches.size > 1
-          $stderr.puts "Error: Multiple keys match '#{key}'. Be more specific:"
-          matches.sort.each { |k| $stderr.puts "  #{k}" }
-          return
-        else
-          abort_with "Key '#{key}' not found in vault '#{vault.name}'"
-          return
-        end
+      lookup = KeyLookup.lookup(vault, key)
+
+      if lookup.exact?
+        $stdout.puts lookup.value
+      elsif lookup.single_match?
+        $stdout.puts vault.get(lookup.matches.first)
+      elsif lookup.multiple_matches?
+        $stderr.puts "Error: Multiple keys match '#{key}'. Be more specific:"
+        lookup.matches.each { |k| $stderr.puts "  #{k}" }
+      else
+        abort_with "Key '#{key}' not found in vault '#{vault.name}'"
       end
-
-      $stdout.puts value
     end
 
     desc "list", "List all secret keys in the vault"
@@ -231,13 +224,25 @@ module LocalVault
 \x05    eval $(localvault env -v intellectaco)
 \x05    # → export PLATEPOSE__DATABASE_URL=...  export INVENTLIST__DATABASE_URL=...
 
+      SCOPED EXPORTS:
+\x05    localvault env --only AWS_IAM.*
+\x05    localvault env --only AWS_IAM.*,AWS_SES.* --except AWS_SES.smtp_password
+\x05    localvault env --map AWS_IAM.access_key_id=AWS_ACCESS_KEY_ID
+\x05    localvault env --profile aws
+
       Use `localvault exec` to inject directly into a subprocess without eval.
     DESC
     method_option :project, aliases: "-p", type: :string, desc: "Export only this project group (no prefix)"
+    method_option :only, type: :string, desc: "Export only exact keys or namespaces (KEY,GROUP.*)"
+    method_option :except, type: :string, desc: "Exclude exact keys or namespaces after --only"
+    method_option :map, type: :string, desc: "Map vault keys to env vars (KEY=ENV_NAME)"
+    method_option :profile, type: :string, desc: "Apply a built-in env mapping profile (aws)"
     def env
       vault = open_vault!
       skip_warn = ->(k) { $stderr.puts "Warning: skipping unsafe key '#{k}'" }
-      $stdout.puts vault.export_env(project: options[:project], on_skip: skip_warn)
+      $stdout.puts vault.export_env(**env_projection_options(on_skip: skip_warn))
+    rescue EnvProjection::InvalidMapping, EnvProjection::UnknownProfile => e
+      abort_with e.message
     end
 
     desc "exec -- CMD", "Run a command with secrets injected as environment variables"
@@ -256,13 +261,24 @@ module LocalVault
       TEAM VAULT — all projects (keys prefixed to avoid collisions):
 \x05    localvault exec -v intellectaco -- your-script
 \x05    # → PLATEPOSE__DATABASE_URL, INVENTLIST__DATABASE_URL, etc.
+
+      SCOPED INJECTION:
+\x05    localvault exec --only AWS_IAM.* -- aws sts get-caller-identity
+\x05    localvault exec --profile aws -- aws s3 ls
+\x05    localvault exec --map AWS_IAM.access_key_id=AWS_ACCESS_KEY_ID -- env
     DESC
     method_option :project, aliases: "-p", type: :string, desc: "Inject only this project group (no prefix)"
+    method_option :only, type: :string, desc: "Inject only exact keys or namespaces (KEY,GROUP.*)"
+    method_option :except, type: :string, desc: "Exclude exact keys or namespaces after --only"
+    method_option :map, type: :string, desc: "Map vault keys to env vars (KEY=ENV_NAME)"
+    method_option :profile, type: :string, desc: "Apply a built-in env mapping profile (aws)"
     def exec(*cmd)
       vault = open_vault!
       skip_warn = ->(k) { $stderr.puts "Warning: skipping unsafe key '#{k}'" }
-      env_vars = vault.env_hash(project: options[:project], on_skip: skip_warn)
+      env_vars = vault.env_hash(**env_projection_options(on_skip: skip_warn))
       Kernel.exec(env_vars, *cmd)
+    rescue EnvProjection::InvalidMapping, EnvProjection::UnknownProfile => e
+      abort_with e.message
     end
 
     desc "vaults", "List all vaults with secret counts"
@@ -466,8 +482,10 @@ module LocalVault
         cursor        Adds to ~/.cursor/mcp.json
         windsurf      Adds to ~/.codeium/windsurf/mcp_config.json
 
-      The MCP server uses whichever vault is your current default (localvault switch).
-      Unlock the vault once with `localvault show`, then the AI tool picks it up via Keychain.
+      The MCP server uses the same active vault rules as the CLI: explicit vault,
+      then LOCALVAULT_VAULT, then the configured default from `localvault switch`.
+      Unlock with `localvault show` or `localvault unlock`; `localvault lock`
+      revokes access without restarting the AI tool.
     DESC
     def install_mcp(client = "claude-code")
       case client.downcase
@@ -1514,7 +1532,18 @@ module LocalVault
     end
 
     def resolve_vault_name
-      options[:vault] || Config.default_vault
+      VaultResolver.active_vault_name(options[:vault]).first
+    end
+
+    def env_projection_options(on_skip:)
+      {
+        project: options[:project],
+        only: options[:only],
+        except: options[:except],
+        map: options[:map],
+        profile: options[:profile],
+        on_skip: on_skip
+      }
     end
 
     def open_vault_by_name!(vault_name)

data/lib/localvault/env_projection.rb

@@ -0,0 +1,131 @@
+module LocalVault
+  module EnvProjection
+    class InvalidMapping < StandardError; end
+    class UnknownProfile < StandardError; end
+
+    Entry = Struct.new(:key, :env_name, :value, keyword_init: true)
+
+    ENV_NAME_PATTERN = /\A[A-Za-z_][A-Za-z0-9_]*\z/
+
+    PROFILES = {
+      "aws" => {
+        only: ["AWS_IAM.*"],
+        map: {
+          "AWS_IAM.access_key_id" => "AWS_ACCESS_KEY_ID",
+          "AWS_IAM.secret_access_key" => "AWS_SECRET_ACCESS_KEY",
+          "AWS_IAM.session_token" => "AWS_SESSION_TOKEN"
+        }
+      }
+    }.freeze
+
+    def self.entries(secrets, project: nil, only: nil, except: nil, map: nil, profile: nil, on_skip: nil)
+      profile_config = profile_config(profile)
+      selectors = parse_selectors(only) || profile_config[:only]
+      exclusions = parse_selectors(except) || []
+      mappings = profile_config[:map].merge(parse_map(map))
+
+      flatten(secrets, project: project, on_skip: on_skip)
+        .select { |entry| include_entry?(entry.key, selectors) }
+        .reject { |entry| selector_match?(entry.key, exclusions) }
+        .map { |entry| apply_mapping(entry, mappings, on_skip: on_skip) }
+        .compact
+    end
+
+    def self.parse_selectors(value)
+      values = Array(value).compact.flat_map { |v| v.to_s.split(",") }
+      selectors = values.map(&:strip).reject(&:empty?)
+      selectors.empty? ? nil : selectors
+    end
+
+    def self.parse_map(value)
+      Array(value).compact.flat_map { |v| v.to_s.split(",") }.each_with_object({}) do |pair, hash|
+        next if pair.strip.empty?
+
+        key, env_name = pair.split("=", 2).map(&:strip)
+        raise InvalidMapping, "Invalid map '#{pair}'. Use KEY=ENV_NAME" if key.to_s.empty? || env_name.to_s.empty?
+        raise InvalidMapping, "Invalid environment variable name '#{env_name}'" unless safe_env_name?(env_name)
+
+        hash[key] = env_name
+      end
+    end
+
+    def self.profile_config(profile)
+      return { only: nil, map: {} } if profile.nil? || profile.to_s.empty?
+
+      PROFILES.fetch(profile.to_s) do
+        raise UnknownProfile, "Unknown env profile '#{profile}'"
+      end
+    end
+
+    def self.flatten(secrets, project:, on_skip:)
+      if project
+        group = secrets[project]
+        return [] unless group.is_a?(Hash)
+
+        group.filter_map do |key, value|
+          if safe_env_name?(key)
+            Entry.new(key: key, env_name: key, value: value.to_s)
+          else
+            on_skip&.call(key)
+            nil
+          end
+        end
+      else
+        secrets.flat_map do |key, value|
+          if value.is_a?(Hash)
+            flatten_group(key, value, on_skip: on_skip)
+          elsif safe_env_name?(key)
+            [Entry.new(key: key, env_name: key, value: value.to_s)]
+          else
+            on_skip&.call(key)
+            []
+          end
+        end
+      end
+    end
+
+    def self.flatten_group(group, pairs, on_skip:)
+      unless safe_env_name?(group)
+        on_skip&.call(group)
+        return []
+      end
+
+      pairs.filter_map do |key, value|
+        if safe_env_name?(key)
+          Entry.new(key: "#{group}.#{key}", env_name: "#{group.upcase}__#{key}", value: value.to_s)
+        else
+          on_skip&.call("#{group}.#{key}")
+          nil
+        end
+      end
+    end
+
+    def self.include_entry?(key, selectors)
+      selectors.nil? || selector_match?(key, selectors)
+    end
+
+    def self.selector_match?(key, selectors)
+      selectors.any? do |selector|
+        if selector.end_with?(".*")
+          key.start_with?("#{selector.delete_suffix(".*")}.")
+        else
+          key == selector
+        end
+      end
+    end
+
+    def self.apply_mapping(entry, mappings, on_skip:)
+      mapped_name = mappings.fetch(entry.key, entry.env_name)
+      unless safe_env_name?(mapped_name)
+        on_skip&.call(entry.key)
+        return nil
+      end
+
+      Entry.new(key: entry.key, env_name: mapped_name, value: entry.value)
+    end
+
+    def self.safe_env_name?(name)
+      name.is_a?(String) && name.match?(ENV_NAME_PATTERN)
+    end
+  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/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
@@ -85,7 +84,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 +98,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,6 @@
 require "json"
+require_relative "../key_lookup"
+require_relative "../version"
 
 module LocalVault
   module MCP
@@ -28,6 +30,19 @@ module LocalVault
         {
           "name" => "list_secrets",
           "description" => "List all secret keys in a localvault vault",
+          "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" => []
+          }
+        },
+        {
+          "name" => "localvault_whoami",
+          "description" => "Show which localvault home, vault, and unlocked sessions the MCP server can see",
           "inputSchema" => {
             "type" => "object",
             "properties" => { **VAULT_PARAM },
@@ -72,12 +87,16 @@ 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"
+
         vault = vault_resolver.call(vault_name)
 
         unless vault
@@ -87,30 +106,54 @@ module LocalVault
 
         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 = 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"))
       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 +166,43 @@ 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.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,
+        :text_result, :error_result, :whoami, :candidate_message,
+        :present_string?, :optional_string?, :required_argument_error, :string_argument_error
     end
   end
 end

data/lib/localvault/vault.rb

@@ -1,5 +1,6 @@
 require "json"
 require "shellwords"
+require_relative "env_projection"
 
 module LocalVault
   # Encrypted key-value store backed by a single JSON blob.
@@ -143,44 +144,15 @@ module LocalVault
     # @example
     #   vault.export_env(project: "myapp")
     #   # => "export DB_URL=postgres%3A//..."
-    def export_env(project: nil, on_skip: nil)
-      secrets = all
-      if project
-        group = secrets[project]
-        return "" unless group.is_a?(Hash)
-        group.filter_map do |k, v|
-          if shell_safe_key?(k)
-            "export #{k}=#{Shellwords.escape(v.to_s)}"
-          else
-            on_skip&.call(k)
-            nil
-          end
-        end.join("\n")
-      else
-        secrets.flat_map do |k, v|
-          if v.is_a?(Hash)
-            unless shell_safe_key?(k)
-              on_skip&.call(k)
-              next []
-            end
-            v.filter_map do |sk, sv|
-              if shell_safe_key?(sk)
-                "export #{k.upcase}__#{sk}=#{Shellwords.escape(sv.to_s)}"
-              else
-                on_skip&.call("#{k}.#{sk}")
-                nil
-              end
-            end
-          else
-            if shell_safe_key?(k)
-              ["export #{k}=#{Shellwords.escape(v.to_s)}"]
-            else
-              on_skip&.call(k)
-              []
-            end
-          end
-        end.join("\n")
-      end
+    def export_env(project: nil, on_skip: nil, only: nil, except: nil, map: nil, profile: nil)
+      EnvProjection.entries(all,
+        project: project,
+        only: only,
+        except: except,
+        map: map,
+        profile: profile,
+        on_skip: on_skip
+      ).map { |entry| "export #{entry.env_name}=#{Shellwords.escape(entry.value)}" }.join("\n")
     end
 
     # Returns a flat hash suitable for env injection.
@@ -195,40 +167,16 @@ module LocalVault
     # @example
     #   vault.env_hash(project: "myapp")
     #   # => {"DB_URL" => "postgres://...", "SECRET" => "abc"}
-    def env_hash(project: nil, on_skip: nil)
-      secrets = all
-      if project
-        group = secrets[project]
-        return {} unless group.is_a?(Hash)
-        group.each_with_object({}) do |(k, v), h|
-          if shell_safe_key?(k)
-            h[k] = v.to_s
-          else
-            on_skip&.call(k)
-          end
-        end
-      else
-        secrets.each_with_object({}) do |(k, v), h|
-          if v.is_a?(Hash)
-            unless shell_safe_key?(k)
-              on_skip&.call(k)
-              next
-            end
-            v.each do |sk, sv|
-              if shell_safe_key?(sk)
-                h["#{k.upcase}__#{sk}"] = sv.to_s
-              else
-                on_skip&.call("#{k}.#{sk}")
-              end
-            end
-          else
-            if shell_safe_key?(k)
-              h[k] = v.to_s
-            else
-              on_skip&.call(k)
-            end
-          end
-        end
+    def env_hash(project: nil, on_skip: nil, only: nil, except: nil, map: nil, profile: nil)
+      EnvProjection.entries(all,
+        project: project,
+        only: only,
+        except: except,
+        map: map,
+        profile: profile,
+        on_skip: on_skip
+      ).each_with_object({}) do |entry, hash|
+        hash[entry.env_name] = entry.value
       end
     end
 

data/lib/localvault/vault_resolver.rb

@@ -0,0 +1,81 @@
+require "base64"
+
+module LocalVault
+  module VaultResolver
+    Result = Struct.new(:vault, :active_vault, :active_vault_source, :session_vault, keyword_init: true)
+
+    def self.resolve(name = nil)
+      active_vault, source = active_vault_name(name)
+      session_name, session_key = session_credentials
+
+      if session_name == active_vault && session_key
+        vault = build_vault(active_vault, session_key)
+        return Result.new(vault: vault, active_vault: active_vault, active_vault_source: source, session_vault: session_name) if vault
+      end
+
+      if (master_key = SessionCache.get(active_vault))
+        vault = build_vault(active_vault, master_key)
+        return Result.new(vault: vault, active_vault: active_vault, active_vault_source: source, session_vault: session_name) if vault
+      end
+
+      Result.new(vault: nil, active_vault: active_vault, active_vault_source: source, session_vault: session_name)
+    end
+
+    def self.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,
+        "unlocked_vaults" => unlocked_vault_names,
+        "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?
+
+      [Config.default_vault, "config"]
+    end
+
+    def self.session_vault_name
+      session_credentials.first
+    end
+
+    def self.unlocked_vault_names
+      names = []
+      session_name, session_key = session_credentials
+      names << session_name if session_name && session_key && build_vault(session_name, session_key)
+
+      Store.list_vaults.each do |vault_name|
+        next if names.include?(vault_name)
+        names << vault_name if SessionCache.get(vault_name)
+      end
+
+      names.sort
+    end
+
+    def self.session_credentials
+      token = ENV["LOCALVAULT_SESSION"]
+      return [nil, nil] unless token
+
+      decoded = Base64.strict_decode64(token)
+      vault_name, key_b64 = decoded.split(":", 2)
+      return [nil, nil] unless vault_name && key_b64
+
+      [vault_name, Base64.strict_decode64(key_b64)]
+    rescue ArgumentError
+      [nil, nil]
+    end
+
+    def self.build_vault(name, master_key)
+      vault = Vault.new(name: name, master_key: master_key)
+      vault.all
+      vault
+    rescue Crypto::DecryptionError, Store::InvalidVaultName
+      nil
+    end
+  end
+end

data/lib/localvault/version.rb

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

data/lib/localvault.rb

@@ -2,6 +2,9 @@ require_relative "localvault/version"
 require_relative "localvault/crypto"
 require_relative "localvault/config"
 require_relative "localvault/store"
+require_relative "localvault/env_projection"
+require_relative "localvault/key_lookup"
+require_relative "localvault/vault_resolver"
 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.6.2
+  version: 1.7.0
 platform: ruby
 authors:
 - Nauman Tariq
@@ -114,7 +114,9 @@ files:
 - lib/localvault/cli/team_helpers.rb
 - lib/localvault/config.rb
 - lib/localvault/crypto.rb
+- lib/localvault/env_projection.rb
 - lib/localvault/identity.rb
+- lib/localvault/key_lookup.rb
 - lib/localvault/key_slot.rb
 - lib/localvault/mcp/server.rb
 - lib/localvault/mcp/tools.rb
@@ -124,6 +126,7 @@ files:
 - lib/localvault/sync_bundle.rb
 - lib/localvault/sync_state.rb
 - lib/localvault/vault.rb
+- lib/localvault/vault_resolver.rb
 - lib/localvault/version.rb
 homepage: https://github.com/inventlist/localvault
 licenses: