rhino-rails 4.3.0 → 4.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 43ae824cbc25eeacd6ce09fc6a9d5b218206d8877fc672a49b728dd6fbf10b1c
-  data.tar.gz: 6590704092005ad3b6c0b959b0166332387b2503d8db19e57fc17be7734c2d0b
+  metadata.gz: ecffad187ec69c47659219d1eb766247a82ce666a662be9a32c3d88afe4bd48c
+  data.tar.gz: 1ccb038bc991c74d4338b84a20280b38660f1ec959552b3546625de855f37969
 SHA512:
-  metadata.gz: a8007c1c7f90ceae1cb0aed88ca032009e417f0e8052897f5ed73e514d9f3c782c6304f92f9b16002179d6492f5510d7ef3a3e00f5902094a925c2dd74c3b781
-  data.tar.gz: a58f92293f66ad18700a9ec39bf48e0696f64c72b7ac82c64fde715775821a5f00c3b90ce8e61dbf76b4edf4973eb520bc04b075e04ffb16c84fe7253c350e74
+  metadata.gz: 242a0d4672911f646bd9dc62dcfa6bd0641caed3ec88af8f62dea657f146e0d019f80d9cbe769fb9e7415c611e709946c1aeb01af4eeb1871ca590ea2533b866
+  data.tar.gz: ea611e79054413e6322dd44a2a141aa01a0791a8eb48d13e4dd8311c03821c8195fb7befd598840d63401355a3fd4819f7b4506afd6486d38d5a0fedef48a5e4

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/context.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Rhino
+  # Ambient tenant context resolver.
+  #
+  # Reads the current user/organization from RequestStore by default (request-time
+  # context set by the controller before_actions), but can be overridden for the
+  # duration of a block via +with+ — used by the explicit query builder so jobs,
+  # rake tasks, and tests can query without a route.
+  module Context
+    module_function
+
+    # The active organization: the explicit override if one is in effect, else the
+    # request-time organization from RequestStore.
+    def organization
+      if store.key?(:rhino_organization)
+        store[:rhino_organization]
+      elsif defined?(RequestStore)
+        RequestStore.store[:rhino_organization]
+      end
+    end
+
+    # The active user: the explicit override if one is in effect, else the
+    # request-time user from RequestStore.
+    def user
+      if store.key?(:rhino_current_user)
+        store[:rhino_current_user]
+      elsif defined?(RequestStore)
+        RequestStore.store[:rhino_current_user]
+      end
+    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:)
+      return yield unless defined?(RequestStore)
+
+      had_user = RequestStore.store.key?(:rhino_current_user)
+      had_org  = RequestStore.store.key?(:rhino_organization)
+      prev_user = RequestStore.store[:rhino_current_user]
+      prev_org  = RequestStore.store[:rhino_organization]
+
+      # 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)
+      had_override_org  = store.key?(:rhino_organization)
+      prev_override_user = store[:rhino_current_user]
+      prev_override_org  = store[:rhino_organization]
+
+      RequestStore.store[:rhino_current_user] = user
+      RequestStore.store[:rhino_organization] = organization
+      store[:rhino_current_user] = user
+      store[:rhino_organization] = organization
+
+      begin
+        yield
+      ensure
+        if had_user
+          RequestStore.store[:rhino_current_user] = prev_user
+        else
+          RequestStore.store.delete(:rhino_current_user)
+        end
+        if had_org
+          RequestStore.store[:rhino_organization] = prev_org
+        else
+          RequestStore.store.delete(:rhino_organization)
+        end
+
+        if had_override_user
+          store[:rhino_current_user] = prev_override_user
+        else
+          store.delete(:rhino_current_user)
+        end
+        if had_override_org
+          store[:rhino_organization] = prev_override_org
+        else
+          store.delete(:rhino_organization)
+        end
+      end
+    end
+
+    # Fiber-local override store for the active explicit context.
+    def store
+      Thread.current[:rhino_context_override] ||= {}
+    end
+  end
+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
 
@@ -442,61 +446,10 @@ module Rhino
       org = current_organization
       return unless org
 
