safedb 0.4.1002 → 0.5.1001

data/lib/model/book.rb

@@ -68,6 +68,7 @@ module SafeDb
       return @master_verse_count
     end
 
+
     # Get the hash data structure representing the branch's state. This state
     # may or may not be equivalent to the current master state as gettable by
     # the {to_master_data} method.
@@ -88,6 +89,7 @@ module SafeDb
 
     end
 
+
     # Get the number of verses in the branch's data structure.
     # @return [Number] the number of verses in the branch's data.
     def get_branch_verse_count()
@@ -170,16 +172,19 @@ module SafeDb
     end
 
 
-    # Return true if this book has been opened at a chapter and verse location.
+    # Return true if this book has NOT been opened at a chapter and verse location.
     # This method uses {TextChunk.not_open_message} to print out a helpful message
     # detailing how to open a chapter and verse.
     #
     # Note that an open chapter need not contain any data. The same goes for an
     # open verse. In these cases the {open_chapter} and {open_verse} methods both
     # return empty data structures.
-    def unopened_chapter_verse()
-      return if has_open_chapter_name?() and has_open_verse_name?()
+    #
+    # @return [Boolean] true if no chapter and verse for this book is open
+    def unopened_chapter_verse?()
+      return false if( has_open_chapter_name?() and has_open_verse_name?() )
       TextChunk.not_open_message()
+      return true
     end
 
 
@@ -372,9 +377,9 @@ module SafeDb
 
 
     # Return true if the commit identifiers for the master and the branch match
-    # meaning that we can commit (checkin).
-    # @return [Boolean] true if can checkin, false otherwise
-    def can_checkin?()
+    # meaning that we can commit (commit).
+    # @return [Boolean] true if can commit, false otherwise
+    def can_commit?()
       return @branch_keys.get( Indices::COMMIT_IDENTIFIER ).eql?( @master_keys.get( Indices::COMMIT_IDENTIFIER ) )
     end
 

data/lib/model/indices.rb

@@ -46,7 +46,7 @@ module SafeDb
     # The AES symmetric encryption initialization vector
     CONTENT_RANDOM_IV  = "content.iv"
 
-    # The commit identifiers of the master and branch are compared to ascertain eligibility for checkins
+    # The commit identifiers of the master and branch are compared to ascertain eligibility for commits
     COMMIT_IDENTIFIER = "commit.identifier"
 
     # The bootup id is set on machine boot and lasts until the reboot or shutdown.

data/lib/model/state.inspect.rb

@@ -7,64 +7,21 @@ module SafeDb
   #
   class StateInspect
 
+    # Return true if this book has been logged in during this session.
+    # @return [Boolean] true if not logged into this book
+    def self.not_logged_in?()
 
-    # A checkout is effectively an incoming merge of the master's data
-    # structure into the working branch. With checkouts nothing ever gets
-    # deleted.
-    #
-    # No delete is self-evident in this list of only <tt>4 prophetic</tt>
-    # outcomes
-    #
-    # - this chapter will be added
-    # - this verse will be added
-    # - this line will be added
-    # - this branch's line value will be overwritten with the value from master
-    #
-    # Examine the sister method {checkin_diff} that prophesizes on the
-    # state changes a checkin will invoke.
-    #
-    # @param master_data [Hash] data structure from the master line of the book
-    # @param branch_data [Hash] data structure from the current working branch
-    def self.checkout_prophecies( master_data, branch_data )
-
-      puts " = safe diff --checkout"
-      puts " = incoming from master to working branch"
-      puts ""
-
-      data_differences( master_data, branch_data )
-
-    end
-
-
-    # A checkout merges whilst a checkin is effectively a hard copy that destroys
-    # whatever is on the master making it exactly reflect the branch's current state.
-    #
-    # The three addition state changes prophesized by a checkout can also occur on
-    # checkins. However checkins can also prophesize that
-    #
-    # - this master's line value will be overwritten with the branch's value
-    # - this chapter will be removed
-    # - this verse will be removed
-    # - this line will be removed
-    #
-    # Examine the sister method {checkin_diff} that prophesizes on the
-    # state changes a checkin will invoke.
-    #
-    # @param master_data [Hash] data structure from the master line of the book
-    # @param branch_data [Hash] data structure from the current working branch
-    def self.checkin_prophecies( master_data, branch_data )
-
-      puts " = safe diff --checkin"
-      puts " = outgoing from working branch to master"
-      puts ""
-
-      data_differences( branch_data, master_data )
-      drop_differences( master_data, branch_data )
+      branch_id = Identifier.derive_branch_id( Branch.to_token() )
+      return true unless File.exists?( FileTree.branch_indices_filepath( branch_id ) )
+      branch_keys = DataMap.new( FileTree.branch_indices_filepath( branch_id ) )
+      return true unless branch_keys.has_section?( Indices::BRANCH_DATA )
+      book_id = branch_keys.read( Indices::BRANCH_DATA, Indices::CURRENT_BRANCH_BOOK_ID )
+      return true unless branch_keys.has_section?( book_id )
+      return !is_logged_in?( book_id )
 
     end
 
 
