sinatra-bouncer 1.3.0 → 3.0.0

data/RELEASE_NOTES.md

@@ -0,0 +1,170 @@
+# 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
+
+## [3.0.0] - 2023-11-21
+
+### Major Changes
+
+* Changed rules DSL to be role-oriented
+* Removed the `:any` HTTP method wildcard
+* Changed Sinatra API to require calling methods on bouncer object
+    * eg. `rules do ... end` should now be `bouncer.rules do ... end`
+
+### 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

data/lib/sinatra/bouncer/basic_bouncer.rb

@@ -4,65 +4,62 @@ require_relative 'rule'
 
 module Sinatra
    module Bouncer
+      # Core implementation of Bouncer logic
       class BasicBouncer
-         attr_accessor :bounce_with, :rules_initializer
+         attr_accessor :rules_initializer
 
          def initialize
-            # @rules = Hash.new do |method_to_paths, method|
-            #    method_to_paths[method] = Hash.new do |path_to_rules, path|
-            #       path_to_rules[path] = []
-            #    end
-            # end
+            @rules = []
 
-            @ruleset = Hash.new do
-               []
+            role :anyone do
+               true
             end
 
             @rules_initializer = proc {}
+            @bounce_strategy   = proc do
+               halt 403
+            end
          end
 
-         def reset!
-            @ruleset.clear
+         def rules(&block)
+            instance_exec(&block)
+            @rules.each do |rule|
+               raise BouncerError, 'rules block error: missing #can or #can_sometimes call' if rule.incomplete?
+            end
          end
 
-         def can(method, *paths)
-            if block_given?
-               hint = 'If you wish to conditionally allow, use #can_sometimes instead.'
-               raise BouncerError, "You cannot provide a block to #can. #{ hint }"
-            end
+         def can?(method, path, context)
+            method = method.downcase.to_sym unless method.is_a? Symbol
 
-            can_sometimes(method, *paths) do
-               true
+            @rules.any? do |rule|
+               rule.allow? method, path, context
             end
          end
 
-         def can_sometimes(method, *paths, &block)
-            unless block
-               hint = 'If you wish to always allow, use #can instead.'
-               raise BouncerError, "You must provide a block to #can_sometimes. #{ hint }"
-            end
-
-            paths.each do |path|
-               @ruleset[method] += [Rule.new(path, &block)]
-            end
+         def bounce_with(&block)
+            @bounce_strategy = block
          end
 
-         def can?(method, path)
-            rules = (@ruleset[:any_method] + @ruleset[method]).select { |rule| rule.match_path?(path) }
+         def bounce(instance)
+            instance.instance_exec(&@bounce_strategy)
+         end
 
-            rules.any? do |rule_block|
-               ruling = rule_block.rule_passes?
+         def role(identifier, &block)
+            raise ArgumentError, 'must provide a role identifier to #role' unless identifier
+            raise ArgumentError, 'must provide a role condition block to #role' unless block
+            raise ArgumentError, "role called '#{ identifier }' already defined" if respond_to? identifier
 
-               ruling
+            define_singleton_method identifier do
+               add_rule(&block)
             end
          end
 
-         def bounce(instance)
-            if bounce_with
-               instance.instance_exec(&bounce_with)
-            else
-               instance.halt 403
-            end
+         private
+
+         def add_rule(&block)
+            rule = Rule.new(&block)
+            @rules << rule
+            rule
          end
       end
 

data/lib/sinatra/bouncer/rule.rb

@@ -2,42 +2,122 @@
 
 module Sinatra
    module Bouncer
+      # Defines a RuleSet to be evaluated with each request
       class Rule
-         def initialize(path, &rule_block)
-            if path == :all
-               @path = :all
-            else
-               path = "/#{ path }" unless path.start_with?('/')
+         # Enumeration of HTTP method strings based on:
+         #    https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods
+         # Ignoring CONNECT and TRACE due to rarity
+         HTTP_METHODS = %w[GET HEAD PUT POST DELETE OPTIONS PATCH].freeze
+
+         # Symbol versions of HTTP_METHODS constant
+         #
+         # @see HTTP_METHODS
+         HTTP_METHOD_SYMBOLS = HTTP_METHODS.collect do |http_method|
+            http_method.downcase.to_sym
+         end.freeze
 
