checkpoint 1.0.3 → 1.1.0

data/lib/checkpoint/db/params.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Checkpoint
+  module DB
+    # 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

data/lib/checkpoint/db/query/ac.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Checkpoint::DB
+  module Query
+    # A query object based on agents and credentials.
+    #
+    # This query finds grants for any supplied agents, for any supplied
+    # credentials. Its primary purpose is to find which resources for which an
+    # agent has been granted a given credential.
+    #
+    # It can take single items or arrays and converts them all to their tokens
+    # for query purposes.
+    class AC < CartesianSelect
+      attr_reader :agents, :credentials
+
+      def initialize(agents, credentials, scope: Grant)
+        super(scope: scope)
+        @agents      = tokenize(agents)
+        @credentials = tokenize(credentials)
+      end
+
+      def conditions
+        super.merge(
+          agent_token:      agent_params.placeholders,
+          credential_token: credential_params.placeholders
+        )
+      end
+
+      def parameters
+        super.merge(Hash[
+          agent_params.values +
+          credential_params.values
+        ])
+      end
+
+      protected
+
+      def agent_params
+        Params.new(agents, 'at')
+      end
+
+      def credential_params
+        Params.new(credentials, 'ct')
+      end
+    end
+  end
+end

data/lib/checkpoint/db/query/acr.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Checkpoint::DB
+  module Query
+    # A query object based on agents, credentials, and resources.
+    #
+    # This query mirrors the essence of the Checkpoint semantics; that is, it
+    # finds grants for any supplied agents, for any supplied credentials, for
+    # any supplied resources.
+    #
+    # It can take single items or arrays and converts them all to their tokens
+    # for query purposes.
+    class ACR < CartesianSelect
+      attr_reader :agents, :credentials, :resources
+
+      def initialize(agents, credentials, resources, scope: Grant)
+        super(scope: scope)
+        @agents      = tokenize(agents)
+        @credentials = tokenize(credentials)
+        @resources   = tokenize(resources)
+      end
+
+      def conditions
+        super.merge(
+          agent_token:      agent_params.placeholders,
+          credential_token: credential_params.placeholders,
+          resource_token:   resource_params.placeholders
+        )
+      end
+
+      def parameters
+        super.merge(Hash[
+          agent_params.values +
+          credential_params.values +
+          resource_params.values
+        ])
+      end
+
+      protected
+
+      def agent_params
+        Params.new(agents, 'at')
+      end
+
+      def credential_params
+        Params.new(credentials, 'ct')
+      end
+
+      def resource_params
+        Params.new(resources, 'rt')
+      end
+    end
+  end
+end

data/lib/checkpoint/db/query/ar.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Checkpoint::DB
+  module Query
+    # A query object based on agents and resources.
+    #
+    # This query finds grants for any supplied agents, for any supplied
+    # resources. Its primary purpose is to find which credentials have been
+    # granted to an agent on a given resource.
+    #
+    # It can take single items or arrays and converts them all to their tokens
+    # for query purposes.
+    class AR < CartesianSelect
+      attr_reader :agents, :resources
+
+      def initialize(agents, resources, scope: Grant)
+        super(scope: scope)
+        @agents      = tokenize(agents)
+        @resources   = tokenize(resources)
+      end
+
+      def conditions
+        super.merge(
+          agent_token:      agent_params.placeholders,
+          resource_token:   resource_params.placeholders
+        )
+      end
+
+      def parameters
+        super.merge(Hash[
+          agent_params.values +
+          resource_params.values
+        ])
+      end
+
+      protected
+
+      def agent_params
+        Params.new(agents, 'at')
+      end
+
+      def resource_params
+        Params.new(resources, 'rt')
+      end
+    end
+  end
+end

