checkpoint 0.2.2 → 1.0.0

data/lib/checkpoint/authority.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require 'checkpoint/agent/resolver'
+require 'checkpoint/credential/resolver'
+require 'checkpoint/resource/resolver'
+require 'checkpoint/permits'
+
+module Checkpoint
+  # An Authority is the central point of contact for authorization questions in
+  # Checkpoint. It checks whether there are permits that would allow a given
+  # action to be taken.
+  class Authority
+    def initialize(
+      agent_resolver: Agent::Resolver.new,
+      credential_resolver: Credential::Resolver.new,
+      resource_resolver: Resource::Resolver.new,
+      permits: Permits.new)
+
+      @agent_resolver      = agent_resolver
+      @credential_resolver = credential_resolver
+      @resource_resolver   = resource_resolver
+      @permits             = permits
+    end
+
+    def permits?(agent, credential, resource)
+      # Conceptually equivalent to:
+      #   can?(agent, action, target)
+      #   can?(current_user, 'edit', @listing)
+
+      #  user   => agent tokens
+      #  action => credential tokens
+      #  target => resource tokens
+
+      # Permit.where(agent: agents, credential: credentials, resource: resources)
+      # SELECT * FROM permits
+      # WHERE agent IN('user:gkostin', 'account-type:umich', 'affiliation:lib-staff')
+      # AND credential IN('permission:edit', 'role:editor')
+      # AND resource IN('listing:17', 'type:listing')
+
+      #  agent_type, agent_id    | cred_type, cred_id | resource_type, resource_id
+      #  ------------------------------------------------------------------------
+      #  'user:gkostin'          | 'permission:edit'  | 'listing:17'
+      #  'account-type:umich'    | 'role:editor'      | 'type:listing'
+      #  'affiliation:lib-staff' |                    | 'listing:*'
+
+      #        ^^^                       ^^^^              ^^^^
+      #   if current_user has at least one row in each of of these columns,
+      #   they have been "granted permission"
+      permits.for(
+        agent_resolver.resolve(agent),
+        credential_resolver.resolve(credential),
+        resource_resolver.resolve(resource)
+      ).any?
+    end
+
+    # Dummy authority that rejects everything
+    class RejectAll
+      def permits?(*)
+        false
+      end
+    end
+
+    private
+
+    attr_reader :agent_resolver, :credential_resolver, :resource_resolver, :permits
+  end
+end

data/lib/checkpoint/credential.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require 'checkpoint/credential/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
+  # instrument that can represent multiple permissions, such as a role or
+  # license.
+  #
+  # 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
+  # be likened to an instance of that class, bound to a given agent and
+  # possibly bound to a {Resource}.
+  class Credential
+    attr_reader :type, :id
+    alias name id
+
+    # Create a new generic Credential. This should generally not be called,
+    # preferring to use a factory or instantiate a {Permission}, {Role}, or
+    # custom Credential class.
+    #
+    # This class assigns the type 'credential', while most often, applications
+    # will want a {Permission}.
+    #
+    # The term `name` is more intuitive for credentials than `id`, as is used
+    # with the {Agent} and {Resource} types. This is because most applications
+    # will use primitive strings or symbols as the programmatic objects for
+    # credentials, where as `id` is often associated with a database-assigned
+    # identifier that should not appear in the source code. The parameter is
+    # called `name` here to reflect that intuitive concept, but it is really
+    # an alias for the `id` property of this Credential.
+    #
+    # @param name [String|Symbol] the name of this credential
+    def initialize(name)
+      @id   = name.to_s
+      @type = 'credential'
+    end
+
+    # Return the list of Credentials that would grant this one.
+    #
+    # 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
+    # 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.
+    #
+    # @see Checkpoint::PermissionMapper
+    # @return [Array<Credential>] the expanded list of credentials that would
+    #   grant this one
+    def granted_by
+      [self]
+    end
+
+    # @return [Token] a token for this credential
+    def token
+      @token ||= Token.new(type, id)
+    end
+
+    # Compare two Credentials.
+    # @param other [Credential] the Credential to compare
+    # @return [Boolean] true if `other` is a Credential and its type and id
+    #   are both eql? to {#type} and {#id}
+    def eql?(other)
+      type.eql?(other.type) && name.eql?(other.id)
+    end
+
+    alias == eql?
+  end
+end

