verifica 1.0.1 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ccea0b2769fa053006c2ec3d0b4cd0d3cc65a3a4b4375ce390dabe3a093f490d
-  data.tar.gz: 0bb0dd63b30f08a1df1af771671312182cde2c159613094f9fd0c664201b6e24
+  metadata.gz: f38a13446f6e2b3eb7e118a1d97d5369aca85116a3bde44d7dd1f07bfe013f7a
+  data.tar.gz: ae82a49612de5e13ed32992a13c34a3af57e50b18772c0651194459b5a187010
 SHA512:
-  metadata.gz: 5c3bfab0ce9ccd36cd91baadcc4454e462c9a5d098c6295d3073040d3291030e516d7ae90d200b55b84d4cafd51cd0118c51a1e5a5e0ee075d54e18528033d01
-  data.tar.gz: 6f6011eaec5b7f8a1d810233350a8a68cb7fdf7cf86d8bdc069d51478826ce847461c9d53e5c5f7e83922ac956cb3c1546fd957cb973c5dfee1a71cbc7258726
+  metadata.gz: fcaee3d318dbada1fe7f4c135bbd38219b8031126e1e0d29b5c125a15f1867e8305fb4ec5ca91a2b4eddc4040ad49d24af9e79fb6a36ddab115f2d50db70d5fe
+  data.tar.gz: f0a4392ff578a8444b5f922ae7f3844bd14126ceb5570bf2e9ded02463a3ff63ec69d68b248e5b4241dfa10db4ab537b6fd35b2073e1d4d070f76d74f2c6e896

data/CHANGELOG.md

@@ -7,6 +7,12 @@ 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

data/README.md

@@ -20,7 +20,7 @@ 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?
 
@@ -38,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
@@ -78,20 +78,26 @@ 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
@@ -122,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
@@ -145,7 +151,7 @@ class Post
   def resource_id
     1
   end
-  
+
   def resource_type
     :post
   end
@@ -282,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
@@ -365,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)
@@ -391,10 +397,10 @@ class VideosController
       .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)
 

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+
@@ -173,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/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Verifica
-  VERSION = "1.0.1"
+  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
@@ -60,20 +60,26 @@ require_relative "verifica/version"
 #   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.1
+  version: 1.0.2
 platform: ruby
 authors:
 - Maxim Gurin
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-04-15 00:00:00.000000000 Z
+date: 2023-10-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -120,7 +120,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.12
+rubygems_version: 3.4.19
 signing_key:
 specification_version: 4
 summary: The most scalable authorization solution for Ruby