opensecret 0.0.962 → 0.0.988

data/lib/modules/mappers/envelope.rb

@@ -0,0 +1,127 @@
+#!/usr/bin/ruby
+# coding: utf-8
+
+module OpenSecret
+
+  module Mapper
+
+    require 'json'
+
+    # An envelope knows how to manipulate a JSON backed data structure
+    # (put, add etc) <b>after reading and then decrypting it</b> from a
+    # file and <b>before encrypting and then writing it</b> to a file.
+    #
+    # It provides behaviour to which we can create, append (add), update
+    # (change), read parts and delete essentially two structures
+    #
+    # - a collection of name/value pairs
+    # - an  ordered list of values
+    #
+    # == JSON is Not Exposed in the Interface
+    #
+    # An envelope doesn't expose the data format used in the implementation
+    # allowing this to be changed seamlessly to YAMl or other formats.
+    #
+    # == Symmetric Encryption and Decryption
+    #
+    # An envelope supports operations to <b>read from</b> and <b>write to</b>
+    # a known filepath and with a symmetric key it can
+    #
+    # - decrypt <b>after reading from</b> a file and
+    # - encrypt <b>before writing to</b> a (the same) file
+    #
+    # == Hashes as the Primary Data Structure
+    #
+    # Envelope extends {Hash} as the core data structure for holding
+    #
+    # - strings
+    # - arrays
+    # - other hashes
+    # - booleans
+    # - integers and floats
+    class Envelope < Hash
+
+
+      # Read and inject into this envelope, the data structure found in a
+      # file at the path specified in the first parameter.
+      #
+      # Symmetric cryptography is mandatory for the envelope so we must
+      # <b>encrypt before writing</b> and <b>decrypt after reading</b>.
+      #
+      # An argument error will result if a suitable key is not provided.
+      #
+      # If the file does not exist (denoting the first read) all this method
+      # does is to stash the filepath as an instance variable and igore the
+      # decryption key which can be nil (or ommitted).
+      #
+      # @param the_filepath [String]
+      #     absolute path to the file which acts as the persistent mirror to
+      #     this data structure envelope.
+      #
+      # @param decryption_key [String]
+      #     encryption at rest is a given so this mandatory parameter must
+      #     contain a robust symmetric decryption key. The key will be used
+      #     for decryption after the read and it will not linger (ie not cached
+      #     as an instance variable).
+      #
+      # @raise [ArgumentError] if the decryption key is not robust enough.
+      def read the_filepath, decryption_key = nil
+
+        @filepath = the_filepath
+        return unless File.exists? @filepath
+
+        cipher_text = Base64.decode64( File.read( @filepath ).strip )
+        plain_text = ToolBelt::Blowfish.decryptor( cipher_text, decryption_key )
+
+        data_structure = JSON.parse plain_text
+        self.merge! data_structure
+
+      end
+
+
+      # Write the data in this envelope hash map into a file-system
+      # backed mirror whose path was specified in the {self.read} method.
+      #
+      # Technology for encryption at rest is supported by this dictionary
+      # and to this aim, please endeavour to post a robust symmetric
+      # encryption key.
+      #
+      # Calling this {self.write} method when the file at the prescribed path
+      # does not exist results in the directory structure being created
+      # (if necessary) and then the encrypted file being written.
+      #
+      # @param encryption_key [String]
+      #     encryption at rest is a given so this mandatory parameter must
+      #     contain a robust symmetric encryption key. The symmetric key will
+      #     be used for the decryption after the read. Note that the decryption
+      #     key does not linger meaning it isn't cached in an instance variable.
+      def write encryption_key
+
+        FileUtils.mkdir_p(File.dirname(@filepath))
+        cipher_text = Base64.encode64 ToolBelt::Blowfish.encryptor( self.to_json, encryption_key )
+        File.write @filepath, cipher_text
+
+        puts ""
+        puts "=== ============================"
+        puts "=== Envelope State ============="
+        puts "=== ============================"
+
+        a_ini_file = IniFile.new
+        self.each_key do |section_name|
+          a_ini_file[section_name] = self[section_name]
+        end
+        puts a_ini_file.to_s
+
+        puts "=== ============================"
+        puts ""
+
+      end
+
+
+    end
+
+
+  end
+
+
+end