-      # When the resource IS the Organization model
-      if org.class == model_class
-        builder.instance_variable_set(
-          :@scope,
-          builder.scope.where(model_class.primary_key => org.send(model_class.primary_key))
-        )
-        return
-      end
-
-      # Check for scopeForOrganization
-      if model_class.respond_to?(:for_organization)
-        builder.instance_variable_set(:@scope, model_class.for_organization(org))
-        return
-      end
-
-      # Check for organization_id column
-      if model_class.column_names.include?("organization_id")
-        builder.instance_variable_set(
-          :@scope,
-          builder.scope.where(organization_id: org.id)
-        )
-        return
-      end
-
-      # Auto-detect from belongs_to relationships
-      detected_path = discover_organization_path(model_class)
-      if detected_path.present?
-        apply_organization_scope_through_relationship(builder, org, detected_path)
-      end
-    end
-
-    def apply_organization_scope_through_relationship(builder, organization, relationship_path)
-      if relationship_path.include?(".")
-        # Nested path: 'post.blog' -> joins(post: :blog).where(blogs: { organization_id: org.id })
-        parts = relationship_path.split(".")
-        join_chain = parts.reverse.inject(:organization) { |inner, outer| { outer.to_sym => inner } }
-
-        builder.instance_variable_set(
-          :@scope,
-          builder.scope.joins(join_chain.is_a?(Symbol) ? join_chain : parts.first.to_sym => join_chain)
-                       .where(organizations: { id: organization.id })
-        )
-      else
-        # Single relationship
-        assoc = model_class.reflect_on_association(relationship_path.to_sym)
-        return unless assoc
-
-        if assoc.klass.column_names.include?("organization_id")
-          builder.instance_variable_set(
-            :@scope,
-            builder.scope.joins(relationship_path.to_sym)
-                         .where(assoc.klass.table_name => { organization_id: organization.id })
-          )
-        end
-      end
+      builder.instance_variable_set(
+        :@scope,
+        Rhino::ScopesToOrganization.scope_to_organization(builder.scope, model_class, org)
+      )
     end
 
     def add_organization_to_data(data)
@@ -511,9 +464,10 @@ module Rhino
     # Recursively discover the relationship path from a model to Organization
     # by introspecting BelongsTo associations. Returns dot-notation path or nil.
     #
-    # Results are cached per model class to avoid repeated reflection.
+    # The recursion itself lives in Rhino::ScopesToOrganization (the extracted,
+    # pure implementation) so the controller and the custom-query resolver share
+    # one code path. The controller keeps its own per-class cache for back-compat.
     def discover_organization_path(klass, visited = [], max_depth = 3)
-      # Return cached result (including nil)
       if @@organization_path_cache.key?(klass.name)
         return @@organization_path_cache[klass.name]
       end
@@ -524,65 +478,7 @@ module Rhino
     end
 
     def _discover_organization_path_recursive(klass, visited, max_depth)
-      return nil if max_depth <= 0 || visited.include?(klass.name)
-
-      visited = visited + [klass.name]
-
-      begin
-        associations = klass.reflect_on_all_associations(:belongs_to)
-      rescue StandardError
-        return nil
-      end
-
-      matching_paths = []
-
-      associations.each do |assoc|
-        begin
-          related_class = assoc.klass
-        rescue StandardError
-          next
-        end
-
-        # Direct match: related model IS Organization
-        if related_class.name == "Organization"
-          matching_paths << assoc.name.to_s
-          next
-        end
-
-        # Related model has organization_id column
-        begin
-          if related_class.column_names.include?("organization_id")
-            matching_paths << assoc.name.to_s
-            next
-          end
-        rescue StandardError
-          # Table may not exist yet
-        end
-
-        # Related model includes BelongsToOrganization concern
-        if related_class.include?(Rhino::BelongsToOrganization)
-          matching_paths << assoc.name.to_s
-          next
-        end
-
-        # Recurse into related model's BelongsTo associations
-        sub_path = _discover_organization_path_recursive(related_class, visited, max_depth - 1)
-        if sub_path.present?
-          matching_paths << "#{assoc.name}.#{sub_path}"
-        end
-      end
-
-      return nil if matching_paths.empty?
-
-      if matching_paths.length > 1
-        Rails.logger&.debug(
-          "Rhino: Model #{klass.name} has multiple BelongsTo paths to Organization. " \
-          "Using '#{matching_paths[0]}'. " \
-          "Paths found: #{matching_paths.inspect}"
-        )
-      end
-
-      matching_paths[0]
+      Rhino::ScopesToOrganization._discover_organization_path_recursive(klass, visited, max_depth)
     end
 
     # ------------------------------------------------------------------
