verifica 1.0.0

data/lib/verifica/errors.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Verifica
+  # Base class for all Verifica exceptions
+  #
+  # @api public
+  class Error < StandardError
+    # @return [String] detailed description of the error if it's available or +message+ if not
+    #
+    # @api public
+    def explain
+      message
+    end
+  end
+
+  # Raised when {#action} on the given {#resource} isn't allowed for authorization {#subject} (e.g. current user)
+  #
+  # @api public
+  class AuthorizationError < Error
+    # @api private
+    attr_reader :result
+
+    # @api private
+    def initialize(result)
+      @result = result
+      super(result.message)
+    end
+
+    # (see AuthorizationResult#subject)
+    def subject
+      result.subject
+    end
+
+    # (see AuthorizationResult#subject_type)
+    def subject_type
+      result.subject_type
+    end
+
+    # (see AuthorizationResult#subject_id)
+    def subject_id
+      result.subject_id
+    end
+
+    # (see AuthorizationResult#subject_sids)
+    def subject_sids
+      result.subject_sids
+    end
+
+    # (see AuthorizationResult#resource)
+    def resource
+      result.resource
+    end
+
+    # (see AuthorizationResult#resource_type)
+    def resource_type
+      result.resource_type
+    end
+
+    # (see AuthorizationResult#resource_id)
+    def resource_id
+      result.resource_id
+    end
+
+    # (see AuthorizationResult#action)
+    def action
+      result.action
+    end
+
+    # (see AuthorizationResult#acl)
+    def acl
+      result.acl
+    end
+
+    # (see AuthorizationResult#context)
+    def context
+      result.context
+    end
+
+    # (see AuthorizationResult#explain)
+    def explain
+      result.explain
+    end
+  end
+end

data/lib/verifica/resource_configuration.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "set"
+
+module Verifica
+  # Configuration object for resources registered in {Authorizer}
+  #
+  # @see Verifica.authorizer Usage examples
+  # @note Use {Configuration#register_resource} instead of this class directly
+  #
+  # @api public
+  class ResourceConfiguration
+    # @return [Symbol] type of the resource
+    #
+    # @api public
+    attr_reader :resource_type
+
+    # @return [Set<Symbol>] set of actions possible for this resource type
+    #
+    # @api public
+    attr_reader :possible_actions
+
+    # @return [#call] Access Control List provider for this resource type
+    #
+    # @api public
+    attr_reader :acl_provider
+
+    # @see Verifica.authorizer Usage examples
+    # @note Use {Configuration#register_resource} instead of this constructor directly
+    #
+    # @api public
+    def initialize(resource_type, possible_actions, acl_provider)
+      @resource_type = resource_type.to_sym
+      @possible_actions = action_set(possible_actions).freeze
+      if acl_provider.nil?
+        raise Error, "'#{@resource_type}' resource acl_provider should not be nil"
+      end
+      @acl_provider = acl_provider
+      freeze
+    end
+
+    private def action_set(possible_actions)
+      if possible_actions.empty?
+        raise Error, "Empty possible actions for '#{@resource_type}' resource. Probably a bug?"
+      end
+
+      action_set = possible_actions.map(&:to_sym).to_set
+      if action_set.size < possible_actions.size
+        duplicates = possible_actions.tally.select { |_, count| count > 1 }.keys
+        raise Error, "'#{duplicates}' possible actions for '#{@resource_type}' resource are specified several times. " \
+          "Probably code copy-paste and a bug?"
+      end
+
+      action_set
+    end
+  end
+end

data/lib/verifica/sid.rb

