strong_presenter 0.1.0 → 0.2.0

data/CHANGELOG.md

@@ -1,14 +1,22 @@
 # StrongPresenter Changelog
 
-## 0.2.0 In development
+## 0.2.0
 
-Changes to be made:
+This release focuses on tightening up security of the permit interface, along with a number of bug fixes.
 
-- Remove permissions grouping - convert to copy on write
-- Remove permit_all! class method
-- Require explicit wildcard endings to attribute paths to permit everything `[:association, :nested_association, :*]` to permit all methods in the association
+- Renamed `permit` to `permit!` in Presenter, CollectionPresenter, Permissible
+- Renamed `filter` to `select_permitted` in Presenter, CollectionPresenter, Permissible
+- Permitted paths are only prefixes with wildcard endings if specified explicitly
+  - `[:comments, :*]` permits all the methods in each comment in the comments association, but not further associations
+  - `[:comments, :**]` permits all methods in all associations, no matter how deep (for example it permits `[:comments, :user, :username]`)
+- Wildcards disabled for tainted paths, tainted paths are only permitted if the exact path has been permitted
+  - a path is tainted if any element in the array is tainted, for example `params[:extra_column].split(',')` is tainted
+- `permit_all!` class method removed - use an initializer instead
+- Permissions grouping removed - the permissions of each presenter is independent, with copy on write semantics.
+  - but permitting on a presenter will propagate permissions to the presenters of associations or collection items. This can be inefficient if an object has many associations or the collection has many items. It is recommended that `permit!` is called before associations or collection items are loaded
+- Added `reload!`, which will reset the cache on association or collection presenters. This might be used if the underlying object has changed.
 
-## 0.1.0 - Stable
+## 0.1.0
 
 - Copied features from Draper gem (thanks):
   - spec/spec_helper.rb, spec/integration, spec/dummy - much easier for me, since I have difficulties trying to get a dummy app working.

data/README.md

@@ -25,7 +25,7 @@ While there exist other gems for presentation, we hope to provide a more natural
 
 Requires Rails. Rails 3.2+ is supported (probably works on 3.0, 3.1 as well).
 
-Add this line to your application''s Gemfile:
+Add this line to your application's Gemfile:
 
     gem 'strong_presenter'
 
@@ -108,7 +108,7 @@ class UsersPresenter < StrongPresenter::CollectionPresenter
 end
 ```
 
-It wraps each item in the collection with the corresponding singular presenter inferred from the class name, but it can be set using the `:with` option in the constructor, or by calling `presents_with :user` (for example), in the class definition.
+It wraps each item in the collection with the corresponding singular presenter inferred from the class name, but it can be set using the `:with` option in the constructor, or by calling `presents_with :user` (for example), in the class definition. The `::Collection` constant of each presenter will automatically be set to the collection presenter with a matching plural name.
 
 ### Model Associations
 
@@ -147,9 +147,18 @@ class UserController < ApplicationController
 end
 ```
 
+Subsequently, in our view, we can use:
+
+```erb
+  Username: <%= user.username %><br>
+  Email: <%= user.email %><br>
+```
+
 If the `:with` option is not passed, it will be inferred by using the model class name. `:only` and `:except` sets the controller actions it applies to.
 
-### Permit!
+### Permit! and `present`
+
+#### Basics
 
 You can simply use the presenter in the view:
 
@@ -157,16 +166,16 @@ You can simply use the presenter in the view:
 Avatar: <%= @user_presenter.avatar %>
 ```
 
-However, sometimes you will want to display information only if it is permitted. To do this, simply pass the attribute symbols to the `presents` method on the presenter, and it will only display it if it is permitted. This is especially powerful because it controls the display of not just the attribute value, but everything that is passed in the block.
+However, sometimes you will want to display information only if it is permitted. To do this, simply pass the attribute symbols to the `presents` method on the presenter, and it will only display it if it is permitted. This is quite useful because it controls the display of not just the attribute value, but everything that is passed in the block. If no block is given, the results are returned in an array.
 
 ```erb
 <% fields = { :username => "Username", :name => "Name", :email => "E-mail" } %>
-<% user.presents *fields.keys do |key, value| # user = @user_presenter because of the call to `presents` in the controller class %>
+<% @user_presenter.presents *fields.keys do |key, value| %>
   <b><%= fields[key] %>:</b> <%= value %><br>
 <% end %>
 ```
 
-The `present` method is also available to display a single attribute:
+The `present` method is also available to display a single attribute. If no block is given, the result is returned, ready to display.
 
 ```erb
 <b>Hello <%= user.present :name %></b><br>
