critic 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d45e116551e704334c5a3c1ddd1d021edbc19fc6
-  data.tar.gz: a881f09af89ed7e572cd3d89724d13b6b62ef180
+  metadata.gz: 119a637d018051dfe1517011f155c2d78155ccdc
+  data.tar.gz: eb1a100714ade7c9d2b8e15f1bd99b023fe07a1c
 SHA512:
-  metadata.gz: 9df1a366cdae643e0ff01bc896146257c94335a4893e29ff7a30ab922b6e486c20be280de5b1e0d5718bcf4a6bfb43ce29140cc4fd6096e31a1935151ffc23f5
-  data.tar.gz: 9be579f0737285e880be3e5ca4976c3ecca7f7deaeb8ef1ff99e4b7b26796e1fceb29bf2ec4402e3966c051007291d32ec45d313e1e2b2bf5a7dfebec1ea9c38
+  metadata.gz: 0a0e3a0ec214a2a081a3b3725e2271f9bd5e975195f3663c7015600f2647d406a60ffa4c0363bd60e6071a63077a5fbd9cbaec9365102dad49ba98711f267901
+  data.tar.gz: ea2def4856cc138ed661bc309cf48c64ab5820e111e9f60a5f5e89581610c60a7aa04d2a4786f438548f7e83df297587a3075abd085c45ad0829689b1e00bc12

data/.rubocop.yml

@@ -32,3 +32,5 @@ Style/StructInheritance:
   Enabled: false
 Style/AccessorMethodName:
   Enabled: false
+Lint/CircularArgumentReference: 
+  Enabled: false # this does not work very well

data/.travis.yml

@@ -4,10 +4,8 @@ cache:
   - bundler
 rvm:
   - 2.3.0
-  - 2.2.4
-  - 2.1.8
 script: 
-  - bundle exec rubocop -D
+  - bundle exec rake rubocop
   - bundle exec rake spec
 notifications:
   email: false

data/README.md

@@ -1,8 +1,6 @@
 # Critic
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/critic`. To experiment with that code, run `bin/console` for an interactive prompt.
-
-TODO: Delete this and the text above, and describe your gem
+Critic inserts an easily verifiable authorization layer into your MVC application using resource policies.
 
 ## Installation
 
@@ -22,7 +20,133 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+### Policies
+
+A policy contains authorization logic for a resource and an authenticated subject.
+
+```ruby
+# app/policies/post_policy.rb
+class PostPolicy
+  include Critic::Policy
+end
+```
+
+There are two types of methods:
+
+* *action* - determines if subject is authorized to perform a specific operation on the resource
+* *scope* - returns a list of resources available to the subject
+
+
+#### Actions
+
+The most basic actions return `true` or `false` to indicate the authorization status.
+
+```ruby
+# app/policies/post_policy.rb
+class PostPolicy
+  include Critic::Policy
+
+  def update
+    !resource.locked
+  end
+end
+```
+
+This policy will only allow updates if the post is not `locked`.
+
+Verify authorization using `#authorize`.
+
+```ruby
+Post = Struct.new(:locked)
+User = Struct.new
+
+PostPolicy.authorize(:update, User.new, Post.new(false)).granted? #=> true
+PostPolicy.authorize(:update, User.new, Post.new(true)).granted? #=> false
+```
+
+#### Scopes
+
+Scopes treat `resource` as a starting point and return a restricted set of associated resources.  Policies can have any number of scopes.  The default scope is `#index`.
+
+```
+# app/policies/post_policy.rb
+class PostPolicy
+  include Critic::Policy
+
+  def index
+    resource.where(deleted_at: nil, author_id: subject.id)
+  end
+end
+```
+
+### Controller
+
+Controllers are the primary consumer of policies.  Controllers ask the policy if an authenticated subject is authorized to perform a specific action on a specific resource.
+
+In Rails, the policy action is inferred from `params[:action]` which corresponds to the controller action method name.
+
+When `authorize` fails, a `Critic::AuthorizationDenied` exception is raised with reference to the performed authorization.
+
+```ruby
+# app/controllers/post_controller.rb
+class PostController < ApplicationController
+  include Critic::Controller
+
+  rescue_from Critic::AuthorizationDenied do |exception|
+    messages = exception.authorization.messages || exception.message
+    render json: {errors: [messages]}, status: :unauthorized
+  end
+
+  def update
+    post = Post.find(params[:id])
+    authorize post # calls PostPolicy#update
+
+    render json: post
+  end
+end
+```
+
+When action cannot be inferred, pass the intended action to `authorize`.
+
+```ruby
+# app/controllers/post_controller.rb
+class PostController < Sinatra::Base
+  include Critic::Controller
+
+  error Critic::AuthorizationDenied do |exception|
+    messages = exception.authorization.messages || exception.message
+
+    body {errors: [messages]}
+    halt 403
+  end
+
+  put '/posts/:id' do |id|
+    post = Post.find(id)
+    authorize post, :update
+
+    post.to_json
+  end
+end
+```
+
+By default, the policy's subject is referenced by `current_user`.  Override `critic` to customize.
+
+```ruby
+# app/controllers/application_controller.rb
+class ApplicationController < ActionController::Base
+  include Critic::Controller
+
+  protected
+
+  def critic
+    token
+  end
+end
+```
+
+
+#### Testing
+
 
 ## Development
 