data/lib/checkpoint/db/query/cr.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Checkpoint::DB
+  module Query
+    # A query object based on credentials and resources.
+    #
+    # This query finds grants for any supplied credentials, for any supplied
+    # resources. Its primary purpose is to find which agents have been granted
+    # a given credential on a resource.
+    #
+    # It can take single items or arrays and converts them all to their tokens
+    # for query purposes.
+    class CR < CartesianSelect
+      attr_reader :credentials, :resources
+
+      def initialize(credentials, resources, scope: Grant)
+        super(scope: scope)
+        @credentials = tokenize(credentials)
+        @resources   = tokenize(resources)
+      end
+
+      def conditions
+        super.merge(
+          credential_token: credential_params.placeholders,
+          resource_token:   resource_params.placeholders
+        )
+      end
+
+      def parameters
+        super.merge(Hash[
+          credential_params.values +
+          resource_params.values
+        ])
+      end
+
+      protected
+
+      def credential_params
+        Params.new(credentials, 'ct')
+      end
+
+      def resource_params
+        Params.new(resources, 'rt')
+      end
+    end
+  end
+end

data/lib/checkpoint/grants.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+# Note: we do not require db/grant 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 grants -- a simple wrapper for the Sequel Datastore / grants table.
+  class Grants
+    def initialize(grants: Checkpoint::DB::Grant)
+      @grants = grants
+    end
+
+    def for(agents, credentials, resources)
+      where(agents, credentials, resources).all
+    end
+
+    def any?(agents, credentials, resources)
+      where(agents, credentials, resources).first != nil
+    end
+
+    # Find grants of the given credentials on the given resources.
+    #
+    # This is useful for finding who should have particular access. Note that
+    # this low-level interface returns the full grants, rather than a unique
+    # set of agents.
+    #
+    # @return [Array<Grant>] the set of grants of any of the credentials on
+    #   any of the resources
+    def who(credentials, resources)
+      DB::Query::CR.new(credentials, resources, **scope).all
+    end
+
+    # Find grants to the given agents on the given resources.
+    #
+    # This is useful for finding what actions may be taken on particular items.
+    # Note that this low-level interface returns the full grants, rather than a
+    # unique set of credentials.
+    #
+    # @return [Array<Grant>] the set of grants to any of the agents on any of
+    #   the resources
+    def what(agents, resources)
+      DB::Query::AR.new(agents, resources, **scope).all
+    end
+
+    # Find grants to the given agents of the given credentials.
+    #
+    # This is useful for finding which resources may acted upon. Note that this
+    # low-level interface returns the full grants, rather than a unique set of
+    # resources.
+    #
+    # @return [Array<Grant>] the set of grants of any of the credentials to
+    #   any of the agents
+    def which(agents, credentials)
+      DB::Query::AC.new(agents, credentials, **scope).all
+    end
+
+    # Grant a credential.
+    #
+    # This method takes a single agent, credential, and resource to create a
+    # grant. They are not expanded, though they may be general (e.g., an
+    # agent for users of an instituion or a wildcard for resources of some type).
+    #
+    # @param agent [Agent] the agent to whom the credential should be granted
+    # @param credential [Credential] the credential to grant
+    # @param resource [Resource] the resource to which the credential should apply
+    # @return [Grant] the saved Grant; nil if the save fails
+    def grant!(agent, credential, resource)
+      grants.from(agent, credential, resource).save
+    end
+
+    # Revoke a credential.
+    #
+    # Take care to note that this follows the same matching semantics as
+    # {.for}. There is no expansion done here, but anything that matches what
+    # is supplied will be deleted. Of particular note is the default wildcard
+    # behavior of {Checkpoint::Resource::Resolver}: if a specific resource has
+    # been expanded by the resolver, and the array of the resource, a type
+    # wildcard, and the any-resource wildcard (as used for inherited matching)
+    # is supplied, the results may be surprising where there are grants at
+    # specific and general levels.
+    #
+    # In general, the parameters should not have been expanded. If the intent
+    # is to revoke a general grant, the general details should be supplied,
+    # and likewise for the specific case.
+    #
+    # Applications should interact with the {Checkpoint::Authority}, which
+    # exposes a more application-oriented interface. This repository should be
+    # considered internal to Checkpoint.
+    #
+    # @param agents [Agent|Array] the agent or agents to match for deletion
+    # @param credentials [Credential|Array] the credential or credentials to match for deletion
+    # @param resources [Resource|Array] the resource or resources to match for deletion
+    # @return [Integer] the number of Grants deleted
+    def revoke!(agents, credentials, resources)
+      where(agents, credentials, resources).delete
+    end
+
+    private
+
+    def scope
+      { scope: grants }
+    end
+
+    def where(agents, credentials, resources)
+      DB::Query::ACR.new(agents, credentials, resources, **scope)
+    end
+
+    attr_reader :grants
+  end
+end

