openstax_utilities 2.0.0 → 2.1.0

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    YWZhYmU2NTY1MjJiZDNiNTE1YTFiZDI1YTk0YzcwYmY3ODAzZmEzMg==
+    NzdiOTJlYTJhMThlMWQzYjI0MGVkYWI1NzRlNjdlZmUyNmJmMzdlOQ==
   data.tar.gz: !binary |-
-    YWRhMTg0MmIyMmM3NGMzYzk4OWRlNWNmYTQ3NjA5MGYxMzdmMDNiZA==
+    YTQzYTI0YTEzMTQxZDZmZTNkNzQ0OWNkZGI2OWMwZWU5ZjQ3ZjA1ZQ==
 SHA512:
   metadata.gz: !binary |-
-    ZmEyNjIwM2YxMDI5YjkxNDc4MWUyM2NlZDhmZGVjZDYyNzZmMGQ5ZTJlMGI1
-    OTVjMjAxZDYxMTg0Yjg4ODljMDk4MWUxODIxMWYxOTMwZWY0NDI3MWRlNmUw
-    NzM5MjJmMmFkNDE1NmM0ZGY2MTdmMjljMGFhYzljZjdiN2I0YTA=
+    MjBhYTQ2NTc2ODAxNDgxYjhhYzFjYWVhYzFlZWJiOWMyMjBmN2Y5MzExYzgz
+    ZDdmZmI3N2RlMDgzMzMyMmUzMmFhOWVhNjk5OGIyYTdmZGUxNTEzZjY3YjRk
+    OWFlNTMxNmE0MzkzOWU4M2NlODIwMTk3ZDhlNGEzNGE3Njk0NTM=
   data.tar.gz: !binary |-
-    Mjc1YjE5MTYwMjZiM2RkMzQ3MGY3MmMxOGQ3ZjI3NGU0MGU3MDI3MjFmYTBi
-    YzhmY2YzMDU3OWU5NWZmNDkxZGM5OTg4MTI4NDVjYmQxMGE5NTA1Y2EzNWNk
-    NWNjNzE1ZGU1MjRiMTY2OWRkMWVkMzk2MGViNDc3ZWI1ZDk5NTQ=
+    YzYyY2Y0ZTMxOGQ3NGYxZTg3Y2M0NWEzNjZlNDI0N2RmMmYzYzkxMTg2OTk2
+    YWFjOTc4YjI2NDcxYTJkZTA3ZjgxNDdmMjM1NjhiMDFlZmVkOGYzZjM5Yzlj
+    YWNhYTlmNjM5NjlmODQyYTNjYWU5MGUxODQ2NjI5OTE1NmJhZGY=

data/README.md

@@ -9,4 +9,31 @@ To use this utility engine, include it in your Gemfile.
 
 ## Helpers
 
-This engine's helpers are available in the main application by preceding them with `osu.`, e.g. `osu.section_block('Heading') { "guts" }`
+This engine's helpers are available in the main application by preceding them with `osu.`, e.g. `osu.section_block('Heading') { "guts" }`
+
+## Access Policies
+
+As applications grow to include different kinds of users, including signed-in and anonymous human users, as well as other applications, the logic for controlling which user has which accesses to which resources can grow complex.  Controllers certainly aren't the place for this logic.  In a case with one kind of User, models *may* be the place for this logic but even then this makes models know way too much about other models.  
+
+Access Policies were created to be a dedicated place to store the logic controlling who has access to what.  All other code can ask the `AccessPolicy` class for this info, via the `action_allowed?` or the convenience methods `read_allowed?`, `create_allowed?`, etc.  `AccessPolicy` then delegates the access decisions off to other policy classes, of which there is normally one per kind of resource (e.g. a `UserAccessPolicy`, `ContactInfoPolicy`, etc).
+
+These resource-specific policy classes register themselves with the main `AccessPolicy` class, telling `AccessPolicy` what kinds of resources they can handle.  E.g. the `UserAccessPolicy` tells `AccessPolicy` it handles permissions for `User` with the following call:
+
+```rb
+OSU::AccessPolicy.register(User, UserAccessPolicy)
+```
+
+This call is typically made after the policy class' definition so that it is called when the Rails application is loaded. We recommend placing the policy classes under `app/access_policies`, as all files under the `app` directory are autoloaded by Rails.
+
+## Controller Extensions
+
+The following methods will be added to all controllers:
+
+`get_model(id_param, klass)` tries to use the id_param to return the model in question for
+restful actions, or a new instance of klass if the id could not be found.
+(e.g. on :new, :create and even :index)
+By default, id_param is :id and klass is controller_name.classify.constantize.
+
+`self.require_restful_actions_allowed!(options)` adds a before_filter that calls AccessPolicy.require_action_allowed! for all restful actions except :index. So by default it will add checks to :show, :new, :create, :edit, :update and :destroy.
+options is a hash that contains any desired before_filter options, plus the optional keys :id_param and :model_class, which are passed to get_model instead.
+By default, options is an empty hash.

