localvault 1.6.1 → 1.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9cf502e2c11320a16bbf04e20ce1202d799d360775b664c1902c6ef337557302
-  data.tar.gz: 1504ab893d079a1308519a8dd9fdfd941560348fca5d92cc1548edd9f6bf6549
+  metadata.gz: 2ff1cbda409eb9a922e301dfb73866fde96fa06dc7ace9e670df15ef587dd336
+  data.tar.gz: 8f1b78e9c49e3f6f99a37cd97bbca36054e75c15d99d126699beb61f00a07840
 SHA512:
-  metadata.gz: 5aee20035eb1f290f95648c146b7a05f650f033d2f4cfa4ee4dbc565133031871607974c8c3eca58009bf1a3b5fff53ff11940c8841b476d281909d8d72d6ac4
-  data.tar.gz: d8a9f184fc3c636742293a74901d24e12c7c8d48191b1816824e90cf0d7162f670373e78dd54ecc4bc6ef7daffbe6e73f1e341fdb786b258ba7ef3d8ffc1a4da
+  metadata.gz: 35b625b3e4bd845ba5b5832016f4fd3f310b410e763c476a569c32920f8707317b007f00be9cbd441f704aeccf126d8c4d48646706cab7cc597d1e7fabc07d58
+  data.tar.gz: b509a7068ba88ea63e30ecb9c036c1b3b2d63d58da73cd0e2a812069f907ad8439d0ee1ae5d10d17ca7fb97595c0c420c02ab5f9fe151c96525f0c07b85c91d6

data/README.md

@@ -105,7 +105,6 @@ localvault exec -- rails server
 | `sync push [NAME]` | Push one vault to cloud |
 | `sync pull [NAME]` | Pull one vault from cloud (auto-unlocks if you have a key slot) |
 | `sync status` | Show sync state for all vaults |
-| `config set server URL` | Point at a custom server (default: inventlist.com) |
 
 ### Team Sharing (v1.3.0)
 
@@ -139,7 +138,7 @@ backward compatibility but the top-level forms are preferred.
 
 | Command | Description |
 |---------|-------------|
-| `install-mcp [CLIENT]` | Configure MCP server in claude-code, cursor, windsurf, or zed |
+| `install-mcp [CLIENT]` | Configure MCP server in claude-code, cursor, or windsurf |
 | `mcp` | Start MCP server (stdio transport) |
 
 All commands accept `--vault NAME` (or `-v NAME`) to target a specific vault. Default vault is `default`.