-               @path = path.split('/')
+         def initialize(&block)
+            raise ArgumentError, 'must provide a block to Bouncer::Rule' unless block
+
+            @routes = Hash.new do
+               []
             end
 
-            @rule = rule_block
+            @conditions = [block]
          end
 
-         def match_path?(path)
-            return true if @path == :all
+         def can_sometimes(**method_routes, &block)
+            if method_routes.empty?
+               raise ArgumentError,
+                     'must provide a hash where keys are HTTP method symbols and values are one or more path matchers'
+            end
 
-            path = "/#{ path }" unless path.start_with?('/')
+            unless block
+               hint = 'If you wish to always allow, use #can instead.'
+               raise BouncerError, "You must provide a block to #can_sometimes. #{ hint }"
+            end
 
-            split_path = path.split('/')
-            matches    = @path.length == split_path.length
+            method_routes.each do |method, paths|
+               validate_http_method! method
 
-            @path.each_index do |i|
-               allowed_segment = @path[i]
-               given_segment   = split_path[i]
+               paths = [paths] unless paths.respond_to? :collect
 
-               matches &= given_segment == allowed_segment || allowed_segment == '*'
+               @routes[method] += paths.collect { |path| normalize_path path }
             end
 
-            matches
+            @conditions << block
          end
 
-         def rule_passes?
-            ruling = @rule.call
+         def can(**method_routes)
+            if block_given?
+               hint = 'If you wish to conditionally allow, use #can_sometimes instead.'
+               raise BouncerError, "You cannot provide a block to #can. #{ hint }"
+            end
+
+            can_sometimes(**method_routes) do
+               true
+            end
+         end
+
+         def allow?(method, path, context)
+            match_path?(method, path) && @conditions.all? do |condition|
+               rule_passes?(context, &condition)
+            end
+         end
+
+         def incomplete?
+            @routes.empty?
+         end
+
+         private
+
+         def validate_http_method!(method)
+            return if HTTP_METHOD_SYMBOLS.include?(method)
+
+            raise BouncerError, "'#{ method }' is not a known HTTP method key. Must be one of: #{ HTTP_METHOD_SYMBOLS }"
+         end
 
-            unless ruling.is_a?(TrueClass) || ruling.is_a?(FalseClass)
-               source = @rule.source_location.join(':')
+         # Determines if the path matches the exact path or wildcard.
+         #
+         # @return `true` if the path matches
+         def match_path?(method, trial_path)
+            trial_path = normalize_path trial_path
+
+            matchers_for(method).any? do |matcher|
+               return true if matcher == :all
+
+               matcher_parts = matcher.split '/'
+               trial_parts   = trial_path.split '/'
+               matches       = matcher_parts.length == trial_parts.length
+
+               matcher_parts.each_index do |i|
+                  allowed_segment = matcher_parts[i]
+                  given_segment   = trial_parts[i]
+
+                  matches &= given_segment == allowed_segment || allowed_segment == '*'
+               end
+
+               matches
+            end
+         end
+
+         def matchers_for(method)
+            matchers = @routes[method]
+
+            matchers += @routes[:get] if method == :head
+
+            matchers
+         end
+
+         # Evaluates the rule's block. Defensively prevents truthy values from the block from allowing a route.
+         #
+         # @raise BouncerError when the rule block is a truthy value but not exactly `true`
+         # @return Exactly `true` or `false`, depending on the result of the rule block
+         def rule_passes?(context, &rule)
+            ruling = context.instance_exec(&rule)
+
+            unless !ruling || ruling.is_a?(TrueClass)
+               source = rule.source_location.join(':')
                msg    = <<~ERR
                   Rule block at does not return explicit true/false.
                   Rules must return explicit true or false to prevent accidental truthy values.
