cred_hubble 0.1.0.pre → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9fbb2a2213b7e25f0b2df91998752c619c30e659
-  data.tar.gz: eec8c7e06c8435368b241ba5eba2bd646eb0adc9
+  metadata.gz: 8345013303bcb55d2335018f4d4469557ed6f88a
+  data.tar.gz: 24b09bdcef1948594f326f212c5581c7c9ef8d47
 SHA512:
-  metadata.gz: 79f915304e5b0e401c247b2ea8948513243e6fd5e2de99eb0621e6ab585612904f6904e8c8faa8cdf607d71e0246b6b9ed193e36a69bb38d8755c4c11f479740
-  data.tar.gz: af03b68be2dae89b3df1d2afba454668f3ecee12a457c08f38659c74e6571b7dca134c272cff3f5848cb6d5f5ee34d7e45e3ba412e1eea10ae8eeec5073011fd
+  metadata.gz: 17bca452601dca62005f46a238671b565e7e0c481ef88278d6ca333881a0502b69ee4bff600c4b179cf9a2d63123b36dbdced0feff18d8defca75399ba39aa3e
+  data.tar.gz: a00b2bcf4adbaa8e8ee7fda6310c777087ec01d1a96df4b84c0a43408b39b3b37a782946e6f035125fa0c80d4ee45f349827b884d72ed0b1b4f0affdb3eb93a5

data/cred_hubble.gemspec

@@ -27,8 +27,10 @@ Gem::Specification.new do |spec|
   spec.add_runtime_dependency 'addressable', '~> 2.0'
 
   spec.add_development_dependency 'bundler', '~> 1.15'
+  spec.add_development_dependency 'gem-release'
   spec.add_development_dependency 'rake', '~> 10.0'
   spec.add_development_dependency 'rspec', '~> 3.0'
   spec.add_development_dependency 'rubocop'
   spec.add_development_dependency 'webmock', '~> 3.0'
+  spec.add_development_dependency 'yard'
 end

data/lib/cred_hubble/client.rb

@@ -6,6 +6,15 @@ require 'openssl'
 # rubocop:disable ClassLength
 module CredHubble
   class Client
+    # Instantiates a new CredHubble::Client.
+    #
+    # @param host [String] host for the target CredHub server
+    # @param port [Integer] port for the target CredHub server
+    # @param auth_header_token [String] oAuth2 bearer token for auth header
+    # @param client_cert_path [String] path to a client TLS certificate
+    # @param client_key_path [String] path to a client TLS encryption key
+    # @param ca_path [String] path to a CA certificate
+    # @return [CredHubble::Client] a CredHubble::Client instance
     def initialize(host:, port: 8844, auth_header_token: nil, ca_path: nil,
                    client_cert_path: nil, client_key_path: nil)
 
@@ -17,6 +26,13 @@ module CredHubble
       @client_key_path = client_key_path
     end
 
+    # Instantiates a new CredHubble::Client using an oAuth2 bearer token for auth header authentication.
+    #
+    # @param host [String] host for the target CredHub server
+    # @param port [Integer] port for the target CredHub server
+    # @param auth_header_token [String] oAuth2 bearer token for auth header
+    # @param ca_path [String] path to a CA certificate
+    # @return [CredHubble::Client] a CredHubble::Client instance
     def self.new_from_token_auth(host:, port: 8844, auth_header_token:, ca_path: nil)
       new(
         auth_header_token: auth_header_token,
@@ -26,6 +42,14 @@ module CredHubble
       )
     end
 
+    # Instantiates a new CredHubble::Client using a client TLS certificate and key for mutual TLS authentication.
+    #
+    # @param host [String] host for the target CredHub server
+    # @param port [Integer] port for the target CredHub server
+    # @param client_cert_path [String] path to a client TLS certificate
+    # @param client_key_path [String] path to a client TLS encryption key
+    # @param ca_path [String] path to a CA certificate
+    # @return [CredHubble::Client] a CredHubble::Client instance
     def self.new_from_mtls_auth(host:, port: 8844, client_cert_path:, client_key_path:, ca_path: nil)
       new(
         client_cert_path: client_cert_path,
@@ -36,21 +60,39 @@ module CredHubble
       )
     end
 
