sinatra-bouncer 1.3.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6b8592539c3824fa1985a4c02b877bd7d53e6ab2635f4227b173325f16484465
-  data.tar.gz: 1aac0ef35f8584e83cbafd5843172798f8967ad217235f9048e476cf3cc8945f
+  metadata.gz: f07c9c87e55563ac21610aecc8813d32ee3322d291382bb1bd5cca0ce0d55a12
+  data.tar.gz: fa55400409722c0f0f4ea83c6ee552654d0d8aee128d484f3a42c2c888e9b46b
 SHA512:
-  metadata.gz: 83ed25a0acff1d864f978dbbd3667d20f53be0bea36fa5db5abd55eeb4353cad53e29ebeb424f1c462e4a8790444f4a5850cad33c579729aab684ff4f0d482aa
-  data.tar.gz: a3caa0c02709faa60e5512f73f2b4c4f21066f519999e014ffac2545271198d8a98a7a73d430494a185a00e0ea255170e1693274c7fb8bca51b56c6108fcd8a6
+  metadata.gz: 4fc6e73dcb5867a418dea6b555f74fee57f41b58d75ab76657925a71b1b2ff059295135c30646f4de83fe82a00bc816a6d668d54ecd64f035b63f27d68b80ef1
+  data.tar.gz: ca808e79a1f59743c17afc6e7475dd03a9a3186d8ed1ec3c6b4412ec96af2c38c0e454a0fada15c513e83c1070eb7b6f72c2a116be9e2ed7135592ce7f04ce70

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 (2.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,268 @@
-#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 rules look like:
 
-**Gemfile**
 ```ruby
-gem 'sinatra-bouncer'
-```
+rules do
+   # Routes match based on one or more strings. 
+   can get:  '/',
+       post: %w[/user/sign-in
+                /user/sign-out]
+
+   # Wildcards match anything directly under that path 
+   can get: '/lib/js/*'
+
+   # Use a conditional rule block for additional logic
+   can_sometimes get:  '/admin/*',
+                 post: '/admin/actions/*' do
+      current_user.admin?
+   end
+
+   # ... etc ...
+end
 
-**Terminal**
-```sh
-gem install sinatra-bouncer
 ```
 
-##Quickstart
-###Step 1: Require/Register Bouncer
+## Features
 
-After registration, Bouncer will reject any request that either:
-* has no rule associated with it, or
-* has no associated rule that returns `true`
+Here's what this Gem provides:
+
+* **Block-by-default**
+    * Any route must be explicitly allowed
+* **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:
 
-**Sinatra Classic**
 ```ruby
-require 'sinatra'
-require 'sinatra/bouncer'
+gem 'sinatra-bouncer'
+```
 
-   # ... routes and other config
+Then run:
+
+```shell
+bundle install
 ```
 
-**Modular**
+**Sinatra Modular Style**
+
 ```ruby
 require 'sinatra/base'
 require 'sinatra/bouncer'
 
 class MyApp < Sinatra::Base
-  register Sinatra::Bouncer
-  
-  # ... routes and other config
+   register Sinatra::Bouncer
+
+   rules do
+      # ... can statements ...
+   end
+
+   # ... routes and other config
 end
 ```
 
-###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`.
+**Sinatra Classic Style**
 
 ```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
+   # ... can statements ...
 end
 
-# ... route declarations as normal below
+# ... routes and other config
 ```
 
-## API
-#### can
-Any route declared with #can will be accepted without further challenge. 
+## Usage
+
+Call `rules` with a block that uses the `#can` and `#can_sometimes` DSL methods to declare rules for paths.
+
+The rules block is run once as part of the configuration phase but the condition blocks are evaluated in the context of
+the
+request, which means you will have access to Sinatra helpers,
+the `request` object, and `params`.
 
 ```ruby
+require 'sinatra'
+require 'sinatra/bouncer'
+
 rules do
-   can(:post, '/user_posts_blog')
+   # example: always allow GET requests to root path or /sign-in
+   can get: %w[/
+               /sign-in]
+
+   # example: logged in users can view (GET) member restricted paths and edit their account (POST)
+   can_sometimes get:  '/members/*',
+                 post: '/members/edit-account' do
+      !current_user.nil?
+   end
+
+   # example: check an arbitrary request header is present
+   can_sometimes get: '/bots/*' do
+      !request.get_header('X-CUSTOM_PROP').nil?
+   end
 end
+
+# ... Sinatra route declarations as normal ... 
 ```
 
-####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.
+### HTTP Method and Route Matching
+
+Both `#can` and `#can_sometimes` accept multiple
+[HTTP methods](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods) as symbols
+and each key is paired with one or more path strings.
+
+```ruby
+# example: single method, single route 
+can get: '/'
+
+# example: multiple methods, single route each 
+can get:  '/',
+    post: '/blog/action/save'
+
+# example: multiple methods, multiple routes (using string array syntax)
+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
+
+> **Warning** Always be cautious when using wildcards and special symbols to not accidentally open up pathways that
+> should remain private.
+
+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
+can get: '/members/*'
+```
+
+There are also 2 special symbols:
+
+1. `:any` will match any HTTP method.
+2. `:all` will match all paths.
+
+```ruby
+# this allows any method type on the / path
+can any: '/'
+
+# this allows GET on all paths
+can get: :all
+```
+
+### 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
+   # Anyone can access this path over GET
+   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` 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.
 
 ```ruby
-# this allows get on all paths
-can(:get, :all)
+rules do
+   can_sometimes get: '/login' # Anyone can access this path over GET
 
-# this allows any method type to run on the /login path
-can(:any, '/login')
+   can_sometimes post: '/user/blog/actions/save' do
+      !current_user.nil?
+   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 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/).

