sinatra-bouncer 1.3.0 → 2.0.0

data/lib/sinatra/bouncer/basic_bouncer.rb

@@ -4,16 +4,26 @@ require_relative 'rule'
 
 module Sinatra
    module Bouncer
+      # Core implementation of Bouncer logic
       class BasicBouncer
          attr_accessor :bounce_with, :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
+         # 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
+
+         # Method symbol used to match any method
+         WILDCARD_METHOD = :any
 
+         def initialize
             @ruleset = Hash.new do
                []
             end
@@ -21,37 +31,45 @@ module Sinatra
             @rules_initializer = proc {}
          end
 
-         def reset!
-            @ruleset.clear
-         end
-
-         def can(method, *paths)
+         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, *paths) do
+            can_sometimes(**method_routes) do
                true
             end
          end
 
-         def can_sometimes(method, *paths, &block)
+         def can_sometimes(**method_routes, &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)]
+            method_routes.each do |method, paths|
+               unless HTTP_METHOD_SYMBOLS.include?(method) || method == WILDCARD_METHOD
+                  hint = "Must be one of: #{ HTTP_METHOD_SYMBOLS } or :#{ WILDCARD_METHOD }"
+                  raise BouncerError, "'#{ method }' is not a known HTTP method key. #{ hint }"
+               end
+
+               paths = [paths] unless paths.respond_to? :collect
+
+               @ruleset[method] += paths.collect { |path| Rule.new(path, &block) }
             end
          end
 
-         def can?(method, path)
-            rules = (@ruleset[:any_method] + @ruleset[method]).select { |rule| rule.match_path?(path) }
+         def can?(method, path, context)
+            rulesets = @ruleset[WILDCARD_METHOD] + @ruleset[method]
+
+            # HEAD requests are equivalent to GET requests without response
+            rulesets += @ruleset[:get] if method == :head
+
+            rules = rulesets.select { |rule| rule.match_path?(path) }
 
             rules.any? do |rule_block|
-               ruling = rule_block.rule_passes?
+               ruling = rule_block.rule_passes? context
 
                ruling
             end

data/lib/sinatra/bouncer/rule.rb

@@ -2,6 +2,7 @@
 
 module Sinatra
    module Bouncer
+      # Defines a Rule to be evaluated with each request
       class Rule
          def initialize(path, &rule_block)
             if path == :all
@@ -15,6 +16,9 @@ module Sinatra
             @rule = rule_block
          end
 
+         # Determines if the path matches the exact path or wildcard.
+         #
+         # @return `true` if the path matches
          def match_path?(path)
             return true if @path == :all
 
@@ -33,10 +37,14 @@ module Sinatra
             matches
          end
 
-         def rule_passes?
-            ruling = @rule.call
+         # 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)
+            ruling = context.instance_exec(&@rule)
 
-            unless ruling.is_a?(TrueClass) || ruling.is_a?(FalseClass)
+            unless !ruling || ruling.is_a?(TrueClass)
                source = @rule.source_location.join(':')
                msg    = <<~ERR
                   Rule block at does not return explicit true/false.
@@ -47,7 +55,7 @@ module Sinatra
                raise BouncerError, msg
             end
 
-            ruling
+            !!ruling
          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 = '2.0.0'
    end
 end

data/lib/sinatra/bouncer.rb

@@ -23,52 +23,32 @@
 # 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)
+            settings.bouncer.bounce(self) unless settings.bouncer.can?(http_method, path, self)
          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(...)
-         end
+         settings.bouncer.instance_exec(&block)
       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: 2.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-13 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

data/tests/integrations/support/env.rb

