localvault 1.14.0 → 1.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2f77c11508eef73c90760e5a927201f6735a16d836e6890161e89a497e28d917
-  data.tar.gz: 15400be786d2ba53112d1b6b48a1de5bd0518903e5578c859677ec68320f2b8b
+  metadata.gz: 0cfbfdee976a274c577ccb8e782e21f3d64bd1b71ba30e37a5bb583fc1ca54c4
+  data.tar.gz: 9dd3b6663bd7e0eb15d2a6e00fd4d04afb6c0de3962ed76f219418fc4c01207a
 SHA512:
-  metadata.gz: c8fcd7235f9e330cdf7cf2c17528849f7b64b4388e865351ab53c1758b3390d32dd638c2c21e7ba24ff18e7d9c63e7c5e0bd2c66efa87792380d9d8ef12b61b7
-  data.tar.gz: c8491e0b0fcb2e588080496254b4fa04195859ad81d7ce66c38d4e13116d20374fa9f96668cc18cf8dc2a0830affb58ea59df84ed6eb1531c817942f364c54e3
+  metadata.gz: c2849e50bf55078b747403fdc65bde8ae1cabb4c304fd22a422c92f4dd12e2a482ddab6d731b6c18d9cba077e86b93eefdb54dffd2724d28ae087a543efcadbc
+  data.tar.gz: 7d42cfe5bc6c237e6d9b4d9aeefef4e223ff965471c6b417fbf15e7841e1d05a74edfed09221b89b300902ed88ec67afe2e565bd03c46729a2cc5f90debb573c

data/README.md

@@ -125,6 +125,8 @@ localvault exec -- rails server
 | `sync --dry-run` | Preview what sync would do without making changes |
 | `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 diff [NAME]` | Show which keys differ between local and cloud (names only, never values) |
+| `sync merge [NAME]` | Three-way merge local and cloud key by key, then push (`--prefer local\|remote`, `--local KEY`, `--remote KEY`) |
 | `sync status` | Show sync state for all vaults |
 
 ### Team Sharing (v1.3.0)
