rhino-rails 4.7.2 → 4.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 632861555ee3e2508a90ec546b6cb0412368bc141a7d387b2f92698531605b86
-  data.tar.gz: 91b3ad79b1c0b0b492f1f3003e906ce11e9f3fa62e81b067ecfb9c0b7740a025
+  metadata.gz: 9e5e5a25c72952be8b915169fd2f5320476a1414b20aba43428c636e92513188
+  data.tar.gz: 48af3696d7a56d92fc1e9f7e270077f108579bf1e2701542e563d6a75f94dd4e
 SHA512:
-  metadata.gz: 2c5fee208f22ae88b0531f4075e6183d6d0a17137c43423e7f491dbf341848764ce16418feca131b13c45c4295f6b4a3507eebb52e1e30b2f887dcbcfdd624c1
-  data.tar.gz: 83468b5afe671a2b0313778e57c2f053747129156d643bb85d5543513ea2d02aa6c2b63c4b70bb5f04613cb79bbb21544ba142bb4f127ebf56247581aab4c079
+  metadata.gz: '099ea8dc9ecea149b1fd30cd56446fb107d474478cb669d39dbc1bb2d01a16a1669160f6912658da035fa9dc62e26a4639962ad9f661848919ca3b15178f59da'
+  data.tar.gz: d9423c888d912f451312d5c0b3243dd1a1b43493ee4fb60378fafa17127c9f22f445cd0161197492e08543ce6946d2202cfef1a8891f7847e5677374f96c7991

data/README.md

@@ -16,7 +16,7 @@ Register a model, get a full REST API instantly.
 | 2 | **Authentication** | Login, logout, password recovery/reset, invitation-based registration. |
 | 3 | **Authorization & Policies** | Pundit-based permission checks (`{slug}.{action}`), wildcard support. |
 | 4 | **Role-Based Access Control** | Per-org roles via `user_roles` join table. |
-| 5 | **Attribute-Level Permissions** | Control which fields each role can read and write. |
+| 5 | **Attribute-Level Permissions** | Control which fields each role can read and write. A field a role cannot read is also refused as a `?filter[]` or a `?sort`, and skipped by `?search=`. |
 | 6 | **Validation** | Dual-layer: format rules + field presence. Supports role-keyed rules. |
 | 7 | **Cross-Tenant FK Validation** | `exists:` rules auto-scoped to current org, even through indirect FK relationships. |
 | 8 | **Filtering** | `?filter[field]=value` with AND/OR logic. |
@@ -40,7 +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. |
+| 29 | **Named Scopes** | `?scope=availableForDrivers` client-selectable scopes (whitelisted via `rhino_scopes`), plus a `rhino_default_scope` applied when none is requested. A scope may declare parameters the client fills in with `?scope[name][param]=value`, and up to three scopes may be combined. Unknown scopes, scopes the policy's `permitted_scopes` denies, and arguments that do not match the declared parameters return 403. Applies to `index`/`trashed` only. |
 | 30 | **Configurable Route Key** | Match the `:id` URL segment against any column (`rhino_route_key :hash_id` per model, or global `config.route_key`). Member endpoints only — payload FKs and nested-operation ids stay primary-key based. |
 
 ## Quick Start

data/lib/rhino/concerns/has_rhino.rb

@@ -52,6 +52,22 @@ module Rhino
       #   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.
+      #
+      # A scope may also declare parameters the client fills in, in the order the
+      # scope takes them. A parameter listed under :optional may be left out.
+      #   rhino_scopes since:  { params: [:date] },
+      #                window: { params: %i[min max] },
+      #                titled: { params: %i[title status], optional: [:status] },
+      #                mine:   { params: [:status], with: ->(rel, user, status) { ... } }
+      #
+      # Queries:
+      #   GET /api/routes?scope=active
+      #   GET /api/routes?scope[since]=2026-01-01
+      #   GET /api/routes?scope[window][min]=1&scope[window][max]=9
+      #
+      # Up to three scopes may be combined in the bracket form, applied in the
+      # order the URL lists them. A scope with no declared parameters never
+      # receives client input: sending any is a 403.
       def rhino_scopes(*names, **named)
         merged = allowed_scopes.dup
         names.each { |n| merged[n.to_s] = n.to_sym }

