rhino-rails 4.0.1 → 4.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 547b86334ce61b25d13d6dccaa977a5821b8bdb3b275a5fb13a8b5b62d1cd0ee
-  data.tar.gz: 35f4ffa23101a49ab7c1403abd51aa15a2f1f57ff1c437000e49e394b6d1b8c0
+  metadata.gz: 1168eadabff8797a003d07665dfb30f4c1581e78e5df400ac9d72116d323d413
+  data.tar.gz: 0ec4d0b8ce91cadecdc94af585261ecd148157eacf7e720494adeb566187010c
 SHA512:
-  metadata.gz: 68dc8254b5a402eb13ca75a7a2d3b2919aef8e1bd6f5f2ffdae273ff5bad6eb69dc34a4aa3ee5bf6c20cd66dc1cdff5b301d1989c54c2101ae4eb4b8b042caae
-  data.tar.gz: aae80fedc9b6b03cc433204487b0f03fb6bffeed9805aea056cad1f74398f707882c02e9a434f88cce16618ec83c6b5a617c11d1c00230b45c5edfbc0a8aee23
+  metadata.gz: e79bfcd2a29520962874939ec5621c5dbb6242c19681515a36aac49f0ba158a95bbf631638055a342de181248c43e2ce7f9480d77ef79900ec216682f238e3bf
+  data.tar.gz: 264a1e3201782888918077db9e46ba4bea10bb7262d14b5d4a2eaa67ff843fd5b859579dfdfca57041d5a11babfc26f57bc23806359fcf7ca931f07c70d74d41

data/lib/rhino/auth_hooks.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Rhino
+  # Base class for per-group auth lifecycle hooks. A group's optional `hooks:`
+  # class may subclass this (or simply respond to the event methods) and
+  # override any of the events; each defaults to a no-op.
+  #
+  # Each event receives the affected user and a context hash:
+  #   { user:, route_group:, organization:, token:, request: }
+  #
+  # A hook rejects an action by raising Rhino::AuthRejected (optionally with a
+  # status). For token-issuing actions (login/register) the controller revokes
+  # the just-issued token and returns the status; for the others it returns the
+  # status without side effects.
+  #
+  # See GROUP_AUTH_DESIGN.md §7.
+  class AuthHooks
+    def after_login(user, context = {}); end
+
+    def after_logout(user, context = {}); end
+
+    def after_register(user, context = {}); end
+
+    def after_password_recover(user, context = {}); end
+
+    def after_password_reset(user, context = {}); end
+  end
+end

data/lib/rhino/auth_rejected.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Rhino
+  # Raised by a lifecycle hook (or membership enforcement) to reject an auth
+  # action. Carries an HTTP status (default 403) and a message. For
+  # token-issuing actions (login/register) the controller revokes the
+  # just-issued token before returning the status.
+  #
+  # See GROUP_AUTH_DESIGN.md §7.
+  class AuthRejected < StandardError
+    attr_reader :status
+
+    def initialize(message = "Forbidden", status: 403)
+      @status = status
+      super(message)
+    end
+  end
+end

data/lib/rhino/concerns/has_permissions.rb

@@ -35,9 +35,28 @@ module Rhino
     # @param permission [String] Permission string like 'posts.index'
     # @param organization [Object, nil] Organization to check permissions for
     # @return [Boolean]
-    def has_permission?(permission, organization = nil)
+    def has_permission?(permission, organization = nil, route_group: nil)
       return false if permission.blank?
 
