localvault 1.1.1 → 1.2.1

data/lib/localvault/config.rb

@@ -2,76 +2,137 @@ require "yaml"
 require "fileutils"
 
 module LocalVault
+  # Global configuration — paths, default vault, API credentials.
+  #
+  # Reads/writes +~/.localvault/config.yml+ (mode 0600).
+  # All directories are created with mode 0700.
+  # Override the root path with +LOCALVAULT_HOME+ env var.
+  #
+  # @example
+  #   Config.root_path        # => "~/.localvault"
+  #   Config.default_vault    # => "default"
+  #   Config.token = "tok-..."
+  #   Config.inventlist_handle = "nauman"
   module Config
     CONFIG_FILE = "config.yml"
 
+    # Root directory for all LocalVault data. Honors +LOCALVAULT_HOME+ env var.
+    #
+    # @return [String] absolute path, defaults to +~/.localvault+
     def self.root_path
       ENV.fetch("LOCALVAULT_HOME") { File.join(Dir.home, ".localvault") }
     end
 
+    # Path to the global config file.
+    #
+    # @return [String] absolute path to +config.yml+
     def self.config_path
       File.join(root_path, CONFIG_FILE)
     end
 
+    # Path to the directory containing all vaults.
+    #
+    # @return [String] absolute path to +vaults/+ directory
     def self.vaults_path
       File.join(root_path, "vaults")
     end
 
+    # Path to the directory containing identity keys.
+    #
+    # @return [String] absolute path to +keys/+ directory
     def self.keys_path
       File.join(root_path, "keys")
     end
 
+    # Load the config file as a hash.
+    #
+    # @return [Hash] parsed config, or empty hash if file is missing
     def self.load
       return {} unless File.exist?(config_path)
       YAML.safe_load_file(config_path, permitted_classes: [Symbol]) || {}
     end
 
+    # Write config data to disk (mode 0600).
+    #
+    # @param data [Hash] the config hash to persist
+    # @return [void]
     def self.save(data)
       FileUtils.mkdir_p(root_path, mode: 0o700)
       File.write(config_path, YAML.dump(data))
       File.chmod(0o600, config_path)
     end
 
+    # Name of the default vault.
+    #
+    # @return [String] vault name, defaults to "default"
     def self.default_vault
       load.fetch("default_vault", "default")
     end
 
+    # Set the default vault name.
+    #
+    # @param name [String] the vault name to use as default
+    # @return [void]
     def self.default_vault=(name)
       data = load
       data["default_vault"] = name
       save(data)
     end
 
+    # Create the root, vaults, and keys directories if they don't exist (mode 0700).
+    #
+    # @return [void]
     def self.ensure_directories!
       FileUtils.mkdir_p(root_path, mode: 0o700)
       FileUtils.mkdir_p(vaults_path, mode: 0o700)
       FileUtils.mkdir_p(keys_path, mode: 0o700)
     end
 
+    # Read the API authentication token.
+    #
+    # @return [String, nil] the stored token, or nil
     def self.token
       load["token"]
     end
 
+    # Set the API authentication token.
+    #
+    # @param t [String] the token to store
+    # @return [void]
     def self.token=(t)
       data = load
       data["token"] = t
       save(data)
     end
 
+    # Read the InventList user handle.
+    #
+    # @return [String, nil] the stored handle, or nil
     def self.inventlist_handle
       load["inventlist_handle"]
     end
 
+    # Set the InventList user handle.
+    #
+    # @param h [String] the handle to store
+    # @return [void]
     def self.inventlist_handle=(h)
       data = load
       data["inventlist_handle"] = h
       save(data)
     end
 
+    # Read the InventList API base URL.
+    #
+    # @return [String] the API URL, defaults to "https://inventlist.com"
     def self.api_url
       load.fetch("api_url", "https://inventlist.com")
     end
 
+    # Set the InventList API base URL.
+    #
+    # @param url [String] the API URL to store
+    # @return [void]
     def self.api_url=(url)
       data = load
       data["api_url"] = url

data/lib/localvault/crypto.rb

@@ -22,7 +22,20 @@ rescue LoadError => e
 end
 
 module LocalVault
