safedb 0.3.1011 → 0.4.1002

data/lib/controller/admin/README.md

@@ -0,0 +1,47 @@
+
+# Safe Administration Commands
+
+A safe database is a collection of books and each database instance comprises of an index file and a collection of crypt files.
+
+You can use your safe on many machines and on many shells within a machine. All this is synchronized via a **git repository** and with a single index file that is generally kept on removable (usb key) media.
+
+## safe branch admin commands
+
+These commands handle **book and branch creation, instantiation and synchronization** between multiple shells.
+
+| safe command                 | command purpose                                      | cmd summary      |
+|:---------------------------- |:---------------------------------------------------- |:---------------- |
+| **`safe init <BOOK_NAME>`**  | instantiate a new safe database book                 | create book      |
+| **`safe login <BOOK_NAME>`** | create a new shell for instantiated book     | instantiate book |
+| **`safe commit`**            | save the state of the book locally (like git commit) | save book        |
+| **`safe logout`**            | delete references to this book and shell     | delete branch   |
+| **`safe use <BOOK_NAME>`**   | switch shell to using this logged in book    | update branch   |
+| **`safe token`**             | creates cryptographic keys for every shell   | create key       |
+
+
+## safe database sync commands
+
+The **push** and **pull** commands synchronize your safe across many machines.
+
+- **`safe pull --from=/path/to/usb/folder`** | pull safe assets to a machine with old state
+- **`safe pull`** | uses index on usb drive if known and available (else refreshes local state)
+- **`safe push --to=/path/to/usb/folder`** | pushes out safe assets from a machine with new state
+- **`safe push`** | pushes out using index on usb drive if known and available
+
+You must tell the safe where your remote git repository is.
+
+- **`safe store git.pull.url https://github.com/devops4me/example.crypt.git`**
+- **`safe store git.push.url git@safedb.crypt:devops4me/example.crypt.git`**
+
+## chicken and egg | public crypts
+
+The safe is designed to **hold your private keys** so it would be chicken and egg if you needed a private key to access it.
+
+The crypt files are designed to be utterly useless to those without both your usb key and your password. This is why
+
+- **`git.pull.url`** can be publicly accessible from github **`https://github.com/...`**
+- **`git.push.url`** is private **`git@<NAME>:<USER>/<REPO>`**
+
+After you access your safe you then have the private key enabling you to push changes to your safe.
+
+You can prevent access to your crypts by using a privately accessible git.pull.url.

data/lib/controller/admin/access.rb

@@ -0,0 +1,47 @@
+#!/usr/bin/ruby
+	
+module SafeDb
+
+  # Parent to use cases like Init and Login that perform early
+  # initialize workflows.
+  class AccessUc < UseCase
+
+    attr_writer :password, :book_name
+
+
+    private
+
+
+    # Return true if the human secret for the parameter application name
+    # has been collected, transformed into a key, that key used to lock the
+    # power key, then secret and keys deleted, plus a trail of breadcrumbs
+    # sprinkled to allow the <b>branch crypt key to be regenerated</b>
+    # at the <b>next login</b>.
+    def is_book_initialized?()
+
+      KeyError.not_new( @book_name, self )
+      return false unless File.exists?( Indices::MASTER_INDICES_FILEPATH )
+      data_map = DataMap.new( Indices::MASTER_INDICES_FILEPATH )
+      return false unless data_map.has_section?( @book_id )
+      data_map.use( @book_id )
+
+      return contains_all_master_book_indices( data_map )
+
+    end
+
+
+    def contains_all_master_book_indices( data_map )
+      return false unless data_map.contains?( Indices::CONTENT_RANDOM_IV )
+      return false unless data_map.contains?( Indices::CONTENT_IDENTIFIER )
+      return false unless data_map.contains?( Indices::CRYPT_CIPHER_TEXT )
+      return false unless data_map.contains?( Indices::COMMIT_IDENTIFIER )
+      return true
+    end
+
+
+  end
+
+
+end
+
+

data/lib/controller/admin/checkin.rb

@@ -0,0 +1,83 @@
+#!/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

data/lib/controller/admin/checkout.rb

