checkpoint 0.2.2 → 1.0.0

data/lib/checkpoint/resource.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require 'checkpoint/resource/token'
+require 'checkpoint/resource/all_of_type'
+require 'checkpoint/resource/all_of_any_type'
+require 'checkpoint/resource/any_entity'
+require 'checkpoint/resource/any_entity_of_type'
+
+module Checkpoint
+  # A Resource is any application object that should be considered for
+  # restricted access.
+  #
+  # Most commonly, these will be the core domain objects that are created by
+  # users ("model instances", to use Rails terminology), but this is not a
+  # requirement. A Resource can represent a fixed item in the system such as
+  # the administrative password, where there might be a single 'update'
+  # permission to change various elements of configuration. It might also be
+  # something like a section of a site as set up in a config file.
+  #
+  # In modeling an application, it is not always obvious whether a concept
+  # should be a {Credential} or a {Resource}, so take care to evaluate the
+  # options. As an example, consider access to derivatives of a high-quality
+  # media object based on subscription level. It may make more sense for a
+  # given application to model access to a fixed set of profiles (e.g., mobile,
+  # standard, premium) as credentials and named concepts that will appear
+  # throughout the codebase. For an application where the profiles are more
+  # dynamic, it may make more sense to model them as resources that can be
+  # listed and updated by configuration or at runtime, with a fixed set of
+  # permissions (e.g., preview, stream, download).
+  #
+  # Checkpoint does not force this decision to be made in one way for every
+  # application, but provides the concepts of permission mapping and resource
+  # resolution to accommodate whatever fixed, dynamic, or inherited modeling is
+  # most appropriate for the credentials and resources of an application.
+  class Resource
+    attr_reader :entity
+
+    # Special string to be used when permitting or searching for permits on all
+    # types or all resources
+    ALL = '(all)'
+
+    # Creates a Resource for this entity. Prefer the factory method {::from},
+    # which applies default conversion rules. This constructor does not
+    # consider whether the entity can covert itself with #to_resource.
+    def initialize(entity)
+      @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.
+    #
+    # @return [AllOfAnyType] a wildcard resource instance
+    def self.all
+      AllOfAnyType.new
+    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
+    # 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.
+    #
+    # If the entity implements `#resource_type`, we will use that. Otherwise,
+    # we use the entity's class name.
+    #
+    # @return [String] the name of the entity's type after calling `#to_s` on it.
+    def type
+      if entity.respond_to?(:resource_type)
+        entity.resource_type
+      else
+        entity.class
+      end.to_s
+    end
+
+    # Get the resource ID.
+    #
+    # If the entity implements `#resource_id`, we will use that. Otherwise we
+    # call `#id`. If the the entity does not implement either of these methods,
+    # we raise a {NoIdentifierError}.
+    #
+    # @return [String] the entity's ID after calling `#to_s` on it.
+    def id
+      if entity.respond_to?(:resource_id)
+        entity.resource_id
+      elsif entity.respond_to?(:id)
+        entity.id
+      else
+        raise NoIdentifierError, "No usable identifier on entity of type: #{entity.class}"
+      end.to_s
+    end
+
+    # @return [Resource::Token] The token for this resource
+    def token
+      @token ||= Token.new(type, id)
+    end
+
+    # Convert this Resource into a wildcard representing all resources of this
+    # type.
+    #
+    # @see Resource::AllOfType
+    # @return [Resource] A Resource of the same type, but for all members
+    def all_of_type
+      Resource::AllOfType.new(type)
+    end
+
+    # Check whether two Resources refer to the same entity.
+    # @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 `#eql?`.
+    def eql?(other)
+      other.is_a?(Resource) && entity.eql?(other.entity)
+    end
+
+    # Check whether two Resources refer to the same entity.
+    # @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 `#==`.
+    def ==(other)
+      other.is_a?(Resource) && entity == other.entity
+    end
+  end
+end