+  # Cryptographic primitives for vault encryption and key derivation.
+  #
+  # Uses libsodium (via RbNaCl) exclusively:
+  # - Argon2id for passphrase → master key derivation (memory-hard KDF)
+  # - XSalsa20-Poly1305 for authenticated symmetric encryption
+  # - X25519 for asymmetric keypair generation (used by Identity + KeySlot)
+  #
+  # @example Derive a master key and encrypt
+  #   salt = Crypto.generate_salt
+  #   key  = Crypto.derive_master_key("my passphrase", salt)
+  #   ct   = Crypto.encrypt("secret data", key)
+  #   Crypto.decrypt(ct, key)  # => "secret data"
   module Crypto
+    # Raised when decryption fails (wrong key, tampered data, or corrupt ciphertext).
     class DecryptionError < StandardError; end
 
     SALT_BYTES = 16
@@ -33,10 +46,18 @@ module LocalVault
     ARGON2_OPSLIMIT = 2
     ARGON2_MEMLIMIT = 67_108_864 # 64 MB
 
+    # Generate a random salt for key derivation.
+    #
+    # @return [String] 16 random bytes
     def self.generate_salt
       RbNaCl::Random.random_bytes(SALT_BYTES)
     end
 
+    # Derive a 32-byte master key from a passphrase using Argon2id.
+    #
+    # @param passphrase [String] the user's passphrase
+    # @param salt [String] 16-byte salt
+    # @return [String] 32-byte derived key
     def self.derive_master_key(passphrase, salt)
       RbNaCl::PasswordHash.argon2id(
         passphrase,
@@ -47,6 +68,11 @@ module LocalVault
       )
     end
 
+    # Encrypt plaintext with XSalsa20-Poly1305. Prepends a random nonce.
+    #
+    # @param plaintext [String] data to encrypt
+    # @param key [String] 32-byte symmetric key
+    # @return [String] nonce (24 bytes) + ciphertext
     def self.encrypt(plaintext, key)
       box = RbNaCl::SecretBox.new(key)
       nonce = RbNaCl::Random.random_bytes(NONCE_BYTES)
@@ -54,6 +80,12 @@ module LocalVault
       nonce + ciphertext
     end
 
+    # Decrypt ciphertext produced by +encrypt+. Expects nonce prepended.
+    #
+    # @param ciphertext_with_nonce [String] nonce (24 bytes) + ciphertext
+    # @param key [String] 32-byte symmetric key
+    # @return [String] decrypted plaintext
+    # @raise [DecryptionError] when the key is wrong or data is tampered
     def self.decrypt(ciphertext_with_nonce, key)
       box = RbNaCl::SecretBox.new(key)
       nonce = ciphertext_with_nonce[0, NONCE_BYTES]
@@ -63,6 +95,9 @@ module LocalVault
       raise DecryptionError, "Decryption failed: #{e.message}"
     end
 
+    # Generate an X25519 keypair for asymmetric encryption.
+    #
+    # @return [Hash{Symbol => String}] +:public_key+ and +:private_key+ as raw bytes
     def self.generate_keypair
       sk = RbNaCl::PrivateKey.generate
       {
@@ -71,10 +106,21 @@ module LocalVault
       }
     end
 
+    # Encrypt a private key with a master key (convenience wrapper around +encrypt+).
+    #
+    # @param private_key_bytes [String] raw private key bytes
+    # @param master_key [String] 32-byte symmetric key
+    # @return [String] nonce + ciphertext
     def self.encrypt_private_key(private_key_bytes, master_key)
       encrypt(private_key_bytes, master_key)
     end
 
+    # Decrypt a private key with a master key (convenience wrapper around +decrypt+).
+    #
+    # @param encrypted_bytes [String] nonce + ciphertext from +encrypt_private_key+
+    # @param master_key [String] 32-byte symmetric key
+    # @return [String] raw private key bytes
+    # @raise [DecryptionError] when the key is wrong or data is tampered
     def self.decrypt_private_key(encrypted_bytes, master_key)
       decrypt(encrypted_bytes, master_key)
     end

data/lib/localvault/identity.rb

@@ -2,14 +2,43 @@ require "base64"
 require "fileutils"
 
 module LocalVault
+  # Manages the user's X25519 identity keypair for vault sharing and sync.
+  #
+  # The keypair is stored in +~/.localvault/keys/+:
+  # - +identity.priv+ (mode 0600) — base64-encoded private key
+  # - +identity.pub+ (mode 0644) — base64-encoded public key
+  #
+  # The public key is published to InventList so others can encrypt
+  # key slots for you. The private key never leaves the local machine.
+  #
+  # @example
+  #   Identity.generate!
+  #   Identity.public_key       # => "base64..."
+  #   Identity.private_key_bytes # => 32 raw bytes
+  #   Identity.setup?           # => true (if keypair + token exist)
   module Identity
