kbsecret 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9587292e2be80b4a53d26f4bdda06e2a94d1b7be
-  data.tar.gz: 5dd01f1c1819f0f17537487ff73e621e27193938
+  metadata.gz: f468bb679d062bf75ce1d379e4cd76c4544c090f
+  data.tar.gz: d862b1c03920b88de8942fac32ad6f7b4fb89bd2
 SHA512:
-  metadata.gz: 4227a95d277ed064a5cd1b4dd3add4dedcabb97d041c66c5dffec753a87ab0de73684582a4d18e34bd33c192912d54dc173527516daa10a172dbd19d55e73574
-  data.tar.gz: b14e1d1524a71d70e85185c7c61c43a3791923c5698273b68398b6dcf1d072a682a3f7bfb695666d1cd25819812d740e5cf150c71142571d741dd5e426091845
+  metadata.gz: a9de681a6224e5f577deb31e8a72cafe288fa9d48c7de5e7438616c8887408a3705e813bd588fdfc328b84683e0f5b51540f58911163c81494cde918851306a4
+  data.tar.gz: 0fbe3224bc94a6a39eea6e1e0c578ab01fcd4755e92e827cd08441151086bd1cc2c65d00c2de8cfbefca0a32847001d53d7fc5496058de45bdf937cc7e3e64b7

data/README.md

@@ -1,6 +1,8 @@
 kbsecret
 ========
 
