super_auth 0.8.0 → 0.9.0

data/lib/super_auth/railtie.rb

@@ -16,15 +16,6 @@ module SuperAuth
         load "tasks/super_auth_tasks.rake"
       end
 
-      # Rails 7.1+ keeps one deprecator per library and applies
-      # config.active_support.deprecation / report_deprecations to each of
-      # them in the active_support.deprecation_behavior initializer, which
-      # runs after load_environment_config — so registration has to come
-      # before that, as Rails' own railties do.
-      initializer "super_auth.deprecator", before: :load_environment_config do |app|
-        app.deprecators[:super_auth] = SuperAuth.deprecator if app.respond_to?(:deprecators)
-      end
-
       initializer "super_auth.initialize" do
         if defined?(ActiveRecord) && defined?(ActiveRecord::Base)
           SuperAuth.db

data/lib/super_auth/reach.rb

@@ -0,0 +1,88 @@
+# The reach map: which authorization rows admit a row of a protected table.
+#
+# Both layers take the same two keywords, resource_type: and parent:, and
+# both ask the same question of every row: does the current user hold a
+# compiled authorization that reaches it? A row is reached through its own
+# id (a per-record grant, or a type-level grant on the class's own type) or
+# through a column holding another record's id (a parent grant: the row's
+# tenancy, read off the row itself). The reach map is that question in one
+# shape, an ordered Hash from column to the types whose rows admit through
+# it, with :id always the first step:
+#
+#   SuperAuth::Reach.normalize(
+#     resource_type: "Claim",
+#     parent: { column: :organization_id, resource_type: %w[Organization::Member Organization::Admin] })
+#   # => { id: ["Claim"], organization_id: ["Organization::Member", "Organization::Admin"] }
+#
+# The RLS policy and the ByCurrentUser scope each emit one step per entry,
+# and both build from this map rather than from the raw keywords so they
+# cannot drift: an argument shape one layer accepted and the other rejected,
+# or a column one saw and the other did not, is a row the ORM shows and the
+# database hides, or the reverse, which is the dangerous direction. Every
+# entry is a list because RLS must never be narrower than any tier's ORM
+# scope over the same table: a table whose readers key on
+# Organization::Member and whose writers on Organization::CaseWriter names
+# both under the column, so the holder of one without the other is still
+# admitted at the database.
+#
+# :id is refused as a parent column since it is the per-record step, already
+# declared by resource_type:. A column declared twice is refused because the
+# second entry would silently shadow the first; every type a column admits
+# goes in one list.
+module SuperAuth
+  module Reach
+    class << self
+      def normalize(resource_type:, parent: nil)
+        reach = { id: types(resource_type, "resource_type:") }
+        entries(parent).each do |entry|
+          unless entry.is_a?(Hash) && (entry.keys - %i[column resource_type]).empty?
+            raise Error, "parent: must be a Hash {column:, resource_type:} or an Array of them, got #{entry.inspect}"
+          end
+          column = column_name(entry[:column])
+          if reach.key?(column)
+            raise Error, "parent: column #{column.inspect} is declared twice; list every type it admits under one entry"
+          end
+          reach[column] = types(entry[:resource_type], "parent: #{column} resource_type:")
+        end
+        reach.freeze
+      end
+
+      # The column steps alone, for the layer emitting one per parent and for
+      # recording what a policy was built from.
+      def parents(reach)
+        reach.reject { |column, _| column == :id }
+      end
+
+      private
+
+      def entries(parent)
+        case parent
+        when nil then []
+        when Hash then [parent]
+        when Array then parent
+        else raise Error, "parent: must be a Hash {column:, resource_type:} or an Array of them, got #{parent.inspect}"
+        end
+      end
+
+      def column_name(column)
+        name = column.to_s if column.is_a?(Symbol) || column.is_a?(String)
+        if name.nil? || name.empty?
+          raise Error, "parent: column: must be a Symbol or String naming a column, got #{column.inspect}"
+        end
+        if name == "id"
+          raise Error, "parent: column: :id is the per-record step, which resource_type: already declares; a parent is a column holding another record's id"
+        end
+        name.to_sym
+      end
+
+      # Frozen copies rather than freezing the caller's strings in place.
+      def types(value, label)
+        list = value.is_a?(Array) ? value : [value]
+        unless !list.empty? && list.all? { |type| type.is_a?(String) && !type.empty? }
+          raise Error, "#{label} must be a String or a non-empty Array of Strings, got #{value.inspect}"
+        end
+        list.uniq.map { |type| -type }.freeze
+      end
+    end
+  end
+end

