verifica 1.0.0 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8df98ff228b89e7701f41df3d5617d93183e83c32cdae5c879e347c615f367d7
-  data.tar.gz: 956259725d32e5a6208a03f2a07d682d6facbb1dcaae107687ce59cd1cd8363c
+  metadata.gz: f38a13446f6e2b3eb7e118a1d97d5369aca85116a3bde44d7dd1f07bfe013f7a
+  data.tar.gz: ae82a49612de5e13ed32992a13c34a3af57e50b18772c0651194459b5a187010
 SHA512:
-  metadata.gz: d3329c9e126220d43a8e9b4a7923541b30139e74f565387bed6012acea9760239d1b5850d19ee2963e63252ddde3008e39486ac66438e6e9215afe18de0d4256
-  data.tar.gz: 1dab1e7bab877e5f63298240db13270c6f46c238643f508037e81f524a99a54f3613e3515690e54886ac032b371d394622e51d5d33d92528ddab8560d7babb2e
+  metadata.gz: fcaee3d318dbada1fe7f4c135bbd38219b8031126e1e0d29b5c125a15f1867e8305fb4ec5ca91a2b4eddc4040ad49d24af9e79fb6a36ddab115f2d50db70d5fe
+  data.tar.gz: f0a4392ff578a8444b5f922ae7f3844bd14126ceb5570bf2e9ded02463a3ff63ec69d68b248e5b4241dfa10db4ab537b6fd35b2073e1d4d070f76d74f2c6e896

data/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.0.2] - 2023-10-25
+
+### Changed
+
+- Make `Authorizer#authorization_result` public for even more usage flexibility
+
+## [1.0.1] - 2023-04-15
+
+### Added
+
+- `Sid#country_sid` and `Sid#group_sid` helper methods
+
 ## [1.0.0] - 2023-01-19
 
 Initial public release

data/README.md

