safedb 0.01.0001

data/Rakefile

@@ -0,0 +1,16 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+# -
+# - This configuration allows us to run "rake test"
+# - and invoke minitest to execute all files in the
+# - test directory with names ending in "_test.rb".
+# -
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task :default => :test
+

data/bin/safe

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+ 
+require 'interprete'
+
+Interprete.start(ARGV)

data/lib/configs/README.md

@@ -0,0 +1,58 @@
+
+# Modifying Safe's Behaviour | 4 Configuration Scopes
+
+Safe's behaviour can (by default) be modified in a manner that is scoped in 4 ways. Configuration directives can alter behaviour within
+
+1. a **book global** scope
+2. a **machine local** scope
+3. a **shell session** scope and
+4. a **machine global** scope
+
+The scoping concept is similar to Git's --local and --global but it works in a different way.
+
+
+## 1. Book Global Scope
+
+Directives issued against a safe book **"feel local"** but are global in that the behaviour persists on every machine that works with the book.
+
+Git's --local is different because cloning the repository on another machine wipe's out the directives. With safe the directives continue to alter behaviour even when the book is cloned and/or used on another machine.
+
+
+## 2. Machine Local Scope
+
+This is similar to Git's --global directive which affects all repositories owned by a user on a given machine.
+
+Directives with a machine local scope **can influence the behaviour** of every Safe book one logs into on a machine. Move to another machine and the behaviour becomes unstuck.
+
+== Configuration Directive Precedence
+
+Note the sentence **can influence behaviour** as opposed to **will influence behaviour**.
+
+If a directive with a book global scope says "Yes" and the same directive exists but says "No" with machine local scope the "Yes" wins out.
+
+A book global directive overrides its machine local twin.
+
+
+## 3. Shell Session Scope
+
+The self explanatory **shell session scoped** directives override their siblings be they book global or machine local.
+
+Alas, their elevated privileges are countered by relatively short lifespans. Shell session directives only last until either a logout is issued or the shell session comes to an end.
+
+
+## 4. Default | Machine Global Scope
+
+Did you notice only **one (1) user** is affected by directives with a machine local scope as long as it isn't overriden.
+
+Directives with a **machine global scope** are the **default** and are set during an install or upgrade.
+
+They can potentially affect **every user and every safe book**. Even though their longevity is undisputed, their precedence is the lowest when going head to head with their 3 siblings.
+
+## The Naked Eye
+
+Directives with a book global scope **aren't visible to the naked eye**. They are encrypted within the master safe database and thus protected from prying eyes.
+
+The other 3 directive types exist in plain text
+
+- either where the gem is **installed** (machine global scope)
+- or in the INI file in **.safe** off the user's home directory

data/lib/extension/array.rb