@@ -0,0 +1,215 @@
+# frozen_string_literal: true
+
+module Verifica
+  # Security Identifier (SID)
+  #
+  # Typically SID is an immutable string (you could use other objects too, string just makes it easier to understand)
+  # which describes certain fact about a security subject
+  # (current user, external service with given API key and scope of permissions, etc.).
+  # Each subject has a list of SIDs associated with it.
+  # For example, SIDs of a superuser may look like: +["root"]+,
+  # and SIDs of a regular user with ID +123+ may look like: +["authenticated", "user:123"]+.
+  #
+  # Essentially SIDs act as a link between the security subject and Access Control List for each resource in your system.
+  #
+  # @note This is an optional, convenience module. It adds methods that represent SIDs common for many web applications
+  #   so you'll spend less time inventing your own convention. But you are free to use any other convention for SIDs.
+  #
+  # @example
+  #   class User
+  #     include Verifica::Sid
+  #
+  #     def id
+  #       # ...
+  #     end
+  #
+  #     def superuser?
+  #       # ...
+  #     end
+  #
+  #     def org_id
+  #       # ...
+  #     end
+  #
+  #     def subject_sids(**)
+  #       if superuser?
+  #         [root_sid]
+  #       else
+  #         [authenticated_sid, user_sid(id), organization_sid(org_id)]
+  #       end
+  #     end
+  #   end
+  #
+  # @see Acl
+  module Sid
+    ANONYMOUS_SID = "anonymous"
+    AUTHENTICATED_SID = "authenticated"
+    ROOT_SID = "root"
+    private_constant :ANONYMOUS_SID, :AUTHENTICATED_SID, :ROOT_SID
+
+    # Security Identifier of the anonymous subject. Essentially this is a public SID.
+    # Use it when certain resources need to be available to anyone.
+    #
+    # @example
+    #   class PostAclProvider
+    #     include Verifica::Sid
+    #
+    #     def call(post, **)
+    #       Verifica::Acl.build do |acl|
+    #         if post.public?
+    #           acl.allow anonymous_sid, [:read]
+    #         end
+    #
+    #         # ...
+    #       end
+    #     end
+    #   end
+    #
+    # @return [String]
+    #
+    # @api public
+    def anonymous_sid
+      ANONYMOUS_SID
+    end
+
+    # Security Identifier of any authenticated subject (current user, external service, etc.).
+    #
+    # @example
+    #   class PostAclProvider
+    #     include Verifica::Sid
+    #
+    #     def call(post)
+    #       Verifica::Acl.build do |acl|
+    #         if post.public?
+    #           acl.allow authenticated_sid, [:read, :comment]
+    #         end
+    #
+    #         # ...
+    #       end
+    #     end
+    #   end
+    #
+    # @return [String]
+    #
+    # @api public
+    def authenticated_sid
+      AUTHENTICATED_SID
+    end
+
+    # Security Identifier of the superuser. The name is taken from Unix terminology as it provides a clear separation
+    # between true admins and semi-admins common in web applications (e.g. organization admin, chat room admin, etc.).
+    # Typically you allow all actions for this SID on all resources.
+    #
+    # @example
+    #   class PostAclProvider
+    #     include Verifica::Sid
+    #
+    #     ALL_ACTIONS = [:read, :write, :delete, :comment]
+    #     ROOT_ACL = Acl.build { |acl| acl.allow root_sid, ALL_ACTIONS }
+    #
+    #     def call(post, **)
+    #       ROOT_ACL.build do |acl|
+    #         if post.public?
+    #           acl.allow authenticated_sid, [:read, :comment]
+    #         end
+    #
+    #         # ...
+    #       end
+    #     end
+    #   end
+    #
+    # @return [String]
+    #
+    # @api public
+    def root_sid
+      ROOT_SID
+    end
+
+    # Security Identifier of the regular user with given +user_id+.
+    #
+    # @note An argument can't be +nil+ for safety reasons.
+    #   +nil+ can cause unpredictable consequences like two separate users sharing the same SID and access rights
+    #
+    # @example
+    #   class PostAclProvider
+    #     include Verifica::Sid
+    #
+    #     def call(post, **)
+    #       Verifica::Acl.build do |acl|
+    #         acl.allow user_sid(post.author_id), [:read, :comment, :write, :delete]
+    #
+    #         # ...
+    #       end
+    #     end
+    #   end
+    #
+    # @return [String]
+    #
+    # @api public
+    def user_sid(user_id)
+      if user_id.nil?
+        raise ArgumentError, "Nil 'user_id' is unsafe. Use empty string if you absolutely need this behavior"
+      end
+
+      "user:#{user_id}".freeze
+    end
+
+    # Security Identifier of the subject with given +role_id+.
+    #
+    # @note (see #user_sid)
+    #
+    # @example
+    #   class PostAclProvider
+    #     include Verifica::Sid
+    #
+    #     def call(post, **)
+    #       Verifica::Acl.build do |acl|
+    #         acl.allow role_sid("moderator"), [:read, :comment, :delete]
+    #
+    #         # ...
+    #       end
+    #     end
+    #   end
+    #
+    # @return [String]
+    #
+    # @api public
+    def role_sid(role_id)
+      if role_id.nil?
+        raise ArgumentError, "Nil 'role_id' is unsafe. Use empty string if you absolutely need this behavior"
+      end
+
+      "role:#{role_id}".freeze
+    end
+
+    # Security Identifier of the subject who is a member of the organization with given +organization_id+
+    #
+    # @note (see #user_sid)
+    #
+    # @example
+    #   class PostAclProvider
+    #     include Verifica::Sid
+    #
+    #     def call(post, **)
+    #       Verifica::Acl.build do |acl|
+    #         if post.internal?
+    #           acl.allow organization_sid(post.organization_id), [:read, :comment]
+    #         end
+    #
+    #         # ...
+    #       end
+    #     end
+    #   end
+    #
+    # @return [String]
+    #
+    # @api public
+    def organization_sid(organization_id)
+      if organization_id.nil?
+        raise ArgumentError, "Nil 'organization_id' is unsafe. Use empty string if you absolutely need this behavior"
+      end
+
+      "org:#{organization_id}".freeze
+    end
+  end
+end

