checkpoint 1.0.3 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 41834a2cddd2e33f15d474ebaa6d7e3212f8ef7c3f25a4af8e8b01f28c38121f
-  data.tar.gz: 1c9204c8b037814616ad05ed652cdca8bc836b0c17f007e29eab83dcb0d637c2
+  metadata.gz: 4a736e9a0fc810c9323dcd7612aee0cb27af02521c59ef448c62c4e5dac3e15c
+  data.tar.gz: b4ab5365b4cae8e5f0040af209bea2c6b9da1e1e19f856d2ae088081188df1b9
 SHA512:
-  metadata.gz: 1f4a80a00753ab9d20fcf4f75af644addafad7e5e487fdc2f2f35992899163a9db2513bb137835fe4c90f1dffb0516076bb2f0fd25762140486dd08a8e7ed4a7
-  data.tar.gz: cd30847154a96d832e26a3c36b5f3ddb6008439bfccfdf5ba65aebfed67ff98c9efb7364c48ebcee3d8e07181c7406c0e34c09d2d70d6f36f3bfc45112593749
+  metadata.gz: b9f4e9ddda32c366b2402333cf8e43f52da41ad4c7d5ec5a77b66ec524d43c9a9ed521f533e28a27c5c8a96a5382f08a3212db1b4ebe38c12d8b6ea3042b9151
+  data.tar.gz: ec1130f73c436b07751d09b7a7f74e9975da9ac2d6fdd29908878150e5053e9e15f9ba8916861b82a784aa8dafc28f0aee2bc1a7fb99046f68868a6f5dc1873d

data/.rubocop.yml

@@ -15,6 +15,9 @@ AllCops:
     - 'bin/**/*'
     - 'vendor/**/*'
 
+Layout/EmptyLineAfterGuardClause:
+  Enabled: false
+
 Layout/MultilineMethodDefinitionBraceLayout:
   EnforcedStyle: same_line
 
@@ -26,5 +29,17 @@ Metrics/BlockLength:
     - '*.gemspec'
   ExcludedMethods: ['describe', 'context', 'xdescribe', 'xcontext']
 
+Layout/SpaceInsideBlockBraces:
+  Enabled: false
+
+Layout/IndentArray:
+  EnforcedStyle: consistent
+
+Style/ClassAndModuleChildren:
+  Enabled: false
+
 Style/StringLiterals:
   Enabled: false
+
+Style/SymbolArray:
+  EnforcedStyle: brackets

data/.travis.yml

@@ -3,3 +3,11 @@ language: ruby
 rvm:
   - 2.4.2
 before_install: gem install bundler -v 1.16.0
+before_script:
+  - curl -L https://codeclimate.com/downloads/test-reporter/test-reporter-latest-linux-amd64 > ./cc-test-reporter
+  - chmod +x ./cc-test-reporter
+  - ./cc-test-reporter before-build
+script:
+  - bin/rspec
+after_script:
+  - ./cc-test-reporter after-build --exit-code $TRAVIS_TEST_RESULT

data/README.md

@@ -1,5 +1,6 @@
 [![Build Status](https://travis-ci.org/mlibrary/checkpoint.svg?branch=master)](https://travis-ci.org/mlibrary/checkpoint?branch=master)
 [![Coverage Status](https://coveralls.io/repos/github/mlibrary/checkpoint/badge.svg?branch=master)](https://coveralls.io/github/mlibrary/checkpoint?branch=master)
+[![Documentation Status](https://readthedocs.org/projects/checkpoint/badge/?version=latest)](https://checkpoint.readthedocs.io/en/latest/?badge=latest)
 
 # Checkpoint
 
@@ -18,6 +19,11 @@ And then execute:
 
     $ bundle
 
+## Documentation
+
+User documentation source is available in the `docs` directory, and in rendered format
+on [readthedocs](https://checkpoint.readthedocs.io/en/latest/).
+
 ## License
 
 Checkpoint is licensed under the BSD-3-Clause license. See [LICENSE.md](LICENSE.md).

data/db/migrations/{1_create_permits.rb → 1_create_grants.rb}

@@ -2,7 +2,7 @@
 
 Sequel.migration do
   change do
-    create_table :permits do
+    create_table :grants do
       primary_key :id
       column :agent_type,       String, size: 100, null: false
       column :agent_id,         String, size: 100, null: false

data/docs/index.rst

@@ -17,12 +17,17 @@ where enterprise, legacy, and new systems must all interoperate.
 Checkpoint emphasizes the use of policies and object-oriented design, giving
 examples from very simple rules through complex group- and role-based scenarios.
 
+Checkpoint does not handle authentication at all. See Keycard_ for a library
+that does so and provides identity attributes that can be used as the basis for
+grants and policies.
+
+
 Table of Contents
 -----------------
 
 .. toctree::
     :maxdepth: 2
 
-    authentication
     policies
 
+.. _Keycard: https://github.com/mlibrary/keycard

data/lib/checkpoint/agent.rb

@@ -5,43 +5,46 @@ require 'checkpoint/agent/token'
 
 module Checkpoint
   # An Agent is an any person or entity that might be granted various
-  # permission, such as a user, group, or institution.
+  # credentials, such as a user, group, or institution.
   #
   # The application objects that an agent represents may be of any type; this
   # is more of an interface or role than a base class. The important concept is
-  # that permits are granted to agents, and that agents may be representative
+  # that credentials are granted to agents, and that agents may be representative
   # of multiple concrete actors, such as any person affiliated with a given
   # institution or any member of a given group.
+  #
+  # In an application, agents will typically be created by the
+  # {Agent::Resolver} registered with an {Checkpoint::Authority}. This keeps
+  # most of the application code decoupled from the Agent type, allowing the
+  # binding to happen in an isolated component. It will also generally not be
+  # required to subclass Agent, since it delegates to the concrete actor in
+  # flexible, well-defined ways, detailed on the individual methods here.
   class Agent
     attr_accessor :actor
 
-    # Create an Agent. This should not be called externally; use {::from} instead.
+    # Create an Agent, wrapping a concrete actor.
+    #
+    # When retrieving the ID or type, we will delegate to the the actor at that
+    # time. See the {#id} and {#type} methods for exact semantics.
     def initialize(actor)
       @actor = actor
     end
 
-    # Default conversion from an actor to an {Agent}.
+    # Convert this object to an Agent.
     #
-    # If the actor implements #to_agent, we will delegate to it. Otherwise,
-    # we check if the actor implements #agent_type or #agent_id; if so, we
-    # use them as the type and id, respectively. If not, we use the actor's
-    # class name as the type and call #id for the id. If the actor does not
-    # implement any of the ways to supply an #id, an error will be raised.
-    #
-    # @return [Agent] the actor converted to an agent
-    def self.from(actor)
-      if actor.respond_to?(:to_agent)
-        actor.to_agent
-      else
-        new(actor)
-      end
+    # For Checkpoint-supplied Agents, this is an identity operation,
+    # but it allows consistent handling of the built-in types and
+    # application-supplied types that will either implement this interface or
+    # convert themselves to a built-in type. This removes the requirement to
+    # extend Checkpoint types or bind to a specific conversion method.
+    def to_agent
+      self
     end
 
-    # Get the captive actor's type.
+    # Get the wrapped actor's type.
     #
-    # If the entity implements `#to_agent`, we will call that and use the
-    # returned agent's type. If not, but it implements `#agent_type`, we
-    # will use that. Otherwise, we use the actors's class name.
+    # If the actor implements `#agent_type`, we will return that. Otherwise,
+    # we use the actors's class name.
     #
     # @return [String] the name of the actor's type after calling `#to_s` on it.
     def type
@@ -52,14 +55,13 @@ module Checkpoint
       end.to_s
     end
 
-    # Get the captive actor's id.
+    # Get the wrapped actor's ID.
     #
-    # If the entity implements `#to_agent`, we will call that and use the
-    # returned agent's id. If not, but it implements `#agent_id`, we
-    # will use that. Otherwise, we call `#id`. If the the actor does not
-    # implement any of these methods, we raise a {NoIdentifierError}.
+    # If the actor implements `#agent_id`, we will call it and return that
+    # value. Otherwise, we call `#id`. If the the actor does not implement
+    # either of these methods, we raise a {NoIdentifierError}.
     #
-    # @return [String] the name of the actor's type after calling `#to_s` on it.
+    # @return [String] the actor's ID after calling `#to_s` on it.
     def id
       if actor.respond_to?(:agent_id)
         actor.agent_id
@@ -82,12 +84,11 @@ module Checkpoint
       other.is_a?(Agent) && actor.eql?(other.actor)
     end
 
-    # Check whether two Agents refer to the same concrete actor.
+    # Check whether two Agents refer to the same concrete actor by type and id.
     # @param other [Agent] Another Agent to compare with
-    # @return [Boolean] true when the other Agent's actor is the same as
-    #   determined by comparing them with `==`.
+    # @return [Boolean] true when the other Agent's type and id are equal.
     def ==(other)
-      other.is_a?(Agent) && actor == other.actor
+      other.is_a?(Agent) && type == other.type && id == other.id
     end
   end
 end

data/lib/checkpoint/agent/resolver.rb

@@ -2,16 +2,24 @@
 
 module Checkpoint
   class Agent
-    # An Agent Resolver takes a concrete user (or other account/actor) object and
-    # resolves it into the set of {Agent}s that the user represents. This has the
-    # effect of allowing a Permit to any of those agents to take effect when
-    # authorizing an action by this user.
+    # An Agent Resolver is the bridge between a concrete user (or other
+    # account/actor) and {Agent}s that the user represents.
     #
-    # This implementation only resolves the user into one agent, using the default
-    # conversion.
+    # There are two basic operations:
     #
-    # To extend the set of {Agent}s resolved, implement a specialized version
-    # that returns an array of agents from #resolve. This customized
+    # - Conversion maps an actor to a single Agent
+    # - Expansion maps an actor to all of the Agents it represents
+    #
+    # These allow credentials to be granted, matched, or revoked with the
+    # appropriate semantics, depending on the operation. In general, a Grant
+    # is given to or revoked from a single Agent, while matching is applied
+    # to all Agents the actor represents.
+    #
+    # This implementation does not implement any expansion semantics other
+    # than to convert the actor into an Agent and return it as a list.
+    #
+    # To extend the set of {Agent}s resolved, implement a subclass
+    # that returns an array of agents from #expand. This customized
     # implementation would typically be injected to an application-wide
     # {Checkpoint::Authority}, rather than being used directly.
     #
@@ -19,14 +27,36 @@ module Checkpoint
     # the user is a member of, or IP address-based geographical regions or
     # organizational affiliations.
     class Resolver
-      # Resolve an actor to a list of agents it represents.
+      # Expand an actor to a list of Agents it represents.
+      #
+      # This implementation simply converts the actor and wraps the resulting
+      # Agent in an array.
+      #
+      # If extending or overriding, you will likely want to call super or
+      # {#convert} on the concrete actor to make sure that the most specific
+      # Agent is included. It is acceptable to return subclasses of Agent,
+      # though that is generally unnecessary because of its design of
+      # delegating to actor methods.
+      #
+      # @return [Agent] an array of agents for this actor
+      def expand(actor)
+        [convert(actor)]
+      end
+
+      # Default conversion from an actor to an {Agent}.
+      #
+      # If the actor implements #to_agent, we will delegate to it. Otherwise,
+      # we will instantiate an {Agent} with the supplied actor.
+      #
+      # Override this method to use a different or conditional Agent type.
       #
-      # If extending or overriding, you will most likely want to either call
-      # super, or use the default conversion directly.
-      # @return [[Checkpoint::Agent]] an array of agents for this actor
-      # @see Checkpoint::Agent.from
-      def resolve(actor)
-        [Checkpoint::Agent.from(actor)]
+      # @return [Agent] the actor converted to an agent
+      def convert(actor)
+        if actor.respond_to?(:to_agent)
+          actor.to_agent
+        else
+          Agent.new(actor)
+        end
       end
     end
   end

data/lib/checkpoint/agent/token.rb

@@ -3,9 +3,9 @@
 module Checkpoint
   class Agent
     # An Agent::Token is an identifier object for an Agent. It
-    # includes a type and an identifier. A {Permit} can be granted for a Token.
+    # includes a type and an identifier. A {Grant} can be created for a Token.
     # Concrete actors are resolved into a number of agents, and those agents'
-    # tokens will be checked for matching permits.
+    # tokens will be checked for matching grants.
     class Token
       attr_reader :type, :id
 
@@ -34,7 +34,7 @@ module Checkpoint
         self
       end
 
-      # @return [String] a token string suitable for granting or matching permits for this agent
+      # @return [String] a token string suitable for granting or matching grants for this agent
       def to_s
         "#{type}:#{id}"
       end
@@ -45,6 +45,11 @@ module Checkpoint
         other.is_a?(Token) && type == other.type && id == other.id
       end
 
+      # @return [Integer] hash code based on to_s
+      def hash
+        to_s.hash
+      end
+
       alias == eql?
       alias inspect uri
     end

data/lib/checkpoint/authority.rb

@@ -3,36 +3,52 @@
 require 'checkpoint/agent/resolver'
 require 'checkpoint/credential/resolver'
 require 'checkpoint/resource/resolver'
-require 'checkpoint/permits'
+require 'checkpoint/grants'
 
 module Checkpoint
   # An Authority is the central point of contact for authorization questions in
-  # Checkpoint. It checks whether there are permits that would allow a given
+  # Checkpoint. It checks whether there are grants that would allow a given
   # action to be taken.
   class Authority
     def initialize(
       agent_resolver: Agent::Resolver.new,
       credential_resolver: Credential::Resolver.new,
       resource_resolver: Resource::Resolver.new,
-      permits: Permits.new)
+      grants: Grants.new)
 
       @agent_resolver      = agent_resolver
       @credential_resolver = credential_resolver
       @resource_resolver   = resource_resolver
-      @permits             = permits
+      @grants              = grants
     end
 
-    def permits?(agent, credential, resource)
+    # Check whether there are any matching grants that would allow this actor
+    # to take the action on the target entity.
+    #
+    # The parameters are generally intended to be the most convenient forms for
+    # the application. For example, user and resource model objects would be
+    # typical in a Rails application, for the actor and entity, respectively.
+    # Using a symbol for a named action is typical.
+    #
+    # Each of these will be converted and expanded by the corresponding
+    # resolver to sets of {Agent}s, {Credential}s, and {Resource}s. In the case
+    # where you already have an Agent, Credential, or Resource, it can be
+    # passed; the expectation is that those types have an identity conversion.
+    #
+    # @param actor [Object|Agent] The person/account taking the action.
+    # @param action [Symbol|String|Credential] The action to authorize or
+    #   Credential to check for.
+    # @param entity [Object|Resource] The entity/resource to be acted upon.
+    def permits?(actor, action, entity)
       # Conceptually equivalent to:
-      #   can?(agent, action, target)
-      #   can?(current_user, 'edit', @listing)
+      #   can?(current_user, :edit, @listing)
 
       #  user   => agent tokens
       #  action => credential tokens
       #  target => resource tokens
 
-      # Permit.where(agent: agents, credential: credentials, resource: resources)
-      # SELECT * FROM permits
+      # Grant.where(agent: agents, credential: credentials, resource: resources)
+      # SELECT * FROM grants
       # WHERE agent IN('user:gkostin', 'account-type:umich', 'affiliation:lib-staff')
       # AND credential IN('permission:edit', 'role:editor')
       # AND resource IN('listing:17', 'type:listing')
@@ -46,13 +62,109 @@ module Checkpoint
       #        ^^^                       ^^^^              ^^^^
       #   if current_user has at least one row in each of of these columns,
       #   they have been "granted permission"
-      permits.for(
-        agent_resolver.resolve(agent),
-        credential_resolver.resolve(credential),
-        resource_resolver.resolve(resource)
+      grants.for(
+        agent_resolver.expand(actor),
+        credential_resolver.expand(action),
+        resource_resolver.expand(entity)
       ).any?
     end
 
+    # Find agents who have grants to take an action on an entity.
+    #
+    # The action and entity are expanded for matching more general grants.
+    #
+    # @return [Array<Agent::Token>] The distinct set of tokens for agents permitted to
+    #   take the given action on the given entity
+    def who(action, entity)
+      credentials = credential_resolver.expand(action)
+      resources = resource_resolver.expand(entity)
+
+      grants.who(credentials, resources).map do |grant|
+        Agent::Token.new(grant.agent_type, grant.agent_id)
+      end.uniq
+    end
+
+    # Find credentials granted to an actor on an entity.
+    #
+    # The actor and entity are expanded for matching more general grants.
+    #
+    # @return [Array<Credential::Token>] The distinct set of tokens for credentials
+    #   that the actor is granted on the entity
+    def what(actor, entity)
+      agents = agent_resolver.expand(actor)
+      resources = resource_resolver.expand(entity)
+
+      grants.what(agents, resources).map do |grant|
+        Credential::Token.new(grant.credential_type, grant.credential_id)
+      end.uniq
+    end
+
+    # Find resources on which the actor is permitted to take the given action.
+    #
+    # The actor and action are expanded for matching more general grants.
+    #
+    # @return [Array<Resource::Token>] The distinct set of tokens for resources
+    #   on which the actor is permitted to take the given action
+    def which(actor, action)
+      agents = agent_resolver.expand(actor)
+      credentials = credential_resolver.expand(action)
+
+      grants.which(agents, credentials).map do |grant|
+        Resource::Token.new(grant.resource_type, grant.resource_id)
+      end.uniq
+    end
+
+    # Grant a single credential to a specific actor on an entity.
+    #
+    # The parameters are converted to Agent, Credential, and Resource types,
+    # but not expanded. This allows very specific grants to be made. The
+    # default conversion of a symbol or string as the action is to a
+    # {Credential::Permission} of the same name.
+    #
+    # If you want to use more general grants (for example, for an account type
+    # rather than for a given user), you should pass a more general Agent or an
+    # object that will be converted to one. Another example would be using a
+    # wildcard Resource as the entity to grant the credential for all objects
+    # of some given type.
+    #
+    # @param actor [Object|Agent] The actor to whom the grant should be made.
+    # @param action [Symbol|String|Credential] The action or Credential to grant.
+    # @param entity [Object|Resource] The entity or Resource to which the
+    #   grant will apply.
+    # @return [Boolean] True if the grant was made; false if it failed.
+    def grant!(actor, action, entity)
+      grant = grants.grant!(
+        agent_resolver.convert(actor),
+        credential_resolver.convert(action),
+        resource_resolver.convert(entity)
+      )
+
+      !grant.nil?
+    end
+
+    # Revoke a credential from a specific actor on an entity.
+    #
+    # Like {#permit!}, the parameters are converted to Agent, Credential, and
+    # Resource types, but not expanded. This means that specific grants can be
+    # revoked without revoking more general ones. For example, if a user was
+    # granted read permission on an object, and then granted the same credential
+    # on all objects of that type, the more specific grant could be revoked
+    # individually.
+    #
+    # @param actor [Object|Agent] The actor from whom the grant should be revoked.
+    # @param action [Symbol|String|Credential] The action or Credential to revoke.
+    # @param entity [Object|Resource] The entity or Resource upon which the
+    # @return [Boolean] True if any grants were revoked; false if none were revoked.
+    def revoke!(actor, action, entity)
+      revoked = grants.revoke!(
+        agent_resolver.convert(actor),
+        credential_resolver.convert(action),
+        resource_resolver.convert(entity)
+      )
+
+      revoked.positive?
+    end
+
     # Dummy authority that rejects everything
     class RejectAll
       def permits?(*)
@@ -62,6 +174,6 @@ module Checkpoint
 
     private
 
-    attr_reader :agent_resolver, :credential_resolver, :resource_resolver, :permits
+    attr_reader :agent_resolver, :credential_resolver, :resource_resolver, :grants
   end
 end