+      # Group-aware permission resolution (GROUP_AUTH_DESIGN.md §6). Only active
+      # when enforce_group_membership is on. Permissions then resolve from the
+      # membership row matching (route_group, organization), not the heuristic.
+      if group_membership_enforced?
+        membership = Rhino::GroupMembership.matching_membership(self, route_group, organization)
+        return false unless membership
+
+        ur_permissions = parse_permissions(membership.respond_to?(:permissions) ? membership.permissions : nil)
+        return matches_permission?(permission, ur_permissions) if ur_permissions.present?
+
+        role = membership.respond_to?(:role) ? membership.role : nil
+        if role
+          role_permissions = parse_permissions(role.respond_to?(:permissions) ? role.permissions : nil)
+          return matches_permission?(permission, role_permissions) if role_permissions.present?
+        end
+
+        return false
+      end
+
       if organization
         # Tenant route group: check permissions for this organization
         user_role = find_user_role(organization)
@@ -113,5 +132,9 @@ module Rhino
 
       user_roles.find_by(organization_id: organization.id)
     end
+
+    def group_membership_enforced?
+      Rhino.config.respond_to?(:enforce_group_membership?) && Rhino.config.enforce_group_membership?
+    end
   end
 end

data/lib/rhino/configuration.rb

@@ -4,6 +4,7 @@ module Rhino
   class Configuration
     attr_accessor :models, :route_groups, :multi_tenant, :invitations, :nested, :test_framework,
                   :client_path, :mobile_path
+    attr_reader :auth
 
     def initialize
       @models = {}
@@ -20,11 +21,26 @@ module Rhino
         max_operations: 50,
         allowed_models: nil
       }
+      @auth = {
+        enforce_group_membership: false
+      }
       @test_framework = "rspec"
       @client_path = nil
       @mobile_path = nil
     end
 
+    # Auth configuration accessor. Merges supplied keys over defaults so a host
+    # app can set just `enforce_group_membership` without losing future keys.
+    def auth=(value)
+      @auth = { enforce_group_membership: false }.merge((value || {}).symbolize_keys)
+    end
+
+    # Master flag (default off). When off, behavior is byte-for-byte today's:
+    # no group-membership enforcement.
+    def enforce_group_membership?
+      !!@auth[:enforce_group_membership]
+    end
+
     # Register a model with its slug
     # Usage: config.model :posts, 'Post'
     def model(slug, klass_name)
@@ -33,11 +49,24 @@ module Rhino
 
     # Register a route group with its configuration
     # Usage: config.route_group :tenant, prefix: ':organization', middleware: [Rhino::Middleware::ResolveOrganizationFromRoute], models: :all
-    def route_group(name, prefix: "", middleware: [], models: :all)
+    #
+    # The optional `domain:` keyword constrains the group's routes to a specific
+    # host. Two groups can then share the same `prefix:` but live on different
+    # domains. A parameterized domain such as "{organization}.example.com"
+    # captures the subdomain and feeds organization resolution exactly like the
+    # path-prefix ":organization" does. Groups without a domain (nil/blank)
+    # match any host (default, fully backward compatible).
+    def route_group(name, prefix: "", domain: nil, middleware: [], models: :all, auth: false, hooks: nil)
+      normalized_domain = domain.to_s.strip
+      normalized_domain = nil if normalized_domain.empty?
+
       @route_groups[name.to_sym] = {
         prefix: prefix.to_s,
+        domain: normalized_domain,
         middleware: Array(middleware),
-        models: models
+        models: models,
+        auth: !!auth,
+        hooks: hooks
       }
     end
 
@@ -97,5 +126,69 @@ module Rhino
     def model_in_group?(slug, group_name)
       models_for_group(group_name).include?(slug.to_sym)
     end