@@ -1,30 +0,0 @@
-# frozen_string_literal: true
-
-src_dir = File.expand_path('../../..', __dir__)
-$LOAD_PATH.unshift(src_dir) unless $LOAD_PATH.include?(src_dir)
-
-require 'simplecov'
-
-SimpleCov.command_name 'spec'
-
-require 'capybara/cucumber'
-require 'rspec/expectations'
-
-require 'tests/test_app'
-
-# == CAPYBARA ==
-Capybara.app = Sinatra::Application
-
-# Set this to whatever the server's normal port is for you. Sinatra is 4567; rack 9292 by default.
-# Also note: you have to be running the server for this to work.
-Capybara.asset_host = 'http://localhost:4567'
-
-# == REGULAR SETTINGS ==
-Before do
-   Capybara.reset_sessions!
-   Capybara.app.settings.bouncer.instance_variable_get(:@ruleset).clear
-
-   @allowed_once_paths = []
-end
-
-World(RSpec::Matchers)

data/tests/integrations/support/helpers.rb

@@ -1,55 +0,0 @@
-# frozen_string_literal: true
-
-# Helper methods for Cucumber steps
-module HelperMethods
-   # TEST_TMP_ROOT = Pathname.new(Dir.mktmpdir('bouncer_test_')).expand_path.freeze
-   # TEST_TMP_LOG  = (TEST_TMP_ROOT / 'log').expand_path.freeze
-
-   # Data conversion helpers for Cucumber steps
-   module Conversion
-      def extract_list(list_string)
-         (list_string || '').split(',').map(&:strip)
-      end
-
-      def symrow(table)
-         table.symbolic_hashes.first
-      end
-
-      def symtable(table)
-         table.map_headers do |header|
-            header.tr(' ', '_').downcase.to_sym
-         end
-      end
-
-      def parse_bool(string)
-         !(string =~ /t|y/i).nil?
-      end
-
-      def parse_phone(string)
-         string.to_s.split(/:\s+/)
-      end
-
-      def parse_duration(string)
-         scalar, unit = string.split(/\s/)
-
-         return nil if unit.nil? || unit.empty?
-
-         unit = "#{ unit }s" unless unit.end_with?('s')
-
-         unit_map = {
-               years:   365.25 * 86400,
-               months:  30 * 86400,
-               weeks:   7 * 86400,
-               days:    86400,
-               hours:   3600,
-               minutes: 60,
-               seconds: 1
-         }
-
-         scalar.to_i * unit_map[unit.downcase.to_sym]
-      end
-   end
-end
-
-# Inject the HelperMethods into the Cucumber test context
-World(HelperMethods, HelperMethods::Conversion)

data/tests/integrations/support/types.rb

@@ -1,21 +0,0 @@
-# frozen_string_literal: true
-
-ParameterType(name:        'path',
-              regexp:      %r{/(?:\S+/?)*},
-              type:        Pathname,
-              transformer: lambda do |str|
-                 Pathname.new(str)
-              end)
-
-ParameterType(name:        'boolean',
-              regexp:      /(enabled|disabled|true|false|on|off|yes|no)/,
-              transformer: lambda do |str|
-                 %w[enabled true on yes].include? str.downcase
-              end)
-
-ParameterType(name:        'html element',
-              regexp:      /<(\S+)>/,
-              type:        String,
-              transformer: lambda do |str|
-                 str
-              end)

data/tests/spec/basic_bouncer_spec.rb