+    # Path to the private key file.
+    #
+    # @return [String] absolute path to +identity.priv+
     def self.priv_key_path = File.join(Config.keys_path, "identity.priv")
+
+    # Path to the public key file.
+    #
+    # @return [String] absolute path to +identity.pub+
     def self.pub_key_path  = File.join(Config.keys_path, "identity.pub")
 
+    # Check whether both key files exist on disk.
+    #
+    # @return [Boolean] true if both +identity.priv+ and +identity.pub+ exist
     def self.exists?
       File.exist?(priv_key_path) && File.exist?(pub_key_path)
     end
 
+    # Generate a new X25519 identity keypair and write to disk.
+    #
+    # @param force [Boolean] overwrite an existing keypair if true
+    # @return [Hash{Symbol => String}] +:public_key+ and +:private_key+ as raw bytes
+    # @raise [RuntimeError] when keypair exists and +force+ is false
     def self.generate!(force: false)
       raise "Keypair already exists. Use --force to overwrite." if exists? && !force
 
@@ -23,21 +52,33 @@ module LocalVault
       kp
     end
 
+    # Read the public key as a base64-encoded string.
+    #
+    # @return [String, nil] base64 public key, or nil if not generated
     def self.public_key
       return nil unless File.exist?(pub_key_path)
       File.read(pub_key_path).strip
     end
 
+    # Read the private key as a base64-encoded string.
+    #
+    # @return [String, nil] base64 private key, or nil if not generated
     def self.private_key_b64
       return nil unless File.exist?(priv_key_path)
       File.read(priv_key_path).strip
     end
 
+    # Read the private key as raw bytes (decoded from base64).
+    #
+    # @return [String, nil] 32 raw bytes, or nil if not generated
     def self.private_key_bytes
       b64 = private_key_b64
       b64 ? Base64.strict_decode64(b64) : nil
     end
 
+    # Check whether identity is fully configured (keypair exists and token is set).
+    #
+    # @return [Boolean] true if keypair exists and an API token is configured
     def self.setup?
       exists? && !Config.token.nil? && !Config.token.empty?
     end

data/lib/localvault/key_slot.rb

@@ -2,12 +2,28 @@ require "rbnacl"
 require "base64"
 
 module LocalVault
+  # Encrypts/decrypts a vault's master key for a specific user's X25519 public key.
+  #
+  # Key slots enable multi-user vault access via sync. Each authorized user
+  # has a slot containing the vault's master key encrypted to their public key.
+  # Uses an ephemeral sender keypair (X25519 Box) — same construction as ShareCrypto.
+  #
+  # @example Create and decrypt a key slot
+  #   slot = KeySlot.create(master_key, recipient_pub_b64)
+  #   recovered = KeySlot.decrypt(slot, recipient_priv_bytes)
+  #   recovered == master_key  # => true
   module KeySlot
+    # Raised when decryption fails (wrong key, tampered data, or invalid format).
     class DecryptionError < StandardError; end
 
     # Encrypt a master key for a recipient's X25519 public key.
-    # Returns a base64-encoded ciphertext string.
-    # Uses an ephemeral sender keypair (same Box construction as ShareCrypto).
+    #
+    # Uses an ephemeral sender keypair so the recipient can decrypt
+    # without knowing who sent it.
+    #
+    # @param master_key [String] raw 32-byte master key to encrypt
+    # @param recipient_pub_key_b64 [String] base64-encoded X25519 public key
+    # @return [String] base64-encoded JSON payload containing the encrypted key slot
     def self.create(master_key, recipient_pub_key_b64)
       recipient_pub = RbNaCl::PublicKey.new(Base64.strict_decode64(recipient_pub_key_b64))
       ephemeral_sk  = RbNaCl::PrivateKey.generate
@@ -25,7 +41,11 @@ module LocalVault
     end
 
     # Decrypt a key slot using the recipient's private key.
-    # Returns the raw master key bytes.
+    #
+    # @param slot_b64 [String] base64-encoded key slot from +create+
+    # @param my_private_key_bytes [String] raw 32-byte X25519 private key
+    # @return [String] raw master key bytes
+    # @raise [DecryptionError] when the key is wrong, data is tampered, or format is invalid
     def self.decrypt(slot_b64, my_private_key_bytes)
       raw        = Base64.strict_decode64(slot_b64)
       payload    = JSON.parse(raw)

