ccs 3.0.0 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ddc7a13cb4e185260a511ead10fd9f75387fecdd42a4138d19e0a0de35cd9caf
-  data.tar.gz: 8c99aa2c31cbd7a66bb1023f8b32872478691268b475b80f9bf6c203ebb978a1
+  metadata.gz: ce4380f6f1c426727a7147117ba50c7dc21866ec766ecf01083846e5340d8d79
+  data.tar.gz: 162d1b0bebdcbec23a1bb72b2c82d7ad4b6994c4ab6fc4258d1ebeebe29c61b9
 SHA512:
-  metadata.gz: 6c8f8bff758c7917bee0a1f779f5a97594c863d19ae96a673b8ca630cfe0189649d326130c44b622799ce489b9486492c1bf9fb74ee38c6e998167f29a7cb8a5
-  data.tar.gz: 0ac4cd8805f4addd47e7b224a7eff2a7fab360856294aed60444846946d9563c294d415bdbba9f72da3d7fe2f966b1cec18d5f51b97fc615e6a0da49d6da8d94
+  metadata.gz: 70e1cd7ac88384e75d62093429b4fa37a4b2aba6c6b3439e47c856653b2eac54c56b2e55d11281b2258ee0497a6e5008cc365b3f402ae3277e6612764af9e502
+  data.tar.gz: 8b580583449616952eedf65b13e7c893464cfb7fd3595ff2f238eaf933741211dad276df92d31008b54b7d0976ed727bc9a9471d109dc6d8697e3caa047e2f3c

data/CHANGELOG.md

