safedb 0.3.1011 → 0.4.1002

data/lib/controller/edit/editverse.rb

@@ -0,0 +1,48 @@
+#!/usr/bin/ruby
+	
+module SafeDb
+
+  # Any {UseCase} class wishing to edit a safe verse can make use of the functionality
+  # in this parent by exposing an edit_verse() method.
+  #
+  # Classes extending this class will have access to
+  #
+  # - a <tt>@chapther_data</tt> **data** structure
+  # - a <tt>@chapther_id</tt> **string** index
+  # - a <tt>@has_chapter</tt> **boolean** indicator
+  # - a <tt>@verse_data</tt> **data** structure
+  # - a <tt>@verse_id</tt> **string** index
+  # - a <tt>@has_verse</tt> **boolean** indicator
+  #
+  # After the edit method completes the amended chapter data structure will be encrypted
+  # and streamed to a ciphertext file.
+  class EditVerse < UseCase
+
+    # This parental behaviour sets up common ubiquitous chapter and verse data structures
+    # and indices. It then calls the child's query_verse() behaviour and once that is complete
+    # it encrypts and persists an (updated) Book and the amended chapter.
+    #
+    # The streaming process also deletes the current (old) Book and chapter crypts.
+    def execute
+
+      # Before calling the edit_verse() method we perform some
+      # preparatory activities that check, validate and setup.
+      read_verse()
+
+      # This is the expected edit() method that will do and deliver
+      # the intented core contracted value proposition.
+      edit_verse()
+
+      # Now encrypt the changed verse and then write it out to a
+      # chapter crypt file whilst garbage collecting the now spurious
+      # and superceded script.
+      update_verse()
+
+
+    end
+
+
+  end
+
+
+end

data/lib/controller/edit/put.rb

@@ -0,0 +1,35 @@
+#!/usr/bin/ruby
+	
+module SafeDb
+
+  # The <b>put use case</b> follows <b>open</b> and it adds secrets into an
+  # <em>(encrypted at rest)</em> <b>envelope</b>. Put can be called many times
+  # and when done, the <b>lock use case</b> can be called to commit all opened
+  # secrets into the configured storage engines.
+  #
+  # Calling <em>put</em> <b>before</b> calling open or <b>after</b> calling lock
+  # is not allowed and will result in an error.
+  #
+  # == Put Pre-Conditions
+  #
+  # At the point of calling the put use case
+  #
+  # - the safe must be <b>logged in</b> and a chapter and verse opened
+  # - the key / value pair being put must pass minimum standards
+  class Put < EditVerse
+
+    attr_writer :credential_id, :credential_value
+
+    # Execute the act of validating and then putting the credential key and
+    # its value into the chapter and verse location, overwriting if need be.
+    def edit_verse()
+
+      @verse.store( @credential_id, @credential_value )
+
+    end
+
+
+  end
+
+
+end

data/lib/controller/edit/remove.rb

@@ -0,0 +1,29 @@
+#!/usr/bin/ruby
+	
+module SafeDb
+
+  # The <tt>remove</tt> use case takes away one or more of the safe's core entities.
+  #
+  # - at <tt>verse</tt> level - it can delete one or more lines
+  # - at <tt>chapter</tt> level - it can delete one or more verses
+  # - at <tt>book</tt> level - it can delete one or more chapters
+  # - at <tt>safe</tt> level - it can delete one book
+  #
+  class Remove < EditVerse
+
+    attr_writer :line_id
+
+    # Deletion that currently expects an open chapter and verse and always
+    # wants to delete only one line (key/value pair).
+    def edit_verse()
+
+      @verse.delete( @line_id )
+      @verse.delete( "#{Indices::INGESTED_FILE_LINE_NAME_KEY}#{@line_id}" )
+
+    end
+
+
+  end
+
+
+end

data/lib/{usecase → controller}/files/README.md

@@ -1,5 +1,5 @@
 
