safedb 0.4.1002 → 0.5.1001

data/lib/controller/admin/refresh.rb

@@ -0,0 +1,55 @@
+#!/usr/bin/ruby
+	
+module SafeDb
+
+  # The <b>refresh use case</b> commits any changes made to the safe book into
+  # master. This is straightforward if the master's state has not been forwarded
+  # by a ckeckin from another (shell) branch.
+  #
+  # == master and branch not in sync
+  #
+  # Commits cannot occur when the master's state has been moved forward by another
+  # branch commit. In these cases one needs to use the below sequence.
+  #
+  # - <tt>safe diff --refresh</tt> | diff will list what will the state changes during refresh
+  # - <tt>safe refresh</tt> | the actual merge down (from master to branch) that never deletes keys
+  # - <tt>safe commit</tt> | now the commit can proceed as the branch is in line with the master
+  #
+  # == refresh | merge up mechanics
+  #
+  # The mechanics of a simple in-sync refresh is to
+  #
+  # - sync the master crypts to exactly mimic the branch crypts
+  # - tell master the content id of the book index file
+  # - tell master what the current random iv (initialization vector) is
+  # - create a new commit ID and set it on both master and branch
+  # - set the master's last updated date and time
+  #
+  class Refresh < Controller
+
+
+    # The <b>refresh use case</b> commits any changes made to the safe book into
+    # master. This is straightforward if the master's state has not been forwarded
+    # by a ckeckin from another (shell) branch.
+    def execute
+
+      puts ""
+      puts " == Birth Day := #{@book.init_time()}\n"
+      puts " == Book Name := #{@book.book_name()} [#{@book.book_id}]\n"
+      puts " == Book Mark := #{@book.get_open_chapter_name()}/#{@book.get_open_verse_name()}\n" if @book.is_opened?()
+      puts ""
+
+      StateMigrate.refresh( @book )
+      StateMigrate.copy_commit_id_to_branch( @book )
+
+      puts "Refresh from master to branch was successful.\n"
+      puts ""
+
+
+    end
+
+
+  end
+
+
+end

data/lib/controller/admin/token.rb

@@ -6,7 +6,7 @@ module SafeDb
   # to the workstation and shell environment. See the root README.md on how
   # to export it and create a simple command alias for it in the ~/.bash_aliases
   # script which is executed when the shell starts.
-  class Token < UseCase
+  class Token < Controller
 
 
     def execute

data/lib/controller/admin/use.rb

@@ -16,7 +16,7 @@ module SafeDb
   # Error - if the domain name is not listed in the configuration file.
   # Error - if the (dictionary) path to the domain's base does not exist
   #
-  class Use < UseCase
+  class Use < Controller
 
     attr_writer :domain_name
 

data/lib/controller/admin/view.rb

@@ -9,21 +9,19 @@ module SafeDb
   # Goto with the number effectively shortcuts the open pinpointer.
   # Show prints out the verse lines at the opened path but masks any secrets.
   # Tell also prints out the verse lines but unabashedly displays secrets.
-  class View < UseCase
+  class View < Controller
 
     def execute
 
-      book = Book.new()
-
       puts ""
-      puts " == Birth Day := #{book.init_time()}\n"
-      puts " == Book Name := #{book.book_name()} [#{book.book_id}]\n"
-      puts " == Book Mark := #{book.get_open_chapter_name()}/#{book.get_open_verse_name()}\n" if book.is_opened?()
+      puts " == Birth Day := #{@book.init_time()}\n"
+      puts " == Book Name := #{@book.book_name()} [#{@book.book_id}]\n"
+      puts " == Book Mark := #{@book.get_open_chapter_name()}/#{@book.get_open_verse_name()}\n" if @book.is_opened?()
       puts ""
 
       verse_count = 0
       chapter_index = 0
-      book.branch_chapter_keys().each_pair do | chapter_name, chapter_keys |
+      @book.branch_chapter_keys().each_pair do | chapter_name, chapter_keys |
 
         chapter_index += 1
         verse_index = 0
@@ -32,9 +30,9 @@ module SafeDb
 
           verse_index += 1
           verse_count += 1
-          is_open = book.is_open?( chapter_name, verse_name )
+          is_open = @book.is_open?( chapter_name, verse_name )
           isnt_first = verse_count != 1
-          isnt_last = ( chapter_index != book.branch_chapter_keys().length() ) || ( verse_index != chapter_data.length() )
+          isnt_last = ( chapter_index != @book.branch_chapter_keys().length() ) || ( verse_index != chapter_data.length() )
           mark_open = is_open ? "<< " : ""
           mark_close = is_open ? " >>" : ""
           fixdint = format( "%02d", verse_count )
