checkpoint 1.0.3 → 1.1.0

data/lib/checkpoint/resource/resolver.rb

@@ -2,13 +2,20 @@
 
 module Checkpoint
   class Resource
-    # A Resource Resolver takes a concrete object (like a model instance) and
-    # resolves it into all {Resource}s for which a grant would allow an action.
+    # A Resource Resolver is the bridge between concrete entity objects (like
+    # model instances) and {Resource}s that the represent them.
+    #
+    # There are two basic operations:
+    #
+    # - Conversion maps an entity to a single Resource.
+    # - Expansion maps an entity to all Resources for which a grant would allow
+    #   an action.
+    #
     # For example, this can be used to grant a credential on all items of a given
     # model class or to implement cascading permissions when all credentials for
     # a container should apply to the contained objects.
     #
-    # This base implementation resolves to three agents: one for the entity
+    # This base implementation expands to three resources: one for the entity
     # itself, one for all entities of its type, and one for all entities of any
     # type. This provides a convenient and familiar construct, where a broader
     # grant (say, at the type level, or for "everything") implies a grant at
@@ -32,14 +39,14 @@ module Checkpoint
     # there is even more complexity, Checkpoint allows its fundamental
     # semantics to be extended by implementing a custom resolver.
     class Resolver
-      # Resolve an application entity into a set of Resources for which a grant
+      # Expand an application entity into a set of Resources for which a grant
       # would allow access.
       #
-      # The entity will be converted to a Resource with {Resource::from} and
-      # {Resource::AllOfType::from}. That is, the Resolver does a
-      # straightforward expansion, not applying any of its own conversion
-      # semantics. The special {Resource::all} resource is also included to
-      # support zone-wide grants.
+      # The entity will be expanded to three Resources:
+      #
+      # 1. A Resource for the specific entity, by conversion
+      # 2. A {Resource::AllOfType} for the type of the entity, as by conversion
+      # 3. A special {Resource::AllOfAnyType} to support zone-wide grants
       #
       # As an example, permission to download high quality versions of media
       # assets might be granted to a given user system wide (that is, for the
@@ -61,8 +68,24 @@ module Checkpoint
       # this approach may be more convenient than, for example, delegating to a
       # specific policy in the same way from multiple sections of the
       # application.
-      def resolve(target)
-        [Resource.from(target), Resource::AllOfType.from(target), Resource.all]
+      def expand(entity)
+        [convert(entity), convert(entity).all_of_type, Resource.all]
+      end
+
+      # Default conversion from an entity to a {Resource}.
+      #
+      # If the entity implements #to_resource, we will delegate to it. Otherwise,
+      # we will instantiate a {Resource} with the supplied entity.
+      #
+      # Override this method to use a different or conditional Resource type.
+      #
+      # @return [Resource] the entity converted to a resource
+      def convert(entity)
+        if entity.respond_to?(:to_resource)
+          entity.to_resource
+        else
+          Resource.new(entity)
+        end
       end
     end
   end

data/lib/checkpoint/resource/token.rb

@@ -5,9 +5,9 @@ require 'checkpoint/resource/resolver'
 module Checkpoint
   class Resource
     # A Resource::Token is an identifier object for a Resource. It includes a
-    # type and an identifier. A {Permit} can be granted for a Token. Concrete
+    # type and an identifier. A {Grant} can be created for a Token. Concrete
     # entities are resolved into a number of resources, and those resources'
-    # tokens will be checked for matching permits.
+    # tokens will be checked for matching grants.
     class Token
       attr_reader :type, :id
 
@@ -58,6 +58,11 @@ module Checkpoint
         other.is_a?(Resource::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/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Checkpoint
-  VERSION = "1.0.3"
+  VERSION = "1.1.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: checkpoint
 version: !ruby/object:Gem::Version
-  version: 1.0.3
+  version: 1.1.0
 platform: ruby
 authors:
 - Noah Botimer
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-07-19 00:00:00.000000000 Z
+date: 2018-11-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ettin
@@ -217,11 +217,10 @@ files:
 - bin/yard
 - bin/yardoc
 - checkpoint.gemspec
-- db/migrations/1_create_permits.rb
+- db/migrations/1_create_grants.rb
 - docs/Makefile
 - docs/_static/.gitkeep
 - docs/_templates/.gitkeep
-- docs/authentication.rst
 - docs/conf.py
 - docs/index.rst
 - docs/policies.rst
@@ -235,11 +234,17 @@ files:
 - lib/checkpoint/credential/permission.rb
 - lib/checkpoint/credential/resolver.rb
 - lib/checkpoint/credential/role.rb
+- lib/checkpoint/credential/role_map_resolver.rb
 - lib/checkpoint/credential/token.rb
 - lib/checkpoint/db.rb
-- lib/checkpoint/db/permit.rb
-- lib/checkpoint/permission_mapper.rb
-- lib/checkpoint/permits.rb
+- lib/checkpoint/db/cartesian_select.rb
+- lib/checkpoint/db/grant.rb
+- lib/checkpoint/db/params.rb
+- lib/checkpoint/db/query/ac.rb
+- lib/checkpoint/db/query/acr.rb
+- lib/checkpoint/db/query/ar.rb
+- lib/checkpoint/db/query/cr.rb
+- lib/checkpoint/grants.rb
 - lib/checkpoint/query.rb
 - lib/checkpoint/query/action_permitted.rb
 - lib/checkpoint/query/role_granted.rb

data/docs/authentication.rst

@@ -1,18 +0,0 @@
-Identity and Authentication
-===========================
-
-Users can be identified in any number of ways and carry with them various
-attributes that determine the entirety of "who they are". Our typical needs
-include identifying a person by username or email address, and building a
-profile of attributes such as geographical region (as determined by IP address),
-or University status (student, staff, etc.). The identifiers and attributes are
-intrinsic to the user and do not, by themselves, grant any permissions within
-an application. Likewise, these attributes cannot be granted within an
-application, only inspected.
-
-A&E will continue to provide the identity and attributes of users. The
-specifics of whether this will be implemented with environment variables,
-HTTP headers, SAML, or other means is to be determined. An application is
-not expected to implement its own login process except to the degree that
-it can recognize the required authentication information provided to it.
-

data/lib/checkpoint/permission_mapper.rb

@@ -1,29 +0,0 @@
-# frozen_string_literal: true
-
-module Checkpoint
-  # A PermissionMapper translates an action into a set of permissions and roles
-  # that would allow it. Commonly, the actions and permissions will share names
-  # for convenience and consistency, but this is not a requirement.
-  #
-  # For example, it may make sense in an application that one permission
-  # implies another, so an action may have multiple permissions that would
-  # allow it. In another application, it may be more convenient and
-  # understandable for users to have separate roles encapsulate that concept
-  # (such as an editor role having all of the permissions of a reader role and
-  # more).
-  #
-  # As a separate example, it may be more appropriate to implement permission
-  # inheritance directly in policy code (as by delegating to another check or
-  # policy), relying on the matching action and permission names with no roles
-  # resolved, as given by the default PermissionMapper. Checkpoint does not
-  # take an absolute position on the best pattern for a given application.
-  class PermissionMapper
-    def permissions_for(action)
-      [action.to_sym]
-    end
-
-    def roles_granting(_action)
-      []
-    end
-  end
-end

data/lib/checkpoint/permits.rb

@@ -1,133 +0,0 @@
-# frozen_string_literal: true
-
-# Note: we do not require db/permit because Sequel requires the connection
-# to be set up before defining the model classes. The arrangment here
-# assumes that DB.initialize! will have been called if the default model
-# is to be used. In tests, that is done by spec/sequel_helper.rb. In an
-# application, there should be an initializer that reads whatever appropriate
-# configuration and does the initialization.
-
-require 'checkpoint/db'
-
-module Checkpoint
-  # The repository of permits -- a simple wrapper for the Sequel Datastore / permits table.
-  class Permits
-    def initialize(permits: Checkpoint::DB::Permit)
-      @permits = permits
-    end
-
-    def for(agents, credentials, resources)
-      where(agents, credentials, resources).select
-    end
-
-    def any?(agents, credentials, resources)
-      where(agents, credentials, resources).first != nil
-    end
-
-    private
-
-    def where(agents, credentials, resources)
-      Query.new(agents, credentials, resources, scope: permits)
-    end
-
-    attr_reader :permits
-
-    # A query object based on agents, credentials, and resources.
-    #
-    # This is a helper to capture a set of agents, credentials, and resources,
-    # and manage assembly of placeholder variables and binding expressions in
-    # the way Sequel expects them. It can take single items or arrays and
-    # converts them all to their tokens for query purposes.
-    class Query
-      attr_reader :agents, :credentials, :resources, :scope
-
-      def initialize(agents, credentials, resources, scope: Checkpoint::DB::Permit)
-        @agents      = tokenize(agents)
-        @credentials = tokenize(credentials)
-        @resources   = tokenize(resources)
-        @scope       = scope
-      end
-
-      def query
-        scope.where(conditions)
-      end
-
-      def select
-        exec(:select)
-      end
-
-      def first
-        exec(:first)
-      end
-
-      def conditions
-        {
-          agent_token:      agent_params.placeholders,
-          credential_token: credential_params.placeholders,
-          resource_token:   resource_params.placeholders,
-          zone_id: :$zone_id
-        }
-      end
-
-      def parameters
-        (agent_params.values +
-         credential_params.values +
-         resource_params.values +
-         [[:zone_id, DB::Permit.default_zone]]).to_h
-      end
-
-      def agent_params
-        Params.new(agents, 'at')
-      end
-
-      def credential_params
-        Params.new(credentials, 'ct')
-      end
-
-      def resource_params
-        Params.new(resources, 'rt')
-      end
-
-      private
-
-      def exec(mode)
-        query.call(mode, parameters)
-      end
-
-      def tokenize(collection)
-        [collection].flatten.map(&:token)
-      end
-    end
-
-    # A helper for building placeholder variable names from items in a list and
-    # providing a corresponding hash of values. A prefix with some mnemonic
-    # corresponding to the column is recommended. For example, if the column is
-    # `agent_token`, using the prefix `at` will yield `$at_0`, `$at_1`, etc. for
-    # an IN clause.
-    class Params
-      attr_reader :items, :prefix
-
-      def initialize(items, prefix)
-        @items  = [items].flatten
-        @prefix = prefix
-      end
-
-      def placeholders
-        0.upto(items.size - 1).map do |i|
-          :"$#{prefix}_#{i}"
-        end
-      end
-
-      def values
-        items.map.with_index do |item, i|
-          value = if item.respond_to?(:sql_value)
-                    item.sql_value
-                  else
-                    item.to_s
-                  end
-          [:"#{prefix}_#{i}", value]
-        end
-      end
-    end
-  end
-end