+
+    # ------------------------------------------------------------------
+    # Group-aware auth helpers (see GROUP_AUTH_DESIGN.md §5/§7)
+    # ------------------------------------------------------------------
+
+    # Whether a group has per-group auth routes enabled (`auth: true`).
+    # The `public` group is never auth-enabled.
+    def group_auth_enabled?(group_name)
+      return false if group_name.to_s == "public"
+
+      group = @route_groups[group_name.to_sym]
+      !!(group && group[:auth])
+    end
+
+    # Names of all groups (except :public) that opted into per-group auth.
+    def auth_enabled_groups
+      @route_groups.keys.reject { |name| name.to_s == "public" }
+                   .select { |name| group_auth_enabled?(name) }
+    end
+
+    # Names of auth-enabled groups that have an empty prefix AND no domain, i.e.
+    # groups whose auth routes would be byte-for-byte identical to the legacy
+    # unprefixed /api/auth/* set (GROUP_AUTH_DESIGN.md §11.1). Such a group IS
+    # the default/legacy auth: the legacy routes adopt its route_group/hooks
+    # instead of registering a colliding second set. Two or more is a conflict
+    # (raised by the route-group validator).
+    def auth_enabled_legacy_groups
+      auth_enabled_groups.select do |name|
+        group = @route_groups[name.to_sym]
+        prefix = group[:prefix].to_s
+        domain = group[:domain]
+        prefix.empty? && (domain.nil? || domain.to_s.strip.empty?)
+      end
+    end
+
+    # Resolve the configured lifecycle-hooks class for a group, instantiated.
+    # Returns nil when the group has no hooks configured. Accepts a class, a
+    # class name string, or an instance.
+    def hooks_for_group(group_name)
+      return nil if group_name.nil?
+
+      group = @route_groups[group_name.to_sym]
+      return nil unless group
+
+      hooks = group[:hooks]
+      return nil if hooks.nil?
+
+      case hooks
+      when String
+        klass = hooks.safe_constantize
+        klass&.new
+      when Class
+        hooks.new
+      else
+        hooks
+      end
+    end
+
+    # Whether a group is a tenant group (organization-scoped). Only the
+    # reserved `:tenant` group is treated as a tenant group, matching
+    # has_tenant_group?.
+    def group_is_tenant?(group_name)
+      group_name.to_s == "tenant"
+    end
   end
 end

data/lib/rhino/controllers/auth_controller.rb

@@ -30,6 +30,12 @@ module Rhino
         return render json: { message: "Invalid credentials" }, status: :unauthorized
       end
 
+      # Group membership is a coarse access gate (GROUP_AUTH_DESIGN.md §6).
+      # Gated entirely by the enforce_group_membership flag; off = unchanged.
+      if membership_enforced? && !group_member?(user)
+        return render json: { message: "You are not a member of this group" }, status: :forbidden
+      end
+
       token = generate_api_token(user)
 
       # Get the first organization the user belongs to
@@ -39,6 +45,10 @@ module Rhino
         organization_slug = first_org&.slug
       end
 
+      # Lifecycle hook (GROUP_AUTH_DESIGN.md §7). A reject revokes the token.
+      hook_response = run_hook(:after_login, user, token: token, revoke_on_reject: true)
+      return if hook_response
+
       render json: {
         token: token,
         organization_slug: organization_slug
@@ -55,6 +65,10 @@ module Rhino
         user.update_column(:api_token, SecureRandom.hex(32))
       end
 
+      # Token is already gone; a rejecting hook only changes the status code.
+      hook_response = run_hook(:after_logout, user, revoke_on_reject: false)
+      return if hook_response
+
       render json: { message: "Logged out successfully" }, status: :ok
     end
 
@@ -83,9 +97,18 @@ module Rhino
         # Send email via mailer if available
         mailer_class = "Rhino::PasswordRecoveryMailer".safe_constantize
         mailer_class&.recover(user, token)&.deliver_later
+
+        # Lifecycle hook fires only when a user actually exists, and its
+        # rejection is SWALLOWED here. recover_password must be an enumeration
+        # oracle-free endpoint: a rejecting hook would otherwise return a 403
+        # only for existing emails, letting a caller distinguish real accounts
+        # from fake ones. The hook still runs for its side effects (e.g.
+        # auditing, throttling), but its reject never changes the response.
+        run_hook(:after_password_recover, user, revoke_on_reject: false, swallow_reject: true)
       end
 
-      # Always return success to prevent email enumeration
+      # Always return the same response (existing OR non-existing email) to
+      # prevent email enumeration — this is the documented contract.
       render json: { message: "Password recovery email sent." }, status: :ok
     end
 
@@ -132,6 +155,9 @@ module Rhino
       user.reset_password_sent_at = nil
       user.save!
 
+      hook_response = run_hook(:after_password_reset, user, revoke_on_reject: false)
+      return if hook_response
+
       render json: { message: "Password has been reset." }, status: :ok
     end
 
@@ -184,7 +210,7 @@ module Rhino
         password: params[:password]
       )
 