data/lib/localvault/mcp/server.rb

@@ -11,6 +11,10 @@ require_relative "tools"
 module LocalVault
   module MCP
     class Server
+      # Create an MCP server reading JSON-RPC from input, writing responses to output.
+      #
+      # @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
@@ -18,6 +22,12 @@ module LocalVault
         @session_vault = load_session_vault  # LOCALVAULT_SESSION fast-path
       end
 
+      # Start the MCP server loop, reading JSON-RPC messages line-by-line.
+      #
+      # Logs available unlocked vaults to stderr on startup. Blocks until
+      # input is exhausted or interrupted (Ctrl-C).
+      #
+      # @return [void]
       def start
         unlocked = unlocked_vault_names
         label = unlocked.empty? ? "no unlocked vaults (run: localvault show)" : "vaults=#{unlocked.join(', ')}"
@@ -41,6 +51,13 @@ module LocalVault
         $stderr.flush
       end
 
+      # Parse and dispatch a single JSON-RPC message.
+      #
+      # Handles +initialize+, +tools/list+, and +tools/call+ methods.
+      # Notifications (no "id" field) return nil.
+      #
+      # @param json_string [String] raw JSON-RPC message
+      # @return [Hash, nil] JSON-RPC response hash, or nil for notifications
       def handle_message(json_string)
         message = JSON.parse(json_string)
 

data/lib/localvault/mcp/tools.rb

@@ -10,6 +10,8 @@ module LocalVault
         }
       }.freeze
 
+      # MCP tool definitions conforming to the MCP tools/list schema.
+      # Each entry specifies a tool name, description, and JSON Schema for input.
       DEFINITIONS = [
         {
           "name" => "get_secret",
@@ -59,7 +61,17 @@ module LocalVault
         }
       ].freeze
 
-      # vault_resolver: callable that takes a vault name (String or nil) and returns a Vault or nil
+      # Dispatch an MCP tool call by name.
+      #
+      # Resolves the target vault via the provided callable, then executes the
+      # requested tool (get_secret, list_secrets, set_secret, or delete_secret).
+      #
+      # @param name [String] tool name (must match a DEFINITIONS entry)
+      # @param arguments [Hash] tool arguments (e.g. {"key" => "API_KEY", "vault" => "prod"})
+      # @param vault_resolver [#call] callable that accepts a vault name (String or nil)
+      #   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)
         unless DEFINITIONS.any? { |t| t["name"] == name }
           raise ArgumentError, "Unknown tool: #{name}"

data/lib/localvault/session_cache.rb

@@ -3,16 +3,32 @@ require "fileutils"
 require "shellwords"
 
 module LocalVault
-  # Caches derived master keys in macOS Keychain (or a fallback file store).
-  # Avoids re-prompting passphrase on every command.
+  # Caches derived master keys to avoid re-prompting passphrase on every command.
   #
-  # Stored payload: "<base64_key>|<expiry_unix_ts>"
-  # macOS: Keychain service "localvault", account: vault name
-  # Linux/other: ~/.localvault/.sessions/<vault_name> (mode 0600)
+  # On macOS, uses the system Keychain (service "localvault", account = vault name).
+  # Falls back to file-based cache at +~/.localvault/.sessions/+ (mode 0600)
+  # when Keychain is unavailable (CI, sandboxed, Linux).
+  #
+  # Entries expire after +DEFAULT_TTL_HOURS+ (8 hours). Expired entries are
+  # cleaned up on read.
+  #
+  # Stored payload format: +"<base64_key>|<expiry_unix_ts>"+
+  #
+  # @example
+  #   SessionCache.set("production", master_key)
+  #   SessionCache.get("production")  # => master_key bytes (or nil if expired)
+  #   SessionCache.clear("production")
   module SessionCache
     DEFAULT_TTL_HOURS = 8
     KEYCHAIN_SERVICE  = "localvault"
 
+    # Retrieve a cached master key for the given vault.
+    #
+    # Returns nil if no entry exists or the entry has expired. Expired entries
+    # are automatically cleaned up.
+    #
+    # @param vault_name [String] the vault name to look up
+    # @return [String, nil] raw master key bytes, or nil if not cached/expired
     def self.get(vault_name)
       payload = keychain_get(vault_name)
       return nil unless payload