data/lib/verifica/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Verifica
+  VERSION = "1.0.0"
+end

data/lib/verifica.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require_relative "verifica/acl"
+require_relative "verifica/authorization_result"
+require_relative "verifica/authorizer"
+require_relative "verifica/configuration"
+require_relative "verifica/errors"
+require_relative "verifica/sid"
+require_relative "verifica/version"
+
+# Verifica is Ruby's most scalable authorization solution ready to handle sophisticated authorization rules.
+#
+# - Framework and database agnostic
+# - Scalable. Start from 10, grow to 10M records in the database while having the same authorization architecture
+# - Supports any actor in your application. Traditional +current_user+, external service, API client, you name it
+# - No global state. Only local, immutable objects
+# - Plain old Ruby, zero dependencies, no magic
+#
+# Verifica is designed around Access Control List. ACL clearly separates authorization rules definition
+# (who can do what for any given resource) and execution (can +current_user+ delete this post?).
+#
+# @example
+#   require 'verifica'
+#
+#   User = Struct.new(:id, :role, keyword_init: true) do
+#     # Verifica expects each security subject to respond to #subject_id, #subject_type, and #subject_sids
+#     alias_method :subject_id, :id
+#     def subject_type = :user
+#
+#     def subject_sids(**)
+#       role == "root" ? ["root"] : ["authenticated", "user:#{id}"]
+#     end
+#   end
+#
+#   Video = Struct.new(:id, :author_id, :public, keyword_init: true) do
+#     # Verifica expects each secured resource to respond to #resource_id, and #resource_type
+#     alias_method :resource_id, :id
+#     def resource_type = :video
+#   end
+#
+#   video_acl_provider = lambda do |video, **|
+#     Verifica::Acl.build do |acl|
+#       acl.allow "root", [:read, :write, :delete, :comment]
+#       acl.allow "user:#{video.author_id}", [:read, :write, :delete, :comment]
+#
+#       if video.public
+#         acl.allow "authenticated", [:read, :comment]
+#       end
+#     end
+#   end
+#
+#   authorizer = Verifica.authorizer do |config|
+#     config.register_resource :video, [:read, :write, :delete, :comment], video_acl_provider
+#   end
+#
+#   public_video = Video.new(id: 1, author_id: 1000, public: true)
+#   private_video = Video.new(id: 2, author_id: 1000, public: true)
+#
+#   superuser = User.new(id: 777, role: "root")
+#   video_author = User.new(id: 1000, role: "user")
+#   other_user = User.new(id: 2000, role: "user")
+#
+#   authorizer.authorized?(superuser, private_video, :delete)
+#   # true
+#
+#   authorizer.authorized?(video_author, private_video, :delete)
+#   # true
+#
+#   authorizer.authorized?(other_user, private_video, :read)
+#   # false
+#
+#   authorizer.authorized?(other_user, public_video, :comment)
+#   # true
+#
+#   authorizer.authorize(other_user, public_video, :write)
+#   # raises Verifica::AuthorizationError: Authorization FAILURE. Subject 'user' id='2000'. Resource 'video' id='1'. Action 'write'
+#
+# @api public
+module Verifica
+  EMPTY_ARRAY = [].freeze
+  private_constant :EMPTY_ARRAY
+
+  # Empty, frozen Access Control List. Semantically means that no actions are allowed
+  #
+  # @api public
+  EMPTY_ACL = Verifica::Acl.new(EMPTY_ARRAY).freeze
+
+  # Creates a new {Configuration} and yields it to the given block
+  #
+  # @example
+  #   post_acl_provider = lambda do |post, **|
+  #     Verifica::Acl.build do |acl|
+  #       acl.allow "root", [:read, :write, :delete, :comment]
+  #       acl.allow "user:#{post.author_id}", [:read, :write, :delete, :comment]
+  #
+  #       if post.public
+  #         acl.allow "authenticated", [:read, :comment]
+  #       end
+  #     end
+  #   end
+  #
+  #   user_acl_provider = lambda do |user, **|
+  #     Verifica::Acl.build do |acl|
+  #       acl.allow "root", [:read, :write, :delete]
+  #       acl.allow "user:#{user.id}", [:read, :write]
+  #     end
+  #   end
+  #
+  #   authorizer = Verifica.authorizer do |config|
+  #     config.register_resource :post, [:read, :write, :delete, :comment], post_acl_provider
+  #     config.register_resource :user, [:read, :write, :delete], user_acl_provider
+  #   end
+  #
+  # @return [Authorizer] a new Authorizer configured by the given block
+  #
+  # @api public
+  def self.authorizer
+    config = Configuration.new
+    yield config
+    Authorizer.new(config.resources)
+  end
+end

