conjur-api 4.13.0 → 4.14.0

data/lib/conjur/resource.rb

@@ -21,28 +21,62 @@
 require 'conjur/annotations'
 
 module Conjur
+
+  # A `Conjur::Resource` instance represents a Conjur
+  # {http://developer.conjur.net/reference/services/authorization/resource Resource}.
+  #
+  # You should not instantiate this class directly.  Instead, you can get an instance from the
+  # {Conjur::API#resource} and {Conjur::API#resources} methods, or from the {ActsAsResource#resource} method
+  # present on objects representing Conjur assets that have associated resources.
+  #
   class Resource < RestClient::Resource
     include HasAttributes
     include PathBased
     include Exists
-    
+
+    # The identifier part of the `resource_id` for this resource.  The identifier
+    # is the resource id without the `account` and `kind` parts.
+    #
+    # @example
+    #   resource = api.resource 'conjur:layer:pubkeys-1.0/public-keys'
+    #   resource.identifier # => 'pubkeys-1.0/public-keys'
+    #
+    # @return [String] the identifier part of the id.
     def identifier
       match_path(3..-1)
     end
-    
+
+    # The full role id of the role that owns this resource.
+    #
+    # @example
+    #   api.current_role # => 'conjur:user:jon'
+    #   resource = api.create_resource 'conjur:example:resource-owner'
+    #   resource.owner # => 'conjur:user:jon'
+    #
+    # @return [String] the full role id of this resource's owner.
     def ownerid
       attributes['owner']
     end
 
     alias owner ownerid
     
-    # Name convention according to Role#roleid.  
+    # Return the full id for this resource.  The format is `account:kind:identifier`
+    #
+    # @example
+    #   resource = api.layer('pubkeys-1.0/public-keys').resource
+    #   resource.account        # => 'conjur'
+    #   resource.kind           # => 'layer'
+    #   resource.identifier     # => 'pubkeys-1.0/public-keys'
+    #   resource.resourceid     # => 'conjur:layer:pubkeys-1.0/public-keys'
+    # @return [String]
     def resourceid 
       [account, kind, identifier].join ':'
     end
     
     alias :resource_id :resourceid
-    
+
+
+    # @api private
     def create(options = {})
       log do |logger|
         logger << "Creating resource #{resourceid}"
@@ -54,16 +88,42 @@ module Conjur
     end
     
     # Lists roles that have a specified permission on the resource.
+    #
+    # This will return only roles of which api.current_user is a member.
+    #
+    # @example
+    #   resource = api.resource 'conjur:variable:example'
+    #   resource.permitted_roles 'execute' # => ['conjur:user:admin']
+    #   resource.permit 'execute', api.user('jon')
+    #   resource.permitted_roles 'execute' # => ['conjur:user:admin', 'conjur:user:jon']
+    #
+    # @param permission [String] the permission``
+    # @param options [Hash, nil] extra options to pass to RestClient::Resource#get
+    # @return [Array<String>] the ids of roles that have `permission` on this resource.
     def permitted_roles(permission, options = {})
       JSON.parse RestClient::Resource.new(Conjur::Authz::API.host, self.options)["#{account}/roles/allowed_to/#{permission}/#{path_escape kind}/#{path_escape identifier}"].get(options)
     end
     
-    # Changes the owner of a resource
+    # Changes the owner of a resource.  You must be the owner of the resource
+    # or a member of the owner role to do this.
+    #
+    # @example
+    #     resource.owner # => 'conjur:user:admin'
+    #     resource.give_to 'conjur:user:jon'
+    #     resource.owner # => 'conjur:user:jon'
+    #
+    # @param owner [String, #roleid] the new owner.
+    # @return [void]
     def give_to(owner, options = {})
       owner = cast(owner, :roleid)
-      self.put(options.merge(owner: owner))
+      invalidate do
+        self.put(options.merge(owner: owner))
+      end
+
+      nil
     end
 
+    # @api private
     def delete(options = {})
       log do |logger|
         logger << "Deleting resource #{resourceid}"
@@ -74,6 +134,32 @@ module Conjur
       super options
     end
 