@@ -1,4 +1,6 @@
+[![Gem Version](https://badge.fury.io/rb/verifica.svg)](https://badge.fury.io/rb/verifica)
 [![CI](https://github.com/maximgurin/verifica/actions/workflows/ci.yml/badge.svg)](https://github.com/maximgurin/verifica/actions/workflows/ci.yml)
+[![Yard Docs](http://img.shields.io/badge/yard-docs-blue.svg)](http://rubydoc.info/github/maximgurin/verifica)
 [![Codacy Badge](https://app.codacy.com/project/badge/Grade/457e56b0bb514539844a94d85abe99f9)](https://www.codacy.com/gh/maximgurin/verifica/dashboard?utm_source=github.com&utm_medium=referral&utm_content=maximgurin/verifica&utm_campaign=Badge_Grade)
 [![Codacy Badge](https://app.codacy.com/project/badge/Coverage/457e56b0bb514539844a94d85abe99f9)](https://www.codacy.com/gh/maximgurin/verifica/dashboard?utm_source=github.com&utm_medium=referral&utm_content=maximgurin/verifica&utm_campaign=Badge_Coverage)
 ![GitHub](https://img.shields.io/github/license/maximgurin/verifica)
@@ -18,11 +20,11 @@ for any user and resource, regardless of how complex the authorization rules are
 
 *Note: Verifica is a new open-source gem, so you may wonder if it's reliable. Internally,
 this solution has been battle-tested in several B2B products, including one with over 15M database records.
-But anyway, trust nothing. DYOR.*
+But DYOR anyway.*
 
 ## Why Verifica? Isn't Pundit or CanCanCan enough?
 
-Let's say you working on a video platform application:
+Let's say you are working on a video platform application:
 
 - You have 10M videos in the database
 - 7 types of user roles
@@ -36,7 +38,7 @@ In the [Real-world example with Rails](#real-world-example-with-rails) you can s
 ## Basic example
 
 ```ruby
-require 'verifica'
+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
@@ -70,26 +72,32 @@ authorizer = Verifica.authorizer do |config|
 end
 
 public_video = Video.new(id: 1, author_id: 1000, public: true)
-private_video = Video.new(id: 2, author_id: 1000, public: true)
+private_video = Video.new(id: 2, author_id: 1000, public: false)
 
 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?(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.authorized?(other_user, public_video, :comment)
-# true
+begin
+  # raises Verifica::AuthorizationError: Authorization FAILURE. Subject 'user' id='2000'. Resource 'video' id='1'. Action 'write'
+  authorizer.authorize(other_user, public_video, :write)
+rescue Verifica::AuthorizationError => e
+  e.explain # => Long-form explanation of why action is not authorized, your debugging friend
+end
 
-authorizer.authorize(other_user, public_video, :write)
-# raises Verifica::AuthorizationError: Authorization FAILURE. Subject 'user' id='2000'. Resource 'video' id='1'. Action 'write'
+# #authorization_result returns a special object with a bunch of useful info
+auth_result = authorizer.authorization_result(superuser, private_video, :delete)
+auth_result.success? # => true
+auth_result.subject_id # => 777
+auth_result.resource_type # => :video
+auth_result.action # => :delete
+auth_result.allowed_actions # => [:read, :write, :delete, :comment]
+auth_result.explain # => Long-form explanation of why action is authorized
 ```
 
 ## Installation
@@ -120,11 +128,11 @@ class User
   def subject_id
     123
   end
-  
+
   def subject_type
     :user
   end
-  
+
   def subject_sids
     ["root"] # see Security Identifier section below to understand what is this for
   end
@@ -143,7 +151,7 @@ class Post
   def resource_id
     1
   end
-  
+
   def resource_type
     :post
   end
@@ -184,9 +192,9 @@ end
 
 video_acl.to_a
 # =>
-# [#<Verifica::Ace:0x00007fab1955dd60 @action=:view, @allow=true, @sid="authenticated">,          
-#  #<Verifica::Ace:0x00007fab1955dd10 @action=:comment, @allow=true, @sid="authenticated">,       
-#  #<Verifica::Ace:0x00007fab1955dc48 @action=:view, @allow=false, @sid="country:US">]
+# [#<Verifica::Ace:0x00007fab1955dd60 @action=:read, @allow=true, @sid="authenticated">,
+#  #<Verifica::Ace:0x00007fab1955dd10 @action=:comment, @allow=true, @sid="authenticated">,
+#  #<Verifica::Ace:0x00007fab1955dc48 @action=:read, @allow=false, @sid="country:US">]
 ```
 
 ### AclProvider
@@ -210,8 +218,8 @@ end
 ### Authorizer
 
 And finally, Authorizer, the heart of Verifica. It couples all concepts above into an isolated container with no global state.
-Each Authorizer has a list of resource types registered with their companion AclProviders.
-And most importantly, Authorizer has several methods to check the Subject's rights to perform a specific action on a given resource.
+Each Authorizer has a list of resource types registered with their companion AclProviders and
+several methods to check the Subject's rights to perform a specific action on a given resource.
 
 Check the [Basic example](#basic-example) above to see how it all plays together.
 
@@ -280,7 +288,7 @@ class VideoAclProvider
       author_org = video.author.organization
       allowed_countries = author_org&.allow_countries || ds.allow_countries
       denied_countries = author_org&.deny_countries || ds.deny_countries
-      
+
       # ...and 30 more lines to handle all our requirements
     end
   end
@@ -318,11 +326,11 @@ class User < ApplicationRecord
     when "moderator"
       [user_sid(id), role_sid("moderator")]
     when "user"
-      sids = [authenticated_sid, user_sid(id), "country:#{country}"]
+      sids = [authenticated_sid, user_sid(id), country_sid(country)]
       organization_id.try { |org_id| sids.push(organization_sid(org_id)) }
       sids
     when "organization_admin"
-      sids = [authenticated_sid, user_sid(id), "country:#{country}"]
+      sids = [authenticated_sid, user_sid(id), country_sid(country)]
       sids.push(organization_sid(organization_id))
       sids.push(role_sid("organization_admin:#{organization_id}"))
     else
@@ -354,7 +362,7 @@ end
 ```
 
 ```ruby
-# app/models/user.rb
+# app/models/video.rb
 
 class Video < ApplicationRecord
   attr_accessor :allowed_actions
@@ -363,7 +371,7 @@ class Video < ApplicationRecord
   before_save :update_read_acl
 
   def resource_type = :video
-  
+
   def update_read_acl
     acl = AUTHORIZER.resource_acl(self)
     self.read_allow_sids = acl.allowed_sids(:read)
@@ -383,12 +391,16 @@ end
 
 class VideosController
   def index
-    @videos = Video.available_for(current_user).order(:name).limit(50)
+    @videos = Video
+      .includes(:distribution_setting, author: [:organization])
+      .available_for(current_user)
+      .order(:name)
+      .limit(50)
   end
-  
+
   def show
     @video = Video.find(params[:id])
-    
+
     # upon successful authorization helper object is returned with a bunch of useful info
     auth_result = AUTHORIZER.authorize(current_user, @video, :read)
 
@@ -415,8 +427,6 @@ run a background job to find all affected videos and update `read_allow_sids`, `
 Same applies to Distribution Settings and other dependencies.
 - **Rules change handling.** If implementation of `VideoAclProvider` changed you need to run a background job
 to update `read_allow_sids`, `read_deny_sids` columns for all videos.
-- **Cache, N+1 problem.** `VideoAclProvider` retrieves a chain of records associated with each video which leads to
-N+1 problem in a naive implementation.
 
 See also:
 

data/lib/verifica/acl.rb

@@ -54,7 +54,6 @@ module Verifica
 
         allow_deny[:allowed_sids].freeze
         allow_deny[:denied_sids].freeze
-        allow_deny.freeze
       end
 
       @allowed_actions.freeze
@@ -154,7 +153,7 @@ module Verifica
 
     # @example
     #   acl = Verifica::Acl.build { |acl| acl.allow "root", [:read, :write] }
-    #   acl.to_a.map(:to_h)
+    #   acl.to_a.map(&:to_h)
     #   # => [{:sid=>"root", :action=>:read, :allow=>true}, {:sid=>"root", :action=>:write, :allow=>true}]
     #
     # @return [Array<Ace>] a new array representing +self+

data/lib/verifica/authorizer.rb

@@ -73,6 +73,11 @@ module Verifica
 
     # The same as {#authorize} but returns true/false instead of rising an exception
     #
+    # @param subject (see #authorize)
+    # @param resource (see #authorize)
+    # @param action (see #authorize)
+    # @param context (see #authorize)
+    #
     # @return [Boolean] true if +action+ on +resource+ is authorized for +subject+
     # @raise [Error] if +resource.resource_type+ isn't registered in +self+
     #
@@ -81,9 +86,31 @@ module Verifica
       authorization_result(subject, resource, action, **context).success?
     end
 
-    # @param subject [Object] subject of the authorization (e.g. current user, external service)
-    # @param resource [Object] resource to get allowed actions for, should respond to +#resource_type+
-    # @param **context (see #authorize)
+    # The same as {#authorize} but returns a special result object instead of rising an exception
+    #
+    # @param subject (see #authorize)
+    # @param resource (see #authorize)
+    # @param action (see #authorize)
+    # @param context (see #authorize)
+    #
+    # @return [AuthorizationResult] authorization result with all details
+    # @raise [Error] if +resource.resource_type+ isn't registered in +self+
+    #
+    # @api public
+    def authorization_result(subject, resource, action, **context)
+      action = action.to_sym
+      possible_actions = config_by_resource(resource).possible_actions
+      unless possible_actions.include?(action)
+        raise Error, "'#{action}' action is not registered as possible for '#{resource.resource_type}' resource"
+      end
+
+      acl = resource_acl(resource, **context)
+      AuthorizationResult.new(subject, resource, action, acl, **context)
+    end
+
+    # @param subject (see #authorize)
+    # @param resource (see #authorize)
+    # @param context (see #authorize)
     #
     # @return [Array<Symbol>] array of actions allowed for +subject+ or empty array if none
     # @raise [Error] if +resource.resource_type+ isn't registered in +self+
@@ -128,7 +155,7 @@ module Verifica
       @resources.key?(resource_type.to_sym)
     end
 
-    # @param resource [Object] resource to get ACL for, should respond to +#resource_type+
+    # @param resource (see #authorize)
     # @param context [Hash] arbitrary keyword arguments to forward to +acl_provider.call+
     #
     # @return [Acl] Access Control List for +resource+
@@ -141,6 +168,7 @@ module Verifica
     def resource_acl(resource, **context)
       config = config_by_resource(resource)
       acl = config.acl_provider.call(resource, **context)
+      # trade-off flexibility to increase robustness here by requiring a specific type
       unless acl.is_a?(Verifica::Acl)
         type = resource.resource_type
         raise Error, "'#{type}' resource acl_provider should respond to #call with Acl object but got '#{acl.class}'"
@@ -172,16 +200,5 @@ module Verifica
 
       resource_config(type)
     end
-
-    private def authorization_result(subject, resource, action, **context)
-      action = action.to_sym
-      possible_actions = config_by_resource(resource).possible_actions
-      unless possible_actions.include?(action)
-        raise Error, "'#{action}' action is not registered as possible for '#{resource.resource_type}' resource"
-      end
-
-      acl = resource_acl(resource, **context)
-      AuthorizationResult.new(subject, resource, action, acl, **context)
-    end
   end
 end

data/lib/verifica/sid.rb

@@ -211,5 +211,66 @@ module Verifica
 
       "org:#{organization_id}".freeze
     end
+
+    # Security Identifier of the subject who is a member of the group with given +group_id+
+    #
+    # @note (see #user_sid)
+    #
+    # @example
+    #   class PostAclProvider
+    #     include Verifica::Sid
+    #
+    #     def call(post, **)
+    #       Verifica::Acl.build do |acl|
+    #         post.editor_groups.each do |group_id|
+    #           acl.allow group_sid(group_id), [:edit, :delete]
+    #         end
+    #
+    #         # ...
+    #       end
+    #     end
+    #   end
+    #
+    # @return [String]
+    #
+    # @api public
+    def group_sid(group_id)
+      if group_id.nil?
+        raise ArgumentError, "Nil 'group_id' is unsafe. Use empty string if you absolutely need this behavior"
+      end
+
+      "group:#{group_id}".freeze
+    end
+
+    # Security Identifier of the subject whose country is the country with given +country_id+
+    #
+    # @note (see #user_sid)
+    #
+    # @example
+    #   class PostAclProvider
+    #     include Verifica::Sid
+    #
+    #     def call(post, **)
+    #       Verifica::Acl.build do |acl|
+    #         acl.allow authenticated_sid, [:read, :comment]
+    #         post.banned_countries.each do |country_id|
+    #           acl.deny country_sid(country_id), [:read, :comment]
+    #         end
+    #
+    #         # ...
+    #       end
+    #     end
+    #   end
+    #
+    # @return [String]
+    #
+    # @api public
+    def country_sid(country_id)
+      if country_id.nil?
+        raise ArgumentError, "Nil 'country_id' is unsafe. Use empty string if you absolutely need this behavior"
+      end
+
+      "country:#{country_id}".freeze
+    end
   end
 end

data/lib/verifica/version.rb

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

data/lib/verifica.rb

@@ -20,7 +20,7 @@ require_relative "verifica/version"
 # (who can do what for any given resource) and execution (can +current_user+ delete this post?).
 #
 # @example
-#   require 'verifica'
+#   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
@@ -54,26 +54,32 @@ require_relative "verifica/version"
 #   end
 #
 #   public_video = Video.new(id: 1, author_id: 1000, public: true)
-#   private_video = Video.new(id: 2, author_id: 1000, public: true)
+#   private_video = Video.new(id: 2, author_id: 1000, public: false)
 #
 #   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?(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.authorized?(video_author, private_video, :delete)
-#   # true
-#
-#   authorizer.authorized?(other_user, private_video, :read)
-#   # false
-#
-#   authorizer.authorized?(other_user, public_video, :comment)
-#   # true
+#   begin
+#     # raises Verifica::AuthorizationError: Authorization FAILURE. Subject 'user' id='2000'. Resource 'video' id='1'. Action 'write'
+#     authorizer.authorize(other_user, public_video, :write)
+#   rescue Verifica::AuthorizationError => e
+#     e.explain # => Long-form explanation of why action is not authorized, your debugging friend
+#   end
 #
-#   authorizer.authorize(other_user, public_video, :write)
-#   # raises Verifica::AuthorizationError: Authorization FAILURE. Subject 'user' id='2000'. Resource 'video' id='1'. Action 'write'
+#   # #authorization_result returns a special object with a bunch of useful info
+#   auth_result = authorizer.authorization_result(superuser, private_video, :delete)
+#   auth_result.success? # => true
+#   auth_result.subject_id # => 777
+#   auth_result.resource_type # => :video
+#   auth_result.action # => :delete
+#   auth_result.allowed_actions # => [:read, :write, :delete, :comment]
+#   auth_result.explain # => Long-form explanation of why action is authorized
 #
 # @api public
 module Verifica

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: verifica
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.2
 platform: ruby
 authors:
 - Maxim Gurin
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-01-19 00:00:00.000000000 Z
+date: 2023-10-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -105,7 +105,7 @@ metadata:
   source_code_uri: https://github.com/maximgurin/verifica
   bug_tracker_uri: https://github.com/maximgurin/verifica/issues
   rubygems_mfa_required: 'true'
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -120,8 +120,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.3
-signing_key: 
+rubygems_version: 3.4.19
+signing_key:
 specification_version: 4
 summary: The most scalable authorization solution for Ruby
 test_files: []