data/lib/rhino/context.rb

@@ -30,20 +30,24 @@ module Rhino
       end
     end
 
-    # The route group serving the current request, as stashed into RequestStore
-    # by Rhino's own controllers and by Rhino::RouteGroupContext in custom ones.
-    # Nil outside a request or when the route carries no group.
+    # The active route group: the explicit override if one is in effect (set by
+    # Rhino.in_route_group), else the group stashed into RequestStore by Rhino's
+    # own controllers and by Rhino::RouteGroupContext in custom ones.
+    #
+    # Unlike user/organization, an override never *erases* the request's group —
+    # +with+ only installs a non-nil one — so Rhino.for_user(u).query(M) inside a
+    # non-tenant request keeps that request's group.
     def route_group
-      return nil unless defined?(RequestStore)
+      value = store[:rhino_route_group]
+      value = RequestStore.store[:rhino_route_group] if value.nil? && defined?(RequestStore)
 
-      value = RequestStore.store[:rhino_route_group]
-      value.nil? || value.to_s.empty? ? nil : value
+      value.nil? || value.to_s.empty? ? nil : value.to_s
     end
 
     # Run +block+ with the given user/organization installed into RequestStore.
     # Snapshots the prior RequestStore user+org, sets the new ones, yields, and
     # restores the snapshot in an ensure. Returns the block's value.
-    def with(user:, organization:)
+    def with(user:, organization:, route_group: nil)
       return yield unless defined?(RequestStore)
 
       had_user = RequestStore.store.key?(:rhino_current_user)
@@ -51,6 +55,13 @@ module Rhino
       prev_user = RequestStore.store[:rhino_current_user]
       prev_org  = RequestStore.store[:rhino_organization]
 
+      # A route group is only ever ADDED, never cleared: with no explicit group
+      # the request's own one (if any) stays in effect.
+      had_group  = RequestStore.store.key?(:rhino_route_group)
+      prev_group = RequestStore.store[:rhino_route_group]
+      had_override_group  = store.key?(:rhino_route_group)
+      prev_override_group = store[:rhino_route_group]
+
       # Track the active override so Context.user/organization prefer it even when
       # the passed value is nil (distinguishing "explicitly nil" from "absent").
       had_override_user = store.key?(:rhino_current_user)
@@ -63,6 +74,11 @@ module Rhino
       store[:rhino_current_user] = user
       store[:rhino_organization] = organization
 
+      if route_group
+        RequestStore.store[:rhino_route_group] = route_group.to_s
+        store[:rhino_route_group] = route_group.to_s
+      end
+
       begin
         yield
       ensure
@@ -87,6 +103,20 @@ module Rhino
         else
           store.delete(:rhino_organization)
         end
+
+        if route_group
+          if had_group
+            RequestStore.store[:rhino_route_group] = prev_group
+          else
+            RequestStore.store.delete(:rhino_route_group)
+          end
+
+          if had_override_group
+            store[:rhino_route_group] = prev_override_group
+          else
+            store.delete(:rhino_route_group)
+          end
+        end
       end
     end
 

data/lib/rhino/controllers/resources_controller.rb

@@ -17,7 +17,18 @@ module Rhino
     end
 
     rescue_from Rhino::ScopeNotAllowedError do |e|
