safedb 0.01.0001

data/lib/usecase/docker/docker.rb

@@ -0,0 +1,49 @@
+#!/usr/bin/ruby
+	
+module SafeDb
+
+    # This docker use case handles the ...
+    #
+    #     safe docker login
+    #     safe docker logout
+
+    class Docker < UseCase
+
+        # The command which currently must be login, logout or
+        # an empty string.
+        attr_writer :command
+
+        def execute
+
+            return unless ops_key_exists?
+            master_db = get_master_database()
+            return if unopened_envelope?( master_db )
+
+            # Get the open chapter identifier (id).
+            # Decide whether chapter already exists.
+            # Then get (or instantiate) the chapter's hash data structure
+            chapter_id = ENVELOPE_KEY_PREFIX + master_db[ ENV_PATH ]
+            verse_id = master_db[ KEY_PATH ]
+            chapter_exists = KeyApi.db_envelope_exists?( master_db[ chapter_id ] )
+
+            # Unlock the chapter data structure by supplying
+            # key/value mini-dictionary breadcrumbs sitting
+            # within the master database at the section labelled
+            # envelope@<<actual_chapter_id>>.
+            chapter_data = KeyDb.from_json( KeyApi.content_unlock( master_db[ chapter_id ] ) )
+
+            key_value_dictionary = chapter_data[ verse_id ]
+            docker_username = key_value_dictionary[ "docker.username" ]
+            docker_password = key_value_dictionary[ "@docker.password" ]
+            docker_login_cmd = "docker login --username #{docker_username} --password #{docker_password} 2>/dev/null"
+            docker_logout_cmd = "docker logout"
+            docker_cmd = @command.eql?( "logout" ) ? docker_logout_cmd : docker_login_cmd
+            system docker_cmd
+
+        end
+
+
+    end
+
+
+end

data/lib/usecase/edit/README.md

@@ -0,0 +1,43 @@
+
+### safe put | safe delete | safe copy | safe paste
+
+# edit use cases | copy | paste | delete
+
+The edit use cases create, delete and update the credentials and configuration inside your safe.
+
+## Common Usage
+
+Typically you login to a book, open a chapter and verse, then you put **`key/value`** pairs, known as **lines**.
+
+```
+safe login joe@home
+
+# -- -------------------------------------------------- -- #
+# -- Create chapter (email) and verse <<email-address>> -- #
+# -- -------------------------------------------------- -- #
+safe open email joebloggs@gmail.com
+
+# -- ---------------------------- -- #
+# -- Populate it with credentials -- #
+# -- ---------------------------- -- #
+safe put gmail.id joebloggs
+safe put @password s3cr3et
+safe put recovery.phone 07500875278
+
+# -- ----------------------------------------------- -- #
+# -- Now copy and then paste a line (key/value pair) -- #
+# -- ----------------------------------------------- -- #
+safe copy recovery.phone
+safe open email joe@ywork.com
+safe paste
+```
+
+## editing behaviour
+
+**These use cases are intuitive and behave almost like what you would expect.** The safe ethos is for commands to behave according to which of the 5 levels you are at.
+
+
+| Command          | Verse                         | Chapter                          | Book                            |
+|:---------------- |:----------------------------- |:-------------------------------- |:------------------------------- |
+| safe copy <<id>> | Copy one of the verse's lines | Copy one of the chapter's verses | Copy one of the book's chapters |
+| safe copy        | Copy all of the verse's lines | Copy all of the chapter's verses | Copy all of the book's chapters |

data/lib/usecase/edit/delete.rb

@@ -0,0 +1,46 @@
+#!/usr/bin/ruby
+	
+module SafeDb
+
+  # The <b>delete use case</b> delete's one or more of the safe's 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 DeleteMe < UseCase
+
+    attr_writer :entity_id
+
+    # Deletion that currently expects an open chapter and verse and always
+    # wants to delete only one line (key/value pair).
+    def execute
+
+      return unless ops_key_exists?
+      master_db = KeyApi.read_master_db()
+      return if unopened_envelope?( master_db )
+
+      chapter_id = ENVELOPE_KEY_PREFIX + master_db[ ENV_PATH ]
+      chapter_exists = KeyApi.db_envelope_exists?( master_db[ chapter_id ] )
+      chapter_data = KeyDb.from_json( KeyApi.content_unlock( master_db[ chapter_id ] ) ) if chapter_exists
+      chapter_data = KeyDb.new() unless chapter_exists
+
+      content_hdr = create_header()
+      master_db[ chapter_id ] = {} unless chapter_exists
+      verse_id = master_db[ KEY_PATH ]
+
+      chapter_data.delete_entry( verse_id, @entity_id )
+      chapter_data.delete_entry( verse_id, "#{FILE_KEY_PREFIX}#{@entity_id}" )
+
+      KeyApi.content_lock( master_db[ chapter_id ], chapter_data.to_json, content_hdr )
+      KeyApi.write_master_db( content_hdr, master_db )
+      Show.new.flow_of_events
+
+    end
+
+
+  end
+
+
+end