data/Rakefile

@@ -1,48 +1,19 @@
 #!/usr/bin/env rake
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
 
-require 'bundler/gem_tasks'
+APP_RAKEFILE = File.expand_path("../spec/dummy/Rakefile", __FILE__)
+load 'rails/tasks/engine.rake'
 
-# begin
-#   require 'bundler/setup'
-# rescue LoadError
-#   puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
-# end
-# begin
-#   require 'rdoc/task'
-# rescue LoadError
-#   require 'rdoc/rdoc'
-#   require 'rake/rdoctask'
-#   RDoc::Task = Rake::RDocTask
-# end
-
-# RDoc::Task.new(:rdoc) do |rdoc|
-#   rdoc.rdoc_dir = 'rdoc'
-#   rdoc.title    = 'OpenstaxUtilities'
-#   rdoc.options << '--line-numbers'
-#   rdoc.rdoc_files.include('README.rdoc')
-#   rdoc.rdoc_files.include('lib/**/*.rb')
-# end
-
-# APP_RAKEFILE = File.expand_path("../test/dummy/Rakefile", __FILE__)
-
-
-# Bundler::GemHelper.install_tasks
-
-# # require 'rake/testtask'
-
-# # Rake::TestTask.new(:test) do |t|
-# #   t.libs << 'lib'
-# #   t.libs << 'test'
-# #   t.pattern = 'test/**/*_test.rb'
-# #   t.verbose = false
-# # end
-
-
-# # task :default => :test
+Bundler::GemHelper.install_tasks
 
+require 'rspec/core'
 require 'rspec/core/rake_task'
 
-RSpec::Core::RakeTask.new('spec')
+desc "Run all specs in spec directory (excluding plugin specs)"
+RSpec::Core::RakeTask.new(:spec => 'app:db:test:prepare')
 
-# If you want to make this the default task
-task :default => :spec
+task :default => :spec

data/lib/openstax/utilities/access_policy.rb

@@ -0,0 +1,54 @@
+# See the README
+
+module OpenStax
+  module Utilities
+    class AccessPolicy
+      include Singleton
+
+      attr_reader :resource_policy_map
+
+      def initialize()
+        @resource_policy_map = {}
+      end
+
+      def self.method_missing(method_name, *arguments, &block)
+        if method_name.to_s =~ /(.*)_allowed?/
+          action_allowed?(*arguments.unshift($1.to_sym), &block)
+        else
+          super
+        end
+      end
+
+      def self.respond_to_missing?(method_name, include_private = false)
+        method_name.to_s.end_with?('_allowed?') || super
+      end
+
+      def self.require_action_allowed!(action, requestor, resource)
+        raise SecurityTransgression unless action_allowed?(action, requestor, resource)
+      end
+
+      def self.action_allowed?(action, requestor, resource)
+
+        # If the incoming requestor is an ApiUser, choose to use either its
+        # human_user or its application.  If there is a human user involved, it
+        # should always take precedence when testing for access.
+        if defined?(ApiUser) && requestor.is_a?(ApiUser)
+          requestor = requestor.human_user ? requestor.human_user : requestor.application
+        end
+
+        resource_class = resource.is_a?(Class) ? resource : resource.class
+        policy_class = instance.resource_policy_map[resource_class.to_s]
+
+        # If there is no policy registered, we by default deny access
+        return false if policy_class.nil?
+
+        policy_class.action_allowed?(action, requestor, resource)
+      end
+
+      def self.register(resource_class, policy_class)
+        self.instance.resource_policy_map[resource_class.to_s] = policy_class
+      end
+
+    end
+  end
+end

data/lib/openstax/utilities/controller_extensions.rb