-      render json: { message: "Scope '#{e.message}' is not allowed" }, status: :forbidden
+      # A message that already reads as a sentence is rendered as-is (the
+      # too-many-scopes case); a bare name becomes the standard refusal.
+      message = e.message.include?(" ") ? e.message : "Scope '#{e.message}' is not allowed"
+      render json: { message: message }, status: :forbidden
+    end
+
+    rescue_from Rhino::InvalidScopeArgumentsError do |e|
+      render json: { message: e.message }, status: :forbidden
+    end
+
+    rescue_from Rhino::QueryAttributeNotAllowedError do |e|
+      render json: { message: e.message }, status: :forbidden
     end
 
     # Cache for auto-detected organization paths (class-level, survives across requests)

data/lib/rhino/invalid_scope_arguments_error.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Rhino
+  # Raised when a client-requested named scope is given arguments that do not
+  # match the model's declared parameter spec. Rendered as 403 by
+  # ResourcesController, message and all: it is only ever raised after the scope
+  # name itself passed the whitelist and the policy, so naming the parameters
+  # reveals nothing about scopes the user may not use.
+  class InvalidScopeArgumentsError < StandardError; end
+
+  # Raised when a client filters or sorts by an attribute the policy hides from
+  # them. Rendered as 403 by ResourcesController.
+  class QueryAttributeNotAllowedError < StandardError; end
+end

data/lib/rhino/policies/resource_policy.rb

@@ -119,6 +119,24 @@ module Rhino
       []
     end
 
+    # ------------------------------------------------------------------
+    # Scope Permissions
+    # ------------------------------------------------------------------
+
+    # Override to restrict which named scopes this user may select with ?scope=.
+    # Return ['*'] to allow every scope the model declares (default). The model's
+    # rhino_scopes declaration still applies: this can only narrow it.
+    #
+    # The model's rhino_default_scope is applied by the server when the client
+    # sends no scope at all, so it is not subject to this list. Requesting it by
+    # name is.
+    #
+    # @param user [Object, nil] The authenticated user
+    # @return [Array<String>]
+    def permitted_scopes(user)
+      ['*']
+    end
+
     # Override to whitelist which fields a user can submit on create.
     # Return ['*'] to allow all fields (default).
     #

data/lib/rhino/query.rb

@@ -21,9 +21,10 @@ module Rhino
     #
     # Fail closed: an org-scopable model with no org context RAISES
     # Rhino::MissingTenantContext rather than returning an unscoped relation —
-    # unless the request is served by a route group declared non-tenant
-    # (`tenant: false`), where a query legitimately spans every organization. An
-    # explicit organization is always honored, in every group.
+    # unless the query belongs to a route group declared non-tenant
+    # (`tenant: false`), either because the request is served by that group or
+    # because the caller said so with Rhino.in_route_group(...). An explicit
+    # organization is always honored, in every group.
     def query(model_class)
       org = Rhino::Context.organization
 
@@ -44,8 +45,8 @@ module Rhino
     # Build a tenant-scoped relation and apply a whitelisted ?scope= named scope
     # on top of it. +scope_name+ is the wire name (camelCase accepted); nil falls
     # back to the model's rhino_default_scope.
-    def scoped_query(model_class, scope_name = nil)
-      apply_named_scope(query(model_class), model_class, scope_name)
+    def scoped_query(model_class, scope_name = nil, *args)
+      apply_named_scope(query(model_class), model_class, scope_name, *args)
     end
 
     # Begin the fluent explicit builder for +user+.
@@ -53,6 +54,20 @@ module Rhino
       Rhino::PendingScopedContext.new(user: user)
     end
 
+    # Begin an explicit context that acts as the named route group, for use
+    # where no request resolves one — an Active Job, a rake task, the console,
+    # a test.
+    #
+    # The group's own configuration still decides the boundary: naming a group
+    # declared +tenant: false+ lets the query span every organization, while
+    # naming any other group keeps failing closed.
+    #
+    #   Rhino.in_route_group(:admin).query(Task)
+    #   Rhino.for_user(user).in_route_group(:admin).run { ... }
+    def in_route_group(route_group)
+      Rhino::PendingScopedContext.new(user: nil, route_group: route_group)
+    end
+
     # The ambient context resolver.
     def context
       Rhino::Context