data/lib/checkpoint/credential/permission.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Checkpoint
+  class Credential
+    # A Permission is simple extension to the base Credential, specifying its
+    # type as a permission and providing a conceptual object to be instantiated
+    # or passed.
+    #
+    # The most common use from outside Checkpoint will be by way of
+    # {Checkpoint::Query::ActionPermitted}, which will ask whether a given named
+    # 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.
+    class Permission < Credential
+      TYPE = 'permission'
+
+      def type
+        TYPE
+      end
+    end
+  end
+end

data/lib/checkpoint/credential/resolver.rb

@@ -0,0 +1,87 @@
+# 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.
+    #
+    # Checkpoint makes no particular demand on the credential model for an
+    # application, but offers a useful default implementation 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:
+    #
+    #   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.
+    #
+    #   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.
+    #
+    class Resolver
+      def initialize(permission_mapper: PermissionMapper.new)
+        @permission_mapper = permission_mapper
+      end
+
+      # Resolve 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.
+      #
+      # 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 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 into any Credential that would grant it.
+      def resolve(action)
+        if action.respond_to?(:granted_by)
+          [action.granted_by].flatten
+        else
+          permissions_for(action) + roles_granting(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

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Checkpoint
+  class Credential
+    # A Role is simple extension to the base Credential, specifying its type
+    # as a role and providing a conceptual object to be instantiated or passed.
+    #
+    # 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
+    #
+    # More likely, though, is advising the resolution of Roles through a
+    # {Checkpoint::PermissionMapper} or 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.
+    class Role < Credential
+      TYPE = 'role'
+
+      def type
+        TYPE
+      end
+    end
+  end
+end

data/lib/checkpoint/credential/token.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+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
+    # actions are resolved into a number of credentials, and those credentials'
+    # tokens will be checked for matching permits.
+    class Token
+      attr_reader :type, :id
+
+      # Create a new Credential representing a permission or instrument that
+      # represents multiple permissions.
+      #
+      # @param type [String] the application-determined type of this credential.
+      #   For example, this might be 'permission' or 'role'.
+      #
+      # @param id [String] the application-resolvable identifier for this
+      #   credential. For example, this might be an action to be taken or the ID
+      #   of a role.
+      def initialize(type, id)
+        @type = type.to_s
+        @id = id.to_s
+      end
+
+      # @return [String] a URI for this credential, including its type and id
+      def uri
+        "credential://#{type}/#{id}"
+      end
+
+      # @return [Token] self; for convenience of taking a Credential or token
+      def token
+        self
+      end
+
+      # @return [String] a token suitable for granting or matching this credential
+      def to_s
+        "#{type}:#{id}"
+      end
+
+      # Compare with another Credential for equality. Consider them to represent
+      # the same credential if `other` is a credential, has the same type, and same id.
+      def eql?(other)
+        other.is_a?(Token) && type == other.type && id == other.id
+      end
+
+      alias == eql?
+      alias inspect uri
+    end
+  end
+end

data/lib/checkpoint/db.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require 'ostruct'
+require 'logger'
+require 'yaml'
+
+module Checkpoint
+  # Module for everything related to the Checkpoint database.
+  module DB
+    # Any error with the database that Checkpoint itself detects but cannot handle.
+    class DatabaseError < StandardError; end
+
+    CONNECTION_ERROR = 'The Checkpoint database is not initialized. Call initialize! first.'
+
+    ALREADY_CONNECTED = 'Already connected; refusing to connect to another database.'
+
+    MISSING_CONFIG = <<~MSG
+      CHECKPOINT_DATABASE_URL and DATABASE_URL are both missing and a connection
+      has not been configured. Cannot connect to the Checkpoint database.
+      See Checkpoint::DB.connect! for help.
+    MSG
+
+    LOAD_ERROR = <<~MSG
+      Error loading Checkpoint database models.
+      Verify connection information and that the database is migrated.
+    MSG
+
+    SCHEMA_HEADER = "# Checkpoint Database Version\n"
+
+    class << self
+      # Initialize Checkpoint
+      #
+      # This connects to the database if it has not already happened and
+      # requires all of the Checkpoint model classes. It is required to do the
+      # connection setup first because of the design decision in Sequel that
+      # the schema is examined at the time of extending Sequel::Model.
+      def initialize!
+        connect! unless connected?
+        begin
+          model_files.each do |file|
+            require_relative file
+          end
+        rescue Sequel::DatabaseError, NoMethodError => e
+          raise DatabaseError, LOAD_ERROR + "\n" + e.message
+        end
+        db
+      end
+
+      # Connect to the Checkpoint database.
+      #
+      # The default is to use the settings under {.config}, but can be
+      # supplied here (and they will be merged into config as a side effect).
+      # The keys that will be used from either source are documented here as
+      # the options.
+      #
+      # Only one "mode" will be used; the first of these supplied will take
+      # precedence:
+      #
+      # 1. An already-connected {Sequel::Database} object
+      # 2. A connection string
+      # 3. A connection options hash
+      #
+      # While Checkpoint serves as a singleton, this will raise a DatabaseError
+      # if already connected. Check `connected?` if you are unsure.
+      #
+      # @see {Sequel.connect}
+      # @param [Hash] config Optional connection config
+      # @option config [String] :url A Sequel database URL
+      # @option config [Hash]   :opts A set of connection options
+      # @option config [Sequel::Database] :db An already-connected database;
+      # @return [Sequel::Database] The initialized database connection
+      def connect!(config = {})
+        raise DatabaseError, ALREADY_CONNECTED if connected?
+        merge_config!(config)
+        raise DatabaseError, MISSING_CONFIG if self.config.db.nil? && conn_opts.empty?
+
+        # We splat here because we might give one or two arguments depending
+        # on whether we have a string or not; to add our logger regardless.
+        @db = self.config.db || Sequel.connect(*conn_opts)
+      end
+
+      # Run any pending migrations.
+      # This will connect with the current config if not already connected.
+      def migrate!
+        connect! unless connected?
+        Sequel.extension :migration
+        Sequel::Migrator.run(db, File.join(__dir__, '../../db/migrations'), table: schema_table)
+      end
+
+      def schema_table
+        :checkpoint_schema
+      end
+
+      def schema_file
+        'db/checkpoint.yml'
+      end
+
+      def dump_schema!
+        connect! unless connected?
+        version = db[schema_table].first.to_yaml
+        File.write(schema_file, SCHEMA_HEADER + version)
+      end
+
+      def load_schema!
+        connect! unless connected?
+        version = YAML.load_file(schema_file)[:version]
+        db[schema_table].delete
+        db[schema_table].insert(version: version)
+      end
+
+      def model_files
+        [
+          'db/permit'
+        ]
+      end
+
+      # Merge url, opts, or db settings from a hash into our config
+      def merge_config!(config = {})
+        self.config.url  = config[:url]  if config.key?(:url)
+        self.config.opts = config[:opts] if config.key?(:opts)
+        self.config.db   = config[:db]   if config.key?(:db)
+      end
+
+      def conn_opts
+        log = { logger: Logger.new('db/checkpoint.log') }
+        url = config.url
+        opts = config.opts
+        if url
+          [url, log]
+        elsif opts
+          [log.merge(opts)]
+        else
+          []
+        end
+      end
+
+      def config
+        @config ||= OpenStruct.new(
+          url: ENV['CHECKPOINT_DATABASE_URL'] || ENV['DATABASE_URL']
+        )
+      end
+
+      def connected?
+        !@db.nil?
+      end
+
+      # The Checkpoint database
+      # @return [Sequel::Database] The connected database; be sure to call initialize! first.
+      def db
+        raise DatabaseError, CONNECTION_ERROR unless connected?
+        @db
+      end
+
+      # Forward the Sequel::Database []-syntax down to db for convenience.
+      # Everything else must be called on db directly, but this is nice sugar.
+      def [](*args)
+        db[*args]
+      end
+    end
+  end
+end