@@ -1,148 +0,0 @@
-# frozen_string_literal: true
-
-require_relative 'spec_helper'
-
-describe Sinatra::Bouncer::BasicBouncer do
-   let(:bouncer) { Sinatra::Bouncer::BasicBouncer.new }
-
-   describe '#can' do
-      it 'should raise an error if provided a block' do
-         msg = <<~ERR
-            You cannot provide a block to #can. If you wish to conditionally allow, use #can_sometimes instead.
-         ERR
-
-         expect do
-            bouncer.can(:post, 'some_path') do
-               # stub
-            end
-         end.to raise_error(Sinatra::Bouncer::BouncerError, msg.chomp)
-      end
-
-      it 'should handle a list of paths' do
-         bouncer.can(:post, 'some_path', 'other_path')
-
-         expect(bouncer.can?(:post, 'some_path')).to be true
-         expect(bouncer.can?(:post, 'other_path')).to be true
-      end
-
-      it 'should accept a splat' do
-         bouncer.can(:post, 'directory/*')
-
-         expect(bouncer.can?(:post, 'directory/some_path')).to be true
-      end
-   end
-
-   describe '#can_sometimes' do
-      it 'should accept :any_method to mean all http methods' do
-         bouncer.can_sometimes(:any_method, 'some_path') do
-            true
-         end
-
-         expect(bouncer.can?(:get, 'some_path')).to be true
-         expect(bouncer.can?(:post, 'some_path')).to be true
-         expect(bouncer.can?(:put, 'some_path')).to be true
-         expect(bouncer.can?(:delete, 'some_path')).to be true
-         expect(bouncer.can?(:options, 'some_path')).to be true
-         expect(bouncer.can?(:link, 'some_path')).to be true
-         expect(bouncer.can?(:unlink, 'some_path')).to be true
-         expect(bouncer.can?(:head, 'some_path')).to be true
-         expect(bouncer.can?(:trace, 'some_path')).to be true
-         expect(bouncer.can?(:connect, 'some_path')).to be true
-         expect(bouncer.can?(:patch, 'some_path')).to be true
-      end
-
-      it 'should accept :all to mean all paths' do
-         bouncer.can_sometimes(:get, :all) do
-            true
-         end
-
-         expect(bouncer.can?(:get, 'some_path')).to be true
-      end
-
-      it 'should accept a list of paths' do
-         bouncer.can_sometimes(:post, 'some_path', 'other_path') do
-            true
-         end
-
-         expect(bouncer.can?(:post, 'some_path')).to be true
-         expect(bouncer.can?(:post, 'other_path')).to be true
-      end
-
-      it 'should accept a splat' do
-         bouncer.can_sometimes(:post, 'directory/*') do
-            true
-         end
-
-         expect(bouncer.can?(:post, 'directory/some_path')).to be true
-      end
-
-      it 'should not raise an error if provided a block' do
-         expect do
-            bouncer.can_sometimes(:any_method, 'some_path') do
-               true
-            end
-         end.to_not raise_error
-      end
-
-      it 'should raise an error if not provided a block' do
-         msg = <<~ERR
-            You must provide a block to #can_sometimes. If you wish to always allow, use #can instead.
-         ERR
-
-         expect do
-            bouncer.can_sometimes(:any_method, 'some_path')
-         end.to raise_error(Sinatra::Bouncer::BouncerError, msg.chomp)
-      end
-   end
-
-   describe '#can?' do
-      it 'should pass when declared allowed' do
-         bouncer.can(:any_method, 'some_path')
-
-         expect(bouncer.can?(:post, 'some_path')).to be true
-      end
-
-      it 'should fail when not declared allowed' do
-         expect(bouncer.can?(:post, 'some_path')).to be false
-      end
-
-      it 'should pass if the rule block passes' do
-         bouncer.can_sometimes(:any_method, 'some_path') do
-            true
-         end
-
-         expect(bouncer.can?(:post, 'some_path')).to be true
-      end
-
-      it 'should fail if the rule block fails' do
-         bouncer.can_sometimes(:any_method, 'some_path') do
-            false
-         end
-
-         expect(bouncer.can?(:post, 'some_path')).to be false
-      end
-   end
-
-   describe '#bounce' do
-      it 'should run the bounce_with block on sinatra instance' do
-         runner  = nil
-         sinatra = double('sinatra')
-
-         bouncer.bounce_with = proc do
-            runner = self # self should be the sinatra double
-         end
-
-         bouncer.bounce(sinatra)
-
-         expect(runner).to be sinatra
-      end
-
-      it 'should halt 403 if no block provided' do
-         app = double('sinatra')
-
-         expect(app).to receive(:halt).with(403)
-
-         bouncer.bounce(app)
-      end
-   end
-end