-# safe file | ingest and eject files
+# safe read | safe write | reading and writing files
 
 You ingest a file with **safe file** and then **safe eject** will output that file into the present working directory.
 

data/lib/controller/files/read.rb

@@ -0,0 +1,36 @@
+#!/usr/bin/ruby
+	
+module SafeDb
+
+  # The <b>read use case</b> pulls a file in from either an accessible filesystem.
+  #
+  # This use case expects a @file_url parameter.
+  class Read < EditVerse
+
+    attr_writer :file_key, :file_url
+
+    # The <b>read use case</b> pulls a file in from an accessible filesystem.
+    def edit_verse()
+
+      file_full_path = ::File.absolute_path( @file_url )
+      file_base_name = ::File.basename( file_full_path )
+      file_content64 = Base64.urlsafe_encode64( ::File.read( file_full_path ) )
+
+      log.info(x) { "Key name of the file to ingest => #{@file_key}" }
+      log.info(x) { "Ingesting file at path => #{file_full_path}" }
+      log.info(x) { "The name of the file to ingest is => #{file_base_name}" }
+      log.info(x) { "Size of base64 file content => [#{file_content64.length}]" }
+
+      filedata_map = {}
+      filedata_map.store( Indices::INGESTED_FILE_BASE_NAME_KEY, file_base_name )
+      filedata_map.store( Indices::INGESTED_FILE_CONTENT64_KEY, file_content64 )
+
+      @verse.store( Indices::INGESTED_FILE_LINE_NAME_KEY + @file_key, filedata_map )
+
+    end
+
+
+  end
+
+
+end

data/lib/{usecase/files/eject.rb → controller/files/write.rb}

@@ -2,33 +2,29 @@
 	
 module SafeDb
 
-  # The <b>eject use case</b> writes (or overwrites) a file or files.
+  # The <b>write use case</b> writes (or overwrites) a file or files.
   # Files are always ejected into the present working directory. If an
   # overwrite is detected a backup is taken of the about to be clobbered
   # file.
   #
   # If a keyname is provided then only the file against that key is ejected.
   # No keyname will eject every file in the opened chapter and verse.
-  class Eject < UseCase
+  class Write < QueryVerse
 
     attr_writer :file_key, :to_dir
 
-    # Files are always ejected into the present working directory and any
-    # about to be clobbered files are backed up with a timestamp.
-    #
-    # If a keyname is provided then only the file against that key is ejected.
-    # No keyname will eject every file in the opened chapter and verse.
-    def execute
+    # Use the chapter and verse setup to read the parameter {@key_name}
+    # and print its corresponding value without a line feed or return.
+    def query_verse()
 
-      return unless ops_key_exists?
-      master_db = get_master_database()
-      return if unopened_envelope?( master_db )
-      chapter_id = ENVELOPE_KEY_PREFIX + master_db[ ENV_PATH ]
-      verse_id = master_db[ KEY_PATH ]
-      chapter_data = KeyDb.from_json( KeyApi.content_unlock( master_db[ chapter_id ] ) )
+      bcv_name = "#{@book.book_name()}/#{@book.get_open_chapter_name()}/#{@book.get_open_verse_name()}"
 
-      base64_content = chapter_data[ verse_id ][ "#{FILE_KEY_PREFIX}#{@file_key}" ][ FILE_CONTENT_KEY ]
-      simple_filename = chapter_data[ verse_id ][ "#{FILE_KEY_PREFIX}#{@file_key}" ][ FILE_NAME_KEY ]
+      puts ""
+      puts "book/chapter/verse\n"
+      puts "#{bcv_name} (#{@verse.length()})\n"
+
+      base64_content = @verse[ Indices::INGESTED_FILE_LINE_NAME_KEY + @file_key ][ Indices::INGESTED_FILE_CONTENT64_KEY ]
+      simple_filename = @verse[ Indices::INGESTED_FILE_LINE_NAME_KEY + @file_key ][ Indices::INGESTED_FILE_BASE_NAME_KEY ]
 
       # Do a mkdir_p if @to_dir has some valid non-whitespace text
       # If so check that we have permissions to write to the specified folder