data/lib/super_auth/resource.rb

@@ -12,21 +12,52 @@ class SuperAuth::Resource < Sequel::Model(:super_auth_resources)
     # (wildcard) node: at runtime it means every record of that type, present
     # and future (the ByCurrentUser type_level branch, the policy's
     # `resource_external_id IS NULL OR` clause). A node with neither is a
-    # container. Wildcards are deprecated (see warn_deprecated_wildcards) but
-    # still the only way to authorize INSERT under row-level security, so they
-    # stay; what they may not do is join the tree.
+    # container. The type-level grant is a supported, permanent primitive —
+    # "this principal may act on every record of a type" has no cheaper
+    # spelling — and it is flat: what it may not do is join the tree.
     def wildcards
       exclude(external_type: nil).where(external_id: nil)
     end
 
-    # "Wildcard nodes are flat." compile! calls this before touching the
+    # The node registered for one record: the pair every host helper looks
+    # up before it grants, revokes or labels. It refuses a nil id rather than
+    # answering, because where(external_type: type, external_id: nil) is not
+    # "no node" — it IS the type-level node for that type, and a helper called
+    # with an unset foreign key would otherwise act on the grant that covers
+    # every record of the type.
+    def record(type, id)
+      if id.nil?
+        raise SuperAuth::Error, "SuperAuth::Resource.record(#{type.to_s.inspect}, nil): the id is nil. " \
+          "A node with an external_type and no external_id is the type-level node for every #{type} record, " \
+          "not the node for one of them; pass the record's id, or use wildcards for the type-level node."
+      end
+
+      first(external_type: type.to_s, external_id: id)
+    end
+
+    # The recursive step of descendant_pairs stops at a type-level node. A
+    # per-record node nested under one would otherwise receive the
+    # type-level node's grants: one accidental parent_id, and a grant on
+    # "every Claim" also compiled a row for every claim node beneath it, on
+    # every path that reads the walk — including a host that reads
+    # Edge.authorizations directly and never calls compile!, where
+    # assert_compilable! does not run. The walk still anchors on the node a
+    # grant names, so a granted type-level node yields its own (type, NULL)
+    # row and nothing else; join_resource_subtree drops the other direction,
+    # a type-level node reached as a descendant.
+    def descend_from(parent)
+      Sequel.|({ Sequel[parent][:external_type] => nil }, Sequel.~(Sequel[parent][:external_id] => nil))
+    end
+
+    # "Type-level nodes are flat." compile! calls this before touching the
     # compiled table, so a refused compile leaves the previous rows in place.
-    # A wildcard with a parent would compile to a (type, NULL) row reachable
-    # through every ancestor's grants — one edge to a container silently
-    # granting every record of a type — and a wildcard with children would
-    # make the children unreachable except through a grant that already covers
-    # them; neither is a shape anyone means. One query: the wildcards that
-    # have a parent, or that some node names as its parent.
+    # The walk and the join above make the shape harmless; this makes it
+    # loud, because nobody means it. A type-level node with a parent looks
+    # like a container grant that reaches every record of a type, and one
+    # with children looks like a container whose children can only be
+    # reached through a grant that already covers them. One query: the
+    # type-level nodes that have a parent, or that some node names as its
+    # parent.
     def assert_compilable!
       parents = dataset.exclude(parent_id: nil).select(:parent_id)
       nested = wildcards.where(Sequel.|(Sequel.~(parent_id: nil), { id: parents })).select_order_map(:id)
@@ -38,22 +69,5 @@ class SuperAuth::Resource < Sequel::Model(:super_auth_resources)
         "reaches every record of its type through the tree. Move each to the root with no children, or give " \
         "it an external_id."
     end
-
-    # One warning per compile, naming what exists, through SuperAuth.deprecator
-    # so a Rails host's deprecation config (notify, raise, silence) applies.
-    # A no-op when there are none, which is the common case.
-    def warn_deprecated_wildcards
-      rows = wildcards.order(:id).select_map([:id, :name])
-      return if rows.empty?
-
-      listed = rows.first(10).map { |id, name| "#{name} (#{id})" }
-      listed << "..." if rows.size > 10
-      SuperAuth.deprecator.warn(
-        "#{rows.size} type-level (wildcard) resource node#{'s' if rows.size > 1} " \
-        "(external_type set, external_id NULL): #{listed.join(', ')}. Wildcard nodes are deprecated. " \
-        "They still work, and they remain the only way to authorize INSERT under row-level security; " \
-        "the successor is a grant on a parent record. See the CHANGELOG."
-      )
-    end
   end
 end