super_auth 0.8.0 → 0.9.0

data/lib/super_auth/tree_guard.rb

@@ -0,0 +1,115 @@
+module SuperAuth
+  # The database-side cycle guard on super_auth_resources.parent_id: a
+  # Postgres trigger refusing a node as its own parent, or a parent inside
+  # the node's own subtree. A parent_id cycle is a security defect once
+  # resources carry tenancy — every node in a cycle is an ancestor of every
+  # other, so a grant on any of them reaches all their subtrees, and the
+  # walks terminate on a cycle (UNION), so nothing fails loudly. The models
+  # refuse the shape and compile! refuses to run on it; the trigger is the
+  # line for writes that go around both: a raw UPDATE, a data migration,
+  # another language.
+  #
+  # Migration 13 installs it, and this module exists because a migration is
+  # not enough to deliver a trigger to where hosts test: Rails' default
+  # schema_format is :ruby, db/schema.rb cannot carry a function or a
+  # trigger, and db:test:prepare loads schema.rb — so on such a host the
+  # guard is present in development and production and absent from the test
+  # database, where a test asserting "cycles cannot happen" passes for the
+  # wrong reason. Call `install` from the test setup, beside
+  # SuperAuth::RLS.enable, which schema.rb loses for the same reason.
+  #
+  # Postgres only. SQLite and MySQL each have triggers in a dialect of their
+  # own; the model and compile guards hold there, and a second and third
+  # implementation is not worth carrying. On those, every method is a no-op
+  # that answers false.
+  module TreeGuard
+    NAME = "super_auth_resources_tree_guard".freeze
+
+    FUNCTION_SQL = <<~SQL.freeze
+      CREATE OR REPLACE FUNCTION #{NAME}() RETURNS trigger LANGUAGE plpgsql AS $$
+      BEGIN
+        IF NEW.parent_id = NEW.id THEN
+          RAISE EXCEPTION 'super_auth_resources: node % cannot be its own parent', NEW.id
+            USING ERRCODE = 'check_violation';
+        END IF;
+        IF EXISTS (
+          WITH RECURSIVE ancestors(id, parent_id) AS (
+            SELECT r.id, r.parent_id FROM super_auth_resources r WHERE r.id = NEW.parent_id
+            UNION
+            SELECT r.id, r.parent_id FROM super_auth_resources r JOIN ancestors a ON r.id = a.parent_id
+          )
+          SELECT 1 FROM ancestors WHERE ancestors.id = NEW.id OR ancestors.parent_id = NEW.id
+        ) THEN
+          RAISE EXCEPTION 'super_auth_resources: parent_id % is inside the subtree of node %, which would close a cycle', NEW.parent_id, NEW.id
+            USING ERRCODE = 'check_violation';
+        END IF;
+        RETURN NEW;
+      END
+      $$;
+    SQL
+
+    # The walk goes UP from the new parent with UNION, so a cycle already in
+    # the table that does not include the row terminates instead of looping.
+    # It refuses an ancestor that IS the row and an ancestor whose parent_id
+    # NAMES the row, because migration 11 makes the parent_id key DEFERRABLE
+    # on Postgres: inside one transaction a row may point at a parent that
+    # does not exist yet, and on the id alone the walk stops on that dangling
+    # pointer and admits the write that closes the cycle when the parent
+    # arrives. A pointer at the row is a cycle whether or not its target
+    # exists yet, which is what the second test asks; an out-of-order insert
+    # with no cycle still passes.
+    # WHEN keeps the trigger off every root write, which is most of them.
+    TRIGGER_SQL = <<~SQL.freeze
+      CREATE TRIGGER #{NAME}
+        BEFORE INSERT OR UPDATE OF parent_id ON super_auth_resources
+        FOR EACH ROW WHEN (NEW.parent_id IS NOT NULL)
+        EXECUTE FUNCTION #{NAME}()
+    SQL
+
+    class << self
+      # Installs, or reinstalls, the function and the trigger. Idempotent;
+      # true when installed, false where the database has no such thing.
+      def install(db: SuperAuth.db)
+        return false unless postgres?(db)
+
+        db.run FUNCTION_SQL
+        db.run "DROP TRIGGER IF EXISTS #{NAME} ON super_auth_resources"
+        db.run TRIGGER_SQL
+        true
+      end
+
+      def remove(db: SuperAuth.db)
+        return false unless postgres?(db)
+
+        db.run "DROP TRIGGER IF EXISTS #{NAME} ON super_auth_resources"
+        db.run "DROP FUNCTION IF EXISTS #{NAME}()"
+        true
+      end
+
+      # Whether the trigger is on the table now — the question a test helper
+      # or a health check asks of a database that may have been built from
+      # schema.rb. The table is resolved through search_path, the way the
+      # CREATE TRIGGER above resolves it: matching pg_class.relname instead
+      # would answer for a super_auth_resources in any schema, so a leftover
+      # copy in another one that still carries the trigger would report the
+      # live table guarded when it is not. to_regclass rather than a
+      # ::regclass cast, as everywhere else in the gem, because this is asked
+      # of a database that may not have the table yet and a cast raises where
+      # the question has an answer: no table, no trigger.
+      def installed?(db: SuperAuth.db)
+        return false unless postgres?(db)
+
+        db.fetch(
+          "SELECT 1 FROM pg_trigger t WHERE t.tgrelid = to_regclass('super_auth_resources') " \
+          "AND t.tgname = ? AND NOT t.tgisinternal", NAME
+        ).any?
+      end
+
+      private
+
+      def postgres?(db)
+        db.database_type == :postgres
+      end
+    end
+  end
+end

