action_authorization 0.3.4 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 738c9014d3f4738e858d3fed5b026ddf9481f856b814421fe4a2bc7ddcd7c478
-  data.tar.gz: e3fcdc5d42fd8071f0b1c28260197f5dc5f7c748b3c4cd02f5968328e58818c4
+  metadata.gz: d6ff507f71e00e904d3e19c0b9d042e9d62155c1496c6cebb1fc2280d602ee1d
+  data.tar.gz: e771b6625111854c345974406b7dceb8afd3c436e5106e4e7a4381d9fde5cd5f
 SHA512:
-  metadata.gz: a658d363a670eb08452b23352519747317a8415fd49b6a90bd42c534619c441aa98f572a263f3fb731b67b627c32c62a9da190853216287873ab42bd90ee13a4
-  data.tar.gz: '0993d92a305756013707f6391e0368998f742675db8e96765905456b713a35deae8bfcf903df131f6a27d9245c7c091155620b53327236f7cc63da828cca1882'
+  metadata.gz: 94a2acc764e1e6b3fce5652e82d6d2221810423ac0a4e6191adec662c249219ccec77c8b33abd1ffb6f5cf52a1cdf73d2e38e0620b422ecdedb501af8d4c485f
+  data.tar.gz: 4933805e2ffd1ebc2ecc7c3e15657106831eadf0ed3be7200af729b11f2c6d09af555113365b0156a7ae0239097d60bc4339885140dcd703510359b4e6436d39

data/README.md

@@ -1,7 +1,9 @@
 # ActionAuthorization
+
 A base policy class for authorizing controller actions with access to the current_user and object.
 
 ## Installation
+
 Add this line to your application's Gemfile:
 
 ```ruby
@@ -9,19 +11,23 @@ gem 'action_authorization'
 ```
 
 And then execute:
+
 ```bash
 bundle
 ```
 
 Or install it with:
+
 ```bash
 gem install action_authorization
 ```
 
 ## Requirements
+
 ActionAuthorization requires a **current_user** method that returns the currently logged in user.
 
 ## Usage
+
 Include the ActionAuthorization module in your ApplicationController (or indvidual controller(s))
 
 ```ruby
@@ -31,7 +37,8 @@ end
 ```
 
 Create an authorization policy for a resource.
-``` ruby
+
+```ruby
 class DocumentPolicy < ActionAuthorization::BasePolicy
   def show?
     document.owner == user
@@ -40,6 +47,7 @@ end
 ```
 
 Call **authorize** method in controller action.
+
 ```ruby
 class DocumentController < ApplicationController
   def show
@@ -49,6 +57,7 @@ end
 ```
 
 Pass a **policy_class** to authorize to override the default resource based policy.
+
 ```ruby
 class DocumentController < ApplicationController
   def show