@@ -44,12 +40,11 @@ module SafeDb
       puts "Clobbered File = #{backup_filename}" if will_clobber
       puts "Prescribed Directory = #{@to_dir}" unless @to_dir.nil?
       puts "Present Directory = #{Dir.pwd}" if @to_dir.nil?
-      puts "Ejected Filename = #{simple_filename}"
+      puts "Written Out Filename = #{simple_filename}"
       puts "The Full Filepath = #{file_full_path}"
-      puts "Chapter and Verse = #{master_db[ENV_PATH]}::#{verse_id}"
-      puts "Ejected File Key = #{@file_key}"
+      puts "Written File Key = #{@file_key}"
       puts ""
-      puts "File successfully ejected from the safe."
+      puts "File successfully written from safe to filesystem."
       puts ""
 
       File.write( backup_file_path, File.read( file_full_path ) ) if will_clobber

data/lib/controller/query/print.rb

@@ -0,0 +1,26 @@
+#!/usr/bin/ruby
+	
+module SafeDb
+
+  # The print use case prints out a credential value without a line
+  # feed or any other contextual information.
+  #
+  # Print is perfect for reading values from scripts or using unix
+  # like pipe behaviour to pass credentials to other commands.
+  class Print < QueryVerse
+
+    attr_writer :key_name
+
+    # Use the chapter and verse setup to read the parameter {@key_name}
+    # and print its corresponding value without a line feed or return.
+    def query_verse()
+
+      print @verse[ @key_name ]
+
+    end
+
+
+  end
+
+
+end

data/lib/controller/query/queryverse.rb

@@ -0,0 +1,39 @@
+#!/usr/bin/ruby
+	
+module SafeDb
+
+  # Any {UseCase} class wishing to query a safe verse can make use of the functionality
+  # in this parent by exposing an query_verse() method.
+  #
+  # Classes extending this class will have access to
+  #
+  # - a <tt>@chapther_data</tt> **data** structure
+  # - a <tt>@chapther_id</tt> **string** index
+  # - a <tt>@has_chapter</tt> **boolean** indicator
+  # - a <tt>@verse_data</tt> **data** structure
+  # - a <tt>@verse_id</tt> **string** index
+  # - a <tt>@has_verse</tt> **boolean** indicator
+  #
+  # The query_verse() method is not succeeded by any behaviour in the parent. Chilc classes
+  # must do their own output management.
+  class QueryVerse < UseCase
+
+    # This parental behaviour sets up common ubiquitous chapter and verse data structures
+    # and indices.
+    def execute
+
+      # Before calling the edit_verse() method we perform some
+      # preparatory activities that check, validate and setup.
+      read_verse()
+
+      # The query verse behaviour implemented by the child classes will read and
+      # perhaps display credentials without changing state.
+      query_verse()
+
+    end
+
+
+  end
+
+
+end

data/lib/controller/query/show.rb

@@ -0,0 +1,50 @@
+#!/usr/bin/ruby
+
+module SafeDb
+
+  # Show the mini dictionary of key-value pairs within the logged in book
+  # at the opened chapter and verse.
+  #
+  # If no dictionary exists at the opened chapter and verse a suitable
+  # message is pushed out to the console.
+  class Show < QueryVerse
+
+    # We expect the book to be opened at a given chapter and verse location. This
+    # use case simply (sensitively) shows the pertinent data lines contained within
+    # the opened verse.
+    def query_verse()
+
+      @book.print_book_mark()
+      if @verse.empty?()
+
+        puts JSON.pretty_generate( {} )
+        puts ""
+        return
+
+      end
+
+      show_map = {}
+      @verse.each do | key_str, value |
+
+        is_file = key_str.start_with? Indices::INGESTED_FILE_LINE_NAME_KEY
+        value.store( Indices::INGESTED_FILE_CONTENT64_KEY, Indices::SECRET_MASK_STRING ) if is_file
+        show_map.store( key_str[ Indices::INGESTED_FILE_LINE_NAME_KEY.length() .. -1 ], value ) if is_file
+        next if is_file
+
+        is_secret = key_str.start_with? "@"
+        showable_val = Indices::SECRET_MASK_STRING if is_secret
+        showable_val = value unless is_secret
+        show_map.store( key_str, showable_val )
+
+      end
+
+      puts JSON.pretty_generate( show_map )
+      puts ""
+
+    end
+
+
+  end
+
+
+end