+    # Performs a GET request to the CredHub /info endpoint.
+    #
+    # @return [CredHubble::Resources::Info] a CredHubble::Resources::Info instance
     def info
       response = http_client.get('/info').body
       CredHubble::Resources::Info.from_json(response)
     end
 
+    # Performs a GET request to the CredHub /health endpoint.
+    #
+    # @return [CredHubble::Resources::Health] a CredHubble::Resources::Health instance
     def health
       response = http_client.get('/health').body
       CredHubble::Resources::Health.from_json(response)
     end
 
+    # Retrieves a Credential by ID.
+    #
+    # @param credential_id [String] a CredHub credential identifier
+    # @return [CredHubble::Resources::Credential] a CredHubble::Resources::Credential instance,
+    #   e.g. CredHubble::Resources::ValueCredential
     def credential_by_id(credential_id)
       response = http_client.get("/api/v1/data/#{credential_id}").body
       CredHubble::Resources::CredentialFactory.from_json(response)
     end
 
+    # Retrieves a collection of Credentials by Name.
+    #
+    # @param name [String] a CredHub credential name, e.g '/my-credential'
+    # @param current [Boolean] whether or not to return only the current version of a Credential
+    # @param versions [Integer] the maximum number of versions of a Credential to return
+    # @return [CredHubble::Resources::CredentialCollection] a CredHubble::Resources::CredentialCollection instance,
+    #   containing an enumerable list of Credentials
     def credentials_by_name(name, current: nil, versions: nil)
       template = Addressable::Template.new('/api/v1/data{?query*}')
 
@@ -61,6 +103,20 @@ module CredHubble
       CredHubble::Resources::CredentialCollection.from_json(response)
     end
 
+    # Retrieves the value of the current Credential for the given name
+    #
+    # @param credential_name [String] a CredHub credential name, e.g '/my-credential'
+    # @return [String, Hash, RsaValue, SshValue, UserValue, CertificateValue, nil] the Credential#value if it exists
+    def current_credential_value(credential_name)
+      current_credential = credentials_by_name(credential_name, current: true).first
+      current_credential && current_credential.value
+    end
+
+    # Retrieves a collection of Permissions for a Credential by Credential Name.
+    #
+    # @param credential_name [String] a CredHub credential name, e.g '/my-credential'
+    # @return [CredHubble::Resources::PermissionCollection] a CredHubble::Resources::PermissionCollection instance,
+    #   containing an enumerable list of Permissions
     def permissions_by_credential_name(credential_name)
       template = Addressable::Template.new('/api/v1/permissions{?query*}')
 
@@ -71,6 +127,14 @@ module CredHubble
       CredHubble::Resources::PermissionCollection.from_json(response)
     end
 
+    # Creates a new Credential or adds a new version of an existing Credential.
+    #
+    # @param credential [CredHubble::Resources::Credential] a CredHubble::Resources::Credential instance
+    # @param overwrite [Boolean] whether or not CredHub should create a new current version for existing Credentials
+    # @param additional_permissions [CredHubble::Resources::PermissionCollection]
+    #   a CredHubble::Resources::PermissionCollection for additional Permissions to set on the credentials
+    # @return [CredHubble::Resources::Credential] a CredHubble::Resources::Credential instance,
+    #   e.g. CredHubble::Resources::CertificateCredential
     def put_credential(credential, overwrite: nil, additional_permissions: [])
       credential_body = credential.attributes_for_put
       credential_body[:overwrite] = !!overwrite unless overwrite.nil?
@@ -83,10 +147,19 @@ module CredHubble
       CredHubble::Resources::CredentialFactory.from_json(response)
     end
 
+    # Populates "credhub-ref" keys in a JSON string (e.g. ENV['VCAP_SERVICES']) with credential values.
+    #
+    # @param vcap_services_json [String] a valid JSON string including, particularly one from a Cloud Foundry app's
+    #   VCAP_SERVICES environment variable
+    # @return [String] a valid JSON string with populated CredHub references
     def interpolate_credentials(vcap_services_json)
       http_client.post('/api/v1/interpolate', vcap_services_json).body
     end
 