@@ -0,0 +1,57 @@
+#!/usr/bin/ruby
+	
+module SafeDb
+
+  # The <b>checkout 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
+  #
+  # Checkins cannot occur when the master's state has been moved forward by another
+  # branch checkin. In these cases one needs to use the below sequence.
+  #
+  # - <tt>safe diff --checkout</tt> | diff will list what will the state changes during checkout
+  # - <tt>safe checkout</tt> | the actual merge down (from master to branch) that never deletes keys
+  # - <tt>safe checkin</tt> | now the checkin can proceed as the branch is in line with the master
+  #
+  # == checkout | merge up mechanics
+  #
+  # The mechanics of a simple in-sync checkout 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 CheckOut < UseCase
+
+
+    # The <b>checkout 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()
+
+      puts ""
+      puts " == Birth Day := #{book.init_time()}\n"
+      puts " == Book Name := #{book.book_name()} [#{book.book_id}]\n"
+      puts " == Book Mark := #{book.get_open_chapter_name()}/#{book.get_open_verse_name()}\n" if book.is_opened?()
+      puts ""
+
+      StateMigrate.checkout( book )
+      StateMigrate.copy_commit_id_to_branch( book )
+
+      puts "Checkout from master to branch was successful.\n"
+      puts ""
+
+
+    end
+
+
+  end
+
+
+end

data/lib/controller/admin/diff.rb

@@ -0,0 +1,75 @@
+#!/usr/bin/ruby
+	
+module SafeDb
+
+  # The <b>diff use case</b> spells out the key differences between the safe book
+  # on the master line the one on the current working branch. There are two types
+  # of diff - a checkout diff or a checkin diff.
+  #
+  # == a checkout diff
+  #
+  # 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
+  #
+  # == a checkin diff
+  #
+  # 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
+  #
+  class Diff < UseCase
+
+    # The checkin and checkout boolean flags that signal which way round to do the diff
+    attr_writer :checkin, :checkout
+
+    # The <b>diff use case</b> compares the database state of the branch with
+    # that of the master and displays the results without masking sensitive
+    # credentials.
+    def execute
+
+      book = Book.new()
+
+      print_both = @checkin.nil?() && @checkout.nil?()
+      print_checkin = !@checkin.nil?() || print_both
+      print_checkout = !@checkout.nil?() || print_both
+
+      puts ""
+      puts " == Birth Day := #{book.init_time()}\n"
+      puts " == Book Name := #{book.book_name()} [#{book.book_id}]\n"
+      puts " == Book Mark := #{book.get_open_chapter_name()}/#{book.get_open_verse_name()}\n" if book.is_opened?()
+      puts ""
+
+      master_data = book.to_master_data()
+      branch_data = book.to_branch_data()
+
+      StateInspect.checkout_prophecies( master_data, branch_data ) if print_checkout
+      StateInspect.checkin_prophecies( master_data, branch_data ) if print_checkin
+
+      puts ""
+      puts "   master has #{master_data.length()} chapters, and #{book.get_master_verse_count()} verses.\n"
+      puts "   branch has #{branch_data.length()} chapters, and #{book.get_branch_verse_count()} verses.\n"
+      puts ""
+
+    end
+
+
+  end
+
+
+end

data/lib/{usecase → controller/admin}/export.rb

@@ -12,36 +12,37 @@ module SafeDb
 
     def execute
 
-      return unless ops_key_exists?
-      master_db = KeyApi.read_master_db()
+      book = Book.new()
 
       puts ""
       puts "### #############################################################\n"
-      puts "### Book Birthday =>> #{KeyApi.to_db_create_date(master_db)}\n"
-      puts "### The Book Name =>> #{KeyApi.to_db_domain_name(master_db)}\n"
-      puts "### The Book (Id) =>> #{KeyApi.to_db_domain_id(master_db)}\n"
-      puts "### #############################################################\n"
       puts "--- --------------------------------------------------------------\n"
+      puts ""
+      puts " The Birthday := #{book.init_time()}\n"
+      puts " Book Name    := #{book.book_name()}\n"
+      puts " Book Id      := #{book.book_id()}\n"
+      puts " Open Chapter := #{book.get_open_chapter_name()}\n" if book.has_open_chapter_name?()
+      puts " Open Verse   := #{book.get_open_verse_name()}\n"   if book.has_open_verse_name?()
+      puts ""
 
-      chapters = KeyApi.to_matching_dictionary( master_db, ENVELOPE_KEY_PREFIX )
-      export_filename = "safedb.#{KeyApi.read_app_id()}.#{KeyNow.yyjjj_hhmm_ss_nanosec()}.json"
+      export_filename = "safedb.#{KeyNow.yyjjj_hhmm_ss_nanosec()}.#{book.book_id()}.json"
       export_filepath = File.join( Dir.pwd, export_filename )
 
       exported_struct = {}
       verse_count = 0
 