@@ -47,7 +127,19 @@ module Sinatra
                raise BouncerError, msg
             end
 
-            ruling
+            !!ruling
+         end
+
+         def normalize_path(path)
+            if path == :all
+               path
+            else
+               if path.start_with?('/')
+                  path
+               else
+                  "/#{ path }"
+               end.downcase
+            end
          end
       end
    end

data/lib/sinatra/bouncer/version.rb

@@ -3,6 +3,6 @@
 module Sinatra
    module Bouncer
       # Current version of the gem
-      VERSION = '1.3.0'
+      VERSION = '3.0.0'
    end
 end

data/lib/sinatra/bouncer.rb

@@ -23,52 +23,21 @@
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #++
 
+require 'sinatra/base'
 require_relative 'bouncer/basic_bouncer'
 
+# Namespace module
 module Sinatra
+   # Namespace module
    module Bouncer
       def self.registered(base_class)
-         base_class.helpers HelperMethods
-
-         bouncer = BasicBouncer.new
-
-         # TODO: can we instead store it somehow on the actual temp request object?
-         base_class.set :bouncer, bouncer
+         base_class.set :bouncer, BasicBouncer.new
 
          base_class.before do
-            bouncer.reset! # must clear all rules otherwise will leave doors open
-
-            instance_exec(&bouncer.rules_initializer)
-
-            http_method = request.request_method.downcase.to_sym
-            path        = request.path.downcase
-
-            bouncer.bounce(self) unless bouncer.can?(http_method, path)
-         end
-      end
-
-      # Start ExtensionMethods
-      def bounce_with(&block)
-         bouncer.bounce_with = block
-      end
-
-      def rules(&block)
-         bouncer.rules_initializer = block
-      end
-      # End ExtensionMethods
-
-      module HelperMethods
-         def can(*args)
-            settings.bouncer.can(*args)
-         end
-
-         def can_sometimes(...)
-            settings.bouncer.can_sometimes(...)
+            settings.bouncer.bounce(self) unless settings.bouncer.can?(request.request_method, request.path, self)
          end
       end
    end
 
-   if defined? register
-      register Bouncer
-   end
+   register Sinatra::Bouncer
 end

data/sinatra_bouncer.gemspec

@@ -19,7 +19,10 @@ Gem::Specification.new do |spec|
          'rubygems_mfa_required' => 'true'
    }
 
-   spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features|integrations)/}) }
+   spec.files = `git ls-files -z`.split("\x0").reject do |f|
+      f.match(%r{^(test|spec|features|integrations|benchmarks)/})
+   end
+
    spec.require_paths = ['lib']
 
    spec.required_ruby_version = '>= 3.1'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sinatra-bouncer
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 3.0.0
 platform: ruby
 authors:
 - Tenjin Inc
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-09-13 00:00:00.000000000 Z
+date: 2023-11-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: sinatra
@@ -37,9 +37,12 @@ files:
 - ".rubocop.yml"
 - ".ruby-version"
 - ".simplecov"
+- CODE_OF_CONDUCT.md
 - Gemfile
+- Gemfile.lock
 - MIT-LICENSE
 - README.md
+- RELEASE_NOTES.md
 - Rakefile
 - cucumber.yml
 - lib/sinatra/bouncer.rb
@@ -47,18 +50,6 @@ files:
 - lib/sinatra/bouncer/rule.rb
 - lib/sinatra/bouncer/version.rb
 - sinatra_bouncer.gemspec
-- tests/integrations/dev_defines_legal_routes.feature
-- tests/integrations/dev_installs_bouncer.feature
-- tests/integrations/step_definitions/given.rb
-- tests/integrations/step_definitions/then.rb
-- tests/integrations/step_definitions/when.rb
-- tests/integrations/support/env.rb
-- tests/integrations/support/helpers.rb
-- tests/integrations/support/types.rb
-- tests/spec/basic_bouncer_spec.rb
-- tests/spec/rule_spec.rb
-- tests/spec/spec_helper.rb
-- tests/test_app.rb
 homepage: https://github.com/TenjinInc/Sinatra-Bouncer
 licenses:
 - MIT