+    # Deletes a Credential with the given Name.
+    #
+    # @param name [String] a CredHub credential name, e.g '/my-credential'
+    # @return [Boolean] true if the deletion was successful
     def delete_credential_by_name(name)
       template = Addressable::Template.new('/api/v1/data{?query*}')
 
@@ -96,11 +169,22 @@ module CredHubble
       http_client.delete(path).success?
     end
 
+    # Adds additional Permissions to an existing Credential. The Credential is specified by the `credential_name` field
+    # on the PermissionCollection
+    #
+    # @param permission_collection [CredHubble::Resources::PermissionCollection]
+    #   a CredHubble::Resources::PermissionCollection for additional Permissions to set on the credentials
+    # @return [CredHubble::Resources::PermissionCollection] a CredHubble::Resources::PermissionCollection instance
     def add_permissions(permission_collection)
       response = http_client.post('/api/v1/permissions', permission_collection.to_json).body
       CredHubble::Resources::PermissionCollection.from_json(response)
     end
 
+    # Deletes any permissions for the given actor for a Credential.
+    #
+    # @param credential_name [String] a CredHub credential name, e.g '/my-credential'
+    # @param actor [String] a CredHub actor, e.g. 'uaa-user:fca1ae5e-f417-45ce-94b0-79889e27e047'
+    # @return [Boolean] true if the deletion was successful
     def delete_permissions(credential_name, actor)
       template = Addressable::Template.new('/api/v1/permissions{?query*}')
 

data/lib/cred_hubble/version.rb

@@ -1,3 +1,3 @@
 module CredHubble
-  VERSION = '0.1.0.pre'.freeze
+  VERSION = '0.1.0'.freeze
 end

data/spec/cred_hubble/client_spec.rb

@@ -219,6 +219,49 @@ RSpec.describe CredHubble::Client do
     end
   end
 
+  describe '#current_credential_value' do
+    let(:response_body) do
+      '{
+        "data":[
+          {
+            "type":"user",
+            "version_created_at":"2017-10-03T04:12:21Z",
+            "id":"5298e0e4-c3f5-4c73-a156-9ffce4c137f5",
+            "name":"/trade-federation-admin",
+            "value": {
+              "username": "roger_roger",
+              "password": "2582aaf15ec84e3fa3ba682152663a52",
+              "password_hash": "3638fbae81358ff9020be1d7a9a509fc6:1234"
+            }
+          }
+        ]
+      }'
+    end
+
+    it 'makes a request to the /api/v1/data endpoint with the name as a query parameter' do
+      subject.current_credential_value('/trade-federation-admin')
+      expect(mock_http_client).to have_received(:get).with('/api/v1/data?name=%2Ftrade-federation-admin&current=true')
+    end
+
+    context 'when a credential for the given name exists' do
+      it 'returns the credential value' do
+        credential_value = subject.current_credential_value('/trade-federation-admin')
+        expect(credential_value.username).to eq('roger_roger')
+        expect(credential_value.password).to eq('2582aaf15ec84e3fa3ba682152663a52')
+        expect(credential_value.password_hash).to eq('3638fbae81358ff9020be1d7a9a509fc6:1234')
+      end
+    end
+
+    context 'when a credential for the given name does not exist' do
+      let(:response_body) { '{"data":[]}' }
+
+      it 'returns nil' do
+        credential_value = subject.current_credential_value('/trade-federation-admin')
+        expect(credential_value).to be_nil
+      end
+    end
+  end
+
   describe '#permissions_by_credential_name' do
     let(:response_body) do
       '{

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cred_hubble
 version: !ruby/object:Gem::Version
-  version: 0.1.0.pre
+  version: 0.1.0
 platform: ruby
 authors:
 - Tim Downey
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-10-09 00:00:00.000000000 Z
+date: 2017-10-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -78,6 +78,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.15'
+- !ruby/object:Gem::Dependency
+  name: gem-release
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -134,6 +148,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: 
 email:
 - tim@downey.io
@@ -212,9 +240,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '2.1'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
 rubyforge_project: 
 rubygems_version: 2.6.13