data/lib/checkpoint/resource/all_of_any_type.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Checkpoint
+  class Resource
+    # Specialized Resource type to represent all entities of a any/all types.
+    # This is used for zone-/system-wide grants or checks.
+    class AllOfAnyType < Resource
+      # Create a wildcard Resource.
+      #
+      # Because type and ID are static, this takes no parameters
+      def initialize
+        @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
+      end
+
+      # The special ALL id
+      def id
+        Resource::ALL
+      end
+    end
+  end
+end

data/lib/checkpoint/resource/all_of_type.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Checkpoint
+  class Resource
+    # Specialized Resource type to represent all entities of a particular type.
+    class AllOfType < Resource
+      attr_reader :type
+      # Create a wildcard Resource for a given type
+      def initialize(type)
+        @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
+      end
+
+      # Compares with another Resource
+      #
+      # @return [Boolean] true if `other` is a Resource and its #type matches.
+      def eql?(other)
+        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
+end

data/lib/checkpoint/resource/any_entity.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Checkpoint
+  class Resource
+    # Special class to represent any entity of any type. This is used for
+    # zone-/system-wide grants or checks. It is basically so {AllOfAnyType} can
+    # have an entity rather than a nil.
+    #
+    # Wildcards or null objects typically have somewhat strange semantics, and
+    # this is no exception. It will compare as eql? and == to any object.
+    class AnyEntity
+      # Always returns true; this wildcard is "equal" to any object.
+      # return [Boolean] true
+      def eql?(*)
+        true
+      end
+
+      # Always returns true; this wildcard is "equal" to any object.
+      # return [Boolean] true
+      def ==(*)
+        true
+      end
+    end
+  end
+end

data/lib/checkpoint/resource/any_entity_of_type.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Checkpoint
+  class Resource
+    # Special class to represent any entity of a type. This is used for
+    # type-wide grants or checks. It is basically so {AllOfType} can
+    # have an entity rather than a nil.
+    #
+    # Wildcards or null objects typically have somewhat strange semantics, and
+    # this is no exception. It will compare as eql? and == to any object that
+    # has the same type attribute.
+    class AnyEntityOfType
+      attr_reader :type
+
+      # Create a wildcard entity that will compare as equal to
+      def initialize(type)
+        @type = type
+      end
+
+      # Always returns true; this wildcard is "equal" to any object.
+      # return [Boolean] true
+      def eql?(other)
+        other.respond_to?(:type) && type == other.type
+      end
+
+      alias == eql?
+    end
+  end
+end

data/lib/checkpoint/resource/resolver.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+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 permit 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.
+    #
+    # NOTE: This implementation currently always resolves to the entity and its
+    # type and nothing more. This needs some thought on an appropriate extension
+    # mechanism to mirror the {PermissionMapper}.
+    class Resolver
+      def resolve(target)
+        return [target] if target.is_a?(Resource)
+        [Resource.from(target), Resource::AllOfType.from(target)]
+      end
+    end
+  end
+end