@@ -47,7 +45,7 @@ module SafeDb
       end
 
       puts ""
-      puts " == There are #{book.branch_chapter_keys().length()} chapters and #{verse_count} verses."
+      puts " == There are #{@book.branch_chapter_keys().length()} chapters and #{verse_count} verses."
       puts ""
 
       return

data/lib/controller/api/docker/docker.rb

@@ -7,7 +7,7 @@ module SafeDb
     #     safe docker login
     #     safe docker logout
 
-    class Docker < UseCase
+    class Docker < Controller
 
         # The command which currently must be login, logout or
         # an empty string.

data/lib/controller/api/jenkins/jenkins.rb

@@ -11,7 +11,7 @@ module SafeDb
     #
     #     safe jenkins post <<[ aws | docker | git ]>> <<jenkins-host-url>>
 
-    class Jenkins < UseCase
+    class Jenkins < Controller
 
         # The three instance variables provided through the command line like
         # for example  $ safe jenkins post aws http://localhost:8080

data/lib/controller/api/terraform/terraform.rb

@@ -14,7 +14,7 @@ module SafeDb
   # ubiquitous safe open command.
   #
   #     safe open <<chapter>> <<verse>>
-  class Terraform < UseCase
+  class Terraform < QueryVerse
 
     attr_writer :command
 
@@ -22,34 +22,7 @@ module SafeDb
     # and convert for consumption into module input variables.
     TERRAFORM_EVAR_PREFIX = "TF_VAR_"
 
-    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 = DataStore.from_json( Lock.content_unlock( master_db[ chapter_id ] ) )
-
-      # Now read the three AWS IAM credentials @access.key, @secret.key and region.key
-      # into the 3 environment variables terraform expects to find.
+    def query_verse()
 
       # ############## | ############################################################
       # @todo refactor | ############################################################
@@ -82,12 +55,11 @@ module SafeDb
       puts "@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@"
       puts ""
 
-      ENV[ "AWS_ACCESS_KEY_ID"     ] = chapter_data[ verse_id ][ "@access.key" ]
-      ENV[ "AWS_SECRET_ACCESS_KEY" ] = chapter_data[ verse_id ][ "@secret.key" ]
-      ENV[ "AWS_DEFAULT_REGION"    ] = chapter_data[ verse_id ][ "region.key"  ]
+      ENV[ "AWS_ACCESS_KEY_ID"     ] = @verse[ "@access.key" ]
+      ENV[ "AWS_SECRET_ACCESS_KEY" ] = @verse[ "@secret.key" ]
+      ENV[ "AWS_DEFAULT_REGION"    ] = @verse[ "region.key"  ]
 
-      mini_dictionary = chapter_data[ verse_id ]
-      mini_dictionary.each do | key_str, value_object |
+      @verse.each do | key_str, value_object |
 
         is_env_var = key_str.start_with?( ENV_VAR_PREFIX_A ) || key_str.start_with?( ENV_VAR_PREFIX_B )
         next unless is_env_var
@@ -97,6 +69,7 @@ module SafeDb
         env_var_keyname = TERRAFORM_EVAR_PREFIX + env_var_name
         ENV[ env_var_keyname ] = value_object
         puts "Environment variable #{env_var_keyname} has been set."
+        log.info(x) { "Setting terraform environment variable => #{env_var_keyname}" }
 
       end
 

data/lib/controller/api/vpn/vpn.rb

@@ -7,7 +7,7 @@ module SafeDb
   #
   #     safe vpn up
   #     safe vpn down
-  class Vpn < UseCase
+  class Vpn < Controller
 
     attr_writer :command
 

data/lib/controller/{usecase.rb → controller.rb}

@@ -10,7 +10,7 @@ module SafeDb
   #
   # == Common Use Case Behaviour
   #
-  # This {SafeDb::UseCase} use case is designed to be extended and does preparatory
+  # This {SafeDb::Controller} use case is designed to be extended and does preparatory
   # work to create favourable and useful conditions to make use cases readable,
   # less repetitive, simpler and concise.
   #
@@ -26,7 +26,7 @@ module SafeDb
   # - {stash} put directive key/value pair in default section
   # - {read} read the value at key_name from the parameter section
   # - {write} put directive key/value pair in parameter section
-  class UseCase
+  class Controller
 
     # All controllers are initialized here meaning that there will be automatic
     # execution of very frequently used setup behaviour. This includes
@@ -37,12 +37,21 @@ module SafeDb
       class_name = self.class.name.split(":").last.downcase
       is_no_token_uc = [ "token", "init", "id" ].include? class_name
       return if is_no_token_uc
