localvault 1.9.1 → 1.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 20aa094af163dfa0173fae2eabfc274da78badf84ebc37366bf85163f7b7f77d
-  data.tar.gz: f113382f8edb4a630732b56de9abe163470c0c377bbcbf64951fde108f6d5e0b
+  metadata.gz: 89b873121ec4642cd62fc4b8e7d18fb5bf4dd7f456d0b25b9690a154d3392d51
+  data.tar.gz: 90915ed8508f056077cc64ed5c06e9d6925f9c893c70daaf71727fcf4c5d852c
 SHA512:
-  metadata.gz: e65ac37ab002da71e42ed5d1e31369dd492982683e2817165060962777e197b8873b6c73c11761d2f7aa829c1c6729f7334691d83d16f0de858c59de2a8abbec
-  data.tar.gz: 2efaf71acba0f24beaa48313a88d0a9f58058d42f7c80a5ef439af76f29deac6df30435dd74868d04d1bbedf224e1d87499a647e32509cecf0895d696f453934
+  metadata.gz: dfcff8362dfd3ec7cbfa25fa4f8b0c599fe6584eedcea0c53f8e6515b028bfada2576cdcf7ef03e1ac130a083b4a869fbb5fe3ec282ab909a9a6f72a0affcdbb
+  data.tar.gz: 85ba5c571866b4aa78ad40394d8ffcc3aedfaf6c8c9b5b1013042d1bc3e63ee5d9deb324e0fe8b52ddea8df7026cfa107d1e2b076b9cbf3e741d74d703d8f7aa

data/README.md

@@ -88,11 +88,11 @@ localvault exec -- rails server
 | `init [NAME]` | Create a vault (Argon2id key derivation) |
 | `set KEY --stdin` | Store a secret from stdin without argv/history exposure |
 | `set KEY [VALUE]` | Store a secret (positional value kept for compatibility) |
-| `set --group GROUP KEY --stdin` | Store a secret in a named group from stdin |
+| `set --group GROUP KEY --stdin` | Store a secret in a named group from stdin (`-g`) |
 | `get KEY` | Retrieve a secret (raw, pipeable) |
 | `show` | Display all secrets in a table (masked by default) |
-| `show --reveal` | Display with values visible |
-| `show --group` | Group by dot-notation prefix (one table per project) |
+| `show --reveal` | Display with values visible (`-r`) |
+| `show --group` | Group by dot-notation prefix, one table per project (`-g`) |
 | `show --group QUERY` | Show one exact or uniquely matching group |
 | `groups [QUERY]` | List/search group names and key counts without values |
 | `list` | List key names only |

data/lib/localvault/cli/identity_cmd.rb

@@ -0,0 +1,55 @@
+require "thor"
+
+module LocalVault
+  class CLI
+    class IdentityCommand < Thor
+      ALIAS_PATTERN = /\A[a-zA-Z0-9][a-zA-Z0-9_-]{0,31}\z/
+
+      desc "show", "Show your identity — alias, InventList handle, public key"
+      # Print the local identity summary: the configured alias, the
+      # InventList handle (if logged in), and the sync public key (if any).
+      def show
+        $stdout.puts "Alias:      #{Config.identity_alias || "-"}"
+        $stdout.puts "Handle:     #{Config.inventlist_handle ? "@#{Config.inventlist_handle}" : "-"}"
+        $stdout.puts "Public key: #{Identity.exists? ? Identity.public_key : "- (run: localvault keygen)"}"
+      end
+      default_task :show
+
+      desc "set FIELD VALUE", "Set an identity field (currently: alias)"
+      long_desc <<~DESC
+        Set a local identity field.
+
+        SET YOUR ALIAS (a local display name, independent of InventList login):
+        \x05    localvault identity set alias nauman
+
+        The alias is stored in ~/.localvault/config.yml and never leaves
+        your machine.
+      DESC
+      # Set an identity field. Only +alias+ is supported today.
+      def set(field, value)
+        unless field == "alias"
+          $stderr.puts "Error: Unknown field '#{field}'. Supported: alias"
+          exit 1
+        end
+        unless value.match?(ALIAS_PATTERN)
+          $stderr.puts "Error: Alias must be 1-32 characters: letters, digits, '-' or '_', starting with a letter or digit."
+          exit 1
+        end
+        Config.identity_alias = value
+        $stdout.puts "Alias set to '#{value}'."
+      end
+
+      desc "unset FIELD", "Clear an identity field (currently: alias)"
+      # Clear an identity field. Only +alias+ is supported today.
+      def unset(field)
+        unless field == "alias"
+          $stderr.puts "Error: Unknown field '#{field}'. Supported: alias"
+          exit 1
+        end
+        previous = Config.identity_alias
+        Config.identity_alias = nil
+        $stdout.puts(previous ? "Alias '#{previous}' cleared." : "No alias set.")
+      end
+    end
+  end
+end

