checkpoint 0.2.2 → 1.0.0

data/lib/checkpoint/db/permit.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Checkpoint
+  module DB
+    # Sequel model for permits
+    class Permit < Sequel::Model
+      # Instantiate a Permit from the constituent domain objects (agent,
+      # resource, credential).
+      def self.from(agent, credential, resource, zone: 'system')
+        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,
+          resource_type: resource.type,     resource_id: resource.id,     resource_token: resource.token,
+          zone_id: zone
+        )
+      end
+
+      # The default/system zone
+      def self.default_zone
+        '(all)'
+      end
+    end
+  end
+end

data/lib/checkpoint/permission_mapper.rb

@@ -0,0 +1,29 @@
+# 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

@@ -0,0 +1,133 @@
+# 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

data/lib/checkpoint/query.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require 'checkpoint/query/role_granted'
+require 'checkpoint/query/action_permitted'
+
+module Checkpoint
+  # The Query module is a container for the various types of checks or
+  # inquiries that an application might want to make.
+  #
+  # These classes provide a more expressive and object-oriented pattern than
+  # scattering the primitives and throughout the framework (and, more
+  # importantly, application) code base. They improve consistency and
+  # ergonomics in a similar way as named queries or scopes on a model class.
+  # That is, it's possible to query the authority directly (or model, by
+  # comparison) with primitives, but these classes will capture the semantics
+  # of a particular check, taking the conceptually pertinent parameters, and
+  # applying any defaults or conversion to authoriziation primitives needed,
+  # particularly around credential types.
+  #
+  # Despite modeling the semantics of a query in a convenient way, these
+  # objects do not assume a singleton authority. To make their usage truly
+  # convenient, they should be created from a factory method that binds them to
+  # an already-configured {Checkpoint::Authority}.
+  #
+  # NOTE: @botimer 2018-02-25: I suspect that we will build a convenience class
+  # that binds an authority, and has a factory method per query. This might end
+  # up being the main interface to Checkpoint; a wide-but-shallow adapter
+  # object that can be set up at initialization and made available to
+  # application policies (rather than using the authority directly). I also
+  # suspect that a shorthand adapter will appear for convenient aliasing in
+  # context. For example, a `can?` method on a base application policy that
+  # requires only an action parameter, binding its user and resource by
+  # default, would be a familiar and ergonomic way to call `action_permitted`.
+  # This would create and evaluate a new ActionPermitted instance bound to the
+  # parameters and the configured authority. A pattern like this would achieve
+  # the concurrent goals of maintaining the framework design and call-site
+  # simplicity, without relying on mixins -- the delegation to Checkpoint would
+  # be made explicit with some short boilerplate in application code that can
+  # be found and examined without digging into gems.
+  module Query
+  end
+end

data/lib/checkpoint/query/action_permitted.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Checkpoint
+  module Query
+    # ActionPermitted is a predicate query that captures the user, action,
+    # and target, and checks if the authority permits the action. It is likely
+    # to be the most commonly issued query in any given application.
+    class ActionPermitted
+      attr_reader :user, :action, :target
+
+      # @param user [<application actor>] the acting user/account
+      # @param action [String|Symbol] the action to be taken; this will be
+      #   forced to a symbol
+      # @param target [<application entity>] the object or application resource
+      #   to be acted upon; defaults to {Checkpoint::Resource.all} to ease
+      #   checking for zone-/system-wide permission.
+      # @param authority [Checkpoint::Authority] the authority to ask about
+      #   this permission
+      def initialize(
+        user,
+        action,
+        target = Checkpoint::Resource.all,
+        authority: Authority::RejectAll.new)
+
+        @user      = user
+        @action    = action.to_sym
+        @target    = target
+        @authority = authority
+      end
+
+      def true?
+        authority.permits?(user, action, target)
+      end
+
+      private
+
+      attr_reader :authority
+    end
+  end
+end

data/lib/checkpoint/query/role_granted.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Checkpoint
+  module Query
+    # RoleGranted is a predicate query that captures the user, role, and
+    # target, and checks if the authority recognizes the user as having the
+    # role.
+    #
+    # TODO: Extract-To-Manual
+    # There are two primary approaches to handling which actions are permitted
+    # for which roles:
+    #
+    # 1. Encoding the details directly in policy objects and checking for the
+    #    appropriate roles within a given rule. This has the effect of placing
+    #    the literal values within the body of a rule, making it quite easy
+    #    to examine. Tests can validate system behavior at development time
+    #    because it is static.
+    #
+    # 2. Implementing a {Checkpoint::Credential::Mapper} 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
+    #    the effect of being more flexible, while making the specifics of a
+    #    rule more difficult to examine. Tests can only validate system
+    #    behavior for a particular configuration -- whether an instance of the
+    #    application is configured in a correct or expected way is not testable
+    #    at development time.
+    class RoleGranted
+      attr_reader :user, :role, :target
+
+      # @param user [<application actor>] the acting user/account
+      # @param role [String|Symbol] the role to be checked; this will be
+      #   forced to a symbol
+      # @param target [<application entity>] the object or application resource
+      #   for which the user may have a role; defaults to {Checkpoint::Resource.all}
+      #   to ease checking for zone-/system-wide roles.
+      # @param authority [Checkpoint::Authority] the authority to ask about
+      #   this role-grant
+      def initialize(user, role, target = Resource.all, authority: Authority::RejectAll.new)
+        @user      = user
+        @role      = role.to_sym
+        @target    = target
+        @authority = authority
+      end
+
+      def true?
+        authority.permits?(user, Credential::Role.new(role), target)
+      end
+
+      private
+
+      attr_reader :authority
+    end
+  end
+end