data/lib/{session/require.gem.rb → controller/requirer.rb}

@@ -1,7 +1,7 @@
 #!/usr/bin/ruby
 # coding: utf-8
 
-module OpenSession
+module SafeDb
 
 
   # Require every file with a dot rb extension that is
@@ -50,7 +50,7 @@ module OpenSession
   # In the plugins hierarchy, you'll notice that the child classes
   # are always below the parents. This strategy works if the +inheritors+
   # are in the same gem as the +inherited+.
-  class RecursivelyRequire
+  class Require
 
     # Require every file with a dot rb extension that is
     # +either in or recursively below+ the file path given
@@ -83,24 +83,28 @@ module OpenSession
     # their extension classes in the lower subdirectories.
     #
     # @param gem_filepath [String] path to callling gem (use <tt>__FILE</tt>)
-    def self.now gem_filepath
+    def self.gems( gem_filepath )
 
-      require_relative "../usecase/cmd"
+      require_relative "../version"
+      require_relative "../controller/usecase"
+      require_relative "../controller/admin/access"
+      require_relative "../controller/edit/editverse"
+      require_relative "../controller/query/queryverse"
 
       gem_basepath = File.expand_path "..", gem_filepath
 
-      log.info(x) { "@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@" }
-      log.info(x) { "@@@@ Require Gems In or Under [#{gem_basepath}]" }
-      log.info(x) { "@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@" }
+      log.debug(x) { "@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@" }
+      log.debug(x) { "@@@@ Require Gems In or Under [#{gem_basepath}]" }
+      log.debug(x) { "@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@" }
 
       Dir["#{gem_basepath}/**/*.rb"].each do |gem_path|
 
-        log.info(x) { "@@@@ => #{gem_path}" }
+        log.debug(x) { "@@@@ => #{gem_path}" }
         require gem_path
 
       end
 
-      log.info(x) { "@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@" }
+      log.debug(x) { "@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@" }
 
     end
 

data/lib/{usecase → controller}/set.rb

@@ -4,7 +4,7 @@ module SafeDb
 
   # The <b>set <em>use case</em></b> is the generic tool for setting book scoped
   # configuration directives. These directives can only be read, written, updated
-  # or removed during a logged in session.
+  # or removed during a logged in branch.
   #
   # The mirror of this use case is <b><em>unset</em></b>.
   #
@@ -19,11 +19,11 @@ module SafeDb
 
     # The <b>set <em>use case</em></b> is the generic tool for setting book scoped
     # configuration directives. These directives can only be read, written, updated
-    # or removed during a logged in session.
+    # or removed during a logged in branch.
     def execute
 
       return unless ops_key_exists?
-      master_db = KeyApi.read_master_db()
+      master_db = Book.read()
 
       master_db[ @directive_name ] = @directive_value
 
@@ -31,7 +31,7 @@ module SafeDb
       puts JSON.pretty_generate( master_db )
       puts ""
 
-      KeyApi.write_master_db( create_header(), master_db )
+      Book.write( create_header(), master_db )
 
     end
 

data/lib/controller/usecase.rb