data/verifica.gemspec

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative "lib/verifica/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "verifica"
+  spec.authors       = ["Maxim Gurin"]
+  spec.email         = ["mg@maximgurin.com"]
+  spec.version       = Verifica::VERSION
+  spec.license       = "MIT"
+
+  spec.summary       = "The most scalable authorization solution for Ruby"
+  spec.homepage      = "https://github.com/maximgurin/verifica"
+  spec.files         = Dir["CHANGELOG.md", "LICENSE", "README.md", "verifica.gemspec", "lib/**/*"]
+  spec.bindir        = "bin"
+  spec.executables   = []
+  spec.require_paths = ["lib"]
+  spec.description   = <<~DESCRIPTION
+    Verifica is Ruby's most scalable authorization solution, ready to handle sophisticated authorization rules.
+    Verifica is framework and database agnostic and designed around Access Control Lists.
+    ACL powers a straightforward and unified authorization flow for any user and resource,
+    regardless of how tricky the authorization rules are.
+
+    Verifica aims to solve the issue when authorization rules become too complex to be expressed in a single
+    SQL query. And at the same time the database is too big to execute these rules in the application code.
+  DESCRIPTION
+
+  spec.metadata["allowed_push_host"]     = "https://rubygems.org"
+  spec.metadata["homepage_uri"]          = spec.homepage
+  spec.metadata["changelog_uri"]         = "https://github.com/maximgurin/verifica/blob/main/CHANGELOG.md"
+  spec.metadata["source_code_uri"]       = "https://github.com/maximgurin/verifica"
+  spec.metadata["bug_tracker_uri"]       = "https://github.com/maximgurin/verifica/issues"
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  spec.required_ruby_version = ">= 3.0.0"
+
+  spec.add_development_dependency "bundler"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "rspec"
+  spec.add_development_dependency "yard"
+end

metadata

@@ -0,0 +1,127 @@
+--- !ruby/object:Gem::Specification
+name: verifica
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Maxim Gurin
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2023-01-19 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: |
+  Verifica is Ruby's most scalable authorization solution, ready to handle sophisticated authorization rules.
+  Verifica is framework and database agnostic and designed around Access Control Lists.
+  ACL powers a straightforward and unified authorization flow for any user and resource,
+  regardless of how tricky the authorization rules are.
+
+  Verifica aims to solve the issue when authorization rules become too complex to be expressed in a single
+  SQL query. And at the same time the database is too big to execute these rules in the application code.
+email:
+- mg@maximgurin.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/verifica.rb
+- lib/verifica/ace.rb
+- lib/verifica/acl.rb
+- lib/verifica/acl_builder.rb
+- lib/verifica/authorization_result.rb
+- lib/verifica/authorizer.rb
+- lib/verifica/configuration.rb
+- lib/verifica/errors.rb
+- lib/verifica/resource_configuration.rb
+- lib/verifica/sid.rb
+- lib/verifica/version.rb
+- verifica.gemspec
+homepage: https://github.com/maximgurin/verifica
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/maximgurin/verifica
+  changelog_uri: https://github.com/maximgurin/verifica/blob/main/CHANGELOG.md
+  source_code_uri: https://github.com/maximgurin/verifica
+  bug_tracker_uri: https://github.com/maximgurin/verifica/issues
+  rubygems_mfa_required: 'true'
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.3
+signing_key: 
+specification_version: 4
+summary: The most scalable authorization solution for Ruby
+test_files: []