@@ -900,7 +796,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/missing_tenant_context.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Rhino
+  # Raised by Rhino.query (and the explicit builder) when an organization-scopable
+  # model is queried with no organization context available. Fail-closed: the
+  # resolver never returns an unscoped relation for a tenant-scopable model.
+  class MissingTenantContext < StandardError; 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.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module Rhino
+  # Reusable tenant-safe query resolver for custom controllers (dashboards,
+  # reports, anything beyond CRUD). Mirrors the Laravel Rhino::query feature.
+  #
+  # Two ways to use it:
+  #
+  #   # Direct / ambient — org + user from the request context (RequestStore)
+  #   Rhino.query(Task)
+  #
+  #   # Explicit — works in jobs/rake/tests with NO route; org scope comes from
+  #   # the passed org, not the request:
+  #   Rhino.for_user(user).in_organization(org).query(Task)
+  #   Rhino.for_user(user).in_organization(org).run { ... }
+  class << self
+    # Build a tenant-scoped relation for +model_class+ using the ambient context.
+    #
+    # Applies the same org scoping as CRUD plus the model's default_scopes
+    # (BelongsToOrganization / HasAutoScope read RequestStore at BUILD time).
+    #
+    # Fail closed: an org-scopable model with no org context RAISES
+    # Rhino::MissingTenantContext rather than returning an unscoped relation.
+    def query(model_class)
+      org = Rhino::Context.organization
+
+      # default_scope (org via RequestStore) + auto-scope are baked here at build.
+      relation = model_class.all
+
+      if Rhino::ScopesToOrganization.organization_scoped?(model_class)
+        raise Rhino::MissingTenantContext, model_class.name unless org
+
+        relation = Rhino::ScopesToOrganization.scope_to_organization(relation, model_class, org, strict: true)
+      end
+
+      relation
+    end
+
+    # 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)
+    end
+
+    # Begin the fluent explicit builder for +user+.
+    def for_user(user)
+      Rhino::PendingScopedContext.new(user: user)
+    end
+
+    # The ambient context resolver.
+    def context
+      Rhino::Context
+    end
+
+    # Apply a whitelisted named scope to +relation+ for +model_class+.
+    # 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)
+      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) || {}
+      entry = allowed[name]
+      entry ||= name.to_sym 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
+
+      case entry
+      when Symbol
+        relation.merge(model_class.public_send(entry))
+      when Proc
+        entry.call(relation, user)
+      else
+        entry.new.apply(relation)
+      end
+    end
+  end
+
+  # 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)
+      @user = user
+      @organization = organization
+    end
+
+    def in_organization(organization)
+      @organization = organization
+      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
+    # RequestStore, build the relation via Rhino.query, then restore RequestStore.
+    # 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.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)
+      end
+    end
+
+    # Run +block+ with the explicit context installed into RequestStore. Queries
+    # 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)
+    end
+  end
+end

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/scopes_to_organization.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+module Rhino
+  # Pure organization-scoping logic, extracted from ResourcesController so it can
+  # be reused by the custom-query resolver (Rhino.query / Rhino.for_user...).
+  #
+  # Every method takes a RELATION and RETURNS a scoped relation — it never mutates
+  # a QueryBuilder's @scope. The scoping order MUST match the controller exactly:
+  #   1. Organization-is-self (the model IS the Organization)
+  #   2. for_organization (scopeForOrganization)
+  #   3. organization_id column
+  #   4. auto-detected belongs_to relationship path (incl. nested, e.g. post.blog)
+  module ScopesToOrganization
+    # Cache for auto-detected organization paths (survives across calls, keyed by
+    # model class name). Mirrors the controller's @@organization_path_cache.
+    @organization_path_cache = {}
+
+    module_function
+
+    # Apply organization scoping to +relation+ for +model_class+, returning the
+    # scoped relation. Behavior-equivalent to the controller's
+    # apply_organization_scope, but returning instead of mutating a builder.
+    def scope_to_organization(relation, model_class, organization, strict: false)
+      return relation unless organization
+
+      # When the resource IS the Organization model
+      if organization.class == model_class
+        return relation.where(
+          model_class.primary_key => organization.send(model_class.primary_key)
+        )
+      end
+
+      # Check for scopeForOrganization
+      if model_class.respond_to?(:for_organization)
+        return model_class.for_organization(organization)
+      end
+
+      # Check for organization_id column
+      if model_class.column_names.include?("organization_id")
+        return relation.where(organization_id: organization.id)
+      end
+
+      # Auto-detect from belongs_to relationships
+      detected_path = discover_organization_path(model_class)
+      if detected_path.present?
+        return scope_through_relationship(relation, model_class, organization, detected_path, strict: strict)
+      end
+
+      # No mechanism could be applied. In strict mode (the resolver) a model that
+      # reached here after being classified organization_scoped? must NOT return
+      # unscoped — fail closed instead of leaking across tenants.
+      raise Rhino::MissingTenantContext, model_class.name if strict && organization_scoped?(model_class)
+
+      relation
+    end
+
+    # Whether +model_class+ has any organization-scoping mechanism at all. Used by
+    # the resolver to decide whether missing org context must fail closed. On an
+    # unexpected classification error we fail CLOSED (treat as scopable) so the
+    # resolver raises rather than silently returning unscoped rows.
+    def organization_scoped?(model_class)
+      return true if model_class.respond_to?(:for_organization)
+      return true if model_class.column_names.include?("organization_id")
+
+      discover_organization_path(model_class).present?
+    rescue StandardError
+      true
+    end
+
+    def scope_through_relationship(relation, model_class, organization, relationship_path, strict: false)
+      if relationship_path.include?(".")
+        # Nested path: 'post.blog' -> joins(post: :blog).where(organizations: { id: org.id })
+        parts = relationship_path.split(".")
+        join_chain = parts.reverse.inject(:organization) { |inner, outer| { outer.to_sym => inner } }
+
+        relation.joins(join_chain.is_a?(Symbol) ? join_chain : parts.first.to_sym => join_chain)
+                .where(organizations: { id: organization.id })
+      else
+        # Single relationship
+        assoc = model_class.reflect_on_association(relationship_path.to_sym)
+        if assoc.nil?
+          # Classified scopable but the association vanished — fail closed for the
+          # resolver; stay lenient for the controller's legacy path.
+          raise Rhino::MissingTenantContext, model_class.name if strict
+
+          return relation
+        end
+
+        if assoc.klass.column_names.include?("organization_id")
+          relation.joins(relationship_path.to_sym)
+                  .where(assoc.klass.table_name => { organization_id: organization.id })
+        elsif strict
+          # Path leads somewhere without an organization_id column, so no filter
+          # can be applied — fail closed rather than return every tenant's rows.
+          raise Rhino::MissingTenantContext, model_class.name
+        else
+          relation
+        end
+      end
+    end
+
+    # Recursively discover the relationship path from a model to Organization by
+    # introspecting BelongsTo associations. Returns dot-notation path or nil.
+    # Results are cached per model class to avoid repeated reflection.
+    def discover_organization_path(klass, visited = [], max_depth = 3)
+      if @organization_path_cache.key?(klass.name)
+        return @organization_path_cache[klass.name]
+      end
+
+      result = _discover_organization_path_recursive(klass, visited, max_depth)
+      # Only cache a positive result. Caching a transient nil (associations/tables
+      # not yet resolvable under Zeitwerk lazy-loading) would permanently
+      # misclassify a genuinely org-scoped model as global — a fail-open leak.
+      # Mirrors HasAutoScope's non-nil caching.
+      @organization_path_cache[klass.name] = result if result
+      result
+    end
+
+    def _discover_organization_path_recursive(klass, visited, max_depth)
+      return nil if max_depth <= 0 || visited.include?(klass.name)
+
+      visited = visited + [klass.name]
+
+      begin
+        associations = klass.reflect_on_all_associations(:belongs_to)
+      rescue StandardError
+        return nil
+      end
+
+      matching_paths = []
+
+      associations.each do |assoc|
+        begin
+          related_class = assoc.klass
+        rescue StandardError
+          next
+        end
+
+        # Direct match: related model IS Organization
+        if related_class.name == "Organization"
+          matching_paths << assoc.name.to_s
+          next
+        end
+
+        # Related model has organization_id column
+        begin
+          if related_class.column_names.include?("organization_id")
+            matching_paths << assoc.name.to_s
+            next
+          end
+        rescue StandardError
+          # Table may not exist yet
+        end
+
+        # Related model includes BelongsToOrganization concern
+        if defined?(Rhino::BelongsToOrganization) && related_class.include?(Rhino::BelongsToOrganization)
+          matching_paths << assoc.name.to_s
+          next
+        end
+
+        # Recurse into related model's BelongsTo associations
+        sub_path = _discover_organization_path_recursive(related_class, visited, max_depth - 1)
+        if sub_path.present?
+          matching_paths << "#{assoc.name}.#{sub_path}"
+        end
+      end
+
+      return nil if matching_paths.empty?
+
+      if matching_paths.length > 1
+        Rails.logger&.debug(
+          "Rhino: Model #{klass.name} has multiple BelongsTo paths to Organization. " \
+          "Using '#{matching_paths[0]}'. " \
+          "Paths found: #{matching_paths.inspect}"
+        )
+      end
+
+      matching_paths[0]
+    end
+  end
+end