-
       exit(100) unless ops_key_exists?
 
-      # Chop off all fact work for now. May need to resurrect for VPN functionality.
+      is_login_uc = class_name.eql?( "login" )
+      return if is_login_uc
+
+      not_logged_in = StateInspect.not_logged_in?()
+      puts TextChunk.not_logged_in_message() if not_logged_in
+      exit(100) if not_logged_in
+
+      @book = Book.new()
       return
 
+=begin
+      Fact Functionality
+      ======================
       fact_filepath = File.sister_filepath( self, "ini", :execute )
       log.info(x) { "Search location for INI factfile is [#{fact_filepath}]" }
       return unless File.exists?( fact_filepath )
@@ -51,6 +60,7 @@ module SafeDb
       add_secret_facts @facts
       @facts.assimilate_ini_file( fact_filepath )
       @dictionary = @facts.f[ @facts.to_symbol( class_name ) ]
+=end
 
     end
 
@@ -59,10 +69,7 @@ module SafeDb
     # data structures and indices.
     def read_verse()
 
-# @todo => consider doing the book index opening with initializer UNLESS token/admin use case
-
-      @book = Book.new()
-      return if @book.unopened_chapter_verse()
+      exit(100) if @book.unopened_chapter_verse?()
       @verse = @book.get_open_verse_data()
 
     end

data/lib/controller/edit/editverse.rb

@@ -2,7 +2,7 @@
 	
 module SafeDb
 
-  # Any {UseCase} class wishing to edit a safe verse can make use of the functionality
+  # Any {Controller} class wishing to edit a safe verse can make use of the functionality
   # in this parent by exposing an edit_verse() method.
   #
   # Classes extending this class will have access to
@@ -16,7 +16,7 @@ module SafeDb
   #
   # After the edit method completes the amended chapter data structure will be encrypted
   # and streamed to a ciphertext file.
-  class EditVerse < UseCase
+  class EditVerse < Controller
 
     # This parental behaviour sets up common ubiquitous chapter and verse data structures
     # and indices. It then calls the child's query_verse() behaviour and once that is complete

data/lib/controller/id.rb

@@ -3,7 +3,7 @@
 module SafeDb
 
 
-  class Id < UseCase
+  class Id < Controller
 
 
     def execute

data/lib/controller/query/copy.rb