data/RELEASE_NOTES.md

@@ -0,0 +1,153 @@
+# Release Notes
+
+All notable changes to this project will be documented below.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) and this project loosely follows
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Major Changes
+
+* none
+
+### Minor Changes
+
+* none
+
+### Bugfixes
+
+* none
+
+## [2.0.0] - 2023-11-13
+
+### Major Changes
+
+* Converted to hash syntax in `can` and `can_sometimes` statements
+
+### Minor Changes
+
+* Converted Cucumber tests to Rspec integration tests for consistency
+* HEAD requests are evaluated like GET requests due to semantic equivalence
+* Falsey values are now acceptable rule block results
+
+### Bugfixes
+
+* none
+
+## [1.3.0] - 2023-09-13
+
+### Major Changes
+
+* none
+
+### Minor Changes
+
+* Increased minimum Ruby to 3.1
+* Cleaned up development dependencies
+* Rubocop cleanups
+* Installed Simplecov
+* Created Rakefile
+
+### Bugfixes
+
+* none
+
+## [1.2.0] - 2016-10-02
+
+### Major Changes
+
+* none
+
+### Minor Changes
+
+* Supports wildcard matches in route strings
+
+### Bugfixes
+
+* none
+
+## [1.1.1] - 2015-06-02
+
+### Major Changes
+
+* none
+
+### Minor Changes
+
+* none
+
+### Bugfixes
+
+* Runs `bounce_with` in context of web request
+
+## [1.1.0] - 2015-05-28
+
+### Major Changes
+
+* none
+
+### Minor Changes
+
+* none
+
+### Bugfixes
+
+* Correctly forgets rules between routes
+
+## [1.0.2] - 2015-05-24
+
+### Major Changes
+
+* none
+
+### Minor Changes
+
+* Changed default halt to 403
+* Application available in rule block
+
+### Bugfixes
+
+* Fixed sinatra module registration
+
+## [1.0.1] - 2015-05-21
+
+### Major Changes
+
+* none
+
+### Minor Changes
+
+* none
+
+### Bugfixes
+
+* none
+
+## [1.0.0] - Unreleased Prototype
+
+### Major Changes
+
+* none
+
+### Minor Changes
+
+* none
+
+### Bugfixes
+
+* none
+
+## [0.1.0] - Unreleased Prototype
+
+### Major Changes
+
+* Initial prototype
+
+### Minor Changes
+
+* none
+
+### Bugfixes
+
+* none