@@ -0,0 +1,47 @@
+module OpenStax
+  module Utilities
+    module ControllerExtensions
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      # Tries to find model if id is given, or returns a new model if not
+      def get_model(id_param = nil, klass = nil)
+        id_param ||= :id
+        id = params[id_param]
+        klass ||= controller_name.classify.constantize
+        id.nil? ? klass.new : klass.find(id)
+      end
+    
+      module ClassMethods
+        # Calls AccessPolicy.require_action_allowed! on all restful actions
+        # For create and update, the new params are not yet set
+        def require_restful_actions_allowed!(options = {})
+          class_eval do
+            before_filter({:only => [:show, :new, :create, :edit, :update,
+                          :destroy]}.merge(options.except(:id_param,
+                                                          :model_class))) do |c|
+
+              case c.action_name
+              when 'show'
+                action = :read
+              when 'new'
+                action = :create
+              when 'edit'
+                action = :update
+              else
+                action = c.action_name.to_sym
+              end
+
+              OSU::AccessPolicy.require_action_allowed!(action,
+                c.current_user, c.get_model(options[:id_param],
+                                            options[:model_class]))
+            end
+          end
+        end
+      end
+    end
+  end
+end
+
+ActionController::Base.send :include, OpenStax::Utilities::ControllerExtensions

data/lib/openstax/utilities/engine.rb

@@ -16,6 +16,12 @@ module OpenStax
           helper OSU::OsuHelper
         end
       end
+
+      config.generators do |g|
+        g.test_framework :rspec, :fixture => false
+        g.assets false
+        g.helper false
+      end
     end
   end
 end

data/lib/openstax/utilities/version.rb

@@ -1,5 +1,5 @@
 module OpenStax
   module Utilities
-    VERSION = "2.0.0"
+    VERSION = "2.1.0"
   end
 end

data/lib/openstax_utilities.rb

@@ -19,6 +19,8 @@ require "openstax/utilities/action_list"
 require "openstax/utilities/acts_as_numberable"
 require "openstax/utilities/delegate_access_control"
 require "openstax/utilities/roar"
+require "openstax/utilities/access_policy"
+require "openstax/utilities/controller_extensions"
 
 require "openstax/utilities/classy_helper"
 require "openstax/utilities/helpers/misc"

data/spec/dummy/README.md

@@ -0,0 +1 @@
+Dummy application used to test the openstax_utilities gem.

data/spec/dummy/app/access_policies/dummy_access_policy.rb

@@ -0,0 +1,10 @@
+class DummyAccessPolicy
+  cattr_accessor :last_action, :last_requestor, :last_resource
+
+  def self.action_allowed?(action, requestor, resource)
+    @@last_action = action
+    @@last_requestor = requestor
+    @@last_resource = resource
+    true
+  end
+end

data/spec/dummy/app/assets/stylesheets/scaffold.css

@@ -0,0 +1,56 @@
+body { background-color: #fff; color: #333; }
+
+body, p, ol, ul, td {
+  font-family: verdana, arial, helvetica, sans-serif;
+  font-size:   13px;
+  line-height: 18px;
+}
+
+pre {
+  background-color: #eee;
+  padding: 10px;
+  font-size: 11px;
+}
+
+a { color: #000; }
+a:visited { color: #666; }
+a:hover { color: #fff; background-color:#000; }
+
+div.field, div.actions {
+  margin-bottom: 10px;
+}
+
+#notice {
+  color: green;
+}
+
+.field_with_errors {
+  padding: 2px;
+  background-color: red;
+  display: table;
+}
+
+#error_explanation {
+  width: 450px;
+  border: 2px solid red;
+  padding: 7px;
+  padding-bottom: 0;
+  margin-bottom: 20px;
+  background-color: #f0f0f0;
+}
+
+#error_explanation h2 {
+  text-align: left;
+  font-weight: bold;
+  padding: 5px 5px 5px 15px;
+  font-size: 12px;
+  margin: -7px;
+  margin-bottom: 0px;
+  background-color: #c00;
+  color: #fff;
+}
+
+#error_explanation ul li {
+  font-size: 12px;
+  list-style: square;
+}

data/{test → spec}/dummy/app/controllers/application_controller.rb

@@ -1,3 +1,5 @@
 class ApplicationController < ActionController::Base
   protect_from_forgery