@@ -175,13 +184,13 @@ The `present` method is also available to display a single attribute:
 <% end %>
 ```
 
-To permit the display of the attributes, call `permit` on the presenter with the attribute symbols in the controller.
+To permit the display of the attributes, call `permit!` on the presenter with the attribute symbols in the controller.
 
 ```ruby
 class UserController < ApplicationController
   def show
     @user = User.find(params[:id])
-    @user_presenter = UserPresenter.new(@user).permit :username, :name # but not :email
+    @user_presenter = UserPresenter.new(@user).permit! :username, :name # but not :email
   end
 end
 ```
@@ -191,8 +200,8 @@ You can also call it when using the `presents` method in the controller:
 ```ruby
 class UserController < ApplicationController
   presents :user do |presenter|
-    presenter.permit :username, :name
-    presenter.permit :email if current_user.admin?
+    presenter.permit! :username, :name
+    presenter.permit! :email if current_user.admin?
   end
   def show
     @user = User.find(params[:id])
@@ -200,15 +209,13 @@ class UserController < ApplicationController
 end
 ```
 
-To remove authorization checks, simply call `permit!` on an instance of a presenter.
-
-There is also a `filter` method to help you with tables:
+There is also a `select_permitted` method to help you with tables. For example, we use `select_permitted` below to check which of the columns are visible.
 
 ```erb
 <% fields = { :username => "Username", :name => "Name", :email => "E-mail" } %>
 <table>
   <tr>
-    <% @users_presenter.filter( *fields.keys ) do |key| %>
+    <% @users_presenter.select_permitted( *fields.keys ) do |key| %>
       <th><%= fields[key] %></th>
     <% end %>
   </tr>
@@ -222,9 +229,6 @@ There is also a `filter` method to help you with tables:
 </table>
 ```
 
-Here, we use filter to check which of the columns are visible, just like `presents` does. It returns an
-array of only the visible columns, and we use our `fields` hash to label it.
-
 We can decide what attributes to present based on a GET parameter input, for example:
 
 ```erb
@@ -233,31 +237,104 @@ We can decide what attributes to present based on a GET parameter input, for exa
 <% end %>
 ```
 
-Because of the `permit` checks, there is no danger that private information will be revealed.
+Because of the we permit each attribute individually, there is no danger that private information will be revealed.
+
+#### Associations - Permissions Paths
+
+We can permit association attributes by passing an array of symbols. For example, we might normally get an Article&#39;s author using `@article.author.name`. If we permit it:
+
+```ruby
+@article_presenter.permit! [:author, :name]
+```
+
+then we can use the `present` method to display it:
+
+```erb
+<% @article_presenter.present [:author, :name] do |value| %>
+  By <%= value %>
+<% end %>
+```
+
+It is also possible to include arguments. If our presenter method takes 1 argument:
+
+```ruby
+class ArticlePresenter < StrongPresenter::Presenter
+  def comment_text(index)
+    object.comments[index].text
+  end
+end
+```
+
+Our view can call the method using:
+
+```erb
+<% @article_presenter.permit! [:comment_text, 3] %>
+<%= @article_presenter.present [:comment_text, 3] # this is displayed %>
+<%= @article_presenter.present [:comment_text, 4] # this is not %>
+```
+
+Basically, if the first element is an association, the next element will be the method name instead, and so on. When the final method is determined, extra elements in the array are passed as arguments.
+
+When considering whether the permission path (including arguments) is permitted, it is indifferent to the difference between strings and symbols. So permitting a particular string argument will also permit the symbol argument.
 
-#### Permissions Paths
+#### Wildcards
 
-Association methods can be permitted by passing an array.
+To permit every attribute in a presenter, we can use wildcards. For example, to allow the display of all attributes in the article, we can call:
+
+```ruby
+@article_presenter.permit! :*
+```
 
-```rb
-@article_presenter.permit :body, [:author, :name]
+We can then present any attribute:
+
+```ruby
+@article_presenter.present :text
+```
+
+However, association attributes will not be permitted, for example, `@article_presenter.author.name`. To allow those, we can use the wildcard in an array:
+
+```ruby
+@article_presenter.permit! [:author, :*]
 ```
 
-Then, presenting it:
+It is also possible to permit all association attributes:
+
+```ruby
+@article_presenter.permit! :**
+```
+
+Note that the wildcard can only be used as the last element, so for example, `[:*, :name]` is not treated as a wildcard.
+
+Instead of the single wildcard `:*`, we can simply call `permit_all!` on the presenter.
+
+Any attribute permitted by a wildcard will show up using the `presents` method, except when the argument is tainted. For example, if we used `@article_presenter.permit! :**`, and in our view, had:
 
 ```erb
-<%= @article_presenter.present [:author, :name] %>
+<% @article_presenter.presents :title, "subtitle".taint, [:author, :name].taint, ["author".taint, :email], :text do |value| %>
+  <%= value %><br>
+<% end %>
 ```
 