data/lib/localvault/cli.rb

@@ -108,87 +108,47 @@ module LocalVault
 
     class_option :vault, aliases: "-v", type: :string, desc: "Vault name"
 
+    # Main help = Thor's auto-generated command list (always complete, so new
+    # commands appear without touching this file) + a handwritten guide for
+    # the concepts and workflows Thor can't derive from command descriptions.
     def self.help(shell, subcommand = false)
       shell.say ""
       shell.say "LocalVault — encrypted local secrets vault with MCP support for AI agents"
       shell.say "  https://inventlist.com/tools/localvault"
       shell.say ""
+      super
+      shell.say ""
       shell.say "GETTING STARTED"
       shell.say "  localvault login [TOKEN]      Log in to InventList (enables sync + team features)"
       shell.say "  localvault init [NAME]        Create a new encrypted vault"
       shell.say "  localvault demo               Create a demo vault to explore commands"
       shell.say ""
-      shell.say "SECRETS"
+      shell.say "SAFE SECRET INPUT  (preferred over passing values as arguments)"
       shell.say "  printf '%s' \"$SECRET\" | localvault set KEY --stdin"
-      shell.say "                              Store a secret without argv/history exposure"
-      shell.say "  localvault set KEY VALUE      Store a secret (compatibility path)"
-      shell.say "  localvault set --group G K V  Store a secret inside group G"
-      shell.say "  localvault get KEY            Retrieve a secret"
-      shell.say "  localvault show               Display all secrets (masked by default)"
-      shell.say "  localvault groups [QUERY]     List or search stored groups (names only)"
-      shell.say "  localvault list               List secret key names"
-      shell.say "  localvault delete KEY         Remove a secret"
-      shell.say "  localvault import FILE        Bulk-import from .env / .json / .yml"
-      shell.say "  localvault env                Export as shell variable assignments"
-      shell.say "  localvault exec -- CMD        Run a command with secrets injected as env vars"
-      shell.say ""
-      shell.say "  Use with any CLI:  localvault exec -- inventlist ships list"
-      shell.say "                     localvault exec -- curl -H \"Authorization: Bearer $API_KEY\" ..."
+      shell.say "                                Store a secret without argv/history exposure"
       shell.say ""
-      shell.say "VAULT MANAGEMENT"
-      shell.say "  localvault vaults             List all vaults"
-      shell.say "  localvault switch [VAULT]     Switch default vault"
-      shell.say "  localvault rekey [NAME]       Change vault passphrase"
-      shell.say "  localvault unlock             Cache passphrase for session"
-      shell.say "  localvault lock [NAME]        Clear cached passphrase"
-      shell.say "  localvault reset [NAME]       Destroy and reinitialize a vault"
-      shell.say "  localvault rename OLD NEW     Rename a secret key"
-      shell.say "  localvault copy KEY --to V    Copy a secret to another vault"
+      shell.say "PROJECTS  (dot-notation groups inside one vault)"
+      shell.say "  localvault set platepose.API_KEY v    Store a key in the 'platepose' group"
+      shell.say "  Filter any command with -p:  show -p platepose, exec -p platepose -- CMD"
+      shell.say "  Delete a whole group:        localvault delete 'platepose.*'"
       shell.say ""
-      shell.say "SYNC  (requires localvault login)"
-      shell.say "  localvault sync               Sync all vaults bidirectionally (smart push/pull with conflict detection)"
-      shell.say "  localvault sync --dry-run     Show what would happen without making changes"
-      shell.say "  localvault sync push [NAME]   Push one vault to cloud"
-      shell.say "  localvault sync pull [NAME]   Pull one vault from cloud"
-      shell.say "  localvault sync status        Show sync status for all vaults"
+      shell.say "USING SECRETS WITH ANY CLI"
+      shell.say "  localvault exec -- inventlist ships list"
+      shell.say "  localvault exec -- curl -H \"Authorization: Bearer $API_KEY\" ..."
       shell.say ""
       shell.say "TEAM SHARING  (requires localvault login)"
-      shell.say "  localvault dashboard          Aggregate view: owned vaults, vaults shared with you, legacy shares"
-      shell.say "  localvault verify @HANDLE     Check if a person has a published public key"
-      shell.say "  localvault add @HANDLE        Add teammate (use --scope KEY... for partial access)"
-      shell.say "  localvault remove @HANDLE     Remove teammate  (--scope KEY to strip one key, --rotate to re-key)"
-      shell.say "  localvault team init [VAULT]  Convert vault to team vault (required before add)"
-      shell.say "  localvault team list [VAULT]  List vault members and their access"
-      shell.say "  localvault team rotate [VAULT] Re-key vault, keep all members"
-      shell.say "  localvault team SUBCOMMAND    See `localvault help team` for the full team namespace"
-      shell.say "                                (also accepts `team add/remove/verify` aliases for the top-level commands)"
-      shell.say ""
-      shell.say "KEYS  (X25519 identity for vault sharing)"
-      shell.say "  localvault keys generate      Generate X25519 identity keypair"
-      shell.say "  localvault keys publish       Publish public key so others can share vaults with you"
-      shell.say "  localvault keys show          Display your current public key"
-      shell.say "  localvault keys SUBCOMMAND    See `localvault help keys` for the full keys namespace"
+      shell.say "  Convert with `team init`, then `add @HANDLE` / `remove @HANDLE`."
+      shell.say "  Use --scope KEY... for partial access; `team rotate` re-keys for all members."
+      shell.say "  `team add/remove/verify` also work as aliases for the top-level commands."
       shell.say ""
       shell.say "AI / MCP"
-      shell.say "  localvault install-mcp        Configure MCP server in your AI tool"
-      shell.say "  localvault mcp                Start MCP server (stdio)"
-      shell.say "  localvault mcp --check        Check setup and active-vault readiness"
-      shell.say "  Agents: list names, then use localvault_build_exec for safe injection"
-      shell.say "  localvault guard install      Block secrets in agent commands (Claude Code hooks)"
-      shell.say "  localvault guard status       Show guard hook installation state"
+      shell.say "  Agents: list secret names, then use localvault_build_exec for safe injection."
+      shell.say "  `guard install` blocks plaintext secrets in agent commands (Claude Code hooks)."
       shell.say ""
       shell.say "LEGACY SHARING  (pre-v1.2 direct share, still works as fallback)"
-      shell.say "  localvault keygen             Generate X25519 keypair (same as `keys generate`)"
-      shell.say "  localvault share [VAULT]      Share a vault with a user, team, or crew (one-shot copy)"
-      shell.say "  localvault receive            Fetch and import vaults shared with you"
-      shell.say "  localvault revoke SHARE_ID    Revoke a direct vault share"
+      shell.say "  keygen / share / receive / revoke — superseded by `keys` + team vaults."
       shell.say ""
-      shell.say "OTHER"
-      shell.say "  localvault login --status     Show current login status"
-      shell.say "  localvault logout             Log out"
-      shell.say "  localvault version            Print version"
-      shell.say "  localvault doctor             Check install and PATH readiness"
-      shell.say "  localvault help [COMMAND]     Full help for any command"
+      shell.say "Full help for any command: localvault help COMMAND"
       shell.say ""
     end
 
@@ -243,7 +203,7 @@ module LocalVault
       Use `localvault show -p platepose -v vault` to view a single project.
       Use `localvault import` to bulk-load from a .env, .json, or .yml file.
     DESC
-    method_option :group, type: :string, desc: "Store KEY and VALUE inside this named group"
+    method_option :group, aliases: "-g", type: :string, desc: "Store KEY and VALUE inside this named group"
     method_option :stdin, type: :boolean, default: false, desc: "Read VALUE from stdin instead of argv"
     def set(key, value = nil)
       validate_secret_value_source!(value)
@@ -526,8 +486,8 @@ module LocalVault
 \x05    localvault show -p platepose -v intellectaco  # one project only
 \x05    localvault show -p platepose -v intellectaco --reveal
     DESC
-    method_option :group, type: :string, lazy_default: GROUP_ALL_SENTINEL, desc: "Show all groups or one group by name"
-    method_option :reveal,  type: :boolean, default: false, desc: "Show full values instead of masking"
+    method_option :group, aliases: "-g", type: :string, lazy_default: GROUP_ALL_SENTINEL, desc: "Show all groups or one group by name"
+    method_option :reveal, aliases: "-r", type: :boolean, default: false, desc: "Show full values instead of masking"
     method_option :project, aliases: "-p", type: :string,   desc: "Show only this project group"
     def show
       vault = open_vault!
@@ -768,8 +728,10 @@ module LocalVault
     require_relative "cli/team"
     require_relative "cli/sync"
     require_relative "cli/guard"