@@ -0,0 +1,127 @@
+#!/usr/bin/ruby
+	
+module SafeDb
+
+  # The copy use case copies one or more chapters, one or more verses and
+  # one or more lines to the clipboard so Ctrl-v can be used outside the
+  # safe to paste data in (like complex passwords).
+  #
+  # Use {Drag} and {Drop} to move data between books, chapters, verses and
+  # lines.
+  #
+  # Visit documentation at https://www.safedb.net/docs/copy-paste
+  class Copy < QueryVerse
+
+    # this entity can point to a book, chapter, verse or line. If no
+    # parameter entity is provided, the --all switch must be present
+    # to avoid an error message.
+    attr_writer :entity
+
+    # The copy use case copies one or more chapters, one or more verses and
+    # one or more lines to the clipboard so Ctrl-v can be used outside the
+    # safe to paste data in (like complex passwords).
+    def query_verse()
+
+      print @verse[ @key_name ]
+
+=begin
+
+From xclip man page
+
+EXAMPLES
+       I hate man pages without examples!
+
+       uptime | xclip
+
+       Put your uptime in the X selection. Then middle click in an X application to paste.
+
+       xclip -loops 10 -verbose /etc/motd
+
+       Exit after /etc/motd (message of the day) has been pasted 10 times. Show how many  selection  requests  (pastes)
+       have been processed.
+
+       xclip -o > helloworld.c
+
+       Put the contents of the selection into a file.
+
+       xclip -t text/html index.html
+
+       Middle click in an X application supporting HTML to paste the contents of the given file as HTML.
+
+
+
+78apollo@unity:~$ xclip -o
+Constant Summaryapollo@unity:~$ 
+apollo@unity:~$ xclip -o; echo
+Constant Summary
+apollo@unity:~$ xclip -o; echo
+Module: Clipboard::File
+apollo@unity:~$ xclip -o; echo
+character of the selection specified
+apollo@unity:~$ xclip -o; echo
+long as they remain unambiguous
+apollo@unity:~$ xclip -o; echo
+long as they remain unambiguous
+apollo@unity:~$ xclip -o; echo
+long as they remain unambiguous
+apollo@unity:~$ xclip -i ''
+xclip: : No such file or directory
+apollo@unity:~$ xclip -o; echo
+long as they remain unambiguous
+apollo@unity:~$ xclip ''
+xclip: : No such file or directory
+apollo@unity:~$ xclip -o; echo
+long as they remain unambiguous
+apollo@unity:~$ xclip -t ''
+q
+adsf
+
+
+apollo@unity:~$ 
+apollo@unity:~$ 
+apollo@unity:~$ uptime | xclip
+apollo@unity:~$ xclip -o; echo
+ 00:34:46 up  5:10,  1 user,  load average: 0.47, 0.52, 0.35
+
+apollo@unity:~$ uptime
+ 00:35:05 up  5:11,  1 user,  load average: 0.34, 0.48, 0.34
+apollo@unity:~$ uptime | xclip
+apollo@unity:~$ xclip -o
+ 00:35:29 up  5:11,  1 user,  load average: 0.22, 0.44, 0.33
+apollo@unity:~$ xclip -o
+ 00:35:29 up  5:11,  1 user,  load average: 0.22, 0.44, 0.33
+apollo@unity:~$ xclip -o
+ 00:35:29 up  5:11,  1 user,  load average: 0.22, 0.44, 0.33
+apollo@unity:~$ xclip -o
+Error: target STRING not available
+apollo@unity:~$ xclip -o
+Error: target STRING not available
+apollo@unity:~$ xclip -o
+Error: target STRING not available
+apollo@unity:~$ xclip -o
+       apollo@unity:~$ 
+apollo@unity:~$ xclip -o; echo
+       
+apollo@unity:~$ xclip -o; echo
+instead  of  -display.  However,  -v couldn't be used because it is ambiguous (it could be short for -verbose or
+apollo@unity:~$ xclip -o; echo
+0345 072 5555
+apollo@unity:~$ echo "safe deleted clipboard contents" | xclip
+apollo@unity:~$ xclip -o; echo
+safe deleted clipboard contents
+
+apollo@unity:~$ xclip -o; echo
+ (traditionally with the middle mouse button
+apollo@unity:~$ xclip -o; echo
+safedb.yijx-r7zr.19093.1515.01.676152709.json
+
+=end
+
+
+    end
+
+
+  end
+
+
+end

data/lib/controller/query/queryverse.rb

@@ -2,7 +2,7 @@
 	
 module SafeDb
 
-  # Any {UseCase} class wishing to query a safe verse can make use of the functionality
+  # Any {Controller} class wishing to query a safe verse can make use of the functionality
   # in this parent by exposing an query_verse() method.
   #
   # Classes extending this class will have access to
@@ -16,7 +16,7 @@ module SafeDb
   #
   # The query_verse() method is not succeeded by any behaviour in the parent. Chilc classes
   # must do their own output management.
-  class QueryVerse < UseCase
+  class QueryVerse < Controller
 
     # This parental behaviour sets up common ubiquitous chapter and verse data structures
     # and indices.

data/lib/controller/requirer.rb

@@ -86,7 +86,7 @@ module SafeDb
     def self.gems( gem_filepath )
 
       require_relative "../version"
-      require_relative "../controller/usecase"
+      require_relative "../controller/controller"
       require_relative "../controller/admin/access"
       require_relative "../controller/edit/editverse"
       require_relative "../controller/query/queryverse"

data/lib/controller/set.rb

@@ -13,7 +13,7 @@ module SafeDb
   # The configuration directive will either be created or overwriten within the
   # book's configuration store.
   #
-  class Set < UseCase
+  class Set < Controller
 
     attr_writer :directive_name, :directive_value
 

data/lib/controller/verse.rb

@@ -2,7 +2,7 @@
 	
 module SafeDb
 
-  class Verse < UseCase
+  class Verse < Controller
 
     def execute
 

data/lib/controller/visit/visit.rb

@@ -2,7 +2,7 @@
 	
 module SafeDb
 
-  class Visit < UseCase
+  class Visit < Controller
 
     def execute
 

data/lib/manual/copy-paste.md

@@ -0,0 +1,13 @@
+
+# safe copy | safe paste
+
+<tt>Copy and paste data to and from the **clipboard**</tt>.
+
+## pre-condition - install xclip
+
+Linux uses xclip to manage the clipboard so we need to install it before using safe's copy and paste functions.
+
+```
+sudo apt install xclip
+```
+

data/lib/manual/drag-drop.md

@@ -0,0 +1,77 @@
+
+# safe drag | safe drop
+
+<tt>safe drag</tt> picks up data from one place and <tt>safe drop</tt> places that data elsewhere.
+
+## On the same level
+
+You can only drop data when you are at the same level as when you picked it up (although not necessarily in the same book).
+
+### Verse Level
+
+This example drags a key/value pair from one verse to another in the same book.
+
+```
+safe open <<chapter.x>> <<verse.x>>
+safe drag <<line>>
+safe open <<chapter.y>> <<verse.y>>
+safe drop
+```
+
+## Different Books
+
+You can use drag and drop to take data from one book and drop it into another. The rules about being on the same level still apply.
+
+### Drag line to another book
+
+Samantha is not just a cousin, she was in the same class in 2010. I want to copy her phone number from my family book to my friends book.
+
+```
+safe login friends
+safe login family
+safe open cousins samantha
+safe drag phone.number
+safe use friends
+safe open class-of-2010 samantha
+safe drop
+safe logout --all
+```
+
+If the phone number existed it will be overwritten. If not it will be created.
+
+## Dragging more than one
+
+The <tt>--all</tt> switch can be used to drag a collective.
+
+You can either drag a single line, verse or chapter, or you can drag
+
+- every line in a verse
+- every verse in a chapter
+- every chapter in a book
+
+## All siblings are invited to the wedding
+
+This example copies all (verse) siblings to the wedding-guests chapter.
+
+```
+safe open siblings
+safe drag --all
+safe open wedding-guests
+safe drop
+```
+
+## Renaming when you drop
+
+What if you want to rename the line, verse or chapter being dragged and dropped. You can! As long as you are not dragging multiples (using --all).
+
+You can use the data in one verse as a starting point for another.
+
+```
+safe open contacts
+safe drag peter
+safe drop paul
+```
+
+The paul verse is created with the same lines as peter has.
+
+If a paul verse already existed the data within it is merged with priority (on conflicts) given to the (incoming) data being dropped.

data/lib/manual/login-logout.md

@@ -0,0 +1,46 @@
+
+# safe login | safe logout
+
+You can login to one or more books at a shell command line.
+
+```
+safe login <<book>>
+safe login <<book>> --password=<<password>>
+safe login <<book>> -p <<password>>
+safe login <<book>> --clip
+safe login <<book>> -c
+```
+
+## Password Conventions
+
+The safe will **search for passwords** in an orderly manner as per the conventions below.
+
+|  #  | Location | Description (and Important Points) | Example |
+|:---:|:---------- |:------------------------------ |:----------------------- |
+|  1  | Command Line | Leave **a space** before the <tt>safe init</tt> or <tt>safe login</tt> commands to avoid the command being written into `.bash_history` - do not use if AN Other can run `ps` on your machine. | <tt>safe login contacts --password=secret123</tt> |
+|  2  | Environment Variable | First export the password into an environment variable called SAFE_BOOK_PASSWORD and then issue a login. Don't forget to **leave a space** before the <tt>export</tt> command to avoid being logged into .bash_history | <tt>safe login contacts</tt> |
+|  3  | Environment Variables | If you want to login to multiple books in the same shell (or within scripts) you can export the environment variable with the book name appended. | **export SAFE_BOOK_PASSWORD_contacts=secret123** and **export SAFE_BOOK_PASSWORD_accounts=p455w0rd** |
+|  4  | **clip board** | A <tt>--clip</tt> switch **(or -c)** appended to the init and/or login commands tells safe to read the password from the clip board and then immediately delete the clip board contents. | safe login contacts --clip |
+|  5  | Prompt | The ubiquitous password prompt will be issued if none of the above options are viable. | safe login contacts |
+
+<!--
+|  3  | xxx | xxxx | xxx |
+-->
+
+### login pre-conditions
+
+To login into a safe book you must
+
+- have installed safe and set the token (env var)
+- (either) have initialized the book using safe init
+- (or) have pulled in a safe database using safe clone
+- know the book's name and password (from safe init)
+
+## Related Commands
+
+| safe command | parameters | observable value delivered                             | relationships           |
+|:------------ |:---------- |:------------------------------------------------------ |:----------------------- |
+| safe init    | book name  | creates the book for managing credentials              | book must exist first   |
+| safe use     | book name  | switch books after same shell logins to multiple books | login must have occured |
+| safe logout  | (none)     | deletes session information preventing further usage   | can logout after login  |
+

data/lib/model/README.md

@@ -7,8 +7,8 @@ The need to cycle content occurs during
 
 - <tt>initialization</tt> - a new master state box is created
 - <tt>login</tt> - branch state is created that mirrors master
-- <tt>checkin</tt> - transfers state from branch to master
-- <tt>checkout</tt> - transfers state from master to branch
+- <tt>commit</tt> - transfers state from branch to master
+- <tt>refresh</tt> - transfers state from master to branch
 
 
 ## State Elements Transition Table