-is equivalent to `@article_presenter.author.name`, except it includes the permission check.
+then `:title` and `:text` attributes will be displayed, but the other tainted attributes will not be displayed. For example, attributes constructed using the `params` hash will be tainted. This is a security measure to prevent a bug similar to the mass-assignment vulnerability, where an arbitrary presenter method can be called.
+
+#### Association Permissions
 
-#### Permissions Groups
+Association presenters will automatically inherit the permissions of its parent, and any new permissions will be propagated to the association presenter. For example:
 
-Currently, each group of presenters shares a single permissions object. Therefore, each element in a collection references the same permissions object. The presenter for each association also shares the same permissions object. This means that permitting a method will permit it for all presenters in the group, and it is not possible for two presenters in the same collection to have different methods permitted.
+```ruby
+@article_presenter.permit! [:author, :name]
+@author_presenter = @article_presenter.author
+@author_presenter.present(:name) # this is permitted
+@article_presenter.permit! [:author, :email]
+@author_presenter.present(:email) # now this is also permitted
+```
 
-Everytime you get a presenter through a collection or association, it will be added to the permissions group. To start a new group, you will need to initialize it yourself.
+Attributes permitted by an item in a collection will not be permitted on the siblings:
 
-It is the intention that in version 0.2.0, permissions groups (for efficiency in a simple implementation), will be removed, and each new presenter will implement copy on write with the permissions object. This will retain efficiency where `permit` is called early before forking new presenters, but allow different permissions for each presenter. This will change the behaviour of what is considered permitted, but if `permit` is called before using the presenter, the behaviour will not change.
+```ruby
+@articles_presenter[0].permit! :author
+@articles_presenter[1].present(:author) # not permitted
+```
 
 ### Testing
 
@@ -273,7 +350,7 @@ In tests, a view context is built to access helper methods. By default, it will
 StrongPresenter::ViewContext.test_strategy :fast
 ```
 
-In doing so, your presenters will no longer have access to your application''s helpers. If you need to selectively include such helpers, you can pass a block:
+In doing so, your presenters will no longer have access to your application&#39;s helpers. If you need to selectively include such helpers, you can pass a block:
 
 ```ruby
 StrongPresenter::ViewContext.test_strategy :fast do

data/lib/strong_presenter/associable.rb

@@ -3,6 +3,7 @@ module StrongPresenter
   # Methods for defining presenter associations
   module Associable
     extend ActiveSupport::Concern
+    include StrongPresenter::Permissible
 
     module ClassMethods
       #   Automatically wraps multiple associations.
@@ -19,13 +20,14 @@ module StrongPresenter
       #   @return [void]
       def presents_association(association, options = {})
         options.assert_valid_keys(:with, :scope)
+        association = association.to_sym
         options[:with] = Associable.object_association_class(object_class, association) unless options.has_key? :with
         presenter_associations[association] ||= StrongPresenter::PresenterAssociation.new(association, options) do |presenter|
           presenter.link_permissions self, association
           yield presenter if block_given?
         end
         define_method(association) do
-          self.class.send(:presenter_associations)[association].wrap(self)
+          presenter_associations[association] ||= self.class.send(:presenter_associations)[association].wrap(self)
         end
       end
 
@@ -54,18 +56,50 @@ module StrongPresenter
       end
     end
 
+    # Permits given attributes, with propagation to associations.
+    # @param (see StrongPresenter::Permissible#permit!)
+    def permit! *attribute_paths
+      super
+      attribute_paths.each do |path| # propagate permit to associations
+        path = Array(path)
+        if path == [:**]
+          presenter_associations.each_value { |presenter| presenter.permit! [:**]}
+        elsif path.size>1
+          association = path[0].to_sym
+          presenter_associations[association].permit! path.drop(1) if presenter_associations.has_key?(association)
+        end
+      end
+      self
+    end
+
+    # Resets association presenters - clears the cache
+    def reload!
+      @presenter_associations.clear
+      self
+    end
+
+    private
+    def presenter_associations
+      @presenter_associations ||= {}
+    end
+
     protected
 
     # infer association class if possible
     def self.object_association_class(object_class, association)
-      if self.descendant_of(object_class, "ActiveRecord::Reflection")
-        association_class = object_class.reflect_on_association(association).klass
+      klass, collection = get_orm_association_info(object_class, association)
+      return nil if klass.nil?
+      "#{klass}Presenter".constantize
+    rescue NameError
+      get_collection_presenter(klass) if collection # else nil
+    end
+
+    def self.get_orm_association_info(object_class, association)
+      if descendant_of(object_class, "ActiveRecord::Reflection")
+        object_class.reflect_on_association(association).instance_eval { [klass, collection?] }
       else