+
+  attr_accessor :current_user
 end

data/spec/dummy/app/controllers/users_controller.rb

@@ -0,0 +1,87 @@
+class UsersController < ApplicationController
+  # GET /users
+  # GET /users.json
+  def index
+    @users = User.all
+
+    respond_to do |format|
+      format.html # index.html.erb
+      format.json { render json: @users }
+    end
+  end
+
+  # GET /users/1
+  # GET /users/1.json
+  def show
+    @user = User.find(params[:id])
+
+    respond_to do |format|
+      format.html # show.html.erb
+      format.json { render json: @user }
+    end
+  end
+
+  # GET /users/new
+  # GET /users/new.json
+  def new
+    @user = User.new
+
+    respond_to do |format|
+      format.html # new.html.erb
+      format.json { render json: @user }
+    end
+  end
+
+  # GET /users/1/edit
+  def edit
+    @user = User.find(params[:id])
+  end
+
+  # POST /users
+  # POST /users.json
+  def create
+    @user = User.new
+    @user.username = params[:user][:username]
+    @user.password_hash = SecureRandom.hex(32)
+
+    respond_to do |format|
+      if @user.save
+        format.html { redirect_to @user, notice: 'User was successfully created.' }
+        format.json { render json: @user, status: :created, location: @user }
+      else
+        format.html { render action: "new" }
+        format.json { render json: @user.errors, status: :unprocessable_entity }
+      end
+    end
+  end
+
+  # PUT /users/1
+  # PUT /users/1.json
+  def update
+    @user = User.find(params[:id])
+    @user.username = params[:user][:username]
+    @user.password_hash = SecureRandom.hex(32)
+
+    respond_to do |format|
+      if @user.save
+        format.html { redirect_to @user, notice: 'User was successfully updated.' }
+        format.json { head :no_content }
+      else
+        format.html { render action: "edit" }
+        format.json { render json: @user.errors, status: :unprocessable_entity }
+      end
+    end
+  end
+
+  # DELETE /users/1
+  # DELETE /users/1.json
+  def destroy
+    @user = User.find(params[:id])
+    @user.destroy
+
+    respond_to do |format|
+      format.html { redirect_to users_url }
+      format.json { head :no_content }
+    end
+  end
+end

data/spec/dummy/app/models/user.rb

@@ -0,0 +1,2 @@
+class User < ActiveRecord::Base
+end

data/spec/dummy/app/views/users/_form.html.erb

@@ -0,0 +1,17 @@
+<%= form_for(@user) do |f| %>
+  <% if @user.errors.any? %>
+    <div id="error_explanation">
+      <h2><%= pluralize(@user.errors.count, "error") %> prohibited this user from being saved:</h2>
+
+      <ul>
+      <% @user.errors.full_messages.each do |msg| %>
+        <li><%= msg %></li>
+      <% end %>
+      </ul>
+    </div>
+  <% end %>
+
+  <div class="actions">
+    <%= f.submit %>
+  </div>
+<% end %>

data/spec/dummy/app/views/users/edit.html.erb

@@ -0,0 +1,6 @@
+<h1>Editing user</h1>
+
+<%= render 'form' %>
+
+<%= link_to 'Show', @user %> |
+<%= link_to 'Back', users_path %>

data/spec/dummy/app/views/users/index.html.erb

@@ -0,0 +1,21 @@
+<h1>Listing users</h1>
+
+<table>
+  <tr>
+    <th></th>
+    <th></th>
+    <th></th>
+  </tr>
+
+<% @users.each do |user| %>
+  <tr>
+    <td><%= link_to 'Show', user %></td>
+    <td><%= link_to 'Edit', edit_user_path(user) %></td>
+    <td><%= link_to 'Destroy', user, method: :delete, data: { confirm: 'Are you sure?' } %></td>
+  </tr>
+<% end %>
+</table>
+
+<br />
+
+<%= link_to 'New User', new_user_path %>

data/spec/dummy/app/views/users/new.html.erb

@@ -0,0 +1,5 @@
+<h1>New user</h1>
+
+<%= render 'form' %>
+
+<%= link_to 'Back', users_path %>

data/spec/dummy/app/views/users/show.html.erb

@@ -0,0 +1,5 @@
+<p id="notice"><%= notice %></p>
+
+
+<%= link_to 'Edit', edit_user_path(@user) %> |
+<%= link_to 'Back', users_path %>