-
     # Returns true if valid credentials have been provided earlier on in this
     # session against the book specified in the parameter.
     #
@@ -120,6 +77,63 @@ module SafeDb
     end
 
 
+    # A refresh is effectively an incoming merge of the master's data
+    # structure into the working branch. With refreshs nothing ever gets
+    # deleted.
+    #
+    # No delete is self-evident in this list of only <tt>4 prophetic</tt>
+    # outcomes
+    #
+    # - this chapter will be added
+    # - this verse will be added
+    # - this line will be added
+    # - this branch's line value will be overwritten with the value from master
+    #
+    # Examine the sister method {commit_diff} that prophesizes on the
+    # state changes a commit will invoke.
+    #
+    # @param master_data [Hash] data structure from the master line of the book
+    # @param branch_data [Hash] data structure from the current working branch
+    def self.refresh_prophecies( master_data, branch_data )
+
+      puts " = safe diff --refresh"
+      puts " = incoming from master to working branch"
+      puts ""
+
+      data_differences( master_data, branch_data )
+
+    end
+
+
+    # A refresh merges whilst a commit is effectively a hard copy that destroys
+    # whatever is on the master making it exactly reflect the branch's current state.
+    #
+    # The three addition state changes prophesized by a refresh can also occur on
+    # commits. However commits can also prophesize that
+    #
+    # - this master's line value will be overwritten with the branch's value
+    # - this chapter will be removed
+    # - this verse will be removed
+    # - this line will be removed
+    #
+    # Examine the sister method {commit_diff} that prophesizes on the
+    # state changes a commit will invoke.
+    #
+    # @param master_data [Hash] data structure from the master line of the book
+    # @param branch_data [Hash] data structure from the current working branch
+    def self.commit_prophecies( master_data, branch_data )
+
+      puts " = safe diff --commit"
+      puts " = outgoing from working branch to master"
+      puts ""
+
+      data_differences( branch_data, master_data )
+      drop_differences( master_data, branch_data )
+
+    end
+
+
+
     private
 
 

data/lib/model/state.migrate.rb

@@ -7,8 +7,8 @@ module SafeDb
   #
   # - <tt>initialization</tt> - a new master state box is created
   # - <tt>login</tt> - branch state is created that mirrors master
-  # - <tt>checkin</tt> - transfers state from branch to master
-  # - <tt>checkout</tt> - transfers state from master to branch
+  # - <tt>commit</tt> - transfers state from branch to master
+  # - <tt>refresh</tt> - transfers state from master to branch
   #
   class StateMigrate
 
@@ -30,7 +30,7 @@ module SafeDb
     # The high entropy key is recycled only on the first login into a book since the
     # machine reboot. This is because subsequent branch logins that protect the
     # random key will need to check back with the master branch when performing either
-    # a diff or checkout operations. Also the checkin operation must maintain the
+    # a diff or refresh operations. Also the commit operation must maintain the
     # same content encryption key for readability by validated agents.
     #
     # @param book_keys [DataMap]