@@ -62,26 +77,29 @@ module Rhino
     # Shared by Rhino.scoped_query and PendingScopedContext#scoped_query. Uses the
     # same allowed_scopes / default_rhino_scope mechanism as the QueryBuilder.
     # @api private
-    def apply_named_scope(relation, model_class, scope_name = nil)
+    def apply_named_scope(relation, model_class, scope_name = nil, *args)
       requested = scope_name.to_s.presence
       name = requested ? requested.underscore : model_class.try(:default_rhino_scope)
       return relation unless name
 
-      allowed = model_class.try(:allowed_scopes) || {}
+      allowed = Rhino::ScopeSpec.normalize(model_class.try(:allowed_scopes))
       entry = allowed[name]
-      entry ||= name.to_sym if name == model_class.try(:default_rhino_scope)
+      entry ||= { target: name.to_sym, params: [], optional: [] } if name == model_class.try(:default_rhino_scope)
 
       raise Rhino::ScopeNotAllowedError, (requested || name) if entry.nil?
 
       user = defined?(RequestStore) ? RequestStore.store[:rhino_current_user] : nil
+      target = entry[:target] || name.to_sym
 
-      case entry
-      when Symbol
-        relation.merge(model_class.public_send(entry))
+      # Server-side caller: the policy gate belongs to the request path, and any
+      # arguments here come from application code, not from a client.
+      case target
+      when Symbol, String
+        relation.merge(model_class.public_send(target, *args))
       when Proc
-        entry.call(relation, user)
+        target.call(relation, user, *args)
       else
-        entry.new.apply(relation)
+        target.new.apply(relation, *args)
       end
     end
   end
@@ -89,9 +107,10 @@ module Rhino
   # Fluent explicit-context builder. Holds a user (and, once chained, an org) and
   # resolves queries with that context installed into RequestStore at build time.
   class PendingScopedContext
-    def initialize(user:, organization: nil)
+    def initialize(user:, organization: nil, route_group: nil)
       @user = user
       @organization = organization
+      @route_group = route_group
     end
 
     def in_organization(organization)
@@ -99,6 +118,18 @@ module Rhino
       self
     end
 
+    # Act as the named route group for this context (see Rhino.in_route_group).
+    def in_route_group(route_group)
+      @route_group = route_group
+      self
+    end
+
+    # Set the explicit user for this context.
+    def for_user(user)
+      @user = user
+      self
+    end
+
     # Build a fully-baked relation for +model_class+ under this explicit context.
     #
     # Because Rails default_scopes bake at BUILD time, we install the user+org into
@@ -106,15 +137,15 @@ module Rhino
     # The org+user are baked into the returned relation — no stickiness, fully
     # isolated: a later Rhino.query with no context still fails closed.
     def query(model_class)
-      Rhino::Context.with(user: @user, organization: @organization) do
+      Rhino::Context.with(user: @user, organization: @organization, route_group: @route_group) do
         Rhino.query(model_class)
       end
     end
 
     # Build a fully-baked, named-scoped relation under this explicit context.
-    def scoped_query(model_class, scope_name = nil)
-      Rhino::Context.with(user: @user, organization: @organization) do
-        Rhino.scoped_query(model_class, scope_name)
+    def scoped_query(model_class, scope_name = nil, *args)
+      Rhino::Context.with(user: @user, organization: @organization, route_group: @route_group) do
+        Rhino.scoped_query(model_class, scope_name, *args)
       end
     end
 
@@ -122,7 +153,7 @@ module Rhino
     # inside the block see the context; RequestStore is restored afterward.
     # Returns the block's value.
     def run(&block)
-      Rhino::Context.with(user: @user, organization: @organization, &block)
+      Rhino::Context.with(user: @user, organization: @organization, route_group: @route_group, &block)
     end
   end
 end

data/lib/rhino/query_builder.rb