@@ -0,0 +1,162 @@
+#!/usr/bin/ruby
+
+#
+# Reopen the core ruby Array class and add the below methods to it.
+#
+# Case Sensitivity rules for [ALL] the below methods that are
+# added to the core Ruby string class.
+#
+# For case insensitive behaviour make sure you downcase both the
+# string object and the parameter strings (or strings within
+# other parameter objects, like arrays and hashes).
+class Array
+
+
+  # The returned string is a result of a union (join) of all the
+  # (expected) string array elements followed by the <b>deletion</b>
+  # of <b>all <em>non</em> alphanumeric characters</b>.
+  #
+  # <b>Disambiguating the String for Cross Platform Use</b>
+  #
+  # This behaviour is typically used for transforming text that is
+  # about to be signed or digested (hashed). Removing all the non
+  # alpha-numeric characters disambiguates the string.
+  #
+  # An example is the exclusion of line ending characters which in
+  # Windows are different from Linux.
+  #
+  # This disambiguation means that signing functions will return the
+  # same result on widely variant platfoms like Windows vs CoreOS.
+  #
+  # @return [String]
+  #    Returns the alphanumeric union of the strings within this array.
+  #
+  # @raise [ArgumentError]
+  #    if the array is nil or empty. Also an error will be thrown if
+  #    the array contains objects that cannot be naturally converted
+  #    to a string.
+  def alphanumeric_union
+    raise ArgumentError, "Cannot do alphanumeric union on an empty array." if self.empty?
+    return self.join.to_alphanumeric
+  end
+
+
+  # Log the array using our logging mixin by printing every array
+  # item into its own log line. In most cases we (the array) are
+  # a list of strings, however if not, each item's to_string method
+  # is invoked and the result printed using one log line.
+  #
+  # The INFO log level is used to log the lines - if this is not
+  #   appropriate create a (level) parameterized log lines method.
+  def log_lines
+
+    self.each do |line|
+      clean_line = line.to_s.chomp.gsub("\\n","")
+      log.info(x) { line } if clean_line.length > 0
+    end
+
+  end
+
+
+  # Get the text [in between] this and that delimeter [exclusively].
+  # Exclusively means the returned text [does not] include either of
+  # the matched delimeters (although an unmatched instance of [this]
+  # delimeter may appear in the in-between text).
+  #
+  # --------------------
+  # Multiple Delimiters
+  # --------------------
+  #
+  # When multiple delimiters exist, the text returned is in between the
+  #
+  #  [a] - first occurrence of [this] delimeter AND the
+  #  [b] - 1st occurrence of [that] delimeter [AFTER] the 1st delimiter
+  #
+  # Instances of [that] delimiter occurring before [this] are ignored.
+  # The text could contain [this] delimeter instances but is guaranteed
+  # not to contain a [that] delimeter.
+  #
+  # -----------
+  # Parameters
+  # -----------
+  #
+  #   this_delimiter : begin delimeter (not included in returned string)
+  #   that_delimiter : end delimeter (not included in returned string)
+  #
+  # -----------
+  # Exceptions
+  # -----------
+  #
+  # An exception (error) will be thrown if
+  #
+  #   => any nil (or empties) exist in the input parameters
+  #   => [this] delimeter does not appear in the in_string
+  #   => [that] delimeter does not appear after [this] one
+  #
+  def before_and_after begin_delimeter, end_delimeter
+
+    Throw.if_nil_or_empty_strings [ self, begin_delimeter, end_delimeter ]
+
+    before_after_lines = []
+    in_middle_bit = false
+
+    self.each do |candidate_line|
+
+      is_middle_boundary = !in_middle_bit && candidate_line.downcase.include?(begin_delimeter.downcase)
+      if is_middle_boundary
+        in_middle_bit = true
+        next
+      end
+
+      unless in_middle_bit
+        before_after_lines.push candidate_line
+        next
+      end
+
+      #--
+      #-- Now we are definitely in the middle bit.
+      #-- Let's check for the middle end delimeter
+      #--
+      if candidate_line.downcase.include? end_delimeter.downcase
+        in_middle_bit = false
+      end
+
+    end
+
+    return before_after_lines
+
+  end
+
+
+  def middlle_bit begin_delimeter, end_delimeter
+
+    Throw.if_nil_or_empty_strings [ self, begin_delimeter, end_delimeter ]
+
+    middle_lines = []
+    in_middle_bit = false
+
+    self.each do |candidate_line|
+
+      is_middle_boundary = !in_middle_bit && candidate_line.downcase.include?(begin_delimeter.downcase)
+      if is_middle_boundary
+        in_middle_bit = true
+        next
+      end
+
+      end_of_middle = in_middle_bit && candidate_line.downcase.include?(end_delimeter.downcase)
+      return middle_lines if end_of_middle
+      
+      #--
+      #-- We are definitely in the middle bit.
+      #--
+      middle_lines.push(candidate_line) if in_middle_bit
+
+    end
+
+    unreachable_str = "This point should be unreachable unless facts are ended."
+    raise RuntimeError.new unreachable_str
+
+  end
+
+
+end

data/lib/extension/dir.rb

@@ -0,0 +1,35 @@
+#!/usr/bin/ruby
+
+# --
+# -- Reopen the core ruby Dirctory class and add the below methods to it.
+# --
+class Dir
+
+  # --
+  # -- Put all the files starting with the given string in
+  # -- alphabetical ascending order and then return the file
+  # -- that comes last.
+  # --
+  # -- Throw an exception if no file in this folder starts
+  # -- with the given string
+  # --
+  def ascii_order_file_starting_with starts_with_string
+
+    recently_added_file = nil
+    filepath_leadstr = File.join self.path, starts_with_string
+    Dir.glob("#{filepath_leadstr}*").sort.each do |candidate_file|
+
+      next if File.directory? candidate_file
+      recently_added_file = candidate_file
+
+    end
+
+    Throw.if_nil recently_added_file
+    Throw.if_not_exists recently_added_file
+    return recently_added_file
+
+  end
+
+
+
+end

data/lib/extension/file.rb

