rhino-rails 4.3.0 → 4.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 43ae824cbc25eeacd6ce09fc6a9d5b218206d8877fc672a49b728dd6fbf10b1c
-  data.tar.gz: 6590704092005ad3b6c0b959b0166332387b2503d8db19e57fc17be7734c2d0b
+  metadata.gz: 0155b30eedf93061b38295ed96254194529de0abf03aad309becc312a512c5ba
+  data.tar.gz: 5e1ce1624bab2a77f8603ebdf6984a43e4bd71d277f51900ae533465e4fd0881
 SHA512:
-  metadata.gz: a8007c1c7f90ceae1cb0aed88ca032009e417f0e8052897f5ed73e514d9f3c782c6304f92f9b16002179d6492f5510d7ef3a3e00f5902094a925c2dd74c3b781
-  data.tar.gz: a58f92293f66ad18700a9ec39bf48e0696f64c72b7ac82c64fde715775821a5f00c3b90ce8e61dbf76b4edf4973eb520bc04b075e04ffb16c84fe7253c350e74
+  metadata.gz: 975f1ee3efc83423ae775131eace5689a7b09269541848da21e286f2f55cedd71b265a8e3c5c448a85cc7b9c8ecdde2e27dd615ef1a26719732a7d958cbfb8da
+  data.tar.gz: 3a32ccaf04ad8f351828752a83efac31503d53afbd4c3239d0f38e836c8e151dd4681f2a650a853e9d6d728e6477f34e72023680c6bbd36dc63369ad6ca6d10c

data/README.md

@@ -40,6 +40,7 @@ Register a model, get a full REST API instantly.
 | 26 | **Generator CLI** | `rhino:install`, `rhino:generate`, `rhino:blueprint`, `rhino:export_postman`. |
 | 27 | **Postman Export** | Auto-generated Postman Collection v2.1 with all endpoints. |
 | 28 | **Blueprint System** | YAML-to-code generation for models, migrations, factories, policies, tests, and seeders. |
+| 29 | **Named Scopes** | `?scope=availableForDrivers` client-selectable scopes (whitelisted via `rhino_scopes`), plus a `rhino_default_scope` applied when none is requested. Unknown scopes return 403. Applies to `index`/`trashed` only. |
 
 ## Quick Start
 

data/lib/rhino/concerns/has_rhino.rb

@@ -13,6 +13,8 @@ module Rhino
   #     rhino_includes :user, :comments
   #     rhino_fields :id, :title, :status, :created_at
   #     rhino_search :title, :content, 'user.name'
+  #     rhino_scopes :active, available_for_drivers: Scopes::AvailableForDriversScope
+  #     rhino_default_scope :active
   #     rhino_per_page 25
   #     rhino_pagination_enabled true
   #     rhino_middleware 'throttle:60,1'
@@ -24,6 +26,8 @@ module Rhino
 
     included do
       class_attribute :allowed_filters, default: []
+      class_attribute :allowed_scopes, default: {}
+      class_attribute :default_rhino_scope, default: nil
       class_attribute :allowed_sorts, default: []
       class_attribute :default_sort_field, default: nil
       class_attribute :allowed_includes, default: []
@@ -42,6 +46,23 @@ module Rhino
         self.allowed_filters = fields.map(&:to_s)
       end
 
+      # Whitelist client-selectable named scopes for ?scope=.
+      #   rhino_scopes :active, available_for_drivers: Scopes::AvailableForDriversScope
+      # Bare symbols must name an existing ActiveRecord scope/class method on the model.
+      # Hash values may be a Proc(relation, user) or a Rhino::ResourceScope subclass.
+      def rhino_scopes(*names, **named)
+        merged = allowed_scopes.dup
+        names.each { |n| merged[n.to_s] = n.to_sym }
+        named.each { |k, v| merged[k.to_s] = v }
+        self.allowed_scopes = merged
+      end
+
+      # Named scope applied when no ?scope param is sent. Convenience, not a
+      # security boundary. Value is the scope name (string/symbol).
+      def rhino_default_scope(name)
+        self.default_rhino_scope = name.to_s
+      end
+
       def rhino_sorts(*fields)
         self.allowed_sorts = fields.map(&:to_s)
       end

data/lib/rhino/controllers/resources_controller.rb

@@ -16,6 +16,10 @@ module Rhino
       render json: { message: "This action is unauthorized." }, status: :forbidden
     end
 
+    rescue_from Rhino::ScopeNotAllowedError do |e|
+      render json: { message: "Scope '#{e.message}' is not allowed" }, status: :forbidden
+    end
+
     # Cache for auto-detected organization paths (class-level, survives across requests)
     @@organization_path_cache = {}
 
@@ -38,7 +42,7 @@ module Rhino
     def index
       authorize model_class, :index?, policy_class: policy_for(model_class)
 
-      builder = QueryBuilder.new(model_class, params: params)
+      builder = QueryBuilder.new(model_class, params: params, named_scopes: true)
       apply_organization_scope(builder)
       builder.build
 
@@ -170,7 +174,7 @@ module Rhino
     def trashed
       authorize model_class, :view_trashed?, policy_class: policy_for(model_class)
 
-      builder = QueryBuilder.new(model_class.discarded, params: params)
+      builder = QueryBuilder.new(model_class.discarded, params: params, named_scopes: true)
       apply_organization_scope(builder)
       builder.build
 
@@ -900,7 +904,7 @@ module Rhino
     end
 
     def params_hash