@@ -31,16 +47,29 @@ module LocalVault
       nil
     end
 
+    # Cache a master key for the given vault with a time-to-live.
+    #
+    # @param vault_name [String] the vault name to cache
+    # @param master_key [String] raw master key bytes to store
+    # @param ttl_hours [Integer] hours until expiry (default: 8)
+    # @return [void]
     def self.set(vault_name, master_key, ttl_hours: DEFAULT_TTL_HOURS)
       expiry  = Time.now.to_i + (ttl_hours * 3600).to_i
       payload = "#{Base64.strict_encode64(master_key)}|#{expiry}"
       keychain_set(vault_name, payload)
     end
 
+    # Remove the cached master key for a single vault.
+    #
+    # @param vault_name [String] the vault name to clear
+    # @return [void]
     def self.clear(vault_name)
       keychain_delete(vault_name)
     end
 
+    # Remove cached master keys for all known vaults.
+    #
+    # @return [void]
     def self.clear_all
       Store.list_vaults.each { |name| clear(name) }
     end
@@ -87,8 +116,7 @@ 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)
-          File.chmod(0o600, file)
+          File.write(file, payload, perm: 0o600)
         end
       else
         keychain_delete(vault_name)

data/lib/localvault/share_crypto.rb

@@ -3,13 +3,31 @@ require "base64"
 require "json"
 
 module LocalVault
+  # Asymmetric encryption for one-time vault sharing (direct share model).
+  #
+  # Encrypts a secrets hash for a recipient using their X25519 public key.
+  # Uses an ephemeral sender keypair so the sender's identity key is never
+  # transmitted. The recipient decrypts with their private key.
+  #
+  # This is used for the +localvault share --with @handle+ flow (one-time
+  # handoff). For ongoing team access, see KeySlot.
+  #
+  # @example Encrypt and decrypt a share
+  #   payload = ShareCrypto.encrypt_for({"KEY" => "val"}, recipient_pub_b64)
+  #   secrets = ShareCrypto.decrypt_from(payload, recipient_priv_bytes)
   module ShareCrypto
+    # Raised when decryption fails (wrong key, tampered payload, or invalid format).
     class DecryptionError < StandardError; end
 
     # Encrypt a secrets hash for a recipient using their X25519 public key.
-    # Uses an ephemeral sender keypair (Box construction) so the sender's
-    # identity private key is never transmitted.
-    # Returns a base64-encoded JSON blob.
+    #
+    # Uses an ephemeral sender keypair (NaCl Box construction) so the sender's
+    # identity private key is never transmitted. The returned blob contains the
+    # ephemeral public key, nonce, and ciphertext.
+    #
+    # @param secrets [Hash] key-value pairs to encrypt (e.g. {"API_KEY" => "sk-..."})
+    # @param recipient_pub_key_b64 [String] recipient's X25519 public key, base64-encoded
+    # @return [String] base64-encoded JSON payload containing sender_pub, nonce, and ciphertext
     def self.encrypt_for(secrets, recipient_pub_key_b64)
       recipient_pub = RbNaCl::PublicKey.new(Base64.strict_decode64(recipient_pub_key_b64))
       ephemeral_sk  = RbNaCl::PrivateKey.generate
@@ -27,8 +45,15 @@ module LocalVault
       Base64.strict_encode64(JSON.generate(payload))
     end
 
-    # Decrypt an encrypted_payload using the recipient's private key.
-    # Returns the decrypted secrets hash { "KEY" => "value", ... }.
+    # Decrypt a shared payload using the recipient's private key.
+    #
+    # Reverses the envelope produced by {.encrypt_for}, extracting the ephemeral
+    # sender public key and using NaCl Box to decrypt.
+    #
+    # @param encrypted_payload_b64 [String] base64-encoded payload from {.encrypt_for}
+    # @param my_private_key_bytes [String] recipient's raw X25519 private key bytes
+    # @return [Hash] decrypted secrets (e.g. {"API_KEY" => "sk-..."})
+    # @raise [DecryptionError] when the key is wrong, payload is tampered, or format is invalid
     def self.decrypt_from(encrypted_payload_b64, my_private_key_bytes)
       raw     = Base64.strict_decode64(encrypted_payload_b64)
       payload = JSON.parse(raw)