+    # Grant `privilege` on this resource to `role`.
+    #
+    # This operation is idempotent, that is, nothing will happen if
+    # you attempt to grant a privilege that the role already has on
+    # this resource.
+    #
+    # @example
+    #   user = api.user 'bob'
+    #   resource = api.variable('example').resource
+    #   resource.permitted_roles 'bake' # => ['conjur:user:admin']
+    #   resource.permit 'fry', user
+    #   resource.permitted_roles 'fry' # => ['conjur:user:admin', 'conjur:user:bob']
+    #   resource.permit ['boil', 'bake'], bob
+    #   resource.permitted_roles 'boil' # => ['conjur:user:admin', 'conjur:user:bob']
+    #   resource.permitted_roles 'bake' # => ['conjur:user:admin', 'conjur:user:bob']
+    #
+    # @param privilege [String, #each] The privilege to grant, for example
+    #   `'execute'`, `'read'`, or `'update'`.  You may also pass an `Enumerable`
+    #   object, in which case the Strings yielded by #each will all be granted
+    #
+    # @param role [String, #roleid] The role-ish object or full role id
+    #   to which the permission is to be granted/
+    #
+    # @param options [Hash, nil] options to pass through to `RestClient::Resource#post`
+    #
+    # @return [void]
     def permit(privilege, role, options = {})
       role = cast(role, :roleid)
       eachable(privilege).each do |p|
@@ -91,8 +177,24 @@ module Conjur
           raise $! unless $!.http_body == "Privilege already granted."
         end
       end
+      nil
     end
-    
+
+    # The inverse operation of `#permit`.  Deny permission `privilege` to `role`
+    # on this resource.
+    #
+    # @example
+    #
+    #   resource.permitted_roles 'execute' # => ['conjur:user:admin', 'conjur:user:alice']
+    #   resource.deny 'execute', 'conjur:user:alice'
+    #   resource.permitted_roles 'execute' # =>  ['conjur:user:admin']
+    #
+    # @param privilege [String, #each] A permission name or an `Enumerable` of permissions to deny.  In the
+    #   later, all permissions will be denied.
+    #
+    # @param role [String, :roleid] A full role id or a role-ish object whose permissions we will deny.
+    #
+    # @return [void]
     def deny(privilege, role, options = {})
       role = cast(role, :roleid)
       eachable(privilege).each do |p|
@@ -104,11 +206,27 @@ module Conjur
         end
         self["?deny&privilege=#{query_escape p}&role=#{query_escape role}"].post(options)
       end
+      nil
     end
 
-    # True if the logged-in role, or a role specified using the acting-as option, has the
+    # True if the logged-in role, or a role specified using the :acting_as option, has the
     # specified +privilege+ on this resource.
+    #
+    # @example
+    #   api.current_role # => 'conjur:cat:mouse'
+    #   resource.permitted_roles 'execute' # => ['conjur:user:admin', 'conjur:cat:mouse']
+    #   resource.permitted_roles 'update', # => ['conjur:user:admin', 'conjur:cat:gino']
+    #
+    #   resource.permitted? 'update' # => false, `mouse` can't update this resource
+    #   resource.permitted? 'execute' # => true, `mouse` can execute it.
+    #   resource.permitted? 'update',acting_as: 'conjur:cat:gino' # => true, `gino` can update it.
+    # @param privilege [String] the privilege to check
+    # @param [Hash, nil] options for the request
+    # @option options [String,nil] :acting_as check whether the role given by this full role id is permitted
+    #   instead of checking +api.current_role+.
+    # @return [Boolean]
     def permitted?(privilege, options = {})
