sinatra-bouncer 1.3.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6b8592539c3824fa1985a4c02b877bd7d53e6ab2635f4227b173325f16484465
-  data.tar.gz: 1aac0ef35f8584e83cbafd5843172798f8967ad217235f9048e476cf3cc8945f
+  metadata.gz: 849fed52904df15b1cc036685383f197e47aae52bef8283a81decc281fc95660
+  data.tar.gz: 3a3ba41d0d3c2ad70b1c4e48b81558213111d86a750717e2b8f44dea9072ca1f
 SHA512:
-  metadata.gz: 83ed25a0acff1d864f978dbbd3667d20f53be0bea36fa5db5abd55eeb4353cad53e29ebeb424f1c462e4a8790444f4a5850cad33c579729aab684ff4f0d482aa
-  data.tar.gz: a3caa0c02709faa60e5512f73f2b4c4f21066f519999e014ffac2545271198d8a98a7a73d430494a185a00e0ea255170e1693274c7fb8bca51b56c6108fcd8a6
+  metadata.gz: d63e6a5437ef4d71e7183dce458241a8efaebace1c6f95e77766412f2faf2d5d490107a4e925588509dfb8e73b0c2e3a21064e73aae4cb3f98ae0c8465f19dd5
+  data.tar.gz: ca6d627ae51d9ecf6c88ffa21621117adb3af2eee6c83d14846f8ac7a5aa314f9ce4d2d10c30baf192e4a7c435f750bfb5b9bc3c37ed308ee4a5255a8df0eacf

data/.gitignore

@@ -4,9 +4,6 @@
 # or operating system, you probably want to add a global ignore instead:
 #   git config --global core.excludesfile ~/.gitignore_global
 