-      # Accept invitation (adds user to organization)
+      # Accept invitation (adds user to organization, carrying its route_group)
       invitation.accept!(user)
 
       # Generate token
@@ -194,6 +220,15 @@ module Rhino
       organization = invitation.organization
       organization_slug = organization&.slug
 
+      # Lifecycle hook for the group the invitee joined (from the invitation).
+      invite_group = invitation.respond_to?(:route_group) ? invitation.route_group : nil
+      hook_response = run_hook(
+        :after_register, user,
+        token: token, revoke_on_reject: true,
+        group_override: invite_group, organization_override: organization
+      )
+      return if hook_response
+
       render json: {
         message: "Registration successful",
         token: token,
@@ -204,6 +239,87 @@ module Rhino
 
     private
 
+    # ------------------------------------------------------------------
+    # Group-aware auth (GROUP_AUTH_DESIGN.md §5/§6/§7)
+    # ------------------------------------------------------------------
+
+    # The route_group resolved from the matched route's defaults. nil for the
+    # legacy unprefixed auth routes with no :default group.
+    def current_route_group
+      params[:route_group].presence
+    end
+
+    # Resolve the organization for group-aware auth (tenant groups carry the
+    # :organization prefix param). Returns nil for non-tenant/legacy routes.
+    def current_organization
+      return @current_organization if defined?(@current_organization)
+
+      @current_organization = begin
+        org_identifier = params[:organization]
+        if org_identifier.present?
+          org_class = "Organization".safe_constantize
+          if org_class
+            column = Rhino.config.multi_tenant[:organization_identifier_column] || "id"
+            org_class.find_by(column => org_identifier)
+          end
+        end
+      end
+    end
+
+    def membership_enforced?
+      Rhino.config.respond_to?(:enforce_group_membership?) && Rhino.config.enforce_group_membership?
+    end
+
+    # Coarse membership gate for the resolved group (and org for tenant groups).
+    def group_member?(user)
+      Rhino::GroupMembership.member?(user, current_route_group, current_organization)
+    end
+
+    # Run the configured lifecycle hook for the current (or overridden) group.
+    # Returns true when a response was rendered (rejection), false/nil otherwise.
+    #
+    # On Rhino::AuthRejected: for token-issuing actions (revoke_on_reject) the
+    # just-issued token is revoked, then the carried status is returned.
+    #
+    # When swallow_reject is true (password/recover only), a rejection is run
+    # for its side effects but NOT surfaced: the action proceeds to its uniform
+    # response so the endpoint cannot be used as an email-enumeration oracle.
+    def run_hook(event, user, token: nil, revoke_on_reject: false, swallow_reject: false, group_override: :__none__, organization_override: :__none__)
+      group = group_override == :__none__ ? current_route_group : group_override
+      org = organization_override == :__none__ ? current_organization : organization_override
+
+      hooks = Rhino.config.respond_to?(:hooks_for_group) ? Rhino.config.hooks_for_group(group) : nil
+      return false unless hooks
+      return false unless hooks.respond_to?(event)
+
+      context = {
+        user: user,
+        route_group: group,
+        organization: org,
+        token: token,
+        request: request
+      }
+
+      hooks.public_send(event, user, context)
+      false
+    rescue Rhino::AuthRejected => e
+      return false if swallow_reject
+
+      revoke_token(user) if revoke_on_reject
+      render json: { message: e.message }, status: e.status
+      true
+    end
+
+    def revoke_token(user)
+      return unless user
+
+      if user.respond_to?(:regenerate_api_token)
+        user.regenerate_api_token
+      elsif user.respond_to?(:update_column) && user.class.column_names.include?("api_token")
+        user.update_column(:api_token, SecureRandom.hex(32))
+      end
+    end
+
     def authenticate_user!
       unless current_user
         render json: { message: "Unauthenticated." }, status: :unauthorized

data/lib/rhino/controllers/invitations_controller.rb

@@ -53,6 +53,20 @@ module Rhino
 
       email = params[:email].to_s.strip
       role_id = params[:role_id]
+      route_group = params[:route_group].presence
+
+      # The public group is never auth-enabled — it cannot be invited into.
+      if route_group.to_s == "public"
+        return render json: { message: "Cannot invite into the public group" }, status: :unprocessable_entity
+      end
+
+      # When group-membership enforcement is on, the inviter must themselves be
+      # a member of the target group (GROUP_AUTH_DESIGN.md §8).
+      if route_group.present? && membership_enforced?
+        unless Rhino::GroupMembership.member?(current_user, route_group, current_organization)
+          return render json: { message: "You are not a member of this group" }, status: :forbidden
+        end
+      end
 
       # Check if user already exists and is in organization
       user_class = "User".safe_constantize
@@ -75,13 +89,28 @@ module Rhino
         return render json: { message: "A pending invitation already exists for this email" }, status: :unprocessable_entity
       end
 
-      # Create invitation
-      invitation = OrganizationInvitation.create!(
-        organization_id: current_organization.id,
+      # Create invitation. Non-tenant groups (e.g. :admin, :driver) have no
+      # organization, so a non-tenant invite must store organization_id = nil —
+      # matching the nullable membership row that accept! will create. Only the
+      # tenant group (and the legacy no-group invite) carries the current org.
+      invitation_org_id =
+        if route_group.present? && !Rhino.config.group_is_tenant?(route_group)
+          nil
+        else
+          current_organization.id
+        end
+
+      invitation_attrs = {
+        organization_id: invitation_org_id,
         email: email,
         role_id: role_id,
         invited_by: current_user.id
-      )
+      }
+      if route_group.present? && OrganizationInvitation.column_names.include?("route_group")
+        invitation_attrs[:route_group] = route_group
+      end
+
+      invitation = OrganizationInvitation.create!(invitation_attrs)
 
       # Send notification email
       send_invitation_email(invitation)
@@ -221,6 +250,10 @@ module Rhino
       @organization
     end
 
+    def membership_enforced?
+      Rhino.config.respond_to?(:enforce_group_membership?) && Rhino.config.enforce_group_membership?
+    end
+
     def send_invitation_email(invitation)
       mailer_class = "Rhino::InvitationMailer".safe_constantize
       mailer_class&.invite(invitation)&.deliver_later

data/lib/rhino/controllers/resources_controller.rb

@@ -20,8 +20,19 @@ module Rhino
     @@organization_path_cache = {}
 
     before_action :set_model_class
+    before_action :set_route_group
+    # GROUP_AUTH_DESIGN.md §11.2: when enforce_group_membership is ON, the
+    # membership gate (403) must take precedence over the org-resolution 404, so
+    # an authenticated non-member of the requested group gets 403 rather than the
+    # info-hiding 404. We therefore authenticate and run the gate BEFORE resolving
+    # the organization when enforcement is on; the gate resolves the org itself as
+    # needed (a genuinely non-existent org still 404s inside the gate). When
+    # enforcement is OFF (default), the original order is preserved byte-for-byte:
+    # resolve_organization (404) runs first, then authenticate.
+    before_action :authenticate_user_before_org!, if: :authenticate_before_org?
+    before_action :enforce_group_membership, if: :authenticate_before_org?
     before_action :resolve_organization
-    before_action :authenticate_user!, unless: :public_route_group?
+    before_action :authenticate_user_after_org!, if: :authenticate_after_org?
 
     # GET /api/{slug}
     def index
@@ -275,10 +286,92 @@ module Rhino
       current_route_group == "public"
     end
 
+    # Whether enforce_group_membership is on (GROUP_AUTH_DESIGN.md §6/§11.2).
+    def membership_enforced?
+      Rhino.config.respond_to?(:enforce_group_membership?) &&
+        Rhino.config.enforce_group_membership?
+    end
+
+    # When enforcement is ON we authenticate + run the membership gate BEFORE
+    # resolving the org so a 403 (non-member) takes precedence over the org 404.
+    def authenticate_before_org?
+      !public_route_group? && membership_enforced?
+    end
+
+    # When enforcement is OFF (default) we keep today's order: resolve the org
+    # (its 404) first, then authenticate.
+    def authenticate_after_org?
+      !public_route_group? && !membership_enforced?
+    end
+
     def current_route_group
       params[:route_group]
     end
 
+    # Expose the resolved route_group to policies/permissions via RequestStore
+    # so group-aware permission resolution (when enforcement is on) can use it.
+    def set_route_group
+      return unless defined?(RequestStore)
+
+      RequestStore.store[:rhino_route_group] = params[:route_group].presence
+    end
+
+    # Coarse group-membership gate (GROUP_AUTH_DESIGN.md §6). Entirely gated by
+    # the enforce_group_membership flag; off = unchanged. Runs after auth, so an
+    # authenticated user without a matching membership row gets 403.
+    def enforce_group_membership
+      return unless membership_enforced?
+
+      user = current_user
+      return unless user # unauthenticated already handled by authenticate_user!
+
+      # §11.2: this gate runs BEFORE resolve_organization, so it resolves the org
+      # itself. A non-existent org identifier still 404s (info-hiding for a
+      # resource that cannot exist); an authenticated NON-MEMBER gets 403, taking
+      # precedence over the cross-org 404. resolve_organization re-runs afterward
+      # to set request.env/RequestStore for the rest of the request.
+      org = resolve_membership_organization
+      return if performed? # 404: org identifier supplied but no such org
+
+      unless Rhino::GroupMembership.member?(user, current_route_group, org)
+        render json: { message: "You are not a member of this group" }, status: :forbidden
+      end
+    end
+
+    # Resolve the organization for the membership gate from the route's
+    # :organization param. Renders 404 and returns nil when an identifier is
+    # supplied but matches no organization. Returns nil (no render) when no
+    # identifier is present (non-tenant groups).
+    def resolve_membership_organization
+      org_identifier = params[:organization]
+      return nil unless org_identifier.present?
+
+      org_class = "Organization".safe_constantize
+      return nil unless org_class
+
+      column = Rhino.config.multi_tenant[:organization_identifier_column] || "id"
+      organization = org_class.find_by(column => org_identifier)
+
+      unless organization
+        render json: { message: "Organization not found" }, status: :not_found
+        return nil
+      end
+
+      organization
+    end
+
+    # Two distinct callback names so the before_action chain registers BOTH
+    # entries (Rails de-duplicates callbacks by method name; reusing
+    # :authenticate_user! for both the pre- and post-org slots would collapse
+    # them into one with a single condition). Both delegate to authenticate_user!.
+    def authenticate_user_before_org!
+      authenticate_user!
+    end
+
+    def authenticate_user_after_org!
+      authenticate_user!
+    end
+
     def authenticate_user!
       unless current_user
         render json: { message: "Unauthenticated." }, status: :unauthorized

data/lib/rhino/engine.rb

@@ -27,8 +27,9 @@ module Rhino
       require "rhino/policies/resource_policy"
       require "rhino/policies/invitation_policy"
 
-      # Query builder and routes
+      # Query builder, routing constraints and routes
       require "rhino/query_builder"
+      require "rhino/routing/domain_constraint"
       require "rhino/routes"
 
       # Controllers