data/lib/usecase/export.rb

@@ -0,0 +1,40 @@
+#!/usr/bin/ruby
+
+module SafeDb
+
+  # Export the entire book if no chapter and verse is specified (achieved with a safe close),
+  # or the chapter if only the chapter is open (safe shut or safe open <<chapter>>, or the
+  # mini-dictionary at the verse if both chapter and verse are open.
+  class Export < UseCase
+
+    def get_chapter_data( chapter_key )
+      return KeyDb.from_json( KeyApi.content_unlock( chapter_key ) )
+    end
+
+    def execute
+
+      return unless ops_key_exists?
+      master_db = KeyApi.read_master_db()
+
+      return if unopened_envelope?( master_db )
+
+      chapter_id = ENVELOPE_KEY_PREFIX + master_db[ ENV_PATH ]
+      has_chapter = KeyApi.db_envelope_exists?( master_db[ chapter_id ] )
+
+      unless has_chapter
+        puts "{}"
+        return
+      end
+
+      chapter_data = get_chapter_data( master_db[ chapter_id ] )
+      puts JSON.pretty_generate( chapter_data )
+
+      return
+
+    end
+
+
+  end
+
+
+end

data/lib/usecase/files/README.md

@@ -0,0 +1,37 @@
+
+# safe file | ingest and eject files
+
+You ingest a file with **safe file** and then **safe eject** will output that file into the present working directory.
+
+If safe detects during an eject, that a file already exists with the same name - it backs it up with a timestamp before ejecting and clobbering the existing file.
+
+```bash
+safe open <<chapter-name>> <<verse-name>>
+safe file <<keyname>> <</path/to/private-key.pem>>
+safe eject <<keyname>>
+safe show
+```
+
+To pull in 3 certificate oriented files for Kubernetes one could use these commands.
+
+```bash
+safe open production kubernetes
+safe file kubernetes.cert ~/.kubectl/kube.prod.cert.pem
+safe file kubernetes.ca.cert ~/.kubectl/kube.prod.ca.cert.pem
+safe file kubernetes.key ~/.kubectl/kube.prod.key.pem
+cd /tmp
+safe eject
+```
+
+The safe ingests the files and spits them out whenever you so desire.
+**Binary files** are supported and can be safely pulled in with <tt>safe file</tt> and ejected at any point in the future.
+
+## remote (external) files
+
+The **local filesystem** is the most common, but by no means the only file storage location. You can read from and write to
+
+- a zip file **`zip://`**
+- an S3 filesystem **`s3://`**
+- SSH locations **`<<user>>@<<hostname>>:/path/to/file`**
+- a git repository **`git@github.com`**
+- a **google drive** store

data/lib/usecase/files/eject.rb

@@ -0,0 +1,56 @@
+#!/usr/bin/ruby
+	
+module SafeDb
+
+  # The <b>eject 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
+
+    attr_writer :file_key
+
+    # 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
+
+      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 ] ) )
+
+      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 ]
+      file_full_path = File.join( Dir.pwd, simple_filename )
+      backup_filename = KeyNow.yyjjj_hhmm_sst() + "-" + simple_filename
+      backup_file_path = File.join( Dir.pwd, backup_filename )
+      will_clobber = File.file?( file_full_path )
+
+      File.write( backup_file_path, File.read( file_full_path ) ) if will_clobber
+      ::File.write( file_full_path, Base64.urlsafe_decode64( base64_content ) )
+
+      puts ""
+      puts "File successfully ejected from safe into current directory."
+      puts ""
+      puts "Clobbered File = #{backup_filename}" if will_clobber
+      puts "Current Directory = #{Dir.pwd}"
+      puts "Ejected Filename = #{simple_filename}"
+      puts "Chapter and Verse = #{master_db[ENV_PATH]}:#{verse_id}"
+      puts "Ejected File Key = #{@file_key}"
+      puts ""
+
+    end
+
+
+  end
+
+
+end

data/lib/usecase/files/file_me.rb