@@ -215,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
@@ -257,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
 ```
@@ -273,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
 
@@ -325,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/sync.rb

@@ -17,6 +17,7 @@ module LocalVault
       # - Both exist, only local changed → push
       # - Both exist, only remote changed → pull
       # - Both exist, neither changed → skip
+      # - Both exist, no baseline but secrets identical → adopt (record baseline)
       # - Both exist, both changed → CONFLICT (manual resolution)
       # - Shared vault (not owned by you) → pull-only
       def all
@@ -34,7 +35,7 @@ module LocalVault
           return
         end
 
-        plan = all_names.map { |name| classify_vault(name, local_set, remote_map, my_handle) }
+        plan = all_names.map { |name| classify_vault(name, local_set, remote_map, my_handle, client) }
 
         # Print plan
         max_name   = (["Vault"]  + plan.map { |p| p[:name] }).map(&:length).max
@@ -55,7 +56,7 @@ module LocalVault
         end
 
         # Execute
-        pushed = pulled = skipped = conflicts = errors = 0
+        pushed = pulled = skipped = adopted = conflicts = errors = 0
         plan.each do |entry|
           case entry[:action]
           when :push
@@ -70,6 +71,12 @@ module LocalVault
             else
               errors += 1
             end
+          when :adopt
+            if perform_adopt(entry[:name])
+              adopted += 1
+            else
+              errors += 1
+            end
           when :skip
             skipped += 1
           when :conflict
@@ -79,10 +86,11 @@ module LocalVault
 
         # Summary
         parts = []
-        parts << "#{pushed} pushed"     if pushed > 0
-        parts << "#{pulled} pulled"     if pulled > 0
+        parts << "#{pushed} pushed"      if pushed > 0
+        parts << "#{pulled} pulled"      if pulled > 0
+        parts << "#{adopted} baselined"  if adopted > 0
         parts << "#{skipped} up to date" if skipped > 0
-        parts << "#{errors} failed"     if errors > 0
+        parts << "#{errors} failed"      if errors > 0
         parts << "#{conflicts} conflict#{conflicts == 1 ? "" : "s"}" if conflicts > 0
         $stdout.puts "Summary: #{parts.join(", ")}"
 
@@ -292,8 +300,9 @@ module LocalVault
       # @param local_set [Set<String>] vaults that exist on disk
       # @param remote_map [Hash{String => Hash}] remote vault info keyed by name
       # @param my_handle [String] current user's InventList handle
+      # @param client [ApiClient] authenticated API client (used to hash remote secrets)
       # @return [Hash] +{name:, action:, reason:}+
-      def classify_vault(name, local_set, remote_map, my_handle)
+      def classify_vault(name, local_set, remote_map, my_handle, client)
         l_exists = local_set.include?(name)
         r_info   = remote_map[name]
         r_exists = !r_info.nil?
@@ -303,8 +312,25 @@ module LocalVault
         s_exists   = ss.exists?
         baseline   = ss.last_synced_checksum
 
-        local_checksum  = l_exists && store ? SyncState.local_checksum(store) : nil
-        remote_checksum = r_info&.dig("checksum")
+        local_checksum = l_exists && store ? SyncState.local_checksum(store) : nil
+
+        # The server's list `checksum` hashes the whole sync bundle, which lives
+        # in a different hash space than our baseline and +local_checksum+ (both
+        # SHA256 of the encrypted *secrets* bytes). Comparing across those spaces
+        # never matches, so it would flag every both-exist vault as changed or
+        # conflicting. To compare like-for-like we download the bundle and hash
+        # its secrets bytes — but only when both sides exist, since for local-only
+        # / remote-only vaults the direction is unambiguous and no compare is needed.
+        if l_exists && r_exists
+          begin
+            remote_checksum = remote_secrets_checksum(name, client)
+          rescue SyncBundle::UnpackError
+            # A corrupt/unparseable remote bundle must not be conflated with an
+            # empty vault (both would otherwise yield nil and could falsely
+            # "adopt"). Surface it as a conflict the user can inspect.
+            return { name: name, action: :conflict, reason: "remote bundle unreadable — cannot compare" }
+          end
+        end
 
         # Ownership
         owner_handle = r_info&.dig("owner_handle")
@@ -337,12 +363,14 @@ module LocalVault
         # Neither (shouldn't happen since we iterate union)
         return [:skip, "no data"] unless l_exists && r_exists
 
-        # Both exist — no baseline (first sync for this vault)
+        # Both exist — no baseline (first sync for this vault). Compare the
+        # secrets bytes directly: if they match, the sides are already in sync
+        # and we just record a baseline so future syncs can detect drift.
         unless s_exists
-          if local_cs == remote_cs || (local_cs.nil? && remote_cs.nil?)
-            return [:skip, "already in sync (first check)"]
+          if local_cs == remote_cs
+            return [:adopt, "in sync — recording baseline"]
           else
-            return [:conflict, "both exist, no sync baseline — cannot determine which side changed"]
+            return [:conflict, "both exist, no sync baseline — run 'sync push' or 'sync pull' to resolve"]
           end
         end
 
@@ -363,6 +391,45 @@ module LocalVault
 
       # ── Helpers ──────────────────────────────────────────────────
 
+      # Record a sync baseline for a vault whose local and remote secrets are
+      # already byte-identical, without transferring any data. Lets the next
+      # sync detect drift instead of re-comparing from scratch every time.
+      #
+      # @param vault_name [String] vault to baseline
+      # @return [Boolean] true on success, false on any error
+      def perform_adopt(vault_name)
+        store = Store.new(vault_name)
+        SyncState.new(vault_name).write!(
+          checksum: SyncState.local_checksum(store),
+          direction: "adopt"
+        )
+        $stdout.puts "  baselined #{vault_name} (already in sync)"
+        true
+      rescue StandardError => e
+        $stderr.puts "Error baselining '#{vault_name}': #{e.message}"
+        false
+      end
+
+      # SHA256 of a remote vault's encrypted secrets bytes — the same hash space
+      # as +SyncState.local_checksum+ and the stored baseline, so the two can be
+      # compared directly. Returns nil when the vault has no secrets (empty), is
+      # missing remotely (404), or the bundle can't be parsed.
+      #
+      # @param vault_name [String] vault to fetch
+      # @param client [ApiClient] authenticated API client
+      # @return [String, nil] hex digest of the remote secrets bytes, or nil if empty/missing
+      # @raise [SyncBundle::UnpackError] if the bundle exists but can't be parsed
+      def remote_secrets_checksum(vault_name, client)
+        blob = client.pull_vault(vault_name)
+        return nil unless blob.is_a?(String) && !blob.empty?
+        secrets = SyncBundle.unpack(blob)[:secrets]
+        return nil if secrets.nil? || secrets.empty?
+        Digest::SHA256.hexdigest(secrets)
+      rescue ApiClient::ApiError => e
+        raise unless e.status == 404
+        nil
+      end
+
       def try_unlock_via_key_slot(vault_name, key_slots)
         return false unless key_slots.is_a?(Hash) && !key_slots.empty?
         return false unless Identity.exists?

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/session_cache.rb

@@ -116,7 +116,11 @@ module LocalVault
         # Fall back to file store if Keychain fails (e.g., in CI or sandboxed env)
         unless success
           file = session_file(vault_name)
-          File.write(file, payload, perm: 0o600)
+          File.write(file, payload)
+          # chmod unconditionally: File.write's perm: only applies on creation,
+          # so an existing looser-mode file would otherwise keep its perms and
+          # leak the master key.
+          File.chmod(0o600, file)
         end
       else
         keychain_delete(vault_name)

data/lib/localvault/sync_bundle.rb

@@ -90,7 +90,7 @@ module LocalVault
     def self.unpack(blob, expected_name: nil)
       data = JSON.parse(blob)
       version = data["version"]
-      raise UnpackError, "Unsupported bundle version: #{version}" if version && !SUPPORTED_VERSIONS.include?(version)
+      raise UnpackError, "Unsupported bundle version: #{version.inspect}" unless SUPPORTED_VERSIONS.include?(version)
 
       meta_raw    = Base64.strict_decode64(data.fetch("meta"))
       secrets_raw = Base64.strict_decode64(data.fetch("secrets"))

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.1"
+  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.1
+  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: