localvault 1.0.5 → 1.2.0

data/lib/localvault/store.rb

@@ -2,9 +2,25 @@ require "yaml"
 require "fileutils"
 require "tempfile"
 require "base64"
+require "time"
 
 module LocalVault
+  # File-system storage for a single vault's encrypted data and metadata.
+  #
+  # Each vault lives at +~/.localvault/vaults/<name>/+ with two files:
+  # - +meta.yml+ — salt, creation date, version, secret count
+  # - +secrets.enc+ — encrypted JSON blob (XSalsa20-Poly1305)
+  #
+  # Uses atomic writes (tempfile + rename) to prevent corruption.
+  # All directories are created with mode 0700, all files with mode 0600.
+  #
+  # @example
+  #   store = Store.new("production")
+  #   store.create!(salt: Crypto.generate_salt)
+  #   store.write_encrypted(ciphertext)
+  #   store.read_encrypted  # => ciphertext bytes
   class Store
+    # Raised when a vault name contains invalid characters or path traversal.
     class InvalidVaultName < StandardError; end
 
     # Letters, digits, underscore, dash. Must start with alphanumeric.
@@ -12,27 +28,48 @@ module LocalVault
 
     attr_reader :vault_name
 
+    # Initialize a store for the given vault name.
+    #
+    # @param vault_name [String] the vault name (alphanumeric, dash, underscore)
+    # @raise [InvalidVaultName] when name is empty, too long, or has invalid characters
     def initialize(vault_name)
       validate_vault_name!(vault_name)
       @vault_name = vault_name
     end
 
+    # Absolute path to this vault's directory.
+    #
+    # @return [String] path to +~/.localvault/vaults/<name>/+
     def vault_path
       File.join(Config.vaults_path, vault_name)
     end
 
+    # Absolute path to the encrypted secrets file.
+    #
+    # @return [String] path to +secrets.enc+
     def secrets_path
       File.join(vault_path, "secrets.enc")
     end
 
+    # Absolute path to the metadata file.
+    #
+    # @return [String] path to +meta.yml+
     def meta_path
       File.join(vault_path, "meta.yml")
     end
 
+    # Check whether this vault exists on disk.
+    #
+    # @return [Boolean] true if the vault directory and meta file exist
     def exists?
       File.directory?(vault_path) && File.exist?(meta_path)
     end
 
+    # Create a new vault on disk with initial metadata.
+    #
+    # @param salt [String] raw salt bytes for key derivation
+    # @return [void]
+    # @raise [RuntimeError] when the vault already exists
     def create!(salt:)
       raise "Vault '#{vault_name}' already exists" if exists?
 
@@ -47,21 +84,34 @@ module LocalVault
       write_meta(new_meta)
     end
 
+    # Read and parse the vault's metadata.
+    #
+    # @return [Hash, nil] the parsed meta.yml contents, or nil if file is missing
     def meta
       return nil unless File.exist?(meta_path)
       YAML.safe_load_file(meta_path)
     end
 
+    # Read the raw salt bytes from metadata.
+    #
+    # @return [String, nil] decoded salt bytes, or nil if not available
     def salt
       m = meta
       return nil unless m && m["salt"]
       Base64.strict_decode64(m["salt"])
     end
 
+    # Number of secrets stored in this vault.
+    #
+    # @return [Integer] the secret count from metadata, defaults to 0
     def count
       meta&.dig("count") || 0
     end
 
+    # Update the secret count in metadata.
+    #
+    # @param n [Integer] the new count
+    # @return [void]
     def update_count!(n)
       m = meta
       return unless m
@@ -69,11 +119,18 @@ module LocalVault
       write_meta(m)
     end
 
+    # Read the encrypted secrets blob from disk.
+    #
+    # @return [String, nil] raw ciphertext bytes, or nil if file is missing
     def read_encrypted
       return nil unless File.exist?(secrets_path)
       File.binread(secrets_path)
     end
 
+    # Atomically write encrypted bytes to disk using tempfile + rename.
+    #
+    # @param bytes [String] raw ciphertext bytes to write
+    # @return [void]
     def write_encrypted(bytes)
       FileUtils.mkdir_p(vault_path, mode: 0o700)
 
@@ -90,6 +147,10 @@ module LocalVault
       raise
     end
 
+    # Create or overwrite metadata with a new salt, preserving created_at if present.
+    #
+    # @param salt [String] raw salt bytes for key derivation
+    # @return [void]
     def create_meta!(salt:)
       existing = meta
       new_meta = {
@@ -101,6 +162,9 @@ module LocalVault
       write_meta(new_meta)
     end
 
+    # Permanently delete this vault's directory and all its contents.
+    #
+    # @return [void]
     def destroy!
       FileUtils.rm_rf(vault_path)
     end
@@ -121,6 +185,9 @@ module LocalVault
 
     public
 
+    # List all vault names found on disk.
+    #
+    # @return [Array<String>] sorted vault names
     def self.list_vaults
       vaults_dir = Config.vaults_path
       return [] unless File.directory?(vaults_dir)

data/lib/localvault/sync_bundle.rb

@@ -3,32 +3,76 @@ require "base64"
 require "yaml"
 
 module LocalVault
+  # Packs and unpacks vault data for cloud sync via InventList + R2.
+  #
+  # Bundle versions:
+  # - v1: personal sync — +{ version, meta, secrets }+
+  # - v2: legacy team — +{ version, meta, secrets, key_slots }+
+  # - v3: team with ownership — +{ version, owner, meta, secrets, key_slots }+
+  #
+  # The server never sees plaintext — the bundle is opaque ciphertext.
+  #
+  # @example Personal sync (v1)
+  #   blob = SyncBundle.pack(store)
+  #
+  # @example Team sync (v3)
+  #   blob = SyncBundle.pack_v3(store, owner: "alice", key_slots: slots)
+  #   data = SyncBundle.unpack(blob)
+  #   data[:owner]     # => "alice"
+  #   data[:key_slots] # => {"alice" => {...}, "bob" => {...}}
   module SyncBundle
+    # Raised when unpacking fails (bad JSON, missing fields, wrong version, invalid encoding).
     class UnpackError < StandardError; end
 
-    VERSION = 1
+    SUPPORTED_VERSIONS = [1, 2, 3].freeze
 
-    # Pack a vault's meta.yml + secrets.enc into a single JSON blob.
-    # The secrets.enc is already encrypted — this bundle is opaque to the server.
+    # Pack a personal vault — v1 format, no key_slots, no owner.
+    #
+    # @param store [Store] the vault store to pack
+    # @return [String] JSON string ready for upload
     def self.pack(store)
       meta_content    = File.read(store.meta_path)
       secrets_content = store.read_encrypted || ""
       JSON.generate(
-        "version" => VERSION,
+        "version" => 1,
         "meta"    => Base64.strict_encode64(meta_content),
         "secrets" => Base64.strict_encode64(secrets_content)
       )
     end
 
-    # Unpack a blob back into {meta:, secrets:} strings.
-    # Pass expected_name: to validate the meta.yml name matches the vault being pulled.
+    # Pack a team vault — v3 format with owner, key_slots, and per-member blobs.
+    #
+    # @param store [Store] the vault store to pack
+    # @param owner [String] the owner's InventList handle
+    # @param key_slots [Hash] per-user key slot data
+    # @return [String] JSON string ready for upload
+    def self.pack_v3(store, owner:, key_slots: {})
+      meta_content    = File.read(store.meta_path)
+      secrets_content = store.read_encrypted || ""
+      JSON.generate(
+        "version"   => 3,
+        "owner"     => owner,
+        "meta"      => Base64.strict_encode64(meta_content),
+        "secrets"   => Base64.strict_encode64(secrets_content),
+        "key_slots" => key_slots
+      )
+    end
+
+    # Unpack any version bundle into its component parts.
+    #
+    # @param blob [String] JSON string from ApiClient#pull_vault
+    # @param expected_name [String, nil] if set, validates the meta.yml vault name matches
+    # @return [Hash] +{meta:, secrets:, key_slots:, owner:}+
+    # @raise [UnpackError] on invalid format, unsupported version, or name mismatch
     def self.unpack(blob, expected_name: nil)
       data = JSON.parse(blob)
       version = data["version"]
-      raise UnpackError, "Unsupported bundle version: #{version}" if version && version != VERSION
+      raise UnpackError, "Unsupported bundle version: #{version}" if version && !SUPPORTED_VERSIONS.include?(version)
 
       meta_raw    = Base64.strict_decode64(data.fetch("meta"))
       secrets_raw = Base64.strict_decode64(data.fetch("secrets"))
+      key_slots   = data["key_slots"].is_a?(Hash) ? data["key_slots"] : {}
+      owner       = data["owner"]
 
       if expected_name
         meta_parsed = YAML.safe_load(meta_raw)
@@ -38,7 +82,7 @@ module LocalVault
         end
       end
 
-      { meta: meta_raw, secrets: secrets_raw }
+      { meta: meta_raw, secrets: secrets_raw, key_slots: key_slots, owner: owner }
     rescue JSON::ParserError => e
       raise UnpackError, "Invalid sync bundle format: #{e.message}"
     rescue KeyError => e

data/lib/localvault/vault.rb

@@ -2,20 +2,51 @@ require "json"
 require "shellwords"
 
 module LocalVault
+  # Encrypted key-value store backed by a single JSON blob.
+  #
+  # Each vault has a name, a master key (derived from passphrase + salt),
+  # and a Store that handles file I/O. Secrets are stored as a flat or
+  # nested JSON hash, encrypted with XSalsa20-Poly1305.
+  #
+  # Supports dot-notation for nested keys: +"project.SECRET_KEY"+
+  # groups secrets under a project namespace.
+  #
+  # @example Basic usage
+  #   vault = Vault.create!(name: "default", master_key: key, salt: salt)
+  #   vault.set("API_KEY", "sk-...")
+  #   vault.get("API_KEY")    # => "sk-..."
+  #   vault.list              # => ["API_KEY"]
+  #   vault.export_env        # => "export API_KEY=sk-..."
+  #
+  # @example Nested keys
+  #   vault.set("myapp.DB_URL", "postgres://...")
+  #   vault.get("myapp.DB_URL")  # => "postgres://..."
+  #   vault.env_hash(project: "myapp")  # => {"DB_URL" => "postgres://..."}
   class Vault
+    # Raised when a key name contains invalid characters.
     class InvalidKeyName < StandardError; end
 
-    # Shell-safe: letters, digits, underscores. Must start with letter or underscore.
+    # Shell-safe pattern: letters, digits, underscores. Must start with letter or underscore.
     KEY_SEGMENT_PATTERN = /\A[A-Za-z_][A-Za-z0-9_]*\z/
 
     attr_reader :name, :master_key, :store
 
+    # Initialize a vault instance for reading and writing secrets.
+    #
+    # @param name [String] the vault name
+    # @param master_key [String] 32-byte derived master key
     def initialize(name:, master_key:)
       @name = name
       @master_key = master_key
       @store = Store.new(name)
     end
 
+    # Retrieve a secret by key. Supports dot-notation for nested keys.
+    #
+    # @param key [String] the secret key, e.g. "API_KEY" or "myapp.DB_URL"
+    # @return [String, nil] the secret value, or nil if not found
+    # @example
+    #   vault.get("myapp.DB_URL")  # => "postgres://..."
     def get(key)
       if key.include?(".")
         group, subkey = key.split(".", 2)
@@ -27,6 +58,13 @@ module LocalVault
       end
     end
 
+    # Store a secret. Supports dot-notation for nested keys.
+    #
+    # @param key [String] the secret key, e.g. "API_KEY" or "myapp.DB_URL"
+    # @param value [String] the secret value
+    # @return [String] the stored value
+    # @raise [InvalidKeyName] when key contains invalid characters
+    # @raise [RuntimeError] when a scalar key is used as a group
     def set(key, value)
       validate_key!(key)
       secrets = all
@@ -42,6 +80,10 @@ module LocalVault
       value
     end
 
+    # Delete a secret by key. Supports dot-notation for nested keys.
+    #
+    # @param key [String] the secret key to delete
+    # @return [String, nil] the deleted value, or nil if not found
     def delete(key)
       secrets = all
       if key.include?(".")
@@ -58,13 +100,19 @@ module LocalVault
       end
     end
 
-    # Returns a flat list of all keys — nested keys use dot-notation.
+    # Returns a sorted flat list of all keys. Nested keys use dot-notation.
+    #
+    # @return [Array<String>] sorted key names, e.g. ["API_KEY", "myapp.DB_URL"]
     def list
       all.flat_map do |k, v|
         v.is_a?(Hash) ? v.keys.map { |sk| "#{k}.#{sk}" } : [k]
       end.sort
     end
 
+    # Decrypt and return all secrets as a hash.
+    #
+    # @return [Hash] the decrypted secrets hash (may contain nested hashes for groups)
+    # @raise [Crypto::DecryptionError] when master key is wrong or data is corrupt
     def all
       encrypted = store.read_encrypted
       return {} unless encrypted && !encrypted.empty?
@@ -73,11 +121,18 @@ module LocalVault
       JSON.parse(json)
     end
 
-    # Export as shell variable assignments.
-    # - With project: exports only that group's keys (no prefix).
-    # - Without project: flat keys as-is, nested keys as GROUP__KEY.
-    # Keys that aren't valid shell identifiers are skipped. Pass on_skip: callable
-    # to be notified (e.g., for warnings).
+    # Export secrets as shell variable assignments (export KEY=value).
+    #
+    # With +project+, exports only that group's keys without prefix.
+    # Without +project+, flat keys export as-is, nested keys as GROUP__KEY.
+    # Keys that are not valid shell identifiers are skipped.
+    #
+    # @param project [String, nil] optional group name to scope the export
+    # @param on_skip [#call, nil] called with key name when a key is skipped
+    # @return [String] newline-separated export statements
+    # @example
+    #   vault.export_env(project: "myapp")
+    #   # => "export DB_URL=postgres%3A//..."
     def export_env(project: nil, on_skip: nil)
       secrets = all
       if project
@@ -119,10 +174,17 @@ module LocalVault
     end
 
     # Returns a flat hash suitable for env injection.
-    # - With project: only that group's key-value pairs.
-    # - Without project: flat keys + nested keys as GROUP__KEY.
-    # Keys that aren't valid shell identifiers are skipped. Pass on_skip: callable
-    # to be notified.
+    #
+    # With +project+, returns only that group's key-value pairs.
+    # Without +project+, flat keys are kept as-is, nested keys become GROUP__KEY.
+    # Keys that are not valid shell identifiers are skipped.
+    #
+    # @param project [String, nil] optional group name to scope the output
+    # @param on_skip [#call, nil] called with key name when a key is skipped
+    # @return [Hash{String => String}] flat hash of env variable names to values
+    # @example
+    #   vault.env_hash(project: "myapp")
+    #   # => {"DB_URL" => "postgres://...", "SECRET" => "abc"}
     def env_hash(project: nil, on_skip: nil)
       secrets = all
       if project
@@ -160,6 +222,13 @@ module LocalVault
       end
     end
 
+    # Create a new vault with an empty secrets store.
+    #
+    # @param name [String] the vault name
+    # @param master_key [String] 32-byte derived master key
+    # @param salt [String] the salt used for key derivation (stored in metadata)
+    # @return [Vault] the newly created vault instance
+    # @raise [RuntimeError] when a vault with the same name already exists
     def self.create!(name:, master_key:, salt:)
       store = Store.new(name)
       store.create!(salt: salt)
@@ -171,6 +240,14 @@ module LocalVault
       new(name: name, master_key: master_key)
     end
 
+    # Re-encrypt the vault with a new passphrase and salt.
+    #
+    # Decrypts all secrets with the current key, derives a new master key,
+    # and re-encrypts everything. Returns a new Vault instance with the new key.
+    #
+    # @param new_passphrase [String] the new passphrase
+    # @param new_salt [String] optional salt (generated if omitted)
+    # @return [Vault] a new vault instance with the updated master key
     def rekey(new_passphrase, new_salt: Crypto.generate_salt)
       secrets = all
       new_master_key = Crypto.derive_master_key(new_passphrase, new_salt)
@@ -181,6 +258,12 @@ module LocalVault
       new_vault
     end
 
+    # Open an existing vault by deriving the master key from a passphrase.
+    #
+    # @param name [String] the vault name
+    # @param passphrase [String] the passphrase to derive the master key
+    # @return [Vault] the opened vault instance
+    # @raise [RuntimeError] when the vault does not exist or has no salt
     def self.open(name:, passphrase:)
       store = Store.new(name)
       raise "Vault '#{name}' does not exist" unless store.exists?
@@ -192,8 +275,15 @@ module LocalVault
       new(name: name, master_key: master_key)
     end
 
-    # Bulk-set: merges all key-value pairs in a single decrypt/encrypt cycle.
+    # Bulk-set key-value pairs in a single decrypt/encrypt cycle.
+    #
     # Supports nested hashes: { "app" => { "DB" => "..." } } merges into group "app".
+    # Dot-notation keys are also supported in the top-level hash.
+    #
+    # @param hash [Hash] key-value pairs to merge into the vault
+    # @return [void]
+    # @raise [InvalidKeyName] when any key contains invalid characters
+    # @raise [RuntimeError] when a scalar key is used as a group
     def merge(hash)
       secrets = all
       hash.each do |k, v|
@@ -220,6 +310,26 @@ module LocalVault
       write_secrets(secrets)
     end
 
+    # Return a subset of secrets matching the given scopes.
+    #
+    # Scopes can be group names (returns entire nested hash) or flat key names.
+    # +nil+ means full access (returns all). Empty array means nothing.
+    #
+    # @param scopes [Array<String>, nil] list of group/key names, or nil for all
+    # @return [Hash] filtered secrets
+    def filter(scopes)
+      return all if scopes.nil?
+      return {} if scopes.empty?
+
+      secrets = all
+      result = {}
+      scopes.each do |scope|
+        value = secrets[scope]
+        result[scope] = value if value
+      end
+      result
+    end
+
     private
 
     def shell_safe_key?(key)

data/lib/localvault/version.rb

@@ -1,3 +1,3 @@
 module LocalVault
-  VERSION = "1.0.5"
+  VERSION = "1.2.0"
 end

data/lib/localvault.rb

@@ -5,6 +5,7 @@ require_relative "localvault/store"
 require_relative "localvault/vault"
 require_relative "localvault/identity"
 require_relative "localvault/share_crypto"
+require_relative "localvault/key_slot"
 require_relative "localvault/api_client"
 require_relative "localvault/sync_bundle"
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: localvault
 version: !ruby/object:Gem::Version
-  version: 1.0.5
+  version: 1.2.0
 platform: ruby
 authors:
 - Nauman Tariq
@@ -114,6 +114,7 @@ files:
 - lib/localvault/config.rb
 - lib/localvault/crypto.rb
 - lib/localvault/identity.rb
+- lib/localvault/key_slot.rb
 - lib/localvault/mcp/server.rb
 - lib/localvault/mcp/tools.rb
 - lib/localvault/session_cache.rb