data/lib/checkpoint/resource/token.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+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
+    # entities are resolved into a number of resources, and those resources'
+    # tokens will be checked for matching permits.
+    class Token
+      attr_reader :type, :id
+
+      # Create a new Resource representing a domain entity or concept that would
+      # be acted upon.
+      #
+      # @param type [String] the application-determined type of this resource.
+      #   This might correspond to a model class or other type of named concept
+      #   in the application. The type is always coerced to String with `#to_s`
+      #   in case something else is supplied.
+      #
+      # @param id [String] the application-resolvable identifier for this
+      #   resource. For example, this might be the ID of a model object, the
+      #   name of a section. The id is always coerced to String with `#to_s` in
+      #   case something else is supplied.
+      def initialize(type, id)
+        @type = type.to_s
+        @id = id.to_s
+      end
+
+      # Get the special "all" Resource Token. This is a singleton that represents all
+      # resources of all types. It is used to grant permissions or roles within
+      # a zone, but not specific to a particular resource.
+      #
+      # @return [Resource::Token] the special "all" Resource Token
+      def self.all
+        @all ||= new(Resource::ALL, Resource::ALL).freeze
+      end
+
+      # @return [Token] self; for convenience of taking a Resource or token
+      def token
+        self
+      end
+
+      # @return [String] a URI for this resource, including its type and id
+      def uri
+        "resource://#{type}/#{id}"
+      end
+
+      # @return [String] a token suitable for granting or matching this resource
+      def to_s
+        "#{type}:#{id}"
+      end
+
+      # Compare with another Resource for equality. Consider them to represent
+      # the same resource if `other` is a Resource, has the same type, and same id.
+      def eql?(other)
+        other.is_a?(Resource::Token) && type == other.type && id == other.id
+      end
+
+      alias == eql?
+      alias inspect uri
+    end
+  end
+end

data/lib/checkpoint/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Checkpoint
-  VERSION = "0.2.2"
+  VERSION = "1.0.0"
 end

data/lib/tasks/migrate.rake

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'checkpoint'
+
+if defined?(Rails)
+  # When db:schema:dump is called directly, we can tack this on.
+  # If we do it unconditionally, db:migrate will try to dump before we have
+  # been able to migrate the checkpoint tables.
+  if Rake.application.top_level_tasks.include?('db:schema:dump')
+    Rake::Task['db:schema:dump'].enhance do
+      Rake::Task['checkpoint:schema:dump'].invoke
+    end
+  end
+
+  # Run our schema load to make sure that the version number is stored in
+  # schema_info, so migrations don't try to double-run. The actual table
+  # structure is handled by the Rails schema:dump and schema:load.
+  # A db:setup will trigger this, so we don't have to handle it separately.
+  Rake::Task['db:schema:load'].enhance do
+    Rake::Task['checkpoint:schema:load'].invoke
+  end
+
+  # We hook into db:migrate for convenience.
+  Rake::Task['db:migrate'].enhance do
+    Rake::Task['checkpoint:migrate'].invoke
+  end
+
+end
+
+namespace :checkpoint do
+  desc "Migrate the Checkpoint database to the latest version"
+  task :migrate do
+    if defined?(Rails)
+      # Load the 'environment', which does the full Rails initialization.
+      # The Railtie is smart enough to know whether we are in a Rake task,
+      # so it can avoid initializing and we can migrate safely before the
+      # models are loaded.
+      Rake::Task['environment'].invoke
+    end
+
+    # After migrating, we initialize here, even though it isn't strictly
+    # necessary, but it will ensure that migration does a small sanity check
+    # that at least all of the tables expected by model classes exist.
+    Checkpoint::DB.migrate!
+    Checkpoint::DB.initialize!
+  end
+
+  # We don't bother defining the schema:dump and schema:load tasks if we're
+  # not running under Rails. They exist only to cooperate with the dumps done
+  # by Rails, since schema.rb includes any Checkpoint tables in the same
+  # database as the application -- a convenient default mode.
+  if defined?(Rails)
+    namespace :schema do
+      desc "Dump the Checkpoint version to db/checkpoint.yml"
+      task :dump do
+        Rake::Task['environment'].invoke
+        Checkpoint::DB.dump_schema!
+      end
+
+      desc "Load the Checkpoint version from db/checkpoint.yml"
+      task :load do
+        Rake::Task['environment'].invoke
+        Checkpoint::DB.load_schema!
+      end
+
+      # When running under Rails, we dump the schema after migrating so
+      # everything stays synced up for db:setup against a new database.
+      # Rake::Task['checkpoint:schema:dump'].invoke
+      Rake::Task['checkpoint:migrate'].enhance do
+        Rake::Task['checkpoint:schema:dump'].invoke
+      end
+    end
+  end
+end