data/lib/checkpoint/query/role_granted.rb

@@ -16,7 +16,7 @@ module Checkpoint
     #    to examine. Tests can validate system behavior at development time
     #    because it is static.
     #
-    # 2. Implementing a {Checkpoint::Credential::Mapper} that maps backward
+    # 2. Implementing a {Checkpoint::Credential::Resolver} that maps backward
     #    from actions to named permissions and roles that would allow them.
     #    The policy rules would only authorize actions, leaving the mapping
     #    outside to accommodate configuration or runtime modification. This has

data/lib/checkpoint/resource.rb

@@ -35,7 +35,7 @@ module Checkpoint
   class Resource
     attr_reader :entity
 
-    # Special string to be used when permitting or searching for permits on all
+    # Special string to be used when granting or searching for grants on all
     # types or all resources
     ALL = '(all)'
 
@@ -46,19 +46,6 @@ module Checkpoint
       @entity = entity
     end
 
-    # Default conversion from an entity to a Resource. Prefer this to creating
-    # new instances by hand.
-    #
-    # If the entity implements #to_resource, we will delegate to it. Otherwise,
-    # we will return a Resource for this entity.
-    def self.from(entity)
-      if entity.respond_to?(:to_resource)
-        entity.to_resource
-      else
-        new(entity)
-      end
-    end
-
     # Covenience factory method to get a Resource that will match all entities
     # of any type.
     #
@@ -67,11 +54,22 @@ module Checkpoint
       AllOfAnyType.new
     end
 
+    # Convert this object to a Resource.
+    #
+    # For Checkpoint-supplied Resources, 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_resource
+      self
+    end
+
     # Get the resource type.
     #
     # Note that this is not necessarily a class/model type name. It can be
     # whatever type name is most useful for building tokens and inspecting
-    # permits for this types. For example, there may be objects that have
+    # grants for this types. For example, there may be objects that have
     # subtypes that are not modeled as objects, decorators, or collection
     # objects (like a specialized type for the root of a tree) that should
     # be treated as the element type.
@@ -127,12 +125,11 @@ module Checkpoint
       other.is_a?(Resource) && entity.eql?(other.entity)
     end
 
-    # Check whether two Resources refer to the same entity.
+    # Check whether two Resources refer to the same entity by type and id.
     # @param other [Resource] Another Resource to compare with
-    # @return [Boolean] true when the other Resource's entity is the same as
-    #   determined by comparing them with `#==`.
+    # @return [Boolean] true when the other Resource's type and id are equal.
     def ==(other)
-      other.is_a?(Resource) && entity == other.entity
+      other.is_a?(Resource) && type == other.type && id == other.id
     end
   end
 end

data/lib/checkpoint/resource/all_of_any_type.rb

@@ -12,14 +12,6 @@ module Checkpoint
         @entity = AnyEntity.new
       end
 
-      # Create a wildcard Resource "from" an entity. The entity disregarded and
-      # {AnyEntity} is substituted.
-      #
-      # @return [AllOfAnyType] a wildcard Resource instance
-      def self.from(_entity)
-        new
-      end
-
       # The special ALL type
       def type
         Resource::ALL

data/lib/checkpoint/resource/all_of_type.rb

@@ -10,16 +10,6 @@ module Checkpoint
         @type = type
       end
 
-      # Create a type-specific wildcard Resource from a given entity
-      #
-      # When the entity implements to #to_resource, we convert it first and take
-      # the type from the result. Otherwise, when it implements #resource_type,
-      # we use that result. Otherwise, we take the class name of the entity.
-      # Regardless of the source, the type is forced to a string.
-      def self.from(entity)
-        new(type_of(entity))
-      end
-
       # This is always the special ALL resource ID
       def id
         Resource::ALL
@@ -32,18 +22,6 @@ module Checkpoint
         other.is_a?(Resource) && type == other.type
       end
 
-      # Private type name extraction
-      def self.type_of(entity)
-        if entity.respond_to?(:to_resource)
-          entity.to_resource.type
-        elsif entity.respond_to?(:resource_type)
-          entity.resource_type
-        else
-          entity.class
-        end.to_s
-      end
-
-      private_class_method :type_of
       alias == eql?
     end
   end