@@ -12,6 +12,11 @@ module Rhino
   #   - Fields:       ?fields[posts]=id,title,status
   #   - Includes:     ?include=user,comments
   class QueryBuilder
+    # How many named scopes one request may combine. Scopes are arbitrary query
+    # fragments, so stacking many of them is a good way to build an accidental
+    # cross join; three covers every real listing.
+    MAX_SCOPES_PER_REQUEST = 3
+
     attr_reader :scope, :model_class, :params
 
     def initialize(model_class, params: {}, named_scopes: false)
@@ -83,33 +88,82 @@ module Rhino
     # +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
+      raw = params[:scope]
+      raw = raw.to_unsafe_h if raw.respond_to?(:to_unsafe_h)
+
+      declared = Rhino::ScopeSpec.normalize(model_class.try(:allowed_scopes))
+      default = model_class.try(:default_rhino_scope)
+
+      # Nothing requested: the model's default scope, which takes no arguments.
+      if raw.nil? || raw == "" || raw == {}
+        return if default.nil?
+
+        return run_named_scope(default.to_s, declared[default.to_s] || {}, [])
+      end
+
+      requested =
+        if raw.is_a?(Hash)
+          raw
+        else
+          # Legacy form — ?scope=name, one scope, no arguments.
+          { raw.to_s => "" }
+        end
+
+      raise Rhino::ScopeNotAllowedError, "Too many scopes requested" if requested.size > MAX_SCOPES_PER_REQUEST
+
+      permitted = permitted_scope_names
+
+      requested.each do |wire_name, raw_arguments|
+        raise Rhino::ScopeNotAllowedError, wire_name.to_s if wire_name.to_s.empty?
+
+        name = wire_name.to_s.underscore
+        entry = declared[name]
+        # The default scope is implicitly allowed when requested by name.
+        entry ||= { target: name.to_sym, params: [], optional: [] } if name == default
+
+        # Echo the client's wire name (not the underscored form) in the error.
+        raise Rhino::ScopeNotAllowedError, wire_name.to_s if entry.nil?
 
-      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)
+        if permitted != ["*"] && !permitted.include?(name)
+          raise Rhino::ScopeNotAllowedError, wire_name.to_s
+        end
 
-      # Echo the client's wire name (not the underscored form) in the error.
-      raise Rhino::ScopeNotAllowedError, (requested ? requested.to_s : name) if entry.nil?
+        run_named_scope(name, entry, Rhino::ScopeSpec.bind(wire_name.to_s, entry, raw_arguments))
+      end
+    end
 
-      user = defined?(RequestStore) ? RequestStore.store[:rhino_current_user] : nil
+    # Run one already-authorized named scope, passing the bound arguments in the
+    # order the model declared them.
+    def run_named_scope(name, entry, args)
+      target = entry[:target] || name.to_sym
+      user = current_user
 
       @scope =
-        case entry
-        when Symbol
+        case target
+        when Symbol, String
           # 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))
+          @scope.merge(model_class.public_send(target, *args))
         when Proc
-          entry.call(@scope, user)
+          target.call(@scope, user, *args)
         else
-          entry.new.apply(@scope) # Rhino::ResourceScope subclass (user/org/role helpers)
+          target.new.apply(@scope, *args) # Rhino::ResourceScope subclass (user/org/role helpers)
         end
     end
 
+    # Scope names this user may select, or ["*"] when the policy does not
+    # restrict them (the default, and the behavior of every policy written
+    # before permitted_scopes existed).
+    def permitted_scope_names
+      policy = policy_instance
+      return ["*"] unless policy.respond_to?(:permitted_scopes)
+
+      permitted = policy.permitted_scopes(current_user)
+      return ["*"] unless permitted.is_a?(Array)
+
+      permitted.map(&:to_s)
+    end
+
     # ------------------------------------------------------------------
     # Filtering: ?filter[status]=published&filter[user_id]=1
     # ------------------------------------------------------------------
