safedb 0.3.1011 → 0.4.1002

data/lib/model/branch.rb

@@ -0,0 +1,48 @@
+#!/usr/bin/ruby
+
+module SafeDb
+
+  # The shell can access the 152 characters of crypt and salt text
+  # that was set (exported) at the beginning when the shell woke up and typically
+  # executed its .bash_aliases script.
+  class Branch
+
+    def self.to_token()
+
+      raw_env_var_value = ENV[Indices::TOKEN_VARIABLE_NAME]
+      raise_token_error( Indices::TOKEN_VARIABLE_NAME, "not present") unless raw_env_var_value
+
+      env_var_value = raw_env_var_value.strip
+      raise_token_error( Indices::TOKEN_VARIABLE_NAME, "consists only of whitespace") if raw_env_var_value.empty?
+
+      size_msg = "length should contain exactly #{Indices::TOKEN_VARIABLE_SIZE} characters"
+      raise_token_error( Indices::TOKEN_VARIABLE_NAME, size_msg ) unless env_var_value.length == Indices::TOKEN_VARIABLE_SIZE
+
+      return env_var_value
+
+    end
+
+
+    private
+
+
+    def self.raise_token_error env_var_name, message
+
+      puts ""
+      puts "#{Indices::TOKEN_VARIABLE_NAME} environment variable #{message}."
+      puts "To instantiate it you can use the below command."
+      puts ""
+      puts "$ export #{Indices::TOKEN_VARIABLE_NAME}=`safe token`"
+      puts ""
+      puts "ps => those are backticks around `safe token` (not apostrophes)."
+      puts ""
+
+      raise RuntimeError, "#{Indices::TOKEN_VARIABLE_NAME} environment variable #{message}."
+
+    end
+
+
+  end
+
+
+end

data/lib/model/checkin.feature

@@ -0,0 +1,33 @@
+
+## The typical shells
+
+Learn to run emacs commands in a batch so that we can open the below in an automated fashion. Learn to robotically communicate with and manipulate emacs. This will improve your efficiency many many fold.
+
+.%  CORE [dir]              856 Dired by name    /home/apollo/projects/safedb.net/lib/core/
+  * SEARCH [shell]           36 Shell:run        /home/apollo/projects/safedb.net/
+  * RAKE [shell]             94 Shell:run        /home/apollo/projects/safedb.net/
+ %  USECASE [dir]          1080 Dired by name    /home/apollo/projects/safedb.net/lib/usecase/
+ %  safedb.net              924 Dired by name    /home/apollo/projects/safedb.net/
+  * SAFE 2 [shell]           16 Shell:run        /home/apollo/
+  * SAFE 1 [shell]           16 Shell:run        /home/apollo/
+
+# Feature Checkin
+
+## In one shell
+
+safe init boys
+safe login boys
+safe import ~/safedb.test.data.json
+safe view
+safe show (failure because no open chapter has been set)
+safe goto 3
+safe checkin
+
+
+## In Another shell
+
+safe login boys
+
+Failure occurs
+
+R{\370\204m\265^v}\276\223^RZ(\320^N\333e.time":"Wed Apr 10 09:06:37 2019","book.name":"boys","book.init.version":"safedb-v0.3.1012","book.chapter.keys":{"dbms.accounts":{"content.id":"00cxarwaia0s4g","content.iv":"VzbG5IBQEuFdpRFerzGqHPejVKdKekcl","chapter.key.crypt":"Rx5BWXXM9uK5cbiH006WupaHVciXL8q%XooFdogSazMdHnqlJHuulMoeBtZxxJse"},"aws.console.accounts":{"content.id":"r6sc5ope3n3sfi","content.iv":"Jgh4c2aeh2Qjwt@ZaTEJxfK@6A%dzUoz","chapter.key.crypt":"9t5xxjDgyN4jQGQyw%9CHvTzGqJU@MiOWFGFKpGAuz@@fT8FJVO2fjoQIHEjTDfa"},"ops":{"content.id":"uk2u9bnzpynizc","content.iv":"AnvTgyJPbZpBju8kSsT8es0NmHlv2j9d","chapter.key.crypt":"TYyASQ71sgMbzNOxGVgojdb28M1%4iPDDsSDQz8TevjABYY887hqoPTRpvx18xUT"},"git":{"content.id":"r3dso6qr88l5lm","content.iv":"I9hykwLIGrvgp0j2jMQyMJC3QhWg0xSD","chapter.key.crypt":"0QLO7FawspMzEpRnB%6Wb3dVyjiJ36IX5SRp7QNOkU5ut@sMy9%KNYQ42XKA8yTj"}},"book.open.chapter":"aws.console.accounts","book.open.verse":"aimbrain.prod"}

data/lib/{configs/README.md → model/configs.md}

@@ -5,7 +5,7 @@ Safe's behaviour can (by default) be modified in a manner that is scoped in 4 wa
 
 1. a **book global** scope
 2. a **machine local** scope
-3. a **shell session** scope and
+3. a **shell** 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.
@@ -33,11 +33,11 @@ If a directive with a book global scope says "Yes" and the same directive exists
 A book global directive overrides its machine local twin.
 
 
-## 3. Shell Session Scope
+## 3. Shell Scope
 
-The self explanatory **shell session scoped** directives override their siblings be they book global or machine local.
+The self explanatory **shell 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.
+Alas, their elevated privileges are countered by relatively short lifespans. shell directives only last until either a logout is issued or the shell comes to an end.
 
 
 ## 4. Default | Machine Global Scope

data/lib/model/content.rb

@@ -0,0 +1,214 @@
+#!/usr/bin/ruby
+
+module SafeDb
+
+  # This class both locks content, writing the ciphertext to a file, and
+  # unlocks content after reading ciphertext from a file.
+  #
+  # It supports the encryption of large bodies of text or binary because
+  # it uses the efficient and effective AES asymmetric algorithm.
+  #
+  class Content
+
+
+    # Lock the content body provided - place the resulting ciphertext
+    # inside a file named by a random identifier, then write this identifier
+    # along wih the initialization and encryption key into the provided
+    # key-value map (hash).
+    #
+    # The content ciphertext derived from encrypting the body is stored
+    # in a file underneath the provided content header.
+    #
+    # @param book_id [String] used to determine the book's master crypt folder
+    # @param crypt_key [Key] the key used to (symmetrically) encrypt the content provided
+    # @param data_store [DataMap] either DataMap or DataStore containing the content id and random iv
+    # @param content_body [String] content to encryt and the ciphertext will be stored
+    def self.lock_master( book_id, crypt_key, data_store, content_body )
+
+      content_id = Identifier.get_random_identifier( Indices::CONTENT_ID_LENGTH )
+      data_store.set( Indices::CONTENT_IDENTIFIER, content_id )
+      master_crypt_path = FileTree.master_crypts_filepath( book_id, content_id )
+      iv_base64 = KeyIV.new().for_storage()
+      data_store.set( Indices::CONTENT_RANDOM_IV, iv_base64 )
+      random_iv = KeyIV.in_binary( iv_base64 )
+
+      lock_it( master_crypt_path, crypt_key, random_iv, content_body, TextChunk.crypt_header( book_id ) )
+
+    end
+
+
+
+    # Lock the content body provided - place the resulting ciphertext
+    # inside a file named by a random identifier, then write this identifier
+    # along wih the initialization and encryption key into the provided
+    # key-value map (hash).
+    #
+    # The content ciphertext derived from encrypting the body is stored
+    # in a file.
+    #
+    # @param data_store [DataMap] either DataMap or DataStore containing the content id and random iv
+    # @param content_body [String] content to encryt and the ciphertext will be stored
+    def self.lock_chapter( data_store, content_body )
+
+      branch_id = Identifier.derive_branch_id( Branch.to_token() )
+      branch_indices_file = FileTree.branch_indices_filepath( branch_id )
+      book_id = DataMap.new( branch_indices_file ).read( Indices::BRANCH_DATA, Indices::CURRENT_BRANCH_BOOK_ID )
+
+      old_content_id = data_store[ Indices::CONTENT_IDENTIFIER ] if data_store.has_key?(Indices::CONTENT_IDENTIFIER)
+
+      new_content_id = Identifier.get_random_identifier( Indices::CONTENT_ID_LENGTH )
+      data_store.store( Indices::CONTENT_IDENTIFIER, new_content_id )
+
+      new_chapter_crypt_path = FileTree.branch_crypts_filepath( book_id, branch_id, new_content_id )
+
+      iv_base64 = KeyIV.new().for_storage()
+      data_store.store( Indices::CONTENT_RANDOM_IV, iv_base64 )
+      random_iv = KeyIV.in_binary( iv_base64 )
+
+      crypt_key = Key.from_random()
+      data_store.store( Indices::CRYPT_CIPHER_TEXT, crypt_key.to_char64() )
+
+      lock_it( new_chapter_crypt_path, crypt_key, random_iv, content_body, TextChunk.crypt_header( book_id ) )
+
+      unless old_content_id.nil?
+        old_chapter_crypt_path = FileTree.branch_crypts_filepath( book_id, branch_id, old_content_id )
+        File.delete( old_chapter_crypt_path )
+      end
+
+    end
+
+
+
+    # Lock the content body provided - place the resulting ciphertext
+    # inside a file named by a random identifier, then write this identifier
+    # along wih the initialization and encryption key into the provided
+    # key-value map (hash).
+    #
+    # The content ciphertext derived from encrypting the body is stored
+    # in a file underneath the provided content header.
+    #
+    # This method returns the highly random key instantiated for the purposes
+    # of encrypting the content.
+    #
+    # @param crypt_path [File] path to the crypt file holding the encrypted ciphertext
+    # @param crypt_key [Key] the key used to (symmetrically) encrypt the content provided
+    # @param random_iv [String] the random initialization vector for the encryption
+    # @param content_body [String] content to encryt and the ciphertext will be stored
+    # @param crypt_header [String] string that tops and tails the content's ciphertext
+    def self.lock_it( crypt_path, crypt_key, random_iv, content_body, crypt_header )
+
+      binary_ctext = crypt_key.do_encrypt_text( random_iv, content_body )
+      binary_to_write( crypt_path, crypt_header, binary_ctext )
+
+    end
+
+
+
+    # Use the content's external id to find the ciphertext file that is to be unlocked.
+    # Then use the unlock key from the parameter along with the random IV that is inside
+    # the {DataMap} or {DataStore} to decrypt and return the ciphertext.
+    #
+    # @param unlock_key [Key] symmetric key that was used to encrypt the ciphertext
+    # @param data_store [DataMap] either {DataMap} or {DataStore} containing content id and random iv
+    # @return [String] the resulting decrypted text that was encrypted with the parameter key
+    def self.unlock_master( unlock_key, data_store )
+
+      book_id = data_store.section()
+      crypt_path = FileTree.master_crypts_filepath( book_id, data_store.get( Indices::CONTENT_IDENTIFIER ) )
+      random_iv = KeyIV.in_binary( data_store.get( Indices::CONTENT_RANDOM_IV ) )
+      return unlock_it( crypt_path, unlock_key, random_iv )
+
+    end
+
+
+
+    # Use the content's external id to find the ciphertext file that is to be unlocked.
+    # Then use the unlock key from the parameter along with the random IV that is inside
+    # the {DataMap} or {DataStore} to decrypt and return the ciphertext.
+    #
+    # @param data_store [DataMap] either {DataMap} or {DataStore} containing content id and random iv
+    # @return [String] the resulting decrypted text that was encrypted with the parameter key
+    def self.unlock_branch_chapter( data_store )
+
+      branch_id = Identifier.derive_branch_id( Branch.to_token() )
+      branch_indices_file = FileTree.branch_indices_filepath( branch_id )
+      book_id = DataMap.new( branch_indices_file ).read( Indices::BRANCH_DATA, Indices::CURRENT_BRANCH_BOOK_ID )
+
+      content_id = data_store[ Indices::CONTENT_IDENTIFIER ]
+      crypt_key = Key.from_char64( data_store[ Indices::CRYPT_CIPHER_TEXT ] )
+      random_iv = KeyIV.in_binary( data_store[ Indices::CONTENT_RANDOM_IV ] )
+
+      crypt_path = FileTree.branch_crypts_filepath( book_id, branch_id, content_id )
+      return DataStore.from_json( unlock_it( crypt_path, crypt_key, random_iv ) )
+
+    end
+
+
+
+    # Use the content's external id to find the ciphertext file that is to be unlocked.
+    # Then use the unlock key from the parameter along with the random IV that is inside
+    # the {DataMap} or {DataStore} to decrypt and return the ciphertext.
+    #
+    # @param book_id [String] ID of the book to unlock the chapter of
+    # @param data_store [DataMap] either {DataMap} or {DataStore} containing content id and random iv
+    # @return [String] the resulting decrypted text that was encrypted with the parameter key
+    def self.unlock_master_chapter( book_id, data_store )
+
+      random_iv = KeyIV.in_binary( data_store[ Indices::CONTENT_RANDOM_IV ] )
+      crypt_key = Key.from_char64( data_store[ Indices::CRYPT_CIPHER_TEXT ] )
+      content_id = data_store[ Indices::CONTENT_IDENTIFIER ]
+      crypt_path = FileTree.master_crypts_filepath( book_id, content_id )
+      return DataStore.from_json( unlock_it( crypt_path, crypt_key, random_iv ) )
+
+    end
+
+
+
+    # Use the content's external id to find the ciphertext file that is to be unlocked.
+    # Then use the unlock key from the parameter along with the random IV that is inside
+    # the {DataMap} or {DataStore} to decrypt and return the ciphertext.
+    #
+    # @param crypt_path [File] path to the crypt file holding the encrypted ciphertext
+    # @param unlock_key [Key] symmetric key that was used to encrypt the ciphertext
+    # @param random_iv [String] the random initialization vector for the encryption
+    # @return [String] the resulting decrypted text that was encrypted with the parameter key
+    def self.unlock_it( crypt_path, unlock_key, random_iv )
+
+      return unlock_key.do_decrypt_text( random_iv, binary_from_read( crypt_path ) )
+
+    end
+
+
+    private
+
+
+    def self.binary_to_write( to_filepath, crypt_header, binary_ciphertext )
+
+      base64_ciphertext = Base64.encode64( binary_ciphertext )
+
+      content_to_write =
+        crypt_header +
+        Indices::CONTENT_BLOCK_DELIMITER +
+        Indices::CONTENT_BLOCK_START_STRING +
+        base64_ciphertext +
+        Indices::CONTENT_BLOCK_END_STRING +
+        Indices::CONTENT_BLOCK_DELIMITER
+
+      File.write( to_filepath, content_to_write )
+
+    end
+
+
+    def self.binary_from_read( from_filepath )
+
+      file_text = File.read( from_filepath )
+      core_data = file_text.in_between( Indices::CONTENT_BLOCK_START_STRING, Indices::CONTENT_BLOCK_END_STRING ).strip
+      return Base64.decode64( core_data )
+
+    end
+
+
+  end
+
+
+end

data/lib/model/indices.rb

@@ -0,0 +1,132 @@
+#!/usr/bin/ruby
+
+module SafeDb
+
+  # Indices are key/value pairs that serve within the safe database index
+  # files for denoting, pinpointing, writing and retrieving data values as
+  # well as for naming of files folders and other artifacts.
+  class Indices
+
+    # The command used to invoke the safe database
+    COMMANDER = "safe"
+
+    # The short url name of the safe personal database.
+    SAFE_URL_NAME = "safedb.net"
+
+    # The desired length of a safe book ergonomic identifier.
+    SAFE_BOOK_ID_LENGTH = 12
+
+    # The fully qualified domain name of the safedb home website
+    SAFE_GEM_WEBSITE = "https://www.#{SAFE_URL_NAME}"
+
+    # The safe database github clonable url for the ruby software
+    SAFE_GITHUB_URL = "https://github.com/devops4me/#{SAFE_URL_NAME}"
+
+    # The name ofthe master crypts folder.
+    MASTER_CRYPTS_FOLDER_NAME = "safedb-master-crypts"
+
+    # The name ofthe branch indices folder.
+    BRANCH_INDICES_FOLDER_NAME = "safedb-branch-indices"
+
+    # The name ofthe branch crypts folder.
+    BRANCH_CRYPTS_FOLDER_NAME = "safedb-branch-crypts"
+
+    # The file-system location of the safe database tree
+    SAFE_DATABASE_FOLDER = File.join( Dir.home, ".#{SAFE_URL_NAME}" )
+
+    # The path to the master indices file
+    MASTER_INDICES_FILEPATH = File.join( SAFE_DATABASE_FOLDER, "safedb-master-indices.ini" )
+
+    # The desired length of a content identifier
+    CONTENT_ID_LENGTH  = 14
+
+    # Content identifiers act to name chapter and/or index database files.
+    CONTENT_IDENTIFIER = "content.id"
+
+    # 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
+    COMMIT_IDENTIFIER = "commit.identifier"
+
+    # The bootup id is set on machine boot and lasts until the reboot or shutdown.
+    BOOTUP_IDENTIFIER = "bootup.identifier"
+
+    # The key ciphertext that sits against the trio of either master, branch or chapter
+    CRYPT_CIPHER_TEXT = "crypt.cipher"
+
+    # This is the global section header of the branch book index file
+    BRANCH_DATA = "branch.data"
+
+    # The time of the first book login within this shell
+    BRANCH_INITIAL_LOGIN_TIME = "branch.initial.login.time"
+
+    # The most recent time that any book of this branch was accessed
+    BRANCH_LAST_ACCESSED_TIME = "branch.last.accessed.time"
+
+    # The ID of the book being currently used by this branch
+    CURRENT_BRANCH_BOOK_ID = "current.branch.book.id"
+
+    # The time this book was first logged into during this branch
+    BOOK_BRANCH_LOGIN_TIME = "book.branch.login.time"
+
+    # The time this book was last accessed during this branch
+    BOOK_LAST_ACCESSED_TIME = "book.last.accessed.time"
+
+    # The start of the content block laid out in a crypt file
+    CONTENT_BLOCK_START_STRING = "0123456789abcdef0123456789abcdef0123456789abcdef0123456789ab\n"
+
+    # The end of the content block laid out in a crypt file
+    CONTENT_BLOCK_END_STRING   = "ba9876543210fedcba9876543210fedcba9876543210fedcba9876543210\n"
+
+    # The delimeter used to separate headers from ciphertext in a crypt file
+    CONTENT_BLOCK_DELIMITER    = "~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n"
+
+    # The name of the safe tty token environment variable
+    TOKEN_VARIABLE_NAME = "SAFE_TTY_TOKEN"
+
+    # The expected length of the tty token environment variable
+    TOKEN_VARIABLE_SIZE = 152
+
+    # Character (randomly) repeated to mask credentials
+    # Asterices, hyphens, plus and equal signs are common alternatives.
+    SECRET_MASK_STRING = "*" * rand( 7 .. 17 )
+
+    # The birthday (initialization time) of this safe book.
+    SAFE_BOOK_INITIALIZE_TIME = "book.init.time"
+
+    # The name of this safe book.
+    SAFE_BOOK_NAME = "book.name"
+
+    # The application version that oversaw this book's initialization.
+    SAFE_BOOK_INIT_VERSION = "book.init.version"
+
+    # The application version that oversaw this book's initialization.
+    SAFE_BOOK_CURRENT_VERSION = "book.current.version"
+
+    # The handle to the chapter keys inside the book index.
+    SAFE_BOOK_CHAPTER_KEYS = "book.chapter.keys"
+
+    # The opened chapter id/name in the current book
+    OPENED_CHAPTER_NAME = "book.open.chapter"
+
+    # The opened verse id/name in the current book
+    OPENED_VERSE_NAME = "book.open.verse"
+
+    # The application version that oversaw this book's initialization.
+    SAFE_VERSION_STRING = "safedb-v#{SafeDb::VERSION}"
+
+    # Handle to the key name of the ingested file in the submap verse
+    INGESTED_FILE_LINE_NAME_KEY = "safedb.file::"
+
+    # Handle to the file base64 content within the submap verse
+    INGESTED_FILE_CONTENT64_KEY = "file.content"
+
+    # Handle to the simple name of the ingested file in the submap verse
+    INGESTED_FILE_BASE_NAME_KEY = "file.name"
+
+
+  end
+
+
+end