data/lib/super_auth/version.rb

@@ -1,3 +1,3 @@
 module SuperAuth
-  VERSION = "0.8.0"
+  VERSION = "0.9.0"
 end

data/lib/super_auth.rb

@@ -1,44 +1,15 @@
 require_relative "super_auth/version"
+require_relative "super_auth/reach"
+require_relative "super_auth/tree_guard"
 require "sequel"
 
 module SuperAuth
   class Error < StandardError; end
 
-  # Stand-in for ActiveSupport::Deprecation when ActiveSupport is not loaded:
-  # the same two methods the gem calls. Plain Kernel.warn rather than
-  # `category: :deprecated`, which Ruby hides unless -W:deprecated is set,
-  # and a warning nobody sees is not a deprecation.
-  class Deprecator
-    attr_accessor :silenced
-
-    def warn(message)
-      return if silenced
-      Kernel.warn "DEPRECATION WARNING: #{message}"
-    end
-  end
-
   def self.setup
     yield self if block_given?
   end
 
-  # Where the gem's deprecation warnings go. An ActiveSupport::Deprecation
-  # when ActiveSupport is loaded, so a Rails host's
-  # config.active_support.deprecation applies once the railtie registers it
-  # under app.deprecators; otherwise the stand-in above. Both answer
-  # `silenced = true`. Memoized, so that setting survives.
-  def self.deprecator
-    @deprecator ||=
-      if defined?(ActiveSupport::Deprecation)
-        ActiveSupport::Deprecation.new("1.0", "SuperAuth")
-      else
-        Deprecator.new
-      end
-  end
-
-  def self.deprecator=(deprecator)
-    @deprecator = deprecator
-  end
-
   # Controls behavior when SuperAuth.current_user is blank in ByCurrentUser scope.
   # :none (default) — returns an empty result set silently
   # :raise — raises SuperAuth::Error
@@ -114,7 +85,13 @@ module SuperAuth
 
   # Both ORMs cache column types per model class; after (re)installing the
   # migrations those caches can describe a previous schema (e.g. a different
-  # external_id_type) and silently miscast assigned values.
+  # external_id_type) and silently miscast assigned values. The Sequel models
+  # are also rebound to SuperAuth.db: a host requires them before it has
+  # connected anything, so Sequel binds them to whatever Sequel::Model.db is
+  # at that moment (a mock, in a Rails boot), and a class left on that
+  # binding answers `db.database_type` wrong and runs its queries nowhere.
+  # Rebinding here, and from SuperAuth.db=, keeps Model.db equal to
+  # SuperAuth.db for every model, so no host needs to do it by hand.
   def self.refresh_model_schemas
     models = %w[User Group Permission Role Resource Edge Authorization]
     if defined?(SuperAuth::ActiveRecord::User)
@@ -125,7 +102,20 @@ module SuperAuth
     if defined?(SuperAuth::User) && SuperAuth::User.respond_to?(:set_dataset)
       models.each do |name|
         model = SuperAuth.const_get(name)
-        model.set_dataset(model.dataset)
+        if @db.nil? || model.db.equal?(@db)
+          model.set_dataset(model.dataset)
+        else
+          # A dataset on the target database is the one way to move a model
+          # that already has one: Sequel refuses Model.db= after that point.
+          # A host may set SuperAuth.db before its migrations have run, so a
+          # missing table moves the binding and leaves the columns to the
+          # next refresh, which install_migrations makes.
+          begin
+            model.set_dataset(@db[model.table_name])
+          rescue Sequel::DatabaseError
+            nil
+          end
+        end
       end
     end
   end
