keepass_kpscript 1.0.0

data/lib/keepass_kpscript/select.rb

@@ -0,0 +1,110 @@
+module KeepassKpscript
+
+  # Define rules to select entries from a Keepass database.
+  # Those rules are taken from https://keepass.info/help/v2_dev/scr_sc_index.html#editentry
+  class Select
+
+    # Constructor
+    def initialize
+      @selectors = []
+    end
+
+    # Select a set of given field values
+    #
+    # Parameters::
+    # * *selection* (Hash<String or Symbol, String>): Set of { field_name => field_value } to be selected.
+    # Result::
+    # * self: The selector itself, useful for chaining
+    def fields(selection)
+      selection.each do |field_name, field_value|
+        @selectors << "-ref-#{field_name}:\"#{field_value}\""
+      end
+      self
+    end
+
+    # Select a UUID
+    #
+    # Parameters::
+    # * *id* (String): The UUID
+    # Result::
+    # * self: The selector itself, useful for chaining
+    def uuid(id)
+      @selectors << "-refx-UUID:#{id}"
+      self
+    end
+
+    # Select a list of tags
+    #
+    # Parameters::
+    # * *lst_tags* (Array<String>): List of tags to select
+    # Result::
+    # * self: The selector itself, useful for chaining
+    def tags(*lst_tags)
+      @selectors << "-refx-Tags:\"#{lst_tags.flatten.join(',')}\""
+      self
+    end
+
+    # Select entries that expire
+    #
+    # Parameters:
+    # * *switch* (Boolean): Do we select entries that expire? [default = true]
+    # Result::
+    # * self: The selector itself, useful for chaining
+    def expires(switch = true)
+      @selectors << "-refx-Expires:#{switch ? 'true' : 'false'}"
+      self
+    end
+
+    # Select entries that have expired
+    #
+    # Parameters:
+    # * *switch* (Boolean): Do we select entries that have expired? [default = true]
+    # Result::
+    # * self: The selector itself, useful for chaining
+    def expired(switch = true)
+      @selectors << "-refx-Expired:#{switch ? 'true' : 'false'}"
+      self
+    end
+
+    # Select entries that have a given parent group
+    #
+    # Parameters:
+    # * *group_name* (String): Name of the parent group
+    # Result::
+    # * self: The selector itself, useful for chaining
+    def group(group_name)
+      @selectors << "-refx-Group:\"#{group_name}\""
+      self
+    end
+
+    # Select entries that have a given group path
+    #
+    # Parameters:
+    # * *group_path_entries* (Array<String>): Group path
+    # Result::
+    # * self: The selector itself, useful for chaining
+    def group_path(*group_path_entries)
+      @selectors << "-refx-GroupPath:\"#{group_path_entries.flatten.join('/')}\""
+      self
+    end
+
+    # Select all entries
+    #
+    # Result::
+    # * self: The selector itself, useful for chaining
+    def all
+      @selectors << '-refx-All'
+      self
+    end
+
+    # Return the command-line string selecting the entries
+    #
+    # Result::
+    # * String: The command-line string
+    def to_s
+      @selectors.join(' ')
+    end
+
+  end
+
+end

data/lib/keepass_kpscript/version.rb

@@ -0,0 +1,5 @@
+module KeepassKpscript
+
+  VERSION = '1.0.0'
+
+end

data/spec/keepass_kpscript_test/helpers.rb