@@ -0,0 +1,123 @@
+#!/usr/bin/ruby
+
+# Reopen the core ruby File class and add the below methods to it.
+class File
+
+    # Get the full filepath of a sister file that potentially lives
+    # in the same directory that the leaf class is executing from and
+    # has the same name as the leaf class but a different extension.
+    #
+    # == Usage
+    #
+    # If class OpenFoo:Bar extends class OpenFoo:Baz and we are looking
+    # for an INI file in the folder that OpenFoo:Bar lives in we can
+    # call this method within OpenFoo:Baz like this.
+    #
+    #   ini_filepath = sister_filepath( "ini", :execute )
+    #   # => /var/lib/gems/2.5.0/gems/fooey-0.2.99/lib/barry/bazzy/bar.ini
+    #
+    # == Common Implementation
+    #
+    # Object orientation scuppers the commonly used technique which
+    # derives the path from __FILE__
+    #
+    #    class_directory = File.dirname( __FILE__ )
+    #    leaf_class_name = self.class.name.split(":").last.downcase
+    #    sister_filepath = File.join ( class_directory, "#{leaf_class_name}.#{extension}" )
+    #
+    # With object orientation - running the above code within the
+    # abstracted (parent) class would produce a resultant filepath
+    # based on the folder the parent class is in rather than the
+    # extended "concrete" class.
+    #
+    # == Value Proposition
+    #
+    # You can call this method from the parent (abstract) class and it
+    # will still correctly return the path to the potential sister file
+    # living in the directory that the leaf class sits in.
+    #
+    # Put differently - this extension method allows code executing in
+    # the parent class to correctly pinpoint a file in the directory of
+    # the leaf class be it in the same or a different folder.
+    #
+    # @param caller
+    #     the calling class object usually passed in using <tt>self</tt>
+    #
+    # @param extension
+    #     the extension of a sister file that carries the same simple
+    #     (downcased) name of the leaf class of this method's caller.
+    #
+    #     Omit the (segregating) period character when providing this
+    #     extension parameter.
+    #
+    # @param method_symbol
+    #     the method name in symbolic form of any method defined in
+    #     the leaf class even if the method overrides one of the same
+    #     name in the parent class.
+    #
+    # @return the filepath of a potential sister file living in the same
+    #         directory as the class, bearing the same (downcased) name
+    #         as the class with the specified extension.
+    def self.sister_filepath caller, extension, method_symbol
+
+      leaf_classname = caller.class.name.split(":").last.downcase
+      execute_method = caller.method( method_symbol )
+      leaf_classpath = execute_method.source_location.first
+      leaf_directory = File.dirname( leaf_classpath )
+      lower_filename = "#{leaf_classname}.#{extension}"
+      return File.join( leaf_directory, lower_filename )
+
+    end
+
+
+  # This method adds (logging its own contents) behaviour to
+  # the standard library {File} class. If this File points to
+  # a directory - that folder's single level content files are
+  # listed inside the logs.
+  #
+  # The <tt>DEBUG</tt> log level is used for logging. To change this
+  # create a new parameterized method.
+  #
+  # @param file_context [String] context denotes the whys and wherefores of this file.
+  def log_contents file_context
+
+    ## This will fail - add physical raise statement.
+    Throw.if_not_exists self
+
+    log.debug(x) { "# -- ------------------------------------------------------------------------ #" }
+    log.debug(x) { "# -- ------------------------------------------------------------------------ #" }
+    log.debug(x) { "# -- The File Path to Log => #{self}" }
+
+    hr_file_size = PrettyPrint.byte_size( File.size(self) )
+    dotless_extension = File.extname( self )[1..-1]
+    parent_dir_name = File.basename( File.dirname( self ) )
+    file_name = File.basename self
+    is_zip = dotless_extension.eql? "zip"
+
+    log.debug(x) { "# -- ------------------------------------------------------------------------ #" }
+    log.debug(x) { "# -- File Name => #{file_name}" }
+    log.debug(x) { "# -- File Size => #{hr_file_size}" }
+    log.debug(x) { "# -- File Type => #{file_context}" }
+    log.debug(x) { "# -- In Folder => #{parent_dir_name}" }
+    log.debug(x) { "# -- ------------------------------------------------------------------------ #" }
+
+    log.debug(x) { "File #{file_name} is a zip (binary) file." } if is_zip
+    return if is_zip
+
+    File.open( self, "r") do | file_obj |
+      line_no = 1
+      file_obj.each_line do | file_line |
+        line_num = sprintf '%03d', line_no
+        clean_line = file_line.chomp.strip
+        log.debug(x) { "# -- [#{line_num}] - #{clean_line}" }
+        line_no += 1
+      end
+    end
+
+    log.debug(x) { "# -- ------------------------------------------------------------------------ #" }
+    log.debug(x) { "# -- [#{file_context}] End of File [ #{File.basename(self)} ]" }
+    log.debug(x) { "# -- ------------------------------------------------------------------------ #" }
+
+  end
+
+end

data/lib/extension/hash.rb

@@ -0,0 +1,33 @@
+#!/usr/bin/ruby
+
+# Reopen the core ruby Hash class and add the below methods to it.
+class Hash
+
+  # This method adds (logging its own contents) behaviour to
+  # the standard library {Hash} class.
+  #
+  # @note This behaviour does not consider that SECRETS may be inside
+  #    the key value maps - it logs itself without a care in the world.
+  #    This functionality must be included if this behaviourr is used by
+  #    any cryptography classes.
+  #
+  # The <tt>DEBUG</tt> log level is used for logging. To change this
+  # create a new parameterized method.
+  def log_contents
+
+    log.debug(x) { "# --- ----------------------------------------------" }
+    log.debug(x) { "# --- Map has [#{self.length}] key/value pairs." }
+    log.debug(x) { "# --- ----------------------------------------------" }
+
+    self.each do |the_key, the_value|
+
+      padded_key = sprintf '%-33s', the_key
+      log.debug(x) { "# --- #{padded_key} => #{the_value}" }
+
+    end
+
+    log.debug(x) { "# --- ----------------------------------------------" }
+
+  end
+
+end