-        return nil
+        nil
       end
-      "#{association_class}Presenter".constantize
-    rescue NameError
-      nil
     end
 
     def self.descendant_of(object_class, klass)
@@ -73,6 +107,12 @@ module StrongPresenter
     rescue NameError
       false
     end
+
+    def self.get_collection_presenter(klass)
+      "#{"#{klass}".pluralize}Presenter".constantize
+    rescue NameError
+      StrongPresenter::CollectionPresenter
+    end
   end
 end
 

data/lib/strong_presenter/collection_presenter.rb

@@ -14,12 +14,28 @@ module StrongPresenter
       options.assert_valid_keys(:with)
       @object = object
       @presenter_class = options[:with]
+
+      yield self if block_given?
     end
 
     def to_s
       "#<#{self.class.name} of #{presenter_class || "inferred presenters"} for #{object.inspect}>"
     end
 
+    # Permits given attributes, with propagation to collection items.
+    # @param (see StrongPresenter::Permissible#permit!)
+    def permit! *attribute_paths
+      super
+      @collection.each { |presenter| presenter.permit! *attribute_paths } unless @collection.nil?
+      self
+    end
+
+    # Resets item presenters - clears the cache
+    def reload!
+      @collection = nil
+      self
+    end
+
     protected
     # @return [Class] the presenter class used to present each item, as set by
     #   {#initialize}.

data/lib/strong_presenter/permissible.rb

@@ -2,13 +2,6 @@ module StrongPresenter
   module Permissible
     extend ActiveSupport::Concern
 
-    module ClassMethods
-      # Permits all presenter attributes for presents, present & filter methods.
-      def permit!
-        define_method(:permitted_attributes){ @permitted_attributes ||= StrongPresenter::Permissions.new.permit_all! }
-      end
-    end
-
     # Permits given attributes. May be invoked multiple times.
     #
     # @example Each argument represents a single attribute:
@@ -20,24 +13,23 @@ module StrongPresenter
     # @param [[Symbols*]*] attribute_paths
     #   the attributes to permit. An array of symbols represents an attribute path.
     # @return [self]
-    def permit *attribute_paths
-      permitted_attributes.permit permissions_prefix, *attribute_paths
+    def permit! *attribute_paths
+      permitted_attributes.permit *attribute_paths
       self
     end
 
     # Permits all presenter attributes for presents, present & filter methods.
-    def permit!
+    def permit_all!
       permitted_attributes.permit_all!
       self
     end
 
-    # Selects the attributes given which have been permitted - an array of attributes. Attributes are
-    # symbols, and attribute paths are arrays of symbols.
-    # @param [Array<Symbol>*] attribute_paths
+    # Selects the attributes given which have been permitted - an array of attributes
+    # @param [Array<Symbols>*] attribute_paths
     #   the attribute paths to check. The attribute paths may also have arguments.
-    # @return [Array<Array<Symbol>, Symbol>] attribute (paths)
-    def filter *attribute_paths
-      select_permitted(*attribute_paths).map{ |attribute| attribute.first if attribute.size == 1 } # un-pack symbol if array with single symbol
+    # @return [Array<Array<Symbol>>] attribute (paths)
+    def select_permitted *attribute_paths
+      permitted_attributes.select_permitted *attribute_paths
     end
 
     protected
@@ -45,29 +37,14 @@ module StrongPresenter
       @permitted_attributes ||= StrongPresenter::Permissions.new
     end
 
-    # Selects the attributes given which have been permitted - an array of attributes
-    # Each returned attribute paths will be an array, even if it consists of only 1 symbol
-    # @param [Array<Symbols>*] attribute_paths
-    #   the attribute paths to check. The attribute paths may also have arguments.
-    # @return [Array<Array<Symbol>>] attribute (paths)
-    def select_permitted *attribute_paths
-      permitted_attributes.select_permitted permissions_prefix, *attribute_paths
-    end
-
     # Links presenter to permissions group of given presenter.
     # @param [Presenter] parent_presenter
     # @param [Array<Symbol>] relative_path
     #   The prefix prepended before every permission check relative to parent presenter.
     def link_permissions parent_presenter, relative_path = []
-      self.permissions_prefix = parent_presenter.send(:permissions_prefix) + Array(relative_path)
-      @permitted_attributes = parent_presenter.send(:permitted_attributes).merge @permitted_attributes, permissions_prefix
+      @permitted_attributes = StrongPresenter::Permissions.new(parent_presenter.permitted_attributes, relative_path)
     end
 
-    private
-    attr_writer :permissions_prefix
-    def permissions_prefix
-      @permissions_prefix ||= []
-    end
   end
 end