localvault 1.8.1 → 1.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a7cdca7447f0efeb125773a3385a6e3beee17cb03d4c05e04b91dc59254215dd
-  data.tar.gz: b3378c85ad59e00561d5eb5f590e203469d86f8c88925e7b547721717175f5a4
+  metadata.gz: f49d7a925b997780d6d03a2b071117e20da0827d24331d28c9cd5043a70b0056
+  data.tar.gz: 27b2be6fa5bb90d3df68eec4a27fcba483a175b574afd96f7aeba7dd0e175412
 SHA512:
-  metadata.gz: 2e4409c50f9aa0350b86541e905703ed24520cd583498d49de11a320cda8b6c2ebf86bc14c377bed52cd83438ba2254b0e243d91ffcf5521f7f84d9445072e1c
-  data.tar.gz: 97ff4555610dc166e82d01b6f11200ce516d0d36acb701625519c73b6e2f31d9096ae53e19d863128246d240d54eb82ebbd6f60ed51309ef4a8ec45675b144fd
+  metadata.gz: 7863c066d383db0a2ad4a98ae9665fe1fafc04de61b1fdbfec590d4af0ea04e47f31f1635a4c63d5886f0f71780a5f9f0ebd143348af23d404415991487dd214
+  data.tar.gz: b61cb7b5096ad2250560a1462f87ecfd81e538ed823971c46fe4820be3bb50443574055e40d0e080c7f4e5f7b7ce93d2d2f9cceedd03ea4f39a9a13141f35c44

data/README.md

@@ -145,6 +145,9 @@ backward compatibility but the top-level forms are preferred.
 | `install-mcp [CLIENT]` | Configure MCP server in claude-code, cursor, or windsurf |
 | `mcp` | Start MCP server (stdio transport) |
 | `doctor` | Check install and PATH readiness, including brew/asdf shadowing |
+| `guard install` | Install Claude Code hooks that block secrets in agent commands (v1.9.0) |
+| `guard status` | Show guard hook installation state |
+| `guard hook` | Hook entrypoint (reads hook JSON on stdin; not run by hand) |
 
 All commands accept `--vault NAME` (or `-v NAME`) to target a specific vault. Default vault is `default`.
 
@@ -310,6 +313,39 @@ Unlocking writes a derived key to `LOCALVAULT_SESSION` and also caches it with a
 
 ## Security
 