data/spec/dummy/config/routes.rb

@@ -0,0 +1,5 @@
+Rails.application.routes.draw do
+  resources :users
+
+  mount OpenStax::Utilities::Engine => "/openstax_utilities"
+end

data/spec/dummy/db/migrate/0_create_users.rb

@@ -0,0 +1,10 @@
+class CreateUsers < ActiveRecord::Migration
+  def change
+    create_table :users do |t|
+      t.string :username
+      t.string :password_hash
+
+      t.timestamps
+    end
+  end
+end

data/spec/dummy/db/schema.rb

@@ -0,0 +1,23 @@
+# encoding: UTF-8
+# This file is auto-generated from the current state of the database. Instead
+# of editing this file, please use the migrations feature of Active Record to
+# incrementally modify your database, and then regenerate this schema definition.
+#
+# Note that this schema.rb definition is the authoritative source for your
+# database schema. If you need to create the application database on another
+# system, you should be using db:schema:load, not running all the migrations
+# from scratch. The latter is a flawed and unsustainable approach (the more migrations
+# you'll amass, the slower it'll run and the greater likelihood for issues).
+#
+# It's strongly recommended to check this file into your version control system.
+
+ActiveRecord::Schema.define(:version => 0) do
+
+  create_table "users", :force => true do |t|
+    t.string   "username"
+    t.string   "password_hash"
+    t.datetime "created_at",    :null => false
+    t.datetime "updated_at",    :null => false
+  end
+
+end

data/spec/lib/openstax/utilities/access_policy_spec.rb

@@ -0,0 +1,67 @@
+require 'spec_helper'
+
+module OpenStax
+  module Utilities
+
+    describe AccessPolicy do
+
+      let!(:user) { User.create }
+
+      it 'responds to any _allowed? calls' do
+        AccessPolicy.register(User, DummyAccessPolicy)
+
+        DummyAccessPolicy.last_action = nil
+        DummyAccessPolicy.last_requestor = nil
+        DummyAccessPolicy.last_resource = nil
+
+        expect(AccessPolicy.respond_to? :wacky_allowed?).to eq(true)
+        expect(AccessPolicy.wacky_allowed?(user, user)).to eq(true)
+
+        expect(DummyAccessPolicy.last_action).to eq(:wacky)
+        expect(DummyAccessPolicy.last_requestor).to eq(user)
+        expect(DummyAccessPolicy.last_resource).to eq(user)
+      end
+
+      it 'delegates checks to policy classes based on resource class' do
+        dummy_object = double('Dummy')
+        dummy_policy = double('Dummy Policy', :action_allowed? => true)
+
+        AccessPolicy.register(User, DummyAccessPolicy)
+        AccessPolicy.register(dummy_object.class, dummy_policy)
+        
+        DummyAccessPolicy.last_action = nil
+        DummyAccessPolicy.last_requestor = nil
+        DummyAccessPolicy.last_resource = nil
+
+        expect(AccessPolicy.action_allowed?(:read, user, dummy_object)).to(
+          eq(true))
+      
+        expect{AccessPolicy.require_action_allowed!(:read, user, dummy_object)
+          }.not_to raise_error
+
+        expect(DummyAccessPolicy.last_action).to be_nil
+        expect(DummyAccessPolicy.last_requestor).to be_nil
+        expect(DummyAccessPolicy.last_resource).to be_nil
+
+        expect(AccessPolicy.action_allowed?(:create, user, User.new)).to(
+          eq(true))
+
+        expect{AccessPolicy.require_action_allowed!(:create, user, User.new)
+          }.not_to raise_error
+
+        expect(DummyAccessPolicy.last_action).to eq(:create)
+        expect(DummyAccessPolicy.last_requestor).to eq(user)
+        expect(DummyAccessPolicy.last_resource).to be_instance_of(User)
+        expect(DummyAccessPolicy.last_resource.id).to be_nil
+      end
+
+      it 'denies permission if the policy class is not registered' do
+        expect(OSU::AccessPolicy.action_allowed?(:destroy, user, Object)).to eq(false)
+
+        expect{OSU::AccessPolicy.require_action_allowed!(:destroy, user, Object)}.to raise_error(SecurityTransgression)
+      end
+
+    end
+
+  end
+end