sinatra-bouncer 2.0.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f07c9c87e55563ac21610aecc8813d32ee3322d291382bb1bd5cca0ce0d55a12
-  data.tar.gz: fa55400409722c0f0f4ea83c6ee552654d0d8aee128d484f3a42c2c888e9b46b
+  metadata.gz: 849fed52904df15b1cc036685383f197e47aae52bef8283a81decc281fc95660
+  data.tar.gz: 3a3ba41d0d3c2ad70b1c4e48b81558213111d86a750717e2b8f44dea9072ca1f
 SHA512:
-  metadata.gz: 4fc6e73dcb5867a418dea6b555f74fee57f41b58d75ab76657925a71b1b2ff059295135c30646f4de83fe82a00bc816a6d668d54ecd64f035b63f27d68b80ef1
-  data.tar.gz: ca808e79a1f59743c17afc6e7475dd03a9a3186d8ed1ec3c6b4412ec96af2c38c0e454a0fada15c513e83c1070eb7b6f72c2a116be9e2ed7135592ce7f04ce70
+  metadata.gz: d63e6a5437ef4d71e7183dce458241a8efaebace1c6f95e77766412f2faf2d5d490107a4e925588509dfb8e73b0c2e3a21064e73aae4cb3f98ae0c8465f19dd5
+  data.tar.gz: ca6d627ae51d9ecf6c88ffa21621117adb3af2eee6c83d14846f8ac7a5aa314f9ce4d2d10c30baf192e4a7c435f750bfb5b9bc3c37ed308ee4a5255a8df0eacf

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    sinatra-bouncer (2.0.0)
+    sinatra-bouncer (3.0.0)
       sinatra (>= 2.2)
 
 GEM

data/README.md

@@ -5,35 +5,38 @@ routes are permitted based on your own logic.
 
 ## Big Picture
 
-Bouncer rules look like:
+Bouncer's syntax looks like:
 
 ```ruby
-rules do
+# 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. 
-   can get:  '/',
-       post: %w[/user/sign-in
-                /user/sign-out]
+   anyone.can get:  '/',
+              post: ['/user/sign-in',
+                     '/user/sign-out']
 
    # Wildcards match anything directly under that path 
-   can get: '/lib/js/*'
+   anyone.can get: '/lib/js/*'
 
-   # Use a conditional rule block for additional logic
-   can_sometimes get:  '/admin/*',
-                 post: '/admin/actions/*' do
-      current_user.admin?
-   end
+   admins.can get:  '/admin/*',
+              post: '/admin/actions/*'
 
    # ... etc ...
 end
-
 ```
 
-## Features
+### 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
@@ -44,7 +47,7 @@ Here's what this Gem provides:
 * **Forced Boolean Affirmation**
     * Condition blocks must explicitly return `true`, avoiding accidental truthy values
 
-## Anti-Features
+### Anti-Features
 
 Bouncer intentionally does not support some concepts.
 
@@ -80,7 +83,7 @@ require 'sinatra/bouncer'
 class MyApp < Sinatra::Base
    register Sinatra::Bouncer
 
-   rules do
+   bouncer.rules do
       # ... can statements ...
    end
 
@@ -94,7 +97,7 @@ end
 require 'sinatra'
 require 'sinatra/bouncer'
 
-rules do
+bouncer.rules do
    # ... can statements ...
 end
 
@@ -103,57 +106,77 @@ end
 
 ## Usage
 
-Call `rules` with a block that uses the `#can` and `#can_sometimes` DSL methods to declare rules for paths.
+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, which means you will have access to Sinatra helpers,
-the `request` object, and `params`.
+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: always allow GET requests to root path or /sign-in
-   can get: %w[/
-               /sign-in]
+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)
-   can_sometimes get:  '/members/*',
-                 post: '/members/edit-account' do
-      !current_user.nil?
+   members.can get: '/members/*'
+   members.can_sometimes post: '/members/edit-account' do
+      current_user && current_user.id == params[:id]
    end
 
-   # example: check an arbitrary request header is present
-   can_sometimes get: '/bots/*' do
-      !request.get_header('X-CUSTOM_PROP').nil?
-   end
+   # example: require presence of arbitrary request header in the role condition
+   bots.can get: '/bots/*'
 end
 
 # ... Sinatra route declarations as normal ... 
 ```
 
+### 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
+# let's pretend that current_user is a helper that returns the user from Warden
+bouncer.role :admins do
+   current_user&.admin?
+end
+```
+
+> **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 multiple
-[HTTP methods](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods) as symbols
+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 
-can get: '/'
+anyone.can get: '/'
 
 # example: multiple methods, single route each 