@@ -154,6 +144,20 @@ module SuperAuth
   # the connection that holds the transaction.
   def self.as(user, db: SuperAuth.db, **options)
     previous = current_user
+    unless rls?(db)
+      # No policy on this database reads the identity, so there is nothing to
+      # assert and no reason to open a transaction for it — the ORM scope
+      # reads current_user and nothing else. This is the shape of a host that
+      # has not turned RLS on, and of every host on SQLite or MySQL, where
+      # RLS.as raises. Turning RLS on later needs no application change: the
+      # same call starts asserting both layers. `options` is dropped rather
+      # than passed on: every one of them is a Sequel transaction option
+      # (auto_savepoint:, isolation:, ...) and there is no transaction here to
+      # give them to. Anything that ever means something outside one has to be
+      # handled before this return, not added to the splat.
+      self.current_user = user
+      return yield
+    end
     SuperAuth::RLS.as(user, db: db, **options) do
       self.current_user = user
       yield
@@ -162,6 +166,21 @@ module SuperAuth
     self.current_user = previous
   end
 
+  # Whether `db` carries the RLS functions — the question `as` asks on every
+  # block, so the answer is memoised for SuperAuth.db: it is a catalogue
+  # round trip, and only a migration changes it. RLS.enable, which is what
+  # creates them, clears it; so does SuperAuth.db=. Call `rls!` after
+  # installing them some other way in a live process.
+  def self.rls?(db = SuperAuth.db)
+    return SuperAuth::RLS.installed?(db: db) unless db.equal?(@db)
+    @rls = SuperAuth::RLS.installed?(db: db) if @rls.nil?
+    @rls
+  end
+
+  def self.rls!
+    @rls = nil
+  end
+
   # Both user models are internal: their id is the user_id that the policies
   # and ByCurrentUser match on. Anything else is an application object,
   # matched by id and class name.
@@ -238,8 +257,11 @@ module SuperAuth
     end
   end
 
+  # Models already loaded follow the new database; see refresh_model_schemas.
   def self.db=(db)
     @db = db
+    @rls = nil
+    refresh_model_schemas if defined?(SuperAuth::User) && SuperAuth::User.respond_to?(:set_dataset)
   end
 end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: super_auth
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.9.0
 platform: ruby
 authors:
 - Jonathan Frias
@@ -57,6 +57,8 @@ files:
 - config/routes.rb
 - db/migrate/10_add_super_auth_label_to_resources.rb
 - db/migrate/11_add_parent_id_to_resources.rb
+- db/migrate/12_add_resource_indexes.rb
+- db/migrate/13_add_resource_tree_guard.rb
 - db/migrate/1_users.rb
 - db/migrate/2_groups.rb
 - db/migrate/3_permissions.rb
@@ -76,6 +78,8 @@ files:
 - db/migrate_activerecord/20250101000009_add_by_current_user_index_to_super_auth_authorizations.rb
 - db/migrate_activerecord/20250101000010_add_super_auth_label_to_super_auth_resources.rb
 - db/migrate_activerecord/20250101000011_add_parent_id_to_super_auth_resources.rb
+- db/migrate_activerecord/20250101000012_add_super_auth_resource_indexes.rb
+- db/migrate_activerecord/20250101000013_add_resource_tree_guard_to_super_auth_resources.rb
 - db/seeds/sample_data.rb
 - exe/super_auth-editor
 - lib/basic_loader.rb
@@ -90,6 +94,7 @@ files:
 - lib/super_auth/active_record/by_current_user.rb
 - lib/super_auth/active_record/edge.rb
 - lib/super_auth/active_record/group.rb
+- lib/super_auth/active_record/nested.rb
 - lib/super_auth/active_record/permission.rb
 - lib/super_auth/active_record/resource.rb
 - lib/super_auth/active_record/role.rb
@@ -104,9 +109,11 @@ files:
 - lib/super_auth/nestable.rb
 - lib/super_auth/permission.rb
 - lib/super_auth/railtie.rb
+- lib/super_auth/reach.rb
 - lib/super_auth/resource.rb
 - lib/super_auth/rls.rb
 - lib/super_auth/role.rb
+- lib/super_auth/tree_guard.rb
 - lib/super_auth/user.rb
 - lib/super_auth/version.rb
 - lib/tasks/super_auth_tasks.rake