@@ -0,0 +1,244 @@
+#!/usr/bin/ruby
+# coding: utf-8
+
+module SafeDb
+
+  # The parent SafeDb use case is designed to be extended by the cli
+  # (command line) use cases like {SafeDb::Open}, {SafeDb::Put} and
+  # {SafeDb::Lock} because it describes behaviour common to at least two
+  # (but usually more) of the use cases.
+  #
+  # == Common Use Case Behaviour
+  #
+  # This {SafeDb::UseCase} use case is designed to be extended and does preparatory
+  # work to create favourable and useful conditions to make use cases readable,
+  # less repetitive, simpler and concise.
+  #
+  # == Machine (Workstation) Configuration File
+  #
+  # The global configuration filepath is found off the home directory using {Dir.home}.
+  #
+  #    ~/.safedb.net/safedb.net.configuration.ini
+  #
+  # The global configuration file in INI format is managed through the methods
+  #
+  # - {grab} read the value at key_name from the default section
+  # - {stash} put directive key/value pair in default section
+  # - {read} read the value at key_name from the parameter section
+  # - {write} put directive key/value pair in parameter section
+  class UseCase
+
+    # All controllers are initialized here meaning that there will be automatic
+    # execution of very frequently used setup behaviour. This includes
+    # - checking for (and reporting a lack of) the safe token environment variable
+    # - asimilating a fact file if employed by the specific use case (controller)
+    def initialize
+
+      class_name = self.class.name.split(":").last.downcase
+      is_no_token_uc = [ "token", "init", "id" ].include? class_name
+      return if is_no_token_uc
+
+      exit(100) unless ops_key_exists?
+
+      # Chop off all fact work for now. May need to resurrect for VPN functionality.
+      return
+
+      fact_filepath = File.sister_filepath( self, "ini", :execute )
+      log.info(x) { "Search location for INI factfile is [#{fact_filepath}]" }
+      return unless File.exists?( fact_filepath )
+
+      @facts = FactFind.new()
+      add_secret_facts @facts
+      @facts.assimilate_ini_file( fact_filepath )
+      @dictionary = @facts.f[ @facts.to_symbol( class_name ) ]
+
+    end
+
+
+    # This parental behaviour decrypts and reads the ubiquitous chapter and verse
+    # data structures and indices.
+    def read_verse()
+
+# @todo => consider doing the book index opening with initializer UNLESS token/admin use case
+
+      @book = Book.new()
+      return if @book.unopened_chapter_verse()
+      @verse = @book.get_open_verse_data()
+
+    end
+
+
+    # This parental behaviour encrypts and writes out the in-play chapter
+    # and verse data. This behaviour also deletes the crypt file belonging
+    # to the now superceeded chapter state.
+    def update_verse()
+
+      @book.write_open_chapter()
+      Show.new.flow()
+
+    end
+
+
+    # Execute the use cases's flow from beginning when
+    # you validate the input and parameters through the
+    # memorize and execute.
+    def flow()
+
+      check_pre_conditions
+      execute
+      check_post_conditions
+
+    end
+
+
+    # Validate the input parameters and check that the current
+    # state is perfect for executing the use case.
+    #
+    # If either of the above fail - the validation function should
+    # set a human readable string and then throw an exception.
+    def check_pre_conditions
+
+      begin
+        pre_validation
+      rescue OpenError::CliError => e
+
+        puts ""
+        puts "Your command did not complete successfully."
+        puts "Pre validation checks failed."
+        puts ""
+        puts "   => #{e.message}"
+        puts ""
+        abort e.message
+      end
+
+    end
+
+
+    # Override me if you need to
+    def pre_validation
+
+    end
+
+
+    # After the main flow of events certain state conditions
+    # must hold true thus demonstrating that the observable
+    # value has indeed ben delivered.
+    #
+    # Child classes should subclass this method and place any
+    # post execution (post condition) checks in it and then
+    # make a call to this method through the "super" keyword.
+    def check_post_conditions
+
+      begin
+        post_validation
+      rescue OpenError::CliError => e
+
+        puts ""
+        puts "Your command did not complete successfully."
+        puts "Post validation checks failed."
+        puts ""
+        puts "   => #{e.message}"
+        ####        puts "   => #{e.culprit}"
+        puts ""
+        abort e.message
+      end
+
+    end
+
+
+    # Child classes should subclass this method and place any
+    # post execution (post condition) checks in it and then
+    # make a call to this method through the "super" keyword if
+    # this method gets any global behaviour in it worth calling.
+    def post_validation
+
+    end
+
+
+    # Execute the main flow of events of the use case. Any
+    # exceptions thrown are captured and if the instance
+    # variale [@human_readable_message] is set - tell the
+    # user about it. Without any message - just tell the
+    # user something went wrong and tell them where the logs
+    # are that might carry more information.
+    def execute
+
+    end
+
+
+    private
+
+
+    ENV_VAR_PREFIX_A = "evar."
+    ENV_VAR_PREFIX_B = "@evar."
+    COMMANDMENT = "safe"
+    ENV_VAR_KEY_NAME = "SAFE_TTY_TOKEN"
+    ENV_PATH = "env.path"
+    KEY_PATH = "key.path"
+    ENVELOPE_KEY_PREFIX = "envelope@"
+
+
+# -->    def add_secret_facts fact_db
+
+# -->      master_db = Book.read()
+# -->      raise ArgumentError.new "There is no open chapter here." if unopened_envelope?( master_db )
+# -->      chapter_id = ENVELOPE_KEY_PREFIX + master_db[ ENV_PATH ]
+# -->      verse_id = master_db[ KEY_PATH ]
+# -->      chapter_data = DataStore.from_json( Lock.content_unlock( master_db[ chapter_id ] ) )
+# -->      mini_dictionary = chapter_data[ master_db[ KEY_PATH ] ]
+
+# -->      mini_dictionary.each do | key_str, value_str|
+# -->        fact_db.assimilate_fact( "secrets", key_str, value_str )
+# -->      end
+
+# -->    end
+
+
+    def ops_key_exists?
+
+      log_env()
+
+      if ( ENV.has_key? ENV_VAR_KEY_NAME )
+        return true
+      end
+
+      puts ""
+      puts "safe needs you to create a branch key."
+      puts "To automate this step see the documentation."
+      puts "To create the key run the below command."
+      puts ""
+      puts "    export #{ENV_VAR_KEY_NAME}=`#{COMMANDMENT} token`"
+      puts ""
+      puts "Those are backticks surrounding `#{COMMANDMENT} token`"
+      puts "Not apostrophes."
+      puts ""
+
+      return false
+
+    end
+
+
+    def log_env()
+
+      log.debug(x) { "Gem Root Folder    => #{Gem.dir()}" }
+      log.debug(x) { "Gem Config File    => #{Gem.config_file()}" }
+      log.debug(x) { "Gem Binary Path    => #{Gem.default_bindir()}" }
+      log.debug(x) { "Gem Host Path      => #{Gem.host()}" }
+      log.debug(x) { "Gem Caller Folder  => #{Gem.location_of_caller()}" }
+      log.debug(x) { "Gem Paths List     => #{Gem.path()}" }
+      log.debug(x) { "Gem Platforms      => #{Gem.platforms()}" }
+      log.debug(x) { "Gem Ruby Version X => #{Gem.ruby()}" }
+      log.debug(x) { "Gem Ruby Version Y => #{Gem::VERSION}" }
+      log.debug(x) { "Gem Ruby Version Z => #{Gem.latest_rubygems_version()}" }
+      log.debug(x) { "Gem User Folder    => #{Gem.user_dir()}" }
+      log.debug(x) { "Gem User Home      => #{Gem.user_home()}" }
+
+      return
+
+    end
+
+
+  end
+
+
+end