+### Agent Plaintext Containment (v1.9.0)
+
+Two layers keep secrets out of AI agent context and transcripts:
+
+**1. Plaintext refuses captured streams.** `get`, `env`, and `show --reveal`
+print values to an interactive terminal as always. When stdout is captured
+(a pipe or an agent's shell), a human confirms with one keypress on `/dev/tty`;
+an agent's shell has no `/dev/tty`, so it is refused and pointed at injection:
+
+```bash
+localvault get STRIPE_KEY              # human at a terminal: prints
+localvault get STRIPE_KEY | pbcopy     # human piping: "Print plaintext? [y/N]"
+# agent shell: refused → use localvault exec --map STRIPE_KEY=STRIPE_KEY -- CMD
+```
+
+There is deliberately no flag or environment variable to bypass this — the only
+override is a keypress on a real terminal. Headless automation uses
+`localvault exec` injection.
+
+**2. Guard hooks block secrets in agent commands.** `localvault guard install`
+wires Claude Code hooks that scan every Bash tool call against your unlocked
+vaults. A command containing a stored secret value is blocked before it runs,
+naming the key by fingerprint — never by value:
+
+```text
+LocalVault guard: blocked — this tool input contains the plaintext value of
+default/STRIPE.private_key (sha256:1a2b3c4d5e6f). Inject it instead:
+  localvault exec --map STRIPE.private_key=PRIVATE_KEY -- your-command
+```
+
+The installed hook fails open: locked vaults, an old binary, or a missing
+install allow the call rather than breaking your session.
+
 ### Crypto Stack
 
 | Layer | Algorithm | Purpose |

data/lib/localvault/cli/guard.rb

@@ -0,0 +1,87 @@
+require "thor"
+require "json"
+require "fileutils"
+require_relative "../guard"
+
+module LocalVault
+  class CLI
+    class Guard < Thor
+      desc "hook", "Claude Code hook entrypoint (reads hook JSON on stdin)"
+      long_desc <<~DESC
+        Reads a Claude Code PreToolUse/PostToolUse event on stdin. Blocks tool
+        calls whose input contains a stored plaintext secret value from any
+        session-unlocked vault, naming the key by fingerprint — never by value.
+        Fails open on any error so a broken guard cannot block all work.
+      DESC
+      def hook
+        event = JSON.parse($stdin.read)
+        result = LocalVault::Guard.evaluate(event)
+        if result[:exit] != 0
+          $stderr.puts result[:message]
+          exit result[:exit]
+        end
+      rescue StandardError
+        # fail open
+      end
+
+      desc "install", "Install the guard hooks into Claude Code settings"
+      method_option :project, type: :boolean, default: false,
+        desc: "Install into ./.claude/settings.json instead of ~/.claude/settings.json"
+      def install
+        path = settings_path(options[:project])
+        settings = File.exist?(path) ? JSON.parse(File.read(path)) : {}
+        if LocalVault::Guard.merge_hooks!(settings)
+          FileUtils.mkdir_p(File.dirname(path))
+          File.write(path, JSON.pretty_generate(settings) + "\n")
+          $stdout.puts "Installed LocalVault guard hooks in #{path}"
+          $stdout.puts "Restart Claude Code sessions to pick up hook changes."
+        else
+          $stdout.puts "LocalVault guard hooks already installed in #{path}"
+        end
+        warn_if_path_binary_lacks_guard
+      rescue JSON::ParserError
+        $stderr.puts "Error: #{path} is not valid JSON; fix it before installing."
+      end
+
+      desc "status", "Show guard hook installation status"
+      def status
+        { "user" => settings_path(false), "project" => settings_path(true) }.each do |label, path|
+          state = if !File.exist?(path)
+            "not installed"
+          else
+            begin
+              LocalVault::Guard.installed?(JSON.parse(File.read(path))) ? "installed" : "not installed"
+            rescue JSON::ParserError
+              "unreadable JSON"
+            end
+          end
+          $stdout.puts "#{label} (#{path}): #{state}"
+        end
+      end
+
+      no_commands do
+        # The installed hook wraps the entrypoint to fail open, so an old or
+        # missing PATH binary never breaks the user's sessions — but it also
+        # silently guards nothing, which deserves a loud note at install time.
+        def warn_if_path_binary_lacks_guard
+          help_output = `localvault help 2>/dev/null`
+          return if help_output.include?("guard")
+
+          $stderr.puts "Note: the `localvault` on your PATH does not support `guard hook` " \
+                       "(old version or different install). The hook fails open and guards " \
+                       "nothing until you upgrade: brew upgrade localvault"
+        rescue StandardError
+          nil
+        end
+
+        def settings_path(project)
+          if project
+            File.join(Dir.pwd, ".claude", "settings.json")
+          else
+            File.join(Dir.home, ".claude", "settings.json")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/localvault/cli.rb

@@ -4,6 +4,7 @@ require "base64"
 require "lipgloss"
 require_relative "env_projection"
 require_relative "key_lookup"
+require_relative "plaintext_output"
 require_relative "session_cache"
 require_relative "stdin_secret_input"
 require_relative "vault_resolver"
@@ -292,9 +293,9 @@ module LocalVault
       lookup = KeyLookup.lookup(vault, key)
 
       if lookup.exact?
-        $stdout.puts lookup.value
+        print_plaintext(key, lookup.value)
       elsif lookup.single_match?
-        $stdout.puts vault.get(lookup.matches.first)
+        print_plaintext(lookup.matches.first, 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}" }
@@ -403,6 +404,15 @@ module LocalVault
     method_option :profile, type: :string, desc: "Apply a built-in env mapping profile (aws)"
     def env
       vault = open_vault!
+      unless PlaintextOutput.permitted?(purpose: "Export plaintext values")
+        abort_with <<~MSG.strip
+          refusing to print plaintext env exports: stdout is a captured stream, not an interactive terminal.
+          Use process-scoped injection instead:
+            localvault exec [--only KEYS|--map KEY=ENV_NAME|--profile aws] -- your-command
+          A human at a terminal is asked to confirm; agents and CI must use injection.
+        MSG
+        return
+      end
       skip_warn = ->(k) { $stderr.puts "Warning: skipping unsafe key '#{k}'" }
       $stdout.puts vault.export_env(**env_projection_options(on_skip: skip_warn))
     rescue EnvProjection::InvalidMapping, EnvProjection::UnknownProfile => e
@@ -520,6 +530,7 @@ module LocalVault
     def show
       vault = open_vault!
       secrets = vault.all
+      reveal = options[:reveal] && reveal_permitted?
 
       named_group_query = options[:group] && ![GROUP_ALL_SENTINEL, GROUP_OFF_SENTINEL].include?(options[:group])
       if secrets.empty? && !named_group_query
@@ -533,21 +544,21 @@ module LocalVault
           abort_with "No project '#{options[:project]}' in vault '#{vault.name}'"
           return
         end
-        render_table(group.sort.to_h, "#{vault.name}/#{options[:project]}", reveal: options[:reveal])
+        render_table(group.sort.to_h, "#{vault.name}/#{options[:project]}", reveal: reveal)
       elsif options[:group] && ![GROUP_ALL_SENTINEL, GROUP_OFF_SENTINEL].include?(options[:group])
         match = GroupCatalog.new(secrets).resolve(options[:group])
         if match.group
           entries = match.group.entries.to_h { |entry| [entry.label, entry.value] }
-          render_table(entries, "#{vault.name}/#{match.group.name}", reveal: options[:reveal])
+          render_table(entries, "#{vault.name}/#{match.group.name}", reveal: reveal)
         elsif match.kind == :ambiguous
           raise GroupSelectionError.new(:ambiguous, query: options[:group], candidates: match.groups.map(&:name))
         else
           raise GroupSelectionError.new(:absent, query: options[:group])
         end
       elsif options[:group] != GROUP_OFF_SENTINEL && (options[:group] || secrets.values.any? { |v| v.is_a?(Hash) })
-        render_grouped_table(secrets, vault.name, reveal: options[:reveal])
+        render_grouped_table(secrets, vault.name, reveal: reveal)
       else
-        render_table(secrets.sort.to_h, vault.name, reveal: options[:reveal])
+        render_table(secrets.sort.to_h, vault.name, reveal: reveal)
       end
     end
 
@@ -754,7 +765,9 @@ module LocalVault
     require_relative "cli/keys"
     require_relative "cli/team"
     require_relative "cli/sync"
+    require_relative "cli/guard"
 
+    register(Guard, "guard", "guard SUBCOMMAND", "Block plaintext secrets in agent tool traffic (Claude Code hooks)")
     register(Keys, "keys", "keys SUBCOMMAND", "Manage your X25519 keypair for vault sharing")
     register(Team, "team", "team SUBCOMMAND", "Manage vault team access")
     register(Sync, "sync", "sync SUBCOMMAND", "Sync vaults to InventList cloud")
@@ -1915,6 +1928,29 @@ module LocalVault
       $stderr.puts "Error: #{message}"
     end
 
+    # --- plaintext gating (see docs/plans/07-agent-plaintext-containment.md) ---
+
+    def print_plaintext(key, value)
+      unless PlaintextOutput.permitted?(purpose: "Print plaintext value of '#{key}'")
+        env_name = key.split(".").last.upcase
+        abort_with <<~MSG.strip
+          refusing to print plaintext for '#{key}': stdout is a captured stream, not an interactive terminal.
+          Use process-scoped injection instead:
+            localvault exec --map #{key}=#{env_name} -- your-command
+          A human at a terminal is asked to confirm; agents and CI must use injection.
+        MSG
+        return
+      end
+      $stdout.puts value
+    end
+
+    def reveal_permitted?
+      return true if PlaintextOutput.permitted?(purpose: "Reveal plaintext values")
+
+      $stderr.puts "Masking values: stdout is a captured stream. Use `localvault exec` for injection."
+      false
+    end
+
     # --- install-mcp helpers ---
 
     # Claude Code: use `claude mcp add --scope user` so the server is

data/lib/localvault/guard.rb

@@ -0,0 +1,148 @@
+require "json"
+require "digest"
+require_relative "store"
+require_relative "session_cache"
+
+module LocalVault
+  # Scans agent tool traffic (Claude Code hook events) for stored plaintext
+  # secret values, so a value already in an agent's context — retrieved or
+  # freshly generated, once stored — can never pass through a command line
+  # unnoticed.
+  #
+  # Failure posture is fail-open: locked vaults, unreadable stores, and
+  # malformed events all allow the tool call. A locked vault cannot have fed
+  # values into the session, and a guard that blocks all work when it cannot
+  # check gets uninstalled.
+  module Guard
+    MIN_VALUE_LENGTH = 8
+    HOOK_ENTRYPOINT = "localvault guard hook".freeze
+    # The installed command must fail open on machines where the binary is
+    # old, missing, or broken — otherwise every Bash call errors for users
+    # whose settings outlive their localvault install. Only a genuine deny
+    # (exit 2) is allowed through; every other exit becomes a silent allow.
+    HOOK_COMMAND = %(sh -c 'out=$(#{HOOK_ENTRYPOINT} 2>&1); s=$?; if [ $s -eq 2 ]; then echo "$out" >&2; exit 2; fi; exit 0').freeze
+    HOOK_EVENTS = %w[PreToolUse PostToolUse].freeze
+    ALLOW = { exit: 0, message: nil }.freeze
+
+    Match = Struct.new(:vault, :key, :fingerprint, keyword_init: true)
+
+    # Plaintext values from every session-unlocked vault.
+    #
+    # @return [Array<Hash>] entries with :vault, :key, :value
+    def self.unlocked_secrets
+      Store.list_vaults.flat_map do |name|
+        master_key = SessionCache.get(name)
+        next [] unless master_key
+
+        begin
+          vault = Vault.new(name: name, master_key: master_key)
+          flatten(vault.all).map { |key, value| { vault: name, key: key, value: value } }
+        rescue StandardError
+          []
+        end
+      end
+    end
+
+    def self.flatten(hash, prefix = nil)
+      hash.each_with_object({}) do |(k, v), out|
+        key = prefix ? "#{prefix}.#{k}" : k.to_s
+        if v.is_a?(Hash)
+          out.merge!(flatten(v, key))
+        else
+          out[key] = v.to_s
+        end
+      end
+    end
+
+    # @return [Array<Match>] stored secret values appearing in +text+
+    def self.scan(text, secrets = unlocked_secrets)
+      return [] if text.nil? || text.empty?
+
+      secrets.filter_map do |entry|
+        value = entry[:value]
+        next if value.nil? || value.length < MIN_VALUE_LENGTH
+        next unless text.include?(value)
+
+        Match.new(vault: entry[:vault], key: entry[:key], fingerprint: fingerprint(value))
+      end
+    end
+
+    def self.fingerprint(value)
+      Digest::SHA256.hexdigest(value)[0, 12]
+    end
+
+    def self.strings_in(node)
+      case node
+      when String then [node]
+      when Hash then node.values.flat_map { |v| strings_in(v) }
+      when Array then node.flat_map { |v| strings_in(v) }
+      else []
+      end
+    end
+
+    # Evaluate a parsed Claude Code hook event.
+    #
+    # @return [Hash] +{exit: Integer, message: String|nil}+ — exit 2 blocks a
+    #   PreToolUse call / surfaces a PostToolUse warning to the agent
+    def self.evaluate(event, secrets = unlocked_secrets)
+      case event["hook_event_name"]
+      when "PreToolUse"
+        matches = scan(strings_in(event["tool_input"]).join("\n"), secrets)
+        matches.empty? ? ALLOW : { exit: 2, message: deny_message(matches) }
+      when "PostToolUse"
+        matches = scan(strings_in(event["tool_response"]).join("\n"), secrets)
+        matches.empty? ? ALLOW : { exit: 2, message: exposure_message(matches) }
+      else
+        ALLOW
+      end
+    rescue StandardError
+      ALLOW
+    end
+
+    def self.deny_message(matches)
+      first = matches.first
+      env_name = first.key.split(".").last.upcase
+      <<~MSG.strip
+        LocalVault guard: blocked — this tool input contains the plaintext value of #{name_list(matches)}.
+        Never place secret values in commands or arguments. Inject them instead:
+          localvault exec --map #{first.key}=#{env_name} -- your-command
+        or pipe a new value with: printf '%s' "$VALUE" | localvault set KEY --stdin
+      MSG
+    end
+
+    def self.exposure_message(matches)
+      <<~MSG.strip
+        LocalVault guard: this command's output contained the plaintext value of #{name_list(matches)} and has entered the transcript.
+        Treat the value as exposed: rotate it, then store the replacement via --stdin.
+        Avoid commands that print secrets; use scoped injection (localvault exec --only/--map).
+      MSG
+    end
+
+    def self.name_list(matches)
+      matches.map { |m| "#{m.vault}/#{m.key} (sha256:#{m.fingerprint})" }.join(", ")
+    end
+
+    # Idempotently add the guard hook entries to a Claude Code settings hash.
+    #
+    # @return [Boolean] whether the settings were modified
+    def self.merge_hooks!(settings)
+      changed = false
+      hooks = settings["hooks"] ||= {}
+      HOOK_EVENTS.each do |event|
+        entries = hooks[event] ||= []
+        next if entries.any? { |e| (e["hooks"] || []).any? { |h| h["command"].to_s.include?(HOOK_ENTRYPOINT) } }
+
+        entries << { "matcher" => "Bash", "hooks" => [{ "type" => "command", "command" => HOOK_COMMAND }] }
+        changed = true
+      end
+      changed
+    end
+
+    def self.installed?(settings)
+      hooks = settings["hooks"] || {}
+      HOOK_EVENTS.all? do |event|
+        (hooks[event] || []).any? { |e| (e["hooks"] || []).any? { |h| h["command"].to_s.include?(HOOK_ENTRYPOINT) } }
+      end
+    end
+  end
+end

data/lib/localvault/plaintext_output.rb

@@ -0,0 +1,48 @@
+module LocalVault
+  # Gate for printing plaintext secret values.
+  #
+  # Plaintext may flow to an interactive terminal (a human is watching). When
+  # stdout is captured (pipe, command substitution, agent shell), a human can
+  # confirm with one keystroke on /dev/tty. An agent's shell has no /dev/tty,
+  # and there is deliberately no flag, environment variable, or config bypass:
+  # anything discoverable from the binary would be discovered by an agent.
+  module PlaintextOutput
+    TTY_PATH = "/dev/tty".freeze
+
+    class << self
+      # In-process overrides for tests only — unreachable from the installed
+      # binary, unlike an env var or CLI flag would be.
+      attr_accessor :assume_tty
+      attr_accessor :tty_override # {input: IO, output: IO}
+    end
+
+    # @param out [IO] the stream plaintext would be written to
+    # @param purpose [String] short description used in the /dev/tty prompt
+    # @return [Boolean] whether plaintext may be printed to +out+
+    def self.permitted?(out: $stdout, purpose: "Print plaintext")
+      return true if assume_tty
+      return true if out.respond_to?(:tty?) && out.tty?
+
+      confirm("#{purpose}? [y/N] ")
+    end
+
+    def self.confirm(prompt)
+      with_tty do |input, output|
+        output.write(prompt)
+        output.flush
+        answer = input.gets
+        !answer.nil? && %w[y yes].include?(answer.strip.downcase)
+      end
+    end
+
+    def self.with_tty(&block)
+      if tty_override
+        return yield(tty_override[:input], tty_override[:output])
+      end
+
+      File.open(TTY_PATH, "r+") { |tty| yield(tty, tty) }
+    rescue SystemCallError, IOError
+      false
+    end
+  end
+end

data/lib/localvault/version.rb

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

data/lib/localvault.rb

@@ -6,6 +6,8 @@ require_relative "localvault/env_projection"
 require_relative "localvault/key_lookup"
 require_relative "localvault/vault_resolver"
 require_relative "localvault/stdin_secret_input"
+require_relative "localvault/plaintext_output"
+require_relative "localvault/guard"
 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.8.1
+  version: 1.9.0
 platform: ruby
 authors:
 - Nauman Tariq
@@ -109,6 +109,7 @@ files:
 - lib/localvault/api_client.rb
 - lib/localvault/cli.rb
 - lib/localvault/cli/error_presenter.rb
+- lib/localvault/cli/guard.rb
 - lib/localvault/cli/keys.rb
 - lib/localvault/cli/sync.rb
 - lib/localvault/cli/team.rb
@@ -117,6 +118,7 @@ files:
 - lib/localvault/crypto.rb
 - lib/localvault/env_projection.rb
 - lib/localvault/group_catalog.rb
+- lib/localvault/guard.rb
 - lib/localvault/identity.rb
 - lib/localvault/input_validation.rb
 - lib/localvault/key_lookup.rb
@@ -124,6 +126,7 @@ files:
 - lib/localvault/mcp/exec_command_builder.rb
 - lib/localvault/mcp/server.rb
 - lib/localvault/mcp/tools.rb
+- lib/localvault/plaintext_output.rb
 - lib/localvault/session_cache.rb
 - lib/localvault/share_crypto.rb
 - lib/localvault/stdin_secret_input.rb