data/lib/modules/mappers/settings.rb

@@ -0,0 +1,170 @@
+#!/usr/bin/ruby
+# coding: utf-8
+
+module OpenSecret
+
+  module Mapper
+
+    require 'inifile'
+    require 'singleton'
+
+    # This class contains basic behaviour for managing a client only
+    # (serverless) session. Configuration directives are read and written
+    # from an INI off the home directory that is created when the session
+    # is first initiated.
+    class Settings
+
+      # Stash the setting directive and its value into the configuration file
+      # using the default settings group.
+      #
+      # The default settings group is resolved via {Collateral::CONTEXT_NAME}
+      #
+      # @param key_name [String] the name of the key whose value is to be written
+      # @param key_value [String] the data item value of the key specified
+      def self.stash key_name, key_value
+        write Collateral::CONTEXT_NAME, key_name, key_value
+      end
+
+
+      # Stash the setting directive and its value into the configuration file
+      # using the default settings group.
+      #
+      # The default settings group is resolved via {Collateral::CONTEXT_NAME}
+      #
+      # @param key_name [String] the name of the key whose value is to be written
+      # @return [String]
+      #    return the value of the configuration directive in the default group
+      def self.grab key_name
+        read Collateral::CONTEXT_NAME, key_name
+      end
+
+
+      # Write the key/value pair in the parameter into the session's
+      # configuration INI file that lives in a context-named folder
+      # off the home directory.
+      #
+      # The session file will be in a folder whose name is simply
+      # the dot prefixed context_name. The session file itself will
+      # be named using context_name + @@filename_tail
+      #
+      # @example ~/.openbox/openbox-session.ini is the filepath for context "openbox"
+      #
+      # If neither the folder nor file exist, both are created.
+      # If the file did not exist a new one will with the contents
+      # (if the key is length and the value is 2m).
+      #
+      # [openbox]
+      # length = 2m
+      #
+      # If the file does already exist, an appropriate merge will be
+      # performed to create or update the section name, key name and
+      # value. The file may end up looking like
+      #
+      # [closedbox]
+      # shape = cuboid
+      # color = blue
+      #
+      # [openbox]
+      # length = 2m
+      # width = 3m
+      #
+      # @param section_name [String] name grouping the section of config values
+      # @param key [String] the key name of config directive to be written into the file
+      # @param value [String] value of the config directive to be written into the file
+      #
+      def self.write section_name, key, value
+
+        config_filepath = Collateral.instance.config_file
+        config_directory = Collateral.instance.config_directory
+
+        FileUtils.mkdir_p config_directory unless File.exists? config_directory
+
+        config_map = IniFile.new( :filename => config_filepath, :encoding => 'UTF-8' )
+        config_map = IniFile.load( config_filepath ) if File.exists? config_filepath
+
+        config_map[section_name][key] = value
+        config_map.write
+
+      end
+
+
+      # Given the configuration key name and the context name, get the
+      # corresponding key value from the configuration file whose path
+      # is acquired using the {self#get_filepath} method.
+      #
+      # @param key_name [String] the key whose value is to be retrieved
+      #
+      # @return [String] the value configured for the parameter key
+      #
+      # @raise ArgumentError for any one of a long list of reasons that
+      #     cause the key value to not be retrieved. This can range from
+      #     non-existent directories and files, non readable files, incorrect
+      #     configurations right down to missing keys or even missing values.
+      def self.read section_name, key_name
+
+        the_data = get_inifile_data
+
+        section_exists = the_data.has_section?( section_name )
+        raise ArgumentError.new "Section [#{section_name}] not found in INI file => #{the_data.to_s}" unless section_exists
+
+        key_exists = the_data[ section_name ].has_key?( key_name )
+        raise ArgumentError.new "Key [#{key_name}] not found in section [#{section_name}] => #{the_data.to_s}" unless key_exists
+
+        rawvalue = the_data[section_name][key_name]
+        raise ArgumentError.new "Empty value 4 key [#{section_name}][#{key_name}] => #{the_data.to_s}" if rawvalue.empty?
+
+        keyvalue = rawvalue.chomp.strip
+        raise ArgumentError.new "Whitespace value 4 key [#{section_name}][#{key_name}] => #{the_data.to_s}" if keyvalue.empty?
+
+        return keyvalue
+
+      end
+
+
+      # Return true if the settings configuration file contains the specified
+      # key (in the 2nd parameter) within the section name specified in the
+      # first parameter.
+      #
+      # This method does not check the contents (value) of the key. Even if it
+      # is an empty string, this method returns true so long as the section
+      # exists and the key exists within that.
+      #
+      # @param section_name [String] the name of the section to search under
+      # @param key_name [String] the name of the key to test for existence
+      # @return [Boolean]
+      #    return true if both the section and the key exists within it.
+      #    return false if the section specified does not exist.
+      #
+      # raise [ArgumentError]
+      #    if the INI file does not exist
+      def self.contains_key? section_name, key_name
+
+        the_data = get_inifile_data
+
+        return false unless the_data.has_section?( section_name )
+        return the_data[ section_name ].has_key?( key_name )
+
+      end
+
+
+      private
+
+
+      def self.get_inifile_data
+
+        the_file = Collateral.instance.config_file
+        raise ArgumentError.new "No configuration file found => [ #{the_file} ]" unless File.exists? the_file
+
+        the_text = File.read the_file
+        raise ArgumentError.new "Configuration file is empty => [ #{the_file} ]" if the_text.empty?
+
+        return IniFile.load the_file
+
+      end
+
+    end
+
+  end
+
+
+end