-      params.except(:controller, :action, :model_slug, :route_group, :organization, :id, :format).to_unsafe_h
+      params.except(:controller, :action, :model_slug, :route_group, :organization, :id, :format, :scope).to_unsafe_h
     end
   end
 end

data/lib/rhino/models/rhino_model.rb

@@ -104,6 +104,36 @@ module Rhino
     #     self.allowed_filters = %w[status user_id category_id]
     self.allowed_filters = []
 
+    # @!attribute [rw] allowed_scopes
+    #   Client-selectable named scopes (whitelist for +?scope=+).
+    #
+    #   Controls which named scopes can be requested via +?scope=name+
+    #   (camelCase on the wire, underscored internally). Only whitelisted
+    #   scopes are accepted — unknown/unlisted names return 403.
+    #
+    #   Set via DSL: +rhino_scopes :active, available_for_drivers: Scopes::AvailableForDriversScope+
+    #
+    #   Query: +GET /api/posts?scope=availableForDrivers+
+    #
+    #   @return [Hash{String => Symbol, Proc, Class}]
+    #   @example
+    #     rhino_scopes :active, available_for_drivers: Scopes::AvailableForDriversScope
+    self.allowed_scopes = {}
+
+    # @!attribute [rw] default_rhino_scope
+    #   Named scope applied automatically when no +?scope+ param is sent.
+    #
+    #   This is a listing convenience, not a security boundary. The default
+    #   scope is always requestable by name even if it is not otherwise
+    #   whitelisted via +rhino_scopes+.
+    #
+    #   Set via DSL: +rhino_default_scope :active+
+    #
+    #   @return [String, nil]
+    #   @example
+    #     rhino_default_scope :active
+    self.default_rhino_scope = nil
+
     # @!attribute [rw] allowed_sorts
     #   Sortable columns.
     #

data/lib/rhino/query_builder.rb

@@ -14,14 +14,16 @@ module Rhino
   class QueryBuilder
     attr_reader :scope, :model_class, :params
 
-    def initialize(model_class, params: {})
+    def initialize(model_class, params: {}, named_scopes: false)
       @model_class = model_class
       @scope = model_class.all
       @params = params
+      @named_scopes = named_scopes
     end
 
     # Apply all query modifications based on params and model config.
     def build
+      apply_named_scope if @named_scopes
       apply_filters
       apply_default_sort
       apply_sorts
@@ -62,6 +64,41 @@ module Rhino
 
     private
 
+    # ------------------------------------------------------------------
+    # Named scopes: ?scope=availableForDrivers
+    # ------------------------------------------------------------------
+    #
+    # Only runs for collection endpoints (index/trashed), which pass
+    # +named_scopes: true+. `show` (including its ?include= build path) stays
+    # unscoped so a record excluded by the default scope is still viewable.
+    def apply_named_scope
+      requested = params[:scope].presence
+      name = requested ? requested.to_s.underscore : model_class.try(:default_rhino_scope)
+      return unless name
+
+      allowed = model_class.try(:allowed_scopes) || {}
+      entry = allowed[name]
+      # The default scope is implicitly allowed when requested by name.
+      entry ||= name.to_sym if name == model_class.try(:default_rhino_scope)
+
+      # Echo the client's wire name (not the underscored form) in the error.
+      raise Rhino::ScopeNotAllowedError, (requested ? requested.to_s : name) if entry.nil?
+
+      user = defined?(RequestStore) ? RequestStore.store[:rhino_current_user] : nil
+
+      @scope =
+        case entry
+        when Symbol
+          # Whitelisted AR scope. Client input never reaches public_send unless the
+          # developer declared it via rhino_scopes. .merge composes with default_scopes.
+          @scope.merge(model_class.public_send(entry))
+        when Proc
+          entry.call(@scope, user)
+        else
+          entry.new.apply(@scope) # Rhino::ResourceScope subclass (user/org/role helpers)
+        end
+    end
+
     # ------------------------------------------------------------------
     # Filtering: ?filter[status]=published&filter[user_id]=1
     # ------------------------------------------------------------------

data/lib/rhino/scope_not_allowed_error.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Rhino
+  # Raised when a client requests a ?scope= name that is not whitelisted via
+  # rhino_scopes / rhino_default_scope. Rendered as 403 by ResourcesController.
+  class ScopeNotAllowedError < StandardError; end
+end

data/lib/rhino/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Rhino
-  VERSION = "4.3.0"
+  VERSION = "4.4.0"
 end

data/lib/rhino.rb

@@ -3,6 +3,7 @@
 require "rhino/version"
 require "rhino/configuration"
 require "rhino/auth_rejected"
+require "rhino/scope_not_allowed_error"
 require "rhino/auth_hooks"
 require "rhino/group_membership"
 require "rhino/resource_scope"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rhino-rails
 version: !ruby/object:Gem::Version
-  version: 4.3.0
+  version: 4.4.0
 platform: ruby
 authors:
 - Bruno Cipolla
@@ -235,6 +235,7 @@ files:
 - lib/rhino/routes.rb
 - lib/rhino/routing/domain_constraint.rb
 - lib/rhino/routing/route_group_validator.rb
+- lib/rhino/scope_not_allowed_error.rb
 - lib/rhino/tasks/rhino.rake
 - lib/rhino/templates/audit_trail/create_audit_logs.rb.erb
 - lib/rhino/templates/generate/factory.rb.erb