+    require_relative "cli/identity_cmd"
 
     register(Guard, "guard", "guard SUBCOMMAND", "Block plaintext secrets in agent tool traffic (Claude Code hooks)")
+    register(IdentityCommand, "identity", "identity SUBCOMMAND", "Show or set your local identity (alias, handle, public key)")
     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")

data/lib/localvault/config.rb

@@ -122,6 +122,27 @@ module LocalVault
       save(data)
     end
 
+    # Read the local identity alias.
+    #
+    # @return [String, nil] the stored alias, or nil
+    def self.identity_alias
+      load["identity_alias"]
+    end
+
+    # Set the local identity alias. Pass +nil+ to clear it.
+    #
+    # @param a [String, nil] the alias to store
+    # @return [void]
+    def self.identity_alias=(a)
+      data = load
+      if a.nil?
+        data.delete("identity_alias")
+      else
+        data["identity_alias"] = a
+      end
+      save(data)
+    end
+
     # Read the InventList API base URL.
     #
     # @return [String] the API URL, defaults to "https://inventlist.com"

data/lib/localvault/guard.rb

@@ -1,4 +1,5 @@
 require "json"
+require "yaml"
 require "digest"
 require_relative "store"
 require_relative "session_cache"
@@ -15,6 +16,44 @@ module LocalVault
   # check gets uninstalled.
   module Guard
     MIN_VALUE_LENGTH = 8
+
+    # Keys the operator has explicitly declared non-secret, from
+    # ~/.localvault/config.yml:
+    #
+    #   guard_ignore:
+    #     - CLOUDFLARE_ASSETS.r2_bucket
+    #
+    # WHY EXPLICIT, AND NOT INFERRED FROM THE KEY NAME.
+    # The first attempt exempted keys whose name *looked* public — anything
+    # ending in bucket / region / _id — with a veto list of credential-ish
+    # words. An audit killed it in one line: a value stored under `AWS.bucket`
+    # would be exempt regardless of what it actually contained, so the fix
+    # traded a false positive for a false NEGATIVE in a security tool. The veto
+    # list was also unbounded (pem, jwk, seed, mnemonic, salt, otp, bearer,
+    # sas, …) and every omission is a silent bypass.
+    #
+    # A key's name cannot describe its value. Only the operator can say "this
+    # one is public", so only the operator may — by naming the exact full key,
+    # in a file they control, which is greppable and auditable.
+    #
+    # The problem being solved is still real: a public identifier stored beside
+    # real secrets (a bucket name that happens to be a substring of a project
+    # path) denies every command mentioning that path, and a guard that cries
+    # wolf gets uninstalled, which protects nothing. The answer is an explicit
+    # allowlist, not a clever one.
+    def self.ignored_keys(config_path = default_config_path)
+      return [] unless File.exist?(config_path)
+
+      raw = YAML.safe_load(File.read(config_path)) || {}
+      Array(raw["guard_ignore"]).map(&:to_s)
+    rescue StandardError
+      [] # an unreadable config must never widen the exemption
+    end
+
+    def self.default_config_path
+      File.join(Dir.home, ".localvault", "config.yml")
+    end
+
     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
@@ -55,12 +94,17 @@ module LocalVault
     end
 
     # @return [Array<Match>] stored secret values appearing in +text+
-    def self.scan(text, secrets = unlocked_secrets)
+    def self.scan(text, secrets = unlocked_secrets, ignore: ignored_keys)
       return [] if text.nil? || text.empty?
 
+      ignored = Array(ignore).map(&:to_s)
+
       secrets.filter_map do |entry|
         value = entry[:value]
         next if value.nil? || value.length < MIN_VALUE_LENGTH
+        # Exact full-key match only. No prefixes, no suffix inference — an
+        # operator opting one key out must never silently opt out its siblings.
+        next if ignored.include?(entry[:key].to_s)
         next unless text.include?(value)
 
         Match.new(vault: entry[:vault], key: entry[:key], fingerprint: fingerprint(value))

data/lib/localvault/version.rb

@@ -1,3 +1,3 @@
 module LocalVault
-  VERSION = "1.9.1"
+  VERSION = "1.10.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: localvault
 version: !ruby/object:Gem::Version
-  version: 1.9.1
+  version: 1.10.0
 platform: ruby
 authors:
 - Nauman Tariq
@@ -110,6 +110,7 @@ files:
 - lib/localvault/cli.rb
 - lib/localvault/cli/error_presenter.rb
 - lib/localvault/cli/guard.rb
+- lib/localvault/cli/identity_cmd.rb
 - lib/localvault/cli/keys.rb
 - lib/localvault/cli/sync.rb
 - lib/localvault/cli/team.rb