data/Rakefile

@@ -1,7 +1,15 @@
 # frozen_string_literal: true
 require 'bundler/gem_tasks'
 require 'rspec/core/rake_task'
+require 'rubocop/rake_task'
 
 RSpec::Core::RakeTask.new(:spec)
 
 task default: :spec
+
+desc 'Run rubocop'
+task :rubocop do
+  task = RuboCop::RakeTask.new
+  task.patterns = ['lib/**/*.rb']
+  task
+end

data/lib/critic/authorization.rb

@@ -1,12 +1,13 @@
 # frozen_string_literal: true
 class Critic::Authorization
   attr_reader :policy, :action
-  attr_accessor :messages, :granted, :result
+  attr_accessor :messages, :granted, :result, :metadata
 
   def initialize(policy, action)
     @policy = policy
-    @action = action
+    @action = action&.to_sym
 
+    @metadata = {}
     @granted, @result = nil
     @messages = []
   end

data/lib/critic/authorization_denied.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+class Critic::AuthorizationDenied < Critic::Error
+  DEFAULT_MESSAGE = 'Authorization denied'
+
+  attr_reader :authorization
+
+  def initialize(authorization)
+    @authorization = authorization
+
+    message = if authorization.messages.any?
+                authorization.messages.join(',')
+              else
+                DEFAULT_MESSAGE
+              end
+    super(message)
+  end
+end

data/lib/critic/callbacks.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+# Adds callbacks to {Critic::Policy#authorize}
+module Critic::Callbacks
+  extend ActiveSupport::Concern
+
+  included do
+    include ActiveSupport::Callbacks
+
+    if ActiveSupport::VERSION::MAJOR < 4
+      define_callbacks :authorize,
+                       terminator: 'authorization.result == false || result == false',
+                       skip_after_callbacks_if_terminated: true
+    else
+      define_callbacks :authorize,
+                       terminator: ->(target, result) { target.authorization.result == false || false == result },
+                       skip_after_callbacks_if_terminated: true
+    end
+  end
+
+  # Adds callback management functions to {Critic::Policy}
+  module ClassMethods
+    def before_authorize(*names, &blk)
+      _insert_callbacks(names, blk) do |name, options|
+        set_callback(:authorize, :before, name, options)
+      end
+    end
+
+    def after_authorize(*names, &blk)
+      _insert_callbacks(names, blk) do |name, options|
+        set_callback(:authorize, :after, name, options)
+      end
+    end
+
+    def around_authorize(*names, &blk)
+      _insert_callbacks(names, blk) do |name, options|
+        set_callback(:authorize, :around, name, options)
+      end
+    end
+
+    def skip_before_authorize(*names, &blk)
+      _insert_callbacks(names, blk) do |name, options|
+        skip_callback(:authorize, :before, name, options)
+      end
+    end
+
+    # If :only or :except are used, convert the options into the
+    # :unless and :if options of ActiveSupport::Callbacks.
+    # The basic idea is that :only => :index gets converted to
+    # :if => proc {|c| c.action_name == "index" }.
+    #
+    # ==== Options
+    # * <tt>only</tt>   - The callback should be run only for this action
+    # * <tt>except</tt>  - The callback should be run for all actions except this action
+    def _normalize_callback_options(options)
+      _normalize_callback_option(options, :only, :if)
+      _normalize_callback_option(options, :except, :unless)
+    end
+
+    def _normalize_callback_option(options, from, to) # :nodoc:
+      from = options[from]
+      if from
+        from = Array(from).map { |o| "authorization.action.to_s == '#{o}'" }
+        options[to] = Array(options[to]).unshift(from).join(' || ')
+      end
+    end
+
+    # Skip before, after, and around action callbacks matching any of the names.
+    #
+    # ==== Parameters
+    # * <tt>names</tt> - A list of valid names that could be used for
+    #   callbacks. Note that skipping uses Ruby equality, so it's
+    #   impossible to skip a callback defined using an anonymous proc
+    #   using #skip_action_callback
+    def skip_authorize(*names)
+      skip_before_action(*names)
+      skip_after_action(*names)
+      skip_around_action(*names)
+    end
+
+    # Take callback names and an optional callback proc, normalize them,
+    # then call the block with each callback. This allows us to abstract
+    # the normalization across several methods that use it.
+    #
+    # ==== Parameters
+    # * <tt>callbacks</tt> - An array of callbacks, with an optional
+    #   options hash as the last parameter.
+    # * <tt>block</tt>    - A proc that should be added to the callbacks.
+    #
+    # ==== Block Parameters
+    # * <tt>name</tt>     - The callback to be added
+    # * <tt>options</tt>  - A hash of options to be used when adding the callback
+    def _insert_callbacks(callbacks, block = nil)
+      options = callbacks.extract_options!
+      _normalize_callback_options(options)
+      callbacks.push(block) if block
+      callbacks.each do |callback|
+        yield callback, options
+      end
+    end
+  end
+
+  def process_authorization(*)
+    run_callbacks(:authorize) { super }
+  end
+end