@@ -120,12 +120,12 @@ module SafeDb
     end
 
 
-    # In the main, the <tt>checkin use case</tt> changes the master so that it mirrors
-    # the branch's state. A check-in syncs the master's state to mirror the branch.
+    # In the main, the <tt>commit use case</tt> changes the master so that it mirrors
+    # the branch's state. A commit syncs the master's state to mirror the branch.
     #
     # == The Simple Check In
     #
-    # The simplest case is when no other branch has issued a check-in since this branch
+    # The simplest case is when no other branch has issued a commit since this branch
     #
     # - <tt>logged in</tt>
     # - <tt>checked in</tt> or
@@ -142,16 +142,16 @@ module SafeDb
     # A new commit ID is only created during
     #
     # - <tt>either the first login</tt> since the machine booted up
-    # - <tt>or a branch checkin</tt>
+    # - <tt>or a branch commit</tt>
     #
     # The commit ID is copied from master to branch during
     #
     # - <tt>either subsequent logins</tt>
-    # - <tt>or a branch checkout</tt>
+    # - <tt>or a branch refresh</tt>
     #
-    def self.checkin( book )
+    def self.commit( book )
 
-# @todo => If mismatch in commit IDs then print message instructing to first do safe checkout
+# @todo => If mismatch in commit IDs then print message instructing to first do safe refresh
 
       FileUtils.remove_entry( FileTree.master_crypts_folder( book.book_id() ) )
       FileUtils.mkdir_p( FileTree.master_crypts_folder( book.book_id() ) )
@@ -162,9 +162,9 @@ module SafeDb
       branch_keys = DataMap.new( FileTree.branch_indices_filepath( book.branch_id() ) )
       branch_keys.use( book.book_id() )
 
-      checkin_commit_id = Identifier.get_random_identifier( 16 )
-      branch_keys.set( Indices::COMMIT_IDENTIFIER, checkin_commit_id )
-      master_keys.set( Indices::COMMIT_IDENTIFIER, checkin_commit_id )
+      commit_id = Identifier.get_random_identifier( 16 )
+      branch_keys.set( Indices::COMMIT_IDENTIFIER, commit_id )
+      master_keys.set( Indices::COMMIT_IDENTIFIER, commit_id )
 
       master_keys.set( Indices::CONTENT_IDENTIFIER, branch_keys.get( Indices::CONTENT_IDENTIFIER ) )
       master_keys.set( Indices::CONTENT_RANDOM_IV,  branch_keys.get( Indices::CONTENT_RANDOM_IV  ) )
@@ -173,13 +173,13 @@ module SafeDb
 
 
 
-    # A checkout merges down the master's data into the data of this working branch.
-    # The <tt>commit ID</tt> of the working branch after the checkout is made to be
-    # equivalent with that of the master. This act signifies that a checkin is now 
-    # allowed (as long as another branch doesn't checkin in the meantime).
+    # A refresh merges down the master's data into the data of this working branch.
+    # The <tt>commit ID</tt> of the working branch after the refresh is made to be
+    # equivalent with that of the master. This act signifies that a commit is now 
+    # allowed (as long as another branch doesn't commit in the meantime).
     #
     # @param book [Book] the book whose master data will be merged down into the branch.
-    def self.checkout( book )
+    def self.refresh( book )
 
       master_data = book.to_master_data()
       branch_data = book.to_branch_data()
@@ -200,7 +200,7 @@ module SafeDb
 
 
     # Copy the master commit identifier to the branch. This signifies that the branch
-    # is aligned (and ready) to checkin its changes into the master.
+    # is aligned (and ready) to commit its changes into the master.
     # @param book [Book] the book whose commit IDs will be manipulated
     def self.copy_commit_id_to_branch( book )
 

data/lib/model/text_chunk.rb

@@ -29,35 +29,55 @@ CRYPT_HEADER
     end
 
 