-# Ignore bundler config
-/.bundle
-
 # Ignore all logfiles and tempfiles.
 *.log
 tmp/*
@@ -17,7 +14,5 @@ tmp/*
 # Ignore all gem files.
 *.gem
 
-core/config.yml
-persist/database.yml
-
-Gemfile.lock
+# Ignore simplecov results
+.coverage/

data/.rubocop.yml

@@ -3,6 +3,7 @@ inherit_from: ~/.config/rubocop/config.yml
 AllCops:
   Exclude:
     - 'bin/*'
+    - 'benchmarks/*'
 
 Layout/LineLength:
   Exclude:
@@ -11,12 +12,3 @@ Layout/LineLength:
 # setting to 6 to match RubyMine autoformat
 Layout/FirstArrayElementIndentation:
   IndentationWidth: 6
-
-# rspec blocks are huge by design
-Metrics/BlockLength:
-  Exclude:
-    - 'tests/spec/**/*.rb'
-
-Metrics/ModuleLength:
-  Exclude:
-    - 'tests/spec/**/*.rb'

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,49 @@
+# Contributor Code of Conduct
+
+As contributors and maintainers of this project, and in the interest of
+fostering an open and welcoming community, we pledge to respect all people who
+contribute through reporting issues, posting feature requests, updating
+documentation, submitting pull requests or patches, and other activities.
+
+We are committed to making participation in this project a harassment-free
+experience for everyone, regardless of level of experience, gender, gender
+identity and expression, sexual orientation, disability, personal appearance,
+body size, race, ethnicity, age, religion, or nationality.
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery
+* Personal attacks
+* Trolling or insulting/derogatory comments
+* Public or private harassment
+* Publishing other's private information, such as physical or electronic
+  addresses, without explicit permission
+* Other unethical or unprofessional conduct
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+By adopting this Code of Conduct, project maintainers commit themselves to
+fairly and consistently applying these principles to every aspect of managing
+this project. Project maintainers who do not follow or enforce the Code of
+Conduct may be permanently removed from the project team.
+
+This code of conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting a project maintainer at robin@tenjin.ca. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. Maintainers are
+obligated to maintain confidentiality with regard to the reporter of an
+incident.
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 1.3.0, available at
+[http://contributor-covenant.org/version/1/3/0/][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/3/0/

data/Gemfile

@@ -7,13 +7,14 @@ gemspec
 
 group :development do
    gem 'bundler', '~> 2.4'
-   gem 'rake', '~> 13.0'
+   gem 'rake', '~> 13.1'
+   gem 'rubocop', '~> 1.57'
+   gem 'rubocop-performance', '~> 1.19'
    gem 'yard', '~> 0.9'
 end
 
 group :test do
-   gem 'capybara', '~> 3.39'
-   gem 'cucumber', '~> 8.0'
+   gem 'rack-test', '~> 2.1'
    gem 'rspec', '~> 3.12'
    gem 'simplecov', '~> 0.22'
 end

data/Gemfile.lock

@@ -0,0 +1,92 @@
+PATH
+  remote: .
+  specs:
+    sinatra-bouncer (3.0.0)
+      sinatra (>= 2.2)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ast (2.4.2)
+    diff-lcs (1.5.0)
+    docile (1.4.0)
+    json (2.6.3)
+    language_server-protocol (3.17.0.3)
+    mustermann (3.0.0)
+      ruby2_keywords (~> 0.0.1)
+    parallel (1.23.0)
+    parser (3.2.2.4)
+      ast (~> 2.4.1)
+      racc
+    racc (1.7.3)
+    rack (2.2.8)
+    rack-protection (3.1.0)
+      rack (~> 2.2, >= 2.2.4)
+    rack-test (2.1.0)
+      rack (>= 1.3)
+    rainbow (3.1.1)
+    rake (13.1.0)
+    regexp_parser (2.8.2)
+    rexml (3.2.6)
+    rspec (3.12.0)
+      rspec-core (~> 3.12.0)
+      rspec-expectations (~> 3.12.0)
+      rspec-mocks (~> 3.12.0)
+    rspec-core (3.12.2)
+      rspec-support (~> 3.12.0)
+    rspec-expectations (3.12.3)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.12.0)
+    rspec-mocks (3.12.6)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.12.0)
+    rspec-support (3.12.1)
+    rubocop (1.57.2)
+      json (~> 2.3)
+      language_server-protocol (>= 3.17.0)
+      parallel (~> 1.10)
+      parser (>= 3.2.2.4)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.8, < 3.0)
+      rexml (>= 3.2.5, < 4.0)
+      rubocop-ast (>= 1.28.1, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 3.0)
+    rubocop-ast (1.30.0)
+      parser (>= 3.2.1.0)
+    rubocop-performance (1.19.1)
+      rubocop (>= 1.7.0, < 2.0)
+      rubocop-ast (>= 0.4.0)
+    ruby-progressbar (1.13.0)
+    ruby2_keywords (0.0.5)
+    simplecov (0.22.0)
+      docile (~> 1.1)
+      simplecov-html (~> 0.11)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-html (0.12.3)
+    simplecov_json_formatter (0.1.4)
+    sinatra (3.1.0)
+      mustermann (~> 3.0)
+      rack (~> 2.2, >= 2.2.4)
+      rack-protection (= 3.1.0)
+      tilt (~> 2.0)
+    tilt (2.2.0)
+    unicode-display_width (2.5.0)
+    yard (0.9.34)
+
+PLATFORMS
+  x86_64-linux
+
+DEPENDENCIES
+  bundler (~> 2.4)
+  rack-test (~> 2.1)
+  rake (~> 13.1)
+  rspec (~> 3.12)
+  rubocop (~> 1.57)
+  rubocop-performance (~> 1.19)
+  simplecov (~> 0.22)
+  sinatra-bouncer!
+  yard (~> 0.9)
+
+BUNDLED WITH
+   2.4.19

data/README.md