data/lib/modules/storage/coldstore.rb

@@ -0,0 +1,186 @@
+#!/usr/bin/ruby
+# coding: utf-8
+
+module OpenSecret
+
+  module Store
+
+    # Cold storage can sync repositories with a <b>bias during conflicts</b>
+    # either to the <em>remote repository</em> <b>when pulling</b>, and then
+    # conversely to the <em>local reposiory</em> <b>when pushing</b>.
+    #
+    # In between the sync operations a ColdStore can create, read, update and
+    # delete to and from the local mirror.
+    #
+    # == ColdStore | Use Cases
+    #
+    # Any <b>self-respecting coldstore</b> must, after initialization, provide
+    # some basic (and mandatory) behaviour.
+    #
+    # These include
+    #
+    # - <b>read</b> - reading text from a (possibly unavailable) frozen path
+    # - <b>write</b> - writing text (effectively freezing it) to a path
+    # - <b>pull</b> - sync with a <b>collision bias</b> that favours the remote mirror 
+    # - <b>push</b> - sync with a <b>collision bias</b> that favours the local mirror
+    #
+    # <b>Cold Storage</b> is borrowed from BitCoin and represents offline storage
+    # for keys and crypts. opensecret separates keys and crypts so that you can
+    # transfer and share secrets by moving keys (not the crypts).
+    #
+    # == Houses and Gold Bullion
+    #
+    # You don't carry houses or gold bullion around to rent, share or transfer
+    # their ownership.
+    #
+    # You copy keys to rent secrets and when the tenure is up (or you change your
+    # mind) you revoke access with a metaphorical lock change.
+    #
+    # opensecret embodies concepts like an owner who rents as opposed to a change
+    # in ownership.
+    #
+    # == trade secrets | commoditizing secrets
+    #
+    # opensecret is a conduit through which secrets can be bought and sold.
+    #
+    # It commoditizes secrets so that they can be owned, traded, leased and
+    # auctioned. Options to acquire or relinquish them at set prices can easily
+    # be taken out.
+    class ColdStore
+
+      # @param base_path [String]
+      #    path to the store's (mirror) base directory.
+      #    If the denoted directory does not exist an attempt will be made to
+      #    create it. If a file exists at this path an error will be thrown.
+      #
+      # @param domain [String]
+      #    the domain is an identifier (and namespace) denoting which opensecret
+      #    "account" is being accessed. opensecret allows the creation and use of
+      #    multiple domains.
+      def initialize local_path
+
+        @store_path = local_path
+        FileUtils.mkdir_p @store_path
+
+      end
+
+
+      # Read the file frozen (in this store mirror) at this path and
+      # return its contents.
+      #
+      # Coldstores are usually frozen offline (offmachine) so for this
+      # to work the {ColdStore.pull} behaviour must have executed to
+      # create a local store mirror. This method reads from that mirror.
+      #
+      # @param from_path [String]
+      #    read the file frozen at this path and return its contents
+      #    so that the defreeze process can begin.
+      #
+      #    This path is relative to the base of the store defined in
+      #    the constructor.
+      #
+      # @return [String]
+      #    return the text frozen in a file at the denoted local path
+      #
+      #    nil is reurned if no file can be found in the local mirror
+      #    at the configured path
+      #
+      # @raise [RuntimeError]
+      #    unless the path exists in this coldstore and that path is
+      #    a directory (as opposed to a file).
+      #
+      # @raise [ArgumentError]
+      #    if more than one file match is made at the path specified.
+      def read from_path
+
+        frozen_filepath = File.join @store_path, from_path
+        frozen_dir_path = File.dirname(frozen_filepath)
+
+        log.info(x) { "Coldstore will search in folder [#{frozen_dir_path.hr_path}]" }
+
+        exists_msg = "Directory #{frozen_dir_path} does not exist in store."
+        is_dir_msg = "Path #{frozen_dir_path} should be a directory (not a file)."
+        raise RuntimeError, exists_msg unless File.exists? frozen_dir_path
+        raise RuntimeError, is_dir_msg unless File.directory? frozen_dir_path
+
+        full_filepath = ""
+        file_matched = false
+
+        Dir.glob("#{frozen_dir_path}/**/*.os.txt").each do |matched_path|
+
+          log.info(x) { "Coldstore search with [#{from_path}] has matched [#{matched_path.hr_path}]" }
+          log.info(x) { "Ignore directory at [#{matched_path.hr_path}]." } if File.directory? matched_path
+          next if File.directory? matched_path
+
+          two_match_msg = "More than one file matched. The second is #{matched_path}."
+          raise ArgumentError, two_match_msg if file_matched
+          file_matched = true
+
+          full_filepath = matched_path
+
+        end
+
+        no_file_msg = "Coldstore could not find path [#{from_path}] from [#{@store_path}]."
+        raise RuntimeError, no_file_msg unless file_matched
+
+        log.info(x) { "Coldstore matched exactly one envelope at [#{full_filepath.hr_path}]." }
+        return File.read full_filepath
+
+      end
+
+
+      # Write (freeze) the text into a file at the denoted path. The
+      # folder path will be created if need be.
+      #
+      # Coldstores are usually frozen offline (offmachine) so after
+      # this method completes the {ColdStore.push} behaviour must be
+      # executed to synchronize the local coldstore freezer with the
+      # remote mirror.
+      #
+      # @param this_text [String]
+      #    this is the text that needs to be frozen into the local and
+      #    subsequently the remote coldstore freezer.
+      #
+      # @param to_path [String]
+      #    write the text (effectively freezing it) into the file at
+      #    this path. An attempt will be made to put down the necessary
+      #    directory structure.
+      #
+      #    This path is relative to the base of the store defined in
+      #    the constructor.
+      def write this_text, to_path
+
+        freeze_filepath = File.join @store_path, to_path
+
+        log.info(x) { "ColdStore freezing #{this_text.length} characters of worthless text."}
+        log.info(x) { "ColdStore freeze file path => #{freeze_filepath.hr_path}"}
+
+        FileUtils.mkdir_p(File.dirname(freeze_filepath))
+        File.write freeze_filepath, this_text
+
+      end
+
+
+      private
+
+      # @todo - write sync (with a local bias during conflicts)
+      #     The open up to the public (published) api.
+      def push
+
+
+      end
+
+      # @todo - write sync (with a rmote bias during conflicts)
+      #     The open up to the public (published) api.
+      def pull
+
+      end
+
+
+    end
+
+
+  end
+
+
+end