-can get:  '/',
-    post: '/blog/action/save'
+anyone.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]
+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
@@ -161,55 +184,49 @@ can get:  %w[/
 
 #### 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/*'
+members.can get: '/members/*'
 ```
 
-There are also 2 special symbols:
-
-1. `:any` will match any HTTP method.
-2. `:all` will match all paths.
+There is also a special symbol, `:all` that matches all paths. It is intended for rare use
+with superadmin-type accounts.
 
 ```ruby
-# this allows any method type on the / path
-can any: '/'
-
-# this allows GET on all paths
-can get: :all
+# 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
+bouncer.rules do
    # Anyone can access this path over GET
-   can get: '/login'
+   anyone.can get: '/login'
 end
 ```
 
 ### 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.
+`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
-rules do
-   can_sometimes get: '/login' # Anyone can access this path over GET
+bouncer.role :users do
+   !current_user.nil?
+end
 
-   can_sometimes post: '/user/blog/actions/save' do
-      !current_user.nil?
+bouncer.rules do
+   users.can_sometimes post: '/user/save' do
+      current_user.id == params[:id]
    end
 end
 ```
@@ -217,7 +234,7 @@ 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.
+also run in a Sinatra request handler context, so you can use helpers here as well.
 
 ```ruby
 require 'sinatra'

data/RELEASE_NOTES.md

@@ -19,6 +19,23 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 
 * 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

data/lib/sinatra/bouncer/basic_bouncer.rb

@@ -6,81 +6,60 @@ module Sinatra
    module Bouncer
       # Core implementation of Bouncer logic
       class BasicBouncer
-         attr_accessor :bounce_with, :rules_initializer
-
-         # 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
+         attr_accessor :rules_initializer
 
          def initialize
-            @ruleset = Hash.new do
-               []
-            end
+            @rules = []
 
-            @rules_initializer = proc {}
-         end
-
-         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 }"
+            role :anyone do
+               true
             end
 
-            can_sometimes(**method_routes) do
-               true
+            @rules_initializer = proc {}
+            @bounce_strategy   = proc do
+               halt 403
             end
          end
 
-         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 }"
+         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
 
-            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
+         def can?(method, path, context)
+            method = method.downcase.to_sym unless method.is_a? Symbol
 
-               @ruleset[method] += paths.collect { |path| Rule.new(path, &block) }
+            @rules.any? do |rule|
+               rule.allow? method, path, context
             end
          end
 
-         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
+         def bounce_with(&block)
+            @bounce_strategy = block
+         end
 
-            rules = rulesets.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? context
+         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,50 +2,122 @@
 
 module Sinatra
    module Bouncer
-      # Defines a Rule to be evaluated with each request
+      # 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
+
+         def initialize(&block)
+            raise ArgumentError, 'must provide a block to Bouncer::Rule' unless block
+
+            @routes = Hash.new do
+               []
+            end
+
+            @conditions = [block]
+         end
+
+         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
+
+            unless block
+               hint = 'If you wish to always allow, use #can instead.'
+               raise BouncerError, "You must provide a block to #can_sometimes. #{ hint }"
+            end
+
+            method_routes.each do |method, paths|
+               validate_http_method! method
+
+               paths = [paths] unless paths.respond_to? :collect
+
+               @routes[method] += paths.collect { |path| normalize_path path }
+            end
+
+            @conditions << block
+         end
 
-               @path = path.split('/')
+         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
 
-            @rule = rule_block
+            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
 
          # 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
+         def match_path?(method, trial_path)
+            trial_path = normalize_path trial_path
 
-            path = "/#{ path }" unless path.start_with?('/')
+            matchers_for(method).any? do |matcher|
+               return true if matcher == :all
 
-            split_path = path.split('/')
-            matches    = @path.length == split_path.length
+               matcher_parts = matcher.split '/'
+               trial_parts   = trial_path.split '/'
+               matches       = matcher_parts.length == trial_parts.length
 
-            @path.each_index do |i|
-               allowed_segment = @path[i]
-               given_segment   = split_path[i]
+               matcher_parts.each_index do |i|
+                  allowed_segment = matcher_parts[i]
+                  given_segment   = trial_parts[i]
 
-               matches &= given_segment == allowed_segment || allowed_segment == '*'
+                  matches &= given_segment == allowed_segment || allowed_segment == '*'
+               end
+
+               matches
             end
+         end
+
+         def matchers_for(method)
+            matchers = @routes[method]
 
-            matches
+            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)
-            ruling = context.instance_exec(&@rule)
+         def rule_passes?(context, &rule)
+            ruling = context.instance_exec(&rule)
 
             unless !ruling || ruling.is_a?(TrueClass)
-               source = @rule.source_location.join(':')
+               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.
@@ -57,6 +129,18 @@ module Sinatra
 
             !!ruling
          end
+
+         def normalize_path(path)
+            if path == :all
+               path
+            else
+               if path.start_with?('/')
+                  path
+               else
+                  "/#{ path }"
+               end.downcase
+            end
+         end
       end
    end
 end

data/lib/sinatra/bouncer/version.rb

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

data/lib/sinatra/bouncer.rb

@@ -34,20 +34,9 @@ module Sinatra
          base_class.set :bouncer, BasicBouncer.new
 
          base_class.before do
-            http_method = request.request_method.downcase.to_sym
-            path        = request.path.downcase
-
-            settings.bouncer.bounce(self) unless settings.bouncer.can?(http_method, path, self)
+            settings.bouncer.bounce(self) unless settings.bouncer.can?(request.request_method, request.path, self)
          end
       end
-
-      def bounce_with(&block)
-         bouncer.bounce_with = block
-      end
-
-      def rules(&block)
-         settings.bouncer.instance_exec(&block)
-      end
    end
 
    register Sinatra::Bouncer

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sinatra-bouncer
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 3.0.0
 platform: ruby
 authors:
 - Tenjin Inc
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-11-13 00:00:00.000000000 Z
+date: 2023-11-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: sinatra