@@ -0,0 +1,56 @@
+require 'stringio'
+require 'keepass_kpscript'
+
+module KeepassKpscriptTest
+
+  module Helpers
+
+    # Expect some calls to be done on KPScript
+    #
+    # Parameters::
+    # * *expected_calls* (Array<[String, String or Hash]>): The list of calls and their corresponding mocked response:
+    #   * String: Mocked stdout
+    #   * Hash<Symbol,Object>: More complete structure defining the mocked response:
+    #     * *exit_status* (Integer): The command exit status [default: 0]
+    #     * *stdout* (String): The command stdout
+    def expect_calls_to_kpscript(expected_calls)
+      if expected_calls.empty?
+        expect(Open3).not_to receive(:popen3)
+      else
+        expected_calls.each do |(expected_call, mocked_call)|
+          mocked_call = { stdout: mocked_call } if mocked_call.is_a?(String)
+          mocked_call[:exit_status] = 0 unless mocked_call.key?(:exit_status)
+          expect(Open3).to receive(:popen3).with(expected_call) do |_cmd, &block|
+            wait_thr_double = instance_double(Process::Waiter)
+            allow(wait_thr_double).to receive(:value) do
+              wait_thr_value_double = instance_double(Process::Status)
+              allow(wait_thr_value_double).to receive(:exitstatus) do
+                mocked_call[:exit_status]
+              end
+              wait_thr_value_double
+            end
+            block.call(
+              StringIO.new,
+              StringIO.new(mocked_call[:stdout]),
+              StringIO.new,
+              wait_thr_double
+            )
+          end
+        end
+      end
+    end
+
+  end
+
+end
+
+RSpec.configure do |config|
+  config.include KeepassKpscriptTest::Helpers
+
+  config.before do
+    # Make sure log debugs are not output on screen during tests
+    # rubocop:disable RSpec/AnyInstance
+    allow_any_instance_of(KeepassKpscript::Kpscript).to receive(:log_debug).and_yield
+    # rubocop:enable RSpec/AnyInstance
+  end
+end

data/spec/keepass_kpscript_test/tests/keepass_kpscript/database_spec.rb