@@ -0,0 +1,78 @@
+#!/usr/bin/ruby
+	
+module SafeDb
+
+  # The <b>file use case</b> pulls a file in from either an accessible filesystem
+  # or from a remote http, https, git, S3, GoogleDrive and/or ssh source.
+  #
+  # The @file_url is the most common parameter given to this use case.
+  class FileMe < UseCase
+
+    attr_writer :file_key, :file_url
+
+    # There are 3 maps involved in the implementation and they are all (or in part) retrieved and/or
+    # created as necessary. They are
+    #
+    # - the current chapter as a map
+    # - the current verse as a map
+    # - the file's keyname as a map
+    #
+    # Once the maps have been found and/or created if necessary the file's keyname map is either
+    # populated or amended with the following data.
+    #
+    # - filename | {UseCase::FILE_NAME_KEY} | the file's simple name
+    # - content64 | {UseCase::FILE_CONTENT_KEY} | the file's base64 content
+    def execute
+
+      return unless ops_key_exists?
+      master_db = KeyApi.read_master_db()
+      return if unopened_envelope?( master_db )
+
+      chapter_id = ENVELOPE_KEY_PREFIX + master_db[ ENV_PATH ]
+      chapter_exists = KeyApi.db_envelope_exists?( master_db[ chapter_id ] )
+      chapter_data = KeyDb.from_json( KeyApi.content_unlock( master_db[ chapter_id ] ) ) if chapter_exists
+      chapter_data = KeyDb.new() unless chapter_exists
+
+      content_hdr = create_header()
+      master_db[ chapter_id ] = {} unless chapter_exists
+      verse_id = master_db[ KEY_PATH ]
+
+      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}]" }
+
+      chapter_data.create_map_entry( verse_id, "#{FILE_KEY_PREFIX}#{@file_key}", FILE_NAME_KEY, file_base_name )
+      chapter_data.create_map_entry( verse_id, "#{FILE_KEY_PREFIX}#{@file_key}", FILE_CONTENT_KEY, file_content64 )
+
+      KeyApi.content_lock( master_db[ chapter_id ], chapter_data.to_json, content_hdr )
+      KeyApi.write_master_db( content_hdr, master_db )
+
+      Show.new.flow_of_events
+
+    end
+
+
+    private
+
+
+    # Perform pre-conditional validations in preparation to executing the main flow
+    # of events for this use case. This method may throw the below exceptions.
+    #
+    # @raise [SafeDirNotConfigured] if the safe's url has not been configured
+    # @raise [EmailAddrNotConfigured] if the email address has not been configured
+    # @raise [StoreUrlNotConfigured] if the crypt store url is not configured
+    def pre_validation
+
+
+    end
+
+
+  end
+
+
+end

data/lib/usecase/files/read.rb