@@ -125,6 +179,10 @@ module Rhino
         key = key.to_s
         next unless allowed.include?(key)
 
+        unless attribute_queryable?(key)
+          raise Rhino::QueryAttributeNotAllowedError, "Filter '#{key}' is not allowed"
+        end
+
         if value.to_s.include?(",")
           # Multiple values: OR condition
           values = value.to_s.split(",").map(&:strip)
@@ -146,7 +204,9 @@ module Rhino
       default = model_class.try(:default_sort_field)
       return unless default
 
-      apply_sort_string(default)
+      # The default sort is the server's own choice, so it is not subject to the
+      # client allowlist or to the policy.
+      apply_sort_string(default, client_supplied: false)
     end
 
     def apply_sorts
@@ -156,7 +216,7 @@ module Rhino
       apply_sort_string(sort_param.to_s)
     end
 
-    def apply_sort_string(sort_string)
+    def apply_sort_string(sort_string, client_supplied: true)
       allowed = model_class.try(:allowed_sorts) || []
 
       sort_string.split(",").each do |field|
@@ -169,12 +229,83 @@ module Rhino
           direction = :asc
         end
 
-        next unless allowed.empty? || allowed.include?(column)
+        if client_supplied
+          # Deny by default: an undeclared column is ignored, never sorted by.
+          next unless allowed.include?(column)
+
+          unless attribute_queryable?(column)
+            raise Rhino::QueryAttributeNotAllowedError, "Sort '#{column}' is not allowed"
+          end
+        end
 
         @scope = @scope.order(column => direction)
       end
     end
 
+    # ------------------------------------------------------------------
+    # Policy-aware attribute gate
+    # ------------------------------------------------------------------
+    #
+    # Attribute permissions used to apply only when serializing, so a hidden
+    # column stayed usable as a query predicate: ?filter[salary]=300000 never
+    # printed a salary but told the caller whose salary it was, and ?sort= leaked
+    # the whole ordering. Filters, sorts and search now go through the same gate
+    # as the response body.
+
+    def attribute_queryable?(name)
+      return true if name.nil? || name.to_s.empty?
+
+      attribute_path_allowed?(base_class, name.to_s)
+    end
+
+    def attribute_path_allowed?(klass, path)
+      if path.include?(".")
+        relation, rest = path.split(".", 2)
+        assoc = klass.respond_to?(:reflect_on_association) ? klass.reflect_on_association(relation.to_sym) : nil
+        # An unresolvable relation is left alone, so nothing that worked before
+        # starts failing for a reason nobody can find.
+        return true if assoc.nil?
+
+        begin
+          return attribute_path_allowed?(assoc.klass, rest)
+        rescue NoMethodError, NameError
+          return true
+        end
+      end
+
+      policy = policy_instance(klass)
+      user = current_user
+
+      if policy.respond_to?(:hidden_attributes_for_show)
+        return false if Array(policy.hidden_attributes_for_show(user)).map(&:to_s).include?(path)
+      end
+
+      return true unless policy.respond_to?(:permitted_attributes_for_show)
+
+      permitted = Array(policy.permitted_attributes_for_show(user)).map(&:to_s)
+      permitted == ["*"] || permitted.include?(path)
+    end
+
+    # The model class behind the builder: +model_class+ may be a relation, as it
+    # is for the trashed listing.
+    def base_class
+      @base_class ||= model_class.respond_to?(:klass) ? model_class.klass : model_class
+    end
+
+    def policy_instance(klass = base_class)
+      @policy_instances ||= {}
+      @policy_instances[klass] ||= begin
+        policy_class = "#{klass.name}Policy".safe_constantize || Rhino::ResourcePolicy
+        policy_class.new(current_user, klass)
+      rescue StandardError
+        Rhino::ResourcePolicy.new(current_user, klass)
+      end
+    end
+
+    def current_user
+      defined?(RequestStore) ? RequestStore.store[:rhino_current_user] : nil
+    end
+
     # ------------------------------------------------------------------
     # Search: ?search=term
     # ------------------------------------------------------------------