@@ -0,0 +1,240 @@
+describe KeepassKpscript::Database do
+
+  shared_examples 'a database' do
+
+    subject(:database) { kpscript.open('/path/to/my_db.kdbx', password: 'MyPassword') }
+
+    let(:kpscript) { KeepassKpscript.use('/path/to/KPScript.exe', debug: debug) }
+
+    it 'gets a simple password for an entry title' do
+      expect_calls_to_kpscript [
+        [
+          '/path/to/KPScript.exe "/path/to/my_db.kdbx" -pw:"MyPassword" -c:GetEntryString -ref-Title:"MyEntryTitle" -Field:"Password"',
+          <<~EO_STDOUT
+            MyEntryPassword
+            OK: Operation completed successfully.
+          EO_STDOUT
+        ]
+      ]
+      expect(database.password_for('MyEntryTitle')).to eq 'MyEntryPassword'
+    end
+
+    it 'fails with an error silencing secrets when KPScript returns a non-zero exit status' do
+      expect_calls_to_kpscript [
+        [
+          '/path/to/KPScript.exe "/path/to/my_db.kdbx" -pw:"MyPassword" -c:GetEntryString -ref-Title:"MyEntryTitle" -Field:"Password"',
+          {
+            stdout: '',
+            exit_status: 1
+          }
+        ]
+      ]
+      expect { database.password_for('MyEntryTitle') }.to raise_error 'Error while executing /path/to/KPScript.exe "/path/to/my_db.kdbx" -pw:"XXXXX" -c:GetEntryString -ref-Title:"MyEntryTitle" -Field:"Password" (exit status: 1)'
+    end
+
+    it 'fails with an error silencing secrets when KPScript returns an error message' do
+      expect_calls_to_kpscript [
+        [
+          '/path/to/KPScript.exe "/path/to/my_db.kdbx" -pw:"MyPassword" -c:GetEntryString -ref-Title:"MyEntryTitle" -Field:"Password"',
+          'E: Error reading database.'
+        ]
+      ]
+      expect { database.password_for('MyEntryTitle') }.to raise_error 'Error returned by /path/to/KPScript.exe "/path/to/my_db.kdbx" -pw:"XXXXX" -c:GetEntryString -ref-Title:"MyEntryTitle" -Field:"Password": E: Error reading database.'
+    end
+
+    it 'reads entries string' do
+      expect_calls_to_kpscript [
+        [
+          '/path/to/KPScript.exe "/path/to/my_db.kdbx" -pw:"MyPassword" -c:GetEntryString -refx-All -Field:"Field"',
+          <<~EO_STDOUT
+            Value1
+            Value2
+            Value3
+            OK: Operation completed successfully.
+          EO_STDOUT
+        ]
+      ]
+      expect(database.entries_string(kpscript.select.all, 'Field')).to eq %w[Value1 Value2 Value3]
+    end
+
+    it 'reads entries string in a secured way with secret strings' do
+      expect_calls_to_kpscript [
+        [
+          '/path/to/KPScript.exe "/path/to/my_db.kdbx" -pw:"MyPassword" -c:GetEntryString -refx-All -Field:"Field"',
+          <<~EO_STDOUT
+            Value1
+            Value2
+            Value3
+            OK: Operation completed successfully.
+          EO_STDOUT
+        ]
+      ]
+      leaked_values = nil
+      expect do
+        database.with_entries_string(kpscript.select.all, 'Field') do |values|
+          expect(values.map(&:to_s)).to eq %w[XXXXX XXXXX XXXXX]
+          expect(values.map(&:to_unprotected)).to eq %w[Value1 Value2 Value3]
+          leaked_values = values
+        end
+      end.not_to raise_error
+      expect(leaked_values.map(&:to_s)).to eq %w[XXXXX XXXXX XXXXX]
+      expect(leaked_values.map(&:to_unprotected)).to eq ["\x00\x00\x00\x00\x00\x00", "\x00\x00\x00\x00\x00\x00", "\x00\x00\x00\x00\x00\x00"]
+    end
+
+    {
+      fail_if_not_exists: '-FailIfNotExists',
+      fail_if_no_entry: '-FailIfNoEntry',
+      spr: '-Spr'
+    }.each do |keyword, kpscript_flag|
+
+      it "reads entries string with #{keyword} flag" do
+        expect_calls_to_kpscript [
+          [
+            "/path/to/KPScript.exe \"/path/to/my_db.kdbx\" -pw:\"MyPassword\" -c:GetEntryString -refx-All -Field:\"Field\" #{kpscript_flag}",
+            <<~EO_STDOUT
+              Value1
+              Value2
+              Value3
+              OK: Operation completed successfully.
+            EO_STDOUT
+          ]
+        ]
+        expect(database.entries_string(kpscript.select.all, 'Field', **{ keyword => true })).to eq %w[Value1 Value2 Value3]
+      end
+
+      it "reads entries string in a secured way with secret strings with #{keyword} flag" do
+        expect_calls_to_kpscript [
+          [
+            "/path/to/KPScript.exe \"/path/to/my_db.kdbx\" -pw:\"MyPassword\" -c:GetEntryString -refx-All -Field:\"Field\" #{kpscript_flag}",
+            <<~EO_STDOUT
+              Value1
+              Value2
+              Value3
+              OK: Operation completed successfully.
+            EO_STDOUT
+          ]
+        ]
+        leaked_values = nil
+        expect do
+          database.with_entries_string(kpscript.select.all, 'Field', **{ keyword => true }) do |values|
+            expect(values.map(&:to_s)).to eq %w[XXXXX XXXXX XXXXX]
+            expect(values.map(&:to_unprotected)).to eq %w[Value1 Value2 Value3]
+            leaked_values = values
+          end
+        end.not_to raise_error
+        expect(leaked_values.map(&:to_s)).to eq %w[XXXXX XXXXX XXXXX]
+        expect(leaked_values.map(&:to_unprotected)).to eq ["\x00\x00\x00\x00\x00\x00", "\x00\x00\x00\x00\x00\x00", "\x00\x00\x00\x00\x00\x00"]
+      end
+
+    end
+
+    # All edit entries test cases
+    {
+      { fields: { Field: 'Value' } } => '-set-Field:"Value"',
+      { fields: { Field1: 'Value1', Field2: 'Value2' } } => '-set-Field1:"Value1" -set-Field2:"Value2"',
+      { icon_idx: 7 } => '-setx-Icon:7',
+      { custom_icon_idx: 11 } => '-setx-CustomIcon:11',
+      { expires: true } => '-setx-Expires:true',
+      { expiry_time: Time.parse('2021-06-30 15:12:11') } => '-setx-ExpiryTime:"2021-06-30T15:12:11"',
+      { fields: { Field: 'Value' }, create_backup: true } => '-set-Field:"Value" -CreateBackup',
+      {
+        fields: { Field1: 'Value1', Field2: 'Value2' },
+        expiry_time: Time.parse('2021-06-30 15:12:11'),
+        icon_idx: 7,
+        create_backup: true
+      } => '-set-Field1:"Value1" -set-Field2:"Value2" -setx-Icon:7 -setx-ExpiryTime:"2021-06-30T15:12:11" -CreateBackup'
+    }.each do |kwargs, expected_args|
+
+      it "edit entries using #{kwargs}" do
+        expect_calls_to_kpscript [
+          [
+            "/path/to/KPScript.exe \"/path/to/my_db.kdbx\" -pw:\"MyPassword\" -c:EditEntry -refx-All #{expected_args}",
+            'OK: Operation completed successfully.'
+          ]
+        ]
+        expect { database.edit_entries(kpscript.select.all, **kwargs) }.not_to raise_error
+      end
+
+    end
+
+    it 'detaches binaries' do
+      expect_calls_to_kpscript [
+        [
+          '/path/to/KPScript.exe "/path/to/my_db.kdbx" -pw:"MyPassword" -c:DetachBins',
+          'OK: Operation completed successfully.'
+        ]
+      ]
+      expect { database.detach_bins }.not_to raise_error
+    end
+
+    it 'detaches binaries in another directory' do
+      tmpdir = "#{Dir.tmpdir}/keepass_kpscript_test"
+      FileUtils.mkdir_p tmpdir
+      begin
+        database_file = "#{tmpdir}/my_db.kdbx"
+        File.write(database_file, 'Dummy database')
+        bins_dir = "#{tmpdir}/bins_dir"
+        expect_calls_to_kpscript [
+          [
+            "/path/to/KPScript.exe \"#{bins_dir}/my_db.kdbx.tmp.kdbx\" -pw:\"MyPassword\" -c:DetachBins",
+            'OK: Operation completed successfully.'
+          ]
+        ]
+        expect { kpscript.open(database_file, password: 'MyPassword').detach_bins(copy_to_dir: bins_dir) }.not_to raise_error
+        expect(File.exist?(bins_dir)).to eq true
+        # Check that no database copy is remaining
+        expect(Dir.glob("#{bins_dir}/*")).to eq []
+      ensure
+        FileUtils.rm_rf tmpdir
+      end
+    end
+
+    it 'exports the database' do
+      expect_calls_to_kpscript [
+        [
+          '/path/to/KPScript.exe "/path/to/my_db.kdbx" -pw:"MyPassword" -c:Export -Format:"Export Format" -OutFile:"/path/to/export_file"',
+          'OK: Operation completed successfully.'
+        ]
+      ]
+      expect { database.export('Export Format', '/path/to/export_file') }.not_to raise_error
+    end
+
+    it 'exports the database with a group path selected' do
+      expect_calls_to_kpscript [
+        [
+          '/path/to/KPScript.exe "/path/to/my_db.kdbx" -pw:"MyPassword" -c:Export -Format:"Export Format" -OutFile:"/path/to/export_file" -GroupPath:"Group1/Group2/Group3"',
+          'OK: Operation completed successfully.'
+        ]
+      ]
+      expect { database.export('Export Format', '/path/to/export_file', group_path: %w[Group1 Group2 Group3]) }.not_to raise_error
+    end
+
+    it 'exports the database with an XSL file specified' do
+      expect_calls_to_kpscript [
+        [
+          '/path/to/KPScript.exe "/path/to/my_db.kdbx" -pw:"MyPassword" -c:Export -Format:"Export Format" -OutFile:"/path/to/export_file" -XslFile:"/path/to/xsl_file.xsl"',
+          'OK: Operation completed successfully.'
+        ]
+      ]
+      expect { database.export('Export Format', '/path/to/export_file', xsl_file: '/path/to/xsl_file.xsl') }.not_to raise_error
+    end
+
+  end
+
+  context 'without debug' do
+
+    it_behaves_like 'a database' do
+      let(:debug) { false }
+    end
+
+  end
+
+  context 'with debug' do
+
+    it_behaves_like 'a database' do
+      let(:debug) { true }
+    end
+
+  end
+
+end