@@ -0,0 +1,169 @@
+#!/usr/bin/ruby
+	
+module SafeDb
+
+  # The <b>read use case</b> pulls a file in from either an accessible filesystem
+  # or from a remote http, https, git, S3, GoogleDrive and/or ssh source.
+  #
+  # This use case expects a @file_url parameter. The actions it takes are to
+  #
+  # - register @in.url to mirror @file_url
+  # - register @out.url to mirror @file_url
+  # - check the location of @file_url
+  # - if no file exists it humbly finishes up
+  #
+  # If a file does exist at the @in.url this use case
+  #
+  # - handles HOME directory enabling portability
+  # - creates an encryption key and random iv
+  # - creates a file (name) id
+  # - stores the file byte and human readable size
+  # - stores the extension if it has one
+  # - stores the last created date
+  # - stores the last modified date
+  # - stores the (now) in date
+  #
+  # Once done it displays <b><em>key facts about the file</em></b>.
+  class Read < UseCase
+
+# -- ---------------------- --#
+# -- ---------------------- --#
+# -- [SAFE] Name Changes    --#
+# -- ---------------------- --#
+# -- Change env.path ~> open.chapter
+# -- Change key.path ~> open.verse
+# -- Change envelope@xxxx ~> chapter@xxxx
+# --
+# -- Change filenames to ~~~~~> book.db.breadcrumbs
+# -- Change filenames to ~~~~~> chapter.cipher.file
+# -- Change filenames to ~~~~~> safe.db.abc123xyzpq
+# -- ---------------------- --#
+# --    {
+# --        "db.create.date": "Sat Aug 11 11:20:16 2018 ( 18223.1120.07.511467675 )",
+# --        "db.domain.name": "ab.com",
+# --        "db.domain.id": "uhow-ku9l",
+# --        "env.path": "aa",
+# --        "key.path": "aa",
+# --        "envelope@aa": {
+# --            "content.xid": "3uzk12dxity",
+# --            "content.iv": "XTVe%qIGKVvWw@EKcgSa153nfVPaMVJH",
+# --            "content.key": "1u3b2o6KLiAUmt11yYEDThJw1E5Mh4%1iHYOpJQjWiYLthUGgl8IZ5szus8Fz2Jt"
+# --        }
+# --    }
+# -- ---------------------- --#
+# -- ---------------------- --#
+
+    attr_writer :file_url
+
+    # The <b>read use case</b> pulls a file in from either an accessible filesystem
+    # or from a remote http, https, git, S3, GoogleDrive and/or ssh source.
+    def execute
+
+      return unless ops_key_exists?
+      master_db = KeyApi.read_master_db()
+      return if unopened_envelope?( master_db )
+
+      # -- Get the open chapter identifier (id).
+      # -- Decide whether chapter already exists.
+      # -- Then get (or instantiate) the chapter's hash data structure
+      # --
+      chapter_id = ENVELOPE_KEY_PREFIX + master_db[ ENV_PATH ]
+      chapter_exists = KeyApi.db_envelope_exists?( master_db[ chapter_id ] )
+      chapter_data = KeyDb.from_json( KeyApi.content_unlock( master_db[ chapter_id ] ) ) if chapter_exists
+      chapter_data = KeyDb.new() unless chapter_exists
+
+      content_hdr = create_header()
+
+      # -- If no content envelope exists we need to place
+      # -- an empty one inside the appdb content database.
+      # --
+      master_db[ chapter_id ] = {} unless chapter_exists
+
+      # -- We populate (PUT) file instance attributes into
+      # -- the mini-dictionary at the [VERSE] location.
+      # --
+      verse_id = master_db[ KEY_PATH ]
+      file_absolute_path = ::File.absolute_path( @file_url )
+      chapter_data.create_entry( verse_id, "@in.url", file_absolute_path )
+      chapter_data.create_entry( verse_id, "@out.url", file_absolute_path )
+
+      # -- Lock No.1
+      # --
+      # -- Lock the file content and leave the 3 breadcrumbs
+      # -- (content id, content iv and content key) inside
+      # -- the file attributes mini dictionary to facilitate
+      # -- decrypting and writing out the file again.
+      # --
+      KeyApi.content_lock( chapter_data[ verse_id ], ::File.read( @file_url ), content_hdr )
+
+      # -- Lock No.2
+      # --
+      # -- Lock the chapter's data which includes the new or
+      # -- updated mini-dictionary that holds the breadcrumbs
+      # -- (content id, content iv and content key) that will
+      # -- be used to decrypt and write out the file content.
+      # --
+      # -- Leave another set of breadcrumbs inside the master
+      # -- database (content id, content iv and content key)
+      # -- to facilitate decrypting the chapter's data.
+      # --
+      KeyApi.content_lock( master_db[ chapter_id ], chapter_data.to_json, content_hdr )
+
+      # -- Lock No.3
+      # --
+      # -- Re-lock the master database including the breadcrumbs
+      # -- (content id, content iv and content key) that will
+      # -- (in the future) decrypt this chapter's data.
+      # --
+      KeyApi.write_master_db( content_hdr, master_db )
+
+
+      # -- Communicate that the indicated file has just been
+      # -- successfully ingested into the safe.
+      # --
+      print_file_success master_db[ ENV_PATH ], verse_id, file_absolute_path
+
+    end
+
+
+    private
+
+
+    def print_file_success chapter_id, verse_id, file_url
+
+      puts ""
+      puts "|-"
+      puts "|- Chapter ~> #{chapter_id}"
+      puts "|- + Verse ~> #{verse_id}"
+      puts "|-"
+      puts "|- In File ~> #{file_url}"
+      puts "|-"
+      puts "|- File cocooned inside your safe."
+      puts "|-"
+      puts "|-Command Options"
+      puts "|-"
+      puts "|-    #{COMMANDMENT} put out.dir ~/this/folder"
+      puts "|-    #{COMMANDMENT} put out.name new-filename.txt"
+      puts "|-    #{COMMANDMENT} write"
+      puts "|-"
+      puts ""
+
+    end
+
+
+    # Perform pre-conditional validations in preparation to executing the main flow
+    # of events for this use case. This method may throw the below exceptions.
+    #
+    # @raise [SafeDirNotConfigured] if the safe's url has not been configured
+    # @raise [EmailAddrNotConfigured] if the email address has not been configured
+    # @raise [StoreUrlNotConfigured] if the crypt store url is not configured
+    def pre_validation
+
+
+    end
+
+
+  end
+
+
+end

data/lib/usecase/files/write.rb