@@ -0,0 +1,10 @@
+## 3.1.0 2020-11-23
+
+
+### Added
+
+- `force` argument to overwrite remote documents when uploading (paweljw)
+- YARD documentation (paweljw)
+
+
+[Compare 3.0.0...3.1.0](https://github.com/occson/ccs/compare/3.0.0...3.1.0)

data/README.md

@@ -6,9 +6,7 @@ Configuration control system
 
 Add this line to your application's Gemfile:
 
-```ruby
-gem 'ccs'
-```
+    gem 'ccs'
 
 And then execute:
 
@@ -27,6 +25,7 @@ Or install it yourself as:
             --access-token
         -p CCS_PASSPHRASE,               CCS Passphrase
             --passphrase
+        -f, --[no-]force                 Overwrite remote documents when uploading
 
 
 ## Example
@@ -45,6 +44,10 @@ Upload local file
 
     ccs cp /local/path/to/file.yml ccs://workspace-name/0.1.0/path/to/file.yml
 
+Upload local file, overwriting remote document if any'
+
+    ccs cp --force /local/path/to/file.yml ccs://workspace-name/0.1.0/path/to/file.yml
+
 Upload content from STDIN
 
     echo "{ a: 1 }" | ccs cp  - ccs://workspace-name/0.1.0/path/to/file.yml
@@ -79,6 +82,13 @@ After checking out the repo, run `bin/setup` to install dependencies. Then, run
 
 To install this gem onto your local machine, run `bin/rake install`. To release a new version, update the version number in `version.rb`, and then run `bin/rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
+## Documentation
+
+Documentation for the code should be written in YARD format. It can be generated locally into the `doc` directory by running
+
+    bundle exec yard
+
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/occson/ccs. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.

data/exe/ccs

@@ -42,6 +42,10 @@ when 'cp'
       options['passphrase'] = v
     end
 
+    option_parser.on('-f', '--[no-]force', 'Overwrite remote documents when uploading') do |v|
+      options['force'] = v
+    end
+
     option_parser.separator ''
     option_parser.separator 'Configure via environment variables:'
     option_parser.separator '  CCS_ACCESS_TOKEN'
@@ -57,6 +61,8 @@ when 'cp'
     option_parser.separator '    ccs cp ccs://workspace-name/0.1.0/path/to/file.yml /local/path/to/file.yml'
     option_parser.separator '  Upload local file'
     option_parser.separator '    ccs cp /local/path/to/file.yml ccs://workspace-name/0.1.0/path/to/file.yml'
+    option_parser.separator '  Upload local file, overwriting remote document if any'
+    option_parser.separator '    ccs cp --force /local/path/to/file.yml ccs://workspace-name/0.1.0/path/to/file.yml'
     option_parser.separator '  Upload content from STDIN'
     option_parser.separator '    echo "{ a: 1 }" | ccs cp  - ccs://workspace-name/0.1.0/path/to/file.yml'
     option_parser.separator '    cat /local/path/to/file.yml | ccs cp - ccs://workspace-name/0.1.0/path/to/file.yml'
@@ -77,7 +83,7 @@ when 'cp'
   raise OptionParser::MissingArgument, 'source' unless arguments.fetch(0, nil)
   raise OptionParser::MissingArgument, 'destination' unless arguments.fetch(1, nil)
 
-  exit(1) unless Ccs::Commands::Copy.new(arguments[0], arguments[1], options['access_token'], options['passphrase']).call
+  exit(1) unless Ccs::Commands::Copy.new(arguments[0], arguments[1], options['access_token'], options['passphrase'], force: options.fetch('force', false)).call
 else
   puts option_parser
   exit(1)

data/lib/ccs.rb

@@ -12,6 +12,8 @@ require 'ccs/decrypter'
 require 'ccs/uploader'
 require 'ccs/downloader'
 require 'ccs/document'
+
 require 'ccs/commands/copy'
 
+# Top level `Ccs` namespace.
 module Ccs; end

data/lib/ccs/commands/copy.rb

@@ -2,14 +2,37 @@
 
 module Ccs
   module Commands
+    # The copy command, responsible for copying a target to a destination, performing encryption
+    # and decryption as necessary.
+    #
+    # The target and destinations can be:
+    #
+    # - STDIN/STDOUT: a `-` sign is interpreted as these standard streams
+    #
+    # - The Occson server: strings beginning with `ccs://` or `http(s)://` are interpreted as such
+    #
+    # - local files: everything not matching the previous descriptions is assumed to
+    #   be a path on the local system
     class Copy
-      def initialize(source, destination, access_token, passphrase)
+      # Builds an instance of the Copy command.
+      #
+      # @param source [String] `-` for STDIN, an URI or a local file path
+      # @param destination [String] `-` for STDOUT, an URI or a local file path
+      # @param access_token [String] Occson access token
+      # @param passphrase [String] Passphrase used for encryption of the document
+      # @param force [Boolean] Whether to overwrite target document in Occson, if any. Default `false`.
+      def initialize(source, destination, access_token, passphrase, force: false)
         @source = source
         @destination = destination
         @access_token = access_token
         @passphrase = passphrase
+        @force = force
       end
 
+      # Performs a transfer between locations - an upload if `@source` is local or STDIN,
+      # a download if `@source` is an URI.
+      #
+      # No guarantees are made about the return values of this method.
       def call
         download? ? download : upload
       end
@@ -29,7 +52,7 @@ module Ccs
 
       def upload
         content = @source.eql?('-') ? STDIN.read : File.read(@source)
-        Document.new(@destination, @access_token, @passphrase).upload(content)
+        Document.new(@destination, @access_token, @passphrase).upload(content, force: @force)
       end
     end
   end

data/lib/ccs/decrypter.rb

@@ -1,12 +1,27 @@
 # frozen_string_literal: true
 
 module Ccs
+  # Handles client-side decryption for documents.
+  #
+  # The decrypter uses AES-256 in CBC mode internally. A salt is
+  # expected in bytes 8..15, with ciphertext occupying the
+  # further bytes.
   class Decrypter
+    # Constructs a Decrypter instance with given passphrase and content.
+    #
+    # @example
+    #   Ccs::Decrypter.new('the content passphrase', content)
+    #  
+    # @param passphrase [String] Passphrase for content decryption
+    # @param content [String] Encrypted document content
     def initialize(passphrase, content)
       @passphrase = passphrase
       @content = content
     end
 
+    # Performs decryption, returning plaintext if passphrase matched.
+    #
+    # @return [String] Plaintext document content
     def call
       decryptor.pkcs5_keyivgen(@passphrase, ciphertext_salt, 1)
       result = decryptor.update(encrypted)

data/lib/ccs/document.rb

@@ -1,17 +1,46 @@
 # frozen_string_literal: true
 
 module Ccs
+  # An abstraction for the Document concept. Simplifies building URLs,
+  # uploading and downloading contents. Abstracts away workspaces due to
+  # the use of access tokens in constructions.
   class Document
+    # Constructs a Document instance from a given URI, access token and passphrase.
+    #
+    # @example
+    #    uri = 'ccs://path/to/file.yml'
+    #    access_token = 'f30b5450421362c9ca0b'
+    #    passphrase = 'my document passphrase'
+    #
+    #    Ccs::Document.new(uri, access_token, passphrase)
+    #
+    # @param uri [String] Document URI. Accepts `ccs://` as shorthand for Occson location.
+    # @param access_token [String] Occson access token.
+    # @param passphrase [String] Document passphrase, used in encryption and decryption.
     def initialize(uri, access_token, passphrase)
       @uri = build_uri(uri)
       @access_token = access_token
       @passphrase = passphrase
     end
 
-    def upload(content)
-      Uploader.new(@uri, content, @access_token, @passphrase).call
+    # Uploads the given plaintext `content` to target URI.
+    #
+    # @example
+    #     document.upload('My example plaintext.')
+    #
+    # @param content [String] Plaintext to be encrypted and uploaded.
+    # @param force [Boolean] Whether to overwrite target document in Occson, if any. Default `false`.
+    def upload(content, force: false)
+      Uploader.new(@uri, content, @access_token, @passphrase, force: force).call
     end
 
+    # Downloads the encrypted document at `@uri` and returns the plaintext
+    # contents (given that `@passphrase` matches).
+    #
+    # @example
+    #    plaintext = document.download
+    #
+    # @return [String] Decrypted document contents
     def download
       Downloader.new(@uri, @access_token, @passphrase).call
     end

data/lib/ccs/downloader.rb

@@ -1,13 +1,31 @@
 # frozen_string_literal: true
 
 module Ccs
+  # Downloads and decrypts the document at given URI with given access token.
+  # Decryption occurs using given passphrase.
   class Downloader
+    # Constructs a Downloader instance from a given URI, access token and passphrase.
+    #
+    # @example
+    #    uri = 'ccs://path/to/file.yml'
+    #    access_token = 'f30b5450421362c9ca0b'
+    #    passphrase = 'my document passphrase'
+    #
+    #    Ccs::Downloader.new(uri, access_token, passphrase)
+    #
+    # @param uri [String] Document URI. Accepts `ccs://` as shorthand for Occson location.
+    # @param access_token [String] Occson access token.
+    # @param passphrase [String] Document passphrase, used in encryption and decryption.
     def initialize(uri, access_token, passphrase)
       @uri = uri
       @access_token = access_token
       @passphrase = passphrase
     end
 
+    # Performs the download and decryption of document.
+    #
+    # @return [String|nil] Decrypted body of the document or `nil` in case the
+    #   server did not respond with a `200` HTTP code.
     def call
       response = http.request(request)
       body = response.body

data/lib/ccs/encrypter.rb

@@ -1,13 +1,32 @@
 # frozen_string_literal: true
 
 module Ccs
+  # Encrypts the given content for transmission. Uses AES-256 in CBC
+  # mode internally, with salting.
   class Encrypter
+    # Constructs an Encrypter instance with given passphrase, content and salt.
+    # Salt _must_ be exactly 8 characters long.
+    #
+    # @example
+    #   passphrase = 'my long document passphrase'
+    #   content = 'very secret content'
+    #   salt = '12345678'
+    #
+    #   Ccs::Encrypter.new(passphrase, content, salt)
+    #
+    # @param passphrase [String] Document passphrase.
+    # @param content [String] Plaintext content to be encrypted.
+    # @param salt [String] Salt to reinforce the encryption, included in
+    #   plaintext in the encrypted document.
     def initialize(passphrase, content, salt)
       @passphrase = passphrase
       @content = content
       @salt = salt
     end
 
+    # Performs the actual encryption, returning base64-encoded ciphertext.
+    #
+    # @return [String] base64-encoded ciphertext
     def call
       encryptor.pkcs5_keyivgen(@passphrase, @salt, 1)
       encrypted = encryptor.update(@content)

data/lib/ccs/uploader.rb

@@ -1,17 +1,37 @@
 # frozen_string_literal: true
 
 module Ccs
+  # Encrypts and uploads the document to Occson.
   class Uploader
-    def initialize(uri, content, access_token, passphrase)
+    # Constructs an Uploader instance from a given URI, content, access token and passphrase.
+    #
+    # @example
+    #    uri = 'ccs://path/to/file.yml'
+    #    content = 'my very secret message'
+    #    access_token = 'f30b5450421362c9ca0b'
+    #    passphrase = 'my document passphrase'
+    #
+    #    Ccs::Uploader.new(uri, access_token, passphrase)
+    #
+    # @param uri [String] Document URI. Accepts `ccs://` as shorthand for Occson location.
+    # @param content [String] Plaintext for encryption and upload.
+    # @param access_token [String] Occson access token.
+    # @param passphrase [String] Document passphrase, used in encryption and decryption.
+    # @param force [Boolean] Whether to overwrite target document in Occson, if any. Default `false`.
+    def initialize(uri, content, access_token, passphrase, force: false)
       @uri = uri
       @content = content
       @access_token = access_token
       @passphrase = passphrase
+      @force = force.to_s
     end
 
+    # Performs the actual upload to server.
+    #
+    # @return [Boolean] `true` for a successful upload, `false` otherwise
     def call
-      request.body = { encrypted_content: encrypted_content }.to_json
-      http.request(request).code.eql? '201'
+      request.body = { encrypted_content: encrypted_content, force: @force }.to_json
+      %w[200 201].include?(http.request(request).code)
     end
 
     private

data/lib/ccs/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 module Ccs
-  VERSION = '3.0.0'
+  # Ccs gem version definition
+  VERSION = '3.1.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ccs
 version: !ruby/object:Gem::Version
-  version: 3.0.0
+  version: 3.1.0
 platform: ruby
 authors:
 - tkowalewski
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-10-23 00:00:00.000000000 Z
+date: 2020-11-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: inch