data/lib/critic/controller.rb

@@ -9,7 +9,7 @@ module Critic::Controller
     end
   end
 
-  def authorize(resource, action=default_action, policy: policy(resource), with: nil)
+  def authorize(resource, action = default_action, policy: policy(resource), with: nil)
     authorizing!
 
     args = [with] if !with.is_a?(Array) && !with.nil?
@@ -27,10 +27,10 @@ module Critic::Controller
     false
   end
 
-  def authorize_scope(scope, *args, action: nil, policy: policy(scope))
+  def authorize_scope(scope, *args, action: nil, policy: policy(scope), **options)
     authorization_action = action || policy.scope
 
-    authorize(scope, authorization_action, *args, policy: policy)
+    authorize(scope, authorization_action, *args, policy: policy, **options)
   end
 
   protected
@@ -38,7 +38,7 @@ module Critic::Controller
   attr_reader :authorization
 
   def authorization_failed!
-    raise Critic::AuthorizationDenied, authorization.messages
+    raise Critic::AuthorizationDenied, authorization
   end
 
   def authorization_missing!
@@ -46,11 +46,7 @@ module Critic::Controller
   end
 
   def verify_authorized
-    unless true == @_authorizing
-      authorization_missing!
-    else
-      true
-    end
+    (true == @_authorizing) || authorization_missing!
   end
 
   def authorizing!

data/lib/critic/policy.rb

@@ -25,41 +25,25 @@ module Critic::Policy
   end
 
   included do
-    include ActiveSupport::Callbacks
-
-    if ActiveSupport::VERSION::MAJOR < 4
-      define_callbacks :authorize, terminator: 'authorization.result == false || result == false'
-    else
-      define_callbacks :authorize, terminator: ->(target, result) { target.authorization.result == false || false == result }
-    end
+    include Critic::Callbacks
   end
 
   # Policy entry points
   module ClassMethods
-    def authorize(action, subject, resource, args=nil)
+    def authorize(action, subject, resource, args = nil)
       new(subject, resource).authorize(action, *args)
     end
 
     def scope(action = nil)
       action.nil? ? (@scope || :index) : (@scope = action)
     end
-
-    def before_authorize(*args, **options, &block)
-      set_callback(:authorize, :before, *args, **options, &block)
-    end
-
-    def after_authorize(*args, **options, &block)
-      set_callback(:authorize, :after, *args, **options, &block)
-    end
-
-    def around_authorize(*args, **options, &block)
-      set_callback(:authorize, :around, *args, **options, &block)
-    end
   end
 
   attr_reader :subject, :resource, :errors
   attr_accessor :authorization
 
+  delegate :messages, :metadata, to: :authorization
+
   def initialize(subject, resource)
     @subject = subject
     @resource = resource
@@ -73,15 +57,9 @@ module Critic::Policy
   def authorize(action, *args)
     self.authorization = Critic::Authorization.new(self, action)
 
-    result = false
+    result = catch(:halt) { process_authorization(action, args) }
 
-    begin
-      run_callbacks(:authorize) { result = public_send(action, *args) }
-    rescue Critic::AuthorizationDenied
-      authorization.granted = false
-    ensure
-      authorization.result = result if authorization.result.nil?
-    end
+    authorization.result = result if authorization.result.nil?
 
     case authorization.result
     when Critic::Authorization
@@ -98,4 +76,16 @@ module Critic::Policy
 
     authorization
   end
+
+  protected
+
+  def halt(*response)
+    throw :halt, *response
+  end
+
+  private
+
+  def process_authorization(action, args)
+    public_send(action, *args)
+  end
 end

data/lib/critic/version.rb

@@ -1,4 +1,4 @@
 # frozen_string_literal: true
 module Critic
-  VERSION = '0.1.1'
+  VERSION = '0.2.0'
 end

data/lib/critic.rb

@@ -4,13 +4,17 @@ require 'active_support/concern'
 require 'active_support/callbacks'
 require 'active_support/version'
 require 'active_support/core_ext/string/inflections'
+require 'active_support/core_ext/module/delegation'
 
 # Namespace
 module Critic; end
 
-Critic::AuthorizationDenied  = Class.new(StandardError)
-Critic::AuthorizationMissing = Class.new(StandardError)
+Critic::Error = Class.new(StandardError)
+
+Critic::AuthorizationMissing = Class.new(Critic::Error)
 
 require 'critic/policy'
 require 'critic/authorization'
+require 'critic/authorization_denied'
 require 'critic/controller'
+require 'critic/callbacks'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: critic
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Josh Lane
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-06-07 00:00:00.000000000 Z
+date: 2016-06-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -93,6 +93,8 @@ files:
 - critic.gemspec
 - lib/critic.rb
 - lib/critic/authorization.rb
+- lib/critic/authorization_denied.rb
+- lib/critic/callbacks.rb
 - lib/critic/controller.rb
 - lib/critic/policy.rb
 - lib/critic/version.rb