@@ -0,0 +1,89 @@
+#!/usr/bin/ruby
+	
+module SafeDb
+
+  # The <b>write use case</b> writes (or overwrites) a file at the
+  # out url destination.
+  class Write < UseCase
+
+    attr_writer :file_url
+
+    # The <b>read use case</b> pulls a file in from either an accessible filesystem
+    # or from a remote http, https, git, S3, GoogleDrive and/or ssh source.
+    def execute
+
+      return unless ops_key_exists?
+      master_db = get_master_database()
+      return if unopened_envelope?( master_db )
+
+      # Get the open chapter identifier (id).
+      # Decide whether chapter already exists.
+      # Then get (or instantiate) the chapter's hash data structure
+      chapter_id = ENVELOPE_KEY_PREFIX + master_db[ ENV_PATH ]
+      verse_id = master_db[ KEY_PATH ]
+      chapter_exists = KeyApi.db_envelope_exists?( master_db[ chapter_id ] )
+
+
+      # @todo begin
+      # Throw an exception (error) if the chapter
+      # either exists and is empty or does not exist.
+      # @todo end
+
+
+      # Unlock the chapter data structure by supplying
+      # key/value mini-dictionary breadcrumbs sitting
+      # within the master database at the section labelled
+      # envelope@<<actual_chapter_id>>.
+      chapter_data = KeyDb.from_json( KeyApi.content_unlock( master_db[ chapter_id ] ) )
+
+
+      # Unlock the file content by supplying the
+      # key/value mini-dictionary breadcrumbs sitting
+      # within the chapter's data structure in the
+      # section labelled <<verse_id>>.
+      file_content = KeyApi.content_unlock( chapter_data[ verse_id ] )
+
+
+      # We read the location url we plan to eject the
+      # file out into.
+      file_path = @file_url ? @file_url : chapter_data[ verse_id ][ "@out.url" ]
+      file_name = ::File.basename( file_path)
+
+      # If the directory the file will be exported to does
+      # not exist we promptly create it.
+      FileUtils.mkdir_p( File.dirname( file_path ) )
+
+      # Create a backup file if we can detect that a
+      # file occupies the eject (write) filepath.
+      backup_file_path = ::File.join( ::File.dirname( file_path ), KeyNow.yyjjj_hhmm_sst() + "-" + file_name )
+      ::File.write( backup_file_path, ::File.read( file_path ) ) if ::File.file?( file_path )
+
+
+      # Now write (and if necessary overwrite) the eject
+      # file url path with the previously ingested content.
+      ::File.write( file_path, file_content )
+
+
+      # Communicate that the indicated file has just been
+      # successfully written out from the safe.
+      print_file_success( master_db[ ENV_PATH ], verse_id, file_path )
+
+    end
+
+
+    private
+
+
+    # Document a successful write of a file cocooned in the safe.
+    # @param chapter_id the chapter of the file written out
+    # @param verse_id the verse of the file written out
+    # @param file_url the filepath the file was written to
+    def print_file_success chapter_id, verse_id, file_url
+      puts "File [#{file_url}] written out of safe at chapter [#{chapter_id}] and verse [#{verse_id}]."
+    end
+
+
+  end
+
+
+end

data/lib/usecase/goto.rb

@@ -0,0 +1,57 @@
+#!/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 <envelope> and <key> to open.
+  #
+  # Use <b>view</b> to list the valid integer indices for each envelope and key
+  # combination.
+  #
+  # View maps out and numbers each envelope/key combination.
+  # Goto with the number effectively shortcuts the open pin pointer command.
+  # Show prints the dictionary at the opened path masking any secrets.
+  #
+  # Once goto is enacted all path CRUD commands come into play as if you had
+  # opened the path. These include put, copy, paste, show, tell and delete.
+  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
+
+      return unless ops_key_exists?
+      master_db = KeyApi.read_master_db()
+
+      goto_location = 0
+      envelope_dictionaries = KeyApi.to_matching_dictionary( master_db, ENVELOPE_KEY_PREFIX )
+      envelope_dictionaries.each_pair do | envelope_name, crumb_dictionary |
+
+        envelope_content = KeyDb.from_json( KeyApi.content_unlock( crumb_dictionary ) )
+        envelope_content.each_key do | envelope_key |
+
+          goto_location += 1
+          next unless @index.to_i == goto_location
+
+          open_uc = Open.new
+          open_uc.env_path = envelope_name
+          open_uc.key_path = envelope_key
+          open_uc.flow_of_events
+
+          return
+
+        end
+
+
+      end
+
+
+    end
+
+
+  end
+
+
+end