@@ -183,8 +314,18 @@ module Rhino
       search_term = params[:search]
       return unless search_term.present?
 
-      columns = model_class.try(:allowed_search) || []
-      return if columns.empty?
+      declared = model_class.try(:allowed_search) || []
+      return if declared.empty?
+
+      columns = declared.select { |column| attribute_queryable?(column.to_s) }
+
+      # Every searchable column is hidden from this user. Searching a hidden
+      # column tells the caller what is in it, so return nothing rather than
+      # silently returning the whole list the client asked to narrow.
+      if columns.empty?
+        @scope = @scope.none
+        return
+      end
 
       term = "%#{search_term.to_s.downcase}%"
       conditions = []

data/lib/rhino/scope_spec.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Rhino
+  # Parses the +rhino_scopes+ declaration and binds the arguments a client sent
+  # for <tt>?scope[name][param]=value</tt> to the scope's parameters.
+  #
+  # Declaration forms (all may be mixed in one call):
+  #
+  #   rhino_scopes :archived,                                   # no parameters
+  #                since: { params: [:date] },                  # one parameter
+  #                window: { params: %i[min max] },             # two, both required
+  #                titled: { params: %i[title status], optional: [:status] },
+  #                mine:   ->(relation, user) { ... },          # legacy proc
+  #                fresh:  Scopes::FreshScope                    # legacy scope class
+  #
+  # A scope with no declared parameters never receives arguments: sending any
+  # is a 403, so a scope written without client input can never be handed some.
+  module ScopeSpec
+    module_function
+
+    # Normalize a raw +allowed_scopes+ hash into
+    # <tt>name => { target:, params:, optional: }</tt>.
+    def normalize(declared)
+      (declared || {}).each_with_object({}) do |(name, value), out|
+        key = name.to_s
+        out[key] = normalize_entry(key, value)
+      end
+    end
+
+    def normalize_entry(name, value)
+      if value.is_a?(Hash) || value.is_a?(ActiveSupport::HashWithIndifferentAccess)
+        spec = value.symbolize_keys
+        params = Array(spec[:params]).map(&:to_s)
+        optional = Array(spec[:optional]).map(&:to_s) & params
+
+        { target: spec[:with] || name.to_sym, params: params, optional: optional }
+      else
+        { target: value, params: [], optional: [] }
+      end
+    end
+
+    # Bind the raw value a client sent for one scope to positional arguments,
+    # in the order the model declared them.
+    #
+    # +raw+ is whatever the query string produced for <tt>scope[<name>]</tt>:
+    # nil or "" (no arguments), a scalar (the single parameter), or a hash of
+    # parameter name => value.
+    #
+    # Raises Rhino::InvalidScopeArgumentsError.
+    def bind(name, spec, raw)
+      params = spec[:params]
+      given = normalize_raw_arguments(name, params, raw)
+
+      given.each_key do |key|
+        unless params.include?(key)
+          raise Rhino::InvalidScopeArgumentsError, "Scope '#{name}' does not accept parameter '#{key}'"
+        end
+      end
+
+      args = params.map do |param|
+        if given.key?(param)
+          coerce(given[param])
+        elsif spec[:optional].include?(param)
+          nil
+        else
+          raise Rhino::InvalidScopeArgumentsError, "Scope '#{name}' requires parameter '#{param}'"
+        end
+      end
+
+      # Drop trailing nils so an omitted optional parameter falls back to the
+      # default in the scope's own signature.
+      args.pop while args.any? && args.last.nil?
+      args
+    end
+
+    def normalize_raw_arguments(name, params, raw)
+      # ?scope[archived]= (or a bare ?scope[archived]): no arguments. A scope
+      # with required parameters still fails, in bind, naming them.
+      return {} if raw.nil? || raw == ""
+
+      raw = raw.to_unsafe_h if raw.respond_to?(:to_unsafe_h)
+
+      if raw.is_a?(Array)
+        # A positional list (scope[between][]=a) names nothing.
+        raise Rhino::InvalidScopeArgumentsError, "Scope '#{name}' requires named parameters"
+      end
+
+      unless raw.is_a?(Hash)
+        raise Rhino::InvalidScopeArgumentsError, "Scope '#{name}' does not accept arguments" if params.empty?
+
+        # A bare value binds to the single declared parameter. Two parameters can
+        # never be guessed at from one value.
+        if params.length > 1
+          raise Rhino::InvalidScopeArgumentsError, "Scope '#{name}' requires named parameters"
+        end
+
+        return { params.first => raw }
+      end
+
+      raise Rhino::InvalidScopeArgumentsError, "Scope '#{name}' does not accept arguments" if params.empty?
+
+      raw.each_with_object({}) do |(key, value), out|
+        unless value.is_a?(String) || value.is_a?(Numeric) || value.is_a?(TrueClass) ||
+               value.is_a?(FalseClass) || value.nil?
+          raise Rhino::InvalidScopeArgumentsError, "Scope '#{name}' requires named parameters"
+        end
+
+        out[key.to_s.underscore] = value
+      end
+    end
+
+    # Query-string values always arrive as strings; hand scope bodies real
+    # booleans so a check cannot be fooled by the string "false".
+    def coerce(value)
+      return value unless value.is_a?(String)
+
+      case value.downcase
+      when "true" then true
+      when "false" then false
+      else value
+      end
+    end
+  end
+end

