opensecret 0.0.988 → 0.0.9925

data/lib/modules/mappers/collateral.rb

@@ -1,282 +0,0 @@
-#!/usr/bin/ruby
-# coding: utf-8
-
-module OpenSecret
-
-  module Mapper
-
-    # <b>Collateral</b> fingers (locates/points to) resource paths and objects that
-    # are accessible on the filesystem of either the workstation or its associated
-    # (external) drives.
-    #
-    # Its ubiquitous language distinguishes four (4) base paths for the
-    #
-    # - <b>frontend store</b> - usually a path to USB connected devices like phones
-    # - <b>mid-end store</b> - location is on workstation off the user's home directory 
-    # - <b>(local) backend store</b> - departure lounge located off the home directory 
-    # - <b>(remote) backend store</b> - arrival gate on S3, Google Drive or SSH drive
-    class Collateral
-      include Singleton
-
-
-      # After constructing the <b>{Collateral}</b> object the building
-      # blocks that all paths are fabricated from must be injected.
-      attr_accessor :domain_name, :frontend_path
-
-      ENV_OPS_KEY_NAME = "OPS_KEY"
-
-      # The context name is used in various places (filesystem especially)
-      # in order to disambiguate the question of which software creates, reads,
-      # and updates the containing collateral.
-      CONTEXT_NAME = "opensecret.io"
-
-      # The name of the frontend directory in which encrypted
-      # session envelopes are stored in a tree-like structure.
-      SESSION_ENVELOPES_NAME = "session.envelopes"
-
-      # The name of the frontend directory (library) in which crypt
-      # keys are stored in a tree-like structure.
-      KEY_STORE_LIBRARY_NAME = "keystore.library"
-
-      # The name of the backend directory (library) in which crypt
-      # material is stored in a tree-like structure.
-      CRYPT_STORE_LIBRARY_NAME = "crypt.library"
-
-      # The name of the frontend directory (library) in which the
-      # index files are harboured in a flat structure.
-      CONFIG_LIBRARY_NAME = "ops.configuration"
-
-      # The name of the frontend directory in which the master keys
-      # are (or will be) stored.
-      MASTER_KEYS_DIR_NAME = "known.master.keys"
-
-      # The public key filename will end with this constant suffix.
-      PUBLIC_KEY_NAME_SUFFIX = "public.key.txt"
-
-      # The private key filename will end with this constant suffix.
-      PRIVATE_KEY_NAME_SUFFIX = "private.key.txt"
-
-
-      # Write the public key text into a file within the master keys
-      # folder. The directory path is created if necessary.
-      #
-      # @param public_key_text [String]
-      #    the text totality that makes up the domain's public key
-      def write_public_key public_key_text
-        FileUtils.mkdir_p master_keys_path
-        File.write public_key_path, public_key_text
-      end
-
-
-      # Read the public key text from a file within the master keys
-      # folder. This method will fail if the public key isn't found.
-      #
-      # @return [String]
-      #    return the text totality making up the domain's public key
-      def read_public_key
-        return File.read( public_key_path )
-      end
-
-
-      # Write the private key text into a file within the master keys
-      # folder. The directory path is created if necessary.
-      #
-      # @param private_key_text [String]
-      #    the text totality that makes up the domain's private key
-      def write_private_key private_key_text
-        FileUtils.mkdir_p master_keys_path
-        File.write private_key_path, private_key_text
-      end
-
-
-      # Read the private key text from a file within the master keys
-      # folder. This method will fail if the private key isn't found.
-      #
-      # @return [String]
-      #    return the text totality making up the domain's private key
-      def read_private_key
-        return File.read( private_key_path )
-      end
-
-
-      # Return true if the private key exists within a file under the
-      # auspices of the current domain.
-      #
-      # @param private_key_text [String]
-      #    the text totality that makes up the domain's private key
-      def private_key_exists?
-        return File.file? private_key_path
-      end
-
-
-      # The path to the initial configuration file below the user's home
-      # directory. The directory name the configuration file sits in is
-      # a dot prefixed context name derived from the value inside the
-      # {Mapper::Collateral::CONTEXT_NAME} constant.
-      #
-      #     ~/.<<context-name>>/<<context-name>>-configuration.ini
-      #
-      # You can see the filename too is derived from the context with a
-      # trailing string ending in <b>.ini</b>.
-      #
-      # @return [String] full path to the context configuration file
-      def config_file
-        return File.join config_directory, "#{CONTEXT_NAME}.configuration.ini"
-      end
-
-
-      # This method returns the absolute path to the directory that the
-      # configuration file sits in. It is basically just the dot prefixed
-      # context name (the {Mapper::Collateral::CONTEXT_NAME} constant).
-      #
-      #     ~/.<<context-name>>
-      #
-      # @return [String] path to directory holding context configuration file
-      def config_directory
-        return File.join home_directory, ".#{CONTEXT_NAME}"
-      end
-
-
-      # The configuration file governing the files and behaviour
-      # of the specified domain.
-      def domain_config_file
-        return File.join config_library_path, "ops.domain.config.ini"
-      end
-
-      # The path within the frontend directory in which the
-      # data index and the index configuration files are stored.
-      # @return [String]
-      #    path to the base frontend index library directory
-      def config_library_path
-        return File.join frontend_base, CONFIG_LIBRARY_NAME
-      end
-
-
-
-
-
-      # The path to the session's folder that will be situated
-      # within the frontend drive location so that any session
-      # materials can be carried away with the external drive.
-      def session_folder
-        return File.join frontend_base, SESSION_ENVELOPES_NAME
-      end
-
-
-      # The path to the session's index file is an amalgam of the
-      # session folder {session_folder} and a <b>lowercased</b>
-      # session id stamp that should be the first n characters of
-      # the session id.
-      #
-      # @example
-      #
-      #    session id stamp = M4Tywsv3BgNJQSn2MrA3484T
-      #    session filename = session.m4tywsv3bgnjqsn2mra3484t.txt
-      #
-      # @param id_stamp [String]
-      #
-      #    the first n characters of the session id that will
-      #    be lowercased and sandwiched between the words
-      #    <tt>session.</tt> and <tt>.txt</tt>
-      #
-      # @return [String]
-      #    path to the session file that sits inside the frontend
-      #    drive in folder called <b>session.envelopes</b>
-      def session_index_file id_stamp
-        return File.join( session_folder, "session.#{id_stamp.downcase}.txt" )
-      end
-
-
-
-
-      # The path within the frontend directory in which the encrypted
-      # keystore envelopes live in a tree-like structure.
-      # @return [String]
-      #    path to the base frontend keystore data directory
-      def frontend_keystore_path
-        return File.join frontend_base, KEY_STORE_LIBRARY_NAME
-      end
-
-
-      # The path within the backend directory in which the encrypted
-      # crypt envelopes live in a tree-like structure.
-      # @return [String]
-      #    path to the backend crypt store data directory
-      def backend_cryptstore_path
-        return File.join storage_url, "#{@domain_name}.#{CRYPT_STORE_LIBRARY_NAME}"
-      end
-
-
-      # On non-windows systems the home directory is defined
-      # perfectly by Ruby's Dir object.
-      #
-      # On Windows we sometimes get /AppData/Roaming appended
-      # onto the actual home directory. In these cases this
-      # method removes it.
-      #
-      # @return [String] the path to the machine user's home directory
-      def home_directory
-
-        return Dir.home unless Gem.win_platform?
-
-        extraneous_path = "/AppData/Roaming"
-        if Dir.home.end_with? extraneous_path then
-          return Dir.home.gsub( extraneous_path, "" )
-        end
-
-        return Dir.home
-
-      end
-
-
-      # Log the configuration file to two places
-      #
-      # - the console
-      # - the log file below the user's home directory.
-      #
-      # The logging is done at the INFO level.
-      def log_config
-
-        log.info(x) { File.read(config_file).log_lines }
-        puts ""
-        puts File.read(config_file)
-        puts ""
-
-      end
-
-
-      private
-
-
-      def frontend_base
-        return File.join @frontend_path, "ops.#{@domain_name}"
-      end
-
-
-      def storage_url
-        return File.join config_directory, "#{CONTEXT_NAME}.storage"
-      end
-
-
-      def master_keys_path
-        return File.join frontend_base, MASTER_KEYS_DIR_NAME
-      end
-
-
-      def public_key_path
-        return File.join master_keys_path, "#{@domain_name}.#{PUBLIC_KEY_NAME_SUFFIX}"
-      end
-
-
-      def private_key_path
-        return File.join master_keys_path, "#{@domain_name}.#{PRIVATE_KEY_NAME_SUFFIX}"
-      end
-
-
-    end
-
-
-  end
-
-
-end

data/lib/modules/mappers/envelope.rb

@@ -1,127 +0,0 @@
-#!/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

@@ -1,170 +0,0 @@
-#!/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