data/lib/checkpoint/railtie.rb

@@ -1,84 +1,105 @@
-require 'rails'
+# frozen_string_literal: true
 
-class Checkpoint::Railtie < ::Rails::Railtie
-  config.before_initialize do
-    class ::ActionController::Base
-      
-      def self.authorise_controllers_blocks
-        if @authorise_controllers_blocks.nil?
-            @authorise_controllers_blocks = {}
-        end
-        @authorise_controllers_blocks
+module Checkpoint
+  # Railtie to hook Checkpoint into Rails applications.
+  #
+  # This does three things at present:
+  #
+  #   1. Loads our rake tasks, so you can run checkpoint:migrate from the app.
+  #   2. Pulls the Rails database information off of the ActiveRecord
+  #      connection and puts it on Checkpoint::DB.config before any application
+  #      initializers are run.
+  #   3. Sets up the Checkpoint database connection after application
+  #      initializers have run, if it has not already been done and we are not
+  #      running as a Rake task. This condition is key because when we are in
+  #      rails server or console, we want to initialize!, but when we are in
+  #      a rake task to update the database, we have to let it connect, but
+  #      not initialize.
+  class Railtie < Rails::Railtie
+    railtie_name :checkpoint
+
+    class << self
+      # Register a callback to run before anything in 'config/initializers' runs.
+      # The block will get a reference to Checkpoint::DB.config as its only parameter.
+      def before_initializers(&block)
+        before_blocks << block
       end
-  
-      def self.authorise(arg1, &block)
-        
-        if block.nil?
-          block = lambda {|c| true}
-        end
-      
-        to_regexp = lambda do |pattern|
-          if arg1.class.to_s == 'Regexp'
-            arg1
-          else
-            Regexp.new('\A' + pattern.to_s.gsub(/[^\*]/){|char| Regexp.quote(char)}.gsub(/\*/){|| ".*?"} + '\Z')
-          end
-        end
-        
-        patterns = []
-        if arg1.class.to_s == 'Array'
-          arg1.each {|pattern| patterns.push to_regexp.call(pattern) }
-        else
-          patterns.push to_regexp.call(arg1)
-        end
-        
-        authorise_controllers_blocks = ::ApplicationController.authorise_controllers_blocks
-        
-        patterns.each do |pattern|
-          if authorise_controllers_blocks [pattern].nil?
-            authorise_controllers_blocks[pattern] = []
-          end
-          authorise_controllers_blocks[pattern].push(block)
-        end
+
+      # Register a callback to run after anything in 'config/initializers' runs.
+      # The block will get a reference to Checkpoint::DB.config as its only parameter.
+      # Checkpoint::DB.initialize! will not have been automatically called at this
+      # point, so this is an opportunity to do so if an initializer has not.
+      def after_initializers(&block)
+        after_blocks << block
       end
-      
-      #for our american friends
-      def self.authorize(arg1, &block)
-        authorise(arg1, &block)
+
+      # Register a callback to run when Checkpoint is ready and fully initialized.
+      # This will happen once in production, and on each request in development.
+      # If you need to do something once in development, you can choose between
+      # keeping a flag or using the after_initializers.
+      def when_checkpoint_is_ready(&block)
+        ready_blocks << block
       end
-      
-      def authorised?
-        action = "#{self.class.to_s}::#{params[:action]}"
-        ::ApplicationController.authorise_controllers_blocks.each do |pattern, blocks|
-          if action.match pattern
-            blocks.each do |block|
-              if instance_eval(&block)
-                return true
-              end
-            end
-          end
-        end
-        false
+
+      def before_blocks
+        @before ||= []
       end
 
-      def access_denied
-        logger.info "\n\n-----------------------------------------------"
-        logger.info " (401) Access Denied!"
-        logger.info " * see the above request for more info"
-        logger.info "-----------------------------------------------\n\n"
-        render :text => "Access Denied", :status => 401
+      def after_blocks
+        @after ||= []
       end
 
-      def check_authorized
-        if !authorised?
-          access_denied
-        end
+      def ready_blocks
+        @ready ||= []
       end
-      
-      before_filter do |controller|
-        check_authorized
+
+      def under_rake!
+        @rake = true
       end
-      
+
+      def under_rake?
+        @rake ||= false
+      end
+    end
+
+    # This runs before anything in 'config/initializers' runs.
+    initializer "checkpoint.before_initializers", before: :load_config_initializers do
+      config = Checkpoint::DB.config
+      unless config.url
+        opts = ActiveRecord::Base.connection.instance_variable_get(:@config).dup
+        opts.delete(:flags)
+        config[:opts] = opts
+      end
+
+      Railtie.before_blocks.each do |block|
+        block.call(config.to_h)
+      end
+    end
+
+    # This runs after everything in 'config/initializers' runs.
+    initializer "checkpoint.after_initializers", after: :load_config_initializers do
+      config = Checkpoint::DB.config
+      Railtie.after_blocks.each do |block|
+        block.call(config.to_h)
+      end
+    end
+
+    # This runs before any block registered under a `config.to_prepare`, which
+    # could be in plugins or initializers that want to use a fully configured
+    # Checkpoint instance. The `to_prepare` hook is run once at the start of a
+    # production instance and for every request in development (unless caching
+    # is turned on so there is no reloading).
+    initializer "checkpoint.ready", after: :finisher_hook do
+      Checkpoint::DB.initialize! unless Railtie.under_rake?
+
+      Railtie.ready_blocks.each do |block|
+        block.call(Checkpoint::DB.db)
+      end
+    end
+
+    rake_tasks do
+      Railtie.under_rake!
+      load "tasks/migrate.rake"
     end
   end
 end