+    # Print a message stating that the book cannot be accessed until
+    # a successful login has occured.
+    def self.not_logged_in_message()
+
+      <<-NOT_LOGGED_IN_MESSAGE
+
+  Please login to access the credentials in this book.
+  Suppose you initialized a book called websites.
+
+    #{Indices::COMMANDER} login websites
+     #{Indices::COMMANDER} login websites --password=secret123
+    #{Indices::COMMANDER} login websites --clip
+
+  A space before the command skips history logging.
+
+NOT_LOGGED_IN_MESSAGE
+
+    end
+
+
     # Print a message stating that the book has not been opened at any
     # chapter and verse location.
     def self.not_open_message()
 
       <<-UNOPENED_MESSAGE
 
-      Please open a chapter and verse to put, edit or query data.
+  Please open a chapter and verse to put, edit or query data.
 
-          #{Indices::COMMANDER} open contacts monica
+     #{Indices::COMMANDER} open contacts monica
 
-       then add monica's contact details
+  then add monica's contact details
 
-          #{Indices::COMMANDER} put email monica.lewinsky@gmail.com
-          #{Indices::COMMANDER} put phone +1-357-246-8901
-          #{Indices::COMMANDER} put twitter @monica_x
-          #{Indices::COMMANDER} put skype.id 6363430539
-          #{Indices::COMMANDER} put birthday \"1st April 1978\"
+     #{Indices::COMMANDER} put email monica.lewinsky@gmail.com
+     #{Indices::COMMANDER} put phone +1-357-246-8901
+     #{Indices::COMMANDER} put twitter @monica_x
+     #{Indices::COMMANDER} put skype.id 6363430539
+     #{Indices::COMMANDER} put birthday \"1st April 1978\"
 
-       also hilary's
+  also hilary's
 
-          #{Indices::COMMANDER} open contacts hilary
-          #{Indices::COMMANDER} put email hilary@whitehouse.gov
+     #{Indices::COMMANDER} open contacts hilary
+     #{Indices::COMMANDER} put email hilary@whitehouse.gov
 
-       then save the changes to your book and logout."
+  then save the changes to your book and logout."
 
-          #{Indices::COMMANDER} commit"
-          #{Indices::COMMANDER} logout"
+     #{Indices::COMMANDER} commit"
+     #{Indices::COMMANDER} logout"
 
-      UNOPENED_MESSAGE
+UNOPENED_MESSAGE
 
     end
 

data/lib/utils/clipboard/clip.rb

