ostiary 0.14.0 → 0.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '0594884e87d985f4f25c92d557de11a346ce8a7bb53aad64c1c47ad3183b901b'
-  data.tar.gz: d8ba5b7ba7456ae202f00f8cf6a6a1fc02fb2348dbf5e22721b8379c8d3ea0e2
+  metadata.gz: 06dd41598d092805491bf1002d20b09e64794171c9e5c1544cbe9602d9ce7cd8
+  data.tar.gz: fd650ed79a11cd624500bb3e3f6d4b0d21fc87f80a09de630cc06b535f9e765b
 SHA512:
-  metadata.gz: 3fff7e6700a4354a458de759c89fb36ceb70e335231211f0e0f942c64faa54b8fce84cbe3546e061d96fc23300c830eb467f8f6994f6ebab56bd293558a5169f
-  data.tar.gz: b6423e7a2837470cd9c548e2d40aa3e026b4cd2599e263f6e63f142d33faefddde95771d6e41c5112059f58b255491aeba799c4244e1570f08b0e225e5e8f394
+  metadata.gz: 88c015f225cb267ab1b52d2732e78125d9e9fc3c04f4ae5cedf1704dc55d8da7f4867dba3df03d4783ff993f5fa6b15ec4889d1be47b673c3d67c4a7f58c6b7e
+  data.tar.gz: ea35d66e93f5b9da36b5d4bf88d9bc2ccb8820e5a629f2908217c27d5d0f350e8a7a9704446ca9918184c6cc6cf03cf5647b75e79aaf9744994288987cc8a289

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2017 Nedap
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,94 @@
+# Ostiary
+
+An ostiarius, a Latin word sometimes anglicized as ostiary but often literally translated as porter or doorman, originally was a servant or guard posted at the entrance of a building. See also gatekeeper.
+
+## Functionality
+
+[![CircleCI Status](https://circleci.com/gh/nedap/ostiary.svg?style=svg)](https://circleci.com/gh/nedap/ostiary)
+
+This gem will help you enforce 'policies' when viewing controllers/actions.
+This is done by requiring certain roles for controllers, where you can
+optionally include or exclude certain actions.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'ostiary'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install ostiary
+
+## Usage
+
+### Primary setup
+
+In your base Controller class do the following for Rails:
+
+```ruby
+# This class creates a class accessor called :ostiary on each (inherited) controller.
+#  With each controller created, it will stack the policies you add
+include Ostiary::ControllerHelper
+
+before_filter :ensure_authorized!
+
+# Because each ostiary is unique for a controller, you only have to supply the current action.
+#  With this, it can check if there are certain policies that will be broken.
+def ensure_authorized!
+  self.class.ostiary.authorize!(action) do |name|
+    # Your authorization method using name.
+    #  e.g. `current_user.has_right?(name)`
+  end
+rescue Ostiary::PolicyBroken => error
+  # We re-raise the Error as a RoutingError in Rails
+  #  You can also do `return head :forbidden` if that's more in line with your needs.
+  raise ActionController::RoutingError.new(error.message)
+end
+```
+
+### Securing controllers
+
+In each controller you wish to secure, you can call `ostiary_policy`, just like `before_filter` & `after_filter` of Rails.
+
+```ruby
+# Require the :list role on the entire controller
+ostiary_policy :list
+
+# Require the :view role only on the index & show actions
+ostiary_policy :view, only: [:index, :show]
+
+# Require the :edit role except on the index & show actions
+ostiary_policy :edit, except: [:index, :show]
+```
+
+These policies will be added to the ostiary instance created for each Controller Class. It will also include each policy inherited from parent classes.
+
+### Checking for a right
+
+You can also ask if a user is authorized to access to a certain path (url).
+
+in your Controller:
+
+```ruby
+def authorized?(path)
+  # recognize_path is a Rails Routing helper that will return a hash with the controller
+  #  and action of the path you supplied. We'll have to transform that String of the
+  #  controller into an actual Class.
+  return false unless route = Rails.application.routes.recognize_path(path)
+  requested_controller = "#{route[:controller]}_controller".camelize.constantize
+  requested_controller.ostiary.authorized?(route[:action]) do |role|
+    # Your authorization method using name.
+  end
+end
+```
+
+## License
+
+ostiary is Copyright 2017 nedap and released under the MIT license which you should find included in the [LICENSE.txt](LICENSE.txt) file.

data/lib/ostiary/controller_helper.rb

@@ -0,0 +1,52 @@
+module Ostiary
+  module ControllerHelper
+
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+
+      def inherited(subclass)
+        subclass.ostiary.policies += self.ostiary.policies
+        super
+      end
+
+      def ostiary
+        @ostiary ||= Ostiary.new
+      end
+
+      def required_application_role(role, actions = {})
+        warn "[DEPRECATION] `required_application_role` is deprecated.  Please use `ostiary_policy` instead."
+        ostiary_policy(role, actions)
+      end
+
+      # We want to give the option of setting a policy for one action, based on ::Role
+      # So we'll copy the way the filters in controllers work.
+      # Only apply the role to certain action(s)
+      #  only: [*actions]
+      # Exclude action(s) from requiring a role
+      #  except: [*actions]
+      # By default a given role will be required for every action
+      # Override role checking by passing a symbol as method;
+      #   ostiary_policy method: :master?, only: :show
+      # One line creates one policy, which are immediately created with the proper class
+      def ostiary_policy(role = nil, only: nil, except: nil, method: nil)
+        raise ArgumentError, "Use at least role or method" unless method || role
+        raise ArgumentError, "Use either role or method"       if method && role
+        raise ArgumentError, "Use either only or except"       if except && only
+        raise ArgumentError, "Use a symbol for method:"        if method && !(method.is_a? Symbol)
+
+        if only
+          ostiary.policies << PolicyLimited.new(role, only, method: method&.to_proc)
+        elsif except
+          ostiary.policies << PolicyExempted.new(role, except, method: method&.to_proc)
+        else
+          ostiary.policies << Policy.new(role, method: method&.to_proc)
+        end
+      end
+
+    end
+
+  end
+end

data/lib/ostiary/ostiary.rb

@@ -0,0 +1,23 @@
+module Ostiary
+  class Ostiary
+    attr_accessor :policies
+
+    def initialize
+      @policies = []
+    end
+
+    def authorize!(action, &block)
+      policies.each do |policy|
+        next if policy.met?(action, &block)
+        raise PolicyBroken, policy.error_message(action)
+      end
+    end
+
+    def authorized?(action, &block)
+      policies.all? do |policy|
+        policy.met?(action, block)
+      end
+    end
+
+  end
+end

data/lib/ostiary/policy.rb

@@ -0,0 +1,25 @@
+module Ostiary
+  class Policy
+    attr_reader :name, :method, :actions
+
+    def initialize(name, actions = [], method: nil)
+      @name = name
+      @method = method
+      @actions = actions
+    end
+
+    def inspect
+      "#{name}"
+    end
+
+    def met?(_action, &block)
+      return yield name unless method
+      method.call
+    end
+
+    def error_message(action)
+      "#{action} requires #{name}"
+    end
+
+  end
+end

data/lib/ostiary/policy_exempted.rb

@@ -0,0 +1,18 @@
+module Ostiary
+  class PolicyExempted < Policy
+
+    def inspect
+      "#{name} except for #{actions.to_sentence}"
+    end
+
+    def met?(action, &block)
+      return true if actions.include?(action)
+      super
+    end
+
+    def error_message(action)
+      "#{action} not exempted for #{name}"
+    end
+
+  end
+end

data/lib/ostiary/policy_limited.rb

@@ -0,0 +1,18 @@
+module Ostiary
+  class PolicyLimited < Policy
+
+    def inspect
+      "#{name} only for #{actions.to_sentence}"
+    end
+
+    def met?(action, &block)
+      return true unless actions.include?(action)
+      super
+    end
+
+    def error_message(action)
+      "#{action} limited by #{name}"
+    end
+
+  end
+end

data/lib/ostiary/version.rb

@@ -0,0 +1,3 @@
+module Ostiary
+  VERSION = "0.15.0"
+end

data/lib/ostiary.rb

@@ -0,0 +1,10 @@
+require "ostiary/version"
+require "ostiary/ostiary"
+require "ostiary/policy"
+require "ostiary/policy_limited"
+require "ostiary/policy_exempted"
+require "ostiary/controller_helper"
+
+module Ostiary
+  class PolicyBroken < StandardError; end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ostiary
 version: !ruby/object:Gem::Version
-  version: 0.14.0
+  version: 0.15.0
 platform: ruby
 authors:
 - Jacques Hakvoort
@@ -80,7 +80,16 @@ email:
 executables: []
 extensions: []
 extra_rdoc_files: []
-files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/ostiary.rb
+- lib/ostiary/controller_helper.rb
+- lib/ostiary/ostiary.rb
+- lib/ostiary/policy.rb
+- lib/ostiary/policy_exempted.rb
+- lib/ostiary/policy_limited.rb
+- lib/ostiary/version.rb
 homepage: https://github.com/nedap/ostiary
 licenses:
 - MIT