data/spec/keepass_kpscript_test/tests/keepass_kpscript/kpscript_spec.rb

@@ -0,0 +1,117 @@
+describe KeepassKpscript::Kpscript do
+
+  shared_examples 'a kpscript instance' do
+
+    subject(:kpscript) { KeepassKpscript.use('/path/to/KPScript.exe', debug: debug) }
+
+    it 'gives an instance wrapping a KPScript installation' do
+      expect_calls_to_kpscript [['/path/to/KPScript.exe -example-arg', 'OK: Operation completed successfully.']]
+      kpscript.run('-example-arg')
+    end
+
+    it 'encrypts passwords' do
+      expect_calls_to_kpscript [
+        [
+          '/path/to/KPScript.exe "/tmp/keepass_kpscript.tmp.kdbx" -pw:"pass_encryptor" -c:EditEntry -ref-Title:"pass_encryptor" -set-Password:"MyPassword"',
+          'OK: Operation completed successfully.'
+        ],
+        [
+          '/path/to/KPScript.exe "/tmp/keepass_kpscript.tmp.kdbx" -pw:"pass_encryptor" -c:GetEntryString -ref-Title:"pass_encryptor" -Field:"URL" -Spr',
+          <<~EO_STDOUT
+            ENCRYPTED_PASSWORD
+            OK: Operation completed successfully.
+          EO_STDOUT
+        ]
+      ]
+      expect(kpscript.encrypt_password('MyPassword')).to eq 'ENCRYPTED_PASSWORD'
+    end
+
+    it 'opens a database with a password' do
+      expect_calls_to_kpscript [
+        [
+          '/path/to/KPScript.exe "/path/to/my_db.kdbx" -pw:"MyPassword" -c:GetEntryString -ref-Title:"MyEntryTitle" -Field:"Password"',
+          <<~EO_STDOUT
+            MyEntryPassword
+            OK: Operation completed successfully.
+          EO_STDOUT
+        ]
+      ]
+      expect(kpscript.open('/path/to/my_db.kdbx', password: 'MyPassword').password_for('MyEntryTitle')).to eq 'MyEntryPassword'
+    end
+
+    it 'opens a database with an encrypted password' do
+      expect_calls_to_kpscript [
+        [
+          '/path/to/KPScript.exe "/path/to/my_db.kdbx" -pw-enc:"MyEncryptedPassword" -c:GetEntryString -ref-Title:"MyEntryTitle" -Field:"Password"',
+          <<~EO_STDOUT
+            MyEntryPassword
+            OK: Operation completed successfully.
+          EO_STDOUT
+        ]
+      ]
+      expect(kpscript.open('/path/to/my_db.kdbx', password_enc: 'MyEncryptedPassword').password_for('MyEntryTitle')).to eq 'MyEntryPassword'
+    end
+
+    it 'opens a database with a key file' do
+      expect_calls_to_kpscript [
+        [
+          '/path/to/KPScript.exe "/path/to/my_db.kdbx" -keyfile:"/path/to/key_file" -c:GetEntryString -ref-Title:"MyEntryTitle" -Field:"Password"',
+          <<~EO_STDOUT
+            MyEntryPassword
+            OK: Operation completed successfully.
+          EO_STDOUT
+        ]
+      ]
+      expect(kpscript.open('/path/to/my_db.kdbx', key_file: '/path/to/key_file').password_for('MyEntryTitle')).to eq 'MyEntryPassword'
+    end
+
+    it 'opens a database with a key file and password' do
+      expect_calls_to_kpscript [
+        [
+          '/path/to/KPScript.exe "/path/to/my_db.kdbx" -pw:"MyPassword" -keyfile:"/path/to/key_file" -c:GetEntryString -ref-Title:"MyEntryTitle" -Field:"Password"',
+          <<~EO_STDOUT
+            MyEntryPassword
+            OK: Operation completed successfully.
+          EO_STDOUT
+        ]
+      ]
+      expect(kpscript.open('/path/to/my_db.kdbx', password: 'MyPassword', key_file: '/path/to/key_file').password_for('MyEntryTitle')).to eq 'MyEntryPassword'
+    end
+
+    it 'opens a database with a key file and encrypted password' do
+      expect_calls_to_kpscript [
+        [
+          '/path/to/KPScript.exe "/path/to/my_db.kdbx" -pw-enc:"MyEncryptedPassword" -keyfile:"/path/to/key_file" -c:GetEntryString -ref-Title:"MyEntryTitle" -Field:"Password"',
+          <<~EO_STDOUT
+            MyEntryPassword
+            OK: Operation completed successfully.
+          EO_STDOUT
+        ]
+      ]
+      expect(kpscript.open('/path/to/my_db.kdbx', password_enc: 'MyEncryptedPassword', key_file: '/path/to/key_file').password_for('MyEntryTitle')).to eq 'MyEntryPassword'
+    end
+
+    it 'gives a selector' do
+      expect_calls_to_kpscript []
+      expect(kpscript.select.fields(Title: 'MyEntryTitle').to_s).to eq '-ref-Title:"MyEntryTitle"'
+    end
+
+  end
+
+  context 'without debug' do
+
+    it_behaves_like 'a kpscript instance' do
+      let(:debug) { false }
+    end
+
+  end
+
+  context 'with debug' do
+
+    it_behaves_like 'a kpscript instance' do
+      let(:debug) { true }
+    end
+
+  end
+
+end