-      chapters.each_pair do | chapter_name, crumb_dictionary |
+      book.branch_chapter_keys().each_pair do | chapter_name, chapter_keys |
 
-        chapter_struct = KeyDb.from_json( KeyApi.content_unlock( crumb_dictionary ) )
-        verse_count += chapter_struct.length
-        exported_struct.store( chapter_name, chapter_struct )
+        chapter_data = Content.unlock_branch_chapter( chapter_keys )
+        verse_count += chapter_data.length
+        exported_struct.store( chapter_name, chapter_data )
 
       end
 
-      File.write( export_filepath, JSON.pretty_generate( exported_struct ) )
+      File.write( export_filepath, JSON.pretty_generate( exported_struct ) + "\n" )
 
       puts ""
-      puts "Number of chapters exported >> #{chapters.length}"
+      puts "Number of chapters exported >> #{book.chapter_count()}"
       puts "Number of verses exported >> #{verse_count}"
       puts "The export filename is #{export_filename}"
       puts "The Present Working Directory is #{Dir.pwd}"

data/lib/controller/admin/goto.rb

@@ -0,0 +1,52 @@
+#!/usr/bin/ruby
+
+module SafeDb
+
+  # Goto is a shortcut (or alias even) for the open command that takes an integer
+  # index that effectively specifies which chapter and verse to open.
+  #
+  # Use <b>view</b> to list the valid integer indices for each chapter and verse
+  # combination.
+  #
+  # View maps out and numbers each chapter/verse combination.
+  # Goto with the number effectively shortcuts the open pinpointer.
+  # Show prints out the verse lines at the opened path but masks any secrets.
+  # Tell also prints out the verse lines but unabashedly displays secrets.
+  class Goto < UseCase
+
+    # The index (number) starting with 1 of the envelope and key-path
+    # combination that should be opened.
+    attr_writer :index
+
+    def execute
+
+      book = Book.new()
+      goto_location = 0
+      book.branch_chapter_keys().each_pair do | chapter_name, chapter_keys |
+
+        chapter_data = Content.unlock_branch_chapter( chapter_keys )
+        chapter_data.each_key do | verse_name |
+
+          goto_location += 1
+          next unless @index.to_i == goto_location
+
+          open_uc = Open.new
+          open_uc.chapter = chapter_name
+          open_uc.verse = verse_name
+          open_uc.flow()
+
+          return
+
+        end
+
+
+      end
+
+
+    end
+
+
+  end
+
+
+end

data/lib/controller/admin/import.rb

@@ -0,0 +1,54 @@
+#!/usr/bin/ruby
+	
+module SafeDb
+
+  # The <b>import use case</b> takes a filepath parameter in order to pull in
+  # a <em>json</em> formatted data structure. It then proceeds to merge each
+  # chapter of the source JSON structure into the corresponding chapter of
+  # the destination, handling duplicate key/value pairs in a sensible way.
+  #
+  class Import < UseCase
+
+    attr_writer :import_filepath
+
+    # The <b>import use case</b> takes a filepath parameter in order to pull in
+    # a <em>json</em> formatted data structure. It then proceeds to merge each
+    # chapter of the source JSON structure into the corresponding chapter of
+    # the destination, handling duplicate key/value pairs in a sensible way.
+    def execute
+
+      book = Book.new()
+
+      abort "Cannot find the import file at path #{@import_filepath}" unless File.exists?( @import_filepath )
+
+      puts ""
+      puts "### #############################################################\n"
+      puts "--- -------------------------------------------------------------\n"
+      puts ""
+      puts " Book Name   := #{book.book_name()}\n"
+      puts " Book Id     := #{book.book_id()}\n"
+      puts " Import from := #{@import_filepath}\n"
+      puts " Import time := #{KeyNow.readable()}\n"
+      puts ""
+
+      new_verse_count = 0
+      data_store = DataStore.from_json( File.read( @import_filepath ) )
+      data_store.each_pair do | chapter_name, chapter_data |
+        book.import_chapter( chapter_name, chapter_data )
+        new_verse_count += chapter_data.length()
+      end
+
+      book.write()
+
+      puts ""
+      puts "#{data_store.length()} chapters and #{new_verse_count} verses were successfully imported.\n"
+      puts ""
+
+
+    end
+
+
+  end
+
+
+end