@@ -0,0 +1,92 @@
+#!/usr/bin/ruby
+# coding: utf-8
+
+module SafeDb
+
+  # This Clip class reads, writes and overwrites text that either has been
+  # placed in, or will be placed in the clipboard.
+  #
+  # == xclip pre-condition
+  #
+  # xclip must be installed using `sudo apt install --assume-yes xclip`
+  class Clipboard
+
+
+    # Get the first line of text from the clipboard. Raise an exception
+    # if the clipboard either has no text, or the text is empy, or the
+    # text consists solely of whitespace.
+    #
+    # The text will be trimmed before being returned so any leading or
+    # trailing whitespace will be removed.
+    #
+    # For **multiple line** text, the first line that is non-empty and
+    # non whitespace only is returned.
+    #
+    # Due to the sensitive nature of the text the clipboards contents will
+    # be immediately overwritten once the pertinent textual content has
+    # been consumed.
+    #
+    # @raise [RuntimeError] if text is nil, empty or consists solely of whitespace
+    # @return [String] trimmed version of the clipboard's contents
+    def self.read_password()
+      
+      log.info(x) { "About to read a sensitive password from the clipboard." }
+      password_text = read_line()
+      put( "safe has overwritten clipboard contents." )
+      return password_text
+
+    end
+
+
+    # Put the parameter text into the clipboard thus overwriting whatever
+    # content may or may not exist there.
+    #
+    # @param text_line [String] the text line to put in the clipboard
+    def self.put( text_line )
+
+      log.info(x) { "Putting text into the clipboard thus overwriting existing content." }
+      clipboard_put_command = "printf #{text_line} | xclip -selection c"
+      system clipboard_put_command
+
+    end
+
+
+    # Get the first line of text from the clipboard. Raise an exception
+    # if the clipboard either has no text, or the text is empy, or the
+    # text consists solely of whitespace.
+    #
+    # The text will be trimmed before being returned so any leading or
+    # trailing whitespace will be removed.
+    #
+    # For **multiple line** text, the first line that is non-empty and
+    # non whitespace only is returned.
+    #
+    # @raise [RuntimeError] if text is nil, empty or consists solely of whitespace
+    # @return [String] trimmed version of the clipboard's contents
+    def self.read_line()
+      
+      log.info(x) { "About to read and process a text line from the clipboard." }
+      xclip_command = "xclip -o"
+      textual_content = %x[ #{xclip_command} ]
+      no_content = textual_content.nil?() || textual_content.chomp().strip().empty?()
+      raise RuntimeError, "The clipboard does not contain any text." if no_content
+      clipboard_text = textual_content.chomp().strip()
+      num_lines = clipboard_text.lines.count()
+      return clipboard_text if num_lines == 1
+
+      log.info(x) { "Clipboard text has #{num_lines} lines - will return first viable line." }
+
+      clipboard_text.each_line do |text_line|
+        candidate_line = text_line.chomp.gsub("\\n","").strip()
+        return candidate_line unless candidate_line.empty()
+      end
+
+      raise RuntimeError, "The multi-line clipboard text contained no printable characters."
+
+    end
+
+
+  end
+
+
+end

data/lib/utils/key.pass.rb

@@ -40,6 +40,8 @@ module SafeDb
       # @raise [ArgumentError] if the minimum size is less than one
       def self.password_from_shell prompt_twice
 
+        require "io/console"
+
         assert_min_size MINIMUM_PASSWORD_SIZE
 
         sleep(1)
@@ -100,7 +102,7 @@ module SafeDb
         unless( first_text.eql? second_text )
 
           puts
-          puts "Those two bits of text are not the same (in my book)!"
+          puts "Those two passwords are not the same (in my book)!"
           puts
 
           exit

data/lib/version.rb

@@ -1,3 +1,3 @@
 module SafeDb
-  VERSION = "0.4.1002"
+  VERSION = "0.5.1001"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: safedb
 version: !ruby/object:Gem::Version
-  version: 0.4.1002
+  version: 0.5.1001
 platform: ruby
 authors:
 - Apollo Akora
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-04-19 00:00:00.000000000 Z
+date: 2019-04-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bcrypt
@@ -130,8 +130,7 @@ files:
 - lib/cli.rb
 - lib/controller/admin/README.md
 - lib/controller/admin/access.rb
-- lib/controller/admin/checkin.rb
-- lib/controller/admin/checkout.rb
+- lib/controller/admin/commit.rb
 - lib/controller/admin/diff.rb
 - lib/controller/admin/export.rb
 - lib/controller/admin/goto.rb
@@ -140,8 +139,8 @@ files:
 - lib/controller/admin/login.rb
 - lib/controller/admin/logout.rb
 - lib/controller/admin/open.rb
+- lib/controller/admin/refresh.rb
 - lib/controller/admin/token.rb
-- lib/controller/admin/tree.md
 - lib/controller/admin/use.rb
 - lib/controller/admin/view.rb
 - lib/controller/api/docker/README.md
@@ -154,6 +153,7 @@ files:
 - lib/controller/api/vpn/vpn.ini
 - lib/controller/api/vpn/vpn.rb
 - lib/controller/config/README.md
+- lib/controller/controller.rb
 - lib/controller/edit/README.md
 - lib/controller/edit/editverse.rb
 - lib/controller/edit/put.rb
@@ -163,16 +163,20 @@ files:
 - lib/controller/files/read.rb
 - lib/controller/files/write.rb
 - lib/controller/id.rb
+- lib/controller/query/copy.rb
 - lib/controller/query/print.rb
 - lib/controller/query/queryverse.rb
 - lib/controller/query/show.rb
 - lib/controller/requirer.rb
 - lib/controller/set.rb
-- lib/controller/usecase.rb
 - lib/controller/verse.rb
 - lib/controller/visit/README.md
 - lib/controller/visit/visit.rb
 - lib/factbase/facts.safedb.net.ini
+- lib/manual/copy-paste.md
+- lib/manual/dir-structure.md
+- lib/manual/drag-drop.md
+- lib/manual/login-logout.md
 - lib/model/README.md
 - lib/model/book.rb
 - lib/model/branch.rb
@@ -188,10 +192,10 @@ files:
 - lib/modules/cryptology/aes-256.rb
 - lib/modules/cryptology/blowfish.rb
 - lib/modules/cryptology/cipher.rb
-- lib/modules/cryptology/collect.rb
 - lib/modules/cryptology/crypt.io.rb
 - lib/modules/storage/coldstore.rb
 - lib/modules/storage/git.store.rb
+- lib/utils/clipboard/clip.rb
 - lib/utils/extend/array.rb
 - lib/utils/extend/dir.rb
 - lib/utils/extend/file.rb

data/lib/controller/admin/checkin.rb

@@ -1,83 +0,0 @@
-#!/usr/bin/ruby
-	
-module SafeDb
-
-  # The <b>checkin use case</b> commits any changes made to the safe book into
-  # master. This is straightforward if the master's state has not been forwarded
-  # by a ckeckin from another (shell) branch.
-  #
-  # == master and branch not in sync
-  #
-  # The checkin and checkout use cases will be evolved to provide more options
-  # if the master state is out of sync.
-  #
-  # Six options present when the master state is ahead.
-  #
-  # == first checkout and then checkin
-  #
-  # The preferred manner of dealing with an out of sync state is to checkout
-  # first and then to checkin.
-  #
-  # - <tt>safe checkout --merge --branch</tt> | merge down (into branch) and branch wins on duplicates
-  # - <tt>safe checkout --merge --master</tt> | merge down (into branch)  but master wins on duplicates
-  # - <tt>safe checkout --clobber</tt>        | force branch to exactly mimic the master's state
-  #
-  # Once you chosent one of the above you can then <tt>safe checkin</tt> in a safe way.
-  #
-  # == bull in a china shop
-  #
-  # Merging down is more considered (and polite) to team members than merging up.
-  # If you know what you are doing you can merge or clobber up!
-  #
-  # - <tt>safe checkin --merge --branch</tt> | merge up (into master) and branch wins on duplicates
-  # - <tt>safe checkin --merge --master</tt> | merge up (into master) but master wins on duplicates
-  # - <tt>safe checkin --clobber</tt>        | force master to exactly mimic our branch state
-  #
-  # == checkin | merge up mechanics
-  #
-  # The mechanics of a simple in-sync checkin is to
-  #
-  # - sync the master crypts to exactly mimic the branch crypts
-  # - tell master the content id of the book index file
-  # - tell master what the current random iv (initialization vector) is
-  # - create a new commit ID and set it on both master and branch
-  # - set the master's last updated date and time
-  #
-  class CheckIn < UseCase
-
-
-    # The <b>checkin use case</b> commits any changes made to the safe book into
-    # master. This is straightforward if the master's state has not been forwarded
-    # by a ckeckin from another (shell) branch.
-    def execute
-
-      book = Book.new()
-      book.print_book_mark()
-
-      unless book.can_checkin?()
-
-        puts "Cannot checkin as master has moved forward."
-        puts "First see the difference, then checkout, and then checkin."
-        puts ""
-        puts "   safe diff"
-        puts "   safe checkout"
-        puts "   safe checkin"
-        puts ""
-        return
-
-      end
-
-      StateMigrate.checkin( book )
-
-      puts "The checkin was on #{KeyNow.readable()}\n"
-      puts "Checkin from branch to master was successful.\n"
-      puts ""
-
-
-    end
-
-
-  end
-
-
-end