+      # TODO this method should accept an optional role rather than putting it in the options hash.
       params = {
         check: true,
         privilege: query_escape(privilege)
@@ -121,15 +239,31 @@ module Conjur
     rescue RestClient::ResourceNotFound
       false
     end
-    
-    # Return a Conjur::Annotations instance to read and manipulate our annotations.
+
+    # Return an {Conjur::Annotations} object to manipulate and view annotations.
+    #
+    # @see Conjur::Annotations
+    # @example
+    #    resource.annotations.count # => 0
+    #    resource.annotations['foo'] = 'bar'
+    #    resource.annotations.each do |k,v|
+    #       puts "#{k}=#{v}"
+    #    end
+    #    # output is
+    #    # foo=bar
+    #
+    #
+    # @return [Conjur::Annotations]
     def annotations
       @annotations ||= Conjur::Annotations.new(self)
     end
     alias tags annotations
 
-    # Returns all resources (optionally qualified by kind)
-    # visible to the user with given credentials.
+    # @api private
+    # This is documented by Conjur::API#resources.
+    # Returns all resources (optionally qualified by kind) visible to the user with given credentials.
+    #
+    #
     # Options are:
     # - host - authz url,
     # - credentials,
@@ -154,7 +288,15 @@ module Conjur
     end
 
     protected
-    
+
+
+    # Given an Object, return something that responds to each.  In particular,
+    # if `item.respond_to? :each` is true, we return the item, otherwise we put it in
+    # an array.
+    #
+    # @param item [Object] the value we want to each over.
+    # @return [#each]  `item` if item is already eachable, otherwise `[item]`.
+    # @api private
     def eachable(item)
       item.respond_to?(:each) ? item : [ item ]
     end

data/lib/conjur/role.rb

@@ -98,7 +98,7 @@ module Conjur
       false
     end
     
-    def members
+    def members options = {}
       JSON.parse(self["?members"].get(options)).collect do |json|
         RoleGrant.parse_from_json(json, self.options)
       end

data/lib/conjur/standard_methods.rb

@@ -23,6 +23,9 @@ require 'active_support/dependencies/autoload'
 require 'active_support/core_ext'
 
 module Conjur
+  # @api private
+  # This module provides a number of "standard" `REST` helpers,
+  #   to wit, create, list and show.
   module StandardMethods
     
     protected
@@ -43,10 +46,12 @@ module Conjur
     
     def standard_list(host, type, options)
       JSON.parse(RestClient::Resource.new(host, credentials)[type.to_s.pluralize].get(options)).collect do |item|
+        # Note that we don't want to fully_escape the ids below -- methods like #layer, #host, etc don't expect
+        # ids to be escaped, and will escape them again!.
         if item.is_a? String  # lists w/o details are just list of ids 
-          send(type, fully_escape(item)) 
+          send(type,item)
         else                  # list w/ details consists of hashes
-          send(type, fully_escape(item['id'])).tap { |obj| obj.attributes=item }
+          send(type, item['id']).tap { |obj| obj.attributes=item }
         end
       end
     end

data/lib/conjur/variable.rb

@@ -19,12 +19,137 @@
 # CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #
 module Conjur
+
+  # Secrets stored in Conjur are represented by {http://developer.conjur.net/reference/services/directory/variable Variables}.
+  # The code responsible for the actual encryption of variables is open source as part of the
+  # {https://github.com/conjurinc/slosilo Slosilo} library.
+  #
+  # You should not generally create instances of this class directly.  Instead, you can get them from
+  # {Conjur::API} methods such as {Conjur::API#create_variable} and {Conjur::API#variable}.
+  #
+  # Conjur variables store metadata (mime-type and secret kind) with each secret.
+  #
+  # Variables are *versioned*.  Storing secrets in multiple places is a bad security practice, but
+  # overwriting a secret accidentally can create a major problem for development and ops teams.  Conjur
+  # discourages bad security practices while avoiding ops disasters by storing all previous versions of
+  # a secret.
+  #
+  # ### Important
+  # A common pitfall when trying to access older versions of a variable is to assume that `0` is the oldest
+  # version.  In fact, `0` references the *latest* version, while *1* is the oldest.
+  #
+  #
+  # ### Permissions
+  #
+  # * To *read* the value of a `variable`, you must have permission to `'execute'` the variable.
+  # * To *add* a value to a `variable`, you must have permission to `'update'` the variable.
+  # * To *show* metadata associated with a variable, but *not* the value of the secret, you must have `'read'`
+  #     permission on the variable.
+  #
+  #  When you create a secret, the creator role is granted all three of the above permissions.
+  #
+  # @example Get a variable and access its metadata and the latest value
+  #   variable = api.variable 'example'
+  #   puts variable.kind      # "example-secret"
+  #   puts variable.mime_type # "text/plain"
+  #   puts variable.value     # "supahsecret"
+  #
+  # @example Variable permissions
+  #   # use our 'admin' api to create a variable 'permissions-example
+  #   admin_var = admin_api.create_variable 'text/plain', 'example', 'permissions-example'
+  #
+  #   # get a 'view' to it from user 'alice'
+  #   alice_var = alice_api.variable admin_var.id
+  #
+  #   # Initilally, all of the following raise a RestClient::Forbidden exception
+  #   alice_var.attributes
+  #   alice_var.value
+  #   alice_var.add_value 'hi'
+  #
+  #   # Allow alice to see the variables attributes
+  #   admin_var.permit 'read', alice
+  #   alice_var.attributes # OK
+  #
+  #   # Allow alice to update the variable
+  #   admin_var.permit 'update', alice
+  #   alice_var.add_value 'hello'
+  #
+  #   # Notice that alice still can't see the variable's value:
+  #   alice_var.value # raises RestClient::Forbidden
+  #
+  #   # Finally, we let alice execute the variable
+  #   admin_var.permit 'execute', alice
+  #   alice_var.value # 'hello'
+  #
+  # @example Variables are versioned
+  #   var = api.variable 'version-example'
+  #   # Unless you set a variables value when you create it, the variable starts out without a value and version_count
+  #   # is 0.
+  #   var.version_count # => 0
+  #   var.value # raises RestClient::ResourceNotFound (404)
+  #
+  #   # Add a value
+  #   var.add_value 'value 1'
+  #   var.version_count # => 1
+  #   var.value # => 'value 1'
+  #
+  #   # Add another value
+  #   var.add_value 'value 2'
+  #   var.version_count # => 2
+  #
+  #   # 'value' with no argument returns the most recent value
+  #   var.value # => 'value 2'
+  #
+  #   # We can access older versions by their 1 based index:
+  #   var.value 1 # => 'value 1'
+  #   var.value 2 # => 'value 2'
+  #   # Notice that version 0 of a variable is always the most recent:
+  #   var.value 0 # => 'value 2'
+  #
   class Variable < RestClient::Resource
     include ActsAsAsset
-    
-    def kind; attributes['kind']; end
-    def mime_type; attributes['mime_type']; end
-    
+
+    # The kind of secret represented by this variable,  for example, `'postgres-url'` or
+    # `'aws-secret-access-key'`.
+    #
+    # You must have the **`'read'`** permission on a variable to call this method.
+    #
+    # This attribute is only for human consumption, and does not take part in the Conjur permissions
+    # model.
+    #
+    # @note this is **not** the same as the `kind` part of a qualified Conjur id.
+    # @return [String] a string representing the kind of secret.
+    def kind
+      attributes['kind']
+    end
+
+    # The MIME Type of the variable's value.
+    #
+    # You must have the **`'read'`** permission on a variable to call this method.
+    #
+    # This attribute is used by the Conjur services to set a response `Content-Type` header when
+    # returning the value of a variable.  Conjur applies the same MIME Type to all versions of a variable,
+    # so if you plan on accessing the variable in a way that depends on a correct `Content-Type` header
+    # you should make sure to store appropriate data for the mime type in all versions.
+    #
+    # @return [String] a MIME type, such as `'text/plain'` or `'application/octet-stream'`.
+    def mime_type
+      attributes['mime_type']
+    end
+
+    # Add a new value to the variable.
+    #
+    # You must have the **`'update'`** permission on a variable to call this method.
+    #
+    # @example Add a value to a variable
+    #   var = api.variable 'my-secret'
+    #   puts var.version_count     #  1
+    #   puts var.value             #  'supersecret'
+    #   var.add_value "new_secret"
+    #   puts var.version_count     # 2
+    #   puts var.value             # 'new_secret'
+    # @param [String] value the new value to add
+    # @return [void]
     def add_value value
       log do |logger|
         logger << "Adding a value to variable #{id}"
@@ -33,11 +158,48 @@ module Conjur
         self['values'].post value: value
       end
     end
-    
+
+    # Return the number of versions of the variable.
+    #
+    # You must have the **`'read'`** permission on a variable to call this method.
+    #
+    # @example
+    #   var.version_count # => 4
+    #   var.add_value "something new"
+    #   var.version_count # => 5
+    #
+    # @return [Integer] the number of versions
     def version_count
       self.attributes['version_count']
     end
-    
+
+    # Return the version of a variable.
+    #
+    # You must have the **`'execute'`** permission on a variable to call this method.
+    #
+    # When no argument is given, the most recent version is returned.
+    #
+    # When a `version` argument is given, the method returns a version according to the following rules:
+    #  * If `version` is 0, the *most recent* version is returned.
+    #  * If `version` is less than 0 or greater than {#version_count}, a `RestClient::ResourceNotFound` exception
+    #   will be raised.
+    #  * If {#version_count} is 0, a `RestClient::ResourceNotFound` exception will be raised.
+    #  * If `version` is >= 1 and `version` <= {#version_count}, the version at the **1 based** index given by `version`
+    #    will be returned.
+    #
+    # @example Fetch all versions of a variable
+    #   versions = (1..var.version_count).map do |version|
+    #     var.value version
+    #   end
+    #
+    # @example Get the current version of a variable
+    #   # All of these return the same thing:
+    #   var.value
+    #   var.value 0
+    #   var.value var.version_count
+    #
+    # @param [Integer] version the **1 based** version.
+    # @return [String] the value of the variable
     def value(version = nil)
       url = 'value'
       url << "?version=#{version}" if version

data/lib/conjur-api/version.rb

@@ -19,6 +19,6 @@
 
 module Conjur
   class API
-    VERSION = "4.13.0"
+    VERSION = "4.14.0"
   end
 end

data/lib/conjur-api.rb

@@ -0,0 +1,2 @@
+# Just a stub so that require 'conjur-api' works
+require 'conjur/api'

data/spec/api/authn_spec.rb

@@ -1,7 +1,10 @@
 require 'spec_helper'
 require 'cas_rest_client'
+require 'helpers/request_helpers'
 
 describe Conjur::API do
+  include RequestHelpers
+
   let(:host) { 'http://authn.example.com' }
   let(:user) { 'kmitnick' }
   let(:password) { 'sikret' }
@@ -12,7 +15,7 @@ describe Conjur::API do
 
   describe "::login" do
     it "gets /users/login" do
-      expect(RestClient::Request).to receive(:execute).with(
+      expect_request(
         method: :get, url: "http://authn.example.com/users/login", 
         user: user,
         password: password, 
@@ -41,7 +44,7 @@ describe Conjur::API do
 
   describe "::authenticate" do
     it "posts the password and dejsons the result" do
-      expect(RestClient::Request).to receive(:execute).with(
+      expect_request(
         method: :post, url: "http://authn.example.com/users/#{user}/authenticate",
         payload: password, headers: { content_type: 'text/plain' }
       ).and_return '{ "response": "foo"}'
@@ -51,7 +54,7 @@ describe Conjur::API do
   
   describe "::update_password" do
     it "logs in and puts the new password" do
-      expect(RestClient::Request).to receive(:execute).with(
+      expect_request(
         method: :put, 
         url: "http://authn.example.com/users/password",
         user: user,

data/spec/api/groups_spec.rb

@@ -28,7 +28,7 @@ describe Conjur::API, api: :dummy do
 
   describe '#find_groups' do
     it "searches the group by GID" do
-      expect(RestClient::Request).to receive(:execute).with(
+      expect_request(
         method: :get,
         url: "#{core_host}/groups/search?gidnumber=12345",
         headers: credentials[:headers]

data/spec/api/pubkeys_spec.rb

@@ -32,7 +32,7 @@ describe Conjur::API, api: :dummy do
   
   describe "#public_keys" do
     it "GETs /:username" do
-      expect(RestClient::Request).to receive(:execute).with(
+      expect_request(
         url: pubkeys_url_for("bob"),
         method: :get,
         headers: credentials[:headers],
@@ -43,7 +43,7 @@ describe Conjur::API, api: :dummy do
   
   describe "#add_public_key" do
     it "POSTs /:username with the data" do
-      expect(RestClient::Request).to receive(:execute).with(
+      expect_request(
         url: pubkeys_url_for("bob"),
         method: :post,
         headers: credentials[:headers],
@@ -55,7 +55,7 @@ describe Conjur::API, api: :dummy do
   
   describe "#delete_public_key" do
     it "DELETEs /:username/:keyname" do
-      expect(RestClient::Request).to receive(:execute).with(
+      expect_request(
         url: pubkeys_url_for("bob", "bob-key"),
         method: :delete,
         headers: credentials[:headers]
@@ -63,4 +63,4 @@ describe Conjur::API, api: :dummy do
       api.delete_public_key("bob", "bob-key")
     end
   end
-end
+end

data/spec/api/roles_spec.rb

@@ -1,6 +1,8 @@
 require 'spec_helper'
+require 'helpers/request_helpers'
 
 describe Conjur::API, api: :dummy do
+  include RequestHelpers
   subject { api }
 
   describe 'role_graph' do
@@ -34,8 +36,8 @@ describe Conjur::API, api: :dummy do
     end
 
     def expect_request_with_params params={}
-      expect(RestClient::Request).to receive(:execute)
-        .with(headers: credentials[:headers], method: :get, url: role_graph_url_for(roles, options, current_role))
+      expect_request(headers: credentials[:headers], method: :get,
+                     url: role_graph_url_for(roles, options, current_role))
         .and_return(response)
     end
 

data/spec/api/users_spec.rb

@@ -11,7 +11,7 @@ describe Conjur::API, api: :dummy do
   describe 'user#update' do
     let(:userid) { "alice@wonderland" }
     it "PUTs to /users/:id?uidnumber=:uidnumber" do
-      expect(RestClient::Request).to receive(:execute).with(
+      expect_request(
         method: :put,
         url: "#{core_host}/users/#{api.fully_escape(userid)}",
         headers: credentials[:headers],
@@ -28,7 +28,7 @@ describe Conjur::API, api: :dummy do
     let(:search_result)     { ["someuser"].to_json }
     
     it "GETs /users/search with appropriate options, and returns parsed JSON response" do
-      expect(RestClient::Request).to receive(:execute).with(
+      expect_request(
         method: :get,  
         url: "#{core_host}/users/search?uidnumber=12345",
         headers: credentials[:headers]

data/spec/api/variables_spec.rb

@@ -25,7 +25,7 @@ describe Conjur::API, api: :dummy do
     shared_context "Stubbed API" do
       let (:expected_url) { "#{core_host}/variables/values?vars=#{varlist.map {|v| api.fully_escape(v) }.join(",")}"  }
       before {
-        expect(RestClient::Request).to receive(:execute).with(
+        expect_request(
           method: :get,
           url: expected_url,
           headers: credentials[:headers]

data/spec/helpers/errors_matcher.rb

@@ -0,0 +1,34 @@
+require 'rspec/expectations'
+
+RSpec::Matchers.define :raise_one_of do |*exn_classes|
+  supports_block_expectations
+
+  match do |block|
+    expect(&block).to raise_error do |error|
+      @actual_error = error
+      expect(exn_classes).to include error.class
+    end
+  end
+
+  failure_message do
+    "expected #{expected_error}#{given_error}"
+  end
+
+  define_method :expected_error do
+    "one of " + exn_classes.join(', ')
+  end
+
+  def given_error
+    return " but nothing was raised" unless @actual_error
+    backtrace = format_backtrace(@actual_error.backtrace)
+    [
+      ", got #{@actual_error.inspect} with backtrace:",
+      *backtrace
+    ].join("\n  # ")
+  end
+
+  def format_backtrace backtrace
+    formatter = RSpec::Matchers.configuration.backtrace_formatter
+    formatter.format_backtrace(backtrace)
+  end
+end

data/spec/helpers/request_helpers.rb

@@ -0,0 +1,10 @@
+# Helpers for REST client tests
+module RequestHelpers
+  def expect_request details, &block
+    expect(RestClient::Request).to receive(:execute).with(hash_including(details), &block)
+  end
+
+  def allow_request details, &block
+    allow(RestClient::Request).to receive(:execute).with(hash_including(details), &block)
+  end
+end