@@ -201,6 +203,30 @@ localvault sync --dry-run
 #   staging       pull      remote changes
 ```
 
+### Resolving a conflict
+
+When a vault changed on both machines since the last sync, `sync` stops and
+shows which keys differ. Values are never printed.
+
+```bash
+localvault sync
+#   devops  CONFLICT  both local and remote changed since last sync
+#     cloud     added                  REMOTE_ONLY  will take cloud
+#     local     added                  LOCAL_ONLY   will keep local
+#     CONFLICT  changed on both sides  SHARED       needs a choice
+
+localvault sync merge devops                    # clean merge: keeps every change from both sides
+localvault sync merge devops --prefer remote    # conflicting keys: take cloud
+localvault sync merge devops --local SHARED     # or decide per key (--local / --remote, repeatable)
+localvault sync diff devops                     # just look, change nothing
+```
+
+The merge is three-way: each sync records an encrypted snapshot of the
+last-synced state, so a key edited on only one side applies automatically and
+only keys edited differently on both sides need a choice. Deleting a key on one
+side while the other side edits it is also a conflict. `sync push` and
+`sync pull --force` still take one side wholesale.
+
 ## Team Sharing
 
 Share vault access with teammates using X25519 asymmetric encryption. The server never sees plaintext.

data/lib/localvault/cli/sync.rb

@@ -1,10 +1,14 @@
 require "thor"
 require "fileutils"
 require "digest"
+require "io/console"
+require_relative "team_helpers"
 
 module LocalVault
   class CLI
     class Sync < Thor
+      include LocalVault::CLI::TeamHelpers
+
       desc "all", "Sync all vaults bidirectionally (push local changes, pull remote changes)"
       method_option :dry_run, type: :boolean, default: false, desc: "Show what would happen without making changes"
       # Smart bidirectional sync for all vaults.
@@ -18,7 +22,7 @@ module LocalVault
       # - 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)
+      # - Both exist, both changed → CONFLICT (resolve with sync merge / push / pull --force)
       # - Shared vault (not owned by you) → pull-only
       def all
         return unless logged_in?
@@ -94,14 +98,20 @@ module LocalVault
         parts << "#{conflicts} conflict#{conflicts == 1 ? "" : "s"}" if conflicts > 0
         $stdout.puts "Summary: #{parts.join(", ")}"
 
-        # Conflict guidance
+        # Conflict guidance — key names only, never values
         if conflicts > 0
           $stdout.puts
           plan.select { |p| p[:action] == :conflict }.each do |p|
             $stderr.puts "  #{p[:name]} — #{p[:reason]}"
-            $stderr.puts "    Resolve with:"
-            $stderr.puts "      localvault sync push #{p[:name]}   (keep local, overwrite remote)"
-            $stderr.puts "      localvault sync pull #{p[:name]} --force  (keep remote, overwrite local)"
+            result = quiet_merge_preview(p[:name], client)
+            if result
+              print_merge_report(result, indent: "    ", io: $stderr)
+              print_resolution_help(p[:name], result, io: $stderr)
+            else
+              $stderr.puts "    See which keys differ (no values shown):"
+              $stderr.puts "      localvault sync diff #{p[:name]}"
+              print_resolution_help(p[:name], nil, io: $stderr)
+            end
           end
         end
       rescue ApiClient::ApiError => e
@@ -129,6 +139,98 @@ module LocalVault
         perform_pull(vault_name, client, force: options[:force])
       end
 
+      desc "diff [NAME]", "Show which keys differ between local and cloud (names only, no values)"
+      method_option :vault, type: :string, aliases: "-v", desc: "Vault name (same as NAME)"
+      def diff(vault_name = nil)
+        return unless logged_in?
+        vault_name ||= options[:vault] || Config.default_vault
+        client = ApiClient.new(token: Config.token)
+
+        result = build_merge(vault_name, client)
+        return false unless result
+
+        if result.local_changes.empty? && result.remote_changes.empty? &&
+           result.same_changes.empty? && result.conflicts.empty?
+          $stdout.puts "#{vault_name}: local and cloud hold the same secrets."
+          return true
+        end
+
+        $stdout.puts "#{vault_name} — three-way diff against last sync (values never shown)"
+        print_merge_report(result, indent: "  ", io: $stdout)
+        $stdout.puts
+        print_resolution_help(vault_name, result, io: $stdout)
+        true
+      rescue ApiClient::ApiError => e
+        $stderr.puts "Error: #{e.message}"
+        false
+      end
+
+      desc "merge [NAME]", "Three-way merge local and cloud, then push the result"
+      method_option :vault,   type: :string,  aliases: "-v", desc: "Vault name (same as NAME)"
+      method_option :prefer,  type: :string,  enum: %w[local remote], desc: "Resolve every conflicting key from this side"
+      method_option :local,   type: :array,   default: [], desc: "Keys to keep from local (repeatable)"
+      method_option :remote,  type: :array,   default: [], desc: "Keys to take from cloud (repeatable)"
+      method_option :dry_run, type: :boolean, default: false, desc: "Show the merge plan without writing or pushing"
+      method_option :push,    type: :boolean, default: true, desc: "Push after merging (--no-push keeps it local)"
+      # Merge cloud changes into the local vault key by key using the
+      # ancestor snapshot recorded at the last sync. Non-conflicting changes
+      # from both sides apply automatically; a key changed differently on
+      # both sides needs +--prefer+ or a per-key +--local+/+--remote+ pick.
+      def merge(vault_name = nil)
+        return unless logged_in?
+        vault_name ||= options[:vault] || Config.default_vault
+        client = ApiClient.new(token: Config.token)
+
+        both = options[:local] & options[:remote]
+        unless both.empty?
+          $stderr.puts "Error: #{both.join(", ")} given to both --local and --remote. Pick one side per key."
+          return false
+        end
+        picks = {}
+        options[:local].each  { |k| picks[k] = :local }
+        options[:remote].each { |k| picks[k] = :remote }
+        prefer = options[:prefer]&.to_sym
+
+        result = build_merge(vault_name, client, prefer: prefer, picks: picks)
+        return false unless result
+
+        unknown = picks.keys - result.conflict_keys_before_picks
+        unless unknown.empty?
+          $stderr.puts "Warning: #{unknown.join(", ")} #{unknown.size == 1 ? "is" : "are"} not in conflict — ignored."
+        end
+
+        $stdout.puts "#{vault_name} — merge plan (values never shown)"
+        print_merge_report(result, indent: "  ", io: $stdout)
+
+        unless result.clean?
+          $stdout.puts
+          $stderr.puts "Error: #{result.conflicts.size} key#{result.conflicts.size == 1 ? "" : "s"} changed on both sides. Choose a side:"
+          print_resolution_help(vault_name, result, io: $stderr, merge_only: true)
+          return false
+        end
+
+        if options[:dry_run]
+          $stdout.puts
+          $stdout.puts "Dry run — no changes made."
+          return true
+        end
+
+        master_key = @merge_master_key
+        vault = Vault.new(name: vault_name, master_key: master_key)
+        vault.replace(result.merged)
+        $stdout.puts "  merged #{vault_name} locally"
+
+        unless options[:push]
+          $stdout.puts "  not pushed (--no-push). Push later with: localvault sync push #{vault_name}"
+          return true
+        end
+
+        perform_push(vault_name, client)
+      rescue ApiClient::ApiError => e
+        $stderr.puts "Error: #{e.message}"
+        false
+      end
+
       desc "status", "Show sync status for all vaults"
       def status
         return unless logged_in?
@@ -217,6 +319,8 @@ module LocalVault
           end
 
           key_slots = bootstrap_owner_slot(key_slots, store)
+          key_slots = refresh_scoped_slots(key_slots, store)
+          return false unless key_slots
           blob = SyncBundle.pack_v3(store, owner: owner, key_slots: key_slots)
         else
           blob = SyncBundle.pack(store)
@@ -224,11 +328,8 @@ module LocalVault
 
         client.push_vault(vault_name, blob)
 
-        # Record sync state
-        SyncState.new(vault_name).write!(
-          checksum: SyncState.local_checksum(store),
-          direction: "push"
-        )
+        # Record sync state + ancestor snapshot for future merges
+        SyncState.new(vault_name).record!(store, direction: "push")
 
         $stdout.puts "  pushed #{vault_name} (#{blob.bytesize} bytes)"
         true
@@ -266,11 +367,8 @@ module LocalVault
           store.write_encrypted(data[:secrets])
         end
 
-        # Record sync state
-        SyncState.new(vault_name).write!(
-          checksum: SyncState.local_checksum(store),
-          direction: "pull"
-        )
+        # Record sync state + ancestor snapshot for future merges
+        SyncState.new(vault_name).record!(store, direction: "pull")
 
         $stdout.puts "  pulled #{vault_name}"
 
@@ -401,10 +499,7 @@ module LocalVault
       # @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"
-        )
+        SyncState.new(vault_name).record!(store, direction: "adopt")
         $stdout.puts "  baselined #{vault_name} (already in sync)"
         true
       rescue StandardError => e
@@ -462,6 +557,161 @@ module LocalVault
         false
       end
 
+      # ── Merge helpers ────────────────────────────────────────────
+
+      # Decrypt base / local / remote and run the three-way merge. Prompts
+      # for the passphrase when the vault isn't unlocked. Returns nil (after
+      # printing the reason) when anything needed is missing.
+      #
+      # @return [SyncMerge::Result, nil]
+      def build_merge(vault_name, client, prefer: nil, picks: {})
+        store = Store.new(vault_name)
+        unless store.exists?
+          $stderr.puts "Error: Vault '#{vault_name}' does not exist locally. Use: localvault sync pull #{vault_name}"
+          return nil
+        end
+
+        master_key = ensure_master_key(vault_name)
+        return nil unless master_key
+        @merge_master_key = master_key
+
+        blob = client.pull_vault(vault_name)
+        unless blob.is_a?(String) && !blob.empty?
+          $stderr.puts "Error: Vault '#{vault_name}' has no cloud copy. Use: localvault sync push #{vault_name}"
+          return nil
+        end
+        data = SyncBundle.unpack(blob, expected_name: vault_name)
+
+        # Team vaults: only the owner holds the full plaintext and may push, so
+        # only the owner can merge. Members take the cloud copy instead.
+        handle = Config.inventlist_handle
+        if data[:owner] && data[:owner] != handle
+          my_slot = (data[:key_slots] || {})[handle]
+          access  = my_slot.is_a?(Hash) && my_slot["scopes"].is_a?(Array) ? "scoped" : "member"
+          $stderr.puts "Error: '#{vault_name}' is a team vault owned by @#{data[:owner]}; you have #{access} access."
+          $stderr.puts "Only the owner can merge or push. Take the cloud copy with:"
+          $stderr.puts "  localvault sync pull #{vault_name} --force"
+          return nil
+        end
+
+        merge_secrets(vault_name, store, master_key, data[:secrets], prefer: prefer, picks: picks)
+      rescue SyncBundle::UnpackError => e
+        $stderr.puts "Error: Could not parse cloud bundle for '#{vault_name}': #{e.message}"
+        nil
+      rescue Crypto::DecryptionError
+        $stderr.puts "Error: The cloud copy of '#{vault_name}' is encrypted with a different key (rekeyed or rotated elsewhere)."
+        $stderr.puts "Merge is not possible. Take one side:"
+        print_resolution_help(vault_name, nil, io: $stderr)
+        nil
+      rescue ApiClient::ApiError => e
+        if e.status == 404
+          $stderr.puts "Error: Vault '#{vault_name}' not found in cloud. Use: localvault sync push #{vault_name}"
+          nil
+        else
+          raise
+        end
+      end
+
+      # Same as +build_merge+ but never prompts and never prints — used by
+      # +sync all+ to enrich conflict output when the key is already cached.
+      #
+      # @return [SyncMerge::Result, nil]
+      def quiet_merge_preview(vault_name, client)
+        master_key = SessionCache.get(vault_name)
+        return nil unless master_key
+        store = Store.new(vault_name)
+        blob  = client.pull_vault(vault_name)
+        return nil unless blob.is_a?(String) && !blob.empty?
+        remote_bytes = SyncBundle.unpack(blob)[:secrets]
+        merge_secrets(vault_name, store, master_key, remote_bytes)
+      rescue ApiClient::ApiError, SyncBundle::UnpackError, Crypto::DecryptionError,
+             SyncMerge::StructureError, JSON::ParserError
+        nil
+      end
+
+      def merge_secrets(vault_name, store, master_key, remote_bytes, prefer: nil, picks: {})
+        base_bytes = SyncState.new(vault_name).read_base
+        base   = base_bytes ? decrypt_secrets(base_bytes, master_key) : nil
+        local  = decrypt_secrets(store.read_encrypted, master_key)
+        remote = decrypt_secrets(remote_bytes, master_key)
+        result = SyncMerge.merge(base, local, remote, prefer: prefer, picks: picks)
+        # Remember what needed a choice before picks so the CLI can validate them.
+        unresolved = (prefer || !picks.empty?) ? SyncMerge.merge(base, local, remote) : result
+        result.conflict_keys_before_picks = unresolved.conflicts.map(&:key)
+        result
+      rescue JSON::ParserError
+        # Never echo the parser's excerpt: it would contain decrypted bytes.
+        $stderr.puts "Error: decrypted secrets for '#{vault_name}' are not valid JSON (corrupt vault data). Merge aborted."
+        nil
+      rescue SyncMerge::StructureError => e
+        $stderr.puts "Error: cannot merge '#{vault_name}': #{e.message}."
+        $stderr.puts "Rename one of them on one side, or take a whole side:"
+        print_resolution_help(vault_name, nil, io: $stderr)
+        nil
+      end
+
+      def decrypt_secrets(bytes, master_key)
+        return {} if bytes.nil? || bytes.empty?
+        JSON.parse(Crypto.decrypt(bytes, master_key))
+      end
+
+      # Print the key-level report. Only key names and change kinds appear.
+      def print_merge_report(result, indent:, io:)
+        lines = []
+        result.remote_changes.each { |c| lines << ["cloud",    c.kind.to_s, c.key, "will take cloud"] }
+        result.local_changes.each  { |c| lines << ["local",    c.kind.to_s, c.key, "will keep local"] }
+        result.same_changes.each   { |c| lines << ["both",     c.kind.to_s, c.key, "identical, keep"] }
+        result.conflicts.each      { |c| lines << ["CONFLICT", conflict_label(c.kind), c.key, "needs a choice"] }
+
+        if lines.empty?
+          io.puts "#{indent}no key differences"
+          return
+        end
+
+        w0 = lines.map { |l| l[0].length }.max
+        w1 = lines.map { |l| l[1].length }.max
+        w2 = lines.map { |l| l[2].length }.max
+        lines.each do |side, kind, key, note|
+          io.puts "#{indent}#{side.ljust(w0)}  #{kind.ljust(w1)}  #{key.ljust(w2)}  #{note}"
+        end
+      end
+
+      def conflict_label(kind)
+        case kind
+        when :local_deleted  then "deleted here, changed in cloud"
+        when :remote_deleted then "changed here, deleted in cloud"
+        when :structure      then "secret vs group, differs per side"
+        else                      "changed on both sides"
+        end
+      end
+
+      # Print the exact commands that resolve this vault's state.
+      def print_resolution_help(vault_name, result, io:, merge_only: false)
+        if result.nil? || result.clean?
+          io.puts "    Merge (keeps every change from both sides):" unless merge_only
+          io.puts "      localvault sync merge #{vault_name}"
+        else
+          keys = result.conflicts.map(&:key)
+          io.puts "    Merge, choosing a side for the conflicting key#{keys.size == 1 ? "" : "s"}:"
+          io.puts "      localvault sync merge #{vault_name} --prefer local"
+          io.puts "      localvault sync merge #{vault_name} --prefer remote"
+          io.puts "    Or pick per key:"
+          example = keys.size == 1 ? "--local #{keys.first}" : "--local #{keys.first} --remote #{keys[1]}"
+          io.puts "      localvault sync merge #{vault_name} #{example}"
+        end
+        return if merge_only
+        io.puts "    Or take one side entirely:"
+        io.puts "      localvault sync push #{vault_name}          (keep local, overwrite cloud)"
+        io.puts "      localvault sync pull #{vault_name} --force  (keep cloud, overwrite local)"
+      end
+
+      def prompt_passphrase(msg = "Passphrase: ")
+        IO.console&.getpass(msg) || $stdin.gets&.chomp || ""
+      rescue Interrupt
+        $stderr.puts
+        ""
+      end
+
       def logged_in?
         return true if Config.token
 
@@ -497,6 +747,45 @@ module LocalVault
         {}
       end
 
+      # Scoped members read a per-member blob, not the vault ciphertext, so a
+      # push must rebuild those blobs from the current plaintext or members
+      # keep seeing the pre-push values. Needs the master key; when the vault
+      # is locked the push is refused rather than publishing inconsistent
+      # views. Returns nil when the push must not proceed.
+      #
+      # @return [Hash, nil] refreshed key slots, or nil to abort the push
+      def refresh_scoped_slots(key_slots, store)
+        scoped = key_slots.select { |_, s| s.is_a?(Hash) && s["scopes"].is_a?(Array) && s["pub"].is_a?(String) }
+        return key_slots if scoped.empty?
+
+        master_key = SessionCache.get(store.vault_name)
+        unless master_key
+          $stderr.puts "Error: '#{store.vault_name}' has scoped members whose copies must be rebuilt on push, but the vault is locked."
+          $stderr.puts "Run: localvault unlock #{store.vault_name} && localvault sync push #{store.vault_name}"
+          return nil
+        end
+
+        vault   = Vault.new(name: store.vault_name, master_key: master_key)
+        secrets = vault.all
+        scoped.each do |h, slot|
+          filtered   = vault.filter(slot["scopes"], from: secrets)
+          member_key = RbNaCl::Random.random_bytes(32)
+          key_slots[h] = slot.merge(
+            "enc_key" => KeySlot.create(member_key, slot["pub"]),
+            "blob"    => Base64.strict_encode64(Crypto.encrypt(JSON.generate(filtered), member_key))
+          )
+        rescue ArgumentError, KeySlot::DecryptionError
+          # A member whose stored public key is unusable could never decrypt
+          # anything anyway; keep their old slot rather than block the owner.
+          $stderr.puts "  warning: @#{h}'s public key is invalid; their scoped copy was not refreshed."
+        end
+        key_slots
+      rescue Crypto::DecryptionError, JSON::ParserError => e
+        # Fixed message: a parser error's excerpt would contain decrypted bytes.
+        $stderr.puts "Error: could not read '#{store.vault_name}' to rebuild scoped members' copies (#{e.class.name.split("::").last}). Push refused."
+        nil
+      end
+
       def bootstrap_owner_slot(key_slots, store)
         return key_slots unless Identity.exists?
         handle = Config.inventlist_handle

data/lib/localvault/cli/team_helpers.rb

@@ -45,6 +45,10 @@ module LocalVault
       rescue Crypto::DecryptionError
         $stderr.puts "Error: Wrong passphrase for vault '#{vault_name}'."
         nil
+      rescue JSON::ParserError
+        # Never echo the parser's excerpt: it would contain decrypted bytes.
+        $stderr.puts "Error: Vault '#{vault_name}' decrypted but its data is not valid JSON (corrupt vault data)."
+        nil
       end
 
       def load_key_slots(client, vault_name)

data/lib/localvault/cli.rb

@@ -501,6 +501,12 @@ module LocalVault
         .render
 
       $stdout.puts table
+
+      strays = Store.stray_entries
+      unless strays.empty?
+        $stderr.puts "Ignored #{strays.size} non-vault entr#{strays.size == 1 ? "y" : "ies"} in #{Config.vaults_path}: #{strays.map { |s| "'#{s}'" }.join(", ")}"
+        $stderr.puts "A vault is a folder named [a-z0-9_-] with a meta.yml inside."
+      end
     end
 
     desc "unlock [VAULT]", "Cache passphrase for session and output session token"

data/lib/localvault/store.rb

@@ -188,13 +188,40 @@ module LocalVault
     # List all vault names found on disk.
     #
     # @return [Array<String>] sorted vault names
+    # Names of the vaults on disk: directories under +vaults/+ that have a
+    # valid vault name and a +meta.yml+. Anything else (a stray file, a
+    # hand-made folder with spaces in its name, a half-deleted vault) is
+    # skipped so callers can always +Store.new+ what they get back; see
+    # +stray_entries+ to surface those.
+    #
+    # @return [Array<String>] sorted vault names
     def self.list_vaults
       vaults_dir = Config.vaults_path
       return [] unless File.directory?(vaults_dir)
 
       Dir.children(vaults_dir)
-        .select { |name| File.directory?(File.join(vaults_dir, name)) }
+        .select { |name| vault_dir?(vaults_dir, name) }
+        .sort
+    end
+
+    # Entries under +vaults/+ that +list_vaults+ ignores, so a listing can
+    # tell the user why a folder they can see is not a vault.
+    #
+    # @return [Array<String>] sorted entry names
+    def self.stray_entries
+      vaults_dir = Config.vaults_path
+      return [] unless File.directory?(vaults_dir)
+
+      Dir.children(vaults_dir)
+        .reject { |name| name.start_with?(".") || vault_dir?(vaults_dir, name) }
         .sort
     end
+
+    def self.vault_dir?(vaults_dir, name)
+      name.match?(VAULT_NAME_PATTERN) && name.length <= 64 &&
+        File.directory?(File.join(vaults_dir, name)) &&
+        File.exist?(File.join(vaults_dir, name, "meta.yml"))
+    end
+    private_class_method :vault_dir?
   end
 end

data/lib/localvault/sync_merge.rb

@@ -0,0 +1,204 @@
+require "json"
+
+module LocalVault
+  # Three-way merge of vault secrets: base (last synced), local, remote.
+  #
+  # Works on flattened dot-notation keys (+"app.DB_URL"+) so groups and
+  # scalars compare uniformly. Values never leave this module in any report —
+  # callers get key names plus change kinds, which is all a human needs to
+  # decide, and all that is safe to print.
+  #
+  # Rules per key:
+  # - unchanged on both sides                    → keep
+  # - changed on one side only                   → take that side
+  # - changed on both sides to the same value    → keep
+  # - changed on both sides to different values  → conflict
+  #
+  # "changed" covers add, modify and delete relative to base. With no base
+  # (first sync between two pre-existing vaults) nothing can be proven
+  # deleted, so the merge is a union: keys on one side only are added, keys
+  # on both sides with different values are conflicts.
+  module SyncMerge
+    # Raised when merged keys cannot coexist in one nested hash, e.g. a scalar
+    # +app+ from one side and a group +app.X+ from the other.
+    class StructureError < StandardError; end
+
+    Change = Struct.new(:key, :kind, keyword_init: true)
+
+    # Result of a merge. +merged+ is the nested secrets hash ready to write;
+    # +conflicts+ is a list of keys that still need a human choice.
+    Result = Struct.new(:merged, :local_changes, :remote_changes, :conflicts, :same_changes,
+                        :conflict_keys_before_picks, keyword_init: true) do
+      def clean?
+        conflicts.empty?
+      end
+    end
+
+    # @param base [Hash, nil] nested secrets at last sync, nil if unknown
+    # @param local [Hash] nested secrets on disk
+    # @param remote [Hash] nested secrets in the cloud bundle
+    # @param prefer [Symbol, nil] +:local+ or +:remote+ — resolves every conflict
+    # @param picks [Hash{String => Symbol}] per-key resolution, key => :local | :remote
+    # @return [Result]
+    def self.merge(base, local, remote, prefer: nil, picks: {})
+      b = base ? flatten(base) : nil
+      l = flatten(local)
+      r = flatten(remote)
+
+      merged         = {}
+      local_changes  = []
+      remote_changes = []
+      same_changes   = []
+      conflicts      = []
+
+      structural = structural_conflicts(base, local, remote)
+      structural.each do |root|
+        side = picks[root] || prefer
+        source = side == :remote ? r : l
+        source.each { |k, v| merged[k] = v if root_of(k) == root }
+        conflicts << Change.new(key: root, kind: :structure) unless %i[local remote].include?(side)
+      end
+
+      (l.keys | r.keys | (b ? b.keys : [])).sort.each do |key|
+        next if structural.include?(root_of(key))
+        bv = b && b[key]
+        lv = l[key]
+        rv = r[key]
+
+        local_changed  = b ? lv != bv : false
+        remote_changed = b ? rv != bv : false
+
+        if b.nil?
+          # No ancestor: union, conflict only when both present and different.
+          if lv && rv && lv != rv
+            resolve_conflict(key, lv, rv, prefer, picks, merged, conflicts)
+          elsif lv.nil?
+            merged[key] = rv
+            remote_changes << Change.new(key: key, kind: :added)
+          elsif rv.nil?
+            merged[key] = lv
+            local_changes << Change.new(key: key, kind: :added)
+          else
+            merged[key] = lv
+          end
+          next
+        end
+
+        if !local_changed && !remote_changed
+          merged[key] = lv unless lv.nil?
+        elsif local_changed && !remote_changed
+          merged[key] = lv unless lv.nil?
+          local_changes << Change.new(key: key, kind: kind_of(bv, lv))
+        elsif !local_changed && remote_changed
+          merged[key] = rv unless rv.nil?
+          remote_changes << Change.new(key: key, kind: kind_of(bv, rv))
+        elsif lv == rv
+          merged[key] = lv unless lv.nil?
+          same_changes << Change.new(key: key, kind: kind_of(bv, lv))
+        else
+          resolve_conflict(key, lv, rv, prefer, picks, merged, conflicts)
+        end
+      end
+
+      Result.new(
+        merged:         unflatten(merged),
+        local_changes:  local_changes,
+        remote_changes: remote_changes,
+        same_changes:   same_changes,
+        conflicts:      conflicts
+      )
+    end
+
+    # Flatten one level of grouping into dot keys. Values are stringified so
+    # comparison is by content, matching how +Vault#set+ stores them.
+    #
+    # @param hash [Hash] nested secrets
+    # @return [Hash{String => String}]
+    def self.flatten(hash)
+      out = {}
+      hash.each do |k, v|
+        if v.is_a?(Hash)
+          v.each { |sk, sv| out["#{k}.#{sk}"] = sv.to_s }
+        else
+          out[k.to_s] = v.to_s
+        end
+      end
+      out
+    end
+
+    # Inverse of +flatten+. Raises +StructureError+ when a scalar and a group
+    # share a name.
+    #
+    # @param flat [Hash{String => String}]
+    # @return [Hash]
+    def self.unflatten(flat)
+      out = {}
+      flat.each do |key, value|
+        if key.include?(".")
+          group, sub = key.split(".", 2)
+          out[group] ||= {}
+          raise StructureError, "'#{group}' is both a secret and a group" unless out[group].is_a?(Hash)
+          out[group][sub] = value
+        else
+          raise StructureError, "'#{key}' is both a secret and a group" if out[key].is_a?(Hash)
+          out[key] = value
+        end
+      end
+      out
+    end
+
+    # Roots whose shape (scalar / group / absent) differs between local and
+    # remote, with both sides having moved away from base. With no base, only
+    # a present-on-both scalar-vs-group disagreement is structural; a key
+    # missing on one side is an ordinary addition.
+    def self.structural_conflicts(base, local, remote)
+      roots = local.keys | remote.keys | (base ? base.keys : [])
+      roots.select do |root|
+        lk = shape(local[root])
+        rk = shape(remote[root])
+        next false if lk == rk
+        next(lk != :absent && rk != :absent) if base.nil?
+        bk = shape(base[root])
+        lk != bk && rk != bk
+      end
+    end
+
+    def self.shape(value)
+      return :absent if value.nil?
+      value.is_a?(Hash) ? :group : :scalar
+    end
+
+    def self.root_of(key)
+      key.split(".", 2).first
+    end
+
+    def self.kind_of(before, after)
+      return :deleted if after.nil?
+      return :added   if before.nil?
+      :modified
+    end
+
+    def self.resolve_conflict(key, lv, rv, prefer, picks, merged, conflicts)
+      side = picks[key] || prefer
+      case side
+      when :local
+        merged[key] = lv unless lv.nil?
+      when :remote
+        merged[key] = rv unless rv.nil?
+      else
+        # Leave local in place so an unresolved merge never drops a key.
+        merged[key] = lv unless lv.nil?
+        conflicts << Change.new(key: key, kind: conflict_kind(lv, rv))
+      end
+    end
+
+    # Describe a conflict without values: which side deleted, or both modified.
+    def self.conflict_kind(lv, rv)
+      return :local_deleted  if lv.nil?
+      return :remote_deleted if rv.nil?
+      :both_modified
+    end
+
+    private_class_method :kind_of, :resolve_conflict, :conflict_kind, :structural_conflicts, :shape, :root_of
+  end
+end

data/lib/localvault/sync_state.rb

@@ -13,6 +13,12 @@ module LocalVault
   class SyncState
     FILENAME = ".sync_state"
 
+    # Ciphertext snapshot of secrets.enc as of the last successful sync. This
+    # is the common ancestor a three-way merge needs (see +SyncMerge+); the
+    # checksum alone only says *that* both sides drifted, not *which keys*.
+    # Same bytes and same file mode as secrets.enc, so it leaks nothing new.
+    BASE_FILENAME = ".sync_base"
+
     attr_reader :vault_name
 
     def initialize(vault_name)
@@ -23,10 +29,22 @@ module LocalVault
       File.join(Config.vaults_path, vault_name, FILENAME)
     end
 
+    def base_path
+      File.join(Config.vaults_path, vault_name, BASE_FILENAME)
+    end
+
     def exists?
       File.exist?(path)
     end
 
+    # @return [String, nil] encrypted secrets bytes as of the last sync, or nil
+    #   when no snapshot was recorded (older clients, or an empty vault).
+    def read_base
+      return nil unless File.exist?(base_path)
+      bytes = File.binread(base_path)
+      bytes.empty? ? nil : bytes
+    end
+
     # @return [Hash, nil] parsed YAML data or nil
     def read
       return nil unless exists?
@@ -46,8 +64,11 @@ module LocalVault
     # Record a successful sync operation.
     #
     # @param checksum [String] SHA256 hex of the local secrets.enc
-    # @param direction [String] "push" or "pull"
-    def write!(checksum:, direction:)
+    # @param direction [String] "push", "pull", "adopt" or "merge"
+    # @param base [String, nil] encrypted secrets bytes to snapshot as the
+    #   merge ancestor. Pass the bytes that +checksum+ was computed from. nil
+    #   (or empty) removes any previous snapshot.
+    def write!(checksum:, direction:, base: nil)
       FileUtils.mkdir_p(File.dirname(path), mode: 0o700)
       data = {
         "last_synced_checksum" => checksum,
@@ -56,6 +77,25 @@ module LocalVault
       }
       File.write(path, YAML.dump(data))
       File.chmod(0o600, path)
+      write_base!(base)
+    end
+
+    # Record both checksum and ancestor snapshot from a store in one call.
+    #
+    # @param store [Store] vault store whose current secrets.enc is now synced
+    # @param direction [String] see +write!+
+    def record!(store, direction:)
+      bytes = store.read_encrypted
+      write!(checksum: self.class.local_checksum(store), direction: direction, base: bytes)
+    end
+
+    def write_base!(bytes)
+      if bytes.nil? || bytes.empty?
+        FileUtils.rm_f(base_path)
+        return
+      end
+      File.binwrite(base_path, bytes)
+      File.chmod(0o600, base_path)
     end
 
     # Compute the SHA256 hex digest of a vault's local secrets.enc.

data/lib/localvault/vault.rb

@@ -111,6 +111,24 @@ module LocalVault
       end
     end
 
+    # Replace the entire secrets hash. Used by sync merge, which computes the
+    # full merged result and needs deletions applied as well as additions.
+    #
+    # @param secrets [Hash] nested secrets hash (groups as nested hashes)
+    # @return [void]
+    # @raise [InvalidKeyName] when any key contains invalid characters
+    def replace(secrets)
+      secrets.each do |k, v|
+        if v.is_a?(Hash)
+          validate_key_segment!(k)
+          v.each_key { |sk| validate_key_segment!(sk) }
+        else
+          validate_key!(k)
+        end
+      end
+      write_secrets(secrets)
+    end
+
     # 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"]

data/lib/localvault/version.rb

@@ -1,3 +1,3 @@
 module LocalVault
-  VERSION = "1.14.0"
+  VERSION = "1.15.0"
 end

data/lib/localvault.rb

@@ -15,6 +15,7 @@ require_relative "localvault/key_slot"
 require_relative "localvault/api_client"
 require_relative "localvault/sync_bundle"
 require_relative "localvault/sync_state"
+require_relative "localvault/sync_merge"
 
 module LocalVault
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: localvault
 version: !ruby/object:Gem::Version
-  version: 1.14.0
+  version: 1.15.0
 platform: ruby
 authors:
 - Nauman Tariq
@@ -137,6 +137,7 @@ files:
 - lib/localvault/stdin_secret_input.rb
 - lib/localvault/store.rb
 - lib/localvault/sync_bundle.rb
+- lib/localvault/sync_merge.rb
 - lib/localvault/sync_state.rb
 - lib/localvault/vault.rb
 - lib/localvault/vault_resolver.rb