@@ -1,108 +1,285 @@
-#Sinatra-Bouncer
-Simple authorization permissions extension for [Sinatra](http://www.sinatrarb.com/). Require the gem, then declare which routes are permitted based on your own logic. 
+# Sinatra-Bouncer
+
+Simple permissions extension for [Sinatra](http://www.sinatrarb.com/). Require the gem, then declare which
+routes are permitted based on your own logic.
+
+## Big Picture
+
+Bouncer's syntax looks like:
 
-**Gemfile**
 ```ruby
-gem 'sinatra-bouncer'
+# You can define roles to collect permissions together
+bouncer.role :admins do
+   current_user&.admin?
+end
+
+bouncer.rules do
+   # Routes match based on one or more strings. 
+   anyone.can get:  '/',
+              post: ['/user/sign-in',
+                     '/user/sign-out']
+
+   # Wildcards match anything directly under that path 
+   anyone.can get: '/lib/js/*'
+
+   admins.can get:  '/admin/*',
+              post: '/admin/actions/*'
+
+   # ... etc ...
+end
 ```
 
-**Terminal**
-```sh
-gem install sinatra-bouncer
+### Features
+
+Here's what this Gem provides:
+
+* **Block-by-default**
+    * Any route must be explicitly allowed
+* **Role-Oriented**
+    * The [DSL](https://en.wikipedia.org/wiki/Domain-specific_language) is constructed to be easily readable
+* **Declarative Syntax**
+    * Straightforward syntax reduces complexity of layered permissions
+    * Keeps permissions together for clarity
+* **Conditional Logic Via Blocks**
+    * Often additional checks must be performed to know if a route is allowed.
+* **Grouping**
+    * Routes can be matched by wildcard
+* **Forced Boolean Affirmation**
+    * Condition blocks must explicitly return `true`, avoiding accidental truthy values
+
+### Anti-Features
+
+Bouncer intentionally does not support some concepts.
+
+* **No User Identification** *(aka Authentication)*
+    * Bouncer is not a user identification gem. It assumes you already have an existing solution
+      like [Warden](https://github.com/wardencommunity/warden). Knowing *who* someone is is already a complex enough
+      problem and should be separate from what they may do.
+* **No Rails Integration**
+    * Bouncer is not intended to work with Rails. Use one of the Rails-based permissions gems for these situations.
+* **No Negation**
+    * There is intentionally no negation (eg. `cannot`) to preserve the default-deny frame of mind
+
+## Installation
+
+Add this to your gemfile:
+
+```ruby
+gem 'sinatra-bouncer'
 ```
 
-##Quickstart
-###Step 1: Require/Register Bouncer
+Then run:
 
-After registration, Bouncer will reject any request that either:
-* has no rule associated with it, or
-* has no associated rule that returns `true`
+```shell
+bundle install
+```
+
+**Sinatra Modular Style**
 
-**Sinatra Classic**
 ```ruby
-require 'sinatra'
+require 'sinatra/base'
 require 'sinatra/bouncer'
 
+class MyApp < Sinatra::Base
+   register Sinatra::Bouncer
+
+   bouncer.rules do
+      # ... can statements ...
+   end
+
    # ... routes and other config
+end
 ```
 
-**Modular**
+**Sinatra Classic Style**
+
 ```ruby
-require 'sinatra/base'
+require 'sinatra'
 require 'sinatra/bouncer'
 
-class MyApp < Sinatra::Base
-  register Sinatra::Bouncer
-  
-  # ... routes and other config
+bouncer.rules do
+   # ... can statements ...
 end
+
+# ... routes and other config
 ```
 
-###Step 2: Declare Bouncer Rules
-Call `rules` with a block that uses `can` and `can_sometimes` to declare which paths are legalduring this request.  The rules block is run in the context of the request, which means you will have access to sinatra helpers, 
-the `request` object, and `params`.
+## Usage
+
+Define roles using the `role` method and provide each one with a condition block. Then call `rules` with a block that
+uses your defined roles with the `#can` or `#can_sometimes` DSL methods to declare which
+paths are allowed.
+
+The rules block is run once as part of the configuration phase but the condition blocks are evaluated in the context of
+the request handler. This means they have access to Sinatra helpers, the `request` object, and `params`.
 
 ```ruby
 require 'sinatra'
 require 'sinatra/bouncer'
 
-rules do
-  # example: allow any GET request
-  can(:get, :all)
-  
-  # example: logged in users can edit their account
-  if(current_user)
-    can(:post, '/user_edits_account')
-  end
+bouncer.role :members do
+   !current_user.nil?
+end
+
+bouncer.role :bots do
+   !request.get_header('X-CUSTOM-BOT').nil?
+end
+
+bouncer.rules do
+   # example: always allow GET requests to '/' and '/about'; and POST requests to '/sign-in'
+   anyone.can get:  ['/', '/about'],
+              post: '/sign-in'
+
+   # example: logged in users can view (GET) member restricted paths and edit their account (POST)
+   members.can get: '/members/*'
+   members.can_sometimes post: '/members/edit-account' do
+      current_user && current_user.id == params[:id]
+   end
+
+   # example: require presence of arbitrary request header in the role condition
+   bots.can get: '/bots/*'
 end
 
-# ... route declarations as normal below
+# ... Sinatra route declarations as normal ... 
 ```
 
-## API
-#### can
-Any route declared with #can will be accepted without further challenge. 
+### Role Declarations
+
+Roles are declared using the `#role` method in your Sinatra config. Each one must be provided a condition block that
+must return exactly `true` when the role applies.
 
 ```ruby
-rules do
-   can(:post, '/user_posts_blog')
+# let's pretend that current_user is a helper that returns the user from Warden
+bouncer.role :admins do
+   current_user&.admin?
 end
 ```
 
-####can_sometimes
-`can_sometimes` is for occasions that you to check further, but want to defer that choice until the path is actually attempted.
-`can_sometimes` takes a block that will be run once the path is attempted. This block **must return an explicit boolean** 
-(ie. `true` or `false`) to avoid any accidental truthy values creating unwanted access.
+> **Note:** There is a default role called `anyone` that is always declared for you.
+
+### HTTP Method and Route Matching
+
+Both `#can` and `#can_sometimes` accept symbol
+[HTTP methods](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods) as keys
+and each key is paired with one or more path strings.
+
+```ruby
+# example: single method, single route 
+anyone.can get: '/'
+
+# example: multiple methods, single route each 
+anyone.can get:  '/',
+           post: '/blog/action/save'
+
+# example: multiple methods, multiple routes (using string array syntax)
+anyone.can get:  %w[/
+                    /sign-in
+                    /blog/editor],
+           post: %w[/blog/action/save 
+                    /blog/action/delete]
+```
+
+> **Note** Allowing GET implies allowing HEAD, since HEAD is by spec a GET without a response body. The reverse is not
+> true, however; allowing HEAD will not also allow GET.
+
+#### Wildcards and Special Symbols
+
+Provide a wildcard `*` to match any string excluding slash. There is intentionally no syntax for matching wildcards
+recursively, so nested paths will also need to be declared.
+
+```ruby
+# example: match anything directly under the /members/ path
+members.can get: '/members/*'
+```
+
+There is also a special symbol, `:all` that matches all paths. It is intended for rare use
+with superadmin-type accounts.
+
+```ruby
+# this allows GET on all paths to those in the admin group
+admins.can get: :all
+```
+
+> **Warning** Always be cautious when using wildcards and special symbols to avoid accidentally opening up pathways that
+> should remain private.
+
+### Always Allow: `can`
+
+Any route declared with `#can` will be accepted without further challenge.
 
 ```ruby
-rules do
-    can_sometimes('/login') # Anyone can access this path
+bouncer.rules do
+   # Anyone can access this path over GET
+   anyone.can get: '/login'
 end
 ```
 
-#### :any and :all special parameters
-Passing `can` or `can_sometimes`:
- * `:any` to the first parameter will match any HTTP method. 
- * `:all` to the second parameter will match any path. 
+### Conditionally Allow: `can_sometimes`
+
+`can_sometimes` takes a condition block that will be run once the path is attempted. This block **must return an
+explicit boolean** (ie. `true` or `false`) to avoid any accidental truthy values creating unwanted access.
 
 ```ruby
-# this allows get on all paths
-can(:get, :all)
+bouncer.role :users do
+   !current_user.nil?
+end
 
-# this allows any method type to run on the /login path
-can(:any, '/login')
+bouncer.rules do
+   users.can_sometimes post: '/user/save' do
+      current_user.id == params[:id]
+   end
+end
 ```
 
 ### Custom Bounce Behaviour
-The default bounce action is to `halt 403`. Call `bounce_with` with a block to specify your own behaviour. The block is also run in a sinatra request context, so you can use helpers here as well. 
+
+The default bounce action is to `halt 403`. Call `bounce_with` with a block to specify your own behaviour. The block is
+also run in a Sinatra request handler context, so you can use helpers here as well.
 
 ```ruby
 require 'sinatra'
 require 'sinatra/bouncer'
 
-bounce_with do 
-  redirect '/login'
+bounce_with do
+   redirect '/login'
 end
 
 # bouncer rules, routes, etc...
 ```
+
+## Alternatives
+
+The syntax for Bouncer is largely influenced by the now-deprecated [CanCan](https://github.com/ryanb/cancan) gem.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/TenjinInc/Sinatra-Bouncer.
+
+Valued topics:
+
+* Error messages (clarity, hinting)
+* Documentation
+* API
+* Security correctness
+
+This project is intended to be a friendly space for collaboration, and contributors are expected to adhere to the
+[Contributor Covenant](https://www.contributor-covenant.org/) code of conduct. Play nice.
+
+### Core Developers
+
+After checking out the repo, run `bundle install` to install dependencies. Then, run `rake spec` to run the tests. You
+can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the
+version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version,
+push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+Documentation is produced by Yard. Run `bundle exec rake yard`. The goal is to have 100% documentation coverage and 100%
+test coverage.
+
+Release notes are provided in `RELEASE_NOTES.md`, and should vaguely
+follow [Keep A Changelog](https://keepachangelog.com/en/1.0.0/) recommendations.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/license/mit/).