@@ -57,11 +66,142 @@ class DocumentController < ApplicationController
 end
 ```
 
+By default, an unauthorized action raises `ActionAuthorization::AuthorizationFailure`.
+Applications can handle it in their base controller and choose an appropriate response:
+
+```ruby
+class ApplicationController < ActionController::Base
+  rescue_from ActionAuthorization::AuthorizationFailure, with: :authorization_failure
+
+  private
+
+  def authorization_failure
+    head :forbidden
+  end
+end
+```
+
+### `policy`
+
 Check if authorized before displaying a link in the view.
 
 ```erb
 <%= link_to(@document.name, @document) if policy(@document).show? %>
 ```
 
+### `policy_for`
+
+An enhanced version of `policy` that also accepts a `[parent, model]` pair for authorizing a new
+nested record.
+
+```ruby
+policy_for([folder, Document])
+```
+
+This creates the model with the parent assigned to its association and returns its policy. Unlike
+`folder.documents.build`, it does not add the new record to the parent's cached association.
+
+When passed a single object, `policy_for` behaves the same as `policy`:
+
+```ruby
+policy_for(document)
+```
+
+## Testing support
+
+Testing helpers are opt-in and are loaded separately from the runtime API:
+
+```ruby
+require "action_authorization/testing"
+```
+
+The shared `PolicyHelpers` module provides `allow` and `forbid`. It requires including modules to
+define `policy_class_default`, so include the specialized module for the test type rather than
+including `PolicyHelpers` directly:
+
+```ruby
+class ActionDispatch::IntegrationTest
+  include ActionAuthorization::Testing::IntegrationTestPolicyHelpers
+end
+
+class ActionView::TestCase
+  include ActionAuthorization::Testing::ViewTestPolicyHelpers
+end
+```
+
+`IntegrationTestPolicyHelpers` derives the policy class from the test class name (for example,
+`DocumentsControllerTest` uses `DocumentPolicy`). `ViewTestPolicyHelpers` defaults to `OpenPolicy`
+and includes `PolicyStub`, so `policy` returns an open policy in view tests. Both modules provide
+`allow` and `forbid`.
+
+If needed, `PolicyStub` can also be included separately in another test class to make `policy`
+return an open policy:
+
+```ruby
+class SomeHelperTest < ActiveSupport::TestCase
+  include ActionAuthorization::Testing::PolicyStub
+end
+```
+
+`OpenPolicy` allows every action by default, including non-standard predicates such as
+`activate?`. Use `forbid(:activate)` to override a specific action.
+
+The expectation helpers use the `any_instance.expects` API and require Mocha to be configured by
+the client application's test suite.
+
+### Examples
+
+In an integration test, `allow` and `forbid` set the result of the action predicate on the policy
+class inferred from the test class name. For `DocumentsControllerTest`, that is `DocumentPolicy`:
+
+```ruby
+class DocumentsControllerTest < ActionDispatch::IntegrationTest
+  test "shows an authorized document" do
+    allow(:show)
+
+    get document_url(documents(:one))
+    assert_response :success
+  end
+
+  test "raises when showing a forbidden document" do
+    forbid(:show)
+
+    assert_raises(ActionAuthorization::AuthorizationFailure) do
+      get document_url(documents(:one))
+    end
+  end
+end
+```
+
+In a view test, `ViewTestPolicyHelpers` uses `OpenPolicy`, so the link is allowed by default. Use
+`forbid(:show)` to exercise the hidden-link case:
+
+```ruby
+class DocumentsHelperTest < ActionView::TestCase
+  test "returns a link to an authorized document" do
+    assert link_to_document(documents(:one))
+  end
+
+  test "returns nil when showing the document is forbidden" do
+    forbid(:show)
+
+    assert_nil link_to_document(documents(:one))
+  end
+end
+```
+
+Helpers that render a template or partial that calls `policy` need the view object stubbed too.
+Call `view_policy_stub` in those tests:
+
+```ruby
+test "returns the document header" do
+  view_policy_stub
+
+  assert_includes document_header(documents(:one)), "Document"
+end
+```
+
 ## License
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+The gem is available as open source under the terms of the
+[MIT License](https://opensource.org/licenses/MIT).

data/lib/action_authorization/testing/integration_test_policy_helpers.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module ActionAuthorization
+  module Testing
+    module IntegrationTestPolicyHelpers
+      include PolicyHelpers
+
+      private
+
+      def policy_class_default
+        self.class.name.sub("ControllerTest", "").singularize.concat("Policy").constantize
+      end
+    end
+  end
+end

data/lib/action_authorization/testing/open_policy.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module ActionAuthorization
+  module Testing
+    class OpenPolicy < ActionAuthorization::BasePolicy
+      def initialize
+        super(nil, nil)
+      end
+
+      # Any predicate (ending in "?") is allowed, including non-standard actions.
+      def method_missing(method_name, *, &)
+        predicate?(method_name) || super
+      end
+
+      def respond_to_missing?(method_name, include_private = false)
+        predicate?(method_name) || super
+      end
+
+      private
+
+      def authorized?
+        true
+      end
+
+      def predicate?(method_name)
+        method_name.end_with?("?")
+      end
+    end
+  end
+end

data/lib/action_authorization/testing/policy_helpers.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module ActionAuthorization
+  module Testing
+    module PolicyHelpers
+      private
+
+      def allow(action, **)
+        policy_action_expectation(action, **)
+      end
+
+      def forbid(action, **)
+        policy_action_expectation(action, **, value: false)
+      end
+
+      def policy_action_expectation(action, policy_class: policy_class_default, value: true)
+        policy_class.any_instance.expects("#{action}?").returns(value)
+      end
+
+      def policy_class_default
+        raise NotImplementedError, "You must implement policy_class_default in your test class"
+      end
+    end
+  end
+end

data/lib/action_authorization/testing/policy_stub.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module ActionAuthorization
+  module Testing
+    module PolicyStub
+      def policy(*)
+        OpenPolicy.new
+      end
+      alias policy_for policy
+    end
+  end
+end

data/lib/action_authorization/testing/view_test_policy_helpers.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module ActionAuthorization
+  module Testing
+    module ViewTestPolicyHelpers
+      include PolicyHelpers
+      include PolicyStub
+
+      private
+
+      def policy_class_default
+        OpenPolicy
+      end
+
+      def view_policy_stub
+        view.stubs(:policy).returns(policy)
+      end
+    end
+  end
+end

data/lib/action_authorization/testing.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "action_authorization"
+require "action_authorization/testing/open_policy"
+require "action_authorization/testing/policy_stub"
+require "action_authorization/testing/policy_helpers"
+require "action_authorization/testing/integration_test_policy_helpers"
+require "action_authorization/testing/view_test_policy_helpers"

data/lib/action_authorization/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ActionAuthorization
-  VERSION = "0.3.4"
+  VERSION = "0.4.0"
 end

data/lib/action_authorization.rb

@@ -10,7 +10,7 @@ require "action_authorization/authorization_failure"
 module ActionAuthorization
   def self.included(base)
     base.class_eval do
-      helper_method :policy
+      helper_method :policy, :policy_for
     end
   end
 
@@ -26,7 +26,18 @@ module ActionAuthorization
     (policy_class || policy_class_for(object)).new(current_user, object)
   end
 
+  def policy_for(object)
+    policy(object.is_a?(Array) ? policy_record_for(object) : object)
+  end
+
   def policy_class_for(object)
     object.nil? ? NullPolicy : "#{object.model_name}Policy".constantize
   end
+
+  private
+
+  def policy_record_for(array)
+    parent, model = array
+    model.new(parent.model_name.element.to_sym => parent)
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: action_authorization
 version: !ruby/object:Gem::Version
-  version: 0.3.4
+  version: 0.4.0
 platform: ruby
 authors:
 - Aaron Baldwin
@@ -39,6 +39,12 @@ files:
 - lib/action_authorization/authorization_failure.rb
 - lib/action_authorization/base_policy.rb
 - lib/action_authorization/null_policy.rb
+- lib/action_authorization/testing.rb
+- lib/action_authorization/testing/integration_test_policy_helpers.rb
+- lib/action_authorization/testing/open_policy.rb
+- lib/action_authorization/testing/policy_helpers.rb
+- lib/action_authorization/testing/policy_stub.rb
+- lib/action_authorization/testing/view_test_policy_helpers.rb
 - lib/action_authorization/version.rb
 homepage: https://github.com/wwidea/action_authorization
 licenses:
@@ -60,7 +66,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.2
+rubygems_version: 4.0.17
 specification_version: 4
 summary: Rails controller object-level action authorization.
 test_files: []