data/lib/rhino/version.rb

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

data/lib/rhino.rb

@@ -3,9 +3,14 @@
 require "rhino/version"
 require "rhino/configuration"
 require "rhino/auth_rejected"
+require "rhino/scope_not_allowed_error"
+require "rhino/missing_tenant_context"
 require "rhino/auth_hooks"
 require "rhino/group_membership"
 require "rhino/resource_scope"
+require "rhino/scopes_to_organization"
+require "rhino/context"
+require "rhino/query"
 require "rhino/routing/domain_constraint"
 require "rhino/routing/route_group_validator"
 require "rhino/middleware/resolve_organization_from_route"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rhino-rails
 version: !ruby/object:Gem::Version
-  version: 4.3.0
+  version: 4.5.0
 platform: ruby
 authors:
 - Bruno Cipolla
@@ -216,6 +216,7 @@ files:
 - lib/rhino/concerns/has_validation.rb
 - lib/rhino/concerns/hidable_columns.rb
 - lib/rhino/configuration.rb
+- lib/rhino/context.rb
 - lib/rhino/controllers/auth_controller.rb
 - lib/rhino/controllers/invitations_controller.rb
 - lib/rhino/controllers/resources_controller.rb
@@ -223,18 +224,22 @@ files:
 - lib/rhino/group_membership.rb
 - lib/rhino/mailers/invitation_mailer.rb
 - lib/rhino/middleware/resolve_organization_from_route.rb
+- lib/rhino/missing_tenant_context.rb
 - lib/rhino/models/audit_log.rb
 - lib/rhino/models/organization_invitation.rb
 - lib/rhino/models/rhino_model.rb
 - lib/rhino/permissions_migrator.rb
 - lib/rhino/policies/invitation_policy.rb
 - lib/rhino/policies/resource_policy.rb
+- lib/rhino/query.rb
 - lib/rhino/query_builder.rb
 - lib/rhino/railtie.rb
 - lib/rhino/resource_scope.rb
 - 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/scopes_to_organization.rb
 - lib/rhino/tasks/rhino.rake
 - lib/rhino/templates/audit_trail/create_audit_logs.rb.erb
 - lib/rhino/templates/generate/factory.rb.erb