+*Note*: This is still a work in process. Use it with caution.
+
 kbsecret is a combined library/utility that provides a secret management
 interface for [KBFS](https://keybase.io/docs/kbfs) and
 [Keybase](https://keybase.io/).
@@ -16,7 +18,7 @@ interface for [KBFS](https://keybase.io/docs/kbfs) and
 
 ### Installation
 
-kbsecret is available via RubyGems:
+kbsecret is available via [RubyGems](https://rubygems.org/gems/kbsecret):
 
 ```bash
 $ gem install kbsecret
@@ -26,7 +28,7 @@ For hacking:
 
 ```bash
 $ git clone git@github.com:woodruffw/kbsecret.git && cd kbsecret
-$ RUBYLIB=./lib PATH=${PATH}:./bin ./bin/kbsecret help
+$ RUBYLIB=./lib PATH=./bin:${PATH} ./bin/kbsecret help
 ```
 
 ### Usage

data/lib/kbsecret/config.rb

@@ -2,11 +2,18 @@ require "yaml"
 require "fileutils"
 
 module KBSecret
+  # Global and per-session configuration for kbsecret.
   class Config
+    # the configuration directory
+    # @api private
     CONFIG_DIR = File.expand_path("~/.config/kbsecret").freeze
 
+    # the configuration file
+    # @api private
     CONFIG_FILE = File.join(CONFIG_DIR, "config.yml").freeze
 
+    # configuration defaults
+    # @api private
     DEFAULT_CONFIG = {
       mount: "/keybase",
 
@@ -18,22 +25,36 @@ module KBSecret
       }
     }.freeze
 
+    # Retrieve a configured value.
+    # @param key [String]
+    # @return [Object] the corresponding configuration
     def self.[](key)
       @@config[key]
     end
 
+    # Retrieve a session's configuration.
+    # @param sess [Symbol] the session's label
+    # @return [Hash] the session configuration
     def self.session(sess)
       @@config[:sessions][sess]
     end
 
+    # @return [Array<Symbol>] all configured session labels
+    # @todo This should be session_labels.
     def self.session_names
       @@config[:sessions].keys
     end
 
+    # @param sess [Symbol] the session label
+    # @return [Boolean] whether or not the given session is configured
     def self.session?(sess)
       session_names.include?(sess.to_sym)
     end
 
+    # Configure a session.
+    # @param label [Symbol] the session label
+    # @param hsh [Hash] the session configuration
+    # @todo This should be configure_session.
     def self.add_session(label, hsh)
       @@config[:sessions][label.to_sym] = hsh
       File.open(CONFIG_FILE, "w") { |io| io.write @@config.to_yaml }

data/lib/kbsecret/exceptions.rb

@@ -1,7 +1,9 @@
 module KBSecret
+  # A generic error in kbsecret.
   class KBSecretError < RuntimeError
   end
 
+  # Raised during record creation if too many/few arguments are given.
   class RecordCreationArityError < RuntimeError
     def initialize(exp, act)
       super "Needed #{exp} arguments for this record, got #{act}"

data/lib/kbsecret/record/abstract.rb

@@ -2,6 +2,8 @@ require "json"
 
 module KBSecret
   module Record
+    # Represents an abstract kbsecret record that can be subclassed to produce
+    # more useful records.
     # @abstract
     class Abstract
       attr_accessor :session
@@ -10,10 +12,18 @@ module KBSecret
       attr_reader :type
       attr_reader :data
 
+      # @return [String] the record's type
+      # @example
+      #  KBSecret::Record::Abstract.type # => "abstract"
       def self.type
         name.split("::").last.downcase
       end
 
+      # Load the given hash-representation into a record.
+      # @param session [Session] the session to associate with
+      # @param hsh [Hash] the record's hash-representation
+      # @return [Record::AbstractRecord] the created record
+      # @api private
       def self.load!(session, hsh)
         instance = allocate
         instance.session = session
@@ -22,6 +32,10 @@ module KBSecret
         instance
       end
 
+      # Create a brand new record, associated with a session.
+      # @param session [Session] the session to associate with
+      # @param label [Symbol] the new record's label
+      # @note Creation does *not* sync the new record; see {#sync!} for that.
       def initialize(session, label)
         @session = session
         @timestamp = Time.now.to_i
@@ -30,6 +44,10 @@ module KBSecret
         @data = {}
       end
 
+      # Fill in instance fields from a record's hash-representation.
+      # @param hsh [Hash] the record's hash-representation.
+      # @return [void]
+      # @api private
       def initialize_from_hash(hsh)
         @timestamp = hsh[:timestamp]
         @label = hsh[:label]
@@ -37,10 +55,16 @@ module KBSecret
         @data = hsh[:data]
       end
 
+      # The fully qualified path to the record's file.
+      # @return [String] the path
+      # @note If the record hasn't been synced to disk, this path may not
+      #  exist yet.
       def path
         File.join(session.directory, "#{label}.json")
       end
 
+      # Create a hash-representation of the current record.
+      # @return [Hash] the hash-representation
       def to_h
         {
           timestamp: timestamp,
@@ -50,6 +74,9 @@ module KBSecret
         }
       end
 
+      # Write the record's in-memory state to disk.
+      # @note Every sync updates the record's timestamp.
+      # @return [void]
       def sync!
         # bump the timestamp every time we sync
         @timestamp = Time.now.to_i

data/lib/kbsecret/record/environment.rb

@@ -1,9 +1,19 @@
+require "shellwords"
+
 module KBSecret
   module Record
+    # Represents a record containing an environment variable and value.
     class Environment < Abstract
+      # @param session [Session] the session to associate with
+      # @param label [Symbol] the new record's label
+      # @param variable [String] the new record's variable
+      # @param value [String] the new record's value
       def initialize(session, label, variable, value)
         super(session, label)
 
+        value = value.shellescape
+        variable = variable.shellescape
+
         @data = {
           environment: {
             variable: variable,
@@ -12,28 +22,38 @@ module KBSecret
         }
       end
 
+      # @return [String] the record's variable
       def variable
         @data[:environment][:variable]
       end
 
+      # @param var [String] the new variable to insert into the record
+      # @return [void]
+      # @note Triggers a record sync; see {Abstract#sync!}.
       def variable=(var)
         @data[:environment][:variable] = var
         sync!
       end
 
+      # @return [String] the record's value
       def value
         @data[:environment][:value]
       end
 
+      # @param val [String] the new value to insert into the record
+      # @return [void]
+      # @note Triggers a record sync; see {Abstract#sync!}.
       def value=(val)
         @data[:environment][:value] = val
         sync!
       end
 
+      # @return [String] a sh-style environment assignment
       def to_assignment
-        "#{variable}='#{value}'"
+        "#{variable}=#{value}"
       end
 
+      # @return [String] a sh-style environment export line
       def to_export
         "export #{to_assignment}"
       end

data/lib/kbsecret/record/login.rb

@@ -1,6 +1,11 @@
 module KBSecret
   module Record
+    # Represents a record containing a login (username, password) pair.
     class Login < Abstract
+      # @param session [Session] the session to associate with
+      # @param label [Symbol] the new record's label
+      # @param user [String] the new record's username
+      # @param pass [String] the new record's password
       def initialize(session, label, user, pass)
         super(session, label)
 
@@ -12,19 +17,27 @@ module KBSecret
         }
       end
 
+      # @return [String] the record's username
       def username
         @data[:login][:username]
       end
 
+      # @param user [String] the new username to insert into the record
+      # @return [void]
+      # @note Triggers a record sync; see {Abstract#sync!}.
       def username=(user)
         @data[:login][:username] = user
         sync!
       end
 
+      # @return [String] the record's password
       def password
         @data[:login][:password]
       end
 
+      # @param pass [String] the new password to insert into the record
+      # @return [void]
+      # @note Triggers a record sync; see {Abstract#sync!}.
       def password=(pass)
         @data[:login][:password] = pass
         sync!

data/lib/kbsecret/record/unstructured.rb

@@ -1,6 +1,10 @@
 module KBSecret
   module Record
+    # Represents a record containing unstructured text.
     class Unstructured < Abstract
+      # @param session [Session] the session to associate with
+      # @param label [Symbol] the new record's label
+      # @param text [String] the new record's unstructured text
       def initialize(session, label, text)
         super(session, label)
 
@@ -9,10 +13,14 @@ module KBSecret
         }
       end
 
+      # @return [String] the record's unstructured text
       def text
         @data[:text]
       end
 
+      # @param new_text [String] the new text to insert into the record
+      # @return [void]
+      # @note Triggers a record sync; see {Abstract#sync!}.
       def text=(new_text)
         @data[:text] = new_text
         sync!

data/lib/kbsecret/record.rb

@@ -6,21 +6,30 @@ require_relative "record/environment"
 require_relative "record/unstructured"
 
 module KBSecret
+  # The namespace for kbsecret records types.
   module Record
+    # @return [Array<Class>] the class objects of all non-abstract record types
     def self.record_classes
       klasses = constants.map(&Record.method(:const_get)).grep(Class)
       klasses.delete(Record::Abstract)
       klasses
     end
 
+    # @return [Array<String>] the types of all records
     def self.record_types
       record_classes.map(&:type)
     end
 
+    # @return [Boolean] whether a record class exists of the given type
     def self.type?(type)
       record_types.include?(type)
     end
 
+    # Load a record by path into the given session.
+    # @param session [Session] the session to load into
+    # @param path [String] the fully-qualified record path
+    # @return [Record::AbstractRecord] the loaded record
+    # @api private
     def self.load_record!(session, path)
       hsh = JSON.parse(File.read(path), symbolize_names: true)
       klass = record_classes.find { |c| c.type == hsh[:type] }

data/lib/kbsecret/session.rb

@@ -1,10 +1,20 @@
 module KBSecret
+  # Represents a session of N keybase users with collective read/write
+  # access to a collection of records.
   class Session
+    # @return [Symbol] the session's label
     attr_reader :label
+
+    # @return [Hash] the session-specific configuration, from
+    #  {Config::CONFIG_FILE}
     attr_reader :config
     attr_reader :directory
     attr_reader :records
 
+    # @param label [Symbol] the label of the session to initialize
+    # @note This does not *create* a new session, but loads one already
+    #  specified in {Config::CONFIG_FILE}. To *create* a new session,
+    #  see {Config.add_session}.
     def initialize(label: :default)
       @label = label
       @config = Config.session(label.to_sym)
@@ -13,10 +23,20 @@ module KBSecret
       @records = load_records!
     end
 
+    # @return [Array<Symbol>] the labels of all records known to the session
+    # @example
+    #  session.record_labels # => [:website1, :apikey1, :website2]
     def record_labels
       records.map(&:label)
     end
 
+    # Add a record to the session.
+    # @param type [String] the type of record (see {Record.record_types})
+    # @param label [Symbol] the new record's label
+    # @param args [Array<String>] the record-type specific arguments
+    # @return [void]
+    # @raise RecordCreationArityError if the number of specified record
+    #  arguments does not match the record type's constructor
     def add_record(type, label, *args)
       klass = Record.record_classes.find { |k| k.type == type }
       arity = klass.instance_method(:initialize).arity - 2
@@ -30,6 +50,10 @@ module KBSecret
       record.sync!
     end
 
+    # Delete a record from the session, if it exists. Does nothing if
+    # no such record can be found.
+    # @param rec_label [Symbol] the label of the record to delete
+    # @return [void]
     def delete_record(rec_label)
       record = records.find { |r| r.label == rec_label }
       return unless record
@@ -38,6 +62,8 @@ module KBSecret
       records.delete(record)
     end
 
+    # @return [Boolean] whether or not the session contains a record with the
+    #  given label
     def record?(label)
       record_labels.include?(label)
     end

data/lib/kbsecret.rb

@@ -5,9 +5,12 @@ require_relative "kbsecret/exceptions"
 require_relative "kbsecret/record"
 require_relative "kbsecret/session"
 
+# The primary namespace for kbsecret.
 module KBSecret
-  VERSION = "0.0.1".freeze
+  # kbsecret's current version
+  VERSION = "0.0.2".freeze
 
+  # fail very early if the user doesn't have keybase and KBFS running
   raise Keybase::KeybaseNotRunningError unless Keybase.running?
   raise Keybase::KBFSNotRunningError unless Dir.exist?(Config[:mount])
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kbsecret
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - William Woodruff
@@ -55,14 +55,14 @@ dependencies:
 description: Manages your passwords, environment, and more via KBFS.
 email: william@tuffbizz.com
 executables:
-- kbsecret
+- kbsecret-sessions
+- kbsecret-new-session
+- kbsecret-new
 - kbsecret-rm
+- kbsecret-list
 - kbsecret-login
-- kbsecret-new
 - kbsecret-env
-- kbsecret-new-session
-- kbsecret-list
-- kbsecret-sessions
+- kbsecret
 extensions: []
 extra_rdoc_files: []
 files: