checkpoint 1.0.3 → 1.1.0

data/lib/checkpoint/credential.rb

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
 require 'checkpoint/credential/resolver'
+require 'checkpoint/credential/role_map_resolver'
 require 'checkpoint/credential/role'
 require 'checkpoint/credential/permission'
 require 'checkpoint/credential/token'
-require 'checkpoint/permission_mapper'
 
 module Checkpoint
   # A Credential is the permission to take a particular action, or any
@@ -13,8 +13,8 @@ module Checkpoint
   #
   # Credentials are abstract; that is, they are not attached to a particular
   # actor or resource to be acted upon. A credential can be granted to an
-  # {Agent}, optionally applying to a particular resource, by way of a Permit.
-  # In other words, a credential can be likened to a class, while a permit can
+  # {Agent}, optionally applying to a particular resource, by way of a Grant.
+  # In other words, a credential can be likened to a class, while a grant can
   # be likened to an instance of that class, bound to a given agent and
   # possibly bound to a {Resource}.
   class Credential
@@ -47,23 +47,36 @@ module Checkpoint
     # This is an extension mechanism for application authors needing to
     # implement hierarchical or virtual credentials and wanting to do so in
     # an object-oriented way. The default implementation is to simply return
-    # the credential itself in an array but, for example, an a custom
+    # the credential itself in an array but, for example, a custom
     # permission type could provide for aliasing by including itself and
     # another instance for the synonym. Another example is modeling permissions
     # granted by particular roles; this might be static, as defined in the
     # source files, or dynamic, as impacted by configuration or runtime data.
     #
-    # As an alternative, these rules could be implemented under a
-    # {PermissionMapper} in an application that prefers to model its credentials
-    # as strings or symbols, rather than more specialized objects.
+    # As an alternative, these rules could be implemented by using the rather
+    # straightforward {RoleMapResolver} or a custom {Credential::Resolver}.
     #
-    # @see Checkpoint::PermissionMapper
     # @return [Array<Credential>] the expanded list of credentials that would
     #   grant this one
     def granted_by
       [self]
     end
 
+    # Convert this object to a Credential.
+    #
+    # For Checkpoint-supplied Credential types, 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 and, in combination with `#granted_by`, allows
+    # design of an object-oriented permission model that can interoperate
+    # seamlessly with the Checkpoint constructs.
+    #
+    # @return [Credential] this credential
+    def to_credential
+      self
+    end
+
     # @return [Token] a token for this credential
     def token
       @token ||= Token.new(type, id)

data/lib/checkpoint/credential/permission.rb

@@ -11,11 +11,12 @@ module Checkpoint
     # action is permitted for a user. However, Permission could be extended or
     # modified to implement aliasing or hierarchy, for example.
     #
-    # More likely, though, is advising the resolution of Permissions through a
-    # {Checkpoint::PermissionMapper} or implementing a custom
-    # {Checkpoint::Credential::Resolver}. Subclassing or monkey-patching Permission
-    # should only be necessary if the application needs to extend the actual
-    # behavior of the Permission objects, rather than just which ones are resolved.
+    # More likely, though, is advising the resolution of Permissions with a
+    # role map and {Checkpoint::Credential::RoleMapResolver} or implementing a
+    # custom {Checkpoint::Credential::Resolver}. Subclassing or monkey-patching
+    # Permission should only be necessary if the application needs to extend
+    # the actual behavior of the Permission objects, rather than just which
+    # ones are resolved.
     class Permission < Credential
       TYPE = 'permission'
 

data/lib/checkpoint/credential/resolver.rb

@@ -1,87 +1,88 @@
 # frozen_string_literal: true
 
-require 'checkpoint/permission_mapper'
-
 module Checkpoint
   class Credential
-    # A Credential Resolver takes a concrete action name and resolves it into any
-    # {Credential}s that would permit the action.
+    # A Credential Resolver is the bridge between application action names
+    # and {Credential}s that would permit those actions.
     #
     # Checkpoint makes no particular demand on the credential model for an
-    # application, but offers a useful default implementation supporting
+    # application, but offers two useful default implementations supporting
     # permissions and roles. There are no default rules in Checkpoint as to which
     # permissions or roles exist and, therefore, it has no default mapping of
     # roles to permissions.
     #
-    # This default resolver can be advised about an application model using roles
-    # and permissions customized by using one or both of two extension points:
+    # This default resolver is useful for applications that only deal with
+    # permissions or model credentials in an object-oriented way (explained
+    # below). The {RoleMapResolver} supports a basic mapping pattern between
+    # named roles and permissions those roles would grant.
+    #
+    # More sophisticated mappings, such as those reading a configuration file
+    # or with dynamic roles and permissions defined in a database, can be
+    # implemented in a custom resolver.
     #
-    #   1. Supplying a {PermissionMapper} gives a way to map action names to any
-    #      "larger" permissions (e.g., "manage" being a shorthand for all CRUD
-    #      operations on a Resource type) or roles that would grant a given
-    #      permission. This affords a rather straightforward mapping of strings
-    #      or symbols, short of building customized Credential types.
+    # Using this default resolver, it is possible to implement your own
+    # {Credential} types to model an application's credentials in an
+    # object-oriented way. If the resolver receives a {Credential} (rather than
+    # a string or symbol), it will call `#granted_by` on it to expand it. The
+    # Credential should be sure to include itself in the array it returns
+    # unless it is virtual and should never be considered as granted directly.
     #
-    #   2. Implementing your own {Credential} types gives a way to model an
-    #      application's credentials in an object-oriented way. If the resolver
-    #      receives a {Credential} (rather than a string or symbol), it will call
-    #      `#granted_by` on it to expand it. The Credential should be sure to
-    #      include itself in the array it returns unless it is virtual and should
-    #      never be considered as granted directly.
+    # An example of this type of modeling could be implementing named action
+    # classes that have information like labels and descriptions for display
+    # purposes in a permission management interface or messages when a user
+    # does not have sufficient permission to take that action. There might also
+    # be some inheritance such that granting something like "manage" would be a
+    # shorthand for all CRUD operations on a Resource type.
     #
+    # Another example of a custom Credential type could be a license that would
+    # be an application object in its own right, carrying information such as
+    # the licensor and expiration date. By implementing the Credential
+    # interface, a license could be granted directly with the Checkpoint
+    # {Authority} and enforced at the policies.
+    #
+    # @see {RoleMapResolver}
     class Resolver
-      def initialize(permission_mapper: PermissionMapper.new)
-        @permission_mapper = permission_mapper
-      end
-
-      # Resolve an action into all {Credential}s that would permit it.
+      # Expand an action into all {Credential}s that would permit it.
       #
-      # When supplied a string or symbol, we call `permissions_for` and
-      # `roles_granting` on the {PermissionMapper} creating a {Permission} or
-      # {Role} for every result, returning them all in an array.
+      # Expansion first converts the action to a Credential, and then calls
+      # `#granted_by` on it.
       #
-      # When supplied a Credential, we call `#granted_by` on it and bypass the
-      # PermissionMapper. More precisely, we only check that the object responds to
-      # `#granted_by?`, but it would generally be a Credential subclass. The
-      # Credential should return an array, but we ensure the return type by
-      # wrapping and flattening.
+      # Note that the parameter name is `action`, though it can accept a
+      # Credential. This is to promote the most common and recommended model:
+      # authorizing based on named application actions. However, the
+      # polymorphic and hierarchical nature of credentials means that there can
+      # be cases where expanding something like a {Role} is intentional. As an
+      # example, an administrative interface for managing roles granted to
+      # users might need to expand the roles to show inheritance, rather than
+      # checking whether a given user would be permitted to take some action.
       #
-      # Note that the parameter name to `resolve` is `action`. This isn't a perfect
-      # name, but credentials are polymorphic such a way that there really is no
-      # better application-side term (cf. actor -> Agent, entity -> Resource). It
-      # would be something like `action_or_role`, `permission_or_role`, or a generic
-      # `credential`. Part of the naming intent here was to distinguish from the
-      # action and the ability to perform it. This inheritance relationship
-      # permissions and roles are both credential types is a distinguishing feature
-      # of Checkpoint, as opposed to models that treat permissions and roles as
-      # distinct concepts that must be granted in very different ways. A better
-      # name for this parameter may emerge over time, but it seems unlikely. The
-      # name `action` was selected because the most common and appropriate concrete
-      # thing to look for is a permission to take a named application action.
+      # @param action [String|Symbol|Credential] the action name or Credential
+      #   to expand
+      # @return [Array<Credential>] the set of Credentials, any of which would
+      #   allow the action
+      def expand(action)
+        convert(action).granted_by
+      end
+
+      # Convert an action to a Credential.
+      #
+      # This conversion is basic, assuming that actions should convert directly
+      # to permissions. For example, if `:read` or `'read'` is passed, a
+      # {Credential::Permission} with id `'read'` is returned. If the action
+      # implements `#to_credential`, that will be called and returned; the
+      # object must either extend {Credential} or implement its public methods.
       #
       # @param action [String|Symbol|Credential] the action name or Credential
-      #   to expand into any Credential that would grant it.
-      def resolve(action)
-        if action.respond_to?(:granted_by)
-          [action.granted_by].flatten
+      #   to convert
+      # @return Credential a Credential object that would specifically allow
+      #   the action supplied
+      def convert(action)
+        if action.respond_to?(:to_credential)
+          action.to_credential
         else
-          permissions_for(action) + roles_granting(action)
+          Permission.new(action)
         end
       end
-
-      private
-
-      def permissions_for(action)
-        perms = permission_mapper.permissions_for(action)
-        perms.map { |perm| Credential::Permission.new(perm) }
-      end
-
-      def roles_granting(action)
-        roles = permission_mapper.roles_granting(action)
-        roles.map { |role| Credential::Role.new(role) }
-      end
-
-      attr_reader :permission_mapper
     end
   end
 end

data/lib/checkpoint/credential/role.rb

@@ -8,10 +8,9 @@ module Checkpoint
     # The most common use from outside Checkpoint will be by way of
     # {Checkpoint::Query::RoleGranted}, which will ask whether a given named
     # role is granted for a user. However, Role could be extended or modified
-    # to implement aliasing or hierarchy, for example
+    # to implement aliasing or hierarchy, for example.
     #
-    # More likely, though, is advising the resolution of Roles through a
-    # {Checkpoint::PermissionMapper} or implementing a custom
+    # More likely, though, is implementing a custom
     # {Checkpoint::Credential::Resolver}. Subclassing or monkey-patching Role
     # should only be necessary if the application needs to extend the actual
     # behavior of the Role objects, rather than just which ones are resolved.

data/lib/checkpoint/credential/role_map_resolver.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+class Checkpoint::Credential
+  # Credential Resolver that supports a basic role map model.
+  #
+  # The role map should be a hash containing all of the roles and each key
+  # should be an array of the permissions that role would grant. For example:
+  #
+  # ```
+  # {
+  #   admin: [:read, :create, :edit, :delete],
+  #   guest: [:read]
+  # }
+  # ```
+  #
+  # Note that this example is not a recommendation of how to model an
+  # application's permissions; it is only to show the expected format of the
+  # hash and that there is no inheritance of permissions between roles (:read
+  # is included in both roles). Any more sophisticated rules should be
+  # implemented in a custom Resolver, or custom Credential types.
+  #
+  # Actions convert to Permissions according to the base {Resolver} and expand
+  # according to the map.
+  class RoleMapResolver < Resolver
+    attr_reader :role_map, :permission_map
+
+    def initialize(role_map)
+      @role_map = role_map
+      @permission_map = invert_role_map
+    end
+
+    # Expand an action name into the matching permission and any roles that
+    # would grant it.
+    #
+    # @return [Array<Credential>]
+    def expand(action)
+      permissions_for(action) + roles_granting(action)
+    end
+
+    private
+
+    def permissions_for(action)
+      [Permission.new(action)]
+    end
+
+    def roles_granting(action)
+      if permission_map.key?(action)
+        permission_map[action].map {|role| Role.new(role) }
+      else
+        []
+      end
+    end
+
+    def invert_role_map
+      {}.tap do |hash|
+        role_map.each do |role, permissions|
+          permissions.each do |permission|
+            hash[permission] ||= []
+            hash[permission] << role
+          end
+        end
+      end
+    end
+  end
+end

data/lib/checkpoint/credential/token.rb

@@ -3,9 +3,9 @@
 module Checkpoint
   class Credential
     # A Credential::Token is an identifier object for a Credential. It includes
-    # a type and an identifier. A {Permit} can be granted for a Token. Concrete
+    # a type and an identifier. A {Grant} can be created for a Token. Concrete
     # actions are resolved into a number of credentials, and those credentials'
-    # tokens will be checked for matching permits.
+    # tokens will be checked for matching grants.
     class Token
       attr_reader :type, :id
 
@@ -44,6 +44,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/db.rb

@@ -4,6 +4,13 @@ require 'ostruct'
 require 'logger'
 require 'yaml'
 
+require_relative 'db/cartesian_select'
+require_relative 'db/params'
+require_relative 'db/query/acr'
+require_relative 'db/query/ac'
+require_relative 'db/query/ar'
+require_relative 'db/query/cr'
+
 module Checkpoint
   # Module for everything related to the Checkpoint database.
   module DB
@@ -110,7 +117,7 @@ module Checkpoint
 
       def model_files
         [
-          'db/permit'
+          'db/grant'
         ]
       end
 

data/lib/checkpoint/db/cartesian_select.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Checkpoint
+  module DB
+    # Helper for querying by cross-products across sets of parameters,
+    # especially for grants.
+    #
+    # This class is called CartesianSelect because the logical search space is
+    # the Cartesian product, for example, of agents X credentials X resources.
+    # All grants in that space would be selected.
+    #
+    # This is a base class to support convenient variations for searching in
+    # different scenarios. It is unlikely to be very useful in its own right,
+    # but provides structure for specific subclasses. For example, {Query::ACR}
+    # searches for grants when agents, credentials, and resources are all
+    # known, as when checking authorization. When seeking to list agents that
+    # could take a given action on a resource, {Query::CR} would be useful.
+    #
+    # Subclasses should extends the conditions and parameters methods to supply
+    # the placeholders and matching values. The {Params} class is helpful for
+    # that purpose.
+    #
+    # The queries are ultimately implemented with an IN clause for each key in
+    # the conditions with binding expressions in the way Sequel expects them.
+    class CartesianSelect
+      attr_reader :scope
+
+      def initialize(scope: Grant)
+        @scope = scope
+      end
+
+      def query
+        scope.where(conditions)
+      end
+
+      def all
+        exec(:select)
+      end
+
+      def first
+        exec(:first)
+      end
+
+      def delete
+        exec(:delete)
+      end
+
+      def conditions
+        {
+          zone_id: :$zone_id
+        }
+      end
+
+      def parameters
+        {
+          zone_id: Grant.default_zone
+        }
+      end
+
+      private
+
+      def exec(mode)
+        query.call(mode, parameters)
+      end
+
+      def tokenize(collection)
+        [collection].flatten.map(&:token)
+      end
+    end
+  end
+end

data/lib/checkpoint/db/{permit.rb → grant.rb}

@@ -2,11 +2,11 @@
 
 module Checkpoint
   module DB
-    # Sequel model for permits
-    class Permit < Sequel::Model(DB.db)
-      # Instantiate a Permit from the constituent domain objects (agent,
+    # Sequel model for grants
+    class Grant < Sequel::Model(DB.db)
+      # Instantiate a Grant from the constituent domain objects (agent,
       # resource, credential).
-      def self.from(agent, credential, resource, zone: 'system')
+      def self.from(agent, credential, resource, zone: default_zone)
         new(
           agent_type: agent.type,           agent_id: agent.id,           agent_token: agent.token,
           credential_type: credential.type, credential_id: credential.id, credential_token: credential.token,