data/lib/rhino/templates/rhino.rb

@@ -58,8 +58,14 @@ Rhino.configure do |config|
   # Custom (non-Rhino) controllers publish their group by including
   # Rhino::RouteGroupContext and declaring `rhino_route_group :admin`, or by
   # tagging the route with `defaults: { route_group: 'admin' }`. Outside a
-  # request (jobs, rake tasks) no group resolves and the resolver keeps failing
-  # closed.
+  # request (jobs, rake tasks, console) no group resolves, so the caller names
+  # the one it is acting as:
+  #
+  #   Rhino.in_route_group(:admin).query(Task)
+  #   Rhino.for_user(operator).in_route_group(:admin).run { ... }
+  #
+  # The group's own `tenant:` still decides: naming a tenant group there changes
+  # nothing, the query still fails closed.
 
   # config.route_group :default, prefix: '', middleware: [], models: :all
 

data/lib/rhino/version.rb

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

data/lib/rhino.rb

@@ -4,6 +4,8 @@ require "rhino/version"
 require "rhino/configuration"
 require "rhino/auth_rejected"
 require "rhino/scope_not_allowed_error"
+require "rhino/invalid_scope_arguments_error"
+require "rhino/scope_spec"
 require "rhino/missing_tenant_context"
 require "rhino/auth_hooks"
 require "rhino/group_membership"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rhino-rails
 version: !ruby/object:Gem::Version
-  version: 4.7.2
+  version: 4.8.0
 platform: ruby
 authors:
 - Bruno Cipolla
@@ -223,6 +223,7 @@ files:
 - lib/rhino/controllers/resources_controller.rb
 - lib/rhino/engine.rb
 - lib/rhino/group_membership.rb
+- lib/rhino/invalid_scope_arguments_error.rb
 - lib/rhino/mailers/invitation_mailer.rb
 - lib/rhino/middleware/resolve_organization_from_route.rb
 - lib/rhino/missing_tenant_context.rb
@@ -240,6 +241,7 @@ files:
 - lib/rhino/routing/domain_constraint.rb
 - lib/rhino/routing/route_group_validator.rb
 - lib/rhino/scope_not_allowed_error.rb
+- lib/rhino/scope_spec.rb
 - lib/rhino/scopes_to_organization.rb
 - lib/rhino/tasks/rhino.rake
 - lib/rhino/templates/audit_trail/create_audit_logs.rb.erb