rails-acu 1.2.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: c5e4832b86ac7f688e4f9a710bc490471b33dc8e
+  data.tar.gz: fd9a65c185a13acf5e40b03037aedf246cc9229c
+SHA512:
+  metadata.gz: 0a15a8d3858a25f9cc9e121b736632c8cc2d16f5ffd68ac107b4f66d3720242a69f076f6c48ded26f276ceb56e0d4f6cef16aed6d2706341dbe657d22e780457
+  data.tar.gz: 57d389156e2682b7ba1959842ba943f5dd2dcec89cb5b5679c4ca821cdcb8947b327196904d8bec72e69d862caa3d130bbf8e18aba51329e1c587644fb914d19

data/.gitignore

@@ -0,0 +1,8 @@
+.bundle/
+log/*.log
+pkg/
+spec/dummy/db/*.sqlite3
+spec/dummy/db/*.sqlite3-journal
+spec/dummy/log/*.log
+spec/dummy/tmp/
+*.byebug_history

data/.project

@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<projectDescription>
+	<name>acu</name>
+	<comment></comment>
+	<projects>
+	</projects>
+	<buildSpec>
+		<buildCommand>
+			<name>com.aptana.ide.core.unifiedBuilder</name>
+			<arguments>
+			</arguments>
+		</buildCommand>
+	</buildSpec>
+	<natures>
+		<nature>org.radrails.rails.core.railsnature</nature>
+		<nature>com.aptana.ruby.core.rubynature</nature>
+	</natures>
+</projectDescription>

data/.rspec

@@ -0,0 +1,3 @@
+--color
+--format documentation
+--require spec_helper

data/.travis.yml

@@ -0,0 +1,30 @@
+language: ruby
+
+rvm:
+  - 2.4.0
+
+cache: bundler
+
+sudo: false
+
+env:
+  - RAILS_ENV=test
+
+matrix:
+  fast_finish: true
+
+before_install:
+  - gem update --system 2.6.11
+  - gem install bundler -v 1.14.6
+
+script:
+  - export RAILS_ENV=test
+  - bundle exec rake db:create
+  - bundle exec rake db:migrate
+  - bundle exec rake db:seed
+  - bundle exec rspec
+
+notifications:
+  email:
+    recipients:
+      - b.g.dariush@gmail.com

data/Gemfile

@@ -0,0 +1,30 @@
+source 'https://rubygems.org'
+
+git_source(:github) do |repo_name|
+  repo_name = "#{repo_name}/#{repo_name}" unless repo_name.include?("/")
+  "https://github.com/#{repo_name}.git"
+end
+
+# Declare your gem's dependencies in acu.gemspec.
+# Bundler will treat runtime dependencies like base dependencies, and
+# development dependencies will be added by default to the :development group.
+gemspec
+
+# Declare any dependencies that are still in development here instead of in
+# your gemspec. These might include edge Rails or gems from your path or
+# Git. Remember to move these dependencies to your gemspec before releasing
+# your gem to rubygems.org.
+
+# To use a debugger
+# gem 'byebug', group: [:development, :test]
+
+group :development, :test do
+  # Call 'byebug' anywhere in the code to stop execution and get a debugger console
+  gem 'byebug', platform: :mri
+  gem 'rspec-rails', '~> 3.5'
+  gem 'sqlite3'
+  gem 'awesome_print', github: 'awesome-print/awesome_print'
+  gem 'devise'
+  gem 'jquery-rails'
+  gem 'rails-controller-testing'
+end

data/Gemfile.lock

@@ -0,0 +1,169 @@
+GIT
+  remote: https://github.com/awesome-print/awesome_print.git
+  revision: 551bb9cd306aee74e338c92316c8709ff71fb305
+  specs:
+    awesome_print (1.7.0)
+
+PATH
+  remote: .
+  specs:
+    rails-acu (1.2.1)
+      rails (~> 5.0.0, >= 5.0.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    actioncable (5.0.2)
+      actionpack (= 5.0.2)
+      nio4r (>= 1.2, < 3.0)
+      websocket-driver (~> 0.6.1)
+    actionmailer (5.0.2)
+      actionpack (= 5.0.2)
+      actionview (= 5.0.2)
+      activejob (= 5.0.2)
+      mail (~> 2.5, >= 2.5.4)
+      rails-dom-testing (~> 2.0)
+    actionpack (5.0.2)
+      actionview (= 5.0.2)
+      activesupport (= 5.0.2)
+      rack (~> 2.0)
+      rack-test (~> 0.6.3)
+      rails-dom-testing (~> 2.0)
+      rails-html-sanitizer (~> 1.0, >= 1.0.2)
+    actionview (5.0.2)
+      activesupport (= 5.0.2)
+      builder (~> 3.1)
+      erubis (~> 2.7.0)
+      rails-dom-testing (~> 2.0)
+      rails-html-sanitizer (~> 1.0, >= 1.0.3)
+    activejob (5.0.2)
+      activesupport (= 5.0.2)
+      globalid (>= 0.3.6)
+    activemodel (5.0.2)
+      activesupport (= 5.0.2)
+    activerecord (5.0.2)
+      activemodel (= 5.0.2)
+      activesupport (= 5.0.2)
+      arel (~> 7.0)
+    activesupport (5.0.2)
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      i18n (~> 0.7)
+      minitest (~> 5.1)
+      tzinfo (~> 1.1)
+    arel (7.1.4)
+    bcrypt (3.1.11)
+    builder (3.2.3)
+    byebug (9.0.6)
+    concurrent-ruby (1.0.5)
+    devise (4.2.1)
+      bcrypt (~> 3.0)
+      orm_adapter (~> 0.1)
+      railties (>= 4.1.0, < 5.1)
+      responders
+      warden (~> 1.2.3)
+    diff-lcs (1.3)
+    erubis (2.7.0)
+    globalid (0.3.7)
+      activesupport (>= 4.1.0)
+    i18n (0.8.1)
+    jquery-rails (4.3.1)
+      rails-dom-testing (>= 1, < 3)
+      railties (>= 4.2.0)
+      thor (>= 0.14, < 2.0)
+    loofah (2.0.3)
+      nokogiri (>= 1.5.9)
+    mail (2.6.4)
+      mime-types (>= 1.16, < 4)
+    method_source (0.8.2)
+    mime-types (3.1)
+      mime-types-data (~> 3.2015)
+    mime-types-data (3.2016.0521)
+    mini_portile2 (2.1.0)
+    minitest (5.10.1)
+    nio4r (2.0.0)
+    nokogiri (1.7.1)
+      mini_portile2 (~> 2.1.0)
+    orm_adapter (0.5.0)
+    rack (2.0.1)
+    rack-test (0.6.3)
+      rack (>= 1.0)
+    rails (5.0.2)
+      actioncable (= 5.0.2)
+      actionmailer (= 5.0.2)
+      actionpack (= 5.0.2)
+      actionview (= 5.0.2)
+      activejob (= 5.0.2)
+      activemodel (= 5.0.2)
+      activerecord (= 5.0.2)
+      activesupport (= 5.0.2)
+      bundler (>= 1.3.0, < 2.0)
+      railties (= 5.0.2)
+      sprockets-rails (>= 2.0.0)
+    rails-controller-testing (1.0.1)
+      actionpack (~> 5.x)
+      actionview (~> 5.x)
+      activesupport (~> 5.x)
+    rails-dom-testing (2.0.2)
+      activesupport (>= 4.2.0, < 6.0)
+      nokogiri (~> 1.6)
+    rails-html-sanitizer (1.0.3)
+      loofah (~> 2.0)
+    railties (5.0.2)
+      actionpack (= 5.0.2)
+      activesupport (= 5.0.2)
+      method_source
+      rake (>= 0.8.7)
+      thor (>= 0.18.1, < 2.0)
+    rake (12.0.0)
+    responders (2.3.0)
+      railties (>= 4.2.0, < 5.1)
+    rspec-core (3.5.4)
+      rspec-support (~> 3.5.0)
+    rspec-expectations (3.5.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.5.0)
+    rspec-mocks (3.5.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.5.0)
+    rspec-rails (3.5.2)
+      actionpack (>= 3.0)
+      activesupport (>= 3.0)
+      railties (>= 3.0)
+      rspec-core (~> 3.5.0)
+      rspec-expectations (~> 3.5.0)
+      rspec-mocks (~> 3.5.0)
+      rspec-support (~> 3.5.0)
+    rspec-support (3.5.0)
+    sprockets (3.7.1)
+      concurrent-ruby (~> 1.0)
+      rack (> 1, < 3)
+    sprockets-rails (3.2.0)
+      actionpack (>= 4.0)
+      activesupport (>= 4.0)
+      sprockets (>= 3.0.0)
+    sqlite3 (1.3.13)
+    thor (0.19.4)
+    thread_safe (0.3.6)
+    tzinfo (1.2.3)
+      thread_safe (~> 0.1)
+    warden (1.2.7)
+      rack (>= 1.0)
+    websocket-driver (0.6.5)
+      websocket-extensions (>= 0.1.0)
+    websocket-extensions (0.1.2)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  awesome_print!
+  byebug
+  devise
+  jquery-rails
+  rails-acu!
+  rails-controller-testing
+  rspec-rails (~> 3.5)
+  sqlite3
+
+BUNDLED WITH
+   1.14.6

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2017 Dariush Hasanpour
+
+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,221 @@
+[![Build Status](https://travis-ci.org/noise2/rails-acu.svg?branch=master)](https://travis-ci.org/noise2/rails-acu)
+
+# ACU
+ACU is the acronym for **A**ccess **C**ontrol **U**nit, and it's designed to give the 100% control over permissions on multiple levels of rails application's structure.
+The software engineering of this gem tends to make it much faster and simple. All you have to do is to define the **entities** of your authentications (i.e `what is who?`)
+and write the rules for them based on `allow`/`deny` binary logic, and everything else will be done automatically.
+
+## Installation
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'rails-acu'
+```
+
+And then execute:
+```bash
+$ bundle
+```
+
+Or install it yourself as:
+```bash
+$ gem install rails-acu
+```
+
+Then install it in you app using:
+
+```bash
+rails generate acu:install
+```
+
+## Usage
+After installation using `rails generate acu:install`  two files will be created:
+
+```bash
+create  config/initializers/acu_setup.rb
+create  config/initializers/acu_rules.rb
+```
+The file `acu_setup.rb` is the configuration of ACU gem, you can leave it alone and use the default configurations or customize it as desired,
+we will talk about the configuration later.
+
+The other hand the `acu_rules.rb` is where you put your access rules there, access rules are binary, _either an entity can access a resource or not_ -
+in this gem, resource means any of `namespace`, `controller` and `action`. here as an example `acu_rules.rb` and we explain its components in the following:
+
+```ruby
+# config/initializers/acu_rules.rb
+Acu::Rules.define do
+  # anyone makes a request could be count as everyone!
+  whois :everyone { true }
+
+  whois :admin, args: [:user] { |c| c and c.user_type == :ADMIN.to_s }
+
+  whois :client, args: [:user] { |c| c and c.user_type == :CLIENT.to_s }
+
+  # the default namespace
+  namespace do
+    controller :home, except: [:some_secret_action] do
+      allow :everyone
+    end
+    controller :home do
+      allow [:admin, :client], on: [:some_secret_action]
+    end
+  end
+
+  # the admin namespace
+  namespace :admin do
+    allow :admin
+
+    controller :contact, only: [:send_message] do
+      allow :everyone
+    end
+
+    controller :contact do
+      action :support {
+        allow :client
+      }
+    end
+  end
+end
+```
+
+As we define our rules at the first line, we have to say who are the entities? _to whom we call who?_ for this purpose I have come up with a simple entity definition `whois`, it takes three arguments (1 of them is optional: `args`), first the label of the entity, in this example they are `:everyone, :admin` and `:client`, the second argument (which is optional) is the variables that are going to be used to determining if the current request has been initiated by the entity or not, and the final argument is a block which its job is to determine who is the defined entity!
+
+Once we defined our entities we can set their binary access permissions at namespace/controller/action levels using `allow` and `deny` helpers. **that is it, we are done tutorialing; from now on is just tiny details. :)**
+
+> **Scenario:** We have a *public* site which serves to its client's; we have 2 namespaces on this site, one is the _default_ namespace with _home_ controller in it, and the second namespace belongs to the _admin_ of site which has many controllers and also a _contact_ controller.<br />
+We want to grant access to everyone for all of _home_ controller actions in _default_ namespace **except** the `some_secret_action`; but this `some_secret_action` can be accessed via the `:admin` and `:client` entities.<br />
+By default only `:admin` can access to the _admin_ namespace, but we made an exception for 2 actions in the `Admin::ContactController` which everyone can `send_message` to the admin and only clients can ask for `support`.<br />
+If you back trace it in the above example you can easily find this scenario in the rules, plain and simple.
+
+### Entities' arguments
+Occasionally there is some situation that you need to pass the some argument in the entities to be able to determine the entity (i.e you cannot get it from `session`, `global variables/function` or directly from `database`) for such situations you can pass the arguments in one of the **base controller**'s `before_action`s as below:
+
+```ruby
+class ApplicationController < ActionController::Base
+  protect_from_forgery with: :exception
+
+  before_action { Acu::Monitor.by user: some_way_to_fetch_it }
+end
+```
+The method `Acu::Monitor.by` accepts with a hashed list of agruments, please note that the keys should be identical to the entities' `args` argument.
+
+### Some handy helpers
+Although you can define a binary allow/deny access rule in the `acu_rules.rb` file but there will be some gray area that neither you can allow _full access_ to the resource nor _no access_.<br />
+for those situations you allow the entities to get access but limits their operations in the action/view/layout with the `acu_is?` and `acu_as` helpers, here is some usage example of them:
+
+```ruby
+# return true if the entity `:admin`'s block in `whois :admin` return true, otherwise false
+acu_is? :admin
+# returns true if any of the given entity's block return true; if none of the was valid, returns false.
+acu_is? [:admin, :client]
+
+# executes the block if current user identified as an admin by `whois :admin`
+acu_as :admin do
+  puts 'You are identified as an `admin`'
+end
+# executes the block if current user identified as either `:admin` or `:client`
+acu_as [:admin, :client] do
+  puts 'You are either `admin` or `client`'
+end
+```
+
+### Configurations
+One of the files that `acu:install` command will generate is `acu_setup.rb` which contains the configuration for the gem, the default configurations are as following:
+
+```ruby
+Acu.setup do |config|
+  # name it to the Base Application Controller that your project
+  # is going to use as a base of all of your controllers.
+  config.base_controller = :ApplicationController
+
+  # to tighten the security this is enabled by default
+  # i.e if it checked to be true, then if a request didn't match to any of rules, it will get passed through
+  # otherwise the requests which don't fit into any of rules, the request is denied by default
+  config.allow_by_default = false
+
+  # the audit log file, to log how the requests handles, good for production
+  # leave it black for nil to disable the logging
+  config.audit_log_file   = ""
+
+  # cache the rules to make rule matching much faster
+  # it's not recommended to use it in developement/test evn.
+  config.use_cache = false
+
+  # the caching namespace
+  config.cache_namespace = 'acu'
+
+  # define the expiration of cached entries
+  config.cache_expires_in = nil
+
+  # the race condition ttl
+  config.cache_race_condition_ttl = nil
+
+  # more details about cache options:
+  # http://guides.rubyonrails.org/caching_with_rails.html
+end
+```
+
+Here are the details of the configurations:
+
+| Name | Default | Description |
+| ----- |-------| ------ |
+| base_controller | `:ApplicationController` | In order that ACU gem to work it will attach some utilities to the base controller of all controllers, so if your base controller's name is something else change it. |
+| allow_by_default | `false` | Set it `true` if you want to grant access to requests that doesn't fit to any rules you have defined (**Warning:** please be advised, setting it `true` may cause a security hole in your website if you don't cover the rules perfectly!). |
+| audit_log_file |  | The audit log file, useful for rules debugging! |
+| use_cache | `false` | ACU can utilize the `Rails.cache` to make the rules matching much faster by caching them, but if caching is enabled and you change the please make user you have cleared the ACU caches by `Acu::Monitor.clear_cache`. |
+| cache_* | 'acu' or `nil` | See rails [caching options](http://guides.rubyonrails.org/caching_with_rails.html#activesupport-cache-store) for details. |
+
+### API
+Here are the list of APIs that didn't mentioned above:
+
+| API | Arguments | Alias | Description |
+| ----- | :-------: | :------: | ---- |
+| `Acu::Configs.get` | `name` | N/A | Get the value of the `name`ed config |
+| `Acu::Monitor.by` | `kwargs` | N/A | Set the arguments demaned by blocks in `whois` |
+| `Acu::Monitor.clear_cache` | None | N/A | Clears the ACU's rule matching cache |
+| `Acu::Monitor.clear_args` | None | N/A | Clears the argument set by `Acu::Monitor.by` |
+| `Acu::Monitor.valid_for?` | `entity` | `acu_is?` | Check if the current request is come from the entity or not |
+| `Acu::Monitor.gaurd` | None | N/A | Validates the current request, this is called automatically just before Rails start calling the _action_ |
+| `Acu::Rules.define` | `&block` | N/A | Get a block of rules, **Note** that there could be mutliple `Acu::Rules.define` in your project, the rules will all merge together as a one, so you can have mutliple `acu_rule*.rb` file in your `config/initialize` and they will merge together |
+| `Acu::Rules.reset` | None | N/A | Resets everything in the `Acu::Rules` |
+| `Acu::Rule.lock` | None | N/A | Freezes the rules, you can set it at the _end of the last_ `acu_rule*.rb` file. |
+
+
+### Exceptions
+Here are the list of exceptions defined in ACU gem:
+
+```ruby
+class Acu::Errors::AccessDenied < StandardError
+
+class Acu::Errors::UncheckedPermissions < StandardError
+
+class Acu::Errors::InvalidSyntax < StandardError
+
+class Acu::Errors::AmbiguousRule < StandardError
+
+class Acu::Errors::InvalidData < StandardError
+
+class Acu::Errors::MissingData < InvalidData
+
+class Acu::Errors::MissingEntity < MissingData
+
+class Acu::Errors::MissingUser < MissingData
+
+class Acu::Errors::MissingAction < MissingData
+
+class Acu::Errors::MissingController < MissingData
+
+class Acu::Errors::MissingNamespace < MissingData
+```
+
+
+
+## Contributing
+In order contributing to this project:
+1. Fork
+2. Make changes/upgrades/fixes etc
+3. Write a through tests
+4. Make a pull request to the `develop` branch
+
+## License
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).