data/tests/integrations/dev_defines_legal_routes.feature

@@ -1,57 +0,0 @@
-Feature: Developer defines legal routes
-   As a developer
-   So that clients can safely access my server
-   I will allow specific routes
-   
-   Scenario Outline: it should allows access to whitelist routes
-      Given a sinatra server with bouncer and routes:
-         | method | path   | allowed |
-         | get    | <path> | yes     |
-      When I visit /<path>
-      Then it should be at /<path>
-      And it should have status code 200
-      Examples:
-         | path         |
-         | some_path    |
-         | another_path |
-   
-   Scenario: it should NOT allow access to other routes
-      Given a sinatra server with bouncer and routes:
-         | method | path         | allowed |
-         | get    | some_path    | yes     |
-         | get    | illegal_path | no      |
-      When I visit /illegal_path
-      Then it should have status code 403
-   
-   Scenario Outline: it should allow multiple routes with a splat
-      Given a sinatra server with bouncer and routes:
-         | method | path    | allowed |
-         | get    | admin/* | yes     |
-      When I visit /admin/<sub_path>
-      Then it should be at /admin/<sub_path>
-      And it should have status code 200
-      Examples:
-         | sub_path  |
-         | dashboard |
-         | users     |
-   
-   Scenario Outline: it should allow splat to be in the middle of the route
-      Given a sinatra server with bouncer and routes:
-         | method | path           | allowed |
-         | get    | admin/*/create | yes     |
-      When I visit /admin/<sub_path>/create
-      Then it should be at /admin/<sub_path>/create
-      And it should have status code 200
-      Examples:
-         | sub_path |
-         | tasks    |
-         | users    |
-   
-   Scenario: it should forget rules between requests
-      Given a sinatra server with bouncer and routes:
-         | method | path      | allowed |
-         | get    | some_path | once    |
-      When I double visit /some_path
-      Then it should be at /some_path
-      And it should have status code 403
-      

data/tests/integrations/dev_installs_bouncer.feature

@@ -1,12 +0,0 @@
-Feature: Developer installs Bouncer
-   As a developer
-   So that I can secure my sinatra server
-   I will install bouncer
-   
-   Scenario: it should auto protect all routes
-      Given a sinatra server with bouncer and routes:
-         | method | path      |
-         | get    | some_path |
-      When I visit /some_path
-      Then it should have status code 403
-      

data/tests/integrations/step_definitions/given.rb

@@ -1,36 +0,0 @@
-# frozen_string_literal: true
-
-Given 'a sinatra server with bouncer and routes:' do |table|
-   app = Capybara.app
-
-   allowed_paths = []
-
-   table.hashes.each do |row|
-      path = row[:path]
-      path = "/#{ path }" if path[0] != '/' # ensure leading slash
-
-      method = row[:method].to_sym
-      # build the routes
-      app.send(method, path) do
-         'The result of path'
-      end
-
-      is_once = row[:allowed] =~ /once/i
-
-      next unless is_once || parse_bool(row[:allowed])
-
-      allowed_paths << path
-
-      @allowed_once_paths << path if is_once
-   end
-
-   onces = @allowed_once_paths
-
-   app.rules do
-      allowed_paths.each do |path|
-         can_sometimes(:any_method, path) do
-            !onces.include?(path)
-         end
-      end
-   end
-end

data/tests/integrations/step_definitions/then.rb

@@ -1,9 +0,0 @@
-# frozen_string_literal: true
-
-Then 'it should have status code {int}' do |status|
-   expect(page.driver.status_code).to eq status
-end
-
-Then 'it should be at {path}' do |path|
-   expect(page).to have_current_path path.to_s
-end

data/tests/integrations/step_definitions/when.rb

@@ -1,11 +0,0 @@
-# frozen_string_literal: true
-
-When 'he/she/they/I double visit(s) {path}' do |path|
-   visit path
-   visit '/'
-   visit path
-end
-
-When 'he/she/they/I visit(s) {path}' do |path|
-   visit path
-end